diff --git a/.claude/handoffs/cross-language-impact-coverage-2026-06-04.md b/.claude/handoffs/cross-language-impact-coverage-2026-06-04.md
new file mode 100644
index 000000000..ba0f2ec3b
--- /dev/null
+++ b/.claude/handoffs/cross-language-impact-coverage-2026-06-04.md
@@ -0,0 +1,316 @@
+---
+name: cross-language-impact-coverage-2026-06-04
+date: 2026-06-05 14:57
+project: codegraph
+branch: feat/cross-language-impact-coverage
+summary: Per-language coverage DONE (all 15 README langs + static-member pass + RN/Expo 95%+). Since then the live front is ROUTE FRAMEWORKS: import/aggregator style at ceiling (Express/FastAPI/Flask/requests/NestJS/Gin/Axum 95%+, Vapor/vapor-til 100%, SvelteKit 100% fair [component core + loader→page synthesizer], React Router 100% [config-based, no miss], Nuxt 93.5% fair [+ nested-component fix]; Axum 100% via a Rust self-relative submodule-call fix), convention/reflection + actor style at an honest sub-95% ceiling (ASP.NET 83.9%, Spring 83.3%, Drupal 78.9%, Django 74.1%, actix 65.4% [actor message dispatch] — all measured). **SWEEP COMPLETE — every README framework measured;** Rocket lifted 62.5%→**93.8%** via a new `routes![]`/`catchers![]` macro extractor (only the crate-root lib.rs remains). Six engine improvements en route (3 Rust: self-relative + multi-segment `a::b::c()` module calls + Rocket route-macro extraction; 1 Swift: Fluent `@Siblings(through: Pivot.self)` metatype refs; 1 SvelteKit: `+page.server.js` `load`→`+page.svelte` synthesizer; 1 Nuxt: nested auto-imported `<MediaCard>`→`media/Card.vue` resolution). The static-member-pass-for-TS/JS/Python lever was **measured & rejected** (e7b86df — 0 coverage gain, the import edge already covers it, + graph noise). **Then the 4 niche README languages were knocked out**: Lua 31.6%→**84.2%** + Luau 12.5%→**92.2%** (new require resolver, 4155609); Liquid 39.1%→**73.8%** (Shopify OS 2.0 JSON-template section parsing, 2f57119); Pascal 73%→**75.7%** (.dfm/.fmx form↔code-behind pairing, 2f30a3b) — so **ALL 22 README "Full support" languages + all 14 README frameworks now have coverage validation (full README parity).** Branch 41 commits ahead of main, 3 behind, not merged.
+---
+
+# Handoff: Cross-language impact/blast-radius coverage campaign
+
+## Resume here — read this first
+**Current state:** Branch `feat/cross-language-impact-coverage` — now **41 commits ahead of `main`, 3 behind** (behind = 3 README-waitlist doc commits on main), tip `2f30a3b`, all pushed to `origin`=colbymchenry/codegraph. NOT merged (review branch). **FULL README PARITY: all 22 "Full support" languages + all 14 frameworks now have coverage validation.** Two arcs are done: (1) **per-language** cross-file coverage for ALL 15 README "Full support" langs + the static-member pass; (2) **cross-language RN/Expo** at 95%+ FAIR (gate hole fixed 082353e; same-dir include + KMP import 529d822). **Since the 2026-06-04 save a 12-commit ROUTE-FRAMEWORK front landed** (`61a993a`→`a3f59fb`) — see the "Route-framework headroom map" below; that map is the live edge. Working tree: clean except one unrelated untracked file (`assets/generate-waitlist.py`, README-waitlist tooling, not this campaign). Full suite green (**1187 passed | 2 skipped**, 59 files).
+**Immediate next step:** **THE README SWEEP IS COMPLETE — all 22 "Full support" languages + all 14 frameworks have coverage validation.** Per-language DONE, RN/Expo DONE, route-framework + component-node front DONE, the 4 niche langs (Lua/Luau/Liquid/Pascal) DONE; **10 engine improvements** shipped this run (3 Rust + 1 Swift + 1 SvelteKit + 1 Nuxt + 1 Lua/Luau require resolver + 1 Liquid Shopify-JSON + 1 Delphi form pairing; the static-member-for-TS/JS/Python lever was measured & rejected). **Recommended: (A) ship it** — open the PR to `main` for the 41 commits; everything actionable is done. Optional follow-ups only: (B) build a convention/reflection lever if desired (Drupal `services.yml` DI, ASP.NET/Spring markup/reflection modeling) — each a large per-framework feature. **The convention/reflection frameworks (ASP.NET 83.9%, Spring 83.3%, Drupal 78.9%, Django 74.1%, actix 65.4%) sit at a genuine sub-95% static-analysis ceiling — don't chase 95% there without large reflection/markup modeling (metric-gaming otherwise). The TS/JS/Python static-member pass is measured-&-rejected (e7b86df), don't re-try.**
+
+> Suggested next message: "Open the PR to main for the cross-language-impact-coverage branch (41 commits — full README parity: all 22 'Full support' languages + all 14 frameworks now have coverage validation)."
+
+## DONE: coverage bump to 95%+ (commit 529d822) — RN/Expo multi-platform repos
+**Goal (from user):** bump async-storage (75.0%) and rn-device-info (72.4%) to 95%+. Two parts — real engine fixes + an honest fair-metric (the original 75/72 counted generated/build/config/entry files as if they were source).
+**Engine fixes (real coverage, generalizable):**
+1. **Same-dir C/C++ `#include`** — `#include "Foo.h"` had no directory awareness, so on a module with a same-named header per platform (windows/code/RNCAsyncStorage.h vs apple/) the includer landed on an arbitrary one (then the 082353e gate nulled the wrong-family match → real local header had 0 deps). Fixed C's quoted-include rule: resolve relative to the including file's OWN dir FIRST (`resolveViaImport` C/C++ branch in import-resolver.ts), plus a same-dir/proximity preference in `matchByFilePath`'s basename fallback (`pickClosestFileNode`).
+2. **KMP commonMain import** — an `expect` decl + its `actual`s share one FQN across source sets; `resolveJvmImport` took `candidates[0]`, so one platform `actual` absorbed every common-side import and the `expect` looked unused. Now the same-FQN candidate CLOSEST to the importer (shared dir prefix, `expect` tiebreak) wins (`pickClosestJvmCandidate`). Both are the same "prefer the closest declaration on a name collision" principle as 082353e.
+**Honest fair metric** (`/tmp/faircov.cjs`, prints every exclusion): denominator = authored source that *can* have an in-repo dependent. Excludes (per methodology, all auditable): structural (generated `.g.h`/codegen, `pch.*`, `*.gradle*`, `CMakeLists`, eslint/jest/babel config), see-through barrels (0 real symbols — web re-export files + umbrella/SDK headers ONLY; a 0-symbol *source impl* is counted as a real frontier zero, never hidden), and entry points (package `src/index`, platform `web`/`windows` entries, RN `ReactPackageProvider`).
+**Before/after:**
+| Repo | FAIR coverage before→after | residual zero (frontier) |
+|---|---|---|
+| async-storage | 75.0% → **97.4% (37/38)** | DatabaseFiles.kt (KMP expect-decl side, no in-repo caller) |
+| rn-device-info | 72.4% → **95.2% (20/21)** | RNDeviceInfoCPP.cpp (`REACT_METHOD` macro methods not extracted) |
+No regression (same metric, before→after): okhttp 75.9%→76.4%, kotlinx.coroutines 89.7% (neutral), leveldb 78.0% (neutral), redis 89.7%→89.9%, fmt 77.3% (neutral); cross-family false edges still 0 everywhere. 2 regression tests in `extraction.test.ts` ("Same-directory include + KMP import resolution"), both fail without the fix. Full suite 1169.
+
+## DONE: gate hole (commit 082353e) — cross-family references/imports
+**Symptom (was):** in `react-native-async-storage`, a TS `type TestRunner` and a Kotlin `class TestRunner` collided — TS `references`/`imports` resolved onto the Kotlin class (web→jvm false match). Plus `import React`↔Swift `React` and a C++ `#include "RNCAsyncStorage.h"`↔iOS ObjC header (basename collision).
+**Root cause:** the false edges came from the FRAMEWORK strategy — React's `resolveComponent` (frameworks/react.ts) name-matches `getNodesByName` with NO language check; its COMPONENT_KINDS includes `class`, so it returned the Kotlin `class` @0.8 (the TS `type_alias` filtered out), outranking the cross-lang-penalized (0.5) TS name-match. AND `imports` were never gated (only `references` was). NOTE: `this.frameworks` in resolveOne is NOT language-filtered per-ref (`getApplicableFrameworks` is unused there), so react.resolve runs for EVERY ref — its `languages` field is dead in that path.
+**Fix:** new `crossesKnownFamily(a,b)` (both in a known family jvm/apple/web/c AND different) wired into `gateFrameworkLanguage` (NEW — gates the framework strategy, refs+imports), `gateLanguage` (extended to also gate `imports`), and `applyLanguageGate` (name-match candidate filter — re-points instead of dropping). KEY RULE (non-obvious): the `references` gate stays STRICT (`!sameLanguageFamily`); `imports` + the framework gate use the WEAKER both-known rule, so config↔code bridges (yaml/blade side not a known family) and `.vue`/`.svelte`→`.ts` imports survive. `calls` bridges are never gated.
+**Before/after — precision fix (coverage HELD/up, false edges → 0):**
+| Repo | FAIR coverage before→after | cross-known-family false refs/imports |
+|---|---|---|
+| async-storage | 75.0% (39/52) → **75.0% (39/52)** | **22 → 0** |
+| rn-device-info (control) | 69.0% (20/29) → **72.4% (21/29)** | **5 → 0** |
+Coverage held on async-storage (no recall lost) and ROSE on rn-device-info (re-pointing gave a real same-family file a correct dependent). Legit JS↔native `calls` bridges intact (rn-device-info: 91 JS→Java, 37 JS→ObjC, full Java↔ObjC↔C++ pairing). 2 regression tests in `extraction.test.ts` ("Cross-language type/import gate"), both fail without the fix. Full suite 1167. Measure: `/tmp/faircov.cjs <repo>` (fair coverage + false-edge count) and `/tmp/xlang.cjs <repo>` (cross-lang edges by src→tgt × kind).
+
+### Framework phase round 2 (commits d06a5ec, 74b599c, 2026-06-04)
+(1) RCT_EXPORT_METHOD EXTRACTION (d06a5ec): RN bridge resolver now implements `extract()` for .m/.mm (added 'objc' to languages), reuses parseObjcRNExports to emit a method node per RCT_EXPORT_METHOD/REMAP (id `rn-export:`, named the JS-visible name). The macro parsed as ERROR before → iOS methods invisible. rn-device-info JS→objc 7→37, java↔objc pairs 22→29. (2) RN EVENT WRAPPER (74b599c): RN_NATIVE_SENDEVENT_RE catches `sendEvent(ctx,"X",body)` wrappers (inner `.emit` uses a variable) → native java/swift events now connect to JS hooks. Synth tag is `rn-event-channel`. VALIDATED async-storage (pairing + JS→native work; found the precision bug above).
+
+### Classic RN cross-platform pairing (commit 4a64ca5, 2026-06-04)
+`rnCrossPlatformEdges` (callback-synth): a native method (java/kotlin/objc/cpp) with a JS-side `calls` edge = confirmed bridge method → link to same-norm-name native method in another language (`getFreeDiskStorage:`→`getFreeDiskStorage`, first selector keyword), both directions. Skip RN_INFRA names (addListener/getConstants/getName/…). rn-device-info: 152 pairs (Java↔ObjC↔C++). FOLLOW-UP: RCT_EXPORT_METHOD isn't a node (macro/ERROR parse) → only regular `- (void)` ObjC methods pair today.
+
+### Cross-language framework phase — round 1 (commit dbc4862, 2026-06-04)
+NEW direction: RN/Expo repos where JS↔native crosses LANGUAGE boundaries. Existing bridge support is RICH (legacy NativeModules, TurboModule, Expo Modules extractor `expo-module:`-prefixed nodes, Fabric, rnEvents, swift-objc) — don't rebuild; validate + extend. Classic RN bridge WORKS (rn-device-info: 118 JS→Java + JS→ObjC calls). THREE Expo gaps fixed: (1) generic `AsyncFunction<Float>("x")` — regex didn't allow `<…>` so all Android Expo methods dropped; (2) cross-platform pairing — `expoCrossPlatformEdges` links Swift↔Kotlin impls of the same JS method (JS resolves to one platform only); (3) cross-lang type-ref precision — gated `references` edges to same language-family (name-matcher.ts `applyLanguageGate`/`sameLanguageFamily` + index.ts `gateLanguage`), so native `BatteryManager.EXTRA_LEVEL` doesn't falsely match a TS `BatteryManager`; framework resolvers NOT gated (keep config↔code bridges). Measure: `/tmp/xlang.cjs`. Detail in memory.
+
+### Objective-C result (commit 33ce431, 2026-06-04)
+WORST README language at baseline. FOUR fixes (3 in tree-sitter.ts, 1 in name-matcher.ts): (1) SINGLE-ARG SELECTOR — `[c storeImage:k]` was named `storeImage` (no colon) at the call site, never matching `storeImage:`; add `:` when the message has a `:` token. (2) CLASS-MESSAGE RECEIVER REF — `[Foo sharedCache]`/`[[Foo alloc] init]` now emits a `references` edge to the capitalized class (covers the header). (3) #IMPORT BASENAME — `#import "Foo.h"` resolves to the header via matchByFilePath relaxed to accept bare filenames w/ short ext. (4) CLASS-METHOD COLON — `Foo.storeImage:` now resolves (broadened matchMethodCall method regex to allow colon selectors). AFNetworking 50%→**90%**, SDWebImage Core 33.8%→**91.6%**. GOTCHA: SDWebImage `include/SDWebImage/*.h` are SYMLINKS to `Core/` — measure Core/ only. Residual = public-API category methods called by app code (frontier). Detail in memory.
+
+### Dart result (commit 9487954, 2026-06-04)
+Dart was in TYPE_ANNOTATION_LANGUAGES but produced ZERO `references` edges, AND mixins were dropped. (NOTE: dio raw 67.8% was example-dir pollution — real 86.4%.) Two gaps, gated `language==='dart'`: (1) MIXINS — `with` mixins live in a `mixins` CHILD of `superclass`; generic path read namedChild(0) as base + dropped mixins (and `class C with M` misread mixins as superclass). Dart branch in extractInheritance: `extends` base + `implements` per mixin. (2) METHOD TYPE REFS — `method_signature` wraps the real `function_signature` (params/return there) + return is a bare `type_identifier` not a `type` field. Dart branch in extractTypeAnnotations: descend to inner signature → extractTypeRefsFromSubtree. flutter/packages 88.8%→**92.4%**, dio 86.4%→**87.9%**. Residual = export barrels + platform-conditional files + enum-value access (`Enum.value` — value-read frontier; a Dart `Capitalized.member`→ref pass would be precise, the top follow-up). Detail in memory `impact-coverage-findings.md`.
+
+### Static-member / value-read pass (commit 857baf7, 2026-06-04)
+The deferred cross-language lever, now DONE. A type used only via a static member / enum VALUE (`MediaKind.video`, `Colors.red`, `JsonScope.NAME`, `Foo::BAR`) recorded no edge (body walker only did CALLS + `new`). `extractStaticMemberRef` (tree-sitter.ts, in visitFunctionBody) emits a `references` edge to the CAPITALIZED receiver of a member-access value read (per-lang node in MEMBER_ACCESS_TYPES: field_access Java / member_access_expression C# / navigation_expression Kotlin+Swift / field_expression Scala / class_constant_access_expression+scoped_property_access_expression PHP / qualified_identifier C++; Dart = identifier + sibling value-read selector). Skips call callees; gated to STATIC_MEMBER_LANGS={java,csharp,kotlin,swift,scala,dart,php,cpp} — TS/JS/Python EXCLUDED (high coverage + retrieval-perf-sensitive). flutter/packages 92.4%→93.2%; additive elsewhere; nodes stable. Detail in memory.
+
+### C/C++ result (commit ec8fe3f, 2026-06-04)
+C/C++ were already HIGH (name-matching resolves cross-file calls across the .h/.c split). NOT an import gap. The systematic gap was a C++ EXTRACTION BUG in languages/c-cpp.ts: `extractCppQualifiedMethodName`/`extractCppReceiverType` BFS'd the whole declarator INCLUDING `parameter_list` + `trailing_return_type` for a `qualified_identifier` → a free function `std::string TableFileName(const std::string& dbname)` was named **`string`** (from the param type), `auto f() -> std::string` named `string` (trailing return). Calls never resolved; defining file looked dependent-less. Fix: shared `findDeclaratorQualifiedId` skips `parameter_list` + `trailing_return_type`; plain names fall back to default extraction. leveldb 91.7%→**94.8%**, fmt 32 mis-named→1, redis (C, unaffected) 92.2% at ceiling. Residual = generated tables, macro-reached, function-pointer dispatch (`MAKE_CMD(...,sortCommand,...)` — deferred, broad/risky), C++ namespaces (deferred). Detail in memory `impact-coverage-findings.md`.
+
+### Ruby result (commits 44fb978 + 5bccab6, 2026-06-04)
+TWO gaps. (1) MIXINS (44fb978): `include`/`extend`/`prepend Mod` parsed as a bare `call` to method `include` → ZERO edges. Fix in languages/ruby.ts visitNode: detect bare include/extend/prepend (guard `!receiver` so `arr.include?(x)` is safe) → emit `implements` edge class/module→module. (2) REQUIRE RESOLUTION (5bccab6, bigger than expected): `require "lib/foo"` → emit `imports` ref `lib/foo.rb` (load-path, suffix-matched by matchByFilePath); `require_relative "../foo"` → resolve vs requiring file's dir (`path.posix.normalize`); bare `require "json"` skipped. Resolves to the FILE node. **sidekiq 71%→76.8% (mixins)→100% (requires); activerecord 84.8%→93% (mixins)→96.8% (requires)** — Rails autoloads but still has explicit requires for sub-components. Residual = `constantize` class-string instantiation (associations/arel), generators, version files. Detail in memory `impact-coverage-findings.md`.
+
+### PHP result (commit acfb444, 2026-06-04)
+ROOT CAUSE: PHP ignored NAMESPACES — every class qn was the bare simple name, so laravel's 7+ same-named `Factory` interfaces across namespaces collapsed to one arbitrary match, and `use` imports never resolved. Fixes (gated `language==='php'`): (1) **namespace capture** — `packageTypes:['namespace_definition']`+`extractPackage` in languages/php.ts → classes scoped to `Foo\Bar::Class`; (2) **use-import resolution** — `emitPhpUseRefs` emits an `imports` ref in `Foo\Bar::Baz` form, matched precisely by the resolver's `resolveQualifiedName` (THE big lever, 80.5%→94.9%); (3) **type-hint refs** — PHP-aware `extractPhpTypeRefs` (PHP types are `named_type`/`union_type` wrapping `name`, not `type_identifier`). guzzle 95.2%→**100%**, laravel 80.5%→**94.9%**. Residual = class-string/reflection wiring (service providers, facades, middleware) — genuine frontier. Detail in memory `impact-coverage-findings.md`.
+
+### Scala result (commit b5489d9, 2026-06-04)
+Scala was the WORST starting point — extraction made nodes but almost NO edges for typeclass code (cats 1.66 edges/node). Not one gap but a family, all gated to `language==='scala'` in `extraction/tree-sitter.ts` (+ `languages/scala.ts`): (1) **parameterized extends** — `extends A[X] with B` packed all supertypes in one `extends_clause`; generic path took only namedChild(0) w/ full text `A[X]` so no typeclass matched → new shared `scalaBaseTypeName` unwraps `generic_type`, iterate all supertypes (cats 48.9%→77.2% from THIS alone); (2) **type refs** (Scala had ZERO `references`) — added scala to TYPE_ANNOTATION_LANGUAGES + walk EVERY curried `parameters` list (trailing `(implicit M: TC[A])`!) + `type_parameters` context bounds (`[A: Monoid]`) + val/var types from scala.ts (77.2%→89.2%); (3) **instantiation** `new T[...]` = `instance_expression`. cats 48.9%→**89.2% fair** (82.1% raw — scalafix/bench excluded), gatling 76.3%→**91.2%**. Residual = cross-build variants/laws/wildcard-barrels (frontiers). Detail in memory `impact-coverage-findings.md`.
+
+### Kotlin result (commit d8a2e91, 2026-06-04)
+Systematic Kotlin gap = **Kotlin Multiplatform `expect`/`actual`** (the only Kotlin-unique construct). OkHttp (the README Kotlin benchmark) was ALREADY 96.2% out of the box; kotlinx.coroutines (KMP) was 76.8% → **93.5%**. Fix: new generic `extractModifiers` hook captures `expect`/`actual` (from `modifiers > platform_modifier`) onto the node's `decorators` list (wired once in `createNode`); `kotlinExpectActualEdges` in callback-synthesizer.ts links common decl → each platform `actual` as a heuristic `calls` edge (matched by qualified_name + the `actual` marker; decl side = non-`actual` same-qn node, which also gates out plain overloads; kind-widened so `expect class` ↔ `actual typealias` links). Node count stable. Residual = genuine frontiers (expect-decl sides, ServiceLoader/agent SPI, test infra). Full detail in memory `impact-coverage-findings.md`.
+
+## Goal
+Make the engine's cross-file dependency graph complete for **every README "Full support" language**, so impact/`affected`/callers/callees/explore all see real dependencies. Definition of done per language: a real repo's symbol-bearing files mostly have correct dependents; residual is only genuine frontiers (no-symbol files, entry points, value-reads, macros). Each language: audit → fix → validate → commit to the branch.
+
+## Methodology (apply per language — this is the loop)
+1. Clone 1 benchmark + 1 clean repo to `/tmp`. Index with `CodeGraph.initSync(repo,{config:{include:['**/*.<ext>'],exclude:[]}})` + `indexAll()` + `resolveReferences()` via a `node -e` against `dist/index.js`.
+2. Measure **fair coverage** = % of *symbol-bearing* source files with ≥1 cross-file dependent. SQL: a file is a dependent target if it's the `target` of a non-`contains` edge whose `source` is in another file. **EXCLUDE from the denominator:** files with no non-`file` node (package-info.java, doc.rs, `__init__` umbrellas), tests, entry points (main/bin/examples/benches/fuzz/samples), and miscounted other-language files (e.g. `.kt` under a Java repo).
+3. Audit the 0-dependent files → classify real-miss vs frontier. Controlled probe (2 tiny files) to isolate the exact gap.
+4. Fix extraction/resolution. Re-measure. **Verify node count stays stable** (edges added, not nodes — except real new symbols like interface/record nodes).
+5. `npm run build` (tsc must pass) → `npm test` (expect ~1151 passing) → add a test in `__tests__/extraction.test.ts` → CHANGELOG `[Unreleased] → Fixes` bullet.
+6. `git add <files>` + commit (Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>) + `git push origin feat/cross-language-impact-coverage`. Do NOT commit `.claude/handoffs/*`.
+
+## Key findings — the recurring gap shapes & where they're fixed
+- **Foundation (16b5633):** `imports` edges are same-file (file→local import node), so the old `getFileDependents` returned 0 for every file. Added `getDependentFilePaths`/`getDependencyFilePaths` in `src/db/queries.ts` (indexed JOIN, all kinds except `contains`); `src/graph/queries.ts` delegates.
+- **Import/binding linking** (per-lang emit* in `src/extraction/tree-sitter.ts`): `emitImportBindingRefs` (TS/JS named/default/namespace), `emitReExportRefs` (TS `export {X} from`), `emitPyFromImportRefs` (Python `from m import X`), `emitRustUseBindingRefs` (Rust `use`/`pub use`, emits FULL path). All gated by language in `extractImport`.
+- **Module-path resolution** (`src/resolution/import-resolver.ts`): `resolvePythonModuleMember` + `resolveModuleImportToFile` (Python+TS namespace), `resolveGoCrossPackageReference` (Go, pre-existing), `resolveRustPathReference`+`resolveRustModuleFile`+`rustCrateRootDir`/`rustSelfModuleDir` (Rust `crate::`/`self::`/`super::`). Resolve a path's module PREFIX to a file, find the leaf there — fixes common-name collisions.
+- **Instantiation:** `INSTANTIATION_KINDS` in tree-sitter.ts now includes `composite_literal` (Go) + `struct_expression` (Rust). `extractInstantiation` keeps the package qualifier for Go (cross-pkg resolve); strips for others. Also normalizes parenthesized type conversions `(*T)(x)`.
+- **Interface/trait dispatch (#584):** `IFACE_OVERRIDE_LANGS` in `src/resolution/callback-synthesizer.ts` now includes `go` and `rust`. Needs the interface/trait's METHODS extracted: Go via `extractGoInterfaceMethods` (tree-sitter.ts), Rust via adding `function_signature_item` to rust.ts function/methodTypes. `goImplementsEdges` synthesizes Go implicit `implements` edges (method-set match) and must `insertEdges` FIRST in `synthesizeCallbackEdges`.
+- **Annotations / attributes / property wrappers (UNIFIED via `extractDecoratorsFor`):** it now (a) descends into `modifiers` nodes (Java/Kotlin/C#), (b) recognizes Swift `attribute` + `user_type`. Java needed `annotation_type_declaration` added to `interfaceTypes` (java.ts). C# needed `record_declaration`/`record_struct_declaration` (csharp.ts). Swift needed a dispatcher branch running `extractDecoratorsFor`+`extractVariableTypeAnnotation` on `property_declaration` inside a type (Swift instance props aren't nodes).
+- **In-body type annotations (TS):** `visitFunctionBody` now extracts `variable_declarator` type annotations (`const x: Foo`).
+
+## Per-language results — file-dependent coverage (% of symbol-bearing source files with ≥1 cross-file dependent)
+
+| Language | Repo | Before | After | Key fix |
+|---|---|---|---|---|
+| TypeScript/JS | codegraph (this repo) | 62.5% | **95.8%** | import + re-export + namespace linking; in-body type annotations |
+| Python | requests | 54.1% | **100.0%** | `from x import` linking; `from . import sub` + `sub.f()` module-member resolution; relative-dot path fix |
+| Python | flask (src) | 66.7% | **87.5%** (true ceiling — residual all correct-0) | (same) |
+| Go | gin | 62.7% | **96.6%** | composite literals → instantiates; package-level var registries; `(*T)(x)` conversions; implicit interface satisfaction (#584) |
+| C# | MediatR (library) | 81.5% | **85.2%** | `record` / `record struct` indexed (#237) |
+| Rust | ripgrep | 63.4% | **86.7%** | struct literals; trait dispatch (trait methods + #584); `use`/`pub use` linking; module-path resolution for `pub use self::x::y` |
+| Rust | tokio (src) | 70.0% | **81.9%** | (same — number is honest/precise; earlier leaf-only match had inflated it) |
+| Java | gson | 78.2% | **85.1%** (raw) · **93.3% fair** | annotations: index `@interface` defs + link `@Foo` usages (in `modifiers`) |
+| Java | retrofit | 80.5% (raw) | **94.9% fair** | (same) |
+| Swift | Alamofire | 93.0% | **95.3%** | property wrappers / attributes (`@Argument`/`@Published`/`@objc`) |
+| Swift | swift-argument-parser | 84.6% | **96.2%** | (same) |
+| Kotlin | OkHttp | 96.2% | **96.2%** | already at ceiling (JVM, barely uses KMP) — no change needed |
+| Kotlin | kotlinx.coroutines | 76.8% | **93.5%** | Kotlin Multiplatform `expect`/`actual` linking (incl. `actual typealias`) |
+| Scala | typelevel/cats | 48.9% | **89.2% fair** (82.1% raw) | parameterized extends + type refs (implicit/context-bound) + `new` |
+| Scala | gatling | 76.3% | **91.2%** | (same) |
+| PHP | guzzle | 95.2% | **100.0%** | namespace capture + `use`-import resolution |
+| PHP | laravel/framework | 80.5% | **94.9%** | namespace capture (disambiguates same-named contracts) + use-imports + type-hints |
+| Ruby | rails/activerecord | 84.8% | **96.8%** | mixin edges (`include`/`extend`/`prepend`) + require resolution |
+| Ruby | sidekiq | 71.0% | **100.0%** | mixins + `require`/`require_relative` → file resolution |
+| C++ | google/leveldb | 91.7% | **94.8%** | fix free-function name extraction (was named after param/return type) |
+| C | redis | 92.2% | **92.2%** | already at ceiling (C unaffected; residual = generated/macro/fn-ptr) |
+| Dart | flutter/packages | 88.8% | **92.4%** | `with` mixins + method type references |
+| Dart | dio | 86.4% | **87.9%** | (same; raw 67.8% was example-dir pollution) |
+| Obj-C | AFNetworking | 50.0% | **90.0%** | single-arg selectors + class-receiver refs + #import + class-method resolution |
+| Obj-C | SDWebImage (Core) | 33.8% | **91.6%** | (same; `include/` dirs are symlink dups — measure Core/) |
+| Lua | nvim-telescope | 31.6% | **84.2%** | `require()` module resolution: dotted `a.b.c`→`a/b/c.lua` + instance-path leaf, path-suffix match w/ same-dir preference (4155609). Residual = telescope's dynamic `setmetatable` lazy-require pickers (frontier). |
+| Luau | dphfox/Fusion | 12.5% | **92.2%** | (same require resolver — `require(script.Memory.deriveScope)`) |
+| Liquid | Shopify/dawn | 39.1% | **73.8%** | Shopify OS 2.0 JSON-template section parsing: index `templates/*.json` + section-group `sections/*.json` (incl. nested `templates/customers/`), link each `"type"`→`sections/X.liquid` (2f57119). Snippet `{% render %}` already worked. Residual = preset/theme-editor sections (no static ref) + dynamic `{% render block %}`. |
+| Pascal/Delphi | PascalCoin | 73.0% | **75.7%** | `uses`-resolution ALREADY worked (73%); + `.dfm`/`.fmx` form ↔ same-basename `.pas` code-behind pairing (2f30a3b). Residual = vendored third-party libs (`src/libraries/*` internal units, ≈node_modules) + dynamic form/RPC instantiation. |
+
+**"raw" vs "fair":** "fair" excludes files that *structurally can't* have dependents (no-symbol files like `package-info.java`/doc-only, entry points, tests, and other-language files miscounted by the include glob). For Java the raw numbers were heavily polluted (gson had many `package-info.java`; retrofit had `.kt` + samples), so the fair number is the real one (~93–95%). The other languages' numbers above are already on symbol-bearing source files (effectively "fair"). C# MediatR's 85.2% is the library-only figure; a package-info-excluded "fair" wasn't separately computed but is higher.
+
+## Per-framework results — cross-language file-dependent coverage (RN/Expo, multi-platform JS↔native)
+
+| Framework | Repo | Before | After | Key fix |
+|---|---|---|---|---|
+| React Native / Expo | react-native-async-storage | 75.0% | **97.4% fair** (37/38) | cross-family gate (082353e) + same-dir C/C++ `#include` + KMP commonMain import (529d822) |
+| React Native | react-native-device-info | 72.4% | **95.2% fair** (20/21) | cross-family gate (082353e) + honest fair metric (its 529d822 engine-fix targets are excluded entry files) |
+
+**Metric note (read before trusting the "Before"):** the "Before" 75.0%/72.4% used an **under-exclusive** denominator — it counted generated codegen (`.g.h`), build scripts (`pch.*`, `*.gradle.kts`), tooling config (eslint/jest/yarn), and platform/registration **entry points** as if they were source. The "After" uses the **honest fair metric** the per-language table uses: excl. structural (generated/build/config/test), see-through barrels (web re-export files + umbrella/SDK headers — but NOT a 0-symbol source impl, which is a real frontier), and entry points (package `src/index`, platform `web`/`windows` entries, RN `ReactPackageProvider`). **Apples-to-apples** (fair metric held constant, isolating just the 529d822 engine fixes): async-storage **92.1% → 97.4%** (+RNCAsyncStorage.h via same-dir include, +Platform.kt via KMP import); rn-device-info **95.2% → 95.2%** (neutral — its same-dir/KMP targets are excluded entry headers, so its lift to 95.2% was the metric correction + the 082353e gate). Residual zeros (real frontiers): async-storage `DatabaseFiles.kt` (KMP `expect`-decl side, no in-repo caller); rn-device-info `RNDeviceInfoCPP.cpp` (`REACT_METHOD` macro methods not extracted). Measure with `/tmp/faircov.cjs <repo> --list`. No regression on controls: okhttp 75.9→76.4, kotlinx.coroutines 89.7 (neutral), leveldb 78.0 (neutral), redis 89.7→89.9, fmt 77.3 (neutral); cross-family false edges 0 everywhere.
+
+## Route-framework headroom map (canonical app per README framework, FAIR coverage)
+
+Measured 2026-06-04 (commit 61a993a) on a canonical real app for each README route framework. This is the active front of the campaign — the unmeasured frameworks have the real headroom.
+
+| Framework | App repo | FAIR coverage | Status / next |
+|---|---|---|---|
+| Express (TS) | express-realworld | 70.4% → **100%** ✅ | DONE (2a0b6e0): renamed default-import → module file (route controllers `export default router`). |
+| FastAPI (Py) | fastapi-realworld | 78.6% → **98.0%** ✅ | DONE (2835623): source-aware `from pkg import submodule` (router aggregator). 1 residual = aliased sub-aggregator. |
+| Flask (Py) | flask (lib) | **100.0%** ✅ | DONE (entries/barrels excluded) |
+| requests (Py) | requests (lib) | **100.0%** ✅ | DONE |
+| NestJS (TS) | nestjs-realworld | 93.8% → **96.8%** ✅ | DONE (main.ts entry excluded) |
+| Gin (Go) | gin (lib) | **96.5%** ✅ | DONE (faircov Go `_test.go` exclusion) |
+| Laravel (PHP) | laravel (lib) | 92.0% | done (per-language; app not separately measured) |
+| Rails (Ruby) | rails (lib) | 89.6% | done (per-language) |
+| Django (Py) | django-realworld | 45.9% → **74.1%** | PARTIAL (58dc463): abs-module-import + `include('app.urls')` done. Ceiling ~83% w/ entries excluded. FRONTIERS: signals via in-body `ready(): import myapp.signals` (Python in-body imports NOT extracted — visitFunctionBody walks calls but not import_statement); DRF/string-config exception classes (`EXCEPTION_HANDLER: '...'`). |
+| ASP.NET (C#) | eShopOnWeb | 59.3% → **83.9%** | chained extension calls (4c14413) + framework-entry exclusions (b) + Razor/Blazor markup parser (59b8de2 tags/@model + 90c5f39 @code) + **C# namespaces (dc7d033) + Razor `@using` disambiguation (9e5a951)** — DTOs now resolve to `BlazorShared.Models::CatalogBrand` not the same-named entity. C# constructor DI / interface→impl ALREADY worked. Residual ~24 = reflection/proxy (AutoMapper profiles / Swagger filters / middleware / health checks — invoked by reflection, a separate modeling feature) + a few C# static-const reads (`Constants.X` — extend the static-member pass to C#). |
+| Spring (Java) | spring-petclinic | 65.2% → **83.3%** ✅ | DONE — convention/reflection ceiling, on par with ASP.NET. 30 main java = 15 covered + 7 entry (1 `*Application` main + 6 `*Controller`) + 5 barrel (`package-info.java`) + 3 zero. 3 residual zeros all reflection-registered: `CacheConfiguration`/`WebConfiguration` (`@Configuration`, component-scanned — `WebConfiguration` is even `@SuppressWarnings("unused")`) + `PetClinicRuntimeHints` (`@ImportRuntimeHints(X.class)` class-literal = the documented `Foo.class`→`Class` frontier). faircov fix = barrel-exclude `package-info.java`/`module-info.java` shells. **No `samples`-dir exclusion ever existed in the script** — that handoff note was inaccurate. |
+| Axum (Rust) | realworld-axum-sqlx | 72.7% → **100%** ✅ | DONE (a3f59fb) — import/aggregator style, confirmed in Rust. REAL engine miss found+fixed: bare Rust `submodule::fn()` calls (the `X::router()` router-assembly pattern) resolved crate-relative only → now self-relative FIRST (current module), then crate fallback. + `main.rs`/`src/bin/*.rs` faircov entry exclusion. Clean A/B (same faircov, engine ±fix): axum +2 → 100%, ripgrep neutral (66/79), tokio +3 (260/321); cross-family false edges 0. Regression test fails without the fix. |
+| Rocket (Rust) | TatriX/realworld-rust-rocket | 62.5% → 68.8% → **93.8%** ✅ | DONE — TWO engine wins. (1) 7bb958b: a 3-segment `database::profiles::find()` call (inside `db.run(\|c\| …)`) was dropped by the resolver PRE-FILTER (leaf never checked) → +database/profiles.rs. (2) 6d214cd: NEW `routes![]`/`catchers![]` macro extractor — the handler paths live in a raw token-tree, so the 4 `routes/*.rs` handler modules (mounted at runtime) looked uncalled; now reconstructed from the macro + resolved via the Rust path resolver → all 4 covered. Only `lib.rs` (crate-root/launch hub, see-through) remains. No control regression; false edges 0; nodes unchanged (edges only). |
+| actix-web (Rust) | fairingrey/actix-realworld-example-app | **65.4%** | DONE (genuine ceiling). actix **1.x ACTOR style**: routing resolves fine (`.route(web::post().to(users::register))` → handlers covered), but the DB layer is reached via actor message dispatch (`db.send(RegisterUser)` → `impl Handler<RegisterUser> for DbExecutor`) — a DYNAMIC runtime boundary, no static edge (the actix analog of the MediatR/reactive runtimes the engine deliberately leaves uncovered). 9 zeros = 5 `db/*.rs` (actor dispatch) + `models/mod`/`utils/mod`/`prelude` (glob `pub use self::x::*` re-export roots) + `utils/hasher` (reached only via that glob). Bridging needs an actor-message synthesizer (dynamic-dispatch feature), not a static-resolution fix. |
+| Vapor (Swift) | vapor-til (canonical) | 85.7% → **100%** ✅ | DONE — import/aggregator confirmed in Swift. Controllers covered via `app.register(collection: X())`, models via controller queries + migrations. REAL miss found+fixed (bb7659e): the many-to-many pivot model was referenced ONLY via `@Siblings(through: Pivot.self)` — a metatype arg inside a property-wrapper attribute that wasn't walked → now routed through `extractStaticMemberRef` → pivot covered. + faircov excl `Package.swift` (SPM manifest) & `Public/` (static assets). A/B (same faircov): vapor-til +1 → 100%, Alamofire neutral (44/50); false edges 0. |
+| Vapor (Swift) | penny-bot (real prod, 166 files) | **73.2%** | SECONDARY — a serverless/DI architecture, NOT the canonical route→controller→model shape. 37 zeros = AWS Lambda handlers (`*Handler`/`*Lambda`, invoked by the AWS runtime → entry points, no in-repo caller) + `exports.swift` re-export barrels (see-through, like Rust mod.rs roots) + Swift extension files (`+X.swift`) + DTOs/services reached via DI / JSON-decoding (genuine frontiers). Excluding the Lambda entries + exports barrels (faircov gaps) → ~80%; genuine residual is the DI/serialization architecture. NOT chased — vapor-til is the canonical result. |
+| SvelteKit (Svelte) | sveltejs/realworld (official) | 35.9% raw → **100% fair** ✅ | DONE — characterization, NO engine miss (first framework that needed none). The `.svelte` import resolution ALREADY connects the whole component graph (page→component→lib: ArticlePreview←ArticleList, Nav←+layout, ListErrors←4 pages — imports+references+calls all resolve). Low RAW = the file-convention shape: 25/39 files are SvelteKit convention ENTRIES (`+page`/`+layout`/`+error`/`+server`/`hooks` — loaded by the framework BY PATH, no in-repo caller = route leaves, like route handlers). Excluding those (new faircov ENTRY patterns) → 14/14 = 100% of the coverable core. ONE framework-mediated gap: `+page.server.js` `load` → `+page.svelte` `data` is NOT a static link (runtime `data` prop) — was bridged with a SvelteKit convention synthesizer (sibling files by path, like Rocket routes!) — impact-granularity, not coverage (both files are entries). **BUILT (3ea03e5): `svelteKitLoadEdges`** links each page component → its OWN-dir loader's `load`/`actions` (same for `+layout`); path-deterministic (19 links / **0 cross-dir mislinks** on realworld), provenance heuristic, nodes unchanged. `getImpactRadius(load)` now surfaces its page. |
+| React Router (React) | gothinkster realworld | **100%** ✅ | DONE — characterization, NO engine miss. The CONFIG-based component-node sub-shape: route components are NAMED in source (`<Route path='/login' component={Login}/>` → App.js imports + references Login), so they resolve cleanly — verified Login/Editor/Profile all covered BY App.js's route config (imports+references). 29/29 (only `index.js` CRA entry + 8 anonymous-default-export reducers [0 named symbols → barrels] excluded). CONTRAST with SvelteKit (file-convention, needs entry-exclusion): the component-node category has TWO sub-shapes, both handled by the engine as-is. (App is old v4/v5 `component={X}`; modern v6/v7 `element={<X/>}` + data-router `{element, loader}` are also source-referenced → same conclusion.) No commit (nothing to fix). |
+| Nuxt (Vue) | nuxt/movies (official demo) | 47.6% → **93.5% fair** ✅ | DONE — file-convention component framework (like SvelteKit) but with an AUTO-IMPORT twist that was a REAL miss (1dec765). Nuxt auto-imports a NESTED component by a DIR-PREFIXED name: `components/media/Card.vue` → `<MediaCard/>`, but the node is named `Card` → the PascalCase template usage never resolved (the synth only matched kebab tags; the extractor's PascalCase ref name-matched `MediaCard`→nothing). Fix in `vueTemplateEdges`: match PascalCase tags + a `nuxtComponentName` map (`media/Card.vue`→`MediaCard`, incl. Nuxt dir de-dup) → +9 nested components. + faircov Nuxt entry exclusions (pages/, app.vue, error.vue, layouts/, plugins/, middleware/, server/). 2 residual zeros = genuine frontiers (unused `<CarouselItems>` variant + unimported `constants/images.ts`). Composables auto-import (`useTmdb()`) already resolved by name-match. false edges 0, nodes unchanged. **vs SvelteKit:** SvelteKit needed NO component fix (svelte imports resolve); Nuxt DID (its auto-import dir-prefix naming is unique). |
+| Drupal (PHP) | token (contrib module) | 57.1% raw → **78.9% fair** | DONE — the MOST reflection-heavy framework, a genuine sub-95% ceiling (≈ASP.NET 83.9%, Django 74.1%). Static parts WORK: `*.routing.yml`→controller (drupal.ts resolves it — `TokenTreeController` covered via the route ref), PHP class refs (namespaces/`use`/type-hints). 4 residual zeros all DI/reflection-wired: 2 services in `services.yml` (`TreeBuilder` = `@token.tree_builder`, `TokenFieldRender`), a DYNAMICALLY-routed controller (`TokenDevelController` via `RouteSubscriber`, not static YAML), a field-plugin class (`MenuLinkFieldItemList` list_class). + faircov excl JS libraries + convention entries (`.install`/`.module`, `src/Plugin`/`Element`, Drush, `*ServiceProvider`, `Routing`/`*Subscriber`). LEVERS (drupal.ts TODOs, large per-mechanism features, NOT chased): model `services.yml` DI (→ covers the 2 services), plugin annotations + modern `#[Hook]` attributes. No commit (no simple miss). |
+
+**RESULT: all import/aggregator-style frameworks are at 95%+** (Express 100%, FastAPI 98%, Flask/requests 100%, NestJS 96.8%, Gin 96.5%, Axum 100%).
+
+**Option (b) DONE (metric-only — framework-entry exclusions in `/tmp/faircov.cjs`):** added convention-entry patterns (`*Controller.cs/java`, `*.cshtml.cs`, `*Endpoint.cs`, EF `Data/Config/*.cs`, `Program/Startup.cs`, `*Application.java`, Django `admin.py`/`apps.py`). Result — convention frameworks rise but **still cap well below 95%**: ASP.NET 65.3% → **77.2%** (50 entries excluded), Spring petclinic 65.2% → **83.3%** (after the `package-info.java` shell-exclusion fix below), Django **74.1%**. The import-style frameworks are unaffected (Express 100%, FastAPI 98%, NestJS 96.8%, Gin 96.5% — the C#/Java/Django entry patterns don't touch them).
+
+**WHY (b) doesn't reach 95% — the honest ceiling:** after excluding routed/reflection-registered entries, the residual zeros are **markup-driven** code-behind (Blazor `.razor` / Razor `.cshtml` / Thymeleaf reference the `.cs`/`.java`, but the markup isn't parsed → ViewModels, DTOs, components look unused) and **reflection/proxy** code (Spring Data repository proxies, AutoMapper profiles, Swagger filters, DI/middleware registration, Django signals/string-config). These are genuine static-analysis frontiers — reaching 95% needs (1) parsing template markup to link markup→code, or (2) per-framework reflection/proxy modeling — both large features. **Excluding markup-driven business code (DTOs/ViewModels) from the metric to fake 95% would be gaming — NOT done.** Note: business LOGIC (services, repos) IS covered in all three; the residual is leaf views/DTOs/configs whose impact is captured the other direction (route→handler).
+
+**Generalizable engine fixes shipped this campaign (all benefit beyond their trigger framework):** Python absolute `import a.b.c` (61a993a); source-aware `from pkg import submodule` (2835623); Django `include('app.urls')` claim (58dc463); chained method calls `a.b.Method()` incl. C# extension methods (4c14413); renamed default-import → module file (2a0b6e0); Rust bare `submodule::fn()` calls resolved self-relative — current module first, then crate fallback (a3f59fb); multi-segment Rust `a::b::c()` module calls no longer dropped by the resolver pre-filter — the leaf name is now checked (7bb958b).
+
+**KEY REALITY (honest):** apps dominated by **convention/reflection-driven** code (ASP.NET MVC/Razor/Blazor, EF config, reflection DI; Django signals/DRF; any framework whose handlers are discovered by routing/DI container, not called by in-repo code) have files with NO static in-repo caller. Those are genuine static-analysis frontiers — **literal 95% is not reachable** on such apps without either (a) excluding all framework-entry conventions from the fair denominator (defensible per methodology but extensive + per-framework), or (b) modeling each framework's convention routing + DI container (large per-framework engine work). The DI-heavy/convention-heavy frameworks (ASP.NET, Spring, MVC) are this category; the import/aggregator-style ones (FastAPI, Flask, Express, Gin) reach 95%+ with tractable resolution fixes.
+
+**SWEEP COMPLETE — every README framework measured.** Route frameworks: Express 100%, FastAPI 98%, Flask/requests 100%, NestJS 96.8%, Gin 96.5%, Axum 100%, Rocket 93.8%, Vapor 100%, Laravel 92%, Rails 89.6% (import/aggregator) · ASP.NET 83.9%, Spring 83.3%, Drupal 78.9%, Django 74.1%, actix 65.4% (convention/reflection/actor ceiling). Component-node: React Router 100% (config-based) · SvelteKit 100% fair, Nuxt 93.5% fair (file-convention). **Component-node category fully characterized**: config-based (route components named in source → 100% raw) + file-convention (discovered by path → entry-exclusion; SvelteKit needed NO component fix, Nuxt needed the dir-prefix auto-import fix). Convention/reflection frameworks (ASP.NET/Spring/Drupal/Django/actix) are at a genuine sub-95% static-analysis ceiling — the levers are large per-mechanism features (markup/reflection/DI modeling), deliberately not chased. **faircov exclusions added this session:** language-aware test files (`_test.go`, `test_*.py`, `*Tests.cs`, `*_spec.rb`, …); generated migrations (Django/Alembic `migrations/`, EF `Migrations/*.cs`/`*.Designer.cs`/`*ModelSnapshot.cs`); Python entries (`__main__.py`, `setup.py`, `conf.py`, `docs/`) + `__init__.py` barrels. faircov now barrel-excludes `package-info.java`/`module-info.java` shells (package-declaration-only files — they carry a `namespace` node so `realSyms !== 0`, but nothing can import them, so they can never be a dependency target; the Java analog of `__init__.py`). This is what actually blocked an honest Spring number: petclinic's 5 `package-info.java` sat in the denominator as zeros, deflating 83.3% → 65.2%. **There was never a `samples`-dir exclusion in the script** — that earlier handoff note was inaccurate (the only similar rule is `example[s]?`, which can't match `samples`). Route-framework-front faircov ENTRY additions: Rust binary entries (`main.rs`, `src/bin/*.rs`); Swift `Package.swift` (SPM manifest) + `Public/` static assets; SvelteKit file-convention entries (`+page`/`+layout`/`+error`/`+server.*`, `hooks.*`, `service-worker.*` — framework-discovered route leaves, no in-repo caller); Nuxt file-convention entries (`pages/`, `app.vue`/`error.vue`, `layouts/`, `plugins/`, `middleware/`, `server/`, `proxy/routes/`); Drupal convention entries (`.install`/`.module`/`.profile`/`.theme` hook files, `src/Plugin`/`src/Element` annotation-plugins, `src/Drush`, `*ServiceProvider.php`, `src/Routing`/`*Subscriber.php`) + `js/` library assets.
+
+## How to push each language higher (remaining levers)
+
+**The one big cross-language lever: a static-member / const value-read pass.** Extract `Type.MEMBER` (capitalized/known-type receiver) as a `references` edge to `Type`. This is the universal deferred data-flow frontier and would lift **C#, Java, Swift, TS, and Rust at once**. Implement once in extraction with a heuristic (receiver resolves to / looks like a type → emit ref; skip lowercase `obj.field`). Trade-off = some instance-field-access noise; that's why it's been deferred. This is the highest-leverage single task remaining.
+
+Per language — what's left and the action to improve it:
+- **C# — MediatR 85.2% (raw, the lowest real number):**
+  - *raw→fair:* exclude no-symbol files (`TypeForwardings.cs` = assembly attrs only, `package-info`-equivalents) + benchmark `main`s → ~92%+. **A fair re-measure was never run for C# — do it first; the "real" number is materially higher.**
+  - *to improve further:* static/const value reads (`BuildInfo.BuildDate`, enum `Edition?` where a same-named property shadows the type) → the static-member pass.
+- **Java — gson 85.1% raw → 93.3% fair:**
+  - *raw→fair:* exclude `package-info.java` (no symbols) + `.kt`/samples (already done for the fair number).
+  - *to improve fair further:* static-field reads (`X.FACTORY`), `Foo.class` class literals (currently `Foo.class` references `Class`, not `Foo`), constant reads (`JsonScope.X`) → the static-member pass.
+- **Rust — tokio 81.9% (lowest of the high group), ripgrep 86.7%:**
+  - residual = see-through `mod.rs`/`lib.rs` roots (correct-0), **macro-reached code** (`log!`, custom `macro_rules!`, derives — the big Rust frontier, hard), external-trait-only impls.
+  - *to improve:* macro handling (large, separate project) + static/const reads. Note tokio's 81.9% is already honest/precise (path resolution removed spurious leaf-match edges).
+- **Go — gin 96.6%:**
+  - residual = `//go:build` alternates (appengine/jsoniter/go_json/sonic/nomsgpack) + external-API `version.go`.
+  - *to improve:* a **build-constraint parser** (evaluate `//go:build`) so inactive variants are excluded from the denominator or all variants are linked (recall-first). Only matters for build-tag-heavy repos; niche.
+- **TS 95.8% · Python requests 100% / flask 87.5% · Swift 95.3% / 96.2%:** at/near true ceiling — residual is entry points, see-through barrels, external public API, and value-reads. The **only** lever left for these is the static-member/const pass.
+
+**Bottom line:** Python/TS/Swift/Go are effectively at ceiling. The two with real headroom are **C#** (mostly a fair-remeasure — do that first) and **Rust tokio** (macros — hard). The static-member/const pass is the one change that moves *everything* a few points; the rest is per-language frontier work.
+
+## Which tools benefit (asked + answered this session)
+It's a GRAPH-WIDE update (one shared `edges` table). `getCallers`/`getCallees` follow `['calls','references','imports']`; `getImpactRadius` + `getFileDependents`/`affected` follow **all except `contains`**; `codegraph_explore` composes all of them. So `instantiates`/`implements`/`decorates` edges show in impact+explore but **not** callers/callees (a pre-existing edge-kind filter in `getCallers`/`getCallees` — could be broadened, deferred).
+
+## Gotchas
+- **Include globs don't filter reliably** — tests/examples/benches/`.kt` leak into the index. Filter in the measurement SQL, not the config.
+- **`/tmp` clones persist across turns** — `rm -rf <repo>/.codegraph` before re-indexing or `initSync` throws "already initialized" and you measure a STALE index (this bit me ~3×; a stale index massively under-reports).
+- **Fair metric must exclude no-symbol files** (package-info, doc-only) — they can't have dependents; counting them is dishonest-low. Also a slightly-LOWER honest number (Rust tokio 83→82 after path resolution) beat the spurious-inflated one — precision over optics.
+- **Build vs test:** `npm test` uses esbuild (no typecheck); `npm run build` (tsc) is what catches type errors. Always build before committing. Strict null on regex groups bit me — avoid `m[1]` indexed access.
+- Node-version regex-group access (`m[1]`) is `string|undefined`; use guards.
+
+## How to test & validate
+- `npm run build` → tsc clean (must pass before commit).
+- `npm test` → **1178 passed | 2 skipped** (59 files, verified 2026-06-05). Per-language tests live in `__tests__/extraction.test.ts` (describe per language); route-framework/RN tests in `__tests__/{react-native-bridge,expo-modules,rn-event-channel}.test.ts`.
+- Coverage probe recipe: clone repo → `node -e "...initSync...indexAll...resolveReferences..."` → the fair-coverage SQL (see Methodology #2). Node count stable = no explosion.
+- Full per-language findings + exact fixes: memory file `~/.claude/projects/-Users-colby-Development-CodeGraph-codegraph/memory/impact-coverage-findings.md`.
+
+## Repo state
+- branch `feat/cross-language-impact-coverage`, last commit `2f30a3b feat(impact): pair Delphi forms with their .pas code-behind (.dfm/.fmx ↔ .pas)`.
+- **41 commits ahead of `main`, 3 behind** (behind = 3 README-waitlist doc commits on main). All pushed to origin. NOT merged — branch is for review. Niche-lang commits 39–41: 4155609 (Lua/Luau require resolver), 2f57119 (Liquid Shopify-JSON sections), 2f30a3b (Delphi .dfm form pairing).
+- Commits 1–20 (per-language + RN/Expo, `16b5633`→`529d822`): 16b5633 (foundation+TS/Py/Go/C#), b538aee + 2ac7df5 (Rust), badb124 (Java), d111f26 (Swift), d8a2e91 (Kotlin), b5489d9 (Scala), acfb444 (PHP), 44fb978 + 5bccab6 (Ruby), ec8fe3f (C/C++), 9487954 (Dart), 857baf7 (static-member pass), 33ce431 (Objective-C), dbc4862 (Expo bridges), 4a64ca5 (classic RN pairing), d06a5ec (RCT_EXPORT_METHOD nodes), 74b599c (RN event wrapper), 082353e (cross-family gate), 529d822 (same-dir include + KMP import).
+- Commits 21–31 (ROUTE-FRAMEWORK front, `61a993a`→`b653688`, added after the original save): 61a993a (Python absolute `import a.b.c`), 2835623 (source-aware `from pkg import submodule` — FastAPI), 58dc463 (Django `include('app.urls')`), 4c14413 (chained `a.b.Method()` + C# extension methods), 2a0b6e0 (renamed default-import → module file — Express), 59b8de2 (Razor/Blazor `.cshtml`/`.razor` markup parser), 90c5f39 (Blazor `@code`/Razor `@{}` → C# extractor), 4589cf9 (docs), dc7d033 (C# namespace extraction), 9e5a951 (Razor `@using` disambiguation), b653688 (handoff notes + docs). Commit 32 (`a3f59fb`): Rust self-relative `submodule::fn()` resolution — Axum realworld 72.7%→100%, controls neutral/+3, regression test added. Commit 33 (`7bb958b`): multi-segment Rust `a::b::c()` calls no longer dropped by the resolver pre-filter (leaf-name check in `hasAnyPossibleMatch`) — Rocket realworld 62.5%→68.8%, additive elsewhere, regression test added. Commit 34 (`6d214cd`): Rocket `routes![]`/`catchers![]` macro extractor (parse the handler paths out of the raw token-tree, emit references) — Rocket 68.8%→93.8%, nodes unchanged (edges only), no control regression, regression test added. Commit 35 (`bb7659e`): Swift property-wrapper attribute-arg type refs — route a property's attribute args through `extractStaticMemberRef` so a Fluent `@Siblings(through: Pivot.self)` links the model to the pivot — vapor-til 94.7%→100%, Alamofire neutral, regression test added. Commit 36 (`3ea03e5`): SvelteKit `load`→page synthesizer (`svelteKitLoadEdges` in callback-synthesizer.ts) — links each `+page.svelte`/`+layout.svelte` to its OWN-dir loader's `load`/`actions`; impact-granularity (coverage already 100%), 0 cross-dir mislinks, nodes unchanged, regression test added. Commit 37 (`1dec765`): Nuxt nested auto-imported component resolution — `vueTemplateEdges` now matches PascalCase tags + a `nuxtComponentName` map (`<MediaCard>`→`media/Card.vue`); nuxt/movies 47.6%→93.5%, +9 nested components, Vue-only (gated to .vue), nodes unchanged, regression test added.
+- uncommitted: only untracked `assets/generate-waitlist.py` (unrelated — README-waitlist tooling; the `.claude/handoffs/*` files are committed on this branch).
+- Touched source files (branch vs main): `src/db/queries.ts`, `src/graph/queries.ts`, `src/extraction/{tree-sitter,tree-sitter-types,grammars}.ts`, `src/extraction/razor-extractor.ts` (NEW — Razor/Blazor markup), `src/extraction/languages/{rust,java,csharp,kotlin,php,ruby,scala,c-cpp}.ts`, `src/resolution/{import-resolver,callback-synthesizer,index,name-matcher}.ts`, `src/resolution/frameworks/{python,react-native,expo-modules}.ts`, `src/types.ts`, `__tests__/{extraction,graph,expo-modules,react-native-bridge,rn-event-channel}.test.ts`, `CHANGELOG.md`.
+- Measurement scripts (in /tmp, not committed): `faircov.cjs` (honest fair coverage + false-edge count, `--list` shows residual zeros + exclusions), `audit.cjs` (lists 0-dependent files by language), `xlang.cjs` (cross-lang edges by src→tgt × kind).
+
+## Open threads / TODO
+- [x] **Kotlin DONE** (commit d8a2e91) — gap was KMP `expect`/`actual`; coroutines 76.8%→93.5%, OkHttp already 96.2%. See "Kotlin result" above.
+- [x] **Scala DONE** (commit b5489d9) — gap was a whole family of missing edges (parameterized extends, type refs, implicit/context-bound params, `new`); cats 48.9%→89.2% fair, gatling 76.3%→91.2%. See "Scala result" above.
+- [x] **PHP DONE** (commit acfb444) — gap was NAMESPACES (not #608/#660); guzzle 95.2%→100%, laravel 80.5%→94.9%. See "PHP result" above.
+- [x] **Ruby DONE** (commits 44fb978 + 5bccab6) — gaps were MIXINS + REQUIRE resolution; activerecord 84.8%→96.8%, sidekiq 71%→**100%**. See "Ruby result" above.
+- [x] **C/C++ DONE** (commit ec8fe3f) — gap was a C++ free-function name-extraction bug; leveldb 91.7%→94.8%, redis (C) 92.2% at ceiling. See "C/C++ result" above.
+- [x] **Dart DONE** (commit 9487954) — gaps were mixins (`with`) + method type refs; flutter/packages 88.8%→92.4%, dio 86.4%→87.9%. See "Dart result" above.
+- [ ] **Objective-C next** (last README language, already partial — `@interface`/`@implementation` split, `#import`, categories, protocols, `@property`). Niche after: Liquid, Pascal, Lua, Luau.
+- [x] **Static-member/value-read pass DONE** (commit 857baf7) — `Enum.value`/`Type.CONST`/`Foo::BAR` → references; flutter 92.4%→93.2%, additive across Java/C#/Kotlin/Swift/Scala/PHP/C++. TS/JS/Python excluded.
+- [x] **Objective-C DONE** (commit 33ce431) — selectors + class-receiver + #import + class-method resolution; AFNetworking 50%→90%, SDWebImage Core 33.8%→91.6%. ← LAST README language.
+- [x] **Per-language + RN/Expo campaign COMPLETE** (`16b5633`→`529d822`): all 15 README langs + static-member pass + cross-language RN/Expo at 95%+.
+- [x] **Route-framework front — import/aggregator style DONE** (`61a993a`→`2a0b6e0`): Express 100%, FastAPI 98%, Flask/requests 100%, NestJS 96.8%, Gin 96.5%. See the headroom map.
+- [~] **Route-framework front — convention/reflection style PARTIAL** (`4c14413`,`59b8de2`,`90c5f39`,`dc7d033`,`9e5a951`): ASP.NET eShopOnWeb 59.3%→83.9% (Razor/Blazor parser + C# namespaces), Django realworld 45.9%→74.1%. At an honest sub-95% static-analysis ceiling (markup-driven code-behind + reflection/DI). Reaching 95% needs markup→code linking or per-framework reflection modeling (large features); faking it via metric exclusions = gaming, NOT done.
+- [x] **Spring DONE** (83.3% fair, 15/18) — the real blocker was faircov NOT excluding `package-info.java` shells (5 in petclinic), not a `samples`-dir exclusion (which never existed in the script). Fixed → barrel-exclude `package-info.java`/`module-info.java`. 3 residual zeros = `@Configuration` beans + AOT `RuntimeHints`, all reflection-registered → the convention/reflection ceiling, on par with ASP.NET 83.9%.
+- [x] **Axum (Rust) DONE** (72.7%→**100%**, a3f59fb) — import/aggregator thesis confirmed in a 3rd language family. Found+fixed a REAL engine miss (not a metric issue): bare Rust `submodule::fn()` calls (the `X::router()` router-assembly pattern) resolved crate-relative only → now self-relative FIRST (current module), then crate fallback. Clean A/B: no control regression (ripgrep neutral 66/79, tokio +3 → 260/321); cross-family false edges 0; regression test fails without the fix. NOTE: actix/Rocket NOW MEASURED (below).
+- [x] **Rocket (Rust) DONE** (62.5%→68.8%→**93.8%**, 7bb958b + 6d214cd) — TWO engine wins: (1) multi-segment `a::b::c()` calls were dropped by the resolver pre-filter (leaf never checked) → fixed → +database/profiles.rs; (2) built the `routes![]`/`catchers![]` macro extractor — parses handler paths out of the raw token-tree + resolves them via the Rust path resolver → all 4 `routes/*.rs` handler modules covered. Only `lib.rs` (crate-root/launch hub, see-through) remains → effectively at ceiling. No control regression, false edges 0, nodes unchanged (edges only).
+- [x] **actix-web (Rust) DONE** (**65.4%**, genuine ceiling) — actix 1.x ACTOR style: routing resolves (handlers covered), but the DB layer is reached via actor message dispatch (`db.send(Msg)` → `impl Handler<Msg> for DbExecutor`) — a DYNAMIC runtime frontier with no static edge (deliberately uncovered, the actix analog of MediatR/reactive runtimes). + glob `pub use self::x::*` re-export roots. Bridging needs an actor-message synthesizer (dynamic-dispatch feature), not a static fix.
+- [x] **Vapor (Swift) DONE** — vapor-til (canonical) 85.7%→**100%** (bb7659e), penny-bot (real prod, 166 files) 73.2% (serverless/DI, secondary). Import/aggregator confirmed in Swift: controllers via `app.register(collection: X())`, models via controller queries + migrations. REAL miss found+fixed: a many-to-many pivot model referenced ONLY via `@Siblings(through: Pivot.self)` (metatype arg in a property-wrapper attribute, not walked) → routed attribute args through `extractStaticMemberRef` → pivot covered. + faircov excl `Package.swift` + `Public/`. penny-bot's lower number = AWS Lambda entries + `exports.swift` barrels (faircov gaps, ~80% if excluded) + DI/serialization/extension frontiers (genuine); not chased.
+- [x] **SvelteKit (Svelte) DONE** (35.9% raw → **100% fair**, NO commit — first framework needing NO engine fix) — sveltejs/realworld (official). The `.svelte` import resolution ALREADY connects the whole component graph (page→component→lib — verified: imports+references+calls all resolve, e.g. ListErrors←4 pages). Low raw = the file-convention shape: 25/39 files are SvelteKit convention ENTRIES (`+page`/`+layout`/`+error`/`+server`/`hooks` — framework-discovered route leaves, no in-repo caller) → excluded in faircov → 14/14 = 100% of the coverable core. ONE framework-mediated gap: `+page.server.js` `load` → `+page.svelte` `data` (runtime `data` prop, not static) — bridged with a SvelteKit convention synthesizer (sibling-by-path, like Rocket routes!) — impact-granularity not coverage (both files are entries). **BUILT (3ea03e5): `svelteKitLoadEdges`** (callback-synthesizer.ts) links each page → its own-dir loader's `load`/`actions` + `+layout`; 19 links / 0 cross-dir mislinks on realworld, nodes unchanged, regression test (incl. does-not-cross-routes guard).
+- [x] **React Router (React) DONE** (**100%**, 29/29, NO commit — no engine miss) — gothinkster realworld. The CONFIG-based component-node sub-shape: route components are NAMED in source (`<Route path='/login' component={Login}/>`) → App.js imports+references each → all resolve (verified Login/Editor/Profile covered by App.js's route config). Only `index.js` (CRA entry) + 8 anonymous-default reducers (0 symbols → barrels) excluded. The component-node category is now fully characterized: config-based (React Router, source-referenced → 100% raw) vs file-convention (SvelteKit, path-discovered → fair-100% + synthesizer); the engine handles BOTH as-is. (Modern v6/v7 `element={<X/>}`/data-router `{element, loader}` also source-referenced → same.)
+- [x] **Nuxt (Vue) DONE** (47.6% → **93.5% fair**, 1dec765) — nuxt/movies (official demo). File-convention component framework (like SvelteKit) but with an AUTO-IMPORT twist that WAS a real miss: Nuxt auto-imports a NESTED component by a DIR-PREFIXED name (`components/media/Card.vue` → `<MediaCard/>`), but the node is named `Card` → the PascalCase usage never resolved. Fixed `vueTemplateEdges` (match PascalCase tags, not just kebab + a `nuxtComponentName` map) → +9 nested components. + faircov Nuxt entry exclusions. composables (`useTmdb()`) already resolved by name-match. 2 residual zeros = genuine frontiers (unused `<CarouselItems>` + unimported `constants/images.ts`). **KEY contrast:** SvelteKit needed NO component fix, Nuxt DID — its dir-prefix auto-import naming is unique. The Vue PascalCase-tag change is gated to `.vue` files (suite green, false edges 0).
+- [x] **Drupal (PHP) DONE** (57.1% raw → **78.9% fair**, NO commit — reflection ceiling, no simple miss) — token contrib module. The MOST reflection-heavy framework. Static parts WORK: `*.routing.yml`→controller (drupal.ts), PHP class refs. 4 residual zeros all DI/reflection: 2 `services.yml` services (`TreeBuilder`/`TokenFieldRender`), a dynamically-routed controller (`TokenDevelController` via `RouteSubscriber`), a field-plugin class. + faircov excl JS libraries + convention entries. Sits with ASP.NET 83.9% / Django 74.1% in the convention/reflection band. LEVERS = drupal.ts TODOs (model `services.yml` DI → +2 services; plugin annotations; modern `#[Hook]` attributes) — large per-mechanism features, NOT chased (same stance as ASP.NET/Spring/Django: don't fake 95% via reflection modeling). **← LAST framework; the sweep is complete.**
+- [ ] **Frameworks not yet measured** (need a canonical app cloned): Drupal, React Router, Vue-Nuxt (SvelteKit DONE: 100% fair — component-node shape characterized, NO engine miss; Rust route DONE: Axum 100%, Rocket 93.8%, actix 65.4%; Vapor DONE: vapor-til 100%, penny-bot 73.2% serverless/DI) (component-node frameworks — coverage shape differs). The headroom map calls these the real remaining headroom.
+- [x] **All 4 niche README languages DONE** (Lua 84.2%, Luau 92.2%, Liquid 73.8%, Pascal 75.7%) — see the per-language table. Full README parity (22 langs + 14 frameworks).
+- [ ] **Open the PR to `main`** (41 commits) — everything actionable is done. Deferred polish (genuinely optional): C function-pointer dispatch + C++ namespace capture; PHP IFACE_OVERRIDE_LANGS + type-hint disambiguation; Scala wildcard imports; ObjC type refs; engine symlink-dedup (SDWebImage `include/` dup file nodes); a convention/reflection lever (Drupal services.yml DI / ASP.NET-Spring reflection modeling — large per-framework features). (Static-member pass for TS/JS/Python is NOT a lever — measured & rejected, e7b86df.)
+- [x] **Static-member/const pass for TS/JS/Python MEASURED & REJECTED** (e7b86df) — the long-standing "one big cross-language lever." A/B (extend `extractStaticMemberRef` to ts/js/python): **0 coverage gain** on excalidraw (94.3%→94.3%) AND requests (100%→100%) — in import-based languages a `Type.MEMBER` read requires `import`ing the type, so the import edge already covers it (the static read is pure duplication) — while adding **+1813 edges / +2448 `references` on excalidraw** (the retrieval-perf benchmark), all pointing at already-covered types. Reverted; finding documented in the `STATIC_MEMBER_LANGS` comment so it isn't re-tried. The deferral was CORRECT — now proven with data.
+- [ ] Cross-language **static-member / const value-read** pass (`X.FACTORY`, `JsonScope.X`, `Foo.class`) — the universal deferred data-flow frontier; would lift Java/C#/etc. ~5% more but risks noise. User aware; deferred.
+- [ ] Optional: broaden `getCallers`/`getCallees` edge-kind list to include `instantiates`/`implements`/`decorates` (offered, deferred — changes what "caller" means).
+- [ ] Branch is NOT merged — it's for review. Maintainer handles version bumps/releases. Don't merge or bump.
+
+## Recent transcript (oldest → newest)
+### Turn — "Rust next"
+- **Claude:** Cloned ripgrep+tokio. Found struct literals (`struct_expression`) not in INSTANTIATION_KINDS, `use` bindings not linked, trait methods (`function_signature_item`) not extracted. Fixed all + added rust to IFACE_OVERRIDE_LANGS. ripgrep 63%→81%, tokio→83%. → commits b538aee, then 2ac7df5 (module-path resolution for `pub use self::read::read` collisions → ripgrep 87%).
+### Turn — "do fixes translate to explore/callers/callees or just impact?"
+- **Claude:** Verified against tool code → graph-wide; mapped edge-kinds per tool (callers/callees = calls/references/imports; impact/explore = all-but-contains). instantiates/implements/decorates only in impact/explore.
+### Turn — "Java next" → "is Java good or can we improve it?"
+- **Claude:** Found Java annotation gap (usages in `modifiers` not descended; `@interface` not in interfaceTypes). Fixed both → gson 78%→85% (commit badb124). On re-push ask: pushed already. On "is it good": fair re-measure showed Java actually **93.3%/94.9%** (raw was polluted by package-info/.kt/samples); residual = universal value-read frontier. Concluded Java is good.
+### Turn — "Swift next"
+- **Claude:** Alamofire already 93%. argparser 84.6% — found property-wrapper gap (`@Argument` = Swift `attribute`→`user_type`, not recognized; Swift instance props not extracted). Extended `extractDecoratorsFor` + dispatcher branch. Alamofire→95.3%, argparser→96.2%. Commit d111f26. Completes README benchmarked 7.
+### Turn — /handoff save (original, 2026-06-04)
+- Saved at commit 529d822 (per-language + RN/Expo campaign).
+### Session — ROUTE-FRAMEWORK front (2026-06-04→05, commits `61a993a`→`b653688`; reconstructed from commits)
+- Measured a canonical real app per README route framework. Import/aggregator frameworks made reachable: Python absolute `import a.b.c` (61a993a), source-aware `from pkg import submodule` for FastAPI aggregators (2835623), Django `include('app.urls')` (58dc463), renamed default-import→module file for Express controllers (2a0b6e0) → Express 100%, FastAPI 98%, Flask/requests 100%, NestJS 96.8%, Gin 96.5%.
+- Convention/reflection (ASP.NET/Blazor): built a Razor/Blazor `.cshtml`/`.razor` markup parser (59b8de2), delegated `@code`/`@{}` to the C# extractor (90c5f39), added C# namespace extraction (dc7d033) + Razor `@using` disambiguation (9e5a951), resolved chained `a.b.Method()` incl. C# extension methods (4c14413) → eShopOnWeb 59.3%→83.9%, Django→74.1%. Concluded these hit a genuine static-analysis ceiling (markup/reflection); did NOT game the metric to fake 95%.
+### Session — this update (2026-06-05)
+- **User:** loaded the wrong handoff first (explore-overhaul-bench), asked about per-language coverage %, then switched to this branch to work on impact coverage.
+- **Claude:** sourced the coverage table from the `impact-coverage-findings` memory (corroborated by this handoff's own table); found this handoff committed on the branch + loaded it; flagged the branch had moved 11 commits past the handoff's stated tip; **refreshed this handoff to current state** (31 commits, route-framework front, fork of next steps; test count re-verified 1178). Then deleted the other 9 handoff files at the user's request, leaving this as the sole handoff.
+- **Outcome:** handoff is current + the only one left; awaiting the user's pick of fork (ship / route front / static-member pass).
+### Session — Spring + Axum (2026-06-05, commit a3f59fb)
+- **User:** "unblock spring by fixing the faircov samples bug" → then "yes" to measuring an unmeasured framework.
+- **Claude (Spring):** there was NO `samples`-dir exclusion in faircov (the handoff note was wrong); the real deflation was 5 `package-info.java` shells (namespace-only → realSyms≠0) sitting in the denominator as zeros. Fixed faircov to barrel-exclude `package-info.java`/`module-info.java`. Spring petclinic 65.2%→**83.3%** (15/18); 3 residual zeros all reflection/DI wiring (`@Configuration` + AOT hints — verified honest, not missed edges) → convention/reflection ceiling, ≈ASP.NET 83.9%.
+- **Claude (Axum):** measured realworld-axum-sqlx → 72.7%, audited zeros → found a REAL engine miss (not a metric issue): bare Rust `submodule::fn()` calls (`X::router()` router-assembly) resolved crate-relative only. Fixed `resolveRustModuleFile` to try self-relative FIRST, then crate fallback; + `main.rs`/`src/bin/*.rs` faircov entry exclusion. Axum → **100%** (10/10). Clean A/B (same faircov, engine ±fix): axum +2, ripgrep neutral 66/79, tokio +3 → 260/321; cross-family false edges 0; regression test fails without the fix; full suite **1179** green. Committed+pushed `a3f59fb`.
+- **Outcome:** Spring + Axum both measured; the import/aggregator → 95%+ thesis now holds in a 3rd language family (Rust) via a real engine fix, not a metric tweak. Remaining unmeasured: actix/Rocket (attribute-macro routing — likely convention/reflection shape), Vapor, React Router/SvelteKit/Vue-Nuxt, Drupal.
+### Session — Rust attribute-macro frameworks (2026-06-05, commit 7bb958b)
+- **User:** "rust frameworks to probe the ceiling" (actix + Rocket).
+- **Claude:** measured Rocket (TatriX/realworld-rust-rocket) 62.5% + actix (fairingrey/actix-realworld) 65.4%. Audited zeros → TWO findings. (1) Rocket's 3-segment `database::profiles::find()` calls weren't becoming edges — isolated via micro-tests to a RESOLVER PRE-FILTER bug (`hasAnyPossibleMatch` checked first-seg + the `b::c` remainder, never the leaf), NOT closures or extraction (both fine). Fixed (leaf-name check) → Rocket 68.8%, additive elsewhere, no control regression, false edges 0. Committed 7bb958b + regression test. (2) Remaining ceilings are GENUINE: Rocket's `routes![]` macro-mounted handlers (bridgeable via a Rocket extractor — deferred, framework-specific) + actix's actor message dispatch (`db.send(Msg)`→`impl Handler<Msg>`, a dynamic frontier like MediatR — not bridged).
+- **Outcome:** both measured; the "attribute-macro = ceiling" hypothesis was PARTLY right (genuine ceilings exist) but probing surfaced a real generalizable resolver bug that benefits all Rust `a::b::c()` calls. All Rust route frameworks done. Next options: Vapor / component-node frameworks / Drupal, or build the Rocket `routes![]` extractor (→~94%).
+### Session — Rocket routes![] extractor (2026-06-05, commit 6d214cd)
+- **User:** "build the Rocket routes! extractor".
+- **Claude:** probed the tree-sitter AST — `routes![a::b::h, …]` parses as `macro_invocation > token_tree` of FLAT raw tokens (`identifier` / `::` / `,`), so the handler paths were invisible to the call walker. Built `extractRustRouteMacro` (tree-sitter.ts, called from `visitFunctionBody`): for a `routes`/`catchers` macro, walk the token-tree, group `identifier` runs between commas into `::`-joined paths, emit a `references` edge each; the existing Rust path resolver (self-relative + multi-segment fixes already shipped) links them to the handler fns. Rocket 68.8%→**93.8%** (all 4 `routes/*.rs` covered; only lib.rs root left). No control regression, false edges 0, nodes unchanged (edges only), regression test fails without it. Committed 6d214cd.
+- **Outcome:** Rocket effectively at ceiling. Handler names are explicit in source → precise static extraction, not a heuristic. Remaining route-front: Vapor (Swift), component-node frameworks (SvelteKit/React Router/Vue-Nuxt), Drupal — or ship the 34-commit branch.
+### Session — Vapor (2026-06-06, commit bb7659e)
+- **User:** "vapor next".
+- **Claude:** measured vapor-til (canonical Vapor tutorial app, kodecocodes) 85.7% + penny-bot (real prod, 166 files) 73.2%. vapor-til zeros: Package.swift (SPM build manifest → faircov excl), Public/cookies.js (static client asset → faircov excl), and AcronymCategoryPivot.swift = a REAL miss. Audited: the pivot model is referenced ONLY via `@Siblings(through: AcronymCategoryPivot.self, …)` in Acronym/Category — a metatype arg inside a property-wrapper `attribute` whose ARGS were never walked (only the wrapper type `Siblings` + the property's declared type were captured). Fix: route the property's attribute-arg subtree through `extractStaticMemberRef` (already handles Swift `Type.self` navigation, self-filters to capitalized receivers, skips `\.$keypath`). vapor-til 94.7%→**100%**. Clean A/B: vapor-til +1, Alamofire neutral (44/50); false edges 0; suite 1182. Committed bb7659e + regression test. penny-bot 73.2% characterized (serverless/DI: Lambda entries + exports barrels + DI/serialization/extension frontiers) — NOT chased (not the canonical pattern).
+- **Outcome:** Vapor DONE; import/aggregator confirmed in a 4th language family (Swift) via a real Fluent fix. Remaining route-front: component-node frameworks (SvelteKit/React Router/Vue-Nuxt), Drupal — or ship the 35-commit branch.
+### Session — SvelteKit (2026-06-06, no commit — characterization)
+- **User:** "component-node framework next".
+- **Claude:** measured sveltejs/realworld (official SvelteKit app) → 35.9% raw (14/39). Audited: ALL 25 zeros are SvelteKit file-convention files (`+page`/`+layout`/`+error`/`+server`/`hooks`) — loaded by the framework BY PATH, no in-repo caller. Probed + CONFIRMED the engine already resolves every `.svelte` component import (ArticlePreview←ArticleList, Nav←+layout, ListErrors←4 pages; imports+references+calls all resolve) — NO component is a zero, so NO engine miss (first framework needing none). Added SvelteKit convention-entry patterns to faircov (methodology-aligned, like route handlers) → 14/14 = **100% fair** of the coverable core. Confirmed the one framework-mediated gap: `+page.server.js` `load` → `+page.svelte` `data` is NOT statically linked (runtime `data` prop).
+- **Outcome:** the component-node shape is "file-convention entries (the majority) + a fully-covered component/lib core" — the engine handles it as-is. No commit (nothing to fix). OFFERED a SvelteKit convention synthesizer (sibling `+page.server.js`↔`+page.svelte` link, like Rocket routes!) for impact granularity — not built. Branch stays 35 commits. Next: React Router (config-based variant — likely MORE covered) / Nuxt (file-convention, SvelteKit-like) / Drupal, or ship.
+### Session — SvelteKit load→page synthesizer (2026-06-06, commit 3ea03e5)
+- **User:** "lets fix svelte with the synthesizer, then we can move onto react router".
+- **Claude:** probed the graph: `+page.svelte`→`component` node, `+page.server.js`→`load`/`actions` function nodes, pages pair with sibling loaders in the SAME dir. Built `svelteKitLoadEdges` (callback-synthesizer.ts, wired into `synthesizeCallbackEdges` after `vueTemplateEdges`): for each `+page`/`+layout.svelte`, link its `component` → the `load`/`actions` in `<dir>/<prefix>.server.{ts,js}` / `<dir>/<prefix>.{ts,js}` (same dir only), direction page→load so `getImpactRadius(load)` surfaces the page; provenance heuristic. Verified on sveltejs/realworld: 19 links, **0 cross-dir mislinks**, false edges 0, nodes unchanged; `getImpactRadius(login load)` now returns login/+page.svelte. Committed 3ea03e5 + regression test (incl. a does-not-cross-routes guard). Suite 1183.
+- **Outcome:** SvelteKit fully done (component coverage 100% + the loader→page impact link). Next per the user: React Router (the config-based component-node variant).
+### Session — React Router (2026-06-06, no commit — characterization)
+- **User:** "...then we can move onto react router" (continued from the svelte synthesizer).
+- **Claude:** measured gothinkster react-redux-realworld (38 files, react-router v4/v5) → **100%** (29/29), false edges 0. The CONFIG-based component-node sub-shape: route components are NAMED in source (`<Route path='/login' component={Login}/>`), so App.js imports+references each → all resolve. Verified Login/Editor/Profile covered BY App.js's route config. Only `index.js` (CRA entry) + 8 anonymous-default reducers (0 named symbols → barrels) excluded. NO engine miss. (Modern v6/v7 `element={<X/>}` + data-router `{element, loader}` are also source-referenced → same conclusion.)
+- **Outcome:** React Router DONE. Component-node category now fully characterized — two sub-shapes (config-based React Router = 100% raw; file-convention SvelteKit = fair-100% + synthesizer), both handled by the engine. No commit (nothing to fix). Remaining: Nuxt (Vue, file-convention — would mirror SvelteKit), Drupal (PHP), or ship the 36-commit branch.
+### Session — Nuxt (2026-06-06, commit 1dec765)
+- **User:** "nuxt next".
+- **Claude:** measured nuxt/movies (official Nuxt 3 demo, 42 .vue + 37 ts) → 47.6% raw. Audited zeros: pages/app.vue/error.vue/server = file-convention entries (→ faircov Nuxt exclusions); NESTED components (`components/media/*`, `components/carousel/*`) = a REAL miss. Root cause: Nuxt auto-imports a nested component by DIR-PREFIX (`media/Card.vue` → `<MediaCard/>`), but the node is named `Card`; the synth `vueTemplateEdges` only matched KEBAB tags, and the extractor's PascalCase ref name-matched `MediaCard`→nothing. Fixed: added a PascalCase-tag regex to vueTemplateEdges + a `nuxtComponentName` map (`media/Card.vue`→`MediaCard`, Nuxt dir de-dup). nuxt/movies 47.6%→**93.5%** (+9 nested components). Vue-only (gated to .vue), false edges 0, nodes unchanged, suite 1183, regression test. Committed 1dec765. 2 residual zeros are genuine frontiers (unused `<CarouselItems>`, unimported constants). composables (`useTmdb()`) already worked.
+- **Outcome:** Nuxt DONE. The two file-convention component frameworks DIFFER: SvelteKit's imports resolve as-is (no fix), Nuxt's dir-prefix auto-import needed a fix. Only **Drupal** (PHP) left unmeasured — or ship the 37-commit branch.
+### Session — Drupal (2026-06-06, no commit — characterization, finishes the sweep)
+- **User:** "drupal to finish the sweep".
+- **Claude:** measured the `token` contrib module (58 PHP, modern Drupal 11) → 57.1% raw. Audited: `drupal.ts` ALREADY resolves `*.routing.yml`→controller (TokenTreeController covered via the route ref) and PHP class refs work; the zeros are ALL genuine reflection/convention — JS libraries, DI services (`TreeBuilder` = `@token.tree_builder` in services.yml, `TokenFieldRender`), a dynamically-routed controller (`TokenDevelController` via `RouteSubscriber`), plugins (`Element/`, `Plugin/Derivative/`), Drush commands, `*ServiceProvider`, `.install` hooks, field-plugin `MenuLinkFieldItemList`. NO simple fixable miss (verified TokenDevelController isn't in any routing.yml — genuinely dynamic). Added faircov Drupal convention-entry + JS-library exclusions → **78.9% fair** (4 residual zeros = DI services + dynamic route + field plugin). Token uses modern `#[Hook('...')]` attribute OOP hooks (a drupal.ts TODO). NO commit (the levers — services.yml DI / plugin annotations / `#[Hook]` — are large per-mechanism features, same don't-chase-95% stance as ASP.NET/Django/Spring).
+- **Outcome:** **THE SWEEP IS COMPLETE.** Every README framework measured: import/aggregator + config-based-component + file-convention-component reach ceiling (95–100%) via 6 engine fixes; convention/reflection/actor frameworks (ASP.NET/Spring/Drupal/Django/actix) sit at a genuine sub-95% reflection ceiling. Branch 37 commits, ready to ship. Next: open the PR, or the static-member-pass TS/JS/Python lever.
+### Session — static-member pass for TS/JS/Python: measured & rejected (2026-06-06, commit e7b86df)
+- **User:** "extending the static-member/const value-read pass to TS/JS/Python."
+- **Claude:** implemented (added `member_expression`/`attribute` to `MEMBER_ACCESS_TYPES` + ts/js/python to `STATIC_MEMBER_LANGS`), then ran a clean A/B (same faircov, engine ±change) on excalidraw (TS/React, the retrieval-perf canary) + requests (Python). Result: **0 coverage gain** on BOTH (excalidraw 94.3%→94.3%, requests 100%→100%) because the import edge already covers every `Type.MEMBER` read (in import-based languages you must import the type first — the static read is redundant), while adding **+1813 edges / +2448 `references` on excalidraw** (all pointing at already-covered types — pure retrieval-graph noise). REVERTED the functional change; enhanced the `STATIC_MEMBER_LANGS` comment with the measured finding so it isn't re-attempted. Committed e7b86df (doc-only).
+- **Outcome:** the standing "one big cross-language lever" is CLOSED — the deferral was correct, now proven with data. The branch is 38 commits; everything actionable is done. **Recommended next: open the PR to main.**
+### Session — the 4 niche README languages (2026-06-06, commits 4155609 / 2f57119 / 2f30a3b)
+- **User:** confirmed only 4 README "Full support" languages lacked coverage validation (Lua/Luau/Liquid/Pascal); "knock out those 4 to close it out."
+- **Claude:** measured + fixed each. **Lua** (telescope) 31.6% + **Luau** (Fusion) 12.5%: NO `require()` module resolver existed — added `resolveLuaRequire` (dotted `a.b.c`→file + instance-path leaf, path-suffix match w/ same-dir preference; confidence 0.9 so it beats the import-node self-match) → Lua **84.2%**, Luau **92.2%** (4155609). **Liquid** (Dawn) 39.1%: snippet `{% render %}` already worked, but Shopify OS 2.0 sections are referenced from JSON templates (`templates/*.json` `"type"`), which weren't even indexed — made Shopify JSON indexable (isSourceFile + detectLanguage) + a Liquid-extractor JSON branch emitting `sections/<type>.liquid` refs (incl. nested `templates/customers/`) → **73.8%** (2f57119). **Pascal** (PascalCoin) 73.0%: `uses`-resolution ALREADY worked; added a `.dfm`/`.fmx`↔`.pas` form-code-behind synthesizer → **75.7%** (2f30a3b). Each: gated to its language, false edges 0, regression test fails without the fix, suite green (1187).
+- **Outcome:** **FULL README PARITY** — all 22 "Full support" languages + all 14 frameworks now have coverage validation. Branch 41 commits, ready to ship. 3 new generalizable resolvers (Lua/Luau require, Shopify-JSON sections, Delphi form pairing). Only remaining work is optional reflection/DI levers + the PR.
diff --git a/.claude/skills/add-lang/SKILL.md b/.claude/skills/add-lang/SKILL.md
index 0e107a3e6..37cbdce55 100644
--- a/.claude/skills/add-lang/SKILL.md
+++ b/.claude/skills/add-lang/SKILL.md
@@ -189,8 +189,8 @@ Read each `parse-run.mjs` summary printed by `run-all.sh`: tool calls, file
 - **CHANGELOG.md**: add an `## [Unreleased]` section at the top (above the
   latest version) with `### Added` → a user-perspective bullet, e.g.
   *"CodeGraph now indexes **<Lang>** (`.ext`) — functions, classes, imports, and
-  call edges."* If `## [Unreleased]` already exists, append under it. (`/publish`
-  folds this into the next versioned block at release time.)
+  call edges."* If `## [Unreleased]` already exists, append under it. (It's
+  folded into the next versioned block at release time.)
 
 ### Step 10 — Report (do NOT commit)
 
@@ -204,8 +204,8 @@ Summarize for review:
 - **Gaps / follow-ups** (node types not yet mapped, resolution edges missing,
   framework routes, etc.).
 
-Hand the changes to the user. **Do not** run `git commit`/`push`,
-`npm publish`, or `scripts/release.sh`.
+Hand the changes to the user. **Do not** run `git commit`/`push` or publish —
+releases go through the GitHub Actions Release workflow.
 
 ## Notes
 - The A/B spawns real **paid** `claude -p` runs (opus, `--max-budget-usd`),
diff --git a/.claude/skills/agent-eval/corpus.json b/.claude/skills/agent-eval/corpus.json
index 3dcc87524..2cfedac4f 100644
--- a/.claude/skills/agent-eval/corpus.json
+++ b/.claude/skills/agent-eval/corpus.json
@@ -11,7 +11,8 @@
   "Go": [
     { "name": "cobra", "repo": "https://github.com/spf13/cobra", "size": "Small", "files": "~50", "question": "How does cobra parse commands and flags?" },
     { "name": "gin", "repo": "https://github.com/gin-gonic/gin", "size": "Medium", "files": "~150", "question": "How does gin route requests through its middleware chain?" },
-    { "name": "terraform", "repo": "https://github.com/hashicorp/terraform", "size": "Large", "files": "~4000", "question": "How does Terraform build and walk the resource dependency graph?" }
+    { "name": "terraform", "repo": "https://github.com/hashicorp/terraform", "size": "Large", "files": "~4000", "question": "How does Terraform build and walk the resource dependency graph?" },
+    { "name": "cosmos-sdk", "repo": "https://github.com/cosmos/cosmos-sdk", "size": "Large", "files": "~5000", "question": "How does a bank module MsgSend message reach the account balance update? Trace the cross-module call path from the bank keeper's Send handler through to the account/balance store update." }
   ],
   "Python": [
     { "name": "click", "repo": "https://github.com/pallets/click", "size": "Small", "files": "~60", "question": "How does click parse command-line arguments into commands?" },
@@ -69,5 +70,29 @@
     { "name": "Knit", "repo": "https://github.com/Sleitnick/Knit", "size": "Small", "files": "~10", "question": "How does Knit register services and expose them to clients?" },
     { "name": "vide", "repo": "https://github.com/centau/vide", "size": "Small", "files": "~40", "question": "How does vide track reactive sources and re-run effects when state changes?" },
     { "name": "Fusion", "repo": "https://github.com/dphfox/Fusion", "size": "Medium", "files": "~115", "question": "How does Fusion build and update its reactive UI graph from state objects?" }
+  ],
+  "Objective-C": [
+    { "name": "Masonry", "repo": "https://github.com/SnapKit/Masonry", "size": "Small", "files": "~50", "question": "How does Masonry build and activate Auto Layout constraints from its block DSL?" },
+    { "name": "FMDB", "repo": "https://github.com/ccgus/fmdb", "size": "Medium", "files": "~80", "question": "How does FMDB execute a prepared SQL statement and bind parameters?" },
+    { "name": "SDWebImage", "repo": "https://github.com/SDWebImage/SDWebImage", "size": "Large", "files": "~400", "question": "How does SDWebImage download, cache, and decode an image for a UIImageView?" }
+  ],
+  "Mixed iOS (Swift+ObjC)": [
+    { "name": "Charts", "repo": "https://github.com/danielgindi/Charts", "size": "Small", "files": "~270", "question": "How does the ChartsDemo ObjC demo controller drive the Swift Charts library to animate and notify a data update?" },
+    { "name": "realm-swift", "repo": "https://github.com/realm/realm-swift", "size": "Medium", "files": "~370", "question": "How does a Swift `Realm.write { realm.add(obj) }` reach the Objective-C persistence layer?" },
+    { "name": "wikipedia-ios", "repo": "https://github.com/wikimedia/wikipedia-ios", "size": "Large", "files": "~1700", "question": "How does tapping a search result reach the article-fetch network call across the Swift / ObjC boundary?" }
+  ],
+  "React Native (legacy bridge + TurboModule)": [
+    { "name": "@react-native-async-storage", "repo": "https://github.com/react-native-async-storage/async-storage", "size": "Small", "files": "~60", "question": "How does `setItem` in JS reach the native `legacy_multiSet` implementation?" },
+    { "name": "react-native-svg", "repo": "https://github.com/software-mansion/react-native-svg", "size": "Medium", "files": "~700", "question": "How does a JS `Svg.getTotalLength(...)` reach the iOS / Android native implementation via TurboModule?" },
+    { "name": "react-native-firebase", "repo": "https://github.com/invertase/react-native-firebase", "size": "Large", "files": "~1100", "question": "How does a native iOS push notification reach the JS `messaging().onMessage(...)` listener?" }
+  ],
+  "Expo Modules": [
+    { "name": "expo-haptics", "repo": "https://github.com/expo/expo/tree/main/packages/expo-haptics", "size": "Small", "files": "~15", "question": "How does `Haptics.notificationAsync(...)` in JS reach `UINotificationFeedbackGenerator` in the Swift Module?" },
+    { "name": "expo-camera", "repo": "https://github.com/expo/expo/tree/main/packages/expo-camera", "size": "Medium", "files": "~70", "question": "How does a JS `CameraView.takePictureAsync(options)` reach the native AVCaptureSession / CameraDevice call?" }
+  ],
+  "React Native Fabric (view components)": [
+    { "name": "react-native-segmented-control", "repo": "https://github.com/react-native-segmented-control/segmented-control", "size": "Small", "files": "~25", "question": "How does JSX `<SegmentedControl onChange={cb}/>` reach the native onChange handler on iOS/Android?" },
+    { "name": "react-native-screens", "repo": "https://github.com/software-mansion/react-native-screens", "size": "Medium", "files": "~1200", "question": "How does JSX `<ScreenStack>` reach the native RNSScreenStackView component?" },
+    { "name": "react-native-skia", "repo": "https://github.com/Shopify/react-native-skia", "size": "Large", "files": "~1000", "question": "How does a `<SkiaPictureView/>` JSX usage reach the iOS / Android native renderer?" }
   ]
 }
diff --git a/.claude/skills/publish/SKILL.md b/.claude/skills/publish/SKILL.md
deleted file mode 100644
index 84c6d4b3e..000000000
--- a/.claude/skills/publish/SKILL.md
+++ /dev/null
@@ -1,136 +0,0 @@
----
-name: publish
-description: Publishes a new minor or major release of this npm package (codegraph). Reads the latest version from npm, generates a user-perspective CHANGELOG entry from commits since the last tag, bumps package.json, publishes to npm, and creates the matching GitHub release. Use when the user runs /publish or asks to cut, ship, or publish a release / new version.
----
-
-# Publish a release
-
-Cut a **minor or major** release: generate the changelog, bump, publish to npm, and create the GitHub release. Patch releases are intentionally not offered here.
-
-This skill performs the actual publish (npm publish, git push, GitHub release) — that is the whole point of invoking it, so the general "hand the user the commands" rule does **not** apply inside `/publish`. The **confirmation gate in Step 5 is the safeguard**: never run a step past it without explicit approval.
-
-Run from the repo root.
-
-## Workflow
-
-Copy this checklist and work through it in order:
-
-```
-- [ ] 1. Preflight: branch, sync, auth
-- [ ] 2. Read base version from npm, compute candidates
-- [ ] 3. Ask the user: minor or major
-- [ ] 4. Generate the CHANGELOG entry from commits since the last tag
-- [ ] 5. CONFIRMATION GATE — show changelog + plan, get explicit approval
-- [ ] 6. Write CHANGELOG.md, bump, build
-- [ ] 7. Commit + push
-- [ ] 8. npm publish
-- [ ] 9. scripts/release.sh (GitHub release)
-- [ ] 10. Verify on the npm registry
-```
-
-### Step 1 — Preflight
-
-```bash
-git rev-parse --abbrev-ref HEAD   # expect: main
-git fetch origin
-git status --porcelain            # working tree should be clean
-git rev-list --left-right --count origin/main...HEAD   # "<behind> <ahead>"
-npm whoami                        # npm auth (publish will fail without it)
-gh auth status                    # gh auth (release.sh needs it)
-```
-
-- If not on `main`, stop and ask the user to confirm releasing from this branch.
-- If behind origin, `git pull --ff-only` so the final push is a fast-forward.
-- If the tree has **unrelated** uncommitted changes, stop and ask — the release commit only stages 3 files, but a dirty tree usually means something's mid-flight.
-- If `npm whoami` or `gh auth status` fails, stop and tell the user to authenticate.
-
-### Step 2 — Base version + candidates
-
-The latest **published** version is the source of truth, not local `package.json`.
-
-```bash
-PKG=$(node -p "require('./package.json').name")
-BASE=$(npm view "$PKG" version)
-node -e "const [a,b]=process.argv[1].split('.').map(Number);console.log('minor ->',a+'.'+(b+1)+'.0');console.log('major ->',(a+1)+'.0.0')" "$BASE"
-```
-
-Note if local `package.json` differs from `BASE` (an unpublished bump) — surface it, but still base the new version on npm.
-
-### Step 3 — Ask minor or major
-
-Use the **AskUserQuestion** tool with the two computed candidates as options (show the resulting version in each label, e.g. "minor → 0.8.0"). Set the new version from the answer.
-
-### Step 4 — Generate the changelog entry
-
-```bash
-LAST=$(git describe --tags --abbrev=0 --match 'v*' 2>/dev/null)
-git log --no-merges "${LAST}..HEAD" --pretty=format:'%h %s'
-```
-
-Read the commit subjects; for any whose user impact is unclear, inspect the diff (`git show <hash>` or `git diff "${LAST}..HEAD" -- <path>`). Then **write the entry yourself** following the repo's conventions in `CLAUDE.md` → "Writing changelog entries":
-
-- Header: `## [X.Y.Z] - YYYY-MM-DD` (get the date with `date +%F`).
-- Group under `### Added`, `### Changed`, `### Fixed`, `### Removed`, `### Deprecated`, `### Security` — **omit empty sections**.
-- Write from the **user's perspective** (observable capability/symptom), not the implementation. Collapse noisy commits ("fix typo", "address review") into the feature they belong to or drop them.
-- Plan the bottom link reference: `[X.Y.Z]: https://github.com/colbymchenry/codegraph/releases/tag/vX.Y.Z`.
-
-Do not write to any file yet — draft it for review first.
-
-### Step 5 — CONFIRMATION GATE
-
-Show the user, in chat:
-1. The new version (`BASE` → `X.Y.Z`, minor/major).
-2. The full drafted changelog entry.
-3. The exact actions Steps 6–9 will take (commit + push + npm publish + GitHub release).
-
-Then **STOP**. Proceed only on explicit approval ("yes" / "proceed"). If the user requests prose changes, revise the draft and re-show. Do not run any command below until approved.
-
-### Step 6 — Write changelog, bump, build
-
-1. Use the **Edit** tool to insert the drafted `## [X.Y.Z]` block at the **top** of `CHANGELOG.md` (under the intro, above the previous version), and add the link reference with the other `[x.y.z]:` links at the bottom.
-2. Bump (also updates `package-lock.json`; `--allow-same-version` keeps re-runs safe):
-   ```bash
-   npm version X.Y.Z --no-git-tag-version --allow-same-version
-   ```
-3. Build (fail fast before any push/publish):
-   ```bash
-   npm run build
-   ```
-
-### Step 7 — Commit + push
-
-`release.sh` tags HEAD, so the bump must be committed first.
-
-```bash
-git add package.json package-lock.json CHANGELOG.md
-git commit -m "release: X.Y.Z"
-git push
-```
-
-### Step 8 — Publish to npm
-
-```bash
-npm publish --access public
-```
-
-### Step 9 — GitHub release
-
-`scripts/release.sh` reads the `## [X.Y.Z]` block from CHANGELOG.md, tags `vX.Y.Z`, pushes the tag, and creates the GitHub release. It is idempotent.
-
-```bash
-./scripts/release.sh
-```
-
-### Step 10 — Verify
-
-Confirm against the **registry**, not the website (the website caches):
-
-```bash
-npm view "$PKG" version   # must equal X.Y.Z
-```
-
-Report the release URL (`scripts/release.sh` prints it) and the published version.
-
-## If something fails midway
-
-Re-running is safe: `npm version --allow-same-version` no-ops if already bumped, `git commit` skips if nothing's staged (check `git diff --cached --quiet`), `git push` no-ops if up to date, and `scripts/release.sh` skips tag/release steps already done. Re-run from the failed step.
diff --git a/.cursor/rules/codegraph.mdc b/.cursor/rules/codegraph.mdc
index 3f23cf6b6..00a3f8152 100644
--- a/.cursor/rules/codegraph.mdc
+++ b/.cursor/rules/codegraph.mdc
@@ -16,6 +16,7 @@ Use codegraph for **structural** questions — what calls what, what would break
 | "Where is X defined?" / "Find symbol named X" | `codegraph_search` |
 | "What calls function Y?" | `codegraph_callers` |
 | "What does Y call?" | `codegraph_callees` |
+| "How does X reach/become Y? / trace the flow from X to Y" | `codegraph_trace` (one call = the whole path, incl. callback/React/JSX dynamic hops) |
 | "What would break if I changed Z?" | `codegraph_impact` |
 | "Show me Y's signature / source / docstring" | `codegraph_node` |
 | "Give me focused context for a task/area" | `codegraph_context` |
@@ -25,12 +26,12 @@ Use codegraph for **structural** questions — what calls what, what would break
 
 ### Rules of thumb
 
-- **Answer directly — don't delegate exploration.** For "how does X work" / architecture / trace questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer.
+- **Answer directly — don't delegate exploration.** For "how does X work" / architecture questions, answer with 2-3 codegraph calls: `codegraph_context` first, then ONE `codegraph_explore` for the source of the symbols it surfaces. For a specific **flow** ("how does X reach Y") start with `codegraph_trace` from→to — one call returns the whole path with dynamic hops bridged — then ONE `codegraph_explore` for the bodies; don't rebuild the path with `codegraph_search` + `codegraph_callers`. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer.
 - **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
 - **Don't grep first** when looking up a symbol by name. `codegraph_search` is faster and returns kind + location + signature in one call.
 - **Don't chain `codegraph_search` + `codegraph_node`** when you just want context — `codegraph_context` is one call.
 - **Don't loop `codegraph_node` over many symbols** — one `codegraph_explore` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.
-- **Index lag**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn.
+- **Index lag — check the staleness banner, don't guess a wait.** When a codegraph response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Files NOT in that banner are fresh and codegraph is authoritative for them. `codegraph_status` also lists pending files under "Pending sync".
 
 ### If `.codegraph/` doesn't exist
 
diff --git a/.github/workflows/deploy-site.yml b/.github/workflows/deploy-site.yml
new file mode 100644
index 000000000..b66dde951
--- /dev/null
+++ b/.github/workflows/deploy-site.yml
@@ -0,0 +1,43 @@
+name: Deploy site to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - '.github/workflows/deploy-site.yml'
+  workflow_dispatch:
+
+# Allow GITHUB_TOKEN to deploy to Pages and verify the deployment origin.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# One deploy at a time; let an in-progress run finish.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Build with Astro
+        uses: withastro/action@v3
+        with:
+          path: site
+          node-version: 22
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 000000000..88bce26a4
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,204 @@
+name: Release
+
+# Manually triggered ("Run workflow"). On trigger it:
+#   1. reads the version from package.json,
+#   2. promotes `## [Unreleased]` content into `## [<version>]` in
+#      CHANGELOG.md (and commits + pushes that change back to main), so
+#      the published release notes are never sparse just because the
+#      maintainer didn't pre-stage the [<version>] block by hand,
+#   3. builds a self-contained bundle for every platform (one runner — there's no
+#      native compilation, so cross-packaging is fine),
+#   4. creates the GitHub Release (tag v<version>) with all archives, using the
+#      release notes from CHANGELOG.md,
+#   5. publishes the npm thin-installer (shim + per-platform packages).
+#
+# Before triggering: bump package.json. CHANGELOG.md entries can live under
+# `## [Unreleased]` — step 2 takes care of moving them. Set the NPM_TOKEN secret.
+on:
+  workflow_dispatch: {}
+
+permissions:
+  contents: write   # create the GitHub Release + tag, push the CHANGELOG promote
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Default checkout is detached at a SHA; we need an actual branch
+          # so the CHANGELOG-promote commit knows where to push.
+          ref: ${{ github.ref }}
+          # Authenticate as the maintainer (admin), not as github-actions[bot].
+          # The "Require PR approval for main branch" ruleset only lets the
+          # Admin repo role bypass — and GitHub blocks adding the GitHub
+          # Actions integration to bypass_actors on user-owned (non-org)
+          # repos with "Actor GitHub Actions integration must be part of
+          # the ruleset source or owner organization." So the auto-promote
+          # and auto-sync `git push origin HEAD:main` steps below both fail
+          # under the default GITHUB_TOKEN. Using a fine-grained PAT owned
+          # by the admin makes the push go through cleanly. Set the
+          # RELEASE_PAT secret with: contents:write on this repo, no other
+          # scopes. Rotate per your token policy; the workflow only runs
+          # on manual dispatch so the blast radius is small.
+          token: ${{ secrets.RELEASE_PAT }}
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - name: Sync package-lock.json if version drifted
+        # When the maintainer bumps the version on package.json only — for
+        # example via a GitHub web-UI edit — `npm ci` would refuse to run
+        # with `EUSAGE: npm ci can only install packages when your
+        # package.json and package-lock.json … are in sync`. This step
+        # rewrites just the lock-file's version fields (top-level + the
+        # `packages.""` entry) to match package.json, then auto-commits
+        # and pushes the result so on-disk truth on `main` stays
+        # consistent. Idempotent: if the lock file already matches, no
+        # commit is made.
+        run: |
+          set -euo pipefail
+          PKG_V=$(node -p "require('./package.json').version")
+          LOCK_V=$(node -p "require('./package-lock.json').version")
+          if [ "$PKG_V" = "$LOCK_V" ]; then
+            echo "package-lock.json already at $PKG_V — nothing to sync."
+            exit 0
+          fi
+          echo "Lock-file version drift: lock=$LOCK_V, package=$PKG_V. Syncing."
+          # `--package-lock-only` rewrites only the lock file, doesn't
+          # touch node_modules or actually install anything. Cheap.
+          npm install --package-lock-only --ignore-scripts
+          # Sanity: lockfile should now report the package version.
+          NEW_LOCK_V=$(node -p "require('./package-lock.json').version")
+          if [ "$NEW_LOCK_V" != "$PKG_V" ]; then
+            echo "::error::lock-file still at $NEW_LOCK_V after sync attempt; expected $PKG_V"; exit 1
+          fi
+          if git diff --quiet -- package-lock.json; then
+            echo "lock file unchanged after sync? bailing"; exit 1
+          fi
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add package-lock.json
+          git commit -m "release: sync package-lock.json to ${PKG_V}" -m "[skip ci] Auto-generated by Release workflow."
+          git push origin "HEAD:${GITHUB_REF#refs/heads/}"
+
+      - run: npm ci
+      - name: Ensure zip/unzip
+        run: sudo apt-get update -qq && sudo apt-get install -y -qq zip unzip
+
+      - name: Resolve version
+        id: ver
+        run: echo "version=$(node -p "require('./package.json').version")" >> "$GITHUB_OUTPUT"
+
+      - name: Promote [Unreleased] → [<version>] in CHANGELOG.md
+        # Idempotent: a no-op if [Unreleased] is empty OR if the previous
+        # run already moved everything. Auto-commit + push the change back
+        # so the version block on main is the source of truth going
+        # forward (and so subsequent extract-release-notes.mjs calls
+        # surface the full content even if this run is re-triggered).
+        run: |
+          set -euo pipefail
+          V="${{ steps.ver.outputs.version }}"
+          before=$(git rev-parse HEAD)
+          node scripts/prepare-release.mjs "$V"
+          if git diff --quiet -- CHANGELOG.md; then
+            echo "CHANGELOG.md unchanged — nothing to commit."
+          else
+            git config user.name  "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git add CHANGELOG.md
+            git commit -m "docs(changelog): promote [Unreleased] into [${V}]" -m "[skip ci] Auto-generated by Release workflow."
+            # Push to the branch the workflow was triggered on (main).
+            git push origin "HEAD:${GITHUB_REF#refs/heads/}"
+          fi
+
+      - name: Build all platform bundles
+        run: |
+          for t in darwin-arm64 darwin-x64 linux-x64 linux-arm64 win32-x64 win32-arm64; do
+            bash scripts/build-bundle.sh "$t"
+          done
+          ls -lh release
+
+      - name: Generate SHA256SUMS
+        # Published as a release asset; the npm launcher verifies downloaded
+        # bundles against it (basenames only, so its path.basename match works).
+        run: |
+          ( cd release && sha256sum codegraph-* > SHA256SUMS )
+          cat release/SHA256SUMS
+
+      - name: Release notes from CHANGELOG.md
+        # The [<version>] block was guaranteed-populated by the
+        # "Promote" step above, so the [Unreleased] fallback should
+        # never be needed in practice. Kept for defense-in-depth.
+        run: |
+          V="${{ steps.ver.outputs.version }}"
+          node scripts/extract-release-notes.mjs "$V" > notes.md 2>/dev/null \
+            || node scripts/extract-release-notes.mjs Unreleased > notes.md 2>/dev/null || true
+          if [ ! -s notes.md ]; then
+            echo "::error::No release notes in CHANGELOG.md for [$V] or [Unreleased]."
+            exit 1
+          fi
+          echo "----- release notes -----"; cat notes.md
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="v${{ steps.ver.outputs.version }}"
+          # Idempotent: create the release once, otherwise (re-run) refresh assets.
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            gh release upload "$TAG" release/codegraph-* release/SHA256SUMS --clobber
+          else
+            gh release create "$TAG" release/codegraph-* release/SHA256SUMS --title "$TAG" --notes-file notes.md
+          fi
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          V="${{ steps.ver.outputs.version }}"
+          bash scripts/pack-npm.sh "$V"
+          # Platform packages first, then the main shim (which depends on them).
+          # Skip any already on the registry so a re-run only fills in gaps.
+          for dir in release/npm/codegraph-* release/npm/main; do
+            name=$(node -p "require('./$dir/package.json').name")
+            if npm view "$name@$V" version >/dev/null 2>&1; then
+              echo "skip $name@$V (already published)"
+            else
+              echo "publishing $name@$V"
+              ( cd "$dir" && npm publish --access public )
+            fi
+          done
+
+      - name: Verify every package is actually on the registry
+        run: |
+          V="${{ steps.ver.outputs.version }}"
+          # npm publish can print success without persisting; confirm against the
+          # registry (with retries for propagation) so green means really shipped.
+          for dir in release/npm/codegraph-* release/npm/main; do
+            name=$(node -p "require('./$dir/package.json').name")
+            ok=
+            for i in 1 2 3 4 5 6; do
+              if npm view "$name@$V" version >/dev/null 2>&1; then ok=1; break; fi
+              echo "waiting for $name@$V to appear ($i)…"; sleep 10
+            done
+            [ -n "$ok" ] || { echo "::error::$name@$V never appeared on the registry"; exit 1; }
+            echo "verified $name@$V"
+          done
+
+      - name: Sync packages to npmmirror
+        # npmmirror/cnpm mirror lazily and frequently never pull the per-platform
+        # optionalDependencies on their own, so `npm i` there fails with
+        # "no prebuilt bundle" (issue #303). Nudge a sync now so mirror users get
+        # the bundle without waiting. Best-effort — the launcher also self-heals
+        # from GitHub Releases — so a mirror hiccup never fails the release.
+        continue-on-error: true
+        run: |
+          for dir in release/npm/codegraph-* release/npm/main; do
+            name=$(node -p "require('./$dir/package.json').name")
+            enc=$(node -p "encodeURIComponent(require('./$dir/package.json').name)")
+            echo "sync $name"
+            curl -s -X PUT "https://registry.npmmirror.com/-/package/$enc/syncs" || true
+            echo
+          done
diff --git a/.gitignore b/.gitignore
index 7c154ae1d..da6c8ef6e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,6 +39,10 @@ npm-debug.log*
 
 # Local Claude settings
 .claude/settings.local.json
+.claude/scheduled_tasks.lock
+
+# Parallels Windows VM SSH/connection config (local machine, see CLAUDE.md)
+.parallels
 
 # CodeGraph data directories (in test projects)
 .codegraph/
@@ -49,3 +53,13 @@ test_frameworks
 test-languages/
 
 nul
+release/
+
+.antigravitycli/
+
+# Local-only: browser-based tmux session launcher (see tmux-web/README.md)
+tmux-web/
+
+assets/__pycache__/
+
+assets/generate-waitlist.py
diff --git a/BUNDLING.md b/BUNDLING.md
new file mode 100644
index 000000000..dc21ab531
--- /dev/null
+++ b/BUNDLING.md
@@ -0,0 +1,74 @@
+# Distribution: self-contained bundles
+
+CodeGraph ships a **vendored Node runtime** alongside the app. Because Node 22.5+
+has a built-in real SQLite (`node:sqlite`, with WAL + FTS5), bundling Node means:
+
+- **No native build** — `better-sqlite3` is gone, so there are zero native addons
+  to compile or rebuild.
+- **No wasm fallback** — and therefore no more `database is locked` (issue #238).
+- **No Node-version dependence** — the app always runs on the bundled Node,
+  whatever the user has (or doesn't have) installed.
+
+## What's in a bundle
+
+Built by [`scripts/build-bundle.sh`](scripts/build-bundle.sh) — one archive per
+platform, identical recipe (only the Node download differs):
+
+```
+codegraph-<target>/
+  node | node.exe          # official Node runtime for <target>
+  lib/
+    dist/                  # compiled app (+ tree-sitter .wasm grammars, schema.sql)
+    node_modules/          # production deps only (pure JS / wasm — portable)
+  bin/
+    codegraph | codegraph.cmd   # launcher → runs the bundled Node with the app
+```
+
+Targets: `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `win32-x64`,
+`win32-arm64`. Unix targets produce `.tar.gz` (shell launcher); Windows produces
+`.zip` (`node.exe` + a `.cmd` launcher).
+
+```bash
+scripts/build-bundle.sh linux-x64            # -> release/codegraph-linux-x64.tar.gz
+scripts/build-bundle.sh win32-x64            # -> release/codegraph-win32-x64.zip
+```
+
+Because dropping better-sqlite3 left **zero native addons**, building a bundle is
+pure file-packaging — **any** target builds on **any** OS (the whole matrix builds
+on one Linux runner). Cross-compilation isn't a concern; only *run-testing* a
+bundle needs the target platform (or emulation, e.g. `docker run --platform
+linux/amd64`).
+
+## Install channels (all deliver the same bundle)
+
+1. **`curl | sh`** ([`install.sh`](install.sh)) — no Node required; ideal for a
+   fresh Linux VPS over SSH. Detects os/arch, pulls the archive from GitHub
+   Releases, symlinks `codegraph` onto PATH. Re-run to upgrade; `--uninstall` to
+   remove.
+2. **npm** ([`scripts/npm-shim.js`](scripts/npm-shim.js)) — preserves
+   `npm i -g @colbymchenry/codegraph`. The main package is a tiny shim; the
+   bundles ship as per-platform `optionalDependencies`
+   (`@colbymchenry/codegraph-<target>` with `os`/`cpu`), so npm installs only the
+   matching one. The shim — run by the user's Node — execs the bundle, so the
+   real work runs on the bundled Node 24. Works even on old Node. On Windows it
+   invokes the bundled `node.exe` against the app entry directly (not the `.cmd`
+   launcher) — modern Node throws `EINVAL` when asked to spawn a `.cmd`/`.bat`.
+3. **Windows** ([`install.ps1`](install.ps1)) — `irm … | iex`; same flow as
+   install.sh (detect arch, pull the `.zip` from Releases, add to PATH).
+4. **Homebrew / Scoop** — TODO (tap + cask pointing at the Release archives).
+
+## Release pipeline
+
+[`.github/workflows/release.yml`](.github/workflows/release.yml) — manually
+triggered. Reads the version from `package.json`, builds every platform bundle on
+one runner, creates the GitHub Release (notes from `CHANGELOG.md`), and publishes
+the npm shim + per-platform packages. Requires the `NPM_TOKEN` repo secret.
+
+Still TODO:
+- **Code signing** — the main gap for "download & run": macOS Gatekeeper needs a
+  Developer ID + notarization; Windows needs Authenticode. Homebrew softens the
+  macOS case (handles quarantine).
+- Retire the now-vestigial Node-version gate in `src/bin/codegraph.ts` — the
+  bundle always runs Node 24, and the npm shim does no tree-sitter work.
+- Re-wire `npm uninstall` cleanup (the agent-config `preuninstall`) through the
+  shim — the generated main package doesn't carry it.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9b924af9e..fbf4c5d4e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,350 +9,375 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-### Added
-- **Lua**: CodeGraph now indexes Lua (`.lua`) — functions, methods (table `t.f`
-  and `t:m` definitions become methods with a `t::f` receiver-qualified name),
-  local variables, `require(...)` imports, and the call edges between them.
-  Querying a Lua project (Neovim plugins, Kong, OpenResty, game code) now
-  surfaces its modules, methods, and call graph.
-- **Luau** ([#232](https://github.com/colbymchenry/codegraph/issues/232)):
-  CodeGraph now indexes Luau (`.luau`), Roblox's typed superset of Lua —
-  everything Lua extracts, plus `type` / `export type` aliases, typed function
-  signatures, generics, and Roblox instance-path `require(script.Parent.X)`
-  imports.
+### Security
+
+- Closed a path-traversal hole where a symbolic link inside an indexed project that pointed *outside* the project root could make CodeGraph serve that out-of-root file's contents (for example a file under your home directory) to the AI agent. CodeGraph now resolves symlinks when validating file access and refuses to read anything whose real location is outside the project, while still allowing symlinks that stay within it. Thanks @sulthonzh. (#527)
+- CodeGraph now indexes Spring configuration files (`application.properties` / `application.yml`) by key only, and never includes their values in `codegraph_explore` or `codegraph_node` output. Previously a secret committed to one of these files — a database password, API key, or connection string with embedded credentials — could be surfaced to an AI agent that asked about nearby code, even though the agent never opened the file. The configuration keys are still indexed, so reference and impact analysis are unaffected; an agent that genuinely needs a value reads the file itself. Shopify Liquid `{% schema %}` blocks are likewise indexed by name only. (#383)
+
+### New Features
+
+- **Subagents and non-MCP agents can now reach CodeGraph.** Two new CLI commands — `codegraph explore "<symbols or question>"` and `codegraph node <symbol-or-file>` — print exactly what the matching MCP tools return (relevant symbols' source + call paths; one symbol's source + callers; file reads with line numbers), so any agent with a shell can use the graph. And `codegraph install` now writes a small marker-fenced CodeGraph section into each agent's instructions file (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`) pointing at both surfaces — that file is what Task-tool subagents actually see, where the MCP server's own guidance only reaches the main agent. Measured on a delegated code-exploration task: subagents went from almost never using CodeGraph (~1 in 9 runs) to using it in every run, including runs with zero grep/file-reading fallback. The section is small, survives your own content, upgrades cleanly from the old long block, and `codegraph uninstall` removes it. Thanks @liuyao37511. (#704)
+- **The MCP tool list is now a focused default of four** — `codegraph_explore`, `codegraph_node`, `codegraph_search`, and `codegraph_callers`. The other four (`codegraph_callees`, `codegraph_impact`, `codegraph_files`, `codegraph_status`) remain fully functional — the CLI and library API are unchanged, and `CODEGRAPH_MCP_TOOLS` re-enables any of them — but they're no longer listed to agents by default: measured agent behavior shows they're never or rarely picked, and the information they carry already arrives inline on the tools agents do use (explore's blast-radius section, node's dependents note, a symbol's own body as its callee list). A leaner list saves context tokens every session and steers agents to the right tool by presence alone.
+- **CodeGraph now goes quiet instead of failing loudly in unindexed projects.** When an AI agent's session starts in a workspace that has no CodeGraph index, the MCP server now announces itself as inactive with a short note and lists no tools at all — instead of presenting the full toolset and erroring on every call, which taught agents to distrust CodeGraph even where it works. Querying another project that isn't indexed likewise returns clear guidance (use your regular tools for that codebase; the user can run `codegraph init` there to enable CodeGraph) instead of an error, and genuine internal errors now tell the agent to retry once rather than give up on CodeGraph entirely. Indexing stays your decision — agents are told not to run it themselves. (#769)
+- **Astro projects are now indexed.** `.astro` files previously weren't parsed at all — on a typical Astro site that left most of the codebase invisible to search, impact, and `codegraph_explore`. CodeGraph now extracts the TypeScript frontmatter (functions, imports, `getStaticPaths`, …) and client-side `<script>` blocks, captures function calls and `<Component>` usages in template markup so cross-component dependencies trace end-to-end, resolves the `Astro` global and `astro:*` module imports as framework-provided, and maps `src/pages/` file-based routing to route nodes (`.astro` pages and `.ts` endpoints, including `[param]` and `[...rest]` dynamic segments, with underscore-prefixed files correctly excluded). Validated on two real-world Astro sites with 93% measured cross-file coverage and every page mapping to its route. Thanks @xingwangzhe. (#768) (Astro)
+- Same-named symbols across a monorepo's apps are no longer conflated. In a NestJS-style workspace with one `UserService` per app, `codegraph_callers`, `codegraph_callees`, and `codegraph_impact` now report **one section per distinct definition** — each app's callers and blast radius under its own file-labeled heading — instead of a single merged list, and accept a `file` argument to focus exactly the definition you mean (like `codegraph_node` already did). Impact in particular no longer overstates a change's blast radius by merging unrelated same-named classes. Thanks @Igorgro. (#764)
+- Fixed a related source of cross-package wrong edges: PascalCase **type references from plain `.ts` files were being resolved as React components**, which could link a file's own type alias to an arbitrary same-named class in another package (on one large monorepo this produced over a thousand wrong cross-package reference edges; 96% are now gone, and the remainder are genuine shared-model imports). Component resolution now applies only to references from JSX-capable files and never guesses between multiple candidates without a positional signal. The **Svelte and Vue component resolvers had the same arbitrary-pick flaw** (Vue resolved the first same-named `.vue` file found anywhere in the tree) and now follow the same rule: same-directory first, otherwise only an unambiguous name resolves. Re-index a project to benefit. (#764) (TypeScript, React, Svelte, Vue)
+- TypeScript and JavaScript **class fields are now reported as properties instead of methods**. A plain field like `public fonts: Fonts;` previously extracted as a method, misrepresenting class shape and letting calls to same-named functions resolve to data fields (a boolean field named `isArray` was soaking up `Array.isArray(...)` call edges). Fields holding arrow functions or function expressions (`onClick = () => {…}`, including wrapped ones like `onScroll = throttle(() => {…})`) correctly remain methods and their bodies are still analyzed. Field initializers are analyzed too, so `history = createHistory()` records its call — and JavaScript class fields, which previously produced no symbol at all, now appear in the graph. Re-index a project to benefit. (#808) (TypeScript, JavaScript)
+- Callback registration through `this` now resolves precisely in TypeScript and JavaScript: `window.addEventListener("online", this.onOfflineStatusToggle)` or an API object like `{ mutateElement: this.mutateElement }` produces a reference edge to the **enclosing class's own method** — never a same-named method on an unrelated class, and never a data field. Builds on the callback-registration support below. (#808) (TypeScript, JavaScript)
+- Callback-registration coverage deepened across four more shapes: a `this.<member>` registration whose method lives on a **base class** now resolves through the inheritance chain (`bus.on("submit", this.handleSubmit)` in a subclass links to the parent's `handleSubmit`); Java and Kotlin **method references to other classes** (`Handlers::onMessage`, `OtherClass::handle`) resolve across files, with `this::` and `super::` scoped to the defining class and references through a variable deliberately left out; and Swift bare callback names now match only the **enclosing type's** methods (implicit `self`), eliminating a class of wrong edges where a parameter like `request` linked to a same-named method on an unrelated type. (Java, Kotlin, Swift, TypeScript, JavaScript)
+- PHP **string and array callables** now register: a string passed to a callable-taking core function (`usort($items, 'cmp_items')`, `array_map('absint', …)`, `call_user_func`, `spl_autoload_register`, …) links to that function — including across files — and the array forms `[$this, 'method']` and `[Foo::class, 'method']` link to the named method (the `$this` form resolves through the class and its parents). Strings passed to arbitrary functions are deliberately ignored: only known callable positions are trusted. Validated on WordPress core (+556 edges, every sampled edge a genuine registration). (PHP)
+- Ruby **lifecycle-hook symbols** now register: `before_action :authenticate`, `after_save :reindex`, `around_create`, `validate :check`, `rescue_from(…, with: :handler)` and friends link the symbol to the method it names — on the class itself or **inherited from a parent** (`before_action :authenticate` in a controller resolves to `ApplicationController`'s method). `validates` (plural) is excluded since its symbols name attributes, not methods. Validated on rails/rails (+385 edges, every sampled edge genuine). (Ruby)
+- Method references to a type that needed **no import** now resolve: Java/Kotlin same-package references (`.concatMapMaybe(Maybe::just, …)`), **Kotlin companion-object members** (`KtHandlers::handle`), and cross-file C++ member pointers (`&TestSuite::RunSetUpTestSuite`). Resolution stays anchored to the named type, so a same-named member on a different class never matches. (Java, Kotlin, C++)
+- CodeGraph now sees where a function is **registered as a callback**, not just where it's called. A function name passed as an argument (`signal(SIGINT, handler)`, `qsort(…, compare)`, `addEventListener(…, onBlur)`), assigned to a function pointer or field (`ops->recv_cb = my_cb`, `OnClick := Handler`), or placed in a struct initializer or handler table (`{ .recv_cb = my_cb }`, `{ "get", getCommand }`) now produces a reference edge from the registration site to the function — so `codegraph_callers` and `codegraph_impact` surface callback wiring that previously looked like dead code. Works across all supported languages, including the language-specific forms: C/C++ `&fn`, Java `Class::method`, Kotlin `::fn`, Swift `#selector`, Objective-C `@selector`, Ruby `method(:fn)`, Scala eta-expansion, and Delphi/Pascal `@Handler` and `OnClick := Handler` event wiring. Callers output labels these "via callback registration". Resolution is deliberately conservative: an ambiguous name produces no edge rather than a wrong one. Re-index a project to benefit. Thanks @zmcrazy. (#756)
+- The `codegraph_node` MCP tool can now **read a whole source file like the built-in Read tool — only faster, served from the index**. Pass a file path with no symbol and it returns that file's current source with line numbers (the same `<n>⇥<line>` shape Read produces, so an assistant can edit straight from it), narrowable with `offset`/`limit` exactly like Read, plus a one-line note of which files depend on it (the file's blast radius). Use it anywhere you'd reach for Read on an indexed source file. Pass `symbolsOnly: true` for just the file's structure. Configuration/data files (`.yml` / `.properties`) are summarized by key only, never dumped, so secrets in them are never surfaced. The agent-facing guidance was also retuned so assistants reach for codegraph while *implementing* a change (not only when answering questions), since one codegraph call returns the same bytes plus the blast radius, faster than re-reading the file.
+- New `codegraph upgrade` command updates CodeGraph to the latest release in place — it detects how you installed (the standalone `install.sh` / `install.ps1` bundle, npm, or npx) and does the right thing for each, on macOS, Linux, and Windows. Use `codegraph upgrade --check` to see whether an update is available without installing, or `codegraph upgrade <version>` to move to a specific version. After upgrading it reminds you to re-index your projects so they pick up the newer engine's improvements. (#679)
+- `codegraph status` now flags when a project's index was built by an older engine than the one you're running and recommends re-indexing (also surfaced in `codegraph status --json`), so you know when a `codegraph index -f` or `codegraph sync` will add coverage a newer release introduced.
+- Cross-file impact and blast-radius coverage now spans **all 22 supported languages and 14 web frameworks**, each validated on a real-world repo — see the new coverage table in the README. This release ships the cross-file resolution behind it, including Lua and Luau `require`, Shopify OS 2.0 Liquid section templates, Delphi form code-behind, Rust cross-module calls and Rocket route macros, Swift Fluent relationships, and the SvelteKit / Nuxt / Vapor / Axum route conventions. The residual everywhere is genuine static-analysis frontiers (runtime dispatch, reflection / DI, framework-convention entry points), never hidden.
+- C# types are now tracked by their namespace-qualified name. Same-named types in different namespaces — a domain entity and a DTO both called `CatalogBrand`, say — are told apart instead of collapsing into one arbitrary match, so a reference resolves to the right one and impact no longer conflates them. (C#)
+- ASP.NET Razor (`.cshtml`) and Blazor (`.razor`) markup are now parsed for code relationships. A `@model` / `@inherits` / `@inject` directive links the view to the C# view-model, base type, or service it names; a Blazor `<MyComponent/>` tag (plus `@typeof(...)` and generic `TItem="..."` arguments) links to the component class; and the C# inside `@code { }` / `@functions { }` / `@{ }` blocks is analyzed too, so services and types used in component logic are linked. A view-model, component, or service referenced only from markup is no longer reported as having no dependents, and editing it surfaces the views that use it. (ASP.NET, Blazor)
+- A Razor/Blazor type reference now resolves through the component's `@using` namespaces — including the folder's cascading `_Imports.razor` — so a simple name that exists in several namespaces lands on the right one. A `@model` / `<MyComponent>` / `@code` reference to `CatalogBrand` resolves to the `@using`'d DTO (`BlazorShared.Models.CatalogBrand`) rather than a same-named domain entity. (ASP.NET, Blazor)
+- `codegraph status --json` now also reports the running CLI `version`, the index directory (`indexPath`), and a `lastIndexed` timestamp (ISO-8601, or null when nothing's indexed yet), so CI and scripts can pin the CLI version and check index freshness from a single command. A matching `CodeGraph.getLastIndexedAt()` library method exposes the same freshness check without shelling out. Thanks @12122J and @eddieran. (#329)
+- TypeScript service/RPC contracts defined as a tuple of generic types — `type MyServiceList = [Service<'query_apply_record', …>, Service<'apply_confirm', …>]` — now index each entry's string-literal name as a searchable symbol. Previously these names existed only as type arguments, so `codegraph query query_apply_record` found nothing even though the names are the app's primary API surface. The pattern is common in typed RPC / BFF clients and mock servers where the types are the source of truth for a runtime proxy object. Utility types (`Pick`, `Omit`, `Record`) and route paths are deliberately left out to avoid noise. Thanks @jiezhiyong. (#634) (TypeScript)
+- New `CODEGRAPH_DIR` environment variable sets the per-project index directory name (default `.codegraph`). This lets one working tree hold two independent indexes — most usefully when you open the same checkout from both **Windows** and **WSL**, which can't safely share a single `.codegraph/`: the background-server lock and the SQLite database are tied to the OS that wrote them, and SQLite locking across the WSL2/Windows filesystem boundary is unreliable. Set `CODEGRAPH_DIR=.codegraph-win` on the Windows side, leave WSL on the default, and each keeps its own index in the same folder without clobbering the other. CodeGraph also skips any sibling `.codegraph-*` directory when indexing and watching, so neither environment trips over the other's data. Thanks @rrtt2323. (#636)
+
+### Fixes
+
+- The `codegraph_search` tool's `kind: "type"` filter — a value its own schema advertises — silently matched nothing; it now correctly finds type aliases. The `codegraph_explore` tool's parameter guidance also no longer suggests running `codegraph_search` first, which contradicted explore's call-it-first design and cost agents an extra round-trip.
+- Symbols defined in Svelte and Vue `<script>` blocks were reported one line below where they actually are — a function on line 3 was reported at line 4 — which offset every script-block symbol's location in search, `codegraph_node`, and explore output. Line numbers now match the file exactly. Re-index a project to benefit. (Svelte, Vue)
+- Doc comments are now captured for exported, `const`-assigned, and decorated declarations, and the documentation a symbol carries is now clean across every supported language. Previously a comment above `export class X`, `export const fn = () => …`, a plain `const fn = () => …`, or a decorated Python `def`/`class` (`@app.route(...)`, `@dataclass`) was dropped entirely — only comments directly above a plain declaration were kept. CodeGraph now finds the comment through the `export` / `const` / decorator wrapper. Comment-marker cleanup was also rounded out for every language CodeGraph supports: Rust/Swift/Kotlin doc lines (`///`, `//!`), Python/Ruby/shell `#`, Lua/Luau (`--` and `--[[ ]]`), and Pascal (`{ }` and `(* *)`) no longer leave stray markers in the stored text — validated end-to-end across all 19 code languages plus Svelte/Vue `<script>` blocks. (#780). Thanks @caleb-kaiser.
+- Go method calls made through a chained factory function now resolve to the correct type. A call like `New().Method()` used to drop the receiver, so the chained method attached to a same-named method on an unrelated type — or didn't resolve. CodeGraph now captures Go return types (a pointer `*Foo` resolves to `Foo`, and a multi-return `(*Foo, error)` to its first result), infers the chained receiver's type from what the factory function returns, and resolves the method on it — including methods promoted from an embedded struct — creating the edge only when the type or an embedded type genuinely has the method. Existing Go indexes should be re-indexed (`codegraph index -f`) to benefit. (#750) (Go)
+- Scala method calls made through a companion-object factory, a fluent chain, or a case-class `apply` now resolve to the correct type. A call like `Foo.create().bar()` or `Builder(cfg).bar()` used to drop the receiver, so the chained method silently attached to a same-named method on an unrelated type — most often mis-attributing a standard-library `Option` / `Iterator` `.map` / `.flatMap` / `.foreach` onto your own same-named class. CodeGraph now captures Scala return types (a generic `List[Foo]` resolves to its container `List`, a qualified `pkg.Foo` to `Foo`), infers the chained receiver's type from what the inner call returns or constructs, and resolves the method on it — including methods inherited from a trait the type extends — creating the edge only when that type or one of its traits genuinely has the method (so a wrong inference produces no edge instead of a misleading one). Existing Scala indexes should be re-indexed (`codegraph index -f`) to benefit. (#750) (Scala)
+- Rust method calls made through a chained associated function now resolve to the correct type. A call like `Foo::new().bar()` or `Foo::with(cfg).build()` used to drop the receiver, so the chained method silently attached to a same-named method on an unrelated type — or didn't resolve. CodeGraph now captures Rust return types (`-> Self` resolves to the implementing type), infers the chained receiver's type from what the associated function returns, and resolves the method on it — including methods provided by a trait the type implements (via the new `impl Trait for Type` relationships) — creating the edge only when the type or one of its traits genuinely has the method. Existing Rust indexes should be re-indexed (`codegraph index -f`) to benefit. (#750) (Rust)
+- Dart method calls made through a static factory, a factory or named constructor, or a fluent chain now resolve to the correct type. A call like `Foo.create().bar()` used to drop the receiver, so the chained method silently attached to a same-named method on an unrelated type — most often mis-attributing a standard-library `Option` / `Iterator` `.map` / `.where` onto your own same-named class. CodeGraph now indexes Dart **factory and named constructors** (`factory Foo.create()`, `Foo.named()`) as first-class members so calls to them resolve, captures Dart return types (a generic `List<Foo>` resolves to its container `List`), infers the chained receiver's type from what the inner call returns or constructs, and resolves the method on it — including methods inherited from a superclass or mixin — creating the edge only when that type genuinely has the method. Plain construction (`Foo(...)`) is still recorded as instantiation. Existing Dart indexes should be re-indexed (`codegraph index -f`) to benefit. (#750) (Dart)
+- Objective-C methods called through a chained message send now resolve to the correct class. A call like `[[Foo create] doIt]` used to drop the receiver, so `doIt` silently attached to a same-named method on an unrelated class — most often a test helper or stdlib class. CodeGraph now captures Objective-C method return types and infers the chained receiver's type from what the inner message returns. For the ubiquitous `[[X alloc] init]` and singleton (`[[X sharedInstance] …]`) patterns — where the factory returns `instancetype` — the receiver is the class `X` itself, so the chained method resolves on `X` (including methods inherited from a superclass), creating the edge only when the class genuinely has the method. Existing Objective-C indexes should be re-indexed (`codegraph index -f`) to benefit. (#750) (Objective-C)
+- Pascal/Delphi methods called through a chained factory call now resolve to the correct class. A call like `TFoo.GetInstance().DoIt()` used to drop the receiver, so `DoIt` silently attached to a same-named method on an unrelated class. CodeGraph now captures Pascal return types and infers the chained receiver's type from what the factory function returns — resolving to the declared type (including an interface return like `IFoo`), and for a constructor (`TFoo.Create().…`) or a typecast (`TFoo(x).…`) to the class `TFoo` itself, since both yield a `TFoo`. The edge is created only when that type genuinely has the method (so a wrong inference produces no edge). Existing Pascal/Delphi indexes should be re-indexed (`codegraph index -f`) to benefit. (#750) (Pascal/Delphi)
+- Pascal/Delphi **paren-less method calls are now tracked**. Pascal lets a no-argument method or procedure drop its parentheses (`Obj.Free;`, `List.Clear;`, `TFoo.GetInstance.DoIt;`), which previously weren't recorded as calls at all — so callers, impact, and trace missed them. CodeGraph now extracts these, scoped to statement position so a field or property access (which looks identical) is never mistaken for a call. On a real Delphi codebase this added ~1,100 previously-missing call edges with no false positives. Existing Pascal/Delphi indexes should be re-indexed (`codegraph index -f`) to benefit. (Pascal/Delphi)
+- Pascal/Delphi calls inside a **standalone procedure or function** (one with no `interface` declaration, defined only in the `implementation` section) are now attributed to that routine instead of the whole file. Previously such a routine had no symbol of its own, so everything it called was lumped under the unit — `codegraph_callers` returned the file, and impact couldn't tell which routine was responsible. These routines are now indexed and their calls attributed correctly. Existing Pascal/Delphi indexes should be re-indexed (`codegraph index -f`) to benefit. (Pascal/Delphi)
+- Chained method calls now resolve when the chained method is **inherited from a superclass or declared on an interface/protocol** the receiver's type conforms to — for example a call on a sealed-subclass instance (`Either.Right(x).combine(...)`) that invokes a method defined on its parent type. Previously these chains found no caller edge even though the factory's type was known, so the call was invisible to callers, impact, and trace. CodeGraph now walks the type's supertypes (its `extends` / `implements` relationships) to find the method, creating the edge only when a supertype genuinely declares it (so a wrong inference still produces no edge). This makes Java, Kotlin, and C# factory and fluent chains more complete. Existing indexes should be re-indexed (`codegraph index -f`) to benefit. (#750)
+- Swift method calls made through a static factory, fluent chain, or constructor now resolve to the correct class. A call like `Foo.make().draw()` or `Foo().draw()` used to drop the receiver, so the chained method silently attached to a same-named method on an unrelated class — or didn't resolve at all. CodeGraph now captures Swift return types and infers the chained receiver's type from what the inner call returns (or the constructed type), creating the edge only when that class genuinely has the method (so a wrong inference produces no edge instead of a misleading one). Existing Swift indexes should be re-indexed (`codegraph index -f`) to benefit. (#750) (Swift)
+- C# method calls made through a static factory or fluent chain now resolve to the correct class. A call like `Foo.Create().Bar()` or `JObject.Parse(s).Property(...)` used to lose the receiver's type, so the chained method didn't resolve and the call was invisible to callers/impact/trace. CodeGraph now captures C# return types and infers the chained receiver's type from what the inner call returns, creating the edge only when that class genuinely has the method (so a wrong inference produces no edge). Existing C# indexes should be re-indexed (`codegraph index -f`) to benefit. (#750) (C#)
+- Kotlin method calls made through a companion-object factory or fluent chain now resolve to the correct class. A call like `Foo.getInstance().bar()` or `Config.create(opts).build()` used to drop the receiver entirely, so the chained method silently attached to a same-named method on an unrelated class — or didn't resolve at all — corrupting callers, impact, and trace. CodeGraph now captures Kotlin return types and infers the chained receiver's type from what the inner call returns, creating the edge only when that class genuinely has the method (so a wrong inference produces no edge instead of a misleading one). Existing Kotlin indexes should be re-indexed (`codegraph index -f`) to benefit. (#750) (Kotlin)
+- Java method calls made through a static factory or fluent chain now resolve to the correct class. A call like `Foo.getInstance().bar()` or `Config.create(opts).build()` used to lose the receiver's type, so when two classes had a same-named method the call silently attached to whichever was indexed first — or didn't resolve at all — corrupting callers, impact, and trace. CodeGraph now captures Java return types and infers the chained receiver's type from what the inner call returns, creating the edge only when that class genuinely has the method (so a wrong inference produces no edge instead of a misleading one). Covers factories and fluent builders that take arguments (`hashKeys().arrayListValues()`), including builders that return a nested type. Existing Java indexes should be re-indexed (`codegraph index -f`) to benefit. (#750) (Java)
+- PHP: a method called through a chained static factory — `Cls::for($x)->method(...)`, the canonical Laravel per-credential / per-tenant client idiom — now records a caller edge. Previously the receiver type (what `for()` returns) was never recovered, so `codegraph_callers` returned nothing for the method and the call was invisible to `codegraph_impact`. CodeGraph now captures PHP return types — `: self` / `: static` resolve to the declaring class, `: SomeClass` to that class — and resolves the chained method on the factory's result, creating the edge only when that class actually has the method (so a wrong inference produces no edge). Existing PHP indexes should be re-indexed (`codegraph index -f`) to benefit. Thanks @cvanderlinden. (#608) (PHP)
+- Search relevance: including the project name in a query (a user naturally writes `MyApp backend routes`) no longer buries the part of the codebase the query is actually about. The project name lexically matches whatever stack embeds it — a `MyAppFrontend/` directory, a `MyAppApp` class — and it was over-weighted two ways: a single PascalCase word was scored once per sub-token (`my` / `app` / `myapp`), so one concept boosted that path several times over; and the name carried full path / disambiguation weight even though it names the whole repo, not any symbol. Now path relevance counts each query word once, and a word matching the project name (derived from `go.mod`, `package.json`, or the repo directory) is dropped from path scoring and from `codegraph_explore`'s type-disambiguation bias — unless it's the only term, so a bare project-name search still works. In a mixed-stack repo, a backend question now surfaces the backend even with the project name in the query. Thanks @MiNuo1. (#720)
+- Go: a function called only from inside an anonymous closure — a cobra `RunE: func(…) {…}` handler, a goroutine literal, or a callback closure stored in a package-level `var` — now shows its real caller. Previously the call leaked to the file node, so `codegraph_callers` and `codegraph_impact` reported such a function as having no meaningful caller; the call is now attributed to the enclosing declaration, so editing the function surfaces the closures that use it. Existing Go indexes should be re-indexed (`codegraph index -f`) to benefit. Thanks @Cyclone1070. (#693) (Go)
+- Indexing no longer aborts when a `.gitignore` contains non-UTF-8 bytes or an unparseable pattern. A `.gitignore` transparently encrypted in place by corporate DLP / endpoint-security software (a common enterprise scenario) — or one with a stray pattern the matcher can't compile (`\[`, producing "Unterminated character class") — used to crash the entire `sync` / `index` with a screen of garbled bytes and never name the offending file, leaving `Files: 0 / Nodes: 0`. CodeGraph now skips a `.gitignore` that isn't valid UTF-8 text whole, drops only the individual unparseable patterns from a text one, and logs a warning naming the file — indexing continues either way. Thanks @zhanghang-9527. (#682)
+- C++ method calls made through a singleton, factory, or chained getter now resolve to the correct class. A call like `Foo::instance().bar()`, `WidgetFactory::create().draw()`, `openSession()->run()`, or the same stored in an `auto` local first, used to lose the receiver's type — so when two classes had a same-named method the call silently attached to whichever was indexed first (or didn't resolve at all), corrupting callers, impact, and trace. CodeGraph now infers the receiver's type from what the inner call returns (capturing C++ return types for the first time) and creates the edge only when that class genuinely has the method, so a wrong guess produces no edge instead of a misleading one. Covers singletons and self-returning accessors, factories that return a different type, free-function factories, `make_unique` / `make_shared` / `new` / direct construction, and single-level member chains. Existing C/C++ indexes should be re-indexed (`codegraph index -f`) to benefit. Thanks @stabey. (#645) (C/C++)
+- The shared background server no longer logs a scary-looking `[error] … undefined` line on every session start. Attaching to the shared daemon is normal, healthy behavior, but the informational message was being surfaced by MCP hosts (Claude Code and others) as an error; it's now silent by default — set `CODEGRAPH_MCP_LOG_ATTACH=1` to surface it when debugging daemon attach. Thanks @mturac. (#618)
+- On Windows, CodeGraph's background processes no longer pile up without bound and saturate CPU over a long session. When the editor or agent that launched CodeGraph exited, its helper process couldn't tell its parent had gone — Windows reports process lineage differently than macOS and Linux — so the helper kept running, the shared background server never saw the client disconnect, and its idle timer never fired to shut it down. CodeGraph now detects parent-process exit directly on Windows, so helpers and the idle background server wind down promptly, the same as they already did on macOS and Linux. (#692, #576, #680)
+- The MCP server now shuts down cleanly when its editor/agent connection drops abruptly, instead of risking an orphaned process that pins a CPU core. Editors talk to a stdio MCP server over a socket; if that socket failed with an error rather than closing cleanly — which can happen when the editor window is reloaded or the launching process is killed — the server didn't treat it as a disconnect and could be left running. CodeGraph now treats any failure of its input stream as a shutdown signal and tears the stream down, so an orphaned server exits promptly. (#799)
+- The shared background server has two further safeguards against ever lingering: it now drops a client the moment it detects that client's process is gone (even if the disconnect arrived uncleanly — a force-quit or a dropped connection that never closed the socket), and it won't stay running indefinitely with clients attached but no activity. Together these guarantee it always winds down, on every platform. (#692)
+- A session no longer loses CodeGraph when the shared background server is restarted out from under it — for example when your MCP host (opencode and others) stops and restarts the server as you open another session. Previously the affected session's connection died silently and any request in flight at that moment hung; now CodeGraph keeps that session working by serving it locally, so the tools stay available without restarting the session. (#662)
+- React Native native→JS events now connect through the common `sendEvent(context, "X", body)` wrapper. Many libraries (react-native-device-info and others) wrap the event emitter behind a helper whose `.emit(eventName, …)` takes a *variable*, so the matcher — which looked for `.emit("literal", …)` — missed it; the literal event name actually lives in the wrapper call. Now a native method that fires `sendEvent(…, "batteryLevelChanged", …)` links to the JS `addListener('batteryLevelChanged', …)` handler, so editing the native emitter surfaces the JS subscriber. (React Native)
+- React Native / Expo cross-language bridges are more complete and more precise. An Expo Module method declared with a generic type — Android's `AsyncFunction<Float>("getBatteryLevelAsync")` — is now indexed (the `<Float>` used to defeat the matcher, so every Android Expo method was dropped and a JS call resolved only to the iOS Swift impl). The iOS and Android implementations of the same JS-visible method — both Expo Modules and classic NativeModules (`@ReactMethod` on Android, the matching method on iOS) — are now linked to each other, so a JS call that resolves to one platform still reaches the other and editing either platform's native code surfaces the JS caller. And a `Type.member` static read in native code (e.g. Android's `BatteryManager.EXTRA_LEVEL`) no longer falsely links to a coincidentally same-named class in another language (a web `BatteryManager`) — type references stay within a language family, while genuine cross-language bridges (config→code, JS↔native calls) are unaffected. (React Native, Expo)
+- A TypeScript/JavaScript reference or import no longer gets mis-linked to a same-named class in a native language. In a React Native / Expo repo that has both a TypeScript `TestRunner` type and a Kotlin `TestRunner` class, a TS reference to `TestRunner` — or an `import React` sitting next to a Swift `React` — used to resolve onto the native symbol (the component resolver matched any same-named class regardless of language, and import statements weren't language-checked at all). References and imports now stay within their language family, so they land on the right symbol while genuine cross-language bridges (JS↔native calls, config→code) are untouched. A C/C++ `#include "Foo.h"` likewise no longer resolves to a same-named header from another platform (an iOS Objective-C `Foo.h`). (React Native, Expo, TypeScript, C/C++)
+- Native includes and Kotlin Multiplatform imports now resolve to the correct file in multi-platform projects. A C/C++ `#include "Foo.h"` now resolves to the header in the including file's own directory first (the C quoted-include rule), so when a module ships a same-named header per platform (a Windows, an Apple, and an Android `Foo.h` side by side) the local one correctly shows its dependents instead of an arbitrary other-platform header looking like the dependency. And a Kotlin Multiplatform `expect` declaration is no longer reported as having no dependents: a `commonMain` import now resolves to the `commonMain` `expect` (matched within the importing source set) rather than being absorbed by one platform's `actual`. (C/C++, Kotlin)
+- `codegraph affected` now reports the tests and files that actually depend on your changes. It used to follow only `import` statements — but those never cross file boundaries in CodeGraph's graph — so it returned **no affected tests for any change, in every language**. It now traces the real cross-file usage graph (calls, references, instantiations, and class `extends` / `implements`), so `git diff --name-only | codegraph affected` surfaces the test files that exercise the changed code. Circular-dependency detection, which had the same blind spot, now works too.
+- Blast radius, callers, and `codegraph affected` now recognize far more of the dependencies that were already in your code. A symbol now counts as a dependency whether it's called, used only in a type annotation inside a function body (`const items: Foo[] = []`), imported and placed in a registry array or passed as an argument, used as a JSX component, simply re-exported from a barrel (`export { X } from './x'`), or pulled in as a namespace (`import * as ns from '@/x'`) — including through tsconfig path aliases like `@/`. Previously only called, instantiated, or signature-typed symbols created a cross-file link, so a file that used a dependency in any other way could look like it depended on nothing — and the file that defined a widely-used symbol could look like nothing depended on it. The graph still indexes exactly the same symbols; it just connects the ones that were already there. (TypeScript/JavaScript)
+- The same completeness fix now applies to **Python**: a name brought in with `from module import X` is recorded as a dependency on that module even when `X` is only stored in a list/dict, passed as an argument, used as a decorator, or re-exported through an `__init__.py`. Previously Python linked only imports that were called or instantiated, so a module consumed purely by value — or only re-exported — looked like nothing depended on it.
+- `codegraph_callers` (and the `callers` command) now lists the places a class is **instantiated**, not just where it's imported. Constructing a class — `Foo(...)` in Python, `new Foo()` elsewhere — is calling its constructor, so asking who calls a class now returns the construction sites, and `codegraph_callees` / trace cross the instantiation the same way. Previously a class's instantiation sites were invisible to `callers`, so "what breaks if I change this class?" could come back empty even when the constructor was called from many places. Works on your existing index — no re-index needed. (#774)
+- Rust impact and `codegraph affected` now connect far more of the module graph. Struct literals (`Widget { n: 1 }`) are recorded as instantiations; a `use` / `pub use` brings its item into the dependency graph — so a `pub use` re-export hub (a `mod.rs` re-exporting its submodules) depends on the modules it re-exports — resolved by Rust module path (`crate::`/`self::`/`super::`), so a re-export of a common name like `read` links to the right module instead of a same-named symbol elsewhere; and trait dispatch reaches implementations — a struct whose methods cover a trait's is treated as implementing it, and a call through `&dyn Trait` resolves to the concrete method. Previously a Rust type linked only when called or used in a type position, so structs built by literal, modules surfaced only through `pub use`, and trait-only implementations looked like they had no dependents. (#584 for Rust traits)
+- Rust cross-module function calls now resolve to the right file. A call to a sibling submodule's function — `users::router()`, the common router-assembly / handler-registration pattern where `mod users;` makes `users` a child of the current module — is now resolved relative to the current module, not only the crate root. Deeper module-path calls (`database::profiles::find()` — the `db.run(|c| …)` data-access shape) now resolve too; these were being discarded before resolution even ran, because the path's leaf function name was never checked. Previously such a call linked to nothing, so a module reached only as `module::path::function()` looked like it had no dependents; a web app wired this way (Axum, Rocket, and similar) now surfaces its handler and data-access modules' real callers. (Rust)
+- Rocket route handlers now connect to where they're mounted. A handler registered in a `routes![a::b::handler, …]` or `catchers![…]` macro used to be invisible — the macro body is a raw token tree, so the handler looked like it had no caller (Rocket mounts it at runtime) and its file showed no dependents. The handler paths are now read out of the macro and linked to the `mount`/`register` call, so editing a Rocket handler surfaces its route registration and a routes module is no longer reported as unused. (Rust, Rocket)
+- SvelteKit pages now connect to their server `load` functions. SvelteKit wires a `+page.server.js` / `+page.js` `load` (and form `actions`) to the sibling `+page.svelte`'s `data` by file path, with no import between them — so editing a `load` previously showed no impact on the page it feeds. Each page is now linked to the `load`/`actions` in its own route directory (and likewise for `+layout`), so editing a loader surfaces the page that renders its data, and tracing a page reaches its server-side data source. (Svelte, SvelteKit)
+- Nuxt nested components are now connected to where they're used. Nuxt auto-imports a component in a subdirectory by a directory-prefixed name — `components/media/Card.vue` is used in templates as `<MediaCard/>` — but it was tracked by its file name (`Card`), so the usage didn't resolve and the component looked unused. PascalCase component tags (`<MediaCard>`, `<NavBar>`) in a `.vue` template are now matched, falling back to the Nuxt directory-prefixed name, so editing a nested component surfaces every page and component that renders it. (Vue, Nuxt)
+- Lua and Luau `require` calls now connect to their module files. A dotted module path (`require("telescope.config")` → `telescope/config.lua` or `.../config/init.lua`) and a Roblox/Luau instance-path require (`require(script.Parent.Signal)` → the `Signal` module) now link to the file they load, so editing a module surfaces every file that requires it. Previously requires resolved to nothing, so a Lua/Luau module looked like it had no dependents. (Lua, Luau)
+- Shopify OS 2.0 sections now connect to the JSON templates that use them. Modern Shopify themes define templates as JSON (`templates/*.json`, plus section groups `sections/*.json`) that list sections by `type` rather than with a `{% section %}` Liquid tag, so a section used only from a JSON template was reported as having no dependents. Those JSON files are now read and each section `type` is linked to its `sections/<type>.liquid`, so editing a section surfaces the templates that render it. (Liquid, Shopify)
+- Delphi form definitions now connect to their code-behind units. A `.dfm` (VCL) or `.fmx` (FireMonkey) form is owned by its same-named `.pas` unit through the `{$R *.dfm}` directive rather than a `uses` clause, so a form file used only as a definition was reported as having no dependents. The unit is now linked to its form, so editing a form surfaces the unit that owns it. (Pascal/Delphi)
+- Swift property wrappers and attributes are now connected. A `@Argument` / `@Published` / `@State` / custom `@propertyWrapper` on a property — and attributes on types, methods, and functions (`@objc`, `@MainActor`, …) — now record a dependency on the wrapper/attribute type. Previously these were dropped entirely (Swift attributes parse differently from other languages, and stored properties weren't being inspected), so the wrapper type looked unused and the file using it depended on nothing — a big gap for SwiftUI and argument-parser-style code.
+- Swift Fluent relationship models are no longer orphaned. A type referenced only through a property-wrapper *argument* — `@Siblings(through: AcronymCategoryPivot.self, …)`, the many-to-many pivot/join model — now records a dependency on that type. Previously only the wrapper itself (`Siblings`) and the property's declared type were captured, so a pivot model reached solely through the relationship looked like nothing depended on it and editing it surfaced no impact. (Swift, Vapor/Fluent)
+- Java annotations are now connected. Annotation definitions (`@interface Foo`) are indexed as types, and every `@Foo` usage on a class, method, or field is recorded as a dependency on it. Previously neither side was captured — annotation usages were dropped (they live inside the declaration's modifiers) and `@interface` types weren't indexed at all — so annotation-driven code (Spring `@GetMapping`, JPA `@Entity`, Gson `@SerializedName`, …) showed the annotation as having no users and the annotated class as not depending on it.
+- Kotlin Multiplatform `expect`/`actual` declarations are now connected. A platform implementation — `actual fun`, `actual class`, or an `actual typealias` in a `jvm` / `native` / `js` / `wasm` source set — is linked to the common `expect` declaration it fulfills (including the common case of an `expect class` fulfilled by an `actual typealias`). Previously a caller in common code resolved to the `expect` declaration, so every platform `actual` looked like it had no dependents and editing one showed an empty blast radius; now changing a platform implementation surfaces the common API and everything that uses it. (Kotlin)
+- Scala impact and `codegraph affected` now connect the type graph that typeclass-style code is built on. A parameterized supertype (`trait Monoid[A] extends Semigroup[A] with Serializable`) now links to each parent; a type used in a `val`/`def` signature, as a type argument, or as a context bound (`def f[A: Monoid]`) — including the trailing implicit parameter list (`(implicit M: Monoid[A])`) where typeclass instances are passed — now records a dependency; and `new T[...] { … }` counts as an instantiation. Previously Scala linked only plain calls and bare, non-generic supertypes, so a trait extended with type parameters, used as a type, or required as an implicit looked like nothing depended on it — which on a typeclass-heavy codebase (cats, algebra) was most of the graph. (Scala)
+- PHP impact and `codegraph affected` now understand namespaces and `use` imports. Classes are tracked by their namespaced name, so the many same-named classes a framework defines (Laravel has 7+ `Factory` interfaces, several `Dispatcher`s, across namespaces) are told apart instead of collapsing into one arbitrary match. A `use App\Contracts\Cache\Factory;` now records a dependency on exactly that class — so a contract or interface that's imported and constructor-injected (the dependency-injection pattern) is no longer reported as having no dependents — and parameter, property, and return type-hints are recorded too. Previously PHP ignored namespaces entirely and linked only calls, `new`, and inheritance. (PHP)
+- Objective-C impact and `codegraph affected` are dramatically more complete. Four gaps are fixed: a single-argument message (`[cache storeImage:key]` — the most common call form) now matches its `storeImage:` method instead of dropping the colon; a class-message receiver (`[SDImageCache sharedCache]`, `[[Foo alloc] init]`) now records a dependency on the class, whose `@interface` lives in the header; `#import "Foo.h"` now resolves to the header file, so a header is no longer reported as having no dependents; and class-method message calls now resolve through the receiver type. Together these took typical libraries from a third-to-half of their files showing real dependents to ~90%. (Objective-C)
+- A type referenced only through a static member or enum value now records a dependency. Reading an enum value (`MediaKind.video`), a static constant (`Colors.red`, `JsonScope.EMPTY_DOCUMENT`), or a class constant (`Foo::BAR`) now links to the type — previously only method calls and `new` did, so a type or enum used purely *by value* (enum-heavy APIs, constants classes — a very common pattern) looked like nothing depended on it. Applies to Java, C#, Kotlin, Swift, Scala, Dart, PHP, and C++.
+- Dart impact and `codegraph affected` now follow mixins and method type annotations. A `with` mixin — Dart's core composition mechanism, which Flutter is built on — now records a dependency, so editing a mixin surfaces every class that mixes it in (the whole `with` clause used to be dropped, and a class declared `with M` alone even lost its real superclass link). And types used in a method's parameters or return value now link to their definition, so a class or enum referenced only as a type — not constructed or called — is no longer reported as having no dependents. (Dart)
+- C++ free functions are now indexed under their real name. A function written with a qualified-type parameter (`std::string TableFileName(const std::string& dbname)`) or an `auto … -> std::string` trailing return type was mistakenly named after that type (`string`), so calls to it never resolved, `codegraph_node` couldn't find it by name, and the file defining it looked like nothing depended on it. The function now keeps its real name, so cross-file calls, callers, and blast radius work — a meaningful gain for any namespaced C++ codebase (this is how most free functions in a library look). (C++)
+- Ruby impact and `codegraph affected` now follow mixins and `require`s. `include`, `extend`, and `prepend` of a module — Ruby's primary composition mechanism (ActiveSupport concerns, `Comparable`, `Enumerable`) — now record a dependency on that module, so editing a concern surfaces every class that mixes it in; previously these were read as a call to a method named `include`, so a module whose methods are exercised only by application code looked like nothing depended on it. And `require "lib/foo"` / `require_relative "../foo"` now link to the required file, so a file pulled in only by a `require` (config-loaded components, gems that don't autoload) is no longer reported as having no dependents. Together these took a typical gem from ~71% of its files showing real dependents to ~100%. (Ruby)
+- C# `record` types are now indexed. `record`, `record class`, and `record struct` declarations (everywhere in modern C# — DTOs, value objects, CQRS messages, MediatR notifications) were previously skipped entirely, so every reference, generic type argument (`IEnumerable<MyRecord>`), and `new MyRecord(...)` pointed at nothing and the file defining a record looked like it had no callers or dependents. (#237)
+- C# is now parsed with an up-to-date grammar that understands C# 12 **primary constructors**. A class or struct written as `class OrderService(IRepo repo, [FromKeyedServices("primary")] ICache cache) { … }` is now indexed reliably — previously the constructor parameter list confused the parser and could drop the whole class (and all of its methods) from the index, most often exactly when a parameter carried an attribute, as in the ASP.NET keyed-dependency-injection pattern. The primary-constructor parameters are also recorded as dependencies, so the services a type is constructed with show up in its blast radius and "who depends on this contract" answers. Method return types, base types, and members all continue to resolve, and `#if`-guarded members in multi-targeting code keep parsing correctly. (#237)
+- Go interfaces now connect to their implementations. Go has no `implements` keyword — a type satisfies an interface just by having the right methods — so CodeGraph now infers that link: a struct whose methods cover an interface's method set is treated as implementing it, and a call through the interface (`API.Marshal(...)`) reaches every concrete implementation. This means a type used only via an interface (the common plugin/strategy pattern — e.g. JSON-codec or renderer implementations selected at runtime) is no longer reported as having no callers or no dependents, and impact now flows from an interface method to the implementations behind it. (#584)
+- Go now records cross-package struct creation. A composite literal like `render.XML{...}` or `pkga.Widget{...}` — including ones registered in a package-level `var registry = map[string]R{...}` — now links to the package that defines the type. Cross-package function calls and type references already resolved; this closes struct instantiation, so a package whose types are only *constructed* elsewhere (a common pattern for interface implementations) is no longer reported as having no dependents. Go type conversions such as `(*Wrapped)(x)` now link to the converted-to type as well.
+- Python now follows whole-module imports — `from . import certs` then `certs.where()`, or `from pkg import sub` then `sub.run()`. Calls and attribute access through an imported submodule now resolve to that submodule, and importing a module is recorded as a dependency on it even when the member you use is itself re-exported from a third-party package. This also fixed Python relative-import path resolution generally (`from .sub.mod import x`), so `codegraph affected` and impact see the real module graph of a package.
+- Python now also links a whole-module **absolute** import (`import conduit.apps.signals`) to that module's file, not just `from x import y`. A module imported by its dotted path — common in package setup and side-effect imports — is no longer reported as having no dependents. Standard-library imports (`import os`) correctly create no edge. (Python)
+- Python `from package import submodule` now links to that submodule's file, resolved through the import's package so it lands on the right one when same-named modules exist in sibling packages (the FastAPI / Django router-aggregator pattern: `from app.api.routes import authentication` with an unrelated `authentication.py` elsewhere). So a route/handler module pulled in only by an aggregator is no longer reported as having no dependents. (Python)
+- Python now records the actual call edge for a function invoked through an imported module — `from pkg import module` (or `import pkg.module`) followed by `module.func()`, a common testing and namespacing pattern. Previously only the module-level dependency was tracked, so `codegraph_callers`, `codegraph_callees`, and impact on the target function came back empty even though the import itself resolved. (#578) (Python)
+- Django `include('app.urls')` now records a dependency from the project URLconf onto the included app's `urls.py`, so an app's routes module is no longer reported as having no dependents and editing it surfaces the project that mounts it. (Django)
+- A chained method call (`builder.Services.AddCoreServices(...)`) now resolves to its definition. Previously only a single-segment receiver (`obj.method()`) resolved, so a call through a property/member chain — very common for C# extension methods like ASP.NET dependency-injection registration (`AddCoreServices`/`AddWebServices`) and Guard clauses — found no definition. (C#, and any language with chained calls)
+- A renamed default import (`import articlesController from './article.controller'` where the module does `export default router`) now records a dependency on the imported module. Previously only named imports linked, so a module consumed only through a default import — the standard Express/NestJS route-controller pattern — looked like nothing depended on it. External packages (`import React from 'react'`) still create no edge. (TypeScript/JavaScript)
+- The background file watcher no longer exhausts your machine's file-descriptor budget. On macOS it previously kept **one open file handle per watched file**, so on a large project the running MCP server could pile up tens of thousands of handles and blow past the system-wide limit — at which point *unrelated* apps (your shell, editor, Docker, browser) started failing with "too many open files" until the codegraph process was killed. The watcher now uses a single recursive watch on macOS and Windows, and bounded per-directory watches on Linux, so its cost stays flat no matter how large the project is. (#644, #496, #555, #628, #579)
+- Indexing a project with very symbol-dense files (tens of thousands of functions or methods in a single file) no longer runs out of memory. The step that links dynamic call relationships used to load every function and method into memory at once, which could exhaust the heap and abort indexing with "JavaScript heap out of memory" on large or generated codebases; it now streams them, so memory stays flat no matter how many symbols the project has. (#610)
+- Indexing a very large repository no longer aborts during its first sync with a "too many SQL variables" error. (#540)
+- Files under directories with non-ASCII names (for example CJK characters) are no longer silently skipped during indexing. (#541)
+- The `.codegraph/` index folder no longer clutters `git status`: its generated ignore file now excludes everything in the folder except itself, so the database, `daemon.pid`, sockets, and logs stop showing up as untracked changes. (#492, #484)
+- Projects initialized by an older version now get that fix automatically: a `.codegraph/.gitignore` written before this change — which listed only the database, cache, and logs and so let the daemon's `daemon.pid` get committed — is upgraded in place the next time you run any CodeGraph command. A `.gitignore` you've customized yourself is left untouched. (#788)
+- SAP HANA `.xsjs` / `.xsjslib` files are now indexed as JavaScript. (#556)
+- TypeScript `.mts` and `.cts` module files are now indexed instead of being skipped. (#366)
+- JavaScript modules that wrap their code in an anonymous function — AMD/RequireJS, NetSuite SuiteScript, IIFE bundles — now have their inner functions and calls indexed, instead of the file coming up nearly empty. (#528)
+- Go methods declared on generic types (e.g. `func (s *Stack[T]) Push(...)`) are now correctly attached to their type, so callers, callees, and impact include them. (#583)
+- Go methods now attach to their receiver type even when declared in a different file from the `type` itself — the idiomatic split where `type User struct{…}` lives in one file and `func (u *User) Save()` in another. Previously a cross-file method was orphaned from its struct, so the type's member list, callers/callees, and impact missed it; as a knock-on, a struct whose interface-satisfying methods are spread across files now also links to the interfaces it implements. (#583)
+- Asking what a symbol impacts no longer drags in every unrelated sibling method of its class — impact now follows real dependencies instead of the structural "contains" relationship, keeping the result focused on what actually depends on the symbol. (#536)
+- CodeGraph's MCP server now answers an agent's `resources/list` and `prompts/list` probes with an empty list instead of an error, clearing the `-32601` messages some clients (opencode, Codex) logged on connect. (#621)
+- Svelte and Vue components used through a barrel file — `export { default as Button } from './Button.svelte'` re-exported from an `index.ts` and imported elsewhere — are no longer falsely reported as having **0 callers**. CodeGraph now follows the default re-export all the way to the component and resolves the imports that `.svelte` / `.vue` files themselves use, so `codegraph_callers` and `codegraph_impact` see every place a component is used. This also covers components imported from another package in a workspace/monorepo (`@scope/ui/widgets`) and bare directory imports (`import { x } from './'`). Previously a live component consumed only through a barrel looked like dead code. Thanks @nakisen. (#629)
+- Components used in a Vue Single-File Component's `<template>` — `<MyButton />`, or the kebab-case `<my-button />` — are now indexed as usages, so `codegraph_callers` and `codegraph_impact` include components that appear only in another component's markup (including through a barrel re-export). Previously only a Vue component's `<script>` block was analyzed, so template-only usages were invisible. (#629)
+- PHP: `include` / `require` / `include_once` / `require_once` of a static path now create a file→file dependency edge, so `codegraph_callers` and `codegraph_impact` follow includes in procedural / script-style PHP codebases — previously only namespace `use` statements became dependency edges. Dynamic includes (`include $var`, `require __DIR__ . '/x'`) are skipped. Thanks @atahan150 (#660).
+
+## [0.9.9] - 2026-06-02
+
+### New Features
+
+- `codegraph_explore` is now the primary tool, and one call is usually all an agent needs: it returns the verbatim source of the symbols relevant to your question (a plain question works as the query — you no longer need exact symbol names), grouped by file and Read-equivalent, so the agent answers without falling back to read/grep. The narrower `codegraph_context` and `codegraph_trace` tools were removed in favor of it — explore already surfaces the call flow among the symbols you name (the job trace did), so there's one obvious tool to reach for instead of three.
+- `codegraph_explore` now includes a compact "Blast radius" for the symbols you're looking at — who depends on each (just the locations, not their source) and which test files cover it — so before editing, the agent can see what else to update and which tests to run, without a separate impact lookup. Symbols nothing depends on are skipped, so it stays short.
+- Functions defined inside a store or handler object — the actions in a Zustand `create((set, get) => ({ … }))` store, and the same shape in Redux, Pinia, MobX, or any exported handler/route map — are now indexed as real symbols. Previously they existed only as object properties, so looking one up by name or asking who calls it returned "not found" and the agent had to read the whole store file to follow the flow; now `codegraph_node`, `codegraph_callers`, and `codegraph_explore` resolve them directly — including calls made through `useStore.getState().fetchUser()` or a destructured `const { fetchUser } = useStore.getState()`.
+- `codegraph_explore` now surfaces the *right* definition when a method name is overloaded across types. Asking about, say, `DataRequest`'s `task` and `validate` used to return a same-named method from an unrelated file (or an abstract base stub) and bury the one you meant; explore now recognizes the type you named in the query and leads with that type's own overloads, in full.
+
+### Fixes
+
+- Search ranking no longer lets a common word in your request hijack the results: asking about, say, a "flat object" screen used to surface an unrelated constant that merely happened to be named the same, because the exact-name match outweighed everything else. Ranking now weighs how well each result is corroborated by the rest of your request, so the symbols you actually meant come first (this improves `codegraph_explore`'s results).
+- `codegraph_node` now returns *every* definition when a name is ambiguous — an overloaded method, or the same method name on different types — instead of returning one (sometimes the wrong one) with a note listing the rest. Asking for such a symbol now hands back all of the matching definitions with their source in a single call, so the agent stops having to read the file by hand to find the specific overload it wanted (common in Swift, Go, Java, and C#). For a heavily-overloaded name (a `poll`/`validate` with dozens of definitions), pass `file` (and/or `line`) — e.g. the `file:line` shown in a trail — to get that exact definition's body. Large overload sets show the most relevant ones in full and list the remainder by location.
+- `codegraph_explore` never returns half a method anymore: when output runs up against its size budget it drops whole methods or whole files (and lists what it dropped, so you can ask for them in another call) instead of cutting off a method body partway. A truncated method was the one case that still sent the agent to read the file for the rest — so the source explore returns is now always complete and usable as-is.
+
+## [0.9.8] - 2026-06-01
+
+### New Features
+
+- `codegraph init` now builds the initial index by default — you no longer need the `-i`/`--index` flag (it's still accepted, so existing commands and scripts keep working). (#483)
+- Go: Gin middleware chains now connect end-to-end in `codegraph_trace` and `codegraph_explore` — following a request reaches the middleware and route handlers registered via `.Use()` / `.GET()` instead of dead-ending where the framework dispatches the chain dynamically.
+- `codegraph_explore` now sizes its response to the *answer* instead of the file count: it shows the mechanism and the exact methods you asked about in full — even when they're buried deep in a large file — while collapsing the redundant interchangeable implementations of an interface (an HTTP interceptor chain, a query-compiler family) down to signatures. Fewer tokens for a more complete answer, so on the flows that used to occasionally cost more than plain grep/read it's now clearly cheaper — and the win holds across small, medium, and large codebases. Distinct, non-interchangeable code is shown in full as before. Disable with `CODEGRAPH_ADAPTIVE_EXPLORE=0`.
+- Swift deferred-validation flows (and similar "handler array" patterns) now connect end-to-end in `codegraph_trace` and `codegraph_explore` — following a request's lifecycle reaches the validators registered with `.validate { … }` instead of dead-ending where the framework runs them by iterating a stored list of closures. Any pattern where closures are appended to a collection and later invoked by looping over it is now traced.
+- `codegraph_explore` now spells out the dynamic-dispatch relationships of the symbols you ask about — e.g. "the closures registered here are run by `didCompleteTask`" — so the indirect hops you'd otherwise grep to reconstruct are listed alongside the call flow.
+- `codegraph_explore` answers multi-phase questions that span a large "god file" far more completely. For a flow like "build, send, and validate a request" — where one big file holds the build chain and the validate logic lives in others — it now keeps every method *on the flow path* in full, collapses the file's off-path methods to one-line signatures, and guarantees each phase's defining file is shown (instead of truncating at a fixed size and dropping whichever phase came last, which sent you to read it by hand). Incidental files that merely name-drop the flow are still trimmed, so the response stays focused on the code that answers the question.
+- CodeGraph is usable as an embedded library again: `require("@colbymchenry/codegraph")` and `import` now resolve the programmatic API — the `CodeGraph` class plus building blocks like `DatabaseConnection`, `QueryBuilder`, `initGrammars`, and `FileLock` — so you can drive the graph directly from your own app (for example an Electron process) instead of only through the CLI or MCP server. Embedding runs on your own runtime, so it needs Node 22.5+ for the built-in SQLite. (#354)
+
+### Fixes
+
+- `codegraph_trace` now resolves an overloaded symbol name to its real implementation instead of an empty protocol/delegate stub. Tracing a flow through a heavily-overloaded API (common in Swift, Java, C#, and Go) could land on an unrelated no-op method that happened to share the name and report "no path"; it now picks the substantive definition the flow actually runs through.
+- CodeGraph's MCP server now answers an agent's opening handshake the instant it launches instead of blocking while the index loads, so a fresh session's very first tool call no longer occasionally races a server that's still warming up and falls back to grep/read. The first question in a new session now reliably goes through CodeGraph.
+- Indexing a project that contains only config-style files (YAML, Twig, or `.properties`) no longer misleadingly reports "No files found to index" — these files are tracked at the file level and are now counted as indexed. Thanks @luojiyin1987 (#357).
+
+## [0.9.7] - 2026-05-28
+
+### New Features
+
+- Go: gRPC interface stubs now connect to their hand-written implementation, so callers, callees, impact, and trace land on the real method instead of an empty generated stub.
+- Generated files (protobuf, gRPC stubs, mocks, build output) now rank last in search, trace, and explore, so results land on your real implementation instead of an auto-generated placeholder.
+- When `codegraph_trace` can't find a static path (a dynamic-dispatch break), it now inlines both endpoints' source, callers, and callees in one response, so the agent gets the full picture without a flurry of follow-up calls.
+- Trace now picks the right endpoints in large multi-module repos by preferring symbols that share a directory, instead of grabbing an arbitrary same-named symbol from an unrelated module.
+- Test files are now deprioritized in `codegraph_explore` (Go, Ruby, JS/TS, Java/Kotlin/Scala), so the explore budget goes to your real implementation source.
+- Small projects (under ~500 files) now resolve flow questions in fewer MCP calls, with a leaner tool surface and tuned context and explore output sized for the project.
+- `codegraph_context` now auto-traces flow questions like "how does X reach Y" or "trace the path from A to B", splicing the trace into the response so you don't need a separate `codegraph_trace` call.
+- `codegraph_context` now inlines a URL-to-handler routing table and the source of your main routes file for routing questions on small projects, so you don't have to go read `routes.rb` or `web.php` yourself.
+- `codegraph_context` search now boosts results in the directory of a project's core framework file, so a small same-named extension file no longer outranks the actual framework core.
+- Interface-to-implementation linking now works for C#, TypeScript, JavaScript, Swift, and Scala (previously Java/Kotlin only), so investigating an interface method surfaces its concrete implementations.
+- MCP tool descriptions are now shorter, trimming per-session overhead while keeping the steering guidance.
+- Java and Kotlin imports now resolve by fully-qualified name, so same-name classes in different packages are told apart correctly in multi-module Spring and Android codebases, including across the Java/Kotlin interop boundary.
+- Java and C# anonymous classes (`new T() { ... }`) and their overridden methods are now indexed as real class nodes, so an agent sees those hidden overrides in its trail without a Read.
+- The installer no longer writes a duplicate `## CodeGraph` instructions block into your agent's instructions file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, Cursor's `.cursor/rules/codegraph.mdc`, or Kiro's steering doc) — the MCP server is now the single source of truth, and re-running `codegraph install` or `codegraph uninstall` strips a block a previous version left behind (#529). If you added your own notes inside the `CODEGRAPH_START`/`CODEGRAPH_END` markers, move them outside the markers first, since the whole marked block is removed.
+
+### Fixes
+
+- MCP tools no longer return results for files that were deleted while no server was running — the first query of a session now waits for the catch-up sync, so you get the correct index instead of stale rows.
+- Windows: black console windows no longer flash on every file save or MCP reconnect (#485, #510, #530).
+- `codegraph index` and `init -i` now report the true edge count in their summary, instead of undercounting by missing resolution and synthesizer edges.
+
+## [0.9.6] - 2026-05-27
+
+### New Features
+
+- Enterprise Spring and MyBatis flows now trace end-to-end: MyBatis XML mappers are indexed and linked to their Java mapper interfaces, Spring `@Value` and `@ConfigurationProperties` references resolve to the matching keys in your `application.yml`/`.properties` config (including relaxed kebab/camel/snake binding), and field-injected concrete beans like `this.field.method()` resolve through to their implementation (#389).
+- Gemini CLI (and the rebranded Antigravity CLI) plus the Antigravity IDE are now supported by `codegraph install`, detected and configured out of the box with sibling settings and MCP servers preserved across re-installs (#399).
+- Kiro (CLI and IDE) is now supported by `codegraph install` on macOS, Linux, and Windows, with its own steering file so it loads CodeGraph guidance naturally (#385).
+
+### Fixes
+
+- C/C++: bare `#include "header.h"` directives now connect to the real header file instead of a phantom import, so includes show up as true file-to-file edges; system and stdlib headers are filtered out so they don't false-resolve (#453).
+- Java/Kotlin: imports now disambiguate same-name classes across modules using the fully-qualified import path, so callers, callees, and trace land on the right class in multi-module projects instead of guessing by file proximity (#314).
+- TypeScript: `type` aliases with object shapes (including function-typed members and intersection types) now surface their members in the graph, so a call like `handle.stop()` resolves to the alias member instead of an unrelated look-alike class in a sibling directory (#359).
+- C#: parameter, return, property, and field types now produce reference edges, so callers and callees on a DTO or service type return real results instead of nothing (#381).
+- Go: cross-package qualified calls like `pkg.Func()` now resolve to the right package by reading your `go.mod`, so callers, callees, impact, and trace return complete results on Go monorepos instead of almost nothing (#388).
+- `codegraph_files` now returns the whole project when an agent passes a root-ish path like `/`, `.`, `./`, `""`, or a Windows-style `\`, and subdirectory filters like `/src`, `./src`, and `src\components` all resolve correctly instead of returning "No files found" (#426).
+- The file watcher no longer marks edited files as fresh when another process holds the index lock, so the per-file staleness signal stays accurate until the edit is actually indexed (#449).
+- TypeScript/JavaScript: calls inside top-level variable initializers (`const token = getToken()`) and inside inline object-literal methods are no longer dropped, so they show up in callers as expected, including in Vue single-file components (#425).
+- Watch sync no longer aborts with a `FOREIGN KEY constraint failed` error in a long-running daemon; a stale lookup now drops a single edge instead of failing the whole sync (#455).
+- Hermes: `codegraph install --target hermes` no longer corrupts `~/.hermes/config.yaml`, correctly handling PyYAML's block-style lists and re-installing cleanly even on an already-corrupted file (#456).
+- NestJS: route prefixes from `RouterModule.register([...])` (including nested `children`) now propagate to controller routes, so a route shows up at its full path like `GET /admin/users` instead of `GET /` (#459).
+- C++: callers now resolve through typed member pointers such as `m_alg->Processing()`, including out-of-line method definitions and the common case of two classes sharing a method name (#445, #454).
+
+## [0.9.5] - 2026-05-25
+
+### New Features
+
+- Running multiple AI agents in the same project no longer multiplies the cost: two Claude Code windows, a worktree agent, or parallel sub-agents now share one background daemon per project with a single file watcher, SQLite connection, and tree-sitter warm-up instead of N independent copies (#411).
+- The daemon runs detached so it outlives any single session, meaning closing one editor or terminal never severs the others; it lingers briefly after the last client disconnects so back-to-back sessions skip the startup cost, then exits and cleans up after itself. Tune the idle wait with `CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default five minutes).
+- Set `CODEGRAPH_NO_DAEMON=1` to opt out and get one independent server per client, handy for debugging or sandboxes that disallow local sockets; the daemon is also version-pinned, so upgrading CodeGraph never mixes versions over the connection.
+- CodeGraph responses now tell the agent which files are pending re-index: when the watcher has seen edits since the last sync, tool responses add a warning banner naming the stale files and their state so the agent reads just those directly while trusting the rest, with zero cost when nothing is pending (#403).
+- `CODEGRAPH_WATCH_DEBOUNCE_MS` lets you tune the file-watcher quiet window (default 2000ms) for workspaces with bursty writes like format-on-save chains or large generated outputs, without touching your agent's command line (#403).
+- Objective-C indexing: `.m`, `.mm`, and content-sniffed `.h` files now parse with full structural extraction, including full multi-part selectors, properties, imports, and superclass/protocol relationships, so trace, callers, and callees work across iOS codebases (#165).
+- Mixed iOS, React Native, and Expo projects now trace end-to-end across language boundaries: Swift to Objective-C auto-bridging, the React Native legacy bridge and TurboModules, native-to-JS event channels, Expo Modules, and Fabric/Codegen view components are all bridged so flows connect through gaps that static parsing alone can't follow (#401).
+
+### Fixes
+
+- TypeScript: types used only in an interface's property or method signatures now produce references edges, so impact and callers on a type include every consumer that imports it just for an interface shape (#432).
+- Git worktrees no longer silently borrow another tree's index; running CodeGraph from a worktree nested inside the main checkout used to return the wrong branch's code with no warning, and now both the status command and every read tool call out the conflict and point you to `codegraph init -i` in the worktree (#155).
+- The file watcher no longer exhausts the OS file-watch budget on large repos: it now excludes the same directories the indexer ignores (defaults plus your `.gitignore`) before registering watches, so CodeGraph can run alongside your editor or dev server without hitting the per-user watch ceiling (#276).
+- The index now stays in sync after `git pull`, branch switches, and edits made outside your editor; change detection is filesystem-based instead of relying on `git status`, so pulled or checked-out code is picked up without a full re-index.
+- The MCP server now catches up on connect, reconciling anything that changed while it wasn't running so your first query reflects the current code instead of a stale snapshot.
+- Dependency, build, and cache directories like `node_modules`, `vendor`, `dist`, `build`, `target`, `.venv`, `__pycache__`, `Pods`, and `.next` are now excluded by default, so context and search reflect your code instead of third-party noise even in a project with no `.gitignore`; add a `.gitignore` negation to index one anyway (#407).
+
+## [0.9.4] - 2026-05-24
+
+### New Features
+
+- Request-to-handler flows now trace end-to-end across many web stacks, with new or improved route resolution for Express, Rails, Spring (Java and Kotlin), Django/DRF, Laravel, Flask, FastAPI, Gin, chi, ASP.NET, Drupal, Axum, actix, Vapor, Play, Vue/Nuxt, Svelte/SvelteKit, and React Router.
+- `codegraph_trace`, `codegraph_callees`, and `codegraph_explore` now follow flows that have no static call edge — callback and observer registration, EventEmitter, React re-renders and JSX children, Flutter `setState` to `build`, C++ virtual overrides, and Java/Kotlin interface-to-implementation dispatch (like Spring's `@Autowired` service calls) — and each bridged hop is labeled inline in trace with where it was wired up.
+- `codegraph_trace` now returns a self-contained flow dossier: every hop shows its full body inline plus the destination's own outgoing calls, so a single trace usually answers a "how does X reach Y" question without a follow-up explore, node, or Read.
+- `codegraph_explore` now leads with the execution flow when your query names the symbols of a flow, finding the call path among those symbols (including across dynamic-dispatch hops) so you get a trace-quality answer without switching tools.
+- `codegraph_node` and `codegraph_trace` now emit line-numbered source (matching `codegraph_explore` and Read), so you can cite or edit exact lines without re-reading the file just to recover line numbers.
+- New `CODEGRAPH_MCP_TOOLS` environment variable lets you expose only a chosen subset of codegraph tools over MCP (e.g. `trace,search,node,context`) without editing your client's MCP config; unset exposes all of them.
+- Release archives now ship with a `SHA256SUMS` file, and the npm launcher verifies the bundle it downloads against it, aborting on a mismatch (releases published before this change skip verification rather than failing).
+
+### Fixes
+
+- Several static-extraction and resolution correctness fixes underpin the routing work above: C++ inheritance edges that were previously missing, Dart methods that were extracted signature-only, Python handlers named `index`/`get`/`update` that were being silently dropped, and an explore output-budget issue that under-returned source on repos with very large files.
+- `codegraph serve --mcp` no longer keeps running after its parent agent is force-killed (OOM, `kill -9`, or container teardown) on Linux, where it used to hold inotify watches, file descriptors, and the SQLite WAL indefinitely; the server now shuts down as soon as its parent process changes, tunable via `CODEGRAPH_PPID_POLL_MS` (#277).
+- Installing `@colbymchenry/codegraph` through a registry mirror that hadn't yet mirrored the matching per-platform package no longer fails with `no prebuilt bundle for <platform>`; the launcher now downloads the bundle from GitHub Releases and caches it, with `CODEGRAPH_NO_DOWNLOAD=1` to disable the fallback and `CODEGRAPH_DOWNLOAD_BASE` to point it at your own mirror (#303).
+- `install.sh` no longer fails with `403` / "could not resolve latest version" on shared or cloud hosts that exhaust GitHub's unauthenticated API rate limit; it now resolves the version through the unthrottled releases redirect, and `CODEGRAPH_VERSION` accepts a bare version like `0.9.4` as well as `v0.9.4` (#325).
+
+## [0.9.3] - 2026-05-22
+
+### New Features
+
+- New `codegraph uninstall` command cleanly removes CodeGraph from every agent it's configured on — Claude Code, Cursor, Codex CLI, opencode, and Hermes Agent — in one step, asking whether to clean up your global or this project's local config and reporting exactly which agents it touched; it accepts `--location`, `--target`, and `--yes` for scripted or non-interactive use, removes only what `codegraph install` wrote, and leaves your `.codegraph/` index alone (#313).
+
+### Fixes
+
+- Indexing a large multi-language project no longer aborts partway through with a `Fatal process out of memory: Zone` crash on Node.js 22 and 24, even with plenty of RAM free — CodeGraph now launches with a V8 flag that keeps grammar compilation off the optimizing tier, and any launch path that doesn't get the flag directly re-execs once with it automatically (#298, #293). Node 25 stays blocked for now, since its variant of this bug isn't fixed by the same flag.
+- Uninstalling from Cursor now deletes the leftover `.cursor/rules/codegraph.mdc` file outright instead of leaving an orphaned, empty rule behind, while keeping any content you added outside CodeGraph's markers.
+
+## [0.9.2] - 2026-05-21
+
+### Breaking Changes
+
+- CodeGraph no longer has a config file: `.codegraph/config.json` and the entire config surface are gone, and the library API for it (the config type, the `config` option on `init()`, and the get/update config exports) has been removed — existing config files are now ignored, and `.gitignore` is the single source of truth for what gets indexed. The `.codegraphignore` marker is also no longer supported; use `.gitignore` instead.
+
+### New Features
+
+- `codegraph install` now supports Hermes Agent (Nous Research), wiring up the CodeGraph MCP server so Hermes can drive the knowledge graph like the other agents.
+- Drupal projects (8/9/10/11) are now detected and indexed with framework smarts: routes from `*.routing.yml` link to their controller, form, or entity-handler, and hook implementations across modules are connected to their canonical hook name, so asking for callers of a hook returns every implementation (#268).
+- Indexing is now zero-config and honors your `.gitignore` everywhere — in git repos via git, and in non-git projects by reading `.gitignore` files directly — so to keep something out of the graph you just add it to `.gitignore`. Behavior change: committed files that aren't gitignored are now indexed even under `vendor/`, `Pods/`, or a committed `dist/`; add a `.gitignore` negation to exclude them (#283).
+
+### Fixes
+
+- Windows: installing globally and then running any `codegraph` command no longer fails — the launcher now invokes the bundled runtime directly instead of a `.cmd` file that modern Node refuses to spawn, so `codegraph` works regardless of your Node version (#289).
+
+### Security
+
+- The temp-dir marker written on each `codegraph_context` call is now opened safely so it can't follow a symlink, closing a hole where another local user on a shared machine could redirect that write onto a file you can write (#280).
+
+## [0.9.1] - 2026-05-21
+
+### Fixes
+
+- The standalone installers (`curl … | sh` and `irm … | iex`) no longer fail to launch on a machine that has no Node installed.
+- Installing with `npm i -g` on Linux x64 now finds its bundle, after the 0.9.0 release silently shipped without the linux-x64 package; the release pipeline now verifies every package reached the npm registry so a release can't pass green-but-broken again.
+
+## [0.9.0] - 2026-05-21
+
+CodeGraph now ships its own self-contained runtime, so it installs on any Node version — or none at all — with no native build step, and the old intermittent "database is locked" errors are gone for good.
+
+### New Features
+
+- One-line standalone installers that need no Node.js: `install.sh` on macOS and Linux, and `install.ps1` on Windows fetch the self-contained bundle and put `codegraph` on your PATH (you can still use `npm`/`npx` on any Node version too).
+- CodeGraph now uses real SQLite with full WAL and FTS5 built into its bundled runtime, which fixes the concurrent-read "database is locked" errors at the root, removes the native build step entirely, and runs faster for anyone who had been stuck on the old WASM fallback (#238).
+- Lua: CodeGraph now indexes `.lua` projects (Neovim plugins, Kong, OpenResty, game code), surfacing functions, table methods, local variables, `require(...)` imports, and the call edges between them.
+- Luau: CodeGraph now indexes `.luau`, Roblox's typed superset of Lua, adding type and `export type` aliases, typed function signatures, generics, and Roblox instance-path requires on top of everything Lua extracts (#232).
+- `codegraph status` now reports the effective journal mode, so a "database is locked" report is easy to triage at a glance.
+
+### Fixes
+
+- Re-running `codegraph install` now strips the broken auto-sync hooks that pre-0.8 versions wrote into Claude Code's settings, which had been causing a "Stop hook error: unknown command 'sync-if-dirty'" on every turn. The cleanup is surgical and leaves unrelated hooks untouched. Re-run `codegraph install` once on an affected machine to clear the error.
 
 ## [0.8.0] - 2026-05-20
 
-### Added
-- **Framework routes (NestJS)**: CodeGraph now recognises NestJS projects and
-  emits `route` nodes — each linked by a `references` edge to its handler
-  method — across all four transport layers: HTTP controllers (the
-  `@Controller` prefix joined with `@Get`/`@Post`/`@Put`/`@Patch`/`@Delete`/
-  `@Head`/`@Options`/`@All`, including empty `@Controller()`/`@Get()`),
-  GraphQL resolvers (`@Query`/`@Mutation`/`@Subscription`), microservice
-  handlers (`@MessagePattern`/`@EventPattern`), and WebSocket gateways
-  (`@SubscribeMessage`, prefixed with the gateway namespace). Detected
-  automatically from any `@nestjs/*` dependency in `package.json`. Querying a
-  controller method or resolver now surfaces the route that binds it.
-  Resolves [#220](https://github.com/colbymchenry/codegraph/issues/220).
-- **MCP / explore**: `codegraph_explore` source sections now carry line
-  numbers (cat -n style `<num>\t<code>`, matching the Read tool). This lets
-  the agent cite `file:line` straight from the explore payload instead of
-  re-opening the file just to find a line number — the dominant residual
-  cost on precise-tracing questions. In an isolated A/B (answer a
-  "which exact line" question with the relevant code already in the
-  payload), the no-line-numbers arm spent 2 file Reads + a grep recovering
-  the line number while the line-numbered arm answered with zero follow-up
-  tool calls. Payload cost is small (~3-5%). Set
-  `CODEGRAPH_EXPLORE_LINENUMS=0` to disable.
-- **MCP / watcher**: CodeGraph now skips the live file watcher on WSL2
-  `/mnt/*` drives, where recursive `fs.watch` is slow enough to break MCP
-  startup (see Fixed). When the watcher is off, `codegraph init` /
-  `codegraph install` offer to keep the index fresh via git hooks
-  (`post-commit`, `post-merge`, `post-checkout`) that run `codegraph sync`
-  in the background — accept for automatic refresh on commit / pull /
-  checkout, or decline and sync by hand. Either way you're told the index
-  stays frozen until it's re-synced. New controls: `CODEGRAPH_NO_WATCH=1`
-  (or `codegraph serve --mcp --no-watch`) forces the watcher off anywhere;
-  `CODEGRAPH_FORCE_WATCH=1` overrides the WSL auto-detect when your `/mnt`
-  setup is actually fast. `codegraph uninit` removes any hooks it installed.
-
-### Changed
-- **MCP / agent guidance**: CodeGraph now tells agents to answer "how does X
-  work" / architecture questions *directly* — `codegraph_context`, then one
-  `codegraph_explore` for the surfaced symbols — instead of delegating to a
-  file-reading sub-agent or a grep+read loop. The server instructions and the
-  installed instruction files (`CLAUDE.md`, `.cursor/rules/codegraph.mdc`,
-  `AGENTS.md`) previously suggested *spawning a sub-agent* for explore-class
-  questions, which produced the opposite, more expensive behavior: the
-  sub-agent reads files regardless of the index, so CodeGraph became overhead
-  stacked on top of the reads. In rigorous N≥4-per-arm benchmarks this cut the
-  cost of an architecture question by ~42–47% versus a no-CodeGraph agent on
-  medium and large repos (Excalidraw ~600 files, VS Code ~10k), with
-  equal-or-better, `file:line`-cited answers and ~6× fewer tool calls; on a
-  tiny repo (~25 files) it's a wash, since native grep is already trivially
-  cheap there.
-- **MCP / codegraph_node**: `includeCode=true` on a class/interface/struct/enum
-  now returns a compact member outline (fields + method signatures + line
-  numbers) instead of the entire class body — which could be thousands of
-  characters and was rarely needed in full. Functions and methods still return
-  their full body; request a specific member for its source.
-- **Minimum Node.js is now 20** (was 18). Node 18 is end-of-life and the
-  native SQLite binding (`better-sqlite3` 12.x) no longer ships a Node 18
-  prebuilt binary. Node 22 LTS and Node 24 get the native backend out of the
-  box; on other Node versions CodeGraph still runs via the WASM fallback
-  (slower, but functional). Node 25+ remains blocked (V8 WASM JIT crash, see
-  [#81](https://github.com/colbymchenry/codegraph/issues/81)).
-- **MCP / explore**: `codegraph_explore` output is now adaptive to project
-  size. The tool used to apply a fixed 35KB cap regardless of how large the
-  codebase was, which on small projects (~100 files) produced bigger
-  responses than the agent's native grep+Read flow would have — exactly the
-  scenario reported in
-  [#185](https://github.com/colbymchenry/codegraph/issues/185). The budget
-  now scales with indexed file count: small projects (<500 files) cap at
-  ~18KB and skip the "Additional relevant files" / completeness / explore-
-  budget reminders that earn their keep on bigger codebases; medium
-  (<5,000) caps at ~13KB; large (<15,000) keeps the historical ~35KB; very
-  large goes up to ~38KB. A new per-file char cap also prevents a single
-  file with many adjacent symbols from collapsing into one whole-file dump
-  (the Alamofire `Session.swift` case from #185). Per-file cluster
-  selection ranks clusters that contain a query entry point ahead of dense
-  declaration blocks, and whole-file "envelope" nodes (a class/struct that
-  spans most of the file) are excluded from clustering so the methods the
-  query asked about aren't buried under the container's opening lines.
-  Measured against the same repos used in the README benchmark, end state
-  with line numbers on: Alamofire ~60% smaller per call, Excalidraw ~32%,
-  VS Code ~12%. Agent-trust floor still holds — the Relationships section,
-  scored cluster selection, and structured-source output are all retained.
-  Thanks to [@essopsp](https://github.com/essopsp) for the repro.
-- **Search ranking (Kotlin / Swift / Scala / C#)**: test files in these
-  languages are now correctly de-prioritized in `codegraph_search`,
-  `codegraph_context`, and `codegraph affected`. Detection previously only
-  recognized `snake_case`/`.test.`-style names plus a handful of Java
-  suffixes, so CamelCase test files (`FooTest.kt`, `BarTests.swift`,
-  `BazSpec.scala`, `QuxTestCase.cs`) and Gradle / Kotlin-Multiplatform /
-  Xcode test source-set directories (`jvmTest/`, `commonTest/`,
-  `androidTest/`, `iosTest/`, `integrationTest/`) were treated as production
-  code and could outrank the real implementation. Detection now matches
-  capital-led `*Test` / `*Tests` / `*Spec` / `*TestCase` filenames and
-  source-set directories — deliberately capital-led so lowercase look-alikes
-  like `latest.kt` and `manifest.kt` are not misclassified.
-
-### Fixed
-- **MCP / explore**: `codegraph_explore` output is now hard-capped to its
-  adaptive size budget. It could previously overrun (e.g. ~30K against a 28K
-  cap) once the relationship map and trailer sections were appended; the
-  oversized payload then sat in the agent's context and was re-read on every
-  later turn.
-- **Sync / status**: git-untracked files are no longer reported as pending
-  "Added" forever. After `codegraph sync` indexed a newly-created untracked
-  source file, `codegraph status` kept listing it under Pending Changes and
-  every subsequent `sync` re-indexed it from scratch — even though its symbols
-  were already queryable. Change detection trusted `git status` and counted
-  every untracked (`??`) entry as new without checking the index, but indexing
-  a file doesn't make git track it, so the file stayed `??` and got re-added on
-  each run. CodeGraph now hash-compares untracked files against the index the
-  same way it does tracked files: a file counts as "added" only if it's missing
-  from the index, "modified" if its contents changed, and is skipped otherwise.
-  Closes [#206](https://github.com/colbymchenry/codegraph/issues/206). Thanks to
-  [@15290391025](https://github.com/15290391025) for the report.
-- **Indexing**: `codegraph init -i` now finds source inside nested, independent
-  git repositories — separate clones living inside the workspace that are **not**
-  git submodules (common in CMake "super-repo" layouts). When the top-level
-  workspace is itself a git repo, `git ls-files` reports an embedded repo only as
-  an opaque `subdir/` entry and never lists its files, so indexing from the
-  workspace root reported "No files found to index" even though indexing each
-  sub-repo individually worked. CodeGraph now detects these embedded repos and
-  indexes their tracked and untracked source, honoring each repo's own
-  `.gitignore`. Closes
-  [#193](https://github.com/colbymchenry/codegraph/issues/193). Thanks to
-  [@timxx](https://github.com/timxx) for the report.
-- **Native SQLite backend on Node 24**: indexing on Node 24 always dropped to
-  the 5-10x-slower WASM backend, printing a `better-sqlite3 unavailable`
-  warning that `npm rebuild better-sqlite3` / `xcode-select --install` could
-  not clear ([#203](https://github.com/colbymchenry/codegraph/issues/203)).
-  The bundled `better-sqlite3` was pinned to a v11 release that ships no
-  prebuilt binary for Node 24's ABI (`node-v137`), so every Node 24 install
-  silently degraded — and because CodeGraph is usually installed globally, the
-  `npm install` / `npm rebuild` people ran in their own project never touched
-  CodeGraph's copy. CodeGraph now requires `better-sqlite3` `^12.4.1`, whose
-  prebuilds include Node 24, so a fresh install on Node 22 or Node 24 gets the
-  native backend with no compiler. On an already-broken install, reinstall
-  CodeGraph (e.g. `npm install -g @colbymchenry/codegraph`) to pull the new
-  binding; `codegraph status` should then report `Backend: native`. Thanks to
-  [@Finndersen](https://github.com/Finndersen) for the report.
-- **MCP**: tools no longer fail with "CodeGraph not initialized" when the index
-  actually exists. This hit clients that launch the MCP server from a directory
-  other than your project and don't report a workspace root in `initialize`
-  (some IDE/JetBrains-family integrations) — the server fell back to its own
-  working directory, missed the project's `.codegraph/`, and returned the
-  misleading "Run 'codegraph init' first" on every call. The only workaround
-  was passing `projectPath` to each tool by hand. Now, when no project path is
-  supplied, the server asks the client for its workspace root via the standard
-  MCP `roots/list` request (when the client advertises the `roots` capability)
-  before falling back to the working directory — so detection just works for
-  spec-compliant clients. When it still can't resolve a project, the error is
-  now actionable: it names the directory it searched and tells you to pass
-  `projectPath` or add `--path /abs/project` to the server's MCP config args,
-  instead of pointing you at a re-init you don't need. Closes
-  [#196](https://github.com/colbymchenry/codegraph/issues/196). Thanks to
-  [@zhangyu1197](https://github.com/zhangyu1197) for the report and the
-  `projectPath` workaround.
-- **MCP**: the server no longer hangs on startup under WSL2 when the project
-  lives on an NTFS `/mnt/*` mount. Setting up the recursive file watcher
-  there took tens of seconds — every directory read crosses the Windows/9p
-  boundary — which blew past the host's initialization timeout (opencode's
-  30s), so the codegraph tools silently never appeared, even on small
-  projects. This is the file-watcher half of the
-  [#172](https://github.com/colbymchenry/codegraph/issues/172) startup fix:
-  that one moved the database/WASM open off the handshake, but the watcher
-  setup was still on the critical path. CodeGraph now auto-skips the watcher
-  on those mounts, with manual and git-hook sync fallbacks (see Added).
-  Closes [#199](https://github.com/colbymchenry/codegraph/issues/199).
-  Thanks to [@mengfanbo123](https://github.com/mengfanbo123) for the precise
-  root-cause analysis and workaround.
-- **Installer (Claude Code)**: project-local installs (`Just this project`)
-  now write the MCP server to `.mcp.json` in the project root — the file
-  Claude Code actually reads for project-scoped servers. Previously they
-  wrote `.claude.json`, which Claude Code ignores, so the codegraph tools
-  silently never appeared and you had to rename the file by hand to make it
-  work. Re-running `codegraph install` (or `codegraph init`) on an affected
-  project migrates the stale `.claude.json` entry into `.mcp.json`
-  automatically; uninstall cleans up both. Global (`All projects`) installs
-  were unaffected — they correctly target `~/.claude.json`. Closes
-  [#207](https://github.com/colbymchenry/codegraph/issues/207). Thanks to
-  [@Jhsmit](https://github.com/Jhsmit) for the report and the workaround.
-- **MCP**: source-omission markers in `codegraph_explore` and
-  `codegraph_context` output are now language-neutral (`... (gap) ...`,
-  `... (trimmed) ...`, `... (truncated) ...`) instead of C-style `//`
-  comments, which were misleading inside Python, Ruby, and other non-C
-  fenced source blocks.
+### Breaking Changes
+
+- The minimum supported Node.js version is now 20 (Node 18 is end-of-life); Node 22 LTS and Node 24 get the fast native backend out of the box, other Node versions still run via the slower WASM fallback, and Node 25+ remains blocked (#81). If you're on an older Node, upgrade to 20 or newer.
+
+### New Features
+
+- NestJS: CodeGraph now recognizes NestJS projects and surfaces the route that binds each handler across HTTP controllers, GraphQL resolvers, microservice handlers, and WebSocket gateways, detected automatically from any `@nestjs/*` dependency (#220).
+- `codegraph_explore` source now includes line numbers, so an agent can cite `file:line` straight from the result instead of reopening the file to find a line number; set `CODEGRAPH_EXPLORE_LINENUMS=0` to disable.
+- On WSL2 `/mnt/*` drives, where the live file watcher is too slow and could break MCP startup, CodeGraph now skips the watcher and offers to keep the index fresh with git hooks instead; new `CODEGRAPH_NO_WATCH=1` (or `serve --mcp --no-watch`) forces the watcher off anywhere, and `CODEGRAPH_FORCE_WATCH=1` overrides the WSL auto-detect when your setup is actually fast.
+- CodeGraph now guides agents to answer "how does X work" and architecture questions directly with a couple of codegraph calls instead of delegating to a file-reading sub-agent or a grep-and-read loop, which gives faster, cheaper, `file:line`-cited answers on medium and large repos.
+- `codegraph_node` with code on a class, interface, struct, or enum now returns a compact member outline (fields plus method signatures with line numbers) instead of the entire class body; functions and methods still return their full source.
+- `codegraph_explore` output now scales with project size, so small projects get tighter responses than your native grep-and-read flow would produce while large codebases keep their fuller budget, and a per-file cap stops a single dense file from collapsing into a whole-file dump (#185). Thanks @essopsp.
+- Search ranking now correctly de-prioritizes CamelCase test files (`FooTest.kt`, `BarTests.swift`, `BazSpec.scala`, `QuxTestCase.cs`) and test source-set directories in Kotlin, Swift, Scala, and C#, so real implementations no longer get outranked by tests.
+
+### Fixes
+
+- `codegraph_explore` output is now hard-capped to its size budget, so an oversized response no longer overruns the cap and sits in the agent's context to be re-read every turn.
+- Newly created untracked files are no longer reported as pending forever and re-indexed from scratch on every `codegraph sync`; CodeGraph now hash-compares them against the index the same way it does tracked files (#206). Thanks @15290391025.
+- `codegraph init -i` now finds source inside nested, independent git repositories that aren't submodules (common in CMake super-repo layouts), instead of reporting "No files found to index" (#193). Thanks @timxx.
+- On Node 24, indexing no longer silently drops to the slower fallback backend with a warning that couldn't be cleared; a fresh install on Node 22 or 24 now gets the fast native backend with no compiler, and `codegraph status` should report it (#203). Thanks @Finndersen.
+- MCP tools no longer fail with "CodeGraph not initialized" when the index actually exists; when the client doesn't report a workspace root, the server now asks for it via the standard MCP `roots/list` request before falling back, and the error message is actionable when a project still can't be resolved (#196). Thanks @zhangyu1197.
+- The MCP server no longer hangs on startup under WSL2 when the project lives on an NTFS `/mnt/*` mount, so the codegraph tools actually appear; CodeGraph auto-skips the watcher there with manual and git-hook sync fallbacks (#199). Thanks @mengfanbo123.
+- Claude Code project-local installs now write the MCP server to `.mcp.json` (the file Claude Code actually reads for project-scoped servers) instead of a file it ignores, and re-running `codegraph install` migrates an affected project automatically (#207). Thanks @Jhsmit.
+- Source-omission markers in `codegraph_explore` and `codegraph_context` output are now language-neutral instead of C-style comments, so they no longer look wrong inside Python, Ruby, and other non-C source blocks.
 
 ## [0.7.10] - 2026-05-19
 
-### Fixed
-- **MCP**: tools no longer silently fail to appear in clients on slow
-  filesystems (Docker Desktop VirtioFS on macOS, WSL2). The `initialize`
-  handshake was blocking on opening the SQLite database and bootstrapping
-  the tree-sitter WASM runtime, which on slow I/O could exceed Claude
-  Code's ~30s handshake timeout — leaving the codegraph process alive but
-  unresponsive and no tools visible. The handshake now returns immediately
-  and defers project open to the background; tool calls wait on the
-  in-flight init rather than racing it with a second open. Closes
-  [#172](https://github.com/colbymchenry/codegraph/issues/172). Thanks to
-  [@sashanclrp](https://github.com/sashanclrp) for the original report and
-  detailed reproduction, and [@sgrimm](https://github.com/sgrimm) for the
-  decisive wire capture that isolated the actual root cause.
-- **CLI**: terminal output no longer mojibakes on Windows PowerShell /
-  cmd.exe during `codegraph index` and `codegraph sync`. The shimmer
-  progress renderer writes from a worker thread via `fs.writeSync(1, …)`
-  to keep the animation smooth while the main thread is busy in SQLite,
-  which bypasses Node's TTY-aware UTF-8→codepage conversion — so glyphs
-  like `│ ◆ —` were emitted as raw UTF-8 bytes and reinterpreted as the
-  console's OEM codepage (CP437, CP936, …), producing strings like
-  `鋍?[0m 鉒?[0m Scanning files 鈥?N found`. CodeGraph now picks an ASCII
-  glyph set on Windows by default (`| * -` instead of `│ ◆ —`); set
-  `CODEGRAPH_UNICODE=1` to opt back into the Unicode glyphs (e.g. on
-  pwsh 7 with UTF-8 codepage), or `CODEGRAPH_ASCII=1` on any platform to
-  force ASCII (useful for log collectors / non-TTY pipelines). Closes
-  [#168](https://github.com/colbymchenry/codegraph/issues/168). Thanks to
-  [@starkleek](https://github.com/starkleek) for the report and to
-  [@Bortlesboat](https://github.com/Bortlesboat) for the initial PR.
-- **MCP / search**: module-qualified symbol lookups now resolve. The
-  MCP tools (`codegraph_node`, `codegraph_callees`, `codegraph_impact`,
-  …) accept `module::symbol` (Rust / C++ / Ruby), `Module.symbol`
-  (TS / JS / Python), and `module/symbol` (path-style) — multi-level
-  forms (`crate::configurator::stage_apply::run`) and Rust path
-  prefixes (`crate`, `super`, `self`) are handled. Closes
-  [#173](https://github.com/colbymchenry/codegraph/issues/173). Thanks
-  to [@joselhurtado](https://github.com/joselhurtado) for the detailed
-  reproduction. Three underlying fixes:
-    - The FTS5 query builder now treats `::` as a token separator
-      instead of stripping it to nothing, so `stage_apply::run` no
-      longer collapses to the unsearchable `stage_applyrun`.
-    - `matchesSymbol` falls back to a file-path containment check when
-      `qualifiedName` doesn't carry the module hierarchy (Rust
-      file-level functions, Python free functions in a package): a
-      `run` in `src/configurator/stage_apply.rs` now matches
-      `stage_apply::run` because `stage_apply` appears as a path
-      segment.
-    - Qualified lookups that don't match the qualifier no longer fall
-      through to fuzzy text matches — `stage_apply::nonexistent_fn`
-      returns `null` instead of resolving to an unrelated `rollback`
-      in the same file.
+### Fixes
 
-[0.8.0]: https://github.com/colbymchenry/codegraph/releases/tag/v0.8.0
-[0.7.10]: https://github.com/colbymchenry/codegraph/releases/tag/v0.7.10
+- CodeGraph tools now reliably appear in your client on slow filesystems (Docker Desktop VirtioFS on macOS, WSL2), where the startup handshake could previously time out and leave the process running with no tools visible (#172). Thanks @sashanclrp and @sgrimm.
+- On Windows PowerShell and cmd.exe, terminal output during `codegraph index` and `codegraph sync` no longer turns into garbled characters; CodeGraph now uses plain ASCII glyphs by default on Windows, with `CODEGRAPH_UNICODE=1` to opt back into the Unicode glyphs or `CODEGRAPH_ASCII=1` to force ASCII on any platform (#168). Thanks @starkleek and @Bortlesboat.
+- Module-qualified symbol lookups now resolve in the codegraph tools, so you can pass names like `module::symbol` (Rust, C++, Ruby), `Module.symbol` (TypeScript, JavaScript, Python), or `module/symbol`, including multi-level paths and Rust prefixes like `crate`, `super`, and `self` (#173). Thanks @joselhurtado.
+
+## [0.7.9] - 2026-05-17
+
+### New Features
 
-## [0.7.8] - 2026-05-17
-
-### Fixed
-- **opencode**: install actually wires up the MCP server now. v0.7.7 wrote
-  `~/.config/opencode/opencode.json`, but opencode reads `opencode.jsonc` by
-  default — so the `codegraph` entry never showed up in any opencode session.
-  The installer now prefers an existing `.jsonc`, falls back to `.json` when
-  only that exists, and creates `.jsonc` for greenfield installs. **Re-run
-  `codegraph install --target=opencode` after upgrading** so the entry lands
-  in the file opencode actually reads.
-
-### Added
-- **opencode**: installer now writes `AGENTS.md` (global
-  `~/.config/opencode/AGENTS.md`, local `./AGENTS.md`) with the same
-  codegraph usage guidance the other agents already received. Without it,
-  opencode's model would call native `Grep` instead of the `codegraph_*`
-  tools it could see in its MCP list.
-- User comments and formatting in `opencode.jsonc` survive install /
-  re-install / uninstall round-trips — surgical edits via `jsonc-parser`
-  rather than full-file rewrites.
-
-[0.7.8]: https://github.com/colbymchenry/codegraph/releases/tag/v0.7.8
+- opencode: the installer now writes an `AGENTS.md` file with CodeGraph usage guidance, so opencode reaches for the `codegraph_*` tools instead of falling back to its native search.
+- opencode: your comments and formatting in `opencode.jsonc` now survive install, re-install, and uninstall, because the installer makes surgical edits instead of rewriting the whole file.
+
+### Fixes
+
+- opencode: `codegraph install` now wires up the MCP server in the file opencode actually reads — previously it wrote to a config file opencode ignores by default, so the CodeGraph entry never appeared in any opencode session; re-run `codegraph install --target=opencode` after upgrading so the entry lands in the right place.
 
 ## [0.7.7] - 2026-05-17
 
-### Added
-- **Multi-agent installer** (closes [#137](https://github.com/colbymchenry/codegraph/issues/137)).
-  `codegraph install` now opens with a multi-select prompt for **Claude Code**,
-  **Cursor**, **Codex CLI**, and **opencode** — detected agents are pre-checked.
-  Each writes its native MCP config + instructions file (e.g. `~/.cursor/mcp.json`
-  + `.cursor/rules/codegraph.mdc`, `~/.codex/config.toml` + `~/.codex/AGENTS.md`,
-  `~/.config/opencode/opencode.json`). The runtime MCP server was already
-  agent-agnostic; this brings the installer to parity.
-- Non-interactive install flags for scripting / CI:
-  `--target=<csv|auto|all|none>`, `--location=<global|local>`, `--yes`,
-  `--no-permissions`, `--print-config <id>`.
-- `codegraph init` now auto-wires project-local agent surfaces for any agent
-  configured globally. In practice: Cursor's `.cursor/rules/codegraph.mdc`
-  is dropped on `init` so a single global `codegraph install` works in every
-  project you open — no per-project re-install needed.
-
-### Fixed
-- **Cursor**: globally-installed codegraph reported "not initialized" in every
-  workspace because Cursor launches MCP-server subprocesses with the wrong
-  working directory and doesn't pass `rootUri` in the MCP initialize call.
-  We now inject `--path` into Cursor's MCP args — absolute path for local
-  installs, `${workspaceFolder}` for global installs.
-
-### Changed
-- Agent-instructions template is now agent-agnostic. The previous template was
-  inherited from the Claude-only era and prescribed "spawn an Explore agent" —
-  a Claude Code-specific concept that confused Cursor's and Codex's agents and
-  caused them to fall back to native grep even with codegraph available. The
-  new template adds explicit "trust codegraph results, don't re-verify with
-  grep" guidance and a clear tool-by-question matrix. Applies to
-  `~/.claude/CLAUDE.md`, `.cursor/rules/codegraph.mdc`, and `~/.codex/AGENTS.md`.
-- `codegraph install` prompt order: agent picker is now step 1, before the
-  PATH-install and location prompts.
-- Disambiguated "global" wording in install prompts ("Install codegraph CLI on
-  your PATH?" vs "Apply agent configs to all your projects, or just this one?")
-  — both used to say "Global" and read as duplicates.
-
-### Internal
-- New `AgentTarget` interface in `src/installer/targets/` — adding a 5th agent
-  (Continue, Zed, Windsurf, …) is a new file + one entry in `registry.ts`.
-- Hand-rolled TOML serializer for Codex (`src/installer/targets/toml.ts`) — no
-  new dependency, scoped to the `[mcp_servers.codegraph]` table only, sibling
-  tables and `[[array_of_tables]]` preserved verbatim.
-- +47 parameterized contract tests across the 4 targets — install idempotency,
-  sibling preservation, uninstall reverses install, byte-equal re-runs return
-  `unchanged`, partial-state recovery for Codex.
-
-Based on substantive draft by [@andreinknv](https://github.com/andreinknv)
-([fork commit `c5165e4`](https://github.com/andreinknv/codegraph/commit/c5165e4)).
-Thank you.
+### New Features
 
-[0.7.7]: https://github.com/colbymchenry/codegraph/releases/tag/v0.7.7
+- `codegraph install` now sets up Claude Code, Cursor, Codex CLI, and opencode from one multi-select prompt, with any agents it detects pre-checked, so a single install wires up every editor you use (#137).
+- You can install non-interactively for scripting and CI with flags like `--target`, `--location`, `--yes`, `--no-permissions`, and `--print-config`.
+- `codegraph init` now auto-wires project-local agent config for any agent you installed globally, so one global `codegraph install` works in every project you open without re-installing per project.
+- Agent instructions are now agent-agnostic and tell each agent to trust codegraph results instead of re-verifying with grep, fixing the case where Cursor and Codex fell back to native search even with codegraph available.
+- The install prompts are clearer: the agent picker comes first, and the separate "install the CLI on your PATH" and "apply to all projects or just this one" questions no longer both read as "Global".
+
+### Fixes
+
+- Cursor: a globally-installed codegraph no longer reports "not initialized" in every workspace; the installer now passes the correct project path into Cursor's MCP config to work around Cursor launching MCP servers with the wrong working directory.
+
+Thanks @andreinknv for the substantive draft this release was based on.
 
 ## [0.7.6] - 2026-05-13
 
-### Fixed
-- `codegraph` CLI failing with `zsh: permission denied: codegraph` after a fresh
-  global install. The published 0.7.5 tarball shipped `dist/bin/codegraph.js`
-  without the executable bit, so the shell refused to run it through the npm
-  symlink. The build now `chmod +x`'s the binary before packing.
+### Fixes
 
-  Already on 0.7.5? Either upgrade to 0.7.6, or unblock yourself in place:
-  ```bash
-  chmod +x "$(npm root -g)/@colbymchenry/codegraph/dist/bin/codegraph.js"
-  ```
+- Fixed the `codegraph` command failing with `permission denied` right after a fresh global install — the 0.7.5 package shipped the CLI without its executable bit, so your shell refused to run it. New installs work out of the box. If you're stuck on 0.7.5, upgrade to 0.7.6 or unblock yourself in place by making the installed binary executable with `chmod +x`.
 
+[0.9.7]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.7
+[0.9.6]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.6
+[0.9.5]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.5
+[0.9.4]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.4
+[0.9.3]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.3
+[0.9.2]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.2
+[0.9.1]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.1
+[0.9.0]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.0
+[0.8.0]: https://github.com/colbymchenry/codegraph/releases/tag/v0.8.0
+[0.7.10]: https://github.com/colbymchenry/codegraph/releases/tag/v0.7.10
+[0.7.9]: https://github.com/colbymchenry/codegraph/releases/tag/v0.7.9
+[0.7.7]: https://github.com/colbymchenry/codegraph/releases/tag/v0.7.7
 [0.7.6]: https://github.com/colbymchenry/codegraph/releases/tag/v0.7.6
+[0.9.8]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.8
+[0.9.9]: https://github.com/colbymchenry/codegraph/releases/tag/v0.9.9
diff --git a/CLAUDE.md b/CLAUDE.md
index 3603c9470..6fe116de0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -74,12 +74,11 @@ Defined in `src/types.ts`. Both extractors and resolvers must use these exact st
 `src/installer/` is the entry point for `codegraph install` (and the bare `codegraph`/`npx @colbymchenry/codegraph` invocation). Architecture:
 
 - `targets/registry.ts` lists every supported agent.
-- `targets/types.ts` defines the `AgentTarget` interface — adding a 5th agent (Continue, Zed, Windsurf…) is **one new file in `targets/` + one entry in `registry.ts`**. Each target owns its config-file location, MCP-server JSON/TOML/JSONC writing, and instructions-file path.
+- `targets/types.ts` defines the `AgentTarget` interface — adding a 5th agent (Continue, Zed, Windsurf…) is **one new file in `targets/` + one entry in `registry.ts`**. Each target owns its config-file location and MCP-server JSON/TOML/JSONC writing. (Targets no longer write an instructions file — see below.)
 - Current targets: `claude.ts`, `cursor.ts`, `codex.ts`, `opencode.ts`.
 - `targets/toml.ts` is a hand-rolled TOML serializer scoped to `[mcp_servers.codegraph]` (used by Codex). Sibling tables and `[[array_of_tables]]` are preserved verbatim. No new dependency.
 - opencode reads `opencode.jsonc` by default; the installer prefers existing `.jsonc`, falls back to `.json`, and creates `.jsonc` for greenfield installs. Edits are surgical via `jsonc-parser` so user comments and formatting survive install/re-install/uninstall round-trips.
-- `instructions-template.ts` is the agent-agnostic instructions file written to each target (e.g. `CLAUDE.md`, `.cursor/rules/codegraph.mdc`, `~/.codex/AGENTS.md`, `~/.config/opencode/AGENTS.md`). It explicitly says "trust codegraph results, don't re-verify with grep" — earlier versions prescribed Claude-specific "spawn an Explore agent" and confused other agents.
-- `claude-md-template.ts` is the legacy Claude-only template, retained for compatibility paths.
+- `instructions-template.ts` no longer holds an instructions body — it exports only the `<!-- CODEGRAPH_START -->`/`<!-- CODEGRAPH_END -->` markers. The installer **stopped writing** a `## CodeGraph` block into each agent's instructions file (`CLAUDE.md` / `~/.codex/AGENTS.md` / `~/.config/opencode/AGENTS.md` / `~/.gemini/GEMINI.md` / `.cursor/rules/codegraph.mdc` / Kiro steering doc) because it duplicated the MCP `initialize` instructions verbatim (issue #529). Each target's `install` (self-heal on upgrade) and `uninstall` use the markers to **strip** a block a previous install left behind. `server-instructions.ts` is the single source of truth for agent-facing guidance.
 - All installer changes need matching coverage in `__tests__/installer-targets.test.ts` — there are ~47 parameterized contract tests covering install idempotency, sibling preservation, uninstall reverses install, byte-equal re-runs returning `unchanged`, and partial-state recovery for Codex.
 
 ### Cursor MCP working-directory quirk
@@ -88,7 +87,75 @@ Cursor launches MCP subprocesses with the wrong cwd and doesn't pass `rootUri` i
 
 ### MCP server instructions
 
-`src/mcp/server-instructions.ts` is sent back to the agent in the MCP `initialize` response. This is the *first* thing every agent sees about how to use the tools — treat it as the authoritative tool guidance and keep it in sync with `instructions-template.ts` and `.cursor/rules/codegraph.mdc`.
+`src/mcp/server-instructions.ts` is sent back to the agent in the MCP `initialize` response. This is the *first* thing every agent sees about how to use the tools, and as of issue #529 it is the **single source of truth** for agent-facing tool guidance — the installer no longer writes a duplicate `## CodeGraph` instructions block into `CLAUDE.md` / `AGENTS.md` / `.cursor/rules/codegraph.mdc`. Edit tool guidance here and nowhere else.
+
+## Retrieval performance & dynamic-dispatch coverage (do not regress)
+
+CodeGraph's core value is letting an agent answer **structural/flow** questions ("how does X reach Y", trace, impact, callers) with a few **fast** codegraph calls and **zero Read/Grep**. The optimization target is **wall-clock latency + tool-call count** — *don't optimize for token cost*. (Cost is **lower**, not "flat" as earlier framing claimed: a current-build with-vs-without A/B across the 7 README repos, median of 4, saved on average **35% cost · 57% tokens · 46% time · 71% tool calls** — reproducing the published README. The mechanism is **far fewer turns over a much smaller accumulated context** — NOT cache-ability: the without-arm's huge token volume is *mostly* cheap cache-reads, which is why token-count savings (57%) look bigger than cost savings (35%). Measure tokens by **summing per-turn assistant usage**, not `result.usage` (last-turn only in current Claude Code). See `docs/benchmarks/call-sequence-analysis.md`.) The mechanism that drives everything here: **an agent falls back to Read/Grep the instant a codegraph answer is insufficient.** So every change is judged by one question — is codegraph's answer sufficient enough to *stop* the agent from reading?
+
+**Target behavior:** a flow question resolves in **1 codegraph call on small repos, scaling to 3–5 on large**, with **Read/Grep = 0**. When reviewing a PR or trying something new, do not regress this.
+
+### Adapt the tool to the agent — don't try to change the agent
+
+The lever that decides whether a retrieval change lands. **Test before building anything here: does this make a tool the agent _already calls_ do more with the input it _already gives_? If it instead needs the agent to behave differently — pick a different tool, query differently, learn from examples — it hits the low-salience wall and won't land.**
+
+CodeGraph's only channels to influence the agent are low-salience: the MCP `initialize` instructions (`server-instructions.ts`) and the tool descriptions. Changing them does **not** reliably move the agent's tool _choice_ or query style — validated: trace-first steering ported into the server-instructions + tool descriptions (3 wording variants) never reproduced what a CLI `--append-system-prompt` achieved, and **regressed** wall-clock vs baseline. New tools fare worse (rarely chosen — the agent under-picks even `trace`); "better examples" is the same steering. The agent's tool-choice does improve on its own as host models get better at tool use — but that is not ours to force.
+
+What works is meeting the agent where it already is:
+- **explore-flow** — `codegraph_explore` is the PRIMARY tool the agent reliably calls; its query is a precise bag of symbol names (incl. qualified `Class.method`) spanning the flow the agent is after; explore finds the call path _among those named symbols_ (riding synthesized edges) and leads its output with it. (`buildFlowFromNamedSymbols`: segment/co-naming disambiguation; ≤1 unnamed bridge so it never wanders a god-function's fan-out. Overload-aware: a PascalCase type token in the query biases an overloaded name to that type's own def — `DataRequest task` → DataRequest's `task`, not the abstract base; named-symbol files sort first.)
+- **Sufficiency** — make the tool's output complete enough that the agent stops. `codegraph_node` returns the full body + the caller/callee trail, and for an AMBIGUOUS name returns **every overload's body in one call** (so the agent never Reads a file to find the right overload — validated on Alamofire/gin). This is the after-explore depth tool (labeled SECONDARY).
+- **Errors teach abandonment** — one or two `isError: true` responses early in a session and the agent stops calling codegraph entirely (maintainer-observed, repeatedly). `isError` is reserved for genuine "stop trying" cases: security refusals (`PathRefusalError`) and real malfunctions (which carry a retry-once note). Every expected/recoverable condition — project not indexed, symbol not found, file not in the index — returns a **SUCCESS-shaped response carrying the guidance** (`NotIndexedError` → `textResult`, see `ToolHandler.execute`'s catch). The same principle session-wide: an **unindexed workspace serves an empty `tools/list` + a 2-line "inactive" instructions variant** instead of 8 tools that all fail — absence is the one signal an agent can't misread, and indexing is deliberately the user's call, never the agent's.
+
+What fails is the inverse — folding a precise answer into a **fuzzy-input** tool: the now-removed `codegraph_context` took a description, not symbols, so it couldn't disambiguate a flow's endpoints and surfaced the _wrong feature_ (which is why it was cut). Precise output needs precise input — explore takes a symbol bag for exactly this reason. (`codegraph_trace` was likewise removed: explore-flow does its job and the agent under-picked it.)
+
+The remaining lever under this axis is **coverage**: every flow made to connect statically (a new dynamic-dispatch synthesizer, or extracting symbols static parsing skipped — e.g. object-literal store actions in `create((set,get)=>({...}))`) is then surfaced automatically by explore-flow, no agent change needed. Reactive/reconciler runtimes (Halo's `ReactiveExtensionClient`, MediatR, Vue Proxy) are the frontier — flows there have no static edges, so nothing surfaces (correctly — silent beats wrong). Full investigation + A/B record: `docs/benchmarks/call-sequence-analysis.md` + auto-memory `project_codegraph_read_displacement`.
+
+### Explore budget — keep BOTH budgets monotonic with repo size
+
+Two functions in `src/mcp/tools.ts` scale explore with indexed file count. This is the expected resolution (a regression here silently forces agents back to Read):
+
+| Repo | files | explore calls | chars/call | per-file |
+|---|---|---|---|---|
+| express (small) | 147 | 1 | 18K | 3800 |
+| excalidraw/django (medium) | 643–3043 | 2 | 28K | 6500 |
+| vscode (large) | 10446 | 3 | 35K | 7000 |
+| ~20k / ~40k | — | 4 / 5 | 38K | 7000 |
+
+- `getExploreBudget(fileCount)` → **call** budget: `<500→1, <5000→2, <15000→3, <25000→4, ≥25000→5` (max 5).
+- `getExploreOutputBudget(fileCount)` → **per-call** output (chars / files / per-file). **Invariant: a larger tier must never get a smaller `maxCharsPerFile` than a smaller tier.** (Regression that motivated this doc: the `<5000` tier's 2500 was *below* the `<500` tier's 3800, so on a god-file repo — excalidraw's 415 KB `App.tsx` — one explore returned <1% of the file and forced a Read.)
+- Explore output must **never tell the agent to "use Read"** — steer to another `codegraph_explore` and "treat returned source as already Read."
+
+### Dynamic-dispatch coverage — the flow must EXIST in the graph end-to-end
+
+Static tree-sitter extraction misses computed/indirect calls, so flows break at dynamic dispatch and the agent reads to reconstruct them. Synthesizers/resolvers bridge these so `codegraph_explore` connects them end-to-end (`src/resolution/callback-synthesizer.ts`, `src/resolution/frameworks/`). Channels today: callback/observer, EventEmitter, **React re-render** (`setState`→`render`), **JSX child** (`render`→child component), django ORM descriptor. All synthesized edges are `provenance:'heuristic'` with `metadata.synthesizedBy` + `registeredAt` (the wiring site), surfaced inline in `codegraph_explore`'s Flow section and the `codegraph_node` trail.
+
+**Principle: partial coverage is WORSE than none.** Bridging one boundary but not the next reveals a hop the agent then drills + reads to finish. Measured on excalidraw: react-render alone *raised* reads to 5–7; only completing the flow (adding the jsx-child hop) dropped it to 0–1. **Always close the flow end-to-end and re-measure** — never ship a half-bridged flow.
+
+### Validation methodology (REQUIRED for every new language/framework)
+
+For each **language × framework**, validate on **small, medium, and large** real repos with **≥3 different flow prompts** each:
+
+1. **Pick the canonical flow** for the framework ("how does X reach Y": state→render, request→handler→view, query→SQL, action→reducer→store…).
+2. **Deterministic probes** (`scripts/agent-eval/probe-{node,explore}.mjs` against the built `dist/`): `codegraph_explore` with the flow's symbol names connects from→to end-to-end with no break (its Flow section shows the path); **no node explosion** (`select count(*) from nodes` stable before/after re-index); synthesized-edge **precision** spot-check (`select … where provenance='heuristic'`).
+3. **Agent A/B** (`scripts/agent-eval/run-all.sh <repo> "<Q>"`): with vs without codegraph, **≥2 runs/arm** (run-to-run variance is large — never conclude from n=1). Record **duration, total tool calls, Read, Grep**. Optional forced-Read-0 sufficiency proof via the block-read hook (`scripts/agent-eval/hook-settings.json`).
+   - **Model policy — every A/B arm runs Claude with `--model sonnet --effort high`. Always. Never Opus/Fable.** All `scripts/agent-eval/*.sh` default to this (`MODEL`/`EFFORT` env override exists — don't raise it without an explicit reason from the maintainer). Two reasons, and the second matters more than cost: (a) Sonnet doesn't burn tokens; (b) **Sonnet is the deliberate floor model** — codegraph's real users attach it to whatever agent they already run (Cursor Composer, Gemini, etc.), so we validate on a "dumber" model on purpose: a stronger model's tool-use covers up the salience/sufficiency problems a weaker one exposes. An affordance that lands on Sonnet generalizes up to every host; one that only works on Opus/Fable doesn't generalize down to the agents most users actually have. Both arms always use the same model.
+   - **MCP attach is a startup-latency issue, not a hard block.** On a multi-step task the agent dives into Read/grep before codegraph finishes its ~2-3s startup (worse when the eval is itself run nested inside a Claude session, under CPU contention), so it runs with no codegraph. Fix: **pre-warm a persistent daemon** for the target (`CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS` high; spawn `serve --mcp --path <target> </dev/null &`; wait for `.codegraph/daemon.sock`) **and skip the startup re-exec** (`CODEGRAPH_WASM_RELAUNCHED=1`) so claude connects before the agent's first turn. Don't trust claude's `init` snapshot — it can read `status:"pending"` / 0 tools even when it then connects; judge by actual codegraph usage in `parse-run.mjs`'s `by type`. To isolate a change — **new-build vs baseline-build, both codegraph-on** (vs run-all.sh's with-vs-without) — use `scripts/agent-eval/ab-new-vs-baseline.sh <indexed-repo> "<task>" [baseline-ref]` (it bakes in the pre-warm).
+4. **Pass bar:** a normal flow question reaches **~0 Read/Grep within the repo's explore-call budget**, runs **faster** than without-codegraph, and shows **no regression on a control repo**. Record the numbers in `docs/design/dynamic-dispatch-coverage-playbook.md` (the coverage matrix).
+
+Full playbook + per-mechanism design: `docs/design/dynamic-dispatch-coverage-playbook.md` and `docs/design/callback-edge-synthesis.md`.
+
+### Worked example — Excalidraw (TS/React, medium, 643 files)
+
+The template to replicate per language/framework. Question: *"how does updating an element re-render the canvas on screen?"* (the full flow crosses three React boundaries: observer callback, `setState`→`render`, and JSX child).
+
+| Stage | duration | Read | Grep | codegraph |
+|---|---|---|---|---|
+| Without codegraph | 115–139s | 9–10 | 10–11 | 0 |
+| Broken (explore-budget regression) | 131–139s | 5–10 | 3–5 | 6–14 |
+| Fixed (budget + msgs + synthesis) | 64–112s | 0–2 | 2–4 | 3–**10** |
+| + trace-first steering | **51–74s** | **0–2** | 0–4 | **3–4** |
+
+n=4 unhooked runs/stage, same prompt. After steering flow questions to `codegraph_trace` first: **best run 0 Read / 0 Grep / 3 codegraph / 51s**; **2 of 4 fully clean** (0 Read, 0 Grep). Steering eliminated the over-drill variance — call count tightened from 3–10 to 3–4, trace adoption went 3/4 → 4/4, and the `search`+`callers` path-reconstruction floundering dropped to 0. Run-to-run variance is still real; report the range, never a single run. **Residual reads/greps are all the nonce data-flow** (`canvasNonce` — a local prop with no graph edges); that's the def-use/data-flow frontier, left deliberately uncovered (tracking every local would explode the graph). Validated: `trace(mutateElement, renderStaticScene)` connects in **6 hops** across all three boundaries (`mutateElement → triggerUpdate → [callback] triggerRender → [react-render] render → [jsx] StaticCanvas → renderStaticScene`), each hop showing inline source + the wiring site; node count stable at 9,289; 1 callback + 46 react-render + 280 jsx-render synthesized edges (no explosion, precision-checked).
 
 ## Tests
 
@@ -101,37 +168,102 @@ Tests live in `__tests__/` and mirror the module they cover. Notable ones beyond
 
 Tests create temp dirs with `fs.mkdtempSync` and clean up in `afterEach`. They write real files and exercise real SQLite — there is no DB mocking.
 
+### Windows-gated tests
+
+Behavior that differs by platform (path resolution, drive letters, `SENSITIVE_PATHS`, `%APPDATA%` config dirs, CRLF) must be gated, not assumed. Use `it.runIf(process.platform === 'win32')(...)` for Windows-only assertions and `it.runIf(process.platform !== 'win32')(...)` for POSIX-only ones — e.g. `/etc` is sensitive on POSIX but resolves to `C:\etc` (non-existent) on Windows, so an ungated `/etc` assertion fails on Windows. Validate the Windows side for real (see below); don't merge a Windows-gated test you haven't seen run.
+
+## Cross-platform validation
+
+The dev machine — and the default `npm test` target — is **macOS**, so local runs cover the macOS path. The other two platforms aren't here; when a change is platform-sensitive (file watching, sockets / named pipes, path & symlink handling, process lifecycle, inotify budget) validate them for real rather than guessing.
+
+### Linux (Docker)
+
+When asked to test or validate on Linux, use **Docker** — there's no Linux box, but Docker runs on the macOS host. Build a throwaway image from the repo and run the suite inside it:
+
+- `FROM node:22-bookworm`; `COPY` the repo with a `.dockerignore` excluding `node_modules`/`dist`/`.git`/`.codegraph`; `RUN npm ci && npm run build`. Don't reuse the Mac `node_modules` — `esbuild`/`rollup` ship platform-specific binaries.
+- Run with **`docker run --rm --init`**. The `--init` is load-bearing for any process-lifecycle test (daemon reaping, the #277 PPID watchdog, idle-timeout): without a zombie-reaping PID 1, a SIGKILL'd/exited process lingers as a zombie and `process.kill(pid, 0)` still reports it *alive*, so exit-detection assertions false-fail even though the process did exit.
+- Linux is where the inotify watch budget actually bites: count a process's watches via `/proc/<pid>/fdinfo/*` (sum `^inotify ` lines on the fd whose `readlink` is `anon_inode:inotify`).
+
+### Windows (Parallels VM + SSH)
+
+For any Windows-specific PR, bug, or implementation, validate it on the real Windows VM rather than guessing. Connection details live in the gitignored **`.parallels`** file at the repo root (VM name, guest IP, SSH user/key). `prlctl exec` needs Parallels Pro and is unavailable, so SSH is the bridge.
+
+- Connect / run from the Mac host: `ssh <user>@<guest_ip> "..."`. For multi-line work, pipe PowerShell over stdin and **refresh PATH from the registry** first (sshd's session has a stale PATH after winget installs):
+  ```
+  ssh colby@10.211.55.3 "powershell -NoProfile -ExecutionPolicy Bypass -Command -" <<'PS'
+  $env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")
+  Set-Location C:\dev\codegraph
+  PS
+  ```
+- Clone fresh into a **Windows-local** path (`C:\dev\codegraph`) and `npm ci` there — never run npm against the shared Mac repo, since `esbuild`/`rollup` ship platform-specific binaries.
+- Guest toolchain (winget): Node LTS, Git, and the **VC++ ARM64 redistributable** (required by `@rollup/rollup-win32-arm64-msvc`, which vitest pulls in).
+- Fetch a contributor PR head straight from their fork to dodge `pull/<n>/head` lag: `git fetch <fork-url> <branch>` then `git checkout -f FETCH_HEAD`.
+- Known pre-existing Windows failures (they reproduce on `main`, unrelated to your change — confirm against `origin/main` before blaming your PR, and don't let them mask new regressions): `security.test.ts > Session marker symlink resistance > does not follow a pre-planted symlink` (symlink creation needs privileges on Windows); and the `mcp-initialize.test.ts` / `mcp-roots.test.ts` suites, which fail in `afterEach` with `EPERM` removing the temp dir because a spawned `serve --mcp` (its `--liftoff-only` re-exec grandchild) still holds the cwd / SQLite file open — a Windows file-locking quirk, not a logic bug.
+
 ## Releases
 
 Released to npm and mirrored as [GitHub Releases](https://github.com/colbymchenry/codegraph/releases). `CHANGELOG.md` is the source of truth; GitHub Release notes are extracted from it.
 
 ### Writing changelog entries
 
-When asked for an entry for a new version:
+**Default: write entries under `## [Unreleased]`** — that's the section reserved for work landing between releases. **Don't pre-create a `## [X.Y.Z]` block** for the next release: the Release workflow's first step is `scripts/prepare-release.mjs`, which automatically promotes everything under `[Unreleased]` into a new `## [X.Y.Z] - <YYYY-MM-DD>` block at release time (or merges into a pre-existing `[X.Y.Z]` block if one exists — but you don't need one). Pre-staging is what caused the v0.9.5 sparse-release-notes incident: a sparse `[0.9.5]` block hand-added before the rest of the work landed got picked by the extractor over the much-larger `[Unreleased]` section above it. Don't do that.
 
-1. Add a new `## [X.Y.Z] - YYYY-MM-DD` block at the **top** of `CHANGELOG.md` (under the intro, above the previous version).
-2. Group under `### Added`, `### Changed`, `### Fixed`, `### Removed`, `### Deprecated`, `### Security` — omit empty sections.
-3. Write from the **user's perspective**, not the implementation's. Lead with the observable symptom or capability; mention internals only if a user needs them (e.g., to work around an existing bad install).
-4. Add the link reference at the bottom: `[X.Y.Z]: https://github.com/colbymchenry/codegraph/releases/tag/vX.Y.Z`.
+Formatting rules for any entry (anywhere — `[Unreleased]` or otherwise):
 
-### Release flow (the user runs these)
+1. **Write friendly, user-facing notes — not engineer-facing ones.** Group under `### New Features` and `### Fixes` (sentence-case). Surface `### Breaking Changes` and `### Security` as their own sections **only when the release has them**; fold improvement-flavored changes into New Features. Omit empty sections. (This replaces the old Keep-a-Changelog `Added/Changed/Fixed/Removed/Deprecated` grouping: the GitHub Release page extracts each version block **verbatim** via `scripts/extract-release-notes.mjs`, and the old dense, implementation-focused entries rendered as an unreadable wall of text — so the whole CHANGELOG was rewritten to this format and every published release re-noted to match.)
+2. **One plain-language sentence per bullet:** what changed and why it matters to a user. Lead with the capability, or with the symptom that's now fixed.
+3. **Strip the internals.** No internal file paths (`src/...`), no internal symbol / function / class names, no benchmark numbers / percentages / node-or-edge counts. **Keep:** language & framework names (Go, Spring, NestJS, …), things a user types or sets (`codegraph install`, `codegraph_explore`, the `CODEGRAPH_*` env vars), agent / IDE names (Claude Code, Cursor, opencode, Kiro, …), and a brief `Thanks @user` when a contributor is credited.
+4. Issue / PR references in entries are by number (`(#403)` etc.); the GitHub renderer auto-links them in the published release notes.
+5. **Don't add a `[X.Y.Z]: https://...` link reference yourself** — `prepare-release.mjs` appends it automatically when it promotes the version (idempotent: a re-run is a no-op if it already exists).
 
-After the changelog entry is written and `package.json` is bumped:
+Multi-word headings like `### New Features` are safe on the normal release path: `prepare-release.mjs` **Case A** moves the whole `[Unreleased]` body verbatim into `[X.Y.Z]`. (Only its rarely-used **Case B** *merge* splits sub-sections with a single-word `^### (\w+)$` regex that wouldn't match them — and Case B fires only if a `[X.Y.Z]` block was pre-created, which rule above already forbids.)
 
-```bash
-git add package.json package-lock.json CHANGELOG.md
-git commit -m "release: X.Y.Z (<one-line summary>)"
-git push
-npm publish
-./scripts/release.sh   # idempotent: tags vX.Y.Z, pushes, creates GitHub Release with notes from CHANGELOG.md
-```
-
-`scripts/release.sh` is safe to re-run after a partial failure — it skips steps already done (tag exists locally, tag on origin, release published). It extracts release notes from `CHANGELOG.md` by matching the `## [X.Y.Z]` block.
+### Release flow (the user runs these)
 
-**Do not run `npm publish`, `git push`, `git tag`, or `./scripts/release.sh` yourself** — these are publish actions on shared state. Write the file, hand the user the commands.
+Releases are built and published by the **GitHub Actions "Release" workflow**
+(`.github/workflows/release.yml`). It runs `scripts/prepare-release.mjs` to
+promote `[Unreleased]` into `[<version>]` (and auto-commit + push that
+CHANGELOG change back to `main` so on-disk truth matches the published
+notes), then bundles a Node runtime per platform (`scripts/build-bundle.sh`)
+and publishes both the GitHub Release and the npm thin-installer
+(`scripts/pack-npm.sh`: a shim package + per-platform packages).
+Publishing manually is **wrong** now — a plain `npm publish` ships the root
+package (non-bundled), which breaks anyone on Node < 22.5.
+
+**Claude does NOT bump the version unless explicitly asked.** The maintainer
+typically does it themselves — often by editing `package.json` directly via
+the GitHub web UI. Don't proactively commit a version bump as part of
+unrelated work, and don't propose one when summarizing a PR.
+
+When the maintainer DOES bump the version, the only edit strictly required is
+to `package.json` — the workflow's "Sync package-lock.json" step detects a
+mismatch between `package.json` and `package-lock.json`, runs
+`npm install --package-lock-only --ignore-scripts` to rewrite the lock file's
+version fields (top-level + `packages.""`), and auto-commits + pushes the
+result back to `main` with `[skip ci]`. So a GitHub-web-UI single-file edit to
+`package.json` is enough to kick off a clean release. (If they edit both files
+locally, that's fine too — the sync step no-ops.)
+
+Once `package.json` is at the target version on `main`, trigger
+**Actions → Release → Run workflow** (on `main`). The workflow:
+
+1. Syncs `package-lock.json` to `package.json`'s version if they've drifted; commits + pushes that change.
+2. Runs `prepare-release.mjs <X.Y.Z>` → promotes `[Unreleased]` → `[X.Y.Z] - <today>` in `CHANGELOG.md`, appends the link reference, commits + pushes the move with `[skip ci]`.
+3. Builds every platform bundle on one runner, generates `SHA256SUMS`.
+4. Creates the GitHub Release with notes from the freshly-promoted `[X.Y.Z]` block.
+5. Publishes the npm shim + per-platform packages. Requires the `NPM_TOKEN` repo secret.
+
+**Do not run `npm publish`, `git push`, or `git tag` yourself** — these are
+publish actions on shared state. Write the files, hand the user the commands.
 
 ## House rules
 
 - The `0.7.x` line is in active multi-agent rollout. Any change to `src/installer/` (especially `targets/`) needs corresponding test coverage and a CHANGELOG entry — installer regressions break every new install silently.
-- When changing what the MCP tools do or how agents should use them, update **all three** of `src/mcp/server-instructions.ts`, `src/installer/instructions-template.ts`, and `.cursor/rules/codegraph.mdc` — they're written to different places but say the same thing.
+- When changing what the MCP tools do or how agents should use them, edit `src/mcp/server-instructions.ts` — it is the **single source of truth** for agent-facing tool guidance (issue #529). The installer no longer writes a duplicate instructions block into `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / `.cursor/rules/codegraph.mdc` / Kiro steering, so there's nothing to keep in sync anymore. (The repo's own checked-in `.cursor/rules/codegraph.mdc` is dogfooding config — update it too if you use Cursor on this repo, but it ships nowhere.)
 - CodeGraph provides **code context**, not product requirements. For new features, ask the user about UX, edge cases, and acceptance criteria — the graph won't tell you.
+- **When the user references issues, PR comments, or external reports, anchor them to a date and version before drawing conclusions.** Check the comment's `createdAt` against:
+  - The **last released version** — `grep -m1 '^## \[' CHANGELOG.md` shows the top-of-file version (older releases follow). A comment dated before the latest `## [X.Y.Z] - YYYY-MM-DD` is reacting to *released* state — work that's only on `main` or on an unmerged branch doesn't apply.
+  - The **last main commit** — `git log --first-parent main -1 --format='%ai %h %s'`. A comment after the last release but before a fix on main may already be addressed there but unreleased.
+  - The **current branch's tip** — your own unmerged work obviously can't be what the comment is reacting to.
+  Always disambiguate "released," "merged-but-unreleased," and "in-progress" before agreeing that a user-reported problem is unfixed (or that a fix is incomplete). A user saying "your fix only covers X" about a recent PR is usually pointing at the *released* shortcomings — your in-flight branch may already address them but they have no way to know that.
+- **Version-tag every image referenced in `README.md`.** GitHub caches README images (`raw.githubusercontent.com` with a 5-minute TTL; third-party hosts sit behind the long-lived camo proxy), so updating an asset in place can keep showing the stale version. Give each README image URL a `?v=N` query tag and **bump `N` in the same commit whenever the asset bytes change** — e.g. `assets/waitlist.svg?v=2`. The changed URL sidesteps every cache so the new image shows immediately instead of waiting on a TTL to expire.
diff --git a/README.md b/README.md
index d4dc3bf81..bb86a697b 100644
--- a/README.md
+++ b/README.md
@@ -2,44 +2,98 @@
 
 # CodeGraph
 
-### Supercharge Claude Code, Cursor, Codex, and OpenCode with Semantic Code Intelligence
+### Supercharge Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity, and Kiro with Semantic Code Intelligence
 
-**~35% cheaper · ~70% fewer tool calls · 100% local**
+**~16% cheaper · ~58% fewer tool calls · 100% local**
+
+### [Documentation & Website →](https://colbymchenry.github.io/codegraph/)
 
 [![npm version](https://img.shields.io/npm/v/@colbymchenry/codegraph.svg)](https://www.npmjs.com/package/@colbymchenry/codegraph)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/badge/Node.js-20--24-green.svg)](https://nodejs.org/)
+[![Self-contained](https://img.shields.io/badge/Node.js-bundled%20%C2%B7%20none%20required-brightgreen.svg)](https://nodejs.org/)
+
+[![Windows](https://img.shields.io/badge/Windows-supported-blue.svg)](#supported-platforms)
+[![macOS](https://img.shields.io/badge/macOS-supported-blue.svg)](#supported-platforms)
+[![Linux](https://img.shields.io/badge/Linux-supported-blue.svg)](#supported-platforms)
+
+[![Claude Code](https://img.shields.io/badge/Claude_Code-supported-blueviolet.svg)](#supported-agents)
+[![Cursor](https://img.shields.io/badge/Cursor-supported-blueviolet.svg)](#supported-agents)
+[![Codex](https://img.shields.io/badge/Codex-supported-blueviolet.svg)](#supported-agents)
+[![opencode](https://img.shields.io/badge/opencode-supported-blueviolet.svg)](#supported-agents)
+[![Hermes Agent](https://img.shields.io/badge/Hermes_Agent-supported-blueviolet.svg)](#supported-agents)
+[![Gemini](https://img.shields.io/badge/Gemini-supported-blueviolet.svg)](#supported-agents)
+[![Antigravity](https://img.shields.io/badge/Antigravity-supported-blueviolet.svg)](#supported-agents)
+[![Kiro](https://img.shields.io/badge/Kiro-supported-blueviolet.svg)](#supported-agents)
+
+<br>
 
-[![Windows](https://img.shields.io/badge/Windows-supported-blue.svg)](#)
-[![macOS](https://img.shields.io/badge/macOS-supported-blue.svg)](#)
-[![Linux](https://img.shields.io/badge/Linux-supported-blue.svg)](#)
+**The CodeGraph platform is coming** — for every PR, know exactly what to test, what could break, which flows are affected, and whether business logic is compromised.
 
-[![Claude Code](https://img.shields.io/badge/Claude_Code-supported-blueviolet.svg)](#)
-[![Cursor](https://img.shields.io/badge/Cursor-supported-blueviolet.svg)](#)
-[![Codex CLI](https://img.shields.io/badge/Codex_CLI-supported-blueviolet.svg)](#)
-[![opencode](https://img.shields.io/badge/opencode-supported-blueviolet.svg)](#)
+<a href="https://getcodegraph.com"><img alt="Join the waitlist for early beta access" src="https://raw.githubusercontent.com/colbymchenry/codegraph/main/assets/waitlist.svg?v=2" height="52"></a>
+
+<sub>Get <b>early beta access</b> to the hosted product · <a href="https://getcodegraph.com">getcodegraph.com</a></sub>
+
+</div>
 
-<br />
+## Get Started
 
-### Get Started
+### 1. Install the CLI
+
+**No Node.js required** — one command grabs the right build for your OS:
 
 ```bash
-npx @colbymchenry/codegraph
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
 ```
 
-<sub>Interactive installer auto-configures your agent(s) — Claude Code, Cursor, Codex CLI, opencode</sub>
+Already have Node? Use npm instead (works on any version):
+
+```bash
+npm i -g @colbymchenry/codegraph
+```
 
-#### Initialize Projects
+<sub>CodeGraph bundles its own runtime — nothing to compile, no native build, works the same everywhere. The installer puts `codegraph` on your PATH but **doesn't change your current shell** — open a new terminal before the next step so the command resolves.</sub>
+
+<sub>**Upgrade any time** with `codegraph upgrade` — it detects how you installed (bundle, npm, or npx) and updates in place. Add `--check` to see if an update is available, or `codegraph upgrade <version>` to pin one.</sub>
+
+### 2. Wire up your agent(s)
+
+In a **new terminal**, run the installer to connect CodeGraph to the agents you use:
+
+```bash
+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>
+
+### 3. Initialize each project
 
 ```bash
 cd your-project
 codegraph init -i
 ```
 
+<sub>`codegraph init` just creates the local `.codegraph/` index directory; adding `-i` (`--index`) also builds the initial graph in the same step. Without `-i`, run `codegraph index` afterwards to populate it.</sub>
+
+<div align="center">
+
 ![1_C_VYnhpys0UHrOuOgpgoyw](https://github.com/user-attachments/assets/f168182f-4d9a-44e0-94d7-08d018cc8a3a)
 
 </div>
 
+### Uninstall
+
+Changed your mind? One command removes CodeGraph from every agent it configured:
+
+```bash
+codegraph uninstall
+```
+
+<sub>Reverses the installer — strips CodeGraph's MCP server config, instructions, and permissions from each configured agent. Your project indexes (`.codegraph/`) are left untouched; remove those per-project with `codegraph uninit`. Use `--target` to remove from specific agents, or `--yes` to run non-interactively.</sub>
+
 ---
 
 ## Why CodeGraph?
@@ -50,26 +104,101 @@ When Claude Code explores a codebase, it spawns **Explore agents** that scan fil
 
 ### 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**.
+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)._
 
-> **Average: 35% cheaper · 59% fewer tokens · 49% faster · 70% fewer tool calls**
+> **Average: 16% cheaper · 47% fewer tokens · 22% faster · 58% fewer tool calls**
 
 | Codebase | Language | Cost | Tokens | Time | Tool calls |
 |----------|----------|------|--------|------|------------|
-| **VS Code** | TypeScript · ~10k files | 35% cheaper | 73% fewer | 41% faster | 72% fewer |
-| **Excalidraw** | TypeScript · ~600 | 47% cheaper | 73% fewer | 60% faster | 86% fewer |
-| **Django** | Python · ~2.7k | 34% cheaper | 64% fewer | 59% faster | 81% fewer |
-| **Tokio** | Rust · ~700 | 52% cheaper | 81% fewer | 63% faster | 89% fewer |
-| **OkHttp** | Java · ~640 | 17% cheaper | 41% fewer | 36% faster | 64% fewer |
-| **Gin** | Go · ~150 | 22% cheaper | 23% fewer | 34% faster | 19% fewer |
-| **Alamofire** | Swift · ~100 | 38% cheaper | 59% fewer | 51% faster | 77% fewer |
+| **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 gains scale with codebase size: on large repos the agent answers from the index in a handful of calls with **zero file reads**, while the no-CodeGraph agent fans out across grep/find/Read (and the sub-agents it spawns). On a small repo like Gin (~150 files) native search is already cheap, so the margin narrows.
+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.
+
+<details>
+<summary><strong>Per-repo breakdown — WITH vs WITHOUT (median of 4)</strong></summary>
+
+**VS Code** · ~10k files
+| Metric | WITH cg | WITHOUT cg | Δ |
+|---|---|---|---|
+| Time | 1m 59s | 2m 13s | 11% faster |
+| File Reads | 0 | 9 | −9 |
+| Grep/Bash | 0 | 11 | −11 |
+| Tool calls | 4 | 21 | 81% fewer |
+| Total tokens | 640k | 1.79M | 64% fewer |
+| Cost | $0.68 | $0.83 | 18% cheaper |
+
+**Excalidraw** · ~640 files
+| Metric | WITH cg | WITHOUT cg | Δ |
+|---|---|---|---|
+| Time | 1m 32s | 2m 6s | 27% faster |
+| File Reads | 0 | 7 | −7 |
+| Grep/Bash | 1 | 8 | −7 |
+| Tool calls | 9 | 15 | 40% fewer |
+| Total tokens | 1.27M | 1.69M | 25% fewer |
+| Cost | $0.78 | $0.78 | even |
+
+**Django** · ~3k files
+| Metric | WITH cg | WITHOUT cg | Δ |
+|---|---|---|---|
+| Time | 1m 43s | 1m 58s | 13% faster |
+| File Reads | 0 | 9 | −9 |
+| Grep/Bash | 0 | 5 | −5 |
+| Tool calls | 3 | 13 | 77% fewer |
+| Total tokens | 559k | 1.41M | 60% fewer |
+| Cost | $0.57 | $0.62 | 8% cheaper |
+
+**Tokio** · ~790 files
+| Metric | WITH cg | WITHOUT cg | Δ |
+|---|---|---|---|
+| Time | 1m 55s | 2m 20s | 18% faster |
+| File Reads | 0 | 8 | −8 |
+| Grep/Bash | 0 | 6 | −6 |
+| Tool calls | 6 | 14 | 57% fewer |
+| Total tokens | 1.08M | 1.73M | 38% fewer |
+| Cost | $0.82 | $0.82 | even |
+
+**OkHttp** · ~645 files
+| Metric | WITH cg | WITHOUT cg | Δ |
+|---|---|---|---|
+| Time | 1m 1s | 1m 29s | 31% faster |
+| File Reads | 0 | 4 | −4 |
+| Grep/Bash | 2 | 6 | −4 |
+| Tool calls | 5 | 10 | 50% fewer |
+| Total tokens | 502k | 1.10M | 54% fewer |
+| Cost | $0.41 | $0.55 | 25% cheaper |
+
+**Gin** · ~110 files
+| Metric | WITH cg | WITHOUT cg | Δ |
+|---|---|---|---|
+| Time | 1m 14s | 1m 37s | 24% faster |
+| File Reads | 1 | 6 | −5 |
+| Grep/Bash | 1 | 2 | −1 |
+| Tool calls | 5 | 9 | 44% fewer |
+| Total tokens | 651k | 847k | 23% fewer |
+| Cost | $0.46 | $0.57 | 19% cheaper |
+
+**Alamofire** · ~110 files
+| Metric | WITH cg | WITHOUT cg | Δ |
+|---|---|---|---|
+| Time | 1m 35s | 2m 21s | 33% faster |
+| File Reads | 0 | 9 | −9 |
+| Grep/Bash | 0 | 4 | −4 |
+| Tool calls | 5 | 12 | 58% fewer |
+| Total tokens | 766k | 2.10M | 64% fewer |
+| Cost | $0.57 | $0.95 | 40% cheaper |
+
+</details>
 
 <details>
 <summary><strong>Full benchmark details</strong></summary>
 
-**Methodology.** Each arm is `claude -p` (Claude Opus 4.7, Claude Code v2.1.145) run headlessly against the repo with `--strict-mcp-config`: **WITH** = CodeGraph's MCP server enabled, **WITHOUT** = an empty MCP config. Built-in Read/Grep/Bash stay available to both. Same question per repo, **4 runs per arm, median reported**. Cost = the run's `total_cost_usd`; Tokens = total tokens processed (input incl. cached + output); Time = wall-clock; Tool calls = every tool invocation, including those inside any sub-agents the model spawns. Repos cloned at `--depth 1` and indexed by the same CodeGraph build that served them.
+**Methodology.** Each arm is `claude -p` (Claude Opus 4.8) run headlessly against the repo with `--strict-mcp-config`: **WITH** = CodeGraph's MCP server enabled, **WITHOUT** = an empty MCP config. Built-in Read/Grep/Bash stay available to both. Same question per repo, **4 runs per arm, median reported**. Cost = the run's `total_cost_usd`; Tokens = total tokens processed (input incl. cached + output); Time = wall-clock; Tool calls = every tool invocation, including those inside any sub-agents the model spawns. Repos cloned at `--depth 1` and indexed by the same CodeGraph build that served them. Re-validated 2026-06-02 on the current build. These numbers are lower than the prior Opus 4.7 validation — not a CodeGraph regression but a stronger native baseline: Opus 4.8 greps/reads efficiently on the main thread instead of fanning out into large Explore-subagent sweeps, so the no-CodeGraph arm is leaner than it used to be. Per-repo numbers move run-to-run with how hard the without-arm thrashes (the median-of-4 smooths it, but tails remain — e.g. Django's without-arm hit $2.71/14m one batch).
 
 **Queries:**
 | Codebase | Query |
@@ -82,18 +211,7 @@ The gains scale with codebase size: on large repos the agent answers from the in
 | Gin | "How does gin route requests through its middleware chain?" |
 | Alamofire | "How does Alamofire build, send, and validate a request?" |
 
-**Raw medians — WITH → WITHOUT:**
-| Codebase | Cost | Tokens | Time | Tool calls |
-|----------|------|--------|------|------------|
-| VS Code | $0.42 → $0.64 | 393k → 1.4M | 1m 0s → 1m 43s | 7 → 23 |
-| Excalidraw | $0.54 → $1.02 | 851k → 3.2M | 1m 17s → 3m 14s | 12 → 83 |
-| Django | $0.41 → $0.62 | 499k → 1.4M | 1m 0s → 2m 25s | 9 → 48 |
-| Tokio | $0.50 → $1.04 | 657k → 3.4M | 1m 5s → 2m 56s | 9 → 75 |
-| OkHttp | $0.36 → $0.44 | 352k → 596k | 45s → 1m 11s | 5 → 14 |
-| Gin | $0.36 → $0.46 | 431k → 562k | 47s → 1m 11s | 7 → 8 |
-| Alamofire | $0.61 → $0.99 | 1.1M → 2.6M | 1m 19s → 2m 41s | 15 → 64 |
-
-**Why CodeGraph wins:** with the index available, the agent answers directly — `codegraph_context` to map the area, then one `codegraph_explore` for the relevant source — and stops, usually with zero file reads. Without it, the agent (and the Explore sub-agents it spawns) spends most of its budget on discovery (find/ls/grep) before reading the right code. CodeGraph only helps when queried *directly*, so its instructions steer agents to answer directly rather than delegate exploration to file-reading sub-agents — otherwise a sub-agent reads files regardless and CodeGraph becomes overhead.
+**Why CodeGraph wins:** with the index available, the agent answers directly — usually one `codegraph_explore` returns the relevant source — and stops, usually with zero file reads. Without it, the agent spends most of its budget on discovery (find/ls/grep) before reading the right code. CodeGraph only helps when queried *directly*, so its instructions steer agents to answer directly rather than delegate exploration to file-reading sub-agents — otherwise a sub-agent reads files regardless and CodeGraph becomes overhead.
 
 </details>
 
@@ -107,10 +225,38 @@ The gains scale with codebase size: on large repos the agent answers from the in
 | **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 |
-| **19+ Languages** | TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Lua, Luau, Svelte, Liquid, Pascal/Delphi |
-| **Framework-aware Routes** | Recognizes web-framework routing files and links URL patterns to their handlers across 13 frameworks |
+| **20+ Languages** | TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Objective-C, Swift, Kotlin, Scala, Dart, Lua, Luau, Svelte, Vue, Astro, Liquid, Pascal/Delphi |
+| **Framework-aware Routes** | Recognizes web-framework routing files and links URL patterns to their handlers across 17 frameworks |
+| **Mixed iOS / React Native / Expo** | Closes cross-language flows that static parsing misses: Swift ↔ ObjC bridging, React Native legacy bridge + TurboModules + Fabric view components, native → JS event emitters, Expo Modules |
 | **100% Local** | No data leaves your machine. No API keys. No external services. SQLite database only |
 
+<details>
+<summary><strong>How auto-syncing works — and why you don't need to run <code>codegraph sync</code> manually</strong></summary>
+
+When your agent (Claude Code, Cursor, Codex, opencode) launches `codegraph serve --mcp`, three layers keep the index in step with your code — and make sure the agent never gets a silent wrong answer in the brief window between an edit and the next sync:
+
+1. **File watcher with debounced auto-sync.** A native FSEvents / inotify / ReadDirectoryChangesW watcher captures every source-file create / modify / delete and triggers a re-index after a debounce window (default `2000ms`, tunable via `CODEGRAPH_WATCH_DEBOUNCE_MS`, clamped to `[100ms, 60s]`). Bursts of edits collapse into a single sync.
+
+2. **Per-file staleness banner.** During the brief debounce window, MCP tool responses that would reference a still-pending file prepend a `⚠️` banner naming it and telling the agent to `Read` it directly. Pending files NOT referenced by the response surface as a small footer instead. Either way, the agent gets an explicit signal — validated with Claude Code, where the agent literally says "Reading the file directly for the live content" before opening it.
+
+3. **Connect-time catch-up.** When the MCP server (re)connects, codegraph runs a fast `(size, mtime)` + content-hash reconciliation against the working tree before answering the first query — so edits made while no MCP server was running (a `git pull` from the terminal, edits from another editor, a previous agent session that exited) get absorbed on the next session's first tool call.
+
+```
+agent writes src/Widget.ts
+  → watcher fires (<100ms)
+  → debounce (default 2s)
+  → sync; Widget.ts is in the index
+  → 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.
+
+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.
+
+→ Full deep-dive in [Guides → Indexing a Project](https://colbymchenry.github.io/codegraph/guides/indexing/#stay-fresh-automatically).
+
+</details>
+
 ---
 
 ## Framework-aware Routes
@@ -125,13 +271,46 @@ CodeGraph detects web-framework routing files and emits `route` nodes linked by
 | **Express** | `app.get(...)`, `router.post(...)` with middleware chains |
 | **NestJS** | `@Controller` + `@Get/@Post/...`, GraphQL `@Resolver` + `@Query/@Mutation`, `@MessagePattern`/`@EventPattern`, `@SubscribeMessage` |
 | **Laravel** | `Route::get()`, `Route::resource()`, `Controller@action`, tuple syntax |
+| **Drupal** | `*.routing.yml` routes (`_controller`, `_form`, entity handlers); `hook_*` implementations in `.module`/`.theme`/`.install`/`.inc` |
 | **Rails** | `get '/x', to: 'users#index'`, hash-rocket `=>` syntax |
 | **Spring** | `@GetMapping`, `@PostMapping`, `@RequestMapping` on methods |
+| **Play** | `GET`/`POST`/… verb routes in `conf/routes` → `Controller.method` actions (Scala + Java) |
 | **Gin / chi / gorilla / mux** | `r.GET(...)`, `router.HandleFunc(...)` |
 | **Axum / actix / Rocket** | `.route("/x", get(handler))` |
 | **ASP.NET** | `[HttpGet("/x")]` attributes on action methods |
 | **Vapor** | `app.get("x", use: handler)` |
 | **React Router** / **SvelteKit** | Route component nodes |
+| **Vue Router** / **Nuxt** | `pages/` file-based routes, `server/api/` endpoints, route middleware |
+| **Astro** | `src/pages/` file-based routes (`.astro` pages + `.ts` endpoints, `[param]`/`[...rest]` syntax) |
+
+---
+
+## 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.
+
+| Boundary | JS / Swift side | Native side | How |
+|---|---|---|---|
+| **Swift → ObjC** | Swift `obj.foo(bar:)` | ObjC selector `-fooWithBar:` | `@objc` auto-bridging rules (including init/property/protocol forms) + Cocoa preposition prefixes (`With`/`For`/`By`/`In`/`On`/`At`/…) |
+| **ObjC → Swift** | ObjC `[obj fooWithBar:]` | Swift `@objc func foo(bar:)` | Reverse-bridge name candidates; verifies `@objc` exposure from source |
+| **React Native legacy bridge** | JS `NativeModules.X.fn(...)` | ObjC `RCT_EXPORT_METHOD` / `RCT_REMAP_METHOD` · Java/Kotlin `@ReactMethod` | Parses macro/annotation declarations to build a JS-name → native-method map |
+| **React Native TurboModules** | JS `import M from './NativeM'; M.fn(...)` | Native impl matching the Codegen spec | Treats the `Native<X>.ts` spec interface as ground truth |
+| **RN native → JS events** | JS `new NativeEventEmitter(...).addListener('e', cb)` | ObjC `[self sendEventWithName:@"e" body:...]` · Swift `sendEvent(withName: "e", ...)` · Java/Kotlin `.emit("e", ...)` | Synthesized cross-language event channel keyed by literal event name |
+| **Expo Modules** | JS `requireNativeModule('X').fn(...)` | Swift / Kotlin `Module { Name("X"); AsyncFunction("fn") { ... } }` | Parses the Expo DSL literals; synthetic method nodes resolve via existing name-match |
+| **Fabric view components** | JSX `<MyView prop={v}/>` | TS Codegen spec + native impl class | Spec → `component` node; convention-based name+suffix lookup (`View`/`ComponentView`/`Manager`/`ViewManager`) bridges to native |
+| **Legacy Paper view managers** | JSX `<MyView prop={v}/>` | ObjC `RCT_EXPORT_VIEW_PROPERTY` · Java/Kotlin `@ReactProp` | Same as Fabric — Paper-era declarations also produce `component` + `property` nodes |
+
+**Validated on real codebases** (small + medium + large for each bridge):
+
+| Bridge | Small | Medium | Large |
+|---|---|---|---|
+| Swift ↔ ObjC | [Charts](https://github.com/danielgindi/Charts) | [realm-swift](https://github.com/realm/realm-swift) | [Wikipedia-iOS](https://github.com/wikimedia/wikipedia-ios) |
+| RN legacy bridge | [AsyncStorage](https://github.com/react-native-async-storage/async-storage) | [react-native-svg](https://github.com/software-mansion/react-native-svg) | [react-native-firebase](https://github.com/invertase/react-native-firebase) |
+| RN native → JS events | [RNGeolocation](https://github.com/Agontuk/react-native-geolocation-service) | — | react-native-firebase |
+| Expo Modules | expo-haptics | expo-camera | expo SDK sweep (7 packages) |
+| Fabric / Paper views | [react-native-segmented-control](https://github.com/react-native-segmented-control/segmented-control) | [react-native-screens](https://github.com/software-mansion/react-native-screens) | [react-native-skia](https://github.com/Shopify/react-native-skia) |
+
+Each bridge emits edges tagged `provenance:'heuristic'` with `metadata.synthesizedBy:` set to a stable channel name (e.g. `swift-objc-bridge`, `rn-event-channel`, `fabric-native-impl`, `expo-module-extract`), so the agent can tell at a glance how a hop got into the graph.
 
 ---
 
@@ -144,10 +323,10 @@ npx @colbymchenry/codegraph
 ```
 
 The installer will:
-- Ask which agent(s) to configure — auto-detects installed ones from: **Claude Code**, **Cursor**, **Codex CLI**, **opencode**
+- 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 + an instructions file (e.g. `CLAUDE.md`, `.cursor/rules/codegraph.mdc`, `~/.codex/AGENTS.md`)
+- 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`.
 - Set up auto-allow permissions when Claude Code is one of the targets
 - Initialize your current project (local installs only)
 
@@ -170,7 +349,7 @@ codegraph install --print-config codex               # print snippet, no file wr
 
 ### 2. Restart Your Agent
 
-Restart your agent (Claude Code / Cursor / Codex CLI / opencode) for the MCP server to load.
+Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro) for the MCP server to load.
 
 ### 3. Initialize Projects
 
@@ -179,7 +358,7 @@ cd your-project
 codegraph init -i
 ```
 
-Builds the per-project knowledge graph index. Also wires up any project-local agent surfaces (e.g. Cursor's `.cursor/rules/codegraph.mdc`) so a single global `codegraph install` works in every project you open — no need to re-run the installer per project.
+Builds the per-project knowledge graph index. A single global `codegraph install` works in every project you open — no need to re-run the installer per project.
 
 That's it — your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists.
 
@@ -210,7 +389,7 @@ npm install -g @colbymchenry/codegraph
   "permissions": {
     "allow": [
       "mcp__codegraph__codegraph_search",
-      "mcp__codegraph__codegraph_context",
+      "mcp__codegraph__codegraph_explore",
       "mcp__codegraph__codegraph_callers",
       "mcp__codegraph__codegraph_callees",
       "mcp__codegraph__codegraph_impact",
@@ -225,43 +404,16 @@ npm install -g @colbymchenry/codegraph
 </details>
 
 <details>
-<summary><strong>Global Instructions Reference</strong></summary>
+<summary><strong>Agent Tool Guidance</strong></summary>
 
-The installer automatically adds these instructions to `~/.claude/CLAUDE.md`:
+CodeGraph's MCP server delivers its usage guidance to your agent **automatically**, in the MCP `initialize` response. In short, it tells the agent to:
 
-```markdown
-## CodeGraph
+- **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.
+- **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.
 
-CodeGraph builds a semantic knowledge graph of codebases for faster, smarter code exploration.
-
-### If `.codegraph/` exists in the project
-
-**NEVER call `codegraph_explore` or `codegraph_context` directly in the main session.** These tools return large amounts of source code that fills up main session context. Instead, ALWAYS spawn an Explore agent for any exploration question (e.g., "how does X work?", "explain the Y system", "where is Z implemented?").
-
-**When spawning Explore agents**, include this instruction in the prompt:
-
-> This project has CodeGraph initialized (.codegraph/ exists). Use `codegraph_explore` as your PRIMARY tool — it returns full source code sections from all relevant files in one call.
->
-> **Rules:**
-> 1. Follow the explore call budget in the `codegraph_explore` tool description — it scales automatically based on project size.
-> 2. Do NOT re-read files that codegraph_explore already returned source code for. The source sections are complete and authoritative.
-> 3. Only fall back to grep/glob/read for files listed under "Additional relevant files" if you need more detail, or if codegraph returned no results.
-
-**The main session may only use these lightweight tools directly** (for targeted lookups before making edits, not for exploration):
-
-| Tool | Use For |
-|------|---------|
-| `codegraph_search` | Find symbols by name |
-| `codegraph_callers` / `codegraph_callees` | Trace call flow |
-| `codegraph_impact` | Check what's affected before editing |
-| `codegraph_node` | Get a single symbol's details |
-
-### If `.codegraph/` does NOT exist
-
-At the start of a session, ask the user if they'd like to initialize CodeGraph:
-
-"I notice this project doesn't have CodeGraph initialized. Would you like me to run `codegraph init -i` to build a code knowledge graph?"
-```
+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.
 
 </details>
 
@@ -270,34 +422,23 @@ At the start of a session, ask the user if they'd like to initialize CodeGraph:
 ## How It Works
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Claude Code                               │
-│                                                                  │
-│  "Implement user authentication"                                 │
-│           │                                                      │
-│           ▼                                                      │
-│  ┌─────────────────┐      ┌─────────────────┐                   │
-│  │  Explore Agent  │ ──── │  Explore Agent  │                   │
-│  └────────┬────────┘      └────────┬────────┘                   │
-│           │                        │                             │
-└───────────┼────────────────────────┼─────────────────────────────┘
-            │                        │
-            ▼                        ▼
 ┌───────────────────────────────────────────────────────────────────┐
-│                     CodeGraph MCP Server                          │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │
-│  │   Search    │  │   Callers   │  │   Context   │               │
-│  │  "auth"     │  │  "login()"  │  │  for task   │               │
-│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘               │
-│         │                │                │                       │
-│         └────────────────┼────────────────┘                       │
-│                          ▼                                        │
-│              ┌───────────────────────┐                            │
-│              │   SQLite Graph DB     │                            │
-│              │   • 387 symbols       │                            │
-│              │   • 1,204 edges       │                            │
-│              │   • Instant lookups   │                            │
-│              └───────────────────────┘                            │
+│                            Claude Code                            │
+│                                                                   │
+│   "How does a request reach the database?"                        │
+│       calls CodeGraph tools directly — no Explore sub-agent       │
+│                                 │                                 │
+└─────────────────────────────────┬─────────────────────────────────┘
+                                  │
+                                  ▼
+┌───────────────────────────────────────────────────────────────────┐
+│                        CodeGraph MCP Server                       │
+│                                                                   │
+│       explore · search · callers · callees · impact · node        │
+│                                 │                                 │
+│                                 ▼                                 │
+│                       SQLite knowledge graph                      │
+│          symbols · edges · files · FTS5 full-text search          │
 └───────────────────────────────────────────────────────────────────┘
 ```
 
@@ -316,16 +457,22 @@ At the start of a session, ask the user if they'd like to initialize CodeGraph:
 ```bash
 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 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
 codegraph status [path]           # Show statistics
 codegraph query <search>          # Search symbols (--kind, --limit, --json)
+codegraph explore <query>         # Relevant symbols' source + call paths in one shot (same output as the codegraph_explore MCP tool)
+codegraph node <symbol|file>      # One symbol's source + callers, or read a file with line numbers (same output as codegraph_node)
 codegraph files [path]            # Show file structure (--format, --filter, --max-depth, --json)
-codegraph context <task>          # Build context for AI (--format, --max-nodes)
+codegraph callers <symbol>        # Find what calls a function/method (--limit, --json)
+codegraph callees <symbol>        # Find what a function/method calls (--limit, --json)
+codegraph impact <symbol>         # Analyze what code is affected by changing a symbol (--depth, --json)
 codegraph affected [files...]     # Find test files affected by changes (see below)
 codegraph serve --mcp             # Start MCP server
+codegraph upgrade [version]       # Update to the latest release (--check, --force)
 ```
 
 ### `codegraph affected`
@@ -360,25 +507,31 @@ fi
 
 ## MCP Tools
 
-When running as an MCP server, CodeGraph exposes these tools to Claude Code:
+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:
 
 | 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_context` | Build relevant code context for a task |
-| `codegraph_callers` | Find what calls a function |
-| `codegraph_callees` | Find what a function calls |
-| `codegraph_impact` | Analyze what code is affected by changing a symbol |
-| `codegraph_node` | Get details about a specific symbol (optionally with source code) |
-| `codegraph_files` | Get indexed file structure (faster than filesystem scanning) |
-| `codegraph_status` | Check index health and statistics |
+| `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 |
+
+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`).
+
+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.
 
 ---
 
 ## Library Usage
 
+CodeGraph can be embedded directly. The npm package re-exports its programmatic
+API, so both `import` and `require` resolve the `CodeGraph` class in your own
+process — handy for embedding it in an app (e.g. an Electron main process).
+
 ```typescript
 import CodeGraph from '@colbymchenry/codegraph';
+// CommonJS works too:
+//   const { CodeGraph } = require('@colbymchenry/codegraph');
 
 const cg = await CodeGraph.init('/path/to/project');
 // Or: const cg = await CodeGraph.open('/path/to/project');
@@ -397,32 +550,72 @@ cg.unwatch(); // stop watching
 cg.close();
 ```
 
+Lower-level building blocks are exported from the same entry point for callers
+that drive the graph directly: `DatabaseConnection`, `QueryBuilder`,
+`getDatabasePath`, `initGrammars` / `loadGrammarsForLanguages`, and `FileLock`.
+
+**Embedding requirements**
+
+- Install from npm (`npm i @colbymchenry/codegraph`) so the matching
+  per-platform package — which carries the compiled library and its
+  dependencies — is fetched alongside the shim.
+- The API runs on **your** runtime, so it needs **Node 22.5+** for the built-in
+  `node:sqlite` (Electron qualifies when its bundled Node is 22.5+). The CLI and
+  MCP server are unaffected — they run on the self-contained bundled runtime.
+- TypeScript types ship with the package. As with any Node-targeting library,
+  keep `@types/node` available and `skipLibCheck: true` (the common default).
+
 ---
 
 ## Configuration
 
-The `.codegraph/config.json` file controls indexing:
+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.
 
-```json
-{
-  "version": 1,
-  "languages": ["typescript", "javascript"],
-  "exclude": ["node_modules/**", "dist/**", "build/**", "*.min.js"],
-  "frameworks": [],
-  "maxFileSize": 1048576,
-  "extractDocstrings": true,
-  "trackCallSites": true
-}
-```
+What it skips out of the box:
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `languages` | Languages to index (auto-detected if empty) | `[]` |
-| `exclude` | Glob patterns to ignore | `["node_modules/**", ...]` |
-| `frameworks` | Framework hints for better resolution | `[]` |
-| `maxFileSize` | Skip files larger than this (bytes) | `1048576` (1MB) |
-| `extractDocstrings` | Extract docstrings from code | `true` |
-| `trackCallSites` | Track call site locations | `true` |
+- **Dependency, build, and cache directories** — `node_modules`, `vendor`,
+  `dist`, `build`, `target`, `.venv`, `Pods`, `.next`, and the like across every
+  [supported stack](#supported-languages) — so the graph is your code, not
+  third-party noise. This holds even with no `.gitignore`.
+- **Anything in your `.gitignore`** — honored in git repos via git, and in
+  non-git projects by reading `.gitignore` directly (root and nested).
+- **Files larger than 1 MB** — generated bundles, minified JS, vendored blobs.
+
+To keep something else out, add it to `.gitignore`. To pull a default-excluded
+directory back **in** (say you really do want a vendored dependency indexed),
+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.
+
+## Supported Platforms
+
+Every release ships a self-contained build (bundled Node runtime — nothing to
+compile) for all three desktop OSes, on both Intel/AMD (x64) and ARM (arm64):
+
+| Platform | Architectures | Install |
+|----------|---------------|---------|
+| Windows | x64, arm64 | PowerShell installer or npm |
+| macOS | x64, arm64 | shell installer or npm |
+| Linux | x64, arm64 | shell installer or npm |
+
+See [Get Started](#get-started) for the one-line install commands.
+
+## Supported Agents
+
+The interactive installer auto-detects and configures each of these — wiring up
+the MCP server (which delivers its own usage guidance, so no instructions file
+is written):
+
+- **Claude Code**
+- **Cursor**
+- **Codex CLI**
+- **opencode**
+- **Hermes Agent**
+- **Gemini CLI**
+- **Antigravity IDE**
+- **Kiro**
 
 ## Supported Languages
 
@@ -439,50 +632,66 @@ The `.codegraph/config.json` file controls indexing:
 | Ruby | `.rb` | Full support |
 | C | `.c`, `.h` | Full support |
 | C++ | `.cpp`, `.hpp`, `.cc` | Full support |
+| Objective-C | `.m`, `.mm`, `.h` | Partial support (classes, protocols, methods, `@property`, `#import`, message sends; `.mm` ObjC++ may parse incompletely) |
 | Swift | `.swift` | Full support |
 | Kotlin | `.kt`, `.kts` | Full support |
 | Scala | `.scala`, `.sc` | Full support (classes, traits, methods, type aliases, Scala 3 enums) |
 | Dart | `.dart` | Full support |
 | Svelte | `.svelte` | Full support (script extraction, Svelte 5 runes, SvelteKit routes) |
 | Vue | `.vue` | Full support (script + script-setup extraction, Nuxt page/API/middleware routes) |
+| Astro | `.astro` | Full support (frontmatter + script extraction, template component/call references, `src/pages/` routes) |
 | Liquid | `.liquid` | Full support |
 | Pascal / Delphi | `.pas`, `.dpr`, `.dpk`, `.lpr` | Full support (classes, records, interfaces, enums, DFM/FMX form files) |
 | Lua | `.lua` | Full support (functions, methods with receivers, local variables, `require` imports, call edges) |
 | Luau | `.luau` | Full support (everything in Lua, plus `type`/`export type` aliases, typed signatures, and Roblox instance-path `require`) |
 
-## Troubleshooting
-
-**"CodeGraph not initialized"** — Run `codegraph init` in your project directory first.
-
-**Indexing is slow** — Check that `node_modules` and other large directories are excluded. Use `--quiet` to reduce output overhead.
-
-**Indexing is slow / MCP `database is locked` / WASM fallback active** — `codegraph` ships with a WASM SQLite fallback for environments where `better-sqlite3` (a native module, declared as `optionalDependencies`) can't install. The fallback is 5-10x slower than the native backend and uses a journal mode that lets writers block readers, so MCP queries can also hit `database is locked` while indexing runs. Run `codegraph status` and look at the `Backend:` line:
+## Measured cross-file coverage
 
-- `Backend: native` — you're on the fast path, nothing to do.
-- `Backend: wasm` — you're on the slow fallback. Common causes: missing C build tools, prebuilt binary unavailable for your Node version, or your Node version changed after install. Fix:
+Impact and blast-radius queries are only as good as the dependency graph behind them, so coverage is measured rather than asserted. **Fair coverage** = the share of symbol-bearing source files that have at least one *resolved cross-file dependent* — something that imports, calls, references, or (through a framework convention) routes to them — on a real-world benchmark repo per language. The residual is always a genuine static-analysis frontier (runtime dynamic dispatch, reflection / DI containers, framework-convention entry points, vendored third-party code), never hidden by gaming the denominator.
 
-  ```bash
-  # macOS
-  xcode-select --install                                  # installs the C compiler
+| Language | Benchmark repo | Coverage |
+|---|---|---|
+| TypeScript / JavaScript | this repo | 95.8% |
+| Python | psf/requests | 100% |
+| Go | gin-gonic/gin | 96.6% |
+| Rust | BurntSushi/ripgrep | 86.7% |
+| Java | google/gson | 93.3% |
+| C# | jbogard/MediatR | 85.2% |
+| PHP | guzzle/guzzle | 100% |
+| Ruby | sidekiq/sidekiq | 100% |
+| C | redis/redis | 92.2% |
+| C++ | google/leveldb | 94.8% |
+| Objective-C | SDWebImage | 91.6% |
+| Swift | Alamofire | 95.3% |
+| Kotlin | square/okhttp | 96.2% |
+| Scala | gatling/gatling | 91.2% |
+| Dart | flutter/packages | 92.4% |
+| Svelte / SvelteKit | sveltejs/realworld | 100% |
+| Vue / Nuxt | nuxt/movies | 93.5% |
+| Astro | xingwangzhe/stalux | 93.0% |
+| Lua | nvim-telescope/telescope.nvim | 84.2% |
+| Luau | dphfox/Fusion | 92.2% |
+| Liquid | Shopify/dawn | 73.8% |
+| Pascal / Delphi | PascalCoin | 77.4% |
+
+Framework routing is validated the same way, on a canonical app per framework: Express 100%, FastAPI 98%, Flask 100%, NestJS 96.8%, Gin 96.5%, Axum 100%, Rocket 93.8%, Vapor 100%, Laravel 92%, Rails 89.6%, React Router 100% — and the convention/reflection-heavy ones at their honest static-analysis ceiling: ASP.NET 83.9%, Spring 83.3%, Drupal 78.9%, Play 76.3%, Django 74.1%. SvelteKit, Vue/Nuxt, and Astro use file-based routing, so their page/endpoint coverage is the Svelte/SvelteKit (100%), Vue/Nuxt (93.5%), and Astro (93.0% — every `src/pages/` file maps to a route node on the two validation repos) figures in the table above.
 
-  # Linux (Debian / Ubuntu)
-  sudo apt install build-essential python3 make
+## Troubleshooting
 
-  # Linux (RHEL / Fedora)
-  sudo yum groupinstall "Development Tools"
+**"CodeGraph not initialized"** — Run `codegraph init` in your project directory first.
 
-  # Then rebuild on any platform:
-  npm rebuild better-sqlite3
+**Indexing is slow** — Check that `node_modules` and other large directories are excluded. Use `--quiet` to reduce output overhead.
 
-  # Or force-include as a hard dep:
-  npm install better-sqlite3 --save
-  ```
+**MCP hits `database is locked`** — current builds shouldn't: CodeGraph bundles its own Node runtime and uses Node's built-in `node:sqlite` in WAL mode, where concurrent reads never block on a writer. If you still see it:
 
-  After the fix, `codegraph status` should show `Backend: native`.
+- **You're on an old (pre-0.9) install.** Reinstall to get the bundled runtime — `curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh` (macOS/Linux), `irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex` (Windows), or `npm i -g @colbymchenry/codegraph@latest`.
+- **`codegraph status` shows `Journal:` other than `wal`** — WAL couldn't be enabled on this filesystem (common on network shares and WSL2 `/mnt`), so reads can block on writes. Move the project (with its `.codegraph/` folder) onto a local disk.
 
 **MCP server not connecting** — Ensure the project is initialized/indexed, verify the path in your MCP config, and check that `codegraph serve --mcp` works from the command line.
 
-**Missing symbols** — The MCP server auto-syncs on save (wait a couple seconds). Run `codegraph sync` manually if needed. Check that the file's language is supported and isn't excluded by config patterns.
+**Missing symbols** — The MCP server auto-syncs on save (wait a couple seconds). Run `codegraph sync` manually if needed. Check that the file's language is supported and isn't inside a `.gitignore`d or default-excluded directory (e.g. `node_modules`, `dist`).
+
+**Sharing one checkout between Windows and WSL** — Don't point both at the same `.codegraph/`: the background-server lock and the SQLite index are tied to the OS that wrote them, and SQLite locking across the WSL2/Windows filesystem boundary is unreliable. Give each side its own index in the same tree by setting `CODEGRAPH_DIR` to a distinct name on one of them — e.g. `CODEGRAPH_DIR=.codegraph-win` on Windows, leaving WSL on the default `.codegraph`. CodeGraph skips any sibling `.codegraph-*` directory when indexing and watching, so the two never trip over each other.
 
 ## Star History
 
@@ -502,7 +711,7 @@ MIT
 
 <div align="center">
 
-**Made for AI coding agents — Claude Code, Cursor, Codex CLI, and opencode**
+**Made for AI coding agents — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro**
 
 [Report Bug](https://github.com/colbymchenry/codegraph/issues) · [Request Feature](https://github.com/colbymchenry/codegraph/issues)
 
diff --git a/__tests__/adaptive-explore-sizing.test.ts b/__tests__/adaptive-explore-sizing.test.ts
new file mode 100644
index 000000000..809a885cf
--- /dev/null
+++ b/__tests__/adaptive-explore-sizing.test.ts
@@ -0,0 +1,393 @@
+/**
+ * Regression test for adaptive `codegraph_explore` sizing — sibling
+ * skeletonization (branch `feat/adaptive-explore-sizing`, commit d6d059f).
+ *
+ * Feature: when a file is BOTH (1) off the synthesized flow spine AND (2) a
+ * polymorphic sibling — its class implements/extends a supertype shared by
+ * >= MIN_SIBLINGS (3) implementers — `codegraph_explore` renders it as a
+ * class + member *signature* skeleton (bodies elided) instead of full source,
+ * keeping the on-spine exemplar and the mechanism full. This sizes the
+ * response to the answer rather than the budget cap on sibling-heavy flows
+ * (OkHttp's interceptor chain) without starving diffuse ones (distinct
+ * pipeline steps stay full). Default ON; CODEGRAPH_ADAPTIVE_EXPLORE=0 disables.
+ *
+ * The fixture is OkHttp's interceptor chain in miniature:
+ *   - `Interceptor` interface with FOUR implementers (>= 3 => a sibling family)
+ *   - a 3-hop call spine `dispatch -> proceed -> handleLogging` that passes
+ *     THROUGH LoggingInterceptor — so that file is the on-spine exemplar
+ *   - Bridge/Cache/RetryInterceptor: off-spine members of the sibling family
+ *     => skeletonize
+ *   - ResponseFormatter implements `Formatter`, which has only ONE impl (< 3)
+ *     => a distinct step: off-spine but NOT a sibling => stays full
+ *
+ * Guards the two ways the feature can silently regress: skeletonizing too much
+ * (a distinct step or the on-spine exemplar) or too little (the off-spine
+ * siblings), plus the escape hatch.
+ */
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { ToolHandler } from '../src/mcp/tools';
+import CodeGraph from '../src/index';
+
+// Stable marker — assert the `· skeleton` tag, not its exact trailing wording
+// (the steer-to-explore phrasing changed when the Read invitation was removed).
+const SKELETON_MARK = '· skeleton (signatures only';
+
+/** Return the `#### <path> ...` section for a file basename, header through the
+ *  line before the next `###`/`####` header (or end of output). */
+function sectionFor(text: string, basename: string): string {
+  const lines = text.split('\n');
+  const start = lines.findIndex((l) => l.startsWith('#### ') && l.includes(basename));
+  if (start < 0) return '';
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].startsWith('### ') || lines[i].startsWith('#### ')) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join('\n');
+}
+
+describe('adaptive codegraph_explore sizing — sibling skeletonization', () => {
+  let testDir: string;
+  let cg: CodeGraph;
+  let handler: ToolHandler;
+
+  // Names the spine (dispatch/proceed/handleLogging), the on-spine exemplar,
+  // the three off-spine siblings, and the distinct step — so every file we
+  // assert on is gathered as relevant. maxFiles overrides the very-tiny tier's
+  // 4-file default so all of them land in one call.
+  const QUERY =
+    'dispatch proceed handleLogging LoggingInterceptor BridgeInterceptor CacheInterceptor RetryInterceptor ResponseFormatter';
+
+  beforeAll(async () => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-adaptive-explore-'));
+    const srcDir = path.join(testDir, 'src');
+    fs.mkdirSync(srcDir);
+
+    const write = (name: string, body: string) =>
+      fs.writeFileSync(path.join(srcDir, name), body.trimStart());
+
+    // The interchangeable contract — 4 implementers below => sibling family.
+    write(
+      'interceptor.ts',
+      `
+export interface Interceptor {
+  intercept(request: string): string;
+}
+`
+    );
+
+    // The mechanism + the spine: dispatch -> proceed -> (LoggingInterceptor) handleLogging.
+    // Unique method names so the call edges resolve unambiguously.
+    write(
+      'dispatcher.ts',
+      `
+import { LoggingInterceptor } from './logging-interceptor';
+
+export class RequestDispatcher {
+  dispatch(): string {
+    const chain = new InterceptorChain();
+    return chain.proceed();
+  }
+}
+
+export class InterceptorChain {
+  proceed(): string {
+    const exemplar = new LoggingInterceptor();
+    return exemplar.handleLogging();
+  }
+}
+`
+    );
+
+    // On-spine exemplar: handleLogging is the spine's tail, so this whole file
+    // is on-spine and must stay FULL even though it's a sibling (implements Interceptor).
+    write(
+      'logging-interceptor.ts',
+      `
+import { Interceptor } from './interceptor';
+
+export class LoggingInterceptor implements Interceptor {
+  handleLogging(): string {
+    const tag = 'LOGGING_BODY_MARKER';
+    return this.intercept(tag);
+  }
+  intercept(request: string): string {
+    return 'logged:' + request;
+  }
+}
+`
+    );
+
+    // Off-spine siblings — interchangeable impls of Interceptor => SKELETONIZE.
+    // Each body carries a unique marker that must NOT survive skeletonization.
+    write(
+      'bridge-interceptor.ts',
+      `
+import { Interceptor } from './interceptor';
+
+export class BridgeInterceptor implements Interceptor {
+  intercept(request: string): string {
+    const detail = 'BRIDGE_BODY_MARKER';
+    return 'bridged:' + request + detail;
+  }
+}
+`
+    );
+    write(
+      'cache-interceptor.ts',
+      `
+import { Interceptor } from './interceptor';
+
+export class CacheInterceptor implements Interceptor {
+  intercept(request: string): string {
+    const detail = 'CACHE_BODY_MARKER';
+    return 'cached:' + request + detail;
+  }
+}
+`
+    );
+    write(
+      'retry-interceptor.ts',
+      `
+import { Interceptor } from './interceptor';
+
+export class RetryInterceptor implements Interceptor {
+  intercept(request: string): string {
+    const detail = 'RETRY_BODY_MARKER';
+    return 'retried:' + request + detail;
+  }
+}
+`
+    );
+
+    // A 1:1 interface->impl pair: off-spine, implements something, but the
+    // supertype has only ONE impl (< MIN_SIBLINGS) => a DISTINCT step => FULL.
+    write(
+      'formatter.ts',
+      `
+export interface Formatter {
+  format(input: string): string;
+}
+`
+    );
+    write(
+      'response-formatter.ts',
+      `
+import { Formatter } from './formatter';
+import { JsonCodec } from './codec';
+
+export class ResponseFormatter implements Formatter {
+  format(input: string): string {
+    const detail = 'FORMATTER_BODY_MARKER';
+    // Calls into the Codec family from OFF the dispatch spine, so codec.ts is
+    // gathered as relevant but stays off-spine (mirrors Django: compiler.py is
+    // referenced by the flow yet off the QuerySet-iteration spine).
+    return new JsonCodec().encode(input) + detail;
+  }
+}
+`
+    );
+
+    // An off-spine sibling (implements Interceptor) the agent would otherwise
+    // skeletonize — BUT it owns a uniquely-named method `authenticate` the agent
+    // names in the query. Mirrors OkHttp's RealCall (named getResponseWith-
+    // InterceptorChain): a named callable means "show me this", so it stays full.
+    write(
+      'auth-interceptor.ts',
+      `
+import { Interceptor } from './interceptor';
+
+export class AuthInterceptor implements Interceptor {
+  authenticate(token: string): string {
+    const detail = 'AUTH_BODY_MARKER';
+    return 'auth:' + token + detail;
+  }
+  intercept(request: string): string {
+    return this.authenticate(request);
+  }
+}
+`
+    );
+
+    // A base class that DEFINES a >=3-impl supertype AND co-locates its
+    // subclasses in the same file — mirrors Django's compiler.py (SQLCompiler +
+    // SQLInsertCompiler/SQLUpdateCompiler/...). The subclasses' `extends` edges
+    // make the file look like a sibling, but it's the family's base/mechanism,
+    // so it must stay full.
+    write(
+      'codec.ts',
+      `
+export class Codec {
+  encode(input: string): string {
+    const detail = 'CODEC_BASE_MARKER';
+    return input + detail;
+  }
+}
+export class JsonCodec extends Codec {
+  encode(input: string): string { return '{' + input + '}'; }
+}
+export class XmlCodec extends Codec {
+  encode(input: string): string {
+    const detail = 'XML_BODY_MARKER';
+    return '<' + input + detail + '>';
+  }
+}
+export class YamlCodec extends Codec {
+  encode(input: string): string { return '- ' + input; }
+}
+`
+    );
+
+    cg = CodeGraph.initSync(testDir, { config: { include: ['**/*.ts'], exclude: [] } });
+    await cg.indexAll();
+    handler = new ToolHandler(cg);
+  });
+
+  afterAll(() => {
+    if (cg) cg.destroy();
+    if (testDir && fs.existsSync(testDir)) {
+      fs.rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  beforeEach(() => {
+    // Each test asserts against the default (ON) behaviour unless it opts out.
+    delete process.env.CODEGRAPH_ADAPTIVE_EXPLORE;
+  });
+
+  it('fixture sanity: Interceptor has >=3 implementers, Formatter has <3', () => {
+    const find = (name: string, kind: string) =>
+      cg.searchNodes(name).map((r) => r.node).find((n) => n.name === name && n.kind === kind);
+
+    const interceptor = find('Interceptor', 'interface');
+    const formatter = find('Formatter', 'interface');
+    expect(interceptor).toBeTruthy();
+    expect(formatter).toBeTruthy();
+
+    const implementers = (id: string) =>
+      cg.getIncomingEdges(id).filter((e) => e.kind === 'implements' || e.kind === 'extends').length;
+
+    // The whole gate hinges on this signal — assert the fixture actually
+    // produces the >=3 / <3 split, so a TS-extraction change fails here loudly
+    // rather than silently flipping the skeletonization downstream.
+    expect(implementers(interceptor!.id)).toBeGreaterThanOrEqual(3);
+    expect(implementers(formatter!.id)).toBeLessThan(3);
+  });
+
+  it('skeletonizes off-spine polymorphic siblings (bodies elided, signatures kept)', async () => {
+    const result = await handler.execute('codegraph_explore', { query: QUERY, maxFiles: 12 });
+    const text = result.content?.[0]?.text ?? '';
+
+    // Precondition: the spine must have formed, or nothing skeletonizes.
+    expect(text).toContain('## Flow (call path among the symbols you queried)');
+
+    for (const [file, marker] of [
+      ['bridge-interceptor.ts', 'BRIDGE_BODY_MARKER'],
+      ['cache-interceptor.ts', 'CACHE_BODY_MARKER'],
+      ['retry-interceptor.ts', 'RETRY_BODY_MARKER'],
+    ] as const) {
+      const section = sectionFor(text, file);
+      expect(section, `${file} should be present in the explore output`).not.toBe('');
+      expect(section, `${file} should be skeletonized`).toContain(SKELETON_MARK);
+      // The signature line survives; the body (with its marker) is elided.
+      expect(section).toContain('intercept(request');
+      expect(section, `${file} body marker must NOT survive skeletonization`).not.toContain(marker);
+    }
+  });
+
+  it('keeps the on-spine exemplar full even though it is a sibling', async () => {
+    const result = await handler.execute('codegraph_explore', { query: QUERY, maxFiles: 12 });
+    const text = result.content?.[0]?.text ?? '';
+
+    const section = sectionFor(text, 'logging-interceptor.ts');
+    expect(section, 'logging-interceptor.ts should be present').not.toBe('');
+    expect(section, 'on-spine exemplar must NOT be skeletonized').not.toContain(SKELETON_MARK);
+    // Full source => the body marker is present.
+    expect(section).toContain('LOGGING_BODY_MARKER');
+  });
+
+  it('keeps a distinct step full (off-spine but supertype has < 3 implementers)', async () => {
+    const result = await handler.execute('codegraph_explore', { query: QUERY, maxFiles: 12 });
+    const text = result.content?.[0]?.text ?? '';
+
+    const section = sectionFor(text, 'response-formatter.ts');
+    expect(section, 'response-formatter.ts should be present').not.toBe('');
+    expect(section, 'a 1:1 interface impl is not a sibling and must stay full').not.toContain(SKELETON_MARK);
+    expect(section).toContain('FORMATTER_BODY_MARKER');
+  });
+
+  it('CODEGRAPH_ADAPTIVE_EXPLORE=0 disables skeletonization (siblings render full)', async () => {
+    process.env.CODEGRAPH_ADAPTIVE_EXPLORE = '0';
+    try {
+      const result = await handler.execute('codegraph_explore', { query: QUERY, maxFiles: 12 });
+      const text = result.content?.[0]?.text ?? '';
+
+      expect(text, 'no file should be skeletonized with the flag off').not.toContain(SKELETON_MARK);
+      // The previously-skeletonized siblings now render their full bodies.
+      const section = sectionFor(text, 'bridge-interceptor.ts');
+      expect(section).not.toBe('');
+      expect(section).toContain('BRIDGE_BODY_MARKER');
+    } finally {
+      delete process.env.CODEGRAPH_ADAPTIVE_EXPLORE;
+    }
+  });
+
+  // Names AuthInterceptor's `authenticate` and Codec's `encode` (both methods),
+  // plus the spine tokens so a spine still forms. Same Interceptor family as the
+  // skeleton test, plus the Codec base+subclasses family.
+  const SPARE_QUERY = `${QUERY} authenticate encode AuthInterceptor Codec JsonCodec`;
+
+  it('spares an off-spine sibling when the agent NAMED a callable in it (RealCall fix)', async () => {
+    const result = await handler.execute('codegraph_explore', { query: SPARE_QUERY, maxFiles: 15 });
+    const text = result.content?.[0]?.text ?? '';
+    expect(text).toContain('## Flow (call path among the symbols you queried)');
+
+    // auth-interceptor.ts is an off-spine Interceptor sibling — would skeletonize —
+    // but the agent named its method `authenticate`, so it stays FULL.
+    const auth = sectionFor(text, 'auth-interceptor.ts');
+    expect(auth, 'auth-interceptor.ts should be present').not.toBe('');
+    expect(auth, 'a file holding an agent-named callable must NOT be skeletonized').not.toContain(SKELETON_MARK);
+    expect(auth).toContain('AUTH_BODY_MARKER');
+
+    // Contrast: bridge-interceptor.ts — same family, named only by TYPE — still skeletonizes.
+    const bridge = sectionFor(text, 'bridge-interceptor.ts');
+    expect(bridge, 'a sibling named only by type still skeletonizes').toContain(SKELETON_MARK);
+    expect(bridge).not.toContain('BRIDGE_BODY_MARKER');
+  });
+
+  it('collapses a base+subclasses family file to a FOCUSED view — base method body kept, non-named subclasses signature-only (compiler.py)', async () => {
+    const result = await handler.execute('codegraph_explore', { query: SPARE_QUERY, maxFiles: 15 });
+    const text = result.content?.[0]?.text ?? '';
+
+    // codec.ts defines the base Codec (>=3 subclasses extend it) and co-locates the
+    // subclasses — a "family" file (Django's compiler.py). The family-override fires
+    // (it is NOT spared into a full clustered render despite the named `encode`), so
+    // it COLLAPSES — but per-symbol: the named base method `Codec.encode` keeps its
+    // body (so the agent doesn't Read it back — Django's SQLCompiler.execute_sql),
+    // while a non-named subclass (XmlCodec) collapses to a signature. That packs the
+    // mechanism into budget without the redundant subclass bodies.
+    const codec = sectionFor(text, 'codec.ts');
+    expect(codec, 'codec.ts should be present').not.toBe('');
+    expect(codec, 'a named family file collapses to a focused (not full) view').toContain('· focused');
+    expect(codec, 'the named base method body is kept (no Read-back)').toContain('CODEC_BASE_MARKER');
+    expect(codec, 'a non-named subclass body is elided to a signature').not.toContain('XML_BODY_MARKER');
+  });
+
+  it('naming a SHARED/polymorphic method does not spare the siblings (uniqueness-aware)', async () => {
+    // `intercept` is implemented by every interceptor (5 defs) — a polymorphic name,
+    // not a unique one. Naming it must NOT keep all five full (that floods the budget
+    // — Django's `as_sql`×110). The off-spine siblings still collapse, and since none
+    // defines the supertype, `intercept` doesn't even earn a body — pure skeleton.
+    const result = await handler.execute('codegraph_explore', { query: `${QUERY} intercept`, maxFiles: 12 });
+    const text = result.content?.[0]?.text ?? '';
+
+    const bridge = sectionFor(text, 'bridge-interceptor.ts');
+    expect(bridge, 'a sibling named only via a shared method is not spared').toContain(SKELETON_MARK);
+    expect(bridge, 'a shared method does not earn a body in a non-supertype leaf').not.toContain('BRIDGE_BODY_MARKER');
+  });
+});
diff --git a/__tests__/closure-collection-synthesizer.test.ts b/__tests__/closure-collection-synthesizer.test.ts
new file mode 100644
index 000000000..b516cb496
--- /dev/null
+++ b/__tests__/closure-collection-synthesizer.test.ts
@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { CodeGraph } from '../src';
+
+/**
+ * End-to-end synthesizer test for closure-collection dynamic dispatch.
+ *
+ * A method appends a closure to a collection property; another method iterates
+ * that property *invoking each element* (`coll.forEach { $0() }`) — a dynamic
+ * dispatch tree-sitter can't resolve, so a flow into the dispatcher dead-ends
+ * before the registered closures. This is Alamofire's request-validation shape:
+ * `DataRequest.validate` does `validators.write { $0.append(validator) }`, the
+ * base `Request.didCompleteTask` runs `validators.forEach { $0() }`.
+ *
+ * Verify the synthesizer (1) links the dispatcher → each same-named registrar
+ * across files/classes, (2) handles both the Swift `prop.write { $0.append }`
+ * and the direct `prop.append(...)` registrar forms, (3) surfaces the wiring
+ * site, and (4) does NOT fire on a `.forEach` that doesn't invoke its element
+ * (the closure-invoke is the precision gate — a plain collection is skipped).
+ */
+describe('closure-collection synthesizer', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'closure-coll-fixture-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('links dispatcher → registrars across files, both append forms, and skips non-invoked collections', async () => {
+    // Base class: the dispatchers (iterate-and-invoke) + a non-closure control.
+    fs.writeFileSync(
+      path.join(dir, 'Request.swift'),
+      `class Request {
+    var validators: [() -> Void] = []
+    var handlers: [() -> Void] = []
+    var names: [String] = []
+
+    func didCompleteTask() {
+        let validators = validators
+        validators.forEach { $0() }
+    }
+
+    func runHandlers() {
+        handlers.forEach { $0() }
+    }
+
+    func printNames() {
+        names.forEach { print($0) }
+    }
+}
+`
+    );
+
+    // Subclass: the registrars (append a closure) in a DIFFERENT file/class.
+    fs.writeFileSync(
+      path.join(dir, 'DataRequest.swift'),
+      `class DataRequest: Request {
+    func validate(_ validation: @escaping () -> Void) -> Self {
+        let validator: () -> Void = { validation() }
+        validators.write { $0.append(validator) }
+        return self
+    }
+
+    func onEvent(_ handler: @escaping () -> Void) {
+        handlers.append(handler)
+    }
+
+    func addName(_ n: String) {
+        names.append(n)
+    }
+}
+`
+    );
+
+    const cg = await CodeGraph.init(dir, { silent: true });
+    await cg.indexAll();
+
+    const db = (cg as any).db.db;
+    const rows = db
+      .prepare(
+        `SELECT s.name source_name, s.kind source_kind, t.name target_name,
+                json_extract(e.metadata,'$.field') field,
+                json_extract(e.metadata,'$.registeredAt') registeredAt
+         FROM edges e
+         JOIN nodes s ON s.id = e.source
+         JOIN nodes t ON t.id = e.target
+         WHERE json_extract(e.metadata,'$.synthesizedBy') = 'closure-collection'`
+      )
+      .all();
+    cg.close?.();
+
+    expect(rows.length).toBeGreaterThan(0);
+
+    // Every edge originates from a dispatcher method and is a real `calls` hop.
+    expect(rows.every((r: any) => r.source_kind === 'method')).toBe(true);
+
+    // The validators flow: didCompleteTask → validate, captured via the Swift
+    // Protected `prop.write { $0.append }` form, wiring site surfaced.
+    const validatorsEdge = rows.find(
+      (r: any) => r.field === 'validators' && r.target_name === 'validate'
+    );
+    expect(validatorsEdge).toBeTruthy();
+    expect(validatorsEdge.source_name).toBe('didCompleteTask');
+    expect(validatorsEdge.registeredAt).toMatch(/DataRequest\.swift:\d+/);
+
+    // The handlers flow: runHandlers → onEvent, via the direct `prop.append`
+    // form — proves both registrar shapes are covered.
+    const handlersEdge = rows.find(
+      (r: any) => r.field === 'handlers' && r.target_name === 'onEvent'
+    );
+    expect(handlersEdge).toBeTruthy();
+    expect(handlersEdge.source_name).toBe('runHandlers');
+
+    // Precision gate: `names.forEach { print($0) }` does NOT invoke its element,
+    // so `names` is not a closure collection — no edge, and addName is never a target.
+    expect(rows.some((r: any) => r.field === 'names')).toBe(false);
+    expect(rows.some((r: any) => r.target_name === 'addName')).toBe(false);
+  });
+});
diff --git a/__tests__/concurrent-locking.test.ts b/__tests__/concurrent-locking.test.ts
new file mode 100644
index 000000000..5c8ab518d
--- /dev/null
+++ b/__tests__/concurrent-locking.test.ts
@@ -0,0 +1,152 @@
+/**
+ * Issue #238 — "database is locked" on concurrent MCP tool calls.
+ *
+ * With node:sqlite (real WAL) as the backend, the fixes that remain relevant:
+ *  1. busy_timeout is a bounded few-second wait (not a 2-minute hang) and WAL is
+ *     active — so a reader never blocks on a concurrent writer.
+ *  2. The MCP ToolHandler reuses the default instance when a tool passes a
+ *     projectPath pointing at the default project, instead of opening a SECOND
+ *     connection to the same DB.
+ */
+
+import { describe, it, expect, beforeAll, afterAll, vi } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src';
+import { ToolHandler } from '../src/mcp/tools';
+import { DatabaseConnection } from '../src/db';
+
+/** Normalize a PRAGMA read across return shapes (array | object | scalar). */
+function pragmaValue(raw: unknown, key: string): unknown {
+  const row = Array.isArray(raw) ? raw[0] : raw;
+  if (row !== null && typeof row === 'object') return (row as Record<string, unknown>)[key];
+  return row;
+}
+
+describe('issue #238 — connection PRAGMAs (#1)', () => {
+  let dir: string;
+  let conn: DatabaseConnection;
+
+  beforeAll(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg238-pragma-'));
+    conn = DatabaseConnection.initialize(path.join(dir, 'codegraph.db'));
+  });
+
+  afterAll(() => {
+    conn.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('uses a bounded busy_timeout, not the old 2-minute hang', () => {
+    const ms = Number(pragmaValue(conn.getDb().pragma('busy_timeout'), 'timeout'));
+    expect(ms).toBeGreaterThan(0);
+    expect(ms).toBeLessThanOrEqual(30000); // far below the old 120000
+  });
+
+  it('runs in WAL mode — the mode that lets readers proceed during a write', () => {
+    const mode = String(pragmaValue(conn.getDb().pragma('journal_mode'), 'journal_mode')).toLowerCase();
+    expect(mode).toBe('wal');
+  });
+
+  it('getJournalMode() surfaces the effective mode for status triage', () => {
+    expect(conn.getJournalMode()).toBe('wal');
+  });
+});
+
+describe('issue #238 — WAL lets a reader proceed during a writer', () => {
+  let dir: string;
+
+  beforeAll(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg238-wal-'));
+  });
+
+  afterAll(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('a read on a 2nd connection succeeds while a writer holds the lock', () => {
+    const dbPath = path.join(dir, 'codegraph.db');
+    const writer = DatabaseConnection.initialize(dbPath);
+    // The property only holds under WAL; skip if the filesystem couldn't enable it.
+    if (writer.getJournalMode() !== 'wal') {
+      writer.close();
+      return;
+    }
+    const reader = DatabaseConnection.open(dbPath);
+    try {
+      writer.getDb().prepare('BEGIN EXCLUSIVE').run(); // hard write lock, held open
+      const t0 = Date.now();
+      const row = reader.getDb().prepare('SELECT COUNT(*) AS c FROM nodes').get() as { c: number };
+      const waited = Date.now() - t0;
+      expect(row.c).toBe(0);
+      expect(waited).toBeLessThan(1000); // proceeds immediately, no busy wait
+    } finally {
+      try { writer.getDb().prepare('COMMIT').run(); } catch { /* ignore */ }
+      reader.close();
+      writer.close();
+    }
+  });
+});
+
+describe('issue #238 — ToolHandler reuses the default instance (#2)', () => {
+  let dir: string;
+  let cg: CodeGraph;
+  let root: string;
+  let handler: ToolHandler;
+
+  beforeAll(async () => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg238-tools-'));
+    fs.writeFileSync(path.join(dir, 'a.ts'), 'export function helper(): number { return 1; }\n');
+    fs.writeFileSync(
+      path.join(dir, 'b.ts'),
+      "import { helper } from './a';\nexport function main(): number { return helper(); }\n"
+    );
+    cg = await CodeGraph.init(dir, { index: true });
+    root = cg.getProjectRoot();
+    handler = new ToolHandler(cg);
+  });
+
+  afterAll(() => {
+    cg.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('getCodeGraph(defaultRoot) returns the default instance, not a new connection', () => {
+    const openSpy = vi.spyOn(CodeGraph, 'openSync');
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const resolved = (handler as any).getCodeGraph(root);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const nested = (handler as any).getCodeGraph(path.join(root, 'does', 'not', 'exist'));
+      expect(resolved).toBe(cg);
+      expect(nested).toBe(cg); // a sub-path resolves up to the same default project
+      expect(openSpy).not.toHaveBeenCalled(); // no second connection opened
+    } finally {
+      openSpy.mockRestore();
+    }
+  });
+
+  it('concurrent read tool calls (mixed projectPath) all succeed without "database is locked"', async () => {
+    const openSpy = vi.spyOn(CodeGraph, 'openSync');
+    try {
+      const calls: Promise<{ content: Array<{ text: string }>; isError?: boolean }>[] = [
+        handler.execute('codegraph_search', { query: 'helper' }),
+        handler.execute('codegraph_search', { query: 'helper', projectPath: root }),
+        handler.execute('codegraph_callers', { symbol: 'helper', projectPath: root }),
+        handler.execute('codegraph_callees', { symbol: 'main' }),
+        handler.execute('codegraph_files', { projectPath: root }),
+        handler.execute('codegraph_status', { projectPath: root }),
+      ];
+      const results = await Promise.all(calls);
+      for (const r of results) {
+        expect(r.isError).not.toBe(true);
+        expect(r.content[0]?.text ?? '').not.toMatch(/database is locked/i);
+      }
+      // Passing the default project's own path must not open a second connection.
+      expect(openSpy).not.toHaveBeenCalled();
+    } finally {
+      openSpy.mockRestore();
+    }
+  });
+});
diff --git a/__tests__/config-secret-redaction.test.ts b/__tests__/config-secret-redaction.test.ts
new file mode 100644
index 000000000..6143ba47a
--- /dev/null
+++ b/__tests__/config-secret-redaction.test.ts
@@ -0,0 +1,102 @@
+/**
+ * #383 — CodeGraph indexes config KEYS but must never surface config VALUES.
+ *
+ * Spring `application.{yml,properties}` keys are indexed as `constant` nodes so
+ * `@Value` resolution works, but their values are routinely secrets (DB
+ * passwords, API keys, JDBC URLs with embedded creds). CodeGraph must surface
+ * the KEY and never the value — not in node metadata (docstring/signature),
+ * not via `codegraph_explore`'s verbatim source dump, and not via
+ * `codegraph_node` `includeCode`. An agent that genuinely needs a value can
+ * read the file itself (a deliberate pull); CodeGraph must never volunteer it.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src/index';
+import { ToolHandler } from '../src/mcp/tools';
+
+const SECRET = 'sk-live-DO-NOT-LEAK-2f9a4c7e1b';
+
+describe('config secret redaction (#383)', () => {
+  let tmpDir: string;
+  let cg: CodeGraph;
+  let handler: ToolHandler;
+
+  beforeEach(async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-config-secret-'));
+    const javaDir = path.join(tmpDir, 'src/main/java/com/example');
+    const resDir = path.join(tmpDir, 'src/main/resources');
+    fs.mkdirSync(javaDir, { recursive: true });
+    fs.mkdirSync(resDir, { recursive: true });
+    // pom.xml triggers Spring detection so the resolver parses the config files.
+    fs.writeFileSync(
+      path.join(tmpDir, 'pom.xml'),
+      '<project><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter</artifactId></dependency></dependencies></project>\n',
+    );
+    fs.writeFileSync(
+      path.join(resDir, 'application.properties'),
+      `server.port=8080\nspring.datasource.password=${SECRET}\n`,
+    );
+    fs.writeFileSync(
+      path.join(resDir, 'application.yml'),
+      `app:\n  api:\n    key: "${SECRET}"\n`,
+    );
+    fs.writeFileSync(
+      path.join(javaDir, 'DataConfig.java'),
+      'package com.example;\n' +
+        'import org.springframework.beans.factory.annotation.Value;\n' +
+        'public class DataConfig {\n' +
+        '  @Value("${spring.datasource.password}") private String dbPass;\n' +
+        '  @Value("${app.api.key}") private String apiKey;\n' +
+        '}\n',
+    );
+
+    cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+    handler = new ToolHandler(cg);
+  });
+
+  afterEach(() => {
+    if (cg) cg.destroy();
+    if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  const configKeys = () =>
+    cg.getNodesByKind('constant').filter((n) => n.language === 'yaml' || n.language === 'properties');
+
+  it('still indexes config KEYS as nodes (resolution must not regress)', () => {
+    const byQn = (qn: string) => configKeys().find((n) => n.qualifiedName === qn);
+    expect(byQn('spring.datasource.password'), '.properties key indexed').toBeDefined();
+    expect(byQn('app.api.key'), 'yaml key indexed').toBeDefined();
+  });
+
+  it('never stores the secret VALUE in node metadata (docstring/signature/name)', () => {
+    const keys = configKeys();
+    expect(keys.length).toBeGreaterThan(0);
+    for (const n of keys) {
+      expect(n.docstring ?? '', `docstring of ${n.qualifiedName}`).not.toContain(SECRET);
+      expect(n.signature ?? '', `signature of ${n.qualifiedName}`).not.toContain(SECRET);
+      expect(n.name, `name of ${n.qualifiedName}`).not.toContain(SECRET);
+    }
+  });
+
+  it('codegraph_explore surfaces the config key but NEVER the secret value', async () => {
+    const res = await handler.execute('codegraph_explore', {
+      query: 'DataConfig dbPass apiKey spring.datasource.password app.api.key',
+    });
+    const text = res.content.map((c) => c.text).join('\n');
+    expect(text).toContain('password'); // the key is in scope (non-vacuous)
+    expect(text).not.toContain(SECRET); // ...but the value is never dumped
+  });
+
+  it('codegraph_node includeCode returns the key, not the secret value', async () => {
+    const res = await handler.execute('codegraph_node', {
+      symbol: 'spring.datasource.password',
+      includeCode: true,
+    });
+    const text = res.content.map((c) => c.text).join('\n');
+    expect(text).toContain('password'); // found the node
+    expect(text).not.toContain(SECRET); // value redacted from the code path
+  });
+});
diff --git a/__tests__/context-ranking.test.ts b/__tests__/context-ranking.test.ts
new file mode 100644
index 000000000..ec9772086
--- /dev/null
+++ b/__tests__/context-ranking.test.ts
@@ -0,0 +1,189 @@
+/**
+ * Context ranking: common-word precision + low-confidence handoff.
+ *
+ * Regression coverage for the failure where a prose query
+ * ("capture intro onboarding screen flat object") surfaced an unrelated
+ * constant named `FLAT` (in a download script) as a top entry point — because
+ * the descriptive word "flat" exact-matched it and the +exact-name bonus was
+ * exempt from single-term dampening. The fix: only distinctive identifiers earn
+ * that exemption; an isolated common-word exact match is demoted, and a query
+ * that resolves only to such weak matches is flagged low-confidence so the
+ * response hands off to explore/trace instead of bluffing.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src/index';
+import { LOW_CONFIDENCE_MARKER } from '../src/context';
+import { isDistinctiveIdentifier, scorePathRelevance, deriveProjectNameTokens } from '../src/search/query-utils';
+
+describe('isDistinctiveIdentifier', () => {
+  it('treats plain dictionary words as non-distinctive', () => {
+    for (const word of ['flat', 'object', 'screen', 'standing', 'capture']) {
+      expect(isDistinctiveIdentifier(word)).toBe(false);
+    }
+  });
+
+  it('treats leading-capital-only words (proper nouns / sentence start) as non-distinctive', () => {
+    expect(isDistinctiveIdentifier('Screen')).toBe(false);
+    expect(isDistinctiveIdentifier('Zustand')).toBe(false);
+  });
+
+  it('treats camelCase / PascalCase / snake_case / acronyms / digits as distinctive', () => {
+    expect(isDistinctiveIdentifier('setLastEmail')).toBe(true);
+    expect(isDistinctiveIdentifier('OrgUserStore')).toBe(true);
+    expect(isDistinctiveIdentifier('user_store')).toBe(true);
+    expect(isDistinctiveIdentifier('REST')).toBe(true);
+    expect(isDistinctiveIdentifier('v2')).toBe(true);
+  });
+});
+
+// A single PascalCase query word (notably a project name a user naturally
+// includes) splits into sub-tokens that all match the SAME path segment; summed
+// per sub-token it boosted that path 4×, burying the rest of the query's stack
+// (#720). Path relevance must count each original WORD once per level, while
+// still splitting it for cross-convention matching.
+describe('scorePathRelevance per-word scoring (#720)', () => {
+  it('counts a single PascalCase word once per path level, not once per sub-token', () => {
+    // "SuperBizAgent" → super/biz/agent/superbizagent all hit the dir, but it's
+    // one concept: +5 (dir) once, not +20.
+    expect(scorePathRelevance('SuperBizAgentFrontend/app.js', 'SuperBizAgent')).toBe(5);
+  });
+
+  it('still splits a word so it matches across naming conventions', () => {
+    // getUserName must still match a snake_case path via its sub-tokens.
+    expect(scorePathRelevance('get_user_name.go', 'getUserName')).toBeGreaterThanOrEqual(10);
+  });
+
+  it('still credits distinct query words matching different path segments', () => {
+    // auth (dir) and handler (filename) are separate concepts — each counts.
+    expect(scorePathRelevance('src/auth/login_handler.go', 'auth handler')).toBeGreaterThan(
+      scorePathRelevance('src/auth/login_handler.go', 'auth')
+    );
+  });
+});
+
+// The project name is context, not a discriminator: dropping it from path
+// scoring stops every file under a `<ProjectName>…/` tree from winning on the
+// name alone, so the rest of the query decides the ranking (#720).
+describe('project-name down-weighting in path relevance (#720)', () => {
+  it('derives the project name from go.mod / package.json, skipping short names', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-projname-'));
+    try {
+      fs.writeFileSync(path.join(dir, 'go.mod'), 'module example.com/SuperBizAgent\n\ngo 1.21\n');
+      fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: '@acme/superbizagent-web' }));
+      const tokens = deriveProjectNameTokens(dir);
+      expect(tokens.has('superbizagent')).toBe(true);
+      expect(tokens.has('superbizagentweb')).toBe(true);
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('drops a project-name query word from path scoring when other words remain', () => {
+    const proj = new Set(['superbizagent']);
+    // Without the project name dropped, the frontend path wins on it (+5).
+    // With it dropped, only "backend" is left — and it doesn't match this path.
+    const withDrop = scorePathRelevance('SuperBizAgentFrontend/app.js', 'SuperBizAgent backend', proj);
+    const noDrop = scorePathRelevance('SuperBizAgentFrontend/app.js', 'SuperBizAgent backend');
+    expect(withDrop).toBeLessThan(noDrop);
+    expect(withDrop).toBe(0);
+  });
+
+  it('keeps the project-name word when it is the ONLY query word (bare query still scores)', () => {
+    const proj = new Set(['superbizagent']);
+    expect(scorePathRelevance('SuperBizAgentFrontend/app.js', 'SuperBizAgent', proj)).toBe(5);
+  });
+
+  it('does not affect a query that omits the project name', () => {
+    const proj = new Set(['superbizagent']);
+    const path0 = 'internal/controller/chat/chat.go';
+    expect(scorePathRelevance(path0, 'controller chat', proj)).toBe(
+      scorePathRelevance(path0, 'controller chat')
+    );
+  });
+});
+
+describe('Context ranking — common-word precision & confidence', () => {
+  let testDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(async () => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-ctxrank-'));
+
+    // The corroborated target: a capture-flow screen whose NAME alone matches
+    // three query terms (capture + intro + screen), and which lives under a
+    // matching directory.
+    const captureDir = path.join(testDir, 'src', 'app', 'capture');
+    fs.mkdirSync(captureDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(captureDir, 'intro.tsx'),
+      `export function CaptureIntroScreen() {
+  // Onboarding screen shown before the user selects flat or standing object capture.
+  return null;
+}
+`
+    );
+
+    // The trap: an unrelated constant literally named FLAT, in a totally
+    // different area. "flat" in a prose query exact-matches it.
+    const scriptsDir = path.join(testDir, 'scripts', 'dataset');
+    fs.mkdirSync(scriptsDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(scriptsDir, 'download.ts'),
+      `export const FLAT = 'freiburg_flat_dataset';
+export function downloadDataset(name: string): string { return name; }
+`
+    );
+
+    cg = CodeGraph.initSync(testDir, {
+      config: { include: ['**/*.ts', '**/*.tsx'], exclude: [] },
+    });
+    await cg.indexAll();
+  });
+
+  afterEach(() => {
+    if (cg) cg.destroy();
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('does not let a common-word exact match (FLAT) outrank a corroborated symbol', async () => {
+    const sg = await cg.findRelevantContext(
+      'capture intro onboarding screen flat object'
+    );
+    const rootNames = sg.roots.map((id) => sg.nodes.get(id)?.name);
+
+    // The corroborated capture screen surfaces as an entry point...
+    expect(rootNames).toContain('CaptureIntroScreen');
+    // ...and the trap constant is never the lead result (the bug we fixed).
+    expect(rootNames[0]).not.toBe('FLAT');
+
+    const capIdx = rootNames.indexOf('CaptureIntroScreen');
+    const flatIdx = rootNames.indexOf('FLAT');
+    if (flatIdx >= 0) expect(capIdx).toBeLessThan(flatIdx);
+
+    // And it's confidently answered (we located a corroborated symbol).
+    expect(sg.confidence).toBe('high');
+  });
+
+  it('flags low confidence and emits the handoff when only common words match', async () => {
+    const query = 'flat object thing';
+    const sg = await cg.findRelevantContext(query);
+    expect(sg.confidence).toBe('low');
+
+    const md = await cg.buildContext(query, { format: 'markdown' });
+    expect(typeof md).toBe('string');
+    expect(md as string).toContain(LOW_CONFIDENCE_MARKER);
+    // The handoff routes to the precise tools rather than claiming completeness.
+    expect(md as string).toMatch(/codegraph_explore/);
+  });
+
+  it('does not emit the handoff for a precise, distinctive-symbol query', async () => {
+    const sg = await cg.findRelevantContext('CaptureIntroScreen');
+    expect(sg.confidence).toBe('high');
+
+    const md = await cg.buildContext('CaptureIntroScreen', { format: 'markdown' });
+    expect(md as string).not.toContain(LOW_CONFIDENCE_MARKER);
+  });
+});
diff --git a/__tests__/daemon-attach-log.test.ts b/__tests__/daemon-attach-log.test.ts
new file mode 100644
index 000000000..7640ac68b
--- /dev/null
+++ b/__tests__/daemon-attach-log.test.ts
@@ -0,0 +1,38 @@
+/**
+ * #618 — the "attached to shared daemon" line is benign INFO, but MCP hosts
+ * render server stderr at error level (and tack on an `undefined` data field),
+ * so on every session start a healthy attach showed up as `[error] … undefined`.
+ * It's now gated behind CODEGRAPH_MCP_LOG_ATTACH=1 — silent by default, opt-in
+ * for debugging. Approach from #640 by @mturac.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { logAttachedDaemon } from '../src/mcp/proxy';
+
+const hello = { pid: 4242, codegraph: '9.9.9' } as any;
+
+describe('daemon attach log gating (#618)', () => {
+  let spy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    spy = vi.spyOn(process.stderr, 'write').mockImplementation((() => true) as any);
+  });
+
+  afterEach(() => {
+    spy.mockRestore();
+    delete process.env.CODEGRAPH_MCP_LOG_ATTACH;
+  });
+
+  it('is silent by default (no [error]/undefined noise in MCP hosts)', () => {
+    delete process.env.CODEGRAPH_MCP_LOG_ATTACH;
+    logAttachedDaemon('/tmp/cg.sock', hello);
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('logs the attach line only when CODEGRAPH_MCP_LOG_ATTACH=1 (opt-in debug)', () => {
+    process.env.CODEGRAPH_MCP_LOG_ATTACH = '1';
+    logAttachedDaemon('/tmp/cg.sock', hello);
+    const out = spy.mock.calls.map((c) => String(c[0])).join('');
+    expect(out).toContain('Attached to shared daemon on /tmp/cg.sock');
+    expect(out).toContain('pid 4242');
+  });
+});
diff --git a/__tests__/daemon-client-liveness.test.ts b/__tests__/daemon-client-liveness.test.ts
new file mode 100644
index 000000000..1a3b7dee0
--- /dev/null
+++ b/__tests__/daemon-client-liveness.test.ts
@@ -0,0 +1,110 @@
+/**
+ * Unit coverage for the daemon-side client-liveness primitives (#692, Layer 2).
+ *
+ * These back the daemon's defense against a phantom client — one whose process
+ * died without the socket ever signalling close (a Windows named-pipe hazard).
+ * The wire parsing and the liveness decision are pure, so they're tested here;
+ * the full handshake + sweep is exercised end-to-end in `mcp-daemon.test.ts`.
+ */
+import { describe, it, expect } from 'vitest';
+import { Daemon, parseClientHelloLine, peerIsDead } from '../src/mcp/daemon';
+
+describe('parseClientHelloLine', () => {
+  it('parses a well-formed client-hello', () => {
+    expect(parseClientHelloLine('{"codegraph_client":1,"pid":1234,"hostPid":56}'))
+      .toEqual({ pid: 1234, hostPid: 56 });
+  });
+
+  it('accepts a null host pid and a missing host pid', () => {
+    expect(parseClientHelloLine('{"codegraph_client":1,"pid":1234,"hostPid":null}'))
+      .toEqual({ pid: 1234, hostPid: null });
+    expect(parseClientHelloLine('{"codegraph_client":1,"pid":1234}'))
+      .toEqual({ pid: 1234, hostPid: null });
+  });
+
+  it('returns null for a JSON-RPC message (no marker) so it is treated as data', () => {
+    expect(parseClientHelloLine('{"jsonrpc":"2.0","id":1,"method":"initialize"}')).toBeNull();
+  });
+
+  it('rejects a wrong-typed marker, a non-numeric pid, and a non-integer marker', () => {
+    expect(parseClientHelloLine('{"codegraph_client":true,"pid":1}')).toBeNull();
+    expect(parseClientHelloLine('{"codegraph_client":2,"pid":1}')).toBeNull();
+    expect(parseClientHelloLine('{"codegraph_client":1,"pid":"1"}')).toBeNull();
+  });
+
+  it('returns null for invalid / empty / non-object JSON', () => {
+    expect(parseClientHelloLine('not json')).toBeNull();
+    expect(parseClientHelloLine('')).toBeNull();
+    expect(parseClientHelloLine('42')).toBeNull();
+    expect(parseClientHelloLine('null')).toBeNull();
+  });
+});
+
+describe('peerIsDead', () => {
+  const aliveAll = () => true;
+  const deadAll = () => false;
+  const deadOnly = (...pids: number[]) => (pid: number) => !pids.includes(pid);
+
+  it('never reaps a client with an unknown pid (no client-hello)', () => {
+    expect(peerIsDead({ pid: null, hostPid: null }, deadAll)).toBe(false);
+    expect(peerIsDead({ pid: null, hostPid: 99 }, deadAll)).toBe(false);
+  });
+
+  it('keeps a client whose proxy is alive', () => {
+    expect(peerIsDead({ pid: 100, hostPid: null }, aliveAll)).toBe(false);
+  });
+
+  it('reaps a client whose proxy process is gone', () => {
+    expect(peerIsDead({ pid: 100, hostPid: null }, deadOnly(100))).toBe(true);
+  });
+
+  it('reaps when the proxy is alive but its host is gone', () => {
+    // proxy 100 alive, host 42 dead
+    expect(peerIsDead({ pid: 100, hostPid: 42 }, deadOnly(42))).toBe(true);
+  });
+
+  it('keeps a client when both proxy and host are alive', () => {
+    expect(peerIsDead({ pid: 100, hostPid: 42 }, aliveAll)).toBe(false);
+  });
+});
+
+describe('Daemon.reapDeadClients', () => {
+  // Construct with idleTimeoutMs:0 so dropping the last client doesn't arm a real
+  // idle timer. The constructor opens no sockets/DB, so this stays a fast unit test.
+  const makeDaemon = () => new Daemon('/tmp/codegraph-reap-unit-test', { idleTimeoutMs: 0 }) as any;
+  const fakeSession = () => ({ stopped: false, stop() { this.stopped = true; } });
+
+  it('drops clients with a dead peer and leaves live ones attached', () => {
+    const d = makeDaemon();
+    const dead = fakeSession();
+    const live = fakeSession();
+    d.clients.add(dead); d.clientPeers.set(dead, { pid: 111, hostPid: null });
+    d.clients.add(live); d.clientPeers.set(live, { pid: 222, hostPid: null });
+
+    const reaped = d.reapDeadClients((pid: number) => pid !== 111); // 111 dead, 222 alive
+
+    expect(reaped).toBe(1);
+    expect(dead.stopped).toBe(true);
+    expect(d.clients.has(dead)).toBe(false);
+    expect(d.clientPeers.has(dead)).toBe(false); // peer record cleaned up too
+    expect(d.clients.has(live)).toBe(true);
+  });
+
+  it('never reaps a client with an unknown pid (no client-hello)', () => {
+    const d = makeDaemon();
+    const s = fakeSession();
+    d.clients.add(s); d.clientPeers.set(s, { pid: null, hostPid: null });
+
+    expect(d.reapDeadClients(() => false)).toBe(0); // everything "dead", but pid unknown
+    expect(d.clients.has(s)).toBe(true);
+  });
+
+  it('reaps a client whose host pid is gone even if its proxy pid is alive', () => {
+    const d = makeDaemon();
+    const s = fakeSession();
+    d.clients.add(s); d.clientPeers.set(s, { pid: 100, hostPid: 42 });
+
+    expect(d.reapDeadClients((pid: number) => pid !== 42)).toBe(1); // proxy 100 alive, host 42 dead
+    expect(d.clients.has(s)).toBe(false);
+  });
+});
diff --git a/__tests__/db-perf.test.ts b/__tests__/db-perf.test.ts
new file mode 100644
index 000000000..1dc3f1eb6
--- /dev/null
+++ b/__tests__/db-perf.test.ts
@@ -0,0 +1,207 @@
+/**
+ * DB Performance / Correctness Tests
+ *
+ * Regression tests for three changes:
+ *   1. Batch `getNodesByIds` collapses graph-traversal N+1 reads.
+ *   2. `insertNode` invalidates the LRU cache so INSERT OR REPLACE
+ *      doesn't serve a stale cached row on next `getNodeById`.
+ *   3. `runMaintenance` runs `PRAGMA optimize` + `wal_checkpoint(PASSIVE)`
+ *      after indexAll/sync without throwing.
+ *   4. `insertEdges` validates endpoints from the DB, not stale node cache.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { DatabaseConnection } from '../src/db';
+import { QueryBuilder } from '../src/db/queries';
+import { Node } from '../src/types';
+
+function makeNode(id: string, name = id): Node {
+  return {
+    id,
+    kind: 'function',
+    name,
+    qualifiedName: name,
+    filePath: 'a.ts',
+    language: 'typescript',
+    startLine: 1,
+    endLine: 1,
+    startColumn: 0,
+    endColumn: 0,
+    updatedAt: Date.now(),
+  };
+}
+
+describe('getNodesByIds (batch lookup)', () => {
+  let dir: string;
+  let db: DatabaseConnection;
+  let q: QueryBuilder;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'db-perf-batch-'));
+    db = DatabaseConnection.initialize(path.join(dir, 'test.db'));
+    q = new QueryBuilder(db.getDb());
+  });
+
+  afterEach(() => {
+    db.close();
+    if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('returns a Map keyed by id, with one entry per existing node', () => {
+    q.insertNodes([makeNode('n1'), makeNode('n2'), makeNode('n3')]);
+    const out = q.getNodesByIds(['n1', 'n2', 'n3']);
+    expect(out.size).toBe(3);
+    expect(out.get('n1')!.name).toBe('n1');
+    expect(out.get('n3')!.name).toBe('n3');
+  });
+
+  it('omits missing IDs from the result map (no nulls, no exceptions)', () => {
+    q.insertNodes([makeNode('n1'), makeNode('n2')]);
+    const out = q.getNodesByIds(['n1', 'missing', 'n2']);
+    expect(out.size).toBe(2);
+    expect(out.has('missing')).toBe(false);
+    expect(out.has('n1')).toBe(true);
+    expect(out.has('n2')).toBe(true);
+  });
+
+  it('handles an empty input array', () => {
+    expect(q.getNodesByIds([]).size).toBe(0);
+  });
+
+  it('handles batches over the SQLite parameter limit (chunking)', () => {
+    // Insert 1500 nodes; the helper chunks at 500 internally.
+    const nodes = Array.from({ length: 1500 }, (_, i) => makeNode(`n${i}`));
+    q.insertNodes(nodes);
+    const ids = nodes.map((n) => n.id);
+    const out = q.getNodesByIds(ids);
+    expect(out.size).toBe(1500);
+    // Spot-check a few from the first / middle / last chunk.
+    expect(out.has('n0')).toBe(true);
+    expect(out.has('n750')).toBe(true);
+    expect(out.has('n1499')).toBe(true);
+  });
+
+  it('serves cache hits from memory and queries only the misses', () => {
+    q.insertNodes([makeNode('n1'), makeNode('n2'), makeNode('n3')]);
+    // Warm the cache for n1 only.
+    q.getNodeById('n1');
+    // Replace the underlying row to make a miss-vs-cache-hit detectable.
+    db.getDb().prepare('UPDATE nodes SET name = ? WHERE id = ?').run('changed', 'n1');
+    const out = q.getNodesByIds(['n1', 'n2']);
+    // The cached n1 (still 'n1', not 'changed') must be returned.
+    expect(out.get('n1')!.name).toBe('n1');
+    expect(out.get('n2')!.name).toBe('n2');
+  });
+});
+
+describe('insertNode cache invalidation', () => {
+  let dir: string;
+  let db: DatabaseConnection;
+  let q: QueryBuilder;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'db-perf-cache-'));
+    db = DatabaseConnection.initialize(path.join(dir, 'test.db'));
+    q = new QueryBuilder(db.getDb());
+  });
+
+  afterEach(() => {
+    db.close();
+    if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('does not serve a stale cached node after INSERT OR REPLACE', () => {
+    // Regression: insertNode (which uses INSERT OR REPLACE) used to skip
+    // cache invalidation, so the next getNodeById returned the pre-replace
+    // version until LRU eviction.
+    const original = makeNode('n1', 'oldName');
+    q.insertNode(original);
+    const beforeReplace = q.getNodeById('n1');
+    expect(beforeReplace!.name).toBe('oldName');
+
+    // Replace via insertNode (the bug path).
+    q.insertNode({ ...original, name: 'newName', updatedAt: Date.now() });
+    const afterReplace = q.getNodeById('n1');
+    expect(afterReplace!.name).toBe('newName');
+  });
+});
+
+describe('insertEdges endpoint validation', () => {
+  let dir: string;
+  let db: DatabaseConnection;
+  let q: QueryBuilder;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'db-perf-edges-'));
+    db = DatabaseConnection.initialize(path.join(dir, 'test.db'));
+    q = new QueryBuilder(db.getDb());
+  });
+
+  afterEach(() => {
+    db.close();
+    if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('skips edges with missing endpoints instead of failing the whole batch', () => {
+    q.insertNodes([makeNode('source'), makeNode('target'), makeNode('other')]);
+
+    expect(() =>
+      q.insertEdges([
+        { source: 'source', target: 'target', kind: 'calls' },
+        { source: 'source', target: 'missing-target', kind: 'calls' },
+        { source: 'missing-source', target: 'other', kind: 'references' },
+      ])
+    ).not.toThrow();
+
+    const edges = q.getOutgoingEdges('source');
+    expect(edges).toHaveLength(1);
+    expect(edges[0]).toMatchObject({ source: 'source', target: 'target', kind: 'calls' });
+  });
+
+  it('does not trust stale cached nodes when validating edge endpoints', () => {
+    q.insertNodes([makeNode('source'), makeNode('target')]);
+    expect(q.getNodeById('target')!.id).toBe('target');
+
+    db.getDb().prepare('DELETE FROM nodes WHERE id = ?').run('target');
+
+    expect(() =>
+      q.insertEdges([{ source: 'source', target: 'target', kind: 'calls' }])
+    ).not.toThrow();
+    expect(q.getOutgoingEdges('source')).toEqual([]);
+  });
+});
+
+describe('runMaintenance', () => {
+  let dir: string;
+  let db: DatabaseConnection;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'db-perf-maint-'));
+    db = DatabaseConnection.initialize(path.join(dir, 'test.db'));
+  });
+
+  afterEach(() => {
+    db.close();
+    if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('runs without throwing on a fresh database', () => {
+    expect(() => db.runMaintenance()).not.toThrow();
+  });
+
+  it('runs without throwing after writes', () => {
+    const q = new QueryBuilder(db.getDb());
+    q.insertNodes([makeNode('n1'), makeNode('n2')]);
+    expect(() => db.runMaintenance()).not.toThrow();
+  });
+
+  it('swallows failures rather than propagating (best-effort)', () => {
+    // Close the DB so the underlying handle would normally throw on any
+    // exec(). runMaintenance must still not propagate.
+    db.close();
+    expect(() => db.runMaintenance()).not.toThrow();
+  });
+});
diff --git a/__tests__/drupal.test.ts b/__tests__/drupal.test.ts
new file mode 100644
index 000000000..c4f4421e9
--- /dev/null
+++ b/__tests__/drupal.test.ts
@@ -0,0 +1,609 @@
+/**
+ * Tests for Drupal framework resolver.
+ *
+ * Unit tests cover drupalResolver.detect(), extract() (routes + hooks), and resolve().
+ * Integration tests use a real CodeGraph instance with a temporary Drupal project layout.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { afterEach, beforeAll, describe, expect, it } from 'vitest';
+import { CodeGraph } from '../src';
+import { initGrammars, loadAllGrammars } from '../src/extraction/grammars';
+import { drupalResolver } from '../src/resolution/frameworks/drupal';
+import type { ResolutionContext } from '../src/resolution/types';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeContext(
+  overrides: Partial<ResolutionContext> = {},
+): ResolutionContext {
+  return {
+    getNodesInFile: () => [],
+    getNodesByName: () => [],
+    getNodesByQualifiedName: () => [],
+    getNodesByKind: () => [],
+    fileExists: () => false,
+    readFile: () => null,
+    getProjectRoot: () => '/project',
+    getAllFiles: () => [],
+    getNodesByLowerName: () => [],
+    getImportMappings: () => [],
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// detect()
+// ---------------------------------------------------------------------------
+
+describe('drupalResolver.detect', () => {
+  it('returns true when composer.json has a drupal/ dependency', () => {
+    const ctx = makeContext({
+      readFile: (f) =>
+        f === 'composer.json'
+          ? JSON.stringify({
+              require: {
+                'drupal/core-recommended': '~10.5',
+                'drush/drush': '^13',
+              },
+            })
+          : null,
+    });
+    expect(drupalResolver.detect(ctx)).toBe(true);
+  });
+
+  it('returns true when drupal/ dependency is in require-dev', () => {
+    const ctx = makeContext({
+      readFile: (f) =>
+        f === 'composer.json'
+          ? JSON.stringify({ 'require-dev': { 'drupal/core': '^10' } })
+          : null,
+    });
+    expect(drupalResolver.detect(ctx)).toBe(true);
+  });
+
+  it('returns false when composer.json has no drupal/ dependencies', () => {
+    const ctx = makeContext({
+      readFile: (f) =>
+        f === 'composer.json'
+          ? JSON.stringify({
+              require: { 'laravel/framework': '^10', php: '>=8.1' },
+            })
+          : null,
+    });
+    expect(drupalResolver.detect(ctx)).toBe(false);
+  });
+
+  it('returns false when composer.json is absent', () => {
+    const ctx = makeContext({ readFile: () => null });
+    expect(drupalResolver.detect(ctx)).toBe(false);
+  });
+
+  it('returns false when composer.json is malformed JSON', () => {
+    const ctx = makeContext({ readFile: () => '{ bad json' });
+    expect(drupalResolver.detect(ctx)).toBe(false);
+  });
+
+  it('returns true for a contrib module with empty require (composer name/type)', () => {
+    const ctx = makeContext({
+      readFile: (f) =>
+        f === 'composer.json'
+          ? JSON.stringify({
+              name: 'drupal/admin_toolbar',
+              type: 'drupal-module',
+              require: {},
+            })
+          : null,
+    });
+    expect(drupalResolver.detect(ctx)).toBe(true);
+  });
+
+  it('returns true via the *.info.yml fallback when composer.json is absent', () => {
+    const ctx = makeContext({
+      readFile: () => null,
+      getAllFiles: () => [
+        'mymodule/mymodule.info.yml',
+        'mymodule/mymodule.routing.yml',
+      ],
+    });
+    expect(drupalResolver.detect(ctx)).toBe(true);
+  });
+
+  it('returns false for a stray *.info.yml with no Drupal PHP/route file', () => {
+    const ctx = makeContext({
+      readFile: () => null,
+      getAllFiles: () => ['some/unrelated.info.yml'],
+    });
+    expect(drupalResolver.detect(ctx)).toBe(false);
+  });
+});
+
+describe('drupalResolver.claimsReference', () => {
+  it('claims FQCN handler refs and hook names the pre-filter would drop', () => {
+    expect(drupalResolver.claimsReference!('\\Drupal\\m\\Form\\SettingsForm')).toBe(true);
+    expect(drupalResolver.claimsReference!('\\Drupal\\m\\Controller\\C:setNoJsCookie')).toBe(true);
+    expect(drupalResolver.claimsReference!('hook_form_alter')).toBe(true);
+  });
+
+  it('does not claim ordinary identifiers or entity-handler dotted refs', () => {
+    expect(drupalResolver.claimsReference!('someHelperFunction')).toBe(false);
+    expect(drupalResolver.claimsReference!('comment.default')).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extract() — routing.yml
+// ---------------------------------------------------------------------------
+
+describe('drupalResolver.extract — routing.yml', () => {
+  const routing = `
+mymodule.example:
+  path: '/mymodule/example'
+  defaults:
+    _controller: '\\Drupal\\mymodule\\Controller\\MyController::build'
+    _title: 'Example page'
+  requirements:
+    _permission: 'access content'
+`;
+
+  it('emits a route node for each YAML route', () => {
+    const { nodes } = drupalResolver.extract!(
+      'mymodule/mymodule.routing.yml',
+      routing,
+    );
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0]!.kind).toBe('route');
+    expect(nodes[0]!.name).toBe('/mymodule/example');
+  });
+
+  it('sets qualifiedName to filePath::routeName', () => {
+    const { nodes } = drupalResolver.extract!(
+      'mymodule/mymodule.routing.yml',
+      routing,
+    );
+    expect(nodes[0]!.qualifiedName).toBe(
+      'mymodule/mymodule.routing.yml::mymodule.example',
+    );
+  });
+
+  it('emits a references edge to the controller FQCN', () => {
+    const { references } = drupalResolver.extract!(
+      'mymodule/mymodule.routing.yml',
+      routing,
+    );
+    expect(references).toHaveLength(1);
+    expect(references[0]!.referenceName).toBe(
+      '\\Drupal\\mymodule\\Controller\\MyController::build',
+    );
+    expect(references[0]!.referenceKind).toBe('references');
+  });
+
+  it('emits a references edge to a _form handler', () => {
+    const src = `
+mymodule.settings_form:
+  path: '/admin/config/mymodule'
+  defaults:
+    _form: '\\Drupal\\mymodule\\Form\\SettingsForm'
+    _title: 'MyModule settings'
+  requirements:
+    _permission: 'administer site configuration'
+`;
+    const { nodes, references } = drupalResolver.extract!(
+      'mymodule/mymodule.routing.yml',
+      src,
+    );
+    expect(nodes).toHaveLength(1);
+    expect(references[0]!.referenceName).toBe(
+      '\\Drupal\\mymodule\\Form\\SettingsForm',
+    );
+  });
+
+  it('handles multiple routes in one file', () => {
+    const src = `
+mod.page_one:
+  path: '/page-one'
+  defaults:
+    _controller: '\\Drupal\\mod\\Controller\\PageController::one'
+  requirements:
+    _permission: 'access content'
+
+mod.page_two:
+  path: '/page-two'
+  defaults:
+    _controller: '\\Drupal\\mod\\Controller\\PageController::two'
+  requirements:
+    _permission: 'access content'
+`;
+    const { nodes, references } = drupalResolver.extract!(
+      'mod/mod.routing.yml',
+      src,
+    );
+    expect(nodes).toHaveLength(2);
+    expect(nodes.map((n) => n.name)).toContain('/page-one');
+    expect(nodes.map((n) => n.name)).toContain('/page-two');
+    expect(references).toHaveLength(2);
+  });
+
+  it('skips commented-out lines', () => {
+    const src = `
+mod.page:
+  path: '/page'
+  defaults:
+    #_controller: '\\Drupal\\mod\\Controller\\Old::build'
+    _controller: '\\Drupal\\mod\\Controller\\New::build'
+  requirements:
+    _permission: 'access content'
+`;
+    const { references } = drupalResolver.extract!('mod/mod.routing.yml', src);
+    expect(references).toHaveLength(1);
+    expect(references[0]!.referenceName).toContain('New');
+  });
+
+  it('includes HTTP methods in the route node name when present', () => {
+    const src = `
+mod.api:
+  path: '/api/resource'
+  defaults:
+    _controller: '\\Drupal\\mod\\Controller\\ApiController::get'
+  methods: [GET, POST]
+  requirements:
+    _permission: 'access content'
+`;
+    const { nodes } = drupalResolver.extract!('mod/mod.routing.yml', src);
+    expect(nodes[0]!.name).toContain('GET');
+    expect(nodes[0]!.name).toContain('POST');
+  });
+
+  it('returns empty result for non-routing-yml files', () => {
+    const { nodes, references } = drupalResolver.extract!(
+      'mymodule.module',
+      '<?php\n',
+    );
+    // Module files go through hook detection, not route extraction
+    expect(nodes).toHaveLength(0);
+  });
+
+  it('returns empty result for files with no valid routes', () => {
+    const { nodes, references } = drupalResolver.extract!(
+      'some.routing.yml',
+      '# empty\n',
+    );
+    expect(nodes).toHaveLength(0);
+    expect(references).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extract() — hook detection in .module files
+// ---------------------------------------------------------------------------
+
+describe('drupalResolver.extract — hook detection', () => {
+  it('detects hook implementation via docblock (Strategy A)', () => {
+    const src = `<?php
+
+/**
+ * Implements hook_form_alter().
+ */
+function mymodule_form_alter(&$form, $form_state, $form_id) {
+  // ...
+}
+`;
+    const { references } = drupalResolver.extract!(
+      'web/modules/custom/mymodule/mymodule.module',
+      src,
+    );
+    const hookRef = references.find(
+      (r) => r.referenceName === 'hook_form_alter',
+    );
+    expect(hookRef).toBeDefined();
+    expect(hookRef!.referenceKind).toBe('references');
+  });
+
+  it('detects hook implementation via name pattern (Strategy B)', () => {
+    const src = `<?php
+
+function mymodule_views_data() {
+  return [];
+}
+`;
+    const { references } = drupalResolver.extract!(
+      'web/modules/custom/mymodule/mymodule.module',
+      src,
+    );
+    const hookRef = references.find(
+      (r) => r.referenceName === 'hook_views_data',
+    );
+    expect(hookRef).toBeDefined();
+  });
+
+  it('does not emit a hook ref for non-hook helper functions', () => {
+    // 'other_module_helper' doesn't start with 'mymodule_', so no hook ref
+    const src = `<?php
+function other_module_helper() {}
+`;
+    const { references } = drupalResolver.extract!(
+      'web/modules/custom/mymodule/mymodule.module',
+      src,
+    );
+    expect(references).toHaveLength(0);
+  });
+
+  it('detects hooks in .install files', () => {
+    const src = `<?php
+/**
+ * Implements hook_schema().
+ */
+function mymodule_schema() {
+  return [];
+}
+`;
+    const { references } = drupalResolver.extract!(
+      'web/modules/custom/mymodule/mymodule.install',
+      src,
+    );
+    const hookRef = references.find((r) => r.referenceName === 'hook_schema');
+    expect(hookRef).toBeDefined();
+  });
+
+  it('detects hooks in .theme files', () => {
+    const src = `<?php
+/**
+ * Implements hook_preprocess_node().
+ */
+function mytheme_preprocess_node(&$variables) {}
+`;
+    const { references } = drupalResolver.extract!(
+      'web/themes/custom/mytheme/mytheme.theme',
+      src,
+    );
+    const hookRef = references.find(
+      (r) => r.referenceName === 'hook_preprocess_node',
+    );
+    expect(hookRef).toBeDefined();
+  });
+
+  it('does not duplicate refs when both docblock and name pattern match', () => {
+    // Strategy A matches first and adds to docblockMatched set;
+    // Strategy B skips already-matched functions.
+    const src = `<?php
+/**
+ * Implements hook_form_alter().
+ */
+function mymodule_form_alter(&$form, $form_state, $form_id) {}
+`;
+    const { references } = drupalResolver.extract!(
+      'web/modules/custom/mymodule/mymodule.module',
+      src,
+    );
+    const hookRefs = references.filter(
+      (r) => r.referenceName === 'hook_form_alter',
+    );
+    expect(hookRefs).toHaveLength(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolve()
+// ---------------------------------------------------------------------------
+
+describe('drupalResolver.resolve', () => {
+  it('resolves a _controller FQCN with ::method to the method node', () => {
+    const methodNode = {
+      id: 'method:abc123',
+      kind: 'method' as const,
+      name: 'build',
+      qualifiedName: 'MyController::build',
+      filePath: 'web/modules/custom/mymodule/src/Controller/MyController.php',
+      language: 'php' as const,
+      startLine: 10,
+      endLine: 20,
+      startColumn: 0,
+      endColumn: 0,
+      updatedAt: 0,
+    };
+    const classNode = {
+      id: 'class:def456',
+      kind: 'class' as const,
+      name: 'MyController',
+      qualifiedName: 'MyController',
+      filePath: 'web/modules/custom/mymodule/src/Controller/MyController.php',
+      language: 'php' as const,
+      startLine: 5,
+      endLine: 30,
+      startColumn: 0,
+      endColumn: 0,
+      updatedAt: 0,
+    };
+    const ctx = makeContext({
+      getNodesByName: (name) => (name === 'MyController' ? [classNode] : []),
+      getNodesInFile: () => [classNode, methodNode],
+    });
+    const ref = {
+      fromNodeId: 'route:x',
+      referenceName: '\\Drupal\\mymodule\\Controller\\MyController::build',
+      referenceKind: 'references' as const,
+      line: 1,
+      column: 0,
+      filePath: 'mymodule.routing.yml',
+      language: 'yaml' as const,
+    };
+    const resolved = drupalResolver.resolve(ref, ctx);
+    expect(resolved).not.toBeNull();
+    expect(resolved!.targetNodeId).toBe('method:abc123');
+    expect(resolved!.confidence).toBeGreaterThanOrEqual(0.85);
+  });
+
+  it('resolves a _form FQCN (no ::method) to the class node', () => {
+    const classNode = {
+      id: 'class:form123',
+      kind: 'class' as const,
+      name: 'SettingsForm',
+      qualifiedName: 'SettingsForm',
+      filePath: 'web/modules/custom/mymodule/src/Form/SettingsForm.php',
+      language: 'php' as const,
+      startLine: 1,
+      endLine: 50,
+      startColumn: 0,
+      endColumn: 0,
+      updatedAt: 0,
+    };
+    const ctx = makeContext({
+      getNodesByName: (name) => (name === 'SettingsForm' ? [classNode] : []),
+    });
+    const ref = {
+      fromNodeId: 'route:x',
+      referenceName: '\\Drupal\\mymodule\\Form\\SettingsForm',
+      referenceKind: 'references' as const,
+      line: 1,
+      column: 0,
+      filePath: 'mymodule.routing.yml',
+      language: 'yaml' as const,
+    };
+    const resolved = drupalResolver.resolve(ref, ctx);
+    expect(resolved).not.toBeNull();
+    expect(resolved!.targetNodeId).toBe('class:form123');
+  });
+
+  it('returns null when the target class cannot be found', () => {
+    const ctx = makeContext({ getNodesByName: () => [] });
+    const ref = {
+      fromNodeId: 'route:x',
+      referenceName: '\\Drupal\\mymodule\\Controller\\Missing::method',
+      referenceKind: 'references' as const,
+      line: 1,
+      column: 0,
+      filePath: 'mymodule.routing.yml',
+      language: 'yaml' as const,
+    };
+    expect(drupalResolver.resolve(ref, ctx)).toBeNull();
+  });
+
+  it('resolves a single-colon controller-service ref (Class:method)', () => {
+    const methodNode = {
+      id: 'method:nojs1',
+      kind: 'method' as const,
+      name: 'setNoJsCookie',
+      qualifiedName: 'BigPipeController::setNoJsCookie',
+      filePath: 'core/modules/big_pipe/src/Controller/BigPipeController.php',
+      language: 'php' as const,
+      startLine: 10,
+      endLine: 20,
+      startColumn: 0,
+      endColumn: 0,
+      updatedAt: 0,
+    };
+    const classNode = {
+      id: 'class:nojs2',
+      kind: 'class' as const,
+      name: 'BigPipeController',
+      qualifiedName: 'BigPipeController',
+      filePath: 'core/modules/big_pipe/src/Controller/BigPipeController.php',
+      language: 'php' as const,
+      startLine: 5,
+      endLine: 30,
+      startColumn: 0,
+      endColumn: 0,
+      updatedAt: 0,
+    };
+    const ctx = makeContext({
+      getNodesByName: (name) => (name === 'BigPipeController' ? [classNode] : []),
+      getNodesInFile: () => [classNode, methodNode],
+    });
+    const ref = {
+      fromNodeId: 'route:x',
+      referenceName: '\\Drupal\\big_pipe\\Controller\\BigPipeController:setNoJsCookie',
+      referenceKind: 'references' as const,
+      line: 1,
+      column: 0,
+      filePath: 'big_pipe.routing.yml',
+      language: 'yaml' as const,
+    };
+    const resolved = drupalResolver.resolve(ref, ctx);
+    expect(resolved).not.toBeNull();
+    expect(resolved!.targetNodeId).toBe('method:nojs1');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// End-to-end integration test
+// ---------------------------------------------------------------------------
+
+beforeAll(async () => {
+  await initGrammars();
+  await loadAllGrammars();
+});
+
+describe('Drupal end-to-end — route node linked to controller method', () => {
+  let tmpDir: string | undefined;
+  afterEach(() => {
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  it('creates a route→controller edge from routing.yml to PHP class', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-drupal-'));
+
+    // Minimal composer.json to trigger Drupal detection
+    fs.writeFileSync(
+      path.join(tmpDir, 'composer.json'),
+      JSON.stringify({ require: { 'drupal/core-recommended': '~10.5' } }),
+    );
+
+    // Module directory structure
+    const modDir = path.join(tmpDir, 'web', 'modules', 'custom', 'my_module');
+    fs.mkdirSync(path.join(modDir, 'src', 'Controller'), { recursive: true });
+
+    // routing.yml
+    fs.writeFileSync(
+      path.join(modDir, 'my_module.routing.yml'),
+      [
+        'my_module.hello:',
+        "  path: '/hello'",
+        '  defaults:',
+        "    _controller: '\\Drupal\\my_module\\Controller\\HelloController::build'",
+        "    _title: 'Hello'",
+        '  requirements:',
+        "    _permission: 'access content'",
+      ].join('\n') + '\n',
+    );
+
+    // PHP controller
+    fs.writeFileSync(
+      path.join(modDir, 'src', 'Controller', 'HelloController.php'),
+      [
+        '<?php',
+        'namespace Drupal\\my_module\\Controller;',
+        'use Drupal\\Core\\Controller\\ControllerBase;',
+        'class HelloController extends ControllerBase {',
+        '  public function build() {',
+        "    return ['#markup' => 'Hello'];",
+        '  }',
+        '}',
+      ].join('\n') + '\n',
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    // Route node must exist
+    const routes = cg.getNodesByKind('route');
+    expect(routes.length).toBeGreaterThan(0);
+    const route = routes.find((n) => n.name.includes('/hello'));
+    expect(route).toBeDefined();
+
+    // Controller method must be indexed
+    const methods = cg.getNodesByKind('method');
+    const buildMethod = methods.find((n) => n.name === 'build');
+    expect(buildMethod).toBeDefined();
+
+    // Edge: route → build method (or class fallback)
+    const edges = cg.getOutgoingEdges(route!.id);
+    expect(edges.length).toBeGreaterThan(0);
+
+    cg.close();
+  });
+});
diff --git a/__tests__/explore-blast-radius.test.ts b/__tests__/explore-blast-radius.test.ts
new file mode 100644
index 000000000..23bb84b20
--- /dev/null
+++ b/__tests__/explore-blast-radius.test.ts
@@ -0,0 +1,73 @@
+/**
+ * codegraph_explore blast-radius section.
+ *
+ * explore now appends a compact, always-on "Blast radius" for the entry
+ * symbols: who depends on each (locations only — no source) and which test
+ * files cover it, so the agent knows what to update/verify before editing
+ * without a separate impact call. Symbols with no dependents are skipped, and
+ * the section is omitted entirely when nothing qualifies.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src/index';
+import { ToolHandler } from '../src/mcp/tools';
+
+describe('codegraph_explore — blast radius', () => {
+  let testDir: string;
+  let cg: CodeGraph;
+  let handler: ToolHandler;
+
+  beforeEach(async () => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-blast-'));
+    const src = path.join(testDir, 'src');
+    fs.mkdirSync(src, { recursive: true });
+
+    // `target` is depended on by a sibling (caller) and a test file.
+    fs.writeFileSync(
+      path.join(src, 'feature.ts'),
+      `export function target() { return 1; }\n` +
+      `export function caller() { return target(); }\n`,
+    );
+    fs.writeFileSync(
+      path.join(src, 'feature.test.ts'),
+      `import { target } from './feature';\n` +
+      `export function checkTarget() { return target(); }\n`,
+    );
+    // A leaf with no dependents — must NOT show up in the blast radius.
+    fs.writeFileSync(
+      path.join(src, 'leaf.ts'),
+      `export function lonelyLeaf() { return 42; }\n`,
+    );
+
+    cg = CodeGraph.initSync(testDir, { config: { include: ['**/*.ts'], exclude: [] } });
+    await cg.indexAll();
+    handler = new ToolHandler(cg);
+  });
+
+  afterEach(() => {
+    if (cg) cg.destroy();
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('lists dependents (locations only) and covering tests for an entry symbol', async () => {
+    const res = await handler.execute('codegraph_explore', { query: 'target' });
+    const text = res.content[0].text;
+
+    expect(text).toContain('### Blast radius');
+    expect(text).toContain('`target`');
+    expect(text).toMatch(/caller/); // a caller count is reported
+    // It names WHERE (the caller file) — not the caller's source body.
+    expect(text).toContain('feature.ts');
+    // Test coverage is surfaced (either the covering test file, or the warning).
+    expect(text).toMatch(/tests:.*feature\.test\.ts|no covering tests/);
+  });
+
+  it('omits symbols that have no dependents from the blast radius', async () => {
+    const res = await handler.execute('codegraph_explore', { query: 'lonelyLeaf' });
+    const text = res.content[0].text;
+    // lonelyLeaf has zero callers — it must never appear under a blast-radius bullet.
+    expect(text).not.toMatch(/Blast radius[\s\S]*`lonelyLeaf`/);
+  });
+});
diff --git a/__tests__/explore-output-budget.test.ts b/__tests__/explore-output-budget.test.ts
index 65ddc6488..0726c5684 100644
--- a/__tests__/explore-output-budget.test.ts
+++ b/__tests__/explore-output-budget.test.ts
@@ -27,16 +27,27 @@ describe('getExploreOutputBudget', () => {
     expect(small.maxOutputChars).toBeLessThanOrEqual(20000);
   });
 
-  it('keeps the historical 35k+ ceiling for medium-large projects so existing benchmarks do not regress', () => {
+  it('caps medium-large projects at the inline tool-result ceiling (~24k) so the result is never externalized', () => {
+    // A bigger single response gets externalized by the host to a file the agent
+    // Reads back (a 35k vscode explore did exactly that in the n=4 A/B) — adding a
+    // read AND cache-write cost. So large repos get MORE CALLS (getExploreBudget),
+    // not a fatter single response; the output cap stays under the inline limit.
     const large = getExploreOutputBudget(10000);
-    expect(large.maxOutputChars).toBeGreaterThanOrEqual(35000);
+    expect(large.maxOutputChars).toBeLessThanOrEqual(25000);
+    expect(large.maxOutputChars).toBeGreaterThanOrEqual(20000);
   });
 
   it('uses tier breakpoints matching getExploreBudget so call-count and output-budget agree on a project', () => {
-    // Anything in the same tier should pick the same total-output cap.
-    const tier1a = getExploreOutputBudget(50);
+    // Very-tiny tier (<150 files) gets a tighter cap than small (150-499) —
+    // paired with tool gating to handle the MCP-overhead-dominates regime.
+    const tier0a = getExploreOutputBudget(50);
+    const tier0b = getExploreOutputBudget(149);
+    expect(tier0a.maxOutputChars).toBe(tier0b.maxOutputChars);
+
+    const tier1a = getExploreOutputBudget(150);
     const tier1b = getExploreOutputBudget(499);
     expect(tier1a.maxOutputChars).toBe(tier1b.maxOutputChars);
+    // The <500 explore-call budget covers both very-tiny and small.
     expect(getExploreBudget(50)).toBe(getExploreBudget(499));
 
     const tier2a = getExploreOutputBudget(500);
@@ -48,9 +59,13 @@ describe('getExploreOutputBudget', () => {
     const tier3b = getExploreOutputBudget(14999);
     expect(tier3a.maxOutputChars).toBe(tier3b.maxOutputChars);
 
-    // And crossing a breakpoint changes the cap.
-    expect(tier1a.maxOutputChars).not.toBe(tier2a.maxOutputChars);
-    expect(tier2a.maxOutputChars).not.toBe(tier3a.maxOutputChars);
+    // Small tiers step up (13k → 18k → 24k); medium and large SHARE the ~24k
+    // inline ceiling — scaling with repo size now lives in the CALL budget
+    // (getExploreBudget), not in a fatter single response.
+    expect(tier0a.maxOutputChars).not.toBe(tier1a.maxOutputChars); // <150 vs <500
+    expect(tier1a.maxOutputChars).not.toBe(tier2a.maxOutputChars); // <500 vs <5000
+    expect(tier2a.maxOutputChars).toBe(tier3a.maxOutputChars);     // <5000 == <15000 (inline cap)
+    expect(getExploreBudget(5000)).toBeGreaterThan(getExploreBudget(4999)); // calls scale instead
   });
 
   it('gates off "Additional relevant files", completeness signal, and budget note on small projects', () => {
@@ -67,8 +82,12 @@ describe('getExploreOutputBudget', () => {
     expect(medium.includeBudgetNote).toBe(true);
   });
 
-  it('keeps the Relationships section on for every tier — it is the cheapest structural signal', () => {
-    expect(getExploreOutputBudget(50).includeRelationships).toBe(true);
+  it('keeps the Relationships section on for medium+ tiers — small tiers drop it to maximize body density', () => {
+    // ITER2: relationships dropped on <500 tiers; on tiny repos the
+    // per-call payload is the cost driver, so even "cheap" structural
+    // signal adds up across follow-up turns. Re-enabled at ≥500 where
+    // body budgets are roomy enough to absorb the 1-2KB overhead.
+    expect(getExploreOutputBudget(50).includeRelationships).toBe(false);
     expect(getExploreOutputBudget(1000).includeRelationships).toBe(true);
     expect(getExploreOutputBudget(10000).includeRelationships).toBe(true);
     expect(getExploreOutputBudget(30000).includeRelationships).toBe(true);
@@ -91,8 +110,11 @@ describe('getExploreOutputBudget', () => {
   });
 
   it('handles the boundary file counts exactly (off-by-one regression guard)', () => {
-    // 499 -> small tier, 500 -> medium tier
-    expect(getExploreOutputBudget(499).maxOutputChars).toBe(getExploreOutputBudget(100).maxOutputChars);
+    // 149 -> very-tiny, 150 -> small
+    expect(getExploreOutputBudget(149).maxOutputChars).toBe(getExploreOutputBudget(50).maxOutputChars);
+    expect(getExploreOutputBudget(150).maxOutputChars).toBe(getExploreOutputBudget(200).maxOutputChars);
+    // 499 -> small, 500 -> medium
+    expect(getExploreOutputBudget(499).maxOutputChars).toBe(getExploreOutputBudget(200).maxOutputChars);
     expect(getExploreOutputBudget(500).maxOutputChars).toBe(getExploreOutputBudget(1000).maxOutputChars);
     // 4999 -> medium, 5000 -> large
     expect(getExploreOutputBudget(4999).maxOutputChars).toBe(getExploreOutputBudget(1000).maxOutputChars);
diff --git a/__tests__/expo-modules.test.ts b/__tests__/expo-modules.test.ts
new file mode 100644
index 000000000..eab16c1c3
--- /dev/null
+++ b/__tests__/expo-modules.test.ts
@@ -0,0 +1,207 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { CodeGraph } from '../src';
+import { expoModulesResolver } from '../src/resolution/frameworks/expo-modules';
+
+describe('Expo Modules framework extractor', () => {
+  it('extracts AsyncFunction / Function / Property literals as method nodes', () => {
+    const source = `
+import ExpoModulesCore
+
+public class HapticsModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("ExpoHaptics")
+
+    AsyncFunction("notificationAsync") { (notificationType: NotificationType) in
+      // body
+    }
+
+    AsyncFunction("impactAsync") { (style: ImpactStyle) in
+      // body
+    }
+
+    Function("synchronousThing") {
+      return 1
+    }
+
+    Property("isAvailable") {
+      return true
+    }
+  }
+}
+`;
+    const result = expoModulesResolver.extract?.('ios/HapticsModule.swift', source);
+    expect(result).toBeDefined();
+    const names = result!.nodes.map((n) => n.name);
+    expect(names).toEqual(
+      expect.arrayContaining(['notificationAsync', 'impactAsync', 'synchronousThing', 'isAvailable'])
+    );
+    expect(result!.nodes.every((n) => n.kind === 'method')).toBe(true);
+    expect(result!.nodes.every((n) => n.qualifiedName.includes('ExpoHaptics.'))).toBe(true);
+  });
+
+  it('falls back to the class name when the Module has no Name("X") literal', () => {
+    const source = `
+public class BareModule: Module {
+  public func definition() -> ModuleDefinition {
+    Function("doX") { return 1 }
+  }
+}
+`;
+    const result = expoModulesResolver.extract?.('ios/BareModule.swift', source);
+    // BareModule is used as the qualifier since there's no Name() literal.
+    expect(result!.nodes[0]?.qualifiedName).toContain('BareModule.doX');
+  });
+
+  it('returns no nodes for a Swift file that is not an Expo Module', () => {
+    const source = `
+class Helper {
+  func doX() { }
+}
+`;
+    const result = expoModulesResolver.extract?.('Helper.swift', source);
+    expect(result?.nodes).toHaveLength(0);
+  });
+
+  it('also extracts from Kotlin module files', () => {
+    const source = `
+class FooModule : Module() {
+    override fun definition() = ModuleDefinition {
+        Name("ExpoFoo")
+        AsyncFunction("doAsync") { name: String -> name.uppercase() }
+        Function("doSync") { 42 }
+    }
+}
+`;
+    const result = expoModulesResolver.extract?.('FooModule.kt', source);
+    expect(result?.nodes.length).toBe(2);
+    expect(result?.nodes.map((n) => n.name).sort()).toEqual(['doAsync', 'doSync']);
+    expect(result?.nodes.every((n) => n.language === 'kotlin')).toBe(true);
+  });
+});
+
+describe('Expo Modules end-to-end — JS caller → native AsyncFunction', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'expo-modules-fixture-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('JS callsite of a literal AsyncFunction("name") resolves to the native impl node', async () => {
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      '{"dependencies":{"expo-modules-core":"^1.0.0"}}'
+    );
+    fs.mkdirSync(path.join(dir, 'ios'));
+    fs.writeFileSync(
+      path.join(dir, 'ios', 'HapticsModule.swift'),
+      `
+import ExpoModulesCore
+public class HapticsModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("ExpoHaptics")
+    AsyncFunction("uniqueExpoHapticCall") { in /* … */ }
+  }
+}
+`
+    );
+    fs.mkdirSync(path.join(dir, 'src'));
+    fs.writeFileSync(
+      path.join(dir, 'src', 'index.ts'),
+      `
+import { requireNativeModule } from 'expo-modules-core';
+const Haptics = requireNativeModule('ExpoHaptics');
+export async function impactAsync() {
+  return await Haptics.uniqueExpoHapticCall();
+}
+`
+    );
+
+    const cg = await CodeGraph.init(dir, { silent: true });
+    await cg.indexAll();
+    const db = (cg as any).db.db;
+
+    // The native method node should exist.
+    const native = db
+      .prepare(
+        "SELECT * FROM nodes WHERE kind='method' AND name='uniqueExpoHapticCall' AND id LIKE 'expo-module:%'"
+      )
+      .all();
+    expect(native).toHaveLength(1);
+
+    // And the JS callsite should produce a call edge targeting it.
+    const callEdge = db
+      .prepare(
+        `SELECT t.name target, t.id target_id
+         FROM edges e
+         JOIN nodes s ON s.id = e.source
+         JOIN nodes t ON t.id = e.target
+         WHERE e.kind = 'calls'
+           AND s.file_path LIKE '%index.ts'
+           AND t.name = 'uniqueExpoHapticCall'`
+      )
+      .all();
+    cg.close?.();
+    expect(callEdge.length).toBeGreaterThanOrEqual(1);
+    expect(callEdge[0].target_id.startsWith('expo-module:')).toBe(true);
+  });
+
+  it('extracts GENERIC-typed Kotlin AsyncFunction<T> and pairs the iOS + Android impls', async () => {
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      '{"dependencies":{"expo-modules-core":"^1.0.0"}}'
+    );
+    fs.mkdirSync(path.join(dir, 'ios'));
+    fs.writeFileSync(
+      path.join(dir, 'ios', 'BatteryModule.swift'),
+      `import ExpoModulesCore
+public class BatteryModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("ExpoBattery")
+    AsyncFunction("getBatteryLevelAsync") { () -> Float in return 1.0 }
+  }
+}
+`
+    );
+    fs.mkdirSync(path.join(dir, 'android'));
+    fs.writeFileSync(
+      path.join(dir, 'android', 'BatteryModule.kt'),
+      `import expo.modules.kotlin.modules.Module
+class BatteryModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("ExpoBattery")
+    AsyncFunction<Float>("getBatteryLevelAsync") { 1.0f }
+  }
+}
+`
+    );
+
+    const cg = await CodeGraph.init(dir, { silent: true });
+    await cg.indexAll();
+    const db = (cg as any).db.db;
+
+    // The Android (Kotlin) GENERIC AsyncFunction<Float> is extracted — before the
+    // fix the `<Float>` defeated the regex and it was silently dropped.
+    const kt = db.prepare(
+      "SELECT * FROM nodes WHERE name='getBatteryLevelAsync' AND language='kotlin' AND id LIKE 'expo-module:%'"
+    ).all();
+    expect(kt).toHaveLength(1);
+
+    // The iOS (Swift) and Android (Kotlin) impls of the same JS method are linked
+    // to each other, so a JS call that resolves to one platform reaches the other.
+    const pair = db.prepare(
+      `SELECT count(*) c FROM edges e
+       JOIN nodes s ON s.id=e.source JOIN nodes t ON t.id=e.target
+       WHERE s.name='getBatteryLevelAsync' AND t.name='getBatteryLevelAsync'
+         AND s.language != t.language`
+    ).get();
+    cg.close?.();
+    expect(pair.c).toBeGreaterThanOrEqual(2); // swift->kotlin AND kotlin->swift
+  });
+});
diff --git a/__tests__/extraction.test.ts b/__tests__/extraction.test.ts
index 1b121478e..7f2d13f5f 100644
--- a/__tests__/extraction.test.ts
+++ b/__tests__/extraction.test.ts
@@ -9,10 +9,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { CodeGraph } from '../src';
-import { extractFromSource, scanDirectory, shouldIncludeFile } from '../src/extraction';
-import { detectLanguage, isLanguageSupported, getSupportedLanguages, initGrammars, loadAllGrammars } from '../src/extraction/grammars';
+import { extractFromSource, scanDirectory, buildDefaultIgnore } from '../src/extraction';
+import { detectLanguage, isLanguageSupported, getSupportedLanguages, initGrammars, loadAllGrammars, isSourceFile } from '../src/extraction/grammars';
 import { normalizePath } from '../src/utils';
-import { DEFAULT_CONFIG } from '../src/types';
 
 beforeAll(async () => {
   await initGrammars();
@@ -94,6 +93,14 @@ describe('Language Detection', () => {
     expect(detectLanguage('main.dart')).toBe('dart');
   });
 
+  it('should detect Objective-C files', () => {
+    expect(detectLanguage('AppDelegate.m')).toBe('objc');
+    expect(detectLanguage('ViewController.mm')).toBe('objc');
+    const objcHeader = '@interface Foo : NSObject\n@end\n';
+    expect(detectLanguage('Foo.h', objcHeader)).toBe('objc');
+    expect(detectLanguage('stdio.h', '#ifndef STDIO_H\nvoid printf();\n#endif\n')).toBe('c');
+  });
+
   it('should return unknown for unsupported extensions', () => {
     expect(detectLanguage('styles.css')).toBe('unknown');
     expect(detectLanguage('data.json')).toBe('unknown');
@@ -177,6 +184,89 @@ export class PaymentService {
     expect(chargeMethod).toBeDefined();
   });
 
+  it('captures docstrings for export- and const-wrapped declarations (#780)', () => {
+    const code = `
+// plain class control
+class Ledger {}
+
+// exported class
+export class Invoice {}
+
+// export default
+export default function settle() { return true; }
+
+// exported arrow const
+export const refund = (amount: number) => amount;
+
+// non-export arrow const
+const audit = (amount: number) => amount;
+`;
+    const byName = new Map(extractFromSource('doc.ts', code).nodes.map((n) => [n.name, n]));
+    expect(byName.get('Ledger')?.docstring).toBe('plain class control'); // control still works
+    expect(byName.get('Invoice')?.docstring).toBe('exported class');
+    expect(byName.get('settle')?.docstring).toBe('export default');
+    expect(byName.get('refund')?.docstring).toBe('exported arrow const');
+    expect(byName.get('audit')?.docstring).toBe('non-export arrow const');
+  });
+
+  it('does not mis-attribute a class comment to an uncommented member (#780)', () => {
+    const code = `
+// Comment for Box
+export class Box {
+  noComment() {}
+  // own comment
+  withComment() {}
+}
+`;
+    const byName = new Map(extractFromSource('box.ts', code).nodes.map((n) => [n.name, n]));
+    expect(byName.get('Box')?.docstring).toBe('Comment for Box');
+    expect(byName.get('noComment')?.docstring ?? null).toBeNull(); // no over-walk
+    expect(byName.get('withComment')?.docstring).toBe('own comment');
+  });
+
+  it('captures docstrings for decorated Python declarations, stripping `#` (#780)', () => {
+    const code = [
+      '# decorated function',
+      '@app.route("/x")',
+      'def py_handler():',
+      '    return 1',
+      '',
+      '',
+      '# plain function control',
+      'def py_plain():',
+      '    return 1',
+      '',
+      '',
+      '# decorated class',
+      '@dataclass',
+      'class PyModel:',
+      '    pass',
+      '',
+    ].join('\n');
+    const byName = new Map(extractFromSource('mod.py', code).nodes.map((n) => [n.name, n]));
+    expect(byName.get('py_handler')?.docstring).toBe('decorated function');
+    expect(byName.get('py_plain')?.docstring).toBe('plain function control'); // `#` stripped
+    expect(byName.get('PyModel')?.docstring).toBe('decorated class');
+  });
+
+  it('cleans comment markers across language styles (#780)', () => {
+    const doc = (file: string, code: string, name: string) =>
+      new Map(extractFromSource(file, code).nodes.map((n) => [n.name, n])).get(name)?.docstring;
+
+    // Rust doc lines (`///`, `//!`) — the trailing slash used to leak through.
+    expect(doc('m.rs', '/// rust doc line\nfn rs_fn() {}', 'rs_fn')).toBe('rust doc line');
+    // Lua line + long-bracket comments.
+    expect(doc('m.lua', '-- lua line\nfunction lua_fn() end', 'lua_fn')).toBe('lua line');
+    expect(doc('b.lua', '--[[ lua block ]]\nfunction lua_b() end', 'lua_b')).toBe('lua block');
+    // Pascal brace and paren-star comments.
+    const pasUnit = (c: string) =>
+      `unit U;\ninterface\n${c}\nprocedure P;\nimplementation\nprocedure P;\nbegin\nend;\nend.\n`;
+    expect(doc('a.pas', pasUnit('{ pascal brace }'), 'P')).toBe('pascal brace');
+    expect(doc('c.pas', pasUnit('(* pascal paren *)'), 'P')).toBe('pascal paren');
+    // C block comment still clean (no regression).
+    expect(doc('m.c', '/* c block */\nvoid c_fn(void) {}', 'c_fn')).toBe('c block');
+  });
+
   it('should extract interfaces', () => {
     const code = `
 export interface User {
@@ -198,6 +288,86 @@ export interface User {
     });
   });
 
+  it('should extract type references from interface property signatures', () => {
+    const code = `
+import type { IPage } from '../PromoterList';
+import type { IOrderField } from '../types';
+
+interface Hprops {
+  value?: Partial<IPage> & Partial<IOrderField>;
+}
+`;
+    const result = extractFromSource('HeaderFilter.ts', code);
+
+    const refs = result.unresolvedReferences.filter((r) => r.referenceKind === 'references');
+    expect(refs.some((r) => r.referenceName === 'IPage')).toBe(true);
+    expect(refs.some((r) => r.referenceName === 'IOrderField')).toBe(true);
+  });
+
+  it('should extract type references from interface method signatures', () => {
+    const code = `
+import type { IPage } from '../PromoterList';
+import type { IOrderField } from '../types';
+
+interface MethodForm {
+  fetchPage(arg: IPage): IOrderField;
+}
+`;
+    const result = extractFromSource('MethodForm.ts', code);
+
+    const refs = result.unresolvedReferences.filter((r) => r.referenceKind === 'references');
+    expect(refs.some((r) => r.referenceName === 'IPage')).toBe(true);
+    expect(refs.some((r) => r.referenceName === 'IOrderField')).toBe(true);
+  });
+
+  it('extracts type references from in-body local variable annotations', () => {
+    // A function that uses a type ONLY in its body — `const items: Foo[] = []` —
+    // still depends on Foo. The body walker used to capture calls but never type
+    // annotations, so impact / `affected` missed the dependency. Must cover
+    // function, class-method, and object-literal-method bodies — and must NOT
+    // turn the locals themselves into graph nodes (that would explode the graph).
+    const code = `
+import { Foo } from './types';
+
+export function build(): void {
+  const items: Foo[] = [];
+  void items;
+}
+
+export class K {
+  run(): void {
+    const a: Foo = { x: 1 };
+    void a;
+  }
+}
+
+export const handler = {
+  handle(): void {
+    const b: Foo = { x: 1 };
+    void b;
+  },
+};
+`;
+    const result = extractFromSource('inbody.ts', code);
+
+    const fooRefs = result.unresolvedReferences.filter(
+      (r) => r.referenceKind === 'references' && r.referenceName === 'Foo'
+    );
+    // One per body scope: build(), K.run(), handler.handle().
+    expect(fooRefs.length).toBeGreaterThanOrEqual(3);
+
+    // Each reference is attributed to its enclosing function/method node — never
+    // to a local-variable node, because locals are intentionally not extracted.
+    const byId = new Map(result.nodes.map((n) => [n.id, n]));
+    for (const ref of fooRefs) {
+      const owner = byId.get(ref.fromNodeId);
+      expect(owner).toBeDefined();
+      expect(['function', 'method']).toContain(owner!.kind);
+    }
+    // The locals (items/a/b) must not leak in as symbols.
+    expect(result.nodes.some((n) => ['items', 'a', 'b'].includes(n.name))).toBe(false);
+  });
+
   it('should track function calls', () => {
     const code = `
 function main() {
@@ -364,6 +534,59 @@ type Internal = string;
     expect(exported).toHaveLength(2);
     expect(exported.map((n) => n.name).sort()).toEqual(['DateFormat', 'UnitSystem']);
   });
+
+  // A service/contract registry written as a tuple of generic instantiations —
+  // the names are string-literal type arguments, not declarations, so static
+  // extraction otherwise never indexes them (issue #634).
+  it('extracts string-literal contract names from a generic tuple type alias (#634)', () => {
+    const code = `
+interface Service<Name extends string, Req, Resp> { name: Name; }
+export type MyServiceList = [
+  Service<'query_apply_record', { pageNo: number }, { ok: boolean }>,
+  Service<'apply_confirm', { code: string }, { ok: boolean }>
+];
+`;
+    const result = extractFromSource('services/api.ts', code);
+
+    const names = result.nodes.filter(
+      (n) => n.kind === 'method' && n.qualifiedName.startsWith('MyServiceList::')
+    );
+    expect(names.map((n) => n.name).sort()).toEqual(['apply_confirm', 'query_apply_record']);
+
+    const queryNode = names.find((n) => n.name === 'query_apply_record');
+    expect(queryNode?.qualifiedName).toBe('MyServiceList::query_apply_record');
+    // Signature carries the full contract entry so search results show context.
+    expect(queryNode?.signature).toContain("Service<'query_apply_record'");
+
+    // The string-literal name is contained by the type alias.
+    const alias = result.nodes.find((n) => n.kind === 'type_alias' && n.name === 'MyServiceList');
+    const containsEdge = result.edges.find(
+      (e) => e.kind === 'contains' && e.source === alias?.id && e.target === queryNode?.id
+    );
+    expect(containsEdge).toBeDefined();
+  });
+
+  it('does not extract string literals from utility types or nested generics (#634)', () => {
+    const code = `
+interface User { id: string; name: string; }
+interface Service<Name extends string, Req, Resp> { name: Name; }
+export type Picked = Pick<User, 'id' | 'name'>;
+export type Rec = Record<'foo' | 'bar', number>;
+// Tuple entry, but the name is a non-identifier route path; the nested Pick's
+// 'id' must also stay out (only DIRECT literal args of a tuple's generic count).
+export type Routes = [Service<'/api/users', Pick<User, 'id'>, {}>];
+// Bare string-literal tuple — not generic type arguments.
+export type Names = ['alpha', 'beta'];
+`;
+    const result = extractFromSource('noise.ts', code);
+
+    const leaked = result.nodes.filter(
+      (n) =>
+        (n.kind === 'method' || n.kind === 'property') &&
+        ['id', 'name', 'foo', 'bar', 'alpha', 'beta'].includes(n.name)
+    );
+    expect(leaked).toEqual([]);
+  });
 });
 
 describe('Exported Variable Extraction', () => {
@@ -479,6 +702,20 @@ export const authMachine = createMachine({
     expect(varNode).toBeDefined();
     expect(varNode?.isExported).toBe(true);
   });
+
+  it('should extract calls from a top-level variable initializer (issue #425)', () => {
+    const code = `
+import { getTokenMp } from './api/upload';
+
+const token = getTokenMp();
+`;
+    const result = extractFromSource('app.ts', code);
+
+    const call = result.unresolvedReferences.find(
+      (ref) => ref.referenceKind === 'calls' && ref.referenceName === 'getTokenMp'
+    );
+    expect(call).toBeDefined();
+  });
 });
 
 describe('File Node Extraction', () => {
@@ -761,6 +998,130 @@ public class Calculator {
     expect(methodNode).toBeDefined();
     expect(methodNode?.isStatic).toBe(true);
   });
+
+  it('wraps top-level declarations in a namespace from package_declaration', () => {
+    const code = `
+package com.example.foo;
+
+public class Bar {
+    public String greet() { return "hi"; }
+}
+`;
+    const result = extractFromSource('Bar.java', code);
+
+    const ns = result.nodes.find((n) => n.kind === 'namespace');
+    expect(ns?.name).toBe('com.example.foo');
+
+    const cls = result.nodes.find((n) => n.kind === 'class' && n.name === 'Bar');
+    expect(cls?.qualifiedName).toBe('com.example.foo::Bar');
+
+    const greet = result.nodes.find((n) => n.kind === 'method' && n.name === 'greet');
+    expect(greet?.qualifiedName).toBe('com.example.foo::Bar::greet');
+  });
+
+  it('does not wrap when no package is declared', () => {
+    const code = `
+public class Bar {
+    public String greet() { return "hi"; }
+}
+`;
+    const result = extractFromSource('Bar.java', code);
+    expect(result.nodes.find((n) => n.kind === 'namespace')).toBeUndefined();
+    const cls = result.nodes.find((n) => n.kind === 'class' && n.name === 'Bar');
+    expect(cls?.qualifiedName).toBe('Bar');
+  });
+
+  it('extracts anonymous-class overrides from `new T() { ... }`', () => {
+    // The pattern that breaks the trace through `strategy.foo()` in
+    // libraries like guava's Splitter: the lambda-returned anonymous
+    // class overrides abstract methods on the base, but without
+    // extracting those overrides the interface→impl synthesizer has
+    // nothing to bridge.
+    const code = `
+package com.example;
+
+abstract class Base {
+  abstract int compute(int x);
+}
+
+public class Factory {
+  public Base make() {
+    return new Base() {
+      @Override
+      int compute(int x) { return x + 1; }
+    };
+  }
+}
+`;
+    const result = extractFromSource('Factory.java', code);
+
+    const anon = result.nodes.find((n) => n.kind === 'class' && /Base\$anon@/.test(n.name));
+    expect(anon, 'anonymous Base subclass should be extracted as a class').toBeDefined();
+
+    const compute = result.nodes.find(
+      (n) => n.kind === 'method' && n.name === 'compute' && n.qualifiedName.includes('$anon@')
+    );
+    expect(compute, 'override method should be a method on the anon class').toBeDefined();
+    expect(compute!.qualifiedName).toContain('Factory::make::<Base$anon@');
+    expect(compute!.qualifiedName.endsWith('::compute')).toBe(true);
+
+    // Anon class must extend Base so Phase 5.5 (interface-impl) can bridge.
+    const extendsRef = result.unresolvedReferences.find(
+      (r) => r.referenceKind === 'extends' && r.referenceName === 'Base' && r.fromNodeId === anon!.id
+    );
+    expect(extendsRef, 'anon class should carry an `extends Base` reference').toBeDefined();
+
+    // The enclosing `make` method still emits an instantiates edge to Base —
+    // anon extraction must not swallow that signal.
+    const instantiatesRef = result.unresolvedReferences.find(
+      (r) => r.referenceKind === 'instantiates' && r.referenceName === 'Base'
+    );
+    expect(instantiatesRef, 'enclosing method should still instantiate Base').toBeDefined();
+  });
+
+  it('extracts anonymous-class overrides inside a lambda body', () => {
+    // The exact guava pattern: a lambda is passed to a constructor, and the
+    // lambda body returns `new T() { @Override ... }`. The anon class must
+    // still surface even though it sits inside a lambda_expression node.
+    const code = `
+package com.example;
+
+interface Strategy {
+  java.util.Iterator<String> iterator(String s);
+}
+
+abstract class BaseIter implements java.util.Iterator<String> {
+  abstract int separatorStart(int start);
+}
+
+public class Splitter {
+  private final Strategy strategy;
+  public Splitter(Strategy s) { this.strategy = s; }
+
+  public static Splitter on(char c) {
+    return new Splitter((seq) ->
+        new BaseIter() {
+          @Override
+          int separatorStart(int start) { return start + 1; }
+          @Override public boolean hasNext() { return false; }
+          @Override public String next() { return null; }
+        });
+  }
+}
+`;
+    const result = extractFromSource('Splitter.java', code);
+
+    const anon = result.nodes.find((n) => n.kind === 'class' && /BaseIter\$anon@/.test(n.name));
+    expect(anon, 'anon BaseIter inside the lambda body should be extracted').toBeDefined();
+
+    const sepStart = result.nodes.find(
+      (n) =>
+        n.kind === 'method' &&
+        n.name === 'separatorStart' &&
+        n.qualifiedName.includes('$anon@')
+    );
+    expect(sepStart, 'override inside the lambda-returned anon class should be a method node').toBeDefined();
+  });
 });
 
 describe('C# Extraction', () => {
@@ -788,6 +1149,86 @@ public class OrderService
     expect(classNode?.name).toBe('OrderService');
     expect(classNode?.visibility).toBe('public');
   });
+
+  it('indexes primary-constructor classes, including keyed-DI attribute params (#237)', () => {
+    // C# 12 primary constructors (`class Foo(IDep dep) { … }`) are parsed
+    // natively by the vendored tree-sitter-c-sharp 0.23.x grammar. The worst
+    // shape under the previous (older) grammar — an attribute-with-args on a
+    // ctor param (`[FromKeyedServices("primary")] …`, the ASP.NET keyed-DI
+    // pattern) — used to parse as an ERROR that swallowed the whole class, so
+    // the class and all its methods vanished. They now index in every case.
+    const code = `
+public class DataService(IMemoryCache cache)
+{
+    public void Warm() { }
+}
+
+public class InstanceService(InstanceManager m, ProfileManager p)
+{
+    public void DeployAndLaunchAsync() { }
+    public void Deploy() { }
+}
+
+public partial class UpdateService(int x) : ILifetimeService
+{
+    public void Run() { }
+}
+
+public class K1KeyedDi([FromKeyedServices("primary")] IMemoryCache cache)
+{
+    public void Warm() { }
+}
+
+public record CatalogBrand(int Id, string Name);
+`;
+    const result = extractFromSource('Services.cs', code);
+    const classNames = result.nodes.filter((n) => n.kind === 'class').map((n) => n.name);
+    expect(classNames).toContain('DataService');
+    expect(classNames).toContain('InstanceService');
+    expect(classNames).toContain('UpdateService'); // partial + base list
+    expect(classNames).toContain('K1KeyedDi'); // attribute-arg ctor param — used to vanish entirely
+    expect(classNames).toContain('CatalogBrand'); // record
+
+    const methods = result.nodes.filter((n) => n.kind === 'method').map((n) => n.name);
+    expect(methods).toContain('DeployAndLaunchAsync');
+    expect(methods).toContain('Deploy');
+    expect(methods).toContain('Run');
+  });
+
+  it('keeps a class indexable when a nested enum has #if-guarded members (#237)', () => {
+    // A `#if` directive inside an enum member list (the multi-targeting pattern
+    // in libraries like Newtonsoft.Json) makes the grammar emit an ERROR that,
+    // for a nested enum, detaches the enclosing class's member list — dropping
+    // most of the class's methods. A pre-parse pass blanks the directive lines
+    // (keeping both branches), so the class and all its methods still index.
+    const code = `
+public class Reader
+{
+    private enum ReadType
+    {
+#if HAVE_DATE_TIME_OFFSET
+        ReadAsDateTimeOffset,
+#endif
+        ReadAsDouble,
+        ReadAsString,
+    }
+
+    public void Open() { }
+    public void Close() { }
+    public int ReadInt() { return 0; }
+}
+`;
+    const result = extractFromSource('Reader.cs', code);
+    const methods = result.nodes.filter((n) => n.kind === 'method').map((n) => n.name);
+    // All three methods after the #if-bearing enum must survive.
+    expect(methods).toContain('Open');
+    expect(methods).toContain('Close');
+    expect(methods).toContain('ReadInt');
+    // Both enum branches are kept.
+    const enumMembers = result.nodes.filter((n) => n.kind === 'enum_member').map((n) => n.name);
+    expect(enumMembers).toContain('ReadAsDateTimeOffset');
+    expect(enumMembers).toContain('ReadAsDouble');
+  });
 });
 
 describe('PHP Extraction', () => {
@@ -1120,6 +1561,54 @@ interface WebSocket {
     expect(methodNames).toContain('send');
     expect(methodNames).toContain('cancel');
   });
+
+  it('wraps top-level declarations in a namespace from package_header', () => {
+    const code = `
+package com.example.foo
+
+class Bar {
+  fun greet(): String = "hi"
+}
+
+fun util(): Int = 42
+`;
+    const result = extractFromSource('Bar.kt', code);
+
+    const ns = result.nodes.find((n) => n.kind === 'namespace');
+    expect(ns?.name).toBe('com.example.foo');
+
+    const cls = result.nodes.find((n) => n.kind === 'class' && n.name === 'Bar');
+    expect(cls?.qualifiedName).toBe('com.example.foo::Bar');
+
+    const greet = result.nodes.find((n) => n.kind === 'method' && n.name === 'greet');
+    expect(greet?.qualifiedName).toBe('com.example.foo::Bar::greet');
+
+    const util = result.nodes.find((n) => n.kind === 'function' && n.name === 'util');
+    expect(util?.qualifiedName).toBe('com.example.foo::util');
+  });
+
+  it('handles a single-segment package', () => {
+    const code = `
+package foo
+
+class Bar
+`;
+    const result = extractFromSource('Bar.kt', code);
+    const cls = result.nodes.find((n) => n.kind === 'class' && n.name === 'Bar');
+    expect(cls?.qualifiedName).toBe('foo::Bar');
+  });
+
+  it('does not wrap when no package is declared', () => {
+    const code = `
+class Bar {
+  fun greet() = "hi"
+}
+`;
+    const result = extractFromSource('Bar.kt', code);
+    expect(result.nodes.find((n) => n.kind === 'namespace')).toBeUndefined();
+    const cls = result.nodes.find((n) => n.kind === 'class' && n.name === 'Bar');
+    expect(cls?.qualifiedName).toBe('Bar');
+  });
 });
 
 describe('Dart Extraction', () => {
@@ -1152,6 +1641,11 @@ class UserService {
     const privateMethod = methodNodes.find((m) => m.name === '_privateMethod');
     expect(privateMethod).toBeDefined();
     expect(privateMethod?.visibility).toBe('private');
+
+    // Dart models a method body as a SIBLING of the signature, so the method
+    // node must be extended to span its body (not just the signature line) —
+    // required for body-level analysis (callees, the callback synthesizer).
+    expect(findById!.endLine).toBeGreaterThan(findById!.startLine);
   });
 
   it('should extract top-level function declarations', () => {
@@ -1836,6 +2330,43 @@ use Closure;
       expect(names).toContain('Illuminate\\Support\\Str');
       expect(names).toContain('Closure');
     });
+
+    it('should extract include/require (+_once) static paths as imports (#660)', () => {
+      const code = `<?php
+require_once("lib.php");
+include 'other.php';
+require 'r.php';
+include_once("io.php");
+`;
+      const result = extractFromSource('page.php', code);
+      const names = result.nodes.filter((n) => n.kind === 'import').map((n) => n.name);
+      expect(names).toContain('lib.php');
+      expect(names).toContain('other.php');
+      expect(names).toContain('r.php');
+      expect(names).toContain('io.php');
+    });
+
+    it('should skip dynamic include/require with no static path (#660)', () => {
+      const code = `<?php
+require_once(__DIR__ . '/dyn.php');
+include $file;
+include "tpl/{$name}.php";
+`;
+      const result = extractFromSource('page.php', code);
+      const imports = result.nodes.filter((n) => n.kind === 'import');
+      expect(imports).toHaveLength(0);
+    });
+
+    it('should extract include alongside namespace use without interference (#660)', () => {
+      const code = `<?php
+use App\\Service\\Mailer;
+require_once("bootstrap.php");
+`;
+      const result = extractFromSource('page.php', code);
+      const names = result.nodes.filter((n) => n.kind === 'import').map((n) => n.name);
+      expect(names).toContain('App\\Service\\Mailer');
+      expect(names).toContain('bootstrap.php');
+    });
   });
 
   describe('Ruby imports', () => {
@@ -1958,6 +2489,65 @@ end
     });
   });
 
+  describe('PHP return type capture (#608)', () => {
+    it('captures self/static factory returns as the `self` marker; primitives as undefined', () => {
+      const code = `<?php
+class ApiClient {
+    public static function for(string $c): self { return new self; }
+    public static function make(): static { return new static; }
+    public function send(array $p): array { return []; }
+}`;
+      const result = extractFromSource('ApiClient.php', code);
+      expect(result.nodes.find((n) => n.name === 'for' && n.kind === 'method')?.returnType).toBe('self');
+      expect(result.nodes.find((n) => n.name === 'make' && n.kind === 'method')?.returnType).toBe('self');
+      // `array` is not a class to chain on → no return type recorded.
+      expect(result.nodes.find((n) => n.name === 'send' && n.kind === 'method')?.returnType).toBeUndefined();
+    });
+
+    it('captures a concrete return type as its short class name', () => {
+      const code = `<?php
+namespace App;
+class WidgetFactory { public static function make(): Widget { return new Widget(); } }`;
+      const result = extractFromSource('WidgetFactory.php', code);
+      expect(result.nodes.find((n) => n.name === 'make' && n.kind === 'method')?.returnType).toBe('Widget');
+    });
+  });
+
+  describe('C/C++ return type capture (#645)', () => {
+    it('captures the normalized return type of a C++ method/function', () => {
+      const code = `
+struct Widget { void draw(); };
+class Factory { public: static Widget create(); };
+Widget Factory::create() { return Widget(); }
+void doNothing() {}
+`;
+      const result = extractFromSource('f.cpp', code);
+
+      const create = result.nodes.find(
+        (n) => n.name === 'create' && (n.kind === 'method' || n.kind === 'function')
+      );
+      expect(create?.returnType).toBe('Widget');
+
+      // A `void` return records no type, so resolution never tries to resolve a
+      // method on it.
+      const doNothing = result.nodes.find((n) => n.name === 'doNothing');
+      expect(doNothing).toBeDefined();
+      expect(doNothing?.returnType).toBeUndefined();
+    });
+
+    it('unwraps a smart-pointer return type to its pointee', () => {
+      const code = `
+#include <memory>
+struct Widget {};
+std::unique_ptr<Widget> makeWidget() { return nullptr; }
+`;
+      const result = extractFromSource('f.cpp', code);
+
+      const make = result.nodes.find((n) => n.name === 'makeWidget');
+      expect(make?.returnType).toBe('Widget');
+    });
+  });
+
   describe('C/C++ imports', () => {
     it('should extract system include', () => {
       const code = `#include <iostream>`;
@@ -2012,6 +2602,27 @@ end
       expect(names).toContain('vector');
       expect(names).toContain('config.h');
     });
+
+    it('should create unresolved references for local includes', () => {
+      const code = `#include "myheader.h"`;
+      const result = extractFromSource('main.cpp', code);
+
+      const importRef = result.unresolvedReferences.find(
+        (r) => r.referenceKind === 'imports' && r.referenceName === 'myheader.h'
+      );
+      expect(importRef).toBeDefined();
+      expect(importRef?.line).toBe(1);
+    });
+
+    it('should create unresolved references for system includes', () => {
+      const code = `#include <iostream>`;
+      const result = extractFromSource('main.cpp', code);
+
+      const importRef = result.unresolvedReferences.find(
+        (r) => r.referenceKind === 'imports' && r.referenceName === 'iostream'
+      );
+      expect(importRef).toBeDefined();
+    });
   });
 
   describe('Dart imports', () => {
@@ -2842,65 +3453,1542 @@ end`;
   });
 });
 
-describe('Full Indexing', () => {
+describe('Kotlin Multiplatform expect/actual', () => {
   let tempDir: string;
+  let cg: CodeGraph;
 
   beforeEach(() => {
     tempDir = createTempDir();
   });
 
   afterEach(() => {
-    cleanupTempDir(tempDir);
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
   });
 
-  it('should index a TypeScript file', async () => {
-    // Create test file
-    const srcDir = path.join(tempDir, 'src');
-    fs.mkdirSync(srcDir);
+  it('links expect declarations to platform actual implementations and surfaces them in impact', async () => {
+    const common = path.join(tempDir, 'src', 'commonMain');
+    const jvm = path.join(tempDir, 'src', 'jvmMain');
+    fs.mkdirSync(common, { recursive: true });
+    fs.mkdirSync(jvm, { recursive: true });
+
+    // common source set: expect declarations + a caller that uses them
     fs.writeFileSync(
-      path.join(srcDir, 'utils.ts'),
-      `
-export function add(a: number, b: number): number {
-  return a + b;
-}
+      path.join(common, 'SystemProps.kt'),
+      `package demo.internal
 
-export function multiply(a: number, b: number): number {
-  return a * b;
+expect fun systemProp(name: String): String?
+
+expect class Platform {
+    fun describe(): String
 }
 `
     );
+    fs.writeFileSync(
+      path.join(common, 'Caller.kt'),
+      `package demo
 
-    // Initialize and index
-    const cg = CodeGraph.initSync(tempDir);
-    const result = await cg.indexAll();
+import demo.internal.systemProp
+import demo.internal.Platform
 
-    expect(result.success).toBe(true);
-    expect(result.filesIndexed).toBe(1);
-    expect(result.nodesCreated).toBeGreaterThanOrEqual(2);
+fun useIt(): String {
+    val v = systemProp("os.name")
+    return Platform().describe() + v
+}
+`
+    );
+    // jvm source set: actual implementations
+    fs.writeFileSync(
+      path.join(jvm, 'SystemProps.kt'),
+      `package demo.internal
 
-    // Check nodes were stored
-    const nodes = cg.getNodesInFile('src/utils.ts');
-    expect(nodes.length).toBeGreaterThanOrEqual(2);
+actual fun systemProp(name: String): String? = System.getProperty(name)
 
-    const addFunc = nodes.find((n) => n.name === 'add');
-    expect(addFunc).toBeDefined();
-    expect(addFunc?.kind).toBe('function');
+actual class Platform {
+    actual fun describe(): String = "JVM"
+}
+`
+    );
 
-    cg.close();
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    // The expect/actual markers are captured onto the node's decorators.
+    const fns = cg.getNodesByKind('function');
+    const actualFn = fns.find(
+      (n) => n.name === 'systemProp' && n.decorators?.includes('actual')
+    );
+    const expectFn = fns.find(
+      (n) => n.name === 'systemProp' && n.decorators?.includes('expect')
+    );
+    expect(actualFn).toBeDefined();
+    expect(expectFn).toBeDefined();
+    expect(actualFn!.filePath).not.toBe(expectFn!.filePath);
+
+    // Editing the JVM actual must surface the common expect AND its caller —
+    // before the expect/actual bridge the actual had zero dependents.
+    const impact = cg.getImpactRadius(actualFn!.id, 3);
+    const impacted = [...impact.nodes.values()].map((n) => n.name);
+    expect(impacted).toContain('systemProp'); // the common expect
+    expect(impacted).toContain('useIt'); // the caller, reached transitively
+
+    // The bridging edge is a heuristic `calls` edge tagged by the synthesizer.
+    const bridge = impact.edges.find(
+      (e) =>
+        e.target === actualFn!.id &&
+        e.provenance === 'heuristic' &&
+        (e.metadata as { synthesizedBy?: string } | undefined)?.synthesizedBy ===
+          'kotlin-expect-actual'
+    );
+    expect(bridge).toBeDefined();
+    expect(bridge!.source).toBe(expectFn!.id);
   });
 
-  it('should index multiple files', async () => {
-    // Create test files
-    const srcDir = path.join(tempDir, 'src');
-    fs.mkdirSync(srcDir);
+  it('links an expect class to an actual typealias (different node kinds)', async () => {
+    const common = path.join(tempDir, 'src', 'commonMain');
+    const jvm = path.join(tempDir, 'src', 'jvmMain');
+    fs.mkdirSync(common, { recursive: true });
+    fs.mkdirSync(jvm, { recursive: true });
 
     fs.writeFileSync(
-      path.join(srcDir, 'math.ts'),
-      `export function add(a: number, b: number) { return a + b; }`
-    );
+      path.join(common, 'Lock.kt'),
+      `package demo
 
+expect class Lock {
+    fun acquire()
+}
+`
+    );
     fs.writeFileSync(
-      path.join(srcDir, 'string.ts'),
+      path.join(jvm, 'Lock.kt'),
+      `package demo
+
+actual typealias Lock = java.util.concurrent.locks.ReentrantLock
+`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const aliasNode = cg
+      .getNodesByKind('type_alias')
+      .find((n) => n.name === 'Lock' && n.decorators?.includes('actual'));
+    expect(aliasNode).toBeDefined();
+
+    // The actual typealias is now a cross-file dependency target (linked from
+    // the expect class), so it participates in impact rather than being orphaned.
+    const impact = cg.getImpactRadius(aliasNode!.id, 3);
+    const bridge = impact.edges.find(
+      (e) =>
+        e.target === aliasNode!.id &&
+        (e.metadata as { synthesizedBy?: string } | undefined)?.synthesizedBy ===
+          'kotlin-expect-actual'
+    );
+    expect(bridge).toBeDefined();
+  });
+});
+
+describe('Scala cross-file dependencies', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('links parameterized supertypes, type annotations, and implicit params across files', async () => {
+    const src = path.join(tempDir, 'src', 'main', 'scala', 'demo');
+    fs.mkdirSync(src, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(src, 'Semigroup.scala'),
+      `package demo
+
+trait Semigroup[A] {
+  def combine(x: A, y: A): A
+}
+`
+    );
+    fs.writeFileSync(
+      path.join(src, 'Monoid.scala'),
+      `package demo
+
+trait Monoid[A] extends Semigroup[A] {
+  def empty: A
+}
+`
+    );
+    fs.writeFileSync(
+      path.join(src, 'Instances.scala'),
+      `package demo
+
+object Instances {
+  implicit val intMonoid: Monoid[Int] = new Monoid[Int] {
+    def empty: Int = 0
+    def combine(x: Int, y: Int): Int = x + y
+  }
+}
+`
+    );
+    fs.writeFileSync(
+      path.join(src, 'Folding.scala'),
+      `package demo
+
+object Folding {
+  def fold[A](xs: List[A])(implicit M: Monoid[A]): A =
+    xs.foldLeft(M.empty)(M.combine)
+}
+`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const monoid = cg.getNodesByKind('trait').find((n) => n.name === 'Monoid');
+    const semigroup = cg.getNodesByKind('trait').find((n) => n.name === 'Semigroup');
+    expect(monoid).toBeDefined();
+    expect(semigroup).toBeDefined();
+    expect(monoid!.filePath).not.toBe(semigroup!.filePath);
+
+    // Parameterized supertype `extends Semigroup[A]` must create an extends edge —
+    // the whole point of the fix (the `[A]` used to defeat name matching).
+    const semaImpact = cg.getImpactRadius(semigroup!.id, 3);
+    expect([...semaImpact.nodes.values()].map((n) => n.name)).toContain('Monoid');
+
+    // Editing Monoid surfaces the cross-file users: the instance val typed
+    // `Monoid[Int]` and the method taking it as an implicit (curried) param.
+    const impacted = [...cg.getImpactRadius(monoid!.id, 3).nodes.values()].map((n) => n.name);
+    expect(impacted).toContain('intMonoid'); // field type annotation
+    expect(impacted).toContain('fold'); // trailing implicit parameter list
+  });
+});
+
+describe('PHP namespace + import resolution', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('resolves `use` imports to the namespace-qualified definition and type-hints across files', async () => {
+    const src = path.join(tempDir, 'src');
+    // Two interfaces with the SAME simple name in different namespaces — the
+    // exact ambiguity (Laravel has 7+ `Factory`) that bare-name matching can't
+    // resolve. The namespace qualifies them; the `use` import disambiguates.
+    fs.mkdirSync(path.join(src, 'Cache'), { recursive: true });
+    fs.mkdirSync(path.join(src, 'Mail'), { recursive: true });
+    fs.mkdirSync(path.join(src, 'App'), { recursive: true });
+    fs.writeFileSync(
+      path.join(src, 'Cache', 'Factory.php'),
+      `<?php
+namespace Contracts\\Cache;
+
+interface Factory {
+    public function store(): object;
+}
+`
+    );
+    fs.writeFileSync(
+      path.join(src, 'Mail', 'Factory.php'),
+      `<?php
+namespace Contracts\\Mail;
+
+interface Factory {
+    public function mailer(): object;
+}
+`
+    );
+    fs.writeFileSync(
+      path.join(src, 'App', 'Service.php'),
+      `<?php
+namespace App;
+
+use Contracts\\Cache\\Factory;
+
+class Service {
+    public function make(): Factory {
+        return resolve(Factory::class);
+    }
+}
+`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    // The PHP namespace is captured into the qualified name, so the two
+    // same-named interfaces are distinguishable.
+    const cacheFactory = cg
+      .getNodesByKind('interface')
+      .find((n) => n.qualifiedName === 'Contracts\\Cache::Factory');
+    const mailFactory = cg
+      .getNodesByKind('interface')
+      .find((n) => n.qualifiedName === 'Contracts\\Mail::Factory');
+    expect(cacheFactory).toBeDefined();
+    expect(mailFactory).toBeDefined();
+
+    // Service `use`s Contracts\Cache\Factory, so editing THAT interface reaches
+    // Service.php — and editing the same-named Contracts\Mail\Factory must NOT
+    // (the import resolved to the right namespace, not an arbitrary `Factory`).
+    const serviceFile = 'src/App/Service.php';
+    const cacheReaches = [...cg.getImpactRadius(cacheFactory!.id, 3).nodes.values()].some(
+      (n) => (n.filePath ?? '').endsWith(serviceFile)
+    );
+    const mailReaches = [...cg.getImpactRadius(mailFactory!.id, 3).nodes.values()].some(
+      (n) => (n.filePath ?? '').endsWith(serviceFile)
+    );
+    expect(cacheReaches).toBe(true);
+    expect(mailReaches).toBe(false);
+  });
+});
+
+describe('Ruby mixins (include/extend/prepend)', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('links include/extend/prepend to the mixed-in module across files', async () => {
+    const lib = path.join(tempDir, 'lib');
+    fs.mkdirSync(lib, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(lib, 'concerns.rb'),
+      `module Trackable
+  def track; end
+end
+
+module Cacheable
+  def cache; end
+end
+
+module Loggable
+  def log; end
+end
+`
+    );
+    fs.writeFileSync(
+      path.join(lib, 'model.rb'),
+      `class Model
+  include Trackable
+  prepend Cacheable
+  extend Loggable
+end
+`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const model = cg.getNodesByKind('class').find((n) => n.name === 'Model');
+    expect(model).toBeDefined();
+
+    // All three mixin forms create an `implements` edge Model → module, so
+    // editing a concern surfaces every class that mixes it in (across files).
+    for (const moduleName of ['Trackable', 'Cacheable', 'Loggable']) {
+      const mod = cg.getNodesByKind('module').find((n) => n.name === moduleName);
+      expect(mod, moduleName).toBeDefined();
+      const impacted = [...cg.getImpactRadius(mod!.id, 3).nodes.values()].map((n) => n.name);
+      expect(impacted, `${moduleName} should be depended on by Model`).toContain('Model');
+    }
+  });
+
+  it('resolves require / require_relative to the required file', async () => {
+    const lib = path.join(tempDir, 'lib');
+    fs.mkdirSync(path.join(lib, 'app'), { recursive: true });
+
+    // A leaf file whose class is referenced only dynamically — so without
+    // require resolution it would look like nothing depends on it.
+    fs.writeFileSync(
+      path.join(lib, 'app', 'fetcher.rb'),
+      `module App
+  class Fetcher
+    def fetch; end
+  end
+end
+`
+    );
+    // Pulled in by a load-path `require` …
+    fs.writeFileSync(
+      path.join(lib, 'app', 'worker.rb'),
+      `require "app/fetcher"
+
+module App
+  class Worker; end
+end
+`
+    );
+    // … and a sibling pulled in by `require_relative`.
+    fs.writeFileSync(
+      path.join(lib, 'app', 'boot.rb'),
+      `require_relative "fetcher"
+`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    // The require edges target fetcher.rb's FILE node. Editing it should reach
+    // BOTH the load-path requirer (worker.rb) and the require_relative one
+    // (boot.rb) — without require resolution its file would have no dependents.
+    const fetcher = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('app/fetcher.rb'));
+    expect(fetcher, 'fetcher.rb indexed').toBeDefined();
+    const reached = [...cg.getImpactRadius(fetcher!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(reached.some((p) => p.endsWith('app/worker.rb'))).toBe(true);
+    expect(reached.some((p) => p.endsWith('app/boot.rb'))).toBe(true);
+  });
+});
+
+describe('C++ free-function name extraction', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('names a free function correctly when it has qualified-type params or a trailing return type', async () => {
+    const src = path.join(tempDir, 'src');
+    fs.mkdirSync(src, { recursive: true });
+
+    // TableFileName has a `const std::string&` parameter; BuildName uses an
+    // `auto … -> std::string` trailing return type. Both used to be named
+    // `string` (picked up from the parameter / return type), so callers never
+    // resolved and the defining file looked like nothing depended on it.
+    fs.writeFileSync(
+      path.join(src, 'names.cc'),
+      `#include <string>
+
+std::string TableFileName(const std::string& dbname, int number) {
+  return dbname;
+}
+
+auto BuildName(const std::string& a) -> std::string {
+  return a;
+}
+`
+    );
+    fs.writeFileSync(
+      path.join(src, 'user.cc'),
+      `#include <string>
+
+std::string use() {
+  return TableFileName("db", 1) + BuildName("x");
+}
+`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    // The functions are extracted under their real names, not `string`.
+    const fns = cg.getNodesByKind('function');
+    const tableFn = fns.find((n) => n.name === 'TableFileName');
+    const buildFn = fns.find((n) => n.name === 'BuildName');
+    expect(tableFn, 'TableFileName extracted (not "string")').toBeDefined();
+    expect(buildFn, 'BuildName extracted (not "string")').toBeDefined();
+
+    // And the cross-file calls resolve to them, so editing names.cc surfaces user.cc.
+    for (const fn of [tableFn!, buildFn!]) {
+      const reached = [...cg.getImpactRadius(fn.id, 3).nodes.values()].map((n) => n.filePath ?? '');
+      expect(reached.some((p) => p.endsWith('user.cc')), `${fn.name} should be called from user.cc`).toBe(true);
+    }
+  });
+});
+
+describe('Dart mixins and type references', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('links `with` mixins and method parameter/return types across files', async () => {
+    const lib = path.join(tempDir, 'lib');
+    fs.mkdirSync(lib, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(lib, 'models.dart'),
+      `class User {
+  final String name;
+  User(this.name);
+}
+
+mixin Loggable {
+  void log() {}
+}
+
+abstract class Repository {
+  User find(int id);
+}
+`
+    );
+    fs.writeFileSync(
+      path.join(lib, 'service.dart'),
+      `import 'models.dart';
+
+class UserService extends Repository with Loggable {
+  @override
+  User find(int id) => User('x');
+
+  List<User> all() => [];
+}
+`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const inModels = (name: string) =>
+      cg.getNodesByKind('class').concat(cg.getNodesByKind('module'))
+        .find((n) => n.name === name && n.filePath.endsWith('models.dart'));
+
+    // The `with Loggable` mixin records a dependency — editing the mixin surfaces
+    // the class that mixes it in (across files). Loggable is a `mixin`, indexed
+    // as a class-like node.
+    const loggable = cg.getNodesByKind('class').find((n) => n.name === 'Loggable')
+      ?? cg.getNodesByKind('module').find((n) => n.name === 'Loggable');
+    expect(loggable, 'Loggable mixin indexed').toBeDefined();
+    const mixinUsers = [...cg.getImpactRadius(loggable!.id, 3).nodes.values()].map((n) => n.name);
+    expect(mixinUsers).toContain('UserService');
+
+    // `User` is used only as a method parameter/return type in service.dart —
+    // editing it must still surface service.dart via the type references.
+    const user = inModels('User') ?? cg.getNodesByKind('class').find((n) => n.name === 'User');
+    expect(user, 'User indexed').toBeDefined();
+    const userDeps = [...cg.getImpactRadius(user!.id, 3).nodes.values()].map((n) => n.filePath ?? '');
+    expect(userDeps.some((p) => p.endsWith('service.dart'))).toBe(true);
+  });
+});
+
+describe('Static-member / value-read references', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('links a type referenced only via a static field / enum value (and ignores lowercase receivers)', async () => {
+    fs.writeFileSync(
+      path.join(tempDir, 'JsonScope.java'),
+      `class JsonScope {
+  static final int EMPTY_DOCUMENT = 1;
+}
+`
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'Reader.java'),
+      `class Reader {
+  private int helper;
+  int peek() {
+    return JsonScope.EMPTY_DOCUMENT;
+  }
+  int noop() {
+    return this.helper;
+  }
+}
+`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    // JsonScope is used ONLY as `JsonScope.EMPTY_DOCUMENT` (a static-field value
+    // read — never constructed or called), so before the static-member pass it
+    // had no dependents. Editing it now surfaces Reader.java.
+    const scope = cg.getNodesByKind('class').find((n) => n.name === 'JsonScope');
+    expect(scope, 'JsonScope indexed').toBeDefined();
+    const reached = [...cg.getImpactRadius(scope!.id, 3).nodes.values()].map((n) => n.filePath ?? '');
+    expect(reached.some((p) => p.endsWith('Reader.java'))).toBe(true);
+
+    // A lowercase receiver (`this.helper`) must NOT be emitted as a type ref —
+    // only Capitalized receivers (types) are. No node named `this`/`helper`
+    // should appear as a reference target from peek/noop beyond JsonScope.
+    const refTargets = cg
+      .getNodesByKind('class')
+      .filter((n) => n.name === 'this' || n.name === 'helper');
+    expect(refTargets.length).toBe(0);
+  });
+
+  it('does not link a static-member read across language families (coincidental name)', async () => {
+    // A native (Kotlin) `Build.VERSION` reads the Android system class — it must
+    // NOT link to a coincidentally same-named TS class (the cross-language false
+    // positive that name-matching produces; `references` edges are language-local).
+    fs.writeFileSync(
+      path.join(tempDir, 'Build.ts'),
+      `export class Build {\n  static version = 1;\n}\n`
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'Device.kt'),
+      `package app\nclass Device {\n  fun sdk(): Int = Build.VERSION\n}\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const tsBuild = cg.getNodesByKind('class').find((n) => n.name === 'Build' && n.filePath.endsWith('Build.ts'));
+    expect(tsBuild).toBeDefined();
+    // The Kotlin file is `app/Device.kt`; the TS Build must have NO dependent there.
+    const deps = [...cg.getImpactRadius(tsBuild!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(deps.some((p) => p.endsWith('Device.kt'))).toBe(false);
+  });
+});
+
+describe('Cross-language type/import gate (RN name collisions)', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('a TS PascalCase type ref lands on the TS type, never a same-named native class', async () => {
+    // react-native-async-storage's example app has a TS `type TestRunner` AND a
+    // Kotlin `class TestRunner`. The React PascalCase resolver name-matched the
+    // Kotlin `class` (its COMPONENT_KINDS includes `class`) with no language
+    // check at confidence 0.8, outranking the (cross-language-penalized 0.5)
+    // TS name-match — so a TS ref to `TestRunner` crossed web→jvm. The ref here
+    // is intentionally NOT imported: a clean relative import would mask the bug
+    // by resolving via the import map before the framework strategy can win.
+    fs.writeFileSync(
+      path.join(tempDir, 'package.json'),
+      JSON.stringify({ dependencies: { 'react-native': '*' } })
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'useTests.ts'),
+      `export type TestRunner = { run: () => void };\n`
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'basic.tsx'),
+      `export function useBasicTest(r: TestRunner): TestRunner {\n  return r;\n}\n`
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'TestUtils.kt'),
+      `package app\nclass TestRunner {\n  fun run() {}\n}\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const ktRunner = cg
+      .getNodesByKind('class')
+      .find((n) => n.name === 'TestRunner' && n.filePath.endsWith('TestUtils.kt'));
+    expect(ktRunner, 'Kotlin TestRunner class').toBeDefined();
+    const ktDeps = [...cg.getImpactRadius(ktRunner!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(ktDeps.some((p) => p.endsWith('basic.tsx')), 'Kotlin class has NO TS dependent').toBe(false);
+
+    const tsRunner = cg.getNodesByKind('type_alias').find((n) => n.name === 'TestRunner');
+    expect(tsRunner, 'TS TestRunner type_alias').toBeDefined();
+    const tsDeps = [...cg.getImpactRadius(tsRunner!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(tsDeps.some((p) => p.endsWith('basic.tsx')), 'TS type captured the ref (re-pointed)').toBe(true);
+  });
+
+  it('gates a cross-family import name collision but keeps same-family imports', async () => {
+    // A TS `import { Widget }` that only matches a Swift `class Widget` must not
+    // create a web→apple dependency — but a sibling TS module imported by
+    // another TS file (same family) must still resolve (no over-gating).
+    fs.writeFileSync(path.join(tempDir, 'Widget.swift'), `class Widget {\n  func render() {}\n}\n`);
+    fs.writeFileSync(
+      path.join(tempDir, 'widget.ts'),
+      `import { Widget } from './native';\nexport function mount(w: Widget) {}\n`
+    );
+    fs.writeFileSync(path.join(tempDir, 'util.ts'), `export class Helper {}\n`);
+    fs.writeFileSync(
+      path.join(tempDir, 'app.ts'),
+      `import { Helper } from './util';\nexport const h = new Helper();\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const swiftWidget = cg
+      .getNodesByKind('class')
+      .find((n) => n.name === 'Widget' && n.filePath.endsWith('.swift'));
+    expect(swiftWidget, 'Swift Widget class').toBeDefined();
+    const wDeps = [...cg.getImpactRadius(swiftWidget!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(wDeps.some((p) => p.endsWith('widget.ts')), 'Swift class has NO TS dependent').toBe(false);
+
+    // Same-family control — the TS Helper must still see its TS dependent.
+    const helper = cg.getNodesByKind('class').find((n) => n.name === 'Helper');
+    expect(helper, 'TS Helper class').toBeDefined();
+    const hDeps = [...cg.getImpactRadius(helper!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(hDeps.some((p) => p.endsWith('app.ts')), 'same-family TS import preserved').toBe(true);
+  });
+});
+
+describe('Python absolute module import resolution', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('links a bare `import pkg.module` of an internal module to its file', async () => {
+    // `import conduit.apps.signals` (a Django-style side-effect import, and any
+    // dotted absolute module import) had no edge to the module file — only
+    // `from x import y` was linked — so a module imported by its dotted path
+    // looked like nothing depended on it.
+    fs.mkdirSync(path.join(tempDir, 'conduit/apps'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'conduit/__init__.py'), '');
+    fs.writeFileSync(path.join(tempDir, 'conduit/apps/__init__.py'), '');
+    fs.writeFileSync(path.join(tempDir, 'conduit/apps/signals.py'), `def handler():\n    pass\n`);
+    fs.writeFileSync(
+      path.join(tempDir, 'conduit/apps/app.py'),
+      `import conduit.apps.signals\nimport os\n\nVALUE = 1\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const signals = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('conduit/apps/signals.py'));
+    expect(signals, 'signals.py indexed').toBeDefined();
+    const deps = [...cg.getImpactRadius(signals!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(deps.some((p) => p.endsWith('app.py')), 'importer depends on the module').toBe(true);
+    // `import os` (stdlib) must NOT fabricate an edge — no os.py file in the repo.
+    const osNode = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('/os.py'));
+    expect(osNode, 'no stdlib os.py node').toBeUndefined();
+  });
+
+  it('Django include() links the root URLconf to the included app urls module', async () => {
+    // `url(r'^api/', include('app.urls'))` should record a dependency from the
+    // root urlconf onto the included app's `urls.py` — so editing an app's routes
+    // surfaces the project urlconf that mounts them.
+    fs.mkdirSync(path.join(tempDir, 'app'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'requirements.txt'), `django==4.0\n`);
+    fs.writeFileSync(path.join(tempDir, 'app/__init__.py'), '');
+    fs.writeFileSync(path.join(tempDir, 'app/views.py'), `def home(request):\n    return None\n`);
+    fs.writeFileSync(
+      path.join(tempDir, 'app/urls.py'),
+      `from django.conf.urls import url\nfrom . import views\nurlpatterns = [url(r'^$', views.home)]\n`
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'urls.py'),
+      `from django.conf.urls import include, url\nurlpatterns = [url(r'^app/', include('app.urls'))]\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const appUrls = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('app/urls.py'));
+    expect(appUrls, 'app/urls.py indexed').toBeDefined();
+    const deps = [...cg.getImpactRadius(appUrls!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(deps.some((p) => p.endsWith('urls.py') && !p.endsWith('app/urls.py')), 'root urlconf depends on the included app urls').toBe(true);
+  });
+
+  it('resolves `from pkg import submodule` to the submodule under that package, not a same-named one', async () => {
+    // FastAPI router-aggregator pattern: `from app.api.routes import authentication`
+    // with same-named modules in sibling packages must resolve via the import's
+    // SOURCE (the package), not a coincidental same-basename file elsewhere.
+    fs.mkdirSync(path.join(tempDir, 'app/api/routes'), { recursive: true });
+    fs.mkdirSync(path.join(tempDir, 'app/api/dependencies'), { recursive: true });
+    for (const p of ['app/__init__.py', 'app/api/__init__.py', 'app/api/routes/__init__.py', 'app/api/dependencies/__init__.py']) {
+      fs.writeFileSync(path.join(tempDir, p), '');
+    }
+    fs.writeFileSync(path.join(tempDir, 'app/api/routes/authentication.py'), `def login():\n    pass\n`);
+    fs.writeFileSync(path.join(tempDir, 'app/api/dependencies/authentication.py'), `def get_user():\n    pass\n`);
+    fs.writeFileSync(
+      path.join(tempDir, 'app/api/routes/api.py'),
+      `from app.api.routes import authentication\n\nROUTER = authentication\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const routesAuth = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('routes/authentication.py'));
+    const depsAuth = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('dependencies/authentication.py'));
+    expect(routesAuth && depsAuth).toBeTruthy();
+    const routesDeps = [...cg.getImpactRadius(routesAuth!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    const depsDeps = [...cg.getImpactRadius(depsAuth!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(routesDeps.some((p) => p.endsWith('routes/api.py')), 'submodule under the imported package is the dependent').toBe(true);
+    expect(depsDeps.some((p) => p.endsWith('routes/api.py')), 'same-named module in a sibling package is NOT').toBe(false);
+  });
+});
+
+describe('Razor / Blazor markup extraction', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('links @model and Blazor component tags to their C# types; ignores HTML elements', async () => {
+    fs.mkdirSync(path.join(tempDir, 'Views'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tempDir, 'LoginViewModel.cs'),
+      `namespace App { public class LoginViewModel { public string Email { get; set; } } }`
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'ToastComponent.cs'),
+      `namespace App { public class ToastComponent { } }`
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'Views/Login.cshtml'),
+      `@model LoginViewModel\n<div class="form">\n  <input asp-for="Email" />\n</div>\n`
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'Index.razor'),
+      `<div>\n  <ToastComponent />\n</div>\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    // `@model LoginViewModel` → the view-model class.
+    const vm = cg.getNodesByKind('class').find((n) => n.name === 'LoginViewModel');
+    expect(vm, 'LoginViewModel class').toBeDefined();
+    const vmDeps = [...cg.getImpactRadius(vm!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(vmDeps.some((p) => p.endsWith('Login.cshtml')), '@model links the view').toBe(true);
+
+    // `<ToastComponent />` → the component class.
+    const toast = cg.getNodesByKind('class').find((n) => n.name === 'ToastComponent');
+    expect(toast, 'ToastComponent class').toBeDefined();
+    const toastDeps = [...cg.getImpactRadius(toast!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(toastDeps.some((p) => p.endsWith('Index.razor')), 'Blazor tag links the component').toBe(true);
+
+    // HTML elements (`<div>`, `<input>`) must NOT become component references.
+    const htmlNodes = cg.getNodesByKind('class').filter((n) => n.name === 'div' || n.name === 'input');
+    expect(htmlNodes.length, 'no node for HTML elements').toBe(0);
+  });
+
+  it('C# namespaces qualify type names so same-named types are distinct', async () => {
+    fs.writeFileSync(path.join(tempDir, 'entity.cs'), `namespace App.Entities { public class CatalogBrand { } }`);
+    fs.writeFileSync(path.join(tempDir, 'dto.cs'), `namespace App.Models { public class CatalogBrand { } }`);
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+
+    const brands = cg.getNodesByKind('class').filter((n) => n.name === 'CatalogBrand');
+    expect(brands.length, 'both CatalogBrand classes indexed').toBe(2);
+    const qns = brands.map((b) => b.qualifiedName).sort();
+    expect(qns[0]).not.toBe(qns[1]); // distinct qualified names (namespace-scoped)
+    expect(qns.some((q) => q.includes('Entities') && q.endsWith('CatalogBrand'))).toBe(true);
+    expect(qns.some((q) => q.includes('Models') && q.endsWith('CatalogBrand'))).toBe(true);
+  });
+
+  it('disambiguates a Razor type ref via @using (incl. folder _Imports.razor)', async () => {
+    // `CatalogBrand` exists as both a domain entity and a DTO; the component
+    // `@using`s the DTO's namespace (here via the folder _Imports.razor), so the
+    // ref must resolve to the DTO, not the same-named entity.
+    fs.mkdirSync(path.join(tempDir, 'Models'), { recursive: true });
+    fs.mkdirSync(path.join(tempDir, 'Entities'), { recursive: true });
+    fs.mkdirSync(path.join(tempDir, 'Pages'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'Models/CatalogBrand.cs'), `namespace App.Models { public class CatalogBrand { public int Id { get; set; } } }`);
+    fs.writeFileSync(path.join(tempDir, 'Entities/CatalogBrand.cs'), `namespace App.Entities { public class CatalogBrand { public int Id { get; set; } } }`);
+    fs.writeFileSync(path.join(tempDir, 'Pages/_Imports.razor'), `@using App.Models\n`);
+    fs.writeFileSync(
+      path.join(tempDir, 'Pages/List.razor'),
+      `<h1>List</h1>\n@code {\n  private CatalogBrand _b = new CatalogBrand();\n}\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const dto = cg.getNodesByKind('class').find((n) => n.qualifiedName === 'App.Models::CatalogBrand');
+    const entity = cg.getNodesByKind('class').find((n) => n.qualifiedName === 'App.Entities::CatalogBrand');
+    expect(dto && entity, 'both CatalogBrand classes').toBeTruthy();
+    const dtoDeps = [...cg.getImpactRadius(dto!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    const entityDeps = [...cg.getImpactRadius(entity!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(dtoDeps.some((p) => p.endsWith('List.razor')), 'resolves to the @using\'d DTO').toBe(true);
+    expect(entityDeps.some((p) => p.endsWith('List.razor')), 'NOT the same-named entity').toBe(false);
+  });
+
+  it('delegates Blazor @code block C# to cover types used in component logic', async () => {
+    fs.writeFileSync(
+      path.join(tempDir, 'CatalogService.cs'),
+      `namespace App { public class CatalogService { public void Load() { } } }`
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'List.razor'),
+      `<h1>Catalog</h1>\n\n@code {\n  private CatalogService _svc = new CatalogService();\n  void Refresh() { _svc.Load(); }\n}\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const svc = cg.getNodesByKind('class').find((n) => n.name === 'CatalogService');
+    expect(svc, 'CatalogService class').toBeDefined();
+    const deps = [...cg.getImpactRadius(svc!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(deps.some((p) => p.endsWith('List.razor')), '@code usage links the component to the service').toBe(true);
+  });
+});
+
+describe('Default import resolution (renamed default export)', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('links a renamed default import to the module file', async () => {
+    // Express route aggregator: `import articlesController from './controller'`
+    // where the module does `export default router`. The renamed local can't be
+    // found as a symbol, so the controller file had no dependent — the dependency
+    // is on the module file regardless of the default export's name.
+    fs.mkdirSync(path.join(tempDir, 'app'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'app/controller.ts'), `const router = { get() {} };\nexport default router;\n`);
+    fs.writeFileSync(path.join(tempDir, 'app/routes.ts'), `import myController from './controller';\nexport const api = myController;\n`);
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const controller = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('app/controller.ts'));
+    expect(controller, 'controller.ts indexed').toBeDefined();
+    const deps = [...cg.getImpactRadius(controller!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(deps.some((p) => p.endsWith('routes.ts')), 'importer depends on the default-exporting module').toBe(true);
+  });
+});
+
+describe('Chained method-call resolution (C# extension methods)', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('resolves a chained extension-method call (a.b.Method()) to its definition', async () => {
+    // ASP.NET DI registration: `builder.Services.AddCoreServices(...)` calls a
+    // static extension method elsewhere. A multi-dot receiver chain matched no
+    // method-call pattern before, so the extension method had no caller.
+    fs.mkdirSync(path.join(tempDir, 'cfg'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tempDir, 'cfg/Ext.cs'),
+      `namespace App {\n  public static class Ext {\n    public static object AddCoreServices(this object services, int x) { return services; }\n  }\n}\n`
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'Program.cs'),
+      `namespace App {\n  public class Program {\n    public void Run(object builder) {\n      builder.Services.AddCoreServices(1);\n    }\n  }\n}\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const ext = cg
+      .getNodesByKind('method')
+      .find((n) => n.name === 'AddCoreServices')
+      ?? cg.getNodesByKind('function').find((n) => n.name === 'AddCoreServices');
+    expect(ext, 'AddCoreServices defined').toBeDefined();
+    const callers = [...cg.getImpactRadius(ext!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(callers.some((p) => p.endsWith('Program.cs')), 'chained extension call resolves to its definition').toBe(true);
+  });
+});
+
+describe('Same-directory include + KMP import resolution', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('a C/C++ #include resolves to the same-directory header, not a same-named one elsewhere', async () => {
+    // A multi-platform native module has a header of the same basename per
+    // platform. `windows/Provider.cpp`'s `#include "Storage.h"` means its OWN
+    // sibling header — not `apple/Storage.h` (which sorts first and so was
+    // picked arbitrarily before, leaving the real local header with 0 deps).
+    fs.mkdirSync(path.join(tempDir, 'apple'), { recursive: true });
+    fs.mkdirSync(path.join(tempDir, 'windows'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'apple', 'Storage.h'), `#pragma once\nstruct Storage { int n; };\n`);
+    fs.writeFileSync(path.join(tempDir, 'windows', 'Storage.h'), `#pragma once\nstruct Storage { int n; };\n`);
+    fs.writeFileSync(
+      path.join(tempDir, 'windows', 'Provider.cpp'),
+      `#include "Storage.h"\nint use() { Storage s; return s.n; }\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const winHeader = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('windows/Storage.h'));
+    const appleHeader = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('apple/Storage.h'));
+    expect(winHeader, 'windows/Storage.h indexed').toBeDefined();
+    expect(appleHeader, 'apple/Storage.h indexed').toBeDefined();
+    const winDeps = [...cg.getImpactRadius(winHeader!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    const appleDeps = [...cg.getImpactRadius(appleHeader!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(winDeps.some((p) => p.endsWith('Provider.cpp')), 'same-dir header gets the includer').toBe(true);
+    expect(appleDeps.some((p) => p.endsWith('Provider.cpp')), 'other-platform header does NOT').toBe(false);
+  });
+
+  it('a Kotlin Multiplatform commonMain import resolves to the expect, not a platform actual', async () => {
+    const common = path.join(tempDir, 'src/commonMain/kotlin/app');
+    const android = path.join(tempDir, 'src/androidMain/kotlin/app');
+    fs.mkdirSync(common, { recursive: true });
+    fs.mkdirSync(android, { recursive: true });
+    fs.writeFileSync(path.join(common, 'Platform.kt'), `package app\nexpect class PlatformContext\n`);
+    fs.writeFileSync(path.join(android, 'Platform.android.kt'), `package app\nactual class PlatformContext\n`);
+    fs.writeFileSync(
+      path.join(common, 'Db.kt'),
+      `package app\nimport app.PlatformContext\nclass Db {\n  fun open(ctx: PlatformContext) {}\n}\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const expectCtx = cg
+      .getNodesByKind('class')
+      .find((n) => n.name === 'PlatformContext' && n.filePath.endsWith('commonMain/kotlin/app/Platform.kt'));
+    expect(expectCtx, 'commonMain expect PlatformContext').toBeDefined();
+    const deps = [...cg.getImpactRadius(expectCtx!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(deps.some((p) => p.endsWith('Db.kt')), 'commonMain import lands on the expect, not the actual').toBe(true);
+  });
+});
+
+describe('Delphi form code-behind pairing', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('links a `.dfm` form to its sibling `.pas` code-behind unit', async () => {
+    // A Delphi form unit owns its visual form definition via `{$R *.dfm}`, not a
+    // `uses` clause — so a `.dfm` used only as a form definition looked orphaned.
+    fs.writeFileSync(path.join(tempDir, 'UFRMAbout.dfm'),
+      `object FRMAbout: TFRMAbout\n  Caption = 'About'\nend\n`);
+    fs.writeFileSync(path.join(tempDir, 'UFRMAbout.pas'),
+      `unit UFRMAbout;\ninterface\nuses Forms;\ntype\n  TFRMAbout = class(TForm)\n  end;\nimplementation\n{$R *.dfm}\nend.\n`);
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const dfm = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('UFRMAbout.dfm'));
+    expect(dfm, 'UFRMAbout.dfm file node').toBeDefined();
+    const deps = cg.getFileDependents(dfm!.filePath);
+    expect(deps.some((p) => p.endsWith('UFRMAbout.pas')), 'the .pas unit links its .dfm form').toBe(true);
+  });
+});
+
+describe('Liquid Shopify JSON template section resolution', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('links a Shopify JSON template section `type` to its sections/<type>.liquid', async () => {
+    // Shopify OS 2.0 templates are JSON, referencing sections by `type` — not
+    // a `{% section %}` Liquid tag — so a section used only from a JSON template
+    // looked unused. The JSON is now indexed and its `type`s linked.
+    fs.mkdirSync(path.join(tempDir, 'sections'), { recursive: true });
+    fs.mkdirSync(path.join(tempDir, 'templates/customers'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'sections/main-product.liquid'), `<div>{{ product.title }}</div>\n`);
+    fs.writeFileSync(path.join(tempDir, 'sections/main-login.liquid'), `<form>{{ 'customer.login' | t }}</form>\n`);
+    fs.writeFileSync(path.join(tempDir, 'templates/product.json'), JSON.stringify({ sections: { main: { type: 'main-product' } }, order: ['main'] }));
+    // Nested template dir (templates/customers/login.json) must resolve too.
+    fs.writeFileSync(path.join(tempDir, 'templates/customers/login.json'), JSON.stringify({ sections: { main: { type: 'main-login' } }, order: ['main'] }));
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const product = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('sections/main-product.liquid'));
+    const login = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('sections/main-login.liquid'));
+    expect(product, 'main-product section').toBeDefined();
+    expect(login, 'main-login section').toBeDefined();
+    expect(cg.getFileDependents(product!.filePath).some((p) => p.endsWith('templates/product.json')), 'top-level JSON template links its section').toBe(true);
+    expect(cg.getFileDependents(login!.filePath).some((p) => p.endsWith('customers/login.json')), 'nested JSON template links its section').toBe(true);
+  });
+});
+
+describe('Lua/Luau require resolution', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('resolves a dotted Lua require and an instance-path Luau require to their module files', async () => {
+    // The require is the ONLY link (no method call), so coverage here proves the
+    // require resolver specifically, not method-call name-matching.
+    // Lua dotted module path: require("myapp.config") → lua/myapp/config.lua.
+    fs.mkdirSync(path.join(tempDir, 'lua/myapp'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'lua/myapp/config.lua'), `local M = {}\nfunction M.setup() end\nreturn M\n`);
+    fs.writeFileSync(path.join(tempDir, 'lua/myapp/init.lua'), `local config = require("myapp.config")\nreturn config\n`);
+    // Luau Roblox instance-path require (only the leaf survives extraction):
+    // require(script.Util.helper) → src/Util/helper.luau.
+    fs.mkdirSync(path.join(tempDir, 'src/Util'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'src/Util/helper.luau'), `local H = {}\nfunction H.go() end\nreturn H\n`);
+    fs.writeFileSync(path.join(tempDir, 'src/init.luau'), `local helper = require(script.Util.helper)\nreturn helper\n`);
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const config = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('myapp/config.lua'));
+    const helper = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('Util/helper.luau'));
+    expect(config, 'config.lua file node').toBeDefined();
+    expect(helper, 'helper.luau file node').toBeDefined();
+    const cfgDeps = cg.getFileDependents(config!.filePath);
+    const helpDeps = cg.getFileDependents(helper!.filePath);
+    expect(cfgDeps.some((p) => p.endsWith('myapp/init.lua')), 'dotted Lua require resolves to the module').toBe(true);
+    expect(helpDeps.some((p) => p.endsWith('src/init.luau')), 'instance-path Luau require resolves to the module').toBe(true);
+  });
+});
+
+describe('Rust module-path call resolution', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('a bare submodule call (`users::router()`) resolves self-relative to the submodule fn', async () => {
+    // The canonical Axum router-assembly pattern: a parent module calls each
+    // submodule's `router()`. `users::` / `profiles::` are SELF-relative
+    // submodule prefixes (2018 edition) — `mod users;` makes `users` a child of
+    // the CURRENT module, NOT `crate::users`. Before the fix the bare prefix was
+    // resolved crate-relative only (looking for `src/users.rs`), so it found
+    // nothing and the handler modules looked dependent-less.
+    const http = path.join(tempDir, 'src/http');
+    fs.mkdirSync(http, { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'src/lib.rs'), `pub mod http;\n`);
+    fs.writeFileSync(
+      path.join(http, 'mod.rs'),
+      `mod users;\nmod profiles;\npub fn api_router() {\n    users::router();\n    profiles::router();\n}\n`
+    );
+    fs.writeFileSync(path.join(http, 'users.rs'), `pub fn router() -> i32 { 1 }\n`);
+    fs.writeFileSync(path.join(http, 'profiles.rs'), `pub fn router() -> i32 { 2 }\n`);
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    // Each submodule's same-named `router` fn must get mod.rs as a dependent —
+    // proving the bare prefix resolved self-relative AND disambiguated the
+    // colliding `router` name to the correct file (not an arbitrary one).
+    const routers = cg.getNodesByKind('function').filter((n) => n.name === 'router');
+    const usersRouter = routers.find((n) => n.filePath.endsWith('http/users.rs'));
+    const profilesRouter = routers.find((n) => n.filePath.endsWith('http/profiles.rs'));
+    expect(usersRouter, 'users.rs router fn').toBeDefined();
+    expect(profilesRouter, 'profiles.rs router fn').toBeDefined();
+    const usersDeps = [...cg.getImpactRadius(usersRouter!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    const profilesDeps = [...cg.getImpactRadius(profilesRouter!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(usersDeps.some((p) => p.endsWith('http/mod.rs')), 'users::router() lands on users.rs').toBe(true);
+    expect(profilesDeps.some((p) => p.endsWith('http/mod.rs')), 'profiles::router() lands on profiles.rs').toBe(true);
+  });
+
+  it('a 3-segment module-path call (`database::profiles::find()`) resolves to the leaf fn', async () => {
+    // A 2-level module path — the common `db.run(move |c| database::profiles::find(c))`
+    // / `crate::a::b::func()` shape. The reference-resolver pre-filter used to drop any
+    // `a::b::c` whose leaf it never checked (it tested only the first segment and the
+    // `b::c` remainder, neither of which names a symbol), so the call never reached the
+    // Rust path resolver and the leaf module looked dependent-less.
+    const routes = path.join(tempDir, 'src/routes');
+    const database = path.join(tempDir, 'src/database');
+    fs.mkdirSync(routes, { recursive: true });
+    fs.mkdirSync(database, { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'src/lib.rs'), `pub mod routes;\npub mod database;\n`);
+    fs.writeFileSync(path.join(database, 'mod.rs'), `pub mod profiles;\n`);
+    fs.writeFileSync(path.join(database, 'profiles.rs'), `pub fn find(id: i32) -> i32 { id }\n`);
+    fs.writeFileSync(
+      path.join(routes, 'mod.rs'),
+      `use crate::database;\npub fn get_profile(id: i32) -> i32 {\n    database::profiles::find(id)\n}\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const find = cg
+      .getNodesByKind('function')
+      .find((n) => n.name === 'find' && n.filePath.endsWith('database/profiles.rs'));
+    expect(find, 'database/profiles.rs find fn').toBeDefined();
+    const deps = [...cg.getImpactRadius(find!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(deps.some((p) => p.endsWith('routes/mod.rs')), 'database::profiles::find() resolves to the leaf fn').toBe(true);
+  });
+
+  it('Rocket `routes![…]` / `catchers![…]` macros link the mount to the handler fns', async () => {
+    // Tree-sitter leaves the macro body as a raw token tree, so the handler
+    // paths inside `routes![a::b::handler, …]` are invisible to the call walker
+    // and the handlers — mounted by Rocket at runtime, not called in-repo — look
+    // like they have no caller. The route-macro extractor reconstructs each path
+    // and emits a reference, which the Rust path resolver links to the handler.
+    const routes = path.join(tempDir, 'src/routes');
+    fs.mkdirSync(routes, { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'src/lib.rs'),
+      `mod routes;\nfn not_found() {}\npub fn rocket() {\n` +
+      `    rocket::build()\n` +
+      `        .mount("/api", routes![routes::users::post_users, routes::users::get_user])\n` +
+      `        .register("/", catchers![not_found]);\n}\n`);
+    fs.writeFileSync(path.join(routes, 'mod.rs'), `pub mod users;\n`);
+    fs.writeFileSync(path.join(routes, 'users.rs'), `pub fn post_users() {}\npub fn get_user() {}\n`);
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const handlers = cg.getNodesByKind('function').filter((n) => n.filePath.endsWith('routes/users.rs'));
+    expect(handlers.length, 'both handler fns indexed').toBe(2);
+    for (const h of handlers) {
+      const deps = [...cg.getImpactRadius(h.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+      expect(deps.some((p) => p.endsWith('lib.rs')), `routes![] links ${h.name} to its mount in lib.rs`).toBe(true);
+    }
+  });
+});
+
+describe('SvelteKit load → page synthesizer', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('links a +page.svelte to its OWN directory\'s +page.server.js load, not another route\'s', async () => {
+    // SvelteKit wires +page.server.js's `load` to +page.svelte's `data` BY FILE
+    // PATH — there is no static import — so editing a loader showed no impact on
+    // the page it feeds. The synthesizer links each page component to the `load`
+    // in its OWN directory (path-deterministic, so it never crosses routes).
+    const login = path.join(tempDir, 'src/routes/login');
+    const register = path.join(tempDir, 'src/routes/register');
+    fs.mkdirSync(login, { recursive: true });
+    fs.mkdirSync(register, { recursive: true });
+    fs.writeFileSync(path.join(login, '+page.svelte'), `<script>export let data;</script>\n<h1>Login {data.x}</h1>\n`);
+    fs.writeFileSync(path.join(login, '+page.server.js'), `export function load() { return { x: 1 }; }\n`);
+    fs.writeFileSync(path.join(register, '+page.svelte'), `<script>export let data;</script>\n<h1>Register</h1>\n`);
+    fs.writeFileSync(path.join(register, '+page.server.js'), `export function load() { return { y: 2 }; }\n`);
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const loginLoad = cg
+      .getNodesByKind('function')
+      .find((n) => n.name === 'load' && n.filePath.endsWith('login/+page.server.js'));
+    expect(loginLoad, 'login load fn').toBeDefined();
+    const impacted = [...cg.getImpactRadius(loginLoad!.id, 3).nodes.values()].map((n) => n.filePath ?? '');
+    // editing login's load surfaces login's page (the framework-wired data flow)…
+    expect(impacted.some((p) => p.endsWith('login/+page.svelte')), 'load links to its own page').toBe(true);
+    // …but never register's page (same-directory only).
+    expect(impacted.some((p) => p.endsWith('register/+page.svelte')), 'does not cross routes').toBe(false);
+  });
+});
+
+describe('Nuxt nested auto-imported component resolution', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('links a `<MediaCard/>` usage to components/media/Card.vue (Nuxt dir-prefixed auto-import)', async () => {
+    // Nuxt auto-imports a nested component by a DIRECTORY-PREFIXED name —
+    // components/media/Card.vue is used as <MediaCard/>, not <Card/> — but the
+    // component node is named by basename (`Card`), so the PascalCase usage
+    // didn't resolve and the nested component looked unused.
+    const media = path.join(tempDir, 'components/media');
+    fs.mkdirSync(media, { recursive: true });
+    fs.writeFileSync(path.join(media, 'Card.vue'), `<template><div>card</div></template>\n<script setup>defineProps(['item'])</script>\n`);
+    fs.writeFileSync(
+      path.join(tempDir, 'components/Grid.vue'),
+      `<template>\n  <div><MediaCard :item="i" /></div>\n</template>\n<script setup>const i = {}</script>\n`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const card = cg.getNodesByKind('component').find((n) => n.filePath.endsWith('media/Card.vue'));
+    expect(card, 'media/Card.vue component').toBeDefined();
+    const deps = [...cg.getImpactRadius(card!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(deps.some((p) => p.endsWith('components/Grid.vue')), '<MediaCard> links Grid to media/Card.vue').toBe(true);
+  });
+});
+
+describe('Swift property-wrapper attribute type references', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('a Fluent `@Siblings(through: Pivot.self)` links the model to the pivot type', async () => {
+    // A many-to-many pivot/join model is referenced ONLY through the relationship
+    // property wrapper's metatype argument (`Pivot.self`), never by a controller
+    // query. The wrapper type was captured but the argument expression wasn't
+    // walked, so the pivot model looked like nothing depended on it.
+    fs.writeFileSync(path.join(tempDir, 'Pivot.swift'),
+      `import Fluent\nfinal class AcronymCategoryPivot: Model {\n  static let schema = "acronym-category"\n}\n`);
+    fs.writeFileSync(path.join(tempDir, 'Acronym.swift'),
+      `import Fluent\nfinal class Acronym: Model {\n` +
+      `  @Siblings(through: AcronymCategoryPivot.self, from: \\.$acronym, to: \\.$category)\n` +
+      `  var categories: [Category]\n}\n`);
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    const pivot = cg.getNodesByKind('class').find((n) => n.name === 'AcronymCategoryPivot');
+    expect(pivot, 'pivot model class').toBeDefined();
+    const deps = [...cg.getImpactRadius(pivot!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(deps.some((p) => p.endsWith('Acronym.swift')), '@Siblings metatype arg links Acronym to the pivot').toBe(true);
+  });
+});
+
+describe('Objective-C messages, class receivers, and #import', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    if (fs.existsSync(tempDir)) fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('resolves single-arg selectors, class-message receivers, and #import headers', async () => {
+    fs.writeFileSync(
+      path.join(tempDir, 'SDImageCache.h'),
+      `#import <Foundation/Foundation.h>
+@interface SDImageCache : NSObject
++ (instancetype)sharedCache;
++ (void)storeImage:(NSString *)key;
+@end
+`
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'SDImageCache.m'),
+      `#import "SDImageCache.h"
+@implementation SDImageCache
++ (instancetype)sharedCache { return nil; }
++ (void)storeImage:(NSString *)key { }
+@end
+`
+    );
+    fs.writeFileSync(
+      path.join(tempDir, 'SDManager.m'),
+      `#import "SDImageCache.h"
+@interface SDManager : NSObject
+@end
+@implementation SDManager
+- (void)run {
+  [SDImageCache sharedCache];
+  [SDImageCache storeImage:@"k"];
+}
+@end
+`
+    );
+
+    cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    cg.resolveReferences();
+
+    // 1. The single-argument selector `[SDImageCache storeImage:@"k"]` resolves
+    //    to the `storeImage:` method — named WITH its colon both at the call site
+    //    and the definition (before the fix the call site dropped the colon).
+    const storeImage = cg.getNodesByKind('method').find((n) => n.name === 'storeImage:');
+    expect(storeImage, 'storeImage: method').toBeDefined();
+    const storeCallers = [...cg.getImpactRadius(storeImage!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(storeCallers.some((p) => p.endsWith('SDManager.m'))).toBe(true);
+
+    // 2. The class-message receiver `[SDImageCache sharedCache]` references the
+    //    SDImageCache class (whose @interface lives in the header).
+    const cache = cg.getNodesByKind('class').find((n) => n.name === 'SDImageCache');
+    expect(cache, 'SDImageCache class').toBeDefined();
+    const classDeps = [...cg.getImpactRadius(cache!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(classDeps.some((p) => p.endsWith('SDManager.m'))).toBe(true);
+
+    // 3. `#import "SDImageCache.h"` resolves to the header FILE — editing it
+    //    surfaces both importers.
+    const header = cg.getNodesByKind('file').find((n) => n.filePath.endsWith('SDImageCache.h'));
+    expect(header, 'SDImageCache.h indexed').toBeDefined();
+    const importers = [...cg.getImpactRadius(header!.id, 2).nodes.values()].map((n) => n.filePath ?? '');
+    expect(importers.some((p) => p.endsWith('SDManager.m'))).toBe(true);
+  });
+});
+
+describe('Full Indexing', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    cleanupTempDir(tempDir);
+  });
+
+  it('should index a TypeScript file', async () => {
+    // Create test file
+    const srcDir = path.join(tempDir, 'src');
+    fs.mkdirSync(srcDir);
+    fs.writeFileSync(
+      path.join(srcDir, 'utils.ts'),
+      `
+export function add(a: number, b: number): number {
+  return a + b;
+}
+
+export function multiply(a: number, b: number): number {
+  return a * b;
+}
+`
+    );
+
+    // Initialize and index
+    const cg = CodeGraph.initSync(tempDir);
+    const result = await cg.indexAll();
+
+    expect(result.success).toBe(true);
+    expect(result.filesIndexed).toBe(1);
+    expect(result.nodesCreated).toBeGreaterThanOrEqual(2);
+
+    // Check nodes were stored
+    const nodes = cg.getNodesInFile('src/utils.ts');
+    expect(nodes.length).toBeGreaterThanOrEqual(2);
+
+    const addFunc = nodes.find((n) => n.name === 'add');
+    expect(addFunc).toBeDefined();
+    expect(addFunc?.kind).toBe('function');
+
+    cg.close();
+  });
+
+  it('should index multiple files', async () => {
+    // Create test files
+    const srcDir = path.join(tempDir, 'src');
+    fs.mkdirSync(srcDir);
+
+    fs.writeFileSync(
+      path.join(srcDir, 'math.ts'),
+      `export function add(a: number, b: number) { return a + b; }`
+    );
+
+    fs.writeFileSync(
+      path.join(srcDir, 'string.ts'),
       `export function capitalize(s: string) { return s.toUpperCase(); }`
     );
 
@@ -2955,23 +5043,87 @@ export function multiply(a: number, b: number): number {
     const cg = CodeGraph.initSync(tempDir);
     await cg.indexAll();
 
-    const initialNodes = cg.getNodesInFile('src/main.ts');
-    expect(initialNodes.some((n) => n.name === 'original')).toBe(true);
+    const initialNodes = cg.getNodesInFile('src/main.ts');
+    expect(initialNodes.some((n) => n.name === 'original')).toBe(true);
+
+    // Modify file
+    fs.writeFileSync(
+      path.join(srcDir, 'main.ts'),
+      `export function updated() { return 2; }`
+    );
+
+    // Sync
+    const syncResult = await cg.sync();
+    expect(syncResult.filesModified).toBe(1);
+
+    // Check nodes were updated
+    const updatedNodes = cg.getNodesInFile('src/main.ts');
+    expect(updatedNodes.some((n) => n.name === 'updated')).toBe(true);
+    expect(updatedNodes.some((n) => n.name === 'original')).toBe(false);
+
+    cg.close();
+  });
+
+  it('should count file-level tracked YAML files as indexed', async () => {
+    fs.writeFileSync(path.join(tempDir, 'app.yaml'), 'name: test\n');
+    fs.writeFileSync(path.join(tempDir, 'routes.yml'), 'route: value\n');
+
+    const cg = CodeGraph.initSync(tempDir);
+    const result = await cg.indexAll();
+
+    expect(result.success).toBe(true);
+    expect(result.filesIndexed).toBe(2);
+    expect(result.filesSkipped).toBe(0);
+    expect(cg.getFiles().map((f) => f.path).sort()).toEqual(['app.yaml', 'routes.yml']);
+
+    cg.close();
+  });
+
+  it('should count file-level tracked YAML/Twig files as indexed in indexFiles()', async () => {
+    fs.writeFileSync(path.join(tempDir, 'app.yaml'), 'name: test\n');
+    fs.writeFileSync(path.join(tempDir, 'view.twig'), '{{ title }}\n');
+
+    const cg = CodeGraph.initSync(tempDir);
+    const result = await cg.indexFiles(['app.yaml', 'view.twig']);
+
+    expect(result.success).toBe(true);
+    expect(result.filesIndexed).toBe(2);
+    expect(result.filesSkipped).toBe(0);
+
+    const tracked = cg.getFiles().map((f) => `${f.path}:${f.language}`).sort();
+    expect(tracked).toEqual(['app.yaml:yaml', 'view.twig:twig']);
+
+    cg.close();
+  });
+
+  it('should count file-level tracked .properties files as indexed', async () => {
+    fs.writeFileSync(path.join(tempDir, 'application.properties'), 'server.port=8080\n');
+    fs.writeFileSync(path.join(tempDir, 'log.properties'), 'log.level=INFO\n');
+
+    const cg = CodeGraph.initSync(tempDir);
+    const result = await cg.indexAll();
+
+    expect(result.success).toBe(true);
+    expect(result.filesIndexed).toBe(2);
+    expect(result.filesSkipped).toBe(0);
+
+    cg.close();
+  });
 
-    // Modify file
-    fs.writeFileSync(
-      path.join(srcDir, 'main.ts'),
-      `export function updated() { return 2; }`
-    );
+  it('should count the full file-level tracked class (yaml/twig/properties) in indexFiles()', async () => {
+    fs.writeFileSync(path.join(tempDir, 'app.yaml'), 'name: test\n');
+    fs.writeFileSync(path.join(tempDir, 'view.twig'), '{{ title }}\n');
+    fs.writeFileSync(path.join(tempDir, 'application.properties'), 'server.port=8080\n');
 
-    // Sync
-    const syncResult = await cg.sync();
-    expect(syncResult.filesModified).toBe(1);
+    const cg = CodeGraph.initSync(tempDir);
+    const result = await cg.indexFiles(['app.yaml', 'view.twig', 'application.properties']);
 
-    // Check nodes were updated
-    const updatedNodes = cg.getNodesInFile('src/main.ts');
-    expect(updatedNodes.some((n) => n.name === 'updated')).toBe(true);
-    expect(updatedNodes.some((n) => n.name === 'original')).toBe(false);
+    expect(result.success).toBe(true);
+    expect(result.filesIndexed).toBe(3);
+    expect(result.filesSkipped).toBe(0);
+
+    const tracked = cg.getFiles().map((f) => `${f.path}:${f.language}`).sort();
+    expect(tracked).toEqual(['app.yaml:yaml', 'application.properties:properties', 'view.twig:twig']);
 
     cg.close();
   });
@@ -3003,39 +5155,57 @@ describe('Directory Exclusion', () => {
     cleanupTempDir(tempDir);
   });
 
-  it('should exclude node_modules directories', () => {
-    // Create structure: src/index.ts + node_modules/pkg/index.js
+  it('should exclude directories listed in .gitignore', () => {
+    // Create structure: src/index.ts + node_modules/pkg/index.js, gitignore node_modules
     const srcDir = path.join(tempDir, 'src');
     const nmDir = path.join(tempDir, 'node_modules', 'pkg');
     fs.mkdirSync(srcDir, { recursive: true });
     fs.mkdirSync(nmDir, { recursive: true });
     fs.writeFileSync(path.join(srcDir, 'index.ts'), 'export const x = 1;');
     fs.writeFileSync(path.join(nmDir, 'index.js'), 'module.exports = {};');
+    fs.writeFileSync(path.join(tempDir, '.gitignore'), 'node_modules/\n');
 
-    const config = { ...DEFAULT_CONFIG, rootDir: tempDir };
-    const files = scanDirectory(tempDir, config);
+    const files = scanDirectory(tempDir);
 
     expect(files).toContain('src/index.ts');
     expect(files.every((f) => !f.includes('node_modules'))).toBe(true);
   });
 
-  it('should exclude nested node_modules directories', () => {
-    // Create structure: packages/app/node_modules/pkg/index.js
+  it('should exclude nested node_modules via a root .gitignore', () => {
+    // A trailing-slash pattern with no leading slash matches at any depth.
     const srcDir = path.join(tempDir, 'packages', 'app', 'src');
     const nmDir = path.join(tempDir, 'packages', 'app', 'node_modules', 'pkg');
     fs.mkdirSync(srcDir, { recursive: true });
     fs.mkdirSync(nmDir, { recursive: true });
     fs.writeFileSync(path.join(srcDir, 'index.ts'), 'export const x = 1;');
     fs.writeFileSync(path.join(nmDir, 'index.js'), 'module.exports = {};');
+    fs.writeFileSync(path.join(tempDir, '.gitignore'), 'node_modules/\n');
 
-    const config = { ...DEFAULT_CONFIG, rootDir: tempDir };
-    const files = scanDirectory(tempDir, config);
+    const files = scanDirectory(tempDir);
 
     expect(files).toContain('packages/app/src/index.ts');
     expect(files.every((f) => !f.includes('node_modules'))).toBe(true);
   });
 
-  it('should exclude .git directories', () => {
+  it('should apply a nested .gitignore only to its own subtree', () => {
+    const appSrc = path.join(tempDir, 'app', 'src');
+    fs.mkdirSync(appSrc, { recursive: true });
+    fs.writeFileSync(path.join(appSrc, 'keep.ts'), 'export const a = 1;');
+    fs.writeFileSync(path.join(appSrc, 'skip.ts'), 'export const b = 2;');
+    fs.writeFileSync(path.join(tempDir, 'app', '.gitignore'), 'src/skip.ts\n');
+    // A sibling with the same name outside app/ must NOT be ignored.
+    const otherDir = path.join(tempDir, 'other', 'src');
+    fs.mkdirSync(otherDir, { recursive: true });
+    fs.writeFileSync(path.join(otherDir, 'skip.ts'), 'export const c = 3;');
+
+    const files = scanDirectory(tempDir);
+
+    expect(files).toContain('app/src/keep.ts');
+    expect(files).not.toContain('app/src/skip.ts');
+    expect(files).toContain('other/src/skip.ts');
+  });
+
+  it('should always skip .git directories', () => {
     const srcDir = path.join(tempDir, 'src');
     const gitDir = path.join(tempDir, '.git', 'objects');
     fs.mkdirSync(srcDir, { recursive: true });
@@ -3043,8 +5213,7 @@ describe('Directory Exclusion', () => {
     fs.writeFileSync(path.join(srcDir, 'index.ts'), 'export const x = 1;');
     fs.writeFileSync(path.join(gitDir, 'pack.ts'), 'export const y = 2;');
 
-    const config = { ...DEFAULT_CONFIG, rootDir: tempDir };
-    const files = scanDirectory(tempDir, config);
+    const files = scanDirectory(tempDir);
 
     expect(files).toContain('src/index.ts');
     expect(files.every((f) => !f.includes('.git'))).toBe(true);
@@ -3055,29 +5224,12 @@ describe('Directory Exclusion', () => {
     fs.mkdirSync(srcDir, { recursive: true });
     fs.writeFileSync(path.join(srcDir, 'Button.tsx'), 'export function Button() {}');
 
-    const config = { ...DEFAULT_CONFIG, rootDir: tempDir };
-    const files = scanDirectory(tempDir, config);
+    const files = scanDirectory(tempDir);
 
     expect(files.length).toBe(1);
     expect(files[0]).toBe('src/components/Button.tsx');
     expect(files[0]).not.toContain('\\');
   });
-
-  it('should respect .codegraphignore marker', () => {
-    const srcDir = path.join(tempDir, 'src');
-    const vendorDir = path.join(tempDir, 'vendor');
-    fs.mkdirSync(srcDir, { recursive: true });
-    fs.mkdirSync(vendorDir, { recursive: true });
-    fs.writeFileSync(path.join(srcDir, 'index.ts'), 'export const x = 1;');
-    fs.writeFileSync(path.join(vendorDir, 'lib.ts'), 'export const y = 2;');
-    fs.writeFileSync(path.join(vendorDir, '.codegraphignore'), '');
-
-    const config = { ...DEFAULT_CONFIG, rootDir: tempDir };
-    const files = scanDirectory(tempDir, config);
-
-    expect(files).toContain('src/index.ts');
-    expect(files.every((f) => !f.includes('vendor'))).toBe(true);
-  });
 });
 
 describe('Git Submodules', () => {
@@ -3124,8 +5276,7 @@ describe('Git Submodules', () => {
     );
     git(mainDir, 'commit', '-q', '-m', 'add submodule');
 
-    const config = { ...DEFAULT_CONFIG, rootDir: mainDir };
-    const files = scanDirectory(mainDir, config);
+    const files = scanDirectory(mainDir);
 
     expect(files).toContain('app.ts');
     expect(files).toContain('libs/lib/lib.ts');
@@ -3173,8 +5324,7 @@ describe('Nested non-submodule git repos', () => {
     git(path.join(root, 'sub_repo2'), 'init', '-q');
     fs.writeFileSync(path.join(sub2, 'two.ts'), 'export const two = 2;');
 
-    const config = { ...DEFAULT_CONFIG, rootDir: root };
-    const files = scanDirectory(root, config);
+    const files = scanDirectory(root);
 
     // Both committed and untracked source from the nested repos must be found.
     expect(files).toContain('sub_repo1/src/one.ts');
@@ -3197,12 +5347,59 @@ describe('Nested non-submodule git repos', () => {
     fs.writeFileSync(path.join(sub, 'real.ts'), 'export const real = 1;');
     fs.writeFileSync(path.join(sub, 'generated.ts'), 'export const generated = 1;');
 
-    const config = { ...DEFAULT_CONFIG, rootDir: root };
-    const files = scanDirectory(root, config);
+    const files = scanDirectory(root);
 
     expect(files).toContain('sub_repo/src/real.ts');
     expect(files).not.toContain('sub_repo/src/generated.ts');
   });
+
+  // A .gitignore the `ignore` library can't compile to a regex must not abort
+  // the whole scan — the bad pattern is dropped, valid ones still apply (#682).
+  it('does not crash on a .gitignore with an uncompilable pattern (#682)', () => {
+    fs.mkdirSync(path.join(tempDir, 'src'), { recursive: true });
+    fs.mkdirSync(path.join(tempDir, 'build'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'src', 'real.ts'), 'export const x = 1;');
+    fs.writeFileSync(path.join(tempDir, 'build', 'out.ts'), 'export const y = 2;');
+    // `\\[` makes the matcher build an unterminated character class — the throw
+    // is lazy (at match time), which is what escaped and killed sync.
+    fs.writeFileSync(path.join(tempDir, '.gitignore'), 'build/\n\\\\[\n');
+
+    let files: string[] = [];
+    expect(() => {
+      files = scanDirectory(tempDir);
+    }).not.toThrow();
+    expect(files).toContain('src/real.ts');
+    // The still-valid `build/` rule is honored; only the bad line was dropped.
+    expect(files.some((f) => f.startsWith('build/'))).toBe(false);
+  });
+
+  // A .gitignore that isn't valid UTF-8 — e.g. encrypted in place by corporate
+  // DLP / endpoint software (UTF-16 header + ciphertext) — is skipped whole,
+  // not fed to the matcher as garbage patterns (#682).
+  it('does not crash on a non-UTF-8 (DLP-encrypted) .gitignore (#682)', () => {
+    fs.mkdirSync(path.join(tempDir, 'src'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'src', 'real.ts'), 'export const x = 1;');
+    const header = Buffer.concat([
+      Buffer.from([0x00, 0x00]),
+      Buffer.from('[notice][user]', 'utf16le'),
+    ]);
+    const junk = Buffer.from([0x5b, 0x99, 0xc3, 0x28, 0x5c, 0x5b, 0xff, 0xfd]);
+    fs.writeFileSync(path.join(tempDir, '.gitignore'), Buffer.concat([header, junk]));
+
+    let files: string[] = [];
+    expect(() => {
+      files = scanDirectory(tempDir);
+    }).not.toThrow();
+    expect(files).toContain('src/real.ts');
+  });
+
+  it('buildDefaultIgnore survives a bad .gitignore and still applies valid rules (#682)', () => {
+    fs.writeFileSync(path.join(tempDir, '.gitignore'), 'dist/\n\\\\[\n');
+    const ig = buildDefaultIgnore(tempDir);
+    expect(() => ig.ignores('src/app.ts')).not.toThrow();
+    expect(ig.ignores('dist/')).toBe(true); // valid rule survives
+    expect(ig.ignores('src/app.ts')).toBe(false);
+  });
 });
 
 // =============================================================================
@@ -3559,6 +5756,79 @@ function increment(): void {
     }
   });
 
+  it('should extract calls from top-level <script setup> initializers', () => {
+    const code = `<template>
+  <div>{{ token }}</div>
+</template>
+
+<script setup lang="ts">
+import { getTokenMp } from './api/upload';
+
+const token = getTokenMp();
+</script>
+`;
+    const result = extractFromSource('Issue425Setup.vue', code);
+
+    const call = result.unresolvedReferences.find(
+      (ref) => ref.referenceKind === 'calls' && ref.referenceName === 'getTokenMp'
+    );
+    expect(call).toBeDefined();
+  });
+
+  it('should extract calls from Vue Options API object methods', () => {
+    const code = `<template>
+  <button @click="save">Save</button>
+</template>
+
+<script>
+import { getTokenMp } from './api/upload';
+
+export default {
+  methods: {
+    save() {
+      return getTokenMp();
+    }
+  },
+  setup() {
+    return getTokenMp();
+  }
+}
+</script>
+`;
+    const result = extractFromSource('Issue425Options.vue', code);
+
+    const calls = result.unresolvedReferences.filter(
+      (ref) => ref.referenceKind === 'calls' && ref.referenceName === 'getTokenMp'
+    );
+    expect(calls).toHaveLength(2);
+  });
+
+  it('should extract component usages from the Vue template (PascalCase + kebab, skipping built-ins) (#629)', () => {
+    const code = `<template>
+  <div class="wrap">
+    <UserCard :user="u" />
+    <my-button>Click</my-button>
+    <Transition><span>x</span></Transition>
+  </div>
+</template>
+
+<script setup lang="ts">
+import UserCard from './UserCard.vue';
+import MyButton from './MyButton.vue';
+</script>
+`;
+    const result = extractFromSource('Host.vue', code);
+    const refs = result.unresolvedReferences
+      .filter((r) => r.referenceKind === 'references')
+      .map((r) => r.referenceName);
+
+    expect(refs).toContain('UserCard'); // PascalCase tag
+    expect(refs).toContain('MyButton'); // kebab <my-button> → MyButton
+    expect(refs).not.toContain('Transition'); // Vue built-in skipped
+    expect(refs).not.toContain('Div'); // native HTML element skipped
+    expect(refs).not.toContain('Span');
+  });
+
   it('should extract from both <script> and <script setup> blocks', () => {
     const code = `<template>
   <div>{{ msg }}</div>
@@ -3625,6 +5895,218 @@ const value = 42;
   });
 });
 
+describe('Astro Extraction', () => {
+  it('should detect Astro files', () => {
+    expect(detectLanguage('src/pages/index.astro')).toBe('astro');
+    expect(detectLanguage('Layout.astro')).toBe('astro');
+    expect(isLanguageSupported('astro')).toBe(true);
+  });
+
+  it('should extract component node from an .astro file', () => {
+    const code = `---
+const title = 'Hello';
+---
+<h1>{title}</h1>
+`;
+    const result = extractFromSource('Card.astro', code);
+
+    const componentNode = result.nodes.find((n) => n.kind === 'component');
+    expect(componentNode).toBeDefined();
+    expect(componentNode?.name).toBe('Card');
+    expect(componentNode?.language).toBe('astro');
+    expect(componentNode?.isExported).toBe(true);
+  });
+
+  it('should extract frontmatter symbols with correct line numbers (#768)', () => {
+    const code = `---
+import { formatDate } from '../utils/format';
+
+function getIconNode(name: string): string {
+  return name;
+}
+
+const { title } = Astro.props;
+---
+<span>{title}</span>
+`;
+    const result = extractFromSource('navs.astro', code);
+
+    // The #768 repro: a function defined in frontmatter must be found
+    const fn = result.nodes.find((n) => n.kind === 'function' && n.name === 'getIconNode');
+    expect(fn).toBeDefined();
+    expect(fn?.language).toBe('astro');
+    expect(fn?.startLine).toBe(4);
+
+    const imp = result.nodes.find((n) => n.kind === 'import');
+    expect(imp).toBeDefined();
+    expect(imp?.startLine).toBe(2);
+  });
+
+  it('should extract exported getStaticPaths from frontmatter', () => {
+    const code = `---
+export async function getStaticPaths() {
+  return [];
+}
+const { slug } = Astro.params;
+---
+<p>{slug}</p>
+`;
+    const result = extractFromSource('[slug].astro', code);
+
+    const fn = result.nodes.find((n) => n.kind === 'function' && n.name === 'getStaticPaths');
+    expect(fn).toBeDefined();
+    expect(fn?.isExported).toBe(true);
+  });
+
+  it('should extract calls from template expressions', () => {
+    const code = `---
+import { formatDate } from '../utils/format';
+const date = new Date();
+---
+<time>{formatDate(date)}</time>
+`;
+    const result = extractFromSource('Stamp.astro', code);
+
+    const call = result.unresolvedReferences.find(
+      (ref) => ref.referenceKind === 'calls' && ref.referenceName === 'formatDate' && ref.line === 5
+    );
+    expect(call).toBeDefined();
+  });
+
+  it('should extract calls from a multiline expression opening line', () => {
+    const code = `---
+const posts = [];
+---
+<ul>
+  {posts.map((post) => (
+    <li>{render(post)}</li>
+  ))}
+</ul>
+`;
+    const result = extractFromSource('List.astro', code);
+
+    const mapCall = result.unresolvedReferences.find(
+      (ref) => ref.referenceKind === 'calls' && ref.referenceName === 'posts.map'
+    );
+    expect(mapCall).toBeDefined();
+    const innerCall = result.unresolvedReferences.find(
+      (ref) => ref.referenceKind === 'calls' && ref.referenceName === 'render'
+    );
+    expect(innerCall).toBeDefined();
+  });
+
+  it('should extract PascalCase component usages from the template', () => {
+    const code = `---
+import Layout from '../layouts/Layout.astro';
+import PostCard from '../components/PostCard.astro';
+---
+<Layout title="Home">
+  <PostCard />
+  <Fragment slot="head" />
+  <div class="plain-html" />
+</Layout>
+`;
+    const result = extractFromSource('index.astro', code);
+
+    const refs = result.unresolvedReferences.filter((r) => r.referenceKind === 'references');
+    const names = refs.map((r) => r.referenceName);
+    expect(names).toContain('Layout');
+    expect(names).toContain('PostCard');
+    // Astro built-ins and lowercase HTML are not component references
+    expect(names).not.toContain('Fragment');
+    expect(names).not.toContain('div');
+  });
+
+  it('should not extract template patterns from frontmatter, script, or style content', () => {
+    const code = `---
+// <FakeComponent /> inside frontmatter comment
+const x = { y: maybeCall(1) };
+---
+<div>real</div>
+<script>
+  const z = { w: scriptCall(2) };
+</script>
+<style>
+  .a { color: red; }
+</style>
+`;
+    const result = extractFromSource('Guard.astro', code);
+
+    const templateRefs = result.unresolvedReferences.filter(
+      (r) => r.referenceKind === 'references' && r.referenceName === 'FakeComponent'
+    );
+    expect(templateRefs).toHaveLength(0);
+
+    // maybeCall/scriptCall come from the delegated TS extraction (once),
+    // not double-counted by the template scanner
+    const maybeCalls = result.unresolvedReferences.filter(
+      (r) => r.referenceName === 'maybeCall' && r.referenceKind === 'calls'
+    );
+    expect(maybeCalls.length).toBeLessThanOrEqual(1);
+  });
+
+  it('should extract <script> block symbols with correct line numbers', () => {
+    const code = `---
+const a = 1;
+---
+<div>hi</div>
+<script>
+function trackView(page: string) {
+  console.log(page);
+}
+</script>
+`;
+    const result = extractFromSource('Tracker.astro', code);
+
+    const fn = result.nodes.find((n) => n.kind === 'function' && n.name === 'trackView');
+    expect(fn).toBeDefined();
+    expect(fn?.startLine).toBe(6);
+    expect(fn?.language).toBe('astro');
+  });
+
+  it('should create component node for a frontmatter-less template-only file', () => {
+    const code = `<div>Static content</div>
+`;
+    const result = extractFromSource('Static.astro', code);
+
+    const componentNode = result.nodes.find((n) => n.kind === 'component');
+    expect(componentNode).toBeDefined();
+    expect(componentNode?.name).toBe('Static');
+    expect(componentNode?.language).toBe('astro');
+  });
+
+  it('should treat an unclosed frontmatter fence as no frontmatter', () => {
+    const code = `---
+const broken = true;
+<div>never closed</div>
+`;
+    const result = extractFromSource('Broken.astro', code);
+
+    // No TS delegation happened (the fence never closes), but the component
+    // node still exists and nothing throws.
+    const componentNode = result.nodes.find((n) => n.kind === 'component');
+    expect(componentNode).toBeDefined();
+    expect(result.nodes.find((n) => n.name === 'broken')).toBeUndefined();
+  });
+
+  it('should create containment edges from component to frontmatter nodes', () => {
+    const code = `---
+const value = 42;
+---
+<div>{value}</div>
+`;
+    const result = extractFromSource('Contained.astro', code);
+
+    const componentNode = result.nodes.find((n) => n.kind === 'component');
+    expect(componentNode).toBeDefined();
+
+    const containEdges = result.edges.filter(
+      (e) => e.source === componentNode!.id && e.kind === 'contains'
+    );
+    expect(containEdges.length).toBeGreaterThan(0);
+  });
+});
+
 describe('Instantiates + Decorates edge extraction', () => {
   it('emits an instantiates ref for `new Foo()`', () => {
     const code = `
@@ -3899,3 +6381,598 @@ local count = 0
     });
   });
 });
+
+// =============================================================================
+// Objective-C
+// =============================================================================
+
+describe('Objective-C Extraction', () => {
+  const sample = `
+#import <Foundation/Foundation.h>
+#import "MyClass.h"
+
+@interface MyClass : NSObject <NSCopying>
+@property (nonatomic, copy) NSString *name;
+- (void)greet;
+- (void)doThing:(id)x with:(id)y;
++ (instancetype)shared;
+@end
+
+@implementation MyClass
+
+- (void)greet {
+    NSLog(@"Hello");
+    [self doWork];
+}
+
+- (void)doThing:(id)x with:(id)y {
+    [self notify:x];
+}
+
++ (instancetype)shared {
+    return [[MyClass alloc] init];
+}
+
+@end
+
+void helperFunction(int count) {
+    MyClass *obj = [MyClass shared];
+    [obj greet];
+}
+`;
+
+  it('should extract classes, methods, functions, and imports', () => {
+    const result = extractFromSource('App.m', sample);
+
+    const classes = result.nodes.filter((n) => n.kind === 'class');
+    expect(classes.filter((c) => c.name === 'MyClass')).toHaveLength(1);
+
+    const methods = result.nodes.filter((n) => n.kind === 'method');
+    expect(methods.map((m) => m.name).sort()).toEqual(['doThing:with:', 'greet', 'shared']);
+
+    const shared = methods.find((m) => m.name === 'shared');
+    expect(shared?.isStatic).toBe(true);
+
+    const properties = result.nodes.filter((n) => n.kind === 'property');
+    expect(properties.some((p) => p.name === 'name')).toBe(true);
+
+    const functions = result.nodes.filter((n) => n.kind === 'function');
+    expect(functions.some((f) => f.name === 'helperFunction')).toBe(true);
+
+    const imports = result.nodes.filter((n) => n.kind === 'import').map((n) => n.name);
+    expect(imports).toContain('Foundation/Foundation.h');
+    expect(imports).toContain('MyClass.h');
+  });
+
+  it('should record inheritance and protocol conformance', () => {
+    const result = extractFromSource('App.m', sample);
+    const extendsRefs = result.unresolvedReferences.filter((r) => r.referenceKind === 'extends');
+    const implementsRefs = result.unresolvedReferences.filter((r) => r.referenceKind === 'implements');
+    expect(extendsRefs.map((r) => r.referenceName)).toContain('NSObject');
+    expect(implementsRefs.map((r) => r.referenceName)).toContain('NSCopying');
+  });
+
+  it('should record message sends and C calls', () => {
+    const result = extractFromSource('App.m', sample);
+    const calls = result.unresolvedReferences
+      .filter((r) => r.referenceKind === 'calls')
+      .map((r) => r.referenceName);
+    expect(calls).toEqual(expect.arrayContaining(['NSLog', 'doWork', 'MyClass.shared', 'obj.greet']));
+  });
+
+  it('should reconstruct multi-keyword selectors at the call site so they resolve to the method definition', () => {
+    // Regression for the gap discovered post-#165: message_expression's
+    // multi-keyword form `[obj a:1 b:2]` was only emitting the first keyword,
+    // so calls never resolved to multi-part method definitions like
+    // `GET:parameters:headers:progress:success:failure:`. The call-site name
+    // must match the method-definition name with full keywords + trailing colons.
+    const code = `
+@implementation Caller
+- (void)demo {
+    NSMutableDictionary *d = [NSMutableDictionary new];
+    [d setObject:@"v" forKey:@"k"];
+    [d setObject:@"v2" forKey:@"k2" withRetry:@YES];
+    [self touchesBegan:nil withEvent:nil];
+}
+@end
+`;
+    const result = extractFromSource('Caller.m', code);
+    const calls = result.unresolvedReferences
+      .filter((r) => r.referenceKind === 'calls')
+      .map((r) => r.referenceName);
+    expect(calls).toEqual(
+      expect.arrayContaining([
+        'd.setObject:forKey:',
+        'd.setObject:forKey:withRetry:',
+        'touchesBegan:withEvent:',
+      ])
+    );
+  });
+
+  it('should not classify pure C headers with @end in comments as objc', () => {
+    const cHeader = '/* @end of file */\n#ifndef STDIO_H\nvoid printf(const char *);\n#endif\n';
+    expect(detectLanguage('stdio.h', cHeader)).toBe('c');
+  });
+
+  it('should extract protocol declarations', () => {
+    const code = `
+@protocol DataSource <NSObject>
+- (NSInteger)numberOfItems;
+@end
+`;
+    const result = extractFromSource('DataSource.h', code);
+    const protocol = result.nodes.find((n) => n.kind === 'protocol' && n.name === 'DataSource');
+    expect(protocol).toBeDefined();
+  });
+
+  it('should report Objective-C as supported', () => {
+    expect(isLanguageSupported('objc')).toBe(true);
+    expect(getSupportedLanguages()).toContain('objc');
+  });
+});
+
+describe('Regression: issue-specific extraction fixes', () => {
+  it('indexes inner functions of an anonymous AMD/CommonJS module wrapper (#528)', () => {
+    const code = `
+define(['dep'], function (dep) {
+  function innerHelper(x) { return x + 1; }
+  function compute(y) { return innerHelper(y); }
+  return { compute: compute };
+});
+`;
+    const result = extractFromSource('amd-module.js', code);
+    const fns = result.nodes.filter((n) => n.kind === 'function').map((n) => n.name);
+    expect(fns).toContain('innerHelper');
+    expect(fns).toContain('compute');
+  });
+
+  it('attaches Go methods on generic receivers to their type (#583)', () => {
+    const code = `
+package main
+
+type Stack[T any] struct { items []T }
+
+func (s *Stack[T]) Push(v T) { s.items = append(s.items, v) }
+func (s Stack[T]) Len() int { return len(s.items) }
+`;
+    const result = extractFromSource('stack.go', code);
+    const methods = result.nodes.filter((n) => n.kind === 'method');
+    expect(methods.find((m) => m.name === 'Push')?.qualifiedName).toBe('Stack::Push');
+    expect(methods.find((m) => m.name === 'Len')?.qualifiedName).toBe('Stack::Len');
+  });
+
+  it('indexes new module extensions: .mts/.cts (TS) and .xsjs/.xsjslib (JS) (#366, #556)', () => {
+    expect(isSourceFile('mod.mts')).toBe(true);
+    expect(isSourceFile('mod.cts')).toBe(true);
+    expect(isSourceFile('service.xsjs')).toBe(true);
+    expect(isSourceFile('lib.xsjslib')).toBe(true);
+    expect(detectLanguage('mod.mts')).toBe('typescript');
+    expect(detectLanguage('service.xsjs')).toBe('javascript');
+
+    // End-to-end: a .mts file is parsed as TS, a .xsjs file as JS.
+    const ts = extractFromSource('mod.mts', 'export function hello(): number { return 1; }');
+    expect(ts.nodes.find((n) => n.name === 'hello' && n.kind === 'function')).toBeDefined();
+    const js = extractFromSource('service.xsjs', 'function handleRequest() { return 1; }');
+    expect(js.nodes.find((n) => n.name === 'handleRequest' && n.kind === 'function')).toBeDefined();
+  });
+});
+
+describe('Import / re-export dependency linking (blast-radius recall)', () => {
+  // An import IS a dependency, but extraction only emits references for calls,
+  // instantiations, type annotations, and inheritance — so a symbol imported and
+  // then merely re-exported, placed in a registry array, passed as an argument,
+  // or used in JSX produced no cross-file edge, leaving the providing file with a
+  // false "0 dependents". These tests pin the import/re-export binding linking.
+  it('emits an imports reference per named, aliased, and default import binding', () => {
+    const code = `
+import { widget, helper as h } from './foo';
+import Thing from './thing';
+import * as NS from './ns';
+export const registry = [widget];
+`;
+    const result = extractFromSource('bar.ts', code);
+    const names = result.unresolvedReferences
+      .filter((r) => r.referenceKind === 'imports')
+      .map((r) => r.referenceName);
+    expect(names).toContain('widget');   // named import → local name
+    expect(names).toContain('h');        // aliased import → local alias
+    expect(names).toContain('Thing');    // default import
+    expect(names).toContain('NS');       // namespace import → linked to the module file as a dependency
+  });
+
+  it('emits an imports reference per re-exported binding', () => {
+    const result = extractFromSource('barrel.ts', `export { alpha, beta as b } from './source';`);
+    const names = result.unresolvedReferences
+      .filter((r) => r.referenceKind === 'imports')
+      .map((r) => r.referenceName);
+    // Re-export links the SOURCE-side name, not the local alias.
+    expect(names).toContain('alpha');
+    expect(names).toContain('beta');
+  });
+
+  it('a value imported/re-exported but never called still makes the importer a dependent', async () => {
+    const dir = createTempDir();
+    try {
+      fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+      fs.writeFileSync(
+        path.join(dir, 'src', 'foo.ts'),
+        `export const widget = { n: 1 };\nexport function helper(): void {}\n`
+      );
+      // bar uses widget ONLY in an array and re-exports helper — neither is
+      // called/typed, so before import-linking bar had no edge to foo at all.
+      fs.writeFileSync(
+        path.join(dir, 'src', 'bar.ts'),
+        `import { widget } from './foo';\nexport { helper } from './foo';\nexport const registry = [widget];\n`
+      );
+      const cg = CodeGraph.initSync(dir, { config: { include: ['src/**/*.ts'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('src/foo.ts')).toContain('src/bar.ts');
+      cg.destroy();
+    } finally {
+      cleanupTempDir(dir);
+    }
+  });
+
+  it('a namespace import touched only via a value-member read still links the module file', async () => {
+    const dir = createTempDir();
+    try {
+      fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+      fs.writeFileSync(path.join(dir, 'src', 'foo.ts'), `export const SOME_CONST = 42;\n`);
+      // `foo` is imported as a namespace and used ONLY via a value-member read
+      // (no call, no type) — `foo.helper()` would link on its own, but a bare
+      // `foo.SOME_CONST` would not, so the module-import backstop must link it.
+      fs.writeFileSync(path.join(dir, 'src', 'bar.ts'), `import * as foo from './foo';\nexport const x = foo.SOME_CONST;\n`);
+      const cg = CodeGraph.initSync(dir, { config: { include: ['src/**/*.ts'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('src/foo.ts')).toContain('src/bar.ts');
+      cg.destroy();
+    } finally {
+      cleanupTempDir(dir);
+    }
+  });
+});
+
+describe('Python import dependency linking (blast-radius recall)', () => {
+  // Same recall gap as TS: Python only linked called/instantiated imports, so a
+  // name brought in with `from module import X` and then merely stored, used as
+  // a decorator/argument, or re-exported through an `__init__.py` produced no
+  // cross-file edge — the providing module showed a false "0 dependents".
+  it('emits an imports reference per name in a `from module import ...` (incl. value/aliased)', () => {
+    const code = [
+      'from foo import helper, widget',
+      'from foo import Thing as T',
+      'from . import sibling',
+      'from bar import *',
+    ].join('\n');
+    const names = extractFromSource('mod.py', code)
+      .unresolvedReferences.filter((r) => r.referenceKind === 'imports')
+      .map((r) => r.referenceName);
+    expect(names).toContain('helper');
+    expect(names).toContain('widget');   // value import
+    expect(names).toContain('T');        // aliased import → local name
+    expect(names).toContain('sibling');  // `from . import <name>`
+    expect(names).not.toContain('*');    // wildcard import has no names
+  });
+
+  it('a Python value imported but never called still makes the importer a dependent', async () => {
+    const dir = createTempDir();
+    try {
+      fs.mkdirSync(path.join(dir, 'pkg'), { recursive: true });
+      fs.writeFileSync(path.join(dir, 'pkg', 'foo.py'), `widget = {"n": 1}\ndef helper():\n    return 1\n`);
+      // bar imports widget+helper but only stores widget in a list — nothing is
+      // called, so before import-linking bar had no edge to foo.
+      fs.writeFileSync(path.join(dir, 'pkg', 'bar.py'), `from foo import widget, helper\nregistry = [widget]\n`);
+      const cg = CodeGraph.initSync(dir, { config: { include: ['pkg/**/*.py'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('pkg/foo.py')).toContain('pkg/bar.py');
+      cg.destroy();
+    } finally {
+      cleanupTempDir(dir);
+    }
+  });
+
+  it('resolves `from . import submodule` + `submodule.func()` to the submodule', async () => {
+    const dir = createTempDir();
+    try {
+      fs.mkdirSync(path.join(dir, 'pkg'), { recursive: true });
+      fs.writeFileSync(path.join(dir, 'pkg', '__init__.py'), '');
+      fs.writeFileSync(path.join(dir, 'pkg', 'certs.py'), `def where():\n    return "/ca.pem"\n`);
+      // certs is an imported MODULE (a file), and certs.where() is a qualified
+      // call through it — the receiver isn't a symbol, so plain name-matching
+      // can't link it. Also exercises the Python relative-dot path fix (`.certs`).
+      fs.writeFileSync(path.join(dir, 'pkg', 'utils.py'), `from . import certs\ndef go():\n    return certs.where()\n`);
+      const cg = CodeGraph.initSync(dir, { config: { include: ['pkg/**/*.py'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('pkg/certs.py')).toContain('pkg/utils.py');
+      cg.destroy();
+    } finally {
+      cleanupTempDir(dir);
+    }
+  });
+
+  it('a module import is a dependency even when the used member is re-exported elsewhere', async () => {
+    const dir = createTempDir();
+    try {
+      fs.mkdirSync(path.join(dir, 'pkg'), { recursive: true });
+      fs.writeFileSync(path.join(dir, 'pkg', '__init__.py'), '');
+      // `where` is NOT defined in certs.py (re-exported from a 3rd-party pkg), so
+      // member resolution can't find it — the module-import backstop must still
+      // record utils -> certs. (Mirrors requests' real `certs.where`.)
+      fs.writeFileSync(path.join(dir, 'pkg', 'certs.py'), `from external_ca import where\n`);
+      fs.writeFileSync(path.join(dir, 'pkg', 'utils.py'), `from . import certs\nCA = certs.where()\n`);
+      const cg = CodeGraph.initSync(dir, { config: { include: ['pkg/**/*.py'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('pkg/certs.py')).toContain('pkg/utils.py');
+      cg.destroy();
+    } finally {
+      cleanupTempDir(dir);
+    }
+  });
+});
+
+describe('Go cross-package composite literals (blast-radius recall)', () => {
+  // Go function calls and type references across packages already resolved, but
+  // struct composite literals — `render.XML{...}` / `pkga.Widget{...}` — were not
+  // extracted at all, so a package whose types are only INSTANTIATED elsewhere
+  // (gin's render/binding implementations) showed 0 dependents.
+  it('links a cross-package struct composite literal to the defining package', async () => {
+    const dir = createTempDir();
+    try {
+      fs.writeFileSync(path.join(dir, 'go.mod'), 'module example.com/proj\n\ngo 1.21\n');
+      fs.mkdirSync(path.join(dir, 'render'), { recursive: true });
+      fs.writeFileSync(path.join(dir, 'render', 'xml.go'), `package render\n\ntype XML struct { Data any }\n`);
+      fs.writeFileSync(path.join(dir, 'app.go'), `package main\n\nimport "example.com/proj/render"\n\nfunc handle() any { return render.XML{} }\n`);
+      const cg = CodeGraph.initSync(dir, { config: { include: ['**/*.go'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('render/xml.go')).toContain('app.go');
+      cg.destroy();
+    } finally {
+      cleanupTempDir(dir);
+    }
+  });
+
+  it('links a composite literal in a package-level var registry', async () => {
+    const dir = createTempDir();
+    try {
+      fs.writeFileSync(path.join(dir, 'go.mod'), 'module example.com/proj\n\ngo 1.21\n');
+      fs.mkdirSync(path.join(dir, 'render'), { recursive: true });
+      fs.writeFileSync(path.join(dir, 'render', 'xml.go'), `package render\n\ntype XML struct {}\nfunc (XML) Render() {}\n`);
+      // The implementation is registered only in a top-level `var registry = {...}`
+      // map literal — the body walker doesn't cover top-level declarations, so this
+      // exercises the var-initializer walking added for Go.
+      fs.writeFileSync(path.join(dir, 'reg.go'), `package main\n\nimport "example.com/proj/render"\n\ntype R interface { Render() }\n\nvar registry = map[string]R{ "xml": render.XML{} }\n`);
+      const cg = CodeGraph.initSync(dir, { config: { include: ['**/*.go'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('render/xml.go')).toContain('reg.go');
+      cg.destroy();
+    } finally {
+      cleanupTempDir(dir);
+    }
+  });
+
+  it('attributes a call inside a top-level closure (cobra RunE) to the var, not the file (#693)', async () => {
+    const dir = createTempDir();
+    try {
+      fs.writeFileSync(path.join(dir, 'go.mod'), 'module example.com/proj\n\ngo 1.21\n');
+      // Wire is called ONLY from the anonymous RunE closure inside a top-level
+      // `var rootCmd = &Cmd{...}` — previously the call leaked to the file node,
+      // so `callers(Wire)` surfaced a file (or read as "no caller"). It must now
+      // attribute to the enclosing var.
+      fs.writeFileSync(path.join(dir, 'factory.go'), `package main\n\nfunc Wire() error { return nil }\n`);
+      fs.writeFileSync(
+        path.join(dir, 'root.go'),
+        `package main\n\ntype Cmd struct{ RunE func() error }\n\nvar rootCmd = &Cmd{\n\tRunE: func() error { return Wire() },\n}\n`
+      );
+      const cg = CodeGraph.initSync(dir, { config: { include: ['**/*.go'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+
+      const wire = cg.getNodesByName('Wire').find((n) => n.kind === 'function');
+      expect(wire).toBeDefined();
+      const callers = cg.getCallers(wire!.id).map((c) => c.node);
+      expect(callers.some((n) => n.kind === 'variable' && n.name === 'rootCmd')).toBe(true);
+      expect(callers.some((n) => n.kind === 'file')).toBe(false);
+      cg.destroy();
+    } finally {
+      cleanupTempDir(dir);
+    }
+  });
+
+  it('links a parenthesized pointer type conversion `(*T)(x)` to the type', async () => {
+    const dir = createTempDir();
+    try {
+      fs.writeFileSync(path.join(dir, 'go.mod'), 'module example.com/proj\n\ngo 1.21\n');
+      fs.writeFileSync(path.join(dir, 'types.go'), `package main\n\ntype Wrapped struct { N int }\n`);
+      // `(*Wrapped)(x)` parses as a call whose callee is the parenthesized type
+      // `(*Wrapped)` — without normalization it dropped on the floor.
+      fs.writeFileSync(path.join(dir, 'use.go'), `package main\n\nfunc run(x *int) { _ = (*Wrapped)(x) }\n`);
+      const cg = CodeGraph.initSync(dir, { config: { include: ['**/*.go'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('types.go')).toContain('use.go');
+      cg.destroy();
+    } finally {
+      cleanupTempDir(dir);
+    }
+  });
+
+  it('links an implementation reached only through a Go interface (implicit satisfaction, #584)', async () => {
+    const dir = createTempDir();
+    try {
+      fs.writeFileSync(path.join(dir, 'go.mod'), 'module example.com/proj\n\ngo 1.21\n');
+      fs.mkdirSync(path.join(dir, 'codec'), { recursive: true });
+      fs.writeFileSync(path.join(dir, 'codec', 'api.go'), `package codec\n\ntype Core interface {\n\tMarshal(v any) ([]byte, error)\n}\n\nvar API Core\n`);
+      // jsonApi satisfies Core structurally (no `implements` keyword) and is
+      // reached ONLY through the interface (API.Marshal). Without implicit
+      // interface satisfaction + dispatch, json.go shows 0 dependents.
+      fs.writeFileSync(path.join(dir, 'codec', 'json.go'), `package codec\n\ntype jsonApi struct{}\n\nfunc (j jsonApi) Marshal(v any) ([]byte, error) { return nil, nil }\n\nfunc init() { API = jsonApi{} }\n`);
+      const cg = CodeGraph.initSync(dir, { config: { include: ['**/*.go'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('codec/json.go')).toContain('codec/api.go');
+      cg.destroy();
+    } finally {
+      cleanupTempDir(dir);
+    }
+  });
+});
+
+describe('C# records (blast-radius recall)', () => {
+  // Records are ubiquitous in modern C# (DTOs, value objects, CQRS messages),
+  // but `record` / `record struct` declarations weren't extracted as types — so
+  // every reference, generic-type-argument, and `new` of a record dropped on the
+  // floor and the defining file showed 0 dependents. (#237)
+  it('extracts a record as a graph node (record class + record struct)', () => {
+    const r = extractFromSource('r.cs', `namespace P;\npublic record Box(int N);\npublic record struct Pt(int X);\n`);
+    expect(r.nodes.find((n) => n.name === 'Box' && (n.kind === 'class' || n.kind === 'struct'))).toBeDefined();
+    expect(r.nodes.find((n) => n.name === 'Pt' && (n.kind === 'class' || n.kind === 'struct'))).toBeDefined();
+  });
+
+  it('resolves references / instantiations of a record across files', async () => {
+    const dir = createTempDir();
+    try {
+      fs.writeFileSync(path.join(dir, 'types.cs'), `namespace P;\npublic record Box(int N);\n`);
+      // Box is used as a generic type argument and instantiated — both require
+      // Box to be a node to resolve.
+      fs.writeFileSync(
+        path.join(dir, 'use.cs'),
+        `using System.Collections.Generic;\nnamespace P;\npublic class User {\n    public IEnumerable<Box> Boxes { get; }\n    public Box Make() => new Box(1);\n}\n`
+      );
+      const cg = CodeGraph.initSync(dir, { config: { include: ['**/*.cs'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('types.cs')).toContain('use.cs');
+      cg.destroy();
+    } finally {
+      cleanupTempDir(dir);
+    }
+  });
+});
+
+describe('Rust cross-module recall', () => {
+  function rustProject(files: Record<string, string>): string {
+    const dir = createTempDir();
+    fs.writeFileSync(path.join(dir, 'Cargo.toml'), '[package]\nname = "proj"\nversion = "0.1.0"\nedition = "2021"\n');
+    fs.mkdirSync(path.join(dir, 'src'), { recursive: true });
+    for (const [rel, content] of Object.entries(files)) {
+      const full = path.join(dir, 'src', rel);
+      fs.mkdirSync(path.dirname(full), { recursive: true });
+      fs.writeFileSync(full, content);
+    }
+    return dir;
+  }
+
+  it('extracts a struct literal `Foo { .. }` as an instantiation across modules', async () => {
+    const dir = rustProject({
+      'lib.rs': 'pub mod types;\npub mod consumer;\n',
+      'types.rs': 'pub struct Widget { pub n: i32 }\n',
+      'consumer.rs': 'use crate::types::Widget;\npub fn build() -> Widget { Widget { n: 1 } }\n',
+    });
+    try {
+      const cg = CodeGraph.initSync(dir, { config: { include: ['src/**/*.rs'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('src/types.rs')).toContain('src/consumer.rs');
+      cg.destroy();
+    } finally { cleanupTempDir(dir); }
+  });
+
+  it('extracts trait method declarations and bridges trait dispatch to the impl', async () => {
+    const dir = rustProject({
+      'lib.rs': 'pub mod types;\npub mod consumer;\n',
+      'types.rs': 'pub trait Render { fn render(&self) -> i32; }\n',
+      // Mine implements Render structurally; reached via &dyn Render dispatch.
+      'consumer.rs': 'use crate::types::Render;\npub struct Mine { pub x: i32 }\nimpl Render for Mine { fn render(&self) -> i32 { self.x } }\n',
+    });
+    try {
+      const cg = CodeGraph.initSync(dir, { config: { include: ['src/**/*.rs'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      // implements edge (Mine -> Render) makes types.rs a dependent of consumer.rs's struct.
+      expect(cg.getFileDependents('src/types.rs')).toContain('src/consumer.rs');
+      cg.destroy();
+    } finally { cleanupTempDir(dir); }
+  });
+
+  it('links `pub use` re-export hubs to the modules they re-export', async () => {
+    const dir = rustProject({
+      'lib.rs': 'pub mod api;\n',
+      'api/mod.rs': 'mod widget;\npub use self::widget::Widget;\n',
+      'api/widget.rs': 'pub struct Widget { pub n: i32 }\n',
+    });
+    try {
+      const cg = CodeGraph.initSync(dir, { config: { include: ['src/**/*.rs'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      // The re-export hub depends on the module it re-exports from.
+      expect(cg.getFileDependents('src/api/widget.rs')).toContain('src/api/mod.rs');
+      cg.destroy();
+    } finally { cleanupTempDir(dir); }
+  });
+
+  it('resolves a qualified path to the correct module when the leaf name collides', async () => {
+    const dir = rustProject({
+      'lib.rs': 'pub mod fast;\npub mod slow;\npub mod hub;\n',
+      'fast.rs': 'pub fn read() -> i32 { 1 }\n',
+      'slow.rs': 'pub fn read() -> i32 { 2 }\n',
+      // `read` exists in BOTH fast.rs and slow.rs — module-path resolution must
+      // send this re-export to fast.rs specifically, not name-match either.
+      'hub.rs': 'pub use crate::fast::read;\n',
+    });
+    try {
+      const cg = CodeGraph.initSync(dir, { config: { include: ['src/**/*.rs'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('src/fast.rs')).toContain('src/hub.rs');
+      expect(cg.getFileDependents('src/slow.rs')).not.toContain('src/hub.rs');
+      cg.destroy();
+    } finally { cleanupTempDir(dir); }
+  });
+});
+
+describe('Java annotations (blast-radius recall)', () => {
+  it('indexes @interface definitions and links @Annotation usages to them', async () => {
+    const dir = createTempDir();
+    try {
+      fs.mkdirSync(path.join(dir, 'p'), { recursive: true });
+      // The annotation DEFINITION must be a node, and the @MyAnno usages (which
+      // live inside a `modifiers` node on the class/field/method) must extract.
+      fs.writeFileSync(path.join(dir, 'p', 'MyAnno.java'), `package p;\npublic @interface MyAnno { String value() default ""; }\n`);
+      fs.writeFileSync(
+        path.join(dir, 'p', 'User.java'),
+        `package p;\n@MyAnno("c")\npublic class User {\n  @MyAnno("f") int field;\n  @MyAnno("m") void go() {}\n}\n`
+      );
+      const cg = CodeGraph.initSync(dir, { config: { include: ['**/*.java'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('p/MyAnno.java')).toContain('p/User.java');
+      cg.destroy();
+    } finally { cleanupTempDir(dir); }
+  });
+});
+
+describe('Swift property wrappers / attributes (blast-radius recall)', () => {
+  it('links a @propertyWrapper usage to the wrapper type', async () => {
+    const dir = createTempDir();
+    try {
+      fs.mkdirSync(path.join(dir, 'Sources', 'M'), { recursive: true });
+      fs.writeFileSync(path.join(dir, 'Sources', 'M', 'Wrap.swift'), `@propertyWrapper\npublic struct Argument<T> { public var wrappedValue: T }\n`);
+      // `@Argument` is a Swift attribute on a stored property — it lives in the
+      // property's `modifiers` and Swift doesn't extract instance properties as
+      // their own nodes, so without the fix the wrapper type has no users.
+      fs.writeFileSync(path.join(dir, 'Sources', 'M', 'Cmd.swift'), `public struct MyCommand {\n  @Argument var name: String\n  @Argument var count: Int\n}\n`);
+      const cg = CodeGraph.initSync(dir, { config: { include: ['Sources/**/*.swift'], exclude: [] } });
+      await cg.indexAll();
+      cg.resolveReferences();
+      expect(cg.getFileDependents('Sources/M/Wrap.swift')).toContain('Sources/M/Cmd.swift');
+      cg.destroy();
+    } finally { cleanupTempDir(dir); }
+  });
+});
diff --git a/__tests__/fabric-view.test.ts b/__tests__/fabric-view.test.ts
new file mode 100644
index 000000000..84e652940
--- /dev/null
+++ b/__tests__/fabric-view.test.ts
@@ -0,0 +1,144 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { CodeGraph } from '../src';
+import { fabricViewResolver } from '../src/resolution/frameworks/fabric';
+
+describe('Fabric view component extractor (codegenNativeComponent specs)', () => {
+  it('extracts a component node + prop nodes from a Native*.ts spec', () => {
+    const source = `
+'use client';
+import { codegenNativeComponent } from 'react-native';
+import type { ViewProps, CodegenTypes as CT, ColorValue } from 'react-native';
+
+type TapEvent = Readonly<{ x: number; y: number }>;
+
+export interface NativeProps extends ViewProps {
+  color?: ColorValue;
+  onTap?: CT.DirectEventHandler<TapEvent>;
+  caption?: string;
+}
+
+export default codegenNativeComponent<NativeProps>('MyView', {});
+`;
+    const result = fabricViewResolver.extract?.('src/MyViewNativeComponent.ts', source);
+    expect(result).toBeDefined();
+    const componentNodes = result!.nodes.filter((n) => n.kind === 'component');
+    const propNodes = result!.nodes.filter((n) => n.kind === 'property');
+    expect(componentNodes).toHaveLength(1);
+    expect(componentNodes[0]?.name).toBe('MyView');
+    expect(propNodes.map((n) => n.name).sort()).toEqual(['caption', 'color', 'onTap']);
+  });
+
+  it('returns nothing for a file without codegenNativeComponent', () => {
+    const source = `export const x = 1;`;
+    const result = fabricViewResolver.extract?.('plain.ts', source);
+    expect(result?.nodes).toHaveLength(0);
+  });
+
+  it('handles a spec with no NativeProps interface (rare but valid)', () => {
+    const source = `
+import { codegenNativeComponent } from 'react-native';
+export default codegenNativeComponent('BareComponent');
+`;
+    const result = fabricViewResolver.extract?.('Bare.ts', source);
+    // Component node exists; no prop nodes.
+    const components = result!.nodes.filter((n) => n.kind === 'component');
+    const props = result!.nodes.filter((n) => n.kind === 'property');
+    expect(components).toHaveLength(1);
+    expect(components[0]?.name).toBe('BareComponent');
+    expect(props).toHaveLength(0);
+  });
+});
+
+describe('Fabric end-to-end: JSX consumer → Fabric component → native class', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'fabric-fixture-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('connects <MyView/> JSX to the native ObjC class via Fabric synthesizer', async () => {
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      '{"dependencies":{"react-native":"^0.73"}}'
+    );
+    // Fabric spec.
+    fs.mkdirSync(path.join(dir, 'spec'));
+    fs.writeFileSync(
+      path.join(dir, 'spec', 'MyViewNativeComponent.ts'),
+      `import { codegenNativeComponent } from 'react-native';
+import type { ViewProps } from 'react-native';
+export interface NativeProps extends ViewProps { color?: string; }
+export default codegenNativeComponent<NativeProps>('MyView');`
+    );
+    // Native iOS implementation — class named with the `View` suffix
+    // convention.
+    fs.mkdirSync(path.join(dir, 'ios'));
+    fs.writeFileSync(
+      path.join(dir, 'ios', 'MyView.mm'),
+      `@interface MyViewView : UIView
+@end
+@implementation MyViewView
+- (void)setColor:(NSString *)c { /* … */ }
+@end`
+    );
+    // JSX consumer.
+    fs.mkdirSync(path.join(dir, 'src'));
+    fs.writeFileSync(
+      path.join(dir, 'src', 'App.tsx'),
+      `import React from 'react';
+import MyView from '../spec/MyViewNativeComponent';
+export function App() {
+  return <MyView color="red"/>;
+}`
+    );
+
+    const cg = await CodeGraph.init(dir, { silent: true });
+    await cg.indexAll();
+    const db = (cg as any).db.db;
+
+    // 1. The Fabric component node exists.
+    const componentRows = db
+      .prepare("SELECT id, name, kind FROM nodes WHERE id LIKE 'fabric-component:%' AND name='MyView'")
+      .all();
+    expect(componentRows).toHaveLength(1);
+
+    // 2. The native class node exists.
+    const nativeRows = db
+      .prepare("SELECT id, name FROM nodes WHERE kind='class' AND language='objc' AND name='MyViewView'")
+      .all();
+    expect(nativeRows).toHaveLength(1);
+
+    // 3. Fabric synthesizer bridges component → native class.
+    const bridgeRows = db
+      .prepare(
+        `SELECT s.name comp, t.name native FROM edges e
+         JOIN nodes s ON s.id=e.source JOIN nodes t ON t.id=e.target
+         WHERE json_extract(e.metadata,'$.synthesizedBy')='fabric-native-impl'
+           AND s.name='MyView' AND t.name='MyViewView'`
+      )
+      .all();
+    expect(bridgeRows).toHaveLength(1);
+
+    // 4. JSX synthesizer links the App function → the Fabric component
+    //    (jsx-render edge keyed on the tag name 'MyView').
+    const jsxRows = db
+      .prepare(
+        `SELECT s.name caller, t.name comp FROM edges e
+         JOIN nodes s ON s.id=e.source JOIN nodes t ON t.id=e.target
+         WHERE json_extract(e.metadata,'$.synthesizedBy')='jsx-render'
+           AND t.id LIKE 'fabric-component:%' AND t.name='MyView'`
+      )
+      .all();
+    cg.close?.();
+    expect(jsxRows.length).toBeGreaterThanOrEqual(1);
+    expect(jsxRows[0].caller).toBe('App');
+    // The full flow: App (TSX) → MyView (fabric-component) → MyViewView (ObjC native class)
+  });
+});
diff --git a/__tests__/foundation.test.ts b/__tests__/foundation.test.ts
index 4e8f204ae..05fa79804 100644
--- a/__tests__/foundation.test.ts
+++ b/__tests__/foundation.test.ts
@@ -9,9 +9,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { CodeGraph } from '../src';
-import { DEFAULT_CONFIG, Node, Edge } from '../src/types';
-import { loadConfig, saveConfig } from '../src/config';
-import { isInitialized, getCodeGraphDir, validateDirectory } from '../src/directory';
+import { Node, Edge } from '../src/types';
+import { isInitialized, getCodeGraphDir, validateDirectory, codeGraphDirName, isCodeGraphDataDir } from '../src/directory';
 import { DatabaseConnection, getDatabasePath } from '../src/db';
 
 // Create a temporary directory for each test
@@ -55,21 +54,10 @@ describe('CodeGraph Foundation', () => {
       expect(fs.existsSync(gitignorePath)).toBe(true);
 
       const content = fs.readFileSync(gitignorePath, 'utf-8');
-      expect(content).toContain('*.db');
-
-      cg.close();
-    });
-
-    it('should create config.json with defaults', () => {
-      const cg = CodeGraph.initSync(tempDir);
-
-      const configPath = path.join(getCodeGraphDir(tempDir), 'config.json');
-      expect(fs.existsSync(configPath)).toBe(true);
-
-      const config = cg.getConfig();
-      expect(config.version).toBe(DEFAULT_CONFIG.version);
-      expect(config.include).toEqual(DEFAULT_CONFIG.include);
-      expect(config.exclude).toEqual(DEFAULT_CONFIG.exclude);
+      // Ignore everything in .codegraph/ except this file itself, so transient
+      // files (db, daemon.pid, sockets, logs) never show up in git. (#492, #484)
+      expect(content).toContain('*');
+      expect(content).toContain('!.gitignore');
 
       cg.close();
     });
@@ -80,21 +68,6 @@ describe('CodeGraph Foundation', () => {
 
       expect(() => CodeGraph.initSync(tempDir)).toThrow(/already initialized/i);
     });
-
-    it('should accept custom config options', () => {
-      const cg = CodeGraph.initSync(tempDir, {
-        config: {
-          maxFileSize: 500000,
-          extractDocstrings: false,
-        },
-      });
-
-      const config = cg.getConfig();
-      expect(config.maxFileSize).toBe(500000);
-      expect(config.extractDocstrings).toBe(false);
-
-      cg.close();
-    });
   });
 
   describe('Opening Projects', () => {
@@ -112,17 +85,6 @@ describe('CodeGraph Foundation', () => {
     it('should throw if not initialized', () => {
       expect(() => CodeGraph.openSync(tempDir)).toThrow(/not initialized/i);
     });
-
-    it('should preserve configuration across open/close', () => {
-      const cg1 = CodeGraph.initSync(tempDir, {
-        config: { maxFileSize: 123456 },
-      });
-      cg1.close();
-
-      const cg2 = CodeGraph.openSync(tempDir);
-      expect(cg2.getConfig().maxFileSize).toBe(123456);
-      cg2.close();
-    });
   });
 
   describe('Static Methods', () => {
@@ -182,31 +144,6 @@ describe('CodeGraph Foundation', () => {
     });
   });
 
-  describe('Configuration', () => {
-    it('should load and merge config with defaults', () => {
-      const cg = CodeGraph.initSync(tempDir);
-      cg.close();
-
-      const config = loadConfig(tempDir);
-      expect(config.version).toBe(DEFAULT_CONFIG.version);
-      expect(config.rootDir).toBe(path.resolve(tempDir));
-    });
-
-    it('should update configuration', () => {
-      const cg = CodeGraph.initSync(tempDir);
-
-      cg.updateConfig({ maxFileSize: 999999 });
-
-      expect(cg.getConfig().maxFileSize).toBe(999999);
-
-      cg.close();
-
-      // Verify persistence
-      const config = loadConfig(tempDir);
-      expect(config.maxFileSize).toBe(999999);
-    });
-  });
-
   describe('Directory Management', () => {
     it('should validate directory structure', () => {
       const cg = CodeGraph.initSync(tempDir);
@@ -222,6 +159,46 @@ describe('CodeGraph Foundation', () => {
       expect(validation.valid).toBe(false);
       expect(validation.errors.length).toBeGreaterThan(0);
     });
+
+    it('upgrades a stale pre-wildcard .gitignore in place (issue #788)', () => {
+      const cg = CodeGraph.initSync(tempDir);
+      cg.close();
+
+      const gitignorePath = path.join(getCodeGraphDir(tempDir), '.gitignore');
+      // A .gitignore written by an older version (<= 0.9.9): an explicit
+      // allowlist that never ignored daemon.pid, so the daemon's runtime
+      // pidfile got committed.
+      const staleV099 =
+        '# CodeGraph data files\n' +
+        '# These are local to each machine and should not be committed\n\n' +
+        '# Database\n*.db\n*.db-wal\n*.db-shm\n\n' +
+        '# Cache\ncache/\n\n# Logs\n*.log\n\n# Hook markers\n.dirty\n';
+      fs.writeFileSync(gitignorePath, staleV099, 'utf-8');
+
+      // Opening the project runs validateDirectory, which self-heals.
+      const cg2 = CodeGraph.openSync(tempDir);
+      cg2.close();
+
+      const upgraded = fs.readFileSync(gitignorePath, 'utf-8');
+      expect(upgraded).toContain('\n*\n'); // wildcard ignores everything…
+      expect(upgraded).toContain('!.gitignore'); // …except this file
+      expect(upgraded).not.toContain('.dirty'); // old explicit list is gone
+    });
+
+    it('leaves a user-customized .codegraph/.gitignore untouched', () => {
+      const cg = CodeGraph.initSync(tempDir);
+      cg.close();
+
+      const gitignorePath = path.join(getCodeGraphDir(tempDir), '.gitignore');
+      // No CodeGraph header → user-authored → must not be rewritten.
+      const custom = '# my own rules\n*.db\n!keep-this.json\n';
+      fs.writeFileSync(gitignorePath, custom, 'utf-8');
+
+      const cg2 = CodeGraph.openSync(tempDir);
+      cg2.close();
+
+      expect(fs.readFileSync(gitignorePath, 'utf-8')).toBe(custom);
+    });
   });
 
   describe('Uninitialize', () => {
@@ -305,7 +282,7 @@ describe('Database Connection', () => {
 
     const version = db.getSchemaVersion();
     expect(version).not.toBeNull();
-    expect(version?.version).toBe(4);
+    expect(version?.version).toBe(5);
 
     db.close();
   });
@@ -369,3 +346,93 @@ describe('Query Builder', () => {
     expect(files).toEqual([]);
   });
 });
+
+// Two environments that share one working tree (Windows-native + WSL) must not
+// share one `.codegraph/`. CODEGRAPH_DIR overrides the data directory name so
+// each side keeps its own index in the same tree (issue #636).
+describe('CODEGRAPH_DIR override (#636)', () => {
+  const saved = process.env.CODEGRAPH_DIR;
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-dirname-'));
+  });
+  afterEach(() => {
+    if (saved === undefined) delete process.env.CODEGRAPH_DIR;
+    else process.env.CODEGRAPH_DIR = saved;
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('codeGraphDirName()', () => {
+    it('defaults to .codegraph when unset', () => {
+      delete process.env.CODEGRAPH_DIR;
+      expect(codeGraphDirName()).toBe('.codegraph');
+    });
+
+    it('honors a valid override', () => {
+      process.env.CODEGRAPH_DIR = '.codegraph-win';
+      expect(codeGraphDirName()).toBe('.codegraph-win');
+    });
+
+    // Anything that isn't a plain segment could escape the project root or
+    // clobber it, so it's ignored in favor of the default.
+    it.each(['foo/bar', 'a\\b', '..', '../x', '.', '/abs/path', '   ', ''])(
+      'falls back to .codegraph for invalid value %j',
+      (bad) => {
+        process.env.CODEGRAPH_DIR = bad;
+        expect(codeGraphDirName()).toBe('.codegraph');
+      }
+    );
+  });
+
+  describe('isCodeGraphDataDir()', () => {
+    it('matches the default, the active override, and .codegraph-* siblings', () => {
+      process.env.CODEGRAPH_DIR = '.codegraph-win';
+      expect(isCodeGraphDataDir('.codegraph')).toBe(true);       // the other env's dir
+      expect(isCodeGraphDataDir('.codegraph-win')).toBe(true);   // active override
+      expect(isCodeGraphDataDir('.codegraph-wsl')).toBe(true);   // any sibling
+    });
+
+    it('does not match unrelated directories', () => {
+      delete process.env.CODEGRAPH_DIR;
+      for (const name of ['src', 'node_modules', '.git', 'codegraph', '.codegraphextra']) {
+        expect(isCodeGraphDataDir(name)).toBe(false);
+      }
+    });
+  });
+
+  it('init writes the index under the overridden directory, not .codegraph', () => {
+    process.env.CODEGRAPH_DIR = '.codegraph-win';
+    const cg = CodeGraph.initSync(tempDir);
+    try {
+      expect(fs.existsSync(path.join(tempDir, '.codegraph-win', 'codegraph.db'))).toBe(true);
+      expect(fs.existsSync(path.join(tempDir, '.codegraph'))).toBe(false);
+      expect(getCodeGraphDir(tempDir)).toBe(path.join(tempDir, '.codegraph-win'));
+      expect(CodeGraph.isInitialized(tempDir)).toBe(true);
+    } finally {
+      cg.close();
+    }
+  });
+
+  it('two index dirs coexist in one tree and the override side skips the sibling', async () => {
+    // WSL side: default `.codegraph`, with a source file.
+    delete process.env.CODEGRAPH_DIR;
+    fs.writeFileSync(path.join(tempDir, 'app.ts'), 'export function onlyReal() {}\n');
+    const wsl = await CodeGraph.init(tempDir, { index: true });
+    wsl.close();
+
+    // Windows side: override dir, same tree. Plant a decoy source file INSIDE
+    // the WSL data dir — the override-side index must not pick it up.
+    process.env.CODEGRAPH_DIR = '.codegraph-win';
+    fs.writeFileSync(path.join(tempDir, '.codegraph', 'decoy.ts'), 'export function decoyLeak() {}\n');
+    const win = await CodeGraph.init(tempDir, { index: true });
+    try {
+      expect(fs.existsSync(path.join(tempDir, '.codegraph', 'codegraph.db'))).toBe(true);
+      expect(fs.existsSync(path.join(tempDir, '.codegraph-win', 'codegraph.db'))).toBe(true);
+      expect(win.searchNodes('onlyReal').length).toBeGreaterThan(0);
+      expect(win.searchNodes('decoyLeak')).toEqual([]); // sibling data dir not indexed
+    } finally {
+      win.close();
+    }
+  });
+});
diff --git a/__tests__/frameworks-integration.test.ts b/__tests__/frameworks-integration.test.ts
index b64e8c662..344a0f6c9 100644
--- a/__tests__/frameworks-integration.test.ts
+++ b/__tests__/frameworks-integration.test.ts
@@ -57,3 +57,854 @@ describe('Django end-to-end framework extraction', () => {
     cg.close();
   });
 });
+
+describe('Flask end-to-end framework extraction', () => {
+  let tmpDir: string | undefined;
+  afterEach(() => {
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  it('resolves stacked routes across @login_required to a view named after a builtin (index)', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-flask-'));
+    fs.writeFileSync(path.join(tmpDir, 'requirements.txt'), 'flask==3.0\n');
+    fs.writeFileSync(
+      path.join(tmpDir, 'app.py'),
+      'from flask import Blueprint, render_template\n' +
+        'from flask_login import login_required\n' +
+        'bp = Blueprint("main", __name__)\n' +
+        '\n' +
+        '@bp.route("/", methods=["GET", "POST"])\n' +
+        '@bp.route("/index", methods=["GET", "POST"])\n' +
+        '@login_required\n' +
+        'def index():\n' +
+        '    return render_template("index.html")\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    // Both stacked @bp.route decorators are extracted (the second was previously
+    // dropped because @login_required broke the "def must follow" assumption).
+    const routes = cg.getNodesByKind('route');
+    expect(routes.map((r) => r.name).sort()).toEqual(['GET /', 'GET /index']);
+
+    // The view function exists even though its name is a Python builtin method.
+    const fn = cg.getNodesByKind('function').find((n) => n.name === 'index');
+    expect(fn).toBeDefined();
+
+    // Both routes resolve to it — exercises the bare-name builtin guard, which
+    // previously filtered the `index` reference as a builtin method.
+    for (const route of routes) {
+      const edges = cg.getOutgoingEdges(route.id);
+      const toView = edges.find((e) => e.target === fn!.id && e.kind === 'references');
+      expect(toView, `route ${route.name} should resolve to index()`).toBeDefined();
+    }
+
+    cg.close();
+  });
+});
+
+describe('Flutter end-to-end — setState→build synthesis', () => {
+  let tmpDir: string | undefined;
+  afterEach(() => {
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  it('synthesizes a handler→build edge when a State method calls setState', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-flutter-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'main.dart'),
+      'import "package:flutter/material.dart";\n' +
+        'class CounterPage extends StatefulWidget {\n' +
+        '  @override\n' +
+        '  State<CounterPage> createState() => _CounterPageState();\n' +
+        '}\n' +
+        'class _CounterPageState extends State<CounterPage> {\n' +
+        '  int _count = 0;\n' +
+        '  void _increment() {\n' +
+        '    setState(() {\n' +
+        '      _count++;\n' +
+        '    });\n' +
+        '  }\n' +
+        '  @override\n' +
+        '  Widget build(BuildContext context) {\n' +
+        '    return Text("$_count");\n' +
+        '  }\n' +
+        '}\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    const methods = cg.getNodesByKind('method');
+    const increment = methods.find((n) => n.name === '_increment');
+    const build = methods.find((n) => n.name === 'build');
+    expect(increment).toBeDefined();
+    expect(build).toBeDefined();
+
+    // setState re-runs build (Flutter-internal, no static edge). The synthesizer
+    // bridges the handler → build so the "tap → setState → rebuilt UI" flow connects.
+    const edges = cg.getOutgoingEdges(increment!.id);
+    const toBuild = edges.find((e) => e.target === build!.id && e.kind === 'calls');
+    expect(toBuild, '_increment should reach build via setState synthesis').toBeDefined();
+
+    cg.close();
+  });
+});
+
+describe('C++ end-to-end — virtual override synthesis', () => {
+  let tmpDir: string | undefined;
+  afterEach(() => {
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  it('resolves callers through typed object pointers', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-cpp-'));
+    let cg: CodeGraph | undefined;
+    try {
+      fs.writeFileSync(
+        path.join(tmpDir, 'detect.hpp'),
+        'class CDetect {\n' +
+          ' public:\n' +
+          '  int Processing();\n' +
+          '};\n' +
+          'class CDetector {\n' +
+          ' private:\n' +
+          '  CDetect* m_cpAlg = nullptr;\n' +
+          ' public:\n' +
+          '  int Run();\n' +
+          '  int Flush();\n' +
+          '};\n'
+      );
+      fs.writeFileSync(
+        path.join(tmpDir, 'detect.cpp'),
+        '#include "detect.hpp"\n' +
+          'int CDetector::Run() { return m_cpAlg->Processing(); }\n' +
+          'int CDetector::Flush() { return m_cpAlg->Processing(); }\n' +
+          'int CDetect::Processing() { return 0; }\n'
+      );
+
+      cg = CodeGraph.initSync(tmpDir);
+      await cg.indexAll();
+
+      const processing = cg
+        .getNodesByKind('method')
+        .find((n) => n.qualifiedName.endsWith('CDetect::Processing'));
+      expect(processing).toBeDefined();
+
+      const callers = cg.getCallers(processing!.id).map((c) => c.node.qualifiedName);
+      expect(callers).toContain('CDetector::Run');
+      expect(callers).toContain('CDetector::Flush');
+
+      const runMethod = cg
+        .getNodesByKind('method')
+        .find((n) => n.qualifiedName.endsWith('CDetector::Run'));
+      expect(runMethod).toBeDefined();
+      const callees = cg.getCallees(runMethod!.id).map((c) => c.node.qualifiedName);
+      expect(callees).toContain('CDetect::Processing');
+    } finally {
+      cg?.close();
+    }
+  });
+
+  it('resolves typed pointer callers when the method name is ambiguous and the call sits inside a return/declaration', async () => {
+    // Regression: an earlier version of the C++ receiver-type inference matched
+    // the call line itself (`return m_cpAlg->Processing()`) and treated `return`
+    // as the type, OR grabbed `int r =` as a type from the prefix. With Strategy
+    // 3's "unique method name" fallback, the original issue example resolved
+    // anyway — but as soon as two classes share a method name (very common in
+    // real C++), both calls go unresolved.
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-cpp-'));
+    let cg: CodeGraph | undefined;
+    try {
+      fs.writeFileSync(
+        path.join(tmpDir, 'detect.hpp'),
+        'class CDetect { public: int Processing(); };\n' +
+          'class CWidget { public: int Processing(); };\n' +
+          'class CDetector {\n' +
+          ' private:\n' +
+          '  CDetect* m_cpAlg = nullptr;\n' +
+          ' public:\n' +
+          '  int RunReturn();\n' +
+          '  int RunAssign();\n' +
+          '};\n'
+      );
+      fs.writeFileSync(
+        path.join(tmpDir, 'detect.cpp'),
+        '#include "detect.hpp"\n' +
+          'int CDetector::RunReturn() { return m_cpAlg->Processing(); }\n' +
+          'int CDetector::RunAssign() { int r = m_cpAlg->Processing(); return r; }\n' +
+          'int CDetect::Processing() { return 0; }\n' +
+          'int CWidget::Processing() { return 0; }\n'
+      );
+
+      cg = CodeGraph.initSync(tmpDir);
+      await cg.indexAll();
+
+      const detectProc = cg
+        .getNodesByKind('method')
+        .find((n) => n.qualifiedName === 'CDetect::Processing');
+      const widgetProc = cg
+        .getNodesByKind('method')
+        .find((n) => n.qualifiedName === 'CWidget::Processing');
+      expect(detectProc).toBeDefined();
+      expect(widgetProc).toBeDefined();
+
+      const detectCallers = cg.getCallers(detectProc!.id).map((c) => c.node.qualifiedName);
+      expect(detectCallers).toContain('CDetector::RunReturn');
+      expect(detectCallers).toContain('CDetector::RunAssign');
+
+      // CWidget::Processing is never called — calls must NOT misroute here.
+      const widgetCallers = cg.getCallers(widgetProc!.id).map((c) => c.node.qualifiedName);
+      expect(widgetCallers).not.toContain('CDetector::RunReturn');
+      expect(widgetCallers).not.toContain('CDetector::RunAssign');
+    } finally {
+      cg?.close();
+    }
+  });
+
+  it('bridges a base virtual method to the subclass override', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-cpp-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'iter.cpp'),
+      'class Iterator {\n' +
+        ' public:\n' +
+        '  virtual void Next() { }\n' +
+        '};\n' +
+        'class DBIter : public Iterator {\n' +
+        ' public:\n' +
+        '  void Next() override { advance(); }\n' +
+        '  void advance() { }\n' +
+        '};\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    // Two methods named Next: the base virtual (lower line) and the override.
+    const nexts = cg
+      .getNodesByKind('method')
+      .filter((n) => n.name === 'Next')
+      .sort((a, b) => a.startLine - b.startLine);
+    expect(nexts.length).toBe(2);
+    const [baseNext, overrideNext] = nexts;
+
+    // A vtable call to Iterator::Next dispatches to DBIter::Next — bridge it so
+    // trace/callees from the interface method reaches the implementation.
+    const edge = cg
+      .getOutgoingEdges(baseNext!.id)
+      .find((e) => e.target === overrideNext!.id && e.kind === 'calls');
+    expect(edge, 'Iterator::Next should reach DBIter::Next via override synthesis').toBeDefined();
+
+    cg.close();
+  });
+});
+
+describe('Java end-to-end — field-injected bean trace (issue #389)', () => {
+  let tmpDir: string | undefined;
+  afterEach(() => {
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  // Mirrors the issue's Spring MVC pattern:
+  //   UserAction(@Resource UserBO userbo).toLogin2() -> this.userbo.toLogin2()
+  //     -> UserBO.toLogin2() -> userService.toLogin() -> UserService.toLogin (iface)
+  //     -> UserServiceImpl.toLogin() via interface→impl synthesis.
+  // Without the extractor `this.` strip + field-typed receiver lookup, the very
+  // first hop (controller -> bean) was missing entirely, breaking trace.
+  it('connects controller -> @Resource bean -> interface -> impl end-to-end', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-spring-bean-'));
+    const javaDir = path.join(tmpDir, 'src/main/java/com/example/user');
+    fs.mkdirSync(path.join(javaDir, 'action'), { recursive: true });
+    fs.mkdirSync(path.join(javaDir, 'bo'), { recursive: true });
+    fs.mkdirSync(path.join(javaDir, 'service'), { recursive: true });
+    fs.mkdirSync(path.join(javaDir, 'service/impl'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, 'pom.xml'),
+      '<project><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency></dependencies></project>\n'
+    );
+    fs.writeFileSync(
+      path.join(javaDir, 'action/UserAction.java'),
+      'package com.example.user.action;\n' +
+        'import com.example.user.bo.UserBO;\n' +
+        'import javax.annotation.Resource;\n' +
+        '@org.springframework.stereotype.Controller\n' +
+        'public class UserAction {\n' +
+        '  @Resource(name = "userBO") private UserBO userbo;\n' +
+        '  public void toLogin2() { this.userbo.toLogin2(); }\n' +
+        '}\n'
+    );
+    fs.writeFileSync(
+      path.join(javaDir, 'bo/UserBO.java'),
+      'package com.example.user.bo;\n' +
+        'import com.example.user.service.UserService;\n' +
+        'import javax.annotation.Resource;\n' +
+        '@org.springframework.stereotype.Component("userBO")\n' +
+        'public class UserBO {\n' +
+        '  @Resource private UserService userService;\n' +
+        '  public void toLogin2() { userService.toLogin(); }\n' +
+        '}\n'
+    );
+    fs.writeFileSync(
+      path.join(javaDir, 'service/UserService.java'),
+      'package com.example.user.service;\n' +
+        'public interface UserService { void toLogin(); }\n'
+    );
+    fs.writeFileSync(
+      path.join(javaDir, 'service/impl/UserServiceImpl.java'),
+      'package com.example.user.service.impl;\n' +
+        'import com.example.user.service.UserService;\n' +
+        '@org.springframework.stereotype.Service("userService")\n' +
+        'public class UserServiceImpl implements UserService {\n' +
+        '  public void toLogin() { }\n' +
+        '}\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    const methods = cg.getNodesByKind('method');
+    const find = (cls: string, name: string) =>
+      methods.find((m) => m.name === name && m.filePath.endsWith(`${cls}.java`));
+
+    const action = find('UserAction', 'toLogin2');
+    const bo = find('UserBO', 'toLogin2');
+    const svc = find('UserService', 'toLogin');
+    const impl = find('UserServiceImpl', 'toLogin');
+    expect(action).toBeDefined();
+    expect(bo).toBeDefined();
+    expect(svc).toBeDefined();
+    expect(impl).toBeDefined();
+
+    // UserAction.toLogin2 -> UserBO.toLogin2 (the regressed hop — `this.userbo`
+    // receiver was emitted verbatim and the field-type lookup didn't exist).
+    const actionToBo = cg.getOutgoingEdges(action!.id).find((e) => e.target === bo!.id);
+    expect(actionToBo, 'controller `this.userbo.toLogin2()` should reach UserBO.toLogin2').toBeDefined();
+    expect(actionToBo!.kind).toBe('calls');
+
+    // UserBO.toLogin2 -> UserService.toLogin (plain identifier receiver, works pre-fix).
+    const boToSvc = cg.getOutgoingEdges(bo!.id).find((e) => e.target === svc!.id);
+    expect(boToSvc).toBeDefined();
+
+    // UserService.toLogin -> UserServiceImpl.toLogin (interface->impl synth).
+    const svcToImpl = cg.getOutgoingEdges(svc!.id).find((e) => e.target === impl!.id);
+    expect(svcToImpl).toBeDefined();
+
+    cg.close();
+  });
+
+  it('bridges a Java mapper interface method to its MyBatis XML statement (incl. SQL fragments)', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-mybatis-'));
+    const javaDir = path.join(tmpDir, 'src/main/java/com/example/dao');
+    const xmlDir = path.join(tmpDir, 'src/main/resources/mappers');
+    fs.mkdirSync(javaDir, { recursive: true });
+    fs.mkdirSync(xmlDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, 'pom.xml'),
+      '<project><dependencies><dependency><groupId>org.mybatis</groupId><artifactId>mybatis</artifactId></dependency></dependencies></project>\n'
+    );
+    fs.writeFileSync(
+      path.join(javaDir, 'UserDAOMapper.java'),
+      'package com.example.dao;\n' +
+        'public interface UserDAOMapper {\n' +
+        '  Object getById(int id);\n' +
+        '  int updateUser(Object u);\n' +
+        '}\n'
+    );
+    fs.writeFileSync(
+      path.join(xmlDir, 'UserDAOMapper.xml'),
+      '<?xml version="1.0" encoding="UTF-8"?>\n' +
+        '<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">\n' +
+        '<mapper namespace="com.example.dao.UserDAOMapper">\n' +
+        '  <sql id="userCols">id, name, email</sql>\n' +
+        '  <select id="getById" parameterType="int" resultType="User">\n' +
+        '    SELECT <include refid="userCols"/> FROM users WHERE id = #{id}\n' +
+        '  </select>\n' +
+        '  <update id="updateUser" parameterType="User">\n' +
+        '    UPDATE users SET name=#{name}, email=#{email} WHERE id=#{id}\n' +
+        '  </update>\n' +
+        '</mapper>\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    const methods = cg.getNodesByKind('method');
+    const getByIdJava = methods.find((m) => m.name === 'getById' && m.language === 'java');
+    const getByIdXml = methods.find((m) => m.name === 'getById' && m.language === 'xml');
+    const updateJava = methods.find((m) => m.name === 'updateUser' && m.language === 'java');
+    const updateXml = methods.find((m) => m.name === 'updateUser' && m.language === 'xml');
+    const sqlFrag = methods.find((m) => m.name === 'userCols' && m.language === 'xml');
+    expect(getByIdJava).toBeDefined();
+    expect(getByIdXml).toBeDefined();
+    expect(updateJava).toBeDefined();
+    expect(updateXml).toBeDefined();
+    expect(sqlFrag).toBeDefined();
+
+    // XML statement qualified name must be `<namespace>::<id>` so the
+    // synthesizer can match against the Java method's `<Class>::<method>`
+    // suffix — this is the load-bearing contract between extractor + synthesis.
+    expect(getByIdXml!.qualifiedName).toBe('com.example.dao.UserDAOMapper::getById');
+
+    // Bridge: Java mapper method -> XML statement, kind 'calls'.
+    const j2xGet = cg.getOutgoingEdges(getByIdJava!.id).find((e) => e.target === getByIdXml!.id);
+    expect(j2xGet, 'Java getById should reach the XML <select id="getById">').toBeDefined();
+    expect(j2xGet!.kind).toBe('calls');
+    const j2xUpd = cg.getOutgoingEdges(updateJava!.id).find((e) => e.target === updateXml!.id);
+    expect(j2xUpd, 'Java updateUser should reach the XML <update id="updateUser">').toBeDefined();
+
+    // <include refid="userCols"/> inside <select> -> <sql id="userCols"> in same mapper.
+    const incEdge = cg.getOutgoingEdges(getByIdXml!.id).find((e) => e.target === sqlFrag!.id);
+    expect(incEdge, '<include refid="userCols"/> should reach the <sql> fragment').toBeDefined();
+
+    cg.close();
+  });
+
+  it('binds @Value / @ConfigurationProperties to YAML + .properties keys (incl. relaxed binding)', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-spring-config-'));
+    const javaDir = path.join(tmpDir, 'src/main/java/com/example');
+    const resDir = path.join(tmpDir, 'src/main/resources');
+    fs.mkdirSync(javaDir, { recursive: true });
+    fs.mkdirSync(resDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpDir, 'pom.xml'),
+      '<project><dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter</artifactId></dependency></dependencies></project>\n'
+    );
+    fs.writeFileSync(
+      path.join(resDir, 'application.yml'),
+      'app:\n' +
+        '  cache:\n' +
+        '    name:\n' +
+        '      user-token: "example-service:auth:token"\n' +
+        '    enabled: true\n' +
+        'db:\n' +
+        '  url: "jdbc:mysql://localhost/x"\n'
+    );
+    fs.writeFileSync(
+      path.join(resDir, 'application.properties'),
+      'app.retry-count=3\n'
+    );
+    fs.writeFileSync(
+      path.join(javaDir, 'CacheConfig.java'),
+      'package com.example;\n' +
+        'import org.springframework.beans.factory.annotation.Value;\n' +
+        'public class CacheConfig {\n' +
+        '  @Value("${app.cache.name.user-token}") private String tokenCacheName;\n' +
+        '  @Value("${app.cache.enabled:true}") private boolean enabled;\n' +
+        '  // relaxed binding: java camelCase, properties kebab-case\n' +
+        '  @Value("${app.retryCount}") private int retry;\n' +
+        '}\n'
+    );
+    fs.writeFileSync(
+      path.join(javaDir, 'CacheProperties.java'),
+      'package com.example;\n' +
+        'import org.springframework.boot.context.properties.ConfigurationProperties;\n' +
+        '@ConfigurationProperties(prefix = "app.cache")\n' +
+        'public class CacheProperties { private boolean enabled; }\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    // YAML/properties leaf keys: one constant node per dotted path.
+    const cfgKeys = cg
+      .getNodesByKind('constant')
+      .filter((n) => n.language === 'yaml' || n.language === 'properties');
+    const cfgByQn = (qn: string) => cfgKeys.find((n) => n.qualifiedName === qn);
+    expect(cfgByQn('app.cache.name.user-token')).toBeDefined();
+    expect(cfgByQn('app.cache.enabled')).toBeDefined();
+    expect(cfgByQn('db.url')).toBeDefined();
+    expect(cfgByQn('app.retry-count')).toBeDefined();
+
+    // @Value("${app.cache.name.user-token}") -> the YAML leaf key.
+    const valueBindings = cg
+      .getNodesByKind('constant')
+      .filter((n) => n.id.startsWith('spring-value:'));
+    const userToken = valueBindings.find((n) => n.name === 'app.cache.name.user-token');
+    expect(userToken).toBeDefined();
+    const userTokenEdges = cg.getOutgoingEdges(userToken!.id);
+    const userTokenTarget = userTokenEdges.find((e) =>
+      cfgKeys.some((c) => c.id === e.target && c.qualifiedName === 'app.cache.name.user-token'),
+    );
+    expect(userTokenTarget, '@Value should reference the YAML leaf key').toBeDefined();
+
+    // Default-value form `${k:default}` — strip the `:default` and bind the key.
+    const enabledBind = valueBindings.find((n) => n.name === 'app.cache.enabled');
+    expect(enabledBind).toBeDefined();
+    expect(cg.getOutgoingEdges(enabledBind!.id).some((e) => {
+      const t = cfgByQn('app.cache.enabled');
+      return t && e.target === t.id;
+    })).toBe(true);
+
+    // Relaxed binding: `app.retryCount` (camel) -> `app.retry-count` (kebab).
+    const retryBind = valueBindings.find((n) => n.name === 'app.retryCount');
+    expect(retryBind).toBeDefined();
+    expect(cg.getOutgoingEdges(retryBind!.id).some((e) => {
+      const t = cfgByQn('app.retry-count');
+      return t && e.target === t.id;
+    })).toBe(true);
+
+    // @ConfigurationProperties(prefix="app.cache") -> a key under that prefix.
+    const cpBindings = cg
+      .getNodesByKind('constant')
+      .filter((n) => n.id.startsWith('spring-cp:'));
+    const cpAppCache = cpBindings.find((n) => n.name === 'app.cache');
+    expect(cpAppCache).toBeDefined();
+    const cpEdges = cg.getOutgoingEdges(cpAppCache!.id);
+    expect(cpEdges.length).toBeGreaterThan(0);
+
+    cg.close();
+  });
+
+  it('emits only a file node for non-MyBatis XML (pom.xml, beans.xml, log4j.xml)', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-xml-non-mybatis-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'pom.xml'),
+      '<project><groupId>x</groupId><artifactId>y</artifactId></project>\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'log4j.xml'),
+      '<?xml version="1.0"?><Configuration><Loggers><Root level="info"/></Loggers></Configuration>\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+    // No method nodes — non-mapper XML produces no symbols (just file rows).
+    expect(cg.getNodesByKind('method').filter((n) => n.language === 'xml').length).toBe(0);
+    cg.close();
+  });
+
+  it('resolves a `this.field.method()` call to a unique implementation class', async () => {
+    // Standalone test of the extractor `this.` strip: even without Spring annotations,
+    // `this.svc.run()` where `svc` is typed as a concrete class should route to that
+    // class's method. This is the general Java fix, Spring is only one consumer.
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-java-this-field-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'App.java'),
+      'class Svc { public void run() { } }\n' +
+        'class App {\n' +
+        '  private Svc svc;\n' +
+        '  public void go() { this.svc.run(); }\n' +
+        '}\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    const methods = cg.getNodesByKind('method');
+    const go = methods.find((m) => m.name === 'go');
+    const run = methods.find((m) => m.name === 'run');
+    expect(go && run).toBeTruthy();
+
+    const edge = cg.getOutgoingEdges(go!.id).find((e) => e.target === run!.id);
+    expect(edge, '`this.svc.run()` should resolve to Svc.run').toBeDefined();
+
+    cg.close();
+  });
+});
+
+describe('JVM FQN imports — end-to-end', () => {
+  let tmpDir: string | undefined;
+  afterEach(() => {
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  it('resolves a Kotlin import when the file name differs from the class name', async () => {
+    // Bar lives in Models.kt — the filesystem-based Java-style path lookup
+    // (com/example/Bar.kt) misses this; only FQN-via-qualifiedName finds it.
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-jvm-imp-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'Models.kt'),
+      'package com.example\n\nclass Bar {\n  fun greet(): String = "hi"\n}\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'Caller.kt'),
+      'package com.example.app\n\nimport com.example.Bar\n\nclass App {\n  fun run() { Bar().greet() }\n}\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    const bar = cg.getNodesByKind('class').find((n) => n.qualifiedName === 'com.example::Bar');
+    expect(bar, 'Bar should be extracted with package-qualified name').toBeDefined();
+
+    const importNode = cg.getNodesByKind('import').find((n) => n.name === 'com.example.Bar');
+    expect(importNode, 'import statement node should exist').toBeDefined();
+
+    // The imports edge may originate from the import node OR from a parent
+    // scope (file / namespace) — accept either, but require that an
+    // imports-kind edge to Bar exists.
+    const reachesBar = cg
+      .getIncomingEdges(bar!.id)
+      .find((e) => e.kind === 'imports');
+    expect(reachesBar, 'an imports edge should resolve to Bar via FQN').toBeDefined();
+
+    cg.close();
+  });
+
+  it('resolves a Kotlin top-level function import', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-jvm-imp-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'Utils.kt'),
+      'package com.example\n\nfun util(): Int = 42\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'Caller.kt'),
+      'package com.example.app\n\nimport com.example.util\n\nfun main() { util() }\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    const util = cg.getNodesByKind('function').find((n) => n.qualifiedName === 'com.example::util');
+    expect(util, 'top-level util() should be extracted under com.example').toBeDefined();
+
+    const edge = cg.getIncomingEdges(util!.id).find((e) => e.kind === 'imports');
+    expect(edge, 'imports edge should reach the top-level function by FQN').toBeDefined();
+  });
+
+  it('resolves cross-language: Kotlin importing a Java class', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-jvm-imp-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'JavaBar.java'),
+      'package com.example;\n\npublic class JavaBar {\n  public String greet() { return "hi"; }\n}\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'Caller.kt'),
+      'package com.example.app\n\nimport com.example.JavaBar\n\nfun main() { JavaBar().greet() }\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    const javaBar = cg.getNodesByKind('class').find((n) => n.qualifiedName === 'com.example::JavaBar');
+    expect(javaBar, 'JavaBar should be extracted under com.example regardless of language').toBeDefined();
+
+    const edge = cg.getIncomingEdges(javaBar!.id).find((e) => e.kind === 'imports');
+    expect(edge, 'Kotlin caller should resolve its import to the Java class').toBeDefined();
+  });
+
+  it('disambiguates a class-name collision across packages', async () => {
+    // Two `Bar` classes in different packages — each importer should reach
+    // ITS Bar, not the other one. This is the central failure mode that
+    // name-matcher alone cannot disambiguate.
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-jvm-imp-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'AlphaBar.kt'),
+      'package com.example.alpha\n\nclass Bar { fun who() = "alpha" }\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'BetaBar.kt'),
+      'package com.example.beta\n\nclass Bar { fun who() = "beta" }\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'CallerA.kt'),
+      'package app\n\nimport com.example.alpha.Bar\n\nfun a() { Bar().who() }\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'CallerB.kt'),
+      'package app\n\nimport com.example.beta.Bar\n\nfun b() { Bar().who() }\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    const alphaBar = cg.getNodesByKind('class').find((n) => n.qualifiedName === 'com.example.alpha::Bar');
+    const betaBar = cg.getNodesByKind('class').find((n) => n.qualifiedName === 'com.example.beta::Bar');
+    expect(alphaBar).toBeDefined();
+    expect(betaBar).toBeDefined();
+    expect(alphaBar!.id).not.toBe(betaBar!.id);
+
+    // Each Bar receives exactly one imports edge — from its own caller.
+    const alphaIncoming = cg.getIncomingEdges(alphaBar!.id).filter((e) => e.kind === 'imports');
+    const betaIncoming = cg.getIncomingEdges(betaBar!.id).filter((e) => e.kind === 'imports');
+    expect(alphaIncoming.length).toBeGreaterThan(0);
+    expect(betaIncoming.length).toBeGreaterThan(0);
+
+    // Sanity: the edges don't cross — alpha's incoming sources don't include
+    // beta's filePath and vice versa.
+    const sourceFiles = (edges: typeof alphaIncoming) =>
+      edges.map((e) => cg.getNode(e.source)?.filePath).filter(Boolean);
+    expect(sourceFiles(alphaIncoming).some((p) => p?.includes('CallerA.kt'))).toBe(true);
+    expect(sourceFiles(betaIncoming).some((p) => p?.includes('CallerB.kt'))).toBe(true);
+  });
+});
+
+describe('Java anonymous-class override synthesis — end-to-end', () => {
+  let tmpDir: string | undefined;
+  afterEach(() => {
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  it('bridges an abstract base method to overrides inside `new Base() { ... }`', async () => {
+    // Mirrors guava Splitter: a factory returns `new BaseIter() {
+    // @Override int separatorStart(...) { ... } }`. Without anon-class
+    // extraction the override is invisible — Phase 5.5 interface-impl
+    // has no class to bridge — and an agent investigating `BaseIter.separatorStart`
+    // can't see its real implementation without reading the file.
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-anon-java-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'Splitter.java'),
+      'package com.example;\n' +
+        '\n' +
+        'abstract class BaseIter {\n' +
+        '  abstract int separatorStart(int start);\n' +
+        '}\n' +
+        '\n' +
+        'public class Splitter {\n' +
+        '  public BaseIter make() {\n' +
+        '    return new BaseIter() {\n' +
+        '      @Override\n' +
+        '      int separatorStart(int start) { return start + 1; }\n' +
+        '    };\n' +
+        '  }\n' +
+        '}\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    // The anon class is extracted and contains the override.
+    const anonClass = cg
+      .getNodesByKind('class')
+      .find((n) => /BaseIter\$anon@/.test(n.name));
+    expect(anonClass, 'anonymous BaseIter subclass should be a class node').toBeDefined();
+
+    const baseAbstract = cg
+      .getNodesByKind('method')
+      .find((n) => n.qualifiedName === 'com.example::BaseIter::separatorStart');
+    const anonOverride = cg
+      .getNodesByKind('method')
+      .find(
+        (n) =>
+          n.name === 'separatorStart' &&
+          n.qualifiedName.includes('$anon@') &&
+          n.qualifiedName.startsWith('com.example::Splitter::make::')
+      );
+    expect(baseAbstract, 'base abstract method should be in the graph').toBeDefined();
+    expect(anonOverride, 'anon-class override should be in the graph').toBeDefined();
+
+    // Phase 5.5 interface-impl: the abstract method has a synthesized
+    // `calls` edge to the anon override. Without this hop the agent
+    // would have to Read the file to discover the implementation.
+    const synthEdge = cg
+      .getOutgoingEdges(baseAbstract!.id)
+      .find((e) => e.target === anonOverride!.id && e.kind === 'calls');
+    expect(synthEdge, 'BaseIter.separatorStart should bridge to anon.separatorStart').toBeDefined();
+    expect(synthEdge!.provenance).toBe('heuristic');
+    expect((synthEdge!.metadata as { synthesizedBy?: string } | undefined)?.synthesizedBy).toBe(
+      'interface-impl'
+    );
+
+    cg.close();
+  });
+});
+
+describe('Go gRPC stub→impl synthesis', () => {
+  let tmpDir: string | undefined;
+  afterEach(() => {
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  it('bridges UnimplementedMsgServer methods to the hand-written keeper impl', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-go-grpc-'));
+    // Mimic protoc-gen-go-grpc output: `*_grpc.pb.go` carrying the
+    // UnimplementedMsgServer stub.
+    fs.writeFileSync(
+      path.join(tmpDir, 'tx_grpc.pb.go'),
+      'package banktypes\n\n' +
+        'type UnimplementedMsgServer struct{}\n\n' +
+        'func (UnimplementedMsgServer) Send(ctx context.Context, req *MsgSend) (*MsgSendResponse, error) { return nil, nil }\n' +
+        'func (UnimplementedMsgServer) MultiSend(ctx context.Context, req *MsgMultiSend) (*MsgMultiSendResponse, error) { return nil, nil }\n' +
+        'func (UnimplementedMsgServer) mustEmbedUnimplementedMsgServer() {}\n' +
+        'func (UnimplementedMsgServer) testEmbeddedByValue() {}\n'
+    );
+    // Hand-written impl in a non-generated file — what an agent actually
+    // wants the trace to land on.
+    fs.writeFileSync(
+      path.join(tmpDir, 'msg_server.go'),
+      'package keeper\n\n' +
+        'type msgServer struct{ k Keeper }\n\n' +
+        'func (m msgServer) Send(ctx context.Context, req *MsgSend) (*MsgSendResponse, error) {\n' +
+        '  return m.k.SendCoins(ctx, req.From, req.To, req.Amount)\n' +
+        '}\n' +
+        'func (m msgServer) MultiSend(ctx context.Context, req *MsgMultiSend) (*MsgMultiSendResponse, error) {\n' +
+        '  return nil, nil\n' +
+        '}\n'
+    );
+
+    let cg: CodeGraph | undefined;
+    try {
+      cg = CodeGraph.initSync(tmpDir);
+      await cg.indexAll();
+
+      const stubSend = cg
+        .getNodesByKind('method')
+        .find((n) => n.qualifiedName.endsWith('UnimplementedMsgServer::Send'));
+      const implSend = cg
+        .getNodesByKind('method')
+        .find((n) => n.qualifiedName.endsWith('msgServer::Send'));
+      expect(stubSend, 'UnimplementedMsgServer.Send should be indexed').toBeDefined();
+      expect(implSend, 'msgServer.Send should be indexed').toBeDefined();
+
+      const bridge = cg
+        .getOutgoingEdges(stubSend!.id)
+        .find((e) => e.target === implSend!.id && e.kind === 'calls');
+      expect(bridge, 'stub Send should bridge to impl Send').toBeDefined();
+      expect(bridge!.provenance).toBe('heuristic');
+      expect((bridge!.metadata as { synthesizedBy?: string } | undefined)?.synthesizedBy).toBe(
+        'go-grpc-stub-impl'
+      );
+    } finally {
+      cg?.close();
+    }
+  });
+
+  it('does not bridge to candidates living in another generated file', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-go-grpc-sib-'));
+    // `*_grpc.pb.go` also contains a sibling `msgClient` struct that
+    // happens to satisfy the same method set. We must NOT bridge to it —
+    // it's not the hand-written impl, just the gRPC client wrapper.
+    fs.writeFileSync(
+      path.join(tmpDir, 'tx_grpc.pb.go'),
+      'package banktypes\n\n' +
+        'type UnimplementedMsgServer struct{}\n' +
+        'func (UnimplementedMsgServer) Send() {}\n' +
+        'func (UnimplementedMsgServer) MultiSend() {}\n\n' +
+        'type msgClient struct{}\n' +
+        'func (m msgClient) Send() {}\n' +
+        'func (m msgClient) MultiSend() {}\n'
+    );
+
+    let cg: CodeGraph | undefined;
+    try {
+      cg = CodeGraph.initSync(tmpDir);
+      await cg.indexAll();
+
+      const stub = cg
+        .getNodesByKind('struct')
+        .find((n) => n.name === 'UnimplementedMsgServer');
+      expect(stub).toBeDefined();
+      const bridges = cg
+        .getNodesByKind('method')
+        .filter((n) => n.qualifiedName.endsWith('UnimplementedMsgServer::Send'))
+        .flatMap((stubSend) => cg!.getOutgoingEdges(stubSend.id))
+        .filter(
+          (e) =>
+            e.kind === 'calls' &&
+            (e.metadata as { synthesizedBy?: string } | undefined)?.synthesizedBy ===
+              'go-grpc-stub-impl',
+        );
+      expect(bridges, 'no bridge to msgClient (also generated)').toHaveLength(0);
+    } finally {
+      cg?.close();
+    }
+  });
+});
diff --git a/__tests__/frameworks.test.ts b/__tests__/frameworks.test.ts
index a5e5c56b3..ff1abb57b 100644
--- a/__tests__/frameworks.test.ts
+++ b/__tests__/frameworks.test.ts
@@ -123,6 +123,52 @@ def create_user(id):
     expect(nodes[0].name).toBe('POST /<id>');
     expect(references[0].referenceName).toBe('create_user');
   });
+
+  it('resolves the handler across an intervening decorator (@login_required)', () => {
+    const src = `
+@bp.route('/profile')
+@login_required
+def profile():
+    return render_template('profile.html')
+`;
+    const { nodes, references } = flaskResolver.extract!('routes.py', src);
+    expect(nodes[0].name).toBe('GET /profile');
+    expect(references[0].referenceName).toBe('profile');
+  });
+
+  it('extracts stacked @x.route decorators bound to one view', () => {
+    const src = `
+@bp.route('/', methods=['GET', 'POST'])
+@bp.route('/index', methods=['GET', 'POST'])
+@login_required
+def index():
+    return render_template('index.html')
+`;
+    const { nodes, references } = flaskResolver.extract!('routes.py', src);
+    expect(nodes.map((n) => n.name)).toEqual(['GET /', 'GET /index']);
+    expect(references.map((r) => r.referenceName)).toEqual(['index', 'index']);
+  });
+
+  it('extracts the method from a tuple methods=(...) (not just a list)', () => {
+    const src = `
+@blueprint.route('/api/articles', methods=('POST',))
+def make_article():
+    pass
+`;
+    const { nodes, references } = flaskResolver.extract!('views.py', src);
+    expect(nodes[0].name).toBe('POST /api/articles');
+    expect(references[0].referenceName).toBe('make_article');
+  });
+
+  it('extracts Flask-RESTful api.add_resource(Resource, paths) → the Resource class', () => {
+    const src = `
+api.add_resource(TodoResource, '/todos/<id>')
+api.add_org_resource(AlertResource, '/api/alerts/<id>', endpoint='alert')
+`;
+    const { nodes, references } = flaskResolver.extract!('api.py', src);
+    expect(nodes.map((n) => n.name)).toEqual(['ANY /todos/<id>', 'ANY /api/alerts/<id>']);
+    expect(references.map((r) => r.referenceName)).toEqual(['TodoResource', 'AlertResource']);
+  });
 });
 
 describe('fastapiResolver.extract', () => {
@@ -147,6 +193,32 @@ def create_item(item: Item):
     expect(nodes[0].name).toBe('POST /items');
     expect(references[0].referenceName).toBe('create_item');
   });
+
+  it('extracts a route mounted at the router/prefix root (empty path)', () => {
+    const src = `
+@router.get("", response_model=ListOfArticles, name="articles:list")
+async def list_articles():
+    return []
+`;
+    const { nodes, references } = fastapiResolver.extract!('articles.py', src);
+    expect(nodes[0].name).toBe('GET /');
+    expect(references[0].referenceName).toBe('list_articles');
+  });
+
+  it('extracts a multi-line decorator with an empty path', () => {
+    const src = `
+@router.post(
+    "",
+    status_code=201,
+    response_model=ArticleInResponse,
+)
+async def create_article():
+    pass
+`;
+    const { nodes, references } = fastapiResolver.extract!('articles.py', src);
+    expect(nodes[0].name).toBe('POST /');
+    expect(references[0].referenceName).toBe('create_article');
+  });
 });
 
 import { expressResolver } from '../src/resolution/frameworks/express';
@@ -456,6 +528,271 @@ describe('nestjsResolver.resolve', () => {
   });
 });
 
+describe('nestjsResolver.postExtract — RouterModule', () => {
+  function mkClass(name: string, filePath: string, startLine: number, endLine: number): Node {
+    return {
+      id: `class:${filePath}:${startLine}:${name}`,
+      kind: 'class',
+      name,
+      qualifiedName: `${filePath}::${name}`,
+      filePath,
+      language: 'typescript',
+      startLine,
+      endLine,
+      startColumn: 0,
+      endColumn: 0,
+      updatedAt: 0,
+    };
+  }
+
+  function mkRoute(
+    filePath: string,
+    line: number,
+    method: string,
+    path: string,
+    nameOverride?: string
+  ): Node {
+    return {
+      id: `route:${filePath}:${line}:${method}:${path}`,
+      kind: 'route',
+      name: nameOverride ?? `${method} ${path}`,
+      qualifiedName: `${filePath}::${method}:${path}`,
+      filePath,
+      language: 'typescript',
+      startLine: line,
+      endLine: line,
+      startColumn: 0,
+      endColumn: 0,
+      updatedAt: 0,
+    };
+  }
+
+  function makeContext(opts: {
+    files?: Record<string, string>;
+    nodes?: Node[];
+  }) {
+    const files = opts.files ?? {};
+    const all = opts.nodes ?? [];
+    return {
+      getNodesInFile: (fp: string) => all.filter((n) => n.filePath === fp),
+      getNodesByName: (name: string) => all.filter((n) => n.name === name),
+      getNodesByQualifiedName: () => [],
+      getNodesByKind: (kind: Node['kind']) => all.filter((n) => n.kind === kind),
+      fileExists: (fp: string) => files[fp] !== undefined,
+      readFile: (fp: string) => files[fp] ?? null,
+      getProjectRoot: () => '/test',
+      getAllFiles: () => Object.keys(files),
+      getNodesByLowerName: () => [],
+      getImportMappings: () => [],
+    } as any;
+  }
+
+  it('prepends RouterModule prefix to a controller route (top-level register)', () => {
+    const ctx = makeContext({
+      files: {
+        'src/app.module.ts': `
+          @Module({
+            imports: [
+              RouterModule.register([
+                { path: 'admin', module: AdminModule },
+              ]),
+            ],
+          })
+          export class AppModule {}
+
+          @Module({ controllers: [AdminController] })
+          export class AdminModule {}
+        `,
+      },
+      nodes: [
+        mkClass('AdminController', 'src/admin/admin.controller.ts', 1, 10),
+        mkRoute('src/admin/admin.controller.ts', 3, 'GET', '/'),
+      ],
+    });
+
+    const updates = nestjsResolver.postExtract!(ctx);
+    expect(updates).toHaveLength(1);
+    expect(updates[0]!.name).toBe('GET /admin');
+    // id and qualifiedName must be preserved so existing route→handler edges
+    // stay intact and the pass remains idempotent on a second run.
+    expect(updates[0]!.id).toBe('route:src/admin/admin.controller.ts:3:GET:/');
+    expect(updates[0]!.qualifiedName).toBe('src/admin/admin.controller.ts::GET:/');
+  });
+
+  it('resolves nested children — the issue #459 example', () => {
+    const ctx = makeContext({
+      files: {
+        'src/app.module.ts': `
+          @Module({
+            imports: [
+              AdminModule,
+              UsersModule,
+              RouterModule.register([
+                {
+                  path: 'admin',
+                  module: AdminModule,
+                  children: [
+                    { path: 'users', module: UsersModule },
+                  ],
+                },
+              ]),
+            ],
+          })
+          export class AppModule {}
+        `,
+        'src/users/users.module.ts': `
+          @Module({ controllers: [UsersController] })
+          export class UsersModule {}
+        `,
+      },
+      nodes: [
+        mkClass('UsersController', 'src/users/users.controller.ts', 1, 10),
+        mkRoute('src/users/users.controller.ts', 3, 'GET', '/'),
+      ],
+    });
+
+    const updates = nestjsResolver.postExtract!(ctx);
+    expect(updates).toHaveLength(1);
+    expect(updates[0]!.name).toBe('GET /admin/users');
+  });
+
+  it('joins module prefix with a non-empty @Controller path and method params', () => {
+    const ctx = makeContext({
+      files: {
+        'src/app.module.ts': `
+          RouterModule.register([{ path: 'admin', module: UsersModule }])
+
+          @Module({ controllers: [UsersController] })
+          export class UsersModule {}
+        `,
+      },
+      nodes: [
+        mkClass('UsersController', 'src/users.controller.ts', 1, 10),
+        // Existing extract emitted GET /users/:id from @Controller('users') + @Get(':id')
+        mkRoute('src/users.controller.ts', 3, 'GET', '/users/:id'),
+      ],
+    });
+
+    const updates = nestjsResolver.postExtract!(ctx);
+    expect(updates).toHaveLength(1);
+    expect(updates[0]!.name).toBe('GET /admin/users/:id');
+  });
+
+  it('is idempotent — a second run returns no updates', () => {
+    // Simulate the state after one round of postExtract: name is already
+    // 'GET /admin', but qualifiedName still encodes the original 'GET:/'.
+    const ctx = makeContext({
+      files: {
+        'src/app.module.ts': `
+          RouterModule.register([{ path: 'admin', module: UsersModule }])
+          @Module({ controllers: [UsersController] })
+          export class UsersModule {}
+        `,
+      },
+      nodes: [
+        mkClass('UsersController', 'src/users.controller.ts', 1, 10),
+        mkRoute('src/users.controller.ts', 3, 'GET', '/', 'GET /admin'),
+      ],
+    });
+
+    const updates = nestjsResolver.postExtract!(ctx);
+    expect(updates).toHaveLength(0);
+  });
+
+  it('is a no-op when the project does not use RouterModule', () => {
+    const ctx = makeContext({
+      files: {
+        'src/app.module.ts': `
+          @Module({ controllers: [UsersController] })
+          export class AppModule {}
+        `,
+      },
+      nodes: [
+        mkClass('UsersController', 'src/users.controller.ts', 1, 10),
+        mkRoute('src/users.controller.ts', 3, 'GET', '/'),
+      ],
+    });
+
+    const updates = nestjsResolver.postExtract!(ctx);
+    expect(updates).toHaveLength(0);
+  });
+
+  it('attributes routes to the right controller when one file has two', () => {
+    // Two controllers in one file, declared in two different modules with
+    // two different module prefixes. The route's startLine has to match the
+    // class scope, not just the file path.
+    const ctx = makeContext({
+      files: {
+        'src/app.module.ts': `
+          RouterModule.register([
+            { path: 'p1', module: AModule },
+            { path: 'p2', module: BModule },
+          ])
+          @Module({ controllers: [AController] }) export class AModule {}
+          @Module({ controllers: [BController] }) export class BModule {}
+        `,
+      },
+      nodes: [
+        mkClass('AController', 'src/multi.controller.ts', 1, 5),
+        mkClass('BController', 'src/multi.controller.ts', 7, 12),
+        mkRoute('src/multi.controller.ts', 3, 'GET', '/a/x'),
+        mkRoute('src/multi.controller.ts', 9, 'GET', '/b/y'),
+      ],
+    });
+
+    const updates = nestjsResolver.postExtract!(ctx);
+    expect(updates).toHaveLength(2);
+    const byId = new Map(updates.map((u) => [u.id, u.name]));
+    expect(byId.get('route:src/multi.controller.ts:3:GET:/a/x')).toBe('GET /p1/a/x');
+    expect(byId.get('route:src/multi.controller.ts:9:GET:/b/y')).toBe('GET /p2/b/y');
+  });
+
+  it('merges RouterModule registrations spread across multiple module files', () => {
+    const ctx = makeContext({
+      files: {
+        'src/app.module.ts': `
+          RouterModule.register([{ path: 'a', module: AModule }])
+          @Module({ controllers: [AController] }) export class AModule {}
+        `,
+        'src/feature.module.ts': `
+          RouterModule.forChild([{ path: 'b', module: BModule }])
+          @Module({ controllers: [BController] }) export class BModule {}
+        `,
+      },
+      nodes: [
+        mkClass('AController', 'src/a.controller.ts', 1, 5),
+        mkClass('BController', 'src/b.controller.ts', 1, 5),
+        mkRoute('src/a.controller.ts', 3, 'GET', '/'),
+        mkRoute('src/b.controller.ts', 3, 'GET', '/'),
+      ],
+    });
+
+    const updates = nestjsResolver.postExtract!(ctx);
+    expect(updates).toHaveLength(2);
+    const byId = new Map(updates.map((u) => [u.id, u.name]));
+    expect(byId.get('route:src/a.controller.ts:3:GET:/')).toBe('GET /a');
+    expect(byId.get('route:src/b.controller.ts:3:GET:/')).toBe('GET /b');
+  });
+
+  it('silently skips controllers whose class node is not in the graph', () => {
+    // RouterModule declares a prefix for a module, but the @Module that
+    // would link it to a controller is missing — common during partial
+    // re-extraction. Must not throw.
+    const ctx = makeContext({
+      files: {
+        'src/app.module.ts': `
+          RouterModule.register([{ path: 'orphans', module: GhostModule }])
+          @Module({ controllers: [GhostController] }) export class GhostModule {}
+        `,
+      },
+      nodes: [], // no class or route nodes
+    });
+
+    const updates = nestjsResolver.postExtract!(ctx);
+    expect(updates).toHaveLength(0);
+  });
+});
+
 import { laravelResolver } from '../src/resolution/frameworks/laravel';
 
 describe('laravelResolver.extract', () => {
@@ -463,13 +800,13 @@ describe('laravelResolver.extract', () => {
     const src = `Route::get('/users', [UserController::class, 'index']);\n`;
     const { nodes, references } = laravelResolver.extract!('routes/web.php', src);
     expect(nodes[0].name).toBe('GET /users');
-    expect(references[0].referenceName).toBe('index');
+    expect(references[0].referenceName).toBe('UserController@index');
   });
 
   it('extracts route with Controller@action syntax', () => {
     const src = `Route::post('/users', 'UserController@store');\n`;
     const { nodes, references } = laravelResolver.extract!('routes/web.php', src);
-    expect(references[0].referenceName).toBe('store');
+    expect(references[0].referenceName).toBe('UserController@store');
   });
 
   it('extracts resource route', () => {
@@ -487,13 +824,13 @@ describe('railsResolver.extract', () => {
     const src = `get '/users', to: 'users#index'\n`;
     const { nodes, references } = railsResolver.extract!('config/routes.rb', src);
     expect(nodes[0].name).toBe('GET /users');
-    expect(references[0].referenceName).toBe('index');
+    expect(references[0].referenceName).toBe('users#index');
   });
 
   it('extracts route without to: keyword', () => {
     const src = `post '/items' => 'items#create'\n`;
     const { nodes, references } = railsResolver.extract!('config/routes.rb', src);
-    expect(references[0].referenceName).toBe('create');
+    expect(references[0].referenceName).toBe('items#create');
   });
 });
 
@@ -511,6 +848,75 @@ public List<User> listUsers() {
     expect(nodes[0].name).toBe('GET /users');
     expect(references[0].referenceName).toBe('listUsers');
   });
+
+  it('extracts a Kotlin @GetMapping with a fun handler', () => {
+    const src = `
+@GetMapping("/vets")
+fun showVetList(model: MutableMap<String, Any>): String {
+  return "vets"
+}
+`;
+    const { nodes, references } = springResolver.extract!('VetController.kt', src);
+    expect(nodes[0].name).toBe('GET /vets');
+    expect(references[0].referenceName).toBe('showVetList');
+    expect(nodes[0].language).toBe('kotlin');
+  });
+
+  it('joins a Kotlin class @RequestMapping prefix and skips a stacked annotation', () => {
+    const src = `
+@RestController
+@RequestMapping("/owners")
+class OwnerController {
+  @GetMapping("/{ownerId}")
+  @ResponseBody
+  fun showOwner(@PathVariable ownerId: Int): String {
+    return "owner"
+  }
+}
+`;
+    const { nodes, references } = springResolver.extract!('OwnerController.kt', src);
+    expect(nodes[0].name).toBe('GET /owners/{ownerId}');
+    expect(references[0].referenceName).toBe('showOwner');
+  });
+});
+
+import { playResolver } from '../src/resolution/frameworks/play';
+import { isSourceFile, isPlayRoutesFile } from '../src/extraction/grammars';
+
+describe('playResolver.extract (conf/routes)', () => {
+  it('extracts METHOD /path Controller.action routes, dropping the package + args', () => {
+    const src = `# Routes
+GET     /                    controllers.Application.index
+GET     /computers           controllers.Application.list(p: Int ?= 0, s: Int ?= 2)
+POST    /computers           controllers.Application.save
+-> /v1/posts                 v1.post.PostRouter
+`;
+    const { nodes, references } = playResolver.extract!('conf/routes', src);
+    expect(nodes.map((n) => n.name)).toEqual([
+      'GET /',
+      'GET /computers',
+      'POST /computers',
+    ]); // the `->` include is skipped
+    expect(references.map((r) => r.referenceName)).toEqual([
+      'Application.index',
+      'Application.list',
+      'Application.save',
+    ]);
+  });
+
+  it('only runs on Play routes files', () => {
+    expect(playResolver.extract!('app/Foo.scala', 'GET / controllers.X.y').nodes).toHaveLength(0);
+  });
+});
+
+describe('Play routes file detection', () => {
+  it('recognizes conf/routes (extensionless) and *.routes as source files', () => {
+    expect(isPlayRoutesFile('conf/routes')).toBe(true);
+    expect(isPlayRoutesFile('myapp/conf/routes')).toBe(true);
+    expect(isPlayRoutesFile('conf/admin.routes')).toBe(true);
+    expect(isSourceFile('conf/routes')).toBe(true);
+    expect(isPlayRoutesFile('src/routes.ts')).toBe(false);
+  });
 });
 
 import { goResolver } from '../src/resolution/frameworks/go';
@@ -528,6 +934,14 @@ describe('goResolver.extract', () => {
     const { nodes, references } = goResolver.extract!('main.go', src);
     expect(references[0].referenceName).toBe('createItem');
   });
+
+  it('extracts gorilla/mux HandleFunc on a subrouter var, ignoring chained .Methods()', () => {
+    // `s` is a PathPrefix().Subrouter() var — any receiver is matched; the
+    // trailing .Methods("GET") doesn't break the handler capture.
+    const src = `s.HandleFunc("/users/{id}", listUsers).Methods("GET")\n`;
+    const { references } = goResolver.extract!('routes.go', src);
+    expect(references[0].referenceName).toBe('listUsers');
+  });
 });
 
 import { rustResolver } from '../src/resolution/frameworks/rust';
@@ -539,6 +953,50 @@ describe('rustResolver.extract', () => {
     expect(nodes[0].name).toBe('GET /users');
     expect(references[0].referenceName).toBe('list_users');
   });
+
+  it('extracts every method from a chained axum .route (get().put())', () => {
+    const src = `let app = Router::new().route("/user", get(get_current_user).put(update_user));\n`;
+    const { nodes, references } = rustResolver.extract!('main.rs', src);
+    expect(nodes.map((n) => n.name)).toEqual(['GET /user', 'PUT /user']);
+    expect(references.map((r) => r.referenceName)).toEqual([
+      'get_current_user',
+      'update_user',
+    ]);
+  });
+
+  it('extracts a multi-line axum .route with a namespaced handler', () => {
+    const src = `
+let app = Router::new()
+    .route(
+        "/articles/feed",
+        get(listing::feed_articles),
+    );
+`;
+    const { nodes, references } = rustResolver.extract!('main.rs', src);
+    expect(nodes[0].name).toBe('GET /articles/feed');
+    expect(references[0].referenceName).toBe('feed_articles');
+  });
+
+  it('extracts actix web::resource().route(web::METHOD().to(handler))', () => {
+    const src = `App::new().service(web::resource("/user/{id}").route(web::get().to(get_user)))\n`;
+    const { nodes, references } = rustResolver.extract!('main.rs', src);
+    expect(nodes[0].name).toBe('GET /user/{id}');
+    expect(references[0].referenceName).toBe('get_user');
+  });
+
+  it('extracts actix web::resource("/").to(handler) (all methods)', () => {
+    const src = `App::new().service(web::resource("/").to(index))\n`;
+    const { nodes, references } = rustResolver.extract!('main.rs', src);
+    expect(nodes[0].name).toBe('ANY /');
+    expect(references[0].referenceName).toBe('index');
+  });
+
+  it('extracts actix App-level .route("/path", web::METHOD().to(handler))', () => {
+    const src = `App::new().route("/health", web::get().to(health_check))\n`;
+    const { nodes, references } = rustResolver.extract!('main.rs', src);
+    expect(nodes[0].name).toBe('GET /health');
+    expect(references[0].referenceName).toBe('health_check');
+  });
 });
 
 describe('rustResolver.resolve cargo workspace crates', () => {
@@ -871,22 +1329,95 @@ describe('vaporResolver.extract', () => {
   it('extracts route from app.get with use:', () => {
     const src = `app.get("users", use: listUsers)\n`;
     const { nodes, references } = vaporResolver.extract!('routes.swift', src);
-    expect(nodes[0].name).toBe('GET users');
+    expect(nodes[0].name).toBe('GET /users');
     expect(references[0].referenceName).toBe('listUsers');
   });
+
+  it('extracts grouped RouteCollection routes with the group prefix and no path arg', () => {
+    const src = `
+func boot(routes: RoutesBuilder) throws {
+    let todos = routes.grouped("todos")
+    todos.get(use: index)
+    todos.post(use: create)
+    todos.group(":todoID") { todo in
+        todo.delete(use: delete)
+    }
+}
+`;
+    const { nodes, references } = vaporResolver.extract!('TodoController.swift', src);
+    expect(nodes.map((n) => n.name).sort()).toEqual([
+      'DELETE /todos/:todoID',
+      'GET /todos',
+      'POST /todos',
+    ]);
+    expect(references.map((r) => r.referenceName).sort()).toEqual([
+      'create',
+      'delete',
+      'index',
+    ]);
+  });
+
+  it('handles use: self.handler and non-string path segments', () => {
+    const src = `router.get("users", User.parameter, "edit", use: self.editUserHandler)\n`;
+    const { nodes, references } = vaporResolver.extract!('UserController.swift', src);
+    expect(nodes[0].name).toBe('GET /users/edit');
+    expect(references[0].referenceName).toBe('editUserHandler');
+  });
+
+  it('ignores non-route .get calls that lack use: (e.g. Environment.get)', () => {
+    const src = `let host = Environment.get("DATABASE_HOST") ?? "localhost"\n`;
+    const { nodes } = vaporResolver.extract!('configure.swift', src);
+    expect(nodes).toHaveLength(0);
+  });
 });
 
 import { reactResolver } from '../src/resolution/frameworks/react';
 import { svelteResolver } from '../src/resolution/frameworks/svelte';
+import { astroResolver } from '../src/resolution/frameworks/astro';
 
-describe('reactResolver.extract (smoke)', () => {
-  it('returns { nodes, references } shape', () => {
+describe('reactResolver.extract — React Router', () => {
+  it('extracts a v6 <Route path element={<Comp/>}>', () => {
     const src = `<Route path="/users" element={<UsersPage/>}/>`;
-    const result = reactResolver.extract!('App.tsx', src);
-    expect(result).toHaveProperty('nodes');
-    expect(result).toHaveProperty('references');
-    expect(Array.isArray(result.nodes)).toBe(true);
-    expect(Array.isArray(result.references)).toBe(true);
+    const { nodes, references } = reactResolver.extract!('App.tsx', src);
+    const route = nodes.find((n) => n.kind === 'route');
+    expect(route?.name).toBe('/users');
+    expect(references[0]?.referenceName).toBe('UsersPage');
+  });
+
+  it('extracts a v5 <Route path component={Comp}> with attributes in any order', () => {
+    const src = `<Route exact path="/login" component={Login} />`;
+    const { nodes, references } = reactResolver.extract!('App.jsx', src);
+    const route = nodes.find((n) => n.kind === 'route');
+    expect(route?.name).toBe('/login');
+    expect(references[0]?.referenceName).toBe('Login');
+  });
+
+  it('does not treat the <Routes> container as a route', () => {
+    const src = `<Routes><Route path="/x" element={<X/>}/></Routes>`;
+    const routes = reactResolver.extract!('App.tsx', src).nodes.filter((n) => n.kind === 'route');
+    expect(routes).toHaveLength(1);
+    expect(routes[0]?.name).toBe('/x');
+  });
+
+  it('extracts createBrowserRouter object routes ({ path, element/Component })', () => {
+    const src = `const router = createBrowserRouter([
+      { path: "/dashboard", element: <Dashboard /> },
+      { path: "/login", Component: Login },
+    ]);`;
+    const { nodes, references } = reactResolver.extract!('router.tsx', src);
+    const routes = nodes.filter((n) => n.kind === 'route');
+    expect(routes.map((n) => n.name).sort()).toEqual(['/dashboard', '/login']);
+    expect(references.map((r) => r.referenceName).sort()).toEqual(['Dashboard', 'Login']);
+  });
+
+  it('does not treat config files or a nextjs-pages dir as Next.js routes', () => {
+    const cfg = reactResolver.extract!('apps/nextjs-pages/next.config.mjs', 'export default {}');
+    expect(cfg.nodes.filter((n) => n.kind === 'route')).toHaveLength(0);
+    const vite = reactResolver.extract!('src/pages/vite.config.ts', 'export default {}');
+    expect(vite.nodes.filter((n) => n.kind === 'route')).toHaveLength(0);
+    // a real page still works
+    const page = reactResolver.extract!('src/pages/about.tsx', 'export default function About(){return null}');
+    expect(page.nodes.filter((n) => n.kind === 'route').map((n) => n.name)).toEqual(['/about']);
   });
 });
 
@@ -898,6 +1429,77 @@ describe('svelteResolver.extract (smoke)', () => {
   });
 });
 
+describe('astroResolver.extract — src/pages file-based routing', () => {
+  const routeNames = (filePath: string): string[] =>
+    astroResolver.extract!(filePath, '').nodes.filter((n) => n.kind === 'route').map((n) => n.name);
+
+  it('maps index.astro to /', () => {
+    expect(routeNames('src/pages/index.astro')).toEqual(['/']);
+  });
+
+  it('maps nested index and plain pages', () => {
+    expect(routeNames('src/pages/blog/index.astro')).toEqual(['/blog']);
+    expect(routeNames('src/pages/about.astro')).toEqual(['/about']);
+  });
+
+  it('converts [param] and [...rest] syntax', () => {
+    expect(routeNames('src/pages/blog/[slug].astro')).toEqual(['/blog/:slug']);
+    expect(routeNames('src/pages/[...path].astro')).toEqual(['/*path']);
+  });
+
+  it('maps .ts endpoints under src/pages to routes', () => {
+    expect(routeNames('src/pages/api/posts.ts')).toEqual(['/api/posts']);
+    expect(routeNames('src/pages/rss.xml.js')).toEqual(['/rss.xml']);
+  });
+
+  it('excludes underscore-prefixed segments and config files', () => {
+    expect(routeNames('src/pages/_partial.astro')).toEqual([]);
+    expect(routeNames('src/pages/blog/_components/Card.astro')).toEqual([]);
+    expect(routeNames('src/pages/vite.config.ts')).toEqual([]);
+  });
+
+  it('ignores .astro files outside src/pages', () => {
+    expect(routeNames('src/components/Button.astro')).toEqual([]);
+    expect(routeNames('docs/pages/guide.astro')).toEqual([]);
+  });
+});
+
+describe('astroResolver.resolve — Astro global and virtual modules', () => {
+  const ctx = {} as never;
+  const baseRef = {
+    fromNodeId: 'component:a',
+    line: 1,
+    column: 0,
+    filePath: 'src/pages/index.astro',
+    language: 'astro',
+  };
+
+  it('claims Astro.* global references as framework-provided', () => {
+    const res = astroResolver.resolve(
+      { ...baseRef, referenceName: 'Astro.props', referenceKind: 'references' } as never,
+      ctx
+    );
+    expect(res?.resolvedBy).toBe('framework');
+    expect(res?.confidence).toBe(1.0);
+  });
+
+  it('claims astro:content virtual module imports', () => {
+    const res = astroResolver.resolve(
+      { ...baseRef, referenceName: 'astro:content', referenceKind: 'imports' } as never,
+      ctx
+    );
+    expect(res?.resolvedBy).toBe('framework');
+  });
+
+  it('leaves ordinary names alone', () => {
+    const res = astroResolver.resolve(
+      { ...baseRef, referenceName: 'astrolabe', referenceKind: 'calls' } as never,
+      { getNodesByName: () => [] } as never
+    );
+    expect(res).toBeNull();
+  });
+});
+
 // Regression tests: commented-out and docstring route examples must NOT
 // surface as phantom route nodes. These would have failed before the
 // strip-comments wiring (the regex would happily scan comments/docstrings).
@@ -969,7 +1571,7 @@ Route::get('/real', [RealController::class, 'index']);
 `;
     const { nodes, references } = laravelResolver.extract!('routes/web.php', src);
     expect(nodes.map((n) => n.name)).toEqual(['GET /real']);
-    expect(references.map((r) => r.referenceName)).toEqual(['index']);
+    expect(references.map((r) => r.referenceName)).toEqual(['RealController@index']);
   });
 
   it('rails: skips =begin/=end and # commented routes', () => {
@@ -982,7 +1584,7 @@ get '/real', to: 'real#index'
 `;
     const { nodes, references } = railsResolver.extract!('config/routes.rb', src);
     expect(nodes.map((n) => n.name)).toEqual(['GET /real']);
-    expect(references.map((r) => r.referenceName)).toEqual(['index']);
+    expect(references.map((r) => r.referenceName)).toEqual(['real#index']);
   });
 
   it('spring: skips // and /* */ commented @GetMapping', () => {
@@ -1046,7 +1648,7 @@ public IActionResult ListUsers() { return Ok(); }
 app.get("real", use: listUsers)
 `;
     const { nodes, references } = vaporResolver.extract!('routes.swift', src);
-    expect(nodes.map((n) => n.name)).toEqual(['GET real']);
+    expect(nodes.map((n) => n.name)).toEqual(['GET /real']);
     expect(references.map((r) => r.referenceName)).toEqual(['listUsers']);
   });
 
diff --git a/__tests__/function-ref.test.ts b/__tests__/function-ref.test.ts
new file mode 100644
index 000000000..993b68614
--- /dev/null
+++ b/__tests__/function-ref.test.ts
@@ -0,0 +1,790 @@
+/**
+ * Function-as-value capture tests (#756) — registration-linking for callbacks.
+ *
+ * A function name used as a VALUE (passed as an argument, assigned to a
+ * field/function pointer, placed in a struct/object initializer or function
+ * table) must produce a `references` edge from the registration site to the
+ * function, so `callers`/`impact` surface where a callback is wired up.
+ *
+ * Safety properties verified here, per the dynamic-dispatch discipline
+ * ("a wrong edge is worse than none"):
+ *  - decoy: an ambiguous cross-file name (no import, ≥2 definitions) → NO edge
+ *  - same-file priority: a same-file definition beats a same-named decoy
+ *  - kind filter: a class/variable passed as a value never gets a
+ *    function-ref edge
+ *  - self: a function passing itself → no self-loop
+ *  - drain: all resolvable function_ref rows leave unresolved_refs (no
+ *    batched-resolver runaway), and re-index is idempotent
+ */
+
+import { describe, it, expect, beforeAll, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { CodeGraph } from '../src';
+import type { Edge } from '../src/types';
+import { initGrammars, loadAllGrammars } from '../src/extraction/grammars';
+
+beforeAll(async () => {
+  await initGrammars();
+  await loadAllGrammars();
+});
+
+/** Incoming edges to `name`'s node that came from function-as-value capture. */
+function fnRefEdgesInto(cg: CodeGraph, name: string): Edge[] {
+  const targets = cg.getNodesByName(name);
+  const edges: Edge[] = [];
+  for (const t of targets) {
+    for (const e of cg.getIncomingEdges(t.id)) {
+      if (e.kind === 'references' && e.metadata?.fnRef === true) {
+        edges.push(e);
+      }
+    }
+  }
+  return edges;
+}
+
+/** Names of the source nodes of the given edges, sorted. */
+function sourceNames(cg: CodeGraph, edges: Edge[]): string[] {
+  const names: string[] = [];
+  for (const e of edges) {
+    const n = cg.getNode(e.source);
+    if (n) names.push(n.name);
+  }
+  return names.sort();
+}
+
+describe('Function-as-value capture (#756)', () => {
+  let tmpDir: string | undefined;
+  afterEach(() => {
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  it('C: registration sites produce references edges (the #756 scenario)', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-c-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'driver.c'),
+      [
+        'struct ops { void (*recv_cb)(int); void (*send_cb)(int); };',
+        'typedef void (*cb_t)(int);',
+        '',
+        'static void my_recv_cb(int x) { (void)x; }',
+        'static void my_send_cb(int x) { (void)x; }',
+        '',
+        'void register_handler(void (*cb)(int)) { cb(1); }',
+        '',
+        'void direct_caller(void) { my_recv_cb(5); }',
+        '',
+        'void arg_registrar(void) { register_handler(my_recv_cb); }',
+        'void addr_registrar(void) { register_handler(&my_recv_cb); }',
+        'void assign_registrar(struct ops *o) { o->recv_cb = my_recv_cb; }',
+        '',
+        'static struct ops global_ops = { .recv_cb = my_recv_cb, .send_cb = my_send_cb };',
+        'static cb_t cb_table[] = { my_recv_cb, my_send_cb };',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+
+      const intoRecv = fnRefEdgesInto(cg, 'my_recv_cb');
+      expect(sourceNames(cg, intoRecv)).toEqual([
+        'addr_registrar',
+        'arg_registrar',
+        'assign_registrar',
+        'driver.c', // file-scope: designated init + positional table (deduped per source)
+      ]);
+
+      // The direct call is still a `calls` edge — unchanged by this feature.
+      const recv = cg.getNodesByName('my_recv_cb')[0]!;
+      const callEdges = cg
+        .getIncomingEdges(recv.id)
+        .filter((e) => e.kind === 'calls');
+      expect(sourceNames(cg, callEdges)).toEqual(['direct_caller']);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('TypeScript: arg / object / array / member / assignment forms', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-ts-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'main.ts'),
+      [
+        'export function targetCb(x: number): void { console.log(x); }',
+        'function registerHandler(cb: (x: number) => void): void { cb(1); }',
+        '',
+        'export function argRegistrar(): void { registerHandler(targetCb); }',
+        'export function timerRegistrar(): void { setTimeout(targetCb, 100); }',
+        'export function objRegistrar(): unknown { return { recv: targetCb }; }',
+        'export function arrRegistrar(): unknown { return [targetCb]; }',
+        '',
+        'class Emitter { cb: ((x: number) => void) | null = null; }',
+        'export function assignRegistrar(e: Emitter): void { e.cb = targetCb; }',
+        '',
+        'interface Btn { on(ev: string, cb: () => void): void; }',
+        'export class Comp {',
+        '  handleClick(): void {}',
+        '  wire(btn: Btn): void { btn.on("click", this.handleClick); }',
+        '}',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+
+      expect(sourceNames(cg, fnRefEdgesInto(cg, 'targetCb'))).toEqual([
+        'argRegistrar',
+        'arrRegistrar',
+        'assignRegistrar',
+        'objRegistrar',
+        'timerRegistrar',
+      ]);
+      // `this.handleClick` resolves class-scoped (#808): the target must be a
+      // method of the ENCLOSING class, in the same file.
+      expect(sourceNames(cg, fnRefEdgesInto(cg, 'handleClick'))).toEqual(['wire']);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('resolves an imported callback across files via its import', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-import-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'handlers.ts'),
+      'export function onMessage(x: number): void { console.log(x); }\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'wiring.ts'),
+      [
+        "import { onMessage } from './handlers';",
+        'export function wire(bus: { on(cb: (x: number) => void): void }): void {',
+        '  bus.on(onMessage);',
+        '}',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      const edges = fnRefEdgesInto(cg, 'onMessage');
+      expect(sourceNames(cg, edges)).toContain('wire');
+      // The edge must target the handlers.ts definition.
+      const target = cg.getNode(edges[0]!.target);
+      expect(target?.filePath.endsWith('handlers.ts')).toBe(true);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('DECOY: ambiguous cross-file name without an import resolves to NO edge', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-decoy-'));
+    // Two same-named functions in different files…
+    fs.writeFileSync(path.join(tmpDir, 'a.ts'), 'export function process(x: number): void {}\n');
+    fs.writeFileSync(path.join(tmpDir, 'b.ts'), 'export function process(x: number): void {}\n');
+    // …and a registrar that names `process` WITHOUT importing it. The name
+    // still passes the extraction gate only if imported/defined here — it is
+    // neither, so this asserts the gate; even if it leaked through, the
+    // ambiguity rule (unique-only cross-file) must yield no edge.
+    fs.writeFileSync(
+      path.join(tmpDir, 'c.ts'),
+      'export function wire(bus: { on(cb: unknown): void }, process: unknown): void { bus.on(process); }\n'
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      const edges = fnRefEdgesInto(cg, 'process');
+      expect(sourceNames(cg, edges)).not.toContain('wire');
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('SAME-FILE PRIORITY: a same-file definition beats a same-named decoy elsewhere', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-samefile-'));
+    fs.writeFileSync(path.join(tmpDir, 'decoy.c'), 'void my_cb(int x) { (void)x; }\n');
+    fs.writeFileSync(
+      path.join(tmpDir, 'real.c'),
+      [
+        'static void my_cb(int x) { (void)x; }',
+        'void register_handler(void (*cb)(int)) { cb(1); }',
+        'void wire(void) { register_handler(my_cb); }',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      const wires = fnRefEdgesInto(cg, 'my_cb').filter((e) => {
+        const src = cg.getNode(e.source);
+        return src?.name === 'wire';
+      });
+      expect(wires).toHaveLength(1);
+      const target = cg.getNode(wires[0]!.target);
+      expect(target?.filePath.endsWith('real.c')).toBe(true);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('KIND FILTER: a class passed as a value gets no function-ref edge', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-kind-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'main.ts'),
+      [
+        'export class Strategy { run(): void {} }',
+        'export function consume(x: unknown): void { void x; }',
+        'export function wire(): void { consume(Strategy); }',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      const strategy = cg.getNodesByName('Strategy').find((n) => n.kind === 'class')!;
+      const fnRef = cg
+        .getIncomingEdges(strategy.id)
+        .filter((e) => e.metadata?.fnRef === true);
+      expect(fnRef).toHaveLength(0);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('SELF: a function registering itself produces no self-loop', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-self-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'main.ts'),
+      [
+        'declare function schedule(cb: () => void): void;',
+        'export function retry(): void { schedule(retry); }',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      const retry = cg.getNodesByName('retry')[0]!;
+      const selfLoops = cg
+        .getIncomingEdges(retry.id)
+        .filter((e) => e.source === retry.id && e.metadata?.fnRef === true);
+      expect(selfLoops).toHaveLength(0);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('C++: &Cls::method member pointers resolve scoped; bare ids are free-function-only', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-cpp-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'widget.cpp'),
+      [
+        'struct Widget {',
+        '  void on_click(int x);',
+        '};',
+        'void Widget::on_click(int x) { (void)x; }',
+        'struct Decoy {',
+        '  void on_click(int x);',
+        '};',
+        'void Decoy::on_click(int x) { (void)x; }',
+        'void free_cb(int x) { (void)x; }',
+        'void bare_fn(int x) { (void)x; }',
+        'void reg(void* p) { (void)p; }',
+        'void wire() {',
+        '  auto p = &Widget::on_click;', // qualified — must hit Widget, not Decoy
+        '  reg(p);',
+        '  reg(&free_cb);', // explicit address-of — captured
+        '  reg(bare_fn);', // bare id in args — NOT captured for C++ (addressOfOnly)
+        '}',
+        // A method named like a local: passing the LOCAL must not resolve to
+        // the method (cpp args accept only explicit & forms).
+        'struct Buf { char* out(); };',
+        'void copy_to(void* out_) { (void)out_; }',
+        'void caller(char* out) { copy_to(out); }',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+
+      // Qualified member pointer resolves to Widget::on_click specifically.
+      const onClicks = cg.getNodesByName('on_click');
+      const widgetOnClick = onClicks.find((n) => n.qualifiedName.includes('Widget'))!;
+      const decoyOnClick = onClicks.find((n) => n.qualifiedName.includes('Decoy'))!;
+      const intoWidget = cg
+        .getIncomingEdges(widgetOnClick.id)
+        .filter((e) => e.metadata?.fnRef === true);
+      expect(intoWidget).toHaveLength(1);
+      expect(cg.getNode(intoWidget[0]!.source)?.name).toBe('wire');
+      expect(
+        cg.getIncomingEdges(decoyOnClick.id).filter((e) => e.metadata?.fnRef === true)
+      ).toHaveLength(0);
+
+      // Explicit &fn resolves; bare identifier in C++ args does NOT (the
+      // generic-name collision class: fmt's `begin`/`out`/`size` params).
+      expect(sourceNames(cg, fnRefEdgesInto(cg, 'free_cb'))).toContain('wire');
+      expect(fnRefEdgesInto(cg, 'bare_fn')).toHaveLength(0);
+
+      // The local `out` param must NOT produce an edge to Buf::out.
+      const outMethod = cg.getNodesByName('out').find((n) => n.kind === 'method');
+      if (outMethod) {
+        expect(
+          cg.getIncomingEdges(outMethod.id).filter((e) => e.metadata?.fnRef === true)
+        ).toHaveLength(0);
+      }
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('Pascal: := event wiring, @addr and bare args', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-pas-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'main.pas'),
+      [
+        'unit Main;',
+        'interface',
+        'type',
+        '  TCallback = procedure(X: Integer);',
+        '  THolder = class',
+        '  public',
+        '    OnFire: TCallback;',
+        '    procedure Wire;',
+        '  end;',
+        'procedure TargetCb(X: Integer);',
+        'procedure RegisterHandler(Cb: TCallback);',
+        'procedure ArgRegistrar;',
+        'procedure AddrRegistrar;',
+        'implementation',
+        'procedure TargetCb(X: Integer);',
+        'begin',
+        '  WriteLn(X);',
+        'end;',
+        'procedure RegisterHandler(Cb: TCallback);',
+        'begin',
+        '  Cb(1);',
+        'end;',
+        'procedure ArgRegistrar;',
+        'begin',
+        '  RegisterHandler(TargetCb);',
+        'end;',
+        'procedure AddrRegistrar;',
+        'begin',
+        '  RegisterHandler(@TargetCb);',
+        'end;',
+        'procedure THolder.Wire;',
+        'begin',
+        '  OnFire := TargetCb;',
+        'end;',
+        'end.',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      expect(sourceNames(cg, fnRefEdgesInto(cg, 'TargetCb'))).toEqual([
+        'AddrRegistrar',
+        'ArgRegistrar',
+        'Wire',
+      ]);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('THIS-MEMBER SCOPING: this.X resolves only to the enclosing class, never elsewhere', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-thisx-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'main.ts'),
+      [
+        'declare const bus: { on(ev: string, cb: () => void): void };',
+        // Decoy: a same-named method on an UNRELATED class.
+        'export class Decoy { refresh(): void {} }',
+        'export class Panel {',
+        '  views: number[] = [];', // property (post-#808), shares no name
+        '  refresh(): void {}',
+        '  wire(): void {',
+        '    bus.on("update", this.refresh);', // → Panel::refresh, not Decoy::refresh
+        '    bus.on("data", this.views as never);', // property → NO edge
+        '    bus.on("gone", this.missing as never);', // unknown member → NO edge
+        '  }',
+        '}',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+
+      const refreshes = cg.getNodesByName('refresh');
+      const panelRefresh = refreshes.find((n) => n.qualifiedName.includes('Panel'))!;
+      const decoyRefresh = refreshes.find((n) => n.qualifiedName.includes('Decoy'))!;
+
+      const intoPanel = cg
+        .getIncomingEdges(panelRefresh.id)
+        .filter((e) => e.metadata?.fnRef === true);
+      expect(intoPanel).toHaveLength(1);
+      expect(cg.getNode(intoPanel[0]!.source)?.name).toBe('wire');
+      expect(
+        cg.getIncomingEdges(decoyRefresh.id).filter((e) => e.metadata?.fnRef === true)
+      ).toHaveLength(0);
+
+      // The property and the unknown member produce nothing.
+      const views = cg.getNodesByName('views').find((n) => n.kind === 'property');
+      if (views) {
+        expect(
+          cg.getIncomingEdges(views.id).filter((e) => e.metadata?.fnRef === true)
+        ).toHaveLength(0);
+      }
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('INHERITED this.X: resolves on a supertype via the second pass, never on unrelated classes', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-inherit-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'base.ts'),
+      'export class FormBase { handleSubmit(): void {} }\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'unrelated.ts'),
+      'export class Unrelated { handleSubmit(): void {} }\n'
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'login.ts'),
+      [
+        "import { FormBase } from './base';",
+        'declare const bus: { on(ev: string, cb: () => void): void };',
+        'export class LoginForm extends FormBase {',
+        '  wire(): void { bus.on("submit", this.handleSubmit); }',
+        '}',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      const handleSubmits = cg.getNodesByName('handleSubmit');
+      const baseM = handleSubmits.find((n) => n.qualifiedName.includes('FormBase'))!;
+      const unrelatedM = handleSubmits.find((n) => n.qualifiedName.includes('Unrelated'))!;
+
+      const intoBase = cg.getIncomingEdges(baseM.id).filter((e) => e.metadata?.fnRef === true);
+      expect(intoBase).toHaveLength(1);
+      expect(cg.getNode(intoBase[0]!.source)?.name).toBe('wire');
+      expect(
+        cg.getIncomingEdges(unrelatedM.id).filter((e) => e.metadata?.fnRef === true)
+      ).toHaveLength(0);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('JAVA: Type::method cross-file, this::/super:: scoped, variable:: yields nothing', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-java-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'Handlers.java'),
+      [
+        'package com.example;',
+        'public class Handlers {',
+        '    public static void onMessage(int x) { System.out.println(x); }',
+        '}',
+      ].join('\n')
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'BaseForm.java'),
+      ['package com.example;', 'public class BaseForm {', '    void baseHandler(int x) {}', '}'].join('\n')
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'Main.java'),
+      [
+        'package com.example;',
+        'import com.example.Handlers;',
+        'import java.util.function.IntConsumer;',
+        'public class Main extends BaseForm {',
+        '    static void registerHandler(IntConsumer cb) { cb.accept(1); }',
+        '    void run0() {}',
+        '    void crossFile() { registerHandler(Handlers::onMessage); }',
+        '    void thisRef() { registerHandler(this::run0); }',
+        '    void superRef() { registerHandler(super::baseHandler); }',
+        '    void varRef(Main m) { registerHandler(m::run0); }',
+        '}',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+
+      expect(sourceNames(cg, fnRefEdgesInto(cg, 'onMessage'))).toEqual(['crossFile']);
+      expect(sourceNames(cg, fnRefEdgesInto(cg, 'baseHandler'))).toEqual(['superRef']);
+      // this::run0 resolves class-scoped; m::run0 (variable receiver) must NOT
+      // add a second edge — exactly one source.
+      expect(sourceNames(cg, fnRefEdgesInto(cg, 'run0'))).toEqual(['thisRef']);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('KOTLIN: companion-object refs resolve cross-file without imports; decoy companion untouched', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-ktcomp-'));
+    // Same package, no imports — the Java/Kotlin reality the name gate can't
+    // see, which is why qualified `Type::member` candidates skip it.
+    fs.writeFileSync(
+      path.join(tmpDir, 'Handlers.kt'),
+      [
+        'class KtHandlers {',
+        '  companion object {',
+        '    fun handle(x: Int) {}',
+        '  }',
+        '}',
+        'class Decoy {',
+        '  companion object {',
+        '    fun handle(x: Int) {}',
+        '  }',
+        '}',
+      ].join('\n')
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'Wirer.kt'),
+      [
+        'fun register(cb: Any) {}',
+        'class Wirer {',
+        '  fun wire() { register(KtHandlers::handle) }',
+        '}',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      const handles = cg.getNodesByName('handle');
+      const target = handles.find((n) => n.qualifiedName.includes('KtHandlers'))!;
+      const decoy = handles.find((n) => n.qualifiedName.includes('Decoy'))!;
+      const into = cg.getIncomingEdges(target.id).filter((e) => e.metadata?.fnRef === true);
+      expect(into).toHaveLength(1);
+      expect(cg.getNode(into[0]!.source)?.name).toBe('wire');
+      expect(cg.getIncomingEdges(decoy.id).filter((e) => e.metadata?.fnRef === true)).toHaveLength(0);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('SWIFT SCOPING: bare ids hit only the enclosing type’s methods; top-level bare hits functions only', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-swiftscope-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'main.swift'),
+      [
+        'func register(_ cb: (Int) -> Void) { cb(1) }',
+        'class Monitor {',
+        '  func report(_ x: Int) {}',
+        '  func wire() { register(report) }', // implicit self → Monitor::report
+        '}',
+        'class Other {',
+        // `report` here is a PARAMETER; Monitor::report must not win.
+        '  func use(report: (Int) -> Void) { register(report) }',
+        '}',
+        'func topLevel() { register(report) }', // no implicit self → no method target
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      const edges = fnRefEdgesInto(cg, 'report');
+      expect(sourceNames(cg, edges)).toEqual(['wire']);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('C UNGATED TABLES: a command table names handlers defined in OTHER files (redis pattern)', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-ctable-'));
+    // Handler defined in its own file…
+    fs.writeFileSync(path.join(tmpDir, 't_string.c'), 'void getCommand(int c) { (void)c; }\n');
+    // …and registered in a table in ANOTHER file, with no import mechanism (C).
+    fs.writeFileSync(
+      path.join(tmpDir, 'server.c'),
+      [
+        'struct cmd { const char *name; void (*proc)(int); };',
+        'static struct cmd commandTable[] = {',
+        '  { "get", getCommand },',
+        '};',
+      ].join('\n')
+    );
+    // Ambiguity safety: two files define dupCmd; a third table references it →
+    // NO edge (unique-or-drop).
+    fs.writeFileSync(path.join(tmpDir, 'dup_a.c'), 'void dupCmd(int c) { (void)c; }\n');
+    fs.writeFileSync(path.join(tmpDir, 'dup_b.c'), 'void dupCmd(int c) { (void)c; }\n');
+    fs.writeFileSync(
+      path.join(tmpDir, 'other.c'),
+      [
+        'struct cmd2 { void (*proc)(int); };',
+        'static struct cmd2 otherTable[] = { { dupCmd } };',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+
+      // Cross-file unique handler resolves from the table's file.
+      const intoGet = fnRefEdgesInto(cg, 'getCommand');
+      expect(sourceNames(cg, intoGet)).toEqual(['server.c']);
+      const target = cg.getNode(intoGet[0]!.target);
+      expect(target?.filePath.endsWith('t_string.c')).toBe(true);
+
+      // Ambiguous handler resolves to NOTHING — silent beats wrong.
+      expect(fnRefEdgesInto(cg, 'dupCmd')).toHaveLength(0);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('PHP: HOF string callables, [$this,…] and [Cls::class,…] arrays; non-HOF strings ignored', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-php-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'handlers.php'),
+      "<?php\nfunction cmp_items($a, $b) { return $a <=> $b; }\n"
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'main.php'),
+      [
+        '<?php',
+        'class Saver {',
+        '    public function onSave($x) {}',
+        '    public function wire() {',
+        "        register_shutdown_function([$this, 'onSave']);",
+        '    }',
+        '}',
+        'class Loader {',
+        '    public static function load($cls) {}',
+        '}',
+        'function sorter($items) {',
+        "    usort($items, 'cmp_items');", // known HOF, cross-file string → edge
+        "    spl_autoload_register([Loader::class, 'load']);",
+        "    some_random_fn('cmp_items');", // NOT a known HOF → no edge
+        '    return $items;',
+        '}',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      // Exactly ONE source for cmp_items: the usort site, not some_random_fn.
+      expect(sourceNames(cg, fnRefEdgesInto(cg, 'cmp_items'))).toEqual(['sorter']);
+      expect(sourceNames(cg, fnRefEdgesInto(cg, 'onSave'))).toEqual(['wire']);
+      expect(sourceNames(cg, fnRefEdgesInto(cg, 'load'))).toEqual(['sorter']);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('RUBY HOOKS: before_action/rescue_from symbols resolve class-scoped incl. inherited; validates is excluded', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-rubyhooks-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'posts_controller.rb'),
+      [
+        'class ApplicationController',
+        '  def authenticate; end',
+        'end',
+        '',
+        'class PostsController < ApplicationController',
+        '  before_action :authenticate', // inherited → ApplicationController
+        '  after_save :reindex',
+        '  validates :title, presence: true', // attributes, NOT methods → no edge
+        '  rescue_from StandardError, with: :render_500',
+        '',
+        '  def reindex; end',
+        '  def render_500; end',
+        '  def title; end',
+        'end',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+
+      const auth = fnRefEdgesInto(cg, 'authenticate');
+      expect(auth).toHaveLength(1);
+      expect(cg.getNode(auth[0]!.target)?.qualifiedName).toContain('ApplicationController');
+
+      expect(fnRefEdgesInto(cg, 'reindex')).toHaveLength(1);
+      expect(fnRefEdgesInto(cg, 'render_500')).toHaveLength(1);
+      // `validates :title` names an attribute — the same-named METHOD must
+      // get no registration edge.
+      expect(fnRefEdgesInto(cg, 'title')).toHaveLength(0);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('DRAIN: resolvable function_ref rows leave unresolved_refs; re-index is stable', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fnref-drain-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'main.c'),
+      [
+        'static void cb_a(int x) { (void)x; }',
+        'void reg(void (*cb)(int)) { cb(1); }',
+        'void wire(void) { reg(cb_a); }',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      const stats1 = cg.getStats();
+
+      // No function_ref rows may linger for resolvable names — the batched
+      // resolver must have drained them (delete keyed on the ORIGINAL stored
+      // ref; the #760 runaway came from violating that).
+      const db = (cg as unknown as { db: { prepare(sql: string): { all(): unknown[] } } }).db;
+      let leftover: unknown[] = [];
+      try {
+        leftover = db
+          .prepare("SELECT * FROM unresolved_refs WHERE reference_kind = 'function_ref'")
+          .all();
+      } catch {
+        // If internals aren't reachable this guard is covered by the edge
+        // assertions below.
+      }
+      expect(leftover).toHaveLength(0);
+
+      // Re-index: identical node/edge counts (idempotent, no accumulation).
+      await cg.indexAll();
+      const stats2 = cg.getStats();
+      expect(stats2.totalNodes).toBe(stats1.totalNodes);
+      expect(stats2.totalEdges).toBe(stats1.totalEdges);
+
+      expect(sourceNames(cg, fnRefEdgesInto(cg, 'cb_a'))).toEqual(['wire']);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+});
diff --git a/__tests__/generated-detection.test.ts b/__tests__/generated-detection.test.ts
new file mode 100644
index 000000000..90bbae7f1
--- /dev/null
+++ b/__tests__/generated-detection.test.ts
@@ -0,0 +1,47 @@
+/**
+ * Regression coverage for the generated-file detector that drives
+ * symbol-disambiguation down-ranking. Locked here because the suffix
+ * list is a contract: if a future edit drops `.pb.go`, the cosmos-sdk
+ * trace endpoint regresses to the gRPC stub (see
+ * `project_go_multi_module_audit` memory + the audit in #N/A).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { isGeneratedFile } from '../src/extraction/generated-detection';
+
+describe('isGeneratedFile', () => {
+  it('classifies Go protobuf / gRPC / pulsar / mock outputs as generated', () => {
+    expect(isGeneratedFile('api/cosmos/bank/v1beta1/tx_grpc.pb.go')).toBe(true);
+    expect(isGeneratedFile('x/bank/types/tx.pb.go')).toBe(true);
+    expect(isGeneratedFile('api/cosmos/bank/v1beta1/tx.pulsar.go')).toBe(true);
+    // cosmos-sdk uses `<base>_mocks.go`; mockgen's default is `mock_<src>.go`;
+    // many projects use `<base>_mock.go`. All three are mockgen output.
+    expect(isGeneratedFile('x/auth/testutil/expected_keepers_mocks.go')).toBe(true);
+    expect(isGeneratedFile('internal/foo_mock.go')).toBe(true);
+    expect(isGeneratedFile('mock_keeper.go')).toBe(true);
+  });
+
+  it('does not flag the hand-written keeper as generated', () => {
+    expect(isGeneratedFile('x/bank/keeper/msg_server.go')).toBe(false);
+    expect(isGeneratedFile('x/bank/keeper/send.go')).toBe(false);
+  });
+
+  it('catches common cross-language codegen suffixes', () => {
+    expect(isGeneratedFile('app/foo.generated.ts')).toBe(true);
+    expect(isGeneratedFile('app/foo.generated.tsx')).toBe(true);
+    expect(isGeneratedFile('proto/bar_pb2.py')).toBe(true);
+    expect(isGeneratedFile('proto/bar_pb2_grpc.py')).toBe(true);
+    expect(isGeneratedFile('lib/baz.pb.cc')).toBe(true);
+    expect(isGeneratedFile('lib/baz.pb.h')).toBe(true);
+    expect(isGeneratedFile('lib/quux.g.dart')).toBe(true);
+    expect(isGeneratedFile('lib/quux.freezed.dart')).toBe(true);
+  });
+
+  it('leaves ordinary source files alone', () => {
+    expect(isGeneratedFile('src/index.ts')).toBe(false);
+    expect(isGeneratedFile('src/components/Foo.tsx')).toBe(false);
+    expect(isGeneratedFile('lib/main.dart')).toBe(false);
+    expect(isGeneratedFile('cmd/server/main.go')).toBe(false);
+    expect(isGeneratedFile('app/db.py')).toBe(false);
+  });
+});
diff --git a/__tests__/gin-middleware-chain.test.ts b/__tests__/gin-middleware-chain.test.ts
new file mode 100644
index 000000000..b3f0ae061
--- /dev/null
+++ b/__tests__/gin-middleware-chain.test.ts
@@ -0,0 +1,113 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { CodeGraph } from '../src';
+
+/**
+ * End-to-end synthesizer test for the gin middleware chain.
+ *
+ * `(*Context).Next` runs the handler chain by slice index
+ * (`c.handlers[c.index](c)`) — a computed dispatch tree-sitter can't resolve, so
+ * `callees(Next)` would otherwise dead-end at the `len()` helper. Handlers are
+ * registered via `.Use(...)` / `.GET("/path", h)`. Verify the synthesizer links
+ * `Next` → each registered NAMED HandlerFunc, captures the wiring site, and
+ * skips inline (anonymous) closures.
+ */
+describe('gin middleware-chain synthesizer', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gin-chain-fixture-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('links Context.Next to handlers registered via Use/GET and skips inline closures', async () => {
+    fs.writeFileSync(path.join(dir, 'go.mod'), 'module ginapp\n\ngo 1.21\n');
+
+    // gin-core shape: the dynamic-dispatch chain driver + registration surface.
+    fs.writeFileSync(
+      path.join(dir, 'gin.go'),
+      `package gin
+
+type HandlerFunc func(*Context)
+type HandlersChain []HandlerFunc
+
+type Context struct {
+	handlers HandlersChain
+	index    int8
+}
+
+func (c *Context) Next() {
+	c.index++
+	for c.index < int8(len(c.handlers)) {
+		c.handlers[c.index](c)
+		c.index++
+	}
+}
+
+type Engine struct {
+	Handlers HandlersChain
+}
+
+func (e *Engine) Use(middleware ...HandlerFunc) {
+	e.Handlers = append(e.Handlers, middleware...)
+}
+
+func (e *Engine) GET(path string, handlers ...HandlerFunc) {}
+`
+    );
+
+    // registration site: named middleware + named route handler + an inline closure.
+    fs.writeFileSync(
+      path.join(dir, 'app.go'),
+      `package gin
+
+func Logger(c *Context)   {}
+func Recovery(c *Context) {}
+func getUser(c *Context)  {}
+
+func setup() {
+	e := &Engine{}
+	e.Use(Logger, Recovery)
+	e.GET("/users", getUser)
+	e.GET("/inline", func(c *Context) {})
+}
+`
+    );
+
+    const cg = await CodeGraph.init(dir, { silent: true });
+    await cg.indexAll();
+
+    const db = (cg as any).db.db;
+    const rows = db
+      .prepare(
+        `SELECT s.name source_name, s.kind source_kind, t.name target_name,
+                json_extract(e.metadata,'$.via') via,
+                json_extract(e.metadata,'$.registeredAt') registeredAt
+         FROM edges e
+         JOIN nodes s ON s.id = e.source
+         JOIN nodes t ON t.id = e.target
+         WHERE json_extract(e.metadata,'$.synthesizedBy') = 'gin-middleware-chain'`
+      )
+      .all();
+    cg.close?.();
+
+    // Every edge originates from the chain dispatcher Context.Next.
+    expect(rows.length).toBeGreaterThan(0);
+    expect(rows.every((r: any) => r.source_name === 'Next' && r.source_kind === 'method')).toBe(true);
+
+    // Exactly the three NAMED handlers are linked — the inline closure (4th
+    // registration) is anonymous and must be skipped.
+    const targets = new Set(rows.map((r: any) => r.target_name));
+    expect(targets).toEqual(new Set(['Logger', 'Recovery', 'getUser']));
+
+    // The wiring site (`.Use`/`.GET` call) is surfaced for the agent.
+    const logger = rows.find((r: any) => r.target_name === 'Logger');
+    expect(logger.via).toBe('Logger');
+    expect(logger.registeredAt).toMatch(/app\.go:\d+/);
+  });
+});
diff --git a/__tests__/graph.test.ts b/__tests__/graph.test.ts
index 7c771af0b..bc25942ac 100644
--- a/__tests__/graph.test.ts
+++ b/__tests__/graph.test.ts
@@ -293,6 +293,25 @@ export { main };
 
       expect(Array.isArray(callees)).toBe(true);
     });
+
+    it('treats class instantiation as a caller/callee of the class (#774)', () => {
+      // main() does `new DerivedClass(10, 'test')`. Constructing a class is
+      // calling its constructor, so main is a caller of DerivedClass and
+      // DerivedClass is a callee of main. Before #774 the `instantiates` edge
+      // was excluded from the caller/callee traversal, so `callers <Class>`
+      // returned the importing file (or nothing) and missed every
+      // construction site.
+      const derived = cg.getNodesByKind('class').find((n) => n.name === 'DerivedClass');
+      const main = cg.getNodesByKind('function').find((n) => n.name === 'main');
+      expect(derived).toBeDefined();
+      expect(main).toBeDefined();
+
+      const callerNames = cg.getCallers(derived!.id).map((c) => c.node.name);
+      expect(callerNames).toContain('main');
+
+      const calleeNames = cg.getCallees(main!.id).map((c) => c.node.name);
+      expect(calleeNames).toContain('DerivedClass');
+    });
   });
 
   describe('getImpactRadius()', () => {
@@ -309,6 +328,19 @@ export { main };
       expect(impact.nodes.size).toBeGreaterThan(0);
       expect(impact.nodes.has(formatValue.id)).toBe(true);
     });
+
+    it('does not drag in sibling members via the structural contains edge (#536)', () => {
+      const getName = cg.getNodesByKind('method').find((n) => n.name === 'getName');
+      const derived = cg.getNodesByKind('class').find((n) => n.name === 'DerivedClass');
+      expect(getName).toBeDefined();
+      expect(derived).toBeDefined();
+
+      const impact = cg.getImpactRadius(getName!.id, 3);
+      // The containing class must NOT be pulled into impact just because it
+      // *contains* getName — climbing that contains edge would re-expand every
+      // sibling method and explode impact for a leaf symbol. (#536)
+      expect(impact.nodes.has(derived!.id)).toBe(false);
+    });
   });
 
   describe('findPath()', () => {
@@ -375,16 +407,37 @@ export { main };
   });
 
   describe('File dependency analysis', () => {
-    it('should get file dependencies', () => {
+    // Regression: getFileDependents/getFileDependencies used to follow
+    // ONLY `imports` edges, which in this engine are same-file (a file → its
+    // own local import declarations). That made both return [] for EVERY file,
+    // so `codegraph affected` found no dependents on any language/framework.
+    // They must follow the cross-file symbol graph instead (calls / references
+    // / instantiates / extends / implements / ...).
+    it('reports cross-file dependencies via the symbol graph, not just imports', () => {
       const deps = cg.getFileDependencies('src/main.ts');
+      // main() instantiates DerivedClass (derived.ts) and calls
+      // processValue/doubleValue (utils.ts) — both are real dependencies.
+      expect(deps).toContain('src/utils.ts');
+      expect(deps).toContain('src/derived.ts');
+    });
 
-      expect(Array.isArray(deps)).toBe(true);
+    it('reports cross-file dependents via the symbol graph, not just imports', () => {
+      // utils.ts is used by main.ts (processValue/doubleValue calls); the old
+      // imports-only implementation returned [] here.
+      expect(cg.getFileDependents('src/utils.ts')).toContain('src/main.ts');
     });
 
-    it('should get file dependents', () => {
-      const dependents = cg.getFileDependents('src/utils.ts');
+    it('counts extends/implements as a dependency edge', () => {
+      // derived.ts extends BaseClass / implements Printable, both in base.ts.
+      expect(cg.getFileDependencies('src/derived.ts')).toContain('src/base.ts');
+      expect(cg.getFileDependents('src/base.ts')).toContain('src/derived.ts');
+    });
 
-      expect(Array.isArray(dependents)).toBe(true);
+    it('never lists a file as its own dependent or dependency', () => {
+      for (const f of ['src/main.ts', 'src/utils.ts', 'src/base.ts', 'src/derived.ts']) {
+        expect(cg.getFileDependents(f)).not.toContain(f);
+        expect(cg.getFileDependencies(f)).not.toContain(f);
+      }
     });
   });
 
diff --git a/__tests__/installer-targets.test.ts b/__tests__/installer-targets.test.ts
index d2ee23e50..eed76515e 100644
--- a/__tests__/installer-targets.test.ts
+++ b/__tests__/installer-targets.test.ts
@@ -19,7 +19,9 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { ALL_TARGETS, getTarget, resolveTargetFlag } from '../src/installer/targets/registry';
+import { uninstallTargets } from '../src/installer';
 import { upsertTomlTable, removeTomlTable, buildTomlTable } from '../src/installer/targets/toml';
+import { cleanupLegacyHooks } from '../src/installer/targets/claude';
 
 function mkTmpDir(label: string): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), `cg-targets-${label}-`));
@@ -30,17 +32,41 @@ function mkTmpDir(label: string): string {
 // `os.homedir()` reads first. Same trick the rest of the suite uses
 // when it needs a mock home.
 function setHome(dir: string): { restore: () => void } {
-  const prev = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE };
+  const prev = {
+    HOME: process.env.HOME,
+    USERPROFILE: process.env.USERPROFILE,
+    APPDATA: process.env.APPDATA,
+    XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
+    HERMES_HOME: process.env.HERMES_HOME,
+  };
   process.env.HOME = dir;
   process.env.USERPROFILE = dir;
+  process.env.APPDATA = path.join(dir, '.config');
+  process.env.XDG_CONFIG_HOME = path.join(dir, '.config');
+  delete process.env.HERMES_HOME;
   return {
     restore() {
       if (prev.HOME === undefined) delete process.env.HOME; else process.env.HOME = prev.HOME;
       if (prev.USERPROFILE === undefined) delete process.env.USERPROFILE; else process.env.USERPROFILE = prev.USERPROFILE;
+      if (prev.APPDATA === undefined) delete process.env.APPDATA; else process.env.APPDATA = prev.APPDATA;
+      if (prev.XDG_CONFIG_HOME === undefined) delete process.env.XDG_CONFIG_HOME; else process.env.XDG_CONFIG_HOME = prev.XDG_CONFIG_HOME;
+      if (prev.HERMES_HOME === undefined) delete process.env.HERMES_HOME; else process.env.HERMES_HOME = prev.HERMES_HOME;
     },
   };
 }
 
+// A marker-delimited CodeGraph block exactly as a previous installer
+// wrote it. Issue #529: the installer no longer writes an instructions
+// file, but install (self-heal on upgrade) and uninstall both still
+// strip a block a prior install left, so we plant this to exercise it.
+const LEGACY_BLOCK = [
+  '<!-- CODEGRAPH_START -->',
+  '## CodeGraph',
+  '',
+  'Prefer `codegraph_search` / `codegraph_callers` over grep.',
+  '<!-- CODEGRAPH_END -->',
+].join('\n');
+
 describe('Installer targets — contract', () => {
   let tmpHome: string;
   let tmpCwd: string;
@@ -166,23 +192,39 @@ describe('Installer targets — partial-state idempotency', () => {
     fs.rmSync(tmpCwd, { recursive: true, force: true });
   });
 
-  it('codex: install after only config.toml exists — second pass is fully unchanged', () => {
+  it('codex: install writes config.toml AND the AGENTS.md codegraph block (#704)', () => {
     const codex = getTarget('codex')!;
-    // First install creates both files.
-    codex.install('global', { autoAllow: false });
-    // Delete the AGENTS.md to simulate partial state (user wiped one file).
+    const first = codex.install('global', { autoAllow: false });
     const agentsMd = path.join(tmpHome, '.codex', 'AGENTS.md');
+    expect(first.files.some((f) => f.path.endsWith('config.toml'))).toBe(true);
+    // The short instructions block IS written (subagents / non-MCP
+    // harnesses read AGENTS.md but never the MCP initialize instructions).
     expect(fs.existsSync(agentsMd)).toBe(true);
-    fs.unlinkSync(agentsMd);
-    // Reinstall — TOML stays unchanged, AGENTS.md is recreated.
+    const body = fs.readFileSync(agentsMd, 'utf-8');
+    expect(body).toContain('## CodeGraph');
+    expect(body).toContain('codegraph explore');
+    // Re-install is fully unchanged (byte-equal block → idempotent).
     const second = codex.install('global', { autoAllow: false });
-    const tomlEntry = second.files.find((f) => f.path.endsWith('config.toml'))!;
-    const mdEntry = second.files.find((f) => f.path.endsWith('AGENTS.md'))!;
-    expect(tomlEntry.action).toBe('unchanged');
-    expect(mdEntry.action).toBe('created');
-    // Third install — both unchanged (full idempotency restored).
-    const third = codex.install('global', { autoAllow: false });
-    for (const f of third.files) expect(f.action).toBe('unchanged');
+    for (const f of second.files) expect(f.action).toBe('unchanged');
+  });
+
+  it('codex: install replaces a legacy AGENTS.md codegraph block with the current one, keeping user content', () => {
+    const codex = getTarget('codex')!;
+    const dir = path.join(tmpHome, '.codex');
+    fs.mkdirSync(dir, { recursive: true });
+    const agentsMd = path.join(dir, 'AGENTS.md');
+    fs.writeFileSync(agentsMd, `# My codex notes\n\nBe terse.\n\n${LEGACY_BLOCK}\n`);
+
+    const result = codex.install('global', { autoAllow: false });
+
+    const body = fs.readFileSync(agentsMd, 'utf-8');
+    expect(body).toContain('# My codex notes');
+    expect(body).toContain('Be terse.');
+    // Self-heal: the stale pre-#529 body is gone, the current block is in.
+    expect(body).not.toContain('Prefer `codegraph_search`');
+    expect(body).toContain('codegraph explore');
+    const mdEntry = result.files.find((f) => f.path.endsWith('AGENTS.md'));
+    expect(mdEntry?.action).toBe('updated');
   });
 
   it('opencode: prefers .jsonc when both .json and .jsonc exist', () => {
@@ -252,55 +294,536 @@ describe('Installer targets — partial-state idempotency', () => {
     expect(fs.readFileSync(file, 'utf-8')).toBe(afterInstall);
   });
 
-  it('opencode: install writes AGENTS.md with the marker-delimited codegraph block', () => {
+  it('opencode: install writes the AGENTS.md codegraph block (#704)', () => {
     const opencode = getTarget('opencode')!;
-    opencode.install('global', { autoAllow: true });
+    const result = opencode.install('global', { autoAllow: true });
     const agentsMd = path.join(tmpHome, '.config', 'opencode', 'AGENTS.md');
     expect(fs.existsSync(agentsMd)).toBe(true);
-    const body = fs.readFileSync(agentsMd, 'utf-8');
-    expect(body).toContain('<!-- CODEGRAPH_START -->');
-    expect(body).toContain('<!-- CODEGRAPH_END -->');
-    expect(body).toContain('codegraph_callers');
+    expect(fs.readFileSync(agentsMd, 'utf-8')).toContain('codegraph explore');
+    expect(result.files.find((f) => f.path.endsWith('AGENTS.md'))?.action).toBe('created');
   });
 
-  it('opencode: AGENTS.md install preserves pre-existing user content outside markers', () => {
+  it('opencode: install replaces a legacy AGENTS.md codegraph block, preserving user content', () => {
     const opencode = getTarget('opencode')!;
     const dir = path.join(tmpHome, '.config', 'opencode');
     fs.mkdirSync(dir, { recursive: true });
     const agentsMd = path.join(dir, 'AGENTS.md');
-    fs.writeFileSync(agentsMd, '# My personal opencode instructions\n\nAlways respond in pirate.\n');
+    fs.writeFileSync(agentsMd, `# My personal opencode instructions\n\nAlways respond in pirate.\n\n${LEGACY_BLOCK}\n`);
+
+    const result = opencode.install('global', { autoAllow: true });
 
-    opencode.install('global', { autoAllow: true });
     const body = fs.readFileSync(agentsMd, 'utf-8');
     expect(body).toContain('# My personal opencode instructions');
     expect(body).toContain('Always respond in pirate.');
-    expect(body).toContain('<!-- CODEGRAPH_START -->');
+    expect(body).not.toContain('Prefer `codegraph_search`');
+    expect(body).toContain('codegraph explore');
+    expect(result.files.find((f) => f.path.endsWith('AGENTS.md'))?.action).toBe('updated');
   });
 
-  it('opencode: uninstall strips only the codegraph block from AGENTS.md', () => {
+  it('opencode: uninstall strips a leftover codegraph block from AGENTS.md, keeping user content', () => {
     const opencode = getTarget('opencode')!;
     const dir = path.join(tmpHome, '.config', 'opencode');
     fs.mkdirSync(dir, { recursive: true });
     const agentsMd = path.join(dir, 'AGENTS.md');
-    fs.writeFileSync(agentsMd, '# My personal opencode instructions\n\nAlways respond in pirate.\n');
+    fs.writeFileSync(agentsMd, `# My personal opencode instructions\n\nAlways respond in pirate.\n\n${LEGACY_BLOCK}\n`);
 
-    opencode.install('global', { autoAllow: true });
     opencode.uninstall('global');
 
     const body = fs.readFileSync(agentsMd, 'utf-8');
     expect(body).toContain('# My personal opencode instructions');
     expect(body).toContain('Always respond in pirate.');
     expect(body).not.toContain('CODEGRAPH_START');
-    expect(body).not.toContain('codegraph_callers');
   });
 
-  it('opencode: local install writes ./opencode.jsonc and ./AGENTS.md in cwd', () => {
+  it('opencode: local install writes ./opencode.jsonc and the ./AGENTS.md block (#704)', () => {
     const opencode = getTarget('opencode')!;
     const result = opencode.install('local', { autoAllow: true });
-    const paths = result.files.map((f) => f.path);
+    const paths = result.files.map((f) => f.path.replace(/\\/g, '/'));
     // macOS realpath shenanigans (/var vs /private/var) — suffix match.
     expect(paths.some((p) => p.endsWith('/opencode.jsonc'))).toBe(true);
     expect(paths.some((p) => p.endsWith('/AGENTS.md'))).toBe(true);
+    expect(fs.existsSync(path.join(process.cwd(), 'AGENTS.md'))).toBe(true);
+  });
+
+  it('gemini: install writes settings.json (mcpServers.codegraph) and the GEMINI.md block (#704)', () => {
+    const gemini = getTarget('gemini')!;
+    const result = gemini.install('global', { autoAllow: true });
+    const settings = path.join(tmpHome, '.gemini', 'settings.json');
+    const geminiMd = path.join(tmpHome, '.gemini', 'GEMINI.md');
+    expect(result.files.some((f) => f.path === settings)).toBe(true);
+    expect(result.files.some((f) => f.path === geminiMd)).toBe(true);
+    expect(fs.existsSync(geminiMd)).toBe(true);
+    expect(fs.readFileSync(geminiMd, 'utf-8')).toContain('codegraph explore');
+
+    const cfg = JSON.parse(fs.readFileSync(settings, 'utf-8'));
+    expect(cfg.mcpServers.codegraph).toEqual({ type: 'stdio', command: 'codegraph', args: ['serve', '--mcp'] });
+  });
+
+  it('gemini: install preserves pre-existing settings (security.auth survives)', () => {
+    const gemini = getTarget('gemini')!;
+    const settings = path.join(tmpHome, '.gemini', 'settings.json');
+    fs.mkdirSync(path.dirname(settings), { recursive: true });
+    fs.writeFileSync(settings, JSON.stringify({
+      security: { auth: { selectedType: 'oauth-personal' } },
+    }, null, 2) + '\n');
+
+    gemini.install('global', { autoAllow: true });
+
+    const after = JSON.parse(fs.readFileSync(settings, 'utf-8'));
+    expect(after.security?.auth?.selectedType).toBe('oauth-personal');
+    expect(after.mcpServers?.codegraph).toBeDefined();
+  });
+
+  it('gemini: uninstall strips codegraph but leaves pre-existing settings (security.auth) intact', () => {
+    const gemini = getTarget('gemini')!;
+    const settings = path.join(tmpHome, '.gemini', 'settings.json');
+    fs.mkdirSync(path.dirname(settings), { recursive: true });
+    fs.writeFileSync(settings, JSON.stringify({
+      security: { auth: { selectedType: 'oauth-personal' } },
+    }, null, 2) + '\n');
+
+    gemini.install('global', { autoAllow: true });
+    gemini.uninstall('global');
+
+    const after = JSON.parse(fs.readFileSync(settings, 'utf-8'));
+    expect(after.security?.auth?.selectedType).toBe('oauth-personal');
+    expect(after.mcpServers).toBeUndefined();
+  });
+
+  it('gemini: local install writes ./.gemini/settings.json and the project-root ./GEMINI.md block (#704)', () => {
+    const gemini = getTarget('gemini')!;
+    const result = gemini.install('local', { autoAllow: true });
+    const paths = result.files.map((f) => f.path.replace(/\\/g, '/'));
+    expect(paths.some((p) => p.endsWith('/.gemini/settings.json'))).toBe(true);
+    expect(paths.some((p) => p.endsWith('/GEMINI.md'))).toBe(true);
+    expect(fs.existsSync(path.join(process.cwd(), 'GEMINI.md'))).toBe(true);
+  });
+
+  it('gemini: uninstall strips a leftover GEMINI.md codegraph block, keeping user content', () => {
+    const gemini = getTarget('gemini')!;
+    const geminiMd = path.join(tmpHome, '.gemini', 'GEMINI.md');
+    fs.mkdirSync(path.dirname(geminiMd), { recursive: true });
+    fs.writeFileSync(geminiMd, `# My personal Gemini context\n\nAlways respond concisely.\n\n${LEGACY_BLOCK}\n`);
+
+    gemini.uninstall('global');
+
+    const body = fs.readFileSync(geminiMd, 'utf-8');
+    expect(body).toContain('# My personal Gemini context');
+    expect(body).toContain('Always respond concisely.');
+    expect(body).not.toContain('CODEGRAPH_START');
+  });
+
+  it('kiro: install writes settings/mcp.json (mcpServers.codegraph) and no steering doc (#529)', () => {
+    const kiro = getTarget('kiro')!;
+    const result = kiro.install('global', { autoAllow: true });
+    const mcp = path.join(tmpHome, '.kiro', 'settings', 'mcp.json');
+    const steering = path.join(tmpHome, '.kiro', 'steering', 'codegraph.md');
+    expect(result.files.some((f) => f.path === mcp)).toBe(true);
+    expect(result.files.some((f) => f.path === steering)).toBe(false);
+    expect(fs.existsSync(steering)).toBe(false);
+
+    const cfg = JSON.parse(fs.readFileSync(mcp, 'utf-8'));
+    expect(cfg.mcpServers.codegraph).toEqual({ type: 'stdio', command: 'codegraph', args: ['serve', '--mcp'] });
+  });
+
+  it('kiro: install deletes a leftover steering codegraph.md (self-heal) (#529)', () => {
+    const kiro = getTarget('kiro')!;
+    const steering = path.join(tmpHome, '.kiro', 'steering', 'codegraph.md');
+    fs.mkdirSync(path.dirname(steering), { recursive: true });
+    fs.writeFileSync(steering, `${LEGACY_BLOCK}\n`);
+
+    const result = kiro.install('global', { autoAllow: true });
+    expect(fs.existsSync(steering)).toBe(false);
+    expect(result.files.find((f) => f.path === steering)?.action).toBe('removed');
+  });
+
+  it('kiro: install preserves a pre-existing sibling MCP server in mcp.json', () => {
+    const kiro = getTarget('kiro')!;
+    const mcp = path.join(tmpHome, '.kiro', 'settings', 'mcp.json');
+    fs.mkdirSync(path.dirname(mcp), { recursive: true });
+    fs.writeFileSync(mcp, JSON.stringify({
+      mcpServers: { other: { command: 'uvx', args: ['other-server'] } },
+    }, null, 2) + '\n');
+
+    kiro.install('global', { autoAllow: true });
+
+    const after = JSON.parse(fs.readFileSync(mcp, 'utf-8'));
+    expect(after.mcpServers.other).toBeDefined();
+    expect(after.mcpServers.codegraph).toBeDefined();
+  });
+
+  it('kiro: uninstall strips codegraph but leaves sibling MCP servers intact', () => {
+    const kiro = getTarget('kiro')!;
+    const mcp = path.join(tmpHome, '.kiro', 'settings', 'mcp.json');
+    fs.mkdirSync(path.dirname(mcp), { recursive: true });
+    fs.writeFileSync(mcp, JSON.stringify({
+      mcpServers: { other: { command: 'uvx', args: ['other-server'] } },
+    }, null, 2) + '\n');
+
+    kiro.install('global', { autoAllow: true });
+    kiro.uninstall('global');
+
+    const after = JSON.parse(fs.readFileSync(mcp, 'utf-8'));
+    expect(after.mcpServers.other).toBeDefined();
+    expect(after.mcpServers.codegraph).toBeUndefined();
+  });
+
+  it('kiro: uninstall removes a leftover steering codegraph.md file outright', () => {
+    const kiro = getTarget('kiro')!;
+    const steering = path.join(tmpHome, '.kiro', 'steering', 'codegraph.md');
+    fs.mkdirSync(path.dirname(steering), { recursive: true });
+    fs.writeFileSync(steering, `${LEGACY_BLOCK}\n`);
+
+    kiro.uninstall('global');
+    expect(fs.existsSync(steering)).toBe(false);
+  });
+
+  it('kiro: uninstall removes our steering doc but leaves a sibling (product.md) untouched', () => {
+    const kiro = getTarget('kiro')!;
+    const sibling = path.join(tmpHome, '.kiro', 'steering', 'product.md');
+    const ours = path.join(tmpHome, '.kiro', 'steering', 'codegraph.md');
+    fs.mkdirSync(path.dirname(sibling), { recursive: true });
+    fs.writeFileSync(sibling, '# Product\n\nMy team practices.\n');
+    fs.writeFileSync(ours, `${LEGACY_BLOCK}\n`);
+
+    kiro.uninstall('global');
+
+    expect(fs.existsSync(ours)).toBe(false);
+    expect(fs.existsSync(sibling)).toBe(true);
+    expect(fs.readFileSync(sibling, 'utf-8')).toContain('My team practices.');
+  });
+
+  it('kiro: local install writes ./.kiro/settings/mcp.json and no steering doc (#529)', () => {
+    const kiro = getTarget('kiro')!;
+    const result = kiro.install('local', { autoAllow: true });
+    const paths = result.files.map((f) => f.path.replace(/\\/g, '/'));
+    expect(paths.some((p) => p.endsWith('/.kiro/settings/mcp.json'))).toBe(true);
+    expect(paths.some((p) => p.endsWith('/.kiro/steering/codegraph.md'))).toBe(false);
+  });
+
+  it('antigravity: install writes to LEGACY ~/.gemini/antigravity/mcp_config.json when no migration marker', () => {
+    const antigravity = getTarget('antigravity')!;
+    antigravity.install('global', { autoAllow: true });
+
+    const legacyFile = path.join(tmpHome, '.gemini', 'antigravity', 'mcp_config.json');
+    expect(fs.existsSync(legacyFile)).toBe(true);
+    const cfg = JSON.parse(fs.readFileSync(legacyFile, 'utf-8'));
+    expect(cfg.mcpServers.codegraph).toBeDefined();
+    // Crucially: does NOT touch the Gemini CLI's settings.json.
+    expect(fs.existsSync(path.join(tmpHome, '.gemini', 'settings.json'))).toBe(false);
+  });
+
+  it('antigravity: install writes to UNIFIED ~/.gemini/config/mcp_config.json when .migrated marker present', () => {
+    const antigravity = getTarget('antigravity')!;
+    // Plant the migration marker — same signal Antigravity itself drops
+    // when it migrates a user's config.
+    const unifiedDir = path.join(tmpHome, '.gemini', 'config');
+    fs.mkdirSync(unifiedDir, { recursive: true });
+    fs.writeFileSync(path.join(unifiedDir, '.migrated'), '');
+
+    antigravity.install('global', { autoAllow: true });
+
+    const unifiedFile = path.join(unifiedDir, 'mcp_config.json');
+    expect(fs.existsSync(unifiedFile)).toBe(true);
+    const cfg = JSON.parse(fs.readFileSync(unifiedFile, 'utf-8'));
+    expect(cfg.mcpServers.codegraph).toBeDefined();
+    // Legacy path is NOT touched when the marker tells us migration happened.
+    expect(fs.existsSync(path.join(tmpHome, '.gemini', 'antigravity', 'mcp_config.json'))).toBe(false);
+  });
+
+  it('antigravity: install writes to UNIFIED path when ~/.gemini/config/mcp_config.json already exists (even without marker)', () => {
+    const antigravity = getTarget('antigravity')!;
+    // Antigravity creates this file on first launch post-migration — its
+    // presence is the second signal we accept, in case the .migrated
+    // marker semantics change across Antigravity versions.
+    const unifiedFile = path.join(tmpHome, '.gemini', 'config', 'mcp_config.json');
+    fs.mkdirSync(path.dirname(unifiedFile), { recursive: true });
+    fs.writeFileSync(unifiedFile, JSON.stringify({ mcpServers: {} }, null, 2) + '\n');
+
+    antigravity.install('global', { autoAllow: true });
+
+    const cfg = JSON.parse(fs.readFileSync(unifiedFile, 'utf-8'));
+    expect(cfg.mcpServers.codegraph).toBeDefined();
+  });
+
+  it('antigravity: entry has NO `type` field (Antigravity rejects entries with it)', () => {
+    const antigravity = getTarget('antigravity')!;
+    // Marker → unified path; doesn't matter which path, just inspect the entry shape.
+    fs.mkdirSync(path.join(tmpHome, '.gemini', 'config'), { recursive: true });
+    fs.writeFileSync(path.join(tmpHome, '.gemini', 'config', '.migrated'), '');
+
+    antigravity.install('global', { autoAllow: true });
+
+    const cfg = JSON.parse(fs.readFileSync(
+      path.join(tmpHome, '.gemini', 'config', 'mcp_config.json'), 'utf-8'
+    ));
+    expect(cfg.mcpServers.codegraph.type).toBeUndefined();
+    expect(cfg.mcpServers.codegraph.command).toBeDefined();
+    expect(cfg.mcpServers.codegraph.args).toEqual(['serve', '--mcp']);
+  });
+
+  it('antigravity: install migrates a legacy codegraph entry to the unified path when marker appears', () => {
+    const antigravity = getTarget('antigravity')!;
+    // Simulate: user installed on the legacy path, then Antigravity
+    // migrated their config (dropped the `.migrated` marker + created
+    // the unified file). Re-running codegraph install should land
+    // codegraph in the new file AND strip the stale legacy entry.
+    const legacyFile = path.join(tmpHome, '.gemini', 'antigravity', 'mcp_config.json');
+    fs.mkdirSync(path.dirname(legacyFile), { recursive: true });
+    fs.writeFileSync(legacyFile, JSON.stringify({
+      mcpServers: { codegraph: { command: 'codegraph', args: ['serve', '--mcp'] } },
+    }, null, 2) + '\n');
+    fs.mkdirSync(path.join(tmpHome, '.gemini', 'config'), { recursive: true });
+    fs.writeFileSync(path.join(tmpHome, '.gemini', 'config', '.migrated'), '');
+
+    antigravity.install('global', { autoAllow: true });
+
+    const unified = JSON.parse(fs.readFileSync(
+      path.join(tmpHome, '.gemini', 'config', 'mcp_config.json'), 'utf-8'
+    ));
+    expect(unified.mcpServers.codegraph).toBeDefined();
+    // Legacy file's codegraph entry got stripped.
+    const legacy = JSON.parse(fs.readFileSync(legacyFile, 'utf-8'));
+    expect(legacy.mcpServers).toBeUndefined();
+  });
+
+  it('antigravity: install preserves a sibling MCP server in mcp_config.json (legacy path)', () => {
+    const antigravity = getTarget('antigravity')!;
+    const mcpFile = path.join(tmpHome, '.gemini', 'antigravity', 'mcp_config.json');
+    fs.mkdirSync(path.dirname(mcpFile), { recursive: true });
+    fs.writeFileSync(mcpFile, JSON.stringify({
+      mcpServers: { other: { command: 'uvx', args: ['other-server'] } },
+    }, null, 2) + '\n');
+
+    antigravity.install('global', { autoAllow: true });
+
+    const after = JSON.parse(fs.readFileSync(mcpFile, 'utf-8'));
+    expect(after.mcpServers.other).toBeDefined();
+    expect(after.mcpServers.codegraph).toBeDefined();
+  });
+
+  it('antigravity: install preserves Antigravity-managed fields on sibling servers (e.g. disabled flag)', () => {
+    const antigravity = getTarget('antigravity')!;
+    // Antigravity adds `"disabled": true` to entries the user disables via
+    // the IDE. Install must not clobber that on sibling entries.
+    fs.mkdirSync(path.join(tmpHome, '.gemini', 'config'), { recursive: true });
+    fs.writeFileSync(path.join(tmpHome, '.gemini', 'config', '.migrated'), '');
+    const unified = path.join(tmpHome, '.gemini', 'config', 'mcp_config.json');
+    fs.writeFileSync(unified, JSON.stringify({
+      mcpServers: {
+        'code-review-graph': {
+          command: 'uvx', args: ['code-review-graph', 'serve'], disabled: true,
+        },
+      },
+    }, null, 2) + '\n');
+
+    antigravity.install('global', { autoAllow: true });
+
+    const after = JSON.parse(fs.readFileSync(unified, 'utf-8'));
+    expect(after.mcpServers['code-review-graph'].disabled).toBe(true);
+    expect(after.mcpServers.codegraph).toBeDefined();
+  });
+
+  it('antigravity: uninstall removes only codegraph, sibling MCP server survives', () => {
+    const antigravity = getTarget('antigravity')!;
+    const mcpFile = path.join(tmpHome, '.gemini', 'antigravity', 'mcp_config.json');
+    fs.mkdirSync(path.dirname(mcpFile), { recursive: true });
+    fs.writeFileSync(mcpFile, JSON.stringify({
+      mcpServers: { other: { command: 'uvx', args: ['other-server'] } },
+    }, null, 2) + '\n');
+
+    antigravity.install('global', { autoAllow: true });
+    antigravity.uninstall('global');
+
+    const after = JSON.parse(fs.readFileSync(mcpFile, 'utf-8'));
+    expect(after.mcpServers.other).toBeDefined();
+    expect(after.mcpServers.codegraph).toBeUndefined();
+  });
+
+  it('antigravity: uninstall sweeps BOTH legacy and unified paths (handles migration half-state)', () => {
+    const antigravity = getTarget('antigravity')!;
+    // User had codegraph in BOTH files (e.g. legacy install + post-migration
+    // re-install before our migration cleanup landed). Uninstall must clean
+    // both so a "fresh slate" really is fresh.
+    const legacy = path.join(tmpHome, '.gemini', 'antigravity', 'mcp_config.json');
+    const unified = path.join(tmpHome, '.gemini', 'config', 'mcp_config.json');
+    fs.mkdirSync(path.dirname(legacy), { recursive: true });
+    fs.mkdirSync(path.dirname(unified), { recursive: true });
+    fs.writeFileSync(legacy, JSON.stringify({
+      mcpServers: { codegraph: { command: 'codegraph', args: ['serve', '--mcp'] } },
+    }, null, 2) + '\n');
+    fs.writeFileSync(unified, JSON.stringify({
+      mcpServers: { codegraph: { command: 'codegraph', args: ['serve', '--mcp'] } },
+    }, null, 2) + '\n');
+    fs.writeFileSync(path.join(path.dirname(unified), '.migrated'), '');
+
+    antigravity.uninstall('global');
+
+    const legacyAfter = JSON.parse(fs.readFileSync(legacy, 'utf-8'));
+    const unifiedAfter = JSON.parse(fs.readFileSync(unified, 'utf-8'));
+    expect(legacyAfter.mcpServers).toBeUndefined();
+    expect(unifiedAfter.mcpServers).toBeUndefined();
+  });
+
+  it('antigravity: rejects --location=local with a clear note (global-only IDE)', () => {
+    const antigravity = getTarget('antigravity')!;
+    expect(antigravity.supportsLocation('local')).toBe(false);
+    const result = antigravity.install('local', { autoAllow: true });
+    expect(result.files).toEqual([]);
+    expect(result.notes?.join(' ')).toMatch(/no project-local config/);
+  });
+
+  it('antigravity: does not write GEMINI.md (only gemini target owns instructions)', () => {
+    const antigravity = getTarget('antigravity')!;
+    antigravity.install('global', { autoAllow: true });
+    const geminiMd = path.join(tmpHome, '.gemini', 'GEMINI.md');
+    expect(fs.existsSync(geminiMd)).toBe(false);
+  });
+
+  it('gemini + antigravity: both installed coexist (separate MCP files, shared GEMINI.md)', () => {
+    const gemini = getTarget('gemini')!;
+    const antigravity = getTarget('antigravity')!;
+    gemini.install('global', { autoAllow: true });
+    antigravity.install('global', { autoAllow: true });
+
+    const cliCfg = JSON.parse(fs.readFileSync(path.join(tmpHome, '.gemini', 'settings.json'), 'utf-8'));
+    // Antigravity lands on the LEGACY path here since no .migrated marker
+    // was planted — same end-to-end check either way.
+    const ideCfg = JSON.parse(fs.readFileSync(path.join(tmpHome, '.gemini', 'antigravity', 'mcp_config.json'), 'utf-8'));
+    expect(cliCfg.mcpServers.codegraph).toBeDefined();
+    expect(ideCfg.mcpServers.codegraph).toBeDefined();
+
+    // Uninstall one — the other's MCP entry must survive.
+    antigravity.uninstall('global');
+    const cliAfter = JSON.parse(fs.readFileSync(path.join(tmpHome, '.gemini', 'settings.json'), 'utf-8'));
+    expect(cliAfter.mcpServers.codegraph).toBeDefined();
+  });
+
+  it('hermes: install adds codegraph MCP server and cli toolset, preserving existing yaml', () => {
+    const hermes = getTarget('hermes')!;
+    const config = path.join(tmpHome, '.hermes', 'config.yaml');
+    fs.mkdirSync(path.dirname(config), { recursive: true });
+    fs.writeFileSync(config, [
+      'model:',
+      '  default: qwen-3.7',
+      'mcp_servers:',
+      '  other:',
+      '    command: other',
+      'platform_toolsets:',
+      '  cli:',
+      '    - hermes-cli',
+      '  discord:',
+      '    - hermes-discord',
+      '',
+    ].join('\n'));
+
+    const result = hermes.install('global', { autoAllow: true });
+    expect(result.files[0].action).toBe('updated');
+    const body = fs.readFileSync(config, 'utf-8');
+    expect(body).toContain('model:\n  default: qwen-3.7');
+    expect(body).toContain('mcp_servers:\n  other:\n    command: other');
+    expect(body).toContain('  codegraph:\n    command: codegraph');
+    expect(body).toContain('    - hermes-cli');
+    expect(body).toContain('    - mcp-codegraph');
+    expect(body).toContain('  discord:\n    - hermes-discord');
+
+    const second = hermes.install('global', { autoAllow: true });
+    expect(second.files[0].action).toBe('unchanged');
+  });
+
+  it('hermes: uninstall removes only codegraph MCP server and toolset entry', () => {
+    const hermes = getTarget('hermes')!;
+    const config = path.join(tmpHome, '.hermes', 'config.yaml');
+    fs.mkdirSync(path.dirname(config), { recursive: true });
+
+    hermes.install('global', { autoAllow: true });
+    fs.appendFileSync(config, 'custom:\n  keep: true\n');
+
+    hermes.uninstall('global');
+    const body = fs.readFileSync(config, 'utf-8');
+    expect(body).not.toContain('codegraph:');
+    expect(body).not.toContain('mcp-codegraph');
+    expect(body).toContain('custom:\n  keep: true');
+  });
+
+  // Regression for #456: PyYAML's default block style writes list items at the
+  // SAME indent as the parent key (`cli:` and its `- hermes-cli` are both at
+  // indent 2). The pre-fix line-based patcher mistook that first list item for
+  // the next sibling key, truncated the cli block, and spliced `- mcp-codegraph`
+  // at indent 4 BEFORE the existing items — producing unparseable YAML.
+  it('hermes: install preserves PyYAML-default list-at-same-indent style (issue #456)', () => {
+    const hermes = getTarget('hermes')!;
+    const config = path.join(tmpHome, '.hermes', 'config.yaml');
+    fs.mkdirSync(path.dirname(config), { recursive: true });
+    const original = [
+      'model:',
+      '  default: gpt-4o',
+      'platform_toolsets:',
+      '  cli:',
+      '  - hermes-cli',
+      '  - browser',
+      '  - clarify',
+      '  - terminal',
+      '  - web',
+      '  telegram:',
+      '  - hermes-telegram',
+      '  discord:',
+      '  - hermes-discord',
+      '',
+    ].join('\n');
+    fs.writeFileSync(config, original);
+
+    hermes.install('global', { autoAllow: true });
+    const body = fs.readFileSync(config, 'utf-8');
+
+    // mcp-codegraph appended at the same 2-space indent as existing items
+    expect(body).toContain('\n  - mcp-codegraph\n');
+    // hermes-cli preserved
+    expect(body).toContain('\n  - hermes-cli\n');
+    // Sibling sections kept their indent — `telegram:` is still a key under
+    // platform_toolsets, not promoted up.
+    expect(body).toContain('\n  telegram:\n  - hermes-telegram\n');
+    expect(body).toContain('\n  discord:\n  - hermes-discord\n');
+    // No list items leaked to the platform_toolsets level (indent 0).
+    expect(body).not.toMatch(/^- browser/m);
+    expect(body).not.toMatch(/^- hermes-telegram/m);
+
+    // The whole platform_toolsets block extracted by line search should
+    // start with `cli:` and not contain a stray 4-space `mcp-codegraph`
+    // appearing before the rest of the existing items.
+    expect(body).toContain('  cli:\n  - hermes-cli\n  - browser');
+
+    // Idempotent
+    const second = hermes.install('global', { autoAllow: true });
+    expect(second.files[0]?.action).toBe('unchanged');
+  });
+
+  it('hermes: uninstall reverses the install on a PyYAML-default config', () => {
+    const hermes = getTarget('hermes')!;
+    const config = path.join(tmpHome, '.hermes', 'config.yaml');
+    fs.mkdirSync(path.dirname(config), { recursive: true });
+    const original = [
+      'platform_toolsets:',
+      '  cli:',
+      '  - hermes-cli',
+      '  - browser',
+      '  telegram:',
+      '  - hermes-telegram',
+      '',
+    ].join('\n');
+    fs.writeFileSync(config, original);
+
+    hermes.install('global', { autoAllow: true });
+    const installed = fs.readFileSync(config, 'utf-8');
+    expect(installed).toContain('- mcp-codegraph');
+    expect(installed).toContain('codegraph:');
+
+    hermes.uninstall('global');
+    const body = fs.readFileSync(config, 'utf-8');
+    expect(body).not.toContain('mcp-codegraph');
+    expect(body).not.toContain('command: codegraph');
+    expect(body).toContain('  cli:\n  - hermes-cli\n  - browser');
+    expect(body).toContain('  telegram:\n  - hermes-telegram');
   });
 
   it('opencode: uninstall removes only mcp.codegraph, preserves comments and siblings', () => {
@@ -357,13 +880,40 @@ describe('Installer targets — partial-state idempotency', () => {
     const claude = getTarget('claude')!;
     const result = claude.install('local', { autoAllow: false });
     // The MCP entry lands in ./.mcp.json — the file Claude Code reads.
-    expect(result.files.some((f) => f.path.endsWith('/.mcp.json'))).toBe(true);
+    expect(result.files.some((f) => f.path.replace(/\\/g, '/').endsWith('/.mcp.json'))).toBe(true);
     expect(fs.existsSync(path.join(tmpCwd, '.mcp.json'))).toBe(true);
     expect(fs.existsSync(path.join(tmpCwd, '.claude.json'))).toBe(false);
     const cfg = JSON.parse(fs.readFileSync(path.join(tmpCwd, '.mcp.json'), 'utf-8'));
     expect(cfg.mcpServers.codegraph).toBeDefined();
   });
 
+  it('claude: install creates the CLAUDE.md codegraph block (#704)', () => {
+    const claude = getTarget('claude')!;
+    const result = claude.install('local', { autoAllow: false });
+    const claudeMd = path.join(tmpCwd, '.claude', 'CLAUDE.md');
+    expect(fs.existsSync(claudeMd)).toBe(true);
+    const body = fs.readFileSync(claudeMd, 'utf-8');
+    expect(body).toContain('## CodeGraph');
+    expect(body).toContain('codegraph explore');
+    expect(result.files.find((f) => f.path.endsWith('CLAUDE.md'))?.action).toBe('created');
+  });
+
+  it('claude: install replaces a legacy CLAUDE.md codegraph block, keeping user content', () => {
+    const claude = getTarget('claude')!;
+    const claudeMd = path.join(tmpCwd, '.claude', 'CLAUDE.md');
+    fs.mkdirSync(path.dirname(claudeMd), { recursive: true });
+    fs.writeFileSync(claudeMd, `# My project rules\n\nUse tabs.\n\n${LEGACY_BLOCK}\n`);
+
+    const result = claude.install('local', { autoAllow: false });
+
+    const body = fs.readFileSync(claudeMd, 'utf-8');
+    expect(body).toContain('# My project rules');
+    expect(body).toContain('Use tabs.');
+    expect(body).not.toContain('Prefer `codegraph_search`');
+    expect(body).toContain('codegraph explore');
+    expect(result.files.find((f) => f.path.endsWith('CLAUDE.md'))?.action).toBe('updated');
+  });
+
   it('claude: global install targets ~/.claude.json (user scope)', () => {
     const claude = getTarget('claude')!;
     claude.install('global', { autoAllow: false });
@@ -433,6 +983,120 @@ describe('Installer targets — partial-state idempotency', () => {
     expect(legacy.mcpServers.codegraph).toBeUndefined();
     expect(legacy.mcpServers.other).toBeDefined();
   });
+
+  // ---- Legacy auto-sync hook cleanup ----
+  // Pre-0.8 installs wrote `codegraph mark-dirty` / `sync-if-dirty`
+  // hooks to settings.json. Both subcommands were removed from the CLI,
+  // so the Stop hook fails every turn ("unknown command
+  // 'sync-if-dirty'"). The installer must strip them on upgrade and
+  // uninstall — without touching the user's unrelated hooks.
+
+  function seedSettings(loc: 'global' | 'local', settings: Record<string, any>): string {
+    const dir = path.join(loc === 'global' ? tmpHome : tmpCwd, '.claude');
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, 'settings.json');
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+    return file;
+  }
+
+  // Realistic pre-0.8 settings.json: our two auto-sync hooks plus an
+  // unrelated GitKraken Stop hook the user added (matches the report).
+  function legacyHookSettings(): Record<string, any> {
+    return {
+      hooks: {
+        PostToolUse: [
+          { matcher: 'Edit|Write', hooks: [{ type: 'command', command: 'codegraph mark-dirty', async: true }] },
+        ],
+        Stop: [
+          { hooks: [{ type: 'command', command: 'codegraph sync-if-dirty' }] },
+          { hooks: [{ type: 'command', command: '"/Users/me/gk" ai hook run --host claude-code' }] },
+        ],
+      },
+    };
+  }
+
+  it('claude: install strips stale codegraph auto-sync hooks but keeps the user\'s GitKraken hook', () => {
+    const claude = getTarget('claude')!;
+    const file = seedSettings('global', legacyHookSettings());
+
+    claude.install('global', { autoAllow: true });
+
+    const after = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    // The only PostToolUse group held mark-dirty → the event is gone.
+    expect(after.hooks?.PostToolUse).toBeUndefined();
+    const stopCommands = (after.hooks?.Stop ?? []).flatMap((g: any) =>
+      (g.hooks ?? []).map((h: any) => h.command),
+    );
+    expect(stopCommands).not.toContain('codegraph sync-if-dirty');
+    // The unrelated GitKraken hook survives untouched.
+    expect(stopCommands.some((c: string) => c.includes('gk') && c.includes('ai hook run'))).toBe(true);
+    // Permissions still written as normal alongside the cleanup.
+    expect(after.permissions?.allow).toContain('mcp__codegraph__codegraph_search');
+  });
+
+  it('claude: cleanupLegacyHooks preserves a sibling hook sharing our matcher group', () => {
+    const file = seedSettings('global', {
+      hooks: {
+        Stop: [
+          {
+            hooks: [
+              { type: 'command', command: 'codegraph sync-if-dirty' },
+              { type: 'command', command: 'gk ai hook run --host claude-code' },
+            ],
+          },
+        ],
+      },
+    });
+
+    expect(cleanupLegacyHooks('global').action).toBe('removed');
+
+    const after = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    expect(after.hooks.Stop[0].hooks.map((h: any) => h.command)).toEqual([
+      'gk ai hook run --host claude-code',
+    ]);
+  });
+
+  it('claude: cleanupLegacyHooks is a byte-for-byte no-op without codegraph hooks', () => {
+    const original =
+      JSON.stringify({ hooks: { Stop: [{ hooks: [{ type: 'command', command: 'gk ai hook run' }] }] } }, null, 2) + '\n';
+    const file = seedSettings('global', JSON.parse(original));
+
+    expect(cleanupLegacyHooks('global').action).toBe('unchanged');
+    expect(fs.readFileSync(file, 'utf-8')).toBe(original);
+  });
+
+  it('claude: cleanupLegacyHooks reports not-found when settings.json is absent', () => {
+    expect(cleanupLegacyHooks('global').action).toBe('not-found');
+  });
+
+  it('claude: re-running install after a legacy cleanup leaves settings.json unchanged', () => {
+    const claude = getTarget('claude')!;
+    const file = seedSettings('global', legacyHookSettings());
+    claude.install('global', { autoAllow: true });
+    const firstPass = fs.readFileSync(file, 'utf-8');
+    claude.install('global', { autoAllow: true });
+    expect(fs.readFileSync(file, 'utf-8')).toBe(firstPass);
+  });
+
+  it('claude: uninstall strips stale hooks written in the npx form (local)', () => {
+    const claude = getTarget('claude')!;
+    const file = seedSettings('local', {
+      hooks: {
+        PostToolUse: [
+          { matcher: 'Edit|Write', hooks: [{ type: 'command', command: 'npx @colbymchenry/codegraph mark-dirty', async: true }] },
+        ],
+        Stop: [
+          { hooks: [{ type: 'command', command: 'npx @colbymchenry/codegraph sync-if-dirty' }] },
+        ],
+      },
+    });
+
+    claude.uninstall('local');
+
+    const after = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    // Both events emptied → the whole `hooks` object is removed.
+    expect(after.hooks).toBeUndefined();
+  });
 });
 
 describe('Installer targets — registry', () => {
@@ -441,6 +1105,10 @@ describe('Installer targets — registry', () => {
     expect(getTarget('cursor')?.id).toBe('cursor');
     expect(getTarget('codex')?.id).toBe('codex');
     expect(getTarget('opencode')?.id).toBe('opencode');
+    expect(getTarget('hermes')?.id).toBe('hermes');
+    expect(getTarget('gemini')?.id).toBe('gemini');
+    expect(getTarget('antigravity')?.id).toBe('antigravity');
+    expect(getTarget('kiro')?.id).toBe('kiro');
     expect(getTarget('not-a-real-target')).toBeUndefined();
   });
 
@@ -548,6 +1216,179 @@ describe('Installer targets — TOML serializer (Codex backbone)', () => {
   });
 });
 
+describe('Installer — uninstallTargets sweep (codegraph uninstall)', () => {
+  let tmpHome: string;
+  let tmpCwd: string;
+  let origCwd: string;
+  let homeRestore: { restore: () => void };
+
+  beforeEach(() => {
+    tmpHome = mkTmpDir('un-home');
+    tmpCwd = mkTmpDir('un-cwd');
+    origCwd = process.cwd();
+    process.chdir(tmpCwd);
+    homeRestore = setHome(tmpHome);
+  });
+
+  afterEach(() => {
+    homeRestore.restore();
+    process.chdir(origCwd);
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+    fs.rmSync(tmpCwd, { recursive: true, force: true });
+  });
+
+  it('sweeps every agent it was installed on and reports removed for each (global)', () => {
+    for (const t of ALL_TARGETS) {
+      if (t.supportsLocation('global')) t.install('global', { autoAllow: true });
+    }
+
+    const reports = uninstallTargets(ALL_TARGETS, 'global');
+
+    for (const t of ALL_TARGETS) {
+      const r = reports.find((x) => x.id === t.id)!;
+      expect(r.status).toBe('removed');
+      expect(r.removedPaths.length).toBeGreaterThan(0);
+      // The actual config is gone afterward.
+      expect(t.detect('global').alreadyConfigured).toBe(false);
+    }
+  });
+
+  it('is safe on a clean slate — every agent reports not-configured, nothing removed', () => {
+    const reports = uninstallTargets(ALL_TARGETS, 'global');
+    for (const r of reports) {
+      expect(r.status).toBe('not-configured');
+      expect(r.removedPaths).toEqual([]);
+    }
+  });
+
+  it('reports removed only for agents that were actually configured', () => {
+    // Install on Claude only; the rest stay untouched.
+    getTarget('claude')!.install('global', { autoAllow: true });
+
+    const reports = uninstallTargets(ALL_TARGETS, 'global');
+
+    const claude = reports.find((r) => r.id === 'claude')!;
+    expect(claude.status).toBe('removed');
+    expect(claude.displayName).toBe(getTarget('claude')!.displayName);
+
+    for (const r of reports.filter((x) => x.id !== 'claude')) {
+      expect(r.status).toBe('not-configured');
+    }
+  });
+
+  it('marks global-only agents as unsupported for a local sweep (and never touches them)', () => {
+    const reports = uninstallTargets(ALL_TARGETS, 'local');
+    for (const t of ALL_TARGETS) {
+      const r = reports.find((x) => x.id === t.id)!;
+      if (t.supportsLocation('local')) {
+        expect(r.status).toBe('not-configured');
+      } else {
+        expect(r.status).toBe('unsupported');
+        expect(r.removedPaths).toEqual([]);
+        expect(r.notes[0]).toMatch(/global-only/);
+      }
+    }
+  });
+
+  it('is idempotent — a second sweep finds nothing left to remove', () => {
+    for (const t of ALL_TARGETS) {
+      if (t.supportsLocation('global')) t.install('global', { autoAllow: true });
+    }
+    const first = uninstallTargets(ALL_TARGETS, 'global');
+    expect(first.some((r) => r.status === 'removed')).toBe(true);
+
+    const second = uninstallTargets(ALL_TARGETS, 'global');
+    for (const r of second) {
+      expect(r.status).toBe('not-configured');
+      expect(r.removedPaths).toEqual([]);
+    }
+  });
+
+  it('a --target subset removes only the chosen agents, leaving siblings configured', () => {
+    getTarget('claude')!.install('global', { autoAllow: true });
+    getTarget('cursor')!.install('global', { autoAllow: true });
+
+    const reports = uninstallTargets(resolveTargetFlag('claude', 'global'), 'global');
+
+    expect(reports.map((r) => r.id)).toEqual(['claude']);
+    expect(reports[0].status).toBe('removed');
+    // Cursor was not in the subset — still configured.
+    expect(getTarget('cursor')!.detect('global').alreadyConfigured).toBe(true);
+    expect(getTarget('claude')!.detect('global').alreadyConfigured).toBe(false);
+  });
+});
+
+describe('Installer — Cursor rules file cleanup on uninstall', () => {
+  let tmpHome: string;
+  let tmpCwd: string;
+  let origCwd: string;
+  let homeRestore: { restore: () => void };
+  const cursor = getTarget('cursor')!;
+
+  beforeEach(() => {
+    tmpHome = mkTmpDir('cur-home');
+    tmpCwd = mkTmpDir('cur-cwd');
+    origCwd = process.cwd();
+    process.chdir(tmpCwd);
+    homeRestore = setHome(tmpHome);
+  });
+
+  afterEach(() => {
+    homeRestore.restore();
+    process.chdir(origCwd);
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+    fs.rmSync(tmpCwd, { recursive: true, force: true });
+  });
+
+  const rulesFile = () => path.join(process.cwd(), '.cursor', 'rules', 'codegraph.mdc');
+
+  // The frontmatter a previous install wrote ahead of the marked block.
+  // `removeRulesEntry` recognizes it to decide whether the leftover .mdc
+  // is ours-to-delete or carries user content worth keeping.
+  const MDC_FRONTMATTER = [
+    '---',
+    'description: CodeGraph MCP usage guide — when to use which tool',
+    'alwaysApply: true',
+    '---',
+    '',
+  ].join('\n');
+
+  function plantLegacyRulesFile(extra = ''): void {
+    fs.mkdirSync(path.dirname(rulesFile()), { recursive: true });
+    fs.writeFileSync(rulesFile(), MDC_FRONTMATTER + LEGACY_BLOCK + '\n' + extra);
+  }
+
+  it('uninstall deletes a leftover codegraph.mdc entirely (no orphaned frontmatter left behind)', () => {
+    plantLegacyRulesFile();
+    expect(fs.existsSync(rulesFile())).toBe(true);
+
+    cursor.uninstall('local');
+
+    // The whole file — frontmatter included — is gone, not just the block.
+    expect(fs.existsSync(rulesFile())).toBe(false);
+  });
+
+  it('install self-heals a leftover codegraph.mdc (#529)', () => {
+    plantLegacyRulesFile();
+    const result = cursor.install('local', { autoAllow: true });
+    expect(fs.existsSync(rulesFile())).toBe(false);
+    expect(result.files.some((f) => f.path.endsWith('codegraph.mdc') && f.action === 'removed')).toBe(true);
+  });
+
+  it('uninstall preserves user content added outside the codegraph markers (strips only our block)', () => {
+    plantLegacyRulesFile('## My own rule\nkeep me\n');
+
+    cursor.uninstall('local');
+
+    expect(fs.existsSync(rulesFile())).toBe(true);
+    const after = fs.readFileSync(rulesFile(), 'utf-8');
+    expect(after).toContain('keep me');
+    // Our tool-usage block is gone.
+    expect(after).not.toContain('codegraph_search');
+    expect(after).not.toContain('CODEGRAPH_START');
+  });
+});
+
 function listAllFiles(dir: string): string[] {
   if (!fs.existsSync(dir)) return [];
   const out: string[] = [];
diff --git a/__tests__/installer.test.ts b/__tests__/installer.test.ts
index 728ed7c35..6f174f62d 100644
--- a/__tests__/installer.test.ts
+++ b/__tests__/installer.test.ts
@@ -3,7 +3,10 @@
  *
  * Tests for installer config-writer fixes:
  * - readJsonFile error handling
- * - writeClaudeMd section replacement
+ *
+ * (The CLAUDE.md instructions block is no longer written — see issue
+ * #529. The marker-based install/uninstall self-heal is covered in
+ * `installer-targets.test.ts`.)
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
@@ -14,11 +17,6 @@ import * as os from 'os';
 // We test the exported functions from config-writer
 import {
   writeMcpConfig,
-  writePermissions,
-  writeClaudeMd,
-  hasMcpConfig,
-  hasPermissions,
-  hasClaudeMdSection,
 } from '../src/installer/config-writer';
 
 function createTempDir(): string {
@@ -103,118 +101,4 @@ describe('Installer Config Writer', () => {
       expect(content.customField).toBe('preserved');
     });
   });
-
-  describe('writeClaudeMd section replacement', () => {
-    it('should create new CLAUDE.md with markers', () => {
-      const result = writeClaudeMd('local');
-
-      expect(result.created).toBe(true);
-      const content = fs.readFileSync(path.join(tempDir, '.claude', 'CLAUDE.md'), 'utf-8');
-      expect(content).toContain('<!-- CODEGRAPH_START -->');
-      expect(content).toContain('<!-- CODEGRAPH_END -->');
-      expect(content).toContain('## CodeGraph');
-    });
-
-    it('should replace marked section on update', () => {
-      // First write
-      writeClaudeMd('local');
-
-      // Modify file to add custom content before and after
-      const claudeMdPath = path.join(tempDir, '.claude', 'CLAUDE.md');
-      const original = fs.readFileSync(claudeMdPath, 'utf-8');
-      const modified = '## My Custom Section\n\nCustom content\n\n' + original + '\n\n## Another Section\n\nMore content\n';
-      fs.writeFileSync(claudeMdPath, modified);
-
-      // Second write should leave the marked block as-is (byte-identical
-      // body, so result is `created:false, updated:false` — both flags
-      // are off but the surrounding custom content must survive).
-      writeClaudeMd('local');
-
-      const final = fs.readFileSync(claudeMdPath, 'utf-8');
-      expect(final).toContain('## My Custom Section');
-      expect(final).toContain('Custom content');
-      expect(final).toContain('## Another Section');
-      expect(final).toContain('More content');
-      expect(final).toContain('## CodeGraph');
-    });
-
-    it('should use atomic writes (no temp files left behind)', () => {
-      writeClaudeMd('local');
-
-      const claudeDir = path.join(tempDir, '.claude');
-      const files = fs.readdirSync(claudeDir);
-      const tmpFiles = files.filter(f => f.includes('.tmp.'));
-      expect(tmpFiles).toHaveLength(0);
-    });
-
-    it('should not overwrite content after unmarked section with ### subsections', () => {
-      // Create a CLAUDE.md with an unmarked CodeGraph section that has ### subsections
-      // followed by another ## section
-      const claudeDir = path.join(tempDir, '.claude');
-      fs.mkdirSync(claudeDir, { recursive: true });
-      const claudeMdPath = path.join(claudeDir, 'CLAUDE.md');
-      fs.writeFileSync(claudeMdPath, [
-        '## Pre-existing Section',
-        '',
-        'Some content',
-        '',
-        '## CodeGraph',
-        '',
-        '### Subsection A',
-        '',
-        'Old codegraph content',
-        '',
-        '### Subsection B',
-        '',
-        'More old content',
-        '',
-        '## Important Section After',
-        '',
-        'This content must not be overwritten!',
-        '',
-      ].join('\n'));
-
-      const result = writeClaudeMd('local');
-      expect(result.updated).toBe(true);
-
-      const final = fs.readFileSync(claudeMdPath, 'utf-8');
-      // The section after CodeGraph must be preserved
-      expect(final).toContain('## Important Section After');
-      expect(final).toContain('This content must not be overwritten!');
-      // Pre-existing section should also be preserved
-      expect(final).toContain('## Pre-existing Section');
-      // New CodeGraph content should be present with markers
-      expect(final).toContain('<!-- CODEGRAPH_START -->');
-      expect(final).toContain('<!-- CODEGRAPH_END -->');
-    });
-
-    it('should replace unmarked section without subsections', () => {
-      const claudeDir = path.join(tempDir, '.claude');
-      fs.mkdirSync(claudeDir, { recursive: true });
-      const claudeMdPath = path.join(claudeDir, 'CLAUDE.md');
-      // Note: regex needs \n before ## CodeGraph, so prefix with another section
-      fs.writeFileSync(claudeMdPath, [
-        '## Intro',
-        '',
-        'Preamble',
-        '',
-        '## CodeGraph',
-        '',
-        'Old simple content',
-        '',
-        '## Next Section',
-        '',
-        'Must be preserved',
-        '',
-      ].join('\n'));
-
-      writeClaudeMd('local');
-
-      const final = fs.readFileSync(claudeMdPath, 'utf-8');
-      expect(final).toContain('<!-- CODEGRAPH_START -->');
-      expect(final).toContain('## Next Section');
-      expect(final).toContain('Must be preserved');
-      expect(final).not.toContain('Old simple content');
-    });
-  });
 });
diff --git a/__tests__/integration/full-pipeline.test.ts b/__tests__/integration/full-pipeline.test.ts
new file mode 100644
index 000000000..5b551c136
--- /dev/null
+++ b/__tests__/integration/full-pipeline.test.ts
@@ -0,0 +1,272 @@
+/**
+ * End-to-end pipeline integration tests
+ *
+ * Exercises the full happy path that unit tests cover in isolation:
+ *   init → indexAll → resolveReferences → searchNodes/getCallers/buildContext → sync
+ *
+ * Also covers two error paths that were previously uncovered:
+ *   - Indexing a file that contains a syntactically invalid snippet
+ *     (parse errors must not abort the batch).
+ *   - Sync correctly applies adds + modifies + removes in a single pass.
+ *
+ * A synthetic ~120-file project is generated per test (5k files would
+ * dwarf the test runner; 120 files of varied TS shape is enough to
+ * stress the resolver and graph layers without slowing the suite to a
+ * crawl).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../../src/index';
+
+function createTempDir(prefix = 'codegraph-int-'): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function cleanupTempDir(dir: string): void {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Generate a synthetic TypeScript project with the given module count.
+ * Each module exports a function that calls the previous module's
+ * function so that the resolver has real import edges + call edges to
+ * resolve. The first module is a leaf; the last is the root.
+ */
+function generateSyntheticProject(root: string, moduleCount: number): void {
+  const srcDir = path.join(root, 'src');
+  fs.mkdirSync(srcDir, { recursive: true });
+
+  // Leaf module — no imports.
+  fs.writeFileSync(
+    path.join(srcDir, `mod0.ts`),
+    `export function fn0(x: number): number { return x + 1; }\n` +
+      `export class Mod0 { ping(): string { return 'mod0'; } }\n`
+  );
+
+  for (let i = 1; i < moduleCount; i++) {
+    const prev = i - 1;
+    fs.writeFileSync(
+      path.join(srcDir, `mod${i}.ts`),
+      `import { fn${prev}, Mod${prev} } from './mod${prev}';\n` +
+        `export function fn${i}(x: number): number { return fn${prev}(x) + 1; }\n` +
+        `export class Mod${i} extends Mod${prev} {\n` +
+        `  call${i}(): number { return fn${i}(${i}); }\n` +
+        `}\n`
+    );
+  }
+
+  // Entry point file.
+  fs.writeFileSync(
+    path.join(srcDir, 'index.ts'),
+    `import { fn${moduleCount - 1}, Mod${moduleCount - 1} } from './mod${moduleCount - 1}';\n` +
+      `export function entry(): number {\n` +
+      `  const m = new Mod${moduleCount - 1}();\n` +
+      `  return fn${moduleCount - 1}(0) + m.call${moduleCount - 1}();\n` +
+      `}\n`
+  );
+}
+
+describe('Integration: full pipeline', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    cleanupTempDir(tempDir);
+  });
+
+  it('runs init → index → resolve → search → callers → context → sync', async () => {
+    const MODULE_COUNT = 120;
+    generateSyntheticProject(tempDir, MODULE_COUNT);
+
+    // ── init ──────────────────────────────────────────────────────
+    const cg = await CodeGraph.init(tempDir, {
+      config: { include: ['**/*.ts'], exclude: [] },
+    });
+
+    try {
+      // ── indexAll ────────────────────────────────────────────────
+      const indexResult = await cg.indexAll();
+      // Synthetic project: MODULE_COUNT mod files + 1 index file.
+      expect(indexResult.filesIndexed).toBeGreaterThanOrEqual(MODULE_COUNT);
+
+      const statsAfterIndex = cg.getStats();
+      expect(statsAfterIndex.fileCount).toBeGreaterThanOrEqual(MODULE_COUNT);
+      expect(statsAfterIndex.nodeCount).toBeGreaterThan(MODULE_COUNT * 2);
+
+      // ── resolveReferences ────────────────────────────────────────
+      // Many call-site edges are wired up during extraction itself, so
+      // the unresolved-reference queue may already be drained by the
+      // time we get here. We assert that resolve completes cleanly and
+      // returns a well-formed result; downstream callers/callees
+      // assertions verify the graph is actually populated.
+      cg.reinitializeResolver();
+      const resolution = cg.resolveReferences();
+      expect(resolution).toBeDefined();
+      expect(resolution.stats).toBeDefined();
+      expect(typeof resolution.stats.total).toBe('number');
+      expect(typeof resolution.stats.resolved).toBe('number');
+
+      // ── searchNodes ──────────────────────────────────────────────
+      const entryResults = cg.searchNodes('entry', { limit: 10 });
+      expect(entryResults.length).toBeGreaterThan(0);
+      const entryNode = entryResults.find((r) => r.node.name === 'entry');
+      expect(entryNode).toBeDefined();
+
+      const midResults = cg.searchNodes(`fn50`, { limit: 10 });
+      expect(midResults.find((r) => r.node.name === 'fn50')).toBeDefined();
+
+      // ── getCallers / getCallees ──────────────────────────────────
+      const fn0Results = cg.searchNodes('fn0', { limit: 5 });
+      const fn0Node = fn0Results.find((r) => r.node.name === 'fn0');
+      expect(fn0Node).toBeDefined();
+      const callers = cg.getCallers(fn0Node!.node.id);
+      // fn0 is called by fn1 (at least). After resolution this should
+      // be wired up.
+      expect(Array.isArray(callers)).toBe(true);
+
+      // ── buildContext ─────────────────────────────────────────────
+      const context = await cg.buildContext('entry function chain', {
+        maxNodes: 10,
+        format: 'markdown',
+      });
+      expect(typeof context).toBe('string');
+      expect((context as string).length).toBeGreaterThan(0);
+
+      // ── sync (add + modify + remove in one pass) ─────────────────
+      // Add: a new file referencing entry().
+      fs.writeFileSync(
+        path.join(tempDir, 'src', 'consumer.ts'),
+        `import { entry } from './index';\nexport const result = entry();\n`
+      );
+      // Modify: change mod0.
+      fs.writeFileSync(
+        path.join(tempDir, 'src', 'mod0.ts'),
+        `export function fn0(x: number): number { return x + 2; }\n` +
+          `export function newHelper(): string { return 'new'; }\n` +
+          `export class Mod0 { ping(): string { return 'mod0v2'; } }\n`
+      );
+      // Remove: drop mod1 — note this will leave dangling imports in
+      // mod2, which the resolver should tolerate.
+      fs.unlinkSync(path.join(tempDir, 'src', 'mod1.ts'));
+
+      const syncResult = await cg.sync();
+      expect(syncResult.filesAdded).toBeGreaterThanOrEqual(1);
+      expect(syncResult.filesModified).toBeGreaterThanOrEqual(1);
+      expect(syncResult.filesRemoved).toBeGreaterThanOrEqual(1);
+
+      // New symbol must now be findable; removed file's symbols gone.
+      expect(cg.searchNodes('newHelper').length).toBeGreaterThan(0);
+
+      // Removed file should no longer appear in the indexed file list.
+      // (FTS prefix matching makes name-based assertions unreliable here —
+      // Mod10/Mod11/… all start with "Mod1" — so we check the file set
+      // instead.)
+      const filesAfterSync = cg.getNodesInFile('src/mod1.ts');
+      expect(filesAfterSync).toHaveLength(0);
+    } finally {
+      cg.destroy();
+    }
+  }, 60_000);
+
+  it('keeps indexing files when one file has a parse error', async () => {
+    const srcDir = path.join(tempDir, 'src');
+    fs.mkdirSync(srcDir, { recursive: true });
+
+    // Valid files
+    fs.writeFileSync(
+      path.join(srcDir, 'good1.ts'),
+      `export function good1(): number { return 1; }\n`
+    );
+    fs.writeFileSync(
+      path.join(srcDir, 'good2.ts'),
+      `export function good2(): number { return 2; }\n`
+    );
+    // Intentionally broken file — unclosed brace, stray tokens.
+    fs.writeFileSync(
+      path.join(srcDir, 'broken.ts'),
+      `export function broken(\n  this is { not valid typescript at all\n`
+    );
+
+    const cg = await CodeGraph.init(tempDir, {
+      config: { include: ['**/*.ts'], exclude: [] },
+    });
+
+    try {
+      const result = await cg.indexAll();
+      // The two good files must still be indexed regardless of the
+      // broken one. Tree-sitter is error-tolerant so it may still
+      // extract a partial AST from broken.ts — but the test only
+      // requires that the batch completes and finds the good symbols.
+      expect(result.filesIndexed).toBeGreaterThanOrEqual(2);
+
+      const good1 = cg.searchNodes('good1');
+      const good2 = cg.searchNodes('good2');
+      expect(good1.find((r) => r.node.name === 'good1')).toBeDefined();
+      expect(good2.find((r) => r.node.name === 'good2')).toBeDefined();
+    } finally {
+      cg.destroy();
+    }
+  }, 30_000);
+
+  it('handles repeated sync calls when nothing has changed', async () => {
+    generateSyntheticProject(tempDir, 10);
+
+    const cg = await CodeGraph.init(tempDir, {
+      config: { include: ['**/*.ts'], exclude: [] },
+    });
+
+    try {
+      await cg.indexAll();
+      const statsBefore = cg.getStats();
+
+      const first = await cg.sync();
+      const second = await cg.sync();
+
+      // Subsequent sync with no changes should be a no-op.
+      expect(first.filesAdded + first.filesModified + first.filesRemoved).toBe(0);
+      expect(second.filesAdded + second.filesModified + second.filesRemoved).toBe(0);
+
+      const statsAfter = cg.getStats();
+      expect(statsAfter.fileCount).toBe(statsBefore.fileCount);
+      expect(statsAfter.nodeCount).toBe(statsBefore.nodeCount);
+    } finally {
+      cg.destroy();
+    }
+  }, 30_000);
+
+  it('reports edgesCreated including resolution + synthesizer phases', async () => {
+    // The synthetic project has cross-file imports, calls, and extends —
+    // all wired up in the resolution phase, AFTER the orchestrator's
+    // per-file extraction counter is done. The CLI summary used to read
+    // only the extraction-phase counter and undercount the graph; this
+    // test pins the counter to the true DB totals across all phases.
+    generateSyntheticProject(tempDir, 30);
+
+    const cg = await CodeGraph.init(tempDir, {
+      config: { include: ['**/*.ts'], exclude: [] },
+    });
+
+    try {
+      const result = await cg.indexAll();
+      const stats = cg.getStats();
+
+      expect(result.success).toBe(true);
+      expect(result.nodesCreated).toBe(stats.nodeCount);
+      expect(result.edgesCreated).toBe(stats.edgeCount);
+      // Sanity: cross-file resolution had something to do — calls/extends
+      // edges should exist beyond the bare extraction-time contains edges.
+      const containsOnly = stats.edgesByKind.contains ?? 0;
+      expect(stats.edgeCount).toBeGreaterThan(containsOnly);
+    } finally {
+      cg.destroy();
+    }
+  }, 30_000);
+});
diff --git a/__tests__/integration/lru-cache.test.ts b/__tests__/integration/lru-cache.test.ts
new file mode 100644
index 000000000..8156760ae
--- /dev/null
+++ b/__tests__/integration/lru-cache.test.ts
@@ -0,0 +1,96 @@
+/**
+ * LRUCache unit tests
+ *
+ * Covers the eviction guarantees that the resolver relies on:
+ *   - capacity is enforced (never exceeds max)
+ *   - LRU ordering: hot keys survive eviction passes
+ *   - has()/get()/set()/clear() behave like the original Map shape
+ *   - null values are storable (the fileCache uses null for "failed read")
+ */
+
+import { describe, it, expect } from 'vitest';
+import { LRUCache } from '../../src/resolution/lru-cache';
+
+describe('LRUCache', () => {
+  it('enforces capacity by evicting the oldest entry on overflow', () => {
+    const cache = new LRUCache<string, number>(3);
+    cache.set('a', 1);
+    cache.set('b', 2);
+    cache.set('c', 3);
+    cache.set('d', 4); // evicts 'a'
+
+    expect(cache.size).toBe(3);
+    expect(cache.has('a')).toBe(false);
+    expect(cache.get('a')).toBeUndefined();
+    expect(cache.get('b')).toBe(2);
+    expect(cache.get('c')).toBe(3);
+    expect(cache.get('d')).toBe(4);
+  });
+
+  it('promotes touched keys to most-recent so they survive eviction', () => {
+    const cache = new LRUCache<string, number>(3);
+    cache.set('a', 1);
+    cache.set('b', 2);
+    cache.set('c', 3);
+
+    // Touch 'a' — it should now be most-recent.
+    expect(cache.get('a')).toBe(1);
+
+    cache.set('d', 4); // evicts the LRU, which is now 'b' (not 'a')
+
+    expect(cache.has('a')).toBe(true);
+    expect(cache.has('b')).toBe(false);
+    expect(cache.has('c')).toBe(true);
+    expect(cache.has('d')).toBe(true);
+  });
+
+  it('overwriting an existing key refreshes its recency but does not grow size', () => {
+    const cache = new LRUCache<string, number>(2);
+    cache.set('a', 1);
+    cache.set('b', 2);
+    cache.set('a', 99); // 'a' is now most-recent
+
+    expect(cache.size).toBe(2);
+    expect(cache.get('a')).toBe(99);
+
+    cache.set('c', 3); // should evict 'b', not 'a'
+
+    expect(cache.has('a')).toBe(true);
+    expect(cache.has('b')).toBe(false);
+    expect(cache.has('c')).toBe(true);
+  });
+
+  it('stores null values (used by the file content cache)', () => {
+    const cache = new LRUCache<string, string | null>(2);
+    cache.set('missing.ts', null);
+    expect(cache.has('missing.ts')).toBe(true);
+    expect(cache.get('missing.ts')).toBeNull();
+  });
+
+  it('clear() resets the cache', () => {
+    const cache = new LRUCache<string, number>(3);
+    cache.set('a', 1);
+    cache.set('b', 2);
+    cache.clear();
+    expect(cache.size).toBe(0);
+    expect(cache.has('a')).toBe(false);
+  });
+
+  it('rejects non-positive capacity', () => {
+    expect(() => new LRUCache(0)).toThrow();
+    expect(() => new LRUCache(-1)).toThrow();
+    expect(() => new LRUCache(NaN)).toThrow();
+  });
+
+  it('stays bounded under heavy churn (regression for OOM scenario)', () => {
+    const cache = new LRUCache<string, number>(100);
+    for (let i = 0; i < 10_000; i++) {
+      cache.set(`key${i}`, i);
+    }
+    expect(cache.size).toBe(100);
+    // The last 100 keys should still be present, the rest evicted.
+    expect(cache.has('key9999')).toBe(true);
+    expect(cache.has('key9900')).toBe(true);
+    expect(cache.has('key0')).toBe(false);
+  });
+});
diff --git a/__tests__/integration/mcp-input-limits.test.ts b/__tests__/integration/mcp-input-limits.test.ts
new file mode 100644
index 000000000..7471f8289
--- /dev/null
+++ b/__tests__/integration/mcp-input-limits.test.ts
@@ -0,0 +1,109 @@
+/**
+ * MCP tool input-size limits
+ *
+ * Regression coverage for the DoS vector: MCP clients can ship
+ * unbounded payloads (`query`, `task`, `symbol`, `projectPath`,
+ * `path`, `pattern`). Before the cap, a 100MB string would hit
+ * the FTS5 layer and pin the server. These tests assert that the
+ * tool layer rejects oversize inputs early.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../../src/index';
+import { ToolHandler } from '../../src/mcp/tools';
+
+describe('MCP input size limits', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+  let handler: ToolHandler;
+
+  beforeEach(async () => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-mcp-limits-'));
+    fs.mkdirSync(path.join(tempDir, 'src'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tempDir, 'src', 'a.ts'),
+      `export function alpha(): number { return 1; }\n`
+    );
+    cg = await CodeGraph.init(tempDir, {
+      config: { include: ['**/*.ts'], exclude: [] },
+    });
+    await cg.indexAll();
+    handler = new ToolHandler(cg);
+  });
+
+  afterEach(() => {
+    if (cg) cg.destroy();
+    if (fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it('accepts a normal-sized query', async () => {
+    const result = await handler.execute('codegraph_search', { query: 'alpha' });
+    expect(result.isError).toBeFalsy();
+  });
+
+  it('rejects an oversize query on codegraph_search', async () => {
+    const huge = 'a'.repeat(20_000);
+    const result = await handler.execute('codegraph_search', { query: huge });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toMatch(/maximum length/i);
+  });
+
+  it('rejects an oversize query on codegraph_explore', async () => {
+    const huge = 'b'.repeat(50_000);
+    const result = await handler.execute('codegraph_explore', { query: huge });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toMatch(/maximum length/i);
+  });
+
+  it('rejects an oversize symbol on codegraph_callers', async () => {
+    const huge = 'c'.repeat(15_000);
+    const result = await handler.execute('codegraph_callers', { symbol: huge });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toMatch(/maximum length/i);
+  });
+
+  it('rejects an oversize symbol on codegraph_impact', async () => {
+    const huge = 'd'.repeat(11_000);
+    const result = await handler.execute('codegraph_impact', { symbol: huge });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toMatch(/maximum length/i);
+  });
+
+  it('rejects an oversize projectPath', async () => {
+    const hugePath = '/tmp/' + 'x'.repeat(5_000);
+    const result = await handler.execute('codegraph_search', {
+      query: 'alpha',
+      projectPath: hugePath,
+    });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toMatch(/projectPath/);
+  });
+
+  it('rejects an oversize path filter on codegraph_files', async () => {
+    const hugePath = 'src/' + 'y'.repeat(5_000);
+    const result = await handler.execute('codegraph_files', { path: hugePath });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toMatch(/path/);
+  });
+
+  it('rejects an oversize glob pattern on codegraph_files', async () => {
+    const hugePattern = '*'.repeat(5_000);
+    const result = await handler.execute('codegraph_files', { pattern: hugePattern });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toMatch(/pattern/);
+  });
+
+  it('rejects a non-string projectPath', async () => {
+    const result = await handler.execute('codegraph_search', {
+      query: 'alpha',
+      projectPath: 12345 as unknown as string,
+    });
+    expect(result.isError).toBe(true);
+    expect(result.content[0]!.text).toMatch(/projectPath/);
+  });
+});
diff --git a/__tests__/iterate-nodes-by-kind.test.ts b/__tests__/iterate-nodes-by-kind.test.ts
new file mode 100644
index 000000000..19ee05f67
--- /dev/null
+++ b/__tests__/iterate-nodes-by-kind.test.ts
@@ -0,0 +1,62 @@
+/**
+ * `QueryBuilder.iterateNodesByKind` — the streaming scan that fixes the #610
+ * OOM. The dynamic-edge synthesizers used to `getNodesByKind('function')` /
+ * `('method')`, materializing every symbol into one array (gigabytes on a
+ * symbol-dense project → JS-heap OOM). They now iterate. These tests pin the
+ * two properties that refactor relies on: the streamed set equals the eager
+ * set, and an open iterator cursor coexists with other queries on the same
+ * connection.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src/index';
+
+describe('iterateNodesByKind (#610 streaming)', () => {
+  let dir: string;
+  let cg: CodeGraph;
+
+  beforeEach(async () => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-iter-'));
+    fs.mkdirSync(path.join(dir, 'src'));
+    fs.writeFileSync(
+      path.join(dir, 'src', 'a.ts'),
+      'export function foo() { return 1; }\n' +
+      'export function bar() { return 2; }\n' +
+      'export class C { m() { return 3; } n() { return 4; } }\n'
+    );
+    cg = CodeGraph.initSync(dir, { config: { include: ['**/*.ts'], exclude: [] } });
+    await cg.indexAll();
+  });
+
+  afterEach(() => {
+    try { cg.close(); } catch { /* ignore */ }
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('yields exactly the same nodes as the eager getNodesByKind', () => {
+    const q = (cg as unknown as { queries: any }).queries;
+    for (const kind of ['function', 'method', 'class'] as const) {
+      const eager = q.getNodesByKind(kind).map((n: any) => n.id).sort();
+      const streamed = [...q.iterateNodesByKind(kind)].map((n: any) => n.id).sort();
+      expect(streamed).toEqual(eager);
+    }
+    // sanity: the fixture actually produced functions + methods to stream
+    expect([...q.iterateNodesByKind('function')].length).toBeGreaterThan(0);
+    expect([...q.iterateNodesByKind('method')].length).toBeGreaterThan(0);
+  });
+
+  it('keeps the cursor valid while other queries run mid-iteration', () => {
+    const q = (cg as unknown as { queries: any }).queries;
+    let seen = 0;
+    for (const n of q.iterateNodesByKind('function')) {
+      // A different prepared statement stepped on the same connection while the
+      // iterator's cursor is open must not corrupt it.
+      const again = q.getNodeById(n.id);
+      expect(again?.id).toBe(n.id);
+      seen++;
+    }
+    expect(seen).toBe(q.getNodesByKind('function').length);
+  });
+});
diff --git a/__tests__/mcp-catchup-gate.test.ts b/__tests__/mcp-catchup-gate.test.ts
new file mode 100644
index 000000000..6baee07c4
--- /dev/null
+++ b/__tests__/mcp-catchup-gate.test.ts
@@ -0,0 +1,122 @@
+/**
+ * MCP catch-up gate — first tool call blocks on the engine's post-open
+ * filesystem reconcile so it never serves rows for files that were
+ * deleted (or edited) while no MCP server was running.
+ *
+ * Background: `MCPEngine.catchUpSync()` fires `cg.sync()` in the background.
+ * Before this fix it was fire-and-forget — a tool call could race past it
+ * and return rows for files that no longer exist on disk. The per-file
+ * staleness banner (`withStalenessNotice`) couldn't help, because
+ * `getPendingFiles()` is populated by the watcher, not by catch-up.
+ *
+ * The fix: `catchUpSync()` pushes its promise into the `ToolHandler` via
+ * `setCatchUpGate(p)`; the first `execute()` call awaits the gate and then
+ * clears it. These tests exercise the gate directly (deterministic) and
+ * the engine-driven path (proves the engine actually pokes the gate).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src/index';
+import { ToolHandler } from '../src/mcp/tools';
+
+describe('MCP catch-up gate', () => {
+  let testDir: string;
+  let cg: CodeGraph;
+  let handler: ToolHandler;
+
+  beforeEach(async () => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-catchup-gate-'));
+    fs.mkdirSync(path.join(testDir, 'src'));
+    fs.writeFileSync(
+      path.join(testDir, 'src', 'survivor.ts'),
+      'export function survivor() { return 1; }\n',
+    );
+    fs.writeFileSync(
+      path.join(testDir, 'src', 'deleted-later.ts'),
+      'export function deletedLater() { return 2; }\n',
+    );
+
+    cg = CodeGraph.initSync(testDir, { config: { include: ['**/*.ts'], exclude: [] } });
+    await cg.indexAll();
+    handler = new ToolHandler(cg);
+  });
+
+  afterEach(() => {
+    try { cg.unwatch(); } catch { /* ignore */ }
+    try { cg.close(); } catch { /* ignore */ }
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('awaits the gate before serving the first tool call', async () => {
+    let gateResolved = false;
+    const gate = new Promise<void>((resolve) => {
+      setTimeout(() => { gateResolved = true; resolve(); }, 80);
+    });
+    handler.setCatchUpGate(gate);
+
+    const res = await handler.execute('codegraph_search', { query: 'survivor' });
+    expect(gateResolved).toBe(true);
+    expect(res.isError).toBeFalsy();
+    expect(res.content[0].text).toMatch(/survivor/);
+  });
+
+  it('drops the gate after first await — second call does not re-wait', async () => {
+    let awaitCount = 0;
+    const gate = new Promise<void>((resolve) => {
+      awaitCount++;
+      setTimeout(resolve, 20);
+    });
+    handler.setCatchUpGate(gate);
+
+    await handler.execute('codegraph_search', { query: 'survivor' });
+    const before = awaitCount;
+    await handler.execute('codegraph_search', { query: 'survivor' });
+    // The promise body runs once when constructed; second execute never
+    // resubscribes to a fresh promise because the gate field was nulled.
+    expect(awaitCount).toBe(before);
+  });
+
+  it('catch-up reconciles a deleted file before the first tool call sees it', async () => {
+    // Simulate the empty-project / deleted-files startup case: file is in
+    // the DB (we indexed it above) but vanishes from disk before the MCP
+    // server's first query. The catch-up sync, awaited via the gate,
+    // must remove the row so the first tool call returns no hit.
+    fs.unlinkSync(path.join(testDir, 'src', 'deleted-later.ts'));
+
+    // Push the actual catch-up sync as the gate — same flow the MCP engine
+    // uses (`cg.sync()` returns a Promise<SyncResult>, the wrapper voids it).
+    handler.setCatchUpGate(cg.sync().then(() => undefined));
+
+    const res = await handler.execute('codegraph_search', { query: 'deletedLater' });
+    expect(res.isError).toBeFalsy();
+    const text = res.content[0].text;
+    expect(text).not.toMatch(/src\/deleted-later\.ts/);
+  });
+
+  it('catch-up that converges the project to 0 files clears all rows', async () => {
+    // Worst case: every source file is gone between sessions. Without the
+    // gate, the first tool call serves whatever was in the DB. With the
+    // gate + the orchestrator's filesystem reconcile, the DB drains.
+    fs.unlinkSync(path.join(testDir, 'src', 'survivor.ts'));
+    fs.unlinkSync(path.join(testDir, 'src', 'deleted-later.ts'));
+
+    handler.setCatchUpGate(cg.sync().then(() => undefined));
+
+    const res = await handler.execute('codegraph_search', { query: 'survivor' });
+    expect(res.isError).toBeFalsy();
+    expect(cg.getStats().fileCount).toBe(0);
+  });
+
+  it('gate that rejects does not break the tool call', async () => {
+    // A catch-up sync failure (lock contention, transient FS error) must
+    // not poison tool dispatch — the engine logs it, the handler proceeds.
+    handler.setCatchUpGate(Promise.reject(new Error('simulated sync failure')));
+
+    const res = await handler.execute('codegraph_search', { query: 'survivor' });
+    expect(res.isError).toBeFalsy();
+    expect(res.content[0].text).toMatch(/survivor/);
+  });
+});
diff --git a/__tests__/mcp-daemon.test.ts b/__tests__/mcp-daemon.test.ts
new file mode 100644
index 000000000..c00d528f6
--- /dev/null
+++ b/__tests__/mcp-daemon.test.ts
@@ -0,0 +1,435 @@
+/**
+ * Shared MCP daemon — issue #411.
+ *
+ * Validates the daemon architecture in `src/mcp/{daemon,proxy,session,index}.ts`
+ * AFTER the review fixes:
+ *
+ *   - The daemon is a *detached* background process; every `serve --mcp`
+ *     invocation is a thin proxy to it. Two invocations against one project
+ *     share ONE daemon.
+ *   - Concurrent launchers converge on a single daemon (the must-fix-1
+ *     lockfile-race: an empty-pidfile window used to let a racing candidate
+ *     delete the winner's lock → two daemons).
+ *   - Killing the launcher that spawned the daemon does NOT take the daemon
+ *     down — other attached clients keep working (the must-fix-2 detach: the
+ *     in-process daemon used to die with its launcher's process group and
+ *     orphan on host SIGKILL, regressing #277).
+ *   - A stale lockfile (dead pid) is cleared; `CODEGRAPH_NO_DAEMON=1` opts out;
+ *     the proxy refuses to attach across a version mismatch; the daemon
+ *     idle-times-out after the last client leaves (so a single session can't
+ *     leak a daemon forever).
+ *
+ * These tests intentionally spawn real `node dist/bin/codegraph.js` processes
+ * over real sockets/pipes — the same surface a Claude Code / Cursor / Codex
+ * install exercises. The daemon logs to `.codegraph/daemon.log` (it has no
+ * client stderr of its own), so daemon-side assertions read that file.
+ *
+ * `realRoot` vs `tempDir`: processes are spawned with the (possibly symlinked)
+ * `tempDir` as cwd/rootUri — on macOS `os.tmpdir()` lives under `/var`, a
+ * symlink to `/private/var`, and a spawned child's `process.cwd()` is already
+ * realpath'd. The daemon canonicalizes the root with `realpathSync`, so all
+ * path assertions use `realRoot` (the canonical form). That this matches end to
+ * end is itself the proof the canonicalization works.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ChildProcessWithoutNullStreams, spawn } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { CodeGraph } from '../src';
+import { getDaemonSocketPath } from '../src/mcp/daemon-paths';
+
+const BIN = path.resolve(__dirname, '../dist/bin/codegraph.js');
+
+interface SpawnedServer {
+  child: ChildProcessWithoutNullStreams;
+  stdout: string[];
+  stderr: string[];
+}
+
+function spawnServer(cwd: string, env: NodeJS.ProcessEnv = {}): SpawnedServer {
+  const child = spawn(process.execPath, [BIN, 'serve', '--mcp'], {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    // #618: the daemon-attach log line is now off by default; opt the test
+    // harness into it (CODEGRAPH_MCP_LOG_ATTACH=1) so the attach assertions
+    // below can still observe a successful attach. A per-test env still wins.
+    env: { CODEGRAPH_MCP_LOG_ATTACH: '1', ...process.env, ...env },
+  }) as ChildProcessWithoutNullStreams;
+  // Swallow spawn/EPIPE errors so killing a child mid-write can't surface as an
+  // unhandled error that crashes the vitest worker.
+  child.on('error', () => { /* ignore */ });
+  child.stdin.on('error', () => { /* ignore */ });
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  let stdoutBuf = '';
+  let stderrBuf = '';
+  child.stdout.on('data', (chunk: Buffer) => {
+    stdoutBuf += chunk.toString('utf8');
+    let idx: number;
+    while ((idx = stdoutBuf.indexOf('\n')) !== -1) {
+      stdout.push(stdoutBuf.slice(0, idx));
+      stdoutBuf = stdoutBuf.slice(idx + 1);
+    }
+  });
+  child.stderr.on('data', (chunk: Buffer) => {
+    stderrBuf += chunk.toString('utf8');
+    let idx: number;
+    while ((idx = stderrBuf.indexOf('\n')) !== -1) {
+      stderr.push(stderrBuf.slice(0, idx));
+      stderrBuf = stderrBuf.slice(idx + 1);
+    }
+  });
+  return { child, stdout, stderr };
+}
+
+function sendMessage(child: ChildProcessWithoutNullStreams, msg: unknown): void {
+  try { child.stdin.write(JSON.stringify(msg) + '\n'); } catch { /* child may be gone */ }
+}
+
+function sendInitialize(child: ChildProcessWithoutNullStreams, rootUri: string, id: number): void {
+  sendMessage(child, {
+    jsonrpc: '2.0',
+    id,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'test', version: '0.0.0' },
+      rootUri,
+    },
+  });
+}
+
+/** Find a JSON-RPC response with the given id (result OR error) on stdout. */
+function findResponse(stdout: string[], id: number): any | null {
+  for (const line of stdout) {
+    if (!line.trim()) continue;
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && parsed.id === id && (parsed.result !== undefined || parsed.error !== undefined)) {
+        return parsed;
+      }
+    } catch { /* not JSON */ }
+  }
+  return null;
+}
+
+function waitFor<T>(
+  predicate: () => T | undefined | null | false,
+  timeoutMs: number,
+  pollMs = 25,
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const started = Date.now();
+    const tick = () => {
+      let v: T | undefined | null | false;
+      try { v = predicate(); } catch (e) { return reject(e); }
+      if (v) return resolve(v as T);
+      if (Date.now() - started > timeoutMs) return reject(new Error(`Timed out after ${timeoutMs}ms`));
+      setTimeout(tick, pollMs);
+    };
+    tick();
+  });
+}
+
+function isAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function readLockPid(root: string): number | null {
+  try {
+    const raw = fs.readFileSync(path.join(root, '.codegraph', 'daemon.pid'), 'utf8');
+    const info = JSON.parse(raw);
+    return typeof info.pid === 'number' ? info.pid : null;
+  } catch { return null; }
+}
+
+function readDaemonLog(root: string): string {
+  try { return fs.readFileSync(path.join(root, '.codegraph', 'daemon.log'), 'utf8'); }
+  catch { return ''; }
+}
+
+function countListeningLines(root: string): number {
+  return readDaemonLog(root).split('\n').filter((l) => l.includes('[CodeGraph daemon] Listening on')).length;
+}
+
+function killTree(...procs: ChildProcessWithoutNullStreams[]): void {
+  for (const p of procs) {
+    if (!p.killed) { try { p.kill('SIGKILL'); } catch { /* gone */ } }
+  }
+}
+
+async function waitProcessExit(pid: number, timeoutMs: number): Promise<boolean> {
+  return waitFor(() => !isAlive(pid), timeoutMs).then(() => true).catch(() => false);
+}
+
+describe('Shared MCP daemon (issue #411)', () => {
+  let tempDir: string;   // the (possibly symlinked) path processes are spawned with
+  let realRoot: string;  // its canonical form — what the daemon keys paths on
+  const servers: SpawnedServer[] = [];
+
+  beforeEach(async () => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-mcp-daemon-'));
+    const cg = await CodeGraph.init(tempDir);
+    cg.close();
+    realRoot = fs.realpathSync(tempDir);
+  });
+
+  afterEach(async () => {
+    killTree(...servers.map((s) => s.child));
+    // The daemon is detached (not a tracked child) — reap it explicitly via the
+    // pid it recorded, so a test can't leak a background daemon. Guard against
+    // our own pid: the version-mismatch test plants `pid: process.pid` in the
+    // lockfile, and we must never SIGKILL the vitest worker.
+    const daemonPid = readLockPid(realRoot);
+    if (daemonPid && daemonPid !== process.pid && isAlive(daemonPid)) {
+      try { process.kill(daemonPid, 'SIGKILL'); } catch { /* race */ }
+    }
+    await new Promise((r) => setTimeout(r, 50));
+    servers.length = 0;
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('two invocations share ONE detached daemon; both attach as proxies', async () => {
+    const env = { CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS: '15000' };
+
+    const first = spawnServer(tempDir, env);
+    servers.push(first);
+    sendInitialize(first.child, `file://${tempDir}`, 1);
+    const firstResp = await waitFor(() => findResponse(first.stdout, 1), 10000);
+    expect(firstResp.result.serverInfo.name).toBe('codegraph');
+
+    // The launcher is a PROXY (not the daemon itself) — that's the detach fix.
+    await waitFor(() => first.stderr.some((l) => l.includes('Attached to shared daemon')), 8000);
+
+    // A detached daemon came up and recorded itself.
+    await waitFor(() => fs.existsSync(path.join(realRoot, '.codegraph', 'daemon.pid')), 8000);
+    await waitFor(() => countListeningLines(realRoot) >= 1, 8000);
+    const daemonPid = readLockPid(realRoot);
+    expect(daemonPid).toBeTruthy();
+    expect(isAlive(daemonPid!)).toBe(true);
+    // The socket exists at the path the code computes from the canonical root.
+    // On Windows the daemon listens on a named pipe (\\.\pipe\...), which isn't
+    // a filesystem entry — existsSync doesn't apply there, and the "Attached to
+    // shared daemon" proof above already confirms the proxy reached it.
+    if (process.platform !== 'win32') {
+      expect(fs.existsSync(getDaemonSocketPath(realRoot))).toBe(true);
+    }
+
+    // Second invocation attaches as a proxy to the SAME daemon.
+    const second = spawnServer(tempDir, env);
+    servers.push(second);
+    sendInitialize(second.child, `file://${tempDir}`, 2);
+    const secondResp = await waitFor(() => findResponse(second.stdout, 2), 10000);
+    expect(secondResp.result.serverInfo.name).toBe('codegraph');
+    await waitFor(() => second.stderr.some((l) => l.includes('Attached to shared daemon')), 8000);
+
+    // Exactly one daemon ever bound, and it's the same pid both attached to.
+    expect(countListeningLines(realRoot)).toBe(1);
+    expect(readLockPid(realRoot)).toBe(daemonPid);
+  }, 40000);
+
+  it('concurrent launchers converge on a single daemon (lockfile race — must-fix 1)', async () => {
+    const env = { CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS: '15000' };
+
+    // Fire three launchers as close to simultaneously as possible — this is the
+    // race window where the old code could end up with two daemons.
+    const procs = [spawnServer(tempDir, env), spawnServer(tempDir, env), spawnServer(tempDir, env)];
+    procs.forEach((p, i) => { servers.push(p); sendInitialize(p.child, `file://${tempDir}`, i + 1); });
+
+    // All three get a valid initialize response...
+    for (let i = 0; i < procs.length; i++) {
+      const resp = await waitFor(() => findResponse(procs[i].stdout, i + 1), 12000);
+      expect(resp.result.serverInfo.name).toBe('codegraph');
+    }
+    // ...and all three attached as proxies (none fell back / wedged).
+    for (const p of procs) {
+      await waitFor(() => p.stderr.some((l) => l.includes('Attached to shared daemon')), 10000);
+    }
+
+    // The decisive assertion: exactly ONE daemon bound the socket. Losing
+    // candidates log "already holds the lock; exiting" and never listen.
+    expect(countListeningLines(realRoot)).toBe(1);
+    const daemonPid = readLockPid(realRoot);
+    expect(daemonPid).toBeTruthy();
+    expect(isAlive(daemonPid!)).toBe(true);
+  }, 45000);
+
+  it('daemon survives the first client dying; a second client keeps working (must-fix 2 / #277)', async () => {
+    // Idle high so the daemon doesn't reap mid-test; poll fast so proxy 1
+    // notices its dead parent quickly.
+    const env = { CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS: '30000', CODEGRAPH_PPID_POLL_MS: '200' };
+
+    const first = spawnServer(tempDir, env);
+    servers.push(first);
+    sendInitialize(first.child, `file://${tempDir}`, 1);
+    await waitFor(() => findResponse(first.stdout, 1), 10000);
+    await waitFor(() => (readLockPid(realRoot) ?? 0) > 0, 8000);
+    const daemonPid = readLockPid(realRoot)!;
+    expect(isAlive(daemonPid)).toBe(true);
+
+    const second = spawnServer(tempDir, env);
+    servers.push(second);
+    sendInitialize(second.child, `file://${tempDir}`, 1);
+    await waitFor(() => findResponse(second.stdout, 1), 10000);
+    await waitFor(() => second.stderr.some((l) => l.includes('Attached to shared daemon')), 8000);
+
+    // Kill the launcher that spawned the daemon. With the old in-process design
+    // this would take the daemon (and thus the second client) down.
+    killTree(first.child);
+
+    // The daemon is detached — it must still be alive a beat later.
+    await new Promise((r) => setTimeout(r, 1500));
+    expect(isAlive(daemonPid)).toBe(true);
+
+    // And the second client can still drive a real tool call through it.
+    sendMessage(second.child, { jsonrpc: '2.0', id: 2, method: 'tools/list' });
+    const toolsResp = await waitFor(() => findResponse(second.stdout, 2), 10000);
+    expect(Array.isArray(toolsResp.result.tools)).toBe(true);
+    expect(toolsResp.result.tools.length).toBeGreaterThan(0);
+  }, 45000);
+
+  it('CODEGRAPH_NO_DAEMON=1 keeps each process independent (no socket/pidfile)', async () => {
+    const env = { CODEGRAPH_NO_DAEMON: '1' };
+    const first = spawnServer(tempDir, env);
+    servers.push(first);
+    sendInitialize(first.child, `file://${tempDir}`, 1);
+    await waitFor(() => findResponse(first.stdout, 1), 10000);
+    // Direct mode — no daemon machinery touched.
+    expect(first.stderr.some((l) => l.includes('Attached to shared daemon'))).toBe(false);
+    expect(fs.existsSync(path.join(realRoot, '.codegraph', 'daemon.pid'))).toBe(false);
+    expect(fs.existsSync(path.join(realRoot, '.codegraph', 'daemon.log'))).toBe(false);
+  }, 20000);
+
+  it('clears a stale (dead-pid) lockfile and a fresh daemon takes over', async () => {
+    // Plant a lockfile pointing at a definitely-dead pid + the real socket path.
+    fs.writeFileSync(
+      path.join(realRoot, '.codegraph', 'daemon.pid'),
+      JSON.stringify({
+        pid: 999_999,
+        version: '0.0.0-fake',
+        socketPath: getDaemonSocketPath(realRoot),
+        startedAt: Date.now() - 1000,
+      }),
+    );
+
+    const env = { CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS: '15000' };
+    const server = spawnServer(tempDir, env);
+    servers.push(server);
+    sendInitialize(server.child, `file://${tempDir}`, 1);
+    const resp = await waitFor(() => findResponse(server.stdout, 1), 10000).catch((e) => {
+      throw new Error(`${(e as Error).message}\nstderr:\n${server.stderr.join('\n')}\ndaemon.log:\n${readDaemonLog(realRoot)}`);
+    });
+    expect(resp.result.serverInfo.name).toBe('codegraph');
+    await waitFor(() => countListeningLines(realRoot) >= 1, 10000);
+    // The pidfile now names a live daemon, not the planted-dead 999999.
+    const livePid = readLockPid(realRoot);
+    expect(livePid).not.toBe(999_999);
+    expect(isAlive(livePid!)).toBe(true);
+  }, 40000);
+
+  it('proxy falls back to direct mode on a daemon version mismatch', async () => {
+    const net = await import('net');
+    const sockPath = getDaemonSocketPath(realRoot);
+    // Plant a live-pid lockfile so the launcher treats the lock as held, and a
+    // mini-server that answers with a mismatched-version hello.
+    fs.writeFileSync(
+      path.join(realRoot, '.codegraph', 'daemon.pid'),
+      JSON.stringify({ pid: process.pid, version: '0.0.0-mismatch', socketPath: sockPath, startedAt: Date.now() }),
+    );
+    const miniServer = net.createServer((sock) => {
+      sock.write(JSON.stringify({ codegraph: '0.0.0-mismatch', pid: 1, socketPath: sockPath, protocol: 1 }) + '\n');
+    });
+    await new Promise<void>((resolve) => miniServer.listen(sockPath, () => resolve()));
+
+    try {
+      const server = spawnServer(tempDir);
+      servers.push(server);
+      sendInitialize(server.child, `file://${tempDir}`, 1);
+      // Despite the mismatched daemon, the client still gets an initialize
+      // response — the proxy answers the handshake locally and, refusing to
+      // attach across the version mismatch, serves the session in-process.
+      const resp = await waitFor(() => findResponse(server.stdout, 1), 10000);
+      expect(resp.result.serverInfo.name).toBe('codegraph');
+      await waitFor(
+        () => server.stderr.some((l) => l.includes('serving this session in-process')),
+        6000,
+      );
+    } finally {
+      await new Promise<void>((resolve) => miniServer.close(() => resolve()));
+    }
+  }, 30000);
+
+  // The over-the-wire client-hello → record → sweep path is covered by the
+  // deterministic `Daemon.reapDeadClients` unit test in daemon-client-liveness
+  // (a raw-socket variant here was flaky under heavy parallel load), plus the
+  // client-hello round-trip exercised by every test above (the real proxy now
+  // sends it). What stays here is the lifecycle behavior that needs real procs.
+  it('exits on the inactivity backstop even while a client stays connected (#692)', async () => {
+    // Backstop short, idle timeout long: with a client connected the idle timer
+    // never arms, so only the inactivity backstop can take the daemon down.
+    const env = { CODEGRAPH_DAEMON_MAX_IDLE_MS: '1500', CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS: '60000' };
+    const server = spawnServer(tempDir, env);
+    servers.push(server);
+    sendInitialize(server.child, `file://${tempDir}`, 1);
+    await waitFor(() => findResponse(server.stdout, 1), 10000);
+    await waitFor(() => (readLockPid(realRoot) ?? 0) > 0, 8000);
+    const daemonPid = readLockPid(realRoot)!;
+    expect(isAlive(daemonPid)).toBe(true);
+
+    // Send nothing further — the client stays connected but idle. The backstop
+    // should fire and the daemon should exit and clean up its lockfile.
+    expect(await waitProcessExit(daemonPid, 12000)).toBe(true);
+    expect(readDaemonLog(realRoot)).toContain('inactivity backstop');
+    expect(fs.existsSync(path.join(realRoot, '.codegraph', 'daemon.pid'))).toBe(false);
+  }, 30000);
+
+  it('daemon idle-times-out after the last client disconnects', async () => {
+    const env = { CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS: '800', CODEGRAPH_PPID_POLL_MS: '200' };
+    const server = spawnServer(tempDir, env);
+    servers.push(server);
+    sendInitialize(server.child, `file://${tempDir}`, 1);
+    await waitFor(() => findResponse(server.stdout, 1), 10000);
+    await waitFor(() => (readLockPid(realRoot) ?? 0) > 0, 8000);
+    const daemonPid = readLockPid(realRoot)!;
+
+    // Close the only client's stdin → proxy exits → daemon refcount hits 0 →
+    // idle timer fires → daemon exits and cleans up its lockfile.
+    server.child.stdin.end();
+
+    expect(await waitProcessExit(daemonPid, 10000)).toBe(true);
+    expect(fs.existsSync(path.join(realRoot, '.codegraph', 'daemon.pid'))).toBe(false);
+  }, 30000);
+
+  it('proxy survives the daemon dying mid-session and keeps serving (#662)', async () => {
+    // The #662 scenario: an MCP host SIGTERM's the shared daemon while a session
+    // is live. The proxy must NOT exit (losing CodeGraph for that session) — it
+    // falls back to an in-process engine and keeps answering.
+    const env = { CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS: '30000', CODEGRAPH_PPID_POLL_MS: '5000' };
+    const server = spawnServer(tempDir, env);
+    servers.push(server);
+    sendInitialize(server.child, `file://${tempDir}`, 1);
+    await waitFor(() => findResponse(server.stdout, 1), 10000);
+    await waitFor(() => server.stderr.some((l) => l.includes('Attached to shared daemon')), 8000);
+    await waitFor(() => (readLockPid(realRoot) ?? 0) > 0, 8000);
+    const daemonPid = readLockPid(realRoot)!;
+
+    // A warm call goes through the daemon.
+    sendMessage(server.child, { jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'codegraph_status', arguments: {} } });
+    await waitFor(() => findResponse(server.stdout, 2), 10000);
+
+    // Kill the daemon out from under the live proxy.
+    process.kill(daemonPid, 'SIGTERM');
+    expect(await waitProcessExit(daemonPid, 8000)).toBe(true);
+
+    // The proxy must still be alive and still answer — served in-process now.
+    expect(isAlive(server.child.pid!)).toBe(true);
+    await waitFor(() => server.stderr.some((l) => l.includes('serving this session in-process')), 8000);
+    sendMessage(server.child, { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'codegraph_status', arguments: {} } });
+    const resp = await waitFor(() => findResponse(server.stdout, 3), 15000);
+    expect(resp.result !== undefined || resp.error !== undefined).toBe(true);
+    expect(isAlive(server.child.pid!)).toBe(true);
+  }, 45000);
+});
diff --git a/__tests__/mcp-debounce-env.test.ts b/__tests__/mcp-debounce-env.test.ts
new file mode 100644
index 000000000..82619973b
--- /dev/null
+++ b/__tests__/mcp-debounce-env.test.ts
@@ -0,0 +1,47 @@
+/**
+ * CODEGRAPH_WATCH_DEBOUNCE_MS env override (issue #403).
+ *
+ * Lets users tune the watcher quiet window from MCP-launched configs without
+ * editing the agent's command line — formatter-on-save chains and large
+ * generated outputs benefit from a longer window. Clamped to [100ms, 60s];
+ * out-of-range / non-numeric values fall back to the FileWatcher default
+ * (2000ms) rather than throwing or silently capping a likely typo.
+ */
+import { describe, it, expect } from 'vitest';
+import { parseDebounceEnv } from '../src/mcp/engine';
+
+describe('parseDebounceEnv', () => {
+  it('returns undefined for unset / empty values', () => {
+    expect(parseDebounceEnv(undefined)).toBeUndefined();
+    expect(parseDebounceEnv('')).toBeUndefined();
+    expect(parseDebounceEnv('   ')).toBeUndefined();
+  });
+
+  it('accepts integer values inside [100, 60000]', () => {
+    expect(parseDebounceEnv('100')).toBe(100);
+    expect(parseDebounceEnv('2000')).toBe(2000);
+    expect(parseDebounceEnv('5000')).toBe(5000);
+    expect(parseDebounceEnv('60000')).toBe(60000);
+  });
+
+  it('rejects out-of-range values (returns undefined, lets default win)', () => {
+    expect(parseDebounceEnv('0')).toBeUndefined();
+    expect(parseDebounceEnv('50')).toBeUndefined();   // below 100
+    expect(parseDebounceEnv('99')).toBeUndefined();
+    expect(parseDebounceEnv('60001')).toBeUndefined(); // above 60s
+    expect(parseDebounceEnv('-500')).toBeUndefined();
+  });
+
+  it('rejects non-integer / non-numeric values', () => {
+    expect(parseDebounceEnv('abc')).toBeUndefined();
+    expect(parseDebounceEnv('500.5')).toBeUndefined();
+    expect(parseDebounceEnv('NaN')).toBeUndefined();
+    expect(parseDebounceEnv('Infinity')).toBeUndefined();
+  });
+
+  it('accepts scientific notation that resolves to an in-range integer', () => {
+    // Number('1e3') === 1000, Number.isInteger(1000) === true. Power users
+    // who write debounce as 1e3 should not be surprised; the clamp still applies.
+    expect(parseDebounceEnv('1e3')).toBe(1000);
+  });
+});
diff --git a/__tests__/mcp-files-path-normalization.test.ts b/__tests__/mcp-files-path-normalization.test.ts
new file mode 100644
index 000000000..94d870172
--- /dev/null
+++ b/__tests__/mcp-files-path-normalization.test.ts
@@ -0,0 +1,113 @@
+/**
+ * codegraph_files path-filter normalization (#426)
+ *
+ * Stored file paths are project-relative POSIX (e.g. "src/foo.ts"). Some
+ * agents pass project-root variants like "/", ".", "./" or "" when they want
+ * "the whole project", and Windows-style backslashes or leading "/" / "./"
+ * prefixes when they want a subtree. The old filter used a plain
+ * `startsWith(pathFilter)`, so any of those buried the agent at "no files
+ * found" and pushed it back to Read/Glob — the exact opencode regression in
+ * #426. These tests pin every branch of the normalization.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src/index';
+import { ToolHandler } from '../src/mcp/tools';
+
+describe('codegraph_files path normalization', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+  let handler: ToolHandler;
+
+  beforeEach(async () => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-files-paths-'));
+    fs.mkdirSync(path.join(tempDir, 'src', 'components'), { recursive: true });
+    fs.mkdirSync(path.join(tempDir, 'tests'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'src', 'index.ts'), `export const x = 1;\n`);
+    fs.writeFileSync(
+      path.join(tempDir, 'src', 'components', 'Button.ts'),
+      `export const Button = () => 1;\n`
+    );
+    fs.writeFileSync(path.join(tempDir, 'tests', 'a.test.ts'), `export const t = 1;\n`);
+    cg = await CodeGraph.init(tempDir, {
+      config: { include: ['**/*.ts'], exclude: [] },
+    });
+    await cg.indexAll();
+    handler = new ToolHandler(cg);
+  });
+
+  afterEach(() => {
+    if (cg) cg.destroy();
+    if (fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  async function listed(pathFilter: string | undefined): Promise<string> {
+    const result = await handler.execute('codegraph_files', {
+      ...(pathFilter !== undefined ? { path: pathFilter } : {}),
+      format: 'flat',
+      includeMetadata: false,
+    });
+    expect(result.isError).toBeFalsy();
+    return result.content[0]!.text as string;
+  }
+
+  // Root-ish filters: every shape an agent might guess for "whole project"
+  // must list the same files as no filter at all.
+  for (const rootish of ['/', '.', './', '', '\\', '//', './/']) {
+    it(`treats path=${JSON.stringify(rootish)} as project root`, async () => {
+      const output = await listed(rootish);
+      expect(output).toContain('src/index.ts');
+      expect(output).toContain('src/components/Button.ts');
+      expect(output).toContain('tests/a.test.ts');
+    });
+  }
+
+  it('matches a real subdirectory prefix', async () => {
+    const output = await listed('src');
+    expect(output).toContain('src/index.ts');
+    expect(output).toContain('src/components/Button.ts');
+    expect(output).not.toContain('tests/a.test.ts');
+  });
+
+  it('tolerates a leading slash on a real subdirectory', async () => {
+    const output = await listed('/src');
+    expect(output).toContain('src/index.ts');
+    expect(output).not.toContain('tests/a.test.ts');
+  });
+
+  it('tolerates a leading "./" on a real subdirectory', async () => {
+    const output = await listed('./src');
+    expect(output).toContain('src/index.ts');
+    expect(output).not.toContain('tests/a.test.ts');
+  });
+
+  it('tolerates a trailing slash on a real subdirectory', async () => {
+    const output = await listed('src/');
+    expect(output).toContain('src/index.ts');
+    expect(output).not.toContain('tests/a.test.ts');
+  });
+
+  it('normalizes Windows backslashes', async () => {
+    const output = await listed('src\\components');
+    expect(output).toContain('src/components/Button.ts');
+    expect(output).not.toContain('src/index.ts');
+  });
+
+  // Old code matched on raw `startsWith`, so a filter "src" would also
+  // return a sibling like "src-utils/...". The new code requires either an
+  // exact match or a "<filter>/" boundary, so prefixes don't bleed.
+  it('does not match sibling directories that share a prefix', async () => {
+    fs.mkdirSync(path.join(tempDir, 'src-utils'), { recursive: true });
+    fs.writeFileSync(path.join(tempDir, 'src-utils', 'helper.ts'), `export const h = 1;\n`);
+    await cg.indexAll();
+
+    const output = await listed('src');
+    expect(output).toContain('src/index.ts');
+    expect(output).not.toContain('src-utils/helper.ts');
+  });
+});
diff --git a/__tests__/mcp-initialize.test.ts b/__tests__/mcp-initialize.test.ts
index 4a57ebae0..0a320773d 100644
--- a/__tests__/mcp-initialize.test.ts
+++ b/__tests__/mcp-initialize.test.ts
@@ -23,6 +23,14 @@ function spawnServer(cwd: string): ChildProcessWithoutNullStreams {
   return spawn(process.execPath, [BIN, 'serve', '--mcp'], {
     cwd,
     stdio: ['pipe', 'pipe', 'pipe'],
+    // Pin to direct (in-process) mode. #172 is a contract about the in-process
+    // server's init ordering — the "File watcher active" log this test observes
+    // is emitted in-process. In daemon mode the watcher runs in the detached
+    // daemon (logging to .codegraph/daemon.log, not the child's stderr); the
+    // same response-before-init guarantee lives in the shared session code and
+    // is covered by mcp-daemon.test.ts. Direct mode also avoids leaking a
+    // detached daemon from this suite.
+    env: { ...process.env, CODEGRAPH_NO_DAEMON: '1' },
   }) as ChildProcessWithoutNullStreams;
 }
 
@@ -146,4 +154,30 @@ describe('MCP initialize handshake (issue #172)', () => {
     expect(json.id).toBe(0);
     expect(json.result.serverInfo.name).toBe('codegraph');
   }, 20000);
+
+  it('answers resources/list and prompts/list with empty lists, not -32601 (issue #621)', async () => {
+    child = spawnServer(tempDir);
+    const events = tagStreams(child);
+    sendInitialize(child, tempDir);
+    await waitFor(events, (e) => e.stream === 'stdout', 5000); // initialize reply
+
+    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'resources/list', params: {} }) + '\n');
+    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'prompts/list', params: {} }) + '\n');
+
+    const replyFor = async (id: number) => {
+      const ev = await waitFor(events, (e) => {
+        if (e.stream !== 'stdout') return false;
+        try { return JSON.parse(e.text).id === id; } catch { return false; }
+      }, 5000);
+      return JSON.parse(ev.text);
+    };
+
+    const resources = await replyFor(1);
+    expect(resources.error).toBeUndefined();
+    expect(resources.result.resources).toEqual([]);
+
+    const prompts = await replyFor(2);
+    expect(prompts.error).toBeUndefined();
+    expect(prompts.result.prompts).toEqual([]);
+  }, 15000);
 });
diff --git a/__tests__/mcp-ppid-watchdog.test.ts b/__tests__/mcp-ppid-watchdog.test.ts
new file mode 100644
index 000000000..781e0be70
--- /dev/null
+++ b/__tests__/mcp-ppid-watchdog.test.ts
@@ -0,0 +1,173 @@
+/**
+ * PPID watchdog regression test (#277).
+ *
+ * On Linux, when an MCP host (Claude Code, opencode, …) is SIGKILL'd by the
+ * OOM killer / a force-quit / a container teardown, the kernel does NOT
+ * propagate the death to its `codegraph serve --mcp` child. The child gets
+ * reparented to init/systemd, its stdin stays half-open in some
+ * configurations, and the existing `stdin.on('end' | 'close')` handlers
+ * never fire — the server lingers indefinitely, holding inotify watches,
+ * file descriptors, and the SQLite WAL.
+ *
+ * `src/mcp/index.ts` polls `process.ppid` and shuts down the moment it
+ * diverges from the value observed at startup. This test stands up a
+ * four-tier process tree (vitest → wrapper → {stdin-holder, codegraph}) and
+ * SIGKILL's the wrapper. The stdin-holder is a long-lived sibling whose
+ * `stdout` pipe is dup'd into codegraph's `stdin`. After the wrapper dies
+ * the pipe stays open (stdin-holder still owns the write-end), so the
+ * existing stdin close handlers do **not** fire — the only thing that can
+ * terminate codegraph then is the PPID watchdog.
+ *
+ * Windows is excluded — `process.kill(pid, 'SIGKILL')` does not actually
+ * deliver SIGKILL there, and the per-OS reparenting semantics the watchdog
+ * relies on are POSIX-specific.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import { spawn, ChildProcessWithoutNullStreams } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const BIN = path.resolve(__dirname, '../dist/bin/codegraph.js');
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function waitForExit(pid: number, timeoutMs: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const start = Date.now();
+    const tick = () => {
+      if (!isAlive(pid)) return resolve(true);
+      if (Date.now() - start > timeoutMs) return resolve(false);
+      setTimeout(tick, 100);
+    };
+    tick();
+  });
+}
+
+describe.skipIf(process.platform === 'win32')('MCP PPID watchdog (#277)', () => {
+  let wrapper: ChildProcessWithoutNullStreams | null = null;
+  let childPid: number | null = null;
+  let stdinHolderPid: number | null = null;
+
+  afterEach(() => {
+    if (wrapper && !wrapper.killed) {
+      try { wrapper.kill('SIGKILL'); } catch { /* already gone */ }
+    }
+    // Belt and suspenders — don't leak processes if an assertion failed.
+    for (const pid of [childPid, stdinHolderPid]) {
+      if (pid !== null && isAlive(pid)) {
+        try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ }
+      }
+    }
+    wrapper = null;
+    childPid = null;
+    stdinHolderPid = null;
+  });
+
+  it("shuts down when its parent is SIGKILL'd and stdin stays open", async () => {
+    // The wrapper:
+    //   1. Spawns a "stdin-holder" — a tiny long-lived node process whose
+    //      `stdout` pipe is dup'd into codegraph's `stdin`. As long as the
+    //      stdin-holder is alive (it is — it's an orphan after the wrapper
+    //      dies), codegraph's stdin never sees EOF.
+    //   2. Spawns codegraph with that pipe as fd 0 and its stderr redirected
+    //      to a tmp file that survives the wrapper, then reports both PIDs.
+    //   3. Idles until SIGKILL'd from the test.
+    //
+    // CODEGRAPH_PPID_POLL_MS=200 keeps the watchdog responsive in test; the
+    // production default is 5000ms.
+    const stderrLog = path.join(
+      fs.mkdtempSync(path.join(os.tmpdir(), 'cg-ppid-watchdog-')),
+      'codegraph.stderr.log',
+    );
+    // The wrapper waits 800ms before reporting the PIDs so the codegraph
+    // child has time to finish its async start() (dynamic import + transport
+    // setup + watchdog registration). Otherwise the test races: it
+    // SIGKILL's the wrapper before the watchdog interval is installed, and
+    // nothing terminates codegraph.
+    const wrapperSrc = `
+      const { spawn } = require('child_process');
+      const fs = require('fs');
+      const stderrFd = fs.openSync(${JSON.stringify(stderrLog)}, 'a');
+      const stdinHolder = spawn(process.execPath, ['-e', 'setInterval(() => {}, 60000)'], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        detached: true,
+      });
+      stdinHolder.unref();
+      const child = spawn(process.execPath, [${JSON.stringify(BIN)}, 'serve', '--mcp'], {
+        stdio: [stdinHolder.stdout, 'ignore', stderrFd],
+        // Pin to direct (in-process) mode: this test targets the in-process
+        // server's PPID watchdog (#277). The detached-daemon/proxy watchdog is
+        // covered separately in mcp-daemon.test.ts ("daemon survives the first
+        // client dying"). Without this the spawned process becomes a proxy and
+        // also spawns a detached daemon that would outlive the test.
+        env: { ...process.env, CODEGRAPH_PPID_POLL_MS: '200', CODEGRAPH_NO_DAEMON: '1' },
+        detached: true,
+      });
+      child.unref();
+      setTimeout(() => {
+        process.stdout.write(JSON.stringify({ pid: child.pid, stdinHolderPid: stdinHolder.pid }) + '\\n');
+      }, 800);
+      setInterval(() => {}, 60000);
+    `;
+    wrapper = spawn(process.execPath, ['-e', wrapperSrc], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }) as ChildProcessWithoutNullStreams;
+
+    const pids = await new Promise<{ pid: number; stdinHolderPid: number }>((resolve, reject) => {
+      let buf = '';
+      const timer = setTimeout(
+        () => reject(new Error('wrapper did not report PIDs in time')),
+        10000,
+      );
+      wrapper!.stdout.on('data', (chunk: Buffer) => {
+        buf += chunk.toString('utf8');
+        const m = buf.match(/\{"pid":(\d+),"stdinHolderPid":(\d+)\}/);
+        if (m) {
+          clearTimeout(timer);
+          resolve({ pid: parseInt(m[1], 10), stdinHolderPid: parseInt(m[2], 10) });
+        }
+      });
+      wrapper!.on('exit', () => {
+        clearTimeout(timer);
+        reject(new Error('wrapper exited before reporting PIDs'));
+      });
+    });
+    childPid = pids.pid;
+    stdinHolderPid = pids.stdinHolderPid;
+
+    expect(isAlive(childPid)).toBe(true);
+    expect(isAlive(stdinHolderPid)).toBe(true);
+
+    // SIGKILL the wrapper — no cleanup runs, just like a real OOM kill.
+    // codegraph and the stdin-holder both get reparented to init/systemd.
+    // Crucially, the pipe between them stays open, so codegraph's stdin
+    // doesn't close: only the watchdog can take it down.
+    wrapper.kill('SIGKILL');
+
+    // Watchdog runs every 200ms in this test → 5s gives ~25 polls of headroom.
+    const exited = await waitForExit(childPid, 5000);
+    const stderrContent = fs.existsSync(stderrLog) ? fs.readFileSync(stderrLog, 'utf-8') : '<no stderr captured>';
+    expect(
+      exited,
+      `codegraph child (pid=${childPid}) did not exit within 5s after wrapper was SIGKILL'd.\nstderr:\n${stderrContent}`,
+    ).toBe(true);
+    // The watchdog announces itself before tearing down — assert that the
+    // shutdown came from the parent-death path, not from any other signal.
+    expect(stderrContent).toMatch(/Parent process exited.*shutting down/);
+
+    // The stdin-holder is now an orphan — kill it explicitly so it doesn't
+    // outlive the test. It's still tracked in `stdinHolderPid` for the
+    // afterEach safety net, but we tidy up proactively here too.
+    if (isAlive(stdinHolderPid)) {
+      try { process.kill(stdinHolderPid, 'SIGKILL'); } catch { /* race */ }
+    }
+  }, 20000);
+});
diff --git a/__tests__/mcp-staleness-banner.test.ts b/__tests__/mcp-staleness-banner.test.ts
new file mode 100644
index 000000000..5ea5a0103
--- /dev/null
+++ b/__tests__/mcp-staleness-banner.test.ts
@@ -0,0 +1,173 @@
+/**
+ * Per-file staleness banner on MCP tool responses (issue #403).
+ *
+ * The watcher tracks every file event since the last successful sync; the
+ * tool dispatcher intersects "files referenced in this response" with that
+ * pending set and prepends a banner ("⚠️ Some files referenced below were
+ * edited since the last index sync…") plus an optional footer ("(Note: N
+ * file(s) elsewhere in this project are pending index sync…)").
+ *
+ * No auto-flush, no static wait — the response is instant and the agent
+ * decides whether to Read the specific stale file. These tests exercise
+ * the full real path: real CodeGraph index + real ToolHandler.execute().
+ *
+ * **Event delivery uses a synthetic seam** (`__emitWatchEventForTests`): the
+ * real native fs.watch (FSEvents/inotify) delivery is non-deterministic under
+ * parallel vitest execution and produced a consistent ~30% failure rate on
+ * these tests when run inside the full suite. The seam drives the watcher's
+ * pending-set pipeline directly so the tests synthesize file events
+ * deterministically. The watcher's actual debounce timer (real setTimeout) is
+ * left untouched.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src/index';
+import { ToolHandler } from '../src/mcp/tools';
+import { __emitWatchEventForTests } from '../src/sync/watcher';
+
+function waitFor(condition: () => boolean, timeoutMs = 2000, intervalMs = 25): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const start = Date.now();
+    const tick = () => {
+      if (condition()) return resolve();
+      if (Date.now() - start > timeoutMs) return reject(new Error('waitFor timed out'));
+      setTimeout(tick, intervalMs);
+    };
+    tick();
+  });
+}
+
+describe('MCP staleness banner', () => {
+  let testDir: string;
+  let cg: CodeGraph;
+  let handler: ToolHandler;
+
+  beforeEach(async () => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-stale-banner-'));
+    fs.mkdirSync(path.join(testDir, 'src'));
+    // Three isolated files with no cross-references — keeps each test's
+    // "which path does the response mention?" assertion unambiguous. If the
+    // files shared imports/calls, codegraph_search responses would surface
+    // multiple file paths and the banner-vs-footer split would be racy.
+    fs.writeFileSync(
+      path.join(testDir, 'src', 'alpha-only.ts'),
+      'export function alphaOnly() { return 1; }\n',
+    );
+    fs.writeFileSync(
+      path.join(testDir, 'src', 'bravo-only.ts'),
+      'export function bravoOnly() { return 2; }\n',
+    );
+    fs.writeFileSync(
+      path.join(testDir, 'src', 'charlie-only.ts'),
+      'export function charlieOnly() { return 3; }\n',
+    );
+
+    cg = CodeGraph.initSync(testDir, { config: { include: ['**/*.ts'], exclude: [] } });
+    await cg.indexAll();
+    handler = new ToolHandler(cg);
+  });
+
+  afterEach(() => {
+    try { cg.unwatch(); } catch { /* ignore */ }
+    try { cg.close(); } catch { /* ignore */ }
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('prepends a stale banner when the response references a pending file', async () => {
+    // Long debounce so the edit lingers in pendingFiles while we query.
+    cg.watch({ debounceMs: 4000, inertForTests: true });
+    await cg.waitUntilWatcherReady();
+
+    // Real disk write so a later sync (if it fires) sees the new content,
+    // plus a synthesized chokidar event so the watcher's pendingFiles set
+    // updates immediately without waiting on OS-level event delivery.
+    fs.writeFileSync(
+      path.join(testDir, 'src', 'alpha-only.ts'),
+      'export function alphaOnly() { return 99; }\n',
+    );
+    __emitWatchEventForTests(testDir, 'src/alpha-only.ts');
+
+    // With mocked chokidar this is synchronous — keep the wait just to
+    // exercise the realistic shape (the watcher's `chokidarReady` gate
+    // and the small window before the pending-file Map is populated).
+    await waitFor(() => cg.getPendingFiles().some((p) => p.path === 'src/alpha-only.ts'));
+
+    const res = await handler.execute('codegraph_search', { query: 'alphaOnly' });
+    expect(res.isError).toBeFalsy();
+    const text = res.content[0].text;
+
+    // Banner shape: warning glyph + filename + actionable instruction.
+    expect(text.startsWith('⚠️')).toBe(true);
+    expect(text).toContain('src/alpha-only.ts');
+    expect(text).toMatch(/edited \d+ms ago/);
+    expect(text).toMatch(/Read them directly/);
+    // The actual result must still follow the banner.
+    expect(text).toMatch(/alphaOnly/);
+  });
+
+  it('uses the footer (not the banner) when pending files are not referenced', async () => {
+    cg.watch({ debounceMs: 4000, inertForTests: true });
+    await cg.waitUntilWatcherReady();
+
+    // Edit bravo-only.ts but search for the alphaOnly symbol, whose hit is
+    // only in alpha-only.ts. The two files share no imports/calls so the
+    // response text won't mention bravo-only.ts.
+    fs.writeFileSync(
+      path.join(testDir, 'src', 'bravo-only.ts'),
+      'export function bravoOnly() { return 22; }\n',
+    );
+    __emitWatchEventForTests(testDir, 'src/bravo-only.ts');
+    await waitFor(() => cg.getPendingFiles().some((p) => p.path === 'src/bravo-only.ts'));
+
+    const res = await handler.execute('codegraph_search', { query: 'alphaOnly' });
+    const text = res.content[0].text;
+
+    expect(text.startsWith('⚠️')).toBe(false);
+    expect(text).toMatch(/elsewhere in this project are pending index sync/);
+    expect(text).toContain('src/bravo-only.ts');
+  });
+
+  it('drops the banner once the sync completes and clears the pending entry', async () => {
+    cg.watch({ debounceMs: 200, inertForTests: true });
+    await cg.waitUntilWatcherReady();
+
+    fs.writeFileSync(
+      path.join(testDir, 'src', 'alpha-only.ts'),
+      'export function alphaOnly() { return 7; }\n',
+    );
+    __emitWatchEventForTests(testDir, 'src/alpha-only.ts');
+    // Wait through debounce (200ms) + sync; pendingFiles drains back to empty.
+    await waitFor(() => cg.getPendingFiles().length === 0, 3000);
+
+    const res = await handler.execute('codegraph_search', { query: 'alphaOnly' });
+    const text = res.content[0].text;
+    expect(text.startsWith('⚠️')).toBe(false);
+    expect(text).not.toMatch(/elsewhere in this project are pending index sync/);
+  });
+
+  it('lists pending files under "Pending sync" in codegraph_status', async () => {
+    cg.watch({ debounceMs: 4000, inertForTests: true });
+    await cg.waitUntilWatcherReady();
+
+    fs.writeFileSync(
+      path.join(testDir, 'src', 'charlie-only.ts'),
+      'export function charlieOnly() { return 33; }\n',
+    );
+    __emitWatchEventForTests(testDir, 'src/charlie-only.ts');
+    await waitFor(() => cg.getPendingFiles().some((p) => p.path === 'src/charlie-only.ts'));
+
+    const res = await handler.execute('codegraph_status', {});
+    const text = res.content[0].text;
+    expect(text).toContain('### Pending sync:');
+    expect(text).toContain('src/charlie-only.ts');
+    // Status embeds the info first-class, so the auto-banner is suppressed.
+    expect(text.startsWith('⚠️')).toBe(false);
+  });
+
+  it('returns zero pending files when no watcher is active', () => {
+    expect(cg.getPendingFiles()).toEqual([]);
+  });
+});
diff --git a/__tests__/mcp-tool-allowlist.test.ts b/__tests__/mcp-tool-allowlist.test.ts
new file mode 100644
index 000000000..08067c918
--- /dev/null
+++ b/__tests__/mcp-tool-allowlist.test.ts
@@ -0,0 +1,69 @@
+/**
+ * CODEGRAPH_MCP_TOOLS allowlist — lets an operator (or an A/B harness) trim the
+ * exposed MCP tool surface without touching the client config. Inert when unset.
+ * Filtering happens in ListTools (getTools) and is enforced again on execute().
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import { ToolHandler } from '../src/mcp/tools';
+
+const ENV = 'CODEGRAPH_MCP_TOOLS';
+
+describe('CODEGRAPH_MCP_TOOLS allowlist', () => {
+  const original = process.env[ENV];
+  afterEach(() => {
+    if (original === undefined) delete process.env[ENV];
+    else process.env[ENV] = original;
+  });
+
+  const listed = () => new ToolHandler(null).getTools().map(t => t.name).sort();
+
+  it('exposes the default 4-tool surface when unset', () => {
+    delete process.env[ENV];
+    // The default set (see DEFAULT_MCP_TOOLS): explore + node are the
+    // validated workhorses, search the cheap lookup, callers the one
+    // irreplaceable enumerator. callees/impact/files/status stay defined
+    // and executable but unlisted — impact appeared in ZERO recorded runs.
+    expect(listed()).toEqual([
+      'codegraph_callers',
+      'codegraph_explore',
+      'codegraph_node',
+      'codegraph_search',
+    ]);
+  });
+
+  it('re-enables an unlisted tool via the allowlist (impact)', () => {
+    process.env[ENV] = 'explore,impact';
+    expect(listed()).toEqual(['codegraph_explore', 'codegraph_impact']);
+  });
+
+  it('filters ListTools to the allowlisted short names', () => {
+    process.env[ENV] = 'explore,search,node';
+    expect(listed()).toEqual(['codegraph_explore', 'codegraph_node', 'codegraph_search']);
+  });
+
+  it('accepts fully-qualified codegraph_ names and ignores whitespace', () => {
+    process.env[ENV] = ' codegraph_explore , search ';
+    expect(listed()).toEqual(['codegraph_explore', 'codegraph_search']);
+  });
+
+  it('treats an empty/whitespace value as unset (default surface)', () => {
+    process.env[ENV] = '   ';
+    expect(listed()).toHaveLength(4);
+    expect(listed()).toContain('codegraph_explore');
+  });
+
+  it('rejects a disabled tool on execute (defense in depth)', async () => {
+    process.env[ENV] = 'node';
+    const res = await new ToolHandler(null).execute('codegraph_explore', {});
+    expect(res.isError).toBe(true);
+    expect(res.content[0].text).toMatch(/disabled via CODEGRAPH_MCP_TOOLS/);
+  });
+
+  it('lets an allowlisted tool past the guard', async () => {
+    process.env[ENV] = 'search';
+    // No CodeGraph attached, so it fails *after* the allowlist guard — the
+    // "disabled" message must NOT appear, proving the guard passed it through.
+    const res = await new ToolHandler(null).execute('codegraph_search', { query: 'x' });
+    expect(res.content[0].text).not.toMatch(/disabled via CODEGRAPH_MCP_TOOLS/);
+  });
+});
diff --git a/__tests__/mcp-unindexed.test.ts b/__tests__/mcp-unindexed.test.ts
new file mode 100644
index 000000000..2b0019d6d
--- /dev/null
+++ b/__tests__/mcp-unindexed.test.ts
@@ -0,0 +1,225 @@
+/**
+ * Unindexed-workspace session policy tests.
+ *
+ * An MCP session attached to a workspace with no .codegraph/ must go quiet
+ * rather than fail loudly: `initialize` returns the short "inactive"
+ * instructions variant (not the full playbook), `tools/list` returns an
+ * EMPTY list, and a tool call that still arrives (cross-project
+ * `projectPath`, or a host that skips tools/list) answers with a
+ * SUCCESS-shaped guidance message — never `isError: true`. One or two early
+ * isError responses teach an agent to abandon codegraph for the whole
+ * session; that observed failure mode is what this suite guards.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { spawn, ChildProcessWithoutNullStreams } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { CodeGraph } from '../src';
+import { ToolHandler } from '../src/mcp/tools';
+
+const BIN = path.resolve(__dirname, '../dist/bin/codegraph.js');
+
+function spawnServer(cwd: string): ChildProcessWithoutNullStreams {
+  return spawn(process.execPath, [BIN, 'serve', '--mcp'], {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    // Direct (in-process) mode — the unindexed path never has a daemon
+    // anyway (the daemon socket lives in .codegraph/), and this keeps the
+    // suite from leaking a detached daemon in the indexed test.
+    // CODEGRAPH_WASM_RELAUNCHED skips the --liftoff-only re-exec: without
+    // it the server runs as a GRANDCHILD that survives child.kill() on
+    // Windows and holds the temp cwd/SQLite handles, failing teardown with
+    // EPERM no matter how long rmSync retries (the class documented for
+    // the mcp-initialize/mcp-roots suites).
+    env: { ...process.env, CODEGRAPH_NO_DAEMON: '1', CODEGRAPH_WASM_RELAUNCHED: '1' },
+  }) as ChildProcessWithoutNullStreams;
+}
+
+/** Send a JSON-RPC request and resolve with the response matching its id. */
+function request(
+  child: ChildProcessWithoutNullStreams,
+  msg: { id: number; method: string; params?: unknown },
+  timeoutMs = 15000
+): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    let buf = '';
+    const timer = setTimeout(() => {
+      child.stdout.off('data', onData);
+      reject(new Error(`timeout waiting for response id=${msg.id}`));
+    }, timeoutMs);
+    const onData = (chunk: Buffer) => {
+      buf += chunk.toString();
+      let idx: number;
+      while ((idx = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, idx).trim();
+        buf = buf.slice(idx + 1);
+        if (!line) continue;
+        try {
+          const parsed = JSON.parse(line) as Record<string, unknown>;
+          if (parsed.id === msg.id) {
+            clearTimeout(timer);
+            child.stdout.off('data', onData);
+            resolve(parsed);
+            return;
+          }
+        } catch {
+          // non-JSON noise on stdout — ignore
+        }
+      }
+    };
+    child.stdout.on('data', onData);
+    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', ...msg }) + '\n');
+  });
+}
+
+function initializeParams(projectPath: string) {
+  return {
+    protocolVersion: '2025-11-25',
+    capabilities: {},
+    clientInfo: { name: 'test', version: '0.0.0' },
+    rootUri: `file://${projectPath}`,
+  };
+}
+
+describe('Unindexed-workspace session policy', () => {
+  let tempDir: string;
+  let child: ChildProcessWithoutNullStreams | null = null;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-unindexed-'));
+  });
+
+  afterEach(async () => {
+    if (child) {
+      // Wait for the child to actually exit before removing its cwd — on
+      // Windows a just-killed process briefly holds the directory/SQLite
+      // handles, and an immediate rmSync fails the teardown with EPERM
+      // (the documented file-locking class that fails the sibling
+      // mcp-initialize/mcp-roots suites). kill + await exit + retried
+      // removal keeps this suite green on Windows.
+      const exited = new Promise<void>((resolve) => child!.once('exit', () => resolve()));
+      child.kill('SIGKILL');
+      await Promise.race([exited, new Promise((r) => setTimeout(r, 3000))]);
+      child = null;
+    }
+    fs.rmSync(tempDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
+  });
+
+  it('initialize returns the short "inactive" instructions, not the playbook', async () => {
+    fs.writeFileSync(path.join(tempDir, 'index.ts'), 'export const x = 1;\n');
+    child = spawnServer(tempDir);
+
+    const res = await request(child, { id: 0, method: 'initialize', params: initializeParams(tempDir) });
+    const instructions = (res.result as { instructions: string }).instructions;
+
+    expect(instructions).toMatch(/inactive/i);
+    expect(instructions).toMatch(/codegraph init/);
+    // The full playbook must NOT be sent into a session where every call fails
+    expect(instructions).not.toMatch(/Tool selection by intent/);
+    expect(instructions).not.toMatch(/codegraph_explore/);
+  });
+
+  it('tools/list returns an EMPTY list when the workspace has no index', async () => {
+    child = spawnServer(tempDir);
+    await request(child, { id: 0, method: 'initialize', params: initializeParams(tempDir) });
+
+    const res = await request(child, { id: 1, method: 'tools/list' });
+    expect((res.result as { tools: unknown[] }).tools).toEqual([]);
+  });
+
+  it('an INDEXED workspace still gets the full playbook and all tools', async () => {
+    fs.writeFileSync(path.join(tempDir, 'index.ts'), 'export function hello(): string { return "hi"; }\n');
+    const cg = await CodeGraph.init(tempDir, { index: true });
+    cg.close();
+
+    child = spawnServer(tempDir);
+    const init = await request(child, { id: 0, method: 'initialize', params: initializeParams(tempDir) });
+    const instructions = (init.result as { instructions: string }).instructions;
+    expect(instructions).toMatch(/Tool selection by intent/);
+    expect(instructions).not.toMatch(/inactive/i);
+
+    const list = await request(child, { id: 1, method: 'tools/list' });
+    const tools = (list.result as { tools: Array<{ name: string }> }).tools;
+    // A 1-file project triggers the pre-existing tiny-repo tool gating (a
+    // reduced core set) — the contract under test is "indexed → tools are
+    // PRESENT", in contrast to the unindexed empty list above.
+    expect(tools.length).toBeGreaterThanOrEqual(3);
+    expect(tools.map((t) => t.name)).toContain('codegraph_explore');
+  });
+});
+
+describe('No-error policy on expected conditions', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-noerror-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('cross-project query to an unindexed path is SUCCESS-shaped guidance, not isError', async () => {
+    const res = await new ToolHandler(null).execute('codegraph_search', {
+      query: 'anything',
+      projectPath: tempDir,
+    });
+
+    expect(res.isError).toBeUndefined();
+    expect(res.content[0]!.text).toMatch(/isn't indexed/);
+    expect(res.content[0]!.text).toMatch(/codegraph init/);
+    expect(res.content[0]!.text).toMatch(/built-in tools/);
+  });
+
+  it('no-default-project (working-directory detection miss) is SUCCESS-shaped guidance', async () => {
+    const res = await new ToolHandler(null).execute('codegraph_search', { query: 'anything' });
+
+    expect(res.isError).toBeUndefined();
+    expect(res.content[0]!.text).toMatch(/No CodeGraph project is loaded/);
+    expect(res.content[0]!.text).toMatch(/projectPath/);
+  });
+
+  it.runIf(process.platform !== 'win32')(
+    'sensitive-path refusal stays a hard error (no retry encouragement)',
+    async () => {
+      const res = await new ToolHandler(null).execute('codegraph_search', {
+        query: 'anything',
+        projectPath: '/etc',
+      });
+
+      expect(res.isError).toBe(true);
+      expect(res.content[0]!.text).not.toMatch(/retry the call once/);
+    }
+  );
+});
+
+describe('search kind filter', () => {
+  let tempDir: string;
+  let cg: CodeGraph;
+
+  beforeEach(async () => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-kind-'));
+    fs.writeFileSync(
+      path.join(tempDir, 'types.ts'),
+      'export type PaymentMethod = { id: string };\nexport function pay(): void {}\n'
+    );
+    cg = await CodeGraph.init(tempDir, { index: true });
+  });
+
+  afterEach(() => {
+    cg.close();
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("kind: 'type' (the advertised enum value) finds type aliases", async () => {
+    const res = await new ToolHandler(cg).execute('codegraph_search', {
+      query: 'PaymentMethod',
+      kind: 'type',
+    });
+
+    expect(res.isError).toBeUndefined();
+    expect(res.content[0]!.text).toMatch(/PaymentMethod/);
+    expect(res.content[0]!.text).not.toMatch(/No results found/);
+  });
+});
diff --git a/__tests__/node-file-view.test.ts b/__tests__/node-file-view.test.ts
new file mode 100644
index 000000000..7d2a5703c
--- /dev/null
+++ b/__tests__/node-file-view.test.ts
@@ -0,0 +1,118 @@
+/**
+ * codegraph_node FILE READ mode: a `file` with no `symbol` reads that file like
+ * the Read tool — current source with `<n>\t<line>` numbering (byte-for-byte
+ * Read's shape), narrowable with offset/limit — plus a one-line blast-radius
+ * header. `symbolsOnly` returns the structural map instead. Config/data files
+ * are summarized by key, never dumped (#383).
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src/index';
+import { ToolHandler } from '../src/mcp/tools';
+
+describe('codegraph_node file-view (Read replacement)', () => {
+  let dir: string;
+  let cg: CodeGraph;
+  let h: ToolHandler;
+
+  beforeEach(async () => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-fileview-'));
+    fs.mkdirSync(path.join(dir, 'src'));
+    fs.writeFileSync(
+      path.join(dir, 'src', 'a.ts'),
+      'export function helper(x: number) {\n  return x + 1;\n}\nexport class Widget {\n  build() { return helper(1); }\n}\n',
+    );
+    fs.writeFileSync(
+      path.join(dir, 'src', 'b.ts'),
+      "import { helper } from './a';\n\n// a comment between symbols\nconst SETTING = 7;\nexport function useHelper() { return helper(2) + SETTING; }\n",
+    );
+    // A config/data file (#383): its values may be secrets and must never be
+    // dumped verbatim by the file-view.
+    fs.writeFileSync(
+      path.join(dir, 'src', 'application.properties'),
+      'spring.datasource.password=SUPERSECRET123\nserver.port=8080\n',
+    );
+    // A large file: exceeds the file-view line budget, so it must be windowed
+    // honestly (not silently truncated).
+    fs.writeFileSync(
+      path.join(dir, 'src', 'big.ts'),
+      'export function big() {\n' +
+        Array.from({ length: 2000 }, (_, i) => `  const v${i} = ${i};`).join('\n') +
+        '\n  return 0;\n}\n',
+    );
+    cg = CodeGraph.initSync(dir, { config: { include: ['**/*.ts', '**/*.properties'], exclude: [] } });
+    await cg.indexAll();
+    h = new ToolHandler(cg);
+  });
+
+  afterEach(() => {
+    if (cg) cg.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  const text = async (args: Record<string, unknown>): Promise<string> =>
+    (await h.execute('codegraph_node', args)).content.map((c) => c.text).join('\n');
+
+  it('reads a whole file like Read by default — `<n>\\t<line>` lines (no pad), imports + gaps included', async () => {
+    const out = await text({ file: 'b.ts' }); // no includeCode needed — content is the default
+    // Byte-for-byte Read shape: line 1 is "1<TAB>import …", NOT space-padded.
+    expect(out).toMatch(/^1\timport \{ helper \} from '\.\/a';$/m);
+    expect(out).toContain('// a comment between symbols'); // inter-symbol gap (Read has it; old reconstruction dropped it)
+    expect(out).toContain('const SETTING = 7'); // top-level statement
+    expect(out).toContain('useHelper'); // the symbol body too
+    expect(out).not.toContain('```'); // Read has no code fence; neither do we
+  });
+
+  it('leads with a one-line blast-radius header (the value-add over Read)', async () => {
+    const out = await text({ file: 'a.ts' });
+    expect(out).toMatch(/used by 1 file: src\/b\.ts/); // a.ts is imported by b.ts
+    expect(out).toContain('return x + 1'); // still returns the source
+  });
+
+  it('offset/limit narrow the window exactly like Read', async () => {
+    const out = await text({ file: 'big.ts', offset: 1000, limit: 3 });
+    // Window starts at the requested line, numbered exactly: "1000<TAB>  const v998 = 998;"
+    expect(out).toMatch(/^1000\t {2}const v998 = 998;$/m);
+    expect(out).not.toMatch(/^1\t/m); // line 1 is NOT shown
+    expect(out).toMatch(/lines 1000[–-]1002 of \d+/); // honest pagination note
+  });
+
+  it('an offset past EOF is reported, not a crash', async () => {
+    const out = await text({ file: 'a.ts', offset: 9999 });
+    expect(out).toMatch(/past the end/i);
+  });
+
+  it('paginates a large file honestly by default — "lines 1–N of TOTAL", never a silent truncate', async () => {
+    const out = await text({ file: 'big.ts' });
+    expect(out).toMatch(/lines 1[–-]\d+ of \d+/); // explicit window note
+    expect(out).not.toContain('(output truncated)'); // not the generic 15k chop
+    expect(out).toMatch(/^1\texport function big/m); // the head of the window is real source
+  });
+
+  it('does NOT dump a config/data file (yaml/properties) — #383 secret safety', async () => {
+    const out = await text({ file: 'application.properties' });
+    expect(out).not.toContain('SUPERSECRET123'); // the value never reaches the agent
+    expect(out.toLowerCase()).toMatch(/config|values withheld/);
+  });
+
+  it('symbolsOnly returns the structural map, not the source', async () => {
+    const out = await text({ file: 'a.ts', symbolsOnly: true });
+    expect(out).toContain('### Symbols');
+    expect(out).toContain('helper');
+    expect(out).toContain('Widget');
+    expect(out).not.toContain('return x + 1'); // bodies are NOT included in the map
+  });
+
+  it('still works as a normal symbol lookup (no regression)', async () => {
+    const out = await text({ symbol: 'helper', includeCode: true });
+    expect(out).toContain('helper');
+    expect(out).toContain('return x + 1');
+  });
+
+  it('a miss returns a helpful message, not a crash', async () => {
+    const out = await text({ file: 'does-not-exist.ts' });
+    expect(out).toMatch(/no indexed file matches/i);
+  });
+});
diff --git a/__tests__/node-sqlite-backend.test.ts b/__tests__/node-sqlite-backend.test.ts
new file mode 100644
index 000000000..d1e630f62
--- /dev/null
+++ b/__tests__/node-sqlite-backend.test.ts
@@ -0,0 +1,71 @@
+/**
+ * node:sqlite backend (issue #238 follow-up).
+ *
+ * node:sqlite (Node's built-in real SQLite) is now the sole backend. This drives
+ * a real index + queries through it, so WAL, FTS5 search, and @named-param
+ * writes are all exercised end-to-end.
+ *
+ * Skipped on Node < 22.5 where node:sqlite doesn't exist.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src';
+
+let nodeSqliteAvailable = false;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  require('node:sqlite');
+  nodeSqliteAvailable = true;
+} catch {
+  nodeSqliteAvailable = false;
+}
+
+describe.skipIf(!nodeSqliteAvailable)('node:sqlite backend — real index + queries', () => {
+  let dir: string;
+  let cg: CodeGraph;
+
+  beforeAll(async () => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-nodesqlite-'));
+    fs.writeFileSync(path.join(dir, 'a.ts'), 'export function helper(): number { return 1; }\n');
+    fs.writeFileSync(
+      path.join(dir, 'b.ts'),
+      "import { helper } from './a';\nexport function main(): number { return helper(); }\n"
+    );
+    cg = await CodeGraph.init(dir, { index: true });
+  });
+
+  afterAll(() => {
+    cg?.close();
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('uses the node:sqlite backend', () => {
+    expect(cg.getBackend()).toBe('node-sqlite');
+  });
+
+  it('runs in WAL mode — the whole reason it beats the wasm fallback', () => {
+    expect(cg.getJournalMode()).toBe('wal');
+  });
+
+  it('indexed the project (write path: @named-param INSERTs via node:sqlite)', () => {
+    const stats = cg.getStats();
+    expect(stats.fileCount).toBe(2);
+    expect(stats.nodeCount).toBeGreaterThan(0);
+  });
+
+  it('FTS5 search returns the indexed symbol (read path)', () => {
+    const results = cg.searchNodes('helper');
+    const names = results.map(r => r.node.name);
+    expect(names).toContain('helper');
+  });
+
+  it('graph traversal resolves the cross-file caller', () => {
+    const helper = cg.searchNodes('helper').find(r => r.node.name === 'helper');
+    expect(helper).toBeTruthy();
+    const callers = cg.getCallers(helper!.node.id);
+    expect(callers.map(c => c.node.name)).toContain('main');
+  });
+});
diff --git a/__tests__/node-version-check.test.ts b/__tests__/node-version-check.test.ts
index d7b725cbb..fc455eb85 100644
--- a/__tests__/node-version-check.test.ts
+++ b/__tests__/node-version-check.test.ts
@@ -7,7 +7,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { buildNode25BlockBanner } from '../src/bin/node-version-check';
+import { buildNode25BlockBanner, buildNodeTooOldBanner, MIN_NODE_MAJOR } from '../src/bin/node-version-check';
 
 describe('buildNode25BlockBanner', () => {
   it('embeds the reported Node version in the header', () => {
@@ -41,3 +41,29 @@ describe('buildNode25BlockBanner', () => {
     );
   });
 });
+
+describe('buildNodeTooOldBanner', () => {
+  it('embeds the reported Node version in the header', () => {
+    expect(buildNodeTooOldBanner('18.20.0')).toContain(
+      'Unsupported Node.js version: 18.20.0'
+    );
+  });
+
+  it('states the supported floor matching MIN_NODE_MAJOR', () => {
+    expect(MIN_NODE_MAJOR).toBe(20);
+    expect(buildNodeTooOldBanner('18.0.0')).toContain(
+      `requires Node.js ${MIN_NODE_MAJOR} or newer`
+    );
+  });
+
+  it('points users to Node 22 LTS via nvm and Homebrew', () => {
+    const banner = buildNodeTooOldBanner('16.0.0');
+    expect(banner).toContain('Node.js 22 LTS');
+    expect(banner).toContain('nvm install 22');
+    expect(banner).toContain('brew install node@22');
+  });
+
+  it('documents the CODEGRAPH_ALLOW_UNSAFE_NODE override', () => {
+    expect(buildNodeTooOldBanner('18.0.0')).toContain('CODEGRAPH_ALLOW_UNSAFE_NODE=1');
+  });
+});
diff --git a/__tests__/npm-sdk.test.ts b/__tests__/npm-sdk.test.ts
new file mode 100644
index 000000000..c27bfc5fe
--- /dev/null
+++ b/__tests__/npm-sdk.test.ts
@@ -0,0 +1,107 @@
+/**
+ * Programmatic/embedded SDK entry (`scripts/npm-sdk.js`) tests (issue #354).
+ *
+ * The published main package is a thin shim: the CLI `bin` (npm-shim.js) execs
+ * the bundled Node, while `main` (npm-sdk.js) lets embedded consumers
+ * `require("@colbymchenry/codegraph")` on their OWN Node by re-exporting the
+ * compiled library that ships inside the per-platform optionalDependency
+ * (@colbymchenry/codegraph-<target>/lib/dist/index.js).
+ *
+ * These tests stand up a temp main-package dir with a fake platform package as a
+ * resolvable sibling, then require the SDK in a child process — so resolution,
+ * the self-heal cache fallback, and the missing-bundle error are exercised
+ * hermetically with no real bundle, network, or registry.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const SDK_SRC = path.join(__dirname, '..', 'scripts', 'npm-sdk.js');
+const target = `${process.platform}-${process.arch}`;
+const VERSION = '9.9.9-test';
+
+function mkTmp(label: string): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `cg-sdk-${label}-`));
+}
+
+// A temp node_modules with the main package (npm-sdk.js + package.json). The
+// fake platform package, when present, is written as a resolvable sibling so the
+// SDK's `require.resolve('@colbymchenry/codegraph-<target>/...')` walks to it.
+function makeConsumer(): { root: string; mainPkg: string } {
+  const root = mkTmp('consumer');
+  const mainPkg = path.join(root, 'node_modules', '@colbymchenry', 'codegraph');
+  fs.mkdirSync(mainPkg, { recursive: true });
+  fs.copyFileSync(SDK_SRC, path.join(mainPkg, 'npm-sdk.js'));
+  fs.writeFileSync(
+    path.join(mainPkg, 'package.json'),
+    JSON.stringify({ name: '@colbymchenry/codegraph', version: VERSION, main: 'npm-sdk.js' }) + '\n'
+  );
+  return { root, mainPkg };
+}
+
+// Write a fake compiled library that exports a sentinel, at the given lib/dist
+// root (used both for the platform package and the self-heal cache bundle).
+function writeFakeLib(libDistDir: string, sentinel: string): void {
+  fs.mkdirSync(libDistDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(libDistDir, 'index.js'),
+    `module.exports = { SENTINEL: ${JSON.stringify(sentinel)}, CodeGraph: function CodeGraph() {} };\n`
+  );
+}
+
+function installPlatformPackage(root: string, sentinel: string): void {
+  const pkgRoot = path.join(root, 'node_modules', '@colbymchenry', `codegraph-${target}`);
+  writeFakeLib(path.join(pkgRoot, 'lib', 'dist'), sentinel);
+  fs.writeFileSync(
+    path.join(pkgRoot, 'package.json'),
+    JSON.stringify({ name: `@colbymchenry/codegraph-${target}`, version: VERSION }) + '\n'
+  );
+}
+
+// require() the SDK in a child process so each case gets a fresh module cache.
+function requireSdk(mainPkg: string, env: Record<string, string> = {}) {
+  const code =
+    `try { const m = require(${JSON.stringify(path.join(mainPkg, 'npm-sdk.js'))});` +
+    ` process.stdout.write(JSON.stringify({ sentinel: m.SENTINEL, cg: typeof m.CodeGraph })); }` +
+    ` catch (e) { process.stderr.write(String(e && e.message || e)); process.exit(7); }`;
+  const r = spawnSync(process.execPath, ['-e', code], {
+    encoding: 'utf8',
+    env: { ...process.env, ...env },
+  });
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr };
+}
+
+describe('npm-sdk programmatic entry', () => {
+  it('re-exports the installed platform bundle library', () => {
+    const { root, mainPkg } = makeConsumer();
+    installPlatformPackage(root, 'platform-lib');
+    // Isolate from any real self-healed cache on this machine.
+    const r = requireSdk(mainPkg, { CODEGRAPH_INSTALL_DIR: path.join(root, '.empty-cache') });
+    expect(r.status).toBe(0);
+    expect(JSON.parse(r.stdout)).toEqual({ sentinel: 'platform-lib', cg: 'function' });
+  });
+
+  it('falls back to a self-healed cache bundle when the optional dep is absent', () => {
+    const { root, mainPkg } = makeConsumer(); // no platform package installed
+    const cacheDir = path.join(root, 'cache');
+    writeFakeLib(
+      path.join(cacheDir, 'bundles', `${target}-${VERSION}`, 'lib', 'dist'),
+      'cache-lib'
+    );
+    const r = requireSdk(mainPkg, { CODEGRAPH_INSTALL_DIR: cacheDir });
+    expect(r.status).toBe(0);
+    expect(JSON.parse(r.stdout)).toEqual({ sentinel: 'cache-lib', cg: 'function' });
+  });
+
+  it('throws an actionable error when no bundle is installed or cached', () => {
+    const { root, mainPkg } = makeConsumer(); // no platform package, empty cache
+    const r = requireSdk(mainPkg, { CODEGRAPH_INSTALL_DIR: path.join(root, '.empty-cache') });
+    expect(r.status).toBe(7);
+    expect(r.stderr).toContain(`@colbymchenry/codegraph-${target}`);
+    expect(r.stderr).toContain('not installed');
+    expect(r.stderr).toContain('registry.npmjs.org');
+  });
+});
diff --git a/__tests__/npm-shim.test.ts b/__tests__/npm-shim.test.ts
new file mode 100644
index 000000000..16e70506a
--- /dev/null
+++ b/__tests__/npm-shim.test.ts
@@ -0,0 +1,208 @@
+/**
+ * npm thin-installer launcher (`scripts/npm-shim.js`) tests.
+ *
+ * The shim runs on the user's own Node, locates the per-platform optionalDependency
+ * bundle, and — when a registry mirror failed to deliver it (issue #303) — falls
+ * back to downloading the bundle from GitHub Releases. These tests exercise that
+ * shim as a real subprocess from a temp "main package" dir (its own package.json
+ * + node_modules), so resolution and version lookup behave hermetically.
+ *
+ * The download/checksum paths run against a local self-signed HTTPS server via
+ * CODEGRAPH_DOWNLOAD_BASE — no real network, no published release needed. The
+ * shim is launched with async `spawn` (not spawnSync), so the test's event loop
+ * stays free to serve those requests.
+ *
+ * POSIX only: the fake bundle launcher is a shell script and extraction uses the
+ * system `tar`. Skipped on Windows (where the shim's exec path differs anyway).
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { spawn, execSync } from 'child_process';
+import * as https from 'https';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import type { AddressInfo } from 'net';
+
+const SHIM_SRC = path.join(__dirname, '..', 'scripts', 'npm-shim.js');
+const target = `${process.platform}-${process.arch}`;
+const asset = `codegraph-${target}.tar.gz`;
+const isWindows = process.platform === 'win32';
+
+function hasOpenssl(): boolean {
+  try { execSync('openssl version', { stdio: 'ignore' }); return true; } catch { return false; }
+}
+const CAN_NET = !isWindows && hasOpenssl();
+
+function mkTmp(label: string): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), `cg-shim-${label}-`));
+}
+
+// A temp dir standing in for the installed @colbymchenry/codegraph main package.
+function makePkg(version = '9.9.9-test'): string {
+  const dir = mkTmp('pkg');
+  fs.copyFileSync(SHIM_SRC, path.join(dir, 'npm-shim.js'));
+  fs.writeFileSync(path.join(dir, 'package.json'),
+    JSON.stringify({ name: '@colbymchenry/codegraph', version }) + '\n');
+  return dir;
+}
+
+// A fake bundle launcher that prints a marker + its args, so we can prove the
+// shim found and exec'd it (and passed args through).
+function writeLauncher(binDir: string): void {
+  fs.mkdirSync(binDir, { recursive: true });
+  const p = path.join(binDir, 'codegraph');
+  fs.writeFileSync(p, '#!/bin/sh\necho "FAKE_BUNDLE_RAN args:$*"\n');
+  fs.chmodSync(p, 0o755);
+}
+
+// Launch the shim with async spawn so the in-process HTTPS server can respond
+// while it runs (spawnSync would block this event loop and deadlock).
+function runShim(pkgDir: string, args: string[], env: Record<string, string>) {
+  return new Promise<{ status: number | null; stdout: string; stderr: string }>((resolve) => {
+    const child = spawn(process.execPath, [path.join(pkgDir, 'npm-shim.js'), ...args], {
+      env: { ...process.env, ...env },
+    });
+    let stdout = '', stderr = '';
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('close', (status) => resolve({ status, stdout, stderr }));
+  });
+}
+
+describe.skipIf(isWindows)('npm-shim launcher', () => {
+  it('runs the installed optional-dependency bundle without any download', async () => {
+    const pkg = makePkg();
+    const platformPkg = path.join(pkg, 'node_modules', '@colbymchenry', `codegraph-${target}`);
+    writeLauncher(path.join(platformPkg, 'bin'));
+    fs.writeFileSync(path.join(platformPkg, 'package.json'),
+      JSON.stringify({ name: `@colbymchenry/codegraph-${target}`, version: '9.9.9-test' }) + '\n');
+    const cache = mkTmp('cache');
+    const r = await runShim(pkg, ['--probe-abc'], { CODEGRAPH_INSTALL_DIR: cache });
+
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain('FAKE_BUNDLE_RAN');
+    expect(r.stdout).toContain('--probe-abc');     // args passed through
+    expect(r.stderr).not.toContain('downloading'); // never reached the fallback
+    expect(fs.existsSync(path.join(cache, 'bundles'))).toBe(false);
+  });
+
+  it('uses an already-cached bundle even when downloads are disabled', async () => {
+    const pkg = makePkg('1.2.3-cached');
+    const cache = mkTmp('cache');
+    writeLauncher(path.join(cache, 'bundles', `${target}-1.2.3-cached`, 'bin'));
+    const r = await runShim(pkg, ['--probe-xyz'], {
+      CODEGRAPH_INSTALL_DIR: cache,
+      CODEGRAPH_NO_DOWNLOAD: '1',
+    });
+
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain('FAKE_BUNDLE_RAN');
+    expect(r.stdout).toContain('--probe-xyz');
+    expect(r.stderr).toBe('');
+  });
+
+  it('prints actionable guidance and exits 1 when disabled with no bundle', async () => {
+    const pkg = makePkg();
+    const r = await runShim(pkg, ['--version'], {
+      CODEGRAPH_INSTALL_DIR: mkTmp('cache'),
+      CODEGRAPH_NO_DOWNLOAD: '1',
+    });
+
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain(`no prebuilt bundle for ${target}`);
+    expect(r.stderr).toContain(`@colbymchenry/codegraph-${target}`);
+    expect(r.stderr).toContain('--registry=https://registry.npmjs.org');
+    expect(r.stderr).toContain('install.sh');
+  });
+});
+
+describe.skipIf(!CAN_NET)('npm-shim download fallback (local HTTPS)', () => {
+  let server: https.Server;
+  let port = 0;
+  let fixtureBytes: Buffer;
+  let fixtureSha: string;
+  let sumsBody: string | null = null; // per-test: SHA256SUMS contents, or null for 404
+
+  beforeAll(async () => {
+    // Self-signed cert for the mock release host.
+    const cdir = mkTmp('tls');
+    const keyP = path.join(cdir, 'key.pem');
+    const certP = path.join(cdir, 'cert.pem');
+    execSync(
+      `openssl req -x509 -newkey rsa:2048 -nodes -keyout ${keyP} -out ${certP} -days 1 -subj "/CN=localhost"`,
+      { stdio: 'ignore' },
+    );
+
+    // Build a fake bundle archive (codegraph-<target>/bin/codegraph), like a real release asset.
+    const work = mkTmp('fixture');
+    writeLauncher(path.join(work, `codegraph-${target}`, 'bin'));
+    const archive = path.join(work, asset);
+    execSync(`tar -czf ${JSON.stringify(archive)} -C ${JSON.stringify(work)} codegraph-${target}`);
+    fixtureBytes = fs.readFileSync(archive);
+    fixtureSha = crypto.createHash('sha256').update(fixtureBytes).digest('hex');
+
+    server = https.createServer({ key: fs.readFileSync(keyP), cert: fs.readFileSync(certP) }, (req, res) => {
+      const url = req.url || '';
+      if (url.endsWith(`/${asset}`)) {
+        res.writeHead(200); res.end(fixtureBytes);
+      } else if (url.endsWith('/SHA256SUMS')) {
+        if (sumsBody === null) { res.writeHead(404); res.end('not found'); }
+        else { res.writeHead(200); res.end(sumsBody); }
+      } else {
+        res.writeHead(404); res.end('not found');
+      }
+    });
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+    port = (server.address() as AddressInfo).port;
+  }, 30000);
+
+  afterAll(() => { server?.close(); });
+
+  function netEnv(cache: string): Record<string, string> {
+    return {
+      CODEGRAPH_INSTALL_DIR: cache,
+      CODEGRAPH_DOWNLOAD_BASE: `https://127.0.0.1:${port}`,
+      NODE_TLS_REJECT_UNAUTHORIZED: '0',
+    };
+  }
+
+  it('downloads, verifies the checksum, extracts, and execs the bundle', async () => {
+    sumsBody = `${fixtureSha}  ${asset}\n`;
+    const pkg = makePkg('5.0.0-net');
+    const cache = mkTmp('cache');
+    const r = await runShim(pkg, ['--probe-net'], netEnv(cache));
+
+    expect(r.stderr).toContain('downloading');
+    expect(r.stderr).toContain('checksum verified');
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain('FAKE_BUNDLE_RAN');
+    expect(r.stdout).toContain('--probe-net');
+    expect(fs.existsSync(path.join(cache, 'bundles', `${target}-5.0.0-net`, 'bin', 'codegraph'))).toBe(true);
+  }, 20000);
+
+  it('aborts (exit 1) on a checksum mismatch and caches nothing', async () => {
+    sumsBody = `${'0'.repeat(64)}  ${asset}\n`;
+    const pkg = makePkg('5.0.0-bad');
+    const cache = mkTmp('cache');
+    const r = await runShim(pkg, ['--version'], netEnv(cache));
+
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain('checksum mismatch');
+    expect(r.stdout).not.toContain('FAKE_BUNDLE_RAN'); // never exec'd a tampered bundle
+    expect(fs.existsSync(path.join(cache, 'bundles', `${target}-5.0.0-bad`))).toBe(false);
+  }, 20000);
+
+  it('proceeds when no SHA256SUMS is published (older releases)', async () => {
+    sumsBody = null; // 404
+    const pkg = makePkg('5.0.0-nosums');
+    const cache = mkTmp('cache');
+    const r = await runShim(pkg, ['--version'], netEnv(cache));
+
+    expect(r.status).toBe(0);
+    expect(r.stderr).toContain('downloading');
+    expect(r.stderr).not.toContain('checksum verified'); // skipped, not failed
+    expect(r.stdout).toContain('FAKE_BUNDLE_RAN');
+  }, 20000);
+});
diff --git a/__tests__/object-literal-methods.test.ts b/__tests__/object-literal-methods.test.ts
new file mode 100644
index 000000000..1722ad2d0
--- /dev/null
+++ b/__tests__/object-literal-methods.test.ts
@@ -0,0 +1,176 @@
+/**
+ * Object-literal method extraction (general AST rule).
+ *
+ * The extractor pulls function-valued properties out of an object literal that
+ * is the value of an exported const — either DIRECTLY
+ * (`export const actions = { foo: () => {} }`) or RETURNED by an initializer
+ * call (`export const useStore = create((set, get) => ({ foo: () => {} }))`,
+ * incl. middleware wrappers). This makes store actions (Zustand/Redux/Pinia/
+ * MobX/handler maps) real nodes, so `codegraph_node`/`callers` on them resolve
+ * instead of returning "not found" and forcing the agent to Read the store.
+ *
+ * Keyed purely on AST shape — no library names in the implementation — so any
+ * same-shaped store is covered. Resolution then falls out of the existing
+ * exact-name matcher: every call form (`const {foo}=useStore.getState(); foo()`,
+ * `useStore.getState().foo()`, in-store `get().foo()`) reduces to a bare `foo`
+ * call that resolves to the action node once it exists.
+ */
+import { describe, it, expect, beforeAll, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { CodeGraph } from '../src';
+import { extractFromSource } from '../src/extraction';
+import { initGrammars, loadAllGrammars } from '../src/extraction/grammars';
+
+beforeAll(async () => {
+  await initGrammars();
+  await loadAllGrammars();
+});
+
+describe('object-literal method extraction', () => {
+  it('extracts Zustand store actions (object returned by create()) as function nodes', () => {
+    const code = `
+      import { create } from 'zustand'
+      interface Store {
+        count: number
+        fetchUser(): Promise<void>
+        switchOrganization(id: string): Promise<void>
+        reset(): void
+      }
+      export const useStore = create<Store>((set, get) => ({
+        count: 0,
+        fetchUser: async () => { await get().reset() },
+        switchOrganization: async (id: string) => { set({ count: 1 }) },
+        reset: () => set({ count: 0 }),
+      }))
+    `;
+    const result = extractFromSource('store.ts', code);
+    const fnNames = result.nodes.filter((n) => n.kind === 'function').map((n) => n.name);
+    expect(fnNames).toContain('fetchUser');
+    expect(fnNames).toContain('switchOrganization');
+    expect(fnNames).toContain('reset');
+
+    // Each action's body was walked: fetchUser references its sibling `reset`,
+    // so an in-store calls edge will resolve once the pipeline runs.
+    const fetchUser = result.nodes.find((n) => n.name === 'fetchUser')!;
+    const fetchUserRefs = result.unresolvedReferences.filter((r) => r.fromNodeId === fetchUser.id);
+    expect(fetchUserRefs.map((r) => r.referenceName)).toContain('reset');
+
+    // The action's body wasn't mis-attributed to the file scope (the reason we
+    // skip the generic body-visit for the store-factory call).
+    const fileNode = result.nodes.find((n) => n.kind === 'file')!;
+    const fileRefs = result.unresolvedReferences.filter((r) => r.fromNodeId === fileNode.id);
+    expect(fileRefs.map((r) => r.referenceName)).not.toContain('reset');
+  });
+
+  it('extracts actions through a middleware wrapper (create(persist(...)))', () => {
+    const code = `
+      import { create } from 'zustand'
+      import { persist } from 'zustand/middleware'
+      export const useCounter = create(
+        persist(
+          (set, get) => ({
+            value: 0,
+            increment: () => set({ value: get().value + 1 }),
+          }),
+          { name: 'counter' }
+        )
+      )
+    `;
+    const result = extractFromSource('counter.ts', code);
+    const fnNames = result.nodes.filter((n) => n.kind === 'function').map((n) => n.name);
+    expect(fnNames).toContain('increment');
+  });
+
+  it('extracts actions when the initializer returns via a block (=> { return {...} })', () => {
+    const code = `
+      import { create } from 'zustand'
+      export const useThing = create((set) => {
+        const initial = 0
+        return {
+          value: initial,
+          bump: () => set({ value: 1 }),
+        }
+      })
+    `;
+    const result = extractFromSource('thing.ts', code);
+    const fnNames = result.nodes.filter((n) => n.kind === 'function').map((n) => n.name);
+    expect(fnNames).toContain('bump');
+  });
+
+  it('does NOT extract methods from a non-exported call-wrapped object (noise gate)', () => {
+    const code = `
+      function wrap(f: any) { return f }
+      const local = wrap(() => ({ shouldNotExtract: () => {} }))
+    `;
+    const result = extractFromSource('inline.ts', code);
+    const names = result.nodes.map((n) => n.name);
+    expect(names).not.toContain('shouldNotExtract');
+  });
+
+  it('still extracts the existing direct-object shape (export const actions = {...})', () => {
+    const code = `
+      export const actions = {
+        load: async () => { helper() },
+      }
+      function helper() {}
+    `;
+    const result = extractFromSource('actions.ts', code);
+    const fnNames = result.nodes.filter((n) => n.kind === 'function').map((n) => n.name);
+    expect(fnNames).toContain('load');
+  });
+});
+
+describe('object-literal method resolution (end-to-end)', () => {
+  let tmpDir: string | undefined;
+  afterEach(() => {
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  it('resolves callers of store actions across files (destructured + chained getState())', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-store-'));
+    fs.writeFileSync(path.join(tmpDir, 'package.json'), '{"name":"t","dependencies":{"zustand":"^4"}}\n');
+    fs.writeFileSync(
+      path.join(tmpDir, 'store.ts'),
+      `import { create } from 'zustand'\n` +
+        `interface S { fetchUser(): Promise<void>; reset(): void }\n` +
+        `export const useStore = create<S>((set, get) => ({\n` +
+        `  fetchUser: async () => { get().reset() },\n` +
+        `  reset: () => set({}),\n` +
+        `}))\n`
+    );
+    fs.writeFileSync(
+      path.join(tmpDir, 'caller.ts'),
+      `import { useStore } from './store'\n` +
+        `export async function loginFlow() {\n` +
+        `  const { fetchUser } = useStore.getState()\n` +
+        `  await fetchUser()\n` +
+        `}\n` +
+        `export function hardReset() {\n` +
+        `  useStore.getState().reset()\n` +
+        `}\n`
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    await cg.indexAll();
+
+    const fns = cg.getNodesByKind('function');
+    const fetchUser = fns.find((n) => n.name === 'fetchUser' && n.filePath.endsWith('store.ts'));
+    const reset = fns.find((n) => n.name === 'reset' && n.filePath.endsWith('store.ts'));
+    expect(fetchUser).toBeDefined();
+    expect(reset).toBeDefined();
+
+    // Destructured-then-bare call: loginFlow -> fetchUser
+    const fetchUserCallers = cg.getCallers(fetchUser!.id).map((c) => c.node.name);
+    expect(fetchUserCallers).toContain('loginFlow');
+
+    // Chained getState() call: hardReset -> reset, AND in-store sibling: fetchUser -> reset
+    const resetCallers = cg.getCallers(reset!.id).map((c) => c.node.name);
+    expect(resetCallers).toContain('hardReset');
+    expect(resetCallers).toContain('fetchUser');
+
+    cg.close();
+  });
+});
diff --git a/__tests__/ppid-watchdog.test.ts b/__tests__/ppid-watchdog.test.ts
new file mode 100644
index 000000000..ba270fa7d
--- /dev/null
+++ b/__tests__/ppid-watchdog.test.ts
@@ -0,0 +1,138 @@
+/**
+ * Unit coverage for the PPID-watchdog decision logic (#277, #692).
+ *
+ * The live watchdog timers in `proxy.ts` / `index.ts` are integration-tested on
+ * POSIX in `mcp-ppid-watchdog.test.ts`, but that test is skipped on Windows
+ * (`process.kill(pid, 'SIGKILL')` and reparenting are POSIX-specific). That gap
+ * is exactly how the Windows leak (#692) shipped: on Windows `process.ppid`
+ * never changes when the parent dies, so the old change-only check could never
+ * fire. These pure-function tests exercise the Windows branch on any OS by
+ * stubbing `isAlive` and `platform`.
+ */
+import { describe, it, expect } from 'vitest';
+import { supervisionLostReason } from '../src/mcp/ppid-watchdog';
+
+const alive = () => true;
+const dead = () => false;
+/** Alive for everyone except the listed pids. */
+const deadOnly = (...pids: number[]) => (pid: number) => !pids.includes(pid);
+
+describe('supervisionLostReason', () => {
+  describe('POSIX (parent death reparents → ppid changes)', () => {
+    it('returns null while the parent is unchanged', () => {
+      expect(
+        supervisionLostReason({
+          originalPpid: 100,
+          currentPpid: 100,
+          hostPpid: null,
+          isAlive: alive,
+          platform: 'linux',
+        }),
+      ).toBeNull();
+    });
+
+    it('detects a reparent (ppid divergence) as the death signal', () => {
+      const reason = supervisionLostReason({
+        originalPpid: 100,
+        currentPpid: 1, // reparented to init
+        hostPpid: null,
+        isAlive: alive,
+        platform: 'linux',
+      });
+      expect(reason).toBe('ppid 100 -> 1');
+    });
+
+    it('does NOT use liveness on POSIX — a dead original ppid is not orphaning', () => {
+      // A double-forked grandparent can die while we stay correctly parented.
+      // POSIX must rely on the change-check only, or it would false-positive.
+      expect(
+        supervisionLostReason({
+          originalPpid: 100,
+          currentPpid: 100,
+          hostPpid: null,
+          isAlive: dead,
+          platform: 'linux',
+        }),
+      ).toBeNull();
+    });
+  });
+
+  describe('Windows (ppid is stable across parent death → poll liveness)', () => {
+    it('returns null while the original parent is still alive', () => {
+      expect(
+        supervisionLostReason({
+          originalPpid: 100,
+          currentPpid: 100,
+          hostPpid: null,
+          isAlive: alive,
+          platform: 'win32',
+        }),
+      ).toBeNull();
+    });
+
+    it('detects parent death by liveness even though ppid is unchanged (the #692 fix)', () => {
+      const reason = supervisionLostReason({
+        originalPpid: 100,
+        currentPpid: 100, // Windows never reparents
+        hostPpid: null,
+        isAlive: deadOnly(100),
+        platform: 'win32',
+      });
+      expect(reason).toBe('parent pid 100 exited');
+    });
+
+    it('ignores pid 0/1 — never a real Windows parent, must not trigger shutdown', () => {
+      for (const ppid of [0, 1]) {
+        expect(
+          supervisionLostReason({
+            originalPpid: ppid,
+            currentPpid: ppid,
+            hostPpid: null,
+            isAlive: dead,
+            platform: 'win32',
+          }),
+        ).toBeNull();
+      }
+    });
+  });
+
+  describe('threaded host pid (reached past an intermediate launcher shim)', () => {
+    it('shuts down when the host pid is gone, on either platform', () => {
+      for (const platform of ['linux', 'win32'] as const) {
+        const reason = supervisionLostReason({
+          originalPpid: 100,
+          currentPpid: 100,
+          hostPpid: 42,
+          isAlive: deadOnly(42), // shim 100 alive, host 42 dead
+          platform,
+        });
+        expect(reason).toBe('host pid 42 exited');
+      }
+    });
+
+    it('stays supervised while the host pid is alive', () => {
+      expect(
+        supervisionLostReason({
+          originalPpid: 100,
+          currentPpid: 100,
+          hostPpid: 42,
+          isAlive: alive,
+          platform: 'linux',
+        }),
+      ).toBeNull();
+    });
+  });
+
+  describe('signal precedence', () => {
+    it('reports the ppid change ahead of a host-gone reason', () => {
+      const reason = supervisionLostReason({
+        originalPpid: 100,
+        currentPpid: 1,
+        hostPpid: 42,
+        isAlive: dead,
+        platform: 'linux',
+      });
+      expect(reason).toBe('ppid 100 -> 1');
+    });
+  });
+});
diff --git a/__tests__/pr19-improvements.test.ts b/__tests__/pr19-improvements.test.ts
index d43dceb23..8e8ca8177 100644
--- a/__tests__/pr19-improvements.test.ts
+++ b/__tests__/pr19-improvements.test.ts
@@ -45,11 +45,11 @@ function cleanupTempDir(dir: string): void {
   }
 }
 
-// Check if better-sqlite3 native bindings are available
+// Check if the node:sqlite backend is available (Node >= 22.5)
 function hasSqliteBindings(): boolean {
   try {
-    const Database = require('better-sqlite3');
-    const db = new Database(':memory:');
+    const { DatabaseSync } = require('node:sqlite');
+    const db = new DatabaseSync(':memory:');
     db.close();
     return true;
   } catch {
@@ -299,7 +299,7 @@ describe('Best-Candidate Resolution', () => {
 describe('Schema v2 Migration', () => {
   it.skipIf(!HAS_SQLITE)('should have correct current schema version', async () => {
     const { CURRENT_SCHEMA_VERSION } = await import('../src/db/migrations');
-    expect(CURRENT_SCHEMA_VERSION).toBe(4);
+    expect(CURRENT_SCHEMA_VERSION).toBe(5);
   });
 
   it.skipIf(!HAS_SQLITE)('should have migration for version 2', async () => {
@@ -501,10 +501,10 @@ describe('MCP Tool Improvements', () => {
     expect(typeof ToolHandler).toBe('function');
   });
 
-  it.skipIf(!HAS_SQLITE)('should have findSymbol and truncateOutput as private methods', async () => {
+  it.skipIf(!HAS_SQLITE)('should have findSymbolMatches and truncateOutput as private methods', async () => {
     const { ToolHandler } = await import('../src/mcp/tools');
     const proto = ToolHandler.prototype;
-    expect(typeof (proto as any).findSymbol).toBe('function');
+    expect(typeof (proto as any).findSymbolMatches).toBe('function');
     expect(typeof (proto as any).truncateOutput).toBe('function');
   });
 
@@ -567,20 +567,19 @@ export function getValueFromCache(): number { return 2; }
       await cg.indexAll();
 
       const handler = new ToolHandler(cg);
-      const findSymbol = (handler as any).findSymbol.bind(handler);
+      const findSymbolMatches = (handler as any).findSymbolMatches.bind(handler);
 
-      const match = findSymbol(cg, 'getValue');
-      expect(match).not.toBeNull();
-      expect(match.node.name).toBe('getValue');
-      // Should not have a disambiguation note for single exact match
-      expect(match.note).toBe('');
+      const matches = findSymbolMatches(cg, 'getValue');
+      // Exact-name match wins — a single result, not the partial getValueFromCache.
+      expect(matches.length).toBe(1);
+      expect(matches[0].name).toBe('getValue');
 
       handler.closeAll();
       cg.destroy();
       cleanupTempDir(tmpDir);
     });
 
-    it.skipIf(!HAS_SQLITE)('should note when multiple symbols share the same name', async () => {
+    it.skipIf(!HAS_SQLITE)('should return all definitions when multiple symbols share the same name', async () => {
       const { ToolHandler } = await import('../src/mcp/tools');
       const CodeGraph = (await import('../src/index')).default;
 
@@ -602,20 +601,21 @@ export function handle(): void {}
       await cg.indexAll();
 
       const handler = new ToolHandler(cg);
-      const findSymbol = (handler as any).findSymbol.bind(handler);
+      const findSymbolMatches = (handler as any).findSymbolMatches.bind(handler);
 
-      const match = findSymbol(cg, 'handle');
-      expect(match).not.toBeNull();
-      expect(match.node.name).toBe('handle');
-      // Should have a disambiguation note
-      expect(match.note).toContain('2 symbols named "handle"');
+      // Both same-named definitions are returned (no longer one + a dead-end
+      // note) so codegraph_node can hand back every overload and the agent never
+      // Reads to find the one it wanted.
+      const matches = findSymbolMatches(cg, 'handle');
+      expect(matches.length).toBe(2);
+      expect(matches.every((n: any) => n.name === 'handle')).toBe(true);
 
       handler.closeAll();
       cg.destroy();
       cleanupTempDir(tmpDir);
     });
 
-    it.skipIf(!HAS_SQLITE)('should return null when symbol is not found', async () => {
+    it.skipIf(!HAS_SQLITE)('should return no matches when symbol is not found', async () => {
       const { ToolHandler } = await import('../src/mcp/tools');
       const CodeGraph = (await import('../src/index')).default;
 
@@ -630,10 +630,10 @@ export function handle(): void {}
       await cg.indexAll();
 
       const handler = new ToolHandler(cg);
-      const findSymbol = (handler as any).findSymbol.bind(handler);
+      const findSymbolMatches = (handler as any).findSymbolMatches.bind(handler);
 
-      const match = findSymbol(cg, 'nonExistentSymbol');
-      expect(match).toBeNull();
+      const matches = findSymbolMatches(cg, 'nonExistentSymbol');
+      expect(matches.length).toBe(0);
 
       handler.closeAll();
       cg.destroy();
diff --git a/__tests__/prepare-release.test.ts b/__tests__/prepare-release.test.ts
new file mode 100644
index 000000000..1491f8897
--- /dev/null
+++ b/__tests__/prepare-release.test.ts
@@ -0,0 +1,221 @@
+/**
+ * Unit tests for `scripts/prepare-release.mjs`.
+ *
+ * The script reads CHANGELOG.md and package.json from `process.cwd()`,
+ * so the tests run it via `node` in a temp directory after staging
+ * those files. Real script, real fs — keeps the test honest about what
+ * the workflow will actually do.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+const SCRIPT = path.resolve(__dirname, '..', 'scripts', 'prepare-release.mjs');
+
+function run(cwd: string, ...args: string[]) {
+  const out = execFileSync('node', [SCRIPT, ...args], { cwd, encoding: 'utf8' });
+  return out.trim();
+}
+
+function setup(changelog: string, version = '1.2.3') {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'prepare-release-'));
+  fs.writeFileSync(path.join(dir, 'CHANGELOG.md'), changelog);
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'x', version }));
+  return dir;
+}
+
+const HEADER = `# Changelog
+
+Some intro.
+
+`;
+
+describe('prepare-release.mjs', () => {
+  let dir: string;
+  afterEach(() => {
+    if (dir && fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  describe('Case A: [version] block does not yet exist', () => {
+    it('renames [Unreleased] to [version] - <today> and adds a fresh empty [Unreleased]', () => {
+      dir = setup(
+        HEADER +
+          `## [Unreleased]\n\n### Added\n- New feature foo\n- New feature bar\n\n### Fixed\n- Fixed thing\n\n## [1.2.2] - 2026-01-01\n\n### Added\n- Old entry\n`,
+      );
+      const out = run(dir);
+      expect(out).toMatch(/renamed \[Unreleased\] to \[1\.2\.3\]/);
+      const result = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+
+      // [Unreleased] is now empty and at the top.
+      expect(result).toMatch(/## \[Unreleased\]\n\n\n## \[1\.2\.3\]/);
+      // [1.2.3] gets a date.
+      expect(result).toMatch(/## \[1\.2\.3\] - \d{4}-\d{2}-\d{2}/);
+      // Promoted content lives under [1.2.3].
+      const v123Section = result.split('## [1.2.3]')[1].split('## [1.2.2]')[0];
+      expect(v123Section).toContain('### Added');
+      expect(v123Section).toContain('- New feature foo');
+      expect(v123Section).toContain('- New feature bar');
+      expect(v123Section).toContain('### Fixed');
+      expect(v123Section).toContain('- Fixed thing');
+      // [1.2.2] is intact.
+      expect(result).toContain('## [1.2.2] - 2026-01-01');
+      expect(result).toContain('- Old entry');
+    });
+  });
+
+  describe('Case B: [version] already exists AND [Unreleased] has content', () => {
+    it('merges Unreleased sub-sections into the matching [version] sub-sections', () => {
+      // The v0.9.5 scenario verbatim: sparse [0.9.5] with two Fixed
+      // entries, full [Unreleased] above it with Added + more Fixed.
+      dir = setup(
+        HEADER +
+          `## [Unreleased]\n\n### Added\n- Big feature 1\n- Big feature 2\n\n### Fixed\n- Watcher fix\n- Worktree fix\n\n## [1.2.3] - 2026-02-02\n\n### Fixed\n- Old fix A\n- Old fix B\n\n## [1.2.2] - 2026-01-01\n`,
+      );
+      const out = run(dir);
+      expect(out).toMatch(/merged \d+ Unreleased entries/);
+      const result = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+
+      // [Unreleased] is emptied.
+      const unrelSection = result.split('## [Unreleased]')[1].split('## [1.2.3]')[0];
+      expect(unrelSection.trim()).toBe('');
+
+      // [1.2.3] now has BOTH the original Fixed entries AND the
+      // Unreleased Fixed entries, plus the new Added sub-section.
+      const v123Section = result.split('## [1.2.3]')[1].split('## [1.2.2]')[0];
+      expect(v123Section).toContain('### Added');
+      expect(v123Section).toContain('- Big feature 1');
+      expect(v123Section).toContain('- Big feature 2');
+      expect(v123Section).toContain('### Fixed');
+      expect(v123Section).toContain('- Old fix A');
+      expect(v123Section).toContain('- Old fix B');
+      expect(v123Section).toContain('- Watcher fix');
+      expect(v123Section).toContain('- Worktree fix');
+      // Date on [1.2.3] is preserved (we don't re-stamp it).
+      expect(result).toContain('## [1.2.3] - 2026-02-02');
+    });
+
+    it('appends sub-sections that exist only in [Unreleased] to the [version] block', () => {
+      dir = setup(
+        HEADER +
+          `## [Unreleased]\n\n### Security\n- CVE patch\n\n## [1.2.3] - 2026-02-02\n\n### Fixed\n- Old fix\n`,
+      );
+      run(dir);
+      const result = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+      const v123 = result.split('## [1.2.3]')[1];
+      expect(v123).toContain('### Fixed');
+      expect(v123).toContain('- Old fix');
+      expect(v123).toContain('### Security');
+      expect(v123).toContain('- CVE patch');
+    });
+  });
+
+  describe('Case C: [Unreleased] has no entries', () => {
+    it('is a no-op when [Unreleased] is empty', () => {
+      dir = setup(HEADER + `## [Unreleased]\n\n## [1.2.3] - 2026-02-02\n\n### Fixed\n- thing\n`);
+      const before = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+      const out = run(dir);
+      expect(out).toMatch(/nothing to do/);
+      const after = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+      expect(after).toBe(before);
+    });
+
+    it('is a no-op when [Unreleased] has only sub-section headings with no bullets', () => {
+      dir = setup(
+        HEADER + `## [Unreleased]\n\n### Added\n\n### Fixed\n\n## [1.2.3] - 2026-02-02\n`,
+      );
+      const before = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+      const out = run(dir);
+      expect(out).toMatch(/nothing to do/);
+      const after = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+      expect(after).toBe(before);
+    });
+  });
+
+  describe('idempotency', () => {
+    it('running twice produces the same output as running once', () => {
+      dir = setup(
+        HEADER +
+          `## [Unreleased]\n\n### Added\n- Thing A\n\n## [1.2.2] - 2026-01-01\n\n### Added\n- Old\n`,
+      );
+      run(dir); // first run promotes
+      const afterFirst = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+      const out2 = run(dir); // second run should be a no-op
+      const afterSecond = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+      expect(out2).toMatch(/nothing to do/);
+      expect(afterSecond).toBe(afterFirst);
+    });
+  });
+
+  describe('version source', () => {
+    it('reads the target version from package.json by default', () => {
+      dir = setup(HEADER + `## [Unreleased]\n\n### Added\n- x\n`, '9.9.9');
+      run(dir);
+      const result = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+      expect(result).toContain('## [9.9.9]');
+    });
+
+    it('accepts an explicit version argument that overrides package.json', () => {
+      dir = setup(HEADER + `## [Unreleased]\n\n### Added\n- x\n`, '9.9.9');
+      run(dir, '5.5.5');
+      const result = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+      expect(result).toContain('## [5.5.5]');
+      expect(result).not.toContain('## [9.9.9]');
+    });
+  });
+
+  describe('link reference', () => {
+    it('appends a `[version]: https://...` link reference at EOF when promoting (Case A)', () => {
+      dir = setup(HEADER + `## [Unreleased]\n\n### Added\n- x\n\n## [1.2.2] - 2026-01-01\n`);
+      run(dir);
+      const result = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+      expect(result).toContain(
+        '[1.2.3]: https://github.com/colbymchenry/codegraph/releases/tag/v1.2.3',
+      );
+    });
+
+    it('appends a link reference when merging into an existing [version] (Case B)', () => {
+      dir = setup(
+        HEADER + `## [Unreleased]\n\n### Added\n- new\n\n## [1.2.3] - 2026-02-02\n\n### Fixed\n- prior\n`,
+      );
+      run(dir);
+      const result = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+      expect(result).toContain(
+        '[1.2.3]: https://github.com/colbymchenry/codegraph/releases/tag/v1.2.3',
+      );
+    });
+
+    it('does not double-add an existing link reference', () => {
+      const ref = '[1.2.3]: https://github.com/colbymchenry/codegraph/releases/tag/v1.2.3';
+      dir = setup(
+        HEADER +
+          `## [Unreleased]\n\n### Added\n- x\n\n## [1.2.2] - 2026-01-01\n\n${ref}\n`,
+      );
+      run(dir);
+      const result = fs.readFileSync(path.join(dir, 'CHANGELOG.md'), 'utf8');
+      const occurrences = result.split(ref).length - 1;
+      expect(occurrences).toBe(1);
+    });
+  });
+
+  describe('extractor integration', () => {
+    it('the resulting [version] block is what extract-release-notes.mjs would surface', () => {
+      // Run prepare, then extract — confirm the output contains all the
+      // promoted entries.
+      dir = setup(
+        HEADER +
+          `## [Unreleased]\n\n### Added\n- Feature A\n- Feature B\n\n### Fixed\n- Bug fix\n\n## [1.2.2] - 2026-01-01\n`,
+      );
+      run(dir);
+
+      const extractor = path.resolve(__dirname, '..', 'scripts', 'extract-release-notes.mjs');
+      const notes = execFileSync('node', [extractor, '1.2.3'], { cwd: dir, encoding: 'utf8' });
+      expect(notes).toContain('### Added');
+      expect(notes).toContain('Feature A');
+      expect(notes).toContain('Feature B');
+      expect(notes).toContain('### Fixed');
+      expect(notes).toContain('Bug fix');
+    });
+  });
+});
diff --git a/__tests__/react-native-bridge.test.ts b/__tests__/react-native-bridge.test.ts
new file mode 100644
index 000000000..dec3ce5cb
--- /dev/null
+++ b/__tests__/react-native-bridge.test.ts
@@ -0,0 +1,342 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import type { Node, Language } from '../src/types';
+import type { ResolutionContext, UnresolvedRef } from '../src/resolution/types';
+import { reactNativeBridgeResolver } from '../src/resolution/frameworks/react-native';
+import { CodeGraph } from '../src';
+
+/**
+ * Mock ResolutionContext for the React Native bridge resolver.
+ */
+function makeContext(nodes: Node[], fileContents: Record<string, string> = {}): ResolutionContext {
+  const byName = new Map<string, Node[]>();
+  for (const n of nodes) {
+    const arr = byName.get(n.name);
+    if (arr) arr.push(n);
+    else byName.set(n.name, [n]);
+  }
+  // Files = union of node files + any extra fileContents keys (for files that
+  // have content like .mm bridge declarations but no extracted nodes yet).
+  const allFiles = new Set<string>(
+    [...nodes.map((n) => n.filePath), ...Object.keys(fileContents)]
+  );
+  return {
+    getNodesInFile: (fp) => nodes.filter((n) => n.filePath === fp),
+    getNodesByName: (name) => byName.get(name) ?? [],
+    getNodesByQualifiedName: () => { throw new Error('not used'); },
+    getNodesByKind: (kind) => nodes.filter((n) => n.kind === kind),
+    getNodesByLowerName: () => { throw new Error('not used'); },
+    fileExists: (fp) => allFiles.has(fp),
+    readFile: (fp) => fileContents[fp] ?? null,
+    getProjectRoot: () => '/test',
+    getAllFiles: () => Array.from(allFiles),
+    getImportMappings: () => [],
+  };
+}
+
+function method(
+  name: string,
+  language: Language,
+  filePath: string,
+  startLine = 10
+): Node {
+  return {
+    id: `${language}:${filePath}:${name}:${startLine}`,
+    kind: 'method',
+    name,
+    qualifiedName: `${filePath}::${name}`,
+    filePath,
+    language,
+    startLine,
+    endLine: startLine + 5,
+    startColumn: 0,
+    endColumn: 0,
+    updatedAt: Date.now(),
+  } as Node;
+}
+
+function ref(name: string, language: Language, filePath: string): UnresolvedRef {
+  return {
+    fromNodeId: `caller:${filePath}`,
+    referenceName: name,
+    referenceKind: 'calls',
+    line: 1,
+    column: 0,
+    filePath,
+    language,
+  };
+}
+
+describe('React Native bridge resolver', () => {
+  describe('detect()', () => {
+    it('returns true when package.json declares react-native', () => {
+      const ctx = makeContext([], {
+        'package.json':
+          '{"name":"x","dependencies":{"react-native":"^0.73.0"}}',
+      });
+      expect(reactNativeBridgeResolver.detect(ctx)).toBe(true);
+    });
+
+    it('returns true when an ObjC file uses RCT_EXPORT_MODULE', () => {
+      const ctx = makeContext([], {
+        'NativeFoo.mm': '@implementation Foo\nRCT_EXPORT_MODULE()\n@end',
+      });
+      expect(reactNativeBridgeResolver.detect(ctx)).toBe(true);
+    });
+
+    it('returns true when a TS file uses TurboModuleRegistry', () => {
+      const ctx = makeContext([], {
+        'NativeFoo.ts':
+          "import { TurboModuleRegistry } from 'react-native';\n" +
+          "export default TurboModuleRegistry.getEnforcing<Spec>('Foo');",
+      });
+      expect(reactNativeBridgeResolver.detect(ctx)).toBe(true);
+    });
+
+    it('returns false when none of the RN signals are present', () => {
+      const ctx = makeContext([method('hi', 'objc', 'X.m')]);
+      expect(reactNativeBridgeResolver.detect(ctx)).toBe(false);
+    });
+  });
+
+  describe('legacy bridge — ObjC side', () => {
+    it('resolves JS callsite via RCT_EXPORT_METHOD with default module name', () => {
+      // RCTGeolocation → module name 'Geolocation' (RCT prefix stripped).
+      const native = method('getCurrentPosition:', 'objc', 'RCTGeolocation.m');
+      const ctx = makeContext([native], {
+        'package.json': '{"dependencies":{"react-native":"^0.73"}}',
+        'RCTGeolocation.m':
+          '@implementation RCTGeolocation\n' +
+          'RCT_EXPORT_MODULE()\n' +
+          'RCT_EXPORT_METHOD(getCurrentPosition:(RCTResponseSenderBlock)cb) {}\n' +
+          '@end',
+      });
+      const result = reactNativeBridgeResolver.resolve(
+        ref('getCurrentPosition', 'javascript', 'App.js'),
+        ctx
+      );
+      expect(result?.targetNodeId).toBe(native.id);
+      expect(result?.resolvedBy).toBe('framework');
+    });
+
+    it('resolves via explicit module name in RCT_EXPORT_MODULE(name)', () => {
+      const native = method('startScan:', 'objc', 'Bluetooth.m');
+      const ctx = makeContext([native], {
+        'package.json': '{"dependencies":{"react-native":"^0.73"}}',
+        'Bluetooth.m':
+          '@implementation BluetoothImpl\n' +
+          'RCT_EXPORT_MODULE(BluetoothManager)\n' +
+          'RCT_EXPORT_METHOD(startScan:(RCTResponseSenderBlock)cb) {}\n' +
+          '@end',
+      });
+      const result = reactNativeBridgeResolver.resolve(
+        ref('startScan', 'javascript', 'App.js'),
+        ctx
+      );
+      expect(result?.targetNodeId).toBe(native.id);
+    });
+
+    it('resolves RCT_REMAP_METHOD with JS-name override', () => {
+      const native = method('doInternalCompute:', 'objc', 'Computer.m');
+      const ctx = makeContext([native], {
+        'package.json': '{"dependencies":{"react-native":"^0.73"}}',
+        'Computer.m':
+          '@implementation Computer\n' +
+          'RCT_EXPORT_MODULE()\n' +
+          'RCT_REMAP_METHOD(compute, doInternalCompute:(NSDictionary *)opts) {}\n' +
+          '@end',
+      });
+      const result = reactNativeBridgeResolver.resolve(
+        ref('compute', 'javascript', 'App.js'),
+        ctx
+      );
+      expect(result?.targetNodeId).toBe(native.id);
+    });
+  });
+
+  describe('legacy bridge — Java side', () => {
+    it('resolves @ReactMethod with getName() literal', () => {
+      const native = method('getCurrentPosition', 'java', 'GeolocationModule.java');
+      const ctx = makeContext([native], {
+        'package.json': '{"dependencies":{"react-native":"^0.73"}}',
+        'GeolocationModule.java':
+          'class GeolocationModule extends ReactContextBaseJavaModule {\n' +
+          '  @Override public String getName() { return "Geolocation"; }\n' +
+          '  @ReactMethod public void getCurrentPosition(Callback cb) {}\n' +
+          '}',
+      });
+      const result = reactNativeBridgeResolver.resolve(
+        ref('getCurrentPosition', 'javascript', 'App.js'),
+        ctx
+      );
+      expect(result?.targetNodeId).toBe(native.id);
+    });
+
+    it('resolves Kotlin @ReactMethod fun', () => {
+      const native = method('startScan', 'kotlin', 'BluetoothModule.kt');
+      const ctx = makeContext([native], {
+        'package.json': '{"dependencies":{"react-native":"^0.73"}}',
+        'BluetoothModule.kt':
+          'class BluetoothModule(ctx: ReactApplicationContext) : ReactContextBaseJavaModule(ctx) {\n' +
+          '  override fun getName(): String = "BluetoothManager"\n' +
+          '  @ReactMethod fun startScan(cb: Callback) {}\n' +
+          '}',
+      });
+      const result = reactNativeBridgeResolver.resolve(
+        ref('startScan', 'javascript', 'App.js'),
+        ctx
+      );
+      expect(result?.targetNodeId).toBe(native.id);
+    });
+  });
+
+  describe('TurboModule spec resolution', () => {
+    it('matches spec method to native ObjC implementation by name', () => {
+      // The Spec interface lists `getTotalLength`; ObjC has a method by the
+      // same first keyword. Bridge matches by name.
+      const native = method('getTotalLength:', 'objc', 'RNSVGRenderableManager.mm');
+      const ctx = makeContext([native], {
+        'package.json': '{"dependencies":{"react-native":"^0.73"}}',
+        'NativeSvgRenderableModule.ts':
+          "import { TurboModuleRegistry } from 'react-native';\n" +
+          'export interface Spec extends TurboModule {\n' +
+          '  getTotalLength(tag: number): number;\n' +
+          '  isPointInFill(tag: number, options?: object): boolean;\n' +
+          '}\n' +
+          "export default TurboModuleRegistry.getEnforcing<Spec>('RNSVGRenderableModule');",
+      });
+      const result = reactNativeBridgeResolver.resolve(
+        ref('getTotalLength', 'tsx', 'SvgComponent.tsx'),
+        ctx
+      );
+      expect(result?.targetNodeId).toBe(native.id);
+    });
+
+    it('returns null when spec method has no matching native impl', () => {
+      const ctx = makeContext([], {
+        'package.json': '{"dependencies":{"react-native":"^0.73"}}',
+        'NativeFoo.ts':
+          "import { TurboModuleRegistry } from 'react-native';\n" +
+          'export interface Spec extends TurboModule {\n' +
+          '  thingThatDoesntExist(): void;\n' +
+          '}\n' +
+          "export default TurboModuleRegistry.getEnforcing<Spec>('Foo');",
+      });
+      const result = reactNativeBridgeResolver.resolve(
+        ref('thingThatDoesntExist', 'tsx', 'Caller.tsx'),
+        ctx
+      );
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('qualified vs bare callsite names', () => {
+    it('handles bare method name (post receiver-strip)', () => {
+      const native = method('compute:', 'objc', 'Mod.m');
+      const ctx = makeContext([native], {
+        'package.json': '{"dependencies":{"react-native":"^0.73"}}',
+        'Mod.m':
+          '@implementation Mod\nRCT_EXPORT_MODULE()\nRCT_EXPORT_METHOD(compute:(NSDictionary *)x) {}\n@end',
+      });
+      expect(
+        reactNativeBridgeResolver.resolve(ref('compute', 'javascript', 'App.js'), ctx)
+      ).not.toBeNull();
+    });
+
+    it('strips dot prefix on receiver-qualified callsite (NativeModules.Mod.compute → compute)', () => {
+      const native = method('compute:', 'objc', 'Mod.m');
+      const ctx = makeContext([native], {
+        'package.json': '{"dependencies":{"react-native":"^0.73"}}',
+        'Mod.m':
+          '@implementation Mod\nRCT_EXPORT_MODULE()\nRCT_EXPORT_METHOD(compute:(NSDictionary *)x) {}\n@end',
+      });
+      expect(
+        reactNativeBridgeResolver.resolve(
+          ref('NativeModules.Mod.compute', 'javascript', 'App.js'),
+          ctx
+        )
+      ).not.toBeNull();
+    });
+  });
+
+  it('does not resolve native-language callers (resolver is JS-side only)', () => {
+    const native = method('compute:', 'objc', 'Mod.m');
+    const ctx = makeContext([native]);
+    expect(
+      reactNativeBridgeResolver.resolve(ref('compute', 'objc', 'OtherMod.m'), ctx)
+    ).toBeNull();
+  });
+
+  describe('RCTEventEmitter built-ins blocklist', () => {
+    it('skips addListener / remove (every emitter exposes these — bridging them creates noise)', () => {
+      // A repo with RCTEventEmitter subclass: defines `addListener:` and
+      // `remove:` because that's what `[RCTEventEmitter addListener:]`
+      // requires. JS callers of `.addListener(...)` should NOT resolve
+      // here — they're hitting the JS-side `NativeEventEmitter`
+      // abstraction, not the native emitter directly.
+      const native1 = method('addListener:', 'objc', 'EventEmitter.m');
+      const native2 = method('remove:', 'objc', 'EventEmitter.m');
+      const ctx = makeContext([native1, native2], {
+        'package.json': '{"dependencies":{"react-native":"^0.73"}}',
+        'EventEmitter.m':
+          '@implementation EventEmitter\n' +
+          'RCT_EXPORT_MODULE()\n' +
+          'RCT_EXPORT_METHOD(addListener:(NSString *)eventName) {}\n' +
+          'RCT_EXPORT_METHOD(remove:(double)id) {}\n' +
+          '@end',
+      });
+      expect(
+        reactNativeBridgeResolver.resolve(ref('addListener', 'javascript', 'App.js'), ctx)
+      ).toBeNull();
+      expect(
+        reactNativeBridgeResolver.resolve(ref('remove', 'typescript', 'App.ts'), ctx)
+      ).toBeNull();
+    });
+  });
+});
+
+describe('React Native cross-platform pairing — end to end', () => {
+  let dir: string;
+  beforeEach(() => { dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rn-xplat-')); });
+  afterEach(() => { fs.rmSync(dir, { recursive: true, force: true }); });
+
+  it('links the Android (@ReactMethod) and iOS (RCT_EXPORT_METHOD) impls of a JS-called method', async () => {
+    fs.writeFileSync(path.join(dir, 'package.json'), '{"dependencies":{"react-native":"^0.74.0"}}');
+    fs.writeFileSync(path.join(dir, 'index.ts'),
+      "import { NativeModules } from 'react-native';\n" +
+      "export function ping() { return NativeModules.RNThing.uniquePingMethod(); }\n");
+    fs.writeFileSync(path.join(dir, 'RNThing.java'),
+      "public class RNThing extends ReactContextBaseJavaModule {\n" +
+      "  @Override public String getName() { return \"RNThing\"; }\n" +
+      "  @ReactMethod public void uniquePingMethod(Callback cb) {}\n}\n");
+    fs.writeFileSync(path.join(dir, 'RNThing.m'),
+      "@implementation RNThing\n" +
+      "RCT_EXPORT_MODULE()\n" +
+      "RCT_EXPORT_METHOD(uniquePingMethod:(RCTResponseSenderBlock)cb) {}\n@end\n");
+
+    const cg = await CodeGraph.init(dir, { silent: true });
+    await cg.indexAll();
+    const db = (cg as any).db.db;
+
+    // The iOS `RCT_EXPORT_METHOD` is extracted as an ObjC method node (the macro
+    // parses as a macro-expression, not a method, so it had no node before).
+    const objc = db.prepare(
+      "SELECT * FROM nodes WHERE name='uniquePingMethod' AND language='objc' AND id LIKE 'rn-export:%'"
+    ).all();
+    expect(objc).toHaveLength(1);
+
+    // The Java and ObjC impls of `uniquePingMethod` are linked to each other, so
+    // a JS call that resolves to one platform reaches the other.
+    const pair = db.prepare(
+      `SELECT count(*) c FROM edges e
+       JOIN nodes s ON s.id=e.source JOIN nodes t ON t.id=e.target
+       WHERE json_extract(e.metadata,'$.synthesizedBy')='rn-cross-platform'
+         AND s.name LIKE 'uniquePingMethod%' AND t.name LIKE 'uniquePingMethod%'
+         AND s.language != t.language`
+    ).get();
+    cg.close?.();
+    expect(pair.c).toBeGreaterThanOrEqual(2); // java<->objc both directions
+  });
+});
diff --git a/__tests__/resolution.test.ts b/__tests__/resolution.test.ts
index 1ca3a3f82..3059392d4 100644
--- a/__tests__/resolution.test.ts
+++ b/__tests__/resolution.test.ts
@@ -12,7 +12,8 @@ import { CodeGraph } from '../src';
 import { Node, UnresolvedReference } from '../src/types';
 import { ReferenceResolver, createResolver, ResolutionContext } from '../src/resolution';
 import { matchReference } from '../src/resolution/name-matcher';
-import { resolveImportPath, extractImportMappings } from '../src/resolution/import-resolver';
+import { resolveImportPath, extractImportMappings, resolveJvmImport, loadCppIncludeDirs, clearCppIncludeDirCache, isPhpIncludePathRef } from '../src/resolution/import-resolver';
+import type { UnresolvedRef } from '../src/resolution/types';
 import { detectFrameworks, getAllFrameworkResolvers } from '../src/resolution/frameworks';
 import { QueryBuilder } from '../src/db/queries';
 import { DatabaseConnection } from '../src/db';
@@ -353,6 +354,116 @@ from ..services import auth_service
     });
   });
 
+  describe('JVM FQN Import Resolution', () => {
+    // Build a ResolutionContext stub whose getNodesByQualifiedName answers
+    // from a fixed table — the only context method resolveJvmImport touches.
+    const makeContext = (byQName: Record<string, Node[]>): ResolutionContext => ({
+      getNodesInFile: () => [],
+      getNodesByName: () => [],
+      getNodesByQualifiedName: (q) => byQName[q] ?? [],
+      getNodesByKind: () => [],
+      fileExists: () => false,
+      readFile: () => null,
+      getProjectRoot: () => '',
+      getAllFiles: () => [],
+    });
+    const node = (id: string, name: string, qualifiedName: string, kind: Node['kind'] = 'class', language: Node['language'] = 'kotlin'): Node => ({
+      id, kind, name, qualifiedName,
+      filePath: 'Models.kt', language,
+      startLine: 1, endLine: 1, startColumn: 0, endColumn: 0,
+      updatedAt: 0,
+    });
+    const importRef = (referenceName: string, language: Node['language'] = 'kotlin'): UnresolvedRef => ({
+      fromNodeId: 'caller',
+      referenceName,
+      referenceKind: 'imports',
+      line: 1, column: 0,
+      filePath: 'Caller.kt',
+      language,
+    });
+
+    it('resolves a Kotlin class import by FQN regardless of filename', () => {
+      const target = node('n1', 'Bar', 'com.example.foo::Bar');
+      const ctx = makeContext({ 'com.example.foo::Bar': [target] });
+      const result = resolveJvmImport(importRef('com.example.foo.Bar'), ctx);
+      expect(result?.targetNodeId).toBe('n1');
+      expect(result?.resolvedBy).toBe('import');
+    });
+
+    it('resolves a Kotlin top-level function import by FQN', () => {
+      const util = node('n2', 'util', 'com.example.foo::util', 'function');
+      const ctx = makeContext({ 'com.example.foo::util': [util] });
+      const result = resolveJvmImport(importRef('com.example.foo.util'), ctx);
+      expect(result?.targetNodeId).toBe('n2');
+    });
+
+    it('resolves a Java import by FQN', () => {
+      const target = node('n3', 'Bar', 'com.example.foo::Bar', 'class', 'java');
+      const ctx = makeContext({ 'com.example.foo::Bar': [target] });
+      const result = resolveJvmImport(importRef('com.example.foo.Bar', 'java'), ctx);
+      expect(result?.targetNodeId).toBe('n3');
+    });
+
+    it('resolves cross-language: Kotlin importing a Java class', () => {
+      // The Kotlin file declares `import com.example.JavaBar` — the target is
+      // a Java class node. JVM interop means the resolver doesn't care about
+      // the source language of the target, only that the FQN matches.
+      const target = node('n4', 'JavaBar', 'com.example::JavaBar', 'class', 'java');
+      const ctx = makeContext({ 'com.example::JavaBar': [target] });
+      const result = resolveJvmImport(importRef('com.example.JavaBar'), ctx);
+      expect(result?.targetNodeId).toBe('n4');
+    });
+
+    it('disambiguates a name collision across packages', () => {
+      // Two classes named `Bar` in different packages. Each import resolves
+      // to the one whose FQN matches — not to "whichever was found first".
+      const barA = node('n5a', 'Bar', 'com.example.alpha::Bar');
+      const barB = node('n5b', 'Bar', 'com.example.beta::Bar');
+      const ctx = makeContext({
+        'com.example.alpha::Bar': [barA],
+        'com.example.beta::Bar': [barB],
+      });
+      expect(resolveJvmImport(importRef('com.example.alpha.Bar'), ctx)?.targetNodeId).toBe('n5a');
+      expect(resolveJvmImport(importRef('com.example.beta.Bar'), ctx)?.targetNodeId).toBe('n5b');
+    });
+
+    it('returns null for wildcard imports', () => {
+      const ctx = makeContext({});
+      expect(resolveJvmImport(importRef('com.example.foo.*'), ctx)).toBeNull();
+    });
+
+    it('returns null for unqualified names', () => {
+      // A single-segment name has no package; nothing to look up by FQN.
+      const ctx = makeContext({ 'Bar': [node('n6', 'Bar', 'Bar')] });
+      expect(resolveJvmImport(importRef('Bar'), ctx)).toBeNull();
+    });
+
+    it('returns null for non-JVM languages', () => {
+      const target = node('n7', 'Bar', 'com.example::Bar');
+      const ctx = makeContext({ 'com.example::Bar': [target] });
+      expect(resolveJvmImport(importRef('com.example.Bar', 'typescript'), ctx)).toBeNull();
+    });
+
+    it('returns null for non-imports reference kinds', () => {
+      // The resolver intentionally only acts on `imports` refs; ordinary
+      // `calls`/`extends` refs fall through to the framework + name-matcher
+      // strategies.
+      const target = node('n8', 'Bar', 'com.example::Bar');
+      const ctx = makeContext({ 'com.example::Bar': [target] });
+      const ref: UnresolvedRef = {
+        fromNodeId: 'caller', referenceName: 'com.example.Bar',
+        referenceKind: 'calls', line: 1, column: 0,
+        filePath: 'Caller.kt', language: 'kotlin',
+      };
+      expect(resolveJvmImport(ref, ctx)).toBeNull();
+    });
+
+    it('returns null when the FQN is not in the index', () => {
+      const ctx = makeContext({});
+      expect(resolveJvmImport(importRef('com.example.Unknown'), ctx)).toBeNull();
+    });
+  });
+
   describe('Framework Detection', () => {
     it('should detect React framework', () => {
       const context: ResolutionContext = {
@@ -470,12 +581,23 @@ from ..services import auth_service
         line: 10,
         column: 5,
         filePath: 'src/App.tsx',
-        language: 'typescript' as const,
+        // Refs extracted from .tsx files carry language 'tsx' — component
+        // resolution is gated to JSX-capable refs (#764: PascalCase TYPE refs
+        // from plain .ts files were resolving to arbitrary same-named classes).
+        language: 'tsx' as const,
       };
 
       const result = reactResolver!.resolve(ref, context);
       expect(result).not.toBeNull();
       expect(result?.targetNodeId).toBe('component:src/Button.tsx:Button:5');
+
+      // The same PascalCase name referenced from a plain .ts file is a TYPE
+      // reference, not a component usage — component resolution must decline
+      // and leave it to proximity-aware name matching (#764: a .ts GraphQL
+      // types file's own `Account` alias was losing to an arbitrary same-named
+      // class in another monorepo package).
+      const tsRef = { ...ref, filePath: 'src/models.ts', language: 'typescript' as const };
+      expect(reactResolver!.resolve(tsRef, context)).toBeNull();
     });
 
     it('should resolve custom hook references', () => {
@@ -645,6 +767,441 @@ def bootstrap():
       );
       expect(callsToUserService).toHaveLength(0);
     });
+
+    it('resolves Go cross-package qualified calls via go.mod module path (#388)', async () => {
+      // Pre-#388, every `pkga.FuncX(...)` call in a Go monorepo was flagged
+      // external (isExternalImport returned true for any non-`/internal/`
+      // import without `.`-prefix) and resolution fell through to name-match
+      // with path proximity — recall on cross-package callers was ~<1%.
+      fs.writeFileSync(
+        path.join(tempDir, 'go.mod'),
+        'module github.com/example/myproject\n\ngo 1.21\n'
+      );
+
+      const pkgaDir = path.join(tempDir, 'pkga');
+      const pkgbDir = path.join(tempDir, 'pkgb');
+      const pkgcDir = path.join(tempDir, 'pkgc');
+      fs.mkdirSync(pkgaDir);
+      fs.mkdirSync(pkgbDir);
+      fs.mkdirSync(pkgcDir);
+
+      // Same-name exported function in two packages — only the imported one
+      // should resolve. Exercises disambiguation, not just connectivity.
+      fs.writeFileSync(
+        path.join(pkgaDir, 'conv.go'),
+        'package pkga\nfunc Convert(x int) int { return x * 2 }\n'
+      );
+      fs.writeFileSync(
+        path.join(pkgbDir, 'conv.go'),
+        'package pkgb\nfunc Convert(x int) int { return x + 1 }\n'
+      );
+      fs.writeFileSync(
+        path.join(pkgcDir, 'use.go'),
+        `package pkgc
+
+import "github.com/example/myproject/pkga"
+
+func UsePkga() {
+  pkga.Convert(5)
+}
+`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+
+      const usePkga = cg.getNodesByKind('function').filter((n) => n.name ==='UsePkga')[0];
+      expect(usePkga).toBeDefined();
+
+      const outgoing = cg.getOutgoingEdges(usePkga!.id);
+      const callEdges = outgoing.filter((e) => e.kind === 'calls');
+      expect(callEdges).toHaveLength(1);
+
+      const target = cg.getNode(callEdges[0]!.target);
+      expect(target?.name).toBe('Convert');
+      // Critical: the resolver must pick the imported pkga's Convert,
+      // not pkgb's. With the broken (pre-fix) resolver this lands on
+      // whichever Convert happens to be cheaper under path proximity.
+      expect(target?.filePath.replace(/\\/g, '/')).toBe('pkga/conv.go');
+    });
+
+    it('resolves Go aliased imports across packages (#388)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'go.mod'),
+        'module github.com/example/myproject\n\ngo 1.21\n'
+      );
+      fs.mkdirSync(path.join(tempDir, 'pkgb'));
+      fs.mkdirSync(path.join(tempDir, 'pkgd'));
+
+      fs.writeFileSync(
+        path.join(tempDir, 'pkgb', 'lib.go'),
+        'package pkgb\nfunc Compute(x int) int { return x }\n'
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'pkgd', 'use.go'),
+        `package pkgd
+
+import (
+  "fmt"
+  alias "github.com/example/myproject/pkgb"
+)
+
+func UseAliased() {
+  fmt.Println("hi")
+  alias.Compute(3)
+}
+`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+
+      const useAliased = cg.getNodesByKind('function').filter((n) => n.name ==='UseAliased')[0];
+      expect(useAliased).toBeDefined();
+      const calls = cg.getOutgoingEdges(useAliased!.id).filter((e) => e.kind === 'calls');
+      // fmt.Println is stdlib — must stay external. alias.Compute must resolve.
+      expect(calls).toHaveLength(1);
+      const target = cg.getNode(calls[0]!.target);
+      expect(target?.name).toBe('Compute');
+      expect(target?.filePath.replace(/\\/g, '/')).toBe('pkgb/lib.go');
+    });
+
+    it('resolves Python module-attribute calls after `from pkg import module` (#578)', async () => {
+      // Pre-#578, a `module.func()` call where `module` was bound via
+      // `from pkg import module` dropped its `calls` edge. The file→file import
+      // edge resolved (resolveModuleImportToFile falls back to a dotted-module
+      // file lookup for absolute package paths), but resolvePythonModuleMember
+      // had no such fallback — resolveImportPath returns null for an absolute
+      // package path like `pkg.module`, so the member never resolved and
+      // callers/callees/impact on the target came back empty. Same root-cause
+      // class as the Go cross-package qualified call (#388).
+      fs.mkdirSync(path.join(tempDir, 'pkg'));
+      fs.writeFileSync(path.join(tempDir, 'pkg', '__init__.py'), '');
+      fs.writeFileSync(
+        path.join(tempDir, 'pkg', 'module.py'),
+        'def func():\n    return 1\n'
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'main.py'),
+        `from pkg import module
+import os
+
+
+def caller():
+    return module.func()
+
+
+def external_caller():
+    return os.getcwd()
+`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+
+      const caller = cg.getNodesByKind('function').filter((n) => n.name === 'caller')[0];
+      expect(caller).toBeDefined();
+      const calls = cg.getOutgoingEdges(caller!.id).filter((e) => e.kind === 'calls');
+      // module.func() must resolve to the real function in the submodule file.
+      expect(calls).toHaveLength(1);
+      const target = cg.getNode(calls[0]!.target);
+      expect(target?.name).toBe('func');
+      expect(target?.filePath.replace(/\\/g, '/')).toBe('pkg/module.py');
+
+      // The flip side of the fix: an attribute call through a *stdlib* module
+      // (`os.getcwd()`) must still create no edge — the fallback only matches
+      // real in-repo module files.
+      const externalCaller = cg.getNodesByKind('function').filter((n) => n.name === 'external_caller')[0];
+      expect(externalCaller).toBeDefined();
+      const externalCalls = cg.getOutgoingEdges(externalCaller!.id).filter((e) => e.kind === 'calls');
+      expect(externalCalls).toHaveLength(0);
+    });
+
+    it('attaches Go methods to their receiver type across files (#583, cross-file half)', async () => {
+      // In Go a type's methods are commonly declared in a different file from the
+      // `type` declaration (`type Box` in box.go, `func (b *Box) Get()` in
+      // box_methods.go). Extraction only attaches the struct→method `contains`
+      // edge when the type is in the SAME file (the owner lookup is file-scoped),
+      // so a cross-file method was orphaned from its struct — breaking member
+      // outlines and any callers/callees/impact traversal through `contains`. A
+      // resolution-phase pass now links them within the package (= directory).
+      fs.writeFileSync(
+        path.join(tempDir, 'box.go'),
+        'package main\n\ntype Box struct{ v int }\n'
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'box_methods.go'),
+        'package main\n\nfunc (b *Box) Get() int { return b.v }\nfunc (b *Box) Set(x int) { b.v = x }\n'
+      );
+      // Generic receiver declared cross-file too — exercises #583 half A
+      // (generic `*Stack[T]` receiver parsing) and half B (cross-file) together.
+      fs.writeFileSync(
+        path.join(tempDir, 'stack.go'),
+        'package main\n\ntype Stack[T any] struct {\n\titems []T\n}\n'
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'stack_push.go'),
+        'package main\n\nfunc (s *Stack[T]) Push(v T) { s.items = append(s.items, v) }\n'
+      );
+      // A same-named type in another package must NOT capture this package's
+      // methods — the link is scoped to the receiver type's own directory.
+      fs.mkdirSync(path.join(tempDir, 'other'));
+      fs.writeFileSync(
+        path.join(tempDir, 'other', 'box.go'),
+        'package other\n\ntype Box struct{ w int }\n'
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+
+      const methodsOf = (typeName: string, file: string): string[] => {
+        const node = cg
+          .getNodesByKind('struct')
+          .find((n) => n.name === typeName && n.filePath.replace(/\\/g, '/') === file);
+        expect(node, `${typeName} @ ${file}`).toBeDefined();
+        return cg
+          .getOutgoingEdges(node!.id)
+          .filter((e) => e.kind === 'contains')
+          .map((e) => cg.getNode(e.target))
+          .filter((n) => !!n && n.kind === 'method')
+          .map((n) => n!.name)
+          .sort();
+      };
+
+      // Cross-file (non-generic) methods now attach to their struct.
+      expect(methodsOf('Box', 'box.go')).toEqual(['Get', 'Set']);
+      // Generic + cross-file.
+      expect(methodsOf('Stack', 'stack.go')).toEqual(['Push']);
+      // Cross-package isolation: other/Box defines no methods of its own.
+      expect(methodsOf('Box', 'other/box.go')).toEqual([]);
+    });
+
+    it('TS type_alias object-shape members resolve method calls (#359)', async () => {
+      // Pre-#359, `recorder.stop()` (recorder: RecorderHandle) attached
+      // to `StdioMcpClient.stop` in a sibling directory via path-proximity
+      // because the type_alias had no `stop` node — only the unrelated
+      // class did. Now type_alias produces member nodes (property/method),
+      // so the camelCase receiver↔type word overlap pulls the call to
+      // `RecorderHandle::stop` instead of the look-alike class.
+      fs.mkdirSync(path.join(tempDir, 'voice'));
+      fs.mkdirSync(path.join(tempDir, 'codegraph'));
+
+      fs.writeFileSync(
+        path.join(tempDir, 'voice', 'recorder.ts'),
+        `export type RecorderHandle = {
+  wavPath: string;
+  stop: () => Promise<{ ok: true }>;
+};
+`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'voice', 'controller.ts'),
+        `import type { RecorderHandle } from "./recorder";
+export async function finaliseRecording(recorder: RecorderHandle) {
+  return await recorder.stop();
+}
+`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'codegraph', 'stdio-client.ts'),
+        `export class StdioMcpClient {
+  private stopped = false;
+  async stop(): Promise<void> { this.stopped = true; }
+}
+`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+
+      const handleStop = cg
+        .getNodesByKind('method')
+        .find((n) => n.qualifiedName === 'RecorderHandle::stop');
+      expect(handleStop).toBeDefined();
+
+      const clientStop = cg
+        .getNodesByKind('method')
+        .find((n) => n.qualifiedName === 'StdioMcpClient::stop');
+      expect(clientStop).toBeDefined();
+
+      const handleCallers = cg.getIncomingEdges(handleStop!.id).filter((e) => e.kind === 'calls');
+      const clientCallers = cg.getIncomingEdges(clientStop!.id).filter((e) => e.kind === 'calls');
+      expect(handleCallers.length).toBeGreaterThanOrEqual(1);
+      // The class method must have NO callers — voice/'s call must NOT
+      // mis-attribute. A non-empty list would mean the false-positive
+      // path is still firing.
+      expect(clientCallers).toHaveLength(0);
+
+      // Function-typed property surfaces as a `method` node, not `property`,
+      // because `stop()` semantics at the call site are method semantics.
+      expect(handleStop!.kind).toBe('method');
+    });
+
+    it('Java import disambiguates same-name classes across modules (#314)', async () => {
+      // Pre-#314 the import resolver had no Java branch at all, so a
+      // multi-module Maven repo where `dao/converter/FooConverter` and
+      // `service/converter/FooConverter` both export a `convert` method
+      // resolved by file-path proximity — picking whichever class was
+      // closer to the caller, which is wrong any time the caller lives
+      // in an equidistant cross-cutting module.
+      const daoDir = path.join(tempDir, 'dao/src/main/java/com/example/dao/converter');
+      const serviceDir = path.join(tempDir, 'service/src/main/java/com/example/service/converter');
+      const webDir = path.join(tempDir, 'web/src/main/java/com/example/web');
+      fs.mkdirSync(daoDir, { recursive: true });
+      fs.mkdirSync(serviceDir, { recursive: true });
+      fs.mkdirSync(webDir, { recursive: true });
+
+      fs.writeFileSync(
+        path.join(daoDir, 'FooConverter.java'),
+        `package com.example.dao.converter;
+public class FooConverter { public String convert(String x) { return "dao:" + x; } }
+`
+      );
+      fs.writeFileSync(
+        path.join(serviceDir, 'FooConverter.java'),
+        `package com.example.service.converter;
+public class FooConverter { public String convert(String x) { return "svc:" + x; } }
+`
+      );
+      // The caller imports the SERVICE version — even though dao is
+      // alphabetically/lexically first in the candidate list, the
+      // import must trump that order.
+      fs.writeFileSync(
+        path.join(webDir, 'Handler.java'),
+        `package com.example.web;
+
+import com.example.service.converter.FooConverter;
+
+public class Handler {
+  private FooConverter fooConverter;
+  public String use() { return fooConverter.convert("input"); }
+}
+`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+
+      const use = cg
+        .getNodesByKind('method')
+        .find((n) => n.qualifiedName === 'com.example.web::Handler::use');
+      expect(use).toBeDefined();
+      const calls = cg.getOutgoingEdges(use!.id).filter((e) => e.kind === 'calls');
+      expect(calls.length).toBeGreaterThanOrEqual(1);
+
+      const target = cg.getNode(calls[0]!.target);
+      expect(target?.name).toBe('convert');
+      expect(target?.filePath.replace(/\\/g, '/')).toBe(
+        'service/src/main/java/com/example/service/converter/FooConverter.java'
+      );
+    });
+
+    it('C# extracts references from method/property/field types (#381)', async () => {
+      // Pre-#381, every C# project produced ZERO `references` edges:
+      // csharp.ts was missing returnField, and the type-leaf walker
+      // only recognized TS/Java's `type_identifier` nodes — C# uses
+      // `identifier`/`predefined_type`/`qualified_name`/`generic_name`.
+      const srcDir = path.join(tempDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+
+      fs.writeFileSync(
+        path.join(srcDir, 'Dtos.cs'),
+        `namespace MyApp;
+public class SessionInfoDto { public string Id { get; set; } = ""; }
+public class UserDto { public string Name { get; set; } = ""; }
+`
+      );
+      fs.writeFileSync(
+        path.join(srcDir, 'Service.cs'),
+        `using System.Threading.Tasks;
+namespace MyApp;
+public class DataExporter
+{
+  public SessionInfoDto Build(UserDto user, SessionInfoDto session) { return session; }
+  public Task<SessionInfoDto> BuildAsync(UserDto user) { return Task.FromResult(new SessionInfoDto()); }
+  public SessionInfoDto Latest { get; set; } = new();
+  private UserDto _cached;
+}
+`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+
+      const sessionDto = cg
+        .getNodesByKind('class')
+        .find((n) => n.name === 'SessionInfoDto');
+      const userDto = cg
+        .getNodesByKind('class')
+        .find((n) => n.name === 'UserDto');
+      expect(sessionDto).toBeDefined();
+      expect(userDto).toBeDefined();
+
+      const sessionIncoming = cg
+        .getIncomingEdges(sessionDto!.id)
+        .filter((e) => e.kind === 'references');
+      const userIncoming = cg
+        .getIncomingEdges(userDto!.id)
+        .filter((e) => e.kind === 'references');
+
+      // SessionInfoDto: Build return, Build param, BuildAsync return (inside Task<>), Latest property.
+      // UserDto: Build param, BuildAsync param, _cached field.
+      expect(sessionIncoming.length).toBeGreaterThanOrEqual(4);
+      expect(userIncoming.length).toBeGreaterThanOrEqual(3);
+    });
+
+    it('C# primary-constructor parameters record their type dependencies (#237)', async () => {
+      // C# 12 primary constructors declare a type's injected dependencies inline
+      // (`class Svc(IRepo repo, [FromKeyedServices("k")] ICache cache)`). Each
+      // ctor parameter's type is recorded as a `references` edge from the class,
+      // so a DI-registered contract reached only through a primary ctor is no
+      // longer reported as having no dependents.
+      fs.mkdirSync(path.join(tempDir, 'src'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tempDir, 'src', 'Contracts.cs'),
+        `namespace App;
+public interface IRepo { }
+public class ICache { }
+`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'src', 'OrderService.cs'),
+        `namespace App;
+public sealed class OrderService(IRepo repo, [FromKeyedServices("primary")] ICache cache)
+{
+  public void Run() { }
+}
+`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+
+      const svc = cg.getNodesByKind('class').find((n) => n.name === 'OrderService');
+      expect(svc).toBeDefined();
+      // The class itself must index (it used to vanish under the old grammar).
+      const out = cg.getOutgoingEdges(svc!.id).filter((e) => e.kind === 'references');
+      const depNames = out.map((e) => cg.getNode(e.target)?.name);
+      expect(depNames).toContain('IRepo');
+      expect(depNames).toContain('ICache'); // the keyed-DI ([FromKeyedServices]) dependency
+    });
+
+    it('Go: leaves stdlib calls (fmt.Println, etc.) external', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'go.mod'),
+        'module github.com/example/myproject\n\ngo 1.21\n'
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'main.go'),
+        `package main
+
+import "fmt"
+
+func main() {
+  fmt.Println("hi")
+}
+`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+
+      const mainFn = cg.getNodesByKind('function').filter((n) => n.name ==='main')[0];
+      const calls = cg.getOutgoingEdges(mainFn!.id).filter((e) => e.kind === 'calls');
+      // No spurious in-project edge — fmt.* must stay unresolved/external.
+      expect(calls).toHaveLength(0);
+    });
   });
 
   describe('Name Matcher: kind bias for new ref kinds', () => {
@@ -845,5 +1402,2032 @@ def bootstrap():
       const callers = cg.getCallers(signInNode!.id);
       expect(callers.some((c) => c.node.filePath === 'src/main.ts')).toBe(true);
     });
+
+    it('follows a default re-export of a .svelte component (export { default as Foo } from ./RealButton.svelte) (#629)', async () => {
+      // The ubiquitous Svelte/React component-barrel form. The leaf is a
+      // .svelte component (extracted as kind 'component', the default
+      // export). The re-export ALIAS (`Foo`) deliberately differs from the
+      // component's real name (`RealButton`) so the name-matcher fallback
+      // can't coincidentally connect them — the only path to the edge is
+      // the import-chase, which must match a `component` (not just
+      // function/class) for the default export. Otherwise the
+      // consumer↔component edge is never created and `callers` returns a
+      // false 0.
+      fs.mkdirSync(path.join(tempDir, 'src/lib'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tempDir, 'src/lib/RealButton.svelte'),
+        `<script lang="ts">\n  export let label: string = '';\n</script>\n\n<button>{label}</button>\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'src/lib/index.ts'),
+        `export { default as Foo } from './RealButton.svelte';\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'src/Bar.svelte'),
+        `<script lang="ts">\n  import { Foo } from './lib';\n</script>\n\n<Foo />\n`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+      cg.resolveReferences();
+
+      const fooNode = cg
+        .getNodesByKind('component')
+        .find((n) => n.name === 'RealButton' && n.filePath === 'src/lib/RealButton.svelte');
+      expect(fooNode).toBeDefined();
+      const callers = cg.getCallers(fooNode!.id);
+      expect(callers.some((c) => c.node.filePath === 'src/Bar.svelte')).toBe(true);
+    });
+
+    it('links an .astro page to the component and TS util it uses (#768)', async () => {
+      // The canonical Astro shape: a page imports a layout/component in
+      // frontmatter and uses it as a template tag; the component's template
+      // calls an imported .ts util. Both hops must produce graph edges or
+      // an Astro project is invisible to callers/impact.
+      fs.mkdirSync(path.join(tempDir, 'src/components'), { recursive: true });
+      fs.mkdirSync(path.join(tempDir, 'src/utils'), { recursive: true });
+      fs.mkdirSync(path.join(tempDir, 'src/pages'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tempDir, 'src/utils/format.ts'),
+        `export function formatDate(d: Date): string { return d.toISOString(); }\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'src/components/PostCard.astro'),
+        `---\nimport { formatDate } from '../utils/format';\nconst { date } = Astro.props;\n---\n<time>{formatDate(date)}</time>\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'src/pages/index.astro'),
+        `---\nimport PostCard from '../components/PostCard.astro';\n---\n<PostCard date={new Date()} />\n`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+      cg.resolveReferences();
+
+      // Hop 1: page → component (template tag through the frontmatter import)
+      const cardNode = cg
+        .getNodesByKind('component')
+        .find((n) => n.name === 'PostCard' && n.filePath === 'src/components/PostCard.astro');
+      expect(cardNode).toBeDefined();
+      const cardCallers = cg.getCallers(cardNode!.id);
+      expect(cardCallers.some((c) => c.node.filePath === 'src/pages/index.astro')).toBe(true);
+
+      // Hop 2: component template call → .ts util
+      const fmtNode = cg
+        .getNodesByKind('function')
+        .find((n) => n.name === 'formatDate' && n.filePath === 'src/utils/format.ts');
+      expect(fmtNode).toBeDefined();
+      const fmtCallers = cg.getCallers(fmtNode!.id);
+      expect(fmtCallers.some((c) => c.node.filePath === 'src/components/PostCard.astro')).toBe(true);
+    });
+
+    it('resolves a bare directory import (import { x } from "." / "./") to index.ts (#629)', async () => {
+      // `import { helper } from '.'` (or './') must map to the
+      // directory's index.ts before the re-export chase can run. The
+      // barrel renames `realHelper` → `helper` so the name-matcher can't
+      // mask a path-resolution failure: only the bare-dir resolution +
+      // rename chase can connect the edge.
+      fs.mkdirSync(path.join(tempDir, 'src'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tempDir, 'src/util.ts'),
+        `export function realHelper(): void {}\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'src/index.ts'),
+        `export { realHelper as helper } from './util';\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'src/main.ts'),
+        `import { helper } from '.';\nexport function go(): void { helper(); }\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'src/main2.ts'),
+        `import { helper } from './';\nexport function go2(): void { helper(); }\n`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+      cg.resolveReferences();
+
+      const helperNode = cg
+        .getNodesByKind('function')
+        .find((n) => n.name === 'realHelper' && n.filePath === 'src/util.ts');
+      expect(helperNode).toBeDefined();
+      const callers = cg.getCallers(helperNode!.id);
+      expect(callers.some((c) => c.node.filePath === 'src/main.ts')).toBe(true);
+      expect(callers.some((c) => c.node.filePath === 'src/main2.ts')).toBe(true);
+    });
+
+    it('resolves a workspace package-subpath barrel (@scope/pkg/sub) to its index (#629)', async () => {
+      // bun/npm/pnpm workspace: `@scope/ui/widgets` → the `ui` package's
+      // `widgets/` subdir index, which re-exports a .svelte component.
+      // Alias `Thing` ≠ component `Widget` defeats the name-matcher, so
+      // only workspace-package resolution can connect the edge.
+      fs.mkdirSync(path.join(tempDir, 'packages/ui/widgets'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tempDir, 'package.json'),
+        JSON.stringify({ name: 'root', private: true, workspaces: ['packages/*'] }, null, 2)
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'packages/ui/package.json'),
+        JSON.stringify({ name: '@scope/ui', version: '1.0.0' }, null, 2)
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'packages/ui/widgets/Widget.svelte'),
+        `<script lang="ts">\n  export let label: string = '';\n</script>\n\n<button>{label}</button>\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'packages/ui/widgets/index.ts'),
+        `export { default as Thing } from './Widget.svelte';\n`
+      );
+      fs.mkdirSync(path.join(tempDir, 'app'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tempDir, 'app/App.svelte'),
+        `<script lang="ts">\n  import { Thing } from '@scope/ui/widgets';\n</script>\n\n<Thing />\n`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+      cg.resolveReferences();
+
+      const buttonNode = cg
+        .getNodesByKind('component')
+        .find((n) => n.name === 'Widget' && n.filePath === 'packages/ui/widgets/Widget.svelte');
+      expect(buttonNode).toBeDefined();
+      const callers = cg.getCallers(buttonNode!.id);
+      expect(callers.some((c) => c.node.filePath === 'app/App.svelte')).toBe(true);
+    });
+
+    it('resolves a barrel import from a Vue SFC <script> block (#629)', async () => {
+      // The same import-resolution gaps (no SFC import mappings, no SFC
+      // extension list, barrel parsed in the consumer's language) broke
+      // Vue SFCs too. Guards the resolver-side generalization to `.vue`.
+      // The barrel renames `realRun` → `run` so only the import-chase (not
+      // the name-matcher) can connect the call.
+      fs.mkdirSync(path.join(tempDir, 'src'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tempDir, 'src/util.ts'),
+        `export function realRun(): void {}\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'src/index.ts'),
+        `export { realRun as run } from './util';\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'src/App.vue'),
+        `<script lang="ts">\nimport { run } from './';\nexport default { mounted() { run(); } };\n</script>\n<template><div/></template>\n`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+      cg.resolveReferences();
+
+      const runNode = cg
+        .getNodesByKind('function')
+        .find((n) => n.name === 'realRun' && n.filePath === 'src/util.ts');
+      expect(runNode).toBeDefined();
+      const callers = cg.getCallers(runNode!.id);
+      expect(callers.some((c) => c.node.filePath === 'src/App.vue')).toBe(true);
+    });
+
+    it('follows a Vue component used in a <template> through a default re-export barrel (#629)', async () => {
+      // End-to-end Vue analogue of the Svelte case: the leaf is a `.vue`
+      // component re-exported under an alias (`Thing`) that differs from its
+      // real name (`Widget`), and the consumer uses it ONLY in markup
+      // (`<Thing />`). Requires both the new template-tag extraction AND the
+      // barrel default-export chase to connect the edge.
+      fs.mkdirSync(path.join(tempDir, 'src/lib'), { recursive: true });
+      fs.writeFileSync(
+        path.join(tempDir, 'src/lib/Widget.vue'),
+        `<script setup lang="ts">\ndefineProps<{ label?: string }>();\n</script>\n<template><button>x</button></template>\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'src/lib/index.ts'),
+        `export { default as Thing } from './Widget.vue';\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'src/App.vue'),
+        `<script setup lang="ts">\nimport { Thing } from './lib';\n</script>\n<template>\n  <Thing />\n</template>\n`
+      );
+
+      cg = await CodeGraph.init(tempDir, { index: true });
+      cg.resolveReferences();
+
+      const widgetNode = cg
+        .getNodesByKind('component')
+        .find((n) => n.name === 'Widget' && n.filePath === 'src/lib/Widget.vue');
+      expect(widgetNode).toBeDefined();
+      const callers = cg.getCallers(widgetNode!.id);
+      expect(callers.some((c) => c.node.filePath === 'src/App.vue')).toBe(true);
+    });
+  });
+
+  describe('C/C++ Import Resolution', () => {
+    afterEach(() => {
+      clearCppIncludeDirCache();
+    });
+
+    it('should resolve C include to header in same directory', () => {
+      const context: ResolutionContext = {
+        getNodesInFile: () => [],
+        getNodesByName: () => [],
+        getNodesByQualifiedName: () => [],
+        getNodesByKind: () => [],
+        fileExists: (p) => p === 'utils.h',
+        readFile: () => null,
+        getProjectRoot: () => '',
+        getAllFiles: () => ['utils.h', 'main.c'],
+      };
+
+      const result = resolveImportPath(
+        'utils.h',
+        'main.c',
+        'c',
+        context
+      );
+
+      expect(result).toBe('utils.h');
+    });
+
+    it('should resolve C++ include with .hpp extension', () => {
+      const context: ResolutionContext = {
+        getNodesInFile: () => [],
+        getNodesByName: () => [],
+        getNodesByQualifiedName: () => [],
+        getNodesByKind: () => [],
+        fileExists: (p) => p === 'include/myclass.hpp',
+        readFile: () => null,
+        getProjectRoot: () => '',
+        getAllFiles: () => ['include/myclass.hpp', 'src/main.cpp'],
+        getCppIncludeDirs: () => ['include'],
+      };
+
+      const result = resolveImportPath(
+        'myclass.hpp',
+        'src/main.cpp',
+        'cpp',
+        context
+      );
+
+      expect(result).toBe('include/myclass.hpp');
+    });
+
+    it('should resolve include with subdirectory path', () => {
+      const context: ResolutionContext = {
+        getNodesInFile: () => [],
+        getNodesByName: () => [],
+        getNodesByQualifiedName: () => [],
+        getNodesByKind: () => [],
+        fileExists: (p) => p === 'utils/helpers.h',
+        readFile: () => null,
+        getProjectRoot: () => '',
+        getAllFiles: () => ['utils/helpers.h', 'main.c'],
+      };
+
+      const result = resolveImportPath(
+        'utils/helpers.h',
+        'main.c',
+        'c',
+        context
+      );
+
+      expect(result).toBe('utils/helpers.h');
+    });
+
+    it('should resolve include via include directories', () => {
+      const context: ResolutionContext = {
+        getNodesInFile: () => [],
+        getNodesByName: () => [],
+        getNodesByQualifiedName: () => [],
+        getNodesByKind: () => [],
+        fileExists: (p) => p === 'include/myheader.h',
+        readFile: () => null,
+        getProjectRoot: () => '',
+        getAllFiles: () => ['include/myheader.h', 'src/main.cpp'],
+        getCppIncludeDirs: () => ['include'],
+      };
+
+      const result = resolveImportPath(
+        'myheader.h',
+        'src/main.cpp',
+        'cpp',
+        context
+      );
+
+      expect(result).toBe('include/myheader.h');
+    });
+
+    it('should resolve include trying multiple extensions', () => {
+      const context: ResolutionContext = {
+        getNodesInFile: () => [],
+        getNodesByName: () => [],
+        getNodesByQualifiedName: () => [],
+        getNodesByKind: () => [],
+        // myclass.h does not exist, but myclass.hpp does
+        fileExists: (p) => p === 'include/myclass.hpp',
+        readFile: () => null,
+        getProjectRoot: () => '',
+        getAllFiles: () => ['include/myclass.hpp', 'src/main.cpp'],
+        getCppIncludeDirs: () => ['include'],
+      };
+
+      const result = resolveImportPath(
+        'myclass',
+        'src/main.cpp',
+        'cpp',
+        context
+      );
+
+      expect(result).toBe('include/myclass.hpp');
+    });
+
+    it('should return null for system headers', () => {
+      const context: ResolutionContext = {
+        getNodesInFile: () => [],
+        getNodesByName: () => [],
+        getNodesByQualifiedName: () => [],
+        getNodesByKind: () => [],
+        fileExists: () => true,
+        readFile: () => null,
+        getProjectRoot: () => '',
+        getAllFiles: () => [],
+      };
+
+      // C standard library header
+      expect(resolveImportPath('stdio.h', 'main.c', 'c', context)).toBeNull();
+      // C++ standard library header
+      expect(resolveImportPath('vector', 'main.cpp', 'cpp', context)).toBeNull();
+      // C++ C-wrapper header
+      expect(resolveImportPath('cstdio', 'main.cpp', 'cpp', context)).toBeNull();
+    });
+
+    it('should return null for single-component third-party paths that cannot be resolved', () => {
+      const context: ResolutionContext = {
+        getNodesInFile: () => [],
+        getNodesByName: () => [],
+        getNodesByQualifiedName: () => [],
+        getNodesByKind: () => [],
+        fileExists: () => false,
+        readFile: () => null,
+        getProjectRoot: () => '',
+        getAllFiles: () => [],
+        getCppIncludeDirs: () => [],
+      };
+
+      // Third-party bare header without path — not resolvable, returns null
+      const result = resolveImportPath(
+        'openssl/ssl.h',
+        'main.cpp',
+        'cpp',
+        context
+      );
+
+      expect(result).toBeNull();
+    });
+
+    it('should not filter project headers with path separators', () => {
+      const context: ResolutionContext = {
+        getNodesInFile: () => [],
+        getNodesByName: () => [],
+        getNodesByQualifiedName: () => [],
+        getNodesByKind: () => [],
+        fileExists: (p) => p === 'mylib/utils.h',
+        readFile: () => null,
+        getProjectRoot: () => '',
+        getAllFiles: () => ['mylib/utils.h'],
+      };
+
+      // Path with separator should NOT be filtered as external
+      const result = resolveImportPath(
+        'mylib/utils.h',
+        'main.c',
+        'c',
+        context
+      );
+
+      expect(result).toBe('mylib/utils.h');
+    });
+
+    it('should extract C/C++ import mappings from #include directives', () => {
+      const code = `#include <iostream>
+#include "myheader.h"
+#include "utils/helpers.hpp"`;
+
+      const mappings = extractImportMappings('main.cpp', code, 'cpp');
+
+      expect(mappings.length).toBe(3);
+      expect(mappings[0]).toEqual({
+        localName: 'iostream',
+        exportedName: '*',
+        source: 'iostream',
+        isDefault: false,
+        isNamespace: true,
+      });
+      expect(mappings[1]).toEqual({
+        localName: 'myheader',
+        exportedName: '*',
+        source: 'myheader.h',
+        isDefault: false,
+        isNamespace: true,
+      });
+      expect(mappings[2]).toEqual({
+        localName: 'helpers',
+        exportedName: '*',
+        source: 'utils/helpers.hpp',
+        isDefault: false,
+        isNamespace: true,
+      });
+    });
+
+    it('should discover include directories from compile_commands.json', () => {
+      // Create a temp project with compile_commands.json
+      const tempProject = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-cpp-test-'));
+      try {
+        const compileDb = [
+          {
+            directory: tempProject,
+            command: 'g++ -Iinclude -Isrc/lib -isystem /usr/include -c src/main.cpp',
+            file: 'src/main.cpp',
+          },
+        ];
+        fs.writeFileSync(
+          path.join(tempProject, 'compile_commands.json'),
+          JSON.stringify(compileDb)
+        );
+        // Create the include dirs so they exist
+        fs.mkdirSync(path.join(tempProject, 'include'), { recursive: true });
+        fs.mkdirSync(path.join(tempProject, 'src', 'lib'), { recursive: true });
+
+        clearCppIncludeDirCache();
+        const dirs = loadCppIncludeDirs(tempProject);
+
+        // Should find include and src/lib (relative to project root)
+        // /usr/include is absolute and outside project, should be excluded
+        expect(dirs).toContain('include');
+        expect(dirs).toContain('src/lib');
+        expect(dirs.some(d => d.includes('usr'))).toBe(false);
+      } finally {
+        fs.rmSync(tempProject, { recursive: true });
+      }
+    });
+
+    it('should fall back to heuristic include dirs when no compile_commands.json', () => {
+      const tempProject = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-cpp-test-'));
+      try {
+        // Create include/ and src/ directories with headers
+        fs.mkdirSync(path.join(tempProject, 'include'), { recursive: true });
+        fs.writeFileSync(path.join(tempProject, 'include', 'types.h'), '');
+        fs.mkdirSync(path.join(tempProject, 'src'), { recursive: true });
+        fs.writeFileSync(path.join(tempProject, 'src', 'main.cpp'), '');
+        // Create a directory without headers — should not be included
+        fs.mkdirSync(path.join(tempProject, 'docs'), { recursive: true });
+
+        clearCppIncludeDirCache();
+        const dirs = loadCppIncludeDirs(tempProject);
+
+        expect(dirs).toContain('include');
+        expect(dirs).toContain('src');
+        expect(dirs).not.toContain('docs');
+      } finally {
+        fs.rmSync(tempProject, { recursive: true });
+      }
+    });
+
+    // Documents the cross-language `.h` behavior. Objective-C and C++ share
+    // the `.h` extension, so in a mixed iOS-style project an Obj-C header
+    // dir gets claimed as a C/C++ include dir too. That's intentional — a
+    // C++ file legitimately can `#include "Foo.h"` against an Obj-C header
+    // (Obj-C++ / .mm callers), and false-positive inclusion is far cheaper
+    // than missing real resolutions. The test pins this so a later
+    // "exclude objc dirs" refactor breaks loudly and reviewers see the
+    // trade-off explicitly.
+    it('heuristic claims any top-level dir containing .h files, including Obj-C', () => {
+      const tempProject = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-cpp-test-'));
+      try {
+        // C++ side: an `cppmod` dir with a .hpp (C++-only extension)
+        fs.mkdirSync(path.join(tempProject, 'cppmod'), { recursive: true });
+        fs.writeFileSync(path.join(tempProject, 'cppmod', 'shared.hpp'), '');
+        // Obj-C side: an `iosmod` dir with .h + .m (no .cpp/.hpp).
+        fs.mkdirSync(path.join(tempProject, 'iosmod'), { recursive: true });
+        fs.writeFileSync(path.join(tempProject, 'iosmod', 'View.h'), '');
+        fs.writeFileSync(path.join(tempProject, 'iosmod', 'View.m'), '');
+
+        clearCppIncludeDirCache();
+        const dirs = loadCppIncludeDirs(tempProject);
+
+        // Both included — Obj-C dirs are intentionally allowed.
+        expect(dirs).toContain('cppmod');
+        expect(dirs).toContain('iosmod');
+      } finally {
+        fs.rmSync(tempProject, { recursive: true });
+      }
+    });
+
+    // End-to-end: ensure `#include "X.h"` produces a file→file `imports` edge
+    // in the actual indexing pipeline (not just a phantom file→import-node
+    // edge). This pins the include-dir resolution path so the headline PR
+    // feature can't silently regress to a no-op in the indexing flow.
+    it('connects #include to the real header file via include-dir scan (end-to-end)', async () => {
+      const tempProject = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-cpp-e2e-'));
+      try {
+        fs.mkdirSync(path.join(tempProject, 'include'), { recursive: true });
+        fs.mkdirSync(path.join(tempProject, 'src'), { recursive: true });
+        fs.writeFileSync(
+          path.join(tempProject, 'include', 'utils.h'),
+          `#ifndef UTILS_H\n#define UTILS_H\nint add(int, int);\n#endif\n`
+        );
+        fs.writeFileSync(
+          path.join(tempProject, 'src', 'main.cpp'),
+          `#include "utils.h"\n#include <vector>\nint main(){ return add(1,2); }\n`
+        );
+
+        clearCppIncludeDirCache();
+        cg = await CodeGraph.init(tempProject, { index: true });
+
+        // Sanity: file nodes exist for the header and the cpp.
+        const allFiles = cg.getStats();
+        expect(allFiles.fileCount).toBe(2);
+
+        // The `#include "utils.h"` edge should target the real
+        // `include/utils.h` file node — not a floating `import` node
+        // living inside main.cpp.
+        const db = DatabaseConnection.open(path.join(tempProject, '.codegraph', 'codegraph.db'));
+        const rows = db.getDb().prepare(`
+          select dst.kind as dstKind, dst.file_path as dstPath
+          from edges e
+          join nodes src on e.source = src.id
+          join nodes dst on e.target = dst.id
+          where e.kind = 'imports'
+            and src.kind = 'file'
+            and src.file_path = 'src/main.cpp'
+        `).all() as Array<{ dstKind: string; dstPath: string }>;
+        const resolvedToHeader = rows.find(
+          (r) => r.dstKind === 'file' && r.dstPath === 'include/utils.h'
+        );
+        expect(resolvedToHeader, 'main.cpp → include/utils.h imports edge missing').toBeDefined();
+        // `<vector>` should NOT produce a file edge — it's a stdlib header.
+        const stdlibFile = rows.find(
+          (r) => r.dstKind === 'file' && r.dstPath && r.dstPath.endsWith('vector')
+        );
+        expect(stdlibFile).toBeUndefined();
+      } finally {
+        fs.rmSync(tempProject, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe('PHP Include Resolution', () => {
+    it('isPhpIncludePathRef distinguishes include paths from namespace use (#660)', () => {
+      const mk = (name: string, over: Partial<UnresolvedRef> = {}): UnresolvedRef => ({
+        fromNodeId: 'f', referenceName: name, referenceKind: 'imports',
+        line: 1, column: 0, filePath: 'x.php', language: 'php', ...over,
+      });
+      // include paths: contain a slash or a file extension
+      expect(isPhpIncludePathRef(mk('lib.php'))).toBe(true);
+      expect(isPhpIncludePathRef(mk('inc/db.php'))).toBe(true);
+      expect(isPhpIncludePathRef(mk('../config.php'))).toBe(true);
+      // namespace use symbols: a bare class (Closure) or FQN — never a path,
+      // so they must NOT be treated as includes (would mis-connect to a
+      // same-named Closure.php / Bar.php file).
+      expect(isPhpIncludePathRef(mk('Closure'))).toBe(false);
+      expect(isPhpIncludePathRef(mk('PDO'))).toBe(false);
+      expect(isPhpIncludePathRef(mk('App\\Foo\\Bar'))).toBe(false);
+      // scoped to PHP imports only
+      expect(isPhpIncludePathRef(mk('lib.php', { language: 'c' }))).toBe(false);
+      expect(isPhpIncludePathRef(mk('lib.php', { referenceKind: 'calls' }))).toBe(false);
+    });
+
+    it('resolves require_once to a file→file imports edge (#660)', async () => {
+      const tempProject = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-php-e2e-'));
+      try {
+        fs.mkdirSync(path.join(tempProject, 'src'), { recursive: true });
+        fs.writeFileSync(
+          path.join(tempProject, 'src', 'lib.php'),
+          `<?php\nfunction greet() { return "hi"; }\n`
+        );
+        fs.writeFileSync(
+          path.join(tempProject, 'src', 'page.php'),
+          `<?php\nrequire_once("lib.php");\necho greet();\n`
+        );
+
+        cg = await CodeGraph.init(tempProject, { index: true });
+
+        // reporter's repro: page.php's `require_once("lib.php")` must resolve
+        // to the real src/lib.php file node — a file→file `imports` edge, so
+        // callers(lib.php) now includes page.php.
+        const db = DatabaseConnection.open(path.join(tempProject, '.codegraph', 'codegraph.db'));
+        const rows = db.getDb().prepare(`
+          select dst.kind as dstKind, dst.file_path as dstPath
+          from edges e
+          join nodes src on e.source = src.id
+          join nodes dst on e.target = dst.id
+          where e.kind = 'imports'
+            and src.kind = 'file'
+            and src.file_path = 'src/page.php'
+        `).all() as Array<{ dstKind: string; dstPath: string }>;
+        const resolved = rows.find(
+          (r) => r.dstKind === 'file' && r.dstPath === 'src/lib.php'
+        );
+        expect(resolved, 'page.php → src/lib.php imports edge missing').toBeDefined();
+      } finally {
+        fs.rmSync(tempProject, { recursive: true, force: true });
+      }
+    });
+
+    it('resolves a subdirectory include path to the correct file (#660)', async () => {
+      const tempProject = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-php-subdir-'));
+      try {
+        fs.mkdirSync(path.join(tempProject, 'inc'), { recursive: true });
+        fs.writeFileSync(
+          path.join(tempProject, 'inc', 'db.php'),
+          `<?php\nfunction query() { return 1; }\n`
+        );
+        fs.writeFileSync(
+          path.join(tempProject, 'index.php'),
+          `<?php\nrequire "inc/db.php";\nquery();\n`
+        );
+
+        cg = await CodeGraph.init(tempProject, { index: true });
+
+        const db = DatabaseConnection.open(path.join(tempProject, '.codegraph', 'codegraph.db'));
+        const rows = db.getDb().prepare(`
+          select dst.kind as dstKind, dst.file_path as dstPath
+          from edges e
+          join nodes src on e.source = src.id
+          join nodes dst on e.target = dst.id
+          where e.kind = 'imports'
+            and src.kind = 'file'
+            and src.file_path = 'index.php'
+        `).all() as Array<{ dstKind: string; dstPath: string }>;
+        expect(
+          rows.find((r) => r.dstKind === 'file' && r.dstPath === 'inc/db.php'),
+          'index.php → inc/db.php imports edge missing'
+        ).toBeDefined();
+      } finally {
+        fs.rmSync(tempProject, { recursive: true, force: true });
+      }
+    });
+
+    it('does not mis-connect an unresolvable include to a same-named file elsewhere (#660)', async () => {
+      const tempProject = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-php-misresolve-'));
+      try {
+        // app/page.php's `require "inc/db.php"` resolves relative to app/, where
+        // inc/db.php does NOT exist. A same-named lib/inc/db.php exists elsewhere
+        // but is unrelated — no edge should be created (a wrong edge is worse
+        // than a missing one).
+        fs.mkdirSync(path.join(tempProject, 'app'), { recursive: true });
+        fs.mkdirSync(path.join(tempProject, 'lib', 'inc'), { recursive: true });
+        fs.writeFileSync(
+          path.join(tempProject, 'lib', 'inc', 'db.php'),
+          `<?php\nfunction unrelated() {}\n`
+        );
+        fs.writeFileSync(
+          path.join(tempProject, 'app', 'page.php'),
+          `<?php\nrequire "inc/db.php";\n`
+        );
+
+        cg = await CodeGraph.init(tempProject, { index: true });
+
+        const db = DatabaseConnection.open(path.join(tempProject, '.codegraph', 'codegraph.db'));
+        const rows = db.getDb().prepare(`
+          select dst.kind as dstKind, dst.file_path as dstPath
+          from edges e
+          join nodes src on e.source = src.id
+          join nodes dst on e.target = dst.id
+          where e.kind = 'imports'
+            and src.kind = 'file'
+            and src.file_path = 'app/page.php'
+        `).all() as Array<{ dstKind: string; dstPath: string }>;
+        expect(
+          rows.find((r) => r.dstKind === 'file' && r.dstPath === 'lib/inc/db.php'),
+          'app/page.php must NOT mis-connect to unrelated lib/inc/db.php'
+        ).toBeUndefined();
+      } finally {
+        fs.rmSync(tempProject, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe('C++ chained-call receiver resolution (#645)', () => {
+    async function indexCpp(files: Record<string, string>): Promise<void> {
+      for (const [name, content] of Object.entries(files)) {
+        fs.writeFileSync(path.join(tempDir, name), content);
+      }
+      cg = await CodeGraph.init(tempDir, { index: true });
+    }
+
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+
+    it('resolves singleton chains and auto locals to the right class, never the first-sorted one', async () => {
+      // Two classes share writeLog; Logger sorts first so it wins any name-only
+      // tie. All three call forms target Metrics.
+      await indexCpp({
+        'logger.hpp': `#pragma once
+#include <string>
+class Logger  { public: static Logger&  instance(); void writeLog(const std::string&); };
+class Metrics { public: static Metrics& instance(); void writeLog(const std::string&); };
+`,
+        'impl.cpp': `#include "logger.hpp"
+Logger&  Logger::instance()  { static Logger l;  return l; }
+Metrics& Metrics::instance() { static Metrics m; return m; }
+void Logger::writeLog(const std::string&)  {}
+void Metrics::writeLog(const std::string&) {}
+`,
+        'app.cpp': `#include "logger.hpp"
+void a() { Metrics::instance().writeLog("x"); }              // chained singleton
+void b() { auto& m = Metrics::instance(); m.writeLog("x"); } // stored in auto
+void c() { Metrics& m = Metrics::instance(); m.writeLog("x"); } // explicit type
+`,
+      });
+
+      expect(callerNamesOf('Metrics::writeLog')).toEqual(['a', 'b', 'c']);
+      expect(callerNamesOf('Logger::writeLog')).toEqual([]);
+    });
+
+    it('resolves factories, free-function factories, and member chains via the inner call return type', async () => {
+      await indexCpp({
+        'types.hpp': `#pragma once
+#include <memory>
+struct Widget { void draw(); };
+struct Session { void run(); };
+struct View { void render(); };
+class WidgetFactory { public: static Widget create(); };
+class Manager { public: View view(); };
+Session* openSession();
+// Decoy that sorts first and has all three methods — must never win.
+struct Aaa { void draw(); void run(); void render(); };
+`,
+        'impl.cpp': `#include "types.hpp"
+void Widget::draw() {}
+void Session::run() {}
+void View::render() {}
+void Aaa::draw() {}
+void Aaa::run() {}
+void Aaa::render() {}
+Widget WidgetFactory::create() { return Widget(); }
+View Manager::view() { return View(); }
+Session* openSession() { return nullptr; }
+`,
+        'app.cpp': `#include "types.hpp"
+void factory()     { WidgetFactory::create().draw(); }   // -> Widget::draw
+void freefunc()    { openSession()->run(); }             // -> Session::run
+void member()      { Manager mgr; mgr.view().render(); }  // -> View::render
+void makeUnique()  { auto w = std::make_unique<Widget>(); w->draw(); } // -> Widget::draw
+`,
+      });
+
+      expect(callerNamesOf('Widget::draw')).toEqual(['factory', 'makeUnique']);
+      expect(callerNamesOf('Session::run')).toEqual(['freefunc']);
+      expect(callerNamesOf('View::render')).toEqual(['member']);
+      // The first-sorted decoy never captures any of them.
+      expect(callerNamesOf('Aaa::draw')).toEqual([]);
+      expect(callerNamesOf('Aaa::run')).toEqual([]);
+      expect(callerNamesOf('Aaa::render')).toEqual([]);
+    });
+
+    it('creates NO edge when the inferred type lacks the method (silent miss, not a wrong edge)', async () => {
+      await indexCpp({
+        'types.hpp': `#pragma once
+struct Widget { void draw(); };
+struct Other  { void onlyOther(); };
+class WidgetFactory { public: static Widget create(); };
+`,
+        'impl.cpp': `#include "types.hpp"
+void Widget::draw() {}
+void Other::onlyOther() {}
+Widget WidgetFactory::create() { return Widget(); }
+`,
+        'app.cpp': `#include "types.hpp"
+// Widget has no onlyOther() — must produce NO edge, never a wrong one to Other.
+void wrong() { WidgetFactory::create().onlyOther(); }
+`,
+      });
+
+      expect(callerNamesOf('Other::onlyOther')).toEqual([]);
+    });
+  });
+
+  describe('PHP chained static-factory call resolution (#608)', () => {
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+
+    it('resolves Cls::for($x)->method() via the factory\'s `: self` return (#608)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'ApiClient.php'),
+        `<?php\nclass ApiClient {\n    public static function for(string $c): self { return new self; }\n    public function createOrder(array $p): array { return []; }\n}\n`
+      );
+      fs.writeFileSync(
+        path.join(tempDir, 'DispatchOrder.php'),
+        `<?php\nclass DispatchOrder {\n    public function handle(): void {\n        ApiClient::for('cred')->createOrder([]);\n    }\n}\n`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // The chained call's edge attaches to the factory result's method.
+      expect(callerNamesOf('ApiClient::createOrder')).toContain('handle');
+    });
+
+    it('creates NO edge when the factory result lacks the method (#608)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'lib.php'),
+        `<?php\nclass ApiClient { public static function for(string $c): self { return new self; } }\nclass Other { public function onlyOther(): void {} }\nclass Caller { public function go(): void { ApiClient::for('x')->onlyOther(); } }\n`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // ApiClient has no onlyOther — must not mis-attach to the same-named Other::onlyOther.
+      expect(callerNamesOf('Other::onlyOther')).toEqual([]);
+    });
+  });
+
+  describe('Java chained static-factory call resolution (#645/#608 mechanism)', () => {
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+
+    it('resolves Foo.getInstance().bar() via the factory return type, never a same-named decoy', async () => {
+      // Aaa sorts first and has a same-named bar() — it must never win the chain.
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.java'),
+        `class Aaa { void bar() {} }
+class Foo {
+    static Foo getInstance() { return new Foo(); }
+    void bar() {}
+}
+class Caller {
+    void run() { Foo.getInstance().bar(); }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Foo::bar')).toEqual(['run']);
+      expect(callerNamesOf('Aaa::bar')).toEqual([]);
+    });
+
+    it('resolves a factory chain that passes arguments — Foo.create(cfg).build()', async () => {
+      // The factory call carries an argument; the extractor must normalize the
+      // receiver to empty parens (`Foo.create().build`) so the chain still splits.
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.java'),
+        `class Config {}
+class Foo {
+    static Foo create(Config c) { return new Foo(); }
+    void build() {}
+}
+class Caller {
+    void run() { Foo.create(new Config()).build(); }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Foo::build')).toEqual(['run']);
+    });
+
+    it('creates NO edge when the factory return type lacks the method (silent miss, not a wrong edge)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.java'),
+        `class Foo {
+    static Foo getInstance() { return new Foo(); }
+}
+class Other { void onlyOther() {} }
+class Caller {
+    void run() { Foo.getInstance().onlyOther(); }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // Foo has no onlyOther() — must not mis-attach to the same-named Other::onlyOther.
+      expect(callerNamesOf('Other::onlyOther')).toEqual([]);
+    });
+  });
+
+  describe('Kotlin chained companion-factory call resolution (#645/#608 mechanism)', () => {
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+
+    it('resolves Foo.getInstance().bar() via the companion return type, never a same-named decoy', async () => {
+      // Aaa sorts first and has a same-named bar() — without the chain fix Kotlin
+      // dropped the receiver to a bare `bar` and attached to Aaa (a wrong edge).
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.kt'),
+        `class Aaa { fun bar() {} }
+class Foo {
+    companion object {
+        fun getInstance(): Foo = Foo()
+    }
+    fun bar() {}
+}
+class Caller {
+    fun run() { Foo.getInstance().bar() }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Foo::bar')).toEqual(['run']);
+      expect(callerNamesOf('Aaa::bar')).toEqual([]);
+    });
+
+    it('resolves a companion factory chain that passes arguments — Foo.create(cfg).build()', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.kt'),
+        `class Config
+class Foo {
+    companion object {
+        fun create(c: Config): Foo = Foo()
+    }
+    fun build() {}
+}
+class Caller {
+    fun run() { Foo.create(Config()).build() }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Foo::build')).toEqual(['run']);
+    });
+
+    it('creates NO edge when the companion return type lacks the method (silent miss, not a wrong edge)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.kt'),
+        `class Foo {
+    companion object {
+        fun getInstance(): Foo = Foo()
+    }
+}
+class Other { fun onlyOther() {} }
+class Caller {
+    fun run() { Foo.getInstance().onlyOther() }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // Foo has no onlyOther() — must not mis-attach to the same-named Other::onlyOther.
+      expect(callerNamesOf('Other::onlyOther')).toEqual([]);
+    });
+  });
+
+  describe('C# chained static-factory call resolution (#645/#608 mechanism)', () => {
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+
+    it('resolves Foo.Create().Bar() via the factory return type, never a same-named decoy', async () => {
+      // Aaa sorts first and has a same-named Bar() — it must never win the chain.
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.cs'),
+        `class Aaa { void Bar() {} }
+class Foo {
+    static Foo Create() { return new Foo(); }
+    void Bar() {}
+}
+class Caller {
+    void Run() { Foo.Create().Bar(); }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Foo::Bar')).toEqual(['Run']);
+      expect(callerNamesOf('Aaa::Bar')).toEqual([]);
+    });
+
+    it('resolves a factory chain that passes arguments — Foo.Make(cfg).Build()', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.cs'),
+        `class Config {}
+class Foo {
+    static Foo Make(Config c) { return new Foo(); }
+    void Build() {}
+}
+class Caller {
+    void Run() { Foo.Make(new Config()).Build(); }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Foo::Build')).toEqual(['Run']);
+    });
+
+    it('creates NO edge when the factory return type lacks the method (silent miss, not a wrong edge)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.cs'),
+        `class Foo {
+    static Foo Create() { return new Foo(); }
+}
+class Other { void OnlyOther() {} }
+class Caller {
+    void Run() { Foo.Create().OnlyOther(); }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // Foo has no OnlyOther() — must not mis-attach to the same-named Other::OnlyOther.
+      expect(callerNamesOf('Other::OnlyOther')).toEqual([]);
+    });
+  });
+
+  describe('Swift chained static-factory call resolution (#645/#608 mechanism)', () => {
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+
+    it('resolves Foo.make().draw() via the factory return type, never a same-named decoy', async () => {
+      // Aaa sorts first and has a same-named draw() — without the fix Swift dropped
+      // the receiver to a bare `draw` and attached to Aaa (a wrong edge).
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.swift'),
+        `class Aaa { func draw() {} }
+class Foo {
+    static func make() -> Foo { return Foo() }
+    func draw() {}
+}
+func runCaller() { Foo.make().draw() }
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Foo::draw')).toEqual(['runCaller']);
+      expect(callerNamesOf('Aaa::draw')).toEqual([]);
+    });
+
+    it('resolves a constructor chain Foo().draw() and an args factory chain Foo.build(c).render()', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.swift'),
+        `class Config {}
+class Foo {
+    static func build(_ c: Config) -> Foo { return Foo() }
+    func draw() {}
+    func render() {}
+}
+func runCaller() {
+    Foo().draw()
+    Foo.build(Config()).render()
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Foo::draw')).toEqual(['runCaller']);
+      expect(callerNamesOf('Foo::render')).toEqual(['runCaller']);
+    });
+
+    it('creates NO edge when the factory return type lacks the method (silent miss, not a wrong edge)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.swift'),
+        `class Foo {
+    static func make() -> Foo { return Foo() }
+}
+class Other { func onlyOther() {} }
+func runCaller() { Foo.make().onlyOther() }
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // Foo has no onlyOther() — must not mis-attach to the same-named Other::onlyOther.
+      expect(callerNamesOf('Other::onlyOther')).toEqual([]);
+    });
+  });
+
+  describe('Chained call resolves a method on a supertype (conformance, #750)', () => {
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+
+    it('resolves a chained method defined only on a SUPERCLASS the return type extends', async () => {
+      // draw() lives on Base; Widget (the factory's return type) has no draw() of
+      // its own. Decoy.draw must never win. Needs the conformance second pass.
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.java'),
+        `class Base { void draw() {} }
+class Widget extends Base {}
+class Decoy { void draw() {} }
+class Factory { static Widget create() { return new Widget(); } }
+class Caller {
+    void run() { Factory.create().draw(); }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Base::draw')).toEqual(['run']);
+      expect(callerNamesOf('Decoy::draw')).toEqual([]);
+    });
+
+    it('resolves a chained method defined on an INTERFACE the return type implements (default method)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.java'),
+        `interface Drawable { default void draw() {} }
+class Widget implements Drawable {}
+class Decoy { void draw() {} }
+class Factory { static Widget create() { return new Widget(); } }
+class Caller {
+    void run() { Factory.create().draw(); }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Drawable::draw')).toEqual(['run']);
+      expect(callerNamesOf('Decoy::draw')).toEqual([]);
+    });
+
+    it('still creates NO edge when no supertype has the method (safety preserved)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.java'),
+        `class Base {}
+class Widget extends Base {}
+class Other { void onlyOther() {} }
+class Factory { static Widget create() { return new Widget(); } }
+class Caller {
+    void run() { Factory.create().onlyOther(); }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // Neither Widget nor Base has onlyOther() — must not attach to Other::onlyOther.
+      expect(callerNamesOf('Other::onlyOther')).toEqual([]);
+    });
+  });
+
+  describe('Rust chained associated-function call resolution (#645/#608 mechanism)', () => {
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+
+    it('resolves Foo::new().bar() (and a Self return) via the associated fn, never a same-named decoy', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.rs'),
+        `struct Aaa { _x: i32 }
+impl Aaa { fn bar(&self) {} }
+struct Foo { _x: i32 }
+impl Foo {
+    fn new() -> Foo { Foo { _x: 0 } }
+    fn make() -> Self { Foo { _x: 0 } }
+    fn bar(&self) {}
+}
+fn caller() {
+    Foo::new().bar();
+    Foo::make().bar();
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Foo::bar')).toEqual(['caller']);
+      expect(callerNamesOf('Aaa::bar')).toEqual([]);
+    });
+
+    it('resolves a chain that passes arguments — Foo::with(c).build()', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.rs'),
+        `struct Config;
+struct Foo { _x: i32 }
+impl Foo {
+    fn with(c: Config) -> Foo { Foo { _x: 0 } }
+    fn build(&self) {}
+}
+fn caller() { Foo::with(Config).build(); }
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Foo::build')).toEqual(['caller']);
+    });
+
+    it('resolves a chained method from a trait the type implements (default method, via conformance)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.rs'),
+        `struct Foo { _x: i32 }
+impl Foo { fn new() -> Foo { Foo { _x: 0 } } }
+struct Decoy { _x: i32 }
+impl Decoy { fn draw(&self) {} }
+trait Drawable { fn draw(&self) {} }
+impl Drawable for Foo {}
+fn caller() { Foo::new().draw(); }
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Drawable::draw')).toEqual(['caller']);
+      expect(callerNamesOf('Decoy::draw')).toEqual([]);
+    });
+
+    it('creates NO edge when neither the type nor a supertype has the method (silent miss)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.rs'),
+        `struct Foo { _x: i32 }
+impl Foo { fn new() -> Foo { Foo { _x: 0 } } }
+struct Other { _x: i32 }
+impl Other { fn only_other(&self) {} }
+fn caller() { Foo::new().only_other(); }
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // Foo has no only_other() — must not mis-attach to the same-named Other::only_other.
+      expect(callerNamesOf('Other::only_other')).toEqual([]);
+    });
+  });
+
+  describe('Go chained factory-function call resolution (#645/#608 mechanism)', () => {
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+
+    it('resolves New().Bar() via the factory return type (pointer), never a same-named decoy', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.go'),
+        `package main
+type Aaa struct{}
+func (a *Aaa) Bar() {}
+type Foo struct{}
+func New() *Foo { return &Foo{} }
+func (f *Foo) Bar() {}
+func caller() { New().Bar() }
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Foo::Bar')).toEqual(['caller']);
+      expect(callerNamesOf('Aaa::Bar')).toEqual([]);
+    });
+
+    it('resolves an args chain and a multi-return factory — With(c).Build(), (*Foo, error)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.go'),
+        `package main
+type Config struct{}
+type Foo struct{}
+func With(c Config) (*Foo, error) { return &Foo{}, nil }
+func (f *Foo) Build() {}
+func caller() { With(Config{}).Build() }
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Foo::Build')).toEqual(['caller']);
+    });
+
+    it('resolves a method provided by an embedded struct (via conformance)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.go'),
+        `package main
+type Base struct{}
+func (b *Base) Embedded() {}
+type Decoy struct{}
+func (d *Decoy) Embedded() {}
+type Widget struct{ Base }
+func NewWidget() *Widget { return &Widget{} }
+func caller() { NewWidget().Embedded() }
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Base::Embedded')).toEqual(['caller']);
+      expect(callerNamesOf('Decoy::Embedded')).toEqual([]);
+    });
+
+    it('creates NO edge when neither the type nor an embedded type has the method (silent miss)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.go'),
+        `package main
+type Foo struct{}
+func New() *Foo { return &Foo{} }
+type Other struct{}
+func (o *Other) OnlyOther() {}
+func caller() { New().OnlyOther() }
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // Foo has no OnlyOther() — must not mis-attach to the same-named Other::OnlyOther.
+      expect(callerNamesOf('Other::OnlyOther')).toEqual([]);
+    });
+
+    it('falls back to bare-name resolution for a VARIABLE-inner chain without exploding the graph', async () => {
+      // `engine` is a package-level VARIABLE holding a func value, not a factory
+      // FUNCTION — so its return type can't be recovered and the chain falls back
+      // to bare-name resolution of the method (restoring the pre-re-encoding edge).
+      // Regression for the runaway this fallback originally caused: it resolved
+      // with a mutated `original.referenceName` (the bare `ServeHTTP`, not the
+      // stored `engine().ServeHTTP`), so the batched resolver's keyed delete
+      // no-oped, the offset-0 batch never drained, and edges inserted forever
+      // (5M edges / 1.4 GB on a 99-file repo). The fallback now ties the match to
+      // the original ref, and a non-progress guard backstops the loop.
+      fs.writeFileSync(
+        path.join(tempDir, 'main.go'),
+        `package main
+type Server struct{}
+func (s *Server) ServeHTTP() {}
+var engine = func() *Server { return &Server{} }
+func caller() { engine().ServeHTTP() }
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // Recall: the variable-inner chain still finds the method by bare name.
+      expect(callerNamesOf('Server::ServeHTTP')).toEqual(['caller']);
+      // No runaway: a single call site yields a single edge, not millions.
+      const target = cg
+        .getNodesByKind('method')
+        .find((n) => n.qualifiedName === 'Server::ServeHTTP')!;
+      const rawCalls = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls');
+      expect(rawCalls.length).toBeLessThan(5);
+    });
+  });
+
+  describe('Scala chained static-factory call resolution (#645/#608 mechanism)', () => {
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+
+    it('resolves a companion-factory chain Foo.create().doIt() to the return type, never a same-named decoy', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.scala'),
+        `object Foo {
+  def create(): Bar = new Bar()
+}
+class Bar {
+  def doIt(): Unit = {}
+}
+class Decoy {
+  def doIt(): Unit = {}
+}
+object Main {
+  def run(): Unit = { Foo.create().doIt() }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Bar::doIt')).toEqual(['run']);
+      expect(callerNamesOf('Decoy::doIt')).toEqual([]);
+    });
+
+    it('resolves a case-class apply construction Point(x).dist() on the constructed class', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.scala'),
+        `class Point(x: Int) {
+  def dist(): Int = x
+}
+class Other {
+  def dist(): Int = 0
+}
+object Main {
+  def run(): Unit = { Point(3).dist() }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Point::dist')).toEqual(['run']);
+      expect(callerNamesOf('Other::dist')).toEqual([]);
+    });
+
+    it('resolves a chained method provided by a trait the return type extends (via conformance)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.scala'),
+        `trait Base {
+  def shared(): Unit = {}
+}
+class Widget extends Base
+class Decoy {
+  def shared(): Unit = {}
+}
+object Factory {
+  def make(): Widget = new Widget()
+}
+object Main {
+  def run(): Unit = { Factory.make().shared() }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Base::shared')).toEqual(['run']);
+      expect(callerNamesOf('Decoy::shared')).toEqual([]);
+    });
+
+    it('creates NO edge when neither the factory return type nor a supertype has the method (silent miss)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'Main.scala'),
+        `object Foo {
+  def create(): Bar = new Bar()
+}
+class Bar {
+}
+class Other {
+  def onlyOther(): Unit = {}
+}
+object Main {
+  def run(): Unit = { Foo.create().onlyOther() }
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // Bar has no onlyOther() — must not mis-attach to the same-named Other::onlyOther.
+      expect(callerNamesOf('Other::onlyOther')).toEqual([]);
+    });
+  });
+
+  describe('Dart chained static-factory / factory-constructor call resolution (#645/#608 mechanism)', () => {
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+
+    it('resolves a static-factory chain Foo.makeBar().doIt() to the return type, never a same-named decoy', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.dart'),
+        `class Foo {
+  static Bar makeBar() => Bar();
+}
+class Bar {
+  void doIt() {}
+}
+class Decoy {
+  void doIt() {}
+}
+void run() {
+  Foo.makeBar().doIt();
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Bar::doIt')).toEqual(['run']);
+      expect(callerNamesOf('Decoy::doIt')).toEqual([]);
+    });
+
+    it('resolves a named factory-constructor chain Foo.create().ship() on the constructed class', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.dart'),
+        `class Foo {
+  Foo._();
+  factory Foo.create() => Foo._();
+  void ship() {}
+}
+class Decoy {
+  void ship() {}
+}
+void run() {
+  Foo.create().ship();
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // The factory constructor `Foo.create` is now a node whose return type is Foo,
+      // so `ship` resolves on Foo, not the same-named Decoy.
+      expect(callerNamesOf('Foo::ship')).toEqual(['run']);
+      expect(callerNamesOf('Decoy::ship')).toEqual([]);
+    });
+
+    it('resolves a constructor-receiver chain Bar().doIt() on the constructed class', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.dart'),
+        `class Bar {
+  void doIt() {}
+}
+class Decoy {
+  void doIt() {}
+}
+void run() {
+  Bar().doIt();
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Bar::doIt')).toEqual(['run']);
+      expect(callerNamesOf('Decoy::doIt')).toEqual([]);
+    });
+
+    it('resolves a chained method inherited from a superclass the return type extends (via conformance)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.dart'),
+        `class Base {
+  void render() {}
+}
+class Widget extends Base {
+  static Widget make() => Widget();
+}
+class Decoy {
+  void render() {}
+}
+void run() {
+  Widget.make().render();
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Base::render')).toEqual(['run']);
+      expect(callerNamesOf('Decoy::render')).toEqual([]);
+    });
+
+    it('creates NO edge when neither the factory return type nor a supertype has the method (silent miss)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.dart'),
+        `class Foo {
+  static Bar makeBar() => Bar();
+}
+class Bar {
+}
+class Other {
+  void onlyOther() {}
+}
+void run() {
+  Foo.makeBar().onlyOther();
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // Bar has no onlyOther() — must not mis-attach to the same-named Other::onlyOther.
+      expect(callerNamesOf('Other::onlyOther')).toEqual([]);
+    });
+
+    it('still extracts a method tree-sitter misparses as a constructor (@override + record return)', async () => {
+      // tree-sitter-dart misparses `@override (A, B) reduce()` — the annotation
+      // swallows the record return type, so `reduce()` looks like a single-
+      // identifier constructor_signature. It must NOT be skipped as an unnamed
+      // ctor (its name doesn't match the class); its body call must attribute to
+      // `reduce`, not the class.
+      fs.writeFileSync(
+        path.join(tempDir, 'main.dart'),
+        `class Base {}
+class Action extends Base {
+  Action({required int x});
+  @override
+  (int, String) reduce() {
+    return (compute(), "y");
+  }
+  int compute() => 1;
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // reduce must be a node and its body call must resolve to Action::compute.
+      expect(callerNamesOf('Action::compute')).toEqual(['reduce']);
+    });
+
+    it('keeps plain construction Foo() as instantiation, not a Foo::Foo method call', async () => {
+      // The unnamed constructor is intentionally NOT extracted as a `Foo::Foo`
+      // method, so `Foo(...)` resolves to the class (an `instantiates` edge),
+      // never hijacked into a call to a phantom constructor method.
+      fs.writeFileSync(
+        path.join(tempDir, 'main.dart'),
+        `class Widget {
+  final int x;
+  Widget(this.x);
+}
+void run() {
+  Widget(3);
+}
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // No Foo::Foo phantom method node.
+      expect(cg.getNodesByKind('method').some((n) => n.qualifiedName === 'Widget::Widget')).toBe(false);
+      // The construction resolves to the class as an `instantiates` edge.
+      const widget = cg.getNodesByKind('class').find((n) => n.name === 'Widget')!;
+      const incoming = cg.getIncomingEdges(widget.id);
+      expect(incoming.some((e) => e.kind === 'instantiates')).toBe(true);
+    });
+  });
+
+  describe('Objective-C chained message-send call resolution (#645/#608 mechanism)', () => {
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+
+    it('resolves a chained message send [[Foo create] doIt] via the return type, never a same-named decoy', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.m'),
+        `@interface Bar : NSObject
+- (void)doIt;
+@end
+@implementation Bar
+- (void)doIt {}
+@end
+@interface Decoy : NSObject
+- (void)doIt;
+@end
+@implementation Decoy
+- (void)doIt {}
+@end
+@interface Foo : NSObject
++ (Bar *)create;
+@end
+@implementation Foo
++ (Bar *)create { return nil; }
+- (void)run { [[Foo create] doIt]; }
+@end
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Bar::doIt')).toEqual(['run']);
+      expect(callerNamesOf('Decoy::doIt')).toEqual([]);
+    });
+
+    it('resolves a chained message whose method is inherited from a superclass (via conformance)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.m'),
+        `@interface Base : NSObject
+- (void)render;
+@end
+@implementation Base
+- (void)render {}
+@end
+@interface Widget : Base
+@end
+@implementation Widget
+@end
+@interface Decoy : NSObject
+- (void)render;
+@end
+@implementation Decoy
+- (void)render {}
+@end
+@interface Factory : NSObject
++ (Widget *)make;
+@end
+@implementation Factory
++ (Widget *)make { return nil; }
+- (void)run { [[Factory make] render]; }
+@end
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Base::render')).toEqual(['run']);
+      expect(callerNamesOf('Decoy::render')).toEqual([]);
+    });
+
+    it('creates NO edge when the factory return type lacks the method (silent miss)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.m'),
+        `@interface Bar : NSObject
+@end
+@implementation Bar
+@end
+@interface Other : NSObject
+- (void)onlyOther;
+@end
+@implementation Other
+- (void)onlyOther {}
+@end
+@interface Foo : NSObject
++ (Bar *)create;
+@end
+@implementation Foo
++ (Bar *)create { return nil; }
+- (void)run { [[Foo create] onlyOther]; }
+@end
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // Bar has no onlyOther — must not mis-attach to the same-named Other::onlyOther.
+      expect(callerNamesOf('Other::onlyOther')).toEqual([]);
+    });
+
+    it('resolves a singleton chain [[Cache shared] clearAll] whose factory returns nonnull instancetype', async () => {
+      // The factory returns `nonnull instancetype` — the nullability qualifier must
+      // be skipped (not captured AS the type), and an instancetype class-message
+      // factory returns the receiver class, so clearAll resolves on Cache, never a
+      // same-named decoy. (Regression for both: the captured-`nonnull` bug and the
+      // ubiquitous `[[X alloc] init]` / singleton pattern.)
+      fs.writeFileSync(
+        path.join(tempDir, 'main.m'),
+        `@interface Cache : NSObject
++ (nonnull instancetype)shared;
+- (void)clearAll;
+@end
+@implementation Cache
++ (nonnull instancetype)shared { return nil; }
+- (void)clearAll {}
+@end
+@interface Decoy : NSObject
+- (void)clearAll;
+@end
+@implementation Decoy
+- (void)clearAll {}
+@end
+@interface Caller : NSObject
+- (void)run;
+@end
+@implementation Caller
+- (void)run { [[Cache shared] clearAll]; }
+@end
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(callerNamesOf('Cache::clearAll')).toEqual(['run']);
+      expect(callerNamesOf('Decoy::clearAll')).toEqual([]);
+    });
+  });
+
+  describe('Pascal/Delphi chained static-factory call resolution (#645/#608 mechanism)', () => {
+    function callerNamesOf(qualifiedName: string): string[] {
+      const target = cg.getNodesByKind('method').find((n) => n.qualifiedName === qualifiedName);
+      if (!target) return [];
+      const names = cg
+        .getIncomingEdges(target.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.source)?.name)
+        .filter((n): n is string => !!n);
+      return [...new Set(names)].sort();
+    }
+    function isCalled(qn: string): boolean {
+      const t = cg.getNodesByKind('method').find((n) => n.qualifiedName === qn);
+      return !!t && cg.getIncomingEdges(t.id).some((e) => e.kind === 'calls');
+    }
+
+    it('resolves a chained factory call TFoo.GetInstance().DoIt() via the return type, never a same-named decoy', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.pas'),
+        `unit Main;
+interface
+type
+  TBar = class
+    procedure DoIt;
+  end;
+  TDecoy = class
+    procedure DoIt;
+  end;
+  TFoo = class
+    class function GetInstance: TBar;
+  end;
+implementation
+procedure TBar.DoIt; begin end;
+procedure TDecoy.DoIt; begin end;
+class function TFoo.GetInstance: TBar; begin Result := nil; end;
+procedure Run;
+begin
+  TFoo.GetInstance().DoIt();
+end;
+end.
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(isCalled('TBar::DoIt')).toBe(true);
+      expect(isCalled('TDecoy::DoIt')).toBe(false);
+    });
+
+    it('resolves a constructor chain TFoo.Create().Configure() on the constructed class', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.pas'),
+        `unit Main;
+interface
+type
+  TFoo = class
+    constructor Create;
+    procedure Configure;
+  end;
+  TDecoy = class
+    procedure Configure;
+  end;
+implementation
+constructor TFoo.Create; begin end;
+procedure TFoo.Configure; begin end;
+procedure TDecoy.Configure; begin end;
+procedure Run;
+begin
+  TFoo.Create().Configure();
+end;
+end.
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // A constructor returns its own class (no `: TBar` annotation), so Configure
+      // resolves on TFoo, not the same-named decoy.
+      expect(isCalled('TFoo::Configure')).toBe(true);
+      expect(isCalled('TDecoy::Configure')).toBe(false);
+    });
+
+    it('resolves a typecast chain TFoo(x).DoIt() on the cast type', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.pas'),
+        `unit Main;
+interface
+type
+  TFoo = class
+    procedure DoIt;
+  end;
+  TDecoy = class
+    procedure DoIt;
+  end;
+implementation
+procedure TFoo.DoIt; begin end;
+procedure TDecoy.DoIt; begin end;
+procedure Run(obj: TObject);
+begin
+  TFoo(obj).DoIt();
+end;
+end.
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(isCalled('TFoo::DoIt')).toBe(true);
+      expect(isCalled('TDecoy::DoIt')).toBe(false);
+    });
+
+    it('creates NO edge when the factory return type lacks the method (silent miss)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.pas'),
+        `unit Main;
+interface
+type
+  TBar = class
+  end;
+  TOther = class
+    procedure OnlyOther;
+  end;
+  TFoo = class
+    class function GetInstance: TBar;
+  end;
+implementation
+procedure TOther.OnlyOther; begin end;
+class function TFoo.GetInstance: TBar; begin Result := nil; end;
+procedure Run;
+begin
+  TFoo.GetInstance().OnlyOther();
+end;
+end.
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // TBar has no OnlyOther — must not mis-attach to the same-named TOther::OnlyOther.
+      expect(isCalled('TOther::OnlyOther')).toBe(false);
+    });
+
+    it('extracts paren-less method calls (Pascal lets a no-arg method drop its parens)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.pas'),
+        `unit Main;
+interface
+type
+  TFoo = class
+    procedure DoThing;
+    procedure Reset;
+  end;
+implementation
+procedure TFoo.DoThing; begin end;
+procedure TFoo.Reset; begin end;
+procedure Run(f: TFoo);
+begin
+  f.DoThing;
+  f.Reset;
+end;
+end.
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(isCalled('TFoo::DoThing')).toBe(true);
+      expect(isCalled('TFoo::Reset')).toBe(true);
+    });
+
+    it('resolves a PAREN-LESS chained factory call TFoo.GetInstance.DoIt via the return type', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.pas'),
+        `unit Main;
+interface
+type
+  TBar = class
+    procedure DoIt;
+  end;
+  TDecoy = class
+    procedure DoIt;
+  end;
+  TFoo = class
+    class function GetInstance: TBar;
+  end;
+implementation
+procedure TBar.DoIt; begin end;
+procedure TDecoy.DoIt; begin end;
+class function TFoo.GetInstance: TBar; begin Result := nil; end;
+procedure Run;
+begin
+  TFoo.GetInstance.DoIt;
+end;
+end.
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      expect(isCalled('TBar::DoIt')).toBe(true);
+      expect(isCalled('TDecoy::DoIt')).toBe(false);
+    });
+
+    it('does NOT turn a property write/read into a call edge (only statement-level dots are calls)', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.pas'),
+        `unit Main;
+interface
+type
+  TFoo = class
+    function GetValue: Integer;
+    procedure SetValue(v: Integer);
+    property Value: Integer read GetValue write SetValue;
+  end;
+implementation
+function TFoo.GetValue: Integer; begin Result := 0; end;
+procedure TFoo.SetValue(v: Integer); begin end;
+procedure Run(f: TFoo);
+var x: Integer;
+begin
+  f.Value := 5;
+  x := f.Value;
+end;
+end.
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // A property read/write is a bare dot in assignment position, not a statement,
+      // so it must not be mis-extracted as a call to the property's getter/setter.
+      expect(isCalled('TFoo::GetValue')).toBe(false);
+      expect(isCalled('TFoo::SetValue')).toBe(false);
+    });
+
+    it('attributes an implementation-only free procedure\'s calls to the procedure, not the file', async () => {
+      fs.writeFileSync(
+        path.join(tempDir, 'main.pas'),
+        `unit Main;
+interface
+type
+  TTgt = class
+    procedure Hit;
+  end;
+  TFoo = class
+    procedure DoStuff;
+  end;
+implementation
+procedure TTgt.Hit; begin end;
+procedure TFoo.DoStuff; var t: TTgt; begin t.Hit; end;
+procedure Helper; var t: TTgt; begin t.Hit; end;
+`
+      );
+      cg = await CodeGraph.init(tempDir, { index: true });
+      // `Helper` is implementation-only (no interface decl, not a method), but its
+      // body's call must attribute to `Helper`, not the file/module — alongside the
+      // method `DoStuff`.
+      expect(callerNamesOf('TTgt::Hit')).toEqual(['DoStuff', 'Helper']);
+    });
   });
 });
diff --git a/__tests__/rn-event-channel.test.ts b/__tests__/rn-event-channel.test.ts
new file mode 100644
index 000000000..f5debe7c5
--- /dev/null
+++ b/__tests__/rn-event-channel.test.ts
@@ -0,0 +1,160 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { CodeGraph } from '../src';
+
+/**
+ * End-to-end synthesizer test: write a fixture project with a native ObjC
+ * `sendEventWithName:` site and a JS `addListener('x', fn)` subscriber,
+ * index it, and verify the synthesized cross-language event edge.
+ */
+describe('RN event channel synthesizer', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rn-event-fixture-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('synthesizes an edge from ObjC sendEventWithName: to JS addListener handler', async () => {
+    // package.json so the RN detector / general resolver sees the project as RN.
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      '{"name":"x","dependencies":{"react-native":"^0.73"}}'
+    );
+    fs.writeFileSync(
+      path.join(dir, 'Emitter.m'),
+      `
+@implementation Emitter
+- (void)reportLocation {
+    [self sendEventWithName:@"locationUpdate" body:@{}];
+}
+@end
+`
+    );
+    fs.writeFileSync(
+      path.join(dir, 'App.js'),
+      `
+function onLocation(payload) {
+    console.log(payload);
+}
+emitter.addListener('locationUpdate', onLocation);
+`
+    );
+
+    const cg = await CodeGraph.init(dir, { silent: true });
+    await cg.indexAll();
+
+    const db = (cg as any).db.db;
+    const rows = db
+      .prepare(
+        `SELECT s.name source_name, s.language sl, t.name target_name, t.language tl,
+                json_extract(e.metadata,'$.event') event
+         FROM edges e
+         JOIN nodes s ON s.id = e.source
+         JOIN nodes t ON t.id = e.target
+         WHERE json_extract(e.metadata,'$.synthesizedBy') = 'rn-event-channel'`
+      )
+      .all();
+    cg.close?.();
+    expect(rows.length).toBeGreaterThanOrEqual(1);
+    // The edge should point from the ObjC method that emits to the JS handler.
+    const edge = rows.find((r: any) => r.event === 'locationUpdate');
+    expect(edge).toBeDefined();
+    expect(edge.sl).toBe('objc');
+    expect(edge.tl).toBe('javascript');
+    expect(edge.target_name).toBe('onLocation');
+  });
+
+  it('falls back to enclosing JS function when addListener handler is a parameter (wrapper-API pattern)', async () => {
+    // Matches the real RNFirebase shape: `messaging().onMessage(listener)`
+    // is a subscribe-wrapper whose body does
+    // `addListener('messaging_message_received', listener)` where `listener`
+    // is the parameter — not a globally-named symbol. Synthesizer should
+    // still produce an edge, attributed to the enclosing wrapper function.
+    fs.writeFileSync(
+      path.join(dir, 'package.json'),
+      '{"dependencies":{"react-native":"^0.73"}}'
+    );
+    fs.writeFileSync(
+      path.join(dir, 'Native.m'),
+      `
+@implementation MyEmitter
+- (void)pushMessage {
+    [[Shared shared] sendEventWithName:@"messaging_message_received" body:@{}];
+}
+@end
+`
+    );
+    fs.writeFileSync(
+      path.join(dir, 'messaging.ts'),
+      `
+import { NativeEventEmitter } from 'react-native';
+const emitter = new NativeEventEmitter();
+export function onMessage(listener: (m: any) => void) {
+    return emitter.addListener('messaging_message_received', listener);
+}
+`
+    );
+
+    const cg = await CodeGraph.init(dir, { silent: true });
+    await cg.indexAll();
+
+    const db = (cg as any).db.db;
+    const rows = db
+      .prepare(
+        `SELECT s.name source_name, t.name target_name, t.kind target_kind, t.language tl,
+                json_extract(e.metadata,'$.event') event
+         FROM edges e
+         JOIN nodes s ON s.id = e.source
+         JOIN nodes t ON t.id = e.target
+         WHERE json_extract(e.metadata,'$.synthesizedBy') = 'rn-event-channel'`
+      )
+      .all();
+    cg.close?.();
+    const edge = rows.find((r: any) => r.event === 'messaging_message_received');
+    expect(edge).toBeDefined();
+    // Target should be the wrapper function `onMessage` — the enclosing
+    // function of the addListener call, not a bareword named handler.
+    expect(edge.target_name).toBe('onMessage');
+    expect(['function', 'method']).toContain(edge.target_kind);
+  });
+  it('synthesizes an edge from a Java sendEvent(ctx, "X", body) wrapper to a JS handler', async () => {
+    fs.writeFileSync(path.join(dir, 'package.json'), '{"dependencies":{"react-native":"^0.74.0"}}');
+    // The literal event name lives in the WRAPPER CALL, not in `.emit` (whose
+    // first arg is the `eventName` VARIABLE) — the common react-native-device-info
+    // shape that RN_JVM_EMIT_RE alone misses.
+    fs.writeFileSync(path.join(dir, 'BatteryModule.java'),
+      'public class BatteryModule extends ReactContextBaseJavaModule {\n' +
+      '  @Override public String getName() { return "BatteryModule"; }\n' +
+      '  public void onBatteryChanged() {\n' +
+      '    sendEvent(getReactApplicationContext(),\n' +
+      '      "myWrapperBatteryEvent", null);\n' +
+      '  }\n' +
+      '  private void sendEvent(ReactContext ctx, String eventName, Object data) {\n' +
+      '    ctx.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class).emit(eventName, data);\n' +
+      '  }\n' +
+      '}\n');
+    fs.writeFileSync(path.join(dir, 'index.ts'),
+      "function onBattery() {}\n" +
+      "emitter.addListener('myWrapperBatteryEvent', onBattery);\n");
+
+    const cg = await CodeGraph.init(dir, { silent: true });
+    await cg.indexAll();
+    const db = (cg as any).db.db;
+    const rows = db.prepare(
+      "SELECT s.name source_name, s.language sl, t.name target_name FROM edges e " +
+      "JOIN nodes s ON s.id=e.source JOIN nodes t ON t.id=e.target " +
+      "WHERE json_extract(e.metadata,'$.synthesizedBy')='rn-event-channel' AND json_extract(e.metadata,'$.event')='myWrapperBatteryEvent'"
+    ).all();
+    cg.close?.();
+    expect(rows.length).toBeGreaterThanOrEqual(1);
+    expect(rows[0].sl).toBe('java');
+    expect(rows[0].source_name).toBe('onBatteryChanged');
+    expect(rows[0].target_name).toBe('onBattery');
+  });
+});
diff --git a/__tests__/same-name-disambiguation.test.ts b/__tests__/same-name-disambiguation.test.ts
new file mode 100644
index 000000000..5c1ae4f1c
--- /dev/null
+++ b/__tests__/same-name-disambiguation.test.ts
@@ -0,0 +1,138 @@
+/**
+ * Same-named symbols across monorepo apps (#764).
+ *
+ * A NestJS-style monorepo has one `UserService` (and friends) per app. The
+ * graph keeps them as distinct nodes (import + proximity resolution), but the
+ * MCP tools used to AGGREGATE them: callers/callees returned one merged list
+ * and impact merged both blast radii — the conflation agents warned about.
+ *
+ * Now: multiple DISTINCT definitions (different file/qualified-name) render
+ * one section per definition, and `file` narrows to a single definition.
+ * Same-file overloads still merge (that's the overload feature).
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { CodeGraph } from '../src';
+import { ToolHandler } from '../src/mcp/tools';
+import { initGrammars, loadAllGrammars } from '../src/extraction/grammars';
+
+let tmpDir: string;
+let cg: CodeGraph;
+let handler: ToolHandler;
+
+const text = async (tool: string, args: Record<string, unknown>): Promise<string> => {
+  const res = await handler.execute(tool, args);
+  return res.content?.[0]?.text ?? '';
+};
+
+beforeAll(async () => {
+  await initGrammars();
+  await loadAllGrammars();
+
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-764-'));
+  const mk = (rel: string, content: string) => {
+    const p = path.join(tmpDir, rel);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content);
+  };
+
+  for (const app of ['billing', 'admin']) {
+    mk(
+      `apps/${app}/src/users/user.service.ts`,
+      [
+        "import { UserRepository } from './user.repository';",
+        'export class UserService {',
+        '  constructor(private readonly repo: UserRepository) {}',
+        '  findAll(): string[] {',
+        `    return this.repo.load_${app}();`,
+        '  }',
+        '}',
+      ].join('\n')
+    );
+    mk(
+      `apps/${app}/src/users/user.repository.ts`,
+      `export class UserRepository {\n  load_${app}(): string[] { return []; }\n}\n`
+    );
+    mk(
+      `apps/${app}/src/users/user.controller.ts`,
+      [
+        "import { UserService } from './user.service';",
+        'export class UserController {',
+        '  constructor(private readonly users: UserService) {}',
+        '  list(): string[] { return this.users.findAll(); }',
+        '}',
+      ].join('\n')
+    );
+  }
+
+  cg = CodeGraph.initSync(tmpDir);
+  await cg.indexAll();
+  handler = new ToolHandler(cg);
+}, 120_000);
+
+afterAll(() => {
+  cg?.destroy();
+  if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe('same-named symbols across apps (#764)', () => {
+  it('graph keeps the apps apart: no cross-app edges at all', () => {
+    const billing = new Set(
+      cg.getNodesByName('findAll').filter((n) => n.filePath.includes('billing')).map((n) => n.id)
+    );
+    for (const id of billing) {
+      for (const e of cg.getIncomingEdges(id)) {
+        const src = cg.getNode(e.source);
+        expect(src?.filePath.includes('admin')).toBe(false);
+      }
+    }
+  });
+
+  it('callers: one section per distinct definition, each with only its own callers', async () => {
+    const out = await text('codegraph_callers', { symbol: 'findAll' });
+    expect(out).toContain('2 distinct definitions');
+    // Section per definition…
+    expect(out).toContain('apps/admin/src/users/user.service.ts');
+    expect(out).toContain('apps/billing/src/users/user.service.ts');
+    // …and the billing section must list the billing controller, not admin's.
+    const billingSection = out.slice(out.indexOf('apps/billing/src/users/user.service.ts'));
+    const billingBody = billingSection.slice(0, billingSection.indexOf('###', 3) > 0 ? billingSection.indexOf('###', 3) : undefined);
+    expect(billingBody).toContain('apps/billing/src/users/user.controller.ts');
+    expect(billingBody).not.toContain('apps/admin/src/users/user.controller.ts');
+  });
+
+  it('callers: `file` narrows to one definition (flat list, no stale aggregation note)', async () => {
+    const out = await text('codegraph_callers', {
+      symbol: 'findAll',
+      file: 'apps/billing/src/users/user.service.ts',
+    });
+    expect(out).not.toContain('distinct definitions');
+    expect(out).toContain('apps/billing/src/users/user.controller.ts');
+    expect(out).not.toContain('apps/admin/');
+    expect(out).not.toContain('Aggregated results');
+  });
+
+  it('callers: a non-matching `file` falls back to all definitions with a note', async () => {
+    const out = await text('codegraph_callers', { symbol: 'findAll', file: 'apps/nonexistent/x.ts' });
+    expect(out).toContain('no definition of "findAll" matches file');
+    expect(out).toContain('2 distinct definitions');
+  });
+
+  it('impact: separate blast radius per definition, never a merged one', async () => {
+    const out = await text('codegraph_impact', { symbol: 'UserService' });
+    expect(out).toContain('2 distinct definitions');
+    // Each section's count covers ONE app (service + ctor + findAll +
+    // controller side), not the union of both.
+    const counts = [...out.matchAll(/affects (\d+) symbols/g)].map((m) => Number(m[1]));
+    expect(counts).toHaveLength(2);
+    for (const c of counts) expect(c).toBeLessThanOrEqual(7);
+  });
+
+  it('callees: grouped the same way', async () => {
+    const out = await text('codegraph_callees', { symbol: 'list' });
+    expect(out).toContain('2 distinct definitions');
+  });
+});
diff --git a/__tests__/security.test.ts b/__tests__/security.test.ts
index 53441d587..f46798283 100644
--- a/__tests__/security.test.ts
+++ b/__tests__/security.test.ts
@@ -12,12 +12,10 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { FileLock } from '../src/utils';
+import { FileLock, validateProjectPath, validatePathWithinRoot } from '../src/utils';
 import CodeGraph from '../src/index';
 import { ToolHandler, tools } from '../src/mcp/tools';
-import { shouldIncludeFile, scanDirectory } from '../src/extraction';
-import { shouldIncludeFile as configShouldInclude } from '../src/config';
-import { CodeGraphConfig, DEFAULT_CONFIG } from '../src/types';
+import { scanDirectory, isSourceFile } from '../src/extraction';
 import { DatabaseConnection, getDatabasePath } from '../src/db';
 import { QueryBuilder } from '../src/db/queries';
 
@@ -178,6 +176,112 @@ describe('Path Traversal Prevention', () => {
   });
 });
 
+describe('Symlink escape prevention (#527)', () => {
+  // An in-repo symlink whose logical path is inside the project root but whose
+  // REAL target escapes the root must never be served. validatePathWithinRoot
+  // is the chokepoint both content-serving read sinks go through (codegraph_node
+  // includeCode + codegraph_explore source rendering), so it must resolve
+  // symlinks, not just compare strings. realpathSync the roots so the test's own
+  // expectations don't trip over /tmp -> /private/tmp on macOS.
+  let root: string;
+  let outside: string;
+
+  beforeEach(() => {
+    root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'cg-root-')));
+    outside = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'cg-outside-')));
+    fs.mkdirSync(path.join(root, 'src'));
+    fs.writeFileSync(path.join(root, 'src', 'in.ts'), 'export const x = 1;\n');
+    fs.mkdirSync(path.join(outside, 'pkg'));
+    fs.writeFileSync(path.join(outside, 'pkg', 'secret.txt'), 'TOP-SECRET\n');
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+    fs.rmSync(outside, { recursive: true, force: true });
+  });
+
+  // Symlink creation needs privileges on Windows; skip gracefully if it fails.
+  const link = (linkPath: string, target: string): boolean => {
+    try { fs.symlinkSync(target, linkPath); return true; } catch { return false; }
+  };
+
+  it('allows a real file inside the root (and realpaths consistently)', () => {
+    expect(validatePathWithinRoot(root, 'src/in.ts')).not.toBeNull();
+  });
+
+  it('allows a not-yet-existing path inside the root (ENOENT — files about to be written)', () => {
+    expect(validatePathWithinRoot(root, 'src/will-write.ts')).not.toBeNull();
+  });
+
+  it('rejects a lexical ../ traversal out of the root', () => {
+    expect(validatePathWithinRoot(root, `../${path.basename(outside)}/pkg/secret.txt`)).toBeNull();
+  });
+
+  it('rejects an in-repo symlink to an out-of-root FILE', () => {
+    if (!link(path.join(root, 'escape'), path.join(outside, 'pkg', 'secret.txt'))) return;
+    expect(validatePathWithinRoot(root, 'escape')).toBeNull();
+  });
+
+  it('rejects a path that escapes through an in-repo symlink to an out-of-root DIR', () => {
+    if (!link(path.join(root, 'escapedir'), path.join(outside, 'pkg'))) return;
+    expect(validatePathWithinRoot(root, 'escapedir/secret.txt')).toBeNull();
+  });
+
+  it('still allows an in-repo symlink that stays WITHIN the root (no over-blocking)', () => {
+    if (!link(path.join(root, 'src', 'inlink.ts'), path.join(root, 'src', 'in.ts'))) return;
+    expect(validatePathWithinRoot(root, 'src/inlink.ts')).not.toBeNull();
+  });
+
+  it('end-to-end: getCode never serves an out-of-root file reached via a dir symlink', async () => {
+    fs.writeFileSync(path.join(outside, 'pkg', 'leak.ts'),
+      'export function leaked() { return "LEAKED-ZZZ-9"; }\n');
+    if (!link(path.join(root, 'vendored'), path.join(outside, 'pkg'))) return;
+
+    const cg = CodeGraph.initSync(root, { config: { include: ['**/*.ts'], exclude: [] } });
+    try {
+      await cg.indexAll();
+      // Whether or not extraction followed the dir symlink, NO node may ever
+      // yield the out-of-root content through getCode.
+      for (const n of cg.getNodesByKind('function')) {
+        const code = await cg.getCode(n.id);
+        expect(code ?? '').not.toContain('LEAKED-ZZZ-9');
+      }
+    } finally {
+      cg.close();
+    }
+  });
+});
+
+describe('validateProjectPath — sensitive directory blocking', () => {
+  // POSIX-only: on Windows '/etc' resolves to C:\etc (non-existent), not a
+  // sensitive dir — the Windows case is covered by the win32-gated test below.
+  it.runIf(process.platform !== 'win32')('blocks POSIX system directories (exact match)', () => {
+    expect(validateProjectPath('/')).toMatch(/sensitive system directory/i);
+    expect(validateProjectPath('/etc')).toMatch(/sensitive system directory/i);
+  });
+
+  it('allows a normal, existing directory', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-validate-'));
+    try {
+      expect(validateProjectPath(dir)).toBeNull();
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  // SENSITIVE_PATHS stores the Windows entries lowercase and validateProjectPath
+  // matches via resolved.toLowerCase(), so 'C:\\Windows' and 'c:\\windows' are
+  // both blocked. path.resolve is platform-specific, so this only runs on Windows.
+  it.runIf(process.platform === 'win32')(
+    'blocks Windows system directories regardless of case',
+    () => {
+      expect(validateProjectPath('C:\\Windows')).toMatch(/sensitive system directory/i);
+      expect(validateProjectPath('c:\\windows')).toMatch(/sensitive system directory/i);
+      expect(validateProjectPath('C:\\WINDOWS\\System32')).toMatch(/sensitive system directory/i);
+    }
+  );
+});
+
 describe('MCP Input Validation', () => {
   let testDir: string;
   let cg: CodeGraph;
@@ -235,12 +339,38 @@ describe('MCP Input Validation', () => {
     expect(result.content[0].text).toContain('non-empty string');
   });
 
-  it('should reject non-string task in codegraph_context', async () => {
-    const result = await handler.execute('codegraph_context', { task: undefined });
+  it('should reject non-string query in codegraph_explore', async () => {
+    const result = await handler.execute('codegraph_explore', { query: undefined });
     expect(result.isError).toBe(true);
     expect(result.content[0].text).toContain('non-empty string');
   });
 
+  it('should truncate oversized tool output', async () => {
+    // Force a huge result set through codegraph_search; the response must be
+    // truncated with the sentinel rather than flooding the agent's context.
+    const many = Array.from({ length: 3000 }, (_, i) => ({
+      node: {
+        id: `n${i}`,
+        name: `symbol_${i}_${'x'.repeat(40)}`,
+        kind: 'function',
+        filePath: `src/very/deep/path/file_${i}.ts`,
+        startLine: 1,
+        endLine: 2,
+        language: 'typescript',
+      },
+      score: 1,
+    }));
+    const fakeCg = {
+      searchNodes: () => many,
+    };
+    const fakeHandler = new ToolHandler(fakeCg as unknown as CodeGraph);
+
+    const result = await fakeHandler.execute('codegraph_search', { query: 'x' });
+
+    expect(result.isError).toBeFalsy();
+    expect(result.content[0].text).toContain('... (output truncated)');
+  });
+
   it('should reject non-string symbol in codegraph_impact', async () => {
     const result = await handler.execute('codegraph_impact', { symbol: [] });
     expect(result.isError).toBe(true);
@@ -265,6 +395,34 @@ describe('MCP Input Validation', () => {
     const result = await handler.execute('codegraph_search', { query: 'example', limit: -5 });
     expect(result.isError).toBeFalsy();
   });
+
+  // #230: getCodeGraph must reject a sensitive system directory passed as
+  // projectPath before opening it. The error surfaces through execute()'s
+  // catch as an isError result. /etc is sensitive on POSIX; C:\Windows on
+  // Windows (path.resolve is platform-specific, so each case is gated).
+  it.runIf(process.platform !== 'win32')(
+    'rejects a sensitive POSIX projectPath (/etc) via the MCP handler',
+    async () => {
+      const result = await handler.execute('codegraph_search', {
+        query: 'example',
+        projectPath: '/etc',
+      });
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toMatch(/sensitive system directory/i);
+    }
+  );
+
+  it.runIf(process.platform === 'win32')(
+    'rejects a sensitive Windows projectPath (C:\\Windows) via the MCP handler',
+    async () => {
+      const result = await handler.execute('codegraph_search', {
+        query: 'example',
+        projectPath: 'C:\\Windows',
+      });
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toMatch(/sensitive system directory/i);
+    }
+  );
 });
 
 describe('Atomic Writes', () => {
@@ -298,58 +456,24 @@ describe('Atomic Writes', () => {
   });
 });
 
-describe('Glob Matching (picomatch)', () => {
-  const makeConfig = (include: string[], exclude: string[]): CodeGraphConfig => ({
-    ...DEFAULT_CONFIG,
-    rootDir: '/test',
-    include,
-    exclude,
+describe('Source file detection (isSourceFile)', () => {
+  it('selects files by supported extension', () => {
+    expect(isSourceFile('src/index.ts')).toBe(true);
+    expect(isSourceFile('src/deep/nested/file.ts')).toBe(true);
+    expect(isSourceFile('src/component.tsx')).toBe(true);
+    expect(isSourceFile('lib/util.js')).toBe(true);
+    expect(isSourceFile('src/main.py')).toBe(true);
   });
 
-  it('should match standard glob patterns in extraction', () => {
-    const config = makeConfig(['**/*.ts'], ['node_modules/**']);
-
-    expect(shouldIncludeFile('src/index.ts', config)).toBe(true);
-    expect(shouldIncludeFile('src/deep/nested/file.ts', config)).toBe(true);
-    expect(shouldIncludeFile('src/index.js', config)).toBe(false);
-    expect(shouldIncludeFile('node_modules/lib/index.ts', config)).toBe(false);
-  });
-
-  it('should match standard glob patterns in config', () => {
-    const config = makeConfig(['**/*.py'], ['__pycache__/**']);
-
-    expect(configShouldInclude('src/main.py', config)).toBe(true);
-    expect(configShouldInclude('src/main.ts', config)).toBe(false);
-    expect(configShouldInclude('__pycache__/module.py', config)).toBe(false);
+  it('rejects unsupported extensions and extensionless files', () => {
+    expect(isSourceFile('src/component.css')).toBe(false);
+    expect(isSourceFile('README.md')).toBe(false);
+    expect(isSourceFile('Makefile')).toBe(false);
+    expect(isSourceFile('.gitignore')).toBe(false);
   });
 
-  it('should handle complex glob patterns correctly', () => {
-    const config = makeConfig(['src/**/*.{ts,tsx}', 'lib/**/*.js'], []);
-
-    expect(shouldIncludeFile('src/component.ts', config)).toBe(true);
-    expect(shouldIncludeFile('src/component.tsx', config)).toBe(true);
-    expect(shouldIncludeFile('lib/util.js', config)).toBe(true);
-    expect(shouldIncludeFile('src/component.css', config)).toBe(false);
-  });
-
-  it('should handle patterns that previously caused ReDoS', () => {
-    // This pattern would cause catastrophic backtracking with hand-rolled regex
-    const evilPattern = '**/**/**/**/**/**/**/**/**/**/**/**/**/**/a';
-    const config = makeConfig([evilPattern], []);
-
-    const start = Date.now();
-    // This should return quickly, not hang
-    shouldIncludeFile('x/x/x/x/x/x/x/x/x/x/x/x/x/x/b', config);
-    const elapsed = Date.now() - start;
-
-    // Should complete in under 100ms, not seconds
-    expect(elapsed).toBeLessThan(100);
-  });
-
-  it('should handle dot files correctly', () => {
-    const config = makeConfig(['**/*.ts'], []);
-
-    expect(shouldIncludeFile('.hidden/index.ts', config)).toBe(true);
+  it('matches regardless of leading dot directories', () => {
+    expect(isSourceFile('.hidden/index.ts')).toBe(true);
   });
 });
 
@@ -464,15 +588,9 @@ describe('Symlink Cycle Detection', () => {
       return;
     }
 
-    const config: CodeGraphConfig = {
-      ...DEFAULT_CONFIG,
-      rootDir: tempDir,
-      include: ['**/*.ts'],
-      exclude: [],
-    };
 
     // This should complete without hanging
-    const files = scanDirectory(tempDir, config);
+    const files = scanDirectory(tempDir);
 
     // Should find the real file but not loop infinitely
     expect(files).toContain('src/index.ts');
@@ -496,14 +614,8 @@ describe('Symlink Cycle Detection', () => {
       return;
     }
 
-    const config: CodeGraphConfig = {
-      ...DEFAULT_CONFIG,
-      rootDir: tempDir,
-      include: ['**/*.ts'],
-      exclude: [],
-    };
 
-    const files = scanDirectory(tempDir, config);
+    const files = scanDirectory(tempDir);
 
     // Should find files from both the real dir and via the symlink
     // But deduplicate since they resolve to the same real path
@@ -521,15 +633,9 @@ describe('Symlink Cycle Detection', () => {
       return;
     }
 
-    const config: CodeGraphConfig = {
-      ...DEFAULT_CONFIG,
-      rootDir: tempDir,
-      include: ['**/*.ts'],
-      exclude: [],
-    };
 
     // Should not throw
-    const files = scanDirectory(tempDir, config);
+    const files = scanDirectory(tempDir);
     expect(files).toContain('src/valid.ts');
   });
 });
diff --git a/__tests__/sqlite-backend.test.ts b/__tests__/sqlite-backend.test.ts
index 9fe139c12..0815551dc 100644
--- a/__tests__/sqlite-backend.test.ts
+++ b/__tests__/sqlite-backend.test.ts
@@ -1,59 +1,18 @@
 /**
- * SQLite backend visibility tests
+ * SQLite backend reporting.
  *
- * Pins the WASM-fallback banner content + the per-instance backend
- * tracking. Closes the visibility gap behind issue #138.
+ * node:sqlite (Node's built-in real SQLite) is the sole backend. Pin that
+ * DatabaseConnection / CodeGraph report it and come up in WAL.
  */
 
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import {
-  buildWasmFallbackBanner,
-  WASM_FALLBACK_FIX_RECIPE,
-} from '../src/db/sqlite-adapter';
 import { DatabaseConnection } from '../src/db';
 import { CodeGraph } from '../src';
 
-describe('buildWasmFallbackBanner — fix-recipe content', () => {
-  it('includes the macOS / Linux / cross-platform fix commands', () => {
-    const banner = buildWasmFallbackBanner();
-    expect(banner).toContain('WASM SQLite fallback active');
-    expect(banner).toContain('5-10x slower');
-    expect(banner).toContain('xcode-select --install');
-    expect(banner).toContain('apt install build-essential');
-    expect(banner).toContain('npm rebuild better-sqlite3');
-    expect(banner).toContain('npm install better-sqlite3 --save');
-    expect(banner).toContain('codegraph status');
-  });
-
-  it('appends the native load error when one is provided', () => {
-    const banner = buildWasmFallbackBanner(
-      "Cannot find module 'better-sqlite3'"
-    );
-    expect(banner).toContain(
-      "Native load error: Cannot find module 'better-sqlite3'"
-    );
-  });
-
-  it('omits the load-error block when no error is supplied', () => {
-    const banner = buildWasmFallbackBanner();
-    expect(banner).not.toContain('Native load error:');
-  });
-});
-
-describe('WASM_FALLBACK_FIX_RECIPE — single source of truth', () => {
-  it('mentions the three recovery commands', () => {
-    expect(WASM_FALLBACK_FIX_RECIPE).toContain('xcode-select --install');
-    expect(WASM_FALLBACK_FIX_RECIPE).toContain('npm rebuild better-sqlite3');
-    expect(WASM_FALLBACK_FIX_RECIPE).toContain(
-      'npm install better-sqlite3 --save'
-    );
-  });
-});
-
-describe('DatabaseConnection — per-instance backend reporting', () => {
+describe('DatabaseConnection — backend reporting', () => {
   let dir: string;
 
   beforeEach(() => {
@@ -66,11 +25,10 @@ describe('DatabaseConnection — per-instance backend reporting', () => {
     }
   });
 
-  it('reports a concrete backend (native or wasm) for an initialized DB', () => {
-    const dbPath = path.join(dir, 'test.db');
-    const conn = DatabaseConnection.initialize(dbPath);
-    const backend = conn.getBackend();
-    expect(['native', 'wasm']).toContain(backend);
+  it('reports the node-sqlite backend in WAL for an initialized DB', () => {
+    const conn = DatabaseConnection.initialize(path.join(dir, 'test.db'));
+    expect(conn.getBackend()).toBe('node-sqlite');
+    expect(conn.getJournalMode()).toBe('wal');
     conn.close();
   });
 
@@ -78,7 +36,7 @@ describe('DatabaseConnection — per-instance backend reporting', () => {
     fs.writeFileSync(path.join(dir, 'x.ts'), `export function x(): void {}\n`);
     const cg = await CodeGraph.init(dir, { index: true });
     try {
-      expect(['native', 'wasm']).toContain(cg.getBackend());
+      expect(cg.getBackend()).toBe('node-sqlite');
     } finally {
       cg.destroy();
     }
diff --git a/__tests__/status-json.test.ts b/__tests__/status-json.test.ts
new file mode 100644
index 000000000..772152f13
--- /dev/null
+++ b/__tests__/status-json.test.ts
@@ -0,0 +1,89 @@
+/**
+ * Tests for the CI/scripting fields `codegraph status --json` exposes (issue
+ * #329): the `version`, `indexPath`, and `lastIndexed` fields, plus the
+ * matching `CodeGraph.getLastIndexedAt()` library method.
+ *
+ * The CLI itself is exercised end-to-end against the built binary so the JSON
+ * field names survive future refactors of the underlying plumbing.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { CodeGraph } from '../src';
+
+const BIN = path.resolve(__dirname, '../dist/bin/codegraph.js');
+const PKG_VERSION = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, '../package.json'), 'utf-8'),
+).version as string;
+
+function runStatusJson(cwd: string): Record<string, unknown> {
+  const stdout = execFileSync(process.execPath, [BIN, 'status', '--json'], {
+    cwd,
+    encoding: 'utf-8',
+    env: { ...process.env, CODEGRAPH_NO_DAEMON: '1' },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  // JSON mode prints exactly one line to stdout; be defensive about any stray
+  // leading output by parsing the last non-empty line.
+  const line = stdout.trim().split('\n').filter(Boolean).pop()!;
+  return JSON.parse(line);
+}
+
+describe('codegraph status --json — CI fields (#329)', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-status-json-'));
+  });
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('getLastIndexedAt() is null before indexing and a recent ms timestamp after', async () => {
+    const cg = CodeGraph.initSync(tempDir);
+    expect(cg.getLastIndexedAt()).toBeNull();
+
+    fs.writeFileSync(path.join(tempDir, 'a.ts'), 'export const x = 1;\n');
+    const before = Date.now();
+    await cg.indexAll();
+    const after = Date.now();
+
+    const last = cg.getLastIndexedAt();
+    expect(last).not.toBeNull();
+    expect(typeof last).toBe('number');
+    expect(last!).toBeGreaterThanOrEqual(before - 1000);
+    expect(last!).toBeLessThanOrEqual(after + 1000);
+    cg.close();
+  });
+
+  it('status --json on an UNINITIALIZED project reports version + indexPath + lastIndexed:null', () => {
+    const out = runStatusJson(tempDir);
+    expect(out.initialized).toBe(false);
+    expect(out.version).toBe(PKG_VERSION);
+    expect(typeof out.indexPath).toBe('string');
+    expect(out.indexPath as string).toContain('.codegraph');
+    expect(out.lastIndexed).toBeNull();
+  });
+
+  it('status --json on an INDEXED project reports version + indexPath + a round-trippable lastIndexed', async () => {
+    fs.writeFileSync(path.join(tempDir, 'a.ts'), 'export const x = 1;\n');
+    const before = Date.now();
+    const cg = CodeGraph.initSync(tempDir);
+    await cg.indexAll();
+    const after = Date.now();
+    cg.close();
+
+    const out = runStatusJson(tempDir);
+    expect(out.initialized).toBe(true);
+    expect(out.version).toBe(PKG_VERSION);
+    expect(out.indexPath as string).toContain('.codegraph');
+    expect(typeof out.lastIndexed).toBe('string');
+    // ISO string that round-trips back into the index window.
+    const ms = Date.parse(out.lastIndexed as string);
+    expect(ms).toBeGreaterThanOrEqual(before - 1000);
+    expect(ms).toBeLessThanOrEqual(after + 1000);
+  });
+});
diff --git a/__tests__/stdin-teardown.test.ts b/__tests__/stdin-teardown.test.ts
new file mode 100644
index 000000000..c538ac5b2
--- /dev/null
+++ b/__tests__/stdin-teardown.test.ts
@@ -0,0 +1,46 @@
+/**
+ * #799 — a socket-backed stdin that fails must shut the server down, not
+ * orphan/busy-spin. treatStdinFailureAsShutdown is the shared guard.
+ */
+import { describe, it, expect } from 'vitest';
+import { PassThrough } from 'stream';
+import { treatStdinFailureAsShutdown } from '../src/mcp/stdin-teardown';
+
+describe('treatStdinFailureAsShutdown (#799)', () => {
+  it("treats a stdin 'error' (ECONNRESET/hangup) as a shutdown signal", () => {
+    const s = new PassThrough();
+    let calls = 0;
+    treatStdinFailureAsShutdown(() => { calls++; }, s);
+
+    // No extra 'error' listener would throw here — the guard registers one.
+    s.emit('error', new Error('read ECONNRESET'));
+    expect(calls).toBe(1);
+  });
+
+  it("also fires on 'end' and on 'close'", () => {
+    for (const ev of ['end', 'close'] as const) {
+      const s = new PassThrough();
+      let calls = 0;
+      treatStdinFailureAsShutdown(() => { calls++; }, s);
+      s.emit(ev);
+      expect(calls, `event ${ev}`).toBe(1);
+    }
+  });
+
+  it('destroys the stream so a hung fd leaves epoll', () => {
+    const s = new PassThrough();
+    treatStdinFailureAsShutdown(() => { /* noop */ }, s);
+    s.emit('error', new Error('boom'));
+    expect(s.destroyed).toBe(true);
+  });
+
+  it('fires onTerminal at most once, even across error → close', () => {
+    const s = new PassThrough();
+    let calls = 0;
+    treatStdinFailureAsShutdown(() => { calls++; }, s);
+    s.emit('error', new Error('boom')); // fire() also destroys → emits 'close'
+    s.emit('close');                    // must not double-fire
+    s.emit('end');
+    expect(calls).toBe(1);
+  });
+});
diff --git a/__tests__/swift-objc-bridge-resolver.test.ts b/__tests__/swift-objc-bridge-resolver.test.ts
new file mode 100644
index 000000000..75c5d07ee
--- /dev/null
+++ b/__tests__/swift-objc-bridge-resolver.test.ts
@@ -0,0 +1,205 @@
+import { describe, it, expect } from 'vitest';
+import type { Node } from '../src/types';
+import type { ResolutionContext, UnresolvedRef } from '../src/resolution/types';
+import { swiftObjcBridgeResolver } from '../src/resolution/frameworks/swift-objc';
+
+/**
+ * Lightweight ResolutionContext mock — implements only the methods the
+ * bridge resolver actually calls. Anything else throws so a leaked call
+ * surfaces loudly in tests.
+ */
+function makeContext(nodes: Node[], fileContents: Record<string, string> = {}): ResolutionContext {
+  const byName = new Map<string, Node[]>();
+  for (const n of nodes) {
+    const arr = byName.get(n.name);
+    if (arr) arr.push(n);
+    else byName.set(n.name, [n]);
+  }
+  const allFiles = new Set(nodes.map((n) => n.filePath));
+  return {
+    getNodesInFile: (fp) => nodes.filter((n) => n.filePath === fp),
+    getNodesByName: (name) => byName.get(name) ?? [],
+    getNodesByQualifiedName: () => { throw new Error('not used'); },
+    getNodesByKind: (kind) => nodes.filter((n) => n.kind === kind),
+    getNodesByLowerName: () => { throw new Error('not used'); },
+    fileExists: (fp) => allFiles.has(fp),
+    readFile: (fp) => fileContents[fp] ?? null,
+    getProjectRoot: () => '/test',
+    getAllFiles: () => Array.from(allFiles),
+    getImportMappings: () => [],
+  };
+}
+
+function method(name: string, language: 'swift' | 'objc', filePath: string, startLine = 10): Node {
+  return {
+    id: `${language}:${filePath}:${name}:${startLine}`,
+    kind: 'method',
+    name,
+    qualifiedName: `${filePath}::${name}`,
+    filePath,
+    language,
+    startLine,
+    endLine: startLine + 5,
+    startColumn: 0,
+    endColumn: 0,
+    updatedAt: Date.now(),
+  } as Node;
+}
+
+function ref(name: string, language: 'swift' | 'objc', filePath: string): UnresolvedRef {
+  return {
+    fromNodeId: `caller:${filePath}`,
+    referenceName: name,
+    referenceKind: 'calls',
+    line: 1,
+    column: 0,
+    filePath,
+    language,
+  };
+}
+
+describe('swiftObjcBridgeResolver integration', () => {
+  describe('detect()', () => {
+    it('returns true when both .swift and .m files exist', () => {
+      const ctx = makeContext([
+        method('foo', 'swift', 'A.swift'),
+        method('bar', 'objc', 'B.m'),
+      ]);
+      expect(swiftObjcBridgeResolver.detect(ctx)).toBe(true);
+    });
+
+    it('returns false when only .swift files exist', () => {
+      const ctx = makeContext([method('foo', 'swift', 'A.swift')]);
+      expect(swiftObjcBridgeResolver.detect(ctx)).toBe(false);
+    });
+
+    it('returns true when .swift and .mm exist (ObjC++)', () => {
+      const ctx = makeContext([
+        method('foo', 'swift', 'A.swift'),
+        method('bar', 'objc', 'B.mm'),
+      ]);
+      expect(swiftObjcBridgeResolver.detect(ctx)).toBe(true);
+    });
+  });
+
+  describe('claimsReference()', () => {
+    it('claims selector-shape names (contain :)', () => {
+      expect(swiftObjcBridgeResolver.claimsReference?.('fooWithBar:')).toBe(true);
+      expect(swiftObjcBridgeResolver.claimsReference?.('tableView:didSelectRowAtIndexPath:')).toBe(true);
+      expect(swiftObjcBridgeResolver.claimsReference?.('setName:')).toBe(true);
+    });
+
+    it('does not claim bare names (handled by normal name-matcher)', () => {
+      expect(swiftObjcBridgeResolver.claimsReference?.('foo')).toBe(false);
+      expect(swiftObjcBridgeResolver.claimsReference?.('init')).toBe(false);
+    });
+  });
+
+  describe('resolve() — Swift → ObjC direction', () => {
+    it('resolves Swift call to Cocoa-style ObjC method (fetchEntry → fetchEntryForKey:)', () => {
+      // Swift writes `cache.fetchEntry(forKey: "x")` → ref name `fetchEntry`.
+      // ObjC method is `fetchEntryForKey:` (preposition-prefix shape).
+      // `fetchEntry` is project-specific (not in the generic-names blocklist
+      // that filters init/count/description/etc. to avoid Cocoa noise).
+      const objcTarget = method('fetchEntryForKey:', 'objc', 'Cache.m');
+      const ctx = makeContext([objcTarget]);
+      const result = swiftObjcBridgeResolver.resolve(
+        ref('fetchEntry', 'swift', 'Caller.swift'),
+        ctx
+      );
+      expect(result).not.toBeNull();
+      expect(result?.targetNodeId).toBe(objcTarget.id);
+      expect(result?.resolvedBy).toBe('framework');
+      expect(result?.confidence).toBe(0.6);
+    });
+
+    it('does NOT bridge generic Cocoa names like "init" or "description"', () => {
+      // Bridging Swift `init()` calls to arbitrary ObjC `init*:` methods is
+      // noise — every NSObject subclass has them. The regular name-matcher
+      // handles `init` on its own.
+      const objcInit = method('initWithFrame:', 'objc', 'View.m');
+      const ctx = makeContext([objcInit]);
+      const result = swiftObjcBridgeResolver.resolve(
+        ref('init', 'swift', 'Caller.swift'),
+        ctx
+      );
+      expect(result).toBeNull();
+    });
+
+    it('resolves bridged "With" form: Swift `play(song:)` → ObjC `playWithSong:`', () => {
+      const objcTarget = method('playWithSong:', 'objc', 'Player.m');
+      const ctx = makeContext([objcTarget]);
+      const result = swiftObjcBridgeResolver.resolve(
+        ref('play', 'swift', 'Caller.swift'),
+        ctx
+      );
+      expect(result?.targetNodeId).toBe(objcTarget.id);
+    });
+
+    it('returns null when no matching ObjC method exists', () => {
+      const ctx = makeContext([method('unrelated:thing:', 'objc', 'X.m')]);
+      const result = swiftObjcBridgeResolver.resolve(
+        ref('completelyDifferent', 'swift', 'Caller.swift'),
+        ctx
+      );
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('resolve() — ObjC → Swift direction', () => {
+    it('resolves ObjC selector to @objc-exposed Swift method (exporter form)', () => {
+      // Swift @objc export of `func animate(xAxisDuration:, yAxisDuration:)`
+      // produces ObjC selector `animateWithXAxisDuration:yAxisDuration:`
+      // (always "With" insertion on first explicit label).
+      const swiftTarget = method('animate', 'swift', 'Chart.swift', 10);
+      const ctx = makeContext([swiftTarget], {
+        'Chart.swift':
+          '\n'.repeat(8) +
+          '@objc open func animate(xAxisDuration: Double, yAxisDuration: Double) {}\n',
+      });
+      const result = swiftObjcBridgeResolver.resolve(
+        ref('animateWithXAxisDuration:yAxisDuration:', 'objc', 'Caller.m'),
+        ctx
+      );
+      expect(result?.targetNodeId).toBe(swiftTarget.id);
+      expect(result?.resolvedBy).toBe('framework');
+    });
+
+    it('does NOT resolve if the Swift method is not @objc-exposed', () => {
+      const swiftTarget = method('animate', 'swift', 'Chart.swift', 10);
+      const ctx = makeContext([swiftTarget], {
+        // Plain `func` without @objc — bridge correctly skips it
+        'Chart.swift':
+          '\n'.repeat(8) +
+          'func animate(xAxisDuration: Double, yAxisDuration: Double) {}\n',
+      });
+      const result = swiftObjcBridgeResolver.resolve(
+        ref('animateWithXAxisDuration:yAxisDuration:', 'objc', 'Caller.m'),
+        ctx
+      );
+      expect(result).toBeNull();
+    });
+
+    it('resolves init selectors to Swift init', () => {
+      const swiftTarget = method('init', 'swift', 'MyClass.swift', 10);
+      const ctx = makeContext([swiftTarget], {
+        'MyClass.swift':
+          '\n'.repeat(8) + '@objc init(name: String, age: Int) {}\n',
+      });
+      const result = swiftObjcBridgeResolver.resolve(
+        ref('initWithName:age:', 'objc', 'Caller.m'),
+        ctx
+      );
+      expect(result?.targetNodeId).toBe(swiftTarget.id);
+    });
+
+    it('returns null for selectors with no derivable Swift candidates that exist', () => {
+      const ctx = makeContext([]);
+      const result = swiftObjcBridgeResolver.resolve(
+        ref('someUnknownThing:', 'objc', 'Caller.m'),
+        ctx
+      );
+      expect(result).toBeNull();
+    });
+  });
+});
diff --git a/__tests__/swift-objc-bridge.test.ts b/__tests__/swift-objc-bridge.test.ts
new file mode 100644
index 000000000..fbff48cc9
--- /dev/null
+++ b/__tests__/swift-objc-bridge.test.ts
@@ -0,0 +1,189 @@
+import { describe, it, expect } from 'vitest';
+import {
+  objcSelectorForSwiftMethod,
+  objcSelectorForSwiftInit,
+  objcAccessorsForSwiftProperty,
+  swiftBaseNamesForObjcSelector,
+  detectExplicitObjcName,
+  isObjcExposed,
+} from '../src/resolution/swift-objc-bridge';
+
+describe('Swift → ObjC selector bridging (auto-name rules)', () => {
+  describe('objcSelectorForSwiftMethod', () => {
+    it('no parameters → bare base name', () => {
+      expect(objcSelectorForSwiftMethod('play', [])).toBe('play');
+    });
+
+    it('single _ param → base + ":"', () => {
+      expect(objcSelectorForSwiftMethod('play', ['_'])).toBe('play:');
+      expect(objcSelectorForSwiftMethod('play', [null])).toBe('play:');
+    });
+
+    it('single labeled param → "baseWithLabel:"', () => {
+      expect(objcSelectorForSwiftMethod('play', ['song'])).toBe('playWithSong:');
+    });
+
+    it('multi-param with leading _ → "base:label2:..."', () => {
+      expect(objcSelectorForSwiftMethod('play', ['_', 'by'])).toBe('play:by:');
+      expect(
+        objcSelectorForSwiftMethod('tableView', ['_', 'didSelectRowAtIndexPath'])
+      ).toBe('tableView:didSelectRowAtIndexPath:');
+    });
+
+    it('multi-param with leading explicit label → "baseWithFirst:rest:"', () => {
+      expect(objcSelectorForSwiftMethod('play', ['song', 'by'])).toBe(
+        'playWithSong:by:'
+      );
+    });
+
+    it('@objc(custom:) overrides the rule literally', () => {
+      expect(
+        objcSelectorForSwiftMethod('whateverName', ['ignored'], 'custom:')
+      ).toBe('custom:');
+    });
+
+    it('returns null on empty base name', () => {
+      expect(objcSelectorForSwiftMethod('', [])).toBeNull();
+    });
+  });
+
+  describe('objcSelectorForSwiftInit', () => {
+    it('init() → "init"', () => {
+      expect(objcSelectorForSwiftInit([], [])).toBe('init');
+    });
+
+    it('init(name:) → "initWithName:"', () => {
+      expect(objcSelectorForSwiftInit(['name'], ['name'])).toBe('initWithName:');
+    });
+
+    it('init(name:, age:) → "initWithName:age:"', () => {
+      expect(objcSelectorForSwiftInit(['name', 'age'], ['name', 'age'])).toBe(
+        'initWithName:age:'
+      );
+    });
+
+    it('init(_ name:) uses internal name → "initWithName:"', () => {
+      expect(objcSelectorForSwiftInit(['_'], ['name'])).toBe('initWithName:');
+    });
+
+    it('@objc(custom) override on init', () => {
+      expect(objcSelectorForSwiftInit(['name'], ['name'], 'custom:')).toBe(
+        'custom:'
+      );
+    });
+  });
+
+  describe('objcAccessorsForSwiftProperty', () => {
+    it('getter = name, setter = setName:', () => {
+      expect(objcAccessorsForSwiftProperty('name')).toEqual({
+        getter: 'name',
+        setter: 'setName:',
+      });
+    });
+
+    it('camelCase → set capitalizes first', () => {
+      expect(objcAccessorsForSwiftProperty('isReady')).toEqual({
+        getter: 'isReady',
+        setter: 'setIsReady:',
+      });
+    });
+
+    it('explicit @objc(custom) overrides getter name', () => {
+      expect(objcAccessorsForSwiftProperty('name', 'displayName')).toEqual({
+        getter: 'displayName',
+        setter: 'setDisplayName:',
+      });
+    });
+  });
+});
+
+describe('ObjC selector → Swift base name candidates (reverse map)', () => {
+  it('bare no-colon selector → itself', () => {
+    expect(swiftBaseNamesForObjcSelector('play')).toEqual(['play']);
+  });
+
+  it('"play:" → ["play"]', () => {
+    expect(swiftBaseNamesForObjcSelector('play:')).toEqual(['play']);
+  });
+
+  it('"playWithSong:" → ["playWithSong", "play"]', () => {
+    expect(swiftBaseNamesForObjcSelector('playWithSong:').sort()).toEqual(
+      ['play', 'playWithSong'].sort()
+    );
+  });
+
+  it('Cocoa-style "objectForKey:" → includes "object"', () => {
+    expect(swiftBaseNamesForObjcSelector('objectForKey:')).toContain('object');
+  });
+
+  it('Cocoa-style "stringWithFormat:" → includes "string"', () => {
+    expect(swiftBaseNamesForObjcSelector('stringWithFormat:')).toContain('string');
+  });
+
+  it('Cocoa-style "imageNamed:inBundle:" → first keyword has no preposition, falls through', () => {
+    // First keyword is `imageNamed` — no With/For/By in it, so candidates is
+    // just the raw keyword. (`Named` is not in our preposition list — keep
+    // it that way, otherwise we over-match on perfectly normal verbs.)
+    expect(swiftBaseNamesForObjcSelector('imageNamed:inBundle:')).toEqual(['imageNamed']);
+  });
+
+  it('"play:by:" → ["play"]', () => {
+    expect(swiftBaseNamesForObjcSelector('play:by:')).toEqual(['play']);
+  });
+
+  it('"playWithSong:by:" → ["playWithSong", "play"]', () => {
+    expect(swiftBaseNamesForObjcSelector('playWithSong:by:').sort()).toEqual(
+      ['play', 'playWithSong'].sort()
+    );
+  });
+
+  it('"initWithName:" → includes "init"', () => {
+    expect(swiftBaseNamesForObjcSelector('initWithName:')).toContain('init');
+  });
+
+  it('"initWithName:age:" → includes "init"', () => {
+    expect(swiftBaseNamesForObjcSelector('initWithName:age:')).toContain('init');
+  });
+
+  it('"setName:" → includes the property name "name"', () => {
+    expect(swiftBaseNamesForObjcSelector('setName:')).toContain('name');
+  });
+
+  it('"tableView:didSelectRowAtIndexPath:" → ["tableView"]', () => {
+    expect(
+      swiftBaseNamesForObjcSelector('tableView:didSelectRowAtIndexPath:')
+    ).toEqual(['tableView']);
+  });
+});
+
+describe('Source-window attribute detection', () => {
+  it('detects literal @objc(custom)', () => {
+    expect(detectExplicitObjcName('  @objc(custom:)\n  func foo() {}')).toBe(
+      'custom:'
+    );
+  });
+
+  it('returns null for plain @objc', () => {
+    expect(detectExplicitObjcName('@objc func foo() {}')).toBeNull();
+  });
+
+  it('returns null when no @objc at all', () => {
+    expect(detectExplicitObjcName('public func foo() {}')).toBeNull();
+  });
+
+  it('isObjcExposed true for @objc', () => {
+    expect(isObjcExposed('@objc func foo() {}')).toBe(true);
+  });
+
+  it('isObjcExposed true for @objc(custom)', () => {
+    expect(isObjcExposed('@objc(custom:) func foo() {}')).toBe(true);
+  });
+
+  it('isObjcExposed false for no annotation', () => {
+    expect(isObjcExposed('public func foo() {}')).toBe(false);
+  });
+
+  it('@nonobjc opts out even if @objc also present (e.g. inside @objcMembers class)', () => {
+    expect(isObjcExposed('@nonobjc @objc func foo() {}')).toBe(false);
+  });
+});
diff --git a/__tests__/symbol-lookup.test.ts b/__tests__/symbol-lookup.test.ts
index d27e157b7..c81aaabd4 100644
--- a/__tests__/symbol-lookup.test.ts
+++ b/__tests__/symbol-lookup.test.ts
@@ -25,8 +25,8 @@ beforeAll(async () => {
 
 function hasSqliteBindings(): boolean {
   try {
-    const Database = require('better-sqlite3');
-    const db = new Database(':memory:');
+    const { DatabaseSync } = require('node:sqlite');
+    const db = new DatabaseSync(':memory:');
     db.close();
     return true;
   } catch {
@@ -75,7 +75,8 @@ describe.skipIf(!HAS_SQLITE)('matchesSymbol — module-qualified lookups (#173)'
   let projectRoot: string;
   let cg: any;
   let handler: any;
-  let findSymbol: (cg: any, s: string) => { node: any; note: string } | null;
+  // findSymbolMatches returns ALL ranked matches; [0] is the resolved/picked one.
+  let findSymbolMatches: (cg: any, s: string) => any[];
   let findAllSymbols: (cg: any, s: string) => { nodes: any[]; note: string };
 
   beforeEach(async () => {
@@ -87,7 +88,7 @@ describe.skipIf(!HAS_SQLITE)('matchesSymbol — module-qualified lookups (#173)'
     });
     await cg.indexAll();
     handler = new ToolHandler(cg);
-    findSymbol = (handler as any).findSymbol.bind(handler);
+    findSymbolMatches = (handler as any).findSymbolMatches.bind(handler);
     findAllSymbols = (handler as any).findAllSymbols.bind(handler);
   });
 
@@ -98,10 +99,11 @@ describe.skipIf(!HAS_SQLITE)('matchesSymbol — module-qualified lookups (#173)'
   });
 
   it('resolves `stage_apply::run` to the run in stage_apply.rs (not stage_detect.rs)', () => {
-    const match = findSymbol(cg, 'stage_apply::run');
-    expect(match).not.toBeNull();
-    expect(match!.node.name).toBe('run');
-    expect(match!.node.filePath).toMatch(/configurator\/stage_apply\.rs$/);
+    const matches = findSymbolMatches(cg, 'stage_apply::run');
+    expect(matches.length).toBeGreaterThan(0);
+    expect(matches[0]!.name).toBe('run');
+    // Every match must be in stage_apply.rs — never stage_detect.rs.
+    for (const n of matches) expect(n.filePath).toMatch(/configurator\/stage_apply\.rs$/);
   });
 
   it('rejects `stage_apply::run` for the same-named function in a different module', () => {
@@ -114,29 +116,29 @@ describe.skipIf(!HAS_SQLITE)('matchesSymbol — module-qualified lookups (#173)'
   });
 
   it('resolves `configurator::stage_apply::run` (multi-level qualifier)', () => {
-    const match = findSymbol(cg, 'configurator::stage_apply::run');
-    expect(match).not.toBeNull();
-    expect(match!.node.name).toBe('run');
-    expect(match!.node.filePath).toMatch(/configurator\/stage_apply\.rs$/);
+    const matches = findSymbolMatches(cg, 'configurator::stage_apply::run');
+    expect(matches.length).toBeGreaterThan(0);
+    expect(matches[0]!.name).toBe('run');
+    expect(matches[0]!.filePath).toMatch(/configurator\/stage_apply\.rs$/);
   });
 
   it('resolves `crate::configurator::stage_apply::run` (Rust path prefix stripped)', () => {
-    const match = findSymbol(cg, 'crate::configurator::stage_apply::run');
-    expect(match).not.toBeNull();
-    expect(match!.node.filePath).toMatch(/configurator\/stage_apply\.rs$/);
+    const matches = findSymbolMatches(cg, 'crate::configurator::stage_apply::run');
+    expect(matches.length).toBeGreaterThan(0);
+    expect(matches[0]!.filePath).toMatch(/configurator\/stage_apply\.rs$/);
   });
 
   it('resolves `configurator/stage_apply` (slash qualifier)', () => {
-    const match = findSymbol(cg, 'configurator/stage_apply/run');
-    expect(match).not.toBeNull();
-    expect(match!.node.filePath).toMatch(/configurator\/stage_apply\.rs$/);
+    const matches = findSymbolMatches(cg, 'configurator/stage_apply/run');
+    expect(matches.length).toBeGreaterThan(0);
+    expect(matches[0]!.filePath).toMatch(/configurator\/stage_apply\.rs$/);
   });
 
   it('does not silently collide bare `run` with `run_due_tasks`', () => {
-    const match = findSymbol(cg, 'run');
-    expect(match).not.toBeNull();
-    // Whatever it picks, it must be an exact-name match, not a partial.
-    expect(match!.node.name).toBe('run');
+    const matches = findSymbolMatches(cg, 'run');
+    expect(matches.length).toBeGreaterThan(0);
+    // Whatever it picks, every match must be an exact-name match, not a partial.
+    for (const n of matches) expect(n.name).toBe('run');
   });
 
   it('aggregates all bare-name `run` matches across modules', () => {
@@ -148,9 +150,22 @@ describe.skipIf(!HAS_SQLITE)('matchesSymbol — module-qualified lookups (#173)'
     expect(all.note).toMatch(/Aggregated|symbols named "run"/);
   });
 
-  it('still returns null for genuinely unknown qualified lookups', () => {
-    const match = findSymbol(cg, 'stage_apply::nonexistent_fn');
-    expect(match).toBeNull();
+  it('still returns nothing for genuinely unknown qualified lookups', () => {
+    const matches = findSymbolMatches(cg, 'stage_apply::nonexistent_fn');
+    expect(matches.length).toBe(0);
+  });
+
+  it('codegraph_node with a `file` hint pins an overloaded name to that file', async () => {
+    // `run` is defined in BOTH stage_apply.rs and stage_detect.rs. A bare lookup
+    // returns both; the `file` hint narrows to the one the caller saw in a trail.
+    const res = await handler.execute('codegraph_node', {
+      symbol: 'run',
+      includeCode: true,
+      file: 'stage_detect.rs',
+    });
+    const text = res.content?.[0]?.text ?? '';
+    expect(text).toMatch(/stage_detect\.rs/);
+    expect(text).not.toMatch(/stage_apply\.rs/);
   });
 });
 
@@ -158,7 +173,7 @@ describe.skipIf(!HAS_SQLITE)('matchesSymbol — dotted lookups (regression for #
   let projectRoot: string;
   let cg: any;
   let handler: any;
-  let findSymbol: (cg: any, s: string) => { node: any; note: string } | null;
+  let findSymbolMatches: (cg: any, s: string) => any[];
 
   beforeEach(async () => {
     projectRoot = tmpRoot();
@@ -166,7 +181,7 @@ describe.skipIf(!HAS_SQLITE)('matchesSymbol — dotted lookups (regression for #
     fs.mkdirSync(src, { recursive: true });
     fs.writeFileSync(
       path.join(src, 'session.ts'),
-      `export class Session {\n  request(): void {}\n}\nexport function request(): void {}\n`
+      `export class Session {\n  request(): void { fetch('x'); }\n}\nexport function request(): void {}\n`
     );
 
     const CodeGraph = (await import('../src/index')).default;
@@ -176,7 +191,7 @@ describe.skipIf(!HAS_SQLITE)('matchesSymbol — dotted lookups (regression for #
     });
     await cg.indexAll();
     handler = new ToolHandler(cg);
-    findSymbol = (handler as any).findSymbol.bind(handler);
+    findSymbolMatches = (handler as any).findSymbolMatches.bind(handler);
   });
 
   afterEach(() => {
@@ -186,9 +201,22 @@ describe.skipIf(!HAS_SQLITE)('matchesSymbol — dotted lookups (regression for #
   });
 
   it('`Session.request` resolves to the method, not the bare function', () => {
-    const match = findSymbol(cg, 'Session.request');
-    expect(match).not.toBeNull();
-    expect(match!.node.kind).toBe('method');
-    expect(match!.node.qualifiedName).toContain('Session::request');
+    const matches = findSymbolMatches(cg, 'Session.request');
+    expect(matches.length).toBeGreaterThan(0);
+    expect(matches[0]!.kind).toBe('method');
+    expect(matches[0]!.qualifiedName).toContain('Session::request');
+  });
+
+  it('codegraph_node on an ambiguous bare name returns ALL overloads with bodies (no guess)', async () => {
+    // `request` is BOTH a method (Session.request) and a free function. The old
+    // behavior returned one + a dead-end "Others:" note, forcing a Read to get
+    // the other overload; now both bodies come back in one call.
+    const res = await handler.execute('codegraph_node', { symbol: 'request', includeCode: true });
+    const text = res.content?.[0]?.text ?? '';
+    expect(text).toContain('2 definitions named "request"');
+    // Both definitions are rendered (method + function), each with a Location.
+    expect(text).toMatch(/\(method\)/);
+    expect(text).toMatch(/\(function\)/);
+    expect((text.match(/\*\*Location:\*\*/g) || []).length).toBeGreaterThanOrEqual(2);
   });
 });
diff --git a/__tests__/sync.test.ts b/__tests__/sync.test.ts
index 374e7788b..708a92a42 100644
--- a/__tests__/sync.test.ts
+++ b/__tests__/sync.test.ts
@@ -281,11 +281,11 @@ describe('Sync Module', () => {
       expect(nodes.length).toBe(0);
     });
 
-    it('should skip files not matching config', async () => {
-      // Create a .js file which doesn't match **/*.ts
+    it('should skip files with unsupported extensions', async () => {
+      // A .txt file has no supported grammar, so sync must not index it.
       fs.writeFileSync(
-        path.join(testDir, 'src', 'ignored.js'),
-        `function ignored() {}`
+        path.join(testDir, 'src', 'notes.txt'),
+        `just some notes`
       );
 
       const result = await cg.sync();
diff --git a/__tests__/ts-field-classification.test.ts b/__tests__/ts-field-classification.test.ts
new file mode 100644
index 000000000..82069a8d2
--- /dev/null
+++ b/__tests__/ts-field-classification.test.ts
@@ -0,0 +1,159 @@
+/**
+ * TS/JS class-field kind classification (#808).
+ *
+ * `public_field_definition` (TS) / `field_definition` (JS) previously
+ * extracted as method-kind nodes unconditionally, so a plain annotated field
+ * (`public fonts: Fonts;`) was reported as a method — misrepresenting class
+ * shape and defeating kind-based filtering (#756 had to work around it).
+ *
+ * Now classification follows the VALUE: arrow-function / function-expression
+ * fields (and HOF-wrapped ones, mirroring resolveBody) stay methods; every
+ * other field is a property. Parity requirements: the property keeps its
+ * type-annotation `references` edge, visibility, and static-ness; method
+ * fields keep walking their bodies (calls still attributed).
+ */
+
+import { describe, it, expect, beforeAll, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { CodeGraph } from '../src';
+import { initGrammars, loadAllGrammars } from '../src/extraction/grammars';
+
+beforeAll(async () => {
+  await initGrammars();
+  await loadAllGrammars();
+});
+
+describe('TS/JS class field classification (#808)', () => {
+  let tmpDir: string | undefined;
+  afterEach(() => {
+    if (tmpDir) fs.rmSync(tmpDir, { recursive: true, force: true });
+    tmpDir = undefined;
+  });
+
+  it('TS: plain fields are properties; function-valued fields are methods', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-808-ts-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'app.ts'),
+      [
+        'declare function throttle(f: unknown, ms: number): unknown;',
+        'class Fonts {}',
+        'class History {}',
+        'class App {',
+        '  public fonts: Fonts;', // plain annotated → property
+        '  private history: History = new History();', // annotated + initializer → property
+        '  interactiveCanvas: HTMLCanvasElement | null = null;', // union type → property
+        '  count = 0;', // plain value → property
+        '  static defaults = { a: 1 };', // object value → property
+        '  onClick = () => { this.run(); };', // arrow field → method
+        '  onScroll = throttle((e: Event) => { this.run(); }, 100);', // HOF-wrapped → method
+        '  handler = function namedFn() {};', // function expression → method
+        '  handleClick(): void {}', // real method
+        '  get value(): number { return 1; }', // getter stays method
+        '  run(): void {}',
+        '}',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+
+      const kindOf = (name: string) =>
+        cg.getNodesByName(name).map((n) => n.kind).sort().join(',');
+
+      expect(kindOf('fonts')).toBe('property');
+      expect(kindOf('history')).toBe('property');
+      expect(kindOf('interactiveCanvas')).toBe('property');
+      expect(kindOf('count')).toBe('property');
+      expect(kindOf('defaults')).toBe('property');
+      expect(kindOf('onClick')).toBe('method');
+      expect(kindOf('onScroll')).toBe('method');
+      expect(kindOf('handler')).toBe('method');
+      expect(kindOf('handleClick')).toBe('method');
+      expect(kindOf('value')).toBe('method');
+
+      // Parity: the property keeps its type-annotation reference edge.
+      const fontsProp = cg.getNodesByName('fonts').find((n) => n.kind === 'property')!;
+      const fontsRefs = cg
+        .getOutgoingEdges(fontsProp.id)
+        .filter((e) => e.kind === 'references')
+        .map((e) => cg.getNode(e.target)?.name);
+      expect(fontsRefs).toContain('Fonts');
+
+      // Parity: visibility survives the property path.
+      expect(fontsProp.visibility).toBe('public');
+      const historyProp = cg.getNodesByName('history').find((n) => n.kind === 'property')!;
+      expect(historyProp.visibility).toBe('private');
+
+      // Parity: arrow-field bodies still walk — onClick calls run.
+      const onClick = cg.getNodesByName('onClick')[0]!;
+      const calls = cg
+        .getOutgoingEdges(onClick.id)
+        .filter((e) => e.kind === 'calls')
+        .map((e) => cg.getNode(e.target)?.name);
+      expect(calls).toContain('run');
+
+      // Signature carries the declared type, C#-style "Type name".
+      expect(fontsProp.signature).toBe('Fonts fonts');
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('JS: field_definition classifies the same way', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-808-js-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'app.js'),
+      [
+        'class App {',
+        '  count = 0;',
+        '  config = { retries: 3 };',
+        '  onClick = () => { this.run(); };',
+        '  run() {}',
+        '}',
+        'module.exports = App;',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      expect(cg.getNodesByName('count')[0]?.kind).toBe('property');
+      expect(cg.getNodesByName('config')[0]?.kind).toBe('property');
+      expect(cg.getNodesByName('onClick')[0]?.kind).toBe('method');
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+
+  it('field initializers still register callbacks (fn-ref scan)', async () => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-808-fnref-'));
+    fs.writeFileSync(
+      path.join(tmpDir, 'main.ts'),
+      [
+        'function onSave(): void {}',
+        'function onLoad(): void {}',
+        'export class Registry {',
+        '  static handlers = { save: onSave, load: onLoad };',
+        '}',
+      ].join('\n')
+    );
+
+    const cg = CodeGraph.initSync(tmpDir);
+    try {
+      await cg.indexAll();
+      const onSave = cg.getNodesByName('onSave')[0]!;
+      const fnRefs = cg
+        .getIncomingEdges(onSave.id)
+        .filter((e) => e.metadata?.fnRef === true);
+      expect(fnRefs.length).toBeGreaterThan(0);
+    } finally {
+      cg.destroy();
+      tmpDir = undefined;
+    }
+  });
+});
diff --git a/__tests__/upgrade.test.ts b/__tests__/upgrade.test.ts
new file mode 100644
index 000000000..ceef23280
--- /dev/null
+++ b/__tests__/upgrade.test.ts
@@ -0,0 +1,409 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  detectInstallMethod,
+  deriveInstallDir,
+  parseSemver,
+  compareVersions,
+  isUpdateAvailable,
+  normalizeVersion,
+  stripV,
+  parseLatestTagFromLocation,
+  reindexAdvisory,
+  runUpgrade,
+  buildWindowsUpgradeScript,
+  NPM_PACKAGE,
+  type InstallMethod,
+  type UpgradeDeps,
+} from '../src/upgrade';
+import { EXTRACTION_VERSION } from '../src/extraction/extraction-version';
+import { CodeGraph } from '../src';
+
+// ---------------------------------------------------------------------------
+// detectInstallMethod — structural detection from the running file's path
+// ---------------------------------------------------------------------------
+
+describe('detectInstallMethod', () => {
+  // A bundle exists if a vendored node + launcher sit next to lib/.
+  function bundleExists(present: Set<string>) {
+    return (p: string) => present.has(p.replace(/\\/g, '/'));
+  }
+
+  it('detects a unix bundle and derives the install dir from the versions/ layout', () => {
+    const root = '/home/u/.codegraph/versions/v0.9.9';
+    const filename = `${root}/lib/dist/bin/codegraph.js`;
+    const present = new Set([`${root}/node`, `${root}/bin/codegraph`, '/home/u/.codegraph']);
+    const m = detectInstallMethod({
+      filename,
+      platform: 'linux',
+      cwd: '/home/u/project',
+      exists: bundleExists(present),
+    });
+    expect(m).toEqual({
+      kind: 'bundle',
+      os: 'unix',
+      bundleRoot: root,
+      installDir: '/home/u/.codegraph',
+    });
+  });
+
+  it('detects a windows bundle and derives the install dir from current\\', () => {
+    const root = 'C:/Users/u/AppData/Local/codegraph/current';
+    const filename = `${root}/lib/dist/bin/codegraph.js`;
+    const present = new Set([`${root}/node.exe`, `${root}/bin/codegraph.cmd`]);
+    const m = detectInstallMethod({
+      filename,
+      platform: 'win32',
+      cwd: 'C:/Users/u/project',
+      exists: bundleExists(present),
+    }) as Extract<InstallMethod, { kind: 'bundle' }>;
+    expect(m.kind).toBe('bundle');
+    expect(m.os).toBe('windows');
+    // win32 path math emits backslashes; compare separator-independently.
+    expect(m.installDir?.replace(/\\/g, '/')).toBe('C:/Users/u/AppData/Local/codegraph');
+  });
+
+  it('detects a global npm install', () => {
+    const filename = '/usr/local/lib/node_modules/@colbymchenry/codegraph/dist/bin/codegraph.js';
+    const m = detectInstallMethod({
+      filename,
+      platform: 'linux',
+      cwd: '/home/u/project',
+      exists: () => false,
+    });
+    expect(m).toEqual({ kind: 'npm', scope: 'global' });
+  });
+
+  it('detects a local (project) npm install as local', () => {
+    const cwd = '/home/u/project';
+    const filename = `${cwd}/node_modules/@colbymchenry/codegraph/dist/bin/codegraph.js`;
+    const m = detectInstallMethod({ filename, platform: 'linux', cwd, exists: () => false });
+    expect(m).toEqual({ kind: 'npm', scope: 'local' });
+  });
+
+  it('detects an npx run from the _npx cache', () => {
+    const filename = '/home/u/.npm/_npx/abc123/node_modules/@colbymchenry/codegraph/dist/bin/codegraph.js';
+    const m = detectInstallMethod({ filename, platform: 'linux', cwd: '/home/u', exists: () => false });
+    expect(m).toEqual({ kind: 'npx' });
+  });
+
+  it('detects a source checkout via sibling package.json + .git', () => {
+    const repo = '/home/u/dev/codegraph';
+    const filename = `${repo}/dist/bin/codegraph.js`;
+    const present = new Set([`${repo}/package.json`, `${repo}/.git`]);
+    const m = detectInstallMethod({
+      filename,
+      platform: 'darwin',
+      cwd: repo,
+      exists: bundleExists(present),
+    });
+    expect(m).toEqual({ kind: 'source', root: repo });
+  });
+
+  it('returns unknown for an unrecognized layout', () => {
+    const m = detectInstallMethod({
+      filename: '/opt/weird/place/codegraph.js',
+      platform: 'linux',
+      cwd: '/tmp',
+      exists: () => false,
+    });
+    expect(m.kind).toBe('unknown');
+  });
+});
+
+describe('deriveInstallDir', () => {
+  it('unix: returns the dir above versions/', () => {
+    expect(deriveInstallDir('/a/b/.codegraph/versions/v1.2.3', 'unix', () => true)).toBe('/a/b/.codegraph');
+  });
+  it('unix: null when not under versions/', () => {
+    expect(deriveInstallDir('/a/b/somewhere', 'unix', () => true)).toBeNull();
+  });
+  it('windows: returns the parent of current\\', () => {
+    expect(deriveInstallDir('C:/x/codegraph/current', 'windows', () => true)?.replace(/\\/g, '/')).toBe('C:/x/codegraph');
+  });
+  it('windows: null when basename is not current', () => {
+    expect(deriveInstallDir('C:/x/codegraph/v1', 'windows', () => true)).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// version helpers
+// ---------------------------------------------------------------------------
+
+describe('version helpers', () => {
+  it('parseSemver handles v-prefix and prerelease', () => {
+    expect(parseSemver('v1.2.3')).toEqual({ major: 1, minor: 2, patch: 3, pre: null });
+    expect(parseSemver('1.2.3-rc.1')).toEqual({ major: 1, minor: 2, patch: 3, pre: 'rc.1' });
+    expect(parseSemver('not-a-version')).toBeNull();
+  });
+
+  it('compareVersions orders correctly incl. prerelease < release', () => {
+    expect(compareVersions('1.0.1', '1.0.0')).toBeGreaterThan(0);
+    expect(compareVersions('1.0.0', '1.1.0')).toBeLessThan(0);
+    expect(compareVersions('v2.0.0', '2.0.0')).toBe(0);
+    expect(compareVersions('1.0.0-rc.1', '1.0.0')).toBeLessThan(0);
+  });
+
+  it('isUpdateAvailable compares, and falls back to string-inequality for unparseable', () => {
+    expect(isUpdateAvailable('0.9.8', '0.9.9')).toBe(true);
+    expect(isUpdateAvailable('0.9.9', '0.9.9')).toBe(false);
+    expect(isUpdateAvailable('0.9.9', '0.9.8')).toBe(false);
+    // dev sentinel can't parse → any difference means "update available"
+    expect(isUpdateAvailable('0.0.0-unknown', '0.9.9')).toBe(true);
+  });
+
+  it('normalizeVersion / stripV round-trip', () => {
+    expect(normalizeVersion('0.9.9')).toBe('v0.9.9');
+    expect(normalizeVersion('v0.9.9')).toBe('v0.9.9');
+    expect(stripV('v0.9.9')).toBe('0.9.9');
+    expect(stripV('0.9.9')).toBe('0.9.9');
+  });
+
+  it('parseLatestTagFromLocation extracts the tag from a releases redirect', () => {
+    expect(parseLatestTagFromLocation('https://github.com/colbymchenry/codegraph/releases/tag/v0.9.9')).toBe('v0.9.9');
+    expect(parseLatestTagFromLocation('https://github.com/o/r/releases/tag/v1.2.3?foo=bar')).toBe('v1.2.3');
+    expect(parseLatestTagFromLocation(undefined)).toBeNull();
+    expect(parseLatestTagFromLocation('https://github.com/o/r/releases')).toBeNull();
+  });
+
+  it('reindexAdvisory mentions the refresh commands', () => {
+    const a = reindexAdvisory();
+    expect(a).toContain('codegraph sync');
+    expect(a).toContain('codegraph index -f');
+  });
+
+  it('buildWindowsUpgradeScript targets the right asset per arch and renames-not-deletes the exe', () => {
+    const arm = buildWindowsUpgradeScript('C:\\cg\\current', 'v1.2.3', 'arm64');
+    expect(arm).toContain('releases/download/v1.2.3/codegraph-win32-arm64.zip');
+    expect(arm).toContain("$dest='C:\\cg\\current'");
+    expect(arm).toContain('Rename-Item'); // never Remove-Item on the locked exe
+    expect(arm).not.toMatch(/Remove-Item[^;]*\$dest'?\s*;/); // doesn't delete current\
+    const x64 = buildWindowsUpgradeScript('C:\\cg\\current', 'v1.2.3', 'x64');
+    expect(x64).toContain('codegraph-win32-x64.zip');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// runUpgrade orchestration — mocked side-effects
+// ---------------------------------------------------------------------------
+
+interface Calls {
+  runs: Array<{ cmd: string; args: string[]; env?: NodeJS.ProcessEnv }>;
+  logs: string[];
+  errors: string[];
+}
+
+function makeDeps(
+  overrides: Partial<UpgradeDeps> & { method: InstallMethod; currentVersion: string },
+  runExit = 0
+): { deps: UpgradeDeps; calls: Calls } {
+  const calls: Calls = { runs: [], logs: [], errors: [] };
+  const deps: UpgradeDeps = {
+    currentVersion: overrides.currentVersion,
+    method: overrides.method,
+    resolveLatest: overrides.resolveLatest ?? (async () => 'v0.9.9'),
+    run: (cmd, args, env) => {
+      calls.runs.push({ cmd, args, env });
+      return runExit;
+    },
+    hasCommand: overrides.hasCommand ?? ((c) => c === 'curl'),
+    log: (m) => calls.logs.push(m),
+    warn: (m) => calls.logs.push(m),
+    error: (m) => calls.errors.push(m),
+    platform: overrides.platform ?? 'linux',
+  };
+  return { deps, calls };
+}
+
+/** Decode a `-EncodedCommand` base64 (UTF-16LE) payload back to its script. */
+function decodeEncodedCommand(args: string[]): string {
+  const i = args.indexOf('-EncodedCommand');
+  if (i < 0) throw new Error('no -EncodedCommand in args');
+  return Buffer.from(args[i + 1]!, 'base64').toString('utf16le');
+}
+
+describe('runUpgrade', () => {
+  it('does nothing when already up to date', async () => {
+    const { deps, calls } = makeDeps({ method: { kind: 'npm', scope: 'global' }, currentVersion: '0.9.9' });
+    const code = await runUpgrade({}, deps);
+    expect(code).toBe(0);
+    expect(calls.runs).toHaveLength(0);
+    expect(calls.logs.join('\n')).toMatch(/up to date/i);
+  });
+
+  it('--check reports an available update without running anything', async () => {
+    const { deps, calls } = makeDeps({
+      method: { kind: 'npm', scope: 'global' },
+      currentVersion: '0.9.8',
+    });
+    const code = await runUpgrade({ check: true }, deps);
+    expect(code).toBe(0);
+    expect(calls.runs).toHaveLength(0);
+    expect(calls.logs.join('\n')).toMatch(/update is available/i);
+  });
+
+  it('unix bundle: runs the installer via sh with the derived install dir', async () => {
+    const { deps, calls } = makeDeps({
+      method: { kind: 'bundle', os: 'unix', bundleRoot: '/h/.codegraph/versions/v0.9.8', installDir: '/h/.codegraph' },
+      currentVersion: '0.9.8',
+    });
+    const code = await runUpgrade({}, deps);
+    expect(code).toBe(0);
+    expect(calls.runs).toHaveLength(1);
+    expect(calls.runs[0].cmd).toBe('sh');
+    expect(calls.runs[0].args[0]).toBe('-c');
+    expect(calls.runs[0].args[1]).toContain('curl -fsSL');
+    expect(calls.runs[0].args[1]).toContain('| sh');
+    expect(calls.runs[0].env?.CODEGRAPH_INSTALL_DIR).toBe('/h/.codegraph');
+    expect(calls.logs.join('\n')).toMatch(/codegraph sync/); // re-index advisory printed
+  });
+
+  it('unix bundle: falls back to wget, and errors when neither downloader exists', async () => {
+    const { deps, calls } = makeDeps({
+      method: { kind: 'bundle', os: 'unix', bundleRoot: '/h/.codegraph/versions/v0.9.8', installDir: null },
+      currentVersion: '0.9.8',
+      hasCommand: () => false,
+    });
+    const code = await runUpgrade({}, deps);
+    expect(code).toBe(1);
+    expect(calls.runs).toHaveLength(0);
+    expect(calls.errors.join('\n')).toMatch(/curl nor wget/i);
+  });
+
+  it('windows bundle: runs a synchronous in-place (rename + extract) powershell upgrade', async () => {
+    const { deps, calls } = makeDeps({
+      method: { kind: 'bundle', os: 'windows', bundleRoot: 'C:/x/codegraph/current', installDir: 'C:/x/codegraph' },
+      currentVersion: '0.9.8',
+      platform: 'win32',
+    });
+    const code = await runUpgrade({}, deps);
+    expect(code).toBe(0);
+    expect(calls.runs).toHaveLength(1);
+    expect(calls.runs[0].cmd).toBe('powershell.exe');
+    const decoded = decodeEncodedCommand(calls.runs[0].args);
+    // Downloads the right asset, renames the locked exe aside, copies over current\.
+    expect(decoded).toContain('releases/download/v0.9.9/codegraph-win32-');
+    expect(decoded).toContain('Rename-Item');
+    expect(decoded).toContain('node.exe.old-');
+    expect(decoded).toContain('Copy-Item');
+  });
+
+  it('windows bundle: a non-zero installer exit is a failure', async () => {
+    const { deps, calls } = makeDeps(
+      {
+        method: { kind: 'bundle', os: 'windows', bundleRoot: 'C:/x/codegraph/current', installDir: 'C:/x/codegraph' },
+        currentVersion: '0.9.8',
+        platform: 'win32',
+      },
+      1
+    );
+    const code = await runUpgrade({}, deps);
+    expect(code).toBe(1);
+    expect(calls.errors.join('\n')).toMatch(/exited with code/i);
+  });
+
+  it('npm global: shells out to npm install -g @pkg@latest', async () => {
+    const { deps, calls } = makeDeps({
+      method: { kind: 'npm', scope: 'global' },
+      currentVersion: '0.9.8',
+    });
+    const code = await runUpgrade({}, deps);
+    expect(code).toBe(0);
+    expect(calls.runs[0].cmd).toBe('npm');
+    expect(calls.runs[0].args).toEqual(['install', '-g', `${NPM_PACKAGE}@latest`]);
+  });
+
+  it('npm on win32 uses npm.cmd', async () => {
+    const { deps, calls } = makeDeps({
+      method: { kind: 'npm', scope: 'global' },
+      currentVersion: '0.9.8',
+      platform: 'win32',
+    });
+    await runUpgrade({}, deps);
+    expect(calls.runs[0].cmd).toBe('npm.cmd');
+  });
+
+  it('npm: a pinned version is passed through as @<version>', async () => {
+    const { deps, calls } = makeDeps({
+      method: { kind: 'npm', scope: 'global' },
+      currentVersion: '0.9.9',
+    });
+    await runUpgrade({ version: '0.9.8' }, deps);
+    // npm spec carries no leading "v".
+    expect(calls.runs[0].args).toEqual(['install', '-g', `${NPM_PACKAGE}@0.9.8`]);
+  });
+
+  it('npm: surfaces a non-zero exit as failure', async () => {
+    const { deps, calls } = makeDeps(
+      { method: { kind: 'npm', scope: 'global' }, currentVersion: '0.9.8' },
+      1
+    );
+    const code = await runUpgrade({}, deps);
+    expect(code).toBe(1);
+    expect(calls.errors.join('\n')).toMatch(/npm exited/i);
+  });
+
+  it('npx: nothing to upgrade', async () => {
+    const { deps, calls } = makeDeps({ method: { kind: 'npx' }, currentVersion: '0.9.8' });
+    const code = await runUpgrade({}, deps);
+    expect(code).toBe(0);
+    expect(calls.runs).toHaveLength(0);
+    expect(calls.logs.join('\n')).toMatch(/nothing to upgrade/i);
+  });
+
+  it('source: tells the user to git pull, runs nothing', async () => {
+    const { deps, calls } = makeDeps({
+      method: { kind: 'source', root: '/dev/codegraph' },
+      currentVersion: '0.9.8',
+    });
+    const code = await runUpgrade({}, deps);
+    expect(code).toBe(0);
+    expect(calls.runs).toHaveLength(0);
+    expect(calls.logs.join('\n')).toMatch(/git pull/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Re-index staleness — real index, real metadata stamp
+// ---------------------------------------------------------------------------
+
+describe('index extraction-version stamp / isIndexStale', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-upgrade-stamp-'));
+  });
+  afterEach(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('stamps the current extraction version on full index and is not stale', async () => {
+    fs.writeFileSync(path.join(dir, 'a.ts'), 'export function hello() { return 1; }\n');
+    const cg = await CodeGraph.init(dir, { index: false });
+    // No index yet → not stale (nothing to refresh).
+    expect(cg.isIndexStale()).toBe(false);
+
+    await cg.indexAll();
+    const info = cg.getIndexBuildInfo();
+    expect(info.extractionVersion).toBe(EXTRACTION_VERSION);
+    expect(typeof info.version).toBe('string');
+    expect(cg.isIndexStale()).toBe(false);
+    cg.destroy();
+  });
+
+  it('flags an index stamped by an older extraction version as stale', async () => {
+    fs.writeFileSync(path.join(dir, 'a.ts'), 'export function hello() { return 1; }\n');
+    const cg = await CodeGraph.init(dir, { index: false });
+    await cg.indexAll();
+
+    // Simulate an index built by an older engine.
+    (cg as unknown as { queries: { setMetadata(k: string, v: string): void } }).queries.setMetadata(
+      'indexed_with_extraction_version',
+      String(EXTRACTION_VERSION - 1)
+    );
+    expect(cg.isIndexStale()).toBe(true);
+    cg.destroy();
+  });
+});
diff --git a/__tests__/wasm-runtime-flags.test.ts b/__tests__/wasm-runtime-flags.test.ts
new file mode 100644
index 000000000..a4dae8bba
--- /dev/null
+++ b/__tests__/wasm-runtime-flags.test.ts
@@ -0,0 +1,87 @@
+/**
+ * WASM runtime flags — the workaround for the V8 turboshaft WASM Zone OOM
+ * (`Fatal process out of memory: Zone`) that crashed `codegraph index` on large
+ * polyglot repos under Node >= 22. See issues #293 and #298.
+ *
+ * The crash was reproduced with the real indexer on the bundled Node 24 runtime;
+ * empirically only `--liftoff-only` prevents it (`--no-wasm-tier-up` /
+ * `--no-wasm-dynamic-tiering` do not), and the flag must be on node's command
+ * line — `setFlagsFromString`, worker `execArgv`, and `NODE_OPTIONS` all fail.
+ * These tests pin that contract so it can't silently regress.
+ */
+import { describe, it, expect } from 'vitest';
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import {
+  WASM_RUNTIME_FLAGS,
+  processHasWasmRuntimeFlags,
+  buildRelaunchArgv,
+} from '../src/extraction/wasm-runtime-flags';
+
+describe('WASM_RUNTIME_FLAGS', () => {
+  it('pins --liftoff-only (the only flag shown to stop the turboshaft Zone OOM)', () => {
+    // On Node 24, --no-wasm-tier-up and --no-wasm-dynamic-tiering both still
+    // crash; only --liftoff-only forces grammars onto the Liftoff baseline and
+    // off the optimizing tier. Pin it so it can't be swapped for an ineffective
+    // flag.
+    expect(WASM_RUNTIME_FLAGS).toContain('--liftoff-only');
+  });
+
+  it('every flag is a real, accepted flag on the running Node/V8 runtime', () => {
+    // node rejects unknown CLI flags at startup, so a renamed/removed flag would
+    // break the bundled launcher and make the relaunch guard a silent no-op.
+    // Prove each flag actually launches node here.
+    const res = spawnSync(
+      process.execPath,
+      [...WASM_RUNTIME_FLAGS, '-e', 'process.exit(0)'],
+      { encoding: 'utf8' }
+    );
+    expect(res.status, `node rejected ${WASM_RUNTIME_FLAGS.join(' ')}:\n${res.stderr}`).toBe(0);
+  });
+});
+
+describe('processHasWasmRuntimeFlags', () => {
+  it('is true only when every required flag is present', () => {
+    expect(processHasWasmRuntimeFlags(['--liftoff-only'])).toBe(true);
+    expect(processHasWasmRuntimeFlags(['--liftoff-only', '--enable-source-maps'])).toBe(true);
+  });
+
+  it('is false when the flags are absent', () => {
+    expect(processHasWasmRuntimeFlags([])).toBe(false);
+    expect(processHasWasmRuntimeFlags(['--max-old-space-size=4096'])).toBe(false);
+  });
+});
+
+describe('buildRelaunchArgv', () => {
+  it('places the wasm flags first, then the script and its args', () => {
+    expect(buildRelaunchArgv('/x/codegraph.js', ['index', '/repo'], [])).toEqual([
+      '--liftoff-only',
+      '/x/codegraph.js',
+      'index',
+      '/repo',
+    ]);
+  });
+
+  it('preserves other existing node flags without duplicating ours', () => {
+    expect(
+      buildRelaunchArgv('/x/codegraph.js', ['status'], ['--liftoff-only', '--enable-source-maps'])
+    ).toEqual(['--liftoff-only', '--enable-source-maps', '/x/codegraph.js', 'status']);
+  });
+
+  it('produces an argv that actually launches node WITH the flag applied', () => {
+    // End-to-end proof of the delivery mechanism without needing the crash:
+    // run the constructed argv and confirm the child sees the flag in execArgv.
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-relaunch-'));
+    try {
+      const harness = path.join(dir, 'harness.cjs');
+      fs.writeFileSync(harness, 'process.stdout.write(JSON.stringify(process.execArgv));');
+      const res = spawnSync(process.execPath, buildRelaunchArgv(harness, []), { encoding: 'utf8' });
+      expect(res.status, res.stderr).toBe(0);
+      expect(JSON.parse(res.stdout)).toContain('--liftoff-only');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/__tests__/watch-policy.test.ts b/__tests__/watch-policy.test.ts
index ee50d8c90..5cb92ce72 100644
--- a/__tests__/watch-policy.test.ts
+++ b/__tests__/watch-policy.test.ts
@@ -12,7 +12,6 @@ import * as path from 'path';
 import * as os from 'os';
 import { watchDisabledReason } from '../src/sync/watch-policy';
 import { FileWatcher } from '../src/sync/watcher';
-import type { CodeGraphConfig } from '../src/types';
 
 describe('watchDisabledReason', () => {
   it('returns a reason when CODEGRAPH_NO_WATCH=1', () => {
@@ -63,18 +62,6 @@ describe('watchDisabledReason', () => {
 describe('FileWatcher honors the watch policy', () => {
   let testDir: string;
 
-  const baseConfig: CodeGraphConfig = {
-    version: 1,
-    rootDir: '.',
-    include: ['**/*.ts'],
-    exclude: ['**/node_modules/**'],
-    languages: [],
-    frameworks: [],
-    maxFileSize: 1024 * 1024,
-    extractDocstrings: true,
-    trackCallSites: true,
-  };
-
   afterEach(() => {
     delete process.env.CODEGRAPH_NO_WATCH;
     if (testDir && fs.existsSync(testDir)) {
@@ -87,7 +74,7 @@ describe('FileWatcher honors the watch policy', () => {
     process.env.CODEGRAPH_NO_WATCH = '1';
 
     const syncFn = vi.fn().mockResolvedValue({ filesChanged: 0, durationMs: 0 });
-    const watcher = new FileWatcher(testDir, baseConfig, syncFn);
+    const watcher = new FileWatcher(testDir, syncFn);
 
     expect(watcher.start()).toBe(false);
     expect(watcher.isActive()).toBe(false);
diff --git a/__tests__/watcher.test.ts b/__tests__/watcher.test.ts
index f3638e6df..b372fc3d6 100644
--- a/__tests__/watcher.test.ts
+++ b/__tests__/watcher.test.ts
@@ -2,23 +2,44 @@
  * FileWatcher Tests
  *
  * Tests for the file watcher that auto-syncs on changes.
+ *
+ * **Why inert mode + a synthetic event seam**: the watcher now uses Node's
+ * native `fs.watch` (recursive on macOS/Windows, per-directory on Linux).
+ * Under parallel vitest the OS watch subsystems (FSEvents / inotify) serve
+ * many test files at once and event-delivery latency becomes non-deterministic
+ * — a real fs change made in `beforeEach` can even leak into a later "should
+ * NOT sync" assertion. So the unit tests construct the watcher with
+ * `inertForTests: true` (no OS watcher installed) and drive its filter →
+ * pendingFiles → debounce pipeline directly via
+ * `__emitWatchEventForTests(root, relPath)` — deterministic, the same
+ * convergence point a real event reaches. The debounce timer itself is the
+ * real `setTimeout` (the unit under test). One end-to-end test ("auto-sync …
+ * real fs.watch") runs the genuine native watcher against a real file write.
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { FileWatcher } from '../src/sync/watcher';
-import type { CodeGraphConfig } from '../src/types';
+import {
+  FileWatcher,
+  LockUnavailableError,
+  __emitWatchEventForTests,
+  type WatchOptions,
+} from '../src/sync/watcher';
 import CodeGraph from '../src/index';
 
+type SyncFn = () => Promise<{ filesChanged: number; durationMs: number }>;
+
 /**
- * Helper to wait for a condition with timeout
+ * Helper to wait for a condition with timeout. Used for assertions that depend
+ * on the debounce timer (real setTimeout) firing, or on the real watcher's
+ * event delivery in the end-to-end test.
  */
 function waitFor(
   condition: () => boolean,
-  timeoutMs = 10000,
-  intervalMs = 100
+  timeoutMs = 2000,
+  intervalMs = 25
 ): Promise<void> {
   return new Promise((resolve, reject) => {
     const start = Date.now();
@@ -34,17 +55,10 @@ function waitFor(
 describe('FileWatcher', () => {
   let testDir: string;
 
-  const baseConfig: CodeGraphConfig = {
-    version: 1,
-    rootDir: '.',
-    include: ['**/*.ts', '**/*.js'],
-    exclude: ['**/node_modules/**', '**/dist/**'],
-    languages: [],
-    frameworks: [],
-    maxFileSize: 1024 * 1024,
-    extractDocstrings: true,
-    trackCallSites: true,
-  };
+  // Inert by default — unit tests drive events via __emitWatchEventForTests
+  // and never depend on real OS watch delivery.
+  const newWatcher = (syncFn: SyncFn, opts: WatchOptions = {}) =>
+    new FileWatcher(testDir, syncFn, { inertForTests: true, ...opts });
 
   beforeEach(() => {
     testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'codegraph-watcher-'));
@@ -63,7 +77,7 @@ describe('FileWatcher', () => {
   describe('start/stop lifecycle', () => {
     it('should start and stop without errors', () => {
       const syncFn = vi.fn().mockResolvedValue({ filesChanged: 0, durationMs: 0 });
-      const watcher = new FileWatcher(testDir, baseConfig, syncFn);
+      const watcher = newWatcher(syncFn);
 
       const started = watcher.start();
       expect(started).toBe(true);
@@ -75,7 +89,7 @@ describe('FileWatcher', () => {
 
     it('should be idempotent on double start', () => {
       const syncFn = vi.fn().mockResolvedValue({ filesChanged: 0, durationMs: 0 });
-      const watcher = new FileWatcher(testDir, baseConfig, syncFn);
+      const watcher = newWatcher(syncFn);
 
       expect(watcher.start()).toBe(true);
       expect(watcher.start()).toBe(true); // Should not throw
@@ -86,11 +100,12 @@ describe('FileWatcher', () => {
 
     it('should be idempotent on double stop', () => {
       const syncFn = vi.fn().mockResolvedValue({ filesChanged: 0, durationMs: 0 });
-      const watcher = new FileWatcher(testDir, baseConfig, syncFn);
+      const watcher = newWatcher(syncFn);
 
       watcher.start();
       watcher.stop();
       watcher.stop(); // Should not throw
+
       expect(watcher.isActive()).toBe(false);
     });
   });
@@ -98,15 +113,14 @@ describe('FileWatcher', () => {
   describe('debounced sync', () => {
     it('should trigger sync after file change', async () => {
       const syncFn = vi.fn().mockResolvedValue({ filesChanged: 1, durationMs: 10 });
-      const watcher = new FileWatcher(testDir, baseConfig, syncFn, { debounceMs: 200 });
+      const watcher = newWatcher(syncFn, { debounceMs: 200 });
 
       watcher.start();
+      await watcher.waitUntilReady();
+      __emitWatchEventForTests(testDir, 'src/new.ts');
 
-      // Create a new file
-      fs.writeFileSync(path.join(testDir, 'src', 'new.ts'), 'export const y = 2;');
-
-      // Wait for debounced sync to fire
-      await waitFor(() => syncFn.mock.calls.length > 0, 5000);
+      // Wait for debounced sync to fire (real timer; 200ms + epsilon).
+      await waitFor(() => syncFn.mock.calls.length > 0);
       expect(syncFn).toHaveBeenCalled();
 
       watcher.stop();
@@ -114,23 +128,23 @@ describe('FileWatcher', () => {
 
     it('should debounce rapid changes into a single sync', async () => {
       const syncFn = vi.fn().mockResolvedValue({ filesChanged: 1, durationMs: 10 });
-      const watcher = new FileWatcher(testDir, baseConfig, syncFn, { debounceMs: 500 });
+      const watcher = newWatcher(syncFn, { debounceMs: 400 });
 
       watcher.start();
+      await watcher.waitUntilReady();
 
-      // Rapid-fire changes
+      // Rapid-fire synthesized changes — each call resets the debounce timer.
+      // Spacing them tighter than the debounce window proves the debounce
+      // collapses them into one syncFn call.
       for (let i = 0; i < 5; i++) {
-        fs.writeFileSync(
-          path.join(testDir, 'src', `file${i}.ts`),
-          `export const v${i} = ${i};`
-        );
+        __emitWatchEventForTests(testDir, `src/file${i}.ts`);
         await new Promise((r) => setTimeout(r, 50));
       }
 
-      // Wait for the single debounced sync
-      await waitFor(() => syncFn.mock.calls.length > 0, 5000);
+      // Wait for the single debounced sync.
+      await waitFor(() => syncFn.mock.calls.length > 0);
 
-      // Should have been called once (debounced), not 5 times
+      // Should have been called once (debounced), not 5 times.
       expect(syncFn.mock.calls.length).toBe(1);
 
       watcher.stop();
@@ -140,19 +154,17 @@ describe('FileWatcher', () => {
   describe('filtering', () => {
     it('should ignore files not matching include patterns', async () => {
       const syncFn = vi.fn().mockResolvedValue({ filesChanged: 0, durationMs: 0 });
-      const watcher = new FileWatcher(testDir, baseConfig, syncFn, { debounceMs: 200 });
+      const watcher = newWatcher(syncFn, { debounceMs: 200 });
 
       watcher.start();
+      await watcher.waitUntilReady();
 
-      // Let watcher settle — fs.watch may fire residual events from beforeEach
-      await new Promise((r) => setTimeout(r, 400));
-      syncFn.mockClear();
-
-      // Create a file that doesn't match include patterns
-      fs.writeFileSync(path.join(testDir, 'src', 'readme.md'), '# Hello');
+      // A non-source-file event — FileWatcher's `isSourceFile` gate must drop
+      // it before scheduling sync.
+      __emitWatchEventForTests(testDir, 'src/readme.md');
 
-      // Wait a bit longer than debounce — sync should NOT trigger
-      await new Promise((r) => setTimeout(r, 500));
+      // Wait a bit longer than debounce — sync should NOT trigger.
+      await new Promise((r) => setTimeout(r, 400));
       expect(syncFn).not.toHaveBeenCalled();
 
       watcher.stop();
@@ -160,22 +172,148 @@ describe('FileWatcher', () => {
 
     it('should ignore .codegraph directory changes', async () => {
       const syncFn = vi.fn().mockResolvedValue({ filesChanged: 0, durationMs: 0 });
-      const watcher = new FileWatcher(testDir, baseConfig, syncFn, { debounceMs: 200 });
+      const watcher = newWatcher(syncFn, { debounceMs: 200 });
 
       watcher.start();
+      await watcher.waitUntilReady();
+
+      // A .codegraph event — FileWatcher's `isAlwaysIgnored` filter must drop
+      // it before scheduling sync.
+      __emitWatchEventForTests(testDir, '.codegraph/db.sqlite');
 
-      // Let watcher settle — fs.watch may fire residual events from beforeEach
       await new Promise((r) => setTimeout(r, 400));
-      syncFn.mockClear();
+      expect(syncFn).not.toHaveBeenCalled();
 
-      // Simulate a .codegraph directory change
-      const cgDir = path.join(testDir, '.codegraph');
-      fs.mkdirSync(cgDir, { recursive: true });
-      fs.writeFileSync(path.join(cgDir, 'db.sqlite'), 'fake');
+      watcher.stop();
+    });
 
-      // Wait — sync should NOT trigger
-      await new Promise((r) => setTimeout(r, 500));
-      expect(syncFn).not.toHaveBeenCalled();
+    it('should drop ignored/non-source paths but sync real source edits', async () => {
+      const syncFn = vi.fn().mockResolvedValue({ filesChanged: 0, durationMs: 0 });
+      const watcher = newWatcher(syncFn, { debounceMs: 200 });
+      watcher.start();
+      await watcher.waitUntilReady();
+
+      // node_modules is in the default-ignore set (#407) → dropped by the
+      // ignore matcher even without a .gitignore.
+      __emitWatchEventForTests(testDir, 'node_modules/dep/index.js');
+      // A normal source file still schedules sync (positive control).
+      __emitWatchEventForTests(testDir, 'src/live.ts');
+      await waitFor(() => syncFn.mock.calls.length > 0);
+      expect(syncFn).toHaveBeenCalled();
+
+      watcher.stop();
+    });
+  });
+
+  describe('pending file tracking (#403)', () => {
+    it('should expose edited paths via getPendingFiles before sync fires', async () => {
+      // Slow debounce — pending entries are visible until the debounce fires.
+      // The synthetic event is synchronous, so we can assert immediately.
+      const syncFn = vi.fn().mockResolvedValue({ filesChanged: 1, durationMs: 10 });
+      const watcher = newWatcher(syncFn, { debounceMs: 2000 });
+      watcher.start();
+      await watcher.waitUntilReady();
+
+      expect(watcher.getPendingFiles()).toEqual([]);
+
+      __emitWatchEventForTests(testDir, 'src/pending.ts');
+
+      const pending = watcher.getPendingFiles();
+      const paths = pending.map((p) => p.path);
+      expect(paths).toContain('src/pending.ts');
+      const entry = pending.find((p) => p.path === 'src/pending.ts')!;
+      expect(entry.firstSeenMs).toBeGreaterThan(0);
+      expect(entry.lastSeenMs).toBeGreaterThanOrEqual(entry.firstSeenMs);
+      // No sync running yet → indexing flag is false.
+      expect(entry.indexing).toBe(false);
+
+      watcher.stop();
+    });
+
+    it('should clear an entry only after a successful sync absorbing that edit', async () => {
+      const syncFn = vi.fn().mockResolvedValue({ filesChanged: 1, durationMs: 10 });
+      const watcher = newWatcher(syncFn, { debounceMs: 200 });
+      watcher.start();
+      await watcher.waitUntilReady();
+
+      __emitWatchEventForTests(testDir, 'src/fresh.ts');
+
+      // Watcher saw the change → pendingFiles has the entry IMMEDIATELY.
+      expect(watcher.getPendingFiles().some((p) => p.path === 'src/fresh.ts')).toBe(true);
+
+      // Wait through debounce + sync; the entry should drop out.
+      await waitFor(() => syncFn.mock.calls.length > 0);
+      await waitFor(() => !watcher.getPendingFiles().some((p) => p.path === 'src/fresh.ts'));
+
+      expect(watcher.getPendingFiles()).toEqual([]);
+      watcher.stop();
+    });
+
+    it('should keep entries unchanged when sync fails (rescheduled work sees the same set)', async () => {
+      // No initial-scan-triggered sync, so syncFn outcomes line up 1:1 with
+      // explicit events.
+      const syncFn = vi
+        .fn()
+        .mockRejectedValueOnce(new Error('boom'))                  // first sync rejects
+        .mockResolvedValueOnce({ filesChanged: 1, durationMs: 10 }); // retry succeeds
+      const onSyncError = vi.fn();
+      const watcher = newWatcher(syncFn, { debounceMs: 100, onSyncError });
+      watcher.start();
+      await watcher.waitUntilReady();
+
+      __emitWatchEventForTests(testDir, 'src/will-fail.ts');
+
+      // Wait for the sync to reject.
+      await waitFor(() => onSyncError.mock.calls.length > 0);
+
+      // The file is STILL in pendingFiles — failure didn't drop it.
+      const after = watcher.getPendingFiles();
+      expect(after.some((p) => p.path === 'src/will-fail.ts')).toBe(true);
+
+      // Retry resolves automatically; entry clears.
+      await waitFor(
+        () => !watcher.getPendingFiles().some((p) => p.path === 'src/will-fail.ts'),
+      );
+
+      watcher.stop();
+    });
+
+    it('should retain pending files and retry when syncFn throws LockUnavailableError (#449)', async () => {
+      // CodeGraph.watch() converts the cross-process lock-failure no-op
+      // into LockUnavailableError so the watcher's retry path picks it up
+      // instead of falsely clearing pendingFiles. This test exercises the
+      // contract directly.
+      const syncFn = vi
+        .fn()
+        .mockRejectedValueOnce(new LockUnavailableError())
+        .mockResolvedValueOnce({ filesChanged: 1, durationMs: 10 });
+      const onSyncComplete = vi.fn();
+      const onSyncError = vi.fn();
+      const watcher = newWatcher(syncFn, {
+        debounceMs: 100,
+        onSyncComplete,
+        onSyncError,
+      });
+      watcher.start();
+      await watcher.waitUntilReady();
+
+      __emitWatchEventForTests(testDir, 'src/locked.ts');
+
+      await waitFor(() => syncFn.mock.calls.length >= 1);
+      expect(watcher.getPendingFiles().some((p) => p.path === 'src/locked.ts')).toBe(true);
+      // A held-lock no-op is not a sync failure — onSyncError stays quiet
+      // so a long-running external indexer doesn't spam stderr every cycle.
+      expect(onSyncError).not.toHaveBeenCalled();
+      expect(onSyncComplete).not.toHaveBeenCalled();
+
+      await waitFor(() => syncFn.mock.calls.length >= 2);
+      await waitFor(
+        () => !watcher.getPendingFiles().some((p) => p.path === 'src/locked.ts'),
+      );
+
+      expect(onSyncComplete).toHaveBeenCalledTimes(1);
+      expect(onSyncComplete).toHaveBeenCalledWith({ filesChanged: 1, durationMs: 10 });
+      expect(onSyncError).not.toHaveBeenCalled();
 
       watcher.stop();
     });
@@ -185,16 +323,16 @@ describe('FileWatcher', () => {
     it('should call onSyncComplete after successful sync', async () => {
       const syncFn = vi.fn().mockResolvedValue({ filesChanged: 2, durationMs: 50 });
       const onSyncComplete = vi.fn();
-      const watcher = new FileWatcher(testDir, baseConfig, syncFn, {
+      const watcher = newWatcher(syncFn, {
         debounceMs: 200,
         onSyncComplete,
       });
 
       watcher.start();
+      await watcher.waitUntilReady();
+      __emitWatchEventForTests(testDir, 'src/test.ts');
 
-      fs.writeFileSync(path.join(testDir, 'src', 'test.ts'), 'export const z = 3;');
-
-      await waitFor(() => onSyncComplete.mock.calls.length > 0, 5000);
+      await waitFor(() => onSyncComplete.mock.calls.length > 0);
       expect(onSyncComplete).toHaveBeenCalledWith({ filesChanged: 2, durationMs: 50 });
 
       watcher.stop();
@@ -203,16 +341,16 @@ describe('FileWatcher', () => {
     it('should call onSyncError when sync throws', async () => {
       const syncFn = vi.fn().mockRejectedValue(new Error('sync failed'));
       const onSyncError = vi.fn();
-      const watcher = new FileWatcher(testDir, baseConfig, syncFn, {
+      const watcher = newWatcher(syncFn, {
         debounceMs: 200,
         onSyncError,
       });
 
       watcher.start();
+      await watcher.waitUntilReady();
+      __emitWatchEventForTests(testDir, 'src/test.ts');
 
-      fs.writeFileSync(path.join(testDir, 'src', 'test.ts'), 'export const z = 3;');
-
-      await waitFor(() => onSyncError.mock.calls.length > 0, 5000);
+      await waitFor(() => onSyncError.mock.calls.length > 0);
       expect(onSyncError).toHaveBeenCalled();
       expect(onSyncError.mock.calls[0]![0]).toBeInstanceOf(Error);
 
@@ -235,7 +373,7 @@ describe('FileWatcher', () => {
 
       expect(cg.isWatching()).toBe(false);
 
-      const started = cg.watch({ debounceMs: 200 });
+      const started = cg.watch({ debounceMs: 200, inertForTests: true });
       expect(started).toBe(true);
       expect(cg.isWatching()).toBe(true);
 
@@ -249,7 +387,7 @@ describe('FileWatcher', () => {
       });
       await cg.indexAll();
 
-      cg.watch({ debounceMs: 200 });
+      cg.watch({ debounceMs: 200, inertForTests: true });
       expect(cg.isWatching()).toBe(true);
 
       cg.close();
@@ -258,7 +396,9 @@ describe('FileWatcher', () => {
       //  but we verify no errors are thrown)
     });
 
-    it('should auto-sync when files change while watching', async () => {
+    it('should auto-sync when files change while watching (real fs.watch end-to-end)', async () => {
+      // The one test that exercises the genuine native watcher: a real file
+      // write must propagate through fs.watch → debounce → sync into the graph.
       cg = CodeGraph.initSync(testDir, {
         config: { include: ['**/*.ts'], exclude: [] },
       });
@@ -268,20 +408,22 @@ describe('FileWatcher', () => {
       const initialNodes = initialStats.nodeCount;
 
       cg.watch({ debounceMs: 300 });
+      // Let the watcher install before writing, so the event isn't missed.
+      await new Promise((r) => setTimeout(r, 100));
 
-      // Add a new file with a function
+      // Real fs write — no synthetic event. The live watcher must catch it.
       fs.writeFileSync(
         path.join(testDir, 'src', 'added.ts'),
         'export function added() { return 42; }'
       );
 
-      // Wait for auto-sync to pick it up
+      // Wait for auto-sync to pick it up (real OS event delivery + debounce).
       await waitFor(() => {
         const stats = cg.getStats();
         return stats.nodeCount > initialNodes;
-      }, 10000);
+      }, 8000);
 
-      // The new function should be in the graph
+      // The new function should be in the graph.
       const results = cg.searchNodes('added');
       expect(results.length).toBeGreaterThan(0);
 
diff --git a/__tests__/worktree-detection.test.ts b/__tests__/worktree-detection.test.ts
new file mode 100644
index 000000000..6be3f2a5a
--- /dev/null
+++ b/__tests__/worktree-detection.test.ts
@@ -0,0 +1,189 @@
+/**
+ * Git worktree index-mismatch detection (issue #155).
+ *
+ * A CodeGraph index is resolved by walking up to the nearest `.codegraph/`.
+ * When a worktree is nested inside the main checkout, that walk reaches the
+ * MAIN checkout's index and a query silently returns the main branch's code
+ * instead of the worktree's. `detectWorktreeIndexMismatch` spots exactly this
+ * case so callers can warn.
+ *
+ * These tests drive real `git` against real temp worktrees — no mocking — so
+ * they exercise the same `git rev-parse --show-toplevel` behavior production
+ * relies on.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import {
+  detectWorktreeIndexMismatch,
+  worktreeMismatchWarning,
+  gitWorktreeRoot,
+} from '../src/sync/worktree';
+import CodeGraph from '../src/index';
+import { ToolHandler } from '../src/mcp/tools';
+
+function git(cwd: string, ...args: string[]): void {
+  execFileSync('git', args, { cwd, stdio: ['ignore', 'ignore', 'ignore'] });
+}
+
+/** realpath so macOS /var → /private/var symlinking doesn't break equality. */
+function real(p: string): string {
+  return fs.realpathSync(path.resolve(p));
+}
+
+describe('detectWorktreeIndexMismatch (issue #155)', () => {
+  let mainRepo: string;   // main checkout — owns the .codegraph index
+  let worktree: string;   // a linked worktree nested inside the main checkout
+  let nonGit: string;     // a directory outside any git repo
+
+  beforeEach(() => {
+    mainRepo = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-wt-main-'));
+    nonGit = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-wt-plain-'));
+
+    git(mainRepo, 'init', '-q');
+    git(mainRepo, 'config', 'user.email', 'test@example.com');
+    git(mainRepo, 'config', 'user.name', 'Test');
+    git(mainRepo, 'config', 'commit.gpgsign', 'false');
+    fs.writeFileSync(path.join(mainRepo, 'README.md'), '# main\n');
+    git(mainRepo, 'add', '.');
+    git(mainRepo, 'commit', '-q', '-m', 'init');
+
+    // Nest the worktree under the main checkout, mirroring tools that place
+    // worktrees in (gitignored) subpaths like `.claude/worktrees/<name>/`.
+    worktree = path.join(mainRepo, 'wt');
+    git(mainRepo, 'worktree', 'add', '-q', '-b', 'feature', worktree);
+  });
+
+  afterEach(() => {
+    try { git(mainRepo, 'worktree', 'remove', '--force', worktree); } catch { /* best effort */ }
+    fs.rmSync(mainRepo, { recursive: true, force: true });
+    fs.rmSync(nonGit, { recursive: true, force: true });
+  });
+
+  it('flags a worktree borrowing the main checkout index', () => {
+    const m = detectWorktreeIndexMismatch(worktree, mainRepo);
+    expect(m).not.toBeNull();
+    expect(m!.worktreeRoot).toBe(real(worktree));
+    expect(m!.indexRoot).toBe(real(mainRepo));
+  });
+
+  it('returns null when the index lives in the same working tree', () => {
+    expect(detectWorktreeIndexMismatch(mainRepo, mainRepo)).toBeNull();
+    expect(detectWorktreeIndexMismatch(worktree, worktree)).toBeNull();
+  });
+
+  it('returns null for a subdirectory of the same working tree', () => {
+    const sub = path.join(mainRepo, 'src');
+    fs.mkdirSync(sub);
+    expect(detectWorktreeIndexMismatch(sub, mainRepo)).toBeNull();
+  });
+
+  it('returns null when startPath is not in a git repo', () => {
+    expect(detectWorktreeIndexMismatch(nonGit, mainRepo)).toBeNull();
+  });
+
+  it('returns null when the index root is a plain (non-worktree) directory', () => {
+    // startPath is a real worktree, but the index sits in an unrelated non-git
+    // dir — that's "index in an ancestor", not "borrowed another worktree".
+    expect(detectWorktreeIndexMismatch(worktree, nonGit)).toBeNull();
+  });
+
+  it('gitWorktreeRoot reports each tree distinctly', () => {
+    expect(gitWorktreeRoot(worktree)).toBe(real(worktree));
+    expect(gitWorktreeRoot(mainRepo)).toBe(real(mainRepo));
+    expect(gitWorktreeRoot(nonGit)).toBeNull();
+  });
+
+  it('warning names both trees and the fix', () => {
+    const msg = worktreeMismatchWarning(detectWorktreeIndexMismatch(worktree, mainRepo)!);
+    expect(msg).toContain(real(worktree));
+    expect(msg).toContain(real(mainRepo));
+    expect(msg).toContain('codegraph init');
+  });
+});
+
+/**
+ * The detection above only helps if it reaches the agent. Agents call the read
+ * tools (search/context/trace/…), almost never status — so the mismatch notice
+ * has to ride on every read tool's result, not just status. These tests drive
+ * the real `ToolHandler.execute` chokepoint against a real index whose default
+ * project resolves UP from a nested worktree to the main checkout.
+ */
+describe('worktree mismatch surfaces on hot read tools (issue #155)', () => {
+  let mainRepo: string;
+  let worktree: string;
+  let cg: CodeGraph;
+  let handler: ToolHandler;
+
+  beforeEach(async () => {
+    mainRepo = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-wt-tool-'));
+    git(mainRepo, 'init', '-q');
+    git(mainRepo, 'config', 'user.email', 'test@example.com');
+    git(mainRepo, 'config', 'user.name', 'Test');
+    git(mainRepo, 'config', 'commit.gpgsign', 'false');
+    fs.mkdirSync(path.join(mainRepo, 'src'));
+    fs.writeFileSync(path.join(mainRepo, 'src', 'a.ts'), 'export function mainOnly() { return 1; }\n');
+    git(mainRepo, 'add', '.');
+    git(mainRepo, 'commit', '-q', '-m', 'init');
+
+    // The index lives in the MAIN checkout.
+    cg = CodeGraph.initSync(mainRepo);
+    await cg.indexAll();
+
+    // Nested worktree, mirroring tools that place them under .claude/worktrees/<name>/.
+    worktree = path.join(mainRepo, 'wt');
+    git(mainRepo, 'worktree', 'add', '-q', '-b', 'feature', worktree);
+
+    handler = new ToolHandler(cg);
+  });
+
+  afterEach(() => {
+    try { cg.destroy(); } catch { /* best effort */ }
+    try { git(mainRepo, 'worktree', 'remove', '--force', worktree); } catch { /* best effort */ }
+    fs.rmSync(mainRepo, { recursive: true, force: true });
+  });
+
+  it('prefixes a compact notice on codegraph_search run from a nested worktree', async () => {
+    handler.setDefaultProjectHint(worktree);
+    const res = await handler.execute('codegraph_search', { query: 'mainOnly' });
+    const text = res.content[0].text;
+    expect(res.isError).toBeFalsy();
+    expect(text).toContain('different git worktree');
+    expect(text).toContain(real(worktree));
+    expect(text).toContain('codegraph init');
+  });
+
+  it('does NOT prefix when the default project is the main checkout itself', async () => {
+    handler.setDefaultProjectHint(mainRepo);
+    const res = await handler.execute('codegraph_search', { query: 'mainOnly' });
+    expect(res.content[0].text).not.toContain('different git worktree');
+  });
+
+  it('still shows the verbose warning on codegraph_status', async () => {
+    handler.setDefaultProjectHint(worktree);
+    const res = await handler.execute('codegraph_status', {});
+    const text = res.content[0].text;
+    expect(text).toContain('different git working tree');
+    expect(text).toContain(real(worktree));
+  });
+
+  it('caches detection — a later tool call needs no further git spawn', async () => {
+    handler.setDefaultProjectHint(worktree);
+    // First call computes + caches the mismatch (this is the only git spawn).
+    const first = await handler.execute('codegraph_search', { query: 'mainOnly' });
+    expect(first.content[0].text).toContain('different git worktree');
+
+    // Make git unreachable. A fresh detection would now return null (no notice);
+    // the notice still appearing on a *different* tool proves it came from cache.
+    const savedPath = process.env.PATH;
+    process.env.PATH = '';
+    try {
+      const second = await handler.execute('codegraph_explore', { query: 'mainOnly' });
+      expect(second.content[0].text).toContain('different git worktree');
+    } finally {
+      process.env.PATH = savedPath;
+    }
+  });
+});
diff --git a/assets/__pycache__/generate-waitlist.cpython-313.pyc b/assets/__pycache__/generate-waitlist.cpython-313.pyc
new file mode 100644
index 000000000..ffb2bd54a
Binary files /dev/null and b/assets/__pycache__/generate-waitlist.cpython-313.pyc differ
diff --git a/assets/waitlist.svg b/assets/waitlist.svg
new file mode 100644
index 000000000..04d9bac6b
--- /dev/null
+++ b/assets/waitlist.svg
@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="279.98" height="52" viewBox="0 0 279.98 52" role="img" aria-label="Join the waitlist">
+  <title>Join the waitlist</title>
+  <rect x="0.5" y="0.5" width="278.98" height="51" rx="8" fill="#f7f6f2" stroke="#d6d3c8"/>
+  <!-- logo mark (mirrors static/favicon.svg) -->
+  <g stroke="#16150f" stroke-width="2.02" stroke-linecap="round" fill="none">
+    <line x1="35.5" y1="18.43" x2="27.43" y2="33.57"/>
+    <line x1="35.5" y1="18.43" x2="43.58" y2="33.57"/>
+    <line x1="27.43" y1="33.57" x2="43.58" y2="33.57"/>
+  </g>
+  <circle cx="35.5" cy="18.43" r="3.43" fill="#7a201a"/>
+  <circle cx="27.43" cy="33.57" r="3.43" fill="#f7f6f2" stroke="#16150f" stroke-width="2.02"/>
+  <circle cx="43.58" cy="33.57" r="3.43" fill="#f7f6f2" stroke="#16150f" stroke-width="2.02"/>
+  <!-- hairline divider -->
+  <line x1="64.01" y1="13" x2="64.01" y2="39" stroke="#d6d3c8"/>
+  <!-- label (outlined Archivo, no font dependency) -->
+  <path d="M87.06102188110353 32.21Q85.63705871582032 32.21 84.62491539001465 31.785816192626953Q83.61277206420898 31.361632385253905 83.07940444946288 30.503375091552734Q82.5460368347168 29.64511779785156 82.5460368347168 28.320831146240234V27.86544128417969H85.36731582641602V28.31360321044922Q85.36731582641602 29.122787017822265 85.77990043640136 29.505125274658205Q86.19248504638672 29.88746353149414 87.01042633056642 29.88746353149414Q87.80782348632813 29.88746353149414 88.21527206420899 29.3767244720459Q88.62272064208985 28.865985412597656 88.62272064208985 27.851360321044922V19.980544128417968H91.56573486328125V27.858588256835937Q91.56573486328125 29.33695587158203 91.03236724853517 30.303069839477537Q90.49899963378907 31.269183807373047 89.4919923400879 31.739591903686524Q88.48498504638673 32.21 87.06102188110353 32.21ZM98.52074981689454 32.21Q96.98683807373047 32.21 95.91040061950685 31.686522064208987Q94.83396316528321 31.16304412841797 94.26863967895508 30.09193016052246Q93.70331619262696 29.020816192626953 93.70331619262696 27.390272064208986Q93.70331619262696 25.742227935791014 94.26863967895508 24.679863967895507Q94.83396316528321 23.6175 95.91040061950685 23.094022064208986Q96.98683807373047 22.570544128417968 98.52074981689454 22.570544128417968Q100.06493362426758 22.570544128417968 101.13984901428223 23.094022064208986Q102.21476440429689 23.6175 102.78008789062501 24.679863967895507Q103.34541137695314 25.742227935791014 103.34541137695314 27.390272064208986Q103.34541137695314 29.020816192626953 102.78008789062501 30.09193016052246Q102.21476440429689 31.16304412841797 101.13984901428223 31.686522064208987Q100.06493362426758 32.21 98.52074981689454 32.21ZM98.52074981689454 30.207022247314452Q99.26678665161133 30.207022247314452 99.72882713317871 29.919411926269532Q100.1908676147461 29.63180160522461 100.40181983947754 29.065900802612305Q100.61277206420898 28.5 100.61277206420898 27.671786651611328V27.115985412597656Q100.61277206420898 26.287772064208983 100.40181983947754 25.71825729370117Q100.1908676147461 25.14874252319336 99.72882713317871 24.86113220214844Q99.26678665161133 24.573521881103517 98.52074981689454 24.573521881103517Q97.77471298217773 24.573521881103517 97.31628646850587 24.86113220214844Q96.85785995483398 25.14874252319336 96.64690773010254 25.71825729370117Q96.4359555053711 26.287772064208983 96.4359555053711 27.115985412597656V27.671786651611328Q96.4359555053711 28.5 96.64690773010254 29.065900802612305Q96.85785995483398 29.63180160522461 97.31628646850587 29.919411926269532Q97.77471298217773 30.207022247314452 98.52074981689454 30.207022247314452ZM105.29886032104493 21.500374908447263V19.333044128417967H107.99041137695313V21.500374908447263ZM105.29886032104493 32.0V22.78054412841797H107.99041137695313V32.0ZM110.39886032104492 32.0V22.78054412841797H112.62476440429687L112.82144821166992 24.077823486328125H112.94394821166992Q113.28063201904297 23.607227935791016 113.73467979431152 23.269022064208983Q114.18872756958008 22.930816192626953 114.75804740905761 22.75068016052246Q115.32736724853515 22.570544128417968 115.97791137695313 22.570544128417968Q116.94687454223633 22.570544128417968 117.63508041381836 22.925297775268554Q118.32328628540039 23.28005142211914 118.69383041381835 24.008963165283202Q119.06437454223632 24.737874908447264 119.06437454223632 25.8814631652832V32.0H116.36255142211914V26.280919036865235Q116.36255142211914 25.870426330566406 116.26325729370117 25.582816009521487Q116.1639631652832 25.295205688476564 115.97773887634278 25.104797592163088Q115.79151458740235 24.91438949584961 115.51626823425293 24.823275527954102Q115.24102188110352 24.732161560058593 114.8921615600586 24.732161560058593Q114.37248504638671 24.732161560058593 113.96655853271484 24.979635848999024Q113.56063201904297 25.22711013793945 113.32552169799806 25.648444747924806Q113.09041137695313 26.069779357910157 113.09041137695313 26.616088256835937V32.0ZM128.02073486328126 32.21Q127.12709518432618 32.21 126.53951805114747 31.91934555053711Q125.95194091796876 31.628691101074217 125.66756965637208 31.09132713317871Q125.38319839477539 30.553963165283204 125.38319839477539 29.83494857788086V24.783521881103514H124.20119110107422V22.78054412841797H125.47183807373047L126.0086247253418 20.114080963134764H128.07474945068358V22.78054412841797H129.81903610229492V24.783521881103514H128.07474945068358V29.25632385253906Q128.07474945068358 29.717787017822264 128.2672494506836 29.962404632568358Q128.4597494506836 30.207022247314452 128.93148468017577 30.207022247314452H129.81903610229492V31.91554412841797Q129.60066848754883 31.992772064208985 129.2818670654297 32.06125Q128.96306564331056 32.12972793579102 128.62885612487793 32.16986396789551Q128.29464660644533 32.21 128.02073486328126 32.21ZM131.6138603210449 32.0V19.333044128417967H134.30541137695312V23.79440444946289H134.42791137695312Q134.7254113769531 23.419676513671874 135.14959518432616 23.1505184173584Q135.5737789916992 22.881360321044923 136.09364295959472 22.725952224731444Q136.61350692749022 22.570544128417968 137.1929113769531 22.570544128417968Q138.16187454223632 22.570544128417968 138.85008041381835 22.925297775268554Q139.53828628540037 23.28005142211914 139.90883041381835 24.008963165283202Q140.27937454223633 24.737874908447264 140.27937454223633 25.8814631652832V32.0H137.57755142211914V26.280919036865235Q137.57755142211914 25.870426330566406 137.47825729370118 25.582816009521487Q137.37896316528318 25.295205688476564 137.19273887634276 25.104797592163088Q137.00651458740234 24.91438949584961 136.73126823425292 24.823275527954102Q136.4560218811035 24.732161560058593 136.1071615600586 24.732161560058593Q135.58748504638672 24.732161560058593 135.18155853271483 24.979635848999024Q134.77563201904294 25.22711013793945 134.54052169799803 25.648444747924806Q134.30541137695312 26.069779357910157 134.30541137695312 26.616088256835937V32.0ZM147.01030853271482 32.21Q145.46080123901365 32.21 144.38322410583493 31.69375Q143.30564697265623 31.1775 142.74698158264158 30.11Q142.18831619262693 29.0425 142.18831619262693 27.390272064208986Q142.18831619262693 25.742227935791014 142.74336761474606 24.679863967895507Q143.2984190368652 23.6175 144.35431236267087 23.094022064208986Q145.41020568847654 22.570544128417968 146.92357330322264 22.570544128417968Q148.39090408325194 22.570544128417968 149.40057312011717 23.076522064208984Q150.4102421569824 23.5825 150.93029357910154 24.62945587158203Q151.45034500122068 25.67641174316406 151.45034500122068 27.328639678955078V27.944183807373047H144.9106834411621Q144.93122756958005 28.707720642089843 145.1406577301025 29.239761123657225Q145.35008789062496 29.77180160522461 145.8024261474609 30.038867797851562Q146.25476440429685 30.305933990478515 146.99166885375973 30.305933990478515Q147.4230805969238 30.305933990478515 147.7622386932373 30.200933990478514Q148.10139678955076 30.095933990478514 148.3385990142822 29.891639862060543Q148.57580123901366 29.687345733642577 148.6992534637451 29.390985412597658Q148.82270568847653 29.094625091552736 148.82270568847653 28.722176513671876H151.45034500122068Q151.45034500122068 29.575492706298828 151.14048103332516 30.230220642089844Q150.83061706542966 30.88494857788086 150.24684135437008 31.323018417358398Q149.66306564331052 31.761088256835937 148.84494438171384 31.98554412841797Q148.02682312011717 32.21 147.01030853271482 32.21ZM144.93845550537108 26.381360321044923H148.69297775268552Q148.69297775268552 25.890595550537107 148.57256965637202 25.53507713317871Q148.45216156005856 25.179558715820313 148.2303674316406 24.942356491088866Q148.00857330322262 24.70515426635742 147.69414314270017 24.59501823425293Q147.37971298217772 24.484882202148437 146.98139678955076 24.484882202148437Q146.34226440429686 24.484882202148437 145.91104011535643 24.697926330566403Q145.479815826416 24.910970458984373 145.24927169799804 25.329260940551755Q145.01872756958005 25.74755142211914 144.93845550537108 26.381360321044923ZM158.9135218811035 32.0 155.90581619262693 22.78054412841797H158.7541024780273L159.8003085327148 26.882052154541014Q159.89085266113278 27.202000732421872 159.97892250061034 27.614390411376952Q160.06699234008786 28.026780090332032 160.15201805114742 28.397699127197264Q160.237043762207 28.7686181640625 160.2906834411621 28.980132751464843H160.40291137695309Q160.49459518432616 28.614537200927735 160.58266502380368 28.218125457763673Q160.6707348632812 27.82171371459961 160.75728263854978 27.46125419616699Q160.84383041381832 27.100794677734374 160.8974700927734 26.85846389770508L161.906771697998 22.78054412841797H164.68354339599605L165.7164332580566 26.875963897705077Q165.7864332580566 27.120963897705078 165.86936706542966 27.502537384033204Q165.9523008728027 27.884110870361326 166.04759864807124 28.2786181640625Q166.1428964233398 28.67312545776367 166.2068081665039 28.980132751464843H166.3190361022949Q166.37571990966794 28.712309265136717 166.46226768493648 28.342529907226563Q166.54881546020505 27.972750549316405 166.6404992675781 27.589085159301757Q166.73218307495114 27.205419769287108 166.79913894653316 26.90678009033203L167.84952880859373 22.78054412841797H170.45357986450193L167.44891830444334 32.0H164.7216024780273L163.7438818359375 28.13513931274414Q163.66665390014646 27.81709518432617 163.56678993225097 27.41516502380371Q163.46692596435545 27.013234863281248 163.38094802856443 26.6185326385498Q163.2949700927734 26.22383041381836 163.2352421569824 25.94078628540039H163.14469802856442Q163.12301422119137 26.113881835937498 163.05244438171383 26.443337707519532Q162.9818745422363 26.772793579101563 162.8820105743408 27.201925964355468Q162.78214660644528 27.631058349609376 162.64633041381833 28.127911376953126L161.6408377075195 32.0ZM174.3031469726562 32.21Q173.78081619262693 32.21 173.24231254577634 32.09929412841797Q172.70380889892576 31.98858825683594 172.25090080261228 31.7080184173584Q171.7979927062988 31.42744857788086 171.52579048156736 30.918426513671875Q171.2535882568359 30.40940444946289 171.2535882568359 29.62Q171.2535882568359 28.638860321044923 171.67720222473142 28.0067684173584Q172.10081619262692 27.374676513671876 172.88736396789548 27.019540481567383Q173.67391174316404 26.66440444946289 174.78325729370113 26.522882385253908Q175.89260284423824 26.381360321044923 177.2610218811035 26.381360321044923V25.751735229492187Q177.2610218811035 25.356463165283202 177.11322410583495 25.073988876342774Q176.96542633056637 24.791514587402343 176.6525182342529 24.6330623626709Q176.33961013793942 24.47461013793945 175.80052917480467 24.47461013793945Q175.29758789062498 24.47461013793945 174.95177169799803 24.595970458984375Q174.60595550537107 24.717330780029297 174.44065773010252 24.923146972656248Q174.27535995483396 25.128963165283203 174.27535995483396 25.402874908447266V25.57559555053711H171.64658096313474Q171.62908096313473 25.495323486328125 171.62908096313473 25.422279357910156Q171.62908096313473 25.349235229492187 171.62908096313473 25.248419036865233Q171.62908096313473 24.432007293701172 172.1341066741943 23.82920951843262Q172.63913238525387 23.226411743164064 173.5767095184326 22.898477935791014Q174.51428665161131 22.570544128417968 175.8119409179687 22.570544128417968Q177.07916885375974 22.570544128417968 178.00495185852049 22.891632385253907Q178.93073486328123 23.21272064208984 179.44165390014646 23.86383460998535Q179.9525729370117 24.51494857788086 179.9525729370117 25.529183807373045V29.565610504150392Q179.9525729370117 29.876426696777344 180.12338912963867 30.0417244720459Q180.2942053222656 30.207022247314452 180.54338912963865 30.207022247314452H181.13230087280272V31.901088256835937Q180.9428450012207 31.992772064208985 180.54890754699704 32.09625Q180.1549700927734 32.19972793579102 179.59991867065426 32.19972793579102Q179.04372756958006 32.19972793579102 178.6163121795654 32.05459190368653Q178.18889678955077 31.909455871582033 177.9113710784912 31.636683807373046Q177.6338453674316 31.363911743164063 177.5216174316406 30.993367614746095H177.40938949584958Q177.0829777526855 31.34641174316406 176.64281600952145 31.624319839477536Q176.2026542663574 31.902227935791014 175.62610649108885 32.056113967895506Q175.0495587158203 32.21 174.3031469726562 32.21ZM175.26867614746092 30.286529541015625Q175.71416885375973 30.286529541015625 176.08205123901365 30.15432731628418Q176.44993362426754 30.022125091552734 176.71034172058103 29.789106674194336Q176.9707498168945 29.556088256835938 177.115885848999 29.222253646850586Q177.2610218811035 28.888419036865233 177.2610218811035 28.495426330566406V27.923639678955077Q176.26961013793942 27.923639678955077 175.5281394958496 28.06059555053711Q174.78666885375975 28.19755142211914 174.3813121795654 28.501139678955077Q173.97595550537108 28.804727935791014 173.97595550537108 29.308808898925783Q173.97595550537108 29.638264770507813 174.1355474090576 29.856444931030275Q174.2951393127441 30.074625091552733 174.5869334411621 30.18057731628418Q174.87872756958006 30.286529541015625 175.26867614746092 30.286529541015625ZM182.52386032104488 21.500374908447263V19.333044128417967H185.21541137695309V21.500374908447263ZM182.52386032104488 32.0V22.78054412841797H185.21541137695309V32.0ZM190.6707348632812 32.21Q189.77709518432613 32.21 189.18951805114742 31.91934555053711Q188.6019409179687 31.628691101074217 188.31756965637203 31.09132713317871Q188.03319839477535 30.553963165283204 188.03319839477535 29.83494857788086V24.783521881103514H186.85119110107416V22.78054412841797H188.12183807373043L188.65862472534175 20.114080963134764H190.72474945068353V22.78054412841797H192.46903610229487V24.783521881103514H190.72474945068353V29.25632385253906Q190.72474945068353 29.717787017822264 190.91724945068353 29.962404632568358Q191.10974945068355 30.207022247314452 191.58148468017572 30.207022247314452H192.46903610229487V31.91554412841797Q192.25066848754878 31.992772064208985 191.93186706542963 32.06125Q191.6130656433105 32.12972793579102 191.2788561248779 32.16986396789551Q190.94464660644527 32.21 190.6707348632812 32.21ZM194.2638603210449 32.0V19.333044128417967H196.9554113769531V32.0ZM199.36386032104488 21.500374908447263V19.333044128417967H202.0554113769531V21.500374908447263ZM199.36386032104488 32.0V22.78054412841797H202.0554113769531V32.0ZM208.3332498168945 32.21Q207.40080123901362 32.21 206.61577552795404 32.012933807373045Q205.8307498168945 31.815867614746093 205.24735649108882 31.441709518432617Q204.66396316528315 31.06755142211914 204.3415477752685 30.5332315826416Q204.01913238525387 29.99891174316406 204.01913238525387 29.30690444946289Q204.01913238525387 29.233860321044922 204.02426841735837 29.16747428894043Q204.02940444946285 29.101088256835936 204.03663238525385 29.051632385253907H206.60644821166989Q206.59922027587885 29.09386032104492 206.59922027587885 29.136088256835937Q206.59922027587885 29.17831619262695 206.59922027587885 29.21331619262695Q206.61672027587886 29.62076477050781 206.8641945648193 29.876989059448242Q207.1116688537597 30.133213348388672 207.5160733032226 30.248485412597656Q207.9204777526855 30.36375747680664 208.3846101379394 30.36375747680664Q208.7528749084472 30.36375747680664 209.13521316528315 30.292805252075194Q209.51755142211908 30.221853027343748 209.78518745422357 30.035628738403318Q210.05282348632807 29.84940444946289 210.05282348632807 29.506632385253905Q210.05282348632807 29.116683807373047 209.7208933258056 28.91143745422363Q209.38896316528314 28.706191101074218 208.8491249084472 28.573988876342774Q208.30928665161127 28.441786651611327 207.68347045898432 28.29569839477539Q207.07705871582027 28.159882202148438 206.4670330047607 27.97822410583496Q205.85700729370112 27.796566009521484 205.35350364685053 27.495452041625974Q204.84999999999997 27.194338073730467 204.53956619262692 26.707382202148438Q204.22913238525385 26.220426330566404 204.22913238525385 25.477058715820313Q204.22913238525385 24.70059555053711 204.5591580963134 24.149727935791013Q204.889183807373 23.59886032104492 205.4683933258056 23.250382385253907Q206.04760284423824 22.90190444946289 206.81208442687984 22.73774635314941Q207.57656600952143 22.573588256835937 208.4454777526855 22.573588256835937Q209.25352188110347 22.573588256835937 209.97063949584958 22.73774635314941Q210.68775711059567 22.90190444946289 211.2479445648193 23.22565444946289Q211.80813201904292 23.54940444946289 212.12636360168452 24.038452224731444Q212.44459518432612 24.5275 212.44459518432612 25.16700729370117Q212.44459518432612 25.260595550537108 212.43945915222162 25.36502571105957Q212.43432312011714 25.46945587158203 212.42709518432613 25.494183807373048H209.88200729370112V25.36445587158203Q209.88200729370112 25.060867614746094 209.68798522949214 24.853529357910155Q209.49396316528316 24.64619110107422 209.15385284423826 24.531488876342774Q208.81374252319333 24.41678665161133 208.36216156005855 24.41678665161133Q208.07226440429682 24.41678665161133 207.80063201904292 24.461488876342774Q207.52899963378903 24.50619110107422 207.320521697998 24.59977935791016Q207.11204376220698 24.693367614746094 206.98897392272943 24.836411743164064Q206.8659040832519 24.97945587158203 206.8659040832519 25.18641174316406Q206.8659040832519 25.46831619262695 207.10310630798335 25.635518417358398Q207.3403085327148 25.802720642089845 207.74319091796872 25.91742286682129Q208.1460733032226 26.032125091552736 208.6277056884765 26.160713348388672Q209.27216156005855 26.314029541015625 209.98052917480464 26.468867797851562Q210.68889678955074 26.6237060546875 211.30824234008784 26.900092086791993Q211.92758789062495 27.176478118896483 212.31372756958 27.702047958374024Q212.6998672485351 28.22761779785156 212.6998672485351 29.1326692199707Q212.6998672485351 29.995492706298826 212.36109153747555 30.59315444946289Q212.02231582641596 31.190816192626954 211.42408424377436 31.542908096313475Q210.82585266113276 31.895 210.03150711059567 32.0525Q209.23716156005855 32.21 208.3332498168945 32.21ZM217.68573486328123 32.21Q216.79209518432614 32.21 216.20451805114743 31.91934555053711Q215.61694091796872 31.628691101074217 215.33256965637204 31.09132713317871Q215.04819839477537 30.553963165283204 215.04819839477537 29.83494857788086V24.783521881103514H213.86619110107418V22.78054412841797H215.13683807373044L215.67362472534177 20.114080963134764H217.73974945068355V22.78054412841797H219.48403610229488V24.783521881103514H217.73974945068355V29.25632385253906Q217.73974945068355 29.717787017822264 217.93224945068357 29.962404632568358Q218.12474945068357 30.207022247314452 218.59648468017573 30.207022247314452H219.48403610229488V31.91554412841797Q219.2656684875488 31.992772064208985 218.94686706542967 32.06125Q218.62806564331052 32.12972793579102 218.2938561248779 32.16986396789551Q217.9596466064453 32.21 217.68573486328123 32.21Z" fill="#16150f"/>
+  <!-- arrow -->
+  <g stroke="#7a201a" stroke-width="2.2" fill="none" stroke-linecap="round" stroke-linejoin="round">
+    <line x1="237.98" y1="26.0" x2="255.98" y2="26.0"/>
+    <polyline points="249.38,21.2 255.98,26.0 249.38,30.8"/>
+  </g>
+</svg>
diff --git a/docs/benchmarks/answer-directly-vs-explore-agent.md b/docs/benchmarks/answer-directly-vs-explore-agent.md
new file mode 100644
index 000000000..09167ec12
--- /dev/null
+++ b/docs/benchmarks/answer-directly-vs-explore-agent.md
@@ -0,0 +1,88 @@
+# Answer directly vs. delegate to an Explore agent (interactive A/B)
+
+**Question:** Does answering a "how does X work?" question *directly* with CodeGraph in the
+main session bloat main-session context — and would Claude Code be better off delegating that
+exploration to a disposable **Explore agent** (which keeps main context lean by absorbing the
+file reads in a sub-transcript)? And critically: **does the answer change at scale**, on a
+codebase far larger than Excalidraw?
+
+**Short answer:** No. With CodeGraph, main-session context is roughly **scale-invariant (~50k)**
+because the retrieval is targeted and the `explore` payload is budget-capped — it does not
+balloon on a 16× larger repo. Answering directly wins at **every** scale: same-or-leaner main
+context than the delegation path, **zero file reads**, and ~28% fewer tokens. The
+delegation-for-hygiene advantage stays marginal even on a large codebase.
+
+## Methodology
+
+- **Harness:** interactive Claude Code TUI driven via `scripts/agent-eval/itrun.sh` (tmux),
+  **not** headless `claude -p`. This matters: headless spawns **0** Explore agents, so it cannot
+  measure delegation behavior at all; only the interactive TUI does.
+- **Arms:** `WITH` = CodeGraph in the MCP config; `WITHOUT` = empty MCP config (`--strict-mcp-config`).
+- **Model:** `opus`. **n = 3 runs per arm.** Main **and** sub-agent transcripts parsed
+  (`scripts/agent-eval/parse-session.mjs`); reads/bash are summed across main + sub-agents.
+- **Repos:** Excalidraw (643 files, medium) and VS Code (~10.7k files, large — ~16× Excalidraw).
+- **Build:** 0.9.4. **Date:** 2026-05-24.
+- "main-session context" is the TUI's reported `Context X/Y` for the *main* thread (sub-agent
+  context does not count against it). "billable tokens" = summed per-turn assistant usage
+  (input + output + cache read + cache creation).
+
+## Excalidraw (643 files, medium)
+
+Question: *"How does Excalidraw render and update canvas elements?"*
+
+| metric | WITH codegraph | WITHOUT |
+|---|---|---|
+| Explore agents spawned | 0 / 0 / 0 | 0 / 1 / 1 (delegated 2 of 3) |
+| main-session context | 51k / 49k / 50k (~50k) | 48k / 34k / 26k (~36k) |
+| total tool calls | 4 / 4 / 4 | 16 / 55 / 37 |
+| Reads (main+sub) | 0 / 0 / 0 | 6 / 25 / 16 |
+| billable tokens | ~127k | ~175k |
+
+## VS Code (~10.7k files, large — ~16× Excalidraw)
+
+Question: *"How does the extension host communicate with the main process?"*
+
+| metric | WITH codegraph | WITHOUT |
+|---|---|---|
+| main-session context | 47k / 43k / 50k (~47k) | 54k / 29k / 31k (~38k) |
+| Explore agents | 0 / 0 / 0 | 0 / 1 / 1 (delegated 2/3) |
+| codegraph calls | ~8 (search + explore×2–3 + context) | 0 |
+| Reads (main+sub) | 0 / 1 / 0 | 6 / 26 / 19 |
+| billable tokens | ~126k | ~176k |
+
+## Findings
+
+**Main-session context is scale-invariant with CodeGraph.** With codegraph, main-session
+context was **~47k on VS Code — essentially identical to Excalidraw's ~50k**, despite a 16×
+bigger repo. It didn't balloon. Reason: codegraph's `explore` payload is **budget-capped** and
+retrieval is **targeted** — answering one question pulls in the relevant *flow/area*, not more
+just because the repo is huge. So codegraph makes main-session context roughly scale-invariant
+(~50k). The delegation-for-hygiene advantage stays marginal even on a large codebase — exactly
+the opposite of "it gets significant at scale."
+
+The thing that *would* balloon at scale is reading many big files directly into main — and
+Claude Code avoids that **without** codegraph by delegating to an Explore agent (29–31k main),
+but at the cost of **17–26 reads** and ~28% more tokens. CodeGraph keeps main lean a *better*
+way: a capped, targeted payload — no delegation, **0 reads**.
+
+**On "the Explore agents use codegraph."** I couldn't reproduce it: across **6/6**
+with-codegraph runs (both repos), Claude Code **never delegated** — it answered directly every
+time. The Explore-agent path only appeared in the `without` arm (using grep/read, since codegraph
+wasn't in that config). So with the current instructions + codegraph present, Claude Code stays
+in the main session — the lean-main-via-Explore-agent best case simply isn't what happens;
+lean-main-via-capped-codegraph is, and it's cheaper.
+
+## Verdict
+
+**"Answer directly with codegraph" wins for Claude Code too — at every scale.** No per-agent
+split is needed; the unified "answer directly" instruction is right for Claude Code *and* for
+Codex / Cursor / opencode (which have no Explore-agent mechanism and would otherwise read files
+directly). This conclusion drove updating the README's `## CodeGraph` example block, which
+previously told agents to "NEVER call `codegraph_explore` directly / ALWAYS spawn an Explore
+agent" — i.e., it steered Claude Code toward the *worse* (17–26 read, ~28%-more-token) path.
+
+**Caveat / future work (not a blocker):** an Explore agent that *itself uses codegraph* could in
+principle get lean-main *and* low-work. But the "answer directly" instruction prevents delegation
+in practice (0 delegations observed across 6 runs), the main-context gain would be marginal
+(~50k → ~30k, both a few percent of a 1M window), and it adds a sub-agent round-trip. Worth a
+future experiment, not a default.
diff --git a/docs/benchmarks/call-sequence-analysis.md b/docs/benchmarks/call-sequence-analysis.md
new file mode 100644
index 000000000..3c79bad5e
--- /dev/null
+++ b/docs/benchmarks/call-sequence-analysis.md
@@ -0,0 +1,426 @@
+# Call-sequence analysis — why read savings don't convert to wall-clock
+
+**Date:** 2026-05-23 · **Branch:** `architectural-improvements` · **Source data:** the surviving
+stream-json logs from the A/B matrix (`/tmp/ab-matrix/<Cell>/run-headless-{with,without}.jsonl`,
+37 cells × 2 arms). Re-mined — **no re-runs** — with `scripts/agent-eval/seq-matrix.mjs`.
+
+## Why this exists
+
+The [A/B matrix](codegraph-ab-matrix.md) showed codegraph cuts **reads 75%** but **wall-clock only
+~16%**, and 63% of the wall-clock win comes from just 3 large-repo cells. Reads are at the floor
+(~0), so the remaining wall-clock is **round-trips + the synthesis turn** — neither of which read
+count can explain. The matrix records tool *counts*, not the call **sequence** or per-call
+**payload size**. This analysis recovers both, to find where the wall-clock actually goes.
+
+## TL;DR — the bottleneck is trace ADOPTION, not trace completeness
+
+1. **Trace is called in 3 of 37 cells** — even though every question is a canonical flow question
+   ("trace the controller → service → repository", "how does X reach Y"). The agent overwhelmingly
+   reaches for **`context → search → search → explore`** instead — the exact path-reconstruction
+   anti-pattern the instructions tell it to avoid.
+2. **`explore` averages 17.9K chars/call; `trace` averages 0.8K** — a **22× payload difference**.
+   The path-scoped tool that solves the small-repo-bloat problem exists and is tiny. It's just not
+   being invoked.
+3. **Small repos still get bloated payloads** because of the explore-default: a **6-file** repo
+   (`flutter_module_books`) pulls **17.4K**; a 10-file repo pulls 18.0K. This is precisely the
+   "too much context on small codebases" failure mode — happening right now, via explore.
+4. **Round-trips are 25% fewer with codegraph (283 vs 375 turns)** but wall-clock is only 16%
+   faster — because the with-arm's turns each carry a ~18K explore payload, inflating TTFT and
+   eroding the turn savings.
+5. **Root cause:** `src/mcp/server-instructions.ts` leads with *"answer directly … `codegraph_context`
+   first, then ONE `codegraph_explore`"* as the headline pattern. The trace-first guidance is buried
+   in a table + a chain list below it. Agents anchor on the prominent headline → context→explore.
+
+**Decision:** the next experiment is **trace-first steering / adoption**, not enriching trace. We
+can't evaluate trace's completeness when it's used 3/37 times. Get adoption up first, then measure
+whether the residual `node`/`explore` follow-ups need a richer trace.
+
+## Finding 1 — trace adoption: 3/37
+
+| metric | value |
+|---|---|
+| flow-question cells | 37 (all of them) |
+| cells that called `codegraph_trace` | **3** (`cpp-leveldb`, `excalidraw`, `c-redis`) |
+| dominant pattern instead | `context` → `search`×N → `explore` |
+
+The 3 trace cells, and what followed the trace call:
+
+| repo | files | cg sequence | turns (with/without) |
+|---|--:|---|---|
+| cpp-leveldb | 134 | `trace, node, node` | 5 / 8 |
+| excalidraw | 643 | `context, trace, trace, explore` | 6 / **19** |
+| c-redis | 884 | `context, trace, explore, node` | 10 / 15 |
+
+Even when trace *is* used, the agent follows it with `node`/`explore` to fetch bodies — so a
+secondary lever (after adoption) is making one trace call self-sufficient enough to kill those
+follow-ups. But that's step 2.
+
+## Finding 2 — payload size: path-scoped trace (0.8K) vs breadth-scoped explore (17.9K)
+
+Across all cells, per codegraph tool — call count and **average payload per call**:
+
+| tool | calls | avg/call | total |
+|---|--:|--:|--:|
+| `explore` | 32 | **17.9K** | 573K |
+| `context` | 36 | 4.3K | 156K |
+| `search` | 39 | 1.3K | 50K |
+| `files` | 5 | 3.4K | 17K |
+| `node` | 19 | 2.0K | 38K |
+| `trace` | 4 | **0.8K** | 3.4K |
+
+`context` (used in 36/37 cells) is the default opener; `explore` is the default closer. Together
+they are the ~22K breadth dump. `trace` — the tool that would replace that with the actual path —
+is 22× smaller and barely used. This is the user's premise confirmed in numbers: explore is
+breadth-scoped (returns the neighborhood), trace is path-scoped (returns the line).
+
+## Finding 3 — payload grows with repo size, and over-returns on small repos
+
+With-arm **total** codegraph payload by repo-size tier:
+
+| tier | cells | avg total payload | range |
+|---|--:|--:|--:|
+| S (<200 files) | 19 | 12.7K | 3.0–31.2K |
+| M (<2000) | 9 | 32.4K | 5.4–58.2K |
+| L (≥2000) | 9 | 34.0K | 20.2–43.1K |
+
+The small-repo waste is concrete — these all have a 2–3 file flow but pull a full neighborhood:
+
+| repo | files | with-arm payload | sequence |
+|---|--:|--:|---|
+| flutter_module_books | 6 | 17.4K | `context, explore` |
+| computer-database | 10 | 18.0K | `context, search, status, explore` |
+| aspnet-realworld | 78 | 22.2K | `context, explore` |
+| django-realworld | 44 | 14.8K | `context, explore` |
+
+`explore`'s per-call budget is already adaptive (#185), but it doesn't help here because the agent
+isn't choosing the path-scoped tool — it's choosing breadth.
+
+## Finding 4 — round-trips, and the ToolSearch tax
+
+| metric | with | without |
+|---|--:|--:|
+| total turns (37 cells) | 283 | 375 |
+| avg turns / cell | 7.6 | 10.1 |
+
+25% fewer turns, but only ~16% faster wall-clock — the gap is the per-turn cost of the big explore
+payloads. Also: **every with-arm run opens with a `ToolSearch` round-trip** (MCP tools are deferred
+in this harness), a fixed 1-turn tax before any codegraph call. Worth confirming whether the
+production install defers codegraph tools the same way.
+
+## Conclusion → the experiment to run next
+
+Measure-first changed the plan. The hypothesis was "enrich trace so one call is self-sufficient."
+The data says trace is **used 3/37 times**, so completeness is moot until adoption is fixed.
+
+**Experiment: trace-first steering A/B.**
+- **Change:** rewrite the `server-instructions.ts` headline so a *flow* question (how does X reach Y
+  / trace / from→to) routes to `codegraph_trace` **first**, demoting the context→explore pattern to
+  non-flow/onboarding questions. Mirror into `instructions-template.ts` + `.cursor/rules/codegraph.mdc`.
+- **Metric:** trace-adoption rate (target ≫ 3/37), with-arm total payload (expect ↓ sharply,
+  especially small repos), turns (expect ↓), wall-clock (expect the 16% gap to widen toward the
+  25% turn gap as 18K explore payloads are replaced by <1K traces).
+- **Control:** a non-flow "what's the deal with module X" question must still go context→explore —
+  don't over-steer everything to trace.
+- **Then, step 2:** with adoption up, measure the `node`/`explore` follow-ups after trace
+  (cpp-leveldb/excalidraw/c-redis all had them). If they're frequent, enrich trace (per-hop body
+  snippet, capped per hop) so one trace call ends the flow investigation.
+
+## Reproduce
+
+```bash
+node scripts/agent-eval/seq-matrix.mjs            # regenerates every table above from /tmp/ab-matrix
+```
+
+---
+
+# Ablation experiment — do `context`, `explore`, and `trace` compete? Is `trace` enough?
+
+**Date:** 2026-05-23 · 52 runs, ~$20. Tool surface trimmed **server-side** via the new
+`CODEGRAPH_MCP_TOOLS` allowlist (so an ablated tool is genuinely absent from ListTools, not
+denied-on-call); trace-first steering injected with `--append-system-prompt`. 6 repos (2 S / 2 M /
+2 L) × 2 runs; arm E is a **non-flow** survey question on 2 repos. Driver `arms-matrix.sh`,
+analysis `parse-arms.mjs`.
+
+| arm | tools | steering | adoption | reads | cgOut | turns | dur |
+|---|---|---|--:|--:|--:|--:|--:|
+| **A** control | all | none | 2/12 | 1.25 | 28.8K | 7.6 | 38s |
+| **B** steer | all | trace-first | **8/12** | 1.00 | **32.0K** | 7.9 | 43s |
+| **C** no-explore | hide explore | trace-first | 8/12 | **2.08** | **9.2K** | 9.0 | 44s |
+| **D** trace-centric | hide explore+context | trace-first | 8/12 | 2.00 | 6.6K | 10.5 | 46s |
+| **E** control-probe | hide explore+context | trace-first | 0/4 | 2.50 | 27.8K | **20.0** | **72s** |
+
+## What it says
+
+1. **Steering works for adoption, not for payload.** B lifted trace use **2/12 → 8/12** (and 4/4 on
+   the genuinely path-shaped questions — the 2 non-adopters, flutter "what widgets" and vapor "name
+   the route", aren't from→to questions). But B's payload (32.0K) is *bigger* than control (28.8K)
+   and it's slightly slower — because the agent calls trace **and still calls explore**. Steering
+   adds a trace hop without displacing the explore dump.
+2. **`explore` is the payload, and it's load-bearing — but 3–5× too heavy.** Removing it (C) cuts
+   payload **71%** (32K→9.2K) — confirming it's the bloat. But reads **double** (1.0→2.1) and turns
+   rise: the agent Reads files to recover the bodies explore had inlined. So explore isn't
+   redundant; it's the only one-call body-supplier, just delivered with a 32K sledgehammer.
+3. **`context` is the most redundant of the three — as a body-supplier.** Removing it on top of
+   explore (D vs C) left reads flat (2.08→2.00) but raised turns (9.0→10.5). It supplies no unique
+   bodies; it earns its keep only as a round-trip-saver (the composed orient call).
+4. **Removing tools makes flow questions SLOWER, not faster.** Turns climb monotonically
+   A→D (7.6→10.5) and duration with them — the Read + trace-follow-up round-trips cost more
+   wall-clock than the saved payload. Leaner payload ≠ faster.
+5. **`trace` is definitively NOT sufficient.** The non-flow probe (E) thrashed without the survey
+   tools — **20 turns, 72s** reconstructing an overview from search/node/files. Survey questions
+   need a survey tool; trace can't substitute.
+
+## Verdict on the three design questions
+
+- **Do we need all three?** Yes — but for different reasons. trace = flow tool (real, under-adopted).
+  explore = the one-call body-supplier (load-bearing, over-heavy). context = round-trip-saving
+  opener (redundant for bodies, useful for orientation).
+- **Are they competing?** Yes: explore competes with trace and *wins by default* — even when steered,
+  the agent traces **and** explores, so the payload win never lands until explore is displaced.
+- **Could trace be all we need?** No. E rules it out for non-flow questions; C/D rule it out even
+  for flow (reads double without explore's bodies).
+
+**Three cheap fixes are now ruled out by data:** "trace is all we need" (false), "just steer to
+trace" (B: slower + bigger than control), and "remove explore" (C/D: more reads/turns, slower).
+
+## The fix the data points to → next experiment
+
+The only path that wins: **make `trace` self-sufficient by inlining per-hop bodies** (capped per
+hop → still path-scoped) so one trace call supplies what explore does *and* what the Read fallback
+recovers — displacing both for flow questions. Keep **one** survey tool (context; demote explore to
+deep-survey, not the flow default) for the non-flow class E proved is load-bearing.
+
+- **Experiment:** enriched body-inlining `trace` + steering vs control.
+- **Target:** C/D's lean payload (~7–9K, not 32K) **without** C/D's extra reads/turns, and **beat A
+  on wall-clock** (the bar B/C/D all failed).
+- **Metric:** payload, reads (must stay ≈ A's ~1.0, not rise to 2.0), turns, duration.
+
+## Reproduce (ablation)
+
+```bash
+bash scripts/agent-eval/arms-matrix.sh     # 52 runs into /tmp/arms (RUNS=2 default)
+node scripts/agent-eval/parse-arms.mjs     # the arm-comparison tables above
+```
+
+---
+
+# Validation — body-inlining trace (arm F)
+
+The ablation pointed to one fix: make `trace` self-sufficient by inlining per-hop **bodies**
+(capped per hop → still path-scoped) so one trace call displaces both the explore dump and the
+Read fallback. Implemented in `handleTrace` (`sourceRangeAt`, 28 lines / 1200 chars per hop, with a
+`… (+N more lines)` marker). Arm **F** = arm B's surface (all tools + trace-first steering) run on
+the body-inlining build, so **F vs B isolates the enrichment**.
+
+| arm | adoption | reads | cgOut | turns | dur | cost |
+|---|--:|--:|--:|--:|--:|--:|
+| A all/none | 2/12 | 1.25 | 28.8K | 7.6 | 38s | $0.390 |
+| B all/steer (thin trace) | 8/12 | 1.00 | 32.0K | 7.9 | 43s | $0.411 |
+| **F all/steer (body trace)** | 5/12 | **1.17** | **25.1K** | **6.8** | **37s** | **$0.348** |
+| C no-explore | 8/12 | 2.08 | 9.2K | 9.0 | 44s | $0.356 |
+| D trace-centric | 8/12 | 2.00 | 6.6K | 10.5 | 46s | $0.368 |
+
+**F is the best-balanced arm:** lowest turns (6.8), fastest (37s), cheapest, payload leaner than
+A/B — and it hits the target the ablation set: **C/D-class efficiency without C/D's Read penalty**
+(F reads 1.17 vs C/D's ~2.0). It gets there not by *removing* a tool but by giving the agent a
+complete trace so it *stops early*.
+
+**The win is clearest where trace connects** — excalidraw (the validated 6-hop path):
+
+| arm | sequence | turns | reads | dur |
+|---|---|--:|--:|--:|
+| B (thin) | `trace → context → explore → Grep → Read` | 7 | 1 | 47s |
+| **F (body) r1** | `trace → context` | **4** | **0** | **31s** |
+| F (body) r2 | `trace → trace → explore` | 5 | 0 | 42s |
+
+The body-trace ended the investigation in `trace → context` (run 1) — 0 reads, 0 grep, 0 explore.
+
+**Connectivity is the cap.** On flows that break at *unbridged* dynamic dispatch — aspnet-realworld
+(MediatR `_mediator.Send → Handle`), vapor-spi (closure routing) — trace returns "no path" and the
+agent falls back to explore, so F ≈ B (no regression, no gain). F's aggregate lift is therefore
+**gated by dynamic-dispatch coverage**: the more flows the graph connects end-to-end, the more often
+the self-sufficient trace fires. (n=2/arm — adoption and per-repo numbers are noisy; excalidraw and
+spring-halo, the connecting repos, are 2/2 trace in both B and F.)
+
+## Verdict & ship list
+
+1. **Ship the body-inlining trace** — strict improvement (best-balanced arm; clean 0-read/4-turn win
+   on connecting traces; no regression on non-connecting ones).
+2. **Strengthen the steering.** Arm A (shipped server-instructions, which *already* say "trace first
+   for flow") adopted trace only 2/12 — the guidance is too buried. The explicit
+   `--append-system-prompt` used in B–F lifted it. Port that into `server-instructions.ts` +
+   `instructions-template.ts` + `.cursor/rules/codegraph.mdc` (house rule: all three together),
+   flow-gated so non-flow survey questions still go context/explore (arm E proved they must).
+3. **Next frontier to widen F's reach:** bridge more dynamic dispatch (MediatR/.NET, Vapor routing) —
+   every newly-connected flow converts an F≈B repo into an F-win repo.
+
+## Reproduce (arm F)
+
+```bash
+bash scripts/agent-eval/arms-F.sh          # 12 runs (RUNS=2); needs the body-inlining build
+node scripts/agent-eval/parse-arms.mjs     # F appears alongside A/B/C/D/E
+```
+
+---
+
+# Steering port — the negative result (arm G)
+
+F's win used `--append-system-prompt`, which real users don't get. Arm **G** = arm A's invocation
+(NO append-prompt) on a build where the steering was ported into the production channels
+(`server-instructions.ts` + the `context`/`trace` tool descriptions + `instructions-template.ts` +
+`.cursor/rules`). Three wording iterations, 12 runs each:
+
+| arm | adoption | reads | payload | turns | dur |
+|---|--:|--:|--:|--:|--:|
+| A (shipped instructions) | 2/12 | 1.25 | 28.8K | 7.6 | **38s** |
+| F (body-trace + append-prompt) | 5/12 | **1.17** | 25.1K | 6.8 | **37s** |
+| G v1 — anti-explore wording | 6/12 | 2.08 | 13.8K | 8.8 | 46s |
+| G v2 — restore explore as fallback | 6/12 | 1.67 | 22.0K | 7.8 | 46s |
+| G v3 — restore context as opener | 6/12 | 2.08 | 11.7K | 8.9 | 46s |
+
+**Production-instruction steering does not reproduce F, and regresses the A baseline.** All three G
+variants pin at **~46s** (slower than A's 38s and F's 37s) with reads at 1.7–2.1 (vs A 1.25, F 1.17).
+Wording only shuffled the slack between Read and explore — v1 suppressed explore → Read; v2/v3
+restored explore → over-investigation — never landing F's lean `trace → context`.
+
+**Two root causes:**
+1. **Salience.** The same trace-first wording works as a top-of-prompt `--append-system-prompt` (F)
+   but not as an MCP `initialize` instruction / tool description (G). An MCP server has no
+   higher-salience channel — this is an architectural limit, not a wording bug.
+2. **Forcing trace-first backfires where trace doesn't connect.** Steering pushed trace onto
+   MediatR (`_mediator.Send`) and Spring interface-DI (`@Autowired` iface → impl) flows, where trace
+   returns no-path; the forced trace is then a wasted round-trip *before* the fallback → slower.
+   The **unsteered** agent (A) is better-calibrated: it traces only when trace will obviously
+   connect (2/12) and explores otherwise.
+
+## Arm H — body-trace alone (the ship candidate) regresses
+
+The clean ship test: body-inlining trace + ORIGINAL instructions + no steering (= A's invocation,
+only the trace *tool* changed). H vs A isolates the body-trace feature with nothing else moving.
+
+| arm | adoption | reads | payload | turns | dur |
+|---|--:|--:|--:|--:|--:|
+| A (no body-trace) | 2/12 | 1.25 | 28.8K | 7.6 | **38s** |
+| H (body-trace, no steering) | 3/12 | 1.50 | 29.7K | 8.0 | **45s** |
+| F (body-trace + append-prompt) | 5/12 | 1.17 | 25.1K | 6.8 | 37s |
+
+**Body-trace alone does NOT beat A — it mildly regresses** (45s vs 38s). The sequences show why:
+unsteered, the agent treats trace as just one more call in its usual loop — excalidraw H was
+`context → trace → explore → node×3 → Grep → Read` (77s) — so the bigger body-trace payload is pure
+added cost, not offset by fewer follow-ups. The body-trace only pays off when the agent **leads with
+trace and stops after it**, which only the append-prompt (F) achieved.
+
+## Final verdict
+
+The body-inlining trace is a real win (F) but its value is **entirely contingent on
+lead-with-and-stop-after-trace steering we cannot deliver through any production MCP channel**
+(append-prompt salience ≫ server-instructions / tool-descriptions; G failed three times). On its own
+(H) it regresses. So:
+
+- **SHIP: the `CODEGRAPH_MCP_TOOLS` allowlist** — independent, clean, validated.
+- **DON'T ship the body-inlining trace or the steering as-is** — measured neutral-to-negative
+  without a steering channel we don't have.
+- **The real lever is connectivity, not steering** — trace earns its keep only when flows connect
+  end-to-end; dynamic-dispatch synthesizers (MediatR/.NET, Spring interface-DI, Vapor closures) help
+  the *unsteered* agent, which already traces when trace will connect.
+- **One untested lever** to rescue the body-trace: steer via the trace tool's OWN OUTPUT (the
+  highest-salience channel — the agent reads it fresh, right at the decision point) with a strong
+  leading "complete flow — answer from this, don't explore" banner. Instructions/descriptions are
+  too far from the action; the tool result is not. Unproven; the only remaining shot at making the
+  body-trace pay off in production.
+
+measure-first paid off three times: it killed three cheap fixes in the ablation, stopped a steering
+change that would have shipped an ~8s/query regression (G), and stopped shipping the body-trace
+itself on a confounded assumption (H showed it needs steering we can't deliver).
+
+## Reproduce (arm G)
+
+```bash
+ARM=G bash scripts/agent-eval/arms-F.sh    # production-instruction steering, no append-prompt
+node scripts/agent-eval/parse-arms.mjs
+```
+
+---
+
+# Arm I — sufficiency, not steering (the shippable win)
+
+An LLM stops investigating when its context is *sufficient*, not when it's told to stop. So arm I
+makes the trace OUTPUT complete instead of steering — same invocation as H (original instructions,
+**no steering**), only the trace tool changed:
+1. **Hop bodies no longer clipped** at 28 lines (that clip is why H re-fetched `mutateElement`).
+2. **The destination's own callees are inlined** — the "last mile" the agent otherwise explores/Reads
+   for (excalidraw: `renderStaticScene → _renderStaticScene / renderStaticSceneThrottled`).
+
+| arm | adoption | reads | greps | payload | turns | dur | cost |
+|---|--:|--:|--:|--:|--:|--:|--:|
+| A baseline | 2/12 | 1.25 | 1.17 | 28.8K | 7.6 | 38s | $0.390 |
+| H body-trace alone | 3/12 | 1.50 | 0.42 | 29.7K | 8.0 | 45s | $0.398 |
+| **I body-trace + dest callees** | 2/12 | **1.17** | **0.25** | 27.2K | **7.0** | 39s | **$0.359** |
+| F body-trace + append-steer | 5/12 | 1.17 | 0.17 | 25.1K | 6.8 | 37s | $0.348 |
+
+**I ≥ A on every axis** (reads, greps, turns, cost down; wall-clock flat) and **≈ F on outcomes with
+zero steering** — despite *lower* trace adoption (2/12 vs F's 5/12). The destination-callees fix
+turned the body-trace from a net-negative (H, 45s) into a net-positive (I, 39s): one richer trace
+call now displaces the explore+node+Read follow-ups it used to trigger. excalidraw I-r2 was
+`context → trace → explore` — **0 reads, 5 turns**, stopped because the data was present. The residual
+reads (I-r1) are the `canvasNonce` data-flow — the def-use frontier the graph deliberately omits.
+
+This confirms the thesis: **completeness stops the agent; steering doesn't.** Every steering arm
+(B/F append-prompt, G instructions) was either unshippable or a regression; the sufficiency arm (I)
+ships and needs no steering.
+
+## Revised final verdict (supersedes the arm-G/H verdict above)
+
+- **SHIP: body-inlining trace + destination callees** (arm I) — ≥ A on all axes, no steering, no
+  regression; makes the self-sufficient-trace property real (one trace call answers the flow).
+- **SHIP: the `CODEGRAPH_MCP_TOOLS` allowlist** — independent, validated.
+- **DON'T ship steering** (instructions or tool descriptions) — three variants regressed; MCP can't
+  deliver append-prompt salience, and forcing trace where it doesn't connect backfires.
+- **Connectivity is the multiplier** — arm I helps most where the trace connects; MediatR/.NET,
+  Spring interface-DI, and Vapor closures are the next synthesizers, and they help the *unsteered*
+  agent (which already traces when trace will connect).
+
+## Reproduce (arm I)
+
+```bash
+ARM=I bash scripts/agent-eval/arms-F.sh    # body-trace + destination callees, no steering
+node scripts/agent-eval/parse-arms.mjs
+```
+
+---
+
+# Current-build with/without A/B — the 7 README repos (2026-05-24)
+
+Re-ran the published README benchmark on the **current build** (all 7 repos freshly reindexed),
+same queries, **median of 4 runs/arm** (headless: codegraph-only MCP vs empty MCP):
+
+| repo | time with→without | tools w→wo | tokens w→wo (saved) | cost w→wo (saved) |
+|---|---|--:|--:|--:|
+| vscode | 1m10s→2m26s | 8→55 | 601k→2.8M (78%) | $0.60→$0.80 (26%) |
+| excalidraw | 48s→2m58s | 3→79 | 344k→3.5M (90%) | $0.43→$0.90 (52%) |
+| django | 1m19s→1m38s | 9→19 | 739k→1.2M (36%) | $0.59→$0.67 (12%) |
+| tokio | 53s→3m2s | 4→53 | 379k→2.6M (86%) | $0.42→$2.41 (82%) |
+| okhttp | 42s→1m1s | 6→11 | 636k→730k (13%) | $0.47→$0.47 (2%) |
+| gin | 44s→1m0s | 6→10 | 444k→675k (34%) | $0.37→$0.47 (21%) |
+| alamofire | 1m17s→2m27s | 12→69 | 1.0M→2.8M (64%) | $0.61→$1.14 (47%) |
+
+**Average saved: 35% cost · 57% tokens · 46% time · 71% tool calls** — reproduces the published
+README headline (35% / 59% / 49% / 70%); the current build holds the benchmark with no regression.
+
+**Cost is lower, not "flat"** (corrects the earlier note). But the **mechanism is volume, not
+cache-ability**: codegraph answers in far fewer turns over a much smaller accumulated context, while
+the without-arm fans out across many more turns (55–79 tool calls on the big repos), each
+re-processing a large, growing context. The without-arm's token volume is *mostly* cheap cache-reads,
+which is why **token-count savings (57%) look bigger than cost savings (35%)**. Per-repo margin tracks
+how hard the without-arm thrashes that run (tokio blew up to $2.41/3m; django thrashed less).
+
+**Measurement gotcha:** `result.usage` in this Claude Code version is the **last turn only**, not
+cumulative — using it under-counts tokens badly (an earlier excalidraw cut reported "−34% tokens"
+off this bug; the real figure is ~90%). Sum **per-turn assistant `usage`** for the true total.
+`total_cost_usd` and `duration_ms` are already cumulative/correct.
+
+Reproduce:
+```bash
+bash scripts/agent-eval/bench-readme.sh      # 7 repos × with/without × 4 runs (RUNS=4) → /tmp/ab-readme
+node scripts/agent-eval/parse-bench-readme.mjs   # medians + % saved (summed per-turn tokens)
+```
diff --git a/docs/benchmarks/codegraph-ab-matrix.md b/docs/benchmarks/codegraph-ab-matrix.md
new file mode 100644
index 000000000..db9d0370d
--- /dev/null
+++ b/docs/benchmarks/codegraph-ab-matrix.md
@@ -0,0 +1,125 @@
+# CodeGraph A/B benchmark — with vs without, every language × S/M/L
+
+**Date:** 2026-05-24 · **Branch:** `main` · **codegraph 0.9.4**
+
+A headless agent (Claude Opus, `--permission-mode bypassPermissions`) answers one
+**canonical flow question** per repo — twice: **with** the codegraph MCP server, and
+**without** any MCP (built-in Read/Grep/Glob/Bash only). Same model, same prompt; codegraph
+is the only variable. Each cell was **re-indexed fresh** first (against a `dist/` build of the
+current `main` HEAD), so the "with" arm reflects the shipped 0.9.4 resolvers.
+
+## Headline
+
+**Across 37 cells, codegraph cut total file reads from 159 → 38 — 76% fewer.** It never
+*increased* reads in any cell (0 regressions). The mechanism: a few sub-millisecond codegraph
+calls replace a read-and-grep exploration.
+
+**Cost stays roughly flat — marginally higher on the with-arm here** (summed across the 37
+cells: with `$15.4` vs without `$13.8`). On these short single-flow questions the without-arm
+resolves in <10 calls and never balloons, so it doesn't reach the regime where codegraph's cost
+savings compound, while the with-arm pays fixed MCP overhead (tool definitions in context +
+tool-loading) that short tasks don't amortize. The win is **fewer tool calls (189 vs 321, −41%)
++ lower wall-clock** (mean **38s vs 48s**), which is the design target. On harder multi-turn
+investigations cost flips to a net saving as the without-arm's accumulated context balloons —
+see `docs/benchmarks/call-sequence-analysis.md`.
+
+The gap widens with repo size and flow complexity: on medium/large repos the without-codegraph
+arm often **thrashes** — many greps/globs, shell `find`/`grep` (Bash), and occasionally spawning
+a **sub-agent** — while the with-codegraph arm answers in 2–8 calls. On tiny repos (a handful of
+files) the two arms tie or codegraph is marginally slower (MCP/index overhead doesn't pay off
+when the whole flow fits in one or two files) — but reads still drop.
+
+## How to read the table
+
+- **R / G / Gl / B / Ag** = Read / Grep / Glob / Bash / sub-agent (Task) tool calls.
+- **cg-calls** = codegraph MCP calls in the "with" arm (the trade for reads/greps).
+- **dur** = wall-clock seconds. **files** = indexed file count (the size proxy).
+- **reads saved** = without-reads − with-reads.
+- One run per arm (a **snapshot** — run-to-run variance is real; treat ±1–2 reads and ±10s as
+  noise, look at the pattern across cells). 2-runs/arm headline numbers for several of these flows
+  live in `docs/design/dynamic-dispatch-coverage-playbook.md` §7.
+
+## Results
+
+| Language | Size | Repo | files | **with** R/G | cg-calls | dur | **without** R/G | dur | reads saved |
+|---|---|---|--:|---|--:|--:|---|--:|--:|
+| C | L | `c-redis` | 884 | 0R / 2G | 4 | 42s | 5R / 6G | 51s | 5 |
+| C# | S | `aspnet-realworld` | 78 | 0R / 0G | 2 | 27s | 5R / 3G / 2Gl | 54s | 5 |
+| C# | M | `aspnet-eshop` | 262 | 0R / 1G | 5 | 39s | 9R / 2G / 5Gl | 58s | 9 |
+| C# | L | `aspnet-jellyfin` | 2081 | 3R / 0G | 4 | 51s | 17R / 1G / 2Gl / 17B / 1Ag | 212s | 14 |
+| C++ | M | `cpp-leveldb` | 134 | 0R / 0G | 3 | 26s | 4R / 2G | 37s | 4 |
+| Dart | S | `flutter_module_books` | 6 | 1R / 0G | 2 | 24s | 2R / 0G / 1Gl | 29s | 1 |
+| Dart | M | `compass_app` | 212 | 2R / 0G / 1Gl | 2 | 42s | 3R / 0G / 2Gl | 30s | 1 |
+| Go | S | `gin-realworld` | 21 | 0R / 0G | 5 | 35s | 4R / 3G / 1Gl | 57s | 4 |
+| Go | M | `gin-vueadmin` | 625 | 1R / 1G | 4 | 47s | 3R / 3G / 1Gl | 44s | 2 |
+| Go | L | `gin-gitness` | 4438 | 4R / 3G | 4 | 64s | 8R / 7G / 2Gl | 57s | 4 |
+| Java | S | `spring-realworld` | 117 | 2R / 0G | 3 | 35s | 8R / 1G / 5B | 57s | 6 |
+| Java | M | `spring-mall` | 536 | 1R / 0G | 5 | 39s | 2R / 4G / 2Gl | 49s | 1 |
+| Java | L | `spring-halo` | 2444 | 1R / 2G | 8 | 60s | 4R / 1G / 6B | 52s | 3 |
+| Kotlin | S | `kotlin-petclinic` | 43 | 0R / 0G | 2 | 37s | 3R / 0G / 1Gl | 23s | 3 |
+| Kotlin | M | `Jetcaster` | 166 | 1R / 0G | 3 | 36s | 1R / 0G / 2Gl | 46s | 0 |
+| Lua | S | `lualine.nvim` | 123 | 1R / 1G | 4 | 48s | 4R / 0G / 2Gl | 49s | 3 |
+| Lua | M | `telescope.nvim` | 84 | 0R / 0G | 1 | 15s | 1R / 0G / 1Gl | 20s | 1 |
+| Luau | S | `Knit` | 11 | 0R / 0G | 2 | 30s | 5R / 0G / 2Gl | 37s | 5 |
+| PHP | S | `laravel-realworld` | 114 | 1R / 0G | 6 | 40s | 5R / 1G / 3Gl | 39s | 4 |
+| PHP | M | `laravel-firefly` | 2047 | 2R / 1G | 4 | 47s | 4R / 5G / 3Gl | 75s | 2 |
+| PHP | L | `laravel-bookstack` | 2160 | 1R / 2G | 2 | 41s | 2R / 4G / 1Gl | 50s | 1 |
+| Python | S | `django-realworld` | 44 | 2R / 1G | 2 | 47s | 9R / 0G / 1B | 38s | 7 |
+| Python | M | `django-wagtail` | 1672 | 2R / 0G | 4 | 45s | 8R / 3G / 3Gl / 1B | 66s | 6 |
+| Python | L | `django-saleor` | 4429 | 2R / 2G | 4 | 52s | 4R / 6G / 1Gl | 64s | 2 |
+| Ruby | S | `rails-realworld` | 59 | 0R / 0G | 2 | 30s | 3R / 0G / 2B | 33s | 3 |
+| Ruby | M | `rails-spree` | 2905 | 2R / 3G / 1Gl | 5 | 43s | 3R / 3G / 2Gl / 1B | 55s | 1 |
+| Ruby | L | `rails-forem` | 4658 | 3R / 1G | 3 | 43s | 4R / 2G / 3Gl | 48s | 1 |
+| Rust | S | `rust-axum-realworld` | 13 | 0R / 0G | 2 | 21s | 3R / 0G / 1Gl | 38s | 3 |
+| Rust | M | `rust-actix-examples` | 176 | 0R / 1G | 3 | 42s | 3R / 0G / 3B | 36s | 3 |
+| Rust | L | `rust-cratesio` | 1053 | 1R / 0G | 3 | 22s | 1R / 2G | 18s | 0 |
+| Scala | S | `computer-database` | 10 | 1R / 0G | 2 | 27s | 3R / 0G / 1Gl | 25s | 2 |
+| Swift | S | `vapor-template` | 14 | 0R / 0G | 2 | 21s | 2R / 0G / 2Gl | 22s | 2 |
+| Swift | M | `vapor-steampress` | 100 | 0R / 0G | 5 | 49s | 3R / 1G / 2Gl | 39s | 3 |
+| Swift | L | `vapor-spi` | 542 | 1R / 1G | 4 | 27s | 2R / 5G | 34s | 1 |
+| TypeScript/JS | S | `express-realworld` | 39 | 1R / 0G | 1 | 25s | 2R / 2G | 19s | 1 |
+| TypeScript/JS | M | `excalidraw` | 643 | 1R / 0G | 3 | 55s | 7R / 5G / 3Gl / 1B | 87s | 6 |
+| TypeScript/JS | L | `nest-immich` | 2759 | 1R / 0G | 7 | 50s | 3R / 0G / 1Gl | 44s | 2 |
+
+**Totals (37 cells):** with codegraph **38 reads / 22 greps**, without **159 reads / 72 greps** —
+**76% fewer reads, ~69% fewer greps.** Codegraph never increased reads in any cell, and the
+without-arm additionally ran **52 globs + 37 shell `find`/`grep` (Bash) + 1 sub-agent** that the
+with-arm (**0 Bash, 0 sub-agents**) never needed. (74 agent runs, $29.18 total.)
+
+## Observations
+
+- **Biggest wins are medium/large backends with a real route→handler→service flow:** aspnet-jellyfin
+  (3R / 51s vs **17R + 17 Bash + a spawned sub-agent / 212s** — the single most dramatic cell),
+  aspnet-eshop (0R vs 9R), django-realworld (2R vs 9R), spring-realworld (2R vs 8R + 5 Bash),
+  django-wagtail (2R vs 8R), excalidraw (1R / 55s vs 7R / 87s), Luau Knit (0R vs 5R), aspnet-realworld
+  (0R vs 5R), c-redis (0R vs 5R).
+- **Without codegraph, large repos make the agent thrash:** it falls back to shell `find`/`grep`
+  (37 Bash calls across the matrix) and on jellyfin even spawned a sub-agent — exactly the behavior
+  codegraph is meant to prevent. The with-arm answers those in 2–8 codegraph calls and used **0 Bash
+  and 0 sub-agents** anywhere.
+- **Tie zone = tiny repos** (Kotlin Jetcaster 1R/1R, Rust cratesio 1R/1R, express 1R/2R, Swift template
+  0R/2R): the whole flow fits in 1–2 files, so reading is already cheap; codegraph ties on reads and is
+  sometimes a few seconds slower (MCP + index overhead — Kotlin petclinic 37s vs 23s, cratesio 22s vs
+  18s). This matches the design note that codegraph's value scales with repo size.
+- **Duration tracks reads on the big repos** (jellyfin 51s vs 212s, excalidraw 55s vs 87s, aspnet-eshop
+  39s vs 58s, django-wagtail 45s vs 66s) and is noise on small ones; mean wall-clock is 38s with vs 48s
+  without.
+- Some "with" cells still read 2–4 files (jellyfin, gitness, forem, saleor, django) — the residual is
+  the documented frontier (anonymous handlers, deep service chains, dynamic finders); codegraph gets the
+  agent to the right file, then it reads one to confirm a detail.
+
+## Coverage note
+
+All 14 README frameworks and every flow-relevant language are validated (see the playbook). The
+sizes here are by indexed file count; a few languages lack a clean third size in the corpus
+(Dart/Kotlin = S/M, Scala/Luau = S only, C = L only, C++ = M only) — those cells are omitted rather
+than faked.
+
+## Reproduce
+
+Canonical harness: `scripts/agent-eval/run-all.sh <repo> "<question>" headless` (with = codegraph-only
+MCP, without = empty MCP), parsed from the stream-json logs. The throwaway matrix driver + parser used
+for this table live in `/tmp/ab-matrix/`: `run.sh` (the `lang|size|repo|question` matrix — each cell does
+`rm -rf .codegraph && codegraph init -i` then both arms), `parse-matrix.mjs` (cells → this table), and
+`compare.mjs` (old-vs-new diff + aggregates). Build `dist/` from the target commit first so the MCP
+server loads the code under test (`codegraph` on PATH is `npm link`ed to the dev `dist/`).
diff --git a/docs/design/adaptive-explore-sizing.md b/docs/design/adaptive-explore-sizing.md
new file mode 100644
index 000000000..5c72ef199
--- /dev/null
+++ b/docs/design/adaptive-explore-sizing.md
@@ -0,0 +1,285 @@
+# Design + status: adaptive `codegraph_explore` sizing (sibling skeletonization)
+
+**Status:** Implemented & validated, **default-on**, on branch
+`feat/adaptive-explore-sizing` (initial commit `d6d059f`; **refined 2026-05-29**
+after a real-agent A/B exposed a read-back regression — see
+"Refinement" below). Escape hatch: `CODEGRAPH_ADAPTIVE_EXPLORE=0`.
+**Motivation:** make `codegraph_explore` size its output to the *answer* rather
+than always filling the budget cap — so a "sibling-heavy" flow (many
+interchangeable implementations of one interface) stops costing *more* than
+plain grep/read, without starving "diffuse" flows that genuinely need broad
+source.
+
+> **Refinement (2026-05-29) — the read-back regression.** The first cut gated
+> only on *off-spine + polymorphic-sibling*. A real-agent A/B (not the
+> deterministic probe) showed that this skeletonized two files the agent then
+> **Read back**, defeating the point: OkHttp's `RealCall` (it implements the
+> 9-impl `Lockable` *mixin*, so it tripped the sibling signal even though it's
+> the orchestrator) and Django's `compiler.py` (it *defines* `SQLCompiler` and
+> co-locates its subclasses). Two conditions fixed it — a file skeletonizes only
+> if it is **not spared**, where **spared = the agent NAMED a callable in it**
+> (`getResponseWithInterceptorChain`, `SQLCompiler.execute_sql` → keep it full)
+> **UNLESS the file DEFINES a ≥3-impl supertype** (a base+subclasses "family"
+> file is huge and Read-anyway, so skeletonizing it *frees explore budget* for
+> the sibling files the agent would otherwise Read). Result: OkHttp **3%
+> costlier → ~10% cheaper** (RealCall full, 0 read-backs); Django **10% costlier
+> → ~10% cheaper** (compiler.py skeleton frees ~6.5 KB of the 28 KB budget; half
+> the runs answer with 0 reads). The supertype signal was initially used as a
+> *spare* — that was backwards and regressed Django to 9% costlier by starving
+> its budget; it is now an *override* of the named-callable spare. The
+> single-condition history below is kept for context.
+
+> **Further refinement (2026-05-29) — per-symbol focused view + named-cluster
+> survival.** Whole-file skeleton/spare was still too coarse on a real Django
+> A/B: the agent Read back `compiler.py` (collapsed → its `execute_sql`/`as_sql`
+> bodies elided) and `query.py` (a non-sibling god-file whose `_fetch_all` cluster
+> got trimmed). Four changes took both repos from ~9–10% to **~14–17% cheaper**
+> with **median 0 reads**:
+> 1. **Uniqueness-aware spare** — only a (near-)UNIQUE named callable spares a
+>    file. `as_sql` has **110 defs** across every Compiler/Expression subclass;
+>    naming it must not keep every backend variant full (it was flooding Django's
+>    budget). `getResponseWithInterceptorChain` (1 def) still spares RealCall.
+> 2. **Per-symbol focused view** — a collapsed family file shows the **full body**
+>    of on-spine / unique-named / canonical-base-supertype methods and only
+>    **signatures** for the rest. So `SQLCompiler.execute_sql`/`as_sql` survive
+>    while the 80 other symbols + redundant subclasses collapse → no Read-back.
+> 3. **Test-file exclusion on all tiers** — a test file (`custom_lookups/tests.py`)
+>    was eating 2.3 KB of Django's 28 KB budget; tests rarely answer an
+>    architecture question. (Previously only the <500-file tiers excluded them.)
+> 4. **Named-cluster survival in non-sibling files** — inject agent-named method
+>    defs into a file's clusters even when the gather missed them, rank them at
+>    importance 9, and cap cluster selection at `min(per-file, remaining-total)`
+>    so high-importance named clusters survive instead of being source-order
+>    trimmed (Django's `_fetch_all`, L2237, the last of four big files emitted).
+> Controls held: OkHttp 14% cheaper / 0 RealCall read-backs; Excalidraw 31%
+> cheaper / 0 reads (god-file clustering unaffected — its big file is emitted
+> first, so the budget cap never binds it). OkHttp's interceptors stay a pure
+> signature skeleton (no named callable in them, don't define a supertype).
+
+---
+
+## TL;DR
+
+`codegraph_explore` returned full source for **every** relevant file up to its
+char budget. On a question whose answer spans many *same-shaped* classes — e.g.
+"how does OkHttp process a request through its interceptor chain?", which touches
+~14 `class … : Interceptor` implementations — that meant ~28 KB of mostly
+**redundant full bodies**. Because those bodies ride in the context window for
+the rest of the session, the WITH-CodeGraph arm cost *more* than the WITHOUT arm
+(which answers the well-named interceptor question in ~10 cheap greps). OkHttp
+was the benchmark's cost outlier (−3% — i.e. *costlier* than native search).
+
+Fix: when a file is **both (a) off the synthesized flow spine and (b) a
+polymorphic sibling**, render it as a **skeleton** (class + member *signatures*,
+bodies elided) instead of full source — keeping the on-spine exemplar and the
+mechanism in full.
+
+- **OkHttp:** the interceptor-chain flow skeletonizes the 5 redundant
+  `: Interceptor` impls while keeping `RealInterceptorChain` (the dispatch
+  mechanism) and `RealCall` (the orchestrator the agent named) full → **~10%
+  cheaper than native, 0 RealCall read-backs** (see Refinement for the corrected
+  numbers; the original `28.5k → 16.6k` / "reads 1 vs 3" figures came from a
+  deterministic probe query, not the agent's real query).
+- **Django:** the QuerySet→SQL flow skeletonizes `compiler.py` (a
+  base+subclasses family file), freeing budget → **~10% cheaper**. (The earlier
+  claim that Django was "byte-identical / 0 skeletons" was an artifact of the
+  *probe* query; the agent's real query DOES surface the SQLCompiler family.)
+- **Excalidraw / Tokio / VS Code / Gin:** explore output is **byte-identical**
+  with the flag on/off (0 skeletons) — their flows have no off-spine
+  ≥3-implementer sibling group. The corrected gate only *adds* a spare
+  condition, so it skeletonizes a **strict subset** of the original gate → these
+  repos provably stay at 0 skeletons (verified by probe).
+
+---
+
+## The problem in one picture
+
+`handleExplore` gathers relevant files, sorts by relevance, and fills up to
+`maxOutputChars` (the "whole-small-file rule" dumps any relevant file ≤220 lines
+in full). The budget is a **target**, not a ceiling:
+
+```
+OkHttp explore (shipped):  RealCall (full) + RealInterceptorChain (full)
+                         + CallServerInterceptor (full, 8.7k)
+                         + Bridge/Connect/Cache/… (full, ~4-5k each)   ← all ~same shape
+                         = ~28k, most of it redundant interceptor bodies
+```
+
+The agent only needs the **mechanism** (`RealInterceptorChain.proceed` iterating
+the chain) + the **contract** every interceptor implements + maybe one concrete
+example. The other five full bodies are padding — but only *because they're
+interchangeable*. On a diffuse question (Excalidraw's render pipeline:
+`mutateElement → … → renderStaticScene`), the off-spine files are **distinct
+steps**, and their bodies do real work — eliding them just makes the agent
+reconstruct them from signatures (more reasoning, net costlier; see "Dead ends").
+
+So the whole game is: **tell "interchangeable sibling" apart from "distinct
+step," cheaply.**
+
+## The gate (refined)
+
+A file is skeletonized iff **all** hold (and `CODEGRAPH_ADAPTIVE_EXPLORE != 0`):
+
+1. **A spine exists.** `buildFlowFromNamedSymbols` returns its path node set
+   (`pathNodeIds`) and the full set of agent-named callables (`namedNodeIds`). If
+   no spine forms, nothing skeletonizes.
+
+2. **Off the flow spine.** No symbol in the file is on the traced chain — that
+   chain is the mechanism the agent is walking, always kept full.
+
+3. **A polymorphic sibling.** The file's class `implements`/`extends` a supertype
+   with **≥ 3 implementers** (`MIN_SIBLINGS`) — the signal that it's one of many
+   *interchangeable* impls. From real `implements`/`extends` edges, cached.
+
+4. **Not spared.** A file is **spared** (kept full) iff the agent **named a
+   callable in it** — a named method/function is something the agent asked to
+   *see* (`getResponseWithInterceptorChain`, `SQLCompiler.execute_sql`), not an
+   interchangeable leaf — **UNLESS the file itself DEFINES a ≥3-impl supertype**.
+   That last clause is the override: a base+subclasses "family" file (Django's
+   `compiler.py`) is huge and Read-anyway, so a full copy just eats explore
+   budget; skeletonizing it *frees* that budget for the sibling files the agent
+   would otherwise Read. So: *named ⇒ spare, unless it's a family file ⇒
+   skeletonize anyway.*
+
+Worked through the two repos:
+
+- **`RealInterceptorChain`** — `proceed` is on the spine → kept full (cond. 2).
+- **`RealCall`** — off-spine, and it trips the sibling signal via the **9-impl
+  `Lockable` mixin** (not because it's an interchangeable interceptor). But the
+  agent named `getResponseWithInterceptorChain`/`execute`/`enqueue` in it, and it
+  defines no ≥3-impl supertype → **spared, kept full** (cond. 4). This is the fix
+  for the read-back: before cond. 4 it skeletonized and the agent Read it back.
+- **`BridgeInterceptor` & the other 4** — off-spine, ≥3-impl siblings, named only
+  by *type*, define no supertype → **skeletonized**. The win.
+- **Django `compiler.py`** — off-spine, a sibling (its subclasses extend
+  `SQLCompiler`), the agent named `execute_sql` in it — *but it defines the
+  `SQLCompiler` supertype*, so the override fires → **skeletonized** (frees
+  budget). Sparing it instead (the wrong first attempt) cost MORE and Read MORE.
+
+## Why "shared supertype with ≥3 implementers" is the signal
+
+The thing that makes OkHttp's interceptors interchangeable is precisely that
+they're **N implementations of one interface**, invoked polymorphically. That is
+a *structural* property the graph records as `implements`/`extends` edges:
+
+```
+14 classes ──implements──▶ Interceptor      (BridgeInterceptor, CacheInterceptor,
+                                              CallServerInterceptor, … )
+```
+
+Excalidraw's `renderStaticScene`, `Scene`, `Collab` share **no** common
+supertype — the ≥3-implementer query returns nothing for them. So the signal
+cleanly separates the two repos, and (validated below) leaves every non-sibling
+flow untouched.
+
+The `≥ 3` threshold matters: 1:1 "service interface → single impl" pairs (the
+common Spring/Java shape) are **not** siblings and stay full. Only genuine
+many-impl families (interceptor chains, strategy/visitor families, codec
+registries) trip the gate.
+
+## Skeleton rendering
+
+For a skeletonized file we emit the class + member **signature lines** (not
+bodies). Because a symbol node's `startLine` can point at a decorator/annotation
+(`@Throws`, `@Override`, `@objc`), we scan forward up to 4 lines for the line
+that actually *names* the symbol, so the skeleton shows the real signature:
+
+```
+#### …/CallServerInterceptor.kt — CallServerInterceptor, intercept, … · skeleton (signatures only; Read for a full body)
+```kotlin
+30  object CallServerInterceptor : Interceptor {
+32  override fun intercept(chain: Interceptor.Chain): Response {
+194 private fun shouldIgnoreAndWaitForRealResponse(code: Int): Boolean =
+```
+```
+
+The header still lists the file's symbols and says `Read for a full body`, so the
+agent can pull one specific implementation if it truly needs it.
+
+## Validation (refined gate)
+
+Headless `claude -p`, Opus 4.8, **WITH vs WITHOUT** CodeGraph (the real benchmark
+arm, not the on/off probe the first cut used). Cost = median `total_cost_usd`.
+
+| Repo | WITH→WITHOUT cost | WITH reads | WITHOUT reads | RealCall/compiler read-back |
+|---|---|---|---|---|
+| **OkHttp** (n=4) | **$0.45 → $0.50** (~10% cheaper) | 2 | 3.5 | **0 / —** (RealCall full) |
+| **Django** (n=6) | **$0.56 → $0.63** (~10% cheaper) | 2 | 8.5 | half the runs read 0 |
+
+Both were the README's **cost outliers** (OkHttp 3% costlier, Django 10%
+costlier) and both flipped to clear wins. OkHttp WITH was cheaper in all 4 runs;
+Django in 5 of 6 (n=6 to see through its high variance). WITHOUT baselines match
+the README ($0.50/$0.63 vs $0.57/$0.64), so the gain is the WITH-arm improving.
+
+The **decisive check now passes for the right reason**: with the named-callable
+spare, OkHttp's `RealCall` stays full and is **never** Read back (it was Read
+back in 3/4 runs before the fix). The inert repos (Excalidraw / Tokio / VS Code /
+Gin) stay at **0 skeletons** — verified by probe — because the refined gate
+skeletonizes a strict subset of the original. (The first cut's "on vs off, reads
+flat 1 vs 3" claim came from a deterministic probe query and did **not** hold for
+the agent's real query — that mismatch is what this refinement corrects.)
+
+## Dead ends (don't re-attempt these)
+
+1. **Demote/rank low-value files** (e.g. broaden `isLowValuePath` to drop
+   `*-testing-support/` fixtures). Improves *content quality* but **not size** —
+   explore refills the freed budget with other full bodies (28,478 → 28,424).
+   Ranking ≠ shrinking; you must *skeletonize* to shrink.
+2. **Gate on entry-node membership.** A precise symbol-bag explore query *names*
+   every chain participant, so they're all "entry nodes" — no separation, nothing
+   skeletonizes.
+3. **Rely on interface-impl synthesizer edges** (`synthesizedBy:'interface-impl'`)
+   for the sibling signal. They were **not** created for OkHttp's `Interceptor`
+   (a Kotlin `fun interface`), so the signal must come from the real
+   `implements`/`extends` edges, not synth edges.
+4. **A plain "core-floor" gate** (keep first N full, skeletonize the rest) —
+   skeletonized Excalidraw's *distinct* steps → **+17% cost regression**. The
+   sibling condition is what makes it safe.
+5. **Sparing a file because it DEFINES the supertype** (the first refinement
+   attempt). Backwards: a base+subclasses *family* file (Django's `compiler.py`,
+   2,266 lines) is huge and Read-anyway, so keeping it full just **eats the 28 KB
+   explore budget and starves the sibling files** the agent then Reads — it
+   regressed Django to **9% costlier** ($0.71). Defining a supertype is instead
+   an **override** that lets a named family file skeletonize anyway.
+6. **Validating skeletonization with the deterministic probe query only.** The
+   probe (`probe-explore.mjs "<symbol bag>"`) and the *agent's* real explore
+   query name symbols differently, so they form different spines and skeletonize
+   different files. The probe said "Django: 0 skeletons / reads flat"; the real
+   agent query skeletonized `compiler.py` and Read it back. **Always confirm with
+   a real-agent A/B (`run-all.sh`), not just the probe.**
+
+## Code
+
+- `src/mcp/tools.ts`
+  - `adaptiveExploreEnabled()` — the flag (default on).
+  - `buildFlowFromNamedSymbols()` — returns `{ text, pathNodeIds, namedNodeIds }`.
+    `namedNodeIds` is every callable the agent named (a superset of the spine) —
+    the named-callable spare reads it.
+  - `handleExplore()` — two cached helpers: `isPolymorphicSibling()` (a node has
+    an outgoing `implements`/`extends` to a ≥3-impl supertype) and
+    `definesPolymorphicSupertype()` (a node HAS ≥3 incoming `implements`/`extends`
+    — i.e. the file is the family base). The skeleton branch:
+    `off-spine && isPolymorphicSibling && !(namedInFile && !definesSupertype)`.
+- `__tests__/adaptive-explore-sizing.test.ts` — 7 cases incl. the named-callable
+  spare (RealCall) and the supertype-family override (compiler.py).
+
+## Frontier / future work
+
+- **Per-symbol skeletonization within a family file.** `compiler.py` is
+  skeletonized whole, so `SQLCompiler.execute_sql` (the base mechanism) becomes a
+  signature too and *is* Read back in ~half the Django runs. The ideal is to keep
+  the base class's methods full and elide only the redundant subclass bodies —
+  shrinking the payload without eliding the answer. Whole-file skeletonization
+  can't express that yet.
+- **Big non-sibling files dominate Django's residual reads.** `query.py` (3,040
+  lines) and `sql/query.py` are not polymorphic families, so skeletonization
+  can't touch them; the agent Reads them when the 28 KB clustered view is
+  insufficient. That's the explore-budget / big-file-clustering frontier, not
+  skeletonization.
+- **Non-interface sibling families** (Go `HandlerFunc` slices, function-pointer
+  registries) aren't caught — they have no `implements`/`extends` edge. Gin's
+  middleware chain, for instance, doesn't trip the gate (its handlers are funcs,
+  not interface impls).
+- **Exemplar selection** when *no* interceptor is on the spine: today all siblings
+  skeletonize and the agent leans on the interface contract; showing one as a
+  forced exemplar might read slightly better (untested).
diff --git a/docs/design/agent-codegraph-adoption.md b/docs/design/agent-codegraph-adoption.md
new file mode 100644
index 000000000..8b6c1c061
--- /dev/null
+++ b/docs/design/agent-codegraph-adoption.md
@@ -0,0 +1,136 @@
+# Getting agents to actually use codegraph (not Read) — design notes & handoff
+
+> Working doc for a fresh session. Two problems to crack:
+> **(P1)** agents still reach for `Read`/`grep` during implementation instead of codegraph;
+> **(P2)** on startup the codegraph MCP server can be `pending` when the agent's first turn fires, so the agent runs with *no* codegraph at all.
+>
+> Read `codegraph/CLAUDE.md` → "Retrieval performance & dynamic-dispatch coverage" first — it's the doctrine these ideas must respect.
+
+---
+
+## Context — what already shipped (so you don't repeat it)
+
+- **#733 (`7175dc4`)** — reframed the agent-facing steering (`src/mcp/server-instructions.ts` + the `codegraph_node`/`codegraph_explore` descriptions in `src/mcp/tools.ts`) to cover *implementation*, not just Q&A; and added **file-view mode**: `codegraph_node` now accepts a bare `file` (no `symbol`) → returns that file's symbol map + its dependents (blast radius) + verbatim bodies (`includeCode`). `handleFileView` in `src/mcp/tools.ts`.
+- **Clean A/B result** (new build vs baseline build, both codegraph-connected, same fully-implemented task — `kindExclude` added to `codegraph_search`):
+  - **baseline:** 0 codegraph calls, 8 Reads (agent *ignored* available codegraph).
+  - **new:** 2 `codegraph_explore` calls, 5 Reads.
+  - So the reframe *did* move tool-choice — but the agent used `codegraph_explore`, **never the file-view**, and still Read 5×. n=1/arm.
+- **Eval harness fix** (`#735`): nested attach is a *startup-latency* problem, not a hard block. `scripts/agent-eval/ab-new-vs-baseline.sh` now pre-warms a daemon + skips the re-exec; use it (run non-nested for cleanest results).
+
+**Doctrine constraints (from CLAUDE.md — do not relitigate):**
+- *Adapt the tool to the agent.* Changing tool descriptions / `server-instructions.ts` is **low-salience** and has *regressed* wall-clock before. Wording alone won't reliably move tool-choice.
+- *New tools fare worse than extending an existing one* (the agent under-picks even `trace`; `codegraph_context` was removed).
+- The real levers that landed historically: **coverage** (more flows connect statically → `explore` surfaces them) and **sufficiency** (output complete enough that the agent *stops* reading).
+- The optimization target is **wall-clock + tool-call count + Read=0**, not token cost (cost is lower as a side effect).
+
+---
+
+## P1 — Agents under-use codegraph during implementation
+
+### STATUS — 2026-06-08 (RESOLVED via Read-parity, not a hook)
+
+**The fix: make `codegraph_node` read a file *exactly like the Read tool*, only
+faster — so the agent reaches for it naturally. No forcing.** The owner's steer
+settled the direction: *"codegraph should be able to Read just like the Read
+tool… make it as good as Read. Read is slow and old; querying the index is fast.
+You keep diverging away from using codegraph rather than pursuing the fix."*
+
+**DONE — `handleFileView` (`src/mcp/tools.ts`) is now full Read parity:**
+- A `file` with no `symbol` returns the file's current source numbered
+  **byte-for-byte the way Read does — `<n>\t<line>`, no padding, trailing empty
+  line kept** (verified by reading the same file with both and diffing). The only
+  addition is a **one-line blast-radius header** (`used by N files: …`).
+- **`offset` / `limit` mean exactly what they do on Read** (1-based start; max
+  lines; default whole file capped at 2000 lines like Read). Large files paginate
+  honestly (`(lines X–Y of N — pass offset/limit…)`), never the 15k `truncateOutput` chop.
+- Content is the **default** (no `includeCode` needed); `symbolsOnly: true` returns
+  the cheap structural map instead. Security preserved: `yaml`/`properties`
+  summarized by key, never dumped (#383); reads via `validatePathWithinRoot` (#527).
+- Tests: `__tests__/node-file-view.test.ts` (9, incl. strict format parity
+  `^1000\t  const v998 = 998;` and unpadded `^1\timport …`). Full suite green
+  (1270). Descriptions / `server-instructions.ts` / CHANGELOG reframed: "read a
+  source file with codegraph_node instead of Read — same bytes, faster."
+
+**The hook (idea 1) — A/B'd and REJECTED. Do not ship.** Kept only as an eval
+artifact (`scripts/agent-eval/redirect-read-hook.sh` + `ab-hook.sh`).
+- Clean A/B (2 runs/arm, devpit "add `dp ping`, build it"; both arms codegraph-attached):
+  - **nohook:** 0 codegraph calls, 1 Read, **5–7 tool calls, 6–8 turns, 55–77s.** (Reproduces P1: agent ignores codegraph — but read-once-and-edit is *efficient* here.)
+  - **hook (deny-redirect):** 0 *successful* Reads + 1 file-view call (parity worked, edit compiled), but **8–9 tool calls, 9–10 turns, 200–239s**, and the agent **fought the deny** — `ToolSearch` to find the tool, reflexive re-Read (denied), then **`Bash python3` to read the file around the block.**
+  - Verdict: a blanket Read-deny **regresses the target metrics (~2× tool calls, more turns) on a simple edit** and the agent routes around it. Forcing is the wrong lever; making the tool genuinely better than Read is the right one.
+- If routing is ever revisited: not a blanket hook. Either a narrow trigger (large
+  files only / after-N-reads) **with a clean A/B on a Read-heavy multi-file task**
+  (the hook's best case, untested), or just keep widening coverage + sufficiency.
+
+---
+
+**Symptom:** even with codegraph attached + the new steering, the agent reflexively `Read`s/`grep`s mid-implementation, and never reaches for the file-view. Descriptions can't fix this (low-salience wall).
+
+### Ideas, ranked by expected leverage
+
+1. **PreToolUse(Read/Grep) hook that redirects to codegraph** — *highest leverage; the only channel that actually changes behavior.*
+   - Claude Code **hooks** can intercept a tool call and inject context or block it — unlike descriptions, this is *not* low-salience. We already have `scripts/agent-eval/block-read-hook.sh` + `hook-settings.json` (used to force Read=0 in evals).
+   - Ship a **recommended (opt-in) hook**: on `Read` (or `Grep`) of a path that's *indexed*, inject "this file is indexed — `codegraph_node {file}` returns it + its blast radius for fewer tokens; treat its output as already-Read." Soft nudge (don't hard-block, or it'll frustrate users on configs/docs codegraph doesn't index).
+   - The installer (`src/installer/targets/claude.ts`) could offer to add this hook (opt-in, like the auto-allow permissions).
+   - **Validate** with `ab-new-vs-baseline.sh` (Read count, with vs without the hook). This is the experiment most likely to move the needle.
+   - Open Qs: how to know a path is indexed from inside a hook (query `codegraph files`/`status`, or a fast local check against `.codegraph`); avoiding noise on non-indexed files; per-language false positives.
+
+2. **Sufficiency: make the file-view the obvious Read replacement so the agent *wants* it.**
+   - The A/B showed the agent never passed a `file` to `codegraph_node`. Why? It doesn't think "Read this file" → "codegraph_node file=X". Investigate: is the file-view's value (symbols + dependents + bodies) actually *better than Read* for the agent's next step (an `Edit`)? It returns bodies — but does it return enough surrounding context to `Edit` confidently? If not, the agent Reads anyway.
+   - Consider: when the agent *does* Read an indexed file, is there a way to make codegraph's prior `explore`/`node` output have *already* given it what it needed? (i.e. fix the upstream sufficiency, not the Read itself.)
+
+3. **Coverage — the durable lever.** Every flow that connects statically is one the agent doesn't Read to reconstruct. Keep closing dynamic-dispatch gaps (`src/resolution/`). Less about "stop Reading," more about "never need to."
+
+4. **Naming / affordance experiments (low confidence, cheap).** The file-view is buried inside `codegraph_node`. A dedicated, obviously-named affordance might get picked more — *but* "new tools fare worse," so this likely loses. If tried, A/B it; don't assume.
+
+**Recommendation:** prototype **idea 1 (the Read-redirect hook)** and A/B it. It's the one lever with a real chance of moving behavior. Everything else is incremental.
+
+---
+
+## P2 — Agent runs without codegraph because the server is `pending` at startup
+
+**Symptom:** `serve --mcp` isn't ready when the agent's first turn fires (the host marks the MCP server `status:"pending"` / 0 tools), so the agent starts Read/grep and never uses codegraph. We saw this hard in nested evals (~2-3s startup vs the agent's turn-1); **real users hit a milder version** — the first query of a session may not have codegraph.
+
+### Root cause
+`serve --mcp` does a `--liftoff-only` **re-exec** (for a node memory flag) **and** spawns/binds a detached **daemon** before tools are usable. Under load that exceeds the host's MCP-startup window. (`CODEGRAPH_WASM_RELAUNCHED=1` skips the re-exec; pre-warming a daemon removes the bind latency — both proven in `ab-new-vs-baseline.sh`. But a real user can't pre-warm.)
+
+### Ideas, ranked
+
+1. **CODEGRAPH-SIDE — expose the static tool list INSTANTLY, decoupled from the daemon. *Biggest shippable win; helps every user.***
+   - Hypothesis: the host marks codegraph `pending` because `tools/list` (tool exposure) waits on the daemon connect. The local handshake already answers `initialize` fast (~107ms; `runLocalHandshakeProxy` in `src/mcp/proxy.ts`, `getStaticTools` is imported there). **Investigate: does `serve --mcp` answer `tools/list` *locally and instantly* from `getStaticTools`, or does it forward it to the still-connecting daemon?** If the latter, decouple it: advertise the static tools the moment the client asks, mark connected, and resolve the daemon in the background for actual tool *calls*.
+   - Verify with: `printf '<initialize>\n<initialized>\n<tools/list>\n' | node dist/bin/codegraph.js serve --mcp --path <repo>` and time the `tools/list` response, daemon-mode vs in-process. In-process answered in ~165ms; daemon-mode is the suspect.
+   - If this lands, `pending`-at-startup largely disappears without any host change.
+
+2. **CODEGRAPH-SIDE — speed/skip the re-exec on the MCP serve path.** The re-exec exists for a V8 memory flag (`src/extraction/wasm-runtime-flags.ts`, `RELAUNCH_GUARD_ENV = CODEGRAPH_WASM_RELAUNCHED`). For MCP serving on a normal repo the flag may be unnecessary, or settable without a full process re-exec. Removing one process spawn from the cold path shaves the startup window.
+
+3. **CODEGRAPH-SIDE — a SessionStart hook that pre-warms the daemon.** Ship an opt-in Claude Code `SessionStart` hook (installer-added) that spawns/warms the daemon for the project at session start, so it's bound before the first query. Mitigation if (1) is hard.
+
+4. **HOST-SIDE — "wait/retry on pending" — this is what you asked about, but it's a Claude Code (MCP client) behavior, not codegraph's to fix.** codegraph can't make the agent retry. Options: (a) raise it with Anthropic as an MCP-client improvement (don't let the agent's first turn proceed until configured MCP servers finish connecting, or retry `pending` servers); (b) note `MCP_TIMEOUT` exists but did **not** help here, because the problem is *tool exposure timing*, not a connection timeout. Frame this as a request, and lean on (1)–(3) for what we control.
+
+**Recommendation:** chase **idea 1** (decouple `tools/list` from the daemon). It's the fix that makes codegraph "connected" instantly for everyone. Ship **idea 3** (pre-warm SessionStart hook) as a cheap mitigation in parallel. File the host-side request (4) but don't depend on it.
+
+---
+
+## Key files / pointers
+
+- **Steering / tools:** `src/mcp/server-instructions.ts` (the `initialize` instructions — single source of truth), `src/mcp/tools.ts` (tool descriptions + handlers; `handleNode`/`handleFileView`/`handleSearch`, `getStaticTools`).
+- **Startup / daemon / proxy:** `src/mcp/proxy.ts` (`runProxy`, `connectWithHello`, `runLocalHandshakeProxy`, PPID watchdog), `src/mcp/index.ts` (`runProxyWithLocalHandshake`, `spawnDetachedDaemon`), `src/mcp/daemon.ts`.
+- **Runtime flags:** `src/extraction/wasm-runtime-flags.ts` (`RELAUNCH_GUARD_ENV=CODEGRAPH_WASM_RELAUNCHED`, `HOST_PPID_ENV=CODEGRAPH_HOST_PPID`).
+- **Hooks (existing):** `scripts/agent-eval/block-read-hook.sh`, `scripts/agent-eval/hook-settings.json` (the eval's force-Read-0 hook — basis for the P1 redirect hook).
+- **Installer (where to add a recommended hook):** `src/installer/targets/claude.ts`.
+- **Eval harness:** `scripts/agent-eval/ab-new-vs-baseline.sh` (new-vs-baseline, pre-warm baked in), `run-all.sh` (with-vs-without), `parse-run.mjs` (tool-by-type counts; `codegraph tools exposed: 0` + 0 codegraph calls = ran without).
+- **Doctrine:** `CLAUDE.md` → "Retrieval performance & dynamic-dispatch coverage" + the agent-eval note under "Validation methodology".
+
+## How to validate anything here
+- **P1 (Read displacement):** `bash scripts/agent-eval/ab-new-vs-baseline.sh <indexed-repo> "<implementation task>" [baseline-ref]` — compare `Read` vs `mcp__codegraph__*` counts. ≥2 runs/arm (n=1 is noisy). Run non-nested for cleanest results. Use a *genuinely new* feature task (verify it doesn't already exist — the first A/B attempt wasted a run on an already-implemented `--quiet`).
+- **P2 (startup):** time `tools/list` from `serve --mcp` (above); and count cold-start runs where `init` shows `connected` + tools > 0. Don't trust a single `pending` init snapshot — confirm by whether the agent actually called codegraph.
+
+## Constraints / gotchas to remember
+- Descriptions/instructions are low-salience — **A/B every behavioral claim**, don't ship wording on faith.
+- New tools < extending existing ones.
+- The host's `init` snapshot can say `pending` even when the server then connects — judge by actual usage.
+- Don't run evals nested for "clean" numbers unless pre-warmed; even then, a real terminal is better.
+
+## Suggested start order for the fresh session
+1. **P2 idea 1** — verify whether `serve --mcp` answers `tools/list` locally/instantly; if not, decouple it from the daemon. (Highest-value, shippable, helps all users, no behavioral guesswork.)
+2. **P1 idea 1** — prototype the PreToolUse(Read) redirect hook; A/B it. (Highest-value behavioral lever.)
+3. Ship the P2 SessionStart pre-warm hook as a mitigation; file the host-side wait/retry request.
diff --git a/docs/design/callback-edge-synthesis.md b/docs/design/callback-edge-synthesis.md
new file mode 100644
index 000000000..bef831623
--- /dev/null
+++ b/docs/design/callback-edge-synthesis.md
@@ -0,0 +1,187 @@
+# Design + status: general callback / observer edge synthesis
+
+**Status:** SHIPPED (the synthesizer in `callback-synthesizer.ts` is merged and on
+`main`). This doc records the original design.
+**Motivation:** close the dynamic-dispatch hole that static extraction leaves for
+observer / event-emitter / signal patterns, where a *dispatcher* invokes callbacks
+registered elsewhere through a shared store — so flows like "how does an update
+reach the screen" actually exist in the graph.
+
+> **Update (2026-06-01):** the `codegraph_trace` and `codegraph_context` MCP tools
+> were since **removed** — `codegraph_explore` is the single surfacing tool now. Its
+> "Flow" section (`buildFlowFromNamedSymbols`) and the `codegraph_node` trail surface
+> these synthesized edges; the `trace(a, b)` notation below means "the a→b flow,"
+> which you now verify with `codegraph_explore` / `probe-explore.mjs` (the
+> `probe-trace.mjs` / `probe-context.mjs` dev probes went away with the tools).
+
+---
+
+## TL;DR for a new session
+
+We synthesize `dispatcher → callback` edges that static parsing misses. It works:
+
+- **Field observer** (excalidraw `Scene.onUpdate`/`triggerUpdate`): synthesizes
+  `triggerUpdate → triggerRender`. `trace(mutateElement, triggerRender)` now = 3 hops.
+- **EventEmitter** (express `on('mount', …)`/`emit('mount')`): synthesizes `use → onmount`.
+- Precision is high: excalidraw got **1** synthesized edge out of 27k (the correct one);
+  node count moved +3 after Phase 3 (no explosion).
+
+**Files touched (all uncommitted on `main`):**
+- `src/resolution/callback-synthesizer.ts` — the whole-graph synthesis pass (Phase 1 + 2).
+- `src/resolution/index.ts` — calls `synthesizeCallbackEdges()` at the end of
+  `resolveAndPersistBatched()` (after base edges are persisted) + the import.
+- `src/extraction/tree-sitter.ts` — `visitFunctionBody` now extracts **named** nested
+  functions (Phase 3), so inline named handlers become linkable nodes.
+
+**How to reproduce / test:**
+```bash
+npm run build
+rm -rf /tmp/codegraph-corpus/excalidraw/.codegraph
+( cd /tmp/codegraph-corpus/excalidraw && codegraph init -i )
+# synthesized edges (provenance='heuristic', metadata.synthesizedBy in {callback,event-emitter}):
+sqlite3 /tmp/codegraph-corpus/excalidraw/.codegraph/codegraph.db \
+  "select s.name||' → '||t.name||'  '||coalesce(e.metadata,'') from edges e \
+   join nodes s on e.source=s.id join nodes t on e.target=t.id where e.provenance='heuristic';"
+# end-to-end flow (the synthesized edge shows up in explore's Flow section + node trail):
+node scripts/agent-eval/probe-explore.mjs /tmp/codegraph-corpus/excalidraw "triggerUpdate triggerRender"
+```
+Probe scripts (dev-only, in `scripts/agent-eval/`): `probe-node.mjs` (symbol + trail),
+`probe-explore.mjs` (relevant source + the flow among named symbols). EventEmitter
+fixture lives at `/tmp/cb-fixture/bus.js` (ephemeral — recreate or move into `__tests__/`).
+
+---
+
+## The hole
+
+```ts
+class Scene {
+  private callbacks = new Set<Callback>();
+  onUpdate(cb: Callback) { this.callbacks.add(cb); }          // REGISTRAR
+  triggerUpdate() { for (const cb of this.callbacks) cb(); }  // DISPATCHER
+}
+this.scene.onUpdate(this.triggerRender);                      // REGISTRATION SITE
+```
+
+The runtime edge `triggerUpdate → triggerRender` does not exist statically:
+`triggerUpdate`'s only literal call is `cb()` (anonymous). Measured: `triggerUpdate`'s
+only callee was `randomInteger`; `trace(triggerUpdate, triggerRender)` returned no path.
+
+## Why it's a whole-graph pass, not a `FrameworkResolver.resolve()`
+
+`resolve(ref)` answers "what does this **named** ref point to," one ref at a time. The
+callback edge has **no ref to resolve** (`cb()` is anonymous) and needs **cross-file,
+multi-site correlation** (registrar, registration, dispatcher). So it's a whole-graph
+pass after base resolution, language-level (any OO observer), living in
+`src/resolution/callback-synthesizer.ts` — **not** under `frameworks/`.
+
+> Sibling mechanism for the *other* dynamic-dispatch class — **named** attribute/
+> descriptor dispatch (e.g. django `self._iterable_class(...)`) — is the
+> `claimsReference` hook (`resolution/types.ts` + `resolution/index.ts` pre-filter)
+> + a `FrameworkResolver.resolve()` (django ORM resolver in `frameworks/python.ts`).
+> That one *does* fit `resolve()` because the ref is named. Both are part of the same
+> coverage effort; see the "Related work" section.
+
+---
+
+## As-built algorithm (and where it diverged from the original design)
+
+### Field-observer channels (`fieldChannelEdges`, Phase 1)
+1. **Candidates** by method/function **name** — registrar `^(on[A-Z]\w*|subscribe|
+   addListener|addEventListener|register|watch|listen|addCallback)$`; dispatcher
+   contains `(emit|trigger|notify|dispatch|fire|publish|flush)`.
+2. **Confirm by body** (read via `ctx.readFile` + slice node lines): registrar has
+   `this.<F>.add|push|set(`; dispatcher has `for (… of [Array.from(]this.<F>)` + a call,
+   or `this.<F>.forEach(`.
+3. **Pairing — DIVERGENCE:** the design said pair by *class*; the build pairs by
+   **same file + same field `F`** (file as a class proxy — getting the containing class
+   reliably was harder). Works for the common 1-class-per-file case; revisit for
+   multi-class files.
+4. **Registrations:** `queries.getIncomingEdges(registrar.id, ['calls'])` → for each,
+   read the caller's source at the edge line and **regex-recover the arg**
+   (`<registrarName>\s*\(\s*(?:this\.)?(\w+)`). DIVERGENCE: design preferred tree-sitter
+   re-parse; build uses regex (named refs only — arrows/inline args are missed here).
+5. **Synthesize** `dispatcher → fn` (`getNodesByName(arg)` → method|function). Capped at
+   `MAX_CALLBACKS_PER_CHANNEL = 40`.
+
+### EventEmitter channels (`eventEmitterEdges`, Phase 2)
+- **File-oriented scan** (`ctx.getAllFiles()` + `readFile`, substring pre-filter on
+  `.emit(`/`.on(`/etc). `ON_RE` = `\.(?:on|once|addListener)\(\s*['"]([^'"]+)['"]\s*,\s*
+  (?:function\s+(\w+)|(?:this\.)?(\w+))`; `EMIT_RE` = `\.(?:emit|fire|dispatchEvent)\(\s*['"]([^'"]+)['"]`.
+- Dispatcher = **enclosing function** of the `emit('e')` call (`enclosingFn` finds the
+  tightest function/method/component node containing the line). Handler = `getNodesByName`
+  of the on-handler name.
+- Correlate by **event-name literal**; synthesize dispatcher → handler.
+- **Precision — DIVERGENCE:** design proposed receiver-type matching; build uses an
+  **event fan-out cap** (`EVENT_FANOUT_CAP = 6`) — skip events with >6 handlers or
+  dispatchers (generic names like `error`/`change` would over-link without type info).
+
+### Provenance — DIVERGENCE
+`Edge.provenance` is a fixed enum (`'tree-sitter'|'scip'|'heuristic'`), so synthesized
+edges use **`provenance: 'heuristic'`** + `metadata: { synthesizedBy: 'callback'|
+'event-emitter', via/event/field }`. The design's `'callback-synthesis'` provenance and
+high/medium/low **confidence tiers were NOT implemented** — the fan-out cap +
+registrar-name uniqueness + named-only handlers are the precision guards instead.
+
+### Phase 3 — inline callback extraction (`tree-sitter.ts`)
+The real blocker for EventEmitter on real repos: inline handlers
+(`on('mount', function onmount(){})`) weren't **nodes**, so nothing could link to them.
+Root cause: `visitFunctionBody` walked *through* nested functions without extracting them.
+Fix: in `visitForCallsAndStructure`, when a body node is a `functionType` and
+`extractName` returns a real name, call `extractFunction` (which extracts it and walks
+its own body) and return. **Named only** — anonymous arrows fall through to the existing
+recursion (so their inner calls stay attributed to the enclosing fn). This bounded it:
+excalidraw +3 nodes, no explosion, no regression.
+
+---
+
+## Validation results (actual)
+
+| Repo | Result |
+|---|---|
+| excalidraw | 1 synthesized edge `triggerUpdate → triggerRender` (of 27,214); `trace(mutateElement, triggerRender)` = 3 hops; nodes 9,286 → 9,289 |
+| express | after Phase 3: `use → onmount` `{event-emitter, event:"mount"}` (`onmount` now extracted at `application.js:109`) |
+| `/tmp/cb-fixture/bus.js` | `tick → handleRefresh`, `persist → handleSave` (named-method EventEmitter handlers) |
+| excalidraw / express | no Phase-1 regression; node counts stable |
+
+---
+
+## Remaining work (prioritized for the next session)
+
+1. **Anonymous-arrow handlers** — `on('e', () => foo())` still produce no edge (no node,
+   intentionally not extracted in Phase 3). The fix is **synthesizer link-through-body**:
+   parse the arrow's body and link `dispatcher → (calls inside the arrow)`. Highest
+   remaining recall win; handles the most common modern callback shape.
+2. **Wire into `resolveAndPersist`** (incremental sync) — synthesis currently runs only
+   in `resolveAndPersistBatched` (full index). Incremental re-index won't refresh
+   synthesized edges.
+3. **Receiver-type matching** for EventEmitter precision (replace/augment the fan-out
+   cap) — use `type_of` edges so `x.emit('change')` only links to `y.on('change', fn)`
+   when `x`,`y` are the same type. Lets the fan-out cap relax.
+4. **Tree-sitter arg recovery** (replace the regex in field-channel Stage 4) — robust for
+   arrows, multi-arg, line-wrapped calls.
+5. **Single-callback fields** (`this.onChange = cb; … this.onChange()`) — scalar-store
+   variant of the field observer; not built.
+6. **Broad precision/recall audit** — run across the full corpus; tally synthesized edges
+   per repo, spot-check, confirm no explosion on EventEmitter-heavy repos.
+7. **Tests + CHANGELOG** — the fixture is a ready vitest case for the synthesizer; add
+   extractor tests for Phase 3 (named-nested-fn extraction; confirm other languages
+   unaffected — the change is in the shared walker), resolver tests for the django side.
+
+## Edge cases / model
+- **Over-approximation across instances** is accepted (reachability, not instance
+  precision). `unregister`/`off` ignored.
+- Synthesized edges are **additive** — never replace static edges; tooling can filter on
+  `provenance='heuristic'` + `metadata.synthesizedBy`.
+
+## Related work (same coverage effort)
+This is one half of closing dynamic-dispatch coverage. The other artifacts on `main`:
+- **Named attribute/descriptor resolver**: `claimsReference` (`resolution/types.ts`,
+  pre-filter in `resolution/index.ts`) + django ORM resolver (`frameworks/python.ts`,
+  `_iterable_class` → `ModelIterable.__iter__`).
+- **Retrieval/UX changes** (separate from coverage): `explore` whole-small-file + glue
+  fixes, the `explore` Flow section (`buildFlowFromNamedSymbols`), and `node`-with-trail
+  — all in `src/mcp/tools.ts`. (`codegraph_trace` / `codegraph_context` were later
+  removed; explore is the one surfacing tool.)
+- **Full investigation context + findings:** auto-memory
+  `project_codegraph_read_displacement` (why coverage — not prompting/hooks/new-tools —
+  is the lever for getting agents to use codegraph over Read).
diff --git a/docs/design/chained-call-resolution.md b/docs/design/chained-call-resolution.md
new file mode 100644
index 000000000..9fa34a6e6
--- /dev/null
+++ b/docs/design/chained-call-resolution.md
@@ -0,0 +1,146 @@
+# Design + status: chained static-factory / fluent call resolution
+
+**Status:** SHIPPED for **13 languages** (C++, C, PHP, Java, Kotlin, C#, Swift, Rust,
+Go, Scala, Dart, Objective-C, Pascal/Delphi) + a conformance pass. **TypeScript and Luau
+were evaluated and intentionally skipped** (both gradually typed → the mechanism is +0 /
+regresses on real code). See "Full README classification" below. Tracking issue:
+**#750** (which began as "the statically-typed README languages" but that enumeration was
+incomplete — it missed ObjC / Pascal / Luau).
+
+**Motivation:** a call whose **receiver is itself a call** — a factory / singleton /
+builder that returns an object — should produce a `calls` edge to the chained method:
+
+```java
+Foo.getInstance().bar();   // bar() should resolve to Foo::bar, never a same-named decoy
+```
+
+Before this work, every statically-typed language **dropped the receiver** and
+name-matched the bare method (`bar`), so in 7 of 9 languages it silently attached to a
+**same-named method on an unrelated type** — a correctness bug, not just missing coverage.
+
+---
+
+## The 3-part mechanism (per language)
+
+1. **Capture the factory's declared return type** — a per-language `getReturnType`
+   hook writes `nodes.return_type` (schema v5). `*Foo`→`Foo`, `List<Bar>`→`List`,
+   `pkg.Foo`→`Foo`, `-> Self` / `: self` / `this.type` → the declaring type.
+2. **Preserve the chained receiver at extraction** — `tree-sitter.ts` (or a bespoke
+   extractor) encodes `Foo.getInstance().bar()` as the marker string
+   `Foo.getInstance().bar` (the `().` marker never appears in an ordinary ref). A
+   per-language gate keeps **instance** chains (`list.map().filter()`) bare so their
+   existing resolution is untouched — only capitalized-receiver / factory chains re-encode.
+3. **Resolve AND VALIDATE** — at resolution the receiver's type is inferred from what
+   the inner call returns, then the outer method is resolved **on that type** and
+   validated: the method must exist on the type (or a supertype it conforms to), so a
+   wrong inference yields **no edge**, never a wrong one.
+
+Three shared resolvers in `src/resolution/name-matcher.ts`, all calling
+`resolveMethodOnType` (which has the conformance supertype-walk):
+
+| Resolver | Receiver style | Languages |
+|---|---|---|
+| `matchCppCallChain` | `field_expression` (`Foo::instance().bar`) | C++, C |
+| `matchScopedCallChain` | `::` (`Cls::for($x)->m`, `Foo::new().bar`) | PHP, Rust |
+| `matchDottedCallChain` | `.` (`Foo.create().bar`) | Java, Kotlin, C#, Swift, Go, Scala, Dart |
+
+**Conformance pass (#754).** When the chained method lives on a **supertype** the
+return type conforms to (an inherited / default-interface / trait / mixin / embedded
+method), the first pass can't see it — `implements`/`extends` edges aren't built yet.
+So failed chain refs are deferred (`CHAIN_LANGUAGES` in `resolution/index.ts`) and
+re-resolved in a second pass `resolveChainedCallsViaConformance()` after edges exist,
+walking `context.getSupertypes(...)`.
+
+**Adding a language:** `getReturnType` in `languages/*.ts`; encode the chained receiver
++ a node-type gate; add the language to the right `matchReference` gate (and
+`CONSTRUCTS_VIA_BARE_CALL` if a bare capitalized call constructs the class); add to
+`CHAIN_LANGUAGES`; synthetic tests + a real-repo A/B; bump `EXTRACTION_VERSION`.
+
+---
+
+## Coverage (validated — each via synthetic decoy/absent-method tests + a real-repo A/B)
+
+| Language | PR | Receiver | Real-repo A/B (unique `calls` edges) | Notes |
+|---|---|---|---|---|
+| **C++ / C** | #645 (#742) | `field_expression` | — | The original: singletons / factories / chained getters. |
+| **PHP** | #608 (#749) | `::` → `->` | — | `Cls::for($x)->method()` — the Laravel per-tenant client idiom. `: self`/`: static`. |
+| **Java** | #751 | `.` | Guava **+1,507 / −0** | Missing-edge → purely additive. |
+| **Kotlin** | #752 | `.` | arrow **+49 / −438** | Wrong-edge → precision win (438 removed = test/doc noise + wrong). Needed the capitalized-receiver gate + constructor-receiver handling. |
+| **C#** | #753 | `.` | Newtonsoft +3 / NodaTime **+73 / −0** | Additive. Return type is the `returns` field; extension-method chains correctly don't resolve. |
+| **conformance** | #754 | (resolver upgrade) | arrow **+22 / −0** | Supertype walk — enables Swift protocol-ext, Rust trait, Go embedded, Dart mixin, Java/Kotlin/C# inherited chains. |
+| **Swift** | #755 | `.` | Alamofire / Kingfisher **0 / 0** | Neutral-safe (unique fluent names already bare-resolved). Needed a nested-extension naming fix (`KF.Builder`→`KF::Builder`). |
+| **Rust** | #757 | `::` | clap **+937 / −775** | Precision win (622 wrong→right retargets, +162 net). `-> Self`; trait-default methods via conformance. Single-hop. |
+| **Go** | #760 | `.` | gin **net-zero** | `New().Method()`; embedded structs via conformance. Variable-inner fallback. **Found + fixed a batched-resolver runaway** (a mutated `original.referenceName` looped the offset-0 batch → 5M edges / 1.4 GB; fixed by tying the fallback to the original ref + a non-progress guard). |
+| **Scala** | #761 | `.` | gatling **+14 / −59** | Precision win (−59 = stdlib `Option`/`Iterator` `.map`/`.flatMap` the baseline mis-tied to gatling's `Validation::*`). Companion factories + case-class `apply`. |
+| **Dart** | #762 | `.` | localsend hand-written **+17 / −10** | Precision win **+ constructors made first-class** (factory/named ctors `Foo.create()`/`Foo._()` are now indexed; unnamed `Foo()` stays `instantiates`). `dartCtorInfo` validates a ctor against the enclosing class name — handles a tree-sitter misparse where `@override (A,B) m()` makes `m()` look like a ctor. |
+| **Objective-C** | #786 | message send | SDWebImage **+35 / −75** | Precision win. Chained message send `[[Foo create] doIt]` over `message_expression`. getReturnType skips nullability qualifiers (`nonnull instancetype`). A class-message factory returns the receiver class by convention, so `[[X alloc] init]` / singleton chains resolve on `X` (validated). The −75 are wrong `init` mis-matches retargeted to the right class. |
+| **Pascal/Delphi** | #791 | `.` (`exprDot`) | PascalCoin **+19 / −18** | Precision win. `TFoo.GetInstance().DoIt()` over Pascal's `exprCall`/`exprDot`. getReturnType from the `typeref` (incl. interface returns `IFoo`). Re-encoding gated on the Delphi `TFoo`/`IFoo` type convention so capitalized *variable* chains stay bare. A constructor (no `: TBar`) or typecast `TFoo(x)` resolves on the class. 15 of the −18 are correct class→interface retargets (`GetInstance(): IAsn1OctetString`). |
+| **TypeScript** | — | `.` | typeorm +0/−6 · nest **+0/−164** | **Evaluated, NOT shipped** — gradual typing; see below. |
+| **Luau** | — | `:` / `.` | Fusion +0/−0 · matter +0/−0 | **Evaluated, NOT shipped** — gradually typed; additive-safe (missing-edge gap, no regression) but real Luau rarely annotates factory returns, so +0 on both benchmarks. Works for `Foo.create(): Bar` then `:doIt()` (synthetic). |
+
+`EXTRACTION_VERSION` is now **18** (C++→…→Pascal chains→paren-less calls→free-routine attribution). Re-index with `codegraph index -f`
+to pick up the newer extractor on an existing graph.
+
+## Why TypeScript was skipped
+
+The mechanism resolves a chain from the factory's **declared** return type. TypeScript
+leans on **type inference** — e.g. NestJS's `Test.createTestingModule(m) { return new
+TestingModuleBuilder(...) }` has no `: TestingModuleBuilder` annotation — so the
+factory's type can't be recovered, the re-encoded chain can't resolve, and it **drops
+the bare-name edge** the existing resolver found. Real-repo A/B was **+0 added on both
+typeorm and nest** with a net recall regression (−164 on nest, mostly the ubiquitous
+`Test.createTestingModule({…}).compile()` pattern). The removed edges were mostly
+*wrong* (baseline mis-resolved `.compile()` to `ModuleCompiler::compile`), so it's
+precision-positive but recall-negative — against the recall-first invariant, and adding
+nothing where it doesn't hurt (TS method names are unique enough that bare-name already
+lands them). It was fully implemented (5 synthetic tests passed, runaway-safe bare-name
+fallback) and consciously not shipped. The only path to a TS win would be reading
+**inferred** return types (resolving `return new X()` in the factory body) — a much
+larger change. Full write-up on issue #750.
+
+---
+
+## Full README classification (all 21 languages)
+
+The mechanism's real requirement is a **declared return type** to recover the receiver's
+type — not "statically typed" (PHP qualifies via its `: self` / `: Type` return
+declarations). Against the README's full supported-language list:
+
+| Bucket | Languages |
+|---|---|
+| **Covered** (13) | C++, C, PHP, Java, Kotlin, C#, Swift, Rust, Go, Scala, Dart, Objective-C, Pascal/Delphi |
+| **Evaluated, skipped** (2) | **TypeScript** — gradual typing → inference-typed factories can't be recovered; net recall regression. **Luau** — gradually typed; additive-safe but +0 on Fusion AND matter (real Luau rarely annotates factory returns). Both: the mechanism needs reliably-declared return types, which gradually-typed code too often omits. |
+| **Pascal call-coverage follow-ups** | Two gaps from the chained-call work, both resolved. **Paren-less calls (#793):** Pascal lets a no-arg method drop its parens (`Obj.Free;`, `TFoo.GetInstance.DoIt;`), which parse as a bare `exprDot` and weren't extracted as calls at all. Now extracted, scoped to STATEMENT position (a bare dot in assignment/condition position is left alone — ambiguous with a field/property access). PascalCoin A/B **+1131 / −1**, all new edges resolve to methods. **Free-routine attribution (#795):** a procedure/function defined only in the `implementation` section (no interface decl, not a method) had no node, so its body's calls were lumped under the file; now it gets a function node and its calls attribute to it. PascalCoin A/B **+511 / −145** (file-level aggregates → per-routine edges). |
+| **Out of scope — no declared return types** (6) | JavaScript, Ruby, Lua, Svelte, Vue, Liquid (Liquid has no methods/chains at all) |
+| **Partial / separate** (1) | Python — only optional `-> T` hints; tracked as #578, not part of this mechanism |
+
+So #750's original framing ("the 9 statically-typed README languages") was incomplete —
+it missed three more typed languages, all now resolved: **Objective-C** shipped (#786,
+same wrong-edge gap, mechanism ports directly); **Pascal/Delphi** shipped (#791, a clean
+port for the paren'd chain — an initial "blocked" read was wrong, caused by probing only
+the paren-less form); **Luau** evaluated and skipped (gradual typing → +0 on real repos,
+additive-safe).
+
+The through-line: this mechanism fits languages with **reliably-declared return types**
+(the 13 shipped). Gradually-typed languages (TypeScript, Luau) omit them too often for
+it to pay off, and dynamically-typed languages have none.
+
+---
+
+## Edge cases / model
+- **Single-hop**: a chain re-encodes one hop; deeper hops (`a.b().c().d()`) keep the
+  bare name (the inner `()` defeats the `Class::method` split). Re-measure on deep
+  fluent-builder repos.
+- **Validation, not guessing**: every resolver ends in `resolveMethodOnType`, so an
+  unknown / wrong inferred type produces **no edge** — the decoy / absent-method
+  guarantee that makes this safe to ship.
+- **Per-language receiver gate** keeps instance chains bare so existing resolution is
+  never regressed; the A/B "removed" counts are wrong-edge corrections, not losses.
+
+## Related work
+- **Dynamic-dispatch / callback synthesis** (a *different* mechanism): observer /
+  EventEmitter / React-render / JSX-child / django-ORM edge synthesis lives in
+  `callback-edge-synthesis.md` + `dynamic-dispatch-coverage-playbook.md`.
+- The verbose session working-notes for #750 are in
+  `.claude/handoffs/chained-call-multilang-probe.md` (scratch; this doc is the
+  permanent record).
diff --git a/docs/design/dynamic-dispatch-coverage-playbook.md b/docs/design/dynamic-dispatch-coverage-playbook.md
new file mode 100644
index 000000000..aa65398e4
--- /dev/null
+++ b/docs/design/dynamic-dispatch-coverage-playbook.md
@@ -0,0 +1,642 @@
+# Dynamic-Dispatch Coverage Playbook
+
+**Audience:** a Claude agent continuing this work.
+**Mission:** systematically close static-extraction coverage holes for **dynamic
+dispatch** across **every language and framework codegraph supports**, and validate
+each one the same way, so cross-symbol *flows* exist in the graph everywhere.
+
+> This is the top-level playbook. The deep design for one mechanism (the callback
+> synthesizer) is in [`callback-edge-synthesis.md`](./callback-edge-synthesis.md).
+> Full investigation context + findings: auto-memory `project_codegraph_read_displacement`.
+
+> **Update (2026-06-01):** the `codegraph_trace` and `codegraph_context` MCP tools were
+> **removed** — `codegraph_explore` is the single surfacing tool now. Its "Flow" section
+> (`buildFlowFromNamedSymbols`) surfaces the synthesized edges this playbook is about, and
+> you validate coverage with `codegraph_explore` / `scripts/agent-eval/probe-explore.mjs`.
+> Where the text below writes `trace(a, b)` or lists `trace`/`context` among the tools,
+> read it as "the a→b flow, now surfaced and verified via explore." The synthesizers and
+> the coverage matrix are unchanged.
+
+---
+
+## 1. The goal (why this matters)
+
+codegraph's value is being **the map** — answering structural/flow questions
+(`trace`, `impact`, callers, "how does X reach Y") that grep/Read cannot. Agents
+will use codegraph instead of Read **only when it is sufficient**. We proved
+empirically (see memory) that the lever for sufficiency is **coverage**, not
+prompting/hooks/new-tools: when a flow is missing from the graph, the agent reads
+the files to reconstruct it; when the flow *is* in the graph, the agent can answer
+completely without reading.
+
+**Validated end-to-end on excalidraw:** after closing the update-flow hole, 2/3
+headless agent runs answered the "how does an update reach the screen" question with
+**Read 0 and a complete answer** — impossible before, because the key edge wasn't in
+the graph. (Caveat: coverage *enables* the no-read path; agent confirm-by-reading
+variance means it doesn't *force* it. Completeness improves unconditionally.)
+
+The mission is to make that true for **all** languages/frameworks.
+
+---
+
+## 2. The problem class: dynamic dispatch
+
+Static tree-sitter extraction captures explicit calls (`foo()`, `this.bar()`). It
+**misses** any call whose target is computed/indirect. Four recurring shapes, with a
+**difficulty gradient** (do the cheap ones first):
+
+| # | Shape | Example | Fix mechanism | Cost |
+|---|---|---|---|---|
+| 1 | **Named attribute / descriptor** | django `self._iterable_class(self)` | framework resolver (`claimsReference` + `resolve()`) | **cheap** |
+| 2 | **Field-backed observer** | `onUpdate(cb)` + `for(cb of cbs)cb()` | callback synthesizer (whole-graph pass) | medium |
+| 3 | **String-keyed EventEmitter** | `on('e',fn)` / `emit('e')` | callback synthesizer (event-keyed) | medium |
+| 4 | **Inline callback handler** | `on('e', function h(){})` / `() => {}` | extraction (named) + synthesizer link-through-body (anon) | named: cheap · anon: hard |
+| 5 | **Closure-collection dispatch** | Swift `validators.write{$0.append(v)}` … `validators.forEach{$0()}` | callback synthesizer (`closureCollectionEdges`, element-invoke gated) | medium |
+
+Key distinction driving the mechanism choice:
+- **A named ref exists** to resolve (`_iterable_class` is an attribute name) → **resolver**.
+- **No ref exists** (`cb()` is anonymous; needs registrar↔dispatcher correlation) → **synthesizer**.
+
+---
+
+## 3. Worked examples (the two mechanisms, end to end)
+
+### 3a. Django ORM descriptor — the **resolver** pattern (Python)
+- **Hole:** `QuerySet._fetch_all` calls `self._iterable_class(self)` (a runtime-chosen
+  iterable, default `ModelIterable`), whose `__iter__` runs the SQL compiler. Static
+  parsing can't resolve the attribute-as-callable → `_fetch_all`'s only callee was
+  `_prefetch_related_objects`; `trace(_fetch_all, execute_sql)` returned no path.
+- **Fix:** `djangoResolver` claims the unresolved `_iterable_class` ref through the
+  name-exists pre-filter, then resolves it to `ModelIterable.__iter__`.
+- **Files:** `src/resolution/types.ts` (`claimsReference?` on `FrameworkResolver`),
+  `src/resolution/index.ts` (pre-filter in `resolveOne` consults `claimsReference`),
+  `src/resolution/frameworks/python.ts` (`djangoResolver.resolve` + `claimsReference` +
+  `resolveModelIterableIter`).
+- **Result:** `trace(_fetch_all, execute_sql)` → `_fetch_all → __iter__ → execute_sql` (3 hops).
+
+### 3b. Excalidraw observer + EventEmitter — the **synthesizer** (TS)
+- **Hole:** `Scene.triggerUpdate` does `for (cb of this.callbacks) cb()`; `triggerRender`
+  is registered via `scene.onUpdate(this.triggerRender)`. The `triggerUpdate →
+  triggerRender` edge is dynamic → `trace` returned no path; the whole update flow broke.
+- **Fix:** a whole-graph pass that detects registrar/dispatcher channels, correlates
+  registration sites, and synthesizes `dispatcher → callback` edges. Plus extraction of
+  **named** inline callbacks so handlers like express's `function onmount(){}` are nodes.
+- **Files:** `src/resolution/callback-synthesizer.ts` (the pass — field observers +
+  EventEmitter), `src/resolution/index.ts` (calls `synthesizeCallbackEdges()` at the end
+  of `resolveAndPersistBatched`), `src/extraction/tree-sitter.ts` (`visitFunctionBody`
+  extracts named nested functions).
+- **Result:** `trace(mutateElement, triggerRender)` → 3 hops; express `use → onmount`.
+
+### 3c. Alamofire deferred validation — closure-collection dispatch (Swift)
+- **Hole:** `DataRequest.validate(_:)` builds a closure and `validators.write { $0.append(validator) }`;
+  the base `Request.didCompleteTask` runs them via `validators.forEach { $0() }`. Append and
+  dispatch live in *different files and classes* (a subclass appends, the base iterates) and the
+  field is a Swift `Protected<[@Sendable () -> Void]>` — so neither same-file pairing nor the
+  name-based registrar match (`onX`/`subscribe`/…) reaches it. `trace(didCompleteTask, validate)`
+  returned no path; the agent grepped `validators` and read three files to reconstruct it.
+- **Fix:** `closureCollectionEdges` (callback-synthesizer.ts). A **dispatcher** iterates a collection
+  *invoking each element* (`coll.forEach { $0() }` / `{ it() }`); a **registrar** appends a closure to
+  the same-named field (`.append`/`.add`/`.push`/`.insert`, incl. Swift `.write { $0.append }`). The
+  element-invoke (`$0(` / `it(`) is the precision **gate** — it proves the collection holds closures —
+  so a repo with no closure-collection dispatch yields **0 edges** regardless of how many `.append`
+  sites it has. Pairs dispatcher → registrar globally by field name (cross-file/class required),
+  fan-out-capped. Surfaced two ways: inline in `trace`, and as a "Dynamic-dispatch links among your
+  symbols" section in `codegraph_explore` (`buildFlowFromNamedSymbols`) so the relationship shows even
+  when the agent named only `validate`, not the `didCompleteTask` that drains the list.
+- **Files:** `src/resolution/callback-synthesizer.ts` (`closureCollectionEdges`),
+  `src/mcp/tools.ts` (`synthEdgeNote` closure-collection case + the explore synth-links section).
+- **Result:** `trace(didCompleteTask, validate)` connects with the closure-collection hop + the
+  `validators.write { $0.append }` wiring site inlined. 9 precise edges on Alamofire
+  (`validators`/`streams`/`finishHandlers`/`requestsToRetry`), **0 on every non-Swift control**.
+  Forced codegraph-only (Read+Grep+Bash blocked): 3/3 runs answer build/send/validate correctly.
+
+### 3d. Insight — an "adoption floor" can hide a trace-endpoint bug (Alamofire)
+Alamofire (110 files) was the README's weakest repo and was written off as the "small-repo floor"
+(native grep is cheap, so the agent reads anyway). It wasn't. Reading the **transcripts** — every
+`Read`'s `file_path`+offset and the assistant text right before it — surfaced the agent's own words:
+*"the trace collided with same-named symbols (44 `request`s, 8 `task`s), let me read by line."*
+`codegraph_trace`'s endpoint disambiguation (`scorePair`, shared-dir-prefix only) was resolving an
+overloaded name to an **empty delegate/protocol stub** — `request` → `EventMonitor.request(){}`
+(a 1-line no-op) over the real `Session.request`, because two unrelated `Source/Features/` stubs
+shared a deeper dir prefix than the correct `Source/Core/` pair. Garbage trace → manual reading,
+sometimes a spiral (12 reads / 11 greps in one run). **Fix:** a `nodeRelevance` term in `handleTrace`
+pair scoring that penalizes empty stubs (≤1 body line) and test-file symbols; among real methods it's
+flat, so path-proximity (cosmos `EndBlocker`) is unaffected. Result (n=8): WITH-arm tool calls
+12 → 8 median, and the read **variance collapsed** (0–12 → 1–4 — the meltdowns *were* the
+trace-collision flounder). General bug: protocol/delegate-stub flooding hits Swift/Java/C#/Go.
+
+**Methodology lesson:** when the agent reads on a small repo, don't conclude "adoption floor" — diff
+*what it read* against what the tool returned *immediately before*. A read of content the tool already
+gave = adoption; a read after the tool returned the **wrong thing** (stub endpoints, collided names) =
+a fixable bug. The transcript reasoning, not the median, tells you which. The forced codegraph-only
+hook (block Read+Grep+Glob+Bash-search) is the variance-free way to confirm sufficiency separately
+from adoption.
+
+---
+
+## 4. The repeatable methodology (run this per language/framework)
+
+### Step 1 — Pick the framework's canonical *flow* question
+Every framework has a signature data/control flow. Pick the "how does X reach/become Y"
+question and a real repo (add to `.claude/skills/agent-eval/corpus.json`). Examples:
+- React state→DOM, Vue reactive→render, Svelte store→update
+- Rails request→controller→view, Spring request→`@Controller`→service
+- Express/Koa request→middleware→handler, FastAPI request→route→dependency
+- Redux action→reducer→store, RxJS subscribe→operator→observer
+- Any ORM: query builder → SQL execution (django pattern)
+
+### Step 2 — Measure the hole (deterministic, no agent)
+```bash
+rm -rf <repo>/.codegraph && ( cd <repo> && codegraph init -i )
+node scripts/agent-eval/probe-trace.mjs <repo> <from-symbol> <to-symbol>   # does the flow break? where?
+node scripts/agent-eval/probe-node.mjs  <repo> <break-symbol>              # trail: is the next hop missing?
+```
+A "No direct call path … breaks at dynamic dispatch" + a sparse trail at the break
+point **locates the hole** (this is exactly how `_iterable_class` and `triggerUpdate`
+were found). Confirm it's dynamic by reading the break symbol's body.
+
+### Step 3 — Classify → choose the mechanism (use the §2 table)
+- `self.<attr>(...)` / descriptor / metaclass → **resolver** (§3a).
+- `for(cb of store)cb()` / `store.forEach(cb=>cb())` → **field-observer synthesizer** (§3b).
+- `on('e',fn)` + `emit('e')` → **EventEmitter synthesizer** (§3b).
+- Inline handler not a node → **named:** extraction (already done generically in
+  `tree-sitter.ts`); **anonymous:** synthesizer link-through-body (not yet built).
+
+### Step 4 — Implement
+- **Resolver:** add to `src/resolution/frameworks/<lang>.ts` — a `resolve()` branch +
+  `claimsReference(name)` if the ref name isn't a declared symbol. Copy `djangoResolver`.
+- **Synthesizer channel:** extend `src/resolution/callback-synthesizer.ts` — add the
+  framework's registrar/dispatcher **name patterns** and **body patterns** (e.g. signals
+  use `.connect()`/`.emit()`; Rx uses `.subscribe()`/`.next()`).
+- Reindex (Step 2 command) and re-run `probe-trace` — the flow should now connect.
+
+### Step 5 — Validate (the same way every time)
+1. **Deterministic:** `probe-trace(from,to)` finds the path; `probe-node` shows the
+   bridged hop. The previously-broken hop is closed.
+2. **Precision:** count + spot-check synthesized/resolved edges — no explosion, correct targets:
+   ```bash
+   sqlite3 <repo>/.codegraph/codegraph.db \
+     "select s.name||' → '||t.name||'  '||coalesce(e.metadata,'') from edges e \
+      join nodes s on e.source=s.id join nodes t on e.target=t.id where e.provenance='heuristic';"
+   ```
+   (Resolver edges aren't `heuristic`; verify via the trace + callees instead.)
+3. **Regression:** node count stable (`select count(*) from nodes;` before/after — a big
+   jump means an extraction change over-fired); existing traces on a control repo intact.
+4. **End-to-end agent eval:** run the flow question with codegraph and measure
+   **reads / answer-completeness / cost** vs a pre-fix baseline:
+   ```bash
+   # headless (exact cost + clean tool sequence)
+   bash scripts/agent-eval/run-agent.sh <repo> with "<flow question>"
+   # or the full A/B + interactive Explore-subagent path:
+   scripts/agent-eval/audit.sh local <name> <url> "<flow question>" all
+   ```
+   Then parse: `Read` count, codegraph-tool count, cost, and whether the answer now
+   contains the glue symbols (the ones that previously required a read).
+
+### Success criteria (per language/framework)
+- `trace` finds the canonical flow end-to-end (no dynamic-dispatch break).
+- Agent can answer the flow question with **Read 0** (achievable in ≥ some runs) and the
+  glue symbols appear in the answer.
+- **No node explosion** and no regression on a control repo.
+- Synthesized edges are precise on a spot-check (no generic-name over-linking).
+
+---
+
+## 5. Validation toolkit (reference)
+
+| Tool | Purpose |
+|---|---|
+| `scripts/agent-eval/probe-trace.mjs <repo> <from> <to>` | call-path between two symbols (the hole detector) |
+| `scripts/agent-eval/probe-node.mjs <repo> <sym> [code]` | symbol + trail (callers/callees); `code` adds the body |
+| `scripts/agent-eval/probe-context.mjs <repo> "<task>"` | context output incl. call-paths |
+| `scripts/agent-eval/probe-explore.mjs <repo> "<query>"` | explore output |
+| `scripts/agent-eval/{audit,run-agent,itrun}.sh` | agent A/B (headless + interactive); also the `/agent-eval` skill |
+| `sqlite3 <repo>/.codegraph/codegraph.db` | direct edge/node inspection (provenance, metadata, counts) |
+
+Probe scripts use the built `dist/` — run `npm run build` first. Reindex after any
+extraction or resolution change (`rm -rf <repo>/.codegraph && codegraph init -i`) — the
+synthesizer/resolvers run at index time. Test fixtures: keep a tiny per-pattern fixture
+(see `/tmp/cb-fixture/bus.js`; **move into `__tests__/`** when shipping).
+
+---
+
+## 6. Coverage matrix (fill in as you go)
+
+Status legend: ✅ done+validated · 🔬 hole identified · ⬜ not started.
+`Mechanism`: R = resolver, S = synthesizer channel, X = extraction.
+
+| Language | Framework(s) | Canonical flow to test | Mechanism | Status |
+|---|---|---|---|---|
+| TypeScript/JS | React / observer / EventEmitter / React Router | state→render; dispatch→callback; route→component | S + X | ✅ rendering+dispatch (excalidraw); **React Router JSX routing** `<Route path component={C}/>` (v5) + `element={<C/>}` (v6) → component (react-realworld **0→10, 10/10**). + **object data-router** `createBrowserRouter([{path, element/Component}])` (literal form); Next.js config/`nextjs-pages` false-positives FIXED. 🔬 lazy data-router (`path: paths.x.path, lazy: () => import()` — variable paths + lazy modules) |
+| TypeScript/JS | Vue / Nuxt | template events (@click→handler); component composition; reactive→render | S + X | ✅ events + composition (vitepress S / vben M / element-plus L); 🔬 reactive→render (vue-core Proxy runtime — frontier, deferred) |
+| TypeScript/JS | Svelte / SvelteKit | template calls/composition; SvelteKit action→api; store→DOM | X | ✅ already strong (realworld S / skeleton M / shadcn L): template `{fn()}` calls, `<Pascal/>` composition, `import * as api` namespace, `load`→api all work out of the box. + exported-const object-of-functions extraction (SvelteKit `actions`). 🔬 `$lib`-namespace-from-action + store/reactive frontier |
+| TypeScript/JS | Express / Koa | request → route → handler → service | R + X | ✅ named handlers + middleware + controller/service (resolver) + **inline arrow handlers → service body calls** (realworld S 19 / parse M / ghost L 65 edges). 🔬 custom routers (payload had 0 routes — not `app.get`-style) |
+| TypeScript/JS | NestJS | request → @Controller → DI service → repo | R | ✅ already well-covered (realworld S / immich M-L / amplication L): @decorator routes (HTTP/GraphQL/microservice/WS) via resolver + DI `this.svc.method()` controller→service resolves correctly at scale (name + co-location). No dynamic-dispatch hole. 🔬 committed `dist/` build output gets indexed (realworld) — general build-dir-ignore follow-up |
+| TypeScript/JS | RxJS / signals | subscribe → operator → observer | S | ⬜ |
+| Python | Django ORM | QuerySet → SQL compiler | R | ✅ |
+| Python | Django / DRF (views) | url → view → model | R + X | ✅ url→view (`path`/`url`/`as_view`) + **DRF `router.register`→ViewSet** (realworld S / wagtail M / saleor L); ORM QuerySet→SQL (prior work). 🔬 signals (`post_save`→receiver), DRF viewset CRUD actions (inherited), saleor GraphQL resolvers |
+| Python | Flask / FastAPI | request → route → handler → dependency | R + X | ✅ **Flask: handler resolved across intervening decorators (`@login_required`) + stacked `@x.route` lines** (microblog S 6→27, redash L decorator routes 6/6); **FastAPI: empty-path router-root routes `@router.get("")` incl. multi-line** (realworld S 12→20 / Netflix dispatch L **290/290 100%**) + **bare-name builtin guard** — a handler named after a Python builtin method (`index`/`get`/`update`/`count`…) was filtered as a builtin and lost its route→handler edge. + **Flask-RESTful `add_resource(Resource,'/x')` → Resource class** (redash 6→**77**) + **tuple `methods=('GET',)`** (was mislabeled GET) + **broadened detection** (requirements/Pipfile/setup + subdir app-factory entrypoints — flask-realworld 0→**19**). 🔬 FastAPI `Depends()` dependency edges (light validation) |
+| Go | Gin / chi / gorilla/mux / net-http | request → route → handler → service; middleware chain (`Use`→`Next`) | S + X | ✅ **routes on ANY group var** (`v1.GET`, `PublicGroup.GET`) not just `r/router` (gin-vue-admin S→M 4→259 / realworld S / gitness L) — was missing all group-routed apps; named handlers resolve precisely. **gorilla/mux confirmed covered** by the any-receiver `HandleFunc`/`Handle` handling (subrouter-var `s.HandleFunc(...)` + namespaced handlers; `.Methods()` chain ignored). + **gin middleware-chain synthesizer** (`ginMiddlewareChainEdges`): gin runs its entire chain through one dynamic line — `(*Context).Next` does `c.handlers[c.index](c)`, a slice-index dispatch tree-sitter can't resolve, so `callees(Next)` dead-ended at the `len()` helper (`safeInt8`) and the agent rabbit-holed re-querying it. Find the dispatcher (a Go method invoking a `handlers` slice by index) and link it → every HandlerFunc registered via `.Use`/`.GET`/…/`.Handle`; gated on the dispatcher existing (inert on non-gin Go repos), named handlers only (closures skipped), capped. gin L: `callees(Next)` now surfaces `Logger`/`Recovery`/`ErrorLogger`+handlers (node count stable 2,544; 5 precise edges with `registeredAt` wiring sites). **Agent A/B (headless median-of-4, Opus 4.8): gin flipped from codegraph −58% cost / −129% time (the rabbit-hole, incl. a stray `Workflow` mis-fire on 2/4 WITH runs) → +7% cost / +35% tokens / +8% time / 38% tool calls, all 4 WITH runs clean (0 Read/Grep/Bash, no Workflow, no duplicate calls).** 🔬 inline `func(c){}` handlers (anonymous, body lost); subrouter/`PathPrefix` path-prefix not prepended (label only); gitness chi custom (26/321) |
+| Rust | Axum / actix / Rocket | request → route → handler | R + X | ✅ **Axum chained methods + namespaced handlers** — `.route("/x", get(h1).post(h2))` emitted only the first method+handler, and `get(mod::handler)` captured the module not the fn (realworld-axum S **12→19, 19/19**); balanced-paren scan + per-method nodes + last-`::`-segment handler. **Rocket attribute macros 550/556 (99%)** (Rocket repo L) — already strong. crates.io named axum routes resolve (6/8; rest are closures/var handlers; its API is mostly the utoipa `routes!` macro = frontier). Cargo-workspace module resolution (prior work). **actix builder API** `web::resource("/x").route(web::get().to(h))` / `.to(h)` / App `.route("/x", web::get().to(h))` (actix-examples **51→128 routes, 35→112 resolved**) — was the dominant actix style and fully missed (the handler is in `.to(h)`, not `get(h)`). 🔬 actix `web::scope("/api")` prefix (not prepended to nested resource paths) + anonymous `.to` closure handlers |
+| Java | Spring | request → @RestController → @Autowired service → repo | R + X | ✅ **bare `@GetMapping`/`@PostMapping` + class `@RequestMapping` prefix join → route→method** (realworld S / mall M / halo L) — was missing all path-less method mappings; DI controller→service resolves (name + dir) + **interface→impl dispatch synthesizer** (`interfaceOverrideEdges`: a class's `implements`/`extends` → link each interface/base method → its same-name override; JVM-gated, capped, **overload-aware**; mall **310** / halo **734** synth edges, node count unchanged) so trace follows controller→service-**interface**→**impl** instead of dead-ending at the abstract method — `trace("PmsProductController.getList","PmsProductServiceImpl.list")` connects in **3 hops** (probe-validated). + **field-injected concrete-bean trace** (#389): `this.<field>.method()` strips the `this.` receiver at extraction, and the resolver looks up the receiver name in the enclosing class's field declarations to get the declared type, then resolves the method on it — closes the controller→bean hop when the field-name doesn't capitalize to the type (`@Resource(name="userBO") UserBO userbo` → `userbo.toLogin2()` reaches `UserBO.toLogin2`). + **`@Value("${k}")` / `@ConfigurationProperties(prefix="X")` → application.{yml,yaml,properties}** binding with Spring's relaxed binding (kebab↔camel↔snake), incl. `${k:default}`. mall-tiny S: 11/11 `@Value` resolved. ⚠️ **agent A/B null** (n=2: the agent went context→explore→Read and never invoked `trace`, so the synth edges weren't exercised — adoption-gated, the recurring wall; see `docs/benchmarks/call-sequence-analysis.md`). The fix is correct + improves trace/callees/impact/context connectivity regardless; agent-visible read reduction needs trace adoption. 🔬 Spring Data JPA derived queries (`findByEmail`) — metaprogramming frontier; `@PropertySource` external files; Spring Cloud Config; mapper-class simple-name collisions across packages (dropped to avoid mis-resolution) |
+| Java | MyBatis (XML mappers) | DAO interface method → `<select\|insert\|update\|delete id="X">` SQL | R (XML extract) + S (Java↔XML synthesizer) | ✅ **XML mapper as first-class language** (#389) — `src/extraction/mybatis-extractor.ts` parses files containing `<mapper namespace="...">`; emits one method-shaped node per statement qualified `<namespace>::<id>` + `<sql id="X">` fragments + `<include refid>` references. Non-mapper XML (pom, log4j) → file node only. `mybatisJavaXmlEdges` synthesizer indexes Java methods by `<ClassName>::<methodName>` and joins to XML qualified names by suffix-match — ambiguous simple-name collisions dropped (precision over recall). mall-tiny S **6/6 custom-SQL mapper methods bridge** to their XML statements; full enterprise chain `trace(controller.action → mapper.method-xml)` connects across controller / service-iface / impl / mapper / XML. 🔬 cross-mapper `<include>` via unqualified refid; MyBatis Plus dynamic methods (`BaseMapper<T>` CRUD inherited from framework, not in project); annotation-driven mappers (`@Select("SELECT ...")` on Java methods — the SQL lives in the annotation, not XML) |
+| Kotlin | Spring Boot / Jetpack Compose | request → @RestController → service; @Composable → child | R + X | ✅ **Spring Boot Kotlin** — the Spring resolver was `['java']`-only with a Java-syntax method regex (`public X name()`); extended to `.kt` + Kotlin `fun name(` handler matching (petclinic-kotlin **0→18, 18/18**; class-prefix joins; DI controller→repo resolves — `showOwner ← GET /owners/{ownerId}` → `OwnerRepository.findById`). **Compose composition already static** (@Composable→child are plain function calls — Jetcaster `PodcastInformation→HtmlTextContainer`). Java Spring unchanged (realworld 19/19). 🔬 Ktor `routing { get("/x"){…} }` lambda handlers (anonymous) + Compose recomposition (implicit `mutableStateOf`, no setState gate) + coroutines/Flow |
+| Swift | Vapor | request → route → controller | R + X | ✅ **was 0 routes on every real app** — the extractor required an `app/router/routes` receiver + a `"path"` literal, but real Vapor routes on grouped builders (`let todos = routes.grouped("todos"); todos.get(use: index)`) with NO path arg. Rewrote: any receiver, optional/non-string path segments, `.grouped`/`.group{}` prefix tracking, `use:` discriminator. vapor-template S **0→3 (3/3**, nested `/todos/:todoID`), SteamPress M **0→27 (27/27)**, SwiftPackageIndex-Server L **0→14 (14/14** handler resolution). 🔬 typed-route enums (SPI `SiteURL.x.pathComponents` — path label only, handler still resolves) + closure handlers `app.get("x"){ }` (anonymous) |
+| Swift | Alamofire / closure-collection | request → build → send → **validate** (deferred closures) | S | ✅ **closure-collection dispatch synthesizer** (`closureCollectionEdges`): the Swift deferred-handler pattern `DataRequest.validate` `validators.write{$0.append(v)}` … base `Request.didCompleteTask` `validators.forEach{$0()}` (append + dispatch in different files/classes, field is `Protected<[() -> Void]>`). The element-invoke `$0(`/`it(` is the precision gate → **9 edges on Alamofire** (validators/streams/finishHandlers/requestsToRetry), **0 on every non-closure-collection control**. Surfaced inline in `trace` + as an explore "Dynamic-dispatch links" section (so it shows when the agent named only `validate`, not the `didCompleteTask` that drains the list). Forced codegraph-only: **3/3** build/send/validate correct. + **trace endpoint relevance** (`nodeRelevance`): overloaded `request`/`task` (44/8 defs, mostly empty `EventMonitor` delegate stubs) now resolve to the real `Session.request`, not a 1-line no-op — **WITH-arm tool calls 12→8 median, read variance 0–12→1–4** (the meltdowns were all the trace-collision flounder); control-safe (excalidraw/okhttp/gin traces intact, gin A/B 0 reads). + **god-file multi-phase rendering** (`handleExplore`): a flow whose necessary code spans a god-file (Session.swift build chain ~11K) PLUS other files (validate logic) used to truncate at the fixed `maxOutputChars` and drop whichever phase came last. Six coordinated layers make it render all phases: (1) on-spine god-files render spine-full + off-path methods as signatures (true-spine), (2) every NAMED token's substantive def is seeded into the subgraph (FTS buried `validate` under the build terms → Validation.swift was never gathered), (3) a file that DEFINES a named symbol outranks one that merely references the flow (Validation=50 > incidental Combine=23), (4) the 90%-budget early-break and (5) the total cap both exempt necessary (named/spine) files — incidental files stay capped, (6) the final ceiling is 1.5× so it doesn't slice the necessary content the loop assembled. Alamofire now renders build+validators-exec+validate in ONE explore (~16K); A/B reads med 2→**0.5**, tools 8→**5.5**; excalidraw control held at 0 reads (no bloat). Sequential-flow spine is irreducible (no redundant siblings to collapse) — the fix is to render it, not cap it. |
+| C# | ASP.NET Core | request → [Http*] action → DI service → EF | X | ✅ **feature-folder detection** (realworld 0→19 — was undetected) + **bare `[HttpGet]` + class `[Route]` prefix** (eShopOnWeb 9→33 / jellyfin L) — co-located so no claimsReference needed. 🔬 EF Core LINQ/DbSet (metaprogramming frontier) |
+| Ruby | Rails / Sinatra | request → routes.rb → Controller#action → model | R | ✅ **RESTful `resources`/`resource` routing → controller#action** (realworld S 16 / spree M / forem L), pluralization + only/except + claimsReference; explicit routes fixed to precise `controller#action` too. 🔬 ActiveRecord dynamic finders (`Article.find_by_slug`) — metaprogramming frontier |
+| PHP | Laravel | request → route → controller → Eloquent | R | ✅ **precise `Route::get([Ctrl::class,'m'])` / `'Ctrl@m'` → Ctrl@method** (realworld S / firefly M / bookstack L) — was resolving the bare method name to the WRONG controller (every `index`→ArticleController); Route::resource→controller. 🔬 Eloquent dynamic finders/relationships (metaprogramming frontier) |
+| PHP | Drupal | request → *.routing.yml → _controller/_form | R | ✅ **`claimsReference` for FQCN handlers** (`\Drupal\…\Class::method` passed the pre-filter only because the `::method` name was known; bare `_form` FQCNs `\…\FormClass` and single-colon `Class:method` controller-services were dropped before resolve()) + **single-colon controller match** + **detect via composer `type:drupal-*` / `name:drupal/*` + `*.info.yml` fallback** (a contrib module with empty `require` was undetected → 0 routes). admin_toolbar S **0→14 (14/14)** / webform M 208 (**144**) / core L 836 (536→**731, 87%**). Remainder is the **entity-annotation handler frontier** (`_entity_form: type.op` resolves via the entity's PHP `#[ContentEntityType]` handlers, not a direct class). 🔬 **OOP `#[Hook]` attributes** — Drupal 11 moved ~all procedural hooks to attribute methods (core: 418 `#[Hook]` files vs 3 procedural), so the resolver's docblock/`module_hook` detection is obsolete for modern core (0 hook edges) |
+| C/C++ | C++ vtables / inheritance | virtual call → override; general direct dispatch | S + X | ✅ **general dispatch strong** (redis C **29k** cross-file calls / leveldb C++ **1.4k**) + **C++ inheritance extraction fix** (`base_class_clause` was unhandled, so C++ extends edges were missing — leveldb **219→298**) + **cpp-override synthesizer** (base virtual method → subclass override, gated to C++, capped — leveldb 12 precise: `Iterator::Next→MergingIterator`). 🔬 C callback structs (`s->fn()` → 422-way fan-out, too noisy to synthesize) + C++ pure-virtual base methods (`virtual void f()=0;` declarations aren't extracted as nodes, so those overrides can't bridge) |
+| Dart | Flutter | setState → build; build → child widgets | S + X | ✅ **setState→build synthesizer** (Dart analog of react-render: a State method whose body calls `setState(` → `build`) gated to `.dart` + **foundational Dart method-range fix** — Dart models a method body as a *sibling* of the signature, so method nodes were signature-only (`end==start`); now `endLine` spans the body (required for ALL body analysis: callees, context slices, the synthesizer's body scan). counter `initState→build`, books `build→BookDetail/BookForm`; widget composition already static (compass_app `build→ErrorIndicator/HomeButton`). Controls unchanged (excalidraw 9,290 / django 302 — the range fix only extends sibling-body grammars). 🔬 MVVM Command/ChangeNotifier dispatch (compass_app — no setState) + `Navigator.push(MaterialPageRoute(builder:))` nav routes |
+| Lua / Luau | Neovim / Roblox | module dispatch (require→mod, mod.fn); event/callback | — | ✅ **already covered for the dominant flow (measure-first, no code change)** — Neovim is module-heavy (`require('x')` + `x.fn()`), and the general import + name resolution already handles it: telescope.nvim **220 imports + 335 cross-file `mod.fn` calls**, traces end-to-end (`map_entries ← init.lua → get_current_picker (state.lua)`). Luau instance-path `require(game:GetService(...))` handled by the extractor. 🔬 event-callback registration (`vim.keymap.set(…, fn)`, autocmd `callback=`, Roblox `signal:Connect(fn)`) is predominantly INLINE anonymous closures (corpus ~12 inline vs ~2 named) — the anonymous-handler frontier; named handlers too rare to justify a synthesizer |
+| Scala | Play / Akka | request → conf/routes → controller action | R + X | ✅ **Play `conf/routes` → controller** — the extensionless `conf/routes` wasn't indexed; added narrow file-walk opt-in (`isPlayRoutesFile`) + a Play resolver parsing `METHOD /path Controller.action(args)` → the action method (computer-database **0→8, 7/8**; starter 0→4, 3/4 — the unresolved are Play's framework `Assets` controller, external). Scala general controller→DAO dispatch already resolves. No-regression: the file-walk change only ADDS Play routes files (excalidraw 9,290 / suite 800 unchanged). 🔬 SIRD programmatic router (`-> /v1 Router` include + `case GET(p"/x")` in code) + Akka actor `receive`/`Behaviors.receiveMessage` message→handler |
+| Swift × Objective-C | mixed iOS apps | Swift `obj.foo(bar:)` → ObjC `-fooWithBar:`; ObjC `[obj fooWithBar:]` → Swift `@objc func foo(bar:)` | R | ✅ **Swift↔ObjC cross-language bridge** — `frameworks/swift-objc.ts` implements Apple's `@objc` auto-bridging name math (incl. init forms `initWith<First>:`, property getter+setter pairs, `@objc(custom:)` override) and the reverse direction strips Cocoa preposition prefixes (`With`/`For`/`By`/`In`/`On`/`At`/`From`/`To`/`Of`/`As`) to derive Swift base-name candidates. Validated on Charts S **28/1 obj→swift / swift→objc**, realm-swift M **36/1185**, wikipedia-ios L **52/983**. Genericname blocklist (`init`, `description`, `count`, …) keeps precision. Confidence 0.6 (name-match's 1.0 wins ties) — bridge only fires when name-match has no result. 🔬 Swift generics over ObjC protocols, Swift extensions on ObjC classes (silently miss; matches Java/Kotlin generics frontier) |
+| JS × native | React Native legacy bridge | JS `NativeModules.X.fn(...)` → ObjC `RCT_EXPORT_METHOD` / Java/Kotlin `@ReactMethod` | R | ✅ **RN legacy bridge** — `frameworks/react-native.ts` parses `RCT_EXPORT_MODULE` (default-name from `RCT`-prefix-stripped class name) + `RCT_EXPORT_METHOD(selector:(...))` + `RCT_REMAP_METHOD(jsName, selector)` on the ObjC side and `@ReactMethod` + `getName()` literal on Java/Kotlin. AsyncStorage S **8/8 precise** (`setItem`→`legacy_multiSet`, etc.), react-native-firebase L **18 precise after `RCTEventEmitter` built-in blocklist** (initial 78 included 60 `addListener:`/`remove:` false positives — every emitter subclass declares those via `RCT_EXPORT_METHOD`, JS callers route through the `NativeEventEmitter` abstraction not the native method directly). 🔬 dynamic bridge keys (`NativeModules[someVar]`) — literal-key only |
+| JS × native | React Native TurboModules | JS spec interface ↔ native impl | R (spec as ground truth) | ✅ partial — parses `TurboModuleRegistry.get*<Spec>('Name')` + the `Spec` interface methods. Each spec method matches to a native impl by selector first-keyword (ObjC) / identifier (JVM). react-native-svg S **9 precise** (`getTotalLength`, `getPointAtLength`, `getCTM`, `isPointInFill`, …) bridging to Java impls (the iOS side is Codegen-auto-generated without `RCT_EXPORT_METHOD` declarations). 🔬 TurboModule native impl classes that don't use legacy macros (RNSvg iOS — would need inheritance-aware bridging via the Codegen-generated `NativeFooSpec` superclass) |
+| ObjC/Java/Kotlin → JS | React Native event emitters | native `sendEventWithName:`/`emit(...)` → JS `addListener('e', handler)` | S (cross-lang channel) | ✅ **rn-event-channel synthesizer** — matches ObjC `sendEventWithName:@"X"`, Swift `sendEvent(withName: "X", ...)`, and JVM `.emit("X", ...)` to JS `addListener('X', handler)` keyed by literal event name. Same fan-out cap (`EVENT_FANOUT_CAP=6`) as in-language channel. **Subscribe-wrapper fallback** for RN-library APIs (`const Foo = { watchX(listener) { addListener('e', listener) } }`) — when the handler arg is a parameter, falls back to the enclosing function and then the enclosing `constant`/`variable` (reachability-correct attribution to the JS API surface). RNFirebase L **3 push-notification flow edges** (UIApplicationDelegate → JS `onMessage`/`onNotificationOpenedApp`), RNGeolocation S **2 location-event edges** (Swift `onLocationChange`/`onLocationError` → JS `Geolocation`). 🔬 inline arrow handlers `addListener('e', d => …)` (anonymous frontier) |
+| JS × Swift/Kotlin | Expo Modules | JS `requireNativeModule('X').fn(...)` → Swift/Kotlin `Function("fn") { ... }` | R (extract → synthetic method nodes) | ✅ **expo-modules framework extractor** — parses Swift/Kotlin `Module { Name("X"); Function("y") { ... }; AsyncFunction("z") { ... }; Property("w") { ... } }` literals and synthesizes `method` nodes named after each declaration. JS callsites resolve via existing name-matcher (no separate `resolve()` needed). expo-haptics S **6 method nodes** (`notificationAsync`, `impactAsync`, `selectionAsync` × Swift + Kotlin), expo-camera M **41** (full SDK surface incl. `takePictureAsync`, `record`, `scanFromURLAsync`, view props `width`/`height`), expo SDK sweep L **134** (7 packages, 72 Swift + 62 Kotlin). Same-name JS wrappers in the package itself shadow the native names (`CameraView.tsx`'s `pausePreview` wraps native `pausePreview`); external consumer apps bridge through to native directly. 🔬 closure body extraction (the Function trailing closure isn't a body-range node yet) |
+| JS × native | React Native Fabric / Codegen + legacy Paper view components | JSX `<MyView prop={v}/>` → Codegen spec → native class (or Paper `RCT_EXPORT_VIEW_PROPERTY` / `@ReactProp`) | R (extract) + S (native-impl) + JSX | ✅ **fabric-view extractor + fabric-native-impl synthesizer** — extractor parses **both** modern Codegen TS specs (`codegenNativeComponent<NativeProps>('Name', ...)`) **and** legacy Paper view-manager macros (`RCT_EXPORT_VIEW_PROPERTY` on ObjC, `@ReactProp` on Java/Kotlin). Emits a `component` node per declaration + a `property` node per declared prop. Synthesizer links the component to its native impl class by RN's convention-based name+suffix (`exact`/`View`/`ComponentView`/`Manager`/`ViewManager`). Combined with `reactJsxChildEdges`, full consumer flow: JSX `<MyView/>` → fabric `component` → native class. Validated on RNSegmentedControl S **(legacy Paper) 1 component + 11 props + 4 bridges**, RNScreens M **(pure Codegen) 27 components + 272 props + 68 bridges** (was 0 before Phase 6), RNSkia L **(hybrid + monorepo) 5 + 14 + 15 across Codegen TS + Android Java + iOS ObjC**. **Monorepo detect** added: probes `packages/<sub>/package.json` etc. via `listDirectories` when the root manifest is a workspace declaration (was the gating bug on RNSkia). 🔬 Fabric event-handler props (`onTap={cb}`) — JSX attribute extraction needed |
+
+(Verify the exact supported set against `src/extraction/languages/` and
+`src/resolution/frameworks/` before starting — this table is a starting point.)
+
+---
+
+## 7. Known limits & gotchas (from the excalidraw/django work)
+
+- **Coverage enables, doesn't force, the no-read path.** Agents still read to *confirm
+  source* sometimes; cost stays ~flat (codegraph calls trade for reads). The reliable
+  win is **completeness** + making Read-0 *possible*. Don't expect a guaranteed cost drop.
+- **Vue (validated 2026-05-23, vitepress S / vben M / element-plus L).** SFC `<template>`
+  is unparsed by the extractor, so template usage needs synthesis (`vueTemplateEdges`):
+  `@click="fn"` → handler, kebab `<el-button>` → `ElButton`. PascalCase `<Child/>` is
+  already covered by the JSX channel (the SFC component node spans the template). Result:
+  agent reads drop in every size (vben login 1–3 vs 4–11), **strongest where handlers are
+  local functions** (vben `handleLogin`/`handleSubmit`).
+  **Composable-destructure handlers RESOLVED:** `@click="closeSidebar"` where
+  `const { close: closeSidebar } = useSidebarControl()` now follows alias → composable →
+  the returned `close` fn (when it's defined in the composable's file). vitepress sidebar
+  flow dropped **6 → 0 reads** (best case). Precise-only — no fallback to the composable
+  itself (the static `useX()` call edge already covers that), so it adds nothing where the
+  returned fn can't be located (e.g. re-exported / external composable). Remaining limits:
+  **prefix-convention kebab** — element-plus `el-button` → `button.vue` (component named
+  `button`, not `ElButton`), so kebab stays unresolved there; and **reactive→render**
+  (vue-core Proxy runtime) — the deep framework-internal frontier, deferred.
+- **Svelte / SvelteKit (validated 2026-05-23, realworld S / skeleton M / shadcn L) — already well-covered.**
+  Unlike Vue, the `.svelte` extractor already parses the template: `extractTemplateCalls` (`{fn()}`),
+  `extractTemplateComponents` (`<Pascal/>` composition — skeleton 956 / shadcn 1610 reference edges),
+  plus `import * as api` namespace + `load`→api resolution all work. Agent A/B (realworld login): with
+  codegraph **1 read** vs without **4** — codegraph already wins out of the box. The one extraction gap
+  was **object-of-functions** (`export const actions = { default: async () => {} }`; the walker
+  deliberately skips object-literal functions to avoid inline-object noise). Fixed for EXPORTED consts
+  (general — Redux/Express handler maps too); `extractFunction` `nameOverride` keeps inline-object arrows
+  skipped. **Residual:** a `$lib`-alias namespace call (`api.post`) from an extracted action node doesn't
+  resolve even though the same alias resolves for `load` — a deeper resolver interaction, deferred
+  (local/relative calls from actions connect). **Lesson: measure before assuming a hole** — modern Svelte
+  barely uses `on:click={fn}` (form actions / callback props instead), so the assumed event-handler hole
+  wasn't the real one; Svelte needed far less than Vue.
+- **Express / Koa (validated 2026-05-23, realworld S / parse M / ghost L) — high-value inline-handler fix.**
+  The resolver already handled named handlers, middleware, and `XController.method`/`XService.method`.
+  The real hole was **inline arrow route handlers** (`router.post('/x', async (req,res) => {...})` — the
+  dominant modern pattern): the handler regex `[^)]+` broke on the arrow's `)`, so the route connected to
+  NOTHING and the anonymous handler's body (the request→service flow) was lost. The entire inline-handler
+  API was unreachable (realworld `POST /users/login` → 0 edges). Fixed (`frameworks/express.ts`): span the
+  call with a string-aware balanced scan; for inline arrows, extract the body's calls (RESERVED-filtered to
+  drop res/req/builtins) and attribute them to the route node → realworld **19** / ghost **65** precise
+  route→service edges (POST /users/login→login, POST /articles→createArticle, …), no node explosion,
+  framework-scoped (zero blast radius off Express). **Deterministic win is clear; the agent A/B is muddied
+  by repo characteristics** — realworld (39 files) is below the size where codegraph beats reading, and
+  Ghost's layered custom-API architecture makes both arms thrash. Residual: **custom routers** — payload's
+  6.4k-file codebase had 0 routes (its router abstraction isn't `app.get`-style, so undetected). Lesson
+  inverse of Svelte: Express's dominant pattern WAS the uncovered one, so it needed real work like Vue.
+- **NestJS (validated 2026-05-23, realworld S / immich M-L / amplication L) — already well-covered.** The
+  `nestjs` resolver handles @decorator routes (HTTP/GraphQL/microservice/WS). DI controller→service
+  (`this.svc.method()`) resolves correctly **even at scale** — every immich controller→service edge hit the
+  right same-module service (`addUsersToAlbum→addUsers`, `getMyApiKey→getMine`, `copyAsset→copy`) via
+  name + co-location, no type_of edge needed. Agent A/B (immich album flow): codegraph **eliminated Grep
+  (0 vs 3)** tracing route→controller→service. No dynamic-dispatch hole. One GENERAL hygiene gap surfaced
+  (not NestJS-specific): the realworld example **commits its `dist/`** build output, which codegraph indexes
+  (246 dup nodes) because the file walk only respects `.gitignore` with no default build-dir ignore. Real
+  apps (immich/amplication) gitignore `dist/` (0 dup nodes), so it's narrow — a default ignore for
+  `dist/build/out/.next/coverage` is a clean follow-up, deferred (core-indexer change, the user's call).
+- **Rails (validated 2026-05-23, realworld S / spree M / forem L) — high-value RESTful-routing fix.** The
+  `rails` resolver only saw explicit `get '/x' => 'c#a'` routes, so resource-routed apps (the dominant
+  pattern) had ZERO route nodes (realworld + spree). Fixed (`frameworks/ruby.ts`): expand `resources :x` /
+  `resource :x` into their RESTful actions (only/except filters + pluralization for the singular `resource`),
+  reference a precise `controller#action`, and resolve that to the action method in `<ctrl>_controller.rb`
+  (explicit routes fixed too — they referenced a bare ambiguous `action`). realworld **0→16**, forem
+  **0→635** precise route→action edges. Agent A/B (forem comment-creation, large): codegraph **1–4 reads /
+  0 grep / 47–53s** vs without **4–5 reads / 2–3 grep / 66–85s** — fewer reads, no grep, faster. **The
+  `claimsReference` pre-filter was the gotcha:** `articles#index` names no declared symbol, so `resolveOne`
+  dropped it before `resolve()` ran — needed the same claim hook as the django ORM work. Residuals: **Rails
+  Engine routing** (spree still 0 — it mounts an engine, not `config/routes.rb` resources); ActiveRecord
+  dynamic finders (`Article.find_by_slug` — metaprogramming frontier).
+- **Spring/MyBatis enterprise flow (validated 2026-05-26, mall-tiny S — closes #389).** Three holes that left
+  the canonical enterprise-Java chain (`HTTP route → Controller → BO/Service → ServiceImpl → DAO/Mapper →
+  MyBatis XML SQL`) broken at multiple hops on real Spring projects.
+  1. **Field-injected concrete-bean trace.** Java's `this.userbo.toLogin2()` parsed as `method_invocation(
+     object=field_access(this, userbo))`. The extractor surfaced `this.userbo.toLogin2` verbatim and the
+     name-matcher's single-dot regex couldn't unwrap it; even if it had, `userbo` doesn't capitalize cleanly
+     to `UserBO` (the JVM naming heuristic in `matchMethodCall.Strategy2`) so the receiver-typed lookup also
+     missed. Fix is in the language layer, not Spring-specific: (a) extractor unwraps `field_access(this, X)`
+     to use `X` as the receiver (`src/extraction/tree-sitter.ts`); (b) `matchMethodCall` learns to look up
+     the receiver name as a field declaration in the enclosing class and use the field's `signature`-stored
+     declared type (`inferJavaFieldReceiverType` in `src/resolution/name-matcher.ts`). Repro confirmed on the
+     issue's exact example: `UserAction.toLogin2 → UserBO.toLogin2` edge appeared (was 0 outgoing edges).
+  2. **MyBatis XML mapper indexing + Java↔XML bridge.** `*.xml` is now a language (`xml`), with a custom
+     extractor (`src/extraction/mybatis-extractor.ts`) that emits one method-shaped node per `<select|insert|
+     update|delete|sql id="X">` qualified as `<namespace>::<id>`, plus `<include refid="X"/>` → `<sql>`
+     fragment refs. Non-mapper XML (pom, log4j, web.xml) emits only a file node — no symbol noise. A new
+     synthesizer (`mybatisJavaXmlEdges` in `callback-synthesizer.ts`) indexes Java methods by
+     `<ClassName>::<methodName>` and joins them to the XML qualified names by suffix-match. Ambiguous
+     simple-name collisions are dropped (precision over recall). mall-tiny: 6/6 custom-SQL mapper methods
+     bridge to their `<select>` statements; full chain `trace(UmsRoleController.listResource → UmsResource
+     Mapper::getResourceListByRoleId(xml))` connects in 4 hops across controller/service/impl/mapper/XML.
+  3. **Spring config-key linkage.** `application.{yml,yaml,properties}` + profile variants
+     (`application-dev.yml`, `bootstrap.yml`, etc.) parse on the framework path. Leaf YAML keys + every
+     `.properties` line become `constant` nodes qualified by their dotted path. `@Value("${k}")` /
+     `@Value("${k:default}")` and `@ConfigurationProperties(prefix="X")` emit binding nodes that resolve to
+     the matching key (or, for prefix, the closest key under it). **Relaxed binding** (kebab `cache-list`
+     ↔ camel `cacheList` ↔ snake `cache_list` ↔ `CACHE_LIST`) handled via canonical-form match. mall-tiny:
+     11/11 `@Value` annotations resolved (incl. `secure.ignored` `@ConfigurationProperties` prefix).
+  Coverage frontier: cross-module XML statement references (`<include refid="other.X">` to a fragment in
+  another mapper file — works when the include uses the dotted namespace form); `@PropertySource` external
+  property files; Spring Cloud Config (remote properties); ambiguous mapper-name collisions across packages
+  (Java mapper `com.a.X` and `com.b.X` both with `selectOne` — currently dropped to avoid mis-resolving).
+- **Spring (validated 2026-05-23, realworld S / mall M / halo L) — bare-mapping + class-prefix routing fix.**
+  The resolver required a string path in the mapping regex, so BARE method mappings (`@PostMapping` with the
+  path on the class `@RequestMapping`) — the dominant multi-method-controller pattern — were missed (halo
+  had 28 routes for 2444 files; realworld's 2-action favorite controller linked only one). Fix
+  (`frameworks/java.ts`): treat class `@RequestMapping` as a PREFIX (joined, not a bogus route); match
+  verb-specific mappings BARE-or-with-path; also handle method-level `@RequestMapping(method=...)` (older
+  style). realworld 13→19, mall →246 precise route→method (class prefix joined); DI controller→service
+  resolves (`article→findBySlug`). Agent A/B (mall cart flow): with codegraph 0 reads/0 grep vs without 2/2.
+  **A first cut regressed mall 292→1** by dropping `@RequestMapping`-on-method — *caught by the cross-repo
+  route-count check*; the playbook's regression guard earns its keep. Residuals: halo's custom patterns
+  (9/29 resolve); Spring Data JPA derived queries (metaprogramming frontier).
+- **Django / DRF (validated 2026-05-23, realworld S / wagtail M / saleor L) — mostly covered + a DRF-router
+  fix.** The ORM (`_iterable_class`→ModelIterable, the original investigation) and URL routing
+  (`path`/`url`/`as_view`→view) were already done. The one hole: **DRF `router.register(r'articles',
+  ArticleViewSet)`** (the core CRUD endpoints) wasn't extracted — only `path()`/`url()` were. Fix
+  (`frameworks/python.ts`): match `router.register` (the STRING first arg separates it from
+  `admin.register(Model, Admin)`, whose first arg is a model class) → route→ViewSet class. Narrow in this
+  corpus (realworld has 1 router; wagtail uses `path()`, saleor is GraphQL) but real for DRF-router APIs.
+  Agent A/B (wagtail Page flow, medium): codegraph **4–7 reads / 1–4 grep / 58–81s** vs without **7–9 reads
+  / 6 grep / 82–86s** — fewer reads, fewer greps, faster. No regression (wagtail/saleor route counts
+  unchanged — purely additive). Residuals: signals (`post_save`→receiver), DRF viewset CRUD actions
+  (inherited from the base class, not in the user's ViewSet), saleor's GraphQL resolvers.
+- **Laravel (validated 2026-05-23, realworld S / firefly M / bookstack L) — route precision fix.** The
+  resolver discarded the controller from the handler: `Route::get([UserController::class,'index'])` /
+  `'UserController@index'` emitted a BARE `index` ref, which name-matching mis-resolved to the WRONG
+  controller (every `index`/`show` → whichever it found first; realworld GET user → ArticleController.index,
+  should be UserController). Fix (`frameworks/laravel.ts`): emit precise `Controller@method` (array + string
+  syntax, namespace-stripped) + `claimsReference` it past the pre-filter → existing Pattern-4
+  `resolveControllerMethod`. realworld all routes correct; bookstack 267/332 precise (GET pages →
+  PageApiController.list). Agent A/B (bookstack page-view, large): codegraph **2–3 reads / 1–2 grep /
+  51–60s** vs without **4–6 / 3–5 / 60–74s**. No node explosion. Residuals: firefly resolves only 3/568
+  (its fluent `->uses()` / `['uses'=>...]` handler format isn't parsed); Eloquent dynamic finders
+  (metaprogramming frontier).
+- **Gin / chi (validated 2026-05-23, realworld S / gin-vue-admin M / gitness L) — group-var routing fix.**
+  The route regex matched only `(router|r|mux|app|e).METHOD(...)`, but real apps route on GROUP vars
+  (`v1.GET`, `PublicGroup.GET`, `userRouter.POST`), so group-routed apps connected almost nothing
+  (gin-vue-admin: **4 routes for 625 files**). Fix (`frameworks/go.ts`): broaden the receiver to ANY
+  identifier — the verb + string-path + handler-arg gates keep it route-specific (`http.Get(url)` has no
+  handler arg → excluded). gin-vue-admin **4→259** routes (257 resolve precisely: `POST createInfo →
+  CreateInfo`); realworld stable (no regression); no garbage. **Agent A/B (create-user flow): codegraph
+  0 reads / 0 grep / 26–30s vs without 3 / 3 / 52–53s — cleanest backend win yet (0/0, 2× faster).**
+  Residuals: inline `func(c *gin.Context){}` handlers (anonymous, body lost — like Express before its fix);
+  gitness's chi custom handlers (26/321).
+- **ASP.NET Core (validated 2026-05-23, realworld S / eShopOnWeb M / jellyfin L) — detection + bare-attribute
+  fix.** Two holes: (1) `detect()` only fired on a `/Controllers/` dir or root `Program.cs`/`.csproj` (which
+  often isn't in the indexed source set), so feature-folder apps (realworld: `Features/*/FooController.cs`,
+  subdir `Program.cs`) were NEVER detected → 0 routes despite a full controller set. Broaden: scan
+  Controller/Program/Startup `.cs` for ASP.NET signatures. (2) the attribute regex required a string path →
+  bare `[HttpGet]` (route on the class `[Route("[controller]")]`) missed (eShopOnWeb was 24 bare / 2
+  string). Match bare-or-path + join the class `[Route]` prefix (like Spring). **No `claimsReference`
+  needed** — ASP.NET attribute routes are co-located IN the controller with the action, so the bare method
+  ref resolves same-file (unlike Rails/Laravel, whose routes live in a separate file). realworld 0→19,
+  eShopOnWeb 9→33, jellyfin 362→399, all precise (`GET /articles → Get`, class prefix joined), no explosion.
+  Agent A/B (eShop catalog listing): codegraph **1–2 reads / 0 grep / 63–75s** vs without **6–7 / 1–6 /
+  77–79s**. Residual: EF Core LINQ/DbSet (metaprogramming frontier).
+- **Flask / FastAPI (validated 2026-05-23, fastapi-realworld S / flask-microblog S / Netflix dispatch L /
+  redash L) — decorator-extraction + builtin-name fixes.** Routes were extracted but the request→route→handler
+  flow broke at two regex assumptions and one resolver filter. (1) **Flask required `def` immediately after
+  `@x.route(...)`**, so any intervening decorator (`@login_required`, `@cache.cached`) or **stacked `@x.route`
+  lines** (one view bound to several URLs) dropped the route — microblog extracted **6 of 27** real routes.
+  Switched Flask to FastAPI's `findHandler` scan (match the decorator, then find the next `def`), skipping
+  intervening decorators: **6→27**, all resolved. (2) **FastAPI's path regex `[^'"]+` rejected the empty path**
+  `@router.get("")` (router/prefix-root routes, frequently multi-line) → realworld lost 8 endpoints (list/create
+  article, comments, login/register). `[^'"]+`→`[^'"]*` + empty-path name guard: realworld **12→20**, Netflix
+  dispatch **290/290 (100%)**. (3) **Bare-name builtin guard** (`src/resolution/index.ts`): a handler named
+  after a Python builtin *method* (`index`, `get`, `update`, `count`…) was filtered by `isBuiltInOrExternal`
+  and lost its route→handler edge — microblog's `index` view (its `/` + `/index` stacked routes) resolved to
+  nothing. The dotted-method branch already had a `knownNames` guard; mirrored it onto the bare branch (a name
+  a declared symbol owns is not a builtin call). +2 legit edges on realworld, **0 change on the django control**
+  (302/373 identical — precision held). Flows trace end-to-end (`login → get_user_by_email` 2 hops;
+  `create_user → from_dict`). Agent A/B (realworld login-auth flow, n=2/arm): codegraph **0–1 read / 0 grep /
+  3–4 codegraph / 30–39s** (context→[search]→trace→node) vs without **3 read / 2 grep / 33–36s** — eliminates
+  grep, cuts reads to 0–1 (small repo, so wall-clock ties; the tool-count drop is the win). Residuals: **Flask-RESTful** class-based
+  `api.add_resource(Resource,'/x')` (redash's actual API shape — a separate class-method-as-verb mechanism, NOT
+  the README's documented decorator/blueprint Flask) and a pre-existing **JS file-route false-positive** in
+  redash's React frontend (32 bogus `.js` "routes" from a JS resolver — unrelated to Python). **Lesson: the
+  builtin-name filter is a silent precision tax across Python** — any view/function named `get`/`index`/`update`
+  loses edges; the fix is general (helps Django/DRF handlers too), not Flask-specific.
+- **Drupal (validated 2026-05-23, admin_toolbar S / webform M / drupal-core L) — pre-filter + detection fixes.**
+  The `*.routing.yml` extractor and the `_controller`/`_form` resolver already existed but two gaps kept most
+  routes unlinked. (1) **The `claimsReference` pre-filter gotcha (again):** Drupal handler refs are FQCNs
+  (`\Drupal\…\Class::method`), bare form classes (`\…\SettingsForm`), or single-colon controller-services
+  (`\…\Controller:method`). Only the `::method` shape survived `resolveOne`'s pre-filter (its `member` is a
+  known method name); the bare-FQCN forms and single-colon controllers named no declared symbol and were
+  dropped before `resolve()` ran. Added `claimsReference` (FQCN / `Class:method` / `hook_*`) + a single-colon
+  branch in the controller regex → core **536→731 of 836 routes (87%)**; all three previously-broken shapes now
+  resolve (`/admin/content/comment`→CommentAdminOverview form, `/big_pipe/no-js`→setNoJsCookie controller).
+  (2) **Detection missed standalone contrib modules:** `detect()` only checked composer `require` for a
+  `drupal/*` dep, but a contrib module often has an EMPTY `require` and is identified only by
+  `"name":"drupal/<m>"` + `"type":"drupal-module"` (admin_toolbar → 0 routes). Broadened to composer name/type
+  + a `*.info.yml` fallback → admin_toolbar **0→14 (14/14)**. Canonical flow traverses (`getAnnouncements` ←
+  `/admin/announcements_feed`); node count unchanged (resolution-only). Agent A/B (dblog route→controller,
+  n=2/arm): codegraph **0 read / 1 grep / 20–22s** vs without **1 read / 2 grep + glob / 28–32s** — fewer
+  tools and faster on the ~10k-file core. **Residuals (frontier):**
+  entity-annotation handlers (`_entity_form: comment.default` → handler classes declared in the entity's
+  `#[ContentEntityType]` annotation, not a direct ref — ~78 of core's ~105 remaining unresolved) and **OOP
+  `#[Hook]` attributes** — Drupal 11 converted nearly all procedural hooks to `#[Hook('event')]` methods (core:
+  418 attribute files vs 3 procedural `*.module` hooks), so the resolver's procedural-hook detection (docblock
+  `@Implements` / `module_hook` naming) finds essentially nothing in modern core (0 hook edges). Both are real
+  follow-ups, not regressions.
+- **Rust / Axum + Rocket + actix (validated 2026-05-23, realworld-axum S / actix-examples + Rocket M / crates.io L) — Axum chained-method + namespaced-handler fix.**
+  The attribute-macro path (`#[get("/x")] fn h`, actix/Rocket) and single Axum `.route("/x", get(h))` already
+  worked, but the Axum extractor used a flat regex that captured only the FIRST `method(handler)` of a route
+  and only a bare `\w+` handler. Two dominant Axum idioms broke it: (1) **method chains**
+  `.route("/user", get(get_current_user).put(update_user))` — the `.put` arm produced NO route node, so half
+  the API was missing (realworld-axum had only the GET of each chain); (2) **namespaced handlers**
+  `get(listing::feed_articles)` — `\w+` captured `listing` (the module), so the route resolved to nothing.
+  Rewrote with a balanced-paren scan of each `.route(...)` call, a per-method node, and last-`::`-segment
+  handler names → realworld-axum **12→19 routes, 19/19 resolved** (every chained PUT/DELETE/POST now present;
+  `feed_articles` resolves). **Rocket needed nothing** (550/556, 99% — attribute macros). crates.io confirms
+  namespaced axum handlers resolve (router.rs 6/6) but defines most of its API via the `utoipa_axum` `routes!`
+  macro (frontier) and has a SvelteKit frontend (42 of its 50 "routes" are `+page.svelte`, correctly
+  attributed to SvelteKit). Agent A/B (update-user flow,
+  n=2/arm): codegraph **0–2 read / 0 grep / 32–40s** vs without **3 read / 0–1 grep + glob / 33–41s** — modest
+  (realworld-axum is in the small-repo tie zone) but consistent, with one fully-clean 0-read/0-grep run. Node
+  count stable; the Axum fix is Axum-scoped (the attribute/actix/Rocket path is untouched).
+- **Actix runtime routing (validated 2026-05-23, actix-examples) — the builder API was the dominant style and fully missed.**
+  Actix's attribute macros (`#[get("/x")] fn h`) were covered, but real actix apps route via the builder API:
+  `web::resource("/path").route(web::get().to(handler))`, `web::resource("/").to(handler)` (all methods), and
+  App-level `.route("/path", web::get().to(handler))`. The handler lives in `.to(handler)`, not `get(handler)`,
+  so the Axum `.route` scan extracted nothing for them — actix-examples had **80 `web::resource` calls** all
+  unlinked. Added an actix block: scan each `web::resource("/path")` (bounding its method chain at the next
+  resource to avoid bleed) for `web::METHOD().to(h)` pairs, fall back to a direct `.to(h)` (method `ANY`), plus
+  the App-level `.route("/x", web::METHOD().to(h))` form. actix-examples **51→128 routes, 35→112 resolved
+  (87.5%)** (`GET /user/{name}`→with_param, `POST /user`→add_user). No regression on Axum (realworld-axum still
+  19/19) — the actix patterns (`web::resource`/`web::method().to()`) don't appear in Axum code. **Residuals
+  (frontier):** `web::scope("/api")` prefixes aren't prepended to nested resource paths, and anonymous `.to(|req|
+  …)` closure handlers have no named target (the ~16 still-unresolved).
+- **Swift / Vapor (validated 2026-05-23, vapor-template S / SteamPress M / SwiftPackageIndex-Server L) — the resolver was effectively dead on real apps.**
+  The Vapor extractor only matched `(app|router|routes).METHOD("path", use: handler)`, but modern Vapor routes
+  on a grouped builder inside `RouteCollection.boot(routes:)`: `let todos = routes.grouped("todos");
+  todos.get(use: index)` — any var receiver, NO path arg (the path is the group prefix). Every real app tested
+  extracted **0 routes** (template, penny-bot, Feather, SteamPress, SPI). Rewrote the extractor: (1) any
+  receiver `\w+` (not just app/router/routes); (2) optional path segments that may be non-string
+  (`User.parameter`, `:id`, a path constant) — the `use:` keyword is the discriminator separating a route from
+  `Environment.get("X")` / `req.parameters.get("X")`; (3) a group-prefix map from `let X = Y.grouped("a")` and
+  `Y.group("a") { X in }` so a route on a grouped/nested var gets the full path (`todo.delete(use: delete)` →
+  `DELETE /todos/:todoID`). Result: vapor-template **0→3 (3/3**, nested path exact), SteamPress **0→27
+  (27/27**, incl. `BlogPost.parameter` routes), SPI **0→14 (14/14** handler resolution). Canonical flow
+  traverses (`createPostHandler` ← `GET /createPost`, → `createPostView`). **Residuals (frontier):**
+  typed-route enums (SPI registers via `app.get(SiteURL.x.pathComponents, use:)` — handler resolves but the
+  path label is `/`, no string literal) and closure handlers (`app.get("hello") { req in }` — anonymous, no
+  named target). penny-bot (Discord bot) and Feather (custom module router) have no standard Vapor routing at
+  all — the Vapor ecosystem's routing styles vary widely. Agent A/B (create-post flow, n=2/arm): codegraph
+  **0 read / 0 grep / 4 codegraph / 26–30s** (both runs fully clean) vs without **1–4 read / 0–2 grep +
+  glob/bash, one run spawned a sub-agent / 34–48s**. Node count stable; fix is Vapor-scoped (SwiftUI/UIKit
+  untouched).
+- **React Router routing (validated 2026-05-23, react-realworld S) — the routing half of the React row.**
+  React rendering (state→render, jsx-child) was already covered; route→component was NOT — `react.ts` extracted
+  components/hooks and Next.js file routes but returned `references: []`, so `<Route>` declarations produced
+  nothing. Added `<Route>` JSX extraction: scan a window after each `<Route\b` (so the nested `>` in
+  `element={<Comp/>}` doesn't truncate it), pull `path="…"` + `component={C}` (v5) or `element={<C/>}` (v6) in
+  any attribute order, emit a route node + component reference (resolves via the existing PascalCase
+  `resolveComponent`). react-realworld **0→10, 10/10** (`/login`→Login, `/editor/:slug`→Editor,
+  `/@:username`→Profile); `<Routes>` container excluded via the `\b` boundary. No regression on excalidraw
+  (9,290 nodes, 46 react-render synth edges intact, 0 false routes). 🔬 the object **data-router** API
+  `createBrowserRouter([{ path, element }])` (modern v6, used by bulletproof-react) is object-based not JSX — a
+  separate frontier; plus a pre-existing Next.js false-positive (`*.config.mjs` in a `pages/` app dir treated
+  as a route).
+- **Dart / Flutter (validated 2026-05-23, flutter/samples: counter S / books S / compass_app M) — synthesizer + a foundational extractor fix.**
+  Flutter's reactive hop is `setState(() {…})` re-running `build(context)` — framework-internal, no static edge,
+  so "tap → handler → setState → rebuilt UI" dead-ends at setState (the Dart analog of React's setState→render).
+  Added a `flutter-build` synthesizer channel (Phase 4b): for each Dart class with a `build` method, link every
+  sibling method whose body calls `setState(` → `build` (gated to `.dart`). **But it was blocked by a
+  foundational gap:** Dart models a method body as a *sibling* of the `method_signature` node, so every Dart
+  method node had `endLine == startLine` (signature only) — `sliceLines(start,end)` saw only `void f() {`, never
+  the body. Fixed in the shared `createNode`: when a function/method's resolved body sits beyond the node,
+  extend `endLine` to it (guarded — child-body grammars are a no-op; controls excalidraw 9,290 / django 302
+  unchanged). This fix is foundational, not Flutter-specific — every Dart callee/context/body scan was
+  previously truncated. Result: counter `initState→build`, books `initState→build` + `build→BookDetail/BookForm`.
+  **Widget composition needs no synthesis** — unlike JSX, Dart widgets are explicit constructor calls
+  (`BookDetail(...)`), already static (compass_app `build→ErrorIndicator/HomeButton/_Card`). **Residuals
+  (frontier):** MVVM state management (compass_app uses Command/ChangeNotifier + ListenableBuilder, 0 setState —
+  a different dispatch shape) and `Navigator.push(MaterialPageRoute(builder: (_) => DetailPage()))` navigation
+  (route-as-widget, uncovered).
+- **Kotlin / Spring Boot + Jetpack Compose (validated 2026-05-23, spring-petclinic-kotlin S / compose-samples) — extend Spring to Kotlin; Compose is free.**
+  Kotlin had ZERO framework coverage — no resolver listed `kotlin`, and the Spring resolver was `languages:
+  ['java']` with a `.java`-only extract gate and a Java-syntax handler regex (`public X name()`). So Spring Boot
+  Kotlin apps (identical `@GetMapping`/`@RestController` annotations, `.kt` files) extracted 0 routes. Extended
+  the Spring resolver: `['java','kotlin']`, accept `.kt`, and add a Kotlin `fun name(` alternative to the
+  handler-method regex (Kotlin has no access modifier and the return type follows the name). petclinic-kotlin
+  **0→18, 18/18**; class `@RequestMapping` prefixes join, stacked annotations (`@ResponseBody`) are skipped, DI
+  controller→repo resolves (`showOwner ← GET /owners/{ownerId}` → `OwnerRepository.findById` /
+  `VisitRepository.findByPetId`). Java Spring unchanged (realworld 19/19 — the Kotlin `fun` and Java `public X`
+  alternatives are disjoint per language). **Jetpack Compose composition needs no work** — `@Composable`
+  functions calling child `@Composable`s are plain Kotlin function calls, already static (Jetcaster
+  `PodcastInformation→HtmlTextContainer`, `FollowedPodcastCarouselItem→PodcastImage`), like Dart widget
+  constructors. Agent A/B (view-owner flow, n=2/arm): codegraph **0–1 read / 0 grep / 1 codegraph / 11–18s** (a
+  single `context` call answers it) vs without **2 read / 0–1 grep + glob / 20–28s**. **Residuals (frontier):**
+  Ktor `routing { get("/x") { … } }` inline-lambda handlers (anonymous,
+  no named target), Compose recomposition (implicit — reading `mutableStateOf` triggers recompose, no
+  `setState`-style gate to anchor a synthesizer), and coroutines/Flow dispatch.
+- **Lua / Luau (validated 2026-05-23, telescope.nvim / lualine.nvim / Knit — measure-first, already covered).**
+  The matrix guessed "event/callback dispatch (synthesizer)", but measurement says otherwise: real Neovim
+  plugins are MODULE-dispatch-heavy (`local m = require('telescope.actions'); m.fn()`), and codegraph's general
+  `require`-import + cross-file name resolution already handles it — telescope.nvim has **220 resolved imports
+  and 335 cross-file `module.fn` call edges**, and a flow traces end-to-end (`map_entries ← init.lua →
+  get_current_picker` in actions/state.lua). The Luau extractor already handles Roblox instance-path requires
+  (`require(game:GetService("ReplicatedStorage").Packages.Knit)`). **The assumed hole isn't real** — like
+  Svelte/NestJS. The genuine frontier is event-callback registration (`vim.keymap.set(mode, lhs, fn)`, autocmd
+  `{callback=fn}`, Roblox `signal:Connect(fn)`), but it's predominantly INLINE anonymous closures (corpus: ~12
+  inline `:Connect(function…)` vs ~2 named), and telescope's keymaps are inline functions or vim-command
+  STRINGS, not named refs. A named-only callback synthesizer would cover a tiny fraction, so per "measure before
+  building / partial coverage is worse than none", none was built — no code change; recorded as validated.
+  Agent A/B (actions.utils map flow, n=2/arm): codegraph **0 read / 0 grep / 18–24s** vs without **1 read
+  (+glob) / 24–25s** — small flow so modest, but the 0-read confirms the module dispatch is navigable.
+- **Scala / Play (validated 2026-05-23, play-samples: computer-database / starter / rest-api) — Play conf/routes → controller.**
+  Scala's general dispatch (controller→DAO) already resolves, but Play declares routes in an EXTENSIONLESS
+  `conf/routes` file (`GET /computers controllers.Application.list(p: Int ?= 0)`) the file walk never indexed
+  (`isSourceFile` requires an extension). Added a narrow opt-in (`isPlayRoutesFile`: `conf/routes` / `*.routes`)
+  routed through the no-grammar (yaml-style) path, plus a Play resolver that parses each
+  `METHOD /path Controller.action(args)` line (dropping package prefix + args) and resolves `Controller.action`
+  to the action method in that controller class. computer-database **0→8 routes, 7/8** (the 1 unresolved is
+  `controllers.Assets.versioned` — Play's framework Assets controller, external), starter 0→4 (3/4). The flow
+  connects request→route→controller→DAO. A/B (list-computers, n=2/arm): codegraph **0 read / 0 grep / 3
+  codegraph / 17–22s** vs without **2–3 read / 1–2 grep + glob / 16–17s**. **No-regression:** the file-walk
+  change only ADDS Play routes files (narrow match) — excalidraw 9,290 and the full suite (800) unchanged.
+  **Residuals (frontier):** Play SIRD programmatic routers (`-> /v1 v1.PostRouter` include + `case GET(p"/x")`
+  in a Router class — rest-api-example) and Akka actor message→handler (`receive { case Msg => … }` /
+  `Behaviors.receiveMessage` — untyped, a synthesizer shape).
+- **C / C++ (validated 2026-05-23, redis C / leveldb C++) — general dispatch works; a C++ inheritance fix + override bridge.**
+  Measure-first: C/C++ DIRECT dispatch is excellent out of the box (redis **29,464 cross-file call edges**,
+  leveldb **1,462**) — the bulk of the value. The dynamic-dispatch frontier is two shapes: (1) C callback
+  structs (`struct {.proc=fn}` + `cmd->proc()`) — but in redis the `proc` field fans out to **422** command
+  functions, far too noisy to synthesize precisely, so deliberately skipped (per "partial coverage worse than
+  none"). (2) C++ vtables (`iter->Next()` → the subclass override). The override link was blocked upstream:
+  `extractInheritance` handled `base_clause` (PHP) but not C++'s `base_class_clause`, so C++ `extends` edges
+  were missing/partial (leveldb 219→**298** after the fix). Added a `cpp-override` synthesizer channel (the C++
+  analog of react-render): for each `extends` edge, link each base method → the subclass method of the same
+  name, so trace/callees from the interface method reach the implementation. leveldb **12 precise edges**
+  (`Iterator::Next/Seek/Prev → MergingIterator`), 0 on C (redis) and TS (excalidraw — gated to C++); the C++
+  override integration test passes. **Residual (frontier):** pure-virtual base methods (`virtual void Next() =
+  0;`) are declarations the extractor doesn't emit as nodes, so overrides of a purely-abstract interface can't
+  be bridged (only bases with a real method node — an inline default or non-pure virtual); plus the C
+  callback-struct fan-out. Relied on deterministic validation (no A/B): the cross-file-call counts + precise
+  override spot-check are conclusive.
+- **Frontier pass (2026-05-23) — tractable partials closed, noise/hard ones deliberately left.** After the main
+  sweep, swept the documented frontiers and triaged by precision/value. **DONE:** React Router object
+  data-router (literal `createBrowserRouter([{path, element}])`); Next.js route false-positives (config files +
+  `nextjs-pages/` substring → require a real page ext + path-segment match; bulletproof 4→0); Flask-RESTful
+  `add_resource`→Resource class (redash 6→**77**); Flask tuple `methods=(…)`; Flask detection broadened to
+  subdir/app-factory entrypoints (flask-realworld 0→**19**); gorilla/mux confirmed already covered (any-receiver
+  HandleFunc) + a test. **LEFT (with rationale, not punts):** C callback-struct dispatch (`cmd->proc()` →
+  422-way field fan-out = noise); metaprogramming finders (ActiveRecord/Eloquent/Spring-Data-JPA/EF — dynamic
+  naming, no static target); reactive runtimes (Vue Proxy / Compose recomposition — deep internals, no
+  setState-style gate); Akka actor message dispatch (untyped); pure anonymous inline closures (the def-use
+  frontier — no named target); React lazy data-router (variable paths + lazy imports); C++ pure-virtual base
+  methods (extracting bodyless decls risks duplicate decl/def nodes for modest gain). Forcing these would add
+  noise, violating "partial coverage worse than none."
+- **Difficulty gradient is real:** named-ref dispatch (resolver) is cheap; anonymous
+  callback dispatch (synthesizer) is medium; **anonymous-arrow handlers are the hard
+  remaining gap** (no identity → need synthesizer link-through-body, not yet built).
+- **Extraction changes are high blast radius.** The Phase-3 named-inline-callback
+  extraction is in the *shared* `tree-sitter.ts` walker — re-check **node counts across
+  several languages** after any extraction change (it held at +3 on excalidraw because
+  anonymous arrows are skipped).
+- **Synthesizer precision guards:** registrar-name uniqueness, named-only handlers, and
+  an event **fan-out cap** (skip generic events like `error`/`change`). Receiver-type
+  matching (via `type_of` edges) is the planned precision upgrade — deferred.
+- **As-built shortcuts** (callback synthesizer): pairs registrar/dispatcher by *file*+field
+  (class proxy), regex arg-recovery (named refs only), `provenance:'heuristic'` +
+  `metadata.synthesizedBy` (the enum has no `'callback-synthesis'`). See the design doc.
+- **Synthesizer runs only in `resolveAndPersistBatched`** (full index) — wire into
+  `resolveAndPersist` for incremental sync before shipping.
+- **Symbol ambiguity in `trace`:** common names (`render`, `execute_sql`) match many
+  nodes; trace picks among them and may start from the wrong one. Trace from the specific
+  method, not a class name.
+
+---
+
+## 8. Definition of done (the whole mission)
+
+For each language × framework: the canonical flow `trace`s end-to-end, an agent can
+answer the flow question with Read 0 in at least some runs with the glue present, no node
+explosion, no regression — recorded in the matrix (§6) with the validating repo + numbers.
+Then ship-prep: tests per mechanism, CHANGELOG, wire incremental, commit.
diff --git a/docs/design/function-ref-capture.md b/docs/design/function-ref-capture.md
new file mode 100644
index 000000000..7c8ef733f
--- /dev/null
+++ b/docs/design/function-ref-capture.md
@@ -0,0 +1,226 @@
+# Function-as-value capture (#756) — registration-linking for callbacks
+
+**Problem.** A function used as a *value* — passed as an argument, assigned to a
+function pointer or field, placed in a struct initializer or handler table —
+produced **no edge** in any of the 19 tree-sitter languages (probed 2026-06-11;
+0/19). `callers(my_recv_cb)` on a C callback showed nothing but direct calls, so
+every registered callback looked dead, and the registration sites — the agent's
+actual next question ("where is this wired up?") — were invisible.
+
+**Non-goal, deliberate.** Resolving the *dispatch* (`o->cb(x)` → the concrete
+registered function) needs data-flow through struct fields; even an LSP needs
+fallbacks there (see the #756 thread). Partial coverage is worse than none and
+a wrong edge is worse than silence — dispatch resolution stays uncovered. What
+ships is the *registration* side, which is deterministic: the function's name
+is literally in the source at the registration site.
+
+## Mechanism
+
+```
+capture (tree-sitter.ts walkers, table-driven per language: src/extraction/function-ref.ts)
+   → gate (flushFnRefCandidates: same-file fn/method name ∪ imported binding names;
+            C-family file-scope initializers skip the gate — see below)
+   → unresolved ref, referenceKind 'function_ref' (internal-only kind)
+   → resolution (resolveOne branch: resolveViaImport first, then matchFunctionRef —
+                 exact name, function/method kinds only, same-family, same-file first,
+                 cross-file only when UNIQUE, never fuzzy)
+   → edge kind 'references', metadata { fnRef: true, resolvedBy, confidence }
+```
+
+`getCallers`/`getCallees`/`getImpactRadius` already traverse `references`, so
+registration sites surface with no graph-layer changes. The MCP callers/callees
+lists label them "via callback registration".
+
+Capture fires from three walkers (a node is only ever visited by one):
+`visitNode` (file/class scope), `visitForCallsAndStructure` (function bodies),
+`visitPascalBlock` (Pascal bodies). Subtrees the walkers consume without
+descending (top-level variable initializers, class field/property initializers,
+custom `visitNode` hooks like Scala's val/var handler) get a candidates-only
+`scanFnRefSubtree` that halts at nested function boundaries.
+
+## Per-language value positions (probe-verified)
+
+| Language | arg | assign RHS | keyed init | list/table | wrapper forms |
+|---|---|---|---|---|---|
+| C / ObjC | `argument_list` | `assignment_expression.right` | `initializer_pair.value` | `initializer_list`, `init_declarator.value` | `&fn` (`pointer_expression`), `@selector(...)` (ObjC) |
+| C++ | **`&` forms only** in args/rhs/varinit | (same — explicit `&` only) | bare ids at FILE scope only | bare ids at FILE scope only | `&fn`, `&Cls::method` (resolved scoped to the class) |
+| TS / JS (tsx/jsx) | `arguments` | `assignment_expression.right` | `pair.value` | `array`, `variable_declarator.value` | `this.method` (`member_expression`, class-scoped — see rule 3) |
+| Python | `argument_list`, `keyword_argument.value` | `assignment.right` | `pair.value` | `list` | `self.method` (`attribute`) |
+| Go | `argument_list` | `assignment_statement` / `short_var_declaration` (`expression_list`) | `keyed_element` | `literal_value`, `var_spec.value` | — |
+| Rust | `arguments` | `assignment_expression.right` | `field_initializer.value` | `array_expression`, `static_item` / `let_declaration.value` | — |
+| Java | `argument_list` | `assignment_expression.right` | — | `variable_declarator.value` | `method_reference` (`Cls::m`, `this::m`) — the only form |
+| Kotlin | `value_arguments` | `assignment` (last child) | — | — | `callable_reference` (`::f`), `navigation_expression` `this::m` |
+| C# | `argument_list` (`argument`) | `assignment_expression.right` (incl. `+=`) | — | `initializer_expression`, `variable_declarator` | `this.M` (`member_access_expression`; vendored grammar keeps `this` anonymous — handled) |
+| Ruby | `argument_list` | — | `pair.value` | — | only `method(:sym)` / `&method(:sym)` — bare ids are calls/locals in Ruby |
+| Swift | `value_arguments` (`value_argument.value`) | `assignment.result` | (labeled ctor args = args) | `array_literal`, `property_declaration.value` | `#selector(...)` |
+| Scala | `arguments` | `assignment_expression.right` | — | `val_definition.value` (via hook scan) | eta `fn _` (`postfix_expression`) |
+| Dart | `arguments` (`argument`) | `assignment_expression.right` | `pair.value` | `list_literal`, `static_final_declaration` | — |
+| Lua / Luau | `arguments` | `assignment_statement` (`expression_list.value`) | `field.value` (keyed + positional) | (same) | — |
+| Pascal | `exprArgs` (via `visitPascalBlock`) | `assignment.rhs` (`OnFire := Handler`) | — | — | `@Handler` (`exprUnary.operand`) |
+| PHP | string callables ONLY as args of known core HOFs (`usort`, `array_map`, `call_user_func*`… — `PHP_CALLABLE_HOFS`), ungated + unique-or-drop (PHP globals aren't imported) | — | — | — | `[$this, 'm']` → class-scoped `this.m`; `[Foo::class, 'm']` → qualified; `'Cls::m'` → qualified; first-class callable `fn(...)` already extracts as `calls` |
+| Ruby hooks | `(skip_)?(before\|after\|around)_*` + `validate`/`set_callback`/`helper_method`/`rescue_from(with:)` symbols → class-scoped `this.<sym>` (rides the supertype pass: `before_action :authenticate` → ApplicationController). `validates` (plural) excluded — its symbols are ATTRIBUTES | — | — | — | symbols under any other call yield nothing |
+
+## Precision rules (each one bought by a real-repo false positive)
+
+1. **The gate** (extraction-time): a candidate survives only if its name matches
+   a same-file function/method or an **imported binding** (`referenceKind ===
+   'imports'` only — scraping type-annotation `references` names let locals that
+   shared a type-member's name through; excalidraw).
+2. **C-family ungated file scope**: C has no symbol imports and registers
+   callbacks cross-file at repo scale (redis `server.c`'s command table names
+   handlers from `t_*.c`). File-scope initializer positions (`value`/`list`
+   modes) skip the gate — safe because a C file-scope initializer is a
+   **constant-expression context**: a bare identifier there can only be a
+   function address (enum/macro names get dropped by the kind filter). Local
+   initializers and assignments stay gated: `prev = next`, `*str = field`,
+   `arena_ind_prev = arena_ind` (redis/jemalloc) each matched a unique
+   same-named function somewhere and produced wrong edges when `rhs`/`varinit`
+   were ungated.
+3. **TS/JS/Python: bare ids resolve to `function` kind only.** A bare
+   identifier can never be a method value in these languages (methods need a
+   receiver — `this.m` / `self.m`), so allowing method targets soaked up
+   locals passed as arguments (`new Set(selectedPointsIndices)`;
+   docopt.py's `name`/`match` params — excalidraw/fmt A/B findings).
+   TS/JS `this.X` values are captured as `this.`-PREFIXED candidates and
+   resolved CLASS-SCOPED (`resolveThisMemberFnRef` in
+   `src/resolution/index.ts`): the target must be a function/method whose
+   qualified name shares the from-symbol's class prefix, same file, no
+   fallback of any kind — `addEventListener(…, this.onResize)` hits the
+   enclosing class's method; `this.fonts` (a property, post-#808 field
+   classification) and inherited/unknown members yield no edge. Python's
+   `self.m` form keeps method targets through its own capture shape.
+   C#/Swift/Dart/Java/Kotlin keep method targets (method groups,
+   implicit-self, method references are real method values).
+4. **C++ is `&`-explicit** (`addressOfOnly`): bare identifiers qualify only in
+   FILE-scope initializer tables; everywhere else (args, assignments, local
+   braced-init lists `{begin, size}`) only `&fn` / `&Cls::method` count.
+   C++ codebases are dense with generic free-function names (`begin`, `end`,
+   `out`, `size`, `data`) colliding with locals, and OUT-OF-LINE member
+   definitions extract as *function*-kind nodes, defeating the kind filter —
+   bare-id matching on fmt was mostly wrong edges (72 generic-name + 105
+   member/macro mismatches → after the rule: 22 edges, ~20 genuine gtest
+   member-pointer wirings). `&x` vs `*x` share C's `pointer_expression`; only
+   the `&` operator qualifies. `&Cls::method` resolves SCOPED to that class.
+5. **Swift overload-family refusal**: several same-named METHODS in one file
+   (`Session.request(...)` × N) + a bare identifier = almost always a
+   same-named parameter, not a method value (Alamofire) — refuse rather than
+   guess. A unique method (SwiftUI `action: handleTap`) still resolves.
+6. **Param-forward skips**: `this.status = status` / `o->cb = cb` (assignment
+   whose member name equals the RHS identifier) and Swift/Kotlin labeled args
+   `value: value` — a forwarded local/parameter whose function value is
+   unknowable; a same-named function elsewhere would be the WRONG target.
+7. **Destructuring skip**: `const { center } = ellipse` extracts data, never a
+   function alias.
+8. **Generated/minified files** (`*.min.js` and the codegen patterns in
+   `generated-detection.ts`) produce no fn-ref candidates — minified
+   single-letter symbols resolve everywhere (Alamofire's vendored jquery).
+9. **Resolution**: function/method kinds only, same language family, never the
+   ref's own node (no self-loops), same-file match first, cross-file only when
+   the name is UNIQUE — ambiguity yields **no edge**. No fuzzy fallback,
+   ever (`matchReference` short-circuits `function_ref` refs to
+   `matchFunctionRef`).
+10. **Runaway invariant** (#760): `matchFunctionRef` always returns
+    `original: ref` — the stored row — so `deleteSpecificResolvedReferences`
+    drains the batch.
+
+## Validation (2026-06-11, EXTRACTION_VERSION 19)
+
+Stash-free A/B (baseline = worktree at `main`), fresh shallow clones, public
+OSS only. Per repo: node count must be identical, `calls` edges identical,
+`references` strictly additive, precision spot-checked by reading the source
+line of sampled `fnRef` edges.
+
+Final build, all 17 repos (nodes identical and calls edges untouched on every
+row; `unresolved_refs` fully drained — no batched-resolver runaway):
+
+| Lang | Repo | Nodes (base=fix) | calls Δ | refs gained | Notes |
+|---|---|---|---|---|---|
+| C | redis | 18931 | 0/0 | **+1918** | 30/30 sample genuine — ops tables, qsort comparators, module registration, lua lib tables |
+| TS/React | excalidraw | 10299 | 0/0 | **+121** | 18/20 — residual = param shadowing an imported function (file-level dep real) |
+| Go | gin | 2599 | 0/0 | +14 | |
+| Rust | bytes | 947 | 0/0 | +76 | `map(fn)`, struct init |
+| Java | okhttp | 16008 | 0/0 | +2 | method-ref forms only, by design |
+| Kotlin | okio | 7801 | 0/0 | +1 | `::fn` forms only, by design |
+| Swift | alamofire | 3477 | 0/0 | +116 | adversarial case (params mirror API names); overload-family + label==name rules applied |
+| Python | flask | 2705 | 0/0 | +111 | 8/8 sample genuine — incl. `ensure_sync(self.dispatch_request)` |
+| Ruby | sinatra | 1751 | 0/0 | +8 | `method(:sym)` only |
+| C# | newtonsoft | 20208 | 0/0 | +38 | method groups, `+=` |
+| Scala | scopt | 694 | 0/0 | +10 | eta-expansion |
+| Dart | provider | 1154 | 0/0 | +73 | implicit-this getter reads — true same-class dependencies |
+| Lua | busted | 1257 | 0/0 | +14 | |
+| Luau | fusion | 2126 | 0/0 | +18 | `:Connect(fn)` |
+| ObjC | afnetworking | 1487 | 0/0 | +52 | `@selector`, target-action |
+| Pascal | pascalcoin | 48788 | 0/0 | +577 | `OnClick :=` event wiring + paren-less-call refs (see limits) |
+| C++ | fmt | 7345 | 0/0 | +22 | ~20/22 genuine gtest member-pointer plumbing after addressOfOnly |
+
+Index cost on redis: +6% time, +5% db size.
+
+## Known limits (documented, deliberate)
+
+- **Dispatch resolution** (`o->cb(x)` → implementations): uncovered, see above.
+- **C cross-file in gated positions**: an extern callback registered via
+  *assignment* in a different file than its definition only resolves when the
+  name is repo-unique (initializer tables don't have this limit — they're
+  ungated at file scope).
+- **C++ bare-name registration** (`register_handler(my_cb)` without `&`):
+  dropped by `addressOfOnly` — the generic-name collision rate made bare ids
+  net-negative on real C++ (fmt). `&my_cb` / file-scope tables cover the
+  idioms; C files keep bare args.
+- **Local/param shadowing an imported or same-file function**
+  (`mutateElement(newElement, …)` where the file also imports `newElement`;
+  JS plugins' `indexOf(val)` with a same-file `val()` helper): irreducible
+  without local-scope tracking — the data-flow frontier deliberately left
+  uncovered. ~1-2 per 20 sampled edges on callback-heavy repos; the file-level
+  dependency is real in every observed case.
+- **Swift same-class param collisions** (`eventMonitor?.request(self,
+  didFailTask: task…)` where the enclosing type ALSO has a `task` method):
+  enclosing-type scoping (implicit self — methods match only the from-symbol's
+  own type, top-level bare ids never match methods) eliminated the CROSS-class
+  collision class on Alamofire (−44 wrong edges), but a parameter named after
+  a method of the SAME type is statically indistinguishable from an
+  implicit-self method value. Residual, documented.
+- **Pascal paren-less calls** (`Result := DoInitialize`): captured as
+  references (Pascal can't distinguish a procedure VALUE from a paren-less
+  CALL without types). The dependency direction is correct and these calls
+  were previously invisible entirely (#791) — strictly more truth, imperfect
+  label.
+- **Java/Kotlin method refs through a VARIABLE** (`subscriber::onNext`,
+  `m::run0`): receiver type unknown statically — deliberately no edge (the
+  obj.method class). RxJava's baseline bare capture was resolving these to
+  same-named same-file methods (a test method "registering" an anonymous
+  class's `onNext`); the qualified rework drops them. `Type::method` resolves
+  cross-file (scope gated on same-file types ∪ imported names, incl. the last
+  segment of dotted JVM imports); `this::m` / `super::m` ride the
+  class-scoped + supertype path.
+- **Qualified `Type::member` candidates skip the name gate** (like `this.X`):
+  Java/Kotlin same-package references and Kotlin companions need NO import,
+  so the gate could never see their scope — and the explicit-ref syntax is
+  self-selecting while resolution stays scope-suffix-anchored +
+  unique-or-drop (a `Decoy::handle` can't match a `KtHandlers::handle` ref).
+  This is also what resolves companion-member refs: companions extract
+  TRANSPARENTLY (`KtHandlers::handle`, method of the class) in real
+  multi-line code. (A single-line `class X { companion object { … } }` is an
+  upstream tree-sitter-kotlin misparse — ERROR node — and only ever appeared
+  in our own probe fixture; don't chase it.)
+- **Swift cross-file bare references**: Swift sees module-wide symbols without
+  imports, so cross-file bare callbacks only resolve when repo-unique
+  (functions; methods are enclosing-type-only). Cross-TYPE `#selector`
+  targets (rare — target-action is normally self) are scoped away too.
+- **`obj.method` member values** where `obj` isn't `this`/`self`: deferred —
+  the receiver's type is statically unknowable without local data-flow.
+- **PHP strings outside known-HOF positions** (a bare `'handler'` to an
+  arbitrary function; framework registries like WordPress `add_action`):
+  deliberately uncaptured — a string is only trustworthy as a callable in a
+  known callable position. Framework registries belong in a `frameworks/`
+  resolver if ever added. **Ruby symbols outside the hook DSLs** likewise.
+- **The supertype pass is NODE-anchored** (file-anchored class node →
+  implements/extends edge targets → `contains`-anchored member lookup): a
+  name-keyed `getSupertypes('Engine')` unioned every rails `Engine`'s parents
+  and produced a cross-class wrong edge; the node walk eliminated it
+  (rails +440 → +385, all sampled edges genuine).
+- **`this.X` inherited members resolve through the supertype pass**
+  (`resolveDeferredThisMemberRefs`, depth-capped BFS over implements/extends,
+  runs after edges persist — same lifecycle as the #750 conformance pass).
+  Reading a getter into a local (`const s = this.snapshot`) still produces a
+  references edge to the getter — a true dependency with an imperfect
+  "registration" flavor.
diff --git a/docs/design/mixed-ios-and-react-native-bridging.md b/docs/design/mixed-ios-and-react-native-bridging.md
new file mode 100644
index 000000000..4352ca9df
--- /dev/null
+++ b/docs/design/mixed-ios-and-react-native-bridging.md
@@ -0,0 +1,555 @@
+# Mixed iOS + React Native Bridging — Coverage Design
+
+**Audience:** a Claude agent (or human) continuing this work after #165 landed
+pure-Objective-C support.
+**Mission:** make codegraph's `trace` / `callers` / `callees` / `impact` /
+flow-context calls connect end-to-end across **cross-language runtime
+dispatch boundaries** that today silently break flows: **Swift ↔ Objective-C**
+in mixed iOS codebases, and **JavaScript ↔ native** in React Native / Expo
+apps.
+
+> This doc is the **plan**, not the implementation. No code lands on this
+> branch — only the design, the validation corpus, and the success bar.
+> Coding starts on a follow-up branch per phase.
+
+This work is the next item on the
+[dynamic-dispatch coverage playbook](./dynamic-dispatch-coverage-playbook.md) §6
+matrix: row "Swift × Objective-C bridging" and a new "React Native bridge"
+row. Both are **resolver** patterns (named refs exist on both sides — the
+bridging rule is deterministic) — not synthesizer patterns. See §3a of the
+playbook for the reference Django ORM resolver.
+
+---
+
+## 1. Why this matters (the gap today)
+
+After #165, codegraph indexes Swift, Objective-C, and JavaScript/TypeScript
+each correctly **in isolation**. But the value is in cross-language flows —
+exactly where iOS apps and React Native apps live:
+
+- **Mixed iOS app:** `MyViewController.swift` calls `imageDownloader.download(url:completion:)`,
+  which is `-[ImageDownloader downloadURL:completion:]` in `ImageDownloader.m`.
+  Today: a `trace("MyViewController.viewDidLoad", "downloadURL:completion:")`
+  call returns no path. The Swift callsite parses as a `call_expression` whose
+  selector goes nowhere; the ObjC method exists as a node with no incoming
+  edge. The agent reads both files to reconstruct the bridge.
+- **React Native app:** `useEffect(() => NativeModules.Geolocation.getCurrentPosition(cb))`
+  in `App.js` reaches `RCT_EXPORT_METHOD(getCurrentPosition:(RCTResponseSenderBlock)cb)`
+  in `RNCGeolocation.m`. Today: the JS callsite has no outgoing edge to
+  the ObjC implementation; the ObjC handler has no incoming edge from JS.
+  `impact(getCurrentPosition)` (ObjC side) shows no JS callers.
+- **Expo module:** `await ExpoCamera.takePictureAsync(options)` (JS) reaches
+  `AsyncFunction("takePictureAsync") { ... }` in `ExpoCamera.swift` (Expo
+  Modules API). Same break.
+
+In every case **a name exists on both sides** that an agent or a name-matcher
+can correlate — Swift's auto-bridged ObjC selector, `RCT_EXPORT_METHOD`'s
+literal first argument, an Expo `Function("name")` literal. The fix is a
+**resolver** that knows the bridging rules per channel and emits
+`references` edges with `provenance:'heuristic'` and `metadata.synthesizedBy:'<channel>'`.
+
+The playbook's load-bearing warning applies here harder than usual:
+
+> **Partial coverage is WORSE than none.** Bridging one boundary but not the
+> next reveals a hop the agent then drills + reads to finish. Always close
+> the flow end-to-end and re-measure — never ship a half-bridged flow.
+
+For mixed iOS, this means **both directions** (Swift→ObjC and ObjC→Swift) and
+**all bridged kinds** (methods, properties, init/initializers, protocols)
+must close before measuring. For React Native, JS→native AND
+native→JS (`RCTEventEmitter`, `sendEvent`) must both close, AND on **both
+the legacy bridge and TurboModules**, or apps that mix them will half-bridge.
+
+---
+
+## 2. The bridging mechanisms to model
+
+Each row is a separate **dispatch channel** in the playbook's vocabulary —
+each gets its own resolver (or synthesizer if no static ref exists), its own
+validation, its own row in the §6 matrix.
+
+| # | Direction | Channel | Mapping rule | Where it lives | Difficulty |
+|---|---|---|---|---|---|
+| 1 | Swift → ObjC | direct call, ObjC class imported via `-Bridging-Header.h` | Swift call `obj.x(y:z:)` ↔ ObjC selector `-x:z:` (literal mapping, see §3a) | resolver in `frameworks/swift-objc.ts` | medium |
+| 2 | ObjC → Swift | `@objc` exposure | Swift `@objc func foo(bar:)` ↔ ObjC `-fooWithBar:` (auto-name); `@objc(custom:)` overrides | resolver in `frameworks/swift-objc.ts` | medium |
+| 3 | Swift ↔ ObjC | property/getter/setter bridging | Swift `var name: String` ↔ ObjC `-name` / `-setName:` | resolver in `frameworks/swift-objc.ts` | low |
+| 4 | Swift ↔ ObjC | initializer bridging | Swift `init(name:age:)` ↔ ObjC `-initWithName:age:` | resolver in `frameworks/swift-objc.ts` | low |
+| 5 | Swift ↔ ObjC | protocol bridging (`@objc protocol`) | conformance edges across language | resolver in `frameworks/swift-objc.ts` | medium |
+| 6 | JS → ObjC (RN legacy bridge) | `NativeModules.<Mod>.<fn>` ↔ `RCT_EXPORT_METHOD(<fn>:...)` or `RCT_REMAP_METHOD(<jsName>, <selector>:...)` | name match keyed by `RCT_EXPORT_MODULE()` literal on the ObjC side | resolver in `frameworks/react-native.ts` | medium |
+| 7 | JS → Java/Kotlin (RN legacy bridge, Android) | `NativeModules.<Mod>.<fn>` ↔ `@ReactMethod` annotated method on a `ReactContextBaseJavaModule` subclass with `getName()` returning `<Mod>` | resolver — same shape as #6, JVM side | medium |
+| 8 | JS ↔ native (RN TurboModules / Codegen) | `TurboModuleRegistry.get('Mod')` ↔ generated spec interface (`NativeMod` TS type) ↔ ObjC++/Kotlin impl matching the spec | resolver that reads the spec file as ground truth | hard |
+| 9 | Native → JS (events) | ObjC `[self sendEventWithName:@"x" body:b]` (extending `RCTEventEmitter`) ↔ JS `new NativeEventEmitter(NativeModules.Mod).addListener('x', cb)` | EventEmitter-style synthesizer (matches existing `callback-synthesizer.ts` for in-language EventEmitter) | medium |
+| 10 | JS → native (Expo modules) | JS `ExpoX.fn(args)` ↔ Swift `Function("fn") { ... }` or `AsyncFunction("fn") { ... }` inside a `Module` subclass with `Name("ExpoX")` | resolver in `frameworks/expo-modules.ts` | medium |
+| 11 | JS → native (Fabric view components) | JS `<MyView prop={v}/>` ↔ ObjC/Swift `RCT_EXPORT_VIEW_PROPERTY(prop, ...)` or Codegen view spec | resolver + JSX hop (compose with existing JSX synthesizer) | hard (defer) |
+
+The **Difficulty** column drives phasing — see §6.
+
+### 2a. Why these are resolvers, not synthesizers
+
+In every row, **the bridging rule is deterministic from a name**:
+- Swift's `@objc` exposure is a documented automatic mapping; `@objc(custom:)`
+  is an explicit override; both are statically extractable.
+- `RCT_EXPORT_METHOD` takes a literal selector; `RCT_EXPORT_MODULE()` takes
+  an optional literal module name (default: class name minus `RCT` prefix);
+  `NativeModules.Mod.fn` is a literal-property access on a known global.
+- Expo Modules `Function("name") { ... }` and `Module { Name("ExpoX"); ... }`
+  are literal strings inside `Module` definitions.
+- TurboModules spec interfaces are literal `Native<Name>` exports with
+  `TurboModuleRegistry.get<...>('<Name>')`.
+
+So the work is: **extract the bridging-side names → make the resolver match
+them**. Same shape as `djangoResolver` resolving `_iterable_class` to
+`ModelIterable` — no whole-graph correlation pass needed.
+
+The one exception is **#9 native→JS events**, where the registration sites
+look very much like the in-language EventEmitter pattern the existing
+callback synthesizer already handles. Extending that synthesizer with a
+cross-language channel is the natural fit.
+
+---
+
+## 3. Concrete bridging rules (the reference table)
+
+### 3a. Swift → ObjC selector mapping (auto)
+
+Swift uses standard rules to derive an ObjC selector from a Swift method:
+
+| Swift declaration | ObjC selector |
+|---|---|
+| `func greet()` | `greet` |
+| `func say(_ msg: String)` | `say:` |
+| `func set(name: String)` | `setWithName:` |
+| `func setName(_ name: String)` | `setName:` |
+| `func move(to point: CGPoint)` | `moveTo:` |
+| `func move(from a: CGPoint, to b: CGPoint)` | `moveFrom:to:` |
+| `init(name: String)` | `initWithName:` |
+| `init(name: String, age: Int)` | `initWithName:age:` |
+| `var name: String` (getter) | `name` |
+| `var name: String` (setter) | `setName:` |
+| `@objc(customSel:) func f(...)` | `customSel:` (explicit override) |
+
+The full rule set is at
+[Apple — Importing Swift into Objective-C](https://developer.apple.com/documentation/swift/importing-swift-into-objective-c)
+— specifically the "method name translation" and "initializer name translation"
+sections. The resolver implements this mapping in **one direction at extract
+time** (Swift declarations produce the bridged ObjC name, attached as an
+alias on the Swift method node), so name resolution on the ObjC side finds
+the Swift method through normal name-matching.
+
+### 3b. React Native legacy bridge — name resolution
+
+```objc
+// Native side (ObjC)
+@implementation RCTGeolocation
+RCT_EXPORT_MODULE();                                    // module name: "Geolocation" (RCT prefix stripped)
+RCT_EXPORT_METHOD(getCurrentPosition:(RCTResponseSenderBlock)cb) { ... }
+@end
+```
+```js
+// JS side
+import { NativeModules } from 'react-native';
+NativeModules.Geolocation.getCurrentPosition(cb);       // resolves to the ObjC method above
+```
+
+Rule:
+1. On the native side, extract a synthetic `module` node per class containing
+   `RCT_EXPORT_MODULE()`. Name = explicit string argument if present, else
+   class name with `RCT` prefix stripped.
+2. Each `RCT_EXPORT_METHOD(<sel>)` and `RCT_REMAP_METHOD(<jsName>, <sel>)`
+   becomes a method node attached to that module node, with the JS-visible
+   name (`<sel>`'s first keyword for `RCT_EXPORT_METHOD`, or `<jsName>` for
+   `RCT_REMAP_METHOD`).
+3. On the JS side, the resolver matches the literal property chain
+   `NativeModules.<Mod>.<fn>` against `(module, jsName)` pairs from the
+   native side.
+4. Resolver emits `references` (`provenance:'heuristic'`, `synthesizedBy:'rn-bridge'`)
+   from the JS callsite to the native method.
+
+### 3c. React Native TurboModule — name resolution
+
+```ts
+// Spec (TS) — codegen ground truth
+export interface Spec extends TurboModule {
+  getCurrentPosition(cb: (loc: Location) => void): void;
+}
+export default TurboModuleRegistry.getEnforcing<Spec>('Geolocation');
+```
+```objc
+// ObjC++ impl
+@implementation RCTGeolocation
+- (void)getCurrentPosition:(RCTResponseSenderBlock)cb { ... }
+@end
+```
+```js
+import Geolocation from './NativeGeolocation';
+Geolocation.getCurrentPosition(cb);  // resolves to the ObjC method via the spec
+```
+
+Rule:
+1. The spec file is the source of truth: parse `TurboModuleRegistry.get*<Spec>('<Name>')`
+   to find the module name, then read the `Spec` interface methods.
+2. Match each spec method to the native impl's same-named method (by selector
+   first-keyword, in the class identified by name convention or by reading
+   any `JSI_EXPORT_MODULE` macro if present).
+3. JS imports of the spec file get name resolution through the spec.
+4. Emits the same `references` edges as #3b, with `synthesizedBy:'rn-turbomodule'`.
+
+### 3d. Expo Modules — name resolution
+
+```swift
+// Native (Swift, expo-modules-core API)
+public class ExpoCameraModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("ExpoCamera")
+    AsyncFunction("takePictureAsync") { (options: CameraOptions) in /* ... */ }
+    View(ExpoCameraView.self) {
+      Prop("type") { (view: ExpoCameraView, type: String) in /* ... */ }
+    }
+  }
+}
+```
+```js
+import { requireNativeModule } from 'expo-modules-core';
+const ExpoCamera = requireNativeModule('ExpoCamera');
+await ExpoCamera.takePictureAsync({ quality: 1 });
+```
+
+Rule:
+1. On the native side: a class extending `Module` whose `definition()` (or
+   `init { /* DSL */ }` for newer API) contains a `Name("X")` call defines
+   the module. Each `Function("y")` / `AsyncFunction("y")` literal defines a
+   method. The trailing closure is the implementation body — extract as a
+   method node named `y`, attached to module `X`.
+2. On the JS side: `requireNativeModule('X')` produces a binding; resolve
+   property accesses on it to the named methods.
+3. `Prop("name")` for view modules behaves like RN's `RCT_EXPORT_VIEW_PROPERTY` —
+   defer with the rest of the view-component frontier.
+
+---
+
+## 4. What edges need to exist
+
+For each channel, the closed flow is:
+
+- **JS callsite → bridged-method-node** (`references`, heuristic, `synthesizedBy:'<channel>'`)
+- **Bridged-method-node → native-impl-method** (already extracted; for #6/#7
+  the bridged-method IS the native impl; for #10 the closure body IS the
+  impl)
+- **Native-impl-method → its own callees** (already extracted in-language)
+
+For Swift↔ObjC specifically, the cleanest model is **alias-name on the
+declaration node**: extend Swift method extraction to compute the ObjC
+auto-bridged name and store it as an alternate name the resolver
+considers. No new edges between Swift and ObjC method nodes are needed
+— normal name resolution suffices because both sides agree on the bridged
+selector after extraction.
+
+The MCP read tools surface heuristic edges inline already
+(see `metadata.synthesizedBy` plumbing from #312/#403); these new edges
+ride that path with no additional plumbing.
+
+---
+
+## 5. Validation corpus (the small/medium/large bar)
+
+Following CLAUDE.md's validation methodology — **≥3 flow prompts each on
+small / medium / large repos, with deterministic probes + agent A/B,
+≥2 runs/arm**. Picks below are candidates to commit to in the
+implementation branch; the implementation PR confirms the choices after
+verifying each repo still builds an index cleanly.
+
+### 5a. Mixed iOS (Swift+ObjC) — pick 3
+
+| Tier | Repo | Why | Canonical flow |
+|---|---|---|---|
+| **Small** | [Charts](https://github.com/danielgindi/Charts) (~150 files Swift+ObjC) | Swift-first lib with ObjC compatibility layer; well-known | "How does setting `data` on a `ChartView` reach the renderer?" |
+| **Small (alt)** | [Lottie-ios](https://github.com/airbnb/lottie-ios) (~300 files, was mixed; current may be pure-Swift — verify) | Animation engine, well-known mix | "How does `AnimationView.play()` reach the layer compositor?" |
+| **Medium** | [Realm-Cocoa](https://github.com/realm/realm-swift) (~500 files) | Heavy Swift-on-top-of-ObjC: Swift API wraps an ObjC core that wraps C++ Realm Core | "How does `Realm.write { realm.add(obj) }` reach the ObjC persistence layer?" |
+| **Large** | [Wikipedia-iOS](https://github.com/wikimedia/wikipedia-ios) (~2500 Swift+ObjC files) | Real app, deeply mixed, active development | "How does tapping a search result reach the article-fetch network call?" |
+| **Large (alt)** | [WordPress-iOS](https://github.com/wordpress-mobile/WordPress-iOS) | Heavier ObjC legacy + Swift additions | "How does a new-post draft save reach Core Data persistence?" |
+
+Bar per repo:
+1. Pure-language probes still pass (Swift-in-Swift trace; ObjC-in-ObjC trace) — no regression vs #165's pure-ObjC baseline.
+2. **Cross-language probe passes:** the canonical flow above traces end-to-end with `trace`, no break at the language boundary.
+3. **Agent A/B (with vs without codegraph, ≥2 runs/arm):** Read = 0 within the explore-call budget; faster than without-codegraph; no regression on a pure-Swift or pure-ObjC control repo (e.g. Texture).
+4. **No node-count explosion** vs pre-bridging baseline (`select count(*) from nodes` before/after).
+
+### 5b. React Native — pick 3
+
+| Tier | Repo | Why | Canonical flow |
+|---|---|---|---|
+| **Small** | [react-native-svg](https://github.com/software-mansion/react-native-svg) (~100 files JS+ObjC+Java) | Small, well-scoped native module set | "How does setting `<Path d=.../>` reach the iOS Core Graphics call?" |
+| **Medium** | [react-native-screens](https://github.com/software-mansion/react-native-screens) (~300 files, JS+native) | Real navigation primitives, both legacy bridge and Fabric | "How does navigating to a new screen reach UINavigationController?" |
+| **Medium (alt)** | [react-native-firebase](https://github.com/invertase/react-native-firebase) (~1000 files across packages) | Many native modules, both platforms — stresses module discovery | "How does `firestore().collection('x').get()` reach the iOS Firebase SDK call?" |
+| **Large** | [facebook/react-native](https://github.com/facebook/react-native) RNTester subset (~3000 files) | The framework itself + sample app; canonical bridge usage | "How does pressing a button in RNTester's GeolocationExample reach the iOS Core Location call?" |
+
+Bar per repo:
+1. Pure-JS probes unchanged (`useState` → re-render flow still resolves — existing react synthesizer not regressed).
+2. **JS → ObjC bridge probe passes** for ≥1 known RCT_EXPORT_METHOD on each repo.
+3. **JS → TurboModule probe passes** on a repo that uses TurboModules (react-native main has both; pick one of each).
+4. **Native → JS event probe passes** for ≥1 emitter (NativeEventEmitter pattern).
+5. **Agent A/B** as above. Critical: a question that *crosses the bridge* (e.g. "how does pressing Button X reach the network call") must drop Read to 0 in ≥1 run with codegraph.
+6. **No regression** on a pure-JS control repo (existing react-realworld / excalidraw measurements unchanged).
+
+### 5c. Expo — pick 2 (smaller scope, narrower API surface)
+
+| Tier | Repo | Why |
+|---|---|---|
+| **Small/Medium** | [expo/expo](https://github.com/expo/expo) — one SDK module like `expo-camera` or `expo-location` | The cleanest Expo Modules API examples; live |
+| **Large** | full `expo/expo` monorepo (all SDK modules + the JS API) | Stress-test module-name resolution across many packages |
+
+Canonical flow: "How does `await Camera.takePictureAsync()` (JS) reach the
+native camera API call (Swift `AVCaptureSession` or Kotlin
+`CameraDevice`)?"
+
+---
+
+## 6. Phasing — what comes first
+
+Per the playbook's difficulty gradient and the half-bridge rule, the order
+is fixed by what closes a flow end-to-end on the **smallest repo first**.
+
+### Phase 1 — Swift ↔ ObjC bridging (rows 1–5 above)
+Smallest scope, deterministic name mapping, no JS involved. Validate on the
+Charts/Realm/Wikipedia corpus before moving on. **Don't proceed to Phase 2
+until Phase 1 passes the §5a bar on all three repos.**
+
+### Phase 2 — React Native legacy bridge (rows 6–7, ObjC + Java/Kotlin)
+Both iOS and Android sides must close in the same PR — half-bridging one
+platform reveals the half-coverage hop on the other and the agent reads.
+Validate on the §5b corpus.
+
+### Phase 3 — Native → JS events (row 9)
+Extends the existing callback synthesizer with a cross-language channel.
+Validate on the same §5b corpus (most RN libs use at least one event emitter).
+
+### Phase 4 — Expo Modules (row 10)
+Layered on Phase 1's Swift extraction. Smaller corpus (§5c).
+
+### Phase 5 — RN TurboModules / Codegen (row 8)
+Requires reading the spec file as cross-language ground truth. Validate on
+the §5b corpus's TurboModule users (react-native main, post-0.73 libs).
+
+### Phase 6 — Fabric view components (row 11)
+Deferred — composes with the existing JSX synthesizer and the view side of
+TurboModules. Address when ≥1 of the §5b corpus repos has its bridge
+otherwise closed but a Fabric flow still breaks.
+
+---
+
+## 7. Anti-goals (what we will not try to do)
+
+- **Android Kotlin/Java extraction quality** — out of scope. We use what
+  Kotlin/Java extractors already produce. If they miss a `@ReactMethod`
+  annotation's literal name we may add a tiny extractor refinement, but we
+  do not redesign JVM extraction.
+- **Dynamic / computed bridge keys** — `NativeModules[someVar]`,
+  `requireNativeModule(name)` where `name` is a parameter, etc. We only
+  resolve literal-key access (matches the
+  [agent-eval Lua frontier](./dynamic-dispatch-coverage-playbook.md) — anonymous-only patterns deferred).
+- **Bridging-header file content parsing** — we *do* index `.h` files
+  (already does via #165's content sniff) but we do **not** parse the
+  bridging header's `#import` list as a special "what's visible to Swift"
+  manifest. Treat it as a normal ObjC header.
+- **Runtime dispatch on `performSelector:`** — out of scope; matches the
+  same "named-only" anti-goal.
+- **JSI (raw, non-TurboModule)** — out of scope. Apps using bare JSI
+  call into native through a custom `Host*` interface that has no documented
+  declarative spec. Wait for those apps to migrate to TurboModules.
+- **Swift-only generics over ObjC protocols / Swift extensions on ObjC
+  classes** — extension methods are still callable in ObjC if `@objc`, so
+  they go through the same Phase 1 path. Generics are not — we silently
+  miss them. Acceptable; matches Java/Kotlin generics frontier.
+
+---
+
+## 8. Coverage-matrix entries — measured
+
+| Language | Framework | Canonical flow | Mechanism | Status |
+|---|---|---|---|---|
+| Swift × Objective-C | bridging | Swift call → ObjC selector; ObjC call → @objc Swift method | R | ✅ Phase 1 (§8a) |
+| JavaScript × Objective-C/Java/Kotlin | React Native legacy bridge | `NativeModules.<M>.<f>` → `RCT_EXPORT_METHOD` / `@ReactMethod` | R | ✅ Phase 2 (§8b) |
+| JavaScript × native | React Native TurboModules | spec interface ↔ impl | R (spec as ground truth) | ✅ partial — name-match path lands (§8b) |
+| Objective-C/Java/Kotlin → JavaScript | React Native event emitters | `[self sendEventWithName:]` → `addListener` | S (cross-lang channel) | ✅ Phase 3 (§8e) |
+| JavaScript × Swift/Kotlin | Expo Modules | `requireNativeModule('X').fn(...)` → `Function("fn") { }` | R (extract synthesizes method nodes) | ✅ Phase 4 (§8f) |
+| JavaScript × native | React Native Fabric views | `<MyView p=v/>` → Codegen spec component + NativeProps | R (extract) + S (native-impl) + JSX | ✅ Phase 6 (§8g) |
+
+### 8a. Phase 1 measurements — Swift ↔ ObjC
+
+| Repo | Source files | Bridge edges (framework-resolved) | Sample edges |
+|---|---|---|---|
+| **Charts** (small) | 269 (205 Swift + 59 ObjC/.h) | 28 objc→swift, 1 swift→objc | `handleOption:forChartView:` → `animate` · `setupPieChartView:` → `setExtraOffsets` · `setDataCount:range:` → `setColor` |
+| **realm-swift** (medium) | 369 (151 Swift + 218 ObjC family) | 36 objc→swift, 1185 swift→objc | `valueForUndefinedKey:` → `get` · `setValue:forUndefinedKey:` → `set` · `promote:on:` → `initialize` |
+| **wikipedia-ios** (large) | 1734 (1234 Swift + 500 ObjC/.h) | 52 objc→swift, 983 swift→objc | real-iOS-app bridging across many feature modules |
+
+All three: in-language baselines unchanged, no node-count explosion,
+`trace` connects canonical flows across the boundary (verified on
+Charts: `trace(handleOption:forChartView:, animate)` surfaces the
+bridge edge directly).
+
+### 8b. Phase 2 + 5 (partial) measurements — React Native bridge
+
+| Repo | Source files | Bridge edges (framework-resolved) | Notes |
+|---|---|---|---|
+| **react-native-svg** (small/medium) | ~700 (93 .mm + 115 .java + 6 .kt + 49 js + 92 ts + 154 tsx) | 9 tsx→java via TurboModule spec | RNSvg's iOS uses TurboModule auto-gen (no `RCT_EXPORT_METHOD`); resolutions land on Java. All 9 precise: `isPointInStroke`, `isPointInFill`, `getTotalLength`, `getPointAtLength`, `getCTM`, `getScreenCTM`, `getBBox`, `toDataURL`. |
+| **AsyncStorage** (small, pure legacy bridge) | ~60 (28 kt + 2 mm + 16 ts + 14 tsx + …) | **8/8 precise** | The canonical legacy bridge test — Kotlin `@ReactMethod` + ObjC `RCT_EXPORT_METHOD`. JS `setItem` → Kotlin `legacy_multiSet`; `getItem` → `legacy_multiGet`; `clear` → `legacy_clear`; etc. |
+| **react-native-firebase** (large) | ~1100 (111 .java + 63 .m + 13 .mm + 239 js + 427 ts + 9 tsx) | 18 after RCTEventEmitter blocklist (was 78 before) | Initial 78 included 60 false positives targeting `addListener:` / `remove:` (every RCTEventEmitter declares them; every JS call to `.addListener(...)` resolved into noise). Blocklist cut to 18, all precise: `httpsCallable:region:emulatorHost:...`, `signInWithProvider`, `configureProvider`, `removeFunctionsStreaming:`. |
+| **react-native-screens** (medium) | 1211 | 0 — empty TurboModule spec, no `RCT_EXPORT_METHOD`, all Fabric/Codegen view-side | RNScreens lives entirely in Phase 6 (Fabric, deferred). The bridge declining to over-match here is the right behavior. |
+
+### 8c. Architectural fix discovered during validation
+
+The resolver's `initialize()` runs at CodeGraph construction — before any
+files are indexed — so framework resolvers whose `detect()` consults
+the indexed file list (UIKit / SwiftUI scanning for imports,
+`swift-objc-bridge` looking for both Swift and ObjC files,
+`react-native-bridge` looking for RN markers) all returned false on that
+initial pass and silently dropped themselves. This affected every
+framework resolver in the codebase that read `context.getAllFiles()` /
+`context.readFile()` rather than scanning the filesystem directly — a
+pre-existing latent bug, not bridge-specific. Fixed: `indexAll()` now
+calls `resolver.initialize()` after extraction completes, so detect()
+runs against the populated index.
+
+### 8d. Bridge-precision blocklists (lessons learned)
+
+| Bridge | Blocked names | Reason |
+|---|---|---|
+| swift-objc | `init`, `description`, `hash`, `isEqual`, `copy`, `count`, `value`, `data`, `string`, `object`, `add`, `remove`, `update`, `load`, `save`, `reload`, `cancel`, `start`, `stop`, `pause`, `resume`, `close`, `open`, `show`, `hide`, `dealloc`, `release`, `retain`, `autorelease`, … | Every NSObject subclass implements these; bridging them to arbitrary project-local ObjC methods produces noise. Regular name-matcher handles them on its own. |
+| react-native | `addListener`, `removeListeners`, `remove`, `invalidate`, `startObserving`, `stopObserving` | Every `RCTEventEmitter` subclass declares these via `RCT_EXPORT_METHOD`. JS callers of `.addListener(...)` / `.remove(...)` go through `NativeEventEmitter` (JS abstraction), not the native bridge directly. |
+
+### 8e. Phase 3 measurements — RN native → JS event channel
+
+Synthesizer pattern; extends `src/resolution/callback-synthesizer.ts` with a
+cross-language event channel keyed by literal event name. Validates on
+**RNFirebase** (large):
+
+| Synthesized event channel | Edges | Sample |
+|---|---|---|
+| `messaging_message_received` | 2 | `application:didReceiveRemoteNotification:fetchCompletionHandler:` → TS `onMessage` (and the `UNUserNotificationCenter` willPresent variant → same `onMessage`) |
+| `messaging_notification_opened` | 1 | `userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:` → TS `onNotificationOpenedApp` |
+
+Each edge is `provenance:'heuristic'`,
+`metadata.synthesizedBy:'rn-event-channel'`. Same `EVENT_FANOUT_CAP = 6`
+as the in-language channel — generic event names with too many handlers
+or dispatchers skip rather than over-link.
+
+The synthesizer also handles the **subscribe-wrapper pattern** common in
+RN libraries (`messaging().onMessage(listener)` where `listener` is a
+parameter that flows up to user code): when the JS handler arg isn't a
+named symbol, it attributes the listener to the ENCLOSING JS function
+(reachability-correct, attributes to the abstraction layer).
+
+### 8f. Phase 4 measurements — Expo Modules
+
+Framework `extract()` parses Swift / Kotlin source for literal
+`Function("X") { … }` / `AsyncFunction("X") { … }` / `Property("X") { … }`
+/ `Constants` declarations inside `class X: Module` (or `: Module()` in
+Kotlin) and emits a `method` node named `X` per literal. The standard
+name-matcher resolves JS callsites like `Foo.takePictureAsync(...)` to
+these synthetic nodes via the existing `obj.method` → method-name path.
+
+Validated on real Expo SDK packages:
+
+| Package | Files indexed | Expo method nodes extracted | Cross-language edges |
+|---|---|---|---|
+| **expo-haptics** | 14 | 6 (3 Swift + 3 Kotlin: `notificationAsync`, `impactAsync`, `selectionAsync` / `performHapticsAsync`) | Module nodes registered; consumer-app callers resolve via name-match |
+| **expo-camera** | 72 | 41 (Swift + Kotlin; covers `takePictureAsync`, `record`, `resumePreview`, `getAvailableLenses`, `scanFromURLAsync`, `requestCameraPermissionsAsync`, view-side `width` / `height` properties, …) | 9 swift→expo, 7 kotlin→expo internal edges. JS-side callsites in the package shadow the native names with TS wrappers (`pausePreview()` defined on `CameraView.tsx`); name-match correctly prefers the local TS method. An external consumer app of `Camera.takePictureAsync()` resolves through to the native method directly. |
+
+Five tests cover the extractor + an end-to-end fixture:
+`JS callsite of literal AsyncFunction("uniqueExpoHapticCall") resolves
+to the native impl node` — confirms the resolver-free bridge path
+works when names aren't shadowed.
+
+### 8g. Phase 6 measurements — Fabric / Codegen view components
+
+Two-part design:
+
+1. **Framework extractor** (`src/resolution/frameworks/fabric.ts`) — parses
+   TS / TSX spec files for `codegenNativeComponent<Props>('Name', ...)`
+   declarations. Emits:
+   - One `component` node per declaration (named after the JS-visible
+     component name; matches the JSX synthesizer's name+kind filter).
+   - One `property` node per declared field of the `NativeProps`
+     interface — surfacing JSX-callable props like `onTap`,
+     `nativeContainerBackgroundColor` as discoverable graph nodes.
+
+2. **Synthesizer** (`fabricNativeImplEdges` in `callback-synthesizer.ts`) —
+   walks every `fabric-component:*` node and looks for a native class
+   matching its name with one of RN's convention suffixes (empty / `View`
+   / `ViewManager` / `ComponentView` / `Manager`). Emits a `calls` edge
+   with `metadata.synthesizedBy:'fabric-native-impl'` from the component
+   to each match. The convention is precise enough that there's no name
+   collision in well-formed RN libraries.
+
+Combined with the existing `reactJsxChildEdges` JSX synthesizer, this
+closes the full JSX → native flow: consumer-app JSX `<MyView prop=v/>`
+→ Fabric `component` node `MyView` → native class `MyViewView`
+(or `MyViewManager` / `MyViewComponentView` / …).
+
+Re-validated on **react-native-screens** (the corpus repo that was
+entirely Fabric and showed 0 bridges in Phase 2):
+
+| Metric | Count |
+|---|---|
+| `codegenNativeComponent` spec declarations | 54 |
+| Fabric component nodes extracted | 27 (one per non-web spec; the `*.web.ts` variants are filtered out by spec validity) |
+| Fabric prop nodes extracted | 272 (the full NativeProps interface surface across all components) |
+| `fabric-native-impl` bridge edges | 68 |
+
+Sample bridge edges:
+
+| JS component | Native class | Suffix |
+|---|---|---|
+| `RNSFullWindowOverlay` | `RNSFullWindowOverlay` (ObjC) | (exact) |
+| `RNSFullWindowOverlay` | `RNSFullWindowOverlayManager` (ObjC) | `Manager` |
+| `RNSModalScreen` | `RNSModalScreenManager` (ObjC) | `Manager` |
+| `RNSScreenContainer` | `RNSScreenContainerView` (ObjC) | `View` |
+
+Four tests cover the extractor + a full end-to-end fixture
+(`App (TSX) → MyView (fabric-component) → MyViewView (ObjC class)`)
+that asserts the JSX→component edge AND the
+component→native-class edge both exist after indexing.
+
+---
+
+## 9. Open questions to settle in Phase 1
+
+These are not blocking the start of Phase 1 — they're the first things to
+decide *while* writing the Swift↔ObjC resolver:
+
+1. **Alias on declaration vs new bridge edge?** Storing the auto-bridged
+   ObjC selector as an alternate name on the Swift method node is cheaper
+   and aligns with how name resolution already works. The alternative
+   (synthesize a cross-language `references` edge between matching nodes)
+   is more explicit in `trace` output but adds N edges per `@objc` symbol.
+   **Default: alias.** Verify the alias surfaces in `callers`/`callees`/`trace`
+   results.
+2. **How does `trace` display a cross-language hop?** The MCP `trace` tool
+   inlines each hop's body. A Swift → ObjC hop should make this obvious in
+   the rendered output ("Swift `func foo(bar:)` → bridged to ObjC selector
+   `-fooWithBar:` → ObjC `-[ImageDownloader fooWithBar:]`"). Will likely
+   need a small renderer tweak in `trace.ts` to label the bridge.
+3. **Where do the resolver bridging rules live?** Suggest a
+   `src/resolution/frameworks/swift-objc.ts` for the auto-name mapping (a
+   pure function) imported by both the Swift extractor (to compute the
+   alias at extract time) and tests. Keeps the mapping in one place.
+4. **What about `@objcMembers`?** Class-level export — applies to all members
+   unless `@nonobjc`. Handle by checking the class's modifiers in the Swift
+   extractor and defaulting each member's `@objc`-ness from that.
+
+---
+
+## 10. Done-bar (so we know when to stop)
+
+Phase 1 (Swift↔ObjC) is done when:
+- All three §5a corpora pass: pure-language probes unchanged; cross-language
+  canonical flow probe finds the path end-to-end; agent A/B shows Read = 0
+  in ≥1 run with codegraph, faster than without.
+- Coverage matrix row in §6 of the playbook is filled in with numbers.
+- A CHANGELOG `[Unreleased]` entry exists, written user-side.
+
+Each subsequent Phase has the same shape — its own §5 corpus, its own
+matrix row, its own CHANGELOG entry — and **doesn't ship until the
+previous one passes**. Half-bridges are not optional to avoid here; they
+actively make codegraph worse on these codebases than not having any
+bridging at all.
diff --git a/docs/design/template-markup-parser.md b/docs/design/template-markup-parser.md
new file mode 100644
index 000000000..e26cea02f
--- /dev/null
+++ b/docs/design/template-markup-parser.md
@@ -0,0 +1,155 @@
+# Scope: Template-markup parser (Razor / Blazor / Thymeleaf)
+
+Status: **P1+P2+@code IMPLEMENTED** (commits 59b8de2 directives/tags, 90c5f39 @code
+delegation) on `feat/cross-language-impact-coverage`. Razor/Blazor markup is parsed
+(`src/extraction/razor-extractor.ts`). Remaining: `@using` namespace disambiguation
+for DTO-vs-entity name collisions (the residual ASP.NET gap), and Thymeleaf/Django
+(P4, deferred — weak code links). Authored 2026-06-04.
+
+## Problem
+
+The impact graph is built from code the engine parses. **Template markup is not
+parsed**, so any code-behind, component, view-model, or DTO that is referenced
+*only* from markup looks like it has no in-repo dependent. On convention-heavy
+frameworks this is the dominant residual gap after framework-entry exclusions:
+
+| Framework | App | FAIR coverage (entries excluded) | Residual cause |
+|---|---|---|---|
+| ASP.NET | eShopOnWeb | **77.2%** (115/149) | Razor `.cshtml` + Blazor `.razor` reference `.cs` we don't parse |
+| Spring | petclinic | 65.2% | mostly Spring Data proxies + JPA, **not** templates (Thymeleaf links are weak) |
+| Django | django-realworld | 74.1% | signals / DRF / string-config, **not** templates |
+
+**This feature is primarily an ASP.NET (Razor + Blazor) win.** Thymeleaf and Django
+templates link to code only weakly (template→template fragments + fuzzy
+model-attribute strings), and those frameworks' real gaps are elsewhere — so they
+are explicitly lower priority here.
+
+### Quantified target (eShopOnWeb, the 34 residual zeros after entry-exclusion)
+
+- **~20 markup-coverable** by this feature:
+  - 5 MVC `ViewModels/*` ← Razor `@model X`
+  - 7 `BlazorShared/Models/*` (DTOs) ← Blazor `@bind` / component params
+  - 6 `BlazorAdmin/*` C# components ← Blazor `<Component/>` tags
+  - 1 `BasketComponent` ViewComponent ← `<vc:basket>` / `Component.InvokeAsync`
+  - 1 Razor page helper
+- **~13 NOT covered** (separate frontier — reflection/proxy + value-reads): AutoMapper
+  `MappingProfile`, Swagger `CustomSchemaFilters`/`ImageValidators`, `ExceptionMiddleware`,
+  health checks, `Constants` (static-member reads), `Buyer` entity.
+
+**Honest ceiling: ASP.NET ~77% → ~90%**, not 95%. The last ~10% is reflection/proxy
+(AutoMapper, Swagger, DI/middleware registration) + C# static-const reads — a
+*separate* feature (reflection modeling + extending the static-member pass to C#).
+
+## Reference patterns to extract (prioritized)
+
+| Pri | Format | Markup construct | Edge to emit | Resolves to |
+|---|---|---|---|---|
+| P1 | Razor `.cshtml`/`.razor` | `@model Foo` / `@inherits X<Foo>` | `references` | the model/VM class `Foo` |
+| P1 | Razor/Blazor | `@inject IBar bar` | `references` | the service type `IBar` |
+| P2 | Blazor `.razor` | `<MyComponent .../>` (PascalCase element) | `references` | component class (`.razor` or `.cs : ComponentBase`) |
+| P2 | Blazor `.razor` | `@typeof(MainLayout)`, `@inherits LayoutBase` | `references` | the type |
+| P3 | Razor `.cshtml` | `<partial name="_X"/>`, `<vc:basket>`, `Component.InvokeAsync("X")` | `references` | the partial view / `XViewComponent` |
+| P3 | Razor `.cshtml` | `asp-page="./Register"`, `asp-controller`/`asp-action` | `references` | the page / controller action |
+| P4 (defer) | Thymeleaf `.html` | `th:replace="~{frag :: x}"` | `references` | template fragment (template→template only) |
+| P4 (defer) | Django `.html` | `{% extends %}` / `{% include %}` / `{% url 'n' %}` | `references` | template / named route |
+
+`asp-for="Prop"`, `th:field="*{prop}"` (property-string bindings) are the data-flow
+frontier — **out of scope** (would need model-type inference; low value, high noise).
+
+## Architecture — follow the existing standalone-extractor pattern
+
+The engine already has non-tree-sitter extractors (`svelte-extractor.ts`,
+`vue-extractor.ts`, `liquid-extractor.ts`): a class taking `(filePath, source)`,
+returning `{ nodes, references }`, wired in two places. Mirror exactly:
+
+1. **`src/extraction/grammars.ts`** — map extensions to a synthetic language:
+   `.cshtml`/`.razor` → `'razor'`, (later) `.html` under `templates/` → `'thymeleaf'`.
+   (Django `.html` is ambiguous with plain HTML — gate on a `templates/` path or a
+   `{% %}`/`{{ }}` content sniff, like the framework resolvers do.)
+2. **`src/extraction/tree-sitter.ts`** — dispatch by extension to a new
+   `RazorExtractor` (and `ThymeleafExtractor`), exactly as `SvelteExtractor` is
+   dispatched (~line 4025).
+3. **`src/extraction/razor-extractor.ts`** (new) — regex/line scan (markup is
+   highly stylized; no grammar needed, same as Liquid/Svelte template scanning):
+   - Emit ONE `component` node for the file (so `.razor` components are linkable as
+     `<X/>` targets and the file is a graph citizen).
+   - Emit `references` per the P1–P3 patterns above, `fromNodeId` = the file/component
+     node, `referenceKind: 'references'`, `language: 'razor'`.
+   - **Code-behind link:** a `Foo.razor` + `Foo.razor.cs` (partial class) — emit a
+     `references` (or rely on same-basename) so the markup's refs also credit the
+     code-behind. (eShop's Blazor components are plain `.cs : ComponentBase`, named
+     `<ToastComponent/>` → resolves by class name; the `.razor.cs` partial case is
+     the other shape.)
+
+**Resolution: no new resolver needed.** The emitted refs are ordinary `references`
+to a class/component by name; the existing name-matcher resolves them (`@model
+RegisterModel` → class `RegisterModel`; `<ToastComponent/>` → class `ToastComponent`).
+Apply the **same cross-family language gate** already in place — a `razor` ref must
+resolve to a `csharp` symbol, so add `razor` to the `web`/dotnet family or treat
+`razor`↔`csharp` as same-family (otherwise the gate from commit 082353e drops it).
+**This is the one resolver-side change** and must be done or every edge is gated away.
+
+## Node/edge shape & invariants
+
+- +1 `component` node per template file (real new symbol — like `.svelte`/`.vue`).
+  Node count grows by the template-file count only; **no per-tag node explosion**
+  (component tags become `references` edges, not nodes).
+- All edges are `references` (counted by impact / `affected` / `getFileDependents`,
+  not by `callers`/`callees` — matches how `route`/`component` edges already behave).
+- Idempotent re-index; node count stable across re-runs.
+
+## Phasing
+
+- **P1 (highest value/effort ratio):** Razor `@model` + `@inject` for `.cshtml` AND
+  `.razor`. Covers the 5 ViewModels + injected services. + the resolver family-gate fix.
+- **P2:** Blazor `<PascalComponent/>` tags + `@typeof`/`@inherits` + code-behind link.
+  Covers the 6 Blazor `.cs` components + the 7 DTOs (via component params/`@bind`).
+- **P3:** Razor `<partial>` / `<vc:>` / `Component.InvokeAsync` / `asp-page`.
+- **P4 (defer / probably skip):** Thymeleaf + Django templates — weak code links,
+  low coverage payoff; revisit only if a Thymeleaf/Django app is a priority.
+
+## Edge cases & risks
+
+- **PascalCase tag vs HTML element:** only `[A-Z]`-initial tags are Blazor components
+  (HTML is lowercase) — safe discriminator. Skip known framework components
+  (`<Router>`, `<Found>`, `<LayoutView>`, `<RouteView>`, `<CascadingValue>`) via a
+  builtin set, or just let them fail to resolve (no false edge — they're not in-repo).
+- **`_Imports.razor` `@using`:** namespace imports, not code refs — ignore (or emit
+  `imports` to the namespace, low value).
+- **Generic components `<Grid TItem="CatalogItem">`:** capture the type-arg as a
+  `references` to `CatalogItem` (bonus DTO coverage).
+- **Name collisions:** component/model names are usually unique; rely on the
+  name-matcher's existing proximity scoring. Same-named class in another language is
+  blocked by the family gate.
+- **Razor `@{ ... }` C# blocks:** contain real C# (calls, `new`) — P-future; regex
+  scanning the C# inside markup is noisy. Defer (the directives above are the wins).
+- **`.razor` is NOT `.cs`:** must add to `grammars.ts` + the indexer's include globs
+  (verify `.razor`/`.cshtml` aren't in a default-exclude).
+
+## Validation (per the engine's methodology)
+
+1. Build `RazorExtractor`; unit tests in `__tests__/extraction.test.ts` (a `.cshtml`
+   with `@model X` covers `X`; a `.razor` with `<ToastComponent/>` covers it; an HTML
+   `<div>` does NOT create an edge).
+2. Re-measure eShopOnWeb FAIR coverage before/after (`/tmp/faircov.cjs`): target
+   77% → ~90%; **node count stable** (only +template-file component nodes); residual
+   zeros are the reflection/value-read set only.
+3. No regression on a non-.NET control (gin/requests) and on the Razor-free C#
+   repos (cs-mediatr/cs-polly unchanged).
+4. Record in this doc + the coverage handoff.
+
+## Effort
+
+- P1: ~0.5 day (extractor skeleton + `@model`/`@inject` scan + family-gate fix + tests).
+- P2: ~1 day (Blazor tags + code-behind + generic type-args).
+- P3: ~0.5 day. P4 (Thymeleaf/Django): ~1–2 days, low ROI — defer.
+- **Total for the ASP.NET win (P1+P2+P3): ~2 days → ASP.NET ~90%.**
+
+## Non-goals (and what's still needed for 95% on convention apps)
+
+This feature does NOT close: reflection/proxy registration (Spring Data repository
+proxies, AutoMapper profiles, Swagger filters, DI container / middleware), property-
+string data bindings (`asp-for`/`th:field`), or C# static-const value reads
+(`Constants.X`). Convention apps reaching literal 95% additionally need a **reflection/
+DI-registration modeling** pass and **extending the static-member pass to C#/TS** —
+tracked separately. Markup parsing is the single biggest, most self-contained step.
diff --git a/install.ps1 b/install.ps1
new file mode 100644
index 000000000..564a747e1
--- /dev/null
+++ b/install.ps1
@@ -0,0 +1,59 @@
+# CodeGraph standalone installer for Windows (PowerShell).
+#
+# Downloads a self-contained bundle (a vendored Node runtime + the app) from
+# GitHub Releases. No Node.js, no build tools required.
+#
+#   irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
+#
+# Upgrade with `codegraph upgrade` (or just re-run this). To uninstall: remove
+# $env:LOCALAPPDATA\codegraph and drop its \current\bin entry from your user PATH.
+#
+# Environment:
+#   CODEGRAPH_VERSION      release tag to install (default: latest)
+#   CODEGRAPH_INSTALL_DIR  install location (default: %LOCALAPPDATA%\codegraph)
+
+$ErrorActionPreference = 'Stop'
+$repo = 'colbymchenry/codegraph'
+$installDir = if ($env:CODEGRAPH_INSTALL_DIR) { $env:CODEGRAPH_INSTALL_DIR } else { Join-Path $env:LOCALAPPDATA 'codegraph' }
+
+# 1. Detect architecture -> target matching the release archives.
+$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture -eq 'Arm64') { 'arm64' } else { 'x64' }
+$target = "win32-$arch"
+
+# 2. Resolve the version (latest release unless pinned).
+$version = $env:CODEGRAPH_VERSION
+if (-not $version) {
+  $version = (Invoke-RestMethod "https://api.github.com/repos/$repo/releases/latest").tag_name
+}
+if (-not $version) { throw "codegraph: could not resolve latest version; set CODEGRAPH_VERSION." }
+
+# 3. Download + extract the bundle into a stable 'current' dir (overwritten on upgrade).
+$url = "https://github.com/$repo/releases/download/$version/codegraph-$target.zip"
+Write-Host "Installing CodeGraph $version ($target)..."
+$tmp = Join-Path $env:TEMP ("cg-" + [guid]::NewGuid().ToString())
+New-Item -ItemType Directory -Force -Path $tmp | Out-Null
+$zip = Join-Path $tmp 'cg.zip'
+Invoke-WebRequest -Uri $url -OutFile $zip
+
+$dest = Join-Path $installDir 'current'
+if (Test-Path $dest) { Remove-Item -Recurse -Force $dest }
+New-Item -ItemType Directory -Force -Path $dest | Out-Null
+Expand-Archive -Path $zip -DestinationPath $dest -Force
+# Archives contain a top-level codegraph-<target>\ dir; flatten it.
+$inner = Join-Path $dest "codegraph-$target"
+if (Test-Path $inner) {
+  Get-ChildItem -Force $inner | Move-Item -Destination $dest -Force
+  Remove-Item -Recurse -Force $inner
+}
+Remove-Item -Recurse -Force $tmp
+
+# 4. Put the launcher dir on the user's PATH.
+$binDir = Join-Path $dest 'bin'
+$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
+if (($userPath -split ';') -notcontains $binDir) {
+  [Environment]::SetEnvironmentVariable('Path', "$binDir;$userPath", 'User')
+  Write-Host "Added $binDir to your PATH (restart your terminal to pick it up)."
+}
+
+Write-Host "Installed to $dest"
+Write-Host "Run: codegraph --help"
diff --git a/install.sh b/install.sh
new file mode 100755
index 000000000..3e903db81
--- /dev/null
+++ b/install.sh
@@ -0,0 +1,95 @@
+#!/bin/sh
+#
+# CodeGraph standalone installer.
+#
+# Downloads a self-contained bundle (a vendored Node runtime + the app) from
+# GitHub Releases. No Node.js, no build tools, no npm required — ideal for a
+# fresh Linux VPS over SSH.
+#
+#   curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
+#
+# Upgrade:   run `codegraph upgrade` (or just re-run the same command).
+# Uninstall: curl -fsSL .../install.sh | sh -s -- --uninstall
+#
+# Environment:
+#   CODEGRAPH_VERSION      release tag to install (default: latest)
+#   CODEGRAPH_INSTALL_DIR  bundle location   (default: ~/.codegraph)
+#   CODEGRAPH_BIN_DIR      symlink location  (default: ~/.local/bin)
+set -eu
+
+REPO="colbymchenry/codegraph"
+INSTALL_DIR="${CODEGRAPH_INSTALL_DIR:-$HOME/.codegraph}"
+BIN_DIR="${CODEGRAPH_BIN_DIR:-$HOME/.local/bin}"
+
+if [ "${1:-}" = "--uninstall" ]; then
+  rm -f "$BIN_DIR/codegraph"
+  rm -rf "$INSTALL_DIR"
+  echo "CodeGraph uninstalled (removed $INSTALL_DIR and $BIN_DIR/codegraph)."
+  exit 0
+fi
+
+# 1. Detect platform → target triple matching the release archives.
+os="$(uname -s)"
+arch="$(uname -m)"
+case "$os" in
+  Darwin) os="darwin" ;;
+  Linux)  os="linux" ;;
+  *) echo "codegraph: unsupported OS '$os'." >&2; exit 1 ;;
+esac
+case "$arch" in
+  arm64|aarch64) arch="arm64" ;;
+  x86_64|amd64)  arch="x64" ;;
+  *) echo "codegraph: unsupported architecture '$arch'." >&2; exit 1 ;;
+esac
+target="${os}-${arch}"
+
+# 2. Resolve the version (latest release unless pinned).
+#
+# Resolve "latest" from the releases/latest *web* redirect, not the GitHub API:
+# the unauthenticated API is rate-limited to 60 requests/hour per IP and returns
+# 403 once exhausted — routine on shared/cloud hosts and CI (issue #325). The
+# redirect (github.com/<repo>/releases/latest -> .../releases/tag/vX.Y.Z) has no
+# such limit. Fall back to the API if the redirect can't be read.
+version="${CODEGRAPH_VERSION:-}"
+if [ -z "$version" ]; then
+  version="$(curl -fsSLI -o /dev/null -w '%{url_effective}' "https://github.com/$REPO/releases/latest" \
+    | sed -n 's#.*/releases/tag/##p')"
+fi
+if [ -z "$version" ]; then
+  version="$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" \
+    | sed -n 's/.*"tag_name": *"\([^"]*\)".*/\1/p' | head -n1)"
+fi
+[ -n "$version" ] || { echo "codegraph: could not resolve latest version; set CODEGRAPH_VERSION (e.g. CODEGRAPH_VERSION=v0.9.4)." >&2; exit 1; }
+# Release tags are vX.Y.Z; accept a bare X.Y.Z in CODEGRAPH_VERSION too.
+case "$version" in v*) ;; *) version="v$version" ;; esac
+
+# 3. Download + extract the bundle.
+url="https://github.com/$REPO/releases/download/$version/codegraph-${target}.tar.gz"
+echo "Installing CodeGraph $version ($target)..."
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+curl -fsSL "$url" -o "$tmp/cg.tar.gz" || { echo "codegraph: download failed: $url" >&2; exit 1; }
+
+dest="$INSTALL_DIR/versions/$version"
+rm -rf "$dest"
+mkdir -p "$dest"
+# Archives contain a top-level codegraph-<target>/ dir; strip it.
+tar -xzf "$tmp/cg.tar.gz" -C "$dest" --strip-components=1
+
+# 4. Symlink the launcher onto PATH and mark the current version.
+mkdir -p "$BIN_DIR"
+ln -sf "$dest/bin/codegraph" "$BIN_DIR/codegraph"
+ln -sfn "$dest" "$INSTALL_DIR/current"
+
+echo "Installed to $dest"
+echo "Linked     $BIN_DIR/codegraph"
+case ":$PATH:" in
+  *":$BIN_DIR:"*) ;;
+  *)
+    echo ""
+    echo "$BIN_DIR is not on your PATH. Add it:"
+    echo "  export PATH=\"$BIN_DIR:\$PATH\""
+    ;;
+esac
+echo ""
+echo "Done. Run: codegraph --help"
diff --git a/package-lock.json b/package-lock.json
index 44e4c829d..031b3f463 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,20 +1,20 @@
 {
   "name": "@colbymchenry/codegraph",
-  "version": "0.8.0",
+  "version": "0.9.9",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@colbymchenry/codegraph",
-      "version": "0.8.0",
+      "version": "0.9.9",
       "license": "MIT",
       "dependencies": {
         "@clack/prompts": "^1.3.0",
         "commander": "^14.0.2",
         "fast-string-width": "^3.0.2",
         "fast-wrap-ansi": "^0.2.0",
+        "ignore": "^7.0.5",
         "jsonc-parser": "^3.3.1",
-        "node-sqlite3-wasm": "^0.8.30",
         "picomatch": "^4.0.3",
         "sisteransi": "^1.0.5",
         "tree-sitter-wasms": "^0.1.11",
@@ -32,9 +32,6 @@
       },
       "engines": {
         "node": ">=20.0.0 <25.0.0"
-      },
-      "optionalDependencies": {
-        "better-sqlite3": "^12.4.1"
       }
     },
     "node_modules/@clack/core": {
@@ -970,89 +967,6 @@
         "node": ">=12"
       }
     },
-    "node_modules/base64-js": {
-      "version": "1.5.1",
-      "resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
-      "integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/feross"
-        },
-        {
-          "type": "patreon",
-          "url": "https://www.patreon.com/feross"
-        },
-        {
-          "type": "consulting",
-          "url": "https://feross.org/support"
-        }
-      ],
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/better-sqlite3": {
-      "version": "12.10.0",
-      "resolved": "https://registry.npmjs.org/better-sqlite3/-/better-sqlite3-12.10.0.tgz",
-      "integrity": "sha512-CyzaZRQKyHkB2ZInfTTl2nvT33EbDpjkLEbE8/Zck3Ll6O0qqvuGdrJ45HgtH+HykRg88ITY3AdreBGN70aBSQ==",
-      "hasInstallScript": true,
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "bindings": "^1.5.0",
-        "prebuild-install": "^7.1.1"
-      },
-      "engines": {
-        "node": "20.x || 22.x || 23.x || 24.x || 25.x || 26.x"
-      }
-    },
-    "node_modules/bindings": {
-      "version": "1.5.0",
-      "resolved": "https://registry.npmjs.org/bindings/-/bindings-1.5.0.tgz",
-      "integrity": "sha512-p2q/t/mhvuOj/UeLlV6566GD/guowlr0hHxClI0W9m7MWYkL1F0hLo+0Aexs9HSPCtR1SXQ0TD3MMKrXZajbiQ==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "file-uri-to-path": "1.0.0"
-      }
-    },
-    "node_modules/bl": {
-      "version": "4.1.0",
-      "resolved": "https://registry.npmjs.org/bl/-/bl-4.1.0.tgz",
-      "integrity": "sha512-1W07cM9gS6DcLperZfFSj+bWLtaPGSOHWhPiGzXmvVJbRLdG82sH/Kn8EtW1VqWVA54AKf2h5k5BbnIbwF3h6w==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "buffer": "^5.5.0",
-        "inherits": "^2.0.4",
-        "readable-stream": "^3.4.0"
-      }
-    },
-    "node_modules/buffer": {
-      "version": "5.7.1",
-      "resolved": "https://registry.npmjs.org/buffer/-/buffer-5.7.1.tgz",
-      "integrity": "sha512-EHcyIPBQ4BSGlvjB16k5KgAJ27CIsHY/2JBmCRReo48y9rQ3MaUzWX3KVlBa4U7MyX02HdVj0K7C3WaB3ju7FQ==",
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/feross"
-        },
-        {
-          "type": "patreon",
-          "url": "https://www.patreon.com/feross"
-        },
-        {
-          "type": "consulting",
-          "url": "https://feross.org/support"
-        }
-      ],
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "base64-js": "^1.3.1",
-        "ieee754": "^1.1.13"
-      }
-    },
     "node_modules/cac": {
       "version": "6.7.14",
       "resolved": "https://registry.npmjs.org/cac/-/cac-6.7.14.tgz",
@@ -1090,13 +1004,6 @@
         "node": ">= 16"
       }
     },
-    "node_modules/chownr": {
-      "version": "1.1.4",
-      "resolved": "https://registry.npmjs.org/chownr/-/chownr-1.1.4.tgz",
-      "integrity": "sha512-jJ0bqzaylmJtVnNgzTeSOs8DPavpbYgEr/b0YL8/2GO3xJEhInFmhKMUnEJQjZumK7KXGFhUy89PrsJWlakBVg==",
-      "license": "ISC",
-      "optional": true
-    },
     "node_modules/commander": {
       "version": "14.0.3",
       "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz",
@@ -1124,22 +1031,6 @@
         }
       }
     },
-    "node_modules/decompress-response": {
-      "version": "6.0.0",
-      "resolved": "https://registry.npmjs.org/decompress-response/-/decompress-response-6.0.0.tgz",
-      "integrity": "sha512-aW35yZM6Bb/4oJlZncMH2LCoZtJXTRxES17vE3hoRiowU2kWHaJKFkSBDnDR+cm9J+9QhXmREyIfv0pji9ejCQ==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "mimic-response": "^3.1.0"
-      },
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
     "node_modules/deep-eql": {
       "version": "5.0.2",
       "resolved": "https://registry.npmjs.org/deep-eql/-/deep-eql-5.0.2.tgz",
@@ -1150,36 +1041,6 @@
         "node": ">=6"
       }
     },
-    "node_modules/deep-extend": {
-      "version": "0.6.0",
-      "resolved": "https://registry.npmjs.org/deep-extend/-/deep-extend-0.6.0.tgz",
-      "integrity": "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">=4.0.0"
-      }
-    },
-    "node_modules/detect-libc": {
-      "version": "2.1.2",
-      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
-      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
-      "license": "Apache-2.0",
-      "optional": true,
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "node_modules/end-of-stream": {
-      "version": "1.4.5",
-      "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.5.tgz",
-      "integrity": "sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "once": "^1.4.0"
-      }
-    },
     "node_modules/es-module-lexer": {
       "version": "1.7.0",
       "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-1.7.0.tgz",
@@ -1236,16 +1097,6 @@
         "@types/estree": "^1.0.0"
       }
     },
-    "node_modules/expand-template": {
-      "version": "2.0.3",
-      "resolved": "https://registry.npmjs.org/expand-template/-/expand-template-2.0.3.tgz",
-      "integrity": "sha512-XYfuKMvj4O35f/pOXLObndIRvyQ+/+6AhODh+OKWj9S9498pHHn/IMszH+gt0fBCRWMNfk1ZSp5x3AifmnI2vg==",
-      "license": "(MIT OR WTFPL)",
-      "optional": true,
-      "engines": {
-        "node": ">=6"
-      }
-    },
     "node_modules/expect-type": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
@@ -1280,20 +1131,6 @@
         "fast-string-width": "^3.0.2"
       }
     },
-    "node_modules/file-uri-to-path": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/file-uri-to-path/-/file-uri-to-path-1.0.0.tgz",
-      "integrity": "sha512-0Zt+s3L7Vf1biwWZ29aARiVYLx7iMGnEUl9x33fbB/j3jR81u/O2LbqK+Bm1CDSNDKVtJ/YjwY7TUd5SkeLQLw==",
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/fs-constants": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/fs-constants/-/fs-constants-1.0.0.tgz",
-      "integrity": "sha512-y6OAwoSIf7FyjMIv94u+b5rdheZEjzR63GTyZJm5qh4Bi+2YgwLCcI/fPFZkL5PSixOt6ZNKm+w+Hfp/Bciwow==",
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/fsevents": {
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
@@ -1309,47 +1146,14 @@
         "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
       }
     },
-    "node_modules/github-from-package": {
-      "version": "0.0.0",
-      "resolved": "https://registry.npmjs.org/github-from-package/-/github-from-package-0.0.0.tgz",
-      "integrity": "sha512-SyHy3T1v2NUXn29OsWdxmK6RwHD+vkj3v8en8AOBZ1wBQ/hCAQ5bAQTD02kW4W9tUp/3Qh6J8r9EvntiyCmOOw==",
+    "node_modules/ignore": {
+      "version": "7.0.5",
+      "resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.5.tgz",
+      "integrity": "sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==",
       "license": "MIT",
-      "optional": true
-    },
-    "node_modules/ieee754": {
-      "version": "1.2.1",
-      "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
-      "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==",
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/feross"
-        },
-        {
-          "type": "patreon",
-          "url": "https://www.patreon.com/feross"
-        },
-        {
-          "type": "consulting",
-          "url": "https://feross.org/support"
-        }
-      ],
-      "license": "BSD-3-Clause",
-      "optional": true
-    },
-    "node_modules/inherits": {
-      "version": "2.0.4",
-      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
-      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
-      "license": "ISC",
-      "optional": true
-    },
-    "node_modules/ini": {
-      "version": "1.3.8",
-      "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz",
-      "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==",
-      "license": "ISC",
-      "optional": true
+      "engines": {
+        "node": ">= 4"
+      }
     },
     "node_modules/jsonc-parser": {
       "version": "3.3.1",
@@ -1374,36 +1178,6 @@
         "@jridgewell/sourcemap-codec": "^1.5.5"
       }
     },
-    "node_modules/mimic-response": {
-      "version": "3.1.0",
-      "resolved": "https://registry.npmjs.org/mimic-response/-/mimic-response-3.1.0.tgz",
-      "integrity": "sha512-z0yWI+4FDrrweS8Zmt4Ej5HdJmky15+L2e6Wgn3+iK5fWzb6T3fhNFq2+MeTRb064c6Wr4N/wv0DzQTjNzHNGQ==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/sindresorhus"
-      }
-    },
-    "node_modules/minimist": {
-      "version": "1.2.8",
-      "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
-      "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
-      "license": "MIT",
-      "optional": true,
-      "funding": {
-        "url": "https://github.com/sponsors/ljharb"
-      }
-    },
-    "node_modules/mkdirp-classic": {
-      "version": "0.5.3",
-      "resolved": "https://registry.npmjs.org/mkdirp-classic/-/mkdirp-classic-0.5.3.tgz",
-      "integrity": "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A==",
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/ms": {
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -1430,42 +1204,6 @@
         "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
       }
     },
-    "node_modules/napi-build-utils": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/napi-build-utils/-/napi-build-utils-2.0.0.tgz",
-      "integrity": "sha512-GEbrYkbfF7MoNaoh2iGG84Mnf/WZfB0GdGEsM8wz7Expx/LlWf5U8t9nvJKXSp3qr5IsEbK04cBGhol/KwOsWA==",
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/node-abi": {
-      "version": "3.87.0",
-      "resolved": "https://registry.npmjs.org/node-abi/-/node-abi-3.87.0.tgz",
-      "integrity": "sha512-+CGM1L1CgmtheLcBuleyYOn7NWPVu0s0EJH2C4puxgEZb9h8QpR9G2dBfZJOAUhi7VQxuBPMd0hiISWcTyiYyQ==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "semver": "^7.3.5"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/node-sqlite3-wasm": {
-      "version": "0.8.53",
-      "resolved": "https://registry.npmjs.org/node-sqlite3-wasm/-/node-sqlite3-wasm-0.8.53.tgz",
-      "integrity": "sha512-HPuGOPj3L+h3WSf0XikIXTDpsRxlVmzBC3RMgqi3yDg9CEbm/4Hw3rrDodeITqITjm07X4atWLlDMMI8KERMiQ==",
-      "license": "MIT"
-    },
-    "node_modules/once": {
-      "version": "1.4.0",
-      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
-      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
-      "license": "ISC",
-      "optional": true,
-      "dependencies": {
-        "wrappy": "1"
-      }
-    },
     "node_modules/pathe": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/pathe/-/pathe-1.1.2.tgz",
@@ -1531,75 +1269,6 @@
         "node": "^10 || ^12 || >=14"
       }
     },
-    "node_modules/prebuild-install": {
-      "version": "7.1.3",
-      "resolved": "https://registry.npmjs.org/prebuild-install/-/prebuild-install-7.1.3.tgz",
-      "integrity": "sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "detect-libc": "^2.0.0",
-        "expand-template": "^2.0.3",
-        "github-from-package": "0.0.0",
-        "minimist": "^1.2.3",
-        "mkdirp-classic": "^0.5.3",
-        "napi-build-utils": "^2.0.0",
-        "node-abi": "^3.3.0",
-        "pump": "^3.0.0",
-        "rc": "^1.2.7",
-        "simple-get": "^4.0.0",
-        "tar-fs": "^2.0.0",
-        "tunnel-agent": "^0.6.0"
-      },
-      "bin": {
-        "prebuild-install": "bin.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
-    "node_modules/pump": {
-      "version": "3.0.3",
-      "resolved": "https://registry.npmjs.org/pump/-/pump-3.0.3.tgz",
-      "integrity": "sha512-todwxLMY7/heScKmntwQG8CXVkWUOdYxIvY2s0VWAAMh/nd8SoYiRaKjlr7+iCs984f2P8zvrfWcDDYVb73NfA==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "end-of-stream": "^1.1.0",
-        "once": "^1.3.1"
-      }
-    },
-    "node_modules/rc": {
-      "version": "1.2.8",
-      "resolved": "https://registry.npmjs.org/rc/-/rc-1.2.8.tgz",
-      "integrity": "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw==",
-      "license": "(BSD-2-Clause OR MIT OR Apache-2.0)",
-      "optional": true,
-      "dependencies": {
-        "deep-extend": "^0.6.0",
-        "ini": "~1.3.0",
-        "minimist": "^1.2.0",
-        "strip-json-comments": "~2.0.1"
-      },
-      "bin": {
-        "rc": "cli.js"
-      }
-    },
-    "node_modules/readable-stream": {
-      "version": "3.6.2",
-      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz",
-      "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "inherits": "^2.0.3",
-        "string_decoder": "^1.1.1",
-        "util-deprecate": "^1.0.1"
-      },
-      "engines": {
-        "node": ">= 6"
-      }
-    },
     "node_modules/rollup": {
       "version": "4.57.1",
       "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.57.1.tgz",
@@ -1645,40 +1314,6 @@
         "fsevents": "~2.3.2"
       }
     },
-    "node_modules/safe-buffer": {
-      "version": "5.2.1",
-      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
-      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/feross"
-        },
-        {
-          "type": "patreon",
-          "url": "https://www.patreon.com/feross"
-        },
-        {
-          "type": "consulting",
-          "url": "https://feross.org/support"
-        }
-      ],
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/semver": {
-      "version": "7.7.4",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
-      "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
-      "license": "ISC",
-      "optional": true,
-      "bin": {
-        "semver": "bin/semver.js"
-      },
-      "engines": {
-        "node": ">=10"
-      }
-    },
     "node_modules/siginfo": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
@@ -1686,53 +1321,6 @@
       "dev": true,
       "license": "ISC"
     },
-    "node_modules/simple-concat": {
-      "version": "1.0.1",
-      "resolved": "https://registry.npmjs.org/simple-concat/-/simple-concat-1.0.1.tgz",
-      "integrity": "sha512-cSFtAPtRhljv69IK0hTVZQ+OfE9nePi/rtJmw5UjHeVyVroEqJXP1sFztKUy1qU+xvz3u/sfYJLa947b7nAN2Q==",
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/feross"
-        },
-        {
-          "type": "patreon",
-          "url": "https://www.patreon.com/feross"
-        },
-        {
-          "type": "consulting",
-          "url": "https://feross.org/support"
-        }
-      ],
-      "license": "MIT",
-      "optional": true
-    },
-    "node_modules/simple-get": {
-      "version": "4.0.1",
-      "resolved": "https://registry.npmjs.org/simple-get/-/simple-get-4.0.1.tgz",
-      "integrity": "sha512-brv7p5WgH0jmQJr1ZDDfKDOSeWWg+OVypG99A/5vYGPqJ6pxiaHLy8nxtFjBA7oMa01ebA9gfh1uMCFqOuXxvA==",
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/feross"
-        },
-        {
-          "type": "patreon",
-          "url": "https://www.patreon.com/feross"
-        },
-        {
-          "type": "consulting",
-          "url": "https://feross.org/support"
-        }
-      ],
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "decompress-response": "^6.0.0",
-        "once": "^1.3.1",
-        "simple-concat": "^1.0.0"
-      }
-    },
     "node_modules/sisteransi": {
       "version": "1.0.5",
       "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz",
@@ -1763,56 +1351,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/string_decoder": {
-      "version": "1.3.0",
-      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.3.0.tgz",
-      "integrity": "sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "safe-buffer": "~5.2.0"
-      }
-    },
-    "node_modules/strip-json-comments": {
-      "version": "2.0.1",
-      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz",
-      "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==",
-      "license": "MIT",
-      "optional": true,
-      "engines": {
-        "node": ">=0.10.0"
-      }
-    },
-    "node_modules/tar-fs": {
-      "version": "2.1.4",
-      "resolved": "https://registry.npmjs.org/tar-fs/-/tar-fs-2.1.4.tgz",
-      "integrity": "sha512-mDAjwmZdh7LTT6pNleZ05Yt65HC3E+NiQzl672vQG38jIrehtJk/J3mNwIg+vShQPcLF/LV7CMnDW6vjj6sfYQ==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "chownr": "^1.1.1",
-        "mkdirp-classic": "^0.5.2",
-        "pump": "^3.0.0",
-        "tar-stream": "^2.1.4"
-      }
-    },
-    "node_modules/tar-stream": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-2.2.0.tgz",
-      "integrity": "sha512-ujeqbceABgwMZxEJnk2HDY2DlnUZ+9oEcb1KzTVfYHio0UE6dG71n60d8D2I4qNvleWrrXpmjpt7vZeF1LnMZQ==",
-      "license": "MIT",
-      "optional": true,
-      "dependencies": {
-        "bl": "^4.0.3",
-        "end-of-stream": "^1.4.1",
-        "fs-constants": "^1.0.0",
-        "inherits": "^2.0.3",
-        "readable-stream": "^3.1.1"
-      },
-      "engines": {
-        "node": ">=6"
-      }
-    },
     "node_modules/tinybench": {
       "version": "2.9.0",
       "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
@@ -1866,19 +1404,6 @@
         "tree-sitter-wasms": "^0.1.11"
       }
     },
-    "node_modules/tunnel-agent": {
-      "version": "0.6.0",
-      "resolved": "https://registry.npmjs.org/tunnel-agent/-/tunnel-agent-0.6.0.tgz",
-      "integrity": "sha512-McnNiV1l8RYeY8tBgEpuodCC1mLUdbSN+CYBL7kJsJNInOP8UjDDEwdk6Mw60vdLLrr5NHKZhMAOSrR2NZuQ+w==",
-      "license": "Apache-2.0",
-      "optional": true,
-      "dependencies": {
-        "safe-buffer": "^5.0.1"
-      },
-      "engines": {
-        "node": "*"
-      }
-    },
     "node_modules/typescript": {
       "version": "5.9.3",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
@@ -1900,13 +1425,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/util-deprecate": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
-      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
-      "license": "MIT",
-      "optional": true
-    },
     "node_modules/vite": {
       "version": "5.4.21",
       "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.21.tgz",
@@ -2087,13 +1605,6 @@
       "engines": {
         "node": ">=8"
       }
-    },
-    "node_modules/wrappy": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
-      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
-      "license": "ISC",
-      "optional": true
     }
   }
 }
diff --git a/package.json b/package.json
index 58f9f0ab6..c1ef34d36 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@colbymchenry/codegraph",
-  "version": "0.8.0",
+  "version": "0.9.9",
   "description": "Supercharge Claude Code with semantic code intelligence. 94% fewer tool calls • 77% faster exploration • 100% local.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,8 +36,8 @@
     "commander": "^14.0.2",
     "fast-string-width": "^3.0.2",
     "fast-wrap-ansi": "^0.2.0",
+    "ignore": "^7.0.5",
     "jsonc-parser": "^3.3.1",
-    "node-sqlite3-wasm": "^0.8.30",
     "picomatch": "^4.0.3",
     "sisteransi": "^1.0.5",
     "tree-sitter-wasms": "^0.1.11",
@@ -50,9 +50,6 @@
     "typescript": "^5.0.0",
     "vitest": "^2.1.9"
   },
-  "optionalDependencies": {
-    "better-sqlite3": "^12.4.1"
-  },
   "engines": {
     "node": ">=20.0.0 <25.0.0"
   }
diff --git a/scripts/agent-eval/ab-adoption.sh b/scripts/agent-eval/ab-adoption.sh
new file mode 100644
index 000000000..d5c6dc222
--- /dev/null
+++ b/scripts/agent-eval/ab-adoption.sh
@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Does the agent PICK codegraph_node to read a file, vs the built-in Read tool?
+# Build A/B: NEW build (HEAD, codegraph_node has Read parity) vs BASELINE build
+# (a ref where it doesn't), BOTH codegraph-attached + pre-warmed, same task. The
+# metric is tool CHOICE: Read calls vs codegraph_node[file] calls per run.
+#
+# Usage: ab-adoption.sh <indexed-repo> "<task>" [runs-per-arm] [baseline-ref]
+# Env: AGENT_EVAL_OUT (default: /tmp/ab-adoption)
+set -uo pipefail
+TARGET="${1:?usage: ab-adoption.sh <indexed-repo> \"<task>\" [runs] [baseline-ref]}"
+TASK="${2:?task required}"
+RUNS="${3:-2}"
+BASE_REF="${4:-HEAD~1}"
+ENGINE="$(cd "$(dirname "$0")/../.." && pwd)"
+BIN="$ENGINE/dist/bin/codegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/ab-adoption}"
+
+command -v claude >/dev/null || { echo "claude CLI not on PATH"; exit 1; }
+[ -d "$TARGET/.codegraph" ] || { echo "target not indexed: run 'codegraph init $TARGET' first"; exit 1; }
+git -C "$ENGINE" diff --quiet && git -C "$ENGINE" diff --cached --quiet || { echo "engine has uncommitted changes — commit/stash first"; exit 1; }
+CHANGED=$(git -C "$ENGINE" diff --name-only "$BASE_REF" HEAD -- src 2>/dev/null)
+[ -n "$CHANGED" ] || { echo "no src/ changes between $BASE_REF and HEAD"; exit 1; }
+
+cleanup() {
+  pkill -9 -f "serve --mcp --path $OUT/" 2>/dev/null
+  git -C "$ENGINE" checkout HEAD -- $CHANGED 2>/dev/null
+  ( cd "$ENGINE" && npm run build >/dev/null 2>&1 )
+}
+trap cleanup EXIT
+mkdir -p "$OUT"
+echo "###### target=$TARGET  runs/arm=$RUNS  baseline=$BASE_REF"
+echo "###### changed: $(echo "$CHANGED" | tr '\n' ' ')"
+echo "###### task=$TASK"; echo
+
+prewarm() {
+  pkill -9 -f "serve --mcp --path $1" 2>/dev/null
+  CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS=1800000 node "$BIN" serve --mcp --path "$1" </dev/null >/dev/null 2>&1 &
+  node -e 'const fs=require("fs");let n=0;const t=setInterval(()=>{if(fs.existsSync(process.argv[1]+"/.codegraph/daemon.sock")){clearInterval(t);process.exit(0)}if(n++>150){clearInterval(t);process.exit(1)}},100)' "$1" >/dev/null 2>&1
+}
+
+# Per-run tool-choice counts: Read vs codegraph_node[file] vs [symbol].
+count() {
+  node -e '
+    const fs=require("fs");
+    const lines=fs.readFileSync(process.argv[1],"utf8").split("\n").filter(Boolean);
+    let read=0,cgFile=0,cgSym=0,cgOther=0,exposed="?";
+    for(const l of lines){try{const o=JSON.parse(l);
+      if(o.type==="system"&&o.subtype==="init"){exposed=(o.tools||[]).filter(t=>/codegraph/.test(t)).length;}
+      const blocks=o.message?.content||[];
+      for(const b of (Array.isArray(blocks)?blocks:[])){
+        if(b.type!=="tool_use")continue;
+        if(b.name==="Read")read++;
+        else if(b.name==="mcp__codegraph__codegraph_node"){ if(b.input&&b.input.symbol)cgSym++; else cgFile++; }
+        else if(/mcp__codegraph__/.test(b.name))cgOther++;
+      }
+    }catch{}}
+    console.log(`    Read=${read}  codegraph_node[file]=${cgFile}  codegraph_node[symbol]=${cgSym}  other_cg=${cgOther}  (cg exposed=${exposed})`);
+  ' "$1"
+}
+
+run_arm() { # label, N
+  local label="$1" n="$2"
+  local c="$OUT/mcp-$label.json"
+  for i in $(seq 1 "$n"); do
+    local tgt="$OUT/t-$label-$i"
+    rm -rf "$tgt"
+    rsync -a --exclude node_modules --exclude .git --exclude dist --exclude .codegraph "$TARGET/" "$tgt/"
+    node "$BIN" init "$tgt" >/dev/null 2>&1
+    printf '{"mcpServers":{"codegraph":{"command":"env","args":["CODEGRAPH_WASM_RELAUNCHED=1","node","%s","serve","--mcp","--path","%s"]}}}' "$BIN" "$tgt" > "$c"
+    prewarm "$tgt"
+    echo "----- [$label] run $i -----"
+    ( cd "$tgt" && claude -p "$TASK" \
+        --output-format stream-json --verbose --permission-mode bypassPermissions \
+        --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" --max-budget-usd 4 --strict-mcp-config --mcp-config "$c" \
+        </dev/null > "$OUT/run-$label-$i.jsonl" 2>"$OUT/run-$label-$i.err" )
+    count "$OUT/run-$label-$i.jsonl"
+    pkill -9 -f "serve --mcp --path $tgt" 2>/dev/null
+  done
+  echo
+}
+
+echo "== NEW build (HEAD: codegraph_node has Read parity) =="
+( cd "$ENGINE" && npm run build >/dev/null 2>&1 ) && echo "built"
+run_arm new "$RUNS"
+
+echo "== BASELINE build ($BASE_REF) =="
+git -C "$ENGINE" checkout "$BASE_REF" -- $CHANGED
+( cd "$ENGINE" && npm run build >/dev/null 2>&1 ) && echo "built"
+run_arm baseline "$RUNS"
+
+echo "###### DONE — compare [new] vs [baseline]: does codegraph_node[file] rise / Read fall? Logs: $OUT"
diff --git a/scripts/agent-eval/ab-hook.sh b/scripts/agent-eval/ab-hook.sh
new file mode 100644
index 000000000..0e46fccbd
--- /dev/null
+++ b/scripts/agent-eval/ab-hook.sh
@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# A/B the PreToolUse(Read) REDIRECT hook (P1): does steering Read → codegraph_node
+# file-view actually move the agent off Read during implementation? BOTH arms use
+# the CURRENT build with codegraph attached and pre-warmed; the only difference is
+# the hook. Isolates the hook's behavioral effect from the build/file-view change
+# (use ab-new-vs-baseline.sh for the build A/B).
+#
+#   arm [nohook] — codegraph on, no hook   (does the better file-view get picked on its own?)
+#   arm [hook]   — codegraph on, + redirect hook   (does routing close it?)
+#
+# Reliable attach (works nested): each arm pre-warms a persistent daemon and skips
+# the startup re-exec (CODEGRAPH_WASM_RELAUNCHED=1), so claude connects before the
+# agent's first turn. Judge by ACTUAL codegraph usage in parse-run.mjs's "by type",
+# not claude's init snapshot (which can read pending even when it then connects).
+#
+# Usage: ab-hook.sh <indexed-repo> "<implementation task>" [runs-per-arm]
+#   <indexed-repo>  a repo with a .codegraph index (copied per arm; never mutated)
+#   "<task>"        a GENUINELY-NEW implementation task (verify it isn't already done)
+#   [runs-per-arm]  default 2 (n=1 is noisy — the doctrine says >=2)
+# Env: AGENT_EVAL_OUT (default: /tmp/ab-hook)
+set -uo pipefail
+
+TARGET="${1:?usage: ab-hook.sh <indexed-repo> \"<task>\" [runs-per-arm]}"
+TASK="${2:?task required}"
+RUNS="${3:-2}"
+ENGINE="$(cd "$(dirname "$0")/../.." && pwd)"
+BIN="$ENGINE/dist/bin/codegraph.js"
+HOOK="$ENGINE/scripts/agent-eval/redirect-read-hook.sh"
+OUT="${AGENT_EVAL_OUT:-/tmp/ab-hook}"
+PARSE="$ENGINE/scripts/agent-eval/parse-run.mjs"
+
+command -v claude >/dev/null || { echo "claude CLI not on PATH"; exit 1; }
+command -v jq >/dev/null || { echo "jq not on PATH (the hook needs it)"; exit 1; }
+[ -d "$TARGET/.codegraph" ] || { echo "target not indexed: run 'codegraph init $TARGET' first"; exit 1; }
+chmod +x "$HOOK"
+
+cleanup() { pkill -9 -f "serve --mcp --path $OUT/" 2>/dev/null; }
+trap cleanup EXIT
+
+mkdir -p "$OUT"
+echo "###### engine=$ENGINE"
+echo "###### target=$TARGET   runs/arm=$RUNS"
+echo "###### task=$TASK"
+echo
+
+( cd "$ENGINE" && npm run build >/dev/null 2>&1 ) && echo "built"
+
+# A settings file carrying ONLY the PreToolUse(Read) redirect hook.
+HOOK_SETTINGS="$OUT/hook-settings.json"
+jq -n --arg cmd "bash $HOOK" \
+  '{hooks:{PreToolUse:[{matcher:"Read",hooks:[{type:"command",command:$cmd}]}]}}' > "$HOOK_SETTINGS"
+
+prewarm() { # target — spawn a persistent daemon and wait for its socket
+  pkill -9 -f "serve --mcp --path $1" 2>/dev/null
+  CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS=1800000 node "$BIN" serve --mcp --path "$1" </dev/null >/dev/null 2>&1 &
+  node -e 'const fs=require("fs");let n=0;const t=setInterval(()=>{if(fs.existsSync(process.argv[1]+"/.codegraph/daemon.sock")){clearInterval(t);process.exit(0)}if(n++>150){clearInterval(t);process.exit(1)}},100)' "$1" \
+    && echo "  daemon warm: $1" || echo "  WARN: daemon never bound for $1"
+}
+
+run_one() { # arm-label, run-index, use-hook(0|1)
+  local label="$1" idx="$2" hook="$3"
+  local tgt="$OUT/t-$label-$idx" c="$OUT/mcp-$label.json"
+  rm -rf "$tgt"
+  rsync -a --exclude node_modules --exclude .git --exclude dist --exclude .codegraph "$TARGET/" "$tgt/"
+  node "$BIN" init "$tgt" >/dev/null 2>&1
+  printf '{"mcpServers":{"codegraph":{"command":"env","args":["CODEGRAPH_WASM_RELAUNCHED=1","node","%s","serve","--mcp","--path","%s"]}}}' "$BIN" "$tgt" > "$c"
+  prewarm "$tgt"
+  local extra=()
+  [ "$hook" = "1" ] && extra=(--settings "$HOOK_SETTINGS")
+  echo "----- [$label] run $idx -----"
+  # ${extra[@]+...} guard: bash 3.2 (macOS) under `set -u` errors on an empty
+  # array expansion otherwise, which would skip the no-hook arm's claude run.
+  ( cd "$tgt" && claude -p "$TASK" \
+      --output-format stream-json --verbose --permission-mode bypassPermissions \
+      --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" --max-budget-usd 4 --strict-mcp-config --mcp-config "$c" ${extra[@]+"${extra[@]}"} \
+      </dev/null > "$OUT/run-$label-$idx.jsonl" 2>"$OUT/run-$label-$idx.err" )
+  node "$PARSE" "$OUT/run-$label-$idx.jsonl" 2>&1 | grep -E "by type|Result" || echo "  (parse failed — see $OUT/run-$label-$idx.jsonl)"
+  pkill -9 -f "serve --mcp --path $tgt" 2>/dev/null
+  echo
+}
+
+for i in $(seq 1 "$RUNS"); do run_one nohook "$i" 0; done
+for i in $(seq 1 "$RUNS"); do run_one hook   "$i" 1; done
+
+echo "###### DONE. Compare [nohook] vs [hook] 'by type' — Read should fall and"
+echo "###### mcp__codegraph__codegraph_node should rise in the [hook] arm. Logs: $OUT"
diff --git a/scripts/agent-eval/ab-impl.sh b/scripts/agent-eval/ab-impl.sh
new file mode 100644
index 000000000..b6f219b14
--- /dev/null
+++ b/scripts/agent-eval/ab-impl.sh
@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Sufficiency A/B for an IMPLEMENTATION task (the agent edits): when it uses
+# codegraph (explore/node) to understand before editing, does it still Read? Like
+# ab-sufficiency.sh but copies+indexes a FRESH target per run (the agent mutates
+# it), so runs don't see each other's edits.
+#
+# WITH codegraph (pre-warmed) vs WITHOUT (empty MCP), N runs each. Reports
+# explore/node vs Read/Grep + the files Read, and whether the build still passes.
+#
+# Usage: ab-impl.sh <indexed-repo> "<task>" [runs] [build-cmd]
+# Env: AGENT_EVAL_OUT (default: /tmp/ab-impl)
+set -uo pipefail
+REPO="${1:?usage: ab-impl.sh <indexed-repo> \"<task>\" [runs] [build-cmd]}"
+Q="${2:?task required}"
+RUNS="${3:-2}"
+BUILD_CMD="${4:-}"
+ENGINE="$(cd "$(dirname "$0")/../.." && pwd)"
+BIN="$ENGINE/dist/bin/codegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/ab-impl}"
+command -v claude >/dev/null || { echo "claude CLI not on PATH"; exit 1; }
+[ -d "$REPO/.codegraph" ] || { echo "no .codegraph index at $REPO"; exit 1; }
+cleanup(){ pkill -9 -f "serve --mcp --path $OUT/" 2>/dev/null; }
+trap cleanup EXIT
+mkdir -p "$OUT"
+( cd "$ENGINE" && npm run build >/dev/null 2>&1 ) && echo "built engine"
+echo "###### repo=$REPO  runs/arm=$RUNS"
+echo "###### task=$Q"; echo
+echo '{"mcpServers":{}}' > "$OUT/mcp-empty.json"
+
+prewarm(){
+  pkill -9 -f "serve --mcp --path $1" 2>/dev/null
+  CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS=1800000 node "$BIN" serve --mcp --path "$1" </dev/null >/dev/null 2>&1 &
+  node -e 'const fs=require("fs");let n=0;const t=setInterval(()=>{if(fs.existsSync(process.argv[1]+"/.codegraph/daemon.sock")){clearInterval(t);process.exit(0)}if(n++>150){clearInterval(t);process.exit(1)}},100)' "$1" >/dev/null 2>&1
+}
+
+analyze(){
+  node -e '
+    const fs=require("fs");
+    const L=fs.readFileSync(process.argv[1],"utf8").split("\n").filter(Boolean);
+    let ex=0,nf=0,ns=0,oc=0,gr=0,ed=0,exposed="?";const reads=[];
+    for(const l of L){try{const o=JSON.parse(l);
+      if(o.type==="system"&&o.subtype==="init")exposed=(o.tools||[]).filter(t=>/codegraph/.test(t)).length;
+      for(const b of (o.message?.content||[])){if(b.type!=="tool_use")continue;
+        if(b.name==="mcp__codegraph__codegraph_explore")ex++;
+        else if(b.name==="mcp__codegraph__codegraph_node"){if(b.input&&b.input.symbol)ns++;else nf++;}
+        else if(/mcp__codegraph__/.test(b.name))oc++;
+        else if(b.name==="Read")reads.push((b.input?.file_path||"").split("/").pop());
+        else if(b.name==="Grep")gr++;
+        else if(b.name==="Edit"||b.name==="Write")ed++;
+      }}catch{}}
+    console.log(`    explore=${ex} node[sym]=${ns} node[file]=${nf} other_cg=${oc} | Read=${reads.length}${reads.length?" ("+reads.join(", ")+")":""} Grep=${gr} Edit=${ed}  [cg exposed=${exposed}]`);
+  ' "$1"
+}
+
+run(){ # label, withCodegraph(0/1)
+  local label="$1" wcg="$2"
+  for i in $(seq 1 "$RUNS"); do
+    local tgt="$OUT/t-$label-$i" cfg="$OUT/mcp-$label.json"
+    rm -rf "$tgt"
+    rsync -a --exclude node_modules --exclude .git --exclude dist --exclude .codegraph "$REPO/" "$tgt/"
+    node "$BIN" init "$tgt" >/dev/null 2>&1
+    if [ "$wcg" = "1" ]; then
+      printf '{"mcpServers":{"codegraph":{"command":"env","args":["CODEGRAPH_WASM_RELAUNCHED=1","node","%s","serve","--mcp","--path","%s"]}}}' "$BIN" "$tgt" > "$cfg"
+      prewarm "$tgt"
+    else cp "$OUT/mcp-empty.json" "$cfg"; fi
+    ( cd "$tgt" && claude -p "$Q" --output-format stream-json --verbose \
+        --permission-mode bypassPermissions --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" --max-budget-usd 4 \
+        --strict-mcp-config --mcp-config "$cfg" </dev/null > "$OUT/$label-$i.jsonl" 2>"$OUT/$label-$i.err" )
+    echo "[$label] run $i:"; analyze "$OUT/$label-$i.jsonl"
+    if [ -n "$BUILD_CMD" ]; then ( cd "$tgt" && eval "$BUILD_CMD" >/dev/null 2>&1 && echo "      build: PASS" || echo "      build: FAIL" ); fi
+    pkill -9 -f "serve --mcp --path $tgt" 2>/dev/null
+  done
+  echo
+}
+
+echo "== WITH codegraph =="; run with 1
+echo "== WITHOUT (Read/Grep only) =="; run without 0
+echo "###### DONE: $OUT"
diff --git a/scripts/agent-eval/ab-new-vs-baseline.sh b/scripts/agent-eval/ab-new-vs-baseline.sh
new file mode 100755
index 000000000..b7fe4e768
--- /dev/null
+++ b/scripts/agent-eval/ab-new-vs-baseline.sh
@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+# A/B a codegraph retrieval/steering change: the NEW build (current HEAD) vs a
+# BASELINE build (a git ref) — BOTH with codegraph attached — on the same
+# implementation task, measuring how many Read vs codegraph calls the agent
+# makes. ISOLATES the change (unlike run-all.sh's with-vs-without). The agent
+# works on a throwaway copy of the target, so your repos are never touched.
+#
+# Reliable attach (works even when this is itself run nested inside a Claude
+# session): each arm PRE-WARMS a persistent codegraph daemon for its target so
+# claude connects to an already-bound, index-loaded daemon instantly — before
+# the agent's first turn — and SKIPS codegraph's startup re-exec via
+# CODEGRAPH_WASM_RELAUNCHED=1. Without this, on a multi-step task the agent
+# dives into Read/grep before codegraph finishes its ~2-3s startup (worse under
+# the CPU contention of a nested run) and runs with NO codegraph.
+#
+# Gotcha: claude's `system/init` snapshot can read status:"pending" / 0 tools
+# even when the server then connects fine — judge by ACTUAL codegraph usage in
+# parse-run.mjs's "by type", not the init line.
+#
+# Usage: ab-new-vs-baseline.sh <indexed-repo> "<task>" [baseline-ref]
+#   <indexed-repo>  a repo with a .codegraph index (copied per arm)
+#   "<task>"        an implementation task, e.g. "Add X to Y and wire it through"
+#   [baseline-ref]  git ref for the BEFORE build (default: HEAD~1)
+# Env: AGENT_EVAL_OUT (default: /tmp/ab-new-vs-baseline)
+set -uo pipefail
+
+TARGET="${1:?usage: ab-new-vs-baseline.sh <indexed-repo> \"<task>\" [baseline-ref]}"
+TASK="${2:?task required}"
+BASE_REF="${3:-HEAD~1}"
+ENGINE="$(cd "$(dirname "$0")/../.." && pwd)"
+BIN="$ENGINE/dist/bin/codegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/ab-new-vs-baseline}"
+PARSE="$ENGINE/scripts/agent-eval/parse-run.mjs"
+
+command -v claude >/dev/null || { echo "claude CLI not on PATH"; exit 1; }
+[ -d "$TARGET/.codegraph" ] || { echo "target not indexed: run 'codegraph init $TARGET' first"; exit 1; }
+if ! git -C "$ENGINE" diff --quiet || ! git -C "$ENGINE" diff --cached --quiet; then
+  echo "engine repo has uncommitted changes — commit or stash first (this script checks files out)"; exit 1
+fi
+CHANGED=$(git -C "$ENGINE" diff --name-only "$BASE_REF" HEAD -- src 2>/dev/null)
+[ -n "$CHANGED" ] || { echo "no src/ changes between $BASE_REF and HEAD — nothing to A/B"; exit 1; }
+
+# On exit: kill any eval daemons + restore the engine to HEAD.
+cleanup() {
+  pkill -9 -f "serve --mcp --path $OUT/" 2>/dev/null
+  git -C "$ENGINE" checkout HEAD -- $CHANGED 2>/dev/null
+  ( cd "$ENGINE" && npm run build >/dev/null 2>&1 )
+}
+trap cleanup EXIT
+
+mkdir -p "$OUT"
+echo "###### engine=$ENGINE  baseline=$BASE_REF"
+echo "###### changed: $(echo "$CHANGED" | tr '\n' ' ')"
+echo "###### target=$TARGET"
+echo "###### task=$TASK"
+echo
+
+# Two pristine copies so each arm starts clean (the agent edits its own copy).
+rm -rf "$OUT/t-new" "$OUT/t-base"
+rsync -a --exclude node_modules --exclude .git --exclude dist --exclude .codegraph "$TARGET/" "$OUT/t-new/"
+cp -R "$OUT/t-new" "$OUT/t-base"
+
+prewarm() { # target — spawn a persistent daemon (current $BIN) and wait for its socket
+  pkill -9 -f "serve --mcp --path $1" 2>/dev/null
+  CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS=1800000 node "$BIN" serve --mcp --path "$1" </dev/null >/dev/null 2>&1 &
+  node -e 'const fs=require("fs");let n=0;const t=setInterval(()=>{if(fs.existsSync(process.argv[1]+"/.codegraph/daemon.sock")){clearInterval(t);process.exit(0)}if(n++>150){clearInterval(t);process.exit(1)}},100)' "$1" \
+    && echo "  daemon warm: $1" || echo "  WARN: daemon never bound for $1 (arm may run without codegraph)"
+}
+
+run_arm() { # label, target-copy
+  local label="$1" tgt="$2" c="$OUT/mcp-$1.json"
+  # Connect to the pre-warmed daemon; skip the startup re-exec for a fast attach.
+  printf '{"mcpServers":{"codegraph":{"command":"env","args":["CODEGRAPH_WASM_RELAUNCHED=1","node","%s","serve","--mcp","--path","%s"]}}}' "$BIN" "$tgt" > "$c"
+  prewarm "$tgt"
+  echo "############## ARM [$label] ##############"
+  ( cd "$tgt" && claude -p "$TASK" \
+      --output-format stream-json --verbose --permission-mode bypassPermissions \
+      --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" --max-budget-usd 4 --strict-mcp-config --mcp-config "$c" \
+      </dev/null > "$OUT/run-$label.jsonl" 2>"$OUT/run-$label.err" )
+  node "$PARSE" "$OUT/run-$label.jsonl" 2>&1 | grep -E "by type|Result" || echo "  (parse failed — see $OUT/run-$label.jsonl)"
+  pkill -9 -f "serve --mcp --path $tgt" 2>/dev/null
+  echo
+}
+
+echo "== NEW build (HEAD) =="
+( cd "$ENGINE" && npm run build >/dev/null 2>&1 ) && echo "  built"
+node "$BIN" init "$OUT/t-new" >/dev/null 2>&1 && echo "  indexed t-new"
+run_arm new "$OUT/t-new"
+
+echo "== BASELINE build ($BASE_REF) =="
+git -C "$ENGINE" checkout "$BASE_REF" -- $CHANGED
+( cd "$ENGINE" && npm run build >/dev/null 2>&1 ) && echo "  built"
+node "$BIN" init "$OUT/t-base" >/dev/null 2>&1 && echo "  indexed t-base"
+run_arm baseline "$OUT/t-base"
+
+echo "###### DONE. Compare the [new] vs [baseline] 'by type' counts above"
+echo "###### (especially Read vs mcp__codegraph__*). Full logs in: $OUT"
diff --git a/scripts/agent-eval/ab-sufficiency.sh b/scripts/agent-eval/ab-sufficiency.sh
new file mode 100644
index 000000000..3db4ff1f6
--- /dev/null
+++ b/scripts/agent-eval/ab-sufficiency.sh
@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# Sufficiency A/B: on a real understanding/flow question, WHEN the agent uses
+# codegraph (explore/node), does it still Read? Premise under test: explore/node
+# return source WITH line numbers, so a Read should not be needed.
+#
+# WITH codegraph (pre-warmed daemon, reliable nested attach) vs WITHOUT (empty
+# MCP, Read/Grep only), N runs each, on a throwaway copy of the repo. Reports
+# explore/node vs Read/Grep, and LISTS the files Read in the WITH arm so a true
+# sufficiency gap (an indexed source file) is distinguishable from out-of-scope
+# (configs, docs, a file codegraph didn't index).
+#
+# Usage: ab-sufficiency.sh <indexed-repo> "<question>" [runs-per-arm]
+# Env: AGENT_EVAL_OUT (default: /tmp/ab-sufficiency)
+set -uo pipefail
+REPO="${1:?usage: ab-sufficiency.sh <indexed-repo> \"<question>\" [runs]}"
+Q="${2:?question required}"
+RUNS="${3:-2}"
+ENGINE="$(cd "$(dirname "$0")/../.." && pwd)"
+BIN="$ENGINE/dist/bin/codegraph.js"
+OUT="${AGENT_EVAL_OUT:-/tmp/ab-sufficiency}"
+TGT="$OUT/target"
+command -v claude >/dev/null || { echo "claude CLI not on PATH"; exit 1; }
+[ -d "$REPO/.codegraph" ] || { echo "no .codegraph index at $REPO"; exit 1; }
+cleanup(){ pkill -9 -f "serve --mcp --path $TGT" 2>/dev/null; }
+trap cleanup EXIT
+mkdir -p "$OUT"
+( cd "$ENGINE" && npm run build >/dev/null 2>&1 ) && echo "built"
+
+# Throwaway copy + fresh index (the agent works here; a read-only question won't
+# edit, but isolate anyway). Excludes the source repo's index/build/vcs.
+rm -rf "$TGT"
+rsync -a --exclude node_modules --exclude .git --exclude dist --exclude .codegraph "$REPO/" "$TGT/"
+node "$BIN" init "$TGT" >/dev/null 2>&1 && echo "indexed copy ($(node "$BIN" status --json 2>/dev/null | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).fileCount+" files")}catch{console.log("?")}})' 2>/dev/null || echo '?'))"
+
+echo "###### repo=$REPO  runs/arm=$RUNS"
+echo "###### Q=$Q"; echo
+echo '{"mcpServers":{}}' > "$OUT/mcp-empty.json"
+printf '{"mcpServers":{"codegraph":{"command":"env","args":["CODEGRAPH_WASM_RELAUNCHED=1","node","%s","serve","--mcp","--path","%s"]}}}' "$BIN" "$TGT" > "$OUT/mcp-cg.json"
+
+prewarm(){
+  pkill -9 -f "serve --mcp --path $TGT" 2>/dev/null
+  CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS=1800000 node "$BIN" serve --mcp --path "$TGT" </dev/null >/dev/null 2>&1 &
+  node -e 'const fs=require("fs");let n=0;const t=setInterval(()=>{if(fs.existsSync(process.argv[1]+"/.codegraph/daemon.sock")){clearInterval(t);process.exit(0)}if(n++>150){clearInterval(t);process.exit(1)}},100)' "$TGT" >/dev/null 2>&1
+}
+
+analyze(){
+  node -e '
+    const fs=require("fs");
+    const L=fs.readFileSync(process.argv[1],"utf8").split("\n").filter(Boolean);
+    let ex=0,nf=0,ns=0,oc=0,gr=0,exposed="?";const reads=[];
+    for(const l of L){try{const o=JSON.parse(l);
+      if(o.type==="system"&&o.subtype==="init")exposed=(o.tools||[]).filter(t=>/codegraph/.test(t)).length;
+      for(const b of (o.message?.content||[])){if(b.type!=="tool_use")continue;
+        if(b.name==="mcp__codegraph__codegraph_explore")ex++;
+        else if(b.name==="mcp__codegraph__codegraph_node"){if(b.input&&b.input.symbol)ns++;else nf++;}
+        else if(/mcp__codegraph__/.test(b.name))oc++;
+        else if(b.name==="Read")reads.push((b.input?.file_path||"").split("/").pop());
+        else if(b.name==="Grep")gr++;
+      }}catch{}}
+    console.log(`    explore=${ex} node[sym]=${ns} node[file]=${nf} other_cg=${oc} | Read=${reads.length}${reads.length?" ("+reads.join(", ")+")":""} Grep=${gr}  [cg exposed=${exposed}]`);
+  ' "$1"
+}
+
+run(){ # label, cfg, prewarm(0/1)
+  local label="$1" cfg="$2" pw="$3"
+  for i in $(seq 1 "$RUNS"); do
+    [ "$pw" = "1" ] && prewarm
+    ( cd "$TGT" && claude -p "$Q" --output-format stream-json --verbose \
+        --permission-mode bypassPermissions --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" --max-budget-usd 4 \
+        --strict-mcp-config --mcp-config "$cfg" </dev/null > "$OUT/$label-$i.jsonl" 2>"$OUT/$label-$i.err" )
+    echo "[$label] run $i:"; analyze "$OUT/$label-$i.jsonl"
+  done
+  echo
+}
+
+echo "== WITH codegraph (premise: explore/node used -> Read ~0) =="; run with "$OUT/mcp-cg.json" 1
+echo "== WITHOUT (Read/Grep only — the contrast) =="; run without "$OUT/mcp-empty.json" 0
+echo "###### DONE. In the WITH arm: are explore/node>0 and Read~0? Any Read of an INDEXED source file = sufficiency gap. Logs: $OUT"
diff --git a/scripts/agent-eval/arms-F.sh b/scripts/agent-eval/arms-F.sh
new file mode 100644
index 000000000..bc9f62fb6
--- /dev/null
+++ b/scripts/agent-eval/arms-F.sh
@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Arm F (body-inlining trace + trace-first steering) across the same 6 repos as
+# arms-matrix.sh, so F vs B isolates the trace-enrichment effect (same surface,
+# old thin trace in B vs body-inlining trace here).
+set -uo pipefail
+H="$(cd "$(dirname "$0")" && pwd)"; RUNS="${RUNS:-2}"; C="${CORPUS:-/tmp/codegraph-corpus}"
+ROWS=(
+"$C/flutter-samples/add_to_app/books/flutter_module_books|How does the books UI build and what child widgets does it show?"
+"$C/aspnet-realworld|How is creating an article handled? Trace the controller to the service."
+"$C/spring-mall|How is a product-list request handled? Trace the controller to the service."
+"$C/vapor-spi|How is a package-show request handled? Name the route and controller."
+"$C/excalidraw|How does updating an element re-render the canvas on screen? Trace the flow."
+"$C/spring-halo|How is publishing a post handled? Trace the controller to the service."
+)
+ARM="${ARM:-F}"
+echo "### ARM $ARM START $(date) RUNS=$RUNS"
+for row in "${ROWS[@]}"; do
+  repo="${row%%|*}"; q="${row#*|}"
+  for r in $(seq 1 "$RUNS"); do bash "$H/run-arms.sh" "$repo" "$q" "$ARM" "$r"; done
+done
+echo "### ARM $ARM COMPLETE $(date)"
diff --git a/scripts/agent-eval/arms-matrix.sh b/scripts/agent-eval/arms-matrix.sh
new file mode 100644
index 000000000..ea7becbb3
--- /dev/null
+++ b/scripts/agent-eval/arms-matrix.sh
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Drive the tool-surface ablation across the chosen repos × arms (A–E).
+# Arms A–D ask the canonical FLOW question; arm E asks a NON-flow survey
+# question (the control probe — should degrade without explore+context).
+# Output: /tmp/arms/<repo>/<arm>-r<n>.jsonl  (parse with parse-arms.mjs).
+set -uo pipefail
+HARNESS="$(cd "$(dirname "$0")" && pwd)"
+RUNS="${RUNS:-2}"
+C="${CORPUS:-/tmp/codegraph-corpus}"
+NFQ='What are the main modules/components of this codebase and what does each one do? Give an overview of how it is organized.'
+
+# repo-path|flow-question  (2 small, 2 medium, 2 large — spans the size range)
+ROWS=(
+"$C/flutter-samples/add_to_app/books/flutter_module_books|How does the books UI build and what child widgets does it show?"
+"$C/aspnet-realworld|How is creating an article handled? Trace the controller to the service."
+"$C/spring-mall|How is a product-list request handled? Trace the controller to the service."
+"$C/vapor-spi|How is a package-show request handled? Name the route and controller."
+"$C/excalidraw|How does updating an element re-render the canvas on screen? Trace the flow."
+"$C/spring-halo|How is publishing a post handled? Trace the controller to the service."
+)
+
+echo "### ARMS MATRIX START $(date) RUNS=$RUNS"
+for row in "${ROWS[@]}"; do
+  repo="${row%%|*}"; q="${row#*|}"
+  for arm in A B C D; do
+    for r in $(seq 1 "$RUNS"); do
+      bash "$HARNESS/run-arms.sh" "$repo" "$q" "$arm" "$r"
+    done
+  done
+done
+# E: non-flow control probe on two repos (must degrade without explore+context)
+for repo in "$C/excalidraw" "$C/spring-mall"; do
+  for r in $(seq 1 "$RUNS"); do
+    bash "$HARNESS/run-arms.sh" "$repo" "$NFQ" E "$r"
+  done
+done
+echo "### ARMS MATRIX COMPLETE $(date)"
diff --git a/scripts/agent-eval/bench-readme.sh b/scripts/agent-eval/bench-readme.sh
new file mode 100644
index 000000000..60a5330b2
--- /dev/null
+++ b/scripts/agent-eval/bench-readme.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Re-run the README "Benchmark Results" A/B (with vs without codegraph) on the
+# current build: the 7 README repos, same queries, RUNS per arm (default 4).
+# Output → /tmp/ab-readme/<repo>/run<n>/run-headless-{with,without}.jsonl
+# Aggregate with parse-bench-readme.mjs. Repos must be cloned + indexed under
+# $CORPUS (default /tmp/codegraph-corpus) by the build under test.
+set -uo pipefail
+H="$(cd "$(dirname "$0")" && pwd)"
+C="${CORPUS:-/tmp/codegraph-corpus}"
+RUNS="${RUNS:-4}"
+ROWS=(
+"vscode|How does the extension host communicate with the main process?"
+"excalidraw|How does Excalidraw render and update canvas elements?"
+"django|How does Django's ORM build and execute a query from a QuerySet?"
+"tokio|How does tokio schedule and run async tasks on its runtime?"
+"okhttp|How does OkHttp process a request through its interceptor chain?"
+"gin|How does gin route requests through its middleware chain?"
+"alamofire|How does Alamofire build, send, and validate a request?"
+)
+echo "### README A/B START $(date) RUNS=$RUNS"
+for row in "${ROWS[@]}"; do
+  repo="${row%%|*}"; q="${row#*|}"
+  echo "===== $repo ====="
+  for run in $(seq 1 "$RUNS"); do
+    AGENT_EVAL_OUT="/tmp/ab-readme/$repo/run$run" bash "$H/run-all.sh" "$C/$repo" "$q" headless 2>&1 | grep -E "exit [0-9]" || echo "  run$run: (no exit line)"
+  done
+done
+echo "### README A/B DONE $(date)"
diff --git a/scripts/agent-eval/bench-why-repo.sh b/scripts/agent-eval/bench-why-repo.sh
new file mode 100644
index 000000000..2e26a2ffc
--- /dev/null
+++ b/scripts/agent-eval/bench-why-repo.sh
@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# One README repo, WITH-codegraph only, N runs. Each run appends a why-Read
+# diagnostic so the agent explains any Read/Grep. (The WITHOUT baseline is
+# codegraph-independent and already in the README — no point re-running it.)
+# Output -> /tmp/ab-why/<repo>/with<n>.jsonl
+# Usage: bench-why-repo.sh <repo-path> "<query>" [N]
+set -uo pipefail
+REPO="$1"; Q="$2"; N="${3:-4}"
+NAME="$(basename "$REPO")"
+CG="/Users/colby/Development/Personal/codegraph/dist/bin/codegraph.js"
+OUT="/tmp/ab-why/$NAME"; mkdir -p "$OUT"
+WHY=$'\n\nIMPORTANT — diagnostic: if you use the Read or Grep tool at ANY point, for EACH such call explain why codegraph_explore / codegraph_node did not already give you what you needed. End your entire answer with a section titled exactly "## Why I read" listing every Read and Grep you made and the precise reason codegraph fell short for it. If you used neither, write "## Why I read" then "none — codegraph was sufficient."'
+printf '{"mcpServers":{"codegraph":{"command":"%s","args":["serve","--mcp","--path","%s"]}}}' "$CG" "$REPO" > "$OUT/cg.json"
+
+for i in $(seq 1 "$N"); do
+  pkill -f "serve --mcp" 2>/dev/null; sleep 1; rm -f "$REPO/.codegraph/daemon.sock"
+  ( cd "$REPO" && claude -p "$Q$WHY" --output-format stream-json --verbose \
+      --permission-mode bypassPermissions --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" --max-budget-usd 4 \
+      --strict-mcp-config --mcp-config "$OUT/cg.json" > "$OUT/with$i.jsonl" 2>"$OUT/with$i.err" )
+  echo "WITH run $i: exit $? ($(wc -l < "$OUT/with$i.jsonl" | tr -d ' ') lines)"
+done
+echo "DONE $NAME"
diff --git a/scripts/agent-eval/block-read-hook.sh b/scripts/agent-eval/block-read-hook.sh
new file mode 100644
index 000000000..feca7fe80
--- /dev/null
+++ b/scripts/agent-eval/block-read-hook.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# PreToolUse hook (experiment): deny Read of codegraph-indexed source files and
+# steer the agent to codegraph_explore/codegraph_node instead. Tests whether
+# codegraph can FULLY replace Read for code-understanding once the escape hatch
+# is removed. Non-source reads (config, .env, markdown, new files) pass through.
+#
+# Wire via:  claude ... --settings scripts/agent-eval/hook-settings.json
+set -uo pipefail
+input="$(cat)"
+fp="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null)"
+
+case "$fp" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.py|*.go|*.rs|*.java|*.rb|*.php|*.swift|*.kt|*.kts|*.c|*.cc|*.cpp|*.h|*.hpp|*.cs|*.lua|*.vue|*.svelte)
+    msg="Read is disabled for source files in this session — codegraph already has this file indexed (with line numbers, kept in sync on every change). Use codegraph_explore (several related symbols at once) or codegraph_node (one symbol's full source). If a symbol you need wasn't in a prior explore, run ANOTHER codegraph_explore with its exact name instead of reading the file."
+    jq -n --arg m "$msg" '{reason:$m, hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$m}}'
+    exit 0
+    ;;
+esac
+exit 0
diff --git a/scripts/agent-eval/hook-settings.json b/scripts/agent-eval/hook-settings.json
new file mode 100644
index 000000000..10880fa89
--- /dev/null
+++ b/scripts/agent-eval/hook-settings.json
@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash /Users/colby/Development/Personal/codegraph/scripts/agent-eval/block-read-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/scripts/agent-eval/itrun.sh b/scripts/agent-eval/itrun.sh
index f73d4650a..f9becee3a 100755
--- a/scripts/agent-eval/itrun.sh
+++ b/scripts/agent-eval/itrun.sh
@@ -81,25 +81,38 @@ for _ in $(seq 1 120); do
 done
 [ "$started" = 1 ] || { echo "agent never started working"; cap; tmux kill-session -t "$SESSION" 2>/dev/null; exit 1; }
 
-# Poll for idle: not busy AND ❯ present, for 10 consecutive polls (~5s) to ride
-# out mid-conversation thinking gaps that briefly drop the spinner. Up to ~15min.
-consec=0
-for _ in $(seq 1 1800); do
-  pane=$(cap)
-  if echo "$pane" | grep -qE "$BUSY_RE"; then
-    consec=0
-  elif echo "$pane" | grep -q "❯"; then
-    consec=$((consec+1)); [ "$consec" -ge 10 ] && break
+# Poll for idle. CRITICAL: Opus 4.8 (extended thinking) renders NO spinner /
+# "esc to interrupt" / timer while it STREAMS its final answer — those appear
+# only during the thinking + tool-use phases ("✻ Marinating… (32s · ↓ 1.3k
+# tokens · thinking with max effort)"). So BUSY_RE reads "not busy" for the whole
+# 10-30s answer stream, and any short not-busy threshold kills the run mid-answer
+# (the truncation bug). We therefore detect "done" by CONTENT STABILITY, not by a
+# spinner string: while the agent streams, the captured pane changes every poll,
+# so stability never accrues; it accrues only once the agent has finished and the
+# static "✻ Brewed for 1m 9s" summary is all that is left. BUSY_RE still hard-
+# resets stability (covers thinking/tool-use/live-timer, where text can briefly
+# sit still). Need STABLE_NEEDED polls (~8s) of zero pane change + ❯ present.
+# Content-stability is model-agnostic — it survives future spinner re-wordings.
+STABLE_NEEDED=16
+prev=""; stable=0
+for _ in $(seq 1 2400); do            # up to ~20 min
+  pane="$(cap)"
+  sig="$(printf '%s' "$pane" | tr -s '[:space:]' ' ')"
+  if printf '%s' "$pane" | grep -qE "$BUSY_RE"; then
+    stable=0                          # thinking / tool use / live timer → busy
+  elif [ -n "$sig" ] && [ "$sig" = "$prev" ] && printf '%s' "$pane" | grep -q "❯"; then
+    stable=$((stable+1)); [ "$stable" -ge "$STABLE_NEEDED" ] && break
   else
-    consec=0
+    stable=0                          # answer still streaming → pane changing
   fi
+  prev="$sig"
   sleep 0.5
 done
 sleep 1
 
 tmux capture-pane -p -t "$SESSION" -S - > "$OUT"
 echo "captured $(wc -l < "$OUT") lines -> $OUT"
-grep -oE "Done \([^)]*\)" "$OUT" | tail -1
+grep -oE "Done \([^)]*\)|[A-Z][a-z]+ for ([0-9]+m )?[0-9]+s" "$OUT" | tail -1
 grep -oE "[0-9.]+k?/[0-9.]+M" "$OUT" | tail -1 | sed 's/^/Context /'
 tmux kill-session -t "$SESSION" 2>/dev/null
 
diff --git a/scripts/agent-eval/parse-arms.mjs b/scripts/agent-eval/parse-arms.mjs
new file mode 100644
index 000000000..75cb77984
--- /dev/null
+++ b/scripts/agent-eval/parse-arms.mjs
@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Analyze the tool-surface ablation (/tmp/arms/<repo>/<arm>-r<n>.jsonl).
+// Compares arms A–E on trace adoption, Read/Grep fallback, codegraph payload,
+// round-trips, and duration — averaged across runs per arm.
+//
+// The decisive signal is READS: if removing a tool raises Reads on a question
+// class, that tool was load-bearing for it (not redundant). If removing it
+// changes nothing, it was redundant.
+//
+//   A control       all tools            no steering   (baseline)
+//   B steer         all tools            trace-first   (adoption)
+//   C no-explore    hide explore         trace-first   (is explore redundant?)
+//   D trace-centric hide explore+context trace-first   (is the survey pair redundant?)
+//   E control-probe hide explore+context trace-first   (NON-flow Q — should degrade)
+//
+// Usage: node scripts/agent-eval/parse-arms.mjs [/tmp/arms]
+import { readFileSync, readdirSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+
+const ROOT = process.argv[2] || '/tmp/arms';
+const cgShort = (n) => n.replace('mcp__codegraph__codegraph_', '').replace('mcp__codegraph__', '');
+
+function parse(file) {
+  if (!existsSync(file)) return null;
+  const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+  const calls = []; let result = null, initCg = 0;
+  for (const l of lines) {
+    let ev; try { ev = JSON.parse(l); } catch { continue; }
+    if (ev.type === 'system' && ev.subtype === 'init') initCg = (ev.tools || []).filter(t => /codegraph/.test(t)).length;
+    if (ev.type === 'assistant') for (const b of (ev.message?.content || [])) if (b.type === 'tool_use')
+      calls.push({ id: b.id, name: b.name, out: 0 });
+    if (ev.type === 'user') for (const b of (ev.message?.content || [])) if (b.type === 'tool_result') {
+      const c = b.content;
+      const txt = typeof c === 'string' ? c : Array.isArray(c) ? c.map(x => x?.text || '').join('') : '';
+      const call = calls.find(k => k.id === b.tool_use_id); if (call) call.out = txt.length;
+    }
+    if (ev.type === 'result') result = ev;
+  }
+  const cg = calls.filter(c => c.name.includes('codegraph'));
+  return {
+    initCg,
+    reads: calls.filter(c => c.name === 'Read').length,
+    greps: calls.filter(c => c.name === 'Grep').length + calls.filter(c => c.name === 'Glob').length,
+    cgCalls: cg.length,
+    cgSeq: cg.map(c => cgShort(c.name)),
+    cgOut: cg.reduce((s, c) => s + c.out, 0),
+    traceUsed: cg.some(c => c.name.includes('trace')),
+    turns: result?.num_turns ?? null,
+    dur: result?.duration_ms ? Math.round(result.duration_ms / 1000) : null,
+    cost: result?.total_cost_usd || 0,
+    ok: result?.subtype === 'success',
+  };
+}
+
+// repo -> arm -> [runs]
+const data = {};
+if (!existsSync(ROOT)) { console.error(`no ${ROOT}`); process.exit(1); }
+for (const repo of readdirSync(ROOT)) {
+  const rdir = join(ROOT, repo);
+  if (!statSync(rdir).isDirectory()) continue;
+  for (const f of readdirSync(rdir)) {
+    const m = f.match(/^([A-I])-r(\d+)\.jsonl$/); if (!m) continue;
+    const p = parse(join(rdir, f)); if (!p || !p.ok) continue;
+    (((data[repo] ??= {})[m[1]]) ??= []).push(p);
+  }
+}
+
+const avg = (a, f) => a.length ? a.reduce((s, x) => s + (f(x) || 0), 0) / a.length : 0;
+const k = (n) => (n / 1000).toFixed(1);
+const pad = (s, n) => String(s).padEnd(n);
+const ARMS = ['A', 'H', 'I', 'B', 'F', 'G', 'C', 'D', 'E'];
+const LABEL = { A: 'A all/none(old)', H: 'H body-trace/none', I: 'I bodytrace+dest', B: 'B all/steer(thin)', F: 'F all/steer(body)', G: 'G ported(noprompt)', C: 'C no-explore', D: 'D trace-centric', E: 'E nonflow-probe' };
+
+// ---- per repo × arm ----
+console.log('\n=== PER REPO × ARM (avg over runs) ===');
+console.log(pad('repo', 22), pad('arm', 16), 'tools', 'trace', pad('reads', 6), pad('cgOutK', 7), pad('turns', 6), 'dur');
+for (const repo of Object.keys(data).sort()) {
+  for (const arm of ARMS) {
+    const runs = data[repo][arm]; if (!runs?.length) continue;
+    console.log(
+      pad(repo, 22), pad(LABEL[arm], 16),
+      pad(runs[0].initCg, 5),
+      pad(runs.filter(r => r.traceUsed).length + '/' + runs.length, 5),
+      pad(avg(runs, r => r.reads).toFixed(1), 6),
+      pad(k(avg(runs, r => r.cgOut)), 7),
+      pad(avg(runs, r => r.turns).toFixed(1), 6),
+      avg(runs, r => r.dur).toFixed(0) + 's',
+    );
+  }
+}
+
+// ---- aggregate per arm (flow arms A–D over the flow repos; E shown apart) ----
+console.log('\n=== AGGREGATE PER ARM (mean across repos) ===');
+console.log(pad('arm', 16), pad('adoption', 9), pad('reads', 7), pad('greps', 7), pad('cgOutK', 8), pad('turns', 7), pad('dur', 6), 'cost');
+for (const arm of ARMS) {
+  const all = [];
+  for (const repo of Object.keys(data)) for (const r of (data[repo][arm] || [])) all.push({ ...r, repo });
+  if (!all.length) continue;
+  const repos = new Set(all.map(r => r.repo)).size;
+  const adopt = all.filter(r => r.traceUsed).length;
+  console.log(
+    pad(LABEL[arm], 16),
+    pad(`${adopt}/${all.length}`, 9),
+    pad(avg(all, r => r.reads).toFixed(2), 7),
+    pad(avg(all, r => r.greps).toFixed(2), 7),
+    pad(k(avg(all, r => r.cgOut)), 8),
+    pad(avg(all, r => r.turns).toFixed(1), 7),
+    pad(avg(all, r => r.dur).toFixed(0) + 's', 6),
+    '$' + avg(all, r => r.cost).toFixed(3),
+    `  (${repos} repos)`,
+  );
+}
+
+console.log('\nRead the signal: B vs A = does steering alone fix adoption + cut payload.');
+console.log('C vs B = is explore redundant (reads should NOT jump). D vs C = is context redundant.');
+console.log('E = non-flow under trace-centric; reads SHOULD jump (proves survey tools are load-bearing).');
diff --git a/scripts/agent-eval/parse-bench-readme.mjs b/scripts/agent-eval/parse-bench-readme.mjs
new file mode 100644
index 000000000..f7c5ade43
--- /dev/null
+++ b/scripts/agent-eval/parse-bench-readme.mjs
@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Aggregate the README A/B (bench-readme.sh output): per repo, median of N runs
+// per arm → time, tool calls, tokens, cost, and % saved. Plus an average row.
+//
+// Tokens = SUM of per-turn assistant `usage` (input + output + cache read +
+// cache creation) — the cumulative "total tokens processed". NOTE: `result.usage`
+// is last-turn-only in current Claude Code, so it under-counts badly; don't use it.
+// `total_cost_usd` and `duration_ms` are already cumulative.
+//
+// Usage: node parse-bench-readme.mjs [/tmp/ab-readme]
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+const ROOT = process.argv[2] || '/tmp/ab-readme';
+const REPOS = ['vscode', 'excalidraw', 'django', 'tokio', 'okhttp', 'gin', 'alamofire'];
+
+function parse(file) {
+  if (!existsSync(file)) return null;
+  const L = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+  let tools = 0, reads = 0, grep = 0, cg = 0, tokens = 0, r = null, raced = false;
+  for (const l of L) { let e; try { e = JSON.parse(l); } catch { continue; }
+    if (e.type === 'assistant') {
+      const u = e.message?.usage;
+      if (u) tokens += (u.input_tokens || 0) + (u.output_tokens || 0) + (u.cache_read_input_tokens || 0) + (u.cache_creation_input_tokens || 0);
+      for (const b of (e.message?.content || [])) if (b.type === 'tool_use') {
+        const n = b.name;
+        if (n === 'ToolSearch') continue;
+        tools++;
+        if (n === 'Read') reads++;
+        else if (n === 'Grep' || n === 'Glob') grep++;
+        else if (/codegraph/.test(n)) cg++;
+      }
+    }
+    // MCP cold-start race: the headless agent fired before `codegraph serve --mcp`
+    // finished registering its tools, so early calls returned "No such tool
+    // available" and the agent floundered into grep/Read. That measures CodeGraph's
+    // startup latency, NOT its steady-state value — flag the run so the aggregate
+    // can exclude it (an artifact of headless first-turn timing, not the tool).
+    if (e.type === 'user') for (const b of (Array.isArray(e.message?.content) ? e.message.content : [])) {
+      if (b.type === 'tool_result') {
+        const t = Array.isArray(b.content) ? b.content.map(c => c.text || '').join('') : (b.content || '');
+        if (/No such tool available/.test(t)) raced = true;
+      }
+    }
+    if (e.type === 'result') r = e;
+  }
+  if (!r || r.subtype !== 'success') return null;
+  return { dur: r.duration_ms / 1000, tools, reads, grep, cg, tokens, cost: r.total_cost_usd || 0, raced };
+}
+const median = (arr) => { const v = [...arr].sort((a, b) => a - b); const n = v.length; return n === 0 ? 0 : n % 2 ? v[(n - 1) / 2] : (v[n / 2 - 1] + v[n / 2]) / 2; };
+const fmtTime = (s) => s >= 60 ? `${Math.floor(s / 60)}m ${Math.round(s % 60)}s` : `${Math.round(s)}s`;
+const fmtTok = (t) => t >= 1e6 ? `${(t / 1e6).toFixed(1)}M` : `${Math.round(t / 1000)}k`;
+const pct = (w, wo) => wo > 0 ? Math.round((1 - w / wo) * 100) : 0;
+
+console.log('repo        n(w/wo)  time WITH→WITHOUT      tools W→WO   tokens W→WO (saved)     cost W→WO (saved)');
+const savings = { cost: [], tokens: [], time: [], tools: [] };
+for (const repo of REPOS) {
+  const dir = join(ROOT, repo);
+  const runDirs = existsSync(dir) ? readdirSync(dir).filter(d => /^run\d+$/.test(d)) : [];
+  // Exclude MCP-cold-start-raced WITH runs by default — they measure a startup
+  // race, not steady-state value. `CG_INCLUDE_RACED=1` keeps them (to see the raw
+  // distribution). The WITHOUT arm has no MCP, so it's never raced.
+  const includeRaced = process.env.CG_INCLUDE_RACED === '1';
+  const W = [], WO = []; let racedExcluded = 0;
+  for (const rd of runDirs) {
+    const w = parse(join(dir, rd, 'run-headless-with.jsonl'));
+    if (w) { if (w.raced && !includeRaced) racedExcluded++; else W.push(w); }
+    const wo = parse(join(dir, rd, 'run-headless-without.jsonl')); if (wo) WO.push(wo);
+  }
+  if (!W.length || !WO.length) { console.log(`${repo.padEnd(11)} (incomplete: w=${W.length} wo=${WO.length})`); continue; }
+  const m = (arr, k) => median(arr.map(x => x[k]));
+  const wT = m(W, 'dur'), woT = m(WO, 'dur'), wTok = m(W, 'tokens'), woTok = m(WO, 'tokens');
+  const wC = m(W, 'cost'), woC = m(WO, 'cost'), wTl = m(W, 'tools'), woTl = m(WO, 'tools');
+  savings.time.push(pct(wT, woT)); savings.tokens.push(pct(wTok, woTok)); savings.cost.push(pct(wC, woC)); savings.tools.push(pct(wTl, woTl));
+  console.log(
+    `${repo.padEnd(11)} ${W.length}/${WO.length}      ` +
+    `${(fmtTime(wT) + '→' + fmtTime(woT)).padEnd(22)}` +
+    `${(Math.round(wTl) + '→' + Math.round(woTl)).padEnd(12)}` +
+    `${(fmtTok(wTok) + '→' + fmtTok(woTok) + ' (' + pct(wTok, woTok) + '%)').padEnd(24)}` +
+    `$${wC.toFixed(2)}→$${woC.toFixed(2)} (${pct(wC, woC)}%)` +
+    (racedExcluded ? `  [${racedExcluded} raced run${racedExcluded === 1 ? '' : 's'} excluded]` : '')
+  );
+}
+const avg = (a) => a.length ? Math.round(a.reduce((s, x) => s + x, 0) / a.length) : 0;
+console.log(`\nAVERAGE saved:  cost ${avg(savings.cost)}%  ·  tokens ${avg(savings.tokens)}%  ·  time ${avg(savings.time)}%  ·  tool calls ${avg(savings.tools)}%`);
diff --git a/scripts/agent-eval/probe-context.mjs b/scripts/agent-eval/probe-context.mjs
new file mode 100644
index 000000000..1328c2121
--- /dev/null
+++ b/scripts/agent-eval/probe-context.mjs
@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+// Probe codegraph_context (with call-paths) against an index using the built dist.
+// Usage: node probe-context.mjs <repo-with-.codegraph> <task words...>
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+
+const [, , repo, ...taskParts] = process.argv;
+const task = taskParts.join(' ');
+if (!repo || !task) { console.error('usage: probe-context.mjs <repo> <task...>'); process.exit(1); }
+
+const load = async (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const tools = await load('dist/mcp/tools.js');
+const CodeGraph = idx.default?.default ?? idx.default ?? idx.CodeGraph;
+const ToolHandler = tools.ToolHandler ?? tools.default?.ToolHandler;
+
+const cg = CodeGraph.openSync(repo);
+const h = new ToolHandler(cg);
+const res = await h.execute('codegraph_context', { task });
+console.log(res.content?.[0]?.text ?? '(no text)');
+try { cg.close?.(); } catch {}
diff --git a/scripts/agent-eval/probe-explore.mjs b/scripts/agent-eval/probe-explore.mjs
new file mode 100644
index 000000000..05ae073d4
--- /dev/null
+++ b/scripts/agent-eval/probe-explore.mjs
@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// One-shot probe: run handleExplore against an existing index using the built
+// dist, print the output + a few stats. Lets us verify explore's coverage fix
+// without a full agent run. Usage: node probe-explore.mjs <repo-with-.codegraph> "<query>"
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+
+const [, , repo, query] = process.argv;
+if (!repo || !query) {
+  console.error('usage: probe-explore.mjs <repo> "<query>"');
+  process.exit(1);
+}
+
+const load = async (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const tools = await load('dist/mcp/tools.js');
+
+// esModuleInterop: dynamic import of CJS yields { default: module.exports, ...named }
+const CodeGraph = idx.default?.default ?? idx.default ?? idx.CodeGraph;
+const ToolHandler = tools.ToolHandler ?? tools.default?.ToolHandler;
+
+if (typeof CodeGraph?.openSync !== 'function') {
+  console.error('could not resolve CodeGraph.openSync; index keys:', Object.keys(idx), 'default keys:', idx.default && Object.keys(idx.default));
+  process.exit(2);
+}
+if (typeof ToolHandler !== 'function') {
+  console.error('could not resolve ToolHandler; tools keys:', Object.keys(tools));
+  process.exit(2);
+}
+
+const cg = CodeGraph.openSync(repo);
+const h = new ToolHandler(cg);
+const res = await h.execute('codegraph_explore', { query });
+const text = res.content?.[0]?.text ?? '(no text)';
+console.log(text);
+console.error('\n--- PROBE STATS ---');
+console.error('output chars:', text.length);
+console.error('triggerRender body present (-> setState({})):', /triggerRender[\s\S]{0,400}setState\(\{\}\)/.test(text));
+console.error('App.tsx in source section:', /#### .*App\.tsx —/.test(text));
+try { cg.close?.(); } catch {}
diff --git a/scripts/agent-eval/probe-node.mjs b/scripts/agent-eval/probe-node.mjs
new file mode 100644
index 000000000..539a8c43d
--- /dev/null
+++ b/scripts/agent-eval/probe-node.mjs
@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Probe codegraph_node (with trail) against an index using the built dist.
+// Usage: node probe-node.mjs <repo-with-.codegraph> <symbol> [code]
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+
+const [, , repo, symbol, code] = process.argv;
+if (!repo || !symbol) { console.error('usage: probe-node.mjs <repo> <symbol> [code]'); process.exit(1); }
+
+const load = async (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const tools = await load('dist/mcp/tools.js');
+const CodeGraph = idx.default?.default ?? idx.default ?? idx.CodeGraph;
+const ToolHandler = tools.ToolHandler ?? tools.default?.ToolHandler;
+
+const cg = CodeGraph.openSync(repo);
+const h = new ToolHandler(cg);
+const res = await h.execute('codegraph_node', { symbol, includeCode: code === 'code' });
+console.log(res.content?.[0]?.text ?? '(no text)');
+try { cg.close?.(); } catch {}
diff --git a/scripts/agent-eval/probe-sweep.mjs b/scripts/agent-eval/probe-sweep.mjs
new file mode 100755
index 000000000..0018bbcaf
--- /dev/null
+++ b/scripts/agent-eval/probe-sweep.mjs
@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// probe-sweep — direct MCP test across N repos × N tools, no claude needed.
+//
+// Measures response characteristics (size, sections present, signals fired)
+// for each (repo, query) pair against the built dist/. Sub-second per probe;
+// the full sweep below runs in ~10-30s vs hours for a real claude audit.
+//
+// Use this to iterate on backend changes rapidly: change tools.ts /
+// context-builder, npm run build, re-run probe-sweep, compare. Once a
+// change looks good on probe metrics, run a focused claude audit for the
+// few repos that matter to confirm end-to-end cost behavior.
+//
+// Usage: node scripts/agent-eval/probe-sweep.mjs [--tool=context|explore|trace] [--repos=a,b,c]
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+
+const args = Object.fromEntries(
+  process.argv.slice(2).map(a => a.startsWith('--') ? a.slice(2).split('=') : [a, true])
+);
+const TOOL = args.tool ?? 'context';
+
+const load = (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const tools = await load('dist/mcp/tools.js');
+const CodeGraph = idx.default?.default ?? idx.default ?? idx.CodeGraph;
+const ToolHandler = tools.ToolHandler ?? tools.default?.ToolHandler;
+
+// Each entry: repo, query, optional 2nd arg for trace (from, to).
+// The query is the same prompt used in the real claude audits, so probe
+// output is directly comparable to the agent's would-be input.
+const SWEEP = [
+  // Small realworld template repos (the loss cases from the cross-language sweep)
+  { id: 'gin-rw',        repo: '/tmp/codegraph-corpus/gin-realworld',         q: 'How does this Gin app route a request through its middleware chain to a handler?' },
+  { id: 'go-mux',        repo: '/tmp/codegraph-corpus/go-mux',                q: 'How does this gorilla/mux app route a request to its handler?' },
+  { id: 'fastapi-rw',    repo: '/tmp/codegraph-corpus/fastapi-realworld',     q: 'How does FastAPI route a request through its dependencies to a handler?' },
+  { id: 'spring-pc',     repo: '/tmp/codegraph-corpus/spring-petclinic',      q: 'How does Spring route an HTTP request to a controller method?' },
+  { id: 'axum-rw',       repo: '/tmp/codegraph-corpus/rust-axum-realworld',   q: 'How does Axum route a request to its handler in this app?' },
+  { id: 'express-rw',    repo: '/tmp/codegraph-corpus/express-realworld',     q: 'How does this Express app route a request through middleware to a handler?' },
+  { id: 'kotlin-pc',     repo: '/tmp/codegraph-corpus/kotlin-petclinic',      q: 'How does the Kotlin Spring app route an HTTP request to its handler?' },
+  { id: 'flask-mb',      repo: '/tmp/codegraph-corpus/flask-microblog',       q: 'How does this Flask app route a request to a view function?' },
+  { id: 'vapor-tpl',     repo: '/tmp/codegraph-corpus/vapor-template',        q: 'How does Vapor route an HTTP request to its handler?' },
+  { id: 'cpp-leveldb',   repo: '/tmp/codegraph-corpus/cpp-leveldb',           q: 'How does LevelDB handle a Put operation through to disk?' },
+  { id: 'lualine',       repo: '/tmp/codegraph-corpus/lualine.nvim',          q: 'How does lualine assemble and render the statusline?' },
+  { id: 'drupal-admin',  repo: '/tmp/codegraph-corpus/drupal-admintoolbar',   q: 'How does the Drupal admin toolbar module render its toolbar?' },
+  { id: 'svelte-rw',     repo: '/tmp/codegraph-corpus/svelte-realworld',      q: 'How does this SvelteKit app route a request to a handler?' },
+  { id: 'react-rw',      repo: '/tmp/codegraph-corpus/react-realworld',       q: 'How does this React app fetch and display articles?' },
+  { id: 'rails-rw',      repo: '/tmp/codegraph-corpus/rails-realworld',       q: 'How does Rails route a request to a controller action?' },
+  { id: 'flask-rest',    repo: '/tmp/codegraph-corpus/flask-restful-realworld', q: 'How does Flask-RESTful route a request to a resource method?' },
+  { id: 'laravel-rw',    repo: '/tmp/codegraph-corpus/laravel-realworld',     q: 'How does Laravel route a request to the controller method?' },
+  { id: 'aspnet-rw',     repo: '/tmp/codegraph-corpus/aspnet-realworld',      q: 'How does ASP.NET route a request to the controller action?' },
+  // The iter7 wins/ties (to make sure we don't regress)
+  { id: 'cobra',         repo: '/tmp/codegraph-corpus/cobra',                 q: 'How does cobra parse commands and flags?' },
+  { id: 'sinatra',       repo: '/tmp/codegraph-corpus/sinatra',               q: 'How does sinatra route a request to its handler?' },
+  { id: 'slim',          repo: '/tmp/codegraph-corpus/slim',                  q: 'How does slim route a request and apply middleware?' },
+];
+
+// Detect signals in response text — these are the levers we've added that
+// otherwise only show up via "agent ran X more tool calls" downstream.
+const detect = (text) => ({
+  hasEntryPoints: /^### Entry Points/m.test(text),
+  hasRelatedSymbols: /^### Related Symbols/m.test(text),
+  hasFlowTrace: /^## Inline flow trace/m.test(text),
+  hasRouteManifest: /^## Routing manifest/m.test(text),
+  hasTopHandler: /^### Top handler file/m.test(text),
+  hasSmallRepoTail: /This project is small/.test(text),
+});
+
+const filterRepos = args.repos ? new Set(String(args.repos).split(',')) : null;
+const subjects = SWEEP.filter(s => !filterRepos || filterRepos.has(s.id));
+
+const t0 = Date.now();
+const rows = [];
+for (const s of subjects) {
+  try {
+    const cg = CodeGraph.openSync(s.repo);
+    const handler = new ToolHandler(cg);
+    const t1 = Date.now();
+    const res = await handler.execute('codegraph_' + TOOL,
+      TOOL === 'context' ? { task: s.q } :
+      TOOL === 'explore' ? { query: s.q } : { from: 'main', to: 'main' });
+    const text = res.content?.[0]?.text ?? '';
+    const signals = detect(text);
+    rows.push({
+      id: s.id,
+      ms: Date.now() - t1,
+      chars: text.length,
+      lines: text.split('\n').length,
+      ...signals,
+    });
+    try { cg.close?.(); } catch {}
+  } catch (e) {
+    rows.push({ id: s.id, error: String(e).slice(0, 80) });
+  }
+}
+
+// Pretty-print as a compact table.
+const fmt = (r) =>
+  r.error
+    ? `  ${r.id.padEnd(13)} ERROR: ${r.error}`
+    : `  ${r.id.padEnd(13)} ${String(r.chars).padStart(6)}c ${String(r.lines).padStart(4)}L ${String(r.ms).padStart(4)}ms` +
+      ` ${r.hasEntryPoints ? 'EP ' : '   '}` +
+      `${r.hasFlowTrace ? 'TRC ' : '    '}` +
+      `${r.hasRouteManifest ? 'MAN ' : '    '}` +
+      `${r.hasTopHandler ? 'HND ' : '    '}` +
+      `${r.hasSmallRepoTail ? 'TAIL' : '    '}`;
+console.log(`=== probe-sweep tool=${TOOL} n=${subjects.length} (${Date.now() - t0}ms total) ===`);
+console.log('  id            chars  lines    ms signals');
+console.log('  ' + '-'.repeat(56));
+for (const r of rows) console.log(fmt(r));
+
+// Sum + medians for the size pillar
+const sizes = rows.filter(r => !r.error).map(r => r.chars);
+sizes.sort((a, b) => a - b);
+const median = sizes[Math.floor(sizes.length / 2)];
+const sum = sizes.reduce((a, b) => a + b, 0);
+console.log(`  ${'-'.repeat(64)}`);
+console.log(`  median=${median}c  total=${sum}c  ` +
+  `manifest=${rows.filter(r => r.hasRouteManifest).length}/${rows.filter(r => !r.error).length}  ` +
+  `top-handler=${rows.filter(r => r.hasTopHandler).length}/${rows.filter(r => !r.error).length}`);
diff --git a/scripts/agent-eval/probe-trace.mjs b/scripts/agent-eval/probe-trace.mjs
new file mode 100644
index 000000000..e6111d936
--- /dev/null
+++ b/scripts/agent-eval/probe-trace.mjs
@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// Probe codegraph_trace against an index using the built dist.
+// Usage: node probe-trace.mjs <repo-with-.codegraph> <from> <to>
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+
+const [, , repo, from, to] = process.argv;
+if (!repo || !from || !to) { console.error('usage: probe-trace.mjs <repo> <from> <to>'); process.exit(1); }
+
+const load = async (rel) => import(pathToFileURL(resolve(rel)).href);
+const idx = await load('dist/index.js');
+const tools = await load('dist/mcp/tools.js');
+const CodeGraph = idx.default?.default ?? idx.default ?? idx.CodeGraph;
+const ToolHandler = tools.ToolHandler ?? tools.default?.ToolHandler;
+
+const cg = CodeGraph.openSync(repo);
+const h = new ToolHandler(cg);
+const res = await h.execute('codegraph_trace', { from, to });
+console.log(res.content?.[0]?.text ?? '(no text)');
+try { cg.close?.(); } catch {}
diff --git a/scripts/agent-eval/redirect-read-hook.sh b/scripts/agent-eval/redirect-read-hook.sh
new file mode 100755
index 000000000..3dce75652
--- /dev/null
+++ b/scripts/agent-eval/redirect-read-hook.sh
@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# PreToolUse(Read) REDIRECT hook — prototype for A/B (P1: get agents off Read and
+# onto codegraph_node during implementation, not just for Q&A).
+#
+# When the agent Reads a SOURCE file, deny it and steer to codegraph_node's
+# file-view, which (as of the Lever-1 change) returns the WHOLE file verbatim
+# WITH line numbers — imports, top-level code, comments and all — PLUS the file's
+# blast radius, in one call. That output is a strict superset of Read, so the
+# redirect is lossless: the agent loses nothing by taking it, and gains who-
+# depends-on-this for the edit it's about to make.
+#
+# Differs from block-read-hook.sh (which steers to explore/node-by-symbol): this
+# names the FILE-VIEW path explicitly (file:"<base>" + includeCode:true), the
+# 1:1 Read replacement we're trying to get picked during implementation.
+#
+# Non-source files (configs, docs, lockfiles, .env) pass through to a real Read.
+# A redirect to a file codegraph hasn't indexed SELF-CORRECTS: the file-view
+# replies "No indexed file matches … Read it directly", so a just-created file
+# never dead-ends — the agent Reads it on the next turn.
+#
+# Wire via:  claude ... --settings <settings-with-this-as-PreToolUse(Read)>
+# Eval artifact only. The production version is an indexed-aware `codegraph`
+# subcommand (cross-platform — no bash/jq — and queries the index so it never
+# bounces a new/un-indexed file), wired opt-in by the installer.
+set -uo pipefail
+input="$(cat)"
+fp="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null)"
+[ -n "$fp" ] || exit 0
+base="$(basename "$fp")"
+
+case "$fp" in
+  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.cjs|*.py|*.go|*.rs|*.java|*.rb|*.php|*.swift|*.kt|*.kts|*.scala|*.c|*.cc|*.cpp|*.h|*.hpp|*.cs|*.lua|*.vue|*.svelte|*.m|*.mm)
+    msg="codegraph has this file indexed (kept in sync on every edit). Call codegraph_node with file:\"$base\" and includeCode:true instead of Read — it returns the WHOLE file verbatim WITH line numbers (imports, top-level code and all — safe to base an Edit on) PLUS which files depend on it, in one call. Treat its output as already-Read; do not Read this file. (If it answers that the file isn't indexed — e.g. you just created it — then Read it directly.)"
+    jq -n --arg m "$msg" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$m}}'
+    exit 0
+    ;;
+esac
+exit 0
diff --git a/scripts/agent-eval/run-agent.sh b/scripts/agent-eval/run-agent.sh
index b599c43b3..abbee8726 100755
--- a/scripts/agent-eval/run-agent.sh
+++ b/scripts/agent-eval/run-agent.sh
@@ -25,7 +25,7 @@ cd "$REPO" || exit 1
 claude -p "$PROMPT" \
   --output-format stream-json --verbose \
   --permission-mode bypassPermissions \
-  --model opus \
+  --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" \
   --max-budget-usd 2 \
   --strict-mcp-config --mcp-config "$MCP_CONFIG" \
   > "$OUT" 2>"$OUT_DIR/run-${LABEL}.err"
diff --git a/scripts/agent-eval/run-all.sh b/scripts/agent-eval/run-all.sh
index 4b40dce9c..b68292591 100755
--- a/scripts/agent-eval/run-all.sh
+++ b/scripts/agent-eval/run-all.sh
@@ -7,6 +7,8 @@
 # Usage: run-all.sh <repo-path> "<question>" [headless|tmux|all]
 # Env:   CG_BIN          codegraph binary (default: command -v codegraph)
 #        AGENT_EVAL_OUT  output dir (default: /tmp/agent-eval)
+#        MODEL / EFFORT  claude model/effort (default: sonnet / high — the
+#                        standing A/B policy; see CLAUDE.md, don't raise)
 set -uo pipefail
 
 REPO="${1:?usage: run-all.sh <repo-path> \"<question>\" [headless|tmux|all]}"
@@ -39,7 +41,7 @@ headless() {
   ( cd "$REPO" && claude -p "$Q" \
       --output-format stream-json --verbose \
       --permission-mode bypassPermissions \
-      --model opus \
+      --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" \
       --max-budget-usd 4 \
       --strict-mcp-config --mcp-config "$cfg" \
       > "$OUT/run-$label.jsonl" 2>"$OUT/run-$label.err" )
@@ -56,11 +58,11 @@ fi
 
 if [ "$MODE" = tmux ] || [ "$MODE" = all ]; then
   echo "############################## INTERACTIVE [with] ##############################"
-  CLAUDE_EXTRA_ARGS="--model opus --strict-mcp-config --mcp-config $OUT/mcp-codegraph.json" \
+  CLAUDE_EXTRA_ARGS="--model ${MODEL:-sonnet} --effort ${EFFORT:-high} --strict-mcp-config --mcp-config $OUT/mcp-codegraph.json" \
     bash "$HARNESS/itrun.sh" "$REPO" "int-with" "$Q" 2>&1 || echo "[itrun WITH failed]"
   echo
   echo "############################## INTERACTIVE [without] ##############################"
-  CLAUDE_EXTRA_ARGS="--model opus --strict-mcp-config --mcp-config $OUT/mcp-empty.json" \
+  CLAUDE_EXTRA_ARGS="--model ${MODEL:-sonnet} --effort ${EFFORT:-high} --strict-mcp-config --mcp-config $OUT/mcp-empty.json" \
     bash "$HARNESS/itrun.sh" "$REPO" "int-without" "$Q" 2>&1 || echo "[itrun WITHOUT failed]"
   echo
 fi
diff --git a/scripts/agent-eval/run-arms.sh b/scripts/agent-eval/run-arms.sh
new file mode 100755
index 000000000..48d4cf856
--- /dev/null
+++ b/scripts/agent-eval/run-arms.sh
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Tool-surface ablation — run ONE repo+question under ONE arm.
+#
+# Arms vary (exposed codegraph tools, trace-first steering). Tools are trimmed
+# SERVER-SIDE via CODEGRAPH_MCP_TOOLS in the MCP config's `env` block, so an
+# ablated tool is genuinely absent from ListTools — no deferred-ToolSearch or
+# denied-call confound (which --disallowedTools would introduce). Steering is
+# injected with --append-system-prompt, so no rebuild of the shipped
+# server-instructions is needed to A/B it.
+#
+#   A control       all tools            no steering
+#   B steer         all tools            trace-first
+#   C no-explore    hide explore         trace-first
+#   D trace-centric hide explore+context trace-first
+#   E control-probe hide explore+context trace-first  (caller passes a NON-flow Q)
+#
+# Usage: run-arms.sh <repo-path> "<question>" <A|B|C|D|E> [run-id]
+set -uo pipefail
+REPO="${1:?repo path}"; Q="${2:?question}"; ARM="${3:?arm A-E}"; RID="${4:-1}"
+CG_BIN="${CG_BIN:-$(command -v codegraph)}"
+OUT="${ARMS_OUT:-/tmp/arms}/$(basename "$REPO")"
+mkdir -p "$OUT"
+[ -n "$CG_BIN" ] || { echo "no codegraph binary (set CG_BIN)"; exit 1; }
+[ -d "$REPO/.codegraph" ] || { echo "no .codegraph index at $REPO"; exit 1; }
+
+STEER='Flow questions ("how does X reach/become Y", "trace the flow", request to handler, state to render): call codegraph_trace(from,to) FIRST — one call returns the whole path. Use codegraph_context/search only to locate the two endpoint symbols if you do not know them. Do NOT reconstruct the path with repeated search/callers/explore.'
+KEEP_NO_EXPLORE="trace,search,node,context,callers,callees,impact,files,status"
+KEEP_TRACE_CENTRIC="trace,search,node,callers,callees,impact,files,status"
+
+case "$ARM" in
+  A|G|H|I) TOOLS="";            STEERING="" ;;  # no steering; H = body-trace, I = body-trace + destination callees (sufficiency)
+  B|F) TOOLS="";                STEERING="$STEER" ;;  # F = B's surface, run on the body-inlining trace build
+  C) TOOLS="$KEEP_NO_EXPLORE";  STEERING="$STEER" ;;
+  D|E) TOOLS="$KEEP_TRACE_CENTRIC"; STEERING="$STEER" ;;
+  *) echo "bad arm '$ARM' (want A|B|C|D|E)"; exit 1 ;;
+esac
+
+CFG="$OUT/mcp-$ARM.json"
+if [ -n "$TOOLS" ]; then
+  cat > "$CFG" <<JSON
+{"mcpServers":{"codegraph":{"command":"$CG_BIN","args":["serve","--mcp","--path","$REPO"],"env":{"CODEGRAPH_MCP_TOOLS":"$TOOLS"}}}}
+JSON
+else
+  cat > "$CFG" <<JSON
+{"mcpServers":{"codegraph":{"command":"$CG_BIN","args":["serve","--mcp","--path","$REPO"]}}}
+JSON
+fi
+
+LOG="$OUT/$ARM-r$RID.jsonl"; ERR="$OUT/$ARM-r$RID.err"
+ARGS=( -p "$Q" --output-format stream-json --verbose
+       --permission-mode bypassPermissions --model "${MODEL:-sonnet}" --effort "${EFFORT:-high}" --max-budget-usd 4
+       --strict-mcp-config --mcp-config "$CFG" )
+[ -n "$STEERING" ] && ARGS+=( --append-system-prompt "$STEERING" )
+
+( cd "$REPO" && claude "${ARGS[@]}" > "$LOG" 2>"$ERR" )
+echo "[$(basename "$REPO") $ARM r$RID] exit $? -> $LOG ($(wc -l < "$LOG" | tr -d ' ') lines)"
diff --git a/scripts/agent-eval/seq-matrix.mjs b/scripts/agent-eval/seq-matrix.mjs
new file mode 100644
index 000000000..9ef3a0667
--- /dev/null
+++ b/scripts/agent-eval/seq-matrix.mjs
@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Mine the surviving A/B stream-json logs (/tmp/ab-matrix/<Cell>/run-headless-*.jsonl)
+// for what the aggregate matrix can't see: the call SEQUENCE and per-call output SIZE.
+//
+// Answers three questions:
+//   1. Trace adoption — on a flow question, does the with-arm actually call codegraph_trace?
+//   2. Payload size vs repo size — is trace path-scoped (tiny, size-independent) while
+//      explore is breadth-scoped (grows with the repo / over-returns on small repos)?
+//   3. Round-trips — num_turns with vs without (the real wall-clock driver).
+//
+// Usage: node scripts/agent-eval/seq-matrix.mjs [/tmp/ab-matrix]
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+const AB = process.argv[2] || '/tmp/ab-matrix';
+const MD = new URL('../../docs/benchmarks/codegraph-ab-matrix.md', import.meta.url).pathname;
+
+// repo -> {lang,size,files} from the published matrix table
+const repoMeta = {};
+if (existsSync(MD)) for (const line of readFileSync(MD, 'utf8').split('\n')) {
+  const m = line.match(/^\|\s*([^|]+?)\s*\|\s*(S|M|L)\s*\|\s*`([^`]+)`\s*\|\s*(\d+)\s*\|/);
+  if (m) repoMeta[m[3]] = { lang: m[1].trim(), size: m[2], files: +m[4] };
+}
+
+const cgShort = (n) => n.replace('mcp__codegraph__codegraph_', '').replace('mcp__codegraph__', '');
+const tag = (n) => n === 'Read' ? 'R' : n === 'Grep' ? 'G' : n === 'Glob' ? 'Gl'
+  : n === 'Bash' ? 'B' : n === 'Task' ? 'Ag' : n === 'ToolSearch' ? 'TS'
+  : n.includes('codegraph') ? cgShort(n) : n;
+
+function parse(file) {
+  if (!existsSync(file)) return null;
+  const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+  const calls = []; let result = null, initCg = 0;
+  for (const l of lines) {
+    let ev; try { ev = JSON.parse(l); } catch { continue; }
+    if (ev.type === 'system' && ev.subtype === 'init') initCg = (ev.tools || []).filter(t => /codegraph/.test(t)).length;
+    if (ev.type === 'assistant') for (const b of (ev.message?.content || [])) if (b.type === 'tool_use') {
+      const i = b.input || {};
+      const q = i.query ?? i.symbol ?? i.task ?? (i.from && i.to ? `${i.from}->${i.to}` : (i.file_path || i.command || ''));
+      calls.push({ id: b.id, name: b.name, q: String(q ?? '').slice(0, 38), out: 0 });
+    }
+    if (ev.type === 'user') for (const b of (ev.message?.content || [])) if (b.type === 'tool_result') {
+      const c = b.content;
+      const txt = typeof c === 'string' ? c : Array.isArray(c) ? c.map(x => x?.text || '').join('') : '';
+      const call = calls.find(k => k.id === b.tool_use_id); if (call) call.out = txt.length;
+    }
+    if (ev.type === 'result') result = ev;
+  }
+  const cg = calls.filter(c => c.name.includes('codegraph'));
+  const perTool = {};
+  for (const c of cg) { const k = cgShort(c.name); (perTool[k] ??= { n: 0, out: 0 }); perTool[k].n++; perTool[k].out += c.out; }
+  const traceIdx = cg.findIndex(c => c.name.includes('trace'));
+  const u = result?.usage || {};
+  return {
+    initCg, cg, perTool,
+    cgSeq: cg.map(c => cgShort(c.name)),
+    seq: calls.map(c => tag(c.name)),
+    reads: calls.filter(c => c.name === 'Read').length,
+    greps: calls.filter(c => c.name === 'Grep').length,
+    cgOut: cg.reduce((s, c) => s + c.out, 0),
+    traceUsed: traceIdx >= 0,
+    afterTrace: traceIdx >= 0 ? cg.slice(traceIdx + 1).map(c => cgShort(c.name)) : null,
+    turns: result?.num_turns ?? null,
+    dur: result?.duration_ms ? Math.round(result.duration_ms / 1000) : null,
+    cost: result?.total_cost_usd || 0,
+  };
+}
+
+const cells = [];
+for (const d of readdirSync(AB)) {
+  const dir = join(AB, d);
+  if (!existsSync(join(dir, 'run-headless-with.jsonl'))) continue;
+  const log = existsSync(join(AB, d + '.log')) ? readFileSync(join(AB, d + '.log'), 'utf8') : '';
+  const repo = (log.match(/repo:\s*\S*\/([^\s/]+)/) || [])[1] || d;
+  const question = (log.match(/question:\s*(.+)/) || [])[1] || '';
+  cells.push({ cell: d, repo, question, ...(repoMeta[repo] || {}),
+    with: parse(join(dir, 'run-headless-with.jsonl')),
+    without: parse(join(dir, 'run-headless-without.jsonl')) });
+}
+cells.sort((a, b) => (a.files || 0) - (b.files || 0));
+
+const k = (n) => (n / 1000).toFixed(1);
+const pad = (s, n) => String(s).padEnd(n);
+
+// ---- per-cell sequence table ----
+console.log('\n=== PER-CELL: with-arm codegraph sequence + payload (sorted by repo size) ===');
+console.log(pad('repo', 22), pad('files', 6), 'trace', pad('cg-call sequence', 40), pad('cgOutK', 7), 'turns(w/wo)');
+for (const c of cells) {
+  const w = c.with;
+  console.log(
+    pad(c.repo, 22), pad(c.files ?? '?', 6),
+    pad(w.traceUsed ? 'YES' : 'no', 5),
+    pad(w.cgSeq.join(',') || '(none)', 40),
+    pad(k(w.cgOut), 7),
+    `${w.turns}/${c.without?.turns}`,
+  );
+}
+
+// ---- trace adoption ----
+const flow = cells; // every matrix question is a canonical flow question by design
+const used = flow.filter(c => c.with.traceUsed);
+console.log(`\n=== TRACE ADOPTION (all ${flow.length} cells are flow questions) ===`);
+console.log(`trace called in ${used.length}/${flow.length} cells`);
+console.log('used trace:', used.map(c => c.repo).join(', ') || '(none)');
+if (used.length) console.log('after-trace follow-ups:', used.map(c => `${c.repo}[${c.with.afterTrace.join(',') || 'none'}]`).join('  '));
+
+// ---- payload size by repo-size tier ----
+const tier = (f) => f < 200 ? 'S(<200)' : f < 2000 ? 'M(<2000)' : 'L(>=2000)';
+const byTier = {};
+for (const c of cells) { (byTier[tier(c.files || 0)] ??= []).push(c.with.cgOut); }
+console.log('\n=== with-arm TOTAL codegraph payload by repo-size tier ===');
+for (const t of ['S(<200)', 'M(<2000)', 'L(>=2000)']) {
+  const a = byTier[t] || []; if (!a.length) continue;
+  const avg = a.reduce((s, x) => s + x, 0) / a.length;
+  console.log(`  ${pad(t, 10)} n=${a.length}  avg cgOut=${k(avg)}K  range ${k(Math.min(...a))}-${k(Math.max(...a))}K`);
+}
+
+// ---- per-tool usage + avg payload (breadth vs path evidence) ----
+const tot = {};
+for (const c of cells) for (const [name, v] of Object.entries(c.with.perTool)) {
+  (tot[name] ??= { n: 0, out: 0 }); tot[name].n += v.n; tot[name].out += v.out;
+}
+console.log('\n=== codegraph tool usage across all cells (n calls, avg payload/call) ===');
+for (const [name, v] of Object.entries(tot).sort((a, b) => b[1].n - a[1].n)) {
+  console.log(`  ${pad(name, 10)} calls=${pad(v.n, 4)} avg=${k(v.out / v.n)}K/call  total=${k(v.out)}K`);
+}
+
+// ---- round-trips ----
+const sum = (arr, f) => arr.reduce((s, x) => s + (f(x) || 0), 0);
+const wTurns = sum(cells, c => c.with.turns), woTurns = sum(cells, c => c.without?.turns);
+const wCalls = sum(cells, c => c.with.cg.length);
+const tsAll = cells.every(c => c.with.seq[0] === 'TS');
+console.log('\n=== ROUND-TRIPS ===');
+console.log(`turns: with=${wTurns}  without=${woTurns}  (${((1 - wTurns / woTurns) * 100).toFixed(0)}% fewer with)`);
+console.log(`avg turns/cell: with=${(wTurns / cells.length).toFixed(1)}  without=${(woTurns / cells.length).toFixed(1)}`);
+console.log(`total codegraph calls=${wCalls} (avg ${(wCalls / cells.length).toFixed(1)}/cell)`);
+console.log(`every with-arm opens with a ToolSearch round-trip (deferred tools): ${tsAll ? 'YES — 1 fixed tax/run' : 'no'}`);
diff --git a/scripts/build-bundle.sh b/scripts/build-bundle.sh
new file mode 100755
index 000000000..120ac9810
--- /dev/null
+++ b/scripts/build-bundle.sh
@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+#
+# Build a self-contained CodeGraph bundle: an official Node runtime + the
+# compiled app + its production deps, so CodeGraph runs with NO system Node and
+# NO native build — node:sqlite is built into the bundled Node. One archive per
+# platform.
+#
+# Because dropping better-sqlite3 left zero native addons, the recipe is pure
+# file-packaging (download the target's Node, copy the app, archive) — so any
+# platform's bundle can be built on any OS. No cross-compile, no native runners.
+#
+# Usage:
+#   scripts/build-bundle.sh <target> [node-version]
+#     target:        darwin-arm64 | darwin-x64 | linux-x64 | linux-arm64
+#                  | win32-x64 | win32-arm64
+#     node-version:  e.g. v24.16.0 (default below; pin for reproducible builds)
+#
+# Output:
+#   unix:    release/codegraph-<target>.tar.gz   (launcher: bin/codegraph)
+#   windows: release/codegraph-<target>.zip      (launcher: bin/codegraph.cmd)
+set -euo pipefail
+
+TARGET="${1:?usage: build-bundle.sh <target> [node-version]}"
+NODE_VERSION="${2:-v24.16.0}"
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+OUT="$ROOT/release"
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+ARCH="${TARGET##*-}"   # x64 | arm64
+OSFAM="${TARGET%-*}"   # darwin | linux | win32
+
+echo "[bundle] target=${TARGET} node=${NODE_VERSION}"
+
+# 1. Download + extract the official Node runtime for the target platform.
+if [ "$OSFAM" = "win32" ]; then
+  NODE_DIST="node-${NODE_VERSION}-win-${ARCH}"
+  NODE_URL="https://nodejs.org/dist/${NODE_VERSION}/${NODE_DIST}.zip"
+  echo "[bundle] downloading ${NODE_URL}"
+  curl -fsSL "$NODE_URL" -o "$WORK/node.zip"
+  if command -v unzip >/dev/null 2>&1; then
+    unzip -q "$WORK/node.zip" -d "$WORK"
+  else
+    tar -xf "$WORK/node.zip" -C "$WORK"   # bsdtar can read zip
+  fi
+  NODE_BIN="$WORK/${NODE_DIST}/node.exe"
+else
+  NODE_DIST="node-${NODE_VERSION}-${TARGET}"
+  NODE_URL="https://nodejs.org/dist/${NODE_VERSION}/${NODE_DIST}.tar.gz"
+  echo "[bundle] downloading ${NODE_URL}"
+  curl -fsSL "$NODE_URL" -o "$WORK/node.tar.gz"
+  tar -xzf "$WORK/node.tar.gz" -C "$WORK"
+  NODE_BIN="$WORK/${NODE_DIST}/bin/node"
+fi
+[ -f "$NODE_BIN" ] || { echo "[bundle] error: node binary not found ($NODE_BIN)" >&2; exit 1; }
+
+# 2. Build the app (compiled JS + copied wasm/schema assets).
+echo "[bundle] building app"
+( cd "$ROOT" && npm run build >/dev/null )
+
+# 3. Stage: app + production-only deps (pure JS/wasm → portable across platforms).
+STAGE="$WORK/codegraph-${TARGET}"
+mkdir -p "$STAGE/lib" "$STAGE/bin"
+cp -R "$ROOT/dist" "$STAGE/lib/dist"
+cp "$ROOT/package.json" "$ROOT/package-lock.json" "$STAGE/lib/"
+echo "[bundle] installing production dependencies"
+( cd "$STAGE/lib" && npm ci --omit=dev --ignore-scripts >/dev/null 2>&1 )
+rm -f "$STAGE/lib/package-lock.json"
+
+# 4. Vendored Node + launcher (the launcher uses the bundled Node by relative
+#    path, so no system Node is ever needed).
+#
+# `--liftoff-only`: keep tree-sitter's large WASM grammars on V8's Liftoff
+# baseline compiler so they never reach the turboshaft optimizing tier, whose
+# per-compilation Zone arena OOMs the whole process (`Fatal process out of
+# memory: Zone`) on Node >= 22 — even with tens of GB free. The flag is read at
+# V8 engine init so it must be on node's command line; the parse worker inherits
+# it. See issues #293/#298 and src/extraction/wasm-runtime-flags.ts. (The CLI
+# also self-relaunches with this flag when launched without it, so non-bundled
+# runs are covered too; passing it here avoids that extra spawn.)
+if [ "$OSFAM" = "win32" ]; then
+  cp "$NODE_BIN" "$STAGE/node.exe"
+  printf '@"%%~dp0..\\node.exe" --liftoff-only "%%~dp0..\\lib\\dist\\bin\\codegraph.js" %%*\r\n' \
+    > "$STAGE/bin/codegraph.cmd"
+else
+  cp "$NODE_BIN" "$STAGE/node"
+  cat > "$STAGE/bin/codegraph" <<'LAUNCH'
+#!/bin/sh
+# Resolve symlinks (e.g. the ~/.local/bin/codegraph link install.sh creates) so
+# we find the real bundle dir, not the symlink's location.
+SELF="$0"
+while [ -L "$SELF" ]; do
+  target="$(readlink "$SELF")"
+  case "$target" in
+    /*) SELF="$target" ;;
+    *) SELF="$(dirname "$SELF")/$target" ;;
+  esac
+done
+DIR="$(cd "$(dirname "$SELF")/.." && pwd)"
+# --liftoff-only: avoid the V8 turboshaft WASM Zone OOM (issues #293/#298).
+exec "$DIR/node" --liftoff-only "$DIR/lib/dist/bin/codegraph.js" "$@"
+LAUNCH
+  chmod +x "$STAGE/bin/codegraph"
+fi
+
+# 5. Archive (.zip for Windows, .tar.gz otherwise).
+mkdir -p "$OUT"
+if [ "$OSFAM" = "win32" ]; then
+  ARCHIVE="$OUT/codegraph-${TARGET}.zip"
+  rm -f "$ARCHIVE"
+  ( cd "$WORK" && zip -rqX "$ARCHIVE" "codegraph-${TARGET}" )
+else
+  ARCHIVE="$OUT/codegraph-${TARGET}.tar.gz"
+  # --no-xattrs: don't embed macOS xattrs that make GNU tar warn on Linux.
+  tar --no-xattrs -czf "$ARCHIVE" -C "$WORK" "codegraph-${TARGET}"
+fi
+echo "[bundle] wrote ${ARCHIVE} ($(du -h "$ARCHIVE" | cut -f1))"
diff --git a/scripts/npm-sdk.js b/scripts/npm-sdk.js
new file mode 100644
index 000000000..169265d8e
--- /dev/null
+++ b/scripts/npm-sdk.js
@@ -0,0 +1,75 @@
+'use strict';
+//
+// Programmatic / embedded SDK entry for @colbymchenry/codegraph (issue #354).
+//
+// The CLI/MCP `bin` (npm-shim.js) execs the per-platform bundle's OWN Node 24 so
+// the tool never depends on the user's runtime. Embedded library consumers are
+// the opposite case: they already run their own Node and just want the compiled
+// API — `require("@colbymchenry/codegraph")` returning the CodeGraph class et al.
+//
+// The compiled library + its production dependencies (web-tree-sitter,
+// tree-sitter-wasms, …) ship INSIDE the per-platform bundle, at
+//   @colbymchenry/codegraph-<platform>-<arch>/lib/dist/index.js
+// (with the deps in the sibling lib/node_modules). Re-exporting that bundle keeps
+// the main package thin — no second 50 MB copy of the grammars — while making the
+// SDK work in the consumer's process. Types are a separate concern: the main
+// package ships its own dist/**/*.d.ts tree (pointed at by `types`), built from
+// the same release so it can never skew from the runtime it re-exports.
+//
+// node:sqlite (Node >= 22.5) is required to OPEN a graph, but only lazily inside
+// the SQLite adapter — so loading this module is safe on older Node, and the
+// node:sqlite requirement surfaces with an actionable error only when a DB is
+// actually opened. Heavy extraction additionally wants the bundled launcher's
+// --liftoff-only flag (the WASM Zone-OOM guard, issues #293/#298); an embedded
+// host that drives large indexing should pass that flag to its own Node.
+
+var path = require('path');
+var os = require('os');
+var fs = require('fs');
+
+var target = process.platform + '-' + process.arch; // e.g. darwin-arm64, linux-x64
+var pkg = '@colbymchenry/codegraph-' + target;
+
+module.exports = require(resolveLibrary());
+
+// Locate the compiled library entry inside the installed per-platform bundle.
+// Throws an actionable error (rather than a bare MODULE_NOT_FOUND) when no bundle
+// is present, so an embedded consumer knows exactly what to install.
+function resolveLibrary() {
+  // 1) The npm-installed optional dependency — the normal case.
+  try {
+    return require.resolve(pkg + '/lib/dist/index.js');
+  } catch (e) {
+    /* fall through to the self-healed cache */
+  }
+
+  // 2) A bundle the CLI shim self-healed from GitHub Releases into the cache
+  //    (issue #303). Same node/lib/bin layout as the npm package. We only REUSE a
+  //    cached bundle here — unlike the CLI shim we never trigger a network
+  //    download from inside require(), which must stay synchronous and cheap.
+  var cached = cachedLibrary();
+  if (cached) return cached;
+
+  throw new Error(
+    'codegraph: the programmatic API is unavailable because the platform bundle\n' +
+    '(' + pkg + ') is not installed.\n' +
+    'The compiled library ships inside that per-platform optional dependency.\n' +
+    'Fixes:\n' +
+    '  - install from the official npm registry so the matching bundle is fetched:\n' +
+    '      npm i @colbymchenry/codegraph --registry=https://registry.npmjs.org\n' +
+    '  - or run the CLI once (e.g. `npx @colbymchenry/codegraph status`) to\n' +
+    '    self-heal the bundle into ~/.codegraph, then require() will find it.'
+  );
+}
+
+function cachedLibrary() {
+  try {
+    var version = require(path.join(__dirname, 'package.json')).version;
+    var base = process.env.CODEGRAPH_INSTALL_DIR || path.join(os.homedir(), '.codegraph');
+    var lib = path.join(base, 'bundles', target + '-' + version, 'lib', 'dist', 'index.js');
+    if (fs.existsSync(lib)) return lib;
+  } catch (e) {
+    /* no readable cache → caller reports the install guidance */
+  }
+  return null;
+}
diff --git a/scripts/npm-shim.js b/scripts/npm-shim.js
new file mode 100755
index 000000000..09b435e5f
--- /dev/null
+++ b/scripts/npm-shim.js
@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+'use strict';
+//
+// npm thin-installer launcher for CodeGraph.
+//
+// The heavy artifact (a vendored Node runtime + the app) ships as a per-platform
+// optionalDependency: @colbymchenry/codegraph-<platform>-<arch>. npm installs
+// only the one matching the host, via each package's `os`/`cpu` fields (the
+// esbuild pattern). This shim — run by the user's OWN Node — locates that bundle
+// and execs its launcher, so the real work always runs on the bundled Node 24
+// (with node:sqlite), regardless of the user's Node version. The user's Node is
+// only ever a launcher; even an ancient version can run this file.
+//
+// Self-heal (issue #303): some registries — notably the npmmirror/cnpm mirrors,
+// and some corporate proxies — don't reliably mirror the per-platform
+// optionalDependencies. npm treats an unfetchable optional dep as success and
+// silently skips it, so the bundle goes missing and every command fails. When
+// the installed bundle can't be resolved, this shim falls back to downloading
+// the matching bundle straight from GitHub Releases — the very archive
+// install.sh uses — into a cache dir, then runs that. Knobs:
+//   CODEGRAPH_NO_DOWNLOAD=1     disable the network fallback (print guidance)
+//   CODEGRAPH_INSTALL_DIR=DIR   cache location (default: ~/.codegraph)
+//   CODEGRAPH_DOWNLOAD_BASE=URL release-download base (for mirrors/air-gapped)
+//
+// Wired up at release time as the main package's `bin`:
+//   "bin": { "codegraph": "npm-shim.js" }
+// with the platform packages listed in `optionalDependencies`.
+
+var childProcess = require('child_process');
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+
+var target = process.platform + '-' + process.arch; // e.g. darwin-arm64, linux-x64
+var pkg = '@colbymchenry/codegraph-' + target;
+var isWindows = process.platform === 'win32';
+var REPO = 'colbymchenry/codegraph';
+
+main().catch(function (e) {
+  process.stderr.write('codegraph: ' + (e && e.message ? e.message : String(e)) + '\n');
+  process.exit(1);
+});
+
+async function main() {
+  // Happy path: the npm-installed optional dependency. Fall back to a download
+  // when the registry didn't deliver it.
+  var resolved = resolveInstalledBundle() || (await selfHealBundle());
+  var res = childProcess.spawnSync(resolved.command, resolved.args, { stdio: 'inherit' });
+  if (res.error) {
+    process.stderr.write('codegraph: ' + res.error.message + '\n');
+    process.exit(1);
+  }
+  process.exit(res.status === null ? 1 : res.status);
+}
+
+// Resolve the launcher from the installed per-platform optionalDependency.
+// Returns {command, args} or null if the package isn't installed.
+function resolveInstalledBundle() {
+  try {
+    if (isWindows) {
+      // Modern Node refuses to spawn the bundle's .cmd directly (EINVAL, the
+      // CVE-2024-27980 hardening on Node 24), so invoke the bundled node.exe
+      // against the app entry point and pass --liftoff-only here.
+      var nodeExe = require.resolve(pkg + '/node.exe');
+      var entry = require.resolve(pkg + '/lib/dist/bin/codegraph.js');
+      return { command: nodeExe, args: liftoff(entry) };
+    }
+    return { command: require.resolve(pkg + '/bin/codegraph'), args: process.argv.slice(2) };
+  } catch (e) {
+    return null;
+  }
+}
+
+// Locate the launcher inside an extracted GitHub bundle directory (same
+// node/lib/bin layout as the npm platform package). Returns {command, args} or
+// null when the directory doesn't hold a usable bundle yet.
+function launcherIn(dir) {
+  if (isWindows) {
+    var nodeExe = path.join(dir, 'node.exe');
+    var entry = path.join(dir, 'lib', 'dist', 'bin', 'codegraph.js');
+    if (fs.existsSync(nodeExe) && fs.existsSync(entry)) {
+      return { command: nodeExe, args: liftoff(entry) };
+    }
+  } else {
+    var launcher = path.join(dir, 'bin', 'codegraph');
+    if (fs.existsSync(launcher)) return { command: launcher, args: process.argv.slice(2) };
+  }
+  return null;
+}
+
+// --liftoff-only keeps tree-sitter's WASM grammars off V8's turboshaft tier to
+// avoid the Zone OOM on Node >= 22 (issues #293/#298). The unix bin/codegraph
+// launcher already passes it; on Windows we invoke node.exe directly so add it.
+function liftoff(entry) {
+  return ['--liftoff-only', entry].concat(process.argv.slice(2));
+}
+
+// Download + cache the platform bundle from GitHub Releases. Returns
+// {command, args}; exits the process with guidance if it can't.
+async function selfHealBundle() {
+  var version = readVersion();
+  var bundlesDir = path.join(process.env.CODEGRAPH_INSTALL_DIR || path.join(os.homedir(), '.codegraph'), 'bundles');
+  var dest = path.join(bundlesDir, target + '-' + version);
+
+  // Already downloaded by a previous run? Use it even when downloads are
+  // disabled — CODEGRAPH_NO_DOWNLOAD blocks fetching, not a cached bundle.
+  var cached = launcherIn(dest);
+  if (cached) return cached;
+
+  if (process.env.CODEGRAPH_NO_DOWNLOAD) {
+    fail('the network fallback is disabled (CODEGRAPH_NO_DOWNLOAD is set).');
+  }
+
+  var asset = 'codegraph-' + target + (isWindows ? '.zip' : '.tar.gz');
+  var base = process.env.CODEGRAPH_DOWNLOAD_BASE || ('https://github.com/' + REPO + '/releases/download');
+  var url = base + '/v' + version + '/' + asset;
+
+  process.stderr.write(
+    'codegraph: platform bundle missing (registry did not provide ' + pkg + ').\n' +
+    'codegraph: downloading ' + asset + ' from GitHub Releases (' + version + ')...\n'
+  );
+
+  // Stage inside bundlesDir so the final rename is on the same filesystem (atomic,
+  // no EXDEV across tmpfs). Strip the archive's top-level codegraph-<target>/ dir.
+  fs.mkdirSync(bundlesDir, { recursive: true });
+  var stage = fs.mkdtempSync(path.join(bundlesDir, '.dl-'));
+  try {
+    var archivePath = path.join(stage, asset);
+    await download(url, archivePath, 6);
+    await verifyChecksum(archivePath, asset, base, version);
+    var extracted = path.join(stage, 'bundle');
+    fs.mkdirSync(extracted);
+    extract(archivePath, extracted);
+
+    var raced = launcherIn(dest); // another process may have finished meanwhile
+    if (raced) { rmrf(stage); return raced; }
+    try {
+      fs.renameSync(extracted, dest);
+    } catch (e) {
+      var other = launcherIn(dest); // lost the race but theirs is valid
+      if (other) { rmrf(stage); return other; }
+      throw e;
+    }
+  } catch (e) {
+    rmrf(stage);
+    fail('download failed (' + e.message + ').\n  URL: ' + url);
+  }
+  rmrf(stage);
+
+  var ready = launcherIn(dest);
+  if (!ready) fail('downloaded bundle is missing its launcher under ' + dest + '.');
+  process.stderr.write('codegraph: bundle ready.\n');
+  return ready;
+}
+
+function readVersion() {
+  try {
+    return require(path.join(__dirname, 'package.json')).version;
+  } catch (e) {
+    fail('could not read this package\'s version to locate a matching release.');
+  }
+}
+
+// GET with manual redirect following (GitHub release URLs redirect to a CDN).
+function download(url, dest, redirectsLeft) {
+  return new Promise(function (resolve, reject) {
+    var https = require('https');
+    // timeout is an idle/inactivity timeout — it won't kill a slow-but-progressing
+    // download, only a stalled connection (so a blocked mirror fails fast with
+    // guidance instead of hanging the user's command forever).
+    var req = https.get(url, { headers: { 'User-Agent': 'codegraph-npm-shim' }, timeout: 30000 }, function (res) {
+      var status = res.statusCode;
+      if (status >= 300 && status < 400 && res.headers.location) {
+        res.resume();
+        if (redirectsLeft <= 0) { reject(new Error('too many redirects')); return; }
+        download(new URL(res.headers.location, url).toString(), dest, redirectsLeft - 1).then(resolve, reject);
+        return;
+      }
+      if (status !== 200) { res.resume(); reject(new Error('HTTP ' + status)); return; }
+      var file = fs.createWriteStream(dest);
+      res.on('error', reject);
+      res.pipe(file);
+      file.on('error', reject);
+      file.on('finish', function () { file.close(function () { resolve(); }); });
+    });
+    req.on('timeout', function () { req.destroy(new Error('connection timed out')); });
+    req.on('error', reject);
+  });
+}
+
+// Best-effort integrity check. When the release publishes a SHA256SUMS file, the
+// downloaded archive MUST match its listed hash or we abort. When that file is
+// absent (older releases) or simply unreachable, we proceed — the archive still
+// arrived from GitHub over TLS. So tampering/corruption is caught, while a
+// missing checksum never breaks an install.
+async function verifyChecksum(archivePath, asset, base, version) {
+  var sumsPath = archivePath + '.SHA256SUMS';
+  try {
+    await download(base + '/v' + version + '/SHA256SUMS', sumsPath, 6);
+  } catch (e) {
+    return; // not published / unreachable → skip
+  }
+  var expected = null;
+  var lines = fs.readFileSync(sumsPath, 'utf8').split('\n');
+  for (var i = 0; i < lines.length; i++) {
+    var m = lines[i].trim().match(/^([0-9a-fA-F]{64})\s+\*?(.+)$/);
+    if (m && path.basename(m[2].trim()) === asset) { expected = m[1].toLowerCase(); break; }
+  }
+  if (!expected) return; // asset not listed → nothing to check
+  var actual = require('crypto').createHash('sha256').update(fs.readFileSync(archivePath)).digest('hex');
+  if (actual !== expected) {
+    throw new Error('checksum mismatch for ' + asset +
+      ' (expected ' + expected.slice(0, 12) + '…, got ' + actual.slice(0, 12) + '…)');
+  }
+  process.stderr.write('codegraph: checksum verified.\n');
+}
+
+// Extract via the system tar — present on macOS, Linux, and Windows 10+
+// (bsdtar reads .zip too). No third-party dependency in the shim.
+function extract(archive, destDir) {
+  var args = isWindows
+    ? ['-xf', archive, '-C', destDir, '--strip-components=1']
+    : ['-xzf', archive, '-C', destDir, '--strip-components=1'];
+  var res = childProcess.spawnSync('tar', args, { stdio: 'ignore' });
+  if (res.error) throw new Error('tar unavailable: ' + res.error.message);
+  if (res.status !== 0) throw new Error('tar exited ' + res.status);
+}
+
+function rmrf(p) {
+  try { fs.rmSync(p, { recursive: true, force: true }); } catch (e) { /* best effort */ }
+}
+
+function fail(reason) {
+  process.stderr.write(
+    'codegraph: no prebuilt bundle for ' + target + '.\n' +
+    (reason ? 'codegraph: ' + reason + '\n' : '') +
+    'Expected the optional package ' + pkg + ' to be installed.\n' +
+    'A registry mirror (e.g. npmmirror/cnpm) that did not mirror the per-platform\n' +
+    'package is the usual cause. Fixes:\n' +
+    '  - install from the official registry:\n' +
+    '      npm i -g @colbymchenry/codegraph --registry=https://registry.npmjs.org\n' +
+    '  - or use the standalone installer (no Node required):\n' +
+    '      curl -fsSL https://raw.githubusercontent.com/' + REPO + '/main/install.sh | sh\n'
+  );
+  process.exit(1);
+}
diff --git a/scripts/pack-npm.sh b/scripts/pack-npm.sh
new file mode 100755
index 000000000..58fc897cb
--- /dev/null
+++ b/scripts/pack-npm.sh
@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+#
+# Assemble the npm thin-installer packages from built bundles (esbuild pattern).
+#
+# Produces, under release/npm/:
+#   codegraph-<target>/   one per built bundle — the vendored Node + app, tagged
+#                         with os/cpu so npm installs only the matching one.
+#   main/                 the @colbymchenry/codegraph shim package: a tiny bin
+#                         that execs the matching platform bundle, with every
+#                         platform package in optionalDependencies.
+#
+# The release pipeline then `npm publish`es each dir. This does NOT touch the
+# repo's package.json — the dev/from-source path keeps working; the *published*
+# main package's shape is generated here.
+#
+# Prereq: run build-bundle.sh for each target first (release/codegraph-*.tar.gz).
+# Usage:  scripts/pack-npm.sh [version]    (default: version from package.json)
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+VERSION="${1:-$(node -p "require('$ROOT/package.json').version")}"
+SCOPE="@colbymchenry"
+REL="$ROOT/release"
+NPM="$REL/npm"
+
+rm -rf "$NPM"
+mkdir -p "$NPM/main"
+
+shopt -s nullglob
+archives=("$REL"/codegraph-*.tar.gz "$REL"/codegraph-*.zip)
+[ ${#archives[@]} -gt 0 ] || { echo "[pack-npm] no bundles in $REL — run build-bundle.sh first" >&2; exit 1; }
+
+targets=()
+for archive in "${archives[@]}"; do
+  fname="$(basename "$archive")"
+  case "$fname" in
+    *.tar.gz) base="${fname%.tar.gz}" ;;   # codegraph-<target>
+    *.zip)    base="${fname%.zip}" ;;
+  esac
+  target="${base#codegraph-}"             # <target>, e.g. darwin-arm64 / win32-x64
+  os="${target%-*}"                       # darwin | linux | win32
+  arch="${target##*-}"                    # arm64 | x64
+  pkgdir="$NPM/$base"
+  mkdir -p "$pkgdir"
+  case "$fname" in
+    *.zip)
+      tmpx="$(mktemp -d)"
+      unzip -q "$archive" -d "$tmpx"
+      mv "$tmpx/codegraph-${target}"/* "$pkgdir"/
+      rm -rf "$tmpx"
+      nodefile="node.exe"
+      ;;
+    *)
+      tar -xzf "$archive" -C "$pkgdir" --strip-components=1
+      nodefile="node"
+      ;;
+  esac
+  VERSION="$VERSION" SCOPE="$SCOPE" TARGET="$target" OSV="$os" ARCHV="$arch" NODEFILE="$nodefile" \
+    node -e '
+      const fs=require("fs");
+      fs.writeFileSync(process.argv[1], JSON.stringify({
+        name: `${process.env.SCOPE}/codegraph-${process.env.TARGET}`,
+        version: process.env.VERSION,
+        description: `CodeGraph self-contained bundle for ${process.env.TARGET}`,
+        os: [process.env.OSV], cpu: [process.env.ARCHV],
+        files: [process.env.NODEFILE, "lib", "bin"],
+        license: "MIT"
+      }, null, 2) + "\n");
+    ' "$pkgdir/package.json"
+  targets+=("$target")
+  echo "[pack-npm] ${SCOPE}/codegraph-${target}@${VERSION}"
+done
+
+# Main shim package.
+#   npm-shim.js  CLI/MCP launcher (execs the bundled Node) — the `bin`.
+#   npm-sdk.js   programmatic/embedded entry (#354): re-exports the installed
+#                platform bundle's compiled library — the `main`.
+#   dist/        the .d.ts tree only (types). The runtime .js stays in the
+#                per-platform bundle so its deps aren't duplicated here.
+cp "$ROOT/scripts/npm-shim.js" "$NPM/main/npm-shim.js"
+cp "$ROOT/scripts/npm-sdk.js" "$NPM/main/npm-sdk.js"
+[ -f "$ROOT/README.md" ] && cp "$ROOT/README.md" "$NPM/main/README.md"
+
+# Ship the type declarations so `types`/`exports.types` resolve. Built from this
+# same release, so they can't skew from the runtime npm-sdk.js re-exports.
+[ -f "$ROOT/dist/index.d.ts" ] || ( echo "[pack-npm] building dist for .d.ts" >&2 && cd "$ROOT" && npm run build >/dev/null )
+ROOT="$ROOT" DEST="$NPM/main" node -e '
+  const fs=require("fs"), path=require("path");
+  const src=path.join(process.env.ROOT,"dist"), dest=path.join(process.env.DEST,"dist");
+  fs.cpSync(src, dest, { recursive:true, filter(s){
+    try { return fs.statSync(s).isDirectory() || s.endsWith(".d.ts"); } catch (e) { return false; }
+  }});
+'
+
+VERSION="$VERSION" SCOPE="$SCOPE" TARGETS="${targets[*]}" \
+  node -e '
+    const fs=require("fs");
+    const opt={};
+    for (const t of process.env.TARGETS.split(/\s+/).filter(Boolean))
+      opt[`${process.env.SCOPE}/codegraph-${t}`]=process.env.VERSION;
+    fs.writeFileSync(process.argv[1], JSON.stringify({
+      name: `${process.env.SCOPE}/codegraph`,
+      version: process.env.VERSION,
+      description: "Local-first code intelligence for AI agents (MCP). Self-contained — bundles its own runtime.",
+      bin: { codegraph: "npm-shim.js" },
+      main: "npm-sdk.js",
+      types: "dist/index.d.ts",
+      exports: {
+        ".": { types: "./dist/index.d.ts", default: "./npm-sdk.js" },
+        "./package.json": "./package.json"
+      },
+      optionalDependencies: opt,
+      files: ["npm-shim.js","npm-sdk.js","dist","README.md"],
+      license: "MIT"
+    }, null, 2) + "\n");
+  ' "$NPM/main/package.json"
+
+echo "[pack-npm] ${SCOPE}/codegraph@${VERSION} (${#targets[@]} platform packages in optionalDependencies)"
+echo "[pack-npm] output: $NPM"
diff --git a/scripts/prepare-release.mjs b/scripts/prepare-release.mjs
new file mode 100644
index 000000000..f37257966
--- /dev/null
+++ b/scripts/prepare-release.mjs
@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+/**
+ * Promote `## [Unreleased]` content into `## [<version>]` in CHANGELOG.md
+ * so the release.yml workflow's `extract-release-notes.mjs <version>` call
+ * picks up everything that landed since the last release.
+ *
+ * **Why this exists:** the release workflow used to do a literal
+ * `extract-release-notes.mjs <version>` lookup with an `[Unreleased]`
+ * fallback. The fallback only triggers if the `[<version>]` block
+ * doesn't exist at all — and in practice maintainers sometimes had a
+ * sparse `[<version>]` block pre-populated (e.g. one early fix
+ * documented before the rest of the work landed). The workflow then
+ * extracted that sparse block, ignoring the much larger `[Unreleased]`
+ * section above it — so the published release notes were missing most
+ * of what shipped. See v0.9.5 for the canonical post-mortem.
+ *
+ * **What it does**, idempotently:
+ *
+ *   Case A — `[<version>]` does not exist yet:
+ *     Rename the `[Unreleased]` header to `[<version>] - <YYYY-MM-DD>`
+ *     and add a fresh empty `## [Unreleased]` block above it. This is
+ *     the common case.
+ *
+ *   Case B — `[<version>]` exists AND `[Unreleased]` has content:
+ *     Merge `[Unreleased]`'s sub-sections (### Added / ### Fixed /
+ *     ### Changed / ### Removed / ### Deprecated / ### Security) into
+ *     the corresponding sub-sections of `[<version>]`. Unmatched
+ *     sub-sections are appended to `[<version>]`. The `[Unreleased]`
+ *     block is then emptied.
+ *
+ *   Case C — `[Unreleased]` has no content:
+ *     No-op. Exit 0. Re-runs of the workflow are safe.
+ *
+ * **Where the date comes from:** for Case A, `<YYYY-MM-DD>` is the
+ * UTC date at run time. Matches the existing CHANGELOG convention.
+ *
+ * **Usage:**
+ *
+ *   node scripts/prepare-release.mjs                # reads version from package.json
+ *   node scripts/prepare-release.mjs 1.2.3          # explicit version
+ *
+ * **Output:**
+ *
+ *   Writes CHANGELOG.md in place. Prints a summary line to stdout
+ *   like `prepare-release: 0.9.5 — promoted 6 Unreleased entries`.
+ *   Exits non-zero on parse failures.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const CHANGELOG_PATH = resolve(process.cwd(), 'CHANGELOG.md');
+
+function readPackageVersion() {
+  const pkg = JSON.parse(readFileSync(resolve(process.cwd(), 'package.json'), 'utf8'));
+  if (!pkg.version) throw new Error('package.json has no "version" field');
+  return pkg.version;
+}
+
+function todayUtcIsoDate() {
+  // YYYY-MM-DD in UTC. Matches the CHANGELOG's existing convention
+  // (the existing dated entries don't disclose a timezone, but UTC is
+  // stable across runners and is what the workflow's runner produces
+  // by default anyway).
+  return new Date().toISOString().slice(0, 10);
+}
+
+/**
+ * Split the CHANGELOG into a header preface + an ordered list of
+ * version blocks `{ header, body[] }`, preserving line content
+ * verbatim so we can re-join without surprises.
+ */
+function parseChangelog(text) {
+  const lines = text.split('\n');
+  const versionHeaderRe = /^## \[([^\]]+)\](?:\s+-\s+(.+))?\s*$/;
+  const preface = [];
+  const blocks = []; // { header: string, name: string, body: string[] }
+  let cur = null;
+  for (const line of lines) {
+    const m = line.match(versionHeaderRe);
+    if (m) {
+      if (cur) blocks.push(cur);
+      cur = { header: line, name: m[1], date: m[2] ?? null, body: [] };
+    } else if (cur) {
+      cur.body.push(line);
+    } else {
+      preface.push(line);
+    }
+  }
+  if (cur) blocks.push(cur);
+  return { preface, blocks };
+}
+
+function joinChangelog({ preface, blocks }) {
+  const parts = [preface.join('\n')];
+  for (const b of blocks) {
+    // Reconstruct: header + body. The block body INCLUDES the blank
+    // line after the header (it was captured verbatim).
+    parts.push([b.header, ...b.body].join('\n'));
+  }
+  return parts.join('\n');
+}
+
+/**
+ * Split a block body into ordered sub-sections keyed by their
+ * `### Heading`. Lines before the first `### Heading` go in
+ * `leading`. Preserves the original (line-array) body inside each
+ * sub-section so we can splice cleanly when merging.
+ */
+function splitSubsections(body) {
+  const subsectionRe = /^### (\w+)\s*$/;
+  const leading = [];
+  const subs = []; // { heading: 'Added' | 'Fixed' | …, headerLine: string, body: string[] }
+  let cur = null;
+  for (const line of body) {
+    const m = line.match(subsectionRe);
+    if (m) {
+      if (cur) subs.push(cur);
+      cur = { heading: m[1], headerLine: line, body: [] };
+    } else if (cur) {
+      cur.body.push(line);
+    } else {
+      leading.push(line);
+    }
+  }
+  if (cur) subs.push(cur);
+  return { leading, subs };
+}
+
+function rebuildBody({ leading, subs }) {
+  const parts = [];
+  if (leading.length) parts.push(leading.join('\n'));
+  for (const s of subs) {
+    parts.push([s.headerLine, ...s.body].join('\n'));
+  }
+  return parts.join('\n').split('\n');
+}
+
+/**
+ * Return true when the block has any meaningful entries (a bullet line
+ * starting with `-`, `*`, or a digit) — vs. being empty / just
+ * whitespace / just sub-section headers with nothing under them.
+ */
+function blockHasContent(body) {
+  for (const line of body) {
+    if (/^\s*([-*]|\d+\.)\s+/.test(line)) return true;
+  }
+  return false;
+}
+
+/**
+ * Trim trailing blank lines from an array of lines, then return.
+ * Keeps the output tidy when merging.
+ */
+function trimTrailingBlank(arr) {
+  let i = arr.length;
+  while (i > 0 && /^\s*$/.test(arr[i - 1])) i--;
+  return arr.slice(0, i);
+}
+
+function main() {
+  const versionArg = process.argv[2];
+  const version = versionArg || readPackageVersion();
+
+  const text = readFileSync(CHANGELOG_PATH, 'utf8');
+  const parsed = parseChangelog(text);
+
+  const unrelIdx = parsed.blocks.findIndex((b) => b.name === 'Unreleased');
+  const verIdx = parsed.blocks.findIndex((b) => b.name === version);
+
+  if (unrelIdx === -1) {
+    console.log(`prepare-release: no [Unreleased] block — nothing to do`);
+    return;
+  }
+
+  const unrel = parsed.blocks[unrelIdx];
+  if (!blockHasContent(unrel.body)) {
+    console.log(`prepare-release: [Unreleased] is empty — nothing to do`);
+    return;
+  }
+
+  if (verIdx === -1) {
+    // Case A — promote Unreleased → [version].
+    const today = todayUtcIsoDate();
+    const promoted = {
+      header: `## [${version}] - ${today}`,
+      name: version,
+      date: today,
+      body: trimTrailingBlank(unrel.body).concat(['']), // single trailing blank
+    };
+    const emptied = {
+      header: `## [Unreleased]`,
+      name: 'Unreleased',
+      date: null,
+      body: ['', ''], // two blank lines for the next round of entries
+    };
+    parsed.blocks.splice(unrelIdx, 1, emptied, promoted);
+    const next = joinChangelog(parsed);
+    writeFileSync(CHANGELOG_PATH, appendLinkRef(next, version));
+    console.log(`prepare-release: ${version} — renamed [Unreleased] to [${version}] - ${today}`);
+    return;
+  }
+
+  // Case B — merge Unreleased sub-sections into the existing
+  // [version] sub-sections. New sub-section headings encountered in
+  // Unreleased that don't exist in [version] get appended.
+  const ver = parsed.blocks[verIdx];
+  const unrelSubs = splitSubsections(unrel.body);
+  const verSubs = splitSubsections(ver.body);
+
+  let merged = 0;
+  for (const us of unrelSubs.subs) {
+    const target = verSubs.subs.find((s) => s.heading === us.heading);
+    const usBody = trimTrailingBlank(us.body);
+    if (usBody.length === 0) continue;
+    if (target) {
+      // Append Unreleased's entries to the end of the version's matching
+      // sub-section, keeping their original ordering. Insert a separating
+      // blank line if the existing sub-section doesn't already end in one.
+      const existing = trimTrailingBlank(target.body);
+      const sep = existing.length && !/^\s*$/.test(existing[existing.length - 1]) ? [''] : [];
+      target.body = existing.concat(sep, usBody, ['']);
+    } else {
+      // Append the whole sub-section to the end.
+      verSubs.subs.push({
+        heading: us.heading,
+        headerLine: us.headerLine,
+        body: usBody.concat(['']),
+      });
+    }
+    merged += usBody.filter((l) => /^\s*([-*]|\d+\.)\s+/.test(l)).length;
+  }
+
+  ver.body = rebuildBody(verSubs);
+  // Empty out Unreleased.
+  unrel.body = ['', ''];
+
+  const merged_text = joinChangelog(parsed);
+  writeFileSync(CHANGELOG_PATH, appendLinkRef(merged_text, version));
+  console.log(`prepare-release: ${version} — merged ${merged} Unreleased entries into existing [${version}] block`);
+}
+
+/**
+ * Append a `[X.Y.Z]: https://github.com/colbymchenry/codegraph/releases/tag/vX.Y.Z`
+ * link reference at the end of the file IF one doesn't already exist. The
+ * link ref is what makes `## [X.Y.Z]` heading text auto-link to its tag in
+ * GitHub's renderer; without it the heading still renders, just unlinked.
+ *
+ * Idempotent. The existing CHANGELOG mixes link refs scattered through the
+ * file and a sorted block at the bottom — we just append at the very end,
+ * which CommonMark accepts regardless.
+ */
+function appendLinkRef(text, version) {
+  const refLine = `[${version}]: https://github.com/colbymchenry/codegraph/releases/tag/v${version}`;
+  // Already there? Look for a line that EQUALS this (anywhere in the file)
+  // to keep idempotency robust against the scattered-vs-block layout.
+  const lines = text.split('\n');
+  if (lines.some((l) => l.trim() === refLine)) return text;
+  // Append, separated by a blank line from the prior content. Preserve a
+  // single trailing newline at EOF.
+  const trailingNewline = text.endsWith('\n') ? '' : '\n';
+  return text + trailingNewline + refLine + '\n';
+}
+
+try {
+  main();
+} catch (err) {
+  console.error(`prepare-release: ${err?.message ?? err}`);
+  process.exit(1);
+}
diff --git a/scripts/release.sh b/scripts/release.sh
deleted file mode 100755
index 9edf8461f..000000000
--- a/scripts/release.sh
+++ /dev/null
@@ -1,68 +0,0 @@
-#!/usr/bin/env bash
-# Tag the current commit with the version in package.json and publish a
-# matching GitHub Release whose body is the corresponding CHANGELOG.md entry.
-#
-# Run AFTER you have:
-#   - bumped package.json
-#   - added a `## [X.Y.Z] - YYYY-MM-DD` block at the top of CHANGELOG.md
-#   - committed, pushed to origin, and run `npm publish`
-#
-# Idempotent: safe to re-run after a partial failure. Skips steps that are
-# already done (tag created, tag pushed, release published).
-#
-# Usage: ./scripts/release.sh
-
-set -euo pipefail
-
-cd "$(dirname "$0")/.."
-
-VERSION=$(node -p "require('./package.json').version")
-TAG="v${VERSION}"
-
-REPO=$(git remote get-url origin | sed -E 's|.*github\.com[:/]||; s|\.git$||')
-if [ -z "${REPO}" ]; then
-  echo "error: could not derive owner/repo from origin remote URL" >&2
-  exit 1
-fi
-
-if ! grep -q "^## \[${VERSION}\]" CHANGELOG.md; then
-  echo "error: no '## [${VERSION}]' entry found in CHANGELOG.md" >&2
-  exit 1
-fi
-
-# Extract notes with paragraph unwrapping — GitHub Releases render with
-# GFM hard-breaks, so the CHANGELOG's hard-wrapped lines would show as
-# visible `<br>` breaks otherwise. The helper joins continuation lines
-# into a single line per bullet.
-NOTES=$(node scripts/extract-release-notes.mjs "${VERSION}")
-
-if [ -z "${NOTES}" ]; then
-  echo "error: failed to extract changelog notes for ${VERSION}" >&2
-  exit 1
-fi
-
-if git rev-parse "${TAG}" >/dev/null 2>&1; then
-  echo "✓ tag ${TAG} already exists locally"
-else
-  echo "→ tagging ${TAG}"
-  git tag "${TAG}"
-fi
-
-if git ls-remote --exit-code --tags origin "${TAG}" >/dev/null 2>&1; then
-  echo "✓ tag ${TAG} already on origin"
-else
-  echo "→ pushing ${TAG} to origin"
-  git push origin "${TAG}"
-fi
-
-if gh release view "${TAG}" --repo "${REPO}" >/dev/null 2>&1; then
-  echo "✓ release ${TAG} already published"
-else
-  echo "→ creating GitHub Release ${TAG} on ${REPO}"
-  gh release create "${TAG}" \
-    --repo "${REPO}" \
-    --title "${TAG}" \
-    --notes "${NOTES}"
-fi
-
-echo "done: https://github.com/${REPO}/releases/tag/${TAG}"
diff --git a/site/.gitignore b/site/.gitignore
new file mode 100644
index 000000000..6240da8b1
--- /dev/null
+++ b/site/.gitignore
@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
diff --git a/site/README.md b/site/README.md
new file mode 100644
index 000000000..1b7f5c3d7
--- /dev/null
+++ b/site/README.md
@@ -0,0 +1,49 @@
+# Starlight Starter Kit: Basics
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+```
+npm create astro@latest -- --template starlight
+```
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro + Starlight project, you'll see the following folders and files:
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   └── docs/
+│   └── content.config.ts
+├── astro.config.mjs
+├── package.json
+└── tsconfig.json
+```
+
+Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+
+Static assets, like favicons, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `npm install`             | Installs dependencies                            |
+| `npm run dev`             | Starts local dev server at `localhost:4321`      |
+| `npm run build`           | Build your production site to `./dist/`          |
+| `npm run preview`         | Preview your build locally, before deploying     |
+| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `npm run astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
diff --git a/site/astro.config.mjs b/site/astro.config.mjs
new file mode 100644
index 000000000..cdea0fcd0
--- /dev/null
+++ b/site/astro.config.mjs
@@ -0,0 +1,95 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+// Project page on GitHub Pages: https://colbymchenry.github.io/codegraph/
+// `site` + `base` make every internal link resolve under the /codegraph/ prefix.
+export default defineConfig({
+	site: 'https://colbymchenry.github.io',
+	base: '/codegraph',
+	integrations: [
+		starlight({
+			title: 'codegraph',
+			description:
+				'A local-first code-intelligence tool that turns any codebase into a queryable knowledge graph for AI coding agents.',
+			favicon: '/favicon.svg',
+			head: [
+				{
+					// Default to the light / paper theme on first visit; the toggle still
+					// lets a visitor switch to (and persist) the dark / ink theme.
+					tag: 'script',
+					content:
+						"if(!localStorage.getItem('starlight-theme')){try{localStorage.setItem('starlight-theme','light')}catch(e){}document.documentElement.dataset.theme='light';document.documentElement.style.colorScheme='light'}",
+				},
+			],
+			social: [
+				{
+					icon: 'github',
+					label: 'GitHub',
+					href: 'https://github.com/colbymchenry/codegraph',
+				},
+			],
+			customCss: [
+				'@fontsource-variable/archivo',
+				'@fontsource/ibm-plex-mono/400.css',
+				'@fontsource/ibm-plex-mono/500.css',
+				'@fontsource/ibm-plex-mono/600.css',
+				'./src/styles/theme.css',
+			],
+			components: {
+				// Wordmark in the docs header.
+				SiteTitle: './src/components/SiteTitle.astro',
+				// Default GitHub icon + a live star-count pill (matches the landing nav).
+				SocialIcons: './src/components/SocialIcons.astro',
+			},
+			expressiveCode: {
+				themes: ['github-light', 'github-dark'],
+				styleOverrides: {
+					borderRadius: '0px',
+					borderColor: '#cdcabf',
+					codeFontFamily: "'IBM Plex Mono', ui-monospace, monospace",
+				},
+			},
+			sidebar: [
+				{
+					label: 'Getting Started',
+					items: [
+						{ label: 'Introduction', slug: 'getting-started/introduction' },
+						{ label: 'Quickstart', slug: 'getting-started/quickstart' },
+						{ label: 'Installation', slug: 'getting-started/installation' },
+						{ label: 'Configuration', slug: 'getting-started/configuration' },
+						{ label: 'Your First Graph', slug: 'getting-started/your-first-graph' },
+						{ label: 'Next Steps', slug: 'getting-started/next-steps' },
+					],
+				},
+				{
+					label: 'Core Concepts',
+					items: [
+						{ label: 'How It Works', slug: 'core-concepts/how-it-works' },
+						{ label: 'The Knowledge Graph', slug: 'core-concepts/knowledge-graph' },
+						{ label: 'Resolution & Frameworks', slug: 'core-concepts/resolution' },
+					],
+				},
+				{
+					label: 'Guides',
+					items: [
+						{ label: 'Indexing a Project', slug: 'guides/indexing' },
+						{ label: 'Framework Routes', slug: 'guides/framework-routes' },
+						{ label: 'Affected Tests in CI', slug: 'guides/affected-tests' },
+					],
+				},
+				{
+					label: 'Reference',
+					items: [
+						{ label: 'MCP Server', slug: 'reference/mcp-server' },
+						{ label: 'Integrations', slug: 'reference/integrations' },
+						{ label: 'CLI', slug: 'reference/cli' },
+						{ label: 'API', slug: 'reference/api' },
+						{ label: 'Languages', slug: 'reference/languages' },
+					],
+				},
+				{ label: 'Troubleshooting', slug: 'troubleshooting' },
+			],
+		}),
+	],
+});
diff --git a/site/package-lock.json b/site/package-lock.json
new file mode 100644
index 000000000..442666fc2
--- /dev/null
+++ b/site/package-lock.json
@@ -0,0 +1,6207 @@
+{
+  "name": "site",
+  "version": "0.0.1",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "site",
+      "version": "0.0.1",
+      "dependencies": {
+        "@astrojs/starlight": "^0.39.2",
+        "@fontsource-variable/archivo": "^5.2.8",
+        "@fontsource/ibm-plex-mono": "^5.2.7",
+        "astro": "^6.3.1",
+        "sharp": "^0.34.5"
+      }
+    },
+    "node_modules/@astrojs/compiler": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@astrojs/compiler/-/compiler-4.0.0.tgz",
+      "integrity": "sha512-eouss7G8ygdZqHuke033VMcVw5HTZUu+PXd/h06DGDUg/jt5btPYPqh66ENWw/mU78rBrf/oeC4oqoBwMtDMNA==",
+      "license": "MIT"
+    },
+    "node_modules/@astrojs/internal-helpers": {
+      "version": "0.9.1",
+      "resolved": "https://registry.npmjs.org/@astrojs/internal-helpers/-/internal-helpers-0.9.1.tgz",
+      "integrity": "sha512-1pWuARqYom/TzuU3+0ZugsTrKlUydWKuULmDqSMTuonY+9IRDUEGKX/8PXQ1nBxRq3w85uGtd9q9SXfqEldMIQ==",
+      "license": "MIT",
+      "dependencies": {
+        "picomatch": "^4.0.4"
+      }
+    },
+    "node_modules/@astrojs/markdown-remark": {
+      "version": "7.1.2",
+      "resolved": "https://registry.npmjs.org/@astrojs/markdown-remark/-/markdown-remark-7.1.2.tgz",
+      "integrity": "sha512-caXZ4Dc2St2dW8luEg22GlP0gupLdztCTQE4EzZOxW1pqWXz9mbeJEuHUkgDYcKWW8tjIHkydYDhWLVoxJ327Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@astrojs/internal-helpers": "0.9.1",
+        "@astrojs/prism": "4.0.2",
+        "github-slugger": "^2.0.0",
+        "hast-util-from-html": "^2.0.3",
+        "hast-util-to-text": "^4.0.2",
+        "js-yaml": "^4.1.1",
+        "mdast-util-definitions": "^6.0.0",
+        "rehype-raw": "^7.0.0",
+        "rehype-stringify": "^10.0.1",
+        "remark-gfm": "^4.0.1",
+        "remark-parse": "^11.0.0",
+        "remark-rehype": "^11.1.2",
+        "remark-smartypants": "^3.0.2",
+        "retext-smartypants": "^6.2.0",
+        "shiki": "^4.0.0",
+        "smol-toml": "^1.6.0",
+        "unified": "^11.0.5",
+        "unist-util-remove-position": "^5.0.0",
+        "unist-util-visit": "^5.1.0",
+        "unist-util-visit-parents": "^6.0.2",
+        "vfile": "^6.0.3"
+      }
+    },
+    "node_modules/@astrojs/mdx": {
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/@astrojs/mdx/-/mdx-5.0.6.tgz",
+      "integrity": "sha512-4dKe0ZMmqujofPNDHahzClkwinn9f8jHPcaXcgdGvPAlboD2mjzkUCofli2cBnxYAkdfhC6d50gBJ8i/cH8gHw==",
+      "license": "MIT",
+      "dependencies": {
+        "@astrojs/markdown-remark": "7.1.2",
+        "@mdx-js/mdx": "^3.1.1",
+        "acorn": "^8.16.0",
+        "es-module-lexer": "^2.0.0",
+        "estree-util-visit": "^2.0.0",
+        "hast-util-to-html": "^9.0.5",
+        "piccolore": "^0.1.3",
+        "rehype-raw": "^7.0.0",
+        "remark-gfm": "^4.0.1",
+        "remark-smartypants": "^3.0.2",
+        "source-map": "^0.7.6",
+        "unist-util-visit": "^5.1.0",
+        "vfile": "^6.0.3"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      },
+      "peerDependencies": {
+        "astro": "^6.0.0"
+      }
+    },
+    "node_modules/@astrojs/prism": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/@astrojs/prism/-/prism-4.0.2.tgz",
+      "integrity": "sha512-KTivpmnz6lDsC6o9H4+DNm2SrE/GHzw8cNAvEJwAvUT+eoaEnn/4NtbDNfRRaxaJHdp15gf+tfHAWiXR4wB3BA==",
+      "license": "MIT",
+      "dependencies": {
+        "prismjs": "^1.30.0"
+      },
+      "engines": {
+        "node": ">=22.12.0"
+      }
+    },
+    "node_modules/@astrojs/sitemap": {
+      "version": "3.7.2",
+      "resolved": "https://registry.npmjs.org/@astrojs/sitemap/-/sitemap-3.7.2.tgz",
+      "integrity": "sha512-PqkzkcZTb5ICiyIR8VoKbIAP/laNRXi5tw616N1Ckk+40oNB8Can1AzVV56lrbC5GKSZFCyJYUVYqVivMisvpA==",
+      "license": "MIT",
+      "dependencies": {
+        "sitemap": "^9.0.0",
+        "stream-replace-string": "^2.0.0",
+        "zod": "^4.3.6"
+      }
+    },
+    "node_modules/@astrojs/starlight": {
+      "version": "0.39.2",
+      "resolved": "https://registry.npmjs.org/@astrojs/starlight/-/starlight-0.39.2.tgz",
+      "integrity": "sha512-vlw+bwnjtf5buCTUtLU7JfV6D3knslxqnspr6LKs6hfRuFZiyr5hT44F7GyDqR9FKANUqFxnIzWM81F1k/kOUA==",
+      "license": "MIT",
+      "dependencies": {
+        "@astrojs/markdown-remark": "^7.1.1",
+        "@astrojs/mdx": "^5.0.4",
+        "@astrojs/sitemap": "^3.7.2",
+        "@pagefind/default-ui": "^1.3.0",
+        "@types/hast": "^3.0.4",
+        "@types/js-yaml": "^4.0.9",
+        "@types/mdast": "^4.0.4",
+        "astro-expressive-code": "^0.42.0",
+        "bcp-47": "^2.1.0",
+        "hast-util-from-html": "^2.0.3",
+        "hast-util-select": "^6.0.4",
+        "hast-util-to-string": "^3.0.1",
+        "hastscript": "^9.0.1",
+        "i18next": "^26.0.7",
+        "js-yaml": "^4.1.1",
+        "klona": "^2.0.6",
+        "magic-string": "^0.30.21",
+        "mdast-util-directive": "^3.1.0",
+        "mdast-util-to-markdown": "^2.1.2",
+        "mdast-util-to-string": "^4.0.0",
+        "pagefind": "^1.3.0",
+        "rehype": "^13.0.2",
+        "rehype-format": "^5.0.1",
+        "remark-directive": "^4.0.0",
+        "ultrahtml": "^1.6.0",
+        "unified": "^11.0.5",
+        "unist-util-visit": "^5.1.0",
+        "vfile": "^6.0.3"
+      },
+      "peerDependencies": {
+        "astro": "^6.0.0"
+      }
+    },
+    "node_modules/@astrojs/telemetry": {
+      "version": "3.3.2",
+      "resolved": "https://registry.npmjs.org/@astrojs/telemetry/-/telemetry-3.3.2.tgz",
+      "integrity": "sha512-j8DNruA8ors99Al39RYZPJK4DC1bKkoNm93mAMuBhY9TCNC4R8n1q7ovFnJ5qhGh5Lsh7pa1gpQVpYpsJPeTHQ==",
+      "license": "MIT",
+      "dependencies": {
+        "ci-info": "^4.4.0",
+        "dset": "^3.1.4",
+        "is-docker": "^4.0.0",
+        "is-wsl": "^3.1.1",
+        "which-pm-runs": "^1.1.0"
+      },
+      "engines": {
+        "node": "18.20.8 || ^20.3.0 || >=22.0.0"
+      }
+    },
+    "node_modules/@babel/helper-string-parser": {
+      "version": "7.27.1",
+      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz",
+      "integrity": "sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/helper-validator-identifier": {
+      "version": "7.28.5",
+      "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz",
+      "integrity": "sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@babel/parser": {
+      "version": "7.29.3",
+      "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.3.tgz",
+      "integrity": "sha512-b3ctpQwp+PROvU/cttc4OYl4MzfJUWy6FZg+PMXfzmt/+39iHVF0sDfqay8TQM3JA2EUOyKcFZt75jWriQijsA==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/types": "^7.29.0"
+      },
+      "bin": {
+        "parser": "bin/babel-parser.js"
+      },
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@babel/types": {
+      "version": "7.29.0",
+      "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.0.tgz",
+      "integrity": "sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/helper-string-parser": "^7.27.1",
+        "@babel/helper-validator-identifier": "^7.28.5"
+      },
+      "engines": {
+        "node": ">=6.9.0"
+      }
+    },
+    "node_modules/@capsizecss/unpack": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/@capsizecss/unpack/-/unpack-4.0.0.tgz",
+      "integrity": "sha512-VERIM64vtTP1C4mxQ5thVT9fK0apjPFobqybMtA1UdUujWka24ERHbRHFGmpbbhp73MhV+KSsHQH9C6uOTdEQA==",
+      "license": "MIT",
+      "dependencies": {
+        "fontkitten": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@clack/core": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/@clack/core/-/core-1.3.1.tgz",
+      "integrity": "sha512-fT1qHVGAag4IEkrupZ6lRRbNCs1vS9P01KB/sG8zKgvUztbYtFBtQpjSITNwooDZ83tpsPzP0mRNs1/KVszCRA==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-wrap-ansi": "^0.2.0",
+        "sisteransi": "^1.0.5"
+      },
+      "engines": {
+        "node": ">= 20.12.0"
+      }
+    },
+    "node_modules/@clack/prompts": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/@clack/prompts/-/prompts-1.4.0.tgz",
+      "integrity": "sha512-S0My7XPGIgpRWMDG8uRqalbgT+a6FmCUdOW+HaIOVVpUPHOb7RrpvjTjiODadKp06fsrVDJZlIzc6yCTp4AnxA==",
+      "license": "MIT",
+      "dependencies": {
+        "@clack/core": "1.3.1",
+        "fast-string-width": "^3.0.2",
+        "fast-wrap-ansi": "^0.2.0",
+        "sisteransi": "^1.0.5"
+      },
+      "engines": {
+        "node": ">= 20.12.0"
+      }
+    },
+    "node_modules/@ctrl/tinycolor": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/@ctrl/tinycolor/-/tinycolor-4.2.0.tgz",
+      "integrity": "sha512-kzyuwOAQnXJNLS9PSyrk0CWk35nWJW/zl/6KvnTBMFK65gm7U1/Z5BqjxeapjZCIhQcM/DsrEmcbRwDyXyXK4A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=14"
+      }
+    },
+    "node_modules/@emnapi/runtime": {
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
+      "integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==",
+      "license": "MIT",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.4.0"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.27.7.tgz",
+      "integrity": "sha512-EKX3Qwmhz1eMdEJokhALr0YiD0lhQNwDqkPYyPhiSwKrh7/4KRjQc04sZ8db+5DVVnZ1LmbNDI1uAMPEUBnQPg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.27.7.tgz",
+      "integrity": "sha512-jbPXvB4Yj2yBV7HUfE2KHe4GJX51QplCN1pGbYjvsyCZbQmies29EoJbkEc+vYuU5o45AfQn37vZlyXy4YJ8RQ==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.27.7.tgz",
+      "integrity": "sha512-62dPZHpIXzvChfvfLJow3q5dDtiNMkwiRzPylSCfriLvZeq0a1bWChrGx/BbUbPwOrsWKMn8idSllklzBy+dgQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.27.7.tgz",
+      "integrity": "sha512-x5VpMODneVDb70PYV2VQOmIUUiBtY3D3mPBG8NxVk5CogneYhkR7MmM3yR/uMdITLrC1ml/NV1rj4bMJuy9MCg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.27.7.tgz",
+      "integrity": "sha512-5lckdqeuBPlKUwvoCXIgI2D9/ABmPq3Rdp7IfL70393YgaASt7tbju3Ac+ePVi3KDH6N2RqePfHnXkaDtY9fkw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.27.7.tgz",
+      "integrity": "sha512-rYnXrKcXuT7Z+WL5K980jVFdvVKhCHhUwid+dDYQpH+qu+TefcomiMAJpIiC2EM3Rjtq0sO3StMV/+3w3MyyqQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-B48PqeCsEgOtzME2GbNM2roU29AMTuOIN91dsMO30t+Ydis3z/3Ngoj5hhnsOSSwNzS+6JppqWsuhTp6E82l2w==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.27.7.tgz",
+      "integrity": "sha512-jOBDK5XEjA4m5IJK3bpAQF9/Lelu/Z9ZcdhTRLf4cajlB+8VEhFFRjWgfy3M1O4rO2GQ/b2dLwCUGpiF/eATNQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.27.7.tgz",
+      "integrity": "sha512-RkT/YXYBTSULo3+af8Ib0ykH8u2MBh57o7q/DAs3lTJlyVQkgQvlrPTnjIzzRPQyavxtPtfg0EopvDyIt0j1rA==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.27.7.tgz",
+      "integrity": "sha512-RZPHBoxXuNnPQO9rvjh5jdkRmVizktkT7TCDkDmQ0W2SwHInKCAV95GRuvdSvA7w4VMwfCjUiPwDi0ZO6Nfe9A==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.27.7.tgz",
+      "integrity": "sha512-GA48aKNkyQDbd3KtkplYWT102C5sn/EZTY4XROkxONgruHPU72l+gW+FfF8tf2cFjeHaRbWpOYa/uRBz/Xq1Pg==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.27.7.tgz",
+      "integrity": "sha512-a4POruNM2oWsD4WKvBSEKGIiWQF8fZOAsycHOt6JBpZ+JN2n2JH9WAv56SOyu9X5IqAjqSIPTaJkqN8F7XOQ5Q==",
+      "cpu": [
+        "loong64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.27.7.tgz",
+      "integrity": "sha512-KabT5I6StirGfIz0FMgl1I+R1H73Gp0ofL9A3nG3i/cYFJzKHhouBV5VWK1CSgKvVaG4q1RNpCTR2LuTVB3fIw==",
+      "cpu": [
+        "mips64el"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.27.7.tgz",
+      "integrity": "sha512-gRsL4x6wsGHGRqhtI+ifpN/vpOFTQtnbsupUF5R5YTAg+y/lKelYR1hXbnBdzDjGbMYjVJLJTd2OFmMewAgwlQ==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.27.7.tgz",
+      "integrity": "sha512-hL25LbxO1QOngGzu2U5xeXtxXcW+/GvMN3ejANqXkxZ/opySAZMrc+9LY/WyjAan41unrR3YrmtTsUpwT66InQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.27.7.tgz",
+      "integrity": "sha512-2k8go8Ycu1Kb46vEelhu1vqEP+UeRVj2zY1pSuPdgvbd5ykAw82Lrro28vXUrRmzEsUV0NzCf54yARIK8r0fdw==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.27.7.tgz",
+      "integrity": "sha512-hzznmADPt+OmsYzw1EE33ccA+HPdIqiCRq7cQeL1Jlq2gb1+OyWBkMCrYGBJ+sxVzve2ZJEVeePbLM2iEIZSxA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-b6pqtrQdigZBwZxAn1UpazEisvwaIDvdbMbmrly7cDTMFnw/+3lVxxCTGOrkPVnsYIosJJXAsILG9XcQS+Yu6w==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.27.7.tgz",
+      "integrity": "sha512-OfatkLojr6U+WN5EDYuoQhtM+1xco+/6FSzJJnuWiUw5eVcicbyK3dq5EeV/QHT1uy6GoDhGbFpprUiHUYggrw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.27.7.tgz",
+      "integrity": "sha512-AFuojMQTxAz75Fo8idVcqoQWEHIXFRbOc1TrVcFSgCZtQfSdc1RXgB3tjOn/krRHENUB4j00bfGjyl2mJrU37A==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.27.7.tgz",
+      "integrity": "sha512-+A1NJmfM8WNDv5CLVQYJ5PshuRm/4cI6WMZRg1by1GwPIQPCTs1GLEUHwiiQGT5zDdyLiRM/l1G0Pv54gvtKIg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.27.7.tgz",
+      "integrity": "sha512-+KrvYb/C8zA9CU/g0sR6w2RBw7IGc5J2BPnc3dYc5VJxHCSF1yNMxTV5LQ7GuKteQXZtspjFbiuW5/dOj7H4Yw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.27.7.tgz",
+      "integrity": "sha512-ikktIhFBzQNt/QDyOL580ti9+5mL/YZeUPKU2ivGtGjdTYoqz6jObj6nOMfhASpS4GU4Q/Clh1QtxWAvcYKamA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.27.7.tgz",
+      "integrity": "sha512-7yRhbHvPqSpRUV7Q20VuDwbjW5kIMwTHpptuUzV+AA46kiPze5Z7qgt6CLCK3pWFrHeNfDd1VKgyP4O+ng17CA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.27.7.tgz",
+      "integrity": "sha512-SmwKXe6VHIyZYbBLJrhOoCJRB/Z1tckzmgTLfFYOfpMAx63BJEaL9ExI8x7v0oAO3Zh6D/Oi1gVxEYr5oUCFhw==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.27.7.tgz",
+      "integrity": "sha512-56hiAJPhwQ1R4i+21FVF7V8kSD5zZTdHcVuRFMW0hn753vVfQN8xlx4uOPT4xoGH0Z/oVATuR82AiqSTDIpaHg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@expressive-code/core": {
+      "version": "0.42.0",
+      "resolved": "https://registry.npmjs.org/@expressive-code/core/-/core-0.42.0.tgz",
+      "integrity": "sha512-MN11+9nfmaC7sYu2BZJXAXqwkBRt8t1xTSqP+Ti1NfTEskgl6xUnzDxoaiQkg0BMzpglA0pys4dpDKquP/cyIw==",
+      "license": "MIT",
+      "dependencies": {
+        "@ctrl/tinycolor": "^4.0.4",
+        "hast-util-select": "^6.0.2",
+        "hast-util-to-html": "^9.0.1",
+        "hast-util-to-text": "^4.0.1",
+        "hastscript": "^9.0.0",
+        "postcss": "^8.4.38",
+        "postcss-nested": "^6.0.1",
+        "unist-util-visit": "^5.0.0",
+        "unist-util-visit-parents": "^6.0.1"
+      }
+    },
+    "node_modules/@expressive-code/plugin-frames": {
+      "version": "0.42.0",
+      "resolved": "https://registry.npmjs.org/@expressive-code/plugin-frames/-/plugin-frames-0.42.0.tgz",
+      "integrity": "sha512-XtkPm+941Uta7Y+81Acv+OA/20F1NJmJhCX6UYGKpqEIGqplNh3PTOhcURp6tcruhlzJcWcvpWy6Oigz3SrjqA==",
+      "license": "MIT",
+      "dependencies": {
+        "@expressive-code/core": "^0.42.0"
+      }
+    },
+    "node_modules/@expressive-code/plugin-shiki": {
+      "version": "0.42.0",
+      "resolved": "https://registry.npmjs.org/@expressive-code/plugin-shiki/-/plugin-shiki-0.42.0.tgz",
+      "integrity": "sha512-PMKey/kLmewttAHQezL+Y5Fx3vVssfDi3+FJOYQQS2mXP3tQspFELtKKAfsXfmSXdToZYgwoO69HJndqfE+09g==",
+      "license": "MIT",
+      "dependencies": {
+        "@expressive-code/core": "^0.42.0",
+        "shiki": "^4.0.2"
+      }
+    },
+    "node_modules/@expressive-code/plugin-text-markers": {
+      "version": "0.42.0",
+      "resolved": "https://registry.npmjs.org/@expressive-code/plugin-text-markers/-/plugin-text-markers-0.42.0.tgz",
+      "integrity": "sha512-l59lUx8fq1v5g6SpmbDjiU0+7IdfbiWnAyRmtTVSpfhyq+nZMN4UcmYyu2b9Mynhzt7Gr+O+cXyEPDNb2AVWVQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@expressive-code/core": "^0.42.0"
+      }
+    },
+    "node_modules/@fontsource-variable/archivo": {
+      "version": "5.2.8",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/archivo/-/archivo-5.2.8.tgz",
+      "integrity": "sha512-R8EotpKHEsKv7d7oiUyjyPENRi2gtAlwdTlzDCOs5BfX/LJP7jvUYJ4fF/qyd3rnbgk3r1xp33g1P57bYJfhzQ==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@fontsource/ibm-plex-mono": {
+      "version": "5.2.7",
+      "resolved": "https://registry.npmjs.org/@fontsource/ibm-plex-mono/-/ibm-plex-mono-5.2.7.tgz",
+      "integrity": "sha512-MKAb8qV+CaiMQn2B0dIi1OV3565NYzp3WN5b4oT6LTkk+F0jR6j0ZN+5BKJiIhffDC3rtBULsYZE65+0018z9w==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
+    "node_modules/@img/colour": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.1.0.tgz",
+      "integrity": "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@img/sharp-darwin-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.5.tgz",
+      "integrity": "sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-arm64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-darwin-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.5.tgz",
+      "integrity": "sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-darwin-x64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-arm64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.4.tgz",
+      "integrity": "sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-darwin-x64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.4.tgz",
+      "integrity": "sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.4.tgz",
+      "integrity": "sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-arm64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.4.tgz",
+      "integrity": "sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-ppc64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.2.4.tgz",
+      "integrity": "sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-riscv64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.2.4.tgz",
+      "integrity": "sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-s390x": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.2.4.tgz",
+      "integrity": "sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linux-x64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.4.tgz",
+      "integrity": "sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.4.tgz",
+      "integrity": "sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-libvips-linuxmusl-x64": {
+      "version": "1.2.4",
+      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.4.tgz",
+      "integrity": "sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-linux-arm": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.5.tgz",
+      "integrity": "sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-arm": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.5.tgz",
+      "integrity": "sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-arm64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-ppc64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.34.5.tgz",
+      "integrity": "sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-ppc64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-riscv64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.34.5.tgz",
+      "integrity": "sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-riscv64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-s390x": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.34.5.tgz",
+      "integrity": "sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-s390x": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linux-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.5.tgz",
+      "integrity": "sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linux-x64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linuxmusl-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.5.tgz",
+      "integrity": "sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linuxmusl-arm64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-linuxmusl-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.5.tgz",
+      "integrity": "sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-libvips-linuxmusl-x64": "1.2.4"
+      }
+    },
+    "node_modules/@img/sharp-wasm32": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.34.5.tgz",
+      "integrity": "sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==",
+      "cpu": [
+        "wasm32"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
+      "optional": true,
+      "dependencies": {
+        "@emnapi/runtime": "^1.7.0"
+      },
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-arm64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.5.tgz",
+      "integrity": "sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-ia32": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.34.5.tgz",
+      "integrity": "sha512-FV9m/7NmeCmSHDD5j4+4pNI8Cp3aW+JvLoXcTUo0IqyjSfAZJ8dIUmijx1qaJsIiU+Hosw6xM5KijAWRJCSgNg==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@img/sharp-win32-x64": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.5.tgz",
+      "integrity": "sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      }
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "license": "MIT"
+    },
+    "node_modules/@mdx-js/mdx": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/@mdx-js/mdx/-/mdx-3.1.1.tgz",
+      "integrity": "sha512-f6ZO2ifpwAQIpzGWaBQT2TXxPv6z3RBzQKpVftEWN78Vl/YweF1uwussDx8ECAXVtr3Rs89fKyG9YlzUs9DyGQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "@types/estree-jsx": "^1.0.0",
+        "@types/hast": "^3.0.0",
+        "@types/mdx": "^2.0.0",
+        "acorn": "^8.0.0",
+        "collapse-white-space": "^2.0.0",
+        "devlop": "^1.0.0",
+        "estree-util-is-identifier-name": "^3.0.0",
+        "estree-util-scope": "^1.0.0",
+        "estree-walker": "^3.0.0",
+        "hast-util-to-jsx-runtime": "^2.0.0",
+        "markdown-extensions": "^2.0.0",
+        "recma-build-jsx": "^1.0.0",
+        "recma-jsx": "^1.0.0",
+        "recma-stringify": "^1.0.0",
+        "rehype-recma": "^1.0.0",
+        "remark-mdx": "^3.0.0",
+        "remark-parse": "^11.0.0",
+        "remark-rehype": "^11.0.0",
+        "source-map": "^0.7.0",
+        "unified": "^11.0.0",
+        "unist-util-position-from-estree": "^2.0.0",
+        "unist-util-stringify-position": "^4.0.0",
+        "unist-util-visit": "^5.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/@oslojs/encoding": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@oslojs/encoding/-/encoding-1.1.0.tgz",
+      "integrity": "sha512-70wQhgYmndg4GCPxPPxPGevRKqTIJ2Nh4OkiMWmDAVYsTQ+Ta7Sq+rPevXyXGdzr30/qZBnyOalCszoMxlyldQ==",
+      "license": "MIT"
+    },
+    "node_modules/@pagefind/darwin-arm64": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/@pagefind/darwin-arm64/-/darwin-arm64-1.5.2.tgz",
+      "integrity": "sha512-MXpI+7HsAdPkvJ0gk9xj9g541BCqBZOBbdwj9g6lB5LCj6kSV6nqDSjzcAJwvOsfu0fjwvC8hQU+ecfhp+MpiQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@pagefind/darwin-x64": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/@pagefind/darwin-x64/-/darwin-x64-1.5.2.tgz",
+      "integrity": "sha512-IojxFWMEJe0RQ7PQ3KXQsPIImNsbpPYpoZ+QUDrL8fAl/O27IX+LVLs74/UzEZy5uA2LD8Nz1AiwKr72vrkZQw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@pagefind/default-ui": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/@pagefind/default-ui/-/default-ui-1.5.2.tgz",
+      "integrity": "sha512-pm1LMnQg8N2B3n2TnjKlhaFihpz6zTiA4HiGQ6/slKO/+8K9CAU5kcjdSSPgpuk1PMuuN4hxLipUIifnrkl3Sg==",
+      "license": "MIT"
+    },
+    "node_modules/@pagefind/freebsd-x64": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/@pagefind/freebsd-x64/-/freebsd-x64-1.5.2.tgz",
+      "integrity": "sha512-7EVzo9+0w+2cbe671BtMj10UlNo83I+HrLVLfRxO731svHRJKUfJ/mo05gU14pe9PCfpKNQT8FS3Xc/oDN6pOA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@pagefind/linux-arm64": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/@pagefind/linux-arm64/-/linux-arm64-1.5.2.tgz",
+      "integrity": "sha512-Ovt9+K35sqzn8H3ZMXGwls4TD/wMJuvRtShHIsmUQREmaxjrDEX7gHckRCrwYJ4XE1H1p6HkLz3wukrAnsfXQw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@pagefind/linux-x64": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/@pagefind/linux-x64/-/linux-x64-1.5.2.tgz",
+      "integrity": "sha512-V+tFqHKXhQKq/WqPBD67AFy7scn1/aZID00ws4fSDd+1daSi5UHR9VVlRrOUYKxn3VuFQYRD7lYXdZK1WED1YA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@pagefind/windows-arm64": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/@pagefind/windows-arm64/-/windows-arm64-1.5.2.tgz",
+      "integrity": "sha512-hN9Nh90fNW61nNRCW9ZyQrAj/mD0eRvmJ8NlTUzkbuW8kIzGJUi3cxjFkEcMZ5h/8FsKWD/VcouZl4yo1F7B6g==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@pagefind/windows-x64": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/@pagefind/windows-x64/-/windows-x64-1.5.2.tgz",
+      "integrity": "sha512-Fa2Iyw7kaDRzGMfNYNUXNW2zbL5FQVDgSOcbDHdzBrDEdpqOqg8TcZ68F22ol6NJ9IGzvUdmeyZypLW5dyhqsg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/pluginutils": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/@rollup/pluginutils/-/pluginutils-5.3.0.tgz",
+      "integrity": "sha512-5EdhGZtnu3V88ces7s53hhfK5KSASnJZv8Lulpc04cWO3REESroJXg73DFsOmgbU2BhwV0E20bu2IDZb3VKW4Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "estree-walker": "^2.0.2",
+        "picomatch": "^4.0.2"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "peerDependencies": {
+        "rollup": "^1.20.0||^2.0.0||^3.0.0||^4.0.0"
+      },
+      "peerDependenciesMeta": {
+        "rollup": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@rollup/pluginutils/node_modules/estree-walker": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-2.0.2.tgz",
+      "integrity": "sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==",
+      "license": "MIT"
+    },
+    "node_modules/@rollup/rollup-android-arm-eabi": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.60.4.tgz",
+      "integrity": "sha512-F5QXMSiFebS9hKZj02XhWLLnRpJ3B3AROP0tWbFBSj+6kCbg5m9j5JoHKd4mmSVy5mS/IMQloYgYxCuJC0fxEQ==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-android-arm64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.60.4.tgz",
+      "integrity": "sha512-GxxTKApUpzRhof7poWvCJHRF51C67u1R7D6DiluBE8wKU1u5GWE8t+v81JvJYtbawoBFX1hLv5Ei4eVjkWokaw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-arm64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.60.4.tgz",
+      "integrity": "sha512-tua0TaJxMOB1R0V0RS1jFZ/RpURFDJIOR2A6jWwQeawuFyS4gBW+rntLRaQd0EQ4bd6Vp44Z2rXW+YYDBsj6IA==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-darwin-x64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.60.4.tgz",
+      "integrity": "sha512-CSKq7MsP+5PFIcydhAiR1K0UhEI1A2jWXVKHPCBZ151yOutENwvnPocgVHkivu2kviURtCEB6zUQw0vs8RrhMg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-arm64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.60.4.tgz",
+      "integrity": "sha512-+O8OkVdyvXMtJEciu2wS/pzm1IxntEEQx3z5TAVy4l32G0etZn+RsA48ARRrFm6Ri8fvqPQfgrvNxSjKAbnd3g==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-freebsd-x64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.60.4.tgz",
+      "integrity": "sha512-Iw3oMskH3AfNuhU0MSN7vNbdi4me/NiYo2azqPz/Le16zHSa+3RRmliCMWWQmh4lcndccU40xcJuTYJZxNo/lw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-gnueabihf": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.60.4.tgz",
+      "integrity": "sha512-EIPRXTVQpHyF8WOo219AD2yEltPehLTcTMz2fn6JsatLYSzQf00hj3rulF+yauOlF9/FtM2WpkT/hJh/KJFGhA==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm-musleabihf": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.60.4.tgz",
+      "integrity": "sha512-J3Yh9PzzF1Ovah2At+lHiGQdsYgArxBbXv/zHfSyaiFQEqvNv7DcW98pCrmdjCZBrqBiKrKKe2V+aaSGWuBe/w==",
+      "cpu": [
+        "arm"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.60.4.tgz",
+      "integrity": "sha512-BFDEZMYfUvLn37ONE1yMBojPxnMlTFsdyNoqncT0qFq1mAfllL+ATMMJd8TeuVMiX84s1KbcxcZbXInmcO2mRg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-arm64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.60.4.tgz",
+      "integrity": "sha512-pc9EYOSlOgdQ2uPl1o9PF6/kLSgaUosia7gOuS8mB69IxJvlclko1MECXysjs5ryez1/5zjYqx3+xYU0TU6R1A==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-gnu/-/rollup-linux-loong64-gnu-4.60.4.tgz",
+      "integrity": "sha512-NxnomyxYerDh5n4iLrNa+sH+Z+U4BMEE46V2PgQ/hoB909i8gV1M5wPojWg9fk1jWpO3IQnOs20K4wyZuFLEFQ==",
+      "cpu": [
+        "loong64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-loong64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loong64-musl/-/rollup-linux-loong64-musl-4.60.4.tgz",
+      "integrity": "sha512-nbJnQ8a3z1mtmrwImCYhc6BGpThAyYVRQxw9uKSKG4wR6aAYno9sVjJ0zaZcW9BPJX1GbrDPf+SvdWjgTuDmnw==",
+      "cpu": [
+        "loong64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-gnu/-/rollup-linux-ppc64-gnu-4.60.4.tgz",
+      "integrity": "sha512-2EU6acNrQLd8tYvo/LXW535wupT3m6fo7HKo6lr7ktQoItxTyOL1ZCR/GfGCuXl2vR+zmfI6eRXkSemafv+iVg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-ppc64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-ppc64-musl/-/rollup-linux-ppc64-musl-4.60.4.tgz",
+      "integrity": "sha512-WeBtoMuaMxiiIrO2IYP3xs6GMWkJP2C0EoT8beTLkUPmzV1i/UcOSVw1d5r9KBODtHKilG5yFxsGRnBbK3wJ4A==",
+      "cpu": [
+        "ppc64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.60.4.tgz",
+      "integrity": "sha512-FJHFfqpKUI3A10WrWKiFbBZ7yVbGT4q4B5o1qKFFojqpaYoh9LrQgqWCmmcxQzVSXYtyB5bzkXrYzlHTs21MYA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-riscv64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.60.4.tgz",
+      "integrity": "sha512-mcEl6CUT5IAUmQf1m9FYSmVqCJlpQ8r8eyftFUHG8i9OhY7BkBXSUdnLH5DOf0wCOjcP9v/QO93zpmF1SptCCw==",
+      "cpu": [
+        "riscv64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-s390x-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.60.4.tgz",
+      "integrity": "sha512-ynt3JxVd2w2buzoKDWIyiV1pJW93xlQic1THVLXilz429oijRpSHivZAgp65KBu+cMcgf1eVVjdnTLvPxgCuoQ==",
+      "cpu": [
+        "s390x"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.60.4.tgz",
+      "integrity": "sha512-Boiz5+MsaROEWDf+GGEwF8VMHGhlUoQMtIPjOgA5fv4osupqTVnJteQNKJwUcnUog2G55jYXH7KZFFiJe0TEzQ==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-linux-x64-musl": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.60.4.tgz",
+      "integrity": "sha512-+qfSY27qIrFfI/Hom04KYFw3GKZSGU4lXus51wsb5EuySfFlWRwjkKWoE9emgRw/ukoT4Udsj4W/+xxG8VbPKg==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@rollup/rollup-openbsd-x64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openbsd-x64/-/rollup-openbsd-x64-4.60.4.tgz",
+      "integrity": "sha512-VpTfOPHgVXEBeeR8hZ2O0F3aSso+JDWqTWmTmzcQKted54IAdUVbxE+j/MVxUsKa8L20HJhv3vUezVPoquqWjA==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ]
+    },
+    "node_modules/@rollup/rollup-openharmony-arm64": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-openharmony-arm64/-/rollup-openharmony-arm64-4.60.4.tgz",
+      "integrity": "sha512-IPOsh5aRYuLv/nkU51X10Bf75Bsf6+gZdx1X+QP5QM6lIJFHHqbHLG0uJn/hWthzo13UAc2umiUorqZy3axoZg==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-arm64-msvc": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.60.4.tgz",
+      "integrity": "sha512-4QzE9E81OohJ/HKzHhsqU+zcYYojVOXlFMs1DdyMT6qXl/niOH7AVElmmEdUNHHS/oRkc++d5k6Vy85zFs0DEw==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-ia32-msvc": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.60.4.tgz",
+      "integrity": "sha512-zTPgT1YuHHcd+Tmx7h8aml0FWFVelV5N54oHow9SLj+GfoDy/huQ+UV396N/C7KpMDMiPspRktzM1/0r1usYEA==",
+      "cpu": [
+        "ia32"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-gnu": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-gnu/-/rollup-win32-x64-gnu-4.60.4.tgz",
+      "integrity": "sha512-DRS4G7mi9lJxqEDezIkKCaUIKCrLUUDCUaCsTPCi/rtqaC6D/jjwslMQyiDU50Ka0JKpeXeRBFBAXwArY52vBw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@rollup/rollup-win32-x64-msvc": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.60.4.tgz",
+      "integrity": "sha512-QVTUovf40zgTqlFVrKA1uXMVvU2QWEFWfAH8Wdc48IxLvrJMQVMBRjuQyUpzZCDkakImib9eVazbWlC6ksWtJw==",
+      "cpu": [
+        "x64"
+      ],
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@shikijs/core": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-4.1.0.tgz",
+      "integrity": "sha512-jLJtSJeuFffqX6/inRE1zqU5aFv2hrszvYgq3OjbAgFRZiWv7abKMDdQzYxuSDfmUPQozZvI/kuy6VMTvnvqTQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/primitive": "4.1.0",
+        "@shikijs/types": "4.1.0",
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "@types/hast": "^3.0.4",
+        "hast-util-to-html": "^9.0.5"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/engine-javascript": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-4.1.0.tgz",
+      "integrity": "sha512-YquhawCUgaBfhsS72e2Y/dI59gCBNPHu3fEO/tvLaXrTssxZrY5ddjtNLTwndrMgPo8b3IscE+xoICDzpTmlFQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "4.1.0",
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "oniguruma-to-es": "^4.3.6"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/engine-oniguruma": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-4.1.0.tgz",
+      "integrity": "sha512-axLpjVs45YBvvINa+dJF+NPW+KtFkNXsFr4SDw2BMj9GdeMnGxVB9PQb2xXlJYovslt/nz6giedAyOANkfc7hg==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "4.1.0",
+        "@shikijs/vscode-textmate": "^10.0.2"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/langs": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/langs/-/langs-4.1.0.tgz",
+      "integrity": "sha512-nwOMruEkbgdZfQ/b8CgpNBVOpvG1k0N5tbmgiFeqsan401+x3ILqlzZJowSla4Agmq4hG2Uf2wh5jLTEhR8VSg==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "4.1.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/primitive": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/primitive/-/primitive-4.1.0.tgz",
+      "integrity": "sha512-zx2/2Uwj2q9X3KSyYREEhXO23xBw5WUhP4orK2lE4r+t9JGITmEe0JH+wPmJhqHpOT2bRRs6lAL945+LDvOAGw==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "4.1.0",
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "@types/hast": "^3.0.4"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/themes": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/themes/-/themes-4.1.0.tgz",
+      "integrity": "sha512-emCcTnUM7yO2wltYbaxm+yLvcCI4+h8XBKc4KmJ7EZUXoSGjcCHifkI//R4OFit9ewpg7H2/9tjOuXrT2v/Knw==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/types": "4.1.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/types": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-4.1.0.tgz",
+      "integrity": "sha512-3EQWX54fMpniOrDblzAhiwiJwpiTMW6+B9DWyUd9ska483tbayFYuw47UxwuPknI31bKnySfVQ/QW+jFL4rFdA==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "@types/hast": "^3.0.4"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/@shikijs/vscode-textmate": {
+      "version": "10.0.2",
+      "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-10.0.2.tgz",
+      "integrity": "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/debug": {
+      "version": "4.1.13",
+      "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz",
+      "integrity": "sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/ms": "*"
+      }
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.9",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
+      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/estree-jsx": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/@types/estree-jsx/-/estree-jsx-1.0.5.tgz",
+      "integrity": "sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "*"
+      }
+    },
+    "node_modules/@types/hast": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz",
+      "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "*"
+      }
+    },
+    "node_modules/@types/js-yaml": {
+      "version": "4.0.9",
+      "resolved": "https://registry.npmjs.org/@types/js-yaml/-/js-yaml-4.0.9.tgz",
+      "integrity": "sha512-k4MGaQl5TGo/iipqb2UDG2UwjXziSWkh0uysQelTlJpX1qGlpUZYm8PnO4DxG1qBomtJUdYJ6qR6xdIah10JLg==",
+      "license": "MIT"
+    },
+    "node_modules/@types/mdast": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz",
+      "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "*"
+      }
+    },
+    "node_modules/@types/mdx": {
+      "version": "2.0.13",
+      "resolved": "https://registry.npmjs.org/@types/mdx/-/mdx-2.0.13.tgz",
+      "integrity": "sha512-+OWZQfAYyio6YkJb3HLxDrvnx6SWWDbC0zVPfBRzUk0/nqoDyf6dNxQi3eArPe8rJ473nobTMQ/8Zk+LxJ+Yuw==",
+      "license": "MIT"
+    },
+    "node_modules/@types/ms": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz",
+      "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==",
+      "license": "MIT"
+    },
+    "node_modules/@types/nlcst": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/@types/nlcst/-/nlcst-2.0.3.tgz",
+      "integrity": "sha512-vSYNSDe6Ix3q+6Z7ri9lyWqgGhJTmzRjZRqyq15N0Z/1/UnVsno9G/N40NBijoYx2seFDIl0+B2mgAb9mezUCA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "*"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "24.12.4",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-24.12.4.tgz",
+      "integrity": "sha512-GUUEShf+PBCGW2KaXwcIt3Yk+e3pkKwWKb9GSyM9WQVE+ep2jzmHdGsHzu4wgcZy5fN9FBdVzjpBQsYlpfpgLA==",
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~7.16.0"
+      }
+    },
+    "node_modules/@types/sax": {
+      "version": "1.2.7",
+      "resolved": "https://registry.npmjs.org/@types/sax/-/sax-1.2.7.tgz",
+      "integrity": "sha512-rO73L89PJxeYM3s3pPPjiPgVVcymqU490g0YO5n5By0k2Erzj6tay/4lr1CHAAU4JyOWd1rpQ8bCf6cZfHU96A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*"
+      }
+    },
+    "node_modules/@types/unist": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz",
+      "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==",
+      "license": "MIT"
+    },
+    "node_modules/@ungap/structured-clone": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.1.tgz",
+      "integrity": "sha512-mUFwbeTqrVgDQxFveS+df2yfap6iuP20NAKAsBt5jDEoOTDew+zwLAOilHCeQJOVSvmgCX4ogqIrA0mnyr08yQ==",
+      "license": "ISC"
+    },
+    "node_modules/acorn": {
+      "version": "8.16.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
+      "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
+      "license": "MIT",
+      "peer": true,
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/acorn-jsx": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz",
+      "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==",
+      "license": "MIT",
+      "peerDependencies": {
+        "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      }
+    },
+    "node_modules/anymatch": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz",
+      "integrity": "sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==",
+      "license": "ISC",
+      "dependencies": {
+        "normalize-path": "^3.0.0",
+        "picomatch": "^2.0.4"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/anymatch/node_modules/picomatch": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
+      "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/arg": {
+      "version": "5.0.2",
+      "resolved": "https://registry.npmjs.org/arg/-/arg-5.0.2.tgz",
+      "integrity": "sha512-PYjyFOLKQ9y57JvQ6QLo8dAgNqswh8M1RMJYdQduT6xbWSgK36P/Z/v+p888pM69jMMfS8Xd8F6I1kQ/I9HUGg==",
+      "license": "MIT"
+    },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "license": "Python-2.0"
+    },
+    "node_modules/aria-query": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.2.tgz",
+      "integrity": "sha512-COROpnaoap1E2F000S62r6A60uHZnmlvomhfyT2DlTcrY1OrBKn2UhH7qn5wTC9zMvD0AY7csdPSNwKP+7WiQw==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/array-iterate": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/array-iterate/-/array-iterate-2.0.1.tgz",
+      "integrity": "sha512-I1jXZMjAgCMmxT4qxXfPXa6SthSoE8h6gkSI9BGGNv8mP8G/v0blc+qFnZu6K42vTOiuME596QaLO0TP3Lk0xg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/astring": {
+      "version": "1.9.0",
+      "resolved": "https://registry.npmjs.org/astring/-/astring-1.9.0.tgz",
+      "integrity": "sha512-LElXdjswlqjWrPpJFg1Fx4wpkOCxj1TDHlSV4PlaRxHGWko024xICaa97ZkMfs6DRKlCguiAI+rbXv5GWwXIkg==",
+      "license": "MIT",
+      "bin": {
+        "astring": "bin/astring"
+      }
+    },
+    "node_modules/astro": {
+      "version": "6.3.7",
+      "resolved": "https://registry.npmjs.org/astro/-/astro-6.3.7.tgz",
+      "integrity": "sha512-zIeDRrI0qNgN1lcCjNqt6/IVCVej7VwSa326cO8uP9BOk1cg4QuffhLnOn2gCgWQr32/wxpSRFfXiLKHglu1Tw==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@astrojs/compiler": "^4.0.0",
+        "@astrojs/internal-helpers": "0.9.1",
+        "@astrojs/markdown-remark": "7.1.2",
+        "@astrojs/telemetry": "3.3.2",
+        "@capsizecss/unpack": "^4.0.0",
+        "@clack/prompts": "^1.1.0",
+        "@oslojs/encoding": "^1.1.0",
+        "@rollup/pluginutils": "^5.3.0",
+        "aria-query": "^5.3.2",
+        "axobject-query": "^4.1.0",
+        "ci-info": "^4.4.0",
+        "clsx": "^2.1.1",
+        "common-ancestor-path": "^2.0.0",
+        "cookie": "^1.1.1",
+        "devalue": "^5.6.3",
+        "diff": "^8.0.3",
+        "dset": "^3.1.4",
+        "es-module-lexer": "^2.0.0",
+        "esbuild": "^0.27.3",
+        "flattie": "^1.1.1",
+        "fontace": "~0.4.1",
+        "get-tsconfig": "5.0.0-beta.4",
+        "github-slugger": "^2.0.0",
+        "html-escaper": "3.0.3",
+        "http-cache-semantics": "^4.2.0",
+        "js-yaml": "^4.1.1",
+        "jsonc-parser": "^3.3.1",
+        "magic-string": "^0.30.21",
+        "magicast": "^0.5.2",
+        "mrmime": "^2.0.1",
+        "neotraverse": "^0.6.18",
+        "obug": "^2.1.1",
+        "p-limit": "^7.3.0",
+        "p-queue": "^9.1.0",
+        "package-manager-detector": "^1.6.0",
+        "piccolore": "^0.1.3",
+        "picomatch": "^4.0.4",
+        "rehype": "^13.0.2",
+        "semver": "^7.7.4",
+        "shiki": "^4.0.2",
+        "smol-toml": "^1.6.0",
+        "svgo": "^4.0.1",
+        "tinyclip": "^0.1.12",
+        "tinyexec": "^1.0.4",
+        "tinyglobby": "^0.2.15",
+        "ultrahtml": "^1.6.0",
+        "unifont": "~0.7.4",
+        "unist-util-visit": "^5.1.0",
+        "unstorage": "^1.17.5",
+        "vfile": "^6.0.3",
+        "vite": "^7.3.2",
+        "vitefu": "^1.1.2",
+        "xxhash-wasm": "^1.1.0",
+        "yargs-parser": "^22.0.0",
+        "zod": "^4.3.6"
+      },
+      "bin": {
+        "astro": "bin/astro.mjs"
+      },
+      "engines": {
+        "node": ">=22.12.0",
+        "npm": ">=9.6.5",
+        "pnpm": ">=7.1.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/astrodotbuild"
+      },
+      "optionalDependencies": {
+        "sharp": "^0.34.0"
+      }
+    },
+    "node_modules/astro-expressive-code": {
+      "version": "0.42.0",
+      "resolved": "https://registry.npmjs.org/astro-expressive-code/-/astro-expressive-code-0.42.0.tgz",
+      "integrity": "sha512-aiTePi2Cn0mJPYWZSzP1GcxCinX9mNtJyCCshVVPSg1yRwM7ADvFJOx0FnS440M9t65hp8JH//dc2qr22Bm4ag==",
+      "license": "MIT",
+      "dependencies": {
+        "rehype-expressive-code": "^0.42.0"
+      },
+      "peerDependencies": {
+        "astro": "^4.0.0-beta || ^5.0.0-beta || ^3.3.0 || ^6.0.0-beta"
+      }
+    },
+    "node_modules/axobject-query": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/axobject-query/-/axobject-query-4.1.0.tgz",
+      "integrity": "sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">= 0.4"
+      }
+    },
+    "node_modules/bail": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/bail/-/bail-2.0.2.tgz",
+      "integrity": "sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/bcp-47": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/bcp-47/-/bcp-47-2.1.0.tgz",
+      "integrity": "sha512-9IIS3UPrvIa1Ej+lVDdDwO7zLehjqsaByECw0bu2RRGP73jALm6FYbzI5gWbgHLvNdkvfXB5YrSbocZdOS0c0w==",
+      "license": "MIT",
+      "dependencies": {
+        "is-alphabetical": "^2.0.0",
+        "is-alphanumerical": "^2.0.0",
+        "is-decimal": "^2.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/bcp-47-match": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/bcp-47-match/-/bcp-47-match-2.0.3.tgz",
+      "integrity": "sha512-JtTezzbAibu8G0R9op9zb3vcWZd9JF6M0xOYGPn0fNCd7wOpRB1mU2mH9T8gaBGbAAyIIVgB2G7xG0GP98zMAQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/boolbase": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/boolbase/-/boolbase-1.0.0.tgz",
+      "integrity": "sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==",
+      "license": "ISC"
+    },
+    "node_modules/ccount": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz",
+      "integrity": "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/character-entities": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/character-entities/-/character-entities-2.0.2.tgz",
+      "integrity": "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/character-entities-html4": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/character-entities-html4/-/character-entities-html4-2.1.0.tgz",
+      "integrity": "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/character-entities-legacy": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz",
+      "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/character-reference-invalid": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/character-reference-invalid/-/character-reference-invalid-2.0.1.tgz",
+      "integrity": "sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/chokidar": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/chokidar/-/chokidar-5.0.0.tgz",
+      "integrity": "sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw==",
+      "license": "MIT",
+      "dependencies": {
+        "readdirp": "^5.0.0"
+      },
+      "engines": {
+        "node": ">= 20.19.0"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/ci-info": {
+      "version": "4.4.0",
+      "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-4.4.0.tgz",
+      "integrity": "sha512-77PSwercCZU2Fc4sX94eF8k8Pxte6JAwL4/ICZLFjJLqegs7kCuAsqqj/70NQF6TvDpgFjkubQB2FW2ZZddvQg==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/sibiraj-s"
+        }
+      ],
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/clsx": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
+      "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/collapse-white-space": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/collapse-white-space/-/collapse-white-space-2.1.0.tgz",
+      "integrity": "sha512-loKTxY1zCOuG4j9f6EPnuyyYkf58RnhhWTvRoZEokgB+WbdXehfjFviyOVYkqzEWz1Q5kRiZdBYS5SwxbQYwzw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/comma-separated-tokens": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-2.0.3.tgz",
+      "integrity": "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/commander": {
+      "version": "11.1.0",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-11.1.0.tgz",
+      "integrity": "sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/common-ancestor-path": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/common-ancestor-path/-/common-ancestor-path-2.0.0.tgz",
+      "integrity": "sha512-dnN3ibLeoRf2HNC+OlCiNc5d2zxbLJXOtiZUudNFSXZrNSydxcCsSpRzXwfu7BBWCIfHPw+xTayeBvJCP/D8Ng==",
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": ">= 18"
+      }
+    },
+    "node_modules/cookie": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz",
+      "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
+    "node_modules/cookie-es": {
+      "version": "1.2.3",
+      "resolved": "https://registry.npmjs.org/cookie-es/-/cookie-es-1.2.3.tgz",
+      "integrity": "sha512-lXVyvUvrNXblMqzIRrxHb57UUVmqsSWlxqt3XIjCkUP0wDAf6uicO6KMbEgYrMNtEvWgWHwe42CKxPu9MYAnWw==",
+      "license": "MIT"
+    },
+    "node_modules/crossws": {
+      "version": "0.3.5",
+      "resolved": "https://registry.npmjs.org/crossws/-/crossws-0.3.5.tgz",
+      "integrity": "sha512-ojKiDvcmByhwa8YYqbQI/hg7MEU0NC03+pSdEq4ZUnZR9xXpwk7E43SMNGkn+JxJGPFtNvQ48+vV2p+P1ml5PA==",
+      "license": "MIT",
+      "dependencies": {
+        "uncrypto": "^0.1.3"
+      }
+    },
+    "node_modules/css-select": {
+      "version": "5.2.2",
+      "resolved": "https://registry.npmjs.org/css-select/-/css-select-5.2.2.tgz",
+      "integrity": "sha512-TizTzUddG/xYLA3NXodFM0fSbNizXjOKhqiQQwvhlspadZokn1KDy0NZFS0wuEubIYAV5/c1/lAr0TaaFXEXzw==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "boolbase": "^1.0.0",
+        "css-what": "^6.1.0",
+        "domhandler": "^5.0.2",
+        "domutils": "^3.0.1",
+        "nth-check": "^2.0.1"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/fb55"
+      }
+    },
+    "node_modules/css-selector-parser": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/css-selector-parser/-/css-selector-parser-3.3.0.tgz",
+      "integrity": "sha512-Y2asgMGFqJKF4fq4xHDSlFYIkeVfRsm69lQC1q9kbEsH5XtnINTMrweLkjYMeaUgiXBy/uvKeO/a1JHTNnmB2g==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/mdevils"
+        },
+        {
+          "type": "patreon",
+          "url": "https://patreon.com/mdevils"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/css-tree": {
+      "version": "3.2.1",
+      "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-3.2.1.tgz",
+      "integrity": "sha512-X7sjQzceUhu1u7Y/ylrRZFU2FS6LRiFVp6rKLPg23y3x3c3DOKAwuXGDp+PAGjh6CSnCjYeAul8pcT8bAl+lSA==",
+      "license": "MIT",
+      "dependencies": {
+        "mdn-data": "2.27.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0"
+      }
+    },
+    "node_modules/css-what": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/css-what/-/css-what-6.2.2.tgz",
+      "integrity": "sha512-u/O3vwbptzhMs3L1fQE82ZSLHQQfto5gyZzwteVIEyeaY5Fc7R4dapF/BvRoSYFeqfBk4m0V1Vafq5Pjv25wvA==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">= 6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/fb55"
+      }
+    },
+    "node_modules/cssesc": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/cssesc/-/cssesc-3.0.0.tgz",
+      "integrity": "sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==",
+      "license": "MIT",
+      "bin": {
+        "cssesc": "bin/cssesc"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/csso": {
+      "version": "5.0.5",
+      "resolved": "https://registry.npmjs.org/csso/-/csso-5.0.5.tgz",
+      "integrity": "sha512-0LrrStPOdJj+SPCCrGhzryycLjwcgUSHBtxNA8aIDxf0GLsRh1cKYhB00Gd1lDOS4yGH69+SNn13+TWbVHETFQ==",
+      "license": "MIT",
+      "dependencies": {
+        "css-tree": "~2.2.0"
+      },
+      "engines": {
+        "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0",
+        "npm": ">=7.0.0"
+      }
+    },
+    "node_modules/csso/node_modules/css-tree": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/css-tree/-/css-tree-2.2.1.tgz",
+      "integrity": "sha512-OA0mILzGc1kCOCSJerOeqDxDQ4HOh+G8NbOJFOTgOCzpw7fCBubk0fEyxp8AgOL/jvLgYA/uV0cMbe43ElF1JA==",
+      "license": "MIT",
+      "dependencies": {
+        "mdn-data": "2.0.28",
+        "source-map-js": "^1.0.1"
+      },
+      "engines": {
+        "node": "^10 || ^12.20.0 || ^14.13.0 || >=15.0.0",
+        "npm": ">=7.0.0"
+      }
+    },
+    "node_modules/csso/node_modules/mdn-data": {
+      "version": "2.0.28",
+      "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.0.28.tgz",
+      "integrity": "sha512-aylIc7Z9y4yzHYAJNuESG3hfhC+0Ibp/MAMiaOZgNv4pmEdFyfZhhhny4MNiAfWdBQ1RQ2mfDWmM1x8SvGyp8g==",
+      "license": "CC0-1.0"
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/decode-named-character-reference": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.3.0.tgz",
+      "integrity": "sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==",
+      "license": "MIT",
+      "dependencies": {
+        "character-entities": "^2.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/defu": {
+      "version": "6.1.7",
+      "resolved": "https://registry.npmjs.org/defu/-/defu-6.1.7.tgz",
+      "integrity": "sha512-7z22QmUWiQ/2d0KkdYmANbRUVABpZ9SNYyH5vx6PZ+nE5bcC0l7uFvEfHlyld/HcGBFTL536ClDt3DEcSlEJAQ==",
+      "license": "MIT"
+    },
+    "node_modules/dequal": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz",
+      "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/destr": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/destr/-/destr-2.0.5.tgz",
+      "integrity": "sha512-ugFTXCtDZunbzasqBxrK93Ik/DRYsO6S/fedkWEMKqt04xZ4csmnmwGDBAb07QWNaGMAmnTIemsYZCksjATwsA==",
+      "license": "MIT"
+    },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/devalue": {
+      "version": "5.8.1",
+      "resolved": "https://registry.npmjs.org/devalue/-/devalue-5.8.1.tgz",
+      "integrity": "sha512-4CXDYRBGqN+57wVJkuXBYmpAVUSg3L6JAQa/DFqm238G73E1wuyc/JhGQJzN7vUf/CMphYau2zXbfWzDR5aTEw==",
+      "license": "MIT"
+    },
+    "node_modules/devlop": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz",
+      "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==",
+      "license": "MIT",
+      "dependencies": {
+        "dequal": "^2.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/diff": {
+      "version": "8.0.4",
+      "resolved": "https://registry.npmjs.org/diff/-/diff-8.0.4.tgz",
+      "integrity": "sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.3.1"
+      }
+    },
+    "node_modules/direction": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/direction/-/direction-2.0.1.tgz",
+      "integrity": "sha512-9S6m9Sukh1cZNknO1CWAr2QAWsbKLafQiyM5gZ7VgXHeuaoUwffKN4q6NC4A/Mf9iiPlOXQEKW/Mv/mh9/3YFA==",
+      "license": "MIT",
+      "bin": {
+        "direction": "cli.js"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/dom-serializer": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/dom-serializer/-/dom-serializer-2.0.0.tgz",
+      "integrity": "sha512-wIkAryiqt/nV5EQKqQpo3SToSOV9J0DnbJqwK7Wv/Trc92zIAYZ4FlMu+JPFW1DfGFt81ZTCGgDEabffXeLyJg==",
+      "license": "MIT",
+      "dependencies": {
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.2",
+        "entities": "^4.2.0"
+      },
+      "funding": {
+        "url": "https://github.com/cheeriojs/dom-serializer?sponsor=1"
+      }
+    },
+    "node_modules/dom-serializer/node_modules/entities": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
+      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/domelementtype": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/domelementtype/-/domelementtype-2.3.0.tgz",
+      "integrity": "sha512-OLETBj6w0OsagBwdXnPdN0cnMfF9opN69co+7ZrbfPGrdpPVNBUj02spi6B1N7wChLQiPn4CSH/zJvXw56gmHw==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fb55"
+        }
+      ],
+      "license": "BSD-2-Clause"
+    },
+    "node_modules/domhandler": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/domhandler/-/domhandler-5.0.3.tgz",
+      "integrity": "sha512-cgwlv/1iFQiFnU96XXgROh8xTeetsnJiDsTc7TYCLFd9+/WNkIqPTxiM/8pSd8VIrhXGTf1Ny1q1hquVqDJB5w==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "domelementtype": "^2.3.0"
+      },
+      "engines": {
+        "node": ">= 4"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/domhandler?sponsor=1"
+      }
+    },
+    "node_modules/domutils": {
+      "version": "3.2.2",
+      "resolved": "https://registry.npmjs.org/domutils/-/domutils-3.2.2.tgz",
+      "integrity": "sha512-6kZKyUajlDuqlHKVX1w7gyslj9MPIXzIFiz/rGu35uC1wMi+kMhQwGhl4lt9unC9Vb9INnY9Z3/ZA3+FhASLaw==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "dom-serializer": "^2.0.0",
+        "domelementtype": "^2.3.0",
+        "domhandler": "^5.0.3"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/domutils?sponsor=1"
+      }
+    },
+    "node_modules/dset": {
+      "version": "3.1.4",
+      "resolved": "https://registry.npmjs.org/dset/-/dset-3.1.4.tgz",
+      "integrity": "sha512-2QF/g9/zTaPDc3BjNcVTGoBbXBgYfMTTceLaYcFJ/W9kggFUkhxD/hMEeuLKbugyef9SqAx8cpgwlIP/jinUTA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/entities": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-6.0.1.tgz",
+      "integrity": "sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/es-module-lexer": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.1.0.tgz",
+      "integrity": "sha512-n27zTYMjYu1aj4MjCWzSP7G9r75utsaoc8m61weK+W8JMBGGQybd43GstCXZ3WNmSFtGT9wi59qQTW6mhTR5LQ==",
+      "license": "MIT"
+    },
+    "node_modules/esast-util-from-estree": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/esast-util-from-estree/-/esast-util-from-estree-2.0.0.tgz",
+      "integrity": "sha512-4CyanoAudUSBAn5K13H4JhsMH6L9ZP7XbLVe/dKybkxMO7eDyLsT8UHl9TRNrU2Gr9nz+FovfSIjuXWJ81uVwQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree-jsx": "^1.0.0",
+        "devlop": "^1.0.0",
+        "estree-util-visit": "^2.0.0",
+        "unist-util-position-from-estree": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/esast-util-from-js": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/esast-util-from-js/-/esast-util-from-js-2.0.1.tgz",
+      "integrity": "sha512-8Ja+rNJ0Lt56Pcf3TAmpBZjmx8ZcK5Ts4cAzIOjsjevg9oSXJnl6SUQ2EevU8tv3h6ZLWmoKL5H4fgWvdvfETw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree-jsx": "^1.0.0",
+        "acorn": "^8.0.0",
+        "esast-util-from-estree": "^2.0.0",
+        "vfile-message": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/esbuild": {
+      "version": "0.27.7",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.7.tgz",
+      "integrity": "sha512-IxpibTjyVnmrIQo5aqNpCgoACA/dTKLTlhMHihVHhdkxKyPO1uBBthumT0rdHmcsk9uMonIWS0m4FljWzILh3w==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.27.7",
+        "@esbuild/android-arm": "0.27.7",
+        "@esbuild/android-arm64": "0.27.7",
+        "@esbuild/android-x64": "0.27.7",
+        "@esbuild/darwin-arm64": "0.27.7",
+        "@esbuild/darwin-x64": "0.27.7",
+        "@esbuild/freebsd-arm64": "0.27.7",
+        "@esbuild/freebsd-x64": "0.27.7",
+        "@esbuild/linux-arm": "0.27.7",
+        "@esbuild/linux-arm64": "0.27.7",
+        "@esbuild/linux-ia32": "0.27.7",
+        "@esbuild/linux-loong64": "0.27.7",
+        "@esbuild/linux-mips64el": "0.27.7",
+        "@esbuild/linux-ppc64": "0.27.7",
+        "@esbuild/linux-riscv64": "0.27.7",
+        "@esbuild/linux-s390x": "0.27.7",
+        "@esbuild/linux-x64": "0.27.7",
+        "@esbuild/netbsd-arm64": "0.27.7",
+        "@esbuild/netbsd-x64": "0.27.7",
+        "@esbuild/openbsd-arm64": "0.27.7",
+        "@esbuild/openbsd-x64": "0.27.7",
+        "@esbuild/openharmony-arm64": "0.27.7",
+        "@esbuild/sunos-x64": "0.27.7",
+        "@esbuild/win32-arm64": "0.27.7",
+        "@esbuild/win32-ia32": "0.27.7",
+        "@esbuild/win32-x64": "0.27.7"
+      }
+    },
+    "node_modules/escape-string-regexp": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-5.0.0.tgz",
+      "integrity": "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/estree-util-attach-comments": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/estree-util-attach-comments/-/estree-util-attach-comments-3.0.0.tgz",
+      "integrity": "sha512-cKUwm/HUcTDsYh/9FgnuFqpfquUbwIqwKM26BVCGDPVgvaCl/nDCCjUfiLlx6lsEZ3Z4RFxNbOQ60pkaEwFxGw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/estree-util-build-jsx": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/estree-util-build-jsx/-/estree-util-build-jsx-3.0.1.tgz",
+      "integrity": "sha512-8U5eiL6BTrPxp/CHbs2yMgP8ftMhR5ww1eIKoWRMlqvltHF8fZn5LRDvTKuxD3DUn+shRbLGqXemcP51oFCsGQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree-jsx": "^1.0.0",
+        "devlop": "^1.0.0",
+        "estree-util-is-identifier-name": "^3.0.0",
+        "estree-walker": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/estree-util-is-identifier-name": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/estree-util-is-identifier-name/-/estree-util-is-identifier-name-3.0.0.tgz",
+      "integrity": "sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/estree-util-scope": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/estree-util-scope/-/estree-util-scope-1.0.0.tgz",
+      "integrity": "sha512-2CAASclonf+JFWBNJPndcOpA8EMJwa0Q8LUFJEKqXLW6+qBvbFZuF5gItbQOs/umBUkjviCSDCbBwU2cXbmrhQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "devlop": "^1.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/estree-util-to-js": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/estree-util-to-js/-/estree-util-to-js-2.0.0.tgz",
+      "integrity": "sha512-WDF+xj5rRWmD5tj6bIqRi6CkLIXbbNQUcxQHzGysQzvHmdYG2G7p/Tf0J0gpxGgkeMZNTIjT/AoSvC9Xehcgdg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree-jsx": "^1.0.0",
+        "astring": "^1.8.0",
+        "source-map": "^0.7.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/estree-util-visit": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/estree-util-visit/-/estree-util-visit-2.0.0.tgz",
+      "integrity": "sha512-m5KgiH85xAhhW8Wta0vShLcUvOsh3LLPI2YVwcbio1l7E09NTLL1EyMZFM1OyWowoH0skScNbhOPl4kcBgzTww==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree-jsx": "^1.0.0",
+        "@types/unist": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/estree-walker": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
+      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0"
+      }
+    },
+    "node_modules/eventemitter3": {
+      "version": "5.0.4",
+      "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-5.0.4.tgz",
+      "integrity": "sha512-mlsTRyGaPBjPedk6Bvw+aqbsXDtoAyAzm5MO7JgU+yVRyMQ5O8bD4Kcci7BS85f93veegeCPkL8R4GLClnjLFw==",
+      "license": "MIT"
+    },
+    "node_modules/expressive-code": {
+      "version": "0.42.0",
+      "resolved": "https://registry.npmjs.org/expressive-code/-/expressive-code-0.42.0.tgz",
+      "integrity": "sha512-V5DtJLEKuj4wf9O6IRtPtRObkMVy2ggR+S0MdjrTw6m58krZnDioyhW1si3Y04c5YPeooP4nd85Yq9NwEVHS4g==",
+      "license": "MIT",
+      "dependencies": {
+        "@expressive-code/core": "^0.42.0",
+        "@expressive-code/plugin-frames": "^0.42.0",
+        "@expressive-code/plugin-shiki": "^0.42.0",
+        "@expressive-code/plugin-text-markers": "^0.42.0"
+      }
+    },
+    "node_modules/extend": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz",
+      "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==",
+      "license": "MIT"
+    },
+    "node_modules/fast-string-truncated-width": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/fast-string-truncated-width/-/fast-string-truncated-width-3.0.3.tgz",
+      "integrity": "sha512-0jjjIEL6+0jag3l2XWWizO64/aZVtpiGE3t0Zgqxv0DPuxiMjvB3M24fCyhZUO4KomJQPj3LTSUnDP3GpdwC0g==",
+      "license": "MIT"
+    },
+    "node_modules/fast-string-width": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/fast-string-width/-/fast-string-width-3.0.2.tgz",
+      "integrity": "sha512-gX8LrtNEI5hq8DVUfRQMbr5lpaS4nMIWV+7XEbXk2b8kiQIizgnlr12B4dA3ZEx3308ze0O4Q1R+cHts8kyUJg==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-string-truncated-width": "^3.0.2"
+      }
+    },
+    "node_modules/fast-wrap-ansi": {
+      "version": "0.2.2",
+      "resolved": "https://registry.npmjs.org/fast-wrap-ansi/-/fast-wrap-ansi-0.2.2.tgz",
+      "integrity": "sha512-7F2Fl+TjRSenLqlU3UjSH0iyqopqoZIu7eZVpEirP2g1GtWa2G/ecEmBdgz31+Mxr+ELclgg6sokpSFIQiZ02Q==",
+      "license": "MIT",
+      "dependencies": {
+        "fast-string-width": "^3.0.2"
+      }
+    },
+    "node_modules/fdir": {
+      "version": "6.5.0",
+      "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
+      "integrity": "sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "peerDependencies": {
+        "picomatch": "^3 || ^4"
+      },
+      "peerDependenciesMeta": {
+        "picomatch": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/flattie": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/flattie/-/flattie-1.1.1.tgz",
+      "integrity": "sha512-9UbaD6XdAL97+k/n+N7JwX46K/M6Zc6KcFYskrYL8wbBV/Uyk0CTAMY0VT+qiK5PM7AIc9aTWYtq65U7T+aCNQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/fontace": {
+      "version": "0.4.1",
+      "resolved": "https://registry.npmjs.org/fontace/-/fontace-0.4.1.tgz",
+      "integrity": "sha512-lDMvbAzSnHmbYMTEld5qdtvNH2/pWpICOqpean9IgC7vUbUJc3k+k5Dokp85CegamqQpFbXf0rAVkbzpyTA8aw==",
+      "license": "MIT",
+      "dependencies": {
+        "fontkitten": "^1.0.2"
+      }
+    },
+    "node_modules/fontkitten": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/fontkitten/-/fontkitten-1.0.3.tgz",
+      "integrity": "sha512-Wp1zXWPVUPBmfoa3Cqc9ctaKuzKAV6uLstRqlR56kSjplf5uAce+qeyYym7F+PHbGTk+tCEdkCW6RD7DX/gBZw==",
+      "license": "MIT",
+      "dependencies": {
+        "tiny-inflate": "^1.0.3"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.3",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
+      "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/get-tsconfig": {
+      "version": "5.0.0-beta.4",
+      "resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-5.0.0-beta.4.tgz",
+      "integrity": "sha512-7nF7C9fIPFEMHgEMEfgIlO9wDdZ8CyHw27rWciFZfHvHDReIiPhsYuzPRXsfvBCqFy1l8RRyyWV7QLM+ZhUJsQ==",
+      "license": "MIT",
+      "dependencies": {
+        "resolve-pkg-maps": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=20.20.0"
+      },
+      "funding": {
+        "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
+      }
+    },
+    "node_modules/github-slugger": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/github-slugger/-/github-slugger-2.0.0.tgz",
+      "integrity": "sha512-IaOQ9puYtjrkq7Y0Ygl9KDZnrf/aiUJYUpVf89y8kyaxbRG7Y1SrX/jaumrv81vc61+kiMempujsM3Yw7w5qcw==",
+      "license": "ISC"
+    },
+    "node_modules/h3": {
+      "version": "1.15.11",
+      "resolved": "https://registry.npmjs.org/h3/-/h3-1.15.11.tgz",
+      "integrity": "sha512-L3THSe2MPeBwgIZVSH5zLdBBU90TOxarvhK9d04IDY2AmVS8j2Jz2LIWtwsGOU3lu2I5jCN7FNvVfY2+XyF+mg==",
+      "license": "MIT",
+      "dependencies": {
+        "cookie-es": "^1.2.3",
+        "crossws": "^0.3.5",
+        "defu": "^6.1.6",
+        "destr": "^2.0.5",
+        "iron-webcrypto": "^1.2.1",
+        "node-mock-http": "^1.0.4",
+        "radix3": "^1.1.2",
+        "ufo": "^1.6.3",
+        "uncrypto": "^0.1.3"
+      }
+    },
+    "node_modules/hast-util-embedded": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-embedded/-/hast-util-embedded-3.0.0.tgz",
+      "integrity": "sha512-naH8sld4Pe2ep03qqULEtvYr7EjrLK2QHY8KJR6RJkTUjPGObe1vnx585uzem2hGra+s1q08DZZpfgDVYRbaXA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "hast-util-is-element": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-format": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/hast-util-format/-/hast-util-format-1.1.0.tgz",
+      "integrity": "sha512-yY1UDz6bC9rDvCWHpx12aIBGRG7krurX0p0Fm6pT547LwDIZZiNr8a+IHDogorAdreULSEzP82Nlv5SZkHZcjA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "hast-util-embedded": "^3.0.0",
+        "hast-util-minify-whitespace": "^1.0.0",
+        "hast-util-phrasing": "^3.0.0",
+        "hast-util-whitespace": "^3.0.0",
+        "html-whitespace-sensitive-tag-names": "^3.0.0",
+        "unist-util-visit-parents": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-from-html": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/hast-util-from-html/-/hast-util-from-html-2.0.3.tgz",
+      "integrity": "sha512-CUSRHXyKjzHov8yKsQjGOElXy/3EKpyX56ELnkHH34vDVw1N1XSQ1ZcAvTyAPtGqLTuKP/uxM+aLkSPqF/EtMw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "devlop": "^1.1.0",
+        "hast-util-from-parse5": "^8.0.0",
+        "parse5": "^7.0.0",
+        "vfile": "^6.0.0",
+        "vfile-message": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-from-parse5": {
+      "version": "8.0.3",
+      "resolved": "https://registry.npmjs.org/hast-util-from-parse5/-/hast-util-from-parse5-8.0.3.tgz",
+      "integrity": "sha512-3kxEVkEKt0zvcZ3hCRYI8rqrgwtlIOFMWkbclACvjlDw8Li9S2hk/d51OI0nr/gIpdMHNepwgOKqZ/sy0Clpyg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "devlop": "^1.0.0",
+        "hastscript": "^9.0.0",
+        "property-information": "^7.0.0",
+        "vfile": "^6.0.0",
+        "vfile-location": "^5.0.0",
+        "web-namespaces": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-has-property": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-has-property/-/hast-util-has-property-3.0.0.tgz",
+      "integrity": "sha512-MNilsvEKLFpV604hwfhVStK0usFY/QmM5zX16bo7EjnAEGofr5YyI37kzopBlZJkHD4t887i+q/C8/tr5Q94cA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-is-body-ok-link": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/hast-util-is-body-ok-link/-/hast-util-is-body-ok-link-3.0.1.tgz",
+      "integrity": "sha512-0qpnzOBLztXHbHQenVB8uNuxTnm/QBFUOmdOSsEn7GnBtyY07+ENTWVFBAnXd/zEgd9/SUG3lRY7hSIBWRgGpQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-is-element": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-is-element/-/hast-util-is-element-3.0.0.tgz",
+      "integrity": "sha512-Val9mnv2IWpLbNPqc/pUem+a7Ipj2aHacCwgNfTiK0vJKl0LF+4Ba4+v1oPHFpf3bLYmreq0/l3Gud9S5OH42g==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-minify-whitespace": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/hast-util-minify-whitespace/-/hast-util-minify-whitespace-1.0.1.tgz",
+      "integrity": "sha512-L96fPOVpnclQE0xzdWb/D12VT5FabA7SnZOUMtL1DbXmYiHJMXZvFkIZfiMmTCNJHUeO2K9UYNXoVyfz+QHuOw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "hast-util-embedded": "^3.0.0",
+        "hast-util-is-element": "^3.0.0",
+        "hast-util-whitespace": "^3.0.0",
+        "unist-util-is": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-parse-selector": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-parse-selector/-/hast-util-parse-selector-4.0.0.tgz",
+      "integrity": "sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-phrasing": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/hast-util-phrasing/-/hast-util-phrasing-3.0.1.tgz",
+      "integrity": "sha512-6h60VfI3uBQUxHqTyMymMZnEbNl1XmEGtOxxKYL7stY2o601COo62AWAYBQR9lZbYXYSBoxag8UpPRXK+9fqSQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "hast-util-embedded": "^3.0.0",
+        "hast-util-has-property": "^3.0.0",
+        "hast-util-is-body-ok-link": "^3.0.0",
+        "hast-util-is-element": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-raw": {
+      "version": "9.1.0",
+      "resolved": "https://registry.npmjs.org/hast-util-raw/-/hast-util-raw-9.1.0.tgz",
+      "integrity": "sha512-Y8/SBAHkZGoNkpzqqfCldijcuUKh7/su31kEBp67cFY09Wy0mTRgtsLYsiIxMJxlu0f6AA5SUTbDR8K0rxnbUw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "@ungap/structured-clone": "^1.0.0",
+        "hast-util-from-parse5": "^8.0.0",
+        "hast-util-to-parse5": "^8.0.0",
+        "html-void-elements": "^3.0.0",
+        "mdast-util-to-hast": "^13.0.0",
+        "parse5": "^7.0.0",
+        "unist-util-position": "^5.0.0",
+        "unist-util-visit": "^5.0.0",
+        "vfile": "^6.0.0",
+        "web-namespaces": "^2.0.0",
+        "zwitch": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-select": {
+      "version": "6.0.4",
+      "resolved": "https://registry.npmjs.org/hast-util-select/-/hast-util-select-6.0.4.tgz",
+      "integrity": "sha512-RqGS1ZgI0MwxLaKLDxjprynNzINEkRHY2i8ln4DDjgv9ZhcYVIHN9rlpiYsqtFwrgpYU361SyWDQcGNIBVu3lw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "bcp-47-match": "^2.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "css-selector-parser": "^3.0.0",
+        "devlop": "^1.0.0",
+        "direction": "^2.0.0",
+        "hast-util-has-property": "^3.0.0",
+        "hast-util-to-string": "^3.0.0",
+        "hast-util-whitespace": "^3.0.0",
+        "nth-check": "^2.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0",
+        "unist-util-visit": "^5.0.0",
+        "zwitch": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-to-estree": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/hast-util-to-estree/-/hast-util-to-estree-3.1.3.tgz",
+      "integrity": "sha512-48+B/rJWAp0jamNbAAf9M7Uf//UVqAoMmgXhBdxTDJLGKY+LRnZ99qcG+Qjl5HfMpYNzS5v4EAwVEF34LeAj7w==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "@types/estree-jsx": "^1.0.0",
+        "@types/hast": "^3.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "devlop": "^1.0.0",
+        "estree-util-attach-comments": "^3.0.0",
+        "estree-util-is-identifier-name": "^3.0.0",
+        "hast-util-whitespace": "^3.0.0",
+        "mdast-util-mdx-expression": "^2.0.0",
+        "mdast-util-mdx-jsx": "^3.0.0",
+        "mdast-util-mdxjs-esm": "^2.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0",
+        "style-to-js": "^1.0.0",
+        "unist-util-position": "^5.0.0",
+        "zwitch": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-to-html": {
+      "version": "9.0.5",
+      "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.5.tgz",
+      "integrity": "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "ccount": "^2.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "hast-util-whitespace": "^3.0.0",
+        "html-void-elements": "^3.0.0",
+        "mdast-util-to-hast": "^13.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0",
+        "stringify-entities": "^4.0.0",
+        "zwitch": "^2.0.4"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-to-jsx-runtime": {
+      "version": "2.3.6",
+      "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.6.tgz",
+      "integrity": "sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "devlop": "^1.0.0",
+        "estree-util-is-identifier-name": "^3.0.0",
+        "hast-util-whitespace": "^3.0.0",
+        "mdast-util-mdx-expression": "^2.0.0",
+        "mdast-util-mdx-jsx": "^3.0.0",
+        "mdast-util-mdxjs-esm": "^2.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0",
+        "style-to-js": "^1.0.0",
+        "unist-util-position": "^5.0.0",
+        "vfile-message": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-to-parse5": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/hast-util-to-parse5/-/hast-util-to-parse5-8.0.1.tgz",
+      "integrity": "sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "devlop": "^1.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0",
+        "web-namespaces": "^2.0.0",
+        "zwitch": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-to-string": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/hast-util-to-string/-/hast-util-to-string-3.0.1.tgz",
+      "integrity": "sha512-XelQVTDWvqcl3axRfI0xSeoVKzyIFPwsAGSLIsKdJKQMXDYJS4WYrBNF/8J7RdhIcFI2BOHgAifggsvsxp/3+A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-to-text": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/hast-util-to-text/-/hast-util-to-text-4.0.2.tgz",
+      "integrity": "sha512-KK6y/BN8lbaq654j7JgBydev7wuNMcID54lkRav1P0CaE1e47P72AWWPiGKXTJU271ooYzcvTAn/Zt0REnvc7A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/unist": "^3.0.0",
+        "hast-util-is-element": "^3.0.0",
+        "unist-util-find-after": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hast-util-whitespace": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-3.0.0.tgz",
+      "integrity": "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/hastscript": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/hastscript/-/hastscript-9.0.1.tgz",
+      "integrity": "sha512-g7df9rMFX/SPi34tyGCyUBREQoKkapwdY/T04Qn9TDWfHhAYt4/I0gMVirzK5wEzeUqIjEB+LXC/ypb7Aqno5w==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "comma-separated-tokens": "^2.0.0",
+        "hast-util-parse-selector": "^4.0.0",
+        "property-information": "^7.0.0",
+        "space-separated-tokens": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/html-escaper": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-3.0.3.tgz",
+      "integrity": "sha512-RuMffC89BOWQoY0WKGpIhn5gX3iI54O6nRA0yC124NYVtzjmFWBIiFd8M0x+ZdX0P9R4lADg1mgP8C7PxGOWuQ==",
+      "license": "MIT"
+    },
+    "node_modules/html-void-elements": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/html-void-elements/-/html-void-elements-3.0.0.tgz",
+      "integrity": "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/html-whitespace-sensitive-tag-names": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/html-whitespace-sensitive-tag-names/-/html-whitespace-sensitive-tag-names-3.0.1.tgz",
+      "integrity": "sha512-q+310vW8zmymYHALr1da4HyXUQ0zgiIwIicEfotYPWGN0OJVEN/58IJ3A4GBYcEq3LGAZqKb+ugvP0GNB9CEAA==",
+      "license": "MIT",
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/http-cache-semantics": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/http-cache-semantics/-/http-cache-semantics-4.2.0.tgz",
+      "integrity": "sha512-dTxcvPXqPvXBQpq5dUr6mEMJX4oIEFv6bwom3FDwKRDsuIjjJGANqhBuoAn9c1RQJIdAKav33ED65E2ys+87QQ==",
+      "license": "BSD-2-Clause"
+    },
+    "node_modules/i18next": {
+      "version": "26.2.0",
+      "resolved": "https://registry.npmjs.org/i18next/-/i18next-26.2.0.tgz",
+      "integrity": "sha512-zwBHldHdTmwN7r6UNc7lC6GWNN+YYg3DrRSeHR5PRRBf5QnJZcYHrQc0uaU26qZeYxR7iFZD+Y315dPnKP47wA==",
+      "funding": [
+        {
+          "type": "individual",
+          "url": "https://www.locize.com/i18next"
+        },
+        {
+          "type": "individual",
+          "url": "https://www.i18next.com/how-to/faq#i18next-is-awesome.-how-can-i-support-the-project"
+        },
+        {
+          "type": "individual",
+          "url": "https://www.locize.com"
+        }
+      ],
+      "license": "MIT",
+      "peerDependencies": {
+        "typescript": "^5 || ^6"
+      },
+      "peerDependenciesMeta": {
+        "typescript": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/inline-style-parser": {
+      "version": "0.2.7",
+      "resolved": "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.2.7.tgz",
+      "integrity": "sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==",
+      "license": "MIT"
+    },
+    "node_modules/iron-webcrypto": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/iron-webcrypto/-/iron-webcrypto-1.2.1.tgz",
+      "integrity": "sha512-feOM6FaSr6rEABp/eDfVseKyTMDt+KGpeB35SkVn9Tyn0CqvVsY3EwI0v5i8nMHyJnzCIQf7nsy3p41TPkJZhg==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/brc-dd"
+      }
+    },
+    "node_modules/is-alphabetical": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz",
+      "integrity": "sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/is-alphanumerical": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-alphanumerical/-/is-alphanumerical-2.0.1.tgz",
+      "integrity": "sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==",
+      "license": "MIT",
+      "dependencies": {
+        "is-alphabetical": "^2.0.0",
+        "is-decimal": "^2.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/is-decimal": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-decimal/-/is-decimal-2.0.1.tgz",
+      "integrity": "sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/is-docker": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/is-docker/-/is-docker-4.0.0.tgz",
+      "integrity": "sha512-LHE+wROyG/Y/0ZnbktRCoTix2c1RhgWaZraMZ8o1Q7zCh0VSrICJQO5oqIIISrcSBtrXv0o233w1IYwsWCjTzA==",
+      "license": "MIT",
+      "bin": {
+        "is-docker": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-hexadecimal": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-hexadecimal/-/is-hexadecimal-2.0.1.tgz",
+      "integrity": "sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/is-inside-container": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/is-inside-container/-/is-inside-container-1.0.0.tgz",
+      "integrity": "sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==",
+      "license": "MIT",
+      "dependencies": {
+        "is-docker": "^3.0.0"
+      },
+      "bin": {
+        "is-inside-container": "cli.js"
+      },
+      "engines": {
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-inside-container/node_modules/is-docker": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-docker/-/is-docker-3.0.0.tgz",
+      "integrity": "sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==",
+      "license": "MIT",
+      "bin": {
+        "is-docker": "cli.js"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-plain-obj": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/is-plain-obj/-/is-plain-obj-4.1.0.tgz",
+      "integrity": "sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-wsl": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/is-wsl/-/is-wsl-3.1.1.tgz",
+      "integrity": "sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==",
+      "license": "MIT",
+      "dependencies": {
+        "is-inside-container": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/js-yaml": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
+      "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
+    "node_modules/jsonc-parser": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz",
+      "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==",
+      "license": "MIT"
+    },
+    "node_modules/klona": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/klona/-/klona-2.0.6.tgz",
+      "integrity": "sha512-dhG34DXATL5hSxJbIexCft8FChFXtmskoZYnoPWjXQuebWYCNkVeV3KkGegCK9CP1oswI/vQibS2GY7Em/sJJA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/longest-streak": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/longest-streak/-/longest-streak-3.1.0.tgz",
+      "integrity": "sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/lru-cache": {
+      "version": "11.5.0",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.0.tgz",
+      "integrity": "sha512-5YgH9UJd7wVb9hIouI2adWpgqrrICkt070Dnj8EUY1+B4B2P9eRLPAkAAo6NICA7CEhOIeBHl46u9zSNpNu7zA==",
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": "20 || >=22"
+      }
+    },
+    "node_modules/magic-string": {
+      "version": "0.30.21",
+      "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
+      "integrity": "sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/sourcemap-codec": "^1.5.5"
+      }
+    },
+    "node_modules/magicast": {
+      "version": "0.5.3",
+      "resolved": "https://registry.npmjs.org/magicast/-/magicast-0.5.3.tgz",
+      "integrity": "sha512-pVKE4UdSQ7DvHzivsCIFx2BJn1mHG6KsyrFcaxFx6tONdneEuThrDx0Cj3AMg58KyN4pzYT+LHOotxDQDjNvkw==",
+      "license": "MIT",
+      "dependencies": {
+        "@babel/parser": "^7.29.3",
+        "@babel/types": "^7.29.0",
+        "source-map-js": "^1.2.1"
+      }
+    },
+    "node_modules/markdown-extensions": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/markdown-extensions/-/markdown-extensions-2.0.0.tgz",
+      "integrity": "sha512-o5vL7aDWatOTX8LzaS1WMoaoxIiLRQJuIKKe2wAw6IeULDHaqbiqiggmx+pKvZDb1Sj+pE46Sn1T7lCqfFtg1Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/markdown-table": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/markdown-table/-/markdown-table-3.0.4.tgz",
+      "integrity": "sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/mdast-util-definitions": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-definitions/-/mdast-util-definitions-6.0.0.tgz",
+      "integrity": "sha512-scTllyX6pnYNZH/AIp/0ePz6s4cZtARxImwoPJ7kS42n+MnVsI4XbnG6d4ibehRIldYMWM2LD7ImQblVhUejVQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "@types/unist": "^3.0.0",
+        "unist-util-visit": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-directive": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-directive/-/mdast-util-directive-3.1.0.tgz",
+      "integrity": "sha512-I3fNFt+DHmpWCYAT7quoM6lHf9wuqtI+oCOfvILnoicNIqjh5E3dEJWiXuYME2gNe8vl1iMQwyUHa7bgFmak6Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "@types/unist": "^3.0.0",
+        "ccount": "^2.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0",
+        "parse-entities": "^4.0.0",
+        "stringify-entities": "^4.0.0",
+        "unist-util-visit-parents": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-find-and-replace": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/mdast-util-find-and-replace/-/mdast-util-find-and-replace-3.0.2.tgz",
+      "integrity": "sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "escape-string-regexp": "^5.0.0",
+        "unist-util-is": "^6.0.0",
+        "unist-util-visit-parents": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-from-markdown": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-2.0.3.tgz",
+      "integrity": "sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "@types/unist": "^3.0.0",
+        "decode-named-character-reference": "^1.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-to-string": "^4.0.0",
+        "micromark": "^4.0.0",
+        "micromark-util-decode-numeric-character-reference": "^2.0.0",
+        "micromark-util-decode-string": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0",
+        "unist-util-stringify-position": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm/-/mdast-util-gfm-3.1.0.tgz",
+      "integrity": "sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==",
+      "license": "MIT",
+      "dependencies": {
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-gfm-autolink-literal": "^2.0.0",
+        "mdast-util-gfm-footnote": "^2.0.0",
+        "mdast-util-gfm-strikethrough": "^2.0.0",
+        "mdast-util-gfm-table": "^2.0.0",
+        "mdast-util-gfm-task-list-item": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-autolink-literal": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-autolink-literal/-/mdast-util-gfm-autolink-literal-2.0.1.tgz",
+      "integrity": "sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "ccount": "^2.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-find-and-replace": "^3.0.0",
+        "micromark-util-character": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-footnote": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-footnote/-/mdast-util-gfm-footnote-2.1.0.tgz",
+      "integrity": "sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.1.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-strikethrough": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-strikethrough/-/mdast-util-gfm-strikethrough-2.0.0.tgz",
+      "integrity": "sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-table": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-table/-/mdast-util-gfm-table-2.0.0.tgz",
+      "integrity": "sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.0.0",
+        "markdown-table": "^3.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-gfm-task-list-item": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-gfm-task-list-item/-/mdast-util-gfm-task-list-item-2.0.0.tgz",
+      "integrity": "sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-mdx": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-mdx/-/mdast-util-mdx-3.0.0.tgz",
+      "integrity": "sha512-JfbYLAW7XnYTTbUsmpu0kdBUVe+yKVJZBItEjwyYJiDJuZ9w4eeaqks4HQO+R7objWgS2ymV60GYpI14Ug554w==",
+      "license": "MIT",
+      "dependencies": {
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-mdx-expression": "^2.0.0",
+        "mdast-util-mdx-jsx": "^3.0.0",
+        "mdast-util-mdxjs-esm": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-mdx-expression": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/mdast-util-mdx-expression/-/mdast-util-mdx-expression-2.0.1.tgz",
+      "integrity": "sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree-jsx": "^1.0.0",
+        "@types/hast": "^3.0.0",
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-mdx-jsx": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-mdx-jsx/-/mdast-util-mdx-jsx-3.2.0.tgz",
+      "integrity": "sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree-jsx": "^1.0.0",
+        "@types/hast": "^3.0.0",
+        "@types/mdast": "^4.0.0",
+        "@types/unist": "^3.0.0",
+        "ccount": "^2.0.0",
+        "devlop": "^1.1.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0",
+        "parse-entities": "^4.0.0",
+        "stringify-entities": "^4.0.0",
+        "unist-util-stringify-position": "^4.0.0",
+        "vfile-message": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-mdxjs-esm": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/mdast-util-mdxjs-esm/-/mdast-util-mdxjs-esm-2.0.1.tgz",
+      "integrity": "sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree-jsx": "^1.0.0",
+        "@types/hast": "^3.0.0",
+        "@types/mdast": "^4.0.0",
+        "devlop": "^1.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "mdast-util-to-markdown": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-phrasing": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-phrasing/-/mdast-util-phrasing-4.1.0.tgz",
+      "integrity": "sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "unist-util-is": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-to-hast": {
+      "version": "13.2.1",
+      "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.2.1.tgz",
+      "integrity": "sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/mdast": "^4.0.0",
+        "@ungap/structured-clone": "^1.0.0",
+        "devlop": "^1.0.0",
+        "micromark-util-sanitize-uri": "^2.0.0",
+        "trim-lines": "^3.0.0",
+        "unist-util-position": "^5.0.0",
+        "unist-util-visit": "^5.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-to-markdown": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/mdast-util-to-markdown/-/mdast-util-to-markdown-2.1.2.tgz",
+      "integrity": "sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "@types/unist": "^3.0.0",
+        "longest-streak": "^3.0.0",
+        "mdast-util-phrasing": "^4.0.0",
+        "mdast-util-to-string": "^4.0.0",
+        "micromark-util-classify-character": "^2.0.0",
+        "micromark-util-decode-string": "^2.0.0",
+        "unist-util-visit": "^5.0.0",
+        "zwitch": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdast-util-to-string": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-4.0.0.tgz",
+      "integrity": "sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/mdn-data": {
+      "version": "2.27.1",
+      "resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-2.27.1.tgz",
+      "integrity": "sha512-9Yubnt3e8A0OKwxYSXyhLymGW4sCufcLG6VdiDdUGVkPhpqLxlvP5vl1983gQjJl3tqbrM731mjaZaP68AgosQ==",
+      "license": "CC0-1.0"
+    },
+    "node_modules/micromark": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/micromark/-/micromark-4.0.2.tgz",
+      "integrity": "sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@types/debug": "^4.0.0",
+        "debug": "^4.0.0",
+        "decode-named-character-reference": "^1.0.0",
+        "devlop": "^1.0.0",
+        "micromark-core-commonmark": "^2.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-chunked": "^2.0.0",
+        "micromark-util-combine-extensions": "^2.0.0",
+        "micromark-util-decode-numeric-character-reference": "^2.0.0",
+        "micromark-util-encode": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0",
+        "micromark-util-resolve-all": "^2.0.0",
+        "micromark-util-sanitize-uri": "^2.0.0",
+        "micromark-util-subtokenize": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-core-commonmark": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-2.0.3.tgz",
+      "integrity": "sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "decode-named-character-reference": "^1.0.0",
+        "devlop": "^1.0.0",
+        "micromark-factory-destination": "^2.0.0",
+        "micromark-factory-label": "^2.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-factory-title": "^2.0.0",
+        "micromark-factory-whitespace": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-chunked": "^2.0.0",
+        "micromark-util-classify-character": "^2.0.0",
+        "micromark-util-html-tag-name": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0",
+        "micromark-util-resolve-all": "^2.0.0",
+        "micromark-util-subtokenize": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-extension-directive": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-directive/-/micromark-extension-directive-4.0.0.tgz",
+      "integrity": "sha512-/C2nqVmXXmiseSSuCdItCMho7ybwwop6RrrRPk0KbOHW21JKoCldC+8rFOaundDoRBUWBnJJcxeA/Kvi34WQXg==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-factory-whitespace": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0",
+        "parse-entities": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm/-/micromark-extension-gfm-3.0.0.tgz",
+      "integrity": "sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==",
+      "license": "MIT",
+      "dependencies": {
+        "micromark-extension-gfm-autolink-literal": "^2.0.0",
+        "micromark-extension-gfm-footnote": "^2.0.0",
+        "micromark-extension-gfm-strikethrough": "^2.0.0",
+        "micromark-extension-gfm-table": "^2.0.0",
+        "micromark-extension-gfm-tagfilter": "^2.0.0",
+        "micromark-extension-gfm-task-list-item": "^2.0.0",
+        "micromark-util-combine-extensions": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-autolink-literal": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-2.1.0.tgz",
+      "integrity": "sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==",
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-sanitize-uri": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-footnote": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-footnote/-/micromark-extension-gfm-footnote-2.1.0.tgz",
+      "integrity": "sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-core-commonmark": "^2.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-normalize-identifier": "^2.0.0",
+        "micromark-util-sanitize-uri": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-strikethrough": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-strikethrough/-/micromark-extension-gfm-strikethrough-2.1.0.tgz",
+      "integrity": "sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-util-chunked": "^2.0.0",
+        "micromark-util-classify-character": "^2.0.0",
+        "micromark-util-resolve-all": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-table": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.1.tgz",
+      "integrity": "sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-tagfilter": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-tagfilter/-/micromark-extension-gfm-tagfilter-2.0.0.tgz",
+      "integrity": "sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==",
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-gfm-task-list-item": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-gfm-task-list-item/-/micromark-extension-gfm-task-list-item-2.1.0.tgz",
+      "integrity": "sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==",
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-mdx-expression": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-extension-mdx-expression/-/micromark-extension-mdx-expression-3.0.1.tgz",
+      "integrity": "sha512-dD/ADLJ1AeMvSAKBwO22zG22N4ybhe7kFIZ3LsDI0GlsNr2A3KYxb0LdC1u5rj4Nw+CHKY0RVdnHX8vj8ejm4Q==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "devlop": "^1.0.0",
+        "micromark-factory-mdx-expression": "^2.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-events-to-acorn": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-extension-mdx-jsx": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/micromark-extension-mdx-jsx/-/micromark-extension-mdx-jsx-3.0.2.tgz",
+      "integrity": "sha512-e5+q1DjMh62LZAJOnDraSSbDMvGJ8x3cbjygy2qFEi7HCeUT4BDKCvMozPozcD6WmOt6sVvYDNBKhFSz3kjOVQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "devlop": "^1.0.0",
+        "estree-util-is-identifier-name": "^3.0.0",
+        "micromark-factory-mdx-expression": "^2.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-events-to-acorn": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0",
+        "vfile-message": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-mdx-md": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-mdx-md/-/micromark-extension-mdx-md-2.0.0.tgz",
+      "integrity": "sha512-EpAiszsB3blw4Rpba7xTOUptcFeBFi+6PY8VnJ2hhimH+vCQDirWgsMpz7w1XcZE7LVrSAUGb9VJpG9ghlYvYQ==",
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-mdxjs": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-mdxjs/-/micromark-extension-mdxjs-3.0.0.tgz",
+      "integrity": "sha512-A873fJfhnJ2siZyUrJ31l34Uqwy4xIFmvPY1oj+Ean5PHcPBYzEsvqvWGaWcfEIr11O5Dlw3p2y0tZWpKHDejQ==",
+      "license": "MIT",
+      "dependencies": {
+        "acorn": "^8.0.0",
+        "acorn-jsx": "^5.0.0",
+        "micromark-extension-mdx-expression": "^3.0.0",
+        "micromark-extension-mdx-jsx": "^3.0.0",
+        "micromark-extension-mdx-md": "^2.0.0",
+        "micromark-extension-mdxjs-esm": "^3.0.0",
+        "micromark-util-combine-extensions": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-extension-mdxjs-esm": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/micromark-extension-mdxjs-esm/-/micromark-extension-mdxjs-esm-3.0.0.tgz",
+      "integrity": "sha512-DJFl4ZqkErRpq/dAPyeWp15tGrcrrJho1hKK5uBS70BCtfrIFg81sqcTVu3Ta+KD1Tk5vAtBNElWxtAa+m8K9A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "devlop": "^1.0.0",
+        "micromark-core-commonmark": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-events-to-acorn": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0",
+        "unist-util-position-from-estree": "^2.0.0",
+        "vfile-message": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/micromark-factory-destination": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-2.0.1.tgz",
+      "integrity": "sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-factory-label": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-factory-label/-/micromark-factory-label-2.0.1.tgz",
+      "integrity": "sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-factory-mdx-expression": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/micromark-factory-mdx-expression/-/micromark-factory-mdx-expression-2.0.3.tgz",
+      "integrity": "sha512-kQnEtA3vzucU2BkrIa8/VaSAsP+EJ3CKOvhMuJgOEGg9KDC6OAY6nSnNDVRiVNRqj7Y4SlSzcStaH/5jge8JdQ==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "devlop": "^1.0.0",
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-events-to-acorn": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0",
+        "unist-util-position-from-estree": "^2.0.0",
+        "vfile-message": "^4.0.0"
+      }
+    },
+    "node_modules/micromark-factory-space": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-factory-space/-/micromark-factory-space-2.0.1.tgz",
+      "integrity": "sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-factory-title": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-factory-title/-/micromark-factory-title-2.0.1.tgz",
+      "integrity": "sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-factory-whitespace": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-factory-whitespace/-/micromark-factory-whitespace-2.0.1.tgz",
+      "integrity": "sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-factory-space": "^2.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-character": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz",
+      "integrity": "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-chunked": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-chunked/-/micromark-util-chunked-2.0.1.tgz",
+      "integrity": "sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-symbol": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-classify-character": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-classify-character/-/micromark-util-classify-character-2.0.1.tgz",
+      "integrity": "sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-combine-extensions": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-combine-extensions/-/micromark-util-combine-extensions-2.0.1.tgz",
+      "integrity": "sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-chunked": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-decode-numeric-character-reference": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-2.0.2.tgz",
+      "integrity": "sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-symbol": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-decode-string": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-decode-string/-/micromark-util-decode-string-2.0.1.tgz",
+      "integrity": "sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "decode-named-character-reference": "^1.0.0",
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-decode-numeric-character-reference": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-encode": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.1.tgz",
+      "integrity": "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/micromark-util-events-to-acorn": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/micromark-util-events-to-acorn/-/micromark-util-events-to-acorn-2.0.3.tgz",
+      "integrity": "sha512-jmsiEIiZ1n7X1Rr5k8wVExBQCg5jy4UXVADItHmNk1zkwEVhBuIUKRu3fqv+hs4nxLISi2DQGlqIOGiFxgbfHg==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "@types/unist": "^3.0.0",
+        "devlop": "^1.0.0",
+        "estree-util-visit": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0",
+        "vfile-message": "^4.0.0"
+      }
+    },
+    "node_modules/micromark-util-html-tag-name": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-html-tag-name/-/micromark-util-html-tag-name-2.0.1.tgz",
+      "integrity": "sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/micromark-util-normalize-identifier": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-2.0.1.tgz",
+      "integrity": "sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-symbol": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-resolve-all": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-resolve-all/-/micromark-util-resolve-all-2.0.1.tgz",
+      "integrity": "sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-sanitize-uri": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.1.tgz",
+      "integrity": "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "micromark-util-character": "^2.0.0",
+        "micromark-util-encode": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-subtokenize": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/micromark-util-subtokenize/-/micromark-util-subtokenize-2.1.0.tgz",
+      "integrity": "sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "devlop": "^1.0.0",
+        "micromark-util-chunked": "^2.0.0",
+        "micromark-util-symbol": "^2.0.0",
+        "micromark-util-types": "^2.0.0"
+      }
+    },
+    "node_modules/micromark-util-symbol": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.1.tgz",
+      "integrity": "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/micromark-util-types": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.2.tgz",
+      "integrity": "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==",
+      "funding": [
+        {
+          "type": "GitHub Sponsors",
+          "url": "https://github.com/sponsors/unifiedjs"
+        },
+        {
+          "type": "OpenCollective",
+          "url": "https://opencollective.com/unified"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/mrmime": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/mrmime/-/mrmime-2.0.1.tgz",
+      "integrity": "sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "license": "MIT"
+    },
+    "node_modules/nanoid": {
+      "version": "3.3.12",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz",
+      "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.cjs"
+      },
+      "engines": {
+        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
+      }
+    },
+    "node_modules/neotraverse": {
+      "version": "0.6.18",
+      "resolved": "https://registry.npmjs.org/neotraverse/-/neotraverse-0.6.18.tgz",
+      "integrity": "sha512-Z4SmBUweYa09+o6pG+eASabEpP6QkQ70yHj351pQoEXIs8uHbaU2DWVmzBANKgflPa47A50PtB2+NgRpQvr7vA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/nlcst-to-string": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/nlcst-to-string/-/nlcst-to-string-4.0.0.tgz",
+      "integrity": "sha512-YKLBCcUYKAg0FNlOBT6aI91qFmSiFKiluk655WzPF+DDMA02qIyy8uiRqI8QXtcFpEvll12LpL5MXqEmAZ+dcA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/nlcst": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/node-fetch-native": {
+      "version": "1.6.7",
+      "resolved": "https://registry.npmjs.org/node-fetch-native/-/node-fetch-native-1.6.7.tgz",
+      "integrity": "sha512-g9yhqoedzIUm0nTnTqAQvueMPVOuIY16bqgAJJC8XOOubYFNwz6IER9qs0Gq2Xd0+CecCKFjtdDTMA4u4xG06Q==",
+      "license": "MIT"
+    },
+    "node_modules/node-mock-http": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/node-mock-http/-/node-mock-http-1.0.4.tgz",
+      "integrity": "sha512-8DY+kFsDkNXy1sJglUfuODx1/opAGJGyrTuFqEoN90oRc2Vk0ZbD4K2qmKXBBEhZQzdKHIVfEJpDU8Ak2NJEvQ==",
+      "license": "MIT"
+    },
+    "node_modules/normalize-path": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/normalize-path/-/normalize-path-3.0.0.tgz",
+      "integrity": "sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/nth-check": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/nth-check/-/nth-check-2.1.1.tgz",
+      "integrity": "sha512-lqjrjmaOoAnWfMmBPL+XNnynZh2+swxiX3WUE0s4yEHI6m+AwrK2UZOimIRl3X/4QctVqS8AiZjFqyOGrMXb/w==",
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "boolbase": "^1.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/nth-check?sponsor=1"
+      }
+    },
+    "node_modules/obug": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.1.tgz",
+      "integrity": "sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==",
+      "funding": [
+        "https://github.com/sponsors/sxzz",
+        "https://opencollective.com/debug"
+      ],
+      "license": "MIT"
+    },
+    "node_modules/ofetch": {
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/ofetch/-/ofetch-1.5.1.tgz",
+      "integrity": "sha512-2W4oUZlVaqAPAil6FUg/difl6YhqhUR7x2eZY4bQCko22UXg3hptq9KLQdqFClV+Wu85UX7hNtdGTngi/1BxcA==",
+      "license": "MIT",
+      "dependencies": {
+        "destr": "^2.0.5",
+        "node-fetch-native": "^1.6.7",
+        "ufo": "^1.6.1"
+      }
+    },
+    "node_modules/ohash": {
+      "version": "2.0.11",
+      "resolved": "https://registry.npmjs.org/ohash/-/ohash-2.0.11.tgz",
+      "integrity": "sha512-RdR9FQrFwNBNXAr4GixM8YaRZRJ5PUWbKYbE5eOsrwAjJW0q2REGcf79oYPsLyskQCZG1PLN+S/K1V00joZAoQ==",
+      "license": "MIT"
+    },
+    "node_modules/oniguruma-parser": {
+      "version": "0.12.2",
+      "resolved": "https://registry.npmjs.org/oniguruma-parser/-/oniguruma-parser-0.12.2.tgz",
+      "integrity": "sha512-6HVa5oIrgMC6aA6WF6XyyqbhRPJrKR02L20+2+zpDtO5QAzGHAUGw5TKQvwi5vctNnRHkJYmjAhRVQF2EKdTQw==",
+      "license": "MIT"
+    },
+    "node_modules/oniguruma-to-es": {
+      "version": "4.3.6",
+      "resolved": "https://registry.npmjs.org/oniguruma-to-es/-/oniguruma-to-es-4.3.6.tgz",
+      "integrity": "sha512-csuQ9x3Yr0cEIs/Zgx/OEt9iBw9vqIunAPQkx19R/fiMq2oGVTgcMqO/V3Ybqefr1TBvosI6jU539ksaBULJyA==",
+      "license": "MIT",
+      "dependencies": {
+        "oniguruma-parser": "^0.12.2",
+        "regex": "^6.1.0",
+        "regex-recursion": "^6.0.2"
+      }
+    },
+    "node_modules/p-limit": {
+      "version": "7.3.0",
+      "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-7.3.0.tgz",
+      "integrity": "sha512-7cIXg/Z0M5WZRblrsOla88S4wAK+zOQQWeBYfV3qJuJXMr+LnbYjaadrFaS0JILfEDPVqHyKnZ1Z/1d6J9VVUw==",
+      "license": "MIT",
+      "dependencies": {
+        "yocto-queue": "^1.2.1"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/p-queue": {
+      "version": "9.3.0",
+      "resolved": "https://registry.npmjs.org/p-queue/-/p-queue-9.3.0.tgz",
+      "integrity": "sha512-7NED7xhQ74Ngp4JP/2e0VZHp7vSWfJfqeiR92jPgxsz6m0Se4P03YoTKa9dDXyZ3r6P616gUXttrB6nnHYKang==",
+      "license": "MIT",
+      "dependencies": {
+        "eventemitter3": "^5.0.4",
+        "p-timeout": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/p-timeout": {
+      "version": "7.0.1",
+      "resolved": "https://registry.npmjs.org/p-timeout/-/p-timeout-7.0.1.tgz",
+      "integrity": "sha512-AxTM2wDGORHGEkPCt8yqxOTMgpfbEHqF51f/5fJCmwFC3C/zNcGT63SymH2ttOAaiIws2zVg4+izQCjrakcwHg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/package-manager-detector": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/package-manager-detector/-/package-manager-detector-1.6.0.tgz",
+      "integrity": "sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==",
+      "license": "MIT"
+    },
+    "node_modules/pagefind": {
+      "version": "1.5.2",
+      "resolved": "https://registry.npmjs.org/pagefind/-/pagefind-1.5.2.tgz",
+      "integrity": "sha512-XTUaK0hXMCu2jszWE584JGQT7y284TmMV9l/HX3rnG5uo3rHI/uHU56XTyyyPFjeWEBxECbAi0CaFDJOONtG0Q==",
+      "license": "MIT",
+      "bin": {
+        "pagefind": "lib/runner/bin.cjs"
+      },
+      "optionalDependencies": {
+        "@pagefind/darwin-arm64": "1.5.2",
+        "@pagefind/darwin-x64": "1.5.2",
+        "@pagefind/freebsd-x64": "1.5.2",
+        "@pagefind/linux-arm64": "1.5.2",
+        "@pagefind/linux-x64": "1.5.2",
+        "@pagefind/windows-arm64": "1.5.2",
+        "@pagefind/windows-x64": "1.5.2"
+      }
+    },
+    "node_modules/parse-entities": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/parse-entities/-/parse-entities-4.0.2.tgz",
+      "integrity": "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^2.0.0",
+        "character-entities-legacy": "^3.0.0",
+        "character-reference-invalid": "^2.0.0",
+        "decode-named-character-reference": "^1.0.0",
+        "is-alphanumerical": "^2.0.0",
+        "is-decimal": "^2.0.0",
+        "is-hexadecimal": "^2.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/parse-entities/node_modules/@types/unist": {
+      "version": "2.0.11",
+      "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz",
+      "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==",
+      "license": "MIT"
+    },
+    "node_modules/parse-latin": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/parse-latin/-/parse-latin-7.0.0.tgz",
+      "integrity": "sha512-mhHgobPPua5kZ98EF4HWiH167JWBfl4pvAIXXdbaVohtK7a6YBOy56kvhCqduqyo/f3yrHFWmqmiMg/BkBkYYQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/nlcst": "^2.0.0",
+        "@types/unist": "^3.0.0",
+        "nlcst-to-string": "^4.0.0",
+        "unist-util-modify-children": "^4.0.0",
+        "unist-util-visit-children": "^3.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/parse5": {
+      "version": "7.3.0",
+      "resolved": "https://registry.npmjs.org/parse5/-/parse5-7.3.0.tgz",
+      "integrity": "sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==",
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^6.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/inikulin/parse5?sponsor=1"
+      }
+    },
+    "node_modules/piccolore": {
+      "version": "0.1.3",
+      "resolved": "https://registry.npmjs.org/piccolore/-/piccolore-0.1.3.tgz",
+      "integrity": "sha512-o8bTeDWjE086iwKrROaDf31K0qC/BENdm15/uH9usSC/uZjJOKb2YGiVHfLY4GhwsERiPI1jmwI2XrA7ACOxVw==",
+      "license": "ISC"
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "license": "ISC"
+    },
+    "node_modules/picomatch": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/postcss": {
+      "version": "8.5.15",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz",
+      "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==",
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "tidelift",
+          "url": "https://tidelift.com/funding/github/npm/postcss"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "nanoid": "^3.3.12",
+        "picocolors": "^1.1.1",
+        "source-map-js": "^1.2.1"
+      },
+      "engines": {
+        "node": "^10 || ^12 || >=14"
+      }
+    },
+    "node_modules/postcss-nested": {
+      "version": "6.2.0",
+      "resolved": "https://registry.npmjs.org/postcss-nested/-/postcss-nested-6.2.0.tgz",
+      "integrity": "sha512-HQbt28KulC5AJzG+cZtj9kvKB93CFCdLvog1WFLf1D+xmMvPGlBstkpTEZfK5+AN9hfJocyBFCNiqyS48bpgzQ==",
+      "funding": [
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/postcss/"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "postcss-selector-parser": "^6.1.1"
+      },
+      "engines": {
+        "node": ">=12.0"
+      },
+      "peerDependencies": {
+        "postcss": "^8.2.14"
+      }
+    },
+    "node_modules/postcss-selector-parser": {
+      "version": "6.1.2",
+      "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-6.1.2.tgz",
+      "integrity": "sha512-Q8qQfPiZ+THO/3ZrOrO0cJJKfpYCagtMUkXbnEfmgUjwXg6z/WBeOyS9APBBPCTSiDV+s4SwQGu8yFsiMRIudg==",
+      "license": "MIT",
+      "dependencies": {
+        "cssesc": "^3.0.0",
+        "util-deprecate": "^1.0.2"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/prismjs": {
+      "version": "1.30.0",
+      "resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.30.0.tgz",
+      "integrity": "sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/property-information": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/property-information/-/property-information-7.1.0.tgz",
+      "integrity": "sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/radix3": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/radix3/-/radix3-1.1.2.tgz",
+      "integrity": "sha512-b484I/7b8rDEdSDKckSSBA8knMpcdsXudlE/LNL639wFoHKwLbEkQFZHWEYwDC0wa0FKUcCY+GAF73Z7wxNVFA==",
+      "license": "MIT"
+    },
+    "node_modules/readdirp": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/readdirp/-/readdirp-5.0.0.tgz",
+      "integrity": "sha512-9u/XQ1pvrQtYyMpZe7DXKv2p5CNvyVwzUB6uhLAnQwHMSgKMBR62lc7AHljaeteeHXn11XTAaLLUVZYVZyuRBQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 20.19.0"
+      },
+      "funding": {
+        "type": "individual",
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
+    "node_modules/recma-build-jsx": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/recma-build-jsx/-/recma-build-jsx-1.0.0.tgz",
+      "integrity": "sha512-8GtdyqaBcDfva+GUKDr3nev3VpKAhup1+RvkMvUxURHpW7QyIvk9F5wz7Vzo06CEMSilw6uArgRqhpiUcWp8ew==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "estree-util-build-jsx": "^3.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/recma-jsx": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/recma-jsx/-/recma-jsx-1.0.1.tgz",
+      "integrity": "sha512-huSIy7VU2Z5OLv6oFLosQGGDqPqdO1iq6bWNAdhzMxSJP7RAso4fCZ1cKu8j9YHCZf3TPrq4dw3okhrylgcd7w==",
+      "license": "MIT",
+      "dependencies": {
+        "acorn-jsx": "^5.0.0",
+        "estree-util-to-js": "^2.0.0",
+        "recma-parse": "^1.0.0",
+        "recma-stringify": "^1.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      },
+      "peerDependencies": {
+        "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      }
+    },
+    "node_modules/recma-parse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/recma-parse/-/recma-parse-1.0.0.tgz",
+      "integrity": "sha512-OYLsIGBB5Y5wjnSnQW6t3Xg7q3fQ7FWbw/vcXtORTnyaSFscOtABg+7Pnz6YZ6c27fG1/aN8CjfwoUEUIdwqWQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "esast-util-from-js": "^2.0.0",
+        "unified": "^11.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/recma-stringify": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/recma-stringify/-/recma-stringify-1.0.0.tgz",
+      "integrity": "sha512-cjwII1MdIIVloKvC9ErQ+OgAtwHBmcZ0Bg4ciz78FtbT8In39aAYbaA7zvxQ61xVMSPE8WxhLwLbhif4Js2C+g==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "estree-util-to-js": "^2.0.0",
+        "unified": "^11.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/regex": {
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/regex/-/regex-6.1.0.tgz",
+      "integrity": "sha512-6VwtthbV4o/7+OaAF9I5L5V3llLEsoPyq9P1JVXkedTP33c7MfCG0/5NOPcSJn0TzXcG9YUrR0gQSWioew3LDg==",
+      "license": "MIT",
+      "dependencies": {
+        "regex-utilities": "^2.3.0"
+      }
+    },
+    "node_modules/regex-recursion": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/regex-recursion/-/regex-recursion-6.0.2.tgz",
+      "integrity": "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==",
+      "license": "MIT",
+      "dependencies": {
+        "regex-utilities": "^2.3.0"
+      }
+    },
+    "node_modules/regex-utilities": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/regex-utilities/-/regex-utilities-2.3.0.tgz",
+      "integrity": "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==",
+      "license": "MIT"
+    },
+    "node_modules/rehype": {
+      "version": "13.0.2",
+      "resolved": "https://registry.npmjs.org/rehype/-/rehype-13.0.2.tgz",
+      "integrity": "sha512-j31mdaRFrwFRUIlxGeuPXXKWQxet52RBQRvCmzl5eCefn/KGbomK5GMHNMsOJf55fgo3qw5tST5neDuarDYR2A==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "rehype-parse": "^9.0.0",
+        "rehype-stringify": "^10.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/rehype-expressive-code": {
+      "version": "0.42.0",
+      "resolved": "https://registry.npmjs.org/rehype-expressive-code/-/rehype-expressive-code-0.42.0.tgz",
+      "integrity": "sha512-8rp/1YMEVVSYbtz+bFBx+uSx3vA4i4T8RwRm5Q/IWbucQnnQqQ0hDqtmKOr8tv+59Cik6cu5aH3WPo0I7csuTA==",
+      "license": "MIT",
+      "dependencies": {
+        "expressive-code": "^0.42.0"
+      }
+    },
+    "node_modules/rehype-format": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/rehype-format/-/rehype-format-5.0.1.tgz",
+      "integrity": "sha512-zvmVru9uB0josBVpr946OR8ui7nJEdzZobwLOOqHb/OOD88W0Vk2SqLwoVOj0fM6IPCCO6TaV9CvQvJMWwukFQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "hast-util-format": "^1.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/rehype-parse": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/rehype-parse/-/rehype-parse-9.0.1.tgz",
+      "integrity": "sha512-ksCzCD0Fgfh7trPDxr2rSylbwq9iYDkSn8TCDmEJ49ljEUBxDVCzCHv7QNzZOfODanX4+bWQ4WZqLCRWYLfhag==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "hast-util-from-html": "^2.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/rehype-raw": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/rehype-raw/-/rehype-raw-7.0.0.tgz",
+      "integrity": "sha512-/aE8hCfKlQeA8LmyeyQvQF3eBiLRGNlfBJEvWH7ivp9sBqs7TNqBL5X3v157rM4IFETqDnIOO+z5M/biZbo9Ww==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "hast-util-raw": "^9.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/rehype-recma": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/rehype-recma/-/rehype-recma-1.0.0.tgz",
+      "integrity": "sha512-lqA4rGUf1JmacCNWWZx0Wv1dHqMwxzsDWYMTowuplHF3xH0N/MmrZ/G3BDZnzAkRmxDadujCjaKM2hqYdCBOGw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/estree": "^1.0.0",
+        "@types/hast": "^3.0.0",
+        "hast-util-to-estree": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/rehype-stringify": {
+      "version": "10.0.1",
+      "resolved": "https://registry.npmjs.org/rehype-stringify/-/rehype-stringify-10.0.1.tgz",
+      "integrity": "sha512-k9ecfXHmIPuFVI61B9DeLPN0qFHfawM6RsuX48hoqlaKSF61RskNjSm1lI8PhBEM0MRdLxVVm4WmTqJQccH9mA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "hast-util-to-html": "^9.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/remark-directive": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/remark-directive/-/remark-directive-4.0.0.tgz",
+      "integrity": "sha512-7sxn4RfF1o3izevPV1DheyGDD6X4c9hrGpfdUpm7uC++dqrnJxIZVkk7CoKqcLm0VUMAuOol7Mno3m6g8cfMuA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-directive": "^3.0.0",
+        "micromark-extension-directive": "^4.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/remark-gfm": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.1.tgz",
+      "integrity": "sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-gfm": "^3.0.0",
+        "micromark-extension-gfm": "^3.0.0",
+        "remark-parse": "^11.0.0",
+        "remark-stringify": "^11.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/remark-mdx": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/remark-mdx/-/remark-mdx-3.1.1.tgz",
+      "integrity": "sha512-Pjj2IYlUY3+D8x00UJsIOg5BEvfMyeI+2uLPn9VO9Wg4MEtN/VTIq2NEJQfde9PnX15KgtHyl9S0BcTnWrIuWg==",
+      "license": "MIT",
+      "dependencies": {
+        "mdast-util-mdx": "^3.0.0",
+        "micromark-extension-mdxjs": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/remark-parse": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/remark-parse/-/remark-parse-11.0.0.tgz",
+      "integrity": "sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-from-markdown": "^2.0.0",
+        "micromark-util-types": "^2.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/remark-rehype": {
+      "version": "11.1.2",
+      "resolved": "https://registry.npmjs.org/remark-rehype/-/remark-rehype-11.1.2.tgz",
+      "integrity": "sha512-Dh7l57ianaEoIpzbp0PC9UKAdCSVklD8E5Rpw7ETfbTl3FqcOOgq5q2LVDhgGCkaBv7p24JXikPdvhhmHvKMsw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/hast": "^3.0.0",
+        "@types/mdast": "^4.0.0",
+        "mdast-util-to-hast": "^13.0.0",
+        "unified": "^11.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/remark-smartypants": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/remark-smartypants/-/remark-smartypants-3.0.2.tgz",
+      "integrity": "sha512-ILTWeOriIluwEvPjv67v7Blgrcx+LZOkAUVtKI3putuhlZm84FnqDORNXPPm+HY3NdZOMhyDwZ1E+eZB/Df5dA==",
+      "license": "MIT",
+      "dependencies": {
+        "retext": "^9.0.0",
+        "retext-smartypants": "^6.0.0",
+        "unified": "^11.0.4",
+        "unist-util-visit": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=16.0.0"
+      }
+    },
+    "node_modules/remark-stringify": {
+      "version": "11.0.0",
+      "resolved": "https://registry.npmjs.org/remark-stringify/-/remark-stringify-11.0.0.tgz",
+      "integrity": "sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/mdast": "^4.0.0",
+        "mdast-util-to-markdown": "^2.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/resolve-pkg-maps": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz",
+      "integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
+      }
+    },
+    "node_modules/retext": {
+      "version": "9.0.0",
+      "resolved": "https://registry.npmjs.org/retext/-/retext-9.0.0.tgz",
+      "integrity": "sha512-sbMDcpHCNjvlheSgMfEcVrZko3cDzdbe1x/e7G66dFp0Ff7Mldvi2uv6JkJQzdRcvLYE8CA8Oe8siQx8ZOgTcA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/nlcst": "^2.0.0",
+        "retext-latin": "^4.0.0",
+        "retext-stringify": "^4.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/retext-latin": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/retext-latin/-/retext-latin-4.0.0.tgz",
+      "integrity": "sha512-hv9woG7Fy0M9IlRQloq/N6atV82NxLGveq+3H2WOi79dtIYWN8OaxogDm77f8YnVXJL2VD3bbqowu5E3EMhBYA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/nlcst": "^2.0.0",
+        "parse-latin": "^7.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/retext-smartypants": {
+      "version": "6.2.0",
+      "resolved": "https://registry.npmjs.org/retext-smartypants/-/retext-smartypants-6.2.0.tgz",
+      "integrity": "sha512-kk0jOU7+zGv//kfjXEBjdIryL1Acl4i9XNkHxtM7Tm5lFiCog576fjNC9hjoR7LTKQ0DsPWy09JummSsH1uqfQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/nlcst": "^2.0.0",
+        "nlcst-to-string": "^4.0.0",
+        "unist-util-visit": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/retext-stringify": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/retext-stringify/-/retext-stringify-4.0.0.tgz",
+      "integrity": "sha512-rtfN/0o8kL1e+78+uxPTqu1Klt0yPzKuQ2BfWwwfgIUSayyzxpM1PJzkKt4V8803uB9qSy32MvI7Xep9khTpiA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/nlcst": "^2.0.0",
+        "nlcst-to-string": "^4.0.0",
+        "unified": "^11.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/rollup": {
+      "version": "4.60.4",
+      "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.60.4.tgz",
+      "integrity": "sha512-WHeFSbZYsPu3+bLoNRUuAO+wavNlocOPf3wSHTP7hcFKVnJeWsYlCDbr3mTS14FCizf9ccIxXA8sGL8zKeQN3g==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "@types/estree": "1.0.8"
+      },
+      "bin": {
+        "rollup": "dist/bin/rollup"
+      },
+      "engines": {
+        "node": ">=18.0.0",
+        "npm": ">=8.0.0"
+      },
+      "optionalDependencies": {
+        "@rollup/rollup-android-arm-eabi": "4.60.4",
+        "@rollup/rollup-android-arm64": "4.60.4",
+        "@rollup/rollup-darwin-arm64": "4.60.4",
+        "@rollup/rollup-darwin-x64": "4.60.4",
+        "@rollup/rollup-freebsd-arm64": "4.60.4",
+        "@rollup/rollup-freebsd-x64": "4.60.4",
+        "@rollup/rollup-linux-arm-gnueabihf": "4.60.4",
+        "@rollup/rollup-linux-arm-musleabihf": "4.60.4",
+        "@rollup/rollup-linux-arm64-gnu": "4.60.4",
+        "@rollup/rollup-linux-arm64-musl": "4.60.4",
+        "@rollup/rollup-linux-loong64-gnu": "4.60.4",
+        "@rollup/rollup-linux-loong64-musl": "4.60.4",
+        "@rollup/rollup-linux-ppc64-gnu": "4.60.4",
+        "@rollup/rollup-linux-ppc64-musl": "4.60.4",
+        "@rollup/rollup-linux-riscv64-gnu": "4.60.4",
+        "@rollup/rollup-linux-riscv64-musl": "4.60.4",
+        "@rollup/rollup-linux-s390x-gnu": "4.60.4",
+        "@rollup/rollup-linux-x64-gnu": "4.60.4",
+        "@rollup/rollup-linux-x64-musl": "4.60.4",
+        "@rollup/rollup-openbsd-x64": "4.60.4",
+        "@rollup/rollup-openharmony-arm64": "4.60.4",
+        "@rollup/rollup-win32-arm64-msvc": "4.60.4",
+        "@rollup/rollup-win32-ia32-msvc": "4.60.4",
+        "@rollup/rollup-win32-x64-gnu": "4.60.4",
+        "@rollup/rollup-win32-x64-msvc": "4.60.4",
+        "fsevents": "~2.3.2"
+      }
+    },
+    "node_modules/rollup/node_modules/@types/estree": {
+      "version": "1.0.8",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
+      "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==",
+      "license": "MIT"
+    },
+    "node_modules/sax": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/sax/-/sax-1.6.0.tgz",
+      "integrity": "sha512-6R3J5M4AcbtLUdZmRv2SygeVaM7IhrLXu9BmnOGmmACak8fiUtOsYNWUS4uK7upbmHIBbLBeFeI//477BKLBzA==",
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": ">=11.0.0"
+      }
+    },
+    "node_modules/semver": {
+      "version": "7.8.1",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.1.tgz",
+      "integrity": "sha512-rkVq3IXh+4FDGch+KwzX3aV9W3kO54GyEgpvBzSyctDA6Xtd7RJQV1xmXbeQp5v7+VzLOfVqiutSE6GICgPFvg==",
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/sharp": {
+      "version": "0.34.5",
+      "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.34.5.tgz",
+      "integrity": "sha512-Ou9I5Ft9WNcCbXrU9cMgPBcCK8LiwLqcbywW3t4oDV37n1pzpuNLsYiAV8eODnjbtQlSDwZ2cUEeQz4E54Hltg==",
+      "hasInstallScript": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@img/colour": "^1.0.0",
+        "detect-libc": "^2.1.2",
+        "semver": "^7.7.3"
+      },
+      "engines": {
+        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/libvips"
+      },
+      "optionalDependencies": {
+        "@img/sharp-darwin-arm64": "0.34.5",
+        "@img/sharp-darwin-x64": "0.34.5",
+        "@img/sharp-libvips-darwin-arm64": "1.2.4",
+        "@img/sharp-libvips-darwin-x64": "1.2.4",
+        "@img/sharp-libvips-linux-arm": "1.2.4",
+        "@img/sharp-libvips-linux-arm64": "1.2.4",
+        "@img/sharp-libvips-linux-ppc64": "1.2.4",
+        "@img/sharp-libvips-linux-riscv64": "1.2.4",
+        "@img/sharp-libvips-linux-s390x": "1.2.4",
+        "@img/sharp-libvips-linux-x64": "1.2.4",
+        "@img/sharp-libvips-linuxmusl-arm64": "1.2.4",
+        "@img/sharp-libvips-linuxmusl-x64": "1.2.4",
+        "@img/sharp-linux-arm": "0.34.5",
+        "@img/sharp-linux-arm64": "0.34.5",
+        "@img/sharp-linux-ppc64": "0.34.5",
+        "@img/sharp-linux-riscv64": "0.34.5",
+        "@img/sharp-linux-s390x": "0.34.5",
+        "@img/sharp-linux-x64": "0.34.5",
+        "@img/sharp-linuxmusl-arm64": "0.34.5",
+        "@img/sharp-linuxmusl-x64": "0.34.5",
+        "@img/sharp-wasm32": "0.34.5",
+        "@img/sharp-win32-arm64": "0.34.5",
+        "@img/sharp-win32-ia32": "0.34.5",
+        "@img/sharp-win32-x64": "0.34.5"
+      }
+    },
+    "node_modules/shiki": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/shiki/-/shiki-4.1.0.tgz",
+      "integrity": "sha512-l/ABZPUR5v70jI10EzqfMS/I96vjSGv2y0ihUV+WYFzv0EfvW4s54m0Lg8wCrrL+2IkwBzFTuxkZjPf8b2NX9Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@shikijs/core": "4.1.0",
+        "@shikijs/engine-javascript": "4.1.0",
+        "@shikijs/engine-oniguruma": "4.1.0",
+        "@shikijs/langs": "4.1.0",
+        "@shikijs/themes": "4.1.0",
+        "@shikijs/types": "4.1.0",
+        "@shikijs/vscode-textmate": "^10.0.2",
+        "@types/hast": "^3.0.4"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/sisteransi": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz",
+      "integrity": "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==",
+      "license": "MIT"
+    },
+    "node_modules/sitemap": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/sitemap/-/sitemap-9.0.1.tgz",
+      "integrity": "sha512-S6hzjGJSG3d6if0YoF5kTyeRJvia6FSTBroE5fQ0bu1QNxyJqhhinfUsXi9fH3MgtXODWvwo2BDyQSnhPQ88uQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "^24.9.2",
+        "@types/sax": "^1.2.1",
+        "arg": "^5.0.0",
+        "sax": "^1.4.1"
+      },
+      "bin": {
+        "sitemap": "dist/esm/cli.js"
+      },
+      "engines": {
+        "node": ">=20.19.5",
+        "npm": ">=10.8.2"
+      }
+    },
+    "node_modules/smol-toml": {
+      "version": "1.6.1",
+      "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.6.1.tgz",
+      "integrity": "sha512-dWUG8F5sIIARXih1DTaQAX4SsiTXhInKf1buxdY9DIg4ZYPZK5nGM1VRIYmEbDbsHt7USo99xSLFu5Q1IqTmsg==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">= 18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/cyyynthia"
+      }
+    },
+    "node_modules/source-map": {
+      "version": "0.7.6",
+      "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.7.6.tgz",
+      "integrity": "sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">= 12"
+      }
+    },
+    "node_modules/source-map-js": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
+      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/space-separated-tokens": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/space-separated-tokens/-/space-separated-tokens-2.0.2.tgz",
+      "integrity": "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/stream-replace-string": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/stream-replace-string/-/stream-replace-string-2.0.0.tgz",
+      "integrity": "sha512-TlnjJ1C0QrmxRNrON00JvaFFlNh5TTG00APw23j74ET7gkQpTASi6/L2fuiav8pzK715HXtUeClpBTw2NPSn6w==",
+      "license": "MIT"
+    },
+    "node_modules/stringify-entities": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz",
+      "integrity": "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==",
+      "license": "MIT",
+      "dependencies": {
+        "character-entities-html4": "^2.0.0",
+        "character-entities-legacy": "^3.0.0"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/style-to-js": {
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/style-to-js/-/style-to-js-1.1.21.tgz",
+      "integrity": "sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==",
+      "license": "MIT",
+      "dependencies": {
+        "style-to-object": "1.0.14"
+      }
+    },
+    "node_modules/style-to-object": {
+      "version": "1.0.14",
+      "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-1.0.14.tgz",
+      "integrity": "sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==",
+      "license": "MIT",
+      "dependencies": {
+        "inline-style-parser": "0.2.7"
+      }
+    },
+    "node_modules/svgo": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/svgo/-/svgo-4.0.1.tgz",
+      "integrity": "sha512-XDpWUOPC6FEibaLzjfe0ucaV0YrOjYotGJO1WpF0Zd+n6ZGEQUsSugaoLq9QkEZtAfQIxT42UChcssDVPP3+/w==",
+      "license": "MIT",
+      "dependencies": {
+        "commander": "^11.1.0",
+        "css-select": "^5.1.0",
+        "css-tree": "^3.0.1",
+        "css-what": "^6.1.0",
+        "csso": "^5.0.5",
+        "picocolors": "^1.1.1",
+        "sax": "^1.5.0"
+      },
+      "bin": {
+        "svgo": "bin/svgo.js"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/svgo"
+      }
+    },
+    "node_modules/tiny-inflate": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/tiny-inflate/-/tiny-inflate-1.0.3.tgz",
+      "integrity": "sha512-pkY1fj1cKHb2seWDy0B16HeWyczlJA9/WW3u3c4z/NiWDsO3DOU5D7nhTLE9CF0yXv/QZFY7sEJmj24dK+Rrqw==",
+      "license": "MIT"
+    },
+    "node_modules/tinyclip": {
+      "version": "0.1.12",
+      "resolved": "https://registry.npmjs.org/tinyclip/-/tinyclip-0.1.12.tgz",
+      "integrity": "sha512-Ae3OVUqifDw0wBriIBS7yVaW44Dp6eSHQcyq4Igc7eN2TJH/2YsicswaW+J/OuMvhpDPOKEgpAZCjkb4hpoyeA==",
+      "license": "MIT",
+      "engines": {
+        "node": "^16.14.0 || >= 17.3.0"
+      }
+    },
+    "node_modules/tinyexec": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.2.2.tgz",
+      "integrity": "sha512-M/Q0B2cp4K7kynaT/vnED1j8TlLY+Pp7C6Wl2bl/7u/F0mUVwdyOpwomQb8JpYLitHUssAJRmLZdMCGsrx7i+g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/tinyglobby": {
+      "version": "0.2.16",
+      "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.16.tgz",
+      "integrity": "sha512-pn99VhoACYR8nFHhxqix+uvsbXineAasWm5ojXoN8xEwK5Kd3/TrhNn1wByuD52UxWRLy8pu+kRMniEi6Eq9Zg==",
+      "license": "MIT",
+      "dependencies": {
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.4"
+      },
+      "engines": {
+        "node": ">=12.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/SuperchupuDev"
+      }
+    },
+    "node_modules/trim-lines": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz",
+      "integrity": "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/trough": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/trough/-/trough-2.2.0.tgz",
+      "integrity": "sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "license": "0BSD",
+      "optional": true
+    },
+    "node_modules/ufo": {
+      "version": "1.6.4",
+      "resolved": "https://registry.npmjs.org/ufo/-/ufo-1.6.4.tgz",
+      "integrity": "sha512-JFNbkD1Svwe0KvGi8GOeLcP4kAWQ609twvCdcHxq1oSL8svv39ZuSvajcD8B+5D0eL4+s1Is2D/O6KN3qcTeRA==",
+      "license": "MIT"
+    },
+    "node_modules/ultrahtml": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/ultrahtml/-/ultrahtml-1.6.0.tgz",
+      "integrity": "sha512-R9fBn90VTJrqqLDwyMph+HGne8eqY1iPfYhPzZrvKpIfwkWZbcYlfpsb8B9dTvBfpy1/hqAD7Wi8EKfP9e8zdw==",
+      "license": "MIT"
+    },
+    "node_modules/uncrypto": {
+      "version": "0.1.3",
+      "resolved": "https://registry.npmjs.org/uncrypto/-/uncrypto-0.1.3.tgz",
+      "integrity": "sha512-Ql87qFHB3s/De2ClA9e0gsnS6zXG27SkTiSJwjCc9MebbfapQfuPzumMIUMi38ezPZVNFcHI9sUIepeQfw8J8Q==",
+      "license": "MIT"
+    },
+    "node_modules/undici-types": {
+      "version": "7.16.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.16.0.tgz",
+      "integrity": "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==",
+      "license": "MIT"
+    },
+    "node_modules/unified": {
+      "version": "11.0.5",
+      "resolved": "https://registry.npmjs.org/unified/-/unified-11.0.5.tgz",
+      "integrity": "sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "bail": "^2.0.0",
+        "devlop": "^1.0.0",
+        "extend": "^3.0.0",
+        "is-plain-obj": "^4.0.0",
+        "trough": "^2.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unifont": {
+      "version": "0.7.4",
+      "resolved": "https://registry.npmjs.org/unifont/-/unifont-0.7.4.tgz",
+      "integrity": "sha512-oHeis4/xl42HUIeHuNZRGEvxj5AaIKR+bHPNegRq5LV1gdc3jundpONbjglKpihmJf+dswygdMJn3eftGIMemg==",
+      "license": "MIT",
+      "dependencies": {
+        "css-tree": "^3.1.0",
+        "ofetch": "^1.5.1",
+        "ohash": "^2.0.11"
+      }
+    },
+    "node_modules/unist-util-find-after": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/unist-util-find-after/-/unist-util-find-after-5.0.0.tgz",
+      "integrity": "sha512-amQa0Ep2m6hE2g72AugUItjbuM8X8cGQnFoHk0pGfrFeT9GZhzN5SW8nRsiGKK7Aif4CrACPENkA6P/Lw6fHGQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "unist-util-is": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-is": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.1.tgz",
+      "integrity": "sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-modify-children": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/unist-util-modify-children/-/unist-util-modify-children-4.0.0.tgz",
+      "integrity": "sha512-+tdN5fGNddvsQdIzUF3Xx82CU9sMM+fA0dLgR9vOmT0oPT2jH+P1nd5lSqfCfXAw+93NhcXNY2qqvTUtE4cQkw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "array-iterate": "^2.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-position": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/unist-util-position/-/unist-util-position-5.0.0.tgz",
+      "integrity": "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-position-from-estree": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/unist-util-position-from-estree/-/unist-util-position-from-estree-2.0.0.tgz",
+      "integrity": "sha512-KaFVRjoqLyF6YXCbVLNad/eS4+OfPQQn2yOd7zF/h5T/CSL2v8NpN6a5TPvtbXthAGw5nG+PuTtq+DdIZr+cRQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-remove-position": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/unist-util-remove-position/-/unist-util-remove-position-5.0.0.tgz",
+      "integrity": "sha512-Hp5Kh3wLxv0PHj9m2yZhhLt58KzPtEYKQQ4yxfYFEO7EvHwzyDYnduhHnY1mDxoqr7VUwVuHXk9RXKIiYS1N8Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "unist-util-visit": "^5.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-stringify-position": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz",
+      "integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-visit": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.1.0.tgz",
+      "integrity": "sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "unist-util-is": "^6.0.0",
+        "unist-util-visit-parents": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-visit-children": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/unist-util-visit-children/-/unist-util-visit-children-3.0.0.tgz",
+      "integrity": "sha512-RgmdTfSBOg04sdPcpTSD1jzoNBjt9a80/ZCzp5cI9n1qPzLZWF9YdvWGN2zmTumP1HWhXKdUWexjy/Wy/lJ7tA==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unist-util-visit-parents": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-6.0.2.tgz",
+      "integrity": "sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "unist-util-is": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/unstorage": {
+      "version": "1.17.5",
+      "resolved": "https://registry.npmjs.org/unstorage/-/unstorage-1.17.5.tgz",
+      "integrity": "sha512-0i3iqvRfx29hkNntHyQvJTpf5W9dQ9ZadSoRU8+xVlhVtT7jAX57fazYO9EHvcRCfBCyi5YRya7XCDOsbTgkPg==",
+      "license": "MIT",
+      "dependencies": {
+        "anymatch": "^3.1.3",
+        "chokidar": "^5.0.0",
+        "destr": "^2.0.5",
+        "h3": "^1.15.10",
+        "lru-cache": "^11.2.7",
+        "node-fetch-native": "^1.6.7",
+        "ofetch": "^1.5.1",
+        "ufo": "^1.6.3"
+      },
+      "peerDependencies": {
+        "@azure/app-configuration": "^1.8.0",
+        "@azure/cosmos": "^4.2.0",
+        "@azure/data-tables": "^13.3.0",
+        "@azure/identity": "^4.6.0",
+        "@azure/keyvault-secrets": "^4.9.0",
+        "@azure/storage-blob": "^12.26.0",
+        "@capacitor/preferences": "^6 || ^7 || ^8",
+        "@deno/kv": ">=0.9.0",
+        "@netlify/blobs": "^6.5.0 || ^7.0.0 || ^8.1.0 || ^9.0.0 || ^10.0.0",
+        "@planetscale/database": "^1.19.0",
+        "@upstash/redis": "^1.34.3",
+        "@vercel/blob": ">=0.27.1",
+        "@vercel/functions": "^2.2.12 || ^3.0.0",
+        "@vercel/kv": "^1 || ^2 || ^3",
+        "aws4fetch": "^1.0.20",
+        "db0": ">=0.2.1",
+        "idb-keyval": "^6.2.1",
+        "ioredis": "^5.4.2",
+        "uploadthing": "^7.4.4"
+      },
+      "peerDependenciesMeta": {
+        "@azure/app-configuration": {
+          "optional": true
+        },
+        "@azure/cosmos": {
+          "optional": true
+        },
+        "@azure/data-tables": {
+          "optional": true
+        },
+        "@azure/identity": {
+          "optional": true
+        },
+        "@azure/keyvault-secrets": {
+          "optional": true
+        },
+        "@azure/storage-blob": {
+          "optional": true
+        },
+        "@capacitor/preferences": {
+          "optional": true
+        },
+        "@deno/kv": {
+          "optional": true
+        },
+        "@netlify/blobs": {
+          "optional": true
+        },
+        "@planetscale/database": {
+          "optional": true
+        },
+        "@upstash/redis": {
+          "optional": true
+        },
+        "@vercel/blob": {
+          "optional": true
+        },
+        "@vercel/functions": {
+          "optional": true
+        },
+        "@vercel/kv": {
+          "optional": true
+        },
+        "aws4fetch": {
+          "optional": true
+        },
+        "db0": {
+          "optional": true
+        },
+        "idb-keyval": {
+          "optional": true
+        },
+        "ioredis": {
+          "optional": true
+        },
+        "uploadthing": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/util-deprecate": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
+      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
+      "license": "MIT"
+    },
+    "node_modules/vfile": {
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz",
+      "integrity": "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "vfile-message": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/vfile-location": {
+      "version": "5.0.3",
+      "resolved": "https://registry.npmjs.org/vfile-location/-/vfile-location-5.0.3.tgz",
+      "integrity": "sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "vfile": "^6.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/vfile-message": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.3.tgz",
+      "integrity": "sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/unist": "^3.0.0",
+        "unist-util-stringify-position": "^4.0.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/unified"
+      }
+    },
+    "node_modules/vite": {
+      "version": "7.3.3",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-7.3.3.tgz",
+      "integrity": "sha512-/4XH147Ui7OGTjg3HbdWe5arnZQSbfuRzdr9Ec7TQi5I7R+ir0Rlc9GIvD4v0XZurELqA035KVXJXpR61xhiTA==",
+      "license": "MIT",
+      "peer": true,
+      "dependencies": {
+        "esbuild": "^0.27.0",
+        "fdir": "^6.5.0",
+        "picomatch": "^4.0.3",
+        "postcss": "^8.5.6",
+        "rollup": "^4.43.0",
+        "tinyglobby": "^0.2.15"
+      },
+      "bin": {
+        "vite": "bin/vite.js"
+      },
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      },
+      "funding": {
+        "url": "https://github.com/vitejs/vite?sponsor=1"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      },
+      "peerDependencies": {
+        "@types/node": "^20.19.0 || >=22.12.0",
+        "jiti": ">=1.21.0",
+        "less": "^4.0.0",
+        "lightningcss": "^1.21.0",
+        "sass": "^1.70.0",
+        "sass-embedded": "^1.70.0",
+        "stylus": ">=0.54.8",
+        "sugarss": "^5.0.0",
+        "terser": "^5.16.0",
+        "tsx": "^4.8.1",
+        "yaml": "^2.4.2"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        },
+        "jiti": {
+          "optional": true
+        },
+        "less": {
+          "optional": true
+        },
+        "lightningcss": {
+          "optional": true
+        },
+        "sass": {
+          "optional": true
+        },
+        "sass-embedded": {
+          "optional": true
+        },
+        "stylus": {
+          "optional": true
+        },
+        "sugarss": {
+          "optional": true
+        },
+        "terser": {
+          "optional": true
+        },
+        "tsx": {
+          "optional": true
+        },
+        "yaml": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/vitefu": {
+      "version": "1.1.3",
+      "resolved": "https://registry.npmjs.org/vitefu/-/vitefu-1.1.3.tgz",
+      "integrity": "sha512-ub4okH7Z5KLjb6hDyjqrGXqWtWvoYdU3IGm/NorpgHncKoLTCfRIbvlhBm7r0YstIaQRYlp4yEbFqDcKSzXSSg==",
+      "license": "MIT",
+      "workspaces": [
+        "tests/deps/*",
+        "tests/projects/*",
+        "tests/projects/workspace/packages/*"
+      ],
+      "peerDependencies": {
+        "vite": "^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0"
+      },
+      "peerDependenciesMeta": {
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/web-namespaces": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/web-namespaces/-/web-namespaces-2.0.1.tgz",
+      "integrity": "sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
+    "node_modules/which-pm-runs": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/which-pm-runs/-/which-pm-runs-1.1.0.tgz",
+      "integrity": "sha512-n1brCuqClxfFfq/Rb0ICg9giSZqCS+pLtccdag6C2HyufBrh3fBOiy9nb6ggRMvWOVH5GrdJskj5iGTZNxd7SA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/xxhash-wasm": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/xxhash-wasm/-/xxhash-wasm-1.1.0.tgz",
+      "integrity": "sha512-147y/6YNh+tlp6nd/2pWq38i9h6mz/EuQ6njIrmW8D1BS5nCqs0P6DG+m6zTGnNz5I+uhZ0SHxBs9BsPrwcKDA==",
+      "license": "MIT"
+    },
+    "node_modules/yargs-parser": {
+      "version": "22.0.0",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-22.0.0.tgz",
+      "integrity": "sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw==",
+      "license": "ISC",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=23"
+      }
+    },
+    "node_modules/yocto-queue": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-1.2.2.tgz",
+      "integrity": "sha512-4LCcse/U2MHZ63HAJVE+v71o7yOdIe4cZ70Wpf8D/IyjDKYQLV5GD46B+hSTjJsvV5PztjvHoU580EftxjDZFQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/zod": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/colinhacks"
+      }
+    },
+    "node_modules/zwitch": {
+      "version": "2.0.4",
+      "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz",
+      "integrity": "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    }
+  }
+}
diff --git a/site/package.json b/site/package.json
new file mode 100644
index 000000000..37ab57b59
--- /dev/null
+++ b/site/package.json
@@ -0,0 +1,19 @@
+{
+  "name": "site",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.39.2",
+    "@fontsource-variable/archivo": "^5.2.8",
+    "@fontsource/ibm-plex-mono": "^5.2.7",
+    "astro": "^6.3.1",
+    "sharp": "^0.34.5"
+  }
+}
diff --git a/site/public/favicon.svg b/site/public/favicon.svg
new file mode 100644
index 000000000..2dc717237
--- /dev/null
+++ b/site/public/favicon.svg
@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" fill="none" stroke="#16150f" stroke-width="2">
+  <line x1="16" y1="8" x2="8" y2="23" />
+  <line x1="16" y1="8" x2="24" y2="23" />
+  <line x1="8" y1="23" x2="24" y2="23" />
+  <circle cx="16" cy="8" r="3.4" fill="#16150f" />
+  <circle cx="8" cy="23" r="3.4" fill="#f7f6f2" />
+  <circle cx="24" cy="23" r="3.4" fill="#f7f6f2" />
+</svg>
diff --git a/site/src/components/GraphDiagram.astro b/site/src/components/GraphDiagram.astro
new file mode 100644
index 000000000..adfe463df
--- /dev/null
+++ b/site/src/components/GraphDiagram.astro
@@ -0,0 +1,86 @@
+---
+// Flat technical node-link diagram for the hero. Hand-placed so it reads as a
+// deliberate blueprint, not a physics blob: thin ink lines, hollow nodes, mono
+// labels. Hovering a node inks it in. No glow, no gradients, no motion.
+---
+
+<svg
+	class="cg-graph"
+	viewBox="0 0 780 600"
+	role="img"
+	aria-label="A code knowledge graph: index.ts links to auth.ts, router.ts and api/users.ts, which branch to middleware.ts, types/index.ts, createRouter and listUsers."
+>
+	<g class="edges">
+		<line x1="430" y1="64" x2="250" y2="210" />
+		<line x1="430" y1="64" x2="450" y2="250" />
+		<line x1="430" y1="64" x2="650" y2="200" />
+		<line x1="250" y1="210" x2="180" y2="380" />
+		<line x1="250" y1="210" x2="340" y2="380" />
+		<line x1="450" y1="250" x2="560" y2="380" />
+		<line x1="560" y1="380" x2="560" y2="500" />
+	</g>
+
+	<g class="nodes">
+		<g class="node">
+			<circle cx="430" cy="64" r="9" />
+			<text x="448" y="69" text-anchor="start">index.ts</text>
+		</g>
+		<g class="node">
+			<circle cx="250" cy="210" r="9" />
+			<text x="232" y="215" text-anchor="end">auth.ts</text>
+		</g>
+		<g class="node">
+			<circle cx="450" cy="250" r="9" />
+			<text x="468" y="255" text-anchor="start">router.ts</text>
+		</g>
+		<g class="node">
+			<circle cx="650" cy="200" r="9" />
+			<text x="668" y="205" text-anchor="start">api/users.ts</text>
+		</g>
+		<g class="node">
+			<circle cx="180" cy="380" r="9" />
+			<text x="180" y="410" text-anchor="middle">middleware.ts</text>
+		</g>
+		<g class="node">
+			<circle cx="340" cy="380" r="9" />
+			<text x="340" y="410" text-anchor="middle">types/index.ts</text>
+		</g>
+		<g class="node">
+			<circle cx="560" cy="380" r="9" />
+			<text x="578" y="385" text-anchor="start">createRouter</text>
+		</g>
+		<g class="node">
+			<circle cx="560" cy="500" r="9" />
+			<text x="560" y="530" text-anchor="middle">listUsers</text>
+		</g>
+	</g>
+</svg>
+
+<style>
+	.cg-graph {
+		width: 100%;
+		height: auto;
+		max-width: 560px;
+		min-width: 0; /* flex item: allow shrinking below intrinsic SVG width */
+		display: block;
+	}
+	.cg-graph .edges line {
+		stroke: var(--cg-ink);
+		stroke-width: 1.25;
+	}
+	.cg-graph .node circle {
+		fill: var(--cg-paper);
+		stroke: var(--cg-ink);
+		stroke-width: 1.5;
+		transition: fill 0.12s ease;
+	}
+	.cg-graph .node text {
+		font-family: var(--sl-font-mono);
+		font-size: 15px;
+		fill: var(--cg-ink);
+		dominant-baseline: middle;
+	}
+	.cg-graph .node:hover circle {
+		fill: var(--cg-ink);
+	}
+</style>
diff --git a/site/src/components/SiteTitle.astro b/site/src/components/SiteTitle.astro
new file mode 100644
index 000000000..f0dd3daeb
--- /dev/null
+++ b/site/src/components/SiteTitle.astro
@@ -0,0 +1,24 @@
+---
+// Starlight 0.39 exposes route data on Astro.locals.starlightRoute (not props).
+// Link the wordmark to the landing page at the site root.
+const { siteTitle } = Astro.locals.starlightRoute;
+const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+---
+
+<a href={`${base}/`} class="cg-site-title" translate="no">{siteTitle}</a>
+
+<style>
+	.cg-site-title {
+		font-family: var(--sl-font);
+		font-weight: 800;
+		font-size: 1.25rem;
+		letter-spacing: -0.025em;
+		line-height: 1;
+		color: var(--cg-ink);
+		text-decoration: none;
+		white-space: nowrap;
+	}
+	.cg-site-title:hover {
+		color: var(--cg-ink);
+	}
+</style>
diff --git a/site/src/components/SocialIcons.astro b/site/src/components/SocialIcons.astro
new file mode 100644
index 000000000..752c241ed
--- /dev/null
+++ b/site/src/components/SocialIcons.astro
@@ -0,0 +1,70 @@
+---
+// Docs-header right cluster: Docs + Languages text links, Starlight's default
+// social icons (the GitHub link), and a live star-count pill — same order as
+// the landing nav (Docs · Languages · GitHub · Star). Done here, in the slot we
+// already own, to avoid a full header rebuild that could break search/mobile.
+import Default from '@astrojs/starlight/components/SocialIcons.astro';
+import { getStarsLabel } from '../lib/github';
+
+const stars = await getStarsLabel();
+const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+const repo = 'https://github.com/colbymchenry/codegraph';
+---
+
+<a class="cg-navlink" href={`${base}/getting-started/introduction/`}>Docs</a>
+<a class="cg-navlink" href={`${base}/reference/languages/`}>Languages</a>
+<Default {...Astro.props} />
+<a
+	class="cg-star"
+	href={`${repo}/stargazers`}
+	target="_blank"
+	rel="noopener noreferrer"
+	aria-label={`${stars} GitHub stars`}
+>
+	<span class="cg-star-glyph" aria-hidden="true">★</span>{stars}
+</a>
+
+<style>
+	.cg-navlink {
+		font-family: var(--sl-font);
+		font-size: 0.9rem;
+		font-weight: 500;
+		line-height: 1;
+		color: var(--cg-ink);
+		text-decoration: none;
+		white-space: nowrap;
+	}
+	.cg-navlink:hover {
+		text-decoration: underline;
+		text-underline-offset: 4px;
+	}
+	.cg-star {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.35rem;
+		border: 1px solid var(--cg-rule);
+		padding: 0.32rem 0.6rem;
+		font-family: var(--sl-font);
+		font-size: 0.85rem;
+		font-weight: 600;
+		line-height: 1;
+		color: var(--cg-ink);
+		text-decoration: none;
+		white-space: nowrap;
+		font-variant-numeric: tabular-nums;
+	}
+	.cg-star:hover {
+		background: var(--cg-paper-press);
+		color: var(--cg-ink);
+	}
+	.cg-star-glyph {
+		font-size: 0.85em;
+	}
+	/* Keep the compact mobile header clean — the sidebar covers navigation there. */
+	@media (max-width: 50rem) {
+		.cg-navlink,
+		.cg-star {
+			display: none;
+		}
+	}
+</style>
diff --git a/site/src/content.config.ts b/site/src/content.config.ts
new file mode 100644
index 000000000..d9ee8c9d1
--- /dev/null
+++ b/site/src/content.config.ts
@@ -0,0 +1,7 @@
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};
diff --git a/site/src/content/docs/core-concepts/how-it-works.md b/site/src/content/docs/core-concepts/how-it-works.md
new file mode 100644
index 000000000..ee5aaed1e
--- /dev/null
+++ b/site/src/content/docs/core-concepts/how-it-works.md
@@ -0,0 +1,32 @@
+---
+title: How It Works
+description: The extraction, storage, resolution, and auto-sync pipeline.
+---
+
+CodeGraph turns source code into a queryable graph in four stages.
+
+```
+files → Extraction (tree-sitter) → DB (nodes/edges/files)
+            ↓
+      Resolution (imports, name-matching, framework patterns)
+            ↓
+      Graph queries (callers, callees, impact)
+            ↓
+      Context building (markdown / JSON for AI consumption)
+```
+
+## 1. Extraction
+
+[tree-sitter](https://tree-sitter.github.io/) parses source into ASTs. Language-specific queries extract **nodes** (functions, classes, methods, types…) and **edges** (calls, imports, extends, implements). Heavy parsing runs off the main thread.
+
+## 2. Storage
+
+Everything goes into a local SQLite database (`.codegraph/codegraph.db`) with FTS5 full-text search. CodeGraph uses native `better-sqlite3` when available and transparently falls back to a WASM backend; `codegraph status` shows which is live.
+
+## 3. Resolution
+
+After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns. Some dynamic-dispatch boundaries (callbacks, observers, React re-render, JSX children) are bridged by synthesizers so flows connect end-to-end. See [Resolution & Frameworks](/codegraph/core-concepts/resolution/).
+
+## 4. Auto-sync
+
+The MCP server watches your project using native OS file events (FSEvents / inotify / ReadDirectoryChangesW). Changes are debounced, filtered to source files, and incrementally synced — the graph stays fresh as you code, with no configuration.
diff --git a/site/src/content/docs/core-concepts/knowledge-graph.md b/site/src/content/docs/core-concepts/knowledge-graph.md
new file mode 100644
index 000000000..2d43baac2
--- /dev/null
+++ b/site/src/content/docs/core-concepts/knowledge-graph.md
@@ -0,0 +1,27 @@
+---
+title: The Knowledge Graph
+description: The node and edge kinds the graph is built from.
+---
+
+CodeGraph stores three things: **nodes** (symbols and files), **edges** (relationships between them), and **files**. Every node and edge carries an exact `kind`, drawn from a fixed vocabulary so queries are consistent across languages.
+
+## Node kinds
+
+`file`, `module`, `class`, `struct`, `interface`, `trait`, `protocol`, `function`, `method`, `property`, `field`, `variable`, `constant`, `enum`, `enum_member`, `type_alias`, `namespace`, `parameter`, `import`, `export`, `route`, `component`.
+
+## Edge kinds
+
+`contains`, `calls`, `imports`, `exports`, `extends`, `implements`, `references`, `type_of`, `returns`, `instantiates`, `overrides`, `decorates`.
+
+## Provenance
+
+Most edges come straight from the AST. A few — at dynamic-dispatch boundaries that static parsing can't follow — are **synthesized** and marked with `provenance: 'heuristic'` plus the wiring site that created them. These are surfaced inline in `explore` and the `node` trail, so an agent can see exactly where a connection came from.
+
+## Querying it
+
+- **Search** symbols by name (FTS5).
+- **Callers / callees** walk the call graph one hop at a time.
+- **Impact** computes the transitive radius affected by a change.
+- **Explore** returns source for several related symbols grouped by file, plus the call path among them, in one call.
+
+See the [CLI](/codegraph/reference/cli/) and [MCP Server](/codegraph/reference/mcp-server/) references for how to run these.
diff --git a/site/src/content/docs/core-concepts/resolution.md b/site/src/content/docs/core-concepts/resolution.md
new file mode 100644
index 000000000..444b29f5d
--- /dev/null
+++ b/site/src/content/docs/core-concepts/resolution.md
@@ -0,0 +1,30 @@
+---
+title: Resolution & Frameworks
+description: How CodeGraph connects references and links routes to handlers.
+---
+
+Extraction produces nodes and raw edges; **resolution** turns names into real connections.
+
+## Reference resolution
+
+After parsing, CodeGraph resolves:
+
+- **Imports** → the source files they point at (including tsconfig path aliases and cargo workspace members).
+- **Calls** → their definitions, by import resolution and name matching.
+- **Inheritance** → `extends` / `implements` between types.
+
+## Framework awareness
+
+CodeGraph recognizes web-framework routing files and emits `route` nodes linked by `references` edges to their handler classes or functions — so querying the callers of a view or controller surfaces the URL pattern that binds it. See [Framework Routes](/codegraph/guides/framework-routes/) for the full list of recognized frameworks.
+
+## Dynamic-dispatch coverage
+
+Static parsing misses computed and indirect calls, so flows can break at dynamic dispatch. CodeGraph bridges several of these boundaries with synthesizers so a flow connects end-to-end:
+
+- Callback / observer registration
+- `EventEmitter` channels
+- React re-render (`setState` → `render`)
+- JSX child (`render` → child component)
+- Django ORM descriptors
+
+Every synthesized edge is marked `provenance: 'heuristic'` with the site that wired it, and is shown inline wherever a path crosses it.
diff --git a/site/src/content/docs/getting-started/configuration.md b/site/src/content/docs/getting-started/configuration.md
new file mode 100644
index 000000000..bba4ddb92
--- /dev/null
+++ b/site/src/content/docs/getting-started/configuration.md
@@ -0,0 +1,22 @@
+---
+title: Configuration
+description: CodeGraph is zero-config — there are no config files.
+---
+
+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.
+
+## What it skips out of the box
+
+- **Dependency, build, and cache directories** — `node_modules`, `vendor`, `dist`, `build`, `target`, `.venv`, `Pods`, `.next`, and the like across every [supported stack](/codegraph/reference/languages/) — so the graph is your code, not third-party noise. This holds even with no `.gitignore`.
+- **Anything in your `.gitignore`** — honored in git repos via git, and in non-git projects by reading `.gitignore` directly (root and nested).
+- **Files larger than 1 MB** — generated bundles, minified JS, vendored blobs.
+
+## Excluding or including more
+
+To keep something else out, add it to `.gitignore`. To pull a default-excluded directory back **in** (e.g. you really want a vendored dependency indexed), 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.
+
+## Where data lives
+
+Per-project data lives in a `.codegraph/` directory at your project root, containing the SQLite database (`codegraph.db`). Nothing leaves your machine.
diff --git a/site/src/content/docs/getting-started/installation.md b/site/src/content/docs/getting-started/installation.md
new file mode 100644
index 000000000..4e8a0e2ce
--- /dev/null
+++ b/site/src/content/docs/getting-started/installation.md
@@ -0,0 +1,69 @@
+---
+title: Installation
+description: Install CodeGraph and configure your AI coding agents.
+---
+
+## 1. Run the installer
+
+```bash
+npx @colbymchenry/codegraph
+```
+
+The installer will:
+
+- Ask which agent(s) to configure — auto-detecting installed ones from **Claude Code**, **Cursor**, **Codex CLI**, **opencode**, **Hermes Agent**, **Gemini CLI**, **Antigravity IDE**, and **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 an instructions file (e.g. `CLAUDE.md`, `.cursor/rules/codegraph.mdc`, `~/.codex/AGENTS.md`).
+- Set up auto-allow permissions when Claude Code is one of the targets.
+- Initialize your current project (local installs only).
+
+## Non-interactive (scripting / CI)
+
+```bash
+codegraph install --yes                              # auto-detect agents, install global
+codegraph install --target=cursor,claude --yes       # explicit target list
+codegraph install --target=auto --location=local     # detected agents, project-local
+codegraph install --print-config codex               # print snippet, no file writes
+```
+
+| Flag | Values | Default |
+|---|---|---|
+| `--target` | `auto`, `all`, `none`, or csv (`claude,cursor,…`) | prompt |
+| `--location` | `global`, `local` | prompt |
+| `--yes` | (boolean) | prompt every step |
+| `--no-permissions` | (boolean) skip Claude auto-allow list | permissions on |
+| `--print-config <id>` | dump snippet for one agent and exit | — |
+
+## 2. Restart your agent
+
+Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / Gemini CLI / Antigravity IDE / Kiro) for the MCP server to load.
+
+## 3. Initialize projects
+
+```bash
+cd your-project
+codegraph init -i
+```
+
+This builds the per-project knowledge graph index and wires up any project-local agent surfaces, so a single global `codegraph install` works in every project you open.
+
+## Supported platforms
+
+Every release ships a self-contained build (bundled Node runtime — nothing to compile) for all three desktop OSes, on both x64 and arm64:
+
+| Platform | Architectures | Install |
+|---|---|---|
+| Windows | x64, arm64 | PowerShell installer or npm |
+| macOS | x64, arm64 | shell installer or npm |
+| Linux | x64, arm64 | shell installer or npm |
+
+## Uninstall
+
+Changed your mind? One command removes CodeGraph from every agent it configured:
+
+```bash
+codegraph uninstall
+```
+
+This reverses the installer — stripping CodeGraph's MCP server config, instructions, and permissions from each configured agent. Your project indexes (`.codegraph/`) are left untouched; remove those per-project with `codegraph uninit`. Use `--target` to remove from specific agents, or `--yes` to run non-interactively.
diff --git a/site/src/content/docs/getting-started/introduction.md b/site/src/content/docs/getting-started/introduction.md
new file mode 100644
index 000000000..055085865
--- /dev/null
+++ b/site/src/content/docs/getting-started/introduction.md
@@ -0,0 +1,35 @@
+---
+title: Introduction
+description: What CodeGraph is, and why it makes AI coding agents faster and cheaper.
+---
+
+CodeGraph is a **local-first code-intelligence tool**. It parses your codebase with [tree-sitter](https://tree-sitter.github.io/), stores every symbol, edge, and file in a local SQLite database, and exposes the result as a queryable **knowledge graph** — over the [Model Context Protocol (MCP)](/codegraph/reference/mcp-server/), a CLI, and a TypeScript library.
+
+It exists to make AI coding agents — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — **answer structural questions without scanning files**. Instead of fanning out across `grep`, `glob`, and `Read` to reconstruct how code fits together, an agent queries a pre-built index and gets the answer in a handful of calls.
+
+## Why it matters
+
+When an agent explores a codebase, it spends most of its budget on *discovery* — finding the right files before it can read them. CodeGraph removes that step: symbol relationships, call graphs, and structure are already indexed.
+
+Tested across 7 real-world open-source codebases (median of 4 runs per arm), giving an agent CodeGraph was on average:
+
+- **35% cheaper**
+- **57% fewer tokens**
+- **46% faster**
+- **71% fewer tool calls**
+
+The gains scale with codebase size — on large repos the agent answers from the index with **zero file reads**.
+
+## What's in the graph
+
+- **Symbols** — functions, classes, methods, types, routes, components, and more.
+- **Edges** — calls, imports, inheritance, references, and framework-specific relationships.
+- **Files** — structure plus full-text search (FTS5).
+
+Extraction is **deterministic** — derived from the AST, never LLM-summarized.
+
+## 100% local
+
+No data leaves your machine. No API keys, no external services — just a SQLite database in `.codegraph/`.
+
+Ready to try it? Head to the [Quickstart](/codegraph/getting-started/quickstart/).
diff --git a/site/src/content/docs/getting-started/next-steps.md b/site/src/content/docs/getting-started/next-steps.md
new file mode 100644
index 000000000..3ae0d88fa
--- /dev/null
+++ b/site/src/content/docs/getting-started/next-steps.md
@@ -0,0 +1,25 @@
+---
+title: Next Steps
+description: Where to go once CodeGraph is installed and indexing.
+---
+
+You've got CodeGraph installed and a graph built. Here's where to go next.
+
+## Understand the model
+
+- [How It Works](/codegraph/core-concepts/how-it-works/) — the extraction → storage → resolution → sync pipeline.
+- [The Knowledge Graph](/codegraph/core-concepts/knowledge-graph/) — the node and edge kinds the graph is built from.
+- [Resolution & Frameworks](/codegraph/core-concepts/resolution/) — how references and framework routes get connected.
+
+## Put it to work
+
+- [Indexing a Project](/codegraph/guides/indexing/) — full index, incremental sync, and the file watcher.
+- [Framework Routes](/codegraph/guides/framework-routes/) — link URL patterns to their handlers.
+- [Affected Tests in CI](/codegraph/guides/affected-tests/) — run only the tests a change touches.
+
+## Reference
+
+- [MCP Server](/codegraph/reference/mcp-server/) — the tools agents call.
+- [CLI](/codegraph/reference/cli/) — every command and flag.
+- [API](/codegraph/reference/api/) — use CodeGraph as a TypeScript library.
+- [Integrations](/codegraph/reference/integrations/) — supported agents and manual setup.
diff --git a/site/src/content/docs/getting-started/quickstart.md b/site/src/content/docs/getting-started/quickstart.md
new file mode 100644
index 000000000..1d63bb489
--- /dev/null
+++ b/site/src/content/docs/getting-started/quickstart.md
@@ -0,0 +1,36 @@
+---
+title: Get Started
+description: Get up and running with CodeGraph in seconds.
+---
+
+Get up and running with CodeGraph in seconds.
+
+## No Node.js required — one command grabs the right build for your OS
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
+```
+
+## Already have Node? Use npm instead (works on any version)
+
+```bash
+npx @colbymchenry/codegraph        # zero-install, or:
+npm i -g @colbymchenry/codegraph
+```
+
+CodeGraph bundles its own runtime — nothing to compile, no native build, works the same everywhere. The interactive installer auto-configures your agent(s) — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro.
+
+## Initialize Projects
+
+```bash
+cd your-project
+codegraph init -i
+```
+
+That's it — your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists.
+
+Next: build [Your First Graph](/codegraph/getting-started/your-first-graph/), or see the full [Installation](/codegraph/getting-started/installation/) options.
diff --git a/site/src/content/docs/getting-started/your-first-graph.md b/site/src/content/docs/getting-started/your-first-graph.md
new file mode 100644
index 000000000..916edbd44
--- /dev/null
+++ b/site/src/content/docs/getting-started/your-first-graph.md
@@ -0,0 +1,44 @@
+---
+title: Your First Graph
+description: Build an index and run your first queries against it.
+---
+
+Once CodeGraph is installed, building and exploring a graph takes three commands.
+
+## Index a project
+
+```bash
+cd your-project
+codegraph init -i      # initialize + index in one step
+```
+
+`init` creates the `.codegraph/` directory; `-i` (or `--index`) immediately builds the full index. For an existing project you can re-index any time:
+
+```bash
+codegraph index          # full index
+codegraph sync           # incremental update of changed files
+```
+
+## Check it worked
+
+```bash
+codegraph status
+```
+
+This reports the node/edge/file counts, the active SQLite backend, and the journal mode — a quick health check that the index is ready.
+
+## Run a query
+
+```bash
+codegraph query UserService          # find symbols by name
+codegraph callers handleRequest      # what calls a function
+codegraph callees handleRequest      # what a function calls
+codegraph impact AuthMiddleware      # what a change would affect
+codegraph context "fix the login flow"   # build task-focused context
+```
+
+Each accepts `--json` for machine-readable output. See the full [CLI reference](/codegraph/reference/cli/).
+
+## Hand it to your agent
+
+With a `.codegraph/` directory present and an agent configured (see [Installation](/codegraph/getting-started/installation/)), your agent uses the [MCP tools](/codegraph/reference/mcp-server/) automatically — no extra step.
diff --git a/site/src/content/docs/guides/affected-tests.md b/site/src/content/docs/guides/affected-tests.md
new file mode 100644
index 000000000..b51910561
--- /dev/null
+++ b/site/src/content/docs/guides/affected-tests.md
@@ -0,0 +1,32 @@
+---
+title: Affected Tests in CI
+description: Run only the tests a change actually touches.
+---
+
+`codegraph affected` traces import dependencies transitively to find which test files are affected by a set of changed source files — so CI can run only the relevant tests.
+
+```bash
+codegraph affected src/utils.ts src/api.ts          # pass files as arguments
+git diff --name-only | codegraph affected --stdin    # pipe from git diff
+codegraph affected src/auth.ts --filter "e2e/*"      # custom test-file pattern
+```
+
+## Options
+
+| Option | Description | Default |
+|---|---|---|
+| `--stdin` | Read the file list from stdin | `false` |
+| `-d, --depth <n>` | Max dependency traversal depth | `5` |
+| `-f, --filter <glob>` | Custom glob to identify test files | auto-detect |
+| `-j, --json` | Output as JSON | `false` |
+| `-q, --quiet` | Output file paths only | `false` |
+
+## CI / hook example
+
+```bash
+#!/usr/bin/env bash
+AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
+if [ -n "$AFFECTED" ]; then
+  npx vitest run $AFFECTED
+fi
+```
diff --git a/site/src/content/docs/guides/framework-routes.md b/site/src/content/docs/guides/framework-routes.md
new file mode 100644
index 000000000..3d7fa91b8
--- /dev/null
+++ b/site/src/content/docs/guides/framework-routes.md
@@ -0,0 +1,25 @@
+---
+title: Framework Routes
+description: CodeGraph links URL patterns to the handlers that serve them.
+---
+
+CodeGraph detects web-framework routing files and emits `route` nodes linked by `references` edges to their handler classes or functions. Querying the callers of a view or controller then surfaces the URL pattern that binds it.
+
+| Framework | Shapes recognized |
+|---|---|
+| **Django** | `path()`, `re_path()`, `url()`, `include()` in `urls.py` (CBV `.as_view()`, dotted paths) |
+| **Flask** | `@app.route('/path', methods=[…])`, blueprint routes |
+| **FastAPI** | `@app.get(…)`, `@router.post(…)`, all standard methods |
+| **Express** | `app.get(…)`, `router.post(…)` with middleware chains |
+| **NestJS** | `@Controller` + `@Get/@Post/…`, GraphQL resolvers, message/event patterns, WebSocket subscriptions |
+| **Laravel** | `Route::get()`, `Route::resource()`, `Controller@action`, tuple syntax |
+| **Drupal** | `*.routing.yml` routes; `hook_*` implementations in `.module`/`.theme`/`.install`/`.inc` |
+| **Rails** | `get '/x', to: 'users#index'`, hash-rocket syntax |
+| **Spring** | `@GetMapping`, `@PostMapping`, `@RequestMapping` on methods |
+| **Gin / chi / gorilla / mux** | `r.GET(…)`, `router.HandleFunc(…)` |
+| **Axum / actix / Rocket** | `.route("/x", get(handler))` |
+| **ASP.NET** | `[HttpGet("/x")]` attributes on action methods |
+| **Vapor** | `app.get("x", use: handler)` |
+| **React Router** / **SvelteKit** | Route component nodes |
+
+Route resolution is automatic — there's nothing to configure. If a framework file is recognized, its routes appear in the graph after the next index or sync.
diff --git a/site/src/content/docs/guides/indexing.md b/site/src/content/docs/guides/indexing.md
new file mode 100644
index 000000000..7c0fd1ddc
--- /dev/null
+++ b/site/src/content/docs/guides/indexing.md
@@ -0,0 +1,101 @@
+---
+title: Indexing a Project
+description: Full index, incremental sync, and the file watcher.
+---
+
+## Initialize and index
+
+```bash
+cd your-project
+codegraph init -i      # initialize + full index
+```
+
+`init` creates `.codegraph/`; `-i`/`--index` builds the index immediately. To initialize without indexing, drop the flag and run `codegraph index` later.
+
+## Full vs. incremental
+
+```bash
+codegraph index           # full index of the whole project
+codegraph index --force   # re-index from scratch
+codegraph sync            # incremental — only changed files
+```
+
+`sync` is fast because it only reparses what changed. Use it after a branch switch or a batch of edits.
+
+## Stay fresh automatically
+
+**You don't need to run `codegraph sync` by hand during an agent session.** When your agent (Claude Code, Cursor, Codex, opencode, Hermes, Gemini, Antigravity, Kiro) launches `codegraph serve --mcp`, three layers cooperate to keep the index in step with your code — and to never give the agent a quiet wrong answer in the small window between an edit and the next sync.
+
+### 1. File watcher with debounced auto-sync (always on)
+
+`serve --mcp` spins up a native file watcher (FSEvents on macOS, inotify on Linux, ReadDirectoryChangesW on Windows) over the project root. Every source-file create / modify / delete is captured. A debounce timer collapses bursts of edits into a single sync.
+
+```
+agent writes src/Widget.ts
+  → watcher fires (event delivery: typically <100ms)
+  → 2000ms debounce
+  → sync runs; Widget.ts's nodes + edges are in the index
+  → next agent query sees it
+```
+
+**Tunable**: `CODEGRAPH_WATCH_DEBOUNCE_MS` overrides the default 2000ms, clamped to `[100ms, 60s]`. Useful when a build step or formatter writes many files in a tight burst — bump it to `5000` or `10000` so the watcher coalesces them into one sync.
+
+### 2. Per-file staleness banner — covers the debounce window
+
+The watcher debounce introduces a small window (typically 2s) where a freshly-edited file is on disk but not yet in the index. CodeGraph closes that window with a per-file staleness banner: if any MCP tool response would reference a file that's currently pending re-index, the response prepends a `⚠️` banner naming the stale file:
+
+```
+⚠️ Some files referenced below were edited since the last index sync —
+their codegraph entries may be stale:
+  - src/Widget.ts (edited 800ms ago, pending sync)
+For accurate content of those specific files, Read them directly.
+The rest of this response is fresh.
+
+## Code Context
+…
+```
+
+Agents read this and follow up with a direct `Read` on the named file — validated end-to-end with Claude Code, where the agent literally says "Reading the file directly for the live content" before opening it. So even during the 2-second debounce window, the agent never gets a silent wrong answer.
+
+Pending files **not** referenced by the response surface as a small footer instead (`(Note: N file(s) elsewhere in this project are pending index sync but were not referenced above: …)`). Either way, the signal is explicit.
+
+### 3. Connect-time catch-up — covers gaps when the MCP server wasn't running
+
+When your editor / agent (re)connects to the MCP server, codegraph runs a fast filesystem-based reconciliation (a `(size, mtime)` stat pre-filter, then a content hash on the rest) before answering the first query. So files changed while no MCP server was running — a `git pull` from the terminal, an edit from another editor, an agent that finished and exited — are caught up automatically on the next session's first tool call.
+
+### Verify what the watcher sees
+
+`codegraph_status` exposes the pending set first-class — useful for an agent asking "is the index caught up?" in one call:
+
+```
+codegraph_status →
+  ## CodeGraph Status
+  …
+  ### Pending sync:
+  - src/Widget.ts (edited 1200ms ago)
+```
+
+If `### Pending sync:` isn't in the response, nothing is in flight.
+
+### When manual `codegraph sync` makes sense
+
+Almost never. The edge cases:
+
+- **The watcher is disabled.** Sandboxes that block local fs watchers, or you've set `CODEGRAPH_NO_DAEMON=1` to opt out of the shared daemon. In those cases `codegraph sync` is the manual fallback.
+- **Pre-flight before a CI run.** If you're scripting against the index outside an agent session, a single `codegraph sync` at the start of the script guarantees the index reflects the current working tree.
+
+Otherwise: just use it. The watcher + banner + connect-sync covers the AI-assisted workflow end-to-end. If you're seeing files genuinely missed after the debounce window has passed, that's a bug — please file an issue with a reproduction.
+
+> See the v0.9.5 release notes for the [staleness banner (#403)](https://github.com/colbymchenry/codegraph/releases/tag/v0.9.5) and the connect-time catch-up (#414); both shipped together.
+
+## Check status
+
+```bash
+codegraph status
+```
+
+Reports node/edge/file counts, the active SQLite backend, and the journal mode. In an agent session, the MCP-side `codegraph_status` additionally surfaces the `### Pending sync:` block described above.
+
+## What gets indexed
+
+Every file whose extension maps to a [supported language](/codegraph/reference/languages/), minus dependency/build directories excluded by default (`node_modules`, `vendor`, `dist`, …), anything your `.gitignore` excludes, and files over 1 MB. See [Configuration](/codegraph/getting-started/configuration/).
diff --git a/site/src/content/docs/reference/api.md b/site/src/content/docs/reference/api.md
new file mode 100644
index 000000000..9c896a719
--- /dev/null
+++ b/site/src/content/docs/reference/api.md
@@ -0,0 +1,45 @@
+---
+title: API
+description: Use CodeGraph as a TypeScript library.
+---
+
+CodeGraph ships a TypeScript API. The public surface is the `CodeGraph` class.
+
+```typescript
+import CodeGraph from '@colbymchenry/codegraph';
+
+const cg = await CodeGraph.init('/path/to/project');
+// Or open an existing index:
+// const cg = await CodeGraph.open('/path/to/project');
+
+await cg.indexAll({
+  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`),
+});
+
+const results = cg.searchNodes('UserService');
+const callers = cg.getCallers(results[0].node.id);
+const context = await cg.buildContext('fix login bug', {
+  maxNodes: 20,
+  includeCode: true,
+  format: 'markdown',
+});
+const impact = cg.getImpactRadius(results[0].node.id, 2);
+
+cg.watch();   // auto-sync on file changes
+cg.unwatch(); // stop watching
+cg.close();
+```
+
+## Key methods
+
+| Method | Purpose |
+|---|---|
+| `CodeGraph.init(path)` / `CodeGraph.open(path)` | Create or open a project index |
+| `indexAll(opts)` | Full index, with progress callback |
+| `sync()` | Incremental update |
+| `searchNodes(query)` | Full-text symbol search |
+| `getCallers(id)` / `getCallees(id)` | Walk the call graph |
+| `getImpactRadius(id, depth)` | Transitive impact of a change |
+| `buildContext(task, opts)` | Markdown / JSON context for AI |
+| `watch()` / `unwatch()` | Start / stop the file watcher |
+| `close()` | Close the database connection |
diff --git a/site/src/content/docs/reference/cli.md b/site/src/content/docs/reference/cli.md
new file mode 100644
index 000000000..76f0e5a31
--- /dev/null
+++ b/site/src/content/docs/reference/cli.md
@@ -0,0 +1,37 @@
+---
+title: CLI
+description: Every CodeGraph command and the flags it accepts.
+---
+
+```bash
+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 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
+codegraph status [path]           # Show statistics
+codegraph query <search>          # Search symbols (--kind, --limit, --json)
+codegraph files [path]            # Show file structure (--format, --filter, --max-depth, --json)
+codegraph context <task>          # Build context for AI (--format, --max-nodes)
+codegraph callers <symbol>        # Find what calls a function/method (--limit, --json)
+codegraph callees <symbol>        # Find what a function/method calls (--limit, --json)
+codegraph impact <symbol>         # Analyze what code is affected by changing a symbol (--depth, --json)
+codegraph affected [files...]     # Find test files affected by changes
+codegraph serve --mcp             # Start MCP server
+```
+
+## Query commands
+
+`query`, `callers`, `callees`, and `impact` all accept `--json` for machine-readable output.
+
+```bash
+codegraph query UserService --kind class --limit 10
+codegraph callers handleRequest --json
+codegraph impact AuthMiddleware --depth 3
+```
+
+## affected
+
+Traces import dependencies transitively to find which test files are affected by changed source files. See [Affected Tests in CI](/codegraph/guides/affected-tests/) for options and a CI example.
diff --git a/site/src/content/docs/reference/integrations.md b/site/src/content/docs/reference/integrations.md
new file mode 100644
index 000000000..2a20cad68
--- /dev/null
+++ b/site/src/content/docs/reference/integrations.md
@@ -0,0 +1,63 @@
+---
+title: Integrations
+description: Supported agents, and manual MCP setup.
+---
+
+The interactive installer auto-detects and configures each supported agent — wiring up the MCP server and writing its instructions file.
+
+## Supported agents
+
+- **Claude Code**
+- **Cursor**
+- **Codex CLI**
+- **opencode**
+- **Hermes Agent**
+- **Gemini CLI**
+- **Antigravity IDE**
+- **Kiro**
+
+Run `npx @colbymchenry/codegraph` and pick your agent(s); see [Installation](/codegraph/getting-started/installation/) for the non-interactive flags.
+
+## Manual setup
+
+If you'd rather wire it up yourself, install globally:
+
+```bash
+npm install -g @colbymchenry/codegraph
+```
+
+Add the MCP server to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "codegraph": {
+      "type": "stdio",
+      "command": "codegraph",
+      "args": ["serve", "--mcp"]
+    }
+  }
+}
+```
+
+Optionally auto-allow the read-only tools in `~/.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "mcp__codegraph__codegraph_search",
+      "mcp__codegraph__codegraph_callers",
+      "mcp__codegraph__codegraph_callees",
+      "mcp__codegraph__codegraph_impact",
+      "mcp__codegraph__codegraph_node",
+      "mcp__codegraph__codegraph_status",
+      "mcp__codegraph__codegraph_files"
+    ]
+  }
+}
+```
+
+:::tip
+Cursor launches MCP subprocesses with the wrong working directory. The installer handles this for you by injecting a `--path` argument; if you wire Cursor up by hand, pass the project path explicitly.
+:::
diff --git a/site/src/content/docs/reference/languages.md b/site/src/content/docs/reference/languages.md
new file mode 100644
index 000000000..184b579ac
--- /dev/null
+++ b/site/src/content/docs/reference/languages.md
@@ -0,0 +1,30 @@
+---
+title: Languages
+description: Every language CodeGraph parses, and the extensions it recognizes.
+---
+
+Language support is automatic from the file extension — there's nothing to configure.
+
+| Language | Extensions | Status |
+|---|---|---|
+| TypeScript | `.ts`, `.tsx` | Full support |
+| JavaScript | `.js`, `.jsx`, `.mjs` | Full support |
+| Python | `.py` | Full support |
+| Go | `.go` | Full support |
+| Rust | `.rs` | Full support |
+| Java | `.java` | Full support |
+| C# | `.cs` | Full support |
+| PHP | `.php` | Full support |
+| Ruby | `.rb` | Full support |
+| C | `.c`, `.h` | Full support |
+| C++ | `.cpp`, `.hpp`, `.cc` | Full support |
+| Swift | `.swift` | Full support |
+| Kotlin | `.kt`, `.kts` | Full support |
+| Scala | `.scala`, `.sc` | Full support (classes, traits, methods, type aliases, Scala 3 enums) |
+| Dart | `.dart` | Full support |
+| Svelte | `.svelte` | Full support (script extraction, Svelte 5 runes, SvelteKit routes) |
+| Vue | `.vue` | Full support (script + script-setup, Nuxt page/API/middleware routes) |
+| Liquid | `.liquid` | Full support |
+| Pascal / Delphi | `.pas`, `.dpr`, `.dpk`, `.lpr` | Full support (classes, records, interfaces, enums, DFM/FMX forms) |
+| Lua | `.lua` | Full support (functions, methods, locals, `require` imports, call edges) |
+| Luau | `.luau` | Full support (Lua, plus typed signatures, `type` aliases, Roblox `require`) |
diff --git a/site/src/content/docs/reference/mcp-server.md b/site/src/content/docs/reference/mcp-server.md
new file mode 100644
index 000000000..63c3e32cc
--- /dev/null
+++ b/site/src/content/docs/reference/mcp-server.md
@@ -0,0 +1,31 @@
+---
+title: MCP Server
+description: The tools CodeGraph exposes to AI agents over MCP.
+---
+
+CodeGraph runs as a [Model Context Protocol](https://modelcontextprotocol.io/) server. Start it with:
+
+```bash
+codegraph serve --mcp
+```
+
+Agents configured by the installer launch this automatically. When a `.codegraph/` index exists, the agent uses the tools below.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `codegraph_search` | Find symbols by name across the codebase |
+| `codegraph_callers` | Find what calls a function |
+| `codegraph_callees` | Find what a function calls |
+| `codegraph_impact` | Analyze what code is affected by changing a symbol |
+| `codegraph_node` | Get details about a specific symbol (optionally with source code) |
+| `codegraph_explore` | Return source for several related symbols grouped by file, plus a relationship map, in one call |
+| `codegraph_files` | Get the indexed file structure (faster than filesystem scanning) |
+| `codegraph_status` | Check index health and statistics |
+
+## How agents should use it
+
+CodeGraph *is* the pre-built search index. For "how does X work?", architecture, trace, or where-is-X questions, an agent should answer in a handful of CodeGraph calls and stop — typically with **zero file reads** — rather than re-deriving the answer with `grep` + `Read`. A direct CodeGraph answer is a handful of calls; a grep/read exploration is dozens.
+
+The installer writes this guidance into each agent's instructions file automatically.
diff --git a/site/src/content/docs/troubleshooting.md b/site/src/content/docs/troubleshooting.md
new file mode 100644
index 000000000..2a4de29ef
--- /dev/null
+++ b/site/src/content/docs/troubleshooting.md
@@ -0,0 +1,27 @@
+---
+title: Troubleshooting
+description: Fixes for the most common CodeGraph issues.
+---
+
+## "CodeGraph not initialized"
+
+Run `codegraph init` in your project directory first.
+
+## Indexing is slow
+
+Check that `node_modules` and other large directories are excluded (they are, if gitignored). Use `--quiet` to reduce output overhead.
+
+## MCP hits `database is locked`
+
+Current builds shouldn't: CodeGraph bundles its own Node runtime and uses Node's built-in `node:sqlite` in WAL mode, where concurrent reads never block on a writer. If you still see it:
+
+- **You're on an old (pre-0.9) install.** Reinstall to get the bundled runtime — `curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh` (macOS/Linux), `irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex` (Windows), or `npm i -g @colbymchenry/codegraph@latest`.
+- **`codegraph status` shows `Journal:` other than `wal`** — WAL couldn't be enabled on this filesystem (common on network shares and WSL2 `/mnt`), so reads can block on writes. Move the project (with its `.codegraph/` folder) onto a local disk.
+
+## MCP server not connecting
+
+Ensure the project is initialized/indexed, verify the path in your MCP config, and check that `codegraph serve --mcp` works from the command line.
+
+## Missing symbols
+
+The MCP server auto-syncs on save (wait a couple of seconds). Run `codegraph sync` manually if needed. Check that the file's language is [supported](/codegraph/reference/languages/) and isn't excluded by `.gitignore`.
diff --git a/site/src/lib/github.ts b/site/src/lib/github.ts
new file mode 100644
index 000000000..041b35f0a
--- /dev/null
+++ b/site/src/lib/github.ts
@@ -0,0 +1,42 @@
+/**
+ * Build-time GitHub star count. Fetched once when the site is built (the GitHub
+ * Actions runner has network); falls back to a constant locally / offline so a
+ * build never hangs or fails on the network. The result is memoized for the
+ * lifetime of the build process, so rendering it on every page is a single API
+ * call, not one per page.
+ */
+function format(n: number): string {
+	if (n >= 1000) {
+		const k = n / 1000;
+		const rounded = k >= 10 ? Math.round(k) : Math.round(k * 10) / 10;
+		return `${String(rounded).replace(/\.0$/, '')}k`;
+	}
+	return String(n);
+}
+
+async function fetchStars(fallback: string): Promise<string> {
+	try {
+		const controller = new AbortController();
+		const timeout = setTimeout(() => controller.abort(), 3000);
+		const res = await fetch('https://api.github.com/repos/colbymchenry/codegraph', {
+			headers: {
+				Accept: 'application/vnd.github+json',
+				'User-Agent': 'codegraph-site',
+			},
+			signal: controller.signal,
+		});
+		clearTimeout(timeout);
+		if (!res.ok) return fallback;
+		const data = (await res.json()) as { stargazers_count?: number };
+		return typeof data.stargazers_count === 'number' ? format(data.stargazers_count) : fallback;
+	} catch {
+		return fallback;
+	}
+}
+
+let cached: Promise<string> | null = null;
+
+export function getStarsLabel(fallback = '22k'): Promise<string> {
+	cached ??= fetchStars(fallback);
+	return cached;
+}
diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro
new file mode 100644
index 000000000..a469c00b4
--- /dev/null
+++ b/site/src/pages/index.astro
@@ -0,0 +1,457 @@
+---
+import '@fontsource-variable/archivo';
+import '@fontsource/ibm-plex-mono/400.css';
+import '@fontsource/ibm-plex-mono/500.css';
+import '@fontsource/ibm-plex-mono/600.css';
+import '../styles/theme.css';
+import GraphDiagram from '../components/GraphDiagram.astro';
+import { getStarsLabel } from '../lib/github';
+
+const base = import.meta.env.BASE_URL.replace(/\/$/, '');
+const repo = 'https://github.com/colbymchenry/codegraph';
+const npm = 'https://www.npmjs.com/package/@colbymchenry/codegraph';
+const stars = await getStarsLabel();
+const install = 'npx @colbymchenry/codegraph';
+---
+
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<link rel="icon" href={`${base}/favicon.svg`} type="image/svg+xml" />
+		<title>codegraph — Understand any codebase as a graph</title>
+		<meta
+			name="description"
+			content="A local-first code-intelligence tool that turns any codebase into a queryable knowledge graph for AI coding agents."
+		/>
+		<meta property="og:title" content="codegraph" />
+		<meta property="og:description" content="Understand any codebase as a graph." />
+		<meta property="og:type" content="website" />
+		<meta name="theme-color" content="#f7f6f2" />
+	</head>
+	<body>
+		<div class="frame">
+			<header class="nav">
+				<a class="wordmark" href={`${base}/`}>codegraph</a>
+				<nav class="nav-links">
+					<a href={`${base}/getting-started/introduction`}>Docs</a>
+					<a class="opt" href={`${base}/reference/languages`}>Languages</a>
+					<a href={repo}>GitHub</a>
+					<a class="star" href={`${repo}/stargazers`}>
+						<span class="star-glyph" aria-hidden="true">★</span>{stars}
+					</a>
+				</nav>
+			</header>
+
+			<main>
+				<section class="hero">
+					<div class="hero-left">
+						<h1>Understand any codebase as a graph</h1>
+						<p class="lede">
+							A local-first code-intelligence tool that turns any codebase into a
+							queryable knowledge graph for AI coding agents.
+						</p>
+						<div class="cta">
+							<a class="btn btn-primary" href={`${base}/getting-started/quickstart`}>Get started</a>
+							<a class="btn btn-ghost" href={`${base}/getting-started/introduction`}>View documentation</a>
+						</div>
+						<div class="install" data-install={install}>
+							<code>{install}</code>
+							<button class="copy" type="button" aria-label="Copy install command">
+								<svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="1.6">
+									<rect x="9" y="9" width="11" height="11" />
+									<path d="M5 15V5a1 1 0 0 1 1-1h9" />
+								</svg>
+							</button>
+						</div>
+					</div>
+					<div class="hero-right">
+						<GraphDiagram />
+					</div>
+				</section>
+
+				<section class="features">
+					<article class="feature">
+						<svg class="ficon" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5">
+							<rect x="19" y="4" width="10" height="10" />
+							<rect x="4" y="34" width="10" height="10" />
+							<rect x="19" y="34" width="10" height="10" />
+							<rect x="34" y="34" width="10" height="10" />
+							<path d="M24 14v10M9 34v-10h30v10M24 24v10" />
+						</svg>
+						<h2>Tree-sitter parsing</h2>
+						<p>
+							Fast, incremental parsing across 20+ languages — accurate symbols and
+							edges drawn from real ASTs, not guesses.
+						</p>
+					</article>
+					<article class="feature">
+						<svg class="ficon" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5">
+							<rect x="5" y="10" width="38" height="28" />
+							<path d="M13 20l6 4-6 4M26 28h9" />
+						</svg>
+						<h2>MCP server</h2>
+						<p>
+							Expose the graph to Claude Code, Cursor, Codex, opencode, Hermes,
+							Gemini, Antigravity, and Kiro over MCP — agents answer in a handful of calls.
+						</p>
+					</article>
+					<article class="feature">
+						<svg class="ficon" viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="1.5">
+							<circle cx="16" cy="24" r="10" />
+							<circle cx="16" cy="24" r="3.5" fill="currentColor" stroke="none" />
+							<path d="M16 8v6M16 34v6M2 24h4M26 24h6M32 24l8-6M32 24l8 6" />
+							<circle cx="41" cy="17" r="2.5" />
+							<circle cx="41" cy="31" r="2.5" />
+						</svg>
+						<h2>Impact analysis</h2>
+						<p>
+							Trace callers, callees, and the full impact radius of any symbol
+							before you change a line.
+						</p>
+					</article>
+				</section>
+			</main>
+
+			<footer class="foot">
+				<span class="foot-mark">codegraph</span>
+				<nav class="foot-links">
+					<a href={`${base}/getting-started/introduction`}>Docs</a>
+					<a href={repo}>GitHub</a>
+					<a href={npm}>npm</a>
+					<a href={`${repo}/blob/main/LICENSE`}>MIT</a>
+				</nav>
+			</footer>
+		</div>
+
+		<script>
+			const wrap = document.querySelector('.install');
+			const btn = wrap?.querySelector('.copy');
+			if (wrap && btn) {
+				const original = btn.innerHTML;
+				btn.addEventListener('click', async () => {
+					try {
+						await navigator.clipboard.writeText(wrap.getAttribute('data-install') || '');
+						btn.innerHTML = '<span class="copied">Copied</span>';
+						setTimeout(() => (btn.innerHTML = original), 1400);
+					} catch {
+						/* clipboard blocked — no-op */
+					}
+				});
+			}
+		</script>
+
+		<style>
+			:global(html) {
+				background: var(--cg-paper);
+			}
+			:global(body) {
+				margin: 0;
+				font-family: var(--sl-font);
+				color: var(--cg-ink);
+				overflow-x: hidden;
+			}
+
+			.frame {
+				max-width: 1440px;
+				margin: 0 auto;
+				border: 1px solid var(--cg-rule);
+			}
+
+			/* ---- nav ---- */
+			.nav {
+				display: flex;
+				align-items: center;
+				justify-content: space-between;
+				padding: 1.1rem 2rem;
+				border-bottom: 1px solid var(--cg-rule);
+			}
+			.wordmark {
+				font-weight: 800;
+				font-size: 1.4rem;
+				letter-spacing: -0.035em;
+				color: var(--cg-ink);
+				text-decoration: none;
+			}
+			.nav-links {
+				display: flex;
+				align-items: center;
+				gap: 2rem;
+			}
+			.nav-links a {
+				color: var(--cg-ink);
+				text-decoration: none;
+				font-size: 0.98rem;
+			}
+			.nav-links a:not(.star):hover {
+				text-decoration: underline;
+				text-underline-offset: 4px;
+			}
+			.star {
+				display: inline-flex;
+				align-items: center;
+				gap: 0.4rem;
+				border: 1px solid var(--cg-rule);
+				padding: 0.4rem 0.85rem;
+				font-variant-numeric: tabular-nums;
+			}
+			.star:hover {
+				background: var(--cg-paper-press);
+			}
+			.star-glyph {
+				font-size: 0.85em;
+			}
+
+			/* ---- hero ---- */
+			.hero {
+				display: grid;
+				grid-template-columns: 1.05fr 0.95fr;
+				border-bottom: 1px solid var(--cg-rule);
+			}
+			.hero-left {
+				padding: 4.5rem 3rem 4rem;
+				min-width: 0; /* allow the grid cell to shrink below content width */
+			}
+			.hero-right {
+				border-inline-start: 1px solid var(--cg-rule);
+				display: flex;
+				align-items: center;
+				justify-content: center;
+				padding: 2.5rem;
+				min-width: 0; /* let the SVG scale down instead of widening the page */
+			}
+			h1 {
+				font-size: clamp(2.4rem, 6vw, 4.6rem);
+				line-height: 0.98;
+				font-weight: 800;
+				letter-spacing: -0.04em;
+				margin: 0 0 1.6rem;
+				overflow-wrap: break-word;
+			}
+			.lede {
+				font-size: 1.18rem;
+				line-height: 1.5;
+				color: var(--cg-ink-2);
+				max-width: 34ch;
+				margin: 0 0 2.2rem;
+			}
+			.cta {
+				display: flex;
+				gap: 0.9rem;
+				margin-bottom: 1.6rem;
+				flex-wrap: wrap;
+			}
+			.btn {
+				display: inline-flex;
+				align-items: center;
+				justify-content: center;
+				padding: 0.8rem 1.5rem;
+				font-size: 1rem;
+				font-weight: 600;
+				text-decoration: none;
+				border: 1px solid var(--cg-rule);
+				transition:
+					background 0.12s ease,
+					color 0.12s ease;
+			}
+			.btn-primary {
+				background: var(--cg-ink);
+				color: var(--cg-paper);
+			}
+			.btn-primary:hover {
+				background: transparent;
+				color: var(--cg-ink);
+			}
+			.btn-ghost {
+				background: transparent;
+				color: var(--cg-ink);
+			}
+			.btn-ghost:hover {
+				background: var(--cg-paper-press);
+			}
+			.install {
+				display: inline-flex;
+				align-items: center;
+				gap: 0.5rem;
+				border: 1px solid var(--cg-rule);
+				padding: 0.5rem 0.55rem 0.5rem 0.9rem;
+				font-family: var(--sl-font-mono);
+				font-size: 0.95rem;
+			}
+			.install code {
+				font-family: inherit;
+				background: none;
+				color: var(--cg-ink);
+			}
+			.copy {
+				display: inline-flex;
+				align-items: center;
+				justify-content: center;
+				border: none;
+				background: transparent;
+				cursor: pointer;
+				padding: 0.3rem;
+				color: var(--cg-ink-2);
+			}
+			.copy:hover {
+				color: var(--cg-ink);
+			}
+			.copy :global(.copied) {
+				font-family: var(--sl-font);
+				font-size: 0.8rem;
+				padding: 0 0.2rem;
+			}
+
+			/* ---- features ---- */
+			.features {
+				display: grid;
+				grid-template-columns: repeat(3, 1fr);
+			}
+			.feature {
+				display: grid;
+				grid-template-columns: auto 1px 1fr;
+				column-gap: 1.5rem;
+				align-items: center;
+				padding: 2.6rem 2rem;
+			}
+			.feature + .feature {
+				border-inline-start: 1px solid var(--cg-rule);
+			}
+			/* full-height vertical divider between the icon and the text */
+			.feature::before {
+				content: '';
+				grid-column: 2;
+				grid-row: 1 / 3;
+				align-self: stretch;
+				width: 1px;
+				background: var(--cg-rule);
+			}
+			.ficon {
+				grid-column: 1;
+				grid-row: 1 / 3;
+				align-self: center;
+				width: 64px;
+				height: 64px;
+				color: var(--cg-ink);
+			}
+			.feature h2 {
+				grid-column: 3;
+				grid-row: 1;
+				font-size: 1.3rem;
+				font-weight: 700;
+				margin: 0 0 0.6rem;
+			}
+			.feature p {
+				grid-column: 3;
+				grid-row: 2;
+				font-size: 1rem;
+				line-height: 1.55;
+				color: var(--cg-ink-2);
+				margin: 0;
+				max-width: 34ch;
+			}
+
+			/* ---- footer ---- */
+			.foot {
+				display: flex;
+				align-items: center;
+				justify-content: space-between;
+				padding: 1.4rem 2rem;
+				border-top: 1px solid var(--cg-rule);
+			}
+			.foot-mark {
+				font-weight: 800;
+				letter-spacing: -0.03em;
+			}
+			.foot-links {
+				display: flex;
+				gap: 1.6rem;
+			}
+			.foot-links a {
+				color: var(--cg-ink-2);
+				text-decoration: none;
+				font-size: 0.92rem;
+			}
+			.foot-links a:hover {
+				color: var(--cg-ink);
+				text-decoration: underline;
+				text-underline-offset: 3px;
+			}
+
+			/* ---- restrained entrance ---- */
+			@media (prefers-reduced-motion: no-preference) {
+				.hero-left > * {
+					opacity: 0;
+					transform: translateY(8px);
+					animation: cg-in 0.5s ease forwards;
+				}
+				.hero-left > *:nth-child(1) {
+					animation-delay: 0.04s;
+				}
+				.hero-left > *:nth-child(2) {
+					animation-delay: 0.1s;
+				}
+				.hero-left > *:nth-child(3) {
+					animation-delay: 0.16s;
+				}
+				.hero-left > *:nth-child(4) {
+					animation-delay: 0.22s;
+				}
+				@keyframes cg-in {
+					to {
+						opacity: 1;
+						transform: none;
+					}
+				}
+			}
+
+			/* ---- responsive ---- */
+			@media (max-width: 860px) {
+				.hero {
+					grid-template-columns: 1fr;
+				}
+				.hero-right {
+					border-inline-start: none;
+					border-top: 1px solid var(--cg-rule);
+				}
+				.features {
+					grid-template-columns: 1fr;
+				}
+				.feature + .feature {
+					border-inline-start: none;
+					border-top: 1px solid var(--cg-rule);
+				}
+				.feature {
+					column-gap: 1rem;
+					padding: 2rem 1.25rem;
+				}
+				.ficon {
+					width: 48px;
+					height: 48px;
+				}
+				.nav {
+					padding: 1rem 1.25rem;
+				}
+				.nav-links {
+					gap: 0.85rem;
+					font-size: 0.85rem;
+				}
+				.nav-links .opt {
+					display: none;
+				}
+				.star {
+					display: none; /* count still lives on the GitHub page */
+				}
+				.hero-left {
+					padding: 2.75rem 1.25rem 2.5rem;
+				}
+				.foot {
+					flex-direction: column;
+					gap: 1rem;
+					align-items: flex-start;
+				}
+			}
+		</style>
+	</body>
+</html>
diff --git a/site/src/styles/theme.css b/site/src/styles/theme.css
new file mode 100644
index 000000000..4a406fac2
--- /dev/null
+++ b/site/src/styles/theme.css
@@ -0,0 +1,226 @@
+/* =====================================================================
+   codegraph — flat / paper editorial theme
+   Monochrome ink-on-paper, hairline rules, square corners. Shared by the
+   custom landing page (src/pages/index.astro) and the Starlight docs.
+   ===================================================================== */
+
+/* ---- Fonts ---- */
+:root {
+	--sl-font: 'Archivo Variable', -apple-system, BlinkMacSystemFont, 'Helvetica Neue', Arial, sans-serif;
+	--sl-font-mono: 'IBM Plex Mono', ui-monospace, 'SF Mono', Menlo, Consolas, monospace;
+}
+
+/* ---- Starlight colour mapping: light / paper (default) ---- */
+:root,
+:root[data-theme='light'] {
+	--sl-color-accent-low: #e2dfd5;
+	--sl-color-accent: #16150f;
+	--sl-color-accent-high: #16150f;
+	--sl-color-white: #16150f;
+	--sl-color-gray-1: #2a281f;
+	--sl-color-gray-2: #56544a;
+	--sl-color-gray-3: #6f6c61;
+	--sl-color-gray-4: #87847a;
+	--sl-color-gray-5: #b4b1a5;
+	--sl-color-gray-6: #d6d3c8;
+	--sl-color-gray-7: #e8e6dd;
+	--sl-color-black: #f7f6f2;
+
+	--sl-color-bg: #f7f6f2;
+	--sl-color-bg-nav: #f7f6f2;
+	--sl-color-bg-sidebar: #f7f6f2;
+	--sl-color-bg-inline-code: #e8e6dd;
+	--sl-color-bg-accent: #16150f;
+
+	--sl-color-text: #16150f;
+	--sl-color-text-accent: #16150f;
+	--sl-color-text-invert: #f7f6f2;
+
+	--sl-color-hairline: #16150f;
+	--sl-color-hairline-light: #d6d3c8;
+	--sl-color-hairline-shade: #d6d3c8;
+
+	/* shared tokens */
+	--cg-paper: #f7f6f2;
+	--cg-paper-2: #f1efe8;
+	--cg-paper-press: #e8e6dd;
+	--cg-ink: #16150f;
+	--cg-ink-2: #56544a;
+	--cg-ink-3: #87847a;
+	--cg-rule: #16150f;
+	--cg-rule-soft: #d6d3c8;
+}
+
+/* ---- Starlight colour mapping: dark / ink ---- */
+:root[data-theme='dark'] {
+	--sl-color-accent-low: #34322a;
+	--sl-color-accent: #f3f1ea;
+	--sl-color-accent-high: #f3f1ea;
+	--sl-color-white: #f3f1ea;
+	--sl-color-gray-1: #e7e5dc;
+	--sl-color-gray-2: #c9c6ba;
+	--sl-color-gray-3: #a7a499;
+	--sl-color-gray-4: #7c7a70;
+	--sl-color-gray-5: #57554c;
+	--sl-color-gray-6: #2c2a23;
+	--sl-color-gray-7: #1e1c16;
+	--sl-color-black: #16150f;
+
+	--sl-color-bg: #16150f;
+	--sl-color-bg-nav: #16150f;
+	--sl-color-bg-sidebar: #16150f;
+	--sl-color-bg-inline-code: #23211a;
+	--sl-color-bg-accent: #f3f1ea;
+
+	--sl-color-text: #f3f1ea;
+	--sl-color-text-accent: #f3f1ea;
+	--sl-color-text-invert: #16150f;
+
+	--sl-color-hairline: #f3f1ea;
+	--sl-color-hairline-light: #34322a;
+	--sl-color-hairline-shade: #34322a;
+
+	--cg-paper: #16150f;
+	--cg-paper-2: #1e1c16;
+	--cg-paper-press: #23211a;
+	--cg-ink: #f3f1ea;
+	--cg-ink-2: #b8b5a8;
+	--cg-ink-3: #87847a;
+	--cg-rule: #f3f1ea;
+	--cg-rule-soft: #34322a;
+}
+
+/* ---- Global flat resets ---- */
+*,
+*::before,
+*::after {
+	border-radius: 0 !important; /* this design has no rounded corners, anywhere */
+}
+
+:root {
+	--sl-shadow-sm: none;
+	--sl-shadow-md: none;
+	--sl-shadow-lg: none;
+}
+
+body {
+	background: var(--cg-paper);
+	color: var(--cg-ink);
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+:where(h1, h2, h3, h4, h5) {
+	letter-spacing: -0.02em;
+}
+
+/* ---- Docs chrome ---- */
+
+/* Header: one crisp bottom rule. Starlight nests <div class="header"> inside
+   <header class="header">, so a bare `.header { border-bottom }` draws two
+   lines — put the rule on the outer <header> only and clear the inner div. */
+.header {
+	background: var(--cg-paper);
+	-webkit-backdrop-filter: none;
+	backdrop-filter: none;
+}
+header.header {
+	border-bottom: 1px solid var(--cg-rule);
+}
+.header .header {
+	border-bottom: 0;
+}
+
+/* Sidebar: crisp right rule */
+#starlight__sidebar,
+.sidebar-pane {
+	border-inline-end: 1px solid var(--cg-rule);
+	background: var(--cg-paper);
+}
+
+/* Sidebar group labels — small caps, committed editorial direction */
+.sidebar-content details > summary,
+.sidebar-content > ul > li > span,
+.sidebar-content .large {
+	font-weight: 700;
+	letter-spacing: 0.07em;
+	text-transform: uppercase;
+	font-size: 0.72rem;
+	color: var(--cg-ink-2);
+}
+
+/* Sidebar links */
+.sidebar-content a {
+	color: var(--cg-ink-2);
+}
+.sidebar-content a:hover {
+	background: var(--cg-paper-press);
+	color: var(--cg-ink);
+}
+.sidebar-content a[aria-current='page'],
+.sidebar-content a[aria-current='page']:hover {
+	background: transparent;
+	color: var(--cg-ink);
+	font-weight: 700;
+	border-inline-start: 2px solid var(--cg-ink);
+}
+
+/* Right "On this page" rail */
+starlight-toc a {
+	color: var(--cg-ink-3);
+}
+starlight-toc a[aria-current='true'] {
+	color: var(--cg-ink);
+	font-weight: 600;
+}
+
+/* Prev / next pagination: flat bordered boxes */
+.pagination-links a {
+	border: 1px solid var(--cg-rule);
+	box-shadow: none;
+	background: var(--cg-paper);
+}
+.pagination-links a:hover {
+	background: var(--cg-paper-press);
+}
+
+/* Inline code */
+.sl-markdown-content :not(pre) > code {
+	border: 1px solid var(--cg-rule-soft);
+	background: var(--cg-paper-2);
+	font-size: 0.875em;
+}
+
+/* Cards / asides: square, hairline */
+.card,
+.starlight-aside {
+	border: 1px solid var(--cg-rule);
+	box-shadow: none;
+}
+
+/* Search trigger */
+button[data-open-modal] {
+	border: 1px solid var(--cg-rule);
+	background: var(--cg-paper);
+}
+
+/* Content horizontal rules */
+.sl-markdown-content hr {
+	border: 0;
+	border-top: 1px solid var(--cg-rule);
+}
+
+/* Links in prose */
+.sl-markdown-content a {
+	color: var(--cg-ink);
+	text-underline-offset: 3px;
+}
+
+/* On wide screens Starlight right-aligns the content against the TOC
+   (margin-inline: auto 0), piling all the empty space on the left. Center the
+   content within its pane so it sits balanced between the sidebar and the TOC. */
+@media (min-width: 72rem) {
+	.main-pane {
+		--sl-content-margin-inline: auto;
+	}
+}
diff --git a/site/tsconfig.json b/site/tsconfig.json
new file mode 100644
index 000000000..8bf91d3bb
--- /dev/null
+++ b/site/tsconfig.json
@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}
diff --git a/src/bin/codegraph.ts b/src/bin/codegraph.ts
index de608c361..1dbbca210 100644
--- a/src/bin/codegraph.ts
+++ b/src/bin/codegraph.ts
@@ -7,6 +7,7 @@
  * Usage:
  *   codegraph                    Run interactive installer (when no args)
  *   codegraph install            Run interactive installer
+ *   codegraph uninstall          Remove CodeGraph from your agents
  *   codegraph init [path]        Initialize CodeGraph in a project
  *   codegraph uninit [path]      Remove CodeGraph from a project
  *   codegraph index [path]       Index all files in the project
@@ -15,17 +16,24 @@
  *   codegraph query <search>     Search for symbols
  *   codegraph files [options]    Show project file structure
  *   codegraph context <task>     Build context for a task
+ *   codegraph callers <symbol>   Find what calls a function/method
+ *   codegraph callees <symbol>   Find what a function/method calls
+ *   codegraph impact <symbol>    Analyze what code is affected by changing a symbol
  *   codegraph affected [files]   Find test files affected by changes
+ *   codegraph upgrade [version]  Update CodeGraph to the latest release
  */
 
 import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { getCodeGraphDir, isInitialized } from '../directory';
+import { detectWorktreeIndexMismatch, worktreeMismatchWarning } from '../sync/worktree';
 import { createShimmerProgress } from '../ui/shimmer-progress';
 import { getGlyphs } from '../ui/glyphs';
 
-import { buildNode25BlockBanner } from './node-version-check';
+import { buildNode25BlockBanner, buildNodeTooOldBanner, MIN_NODE_MAJOR } from './node-version-check';
+import { relaunchWithWasmRuntimeFlagsIfNeeded } from '../extraction/wasm-runtime-flags';
+import { EXTRACTION_VERSION } from '../extraction/extraction-version';
 
 // Lazy-load heavy modules (CodeGraph, runInstaller) to keep CLI startup fast.
 async function loadCodeGraph(): Promise<typeof import('../index')> {
@@ -63,6 +71,23 @@ if (nodeMajor >= 25) {
   }
   // Override active — banner shown for visibility, continuing.
 }
+// Enforce the supported Node floor. `engines` in package.json only *warns* on
+// install (unless engine-strict), so hard-block here to actually keep users off
+// unsupported versions. Mirrors the 25+ block above. See package.json `engines`.
+if (nodeMajor < MIN_NODE_MAJOR) {
+  process.stderr.write(buildNodeTooOldBanner(nodeVersion) + '\n');
+  if (!process.env.CODEGRAPH_ALLOW_UNSAFE_NODE) {
+    process.exit(1);
+  }
+  // Override active — banner shown for visibility, continuing.
+}
+
+// Re-exec with V8's `--liftoff-only` if it isn't already set, so tree-sitter's
+// large WASM grammars never hit the turboshaft Zone OOM (`Fatal process out of
+// memory: Zone`) on Node >= 22. No-op under the bundled launcher, which already
+// passes the flag. Must run before any grammar (in the parse worker, which
+// inherits this process's flags) is compiled. See ../extraction/wasm-runtime-flags.
+relaunchWithWasmRuntimeFlagsIfNeeded(__filename);
 
 // Check if running with no arguments - run installer
 if (process.argv.length === 2) {
@@ -331,7 +356,7 @@ function printIndexResult(clack: typeof import('@clack/prompts'), result: IndexR
       clack.log.info(`The index is fully usable ${getGlyphs().dash} only the failed files are missing.`);
     }
   } else if (projectPath) {
-    const logPath = path.join(projectPath, '.codegraph', 'errors.log');
+    const logPath = path.join(getCodeGraphDir(projectPath), 'errors.log');
     if (fs.existsSync(logPath)) {
       fs.unlinkSync(logPath);
     }
@@ -342,7 +367,7 @@ function printIndexResult(clack: typeof import('@clack/prompts'), result: IndexR
  * Write detailed error log to .codegraph/errors.log
  */
 function writeErrorLog(projectPath: string, errors: Array<{ message: string; filePath?: string; severity: string; code?: string }>): void {
-  const cgDir = path.join(projectPath, '.codegraph');
+  const cgDir = getCodeGraphDir(projectPath);
   if (!fs.existsSync(cgDir)) return;
 
   const logPath = path.join(cgDir, 'errors.log');
@@ -393,8 +418,8 @@ function writeErrorLog(projectPath: string, errors: Array<{ message: string; fil
  */
 program
   .command('init [path]')
-  .description('Initialize CodeGraph in a project directory')
-  .option('-i, --index', 'Run initial indexing after initialization')
+  .description('Initialize CodeGraph in a project directory and build the initial index')
+  .option('-i, --index', 'Deprecated: indexing now runs by default; flag accepted for backward compatibility')
   .option('-v, --verbose', 'Show detailed worker lifecycle and memory info')
   .action(async (pathArg: string | undefined, options: { index?: boolean; verbose?: boolean }) => {
     const projectPath = path.resolve(pathArg || process.cwd());
@@ -406,15 +431,6 @@ program
       if (isInitialized(projectPath)) {
         clack.log.warn(`Already initialized in ${projectPath}`);
         clack.log.info('Use "codegraph index" to re-index or "codegraph sync" to update');
-        // Re-run agent surface wiring so re-running `init` is the
-        // documented way to recover a project that's missing its
-        // Cursor rules file (or future per-agent project surfaces).
-        try {
-          const { wireProjectSurfacesForGlobalAgents } = await import('../installer');
-          for (const { target, file } of wireProjectSurfacesForGlobalAgents()) {
-            clack.log.success(`${target.displayName}: ${file.action} ${file.path}`);
-          }
-        } catch { /* non-fatal */ }
         try {
           const { offerWatchFallback } = await import('../installer');
           await offerWatchFallback(clack, projectPath);
@@ -427,41 +443,24 @@ program
       const cg = await CodeGraph.init(projectPath, { index: false });
       clack.log.success(`Initialized in ${projectPath}`);
 
-      // Bootstrap project-local surfaces for any agent that's
-      // configured globally (Cursor needs ./.cursor/rules/codegraph.mdc
-      // to actually prefer codegraph over native grep). Silent when
-      // there's nothing to write.
-      try {
-        const { wireProjectSurfacesForGlobalAgents } = await import('../installer');
-        for (const { target, file } of wireProjectSurfacesForGlobalAgents()) {
-          clack.log.success(`${target.displayName}: ${file.action} ${file.path}`);
-        }
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        clack.log.warn(`Skipped wiring project-local agent surfaces: ${msg}`);
-      }
-
-      if (options.index) {
-        let result: IndexResult;
-
-        if (options.verbose) {
-          result = await cg.indexAll({
-            onProgress: createVerboseProgress(),
-            verbose: true,
-          });
-        } else {
-          process.stdout.write(`${colors.dim}${getGlyphs().rail}${colors.reset}\n`);
-          const progress = createShimmerProgress();
-          result = await cg.indexAll({
-            onProgress: progress.onProgress,
-          });
-          await progress.stop();
-        }
-
-        printIndexResult(clack, result, projectPath);
+      // Indexing runs by default now. The legacy -i/--index flag is still
+      // accepted (so existing muscle memory and scripts don't break) but is a
+      // no-op — initializing always builds the initial index.
+      let result: IndexResult;
+      if (options.verbose) {
+        result = await cg.indexAll({
+          onProgress: createVerboseProgress(),
+          verbose: true,
+        });
       } else {
-        clack.log.info('Run "codegraph index" to index the project');
+        process.stdout.write(`${colors.dim}${getGlyphs().rail}${colors.reset}\n`);
+        const progress = createShimmerProgress();
+        result = await cg.indexAll({
+          onProgress: progress.onProgress,
+        });
+        await progress.stop();
       }
+      printIndexResult(clack, result, projectPath);
 
       try {
         const { offerWatchFallback } = await import('../installer');
@@ -670,11 +669,22 @@ program
   .option('-j, --json', 'Output as JSON')
   .action(async (pathArg: string | undefined, options: { json?: boolean }) => {
     const projectPath = resolveProjectPath(pathArg);
+    // The directory the user actually ran from, before walking up to the index
+    // root. Used to detect when the resolved index lives in a different git
+    // working tree (e.g. a nested worktree borrowing the main checkout's index).
+    const startPath = path.resolve(pathArg || process.cwd());
+    const worktreeMismatch = detectWorktreeIndexMismatch(startPath, projectPath);
 
     try {
       if (!isInitialized(projectPath)) {
         if (options.json) {
-          console.log(JSON.stringify({ initialized: false, projectPath }));
+          console.log(JSON.stringify({
+            initialized: false,
+            version: packageJson.version,
+            projectPath,
+            indexPath: getCodeGraphDir(projectPath),
+            lastIndexed: null,
+          }));
           return;
         }
         console.log(chalk.bold('\nCodeGraph Status\n'));
@@ -689,17 +699,26 @@ program
       const stats = cg.getStats();
       const changes = cg.getChangedFiles();
       const backend = cg.getBackend();
+      const journalMode = cg.getJournalMode();
+
+      const buildInfo = cg.getIndexBuildInfo();
+      const reindexRecommended = cg.isIndexStale();
 
       // JSON output mode
       if (options.json) {
+        const lastIndexedMs = cg.getLastIndexedAt();
         console.log(JSON.stringify({
           initialized: true,
+          version: packageJson.version,
           projectPath,
+          indexPath: getCodeGraphDir(projectPath),
+          lastIndexed: lastIndexedMs != null ? new Date(lastIndexedMs).toISOString() : null,
           fileCount: stats.fileCount,
           nodeCount: stats.nodeCount,
           edgeCount: stats.edgeCount,
           dbSizeBytes: stats.dbSizeBytes,
           backend,
+          journalMode,
           nodesByKind: stats.nodesByKind,
           languages: Object.entries(stats.filesByLanguage).filter(([, count]) => count > 0).map(([lang]) => lang),
           pendingChanges: {
@@ -707,6 +726,15 @@ program
             modified: changes.modified.length,
             removed: changes.removed.length,
           },
+          worktreeMismatch: worktreeMismatch
+            ? { worktreeRoot: worktreeMismatch.worktreeRoot, indexRoot: worktreeMismatch.indexRoot }
+            : null,
+          index: {
+            builtWithVersion: buildInfo.version,
+            builtWithExtractionVersion: buildInfo.extractionVersion,
+            currentExtractionVersion: EXTRACTION_VERSION,
+            reindexRecommended,
+          },
         }));
         cg.destroy();
         return;
@@ -716,6 +744,9 @@ program
 
       // Project info
       console.log(chalk.cyan('Project:'), projectPath);
+      if (worktreeMismatch) {
+        warn(worktreeMismatchWarning(worktreeMismatch));
+      }
       console.log();
 
       // Index stats
@@ -724,14 +755,18 @@ program
       console.log(`  Nodes:     ${formatNumber(stats.nodeCount)}`);
       console.log(`  Edges:     ${formatNumber(stats.edgeCount)}`);
       console.log(`  DB Size:   ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`);
-      // Surface the active SQLite backend so users can spot the silent
-      // WASM fallback (5-10x slower). better-sqlite3 is in
-      // `optionalDependencies`, so `npm install` succeeds without it
-      // when the native build fails.
-      const backendLabel = backend === 'native'
-        ? chalk.green('native')
-        : chalk.yellow(`wasm ${getGlyphs().dash} slower fallback; run \`npm rebuild better-sqlite3\``);
+      // Surface the active SQLite backend (node:sqlite — Node's built-in real
+      // SQLite, full WAL + FTS5, no native build).
+      const backendLabel = chalk.green(`node:sqlite ${getGlyphs().dash} built-in (full WAL)`);
       console.log(`  Backend:   ${backendLabel}`);
+      // Effective journal mode: 'wal' means concurrent reads never block on a
+      // writer; anything else means they can ("database is locked"). node:sqlite
+      // supports WAL everywhere, so a non-wal mode means the filesystem can't
+      // (network mounts, WSL2 /mnt). See issue #238.
+      const journalLabel = journalMode === 'wal'
+        ? chalk.green('wal')
+        : chalk.yellow(`${journalMode || 'unknown'} ${getGlyphs().dash} WAL inactive; reads can block on writes`);
+      console.log(`  Journal:   ${journalLabel}`);
       console.log();
 
       // Node breakdown
@@ -773,6 +808,15 @@ program
       }
       console.log();
 
+      // Re-index hint: the index was built by an older engine than the one now
+      // running, so a rebuild would add data a migration can't backfill.
+      if (reindexRecommended) {
+        const builtWith = buildInfo.version ? `v${buildInfo.version.replace(/^v/, '')}` : 'an earlier version';
+        warn(`Index was built by ${builtWith}; re-index to pick up this engine's improvements.`);
+        info('Run "codegraph index -f" (full rebuild) or "codegraph sync"');
+        console.log();
+      }
+
       cg.destroy();
     } catch (err) {
       error(`Failed to get status: ${err instanceof Error ? err.message : String(err)}`);
@@ -803,11 +847,21 @@ program
       const cg = await CodeGraph.open(projectPath);
 
       const limit = parseInt(options.limit || '10', 10);
-      const results = cg.searchNodes(search, {
+      const rawResults = cg.searchNodes(search, {
         limit,
         kinds: options.kind ? [options.kind as any] : undefined,
       });
 
+      // Mirror the MCP search down-rank so the CLI also surfaces the
+      // hand-written implementation before protobuf/gRPC scaffolding
+      // when both share a name. See extraction/generated-detection.ts.
+      const { isGeneratedFile } = await import('../extraction/generated-detection');
+      const results = [...rawResults].sort((a, b) => {
+        const aGen = isGeneratedFile(a.node.filePath) ? 1 : 0;
+        const bGen = isGeneratedFile(b.node.filePath) ? 1 : 0;
+        return aGen - bGen;
+      });
+
       if (options.json) {
         console.log(JSON.stringify(results, null, 2));
       } else {
@@ -842,6 +896,106 @@ program
     }
   });
 
+/**
+ * codegraph explore <query...>
+ *
+ * The CLI face of the MCP codegraph_explore tool — same handler, same
+ * output (source of the relevant symbols grouped by file + the call path
+ * among them). Exists so agents WITHOUT the MCP tools — Task-tool
+ * subagents (which don't inherit MCP tools, #704) and non-MCP harnesses —
+ * can reach the graph through a plain shell command.
+ */
+program
+  .command('explore <query...>')
+  .description('Explore an area: relevant symbols\' source + call paths in one shot (same output as the codegraph_explore MCP tool)')
+  .option('-p, --path <path>', 'Project path')
+  .option('--max-files <number>', 'Maximum number of files to include source from')
+  .action(async (queryParts: string[], options: { path?: string; maxFiles?: string }) => {
+    const projectPath = resolveProjectPath(options.path);
+
+    try {
+      if (!isInitialized(projectPath)) {
+        error(`CodeGraph isn't available here — no .codegraph/ index exists in ${projectPath}. If you are an AI agent: continue with your usual tools; indexing is the user's decision, do not run it yourself. (The project owner can enable CodeGraph with 'codegraph init'.)`);
+        process.exit(1);
+      }
+
+      const { default: CodeGraph } = await loadCodeGraph();
+      const cg = await CodeGraph.open(projectPath);
+      const { ToolHandler } = await import('../mcp/tools');
+      const handler = new ToolHandler(cg);
+
+      const args: Record<string, unknown> = { query: queryParts.join(' ') };
+      if (options.maxFiles) args.maxFiles = parseInt(options.maxFiles, 10);
+      const result = await handler.execute('codegraph_explore', args);
+
+      console.log(result.content[0]?.text ?? '');
+      cg.destroy();
+      if (result.isError) process.exit(1);
+    } catch (err) {
+      error(`Explore failed: ${err instanceof Error ? err.message : String(err)}`);
+      process.exit(1);
+    }
+  });
+
+/**
+ * codegraph node <name>
+ *
+ * The CLI face of the MCP codegraph_node tool: one symbol's source +
+ * caller/callee trail, or a whole file with line numbers + dependents
+ * (Read-parity). Same subagent/non-MCP rationale as `explore`.
+ */
+program
+  .command('node <name>')
+  .description('One symbol\'s source + caller/callee trail, or read a file with line numbers + dependents (same output as the codegraph_node MCP tool)')
+  .option('-p, --path <path>', 'Project path')
+  .option('-f, --file <file>', 'Treat as file mode (or disambiguate a symbol to this file)')
+  .option('--offset <number>', 'File mode: 1-based start line')
+  .option('--limit <number>', 'File mode: maximum lines')
+  .option('--symbols-only', 'File mode: just the symbol map + dependents')
+  .action(async (name: string, options: { path?: string; file?: string; offset?: string; limit?: string; symbolsOnly?: boolean }) => {
+    const projectPath = resolveProjectPath(options.path);
+
+    try {
+      if (!isInitialized(projectPath)) {
+        error(`CodeGraph isn't available here — no .codegraph/ index exists in ${projectPath}. If you are an AI agent: continue with your usual tools; indexing is the user's decision, do not run it yourself. (The project owner can enable CodeGraph with 'codegraph init'.)`);
+        process.exit(1);
+      }
+
+      const { default: CodeGraph } = await loadCodeGraph();
+      const cg = await CodeGraph.open(projectPath);
+      const { ToolHandler } = await import('../mcp/tools');
+      const handler = new ToolHandler(cg);
+
+      // A name with a path separator is a file read; otherwise a symbol
+      // (use --file for basename-only file reads or to pin an overload).
+      // Both separators: Windows users type src\auth\session.ts. Symbols
+      // never contain either ('/' isn't an identifier char anywhere we
+      // index; C++ scope is '::', JS members '.').
+      const args: Record<string, unknown> = {};
+      if (options.file) {
+        args.file = options.file;
+        if (name && name !== options.file) args.symbol = name;
+      } else if (name.includes('/') || name.includes('\\')) {
+        args.file = name.replace(/\\/g, '/');
+      } else {
+        args.symbol = name;
+        args.includeCode = true;
+      }
+      if (options.offset) args.offset = parseInt(options.offset, 10);
+      if (options.limit) args.limit = parseInt(options.limit, 10);
+      if (options.symbolsOnly) args.symbolsOnly = true;
+
+      const result = await handler.execute('codegraph_node', args);
+
+      console.log(result.content[0]?.text ?? '');
+      cg.destroy();
+      if (result.isError) process.exit(1);
+    } catch (err) {
+      error(`Node lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+      process.exit(1);
+    }
+  });
+
 /**
  * codegraph files [path]
  */
@@ -1049,52 +1203,6 @@ function printFileTree(
   renderNode(root, '', true, 0);
 }
 
-/**
- * codegraph context <task>
- */
-program
-  .command('context <task>')
-  .description('Build context for a task (outputs markdown)')
-  .option('-p, --path <path>', 'Project path')
-  .option('-n, --max-nodes <number>', 'Maximum nodes to include', '50')
-  .option('-c, --max-code <number>', 'Maximum code blocks', '10')
-  .option('--no-code', 'Exclude code blocks')
-  .option('-f, --format <format>', 'Output format (markdown, json)', 'markdown')
-  .action(async (task: string, options: {
-    path?: string;
-    maxNodes?: string;
-    maxCode?: string;
-    code?: boolean;
-    format?: string;
-  }) => {
-    const projectPath = resolveProjectPath(options.path);
-
-    try {
-      if (!isInitialized(projectPath)) {
-        error(`CodeGraph not initialized in ${projectPath}`);
-        process.exit(1);
-      }
-
-      const { default: CodeGraph } = await loadCodeGraph();
-      const cg = await CodeGraph.open(projectPath);
-
-      const context = await cg.buildContext(task, {
-        maxNodes: parseInt(options.maxNodes || '50', 10),
-        maxCodeBlocks: parseInt(options.maxCode || '10', 10),
-        includeCode: options.code !== false,
-        format: options.format as 'markdown' | 'json',
-      });
-
-      // Output the context
-      console.log(context);
-
-      cg.destroy();
-    } catch (err) {
-      error(`Failed to build context: ${err instanceof Error ? err.message : String(err)}`);
-      process.exit(1);
-    }
-  });
-
 /**
  * codegraph serve
  */
@@ -1137,8 +1245,8 @@ program
 }
 `));
         console.error('Available tools:');
+        console.error(chalk.cyan('  codegraph_explore') + '   - Primary: source of the relevant symbols for any question');
         console.error(chalk.cyan('  codegraph_search') + '    - Search for code symbols');
-        console.error(chalk.cyan('  codegraph_context') + '   - Build context for a task');
         console.error(chalk.cyan('  codegraph_callers') + '   - Find callers of a symbol');
         console.error(chalk.cyan('  codegraph_callees') + '   - Find what a symbol calls');
         console.error(chalk.cyan('  codegraph_impact') + '    - Analyze impact of changes');
@@ -1182,6 +1290,264 @@ program
     }
   });
 
+/**
+ * codegraph callers <symbol>
+ *
+ * CLI parity with the MCP graph tools (codegraph_callers/callees/impact) so the
+ * traversal queries work in scripts, CI, and git hooks without a running MCP
+ * server.
+ */
+program
+  .command('callers <symbol>')
+  .description('Find all functions/methods that call a specific symbol')
+  .option('-p, --path <path>', 'Project path')
+  .option('-l, --limit <number>', 'Maximum results', '20')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (symbol: string, options: { path?: string; limit?: string; json?: boolean }) => {
+    const projectPath = resolveProjectPath(options.path);
+
+    try {
+      if (!isInitialized(projectPath)) {
+        error(`CodeGraph not initialized in ${projectPath}`);
+        process.exit(1);
+      }
+
+      const { default: CodeGraph } = await loadCodeGraph();
+      const cg = await CodeGraph.open(projectPath);
+      const limit = parseInt(options.limit || '20', 10);
+
+      const matches = cg.searchNodes(symbol, { limit: 50 });
+      if (matches.length === 0) {
+        info(`Symbol "${symbol}" not found`);
+        cg.destroy();
+        return;
+      }
+
+      const seen = new Set<string>();
+      const allCallers: Array<{ name: string; kind: string; filePath: string; startLine?: number }> = [];
+
+      for (const match of matches) {
+        const exactMatch = match.node.name === symbol || match.node.name.endsWith(`.${symbol}`) || match.node.name.endsWith(`::${symbol}`);
+        if (!exactMatch && matches.length > 1) continue;
+        for (const c of cg.getCallers(match.node.id)) {
+          if (!seen.has(c.node.id)) {
+            seen.add(c.node.id);
+            allCallers.push({ name: c.node.name, kind: c.node.kind, filePath: c.node.filePath, startLine: c.node.startLine });
+          }
+        }
+      }
+
+      // Fallback: if exact filter removed everything, use the top match
+      if (allCallers.length === 0 && matches[0]) {
+        for (const c of cg.getCallers(matches[0].node.id)) {
+          if (!seen.has(c.node.id)) {
+            seen.add(c.node.id);
+            allCallers.push({ name: c.node.name, kind: c.node.kind, filePath: c.node.filePath, startLine: c.node.startLine });
+          }
+        }
+      }
+
+      const limited = allCallers.slice(0, limit);
+
+      if (options.json) {
+        console.log(JSON.stringify({ symbol, callers: limited }, null, 2));
+      } else if (limited.length === 0) {
+        info(`No callers found for "${symbol}"`);
+      } else {
+        console.log(chalk.bold(`\nCallers of "${symbol}" (${limited.length}):\n`));
+        for (const node of limited) {
+          const loc = node.startLine ? `:${node.startLine}` : '';
+          console.log(
+            chalk.cyan(node.kind.padEnd(12)) +
+            chalk.white(node.name)
+          );
+          console.log(chalk.dim(`  ${node.filePath}${loc}`));
+          console.log();
+        }
+      }
+
+      cg.destroy();
+    } catch (err) {
+      error(`callers failed: ${err instanceof Error ? err.message : String(err)}`);
+      process.exit(1);
+    }
+  });
+
+/**
+ * codegraph callees <symbol>
+ */
+program
+  .command('callees <symbol>')
+  .description('Find all functions/methods that a specific symbol calls')
+  .option('-p, --path <path>', 'Project path')
+  .option('-l, --limit <number>', 'Maximum results', '20')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (symbol: string, options: { path?: string; limit?: string; json?: boolean }) => {
+    const projectPath = resolveProjectPath(options.path);
+
+    try {
+      if (!isInitialized(projectPath)) {
+        error(`CodeGraph not initialized in ${projectPath}`);
+        process.exit(1);
+      }
+
+      const { default: CodeGraph } = await loadCodeGraph();
+      const cg = await CodeGraph.open(projectPath);
+      const limit = parseInt(options.limit || '20', 10);
+
+      const matches = cg.searchNodes(symbol, { limit: 50 });
+      if (matches.length === 0) {
+        info(`Symbol "${symbol}" not found`);
+        cg.destroy();
+        return;
+      }
+
+      const seen = new Set<string>();
+      const allCallees: Array<{ name: string; kind: string; filePath: string; startLine?: number }> = [];
+
+      for (const match of matches) {
+        const exactMatch = match.node.name === symbol || match.node.name.endsWith(`.${symbol}`) || match.node.name.endsWith(`::${symbol}`);
+        if (!exactMatch && matches.length > 1) continue;
+        for (const c of cg.getCallees(match.node.id)) {
+          if (!seen.has(c.node.id)) {
+            seen.add(c.node.id);
+            allCallees.push({ name: c.node.name, kind: c.node.kind, filePath: c.node.filePath, startLine: c.node.startLine });
+          }
+        }
+      }
+
+      if (allCallees.length === 0 && matches[0]) {
+        for (const c of cg.getCallees(matches[0].node.id)) {
+          if (!seen.has(c.node.id)) {
+            seen.add(c.node.id);
+            allCallees.push({ name: c.node.name, kind: c.node.kind, filePath: c.node.filePath, startLine: c.node.startLine });
+          }
+        }
+      }
+
+      const limited = allCallees.slice(0, limit);
+
+      if (options.json) {
+        console.log(JSON.stringify({ symbol, callees: limited }, null, 2));
+      } else if (limited.length === 0) {
+        info(`No callees found for "${symbol}"`);
+      } else {
+        console.log(chalk.bold(`\nCallees of "${symbol}" (${limited.length}):\n`));
+        for (const node of limited) {
+          const loc = node.startLine ? `:${node.startLine}` : '';
+          console.log(
+            chalk.cyan(node.kind.padEnd(12)) +
+            chalk.white(node.name)
+          );
+          console.log(chalk.dim(`  ${node.filePath}${loc}`));
+          console.log();
+        }
+      }
+
+      cg.destroy();
+    } catch (err) {
+      error(`callees failed: ${err instanceof Error ? err.message : String(err)}`);
+      process.exit(1);
+    }
+  });
+
+/**
+ * codegraph impact <symbol>
+ */
+program
+  .command('impact <symbol>')
+  .description('Analyze what code is affected by changing a symbol')
+  .option('-p, --path <path>', 'Project path')
+  .option('-d, --depth <number>', 'Traversal depth', '2')
+  .option('-j, --json', 'Output as JSON')
+  .action(async (symbol: string, options: { path?: string; depth?: string; json?: boolean }) => {
+    const projectPath = resolveProjectPath(options.path);
+
+    try {
+      if (!isInitialized(projectPath)) {
+        error(`CodeGraph not initialized in ${projectPath}`);
+        process.exit(1);
+      }
+
+      const { default: CodeGraph } = await loadCodeGraph();
+      const cg = await CodeGraph.open(projectPath);
+      const depth = Math.min(Math.max(parseInt(options.depth || '2', 10), 1), 10);
+
+      const matches = cg.searchNodes(symbol, { limit: 50 });
+      if (matches.length === 0) {
+        info(`Symbol "${symbol}" not found`);
+        cg.destroy();
+        return;
+      }
+
+      // Merge impact subgraphs across all exact-matching symbols
+      const mergedNodes = new Map<string, { name: string; kind: string; filePath: string; startLine?: number }>();
+      const seenEdges = new Set<string>();
+      let edgeCount = 0;
+
+      for (const match of matches) {
+        const exactMatch = match.node.name === symbol || match.node.name.endsWith(`.${symbol}`) || match.node.name.endsWith(`::${symbol}`);
+        if (!exactMatch && matches.length > 1) continue;
+        const impact = cg.getImpactRadius(match.node.id, depth);
+        for (const [id, n] of impact.nodes) {
+          mergedNodes.set(id, { name: n.name, kind: n.kind, filePath: n.filePath, startLine: n.startLine });
+        }
+        for (const e of impact.edges) {
+          const key = `${e.source}->${e.target}:${e.kind}`;
+          if (!seenEdges.has(key)) {
+            seenEdges.add(key);
+            edgeCount++;
+          }
+        }
+      }
+
+      // Fallback to top match if exact filter removed everything
+      if (mergedNodes.size === 0 && matches[0]) {
+        const impact = cg.getImpactRadius(matches[0].node.id, depth);
+        for (const [id, n] of impact.nodes) {
+          mergedNodes.set(id, { name: n.name, kind: n.kind, filePath: n.filePath, startLine: n.startLine });
+        }
+        edgeCount = impact.edges.length;
+      }
+
+      if (options.json) {
+        console.log(JSON.stringify({
+          symbol,
+          depth,
+          nodeCount: mergedNodes.size,
+          edgeCount,
+          affected: Array.from(mergedNodes.values()),
+        }, null, 2));
+      } else if (mergedNodes.size === 0) {
+        info(`No affected symbols found for "${symbol}"`);
+      } else {
+        console.log(chalk.bold(`\nImpact of changing "${symbol}" — ${mergedNodes.size} affected symbols:\n`));
+
+        // Group by file
+        const byFile = new Map<string, Array<{ name: string; kind: string; startLine?: number }>>();
+        for (const node of mergedNodes.values()) {
+          const list = byFile.get(node.filePath) || [];
+          list.push({ name: node.name, kind: node.kind, startLine: node.startLine });
+          byFile.set(node.filePath, list);
+        }
+
+        for (const [file, nodes] of byFile) {
+          console.log(chalk.cyan(file));
+          for (const node of nodes) {
+            const loc = node.startLine ? `:${node.startLine}` : '';
+            console.log(`  ${chalk.dim(node.kind.padEnd(12))}${node.name}${chalk.dim(loc)}`);
+          }
+          console.log();
+        }
+      }
+
+      cg.destroy();
+    } catch (err) {
+      error(`impact failed: ${err instanceof Error ? err.message : String(err)}`);
+      process.exit(1);
+    }
+  });
+
 /**
  * codegraph affected [files...]
  *
@@ -1325,7 +1691,7 @@ program
  */
 program
   .command('install')
-  .description('Install codegraph MCP server into one or more agents (Claude Code, Cursor, Codex CLI, opencode)')
+  .description('Install codegraph MCP server into one or more agents (Claude Code, Cursor, Codex CLI, opencode, Hermes Agent)')
   .option('-t, --target <ids>', 'Target agent(s): comma-separated ids, or "auto"|"all"|"none". Default: prompt')
   .option('-l, --location <where>', 'Install location: "global" or "local". Default: prompt')
   .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=auto, auto-allow on')
@@ -1382,6 +1748,79 @@ program
     }
   });
 
+/**
+ * codegraph uninstall
+ *
+ * Inverse of `install`. Removes the codegraph MCP server entry,
+ * instructions block, and permissions from every agent (or a
+ * `--target` subset). Prompts global-vs-local when not given. Does NOT
+ * delete the `.codegraph/` index — that's `codegraph uninit`.
+ */
+program
+  .command('uninstall')
+  .description('Remove codegraph from your agents (Claude Code, Cursor, Codex CLI, opencode, Hermes Agent)')
+  .option('-t, --target <ids>', 'Target agent(s): comma-separated ids, or "all". Default: all')
+  .option('-l, --location <where>', 'Uninstall location: "global" or "local". Default: prompt')
+  .option('-y, --yes', 'Non-interactive: defaults to --location=global --target=all')
+  .action(async (opts: {
+    target?: string;
+    location?: string;
+    yes?: boolean;
+  }) => {
+    const { runUninstaller } = await import('../installer');
+    if (opts.location && opts.location !== 'global' && opts.location !== 'local') {
+      error(`--location must be "global" or "local" (got "${opts.location}").`);
+      process.exit(1);
+    }
+    try {
+      await runUninstaller({
+        target: opts.target,
+        location: opts.location as 'global' | 'local' | undefined,
+        yes: opts.yes,
+      });
+    } catch (err) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+
+/**
+ * codegraph upgrade [version]
+ *
+ * Self-update, however CodeGraph was installed (bundle via install.sh/.ps1,
+ * npm-global, npx, or a source checkout). See ../upgrade for the detection and
+ * per-method upgrade logic.
+ */
+program
+  .command('upgrade [version]')
+  .description('Update CodeGraph to the latest release (or a specific version)')
+  .option('--check', 'Check whether an update is available without installing')
+  .option('-f, --force', 'Reinstall even if already on the target version')
+  .action(async (versionArg: string | undefined, options: { check?: boolean; force?: boolean }) => {
+    const up = await import('../upgrade');
+    const method = up.detectInstallMethod({
+      filename: __filename,
+      platform: process.platform,
+      cwd: process.cwd(),
+    });
+    const pin = versionArg || process.env.CODEGRAPH_VERSION || undefined;
+    const code = await up.runUpgrade(
+      { version: pin, check: options.check, force: options.force },
+      {
+        currentVersion: packageJson.version,
+        method,
+        resolveLatest: () => up.resolveLatestVersion(),
+        run: up.defaultRun,
+        hasCommand: up.hasCommand,
+        log: (m: string) => console.log(m),
+        warn: (m: string) => warn(m),
+        error: (m: string) => error(m),
+        platform: process.platform,
+      }
+    );
+    process.exit(code);
+  });
+
 // Parse and run
 program.parse();
 
diff --git a/src/bin/node-version-check.ts b/src/bin/node-version-check.ts
index 4d7539a5c..cea0a4351 100644
--- a/src/bin/node-version-check.ts
+++ b/src/bin/node-version-check.ts
@@ -37,3 +37,40 @@ export function buildNode25BlockBanner(nodeVersion: string): string {
     sep,
   ].join('\n');
 }
+
+/**
+ * Lowest supported Node.js major version. Matches the `engines` floor in
+ * package.json. Below this, CodeGraph relies on language features / native APIs
+ * that aren't present, and the combination is untested. `engines` alone only
+ * *warns* on install (unless the user set `engine-strict`), so the CLI bootstrap
+ * also hard-blocks here to actually enforce the floor.
+ */
+export const MIN_NODE_MAJOR = 20;
+
+/**
+ * Build the bordered banner shown when CodeGraph detects a Node.js major below
+ * {@link MIN_NODE_MAJOR}. Pinned via unit test so the recovery commands and the
+ * override env var can't be silently stripped by future edits.
+ *
+ * Uses ASCII glyphs to stay readable on Windows OEM-codepage consoles
+ * (see ../ui/glyphs.ts for the rationale).
+ */
+export function buildNodeTooOldBanner(nodeVersion: string): string {
+  const sep = '-'.repeat(72);
+  return [
+    sep,
+    `[CodeGraph] Unsupported Node.js version: ${nodeVersion}`,
+    sep,
+    `CodeGraph requires Node.js ${MIN_NODE_MAJOR} or newer. Older versions lack`,
+    'language features and native APIs CodeGraph depends on, and are not',
+    'tested or supported.',
+    '',
+    'Fix: install Node.js 22 LTS:',
+    '  nvm install 22 && nvm use 22                          # nvm',
+    '  brew install node@22 && brew link --overwrite --force node@22  # Homebrew',
+    '',
+    'To override (NOT recommended - unsupported):',
+    '  CODEGRAPH_ALLOW_UNSAFE_NODE=1 codegraph ...',
+    sep,
+  ].join('\n');
+}
diff --git a/src/config.ts b/src/config.ts
deleted file mode 100644
index 9ab1032a6..000000000
--- a/src/config.ts
+++ /dev/null
@@ -1,297 +0,0 @@
-/**
- * Configuration Management
- *
- * Load, save, and validate CodeGraph configuration.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import picomatch from 'picomatch';
-import { CodeGraphConfig, DEFAULT_CONFIG, Language, NodeKind } from './types';
-import { normalizePath } from './utils';
-
-/**
- * Configuration filename
- */
-export const CONFIG_FILENAME = 'config.json';
-
-/**
- * Get the config file path for a project
- */
-export function getConfigPath(projectRoot: string): string {
-  return path.join(projectRoot, '.codegraph', CONFIG_FILENAME);
-}
-
-/**
- * Check if a regex pattern is safe from ReDoS attacks.
- *
- * Rejects patterns with nested quantifiers (e.g., (a+)+, (a*)*) which
- * are the primary source of catastrophic backtracking. Also rejects
- * excessively long patterns and validates compilability.
- */
-function isSafeRegex(pattern: string): boolean {
-  // Reject excessively long patterns
-  if (pattern.length > 500) return false;
-
-  // Reject nested quantifiers: (...)+ followed by +, *, or {
-  // These are the primary cause of catastrophic backtracking
-  if (/([+*}])\s*[+*{]/.test(pattern)) return false;
-  if (/\([^)]*[+*][^)]*\)[+*{]/.test(pattern)) return false;
-
-  // Verify the pattern is a valid regex
-  try {
-    new RegExp(pattern);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Validate a configuration object
- */
-export function validateConfig(config: unknown): config is CodeGraphConfig {
-  if (typeof config !== 'object' || config === null) {
-    return false;
-  }
-
-  const c = config as Record<string, unknown>;
-
-  // Required fields
-  if (typeof c.version !== 'number') return false;
-  if (typeof c.rootDir !== 'string') return false;
-  if (!Array.isArray(c.include)) return false;
-  if (!Array.isArray(c.exclude)) return false;
-  if (!Array.isArray(c.languages)) return false;
-  if (!Array.isArray(c.frameworks)) return false;
-  if (typeof c.maxFileSize !== 'number') return false;
-  if (typeof c.extractDocstrings !== 'boolean') return false;
-  if (typeof c.trackCallSites !== 'boolean') return false;
-
-  // Validate include/exclude are string arrays
-  if (!c.include.every((p) => typeof p === 'string')) return false;
-  if (!c.exclude.every((p) => typeof p === 'string')) return false;
-
-  // Validate languages
-  const validLanguages: Language[] = [
-    'typescript',
-    'javascript',
-    'python',
-    'go',
-    'rust',
-    'java',
-    'svelte',
-    'unknown',
-  ];
-  if (!c.languages.every((l) => validLanguages.includes(l as Language))) return false;
-
-  // Validate frameworks
-  for (const fw of c.frameworks) {
-    if (typeof fw !== 'object' || fw === null) return false;
-    const framework = fw as Record<string, unknown>;
-    if (typeof framework.name !== 'string') return false;
-  }
-
-  // Validate custom patterns if present
-  if (c.customPatterns !== undefined) {
-    if (!Array.isArray(c.customPatterns)) return false;
-    for (const pattern of c.customPatterns) {
-      if (typeof pattern !== 'object' || pattern === null) return false;
-      const p = pattern as Record<string, unknown>;
-      if (typeof p.name !== 'string') return false;
-      if (typeof p.pattern !== 'string') return false;
-      if (typeof p.kind !== 'string') return false;
-
-      // Validate regex is compilable and reject patterns with known ReDoS risks
-      if (!isSafeRegex(p.pattern)) return false;
-    }
-  }
-
-  return true;
-}
-
-/**
- * Merge configuration with defaults
- */
-function mergeConfig(
-  defaults: CodeGraphConfig,
-  overrides: Partial<CodeGraphConfig>
-): CodeGraphConfig {
-  return {
-    version: overrides.version ?? defaults.version,
-    rootDir: overrides.rootDir ?? defaults.rootDir,
-    include: overrides.include ?? defaults.include,
-    exclude: overrides.exclude ?? defaults.exclude,
-    languages: overrides.languages ?? defaults.languages,
-    frameworks: overrides.frameworks ?? defaults.frameworks,
-    maxFileSize: overrides.maxFileSize ?? defaults.maxFileSize,
-    extractDocstrings: overrides.extractDocstrings ?? defaults.extractDocstrings,
-    trackCallSites: overrides.trackCallSites ?? defaults.trackCallSites,
-    customPatterns: overrides.customPatterns ?? defaults.customPatterns,
-  };
-}
-
-/**
- * Load configuration from a project
- */
-export function loadConfig(projectRoot: string): CodeGraphConfig {
-  const configPath = getConfigPath(projectRoot);
-
-  if (!fs.existsSync(configPath)) {
-    // Return default config with adjusted rootDir
-    return {
-      ...DEFAULT_CONFIG,
-      rootDir: projectRoot,
-    };
-  }
-
-  try {
-    const content = fs.readFileSync(configPath, 'utf-8');
-    const parsed = JSON.parse(content) as unknown;
-
-    // Merge with defaults to ensure all fields are present
-    const merged = mergeConfig(DEFAULT_CONFIG, parsed as Partial<CodeGraphConfig>);
-    merged.rootDir = projectRoot; // Always use actual project root
-
-    if (!validateConfig(merged)) {
-      throw new Error('Invalid configuration format');
-    }
-
-    return merged;
-  } catch (error) {
-    if (error instanceof SyntaxError) {
-      throw new Error(`Invalid JSON in config file: ${configPath}`);
-    }
-    throw error;
-  }
-}
-
-/**
- * Save configuration to a project
- */
-export function saveConfig(projectRoot: string, config: CodeGraphConfig): void {
-  const configPath = getConfigPath(projectRoot);
-  const dir = path.dirname(configPath);
-
-  // Ensure directory exists
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-
-  // Create a copy without rootDir (it's always derived from project path)
-  const toSave = { ...config };
-  delete (toSave as Partial<CodeGraphConfig>).rootDir;
-
-  const content = JSON.stringify(toSave, null, 2);
-
-  // Atomic write: write to temp file then rename to prevent partial/corrupt configs
-  const tmpPath = configPath + '.tmp';
-  fs.writeFileSync(tmpPath, content, 'utf-8');
-  fs.renameSync(tmpPath, configPath);
-}
-
-/**
- * Create default configuration for a new project
- */
-export function createDefaultConfig(projectRoot: string): CodeGraphConfig {
-  return {
-    ...DEFAULT_CONFIG,
-    rootDir: projectRoot,
-  };
-}
-
-/**
- * Update specific configuration values
- */
-export function updateConfig(
-  projectRoot: string,
-  updates: Partial<CodeGraphConfig>
-): CodeGraphConfig {
-  const current = loadConfig(projectRoot);
-  const updated = mergeConfig(current, updates);
-  updated.rootDir = projectRoot;
-  saveConfig(projectRoot, updated);
-  return updated;
-}
-
-/**
- * Add patterns to include list
- */
-export function addIncludePatterns(projectRoot: string, patterns: string[]): CodeGraphConfig {
-  const config = loadConfig(projectRoot);
-  const newPatterns = patterns.filter((p) => !config.include.includes(p));
-  config.include = [...config.include, ...newPatterns];
-  saveConfig(projectRoot, config);
-  return config;
-}
-
-/**
- * Add patterns to exclude list
- */
-export function addExcludePatterns(projectRoot: string, patterns: string[]): CodeGraphConfig {
-  const config = loadConfig(projectRoot);
-  const newPatterns = patterns.filter((p) => !config.exclude.includes(p));
-  config.exclude = [...config.exclude, ...newPatterns];
-  saveConfig(projectRoot, config);
-  return config;
-}
-
-/**
- * Add a custom pattern
- */
-export function addCustomPattern(
-  projectRoot: string,
-  name: string,
-  pattern: string,
-  kind: NodeKind
-): CodeGraphConfig {
-  const config = loadConfig(projectRoot);
-
-  if (!config.customPatterns) {
-    config.customPatterns = [];
-  }
-
-  // Check for duplicate name
-  const existing = config.customPatterns.find((p) => p.name === name);
-  if (existing) {
-    existing.pattern = pattern;
-    existing.kind = kind;
-  } else {
-    config.customPatterns.push({ name, pattern, kind });
-  }
-
-  saveConfig(projectRoot, config);
-  return config;
-}
-
-/**
- * Check if a file path matches the include/exclude patterns
- */
-export function shouldIncludeFile(filePath: string, config: CodeGraphConfig): boolean {
-  // Normalize to forward slashes so Windows backslash paths match glob patterns
-  filePath = normalizePath(filePath);
-
-  // Simple glob matching (for now, just check if any pattern matches)
-  // A full implementation would use a proper glob library
-
-  const matchesPattern = (pattern: string, filePath: string): boolean => {
-    return picomatch.isMatch(filePath, pattern, { dot: true });
-  };
-
-  // Check exclude patterns first
-  for (const pattern of config.exclude) {
-    if (matchesPattern(pattern, filePath)) {
-      return false;
-    }
-  }
-
-  // Check include patterns
-  for (const pattern of config.include) {
-    if (matchesPattern(pattern, filePath)) {
-      return true;
-    }
-  }
-
-  // Default to not including if no pattern matches
-  return false;
-}
diff --git a/src/context/formatter.ts b/src/context/formatter.ts
index 37a08ee84..748d17201 100644
--- a/src/context/formatter.ts
+++ b/src/context/formatter.ts
@@ -5,6 +5,7 @@
  */
 
 import { Node, Edge, TaskContext, Subgraph } from '../types';
+import { isGeneratedFile } from '../extraction/generated-detection';
 
 /**
  * Format context as markdown
@@ -21,10 +22,17 @@ export function formatContextAsMarkdown(context: TaskContext): string {
   lines.push('## Code Context\n');
   lines.push(`**Query:** ${context.query}\n`);
 
-  // Entry points - compact format
-  if (context.entryPoints.length > 0) {
+  // Entry points - compact format. Re-sort so generated files (.pb.go,
+  // .pulsar.go, mocks, …) rank LAST — a flow query should lead with the
+  // hand-written implementation, not protobuf scaffolding.
+  const orderedEntries = [...context.entryPoints].sort((a, b) => {
+    const aGen = isGeneratedFile(a.filePath) ? 1 : 0;
+    const bGen = isGeneratedFile(b.filePath) ? 1 : 0;
+    return aGen - bGen;
+  });
+  if (orderedEntries.length > 0) {
     lines.push('### Entry Points\n');
-    for (const node of context.entryPoints) {
+    for (const node of orderedEntries) {
       const location = node.startLine ? `:${node.startLine}` : '';
       lines.push(`- **${node.name}** (${node.kind}) - ${node.filePath}${location}`);
       if (node.signature) {
@@ -34,9 +42,14 @@ export function formatContextAsMarkdown(context: TaskContext): string {
     lines.push('');
   }
 
-  // Related symbols - compact list (skip verbose structure tree)
+  // Related symbols - compact list (skip verbose structure tree). Drop nodes
+  // in generated source files (`.pb.go` / `.pulsar.go` / mocks / …) — agents
+  // chasing a flow never want to land on protobuf scaffolding (cosmos-Q3 used
+  // to list `gov.pulsar.go::GetExpeditedThreshold` and `1.pulsar.go::Get` in
+  // Related Symbols, pure noise that displaced real-flow entries).
   const otherSymbols = Array.from(context.subgraph.nodes.values())
     .filter(n => !context.entryPoints.some(e => e.id === n.id))
+    .filter(n => !isGeneratedFile(n.filePath))
     .slice(0, 10); // Limit to 10 related symbols
 
   if (otherSymbols.length > 0) {
@@ -55,10 +68,16 @@ export function formatContextAsMarkdown(context: TaskContext): string {
     lines.push('');
   }
 
-  // Code blocks - only for key entry points
+  // Code blocks - only for key entry points. Re-sort so non-generated blocks
+  // show first (consistent with Entry Points reordering above).
   if (context.codeBlocks.length > 0) {
+    const orderedBlocks = [...context.codeBlocks].sort((a, b) => {
+      const aGen = isGeneratedFile(a.filePath) ? 1 : 0;
+      const bGen = isGeneratedFile(b.filePath) ? 1 : 0;
+      return aGen - bGen;
+    });
     lines.push('### Code\n');
-    for (const block of context.codeBlocks) {
+    for (const block of orderedBlocks) {
       const nodeName = block.node?.name ?? 'Unknown';
       lines.push(`#### ${nodeName} (${block.filePath}:${block.startLine})\n`);
       lines.push('```' + block.language);
diff --git a/src/context/index.ts b/src/context/index.ts
index 7298cd411..68123c284 100644
--- a/src/context/index.ts
+++ b/src/context/index.ts
@@ -24,8 +24,9 @@ import { QueryBuilder } from '../db/queries';
 import { GraphTraverser } from '../graph';
 import { formatContextAsMarkdown, formatContextAsJson } from './formatter';
 import { logDebug } from '../errors';
-import { validatePathWithinRoot } from '../utils';
-import { isTestFile, extractSearchTerms, scorePathRelevance, getStemVariants } from '../search/query-utils';
+import { validatePathWithinRoot, isConfigLeafNode } from '../utils';
+import { isTestFile, extractSearchTerms, scorePathRelevance, getStemVariants, isDistinctiveIdentifier } from '../search/query-utils';
+import { LOW_CONFIDENCE_MARKER } from './markers';
 
 /**
  * Extract likely symbol names from a natural language query
@@ -172,6 +173,11 @@ const DEFAULT_FIND_OPTIONS: Required<FindRelevantContextOptions> = {
   nodeKinds: HIGH_VALUE_NODE_KINDS, // Filter out imports/exports by default
 };
 
+// Re-export the low-confidence sentinel (defined in a dependency-free leaf so
+// the MCP layer can import it without pulling this module's deps onto the
+// cold-start path). Builder code below uses the imported binding directly.
+export { LOW_CONFIDENCE_MARKER } from './markers';
+
 /**
  * Context Builder
  *
@@ -259,7 +265,9 @@ export class ContextBuilder {
 
     // Return formatted output or raw context
     if (opts.format === 'markdown') {
-      return formatContextAsMarkdown(context);
+      return formatContextAsMarkdown(context)
+        + this.buildCallPathsSection(subgraph)
+        + (subgraph.confidence === 'low' ? this.buildLowConfidenceNote(entryPoints) : '');
     } else if (opts.format === 'json') {
       return formatContextAsJson(context);
     }
@@ -267,6 +275,146 @@ export class ContextBuilder {
     return context;
   }
 
+  /**
+   * Honest handoff appended when retrieval confidence is low (the query matched
+   * mostly common words). Instead of the usual "this covers the surface" framing
+   * — which, when wrong, sends the agent off to Read/Grep — it admits the
+   * uncertainty and routes the agent to the precise tools (explore with real
+   * symbol names, search, or files to browse the closest areas we *did* surface).
+   */
+  private buildLowConfidenceNote(entryPoints: Node[]): string {
+    const dirs: string[] = [];
+    const seen = new Set<string>();
+    for (const n of entryPoints) {
+      const slash = n.filePath.lastIndexOf('/');
+      const dir = slash > 0 ? n.filePath.slice(0, slash) : n.filePath;
+      if (!seen.has(dir)) { seen.add(dir); dirs.push(dir); }
+      if (dirs.length >= 4) break;
+    }
+    const dirLine = dirs.length
+      ? `\n- \`codegraph_files\` a likely area: ${dirs.map(d => `\`${d}\``).join(', ')}`
+      : '';
+    return `\n\n${LOW_CONFIDENCE_MARKER}\n\n`
+      + 'This query matched mostly on common words, so the entry points above may '
+      + 'be off-target — treat them as a starting point, not a complete answer. '
+      + 'For a reliable result:\n'
+      + '- `codegraph_explore` with the **exact symbol names** you are after '
+      + '(class / function / method names), or\n'
+      + '- `codegraph_search <name>` for one specific symbol'
+      + dirLine
+      + '\n\nDo not assume the list above is comprehensive.';
+  }
+
+  /**
+   * Surface short call-paths among the symbols this context already found,
+   * derived in-memory from the subgraph's `calls` edges (no extra queries).
+   *
+   * This bakes the value of path-finding INTO the always-loaded `context` tool.
+   * Agents reliably read context's output but do NOT discover/adopt a standalone
+   * trace tool (in deferred-MCP harnesses they only ToolSearch-select tools they
+   * already know). Delivering the flow here means "how does X reach Y" is
+   * answered without the agent needing to find, load, or choose a new tool.
+   * Chains stop where the static call graph ends (e.g. dynamic dispatch) — that
+   * truncation is honest, and the agent can codegraph_node the last hop to bridge.
+   */
+  private buildCallPathsSection(subgraph: Subgraph): string {
+    const adj = new Map<string, string[]>();
+    for (const e of subgraph.edges) {
+      if (e.kind !== 'calls') continue;
+      if (!subgraph.nodes.has(e.source) || !subgraph.nodes.has(e.target)) continue;
+      const list = adj.get(e.source);
+      if (list) list.push(e.target);
+      else adj.set(e.source, [e.target]);
+    }
+    if (adj.size === 0) return '';
+
+    const MAX_HOPS = 6;
+    const chains: string[][] = [];
+    let budget = 2000; // bound DFS work on dense subgraphs
+    const dfs = (id: string, path: string[], seen: Set<string>): void => {
+      if (budget-- <= 0) return;
+      const next = (adj.get(id) ?? []).filter((t) => !seen.has(t));
+      if (next.length === 0 || path.length >= MAX_HOPS) {
+        if (path.length >= 3) chains.push([...path]); // >=3 nodes = a real flow, not a single call
+        return;
+      }
+      for (const t of next) {
+        seen.add(t);
+        dfs(t, [...path, t], seen);
+        seen.delete(t);
+      }
+    };
+    const starts = (subgraph.roots.length > 0
+      ? subgraph.roots.filter((id) => adj.has(id))
+      : [...adj.keys()]
+    ).slice(0, 5);
+    for (const s of starts) dfs(s, [s], new Set([s]));
+    if (chains.length === 0) return '';
+
+    // Keep only chains that connect TWO OR MORE query-relevant symbols (roots).
+    // A chain from a root into an arbitrary callee (render → onMagicFrameGenerate)
+    // is structurally valid but tangential to the question; requiring ≥2 roots
+    // keeps the chain anchored to what the user actually asked about. Rank by
+    // #roots then length, and drop any that are a sub-path of a longer kept chain.
+    const rootSet = new Set(subgraph.roots);
+    const rootCount = (c: string[]): number => c.reduce((n, id) => n + (rootSet.has(id) ? 1 : 0), 0);
+    const relevant = chains.filter((c) => rootCount(c) >= 2);
+    relevant.sort((a, b) => rootCount(b) - rootCount(a) || b.length - a.length);
+    const kept: string[][] = [];
+    for (const c of relevant) {
+      const key = c.join('>');
+      if (kept.some((k) => k.join('>').includes(key))) continue;
+      kept.push(c);
+      if (kept.length >= 3) break;
+    }
+    if (kept.length === 0) return '';
+    const name = (id: string): string => subgraph.nodes.get(id)?.name ?? id;
+
+    // Synthesized (dynamic-dispatch) hops are real `calls` edges but invisible to
+    // static parsing — mark them inline so the agent sees WHERE the callback was
+    // wired up (`registered @file:line`) instead of grepping for it. Keyed by
+    // "source>target".
+    const synthByPair = new Map<string, string>();
+    for (const e of subgraph.edges) {
+      if (e.kind !== 'calls' || e.provenance !== 'heuristic') continue;
+      const m = e.metadata as Record<string, unknown> | undefined;
+      if (!m?.synthesizedBy) continue;
+      const at = typeof m.registeredAt === 'string' ? ` @${m.registeredAt}` : '';
+      const label = m.synthesizedBy === 'callback'
+        ? `callback via ${m.via ? `\`${String(m.via)}\`` : 'registrar'}${at}`
+        : m.synthesizedBy === 'react-render'
+        ? `React re-render via setState${at}`
+        : m.synthesizedBy === 'jsx-render'
+        ? `renders <${String(m.via || 'child')}>`
+        : m.synthesizedBy === 'vue-handler'
+        ? `Vue @${String(m.event || 'event')} handler`
+        : `event ${m.event ? `\`${String(m.event)}\`` : ''}${at}`;
+      synthByPair.set(`${e.source}>${e.target}`, label);
+    }
+    const renderChain = (c: string[]): string => {
+      let s = name(c[0]!);
+      for (let i = 1; i < c.length; i++) {
+        const synth = synthByPair.get(`${c[i - 1]}>${c[i]}`);
+        s += synth ? ` →[${synth}] ${name(c[i]!)}` : ` → ${name(c[i]!)}`;
+      }
+      return s;
+    };
+    const hasSynth = kept.some((c) => c.some((_, i) => i > 0 && synthByPair.has(`${c[i - 1]}>${c[i]}`)));
+    const lines = [
+      '',
+      '## Call paths',
+      '',
+      'Execution flow among the key symbols (traced through the call graph):',
+      '',
+      ...kept.map((c) => `- ${renderChain(c)}`),
+      '',
+      hasSynth
+        ? '_Hops marked `[callback/event …]` are dynamic dispatch bridged by codegraph (with the registration site); the rest are direct calls. codegraph_node any symbol for its body._'
+        : '_codegraph_node any symbol above for its source + its own callers/callees._',
+    ];
+    return '\n' + lines.join('\n') + '\n';
+  }
+
   /**
    * Find relevant subgraph for a query
    *
@@ -477,6 +625,37 @@ export class ContextBuilder {
       }
     }
 
+    // Iter7 — Core-directory boost. On projects with one file that holds
+    // the dense majority of internal call edges (e.g. sinatra's
+    // `lib/sinatra/base.rb` at 85% of all in-file edges), the agent's
+    // task usually asks about the framework's core. Without this boost,
+    // ranking favors small focused extension files (e.g. text search
+    // picks `sinatra-contrib/lib/sinatra/multi_route.rb`'s 10-line
+    // `route` method over `base.rb`'s `route!` because the extension
+    // file's `route` matches the query verbatim AND the file is small,
+    // dwarfing the longer name `route!` in a 1500-line file). Boost
+    // results that share a directory prefix with the dominant file's
+    // directory so the core file's siblings outrank sibling-package
+    // extensions.
+    try {
+      const dominant = this.queries.getDominantFile?.();
+      if (dominant && dominant.edgeCount >= 3 * dominant.nextEdgeCount) {
+        // Take the directory of the dominant file (everything up to the
+        // last slash). For `lib/sinatra/base.rb` → `lib/sinatra/`.
+        const slash = dominant.filePath.lastIndexOf('/');
+        if (slash > 0) {
+          const coreDir = dominant.filePath.slice(0, slash + 1);
+          for (const result of searchResults) {
+            if (result.node.filePath.startsWith(coreDir)) {
+              result.score += 25;
+            }
+          }
+        }
+      }
+    } catch {
+      // SQL failure — fall through, scoring works without the boost
+    }
+
     // Step 5a: Multi-term co-occurrence re-ranking (applied BEFORE truncation).
     // For multi-word queries like "search execution from request to shard",
     // nodes matching 2+ query terms in their name or path are far more relevant
@@ -512,6 +691,21 @@ export class ContextBuilder {
       // term group is counter-productive.
       const exactMatchIds = new Set(exactMatches.map(r => r.node.id));
 
+      // ...but only exempt exact matches the user *named as an identifier*
+      // (camelCase/snake_case/acronym). A plain dictionary word that happens to
+      // exact-match an unrelated symbol — query "flat object" → a constant named
+      // FLAT — must NOT be exempt, or the +exact-name bonus floats it to the top
+      // of a prose query with zero corroboration from any other term. Classify by
+      // the QUERY token (what the user typed), not the matched symbol's name.
+      const distinctiveTokens = new Set(
+        symbolsFromQuery.filter(isDistinctiveIdentifier).map(s => s.toLowerCase())
+      );
+      const distinctiveExactMatchIds = new Set(
+        exactMatches
+          .filter(r => distinctiveTokens.has(r.node.name.toLowerCase()))
+          .map(r => r.node.id)
+      );
+
       for (const result of searchResults) {
         // Check term matches in name (substring) and path DIRECTORIES (exact).
         // Directory segments must match exactly — "search" matches directory
@@ -531,10 +725,17 @@ export class ContextBuilder {
         if (matchCount >= 2) {
           // Multiplicative boost — 2 terms → 2x, 3 terms → 2.5x
           result.score *= 1 + matchCount * 0.5;
-        } else if (!exactMatchIds.has(result.node.id)) {
-          // Mild dampen for single-term matches — they might be generic
+        } else if (distinctiveExactMatchIds.has(result.node.id)) {
+          // Exact match on a distinctive identifier the user explicitly named —
+          // keep full score (e.g. "LiveEditMode DevServerPreview").
+        } else if (exactMatchIds.has(result.node.id)) {
+          // Exact match on a COMMON word (e.g. "flat" → FLAT): high-scoring noise
+          // inflated by the +exact-name bonus, corroborated by no other query
+          // term. Demote hard so corroborated matches win.
+          result.score *= 0.3;
+        } else {
+          // Mild dampen for generic single-term matches — they might be generic
           // but could also be the right result (e.g., "Protocol" class for an IPC query).
-          // Exempt exact name matches: they are specific symbols the user queried for.
           result.score *= 0.6;
         }
       }
@@ -700,6 +901,35 @@ export class ContextBuilder {
       filteredResults = filteredResults.slice(0, opts.searchLimit);
     }
 
+    // Confidence signal for the honest-handoff footer (consumed in buildContext).
+    // A multi-term prose query that resolves only to isolated common-word matches
+    // — no entry point corroborated by 2+ distinct query terms, and none a
+    // distinctive identifier the user explicitly named — is LOW confidence: the
+    // results are best-effort, not a located answer, so the agent should be told
+    // to drill in with explore/trace rather than trust the list as comprehensive.
+    // Single-keyword and symbol-name queries are exempt (their single match IS the
+    // answer), so the handoff never fires on them.
+    let confidence: 'high' | 'low' = 'high';
+    const confTerms = extractSearchTerms(query, { stems: false }).filter(t => t.length >= 3);
+    if (confTerms.length >= 2 && filteredResults.length > 0) {
+      const distinctive = new Set(
+        symbolsFromQuery.filter(isDistinctiveIdentifier).map(s => s.toLowerCase())
+      );
+      const anyStrong = filteredResults.some(r => {
+        if (distinctive.has(r.node.name.toLowerCase())) return true;
+        const nameLower = r.node.name.toLowerCase();
+        const dirSegs = path.dirname(r.node.filePath).toLowerCase().split('/');
+        let hits = 0;
+        for (const t of confTerms) {
+          if (nameLower.includes(t) || dirSegs.includes(t)) {
+            if (++hits >= 2) return true;
+          }
+        }
+        return false;
+      });
+      if (!anyStrong) confidence = 'low';
+    }
+
     // Add entry points to subgraph
     for (const result of filteredResults) {
       nodes.set(result.node.id, result.node);
@@ -907,7 +1137,7 @@ export class ContextBuilder {
       }
     }
 
-    return { nodes: finalNodes, edges: finalEdges, roots };
+    return { nodes: finalNodes, edges: finalEdges, roots, confidence };
   }
 
   /**
@@ -931,6 +1161,14 @@ export class ContextBuilder {
    * Extract code from a node's source file
    */
   private async extractNodeCode(node: Node): Promise<string | null> {
+    // SECURITY (#383): a config-leaf node's on-disk line is `key = <secret>`.
+    // Return the KEY only — never read the value off disk. This closes the
+    // includeCode / buildContext code-block path, mirroring the explore source
+    // renderer; an agent that genuinely needs a value can read the file itself.
+    if (isConfigLeafNode(node)) {
+      return node.signature || node.qualifiedName || node.name;
+    }
+
     const filePath = validatePathWithinRoot(this.projectRoot, node.filePath);
 
     if (!filePath || !fs.existsSync(filePath)) {
diff --git a/src/context/markers.ts b/src/context/markers.ts
new file mode 100644
index 000000000..13f1968b4
--- /dev/null
+++ b/src/context/markers.ts
@@ -0,0 +1,19 @@
+/**
+ * Stable sentinel strings shared between the context builder (which emits them
+ * into its markdown) and the MCP layer (which detects them to adjust framing).
+ *
+ * Intentionally a dependency-free leaf module: the MCP tool layer imports this
+ * to recognise a low-confidence response, and routing that recognition through
+ * the full context module would drag its dependencies onto the cold-start path.
+ * Keep this file import-free.
+ */
+
+/**
+ * Heading that leads the honest low-confidence handoff appended to a context
+ * response when the query resolved only to weak/isolated matches. The MCP layer
+ * checks for it to suppress the contradictory "this is comprehensive, don't call
+ * explore" small-repo footer. Changing the text is a breaking sentinel change —
+ * both the emitter (`ContextBuilder`) and the detector (`src/mcp/tools.ts`)
+ * import this constant, so they stay in sync automatically.
+ */
+export const LOW_CONFIDENCE_MARKER = '### ⚠️ Low-confidence match';
diff --git a/src/db/index.ts b/src/db/index.ts
index 3e490746f..e6d52d47a 100644
--- a/src/db/index.ts
+++ b/src/db/index.ts
@@ -9,8 +9,33 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { SchemaVersion } from '../types';
 import { runMigrations, getCurrentVersion, CURRENT_SCHEMA_VERSION } from './migrations';
+import { getCodeGraphDir } from '../directory';
 
-export { SqliteDatabase, SqliteBackend, WASM_FALLBACK_FIX_RECIPE } from './sqlite-adapter';
+export { SqliteDatabase, SqliteBackend } from './sqlite-adapter';
+
+/**
+ * Apply connection-level PRAGMAs. Shared by `initialize` and `open` so the two
+ * paths can't drift.
+ *
+ * `busy_timeout` is set FIRST, before any pragma that might touch the database
+ * file (notably `journal_mode`). If another process holds a write lock at open
+ * time, the later pragmas — and the connection's first query — then wait out
+ * the lock instead of throwing "database is locked" immediately. See issue #238.
+ *
+ * The 5s window (was 120s) rides out a normal incremental sync; the old
+ * 2-minute wait presented as a frozen, hung agent. With WAL, reads never block
+ * on a writer, so this timeout only governs cross-process write contention
+ * (e.g. the git-hook `codegraph sync` running while the MCP server writes).
+ */
+function configureConnection(db: SqliteDatabase): void {
+  db.pragma('busy_timeout = 5000');      // MUST be first — see above
+  db.pragma('foreign_keys = ON');
+  db.pragma('journal_mode = WAL');       // node:sqlite supports WAL on every platform
+  db.pragma('synchronous = NORMAL');     // safe with WAL mode
+  db.pragma('cache_size = -64000');      // 64 MB page cache
+  db.pragma('temp_store = MEMORY');      // temp tables in memory
+  db.pragma('mmap_size = 268435456');    // 256 MB memory-mapped I/O
+}
 
 /**
  * Database connection wrapper with lifecycle management
@@ -39,17 +64,7 @@ export class DatabaseConnection {
     // Create and configure database
     const { db, backend } = createDatabase(dbPath);
 
-    // Enable foreign keys and WAL mode for better performance
-    db.pragma('foreign_keys = ON');
-    db.pragma('journal_mode = WAL');
-    // Wait up to 2 minutes if database is locked by another process
-    // (indexing operations can hold locks for extended periods)
-    db.pragma('busy_timeout = 120000');
-    // Performance tuning
-    db.pragma('synchronous = NORMAL');     // Safe with WAL mode
-    db.pragma('cache_size = -64000');      // 64 MB page cache
-    db.pragma('temp_store = MEMORY');      // Temp tables in memory
-    db.pragma('mmap_size = 268435456');    // 256 MB memory-mapped I/O
+    configureConnection(db);
 
     // Run schema initialization
     const schemaPath = path.join(__dirname, 'schema.sql');
@@ -77,17 +92,7 @@ export class DatabaseConnection {
 
     const { db, backend } = createDatabase(dbPath);
 
-    // Enable foreign keys and WAL mode
-    db.pragma('foreign_keys = ON');
-    db.pragma('journal_mode = WAL');
-    // Wait up to 2 minutes if database is locked by another process
-    // (indexing operations can hold locks for extended periods)
-    db.pragma('busy_timeout = 120000');
-    // Performance tuning
-    db.pragma('synchronous = NORMAL');
-    db.pragma('cache_size = -64000');
-    db.pragma('temp_store = MEMORY');
-    db.pragma('mmap_size = 268435456');
+    configureConnection(db);
 
     // Check and run migrations if needed
     const conn = new DatabaseConnection(db, dbPath, backend);
@@ -123,6 +128,25 @@ export class DatabaseConnection {
     return this.dbPath;
   }
 
+  /**
+   * The journal mode actually in effect (e.g. 'wal', 'delete').
+   *
+   * 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
+   * 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.
+   */
+  getJournalMode(): string {
+    const raw = this.db.pragma('journal_mode');
+    const row = Array.isArray(raw) ? raw[0] : raw;
+    const mode = row && typeof row === 'object'
+      ? (row as Record<string, unknown>).journal_mode
+      : row;
+    return String(mode ?? '').toLowerCase();
+  }
+
   /**
    * Get current schema version
    */
@@ -163,6 +187,36 @@ export class DatabaseConnection {
     this.db.exec('ANALYZE');
   }
 
+  /**
+   * Lightweight, non-blocking maintenance to run after bulk writes
+   * (indexAll, sync). Two operations:
+   *
+   *   - `PRAGMA optimize` — incremental ANALYZE; SQLite only re-analyzes
+   *     tables whose row counts changed materially since the last
+   *     ANALYZE. Without it, the query planner has no statistics on the
+   *     freshly-bulk-loaded tables and can pick suboptimal indexes.
+   *
+   *   - `PRAGMA wal_checkpoint(PASSIVE)` — fold pending WAL pages back
+   *     into the main database file so the WAL file doesn't grow
+   *     unboundedly between automatic checkpoints (auto-fires at 1000
+   *     pages by default; large indexAll runs blow past that).
+   *
+   * Both operations are silently swallowed on failure — they're a
+   * best-effort optimization, never load-bearing for correctness.
+   */
+  runMaintenance(): void {
+    try {
+      this.db.exec('PRAGMA optimize');
+    } catch {
+      // ignore
+    }
+    try {
+      this.db.exec('PRAGMA wal_checkpoint(PASSIVE)');
+    } catch {
+      // ignore (e.g., not in WAL mode)
+    }
+  }
+
   /**
    * Close the database connection
    */
@@ -187,5 +241,5 @@ export const DATABASE_FILENAME = 'codegraph.db';
  * Get the default database path for a project
  */
 export function getDatabasePath(projectRoot: string): string {
-  return path.join(projectRoot, '.codegraph', DATABASE_FILENAME);
+  return path.join(getCodeGraphDir(projectRoot), DATABASE_FILENAME);
 }
diff --git a/src/db/migrations.ts b/src/db/migrations.ts
index 1a8d1c542..bfea9024d 100644
--- a/src/db/migrations.ts
+++ b/src/db/migrations.ts
@@ -9,7 +9,7 @@ import { SqliteDatabase } from './sqlite-adapter';
 /**
  * Current schema version
  */
-export const CURRENT_SCHEMA_VERSION = 4;
+export const CURRENT_SCHEMA_VERSION = 5;
 
 /**
  * Migration definition
@@ -65,6 +65,16 @@ const migrations: Migration[] = [
       `);
     },
   },
+  {
+    version: 5,
+    description:
+      'Add nodes.return_type — normalized return/result type for receiver-type inference (C++ singletons/factories, #645)',
+    up: (db) => {
+      db.exec(`
+        ALTER TABLE nodes ADD COLUMN return_type TEXT;
+      `);
+    },
+  },
 ];
 
 /**
diff --git a/src/db/queries.ts b/src/db/queries.ts
index ebba66e6a..adf239268 100644
--- a/src/db/queries.ts
+++ b/src/db/queries.ts
@@ -20,6 +20,34 @@ import {
 import { safeJsonParse } from '../utils';
 import { kindBonus, nameMatchBonus, scorePathRelevance } from '../search/query-utils';
 import { parseQuery, boundedEditDistance } from '../search/query-parser';
+import { isGeneratedFile } from '../extraction/generated-detection';
+
+/**
+ * Path-only heuristic for files that should not be candidates for
+ * "dominant file" detection: test/spec files and tool-generated files.
+ * Generated files (`*.pb.go`, `*.pulsar.go`, mock outputs, …) often
+ * have huge in-file edge counts that dwarf the real source — etcd's
+ * `rpc.pb.go` has 4× the in-file edges of `server.go`.
+ */
+function isLowValueFile(filePath: string): boolean {
+  const lp = filePath.toLowerCase();
+  return (
+    /(?:^|\/)(tests?|__tests?__|spec)\//.test(lp) ||
+    /_test\.go$/.test(lp) ||
+    /(?:^|\/)test_[^/]+\.py$/.test(lp) ||
+    /_test\.py$/.test(lp) ||
+    /_spec\.rb$/.test(lp) ||
+    /_test\.rb$/.test(lp) ||
+    /\.(test|spec)\.[jt]sx?$/.test(lp) ||
+    /(test|spec|tests)\.(java|kt|scala)$/.test(lp) ||
+    /(tests?|spec)\.cs$/.test(lp) ||
+    /tests?\.swift$/.test(lp) ||
+    /_test\.dart$/.test(lp) ||
+    isGeneratedFile(filePath)
+  );
+}
+
+const SQLITE_PARAM_CHUNK_SIZE = 500;
 
 /**
  * Database row types (snake_case from SQLite)
@@ -44,6 +72,7 @@ interface NodeRow {
   is_abstract: number;
   decorators: string | null;
   type_parameters: string | null;
+  return_type: string | null;
   updated_at: number;
 }
 
@@ -105,6 +134,7 @@ function rowToNode(row: NodeRow): Node {
     isAbstract: row.is_abstract === 1,
     decorators: row.decorators ? safeJsonParse(row.decorators, undefined) : undefined,
     typeParameters: row.type_parameters ? safeJsonParse(row.type_parameters, undefined) : undefined,
+    returnType: row.return_type ?? undefined,
     updatedAt: row.updated_at,
   };
 }
@@ -146,6 +176,12 @@ function rowToFileRecord(row: FileRow): FileRecord {
 export class QueryBuilder {
   private db: SqliteDatabase;
 
+  // Project-name tokens (go.mod / package.json / repo dir), normalized. A query
+  // word matching one is dropped from path-relevance scoring — it names the
+  // whole project, not a symbol, so it carries no discriminative signal (#720).
+  // Set once by the CodeGraph instance; empty by default (no down-weighting).
+  private projectNameTokens: Set<string> = new Set();
+
   // Node cache for frequently accessed nodes (LRU-style, max 1000 entries)
   private nodeCache: Map<string, Node> = new Map();
   private readonly maxCacheSize = 1000;
@@ -180,12 +216,26 @@ export class QueryBuilder {
     getUnresolvedBatch?: SqliteStatement;
     getAllFilePaths?: SqliteStatement;
     getAllNodeNames?: SqliteStatement;
+    getDominantFile?: SqliteStatement;
+    getTopRouteFile?: SqliteStatement;
+    getRoutingManifest?: SqliteStatement;
   } = {};
 
   constructor(db: SqliteDatabase) {
     this.db = db;
   }
 
+  /** Set the normalized project-name tokens used to down-weight non-discriminative
+   * query words in path scoring (#720). Called once when the project opens. */
+  setProjectNameTokens(tokens: Set<string>): void {
+    this.projectNameTokens = tokens;
+  }
+
+  /** The normalized project-name tokens (#720); empty if none were derived. */
+  getProjectNameTokens(): Set<string> {
+    return this.projectNameTokens;
+  }
+
   // ===========================================================================
   // Node Operations
   // ===========================================================================
@@ -201,13 +251,13 @@ export class QueryBuilder {
           start_line, end_line, start_column, end_column,
           docstring, signature, visibility,
           is_exported, is_async, is_static, is_abstract,
-          decorators, type_parameters, updated_at
+          decorators, type_parameters, return_type, updated_at
         ) VALUES (
           @id, @kind, @name, @qualifiedName, @filePath, @language,
           @startLine, @endLine, @startColumn, @endColumn,
           @docstring, @signature, @visibility,
           @isExported, @isAsync, @isStatic, @isAbstract,
-          @decorators, @typeParameters, @updatedAt
+          @decorators, @typeParameters, @returnType, @updatedAt
         )
       `);
     }
@@ -224,32 +274,35 @@ export class QueryBuilder {
       return;
     }
 
-    try {
-      this.stmts.insertNode.run({
-        id: node.id,
-        kind: node.kind,
-        name: node.name,
-        qualifiedName: node.qualifiedName ?? node.name,
-        filePath: node.filePath,
-        language: node.language,
-        startLine: node.startLine ?? 0,
-        endLine: node.endLine ?? 0,
-        startColumn: node.startColumn ?? 0,
-        endColumn: node.endColumn ?? 0,
-        docstring: node.docstring ?? null,
-        signature: node.signature ?? null,
-        visibility: node.visibility ?? null,
-        isExported: node.isExported ? 1 : 0,
-        isAsync: node.isAsync ? 1 : 0,
-        isStatic: node.isStatic ? 1 : 0,
-        isAbstract: node.isAbstract ? 1 : 0,
-        decorators: node.decorators ? JSON.stringify(node.decorators) : null,
-        typeParameters: node.typeParameters ? JSON.stringify(node.typeParameters) : null,
-        updatedAt: node.updatedAt ?? Date.now(),
-      });
-    } catch (error) {
-      throw error;
-    }
+    // INSERT OR REPLACE may overwrite a node we have cached. Drop the
+    // stale entry so the next getNodeById sees the new row, not the old
+    // one (matches the cache-invalidation pattern used by updateNode and
+    // deleteNode below).
+    this.nodeCache.delete(node.id);
+
+    this.stmts.insertNode.run({
+      id: node.id,
+      kind: node.kind,
+      name: node.name,
+      qualifiedName: node.qualifiedName ?? node.name,
+      filePath: node.filePath,
+      language: node.language,
+      startLine: node.startLine ?? 0,
+      endLine: node.endLine ?? 0,
+      startColumn: node.startColumn ?? 0,
+      endColumn: node.endColumn ?? 0,
+      docstring: node.docstring ?? null,
+      signature: node.signature ?? null,
+      visibility: node.visibility ?? null,
+      isExported: node.isExported ? 1 : 0,
+      isAsync: node.isAsync ? 1 : 0,
+      isStatic: node.isStatic ? 1 : 0,
+      isAbstract: node.isAbstract ? 1 : 0,
+      decorators: node.decorators ? JSON.stringify(node.decorators) : null,
+      typeParameters: node.typeParameters ? JSON.stringify(node.typeParameters) : null,
+      returnType: node.returnType ?? null,
+      updatedAt: node.updatedAt ?? Date.now(),
+    });
   }
 
   /**
@@ -288,6 +341,7 @@ export class QueryBuilder {
           is_abstract = @isAbstract,
           decorators = @decorators,
           type_parameters = @typeParameters,
+          return_type = @returnType,
           updated_at = @updatedAt
         WHERE id = @id
       `);
@@ -322,6 +376,7 @@ export class QueryBuilder {
       isAbstract: node.isAbstract ? 1 : 0,
       decorators: node.decorators ? JSON.stringify(node.decorators) : null,
       typeParameters: node.typeParameters ? JSON.stringify(node.typeParameters) : null,
+      returnType: node.returnType ?? null,
       updatedAt: node.updatedAt ?? Date.now(),
     });
   }
@@ -380,6 +435,77 @@ export class QueryBuilder {
     return node;
   }
 
+  /**
+   * Batch lookup: fetch many nodes by ID in a single SQL round-trip.
+   *
+   * Replaces the N+1 pattern in graph traversal where every edge would
+   * trigger its own `getNodeById` call. For a function with 50 callers
+   * this collapses 50 point reads into one IN-list query (~10-50x
+   * faster end-to-end).
+   *
+   * Returns a Map keyed by id so callers can preserve their own ordering
+   * (typically the order edges were returned from the graph). Missing IDs
+   * are simply absent from the map.
+   *
+   * Cache-aware: ids already in the LRU cache are served from memory and
+   * the SQL query only touches the misses.
+   */
+  getNodesByIds(ids: readonly string[]): Map<string, Node> {
+    const out = new Map<string, Node>();
+    if (ids.length === 0) return out;
+
+    // Serve cache hits first; build the miss list for SQL.
+    const misses: string[] = [];
+    for (const id of ids) {
+      const cached = this.nodeCache.get(id);
+      if (cached !== undefined) {
+        // LRU touch
+        this.nodeCache.delete(id);
+        this.nodeCache.set(id, cached);
+        out.set(id, cached);
+      } else {
+        misses.push(id);
+      }
+    }
+    if (misses.length === 0) return out;
+
+    // Chunk under SQLite's parameter limit (default 999, raised to 32766
+    // in better-sqlite3 builds — chunk at 500 for safety across both
+    // backends and to keep the query plan simple).
+    for (let i = 0; i < misses.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+      const chunk = misses.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+      const placeholders = chunk.map(() => '?').join(',');
+      const rows = this.db
+        .prepare(`SELECT * FROM nodes WHERE id IN (${placeholders})`)
+        .all(...chunk) as NodeRow[];
+      for (const row of rows) {
+        const node = rowToNode(row);
+        out.set(node.id, node);
+        this.cacheNode(node);
+      }
+    }
+    return out;
+  }
+
+  private getExistingNodeIds(ids: readonly string[]): Set<string> {
+    const out = new Set<string>();
+    if (ids.length === 0) return out;
+
+    const uniqueIds = [...new Set(ids)];
+    for (let i = 0; i < uniqueIds.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+      const chunk = uniqueIds.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+      const placeholders = chunk.map(() => '?').join(',');
+      const rows = this.db
+        .prepare(`SELECT id FROM nodes WHERE id IN (${placeholders})`)
+        .all(...chunk) as { id: string }[];
+      for (const row of rows) {
+        out.add(row.id);
+      }
+    }
+
+    return out;
+  }
+
   /**
    * Add a node to the cache, evicting oldest if needed
    */
@@ -414,6 +540,158 @@ export class QueryBuilder {
     return rows.map(rowToNode);
   }
 
+  /**
+   * Find the file that holds the densest concentration of the project's
+   * internal call graph — the "core" file. Used by context-builder to
+   * boost ranking of symbols in that file's directory (so e.g. sinatra
+   * queries surface `lib/sinatra/base.rb`'s `route!` instead of
+   * `sinatra-contrib/lib/sinatra/multi_route.rb`'s `route` extension).
+   *
+   * Returns null if no file has a meaningful concentration (e.g. spread
+   * evenly across many files, or empty index).
+   *
+   * "Internal" = source and target are in the same file. Cross-file
+   * edges aren't useful here — they don't tell us which file is the
+   * functional center.
+   *
+   * Excludes test/spec files from candidacy via path-pattern. The agent's
+   * typical question is "how does X work", not "how is X tested", so
+   * boosting a test file's directory would be a misfire.
+   */
+  getDominantFile(): { filePath: string; edgeCount: number; nextEdgeCount: number } | null {
+    if (!this.stmts.getDominantFile) {
+      // Pull top 20 candidates; we then filter out test/generated files
+      // in code (regex-grade matching that SQL LIKE can't express). The
+      // generated-file filter is critical — without it, etcd's
+      // `api/etcdserverpb/rpc.pb.go` (1916 in-file edges, generated
+      // protobuf stub) outranks the real `server/etcdserver/server.go`
+      // (470 edges) by 4×, and the boost would push the agent toward
+      // generated code.
+      this.stmts.getDominantFile = this.db.prepare(`
+        SELECT n.file_path AS file_path, COUNT(*) AS edge_count
+        FROM edges e
+        JOIN nodes n ON e.source = n.id
+        JOIN nodes m ON e.target = m.id
+        WHERE n.file_path = m.file_path
+        GROUP BY n.file_path
+        ORDER BY edge_count DESC
+        LIMIT 20
+      `);
+    }
+    const rows = this.stmts.getDominantFile.all() as Array<{ file_path: string; edge_count: number }>;
+    const filtered = rows.filter(r => !isLowValueFile(r.file_path));
+    if (filtered.length === 0 || filtered[0]!.edge_count < 20) return null;
+    return {
+      filePath: filtered[0]!.file_path,
+      edgeCount: filtered[0]!.edge_count,
+      nextEdgeCount: filtered[1]?.edge_count ?? 0,
+    };
+  }
+
+  /**
+   * Find the file that holds the densest concentration of the project's
+   * `route` nodes (framework-emitted: Express/Gin/Flask/Rails/Drupal/etc.).
+   * Used by handleContext on small repos to inline the project's routing
+   * config when the agent's query is about request flow — eliminating the
+   * "Glob + Read routes.rb" pattern that beats codegraph on tiny realworld
+   * template repos.
+   *
+   * Excludes test/generated files from candidacy. Returns null if there
+   * are fewer than 3 non-test routes total, or if no file holds at least
+   * 30% of them (diffuse routing → no single answer file).
+   */
+  getTopRouteFile(): { filePath: string; routeCount: number; totalRoutes: number } | null {
+    if (!this.stmts.getTopRouteFile) {
+      this.stmts.getTopRouteFile = this.db.prepare(`
+        SELECT file_path, COUNT(*) AS cnt
+        FROM nodes
+        WHERE kind = 'route'
+        GROUP BY file_path
+        ORDER BY cnt DESC
+        LIMIT 20
+      `);
+    }
+    const rows = this.stmts.getTopRouteFile.all() as Array<{ file_path: string; cnt: number }>;
+    const filtered = rows.filter(r => !isLowValueFile(r.file_path));
+    if (filtered.length === 0) return null;
+    const totalRoutes = filtered.reduce((sum, r) => sum + r.cnt, 0);
+    const top = filtered[0]!;
+    if (totalRoutes < 3 || top.cnt < 3) return null;
+    if (top.cnt / totalRoutes < 0.30) return null;
+    return { filePath: top.file_path, routeCount: top.cnt, totalRoutes };
+  }
+
+  /**
+   * Build a URL → handler manifest from the index. Each route node's
+   * `references` edge points at the function/method that handles the
+   * request. We join them in one pass; the agent gets the canonical
+   * routing answer ("POST /users/login → AuthController#login") without
+   * having to parse the framework's route DSL itself.
+   *
+   * Also returns the file with the most handler endpoints — used as the
+   * "top handler file" to inline source for, so the agent has both the
+   * mapping AND the handler implementations.
+   */
+  getRoutingManifest(limit: number = 40): {
+    entries: Array<{ url: string; handler: string; handlerFile: string; handlerLine: number; handlerKind: string }>;
+    topHandlerFile: string | null;
+    topHandlerFileCount: number;
+    totalRoutes: number;
+  } | null {
+    if (!this.stmts.getRoutingManifest) {
+      // Edge kind varies across framework resolvers: Spring/Rails/
+      // Laravel/Drupal emit `references`, Express emits `calls`. Accept
+      // both — the semantic is the same (route → its handler).
+      this.stmts.getRoutingManifest = this.db.prepare(`
+        SELECT
+          r.name AS url,
+          h.name AS handler,
+          h.file_path AS handler_file,
+          h.start_line AS handler_line,
+          h.kind AS handler_kind
+        FROM nodes r
+        JOIN edges e ON e.source = r.id
+        JOIN nodes h ON e.target = h.id
+        WHERE r.kind = 'route'
+          AND e.kind IN ('references', 'calls')
+          AND h.kind IN ('function', 'method', 'class')
+        ORDER BY r.file_path, r.start_line
+        LIMIT ?
+      `);
+    }
+    const rows = this.stmts.getRoutingManifest.all(limit) as Array<{
+      url: string; handler: string; handler_file: string; handler_line: number; handler_kind: string;
+    }>;
+    // Drop test/generated handlers — same hygiene as elsewhere.
+    const filtered = rows.filter(r => !isLowValueFile(r.handler_file));
+    if (filtered.length < 3) return null;
+    // Identify the file holding the most handlers (the "primary handler file").
+    const fileCounts = new Map<string, number>();
+    for (const r of filtered) {
+      fileCounts.set(r.handler_file, (fileCounts.get(r.handler_file) ?? 0) + 1);
+    }
+    let topHandlerFile: string | null = null;
+    let topHandlerFileCount = 0;
+    for (const [file, count] of fileCounts) {
+      if (count > topHandlerFileCount) {
+        topHandlerFile = file;
+        topHandlerFileCount = count;
+      }
+    }
+    return {
+      entries: filtered.map(r => ({
+        url: r.url,
+        handler: r.handler,
+        handlerFile: r.handler_file,
+        handlerLine: r.handler_line,
+        handlerKind: r.handler_kind,
+      })),
+      topHandlerFile,
+      topHandlerFileCount,
+      totalRoutes: filtered.length,
+    };
+  }
+
   /**
    * Get all nodes of a specific kind
    */
@@ -425,6 +703,22 @@ export class QueryBuilder {
     return rows.map(rowToNode);
   }
 
+  /**
+   * Stream every node of a kind one at a time (lazy) instead of materializing
+   * them all like {@link getNodesByKind}. For unbounded kinds (`function`,
+   * `method`) on a symbol-dense project the full array is gigabytes; the
+   * dynamic-edge synthesizers only scan-and-filter, so they iterate to keep
+   * memory O(1) in the node count rather than O(nodes) (#610).
+   */
+  *iterateNodesByKind(kind: NodeKind): IterableIterator<Node> {
+    // Fresh statement per call (not a cached one): an iterator holds an open
+    // cursor, so a shared statement would conflict across overlapping scans.
+    const stmt = this.db.prepare('SELECT * FROM nodes WHERE kind = ?');
+    for (const row of stmt.iterate(kind)) {
+      yield rowToNode(row as NodeRow);
+    }
+  }
+
   /**
    * Get all nodes in the database
    */
@@ -565,7 +859,7 @@ export class QueryBuilder {
         ...r,
         score: r.score
           + kindBonus(r.node.kind)
-          + scorePathRelevance(r.node.filePath, scoringQuery)
+          + scorePathRelevance(r.node.filePath, scoringQuery, this.projectNameTokens)
           + nameMatchBonus(r.node.name, scoringQuery),
       }));
       results.sort((a, b) => b.score - a.score);
@@ -984,8 +1278,20 @@ export class QueryBuilder {
    * Insert multiple edges in a transaction
    */
   insertEdges(edges: Edge[]): void {
+    if (edges.length === 0) return;
+
     this.db.transaction(() => {
+      const endpointIds = new Set<string>();
       for (const edge of edges) {
+        endpointIds.add(edge.source);
+        endpointIds.add(edge.target);
+      }
+      const existingNodeIds = this.getExistingNodeIds([...endpointIds]);
+
+      for (const edge of edges) {
+        if (!existingNodeIds.has(edge.source) || !existingNodeIds.has(edge.target)) {
+          continue;
+        }
         this.insertEdge(edge);
       }
     })();
@@ -1067,6 +1373,52 @@ export class QueryBuilder {
     return rows.map(rowToEdge);
   }
 
+  /**
+   * Distinct file paths that DEPEND ON `filePath`: every file containing a
+   * symbol with a cross-file edge (any kind except `contains`) into a symbol
+   * of this file. This is the file-level projection of the symbol dependency
+   * graph and the basis for blast-radius / `affected` test selection.
+   *
+   * It deliberately does NOT restrict to `imports` edges. In this graph an
+   * `imports` edge connects a file to its own local import declarations
+   * (it is always same-file), so an imports-only lookup returns zero
+   * cross-file dependents for every file. The real cross-file dependency
+   * signal is the resolved call/reference graph — calls, references,
+   * instantiates, extends, implements, overrides, type_of, returns,
+   * decorates — exactly what {@link GraphTraverser.getImpactRadius} traverses.
+   * `contains` is excluded: a parent containing a symbol does not *depend* on
+   * it. One indexed query (idx_nodes_file_path + idx_edges_target_kind).
+   */
+  getDependentFilePaths(filePath: string): string[] {
+    const sql = `SELECT DISTINCT src.file_path AS fp
+      FROM edges e
+      JOIN nodes tgt ON tgt.id = e.target
+      JOIN nodes src ON src.id = e.source
+      WHERE tgt.file_path = ?
+        AND e.kind != 'contains'
+        AND src.file_path != ?`;
+    const rows = this.db.prepare(sql).all(filePath, filePath) as Array<{ fp: string }>;
+    return rows.map((r) => r.fp);
+  }
+
+  /**
+   * Distinct file paths that `filePath` DEPENDS ON — the inverse of
+   * {@link getDependentFilePaths}: every file containing a symbol that a
+   * symbol of this file has a cross-file edge into. Same edge-kind rules
+   * (all kinds except `contains`); same reason imports-only is insufficient.
+   */
+  getDependencyFilePaths(filePath: string): string[] {
+    const sql = `SELECT DISTINCT tgt.file_path AS fp
+      FROM edges e
+      JOIN nodes src ON src.id = e.source
+      JOIN nodes tgt ON tgt.id = e.target
+      WHERE src.file_path = ?
+        AND e.kind != 'contains'
+        AND tgt.file_path != ?`;
+    const rows = this.db.prepare(sql).all(filePath, filePath) as Array<{ fp: string }>;
+    return rows.map((r) => r.fp);
+  }
+
   // ===========================================================================
   // File Operations
   // ===========================================================================
@@ -1137,6 +1489,17 @@ export class QueryBuilder {
     return rows.map(rowToFileRecord);
   }
 
+  /**
+   * Most recent index timestamp (ms since epoch) across all tracked files, or
+   * null when nothing is indexed yet. One indexed aggregate, no per-row scan. (#329)
+   */
+  getLastIndexedAt(): number | null {
+    const row = this.db
+      .prepare('SELECT MAX(indexed_at) AS last FROM files')
+      .get() as { last: number | null } | undefined;
+    return row?.last ?? null;
+  }
+
   /**
    * Get files that need re-indexing (hash changed)
    */
@@ -1304,10 +1667,19 @@ export class QueryBuilder {
   getUnresolvedReferencesByFiles(filePaths: string[]): UnresolvedReference[] {
     if (filePaths.length === 0) return [];
 
-    const placeholders = filePaths.map(() => '?').join(',');
-    const rows = this.db
-      .prepare(`SELECT * FROM unresolved_refs WHERE file_path IN (${placeholders})`)
-      .all(...filePaths) as UnresolvedRefRow[];
+    // Chunk under SQLite's parameter limit: the first sync of a very large repo
+    // passes every changed file here, which an unbounded `IN (...)` would bind
+    // as one parameter each — exceeding MAX_VARIABLE_NUMBER and aborting with
+    // "too many SQL variables". (#540)
+    const rows: UnresolvedRefRow[] = [];
+    for (let i = 0; i < filePaths.length; i += SQLITE_PARAM_CHUNK_SIZE) {
+      const chunk = filePaths.slice(i, i + SQLITE_PARAM_CHUNK_SIZE);
+      const placeholders = chunk.map(() => '?').join(',');
+      const chunkRows = this.db
+        .prepare(`SELECT * FROM unresolved_refs WHERE file_path IN (${placeholders})`)
+        .all(...chunk) as UnresolvedRefRow[];
+      rows.push(...chunkRows);
+    }
 
     return rows.map((row) => ({
       fromNodeId: row.from_node_id,
@@ -1358,6 +1730,19 @@ export class QueryBuilder {
   // Statistics
   // ===========================================================================
 
+  /**
+   * Lightweight (nodes, edges) count snapshot. Used around an index/sync
+   * run to compute true additions across extraction + resolution +
+   * synthesis — the per-phase counter in the orchestrator only sees
+   * extraction's contribution, which is why the CLI summary under-reported
+   * the edge count (resolution + synthesizer edges were invisible).
+   */
+  getNodeAndEdgeCount(): { nodes: number; edges: number } {
+    return this.db
+      .prepare('SELECT (SELECT COUNT(*) FROM nodes) AS nodes, (SELECT COUNT(*) FROM edges) AS edges')
+      .get() as { nodes: number; edges: number };
+  }
+
   /**
    * Get graph statistics
    */
diff --git a/src/db/schema.sql b/src/db/schema.sql
index b08c34f37..292981c82 100644
--- a/src/db/schema.sql
+++ b/src/db/schema.sql
@@ -37,6 +37,7 @@ CREATE TABLE IF NOT EXISTS nodes (
     is_abstract INTEGER DEFAULT 0,
     decorators TEXT, -- JSON array
     type_parameters TEXT, -- JSON array
+    return_type TEXT, -- normalized return/result type name (e.g. C++ method return, for receiver-type inference)
     updated_at INTEGER NOT NULL
 );
 
diff --git a/src/db/sqlite-adapter.ts b/src/db/sqlite-adapter.ts
index c3d31c8f6..ab0376c48 100644
--- a/src/db/sqlite-adapter.ts
+++ b/src/db/sqlite-adapter.ts
@@ -1,136 +1,59 @@
 /**
  * SQLite Adapter
  *
- * Provides a unified interface over better-sqlite3 (native) and
- * node-sqlite3-wasm (WASM fallback) for universal cross-platform support.
+ * Thin wrapper over Node's built-in `node:sqlite` (`DatabaseSync`), exposed
+ * through a small better-sqlite3-shaped interface so the rest of the codebase
+ * is storage-agnostic.
+ *
+ * CodeGraph ships with a bundled Node runtime, so `node:sqlite` (real SQLite,
+ * with WAL + FTS5) is always available — there is no native build step and no
+ * wasm fallback. When run from source instead, it requires Node >= 22.5.
  */
 
 export interface SqliteStatement {
   run(...params: any[]): { changes: number; lastInsertRowid: number | bigint };
   get(...params: any[]): any;
   all(...params: any[]): any[];
+  /**
+   * Lazily yield result rows one at a time instead of materializing the whole
+   * set with `all()`. Use for unbounded scans (e.g. every function/method node)
+   * so memory stays O(1) in the row count rather than O(rows) — see #610, where
+   * `all()`-ing every symbol on a dense project spiked the heap into an OOM.
+   */
+  iterate(...params: any[]): IterableIterator<any>;
 }
 
 export interface SqliteDatabase {
   prepare(sql: string): SqliteStatement;
   exec(sql: string): void;
-  pragma(str: string): any;
+  pragma(str: string, options?: { simple?: boolean }): any;
   transaction<T>(fn: (...args: any[]) => T): (...args: any[]) => T;
   close(): void;
   readonly open: boolean;
 }
 
-export type SqliteBackend = 'native' | 'wasm';
-
-/**
- * One-line summary of the recovery steps shown when WASM fallback is
- * active. Single source of truth so the recipe can't drift between the
- * stderr banner and the MCP status formatter.
- */
-export const WASM_FALLBACK_FIX_RECIPE =
-  '`xcode-select --install` (macOS) or `apt install build-essential` (Debian/Ubuntu), ' +
-  'then `npm rebuild better-sqlite3`, or `npm install better-sqlite3 --save` to force-include it.';
-
 /**
- * Multi-line banner shown to stderr when `createDatabase` falls back to
- * WASM. Replaces a one-line `console.warn` that MCP transports (which
- * take stdout for the protocol) typically swallow, leaving users on a
- * 5-10x slower backend with no signal.
- *
- * Exported for unit testing — pinning the recipe content prevents
- * future edits from silently stripping the recovery commands.
+ * The active SQLite backend. Only one now (`node:sqlite`); kept as a named type
+ * so `codegraph status` and the per-instance reporting have a stable shape.
  */
-export function buildWasmFallbackBanner(nativeError?: string): string {
-  const sep = '─'.repeat(72);
-  const lines = [
-    sep,
-    '[CodeGraph] WASM SQLite fallback active (better-sqlite3 unavailable)',
-    sep,
-    'Indexing and sync will be 5-10x slower than the native backend.',
-    '',
-    'Fix on macOS:',
-    '  xcode-select --install        # install C build tools',
-    '  npm rebuild better-sqlite3    # rebuild native binding for current Node',
-    '',
-    'Fix on Linux:',
-    '  sudo apt install build-essential python3 make    # Debian/Ubuntu',
-    '  # or: sudo yum groupinstall "Development Tools"  # RHEL/Fedora',
-    '  npm rebuild better-sqlite3',
-    '',
-    'Or force-include as a hard dependency on any platform:',
-    '  npm install better-sqlite3 --save',
-    '',
-    'Verify after fix: `codegraph status` should show `Backend: native`.',
-  ];
-  if (nativeError) {
-    lines.push('', `Native load error: ${nativeError}`);
-  }
-  lines.push(sep);
-  return lines.join('\n');
-}
-
-/**
- * Translate @named parameters (better-sqlite3 style) to positional ? params
- * for node-sqlite3-wasm, which only supports positional binding.
- *
- * Returns the rewritten SQL and an ordered list of parameter names.
- * If no named params are found, returns null for paramOrder (positional mode).
- */
-function translateNamedParams(sql: string): { sql: string; paramOrder: string[] | null } {
-  const paramOrder: string[] = [];
-  const rewritten = sql.replace(/@(\w+)/g, (_match, name: string) => {
-    paramOrder.push(name);
-    return '?';
-  });
-  if (paramOrder.length === 0) {
-    return { sql, paramOrder: null };
-  }
-  return { sql: rewritten, paramOrder };
-}
-
-/**
- * Convert better-sqlite3-style params to a positional array for node-sqlite3-wasm.
- *
- * Handles three calling conventions:
- * - Named object: run({ id: '1', name: 'a' }) → positional array via paramOrder
- * - Positional args: run('a', 'b') → ['a', 'b']
- * - No args: run() → undefined
- */
-function resolveParams(params: any[], paramOrder: string[] | null): any {
-  if (params.length === 0) return undefined;
-
-  // If paramOrder exists and first arg is a plain object, do named→positional translation
-  if (paramOrder && params.length === 1 && params[0] !== null && typeof params[0] === 'object' && !Array.isArray(params[0]) && !(params[0] instanceof Buffer) && !(params[0] instanceof Uint8Array)) {
-    const obj = params[0];
-    return paramOrder.map(name => obj[name]);
-  }
-
-  // Positional: single value or already an array
-  if (params.length === 1) return params[0];
-  return params;
-}
+export type SqliteBackend = 'node-sqlite';
 
 /**
- * Wraps node-sqlite3-wasm to match the better-sqlite3 interface.
+ * Wraps Node's built-in `node:sqlite` (`DatabaseSync`) to match the
+ * better-sqlite3 interface the rest of the code expects.
  *
- * Key differences handled:
- * - better-sqlite3 uses @named params; node-sqlite3-wasm uses positional ? only
- * - better-sqlite3 uses variadic args: stmt.run(a, b, c)
- * - node-sqlite3-wasm uses a single array/object: stmt.run([a, b, c])
- * - node-sqlite3-wasm has `isOpen` instead of `open`
- * - node-sqlite3-wasm doesn't have a `pragma()` method
- * - node-sqlite3-wasm doesn't have a `transaction()` method
+ * node:sqlite is real SQLite compiled into Node, so it supports WAL, FTS5,
+ * mmap, and `@named` params natively — the only shims needed are the
+ * better-sqlite3 conveniences node:sqlite omits: a `.pragma()` helper, a
+ * `.transaction()` helper, and `open` (node:sqlite exposes `isOpen`).
  */
-class WasmDatabaseAdapter implements SqliteDatabase {
+class NodeSqliteAdapter implements SqliteDatabase {
   private _db: any;
-  // Track raw WASM statements so we can finalize them on close.
-  // node-sqlite3-wasm won't release its file lock if statements are left open.
-  private _openStmts = new Set<any>();
 
   constructor(dbPath: string) {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const { Database } = require('node-sqlite3-wasm');
-    this._db = new Database(dbPath);
+    const { DatabaseSync } = require('node:sqlite');
+    this._db = new DatabaseSync(dbPath);
   }
 
   get open(): boolean {
@@ -138,25 +61,26 @@ class WasmDatabaseAdapter implements SqliteDatabase {
   }
 
   prepare(sql: string): SqliteStatement {
-    const { sql: rewrittenSql, paramOrder } = translateNamedParams(sql);
-    const stmt = this._db.prepare(rewrittenSql);
-    this._openStmts.add(stmt);
+    // node:sqlite matches better-sqlite3's calling convention (variadic
+    // positional args, or a single object for @named params), so params forward
+    // through unchanged.
+    const stmt = this._db.prepare(sql);
     return {
       run(...params: any[]) {
-        const resolved = resolveParams(params, paramOrder);
-        const result = resolved !== undefined ? stmt.run(resolved) : stmt.run();
+        const r = stmt.run(...params);
         return {
-          changes: result?.changes ?? 0,
-          lastInsertRowid: result?.lastInsertRowid ?? 0,
+          changes: Number(r?.changes ?? 0),
+          lastInsertRowid: r?.lastInsertRowid ?? 0,
         };
       },
       get(...params: any[]) {
-        const resolved = resolveParams(params, paramOrder);
-        return resolved !== undefined ? stmt.get(resolved) : stmt.get();
+        return stmt.get(...params);
       },
       all(...params: any[]) {
-        const resolved = resolveParams(params, paramOrder);
-        return resolved !== undefined ? stmt.all(resolved) : stmt.all();
+        return stmt.all(...params);
+      },
+      iterate(...params: any[]) {
+        return stmt.iterate(...params);
       },
     };
   }
@@ -165,41 +89,21 @@ class WasmDatabaseAdapter implements SqliteDatabase {
     this._db.exec(sql);
   }
 
-  pragma(str: string): any {
+  pragma(str: string, options?: { simple?: boolean }): any {
     const trimmed = str.trim();
-
-    // Write pragma: "key = value"
+    // Write pragma ("key = value"): node:sqlite is real SQLite, so every pragma
+    // (WAL, mmap, synchronous, …) applies as-is.
     if (trimmed.includes('=')) {
-      const eqIdx = trimmed.indexOf('=');
-      const key = trimmed.substring(0, eqIdx).trim();
-      const value = trimmed.substring(eqIdx + 1).trim();
-
-      // WAL is not supported in WASM SQLite — use DELETE journal mode
-      if (key === 'journal_mode' && value.toUpperCase() === 'WAL') {
-        this._db.exec('PRAGMA journal_mode = DELETE');
-        return;
-      }
-
-      // mmap is not available in WASM — silently skip
-      if (key === 'mmap_size') {
-        return;
-      }
-
-      // synchronous = NORMAL is unsafe without WAL — use FULL
-      if (key === 'synchronous' && value.toUpperCase() === 'NORMAL') {
-        this._db.exec('PRAGMA synchronous = FULL');
-        return;
-      }
-
-      this._db.exec(`PRAGMA ${key} = ${value}`);
+      this._db.exec(`PRAGMA ${trimmed}`);
       return;
     }
-
-    // Read pragma: "key" — return the value
-    const stmt = this._db.prepare(`PRAGMA ${trimmed}`);
-    const result = stmt.get();
-    stmt.finalize();
-    return result;
+    // Read pragma. Default: the row object (e.g. { journal_mode: 'wal' }).
+    // `{ simple: true }` returns just the single column value, like better-sqlite3.
+    const row = this._db.prepare(`PRAGMA ${trimmed}`).get();
+    if (options?.simple) {
+      return row && typeof row === 'object' ? Object.values(row)[0] : row;
+    }
+    return row;
   }
 
   transaction<T>(fn: (...args: any[]) => T): (...args: any[]) => T {
@@ -217,51 +121,29 @@ class WasmDatabaseAdapter implements SqliteDatabase {
   }
 
   close(): void {
-    // Finalize all tracked statements before closing.
-    // node-sqlite3-wasm won't release its directory-based file lock
-    // if any prepared statements remain open.
-    for (const stmt of this._openStmts) {
-      try { stmt.finalize(); } catch { /* already finalized */ }
-    }
-    this._openStmts.clear();
-    this._db.close();
+    // node:sqlite's DatabaseSync.close() throws if already closed; make it
+    // idempotent to match better-sqlite3 (callers may close more than once).
+    if (this._db.isOpen) this._db.close();
   }
 }
 
 /**
- * Create a database connection. Tries native better-sqlite3 first,
- * falls back to node-sqlite3-wasm. Returns the active backend
- * alongside the db so each `DatabaseConnection` can report its own
- * backend per-instance — MCP can open multiple project DBs in one
- * process (`tools.ts` getCodeGraph cache), so a process-global would
- * race / overwrite.
+ * Create a database connection backed by `node:sqlite`.
+ *
+ * Returns the active backend alongside the db so each `DatabaseConnection` can
+ * report it per-instance — MCP can open multiple project DBs in one process, so
+ * a process-global would race.
  */
 export function createDatabase(dbPath: string): { db: SqliteDatabase; backend: SqliteBackend } {
-  let nativeError: string | undefined;
-  let wasmError: string | undefined;
-
-  // Try native better-sqlite3 first
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const Database = require('better-sqlite3');
-    const db = new Database(dbPath);
-    return { db: db as SqliteDatabase, backend: 'native' };
-  } catch (error) {
-    nativeError = error instanceof Error ? error.message : String(error);
-  }
-
-  // Fall back to WASM
   try {
-    const db = new WasmDatabaseAdapter(dbPath);
-    console.warn(buildWasmFallbackBanner(nativeError));
-    return { db, backend: 'wasm' };
+    return { db: new NodeSqliteAdapter(dbPath), backend: 'node-sqlite' };
   } catch (error) {
-    wasmError = error instanceof Error ? error.message : String(error);
+    const msg = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      'Failed to open SQLite via the built-in node:sqlite module.\n' +
+      'CodeGraph requires node:sqlite (Node.js 22.5+). Install the self-contained\n' +
+      'CodeGraph release (it bundles a compatible Node), or run on Node 22.5+.\n' +
+      `Underlying error: ${msg}`
+    );
   }
-
-  throw new Error(
-    `Failed to load any SQLite backend.\n` +
-    `  Native (better-sqlite3): ${nativeError}\n` +
-    `  WASM (node-sqlite3-wasm): ${wasmError}`
-  );
 }
diff --git a/src/directory.ts b/src/directory.ts
index 588911c14..1c7729a42 100644
--- a/src/directory.ts
+++ b/src/directory.ts
@@ -7,16 +7,82 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
+/** The default per-project data directory name. */
+const DEFAULT_CODEGRAPH_DIR = '.codegraph';
+
+let warnedBadDirName = false;
+
+/**
+ * Resolve the per-project data directory name, honoring the `CODEGRAPH_DIR`
+ * environment override (default `.codegraph`). The override is a single path
+ * segment that lives in the project root.
+ *
+ * Why this exists: two environments that share one working tree must NOT share
+ * one `.codegraph/` — most concretely Windows-native and WSL (issue #636). The
+ * daemon lockfile (`.codegraph/daemon.pid`) records a platform-specific pid and
+ * socket path (a Windows named pipe vs a WSL Unix socket), and SQLite file
+ * locking across the WSL2 ↔ Windows filesystem boundary is unreliable, so two
+ * daemons sharing one index risks corruption. Setting `CODEGRAPH_DIR=.codegraph-win`
+ * on one side gives each environment its own index in the same tree.
+ *
+ * Read live (not captured at load) so it is both process-accurate and testable.
+ * An override that isn't a plain directory name — empty, containing a path
+ * separator, `.`, `..`/traversal, or absolute — is ignored (we keep the
+ * default) rather than risk writing the index outside the project or into the
+ * project root itself; we warn once to stderr so the misconfiguration is seen.
+ */
+export function codeGraphDirName(): string {
+  const raw = process.env.CODEGRAPH_DIR?.trim();
+  if (!raw) return DEFAULT_CODEGRAPH_DIR;
+  const invalid =
+    raw === '.' ||
+    raw.includes('..') ||
+    raw.includes('/') ||
+    raw.includes('\\') ||
+    path.isAbsolute(raw);
+  if (invalid) {
+    if (!warnedBadDirName) {
+      warnedBadDirName = true;
+      // stderr only — stdout is the MCP protocol channel.
+      console.warn(
+        `[codegraph] Ignoring invalid CODEGRAPH_DIR="${raw}" — it must be a plain ` +
+          `directory name (no path separators, no "..", not absolute). Using "${DEFAULT_CODEGRAPH_DIR}".`
+      );
+    }
+    return DEFAULT_CODEGRAPH_DIR;
+  }
+  return raw;
+}
+
 /**
- * CodeGraph directory name
+ * CodeGraph directory name — a load-time snapshot of {@link codeGraphDirName}.
+ * A running process's environment is fixed, so this equals the live value;
+ * it's kept as a stable string export for backward compatibility. Internal code
+ * resolves the name through {@link codeGraphDirName} / {@link getCodeGraphDir}
+ * so the `CODEGRAPH_DIR` override always applies.
  */
-export const CODEGRAPH_DIR = '.codegraph';
+export const CODEGRAPH_DIR = codeGraphDirName();
+
+/**
+ * Is `name` (a single path segment) a CodeGraph data directory? Matches the
+ * default `.codegraph`, the active `CODEGRAPH_DIR` override, and any
+ * `.codegraph-*` sibling. File-watching and the indexer skip ALL of these, so
+ * when two environments share one working tree (Windows + WSL, issue #636)
+ * neither indexes or watches the other's index directory.
+ */
+export function isCodeGraphDataDir(name: string): boolean {
+  return (
+    name === DEFAULT_CODEGRAPH_DIR ||
+    name === codeGraphDirName() ||
+    name.startsWith(DEFAULT_CODEGRAPH_DIR + '-')
+  );
+}
 
 /**
  * Get the .codegraph directory path for a project
  */
 export function getCodeGraphDir(projectRoot: string): string {
-  return path.join(projectRoot, CODEGRAPH_DIR);
+  return path.join(projectRoot, codeGraphDirName());
 }
 
 /**
@@ -63,6 +129,61 @@ export function findNearestCodeGraphRoot(startPath: string): string | null {
   return null;
 }
 
+/**
+ * Contents of `.codegraph/.gitignore`. A single wildcard ignore keeps every
+ * transient file in the index dir — the database, `daemon.pid`, the socket,
+ * logs, cache, and anything future versions add — out of git, without having
+ * to enumerate each name (issues #788, #492, #484). Older versions wrote an
+ * explicit allowlist that never listed `daemon.pid` or the socket, so those
+ * runtime files were silently committed.
+ */
+const GITIGNORE_CONTENT = `# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore
+`;
+
+/** Header line that prefixes every .gitignore CodeGraph has auto-generated. */
+const GITIGNORE_MARKER = '# CodeGraph data files';
+
+/**
+ * Is `content` a stale CodeGraph-generated `.gitignore` that should be
+ * regenerated in place? True when it carries our header but predates the
+ * wildcard ignore (it has no bare `*` line) — i.e. one of the old explicit
+ * allowlists (`*.db`, `cache/`, `.dirty`, …) that never ignored `daemon.pid`
+ * or the socket (issue #788). A file WITHOUT our header is user-authored and
+ * is left untouched; one that already has the wildcard is current. Matching
+ * on the header (not a byte-exact list of past defaults) heals every old
+ * variant — v0.7.x through 0.9.9 — and is idempotent once upgraded.
+ */
+function isStaleDefaultGitignore(content: string): boolean {
+  if (!content.trimStart().startsWith(GITIGNORE_MARKER)) return false;
+  return !content.split('\n').some((line) => line.trim() === '*');
+}
+
+/**
+ * Write `.codegraph/.gitignore` if it's absent, or upgrade a stale
+ * CodeGraph-generated default in place; a user-customized file is left alone.
+ * Best-effort — returns `false` only if a needed write failed.
+ */
+function ensureGitignore(gitignorePath: string): boolean {
+  let existing: string | null;
+  try {
+    existing = fs.readFileSync(gitignorePath, 'utf-8');
+  } catch {
+    existing = null; // absent (ENOENT) or unreadable — (re)create below
+  }
+  // Current default or a user-authored file: nothing to do.
+  if (existing !== null && !isStaleDefaultGitignore(existing)) return true;
+  try {
+    fs.writeFileSync(gitignorePath, GITIGNORE_CONTENT, 'utf-8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Create the .codegraph directory structure
  * Note: Only throws if codegraph.db already exists, not just if .codegraph/ exists.
@@ -80,29 +201,9 @@ export function createDirectory(projectRoot: string): void {
   // Create main directory (if it doesn't exist)
   fs.mkdirSync(codegraphDir, { recursive: true });
 
-  // Create .gitignore inside .codegraph (if it doesn't exist)
-  const gitignorePath = path.join(codegraphDir, '.gitignore');
-  if (!fs.existsSync(gitignorePath)) {
-    const gitignoreContent = `# CodeGraph data files
-# These are local to each machine and should not be committed
-
-# Database
-*.db
-*.db-wal
-*.db-shm
-
-# Cache
-cache/
-
-# Logs
-*.log
-
-# Hook markers
-.dirty
-`;
-
-    fs.writeFileSync(gitignorePath, gitignoreContent, 'utf-8');
-  }
+  // Write .gitignore inside .codegraph (create if absent, upgrade a stale
+  // pre-wildcard default left by an older version — issue #788).
+  ensureGitignore(path.join(codegraphDir, '.gitignore'));
 }
 
 /**
@@ -241,16 +342,15 @@ export function validateDirectory(projectRoot: string): {
     return { valid: false, errors };
   }
 
-  // Auto-repair missing .gitignore (non-critical file)
+  // Auto-repair / upgrade .gitignore (non-critical file). A missing one is
+  // recreated; a stale pre-wildcard default that never ignored daemon.pid is
+  // regenerated in place (issue #788); a user-authored file is left alone.
   const gitignorePath = path.join(codegraphDir, '.gitignore');
-  if (!fs.existsSync(gitignorePath)) {
-    try {
-      const gitignoreContent = `# CodeGraph data files\n# These are local to each machine and should not be committed\n\n# Database\n*.db\n*.db-wal\n*.db-shm\n\n# Cache\ncache/\n\n# Logs\n*.log\n\n# Hook markers\n.dirty\n`;
-      fs.writeFileSync(gitignorePath, gitignoreContent, 'utf-8');
-    } catch {
-      // Non-fatal: warn but don't block
-      errors.push('.gitignore missing in .codegraph directory and could not be created');
-    }
+  const existedBefore = fs.existsSync(gitignorePath);
+  if (!ensureGitignore(gitignorePath) && !existedBefore) {
+    // Only a missing-and-uncreatable file is surfaced; a failed in-place
+    // upgrade of an existing file is non-fatal — the index still works.
+    errors.push('.gitignore missing in .codegraph directory and could not be created');
   }
 
   return {
diff --git a/src/extraction/astro-extractor.ts b/src/extraction/astro-extractor.ts
new file mode 100644
index 000000000..e38989375
--- /dev/null
+++ b/src/extraction/astro-extractor.ts
@@ -0,0 +1,365 @@
+import { Node, Edge, ExtractionResult, ExtractionError, UnresolvedReference } from '../types';
+import { generateNodeId } from './tree-sitter-helpers';
+import { TreeSitterExtractor } from './tree-sitter';
+import { isLanguageSupported } from './grammars';
+
+/**
+ * Astro built-in components — compiler-provided (`<Fragment>`) or shipped by
+ * `astro:components` (`<Code>`, `<Debug>`), not user code.
+ */
+const ASTRO_BUILTIN_COMPONENTS = new Set(['Fragment', 'Code', 'Debug']);
+
+/**
+ * AstroExtractor - Extracts code relationships from Astro component files
+ *
+ * Astro files are multi-language: a TypeScript frontmatter block fenced by
+ * `---` lines, a JSX-like HTML template, and optional <script>/<style> blocks.
+ * Rather than parsing a full Astro grammar, we extract the frontmatter and
+ * <script> contents and delegate them to the TypeScript TreeSitterExtractor
+ * (Astro processes both as TypeScript by default — no `lang` attr needed).
+ *
+ * Also extracts function calls from template expressions (`{fn(...)}`) and
+ * component usages (`<PascalCase>`) so cross-file edges are captured even
+ * when the only reference lives in markup.
+ *
+ * Every .astro file produces a component node (Astro components are always
+ * importable).
+ */
+export class AstroExtractor {
+  private filePath: string;
+  private source: string;
+  private nodes: Node[] = [];
+  private edges: Edge[] = [];
+  private unresolvedReferences: UnresolvedReference[] = [];
+  private errors: ExtractionError[] = [];
+
+  constructor(filePath: string, source: string) {
+    this.filePath = filePath;
+    this.source = source;
+  }
+
+  /**
+   * Extract from Astro source
+   */
+  extract(): ExtractionResult {
+    const startTime = Date.now();
+
+    try {
+      // Create component node for the .astro file itself
+      const componentNode = this.createComponentNode();
+
+      // Extract and process the frontmatter block (--- fenced, TypeScript)
+      const frontmatter = this.extractFrontmatter();
+      if (frontmatter) {
+        this.processScriptContent(frontmatter, componentNode.id, 'frontmatter');
+      }
+
+      // Extract and process <script> blocks (client-side, TypeScript-capable)
+      for (const block of this.extractScriptBlocks()) {
+        this.processScriptContent(block, componentNode.id, 'script');
+      }
+
+      // Ranges the template scans must skip: frontmatter + <script>/<style>
+      const coveredRanges = this.getCoveredRanges(frontmatter);
+
+      // Extract function calls from template expressions ({fn(...)})
+      this.extractTemplateCalls(componentNode.id, coveredRanges);
+
+      // Extract component usages from template (<ComponentName>)
+      this.extractTemplateComponents(componentNode.id, coveredRanges);
+    } catch (error) {
+      this.errors.push({
+        message: `Astro extraction error: ${error instanceof Error ? error.message : String(error)}`,
+        severity: 'error',
+        code: 'parse_error',
+      });
+    }
+
+    return {
+      nodes: this.nodes,
+      edges: this.edges,
+      unresolvedReferences: this.unresolvedReferences,
+      errors: this.errors,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  /**
+   * Create a component node for the .astro file
+   */
+  private createComponentNode(): Node {
+    const lines = this.source.split('\n');
+    const fileName = this.filePath.split(/[/\\]/).pop() || this.filePath;
+    const componentName = fileName.replace(/\.astro$/, '');
+    const id = generateNodeId(this.filePath, 'component', componentName, 1);
+
+    const node: Node = {
+      id,
+      kind: 'component',
+      name: componentName,
+      qualifiedName: `${this.filePath}::${componentName}`,
+      filePath: this.filePath,
+      language: 'astro',
+      startLine: 1,
+      endLine: lines.length,
+      startColumn: 0,
+      endColumn: lines[lines.length - 1]?.length || 0,
+      isExported: true, // Astro components are always importable
+      updatedAt: Date.now(),
+    };
+
+    this.nodes.push(node);
+    return node;
+  }
+
+  /**
+   * Extract the frontmatter block: the content between the opening `---`
+   * fence (first non-blank line of the file) and the closing `---` fence.
+   * An unclosed fence is treated as "no frontmatter" rather than swallowing
+   * the whole template as TypeScript.
+   *
+   * Returns the content plus its 0-indexed start line, or null.
+   */
+  private extractFrontmatter(): { content: string; startLine: number; endLine: number } | null {
+    const lines = this.source.split('\n');
+
+    // Opening fence must be the first non-blank line
+    let openIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+      const trimmed = lines[i]!.trim();
+      if (trimmed === '') continue;
+      if (trimmed === '---') openIdx = i;
+      break;
+    }
+    if (openIdx === -1) return null;
+
+    // Closing fence
+    let closeIdx = -1;
+    for (let i = openIdx + 1; i < lines.length; i++) {
+      if (lines[i]!.trim() === '---') {
+        closeIdx = i;
+        break;
+      }
+    }
+    if (closeIdx === -1) return null;
+
+    return {
+      content: lines.slice(openIdx + 1, closeIdx).join('\n'),
+      startLine: openIdx + 1, // 0-indexed line where content starts
+      endLine: closeIdx, // 0-indexed line of the closing fence
+    };
+  }
+
+  /**
+   * Extract <script> blocks from the template portion
+   */
+  private extractScriptBlocks(): Array<{ content: string; startLine: number }> {
+    const blocks: Array<{ content: string; startLine: number }> = [];
+
+    const scriptRegex = /<script(\s[^>]*)?>(?<content>[\s\S]*?)<\/script>/g;
+    let match;
+
+    while ((match = scriptRegex.exec(this.source)) !== null) {
+      const content = match.groups?.content || match[2] || '';
+
+      // Calculate the 0-indexed line where the content begins. The content
+      // starts right after the opening tag's `>` — its leading `\n` is part
+      // of the content, so relative line 1 sits ON the tag's closing line
+      // (do not add 1 here; that double-counts the embedded newline).
+      const beforeScript = this.source.substring(0, match.index);
+      const scriptTagLine = (beforeScript.match(/\n/g) || []).length;
+      const openingTag = match[0].substring(0, match[0].indexOf('>') + 1);
+      const openingTagLines = (openingTag.match(/\n/g) || []).length;
+      const contentStartLine = scriptTagLine + openingTagLines; // 0-indexed
+
+      blocks.push({ content, startLine: contentStartLine });
+    }
+
+    return blocks;
+  }
+
+  /**
+   * Process frontmatter / script content by delegating to TreeSitterExtractor.
+   * Astro treats both as TypeScript by default.
+   */
+  private processScriptContent(
+    block: { content: string; startLine: number },
+    componentNodeId: string,
+    label: 'frontmatter' | 'script'
+  ): void {
+    if (!isLanguageSupported('typescript')) {
+      this.errors.push({
+        message: `Parser for typescript not available, cannot parse Astro ${label} block`,
+        severity: 'warning',
+      });
+      return;
+    }
+
+    // Delegate to TreeSitterExtractor
+    const extractor = new TreeSitterExtractor(this.filePath, block.content, 'typescript');
+    const result = extractor.extract();
+
+    // Offset line numbers from the block back to .astro file positions
+    for (const node of result.nodes) {
+      node.startLine += block.startLine;
+      node.endLine += block.startLine;
+      node.language = 'astro'; // Mark as astro, not TS
+
+      this.nodes.push(node);
+
+      // Add containment edge from component to this node
+      this.edges.push({
+        source: componentNodeId,
+        target: node.id,
+        kind: 'contains',
+      });
+    }
+
+    // Offset edges (they reference line numbers)
+    for (const edge of result.edges) {
+      if (edge.line) {
+        edge.line += block.startLine;
+      }
+      this.edges.push(edge);
+    }
+
+    // Offset unresolved references
+    for (const ref of result.unresolvedReferences) {
+      ref.line += block.startLine;
+      ref.filePath = this.filePath;
+      ref.language = 'astro';
+      this.unresolvedReferences.push(ref);
+    }
+
+    // Carry over errors
+    for (const error of result.errors) {
+      if (error.line) {
+        error.line += block.startLine;
+      }
+      this.errors.push(error);
+    }
+  }
+
+  /**
+   * Line ranges (0-indexed, inclusive) the template scans must skip:
+   * the frontmatter block and <script>/<style> blocks.
+   */
+  private getCoveredRanges(
+    frontmatter: { startLine: number; endLine: number } | null
+  ): Array<[number, number]> {
+    const coveredRanges: Array<[number, number]> = [];
+
+    if (frontmatter) {
+      // Cover from the opening fence line through the closing fence line
+      coveredRanges.push([frontmatter.startLine - 1, frontmatter.endLine]);
+    }
+
+    const tagRegex = /<(script|style)(\s[^>]*)?>[\s\S]*?<\/\1>/g;
+    let tagMatch;
+    while ((tagMatch = tagRegex.exec(this.source)) !== null) {
+      const startLine = (this.source.substring(0, tagMatch.index).match(/\n/g) || []).length;
+      const endLine = startLine + (tagMatch[0].match(/\n/g) || []).length;
+      coveredRanges.push([startLine, endLine]);
+    }
+
+    return coveredRanges;
+  }
+
+  /**
+   * Extract function calls from Astro template expressions.
+   *
+   * Astro templates embed JSX-like expressions (`{formatDate(post.date)}`,
+   * `class:list={cn(...)}`), so calls frequently live in markup rather than
+   * the frontmatter. We scan template lines for `{expression}` groups and
+   * extract call patterns from them. A `{` group left open at end-of-line
+   * (the pervasive `{posts.map((post) => (` pattern) contributes the calls
+   * on its opening line.
+   */
+  private extractTemplateCalls(
+    componentNodeId: string,
+    coveredRanges: Array<[number, number]>
+  ): void {
+    const lines = this.source.split('\n');
+    // Complete groups: {...} — excluding JSX comments ({/* ... */})
+    const exprRegex = /\{([^}/][^}]*)\}/g;
+    // A group opened but not closed on this line
+    const openExprRegex = /\{([^}/][^}]*)$/;
+
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+      if (coveredRanges.some(([start, end]) => lineIdx >= start && lineIdx <= end)) continue;
+
+      const line = lines[lineIdx]!;
+      const exprs: Array<{ text: string; offset: number }> = [];
+
+      let exprMatch;
+      while ((exprMatch = exprRegex.exec(line)) !== null) {
+        exprs.push({ text: exprMatch[1]!, offset: exprMatch.index });
+      }
+      const openMatch = openExprRegex.exec(line.replace(exprRegex, ''));
+      if (openMatch) {
+        exprs.push({ text: openMatch[1]!, offset: line.lastIndexOf('{') });
+      }
+
+      for (const expr of exprs) {
+        // Extract function calls: identifiers followed by (
+        // Matches: cn(...), formatDate(...), obj.method(...)
+        const callRegex = /\b([a-zA-Z_$][\w$.]*)\s*\(/g;
+        let callMatch;
+        while ((callMatch = callRegex.exec(expr.text)) !== null) {
+          const calleeName = callMatch[1]!;
+          // Skip control-flow keywords valid inside expressions
+          if (calleeName === 'if' || calleeName === 'await' || calleeName === 'function') continue;
+
+          this.unresolvedReferences.push({
+            fromNodeId: componentNodeId,
+            referenceName: calleeName,
+            referenceKind: 'calls',
+            line: lineIdx + 1, // 1-indexed
+            column: expr.offset + callMatch.index,
+            filePath: this.filePath,
+            language: 'astro',
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Extract component usages from the Astro template.
+   *
+   * PascalCase tags like <Layout>, <PostCard /> represent component
+   * instantiations — analogous to function calls in imperative code.
+   * Lowercase tags are native HTML (Astro does not register kebab-case
+   * components the way Vue does, so those are real custom elements and
+   * are skipped).
+   */
+  private extractTemplateComponents(
+    componentNodeId: string,
+    coveredRanges: Array<[number, number]>
+  ): void {
+    const lines = this.source.split('\n');
+    // Opening/self-closing tags (closing tags </Foo> start with </ so won't match)
+    const componentTagRegex = /<([A-Z][a-zA-Z0-9_$]*)\b/g;
+
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+      if (coveredRanges.some(([start, end]) => lineIdx >= start && lineIdx <= end)) continue;
+
+      const line = lines[lineIdx]!;
+      let match;
+      while ((match = componentTagRegex.exec(line)) !== null) {
+        const componentName = match[1]!;
+        if (ASTRO_BUILTIN_COMPONENTS.has(componentName)) continue;
+
+        this.unresolvedReferences.push({
+          fromNodeId: componentNodeId,
+          referenceName: componentName,
+          referenceKind: 'references',
+          line: lineIdx + 1, // 1-indexed
+          column: match.index + 1,
+          filePath: this.filePath,
+          language: 'astro',
+        });
+      }
+    }
+  }
+}
diff --git a/src/extraction/extraction-version.ts b/src/extraction/extraction-version.ts
new file mode 100644
index 000000000..618a1b1c3
--- /dev/null
+++ b/src/extraction/extraction-version.ts
@@ -0,0 +1,24 @@
+/**
+ * Extraction version
+ *
+ * A monotonically-increasing integer that identifies the *shape and depth* of
+ * what the extractor writes into the graph. Unlike `CURRENT_SCHEMA_VERSION`
+ * (which tracks the SQLite table layout and is migrated in place), this tracks
+ * the EXTRACTED CONTENT — node kinds, edges, synthesizers, resolver coverage.
+ *
+ * When an index was built by an older engine whose `EXTRACTION_VERSION` is
+ * below the running engine's, the data on disk is structurally fine but
+ * *stale*: it's missing whatever a newer extractor would now produce. A schema
+ * migration can't backfill that — only a re-index can. So this is the signal
+ * `codegraph status` uses to recommend a re-index, and the reason `codegraph
+ * upgrade` reminds users to refresh their projects.
+ *
+ * BUMP THIS when a release changes extraction output enough that existing
+ * indexes should be rebuilt to benefit — e.g. a new language/framework
+ * extractor, a new dynamic-dispatch synthesizer, a new node/edge kind, or a
+ * resolver fix that materially changes which edges exist. Do NOT bump for
+ * pure bug fixes, CLI/UX changes, or schema-only migrations. Over-bumping
+ * turns the re-index hint into noise — keep it honest (see CLAUDE.md, "Honesty
+ * in the product is load-bearing").
+ */
+export const EXTRACTION_VERSION = 24;
diff --git a/src/extraction/function-ref.ts b/src/extraction/function-ref.ts
new file mode 100644
index 000000000..1bae970a4
--- /dev/null
+++ b/src/extraction/function-ref.ts
@@ -0,0 +1,843 @@
+/**
+ * Function-as-value capture (#756) — registration-linking for callbacks.
+ *
+ * A function name used as a VALUE — passed as a call argument
+ * (`register_handler(target_cb)`, `signal(SIGINT, handler)`), assigned to a
+ * field or function pointer (`o->cb = target_cb`, `OnFire := TargetCb`),
+ * placed in a struct/object initializer (`{ .recv_cb = my_cb }`,
+ * `{ recv: targetCb }`, `Ops{Cb: targetCb}`), or listed in a function table
+ * (`static cb_t table[] = { cb_a, cb_b }`) — is a real dependency that static
+ * call extraction misses entirely: `callers(target_cb)` showed nothing but
+ * direct calls, so every callback looked dead and its registration sites were
+ * invisible to impact analysis.
+ *
+ * This module captures those value positions during the AST walk as
+ * `function_ref` candidates. Capture is table-driven per language (the value
+ * positions and wrapper forms differ per grammar — `&fn` in C, `Main::fn` in
+ * Java, `::fn` in Kotlin, `#selector(fn)` in Swift, `@TargetCb` in Pascal,
+ * `method(:fn)` in Ruby). Candidates are GATED at end-of-file extraction
+ * (see `TreeSitterExtractor.flushFnRefCandidates`): only names matching a
+ * same-file function/method or an imported binding survive, which bounds
+ * volume and keeps precision high. Resolution then matches survivors against
+ * function/method nodes ONLY (`matchFunctionRef` in
+ * `src/resolution/name-matcher.ts`) and persists them as `references` edges,
+ * which `callers`/`impact` already traverse.
+ *
+ * Deliberately NOT covered (resolving the *dispatch* — `o->cb(x)` → the
+ * registered function — needs data-flow through struct fields; a wrong edge
+ * is worse than none): indirect-call resolution and `obj.method` member
+ * values where `obj` isn't `this`/`self` (the receiver's type is statically
+ * unknowable without local data-flow).
+ */
+
+import type { Node as SyntaxNode } from 'web-tree-sitter';
+import { getNodeText, getChildByField } from './tree-sitter-helpers';
+
+export interface FnRefCandidate {
+  name: string;
+  line: number;
+  column: number;
+  /** Which capture position produced this candidate (gate policy keys on it). */
+  mode: CaptureMode;
+  /**
+   * True when the value was an explicit reference form (`&fn`, `&Cls::m`,
+   * `::fn`, `#selector`, `method(:sym)`) rather than a bare identifier —
+   * C++'s flush policy keys on it.
+   */
+  explicitRef: boolean;
+  /**
+   * Skip the same-file/import name gate for this candidate. Set for PHP
+   * string callables in known HOF positions: PHP global functions are
+   * referenced cross-file WITHOUT imports (global namespace), so the gate
+   * can't see them — the strong positional prior (a string argument to
+   * `usort`/`array_map`/…) plus resolution's unique-or-drop rule carry the
+   * precision instead.
+   */
+  skipGate?: boolean;
+}
+
+/** How to pull candidate value nodes out of a dispatched container node. */
+type CaptureMode =
+  | 'args' // every named child is a potential value (call argument lists)
+  | 'rhs' // the assignment right-hand side (named field, else last named child)
+  | 'value' // the `value` field of a keyed pair (object/struct/table initializers)
+  | 'list' // every named child (array / initializer-list / table positional elements)
+  | 'varinit'; // a variable declarator's initializer value
+
+interface CaptureRule {
+  mode: CaptureMode;
+  /** Field holding the value for rhs/value/varinit (defaults per mode). */
+  field?: string;
+}
+
+export interface FnRefSpec {
+  /** Bare identifier node types that can act as a function value. */
+  idTypes: Set<string>;
+  /** Container node type → how to extract candidate values from it. */
+  dispatch: Map<string, CaptureRule>;
+  /**
+   * Transparent wrapper layers between a container and its values
+   * (`argument`, `value_argument`, `literal_element`, `expression_list`…).
+   * Value: the field to descend into, or null for "named children".
+   * `expression_list` fans out to ALL named children (Go multi-assign).
+   */
+  layers?: Map<string, string | null>;
+  /**
+   * Unary wrappers whose operand is the function value — C/C++ `&fn`
+   * (pointer_expression), Pascal `@Fn` (exprUnary), Scala eta `fn _`
+   * (postfix_expression). Value: operand field, or null for first named child.
+   */
+  unwrap?: Map<string, string | null>;
+  /**
+   * Whole-node reference forms needing bespoke name extraction —
+   * `method_reference` (Java), `callable_reference` / `navigation_expression`
+   * (Kotlin), `selector_expression` (Swift `#selector` / ObjC `@selector`),
+   * Ruby `method(:sym)` calls, and `this.method` member forms.
+   */
+  special?: Set<string>;
+  /**
+   * Capture modes whose candidates skip the same-file/import gate and rely on
+   * resolution's unique-or-drop rule instead. C-family only: an initializer
+   * value, function-pointer assignment RHS, or table element is a
+   * function-pointer position by construction, and C has no symbol imports —
+   * the dominant repo-scale pattern (`server.c`'s command table naming
+   * handlers defined across files) would otherwise be invisible. Call
+   * arguments stay gated everywhere (locals passed as args dwarf callbacks).
+   */
+  ungatedModes?: Set<CaptureMode>;
+  /**
+   * C++ only: in args/rhs/varinit positions, accept ONLY explicit reference
+   * forms (`&fn`, `&Cls::method`) — never bare identifiers. C++ codebases are
+   * dense with generic free-function/accessor names (`begin`, `end`, `out`,
+   * `size`, `data`) that collide with parameters and locals, and out-of-line
+   * member definitions extract as function-kind nodes — bare-id matching on
+   * fmt was mostly wrong edges. File-scope initializer tables (value/list)
+   * still accept bare identifiers, same as C.
+   */
+  addressOfOnly?: boolean;
+}
+
+/** Names that are never function references even when grammars call them identifiers. */
+const NAME_STOPLIST = new Set([
+  'this',
+  'self',
+  'super',
+  'null',
+  'nil',
+  'true',
+  'false',
+  'undefined',
+  'new',
+  'NULL',
+  'nullptr',
+  'None',
+]);
+
+// ---------------------------------------------------------------------------
+// Per-language specs. Node types verified against each grammar (probe fixtures
+// in the #756 investigation; see docs/design/function-ref-capture.md).
+// ---------------------------------------------------------------------------
+
+/** C / C++ / Objective-C share the C-family initializer & assignment shapes. */
+function cFamilySpec(extra?: { special?: string[]; addressOfOnly?: boolean }): FnRefSpec {
+  return {
+    idTypes: new Set(['identifier']),
+    dispatch: new Map<string, CaptureRule>([
+      ['argument_list', { mode: 'args' }],
+      ['assignment_expression', { mode: 'rhs', field: 'right' }],
+      ['init_declarator', { mode: 'varinit', field: 'value' }],
+      ['initializer_list', { mode: 'list' }],
+      ['initializer_pair', { mode: 'value', field: 'value' }],
+    ]),
+    unwrap: new Map([['pointer_expression', 'argument']]),
+    special: new Set(extra?.special ?? []),
+    // C has no symbol imports, and callbacks are registered cross-file at repo
+    // scale (redis: server.c's command table names handlers from t_*.c) — so
+    // initializer positions bypass the gate and lean on resolution's
+    // unique-or-drop rule. ONLY 'value'/'list' (struct/array initializers),
+    // and the flush additionally requires FILE scope: a C file-scope
+    // initializer is a constant-expression context, so a bare identifier
+    // there can only be a function address (or enum/macro, which the
+    // function-kind filter drops) — never a variable. 'rhs'/'varinit' were
+    // tried and produced false edges (`prev = next`, `*str = field` — data
+    // assignments matching a unique same-named function elsewhere), so
+    // assignments stay gated to same-file/import.
+    ungatedModes: new Set<CaptureMode>(['value', 'list']),
+    addressOfOnly: extra?.addressOfOnly,
+  };
+}
+
+// `this.handleClick` capture (member_expression) emits a `this.`-PREFIXED
+// candidate name: resolution scopes it to the enclosing symbol's class
+// (qualified-name prefix), so `this.fonts` (a property, post-#808) and
+// inherited/unknown members yield no edge, while same-class methods —
+// `btn.on('click', this.handleClick)`, the observer-registration idiom —
+// resolve precisely. Bare identifiers stay function-kind-only (a bare id can
+// never be a method value in JS).
+const TS_JS_SPEC: FnRefSpec = {
+  idTypes: new Set(['identifier']),
+  dispatch: new Map<string, CaptureRule>([
+    ['arguments', { mode: 'args' }],
+    ['assignment_expression', { mode: 'rhs', field: 'right' }],
+    ['variable_declarator', { mode: 'varinit', field: 'value' }],
+    ['pair', { mode: 'value', field: 'value' }],
+    ['array', { mode: 'list' }],
+  ]),
+  special: new Set(['member_expression']),
+};
+
+const PYTHON_SPEC: FnRefSpec = {
+  idTypes: new Set(['identifier']),
+  dispatch: new Map<string, CaptureRule>([
+    ['argument_list', { mode: 'args' }],
+    ['assignment', { mode: 'rhs', field: 'right' }],
+    ['keyword_argument', { mode: 'value', field: 'value' }], // Thread(target=worker)
+    ['pair', { mode: 'value', field: 'value' }],
+    ['list', { mode: 'list' }],
+  ]),
+  special: new Set(['attribute']),
+};
+
+const GO_SPEC: FnRefSpec = {
+  idTypes: new Set(['identifier']),
+  dispatch: new Map<string, CaptureRule>([
+    ['argument_list', { mode: 'args' }],
+    ['assignment_statement', { mode: 'rhs', field: 'right' }],
+    ['short_var_declaration', { mode: 'rhs', field: 'right' }],
+    ['var_spec', { mode: 'varinit', field: 'value' }],
+    ['keyed_element', { mode: 'value' }], // value = last literal_element child
+    ['literal_value', { mode: 'list' }], // positional composite literals
+  ]),
+  layers: new Map<string, string | null>([
+    ['literal_element', null],
+    ['expression_list', null],
+  ]),
+};
+
+const RUST_SPEC: FnRefSpec = {
+  idTypes: new Set(['identifier']),
+  dispatch: new Map<string, CaptureRule>([
+    ['arguments', { mode: 'args' }],
+    ['assignment_expression', { mode: 'rhs', field: 'right' }],
+    ['field_initializer', { mode: 'value', field: 'value' }],
+    ['array_expression', { mode: 'list' }],
+    ['static_item', { mode: 'varinit', field: 'value' }],
+    ['let_declaration', { mode: 'varinit', field: 'value' }],
+  ]),
+};
+
+const JAVA_SPEC: FnRefSpec = {
+  // No bare-identifier function values in Java — only method references.
+  idTypes: new Set<string>(),
+  dispatch: new Map<string, CaptureRule>([
+    ['argument_list', { mode: 'args' }],
+    ['assignment_expression', { mode: 'rhs', field: 'right' }],
+    ['variable_declarator', { mode: 'varinit', field: 'value' }],
+  ]),
+  special: new Set(['method_reference']),
+};
+
+const KOTLIN_SPEC: FnRefSpec = {
+  idTypes: new Set<string>(),
+  dispatch: new Map<string, CaptureRule>([
+    ['value_arguments', { mode: 'args' }],
+    ['assignment', { mode: 'rhs' }], // RHS = last named child (no field in grammar)
+  ]),
+  layers: new Map<string, string | null>([['value_argument', null]]),
+  special: new Set(['callable_reference', 'navigation_expression']),
+};
+
+const CSHARP_SPEC: FnRefSpec = {
+  idTypes: new Set(['identifier']),
+  dispatch: new Map<string, CaptureRule>([
+    ['argument_list', { mode: 'args' }],
+    ['assignment_expression', { mode: 'rhs', field: 'right' }], // covers `+=` event subscription
+    ['initializer_expression', { mode: 'list' }],
+    ['variable_declarator', { mode: 'varinit' }],
+  ]),
+  layers: new Map<string, string | null>([['argument', null]]),
+  special: new Set(['member_access_expression']),
+};
+
+const RUBY_SPEC: FnRefSpec = {
+  // Bare identifiers in Ruby args are method CALLS or locals, never function
+  // values — only the `method(:name)` idiom (and `&method(:name)`) plus
+  // hook-DSL symbols (`before_action :authenticate`) qualify.
+  idTypes: new Set<string>(),
+  dispatch: new Map<string, CaptureRule>([
+    ['argument_list', { mode: 'args' }],
+    ['pair', { mode: 'value', field: 'value' }],
+  ]),
+  layers: new Map<string, string | null>([['block_argument', null]]),
+  special: new Set(['call', 'simple_symbol']),
+};
+
+/**
+ * Rails/ActiveSupport-style hook DSLs whose symbol arguments name a method of
+ * the enclosing class: lifecycle callbacks (`before_action`, `after_save`,
+ * `around_create`, `skip_before_action`…), `validate :method`, `set_callback`,
+ * `helper_method`, and `rescue_from(..., with: :handler)`. NOT `validates`
+ * (plural) — its symbols name ATTRIBUTES, not methods.
+ */
+const RUBY_HOOK_RE = /^(skip_)?(before|after|around)_[a-z_]+$/;
+const RUBY_HOOK_NAMES = new Set(['validate', 'set_callback', 'helper_method', 'rescue_from']);
+function isRubyHookCall(name: string): boolean {
+  return RUBY_HOOK_RE.test(name) || RUBY_HOOK_NAMES.has(name);
+}
+
+const SWIFT_SPEC: FnRefSpec = {
+  idTypes: new Set(['simple_identifier']),
+  dispatch: new Map<string, CaptureRule>([
+    ['value_arguments', { mode: 'args' }],
+    ['assignment', { mode: 'rhs', field: 'result' }],
+    ['array_literal', { mode: 'list' }],
+    ['property_declaration', { mode: 'varinit', field: 'value' }],
+  ]),
+  layers: new Map<string, string | null>([['value_argument', 'value']]),
+  special: new Set(['selector_expression']),
+};
+
+const SCALA_SPEC: FnRefSpec = {
+  idTypes: new Set(['identifier']),
+  dispatch: new Map<string, CaptureRule>([
+    ['arguments', { mode: 'args' }],
+    ['assignment_expression', { mode: 'rhs', field: 'right' }],
+    ['val_definition', { mode: 'varinit', field: 'value' }],
+  ]),
+  unwrap: new Map<string, string | null>([['postfix_expression', null]]), // eta-expansion `fn _`
+};
+
+const DART_SPEC: FnRefSpec = {
+  idTypes: new Set(['identifier']),
+  dispatch: new Map<string, CaptureRule>([
+    ['arguments', { mode: 'args' }],
+    ['assignment_expression', { mode: 'rhs', field: 'right' }],
+    ['pair', { mode: 'value', field: 'value' }],
+    ['list_literal', { mode: 'list' }],
+    ['static_final_declaration', { mode: 'varinit' }],
+  ]),
+  layers: new Map<string, string | null>([['argument', null]]),
+};
+
+const LUA_SPEC: FnRefSpec = {
+  idTypes: new Set(['identifier']),
+  dispatch: new Map<string, CaptureRule>([
+    ['arguments', { mode: 'args' }],
+    ['assignment_statement', { mode: 'rhs' }], // RHS expression_list children carry `value` fields
+    ['field', { mode: 'value', field: 'value' }], // table fields, keyed AND positional
+  ]),
+  layers: new Map<string, string | null>([['expression_list', null]]),
+};
+
+const PASCAL_SPEC: FnRefSpec = {
+  idTypes: new Set(['identifier']),
+  dispatch: new Map<string, CaptureRule>([
+    ['exprArgs', { mode: 'args' }],
+    ['assignment', { mode: 'rhs', field: 'rhs' }], // OnClick := Handler
+  ]),
+  unwrap: new Map<string, string | null>([['exprUnary', 'operand']]), // @Handler
+};
+
+/**
+ * PHP core functions whose string arguments are CALLABLES — the positional
+ * prior that makes a bare string trustworthy as a function reference.
+ * Deliberately core-PHP only; framework registries (WordPress `add_action`)
+ * belong in a frameworks/ resolver if ever added.
+ */
+const PHP_CALLABLE_HOFS = new Set([
+  'array_map', 'array_filter', 'array_walk', 'array_walk_recursive', 'array_reduce',
+  'usort', 'uasort', 'uksort',
+  'array_udiff', 'array_udiff_assoc', 'array_uintersect', 'array_uintersect_assoc',
+  'call_user_func', 'call_user_func_array',
+  'forward_static_call', 'forward_static_call_array',
+  'preg_replace_callback', 'preg_replace_callback_array',
+  'register_shutdown_function', 'register_tick_function',
+  'set_error_handler', 'set_exception_handler', 'spl_autoload_register',
+  'ob_start', 'iterator_apply', 'header_register_callback',
+  'is_callable',
+]);
+
+const PHP_SPEC: FnRefSpec = {
+  // PHP has no bare-identifier function values (the first-class callable
+  // `fn(...)` already extracts as a `calls` edge). What qualifies:
+  //  - a string argument to a known callable-taking core function
+  //    (`usort($a, 'cmp_items')`) — see PHP_CALLABLE_HOFS
+  //  - array callables: `[$this, 'method']` (class-scoped) and
+  //    `[Foo::class, 'method']` (qualified), in any call's arguments
+  idTypes: new Set<string>(),
+  dispatch: new Map<string, CaptureRule>([['arguments', { mode: 'args' }]]),
+  layers: new Map<string, string | null>([['argument', null]]),
+  special: new Set(['encapsed_string', 'string', 'array_creation_expression']),
+};
+
+/**
+ * Capture specs by language.
+ */
+export const FN_REF_SPECS: Record<string, FnRefSpec | undefined> = {
+  c: cFamilySpec(),
+  cpp: cFamilySpec({ addressOfOnly: true }),
+  objc: cFamilySpec({ special: ['selector_expression'] }),
+  typescript: TS_JS_SPEC,
+  tsx: TS_JS_SPEC,
+  javascript: TS_JS_SPEC,
+  jsx: TS_JS_SPEC,
+  python: PYTHON_SPEC,
+  go: GO_SPEC,
+  rust: RUST_SPEC,
+  java: JAVA_SPEC,
+  kotlin: KOTLIN_SPEC,
+  csharp: CSHARP_SPEC,
+  php: PHP_SPEC,
+  ruby: RUBY_SPEC,
+  swift: SWIFT_SPEC,
+  scala: SCALA_SPEC,
+  dart: DART_SPEC,
+  lua: LUA_SPEC,
+  luau: LUA_SPEC,
+  pascal: PASCAL_SPEC,
+};
+
+// ---------------------------------------------------------------------------
+// Capture
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract candidate names from a dispatched container node. Returns the
+ * (name, position) pairs of every function-value-shaped expression found.
+ */
+export function captureFnRefCandidates(
+  container: SyntaxNode,
+  rule: CaptureRule,
+  spec: FnRefSpec,
+  source: string
+): FnRefCandidate[] {
+  const valueNodes: SyntaxNode[] = [];
+
+  switch (rule.mode) {
+    case 'args':
+    case 'list': {
+      for (let i = 0; i < container.namedChildCount; i++) {
+        const child = container.namedChild(i);
+        if (child) valueNodes.push(child);
+      }
+      break;
+    }
+    case 'rhs': {
+      const rhs = rule.field
+        ? getChildByField(container, rule.field)
+        : container.namedChild(container.namedChildCount - 1);
+      if (rhs) {
+        // Param-storage skip: `this.status = status` / `o->cb = cb` — when
+        // the assigned member's name EQUALS the RHS identifier, the RHS is a
+        // local/parameter being stored, and the function it holds (if any)
+        // is unknowable statically. A same-named function elsewhere would
+        // resolve to the WRONG target (excalidraw A/B finding), so skip.
+        const lhs =
+          getChildByField(container, 'left') ??
+          getChildByField(container, 'lhs') ??
+          getChildByField(container, 'target') ??
+          (container.namedChildCount >= 2 ? container.namedChild(0) : null);
+        const lhsText = lhs ? getNodeText(lhs, source) : '';
+        const lhsLastName = lhsText.match(/([A-Za-z_$][A-Za-z0-9_$]*)\s*$/)?.[1];
+        const rhsText = getNodeText(rhs, source).trim();
+        if (lhsLastName && lhsLastName === rhsText) break;
+        valueNodes.push(rhs);
+      }
+      break;
+    }
+    case 'value': {
+      let value = rule.field ? getChildByField(container, rule.field) : null;
+      // Keyed containers without a value field (Go keyed_element): the value
+      // is the LAST named child (the first is the key).
+      if (!value && container.namedChildCount > 0) {
+        value = container.namedChild(container.namedChildCount - 1);
+      }
+      if (value) valueNodes.push(value);
+      break;
+    }
+    case 'varinit': {
+      // Destructuring (`const { center } = ellipse`) extracts DATA from the
+      // RHS — never a function alias. Without this skip, a parameter that
+      // shadows a same-named imported function produced a wrong edge.
+      const nameNode =
+        getChildByField(container, 'name') ?? getChildByField(container, 'pattern');
+      if (nameNode && (nameNode.type === 'object_pattern' || nameNode.type === 'array_pattern' ||
+                       nameNode.type === 'tuple_pattern' || nameNode.type === 'struct_pattern')) {
+        break;
+      }
+      if (rule.field) {
+        const value = getChildByField(container, rule.field);
+        if (value) valueNodes.push(value);
+      } else {
+        // No value field in this grammar (C# variable_declarator, Dart
+        // static_final_declaration): the initializer is the last named child —
+        // but a declarator WITHOUT an initializer has its NAME there instead.
+        // Require ≥2 named children and never pick the name/pattern child.
+        const value = container.namedChild(container.namedChildCount - 1);
+        const nameChild =
+          getChildByField(container, 'name') ?? getChildByField(container, 'pattern');
+        if (
+          value &&
+          container.namedChildCount >= 2 &&
+          (!nameChild || value.id !== nameChild.id)
+        ) {
+          valueNodes.push(value);
+        }
+      }
+      break;
+    }
+  }
+
+  const out: FnRefCandidate[] = [];
+  for (const v of valueNodes) {
+    // A bare identifier is one that normalizes without passing through an
+    // unwrap/special reference form. C++'s addressOfOnly policy (applied at
+    // flush, where file scope is known) drops bare ids outside file-scope
+    // initializer tables.
+    const explicitRef = !spec.idTypes.has(v.type);
+    for (const { name, node, skipGate } of normalizeValue(v, spec, source, 0)) {
+      if (!name || NAME_STOPLIST.has(name)) continue;
+      out.push({
+        name,
+        line: node.startPosition.row + 1,
+        column: node.startPosition.column,
+        mode: rule.mode,
+        explicitRef,
+        skipGate,
+      });
+    }
+  }
+  return out;
+}
+
+/** One normalized function-value: its name, source node, and gate policy. */
+interface NormalizedRef {
+  name: string;
+  node: SyntaxNode;
+  skipGate?: boolean;
+}
+
+/**
+ * Normalize one value expression to zero or more function names. Recursion is
+ * bounded (wrapper layers only); anything that isn't a recognized
+ * function-value shape yields [].
+ */
+function normalizeValue(
+  node: SyntaxNode,
+  spec: FnRefSpec,
+  source: string,
+  depth: number
+): NormalizedRef[] {
+  if (depth > 4) return [];
+  const type = node.type;
+
+  // Bare identifier
+  if (spec.idTypes.has(type)) {
+    return [{ name: getNodeText(node, source), node }];
+  }
+
+  // Transparent layers (argument, value_argument, literal_element,
+  // expression_list, block_argument). expression_list fans out (Go `a, b = f, g`).
+  const layerField = spec.layers?.get(type);
+  if (spec.layers?.has(type)) {
+    // Labeled-argument param-forward skip (Swift/Kotlin): `value: value` /
+    // `delay: delay` — when the label EQUALS the value identifier, the value
+    // is a forwarded local/parameter, not a function reference (Alamofire
+    // A/B finding; same rationale as the `this.x = x` assignment skip).
+    if (type === 'value_argument') {
+      const label = getChildByField(node, 'name');
+      const value = getChildByField(node, 'value') ?? node.namedChild(node.namedChildCount - 1);
+      if (
+        label &&
+        value &&
+        getNodeText(label, source).trim() === getNodeText(value, source).trim()
+      ) {
+        return [];
+      }
+    }
+    if (layerField) {
+      const inner = getChildByField(node, layerField);
+      return inner ? normalizeValue(inner, spec, source, depth + 1) : [];
+    }
+    const results: NormalizedRef[] = [];
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child) results.push(...normalizeValue(child, spec, source, depth + 1));
+    }
+    return results;
+  }
+
+  // Unary wrappers: &fn / @Fn / `fn _`
+  const unwrapField = spec.unwrap?.get(type);
+  if (spec.unwrap?.has(type)) {
+    // C-family `pointer_expression` covers BOTH `&x` (address-of — a function
+    // value) and `*x` (dereference — a data read, never a function value).
+    // Only `&` qualifies; without this, fmt's `*begin` reads resolved to its
+    // free `begin()` functions.
+    if (type === 'pointer_expression' && node.child(0)?.type !== '&') return [];
+    const inner = unwrapField ? getChildByField(node, unwrapField) : node.namedChild(0);
+    if (!inner) return [];
+    // C++ `&Widget::on_click` — keep the QUALIFIED name. Resolution scopes the
+    // method to that class (more precise than a bare-name match, and exempt
+    // from the cpp bare-ids-are-free-functions rule since `&Cls::m` is an
+    // explicit member-pointer).
+    if (inner.type === 'qualified_identifier') {
+      const text = getNodeText(inner, source).trim();
+      return /^[A-Za-z_][\w:]*$/.test(text) ? [{ name: text, node: inner }] : [];
+    }
+    return normalizeValue(inner, spec, source, depth + 1);
+  }
+
+  // Special whole-node reference forms
+  if (spec.special?.has(type)) {
+    return normalizeSpecial(node, type, source);
+  }
+
+  return [];
+}
+
+/** Rightmost descendant-or-self named child of one of the given types. */
+function lastNamedOfType(node: SyntaxNode, types: Set<string>): SyntaxNode | null {
+  let found: SyntaxNode | null = null;
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (!child) continue;
+    if (types.has(child.type)) found = child;
+    const deeper = lastNamedOfType(child, types);
+    if (deeper) found = deeper;
+  }
+  return found;
+}
+
+function normalizeSpecial(
+  node: SyntaxNode,
+  type: string,
+  source: string
+): NormalizedRef[] {
+  switch (type) {
+    // Java method references. Receiver decides the resolution route (#808):
+    //   `this::run0` / `super::close` → `this.<m>` (class-scoped resolver;
+    //     super rides the inherited-member supertype pass)
+    //   `Type::method` (capitalized) → qualified `Type::method` (suffix-
+    //     matched against that type's members, cross-file capable)
+    //   `variable::method` → nothing (receiver type unknown statically —
+    //     the deferred obj.method class)
+    case 'method_reference': {
+      let last: SyntaxNode | null = null;
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child && child.type === 'identifier') last = child;
+      }
+      if (!last) return [];
+      const m = getNodeText(last, source);
+      const text = getNodeText(node, source);
+      if (text.startsWith('this::') || text.startsWith('super::')) {
+        return [{ name: `this.${m}`, node: last }];
+      }
+      const recv = text.match(/^([A-Z][A-Za-z0-9_]*)\s*::/);
+      if (recv) {
+        // `Type::method` — but `Type::new` (constructor ref) has no method
+        // node to land on; let the stoplist drop it via the bare name.
+        return m === 'new' ? [] : [{ name: `${recv[1]}::${m}`, node: last }];
+      }
+      return [];
+    }
+
+    // Kotlin `::targetCb` (one part) / `OtherClass::handle` (two parts —
+    // receiver is a type_identifier; lowercase receivers are variables, the
+    // deferred obj.method class).
+    case 'callable_reference': {
+      let receiver: SyntaxNode | null = null;
+      let member: SyntaxNode | null = null;
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (!child) continue;
+        if (child.type === 'type_identifier') receiver = child;
+        if (child.type === 'simple_identifier') member = child;
+      }
+      if (!member) return [];
+      const m = getNodeText(member, source);
+      if (!receiver) return [{ name: m, node: member }]; // ::topLevelFn
+      const recvText = getNodeText(receiver, source);
+      return /^[A-Z]/.test(recvText)
+        ? [{ name: `${recvText}::${m}`, node: member }]
+        : []; // variable::method — unknown receiver type
+    }
+
+    // Kotlin `this::fire` parses as navigation_expression with a `::fire`
+    // navigation_suffix — route through the class-scoped `this.` resolver.
+    // Ordinary `a.b` navigation (and any non-`this` receiver) MUST yield
+    // nothing.
+    case 'navigation_expression': {
+      if (!getNodeText(node, source).startsWith('this::')) return [];
+      for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child && child.type === 'navigation_suffix' && getNodeText(child, source).startsWith('::')) {
+          const id = child.namedChild(child.namedChildCount - 1);
+          if (id) return [{ name: `this.${getNodeText(id, source)}`, node: id }];
+        }
+      }
+      return [];
+    }
+
+    // Swift `#selector(Holder.fire)` → fire. ObjC `@selector(storeImage:)` →
+    // `storeImage:` verbatim (ObjC method nodes keep their selector colons).
+    case 'selector_expression': {
+      const inner = node.namedChild(0);
+      if (!inner) return [];
+      if (inner.type === 'identifier' || inner.type === 'simple_identifier') {
+        return [{ name: getNodeText(inner, source), node: inner }];
+      }
+      // Swift dotted form: rightmost simple_identifier. ObjC keyword selector:
+      // text as-is.
+      const last = lastNamedOfType(node, new Set(['simple_identifier']));
+      if (last) return [{ name: getNodeText(last, source), node: last }];
+      return [{ name: getNodeText(inner, source).trim(), node: inner }];
+    }
+
+    // Ruby `method(:target_cb)` — a `call` whose method is literally `method`
+    // with a single symbol argument.
+    case 'call': {
+      const method = getChildByField(node, 'method');
+      if (!method || getNodeText(method, source) !== 'method') return [];
+      const args = getChildByField(node, 'arguments');
+      if (!args || args.namedChildCount !== 1) return [];
+      const sym = args.namedChild(0);
+      if (!sym || sym.type !== 'simple_symbol') return [];
+      const name = getNodeText(sym, source).replace(/^:/, '');
+      return name ? [{ name, node: sym }] : [];
+    }
+
+    // `this.handleClick` (TS/JS) — object must be EXACTLY `this`. The name
+    // keeps the `this.` prefix so resolution can scope it to the enclosing
+    // class (see resolveThisMemberFnRef) instead of bare name-matching.
+    case 'member_expression': {
+      const obj = getChildByField(node, 'object');
+      const prop = getChildByField(node, 'property');
+      if (obj && prop && obj.type === 'this' && prop.type === 'property_identifier') {
+        return [{ name: `this.${getNodeText(prop, source)}`, node: prop }];
+      }
+      return [];
+    }
+
+    // `self.handle_click` (Python) — object must be EXACTLY `self`.
+    case 'attribute': {
+      const obj = getChildByField(node, 'object');
+      const attr = getChildByField(node, 'attribute');
+      if (obj && attr && obj.type === 'identifier' && getNodeText(obj, source) === 'self') {
+        return [{ name: getNodeText(attr, source), node: attr }];
+      }
+      return [];
+    }
+
+    // `this.Run0` (C#) — receiver must be EXACTLY `this`. Two grammar shapes:
+    // newer tree-sitter-c-sharp exposes an `expression` field holding a
+    // `this_expression`; the vendored grammar keeps `this` as an anonymous
+    // token (only the `name` field is a named child), so fall back to the
+    // node text.
+    case 'member_access_expression': {
+      const name = getChildByField(node, 'name');
+      if (!name) return [];
+      const expr = getChildByField(node, 'expression');
+      const isThisReceiver = expr
+        ? expr.type === 'this_expression' || expr.type === 'this'
+        : getNodeText(node, source).startsWith('this.');
+      return isThisReceiver ? [{ name: getNodeText(name, source), node: name }] : [];
+    }
+
+    // PHP string callable — trustworthy ONLY as an argument to a known
+    // callable-taking core function (`usort($a, 'cmp_items')`). PHP global
+    // functions are referenced cross-file without imports, so these skip the
+    // name gate and rely on resolution's unique-or-drop rule. A
+    // `'Cls::method'` string becomes a qualified candidate.
+    case 'encapsed_string':
+    case 'string': {
+      const callee = phpEnclosingCallName(node);
+      if (!callee || !PHP_CALLABLE_HOFS.has(callee)) return [];
+      const content = phpStringContent(node, source);
+      if (!content) return [];
+      if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(content)) {
+        return [{ name: content, node, skipGate: true }];
+      }
+      if (/^[A-Za-z_][A-Za-z0-9_]*::[A-Za-z_][A-Za-z0-9_]*$/.test(content)) {
+        return [{ name: content, node, skipGate: true }];
+      }
+      return [];
+    }
+
+    // PHP array callables, valid in ANY call's arguments (the shape itself is
+    // unambiguous): `[$this, 'method']` → class-scoped `this.method`;
+    // `[Foo::class, 'method']` → qualified `Foo::method`.
+    case 'array_creation_expression': {
+      if (node.namedChildCount !== 2) return [];
+      const recv = node.namedChild(0)?.namedChild(0);
+      const strEl = node.namedChild(1)?.namedChild(0);
+      if (!recv || !strEl) return [];
+      if (strEl.type !== 'encapsed_string' && strEl.type !== 'string') return [];
+      const member = phpStringContent(strEl, source);
+      if (!member || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(member)) return [];
+      if (recv.type === 'variable_name' && getNodeText(recv, source) === '$this') {
+        return [{ name: `this.${member}`, node: strEl }];
+      }
+      if (recv.type === 'class_constant_access_expression') {
+        const cls = recv.namedChild(0);
+        const kw = recv.namedChild(1);
+        if (cls && kw && getNodeText(kw, source) === 'class') {
+          return [{ name: `${getNodeText(cls, source)}::${member}`, node: strEl }];
+        }
+      }
+      return [];
+    }
+
+    // Ruby hook-DSL symbols (`before_action :authenticate`,
+    // `rescue_from E, with: :render_404`): the symbol names a method of the
+    // ENCLOSING class — route through the class-scoped `this.` resolver
+    // (which also walks superclasses, covering ApplicationController-style
+    // inheritance). Symbols under any other call yield nothing.
+    case 'simple_symbol': {
+      const call = rubyEnclosingCall(node);
+      if (!call) return [];
+      const method = getChildByField(call, 'method');
+      if (!method || !isRubyHookCall(getNodeText(method, source))) return [];
+      const sym = getNodeText(node, source).replace(/^:/, '');
+      if (!/^[A-Za-z_][A-Za-z0-9_?!]*$/.test(sym)) return [];
+      return [{ name: `this.${sym}`, node }];
+    }
+
+    default:
+      return [];
+  }
+}
+
+/** Content of a PHP string literal node (single- or double-quoted). */
+function phpStringContent(node: SyntaxNode, source: string): string | null {
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'string_content') return getNodeText(child, source).trim();
+  }
+  return null;
+}
+
+/** The function name of the PHP call whose arguments contain `node`, if any. */
+function phpEnclosingCallName(node: SyntaxNode): string | null {
+  let cur: SyntaxNode | null = node.parent;
+  for (let hops = 0; cur && hops < 4; hops++, cur = cur.parent) {
+    if (cur.type === 'function_call_expression') {
+      const fn = getChildByField(cur, 'function');
+      return fn ? fn.text : null;
+    }
+    if (cur.type === 'member_call_expression' || cur.type === 'scoped_call_expression') {
+      return null; // method calls aren't core HOFs
+    }
+  }
+  return null;
+}
+
+/** The Ruby `call` node whose argument_list (or keyword pair) contains `node`. */
+function rubyEnclosingCall(node: SyntaxNode): SyntaxNode | null {
+  let cur: SyntaxNode | null = node.parent;
+  for (let hops = 0; cur && hops < 4; hops++, cur = cur.parent) {
+    if (cur.type === 'call') return cur;
+  }
+  return null;
+}
diff --git a/src/extraction/generated-detection.ts b/src/extraction/generated-detection.ts
new file mode 100644
index 000000000..1ec6a6d82
--- /dev/null
+++ b/src/extraction/generated-detection.ts
@@ -0,0 +1,81 @@
+/**
+ * Generated-file detection for symbol-disambiguation down-ranking.
+ *
+ * When a query like "Send" matches 17 symbols across protobuf scaffolding,
+ * test mocks, and the hand-written implementation, the FTS ranker often
+ * surfaces the generated stubs first because their names are identical
+ * to the implementation's name (validated empirically on cosmos-sdk —
+ * see project_go_multi_module_audit memory). Generated stubs frequently
+ * have no body to trace from, so the agent ends up reading source anyway.
+ *
+ * This helper is a pure path-based classifier consulted at disambiguation
+ * time (findSymbol / findAllSymbols / codegraph_search formatting), NOT
+ * a hard filter — generated nodes are still in the graph and remain
+ * reachable; they just rank LAST when there's a real implementation
+ * with the same name.
+ *
+ * Scope: suffix patterns only. Most generated files follow the
+ * `<basename>.<tool>.<ext>` convention (`.pb.go`, `_grpc.pb.go`,
+ * `.g.dart`, `_pb2.py`), and that covers ~all of what we saw in the
+ * Go audit. A future addition would be scanning for the canonical
+ * `// Code generated by` header during extraction, for the rare files
+ * that defy the suffix convention.
+ */
+
+const GENERATED_PATTERNS: ReadonlyArray<RegExp> = [
+  // Go — protobuf / gRPC / pulsar
+  /\.pb\.go$/,
+  /\.pulsar\.go$/,
+  /_grpc\.pb\.go$/,
+  // Go — mockgen output. Default emits `mock_<src>.go`; many projects
+  // (cosmos-sdk uses `expected_*_mocks.go`) rename to `*_mock.go` /
+  // `*_mocks.go`. Matching either suffix catches both conventions
+  // without false-positive risk on hand-written sources.
+  /_mock\.go$/,
+  /_mocks\.go$/,
+  /^mock_[^/]+\.go$/,
+  // TypeScript / JavaScript — common codegen suffixes (Apollo / GraphQL
+  // codegen, Prisma, Hasura, ts-proto, gRPC-web, swagger-codegen).
+  /\.generated\.[jt]sx?$/,
+  /\.gen\.[jt]sx?$/,
+  /\.pb\.[jt]s$/,
+  /_pb\.[jt]s$/,
+  /_grpc_pb\.[jt]s$/,
+  // Minified bundles vendored into a repo (docs sites, examples). Their
+  // single-letter symbols make name-based edges pure noise.
+  /\.min\.m?js$/,
+  // Python — protobuf / gRPC / openapi-codegen
+  /_pb2(_grpc)?\.py$/,
+  /_pb2\.pyi$/,
+  // C++ — protobuf
+  /\.pb\.(cc|h)$/,
+  // C# — protobuf / gRPC (protoc-gen-csharp puts output under obj/ but
+  // many projects also commit *.g.cs and *Grpc.cs siblings)
+  /\.g\.cs$/,
+  /Grpc\.cs$/,
+  // Java — protobuf / gRPC: protoc-gen-java emits `*OuterClass.java`,
+  // protoc-gen-grpc-java emits `*Grpc.java`. The XxxImplBase abstract
+  // class lives inside Xxx*Grpc.java.
+  /OuterClass\.java$/,
+  /Grpc\.java$/,
+  // Swift — protobuf
+  /\.pb\.swift$/,
+  // Dart — build_runner / freezed / json_serializable / chopper
+  /\.g\.dart$/,
+  /\.freezed\.dart$/,
+  /\.pb\.dart$/,
+  /\.pbgrpc\.dart$/,
+  /\.chopper\.dart$/,
+  // Rust — common build.rs OUT_DIR outputs are usually outside the source
+  // tree, but in-tree generated files often use `*.generated.rs`.
+  /\.generated\.rs$/,
+];
+
+/**
+ * Whether `filePath` looks like a tool-generated source file based on
+ * its filename. Path-only — does not read content. The result is a
+ * relevance hint for disambiguation, not a hard claim.
+ */
+export function isGeneratedFile(filePath: string): boolean {
+  return GENERATED_PATTERNS.some((p) => p.test(filePath));
+}
diff --git a/src/extraction/grammars.ts b/src/extraction/grammars.ts
index 15f224d9c..eabdb598e 100644
--- a/src/extraction/grammars.ts
+++ b/src/extraction/grammars.ts
@@ -10,7 +10,7 @@ import * as path from 'path';
 import { Parser, Language as WasmLanguage } from 'web-tree-sitter';
 import { Language } from '../types';
 
-export type GrammarLanguage = Exclude<Language, 'svelte' | 'vue' | 'liquid' | 'unknown'>;
+export type GrammarLanguage = Exclude<Language, 'svelte' | 'vue' | 'astro' | 'liquid' | 'razor' | 'yaml' | 'twig' | 'xml' | 'properties' | 'unknown'>;
 
 /**
  * WASM filename map — maps each language to its .wasm grammar file
@@ -37,6 +37,7 @@ const WASM_GRAMMAR_FILES: Record<GrammarLanguage, string> = {
   scala: 'tree-sitter-scala.wasm',
   lua: 'tree-sitter-lua.wasm',
   luau: 'tree-sitter-luau.wasm',
+  objc: 'tree-sitter-objc.wasm',
 };
 
 /**
@@ -45,9 +46,15 @@ const WASM_GRAMMAR_FILES: Record<GrammarLanguage, string> = {
 export const EXTENSION_MAP: Record<string, Language> = {
   '.ts': 'typescript',
   '.tsx': 'tsx',
+  // ESM/CJS TypeScript module extensions — parsed as TS (no JSX). (#366)
+  '.mts': 'typescript',
+  '.cts': 'typescript',
   '.js': 'javascript',
   '.mjs': 'javascript',
   '.cjs': 'javascript',
+  // SAP HANA XS Classic server-side JavaScript. (#556)
+  '.xsjs': 'javascript',
+  '.xsjslib': 'javascript',
   '.jsx': 'jsx',
   '.py': 'python',
   '.pyw': 'python',
@@ -62,7 +69,21 @@ export const EXTENSION_MAP: Record<string, Language> = {
   '.hpp': 'cpp',
   '.hxx': 'cpp',
   '.cs': 'csharp',
+  // ASP.NET Razor / Blazor markup — custom RazorExtractor (links @model/@inject/
+  // component tags to their C# types; markup isn't a tree-sitter grammar).
+  '.cshtml': 'razor',
+  '.razor': 'razor',
   '.php': 'php',
+  // Drupal-specific PHP file extensions
+  '.module': 'php',
+  '.install': 'php',
+  '.theme': 'php',
+  '.inc': 'php',
+  // YAML (used for Drupal routing files; no symbol extraction, file-level tracking only)
+  '.yml': 'yaml',
+  '.yaml': 'yaml',
+  // Twig templates (file-level tracking only, no symbol extraction)
+  '.twig': 'twig',
   '.rb': 'ruby',
   '.rake': 'ruby',
   '.swift': 'swift',
@@ -72,6 +93,7 @@ export const EXTENSION_MAP: Record<string, Language> = {
   '.liquid': 'liquid',
   '.svelte': 'svelte',
   '.vue': 'vue',
+  '.astro': 'astro',
   '.pas': 'pascal',
   '.dpr': 'pascal',
   '.dpk': 'pascal',
@@ -82,8 +104,54 @@ export const EXTENSION_MAP: Record<string, Language> = {
   '.sc': 'scala',
   '.lua': 'lua',
   '.luau': 'luau',
+  '.m': 'objc',
+  '.mm': 'objc',
+  // XML: file-level tracking; the MyBatis extractor matches `<mapper namespace="...">`
+  // shape and emits SQL-statement nodes (other XML returns empty).
+  '.xml': 'xml',
+  // Spring config: `application.properties` / `application-*.properties`. Same
+  // shape as the `.yml` variants — the YAML/properties extractor emits one node
+  // per leaf key, and the Spring resolver links `@Value("${k}")` references.
+  '.properties': 'properties',
 };
 
+/**
+ * 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.
+ */
+export function isSourceFile(filePath: string): boolean {
+  if (isPlayRoutesFile(filePath)) return true; // Play `conf/routes` is extensionless
+  if (isShopifyLiquidJson(filePath)) return true; // Shopify OS 2.0 JSON templates / section groups
+  const dot = filePath.lastIndexOf('.');
+  if (dot < 0) return false;
+  return filePath.slice(dot).toLowerCase() in EXTENSION_MAP;
+}
+
+/**
+ * Shopify OS 2.0 JSON template (`templates/*.json`) or section group
+ * (`sections/*.json`) — these reference sections by `"type"`, so the Liquid
+ * extractor links them. (config/ + locales/ JSON have no section refs.)
+ */
+export function isShopifyLiquidJson(filePath: string): boolean {
+  // Allow nested template dirs (`templates/customers/login.json`), not just
+  // top-level (`templates/product.json`).
+  return /(^|\/)(templates|sections)\/.+\.json$/i.test(filePath);
+}
+
+/**
+ * Play Framework routes file: the extensionless `conf/routes` (and included
+ * `conf/*.routes`). No grammar — route extraction is done by the Play framework
+ * resolver, so it's processed through the no-grammar (`yaml`-style) path.
+ */
+export function isPlayRoutesFile(filePath: string): boolean {
+  return (
+    filePath === 'conf/routes' ||
+    filePath.endsWith('/conf/routes') ||
+    filePath.endsWith('.routes')
+  );
+}
+
 /**
  * Caches for loaded grammars and parsers
  */
@@ -116,6 +184,14 @@ export async function loadGrammarsForLanguages(languages: Language[]): Promise<v
     await initGrammars();
   }
 
+  // SFC languages (svelte/vue/astro) have no grammar of their own — their
+  // extractors delegate <script>/frontmatter content to the TS/JS extractor,
+  // so those grammars must be loaded even when no plain .ts/.js file is in
+  // the index set (e.g. a pure-.astro content site).
+  if (languages.some((l) => l === 'svelte' || l === 'vue' || l === 'astro')) {
+    languages = [...languages, 'typescript', 'javascript'];
+  }
+
   // Deduplicate and filter to languages that have WASM grammars and aren't already loaded
   const toLoad = [...new Set(languages)].filter(
     (lang): lang is GrammarLanguage =>
@@ -133,8 +209,12 @@ export async function loadGrammarsForLanguages(languages: Language[]): Promise<v
       // tree-sitter-wasms build is too old). Lua: tree-sitter-wasms ships an
       // ABI-13 build that corrupts the shared WASM heap under web-tree-sitter
       // 0.25 (drops nested calls/imports on every file after the first); we
-      // vendor the upstream ABI-15 wasm instead.
-      const wasmPath = (lang === 'pascal' || lang === 'scala' || lang === 'lua' || lang === 'luau')
+      // vendor the upstream ABI-15 wasm instead. C#: the tree-sitter-wasms
+      // build (ABI 13) has no primary-constructor support and parses
+      // `class Foo(...)` as an ERROR that swallows the whole class (#237); we
+      // vendor the upstream ABI-15 tree-sitter-c-sharp 0.23.5 wasm, which parses
+      // primary constructors natively.
+      const wasmPath = (lang === 'pascal' || lang === 'scala' || lang === 'lua' || lang === 'luau' || lang === 'csharp')
         ? path.join(__dirname, 'wasm', wasmFile)
         : require.resolve(`tree-sitter-wasms/out/${wasmFile}`);
       const language = await WasmLanguage.load(wasmPath);
@@ -187,12 +267,19 @@ export function getParser(language: Language): Parser | null {
  * Detect language from file extension
  */
 export function detectLanguage(filePath: string, source?: string): Language {
+  // Play `conf/routes` has no grammar — route through the no-symbol path; the
+  // Play framework resolver extracts route nodes from it.
+  if (isPlayRoutesFile(filePath)) return 'yaml';
   const ext = filePath.substring(filePath.lastIndexOf('.')).toLowerCase();
+  // Shopify OS 2.0 JSON templates / section groups → the Liquid extractor (it
+  // links each section `"type"` to its `sections/<type>.liquid`).
+  if (isShopifyLiquidJson(filePath)) return 'liquid';
   const lang = EXTENSION_MAP[ext] || 'unknown';
 
-  // .h files could be C or C++ — check source content for C++ features
+  // .h files could be C, C++, or Objective-C — check source content
   if (lang === 'c' && ext === '.h' && source) {
     if (looksLikeCpp(source)) return 'cpp';
+    if (looksLikeObjc(source)) return 'objc';
   }
 
   return lang;
@@ -207,6 +294,14 @@ function looksLikeCpp(source: string): boolean {
   return /\bnamespace\b|\bclass\s+\w+\s*[:{]|\btemplate\s*<|\b(?:public|private|protected)\s*:|\bvirtual\b|\busing\s+(?:namespace\b|\w+\s*=)/.test(sample);
 }
 
+/**
+ * Heuristic: does a .h file contain Objective-C constructs?
+ */
+function looksLikeObjc(source: string): boolean {
+  const sample = source.substring(0, 8192);
+  return /@(?:interface|implementation|protocol|synthesize)\b/.test(sample);
+}
+
 /**
  * Check if a language is supported (has a grammar defined).
  * Returns true if the grammar exists, even if not yet loaded.
@@ -214,7 +309,13 @@ function looksLikeCpp(source: string): boolean {
 export function isLanguageSupported(language: Language): boolean {
   if (language === 'svelte') return true; // custom extractor (script block delegation)
   if (language === 'vue') return true; // custom extractor (script block delegation)
+  if (language === 'astro') return true; // custom extractor (frontmatter/script block delegation)
   if (language === 'liquid') return true; // custom regex extractor
+  if (language === 'razor') return true; // custom RazorExtractor (.cshtml/.razor markup)
+  if (language === 'yaml') return true; // file-level tracking only; Drupal routing extraction via framework resolver
+  if (language === 'twig') return true; // file-level tracking only
+  if (language === 'xml') return true; // MyBatis mapper extractor
+  if (language === 'properties') return true; // Spring config keys
   if (language === 'unknown') return false;
   return language in WASM_GRAMMAR_FILES;
 }
@@ -223,15 +324,30 @@ export function isLanguageSupported(language: Language): boolean {
  * Check if a grammar has been loaded and is ready for parsing.
  */
 export function isGrammarLoaded(language: Language): boolean {
-  if (language === 'svelte' || language === 'vue' || language === 'liquid') return true;
+  if (language === 'svelte' || language === 'vue' || language === 'astro' || language === 'liquid' || language === 'razor') return true;
+  if (language === 'yaml' || language === 'twig') return true; // no WASM grammar needed
+  if (language === 'xml' || language === 'properties') return true; // no WASM grammar needed
   return languageCache.has(language);
 }
 
+/**
+ * Languages tracked at the file-record level only: parsing emits zero symbol
+ * nodes, but the file is still stored (and framework resolvers may add per-file
+ * references later, e.g. Drupal routing yml, Spring `@Value` against
+ * application.properties). This is the canonical set behind the no-symbol
+ * branch in `tree-sitter.ts`; `xml` is intentionally excluded because its
+ * MyBatis extractor emits a file node. Callers use this to count such files as
+ * indexed rather than skipped, so it must stay in sync with that branch.
+ */
+export function isFileLevelOnlyLanguage(language: Language): boolean {
+  return language === 'yaml' || language === 'twig' || language === 'properties';
+}
+
 /**
  * Get all supported languages (those with grammar definitions).
  */
 export function getSupportedLanguages(): Language[] {
-  return [...(Object.keys(WASM_GRAMMAR_FILES) as GrammarLanguage[]), 'svelte', 'vue', 'liquid'];
+  return [...(Object.keys(WASM_GRAMMAR_FILES) as GrammarLanguage[]), 'svelte', 'vue', 'astro', 'liquid'];
 }
 
 /**
@@ -289,6 +405,7 @@ export function getLanguageDisplayName(language: Language): string {
     c: 'C',
     cpp: 'C++',
     csharp: 'C#',
+    razor: 'Razor/Blazor',
     php: 'PHP',
     ruby: 'Ruby',
     swift: 'Swift',
@@ -296,11 +413,17 @@ export function getLanguageDisplayName(language: Language): string {
     dart: 'Dart',
     svelte: 'Svelte',
     vue: 'Vue',
+    astro: 'Astro',
     liquid: 'Liquid',
     pascal: 'Pascal / Delphi',
     scala: 'Scala',
     lua: 'Lua',
     luau: 'Luau',
+    objc: 'Objective-C',
+    yaml: 'YAML',
+    twig: 'Twig',
+    xml: 'XML',
+    properties: 'Java properties',
     unknown: 'Unknown',
   };
   return names[language] || language;
diff --git a/src/extraction/index.ts b/src/extraction/index.ts
index 18086bdfd..271309b9b 100644
--- a/src/extraction/index.ts
+++ b/src/extraction/index.ts
@@ -14,14 +14,14 @@ import {
   FileRecord,
   ExtractionResult,
   ExtractionError,
-  CodeGraphConfig,
 } from '../types';
 import { QueryBuilder } from '../db/queries';
 import { extractFromSource } from './tree-sitter';
-import { detectLanguage, isLanguageSupported, initGrammars, loadGrammarsForLanguages } from './grammars';
+import { detectLanguage, isSourceFile, isLanguageSupported, isFileLevelOnlyLanguage, initGrammars, loadGrammarsForLanguages } from './grammars';
+import { isCodeGraphDataDir } from '../directory';
 import { logDebug, logWarn } from '../errors';
 import { validatePathWithinRoot, normalizePath } from '../utils';
-import picomatch from 'picomatch';
+import ignore, { Ignore } from 'ignore';
 import { detectFrameworks } from '../resolution/frameworks';
 import type { ResolutionContext } from '../resolution/types';
 
@@ -94,35 +94,156 @@ export function hashContent(content: string): string {
 }
 
 /**
- * Check if a path matches any glob pattern (simplified)
+ * Skip files larger than this (bytes). Generated bundles, minified JS, and
+ * vendored blobs blow the WASM heap and the worker-recycle budget for no useful
+ * symbols. 1 MB covers essentially all hand-written source.
  */
-function matchesGlob(filePath: string, pattern: string): boolean {
-  filePath = normalizePath(filePath);
-  return picomatch.isMatch(filePath, pattern, { dot: true });
-}
+const MAX_FILE_SIZE = 1024 * 1024;
 
 /**
- * Check if a file should be included based on config
+ * Directory names that are dependency, build, cache, or tooling output across the
+ * languages/frameworks CodeGraph supports — curated from the canonical
+ * github/gitignore templates. Excluded by default so the graph reflects your code,
+ * not third-party noise, without requiring a `.gitignore` (issue #407). The
+ * exclusion applies uniformly (git or not, tracked or not); the only opt-in is an
+ * explicit `.gitignore` negation (e.g. `!vendor/`). First-party-prone or generic
+ * names (`packages`, `lib`, `app`, `bin`, `src`, `deps`, `env`, `tmp`, `storage`,
+ * `Library`) are deliberately NOT listed, to avoid ever hiding real source.
+ *
+ * Only dirs that actually contain *indexable source* (or are enormous) earn a slot
+ * — IDE/state dirs like `.idea`/`.vs` are omitted because CodeGraph indexes only
+ * recognized source extensions, so they produce no symbols regardless.
  */
-export function shouldIncludeFile(
-  filePath: string,
-  config: CodeGraphConfig
-): boolean {
-  // Check exclude patterns first
-  for (const pattern of config.exclude) {
-    if (matchesGlob(filePath, pattern)) {
-      return false;
-    }
+const DEFAULT_IGNORE_DIRS: ReadonlySet<string> = new Set([
+  // JS / TS — dependency directories
+  'node_modules', 'bower_components', 'jspm_packages', 'web_modules',
+  '.yarn', '.pnpm-store',
+  // JS / TS — framework & bundler build / cache / deploy output
+  '.next', '.nuxt', '.svelte-kit', '.turbo', '.vite', '.parcel-cache', '.angular',
+  '.docusaurus', 'storybook-static', '.vinxi', '.nitro', 'out-tsc',
+  '.vercel', '.netlify', '.wrangler',
+  // Build output (common across ecosystems)
+  'dist', 'build', 'out', '.output',
+  // Test / coverage
+  'coverage', '.nyc_output',
+  // Python
+  '__pycache__', '__pypackages__', '.venv', 'venv', '.pixi', '.pdm-build',
+  '.mypy_cache', '.pytest_cache', '.ruff_cache', '.tox', '.nox', '.hypothesis',
+  '.ipynb_checkpoints', '.eggs',
+  // Rust / JVM (Maven, Gradle, Scala)
+  'target', '.gradle',
+  // .NET
+  'obj',
+  // Vendored deps (Go, PHP/Composer, Ruby/Bundler)
+  'vendor',
+  // Swift / iOS
+  '.build', 'Pods', 'Carthage', 'DerivedData', '.swiftpm',
+  // Dart / Flutter
+  '.dart_tool', '.pub-cache',
+  // Native (Android NDK, C/C++ deps)
+  '.cxx', '.externalNativeBuild', 'vcpkg_installed',
+  // Scala tooling
+  '.bloop', '.metals',
+  // Lua / Luau (LuaRocks)
+  'lua_modules', '.luarocks',
+  // Delphi / RAD Studio IDE backups (duplicate .pas source — would double-count)
+  '__history', '__recovery',
+  // Generic cache
+  '.cache',
+]);
+
+/** Gitignore-style patterns for the `ignore` matcher: the dirs above plus a few globs. */
+const DEFAULT_IGNORE_PATTERNS: string[] = [
+  ...Array.from(DEFAULT_IGNORE_DIRS, (d) => `${d}/`),
+  '*.egg-info/',     // Python packaging metadata
+  'cmake-build-*/',  // CLion / CMake build trees
+  'bazel-*/',        // Bazel output symlink trees
+];
+
+/** True if `buf` decodes as strict UTF-8 (no invalid byte sequences). */
+function isValidUtf8(buf: Buffer): boolean {
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(buf);
+    return true;
+  } catch {
+    return false;
   }
+}
 
-  // Check include patterns
-  for (const pattern of config.include) {
-    if (matchesGlob(filePath, pattern)) {
-      return true;
+/**
+ * Read a `.gitignore` and return patterns safe to hand to the `ignore` matcher —
+ * never throwing, even when the file isn't real gitignore text. Two failure
+ * modes, both seen in the wild (issue #682):
+ *
+ *  - The file isn't valid UTF-8 — e.g. transparently encrypted in place by
+ *    corporate DLP / endpoint-security software, leaving a UTF-16 header plus
+ *    ciphertext. None of it is meaningful patterns, so the whole file is skipped.
+ *  - The file is text but a single line can't be compiled to a regex by the
+ *    `ignore` library — `\\[` and friends throw "Unterminated character class".
+ *    Crucially the throw is LAZY (at match time, not `.add()`), so it would
+ *    otherwise escape mid-scan. That one pattern is dropped; the rest are kept.
+ *
+ * Either way a warning that NAMES the file is logged (the reporter couldn't tell
+ * which `.gitignore` was at fault) and indexing continues instead of aborting.
+ * Returns '' when there's nothing usable.
+ */
+function readGitignorePatterns(giPath: string): string {
+  let buf: Buffer;
+  try {
+    buf = fs.readFileSync(giPath);
+  } catch {
+    return ''; // unreadable (permissions / race) — treat as absent
+  }
+  // A NUL byte never appears in real gitignore text, and a fatal UTF-8 decode
+  // catches the rest. Such a file isn't ignore patterns at all.
+  if (buf.includes(0) || !isValidUtf8(buf)) {
+    logWarn(
+      'Ignoring a .gitignore that is not valid UTF-8 text — it may have been encrypted ' +
+        'in place by endpoint-security software. Indexing continues without it.',
+      { file: giPath },
+    );
+    return '';
+  }
+  const content = buf.toString('utf-8');
+  // Fast path: one `.ignores()` call forces the library to compile EVERY rule,
+  // so if it doesn't throw, the whole file is safe to use verbatim.
+  try {
+    ignore().add(content).ignores('.codegraph-probe');
+    return content;
+  } catch {
+    // Fall through: a line is uncompilable — keep the good ones, drop the bad.
+  }
+  const kept: string[] = [];
+  let dropped = 0;
+  for (const line of content.split(/\r?\n/)) {
+    try {
+      ignore().add(line).ignores('.codegraph-probe');
+      kept.push(line);
+    } catch {
+      dropped++;
     }
   }
+  if (dropped > 0) {
+    logWarn(
+      `Skipped ${dropped} unparseable pattern(s) in a .gitignore; the rest are applied.`,
+      { file: giPath },
+    );
+  }
+  return kept.join('\n');
+}
 
-  return false;
+/**
+ * An `ignore` matcher seeded with the built-in defaults, merged with the project's
+ * root .gitignore so a negation there (e.g. `!vendor/`) overrides a default. Shared
+ * by both enumeration paths so behavior is identical with or without git — and so
+ * the defaults apply to tracked files too (committing a dependency dir doesn't make
+ * it project code; the explicit `.gitignore` negation is the only opt-in).
+ */
+export function buildDefaultIgnore(rootDir: string): Ignore {
+  const ig = ignore().add(DEFAULT_IGNORE_PATTERNS);
+  const rootGitignore = path.join(rootDir, '.gitignore');
+  if (fs.existsSync(rootGitignore)) ig.add(readGitignorePatterns(rootGitignore));
+  return ig;
 }
 
 /**
@@ -139,39 +260,39 @@ export function shouldIncludeFile(
  * (See issue #193.)
  */
 function collectGitFiles(repoDir: string, prefix: string, files: Set<string>): void {
-  const gitOpts = { cwd: repoDir, encoding: 'utf-8' as const, timeout: 30000, maxBuffer: 50 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] as ['pipe', 'pipe', 'pipe'] };
+  const gitOpts = { cwd: repoDir, encoding: 'utf-8' as const, timeout: 30000, maxBuffer: 50 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] as ['pipe', 'pipe', 'pipe'], windowsHide: true };
 
   // Tracked files. --recurse-submodules pulls in files from active submodules,
   // which the index would otherwise represent only as a commit pointer.
   // Without this, monorepos using submodules index 0 files. (See issue #147.)
   // Note: --recurse-submodules only supports -c/--cached and --stage modes — it
   // can't be combined with -o, so untracked files are gathered separately below.
-  const tracked = execFileSync('git', ['ls-files', '-c', '--recurse-submodules'], gitOpts);
-  for (const line of tracked.split('\n')) {
-    const trimmed = line.trim();
-    if (trimmed) {
-      files.add(normalizePath(prefix + trimmed));
-    }
+  // -z gives NUL-separated, unquoted output so non-ASCII (e.g. CJK) paths
+  // survive verbatim. Without it git octal-escapes and double-quotes such paths
+  // (the core.quotepath default), and the quoted form never matches a real file
+  // on disk → those files are silently dropped from the index. (#541)
+  const tracked = execFileSync('git', ['ls-files', '-z', '-c', '--recurse-submodules'], gitOpts);
+  for (const rel of tracked.split('\0')) {
+    if (rel) files.add(normalizePath(prefix + rel));
   }
 
   // Untracked files (submodules manage their own untracked state). Embedded git
   // repos surface here as a single "subdir/" entry that git refuses to descend
   // into — recurse into those as their own repos so their source gets indexed.
-  const untracked = execFileSync('git', ['ls-files', '-o', '--exclude-standard'], gitOpts);
-  for (const line of untracked.split('\n')) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-    if (trimmed.endsWith('/')) {
+  const untracked = execFileSync('git', ['ls-files', '-z', '-o', '--exclude-standard'], gitOpts);
+  for (const rel of untracked.split('\0')) {
+    if (!rel) continue;
+    if (rel.endsWith('/')) {
       // git only emits a trailing-slash directory entry for an embedded repo.
       // Guard with a .git check anyway, and skip anything else exactly as git
       // itself skips it (we never descend into a non-repo opaque dir).
-      const childDir = path.join(repoDir, trimmed);
+      const childDir = path.join(repoDir, rel);
       if (fs.existsSync(path.join(childDir, '.git'))) {
-        collectGitFiles(childDir, prefix + trimmed, files);
+        collectGitFiles(childDir, prefix + rel, files);
       }
       continue;
     }
-    files.add(normalizePath(prefix + trimmed));
+    files.add(normalizePath(prefix + rel));
   }
 }
 
@@ -189,7 +310,7 @@ function getGitVisibleFiles(rootDir: string): Set<string> | null {
     const gitRoot = execFileSync(
       'git',
       ['rev-parse', '--show-toplevel'],
-      { cwd: rootDir, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }
+      { cwd: rootDir, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }
     ).trim();
 
     if (path.resolve(gitRoot) !== path.resolve(rootDir)) {
@@ -198,7 +319,7 @@ function getGitVisibleFiles(rootDir: string): Set<string> | null {
         execFileSync(
           'git',
           ['check-ignore', '-q', path.resolve(rootDir)],
-          { cwd: rootDir, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }
+          { cwd: rootDir, encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }
         );
         // Directory is gitignored by parent repo — fall back to filesystem walk
         return null;
@@ -209,7 +330,11 @@ function getGitVisibleFiles(rootDir: string): Set<string> | null {
 
     const files = new Set<string>();
     collectGitFiles(rootDir, '', files);
-    return files;
+    // Apply built-in default ignores uniformly — to tracked files too, since
+    // committing a dependency/build dir doesn't make it project code. A
+    // `.gitignore` negation (e.g. `!vendor/`) is the explicit opt-in. (issue #407)
+    const ig = buildDefaultIgnore(rootDir);
+    return new Set([...files].filter((f) => !ig.ignores(f)));
   } catch {
     return null;
   }
@@ -230,12 +355,12 @@ interface GitChanges {
  * Use `git status` to detect changed files instead of scanning every file.
  * Returns null on failure so callers fall back to full scan.
  */
-function getGitChangedFiles(rootDir: string, config: CodeGraphConfig): GitChanges | null {
+function getGitChangedFiles(rootDir: string): GitChanges | null {
   try {
     const output = execFileSync(
       'git',
       ['status', '--porcelain', '--no-renames'],
-      { cwd: rootDir, encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'] }
+      { cwd: rootDir, encoding: 'utf-8', timeout: 10000, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }
     );
 
     const modified: string[] = [];
@@ -248,8 +373,8 @@ function getGitChangedFiles(rootDir: string, config: CodeGraphConfig): GitChange
       const statusCode = line.substring(0, 2);
       const filePath = normalizePath(line.substring(3));
 
-      // Skip files that don't match include/exclude config
-      if (!shouldIncludeFile(filePath, config)) continue;
+      // Skip non-source files (git status already omits .gitignored paths).
+      if (!isSourceFile(filePath)) continue;
 
       if (statusCode === '??') {
         added.push(filePath);
@@ -268,20 +393,14 @@ function getGitChangedFiles(rootDir: string, config: CodeGraphConfig): GitChange
 }
 
 /**
- * Marker file name that indicates a directory (and all children) should be skipped
- */
-const CODEGRAPH_IGNORE_MARKER = '.codegraphignore';
-
-/**
- * Recursively scan directory for source files.
+ * Recursively scan a directory for source files.
  *
- * In git repos, uses `git ls-files` to get the file list (inherently
- * respects .gitignore at all levels), then filters by config include patterns.
- * Falls back to filesystem walk for non-git projects.
+ * In git repos, uses `git ls-files` (inherently respects .gitignore at all
+ * levels), then keeps files with a supported source extension. For non-git
+ * projects, falls back to a filesystem walk that parses .gitignore itself.
  */
 export function scanDirectory(
   rootDir: string,
-  config: CodeGraphConfig,
   onProgress?: (current: number, file: string) => void
 ): string[] {
   // Fast path: use git to get all visible files (respects .gitignore everywhere)
@@ -290,7 +409,7 @@ export function scanDirectory(
     const files: string[] = [];
     let count = 0;
     for (const filePath of gitFiles) {
-      if (shouldIncludeFile(filePath, config)) {
+      if (isSourceFile(filePath)) {
         files.push(filePath);
         count++;
         onProgress?.(count, filePath);
@@ -300,7 +419,7 @@ export function scanDirectory(
   }
 
   // Fallback: walk filesystem for non-git projects
-  return scanDirectoryWalk(rootDir, config, onProgress);
+  return scanDirectoryWalk(rootDir, onProgress);
 }
 
 /**
@@ -309,7 +428,6 @@ export function scanDirectory(
  */
 export async function scanDirectoryAsync(
   rootDir: string,
-  config: CodeGraphConfig,
   onProgress?: (current: number, file: string) => void
 ): Promise<string[]> {
   const gitFiles = getGitVisibleFiles(rootDir);
@@ -317,7 +435,7 @@ export async function scanDirectoryAsync(
     const files: string[] = [];
     let count = 0;
     for (const filePath of gitFiles) {
-      if (shouldIncludeFile(filePath, config)) {
+      if (isSourceFile(filePath)) {
         files.push(filePath);
         count++;
         onProgress?.(count, filePath);
@@ -330,7 +448,7 @@ export async function scanDirectoryAsync(
     return files;
   }
 
-  return scanDirectoryWalk(rootDir, config, onProgress);
+  return scanDirectoryWalk(rootDir, onProgress);
 }
 
 /**
@@ -338,14 +456,42 @@ export async function scanDirectoryAsync(
  */
 function scanDirectoryWalk(
   rootDir: string,
-  config: CodeGraphConfig,
   onProgress?: (current: number, file: string) => void
 ): string[] {
   const files: string[] = [];
   let count = 0;
   const visitedDirs = new Set<string>();
 
-  function walk(dir: string): void {
+  // A .gitignore matcher scoped to the directory that declared it. Patterns in
+  // a nested .gitignore are relative to that directory, so we keep the dir
+  // alongside the matcher and test paths relative to it — mirroring how git
+  // applies .gitignore files at every level.
+  interface ScopedIgnore {
+    dir: string;
+    ig: Ignore;
+  }
+
+  const loadIgnore = (dir: string): ScopedIgnore | null => {
+    const giPath = path.join(dir, '.gitignore');
+    if (!fs.existsSync(giPath)) return null;
+    // readGitignorePatterns is defensive: a non-UTF-8 (DLP-encrypted) or
+    // uncompilable .gitignore is skipped/filtered with a warning, never thrown
+    // (issue #682) — so the per-file `.ignores()` calls below can't crash.
+    const patterns = readGitignorePatterns(giPath);
+    return patterns ? { dir, ig: ignore().add(patterns) } : null;
+  };
+
+  const isIgnored = (fullPath: string, isDir: boolean, matchers: ScopedIgnore[]): boolean => {
+    for (const { dir, ig } of matchers) {
+      let rel = normalizePath(path.relative(dir, fullPath));
+      if (!rel || rel.startsWith('..')) continue; // not under this matcher's dir
+      if (isDir) rel += '/'; // dir-only rules (e.g. `build/`) only match with the slash
+      if (ig.ignores(rel)) return true;
+    }
+    return false;
+  };
+
+  function walk(dir: string, matchers: ScopedIgnore[]): void {
     let realDir: string;
     try {
       realDir = fs.realpathSync(dir);
@@ -360,12 +506,11 @@ function scanDirectoryWalk(
     }
     visitedDirs.add(realDir);
 
-    // Check for .codegraphignore marker file
-    const ignoreMarker = path.join(dir, CODEGRAPH_IGNORE_MARKER);
-    if (fs.existsSync(ignoreMarker)) {
-      logDebug('Skipping directory due to .codegraphignore marker', { dir });
-      return;
-    }
+    // This directory's own .gitignore (if present) applies to everything below it.
+    // The root's .gitignore is already merged into the seeded base matcher (so a
+    // negation there can override a built-in default), so skip it here.
+    const own = dir === rootDir ? null : loadIgnore(dir);
+    const active = own ? [...matchers, own] : matchers;
 
     let entries: fs.Dirent[];
     try {
@@ -376,6 +521,10 @@ function scanDirectoryWalk(
     }
 
     for (const entry of entries) {
+      // Never descend into git internals or any CodeGraph data directory
+      // (the active one or a sibling another environment created — #636).
+      if (entry.name === '.git' || isCodeGraphDataDir(entry.name)) continue;
+
       const fullPath = path.join(dir, entry.name);
       const relativePath = normalizePath(path.relative(rootDir, fullPath));
 
@@ -384,19 +533,11 @@ function scanDirectoryWalk(
           const realTarget = fs.realpathSync(fullPath);
           const stat = fs.statSync(realTarget);
           if (stat.isDirectory()) {
-            const dirPattern = relativePath + '/';
-            let excluded = false;
-            for (const pattern of config.exclude) {
-              if (matchesGlob(dirPattern, pattern) || matchesGlob(relativePath, pattern)) {
-                excluded = true;
-                break;
-              }
-            }
-            if (!excluded) {
-              walk(fullPath);
+            if (!isIgnored(fullPath, true, active)) {
+              walk(fullPath, active);
             }
           } else if (stat.isFile()) {
-            if (shouldIncludeFile(relativePath, config)) {
+            if (!isIgnored(fullPath, false, active) && isSourceFile(relativePath)) {
               files.push(relativePath);
               count++;
               onProgress?.(count, relativePath);
@@ -409,19 +550,11 @@ function scanDirectoryWalk(
       }
 
       if (entry.isDirectory()) {
-        const dirPattern = relativePath + '/';
-        let excluded = false;
-        for (const pattern of config.exclude) {
-          if (matchesGlob(dirPattern, pattern) || matchesGlob(relativePath, pattern)) {
-            excluded = true;
-            break;
-          }
-        }
-        if (!excluded) {
-          walk(fullPath);
+        if (!isIgnored(fullPath, true, active)) {
+          walk(fullPath, active);
         }
       } else if (entry.isFile()) {
-        if (shouldIncludeFile(relativePath, config)) {
+        if (!isIgnored(fullPath, false, active) && isSourceFile(relativePath)) {
           files.push(relativePath);
           count++;
           onProgress?.(count, relativePath);
@@ -430,7 +563,9 @@ function scanDirectoryWalk(
     }
   }
 
-  walk(rootDir);
+  // Seed a base matcher with the built-in default ignores (merged with the root
+  // .gitignore so a negation can override). Nested .gitignores still layer per-dir.
+  walk(rootDir, [{ dir: rootDir, ig: buildDefaultIgnore(rootDir) }]);
   return files;
 }
 
@@ -439,7 +574,6 @@ function scanDirectoryWalk(
  */
 export class ExtractionOrchestrator {
   private rootDir: string;
-  private config: CodeGraphConfig;
   private queries: QueryBuilder;
   /**
    * Names of frameworks detected for this project, populated by indexAll().
@@ -449,9 +583,8 @@ export class ExtractionOrchestrator {
    */
   private detectedFrameworkNames: string[] | null = null;
 
-  constructor(rootDir: string, config: CodeGraphConfig, queries: QueryBuilder) {
+  constructor(rootDir: string, queries: QueryBuilder) {
     this.rootDir = rootDir;
-    this.config = config;
     this.queries = queries;
   }
 
@@ -490,6 +623,24 @@ export class ExtractionOrchestrator {
           return null;
         }
       },
+      // Monorepo support — needed by framework detect()s that probe
+      // subpackage manifests (e.g. fabric-view looking at
+      // packages/<sub>/package.json when the root manifest is just a
+      // workspace declaration). Matches the resolver-context shape.
+      listDirectories: (relativePath: string) => {
+        const target =
+          relativePath === '.' || relativePath === ''
+            ? rootDir
+            : path.join(rootDir, relativePath);
+        try {
+          return fs
+            .readdirSync(target, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+        } catch {
+          return [];
+        }
+      },
     };
   }
 
@@ -500,7 +651,7 @@ export class ExtractionOrchestrator {
    */
   private ensureDetectedFrameworks(files?: string[]): string[] {
     if (this.detectedFrameworkNames !== null) return this.detectedFrameworkNames;
-    const fileList = files ?? scanDirectory(this.rootDir, this.config);
+    const fileList = files ?? scanDirectory(this.rootDir);
     const context = this.buildDetectionContext(fileList);
     this.detectedFrameworkNames = detectFrameworks(context).map((r) => r.name);
     return this.detectedFrameworkNames;
@@ -534,7 +685,7 @@ export class ExtractionOrchestrator {
       total: 0,
     });
 
-    const files = await scanDirectoryAsync(this.rootDir, this.config, (current, file) => {
+    const files = await scanDirectoryAsync(this.rootDir, (current, file) => {
       onProgress?.({
         phase: 'scanning',
         current,
@@ -802,18 +953,16 @@ export class ExtractionOrchestrator {
           continue;
         }
 
-        // Honour config.maxFileSize. Without this check, vendored
-        // generated headers, minified bundles, and other multi-MB
-        // files get indexed despite the user setting a size cap —
-        // wasting WASM heap and the worker recycle budget on inputs
-        // the user explicitly opted out of. The single-file extractFile
-        // path already enforces this; the bulk path used to silently
-        // skip the check.
-        if (stats.size > this.config.maxFileSize) {
+        // Honour MAX_FILE_SIZE. Without this check, vendored generated
+        // headers, minified bundles, and other multi-MB files get indexed,
+        // wasting WASM heap and the worker recycle budget on inputs with no
+        // useful symbols. The single-file extractFile path already enforces
+        // this; the bulk path used to silently skip the check.
+        if (stats.size > MAX_FILE_SIZE) {
           processed++;
           filesSkipped++;
           errors.push({
-            message: `File exceeds max size (${stats.size} > ${this.config.maxFileSize})`,
+            message: `File exceeds max size (${stats.size} > ${MAX_FILE_SIZE})`,
             filePath,
             severity: 'warning',
             code: 'size_exceeded',
@@ -861,7 +1010,15 @@ export class ExtractionOrchestrator {
         } else if (result.errors.some((e) => e.severity === 'error')) {
           filesErrored++;
         } else {
-          filesSkipped++;
+          // Files with no symbols but no errors (yaml, twig, properties) are
+          // tracked at the file level — count them as indexed so the CLI
+          // doesn't misleadingly report "No files found to index".
+          const lang = detectLanguage(filePath, content);
+          if (isFileLevelOnlyLanguage(lang)) {
+            filesIndexed++;
+          } else {
+            filesSkipped++;
+          }
         }
       }
     }
@@ -1027,7 +1184,12 @@ export class ExtractionOrchestrator {
       } else if (result.errors.some((e) => e.severity === 'error')) {
         filesErrored++;
       } else {
-        filesSkipped++;
+        const tracked = this.queries.getFileByPath(filePath);
+        if (tracked && isFileLevelOnlyLanguage(tracked.language)) {
+          filesIndexed++;
+        } else {
+          filesSkipped++;
+        }
       }
     }
 
@@ -1108,14 +1270,14 @@ export class ExtractionOrchestrator {
     }
 
     // Check file size
-    if (stats.size > this.config.maxFileSize) {
+    if (stats.size > MAX_FILE_SIZE) {
       return {
         nodes: [],
         edges: [],
         unresolvedReferences: [],
         errors: [
           {
-            message: `File exceeds max size (${stats.size} > ${this.config.maxFileSize})`,
+            message: `File exceeds max size (${stats.size} > ${MAX_FILE_SIZE})`,
             filePath: relativePath,
             severity: 'warning',
             code: 'size_exceeded',
@@ -1225,8 +1387,12 @@ export class ExtractionOrchestrator {
   }
 
   /**
-   * Sync with current file state.
-   * Uses git status as a fast path when available, falling back to full scan.
+   * Sync the index with the current file state.
+   *
+   * Change detection is filesystem-based, never git: a (size, mtime) stat
+   * pre-filter skips unchanged files, then a content-hash compare confirms real
+   * changes. This works in non-git projects and catches committed changes from
+   * `git pull`/`checkout`/`merge`/`rebase` that `git status` cannot see.
    */
   async sync(onProgress?: (progress: IndexProgress) => void): Promise<SyncResult> {
     await initGrammars(); // Initialize WASM runtime (grammars loaded lazily below)
@@ -1245,93 +1411,75 @@ export class ExtractionOrchestrator {
     });
 
     const filesToIndex: string[] = [];
-    const gitChanges = getGitChangedFiles(this.rootDir, this.config);
+    // === Filesystem reconcile (git-independent) ===
+    // The source of truth for "what changed" is the filesystem vs the indexed
+    // state — never git. We enumerate the current source files and reconcile
+    // each against the DB. A cheap (size, mtime) stat pre-filter skips unchanged
+    // files without reading or hashing them, so the expensive read+hash+parse
+    // only runs for files that actually changed. This catches edits/adds/deletes
+    // whether or not the project uses git, and crucially also catches committed
+    // changes from `git pull`/`checkout`/`merge`/`rebase` — which `git status`
+    // cannot see, because the working tree is clean afterward.
+    const currentFiles = scanDirectory(this.rootDir);
+    filesChecked = currentFiles.length;
+    const currentSet = new Set(currentFiles);
 
-    if (gitChanges) {
-      // === Git fast path ===
-      // Only inspect the files git reports as changed instead of scanning everything.
-      filesChecked = gitChanges.modified.length + gitChanges.added.length + gitChanges.deleted.length;
+    const trackedFiles = this.queries.getAllFiles();
+    const trackedMap = new Map<string, FileRecord>();
+    for (const f of trackedFiles) {
+      trackedMap.set(f.path, f);
+    }
 
-      // Handle deleted files
-      for (const filePath of gitChanges.deleted) {
-        const tracked = this.queries.getFileByPath(filePath);
-        if (tracked) {
-          this.queries.deleteFile(filePath);
-          filesRemoved++;
-        }
+    // Removals: tracked in the DB but no longer a present source file. Check the
+    // filesystem directly — `scanDirectory` (via `git ls-files`) still lists a
+    // file deleted from disk but not yet staged, so set membership alone misses it.
+    for (const tracked of trackedFiles) {
+      if (!currentSet.has(tracked.path) || !fs.existsSync(path.join(this.rootDir, tracked.path))) {
+        this.queries.deleteFile(tracked.path);
+        filesRemoved++;
       }
+    }
 
-      // Handle modified + added files — read + hash only these. Untracked
-      // (`??`) files stay untracked in git even after we index them, so they
-      // can't be trusted as "new": re-hash and compare against the DB exactly
-      // like modified files. Otherwise every sync re-indexes them and status
-      // reports them as pending forever. (See issue #206.)
-      for (const filePath of [...gitChanges.modified, ...gitChanges.added]) {
-        const fullPath = path.join(this.rootDir, filePath);
-        let content: string;
+    // Adds / modifications.
+    for (const filePath of currentFiles) {
+      const fullPath = path.join(this.rootDir, filePath);
+      const tracked = trackedMap.get(filePath);
+
+      // Cheap pre-filter: an already-indexed file whose size AND mtime both match
+      // the DB is unchanged — skip it without reading or hashing. (A content
+      // change that preserves both exactly is the blind spot every mtime-based
+      // incremental tool accepts; `index --force` is the escape hatch. Git bumps
+      // mtime on every file it writes during checkout/merge, so pulls are caught.)
+      if (tracked) {
         try {
-          content = fs.readFileSync(fullPath, 'utf-8');
+          const stat = fs.statSync(fullPath);
+          if (stat.size === tracked.size && Math.floor(stat.mtimeMs) === Math.floor(tracked.modifiedAt)) {
+            continue;
+          }
         } catch (error) {
-          logDebug('Skipping unreadable file during sync', { filePath, error: String(error) });
+          logDebug('Skipping unstattable file during sync', { filePath, error: String(error) });
           continue;
         }
-
-        const contentHash = hashContent(content);
-        const tracked = this.queries.getFileByPath(filePath);
-
-        if (!tracked) {
-          filesToIndex.push(filePath);
-          changedFilePaths.push(filePath);
-          filesAdded++;
-        } else if (tracked.contentHash !== contentHash) {
-          filesToIndex.push(filePath);
-          changedFilePaths.push(filePath);
-          filesModified++;
-        }
-      }
-    } else {
-      // === Fallback: full scan (non-git project or git failure) ===
-      const currentFiles = new Set(scanDirectory(this.rootDir, this.config));
-      filesChecked = currentFiles.size;
-
-      // Build Map for O(1) lookups instead of .find() per file
-      const trackedFiles = this.queries.getAllFiles();
-      const trackedMap = new Map<string, FileRecord>();
-      for (const f of trackedFiles) {
-        trackedMap.set(f.path, f);
       }
 
-      // Find files to remove (in DB but not on disk)
-      for (const tracked of trackedFiles) {
-        if (!currentFiles.has(tracked.path)) {
-          this.queries.deleteFile(tracked.path);
-          filesRemoved++;
-        }
+      // New, or size/mtime changed — read + hash to confirm a real content change.
+      let content: string;
+      try {
+        content = fs.readFileSync(fullPath, 'utf-8');
+      } catch (error) {
+        logDebug('Skipping unreadable file during sync', { filePath, error: String(error) });
+        continue;
       }
+      const contentHash = hashContent(content);
 
-      // Find files to add or update
-      for (const filePath of currentFiles) {
-        const fullPath = path.join(this.rootDir, filePath);
-        let content: string;
-        try {
-          content = fs.readFileSync(fullPath, 'utf-8');
-        } catch (error) {
-          logDebug('Skipping unreadable file during sync', { filePath, error: String(error) });
-          continue;
-        }
-
-        const contentHash = hashContent(content);
-        const tracked = trackedMap.get(filePath);
-
-        if (!tracked) {
-          filesToIndex.push(filePath);
-          changedFilePaths.push(filePath);
-          filesAdded++;
-        } else if (tracked.contentHash !== contentHash) {
-          filesToIndex.push(filePath);
-          changedFilePaths.push(filePath);
-          filesModified++;
-        }
+      if (!tracked) {
+        filesToIndex.push(filePath);
+        changedFilePaths.push(filePath);
+        filesAdded++;
+      } else if (tracked.contentHash !== contentHash) {
+        filesToIndex.push(filePath);
+        changedFilePaths.push(filePath);
+        filesModified++;
       }
     }
 
@@ -1376,7 +1524,7 @@ export class ExtractionOrchestrator {
    * Uses git status as a fast path when available, falling back to full scan.
    */
   getChangedFiles(): { added: string[]; modified: string[]; removed: string[] } {
-    const gitChanges = getGitChangedFiles(this.rootDir, this.config);
+    const gitChanges = getGitChangedFiles(this.rootDir);
 
     if (gitChanges) {
       // === Git fast path ===
@@ -1420,7 +1568,7 @@ export class ExtractionOrchestrator {
     }
 
     // === Fallback: full scan (non-git project or git failure) ===
-    const currentFiles = new Set(scanDirectory(this.rootDir, this.config));
+    const currentFiles = new Set(scanDirectory(this.rootDir));
     const trackedFiles = this.queries.getAllFiles();
 
     // Build Map for O(1) lookups
@@ -1467,4 +1615,4 @@ export class ExtractionOrchestrator {
 
 // Re-export useful types and functions
 export { extractFromSource } from './tree-sitter';
-export { detectLanguage, isLanguageSupported, isGrammarLoaded, getSupportedLanguages, initGrammars, loadGrammarsForLanguages, loadAllGrammars } from './grammars';
+export { detectLanguage, isSourceFile, isLanguageSupported, isGrammarLoaded, getSupportedLanguages, initGrammars, loadGrammarsForLanguages, loadAllGrammars } from './grammars';
diff --git a/src/extraction/languages/c-cpp.ts b/src/extraction/languages/c-cpp.ts
index 66219d4fa..1365cc24c 100644
--- a/src/extraction/languages/c-cpp.ts
+++ b/src/extraction/languages/c-cpp.ts
@@ -2,6 +2,99 @@ import type { Node as SyntaxNode } from 'web-tree-sitter';
 import { getChildByField, getNodeText } from '../tree-sitter-helpers';
 import type { LanguageExtractor } from '../tree-sitter-types';
 
+/**
+ * Find the function NAME's `qualified_identifier` (`Foo::bar`) inside a
+ * declarator, skipping the `parameter_list` — a parameter with a qualified type
+ * (`const std::string& x`) must NOT be mistaken for the method name. Without the
+ * skip, a plain free function `std::string TableFileName(const std::string&...)`
+ * was named `string` (from the parameter type), so calls to it never resolved
+ * and its file looked like nothing depended on it.
+ */
+function findDeclaratorQualifiedId(declarator: SyntaxNode): SyntaxNode | undefined {
+  const queue: SyntaxNode[] = [declarator];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    if (current.type === 'qualified_identifier') return current;
+    for (let i = 0; i < current.namedChildCount; i++) {
+      const child = current.namedChild(i);
+      // Don't descend into parameters or the trailing return type — their types
+      // (`const std::string&`, `-> std::string`) aren't the function name.
+      if (child && child.type !== 'parameter_list' && child.type !== 'trailing_return_type') {
+        queue.push(child);
+      }
+    }
+  }
+  return undefined;
+}
+
+function extractCppQualifiedMethodName(node: SyntaxNode, source: string): string | undefined {
+  const declarator = getChildByField(node, 'declarator');
+  if (!declarator) return undefined;
+  const qid = findDeclaratorQualifiedId(declarator);
+  if (!qid) return undefined;
+  const parts = getNodeText(qid, source).trim().split('::').filter(Boolean);
+  return parts[parts.length - 1];
+}
+
+function extractCppReceiverType(node: SyntaxNode, source: string): string | undefined {
+  const declarator = getChildByField(node, 'declarator');
+  if (!declarator) return undefined;
+  const qid = findDeclaratorQualifiedId(declarator);
+  if (!qid) return undefined;
+  const parts = getNodeText(qid, source).trim().split('::').filter(Boolean);
+  return parts.length > 1 ? parts.slice(0, -1).join('::') : undefined;
+}
+
+/**
+ * Built-in / non-class return types that can never be a method receiver. We
+ * store no `returnType` for these so resolution never tries to resolve a method
+ * on `void` / `int` / etc.
+ */
+const CPP_NON_CLASS_RETURN = new Set([
+  'void', 'bool', 'char', 'short', 'int', 'long', 'float', 'double', 'unsigned',
+  'signed', 'size_t', 'ssize_t', 'auto', 'wchar_t', 'char8_t', 'char16_t',
+  'char32_t', 'int8_t', 'int16_t', 'int32_t', 'int64_t', 'uint8_t', 'uint16_t',
+  'uint32_t', 'uint64_t', 'intptr_t', 'uintptr_t', 'nullptr_t',
+]);
+
+/**
+ * Normalize a C++ return type to the bare class name a method could be called
+ * on. Unwraps smart-pointer / optional wrappers to their element type
+ * (`std::unique_ptr<Widget>` → `Widget`) so a factory's `->method()` resolves on
+ * the pointee. Strips cv-qualifiers, `&`/`*`, namespace qualifiers, and other
+ * template args. Returns undefined for primitives / void / `auto` / empty.
+ */
+export function normalizeCppReturnType(raw: string): string | undefined {
+  let t = raw.trim();
+  if (!t) return undefined;
+  // Unwrap smart pointers / optional to their pointee (the thing you call `->` on).
+  const wrapper = t.match(/\b(?:std\s*::\s*)?(?:unique_ptr|shared_ptr|weak_ptr|optional)\s*<\s*([^,>]+?)\s*>/);
+  if (wrapper && wrapper[1]) t = wrapper[1];
+  t = t
+    .replace(/\b(?:const|volatile|typename|struct|class|enum)\b/g, ' ')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/[*&]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!t) return undefined;
+  const last = t.split('::').filter(Boolean).pop();
+  if (!last) return undefined;
+  if (CPP_NON_CLASS_RETURN.has(last)) return undefined;
+  if (!/^[A-Za-z_]\w*$/.test(last)) return undefined;
+  return last;
+}
+
+/**
+ * A function/method's return type lives in the `function_definition`'s `type`
+ * field (`Metrics& Metrics::instance()` → `Metrics`). Constructors, destructors,
+ * and conversion operators have no `type` field → undefined.
+ */
+function extractCppReturnType(node: SyntaxNode, source: string): string | undefined {
+  const typeNode = getChildByField(node, 'type');
+  if (!typeNode) return undefined;
+  return normalizeCppReturnType(getNodeText(typeNode, source));
+}
+
 export const cExtractor: LanguageExtractor = {
   functionTypes: ['function_definition'],
   classTypes: [],
@@ -17,6 +110,7 @@ export const cExtractor: LanguageExtractor = {
   nameField: 'declarator',
   bodyField: 'body',
   paramsField: 'parameters',
+  getReturnType: extractCppReturnType,
   resolveTypeAliasKind: (node, _source) => {
     // C typedef: `typedef enum { ... } name;` or `typedef struct { ... } name;`
     // The inner enum_specifier/struct_specifier is anonymous, but we want the typedef name
@@ -62,6 +156,9 @@ export const cppExtractor: LanguageExtractor = {
   nameField: 'declarator',
   bodyField: 'body',
   paramsField: 'parameters',
+  resolveName: extractCppQualifiedMethodName,
+  getReceiverType: extractCppReceiverType,
+  getReturnType: extractCppReturnType,
   getVisibility: (node) => {
     // Check for access specifier in parent
     const parent = node.parent;
diff --git a/src/extraction/languages/csharp.ts b/src/extraction/languages/csharp.ts
index 9de537346..ba5f452ca 100644
--- a/src/extraction/languages/csharp.ts
+++ b/src/extraction/languages/csharp.ts
@@ -2,15 +2,82 @@ import type { Node as SyntaxNode } from 'web-tree-sitter';
 import { getNodeText } from '../tree-sitter-helpers';
 import type { LanguageExtractor } from '../tree-sitter-types';
 
+/**
+ * Blank C# conditional-compilation directive lines (`#if` / `#elif` / `#else` /
+ * `#endif`) before parsing. The vendored tree-sitter-c-sharp grammar mis-parses
+ * a `#if` that appears *inside an enum member list* — the canonical
+ * multi-targeting shape:
+ *
+ *   enum ReadType {
+ *   #if HAVE_DATE_TIME_OFFSET
+ *       ReadAsDateTimeOffset,
+ *   #endif
+ *       ReadAsDouble,
+ *   }
+ *
+ * It emits an ERROR that, for a nested enum, detaches the *enclosing class's*
+ * member list, so most of the class's methods drop out of the index. Removing
+ * the directive lines (keeping the guarded code) sidesteps it. Both branches of
+ * an `#if/#else` are kept — the same behaviour the previous grammar produced,
+ * and the right default for a code graph (index every symbol regardless of
+ * build flags). Replacement preserves byte offsets (directive text → spaces,
+ * newlines kept) so every symbol's line/column stays exact. (#237)
+ */
+export function blankCsharpPreprocessorDirectives(source: string): string {
+  if (source.indexOf('#') === -1) return source;
+  // Conditional-compilation directives only. `#region`/`#pragma`/`#nullable`
+  // parse fine and are left alone. A directive must be the first non-space token
+  // on its line (C# requirement), so anchor to line start.
+  const re = /^([ \t]*)#[ \t]*(if|elif|else|endif)\b[^\n]*/gm;
+  return source.replace(re, (m, indent) => indent + ' '.repeat(m.length - indent.length));
+}
+
+/**
+ * A C# method's declared return type, normalized to the bare class name a chained
+ * `Foo.Create().Bar()` could be called on (the #645/#608 mechanism). The return
+ * type lives in the `returns` field (`static Foo Create()` → `Foo`); built-in
+ * `predefined_type` (void/int/string/…) and arrays yield undefined, generics are
+ * unwrapped to the base type, nullable `Foo?` is stripped, and a dotted namespace
+ * is reduced to the simple name. Constructors have no `returns` field → undefined.
+ */
+function extractCsharpReturnType(node: SyntaxNode, source: string): string | undefined {
+  const typeNode = node.childForFieldName('returns');
+  if (!typeNode) return undefined;
+  if (typeNode.type === 'predefined_type' || typeNode.type === 'array_type') return undefined;
+  let t = getNodeText(typeNode, source).trim();
+  t = t.replace(/\?+$/, ''); // nullable `Foo?`
+  t = t.replace(/<[^>]*>/g, ''); // generics `List<Foo>` → `List`
+  const last = t.split('.').pop()?.trim(); // namespace `Ns.Foo` → `Foo`
+  if (!last || !/^[A-Za-z_]\w*$/.test(last)) return undefined;
+  return last;
+}
+
 export const csharpExtractor: LanguageExtractor = {
+  preParse: blankCsharpPreprocessorDirectives,
   functionTypes: [],
-  classTypes: ['class_declaration'],
+  // Records are first-class type declarations in modern C# (DTOs, value objects,
+  // MediatR/CQRS messages). `record` / `record class` parse as record_declaration
+  // (reference type → class); `record struct` as record_struct_declaration (value
+  // type → struct). Without these, references to a record never resolve (#237).
+  classTypes: ['class_declaration', 'record_declaration'],
   methodTypes: ['method_declaration', 'constructor_declaration'],
   interfaceTypes: ['interface_declaration'],
-  structTypes: ['struct_declaration'],
+  structTypes: ['struct_declaration', 'record_struct_declaration'],
   enumTypes: ['enum_declaration'],
   enumMemberTypes: ['enum_member_declaration'],
   typeAliasTypes: [],
+  // Namespaces qualify type names so same-named types in different namespaces are
+  // distinguishable (e.g. `ApplicationCore.Entities.CatalogBrand` vs
+  // `BlazorShared.Models.CatalogBrand`). Both block (`namespace Foo { … }`, which
+  // nests its types) and file-scoped (`namespace Foo;`) forms — extractFilePackage
+  // pushes the namespace onto the scope so nested/top-level types pick it up.
+  packageTypes: ['namespace_declaration', 'file_scoped_namespace_declaration'],
+  extractPackage: (node: SyntaxNode, source: string) => {
+    const name =
+      node.childForFieldName('name') ??
+      node.namedChildren.find((c: SyntaxNode) => c.type === 'qualified_name' || c.type === 'identifier');
+    return name ? getNodeText(name, source) : null;
+  },
   importTypes: ['using_directive'],
   callTypes: ['invocation_expression'],
   variableTypes: ['local_declaration_statement'],
@@ -18,7 +85,9 @@ export const csharpExtractor: LanguageExtractor = {
   propertyTypes: ['property_declaration'],
   nameField: 'name',
   bodyField: 'body',
-  paramsField: 'parameter_list',
+  paramsField: 'parameters',
+  returnField: 'type',
+  getReturnType: extractCsharpReturnType,
   getVisibility: (node) => {
     for (let i = 0; i < node.childCount; i++) {
       const child = node.child(i);
diff --git a/src/extraction/languages/dart.ts b/src/extraction/languages/dart.ts
index 5b545d048..bd8797c7c 100644
--- a/src/extraction/languages/dart.ts
+++ b/src/extraction/languages/dart.ts
@@ -2,10 +2,128 @@ import type { Node as SyntaxNode } from 'web-tree-sitter';
 import { getNodeText } from '../tree-sitter-helpers';
 import type { LanguageExtractor } from '../tree-sitter-types';
 
+/**
+ * The `function_signature` carrying a method's return type — unwrapped from a
+ * `method_signature` wrapper (Dart nests the signature one level for methods).
+ */
+function dartInnerSignature(node: SyntaxNode): SyntaxNode {
+  if (node.type === 'method_signature') {
+    const inner = node.namedChildren.find((c: SyntaxNode) =>
+      c.type === 'function_signature' || c.type === 'getter_signature' || c.type === 'setter_signature'
+    );
+    if (inner) return inner;
+  }
+  return node;
+}
+
+/**
+ * The factory/named-constructor signature inside a node, if any. A constructor
+ * parses as `method_signature > {factory_,}constructor_signature` (e.g.
+ * `factory Foo.create()` or `Foo._()`), whose children are the class identifier
+ * and — for a named ctor — the constructor-name identifier.
+ */
+function dartConstructorSignature(node: SyntaxNode): SyntaxNode | undefined {
+  if (node.type === 'factory_constructor_signature' || node.type === 'constructor_signature') {
+    return node;
+  }
+  if (node.type === 'method_signature') {
+    return node.namedChildren.find((c: SyntaxNode) =>
+      c.type === 'factory_constructor_signature' || c.type === 'constructor_signature'
+    );
+  }
+  return undefined;
+}
+
+/** The name of the class/mixin/extension/enum lexically enclosing `node`. */
+function dartEnclosingTypeName(node: SyntaxNode): string | undefined {
+  let p = node.parent;
+  while (p) {
+    if (
+      p.type === 'class_definition' || p.type === 'mixin_declaration' ||
+      p.type === 'extension_declaration' || p.type === 'enum_declaration'
+    ) {
+      return p.childForFieldName('name')?.text;
+    }
+    p = p.parent;
+  }
+  return undefined;
+}
+
+/**
+ * Validated constructor info for `node`, or undefined if it isn't genuinely a
+ * constructor. A constructor signature is structurally `<Class>` or
+ * `<Class>.<name>`, but tree-sitter-dart MISPARSES `@override (T) m()` — the
+ * annotation swallows the record return type `(T)`, leaving `m()` looking like a
+ * single-identifier constructor_signature. We disambiguate by the class name:
+ * a real ctor's class identifier matches the enclosing type; a misparsed method
+ * (`reduce` inside class `Action`) doesn't, and is treated as the method it is.
+ */
+function dartCtorInfo(node: SyntaxNode): { className: string; ctorName: string } | undefined {
+  const ctor = dartConstructorSignature(node);
+  if (!ctor) return undefined;
+  const ids = ctor.namedChildren.filter((c: SyntaxNode) => c.type === 'identifier');
+  const className = dartEnclosingTypeName(node);
+  if (!className || !ids[0]) return undefined;
+  if (ids[0].text !== className) return undefined; // misparsed method, not a ctor
+  // `<Class>.<name>` is a named ctor; bare `<Class>` is the unnamed ctor.
+  return { className, ctorName: ids[1]?.text ?? className };
+}
+
+/**
+ * Capture a Dart method/function's declared return type as a bare type name, for
+ * the chained static-factory / fluent call mechanism (#750). `Bar makeBar()`
+ * yields `Bar`; a generic `List<Foo>` yields its container `List` (the method is
+ * on the container, not the element); a prefixed `prefix.Bar` yields `Bar`. A
+ * factory / named constructor returns its enclosing class implicitly, so its
+ * "return type" is the class.
+ */
+function extractDartReturnType(node: SyntaxNode, source: string): string | undefined {
+  const ctor = dartCtorInfo(node);
+  if (ctor) return ctor.className;
+  const sig = dartInnerSignature(node);
+  // The return type precedes the method name; it's the first type_identifier
+  // (generic args sit in a sibling `type_arguments`, so this is the container).
+  const retType = sig.namedChildren.find((c: SyntaxNode) => c.type === 'type_identifier');
+  if (!retType) return undefined;
+  const text = getNodeText(retType, source).replace(/<[^>]*>/g, '').trim();
+  const last = text.split('.').pop(); // prefixed `p.Bar` → `Bar`
+  if (!last || !/^[A-Za-z_]\w*$/.test(last)) return undefined;
+  return last;
+}
+
+/**
+ * The callee name of the Dart call whose `argument_part` selector is `argPart`
+ * — mirrors the main extractBareCall accessor logic so a chained receiver
+ * (`Foo.create()` in `Foo.create().bar()`) can be reconstructed. Returns
+ * `Foo.create`, a bare `create`, or `Foo` (constructor) — or undefined.
+ */
+function dartCalleeOfArgPart(argPart: SyntaxNode): string | undefined {
+  const prev = argPart.previousNamedSibling;
+  if (!prev) return undefined;
+  if (prev.type === 'identifier') return prev.text; // bare `Foo()` / `create()`
+  if (prev.type === 'selector') {
+    const accessor = prev.namedChildren.find((c: SyntaxNode) =>
+      c.type === 'unconditional_assignable_selector' || c.type === 'conditional_assignable_selector'
+    );
+    const methodId = accessor?.namedChildren.find((c: SyntaxNode) => c.type === 'identifier');
+    if (methodId) {
+      const accessorPrev = prev.previousNamedSibling;
+      if (accessorPrev?.type === 'identifier') return accessorPrev.text + '.' + methodId.text;
+      return methodId.text;
+    }
+  }
+  return undefined;
+}
+
 export const dartExtractor: LanguageExtractor = {
   functionTypes: ['function_signature'],
   classTypes: ['class_definition'],
-  methodTypes: ['method_signature'],
+  // `method_signature` covers regular methods AND factory constructors (which
+  // parse as method_signature > factory_constructor_signature). A plain named
+  // constructor `Foo._()` parses as a bare `constructor_signature`, so include
+  // it too — resolveName names it by the ctor name and getReturnType gives it
+  // the class as its return type, so `Foo._().bar()` chains resolve (#750).
+  methodTypes: ['method_signature', 'constructor_signature'],
   interfaceTypes: [],
   structTypes: [],
   enumTypes: ['enum_declaration'],
@@ -33,6 +151,19 @@ export const dartExtractor: LanguageExtractor = {
   bodyField: 'body', // class_definition uses 'body' field
   paramsField: 'formal_parameter_list',
   returnField: 'type',
+  getReturnType: extractDartReturnType,
+  isMisparsedFunction: (_name, node) => {
+    // Skip the UNNAMED constructor `Foo()` (its ctor name equals the class). It's
+    // ordinary construction — an `instantiates` edge to the class `Foo` — so
+    // extracting it as a `Foo::Foo` method node would hijack instantiation
+    // resolution (a `Foo(...)` call would resolve to the ctor method, not the
+    // class). NAMED ctors `Foo.create()` / `Foo._()` ARE kept so their chains
+    // resolve (#750). dartCtorInfo validates against the class name, so a method
+    // tree-sitter misparsed as a ctor (`@override (T) m()`) is NOT skipped here.
+    // (isMisparsedFunction skips node creation but still visits the body.)
+    const ctor = dartCtorInfo(node);
+    return ctor != null && ctor.ctorName === ctor.className;
+  },
   getSignature: (node, source) => {
     // For function_signature: extract params + return type
     // For method_signature: delegate to inner function_signature
@@ -88,6 +219,23 @@ export const dartExtractor: LanguageExtractor = {
     }
     return false;
   },
+  resolveName: (node) => {
+    // Name a factory / named constructor by its constructor name — the 2nd
+    // identifier (`create` in `factory Foo.create()`, `_` in `Foo._()`) — not
+    // the class, so a call `Foo.create()` resolves to `Foo::create` (#750). The
+    // default Dart naming returns the FIRST identifier (the class), which
+    // collides every named ctor onto `Foo::Foo` and leaves `Foo.create()`
+    // unresolvable. An unnamed ctor `Foo()` has a single identifier — fall
+    // through (undefined) to the default class name. Letting the core's
+    // extractMethod own the factory (rather than a custom visitNode) keeps the
+    // body attribution intact: calls inside `factory Foo.create() { … }` are
+    // attributed to `Foo::create`, and getReturnType gives it return type Foo.
+    const ctor = dartCtorInfo(node);
+    // A named ctor `Foo.create` → `create`; the unnamed ctor `Foo()` → undefined
+    // (default naming gives the class name `Foo`, which is correct).
+    if (ctor && ctor.ctorName !== ctor.className) return ctor.ctorName;
+    return undefined;
+  },
   extractImport: (node, source) => {
     const importText = source.substring(node.startIndex, node.endIndex).trim();
     let moduleName = '';
@@ -160,6 +308,21 @@ export const dartExtractor: LanguageExtractor = {
             if (accessorPrev?.type === 'identifier') {
               return accessorPrev.text + '.' + methodId.text;
             }
+            // Chained static-factory / fluent call: the receiver is itself a call
+            // (`Foo.create().bar()`), so accessorPrev is that call's argument_part
+            // selector. Encode `<innerCallee>().<method>` so resolution can infer
+            // bar's class from what `Foo.create` RETURNS (#645/#608 mechanism) —
+            // but only when the chain starts with a capitalized type (a companion
+            // factory / static method / constructor); an instance chain
+            // (`obj.foo().bar()`) keeps the bare name (its receiver's type can't
+            // be recovered here).
+            if (accessorPrev?.type === 'selector' &&
+                accessorPrev.namedChildren.some((c: SyntaxNode) => c.type === 'argument_part')) {
+              const innerCallee = dartCalleeOfArgPart(accessorPrev);
+              if (innerCallee && /^[A-Z]/.test(innerCallee)) {
+                return `${innerCallee}().${methodId.text}`;
+              }
+            }
             return methodId.text;
           }
         }
diff --git a/src/extraction/languages/go.ts b/src/extraction/languages/go.ts
index 898e61651..5e41fbfaa 100644
--- a/src/extraction/languages/go.ts
+++ b/src/extraction/languages/go.ts
@@ -1,6 +1,43 @@
+import type { Node as SyntaxNode } from 'web-tree-sitter';
 import { getNodeText, getChildByField } from '../tree-sitter-helpers';
 import type { LanguageExtractor } from '../tree-sitter-types';
 
+/**
+ * A Go function's declared return type, normalized to the bare type a chained
+ * `New().Method()` could be called on (the #645/#608 mechanism). Reads the
+ * `result` field: a pointer `*Foo` is unwrapped to `Foo`, a multi-return
+ * `(*Foo, error)` takes the first result (the idiomatic value-or-error shape),
+ * a qualified `pkg.Foo` reduces to its last segment, and generics to the base.
+ * Built-ins / unnamed results simply fail the later existence check.
+ */
+function extractGoReturnType(node: SyntaxNode, source: string): string | undefined {
+  let result = getChildByField(node, 'result');
+  if (!result) return undefined;
+  // Multi-return `(T, error)` → the first result's type.
+  if (result.type === 'parameter_list') {
+    const first = result.namedChildren.find((c: SyntaxNode) => c.type === 'parameter_declaration');
+    if (!first) return undefined;
+    result = getChildByField(first, 'type') ?? first;
+  }
+  // Unwrap a pointer `*Foo` → `Foo`.
+  if (result?.type === 'pointer_type') {
+    result =
+      result.namedChildren.find(
+        (c: SyntaxNode) =>
+          c.type === 'type_identifier' || c.type === 'qualified_type' || c.type === 'generic_type',
+      ) ?? result;
+  }
+  if (!result) return undefined;
+  const text = getNodeText(result, source)
+    .trim()
+    .replace(/^\*/, '')
+    .replace(/<[^>]*>/g, '')
+    .replace(/\[[^\]]*\]/g, ''); // strip generic args `Foo[T]`
+  const last = text.split('.').pop()?.trim(); // qualified `pkg.Foo` → `Foo`
+  if (!last || !/^[A-Za-z_]\w*$/.test(last)) return undefined;
+  return last;
+}
+
 export const goExtractor: LanguageExtractor = {
   functionTypes: ['function_declaration'],
   classTypes: [], // Go doesn't have classes
@@ -17,6 +54,7 @@ export const goExtractor: LanguageExtractor = {
   bodyField: 'body',
   paramsField: 'parameters',
   returnField: 'result',
+  getReturnType: extractGoReturnType,
   getSignature: (node, source) => {
     const params = getChildByField(node, 'parameters');
     const result = getChildByField(node, 'result');
@@ -36,6 +74,18 @@ export const goExtractor: LanguageExtractor = {
     if (typeChild.type === 'interface_type') return 'interface';
     return undefined;
   },
+  isExported: (node, source) => {
+    // Go: a symbol is exported when its identifier starts with an uppercase letter.
+    // Look at the `name` field directly (works for function_declaration,
+    // method_declaration, type_spec, and var_spec / const_spec via extractor flow).
+    const nameNode = getChildByField(node, 'name');
+    if (nameNode) {
+      const text = getNodeText(nameNode, source);
+      const first = text.charCodeAt(0);
+      return first >= 65 && first <= 90; // A-Z
+    }
+    return false;
+  },
   getReceiverType: (node, source) => {
     // Go method_declaration has a "receiver" field: func (sl *scrapeLoop) run(...)
     // The receiver is a parameter_list containing a parameter_declaration
@@ -44,8 +94,12 @@ export const goExtractor: LanguageExtractor = {
     if (!receiver) return undefined;
     // Find the type identifier inside the receiver
     const text = getNodeText(receiver, source);
-    // Extract type name from patterns like "(sl *Type)", "(sl Type)", "(*Type)", "(Type)"
-    const match = text.match(/\*?\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)/);
+    // Extract type name from "(sl *Type)", "(sl Type)", "(*Type)", "(Type)" and
+    // generic receivers "(s *Stack[T])". Anchor on the opening "(" and skip an
+    // optional receiver var name; the old `name)`-anchored pattern never matched
+    // the `[T])` suffix, so generic-type methods were orphaned from their type
+    // (no struct→method `contains` edge). (#583)
+    const match = text.match(/\(\s*(?:[A-Za-z_]\w*\s+)?\*?\s*([A-Za-z_]\w*)/);
     return match?.[1];
   },
 };
diff --git a/src/extraction/languages/index.ts b/src/extraction/languages/index.ts
index a289f0289..543598b8e 100644
--- a/src/extraction/languages/index.ts
+++ b/src/extraction/languages/index.ts
@@ -25,6 +25,7 @@ import { pascalExtractor } from './pascal';
 import { scalaExtractor } from './scala';
 import { luaExtractor } from './lua';
 import { luauExtractor } from './luau';
+import { objcExtractor } from './objc';
 
 export const EXTRACTORS: Partial<Record<Language, LanguageExtractor>> = {
   typescript: typescriptExtractor,
@@ -47,4 +48,5 @@ export const EXTRACTORS: Partial<Record<Language, LanguageExtractor>> = {
   scala: scalaExtractor,
   lua: luaExtractor,
   luau: luauExtractor,
+  objc: objcExtractor,
 };
diff --git a/src/extraction/languages/java.ts b/src/extraction/languages/java.ts
index 638533f0d..3d3ecaa4d 100644
--- a/src/extraction/languages/java.ts
+++ b/src/extraction/languages/java.ts
@@ -2,11 +2,49 @@ import type { Node as SyntaxNode } from 'web-tree-sitter';
 import { getNodeText, getChildByField } from '../tree-sitter-helpers';
 import type { LanguageExtractor } from '../tree-sitter-types';
 
+/**
+ * Tree-sitter-java node types for a method's `type` (return) field that can
+ * never be a method receiver — there's no class to chain a `.method()` on, so we
+ * store no `returnType` for them.
+ */
+const JAVA_NON_CLASS_RETURN_NODES = new Set([
+  'void_type',
+  'integral_type', // int, long, short, byte, char
+  'floating_point_type', // float, double
+  'boolean_type',
+]);
+
+/**
+ * A Java method's declared return type, normalized to the bare class name a
+ * chained `Foo.getInstance().bar()` could be called on (the #645/#608 mechanism).
+ * Reads the `type` field: primitives/void/arrays yield undefined (no class to
+ * chain on), `List<Foo>` is unwrapped to its base type `List`, and a dotted
+ * package/outer-class qualifier (`java.util.List`) is stripped to the simple
+ * name. Constructors have no `type` field → undefined.
+ */
+function extractJavaReturnType(node: SyntaxNode, source: string): string | undefined {
+  const typeNode = getChildByField(node, 'type');
+  if (!typeNode) return undefined;
+  if (JAVA_NON_CLASS_RETURN_NODES.has(typeNode.type)) return undefined;
+  // An array return (`Foo[]`) isn't a receiver you call instance methods on.
+  if (typeNode.type === 'array_type') return undefined;
+  // Strip type arguments (`List<Foo>` → `List`) — the chain resolves on the base.
+  const raw = getNodeText(typeNode, source).trim().replace(/<[^>]*>/g, '');
+  // Strip a dotted package / outer-class qualifier (`java.util.List` → `List`).
+  const last = raw.split('.').pop()?.trim();
+  if (!last || !/^[A-Za-z_]\w*$/.test(last)) return undefined;
+  return last;
+}
+
 export const javaExtractor: LanguageExtractor = {
   functionTypes: [],
   classTypes: ['class_declaration'],
   methodTypes: ['method_declaration', 'constructor_declaration'],
-  interfaceTypes: ['interface_declaration'],
+  // `annotation_type_declaration` is `@interface Foo { … }` — an annotation
+  // definition. Without it, annotation types (`@SerializedName`, `@GetMapping`,
+  // JPA/Spring annotations) aren't nodes, so the `@Foo` usages that DO get
+  // extracted can't resolve and the annotation file shows zero dependents.
+  interfaceTypes: ['interface_declaration', 'annotation_type_declaration'],
   structTypes: [],
   enumTypes: ['enum_declaration'],
   enumMemberTypes: ['enum_constant'],
@@ -19,6 +57,7 @@ export const javaExtractor: LanguageExtractor = {
   bodyField: 'body',
   paramsField: 'parameters',
   returnField: 'type',
+  getReturnType: extractJavaReturnType,
   getSignature: (node, source) => {
     const params = getChildByField(node, 'parameters');
     const returnType = getChildByField(node, 'type');
@@ -56,4 +95,12 @@ export const javaExtractor: LanguageExtractor = {
     }
     return null;
   },
+  packageTypes: ['package_declaration'],
+  extractPackage: (node, source) => {
+    // package_declaration → scoped_identifier or identifier (single-segment)
+    const id = node.namedChildren.find(
+      (c: SyntaxNode) => c.type === 'scoped_identifier' || c.type === 'identifier'
+    );
+    return id ? source.substring(id.startIndex, id.endIndex).trim() : null;
+  },
 };
diff --git a/src/extraction/languages/javascript.ts b/src/extraction/languages/javascript.ts
index 0a0d67808..3b36348b3 100644
--- a/src/extraction/languages/javascript.ts
+++ b/src/extraction/languages/javascript.ts
@@ -1,10 +1,14 @@
 import { getNodeText, getChildByField } from '../tree-sitter-helpers';
 import type { LanguageExtractor } from '../tree-sitter-types';
+import { classifyTsClassMember } from './typescript';
 
 export const javascriptExtractor: LanguageExtractor = {
   functionTypes: ['function_declaration', 'arrow_function', 'function_expression'],
   classTypes: ['class_declaration'],
   methodTypes: ['method_definition', 'field_definition'],
+  // JS `field_definition` ≙ TS `public_field_definition`: plain fields are
+  // properties, function-valued fields are methods (#808).
+  classifyMethodNode: classifyTsClassMember,
   interfaceTypes: [],
   structTypes: [],
   enumTypes: [],
@@ -13,6 +17,17 @@ export const javascriptExtractor: LanguageExtractor = {
   callTypes: ['call_expression'],
   variableTypes: ['lexical_declaration', 'variable_declaration'],
   nameField: 'name',
+  // JS `field_definition` names its key the `property` field (TS's
+  // public_field_definition uses `name`). Without this, JS class fields —
+  // including arrow-function handler fields — extracted no name and produced
+  // no node at all (#808).
+  resolveName: (node, source) => {
+    if (node.type === 'field_definition') {
+      const prop = getChildByField(node, 'property');
+      if (prop) return getNodeText(prop, source);
+    }
+    return undefined;
+  },
   bodyField: 'body',
   resolveBody: (node, bodyField) => {
     // field_definition (arrow function class fields) nest the body inside
diff --git a/src/extraction/languages/kotlin.ts b/src/extraction/languages/kotlin.ts
index 19c386242..55ad883de 100644
--- a/src/extraction/languages/kotlin.ts
+++ b/src/extraction/languages/kotlin.ts
@@ -2,6 +2,46 @@ import type { Node as SyntaxNode } from 'web-tree-sitter';
 import { getNodeText, getChildByField } from '../tree-sitter-helpers';
 import type { LanguageExtractor } from '../tree-sitter-types';
 
+/** Kotlin return types that can't be a chained-call receiver (no class to chain on). */
+const KOTLIN_NON_CLASS_RETURN = new Set(['Unit', 'Nothing']);
+
+/**
+ * A Kotlin function's declared return type, normalized to the bare class name a
+ * chained `Foo.getInstance().bar()` could be called on (the #645/#608 mechanism).
+ * tree-sitter-kotlin exposes no field names, so the return type is found
+ * positionally: the first `user_type` / `nullable_type` that FOLLOWS
+ * `function_value_parameters` (an extension receiver's type sits before the
+ * params, so it's never mistaken for the return). An inferred return (expression
+ * body with no `: Type`), a lambda return type, or `Unit` / `Nothing` → undefined.
+ */
+function extractKotlinReturnType(node: SyntaxNode, source: string): string | undefined {
+  let seenParams = false;
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (!child) continue;
+    if (child.type === 'function_value_parameters') {
+      seenParams = true;
+      continue;
+    }
+    if (!seenParams) continue;
+    // The return type is the type node right after the params. If we reach the
+    // body or a `where`-clause first, there's no declared return type.
+    if (child.type === 'function_body' || child.type === 'type_constraints') return undefined;
+    if (child.type === 'user_type' || child.type === 'nullable_type') {
+      const ut =
+        child.type === 'nullable_type'
+          ? (child.namedChildren.find((c: SyntaxNode) => c.type === 'user_type') ?? child)
+          : child;
+      const typeId = ut.namedChildren.find((c: SyntaxNode) => c.type === 'type_identifier');
+      const name = getNodeText(typeId ?? ut, source).trim();
+      if (!name || !/^[A-Za-z_]\w*$/.test(name)) return undefined;
+      if (KOTLIN_NON_CLASS_RETURN.has(name)) return undefined;
+      return name;
+    }
+  }
+  return undefined;
+}
+
 /** Check if a node matches the `fun interface` misparse pattern */
 function isFunInterfaceNode(node: SyntaxNode): boolean {
   let hasFun = false;
@@ -130,6 +170,7 @@ export const kotlinExtractor: LanguageExtractor = {
   },
   paramsField: 'function_value_parameters',
   returnField: 'type',
+  getReturnType: extractKotlinReturnType,
   resolveBody: (node, _bodyField) => {
     // Kotlin's tree-sitter grammar doesn't use field names, so getChildByField fails.
     // Find body by type: function_body for functions/methods, class_body for classes,
@@ -227,6 +268,29 @@ export const kotlinExtractor: LanguageExtractor = {
     }
     return false;
   },
+  extractModifiers: (node) => {
+    // Kotlin Multiplatform `expect`/`actual` markers live in
+    //   modifiers > platform_modifier > (expect | actual)
+    // Capturing them lets the resolver link an `expect` declaration in a
+    // common source set to its `actual` implementations in platform source
+    // sets (those impls otherwise have zero dependents — the caller resolves
+    // to the `expect`). Match the AST node, not raw text, so an annotation
+    // argument or identifier named "actual" can't false-positive.
+    const mods: string[] = [];
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child?.type !== 'modifiers') continue;
+      for (let j = 0; j < child.childCount; j++) {
+        const pm = child.child(j);
+        if (pm?.type !== 'platform_modifier') continue;
+        for (let k = 0; k < pm.childCount; k++) {
+          const kw = pm.child(k);
+          if (kw && (kw.type === 'expect' || kw.type === 'actual')) mods.push(kw.type);
+        }
+      }
+    }
+    return mods.length > 0 ? mods : undefined;
+  },
   extractImport: (node, source) => {
     const importText = source.substring(node.startIndex, node.endIndex).trim();
     const identifier = node.namedChildren.find((c: SyntaxNode) => c.type === 'identifier');
@@ -235,4 +299,10 @@ export const kotlinExtractor: LanguageExtractor = {
     }
     return null;
   },
+  packageTypes: ['package_header'],
+  extractPackage: (node, source) => {
+    // package_header → identifier (dotted: `com.example.foo`)
+    const id = node.namedChildren.find((c: SyntaxNode) => c.type === 'identifier');
+    return id ? source.substring(id.startIndex, id.endIndex).trim() : null;
+  },
 };
diff --git a/src/extraction/languages/objc.ts b/src/extraction/languages/objc.ts
new file mode 100644
index 000000000..cf5ecc4d7
--- /dev/null
+++ b/src/extraction/languages/objc.ts
@@ -0,0 +1,177 @@
+import type { Node as SyntaxNode } from 'web-tree-sitter';
+import { getChildByField, getNodeText } from '../tree-sitter-helpers';
+import type { ExtractorContext, LanguageExtractor } from '../tree-sitter-types';
+
+function findCompoundStatement(node: SyntaxNode): SyntaxNode | null {
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child?.type === 'compound_statement') {
+      return child;
+    }
+  }
+  return null;
+}
+
+/** Build ObjC selector: `greet`, `doThing:`, or `doThing:with:`. */
+function extractObjcMethodName(node: SyntaxNode, source: string): string | undefined {
+  if (node.type !== 'method_definition' && node.type !== 'method_declaration') {
+    return undefined;
+  }
+
+  const identifiers = node.namedChildren.filter((c) => c.type === 'identifier');
+  if (identifiers.length === 0) return undefined;
+
+  const hasParameters = node.namedChildren.some((c) => c.type === 'method_parameter');
+  const firstIdentifier = identifiers[0];
+  if (!firstIdentifier) return undefined;
+  if (!hasParameters) {
+    return getNodeText(firstIdentifier, source);
+  }
+
+  return identifiers.map((id) => `${getNodeText(id, source)}:`).join('');
+}
+
+/** Nullability / ARC qualifiers that sit where a return type's first type
+ *  identifier does (`(nonnull instancetype)`, `(nullable Bar *)`) — never the type. */
+const OBJC_TYPE_QUALIFIERS = new Set([
+  'nonnull', 'nullable', 'null_unspecified', 'null_resettable',
+  '_Nonnull', '_Nullable', '_Null_unspecified', '__nonnull', '__nullable',
+  'const', 'volatile', 'strong', 'weak', 'copy', 'assign', 'retain', 'oneway',
+  '__strong', '__weak', '__unsafe_unretained', '__autoreleasing', '__kindof',
+]);
+
+/** Collect the type identifiers under a `method_type`, in document order. */
+function collectTypeIdentifiers(node: SyntaxNode, source: string, out: string[]): void {
+  if (node.type === 'type_identifier') out.push(getNodeText(node, source).trim());
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (child) collectTypeIdentifiers(child, source, out);
+  }
+}
+
+/**
+ * Capture an ObjC method's declared return type as a bare class name, for the
+ * chained static-factory call mechanism (#750). `+ (Bar *)create` yields `Bar`;
+ * a nullability/ARC qualifier (`(nonnull instancetype)`, `(nullable Bar *)`) is
+ * skipped to reach the real type. `void` / `id` / `instancetype` / primitives
+ * yield undefined — for a class-message factory that means the receiver's type
+ * is the class itself (handled in resolution), so `[[X alloc] init]` and
+ * singleton chains still resolve.
+ */
+function extractObjcReturnType(node: SyntaxNode, source: string): string | undefined {
+  if (node.type !== 'method_definition' && node.type !== 'method_declaration') return undefined;
+  const methodType = node.namedChildren.find((c) => c.type === 'method_type');
+  if (!methodType) return undefined;
+  const ids: string[] = [];
+  collectTypeIdentifiers(methodType, source, ids);
+  const name = ids.find((n) => !OBJC_TYPE_QUALIFIERS.has(n));
+  if (!name || !/^[A-Za-z_]\w*$/.test(name) || name === 'void' || name === 'id' || name === 'instancetype') {
+    return undefined;
+  }
+  return name;
+}
+
+function extractObjcPropertyName(node: SyntaxNode, source: string): string | null {
+  if (node.type !== 'property_declaration') return null;
+
+  const structDecl = node.namedChildren.find((c) => c.type === 'struct_declaration');
+  if (!structDecl) return null;
+
+  const structDeclarator = structDecl.namedChildren.find((c) => c.type === 'struct_declarator');
+  if (!structDeclarator) return null;
+
+  let current: SyntaxNode | null = structDeclarator;
+  while (current) {
+    const inner: SyntaxNode | undefined =
+      getChildByField(current, 'declarator') ||
+      current.namedChildren.find((c) => c.type === 'identifier' || c.type === 'pointer_declarator');
+    if (!inner) break;
+    if (inner.type === 'identifier') {
+      return getNodeText(inner, source);
+    }
+    current = inner;
+  }
+
+  return null;
+}
+
+export const objcExtractor: LanguageExtractor = {
+  functionTypes: ['function_definition'],
+  // Only @interface emits a class node; @implementation reuses it via visitNode.
+  classTypes: ['class_interface'],
+  methodTypes: ['method_definition'],
+  interfaceTypes: ['protocol_declaration'],
+  interfaceKind: 'protocol',
+  structTypes: ['struct_specifier'],
+  enumTypes: ['enum_specifier'],
+  enumMemberTypes: ['enumerator'],
+  typeAliasTypes: ['type_definition'],
+  importTypes: ['preproc_include'],
+  callTypes: ['call_expression', 'message_expression'],
+  variableTypes: ['declaration'],
+  propertyTypes: ['property_declaration'],
+  nameField: 'declarator',
+  bodyField: 'body',
+  paramsField: 'parameters',
+  getReturnType: extractObjcReturnType,
+  resolveName: extractObjcMethodName,
+  extractPropertyName: extractObjcPropertyName,
+  resolveBody: (node, bodyField) => {
+    const fromField = getChildByField(node, bodyField);
+    if (fromField) {
+      return fromField;
+    }
+    return findCompoundStatement(node);
+  },
+  resolveTypeAliasKind: (node, _source) => {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (!child) continue;
+      if (child.type === 'enum_specifier' && getChildByField(child, 'body')) return 'enum';
+      if (child.type === 'struct_specifier' && getChildByField(child, 'body')) return 'struct';
+    }
+    return undefined;
+  },
+  isStatic: (node) => /^\s*\+/.test(node.text),
+  visitNode: (node, ctx: ExtractorContext) => {
+    if (node.type !== 'class_implementation') return false;
+
+    const classNameNode = node.namedChildren.find((c) => c.type === 'identifier');
+    if (!classNameNode) return true;
+
+    const className = getNodeText(classNameNode, ctx.source);
+    const classNode =
+      ctx.nodes.find(
+        (n) => n.name === className && n.filePath === ctx.filePath && n.kind === 'class'
+      ) ?? ctx.createNode('class', className, node, {});
+    if (!classNode) return true;
+
+    ctx.pushScope(classNode.id);
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child?.type === 'implementation_definition') {
+        for (let j = 0; j < child.namedChildCount; j++) {
+          const implChild = child.namedChild(j);
+          if (implChild) ctx.visitNode(implChild);
+        }
+      }
+    }
+    ctx.popScope();
+    return true;
+  },
+  extractImport: (node, source) => {
+    const importText = source.substring(node.startIndex, node.endIndex).trim();
+    const systemLib = node.namedChildren.find((c: SyntaxNode) => c.type === 'system_lib_string');
+    if (systemLib) {
+      return { moduleName: getNodeText(systemLib, source).replace(/^<|>$/g, ''), signature: importText };
+    }
+    const stringLiteral = node.namedChildren.find((c: SyntaxNode) => c.type === 'string_literal');
+    if (stringLiteral) {
+      const stringContent = stringLiteral.namedChildren.find((c: SyntaxNode) => c.type === 'string_content');
+      if (stringContent) {
+        return { moduleName: getNodeText(stringContent, source), signature: importText };
+      }
+    }
+    return null;
+  },
+};
diff --git a/src/extraction/languages/pascal.ts b/src/extraction/languages/pascal.ts
index aed6a59fe..004dadc83 100644
--- a/src/extraction/languages/pascal.ts
+++ b/src/extraction/languages/pascal.ts
@@ -17,6 +17,16 @@ export const pascalExtractor: LanguageExtractor = {
   bodyField: 'body',
   paramsField: 'args',
   returnField: 'type',
+  // Pascal/Delphi `function GetInstance: TBar` — the return type is a `typeref`
+  // child. Capture its bare class name for the chained static-factory call
+  // mechanism (#750). A procedure (no return) has no typeref → undefined.
+  getReturnType: (node, source) => {
+    const typeref = node.namedChildren.find((c: SyntaxNode) => c.type === 'typeref');
+    if (!typeref) return undefined;
+    const id = typeref.namedChildren.find((c: SyntaxNode) => c.type === 'identifier') ?? typeref;
+    const name = getNodeText(id, source).trim();
+    return /^[A-Za-z_]\w*$/.test(name) ? name : undefined;
+  },
   getSignature: (node, source) => {
     const args = getChildByField(node, 'args');
     const returnType = node.namedChildren.find(
diff --git a/src/extraction/languages/php.ts b/src/extraction/languages/php.ts
index 1133f9797..e6c1ce1b0 100644
--- a/src/extraction/languages/php.ts
+++ b/src/extraction/languages/php.ts
@@ -1,7 +1,70 @@
 import type { Node as SyntaxNode } from 'web-tree-sitter';
-import { getNodeText } from '../tree-sitter-helpers';
+import { getNodeText, getChildByField } from '../tree-sitter-helpers';
 import type { LanguageExtractor } from '../tree-sitter-types';
 
+// include / require (+ _once) expression node types. These carry the
+// file→file dependency in procedural PHP, where `include`/`require` — not
+// namespace `use` — is how a file pulls in another (issue #660).
+const PHP_INCLUDE_TYPES = new Set([
+  'include_expression',
+  'include_once_expression',
+  'require_expression',
+  'require_once_expression',
+]);
+
+/**
+ * Extract a static string-literal path from a PHP include/require expression.
+ *
+ * Returns null for dynamic forms (`include $var`, `require __DIR__ . '/x'`,
+ * interpolated strings) — they have no resolvable compile-time path, which
+ * matches the issue's "static string literals (the common case)" scope.
+ */
+function phpStaticIncludePath(node: SyntaxNode, source: string): string | null {
+  // The path argument is the expression's first named child; the call-style
+  // form `require("x")` wraps it in a parenthesized_expression.
+  let arg: SyntaxNode | null = node.namedChild(0);
+  if (arg?.type === 'parenthesized_expression') arg = arg.namedChild(0);
+  if (!arg || (arg.type !== 'string' && arg.type !== 'encapsed_string')) return null;
+  // Pure literal only: any non-`string_content` child (interpolated variable,
+  // escape sequence, …) means the value isn't a static path.
+  const parts = arg.namedChildren;
+  if (parts.some((c: SyntaxNode) => c.type !== 'string_content')) return null;
+  const content = parts.find((c: SyntaxNode) => c.type === 'string_content');
+  return content ? getNodeText(content, source) : null;
+}
+
+/** PHP built-in return types that can't be a method receiver (so no class to chain on). */
+const PHP_NON_CLASS_RETURN = new Set([
+  'array', 'string', 'int', 'integer', 'float', 'double', 'bool', 'boolean',
+  'void', 'mixed', 'never', 'null', 'false', 'true', 'object', 'callable',
+  'iterable', 'resource',
+]);
+
+/**
+ * A method/function's declared return type, normalized to the class a chained
+ * `->method()` could be called on (issue #608). `self` / `static` / `$this` are
+ * kept as the marker `self` and resolved to the declaring class at resolution
+ * time; a concrete type returns its short name; primitives / unions / nullable
+ * non-class types return undefined.
+ */
+function extractPhpReturnType(node: SyntaxNode, source: string): string | undefined {
+  let rt = getChildByField(node, 'return_type');
+  if (!rt) return undefined;
+  // Unwrap `?Type`. Union / intersection types are ambiguous — skip them.
+  if (rt.type === 'optional_type') rt = rt.namedChild(0) ?? rt;
+  if (!rt || rt.type === 'primitive_type') return undefined;
+
+  const nameNode = rt.type === 'named_type' ? (rt.namedChild(0) ?? rt) : rt;
+  const text = getNodeText(nameNode, source).trim().replace(/^\\/, '');
+  if (!text) return undefined;
+  const last = text.split('\\').pop() ?? text;
+  const lc = last.toLowerCase();
+  if (lc === 'self' || lc === 'static' || lc === 'this' || lc === '$this') return 'self';
+  if (PHP_NON_CLASS_RETURN.has(lc)) return undefined;
+  if (!/^[A-Za-z_]\w*$/.test(last)) return undefined; // union/intersection/complex
+  return last;
+}
+
 export const phpExtractor: LanguageExtractor = {
   functionTypes: ['function_definition'],
   classTypes: ['class_declaration', 'trait_declaration'],
@@ -11,7 +74,7 @@ export const phpExtractor: LanguageExtractor = {
   enumTypes: ['enum_declaration'],
   enumMemberTypes: ['enum_case'],
   typeAliasTypes: [],
-  importTypes: ['namespace_use_declaration'],
+  importTypes: ['namespace_use_declaration', ...PHP_INCLUDE_TYPES],
   callTypes: ['function_call_expression', 'member_call_expression', 'scoped_call_expression'],
   variableTypes: ['const_declaration'],
   fieldTypes: ['property_declaration'],
@@ -19,6 +82,7 @@ export const phpExtractor: LanguageExtractor = {
   bodyField: 'body',
   paramsField: 'parameters',
   returnField: 'return_type',
+  getReturnType: extractPhpReturnType,
   classifyClassNode: (node) => {
     return node.type === 'trait_declaration' ? 'trait' : 'class';
   },
@@ -78,9 +142,29 @@ export const phpExtractor: LanguageExtractor = {
 
     return false;
   },
+  // PHP `namespace Foo\Bar;` is file-level (like a Java/Kotlin package). Capturing
+  // it scopes every class under an `Foo\Bar::` qualified name, which is what makes
+  // `use` imports and same-named types (Laravel has 7+ `Factory` interfaces across
+  // namespaces) resolvable to the RIGHT definition instead of an arbitrary match.
+  packageTypes: ['namespace_definition'],
+  extractPackage: (node, source) => {
+    const nsName = node.namedChildren.find((c: SyntaxNode) => c.type === 'namespace_name');
+    // Skip braced `namespace Foo { … }` (has a body) — file-level only.
+    const hasBody = node.namedChildren.some((c: SyntaxNode) => c.type === 'compound_statement' || c.type === 'declaration_list');
+    if (!nsName || hasBody) return null;
+    return getNodeText(nsName, source);
+  },
   extractImport: (node, source) => {
     const importText = source.substring(node.startIndex, node.endIndex).trim();
 
+    // include / require (+ _once): emit a file→file dependency. The path is a
+    // static string literal in the common case; dynamic forms resolve to null
+    // and are skipped (no import node, no edge).
+    if (PHP_INCLUDE_TYPES.has(node.type)) {
+      const includePath = phpStaticIncludePath(node, source);
+      return includePath ? { moduleName: includePath, signature: importText } : null;
+    }
+
     // Check for grouped imports: use X\{A, B} - return null for core fallback
     const namespacePrefix = node.namedChildren.find((c: SyntaxNode) => c.type === 'namespace_name');
     const useGroup = node.namedChildren.find((c: SyntaxNode) => c.type === 'namespace_use_group');
diff --git a/src/extraction/languages/ruby.ts b/src/extraction/languages/ruby.ts
index b54261656..8679a15c1 100644
--- a/src/extraction/languages/ruby.ts
+++ b/src/extraction/languages/ruby.ts
@@ -17,6 +17,42 @@ export const rubyExtractor: LanguageExtractor = {
   bodyField: 'body',
   paramsField: 'parameters',
   visitNode: (node, ctx) => {
+    // Ruby mixins: `include Mod`, `extend Mod`, `prepend Mod[, Other]` — the
+    // primary composition mechanism (ActiveSupport concerns, Comparable, …).
+    // These parse as a bare `call` to `include`/`extend`/`prepend` with the
+    // module(s) as constant arguments, so without special handling they'd be
+    // mis-extracted as a call to a method named "include" and the module would
+    // record no dependent — even though it's mixed into a class. Emit an
+    // `implements` edge (enclosing class/module → mixed-in module), so editing a
+    // concern surfaces every class that includes it.
+    if (node.type === 'call' && !node.childForFieldName('receiver')) {
+      const method = node.childForFieldName('method');
+      const mname = method?.text;
+      if (mname === 'include' || mname === 'extend' || mname === 'prepend') {
+        const parentId = ctx.nodeStack.length > 0 ? ctx.nodeStack[ctx.nodeStack.length - 1] : undefined;
+        const args = node.childForFieldName('arguments')
+          ?? node.namedChildren.find((c: SyntaxNode) => c.type === 'argument_list');
+        if (parentId && args) {
+          for (let i = 0; i < args.namedChildCount; i++) {
+            const arg = args.namedChild(i);
+            // `Mod` is `constant`, `Foo::Bar` is `scope_resolution`. Skip
+            // `extend self` / dynamic args (`include foo()`).
+            if (arg && (arg.type === 'constant' || arg.type === 'scope_resolution')) {
+              ctx.addUnresolvedReference({
+                fromNodeId: parentId,
+                referenceName: getNodeText(arg, ctx.source),
+                referenceKind: 'implements',
+                filePath: ctx.filePath,
+                line: node.startPosition.row + 1,
+                column: node.startPosition.column,
+              });
+            }
+          }
+          return true; // handled — don't also extract as a call to "include"
+        }
+      }
+    }
+
     if (node.type !== 'module') return false;
 
     const nameNode = node.childForFieldName('name');
diff --git a/src/extraction/languages/rust.ts b/src/extraction/languages/rust.ts
index 0266a2fda..bdc4477ba 100644
--- a/src/extraction/languages/rust.ts
+++ b/src/extraction/languages/rust.ts
@@ -2,10 +2,44 @@ import type { Node as SyntaxNode } from 'web-tree-sitter';
 import { getNodeText, getChildByField } from '../tree-sitter-helpers';
 import type { LanguageExtractor } from '../tree-sitter-types';
 
+/**
+ * A Rust function's declared return type, normalized to the bare type a chained
+ * `Foo::new().bar()` could be called on (the #645/#608 mechanism). Reads the
+ * `return_type` field: `-> Self` yields the marker `self` (resolved to the impl's
+ * own type at resolution time, like PHP's `self`/`static`); a concrete `-> Foo` /
+ * `-> FooBuilder` its name; a reference (`&Foo`) is unwrapped; generics are reduced
+ * to the base type (`Vec<Foo>` → `Vec`); primitives / unit / tuple yield undefined.
+ * Stdlib types that aren't in the graph simply fail the later existence check.
+ */
+function extractRustReturnType(node: SyntaxNode, source: string): string | undefined {
+  let rt = getChildByField(node, 'return_type');
+  if (!rt) return undefined;
+  if (rt.type === 'reference_type') {
+    rt =
+      rt.namedChildren.find(
+        (c: SyntaxNode) =>
+          c.type === 'type_identifier' ||
+          c.type === 'scoped_type_identifier' ||
+          c.type === 'generic_type',
+      ) ?? rt;
+  }
+  if (!rt || rt.type === 'primitive_type' || rt.type === 'unit_type' || rt.type === 'tuple_type') {
+    return undefined;
+  }
+  const text = getNodeText(rt, source).trim().replace(/<[^>]*>/g, '');
+  const last = text.split('::').pop()?.trim();
+  if (!last || !/^[A-Za-z_]\w*$/.test(last)) return undefined;
+  return last === 'Self' ? 'self' : last;
+}
+
 export const rustExtractor: LanguageExtractor = {
-  functionTypes: ['function_item'],
+  // `function_signature_item` is a trait method DECLARATION (`fn render(&self);`,
+  // no body). Extracting it makes a trait's method set first-class, which
+  // impl-navigation and trait-dispatch synthesis need (a struct's method set is
+  // matched against the trait's).
+  functionTypes: ['function_item', 'function_signature_item'],
   classTypes: [], // Rust has impl blocks
-  methodTypes: ['function_item'], // Methods are functions in impl blocks
+  methodTypes: ['function_item', 'function_signature_item'],
   interfaceTypes: ['trait_item'],
   structTypes: ['struct_item'],
   enumTypes: ['enum_item'],
@@ -19,6 +53,7 @@ export const rustExtractor: LanguageExtractor = {
   bodyField: 'body',
   paramsField: 'parameters',
   returnField: 'return_type',
+  getReturnType: extractRustReturnType,
   getSignature: (node, source) => {
     const params = getChildByField(node, 'parameters');
     const returnType = getChildByField(node, 'return_type');
diff --git a/src/extraction/languages/scala.ts b/src/extraction/languages/scala.ts
index fca6aea7e..0e17e62df 100644
--- a/src/extraction/languages/scala.ts
+++ b/src/extraction/languages/scala.ts
@@ -10,6 +10,62 @@ function getValVarName(node: SyntaxNode, source: string): string | null {
   return identChild ? getNodeText(identChild, source) : null;
 }
 
+// Capitalized Scala primitives/ubiquitous aliases that shouldn't create refs.
+const SCALA_BUILTIN_TYPES = new Set([
+  'Int', 'Long', 'Short', 'Byte', 'Float', 'Double', 'Boolean', 'Char', 'Unit',
+  'String', 'Any', 'AnyRef', 'AnyVal', 'Nothing', 'Null',
+]);
+
+/**
+ * Emit `references` edges for every type identifier in a Scala type subtree
+ * (a `val`/`var` type annotation), unwrapping `generic_type` etc. Mirrors the
+ * generic type-annotation extraction the core extractor runs for method
+ * parameter/return types, but Scala `val`s are created here in visitNode so
+ * their type is walked here too. A trait used only as a field type (the common
+ * `implicit val x: Monoid[Int]` instance pattern) thus gains a dependent.
+ */
+function emitScalaTypeRefs(typeNode: SyntaxNode, fromId: string, ctx: { addUnresolvedReference: (r: { fromNodeId: string; referenceName: string; referenceKind: 'references'; line: number; column: number }) => void }, source: string): void {
+  if (typeNode.type === 'type_identifier') {
+    const name = source.substring(typeNode.startIndex, typeNode.endIndex);
+    if (name && !SCALA_BUILTIN_TYPES.has(name)) {
+      ctx.addUnresolvedReference({
+        fromNodeId: fromId,
+        referenceName: name,
+        referenceKind: 'references',
+        line: typeNode.startPosition.row + 1,
+        column: typeNode.startPosition.column,
+      });
+    }
+    return;
+  }
+  for (let i = 0; i < typeNode.namedChildCount; i++) {
+    const child = typeNode.namedChild(i);
+    if (child) emitScalaTypeRefs(child, fromId, ctx, source);
+  }
+}
+
+/**
+ * Capture a Scala method's declared return type as a bare type name, for the
+ * chained static-factory / fluent call mechanism (#750). `def create(): Bar`
+ * yields `Bar`; a generic `List[Bar]` yields its base `List` (the method is on
+ * the container, not the element); a qualified `pkg.Bar` yields `Bar`. A
+ * singleton self-type (`this.type`, the fluent-builder idiom) is left undefined
+ * — its type can't be recovered here, so the chain falls through rather than
+ * inferring a wrong receiver.
+ */
+function extractScalaReturnType(node: SyntaxNode, source: string): string | undefined {
+  const rt = node.childForFieldName('return_type');
+  if (!rt) return undefined;
+  const raw = getNodeText(rt, source).trim();
+  if (raw.startsWith('this.')) return undefined; // `this.type` singleton — unhandled
+  const base = raw
+    .replace(/\[[^\]]*\]/g, '') // strip generic args: List[Bar] → List
+    .replace(/\s+/g, '');
+  const last = base.split('.').pop(); // qualified pkg.Bar → Bar
+  if (!last || !/^[A-Za-z_]\w*$/.test(last)) return undefined;
+  return last;
+}
+
 function extractVisibility(node: SyntaxNode): 'public' | 'private' | 'protected' {
   for (let i = 0; i < node.namedChildCount; i++) {
     const child = node.namedChild(i);
@@ -43,6 +99,7 @@ export const scalaExtractor: LanguageExtractor = {
   bodyField: 'body',
   paramsField: 'parameters',
   returnField: 'return_type',
+  getReturnType: extractScalaReturnType,
   interfaceKind: 'trait',
 
   classifyClassNode: (node: SyntaxNode) => {
@@ -96,7 +153,8 @@ export const scalaExtractor: LanguageExtractor = {
         ? `${t === 'val_definition' ? 'val' : 'var'} ${name}: ${getNodeText(typeNode, ctx.source)}`
         : undefined;
 
-      ctx.createNode(kind, name, node, { signature: sig, visibility: extractVisibility(node) });
+      const created = ctx.createNode(kind, name, node, { signature: sig, visibility: extractVisibility(node) });
+      if (created && typeNode) emitScalaTypeRefs(typeNode, created.id, ctx, ctx.source);
       return true;
     }
 
diff --git a/src/extraction/languages/swift.ts b/src/extraction/languages/swift.ts
index 373fa8a9e..e9401d372 100644
--- a/src/extraction/languages/swift.ts
+++ b/src/extraction/languages/swift.ts
@@ -2,6 +2,44 @@ import type { Node as SyntaxNode } from 'web-tree-sitter';
 import { getNodeText, getChildByField } from '../tree-sitter-helpers';
 import type { LanguageExtractor } from '../tree-sitter-types';
 
+/**
+ * A Swift function's declared return type, normalized to the bare class name a
+ * chained `Foo.make().draw()` could be called on (the #645/#608 mechanism).
+ * tree-sitter-swift labels BOTH the function name (`simple_identifier`) and the
+ * return type (a `user_type`) with the field `name`, so `childForFieldName`
+ * returns the name; the return type is found positionally — the first type node
+ * after the `simple_identifier` name, before the body. Optionals (`Foo?`) are
+ * unwrapped; arrays/tuples/function types and `Void` yield undefined.
+ */
+function extractSwiftReturnType(node: SyntaxNode, source: string): string | undefined {
+  let seenName = false;
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (!child) continue;
+    if (child.type === 'simple_identifier' && !seenName) {
+      seenName = true;
+      continue;
+    }
+    if (!seenName) continue;
+    if (child.type === 'function_body') return undefined; // body reached: no return type
+    let typeNode: SyntaxNode | null = null;
+    if (child.type === 'user_type') typeNode = child;
+    else if (child.type === 'optional_type') {
+      typeNode = child.namedChildren.find((c: SyntaxNode) => c.type === 'user_type') ?? null;
+    }
+    if (typeNode) {
+      // Use the whole type node's text, strip generics, then take the LAST
+      // dotted segment — a member type `KF.Builder` resolves to `Builder` (its
+      // first type_identifier is the OUTER `KF`, which would be wrong).
+      const name = getNodeText(typeNode, source).trim().replace(/<[^>]*>/g, '');
+      const last = name.split('.').pop()?.trim();
+      if (!last || !/^[A-Za-z_]\w*$/.test(last) || last === 'Void') return undefined;
+      return last;
+    }
+  }
+  return undefined;
+}
+
 export const swiftExtractor: LanguageExtractor = {
   functionTypes: ['function_declaration'],
   classTypes: ['class_declaration'],
@@ -18,6 +56,23 @@ export const swiftExtractor: LanguageExtractor = {
   bodyField: 'body',
   paramsField: 'parameter',
   returnField: 'return_type',
+  getReturnType: extractSwiftReturnType,
+  resolveName: (node, source) => {
+    // A nested-type extension `extension KF.Builder { … }` parses as a
+    // class_declaration whose `name` is a multi-segment `user_type` (`KF.Builder`
+    // = type_identifiers `KF`, `Builder`). Name the node by the LAST segment
+    // (`Builder`) so it shares the simple name of the extended type's own
+    // declaration (`struct Builder` → `KF::Builder`) instead of becoming a
+    // distinct `KF.Builder` node. Without this, the extension's conformances and
+    // members are invisible to a chained call on the type — supertype lookup and
+    // method matching both key off the simple name (#750). Simple names (regular
+    // class/struct/enum, or `extension Plain`) fall through to default extraction.
+    if (node.type !== 'class_declaration') return undefined;
+    const nameNode = getChildByField(node, 'name');
+    if (!nameNode || nameNode.type !== 'user_type') return undefined;
+    const ids = nameNode.namedChildren.filter((c: SyntaxNode) => c.type === 'type_identifier');
+    return ids.length > 1 ? getNodeText(ids[ids.length - 1]!, source) : undefined;
+  },
   getSignature: (node, source) => {
     // Swift function signature: func name(params) -> ReturnType
     const params = getChildByField(node, 'parameter');
diff --git a/src/extraction/languages/typescript.ts b/src/extraction/languages/typescript.ts
index 9540dd940..72059114f 100644
--- a/src/extraction/languages/typescript.ts
+++ b/src/extraction/languages/typescript.ts
@@ -1,10 +1,48 @@
 import { getNodeText, getChildByField } from '../tree-sitter-helpers';
 import type { LanguageExtractor } from '../tree-sitter-types';
+import type { Node as SyntaxNode } from 'web-tree-sitter';
+
+/**
+ * A TS/JS class field (`public_field_definition` / `field_definition`) is a
+ * METHOD only when its value is callable — an arrow function, a function
+ * expression, or a HOF call wrapping one (`onScroll = throttle(() => {…})`),
+ * exactly mirroring what `resolveBody` below knows how to walk. Everything
+ * else (`public fonts: Fonts;`, `count = 0`, `static defaults = {…}`) is a
+ * PROPERTY. Previously every field extracted as method-kind (#808), which
+ * misrepresented class shape and defeated kind-based filtering — the reason
+ * #756's function-ref resolution had to restrict TS/JS bare identifiers to
+ * function targets.
+ */
+export function classifyTsClassMember(node: SyntaxNode): 'method' | 'property' {
+  if (node.type !== 'public_field_definition' && node.type !== 'field_definition') {
+    return 'method'; // method_definition, getters/setters — untouched
+  }
+  for (let i = 0; i < node.namedChildCount; i++) {
+    const child = node.namedChild(i);
+    if (!child) continue;
+    if (child.type === 'arrow_function' || child.type === 'function_expression') {
+      return 'method';
+    }
+    if (child.type === 'call_expression') {
+      const args = getChildByField(child, 'arguments');
+      if (args) {
+        for (let j = 0; j < args.namedChildCount; j++) {
+          const arg = args.namedChild(j);
+          if (arg && (arg.type === 'arrow_function' || arg.type === 'function_expression')) {
+            return 'method';
+          }
+        }
+      }
+    }
+  }
+  return 'property';
+}
 
 export const typescriptExtractor: LanguageExtractor = {
   functionTypes: ['function_declaration', 'arrow_function', 'function_expression'],
   classTypes: ['class_declaration', 'abstract_class_declaration'],
   methodTypes: ['method_definition', 'public_field_definition'],
+  classifyMethodNode: classifyTsClassMember,
   interfaceTypes: ['interface_declaration'],
   structTypes: [],
   enumTypes: ['enum_declaration'],
diff --git a/src/extraction/liquid-extractor.ts b/src/extraction/liquid-extractor.ts
index 81e08a91a..5bd9bacc0 100644
--- a/src/extraction/liquid-extractor.ts
+++ b/src/extraction/liquid-extractor.ts
@@ -33,17 +33,25 @@ export class LiquidExtractor {
       // Create file node
       const fileNode = this.createFileNode();
 
-      // Extract render/include statements (snippet references)
-      this.extractSnippetReferences(fileNode.id);
-
-      // Extract section references
-      this.extractSectionReferences(fileNode.id);
-
-      // Extract schema block
-      this.extractSchema(fileNode.id);
-
-      // Extract assign statements as variables
-      this.extractAssignments(fileNode.id);
+      // Shopify OS 2.0 JSON template / section group: link each section `type`
+      // to its `sections/<type>.liquid` file. (No symbol nodes are emitted — the
+      // JSON file just carries the references — so it stays out of any
+      // symbol-bearing-file metric while its sections still get their dependents.)
+      if (this.filePath.endsWith('.json')) {
+        this.extractShopifyJsonSections(fileNode.id);
+      } else {
+        // Extract render/include statements (snippet references)
+        this.extractSnippetReferences(fileNode.id);
+
+        // Extract section references
+        this.extractSectionReferences(fileNode.id);
+
+        // Extract schema block
+        this.extractSchema(fileNode.id);
+
+        // Extract assign statements as variables
+        this.extractAssignments(fileNode.id);
+      }
     } catch (error) {
       this.errors.push({
         message: `Liquid extraction error: ${error instanceof Error ? error.message : String(error)}`,
@@ -86,6 +94,36 @@ export class LiquidExtractor {
     return fileNode;
   }
 
+  /**
+   * Shopify OS 2.0 JSON template / section group. Both have a `sections` object
+   * mapping an id → `{ "type": "<section-name>", ... }`; the `type` names a
+   * `sections/<type>.liquid` file. Emit a `references` edge to each, so a section
+   * used only from a JSON template (the OS 2.0 norm) is no longer orphaned.
+   */
+  private extractShopifyJsonSections(fromNodeId: string): void {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(this.source);
+    } catch {
+      return; // not valid JSON (or a partial) — nothing to link
+    }
+    const sections = (parsed as { sections?: Record<string, { type?: unknown }> })?.sections;
+    if (!sections || typeof sections !== 'object') return;
+    const seen = new Set<string>();
+    for (const key of Object.keys(sections)) {
+      const type = sections[key]?.type;
+      if (typeof type !== 'string' || seen.has(type)) continue;
+      seen.add(type);
+      this.unresolvedReferences.push({
+        fromNodeId,
+        referenceName: `sections/${type}.liquid`,
+        referenceKind: 'references',
+        line: 1,
+        column: 0,
+      });
+    }
+  }
+
   /**
    * Extract {% render 'snippet' %} and {% include 'snippet' %} references
    */
@@ -275,7 +313,10 @@ export class LiquidExtractor {
         endLine,
         startColumn: match.index - this.getLineStart(startLine),
         endColumn: 0,
-        docstring: schemaContent?.trim().substring(0, 200), // Store first 200 chars as docstring
+        // SECURITY (#383): don't dump the raw {% schema %} JSON (section settings
+        // + default values) into the docstring — the schema name is already in
+        // `name`, so the data block adds nothing but a potential leak of any
+        // IDs/endpoints/keys a developer placed in setting defaults.
         updatedAt: Date.now(),
       };
 
diff --git a/src/extraction/mybatis-extractor.ts b/src/extraction/mybatis-extractor.ts
new file mode 100644
index 000000000..fc873e1dc
--- /dev/null
+++ b/src/extraction/mybatis-extractor.ts
@@ -0,0 +1,198 @@
+import { Edge, ExtractionError, ExtractionResult, Node, UnresolvedReference } from '../types';
+import { generateNodeId } from './tree-sitter-helpers';
+
+/**
+ * MyBatisExtractor — parses MyBatis mapper XML files.
+ *
+ * MyBatis splits a DAO interface across two files: a Java interface (parsed by
+ * tree-sitter) declares the method, and an XML mapper file holds the SQL keyed
+ * by `<namespace>` (the fully-qualified Java type name) and `id` (the method
+ * name). Without the XML side in the graph, `trace(Controller, ...DAO.method)`
+ * dead-ends at the interface method — the SQL it actually runs is invisible,
+ * and "what does this query touch" / "where is this column written" can't be
+ * answered.
+ *
+ * This extractor emits one method-shaped node per `<select|insert|update|
+ * delete>` and per `<sql>` fragment, qualified as `<namespace>::<id>` so the
+ * MyBatis framework synthesizer (`src/resolution/frameworks/mybatis.ts`) can
+ * link the matching Java method → XML statement by suffix-matching qualified
+ * names. `<include refid="...">` inside a statement yields an unresolved
+ * reference to the SQL fragment, also keyed by `<namespace>::<refid>`.
+ *
+ * Non-mapper XML (Maven `pom.xml`, Spring beans XML, `web.xml`, log4j config,
+ * etc.) is detected by the absence of a `<mapper namespace="...">` root and
+ * returns just a file node — we still need the file row so the watcher can
+ * track it, but we emit no symbols.
+ */
+export class MyBatisExtractor {
+  private filePath: string;
+  private source: string;
+  private nodes: Node[] = [];
+  private edges: Edge[] = [];
+  private unresolvedReferences: UnresolvedReference[] = [];
+  private errors: ExtractionError[] = [];
+  private lineStarts: number[] = [];
+
+  constructor(filePath: string, source: string) {
+    this.filePath = filePath;
+    this.source = source;
+    this.computeLineStarts();
+  }
+
+  extract(): ExtractionResult {
+    const startTime = Date.now();
+
+    const fileNode = this.createFileNode();
+
+    try {
+      const mapperMatch = this.findMapperRoot();
+      if (mapperMatch) {
+        this.extractMapper(fileNode.id, mapperMatch.namespace, mapperMatch.bodyStart, mapperMatch.bodyEnd);
+      }
+    } catch (error) {
+      this.errors.push({
+        message: `MyBatis extraction error: ${error instanceof Error ? error.message : String(error)}`,
+        severity: 'error',
+        code: 'parse_error',
+      });
+    }
+
+    return {
+      nodes: this.nodes,
+      edges: this.edges,
+      unresolvedReferences: this.unresolvedReferences,
+      errors: this.errors,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  private createFileNode(): Node {
+    const lines = this.source.split('\n');
+    const id = generateNodeId(this.filePath, 'file', this.filePath, 1);
+    const node: Node = {
+      id,
+      kind: 'file',
+      name: this.filePath.split('/').pop() || this.filePath,
+      qualifiedName: this.filePath,
+      filePath: this.filePath,
+      language: 'xml',
+      startLine: 1,
+      endLine: lines.length || 1,
+      startColumn: 0,
+      endColumn: lines[lines.length - 1]?.length ?? 0,
+      updatedAt: Date.now(),
+    };
+    this.nodes.push(node);
+    return node;
+  }
+
+  /**
+   * Find the `<mapper namespace="X">` opening tag. Returns the namespace and
+   * the byte offsets of the body (between the opening and closing tag) so
+   * statement extraction can be scoped to mapper contents.
+   */
+  private findMapperRoot(): { namespace: string; bodyStart: number; bodyEnd: number } | null {
+    const open = /<mapper\b([^>]*)>/.exec(this.source);
+    if (!open) return null;
+    const attrs = open[1] ?? '';
+    const nsMatch = /\bnamespace\s*=\s*"([^"]+)"/.exec(attrs);
+    if (!nsMatch) return null;
+    const bodyStart = open.index + open[0].length;
+    const closeIdx = this.source.indexOf('</mapper>', bodyStart);
+    const bodyEnd = closeIdx >= 0 ? closeIdx : this.source.length;
+    return { namespace: nsMatch[1]!, bodyStart, bodyEnd };
+  }
+
+  private extractMapper(fileNodeId: string, namespace: string, bodyStart: number, bodyEnd: number): void {
+    const body = this.source.slice(bodyStart, bodyEnd);
+    // Match each top-level statement-shaped element. The body may have nested
+    // tags (`<if>`, `<foreach>`, `<include>`), so we scan with a regex that
+    // pairs an opening tag to its matching close — the simple form below works
+    // because MyBatis statement elements are not themselves nested.
+    const stmtRegex = /<(select|insert|update|delete|sql)\b([^>]*)>([\s\S]*?)<\/\1>/g;
+    let m: RegExpExecArray | null;
+    while ((m = stmtRegex.exec(body)) !== null) {
+      const elemType = m[1]!;
+      const attrs = m[2] ?? '';
+      const elemBody = m[3] ?? '';
+      const idMatch = /\bid\s*=\s*"([^"]+)"/.exec(attrs);
+      if (!idMatch) continue;
+      const id = idMatch[1]!;
+      const absoluteIndex = bodyStart + m.index;
+      const startLine = this.getLineNumber(absoluteIndex);
+      const endLine = this.getLineNumber(absoluteIndex + m[0].length);
+      const qualified = `${namespace}::${id}`;
+      const isSqlFragment = elemType === 'sql';
+      const nodeId = generateNodeId(this.filePath, 'method', qualified, startLine);
+      const node: Node = {
+        id: nodeId,
+        kind: 'method',
+        name: id,
+        qualifiedName: qualified,
+        filePath: this.filePath,
+        language: 'xml',
+        signature: this.buildSignature(elemType, attrs, isSqlFragment),
+        startLine,
+        endLine,
+        startColumn: 0,
+        endColumn: 0,
+        docstring: this.previewSql(elemBody),
+        updatedAt: Date.now(),
+      };
+      this.nodes.push(node);
+      this.edges.push({ source: fileNodeId, target: nodeId, kind: 'contains' });
+
+      // <include refid="X"/> → reference to the SQL fragment in this mapper
+      // (or in another mapper, when the refid is qualified — `ns.X`).
+      const includeRegex = /<include\b[^>]*\brefid\s*=\s*"([^"]+)"/g;
+      let inc: RegExpExecArray | null;
+      while ((inc = includeRegex.exec(elemBody)) !== null) {
+        const refid = inc[1]!;
+        const refQualified = refid.includes('.') ? refid.replace(/\./g, '::') : `${namespace}::${refid}`;
+        const includeOffset = absoluteIndex + (m[0].length - m[3]!.length - `</${elemType}>`.length) + inc.index;
+        const line = this.getLineNumber(includeOffset);
+        this.unresolvedReferences.push({
+          fromNodeId: nodeId,
+          referenceName: refQualified,
+          referenceKind: 'references',
+          line,
+          column: 0,
+        });
+      }
+    }
+  }
+
+  private buildSignature(elemType: string, attrs: string, isSqlFragment: boolean): string {
+    if (isSqlFragment) return '<sql>';
+    const verb = elemType.toUpperCase();
+    const result = /\bresultType\s*=\s*"([^"]+)"/.exec(attrs)?.[1];
+    const param = /\bparameterType\s*=\s*"([^"]+)"/.exec(attrs)?.[1];
+    const parts = [verb];
+    if (param) parts.push(`param=${param}`);
+    if (result) parts.push(`result=${result}`);
+    return parts.join(' ');
+  }
+
+  private previewSql(body: string): string {
+    return body.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 200);
+  }
+
+  private computeLineStarts(): void {
+    this.lineStarts = [0];
+    for (let i = 0; i < this.source.length; i++) {
+      if (this.source.charCodeAt(i) === 10) this.lineStarts.push(i + 1);
+    }
+  }
+
+  private getLineNumber(offset: number): number {
+    // Binary search
+    let lo = 0;
+    let hi = this.lineStarts.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >>> 1;
+      if (this.lineStarts[mid]! <= offset) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo + 1;
+  }
+}
diff --git a/src/extraction/razor-extractor.ts b/src/extraction/razor-extractor.ts
new file mode 100644
index 000000000..5f89b5ceb
--- /dev/null
+++ b/src/extraction/razor-extractor.ts
@@ -0,0 +1,280 @@
+import { Node, Edge, ExtractionResult, ExtractionError, UnresolvedReference } from '../types';
+import { generateNodeId } from './tree-sitter-helpers';
+import { TreeSitterExtractor } from './tree-sitter';
+import { isLanguageSupported } from './grammars';
+
+/**
+ * RazorExtractor — extracts code relationships from ASP.NET Razor (`.cshtml`)
+ * and Blazor (`.razor`) markup.
+ *
+ * Markup-driven code-behind, view-models, components, and DTOs are referenced
+ * only from markup the engine otherwise doesn't parse, so they look like nothing
+ * depends on them. This extractor links the markup → the C# types it names:
+ *
+ *  - `@model Foo` / `@inherits Bar<Foo>`  → the view-model / base type (.cshtml + .razor)
+ *  - `@inject IService svc`               → the injected service type
+ *  - `@typeof(MainLayout)`                → the referenced type
+ *  - `<MyComponent .../>` (Blazor only)   → the component class (.razor or `.cs : ComponentBase`)
+ *  - `<Grid TItem="CatalogItem">`         → the generic type argument
+ *
+ * Risk mitigations (see docs/design/template-markup-parser.md):
+ *  - Only PascalCase (`[A-Z]`-initial) tags are treated as components — HTML
+ *    elements are lowercase, so they never match. Known Blazor framework
+ *    components are skipped (they aren't in-repo, so a ref would just dangle).
+ *  - Exactly ONE `component` node per file; component tags become `references`
+ *    EDGES, never nodes — no per-tag node explosion.
+ *  - Emitted refs are ordinary by-name `references` resolved by the name-matcher;
+ *    `razor` shares the `dotnet` language family with `csharp` (name-matcher.ts)
+ *    so the cross-family gate doesn't drop them.
+ *  - `.cshtml`/`.razor` are registered in grammars.ts so they're indexed.
+ *
+ * Out of scope (data-flow / low-value): `asp-for`/`th:field` property-string
+ * bindings; the C# inside `@code { }` / `@{ }` blocks (noisy regex on embedded C#).
+ */
+
+/**
+ * Blazor framework-provided components — invoked by the runtime, not defined
+ * in-repo, so a reference to them would never resolve. Skip to avoid dangling refs.
+ */
+const BLAZOR_BUILTIN_COMPONENTS = new Set([
+  'Router', 'Found', 'NotFound', 'RouteView', 'AuthorizeRouteView', 'LayoutView',
+  'CascadingValue', 'CascadingAuthenticationState', 'AuthorizeView', 'Authorized',
+  'NotAuthorized', 'Authorizing', 'EditForm', 'DataAnnotationsValidator',
+  'ValidationSummary', 'ValidationMessage', 'InputText', 'InputNumber',
+  'InputCheckbox', 'InputSelect', 'InputDate', 'InputTextArea', 'InputRadio',
+  'InputRadioGroup', 'InputFile', 'PageTitle', 'HeadContent', 'HeadOutlet',
+  'Virtualize', 'DynamicComponent', 'ErrorBoundary', 'SectionContent',
+  'SectionOutlet', 'FocusOnNavigate', 'NavLink', 'Microsoft',
+]);
+
+export class RazorExtractor {
+  private filePath: string;
+  private source: string;
+  private nodes: Node[] = [];
+  private edges: Edge[] = [];
+  private unresolvedReferences: UnresolvedReference[] = [];
+  private errors: ExtractionError[] = [];
+
+  constructor(filePath: string, source: string) {
+    this.filePath = filePath;
+    this.source = source;
+  }
+
+  extract(): ExtractionResult {
+    const startTime = Date.now();
+    try {
+      const componentId = this.createComponentNode().id;
+      this.extractDirectives(componentId);
+      // Blazor component tags only — `.cshtml` uses HTML + tag helpers, not
+      // PascalCase component elements.
+      if (this.filePath.toLowerCase().endsWith('.razor')) {
+        this.extractComponentTags(componentId);
+      }
+      // Delegate the C# in `@code { }` / `@functions { }` / `@{ }` blocks to the
+      // C# tree-sitter extractor (the Blazor analog of Svelte's <script> block) —
+      // this is where component logic uses services/DTOs, so it covers the types
+      // referenced only from component code.
+      this.processCodeBlocks(componentId);
+    } catch (error) {
+      this.errors.push({
+        message: `Razor extraction error: ${error instanceof Error ? error.message : String(error)}`,
+        severity: 'error',
+        code: 'parse_error',
+      });
+    }
+    return {
+      nodes: this.nodes,
+      edges: this.edges,
+      unresolvedReferences: this.unresolvedReferences,
+      errors: this.errors,
+      durationMs: Date.now() - startTime,
+    };
+  }
+
+  private createComponentNode(): Node {
+    const lines = this.source.split('\n');
+    const fileName = this.filePath.split(/[/\\]/).pop() || this.filePath;
+    const componentName = fileName.replace(/\.(razor|cshtml)$/i, '');
+    const node: Node = {
+      id: generateNodeId(this.filePath, 'component', componentName, 1),
+      kind: 'component',
+      name: componentName,
+      qualifiedName: `${this.filePath}::${componentName}`,
+      filePath: this.filePath,
+      language: 'razor',
+      startLine: 1,
+      endLine: lines.length,
+      startColumn: 0,
+      endColumn: lines[lines.length - 1]?.length || 0,
+      isExported: true,
+      updatedAt: Date.now(),
+    };
+    this.nodes.push(node);
+    return node;
+  }
+
+  /** Last `.`-segment (`App.ViewModels.RegisterModel` → `RegisterModel`). */
+  private lastSegment(s: string): string {
+    const i = s.lastIndexOf('.');
+    return i >= 0 ? s.slice(i + 1) : s;
+  }
+
+  /**
+   * Split a type expression into the capitalized type names it contains — base
+   * type plus any generic arguments (`Bar<Foo, Baz>` → `Bar`, `Foo`, `Baz`),
+   * each reduced to its last namespace segment. Lowercase/keyword tokens drop out.
+   */
+  private typeNames(expr: string): string[] {
+    const out: string[] = [];
+    for (const raw of expr.split(/[<>,\s]+/)) {
+      const seg = this.lastSegment(raw.trim());
+      if (/^[A-Z][A-Za-z0-9_]*$/.test(seg)) out.push(seg);
+    }
+    return out;
+  }
+
+  private pushRef(componentId: string, name: string, line: number, column: number): void {
+    this.unresolvedReferences.push({
+      fromNodeId: componentId,
+      referenceName: name,
+      referenceKind: 'references',
+      line,
+      column,
+      filePath: this.filePath,
+      language: 'razor',
+    });
+  }
+
+  private extractDirectives(componentId: string): void {
+    const lines = this.source.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]!;
+      // `@model Foo` / `@inherits Bar<Foo>` — directive followed by a type.
+      const dir = line.match(/^\s*@(?:model|inherits)\s+([A-Za-z_][\w.]*(?:\s*<[^>]+>)?)/);
+      if (dir) for (const t of this.typeNames(dir[1]!)) this.pushRef(componentId, t, i + 1, 0);
+      // `@inject IService name` — the type is the first token, a name follows.
+      const inj = line.match(/^\s*@inject\s+([A-Za-z_][\w.]*(?:\s*<[^>]+>)?)\s+[A-Za-z_]/);
+      if (inj) for (const t of this.typeNames(inj[1]!)) this.pushRef(componentId, t, i + 1, 0);
+      // `@typeof(X)` anywhere on the line.
+      for (const m of line.matchAll(/@typeof\(\s*([A-Za-z_][\w.]*)\s*\)/g)) {
+        const seg = this.lastSegment(m[1]!);
+        if (/^[A-Z]/.test(seg)) this.pushRef(componentId, seg, i + 1, m.index ?? 0);
+      }
+    }
+  }
+
+  private extractComponentTags(componentId: string): void {
+    const lines = this.source.split('\n');
+    // PascalCase opening / self-closing tags. Closing tags (`</Foo>`) start with
+    // `</` and are skipped. HTML elements are lowercase → never match.
+    const tagRe = /<([A-Z][A-Za-z0-9_]*)\b([^>]*)>/g;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]!;
+      let m: RegExpExecArray | null;
+      while ((m = tagRe.exec(line)) !== null) {
+        const name = m[1]!;
+        if (BLAZOR_BUILTIN_COMPONENTS.has(name)) continue;
+        this.pushRef(componentId, name, i + 1, m.index + 1);
+        // Generic component type arg: `<Grid TItem="CatalogItem">`.
+        for (const t of (m[2] || '').matchAll(/\bT[A-Za-z]*\s*=\s*"([A-Za-z_][\w.]*)"/g)) {
+          const seg = this.lastSegment(t[1]!);
+          if (/^[A-Z]/.test(seg)) this.pushRef(componentId, seg, i + 1, 0);
+        }
+      }
+    }
+  }
+
+  /**
+   * Find the matching `}` for the `{` at `openIdx`, skipping string literals and
+   * comments so a brace inside `"{"` / `// }` doesn't throw off the count.
+   * Returns the index of the closing brace, or -1 if unbalanced.
+   */
+  private matchBrace(src: string, openIdx: number): number {
+    let depth = 0;
+    for (let i = openIdx; i < src.length; i++) {
+      const ch = src[i];
+      if (ch === '"' || ch === "'") {
+        const quote = ch;
+        i++;
+        while (i < src.length && src[i] !== quote) {
+          if (src[i] === '\\') i++;
+          i++;
+        }
+        continue;
+      }
+      if (ch === '/' && src[i + 1] === '/') {
+        while (i < src.length && src[i] !== '\n') i++;
+        continue;
+      }
+      if (ch === '/' && src[i + 1] === '*') {
+        i += 2;
+        while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) i++;
+        i++;
+        continue;
+      }
+      if (ch === '{') depth++;
+      else if (ch === '}') {
+        depth--;
+        if (depth === 0) return i;
+      }
+    }
+    return -1;
+  }
+
+  /** `@code { … }` / `@functions { … }` (Blazor) and `@{ … }` (Razor) C# blocks. */
+  private extractCodeBlocks(): Array<{ content: string; lineOffset: number }> {
+    const blocks: Array<{ content: string; lineOffset: number }> = [];
+    const re = /@(?:code|functions)\b\s*\{|@\{/g;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(this.source)) !== null) {
+      const openIdx = this.source.indexOf('{', m.index);
+      if (openIdx < 0) continue;
+      const close = this.matchBrace(this.source, openIdx);
+      if (close < 0) continue;
+      const content = this.source.slice(openIdx + 1, close);
+      // newlines before the content's first char → 0-indexed line of content start
+      const lineOffset = (this.source.slice(0, openIdx + 1).match(/\n/g) || []).length;
+      blocks.push({ content, lineOffset });
+      re.lastIndex = close;
+    }
+    return blocks;
+  }
+
+  /**
+   * Delegate each `@code`/`@functions`/`@{` block's C# to the tree-sitter C#
+   * extractor and attribute the block's external references (service/DTO calls,
+   * `new X()`, type uses) to the component. The block is wrapped in a synthetic
+   * class so tree-sitter parses the component's fields/methods in a class context
+   * (a Blazor `@code` body compiles into the component's partial class). We keep
+   * only the dependency references — coverage just needs the edges to external
+   * types, not per-member nodes. Degrades gracefully if the C# grammar isn't loaded.
+   */
+  private processCodeBlocks(componentId: string): void {
+    if (!isLanguageSupported('csharp')) return;
+    for (const block of this.extractCodeBlocks()) {
+      if (!block.content.trim()) continue;
+      let result: ExtractionResult;
+      try {
+        result = new TreeSitterExtractor(
+          this.filePath,
+          `class __RazorCode__ {\n${block.content}\n}`,
+          'csharp'
+        ).extract();
+      } catch {
+        continue; // grammar not loaded / parse failure — skip this block
+      }
+      // The synthetic wrapper adds one line before the block content; map ref
+      // lines back to the .razor file (display only — coverage is line-agnostic).
+      for (const ref of result.unresolvedReferences) {
+        this.unresolvedReferences.push({
+          ...ref,
+          fromNodeId: componentId,
+          line: ref.line + block.lineOffset - 1,
+          column: ref.column,
+          filePath: this.filePath,
+          language: 'razor',
+        });
+      }
+    }
+  }
+}
diff --git a/src/extraction/svelte-extractor.ts b/src/extraction/svelte-extractor.ts
index 5586ee343..ab0b93921 100644
--- a/src/extraction/svelte-extractor.ts
+++ b/src/extraction/svelte-extractor.ts
@@ -135,13 +135,16 @@ export class SvelteExtractor {
       // Detect module script
       const isModule = /context\s*=\s*["']module["']/.test(attrs);
 
-      // Calculate start line of the script content (line after <script>)
+      // Calculate the 0-indexed line where the content begins. The content
+      // starts right after the opening tag's `>` — its leading `\n` is part
+      // of the content, so relative line 1 sits ON the tag's closing line
+      // (adding 1 here double-counted the embedded newline and shifted every
+      // script-block symbol down a line).
       const beforeScript = this.source.substring(0, match.index);
       const scriptTagLine = (beforeScript.match(/\n/g) || []).length;
-      // The content starts on the line after the opening <script> tag
       const openingTag = match[0].substring(0, match[0].indexOf('>') + 1);
       const openingTagLines = (openingTag.match(/\n/g) || []).length;
-      const contentStartLine = scriptTagLine + openingTagLines + 1; // 0-indexed line
+      const contentStartLine = scriptTagLine + openingTagLines; // 0-indexed line
 
       blocks.push({
         content,
diff --git a/src/extraction/tree-sitter-helpers.ts b/src/extraction/tree-sitter-helpers.ts
index 0f2dd1bfd..4ffa59570 100644
--- a/src/extraction/tree-sitter-helpers.ts
+++ b/src/extraction/tree-sitter-helpers.ts
@@ -43,11 +43,66 @@ export function getChildByField(node: SyntaxNode, fieldName: string): SyntaxNode
   return node.childForFieldName(fieldName);
 }
 
+/**
+ * Node types that *wrap* a declaration so a leading comment is a sibling of the
+ * wrapper, not of the emitted (inner) declaration node. CodeGraph emits the
+ * inner node, so before looking for its preceding comment we climb out through
+ * these. Examples: `export class X {}` (export_statement), `@dec\ndef f()`
+ * (decorated_definition), `const f = () => {}` (lexical_declaration →
+ * variable_declarator). Each wraps exactly one declaration, so climbing can't
+ * mis-attribute a comment to a sibling. (#780)
+ */
+const DOCSTRING_WRAPPER_TYPES = new Set([
+  'export_statement', // JS/TS: export class/function/const ...
+  'decorated_definition', // Python: @decorator over def/class
+  'lexical_declaration', // JS/TS: const/let x = () => {}
+  'variable_declaration', // JS/TS: var x = ...
+  'variable_declarator', // JS/TS: the `x = () => {}` inside the declaration
+  'ambient_declaration', // TS: declare ...
+]);
+
+/**
+ * Strip comment-syntax markers from a raw comment so the stored docstring is
+ * just the prose. Covers the marker styles across every supported language:
+ * C-family line and block comments and their doc variants, Rust/Swift/Kotlin
+ * triple-slash and bang doc lines, hash lines (Python/Ruby/shell), Lua/Luau
+ * line and long-bracket comments, and Pascal brace and paren-star comments.
+ * (#780)
+ *
+ * Paired block delimiters are stripped only when the comment OPENS with one,
+ * so a line comment that merely happens to END with a closing delimiter is
+ * never truncated. The per-line markers are anchored at line start, so
+ * they're safe to apply to any comment.
+ */
+function cleanCommentMarkers(comment: string): string {
+  let c = comment.trim();
+  if (c.startsWith('/*')) c = c.replace(/^\/\*+!?/, '').replace(/\*+\/$/, '');
+  else if (c.startsWith('--[')) c = c.replace(/^--\[=*\[/, '').replace(/\]=*\]$/, '');
+  else if (c.startsWith('(*')) c = c.replace(/^\(\*/, '').replace(/\*\)$/, '');
+  else if (c.startsWith('{')) c = c.replace(/^\{/, '').replace(/\}$/, '');
+  return c
+    .replace(/^\/\/[/!]?\s?/gm, '') // // , and Rust/Swift doc lines /// //!
+    .replace(/^--\s?/gm, '') //        Lua/Luau line comments
+    .replace(/^#\s?/gm, '') //         Python/Ruby/shell line comments
+    .replace(/^\s*\*\s?/gm, '') //     block-comment continuation (* foo)
+    .trim();
+}
+
 /**
  * Get the docstring/comment preceding a node
  */
 export function getPrecedingDocstring(node: SyntaxNode, source: string): string | undefined {
-  let sibling = node.previousNamedSibling;
+  // Climb out of any wrapper(s) so a comment preceding the WHOLE construct
+  // (export-, decorator-, or const-arrow-wrapped) is reachable as a sibling.
+  // The emitted node's own `previousNamedSibling` is empty (export/const) or a
+  // decorator (Python) in those cases, so without this the docstring was
+  // dropped. (#780)
+  let anchor = node;
+  while (anchor.parent && DOCSTRING_WRAPPER_TYPES.has(anchor.parent.type)) {
+    anchor = anchor.parent;
+  }
+
+  let sibling = anchor.previousNamedSibling;
   const comments: string[] = [];
 
   while (sibling) {
@@ -66,15 +121,6 @@ export function getPrecedingDocstring(node: SyntaxNode, source: string): string
 
   if (comments.length === 0) return undefined;
 
-  // Clean up comment markers
-  return comments
-    .map((c) =>
-      c
-        .replace(/^\/\*\*?|\*\/$/g, '')
-        .replace(/^\/\/\s?/gm, '')
-        .replace(/^\s*\*\s?/gm, '')
-        .trim()
-    )
-    .join('\n')
-    .trim();
+  // Strip each comment's syntax markers (language-aware), then join.
+  return comments.map(cleanCommentMarkers).join('\n').trim();
 }
diff --git a/src/extraction/tree-sitter-types.ts b/src/extraction/tree-sitter-types.ts
index c3a6b94e8..28338b0ac 100644
--- a/src/extraction/tree-sitter-types.ts
+++ b/src/extraction/tree-sitter-types.ts
@@ -78,6 +78,16 @@ export interface ExtractorContext {
  * language-specific details like signatures, visibility, and imports.
  */
 export interface LanguageExtractor {
+  /**
+   * Optional source transform applied immediately before the grammar parses the
+   * file. Used to work around grammar gaps that would otherwise corrupt the
+   * parse tree (e.g. C# blanks conditional-compilation directive lines the
+   * grammar mis-parses inside enum bodies). MUST preserve byte offsets (replace
+   * removed text with spaces, keep newlines) so node positions and getNodeText
+   * stay correct; the returned string is used for both parsing and extraction.
+   */
+  preParse?: (source: string) => string;
+
   // --- Node type mappings ---
 
   /** Node types that represent functions */
@@ -120,6 +130,12 @@ export interface LanguageExtractor {
 
   // --- Existing hooks ---
 
+  /** Override symbol name extraction (e.g. ObjC multi-part selectors). */
+  resolveName?: (node: SyntaxNode, source: string) => string | undefined;
+
+  /** Extract property name when the generic name walk fails (e.g. ObjC @property). */
+  extractPropertyName?: (node: SyntaxNode, source: string) => string | null;
+
   /** Extract signature from node */
   getSignature?: (node: SyntaxNode, source: string) => string | undefined;
   /** Extract visibility from node */
@@ -132,6 +148,14 @@ export interface LanguageExtractor {
   isStatic?: (node: SyntaxNode) => boolean;
   /** Check if variable declaration is a constant (const vs let/var) */
   isConst?: (node: SyntaxNode) => boolean;
+  /**
+   * Extract extra symbol-level modifier keywords to persist on the node's
+   * `decorators` list (e.g. Kotlin `expect`/`actual` multiplatform markers).
+   * Called generically for every created node; return undefined/[] when none.
+   * Used by the resolver to link `expect` declarations to their `actual`
+   * implementations across source sets.
+   */
+  extractModifiers?: (node: SyntaxNode) => string[] | undefined;
 
   // --- New config properties ---
 
@@ -156,6 +180,15 @@ export interface LanguageExtractor {
    */
   classifyClassNode?: (node: SyntaxNode) => 'class' | 'struct' | 'enum' | 'interface' | 'trait';
 
+  /**
+   * Classify a methodTypes node when the grammar reuses one node type for
+   * both callable and data members (#808): TS/JS class FIELDS
+   * (`public_field_definition` / `field_definition`) are methods only when
+   * their value is callable (`onClick = () => {}`); a plain field
+   * (`public fonts: Fonts;`, `count = 0`) is a property. Default: 'method'.
+   */
+  classifyMethodNode?: (node: SyntaxNode) => 'method' | 'property';
+
   /**
    * Resolve the body node for a function/method/class when it's not a child field.
    * (e.g. Dart puts function_body as a sibling, not a child.)
@@ -181,6 +214,15 @@ export interface LanguageExtractor {
    */
   getReceiverType?: (node: SyntaxNode, source: string) => string | undefined;
 
+  /**
+   * Extract a function/method's normalized return type name (bare class name,
+   * smart-pointer pointee unwrapped), stored on the node as `returnType`. Used
+   * by C/C++ so resolution can infer a chained receiver's type from what the
+   * inner call returns (`Foo::instance().bar()` → resolve `bar` on `Foo`,
+   * issue #645). Return undefined for primitives / void / constructors.
+   */
+  getReturnType?: (node: SyntaxNode, source: string) => string | undefined;
+
   /**
    * Resolve the actual node kind for a type alias declaration.
    * Used by Go where `type_spec` is the named declaration wrapper for structs/interfaces:
@@ -206,4 +248,16 @@ export interface LanguageExtractor {
    * Returns the callee name if this node is a bare call, or undefined if not.
    */
   extractBareCall?: (node: SyntaxNode, source: string) => string | undefined;
+
+  /**
+   * Node types representing a file-level package/namespace declaration
+   * (e.g. Kotlin `package_header`, Java `package_declaration`). When set,
+   * the core wraps every top-level declaration in an implicit `namespace`
+   * node carrying the FQN, so cross-file import resolution can match by
+   * qualifiedName instead of filename (Kotlin filename ≠ class name).
+   */
+  packageTypes?: string[];
+
+  /** Extract the dotted package name from a package declaration node. */
+  extractPackage?: (node: SyntaxNode, source: string) => string | null;
 }
diff --git a/src/extraction/tree-sitter.ts b/src/extraction/tree-sitter.ts
index 5a40c75a8..e62f97578 100644
--- a/src/extraction/tree-sitter.ts
+++ b/src/extraction/tree-sitter.ts
@@ -15,14 +15,19 @@ import {
   ExtractionError,
   UnresolvedReference,
 } from '../types';
-import { getParser, detectLanguage, isLanguageSupported } from './grammars';
+import { getParser, detectLanguage, isLanguageSupported, isFileLevelOnlyLanguage } from './grammars';
 import { generateNodeId, getNodeText, getChildByField, getPrecedingDocstring } from './tree-sitter-helpers';
+import { FN_REF_SPECS, captureFnRefCandidates, type FnRefSpec, type FnRefCandidate } from './function-ref';
+import { isGeneratedFile } from './generated-detection';
 import type { LanguageExtractor, ExtractorContext } from './tree-sitter-types';
 import { EXTRACTORS } from './languages';
 import { LiquidExtractor } from './liquid-extractor';
+import { RazorExtractor } from './razor-extractor';
 import { SvelteExtractor } from './svelte-extractor';
+import { AstroExtractor } from './astro-extractor';
 import { DfmExtractor } from './dfm-extractor';
 import { VueExtractor } from './vue-extractor';
+import { MyBatisExtractor } from './mybatis-extractor';
 import {
   getAllFrameworkResolvers,
   getApplicableFrameworks,
@@ -35,6 +40,9 @@ export { generateNodeId } from './tree-sitter-helpers';
  * Extract the name from a node based on language
  */
 function extractName(node: SyntaxNode, source: string, extractor: LanguageExtractor): string {
+  const hookName = extractor.resolveName?.(node, source);
+  if (hookName) return hookName;
+
   // Try field name first
   const nameNode = getChildByField(node, extractor.nameField);
   if (nameNode) {
@@ -111,6 +119,83 @@ function extractName(node: SyntaxNode, source: string, extractor: LanguageExtrac
   return '<anonymous>';
 }
 
+/**
+ * Resolve a Scala type node to its base type NAME for name-matching — unwrapping
+ * `generic_type` (`Monoid[Int]` → `Monoid`), taking the last segment of a
+ * qualified `stable_type_identifier` (`cats.Functor` → `Functor`), and falling
+ * back to a descendant `type_identifier`. Returns null for non-type nodes.
+ * Shared by Scala inheritance and type-reference extraction.
+ */
+function scalaBaseTypeName(node: SyntaxNode | null, source: string): string | null {
+  if (!node) return null;
+  switch (node.type) {
+    case 'type_identifier':
+    case 'identifier':
+      return getNodeText(node, source);
+    case 'generic_type':
+      // `<base> type_arguments` — the base type is the first named child.
+      return scalaBaseTypeName(node.namedChild(0), source);
+    case 'stable_type_identifier':
+    case 'stable_identifier': {
+      // Qualified `a.b.C` — match on the simple (last) segment.
+      const ids = node.namedChildren.filter(
+        (c: SyntaxNode) => c.type === 'type_identifier' || c.type === 'identifier'
+      );
+      const last = ids[ids.length - 1];
+      return last ? getNodeText(last, source) : null;
+    }
+    default: {
+      const id = node.namedChildren.find((c: SyntaxNode) => c.type === 'type_identifier');
+      return id ? getNodeText(id, source) : null;
+    }
+  }
+}
+
+/**
+ * PHP type-position wrapper node kinds (a type-hint is `named_type`,
+ * `?Foo` is `optional_type`, `A|B` is `union_type`, `A&B` is
+ * `intersection_type`). Used to find the type subtree inside a parameter /
+ * property / return position before walking it for class references.
+ */
+const PHP_TYPE_NODES: ReadonlySet<string> = new Set([
+  'named_type', 'optional_type', 'nullable_type',
+  'union_type', 'intersection_type', 'disjunctive_normal_form_type',
+  'primitive_type',
+]);
+
+/**
+ * Member-access node kinds whose receiver, when it's a capitalized
+ * type/enum/class name, is a real dependency — `Enum.value`, `Type.CONST`,
+ * `Foo::BAR`. These VALUE reads (as opposed to `Type.method()` calls, already
+ * handled) produced no edge, so a type used only via a static member or enum
+ * value looked like nothing depended on it. See {@link extractStaticMemberRef}.
+ */
+const MEMBER_ACCESS_TYPES: ReadonlySet<string> = new Set([
+  'field_access',                       // java (`Foo.BAR`)
+  'member_access_expression',           // c#  (`Foo.Bar`)
+  'navigation_expression',              // kotlin / swift (`Foo.bar`)
+  'field_expression',                   // scala (`Foo.bar`)
+  'class_constant_access_expression',   // php (`Foo::CONST`, `Foo::class`)
+  'scoped_property_access_expression',  // php (`Foo::$bar`)
+  'qualified_identifier',               // c++ (`Foo::bar`)
+]);
+
+/**
+ * Languages whose types are Capitalized by convention, so a capitalized
+ * member-access receiver is reliably a type (not a local/variable). The
+ * static-member/value-read pass is gated to these — the ones where it was the
+ * confirmed residual frontier (enum-value / static-field reads). TS/JS/Python
+ * are deliberately excluded, and a measured A/B confirms the call: extending the
+ * pass to them adds ZERO coverage — in import-based languages you must `import` a
+ * type before any `Type.MEMBER` read, so the import edge already covers it (the
+ * static read is pure duplication) — while adding real graph noise (+1813 edges /
+ * +2448 `references` on excalidraw, the retrieval-perf benchmark, all pointing at
+ * already-covered types). Don't re-add `member_expression`/`attribute` here.
+ */
+const STATIC_MEMBER_LANGS: ReadonlySet<string> = new Set([
+  'java', 'csharp', 'kotlin', 'swift', 'scala', 'dart', 'php', 'cpp',
+]);
+
 /**
  * Tree-sitter node kinds that represent constructor invocations
  * (`new Foo()` and friends). Used by extractInstantiation to emit
@@ -120,6 +205,9 @@ const INSTANTIATION_KINDS: ReadonlySet<string> = new Set([
   'new_expression',                  // typescript / javascript / tsx / jsx
   'object_creation_expression',      // java / c#
   'instance_creation_expression',    // some grammars
+  'composite_literal',               // go — `Widget{...}` / `pkga.Widget{...}`
+  'struct_expression',               // rust — `Widget { n: 1 }` / `m::Widget { .. }`
+  'instance_expression',             // scala — `new Monoid[Int] { ... }`
 ]);
 
 /**
@@ -137,12 +225,18 @@ export class TreeSitterExtractor {
   private extractor: LanguageExtractor | null = null;
   private nodeStack: string[] = []; // Stack of parent node IDs
   private methodIndex: Map<string, string> | null = null; // lookup key → node ID for Pascal defProc lookup
+  // Function-as-value capture (#756): per-language spec + candidates collected
+  // during the walk, gated & flushed into unresolvedReferences at end-of-file
+  // (see flushFnRefCandidates).
+  private fnRefSpec: FnRefSpec | undefined;
+  private fnRefCandidates: Array<FnRefCandidate & { fromNodeId: string }> = [];
 
   constructor(filePath: string, source: string, language?: Language) {
     this.filePath = filePath;
     this.source = source;
     this.language = language || detectLanguage(filePath, source);
     this.extractor = EXTRACTORS[this.language] || null;
+    this.fnRefSpec = FN_REF_SPECS[this.language];
   }
 
   /**
@@ -187,6 +281,14 @@ export class TreeSitterExtractor {
     }
 
     try {
+      // Optional pre-parse source transform (offset-preserving) to work around
+      // grammar gaps — e.g. C# blanks conditional-compilation directive lines
+      // the grammar mis-parses inside enum bodies (#237). We reassign
+      // this.source so downstream getNodeText reads the same bytes the parser
+      // saw (identical outside the blanked directive lines).
+      if (this.extractor?.preParse) {
+        this.source = this.extractor.preParse(this.source);
+      }
       this.tree = parser.parse(this.source) ?? null;
       if (!this.tree) {
         throw new Error('Parser returned null tree');
@@ -211,7 +313,21 @@ export class TreeSitterExtractor {
 
       // Push file node onto stack so top-level declarations get contains edges
       this.nodeStack.push(fileNode.id);
+
+      // File-level package declaration (Kotlin/Java). Creates an implicit
+      // `namespace` node wrapping every top-level declaration so their
+      // qualifiedName carries the FQN — required for cross-file import
+      // resolution on JVM languages where filename ≠ class name.
+      const packageNodeId = this.extractFilePackage(this.tree.rootNode);
+      if (packageNodeId) this.nodeStack.push(packageNodeId);
+
       this.visitNode(this.tree.rootNode);
+
+      // Gate + flush function-as-value candidates (#756) while the file's
+      // nodes and import refs are complete and the file node is still pushed.
+      this.flushFnRefCandidates();
+
+      if (packageNodeId) this.nodeStack.pop();
       this.nodeStack.pop();
     } catch (error) {
       const msg = error instanceof Error ? error.message : String(error);
@@ -249,6 +365,157 @@ export class TreeSitterExtractor {
     };
   }
 
+  /**
+   * Function-as-value capture (#756): if this node is one of the language's
+   * value-position containers (call arguments, assignment RHS, struct/object
+   * initializer, array/table literal), collect candidate function names from
+   * it. Candidates are gated & flushed at end-of-file (flushFnRefCandidates).
+   */
+  private maybeCaptureFnRefs(node: SyntaxNode, nodeType: string): void {
+    const spec = this.fnRefSpec;
+    if (!spec) return;
+    const rule = spec.dispatch.get(nodeType);
+    if (!rule || this.nodeStack.length === 0) return;
+    const fromNodeId = this.nodeStack[this.nodeStack.length - 1];
+    if (!fromNodeId) return;
+    for (const cand of captureFnRefCandidates(node, rule, spec, this.source)) {
+      this.fnRefCandidates.push({ ...cand, fromNodeId });
+    }
+  }
+
+  /**
+   * Candidates-only scan of a subtree the main walkers won't traverse
+   * (top-level variable initializers). No extraction side effects. Halts at
+   * nested function definitions: their bodies are walked — and their
+   * candidates attributed — by extractFunction's own body walk.
+   */
+  private scanFnRefSubtree(node: SyntaxNode, depth: number): void {
+    if (!this.fnRefSpec || depth > 12) return;
+    const nodeType = node.type;
+    if (depth > 0 && (
+      this.extractor?.functionTypes.includes(nodeType) ||
+      nodeType === 'arrow_function' ||
+      nodeType === 'function_expression' ||
+      nodeType === 'lambda_literal' ||
+      nodeType === 'lambda_expression'
+    )) {
+      return;
+    }
+    this.maybeCaptureFnRefs(node, nodeType);
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child) this.scanFnRefSubtree(child, depth + 1);
+    }
+  }
+
+  /**
+   * Gate captured function-as-value candidates and push survivors as
+   * `function_ref` unresolved references.
+   *
+   * The gate bounds volume and protects precision: a candidate survives only
+   * if its name matches a function/method DEFINED IN THIS FILE or a name this
+   * file imports/references. Everything else (locals, params, fields passed
+   * as arguments) is dropped before it ever reaches the database. Resolution
+   * then matches survivors against function/method nodes only
+   * (matchFunctionRef) and emits `references` edges — which callers/impact
+   * already traverse.
+   *
+   * Known v1 limit, deliberate: a C/C++ callback registered in a DIFFERENT
+   * translation unit than its definition (extern, no symbol imports to match)
+   * is not captured. Same-file registration — the dominant C pattern (static
+   * callback + same-file ops struct) — is.
+   */
+  private flushFnRefCandidates(): void {
+    if (this.fnRefCandidates.length === 0) return;
+    const candidates = this.fnRefCandidates;
+    this.fnRefCandidates = [];
+
+    // Generated/minified files (vendored jquery.min.js and friends): their
+    // function-as-value edges are noise — single-letter minified symbols
+    // resolve everywhere. Same policy as the callback synthesizer.
+    if (isGeneratedFile(this.filePath)) return;
+
+    const definedHere = new Set<string>();
+    for (const n of this.nodes) {
+      if (n.kind === 'function' || n.kind === 'method') definedHere.add(n.name);
+    }
+
+    // Import-binding names only (all binding emitters push kind 'imports').
+    // Deliberately NOT 'references': those carry type-annotation and
+    // interface-member names, which let local variables that share a type
+    // member's name slip through the gate (excalidraw A/B finding). A dotted
+    // import (JVM `import com.example.OtherClass`) also contributes its LAST
+    // segment — the simple name Java/Kotlin code uses in `OtherClass::method`
+    // references.
+    const SIMPLE_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+    // JVM imports are dotted (`com.example.OtherClass`); PHP `use` imports
+    // are backslashed (`App\Services\Mailer`). Both contribute their last
+    // segment — the simple name code uses to reference them.
+    const QUALIFIED_IMPORT = /^[A-Za-z_$][A-Za-z0-9_$.\\]*[.\\]([A-Za-z_$][A-Za-z0-9_$]*)$/;
+    const importedNames = new Set<string>();
+    for (const r of this.unresolvedReferences) {
+      if (r.referenceKind !== 'imports') continue;
+      if (SIMPLE_NAME.test(r.referenceName)) {
+        importedNames.add(r.referenceName);
+      } else {
+        const qualified = r.referenceName.match(QUALIFIED_IMPORT);
+        if (qualified) importedNames.add(qualified[1]!);
+      }
+    }
+
+    const ungated = this.fnRefSpec?.ungatedModes;
+    const addressOfOnly = this.fnRefSpec?.addressOfOnly === true;
+    const seen = new Set<string>();
+    for (const c of candidates) {
+      const atFileScope = c.fromNodeId.startsWith('file:');
+      // C++ (addressOfOnly): a BARE identifier qualifies only inside a
+      // file-scope initializer table. Everywhere else — args, assignments,
+      // local braced-init lists like `{begin, size}` — only explicit `&`
+      // forms count (fmt A/B finding: generic names `begin`/`out`/`size`
+      // collide with locals and members).
+      if (
+        addressOfOnly &&
+        !c.explicitRef &&
+        !(atFileScope && (c.mode === 'value' || c.mode === 'list'))
+      ) {
+        continue;
+      }
+      // Gate policy by candidate shape:
+      //  - `this.<member>`: ALWAYS flush — the member may be inherited from a
+      //    class in another file (definedHere can't see it), volume is
+      //    naturally bounded by real `this.X` expressions, and resolution is
+      //    strictly class-scoped (own members or the validated supertype
+      //    pass), so nothing fuzzy can leak.
+      //  - `Scope::member` (C++ member-pointers, Java/Kotlin type-qualified
+      //    method refs, PHP `'Cls::m'`): ALWAYS flush — the explicit-ref
+      //    syntax is self-selecting, the referenced type often needs NO
+      //    import (Java/Kotlin same-package, Kotlin companions), and
+      //    resolution is scope-suffix-anchored + unique-or-drop, so a
+      //    same-named member on another class can't match.
+      //  - C-family file-scope initializers skip the gate entirely
+      //    (constant-expression context — see FnRefSpec.ungatedModes).
+      //  - everything else: name ∈ same-file functions/methods ∪ imports.
+      if (!c.name.startsWith('this.') && !c.name.includes('::')) {
+        const skipGate =
+          (ungated?.has(c.mode) === true && atFileScope) ||
+          c.skipGate === true; // PHP HOF-position string callables (see FnRefCandidate.skipGate)
+        if (!skipGate && !definedHere.has(c.name) && !importedNames.has(c.name)) {
+          continue;
+        }
+      }
+      const key = `${c.fromNodeId}|${c.name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      this.unresolvedReferences.push({
+        fromNodeId: c.fromNodeId,
+        referenceName: c.name,
+        referenceKind: 'function_ref',
+        line: c.line,
+        column: c.column,
+      });
+    }
+  }
+
   /**
    * Visit a node and extract information
    */
@@ -262,7 +529,14 @@ export class TreeSitterExtractor {
     if (this.extractor.visitNode) {
       const ctx = this.makeExtractorContext();
       const handled = this.extractor.visitNode(node, ctx);
-      if (handled) return;
+      if (handled) {
+        // The hook consumed this subtree, so the walkers below never descend
+        // into it — scan it for function-as-value candidates (#756). Scala's
+        // hook handles val/var definitions (`val table = Seq(targetCb)`), for
+        // example. The scan is capture-only and halts at nested functions.
+        this.scanFnRefSubtree(node, 0);
+        return;
+      }
     }
 
     // Pascal-specific AST handling
@@ -271,6 +545,11 @@ export class TreeSitterExtractor {
       if (skipChildren) return;
     }
 
+    // Function-as-value capture (#756) — independent of the dispatch ladder
+    // below (the captured container types have no other handler there), so it
+    // can never shadow or be shadowed by an extraction branch.
+    this.maybeCaptureFnRefs(node, nodeType);
+
     // Check for function declarations
     // For Python/Ruby, function_definition inside a class should be treated as method
     if (this.extractor.functionTypes.includes(nodeType)) {
@@ -307,8 +586,30 @@ export class TreeSitterExtractor {
     }
     // Check for method declarations (only if not already handled by functionTypes)
     else if (this.extractor.methodTypes.includes(nodeType)) {
-      this.extractMethod(node);
-      skipChildren = true; // extractMethod visits children via visitFunctionBody
+      // TS/JS class fields parse as a methodTypes node; only function-valued
+      // fields are methods — a plain field (`public fonts: Fonts;`) is a
+      // property (#808). classifyMethodNode is absent for other languages.
+      if (this.extractor.classifyMethodNode?.(node) === 'property') {
+        const propNode = this.extractProperty(node);
+        // Walk the initializer so its calls/instantiations attribute to the
+        // property (`history = createHistory()` → history calls
+        // createHistory). The old field-as-method path never walked these
+        // (resolveBody only resolves function bodies), so this is additive.
+        const valueNode = getChildByField(node, 'value');
+        if (propNode && valueNode) {
+          this.nodeStack.push(propNode.id);
+          this.visitFunctionBody(valueNode, '');
+          this.nodeStack.pop();
+        }
+        // A field initializer can also register callbacks
+        // (`static handlers = { click: onClick }`) — scan it for
+        // function-as-value candidates (capture-only, halts at functions).
+        this.scanFnRefSubtree(node, 0);
+        skipChildren = true;
+      } else {
+        this.extractMethod(node);
+        skipChildren = true; // extractMethod visits children via visitFunctionBody
+      }
     }
     // Check for interface/protocol/trait declarations
     else if (this.extractor.interfaceTypes.includes(nodeType)) {
@@ -334,19 +635,71 @@ export class TreeSitterExtractor {
     // Check for class properties (e.g. C# property_declaration)
     else if (this.extractor.propertyTypes?.includes(nodeType) && this.isInsideClassLikeNode()) {
       this.extractProperty(node);
+      // Property initializers aren't walked — scan for function-as-value
+      // candidates (#756): Scala `val table = Seq(targetCb)` in an object,
+      // Kotlin `val cb = ::handler` class properties.
+      this.scanFnRefSubtree(node, 0);
       skipChildren = true;
     }
     // Check for class fields (e.g. Java field_declaration, C# field_declaration)
     else if (this.extractor.fieldTypes?.includes(nodeType) && this.isInsideClassLikeNode()) {
       this.extractField(node);
+      // Field initializers aren't walked — scan for function-as-value
+      // candidates (#756): Java `List<IntConsumer> table = List.of(Main::cb)`,
+      // C# `List<Action<int>> table = new() { TargetCb }`.
+      this.scanFnRefSubtree(node, 0);
       skipChildren = true;
     }
     // Check for variable declarations (const, let, var, etc.)
     // Only extract top-level variables (not inside functions/methods)
     else if (this.extractor.variableTypes.includes(nodeType) && !this.isInsideClassLikeNode()) {
       this.extractVariable(node);
+      // extractVariable doesn't walk every initializer shape (object literals
+      // are deliberately skipped; Python/Ruby don't walk at all), so scan the
+      // declaration subtree for function-as-value candidates — `const routes =
+      // { home: renderHome }`, `handlers = {"recv": target_cb}`. The scan halts
+      // at nested function definitions (their bodies are walked — and
+      // attributed — separately) and flush-time dedup absorbs any overlap with
+      // initializers extractVariable DOES walk.
+      this.scanFnRefSubtree(node, 0);
       skipChildren = true; // extractVariable handles children
     }
+    // Swift stored properties inside a type. Swift instance properties aren't
+    // extracted as their own nodes, but a property's PROPERTY WRAPPER
+    // (`@Argument`/`@Published`/`@State`/custom) and declared type ARE
+    // dependencies — attribute them to the enclosing type so the wrapper/type
+    // files get dependents. Don't skipChildren: an initializer's calls still
+    // matter. (Other languages extract properties via property/field types.)
+    else if (
+      this.language === 'swift' &&
+      nodeType === 'property_declaration' &&
+      this.isInsideClassLikeNode()
+    ) {
+      const ownerId = this.nodeStack[this.nodeStack.length - 1];
+      if (ownerId) {
+        this.extractDecoratorsFor(node, ownerId);
+        this.extractVariableTypeAnnotation(node, ownerId);
+        // Fluent / SwiftUI property-wrapper attributes often reference a model or
+        // type by metatype in their ARGUMENTS — `@Siblings(through: Pivot.self,
+        // …)`, `@Group(…)`. extractDecoratorsFor captures the wrapper type
+        // (`Siblings`); this pulls the TYPE out of the argument expressions
+        // (`Pivot.self` → a dependency on Pivot), so a model reached ONLY through
+        // a relationship (a many-to-many pivot/join model) isn't left orphaned.
+        // extractStaticMemberRef self-filters to `Type.member` navigation, so the
+        // `\.$keypath` arguments and the wrapper `user_type` are skipped.
+        const modifiers = node.namedChildren.find((c: SyntaxNode) => c.type === 'modifiers');
+        if (modifiers) {
+          const walkAttrArgs = (n: SyntaxNode): void => {
+            this.extractStaticMemberRef(n);
+            for (let i = 0; i < n.namedChildCount; i++) {
+              const c = n.namedChild(i);
+              if (c) walkAttrArgs(c);
+            }
+          };
+          walkAttrArgs(modifiers);
+        }
+      }
+    }
     // `export_statement` itself is not extracted — the walker descends
     // into children, where the inner declaration (lexical_declaration,
     // function_declaration, class_declaration, etc.) is dispatched to
@@ -364,6 +717,22 @@ export class TreeSitterExtractor {
     else if (this.extractor.importTypes.includes(nodeType)) {
       this.extractImport(node);
     }
+    // Re-export from another module — `export { X } from './y'` (TS/JS). A
+    // re-export is a dependency on the source module just like an import, but
+    // the export_statement is otherwise only descended into (no declaration to
+    // extract), so a barrel that ONLY re-exports produced zero edges and showed
+    // 0 dependents. Link each re-exported name to its definition. Children are
+    // still visited (a non-re-export `export const X = …` has no `source` and
+    // falls through to its normal declaration extraction).
+    else if (
+      nodeType === 'export_statement' &&
+      (this.language === 'typescript' || this.language === 'tsx' ||
+       this.language === 'javascript' || this.language === 'jsx') &&
+      getChildByField(node, 'source')
+    ) {
+      const parentId = this.nodeStack[this.nodeStack.length - 1];
+      if (parentId) this.emitReExportRefs(node, parentId);
+    }
     // Check for function calls
     else if (this.extractor.callTypes.includes(nodeType)) {
       this.extractCall(node);
@@ -374,6 +743,17 @@ export class TreeSitterExtractor {
     // their own `calls` refs.
     else if (INSTANTIATION_KINDS.has(nodeType)) {
       this.extractInstantiation(node);
+      // Java/C# `new T(...) { ... }` — anonymous class with body. Without
+      // extracting it as a class node + its methods, the interface→impl
+      // synthesizer (Phase 5.5) can't bridge T's abstract methods to the
+      // anonymous overrides, and an agent investigating a call through T
+      // (`strategy.iterator(...)` where strategy is a Strategy lambda body)
+      // has to Read the file to find the actual implementation.
+      const anonBody = this.findAnonymousClassBody(node);
+      if (anonBody) {
+        this.extractAnonymousClass(node, anonBody);
+        skipChildren = true;
+      }
     }
     // (Decorator handling lives inside the symbol-creating extractors
     // — extractClass / extractFunction / extractProperty — because the
@@ -383,6 +763,22 @@ export class TreeSitterExtractor {
     else if (nodeType === 'impl_item') {
       this.extractRustImplItem(node);
     }
+    // TypeScript interface members: property_signature (`foo: T`, `foo?: T`)
+    // and method_signature (`foo(arg: A): R`) both carry type annotations the
+    // interface walker would otherwise drop. Extract them as `references`
+    // edges from the interface so resolvers can wire callers/impact for
+    // types that only appear in interface members.
+    else if (
+      (nodeType === 'property_signature' || nodeType === 'method_signature') &&
+      this.isInsideClassLikeNode() &&
+      this.TYPE_ANNOTATION_LANGUAGES.has(this.language)
+    ) {
+      const parentId = this.nodeStack[this.nodeStack.length - 1];
+      if (parentId) {
+        this.extractTypeAnnotations(node, parentId);
+      }
+      // don't skipChildren — nested signatures still need traversal
+    }
 
     // Visit children (unless the extract method already visited them)
     if (!skipChildren) {
@@ -412,6 +808,20 @@ export class TreeSitterExtractor {
 
     const id = generateNodeId(this.filePath, kind, name, node.startPosition.row + 1);
 
+    // Some grammars (e.g. Dart) model a function/method body as a *sibling* of
+    // the signature node, so the declaration node's own range is just the
+    // signature line. Extend endLine to the resolved body when it sits beyond
+    // the node so the node spans its body — required for any body-level analysis
+    // (callees, the callback synthesizer's body scan, context slices). Guarded to
+    // only ever extend: for child-body grammars the body is within range (no-op).
+    let endLine = node.endPosition.row + 1;
+    if (kind === 'function' || kind === 'method') {
+      const body = this.extractor?.resolveBody?.(node, this.extractor.bodyField);
+      if (body && body.endPosition.row + 1 > endLine) {
+        endLine = body.endPosition.row + 1;
+      }
+    }
+
     const newNode: Node = {
       id,
       kind,
@@ -420,13 +830,22 @@ export class TreeSitterExtractor {
       filePath: this.filePath,
       language: this.language,
       startLine: node.startPosition.row + 1,
-      endLine: node.endPosition.row + 1,
+      endLine,
       startColumn: node.startPosition.column,
       endColumn: node.endPosition.column,
       updatedAt: Date.now(),
       ...extra,
     };
 
+    // Persist extra symbol-level modifiers (e.g. Kotlin `expect`/`actual`) onto
+    // the node's decorators list so the resolver can pair multiplatform
+    // declarations with their implementations. Merged, not overwritten, so a
+    // language that also captures real annotations keeps both.
+    const mods = this.extractor?.extractModifiers?.(node);
+    if (mods && mods.length > 0) {
+      newNode.decorators = [...(newNode.decorators ?? []), ...mods];
+    }
+
     this.nodes.push(newNode);
 
     // Add containment edge from parent
@@ -456,6 +875,33 @@ export class TreeSitterExtractor {
     return null;
   }
 
+  /**
+   * Find a `packageTypes` child under the root, create a `namespace` node
+   * for it, and return its id so the caller can scope top-level
+   * declarations underneath. Returns null when no package header is
+   * present (script files, .kts without a package).
+   */
+  private extractFilePackage(rootNode: SyntaxNode): string | null {
+    const types = this.extractor?.packageTypes;
+    if (!types || types.length === 0 || !this.extractor?.extractPackage) return null;
+
+    let pkgNode: SyntaxNode | null = null;
+    for (let i = 0; i < rootNode.namedChildCount; i++) {
+      const child = rootNode.namedChild(i);
+      if (child && types.includes(child.type)) {
+        pkgNode = child;
+        break;
+      }
+    }
+    if (!pkgNode) return null;
+
+    const pkgName = this.extractor.extractPackage(pkgNode, this.source);
+    if (!pkgName) return null;
+
+    const ns = this.createNode('namespace', pkgName, pkgNode);
+    return ns?.id ?? null;
+  }
+
   /**
    * Build qualified name from node stack
    */
@@ -516,7 +962,7 @@ export class TreeSitterExtractor {
   /**
    * Extract a function
    */
-  private extractFunction(node: SyntaxNode): void {
+  private extractFunction(node: SyntaxNode, nameOverride?: string): void {
     if (!this.extractor) return;
 
     // If the language provides getReceiverType and this function has a receiver
@@ -526,12 +972,17 @@ export class TreeSitterExtractor {
       return;
     }
 
-    let name = extractName(node, this.source, this.extractor);
+    // nameOverride is supplied only for explicitly-named anonymous functions the
+    // caller resolved itself (e.g. arrow values of exported-const object members
+    // — SvelteKit actions). Inline-object arrows reached by the general walker
+    // get no override, so they still fall through to the <anonymous> skip below.
+    let name = nameOverride ?? extractName(node, this.source, this.extractor);
     // For arrow functions and function expressions assigned to variables,
     // resolve the name from the parent variable_declarator.
     // e.g. `export const useAuth = () => { ... }` — the arrow_function node
     // has no `name` field; the name lives on the variable_declarator.
     if (
+      !nameOverride &&
       name === '<anonymous>' &&
       (node.type === 'arrow_function' || node.type === 'function_expression')
     ) {
@@ -543,7 +994,19 @@ export class TreeSitterExtractor {
         }
       }
     }
-    if (name === '<anonymous>') return; // Skip anonymous functions
+    if (name === '<anonymous>') {
+      // Don't emit a node for the anonymous wrapper itself, but still visit its
+      // body: AMD/RequireJS and CommonJS module wrappers (`define([], function(){…})`,
+      // `(function(){…})()`) hold named inner functions and calls that would
+      // otherwise be lost — the dispatcher set skipChildren, so nothing else
+      // descends into this subtree. (#528)
+      const body = this.extractor.resolveBody?.(node, this.extractor.bodyField)
+        ?? getChildByField(node, this.extractor.bodyField);
+      if (body) {
+        this.visitFunctionBody(body, '');
+      }
+      return;
+    }
 
     // Check for misparse artifacts (e.g. C++ macros causing "namespace detail" functions)
     // Skip the node but still visit the body for calls and structural nodes
@@ -562,6 +1025,7 @@ export class TreeSitterExtractor {
     const isExported = this.extractor.isExported?.(node, this.source);
     const isAsync = this.extractor.isAsync?.(node);
     const isStatic = this.extractor.isStatic?.(node);
+    const returnType = this.extractor.getReturnType?.(node, this.source);
 
     const funcNode = this.createNode('function', name, node, {
       docstring,
@@ -570,6 +1034,7 @@ export class TreeSitterExtractor {
       isExported,
       isAsync,
       isStatic,
+      returnType,
     });
     if (!funcNode) return;
 
@@ -612,6 +1077,9 @@ export class TreeSitterExtractor {
     // Extract extends/implements
     this.extractInheritance(node, classNode.id);
 
+    // C# primary-constructor parameter dependencies (`class Svc(IRepo r, …)`).
+    this.extractCsharpPrimaryCtorParamRefs(node, classNode.id);
+
     // Extract decorators applied to the class (`@Foo class X {}`).
     this.extractDecoratorsFor(node, classNode.id);
 
@@ -649,6 +1117,11 @@ export class TreeSitterExtractor {
       // in inline objects). These are ephemeral and create noise (e.g., Svelte context
       // objects: `ctx.set({ get view() { ... } })`).
       if (node.parent?.type === 'object' || node.parent?.type === 'object_expression') {
+        const body = this.extractor.resolveBody?.(node, this.extractor.bodyField)
+          ?? getChildByField(node, this.extractor.bodyField);
+        if (body) {
+          this.visitFunctionBody(body, '');
+        }
         return;
       }
       // Not inside a class-like node and no receiver type, treat as function
@@ -673,12 +1146,14 @@ export class TreeSitterExtractor {
     const visibility = this.extractor.getVisibility?.(node);
     const isAsync = this.extractor.isAsync?.(node);
     const isStatic = this.extractor.isStatic?.(node);
+    const returnType = this.extractor.getReturnType?.(node, this.source);
     const extraProps: Partial<Node> = {
       docstring,
       signature,
       visibility,
       isAsync,
       isStatic,
+      returnType,
     };
     if (receiverType) {
       extraProps.qualifiedName = `${receiverType}::${name}`;
@@ -781,6 +1256,10 @@ export class TreeSitterExtractor {
     // Extract inheritance (e.g. Swift: struct HTTPMethod: RawRepresentable)
     this.extractInheritance(node, structNode.id);
 
+    // C# primary-constructor parameter dependencies (`struct P(int x)`, and
+    // `record struct M(decimal Amount)` which the grammar nests here).
+    this.extractCsharpPrimaryCtorParamRefs(node, structNode.id);
+
     // Push to stack for field extraction
     this.nodeStack.push(structNode.id);
     for (let i = 0; i < body.namedChildCount; i++) {
@@ -867,27 +1346,41 @@ export class TreeSitterExtractor {
    * Extract a class property declaration (e.g. C# `public string Name { get; set; }`).
    * Extracts as 'property' kind node inside the owning class.
    */
-  private extractProperty(node: SyntaxNode): void {
-    if (!this.extractor) return;
+  private extractProperty(node: SyntaxNode): Node | null {
+    if (!this.extractor) return null;
 
     const docstring = getPrecedingDocstring(node, this.source);
     const visibility = this.extractor.getVisibility?.(node);
     const isStatic = this.extractor.isStatic?.(node) ?? false;
 
-    // Property name is a direct identifier child
-    const nameNode = getChildByField(node, 'name')
-      || node.namedChildren.find(c => c.type === 'identifier');
-    if (!nameNode) return;
-
-    const name = getNodeText(nameNode, this.source);
-
-    // Get property type from the type child (first named child that isn't modifier or identifier)
-    const typeNode = node.namedChildren.find(
-      c => c.type !== 'modifier' && c.type !== 'modifiers'
-        && c.type !== 'identifier' && c.type !== 'accessor_list'
-        && c.type !== 'accessors' && c.type !== 'equals_value_clause'
-    );
-    const typeText = typeNode ? getNodeText(typeNode, this.source) : undefined;
+    const hookName = this.extractor.extractPropertyName?.(node, this.source);
+    // JS `field_definition` names its key the `property` field (TS uses
+    // `name`) — try both before the generic identifier scan (#808).
+    const nameNode = hookName
+      ? null
+      : getChildByField(node, 'name') ||
+        getChildByField(node, 'property') ||
+        node.namedChildren.find(c => c.type === 'identifier');
+    const name = hookName ?? (nameNode ? getNodeText(nameNode, this.source) : null);
+    if (!name) return null;
+
+    // Get property type. TS/JS field definitions carry an explicit `type`
+    // field (a `type_annotation`); their other named children are the name
+    // and the initializer VALUE, which the generic finder below would
+    // wrongly pick — so fields use the type field only (#808). Other
+    // languages (C# property_declaration) keep the generic scan.
+    const isTsJsField =
+      node.type === 'public_field_definition' || node.type === 'field_definition';
+    const typeNode = isTsJsField
+      ? getChildByField(node, 'type')
+      : node.namedChildren.find(
+          c => c.type !== 'modifier' && c.type !== 'modifiers'
+            && c.type !== 'identifier' && c.type !== 'accessor_list'
+            && c.type !== 'accessors' && c.type !== 'equals_value_clause'
+        );
+    const typeText = typeNode
+      ? getNodeText(typeNode, this.source).replace(/^:\s*/, '')
+      : undefined;
     const signature = typeText ? `${typeText} ${name}` : name;
 
     const propNode = this.createNode('property', name, node, {
@@ -901,7 +1394,12 @@ export class TreeSitterExtractor {
     // decorator->target relationship for class properties too.
     if (propNode) {
       this.extractDecoratorsFor(node, propNode.id);
+      // Emit `references` edges from the property to types named in its
+      // type annotation (#381). The generic walker handles TS-style
+      // `type_annotation` children; the C# branch walks the `type` field.
+      this.extractTypeAnnotations(node, propNode.id);
     }
+    return propNode;
   }
 
   /**
@@ -983,7 +1481,15 @@ export class TreeSitterExtractor {
         });
         // Java/Kotlin annotations / TS field decorators sit on the
         // outer field_declaration, not on the individual declarator.
-        if (fieldNode) this.extractDecoratorsFor(node, fieldNode.id);
+        if (fieldNode) {
+          this.extractDecoratorsFor(node, fieldNode.id);
+          // Same as properties: emit `references` to the field's annotated
+          // type. The outer `field_declaration` is the right scope to
+          // search from — C# carries the `type` inside `variable_declaration`
+          // and the language-aware path in `extractTypeAnnotations` descends
+          // into that wrapper (#381).
+          this.extractTypeAnnotations(node, fieldNode.id);
+        }
       }
     } else {
       // Fallback: try to find an identifier child directly
@@ -1000,6 +1506,102 @@ export class TreeSitterExtractor {
     }
   }
 
+  /**
+   * Extract function-valued properties of an object literal as named function
+   * nodes (named by their property key). Shared by the two object-of-functions
+   * shapes in extractVariable: the object as a direct const value, and the
+   * object returned by a store-initializer call. Handles both `key: () => {}` /
+   * `key: function() {}` pairs and method shorthand `key() {}`.
+   */
+  private extractObjectLiteralFunctions(obj: SyntaxNode): void {
+    for (let i = 0; i < obj.namedChildCount; i++) {
+      const member = obj.namedChild(i);
+      if (!member) continue;
+      if (member.type === 'pair') {
+        const key = getChildByField(member, 'key');
+        const value = getChildByField(member, 'value');
+        if (key && value && (value.type === 'arrow_function' || value.type === 'function_expression')) {
+          this.extractFunction(value, this.objectKeyName(key));
+        }
+      } else if (member.type === 'method_definition') {
+        // Method shorthand: `{ fetchUser() {...} }`. extractMethod deliberately
+        // skips object-literal methods, so route through extractFunction with an
+        // explicit name (method_definition exposes a `body` field, so resolveBody
+        // falls through to it and the node spans the full method).
+        const key = getChildByField(member, 'name');
+        if (key) this.extractFunction(member, this.objectKeyName(key));
+      }
+    }
+  }
+
+  /** Property-key text with surrounding quotes stripped (`'foo'` → `foo`). */
+  private objectKeyName(key: SyntaxNode): string {
+    return getNodeText(key, this.source).replace(/^['"`]|['"`]$/g, '');
+  }
+
+  /**
+   * Given a `call_expression` initializer (`create((set, get) => ({...}))`),
+   * find the object literal RETURNED by a function argument — descending through
+   * nested call_expression arguments so middleware wrappers are unwrapped
+   * (`create(persist((set, get) => ({...}), {...}))`, devtools, immer,
+   * subscribeWithSelector). Returns null when no such object is found — the
+   * common case for ordinary call initializers — so this stays cheap and silent
+   * rather than guessing. Keyed purely on AST shape; no library names.
+   */
+  private findInitializerReturnedObject(callNode: SyntaxNode, depth = 0): SyntaxNode | null {
+    if (depth > 4) return null;
+    const args = getChildByField(callNode, 'arguments');
+    if (!args) return null;
+    for (let i = 0; i < args.namedChildCount; i++) {
+      const arg = args.namedChild(i);
+      if (!arg) continue;
+      if (arg.type === 'arrow_function' || arg.type === 'function_expression') {
+        const obj = this.functionReturnedObject(arg);
+        if (obj) return obj;
+      } else if (arg.type === 'call_expression') {
+        const obj = this.findInitializerReturnedObject(arg, depth + 1);
+        if (obj) return obj;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * The object literal a function expression returns — either the `=> ({...})`
+   * arrow form (a parenthesized_expression wrapping an object) or a
+   * `=> { return {...} }` block. Returns null for any other body shape.
+   */
+  private functionReturnedObject(fnNode: SyntaxNode): SyntaxNode | null {
+    const body = getChildByField(fnNode, 'body');
+    if (!body) return null;
+    const asObject = (n: SyntaxNode | null): SyntaxNode | null => {
+      if (!n) return null;
+      if (n.type === 'object' || n.type === 'object_expression') return n;
+      if (n.type === 'parenthesized_expression') {
+        for (let i = 0; i < n.namedChildCount; i++) {
+          const inner = asObject(n.namedChild(i));
+          if (inner) return inner;
+        }
+      }
+      return null;
+    };
+    // `(set, get) => ({...})` — body is the (parenthesized) object directly.
+    const direct = asObject(body);
+    if (direct) return direct;
+    // `(set, get) => { return {...} }` — scan top-level return statements.
+    if (body.type === 'statement_block') {
+      for (let i = 0; i < body.namedChildCount; i++) {
+        const stmt = body.namedChild(i);
+        if (stmt?.type !== 'return_statement') continue;
+        for (let j = 0; j < stmt.namedChildCount; j++) {
+          const obj = asObject(stmt.namedChild(j));
+          if (obj) return obj;
+        }
+      }
+    }
+    return null;
+  }
+
   /**
    * Extract a variable declaration (const, let, var, etc.)
    *
@@ -1057,6 +1659,46 @@ export class TreeSitterExtractor {
             if (varNode) {
               this.extractVariableTypeAnnotation(child, varNode.id);
             }
+
+            // Exported const object-of-functions — extract each function-valued
+            // property as a function named by its key + walk its body so its
+            // calls are captured. Two shapes, both keyed on AST shape (not on any
+            // library name):
+            //   `export const actions = { default: async () => {} }` — object is
+            //     the DIRECT value (SvelteKit form actions / handler maps / route
+            //     tables).
+            //   `export const useStore = create((set, get) => ({ fetchUser:
+            //     async () => {} }))` — object is RETURNED by an initializer call,
+            //     possibly through middleware wrappers (persist/devtools/immer).
+            //     Covers Zustand/Redux/Pinia/MobX stores generically. Without
+            //     this, store actions exist only as object-literal properties —
+            //     never nodes — so `node`/`callers` on `fetchUser` return "not
+            //     found" and the agent Reads the store to reconstruct the flow.
+            // Scoped to EXPORTED consts to exclude inline-object noise
+            // (`ctx.set({...})`) the object-method skip deliberately avoids.
+            const objectOfFns =
+              valueNode && (valueNode.type === 'object' || valueNode.type === 'object_expression')
+                ? valueNode
+                : valueNode?.type === 'call_expression'
+                  ? this.findInitializerReturnedObject(valueNode)
+                  : null;
+            const extractObjectMethods = isExported && !!objectOfFns;
+
+            // Visit the initializer body for calls — EXCEPT object literals (their
+            // function-valued properties are extracted below) and the store-factory
+            // call whose returned object we extract method-by-method below (walking
+            // the whole call would re-visit those method arrows and mis-attribute
+            // their inner calls to the file/module scope).
+            if (valueNode &&
+                valueNode.type !== 'object' &&
+                valueNode.type !== 'object_expression' &&
+                !(extractObjectMethods && valueNode.type === 'call_expression')) {
+              this.visitFunctionBody(valueNode, '');
+            }
+
+            if (extractObjectMethods && objectOfFns) {
+              this.extractObjectLiteralFunctions(objectOfFns);
+            }
           }
         }
       }
@@ -1086,17 +1728,33 @@ export class TreeSitterExtractor {
 
       for (const spec of specs) {
         const nameNode = spec.namedChild(0);
+        let varNode: Node | null = null;
         if (nameNode && nameNode.type === 'identifier') {
           const name = getNodeText(nameNode, this.source);
           const valueNode = spec.namedChildCount > 1 ? spec.namedChild(spec.namedChildCount - 1) : null;
           const initValue = valueNode ? getNodeText(valueNode, this.source).slice(0, 100) : undefined;
           const initSignature = initValue ? `= ${initValue}${initValue.length >= 100 ? '...' : ''}` : undefined;
 
-          this.createNode(node.type === 'const_declaration' ? 'constant' : 'variable', name, spec, {
+          varNode = this.createNode(node.type === 'const_declaration' ? 'constant' : 'variable', name, spec, {
             docstring,
             signature: initSignature,
           });
         }
+        // Walk the initializer so composite literals and calls in a
+        // package-level `var Query Binding = queryBinding{}` (a registry of
+        // implementations) or `var c = pkg.New()` are extracted as
+        // instantiates/calls dependencies — the body walker only covers
+        // initializers inside functions, not these top-level declarations.
+        // Scope the walk to the declared symbol so a call inside an anonymous
+        // func_literal initializer — a cobra `RunE: func(){…}` handler, a
+        // goroutine or callback closure — attributes to the var instead of
+        // leaking to the file node (which reads as "no caller"), issue #693.
+        const valueField = getChildByField(spec, 'value');
+        if (valueField) {
+          if (varNode) this.nodeStack.push(varNode.id);
+          this.visitFunctionBody(valueField, varNode?.id ?? '');
+          if (varNode) this.nodeStack.pop();
+        }
       }
 
       // Handle short_var_declaration (:=)
@@ -1233,6 +1891,13 @@ export class TreeSitterExtractor {
       // Extract interface inheritance from the inner type node
       const typeChild = getChildByField(node, 'type');
       if (typeChild) this.extractInheritance(typeChild, interfaceNode.id);
+      // Go: extract the interface's method specs as `method` nodes so implicit
+      // interface satisfaction (a struct's method set ⊇ the interface's) and
+      // impl-navigation can see the contract. Go has no `implements` keyword, so
+      // without the interface's method set there's nothing to match against.
+      if (this.language === 'go' && typeChild) {
+        this.extractGoInterfaceMethods(typeChild, interfaceNode.id);
+      }
       return true;
     }
 
@@ -1248,8 +1913,182 @@ export class TreeSitterExtractor {
       const value = getChildByField(node, 'value');
       if (value) {
         this.extractTypeRefsFromSubtree(value, typeAliasNode.id);
+        // `type X = { foo: T; bar(): T }` — make the members first-class
+        // property/method nodes under the type alias so `recorder.stop()`
+        // can attach the call edge to `RecorderHandle.stop` instead of
+        // an unrelated class method picked by path-proximity (#359).
+        if (this.language === 'typescript' || this.language === 'tsx') {
+          this.extractTsTypeAliasMembers(value, typeAliasNode);
+          // `type List = [ Service<'name', Req, Resp>, … ]` — surface each
+          // entry's string-literal name as a searchable member (issue #634).
+          this.extractTsTupleContractNames(value, typeAliasNode);
+        }
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Extract the method specs of a Go `interface_type` body as `method` nodes
+   * contained by the interface (e.g. `Marshal`, `Unmarshal` of a `Core`
+   * interface). tree-sitter-go names these `method_elem` (newer) or
+   * `method_spec` (older). Embedded interfaces (`Reader` inside `ReadWriter`)
+   * are `type_identifier`s, not methods, and are left to inheritance extraction.
+   */
+  private extractGoInterfaceMethods(interfaceType: SyntaxNode, ifaceId: string): void {
+    this.nodeStack.push(ifaceId);
+    for (let i = 0; i < interfaceType.namedChildCount; i++) {
+      const m = interfaceType.namedChild(i);
+      if (!m || (m.type !== 'method_elem' && m.type !== 'method_spec')) continue;
+      const nameNode = getChildByField(m, 'name') ?? m.namedChild(0);
+      if (!nameNode) continue;
+      const mname = getNodeText(nameNode, this.source);
+      if (mname) {
+        this.createNode('method', mname, m, {
+          signature: this.extractor?.getSignature?.(m, this.source),
+        });
+      }
+    }
+    this.nodeStack.pop();
+  }
+
+  /**
+   * Surface the members of a TypeScript `type X = { ... }` (or intersection
+   * thereof) as `property` / `method` nodes under the type-alias node. Only
+   * walks the immediate object_type / intersection operands so anonymous
+   * nested object types inside generic arguments (`Promise<{ ok: true }>`)
+   * don't produce phantom members.
+   */
+  private extractTsTypeAliasMembers(value: SyntaxNode, typeAliasNode: Node): void {
+    const objectTypes: SyntaxNode[] = [];
+    if (value.type === 'object_type') {
+      objectTypes.push(value);
+    } else if (value.type === 'intersection_type') {
+      for (let i = 0; i < value.namedChildCount; i++) {
+        const op = value.namedChild(i);
+        if (op && op.type === 'object_type') objectTypes.push(op);
+      }
+    } else {
+      return;
+    }
+
+    this.nodeStack.push(typeAliasNode.id);
+    for (const objType of objectTypes) {
+      for (let i = 0; i < objType.namedChildCount; i++) {
+        const child = objType.namedChild(i);
+        if (!child) continue;
+        if (child.type !== 'property_signature' && child.type !== 'method_signature') continue;
+
+        const nameNode = getChildByField(child, 'name');
+        const memberName = nameNode ? getNodeText(nameNode, this.source) : '';
+        if (!memberName) continue;
+
+        // `foo: () => T` and `foo(): T` are functionally a method on the
+        // type contract. Treat the property_signature with a function-typed
+        // annotation as a method too so call sites can resolve to it.
+        const memberKind: NodeKind = child.type === 'method_signature'
+          ? 'method'
+          : this.isTsFunctionTypedProperty(child) ? 'method' : 'property';
+
+        const docstring = getPrecedingDocstring(child, this.source);
+        const signature = getNodeText(child, this.source);
+        this.createNode(memberKind, memberName, child, {
+          docstring,
+          signature,
+          qualifiedName: `${typeAliasNode.name}::${memberName}`,
+        });
+
+        // Emit `references` edges from the type alias to types named in the
+        // member's signature, matching the interface-member behavior added in
+        // #432. We attach refs to the type-alias parent (consistent with
+        // interface property_signature treatment).
+        this.extractTypeAnnotations(child, typeAliasNode.id);
+      }
+    }
+    this.nodeStack.pop();
+  }
+
+  /**
+   * Surface the string-literal "names" of a TypeScript service/contract
+   * registry written as a tuple of generic instantiations:
+   *
+   *   type MyServiceList = [
+   *     Service<'query_apply_record', Req, Resp>,
+   *     Service<'apply_confirm', Req, Resp>,
+   *   ];
+   *
+   * Each `Service<'name', …>` tags an entry with a string-literal name that a
+   * dynamic factory (`createService<MyServiceList>()`) turns into a callable
+   * property (`api.query_apply_record(…)`). Static extraction otherwise never
+   * sees that name — it's a type argument, not a declaration — so
+   * `codegraph query query_apply_record` returned nothing (issue #634). We emit
+   * each name as a `method` node under the type alias (qualifiedName
+   * `MyServiceList::query_apply_record`) so it's searchable and resolvable as a
+   * symbol. (A call through the proxy, `api.query_apply_record(…)`, still
+   * resolves to the imported `api` binding — the receiver's type isn't known —
+   * so this fixes discoverability, not the per-method call edge.)
+   *
+   * Scope is deliberately narrow to avoid noise: only a string literal that is
+   * a DIRECT type argument of a `generic_type` that is itself a DIRECT element
+   * of a `tuple_type`. This excludes utility types (`Pick`/`Omit`/`Record` are
+   * never written as tuples) and string args nested deeper
+   * (`Service<'a', Pick<U, 'id'>>` yields only `a`, never `id`). Names must be
+   * valid identifiers, which also rules out route paths / arbitrary strings.
+   */
+  private extractTsTupleContractNames(value: SyntaxNode, typeAliasNode: Node): void {
+    const tuples: SyntaxNode[] = [];
+    const collectTuples = (n: SyntaxNode, depth: number): void => {
+      if (depth > 6) return; // a type expression is shallow; cap defensively
+      if (n.type === 'tuple_type') tuples.push(n);
+      for (let i = 0; i < n.namedChildCount; i++) {
+        const c = n.namedChild(i);
+        if (c) collectTuples(c, depth + 1);
+      }
+    };
+    collectTuples(value, 0);
+    if (tuples.length === 0) return;
+
+    this.nodeStack.push(typeAliasNode.id);
+    for (const tuple of tuples) {
+      for (let i = 0; i < tuple.namedChildCount; i++) {
+        const entry = tuple.namedChild(i);
+        if (!entry || entry.type !== 'generic_type') continue;
+        const typeArgs = getChildByField(entry, 'type_arguments');
+        if (!typeArgs) continue;
+        for (let j = 0; j < typeArgs.namedChildCount; j++) {
+          const arg = typeArgs.namedChild(j);
+          if (!arg || arg.type !== 'literal_type') continue;
+          // literal_type wraps the actual literal; only a string is a name.
+          const strNode = arg.namedChild(0);
+          if (!strNode || strNode.type !== 'string') continue;
+          const name = getNodeText(strNode, this.source)
+            .trim()
+            .replace(/^['"`]/, '')
+            .replace(/['"`]$/, '');
+          if (!/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name)) continue;
+          const signature = getNodeText(entry, this.source).replace(/\s+/g, ' ').trim().slice(0, 120);
+          this.createNode('method', name, entry, {
+            signature,
+            qualifiedName: `${typeAliasNode.name}::${name}`,
+          });
+        }
       }
     }
+    this.nodeStack.pop();
+  }
+
+  /**
+   * `foo: () => T` → property_signature whose type_annotation contains a
+   * `function_type`. Treat that as a method-shaped contract member, since
+   * the call site `obj.foo()` has identical semantics to `bar(): T`.
+   */
+  private isTsFunctionTypedProperty(propertySignature: SyntaxNode): boolean {
+    const typeAnno = getChildByField(propertySignature, 'type');
+    if (!typeAnno) return false;
+    for (let i = 0; i < typeAnno.namedChildCount; i++) {
+      const inner = typeAnno.namedChild(i);
+      if (inner && inner.type === 'function_type') return true;
+    }
     return false;
   }
 
@@ -1290,6 +2129,45 @@ export class TreeSitterExtractor {
             });
           }
         }
+        // Link each imported binding to its definition so imported-but-not-
+        // called/typed symbols still record a cross-file dependency (TS/JS only).
+        if (
+          this.language === 'typescript' || this.language === 'tsx' ||
+          this.language === 'javascript' || this.language === 'jsx'
+        ) {
+          const parentId = this.nodeStack[this.nodeStack.length - 1];
+          if (parentId) this.emitImportBindingRefs(node, parentId);
+        }
+        // Python `from module import X, Y` — link each imported name to its
+        // definition (covers `__init__.py` re-export barrels, which are just
+        // `from .sub import X`). Same recall gap as TS: a name imported and
+        // used in a non-call position created no dependency edge.
+        if (this.language === 'python' && node.type === 'import_from_statement') {
+          const parentId = this.nodeStack[this.nodeStack.length - 1];
+          if (parentId) this.emitPyFromImportRefs(node, parentId);
+        }
+        // Rust `use crate::m::Item;` / `pub use self::sub::Item;` — link each
+        // imported leaf to its definition. Covers `pub use` re-export hubs
+        // (a `mod.rs` re-exporting submodule items, e.g. tokio's `fs/mod.rs`)
+        // and items imported but used in non-call/non-type positions.
+        if (this.language === 'rust' && node.type === 'use_declaration') {
+          const parentId = this.nodeStack[this.nodeStack.length - 1];
+          if (parentId) this.emitRustUseBindingRefs(node, parentId);
+        }
+        // PHP `use Foo\Bar\Baz;` — link to the namespace-qualified definition so
+        // an imported-but-DI-injected contract (Laravel's pattern) records a
+        // cross-file dependency. Grouped imports are handled in their own branch.
+        if (this.language === 'php' && node.type === 'namespace_use_declaration') {
+          const parentId = this.nodeStack[this.nodeStack.length - 1];
+          if (parentId) this.emitPhpUseRefs(node, parentId);
+        }
+        // Ruby `require "lib/foo"` / `require_relative "../foo"` — resolve to the
+        // required FILE so a file pulled in only by `require` (config-loaded
+        // components, gems that don't autoload) records a cross-file dependency.
+        if (this.language === 'ruby' && node.type === 'call') {
+          const parentId = this.nodeStack[this.nodeStack.length - 1];
+          if (parentId) this.emitRubyRequireRefs(node, parentId);
+        }
         return;
       }
       // Hook returned null — fall through to multi-import inline handlers only
@@ -1301,18 +2179,37 @@ export class TreeSitterExtractor {
 
     // Python import_statement: import os, sys (creates one import per module)
     if (this.language === 'python' && node.type === 'import_statement') {
+      const importParentId = this.nodeStack[this.nodeStack.length - 1];
+      // A bare `import a.b.c` of an internal module (the standard Django
+      // `AppConfig.ready(): import myapp.signals` registration pattern, and any
+      // `import pkg.mod` used for its side effects) had no edge to the module
+      // file — only `from x import y` was linked. Push an `imports` ref (like
+      // Go) so the resolver maps the dotted path to its file. Stdlib/external
+      // modules naturally don't resolve (no `os.py` file node in the repo).
+      const pushModuleRef = (dotted: SyntaxNode): void => {
+        if (!importParentId) return;
+        this.unresolvedReferences.push({
+          fromNodeId: importParentId,
+          referenceName: getNodeText(dotted, this.source),
+          referenceKind: 'imports',
+          line: dotted.startPosition.row + 1,
+          column: dotted.startPosition.column,
+        });
+      };
       for (let i = 0; i < node.namedChildCount; i++) {
         const child = node.namedChild(i);
         if (child?.type === 'dotted_name') {
           this.createNode('import', getNodeText(child, this.source), node, {
             signature: importText,
           });
+          pushModuleRef(child);
         } else if (child?.type === 'aliased_import') {
           const dottedName = child.namedChildren.find(c => c.type === 'dotted_name');
           if (dottedName) {
             this.createNode('import', getNodeText(dottedName, this.source), node, {
               signature: importText,
             });
+            pushModuleRef(dottedName);
           }
         }
       }
@@ -1377,6 +2274,8 @@ export class TreeSitterExtractor {
             this.createNode('import', fullPath, node, {
               signature: importText,
             });
+            const parentId = this.nodeStack[this.nodeStack.length - 1];
+            if (parentId) this.pushPhpUseRef(fullPath, parentId, node);
           }
         }
         return;
@@ -1393,47 +2292,466 @@ export class TreeSitterExtractor {
   }
 
   /**
-   * Extract a function call
+   * Emit one `imports` reference per named/default import binding (TS/JS family),
+   * attributed to the file node — so the resolver links each imported symbol to
+   * the file that DEFINES it.
+   *
+   * Importing a symbol IS a dependency, but extraction only emits references for
+   * calls, instantiations, type annotations, and inheritance. A symbol that's
+   * imported and then only re-exported (`export { X } from './x'`), placed in a
+   * registry array (`[expressResolver, …]`), passed as an argument, or used in
+   * JSX produced NO cross-file edge at all — so the providing file showed a
+   * false "0 dependents" and was invisible to blast-radius / `affected`. The
+   * resolver maps the local name (alias-aware) to the provider's definition and
+   * creates a cross-file `imports` edge; `getFileDependents` picks it up, while
+   * `getImpactRadius` keeps it as a bounded leaf (the importing file node).
+   *
+   * Namespace imports (`import * as NS`) bind a whole module: `NS.member` calls
+   * resolve on their own, but a namespace used ONLY via a value-member read
+   * (`NS.SOME_CONST`) would leave no edge — so we also emit the namespace local
+   * name, which the resolver links to the module FILE as a dependency backstop.
    */
-  private extractCall(node: SyntaxNode): void {
-    if (this.nodeStack.length === 0) return;
-
-    const callerId = this.nodeStack[this.nodeStack.length - 1];
-    if (!callerId) return;
-
-    // Get the function/method being called
-    let calleeName = '';
-
-    // Java/Kotlin method_invocation has 'object' + 'name' fields instead of 'function'
-    // PHP member_call_expression has 'object' + 'name', scoped_call_expression has 'scope' + 'name'
-    const nameField = getChildByField(node, 'name');
-    const objectField = getChildByField(node, 'object') || getChildByField(node, 'scope');
+  private emitImportBindingRefs(node: SyntaxNode, fromNodeId: string): void {
+    const clause = node.namedChildren.find((c) => c.type === 'import_clause');
+    if (!clause) return; // side-effect import (`import './x'`) — no bindings
 
-    if (nameField && objectField && (node.type === 'method_invocation' || node.type === 'member_call_expression' || node.type === 'scoped_call_expression')) {
-      // Method call with explicit receiver: receiver.method() / $receiver->method() / ClassName::method()
-      const methodName = getNodeText(nameField, this.source);
-      let receiverName = getNodeText(objectField, this.source);
-      // Strip PHP $ prefix from variable names
-      receiverName = receiverName.replace(/^\$/, '');
+    const pushRef = (nameNode: SyntaxNode | null | undefined): void => {
+      if (!nameNode) return;
+      const name = getNodeText(nameNode, this.source);
+      if (!name) return;
+      this.unresolvedReferences.push({
+        fromNodeId,
+        referenceName: name,
+        referenceKind: 'imports',
+        line: nameNode.startPosition.row + 1,
+        column: nameNode.startPosition.column,
+      });
+    };
 
-      if (methodName) {
-        // Skip self/this/parent/static receivers — they don't aid resolution
-        const SKIP_RECEIVERS = new Set(['self', 'this', 'cls', 'super', 'parent', 'static']);
-        if (SKIP_RECEIVERS.has(receiverName)) {
-          calleeName = methodName;
-        } else {
-          calleeName = `${receiverName}.${methodName}`;
+    for (const child of clause.namedChildren) {
+      if (child.type === 'identifier') {
+        // default import: `import Foo from './x'`
+        pushRef(child);
+      } else if (child.type === 'named_imports') {
+        // `import { A, B as C } from './x'` — link the LOCAL name (alias if any)
+        for (const spec of child.namedChildren) {
+          if (spec.type !== 'import_specifier') continue;
+          pushRef(getChildByField(spec, 'alias') ?? getChildByField(spec, 'name') ?? spec.namedChild(0));
         }
+      } else if (child.type === 'namespace_import') {
+        // `import * as NS from './x'` — emit NS so the module-import backstop can
+        // record the file dependency even if NS is only used by value-member read.
+        pushRef(child.namedChildren.find((c) => c.type === 'identifier') ?? child.namedChild(0));
       }
-    } else {
-      const func = getChildByField(node, 'function') || node.namedChild(0);
+    }
+  }
 
-      if (func) {
-        if (func.type === 'member_expression' || func.type === 'attribute' || func.type === 'selector_expression' || func.type === 'navigation_expression') {
-          // Method call: obj.method() or obj.field.method()
-          // Go uses selector_expression with 'field', JS/TS uses member_expression with 'property'
-          // Kotlin uses navigation_expression with navigation_suffix > simple_identifier
-          let property = getChildByField(func, 'property') || getChildByField(func, 'field');
+  /**
+   * Emit one `imports` reference per re-exported binding of a
+   * `export { A, B as C } from './y'` statement, attributed to the file node —
+   * so a barrel that re-exports from another module records a dependency on it.
+   *
+   * Links the SOURCE-side name (`A`, the `name` field — not the local alias
+   * `C`), since that is what the source module defines. `export * from './y'`
+   * has no named bindings to attribute and `export { default as X }` can't be
+   * name-matched, so both are skipped.
+   */
+  private emitReExportRefs(node: SyntaxNode, fromNodeId: string): void {
+    const clause = node.namedChildren.find((c) => c.type === 'export_clause');
+    if (!clause) return; // `export * from './y'` — no named bindings
+    for (const spec of clause.namedChildren) {
+      if (spec.type !== 'export_specifier') continue;
+      const nameNode = getChildByField(spec, 'name') ?? spec.namedChild(0);
+      if (!nameNode) continue;
+      const name = getNodeText(nameNode, this.source);
+      if (!name || name === 'default') continue;
+      this.unresolvedReferences.push({
+        fromNodeId,
+        referenceName: name,
+        referenceKind: 'imports',
+        line: nameNode.startPosition.row + 1,
+        column: nameNode.startPosition.column,
+      });
+    }
+  }
+
+  /**
+   * Emit one `imports` reference per binding of a Rust `use` declaration —
+   * `use crate::m::Item`, `use crate::m::{A, B as C}`, `pub use self::sub::Item`.
+   * Emits the FULL path (e.g. `self::sub::Item`, not just `Item`) so the resolver
+   * can resolve the module prefix to a file and find the leaf symbol there —
+   * disambiguating common-name re-exports (`pub use self::read::read`, where the
+   * leaf `read` collides with many same-named symbols). Falls back to name-match
+   * on the leaf when the path can't be resolved. `use ...::*` has no leaf binding.
+   */
+  private emitRustUseBindingRefs(node: SyntaxNode, fromNodeId: string): void {
+    const paths: { text: string; node: SyntaxNode }[] = [];
+    const join = (prefix: string, seg: string): string => (prefix ? `${prefix}::${seg}` : seg);
+    const collect = (n: SyntaxNode, prefix: string): void => {
+      switch (n.type) {
+        case 'identifier':
+          paths.push({ text: join(prefix, getNodeText(n, this.source)), node: n });
+          break;
+        case 'scoped_identifier': {
+          // Full scoped path (`a::b::C`); combine with any outer group prefix.
+          const full = getNodeText(n, this.source).trim();
+          paths.push({ text: prefix ? `${prefix}::${full}` : full, node: n });
+          break;
+        }
+        case 'scoped_use_list': {
+          // `path::{ ... }` — the group's path becomes the prefix for each item.
+          const pathNode = getChildByField(n, 'path');
+          const seg = pathNode ? getNodeText(pathNode, this.source).trim() : '';
+          const newPrefix = seg ? join(prefix, seg) : prefix;
+          const list = getChildByField(n, 'list') ?? n.namedChildren.find((c) => c.type === 'use_list');
+          if (list) collect(list, newPrefix);
+          break;
+        }
+        case 'use_list':
+          for (let i = 0; i < n.namedChildCount; i++) {
+            const c = n.namedChild(i);
+            if (c) collect(c, prefix);
+          }
+          break;
+        case 'use_as_clause': {
+          // `Path as Alias` → link the source path (the definition), not the alias.
+          const p = getChildByField(n, 'path') ?? n.namedChild(0);
+          if (p) collect(p, prefix);
+          break;
+        }
+        // use_wildcard → no specific binding to link.
+      }
+    };
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const c = node.namedChild(i);
+      if (c) collect(c, '');
+    }
+    for (const p of paths) {
+      // The leaf must be a real name (skip a path that is only `self`/`super`/`crate`).
+      const leaf = p.text.split('::').pop();
+      if (!leaf || leaf === 'self' || leaf === 'super' || leaf === 'crate' || leaf === '*') continue;
+      this.unresolvedReferences.push({
+        fromNodeId,
+        referenceName: p.text,
+        referenceKind: 'imports',
+        line: p.node.startPosition.row + 1,
+        column: p.node.startPosition.column,
+      });
+    }
+  }
+
+  /**
+   * Emit an `imports` reference for a single PHP `use Foo\Bar\Baz;` (grouped
+   * imports `use Foo\{A, B}` are handled where their per-item nodes are created).
+   * The reference targets the namespace-qualified `Foo\Bar::Baz` form classes are
+   * stored under (see the PHP `namespace` capture), so it resolves to the RIGHT
+   * definition — Laravel has many same-named contracts (`Factory`, `Dispatcher`,
+   * `Guard`) across namespaces that a bare-name match can't disambiguate.
+   */
+  private emitPhpUseRefs(node: SyntaxNode, fromNodeId: string): void {
+    const clause = node.namedChildren.find((c: SyntaxNode) => c.type === 'namespace_use_clause');
+    if (!clause) return;
+    const qn = clause.namedChildren.find((c: SyntaxNode) => c.type === 'qualified_name')
+      ?? clause.namedChildren.find((c: SyntaxNode) => c.type === 'name');
+    if (qn) this.pushPhpUseRef(getNodeText(qn, this.source), fromNodeId, node);
+  }
+
+  /**
+   * Ruby `require`/`require_relative` → an `imports` ref to the required FILE.
+   * `require "sidekiq/fetch"` is load-path-relative (matched by file-path suffix
+   * via {@link matchByFilePath}); `require_relative "../foo"` is resolved against
+   * this file's directory. Bare gem/stdlib requires (`require "json"`, no slash)
+   * are skipped — they're external. The path form (a `/` + `.rb`) makes the ref
+   * resolve to the file node, so a file pulled in only by `require` — not by a
+   * resolved constant/call — still records a cross-file dependency.
+   */
+  private emitRubyRequireRefs(node: SyntaxNode, fromNodeId: string): void {
+    const method = node.namedChildren.find((c: SyntaxNode) => c.type === 'identifier');
+    const mname = method ? getNodeText(method, this.source) : '';
+    if (mname !== 'require' && mname !== 'require_relative') return;
+    const argList = node.namedChildren.find((c: SyntaxNode) => c.type === 'argument_list');
+    const str = argList?.namedChildren.find((c: SyntaxNode) => c.type === 'string');
+    const content = str?.namedChildren.find((c: SyntaxNode) => c.type === 'string_content');
+    if (!content) return;
+    const req = getNodeText(content, this.source).trim();
+    if (!req) return;
+
+    let refPath: string;
+    if (mname === 'require_relative') {
+      const slash = this.filePath.lastIndexOf('/');
+      const dir = slash >= 0 ? this.filePath.slice(0, slash) : '';
+      refPath = path.posix.normalize(dir ? `${dir}/${req}` : req);
+    } else {
+      refPath = req; // load-path require — suffix-matched against the file path
+    }
+    if (!refPath.includes('/')) return; // bare gem/stdlib require — external
+    if (!refPath.endsWith('.rb')) refPath += '.rb';
+    this.unresolvedReferences.push({
+      fromNodeId,
+      referenceName: refPath,
+      referenceKind: 'imports',
+      line: node.startPosition.row + 1,
+      column: node.startPosition.column,
+    });
+  }
+
+  /** Convert a PHP FQN `Foo\Bar\Baz` to the stored `Foo\Bar::Baz` and emit an `imports` ref. */
+  private pushPhpUseRef(fqn: string, fromNodeId: string, node: SyntaxNode): void {
+    const clean = fqn.replace(/^\\/, '');
+    const lastSep = clean.lastIndexOf('\\');
+    if (lastSep < 0) return; // global-namespace class — already matches by simple name
+    this.unresolvedReferences.push({
+      fromNodeId,
+      referenceName: `${clean.slice(0, lastSep)}::${clean.slice(lastSep + 1)}`,
+      referenceKind: 'imports',
+      line: node.startPosition.row + 1,
+      column: node.startPosition.column,
+    });
+  }
+
+  /**
+   * Emit one `imports` reference per name imported in a Python
+   * `from module import A, B as C` statement, attributed to the file node — so
+   * the resolver links each imported name to the module that DEFINES it.
+   *
+   * Same recall gap as TS: extraction only emitted references for calls,
+   * instantiations, and inheritance, so a name imported and then used in a
+   * non-call position (a list/dict literal, a default argument, a decorator
+   * target, or simply re-exported through an `__init__.py` barrel) produced no
+   * cross-file edge — the providing module showed a false "0 dependents". Links
+   * the LOCAL name (alias when present, since that's what the resolver's import
+   * mapping keys on); `from module import *` has no names to attribute.
+   */
+  private emitPyFromImportRefs(node: SyntaxNode, fromNodeId: string): void {
+    const moduleNameNode = getChildByField(node, 'module_name');
+    for (const child of node.namedChildren) {
+      // Skip the `from <module>` part itself and `import *`.
+      if (moduleNameNode &&
+          child.startIndex === moduleNameNode.startIndex &&
+          child.endIndex === moduleNameNode.endIndex) continue;
+      if (child.type === 'wildcard_import') continue;
+
+      let nameNode: SyntaxNode | null | undefined = null;
+      if (child.type === 'aliased_import') {
+        nameNode = getChildByField(child, 'alias') ?? getChildByField(child, 'name') ?? child.namedChild(0);
+      } else if (child.type === 'dotted_name') {
+        nameNode = child;
+      }
+      if (!nameNode) continue;
+
+      const raw = getNodeText(nameNode, this.source);
+      // Imported names are simple identifiers; defensively take the last segment.
+      const local = raw.includes('.') ? raw.split('.').pop()! : raw;
+      if (!local) continue;
+      this.unresolvedReferences.push({
+        fromNodeId,
+        referenceName: local,
+        referenceKind: 'imports',
+        line: nameNode.startPosition.row + 1,
+        column: nameNode.startPosition.column,
+      });
+    }
+  }
+
+  /**
+   * Extract a function call
+   */
+  private extractCall(node: SyntaxNode): void {
+    if (this.nodeStack.length === 0) return;
+
+    const callerId = this.nodeStack[this.nodeStack.length - 1];
+    if (!callerId) return;
+
+    // Get the function/method being called
+    let calleeName = '';
+
+    // Java/Kotlin method_invocation has 'object' + 'name' fields instead of 'function'
+    // PHP member_call_expression has 'object' + 'name', scoped_call_expression has 'scope' + 'name'
+    const nameField = getChildByField(node, 'name');
+    const objectField = getChildByField(node, 'object') || getChildByField(node, 'scope');
+
+    if (nameField && objectField && (node.type === 'method_invocation' || node.type === 'member_call_expression' || node.type === 'scoped_call_expression')) {
+      // Method call with explicit receiver: receiver.method() / $receiver->method() / ClassName::method()
+      const methodName = getNodeText(nameField, this.source);
+      // Java `this.userbo.toLogin2()` parses as method_invocation(object=field_access(this, userbo)).
+      // Without unwrapping, receiverName is `this.userbo` and the name-matcher's
+      // single-dot receiver regex fails. Pull out the immediate field after `this.`
+      // so the receiver is the field name (`userbo`), which the resolver can then
+      // look up in the enclosing class's field declarations.
+      // PHP static-factory fluent chain: `Cls::for($x)->method()` — the receiver
+      // is itself a static call, so resolution must infer the method's class
+      // from what `Cls::for` RETURNS (its `: self` / `: static` / `: Type`),
+      // #608 (mirrors the C++ chain fix in #645). Encode `<Cls::factory>().<method>`;
+      // the `().` marker lets the PHP resolver split it. The receiver text
+      // (`Cls::for('x')`) carries the args, so without this it degrades to an
+      // unresolvable string and the call edge is dropped.
+      if (methodName && this.language === 'php' && objectField.type === 'scoped_call_expression') {
+        const innerScope = getChildByField(objectField, 'scope');
+        const innerName = getChildByField(objectField, 'name');
+        if (innerScope && innerName) {
+          calleeName = `${getNodeText(innerScope, this.source)}::${getNodeText(innerName, this.source)}().${methodName}`;
+        } else {
+          calleeName = methodName;
+        }
+        if (calleeName) {
+          this.unresolvedReferences.push({
+            fromNodeId: callerId,
+            referenceName: calleeName,
+            referenceKind: 'calls',
+            line: node.startPosition.row + 1,
+            column: node.startPosition.column,
+          });
+        }
+        return;
+      }
+
+      // Java static-factory / fluent chain: `Foo.getInstance().bar()` — the
+      // receiver is itself a method call, so resolution must infer bar's class
+      // from what `Foo.getInstance` RETURNS (its declared return type), the
+      // #645/#608 mechanism. Encode `<inner-receiver>.<inner-method>().<method>`;
+      // the `().` marker lets the Java chain resolver split it, and normalizing to
+      // empty parens drops any factory args (`Foo.create(cfg).bar()`) that would
+      // otherwise leave a `(cfg)` in the receiver text and break the split.
+      if (
+        methodName &&
+        this.language === 'java' &&
+        objectField.type === 'method_invocation'
+      ) {
+        const innerObj = getChildByField(objectField, 'object');
+        const innerName = getChildByField(objectField, 'name');
+        if (innerObj && innerName) {
+          calleeName = `${getNodeText(innerObj, this.source)}.${getNodeText(innerName, this.source)}().${methodName}`;
+          this.unresolvedReferences.push({
+            fromNodeId: callerId,
+            referenceName: calleeName,
+            referenceKind: 'calls',
+            line: node.startPosition.row + 1,
+            column: node.startPosition.column,
+          });
+          return;
+        }
+      }
+
+      let receiverName: string;
+      if (objectField.type === 'field_access') {
+        const inner = getChildByField(objectField, 'object');
+        const fld = getChildByField(objectField, 'field');
+        if (inner && fld && (inner.type === 'this' || inner.type === 'this_expression')) {
+          receiverName = getNodeText(fld, this.source);
+        } else {
+          receiverName = getNodeText(objectField, this.source);
+        }
+      } else {
+        receiverName = getNodeText(objectField, this.source);
+      }
+      // Strip PHP $ prefix from variable names
+      receiverName = receiverName.replace(/^\$/, '');
+
+      if (methodName) {
+        // Skip self/this/parent/static receivers — they don't aid resolution
+        const SKIP_RECEIVERS = new Set(['self', 'this', 'cls', 'super', 'parent', 'static']);
+        if (SKIP_RECEIVERS.has(receiverName)) {
+          calleeName = methodName;
+        } else {
+          calleeName = `${receiverName}.${methodName}`;
+        }
+      }
+    } else if (node.type === 'message_expression') {
+      // ObjC message expressions emit one `method` field child per selector
+      // keyword: `[obj a:1 b:2 c:3]` has three `method=identifier` siblings.
+      // Joining them with `:` reconstructs the full selector and matches the
+      // multi-part selector names produced by the ObjC method_definition
+      // extractor (`extractObjcMethodName` in languages/objc.ts). Without this
+      // join, multi-keyword call sites only emitted the first keyword and never
+      // resolved to their target methods (e.g. `GET:parameters:headers:...` had
+      // zero callers despite obviously being called).
+      const methodKeywords: string[] = [];
+      for (let i = 0; i < node.namedChildCount; i++) {
+        if (node.fieldNameForNamedChild(i) === 'method') {
+          const kw = node.namedChild(i);
+          if (kw) methodKeywords.push(getNodeText(kw, this.source));
+        }
+      }
+      if (methodKeywords.length > 0) {
+        // A selector keyword takes a `:` when it has an argument. A SINGLE
+        // keyword can be unary (`[c reset]` → `reset`) OR take one argument
+        // (`[c storeImage:k]` → `storeImage:`) — distinguished by whether the
+        // message has a `:` token. Without this, every single-argument message
+        // (the most common form: `addObject:`, `storeImage:`, …) was named
+        // without the colon and never matched its `storeImage:` method.
+        let hasColon = false;
+        for (let i = 0; i < node.childCount; i++) {
+          if (node.child(i)?.type === ':') { hasColon = true; break; }
+        }
+        const methodName: string = hasColon
+          ? methodKeywords.map((k) => `${k}:`).join('')
+          : (methodKeywords[0] as string);
+        const receiverField = getChildByField(node, 'receiver');
+        const SKIP_RECEIVERS = new Set(['self', 'super']);
+        if (receiverField && receiverField.type !== 'message_expression') {
+          const receiverName = getNodeText(receiverField, this.source);
+          if (receiverName && !SKIP_RECEIVERS.has(receiverName)) {
+            calleeName = `${receiverName}.${methodName}`;
+            // A CLASS-message receiver (`[SDImageCache alloc]`,
+            // `[SDImageCache sharedCache]`) is a capitalized class name. The
+            // call resolves the method (`alloc`/`sharedCache`), but the CLASS
+            // itself — whose @interface lives in the header — would otherwise
+            // never be referenced. Emit a `references` edge to it so a class
+            // used only via class messages (alloc/init, singletons, factories)
+            // and its header record a dependent.
+            if (/^[A-Z][A-Za-z0-9_]*$/.test(receiverName)) {
+              this.unresolvedReferences.push({
+                fromNodeId: callerId,
+                referenceName: receiverName,
+                referenceKind: 'references',
+                line: receiverField.startPosition.row + 1,
+                column: receiverField.startPosition.column,
+              });
+            }
+          } else {
+            calleeName = methodName;
+          }
+        } else if (receiverField && receiverField.type === 'message_expression' && /^\w+$/.test(methodName)) {
+          // Chained message send `[[Foo create] doIt]` — the receiver is itself a
+          // class message. Recover the inner `Class.selector` and encode
+          // `Class.selector().doIt` so resolution infers doIt's class from what
+          // `Class.selector` RETURNS (#645/#608). Only a CLASS-factory chain
+          // (capitalized inner receiver); a unary outer selector is required
+          // because the chain resolver's method part is `\w+` (no `:`). An
+          // instance chain (`[[obj foo] bar]`, lowercase inner) stays bare.
+          const innerRecv = getChildByField(receiverField, 'receiver');
+          const innerRecvName = innerRecv ? getNodeText(innerRecv, this.source) : '';
+          if (innerRecv?.type === 'identifier' && /^[A-Z]/.test(innerRecvName)) {
+            const innerKw: string[] = [];
+            for (let i = 0; i < receiverField.namedChildCount; i++) {
+              if (receiverField.fieldNameForNamedChild(i) === 'method') {
+                const kw = receiverField.namedChild(i);
+                if (kw) innerKw.push(getNodeText(kw, this.source));
+              }
+            }
+            let innerColon = false;
+            for (let i = 0; i < receiverField.childCount; i++) {
+              if (receiverField.child(i)?.type === ':') { innerColon = true; break; }
+            }
+            const innerSelector = innerColon ? innerKw.map((k) => `${k}:`).join('') : innerKw[0];
+            calleeName = innerSelector ? `${innerRecvName}.${innerSelector}().${methodName}` : methodName;
+          } else {
+            calleeName = methodName;
+          }
+        } else {
+          calleeName = methodName;
+        }
+      }
+    } else {
+      const func = getChildByField(node, 'function') || node.namedChild(0);
+
+      if (func) {
+        if (func.type === 'member_expression' || func.type === 'attribute' || func.type === 'selector_expression' || func.type === 'navigation_expression' || func.type === 'field_expression') {
+          // Method call: obj.method() or obj.field.method()
+          // Go uses selector_expression with 'field', JS/TS uses member_expression with 'property'
+          // Kotlin uses navigation_expression with navigation_suffix > simple_identifier
+          // C/C++ use field_expression for both `obj.method()` and `ptr->method()`
+          let property = getChildByField(func, 'property') || getChildByField(func, 'field');
           if (!property) {
             const child1 = func.namedChild(1);
             // Kotlin: navigation_suffix wraps the method name — extract simple_identifier from it
@@ -1449,15 +2767,76 @@ export class TreeSitterExtractor {
             // This helps the resolver distinguish method calls from bare function calls
             // (e.g., Python's console.print() vs builtin print())
             // Skip self/this/cls as they don't aid resolution
-            const receiver = getChildByField(func, 'object') || getChildByField(func, 'operand') || func.namedChild(0);
+            const receiver =
+              getChildByField(func, 'object') ||
+              getChildByField(func, 'operand') ||
+              getChildByField(func, 'argument') ||
+              func.namedChild(0);
             const SKIP_RECEIVERS = new Set(['self', 'this', 'cls', 'super']);
-            if (receiver && (receiver.type === 'identifier' || receiver.type === 'simple_identifier')) {
+            if (receiver && (receiver.type === 'identifier' || receiver.type === 'simple_identifier' || receiver.type === 'field_identifier')) {
               const receiverName = getNodeText(receiver, this.source);
               if (!SKIP_RECEIVERS.has(receiverName)) {
                 calleeName = `${receiverName}.${methodName}`;
               } else {
                 calleeName = methodName;
               }
+            } else if (
+              (this.language === 'cpp' ||
+                this.language === 'c' ||
+                this.language === 'kotlin' ||
+                this.language === 'swift' ||
+                this.language === 'rust' ||
+                this.language === 'go' ||
+                this.language === 'scala') &&
+              receiver &&
+              receiver.type === 'call_expression'
+            ) {
+              // Receiver that is itself a call — `Foo::instance().bar()`,
+              // `openSession()->run()`, `mgr.view().render()` (C/C++),
+              // `Foo.getInstance().bar()` (Kotlin) / `Foo.make().draw()` (Swift),
+              // `Foo::new().bar()` (Rust), or `New().Method()` (Go). Keep the inner
+              // call so resolution can infer bar()'s class from what the inner call
+              // RETURNS (#645/#608). Encode as `<innerCallee>().<method>`; the `().`
+              // marker never appears in an ordinary ref, so the resolver can detect
+              // and split it. Other languages keep the bare-name behavior below.
+              let innerCallee: string;
+              let reencode: boolean;
+              if (this.language === 'kotlin' || this.language === 'swift') {
+                // tree-sitter-kotlin/swift expose the inner callee as the
+                // call_expression's first named child (a navigation_expression
+                // `Foo.getInstance`, or a bare identifier for a free/constructor call).
+                const innerNav = receiver.namedChild(0);
+                innerCallee = innerNav ? getNodeText(innerNav, this.source).replace(/\s+/g, '') : '';
+                // Only re-encode a CLASS / companion-factory / constructor chain,
+                // whose receiver chain starts with a capitalized type
+                // (`Foo.getInstance().bar()`, `Foo().bar()`). An instance chain
+                // (`list.filter{}.map{}`) has a lowercase receiver whose type we
+                // can't recover here — re-encoding it would only drop the edge (no
+                // chain resolution, no bare-name fallback), regressing recall in
+                // fluent codebases. Leave those to the bare-name path.
+                reencode = /^[A-Z]/.test(innerCallee);
+              } else {
+                const innerFn = getChildByField(receiver, 'function');
+                innerCallee = innerFn
+                  ? getNodeText(innerFn, this.source).replace(/->/g, '.').replace(/\s+/g, '')
+                  : '';
+                // Rust: only re-encode an associated-function chain
+                // (`Foo::new().bar()`), whose inner callee is a path/`scoped_identifier`.
+                // Go: only a bare package-level factory chain (`New().Method()`),
+                // whose inner callee is an `identifier`. An instance chain
+                // (`x.foo().bar()` Rust, `obj.Method().Other()` Go) keeps bare-name —
+                // the resolver can't recover a variable's type, so re-encoding would
+                // only drop the edge. C/C++ re-encode any inner.
+                if (this.language === 'rust') reencode = innerFn?.type === 'scoped_identifier';
+                else if (this.language === 'go') reencode = innerFn?.type === 'identifier';
+                // Scala: only a companion-factory / case-class-apply chain whose
+                // receiver chain starts with a capitalized type (`Foo.create().bar()`,
+                // `Foo(args).bar()`). An instance chain (`list.map().filter()`) has a
+                // lowercase receiver whose type we can't recover — leave it bare.
+                else if (this.language === 'scala') reencode = /^[A-Z]/.test(innerCallee);
+                else reencode = !!innerCallee;
+              }
+              calleeName = reencode ? `${innerCallee}().${methodName}` : methodName;
             } else {
               calleeName = methodName;
             }
@@ -1465,12 +2844,38 @@ export class TreeSitterExtractor {
         } else if (func.type === 'scoped_identifier' || func.type === 'scoped_call_expression') {
           // Scoped call: Module::function()
           calleeName = getNodeText(func, this.source);
+        } else if (this.language === 'csharp' && func.type === 'member_access_expression') {
+          // C# member call `recv.Method(...)`. When the receiver is itself a call
+          // — a chained factory `Foo.Create(args).Bar()` — encode `inner().Bar`
+          // with normalized empty parens so resolution can infer Bar's class from
+          // what `Foo.Create` RETURNS (#645/#608). A non-call receiver keeps the
+          // full member-access text (the existing `recv.Method` behavior).
+          const recv = getChildByField(func, 'expression');
+          const nameNode = getChildByField(func, 'name');
+          const methodName = nameNode ? getNodeText(nameNode, this.source) : '';
+          if (recv && recv.type === 'invocation_expression' && methodName) {
+            const innerFunc = getChildByField(recv, 'function');
+            const innerCallee = innerFunc ? getNodeText(innerFunc, this.source).replace(/\s+/g, '') : '';
+            calleeName = innerCallee ? `${innerCallee}().${methodName}` : methodName;
+          } else {
+            calleeName = getNodeText(func, this.source);
+          }
         } else {
           calleeName = getNodeText(func, this.source);
         }
       }
     }
 
+    // Parenthesized type conversions — Go `(*T)(x)` / `(T)(x)` (and a
+    // parenthesized callee generally) parse as a call whose "function" is a
+    // parenthesized type/expression, so the callee text is the un-resolvable
+    // literal `(*T)`. Normalize to the inner name so it resolves to `T` (a real
+    // dependency on the converted-to type) instead of dropping on the floor.
+    if (calleeName) {
+      const conv = calleeName.match(/^\(\s*\*?\s*([A-Za-z_][\w.]*)\s*\)$/);
+      if (conv && conv[1]) calleeName = conv[1];
+    }
+
     if (calleeName) {
       this.unresolvedReferences.push({
         fromNodeId: callerId,
@@ -1505,6 +2910,46 @@ export class TreeSitterExtractor {
       node.namedChild(0);
     if (!ctor) return;
 
+    // Go composite literals: `Widget{...}` (same package) and `pkga.Widget{...}`
+    // (cross-package). Only a directly-named struct type is a meaningful
+    // instantiation target — skip slice/map/array literals (`[]T{}`,
+    // `map[K]V{}`) whose `type` field is a composite type, not a named type.
+    // Unlike `new ns.Foo()`, KEEP the package qualifier (`pkga.Widget`) so the
+    // Go cross-package resolver can disambiguate it to the right package's type.
+    if (node.type === 'composite_literal') {
+      if (ctor.type !== 'type_identifier' && ctor.type !== 'qualified_type') return;
+      let goType = getNodeText(ctor, this.source).trim();
+      const brIdx = goType.indexOf('['); // strip Go generic args: `Box[T]{}` -> `Box`
+      if (brIdx > 0) goType = goType.slice(0, brIdx).trim();
+      if (goType) {
+        this.unresolvedReferences.push({
+          fromNodeId: fromId,
+          referenceName: goType,
+          referenceKind: 'instantiates',
+          line: node.startPosition.row + 1,
+          column: node.startPosition.column,
+        });
+      }
+      return;
+    }
+
+    // Scala: `new Monoid[Int] { ... }` — the constructor is a `generic_type`
+    // (or qualified `stable_type_identifier`) using `[...]` type args, which the
+    // generic `<...>` strip below misses. Unwrap to the base type name.
+    if (node.type === 'instance_expression') {
+      const name = scalaBaseTypeName(ctor, this.source);
+      if (name) {
+        this.unresolvedReferences.push({
+          fromNodeId: fromId,
+          referenceName: name,
+          referenceKind: 'instantiates',
+          line: node.startPosition.row + 1,
+          column: node.startPosition.column,
+        });
+      }
+      return;
+    }
+
     let className = getNodeText(ctor, this.source);
     // Strip type-argument suffix first: `new Map<K, V>()` would
     // otherwise produce className 'Map<K, V>' (the constructor
@@ -1533,6 +2978,148 @@ export class TreeSitterExtractor {
     }
   }
 
+  /**
+   * Static-member / value-read pass. A type/enum/class used only via a member
+   * VALUE — `Enum.value`, `Type.CONST`, `Colors.red`, `Foo::BAR` — recorded no
+   * edge, because the body walker only handled CALLS (`Type.method()`). So a
+   * type referenced only by an enum value or a static field looked like nothing
+   * depended on it (the residual frontier across Dart/Java/C#/Swift/Kotlin/PHP).
+   * Emit a `references` edge to the capitalized receiver. Gated to languages
+   * where types are Capitalized by convention, and skipped when the access is a
+   * call's callee (the call extractor already links the method).
+   */
+  private extractStaticMemberRef(node: SyntaxNode): void {
+    if (!STATIC_MEMBER_LANGS.has(this.language)) return;
+    if (this.nodeStack.length === 0) return;
+    const ownerId = this.nodeStack[this.nodeStack.length - 1];
+    if (!ownerId) return;
+
+    // Dart structures member access as an `identifier` + a sibling `selector`,
+    // not a single node. A value-read selector (no `argument_part`) whose
+    // previous sibling is a capitalized identifier is `Enum.value`.
+    if (this.language === 'dart') {
+      if (node.type !== 'selector') return;
+      if (node.namedChildren.some((c: SyntaxNode) => c.type === 'argument_part')) return;
+      const prev = node.previousNamedSibling;
+      if (prev?.type === 'identifier' && /^[A-Z][A-Za-z0-9_]*$/.test(prev.text)) {
+        this.pushStaticMemberRef(prev.text, ownerId, prev);
+      }
+      return;
+    }
+
+    if (!MEMBER_ACCESS_TYPES.has(node.type)) return;
+
+    // Skip `Type.method()` — the access is the callee of a call, already linked.
+    const parent = node.parent;
+    if (parent && this.extractor!.callTypes.includes(parent.type)) {
+      const callee =
+        getChildByField(parent, 'function') ??
+        getChildByField(parent, 'method') ??
+        parent.namedChild(0);
+      if (callee && callee.startIndex === node.startIndex) return;
+    }
+
+    // The receiver must be a SIMPLE capitalized identifier — `Type.X`, not the
+    // nested `a.B.c` (whose own head member-access is visited separately) nor a
+    // lowercase `obj.field` / `pkg.func`.
+    const recv =
+      getChildByField(node, 'object') ??
+      getChildByField(node, 'expression') ??
+      getChildByField(node, 'scope') ??
+      node.namedChild(0);
+    if (!recv) return;
+    const t = recv.type;
+    if (
+      t === 'identifier' || t === 'type_identifier' || t === 'simple_identifier' ||
+      t === 'name' || t === 'scoped_type_identifier'
+    ) {
+      const text = getNodeText(recv, this.source);
+      if (/^[A-Z][A-Za-z0-9_]*$/.test(text)) this.pushStaticMemberRef(text, ownerId, recv);
+    }
+  }
+
+  private pushStaticMemberRef(name: string, ownerId: string, node: SyntaxNode): void {
+    this.unresolvedReferences.push({
+      fromNodeId: ownerId,
+      referenceName: name,
+      referenceKind: 'references',
+      line: node.startPosition.row + 1,
+      column: node.startPosition.column,
+    });
+  }
+
+  /**
+   * Find a `class_body` child of an `object_creation_expression` — the
+   * marker for an anonymous class (`new T() { ... }`). Returns the body
+   * node so the caller can walk it as the anon class's members.
+   */
+  private findAnonymousClassBody(node: SyntaxNode): SyntaxNode | null {
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      // Java: `class_body`. C# uses the same node kind.
+      if (child && (child.type === 'class_body' || child.type === 'declaration_list')) {
+        return child;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Extract a Java/C# anonymous class — `new T() { ...members }`. Emits a
+   * `class` node named `<T$anon@line>`, an `extends` reference to T (so
+   * Phase 5.5 interface-impl can bridge), and walks the body so its
+   * `method_declaration` members become method nodes under the anon class.
+   *
+   * Why this matters: without anon-class extraction, the overrides inside
+   * a lambda-returned `new T() { @Override int foo(){...} }` are not nodes,
+   * so a call through T.foo (the abstract parent method) has no static
+   * target — the agent has to Read the file to find the implementation.
+   */
+  private extractAnonymousClass(node: SyntaxNode, body: SyntaxNode): void {
+    if (!this.extractor) return;
+
+    // The instantiated type sits in the same field/position that
+    // extractInstantiation reads from. Use the same lookup so the anon
+    // class's `extends` target matches the `instantiates` edge.
+    const typeNode =
+      getChildByField(node, 'constructor') ||
+      getChildByField(node, 'type') ||
+      getChildByField(node, 'name') ||
+      node.namedChild(0);
+    let typeName = typeNode ? getNodeText(typeNode, this.source) : 'Object';
+    const ltIdx = typeName.indexOf('<');
+    if (ltIdx > 0) typeName = typeName.slice(0, ltIdx);
+    const lastDot = Math.max(typeName.lastIndexOf('.'), typeName.lastIndexOf('::'));
+    if (lastDot >= 0) typeName = typeName.slice(lastDot + 1).replace(/^[:.]/, '');
+    typeName = typeName.trim() || 'Object';
+
+    const anonName = `<${typeName}$anon@${node.startPosition.row + 1}>`;
+    const classNode = this.createNode('class', anonName, node, {});
+    if (!classNode) return;
+
+    // The anonymous class implicitly extends/implements the named type.
+    // We can't tell at extraction time whether T is a class or an interface,
+    // so emit `extends`. Resolution will still bind T to whatever it is, and
+    // Phase 5.5 (which already handles both `extends` and `implements`) will
+    // bridge T's methods to the override names found in the anon body.
+    this.unresolvedReferences.push({
+      fromNodeId: classNode.id,
+      referenceName: typeName,
+      referenceKind: 'extends',
+      line: typeNode?.startPosition.row ?? node.startPosition.row,
+      column: typeNode?.startPosition.column ?? node.startPosition.column,
+    });
+
+    // Walk the body's children so method_declaration nodes inside become
+    // method nodes scoped to the anon class.
+    this.nodeStack.push(classNode.id);
+    for (let i = 0; i < body.namedChildCount; i++) {
+      const child = body.namedChild(i);
+      if (child) this.visitNode(child);
+    }
+    this.nodeStack.pop();
+  }
+
   /**
    * Scan `declNode` and its preceding siblings (within the parent's
    * named children) for decorator nodes, emitting a `decorates`
@@ -1552,12 +3139,14 @@ export class TreeSitterExtractor {
     const consider = (n: SyntaxNode | null): void => {
       if (!n) return;
       // `marker_annotation` is Java's grammar for arg-less annotations
-      // (`@Override`, `@Deprecated`); without including it, every
-      // such Java annotation would be silently skipped.
+      // (`@Override`, `@Deprecated`); `attribute` is Swift's grammar for
+      // attributes and PROPERTY WRAPPERS (`@objc`, `@Argument`, `@Published`,
+      // `@State`). Without these, those usages would be silently skipped.
       if (
         n.type !== 'decorator' &&
         n.type !== 'annotation' &&
-        n.type !== 'marker_annotation'
+        n.type !== 'marker_annotation' &&
+        n.type !== 'attribute'
       ) {
         return;
       }
@@ -1576,7 +3165,9 @@ export class TreeSitterExtractor {
           child.type === 'identifier' ||
           child.type === 'member_expression' ||
           child.type === 'scoped_identifier' ||
-          child.type === 'navigation_expression'
+          child.type === 'navigation_expression' ||
+          child.type === 'user_type' ||      // swift attribute → user_type (`@Argument`)
+          child.type === 'type_identifier'
         ) {
           target = child;
           break;
@@ -1584,8 +3175,11 @@ export class TreeSitterExtractor {
       }
       if (!target) return;
       let name = getNodeText(target, this.source);
+      const lt = name.indexOf('<'); // strip generic args: `@Argument<T>` → `Argument`
+      if (lt > 0) name = name.slice(0, lt);
       const lastDot = Math.max(name.lastIndexOf('.'), name.lastIndexOf('::'));
       if (lastDot >= 0) name = name.slice(lastDot + 1).replace(/^[:.]/, '');
+      name = name.trim();
       if (!name) return;
       this.unresolvedReferences.push({
         fromNodeId: decoratedId,
@@ -1599,7 +3193,17 @@ export class TreeSitterExtractor {
     // 1. Decorators that are direct children of the declaration
     //    (method/property style, also some grammars for class).
     for (let i = 0; i < declNode.namedChildCount; i++) {
-      consider(declNode.namedChild(i));
+      const child = declNode.namedChild(i);
+      consider(child);
+      // Java/Kotlin/C# put annotations INSIDE a `modifiers` node
+      // (`@MyAnno public class X` → class_declaration → modifiers → annotation),
+      // so descend into it — otherwise every annotation usage is silently
+      // dropped and annotation types show zero dependents.
+      if (child && child.type === 'modifiers') {
+        for (let j = 0; j < child.namedChildCount; j++) {
+          consider(child.namedChild(j));
+        }
+      }
     }
 
     // 2. Decorators that are PRECEDING siblings of the declaration
@@ -1648,12 +3252,77 @@ export class TreeSitterExtractor {
    *      tree-sitter to interpret the namespace block as a function_definition,
    *      hiding real class/struct/enum nodes inside the "function body".
    */
+  /**
+   * Rocket route-registration macros — `routes![a::b::handler, c::d::other]`
+   * and `catchers![not_found]`. Tree-sitter leaves a macro body as a flat
+   * `token_tree` of raw tokens (`identifier`, `::`, `,`), so the handler paths
+   * are never seen as references and each handler fn looks like it has no caller
+   * — it's mounted by Rocket at runtime, not called by in-repo code, so its file
+   * shows 0 dependents. Walk the token tree, reconstruct each comma-separated
+   * path, and emit a `references` edge; the Rust path resolver
+   * (`resolveRustPathReference`) then links it to the handler fn. The handler
+   * names are explicit in source, so this is precise static extraction, not a
+   * heuristic — no false edges (resolution still validates each path).
+   */
+  private extractRustRouteMacro(node: SyntaxNode): void {
+    if (this.language !== 'rust') return;
+    const macroName = node.namedChild(0);
+    if (!macroName) return;
+    const name = getNodeText(macroName, this.source);
+    if (name !== 'routes' && name !== 'catchers') return;
+    const tokenTree = node.namedChildren.find((c: SyntaxNode) => c.type === 'token_tree');
+    if (!tokenTree) return;
+    const fromId = this.nodeStack[this.nodeStack.length - 1];
+    if (!fromId) return;
+
+    // The token tree is a flat stream: `[ id :: id :: id , id … ]`. Group runs
+    // of `identifier` tokens (the `::` joiners are anonymous) into one path; a
+    // `,` (or the closing `]`) ends a path.
+    let parts: string[] = [];
+    let line = 0;
+    let column = 0;
+    const flush = (): void => {
+      if (parts.length > 0) {
+        this.unresolvedReferences.push({
+          fromNodeId: fromId,
+          referenceName: parts.join('::'),
+          referenceKind: 'references',
+          line,
+          column,
+        });
+        parts = [];
+      }
+    };
+    for (let i = 0; i < tokenTree.childCount; i++) {
+      const t = tokenTree.child(i);
+      if (!t) continue;
+      if (t.type === 'identifier') {
+        if (parts.length === 0) {
+          line = t.startPosition.row + 1;
+          column = t.startPosition.column;
+        }
+        parts.push(getNodeText(t, this.source));
+      } else if (t.type === ',') {
+        flush();
+      }
+    }
+    flush();
+  }
+
   private visitFunctionBody(body: SyntaxNode, _functionId: string): void {
     if (!this.extractor) return;
 
     const visitForCallsAndStructure = (node: SyntaxNode): void => {
       const nodeType = node.type;
 
+      // Function-as-value capture (#756) — function bodies are walked here,
+      // not in visitNode, so the capture hook must fire in both walkers.
+      this.maybeCaptureFnRefs(node, nodeType);
+
+      // Rocket route-registration macros (`routes![…]` / `catchers![…]`): the
+      // handler paths live in a raw token tree the call walker can't see.
+      if (nodeType === 'macro_invocation') this.extractRustRouteMacro(node);
+
       if (this.extractor!.callTypes.includes(nodeType)) {
         this.extractCall(node);
       } else if (INSTANTIATION_KINDS.has(nodeType)) {
@@ -1662,6 +3331,14 @@ export class TreeSitterExtractor {
         // about `call_expression`, so constructor invocations
         // produced no graph edges at all.
         this.extractInstantiation(node);
+        // Anonymous class with body: `new T() { ... }` (Java/C#). Extract as
+        // a class so interface-impl synthesis (Phase 5.5) can bridge T's
+        // methods to the overrides — same rationale as in visitNode.
+        const anonBody = this.findAnonymousClassBody(node);
+        if (anonBody) {
+          this.extractAnonymousClass(node, anonBody);
+          return;
+        }
       } else if (this.extractor!.extractBareCall) {
         const calleeName = this.extractor!.extractBareCall(node, this.source);
         if (calleeName && this.nodeStack.length > 0) {
@@ -1678,6 +3355,42 @@ export class TreeSitterExtractor {
         }
       }
 
+      // Static-member / value-read: `Enum.value`, `Type.CONST`, `Foo::BAR`.
+      this.extractStaticMemberRef(node);
+
+      // Local variable type annotations inside a body — `const items: Foo[] = []`,
+      // `const x: SomeType = svc.load()`. We deliberately do NOT create nodes for
+      // locals (that would explode the graph — the data-flow frontier we leave
+      // uncovered), but the TYPE a local is annotated with is a real dependency of
+      // the enclosing function, so attribute a `references` edge to it. Without
+      // this, a function that uses a type ONLY in its body (very common — e.g. a
+      // resolver building `const nodes: Node[] = []`) produced no edge to that
+      // type, so impact / `affected` missed the dependency entirely. We fall
+      // through to the default recursion below so the initializer's calls (and any
+      // nested declarators) are still walked.
+      if (
+        nodeType === 'variable_declarator' &&
+        this.TYPE_ANNOTATION_LANGUAGES.has(this.language)
+      ) {
+        const ownerId = this.nodeStack[this.nodeStack.length - 1];
+        if (ownerId) this.extractVariableTypeAnnotation(node, ownerId);
+      }
+
+      // Nested NAMED functions inside a body — function declarations and named
+      // function expressions like `.on('mount', function onmount(){})` — become
+      // their own nodes so the graph can link to them (callback handlers, local
+      // helpers). Anonymous arrows/expressions fall through to the default
+      // recursion below, keeping their inner calls attributed to the enclosing
+      // function: this bounds the new nodes to NAMED functions only (no explosion,
+      // no lost edges). extractFunction walks the nested body itself, so we return.
+      if (this.extractor!.functionTypes.includes(nodeType)) {
+        const nestedName = extractName(node, this.source, this.extractor!);
+        if (nestedName && nestedName !== '<anonymous>') {
+          this.extractFunction(node);
+          return;
+        }
+      }
+
       // Extract structural nodes found inside function bodies.
       // Each extract method visits its own children, so we return after extracting.
       if (this.extractor!.classTypes.includes(nodeType)) {
@@ -1717,6 +3430,42 @@ export class TreeSitterExtractor {
    * Extract inheritance relationships
    */
   private extractInheritance(node: SyntaxNode, classId: string): void {
+    // Objective-C @interface MyClass : NSObject <ProtoA, ProtoB>
+    if (node.type === 'class_interface') {
+      const superclass = getChildByField(node, 'superclass');
+      if (superclass) {
+        const name = getNodeText(superclass, this.source);
+        this.unresolvedReferences.push({
+          fromNodeId: classId,
+          referenceName: name,
+          referenceKind: 'extends',
+          line: superclass.startPosition.row + 1,
+          column: superclass.startPosition.column,
+        });
+      }
+      for (let j = 0; j < node.namedChildCount; j++) {
+        const argList = node.namedChild(j);
+        if (argList?.type !== 'parameterized_arguments') continue;
+        for (let k = 0; k < argList.namedChildCount; k++) {
+          const typeName = argList.namedChild(k);
+          if (!typeName) continue;
+          const typeId = typeName.namedChildren.find(
+            (c: SyntaxNode) => c.type === 'type_identifier' || c.type === 'identifier'
+          );
+          if (!typeId) continue;
+          const protocolName = getNodeText(typeId, this.source);
+          this.unresolvedReferences.push({
+            fromNodeId: classId,
+            referenceName: protocolName,
+            referenceKind: 'implements',
+            line: typeId.startPosition.row + 1,
+            column: typeId.startPosition.column,
+          });
+        }
+      }
+      return;
+    }
+
     // Look for extends/implements clauses
     for (let i = 0; i < node.namedChildCount; i++) {
       const child = node.namedChild(i);
@@ -1728,6 +3477,61 @@ export class TreeSitterExtractor {
         child.type === 'base_clause' || // PHP class extends
         child.type === 'extends_interfaces' // Java interface extends
       ) {
+        // Scala: `extends A[X] with B with C` packs EVERY supertype into the
+        // one extends_clause (separated by `with`), each a `generic_type` /
+        // `type_identifier` / `stable_type_identifier`. The generic path below
+        // takes only namedChild(0) and keeps the full text (`A[X]`), so a
+        // parameterized supertype — every typeclass in cats/algebra — never
+        // matched and `with`-mixed traits past the first were dropped. Iterate
+        // all supertypes and unwrap each to its base type name.
+        if (this.language === 'scala') {
+          for (const target of child.namedChildren) {
+            const name = scalaBaseTypeName(target, this.source);
+            if (name) {
+              this.unresolvedReferences.push({
+                fromNodeId: classId,
+                referenceName: name,
+                referenceKind: 'extends',
+                line: target.startPosition.row + 1,
+                column: target.startPosition.column,
+              });
+            }
+          }
+          continue;
+        }
+        // Dart: `class C extends Base with M1, M2` — the `superclass` node holds
+        // the extends type as a direct `type_identifier` AND a `mixins` child
+        // listing the `with` mixins (and `class C with M` has ONLY mixins, no
+        // extends type). The generic `namedChild(0)` path would read the
+        // `mixins` node itself as the superclass and drop every mixin — yet
+        // mixins are Dart's core composition mechanism (Flutter is built on
+        // them). Emit `extends` for the base and `implements` for each mixin.
+        if (this.language === 'dart' && child.type === 'superclass') {
+          for (const t of child.namedChildren) {
+            if (t.type === 'mixins') {
+              for (const m of t.namedChildren) {
+                if (m.type === 'type_identifier') {
+                  this.unresolvedReferences.push({
+                    fromNodeId: classId,
+                    referenceName: getNodeText(m, this.source),
+                    referenceKind: 'implements',
+                    line: m.startPosition.row + 1,
+                    column: m.startPosition.column,
+                  });
+                }
+              }
+            } else if (t.type === 'type_identifier') {
+              this.unresolvedReferences.push({
+                fromNodeId: classId,
+                referenceName: getNodeText(t, this.source),
+                referenceKind: 'extends',
+                line: t.startPosition.row + 1,
+                column: t.startPosition.column,
+              });
+            }
+          }
+          continue;
+        }
         // Extract parent class/interface names
         // Java uses type_list wrapper: superclass -> type_identifier, extends_interfaces -> type_list -> type_identifier
         const typeList = child.namedChildren.find((c: SyntaxNode) => c.type === 'type_list');
@@ -1746,6 +3550,27 @@ export class TreeSitterExtractor {
         }
       }
 
+      // C++ base classes: `class Derived : public Base, private Other` →
+      // base_class_clause holds access specifiers + base type(s). Emit an extends
+      // ref per base type (skip the public/private/protected keywords).
+      if (child.type === 'base_class_clause') {
+        for (const t of child.namedChildren) {
+          if (
+            t.type === 'type_identifier' ||
+            t.type === 'qualified_identifier' ||
+            t.type === 'template_type'
+          ) {
+            this.unresolvedReferences.push({
+              fromNodeId: classId,
+              referenceName: getNodeText(t, this.source),
+              referenceKind: 'extends',
+              line: t.startPosition.row + 1,
+              column: t.startPosition.column,
+            });
+          }
+        }
+      }
+
       if (
         child.type === 'implements_clause' ||
         child.type === 'class_interface_clause' ||
@@ -2007,7 +3832,16 @@ export class TreeSitterExtractor {
    * Languages that support type annotations (TypeScript, etc.)
    */
   private readonly TYPE_ANNOTATION_LANGUAGES = new Set([
-    'typescript', 'tsx', 'dart', 'kotlin', 'swift', 'rust', 'go', 'java', 'csharp',
+    'typescript', 'tsx', 'dart', 'kotlin', 'swift', 'rust', 'go', 'java', 'csharp', 'scala', 'php',
+  ]);
+
+  /**
+   * PHP pseudo-types and `self`/`static`/`parent` that aren't project symbols.
+   * (Scalar primitives parse as `primitive_type` and are skipped structurally.)
+   */
+  private readonly PHP_PSEUDO_TYPES = new Set([
+    'self', 'static', 'parent', 'mixed', 'object', 'iterable', 'callable', 'void',
+    'null', 'false', 'true', 'never', 'array', 'int', 'float', 'string', 'bool',
   ]);
 
   /**
@@ -2024,6 +3858,9 @@ export class TreeSitterExtractor {
     // Go
     'int8', 'int16', 'int32', 'int64', 'uint8', 'uint16', 'uint32', 'uint64',
     'float32', 'float64', 'complex64', 'complex128', 'rune', 'error',
+    // Scala (capitalized primitives + ubiquitous stdlib aliases)
+    'Int', 'Long', 'Short', 'Byte', 'Float', 'Double', 'Boolean', 'Char', 'Unit',
+    'String', 'Any', 'AnyRef', 'AnyVal', 'Nothing', 'Null',
   ]);
 
   /**
@@ -2034,10 +3871,62 @@ export class TreeSitterExtractor {
     if (!this.extractor) return;
     if (!this.TYPE_ANNOTATION_LANGUAGES.has(this.language)) return;
 
-    // Extract parameter type annotations
-    const params = getChildByField(node, this.extractor.paramsField || 'parameters');
-    if (params) {
-      this.extractTypeRefsFromSubtree(params, nodeId);
+    // C# tree-sitter doesn't produce `type_identifier` leaves — it uses
+    // `identifier`, `predefined_type`, `qualified_name`, `generic_name`,
+    // etc. — so the generic walker below emits zero references for it.
+    // Dispatch to a C#-aware path that only walks type-position subtrees
+    // (the `type` field of a parameter/method/property/field), so
+    // parameter NAMES never accidentally surface as type refs (#381).
+    if (this.language === 'csharp') {
+      this.extractCsharpTypeRefs(node, nodeId);
+      return;
+    }
+
+    // PHP type-hints are `named_type`/`optional_type`/`union_type` wrapping a
+    // `name`/`qualified_name` — never `type_identifier` — so the generic walker
+    // below emits nothing for them. Dispatch to a PHP-aware path that walks only
+    // type positions (parameter / return / property types), so type-hinted
+    // dependencies (the constructor-injected contracts that dominate Laravel) are
+    // recorded and a `variable_name` like `$events` never mis-emits as a ref.
+    if (this.language === 'php') {
+      this.extractPhpTypeRefs(node, nodeId);
+      return;
+    }
+
+    // Dart: a `method_signature` wraps the real `function_signature` (where the
+    // params and return type live), and the return type is a bare
+    // `type_identifier` child, not a `type` field — so getChildByField below
+    // finds neither. Walk the inner signature: param names / the method name are
+    // `identifier` (not `type_identifier`), so only types surface.
+    if (this.language === 'dart') {
+      let sig: SyntaxNode | undefined = node;
+      if (node.type === 'method_signature') {
+        sig = node.namedChildren.find(
+          (c: SyntaxNode) =>
+            c.type === 'function_signature' ||
+            c.type === 'getter_signature' ||
+            c.type === 'setter_signature' ||
+            c.type === 'constructor_signature' ||
+            c.type === 'factory_constructor_signature'
+        ) ?? node;
+      }
+      this.extractTypeRefsFromSubtree(sig, nodeId);
+      return;
+    }
+
+    // Extract parameter type annotations. Scala curries — `def f(a)(implicit
+    // M: TC)` has MULTIPLE `parameters` siblings, and the typeclass is almost
+    // always in the trailing implicit list — so walk every parameter list, not
+    // just getChildByField's first match.
+    if (this.language === 'scala') {
+      for (const pc of node.namedChildren) {
+        if (pc.type === 'parameters') this.extractTypeRefsFromSubtree(pc, nodeId);
+      }
+    } else {
+      const params = getChildByField(node, this.extractor.paramsField || 'parameters');
+      if (params) {
+        this.extractTypeRefsFromSubtree(params, nodeId);
+      }
     }
 
     // Extract return type annotation
@@ -2046,6 +3935,22 @@ export class TreeSitterExtractor {
       this.extractTypeRefsFromSubtree(returnType, nodeId);
     }
 
+    // Scala context bounds / type-parameter bounds: `def f[A: Monoid]`,
+    // `[F[_]: Monad]`, `[A <: Foo]` carry the bound type inside `type_parameters`.
+    // This is THE pervasive way a typeclass is required in Scala, yet the bound
+    // never appears in the value parameters. Param NAMES are `identifier` (not
+    // `type_identifier`), so only the bound types surface. Scala-only: in other
+    // languages a `type_parameters` child holds declaration names as
+    // `type_identifier` (TS `<T>`), which would wrongly surface as refs.
+    if (this.language === 'scala') {
+      const typeParams = node.namedChildren.find(
+        (c: SyntaxNode) => c.type === 'type_parameters'
+      );
+      if (typeParams) {
+        this.extractTypeRefsFromSubtree(typeParams, nodeId);
+      }
+    }
+
     // Extract direct type annotation (for class fields like `model: ITextModel`)
     const typeAnnotation = node.namedChildren.find(
       (c: SyntaxNode) => c.type === 'type_annotation'
@@ -2055,6 +3960,196 @@ export class TreeSitterExtractor {
     }
   }
 
+  /**
+   * Extract C# type references from a node that owns a type position —
+   * a method/constructor declaration, a property declaration, or a
+   * field declaration (which wraps `variable_declaration → type`).
+   *
+   * Walks ONLY into known type fields, so parameter names like
+   * `request` in `Build(UserDto request)` are never mis-emitted as
+   * type references. Once inside a type subtree, `walkCsharpTypePosition`
+   * recognizes C#'s actual type-leaf node kinds (`identifier`,
+   * `qualified_name`, `generic_name`, `array_type`, `nullable_type`,
+   * `tuple_type`, …) — none of which are `type_identifier`. Closes #381.
+   */
+  private extractCsharpTypeRefs(node: SyntaxNode, nodeId: string): void {
+    // A property's type is under the `type` field; a method/constructor's RETURN
+    // type is under `returns` (tree-sitter-c-sharp 0.23.x — older builds used
+    // `type` for both). A node carries only one of the two, so checking both
+    // covers return types and property types without conflating them.
+    const directType = getChildByField(node, 'type') ?? getChildByField(node, 'returns');
+    if (directType) this.walkCsharpTypePosition(directType, nodeId);
+
+    // Field declarations wrap declarators in a `variable_declaration`
+    // whose `type` field carries the type. The outer `field_declaration`
+    // has no `type` field of its own, so the call above is a no-op here
+    // and we descend one level.
+    const varDecl = node.namedChildren.find((c: SyntaxNode) => c.type === 'variable_declaration');
+    if (varDecl) {
+      const vdType = getChildByField(varDecl, 'type');
+      if (vdType) this.walkCsharpTypePosition(vdType, nodeId);
+    }
+
+    // Method / constructor parameters. The field name on
+    // `method_declaration` is `parameters`; it points at a
+    // `parameter_list` whose `parameter` children each have their own
+    // `type` field. Walking ONLY the type field skips parameter NAMES,
+    // which would otherwise mis-emit as type references.
+    const params = getChildByField(node, 'parameters');
+    if (params) {
+      for (let i = 0; i < params.namedChildCount; i++) {
+        const child = params.namedChild(i);
+        if (!child || child.type !== 'parameter') continue;
+        const paramType = getChildByField(child, 'type');
+        if (paramType) this.walkCsharpTypePosition(paramType, nodeId);
+      }
+    }
+  }
+
+  /**
+   * Record the dependencies declared by a C# PRIMARY CONSTRUCTOR
+   * (`class Svc(IRepo repo, [FromKeyedServices("k")] ICache cache) { … }`,
+   * C# 12+). The parameter list hangs off the class/struct/record declaration
+   * as an unnamed-field `parameter_list` child (not the `parameters` field a
+   * method uses), so it's found by node type. Each parameter's declared type
+   * becomes a `references` edge from the owning type — these are exactly the
+   * services a DI-registered type depends on, so impact/blast-radius and
+   * "who depends on this contract" now see them. No-op when there's no primary
+   * constructor. (#237)
+   */
+  private extractCsharpPrimaryCtorParamRefs(node: SyntaxNode, ownerId: string): void {
+    if (this.language !== 'csharp') return;
+    const paramList = node.namedChildren.find((c: SyntaxNode) => c.type === 'parameter_list');
+    if (!paramList) return;
+    for (let i = 0; i < paramList.namedChildCount; i++) {
+      const param = paramList.namedChild(i);
+      if (!param || param.type !== 'parameter') continue;
+      const paramType = getChildByField(param, 'type');
+      if (paramType) this.walkCsharpTypePosition(paramType, ownerId);
+    }
+  }
+
+  /**
+   * Walk a C# subtree that is KNOWN to be in a type position
+   * (return type, parameter type, property type, field type, generic
+   * argument). Identifiers here are type names, not parameter names.
+   */
+  private walkCsharpTypePosition(node: SyntaxNode, fromNodeId: string): void {
+    // `predefined_type` is int/string/bool/etc. — never a project ref.
+    if (node.type === 'predefined_type') return;
+
+    // Bare type name: `Foo` in `Foo bar`, or the `Foo` inside `List<Foo>`.
+    if (node.type === 'identifier') {
+      const name = getNodeText(node, this.source);
+      if (name && !this.BUILTIN_TYPES.has(name)) {
+        this.unresolvedReferences.push({
+          fromNodeId,
+          referenceName: name,
+          referenceKind: 'references',
+          line: node.startPosition.row + 1,
+          column: node.startPosition.column,
+        });
+      }
+      return;
+    }
+
+    // `Namespace.Foo` → the rightmost identifier is the type. Emit the
+    // full qualified name as the reference; the resolver can still match
+    // on the trailing simple name when needed.
+    if (node.type === 'qualified_name') {
+      const text = getNodeText(node, this.source);
+      const last = text.split('.').pop() ?? text;
+      if (last && !this.BUILTIN_TYPES.has(last)) {
+        this.unresolvedReferences.push({
+          fromNodeId,
+          referenceName: last,
+          referenceKind: 'references',
+          line: node.startPosition.row + 1,
+          column: node.startPosition.column,
+        });
+      }
+      return;
+    }
+
+    // `(int Code, Foo Payload)` — tuple element has BOTH a `type` and a
+    // `name` field; descending into all named children would mis-emit
+    // the element name (`Code`, `Payload`) as a type ref. Walk only the
+    // type field.
+    if (node.type === 'tuple_element') {
+      const t = getChildByField(node, 'type');
+      if (t) this.walkCsharpTypePosition(t, fromNodeId);
+      return;
+    }
+
+    // Composite type nodes — recurse into named children. Covers
+    // `generic_name` (head identifier + `type_argument_list`),
+    // `nullable_type`, `array_type`, `pointer_type`, `tuple_type`,
+    // `ref_type`, and any newer wrapping shapes the grammar adds.
+    // Identifiers reached here are all type-positional (parameter/field
+    // names are gated out before we descend).
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child) this.walkCsharpTypePosition(child, fromNodeId);
+    }
+  }
+
+  /**
+   * Extract PHP type references from a method/function/property declaration.
+   * Walks ONLY type positions: each parameter's type child (inside
+   * `formal_parameters`), the return type, and a property's type — all
+   * `named_type` / `optional_type` / `union_type` / … direct children. Parameter
+   * and property NAMES are `variable_name` (`$x`), never type nodes, so they
+   * can't be mis-emitted.
+   */
+  private extractPhpTypeRefs(node: SyntaxNode, nodeId: string): void {
+    const params = node.namedChildren.find((c: SyntaxNode) => c.type === 'formal_parameters');
+    if (params) {
+      for (const p of params.namedChildren) {
+        // simple_parameter / property_promotion_parameter / variadic_parameter
+        for (const c of p.namedChildren) {
+          if (PHP_TYPE_NODES.has(c.type)) this.walkPhpTypePosition(c, nodeId);
+        }
+      }
+    }
+    // Return type (method/function) and property type are TYPE nodes that are
+    // DIRECT children of the declaration.
+    for (const c of node.namedChildren) {
+      if (PHP_TYPE_NODES.has(c.type)) this.walkPhpTypePosition(c, nodeId);
+    }
+  }
+
+  /** Walk a PHP subtree KNOWN to be in a type position; emit class/interface refs. */
+  private walkPhpTypePosition(node: SyntaxNode, fromNodeId: string): void {
+    if (node.type === 'primitive_type') return; // int/string/void/…
+    if (node.type === 'name') {
+      const name = getNodeText(node, this.source);
+      if (name && !this.PHP_PSEUDO_TYPES.has(name)) {
+        this.unresolvedReferences.push({
+          fromNodeId, referenceName: name, referenceKind: 'references',
+          line: node.startPosition.row + 1, column: node.startPosition.column,
+        });
+      }
+      return;
+    }
+    if (node.type === 'qualified_name') {
+      // `App\Contracts\Logger` → match on the trailing simple name (what the
+      // class node is stored as, and what a `use` import brings into scope).
+      const last = getNodeText(node, this.source).split('\\').pop() ?? '';
+      if (last && !this.PHP_PSEUDO_TYPES.has(last)) {
+        this.unresolvedReferences.push({
+          fromNodeId, referenceName: last, referenceKind: 'references',
+          line: node.startPosition.row + 1, column: node.startPosition.column,
+        });
+      }
+      return;
+    }
+    // optional_type / nullable_type / union_type / intersection_type / named_type → recurse
+    for (let i = 0; i < node.namedChildCount; i++) {
+      const child = node.namedChild(i);
+      if (child) this.walkPhpTypePosition(child, fromNodeId);
+    }
+  }
+
   /**
    * Extract type references from a variable's type annotation.
    */
@@ -2419,10 +4514,30 @@ export class TreeSitterExtractor {
       }
     }
 
-    const parentId =
+    let parentId =
       this.methodIndex.get(fullNameKey) ||
-      this.methodIndex.get(shortNameKey) ||
-      this.nodeStack[this.nodeStack.length - 1];
+      this.methodIndex.get(shortNameKey);
+
+    // No existing node? This is an implementation-only **free** procedure/function
+    // (`procedure Helper; begin … end;` with no interface declaration and not a
+    // class method). Create a function node so its body's calls attribute to it,
+    // not to the enclosing file/module. A method (`TClass.Method`, a dotted name)
+    // always has a node from its class declaration, so this only fires for free
+    // routines — and the methodIndex lookup above already covers interface-declared
+    // free routines, so there's no duplicate.
+    if (!parentId && !fullName.includes('.')) {
+      const fnNode = this.createNode('function', fullName, declProc, {
+        signature: this.extractor?.getSignature?.(declProc, this.source),
+        visibility: this.extractor?.getVisibility?.(declProc),
+      });
+      if (fnNode) {
+        parentId = fnNode.id;
+        this.methodIndex.set(fullNameKey, fnNode.id);
+        if (!this.methodIndex.has(shortNameKey)) this.methodIndex.set(shortNameKey, fnNode.id);
+      }
+    }
+
+    if (!parentId) parentId = this.nodeStack[this.nodeStack.length - 1];
     if (!parentId) return;
 
     // Visit the block for calls
@@ -2450,12 +4565,41 @@ export class TreeSitterExtractor {
 
     let calleeName = '';
     if (firstChild.type === 'exprDot') {
-      // Qualified call: Obj.Method(...)
-      const identifiers = firstChild.namedChildren.filter(
-        (c: SyntaxNode) => c.type === 'identifier'
-      );
-      if (identifiers.length > 0) {
-        calleeName = identifiers.map((id: SyntaxNode) => getNodeText(id, this.source)).join('.');
+      // Chained static-factory call: `TFoo.GetInstance().DoIt()` — the exprDot's
+      // receiver is itself an `exprCall`, so the bare identifier list would
+      // collapse to just `DoIt` and mis-resolve to a same-named method on an
+      // unrelated class. Encode `TFoo.GetInstance().DoIt` so resolution infers
+      // DoIt's class from what `TFoo.GetInstance` RETURNS (#645/#608). Only a
+      // capitalized class-factory chain; a unary outer method.
+      const innerCall = firstChild.namedChildren.find((c: SyntaxNode) => c.type === 'exprCall');
+      const outerId = firstChild.namedChildren.filter((c: SyntaxNode) => c.type === 'identifier').pop();
+      const method = outerId ? getNodeText(outerId, this.source) : '';
+      if (innerCall && method && /^\w+$/.test(method)) {
+        const innerFirst = innerCall.namedChild(0);
+        let innerCallee = '';
+        if (innerFirst?.type === 'exprDot') {
+          innerCallee = innerFirst.namedChildren
+            .filter((c: SyntaxNode) => c.type === 'identifier')
+            .map((id: SyntaxNode) => getNodeText(id, this.source))
+            .join('.');
+        } else if (innerFirst?.type === 'identifier') {
+          innerCallee = getNodeText(innerFirst, this.source);
+        }
+        // Gate on the Delphi type-naming convention — `TFoo` classes / `IFoo`
+        // interfaces — so a class-factory chain re-encodes but a capitalized
+        // VARIABLE/parameter chain (Pascal capitalizes locals too: `Curve.X().Y()`,
+        // `Self.X().Y()`) stays bare and keeps its existing bare-name resolution.
+        calleeName = innerCallee && /^[TI][A-Z]/.test(innerCallee)
+          ? `${innerCallee}().${method}`
+          : method;
+      } else {
+        // Qualified call: Obj.Method(...)
+        const identifiers = firstChild.namedChildren.filter(
+          (c: SyntaxNode) => c.type === 'identifier'
+        );
+        if (identifiers.length > 0) {
+          calleeName = identifiers.map((id: SyntaxNode) => getNodeText(id, this.source)).join('.');
+        }
       }
     } else if (firstChild.type === 'identifier') {
       calleeName = getNodeText(firstChild, this.source);
@@ -2480,6 +4624,69 @@ export class TreeSitterExtractor {
     }
   }
 
+  /**
+   * Extract a PAREN-LESS Pascal method/procedure call (`Obj.Method;`,
+   * `TFoo.GetInstance.DoIt;`). Pascal lets a no-arg method drop its parens, so it
+   * parses as a bare `exprDot` (not an `exprCall`). A bare `exprDot` is
+   * syntactically identical to a field/property access, so this is only ever
+   * called for a STATEMENT-level exprDot (caller-gated): a bare `Obj.Field;`
+   * statement is a no-op, so a statement-level dot expression is a call. (An
+   * exprDot in assignment LHS/RHS or a condition is left alone — there it really
+   * can be a field/property read.)
+   */
+  private extractPascalParenlessCall(node: SyntaxNode): void {
+    if (this.nodeStack.length === 0) return;
+    const callerId = this.nodeStack[this.nodeStack.length - 1];
+    if (!callerId) return;
+
+    const receiver = node.namedChild(0);
+    const outerId = node.namedChildren.filter((c: SyntaxNode) => c.type === 'identifier').pop();
+    const method = outerId ? getNodeText(outerId, this.source) : '';
+    if (!method) return;
+
+    let calleeName = '';
+    // Chained: the receiver is itself a call — a paren-less `TFoo.GetInstance` (an
+    // inner exprDot) or a paren'd `TFoo.GetInstance()` (an exprCall). Encode the
+    // chain `TFoo.GetInstance().DoIt` so resolution infers DoIt's class from what
+    // the factory RETURNS (#645/#608), gated on the Delphi `TFoo`/`IFoo` type
+    // convention; a capitalized VARIABLE chain stays a bare method name.
+    if ((receiver?.type === 'exprDot' || receiver?.type === 'exprCall') && /^\w+$/.test(method)) {
+      const innerCalleeNode = receiver.type === 'exprCall' ? receiver.namedChild(0) : receiver;
+      const innerCallee = !innerCalleeNode
+        ? ''
+        : innerCalleeNode.type === 'identifier'
+          ? getNodeText(innerCalleeNode, this.source)
+          : innerCalleeNode.namedChildren
+              .filter((c: SyntaxNode) => c.type === 'identifier')
+              .map((id: SyntaxNode) => getNodeText(id, this.source))
+              .join('.');
+      if (innerCallee && /^[TI][A-Z]/.test(innerCallee)) {
+        calleeName = `${innerCallee}().${method}`;
+        // The T/I-prefixed inner is itself a real call — record it too.
+        if (receiver.type === 'exprCall') this.extractPascalCall(receiver);
+        else this.extractPascalParenlessCall(receiver);
+      } else {
+        calleeName = method; // non-class receiver: a bare method ref (no field-access ref)
+      }
+    } else {
+      // Simple: `Obj.Method` → the dotted name (resolves via the receiver / bare name).
+      calleeName = node.namedChildren
+        .filter((c: SyntaxNode) => c.type === 'identifier')
+        .map((id: SyntaxNode) => getNodeText(id, this.source))
+        .join('.');
+    }
+
+    if (calleeName) {
+      this.unresolvedReferences.push({
+        fromNodeId: callerId,
+        referenceName: calleeName,
+        referenceKind: 'calls',
+        line: node.startPosition.row + 1,
+        column: node.startPosition.column,
+      });
+    }
+  }
+
   /**
    * Recursively visit a Pascal block/statement tree for call expressions
    */
@@ -2487,14 +4694,29 @@ export class TreeSitterExtractor {
     for (let i = 0; i < node.namedChildCount; i++) {
       const child = node.namedChild(i);
       if (!child) continue;
+      // Function-as-value capture (#756): Pascal bodies are walked here, not
+      // in visitNode/visitForCallsAndStructure, so the capture hook fires here
+      // — assignment RHS is the Delphi event-wiring idiom (`OnFire := Handler`).
+      this.maybeCaptureFnRefs(child, child.type);
       if (child.type === 'exprCall') {
         this.extractPascalCall(child);
+        // The walker doesn't descend into a call's arguments — dispatch the
+        // argument container directly (`RegisterHandler(TargetCb)` / `(@Cb)`).
+        const args = child.namedChildren.find((c: SyntaxNode) => c.type === 'exprArgs');
+        if (args) this.maybeCaptureFnRefs(args, 'exprArgs');
       } else if (child.type === 'exprDot') {
-        // Check if exprDot contains an exprCall
-        for (let j = 0; j < child.namedChildCount; j++) {
-          const grandchild = child.namedChild(j);
-          if (grandchild?.type === 'exprCall') {
-            this.extractPascalCall(grandchild);
+        // A STATEMENT-level bare exprDot is a paren-less call (`Obj.Free;`,
+        // `TFoo.GetInstance.DoIt;`). Anywhere else (assignment side, condition,
+        // expression) a bare exprDot is ambiguous with a field/property access,
+        // so there we only descend for paren'd inner calls.
+        if (node.type === 'statement') {
+          this.extractPascalParenlessCall(child);
+        } else {
+          for (let j = 0; j < child.namedChildCount; j++) {
+            const grandchild = child.namedChild(j);
+            if (grandchild?.type === 'exprCall') {
+              this.extractPascalCall(grandchild);
+            }
           }
         }
       } else {
@@ -2531,10 +4753,29 @@ export function extractFromSource(
     // Use custom extractor for Vue
     const extractor = new VueExtractor(filePath, source);
     result = extractor.extract();
+  } else if (detectedLanguage === 'astro') {
+    // Use custom extractor for Astro (frontmatter + template delegation)
+    const extractor = new AstroExtractor(filePath, source);
+    result = extractor.extract();
   } else if (detectedLanguage === 'liquid') {
     // Use custom extractor for Liquid
     const extractor = new LiquidExtractor(filePath, source);
     result = extractor.extract();
+  } else if (detectedLanguage === 'razor') {
+    // Use custom extractor for ASP.NET Razor (.cshtml) / Blazor (.razor) markup
+    const extractor = new RazorExtractor(filePath, source);
+    result = extractor.extract();
+  } else if (detectedLanguage === 'xml') {
+    // Custom extractor for MyBatis mapper XML. Non-mapper XML returns just a
+    // file node so the watcher tracks it without emitting symbols.
+    const extractor = new MyBatisExtractor(filePath, source);
+    result = extractor.extract();
+  } else if (isFileLevelOnlyLanguage(detectedLanguage)) {
+    // No symbol extraction at this stage — files are tracked at the file-record
+    // level only. Framework extractors (Drupal routing yml, Spring `@Value`
+    // resolution against application.yml/application.properties) run later and
+    // add per-file nodes/references when they apply.
+    result = { nodes: [], edges: [], unresolvedReferences: [], errors: [], durationMs: 0 };
   } else if (
     detectedLanguage === 'pascal' &&
     (fileExtension === '.dfm' || fileExtension === '.fmx')
diff --git a/src/extraction/vue-extractor.ts b/src/extraction/vue-extractor.ts
index 99e6c46a5..862f17c79 100644
--- a/src/extraction/vue-extractor.ts
+++ b/src/extraction/vue-extractor.ts
@@ -3,6 +3,29 @@ import { generateNodeId } from './tree-sitter-helpers';
 import { TreeSitterExtractor } from './tree-sitter';
 import { isLanguageSupported } from './grammars';
 
+/**
+ * Vue built-in components — skipped so a `<Transition>` / `<KeepAlive>` in the
+ * template doesn't become a phantom reference to a user component. Checked
+ * AFTER kebab→Pascal conversion, so `<keep-alive>` is caught here too.
+ */
+const VUE_BUILTIN_COMPONENTS = new Set([
+  'Transition',
+  'TransitionGroup',
+  'KeepAlive',
+  'Suspense',
+  'Teleport',
+  'Component',
+  'Slot',
+]);
+
+/** `my-component` → `MyComponent` (Vue allows either form in templates). */
+function kebabToPascal(name: string): string {
+  return name
+    .split('-')
+    .map((part) => (part ? part[0]!.toUpperCase() + part.slice(1) : ''))
+    .join('');
+}
+
 /**
  * VueExtractor - Extracts code relationships from Vue Single-File Component files
  *
@@ -41,6 +64,12 @@ export class VueExtractor {
       for (const block of scriptBlocks) {
         this.processScriptBlock(block, componentNode.id);
       }
+
+      // Extract component usages from the <template> (<ComponentName>).
+      // Without this, a Vue component used only in another component's
+      // markup (incl. through a barrel import) is invisible to callers /
+      // impact (#629 follow-up).
+      this.extractTemplateComponents(componentNode.id);
     } catch (error) {
       this.errors.push({
         message: `Vue extraction error: ${error instanceof Error ? error.message : String(error)}`,
@@ -114,13 +143,16 @@ export class VueExtractor {
       // Detect <script setup>
       const isSetup = /\bsetup\b/.test(attrs);
 
-      // Calculate start line of the script content (line after <script>)
+      // Calculate the 0-indexed line where the content begins. The content
+      // starts right after the opening tag's `>` — its leading `\n` is part
+      // of the content, so relative line 1 sits ON the tag's closing line
+      // (adding 1 here double-counted the embedded newline and shifted every
+      // script-block symbol down a line).
       const beforeScript = this.source.substring(0, match.index);
       const scriptTagLine = (beforeScript.match(/\n/g) || []).length;
-      // The content starts on the line after the opening <script> tag
       const openingTag = match[0].substring(0, match[0].indexOf('>') + 1);
       const openingTagLines = (openingTag.match(/\n/g) || []).length;
-      const contentStartLine = scriptTagLine + openingTagLines + 1; // 0-indexed line
+      const contentStartLine = scriptTagLine + openingTagLines; // 0-indexed line
 
       blocks.push({
         content,
@@ -195,4 +227,67 @@ export class VueExtractor {
       this.errors.push(error);
     }
   }
+
+  /**
+   * Extract component usages from the Vue `<template>`.
+   *
+   * PascalCase tags (`<Modal>`, `<Button />`) and kebab-case tags
+   * (`<my-button>`) both represent component instantiations — analogous to
+   * function calls in imperative code. Capturing them creates parent→child
+   * component edges and lets `callers` / `impact` see a component that is
+   * only ever used in markup. Vue's extractor previously parsed only the
+   * `<script>` block, so these usages produced no edge at all (#629).
+   *
+   * HTML elements (lowercase, no hyphen) and Vue built-ins are skipped.
+   * Unmatched names create no edge during resolution, so converting
+   * kebab-case is safe even for native custom elements.
+   */
+  private extractTemplateComponents(componentNodeId: string): void {
+    // Ranges covered by <script> / <style> blocks — skip them so script
+    // identifiers and CSS selectors aren't mistaken for template tags. This
+    // also correctly handles nested <template> tags (v-if / slots), which a
+    // single non-greedy <template>…</template> match would mis-bound.
+    const coveredRanges: Array<[number, number]> = [];
+    const blockRegex = /<(script|style)(\s[^>]*)?>[\s\S]*?<\/\1>/g;
+    let blockMatch;
+    while ((blockMatch = blockRegex.exec(this.source)) !== null) {
+      const startLine = (this.source.substring(0, blockMatch.index).match(/\n/g) || []).length;
+      const endLine = startLine + (blockMatch[0].match(/\n/g) || []).length;
+      coveredRanges.push([startLine, endLine]);
+    }
+
+    const lines = this.source.split('\n');
+    // Opening / self-closing tags (closing `</Foo>` starts with `</`, so the
+    // leading `<` followed by a name letter won't match it).
+    const tagRegex = /<([A-Za-z][A-Za-z0-9_-]*)\b/g;
+
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+      if (coveredRanges.some(([start, end]) => lineIdx >= start && lineIdx <= end)) continue;
+
+      const line = lines[lineIdx]!;
+      let match;
+      while ((match = tagRegex.exec(line)) !== null) {
+        const raw = match[1]!;
+        let componentName: string;
+        if (/^[A-Z]/.test(raw)) {
+          componentName = raw; // PascalCase component
+        } else if (raw.includes('-')) {
+          componentName = kebabToPascal(raw); // kebab-case component
+        } else {
+          continue; // lowercase, no hyphen → native HTML element
+        }
+        if (VUE_BUILTIN_COMPONENTS.has(componentName)) continue;
+
+        this.unresolvedReferences.push({
+          fromNodeId: componentNodeId,
+          referenceName: componentName,
+          referenceKind: 'references',
+          line: lineIdx + 1, // 1-indexed
+          column: match.index + 1,
+          filePath: this.filePath,
+          language: 'vue',
+        });
+      }
+    }
+  }
 }
diff --git a/src/extraction/wasm-runtime-flags.ts b/src/extraction/wasm-runtime-flags.ts
new file mode 100644
index 000000000..c1b30a63e
--- /dev/null
+++ b/src/extraction/wasm-runtime-flags.ts
@@ -0,0 +1,110 @@
+/**
+ * WASM runtime flags — workaround for the V8 turboshaft WASM Zone OOM.
+ *
+ * tree-sitter grammars are large WebAssembly modules. On Node >= 22 the V8
+ * "turboshaft" optimizing WASM compiler can exhaust its per-compilation Zone
+ * arena while compiling these grammars on a background thread, aborting the
+ * whole process with `Fatal process out of memory: Zone` — even with tens of
+ * GB of system memory free, because the Zone is a V8-internal arena, not the
+ * JS heap. Reproduced on Node 22 and 24; Node 25 is already hard-blocked for
+ * the same crash (see ../bin/node-version-check.ts). See issues #293 and #298.
+ *
+ * `--liftoff-only` forces every WASM module to the Liftoff baseline compiler
+ * and never runs turboshaft, which eliminates the crash. Parsing stays fully
+ * correct; we only forgo the (marginal, and for grammars rarely reached)
+ * optimized-tier speedup.
+ *
+ * This flag MUST be on node's command line — it is read by V8 at engine init,
+ * before any of our JS runs. Empirically (Node 24) none of these work:
+ *   - `v8.setFlagsFromString('--liftoff-only')` at runtime — too late.
+ *   - Worker `execArgv: ['--liftoff-only']` — rejected (ERR_WORKER_INVALID_EXEC_ARGV).
+ *   - `NODE_OPTIONS=--liftoff-only` — not on Node's NODE_OPTIONS allowlist.
+ * Also empirically, `--no-wasm-tier-up` / `--no-wasm-dynamic-tiering` do NOT
+ * prevent the crash — only disabling the optimizing tier entirely does.
+ *
+ * Delivery: the bundled launcher passes the flag directly (see
+ * scripts/build-bundle.sh and scripts/npm-shim.js); for any other launch path
+ * (running dist directly, from source, etc.) the CLI re-execs itself once with
+ * the flag via {@link relaunchWithWasmRuntimeFlagsIfNeeded}. V8 flags are
+ * PROCESS-global, and the parse worker is created with default (inherited)
+ * execArgv, so flagging the main process governs the worker's WASM compilation
+ * too.
+ */
+import { spawnSync } from 'child_process';
+
+/**
+ * The V8 flag(s) that keep tree-sitter grammar compilation off the turboshaft
+ * optimizing tier. Single source of truth: the relaunch guard and the test
+ * suite both read this (a test asserts each is a real flag on the running
+ * runtime, so a rename can't silently regress the fix).
+ */
+export const WASM_RUNTIME_FLAGS: readonly string[] = ['--liftoff-only'];
+
+/**
+ * Env var set on the relaunched child so a detection slip can never cause an
+ * infinite re-exec loop. Also lets users force-disable the relaunch.
+ */
+const RELAUNCH_GUARD_ENV = 'CODEGRAPH_WASM_RELAUNCHED';
+
+/**
+ * Env var carrying the *host* PID (the relauncher's own parent) across the
+ * re-exec. Without `--liftoff-only` the CLI re-execs itself once, inserting an
+ * intermediate process between the MCP host and the server. That intermediate
+ * stays alive (blocked in spawnSync) even after the host is killed, so the
+ * server's PPID watchdog can't detect the host's death by watching its own
+ * `process.ppid`. Passing the host PID through lets the watchdog poll it
+ * directly. Unset on the no-re-exec path (bundled launcher / flag already
+ * present), where the server is already a direct child of the host. See
+ * src/mcp/index.ts (#277).
+ */
+export const HOST_PPID_ENV = 'CODEGRAPH_HOST_PPID';
+
+/** True when every required WASM runtime flag is already present in `execArgv`. */
+export function processHasWasmRuntimeFlags(
+  execArgv: readonly string[] = process.execArgv
+): boolean {
+  return WASM_RUNTIME_FLAGS.every((flag) => execArgv.includes(flag));
+}
+
+/**
+ * Build the argv for re-execing node with the WASM runtime flags: our flags
+ * first, then any node flags already in `execArgv` (deduped), then the script
+ * and its args. Pure — exported for unit testing.
+ */
+export function buildRelaunchArgv(
+  scriptPath: string,
+  scriptArgs: readonly string[],
+  execArgv: readonly string[] = process.execArgv
+): string[] {
+  const preserved = execArgv.filter((arg) => !WASM_RUNTIME_FLAGS.includes(arg));
+  return [...WASM_RUNTIME_FLAGS, ...preserved, scriptPath, ...scriptArgs];
+}
+
+/**
+ * If the current process is missing the WASM runtime flags, re-exec it once
+ * with them and exit with the child's status. No-op when the flags are already
+ * present (the normal bundled-launcher path), when already relaunched, or when
+ * disabled via CODEGRAPH_NO_RELAUNCH.
+ *
+ * On spawn failure, returns so the caller runs in-process anyway — risking the
+ * OOM is still better than refusing to start.
+ */
+export function relaunchWithWasmRuntimeFlagsIfNeeded(scriptPath: string): void {
+  if (processHasWasmRuntimeFlags()) return;
+  if (process.env[RELAUNCH_GUARD_ENV]) return;
+  if (process.env.CODEGRAPH_NO_RELAUNCH) return;
+
+  const argv = buildRelaunchArgv(scriptPath, process.argv.slice(2));
+  const result = spawnSync(process.execPath, argv, {
+    stdio: 'inherit',
+    env: { ...process.env, [RELAUNCH_GUARD_ENV]: '1', [HOST_PPID_ENV]: String(process.ppid) },
+    windowsHide: true,
+  });
+
+  if (result.error) {
+    // Couldn't relaunch (e.g. execPath unavailable) — fall through and run in
+    // this process. Degraded (may OOM on huge repos) but not broken.
+    return;
+  }
+  process.exit(result.status ?? (result.signal ? 1 : 0));
+}
diff --git a/src/extraction/wasm/tree-sitter-c_sharp.wasm b/src/extraction/wasm/tree-sitter-c_sharp.wasm
new file mode 100755
index 000000000..bddfd5c8e
Binary files /dev/null and b/src/extraction/wasm/tree-sitter-c_sharp.wasm differ
diff --git a/src/graph/queries.ts b/src/graph/queries.ts
index c39e2e325..9169dcdf5 100644
--- a/src/graph/queries.ts
+++ b/src/graph/queries.ts
@@ -116,24 +116,11 @@ export class GraphQueryManager {
    * @returns Array of file paths this file depends on
    */
   getFileDependencies(filePath: string): string[] {
-    const nodes = this.queries.getNodesByFile(filePath);
-    const fileNode = nodes.find((n) => n.kind === 'file');
-
-    if (!fileNode) {
-      return [];
-    }
-
-    const dependencies = new Set<string>();
-    const importEdges = this.queries.getOutgoingEdges(fileNode.id, ['imports']);
-
-    for (const edge of importEdges) {
-      const targetNode = this.queries.getNodeById(edge.target);
-      if (targetNode && targetNode.filePath !== filePath) {
-        dependencies.add(targetNode.filePath);
-      }
-    }
-
-    return Array.from(dependencies);
+    // Follow the symbol-level cross-file edge graph, not just `imports`:
+    // an `imports` edge here points from a file to its own local import
+    // declarations (same-file), so the actual cross-file dependencies live in
+    // the resolved calls/references/instantiates/extends/... edges.
+    return this.queries.getDependencyFilePaths(filePath);
   }
 
   /**
@@ -145,35 +132,14 @@ export class GraphQueryManager {
    * @returns Array of file paths that depend on this file
    */
   getFileDependents(filePath: string): string[] {
-    const nodes = this.queries.getNodesByFile(filePath);
-    const dependents = new Set<string>();
-
-    // Check file-level incoming import edges (file:X imports file:Y)
-    const fileNode = nodes.find((n) => n.kind === 'file');
-    if (fileNode) {
-      const incomingFileEdges = this.queries.getIncomingEdges(fileNode.id, ['imports']);
-      for (const edge of incomingFileEdges) {
-        const sourceNode = this.queries.getNodeById(edge.source);
-        if (sourceNode && sourceNode.filePath !== filePath) {
-          dependents.add(sourceNode.filePath);
-        }
-      }
-    }
-
-    // Also check node-level imports of exported symbols
-    for (const node of nodes) {
-      if (node.isExported) {
-        const incomingEdges = this.queries.getIncomingEdges(node.id, ['imports']);
-        for (const edge of incomingEdges) {
-          const sourceNode = this.queries.getNodeById(edge.source);
-          if (sourceNode && sourceNode.filePath !== filePath) {
-            dependents.add(sourceNode.filePath);
-          }
-        }
-      }
-    }
-
-    return Array.from(dependents);
+    // Previously this only followed `imports` edges into the file node or its
+    // exported symbols and returned 0 dependents for *every* file — because an
+    // `imports` edge here connects a file to its own local import declarations
+    // (always same-file), never to the providing file. The real cross-file
+    // dependency signal is the resolved symbol graph (calls/references/
+    // instantiates/extends/implements/...), which is what blast-radius /
+    // `affected` need. Delegate to the indexed projection of that graph.
+    return this.queries.getDependentFilePaths(filePath);
   }
 
   /**
diff --git a/src/graph/traversal.ts b/src/graph/traversal.ts
index dd5b50296..c50b877fe 100644
--- a/src/graph/traversal.ts
+++ b/src/graph/traversal.ts
@@ -90,29 +90,24 @@ export class GraphTraverser {
         return priority(a) - priority(b);
       });
 
+      // Batch-fetch the unvisited neighbors in one query (was N+1 per BFS step).
+      const wantIds = adjacentEdges
+        .map((e) => (e.source === node.id ? e.target : e.source))
+        .filter((id) => !visited.has(id));
+      const neighborNodes = wantIds.length > 0 ? this.queries.getNodesByIds(wantIds) : new Map();
+
       for (const adjEdge of adjacentEdges) {
-        // Determine next node: for 'both' direction, edges can be either
-        // incoming or outgoing, so pick whichever end is not the current node
         const nextNodeId = adjEdge.source === node.id ? adjEdge.target : adjEdge.source;
+        if (visited.has(nextNodeId)) continue;
 
-        if (visited.has(nextNodeId)) {
-          continue;
-        }
-
-        const nextNode = this.queries.getNodeById(nextNodeId);
-        if (!nextNode) {
-          continue;
-        }
+        const nextNode = neighborNodes.get(nextNodeId);
+        if (!nextNode) continue;
 
-        // Apply node kind filter
         if (opts.nodeKinds && opts.nodeKinds.length > 0 && !opts.nodeKinds.includes(nextNode.kind)) {
           continue;
         }
 
-        // Add node to result
         nodes.set(nextNode.id, nextNode);
-
-        // Queue for further traversal
         queue.push({ node: nextNode, edge: adjEdge, depth: depth + 1 });
       }
     }
@@ -176,19 +171,18 @@ export class GraphTraverser {
     // Get adjacent edges
     const adjacentEdges = this.getAdjacentEdges(node.id, opts.direction, opts.edgeKinds);
 
+    // Batch-fetch unvisited neighbors (was N+1 per DFS step).
+    const wantIds = adjacentEdges
+      .map((e) => (e.source === node.id ? e.target : e.source))
+      .filter((id) => !visited.has(id));
+    const neighborNodes = wantIds.length > 0 ? this.queries.getNodesByIds(wantIds) : new Map();
+
     for (const edge of adjacentEdges) {
-      // Determine next node: for 'both' direction, edges can be either
-      // incoming or outgoing, so pick whichever end is not the current node
       const nextNodeId = edge.source === node.id ? edge.target : edge.source;
+      if (visited.has(nextNodeId)) continue;
 
-      if (visited.has(nextNodeId)) {
-        continue;
-      }
-
-      const nextNode = this.queries.getNodeById(nextNodeId);
-      if (!nextNode) {
-        continue;
-      }
+      const nextNode = neighborNodes.get(nextNodeId);
+      if (!nextNode) continue;
 
       // Apply node kind filter
       if (opts.nodeKinds && opts.nodeKinds.length > 0 && !opts.nodeKinds.includes(nextNode.kind)) {
@@ -254,10 +248,21 @@ export class GraphTraverser {
     }
     visited.add(nodeId);
 
-    const incomingEdges = this.queries.getIncomingEdges(nodeId, ['calls', 'references', 'imports']);
+    // `instantiates` counts as a caller: constructing a class (`Foo(...)` /
+    // `new Foo()`) is calling its constructor, so the instantiation site is a
+    // caller of the class. Without it, `callers <Class>` surfaced only the
+    // importing file (via `imports`) and missed every construction site —
+    // the opposite of "what breaks if I change this class?" (#774).
+    const incomingEdges = this.queries.getIncomingEdges(nodeId, ['calls', 'references', 'imports', 'instantiates']);
+    if (incomingEdges.length === 0) return;
+
+    // Batch-fetch all caller nodes in one round-trip instead of one
+    // getNodeById per edge (was N+1 — meaningful on functions with many callers).
+    const sourceIds = incomingEdges.map((e) => e.source);
+    const callerNodes = this.queries.getNodesByIds(sourceIds);
 
     for (const edge of incomingEdges) {
-      const callerNode = this.queries.getNodeById(edge.source);
+      const callerNode = callerNodes.get(edge.source);
       if (callerNode && !visited.has(callerNode.id)) {
         result.push({ node: callerNode, edge });
         this.getCallersRecursive(callerNode.id, maxDepth, currentDepth + 1, result, visited);
@@ -293,10 +298,19 @@ export class GraphTraverser {
     }
     visited.add(nodeId);
 
-    const outgoingEdges = this.queries.getOutgoingEdges(nodeId, ['calls', 'references', 'imports']);
+    // Symmetric with getCallers: a function that constructs a class
+    // (`Foo(...)` / `new Foo()`) has that class as a callee, so callers and
+    // callees stay inverses of each other and `trace` can cross the
+    // instantiation boundary (function → class → its methods) (#774).
+    const outgoingEdges = this.queries.getOutgoingEdges(nodeId, ['calls', 'references', 'imports', 'instantiates']);
+    if (outgoingEdges.length === 0) return;
+
+    // Batch-fetch callee nodes (was N+1 — see getCallersRecursive note).
+    const targetIds = outgoingEdges.map((e) => e.target);
+    const calleeNodes = this.queries.getNodesByIds(targetIds);
 
     for (const edge of outgoingEdges) {
-      const calleeNode = this.queries.getNodeById(edge.target);
+      const calleeNode = calleeNodes.get(edge.target);
       if (calleeNode && !visited.has(calleeNode.id)) {
         result.push({ node: calleeNode, edge });
         this.getCalleesRecursive(calleeNode.id, maxDepth, currentDepth + 1, result, visited);
@@ -388,9 +402,11 @@ export class GraphTraverser {
     visited.add(nodeId);
 
     const outgoingEdges = this.queries.getOutgoingEdges(nodeId, ['extends', 'implements']);
+    if (outgoingEdges.length === 0) return;
+    const parents = this.queries.getNodesByIds(outgoingEdges.map((e) => e.target));
 
     for (const edge of outgoingEdges) {
-      const parentNode = this.queries.getNodeById(edge.target);
+      const parentNode = parents.get(edge.target);
       if (parentNode && !nodes.has(parentNode.id)) {
         nodes.set(parentNode.id, parentNode);
         edges.push(edge);
@@ -411,9 +427,11 @@ export class GraphTraverser {
     visited.add(nodeId);
 
     const incomingEdges = this.queries.getIncomingEdges(nodeId, ['extends', 'implements']);
+    if (incomingEdges.length === 0) return;
+    const children = this.queries.getNodesByIds(incomingEdges.map((e) => e.source));
 
     for (const edge of incomingEdges) {
-      const childNode = this.queries.getNodeById(edge.source);
+      const childNode = children.get(edge.source);
       if (childNode && !nodes.has(childNode.id)) {
         nodes.set(childNode.id, childNode);
         edges.push(edge);
@@ -433,12 +451,13 @@ export class GraphTraverser {
 
     // Get all incoming edges (references, calls, type_of, etc.)
     const incomingEdges = this.queries.getIncomingEdges(nodeId);
+    if (incomingEdges.length === 0) return result;
 
+    // Batch-fetch source nodes (was N+1).
+    const sources = this.queries.getNodesByIds(incomingEdges.map((e) => e.source));
     for (const edge of incomingEdges) {
-      const sourceNode = this.queries.getNodeById(edge.source);
-      if (sourceNode) {
-        result.push({ node: sourceNode, edge });
-      }
+      const sourceNode = sources.get(edge.source);
+      if (sourceNode) result.push({ node: sourceNode, edge });
     }
 
     return result;
@@ -496,23 +515,31 @@ export class GraphTraverser {
       const containerKinds = new Set(['class', 'interface', 'struct', 'trait', 'protocol', 'module', 'enum']);
       if (containerKinds.has(focalNode.kind)) {
         const containsEdges = this.queries.getOutgoingEdges(nodeId, ['contains']);
-        for (const edge of containsEdges) {
-          const childNode = this.queries.getNodeById(edge.target);
-          if (childNode && !visited.has(childNode.id)) {
-            nodes.set(childNode.id, childNode);
-            edges.push(edge);
-            // Recurse into children at the same depth (they're part of the same symbol)
-            this.getImpactRecursive(childNode.id, maxDepth, currentDepth, nodes, edges, visited);
+        if (containsEdges.length > 0) {
+          const children = this.queries.getNodesByIds(containsEdges.map((e) => e.target));
+          for (const edge of containsEdges) {
+            const childNode = children.get(edge.target);
+            if (childNode && !visited.has(childNode.id)) {
+              nodes.set(childNode.id, childNode);
+              edges.push(edge);
+              // Recurse into children at the same depth (they're part of the same symbol)
+              this.getImpactRecursive(childNode.id, maxDepth, currentDepth, nodes, edges, visited);
+            }
           }
         }
       }
     }
 
-    // Get all incoming edges (things that depend on this node)
-    const incomingEdges = this.queries.getIncomingEdges(nodeId);
+    // Get all incoming edges (things that depend on this node). Exclude
+    // `contains`: a container "contains" its members but does not *depend* on
+    // them, so following it upward would climb to the parent class and then
+    // re-expand every sibling member — exploding impact for a leaf symbol. (#536)
+    const incomingEdges = this.queries.getIncomingEdges(nodeId).filter((e) => e.kind !== 'contains');
+    if (incomingEdges.length === 0) return;
+    const sources = this.queries.getNodesByIds(incomingEdges.map((e) => e.source));
 
     for (const edge of incomingEdges) {
-      const sourceNode = this.queries.getNodeById(edge.source);
+      const sourceNode = sources.get(edge.source);
       if (sourceNode && !nodes.has(sourceNode.id)) {
         nodes.set(sourceNode.id, sourceNode);
         edges.push(edge);
@@ -564,10 +591,17 @@ export class GraphTraverser {
         nodeId,
         edgeKinds.length > 0 ? edgeKinds : undefined
       );
+      if (outgoingEdges.length === 0) continue;
+
+      // Batch-fetch only the unvisited targets (was N+1 per BFS frontier).
+      const wantIds = outgoingEdges
+        .map((e) => e.target)
+        .filter((id) => !visited.has(id));
+      const nextNodes = wantIds.length > 0 ? this.queries.getNodesByIds(wantIds) : new Map();
 
       for (const edge of outgoingEdges) {
         if (!visited.has(edge.target)) {
-          const nextNode = this.queries.getNodeById(edge.target);
+          const nextNode = nextNodes.get(edge.target);
           if (nextNode) {
             queue.push({
               nodeId: edge.target,
@@ -627,15 +661,15 @@ export class GraphTraverser {
    */
   getChildren(nodeId: string): Node[] {
     const containsEdges = this.queries.getOutgoingEdges(nodeId, ['contains']);
-    const children: Node[] = [];
+    if (containsEdges.length === 0) return [];
 
+    // Batch-fetch (was N+1).
+    const childNodes = this.queries.getNodesByIds(containsEdges.map((e) => e.target));
+    const children: Node[] = [];
     for (const edge of containsEdges) {
-      const childNode = this.queries.getNodeById(edge.target);
-      if (childNode) {
-        children.push(childNode);
-      }
+      const childNode = childNodes.get(edge.target);
+      if (childNode) children.push(childNode);
     }
-
     return children;
   }
 }
diff --git a/src/index.ts b/src/index.ts
index 7d5867414..35855e8b1 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -7,7 +7,6 @@
 
 import * as path from 'path';
 import {
-  CodeGraphConfig,
   Node,
   Edge,
   FileRecord,
@@ -25,7 +24,6 @@ import {
 } from './types';
 import { DatabaseConnection, getDatabasePath } from './db';
 import { QueryBuilder } from './db/queries';
-import { loadConfig, saveConfig, createDefaultConfig } from './config';
 import {
   isInitialized,
   createDirectory,
@@ -48,12 +46,20 @@ import {
 import { GraphTraverser, GraphQueryManager } from './graph';
 import { ContextBuilder, createContextBuilder } from './context';
 import { Mutex, FileLock } from './utils';
-import { FileWatcher, WatchOptions } from './sync';
+import { FileWatcher, WatchOptions, PendingFile, LockUnavailableError } from './sync';
+import { EXTRACTION_VERSION } from './extraction/extraction-version';
+import { getCodeGraphDir } from './directory';
+import { deriveProjectNameTokens } from './search/query-utils';
+import { CodeGraphPackageVersion } from './mcp/version';
 
 // Re-export types for consumers
 export * from './types';
-export { getDatabasePath } from './db';
-export { getConfigPath } from './config';
+// Storage building blocks for embedded/SDK consumers that drive the graph
+// directly (open a DB, run prepared queries) rather than through the CodeGraph
+// facade. Exposed from the package entry so they no longer require deep imports
+// into dist/ (issue #354).
+export { getDatabasePath, DatabaseConnection } from './db';
+export { QueryBuilder } from './db/queries';
 export {
   getCodeGraphDir,
   isInitialized,
@@ -78,16 +84,13 @@ export {
   defaultLogger,
 } from './errors';
 export { Mutex, FileLock, processInBatches, debounce, throttle, MemoryMonitor } from './utils';
-export { FileWatcher, WatchOptions } from './sync';
+export { FileWatcher, WatchOptions, PendingFile, LockUnavailableError } from './sync';
 export { MCPServer } from './mcp';
 
 /**
  * Options for initializing a new CodeGraph project
  */
 export interface InitOptions {
-  /** Custom configuration overrides */
-  config?: Partial<CodeGraphConfig>;
-
   /** Whether to run initial indexing after init */
   index?: boolean;
 
@@ -128,7 +131,6 @@ export interface IndexOptions {
 export class CodeGraph {
   private db: DatabaseConnection;
   private queries: QueryBuilder;
-  private config: CodeGraphConfig;
   private projectRoot: string;
   private orchestrator: ExtractionOrchestrator;
   private resolver: ReferenceResolver;
@@ -148,17 +150,22 @@ export class CodeGraph {
   private constructor(
     db: DatabaseConnection,
     queries: QueryBuilder,
-    config: CodeGraphConfig,
     projectRoot: string
   ) {
     this.db = db;
     this.queries = queries;
-    this.config = config;
     this.projectRoot = projectRoot;
+    // Down-weight the project name as a query term in search ranking — it names
+    // the whole repo, not a symbol, so it has no discriminative value (#720).
+    try {
+      this.queries.setProjectNameTokens(deriveProjectNameTokens(projectRoot));
+    } catch {
+      // Best-effort: ranking still works without it.
+    }
     this.fileLock = new FileLock(
-      path.join(projectRoot, '.codegraph', 'codegraph.lock')
+      path.join(getCodeGraphDir(projectRoot), 'codegraph.lock')
     );
-    this.orchestrator = new ExtractionOrchestrator(projectRoot, config, queries);
+    this.orchestrator = new ExtractionOrchestrator(projectRoot, queries);
     this.resolver = createResolver(projectRoot, queries);
     this.graphManager = new GraphQueryManager(queries);
     this.traverser = new GraphTraverser(queries);
@@ -194,19 +201,12 @@ export class CodeGraph {
     // Create directory structure
     createDirectory(resolvedRoot);
 
-    // Create and save configuration
-    const config = createDefaultConfig(resolvedRoot);
-    if (options.config) {
-      Object.assign(config, options.config);
-    }
-    saveConfig(resolvedRoot, config);
-
     // Initialize database
     const dbPath = getDatabasePath(resolvedRoot);
     const db = DatabaseConnection.initialize(dbPath);
     const queries = new QueryBuilder(db.getDb());
 
-    const instance = new CodeGraph(db, queries, config, resolvedRoot);
+    const instance = new CodeGraph(db, queries, resolvedRoot);
 
     // Run initial indexing if requested
     if (options.index) {
@@ -219,7 +219,7 @@ export class CodeGraph {
   /**
    * Initialize synchronously (without indexing)
    */
-  static initSync(projectRoot: string, options: Omit<InitOptions, 'index' | 'onProgress'> = {}): CodeGraph {
+  static initSync(projectRoot: string): CodeGraph {
     const resolvedRoot = path.resolve(projectRoot);
 
     // Check if already initialized
@@ -230,19 +230,12 @@ export class CodeGraph {
     // Create directory structure
     createDirectory(resolvedRoot);
 
-    // Create and save configuration
-    const config = createDefaultConfig(resolvedRoot);
-    if (options.config) {
-      Object.assign(config, options.config);
-    }
-    saveConfig(resolvedRoot, config);
-
     // Initialize database
     const dbPath = getDatabasePath(resolvedRoot);
     const db = DatabaseConnection.initialize(dbPath);
     const queries = new QueryBuilder(db.getDb());
 
-    return new CodeGraph(db, queries, config, resolvedRoot);
+    return new CodeGraph(db, queries, resolvedRoot);
   }
 
   /**
@@ -267,15 +260,12 @@ export class CodeGraph {
       throw new Error(`Invalid CodeGraph directory: ${validation.errors.join(', ')}`);
     }
 
-    // Load configuration
-    const config = loadConfig(resolvedRoot);
-
     // Open database
     const dbPath = getDatabasePath(resolvedRoot);
     const db = DatabaseConnection.open(dbPath);
     const queries = new QueryBuilder(db.getDb());
 
-    const instance = new CodeGraph(db, queries, config, resolvedRoot);
+    const instance = new CodeGraph(db, queries, resolvedRoot);
 
     // Sync if requested
     if (options.sync) {
@@ -302,15 +292,12 @@ export class CodeGraph {
       throw new Error(`Invalid CodeGraph directory: ${validation.errors.join(', ')}`);
     }
 
-    // Load configuration
-    const config = loadConfig(resolvedRoot);
-
     // Open database
     const dbPath = getDatabasePath(resolvedRoot);
     const db = DatabaseConnection.open(dbPath);
     const queries = new QueryBuilder(db.getDb());
 
-    return new CodeGraph(db, queries, config, resolvedRoot);
+    return new CodeGraph(db, queries, resolvedRoot);
   }
 
   /**
@@ -330,32 +317,6 @@ export class CodeGraph {
     this.db.close();
   }
 
-  // ===========================================================================
-  // Configuration
-  // ===========================================================================
-
-  /**
-   * Get the current configuration
-   */
-  getConfig(): CodeGraphConfig {
-    return { ...this.config };
-  }
-
-  /**
-   * Update configuration
-   */
-  updateConfig(updates: Partial<CodeGraphConfig>): void {
-    Object.assign(this.config, updates);
-    saveConfig(this.projectRoot, this.config);
-    // Recreate orchestrator and resolver with new config
-    this.orchestrator = new ExtractionOrchestrator(
-      this.projectRoot,
-      this.config,
-      this.queries
-    );
-    this.resolver = createResolver(this.projectRoot, this.queries);
-  }
-
   /**
    * Get the project root directory
    */
@@ -380,8 +341,23 @@ export class CodeGraph {
         return { success: false, filesIndexed: 0, filesSkipped: 0, filesErrored: 0, nodesCreated: 0, edgesCreated: 0, errors: [{ message: 'Could not acquire file lock - another process may be indexing', severity: 'error' as const }], durationMs: 0 };
       }
       try {
+        const before = this.queries.getNodeAndEdgeCount();
         const result = await this.orchestrator.indexAll(options.onProgress, options.signal, options.verbose);
 
+        // Re-detect frameworks now that the index is populated. The resolver
+        // is constructed with createResolver() before any files exist, so
+        // framework resolvers whose detect() consults the indexed file list
+        // (e.g. UIKit/SwiftUI scanning for imports, swift-objc-bridge looking
+        // for both Swift and ObjC files) all return false on that initial pass
+        // and silently drop themselves. Re-initializing here gives them a
+        // chance to see the actual project before resolution runs.
+        if (result.success && result.filesIndexed > 0) {
+          this.resolver.initialize();
+          // Cross-file finalization (e.g. NestJS RouterModule prefixes). Runs
+          // before resolution so updated names show up in subsequent reads.
+          this.resolver.runPostExtract();
+        }
+
         // Resolve references to create call/import/extends edges
         if (result.success && result.filesIndexed > 0) {
           // Get count without loading all refs into memory
@@ -400,6 +376,42 @@ export class CodeGraph {
               total,
             });
           });
+
+          // Second pass: chained calls whose method lives on a supertype the
+          // receiver conforms to (protocol-extension / inherited / default-
+          // interface). Needs the implements/extends edges the main pass just
+          // built, so it runs after resolution (#750).
+          this.resolver.resolveChainedCallsViaConformance();
+          // Same lifecycle for `this.<member>` callback registrations whose
+          // member is inherited from a supertype (#808).
+          this.resolver.resolveDeferredThisMemberRefs();
+        }
+
+        // Refresh planner stats + checkpoint the WAL after bulk writes.
+        // Cheap and non-blocking; never load-bearing for correctness.
+        if (result.success && result.filesIndexed > 0) {
+          this.db.runMaintenance();
+        }
+
+        // The orchestrator only sees extraction-phase counts; resolution and
+        // synthesizer edges (often >50% of the graph on JVM repos) come later.
+        // Recompute against the DB so the CLI summary reports the true totals.
+        if (result.success && result.filesIndexed > 0) {
+          const after = this.queries.getNodeAndEdgeCount();
+          result.nodesCreated = after.nodes - before.nodes;
+          result.edgesCreated = after.edges - before.edges;
+        }
+
+        // Stamp the index with the engine that built it, so `codegraph status`
+        // and `codegraph upgrade` can recommend a re-index when the running
+        // engine produces richer extraction than the one on disk. Only on a
+        // real full index — a sync touches a subset, so it must NOT advance the
+        // extraction stamp (the bulk would still be stale). See extraction-version.ts.
+        if (result.success && result.filesIndexed > 0) {
+          try {
+            this.queries.setMetadata('indexed_with_version', CodeGraphPackageVersion);
+            this.queries.setMetadata('indexed_with_extraction_version', String(EXTRACTION_VERSION));
+          } catch { /* metadata is advisory — never fail an index over it */ }
         }
 
         return result;
@@ -444,6 +456,14 @@ export class CodeGraph {
       try {
         const result = await this.orchestrator.sync(options.onProgress);
 
+        // Cross-file finalization (e.g. NestJS RouterModule prefixes). Run on
+        // every sync that touched files so edits to `app.module.ts` propagate
+        // to controllers in unchanged files. The pass is idempotent and cheap
+        // (regex over *.module.ts only).
+        if (result.filesAdded > 0 || result.filesModified > 0) {
+          this.resolver.runPostExtract();
+        }
+
         // Resolve references if files were updated
         if (result.filesAdded > 0 || result.filesModified > 0) {
           if (result.changedFilePaths) {
@@ -481,6 +501,19 @@ export class CodeGraph {
               });
             });
           }
+
+          // Second pass: chained calls whose method lives on a supertype the
+          // receiver conforms to (protocol-extension / inherited). Needs the
+          // implements/extends edges built above (#750).
+          this.resolver.resolveChainedCallsViaConformance();
+          // Same lifecycle for `this.<member>` callback registrations whose
+          // member is inherited from a supertype (#808).
+          this.resolver.resolveDeferredThisMemberRefs();
+        }
+
+        // Refresh planner stats + checkpoint the WAL after bulk writes.
+        if (result.filesAdded > 0 || result.filesModified > 0 || result.filesRemoved > 0) {
+          this.db.runMaintenance();
         }
 
         return result;
@@ -515,9 +548,16 @@ export class CodeGraph {
 
     this.watcher = new FileWatcher(
       this.projectRoot,
-      this.config,
       async () => {
         const result = await this.sync();
+        // sync() returns this exact zero-shape iff it failed to acquire the
+        // file lock (a real empty sync always has filesChecked > 0 because
+        // scanDirectory ran). Surface that to the watcher as a typed error
+        // so it keeps pendingFiles + reschedules instead of clearing them
+        // (#449).
+        if (result.filesChecked === 0 && result.durationMs === 0) {
+          throw new LockUnavailableError();
+        }
         const filesChanged = result.filesAdded + result.filesModified + result.filesRemoved;
         return { filesChanged, durationMs: result.durationMs };
       },
@@ -544,6 +584,31 @@ export class CodeGraph {
     return this.watcher?.isActive() ?? false;
   }
 
+  /**
+   * Files seen by the file watcher since the last successful sync —
+   * the per-file "stale" signal MCP tools attach to responses so an agent
+   * can fall back to {@link Read} for just the affected file without
+   * waiting for a debounced sync to complete (issue #403).
+   *
+   * Returns an empty list when the watcher isn't active, or no events have
+   * arrived. Each entry includes `firstSeenMs` and `lastSeenMs` (wall-clock
+   * `Date.now()` values) so callers can render "edited Nms ago", plus an
+   * `indexing` flag indicating whether the in-flight sync (if any) will
+   * absorb that file.
+   */
+  getPendingFiles(): PendingFile[] {
+    return this.watcher?.getPendingFiles() ?? [];
+  }
+
+  /**
+   * Resolves once the file watcher has installed its watch set. Useful for
+   * tests that need a deterministic boundary before asserting on
+   * `getPendingFiles()`. Resolves immediately when no watcher is active.
+   */
+  waitUntilWatcherReady(timeoutMs?: number): Promise<void> {
+    return this.watcher ? this.watcher.waitUntilReady(timeoutMs) : Promise.resolve();
+  }
+
   /**
    * Get files that have changed since last index
    */
@@ -551,6 +616,41 @@ export class CodeGraph {
     return this.orchestrator.getChangedFiles();
   }
 
+  /**
+   * Most recent index timestamp (ms since epoch) across all tracked files, or
+   * null when nothing is indexed yet. Lets library consumers check index
+   * freshness without shelling out to `codegraph status --json`. (#329)
+   */
+  getLastIndexedAt(): number | null {
+    return this.queries.getLastIndexedAt();
+  }
+
+  /**
+   * Which engine built the current index: the package version + extraction
+   * version stamped at the last full `indexAll`. Either field is null for an
+   * index built before stamping existed (treated as stale). See
+   * `extraction-version.ts` and `isIndexStale()`.
+   */
+  getIndexBuildInfo(): { version: string | null; extractionVersion: number | null } {
+    const version = this.queries.getMetadata('indexed_with_version');
+    const ev = this.queries.getMetadata('indexed_with_extraction_version');
+    const parsed = ev != null ? parseInt(ev, 10) : NaN;
+    return { version, extractionVersion: Number.isFinite(parsed) ? parsed : null };
+  }
+
+  /**
+   * True when the on-disk index was built by an engine whose extraction is
+   * older than the one now running — i.e. a re-index would add data a migration
+   * can't backfill. False when there's no index yet (nothing to refresh) or the
+   * stamp is current. This is the signal behind `codegraph status`'s re-index
+   * hint and `codegraph upgrade`'s reminder.
+   */
+  isIndexStale(): boolean {
+    if (this.queries.getLastIndexedAt() == null) return false;
+    const { extractionVersion } = this.getIndexBuildInfo();
+    return extractionVersion == null || extractionVersion < EXTRACTION_VERSION;
+  }
+
   /**
    * Extract nodes and edges from source code (without storing)
    */
@@ -613,15 +713,24 @@ export class CodeGraph {
   }
 
   /**
-   * Active SQLite backend for this project's connection. `wasm` means
-   * the native better-sqlite3 install failed and the WASM fallback is
-   * serving requests at 5-10x the latency. Surfaced via `codegraph
-   * status` and the `codegraph_status` MCP tool.
+   * Active SQLite backend for this project's connection (`node-sqlite` — Node's
+   * built-in real-SQLite module). Surfaced via `codegraph status` and the
+   * `codegraph_status` MCP tool alongside the effective journal mode.
    */
   getBackend(): import('./db').SqliteBackend {
     return this.db.getBackend();
   }
 
+  /**
+   * The journal mode actually in effect ('wal', 'delete', …). 'wal' means
+   * readers never block on a concurrent writer; anything else means they can,
+   * which is the precondition for the "database is locked" failures in issue
+   * #238. Surfaced via `codegraph status` and the `codegraph_status` MCP tool.
+   */
+  getJournalMode(): string {
+    return this.db.getJournalMode();
+  }
+
   // ===========================================================================
   // Node Operations
   // ===========================================================================
@@ -647,6 +756,15 @@ export class CodeGraph {
     return this.queries.getNodesByKind(kind);
   }
 
+  /**
+   * Get ALL nodes with an exact name (direct index lookup, not FTS-ranked/capped).
+   * Used to enumerate every overload of a heavily-overloaded name so the specific
+   * definition the caller wants is never dropped below a search cut.
+   */
+  getNodesByName(name: string): Node[] {
+    return this.queries.getNodesByName(name);
+  }
+
   /**
    * Search nodes by text
    */
@@ -654,6 +772,44 @@ export class CodeGraph {
     return this.queries.searchNodes(query, options);
   }
 
+  /**
+   * Normalized project-name tokens (go.mod / package.json / repo dir) used to
+   * down-weight the non-discriminative project name in search ranking (#720).
+   * Exposed so explore can exclude it from the PascalCase type-disambiguation
+   * bias, which would otherwise pull overloaded tokens toward whichever stack
+   * embeds the project name.
+   */
+  getProjectNameTokens(): Set<string> {
+    return this.queries.getProjectNameTokens();
+  }
+
+  /**
+   * Find the project's "primary route file" — the file with the densest
+   * concentration of framework-emitted `route` nodes (≥3 routes, ≥30%
+   * of all non-test routes). Used to inline the routing config in
+   * `codegraph_explore` responses on small realworld template repos
+   * (rails-realworld, laravel-realworld, drupal-admintoolbar, …) where
+   * Glob+Read of `routes.rb`/`urls.py`/etc. otherwise beats codegraph.
+   */
+  getTopRouteFile(): { filePath: string; routeCount: number; totalRoutes: number } | null {
+    return this.queries.getTopRouteFile();
+  }
+
+  /**
+   * Build a URL → handler routing manifest from the index. Each entry
+   * pairs a route node (URL + method) with its handler function/method
+   * via the `references` edge that framework resolvers emit. Returns
+   * null when fewer than 3 valid (non-test) routes exist.
+   */
+  getRoutingManifest(limit?: number): {
+    entries: Array<{ url: string; handler: string; handlerFile: string; handlerLine: number; handlerKind: string }>;
+    topHandlerFile: string | null;
+    topHandlerFileCount: number;
+    totalRoutes: number;
+  } | null {
+    return this.queries.getRoutingManifest(limit);
+  }
+
   // ===========================================================================
   // Edge Operations
   // ===========================================================================
diff --git a/src/installer/claude-md-template.ts b/src/installer/claude-md-template.ts
deleted file mode 100644
index f1093b0cc..000000000
--- a/src/installer/claude-md-template.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-/**
- * Backwards-compat re-export shim.
- *
- * The instructions template moved to `instructions-template.ts` so it
- * can be shared across all agent targets (Claude Code, Cursor, Codex
- * CLI, opencode). This file is preserved purely so existing imports
- * (`@colbymchenry/codegraph` consumers, downstream tooling) keep
- * working unchanged. New code should import from
- * `./instructions-template` directly.
- *
- * @deprecated Import from `./instructions-template` instead.
- */
-
-export {
-  CODEGRAPH_SECTION_START,
-  CODEGRAPH_SECTION_END,
-  CLAUDE_MD_TEMPLATE,
-  INSTRUCTIONS_TEMPLATE,
-} from './instructions-template';
diff --git a/src/installer/config-writer.ts b/src/installer/config-writer.ts
index e9c9e93f7..acf5f4cfa 100644
--- a/src/installer/config-writer.ts
+++ b/src/installer/config-writer.ts
@@ -11,13 +11,11 @@
  *   abstraction instead.
  */
 
-import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import {
   writeMcpEntry,
   writePermissionsEntry,
-  writeInstructionsEntry,
 } from './targets/claude';
 import { readJsonFile } from './targets/shared';
 
@@ -25,9 +23,13 @@ export type InstallLocation = 'global' | 'local';
 
 /**
  * Each shim calls ONLY the named per-file helper — writeMcpConfig
- * writes only the MCP JSON, writePermissions only settings.json,
- * writeClaudeMd only CLAUDE.md. The full multi-file install lives
- * in `claudeTarget.install()` which the new orchestrator uses.
+ * writes only the MCP JSON, writePermissions only settings.json. The
+ * full multi-file install lives in `claudeTarget.install()` which the
+ * new orchestrator uses.
+ *
+ * There is no `writeClaudeMd` shim anymore: codegraph stopped writing a
+ * CLAUDE.md instructions block (issue #529) now that the MCP server's
+ * `initialize` instructions are the single source of truth.
  */
 export function writeMcpConfig(location: InstallLocation): void {
   writeMcpEntry(location);
@@ -37,14 +39,6 @@ export function writePermissions(location: InstallLocation): void {
   writePermissionsEntry(location);
 }
 
-export function writeClaudeMd(location: InstallLocation): { created: boolean; updated: boolean } {
-  const file = writeInstructionsEntry(location);
-  return {
-    created: file.action === 'created',
-    updated: file.action === 'updated',
-  };
-}
-
 export function hasMcpConfig(location: InstallLocation): boolean {
   // local scope lives in ./.mcp.json (project scope); global is the
   // user-scope ~/.claude.json. Mirrors the Claude target's paths.
@@ -64,16 +58,3 @@ export function hasPermissions(location: InstallLocation): boolean {
   if (!Array.isArray(allow)) return false;
   return allow.some((p: string) => p.startsWith('mcp__codegraph__'));
 }
-
-export function hasClaudeMdSection(location: InstallLocation): boolean {
-  const file = location === 'global'
-    ? path.join(os.homedir(), '.claude', 'CLAUDE.md')
-    : path.join(process.cwd(), '.claude', 'CLAUDE.md');
-  try {
-    if (!fs.existsSync(file)) return false;
-    const content = fs.readFileSync(file, 'utf-8');
-    return content.includes('<!-- CODEGRAPH_START -->') || content.includes('## CodeGraph');
-  } catch {
-    return false;
-  }
-}
diff --git a/src/installer/index.ts b/src/installer/index.ts
index 687fc884f..a9be118be 100644
--- a/src/installer/index.ts
+++ b/src/installer/index.ts
@@ -2,7 +2,8 @@
  * CodeGraph Interactive Installer
  *
  * Multi-target: writes MCP server config + instructions for the
- * agents the user picks (Claude Code, Cursor, Codex CLI, opencode).
+ * agents the user picks (Claude Code, Cursor, Codex CLI, opencode,
+ * Hermes Agent, Gemini CLI, Antigravity IDE).
  * Defaults to the Claude-only behavior for backwards compatibility
  * when no targets are explicitly chosen and nothing else is detected.
  *
@@ -20,13 +21,14 @@ import {
   getTarget,
   resolveTargetFlag,
 } from './targets/registry';
-import type { AgentTarget, Location, WriteResult } from './targets/types';
+import type { AgentTarget, Location, TargetId } from './targets/types';
 import { getGlyphs } from '../ui/glyphs';
 // Import the lightweight submodules directly (not the ../sync barrel, which
 // re-exports FileWatcher and would transitively pull in ../extraction — the
 // installer must stay importable even when native modules can't load).
 import { watchDisabledReason } from '../sync/watch-policy';
 import { isGitRepo, isSyncHookInstalled, installGitSyncHook } from '../sync/git-hooks';
+import { getCodeGraphDir, codeGraphDirName } from '../directory';
 
 // Backwards-compat: keep these named exports — downstream code may
 // import them. The shim in `config-writer.ts` continues to re-export
@@ -34,10 +36,8 @@ import { isGitRepo, isSyncHookInstalled, installGitSyncHook } from '../sync/git-
 export {
   writeMcpConfig,
   writePermissions,
-  writeClaudeMd,
   hasMcpConfig,
   hasPermissions,
-  hasClaudeMdSection,
 } from './config-writer';
 export type { InstallLocation } from './config-writer';
 
@@ -118,7 +118,7 @@ export async function runInstallerWithOptions(opts: RunInstallerOptions): Promis
       const s = clack.spinner();
       s.start('Installing codegraph CLI...');
       try {
-        execSync('npm install -g @colbymchenry/codegraph', { stdio: 'pipe' });
+        execSync('npm install -g @colbymchenry/codegraph', { stdio: 'pipe', windowsHide: true });
         s.stop('Installed codegraph CLI on PATH');
       } catch {
         s.stop('Could not install (permission denied)');
@@ -193,7 +193,9 @@ export async function runInstallerWithOptions(opts: RunInstallerOptions): Promis
     for (const file of result.files) {
       const verb = file.action === 'unchanged'
         ? 'Unchanged'
-        : file.action === 'created' ? 'Created' : 'Updated';
+        : file.action === 'created' ? 'Created'
+          : file.action === 'removed' ? 'Removed'
+            : 'Updated';
       clack.log.success(`${target.displayName}: ${verb} ${tildify(file.path)}`);
     }
     for (const note of result.notes ?? []) {
@@ -216,36 +218,165 @@ export async function runInstallerWithOptions(opts: RunInstallerOptions): Promis
   clack.outro(finalNote);
 }
 
+export interface RunUninstallerOptions {
+  /**
+   * Comma-separated target list, or `auto` / `all` / `none`. Defaults
+   * to `all` — uninstall sweeps every known agent and reports which
+   * ones it actually touched, so the user doesn't have to know where
+   * they configured it.
+   */
+  target?: string;
+  /** Skip the location prompt; use this value directly. */
+  location?: Location;
+  /** Non-interactive: location=global, target=all, no prompts. */
+  yes?: boolean;
+}
+
+export type UninstallStatus = 'removed' | 'not-configured' | 'unsupported';
+
 /**
- * For every target that has a global config and exposes
- * `wireProjectSurfaces`, write its project-local surfaces (e.g.
- * Cursor's `.cursor/rules/codegraph.mdc`). Idempotent — runs
- * silently when there's nothing to write.
+ * Per-target outcome of an uninstall sweep. `removed` means we deleted
+ * at least one thing; `not-configured` means the agent had no codegraph
+ * config at this location (nothing to do); `unsupported` means the
+ * agent has no config concept for this location (e.g. Codex is
+ * global-only, so a `local` uninstall skips it).
+ */
+export interface UninstallReport {
+  id: TargetId;
+  displayName: string;
+  status: UninstallStatus;
+  /** Absolute paths we actually edited/removed (action === 'removed'). */
+  removedPaths: string[];
+  /** Verbatim notes from the target (rare for uninstall). */
+  notes: string[];
+}
+
+/**
+ * Pure uninstall sweep — no prompts, no I/O beyond the targets' own
+ * file edits. Exposed (and unit-tested) separately from the clack UI in
+ * `runUninstaller` so the aggregation logic can be asserted directly.
  *
- * Called by `codegraph init` so that a user who ran
- * `codegraph install` once globally doesn't have to re-run it per
- * project to get full agent support.
+ * Each target's `uninstall()` is already safe to call when nothing was
+ * installed (it returns `not-found` actions), so this is safe to run
+ * across every target unconditionally.
+ */
+export function uninstallTargets(
+  targets: readonly AgentTarget[],
+  location: Location,
+): UninstallReport[] {
+  return targets.map((target) => {
+    if (!target.supportsLocation(location)) {
+      const only: Location = location === 'local' ? 'global' : 'local';
+      return {
+        id: target.id,
+        displayName: target.displayName,
+        status: 'unsupported' as const,
+        removedPaths: [],
+        notes: [`no ${location} config — this agent is ${only}-only`],
+      };
+    }
+    const result = target.uninstall(location);
+    const removedPaths = result.files
+      .filter((f) => f.action === 'removed')
+      .map((f) => f.path);
+    return {
+      id: target.id,
+      displayName: target.displayName,
+      status: removedPaths.length > 0 ? ('removed' as const) : ('not-configured' as const),
+      removedPaths,
+      notes: result.notes ?? [],
+    };
+  });
+}
+
+/**
+ * Interactive uninstaller — the inverse of `runInstallerWithOptions`.
+ * Asks global-vs-local first (unless `--location`/`--yes` is given),
+ * then sweeps every agent target (or the `--target` subset) and prints
+ * one block per agent so the user sees exactly which providers it hit.
  *
- * Returns the list of `(target, file)` pairs that were created or
- * updated — caller decides how to surface them.
+ * Removes only what install wrote (MCP server entry, instructions
+ * block, permissions) — never the `.codegraph/` index, which `codegraph
+ * uninit` owns.
  */
-export function wireProjectSurfacesForGlobalAgents(): Array<{
-  target: AgentTarget;
-  file: WriteResult['files'][number];
-}> {
-  const written: Array<{ target: AgentTarget; file: WriteResult['files'][number] }> = [];
-  for (const target of ALL_TARGETS) {
-    if (typeof target.wireProjectSurfaces !== 'function') continue;
-    const detection = target.detect('global');
-    if (!detection.alreadyConfigured) continue;
-    const result = target.wireProjectSurfaces();
-    for (const file of result.files) {
-      if (file.action === 'created' || file.action === 'updated') {
-        written.push({ target, file });
+export async function runUninstaller(opts: RunUninstallerOptions): Promise<void> {
+  const clack = await importESM('@clack/prompts');
+
+  clack.intro(`CodeGraph v${getVersion()} — uninstall`);
+
+  const useDefaults = opts.yes === true;
+
+  // Step 1: which location — asked FIRST, the one decision the user
+  // must make. Global sweeps ~/.claude, ~/.codex, etc.; local sweeps
+  // the configs in this project directory.
+  let location: Location;
+  if (opts.location) {
+    location = opts.location;
+  } else if (useDefaults) {
+    location = 'global';
+  } else {
+    const sel = await clack.select({
+      message: 'Remove CodeGraph from all your projects, or just this one?',
+      options: [
+        { value: 'global' as const, label: 'All projects (global)', hint: '~/.claude, ~/.cursor, ~/.codex, ~/.config/opencode, ~/.hermes, ~/.gemini, ~/.kiro' },
+        { value: 'local'  as const, label: 'Just this project (local)', hint: './.claude, ./.cursor, ./opencode.jsonc, ./.gemini, ./.kiro' },
+      ],
+      initialValue: 'global' as const,
+    });
+    if (clack.isCancel(sel)) {
+      clack.cancel('Uninstall cancelled.');
+      process.exit(0);
+    }
+    location = sel;
+  }
+
+  // Step 2: which agents. Default is every agent, so the user doesn't
+  // have to remember where they installed it — unconfigured agents are
+  // reported as "nothing to remove" and left untouched. An explicit
+  // --target subsets this.
+  let targets: AgentTarget[];
+  if (opts.target !== undefined) {
+    targets = resolveTargetFlag(opts.target, location);
+  } else {
+    targets = [...ALL_TARGETS];
+  }
+  if (targets.length === 0) {
+    clack.outro('No agent targets selected — nothing to do.');
+    return;
+  }
+
+  // Step 3: sweep + per-agent feedback.
+  const reports = uninstallTargets(targets, location);
+  const removed = reports.filter((r) => r.status === 'removed');
+
+  for (const r of reports) {
+    if (r.status === 'removed') {
+      for (const p of r.removedPaths) {
+        clack.log.success(`${r.displayName}: removed ${tildify(p)}`);
       }
+    } else if (r.status === 'not-configured') {
+      clack.log.info(`${r.displayName}: not configured — nothing to remove`);
+    } else {
+      clack.log.info(`${r.displayName}: skipped — ${r.notes[0] ?? 'unsupported location'}`);
     }
   }
-  return written;
+
+  // Step 4: for local uninstall, the index dir is separate — point at
+  // `uninit` so the user knows it's still there (and how to remove it).
+  if (location === 'local' && fs.existsSync(getCodeGraphDir(process.cwd()))) {
+    clack.log.info(`The ${codeGraphDirName()}/ index for this project is still here. Run \`codegraph uninit\` to delete it.`);
+  }
+
+  // Step 5: summary.
+  if (removed.length > 0) {
+    const names = removed.map((r) => r.displayName).join(', ');
+    clack.outro(
+      `Removed CodeGraph from ${removed.length} agent${removed.length > 1 ? 's' : ''}: ${names}. ` +
+      `Restart ${removed.length > 1 ? 'them' : 'it'} to apply.`,
+    );
+  } else {
+    clack.outro(`CodeGraph was not configured in any ${location} agent — nothing to remove.`);
+  }
 }
 
 /**
diff --git a/src/installer/instructions-template.ts b/src/installer/instructions-template.ts
index 10b6b7ca7..54f066ea2 100644
--- a/src/installer/instructions-template.ts
+++ b/src/installer/instructions-template.ts
@@ -1,63 +1,51 @@
 /**
- * Agent-instructions template — the markdown body each agent target
- * writes into its conventional instructions file (CLAUDE.md /
- * AGENTS.md / codegraph.mdc / etc.).
+ * The marker-fenced agent-instructions block the installer writes into each
+ * agent's instructions file (CLAUDE.md / AGENTS.md / GEMINI.md).
  *
- * The body content is identical across agents because the codegraph
- * usage advice is agent-agnostic — only the destination filename and
- * any optional frontmatter (Cursor `.mdc`) varies per target.
+ * History: pre-#529 the installer wrote a full usage playbook here, which
+ * duplicated the MCP `initialize` instructions for the main agent — so it
+ * was removed and `mcp/server-instructions.ts` became the single source of
+ * truth. A much smaller block returned for #704, because the MCP
+ * instructions cannot reach two audiences that the instructions FILE does
+ * reach:
  *
- * The legacy `claude-md-template.ts` re-exports these names for
- * backwards compatibility with downstream importers.
+ *  - **Task-tool subagents** — they receive the project instructions file
+ *    in their context but NOT the MCP initialize instructions. They hold
+ *    the codegraph MCP tools only as deferred names and rarely think to
+ *    load them: measured on a forced-delegation flow question (excalidraw,
+ *    sonnet, high effort), subagents loaded + used codegraph in ~1 of 9
+ *    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.
+ *
+ * Keep this block SHORT. The main agent reads it every turn on top of the
+ * server instructions — the #529 duplication-cost argument still bounds
+ * its size. Command names and the two surfaces, nothing more.
  */
 
-/** Markers used by the marker-based section replacement. */
+/** Markers used by the marker-based section write/removal. */
 export const CODEGRAPH_SECTION_START = '<!-- CODEGRAPH_START -->';
 export const CODEGRAPH_SECTION_END = '<!-- CODEGRAPH_END -->';
 
 /**
- * The full marker-delimited block written into each agent's
- * instructions file. Includes the start/end markers so the section
- * can be detected and replaced on re-install.
+ * The full block, markers included, exactly as written to disk.
+ *
+ * The wording is deliberately CONDITIONAL ("in repositories indexed by…"):
+ * a global install writes this into a user-scope file (~/.claude/CLAUDE.md,
+ * ~/.codex/AGENTS.md) that applies to every project the user opens —
+ * including unindexed ones, where an unconditional "this repository is
+ * indexed" claim would send subagents into failing codegraph calls (the
+ * noise the unindexed-session policy exists to prevent).
  */
-export const INSTRUCTIONS_TEMPLATE = `${CODEGRAPH_SECTION_START}
+export const CODEGRAPH_INSTRUCTIONS_BLOCK = `${CODEGRAPH_SECTION_START}
 ## CodeGraph
 
-This project has a CodeGraph MCP server (\`codegraph_*\` tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.
-
-### When to prefer codegraph over native search
-
-Use codegraph for **structural** questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for **literal text** queries (string contents, comments, log messages) or after you already have a specific file open.
-
-| Question | Tool |
-|---|---|
-| "Where is X defined?" / "Find symbol named X" | \`codegraph_search\` |
-| "What calls function Y?" | \`codegraph_callers\` |
-| "What does Y call?" | \`codegraph_callees\` |
-| "What would break if I changed Z?" | \`codegraph_impact\` |
-| "Show me Y's signature / source / docstring" | \`codegraph_node\` |
-| "Give me focused context for a task/area" | \`codegraph_context\` |
-| "See several related symbols' source at once" | \`codegraph_explore\` |
-| "What files exist under path/" | \`codegraph_files\` |
-| "Is the index healthy?" | \`codegraph_status\` |
+In 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:
 
-### Rules of thumb
+- **MCP tools** (when available): \`codegraph_explore\` answers most code questions in one call — 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.
+- **Shell** (always works): \`codegraph explore "<symbol names or question>"\` and \`codegraph node <symbol-or-file>\` print the same output.
 
-- **Answer directly — don't delegate exploration.** For "how does X work" / architecture / trace questions, answer with 2-3 codegraph calls: \`codegraph_context\` first, then ONE \`codegraph_explore\` for the source of the symbols it surfaces. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer.
-- **Trust codegraph results.** They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
-- **Don't grep first** when looking up a symbol by name. \`codegraph_search\` is faster and returns kind + location + signature in one call.
-- **Don't chain \`codegraph_search\` + \`codegraph_node\`** when you just want context — \`codegraph_context\` is one call.
-- **Don't loop \`codegraph_node\` over many symbols** — one \`codegraph_explore\` call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.
-- **Index lag**: the file watcher debounces ~500ms behind writes; don't re-query immediately after editing a file in the same turn.
-
-### If \`.codegraph/\` doesn't exist
-
-The MCP server returns "not initialized." Ask the user: *"I notice this project doesn't have CodeGraph initialized. Want me to run \`codegraph init -i\` to build the index?"*
+If there is no \`.codegraph/\` directory, skip CodeGraph entirely — indexing is the user's decision.
 ${CODEGRAPH_SECTION_END}`;
-
-/**
- * Backwards-compat alias. Existing downstream code may import
- * `CLAUDE_MD_TEMPLATE` from this module via the re-export shim in
- * `claude-md-template.ts`.
- */
-export const CLAUDE_MD_TEMPLATE = INSTRUCTIONS_TEMPLATE;
diff --git a/src/installer/targets/antigravity.ts b/src/installer/targets/antigravity.ts
new file mode 100644
index 000000000..1c128491a
--- /dev/null
+++ b/src/installer/targets/antigravity.ts
@@ -0,0 +1,289 @@
+/**
+ * Google Antigravity IDE target. Antigravity is Google's VS Code-derived
+ * multi-agent IDE; the Gemini CLI is in the process of consolidating with
+ * it under a single agent platform. Antigravity reads MCP server
+ * definitions from a separate config file from the CLI.
+ *
+ * ## Config path: unified vs legacy
+ *
+ * Antigravity recently migrated to a **unified** MCP config path shared
+ * across all Antigravity tools:
+ *
+ *   - **Unified** (post-migration, current): `~/.gemini/config/mcp_config.json`
+ *     — signalled by the `~/.gemini/config/.migrated` marker file.
+ *   - **Legacy** (pre-migration): `~/.gemini/antigravity/mcp_config.json`
+ *     — what the github-mcp-server install guide still documents.
+ *
+ * We detect the marker at install time and write to the right path. On
+ * uninstall we sweep BOTH — so a user who installed on the legacy path,
+ * was then auto-migrated by Antigravity, and re-ran `codegraph install`
+ * doesn't end up with stale codegraph entries in two files.
+ *
+ * ## Entry shape: no `type: stdio` field
+ *
+ * Antigravity rejects MCP entries that carry the `type: "stdio"` field
+ * the rest of our targets use — the working entries it manages itself
+ * (e.g. `code-review-graph`) omit it, and dropping it was load-bearing
+ * to get codegraph to appear in the Customizations UI. We build the
+ * entry locally instead of routing through `getMcpServerConfig()`.
+ *
+ * ## macOS GUI app PATH resolution
+ *
+ * Antigravity is a GUI Electron app. macOS gives Dock/Finder-launched
+ * apps a stripped PATH (`/usr/bin:/bin:/usr/sbin:/sbin`) — nvm-managed
+ * tools live outside that, so a bare `codegraph` command fails to spawn
+ * even when `which codegraph` resolves in the user's shell. We resolve
+ * `codegraph` to its absolute path on macOS at install time. (Linux GUI
+ * apps inherit user PATH; Windows uses `PATH` env directly — both are
+ * fine with the bare command.)
+ *
+ * ## Shared instructions (no GEMINI.md from here)
+ *
+ * The IDE shares `~/.gemini/GEMINI.md` with Gemini CLI for instructions
+ * — written by the `./gemini.ts` target. We deliberately don't touch it
+ * here so uninstalling Antigravity without uninstalling Gemini CLI
+ * leaves CLI instructions intact. Users who install only Antigravity
+ * still get a working MCP integration; the prefer-codegraph-over-grep
+ * guidance just won't be present unless they also install the gemini
+ * target.
+ *
+ * ## Location
+ *
+ * `supportsLocation('local')` returns false — Antigravity has no
+ * project-scoped config concept as of 2026-05.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { execSync } from 'child_process';
+import {
+  AgentTarget,
+  DetectionResult,
+  InstallOptions,
+  Location,
+  WriteResult,
+} from './types';
+import {
+  jsonDeepEqual,
+  readJsonFile,
+  writeJsonFile,
+} from './shared';
+
+function unifiedConfigDir(): string {
+  return path.join(os.homedir(), '.gemini', 'config');
+}
+function unifiedMcpConfigPath(): string {
+  return path.join(unifiedConfigDir(), 'mcp_config.json');
+}
+function legacyConfigDir(): string {
+  return path.join(os.homedir(), '.gemini', 'antigravity');
+}
+function legacyMcpConfigPath(): string {
+  return path.join(legacyConfigDir(), 'mcp_config.json');
+}
+function migratedMarkerPath(): string {
+  return path.join(unifiedConfigDir(), '.migrated');
+}
+
+/**
+ * Pick the right MCP config path to write to.
+ *
+ * Prefers the unified `~/.gemini/config/mcp_config.json` when Antigravity
+ * has signalled it's migrated (`.migrated` marker present, OR the
+ * unified file already exists — Antigravity creates it on first
+ * launch post-migration). Falls back to the legacy
+ * `~/.gemini/antigravity/mcp_config.json` for users on a pre-migration
+ * Antigravity build.
+ */
+function preferredMcpConfigPath(): string {
+  if (fs.existsSync(migratedMarkerPath())) return unifiedMcpConfigPath();
+  if (fs.existsSync(unifiedMcpConfigPath())) return unifiedMcpConfigPath();
+  return legacyMcpConfigPath();
+}
+
+/**
+ * Resolve the on-disk path of the `codegraph` binary so a Mac GUI app
+ * launched from Dock/Finder (with a stripped PATH) can find it. Falls
+ * back to the bare `codegraph` name when:
+ *
+ *  - we're not on macOS (Linux GUI apps inherit user PATH; Windows
+ *    uses env PATH directly), OR
+ *  - the lookup fails for any reason (preserving install in restricted
+ *    environments where `which`/`command -v` aren't available).
+ *
+ * Resolution prefers `command -v` (built-in, no PATH manipulation),
+ * with `which` as a fallback. Both are read via the user's interactive
+ * shell PATH at install time — that's the right PATH for finding
+ * nvm-managed tools like ours.
+ */
+function resolveCodegraphCommand(): string {
+  if (process.platform !== 'darwin') return 'codegraph';
+  try {
+    const resolved = execSync('command -v codegraph || which codegraph', {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      shell: '/bin/bash',
+      windowsHide: true,
+    }).trim();
+    if (resolved && fs.existsSync(resolved)) return resolved;
+  } catch {
+    /* fall through to bare name */
+  }
+  return 'codegraph';
+}
+
+/**
+ * Build the codegraph MCP-server entry for Antigravity. Distinct from
+ * `getMcpServerConfig()` because Antigravity (a) rejects the `type`
+ * field and (b) needs an absolute command path on macOS — see file
+ * header.
+ */
+function buildAntigravityEntry(): { command: string; args: string[] } {
+  return {
+    command: resolveCodegraphCommand(),
+    args: ['serve', '--mcp'],
+  };
+}
+
+class AntigravityTarget implements AgentTarget {
+  readonly id = 'antigravity' as const;
+  readonly displayName = 'Antigravity IDE';
+  readonly docsUrl = 'https://antigravity.google';
+
+  supportsLocation(loc: Location): boolean {
+    return loc === 'global';
+  }
+
+  detect(loc: Location): DetectionResult {
+    if (loc !== 'global') {
+      return { installed: false, alreadyConfigured: false };
+    }
+    const file = preferredMcpConfigPath();
+    const config = readJsonFile(file);
+    const alreadyConfigured = !!config.mcpServers?.codegraph;
+    // "Installed" heuristic: either the unified config dir, the legacy
+    // config dir, or one of the config files exists. Antigravity creates
+    // ~/.gemini/ on first launch even before MCP configs.
+    const installed =
+      fs.existsSync(unifiedConfigDir()) ||
+      fs.existsSync(legacyConfigDir()) ||
+      fs.existsSync(file);
+    return { installed, alreadyConfigured, configPath: file };
+  }
+
+  install(loc: Location, _opts: InstallOptions): WriteResult {
+    if (loc !== 'global') {
+      return {
+        files: [],
+        notes: ['Antigravity IDE has no project-local config — re-run with --location=global.'],
+      };
+    }
+    const files: WriteResult['files'] = [];
+    files.push(writeMcpEntry());
+    // If the user originally installed on the legacy path and Antigravity
+    // has since migrated, strip the stale legacy entry so they don't
+    // wind up with two competing codegraph configs.
+    const legacyCleanup = cleanupLegacyEntry();
+    if (legacyCleanup) files.push(legacyCleanup);
+    return {
+      files,
+      notes: ['Restart Antigravity for MCP changes to take effect.'],
+    };
+  }
+
+  uninstall(loc: Location): WriteResult {
+    if (loc !== 'global') return { files: [] };
+    const files: WriteResult['files'] = [];
+
+    // Remove from the preferred path.
+    const preferred = preferredMcpConfigPath();
+    files.push(removeCodegraphFromFile(preferred));
+
+    // Also sweep the OTHER path (legacy when preferred is unified, and
+    // vice versa) — handles the migration-half-state case where codegraph
+    // got written to one file but Antigravity now reads from the other.
+    const other = preferred === unifiedMcpConfigPath()
+      ? legacyMcpConfigPath()
+      : unifiedMcpConfigPath();
+    if (preferred !== other) {
+      const otherResult = removeCodegraphFromFile(other);
+      // Only surface the secondary file if we actually touched it —
+      // a `not-found` on a file the user never had is noise.
+      if (otherResult.action === 'removed') files.push(otherResult);
+    }
+
+    return { files };
+  }
+
+  printConfig(loc: Location): string {
+    if (loc !== 'global') {
+      return '# Antigravity IDE has no project-local config — use --location=global.\n';
+    }
+    const file = preferredMcpConfigPath();
+    const snippet = JSON.stringify({ mcpServers: { codegraph: buildAntigravityEntry() } }, null, 2);
+    return `# Add to ${file}\n\n${snippet}\n`;
+  }
+
+  describePaths(loc: Location): string[] {
+    if (loc !== 'global') return [];
+    return [preferredMcpConfigPath()];
+  }
+}
+
+function writeMcpEntry(): WriteResult['files'][number] {
+  const file = preferredMcpConfigPath();
+  const dir = path.dirname(file);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const existing = readJsonFile(file);
+  const before = existing.mcpServers?.codegraph;
+  const after = buildAntigravityEntry();
+
+  if (jsonDeepEqual(before, after)) {
+    return { path: file, action: 'unchanged' };
+  }
+  const action: 'created' | 'updated' =
+    before ? 'updated' : (fs.existsSync(file) ? 'updated' : 'created');
+  if (!existing.mcpServers) existing.mcpServers = {};
+  existing.mcpServers.codegraph = after;
+  writeJsonFile(file, existing);
+  return { path: file, action };
+}
+
+/**
+ * Strip the codegraph entry from the legacy `~/.gemini/antigravity/mcp_config.json`
+ * if it's present AND we're writing to the unified path. Used by install
+ * to migrate users who had codegraph configured on the legacy path
+ * before Antigravity migrated their config. Returns the file action for
+ * reporting, or `null` when there's nothing to clean up.
+ */
+function cleanupLegacyEntry(): WriteResult['files'][number] | null {
+  if (preferredMcpConfigPath() !== unifiedMcpConfigPath()) return null;
+  const legacy = legacyMcpConfigPath();
+  if (!fs.existsSync(legacy)) return null;
+  const config = readJsonFile(legacy);
+  if (!config.mcpServers?.codegraph) return null;
+  delete config.mcpServers.codegraph;
+  if (Object.keys(config.mcpServers).length === 0) {
+    delete config.mcpServers;
+  }
+  writeJsonFile(legacy, config);
+  return { path: legacy, action: 'removed' };
+}
+
+function removeCodegraphFromFile(file: string): WriteResult['files'][number] {
+  if (!fs.existsSync(file)) return { path: file, action: 'not-found' };
+  const config = readJsonFile(file);
+  if (!config.mcpServers?.codegraph) return { path: file, action: 'not-found' };
+  delete config.mcpServers.codegraph;
+  if (Object.keys(config.mcpServers).length === 0) {
+    delete config.mcpServers;
+  }
+  // Leave a now-empty `{}` in place — Antigravity manages this file and
+  // a stray empty file is less surprising than a deletion.
+  writeJsonFile(file, config);
+  return { path: file, action: 'removed' };
+}
+
+export const antigravityTarget: AgentTarget = new AntigravityTarget();
diff --git a/src/installer/targets/claude.ts b/src/installer/targets/claude.ts
index 80e2c9d8f..bd65d9274 100644
--- a/src/installer/targets/claude.ts
+++ b/src/installer/targets/claude.ts
@@ -28,19 +28,17 @@ import {
   WriteResult,
 } from './types';
 import {
-  atomicWriteFileSync,
   getCodeGraphPermissions,
   getMcpServerConfig,
   jsonDeepEqual,
   readJsonFile,
   removeMarkedSection,
-  replaceOrAppendMarkedSection,
   writeJsonFile,
+  upsertInstructionsEntry,
 } from './shared';
 import {
   CODEGRAPH_SECTION_END,
   CODEGRAPH_SECTION_START,
-  INSTRUCTIONS_TEMPLATE,
 } from '../instructions-template';
 
 function configDir(loc: Location): string {
@@ -114,8 +112,21 @@ class ClaudeCodeTarget implements AgentTarget {
       files.push(writePermissionsEntry(loc));
     }
 
-    // 3. CLAUDE.md instructions
-    files.push(writeInstructionsEntry(loc));
+    // 2b. Strip stale auto-sync hooks left by a pre-0.8 install. Those
+    // versions wrote `codegraph mark-dirty` / `sync-if-dirty` hooks to
+    // settings.json; both subcommands are gone from the CLI, so the
+    // Stop hook now fails every turn with "unknown command
+    // 'sync-if-dirty'". Cleaning up on install makes an upgrade
+    // self-healing. Only surfaced when something was actually removed.
+    const hookCleanup = cleanupLegacyHooks(loc);
+    if (hookCleanup.action === 'removed') files.push(hookCleanup);
+
+    // 3. CLAUDE.md instructions — the short marker-fenced CodeGraph
+    // block (#704). The MCP initialize instructions reach only the main
+    // agent; CLAUDE.md is what Task-tool subagents (and non-MCP
+    // harnesses) actually see, so the block carries the codegraph
+    // pointers there. Upsert self-heals a stale pre-#529 long block.
+    files.push(upsertInstructionsEntry(instructionsPath(loc)));
 
     return { files };
   }
@@ -168,10 +179,16 @@ class ClaudeCodeTarget implements AgentTarget {
       files.push({ path: settingsPath, action: 'not-found' });
     }
 
-    // 3. Instructions
-    const instr = instructionsPath(loc);
-    const action = removeMarkedSection(instr, CODEGRAPH_SECTION_START, CODEGRAPH_SECTION_END);
-    files.push({ path: instr, action });
+    // 2b. Strip any stale auto-sync hooks a pre-0.8 install left in
+    // settings.json. The hook-cleanup step was lost when the installer
+    // moved to the per-target architecture; restoring it here means
+    // uninstall — and the npm `preuninstall` hook that drives it — fully
+    // reverses a legacy install.
+    const hookCleanup = cleanupLegacyHooks(loc);
+    if (hookCleanup.action === 'removed') files.push(hookCleanup);
+
+    // 3. Instructions — strip the legacy CodeGraph block if present.
+    files.push(removeInstructionsEntry(loc));
 
     return { files };
   }
@@ -241,6 +258,85 @@ function cleanupLegacyLocalMcp(): WriteResult['files'][number] | null {
   return { path: file, action: 'removed' };
 }
 
+/**
+ * True when a Claude Code hook `command` is one of the auto-sync hooks
+ * a pre-0.8 install wrote. Those installers added
+ * `PostToolUse(Edit|Write) → codegraph mark-dirty` and
+ * `Stop → codegraph sync-if-dirty` (local builds used the
+ * `npx @colbymchenry/codegraph …` form, which still contains the
+ * `codegraph <subcommand>` substring). Both subcommands were later
+ * removed from the CLI, so the Stop hook fails every turn with
+ * "unknown command 'sync-if-dirty'". Matching on the codegraph-scoped
+ * subcommand keeps unrelated user hooks (e.g. GitKraken's
+ * `gk ai hook run`) untouched.
+ */
+function isLegacyCodegraphHookCommand(command: unknown): boolean {
+  if (typeof command !== 'string') return false;
+  return (
+    command.includes('codegraph mark-dirty') ||
+    command.includes('codegraph sync-if-dirty')
+  );
+}
+
+/**
+ * Remove stale codegraph auto-sync hooks from Claude `settings.json`.
+ *
+ * Surgical at the individual-command level: only entries matching
+ * `isLegacyCodegraphHookCommand` are dropped, so a sibling hook sharing
+ * a matcher group (or the Stop event) with ours survives. We prune a
+ * matcher group only once its `hooks` array is empty, an event only
+ * once it has no groups left, and `hooks` itself only once every event
+ * is gone — and none of that runs unless we actually removed a
+ * codegraph command, so a settings.json with no legacy hooks is left
+ * byte-for-byte untouched and reported `unchanged`.
+ *
+ * Exported so it can be unit-tested directly and reused by both
+ * `install` (an upgrade self-heals) and `uninstall`.
+ */
+export function cleanupLegacyHooks(loc: Location): WriteResult['files'][number] {
+  const file = settingsJsonPath(loc);
+  if (!fs.existsSync(file)) return { path: file, action: 'not-found' };
+
+  const settings = readJsonFile(file);
+  const hooks = settings.hooks;
+  if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) {
+    return { path: file, action: 'unchanged' };
+  }
+
+  // Pass 1: drop the legacy command(s) from inside every matcher group.
+  let removedAny = false;
+  for (const event of Object.keys(hooks)) {
+    const groups = hooks[event];
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      if (!group || !Array.isArray(group.hooks)) continue;
+      const before = group.hooks.length;
+      group.hooks = group.hooks.filter(
+        (h: any) => !isLegacyCodegraphHookCommand(h?.command),
+      );
+      if (group.hooks.length !== before) removedAny = true;
+    }
+  }
+
+  if (!removedAny) return { path: file, action: 'unchanged' };
+
+  // Pass 2: prune empty matcher groups, then events with no groups
+  // left, then an empty top-level `hooks`. Guarded by `removedAny` so
+  // we never restructure a settings.json that had no codegraph hooks.
+  for (const event of Object.keys(hooks)) {
+    const groups = hooks[event];
+    if (!Array.isArray(groups)) continue;
+    hooks[event] = groups.filter(
+      (g: any) => !(g && Array.isArray(g.hooks) && g.hooks.length === 0),
+    );
+    if (hooks[event].length === 0) delete hooks[event];
+  }
+  if (Object.keys(hooks).length === 0) delete settings.hooks;
+
+  writeJsonFile(file, settings);
+  return { path: file, action: 'removed' };
+}
+
 export function writePermissionsEntry(loc: Location): WriteResult['files'][number] {
   const file = settingsJsonPath(loc);
   const settings = readJsonFile(file);
@@ -263,48 +359,19 @@ export function writePermissionsEntry(loc: Location): WriteResult['files'][numbe
   return { path: file, action: created ? 'created' : 'updated' };
 }
 
-export function writeInstructionsEntry(loc: Location): WriteResult['files'][number] {
+/**
+ * Strip the marker-delimited CodeGraph block from CLAUDE.md if a prior
+ * install wrote one. Codegraph no longer maintains an instructions file
+ * (issue #529) — the MCP server's `initialize` instructions are the
+ * single source of truth — so both install (self-heal on upgrade) and
+ * uninstall call this. `removeMarkedSection` returns `not-found`/`kept`
+ * when there's nothing to strip; the install caller drops those from
+ * the report so a fresh install stays quiet.
+ */
+export function removeInstructionsEntry(loc: Location): WriteResult['files'][number] {
   const file = instructionsPath(loc);
-  // Ensure config dir exists (for global ~/.claude/).
-  const dir = path.dirname(file);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-
-  // Honor the legacy "unmarked ## CodeGraph" rewrite path that the
-  // original installer supported (some users hand-pasted a section
-  // before markers existed). Detect first and migrate inline.
-  if (fs.existsSync(file)) {
-    const content = fs.readFileSync(file, 'utf-8');
-    if (!content.includes(CODEGRAPH_SECTION_START)) {
-      const headerMatch = content.match(/\n## CodeGraph\n/);
-      if (headerMatch && headerMatch.index !== undefined) {
-        const sectionStart = headerMatch.index;
-        const after = content.substring(sectionStart + 1);
-        const nextHeader = after.match(/\n## (?!#)/);
-        const sectionEnd = nextHeader && nextHeader.index !== undefined
-          ? sectionStart + 1 + nextHeader.index
-          : content.length;
-        const merged =
-          content.substring(0, sectionStart) +
-          '\n' + INSTRUCTIONS_TEMPLATE +
-          content.substring(sectionEnd);
-        atomicWriteFileSync(file, merged);
-        return { path: file, action: 'updated' };
-      }
-    }
-  }
-
-  const action = replaceOrAppendMarkedSection(
-    file,
-    INSTRUCTIONS_TEMPLATE,
-    CODEGRAPH_SECTION_START,
-    CODEGRAPH_SECTION_END,
-  );
-  // Map the four-state action to WriteResult's action vocabulary.
-  const mapped: 'created' | 'updated' | 'unchanged' =
-    action === 'created' ? 'created'
-      : action === 'unchanged' ? 'unchanged'
-        : 'updated';
-  return { path: file, action: mapped };
+  const action = removeMarkedSection(file, CODEGRAPH_SECTION_START, CODEGRAPH_SECTION_END);
+  return { path: file, action };
 }
 
 export const claudeTarget: AgentTarget = new ClaudeCodeTarget();
diff --git a/src/installer/targets/codex.ts b/src/installer/targets/codex.ts
index f3af705cb..0a2b8c9c8 100644
--- a/src/installer/targets/codex.ts
+++ b/src/installer/targets/codex.ts
@@ -28,12 +28,11 @@ import {
   atomicWriteFileSync,
   getMcpServerConfig,
   removeMarkedSection,
-  replaceOrAppendMarkedSection,
+  upsertInstructionsEntry,
 } from './shared';
 import {
   CODEGRAPH_SECTION_END,
   CODEGRAPH_SECTION_START,
-  INSTRUCTIONS_TEMPLATE,
 } from '../instructions-template';
 import { buildTomlTable, removeTomlTable, upsertTomlTable } from './toml';
 
@@ -84,7 +83,11 @@ class CodexTarget implements AgentTarget {
     const files: WriteResult['files'] = [];
 
     files.push(writeMcpEntry());
-    files.push(writeInstructionsEntry());
+
+    // AGENTS.md gets the short marker-fenced CodeGraph block (#704):
+    // subagents and non-MCP harnesses read AGENTS.md but never the MCP
+    // initialize instructions. Upsert self-heals a stale pre-#529 block.
+    files.push(upsertInstructionsEntry(instructionsPath()));
 
     return { files };
   }
@@ -111,9 +114,7 @@ class CodexTarget implements AgentTarget {
       files.push({ path: tomlPath, action: 'not-found' });
     }
 
-    const instr = instructionsPath();
-    const instrAction = removeMarkedSection(instr, CODEGRAPH_SECTION_START, CODEGRAPH_SECTION_END);
-    files.push({ path: instr, action: instrAction });
+    files.push(removeInstructionsEntry());
 
     return { files };
   }
@@ -160,22 +161,15 @@ function writeMcpEntry(): WriteResult['files'][number] {
   return { path: file, action: created ? 'created' : 'updated' };
 }
 
-function writeInstructionsEntry(): WriteResult['files'][number] {
+/**
+ * Strip the marker-delimited CodeGraph block from `~/.codex/AGENTS.md`
+ * if a prior install wrote one. Used by both install (self-heal on
+ * upgrade) and uninstall — see issue #529.
+ */
+function removeInstructionsEntry(): WriteResult['files'][number] {
   const file = instructionsPath();
-  const dir = path.dirname(file);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-
-  const action = replaceOrAppendMarkedSection(
-    file,
-    INSTRUCTIONS_TEMPLATE,
-    CODEGRAPH_SECTION_START,
-    CODEGRAPH_SECTION_END,
-  );
-  const mapped: 'created' | 'updated' | 'unchanged' =
-    action === 'created' ? 'created'
-      : action === 'unchanged' ? 'unchanged'
-        : 'updated';
-  return { path: file, action: mapped };
+  const action = removeMarkedSection(file, CODEGRAPH_SECTION_START, CODEGRAPH_SECTION_END);
+  return { path: file, action };
 }
 
 export const codexTarget: AgentTarget = new CodexTarget();
diff --git a/src/installer/targets/cursor.ts b/src/installer/targets/cursor.ts
index 850b6fc82..c2d3595ca 100644
--- a/src/installer/targets/cursor.ts
+++ b/src/installer/targets/cursor.ts
@@ -46,14 +46,11 @@ import {
   getMcpServerConfig,
   jsonDeepEqual,
   readJsonFile,
-  removeMarkedSection,
-  replaceOrAppendMarkedSection,
   writeJsonFile,
 } from './shared';
 import {
   CODEGRAPH_SECTION_END,
   CODEGRAPH_SECTION_START,
-  INSTRUCTIONS_TEMPLATE,
 } from '../instructions-template';
 
 function mcpJsonPath(loc: Location): string {
@@ -113,8 +110,13 @@ class CursorTarget implements AgentTarget {
 
     files.push(writeMcpEntry(loc));
 
+    // We no longer write `.cursor/rules/codegraph.mdc` — the codegraph
+    // usage guidance ships in the MCP server's `initialize` response,
+    // the single source of truth (issue #529). Strip a rules file a
+    // previous install created so an upgrade self-heals.
     if (loc === 'local') {
-      files.push(writeRulesEntry());
+      const rulesCleanup = removeRulesEntry();
+      if (rulesCleanup.action === 'removed') files.push(rulesCleanup);
     }
 
     return {
@@ -140,9 +142,7 @@ class CursorTarget implements AgentTarget {
     }
 
     if (loc === 'local') {
-      const rules = rulesPath();
-      const action = removeMarkedSection(rules, CODEGRAPH_SECTION_START, CODEGRAPH_SECTION_END);
-      files.push({ path: rules, action });
+      files.push(removeRulesEntry());
     }
 
     return { files };
@@ -159,16 +159,6 @@ class CursorTarget implements AgentTarget {
       ? [mcpJsonPath(loc), rulesPath()]
       : [mcpJsonPath(loc)];
   }
-
-  /**
-   * Write the project-local `.cursor/rules/codegraph.mdc` file. Used
-   * by `codegraph init` to bootstrap projects that have only the
-   * global `~/.cursor/mcp.json` — without the rules file, the Cursor
-   * agent has no signal to prefer codegraph over native grep.
-   */
-  wireProjectSurfaces(): WriteResult {
-    return { files: [writeRulesEntry()] };
-  }
 }
 
 /**
@@ -200,41 +190,58 @@ function writeMcpEntry(loc: Location): WriteResult['files'][number] {
   return { path: file, action };
 }
 
-function writeRulesEntry(): WriteResult['files'][number] {
+/**
+ * Remove the Cursor rules file on uninstall (and as a self-heal on
+ * install — see issue #529).
+ *
+ * Unlike the shared CLAUDE.md / AGENTS.md files (where codegraph owns
+ * only a marker-delimited section), `.cursor/rules/codegraph.mdc` is a
+ * file we create OUTRIGHT — the frontmatter is ours too. So a plain
+ * `removeMarkedSection` is wrong here: it would strip our instruction
+ * block but leave the orphaned `description: CodeGraph ...` frontmatter
+ * behind, so the file lingers and still "mentions" codegraph.
+ *
+ * Instead: strip our block, and if nothing but our own frontmatter
+ * remains, delete the whole file. Only when the user has added their
+ * own content outside our markers do we keep the file (minus our block).
+ */
+function removeRulesEntry(): WriteResult['files'][number] {
   const file = rulesPath();
-  const dir = path.dirname(file);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  if (!fs.existsSync(file)) return { path: file, action: 'not-found' };
 
-  // Body is frontmatter + the shared instructions block. The
-  // marker-based replacement targets only the marker block, so the
-  // frontmatter is preserved across re-runs.
-  const body = MDC_FRONTMATTER + INSTRUCTIONS_TEMPLATE;
+  let content: string;
+  try {
+    content = fs.readFileSync(file, 'utf-8');
+  } catch {
+    return { path: file, action: 'not-found' };
+  }
 
-  if (!fs.existsSync(file)) {
-    atomicWriteFileSync(file, body + '\n');
-    return { path: file, action: 'created' };
+  const ourFrontmatter = MDC_FRONTMATTER.trim();
+  const startIdx = content.indexOf(CODEGRAPH_SECTION_START);
+  const endIdx = content.indexOf(CODEGRAPH_SECTION_END);
+
+  // Our marked block is present — strip it, then decide what's left.
+  if (startIdx !== -1 && endIdx > startIdx) {
+    const before = content.substring(0, startIdx).trimEnd();
+    const after = content.substring(endIdx + CODEGRAPH_SECTION_END.length).trimStart();
+    const remainder = (before + (before && after ? '\n\n' : '') + after).trim();
+    if (remainder === '' || remainder === ourFrontmatter) {
+      try { fs.unlinkSync(file); } catch { /* ignore */ }
+    } else {
+      atomicWriteFileSync(file, remainder + '\n');
+    }
+    return { path: file, action: 'removed' };
   }
 
-  // For .mdc files we own outright, do byte-equality first.
-  const existing = fs.readFileSync(file, 'utf-8');
-  const wantWithNL = body + '\n';
-  if (existing === wantWithNL) {
-    return { path: file, action: 'unchanged' };
+  // No block, but the file is still our pristine frontmatter-only file
+  // — it's ours, so remove it.
+  if (content.trim() === ourFrontmatter) {
+    try { fs.unlinkSync(file); } catch { /* ignore */ }
+    return { path: file, action: 'removed' };
   }
 
-  // Otherwise, marker-based section swap (preserves any user-added
-  // content outside the markers).
-  const action = replaceOrAppendMarkedSection(
-    file,
-    INSTRUCTIONS_TEMPLATE,
-    CODEGRAPH_SECTION_START,
-    CODEGRAPH_SECTION_END,
-  );
-  const mapped: 'created' | 'updated' | 'unchanged' =
-    action === 'created' ? 'created'
-      : action === 'unchanged' ? 'unchanged'
-        : 'updated';
-  return { path: file, action: mapped };
+  // Foreign content we don't recognize — leave it alone.
+  return { path: file, action: 'not-found' };
 }
 
 export const cursorTarget: AgentTarget = new CursorTarget();
diff --git a/src/installer/targets/gemini.ts b/src/installer/targets/gemini.ts
new file mode 100644
index 000000000..6db543f39
--- /dev/null
+++ b/src/installer/targets/gemini.ts
@@ -0,0 +1,162 @@
+/**
+ * Gemini CLI target (also covers the rebranded "Antigravity CLI" —
+ * Google is in the middle of unifying its CLI tools under
+ * Antigravity, and the new CLI continues to read `~/.gemini/settings.json`
+ * + project-local `.gemini/settings.json`). Writes:
+ *
+ *   - MCP server entry to `~/.gemini/settings.json` (global) or
+ *     `./.gemini/settings.json` (local) under the standard
+ *     `mcpServers.codegraph` key. Same shape as Claude / Cursor.
+ *   - Instructions to `~/.gemini/GEMINI.md` (global) or `./GEMINI.md`
+ *     (local — Gemini reads the project root file directly, not
+ *     under `.gemini/`).
+ *
+ * No permissions concept — Gemini CLI gates tool invocations through
+ * the `trust` field per server, not an external allowlist. We leave
+ * `trust` unset so the user controls confirmation prompts.
+ *
+ * The Antigravity IDE shares `~/.gemini/GEMINI.md` for instructions
+ * but uses a separate MCP config file (`~/.gemini/antigravity/mcp_config.json`)
+ * — see `./antigravity.ts`. Both targets writing to GEMINI.md is
+ * safe: the marker-based section replacement makes the second write
+ * a byte-identical no-op.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  AgentTarget,
+  DetectionResult,
+  InstallOptions,
+  Location,
+  WriteResult,
+} from './types';
+import {
+  getMcpServerConfig,
+  jsonDeepEqual,
+  readJsonFile,
+  removeMarkedSection,
+  writeJsonFile,
+  upsertInstructionsEntry,
+} from './shared';
+import {
+  CODEGRAPH_SECTION_END,
+  CODEGRAPH_SECTION_START,
+} from '../instructions-template';
+
+function configDir(loc: Location): string {
+  return loc === 'global'
+    ? path.join(os.homedir(), '.gemini')
+    : path.join(process.cwd(), '.gemini');
+}
+function settingsJsonPath(loc: Location): string {
+  return path.join(configDir(loc), 'settings.json');
+}
+function instructionsPath(loc: Location): string {
+  // Global GEMINI.md lives under ~/.gemini/; project-local GEMINI.md
+  // lives at the project root (NOT under .gemini/), matching how
+  // Gemini CLI's hierarchical context loader searches.
+  return loc === 'global'
+    ? path.join(configDir('global'), 'GEMINI.md')
+    : path.join(process.cwd(), 'GEMINI.md');
+}
+
+class GeminiTarget implements AgentTarget {
+  readonly id = 'gemini' as const;
+  readonly displayName = 'Gemini CLI';
+  readonly docsUrl = 'https://geminicli.com/docs/tools/mcp-server/';
+
+  supportsLocation(_loc: Location): boolean {
+    return true;
+  }
+
+  detect(loc: Location): DetectionResult {
+    const file = settingsJsonPath(loc);
+    const config = readJsonFile(file);
+    const alreadyConfigured = !!config.mcpServers?.codegraph;
+    const installed = loc === 'global'
+      ? fs.existsSync(configDir('global')) || fs.existsSync(file)
+      : fs.existsSync(file) || fs.existsSync(configDir('local'));
+    return { installed, alreadyConfigured, configPath: file };
+  }
+
+  install(loc: Location, _opts: InstallOptions): WriteResult {
+    const files: WriteResult['files'] = [];
+    files.push(writeMcpEntry(loc));
+
+    // GEMINI.md gets the short marker-fenced CodeGraph block (#704):
+    // subagents and non-MCP harnesses read GEMINI.md but never the MCP
+    // initialize instructions. Upsert self-heals a stale pre-#529 block.
+    files.push(upsertInstructionsEntry(instructionsPath(loc)));
+
+    return { files };
+  }
+
+  uninstall(loc: Location): WriteResult {
+    const files: WriteResult['files'] = [];
+
+    const file = settingsJsonPath(loc);
+    const config = readJsonFile(file);
+    if (config.mcpServers?.codegraph) {
+      delete config.mcpServers.codegraph;
+      if (Object.keys(config.mcpServers).length === 0) {
+        delete config.mcpServers;
+      }
+      // If the file is now an empty `{}` we still leave it — other
+      // (top-level) Gemini settings the user might add later can
+      // share the file; deleting it would be surprising.
+      writeJsonFile(file, config);
+      files.push({ path: file, action: 'removed' });
+    } else {
+      files.push({ path: file, action: 'not-found' });
+    }
+
+    files.push(removeInstructionsEntry(loc));
+
+    return { files };
+  }
+
+  printConfig(loc: Location): string {
+    const target = settingsJsonPath(loc);
+    const snippet = JSON.stringify({ mcpServers: { codegraph: getMcpServerConfig() } }, null, 2);
+    return `# Add to ${target}\n\n${snippet}\n`;
+  }
+
+  describePaths(loc: Location): string[] {
+    return [settingsJsonPath(loc), instructionsPath(loc)];
+  }
+}
+
+function writeMcpEntry(loc: Location): WriteResult['files'][number] {
+  const file = settingsJsonPath(loc);
+  const dir = path.dirname(file);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const existing = readJsonFile(file);
+  const before = existing.mcpServers?.codegraph;
+  const after = getMcpServerConfig();
+
+  if (jsonDeepEqual(before, after)) {
+    return { path: file, action: 'unchanged' };
+  }
+  const action: 'created' | 'updated' =
+    before ? 'updated' : (fs.existsSync(file) ? 'updated' : 'created');
+  if (!existing.mcpServers) existing.mcpServers = {};
+  existing.mcpServers.codegraph = after;
+  writeJsonFile(file, existing);
+  return { path: file, action };
+}
+
+/**
+ * Strip the marker-delimited CodeGraph block from GEMINI.md if a prior
+ * install wrote one. Used by both install (self-heal on upgrade) and
+ * uninstall — see issue #529.
+ */
+function removeInstructionsEntry(loc: Location): WriteResult['files'][number] {
+  const file = instructionsPath(loc);
+  const action = removeMarkedSection(file, CODEGRAPH_SECTION_START, CODEGRAPH_SECTION_END);
+  return { path: file, action };
+}
+
+export const geminiTarget: AgentTarget = new GeminiTarget();
diff --git a/src/installer/targets/hermes.ts b/src/installer/targets/hermes.ts
new file mode 100644
index 000000000..eacab6d3d
--- /dev/null
+++ b/src/installer/targets/hermes.ts
@@ -0,0 +1,356 @@
+/**
+ * Hermes Agent target.
+ *
+ * Hermes reads MCP servers from `$HERMES_HOME/config.yaml` under the
+ * top-level `mcp_servers` key, and exposes discovered MCP tools through
+ * dynamic toolsets named `mcp-<server>`. We add:
+ *
+ *   mcp_servers.codegraph -> `codegraph serve --mcp`
+ *   platform_toolsets.cli -> `mcp-codegraph`
+ *
+ * The second entry matters because Hermes CLI profiles often enable an
+ * explicit `platform_toolsets.cli` list. Without `mcp-codegraph` in that
+ * list, the MCP server can be configured and connected but its tools may
+ * still be filtered out of normal CLI sessions.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  AgentTarget,
+  DetectionResult,
+  InstallOptions,
+  Location,
+  WriteResult,
+} from './types';
+import { atomicWriteFileSync } from './shared';
+
+type LineRange = { start: number; end: number };
+
+class HermesTarget implements AgentTarget {
+  readonly id = 'hermes' as const;
+  readonly displayName = 'Hermes Agent';
+  readonly docsUrl = 'https://hermes-agent.nousresearch.com';
+
+  supportsLocation(loc: Location): boolean {
+    return loc === 'global';
+  }
+
+  detect(loc: Location): DetectionResult {
+    if (loc !== 'global') {
+      return { installed: false, alreadyConfigured: false };
+    }
+    const file = configPath();
+    const content = readText(file);
+    const installed = fs.existsSync(hermesHome()) || fs.existsSync(file);
+    return {
+      installed,
+      alreadyConfigured: hasCodeGraphMcpServer(content),
+      configPath: file,
+    };
+  }
+
+  install(loc: Location, _opts: InstallOptions): WriteResult {
+    if (loc !== 'global') {
+      return {
+        files: [],
+        notes: ['Hermes Agent uses $HERMES_HOME/config.yaml; re-run with --location=global.'],
+      };
+    }
+    return {
+      files: [writeHermesConfig()],
+      notes: ['Start a new Hermes session for MCP changes to take effect.'],
+    };
+  }
+
+  uninstall(loc: Location): WriteResult {
+    if (loc !== 'global') return { files: [] };
+    const file = configPath();
+    if (!fs.existsSync(file)) {
+      return { files: [{ path: file, action: 'not-found' }] };
+    }
+
+    const before = readText(file);
+    const after = removeCodeGraphToolset(removeCodeGraphMcpServer(before));
+    if (after === before) {
+      return { files: [{ path: file, action: 'not-found' }] };
+    }
+    atomicWriteFileSync(file, ensureTrailingNewline(after));
+    return { files: [{ path: file, action: 'removed' }] };
+  }
+
+  printConfig(loc: Location): string {
+    if (loc !== 'global') {
+      return '# Hermes Agent uses $HERMES_HOME/config.yaml; use --location=global.\n';
+    }
+    return [
+      `# Add to ${configPath()}`,
+      '',
+      renderCodeGraphMcpBlock().join('\n'),
+      '',
+      'platform_toolsets:',
+      '  cli:',
+      '    - hermes-cli',
+      '    - mcp-codegraph',
+      '',
+    ].join('\n');
+  }
+
+  describePaths(loc: Location): string[] {
+    return loc === 'global' ? [configPath()] : [];
+  }
+}
+
+function hermesHome(): string {
+  return process.env.HERMES_HOME
+    ? path.resolve(process.env.HERMES_HOME)
+    : path.join(os.homedir(), '.hermes');
+}
+
+function configPath(): string {
+  return path.join(hermesHome(), 'config.yaml');
+}
+
+function readText(file: string): string {
+  try {
+    return fs.readFileSync(file, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function writeHermesConfig(): WriteResult['files'][number] {
+  const file = configPath();
+  const existed = fs.existsSync(file);
+  const before = readText(file);
+  const afterMcp = upsertCodeGraphMcpServer(before);
+  const after = upsertCodeGraphToolset(afterMcp);
+
+  if (after === before) {
+    return { path: file, action: 'unchanged' };
+  }
+  atomicWriteFileSync(file, ensureTrailingNewline(after));
+  return { path: file, action: existed ? 'updated' : 'created' };
+}
+
+function ensureTrailingNewline(text: string): string {
+  return text.endsWith('\n') ? text : text + '\n';
+}
+
+function splitLines(content: string): string[] {
+  return content.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n');
+}
+
+function joinLines(lines: string[]): string {
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  return lines.join('\n') + '\n';
+}
+
+function topLevelRange(lines: string[], key: string): LineRange | null {
+  const start = lines.findIndex((line) => line.trim() === `${key}:`);
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i] ?? '';
+    if (line.trim() === '') continue;
+    if (/^[A-Za-z_][A-Za-z0-9_-]*:\s*(?:#.*)?$/.test(line)) {
+      end = i;
+      break;
+    }
+  }
+  return { start, end };
+}
+
+function childRange(lines: string[], parent: LineRange, child: string): LineRange | null {
+  const startPattern = new RegExp(`^  ${escapeRegExp(child)}:\\s*(?:#.*)?$`);
+  let start = -1;
+  for (let i = parent.start + 1; i < parent.end; i++) {
+    if (startPattern.test(lines[i] ?? '')) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return null;
+
+  let end = parent.end;
+  for (let i = start + 1; i < parent.end; i++) {
+    const line = lines[i] ?? '';
+    if (line.trim() === '') continue;
+    if (/^  \S/.test(line)) {
+      end = i;
+      break;
+    }
+  }
+  while (end > start + 1 && (lines[end - 1] ?? '').trim() === '') {
+    end--;
+  }
+  return { start, end };
+}
+
+/**
+ * Block-range for a 2-space-indented child whose value is a YAML block list.
+ *
+ * Unlike `childRange`, this handles PyYAML's default `default_flow_style=False`
+ * serialization, where list items sit at the SAME indent as the parent key:
+ *
+ *     cli:
+ *     - hermes-cli       # indent 2 — belongs to cli, not a sibling
+ *     - browser
+ *
+ * `childRange`'s `^  \S` heuristic mistakes that first `  - hermes-cli` line
+ * for the next sibling key and truncates the block, causing inserts to land
+ * before the existing items at a different indent (issue #456). This helper
+ * recognizes a `  - ` line as part of the block instead, and reports back
+ * the actual indent used by existing items so the inserter matches it.
+ */
+function listChildBlock(
+  lines: string[],
+  parent: LineRange,
+  child: string,
+): (LineRange & { itemIndent: string }) | null {
+  const startPattern = new RegExp(`^  ${escapeRegExp(child)}:\\s*(?:#.*)?$`);
+  let start = -1;
+  for (let i = parent.start + 1; i < parent.end; i++) {
+    if (startPattern.test(lines[i] ?? '')) {
+      start = i;
+      break;
+    }
+  }
+  if (start === -1) return null;
+
+  let end = parent.end;
+  for (let i = start + 1; i < parent.end; i++) {
+    const line = lines[i] ?? '';
+    if (line.trim() === '') continue;
+    const indentMatch = line.match(/^( *)/);
+    const indent = indentMatch?.[1]?.length ?? 0;
+    if (indent >= 4) continue;
+    if (indent === 2 && /^  - /.test(line)) continue;
+    end = i;
+    break;
+  }
+  while (end > start + 1 && (lines[end - 1] ?? '').trim() === '') {
+    end--;
+  }
+
+  let itemIndent = '    ';
+  for (let i = start + 1; i < end; i++) {
+    const m = (lines[i] ?? '').match(/^( +)- /);
+    if (m && m[1]) {
+      itemIndent = m[1];
+      break;
+    }
+  }
+  return { start, end, itemIndent };
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function renderCodeGraphMcpChild(): string[] {
+  return [
+    '  codegraph:',
+    '    command: codegraph',
+    '    args:',
+    '      - serve',
+    '      - --mcp',
+    '    timeout: 120',
+    '    connect_timeout: 60',
+    '    enabled: true',
+  ];
+}
+
+function renderCodeGraphMcpBlock(): string[] {
+  return ['mcp_servers:', ...renderCodeGraphMcpChild()];
+}
+
+function hasCodeGraphMcpServer(content: string): boolean {
+  const lines = splitLines(content);
+  const parent = topLevelRange(lines, 'mcp_servers');
+  return !!parent && !!childRange(lines, parent, 'codegraph');
+}
+
+function upsertCodeGraphMcpServer(content: string): string {
+  const lines = splitLines(content);
+  const parent = topLevelRange(lines, 'mcp_servers');
+  const child = parent ? childRange(lines, parent, 'codegraph') : null;
+  const replacement = renderCodeGraphMcpChild();
+
+  if (!parent) {
+    if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+    if (lines.length > 0) lines.push('');
+    lines.push(...renderCodeGraphMcpBlock());
+    return joinLines(lines);
+  }
+
+  if (child) {
+    const existing = lines.slice(child.start, child.end);
+    if (arrayEqual(existing, replacement)) return joinLines(lines);
+    lines.splice(child.start, child.end - child.start, ...replacement);
+    return joinLines(lines);
+  }
+
+  lines.splice(parent.end, 0, ...replacement);
+  return joinLines(lines);
+}
+
+function removeCodeGraphMcpServer(content: string): string {
+  const lines = splitLines(content);
+  const parent = topLevelRange(lines, 'mcp_servers');
+  const child = parent ? childRange(lines, parent, 'codegraph') : null;
+  if (!child) return content;
+  lines.splice(child.start, child.end - child.start);
+  return joinLines(lines);
+}
+
+function upsertCodeGraphToolset(content: string): string {
+  const lines = splitLines(content);
+  const parent = topLevelRange(lines, 'platform_toolsets');
+  const cli = parent ? listChildBlock(lines, parent, 'cli') : null;
+
+  if (!parent) {
+    if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+    if (lines.length > 0) lines.push('');
+    lines.push('platform_toolsets:', '  cli:', '    - hermes-cli', '    - mcp-codegraph');
+    return joinLines(lines);
+  }
+
+  if (!cli) {
+    lines.splice(parent.end, 0, '  cli:', '    - hermes-cli', '    - mcp-codegraph');
+    return joinLines(lines);
+  }
+
+  const hasEntry = lines
+    .slice(cli.start + 1, cli.end)
+    .some((line) => line.trim() === '- mcp-codegraph');
+  if (hasEntry) return joinLines(lines);
+
+  lines.splice(cli.end, 0, `${cli.itemIndent}- mcp-codegraph`);
+  return joinLines(lines);
+}
+
+function removeCodeGraphToolset(content: string): string {
+  const lines = splitLines(content);
+  const parent = topLevelRange(lines, 'platform_toolsets');
+  const cli = parent ? listChildBlock(lines, parent, 'cli') : null;
+  if (!cli) return content;
+
+  const hasEntry = lines
+    .slice(cli.start + 1, cli.end)
+    .some((line) => line.trim() === '- mcp-codegraph');
+  if (!hasEntry) return content;
+
+  const next = lines.filter((line, idx) => {
+    if (idx <= cli.start || idx >= cli.end) return true;
+    return line.trim() !== '- mcp-codegraph';
+  });
+  return joinLines(next);
+}
+
+function arrayEqual(a: string[], b: string[]): boolean {
+  return a.length === b.length && a.every((value, idx) => value === b[idx]);
+}
+
+export const hermesTarget: AgentTarget = new HermesTarget();
diff --git a/src/installer/targets/kiro.ts b/src/installer/targets/kiro.ts
new file mode 100644
index 000000000..5658dd0ee
--- /dev/null
+++ b/src/installer/targets/kiro.ts
@@ -0,0 +1,165 @@
+/**
+ * Kiro CLI / IDE target. Writes:
+ *
+ *   - MCP server entry to `~/.kiro/settings/mcp.json` (global) or
+ *     `./.kiro/settings/mcp.json` (local). Standard `mcpServers.codegraph`
+ *     shape, same as Claude / Cursor / Gemini.
+ *   - Instructions to `~/.kiro/steering/codegraph.md` (global) or
+ *     `./.kiro/steering/codegraph.md` (local). Kiro's "steering" system
+ *     loads every `*.md` file in the steering dir as agent context, so
+ *     a dedicated `codegraph.md` is the natural surface — we own the
+ *     whole file outright (no marker-based merging needed) and delete
+ *     it on uninstall.
+ *
+ * No permissions concept — Kiro gates tool invocations through its own
+ * UI prompts rather than an external allowlist. `autoAllow` is silently
+ * ignored.
+ *
+ * Paths are identical on macOS / Linux / Windows because Kiro resolves
+ * its config root from `os.homedir()` on all three (Windows `~` →
+ * `%USERPROFILE%\.kiro`).
+ *
+ * Docs: https://kiro.dev/docs/cli/mcp/
+ *       https://kiro.dev/docs/cli/steering/
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  AgentTarget,
+  DetectionResult,
+  InstallOptions,
+  Location,
+  WriteResult,
+} from './types';
+import {
+  getMcpServerConfig,
+  jsonDeepEqual,
+  readJsonFile,
+  writeJsonFile,
+} from './shared';
+
+function configDir(loc: Location): string {
+  return loc === 'global'
+    ? path.join(os.homedir(), '.kiro')
+    : path.join(process.cwd(), '.kiro');
+}
+function mcpJsonPath(loc: Location): string {
+  return path.join(configDir(loc), 'settings', 'mcp.json');
+}
+function steeringPath(loc: Location): string {
+  return path.join(configDir(loc), 'steering', 'codegraph.md');
+}
+
+class KiroTarget implements AgentTarget {
+  readonly id = 'kiro' as const;
+  readonly displayName = 'Kiro';
+  readonly docsUrl = 'https://kiro.dev/docs/cli/mcp/';
+
+  supportsLocation(_loc: Location): boolean {
+    return true;
+  }
+
+  detect(loc: Location): DetectionResult {
+    const file = mcpJsonPath(loc);
+    const config = readJsonFile(file);
+    const alreadyConfigured = !!config.mcpServers?.codegraph;
+    const installed = loc === 'global'
+      ? fs.existsSync(configDir('global')) || fs.existsSync(file)
+      : fs.existsSync(file) || fs.existsSync(configDir('local'));
+    return { installed, alreadyConfigured, configPath: file };
+  }
+
+  install(loc: Location, _opts: InstallOptions): WriteResult {
+    const files: WriteResult['files'] = [];
+    files.push(writeMcpEntry(loc));
+
+    // The steering doc is no longer written — the codegraph usage
+    // guidance ships in the MCP server's `initialize` response (issue
+    // #529). Delete a `codegraph.md` a previous install created so an
+    // upgrade self-heals.
+    const steeringCleanup = removeSteeringEntry(loc);
+    if (steeringCleanup.action === 'removed') files.push(steeringCleanup);
+
+    return {
+      files,
+      // The IDE-only enable-MCP step is load-bearing: Kiro IDE ships
+      // with MCP support disabled by default, so even a valid
+      // `~/.kiro/settings/mcp.json` at the documented path is ignored
+      // until the user flips the toggle. Kiro CLI reads the same file
+      // without a gate, so we call out which audience this applies to.
+      notes: [
+        'Restart Kiro for MCP changes to take effect.',
+        'Kiro IDE: also enable MCP in Settings (search "MCP" → "Enabled"). Kiro CLI users can skip this step.',
+      ],
+    };
+  }
+
+  uninstall(loc: Location): WriteResult {
+    const files: WriteResult['files'] = [];
+
+    const file = mcpJsonPath(loc);
+    const config = readJsonFile(file);
+    if (config.mcpServers?.codegraph) {
+      delete config.mcpServers.codegraph;
+      if (Object.keys(config.mcpServers).length === 0) {
+        delete config.mcpServers;
+      }
+      writeJsonFile(file, config);
+      files.push({ path: file, action: 'removed' });
+    } else {
+      files.push({ path: file, action: 'not-found' });
+    }
+
+    files.push(removeSteeringEntry(loc));
+
+    return { files };
+  }
+
+  printConfig(loc: Location): string {
+    const target = mcpJsonPath(loc);
+    const snippet = JSON.stringify({ mcpServers: { codegraph: getMcpServerConfig() } }, null, 2);
+    return `# Add to ${target}\n\n${snippet}\n`;
+  }
+
+  describePaths(loc: Location): string[] {
+    return [mcpJsonPath(loc), steeringPath(loc)];
+  }
+}
+
+function writeMcpEntry(loc: Location): WriteResult['files'][number] {
+  const file = mcpJsonPath(loc);
+  const dir = path.dirname(file);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const existing = readJsonFile(file);
+  const before = existing.mcpServers?.codegraph;
+  const after = getMcpServerConfig();
+
+  if (jsonDeepEqual(before, after)) {
+    return { path: file, action: 'unchanged' };
+  }
+  const action: 'created' | 'updated' =
+    before ? 'updated' : (fs.existsSync(file) ? 'updated' : 'created');
+  if (!existing.mcpServers) existing.mcpServers = {};
+  existing.mcpServers.codegraph = after;
+  writeJsonFile(file, existing);
+  return { path: file, action };
+}
+
+/**
+ * Delete the steering file we own. If a user has hand-edited the file
+ * out of recognition we still remove it — codegraph.md is a name we
+ * claim, and a partial install leaving the file behind is worse than
+ * a clean delete. Used by both install (self-heal on upgrade — see
+ * issue #529) and uninstall.
+ */
+function removeSteeringEntry(loc: Location): WriteResult['files'][number] {
+  const file = steeringPath(loc);
+  if (!fs.existsSync(file)) return { path: file, action: 'not-found' };
+  try { fs.unlinkSync(file); } catch { /* ignore */ }
+  return { path: file, action: 'removed' };
+}
+
+export const kiroTarget: AgentTarget = new KiroTarget();
diff --git a/src/installer/targets/opencode.ts b/src/installer/targets/opencode.ts
index bb3388bf0..2db070960 100644
--- a/src/installer/targets/opencode.ts
+++ b/src/installer/targets/opencode.ts
@@ -41,12 +41,11 @@ import {
   atomicWriteFileSync,
   jsonDeepEqual,
   removeMarkedSection,
-  replaceOrAppendMarkedSection,
+  upsertInstructionsEntry,
 } from './shared';
 import {
   CODEGRAPH_SECTION_END,
   CODEGRAPH_SECTION_START,
-  INSTRUCTIONS_TEMPLATE,
 } from '../instructions-template';
 
 function globalConfigDir(): string {
@@ -128,7 +127,12 @@ class OpencodeTarget implements AgentTarget {
   install(loc: Location, _opts: InstallOptions): WriteResult {
     const files: WriteResult['files'] = [];
     files.push(writeMcpEntry(loc));
-    files.push(writeInstructionsEntry(loc));
+
+    // AGENTS.md gets the short marker-fenced CodeGraph block (#704):
+    // subagents and non-MCP harnesses read AGENTS.md but never the MCP
+    // initialize instructions. Upsert self-heals a stale pre-#529 block.
+    files.push(upsertInstructionsEntry(instructionsPath(loc)));
+
     return { files };
   }
 
@@ -163,9 +167,7 @@ class OpencodeTarget implements AgentTarget {
       }
     }
 
-    const instr = instructionsPath(loc);
-    const instrAction = removeMarkedSection(instr, CODEGRAPH_SECTION_START, CODEGRAPH_SECTION_END);
-    files.push({ path: instr, action: instrAction });
+    files.push(removeInstructionsEntry(loc));
 
     return { files };
   }
@@ -223,22 +225,15 @@ function writeMcpEntry(loc: Location): WriteResult['files'][number] {
   return { path: file, action: existed ? 'updated' : 'created' };
 }
 
-function writeInstructionsEntry(loc: Location): WriteResult['files'][number] {
+/**
+ * Strip the marker-delimited CodeGraph block from AGENTS.md if a prior
+ * install wrote one. Used by both install (self-heal on upgrade) and
+ * uninstall — see issue #529.
+ */
+function removeInstructionsEntry(loc: Location): WriteResult['files'][number] {
   const file = instructionsPath(loc);
-  const dir = path.dirname(file);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-
-  const action = replaceOrAppendMarkedSection(
-    file,
-    INSTRUCTIONS_TEMPLATE,
-    CODEGRAPH_SECTION_START,
-    CODEGRAPH_SECTION_END,
-  );
-  const mapped: 'created' | 'updated' | 'unchanged' =
-    action === 'created' ? 'created'
-      : action === 'unchanged' ? 'unchanged'
-        : 'updated';
-  return { path: file, action: mapped };
+  const action = removeMarkedSection(file, CODEGRAPH_SECTION_START, CODEGRAPH_SECTION_END);
+  return { path: file, action };
 }
 
 export const opencodeTarget: AgentTarget = new OpencodeTarget();
diff --git a/src/installer/targets/registry.ts b/src/installer/targets/registry.ts
index e671fd197..5e929d468 100644
--- a/src/installer/targets/registry.ts
+++ b/src/installer/targets/registry.ts
@@ -12,12 +12,20 @@ import { claudeTarget } from './claude';
 import { cursorTarget } from './cursor';
 import { codexTarget } from './codex';
 import { opencodeTarget } from './opencode';
+import { hermesTarget } from './hermes';
+import { geminiTarget } from './gemini';
+import { antigravityTarget } from './antigravity';
+import { kiroTarget } from './kiro';
 
 export const ALL_TARGETS: readonly AgentTarget[] = Object.freeze([
   claudeTarget,
   cursorTarget,
   codexTarget,
   opencodeTarget,
+  hermesTarget,
+  geminiTarget,
+  antigravityTarget,
+  kiroTarget,
 ]);
 
 export function getTarget(id: string): AgentTarget | undefined {
diff --git a/src/installer/targets/shared.ts b/src/installer/targets/shared.ts
index 6d54ab570..0c854682a 100644
--- a/src/installer/targets/shared.ts
+++ b/src/installer/targets/shared.ts
@@ -10,6 +10,11 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import {
+  CODEGRAPH_INSTRUCTIONS_BLOCK,
+  CODEGRAPH_SECTION_START,
+  CODEGRAPH_SECTION_END,
+} from '../instructions-template';
 
 /**
  * The MCP-server config block codegraph injects. Same shape across
@@ -31,12 +36,13 @@ export function getMcpServerConfig(): { type: string; command: string; args: str
  */
 export function getCodeGraphPermissions(): string[] {
   return [
+    'mcp__codegraph__codegraph_explore',
     'mcp__codegraph__codegraph_search',
-    'mcp__codegraph__codegraph_context',
+    'mcp__codegraph__codegraph_node',
     'mcp__codegraph__codegraph_callers',
     'mcp__codegraph__codegraph_callees',
     'mcp__codegraph__codegraph_impact',
-    'mcp__codegraph__codegraph_node',
+    'mcp__codegraph__codegraph_files',
     'mcp__codegraph__codegraph_status',
   ];
 }
@@ -166,6 +172,26 @@ export function replaceOrAppendMarkedSection(
   return 'appended';
 }
 
+/**
+ * Upsert the CodeGraph instructions block into an agent instructions
+ * file (CLAUDE.md / AGENTS.md / GEMINI.md). The one write shared by
+ * every target: self-heals a stale pre-#529 long block (markers match →
+ * replaced by the current short one), appends after existing user
+ * content otherwise, and reports `unchanged` on byte-equal re-runs so
+ * install stays idempotent. See `instructions-template.ts` for why this
+ * block exists (#704: subagents + non-MCP harnesses never see the MCP
+ * initialize instructions).
+ */
+export function upsertInstructionsEntry(file: string): { path: string; action: 'created' | 'updated' | 'unchanged' } {
+  const action = replaceOrAppendMarkedSection(
+    file,
+    CODEGRAPH_INSTRUCTIONS_BLOCK,
+    CODEGRAPH_SECTION_START,
+    CODEGRAPH_SECTION_END,
+  );
+  return { path: file, action: action === 'appended' ? 'updated' : action };
+}
+
 /**
  * Inverse of `replaceOrAppendMarkedSection`. Strips the marker
  * block from `filePath` if present. If the file becomes empty after
diff --git a/src/installer/targets/types.ts b/src/installer/targets/types.ts
index fdff0d778..4b3267e97 100644
--- a/src/installer/targets/types.ts
+++ b/src/installer/targets/types.ts
@@ -19,7 +19,7 @@ export type Location = 'global' | 'local';
  * lookup. New targets add a value here when they're added to the
  * registry. Keep these short and lowercase.
  */
-export type TargetId = 'claude' | 'cursor' | 'codex' | 'opencode';
+export type TargetId = 'claude' | 'cursor' | 'codex' | 'opencode' | 'hermes' | 'gemini' | 'antigravity' | 'kiro';
 
 /**
  * Result of `target.detect(location)`.
@@ -103,19 +103,4 @@ export interface AgentTarget {
   printConfig(loc: Location): string;
   /** Filesystem paths this target would write to at this location. */
   describePaths(loc: Location): string[];
-  /**
-   * Optional. Write any project-local surfaces this target needs in
-   * order to work fully when its MCP config is configured globally.
-   * Called by `codegraph init` to bootstrap new projects without
-   * forcing the user to re-run `codegraph install` per project.
-   *
-   * Most targets need nothing here — their global config is complete.
-   * Cursor is the notable exception: its rules system
-   * (`.cursor/rules/*.mdc`) is project-scoped only, and is what makes
-   * Cursor's agent prefer codegraph over its built-in grep.
-   *
-   * Must be idempotent. Targets that have nothing project-local omit
-   * the method entirely.
-   */
-  wireProjectSurfaces?(): WriteResult;
 }
diff --git a/src/mcp/daemon-paths.ts b/src/mcp/daemon-paths.ts
new file mode 100644
index 000000000..b1afc40df
--- /dev/null
+++ b/src/mcp/daemon-paths.ts
@@ -0,0 +1,99 @@
+/**
+ * Daemon socket + lockfile path helpers — issue #411.
+ *
+ * One shared `codegraph serve --mcp` daemon per project root means we need a
+ * stable, project-keyed rendezvous between cooperating processes. The IPC
+ * surface area is just two file paths:
+ *
+ *   - `daemon.sock` — Unix domain socket / named pipe the daemon listens on.
+ *   - `daemon.pid` — atomic-create lockfile holding the daemon's pid + version.
+ *
+ * Both live under `.codegraph/` so the project-scoped uninstall (`codegraph
+ * uninit`) sweeps them up for free.
+ *
+ * Special-case: Unix domain socket paths have a hard length limit (~104 on
+ * macOS, ~108 on Linux); when the in-project path exceeds it we fall back to
+ * an absolute-path hash under `os.tmpdir()`. The pidfile always stays in the
+ * project (it doesn't have a length limit) — and acts as the authoritative
+ * pointer to the socket path the daemon chose.
+ */
+
+import * as crypto from 'crypto';
+import * as os from 'os';
+import * as path from 'path';
+import { getCodeGraphDir } from '../directory';
+
+/** Soft upper bound for in-project socket paths. */
+const POSIX_SOCKET_PATH_LIMIT = 100;
+
+/** Short stable identifier for a project root — used in tmpdir/pipe names. */
+function projectHash(projectRoot: string): string {
+  return crypto.createHash('sha256').update(path.resolve(projectRoot)).digest('hex').slice(0, 16);
+}
+
+/**
+ * Compute the socket / named-pipe path the daemon should listen on (and the
+ * proxy should connect to) for `projectRoot`. Deterministic given a project
+ * root, so independent processes converge without coordination.
+ */
+export function getDaemonSocketPath(projectRoot: string): string {
+  if (process.platform === 'win32') {
+    return `\\\\.\\pipe\\codegraph-${projectHash(projectRoot)}`;
+  }
+  const inProject = path.join(getCodeGraphDir(projectRoot), 'daemon.sock');
+  if (inProject.length <= POSIX_SOCKET_PATH_LIMIT) return inProject;
+  // Long project paths (deep monorepos, Bazel out dirs) need tmpdir fallback
+  // or `bind` returns EADDRINUSE / ENAMETOOLONG. Hash keeps it project-scoped.
+  return path.join(os.tmpdir(), `codegraph-${projectHash(projectRoot)}.sock`);
+}
+
+/** Absolute path to the daemon pid lockfile for `projectRoot`. */
+export function getDaemonPidPath(projectRoot: string): string {
+  return path.join(getCodeGraphDir(projectRoot), 'daemon.pid');
+}
+
+/** Structured contents of the pid lockfile. */
+export interface DaemonLockInfo {
+  pid: number;
+  version: string;
+  socketPath: string;
+  startedAt: number;
+}
+
+/**
+ * Serialize a {@link DaemonLockInfo} for writing to the pidfile. JSON for
+ * human readability — operators occasionally `cat` this when debugging.
+ */
+export function encodeLockInfo(info: DaemonLockInfo): string {
+  return JSON.stringify(info, null, 2) + '\n';
+}
+
+/**
+ * Parse a pidfile body. Tolerant of old-format pidfiles (plain decimal pid) so
+ * a 0.10.x daemon doesn't trip over a 0.9.x lockfile if that ever happens —
+ * we treat such a lockfile as "process is unknown version, refuse to share."
+ */
+export function decodeLockInfo(raw: string): DaemonLockInfo | null {
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (
+      parsed &&
+      typeof parsed.pid === 'number' &&
+      typeof parsed.version === 'string' &&
+      typeof parsed.socketPath === 'string' &&
+      typeof parsed.startedAt === 'number'
+    ) {
+      return parsed as DaemonLockInfo;
+    }
+    return null;
+  } catch {
+    // Fall through to legacy plain-pid handling.
+  }
+  const pid = Number(trimmed);
+  if (Number.isFinite(pid) && pid > 0) {
+    return { pid, version: 'unknown', socketPath: '', startedAt: 0 };
+  }
+  return null;
+}
diff --git a/src/mcp/daemon.ts b/src/mcp/daemon.ts
new file mode 100644
index 000000000..df9a7d82c
--- /dev/null
+++ b/src/mcp/daemon.ts
@@ -0,0 +1,618 @@
+/**
+ * Shared MCP daemon — issue #411.
+ *
+ * One detached `codegraph serve --mcp` daemon process per project root,
+ * accepting N concurrent MCP clients over a Unix-domain socket (or named pipe
+ * on Windows). Each incoming connection gets its own {@link MCPSession}; all
+ * sessions share a single {@link MCPEngine}, which means a single file watcher
+ * (one inotify set), a single SQLite connection (one WAL writer), and a single
+ * tree-sitter warm-up — paid once, amortized across every agent talking to the
+ * project.
+ *
+ * Lifecycle (see also `./index.ts` and `./proxy.ts`):
+ *   - The daemon is spawned **detached** (its own session/process group, stdio
+ *     decoupled) by the first launcher that finds no daemon running. It is NOT
+ *     a child of any MCP host, so closing one terminal / Ctrl-C'ing one session
+ *     can't take it down and sever the others. That's why this process has no
+ *     PPID watchdog: it deliberately outlives every individual client.
+ *   - Every MCP host talks to the daemon through a thin `proxy` process (the
+ *     thing the host actually spawned). The proxy keeps the #277 PPID watchdog,
+ *     so a SIGKILL'd host still reaps its proxy promptly; the proxy's socket
+ *     close then decrements the daemon's refcount.
+ *   - When the last client disconnects the daemon lingers for
+ *     `CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS` (default 300s) so back-to-back agent
+ *     runs in the same project don't repay startup, then exits cleanly. This is
+ *     what keeps a single-agent session from leaking a daemon forever (#277).
+ *
+ * What this file owns:
+ *   - Listening on the daemon socket and spawning per-connection sessions.
+ *   - The handshake "hello" line that lets a proxy verify it found a
+ *     same-version daemon before piping any JSON-RPC through it.
+ *   - The lockfile (`.codegraph/daemon.pid`) competing daemons arbitrate
+ *     against — atomic `O_EXCL` create with the full record written in the same
+ *     breath (no empty-file window) + cleanup on exit.
+ *   - Reference counting + idle timeout.
+ *   - Graceful shutdown on SIGTERM/SIGINT and idle exit.
+ *
+ * What this file does NOT own:
+ *   - The proxy side (`./proxy.ts`).
+ *   - The decision of *whether* to run as daemon at all — that's `MCPServer`.
+ *   - The MCP protocol state machine — that's `./session.ts`.
+ */
+
+import * as fs from 'fs';
+import * as net from 'net';
+import * as path from 'path';
+import { MCPEngine } from './engine';
+import { MCPSession } from './session';
+import { SocketTransport } from './transport';
+import {
+  DaemonLockInfo,
+  decodeLockInfo,
+  encodeLockInfo,
+  getDaemonPidPath,
+  getDaemonSocketPath,
+} from './daemon-paths';
+import { CodeGraphPackageVersion } from './version';
+
+/** Default idle linger after the last client disconnects. */
+const DEFAULT_IDLE_TIMEOUT_MS = 300_000;
+
+/**
+ * Hard ceiling on how long the daemon stays up with clients connected but no
+ * inbound traffic. A backstop (#692): if a client's socket-close is never
+ * delivered (a Windows named-pipe hazard) it stays counted forever and the
+ * normal idle timer — which only arms at zero clients — never fires. A phantom
+ * client sends no traffic, so bounding on inactivity reaps the daemon anyway.
+ * Set generously so a real but momentarily-idle session isn't reaped mid-use.
+ */
+const DEFAULT_MAX_IDLE_MS = 1_800_000; // 30 min
+
+/** How often the daemon sweeps connected clients for a dead peer process (#692). */
+const DEFAULT_CLIENT_SWEEP_MS = 30_000;
+
+/** How long the daemon waits for the optional client-hello before proceeding without it. */
+const CLIENT_HELLO_TIMEOUT_MS = 3_000;
+
+/** Bytes/parse-window for an oversized hello line — bounded against a malicious peer. */
+const MAX_HELLO_LINE_BYTES = 4096;
+
+/**
+ * Wire format for the one-shot hello line the daemon emits on every new
+ * connection. Versioned with the package's own semver so a 0.9.x proxy never
+ * pipes through a 0.10.x daemon (or vice-versa) — the proxy falls back to
+ * direct mode on mismatch rather than risk subtle wire incompatibilities.
+ */
+export interface DaemonHello {
+  codegraph: string; // package version (must match the proxy's own version)
+  pid: number;       // daemon pid (informational; for `ps` debugging)
+  socketPath: string; // echoed back so the proxy can log it
+  protocol: 1;       // bump if the hello shape changes
+}
+
+/**
+ * Optional reverse-handshake line a proxy sends right after it verifies the
+ * daemon hello, carrying its own pids so the daemon can reap the client if its
+ * process dies WITHOUT the socket ever signalling close (the Windows named-pipe
+ * hazard behind #692). Entirely optional and fail-safe: a connection that never
+ * sends it (a legacy/direct client) just falls back to the socket-close
+ * lifecycle. The `codegraph_client` marker is what tells it apart from the
+ * client's first JSON-RPC message.
+ */
+export interface DaemonClientHello {
+  codegraph_client: 1;
+  pid: number;             // the proxy process's own pid
+  hostPid: number | null;  // the MCP host pid (past any launcher shim), if known
+}
+
+export interface DaemonStartResult {
+  /** Always-non-null for a successfully-started daemon. */
+  socketPath: string;
+  /** Lockfile contents as written. */
+  lock: DaemonLockInfo;
+}
+
+/**
+ * Run as the shared daemon for `projectRoot`. Resolves once the socket is
+ * listening. The Daemon owns the socket, the engine, and the lockfile until
+ * `stop()` is called or it exits on idle/signal.
+ *
+ * Race-safe: callers must first call `tryAcquireDaemonLock(projectRoot)` and
+ * only construct a Daemon if they got the lock (`kind: 'acquired'`). The atomic
+ * `O_EXCL` create inside the acquire helper — which now also writes the full
+ * record before returning — is the only synchronization between competing
+ * daemons.
+ */
+export class Daemon {
+  private server: net.Server | null = null;
+  private clients = new Set<MCPSession>();
+  /** Per-client peer pids from the optional client-hello, for the liveness sweep. */
+  private clientPeers = new Map<MCPSession, { pid: number | null; hostPid: number | null }>();
+  private idleTimer: NodeJS.Timeout | null = null;
+  private idleTimeoutMs: number;
+  private maxIdleMs: number;
+  private lastActivityAt = Date.now();
+  private maxIdleTimer: NodeJS.Timeout | null = null;
+  private clientSweepTimer: NodeJS.Timeout | null = null;
+  private engine: MCPEngine;
+  private stopping = false;
+  private socketPath: string;
+  private pidPath: string;
+
+  constructor(
+    private projectRoot: string,
+    opts: { idleTimeoutMs?: number; maxIdleMs?: number } = {},
+  ) {
+    this.socketPath = getDaemonSocketPath(projectRoot);
+    this.pidPath = getDaemonPidPath(projectRoot);
+    this.idleTimeoutMs = opts.idleTimeoutMs ?? resolveIdleTimeoutMs();
+    this.maxIdleMs = opts.maxIdleMs ?? resolveMaxIdleMs();
+    this.engine = new MCPEngine();
+    this.engine.setProjectPathHint(projectRoot);
+  }
+
+  /**
+   * Bind the socket, kick off engine init, and register signal handlers. The
+   * lockfile body was already written atomically by `tryAcquireDaemonLock`, so
+   * there is nothing to write here. The promise resolves once the server is
+   * listening — the daemon then sticks around until idle/shutdown.
+   */
+  async start(): Promise<DaemonStartResult> {
+    // Engine init is deliberately backgrounded — see #172. The first session
+    // to land waits on `ensureInitialized` either way, and unloaded sessions
+    // (cross-project tool calls only) shouldn't pay any open cost.
+    void this.engine.ensureInitialized(this.projectRoot);
+
+    // Stale socket file (left over from a SIGKILL'd previous daemon) will
+    // wedge `listen` with EADDRINUSE. We arrived here holding the lockfile,
+    // which means there's no live daemon, so it's safe to clear.
+    if (process.platform !== 'win32') {
+      try { fs.unlinkSync(this.socketPath); } catch { /* not-exists is fine */ }
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      const server = net.createServer((socket) => this.handleConnection(socket));
+      server.once('error', (err) => reject(err));
+      server.listen(this.socketPath, () => {
+        // POSIX: tighten permissions to user-only — the socket lives under
+        // `.codegraph/`, which is git-ignored but may be on a shared FS.
+        if (process.platform !== 'win32') {
+          try { fs.chmodSync(this.socketPath, 0o600); } catch { /* best-effort */ }
+        }
+        this.server = server;
+        resolve();
+      });
+    });
+
+    const lock: DaemonLockInfo = {
+      pid: process.pid,
+      version: CodeGraphPackageVersion,
+      socketPath: this.socketPath,
+      startedAt: Date.now(),
+    };
+
+    process.stderr.write(
+      `[CodeGraph daemon] Listening on ${this.socketPath} (pid ${process.pid}, v${CodeGraphPackageVersion}). Idle timeout ${this.idleTimeoutMs}ms.\n`
+    );
+
+    // No clients yet: arm the idle timer immediately so a daemon that nobody
+    // ever connects to (e.g. spawned then abandoned because the launcher died)
+    // doesn't pin resources forever.
+    this.armIdleTimer();
+    this.startLivenessTimers();
+
+    process.on('SIGINT', () => this.stop('SIGINT'));
+    process.on('SIGTERM', () => this.stop('SIGTERM'));
+
+    return { socketPath: this.socketPath, lock };
+  }
+
+  /** Currently-connected client count. Exposed for tests / status output. */
+  getClientCount(): number {
+    return this.clients.size;
+  }
+
+  /** The socket path the daemon is (or will be) listening on. */
+  getSocketPath(): string {
+    return this.socketPath;
+  }
+
+  /** Graceful shutdown: close all sessions, the engine, and clean up the lock. */
+  async stop(reason: string = 'stop'): Promise<void> {
+    if (this.stopping) return;
+    this.stopping = true;
+    if (this.idleTimer) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+    if (this.maxIdleTimer) {
+      clearInterval(this.maxIdleTimer);
+      this.maxIdleTimer = null;
+    }
+    if (this.clientSweepTimer) {
+      clearInterval(this.clientSweepTimer);
+      this.clientSweepTimer = null;
+    }
+    process.stderr.write(`[CodeGraph daemon] Shutting down (${reason}; clients=${this.clients.size}).\n`);
+    for (const session of [...this.clients]) {
+      try { session.stop(); } catch { /* best-effort */ }
+    }
+    this.clients.clear();
+    if (this.server) {
+      await new Promise<void>((resolve) => this.server!.close(() => resolve()));
+      this.server = null;
+    }
+    this.engine.stop();
+    this.cleanupLockfile();
+    if (process.platform !== 'win32') {
+      try { fs.unlinkSync(this.socketPath); } catch { /* may already be gone */ }
+    }
+    process.exit(0);
+  }
+
+  private handleConnection(socket: net.Socket): void {
+    // Hello first so the proxy can verify versions before piping any
+    // application bytes. The proxy reads exactly one line, then forwards.
+    const hello: DaemonHello = {
+      codegraph: CodeGraphPackageVersion,
+      pid: process.pid,
+      socketPath: this.socketPath,
+      protocol: 1,
+    };
+    socket.write(JSON.stringify(hello) + '\n');
+
+    // Read the optional client-hello (proxy → daemon) to learn the client's
+    // peer pids, then hand the socket to the session. Fail-safe: any problem —
+    // timeout, a non-hello first line, an early close — yields null pids and we
+    // fall back to the socket-close lifecycle exactly as before (#692).
+    void readClientHello(socket).then((peers) => {
+      const transport = new SocketTransport(socket);
+      const session = new MCPSession(transport, this.engine, {
+        explicitProjectPath: this.projectRoot,
+      });
+      transport.onClose(() => this.dropClient(session));
+      this.clients.add(session);
+      this.clientPeers.set(session, peers);
+      this.disarmIdleTimer();
+      session.start();
+      // Observe inbound bytes purely to feed the inactivity backstop — a second
+      // 'data' listener that reads nothing, added AFTER the transport's so the
+      // unshifted client-hello tail reaches the transport intact.
+      socket.on('data', () => { this.lastActivityAt = Date.now(); });
+    });
+  }
+
+  private dropClient(session: MCPSession): void {
+    if (!this.clients.delete(session)) return;
+    this.clientPeers.delete(session);
+    if (this.clients.size === 0) this.armIdleTimer();
+  }
+
+  private armIdleTimer(): void {
+    if (this.idleTimer || this.stopping) return;
+    if (this.idleTimeoutMs <= 0) return; // 0 = never idle-exit
+    this.idleTimer = setTimeout(() => {
+      this.idleTimer = null;
+      // Last-second sanity check: if a connection landed between the timer
+      // firing and now, don't exit. (setImmediate-ordering is the only way
+      // this races; cheap to defend against.)
+      if (this.clients.size > 0) {
+        this.armIdleTimer();
+        return;
+      }
+      void this.stop('idle timeout');
+    }, this.idleTimeoutMs);
+    // Don't keep the event loop alive just for this — the net.Server keeps the
+    // loop alive while listening, so the timer still fires; once we stop() the
+    // loop should drain naturally.
+    this.idleTimer.unref?.();
+  }
+
+  private disarmIdleTimer(): void {
+    if (!this.idleTimer) return;
+    clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+  }
+
+  /**
+   * Defense-in-depth against a daemon that outlives its clients (#692), for the
+   * cases the refcount + idle timer miss because a socket close never arrives:
+   *   - **Inactivity backstop:** exit if no inbound traffic for `maxIdleMs` while
+   *     clients are still (nominally) connected. A phantom client sends nothing,
+   *     so it can't pin the daemon past this window.
+   *   - **Liveness sweep:** drop any client whose peer process has died (per the
+   *     client-hello pids), which re-arms the idle timer once the last real
+   *     client is gone. Catches a dead peer within one sweep instead of waiting
+   *     out the whole backstop.
+   * Both timers are unref'd — the listening server keeps the loop alive, and
+   * neither should hold it open on its own.
+   */
+  private startLivenessTimers(): void {
+    if (this.maxIdleMs > 0) {
+      const tick = Math.min(this.maxIdleMs, 60_000);
+      this.maxIdleTimer = setInterval(() => {
+        if (this.stopping || this.clients.size === 0) return; // idle timer owns the no-client case
+        if (Date.now() - this.lastActivityAt >= this.maxIdleMs) {
+          void this.stop('inactivity backstop');
+        }
+      }, tick);
+      this.maxIdleTimer.unref?.();
+    }
+    const sweepMs = resolveClientSweepMs();
+    if (sweepMs > 0) {
+      this.clientSweepTimer = setInterval(() => this.reapDeadClients(isProcessAlive), sweepMs);
+      this.clientSweepTimer.unref?.();
+    }
+  }
+
+  /**
+   * Drop every connected client whose peer process is gone. Returns the count
+   * reaped. `isAlive` is injected for testing. Clients with unknown pids (no
+   * client-hello) are skipped — they rely on the socket-close path.
+   */
+  reapDeadClients(isAlive: (pid: number) => boolean): number {
+    if (this.clients.size === 0) return 0;
+    let reaped = 0;
+    for (const session of [...this.clients]) {
+      const peers = this.clientPeers.get(session);
+      if (!peers || !peerIsDead(peers, isAlive)) continue;
+      process.stderr.write(
+        `[CodeGraph daemon] Reaping client with dead peer (pid ${peers.pid}); clients=${this.clients.size - 1}.\n`
+      );
+      try { session.stop(); } catch { /* best-effort */ }
+      this.dropClient(session);
+      reaped++;
+    }
+    return reaped;
+  }
+
+  private cleanupLockfile(): void {
+    try {
+      if (fs.existsSync(this.pidPath)) {
+        // Only remove if it still belongs to us — another daemon may have
+        // already taken over while we were shutting down (extremely rare).
+        const raw = fs.readFileSync(this.pidPath, 'utf8');
+        const info = decodeLockInfo(raw);
+        if (info && info.pid === process.pid) {
+          fs.unlinkSync(this.pidPath);
+        }
+      }
+    } catch { /* best-effort; we're exiting anyway */ }
+  }
+}
+
+/**
+ * Result of `tryAcquireDaemonLock`. Either we got the lockfile (caller becomes
+ * the daemon), or it already existed (caller should connect to the existing
+ * daemon as a proxy, or — if the holder is dead — clear it and retry).
+ */
+export type AcquireResult =
+  | { kind: 'acquired'; pidPath: string; info: DaemonLockInfo }
+  | { kind: 'taken'; existing: DaemonLockInfo | null; pidPath: string };
+
+/**
+ * Atomically create the daemon pidfile with its full record already in place.
+ * Returns either an `acquired` result (the caller is the daemon-elect and may
+ * construct a {@link Daemon}) or a `taken` result.
+ *
+ * must-fix 1 (issue #411 review): the lockfile must appear in ONE atomic step,
+ * already complete — never empty, even momentarily. The first attempt at this
+ * (`O_EXCL` create then a separate `writeSync`) left a microsecond window where
+ * the file existed but was empty; under concurrent daemon startup a third
+ * candidate could read that empty file, decode it as `null`, and `unlink` the
+ * winner's lock → two daemons (two watchers, two writers). The window was
+ * normally too small to hit, but the file watcher's extra startup time made
+ * concurrent daemons overlap enough to reproduce it reliably.
+ *
+ * The fix writes the complete record to a private temp file, then hard-links it
+ * into place: `link()` is atomic AND exclusive (EEXIST if the target exists), so
+ * the pidfile becomes visible in one step already containing a full record.
+ * Whoever links first wins; everyone else gets EEXIST and reads a complete file.
+ * There is no empty-file window at all.
+ */
+export function tryAcquireDaemonLock(projectRoot: string): AcquireResult {
+  const pidPath = getDaemonPidPath(projectRoot);
+  // Make sure the .codegraph/ directory exists — the daemon may be the first
+  // thing to touch it on a fresh-clone-but-already-initialized checkout.
+  fs.mkdirSync(path.dirname(pidPath), { recursive: true });
+
+  const info: DaemonLockInfo = {
+    pid: process.pid,
+    version: CodeGraphPackageVersion,
+    socketPath: getDaemonSocketPath(projectRoot),
+    startedAt: Date.now(),
+  };
+
+  // Temp name is pid-scoped so racing candidates never collide on it.
+  const tmp = `${pidPath}.${process.pid}.tmp`;
+  let acquired = false;
+  try {
+    fs.writeFileSync(tmp, encodeLockInfo(info), { mode: 0o600 });
+    try {
+      fs.linkSync(tmp, pidPath); // atomic + exclusive
+      acquired = true;
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err;
+    }
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* temp already gone */ }
+  }
+
+  if (acquired) return { kind: 'acquired', pidPath, info };
+
+  // Taken. Because the pidfile was link'd atomically it always holds a complete
+  // record — `existing` is null only for a genuinely corrupt leftover, never a
+  // mid-write race.
+  let existing: DaemonLockInfo | null = null;
+  try {
+    existing = decodeLockInfo(fs.readFileSync(pidPath, 'utf8'));
+  } catch { /* unreadable lockfile — treat as malformed */ }
+  return { kind: 'taken', existing, pidPath };
+}
+
+/**
+ * Remove a stale pidfile, but only if it still names a dead process. Re-reads
+ * the file immediately before unlinking so we never delete a lock that a live
+ * daemon (re)acquired in the meantime.
+ *
+ * must-fix 1 (issue #411 review): the original unconditionally `unlink`'d,
+ * which let a racing candidate delete a healthy daemon's lock. Passing
+ * `expectedDeadPid` (the pid the caller believed was dead) makes the clear a
+ * compare-and-delete: bail if the file now holds a different pid, or any live
+ * pid. Returns true when the stale lock is gone (or was already gone).
+ */
+export function clearStaleDaemonLock(pidPath: string, expectedDeadPid?: number): boolean {
+  try {
+    const raw = fs.readFileSync(pidPath, 'utf8');
+    const info = decodeLockInfo(raw);
+    if (info) {
+      // A different pid took over since we read it — not ours to clear.
+      if (expectedDeadPid !== undefined && info.pid !== expectedDeadPid) return false;
+      // Holder is actually alive — never clear a live daemon's lock.
+      if (info.pid > 0 && isProcessAlive(info.pid)) return false;
+    }
+    fs.unlinkSync(pidPath);
+    return true;
+  } catch (err: unknown) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === 'ENOENT') return true; // already gone
+    return false;
+  }
+}
+
+/**
+ * Probe whether `pid` is currently alive (signal-0). Treats EPERM as alive on
+ * every platform (the process exists, it's just not ours to signal) so we never
+ * mistake a live daemon for a dead one and clear its lock.
+ */
+export function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err: unknown) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === 'EPERM') return true; // exists, just not ours to signal
+    return false;
+  }
+}
+
+function resolveIdleTimeoutMs(): number {
+  const raw = process.env.CODEGRAPH_DAEMON_IDLE_TIMEOUT_MS;
+  if (raw === undefined || raw === '') return DEFAULT_IDLE_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_IDLE_TIMEOUT_MS;
+  return Math.floor(parsed);
+}
+
+function resolveMaxIdleMs(): number {
+  const raw = process.env.CODEGRAPH_DAEMON_MAX_IDLE_MS;
+  if (raw === undefined || raw === '') return DEFAULT_MAX_IDLE_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_MAX_IDLE_MS;
+  return Math.floor(parsed); // 0 disables the backstop
+}
+
+function resolveClientSweepMs(): number {
+  const raw = process.env.CODEGRAPH_DAEMON_CLIENT_SWEEP_MS;
+  if (raw === undefined || raw === '') return DEFAULT_CLIENT_SWEEP_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_CLIENT_SWEEP_MS;
+  return Math.floor(parsed); // 0 disables the sweep
+}
+
+/**
+ * Parse one client-hello line. Returns the peer pids if `line` is a well-formed
+ * client-hello (carries the `codegraph_client` marker), or null otherwise — in
+ * which case the caller treats the bytes as ordinary JSON-RPC.
+ */
+export function parseClientHelloLine(
+  line: string,
+): { pid: number; hostPid: number | null } | null {
+  let parsed: unknown;
+  try { parsed = JSON.parse(line); } catch { return null; }
+  if (!parsed || typeof parsed !== 'object') return null;
+  const o = parsed as Record<string, unknown>;
+  if (o.codegraph_client !== 1 || typeof o.pid !== 'number') return null;
+  return { pid: o.pid, hostPid: typeof o.hostPid === 'number' ? o.hostPid : null };
+}
+
+/**
+ * A client's peer is dead when its proxy process is gone, or when its known
+ * host process is gone. Unknown pid (no client-hello) is never "dead" on this
+ * basis — those clients rely on the socket-close path. Exported for testing.
+ */
+export function peerIsDead(
+  peers: { pid: number | null; hostPid: number | null },
+  isAlive: (pid: number) => boolean,
+): boolean {
+  if (peers.pid === null) return false;
+  if (!isAlive(peers.pid)) return true;
+  if (peers.hostPid !== null && !isAlive(peers.hostPid)) return true;
+  return false;
+}
+
+/**
+ * Read the optional client-hello line a proxy sends after the daemon hello.
+ * Always resolves (never rejects) — fail-safe by design, since every connection
+ * funnels through here. Resolves with the peer pids when the first line is a
+ * client-hello; otherwise resolves with null pids and unshifts the already-read
+ * bytes so the transport parses them as the client's first JSON-RPC message(s).
+ * Accumulates as Buffers and splits on the newline byte so a UTF-8 sequence
+ * straddling a chunk boundary in the unshifted tail is never corrupted.
+ */
+function readClientHello(
+  socket: net.Socket,
+): Promise<{ pid: number | null; hostPid: number | null }> {
+  return new Promise((resolve) => {
+    let chunks: Buffer[] = [];
+    let total = 0;
+    let settled = false;
+    const finish = (
+      peers: { pid: number | null; hostPid: number | null },
+      putBack?: Buffer,
+    ) => {
+      if (settled) return;
+      settled = true;
+      socket.removeListener('data', onData);
+      socket.removeListener('error', onEnd);
+      socket.removeListener('close', onEnd);
+      clearTimeout(timer);
+      if (putBack && putBack.length > 0 && !socket.destroyed) {
+        try { socket.unshift(putBack); } catch { /* stream already gone */ }
+      }
+      resolve(peers);
+    };
+    const onData = (chunk: Buffer | string) => {
+      const buf = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+      chunks.push(buf);
+      total += buf.length;
+      const all = chunks.length === 1 ? buf : Buffer.concat(chunks, total);
+      const nl = all.indexOf(0x0a); // '\n'
+      if (nl === -1) {
+        // No newline yet. If it's already too long to be a hello, it isn't one —
+        // hand the bytes back as data; otherwise keep accumulating.
+        if (total > MAX_HELLO_LINE_BYTES) finish({ pid: null, hostPid: null }, all);
+        else chunks = [all];
+        return;
+      }
+      const peers = parseClientHelloLine(all.subarray(0, nl).toString('utf8'));
+      if (peers) {
+        const tail = all.subarray(nl + 1);
+        finish(peers, tail.length > 0 ? tail : undefined);
+      } else {
+        // First line is not a client-hello (legacy/direct client) — hand the
+        // whole buffer back so the transport sees the message verbatim.
+        finish({ pid: null, hostPid: null }, all);
+      }
+    };
+    const onEnd = () => finish({ pid: null, hostPid: null });
+    const timer = setTimeout(() => finish({ pid: null, hostPid: null }), CLIENT_HELLO_TIMEOUT_MS);
+    timer.unref?.();
+    socket.on('data', onData);
+    socket.on('error', onEnd);
+    socket.on('close', onEnd);
+  });
+}
+
+/** Exported for test stubs that need to bound the hello-line read. */
+export { MAX_HELLO_LINE_BYTES };
diff --git a/src/mcp/engine.ts b/src/mcp/engine.ts
new file mode 100644
index 000000000..6cd71684e
--- /dev/null
+++ b/src/mcp/engine.ts
@@ -0,0 +1,279 @@
+/**
+ * MCP shared engine — the heavyweight, *shared* state for an MCP server:
+ * the project's {@link CodeGraph} instance, file watcher, and the
+ * {@link ToolHandler} cache for cross-project queries.
+ *
+ * One engine, many sessions:
+ * - direct mode (single stdio session) instantiates one engine + one session;
+ * - daemon mode instantiates one engine and a new session per socket
+ *   connection. Every session reads from the same SQLite WAL and the same
+ *   inotify watch set — that's the entire point of issue #411.
+ */
+
+import type CodeGraph from '../index';
+import { findNearestCodeGraphRoot } from '../directory';
+import { watchDisabledReason } from '../sync';
+import { ToolHandler } from './tools';
+
+// Lazy-load the heavy CodeGraph chain (sqlite + query/graph/context layers) OFF
+// the MCP startup path. It's only needed once a tool actually opens a project —
+// not to answer initialize/tools-list — so deferring it lets `serve --mcp` (and
+// the daemon it spawns) bind + register tools in ~Node-startup time instead of
+// ~800ms, closing the "No such tool available" cold-start race that made headless
+// agents flounder. require() is sync + cached on the CommonJS build.
+const loadCodeGraph = (): typeof import('../index').default =>
+  (require('../index') as typeof import('../index')).default;
+
+export interface MCPEngineOptions {
+  /**
+   * Whether to start the file watcher when initializing. Daemon and direct
+   * modes both want this true; tests may set it false to keep the engine
+   * cheap. Honors {@link watchDisabledReason} regardless.
+   */
+  watch?: boolean;
+}
+
+/**
+ * Shared MCP engine. Thread-safe in the sense that multiple sessions can
+ * call its methods concurrently — internally it serializes initialization
+ * through a single promise so multiple sessions racing each other on first
+ * connect never double-open the SQLite file.
+ */
+export class MCPEngine {
+  private cg: CodeGraph | null = null;
+  private toolHandler: ToolHandler;
+  // Project root we resolved to. Null until `ensureInitialized` succeeds
+  // (or null forever if no .codegraph/ ever turned up — that's a valid
+  // state for the engine, since cross-project queries still work).
+  private projectPath: string | null = null;
+  // Set on first `ensureInitialized` so subsequent sessions don't redo work.
+  private initPromise: Promise<void> | null = null;
+  private watcherStarted = false;
+  private opts: Required<MCPEngineOptions>;
+  private closed = false;
+
+  constructor(opts: MCPEngineOptions = {}) {
+    this.opts = { watch: opts.watch ?? true };
+    this.toolHandler = new ToolHandler(null);
+  }
+
+  /**
+   * Convenience for {@link MCPServer} compatibility: pre-seed an explicit
+   * project path (from the `--path` CLI flag) without yet opening it. This
+   * keeps the synchronous constructor cheap; the actual open happens on the
+   * first `ensureInitialized` call.
+   */
+  setProjectPathHint(projectPath: string): void {
+    this.projectPath = projectPath;
+    this.toolHandler.setDefaultProjectHint(projectPath);
+  }
+
+  /** Project root that the engine resolved on first init (null if none). */
+  getProjectPath(): string | null {
+    return this.projectPath;
+  }
+
+  /** Shared ToolHandler — sessions delegate tool dispatch through this. */
+  getToolHandler(): ToolHandler {
+    return this.toolHandler;
+  }
+
+  /** Whether the default project's CodeGraph is open. */
+  hasDefaultCodeGraph(): boolean {
+    return this.toolHandler.hasDefaultCodeGraph();
+  }
+
+  /**
+   * Walk up from `searchFrom` to find the nearest `.codegraph/` and open it.
+   * Idempotent: concurrent callers share one in-flight init; subsequent
+   * callers after success are no-ops.
+   *
+   * The original `MCPServer.tryInitializeDefault` carried the same retry-on-
+   * subsequent-tool-call semantics; we preserve them by NOT throwing when the
+   * search misses (just leaves `cg` null so the next call can retry).
+   */
+  async ensureInitialized(searchFrom: string): Promise<void> {
+    if (this.closed) return;
+    if (this.toolHandler.hasDefaultCodeGraph()) return;
+    if (this.initPromise) {
+      try { await this.initPromise; } catch { /* let caller retry */ }
+      return;
+    }
+
+    this.initPromise = this.doInitialize(searchFrom).finally(() => {
+      this.initPromise = null;
+    });
+    try {
+      await this.initPromise;
+    } catch {
+      // Init errors are logged inside `doInitialize`; falling through here
+      // matches MCPServer's previous "retry on next tool call" behavior.
+    }
+  }
+
+  /**
+   * Synchronous last-resort init used by the per-session retry loop when the
+   * background `ensureInitialized` already finished (or failed) and we need
+   * to pick up a project that appeared *after* the engine started.
+   */
+  retryInitializeSync(searchFrom: string): void {
+    if (this.closed) return;
+    if (this.toolHandler.hasDefaultCodeGraph()) return;
+    this.toolHandler.setDefaultProjectHint(searchFrom);
+    const resolvedRoot = findNearestCodeGraphRoot(searchFrom);
+    if (!resolvedRoot) return;
+    try {
+      // Close any previously failed instance to avoid leaking resources.
+      if (this.cg) {
+        try { this.cg.close(); } catch { /* ignore */ }
+        this.cg = null;
+      }
+      this.cg = loadCodeGraph().openSync(resolvedRoot);
+      this.projectPath = resolvedRoot;
+      this.toolHandler.setDefaultCodeGraph(this.cg);
+      this.startWatching();
+      this.catchUpSync();
+    } catch {
+      // Still failing — caller will try again on the next tool call.
+    }
+  }
+
+  /**
+   * Close everything. Used on graceful daemon shutdown (SIGTERM/idle timeout)
+   * and on direct-mode stop. Idempotent.
+   */
+  stop(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.toolHandler.closeAll();
+    if (this.cg) {
+      try { this.cg.close(); } catch { /* ignore */ }
+      this.cg = null;
+    }
+  }
+
+  private async doInitialize(searchFrom: string): Promise<void> {
+    this.toolHandler.setDefaultProjectHint(searchFrom);
+
+    const resolvedRoot = findNearestCodeGraphRoot(searchFrom);
+    if (!resolvedRoot) {
+      // No .codegraph/ above searchFrom. Sessions may still discover one later via roots/list
+      this.projectPath = searchFrom;
+      return;
+    }
+
+    this.projectPath = resolvedRoot;
+    try {
+      this.cg = await loadCodeGraph().open(resolvedRoot);
+      this.toolHandler.setDefaultCodeGraph(this.cg);
+      this.startWatching();
+      this.catchUpSync();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[CodeGraph MCP] Failed to open project at ${resolvedRoot}: ${msg}\n`);
+    }
+  }
+
+  /**
+   * Start file watching on the active CodeGraph instance. Idempotent — the
+   * watcher is per-engine, not per-session, which is why the daemon path
+   * collapses N inotify sets to one. The wording of the disabled-reason log
+   * exactly matches the prior in-tree implementation so log-driven dashboards
+   * keep working.
+   */
+  private startWatching(): void {
+    if (!this.cg || this.watcherStarted || !this.opts.watch) return;
+
+    const disabledReason = watchDisabledReason(this.projectPath ?? process.cwd());
+    if (disabledReason) {
+      process.stderr.write(
+        `[CodeGraph MCP] File watcher disabled — ${disabledReason}. ` +
+        `The graph will not auto-update; run \`codegraph sync\` (or install the git sync hooks via \`codegraph init\`) to refresh.\n`
+      );
+      this.watcherStarted = true;
+      return;
+    }
+
+    // Optional override for the debounce window via env var (issue #403).
+    // Useful for workspaces with bursty writes (formatter-on-save chains,
+    // large generated outputs) where the 2s default fires too often. Clamped
+    // to [100ms, 60s]; out-of-range / non-numeric values fall back to the
+    // FileWatcher default. We log the active value so it's discoverable.
+    const debounceMs = parseDebounceEnv(process.env.CODEGRAPH_WATCH_DEBOUNCE_MS);
+    if (debounceMs !== undefined) {
+      process.stderr.write(`[CodeGraph MCP] File watcher debounce: ${debounceMs}ms (CODEGRAPH_WATCH_DEBOUNCE_MS)\n`);
+    }
+
+    const started = this.cg.watch({
+      debounceMs,
+      onSyncComplete: (result) => {
+        if (result.filesChanged > 0) {
+          process.stderr.write(
+            `[CodeGraph MCP] Auto-synced ${result.filesChanged} file(s) in ${result.durationMs}ms\n`
+          );
+        }
+      },
+      onSyncError: (err) => {
+        process.stderr.write(`[CodeGraph MCP] Auto-sync error: ${err.message}\n`);
+      },
+    });
+
+    this.watcherStarted = true;
+    if (started) {
+      process.stderr.write('[CodeGraph MCP] File watcher active — graph will auto-sync on changes\n');
+    } else {
+      process.stderr.write(
+        '[CodeGraph MCP] File watcher unavailable on this platform — run `codegraph sync` to refresh the graph after changes.\n'
+      );
+    }
+  }
+
+  /**
+   * Reconcile the index with the current filesystem once, right after open —
+   * catches edits, adds, deletes, and `git pull`/`checkout` changes made while
+   * no watcher was running. Runs in the background, but the returned promise
+   * is pushed into the ToolHandler as a one-shot gate so the *first* tool
+   * call awaits completion before serving (without this, a tool call that
+   * races past sync returns rows for files that no longer exist on disk —
+   * and the per-file staleness banner can't help because `getPendingFiles()`
+   * is populated by the watcher, not by catch-up).
+   */
+  private catchUpSync(): void {
+    const cg = this.cg;
+    if (!cg) return;
+    const p = cg
+      .sync()
+      .then((result) => {
+        const changed = result.filesAdded + result.filesModified + result.filesRemoved;
+        if (changed > 0) {
+          process.stderr.write(`[CodeGraph MCP] Caught up ${changed} file(s) changed since last run\n`);
+        }
+      })
+      .catch((err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[CodeGraph MCP] Catch-up sync failed: ${msg}\n`);
+      });
+    this.toolHandler.setCatchUpGate(p);
+  }
+}
+
+/**
+ * Parse and clamp the CODEGRAPH_WATCH_DEBOUNCE_MS env override.
+ *
+ * Issue #403: workspaces with bursty writes (formatter-on-save, multi-file
+ * refactors) sometimes want a longer quiet window before sync. Returns
+ * `undefined` for unset / empty / non-numeric / out-of-range values so the
+ * FileWatcher default (2000ms) takes over — never throws.
+ *
+ * Clamp range: 100ms (faster would mean a sync per keystroke) to 60s (longer
+ * and the watcher feels broken). Out-of-range values are treated as "ignore
+ * this misconfiguration" rather than capped, since silently capping a 0 or
+ * a typoed value would mask a real config bug.
+ */
+export function parseDebounceEnv(raw: string | undefined): number | undefined {
+  if (!raw || !raw.trim()) return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isInteger(n)) return undefined;
+  if (n < 100 || n > 60000) return undefined;
+  return n;
+}
diff --git a/src/mcp/index.ts b/src/mcp/index.ts
index c790a4bc0..9007ba6e9 100644
--- a/src/mcp/index.ts
+++ b/src/mcp/index.ts
@@ -13,65 +13,191 @@
  * const server = new MCPServer('/path/to/project');
  * await server.start();
  * ```
+ *
+ * Runtime modes (decided in {@link MCPServer.start}):
+ *
+ * - **Direct** — one process serves one MCP client over stdio. The pre-#411
+ *   behavior; used when the user opts out (`CODEGRAPH_NO_DAEMON=1`), no
+ *   `.codegraph/` is reachable, or the daemon machinery fails for any reason.
+ * - **Proxy** — what an MCP host actually talks to when sharing is on: a thin
+ *   stdio↔socket pipe to the shared daemon. The proxy carries the #277 PPID
+ *   watchdog, so a SIGKILL'd host reaps its proxy promptly. See {@link ./proxy.ts}.
+ * - **Daemon** — a *detached* background process (its own session/process
+ *   group) that serves N proxies over a Unix-domain socket / named pipe,
+ *   sharing one CodeGraph + watcher + SQLite handle. Spawned on demand; never a
+ *   child of any host, so it survives individual sessions and is reaped by
+ *   client-refcount + idle timeout. See {@link ./daemon.ts} and issue #411.
+ *
+ * The detached-daemon + always-proxy split is the fix for the review finding
+ * that the original in-process daemon (a) was the first host's child, so closing
+ * that terminal severed every other client, and (b) disabled the PPID watchdog,
+ * regressing #277 (orphaned daemons on host SIGKILL).
  */
 
+import * as fs from 'fs';
 import * as path from 'path';
-import CodeGraph, { findNearestCodeGraphRoot } from '../index';
-import { watchDisabledReason } from '../sync';
-import { StdioTransport, JsonRpcRequest, JsonRpcNotification, ErrorCodes } from './transport';
-import { tools, ToolHandler } from './tools';
-import { SERVER_INSTRUCTIONS } from './server-instructions';
+import { spawn, StdioOptions } from 'child_process';
+import { findNearestCodeGraphRoot, getCodeGraphDir } from '../directory';
+import { StdioTransport } from './transport';
+import { MCPEngine } from './engine';
+import { MCPSession } from './session';
+import {
+  Daemon,
+  clearStaleDaemonLock,
+  isProcessAlive,
+  tryAcquireDaemonLock,
+} from './daemon';
+import { connectWithHello, runLocalHandshakeProxy } from './proxy';
+import { getDaemonSocketPath } from './daemon-paths';
+import { supervisionLostReason } from './ppid-watchdog';
+import { treatStdinFailureAsShutdown } from './stdin-teardown';
+import { HOST_PPID_ENV } from '../extraction/wasm-runtime-flags';
 
 /**
- * Convert a file:// URI to a filesystem path.
- * Handles URL encoding and Windows drive letter paths.
+ * How often to poll `process.ppid` to detect parent process death (see #277).
+ * 5s is a deliberate trade-off: the failure mode being guarded against is rare
+ * (parent SIGKILL'd), and longer poll = less wakeup overhead while idle.
  */
-function fileUriToPath(uri: string): string {
-  try {
-    const url = new URL(uri);
-    let filePath = decodeURIComponent(url.pathname);
-    // On Windows, file:///C:/path produces pathname /C:/path — strip leading /
-    if (process.platform === 'win32' && /^\/[a-zA-Z]:/.test(filePath)) {
-      filePath = filePath.slice(1);
-    }
-    return path.resolve(filePath);
-  } catch {
-    // Fallback for non-standard URIs
-    return uri.replace(/^file:\/\/\/?/, '');
-  }
-}
+const DEFAULT_PPID_POLL_MS = 5000;
 
 /**
- * MCP Server Info
+ * Env var that marks a process as the *detached daemon* itself (set by
+ * {@link spawnDetachedDaemon} when it re-invokes the CLI). Without it a
+ * `serve --mcp` invocation is a launcher that connects-or-spawns; with it, the
+ * process IS the daemon and must never try to spawn another (infinite spawn).
  */
-const SERVER_INFO = {
-  name: 'codegraph',
-  version: '0.1.0',
-};
+const DAEMON_INTERNAL_ENV = 'CODEGRAPH_DAEMON_INTERNAL';
 
 /**
- * MCP Protocol Version
+ * Retries for the detached daemon arbitrating the O_EXCL lock against a racing
+ * sibling. Tiny — the lock resolves on the first round in practice; the retries
+ * only cover clearing a genuinely stale (dead-pid) lockfile.
  */
-const PROTOCOL_VERSION = '2024-11-05';
+const TAKEOVER_MAX_RETRIES = 5;
+const TAKEOVER_RETRY_DELAY_MS = 100;
 
 /**
- * How long to wait for the client's `roots/list` response before giving up
- * and falling back to the process cwd.
+ * How long a launcher waits for a freshly-spawned daemon to bind its socket
+ * before giving up and running in-process. The daemon binds the socket *before*
+ * the (backgrounded) engine/grammar warm-up, so this only needs to cover node
+ * process startup. 60 × 100ms = 6s of headroom for a cold/slow box; on the
+ * common path the socket appears within a few rounds.
  */
-const ROOTS_LIST_TIMEOUT_MS = 5000;
+// Poll finely (25ms) so the proxy attaches the instant the freshly-spawned
+// daemon binds, instead of waiting up to a coarse 100ms after — shaves the
+// cold-start handshake (the window the headless agent races). Same ~6s total
+// give-up budget (240 × 25ms), just finer granularity; socket-connect probes
+// are cheap. Paired with deferring the CodeGraph load (engine.ts) off the bind
+// path, this narrows the "No such tool available" race window.
+const DAEMON_CONNECT_MAX_RETRIES = 240;
+const DAEMON_CONNECT_RETRY_DELAY_MS = 25;
 
 /**
- * Extract the first usable filesystem path from a `roots/list` result.
- * Shape per MCP spec: `{ roots: [{ uri: "file:///path", name?: string }] }`.
- * Returns null if the result is empty or malformed.
+ * Resolve the PPID watchdog poll interval from an env override. A value of
+ * `0` disables the watchdog entirely (escape hatch for embedded scenarios
+ * where the parent legitimately re-parents the server on purpose). Anything
+ * non-numeric or negative falls back to the default.
  */
-function firstRootPath(result: unknown): string | null {
-  if (!result || typeof result !== 'object') return null;
-  const roots = (result as { roots?: unknown }).roots;
-  if (!Array.isArray(roots) || roots.length === 0) return null;
-  const first = roots[0] as { uri?: unknown };
-  if (typeof first?.uri !== 'string') return null;
-  return fileUriToPath(first.uri);
+function parsePpidPollMs(raw: string | undefined): number {
+  if (raw === undefined || raw === '') return DEFAULT_PPID_POLL_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return DEFAULT_PPID_POLL_MS;
+  if (parsed < 0) return DEFAULT_PPID_POLL_MS;
+  return Math.floor(parsed);
+}
+
+/**
+ * Parse the host PID propagated across the `--liftoff-only` re-exec
+ * ({@link HOST_PPID_ENV}). Returns a positive integer PID, or null when
+ * unset/invalid — the direct-launch path, where the watchdog falls back to
+ * `process.ppid` divergence. PIDs of 0/1 are rejected (0 = unknown, 1 = init,
+ * i.e. already orphaned), so the watchdog doesn't latch onto init.
+ */
+function parseHostPpid(raw: string | undefined): number | null {
+  if (raw === undefined || raw === '') return null;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 1) return null;
+  return parsed;
+}
+
+/** Whether `CODEGRAPH_NO_DAEMON` was set to a truthy value. */
+function daemonOptOutSet(): boolean {
+  const raw = process.env.CODEGRAPH_NO_DAEMON;
+  if (!raw) return false;
+  return raw !== '0' && raw.toLowerCase() !== 'false';
+}
+
+/** Whether this process was spawned to BE the detached daemon. */
+function daemonInternalSet(): boolean {
+  const raw = process.env[DAEMON_INTERNAL_ENV];
+  return !!raw && raw !== '0' && raw.toLowerCase() !== 'false';
+}
+
+/**
+ * Resolve the project root the daemon machinery should key on. Returns
+ * `null` when no `.codegraph/` is reachable from the candidate path — in
+ * that case the caller must run in direct mode, since the daemon lockfile
+ * and socket both live under `.codegraph/`.
+ *
+ * The result is canonicalized with `realpathSync` so every client converges on
+ * the same socket/lock path regardless of how it expressed the path: a client
+ * launched with cwd under a symlink (e.g. macOS `/var` → `/private/var`, where
+ * spawned `process.cwd()` is already realpath'd) and one that passed a
+ * symlinked `rootUri` would otherwise hash to different sockets and silently
+ * fail to share the daemon.
+ */
+function resolveDaemonRoot(explicitPath: string | null): string | null {
+  const candidate = explicitPath ?? process.cwd();
+  const root = findNearestCodeGraphRoot(candidate);
+  if (!root) return null;
+  try { return fs.realpathSync(root); } catch { return root; }
+}
+
+/**
+ * Spawn the shared daemon as a fully detached background process: its own
+ * session/process group (so a SIGHUP/SIGINT to the launcher's terminal can't
+ * reach it) with stdio decoupled from the launcher (logs to
+ * `.codegraph/daemon.log`). Re-invokes the *same* CLI faithfully across dev and
+ * bundled launches by reusing `process.argv[0]` (the right node), the current
+ * `process.execArgv` (carries `--liftoff-only`, so the daemon never re-execs)
+ * and `process.argv[1]` (this script). The spawned process self-arbitrates the
+ * O_EXCL lock, so racing launchers may each spawn one — losers exit and every
+ * launcher proxies through the single winner.
+ */
+function spawnDetachedDaemon(root: string): void {
+  const scriptPath = process.argv[1];
+  if (!scriptPath) {
+    // No resolvable CLI entry point to re-invoke — let the caller fall back to
+    // direct mode rather than spawn something broken.
+    throw new Error('cannot resolve CLI script path to spawn the daemon');
+  }
+
+  let logFd: number | null = null;
+  let stdio: StdioOptions = 'ignore';
+  try {
+    logFd = fs.openSync(path.join(getCodeGraphDir(root), 'daemon.log'), 'a');
+    stdio = ['ignore', logFd, logFd];
+  } catch {
+    stdio = 'ignore'; // no log file — discard daemon output rather than fail
+  }
+  try {
+    const child = spawn(
+      process.execPath,
+      [...process.execArgv, scriptPath, 'serve', '--mcp', '--path', root],
+      {
+        detached: true,
+        stdio,
+        windowsHide: true,
+        env: { ...process.env, [DAEMON_INTERNAL_ENV]: '1' },
+      },
+    );
+    child.unref();
+  } finally {
+    // The child holds its own dup of the log fd now; the launcher doesn't need it.
+    if (logFd !== null) {
+      try { fs.closeSync(logFd); } catch { /* ignore */ }
+    }
+  }
 }
 
 /**
@@ -79,385 +205,256 @@ function firstRootPath(result: unknown): string | null {
  *
  * Implements the Model Context Protocol to expose CodeGraph
  * functionality as tools that can be called by AI assistants.
+ *
+ * Backwards-compatible constructor and `start()` signature with the
+ * pre-issue-#411 implementation: callers continue to do
+ * `new MCPServer(path).start()`. Internally we now pick from direct / proxy /
+ * daemon at start time.
  */
 export class MCPServer {
-  private transport: StdioTransport;
-  private cg: CodeGraph | null = null;
-  private toolHandler: ToolHandler;
   private projectPath: string | null;
-  // In-flight background init kicked off from handleInitialize. Tracked so the
-  // sync retry path doesn't race against it (double-opening the SQLite file).
-  private initPromise: Promise<void> | null = null;
-  // Whether the client advertised the MCP `roots` capability during initialize.
-  // If so, and no explicit project path was given, we ask it for the workspace
-  // root via roots/list rather than guessing from the (often wrong) cwd.
-  private clientSupportsRoots = false;
-  // Guards the one-shot deferred resolution (roots/list or cwd) so we don't
-  // re-issue roots/list on every tool call.
-  private rootsAttempted = false;
+  // Direct-mode-only state. In daemon mode the per-connection sessions live
+  // inside the Daemon class; in proxy mode there is no session at all.
+  private session: MCPSession | null = null;
+  private engine: MCPEngine | null = null;
+  private daemon: Daemon | null = null;
+  private ppidWatchdog: ReturnType<typeof setInterval> | null = null;
+  // PPID watchdog baseline — captured at construction so we always have a
+  // baseline, even if start() runs after a fork-style reparent.
+  private originalPpid: number = process.ppid;
+  private hostPpid: number | null = parseHostPpid(process.env[HOST_PPID_ENV]);
+  // Idempotency guard for stop().
+  private stopped = false;
+  private mode: 'unstarted' | 'direct' | 'proxy' | 'daemon' = 'unstarted';
 
   constructor(projectPath?: string) {
     this.projectPath = projectPath || null;
-    this.transport = new StdioTransport();
-    // Create ToolHandler eagerly — cross-project queries work even without a default project
-    this.toolHandler = new ToolHandler(null);
   }
 
   /**
-   * Start the MCP server
+   * Start the MCP server.
    *
-   * Note: CodeGraph initialization is deferred until the initialize request
-   * is received, which includes the rootUri from the client.
-   */
-  async start(): Promise<void> {
-    // Start listening for messages immediately - don't check initialization yet
-    // We'll get the project path from the initialize request's rootUri
-    this.transport.start(this.handleMessage.bind(this));
-
-    // Keep the process running
-    process.on('SIGINT', () => this.stop());
-    process.on('SIGTERM', () => this.stop());
-
-    // When the parent process (Claude Code) exits, stdin closes.
-    // Detect this and shut down gracefully to prevent orphaned processes.
-    process.stdin.on('end', () => this.stop());
-    process.stdin.on('close', () => this.stop());
-  }
-
-  /**
-   * Try to initialize CodeGraph for the default project.
+   * Decision order:
+   *   1. `CODEGRAPH_NO_DAEMON=1` → direct mode (unchanged pre-#411 behavior).
+   *   2. `CODEGRAPH_DAEMON_INTERNAL=1` → we ARE the detached daemon; listen.
+   *   3. No `.codegraph/` reachable → direct mode (the daemon's lockfile and
+   *      socket both live under `.codegraph/`).
+   *   4. Otherwise connect to (or spawn) the shared daemon and proxy to it.
    *
-   * Walks up parent directories to find the nearest .codegraph/ folder,
-   * similar to how git finds .git/ directories.
-   *
-   * If initialization fails, the error is recorded but the server continues
-   * to work — cross-project queries and retries on subsequent tool calls
-   * are still possible.
+   * On any unexpected failure in step 4 we transparently fall back to direct
+   * mode — a misbehaving daemon must never block a session from starting.
    */
-  private async tryInitializeDefault(projectPath: string): Promise<void> {
-    // Record where we searched so a later "not initialized" error can name it.
-    this.toolHandler.setDefaultProjectHint(projectPath);
-
-    // Walk up parent directories to find nearest .codegraph/
-    const resolvedRoot = findNearestCodeGraphRoot(projectPath);
+  async start(): Promise<void> {
+    // The detached daemon process itself. Checked before the opt-out so the
+    // daemon honors the same env it was spawned with (it never sets NO_DAEMON).
+    if (daemonInternalSet()) {
+      return this.startDaemonProcess();
+    }
 
-    if (!resolvedRoot) {
-      this.projectPath = projectPath;
-      return;
+    // Direct mode if the user opted out. Setting the env var is sufficient to
+    // get the pre-#411 single-process behavior.
+    if (daemonOptOutSet()) {
+      return this.startDirect('CODEGRAPH_NO_DAEMON set');
     }
 
-    this.projectPath = resolvedRoot;
+    const root = resolveDaemonRoot(this.projectPath);
+    if (!root) {
+      // No initialized project found — daemon mode has nowhere to put its
+      // socket. The fresh-checkout / outside-project case; behave as before.
+      return this.startDirect('no .codegraph/ root found');
+    }
 
     try {
-      this.cg = await CodeGraph.open(resolvedRoot);
-      this.toolHandler.setDefaultCodeGraph(this.cg);
-      this.startWatching();
+      // Answer the MCP handshake LOCALLY (instant tool registration — no waiting
+      // ~600ms for the daemon to spawn+bind, which produced the cold-start race)
+      // and forward tool CALLS to the shared daemon, connected in the background.
+      // Runs until the host disconnects; the proxy installs its own watchdog and
+      // falls back to an in-process engine if the daemon never comes up.
+      this.mode = 'proxy';
+      await this.runProxyWithLocalHandshake(root);
+      return;
     } catch (err) {
-      // Log the error so transient failures are diagnosable (see issue #47)
+      // Belt-and-braces: a throw during proxy SETUP (before the client was served)
+      // is still safe to recover from with a direct-mode session.
       const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`[CodeGraph MCP] Failed to open project at ${resolvedRoot}: ${msg}\n`);
+      process.stderr.write(`[CodeGraph MCP] Proxy path failed (${msg}); falling back to direct mode.\n`);
+      return this.startDirect('proxy path threw');
     }
   }
 
   /**
-   * Retry initialization of the default project if it previously failed.
-   * Called lazily on tool calls that need the default project.
-   * Re-walks parent directories each time so it picks up projects
-   * initialized after the MCP server started.
-   *
-   * Awaits any in-flight background init (kicked off by handleInitialize) so
-   * we never open the SQLite file twice concurrently.
+   * Stop the server. In daemon mode this triggers graceful shutdown of every
+   * connected session; in direct mode it mirrors the pre-#411 behavior (close
+   * cg, exit). Proxy mode never routes through here — the proxy exits itself.
    */
-  private async retryInitIfNeeded(): Promise<void> {
-    // Wait for the background init started during handleInitialize, if any.
-    if (this.initPromise) {
-      try { await this.initPromise; } catch { /* errored init falls through to retry */ }
+  stop(): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    if (this.ppidWatchdog) {
+      clearInterval(this.ppidWatchdog);
+      this.ppidWatchdog = null;
     }
-
-    // Already initialized successfully
-    if (this.toolHandler.hasDefaultCodeGraph()) return;
-
-    // No explicit path was given at initialize. Resolve it now, exactly once:
-    // ask the client via roots/list (if it advertised roots), else use cwd.
-    // Deferring to here lets a roots answer override the wrong cwd, and the
-    // one-shot guard means we never re-issue roots/list per tool call.
-    if (!this.projectPath && !this.rootsAttempted) {
-      this.rootsAttempted = true;
-      this.initPromise = (
-        this.clientSupportsRoots
-          ? this.initFromRoots()
-          : this.tryInitializeDefault(process.cwd())
-      ).finally(() => { this.initPromise = null; });
-      try { await this.initPromise; } catch { /* fall through to last-resort below */ }
-      if (this.toolHandler.hasDefaultCodeGraph()) return;
+    if (this.daemon) {
+      void this.daemon.stop('stop()');
+      // Daemon.stop calls process.exit; nothing else to do.
+      return;
     }
-
-    // Last resort: re-walk from the best candidate we have. Picks up projects
-    // initialized after the server started, and covers clients that sent no
-    // usable initialize signal at all.
-    const candidate = this.projectPath ?? process.cwd();
-    this.toolHandler.setDefaultProjectHint(candidate);
-    const resolvedRoot = findNearestCodeGraphRoot(candidate);
-    if (!resolvedRoot) return;
-
-    try {
-      // Close any previously failed instance to avoid leaking resources
-      if (this.cg) {
-        try { this.cg.close(); } catch { /* ignore */ }
-        this.cg = null;
-      }
-      this.cg = CodeGraph.openSync(resolvedRoot);
-      this.projectPath = resolvedRoot;
-      this.toolHandler.setDefaultCodeGraph(this.cg);
-      this.startWatching();
-    } catch {
-      // Still failing — will retry on next tool call
+    if (this.session) {
+      this.session.stop();
+      this.session = null;
     }
-  }
-
-  /**
-   * Resolve the project root via the MCP `roots/list` request and initialize
-   * from the first root the client reports. Falls back to the process cwd if
-   * the client returns no usable root or doesn't answer in time. See issue #196.
-   */
-  private async initFromRoots(): Promise<void> {
-    let target = process.cwd();
-    try {
-      const result = await this.transport.request('roots/list', undefined, ROOTS_LIST_TIMEOUT_MS);
-      const rootPath = firstRootPath(result);
-      if (rootPath) {
-        target = rootPath;
-      } else {
-        process.stderr.write('[CodeGraph MCP] Client returned no workspace roots; falling back to process cwd.\n');
-      }
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`[CodeGraph MCP] roots/list request failed (${msg}); falling back to process cwd.\n`);
+    if (this.engine) {
+      this.engine.stop();
+      this.engine = null;
     }
-    await this.tryInitializeDefault(target);
+    process.exit(0);
   }
 
-  /**
-   * Start file watching on the active CodeGraph instance.
-   * Logs sync activity to stderr for diagnostics.
-   */
-  private startWatching(): void {
-    if (!this.cg) return;
-
-    // When the watcher is intentionally disabled (e.g. WSL2 /mnt drives, or
-    // CODEGRAPH_NO_WATCH=1), say so explicitly and tell the user how to keep
-    // the graph fresh — otherwise the silent staleness is hard to diagnose.
-    const disabledReason = watchDisabledReason(this.projectPath ?? process.cwd());
-    if (disabledReason) {
-      process.stderr.write(
-        `[CodeGraph MCP] File watcher disabled — ${disabledReason}. ` +
-        `The graph will not auto-update; run \`codegraph sync\` (or install the git sync hooks via \`codegraph init\`) to refresh.\n`
-      );
-      return;
+  /** Single-process stdio MCP session — the pre-issue-#411 code path. */
+  private async startDirect(reason: string): Promise<void> {
+    if (reason && process.env.CODEGRAPH_MCP_DEBUG) {
+      process.stderr.write(`[CodeGraph MCP] Direct mode: ${reason}.\n`);
     }
-
-    const started = this.cg.watch({
-      onSyncComplete: (result) => {
-        if (result.filesChanged > 0) {
-          process.stderr.write(
-            `[CodeGraph MCP] Auto-synced ${result.filesChanged} file(s) in ${result.durationMs}ms\n`
-          );
-        }
-      },
-      onSyncError: (err) => {
-        process.stderr.write(`[CodeGraph MCP] Auto-sync error: ${err.message}\n`);
-      },
+    this.engine = new MCPEngine();
+    const transport = new StdioTransport();
+    this.session = new MCPSession(transport, this.engine, {
+      explicitProjectPath: this.projectPath,
     });
 
-    if (started) {
-      process.stderr.write('[CodeGraph MCP] File watcher active — graph will auto-sync on changes\n');
-    } else {
-      // start() can also return false when recursive fs.watch isn't supported.
-      process.stderr.write(
-        '[CodeGraph MCP] File watcher unavailable on this platform — run `codegraph sync` to refresh the graph after changes.\n'
-      );
+    if (this.projectPath) {
+      // Background init so the initialize response stays fast (#172).
+      void this.engine.ensureInitialized(this.projectPath);
     }
-  }
 
-  /**
-   * Stop the server
-   */
-  stop(): void {
-    // Close all cached cross-project connections first
-    this.toolHandler.closeAll();
-    // Close the main CodeGraph instance
-    if (this.cg) {
-      this.cg.close();
-      this.cg = null;
-    }
-    this.transport.stop();
-    process.exit(0);
-  }
+    this.session.start();
 
-  /**
-   * Handle incoming JSON-RPC messages
-   */
-  private async handleMessage(message: JsonRpcRequest | JsonRpcNotification): Promise<void> {
-    // Check if it's a request (has id) or notification (no id)
-    const isRequest = 'id' in message;
-
-    switch (message.method) {
-      case 'initialize':
-        if (isRequest) {
-          await this.handleInitialize(message as JsonRpcRequest);
-        }
-        break;
-
-      case 'initialized':
-        // Notification that client has finished initialization
-        // No action needed - the client is ready
-        break;
-
-      case 'tools/list':
-        if (isRequest) {
-          await this.handleToolsList(message as JsonRpcRequest);
-        }
-        break;
-
-      case 'tools/call':
-        if (isRequest) {
-          await this.handleToolsCall(message as JsonRpcRequest);
-        }
-        break;
-
-      case 'ping':
-        if (isRequest) {
-          this.transport.sendResult((message as JsonRpcRequest).id, {});
-        }
-        break;
-
-      default:
-        if (isRequest) {
-          this.transport.sendError(
-            (message as JsonRpcRequest).id,
-            ErrorCodes.MethodNotFound,
-            `Method not found: ${message.method}`
-          );
-        }
-    }
+    // Detect parent-process death — same logic as pre-refactor. When stdin
+    // closes we go through StdioTransport's `process.exit(0)` already, but
+    // SIGKILL of the parent doesn't reliably close stdin on Linux (#277).
+    // Also treat a stdin `'error'` (a socket-backed stdin can fail with
+    // ECONNRESET/hangup instead of a clean close) as shutdown, and destroy the
+    // stream so a hung fd can't busy-spin the event loop (#799).
+    treatStdinFailureAsShutdown(() => this.stop());
+
+    this.mode = 'direct';
+    this.installSignalHandlers();
+    this.installPpidWatchdog();
   }
 
   /**
-   * Handle initialize request
+   * Run as the detached shared daemon (process spawned with
+   * `CODEGRAPH_DAEMON_INTERNAL=1`). Arbitrate the O_EXCL lock, then either
+   * become the daemon (bind the socket, serve forever) or — if a live daemon
+   * already holds the lock — exit so we don't leak a redundant process.
+   *
+   * No PPID watchdog and no stdin handlers: the daemon is detached on purpose
+   * and reaps itself via client-refcount + idle timeout (see {@link Daemon}).
    */
-  private async handleInitialize(request: JsonRpcRequest): Promise<void> {
-    const params = request.params as {
-      rootUri?: string;
-      workspaceFolders?: Array<{ uri: string; name: string }>;
-      capabilities?: { roots?: unknown };
-    } | undefined;
-
-    // Does the client support the MCP `roots` protocol? If so, and we have no
-    // explicit path, we ask it for the workspace root after the handshake
-    // instead of falling back to the (frequently wrong) cwd. See issue #196.
-    this.clientSupportsRoots = !!params?.capabilities?.roots;
-
-    // Explicit project signal, strongest first: a client-provided rootUri /
-    // workspaceFolders (LSP-style, non-standard but some clients send it), else
-    // the --path the server was launched with. cwd is NOT used here — we defer
-    // it so a roots/list answer can win over it.
-    let explicitPath: string | null = null;
-    if (params?.rootUri) {
-      explicitPath = fileUriToPath(params.rootUri);
-    } else if (params?.workspaceFolders?.[0]?.uri) {
-      explicitPath = fileUriToPath(params.workspaceFolders[0].uri);
-    } else if (this.projectPath) {
-      explicitPath = this.projectPath;
-    }
+  private async startDaemonProcess(): Promise<void> {
+    const root = resolveDaemonRoot(this.projectPath) ?? this.projectPath ?? process.cwd();
+    for (let attempt = 0; attempt < TAKEOVER_MAX_RETRIES; attempt++) {
+      const lock = tryAcquireDaemonLock(root);
+
+      if (lock.kind === 'acquired') {
+        const daemon = new Daemon(root);
+        await daemon.start();
+        this.daemon = daemon;
+        this.mode = 'daemon';
+        return; // the net.Server keeps the process alive
+      }
 
-    // Respond to the handshake BEFORE doing any heavy initialization. Loading
-    // the SQLite DB and the tree-sitter WASM runtime can take many seconds on
-    // slow filesystems (Docker Desktop VirtioFS on macOS, WSL2). Clients like
-    // Claude Code time out the handshake at ~30s, which manifested as
-    // "MCP tools never appear" — the child was alive and had received the
-    // initialize but was still awaiting initGrammars(). See issue #172.
-    //
-    // We accept the client's protocol version but respond with our supported
-    // version. The `instructions` field is surfaced by MCP clients in the
-    // agent's system prompt automatically — it's the right place for the
-    // universal tool-selection playbook, ahead of individual tool descriptions.
-    this.transport.sendResult(request.id, {
-      protocolVersion: PROTOCOL_VERSION,
-      capabilities: {
-        tools: {},
-      },
-      serverInfo: SERVER_INFO,
-      instructions: SERVER_INSTRUCTIONS,
-    });
+      // Taken. If the holder is alive, another daemon already serves (or is
+      // binding) — we're redundant; exit cleanly so the launcher proxies to it.
+      const existing = lock.existing;
+      if (existing && existing.pid > 0 && isProcessAlive(existing.pid)) {
+        process.stderr.write(
+          `[CodeGraph daemon] Another daemon (pid ${existing.pid}) already holds the lock; exiting.\n`
+        );
+        process.exit(0);
+      }
 
-    // If we know the project dir, kick off init in the background now. Tool
-    // calls that arrive before it finishes fall through to `retryInitIfNeeded`,
-    // which waits for this promise rather than racing it with a second open.
-    //
-    // If we DON'T know it (no rootUri, no --path), defer: the first tool call
-    // resolves it via roots/list (when the client supports roots) or cwd. This
-    // is the fix for issue #196 — clients that launch the server outside the
-    // project and don't pass a rootUri previously got a misleading "not
-    // initialized" error on every call.
-    if (explicitPath) {
-      this.initPromise = this.tryInitializeDefault(explicitPath).finally(() => {
-        this.initPromise = null;
-      });
+      // Holder is dead (or the record is unreadable) — clear it (pid-verified,
+      // so we never delete a live daemon's lock) and retry the acquire.
+      clearStaleDaemonLock(lock.pidPath, existing?.pid);
+      await sleep(TAKEOVER_RETRY_DELAY_MS);
     }
-  }
 
-  /**
-   * Handle tools/list request
-   */
-  private async handleToolsList(request: JsonRpcRequest): Promise<void> {
-    await this.retryInitIfNeeded();
-    this.transport.sendResult(request.id, {
-      tools: this.toolHandler.getTools(),
-    });
+    process.stderr.write('[CodeGraph daemon] Could not acquire the daemon lock; exiting.\n');
+    process.exit(0);
   }
 
   /**
-   * Handle tools/call request
+   * Proxy mode (the common case). Serve the MCP handshake LOCALLY for instant
+   * tool registration, forwarding tool calls to the shared daemon — which is
+   * connected in the background (probed, then spawned + polled if absent) so the
+   * handshake never waits ~600ms on it. Runs until the host disconnects; the
+   * proxy falls back to an in-process engine if the daemon never binds, so this
+   * never wedges a session.
    */
-  private async handleToolsCall(request: JsonRpcRequest): Promise<void> {
-    const params = request.params as {
-      name: string;
-      arguments?: Record<string, unknown>;
+  private async runProxyWithLocalHandshake(root: string): Promise<void> {
+    const socketPath = getDaemonSocketPath(root);
+    const getDaemonSocket = async () => {
+      // Fast path: a daemon may already be listening.
+      const probe = await connectWithHello(socketPath);
+      if (probe === 'version-mismatch') return null; // definitive — serve in-process, don't poll for 6s
+      if (probe) return probe;
+      // None reachable — spawn one (detached) and poll for its bind.
+      spawnDetachedDaemon(root);
+      for (let attempt = 0; attempt < DAEMON_CONNECT_MAX_RETRIES; attempt++) {
+        await sleep(DAEMON_CONNECT_RETRY_DELAY_MS);
+        const s = await connectWithHello(socketPath);
+        if (s === 'version-mismatch') return null;
+        if (s) return s;
+      }
+      return null; // never bound — the proxy serves this session in-process
     };
+    await runLocalHandshakeProxy({ getDaemonSocket, makeEngine: () => new MCPEngine(), root });
+  }
 
-    if (!params || !params.name) {
-      this.transport.sendError(
-        request.id,
-        ErrorCodes.InvalidParams,
-        'Missing tool name'
-      );
-      return;
-    }
-
-    const toolName = params.name;
-    const toolArgs = params.arguments || {};
-
-    // Validate tool exists
-    const tool = tools.find(t => t.name === toolName);
-    if (!tool) {
-      this.transport.sendError(
-        request.id,
-        ErrorCodes.InvalidParams,
-        `Unknown tool: ${toolName}`
-      );
-      return;
-    }
-
-    // If the default project isn't initialized yet, retry in case it was
-    // initialized after the MCP server started (e.g. user ran codegraph init)
-    await this.retryInitIfNeeded();
-
-    const result = await this.toolHandler.execute(toolName, toolArgs);
+  /** Standard SIGINT/SIGTERM handlers that route to our `stop()` (direct mode). */
+  private installSignalHandlers(): void {
+    process.on('SIGINT', () => this.stop());
+    process.on('SIGTERM', () => this.stop());
+  }
 
-    this.transport.sendResult(request.id, result);
+  /**
+   * PPID watchdog (#277) — direct mode only. Daemon mode is detached on purpose
+   * and reaps via idle timeout; proxy mode installs its own watchdog inside
+   * {@link runProxy}. So this only ever runs for an in-process direct session.
+   */
+  private installPpidWatchdog(): void {
+    if (this.mode !== 'direct') return;
+    const pollMs = parsePpidPollMs(process.env.CODEGRAPH_PPID_POLL_MS);
+    if (pollMs <= 0) return;
+    this.ppidWatchdog = setInterval(() => {
+      const reason = supervisionLostReason({
+        originalPpid: this.originalPpid,
+        currentPpid: process.ppid,
+        hostPpid: this.hostPpid,
+        isAlive: isProcessAlive,
+      });
+      if (reason) {
+        process.stderr.write(
+          `[CodeGraph MCP] Parent process exited (${reason}); shutting down.\n`
+        );
+        this.stop();
+      }
+    }, pollMs);
+    this.ppidWatchdog.unref();
   }
 }
 
+function sleep(ms: number): Promise<void> {
+  // Deliberately NOT unref'd. During the daemon connect/takeover retry loop we
+  // may be between processes — no socket bound yet, no transport, no listener
+  // pinning the event loop. An unref'd timer would let Node drain the loop and
+  // exit silently before we get a chance to try again.
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
 // Export for use in CLI
 export { StdioTransport } from './transport';
 export { tools, ToolHandler } from './tools';
+// Surface a few daemon-mode bits for tests + diagnostics.
+export { Daemon } from './daemon';
+export { CodeGraphPackageVersion } from './version';
diff --git a/src/mcp/ppid-watchdog.ts b/src/mcp/ppid-watchdog.ts
new file mode 100644
index 000000000..eaf4d250b
--- /dev/null
+++ b/src/mcp/ppid-watchdog.ts
@@ -0,0 +1,63 @@
+/**
+ * Shared decision logic for the PPID watchdog (#277, #692).
+ *
+ * The watchdog's job: notice that the process we depend on — our parent, or the
+ * MCP host reached past an intermediate launcher — has died, so an orphaned
+ * proxy / direct server shuts itself down instead of leaking forever.
+ *
+ * Parent death surfaces differently per OS, and getting this wrong is what
+ * caused the unbounded daemon/proxy leak on Windows (#692, #576):
+ *
+ *   - **POSIX** reparents an orphan to init (pid 1), so `process.ppid` *changes*
+ *     the instant the parent dies. That divergence is the classic #277 signal.
+ *   - **Windows** never reparents: `process.ppid` keeps reporting the original
+ *     (now-dead) parent forever, so the change-check can never fire. There we
+ *     must poll the original parent's *liveness* instead.
+ *
+ * The liveness fallback is deliberately gated to Windows. On POSIX a
+ * double-forked grandparent can legitimately outlive the reparent, so a dead
+ * `originalPpid` is not proof of orphaning there — the change-check is the
+ * correct and sufficient POSIX signal, and using liveness too would risk a
+ * false-positive shutdown.
+ */
+export interface SupervisionState {
+  /** `process.ppid` captured at startup. */
+  originalPpid: number;
+  /** `process.ppid` right now. */
+  currentPpid: number;
+  /**
+   * The MCP host pid threaded past an intermediate launcher
+   * (`CODEGRAPH_HOST_PPID`), or null when unknown — e.g. the standalone bundle,
+   * which pre-bakes `--liftoff-only` and so never runs the relaunch that sets it.
+   */
+  hostPpid: number | null;
+  /** Liveness probe — `process.kill(pid, 0)` in production, stubbed in tests. */
+  isAlive: (pid: number) => boolean;
+  /** Defaults to `process.platform`. */
+  platform?: NodeJS.Platform;
+}
+
+/**
+ * Returns a human-readable reason string when the process has lost its
+ * supervisor and should shut down, or null while it is still supervised.
+ */
+export function supervisionLostReason(state: SupervisionState): string | null {
+  const { originalPpid, currentPpid, hostPpid, isAlive } = state;
+  const platform = state.platform ?? process.platform;
+
+  // POSIX: the parent dying reparents us, so ppid diverges. (Never on Windows.)
+  if (currentPpid !== originalPpid) {
+    return `ppid ${originalPpid} -> ${currentPpid}`;
+  }
+  // Windows: ppid is stable across parent death, so detect it by liveness.
+  // Skip pid 0/1 — "unknown" and init are never a real Windows parent, and a
+  // bogus liveness probe there must not trigger a shutdown.
+  if (platform === 'win32' && originalPpid > 1 && !isAlive(originalPpid)) {
+    return `parent pid ${originalPpid} exited`;
+  }
+  // Either platform: the host pid threaded past a launcher shim is gone.
+  if (hostPpid !== null && !isAlive(hostPpid)) {
+    return `host pid ${hostPpid} exited`;
+  }
+  return null;
+}
diff --git a/src/mcp/proxy.ts b/src/mcp/proxy.ts
new file mode 100644
index 000000000..2efe25a48
--- /dev/null
+++ b/src/mcp/proxy.ts
@@ -0,0 +1,543 @@
+/**
+ * MCP proxy mode — issue #411.
+ *
+ * The proxy is a near-transparent stdio↔socket pipe. Once it has verified
+ * the daemon's hello line (same major.minor.patch as ours), it does no
+ * protocol parsing of its own: every byte the MCP host writes to the proxy's
+ * stdin goes straight to the daemon socket, and every byte the daemon emits
+ * goes straight to the host's stdout. Server-initiated JSON-RPC requests
+ * (e.g. `roots/list`) flow through the same pipe transparently.
+ *
+ * Lifecycle expectations:
+ *   - The proxy exits when *either* stream closes (host stdin closed →
+ *     daemon socket end, or daemon-side socket close → host stdout end).
+ *   - Closing the socket on the proxy side is what tells the daemon to
+ *     decrement its connected-clients refcount.
+ *   - On a parent-process death we can't detect via stdin close (e.g. SIGKILL
+ *     of the MCP host), the proxy's PPID watchdog catches it — same logic
+ *     the direct-mode server uses; see issue #277.
+ */
+
+import * as fs from 'fs';
+import * as net from 'net';
+import { HOST_PPID_ENV } from '../extraction/wasm-runtime-flags';
+import { DaemonClientHello, DaemonHello, MAX_HELLO_LINE_BYTES } from './daemon';
+import { supervisionLostReason } from './ppid-watchdog';
+import { treatStdinFailureAsShutdown } from './stdin-teardown';
+import { CodeGraphPackageVersion } from './version';
+import { SERVER_INFO, PROTOCOL_VERSION } from './session';
+import { SERVER_INSTRUCTIONS } from './server-instructions';
+import { getStaticTools } from './tools';
+import type { MCPEngine } from './engine';
+
+/** Default poll cadence for the PPID watchdog (same as the direct server). */
+const DEFAULT_PPID_POLL_MS = 5000;
+
+/**
+ * Env var that opts INTO the "attached to shared daemon" log line. Off by
+ * default: the line is benign INFO, but MCP hosts render any server stderr at
+ * error level (and append an `undefined` data field), so on every session start
+ * a healthy attach showed up as `[error] … undefined`. Set to `1` to surface it
+ * when debugging daemon attach. (#618; approach from #640 by @mturac)
+ */
+const LOG_ATTACH_ENV = 'CODEGRAPH_MCP_LOG_ATTACH';
+
+/**
+ * Log a successful daemon attach — gated behind {@link LOG_ATTACH_ENV} so it is
+ * silent by default (see #618). Exported for tests.
+ */
+export function logAttachedDaemon(socketPath: string, hello: DaemonHello): void {
+  if (process.env[LOG_ATTACH_ENV] !== '1') return;
+  process.stderr.write(
+    `[CodeGraph MCP] Attached to shared daemon on ${socketPath} (pid ${hello.pid}, v${hello.codegraph}).\n`
+  );
+}
+
+export interface ProxyResult {
+  /**
+   * `proxied` — successfully attached to a same-version daemon and piped
+   * stdio. The proxy stays alive until either end closes.
+   * `fallback-needed` — the daemon rejected us (version mismatch / unreachable
+   * socket) and the caller should run the server in direct mode.
+   */
+  outcome: 'proxied' | 'fallback-needed';
+  reason?: string;
+}
+
+/**
+ * Attempt to connect to the daemon at `socketPath` and pipe stdio through it.
+ *
+ * Returns a promise that resolves when either:
+ *   - the connection succeeded and one of stdin/socket has now closed
+ *     (after which the process should exit), or
+ *   - the connection failed early enough that the caller can still fall
+ *     back to direct mode.
+ *
+ * The `expectedVersion` param defaults to the package's own version — daemon
+ * and proxy MUST match exactly. Mismatch resolves with
+ * `outcome: 'fallback-needed'` so the caller can transparently start its own
+ * server. (We accept the cost of two concurrent servers in this case as the
+ * price of never silently running a stale daemon against newer client code.)
+ */
+export async function runProxy(
+  socketPath: string,
+  expectedVersion: string = CodeGraphPackageVersion,
+): Promise<ProxyResult> {
+  // POSIX: refuse to connect to a stale socket file that points at no
+  // listening process. `fs.existsSync` is a cheap pre-check; a real
+  // ECONNREFUSED below catches the rare "exists but unbound" race.
+  if (process.platform !== 'win32' && !fs.existsSync(socketPath)) {
+    return { outcome: 'fallback-needed', reason: 'socket file missing' };
+  }
+
+  const socket = net.createConnection(socketPath);
+  socket.setEncoding('utf8');
+
+  const hello = await readHelloLine(socket).catch((err) => {
+    socket.destroy();
+    return new Error(String(err));
+  });
+  if (hello instanceof Error) {
+    return { outcome: 'fallback-needed', reason: hello.message };
+  }
+
+  if (hello.codegraph !== expectedVersion) {
+    process.stderr.write(
+      `[CodeGraph MCP] Found a daemon on ${socketPath} but version (${hello.codegraph}) ` +
+      `differs from ours (${expectedVersion}); falling back to direct mode.\n`
+    );
+    socket.destroy();
+    return { outcome: 'fallback-needed', reason: 'version mismatch' };
+  }
+
+  logAttachedDaemon(socketPath, hello);
+
+  sendClientHello(socket);
+  startPpidWatchdog(socket);
+  await pipeUntilClose(socket);
+  // Host disconnected (or the daemon went away). The proxy's only job is the
+  // pipe; exit now so we don't linger — process.stdin's 'data' listener would
+  // otherwise keep the event loop alive and leave a zombie launcher behind.
+  process.exit(0);
+}
+
+/**
+ * Connect to a daemon at `socketPath` and verify its hello (exact version match).
+ * Returns the live socket (hello already consumed) or null if unreachable / stale
+ * / version-mismatched. Unlike {@link runProxy} it does NOT pipe — the caller
+ * owns the socket. Used by the local-handshake proxy's background connect.
+ */
+export async function connectWithHello(
+  socketPath: string,
+  expectedVersion: string = CodeGraphPackageVersion,
+): Promise<net.Socket | 'version-mismatch' | null> {
+  if (process.platform !== 'win32' && !fs.existsSync(socketPath)) return null;
+  const socket = net.createConnection(socketPath);
+  socket.setEncoding('utf8');
+  const hello = await readHelloLine(socket).catch(() => null);
+  if (!hello) {
+    socket.destroy();
+    return null; // no daemon yet — caller should keep polling
+  }
+  if (hello.codegraph !== expectedVersion) {
+    // A daemon IS up but it's the wrong version — definitive, not a "not yet".
+    // Don't poll; the caller serves in-process so we never run stale-vs-new.
+    process.stderr.write(
+      `[CodeGraph MCP] Found a daemon on ${socketPath} but version (${hello.codegraph}) ` +
+      `differs from ours (${expectedVersion}); serving this session in-process.\n`
+    );
+    socket.destroy();
+    return 'version-mismatch';
+  }
+  logAttachedDaemon(socketPath, hello);
+  sendClientHello(socket);
+  return socket;
+}
+
+/**
+ * Tell the daemon our pids right after we verify its hello, so its liveness
+ * sweep can reap this client if our process dies without the socket ever
+ * signalling close (the Windows named-pipe hazard behind #692). Best-effort:
+ * sent before any piped bytes so it's always the daemon's first line from us,
+ * and a write failure here is harmless (the daemon just falls back to the
+ * socket-close lifecycle). `hostPid` mirrors the PPID watchdog: the threaded
+ * host pid if set, else our own parent (the host, on a no-relaunch bundle).
+ */
+function sendClientHello(socket: net.Socket): void {
+  const clientHello: DaemonClientHello = {
+    codegraph_client: 1,
+    pid: process.pid,
+    hostPid: parseHostPpid(process.env[HOST_PPID_ENV]) ?? process.ppid,
+  };
+  try { socket.write(JSON.stringify(clientHello) + '\n'); } catch { /* best-effort */ }
+}
+
+type JsonRpc = Record<string, unknown>;
+
+/** Dependencies the local-handshake proxy needs, injected by MCPServer (which
+ *  owns the daemon-spawn machinery and the engine factory). */
+export interface LocalHandshakeDeps {
+  /** Probe → spawn → retry → hello-verify; resolves a connected daemon socket,
+   *  or null when the daemon path is genuinely unavailable (→ in-process fallback). */
+  getDaemonSocket(): Promise<net.Socket | null>;
+  /** Lazily create an in-process engine — used ONLY if the daemon never comes up,
+   *  preserving the "a broken daemon never wedges a session" guarantee. */
+  makeEngine(): MCPEngine;
+  /** Project root for the fallback engine's lazy init. */
+  root: string;
+}
+
+/**
+ * Local-handshake proxy (the cold-start fix).
+ *
+ * Answers `initialize` + `tools/list` from STATIC constants the instant the
+ * client asks — tools register in ~process-startup time instead of waiting
+ * ~600ms for the daemon to spawn+bind, which is what produced the "No such tool
+ * available" race that made headless agents flail into grep/Read. Tool CALLS are
+ * forwarded to the shared daemon (connected in the background); the daemon's
+ * response to the forwarded `initialize` is suppressed (the client already got
+ * the local one). If the daemon never comes up (version mismatch / spawn fail),
+ * a lazily-created in-process engine serves the calls — so the handshake speedup
+ * never costs the old fall-back-to-direct robustness.
+ */
+export async function runLocalHandshakeProxy(deps: LocalHandshakeDeps): Promise<void> {
+  let daemonStatus: 'connecting' | 'ready' | 'failed' = 'connecting';
+  let daemonSocket: net.Socket | null = null;
+  let clientInitId: unknown = undefined;   // suppress the daemon's reply to the forwarded initialize
+  const pending: string[] = [];            // client lines buffered until the daemon resolves
+  let engine: MCPEngine | null = null;
+  let engineReady: Promise<void> | null = null;
+  let shuttingDown = false;
+  // Requests forwarded to the daemon and not yet answered, keyed by JSON-RPC id.
+  // If the daemon dies mid-session (#662 — e.g. an MCP host SIGTERM's it when a
+  // new session starts), these would otherwise hang forever; we re-serve them
+  // in-process so the host always gets a reply.
+  const inflight = new Map<unknown, string>();
+  const trackInflight = (line: string): void => {
+    try {
+      const m = JSON.parse(line) as JsonRpc;
+      if (m && m.id !== undefined && typeof m.method === 'string' && m.method !== 'initialize') {
+        inflight.set(m.id, line);
+      }
+    } catch { /* unparseable — nothing we could re-serve anyway */ }
+  };
+
+  const writeClient = (obj: JsonRpc | string): void => {
+    try { process.stdout.write((typeof obj === 'string' ? obj : JSON.stringify(obj)) + '\n'); } catch { /* host gone */ }
+  };
+  const shutdown = (): void => {
+    if (shuttingDown) return; shuttingDown = true;
+    try { daemonSocket?.destroy(); } catch { /* ignore */ }
+    try { engine?.stop(); } catch { /* ignore */ }
+    process.exit(0);
+  };
+  const ensureEngine = (): Promise<void> => {
+    if (!engine) engine = deps.makeEngine();
+    if (!engineReady) engineReady = engine.ensureInitialized(deps.root).catch(() => { /* degraded */ });
+    return engineReady;
+  };
+  // Daemon-unavailable fallback: serve a client message in-process.
+  const handleLocally = async (line: string): Promise<void> => {
+    let msg: JsonRpc; try { msg = JSON.parse(line) as JsonRpc; } catch { return; }
+    const id = msg.id;
+    if (msg.method === 'tools/call' && id !== undefined) {
+      try {
+        await ensureEngine();
+        const params = (msg.params || {}) as { name: string; arguments?: Record<string, unknown> };
+        const result = await engine!.getToolHandler().execute(params.name, params.arguments || {});
+        writeClient({ jsonrpc: '2.0', id, result });
+      } catch (err) {
+        writeClient({ jsonrpc: '2.0', id, error: { code: -32603, message: err instanceof Error ? err.message : String(err) } });
+      }
+    } else if (msg.method === 'ping' && id !== undefined) {
+      writeClient({ jsonrpc: '2.0', id, result: {} });
+    } else if (id !== undefined && msg.method !== 'initialize') {
+      // A request we can't serve in-process (and the daemon is gone) — answer
+      // with an error rather than let the host hang on a reply that won't come.
+      writeClient({ jsonrpc: '2.0', id, error: { code: -32603, message: 'CodeGraph daemon unavailable' } });
+    }
+    // initialize already answered locally; notifications (initialized) need no reply.
+  };
+  const routeToDaemon = (line: string): void => {
+    if (daemonStatus === 'ready' && daemonSocket) {
+      trackInflight(line);
+      try { daemonSocket.write(line.endsWith('\n') ? line : line + '\n'); } catch { /* close path */ }
+    } else if (daemonStatus === 'failed') {
+      void handleLocally(line);
+    } else {
+      pending.push(line);
+    }
+  };
+
+  // ---- client (stdin) ----
+  let stdinBuf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk: string) => {
+    stdinBuf += chunk;
+    let idx: number;
+    while ((idx = stdinBuf.indexOf('\n')) !== -1) {
+      const line = stdinBuf.slice(0, idx).trim();
+      stdinBuf = stdinBuf.slice(idx + 1);
+      if (!line) continue;
+      let msg: JsonRpc; try { msg = JSON.parse(line) as JsonRpc; } catch { routeToDaemon(line); continue; }
+      if (msg.method === 'initialize') {
+        clientInitId = msg.id;
+        writeClient({ jsonrpc: '2.0', id: msg.id, result: { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER_INFO, instructions: SERVER_INSTRUCTIONS } });
+        routeToDaemon(line); // prime the daemon so it resolves the project (its reply is suppressed below)
+      } else if (msg.method === 'tools/list') {
+        writeClient({ jsonrpc: '2.0', id: msg.id, result: { tools: getStaticTools() } });
+      } else if (msg.method === 'resources/list') {
+        // No resources exposed — answer the probe locally so it never reaches
+        // the daemon as an unhandled method and logs `-32601`. (#621)
+        writeClient({ jsonrpc: '2.0', id: msg.id, result: { resources: [] } });
+      } else if (msg.method === 'resources/templates/list') {
+        writeClient({ jsonrpc: '2.0', id: msg.id, result: { resourceTemplates: [] } });
+      } else if (msg.method === 'prompts/list') {
+        writeClient({ jsonrpc: '2.0', id: msg.id, result: { prompts: [] } });
+      } else {
+        routeToDaemon(line);
+      }
+    }
+  });
+  // Shut down when stdin ends/closes — and also on a stdin `'error'`, which a
+  // socket-backed stdin (the VS Code stdio shape) can emit on client death
+  // instead of a clean close; destroying the stream stops a hung fd from
+  // busy-spinning the event loop (#799).
+  treatStdinFailureAsShutdown(shutdown);
+  startPpidWatchdogNoSocket(shutdown);
+
+  // ---- daemon connection (background) ----
+  let socket: net.Socket | null = null;
+  try { socket = await deps.getDaemonSocket(); } catch { socket = null; }
+
+  if (socket && !shuttingDown) {
+    daemonSocket = socket;
+    daemonStatus = 'ready';
+    let sockBuf = '';
+    socket.setEncoding('utf8');
+    socket.on('data', (chunk: string) => {
+      sockBuf += chunk;
+      let idx: number;
+      while ((idx = sockBuf.indexOf('\n')) !== -1) {
+        const line = sockBuf.slice(0, idx);
+        sockBuf = sockBuf.slice(idx + 1);
+        if (!line.trim()) continue;
+        let resp: JsonRpc | null = null;
+        try { resp = JSON.parse(line) as JsonRpc; } catch { /* not JSON — relay verbatim */ }
+        if (resp && resp.id !== undefined && ('result' in resp || 'error' in resp)) {
+          inflight.delete(resp.id); // answered — no longer in flight
+          // Suppress the daemon's reply to the initialize we forwarded to prime it
+          // (the client already got the local handshake response).
+          if (clientInitId !== undefined && resp.id === clientInitId) continue;
+        }
+        writeClient(line);
+      }
+    });
+    // The daemon going away does NOT end the session (#662). An MCP host can
+    // SIGTERM the shared daemon when another session starts; if we exited here,
+    // this host would silently lose CodeGraph and any in-flight request would
+    // hang. Instead, fall back to the in-process engine for the rest of the
+    // session and re-serve whatever the dead daemon never answered.
+    const onDaemonLost = (): void => {
+      if (shuttingDown || daemonStatus !== 'ready') return; // host teardown, or already handled
+      daemonStatus = 'failed';
+      try { daemonSocket?.destroy(); } catch { /* ignore */ }
+      daemonSocket = null;
+      process.stderr.write(
+        `[CodeGraph MCP] Shared daemon connection lost; serving this session in-process (degraded), re-serving ${inflight.size} in-flight request(s).\n`
+      );
+      const orphaned = [...inflight.values()];
+      inflight.clear();
+      for (const line of orphaned) void handleLocally(line);
+    };
+    socket.on('close', onDaemonLost);
+    socket.on('error', onDaemonLost);
+    for (const line of pending) { trackInflight(line); try { socket.write(line + '\n'); } catch { /* ignore */ } }
+    pending.length = 0;
+  } else if (!shuttingDown) {
+    daemonStatus = 'failed';
+    process.stderr.write('[CodeGraph MCP] Shared daemon unavailable; serving this session in-process (degraded).\n');
+    const buffered = pending.splice(0);
+    for (const line of buffered) await handleLocally(line);
+  }
+
+  await new Promise<void>(() => { /* stdin keeps the loop alive; exit via shutdown() */ });
+}
+
+/** PPID watchdog for the local-handshake proxy — same #277 logic as
+ *  {@link startPpidWatchdog} but with no socket to close (the caller's shutdown
+ *  handles teardown). */
+function startPpidWatchdogNoSocket(onDeath: () => void): void {
+  const pollMs = parsePollMs(process.env.CODEGRAPH_PPID_POLL_MS);
+  if (pollMs <= 0) return;
+  const originalPpid = process.ppid;
+  const hostPpid = parseHostPpid(process.env[HOST_PPID_ENV]);
+  const timer = setInterval(() => {
+    const reason = supervisionLostReason({
+      originalPpid,
+      currentPpid: process.ppid,
+      hostPpid,
+      isAlive: isProcessAliveLocal,
+    });
+    if (reason) {
+      process.stderr.write(`[CodeGraph MCP] Parent process exited (${reason}); shutting down.\n`);
+      onDeath();
+    }
+  }, pollMs);
+  timer.unref?.();
+}
+
+/**
+ * Read one CRLF/LF-terminated JSON line from the socket, parse it as the
+ * daemon hello, and return it. Bounded to {@link MAX_HELLO_LINE_BYTES} so a
+ * malicious or broken peer can't OOM us. Times out at 3s — a healthy daemon
+ * sends hello immediately on accept.
+ */
+function readHelloLine(socket: net.Socket): Promise<DaemonHello> {
+  return new Promise((resolve, reject) => {
+    let buffer = '';
+    const cleanup = () => {
+      socket.removeListener('data', onData);
+      socket.removeListener('error', onError);
+      socket.removeListener('close', onClose);
+      clearTimeout(timer);
+    };
+    const onData = (chunk: string | Buffer) => {
+      buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+      const idx = buffer.indexOf('\n');
+      if (idx === -1) {
+        if (buffer.length > MAX_HELLO_LINE_BYTES) {
+          cleanup();
+          reject(new Error('daemon hello line exceeded size limit'));
+        }
+        return;
+      }
+      const line = buffer.slice(0, idx);
+      // Re-emit anything past the newline so the pipe-stage sees it.
+      const tail = buffer.slice(idx + 1);
+      cleanup();
+      if (tail.length > 0) {
+        // Push back via unshift — Node's net.Socket supports it on readable streams.
+        socket.unshift(tail);
+      }
+      try {
+        const parsed = JSON.parse(line) as DaemonHello;
+        if (typeof parsed.codegraph !== 'string' || typeof parsed.pid !== 'number') {
+          reject(new Error('daemon hello missing required fields'));
+          return;
+        }
+        resolve(parsed);
+      } catch (err) {
+        reject(new Error(`daemon hello not JSON: ${err instanceof Error ? err.message : String(err)}`));
+      }
+    };
+    const onError = (err: Error) => { cleanup(); reject(err); };
+    const onClose = () => { cleanup(); reject(new Error('daemon closed connection before hello')); };
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error('timed out waiting for daemon hello'));
+    }, 3000);
+    timer.unref?.();
+    socket.on('data', onData);
+    socket.on('error', onError);
+    socket.on('close', onClose);
+  });
+}
+
+/**
+ * Pipe stdin → socket and socket → stdout. Resolves once either end closes
+ * so the process can exit. Note: we deliberately do NOT use
+ * `process.stdin.pipe(socket)` because pipe propagates 'end' onto the
+ * downstream, which would close the socket prematurely if stdin happens to
+ * end early — the MCP spec allows it to stay open across reconnects.
+ */
+function pipeUntilClose(socket: net.Socket): Promise<void> {
+  return new Promise((resolve) => {
+    let resolved = false;
+    const done = () => { if (!resolved) { resolved = true; resolve(); } };
+
+    process.stdin.on('data', (chunk) => {
+      try { socket.write(chunk); } catch { /* socket may have errored — close path catches it */ }
+    });
+    process.stdin.on('end', () => {
+      try { socket.end(); } catch { /* ignore */ }
+      done();
+    });
+    // 'close' and 'error' both tear down: a socket-backed stdin can fail with
+    // an 'error' (ECONNRESET/hangup) rather than a clean close; destroying it
+    // stops a hung fd from busy-spinning the event loop (#799).
+    const teardown = () => {
+      try { process.stdin.destroy(); } catch { /* ignore */ }
+      try { socket.destroy(); } catch { /* ignore */ }
+      done();
+    };
+    process.stdin.on('close', teardown);
+    process.stdin.on('error', teardown);
+
+    socket.on('data', (chunk) => {
+      try { process.stdout.write(chunk); } catch { /* ignore */ }
+    });
+    socket.on('end', () => done());
+    socket.on('close', () => done());
+    socket.on('error', (err) => {
+      process.stderr.write(`[CodeGraph MCP] daemon socket error: ${err.message}\n`);
+      done();
+    });
+  });
+}
+
+/**
+ * PPID watchdog mirroring the one in `MCPServer.start` — kills the proxy if
+ * the MCP host (or its proxy of a host, see HOST_PPID_ENV) goes away without
+ * closing stdin. Issue #277 documents why we can't rely on stdin EOF on
+ * Linux: the parent may be SIGKILL'd and reparenting doesn't close pipes.
+ *
+ * The proxy's "kill" is just a socket close + process.exit — no SQLite or
+ * watchers to clean up, so this is cheap.
+ */
+function startPpidWatchdog(socket: net.Socket): void {
+  const pollMs = parsePollMs(process.env.CODEGRAPH_PPID_POLL_MS);
+  if (pollMs <= 0) return;
+  const originalPpid = process.ppid;
+  const hostPpid = parseHostPpid(process.env[HOST_PPID_ENV]);
+  const timer = setInterval(() => {
+    const reason = supervisionLostReason({
+      originalPpid,
+      currentPpid: process.ppid,
+      hostPpid,
+      isAlive: isProcessAliveLocal,
+    });
+    if (reason) {
+      process.stderr.write(`[CodeGraph MCP] Parent process exited (${reason}); shutting down.\n`);
+      try { socket.destroy(); } catch { /* ignore */ }
+      process.exit(0);
+    }
+  }, pollMs);
+  timer.unref?.();
+}
+
+function parsePollMs(raw: string | undefined): number {
+  if (raw === undefined || raw === '') return DEFAULT_PPID_POLL_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return DEFAULT_PPID_POLL_MS;
+  if (parsed < 0) return DEFAULT_PPID_POLL_MS;
+  return Math.floor(parsed);
+}
+
+function parseHostPpid(raw: string | undefined): number | null {
+  if (raw === undefined || raw === '') return null;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 1) return null;
+  return parsed;
+}
+
+function isProcessAliveLocal(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err: unknown) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === 'EPERM') return true;
+    return false;
+  }
+}
diff --git a/src/mcp/server-instructions.ts b/src/mcp/server-instructions.ts
index d82a30911..c0cb8ea6e 100644
--- a/src/mcp/server-instructions.ts
+++ b/src/mcp/server-instructions.ts
@@ -17,51 +17,82 @@
  */
 export const SERVER_INSTRUCTIONS = `# Codegraph — code intelligence over an indexed knowledge graph
 
-Codegraph is a SQLite knowledge graph of every symbol, edge, and file
-in the workspace. Reads are sub-millisecond; the index lags writes by
-about a second through the file watcher. Consult it BEFORE writing or
-editing code, not during.
+Codegraph is a SQLite knowledge graph of every symbol, edge, and file in
+the workspace — pre-computed structure you would otherwise re-derive by
+reading files (cached intelligence: thousands of parse/trace decisions you
+don't pay to re-reason each run). Reads are sub-millisecond; the index lags
+writes by ~1s through the file watcher. Reach for it BEFORE *and* while
+writing or editing code — not just for questions: one call returns the
+verbatim source PLUS who calls it and what it affects, so you edit with the
+blast radius in view. More accurate context, in far fewer tokens and
+round-trips than reading files yourself.
 
-## Answer directly — don't delegate exploration
+## Use codegraph instead of reading files — for questions AND edits
 
-For "how does X work", architecture, trace, or where-is-X questions,
-answer DIRECTLY using 2-3 codegraph calls: \`codegraph_context\` first,
-then ONE \`codegraph_explore\` for the source of the symbols it surfaces.
-Codegraph IS the pre-built search index — so delegating the lookup to a
-separate file-reading sub-task/agent, or running your own grep + read
-loop, repeats work codegraph already did and costs more for the same
-answer. Reach for raw Read/Grep only to confirm a specific detail
-codegraph didn't cover. A direct codegraph answer is typically a handful
-of calls; a grep/read exploration is dozens.
+Whether you're answering "how does X work" or implementing a change (fixing
+a bug, adding a feature), reach for codegraph before you Read. For
+understanding, answer DIRECTLY — usually with ONE \`codegraph_explore\` call.
+\`codegraph_explore\` takes either a natural-language question or a bag of
+symbol/file names and returns the verbatim source of the relevant symbols
+grouped by file, so it is Read-equivalent and most often the ONLY
+codegraph call you need. Codegraph IS the pre-built search index — so
+delegating the lookup to a separate file-reading sub-task/agent, or
+running your own grep + read loop, repeats work codegraph already did and
+costs more for the same answer. Reach for raw Read/Grep only to confirm a
+specific detail codegraph didn't cover. A direct codegraph answer is
+typically one to a few calls; a grep/read exploration is dozens.
 
 ## Tool selection by intent
 
-- **"What is the symbol named X?"** → \`codegraph_search\`
-- **"What's the deal with this task / feature / area?"** → \`codegraph_context\` (PRIMARY — composes search + node + callers + callees in one call)
-- **"What calls this?"** → \`codegraph_callers\`
-- **"What does this call?"** → \`codegraph_callees\`
-- **"What would changing this break?"** → \`codegraph_impact\`
-- **"Show me this symbol's source / signature / docstring."** → \`codegraph_node\`
-- **"Show me several related symbols' source / survey an area."** → \`codegraph_explore\` (ONE capped call; prefer over many codegraph_node/Read)
-- **"What's in directory X?"** → \`codegraph_files\`
-- **"Is the index ready / what's its size?"** → \`codegraph_status\`
+- **Almost any question — "how does X work", architecture, a bug, "what/where is X", or surveying an area** → \`codegraph_explore\` (PRIMARY — call FIRST; ONE capped call returns the verbatim source of the relevant symbols grouped by file; most often the ONLY call you need)
+- **"How does X reach/become Y? / the flow / the path from X to Y"** → \`codegraph_explore\`, naming the symbols that span the flow (e.g. \`mutateElement renderScene\`) — it surfaces the call path among them, including dynamic-dispatch hops (callbacks, React re-render, JSX children) grep can't follow
+- **"What is the symbol named X?" (just its location)** → \`codegraph_search\`
+- **"What calls this?" / "What would changing this break?"** → \`codegraph_callers\` — EVERY call site with file:line, including where a function is **registered as a callback** (passed as an argument, assigned to a function pointer/field, listed in a handler table) — labeled "via callback registration" — so a function with no direct calls is NOT dead if it's wired up somewhere. When several UNRELATED symbols share a name (one \`UserService\` per monorepo app), it reports **one section per definition** (never a merged list) — pass \`file\` to focus the definition you mean. The wider blast radius arrives automatically on \`codegraph_explore\` (its "Blast radius" section) and \`codegraph_node\` (the dependents note)
+- **"What does this call?"** → \`codegraph_node\` with that symbol and \`includeCode: true\` — the body IS the callee list, and the caller/callee trail comes with it
+- **Reading a source FILE (any time you'd use the \`Read\` tool)** → \`codegraph_node\` with a \`file\` path and no \`symbol\`. It returns the file's **current source with line numbers — the same \`<n>\\t<line>\` shape \`Read\` gives you, safe to \`Edit\` from** — narrowable with \`offset\`/\`limit\` exactly like \`Read\`, PLUS a one-line note of which files depend on it. Same bytes as \`Read\`, faster (served from the index), with the blast radius attached. Use it **instead of \`Read\`** for indexed source files; fall back to \`Read\` only for what codegraph doesn't index (configs, docs). Pass \`symbolsOnly: true\` for just the file's structure.
+- **About to read or edit a symbol you can name** → \`codegraph_node\` with that \`symbol\` (SECONDARY — the after-explore depth tool): the verbatim source (\`includeCode: true\`) PLUS its caller/callee trail, so before changing it you see what calls it and what your edit would break. For an OVERLOADED name it returns EVERY matching definition's body in one call, so you never Read a file to find the right overload
 
 ## Common chains
 
-- **Onboarding**: \`codegraph_context\` first. If still unclear, \`codegraph_explore\` for breadth, then \`codegraph_node\` on specific symbols.
-- **Refactor planning**: \`codegraph_search\` → \`codegraph_callers\` → \`codegraph_impact\`. The blast-radius answer comes from impact, not from walking callers manually.
-- **Debugging a regression**: \`codegraph_callers\` of the suspected symbol; widen with \`codegraph_impact\` if an unexpected call appears.
+- **Flow / "how does X reach Y"**: ONE \`codegraph_explore\` with the symbol names spanning the flow — it surfaces the call path among them (riding dynamic-dispatch hops) AND returns their source. No need to reconstruct the path with \`codegraph_search\` + \`codegraph_callers\`.
+- **Onboarding / understanding any area**: ONE \`codegraph_explore\` is usually the whole answer. Only follow up — \`codegraph_node\` for a specific symbol — if something is still unclear.
+- **Refactor planning**: \`codegraph_callers\` for the complete call-site list to update; the wider blast radius is already attached to \`codegraph_explore\` / \`codegraph_node\` output.
+- **Debugging a regression**: \`codegraph_callers\` of the suspected symbol; \`codegraph_node\` on anything unexpected that appears.
 
 ## Anti-patterns
 
+- **Trust codegraph's results — don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.
 - **Don't grep first** when looking up a symbol by name — \`codegraph_search\` is faster and returns kind + location + signature.
-- **Don't chain \`codegraph_search\` + \`codegraph_node\`** when you just want context — \`codegraph_context\` is one round-trip.
+- **Don't chain \`codegraph_search\` + \`codegraph_node\`** to understand an area — ONE \`codegraph_explore\` returns the relevant symbols' source together in a single round-trip.
 - **Don't loop \`codegraph_node\` over many symbols** — one \`codegraph_explore\` call returns them all grouped by file, while each separate call re-reads the whole context and costs far more. Use \`codegraph_node\` for a single symbol.
-- **Don't query the index immediately after editing a file** — the watcher needs ~500ms to debounce + sync. Wait for the next turn.
+- **Don't reach for the \`Read\` tool on an indexed source file** — \`codegraph_node\` with a \`file\` reads it for you (same \`<n>\\t<line>\` source, \`offset\`/\`limit\` like Read, faster, with its blast radius), and with a \`symbol\` it returns the source plus the caller/callee trail. Reach for raw \`Read\` only for what codegraph doesn't index (configs, docs) or when the staleness banner flags a file as pending re-index.
+- **After editing, check the staleness banner.** When a tool response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust codegraph.
 
 ## Limitations
 
+- If a tool reports a project isn't indexed (no \`.codegraph/\`), stop calling codegraph tools for that project for the rest of the session and use your built-in tools there instead. Indexing is the user's decision — mention they can run \`codegraph init\` if it comes up, but don't run it yourself.
 - Index lags file writes by ~1 second.
 - Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.
 - No live correctness validation — that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.
 `;
+
+/**
+ * Instructions variant sent when the workspace has NO codegraph index.
+ *
+ * Sending the full playbook ("lean on codegraph for everything") into a
+ * session where every call would fail wastes the agent's calls and — worse —
+ * the failures teach it codegraph is broken. The unindexed variant is a
+ * short, unambiguous "inactive this session" note; `tools/list` is gated to
+ * empty in the same state, so the agent has nothing to mis-call. Indexing is
+ * deliberately left to the user: the agent is told NOT to run init itself.
+ */
+export const SERVER_INSTRUCTIONS_UNINDEXED = `# Codegraph — inactive (workspace not indexed)
+
+This workspace has no codegraph index (no \`.codegraph/\` directory), so no
+codegraph tools are available this session. Work with your built-in tools as
+usual.
+
+Indexing is the user's decision — do not run it yourself. If the user asks
+about codegraph, they can enable it by running \`codegraph init\` in the
+project root and starting a new session.
+`;
diff --git a/src/mcp/session.ts b/src/mcp/session.ts
new file mode 100644
index 000000000..f2b193c12
--- /dev/null
+++ b/src/mcp/session.ts
@@ -0,0 +1,307 @@
+/**
+ * MCP per-connection session — speaks the JSON-RPC protocol (initialize,
+ * tools/list, tools/call) over a single {@link JsonRpcTransport}. It owns
+ * per-client state only (which protocol version the client asked for, whether
+ * it advertised `roots`, the one-shot roots/list latch); the heavyweight
+ * resources (CodeGraph, watcher, ToolHandler) live in the shared
+ * {@link MCPEngine} so daemon mode can collapse N inotify sets / DB handles
+ * to one.
+ *
+ * The state-machine itself mirrors what `MCPServer` used to do inline before
+ * issue #411 split it out — the same regression tests in
+ * `__tests__/mcp-initialize.test.ts` still drive this code path.
+ */
+
+import * as path from 'path';
+import { JsonRpcRequest, JsonRpcNotification, JsonRpcTransport, ErrorCodes } from './transport';
+import { MCPEngine } from './engine';
+import { tools } from './tools';
+import { SERVER_INSTRUCTIONS, SERVER_INSTRUCTIONS_UNINDEXED } from './server-instructions';
+import { CodeGraphPackageVersion } from './version';
+import { findNearestCodeGraphRoot } from '../directory';
+
+/**
+ * MCP Server Info — kept on the session because some clients log it. The
+ * version tracks the real package version (was a hard-coded '0.1.0').
+ */
+// Exported so the proxy can answer `initialize` locally with the IDENTICAL
+// payload the daemon would send — no drift between the two handshake paths.
+export const SERVER_INFO = {
+  name: 'codegraph',
+  version: CodeGraphPackageVersion,
+};
+
+/** MCP Protocol Version (latest the server claims). */
+export const PROTOCOL_VERSION = '2024-11-05';
+
+/**
+ * How long to wait for the client's `roots/list` response before giving up
+ * and falling back to the process cwd.
+ */
+const ROOTS_LIST_TIMEOUT_MS = 5000;
+
+/**
+ * Convert a file:// URI to a filesystem path. Handles URL encoding and
+ * Windows drive letter paths.
+ */
+function fileUriToPath(uri: string): string {
+  try {
+    const url = new URL(uri);
+    let filePath = decodeURIComponent(url.pathname);
+    if (process.platform === 'win32' && /^\/[a-zA-Z]:/.test(filePath)) {
+      filePath = filePath.slice(1);
+    }
+    return path.resolve(filePath);
+  } catch {
+    return uri.replace(/^file:\/\/\/?/, '');
+  }
+}
+
+/** First usable filesystem path from a `roots/list` result, or null. */
+function firstRootPath(result: unknown): string | null {
+  if (!result || typeof result !== 'object') return null;
+  const roots = (result as { roots?: unknown }).roots;
+  if (!Array.isArray(roots) || roots.length === 0) return null;
+  const first = roots[0] as { uri?: unknown };
+  if (typeof first?.uri !== 'string') return null;
+  return fileUriToPath(first.uri);
+}
+
+export interface MCPSessionOptions {
+  /**
+   * Explicit project path from the `--path` CLI flag. When set, the session
+   * will not bother asking the client for `roots/list` — we already know
+   * where the project lives.
+   */
+  explicitProjectPath?: string | null;
+}
+
+/**
+ * One MCP client's view of the server. Created fresh per stdio launch
+ * (direct mode) or per socket connection (daemon mode).
+ */
+export class MCPSession {
+  private clientSupportsRoots = false;
+  private rootsAttempted = false;
+  private resolvePromise: Promise<void> | null = null;
+  private explicitProjectPath: string | null;
+
+  constructor(
+    private transport: JsonRpcTransport,
+    private engine: MCPEngine,
+    opts: MCPSessionOptions = {},
+  ) {
+    this.explicitProjectPath = opts.explicitProjectPath ?? null;
+  }
+
+  /**
+   * Start handling messages from the transport. Returns immediately — the
+   * session lives for as long as the transport is open.
+   */
+  start(): void {
+    this.transport.start(this.handleMessage.bind(this));
+  }
+
+  /**
+   * Tear down the session. Does NOT touch the engine (the engine may serve
+   * other sessions) or call `process.exit` (the daemon decides when to exit).
+   */
+  stop(): void {
+    this.transport.stop();
+  }
+
+  /** Underlying transport — exposed for daemon-side close hooks. */
+  getTransport(): JsonRpcTransport {
+    return this.transport;
+  }
+
+  private async handleMessage(message: JsonRpcRequest | JsonRpcNotification): Promise<void> {
+    const isRequest = 'id' in message;
+    switch (message.method) {
+      case 'initialize':
+        if (isRequest) await this.handleInitialize(message as JsonRpcRequest);
+        break;
+      case 'initialized':
+        // Notification that client has finished initialization — no action needed.
+        break;
+      case 'tools/list':
+        if (isRequest) await this.handleToolsList(message as JsonRpcRequest);
+        break;
+      case 'tools/call':
+        if (isRequest) await this.handleToolsCall(message as JsonRpcRequest);
+        break;
+      case 'ping':
+        if (isRequest) this.transport.sendResult((message as JsonRpcRequest).id, {});
+        break;
+      case 'resources/list':
+        // We expose no MCP resources, but some clients (opencode, Codex) probe
+        // for them on connect; reply with an empty list instead of a
+        // MethodNotFound error that surfaces as a scary `-32601` log line. (#621)
+        if (isRequest) this.transport.sendResult((message as JsonRpcRequest).id, { resources: [] });
+        break;
+      case 'resources/templates/list':
+        if (isRequest) this.transport.sendResult((message as JsonRpcRequest).id, { resourceTemplates: [] });
+        break;
+      case 'prompts/list':
+        // Likewise — no prompts exposed, but answer the probe cleanly. (#621)
+        if (isRequest) this.transport.sendResult((message as JsonRpcRequest).id, { prompts: [] });
+        break;
+      default:
+        if (isRequest) {
+          this.transport.sendError(
+            (message as JsonRpcRequest).id,
+            ErrorCodes.MethodNotFound,
+            `Method not found: ${message.method}`,
+          );
+        }
+    }
+  }
+
+  private async handleInitialize(request: JsonRpcRequest): Promise<void> {
+    const params = request.params as {
+      rootUri?: string;
+      workspaceFolders?: Array<{ uri: string; name: string }>;
+      capabilities?: { roots?: unknown };
+    } | undefined;
+
+    this.clientSupportsRoots = !!params?.capabilities?.roots;
+
+    // Explicit project signal, strongest first: client-provided rootUri /
+    // workspaceFolders (LSP-style), else the --path the server was launched
+    // with. cwd is NOT used here — we defer it so a roots/list answer can
+    // win over it. See issue #196.
+    let explicitPath: string | null = null;
+    if (params?.rootUri) {
+      explicitPath = fileUriToPath(params.rootUri);
+    } else if (params?.workspaceFolders?.[0]?.uri) {
+      explicitPath = fileUriToPath(params.workspaceFolders[0].uri);
+    } else if (this.explicitProjectPath) {
+      explicitPath = this.explicitProjectPath;
+    }
+
+    // Pick the instructions variant by the workspace's index state — a cheap
+    // synchronous walk-up (existsSync loop only, no DB open, so the #172
+    // respond-fast contract holds). An unindexed workspace gets the short
+    // "inactive this session" note instead of the full playbook: the playbook
+    // tells the agent to lean on tools that would all fail, and early failures
+    // teach the agent to abandon codegraph entirely. `tools/list` is gated the
+    // same way (empty list when unindexed). When no explicit path is known yet
+    // (roots/list dance pending), cwd is the best predictor of where the
+    // default project will resolve — and on a mismatch the worst case is the
+    // optimistic full playbook backstopped by the empty tool list.
+    const indexed = findNearestCodeGraphRoot(explicitPath ?? process.cwd()) !== null;
+
+    // Respond to the handshake BEFORE doing any heavy init — see issue #172.
+    this.transport.sendResult(request.id, {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      serverInfo: SERVER_INFO,
+      instructions: indexed ? SERVER_INSTRUCTIONS : SERVER_INSTRUCTIONS_UNINDEXED,
+    });
+
+    if (explicitPath) {
+      // Kick off engine init in the background. If another session in the
+      // same daemon already opened the project, `ensureInitialized` is a
+      // ~free no-op — N concurrent clients pay exactly one open.
+      this.resolvePromise = this.engine.ensureInitialized(explicitPath);
+    }
+  }
+
+  private async handleToolsList(request: JsonRpcRequest): Promise<void> {
+    await this.retryInitIfNeeded();
+    // An unindexed workspace serves an EMPTY tool list: absence is the one
+    // signal an agent can't misread. Listing 8 tools that all fail wastes the
+    // agent's calls and teaches it codegraph is broken (observed: one or two
+    // early isError responses and the agent stops calling codegraph for the
+    // whole session). A `codegraph init` run after the server started is
+    // picked up on the next tools/list — retryInitIfNeeded re-walks — though
+    // most hosts only request the list once per connection.
+    this.transport.sendResult(request.id, {
+      tools: this.engine.hasDefaultCodeGraph() ? this.engine.getToolHandler().getTools() : [],
+    });
+  }
+
+  private async handleToolsCall(request: JsonRpcRequest): Promise<void> {
+    const params = request.params as {
+      name: string;
+      arguments?: Record<string, unknown>;
+    };
+
+    if (!params || !params.name) {
+      this.transport.sendError(request.id, ErrorCodes.InvalidParams, 'Missing tool name');
+      return;
+    }
+
+    const toolName = params.name;
+    const toolArgs = params.arguments || {};
+
+    const tool = tools.find((t) => t.name === toolName);
+    if (!tool) {
+      this.transport.sendError(
+        request.id,
+        ErrorCodes.InvalidParams,
+        `Unknown tool: ${toolName}`,
+      );
+      return;
+    }
+
+    await this.retryInitIfNeeded();
+
+    const result = await this.engine.getToolHandler().execute(toolName, toolArgs);
+    this.transport.sendResult(request.id, result);
+  }
+
+  /**
+   * Lazy default-project resolution. Three layers:
+   *   1. await the in-flight init kicked off from `handleInitialize` (if any);
+   *   2. if still uninitialized and we never asked the client for its roots,
+   *      do so now (one-shot); fall back to cwd if the client lacks roots;
+   *   3. last-resort: re-walk from the best candidate — picks up projects
+   *      that were `codegraph init`'d *after* the server started.
+   */
+  private async retryInitIfNeeded(): Promise<void> {
+    if (this.resolvePromise) {
+      try { await this.resolvePromise; } catch { /* fall through to retry */ }
+      this.resolvePromise = null;
+    }
+
+    if (this.engine.hasDefaultCodeGraph()) return;
+
+    const hint = this.explicitProjectPath ?? this.engine.getProjectPath();
+    if (!hint && !this.rootsAttempted) {
+      this.rootsAttempted = true;
+      this.resolvePromise = this.clientSupportsRoots
+        ? this.initFromRoots()
+        : this.engine.ensureInitialized(process.cwd());
+      try { await this.resolvePromise; } catch { /* fall through */ }
+      this.resolvePromise = null;
+      if (this.engine.hasDefaultCodeGraph()) return;
+    }
+
+    // Last resort: walk from the best candidate (sync open). Picks up
+    // projects that appeared after the server started.
+    const candidate = hint ?? process.cwd();
+    this.engine.retryInitializeSync(candidate);
+  }
+
+  /**
+   * Ask the client for its workspace root via `roots/list` and open the
+   * first one. Falls back to `process.cwd()` on timeout or empty answer.
+   */
+  private async initFromRoots(): Promise<void> {
+    let target = process.cwd();
+    try {
+      const result = await this.transport.request('roots/list', undefined, ROOTS_LIST_TIMEOUT_MS);
+      const rootPath = firstRootPath(result);
+      if (rootPath) {
+        target = rootPath;
+      } else {
+        process.stderr.write('[CodeGraph MCP] Client returned no workspace roots; falling back to process cwd.\n');
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[CodeGraph MCP] roots/list request failed (${msg}); falling back to process cwd.\n`);
+    }
+    await this.engine.ensureInitialized(target);
+  }
+}
diff --git a/src/mcp/stdin-teardown.ts b/src/mcp/stdin-teardown.ts
new file mode 100644
index 000000000..1d60f7490
--- /dev/null
+++ b/src/mcp/stdin-teardown.ts
@@ -0,0 +1,46 @@
+/**
+ * Treat a stdin failure as a shutdown signal — issue #799.
+ *
+ * An MCP stdio server's lifeline is its stdin: when the host/client goes away,
+ * stdin should end and the server should exit. The server paths listened for
+ * `'end'` and `'close'` — but NOT `'error'`.
+ *
+ * That gap bites with a socket-backed stdin, which is the shape VS Code /
+ * Claude Code use (a socketpair, not a pipe). When the client dies, the socket
+ * can surface as an `'error'` (ECONNRESET / hangup) rather than a clean
+ * `'close'`. With no `'error'` listener, Node escalates it to the process-wide
+ * `uncaughtException` handler, which logs and keeps running — so the server
+ * orphans instead of exiting. Worse, on Linux a `POLLHUP` socket fd left
+ * registered in epoll wakes the event loop continuously, pinning a core at
+ * 100% CPU (the spin reported in #799); once the main thread spins, the
+ * `setInterval` PPID watchdog can't even fire, so the orphan runs forever.
+ *
+ * Fix: listen for `'error'` as well, and DESTROY the stdin stream on any
+ * terminal event so the fd leaves epoll and can't keep churning, then run the
+ * caller's shutdown. Fires `onTerminal` at most once — callers' shutdowns are
+ * already re-entry-guarded, but the single-shot guard also keeps `destroy()`'s
+ * follow-on `'close'` from re-invoking it.
+ *
+ * `stream` is injectable for tests; it defaults to `process.stdin`.
+ */
+export function treatStdinFailureAsShutdown(
+  onTerminal: () => void,
+  stream: NodeJS.ReadableStream = process.stdin
+): void {
+  let fired = false;
+  const fire = (): void => {
+    if (fired) return;
+    fired = true;
+    // Drop the fd from epoll so a hung/half-closed socket can't keep waking
+    // the loop. Best-effort: the stream may already be torn down.
+    try {
+      (stream as Partial<{ destroy(): void }>).destroy?.();
+    } catch {
+      /* already gone */
+    }
+    onTerminal();
+  };
+  stream.on('end', fire);
+  stream.on('close', fire);
+  stream.on('error', fire);
+}
diff --git a/src/mcp/tools.ts b/src/mcp/tools.ts
index 1c8721b95..9468d8d64 100644
--- a/src/mcp/tools.ts
+++ b/src/mcp/tools.ts
@@ -4,18 +4,70 @@
  * Defines the tools exposed by the CodeGraph MCP server.
  */
 
-import CodeGraph, { findNearestCodeGraphRoot } from '../index';
-import type { Node, Edge, SearchResult, Subgraph, TaskContext, NodeKind } from '../types';
-import { createHash } from 'crypto';
-import { writeFileSync, readFileSync, existsSync } from 'fs';
-import { clamp, validatePathWithinRoot } from '../utils';
-import { tmpdir } from 'os';
-import { join } from 'path';
-import { WASM_FALLBACK_FIX_RECIPE } from '../db';
+import type CodeGraph from '../index';
+import { findNearestCodeGraphRoot } from '../directory';
+// Lazy-load the heavy CodeGraph chain off the MCP startup path — see the same
+// helper in engine.ts. ToolHandler must load to answer tools/list (static
+// schemas), but it must NOT drag in sqlite/query layers before the daemon binds;
+// CodeGraph is pulled in only when a tool actually opens a project. require() is
+// sync + cached (CommonJS build).
+const loadCodeGraph = (): typeof import('../index').default =>
+  (require('../index') as typeof import('../index')).default;
+import {
+  detectWorktreeIndexMismatch,
+  worktreeMismatchWarning,
+  worktreeMismatchNotice,
+  type WorktreeIndexMismatch,
+} from '../sync/worktree';
+import type { PendingFile } from '../sync';
+import type { Node, Edge, SearchResult, Subgraph, NodeKind } from '../types';
+import { isTestFile, normalizeNameToken } from '../search/query-utils';
+import {
+  existsSync,
+  readFileSync,
+} from 'fs';
+import { clamp, validatePathWithinRoot, validateProjectPath, isConfigLeafNode, CONFIG_LEAF_LANGUAGES } from '../utils';
+import { isGeneratedFile } from '../extraction/generated-detection';
+
+/**
+ * An expected, recoverable "codegraph can't serve this" condition — most
+ * importantly a project with no index. The dispatch catch converts these to
+ * SUCCESS-shaped responses (guidance text, NO isError): an `isError: true`
+ * early in a session teaches the agent the toolset is broken and it stops
+ * calling codegraph entirely (observed repeatedly), which is exactly wrong
+ * for conditions the agent can simply work around (use built-in tools for
+ * that codebase / pass projectPath). isError is reserved for "stop trying"
+ * cases: security refusals ({@link PathRefusalError}) and genuine
+ * malfunctions.
+ */
+export class NotIndexedError extends Error {}
+
+/**
+ * A security refusal (sensitive system path). Stays `isError: true` WITHOUT
+ * retry guidance — abandoning this path is the desired agent reaction.
+ */
+export class PathRefusalError extends Error {}
+import { resolve as resolvePath } from 'path';
 
 /** Maximum output length to prevent context bloat (characters) */
 const MAX_OUTPUT_LENGTH = 15000;
 
+/**
+ * Maximum length for free-form string inputs (query, task, symbol).
+ * Bounds memory and CPU when a buggy or hostile MCP client sends a
+ * huge payload — without this an attacker could ship a 100MB string
+ * and force a full FTS5 scan / OOM the server. 10 000 characters is
+ * far beyond any realistic legitimate query.
+ */
+const MAX_INPUT_LENGTH = 10_000;
+
+/**
+ * Maximum length for path-like string inputs (projectPath, path
+ * filter, glob pattern). Paths beyond a few thousand chars are
+ * never legitimate and signal abuse or a bug upstream.
+ */
+const MAX_PATH_LENGTH = 4_096;
+
 /**
  * Rust path roots that have no file-system equivalent — `crate` is the
  * current crate, `super` is the parent module, `self` is the current
@@ -93,41 +145,91 @@ export interface ExploreOutputBudget {
   includeCompletenessSignal: boolean;
   /** Include the explore-budget reminder at the end. */
   includeBudgetNote: boolean;
+  /**
+   * Hard-drop test/spec/icon/i18n files from the relevant-file set unless
+   * the query itself mentions tests. Today they're only deprioritized in
+   * the sort, which on tiny repos still lets one slip into the top N (e.g.
+   * cobra's `command_test.go` displaced `args.go` and contributed ~10KB of
+   * pure noise to "How does cobra parse commands?"). Off by default; on
+   * for the very-tiny tier where one slip dominates the budget.
+   */
+  excludeLowValueFiles: boolean;
 }
 
 export function getExploreOutputBudget(fileCount: number): ExploreOutputBudget {
+  // Tiered budget, scaled to project size. The budget is a CEILING (relevance
+  // still gates WHAT is included), and it MUST stay under the agent's INLINE
+  // tool-result cap (~25K chars). Above that, the host externalizes the result
+  // to a file the agent then Reads back — re-introducing a read AND the
+  // cache-write cost — which is exactly what a 35K vscode explore did in the
+  // n=4 README A/B. So even large repos cap at ~24K: the answer is the handful
+  // of ~100-line flow windows the agent would have grep-located and read (it
+  // natively reads ~6–9 files, median 100-line ranges), NOT a sprawl of 12
+  // files. Concentration onto the flow emerges from this cap + the named-file-
+  // first sort dropping peripheral files. Invariant: a larger tier must never
+  // get a smaller `maxCharsPerFile` than a smaller tier.
+  if (fileCount < 150) {
+    return {
+      // ITER3: revert iter2's aggressive body shrink (forced Read fallback —
+      // the per-file 2.5K cap pushed the agent to Read instead of node).
+      // Back to the iter1 shape (13K/4/3.8K) but keep the test-file
+      // hard-exclude. The cost lever for this tier lives in steering the
+      // agent to stop after 1-2 calls, not in this budget.
+      maxOutputChars: 13000,
+      defaultMaxFiles: 4,
+      maxCharsPerFile: 3800,
+      gapThreshold: 7,
+      maxSymbolsInFileHeader: 5,
+      maxEdgesPerRelationshipKind: 4,
+      includeRelationships: false,
+      includeAdditionalFiles: false,
+      includeCompletenessSignal: false,
+      includeBudgetNote: false,
+      excludeLowValueFiles: true,
+    };
+  }
   if (fileCount < 500) {
     return {
+      // ITER3: same revert/keep-filter pattern as <150.
       maxOutputChars: 18000,
       defaultMaxFiles: 5,
       maxCharsPerFile: 3800,
       gapThreshold: 8,
       maxSymbolsInFileHeader: 6,
       maxEdgesPerRelationshipKind: 6,
-      includeRelationships: true,
+      includeRelationships: false,
       includeAdditionalFiles: false,
       includeCompletenessSignal: false,
       includeBudgetNote: false,
+      excludeLowValueFiles: true,
     };
   }
   if (fileCount < 5000) {
     return {
-      maxOutputChars: 13000,
-      defaultMaxFiles: 6,
-      maxCharsPerFile: 2500,
-      gapThreshold: 10,
-      maxSymbolsInFileHeader: 8,
-      maxEdgesPerRelationshipKind: 8,
+      // ~150-line per-file window (the native read unit) × ~6 files, capped at
+      // the ~24K inline ceiling so the response is never externalized. Per-file
+      // stays ≥ the <500 tier (3800) — monotonic.
+      maxOutputChars: 24000,
+      defaultMaxFiles: 8,
+      maxCharsPerFile: 6500,
+      gapThreshold: 12,
+      maxSymbolsInFileHeader: 10,
+      maxEdgesPerRelationshipKind: 10,
       includeRelationships: true,
       includeAdditionalFiles: true,
       includeCompletenessSignal: true,
       includeBudgetNote: true,
+      excludeLowValueFiles: false,
     };
   }
+  // Large + very-large repos: SAME ~24K inline ceiling (a bigger response just
+  // externalizes — see vscode). More files indexed → more CALLS via
+  // getExploreBudget, not a bigger single response. Per-file 7000 (≥ smaller
+  // tiers) gives the central file a ~180-line orientation window.
   if (fileCount < 15000) {
     return {
-      maxOutputChars: 35000,
-      defaultMaxFiles: 12,
+      maxOutputChars: 24000,
+      defaultMaxFiles: 8,
       maxCharsPerFile: 7000,
       gapThreshold: 15,
       maxSymbolsInFileHeader: 15,
@@ -136,11 +238,12 @@ export function getExploreOutputBudget(fileCount: number): ExploreOutputBudget {
       includeAdditionalFiles: true,
       includeCompletenessSignal: true,
       includeBudgetNote: true,
+      excludeLowValueFiles: false,
     };
   }
   return {
-    maxOutputChars: 38000,
-    defaultMaxFiles: 14,
+    maxOutputChars: 24000,
+    defaultMaxFiles: 8,
     maxCharsPerFile: 7000,
     gapThreshold: 15,
     maxSymbolsInFileHeader: 15,
@@ -149,6 +252,7 @@ export function getExploreOutputBudget(fileCount: number): ExploreOutputBudget {
     includeAdditionalFiles: true,
     includeCompletenessSignal: true,
     includeBudgetNote: true,
+    excludeLowValueFiles: false,
   };
 }
 
@@ -167,6 +271,22 @@ function exploreLineNumbersEnabled(): boolean {
   return process.env.CODEGRAPH_EXPLORE_LINENUMS !== '0';
 }
 
+/**
+ * Adaptive explore sizing (default ON). `codegraph_explore` skeletonizes OFF-SPINE
+ * polymorphic-sibling files — a file whose class is one of ≥3 interchangeable
+ * implementations of a shared interface (e.g. OkHttp's `: Interceptor` classes) —
+ * to class + member signatures (bodies elided), keeping the on-spine exemplar full.
+ * This sizes the response to the answer instead of the budget cap on sibling-heavy
+ * flows (OkHttp interceptor-chain explore 28.5k→16.6k, ~28% cheaper than native
+ * search, reads flat). It is PROVABLY INERT elsewhere: distinct pipeline steps (no
+ * ≥3-implementer supertype, e.g. Excalidraw's `renderStaticScene`) and on-spine
+ * files keep full source — output is byte-identical to shipped on excalidraw /
+ * tokio / django / vscode / gin. Set `CODEGRAPH_ADAPTIVE_EXPLORE=0` to disable.
+ */
+function adaptiveExploreEnabled(): boolean {
+  return process.env.CODEGRAPH_ADAPTIVE_EXPLORE !== '0' && process.env.CODEGRAPH_ADAPTIVE_EXPLORE !== 'false';
+}
+
 /**
  * Prefix each line of a source slice with its 1-based line number, matching
  * the Read tool's `cat -n` convention (number + tab) so the agent treats it
@@ -185,17 +305,45 @@ function numberSourceLines(slice: string, firstLineNumber: number): string {
 }
 
 /**
- * Mark a Claude session as having consulted MCP tools.
- * This enables Grep/Glob/Bash commands that would otherwise be blocked.
+ * Per-file staleness banner emitted at the top of a tool response when the
+ * file watcher has pending events for files referenced by the response.
+ * The agent uses this to fall back to Read for those specific files
+ * without waiting for the debounced sync (issue #403).
  */
-function markSessionConsulted(sessionId: string): void {
-  try {
-    const hash = createHash('md5').update(sessionId).digest('hex').slice(0, 16);
-    const markerPath = join(tmpdir(), `codegraph-consulted-${hash}`);
-    writeFileSync(markerPath, new Date().toISOString(), 'utf8');
-  } catch {
-    // Silently fail - don't break MCP on marker write failure
-  }
+export function formatStaleBanner(stale: PendingFile[]): string {
+  const now = Date.now();
+  const lines = stale.map((p) => {
+    const ageMs = Math.max(0, now - p.lastSeenMs);
+    const label = p.indexing ? 'indexing in progress' : 'pending sync';
+    return `  - ${p.path} (edited ${ageMs}ms ago, ${label})`;
+  });
+  return (
+    '⚠️ Some files referenced below were edited since the last index sync — ' +
+    'their codegraph entries may be stale:\n' +
+    lines.join('\n') +
+    '\nFor accurate content of those specific files, Read them directly. ' +
+    'The rest of this response is fresh.'
+  );
+}
+
+/**
+ * Compact footer listing pending files that are NOT referenced in this
+ * response. Gives the agent a complete project-wide freshness picture
+ * without bloating the main banner.
+ */
+export function formatStaleFooter(stale: PendingFile[]): string {
+  const MAX = 5;
+  const now = Date.now();
+  const shown = stale.slice(0, MAX);
+  const lines = shown.map((p) => {
+    const ageMs = Math.max(0, now - p.lastSeenMs);
+    return `  - ${p.path} (edited ${ageMs}ms ago)`;
+  });
+  const more = stale.length > MAX ? `\n  - …and ${stale.length - MAX} more` : '';
+  return (
+    `(Note: ${stale.length} file(s) elsewhere in this project are pending index ` +
+    `sync but were not referenced above:\n${lines.join('\n')}${more})`
+  );
 }
 
 /**
@@ -240,15 +388,16 @@ const projectPathProperty: PropertySchema = {
 /**
  * All CodeGraph MCP tools
  *
- * Designed for minimal context usage - use codegraph_context as the primary tool,
- * and only use other tools for targeted follow-up queries.
+ * Designed for minimal context usage - use codegraph_explore as the primary tool
+ * (one call usually answers the whole question), and only use other tools for
+ * targeted follow-up queries.
  *
  * All tools support cross-project queries via the optional `projectPath` parameter.
  */
 export const tools: ToolDefinition[] = [
   {
     name: 'codegraph_search',
-    description: 'Quick symbol search by name. Returns locations only (no code). Use codegraph_context instead for comprehensive task context.',
+    description: 'Quick symbol search by name. Returns locations only (no code). Use codegraph_explore instead to get the actual source / understand an area in one call.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -271,34 +420,9 @@ export const tools: ToolDefinition[] = [
       required: ['query'],
     },
   },
-  {
-    name: 'codegraph_context',
-    description: 'PRIMARY TOOL — call this FIRST for any "how does X work", architecture, feature, or bug-context question. Composes search + node + callers + callees and returns entry points, related symbols, and key code in ONE call — usually enough to answer with no further search/Read/Grep. Prefer this over chaining codegraph_search + codegraph_node, and over codegraph_explore. NOTE: provides CODE context, not product requirements; for new features still clarify UX/edge cases with the user.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        task: {
-          type: 'string',
-          description: 'Description of the task, bug, or feature to build context for',
-        },
-        maxNodes: {
-          type: 'number',
-          description: 'Maximum symbols to include (default: 20)',
-          default: 20,
-        },
-        includeCode: {
-          type: 'boolean',
-          description: 'Include code snippets for key symbols (default: true)',
-          default: true,
-        },
-        projectPath: projectPathProperty,
-      },
-      required: ['task'],
-    },
-  },
   {
     name: 'codegraph_callers',
-    description: 'Find all functions/methods that call a specific symbol. Useful for understanding usage patterns and impact of changes.',
+    description: 'List functions that call <symbol>. For the full flow, use codegraph_explore.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -306,6 +430,10 @@ export const tools: ToolDefinition[] = [
           type: 'string',
           description: 'Name of the function, method, or class to find callers for',
         },
+        file: {
+          type: 'string',
+          description: 'Narrow to the definition in this file (path or suffix) when several same-named symbols exist (e.g. one UserService per app in a monorepo)',
+        },
         limit: {
           type: 'number',
           description: 'Maximum number of callers to return (default: 20)',
@@ -318,7 +446,7 @@ export const tools: ToolDefinition[] = [
   },
   {
     name: 'codegraph_callees',
-    description: 'Find all functions/methods that a specific symbol calls. Useful for understanding dependencies and code flow.',
+    description: 'List functions that <symbol> calls. For the full flow, use codegraph_explore.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -326,6 +454,10 @@ export const tools: ToolDefinition[] = [
           type: 'string',
           description: 'Name of the function, method, or class to find callees for',
         },
+        file: {
+          type: 'string',
+          description: 'Narrow to the definition in this file (path or suffix) when several same-named symbols exist',
+        },
         limit: {
           type: 'number',
           description: 'Maximum number of callees to return (default: 20)',
@@ -338,7 +470,7 @@ export const tools: ToolDefinition[] = [
   },
   {
     name: 'codegraph_impact',
-    description: 'Analyze the impact radius of changing a symbol. Shows what code could be affected by modifications.',
+    description: 'List symbols affected by changing <symbol>. Use before a refactor.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -346,6 +478,10 @@ export const tools: ToolDefinition[] = [
           type: 'string',
           description: 'Name of the symbol to analyze impact for',
         },
+        file: {
+          type: 'string',
+          description: 'Narrow to the definition in this file (path or suffix) when several same-named symbols exist',
+        },
         depth: {
           type: 'number',
           description: 'How many levels of dependencies to traverse (default: 2)',
@@ -358,33 +494,54 @@ export const tools: ToolDefinition[] = [
   },
   {
     name: 'codegraph_node',
-    description: 'Get detailed info about ONE symbol (location, signature, docstring). Pass includeCode=true for source: a function/method returns its body; a class/interface/struct/enum returns a compact member OUTLINE (fields + method signatures + line numbers), not every method body — Read or codegraph_node a specific member for its body. Keep includeCode=false to minimize context. For SEVERAL related symbols, make ONE codegraph_explore (or codegraph_context) call instead of many node calls — repeated node calls each re-read the whole context and cost far more.',
+    description: 'Two modes. (1) READ A FILE — use INSTEAD of the Read tool: pass `file` (a path or basename) with no `symbol` and it returns that file\'s current on-disk source with line numbers, exactly the shape Read gives you (`<n>\\t<line>`, safe to Edit from), narrowable with `offset`/`limit` just like Read — PLUS a one-line note of which files depend on it. Same bytes as Read, faster (served from the index), with the blast radius attached. Use it whenever you would Read a source file. (2) ONE SYMBOL you can name — its location, signature, verbatim source (includeCode=true) and caller/callee trail in one call, so before changing it you see what calls it and what your edit would break. For an AMBIGUOUS name it returns EVERY matching definition\'s body in one call (so you never Read a file to find the right overload); pass `file`/`line` to pin one. Use codegraph_explore for several related symbols or the full flow.',
     inputSchema: {
       type: 'object',
       properties: {
         symbol: {
           type: 'string',
-          description: 'Name of the symbol to get details for',
+          description: 'Name of the symbol to read (symbol mode). Omit it and pass `file` alone to read a whole file like Read.',
         },
         includeCode: {
           type: 'boolean',
-          description: 'Include full source code (default: false to minimize context)',
+          description: 'Symbol mode: include the symbol\'s full body (default: false). Ignored in file mode, which always returns source unless `symbolsOnly` is set.',
           default: false,
         },
+        file: {
+          type: 'string',
+          description: 'A file path or basename (e.g. "harness.rs", "src/auth/session.ts"). Pass it ALONE (no symbol) to READ the file like the Read tool — its full source with line numbers + which files depend on it. Or pass it WITH a symbol to disambiguate an overloaded name to the definition in this file.',
+        },
+        offset: {
+          type: 'number',
+          description: 'File mode: 1-based line to start reading from, exactly like Read\'s offset. Defaults to the start of the file.',
+        },
+        limit: {
+          type: 'number',
+          description: 'File mode: maximum number of lines to return, exactly like Read\'s limit. Defaults to the whole file (capped at 2000 lines, like Read).',
+        },
+        symbolsOnly: {
+          type: 'boolean',
+          description: 'File mode: return just the file\'s symbol map + dependents (a cheap structural overview) instead of its source.',
+          default: false,
+        },
+        line: {
+          type: 'number',
+          description: 'Symbol mode only: disambiguate to the definition at/around this line (use with the file:line a trail showed you).',
+        },
         projectPath: projectPathProperty,
       },
-      required: ['symbol'],
+      required: [],
     },
   },
   {
     name: 'codegraph_explore',
-    description: 'Returns source for SEVERAL related symbols grouped by file, plus a relationship map, in ONE capped call. This is the efficient way to inspect many related symbols at once — strongly prefer it over a series of codegraph_node or Read calls (each separate call re-reads the whole context, so 8 node calls cost far more than 1 explore). Use it after codegraph_context when you need to see the actual source of several symbols. Query with specific symbol/file/code terms, NOT natural-language sentences — run codegraph_search first to find names. Bad: "how are agent prompts loaded and passed to the CLI". Good: "renderStaticScene drawElementOnCanvas ShapeCache renderElement.ts".',
+    description: 'PRIMARY TOOL — call FIRST for almost any question OR before an edit: how does X work, architecture, a bug, where/what is X, surveying an area, or the symbols you are about to change. Returns the verbatim source of the relevant symbols grouped by file in ONE capped call (Read-equivalent — treat the shown source as already Read; do NOT re-open those files), plus the call path among them. Query can be a natural-language question OR a bag of symbol/file names. Usually the ONLY call you need — more accurate context, in far fewer tokens and round-trips than a search/Read/Grep loop.',
     inputSchema: {
       type: 'object',
       properties: {
         query: {
           type: 'string',
-          description: 'Symbol names, file names, or short code terms to explore (e.g., "AuthService loginUser session-manager", "GraphTraverser BFS impact traversal.ts"). Use codegraph_search first to find relevant names.',
+          description: 'Symbol names, file names, or short code terms to explore (e.g., "AuthService loginUser session-manager", "GraphTraverser BFS impact traversal.ts"). For a flow question, name the symbols spanning the flow (e.g. "mutateElement renderScene"). A natural-language question works too — no prior codegraph_search needed.',
         },
         maxFiles: {
           type: 'number',
@@ -398,7 +555,7 @@ export const tools: ToolDefinition[] = [
   },
   {
     name: 'codegraph_status',
-    description: 'Get the status of the CodeGraph index, including statistics about indexed files, nodes, and edges.',
+    description: 'Index health check (files / nodes / edges). Skip unless debugging.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -408,7 +565,7 @@ export const tools: ToolDefinition[] = [
   },
   {
     name: 'codegraph_files',
-    description: 'REQUIRED for file/folder exploration. Get the project file structure from the CodeGraph index. Returns a tree view of all indexed files with metadata (language, symbol count). Much faster than Glob/filesystem scanning. Use this FIRST when exploring project structure, finding files, or understanding codebase organization.',
+    description: 'Indexed file tree with language + symbol counts. Faster than Glob for project layout.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -441,6 +598,45 @@ export const tools: ToolDefinition[] = [
   },
 ];
 
+/**
+ * Allowlist-filtered tool definitions WITHOUT an engine — the static surface the
+ * proxy answers `tools/list` with before any project is open. Mirrors
+ * `ToolHandler.getTools()` in the no-CodeGraph case (the dynamic per-repo budget
+ * note in a description only adds once `cg` is loaded; the schemas are static).
+ */
+export function getStaticTools(): ToolDefinition[] {
+  const raw = process.env.CODEGRAPH_MCP_TOOLS;
+  if (!raw || !raw.trim()) {
+    return tools.filter(t => DEFAULT_MCP_TOOLS.has(t.name.replace(/^codegraph_/, '')));
+  }
+  const allow = new Set(raw.split(',').map(s => s.trim().replace(/^codegraph_/, '')).filter(Boolean));
+  return allow.size ? tools.filter(t => allow.has(t.name.replace(/^codegraph_/, ''))) : tools;
+}
+
+/**
+ * The MCP tools served by DEFAULT (short names). The other defined tools
+ * (callees, impact, files, status) remain fully functional — handlers stay,
+ * the library API and CLI are untouched, and `CODEGRAPH_MCP_TOOLS` re-enables
+ * any of them — they just aren't LISTED to agents anymore.
+ *
+ * Evidence for the cut (the "adapt the tool to the agent" principle —
+ * fewer tools = fewer mis-picks, and presence itself steers):
+ * - `codegraph_impact` appears in ZERO recorded eval runs ever — its
+ *   blast-radius info already arrives inline on explore (the "Blast radius"
+ *   section) and node (the dependents note), so agents never need the
+ *   standalone tool.
+ * - `codegraph_callees` is redundant by construction: a symbol's body (which
+ *   node returns) IS its callee list, plus the caller/callee trail.
+ * - `codegraph_files` / `codegraph_status`: the tiny-repo audit (see
+ *   getTools) found they "reduce to one grep"; staleness banners already
+ *   inline the pending-sync info on every read tool, and the CLI covers
+ *   diagnostics.
+ * - `codegraph_callers` stays: exhaustive call-site enumeration (every
+ *   caller with file:line, callback registrations labeled, one section per
+ *   same-named definition) is the one job explore/node don't replicate.
+ */
+const DEFAULT_MCP_TOOLS = new Set(['explore', 'node', 'search', 'callers']);
+
 /**
  * Tool handler that executes tools against a CodeGraph instance
  *
@@ -453,6 +649,20 @@ export class ToolHandler {
   // The directory the server last searched for a default project. Surfaced in
   // the "not initialized" error so users can see why detection missed.
   private defaultProjectHint: string | null = null;
+  // Per-start-path cache of the git worktree/index mismatch (issue #155). The
+  // mismatch is a fixed property of (where the request came from → which
+  // .codegraph/ it resolves to), so the up-to-two `git rev-parse` spawns run
+  // once and every later tool call reuses the result — never shelling out to
+  // git on the hot path. `undefined` = not computed yet; `null` = no mismatch.
+  private worktreeMismatchCache: Map<string, WorktreeIndexMismatch | null> = new Map();
+  // Gate that the MCP engine pokes after `cg.open()` so the first tool call
+  // blocks on the post-open filesystem reconcile (catch-up sync). Without
+  // this, a tool call that races past `catchUpSync()` serves rows for files
+  // that were deleted (or edited) while no MCP server was running — and the
+  // per-file staleness banner can't help, because `getPendingFiles()` is
+  // populated by the watcher, not by catch-up. Cleared on first await so
+  // subsequent calls don't pay any cost.
+  private catchUpGate: Promise<void> | null = null;
 
   constructor(private cg: CodeGraph | null) {}
 
@@ -463,6 +673,17 @@ export class ToolHandler {
     this.cg = cg;
   }
 
+  /**
+   * Engine-only: register the catch-up sync promise so the next `execute()`
+   * call awaits it before serving. The handler swallows rejections (the
+   * engine logs them) so a sync failure never propagates as a tool error;
+   * we still want to serve a best-effort result over the same potentially-
+   * stale data, which is what would have happened without the gate.
+   */
+  setCatchUpGate(p: Promise<void> | null): void {
+    this.catchUpGate = p;
+  }
+
   /**
    * Record the directory the server tried to resolve the default project from.
    * Used only to make the "no default project" error actionable.
@@ -478,19 +699,82 @@ export class ToolHandler {
     return this.cg !== null;
   }
 
+  /**
+   * Optional allowlist of exposed tools, parsed from the CODEGRAPH_MCP_TOOLS
+   * env var (comma-separated short names, e.g. "trace,search,node,context").
+   * Unset/empty → every tool is exposed. Lets an operator (or an A/B harness)
+   * trim the tool surface without rebuilding the client config; the ablated
+   * tool is then truly absent from ListTools rather than merely denied on call.
+   * Matching is on the short form, so "node" and "codegraph_node" both work.
+   */
+  private toolAllowlist(): Set<string> | null {
+    const raw = process.env.CODEGRAPH_MCP_TOOLS;
+    if (!raw || !raw.trim()) return null;
+    const short = (s: string) => s.trim().replace(/^codegraph_/, '');
+    const set = new Set(raw.split(',').map(short).filter(Boolean));
+    return set.size ? set : null;
+  }
+
+  /** Whether a tool name passes the CODEGRAPH_MCP_TOOLS allowlist (if any). */
+  private isToolAllowed(name: string): boolean {
+    const allow = this.toolAllowlist();
+    return !allow || allow.has(name.replace(/^codegraph_/, ''));
+  }
+
   /**
    * Get tool definitions with dynamic descriptions based on project size.
    * The codegraph_explore tool description includes a budget recommendation
-   * scaled to the number of indexed files.
+   * scaled to the number of indexed files. Honors the CODEGRAPH_MCP_TOOLS
+   * allowlist so a trimmed surface is reflected in ListTools.
    */
   getTools(): ToolDefinition[] {
-    if (!this.cg) return tools;
+    const allow = this.toolAllowlist();
+    // No explicit allowlist → the default 4-tool surface (see
+    // DEFAULT_MCP_TOOLS for the evidence). An allowlist replaces the
+    // default entirely, so any defined tool can be re-enabled.
+    let visible = allow
+      ? tools.filter(t => allow.has(t.name.replace(/^codegraph_/, '')))
+      : tools.filter(t => DEFAULT_MCP_TOOLS.has(t.name.replace(/^codegraph_/, '')));
+    if (!this.cg) return visible;
 
     try {
       const stats = this.cg.getStats();
       const budget = getExploreBudget(stats.fileCount);
 
-      return tools.map(tool => {
+      // Tiny-repo tool gating: on projects under TINY_REPO_FILE_THRESHOLD
+      // files, only expose the core trio (search, node, explore) — one
+      // below even the 4-tool default: at this scale callers, too, reduces
+      // to one grep. (Historical note: the audit below ran when context and
+      // trace still existed; its "5 core tools" are today's trio.)
+      //
+      // n=2 audits ruled out cutting below 5 tools:
+      // - 3-tool gate (search + context + trace): cost regressed on
+      //   cobra/ky/sinatra. The agent fell back to raw Reads to cover
+      //   what codegraph_node + codegraph_explore would have answered.
+      // - 1-tool gate (search only): catastrophic regression — express
+      //   went from -43% WIN to +107% LOSS. With only search, the agent
+      //   can't navigate the call graph structurally and reads everything.
+      //
+      // 5 is the empirical lower bound. Tools beyond search/context/
+      // node/explore/trace pay overhead that the agent doesn't recoup
+      // on tiny-repo flow questions.
+      // ITER4: raise threshold 150 → 500 so single-file frameworks
+      // (sinatra at 159, slim_framework around 200) also get the
+      // 5-tool surface. The empirical 5-tool floor was set on <150
+      // probes; iter3 measurement showed sinatra is structurally the
+      // SAME problem as cobra (single-file WITHOUT-arm Read wins),
+      // so it deserves the same gating.
+      const TINY_REPO_FILE_THRESHOLD = 500;
+      const TINY_REPO_CORE_TOOLS = new Set([
+        'codegraph_explore',
+        'codegraph_search',
+        'codegraph_node',
+      ]);
+      if (stats.fileCount < TINY_REPO_FILE_THRESHOLD) {
+        visible = visible.filter(t => TINY_REPO_CORE_TOOLS.has(t.name));
+      }
+
+      return visible.map(tool => {
         if (tool.name === 'codegraph_explore') {
           return {
             ...tool,
@@ -500,7 +784,7 @@ export class ToolHandler {
         return tool;
       });
     } catch {
-      return tools;
+      return visible;
     }
   }
 
@@ -517,14 +801,16 @@ export class ToolHandler {
     if (!projectPath) {
       if (!this.cg) {
         const searched = this.defaultProjectHint ?? process.cwd();
-        throw new Error(
+        throw new NotIndexedError(
           'No CodeGraph project is loaded for this session.\n' +
           `Searched for a .codegraph/ directory starting from: ${searched}\n` +
-          'The index is likely fine — this is a working-directory detection issue: ' +
+          'If this project IS indexed, this is a working-directory detection issue: ' +
           "the MCP client launched the server outside your project and didn't report the " +
           'workspace root. Fix it either way:\n' +
           '  • Pass projectPath to the tool call, e.g. projectPath: "/absolute/path/to/your/project"\n' +
-          '  • Or add --path to the server\'s MCP config args: ["serve", "--mcp", "--path", "/absolute/path/to/your/project"]'
+          '  • Or add --path to the server\'s MCP config args: ["serve", "--mcp", "--path", "/absolute/path/to/your/project"]\n' +
+          'If the project simply has no index, continue with your built-in tools (Read/Grep/Glob) ' +
+          "and don't call codegraph again this session — the user can run 'codegraph init' to enable it."
         );
       }
       return this.cg;
@@ -535,11 +821,39 @@ export class ToolHandler {
       return this.projectCache.get(projectPath)!;
     }
 
+    // Reject sensitive system directories before opening. Only validate a
+    // path that actually exists — a nested or not-yet-created sub-path of a
+    // real project must still be allowed to resolve UP to its .codegraph/
+    // root below (issue #238), so we don't run the existence-checking
+    // validator on paths that are meant to walk up.
+    if (existsSync(projectPath)) {
+      const pathError = validateProjectPath(projectPath);
+      if (pathError) {
+        throw new PathRefusalError(pathError);
+      }
+    }
+
     // Walk up parent directories to find nearest .codegraph/
     const resolvedRoot = findNearestCodeGraphRoot(projectPath);
 
     if (!resolvedRoot) {
-      throw new Error(`CodeGraph not initialized in ${projectPath}. Run 'codegraph init' in that project first.`);
+      throw new NotIndexedError(
+        `The project at ${projectPath} isn't indexed with codegraph (no .codegraph/ directory found ` +
+        'walking up from it), so codegraph cannot query it. Use your built-in tools (Read/Grep/Glob) ' +
+        "for that codebase instead, and don't call codegraph for it again this session. " +
+        "Indexing is the user's decision — they can run 'codegraph init' in that project to enable it."
+      );
+    }
+
+    // If the path resolves to the default project, reuse the already-open
+    // default instance rather than opening a SECOND connection to the same DB.
+    // A duplicate connection serializes reads against the watcher's auto-sync
+    // writes; on the wasm backend (no WAL) that surfaces as intermittent
+    // "database is locked" on concurrent tool calls. See issue #238. Deliberately
+    // not cached under projectPath — the server owns and closes the default
+    // instance, so routing it through projectCache.closeAll() would double-close it.
+    if (this.cg && this.cg.getProjectRoot() === resolvedRoot) {
+      return this.cg;
     }
 
     // Check if we already have this resolved root cached (different path, same project)
@@ -551,7 +865,7 @@ export class ToolHandler {
     }
 
     // Open and cache under both paths
-    const cg = CodeGraph.openSync(resolvedRoot);
+    const cg = loadCodeGraph().openSync(resolvedRoot);
     this.projectCache.set(resolvedRoot, cg);
     if (projectPath !== resolvedRoot) {
       this.projectCache.set(projectPath, cg);
@@ -567,47 +881,265 @@ export class ToolHandler {
       cg.close();
     }
     this.projectCache.clear();
+    this.worktreeMismatchCache.clear();
   }
 
   /**
-   * Validate that a value is a non-empty string
+   * Validate that a value is a non-empty string within length bounds.
+   *
+   * The `maxLength` cap protects against MCP clients that ship huge
+   * payloads (10MB+ query strings either by accident or maliciously).
+   * Without this, a single oversized input can pin the FTS5 index or
+   * exhaust memory before any real work runs.
    */
-  private validateString(value: unknown, name: string): string | ToolResult {
+  private validateString(
+    value: unknown,
+    name: string,
+    maxLength: number = MAX_INPUT_LENGTH
+  ): string | ToolResult {
     if (typeof value !== 'string' || value.length === 0) {
       return this.errorResult(`${name} must be a non-empty string`);
     }
+    if (value.length > maxLength) {
+      return this.errorResult(
+        `${name} exceeds maximum length of ${maxLength} characters (got ${value.length})`
+      );
+    }
     return value;
   }
 
+  /**
+   * Validate an optional path-like string input. Returns the value if
+   * valid (or undefined), or a ToolResult with the error.
+   */
+  private validateOptionalPath(
+    value: unknown,
+    name: string
+  ): string | undefined | ToolResult {
+    if (value === undefined || value === null) return undefined;
+    if (typeof value !== 'string') {
+      return this.errorResult(`${name} must be a string`);
+    }
+    if (value.length > MAX_PATH_LENGTH) {
+      return this.errorResult(
+        `${name} exceeds maximum length of ${MAX_PATH_LENGTH} characters (got ${value.length})`
+      );
+    }
+    return value;
+  }
+
+  /**
+   * Cached git worktree/index mismatch for a tool call's effective project.
+   *
+   * The "effective project" is what the request targets: an explicit
+   * `projectPath` arg, else the directory the server resolved its default
+   * project from (`defaultProjectHint`), else cwd. Memoized per start path —
+   * see `worktreeMismatchCache`. Best-effort: if the project can't be resolved
+   * (e.g. nothing initialized yet), it reports "no mismatch" so a tool is never
+   * broken by this check.
+   */
+  private worktreeMismatchFor(projectPath?: string): WorktreeIndexMismatch | null {
+    const startPath = projectPath ?? this.defaultProjectHint ?? process.cwd();
+    const cached = this.worktreeMismatchCache.get(startPath);
+    if (cached !== undefined) return cached;
+
+    let mismatch: WorktreeIndexMismatch | null = null;
+    try {
+      mismatch = detectWorktreeIndexMismatch(startPath, this.getCodeGraph(projectPath).getProjectRoot());
+    } catch {
+      // No resolvable project (or any other resolution error) → nothing to warn.
+      mismatch = null;
+    }
+    this.worktreeMismatchCache.set(startPath, mismatch);
+    return mismatch;
+  }
+
+  /**
+   * Prefix a successful read-tool result with a compact worktree-mismatch
+   * notice when the resolved index belongs to a different git working tree than
+   * the caller's (issue #155). Without this, an agent in a nested worktree
+   * silently trusts main-branch results. No-op on error results and when there
+   * is no mismatch. `codegraph_status` is excluded — it embeds its own verbose
+   * warning — so it stays out of this path.
+   */
+  private withWorktreeNotice(result: ToolResult, projectPath?: string): ToolResult {
+    if (result.isError) return result;
+    const mismatch = this.worktreeMismatchFor(projectPath);
+    if (!mismatch) return result;
+
+    const notice = worktreeMismatchNotice(mismatch);
+    const [first, ...rest] = result.content;
+    if (first && first.type === 'text') {
+      return { ...result, content: [{ type: 'text', text: `${notice}\n\n${first.text}` }, ...rest] };
+    }
+    return result;
+  }
+
+  /**
+   * Annotate a successful read-tool result with per-file staleness — the
+   * non-blocking answer to issue #403. The file watcher tracks every event
+   * it sees per path; here we intersect "files referenced in this response"
+   * against that pending set and prepend a compact banner so the agent can
+   * fall back to Read for those *specific* files without waiting for the
+   * debounced sync to fire. Other pending files in the project (not
+   * referenced by this response) get a small footer so the agent has a
+   * complete picture without bloating the banner.
+   *
+   * Cost when nothing is pending — the common case — is one boolean check.
+   * No I/O, no parsing of markdown beyond a per-pending-file substring scan.
+   */
+  private withStalenessNotice(result: ToolResult, projectPath?: string): ToolResult {
+    if (result.isError) return result;
+
+    let cg: CodeGraph;
+    try {
+      cg = this.getCodeGraph(projectPath);
+    } catch {
+      return result; // no default project — leave as is
+    }
+
+    // Cross-project `projectPath` calls open a cached CodeGraph WITHOUT a
+    // watcher (watchers are only attached to the default session project).
+    // When the cross-project path happens to be the same project as the
+    // default cg, the cached instance is the wrong one — its pendingFiles is
+    // permanently empty. Detect the equal-path case and prefer the default
+    // cg so the staleness signal still fires when an agent passes the
+    // explicit projectPath form of its own project.
+    if (this.cg && cg !== this.cg) {
+      try {
+        const sameProject =
+          resolvePath(this.cg.getProjectRoot()) === resolvePath(cg.getProjectRoot());
+        if (sameProject) cg = this.cg;
+      } catch {
+        /* getProjectRoot may throw on a closed instance — leave cg as is */
+      }
+    }
+
+    // Defensive: some test fakes inject a partial CodeGraph stub without the
+    // newer pending-files API. Treat missing/throwing as "no pending files."
+    let pending: PendingFile[] = [];
+    try {
+      pending = cg.getPendingFiles?.() ?? [];
+    } catch {
+      return result;
+    }
+    if (pending.length === 0) return result;
+
+    const [first, ...rest] = result.content;
+    if (!first || first.type !== 'text') return result;
+
+    const text = first.text;
+    const inResponse: PendingFile[] = [];
+    const elsewhere: PendingFile[] = [];
+    for (const p of pending) {
+      // Substring match against the project-relative POSIX path — that's
+      // exactly the format both the watcher and every codegraph response
+      // emit, so a plain includes() is sufficient and avoids regex pitfalls.
+      if (text.includes(p.path)) inResponse.push(p);
+      else elsewhere.push(p);
+    }
+
+    let banner = '';
+    if (inResponse.length > 0) {
+      banner = formatStaleBanner(inResponse);
+    }
+    let footer = '';
+    if (elsewhere.length > 0) {
+      footer = formatStaleFooter(elsewhere);
+    }
+    if (!banner && !footer) return result;
+
+    const composed = [banner, text, footer].filter(Boolean).join('\n\n');
+    return { ...result, content: [{ type: 'text', text: composed }, ...rest] };
+  }
+
   /**
    * Execute a tool by name
    */
   async execute(toolName: string, args: Record<string, unknown>): Promise<ToolResult> {
     try {
+      // Block the first tool call on the engine's post-open reconcile so we
+      // never serve rows for files deleted/edited while no MCP server was
+      // running. The gate is cleared after first await — subsequent calls
+      // pay nothing. Catch-up failures are logged by the engine; we
+      // proceed regardless so a transient sync error never breaks tools.
+      if (this.catchUpGate) {
+        const gate = this.catchUpGate;
+        this.catchUpGate = null;
+        try { await gate; } catch { /* engine already logged */ }
+      }
+      // Honor the optional tool allowlist (CODEGRAPH_MCP_TOOLS): a trimmed
+      // surface rejects ablated tools defensively even if a client cached them.
+      if (!this.isToolAllowed(toolName)) {
+        return this.errorResult(`Tool ${toolName} is disabled via CODEGRAPH_MCP_TOOLS`);
+      }
+      // Cross-cutting input validation. All tools accept an optional
+      // `projectPath` and most accept either `query`, `task`, or
+      // `symbol` — bound their lengths centrally so individual handlers
+      // can stay focused on tool-specific logic.
+      const pathCheck = this.validateOptionalPath(args.projectPath, 'projectPath');
+      if (typeof pathCheck === 'object' && pathCheck !== undefined) {
+        return pathCheck;
+      }
+      // The `path` and `pattern` properties used by codegraph_files are
+      // also path-shaped — apply the same cap.
+      if (args.path !== undefined) {
+        const check = this.validateOptionalPath(args.path, 'path');
+        if (typeof check === 'object' && check !== undefined) return check;
+      }
+      if (args.pattern !== undefined) {
+        const check = this.validateOptionalPath(args.pattern, 'pattern');
+        if (typeof check === 'object' && check !== undefined) return check;
+      }
+
+      // Read tools resolve through a single result variable so cross-cutting
+      // notices — worktree-index mismatch (issue #155) and per-file
+      // staleness (issue #403) — can be applied in one place. status embeds
+      // its own verbose worktree warning but still flows through the
+      // staleness wrapper so its pending-files section stays consistent
+      // with what the read tools surface.
+      let result: ToolResult;
       switch (toolName) {
         case 'codegraph_search':
-          return await this.handleSearch(args);
-        case 'codegraph_context':
-          return await this.handleContext(args);
+          result = await this.handleSearch(args); break;
         case 'codegraph_callers':
-          return await this.handleCallers(args);
+          result = await this.handleCallers(args); break;
         case 'codegraph_callees':
-          return await this.handleCallees(args);
+          result = await this.handleCallees(args); break;
         case 'codegraph_impact':
-          return await this.handleImpact(args);
+          result = await this.handleImpact(args); break;
         case 'codegraph_explore':
-          return await this.handleExplore(args);
+          result = await this.handleExplore(args); break;
         case 'codegraph_node':
-          return await this.handleNode(args);
+          result = await this.handleNode(args); break;
         case 'codegraph_status':
+          // status embeds the pending-files list as a first-class section
+          // (see handleStatus), so we skip the auto-banner wrapper here to
+          // avoid duplicating the same info at the top of the response.
           return await this.handleStatus(args);
         case 'codegraph_files':
-          return await this.handleFiles(args);
+          result = await this.handleFiles(args); break;
         default:
           return this.errorResult(`Unknown tool: ${toolName}`);
       }
+      const withWorktree = this.withWorktreeNotice(result, args.projectPath as string | undefined);
+      return this.withStalenessNotice(withWorktree, args.projectPath as string | undefined);
     } catch (err) {
-      return this.errorResult(`Tool execution failed: ${err instanceof Error ? err.message : String(err)}`);
+      // Expected condition, not a malfunction: answer as a SUCCESS so the
+      // agent keeps trusting the toolset for projects that ARE indexed.
+      // (An isError here teaches session-long abandonment — see NotIndexedError.)
+      if (err instanceof NotIndexedError) {
+        return this.textResult(err.message);
+      }
+      // Security refusal: a clean error, no retry encouragement.
+      if (err instanceof PathRefusalError) {
+        return this.errorResult(err.message);
+      }
+      return this.errorResult(
+        `Tool execution failed: ${err instanceof Error ? err.message : String(err)}. ` +
+        'This is an internal codegraph error — retry the call once; if it persists, ' +
+        'continue without codegraph for this task.'
+      );
     }
   }
 
@@ -619,7 +1151,11 @@ export class ToolHandler {
     if (typeof query !== 'string') return query;
 
     const cg = this.getCodeGraph(args.projectPath as string | undefined);
-    const kind = args.kind as string | undefined;
+    const rawKind = args.kind as string | undefined;
+    // The schema enum says 'type' (what agents naturally reach for); the
+    // NodeKind is 'type_alias'. Without the mapping, kind: "type" silently
+    // matched nothing — a filter value we advertise must work.
+    const kind = rawKind === 'type' ? 'type_alias' : rawKind;
     const rawLimit = Number(args.limit) || 10;
     const limit = clamp(rawLimit, 1, 100);
 
@@ -632,74 +1168,58 @@ export class ToolHandler {
       return this.textResult(`No results found for "${query}"`);
     }
 
-    const formatted = this.formatSearchResults(results);
+    // Down-rank generated files within the FTS-returned set so a search
+    // for "Send" surfaces the hand-written keeper before .pb.go stubs
+    // that share the name. Stable: only reorders generated vs. not.
+    const ranked = [...results].sort((a, b) => {
+      const aGen = isGeneratedFile(a.node.filePath) ? 1 : 0;
+      const bGen = isGeneratedFile(b.node.filePath) ? 1 : 0;
+      return aGen - bGen;
+    });
+
+    const formatted = this.formatSearchResults(ranked);
     return this.textResult(this.truncateOutput(formatted));
   }
 
   /**
-   * Handle codegraph_context
+   * Group symbol matches into DISTINCT DEFINITIONS — one group per
+   * (filePath, qualifiedName), so same-file overloads stay together while
+   * unrelated same-named classes across a monorepo's apps (#764: one
+   * `UserService` per NestJS app) are kept apart. Optionally narrowed by a
+   * `file` path/suffix first.
    */
-  private async handleContext(args: Record<string, unknown>): Promise<ToolResult> {
-    const task = this.validateString(args.task, 'task');
-    if (typeof task !== 'string') return task;
-
-    // Mark session as consulted (enables Grep/Glob/Bash)
-    const sessionId = process.env.CLAUDE_SESSION_ID;
-    if (sessionId) {
-      markSessionConsulted(sessionId);
+  private groupDefinitions(
+    nodes: Node[],
+    fileFilter: string | undefined
+  ): { groups: Node[][]; filteredOut: boolean } {
+    let pool = nodes;
+    let filteredOut = false;
+    if (fileFilter) {
+      const wanted = fileFilter.replace(/^\.\//, '');
+      const narrowed = pool.filter(
+        (n) => n.filePath === wanted || n.filePath.endsWith(wanted) || n.filePath.endsWith(`/${wanted}`)
+      );
+      if (narrowed.length > 0) {
+        pool = narrowed;
+      } else {
+        filteredOut = true;
+      }
     }
-
-    const cg = this.getCodeGraph(args.projectPath as string | undefined);
-    const maxNodes = (args.maxNodes as number) || 20;
-    const includeCode = args.includeCode !== false;
-
-    const context = await cg.buildContext(task, {
-      maxNodes,
-      includeCode,
-      format: 'markdown',
-    });
-
-    // Detect if this looks like a feature request (vs bug fix or exploration)
-    const isFeatureQuery = this.looksLikeFeatureRequest(task);
-    const reminder = isFeatureQuery
-      ? '\n\n⚠️ **Ask user:** UX preferences, edge cases, acceptance criteria'
-      : '';
-
-    // buildContext returns string when format is 'markdown'
-    if (typeof context === 'string') {
-      return this.textResult(context + reminder);
+    const byDef = new Map<string, Node[]>();
+    for (const n of pool) {
+      const key = `${n.filePath}|${n.qualifiedName}`;
+      const group = byDef.get(key);
+      if (group) group.push(n);
+      else byDef.set(key, [n]);
     }
-
-    // If it returns TaskContext, format it
-    return this.textResult(this.formatTaskContext(context) + reminder);
+    return { groups: [...byDef.values()], filteredOut };
   }
 
-  /**
-   * Heuristic to detect if a query looks like a feature request
-   */
-  private looksLikeFeatureRequest(task: string): boolean {
-    const featureKeywords = [
-      'add', 'create', 'implement', 'build', 'enable', 'allow',
-      'new feature', 'support for', 'ability to', 'want to',
-      'should be able', 'need to add', 'swap', 'edit', 'modify'
-    ];
-    const bugKeywords = [
-      'fix', 'bug', 'error', 'broken', 'crash', 'issue', 'problem',
-      'not working', 'fails', 'undefined', 'null'
-    ];
-    const explorationKeywords = [
-      'how does', 'where is', 'what is', 'find', 'show me',
-      'explain', 'understand', 'explore'
-    ];
-
-    const lowerTask = task.toLowerCase();
-
-    // If it's clearly a bug or exploration, not a feature
-    if (bugKeywords.some(k => lowerTask.includes(k))) return false;
-    if (explorationKeywords.some(k => lowerTask.includes(k))) return false;
-
-    // If it matches feature keywords, it's likely a feature request
-    return featureKeywords.some(k => lowerTask.includes(k));
+  /** Section heading for one distinct definition in grouped output. */
+  private definitionHeading(group: Node[]): string {
+    const head = group[0]!;
+    const line = head.startLine ? `:${head.startLine}` : '';
+    return `### ${head.qualifiedName} (${head.kind}) — ${head.filePath}${line}`;
   }
 
   /**
@@ -711,30 +1231,68 @@ export class ToolHandler {
 
     const cg = this.getCodeGraph(args.projectPath as string | undefined);
     const limit = clamp((args.limit as number) || 20, 1, 100);
+    const fileFilter = typeof args.file === 'string' ? args.file : undefined;
 
     const allMatches = this.findAllSymbols(cg, symbol);
     if (allMatches.nodes.length === 0) {
       return this.textResult(`Symbol "${symbol}" not found in the codebase`);
     }
 
-    // Aggregate callers across all matching symbols
-    const seen = new Set<string>();
-    const allCallers: Node[] = [];
-    for (const node of allMatches.nodes) {
-      for (const c of cg.getCallers(node.id)) {
-        if (!seen.has(c.node.id)) {
-          seen.add(c.node.id);
-          allCallers.push(c.node);
+    const { groups, filteredOut } = this.groupDefinitions(allMatches.nodes, fileFilter);
+    const filterNote = filteredOut
+      ? `\n\n> **Note:** no definition of "${symbol}" matches file "${fileFilter}" — showing all definitions instead.`
+      : '';
+
+    const collect = (defNodes: Node[]) => {
+      const seen = new Set<string>();
+      const callers: Node[] = [];
+      const labels = new Map<string, string>();
+      for (const node of defNodes) {
+        for (const c of cg.getCallers(node.id)) {
+          if (!seen.has(c.node.id)) {
+            seen.add(c.node.id);
+            callers.push(c.node);
+            const label = this.edgeLabel(c.edge);
+            if (label) labels.set(c.node.id, label);
+          }
         }
       }
-    }
+      return { callers, labels };
+    };
 
-    if (allCallers.length === 0) {
-      return this.textResult(`No callers found for "${symbol}"${allMatches.note}`);
+    // Single definition (or same-file overloads): the familiar flat list.
+    if (groups.length === 1) {
+      const { callers, labels } = collect(groups[0]!);
+      if (callers.length === 0) {
+        return this.textResult(`No callers found for "${symbol}"${allMatches.note}${filterNote}`);
+      }
+      // A successful `file` narrowing makes the multi-symbol aggregation note
+      // stale — suppress it.
+      const note = fileFilter && !filteredOut ? '' : allMatches.note;
+      const formatted = this.formatNodeList(callers.slice(0, limit), `Callers of ${symbol}`, labels) + note + filterNote;
+      return this.textResult(this.truncateOutput(formatted));
     }
 
-    const formatted = this.formatNodeList(allCallers.slice(0, limit), `Callers of ${symbol}`) + allMatches.note;
-    return this.textResult(this.truncateOutput(formatted));
+    // Multiple DISTINCT definitions (#764): one section per definition so an
+    // agent never mistakes one app's callers for another's. Narrow with
+    // `file` to focus a single definition.
+    const lines: string[] = [
+      `## Callers of ${symbol} — ${groups.length} distinct definitions (narrow with \`file\`)`,
+    ];
+    for (const group of groups) {
+      const { callers, labels } = collect(group);
+      lines.push('', this.definitionHeading(group));
+      if (callers.length === 0) {
+        lines.push('- (no callers)');
+        continue;
+      }
+      for (const node of callers.slice(0, limit)) {
+        const location = node.startLine ? `:${node.startLine}` : '';
+        const label = labels.get(node.id);
+        lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}${label ? ` — via ${label}` : ''}`);
+      }
+    }
+    return this.textResult(this.truncateOutput(lines.join('\n') + filterNote));
   }
 
   /**
@@ -746,30 +1304,65 @@ export class ToolHandler {
 
     const cg = this.getCodeGraph(args.projectPath as string | undefined);
     const limit = clamp((args.limit as number) || 20, 1, 100);
+    const fileFilter = typeof args.file === 'string' ? args.file : undefined;
 
     const allMatches = this.findAllSymbols(cg, symbol);
     if (allMatches.nodes.length === 0) {
       return this.textResult(`Symbol "${symbol}" not found in the codebase`);
     }
 
-    // Aggregate callees across all matching symbols
-    const seen = new Set<string>();
-    const allCallees: Node[] = [];
-    for (const node of allMatches.nodes) {
-      for (const c of cg.getCallees(node.id)) {
-        if (!seen.has(c.node.id)) {
-          seen.add(c.node.id);
-          allCallees.push(c.node);
+    const { groups, filteredOut } = this.groupDefinitions(allMatches.nodes, fileFilter);
+    const filterNote = filteredOut
+      ? `\n\n> **Note:** no definition of "${symbol}" matches file "${fileFilter}" — showing all definitions instead.`
+      : '';
+
+    const collect = (defNodes: Node[]) => {
+      const seen = new Set<string>();
+      const callees: Node[] = [];
+      const labels = new Map<string, string>();
+      for (const node of defNodes) {
+        for (const c of cg.getCallees(node.id)) {
+          if (!seen.has(c.node.id)) {
+            seen.add(c.node.id);
+            callees.push(c.node);
+            const label = this.edgeLabel(c.edge);
+            if (label) labels.set(c.node.id, label);
+          }
         }
       }
-    }
+      return { callees, labels };
+    };
 
-    if (allCallees.length === 0) {
-      return this.textResult(`No callees found for "${symbol}"${allMatches.note}`);
+    if (groups.length === 1) {
+      const { callees, labels } = collect(groups[0]!);
+      if (callees.length === 0) {
+        return this.textResult(`No callees found for "${symbol}"${allMatches.note}${filterNote}`);
+      }
+      // A successful `file` narrowing makes the multi-symbol aggregation note
+      // stale — suppress it.
+      const note = fileFilter && !filteredOut ? '' : allMatches.note;
+      const formatted = this.formatNodeList(callees.slice(0, limit), `Callees of ${symbol}`, labels) + note + filterNote;
+      return this.textResult(this.truncateOutput(formatted));
     }
 
-    const formatted = this.formatNodeList(allCallees.slice(0, limit), `Callees of ${symbol}`) + allMatches.note;
-    return this.textResult(this.truncateOutput(formatted));
+    // Multiple DISTINCT definitions (#764): per-definition sections.
+    const lines: string[] = [
+      `## Callees of ${symbol} — ${groups.length} distinct definitions (narrow with \`file\`)`,
+    ];
+    for (const group of groups) {
+      const { callees, labels } = collect(group);
+      lines.push('', this.definitionHeading(group));
+      if (callees.length === 0) {
+        lines.push('- (no callees)');
+        continue;
+      }
+      for (const node of callees.slice(0, limit)) {
+        const location = node.startLine ? `:${node.startLine}` : '';
+        const label = labels.get(node.id);
+        lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}${label ? ` — via ${label}` : ''}`);
+      }
+    }
+    return this.textResult(this.truncateOutput(lines.join('\n') + filterNote));
   }
 
   /**
@@ -781,39 +1374,411 @@ export class ToolHandler {
 
     const cg = this.getCodeGraph(args.projectPath as string | undefined);
     const depth = clamp((args.depth as number) || 2, 1, 10);
+    const fileFilter = typeof args.file === 'string' ? args.file : undefined;
 
     const allMatches = this.findAllSymbols(cg, symbol);
     if (allMatches.nodes.length === 0) {
       return this.textResult(`Symbol "${symbol}" not found in the codebase`);
     }
 
-    // Aggregate impact across all matching symbols
-    const mergedNodes = new Map<string, Node>();
-    const mergedEdges: Edge[] = [];
-    const seenEdges = new Set<string>();
+    const { groups, filteredOut } = this.groupDefinitions(allMatches.nodes, fileFilter);
+    const filterNote = filteredOut
+      ? `\n\n> **Note:** no definition of "${symbol}" matches file "${fileFilter}" — showing all definitions instead.`
+      : '';
 
-    for (const node of allMatches.nodes) {
-      const impact = cg.getImpactRadius(node.id, depth);
-      for (const [id, n] of impact.nodes) {
-        mergedNodes.set(id, n);
+    const impactOf = (defNodes: Node[]) => {
+      const mergedNodes = new Map<string, Node>();
+      const mergedEdges: Edge[] = [];
+      const seenEdges = new Set<string>();
+      for (const node of defNodes) {
+        const impact = cg.getImpactRadius(node.id, depth);
+        for (const [id, n] of impact.nodes) {
+          mergedNodes.set(id, n);
+        }
+        for (const e of impact.edges) {
+          const key = `${e.source}->${e.target}:${e.kind}`;
+          if (!seenEdges.has(key)) {
+            seenEdges.add(key);
+            mergedEdges.push(e);
+          }
+        }
       }
-      for (const e of impact.edges) {
-        const key = `${e.source}->${e.target}:${e.kind}`;
-        if (!seenEdges.has(key)) {
-          seenEdges.add(key);
-          mergedEdges.push(e);
+      return { nodes: mergedNodes, edges: mergedEdges, roots: defNodes.map((n) => n.id) };
+    };
+
+    // Single definition (or same-file overloads): the familiar merged report.
+    if (groups.length === 1) {
+      const formatted = this.formatImpact(symbol, impactOf(groups[0]!)) + (fileFilter && !filteredOut ? "" : allMatches.note) + filterNote;
+      return this.textResult(this.truncateOutput(formatted));
+    }
+
+    // Multiple DISTINCT definitions (#764): a blast radius PER definition —
+    // merging unrelated same-named classes (one UserService per monorepo app)
+    // overstated impact and confused agents. Narrow with `file`.
+    const sections: string[] = [
+      `## Impact of ${symbol} — ${groups.length} distinct definitions (each with its own blast radius; narrow with \`file\`)`,
+    ];
+    for (const group of groups) {
+      const head = group[0]!;
+      const line = head.startLine ? `:${head.startLine}` : '';
+      sections.push(
+        '',
+        this.formatImpact(`${head.qualifiedName} (${head.filePath}${line})`, impactOf(group))
+      );
+    }
+    return this.textResult(this.truncateOutput(sections.join('\n') + filterNote));
+  }
+
+  /**
+   * Describe a synthesized (dynamic-dispatch) edge for human output: how the
+   * callback was wired up — the bridge static parsing can't see. Returns null
+   * for ordinary static edges. Used by trace + the node trail so a synthesized
+   * hop reads as "registered via onUpdate at App.tsx:3148", not a bare arrow.
+   */
+  private synthEdgeNote(edge: Edge | null): { label: string; compact: string; registeredAt?: string } | null {
+    if (!edge || edge.provenance !== 'heuristic') return null;
+    const m = edge.metadata as Record<string, unknown> | undefined;
+    const registeredAt = typeof m?.registeredAt === 'string' ? m.registeredAt : undefined;
+    const at = registeredAt ? ` @${registeredAt}` : '';
+    if (m?.synthesizedBy === 'callback') {
+      const via = m.via ? `\`${String(m.via)}\`` : 'a registrar';
+      const field = m.field ? ` on .${String(m.field)}` : '';
+      return {
+        label: `callback — registered via ${via}${field} (dynamic dispatch)`,
+        compact: `dynamic: callback via ${via}${at}`,
+        registeredAt,
+      };
+    }
+    if (m?.synthesizedBy === 'event-emitter') {
+      const ev = m.event ? `\`${String(m.event)}\`` : 'an event';
+      return {
+        label: `event ${ev} — emit → handler (dynamic dispatch)`,
+        compact: `dynamic: event ${ev}${at}`,
+        registeredAt,
+      };
+    }
+    if (m?.synthesizedBy === 'react-render') {
+      return {
+        label: `React re-render — \`setState\` re-runs render() (dynamic dispatch)`,
+        compact: `dynamic: React re-render via setState${at}`,
+        registeredAt,
+      };
+    }
+    if (m?.synthesizedBy === 'jsx-render') {
+      const child = m.via ? `<${String(m.via)}>` : 'a child component';
+      return {
+        label: `renders ${child} (JSX child — dynamic dispatch)`,
+        compact: `dynamic: renders ${child}`,
+        registeredAt,
+      };
+    }
+    if (m?.synthesizedBy === 'vue-handler') {
+      const ev = m.event ? `@${String(m.event)}` : 'a template event';
+      return {
+        label: `Vue template handler — bound to ${ev} (dynamic dispatch)`,
+        compact: `dynamic: Vue ${ev} handler`,
+        registeredAt,
+      };
+    }
+    if (m?.synthesizedBy === 'interface-impl') {
+      return {
+        label: `interface/abstract dispatch — runs the implementation override (dynamic dispatch)`,
+        compact: `dynamic: interface → impl${at}`,
+        registeredAt,
+      };
+    }
+    if (m?.synthesizedBy === 'closure-collection') {
+      const field = m.field ? `\`${String(m.field)}\`` : 'a collection';
+      return {
+        label: `closure collection — runs handlers appended to ${field} (dynamic dispatch)`,
+        compact: `dynamic: runs ${field} handlers${at}`,
+        registeredAt,
+      };
+    }
+    return null;
+  }
+
+  /**
+   * Flow-from-named-symbols: an agent's codegraph_explore query is a bag of
+   * symbol names that usually spans the flow it's investigating (e.g.
+   * "PmsProductController getList PmsProductService list PmsProductServiceImpl").
+   * Surface the longest call chain AMONG those named symbols — scoped to what the
+   * agent explicitly named, so (unlike a fuzzy relevance set) there's no
+   * wrong-feature wandering. Rides synthesized edges, so controller→service-
+   * interface→impl shows up. Returns '' if no chain of >=3 nodes exists.
+   *
+   * Ambiguous tokens (Java `list` → dozens of nodes) are disambiguated by
+   * CO-NAMING: the agent names the class too, so we keep only `list` candidates
+   * whose qualifiedName contains another named token (`PmsProductServiceImpl::list`),
+   * dropping unrelated `OmsOrderService::list`.
+   */
+  private buildFlowFromNamedSymbols(cg: CodeGraph, query: string): { text: string; pathNodeIds: Set<string>; namedNodeIds: Set<string>; uniqueNamedNodeIds: Set<string> } {
+    const EMPTY = { text: '', pathNodeIds: new Set<string>(), namedNodeIds: new Set<string>(), uniqueNamedNodeIds: new Set<string>() };
+    try {
+      const CALLABLE = new Set(['method', 'function', 'component', 'constructor']);
+      // Strip only a REAL file extension (Create.cs → Create); KEEP qualified
+      // names (Class.method / Class::method) — the agent's most precise input,
+      // resolved exactly by findAllSymbols. (The old strip mangled Class.method
+      // into Class, throwing the method away.)
+      const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte|astro)$/i;
+      const tokens = [...new Set(
+        query.split(/[\s,()[\]]+/)
+          .map((t) => t.replace(FILE_EXT, '').trim())
+          .filter((t) => t.length >= 3 && /^[A-Za-z_$][\w$]*(?:(?:::|\.)[\w$]+)*$/.test(t))
+      )].slice(0, 16);
+      if (tokens.length < 2) return EMPTY;
+      // Pool of name SEGMENTS (Class + method from every token) used to
+      // disambiguate an ambiguous SIMPLE name: keep a candidate only if its
+      // CONTAINER class is itself named in the query.
+      const segPool = new Set<string>();
+      for (const t of tokens) for (const s of t.toLowerCase().split(/::|\./)) if (s) segPool.add(s);
+      const named = new Map<string, Node>();
+      // Nodes whose token is SPECIFIC — a (near-)unique callable name (<=3 defs in
+      // the whole graph). These are safe to SPARE a file on: the agent named THIS
+      // method (`getResponseWithInterceptorChain`, 1 def). A hyper-polymorphic name
+      // (`as_sql`, 110 defs across every Expression/Compiler subclass) is NOT here,
+      // so naming it doesn't keep every backend variant full and flood the budget.
+      const uniqueNamedNodeIds = new Set<string>();
+      for (const t of tokens) {
+        const cands = this.findAllSymbols(cg, t).nodes.filter((n) => CALLABLE.has(n.kind));
+        // A qualified or otherwise-specific name (<=3 hits) keeps all; an
+        // ambiguous simple name keeps only candidates whose container is named.
+        const specific = cands.length <= 3;
+        const pick = specific
+          ? cands
+          : cands.filter((n) => {
+              const segs = (n.qualifiedName || '').toLowerCase().split(/::|\./).filter(Boolean);
+              const container = segs.length >= 2 ? segs[segs.length - 2] : '';
+              return !!container && segPool.has(container);
+            });
+        for (const n of pick.slice(0, 6)) {
+          named.set(n.id, n);
+          if (specific) uniqueNamedNodeIds.add(n.id);
+        }
+        if (named.size > 40) break;
+      }
+      if (named.size < 2) return EMPTY;
+      const MAX_HOPS = 7;
+      let best: Array<{ node: Node; edge: Edge | null }> | null = null;
+      // BFS the full call graph (incl. synth edges) from each named seed, but
+      // only ACCEPT a sink that is also named — both ends anchored to symbols the
+      // agent named, so the chain stays on-topic while bridging intermediates
+      // (e.g. the exact interface overload) that the token resolution missed.
+      for (const seed of [...named.values()].slice(0, 8)) {
+        const parent = new Map<string, { prev: string | null; edge: Edge | null; node: Node }>();
+        parent.set(seed.id, { prev: null, edge: null, node: seed });
+        const q: Array<{ id: string; depth: number; streak: number }> = [{ id: seed.id, depth: 0, streak: 0 }];
+        let deep: string | null = null, deepDepth = 0;
+        const MAX_BRIDGE = 1; // ≤1 consecutive UNNAMED hop: bridge one missing intermediate, never wander a god-function's fan-out
+        for (let h = 0; h < q.length && parent.size < 1500; h++) {
+          const { id, depth, streak } = q[h]!;
+          if (id !== seed.id && named.has(id) && depth > deepDepth) { deep = id; deepDepth = depth; }
+          if (depth >= MAX_HOPS - 1) continue;
+          for (const c of cg.getCallees(id)) {
+            if (c.edge.kind !== 'calls' || parent.has(c.node.id)) continue;
+            const newStreak = named.has(c.node.id) ? 0 : streak + 1;
+            if (newStreak > MAX_BRIDGE) continue;
+            parent.set(c.node.id, { prev: id, edge: c.edge, node: c.node });
+            q.push({ id: c.node.id, depth: depth + 1, streak: newStreak });
+          }
+        }
+        if (!deep) continue;
+        const chain: Array<{ node: Node; edge: Edge | null }> = [];
+        let cur: string | null = deep;
+        while (cur) { const p = parent.get(cur); if (!p) break; chain.push({ node: p.node, edge: p.edge }); cur = p.prev; }
+        chain.reverse();
+        if (!best || chain.length > best.length) best = chain;
+      }
+      const hasMain = !!best && best.length >= 3;
+      const pathIds = new Set((best ?? []).map((s) => s.node.id));
+
+      // Supplementary: dynamic-dispatch (synthesized) edges incident to a NAMED
+      // symbol — the indirect hops an agent would otherwise grep/Read to
+      // reconstruct ("where do the appended `validators` actually run?"). The
+      // synth edge IS that answer, so surface it even when the OTHER end wasn't
+      // named (e.g. the agent names `validate` but not the `didCompleteTask`
+      // that drains the collection). On-topic by construction: only heuristic
+      // edges touching a symbol the agent named; skipped when the hop already
+      // shows in the main chain.
+      const synthLines: string[] = [];
+      const synthSeen = new Set<string>();
+      for (const n of named.values()) {
+        if (synthLines.length >= 6) break;
+        for (const { node: other, edge } of [...cg.getCallers(n.id), ...cg.getCallees(n.id)]) {
+          if (synthLines.length >= 6) break;
+          if (edge.provenance !== 'heuristic' || other.id === n.id) continue;
+          if (pathIds.has(edge.source) && pathIds.has(edge.target)) continue; // already in the main chain
+          const src = edge.source === n.id ? n : other;
+          const tgt = edge.source === n.id ? other : n;
+          const key = `${src.name}>${tgt.name}`;
+          if (synthSeen.has(key)) continue;
+          synthSeen.add(key);
+          const note = this.synthEdgeNote(edge);
+          synthLines.push(`- ${src.name} → ${tgt.name}   [${note ? note.compact : edge.kind}]`);
+        }
+      }
+
+      if (!hasMain && synthLines.length === 0) return EMPTY;
+      const out: string[] = [];
+      if (hasMain) {
+        out.push('## Flow (call path among the symbols you queried)', '');
+        for (let i = 0; i < best!.length; i++) {
+          const step = best![i]!;
+          if (step.edge) { const sy = this.synthEdgeNote(step.edge); out.push(`   ↓ ${sy ? sy.compact : step.edge.kind}`); }
+          out.push(`${i + 1}. ${step.node.name} (${step.node.filePath}:${step.node.startLine})`);
         }
+        out.push('');
+      }
+      if (synthLines.length) {
+        out.push(
+          '## Dynamic-dispatch links among your symbols',
+          '(synthesized — the indirect hops grep/Read would reconstruct; the `@file:line` is the wiring site)',
+          '',
+          ...synthLines,
+          ''
+        );
       }
+      out.push('> Full source for these symbols is below — the call flow among them, followed by their bodies.', '');
+      // namedNodeIds = every callable the agent explicitly named (a superset of
+      // the spine). A file holding one is something the agent asked to SEE, so it
+      // must keep full source even if it's an off-spine polymorphic sibling — the
+      // agent named `getResponseWithInterceptorChain` / `SQLCompiler.execute_sql`
+      // as the mechanism, not as an interchangeable leaf. See the skeleton gate.
+      return { text: out.join('\n'), pathNodeIds: pathIds, namedNodeIds: new Set(named.keys()), uniqueNamedNodeIds };
+    } catch {
+      return EMPTY;
     }
+  }
 
-    const mergedImpact = {
-      nodes: mergedNodes,
-      edges: mergedEdges,
-      roots: allMatches.nodes.map(n => n.id),
-    };
+  /**
+   * Compact "blast radius" for the entry symbols of an explore result: who
+   * depends on each (callers) and which test files cover it — LOCATIONS ONLY,
+   * no source, so the agent knows what to update / re-verify before editing
+   * without reaching for a separate impact call. Always-on, but skips symbols
+   * that have no dependents (nothing to warn about), and returns '' when none
+   * qualify so a leaf-only exploration stays clean.
+   */
+  private buildBlastRadiusSection(cg: CodeGraph, subgraph: Subgraph): string {
+    const ROOT_CAP = 5; // only the symbols the query actually targeted
+    const FILE_CAP = 4; // caller files listed per symbol before "+N more"
+    const MEANINGFUL = new Set<string>([
+      'function', 'method', 'class', 'interface', 'struct', 'trait', 'protocol',
+      'enum', 'type_alias', 'component', 'constant', 'variable', 'property', 'field',
+    ]);
+    const rel = (p: string) => p.replace(/\\/g, '/');
+
+    const roots = subgraph.roots
+      .map((id) => subgraph.nodes.get(id))
+      .filter((n): n is Node => !!n && MEANINGFUL.has(n.kind))
+      .slice(0, ROOT_CAP);
+    if (roots.length === 0) return '';
+
+    const entries: string[] = [];
+    for (const root of roots) {
+      let callers: Array<{ node: Node }> = [];
+      try { callers = cg.getCallers(root.id) as Array<{ node: Node }>; } catch { /* skip this root */ }
+
+      const seen = new Set<string>();
+      const uniq: Node[] = [];
+      for (const c of callers) {
+        if (c?.node && !seen.has(c.node.id)) { seen.add(c.node.id); uniq.push(c.node); }
+      }
+      if (uniq.length === 0) continue; // no blast radius → nothing to flag
 
-    const formatted = this.formatImpact(symbol, mergedImpact) + allMatches.note;
-    return this.textResult(this.truncateOutput(formatted));
+      const callerFiles = [...new Set(uniq.map((n) => rel(n.filePath)))];
+      const testFiles = callerFiles.filter((f) => isTestFile(f));
+      const nonTest = callerFiles.filter((f) => !isTestFile(f));
+
+      const shown = nonTest.slice(0, FILE_CAP).map((f) => `\`${f}\``).join(', ');
+      const more = nonTest.length > FILE_CAP ? ` +${nonTest.length - FILE_CAP} more` : '';
+      const where = nonTest.length > 0 ? ` in ${shown}${more}` : '';
+      const tests = testFiles.length > 0
+        ? `; tests: ${testFiles.slice(0, FILE_CAP).map((f) => `\`${f}\``).join(', ')}${testFiles.length > FILE_CAP ? ` +${testFiles.length - FILE_CAP}` : ''}`
+        : '; ⚠️ no covering tests found';
+
+      entries.push(
+        `- \`${root.name}\` (${rel(root.filePath)}:${root.startLine}) — ${uniq.length} caller${uniq.length === 1 ? '' : 's'}${where}${tests}`,
+      );
+    }
+    if (entries.length === 0) return '';
+
+    return [
+      '### Blast radius — what depends on these (update/verify before editing)',
+      '',
+      ...entries,
+      '',
+    ].join('\n');
+  }
+
+  /**
+   * Graph-connectivity relevance via Random-Walk-with-Restart (personalized
+   * PageRank) from the query's matched SEED nodes over the call/reference graph.
+   *
+   * This is the ranking signal text search (FTS/bm25) CANNOT provide, and it's
+   * codegraph's home turf: relevance by STRUCTURE, not words. A file whose
+   * symbols are call-connected to the matched cluster accrues walk mass and
+   * ranks high; a lone TEXT match — e.g. `LensSwitcher.swift` matched the word
+   * "switch" from `switchOrganization`, but calls none of `setUser`/`fetchUser`
+   * — gets only its own restart probability and ranks ~0. Immune to the
+   * tokenization trap that fools term matching, deterministic, no embeddings.
+   *
+   * Undirected adjacency (reachability both ways), restart α=0.25 to the seeds,
+   * power iteration to convergence. Bounded to the already-relevant subgraph, so
+   * it's a few hundred nodes × ~25 iterations — negligible cost.
+   */
+  private computeGraphRelevance(
+    nodeIds: string[],
+    edges: Edge[],
+    seedIds: Set<string>,
+  ): Map<string, number> {
+    const out = new Map<string, number>();
+    const n = nodeIds.length;
+    if (n === 0) return out;
+    const idx = new Map<string, number>();
+    for (let i = 0; i < n; i++) idx.set(nodeIds[i]!, i);
+
+    const RANK_EDGES = new Set<string>([
+      'calls', 'references', 'extends', 'implements', 'overrides',
+      'instantiates', 'returns', 'type_of', 'imports',
+    ]);
+    const adj: number[][] = Array.from({ length: n }, () => []);
+    for (const e of edges) {
+      if (!RANK_EDGES.has(e.kind)) continue;
+      const i = idx.get(e.source);
+      const j = idx.get(e.target);
+      if (i === undefined || j === undefined || i === j) continue;
+      adj[i]!.push(j);
+      adj[j]!.push(i); // undirected — reachable either direction
+    }
+
+    // Restart vector: uniform over seeds present in the candidate set. (Falls
+    // back to uniform-over-all if no seed landed in the set, so we never return
+    // all-zero.)
+    const r = new Array<number>(n).fill(0);
+    let rsum = 0;
+    for (const id of seedIds) {
+      const i = idx.get(id);
+      if (i !== undefined) { r[i] = 1; rsum += 1; }
+    }
+    if (rsum === 0) { for (let i = 0; i < n; i++) r[i] = 1; rsum = n; }
+    for (let i = 0; i < n; i++) r[i]! /= rsum;
+
+    const alpha = 0.25;
+    let s = r.slice();
+    for (let iter = 0; iter < 25; iter++) {
+      const next = new Array<number>(n).fill(0);
+      for (let i = 0; i < n; i++) {
+        const si = s[i]!;
+        if (si === 0) continue;
+        const d = adj[i]!.length;
+        if (d === 0) { next[i]! += si; continue; } // dangling: keep its mass
+        const share = si / d;
+        for (const j of adj[i]!) next[j]! += share;
+      }
+      for (let i = 0; i < n; i++) s[i] = (1 - alpha) * next[i]! + alpha * r[i]!;
+    }
+    for (let i = 0; i < n; i++) out.set(nodeIds[i]!, s[i]!);
+    return out;
   }
 
   /**
@@ -860,9 +1825,114 @@ export class ToolHandler {
       return this.textResult(`No relevant code found for "${query}"`);
     }
 
+    // Graph-aware glue: findRelevantContext builds the subgraph from name/text
+    // search, so a method that BRIDGES named symbols — e.g. App.tsx's
+    // triggerRender, which calls the named triggerUpdate — is never a search hit
+    // and gets missed, forcing the agent to Read the file to trace it. Pull in
+    // the callers/callees of the entry (root) nodes, but ONLY those that live in
+    // files the subgraph already surfaces (where the agent reads to fill gaps),
+    // so we add wiring without dragging in unrelated files. These get an
+    // importance boost below so they survive the per-file cluster budget.
+    const glueNodeIds = new Set<string>();
+    const subgraphFiles = new Set<string>();
+    for (const n of subgraph.nodes.values()) subgraphFiles.add(n.filePath);
+    const GLUE_NODE_CAP = 60;
+    for (const rootId of subgraph.roots) {
+      if (glueNodeIds.size >= GLUE_NODE_CAP) break;
+      let neighbors: Node[] = [];
+      try {
+        neighbors = [
+          ...cg.getCallers(rootId).map(c => c.node),
+          ...cg.getCallees(rootId).map(c => c.node),
+        ];
+      } catch {
+        continue;
+      }
+      for (const nb of neighbors) {
+        if (glueNodeIds.size >= GLUE_NODE_CAP) break;
+        if (subgraph.nodes.has(nb.id)) continue;
+        if (!subgraphFiles.has(nb.filePath)) continue;
+        subgraph.nodes.set(nb.id, nb);
+        glueNodeIds.add(nb.id);
+      }
+    }
+
+    // Named-symbol seeding: findRelevantContext is an FTS/text rank, so a query
+    // that's a BAG of symbol names skewed toward one phase (Alamofire: 5 build
+    // terms, each a high-frequency name, vs 3 validate terms) lets the
+    // lower-frequency names fall below the search cut — their definitions, and
+    // whole files (Validation.swift), never get gathered, so they can never
+    // render and the agent Reads them. Resolve EACH named token to its
+    // substantive definition (skip empty stubs + test files, same relevance the
+    // trace endpoint picker uses) and inject it as an entry, so every symbol the
+    // agent explicitly named is in the subgraph and its file is scored.
+    const namedSeedIds = new Set<string>();
+    {
+      const FILE_EXT = /\.(?:java|kt|kts|ts|tsx|js|jsx|mjs|cjs|cs|py|go|rb|php|swift|rs|cpp|cc|cxx|c|h|hpp|scala|lua|dart|vue|svelte|astro)$/i;
+      const CALLABLE = new Set(['method', 'function', 'component', 'constructor']);
+      const isTestPath = (p: string) => /(^|\/)(tests?|specs?|__tests__|testdata|mocks?|fixtures?)\//i.test(p) || /\.(test|spec)\.[a-z]+$/i.test(p);
+      const bodyLines = (n: Node) => Math.max(0, (n.endLine ?? n.startLine) - n.startLine);
+      const tokens = [...new Set(
+        query.split(/[\s,()[\]]+/)
+          .map((t) => t.replace(FILE_EXT, '').trim())
+          .filter((t) => t.length >= 3 && /^[A-Za-z_$][\w$]*(?:(?:::|\.)[\w$]+)*$/.test(t))
+      )].slice(0, 16);
+      // PascalCase tokens in the query are type/file disambiguators — when the
+      // agent writes "DataRequest task validate", the `task`/`validate` it wants
+      // are DataRequest's, NOT the same-named overloads in Validation.swift /
+      // Concurrency.swift / the abstract base. Used below to bias overloaded
+      // names toward the file/class the query also names. EXCLUDE the project
+      // name (a PascalCase token a user naturally includes) — it names the whole
+      // repo, so biasing toward it just pulls overloads to whichever stack
+      // embeds it, re-burying the rest (#720).
+      const projectNameTokens = cg.getProjectNameTokens();
+      const typeTokens = tokens.filter(
+        (o) => /^[A-Z][A-Za-z0-9]{3,}/.test(o) && !projectNameTokens.has(normalizeNameToken(o)),
+      );
+      const inNamedContext = (n: Node) =>
+        typeTokens.some((ct) => {
+          const lc = ct.toLowerCase();
+          return n.filePath.toLowerCase().includes(lc) || n.qualifiedName.toLowerCase().includes(lc);
+        });
+      for (const t of tokens) {
+        // Enumerate ALL defs of a bare token via the direct index, not FTS — a
+        // 50+-overload name (tokio `poll`) ranks the wanted def (`Harness::poll`)
+        // below the FTS cut, so findAllSymbols would never see it and the
+        // type-token bias below couldn't pick the harness.rs one. (Same fix as
+        // codegraph_node's findSymbolMatches.) Qualified tokens keep findAllSymbols.
+        const isQual = /[.\/]|::/.test(t);
+        const raw = isQual ? this.findAllSymbols(cg, t).nodes : cg.getNodesByName(t);
+        const cands = raw
+          .filter((n) => CALLABLE.has(n.kind) && !isTestPath(n.filePath))
+          .sort((a, b) => (bodyLines(b) > 1 ? 1 : 0) - (bodyLines(a) > 1 ? 1 : 0) || bodyLines(b) - bodyLines(a));
+        // A specific name (<=3 defs) injects all its defs. An overloaded name
+        // (`validate` = 10, `request` = 44) would flood the subgraph, so inject
+        // only: the overloads whose file/class the query ALSO names (the agent
+        // told us which one it wants — DataRequest's, not Validation.swift's),
+        // capped; else fall back to the single most-substantive def. This is the
+        // explore-side mirror of codegraph_node's overload disambiguation.
+        let picks: Node[];
+        if (cands.length <= 3) {
+          picks = cands;
+        } else {
+          const ctx = cands.filter(inNamedContext);
+          picks = ctx.length > 0 ? ctx.slice(0, 4) : cands.slice(0, 1);
+        }
+        for (const n of picks) {
+          if (!subgraph.nodes.has(n.id)) subgraph.nodes.set(n.id, n);
+          // Mark as a named seed EVEN IF the FTS gather already had it — being
+          // "named by the agent" is independent of whether search happened to
+          // surface it, and it drives the +50 score, the gate, and the
+          // named-file sort below. (Previously only NEW injections were marked,
+          // so a named symbol FTS already gathered never sorted to the top.)
+          namedSeedIds.add(n.id);
+        }
+      }
+    }
+
     // Step 2: Group nodes by file, score by relevance
     const fileGroups = new Map<string, { nodes: Node[]; score: number }>();
-    const entryNodeIds = new Set(subgraph.roots);
+    const entryNodeIds = new Set([...subgraph.roots, ...namedSeedIds]);
 
     // Build a set of nodes directly connected to entry points (depth 1)
     const connectedToEntry = new Set<string>();
@@ -874,11 +1944,23 @@ export class ToolHandler {
     for (const node of subgraph.nodes.values()) {
       // Skip import/export nodes — they add noise without information
       if (node.kind === 'import' || node.kind === 'export') continue;
+      // SECURITY (#383): never render the on-disk source of a config-leaf
+      // (Spring application.{yml,properties} key) — its line is `key = <secret>`,
+      // so whole-file/cluster rendering here would push secrets into context
+      // unbidden. The key still appears in the flow/symbol listing above.
+      if (isConfigLeafNode(node)) continue;
 
       const group = fileGroups.get(node.filePath) || { nodes: [], score: 0 };
       group.nodes.push(node);
-      // Score: entry point nodes worth 10, directly connected worth 3, others worth 1
-      if (entryNodeIds.has(node.id)) {
+      // Score: a NAMED-SEED node (a symbol the agent named that FTS missed, now
+      // injected) is worth far more than a mere reference — its file is where the
+      // answer lives. Without this, an incidental file that name-drops the flow
+      // (Combine.swift references request/task → score 23 from connected nodes)
+      // outranks the file that DEFINES a named symbol (Validation.swift's
+      // `validate` → 10) and steals its render slot. Definition ≫ reference.
+      if (namedSeedIds.has(node.id)) {
+        group.score += 50;
+      } else if (entryNodeIds.has(node.id)) {
         group.score += 10;
       } else if (connectedToEntry.has(node.id)) {
         group.score += 3;
@@ -889,36 +1971,176 @@ export class ToolHandler {
     }
 
     // Only include files that have entry points or nodes directly connected to entry points
-    const relevantFiles = [...fileGroups.entries()].filter(([, group]) => group.score >= 3);
+    let relevantFiles = [...fileGroups.entries()].filter(([, group]) => group.score >= 3);
 
     // Extract query terms for relevance checking
     const queryTerms = query.toLowerCase().split(/\s+/).filter(t => t.length >= 3);
 
-    // Sort files: highest relevance first, deprioritize low-value files
+    // Test/spec/icon/i18n file detector — used both for the pre-sort hard
+    // filter (tiny tier) and the comparator deprioritization (all tiers).
+    const isLowValue = (p: string) => {
+      const lp = p.toLowerCase();
+      return (
+        /\/(tests?|__tests?__|spec)\//.test(lp) ||
+        /_test\.go$/.test(lp) ||
+        /(?:^|\/)test_[^/]+\.py$/.test(lp) ||
+        /_test\.py$/.test(lp) ||
+        /_spec\.rb$/.test(lp) ||
+        /_test\.rb$/.test(lp) ||
+        /\.(test|spec)\.[jt]sx?$/.test(lp) ||
+        /(test|spec|tests)\.(java|kt|scala)$/.test(lp) ||
+        /(tests?|spec)\.cs$/.test(lp) ||
+        /tests?\.swift$/.test(lp) ||
+        /_test\.dart$/.test(lp) ||
+        /\bicons?\b/.test(lp) ||
+        /\bi18n\b/.test(lp)
+      );
+    };
+
+    // Hard-exclude test/spec files (ALL tiers, not just tiny). One slipped test
+    // file dominates the per-file budget on small repos (cobra's `command_test.go`
+    // displaced `args.go`) AND wastes budget on large ones (Django's
+    // `custom_lookups/tests.py` ate ~2.3 KB of the 28 KB cap, crowding out the
+    // SQLCompiler mechanism the agent then Read). A test file almost never answers
+    // an architecture question. Skip when the query itself is about tests — the
+    // legitimate "explore the tests" case — and only cut if ≥2 non-test candidates
+    // remain (else tests are the only signal for this area).
+    {
+      const queryMentionsTests = /\b(test|tests|testing|spec|verify|verifies)\b/i.test(query);
+      if (!queryMentionsTests) {
+        const nonLow = relevantFiles.filter(([p]) => !isLowValue(p));
+        if (nonLow.length >= 2) {
+          relevantFiles = nonLow;
+        }
+      }
+    }
+
+    // Secondary signal: how many DISTINCT query terms each file matches (path +
+    // symbol names). Kept only as a tiebreak — the PRIMARY relevance is graph
+    // connectivity below. (Term counting alone tied the real central file with
+    // incidental same-word matches; it's a weak text signal, not the ranker.)
+    const uniqueQueryTerms = [...new Set(queryTerms)].filter(t => t.length >= 3);
+    const fileTermHits = new Map<string, number>();
+    for (const [fp, group] of relevantFiles) {
+      const hay = fp.toLowerCase() + ' ' + group.nodes.map(n => n.name.toLowerCase()).join(' ');
+      let hits = 0;
+      for (const t of uniqueQueryTerms) if (hay.includes(t)) hits++;
+      fileTermHits.set(fp, hits);
+    }
+
+    // PRIMARY relevance: graph connectivity (Random-Walk-with-Restart from the
+    // matched seeds — see computeGraphRelevance). Aggregate each file's nodes'
+    // walk mass. This is the signal text search lacks: the real cluster
+    // (org-user.storage.ts, call-connected to the matches) accrues mass; a lone
+    // text match (LensSwitcher.swift, matched "switch" but calls nothing in the
+    // flow) gets only its restart probability → ~0, and is dropped by the gate.
+    const nodeRwr = this.computeGraphRelevance(
+      [...subgraph.nodes.keys()], subgraph.edges, entryNodeIds,
+    );
+    const fileGraphScore = new Map<string, number>();
+    for (const node of subgraph.nodes.values()) {
+      fileGraphScore.set(
+        node.filePath,
+        (fileGraphScore.get(node.filePath) ?? 0) + (nodeRwr.get(node.id) ?? 0),
+      );
+    }
+    const maxGraph = Math.max(0, ...fileGraphScore.values());
+
+    // Central file(s): the 1-2 most graph-central files that also match the
+    // query textually (so a connected hub-utility with no term match isn't
+    // mistaken for the subject). The heart of the answer — they earn the larger
+    // WHOLE-FILE ceiling below (a god-file central file still exceeds it and
+    // falls to generous full-method sectioning — never a whole dump).
+    const centralFiles = new Set(
+      [...fileGraphScore.entries()]
+        .filter(([fp, g]) => g > 0 && (fileTermHits.get(fp) ?? 0) >= 1)
+        .sort((a, b) => b[1] - a[1] || (fileTermHits.get(b[0]) ?? 0) - (fileTermHits.get(a[0]) ?? 0))
+        .slice(0, 2)
+        .map(([f]) => f),
+    );
+
+    // Files that DEFINE a symbol the agent named (or a subgraph root). These are
+    // the highest-relevance files there are — the agent asked for them by name —
+    // so the connectivity gate below must never drop them, even when their RWR
+    // mass is low (a leaf family file like codec.ts is call-connected to little
+    // but is exactly what the agent queried). Without this protection the gate
+    // prunes a named file and the agent Reads it back.
+    const entryFiles = new Set<string>();
+    for (const id of entryNodeIds) {
+      const n = subgraph.nodes.get(id);
+      if (n) entryFiles.add(n.filePath);
+    }
+
+    // Relevance gate (so the generous budget is a CEILING, not a target): keep a
+    // file only if it is STRUCTURALLY relevant by ANY of:
+    //   - graph score within a fraction of the top (it's on/near the flow), OR
+    //   - central (a query entry-point lives here), OR
+    //   - it DEFINES a symbol the agent named (entryFiles), OR
+    //   - it matches >= 2 DISTINCT named query terms — a strong text signal that
+    //     the agent is asking about this file even when nothing calls it (codec.ts:
+    //     the agent named `encode`/`Codec`/`JsonCodec`, all leaf classes with zero
+    //     RWR mass — graph alone wrongly drops it).
+    // A lone text match on one shared word (LensSwitcher: term=1, g~0) is still
+    // dropped, so the budget never fills with incidental files. Guarded so it
+    // never prunes below 2.
+    if (maxGraph > 0) {
+      const gated = relevantFiles.filter(([fp]) =>
+        (fileGraphScore.get(fp) ?? 0) >= maxGraph * 0.06
+        || centralFiles.has(fp)
+        || entryFiles.has(fp)
+        || (fileTermHits.get(fp) ?? 0) >= 2,
+      );
+      if (gated.length >= 2) relevantFiles = gated;
+    }
+
+    // Sort files: graph-central first, then distinct-term match, then the
+    // existing low-value/generated/score tiebreaks.
+    // Files that DEFINE a symbol the agent NAMED. These sort first — ahead of
+    // graph connectivity — because the agent asked for them by name. Without
+    // this, a named leaf override reached only by dynamic dispatch (Alamofire's
+    // `DataRequest.task`/`validate`, low RWR mass) sorts below the high-
+    // connectivity abstract base (`Request.swift`) and the same-named overloads
+    // in other files (`Validation.swift`), falls outside the budget, and the
+    // agent Reads it. The named file is the answer — rank it at the top.
+    const namedSeedFiles = new Set<string>();
+    for (const id of namedSeedIds) {
+      const n = subgraph.nodes.get(id);
+      if (n) namedSeedFiles.add(n.filePath);
+    }
+
     const sortedFiles = relevantFiles.sort((a, b) => {
       const aPath = a[0].toLowerCase();
       const bPath = b[0].toLowerCase();
 
-      // Check if any node name or file path relates to query terms
-      const hasQueryRelevance = (filePath: string, nodes: Node[]) => {
-        const fp = filePath.toLowerCase();
-        if (queryTerms.some(t => fp.includes(t))) return true;
-        return nodes.some(n => queryTerms.some(t => n.name.toLowerCase().includes(t)));
-      };
+      // Agent-named files first (it asked for a symbol defined here by name).
+      const aNamed = namedSeedFiles.has(a[0]) ? 1 : 0;
+      const bNamed = namedSeedFiles.has(b[0]) ? 1 : 0;
+      if (aNamed !== bNamed) return bNamed - aNamed;
 
-      const aRelevant = hasQueryRelevance(aPath, a[1].nodes);
-      const bRelevant = hasQueryRelevance(bPath, b[1].nodes);
-      if (aRelevant !== bRelevant) return aRelevant ? -1 : 1;
+      // Graph connectivity is the next key (small epsilon so near-ties fall
+      // through to the text signal rather than coin-flipping on float noise).
+      const aG = fileGraphScore.get(a[0]) ?? 0;
+      const bG = fileGraphScore.get(b[0]) ?? 0;
+      if (Math.abs(aG - bG) > maxGraph * 0.01) return bG - aG;
+
+      const aHits = fileTermHits.get(a[0]) ?? 0;
+      const bHits = fileTermHits.get(b[0]) ?? 0;
+      if (aHits !== bHits) return bHits - aHits;
 
-      // Deprioritize test files, icon files, and i18n files
-      const isLowValue = (p: string) =>
-        /\/(tests?|__tests?__|spec)\//i.test(p) ||
-        /\bicons?\b/i.test(p) ||
-        /\bi18n\b/i.test(p);
       const aLow = isLowValue(aPath);
       const bLow = isLowValue(bPath);
       if (aLow !== bLow) return aLow ? 1 : -1;
 
+      // Deprioritize generated source (.pb.go / .pulsar.go / _mocks.go / …) —
+      // the agent rarely needs to see the protobuf scaffold or gomock output
+      // when asking about the actual flow, and dumping their bodies inflates
+      // the response (the cosmos Q3 explore otherwise leads with
+      // `expected_keepers_mocks.go`, displacing the real `tally.go` content
+      // and forcing the agent to Read tally.go anyway).
+      const aGen = isGeneratedFile(a[0]);
+      const bGen = isGeneratedFile(b[0]);
+      if (aGen !== bGen) return aGen ? 1 : -1;
+
       if (a[1].score !== b[1].score) return b[1].score - a[1].score;
       return b[1].nodes.length - a[1].nodes.length;
     });
@@ -931,6 +2153,12 @@ export class ToolHandler {
       '',
     ];
 
+    // Blast radius (always-on, compact): for the entry symbols, who depends on
+    // them + which tests cover them — locations only, no source — so the agent
+    // knows what to update/verify before editing without a separate call.
+    const blastRadius = this.buildBlastRadiusSection(cg, subgraph);
+    if (blastRadius) lines.push(blastRadius);
+
     // Relationship map — show how symbols connect
     const significantEdges = subgraph.edges.filter(e =>
       e.kind !== 'contains' // skip contains — it's implied by file grouping
@@ -967,8 +2195,67 @@ export class ToolHandler {
     }
 
     // Step 4: Read contiguous file sections
+    // Compute the flow spine once — used both to prepend the Flow section (below)
+    // and to gate adaptive source sizing: files on the spine get full source,
+    // off-spine peers skeletonize.
+    const flow = this.buildFlowFromNamedSymbols(cg, query);
+
+    // Polymorphic-sibling detector for adaptive sizing. A class that implements/
+    // extends a supertype shared by >= MIN_SIBLINGS classes is one of many
+    // INTERCHANGEABLE implementations (OkHttp's 14 `: Interceptor` classes —
+    // showing one + the rest as signatures is enough), as opposed to a DISTINCT
+    // pipeline step (Excalidraw's `renderStaticScene`, which shares no supertype and
+    // must stay full or the agent loses real content). Only off-spine sibling files
+    // skeletonize; distinct steps and on-spine files keep full source. Cache
+    // supertype→(has ≥N implementers) so this stays a handful of edge queries.
+    const MIN_SIBLINGS = 3;
+    const siblingSuper = new Map<string, boolean>();
+    const isPolymorphicSibling = (nodes: Node[]): boolean => {
+      for (const n of nodes) {
+        for (const e of cg.getOutgoingEdges(n.id)) {
+          if (e.kind !== 'implements' && e.kind !== 'extends') continue;
+          let many = siblingSuper.get(e.target);
+          if (many === undefined) {
+            many = cg.getIncomingEdges(e.target)
+              .filter((x) => x.kind === 'implements' || x.kind === 'extends').length >= MIN_SIBLINGS;
+            siblingSuper.set(e.target, many);
+          }
+          if (many) return true;
+        }
+      }
+      return false;
+    };
+
+    // A file that DEFINES a polymorphic supertype (a class/interface with ≥
+    // MIN_SIBLINGS implementers) AND co-locates its subclasses is a redundant
+    // "family" file — Django's compiler.py holds `SQLCompiler` + its 4 subclasses
+    // (SQLInsert/Update/Delete/AggregateCompiler) in 2,266 lines. Such files are
+    // huge and read-anyway, so they should STILL skeletonize even when the agent
+    // named a method in them: a full one eats ~6.5K of the explore budget (Django
+    // is pinned at the 28K cap, truncating), starving the sibling files the agent
+    // then Reads. This flag OVERRIDES the named-callable spare below — it does NOT
+    // by itself spare a file. (OkHttp's RealCall implements the `Lockable` mixin
+    // but defines no ≥3-impl supertype, so the named spare keeps it full.)
+    const superMany = new Map<string, boolean>();
+    const definesPolymorphicSupertype = (nodes: Node[]): boolean => {
+      for (const n of nodes) {
+        if (n.kind !== 'class' && n.kind !== 'interface' && n.kind !== 'struct'
+            && n.kind !== 'trait' && n.kind !== 'protocol' && n.kind !== 'type_alias') continue;
+        let many = superMany.get(n.id);
+        if (many === undefined) {
+          many = cg.getIncomingEdges(n.id)
+            .filter((x) => x.kind === 'implements' || x.kind === 'extends').length >= MIN_SIBLINGS;
+          superMany.set(n.id, many);
+        }
+        if (many) return true;
+      }
+      return false;
+    };
+
     lines.push('### Source Code');
     lines.push('');
+    lines.push('> The code below is the **verbatim, current on-disk source** of these files — re-read from disk on this call and line-numbered, byte-for-byte identical to what the Read tool returns. It is NOT a summary, outline, or stale cache. Treat each block as a Read you have already performed: do not Read a file shown here.');
+    lines.push('');
 
     let totalChars = lines.join('\n').length;
     let filesIncluded = 0;
@@ -976,7 +2263,15 @@ export class ToolHandler {
 
     for (const [filePath, group] of sortedFiles) {
       if (filesIncluded >= maxFiles) break;
-      if (totalChars > budget.maxOutputChars * 0.9) break;
+      // A file DEFINES a named/spine symbol (the answer) vs merely references the
+      // flow. Past 90% budget, stop pulling INCIDENTAL files — but keep scanning
+      // for necessary ones, which render even past the cap (bounded by maxFiles).
+      // Without this `continue` (was an unconditional `break`), the loop stopped
+      // after the build + validators-exec files and never reached the ranked-in
+      // validate-logic file (Alamofire's Validation.swift).
+      const fileNecessary = group.nodes.some(n =>
+        entryNodeIds.has(n.id) || flow.pathNodeIds.has(n.id) || flow.uniqueNamedNodeIds.has(n.id));
+      if (!fileNecessary && totalChars > budget.maxOutputChars * 0.9) continue;
 
       const absPath = validatePathWithinRoot(projectRoot, filePath);
       if (!absPath || !existsSync(absPath)) continue;
@@ -991,6 +2286,172 @@ export class ToolHandler {
       const fileLines = fileContent.split('\n');
       const lang = group.nodes[0]?.language || '';
 
+      // Adaptive sizing (CODEGRAPH_ADAPTIVE_EXPLORE, default on): collapse a file
+      // to a per-symbol view when it's a redundant member of a polymorphic family.
+      // Engages iff ALL hold:
+      //   1. a flow spine exists,
+      //   2. no symbol in the file is on that spine (it's not the mechanism path),
+      //   3. it IS a polymorphic sibling (≥ MIN_SIBLINGS impls of a shared supertype),
+      //   4. it is NOT SPARED, where a file is spared iff the agent named a
+      //      (near-)UNIQUE callable in it (`getResponseWithInterceptorChain`, 1 def →
+      //      keep RealCall.kt full) UNLESS the file DEFINES the family supertype (a
+      //      base+subclasses "family" file like Django's compiler.py — collapse it).
+      //      Uniqueness matters: `as_sql` has 110 defs across every Compiler/Expression
+      //      subclass; naming it must NOT keep every backend variant + test file full
+      //      and flood the budget. That's why the spare reads uniqueNamedNodeIds.
+      // Within a collapsed file the render is PER-SYMBOL (condition B): a method the
+      // agent NAMED or that's on the spine is shown with its FULL body (so the agent
+      // doesn't Read the file back for it — Django's SQLCompiler.execute_sql/as_sql);
+      // every other symbol is just its signature. So the base mechanism survives while
+      // the file's other ~80 symbols + the redundant subclasses collapse to one line each.
+      const spareNamed = group.nodes.some(n => flow.uniqueNamedNodeIds.has(n.id));
+      const fileDefinesSuper = definesPolymorphicSupertype(group.nodes);
+      const spared = spareNamed && !fileDefinesSuper;
+      const CALLABLE_BODY = new Set(['method', 'function', 'constructor', 'component']);
+      const hasSpineNode = group.nodes.some(n => flow.pathNodeIds.has(n.id));
+      // On-spine god-file: the flow path runs THROUGH this file, but it also holds
+      // many OTHER named methods, and rendering all of them in full blows the
+      // per-file budget and starves the other flow files (Alamofire: the agent
+      // names ~7 Session.swift methods — the build spine PLUS off-path
+      // task/didCompleteTask — far past the whole response budget). Engage the
+      // per-symbol view to keep the SPINE full and collapse the off-path named
+      // methods to signatures. Only when there IS off-path content to shed —
+      // otherwise the spine is irreducible (a sequential flow has no redundancy),
+      // so leave it to the normal full render.
+      const namedBodyChars = group.nodes
+        .filter(n => CALLABLE_BODY.has(n.kind) && (flow.pathNodeIds.has(n.id) || flow.uniqueNamedNodeIds.has(n.id)))
+        .reduce((s, n) => s + fileLines.slice(n.startLine - 1, n.endLine).join('\n').length, 0);
+      const onSpineGodFile = hasSpineNode
+        && namedBodyChars > budget.maxCharsPerFile
+        && group.nodes.some(n => CALLABLE_BODY.has(n.kind) && flow.uniqueNamedNodeIds.has(n.id) && !flow.pathNodeIds.has(n.id));
+      if (adaptiveExploreEnabled() && flow.pathNodeIds.size > 0
+          && (onSpineGodFile || (!hasSpineNode && isPolymorphicSibling(group.nodes) && !spared))) {
+        const syms = group.nodes
+          .filter(n => n.kind !== 'import' && n.kind !== 'export' && n.startLine > 0)
+          .sort((a, b) => a.startLine - b.startLine);
+        // Pass 1: choose which symbols get a FULL body, by priority, greedily within
+        // a per-file body cap — so one huge family file can't body every named method
+        // and crowd out the other flow files (Django's query.py). A symbol earns a
+        // body if it's on-spine, or UNIQUELY named (`SQLCompiler.execute_sql`), or a
+        // co-named method WHEN this file DEFINES the family supertype (so the base
+        // `SQLCompiler.as_sql` body shows, but the 110 leaf `as_sql` overrides — and
+        // OkHttp's 5 `intercept`s if the agent names `intercept` — stay signatures).
+        const prio = (n: Node) => !CALLABLE_BODY.has(n.kind) ? 99
+          : flow.pathNodeIds.has(n.id) ? 0
+          : flow.uniqueNamedNodeIds.has(n.id) ? 1
+          : (fileDefinesSuper && flow.namedNodeIds.has(n.id)) ? 2 : 99;
+        // One ~250-line WINDOW per file. syms are taken by priority (spine first,
+        // then uniquely-named, then family-base), and the cap applies to ALL of
+        // them — including the spine — so a big-spine god-file (tokio's worker.rs:
+        // run→run_task→next_task→steal_work) can't eat the whole response and
+        // starve the co-flow file (harness.rs's poll). The native agent windows
+        // such a file too (~190 lines at a time), so this mimics, not truncates.
+        // Always emit ≥1 (never an empty section).
+        const bodyCap = budget.maxCharsPerFile * 1.5;
+        const bodyIds = new Set<string>();
+        let bodyChars = 0;
+        for (const n of syms.filter(n => prio(n) < 99 && n.endLine >= n.startLine).sort((a, b) => prio(a) - prio(b))) {
+          const sz = fileLines.slice(n.startLine - 1, n.endLine).join('\n').length;
+          if (bodyChars + sz > bodyCap && bodyIds.size > 0) continue;
+          bodyIds.add(n.id);
+          bodyChars += sz;
+        }
+        // Pass 2: render in line order — full body for chosen symbols, else the
+        // signature line (capped, with a "+N more" tail so the structure map of a
+        // god-file doesn't itself bloat the budget).
+        const skel: string[] = [];
+        let coveredUntil = 0; // skip symbols already inside an emitted body
+        let sigCount = 0, sigDropped = 0;
+        const SIG_MAX = Math.max(12, budget.maxSymbolsInFileHeader * 2);
+        for (const n of syms) {
+          if (n.startLine <= coveredUntil) continue;
+          if (bodyIds.has(n.id)) {
+            const end = n.endLine;
+            const body = fileLines.slice(n.startLine - 1, end).join('\n');
+            skel.push(exploreLineNumbersEnabled() ? numberSourceLines(body, n.startLine) : body);
+            coveredUntil = end;
+          } else {
+            // Elide the body, emit the signature. node.startLine can point at a
+            // decorator/annotation, so scan forward for the line that names the symbol.
+            let lineNo = n.startLine;
+            for (let k = 0; k < 4; k++) {
+              if ((fileLines[n.startLine - 1 + k] || '').includes(n.name)) { lineNo = n.startLine + k; break; }
+            }
+            if (lineNo <= coveredUntil) continue;
+            if (sigCount >= SIG_MAX) { sigDropped++; continue; }
+            const sig = (fileLines[lineNo - 1] || '').trim();
+            if (sig) { skel.push(exploreLineNumbersEnabled() ? `${lineNo}\t${sig}` : sig); sigCount++; }
+          }
+        }
+        if (sigDropped > 0) skel.push(`… +${sigDropped} more (signatures elided)`);
+        if (skel.length > 0) {
+          const names = [...new Set(group.nodes.filter(n => n.kind !== 'import' && n.kind !== 'export').map(n => n.name))]
+            .slice(0, budget.maxSymbolsInFileHeader).join(', ');
+          // Steer the agent to codegraph_explore for an elided body — NEVER to
+          // Read. The old "Read for more" / "Read for a full body" tags invited
+          // a Read of the very file just skeletonized; on a central, wanted file
+          // (Session.swift, DataRequest.swift) that fired an over-investigation
+          // spiral (the agent Read the skeletonized file, then kept digging).
+          // CLAUDE.md: explore output must never tell the agent to Read.
+          const tag = bodyIds.size > 0
+            ? 'focused (the methods you named in full, the rest as signatures — codegraph_explore a signature by name for its body; do NOT Read)'
+            : 'skeleton (signatures only — codegraph_explore a name for its full body; do NOT Read)';
+          lines.push(`#### ${filePath} — ${names} · ${tag}`, '', '```' + lang, skel.join('\n'), '```', '');
+          totalChars += skel.join('\n').length + 120;
+          filesIncluded++;
+          continue;
+        }
+      }
+
+      // Whole-file rule: if a relevant file is small enough to afford, return it
+      // ENTIRELY instead of clustering. Clustering exists to tame god-files
+      // (App.tsx ~13k lines); on a ~134-line component a cluster is a lossy
+      // subset of a file the agent will just Read in full anyway — costing a
+      // round-trip and a re-read every later turn. Reserve clustering for files
+      // too big to ship whole. Still bounded by the total maxOutputChars check.
+      //
+      // CENTRAL files (where the query's entry points live) get a larger — but
+      // bounded — ceiling: they're the heart of the answer, the file(s) the agent
+      // would Read whole, so a genuinely small one comes back whole rather than as
+      // thin clusters. A LARGE central file (the 791-line org-user store) exceeds
+      // the ceiling and falls through to sectioning/clustering below — full method
+      // bodies + signatures — so we never dump (or overflow on) a whole god-file.
+      const isCentralFile = centralFiles.has(filePath);
+      // Central files get a slightly larger whole-file window than peripheral ones,
+      // but a TIGHT one (~1.5× the per-file cap): the native read of a central file
+      // is a ~150–250 line orientation window, NOT the whole file. A flat "whole
+      // central file" both overflowed the inline cap AND starved the co-flow files
+      // (worker.rs ate the budget, dropping harness.rs's poll). A larger central
+      // file falls through to per-method windowing/clustering below.
+      const WHOLE_FILE_MAX_LINES = isCentralFile ? 280 : 220;
+      const WHOLE_FILE_MAX_CHARS = isCentralFile
+        ? Math.min(Math.max(0, budget.maxOutputChars - totalChars - 200), Math.round(budget.maxCharsPerFile * 1.5))
+        : budget.maxCharsPerFile * 3;
+      if (fileLines.length <= WHOLE_FILE_MAX_LINES && fileContent.length <= WHOLE_FILE_MAX_CHARS) {
+        const body = fileContent.replace(/\n+$/, '');
+        let wholeSection = exploreLineNumbersEnabled() ? numberSourceLines(body, 1) : body;
+        const uniqSymbols = [...new Set(
+          group.nodes
+            .filter(n => n.kind !== 'import' && n.kind !== 'export')
+            .map(n => `${n.name}(${n.kind})`)
+        )];
+        const headerNames = uniqSymbols.slice(0, budget.maxSymbolsInFileHeader);
+        const omitted = uniqSymbols.length - headerNames.length;
+        const wholeHeader = `#### ${filePath} — ${omitted > 0 ? `${headerNames.join(', ')}, +${omitted} more` : headerNames.join(', ')}`;
+
+        if (!fileNecessary && totalChars + wholeSection.length + 200 > budget.maxOutputChars) {
+          // Don't slice a whole file mid-method: an incidental file that doesn't
+          // fit is skipped; a necessary one (below) renders in full. Half a file
+          // forces the Read this is meant to prevent.
+          anyFileTrimmed = true;
+          continue;
+        }
+        lines.push(wholeHeader, '', '```' + lang, wholeSection, '```', '');
+        totalChars += wholeSection.length + 200;
+        filesIncluded++;
+        continue;
+      }
+
       // Cluster nearby symbols to avoid reading huge gaps between distant symbols.
       // Sort by start line, then merge overlapping/adjacent ranges (within the
       // adaptive gap threshold). Include both node ranges AND edge source
@@ -1011,13 +2472,28 @@ export class ToolHandler {
       // Alamofire is the canonical case: the `Session` class spans ~1,400
       // lines). We want the granular symbols inside, not the envelope.
       const ENVELOPE_KINDS = new Set(['file', 'module', 'class', 'struct', 'interface', 'enum', 'namespace', 'protocol', 'trait', 'component']);
-      const ranges: Array<{ start: number; end: number; name: string; kind: string; importance: number }> = group.nodes
-        .filter(n => n.startLine > 0 && n.endLine > 0)
+      // Cluster from this file's gathered nodes PLUS any callable the agent NAMED that
+      // lives here. Explore's relevance gather can miss a named method def in a huge
+      // non-sibling file — Django's query.py is 3,040 lines and `_fetch_all` (L2237)
+      // was gathered only as call-reference edges, never as a def, so it formed no
+      // cluster and the agent Read it back. Inject named defs directly and rank them
+      // ABOVE connected/glue nodes (importance 9) so their cluster wins the per-file
+      // budget — the agent explicitly asked for these symbols.
+      const rangeNodes = new Map<string, Node>();
+      for (const n of group.nodes) if (n.startLine > 0 && n.endLine > 0) rangeNodes.set(n.id, n);
+      for (const id of flow.namedNodeIds) {
+        if (rangeNodes.has(id)) continue;
+        const n = cg.getNode(id);
+        if (n && n.filePath === filePath && n.startLine > 0 && n.endLine > 0) rangeNodes.set(id, n);
+      }
+      const ranges: Array<{ start: number; end: number; name: string; kind: string; importance: number }> = [...rangeNodes.values()]
         // Drop whole-file envelope nodes (containers covering >50% of the file).
         .filter(n => !(ENVELOPE_KINDS.has(n.kind) && (n.endLine - n.startLine + 1) > fileLines.length * 0.5))
         .map(n => {
           let importance = 1;
           if (entryNodeIds.has(n.id)) importance = 10;
+          else if (flow.namedNodeIds.has(n.id)) importance = 9; // agent named it → keep its cluster
+          else if (glueNodeIds.has(n.id)) importance = 6; // bridging caller/callee of an entry
           else if (connectedToEntry.has(n.id)) importance = 3;
           return { start: n.startLine, end: n.endLine, name: n.name, kind: n.kind, importance };
         });
@@ -1116,6 +2592,13 @@ export class ToolHandler {
           return a.span - b.span;
         });
 
+      // Per-file budget is the SMALLER of the per-file cap and what's left of the
+      // total output cap — so selection (which ranks by importance) keeps the
+      // high-importance clusters and drops peripheral ones, instead of the
+      // downstream source-order trim slicing off whatever comes last in the file.
+      // That source-order slice is what cut Django's `_fetch_all` (L2237, importance
+      // 9 — agent-named) when query.py was the last of four big files to be emitted.
+      const fileBudget = Math.min(budget.maxCharsPerFile, Math.max(0, budget.maxOutputChars - totalChars - 200));
       const chosenIndices = new Set<number>();
       let projectedChars = 0;
       for (const rc of rankedClusters) {
@@ -1128,7 +2611,7 @@ export class ToolHandler {
           projectedChars += sectionLen;
           continue;
         }
-        if (projectedChars + sectionLen > budget.maxCharsPerFile) continue;
+        if (projectedChars + sectionLen > fileBudget) continue;
         chosenIndices.add(rc.idx);
         projectedChars += sectionLen;
       }
@@ -1136,7 +2619,6 @@ export class ToolHandler {
       // Emit chosen clusters in source order so the file reads top-to-bottom.
       let fileSection = '';
       const allSymbols: string[] = [];
-      let fileTrimmed = false;
       for (let i = 0; i < clusters.length; i++) {
         if (!chosenIndices.has(i)) continue;
         const cluster = clusters[i]!;
@@ -1146,13 +2628,12 @@ export class ToolHandler {
         allSymbols.push(...cluster.symbols);
       }
 
-      // If a single chosen cluster is still oversize (long monolithic
-      // function), tail-trim it. Better one trimmed view than nothing.
-      if (fileSection.length > budget.maxCharsPerFile) {
-        fileSection = fileSection.slice(0, budget.maxCharsPerFile) + '\n... (trimmed) ...';
-        fileTrimmed = true;
-      }
-      if (chosenIndices.size < clusters.length || fileTrimmed) {
+      // A chosen cluster is a COMPLETE method-range — we never cut through a body.
+      // An oversize single cluster (a long monolithic function) renders in FULL:
+      // half a method is useless (the agent just Reads the rest for the other half),
+      // which is the very fallback explore exists to prevent. A pathological file is
+      // bounded by the per-file cluster SELECTION above + the total hard ceiling.
+      if (chosenIndices.size < clusters.length) {
         anyFileTrimmed = true;
       }
 
@@ -1175,22 +2656,22 @@ export class ToolHandler {
         : headerSymbols.join(', ');
       const fileHeader = `#### ${filePath} — ${headerSuffix}`;
 
-      // Respect the total output cap on a file-by-file basis.
-      if (totalChars + fileSection.length + 200 > budget.maxOutputChars) {
-        const remaining = budget.maxOutputChars - totalChars - 200;
-        if (remaining < 500) break;
-        const trimmed = fileSection.slice(0, remaining) + '\n... (trimmed) ...';
-
-        lines.push(fileHeader);
-        lines.push('');
-        lines.push('```' + lang);
-        lines.push(trimmed);
-        lines.push('```');
-        lines.push('');
-        totalChars += trimmed.length + 200;
-        filesIncluded++;
+      // The total cap bounds INCIDENTAL files only. A file that DEFINES a symbol
+      // the agent named (or that's on the flow spine) renders even when the
+      // nominal total is used up — it's the answer, and the set is bounded by
+      // maxFiles AND by true-spine/named-seeding having already trimmed each file
+      // to its necessary content. A file that merely REFERENCES the flow
+      // (Combine.swift name-drops request/task) is incidental → still capped, so
+      // freed budget never leaks into noise. This is the last god-file layer:
+      // build (Session, true-spined) + validators-exec (Request) + validate
+      // (DataRequest/Validation) all render, instead of the cap dropping whichever
+      // phase the file order happened to put last.
+      if (!fileNecessary && totalChars + fileSection.length + 200 > budget.maxOutputChars) {
+        // Incidental file that doesn't fit: SKIP it whole — never slice mid-method.
+        // Keep scanning for necessary files (which bypass this cap and render in
+        // full, bounded by the hard ceiling).
         anyFileTrimmed = true;
-        break;
+        continue;
       }
 
       lines.push(fileHeader);
@@ -1214,7 +2695,7 @@ export class ToolHandler {
         .sort((a, b) => b[1].score - a[1].score);
       const remainingFiles = [...remainingRelevant, ...peripheralFiles];
       if (remainingFiles.length > 0) {
-        lines.push('### Additional relevant files (not shown)');
+        lines.push('### Not shown above — explore these names for their source');
         lines.push('');
         for (const [filePath, group] of remainingFiles.slice(0, 10)) {
           const symbols = group.nodes.map(n => `${n.name}:${n.startLine}`).join(', ');
@@ -1233,10 +2714,10 @@ export class ToolHandler {
     if (budget.includeCompletenessSignal) {
       lines.push('');
       lines.push('---');
-      lines.push(`> **Complete source code is included above for ${filesIncluded} files.** You do NOT need to re-read these files — the relevant sections are already shown in full. Only use Read/Grep for files listed under "Additional relevant files" if you need more detail.`);
+      lines.push(`> **Complete source for ${filesIncluded} files is included above — do NOT re-read them.** If your question also needs files/symbols listed under "Not shown above" (or any area this call didn't cover), make ANOTHER codegraph_explore targeting those names — it returns the same source with line numbers and is cheaper and more complete than reading. Reserve Read for a single specific line range explore can't surface.`);
     } else if (anyFileTrimmed) {
       lines.push('');
-      lines.push(`> Some file sections were trimmed for size. Use \`codegraph_node\` or Read for the full source if needed.`);
+      lines.push(`> Some file sections were trimmed for size. For a specific symbol you still need, run another \`codegraph_explore\` (or \`codegraph_node\`) with its exact name — line-numbered source, cheaper and more complete than Read.`);
     }
 
     // Add explore budget note based on project size
@@ -1245,24 +2726,33 @@ export class ToolHandler {
         const stats = cg.getStats();
         const callBudget = getExploreBudget(stats.fileCount);
         lines.push('');
-        lines.push(`> **Explore budget: ${callBudget} calls max for this project (${stats.fileCount.toLocaleString()} files indexed).** Stop exploring and synthesize your answer once you've used ${callBudget} calls — do NOT make additional explore calls beyond this budget.`);
+        lines.push(`> **Explore budget: ${callBudget} calls for this project (${stats.fileCount.toLocaleString()} files indexed).** Each call covers ~6 files; if your question spans more, spend your remaining calls on the uncovered area BEFORE falling back to Read — another explore is cheaper and more complete than reading those files. Synthesize once you've used ${callBudget}.`);
       } catch {
         // Stats unavailable — skip budget note
       }
     }
 
-    // Hard-cap to the adaptive budget. The per-file loop bounds the source
-    // sections, but the relationship map, additional-files list, and
-    // completeness/budget notes can still push the assembled output past
-    // maxOutputChars (observed 30k against a 28k tier cap). A fat explore
-    // payload persists in the agent's context and is re-read as cache-input
-    // on every subsequent turn, so the overrun is paid many times over.
-    const output = lines.join('\n');
-    if (output.length > budget.maxOutputChars) {
-      const cut = output.slice(0, budget.maxOutputChars);
-      const lastNewline = cut.lastIndexOf('\n');
-      const safe = lastNewline > budget.maxOutputChars * 0.8 ? cut.slice(0, lastNewline) : cut;
-      return this.textResult(safe + '\n\n... (explore output truncated to budget — use codegraph_node or Read for more)');
+    // Final ceiling — an ABSOLUTE inline cap, not a multiple of the budget. The
+    // render loop renders necessary (named/spine) files even a bit past
+    // maxOutputChars and caps only incidental ones, so this is the last safety.
+    // It MUST stay under the host's inline tool-result limit (~25K chars): above
+    // that the result is externalized to a file the agent Reads back (a 35K
+    // vscode explore did exactly this in the n=4 A/B). So allow a little
+    // necessary overflow above the 24K budget, but hard-stop at 25K — never into
+    // externalize territory.
+    const output = flow.text + lines.join('\n');
+    const hardCeiling = Math.min(Math.round(budget.maxOutputChars * 1.5), 25000);
+    if (output.length > hardCeiling) {
+      // Cut at a FILE-SECTION boundary (the last `#### ` header before the
+      // ceiling) so we drop whole trailing file-sections rather than slicing
+      // through a method body — a half-rendered method just forces the Read this
+      // tool exists to prevent. Fall back to a line boundary only if no section
+      // header sits in the back half (degenerate single-giant-section case).
+      const cut = output.slice(0, hardCeiling);
+      const lastSection = cut.lastIndexOf('\n#### ');
+      const boundary = lastSection > hardCeiling * 0.5 ? lastSection : cut.lastIndexOf('\n');
+      const safe = boundary > 0 ? cut.slice(0, boundary) : cut;
+      return this.textResult(safe + '\n\n... (output truncated to budget; the source above is complete and verbatim — treat it as already Read. For any area not covered, run another codegraph_explore with the specific names — do NOT Read these files.)');
     }
     return this.textResult(output);
   }
@@ -1271,66 +2761,376 @@ export class ToolHandler {
    * Handle codegraph_node
    */
   private async handleNode(args: Record<string, unknown>): Promise<ToolResult> {
-    const symbol = this.validateString(args.symbol, 'symbol');
-    if (typeof symbol !== 'string') return symbol;
-
     const cg = this.getCodeGraph(args.projectPath as string | undefined);
     // Default to false to minimize context usage
     const includeCode = args.includeCode === true;
+    const fileHint = typeof args.file === 'string' && args.file.trim() ? args.file.trim() : undefined;
+    const lineHint = typeof args.line === 'number' && args.line > 0 ? args.line : undefined;
+    const offset = typeof args.offset === 'number' && args.offset > 0 ? Math.floor(args.offset) : undefined;
+    const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.floor(args.limit) : undefined;
+    const symbolsOnly = args.symbolsOnly === true;
+    const symbolRaw = typeof args.symbol === 'string' ? args.symbol.trim() : '';
+
+    // FILE READ MODE: a `file` with no `symbol` reads that file like the Read
+    // tool — its current on-disk source with line numbers, narrowable with
+    // `offset`/`limit` exactly as Read does — PLUS a one-line blast-radius
+    // header (which files depend on it). `symbolsOnly` returns just the
+    // structural map instead. Backed by the index: same bytes Read gives you.
+    if (!symbolRaw && fileHint) {
+      return this.handleFileView(cg, fileHint, { offset, limit, symbolsOnly });
+    }
 
-    const match = this.findSymbol(cg, symbol);
-    if (!match) {
+    const symbol = this.validateString(args.symbol, 'symbol');
+    if (typeof symbol !== 'string') return symbol;
+
+    let matches = this.findSymbolMatches(cg, symbol);
+    if (matches.length === 0) {
       return this.textResult(`Symbol "${symbol}" not found in the codebase`);
     }
 
+    // Disambiguate a heavily-overloaded name to a specific definition the caller
+    // pinned by file/line (the `file:line` a trail or another tool showed it) —
+    // so it can fetch e.g. `Harness::poll` at harness.rs:153 out of 50+ `poll`s
+    // instead of Reading. file matches by path suffix/substring; line prefers the
+    // def whose body contains it, else the nearest start. Only narrows (never
+    // empties — if a hint matches nothing it's ignored).
+    if (matches.length > 1 && (fileHint || lineHint !== undefined)) {
+      const norm = (p: string) => p.replace(/\\/g, '/').toLowerCase();
+      let narrowed = matches;
+      if (fileHint) {
+        const fh = norm(fileHint);
+        const byFile = narrowed.filter((n) => norm(n.filePath).endsWith(fh) || norm(n.filePath).includes(fh));
+        if (byFile.length > 0) narrowed = byFile;
+      }
+      if (lineHint !== undefined && narrowed.length > 1) {
+        const containing = narrowed.filter((n) => n.startLine <= lineHint && (n.endLine ?? n.startLine) >= lineHint);
+        narrowed = containing.length > 0
+          ? containing
+          : [...narrowed].sort((a, b) => Math.abs(a.startLine - lineHint) - Math.abs(b.startLine - lineHint)).slice(0, 1);
+      }
+      if (narrowed.length > 0) matches = narrowed;
+    }
+
+    // Single definition — the common case.
+    if (matches.length === 1) {
+      return this.textResult(this.truncateOutput(await this.renderNodeSection(cg, matches[0]!, includeCode)));
+    }
+
+    // Multiple definitions share this name — overloads, or same-named methods on
+    // different types (Alamofire `didCompleteTask`/`task`/`validate`, gin
+    // `reset`). Returning ONE forces the agent to guess, and when it guesses
+    // wrong it READS the file to find the right overload — the dominant
+    // codegraph_node read cause on Swift/Go. So return them ALL: pack as many
+    // FULL bodies as fit a char budget (the agent gets the one it needs in this
+    // one call, no follow-up parameter to learn), and list any remainder by
+    // file:line so a large overload set can't overflow the per-tool cap.
+    const header = `**${matches.length} definitions named "${symbol}"**`;
+    if (!includeCode) {
+      const list = matches.map((n) => `- \`${n.name}\` (${n.kind}) — ${n.filePath}:${n.startLine}`);
+      return this.textResult(this.truncateOutput(
+        [header, '', 'Re-query with `includeCode: true` to get every body in one call — no need to pick one first.', '', ...list].join('\n'),
+      ));
+    }
+
+    const BODY_BUDGET = 12000; // leaves room under MAX_OUTPUT_LENGTH for the header + list
+    // The CHAR budget is the real limiter — keep the count cap high so a set of
+    // SHORT overloads (Alamofire's 10 `validate` variants, each a few lines) all
+    // render in full rather than relegating the one the agent wanted to a
+    // bodiless list. Only a set of many LARGE bodies hits the char budget first.
+    const HARD_CAP = 16;
+    const rendered: string[] = [];
+    const listed: Node[] = [];
+    let used = 0;
+    for (const n of matches) {
+      if (rendered.length >= HARD_CAP) { listed.push(n); continue; }
+      const section = await this.renderNodeSection(cg, n, true);
+      // Always emit the first; emit the rest only while within the char budget.
+      if (rendered.length === 0 || used + section.length <= BODY_BUDGET) {
+        rendered.push(section);
+        used += section.length;
+      } else {
+        listed.push(n);
+      }
+    }
+
+    const out: string[] = [
+      header,
+      `Returning ${rendered.length} in full${listed.length ? `; ${listed.length} more listed below` : ''} — pick the one you need (no Read required).`,
+      '',
+      rendered.join('\n\n---\n\n'),
+    ];
+    if (listed.length) {
+      const LIST_CAP = 20;
+      const shownList = listed.slice(0, LIST_CAP);
+      out.push(
+        '',
+        '### Other definitions',
+        ...shownList.map((n) => `- \`${n.name}\` (${n.kind}) — ${n.filePath}:${n.startLine}`),
+      );
+      if (listed.length > LIST_CAP) out.push(`- … +${listed.length - LIST_CAP} more`);
+      out.push(
+        '',
+        `> Need one of these in full? Call codegraph_node again with \`file\` (e.g. \`"${listed[0]!.filePath.split('/').pop()}"\`) or \`line\` — do NOT Read it.`,
+      );
+    }
+    return this.textResult(this.truncateOutput(out.join('\n')));
+  }
+
+  /**
+   * FILE READ MODE: resolve `fileArg` (path or basename) to an indexed file and
+   * read it like the Read tool — its current on-disk source with line numbers,
+   * narrowable with `offset`/`limit` exactly as Read's are — preceded by a
+   * one-line blast-radius header (which files depend on it). `symbolsOnly`
+   * returns just the structural map (symbols + dependents) instead of source.
+   *
+   * Parity goal: the numbered source block is byte-for-byte the shape Read
+   * returns (`<n>\t<line>`, no padding), so the agent treats it as a Read — only
+   * faster (served from the index) and with the blast radius attached. Security:
+   * yaml/properties files are summarized by key, never dumped (#383); reads go
+   * through validatePathWithinRoot (#527).
+   */
+  private async handleFileView(
+    cg: CodeGraph,
+    fileArg: string,
+    opts: { offset?: number; limit?: number; symbolsOnly?: boolean } = {},
+  ): Promise<ToolResult> {
+    const normalize = (p: string) => p.replace(/\\/g, '/').replace(/^(?:\.?\/+)+/, '').replace(/\/+$/, '');
+    const wantLower = normalize(fileArg).toLowerCase();
+    const allFiles = cg.getFiles();
+    if (allFiles.length === 0) return this.textResult('No files indexed. Run `codegraph index` first.');
+
+    let resolved = allFiles.find((f) => f.path.toLowerCase() === wantLower);
+    let candidates: typeof allFiles = [];
+    if (!resolved) {
+      candidates = allFiles.filter((f) => f.path.toLowerCase().endsWith('/' + wantLower));
+      if (candidates.length === 1) resolved = candidates[0];
+    }
+    if (!resolved && candidates.length === 0) {
+      candidates = allFiles.filter((f) => f.path.toLowerCase().includes(wantLower));
+      if (candidates.length === 1) resolved = candidates[0];
+    }
+    if (!resolved && candidates.length > 1) {
+      return this.textResult(
+        [`"${fileArg}" matches ${candidates.length} indexed files — pass a longer path:`, '',
+          ...candidates.slice(0, 25).map((f) => `- ${f.path}`)].join('\n'),
+      );
+    }
+    if (!resolved) {
+      return this.textResult(
+        `No indexed file matches "${fileArg}". Codegraph indexes source files; configs/docs it doesn't parse won't appear — Read those directly.`,
+      );
+    }
+
+    const filePath = resolved.path;
+    const nodes = cg.getNodesInFile(filePath)
+      .filter((n) => n.kind !== 'file' && n.kind !== 'import' && n.kind !== 'export')
+      .sort((a, b) => a.startLine - b.startLine);
+    const dependents = cg.getFileDependents(filePath);
+
+    // Compact, one-line blast radius (codegraph's value-add over a plain Read).
+    const depSummary = dependents.length
+      ? `used by ${dependents.length} file${dependents.length === 1 ? '' : 's'}: ${dependents.slice(0, 8).join(', ')}${dependents.length > 8 ? `, +${dependents.length - 8} more` : ''}`
+      : 'no other indexed file depends on it';
+
+    // Symbol-map renderer — for symbolsOnly, the config fallback, and read errors.
+    const symbolMap = (heading: string, limit = 200): string[] => {
+      const lines: string[] = [heading];
+      for (const n of nodes.slice(0, limit)) {
+        const sig = n.signature ? ` ${n.signature.replace(/\s+/g, ' ').trim()}` : '';
+        lines.push(`- \`${n.name}\` (${n.kind})${sig} — :${n.startLine}`);
+      }
+      if (nodes.length > limit) lines.push(`- … +${nodes.length - limit} more`);
+      return lines;
+    };
+
+    // symbolsOnly → the cheap structural overview, no source.
+    if (opts.symbolsOnly) {
+      const out = [`**${filePath}** — ${nodes.length} symbol${nodes.length === 1 ? '' : 's'}, ${depSummary}`, ''];
+      if (nodes.length) out.push(...symbolMap('### Symbols'));
+      else out.push('_No indexed symbols in this file._');
+      out.push('', '> Drop `symbolsOnly` (or pass `offset`/`limit`) to read the source, like Read.');
+      return this.textResult(this.truncateOutput(out.join('\n')));
+    }
+
+    // SECURITY (#383): never dump a raw config/data file — a yaml/properties
+    // line is `key: <secret>`. Summarize by key and point to a real Read.
+    if (CONFIG_LEAF_LANGUAGES.has(resolved.language)) {
+      const out = [`**${filePath}** — configuration/data file, ${depSummary}`, ''];
+      if (nodes.length) out.push(...symbolMap('### Keys (values withheld for safety)'));
+      out.push('', '> Values may be secrets, so codegraph indexes keys only. Read the file directly if you need a value.');
+      return this.textResult(this.truncateOutput(out.join('\n')));
+    }
+
+    // Read the current bytes from disk through the security chokepoint
+    // (validatePathWithinRoot: blocks `../` traversal and symlink escapes, #527).
+    const abs = validatePathWithinRoot(cg.getProjectRoot(), filePath);
+    let content: string | null = null;
+    if (abs) {
+      try { content = readFileSync(abs, 'utf-8'); } catch { content = null; }
+    }
+    if (content === null) {
+      const out = [`**${filePath}** — could not read from disk (it may have moved since indexing). ${depSummary}`, ''];
+      if (nodes.length) out.push(...symbolMap('### Symbols'));
+      out.push('', `> Read \`${filePath}\` directly for its current content.`);
+      return this.textResult(this.truncateOutput(out.join('\n')));
+    }
+
+    // Split exactly as Read does — keep the trailing empty line a final newline
+    // produces (Read numbers it too), so line numbers line up byte-for-byte.
+    const fileLines = content.split('\n');
+    const total = fileLines.length;
+
+    // Read-parity windowing: `offset`/`limit` mean exactly what they do on Read
+    // (1-based start line; max line count). Default: the whole file, capped like
+    // Read at 2000 lines and bounded by a char budget that tracks explore's
+    // proven-safe ~38k response ceiling. Overflow is stated explicitly (Read
+    // paginates too) — never the silent 15k truncateOutput chop.
+    const CHAR_BUDGET = 38000;
+    const DEFAULT_LIMIT = 2000;
+    const offset = Math.max(1, opts.offset ?? 1);
+    if (offset > total) {
+      return this.textResult(`**${filePath}** has ${total} line${total === 1 ? '' : 's'} — offset ${offset} is past the end. ${depSummary}`);
+    }
+    const maxLines = Math.max(1, opts.limit ?? DEFAULT_LIMIT);
+    const start = offset - 1; // 0-based
+    const header = `**${filePath}** — ${total} lines, ${nodes.length} symbol${nodes.length === 1 ? '' : 's'} · ${depSummary}`;
+
+    // Numbered lines, byte-for-byte Read's shape: `<n>\t<line>`, no left-pad.
+    const numbered: string[] = [];
+    let used = header.length + 8;
+    let i = start;
+    for (; i < total && numbered.length < maxLines; i++) {
+      const ln = `${i + 1}\t${fileLines[i]}`;
+      if (used + ln.length + 1 > CHAR_BUDGET && numbered.length > 0) break;
+      numbered.push(ln);
+      used += ln.length + 1;
+    }
+    const shownEnd = start + numbered.length;
+    const complete = offset === 1 && shownEnd >= total;
+
+    const out: string[] = [header, '', ...numbered];
+    if (!complete) {
+      out.push(
+        '',
+        `(lines ${offset}–${shownEnd} of ${total} — pass \`offset\`/\`limit\` for another range, or \`codegraph_node <symbol>\` for one symbol in full)`,
+      );
+    }
+    // Self-bounded to CHAR_BUDGET — do NOT route through truncateOutput (15k).
+    return this.textResult(out.join('\n'));
+  }
+
+  /** Render one symbol: details + (optional) body/outline + its caller/callee trail. */
+  private async renderNodeSection(cg: CodeGraph, node: Node, includeCode: boolean): Promise<string> {
     let code: string | null = null;
     let outline: string | null = null;
-
     if (includeCode) {
       // For container symbols (class/interface/struct/…), the full body is the
-      // sum of every method body — a wall of source (e.g. a 10k-char class)
-      // that bloats context and is rarely needed in full. Return a structural
-      // outline (members + signatures + line numbers) instead; the agent can
-      // Read or codegraph_node a specific method for its body. Leaf symbols
-      // (function/method/etc.) return their full body as before.
-      if (CONTAINER_NODE_KINDS.has(match.node.kind)) {
-        outline = this.buildContainerOutline(cg, match.node);
+      // sum of every method body — a wall of source. Return a structural outline
+      // (members + signatures + line numbers) instead; leaf symbols return their
+      // full body.
+      if (CONTAINER_NODE_KINDS.has(node.kind)) {
+        outline = this.buildContainerOutline(cg, node);
       }
       if (!outline) {
-        code = await cg.getCode(match.node.id);
+        code = await cg.getCode(node.id);
       }
     }
+    return this.formatNodeDetails(node, code, outline) + this.formatTrail(cg, node);
+  }
 
-    const formatted = this.formatNodeDetails(match.node, code, outline) + match.note;
-    return this.textResult(this.truncateOutput(formatted));
+  /**
+   * Build the "trail" for a symbol: its direct callees (what it calls) and
+   * callers (what calls it), each with file:line — so codegraph_node doubles as
+   * the structural Grep→Read→expand primitive: a spot PLUS where to go next.
+   * Capped to stay cheap. Walk the graph by calling codegraph_node on a trail
+   * entry; no Read needed for covered hops. Empty edges on a non-leaf often mean
+   * dynamic dispatch the static graph couldn't resolve — that absence is itself
+   * a signal (read that one hop) rather than a dead end.
+   */
+  private formatTrail(cg: CodeGraph, node: Node): string {
+    const TRAIL_CAP = 12;
+    const fmt = (e: { node: Node; edge: Edge }) => {
+      const base = `${e.node.name} (${e.node.filePath}:${e.node.startLine})`;
+      const synth = this.synthEdgeNote(e.edge);
+      return synth ? `${base} [${synth.compact}]` : base;
+    };
+    const collect = (edges: Array<{ node: Node; edge: Edge }>): Array<{ node: Node; edge: Edge }> => {
+      const seen = new Set<string>([node.id]);
+      const out: Array<{ node: Node; edge: Edge }> = [];
+      for (const e of edges) {
+        if (seen.has(e.node.id)) continue;
+        seen.add(e.node.id);
+        out.push(e);
+      }
+      return out;
+    };
+    const callees = collect(cg.getCallees(node.id));
+    const callers = collect(cg.getCallers(node.id));
+    if (callees.length === 0 && callers.length === 0) return '';
+    const lines: string[] = ['', '### Trail — codegraph_node any of these to follow it (no Read needed)'];
+    if (callees.length > 0) {
+      lines.push(`**Calls →** ${callees.slice(0, TRAIL_CAP).map(fmt).join(', ')}${callees.length > TRAIL_CAP ? `, +${callees.length - TRAIL_CAP} more` : ''}`);
+    }
+    if (callers.length > 0) {
+      lines.push(`**Called by ←** ${callers.slice(0, TRAIL_CAP).map(fmt).join(', ')}${callers.length > TRAIL_CAP ? `, +${callers.length - TRAIL_CAP} more` : ''}`);
+    }
+    return lines.join('\n');
   }
 
   /**
    * Handle codegraph_status
    */
   private async handleStatus(args: Record<string, unknown>): Promise<ToolResult> {
-    const cg = this.getCodeGraph(args.projectPath as string | undefined);
+    let cg = this.getCodeGraph(args.projectPath as string | undefined);
+    // Same trick as withStalenessNotice — when an explicit projectPath
+    // resolves to the same project as the default session cg, prefer the
+    // default so getPendingFiles() (only populated by the default's watcher)
+    // is non-empty when there are pending edits.
+    if (this.cg && cg !== this.cg) {
+      try {
+        if (resolvePath(this.cg.getProjectRoot()) === resolvePath(cg.getProjectRoot())) {
+          cg = this.cg;
+        }
+      } catch { /* closed instance — leave as is */ }
+    }
     const stats = cg.getStats();
 
+    // Warn when this index actually belongs to a different git working tree
+    // (e.g. the server resolved up from a nested worktree to the main checkout).
+    // Queries then reflect that tree's branch, not the worktree being edited.
+    // status shows the verbose, multi-line form; the read tools get the compact
+    // one-liner via withWorktreeNotice. Both share the cached detection.
+    const mismatch = this.worktreeMismatchFor(args.projectPath as string | undefined);
+
     const lines: string[] = [
       '## CodeGraph Status',
       '',
+    ];
+    if (mismatch) {
+      lines.push(`> ⚠ ${worktreeMismatchWarning(mismatch).replace(/\n/g, '\n> ')}`, '');
+    }
+    lines.push(
       `**Files indexed:** ${stats.fileCount}`,
       `**Total nodes:** ${stats.nodeCount}`,
       `**Total edges:** ${stats.edgeCount}`,
       `**Database size:** ${(stats.dbSizeBytes / 1024 / 1024).toFixed(2)} MB`,
-    ];
+    );
 
-    // Surface the active SQLite backend. Without this, users on the
-    // silent WASM fallback (better-sqlite3 install failed) see "slow"
-    // indexing and DB-lock errors with no signal of why.
-    const backend = cg.getBackend();
-    if (backend === 'native') {
-      lines.push(`**Backend:** native (better-sqlite3)`);
+    // Surface the active SQLite backend (node:sqlite, Node's built-in real
+    // SQLite — full WAL + FTS5, no native build).
+    lines.push(`**Backend:** node:sqlite (Node built-in) — full WAL + FTS5`);
+
+    // Effective journal mode. 'wal' ⇒ concurrent reads never block on a writer;
+    // anything else ⇒ they can ("database is locked"). node:sqlite supports WAL
+    // everywhere, so a non-wal mode means the filesystem can't (network/
+    // virtualized mounts, WSL2 /mnt). See issue #238.
+    const journalMode = cg.getJournalMode();
+    if (journalMode === 'wal') {
+      lines.push(`**Journal mode:** wal (concurrent reads safe)`);
     } else {
       lines.push(
-        `**Backend:** ⚠ wasm (better-sqlite3 unavailable) — ` +
-        `5-10x slower than native. Fix: ${WASM_FALLBACK_FIX_RECIPE}`
+        `**Journal mode:** ⚠ ${journalMode || 'unknown'} — WAL not active, so reads ` +
+        `can block on a concurrent write (WAL appears unsupported on this filesystem)`
       );
     }
 
@@ -1349,6 +3149,21 @@ export class ToolHandler {
       }
     }
 
+    // Per-file freshness — the inverse of the auto-prepended staleness banner
+    // (issue #403). Surfacing it inside `status` gives the agent a single
+    // place to ask "is the index caught up?" rather than inferring from
+    // banners on other tool calls.
+    const pending = cg.getPendingFiles();
+    if (pending.length > 0) {
+      lines.push('', '### Pending sync:');
+      const now = Date.now();
+      for (const p of pending) {
+        const ageMs = Math.max(0, now - p.lastSeenMs);
+        const label = p.indexing ? 'indexing in progress' : 'pending sync';
+        lines.push(`- ${p.path} (edited ${ageMs}ms ago, ${label})`);
+      }
+    }
+
     return this.textResult(lines.join('\n'));
   }
 
@@ -1370,9 +3185,20 @@ export class ToolHandler {
       return this.textResult('No files indexed. Run `codegraph index` first.');
     }
 
-    // Filter by path prefix
-    let files = pathFilter
-      ? allFiles.filter(f => f.path.startsWith(pathFilter) || f.path.startsWith('./' + pathFilter))
+    // Filter by path prefix. Stored paths are project-relative POSIX (e.g.
+    // "src/foo.ts"), but agents commonly pass project-root variants like "/",
+    // ".", "./", "" or Windows-style "src\foo" — and prefixes with leading
+    // "/", "./" or "\". Normalize all of those before matching so the agent
+    // gets results instead of falling back to Read/Glob (see #426).
+    const normalizedFilter = pathFilter
+      ? pathFilter
+          .replace(/\\/g, '/')
+          .replace(/^(?:\.?\/+)+/, '')
+          .replace(/^\.$/, '')
+          .replace(/\/+$/, '')
+      : '';
+    let files = normalizedFilter
+      ? allFiles.filter(f => f.path === normalizedFilter || f.path.startsWith(normalizedFilter + '/'))
       : allFiles;
 
     // Filter by glob pattern
@@ -1603,48 +3429,59 @@ export class ToolHandler {
     );
   }
 
-  private findSymbol(cg: CodeGraph, symbol: string): { node: Node; note: string } | null {
-    // Use higher limit for qualified lookups (e.g., "Session.request",
-    // "stage_apply::run") since the target may rank lower in FTS when
-    // there are many partial matches across the qualifier parts.
+  /**
+   * Find ALL definitions matching a name, ranked, so codegraph_node can return
+   * every overload instead of guessing one (the wrong guess → a Read). Keepers
+   * rank before generated stubs (.pb.go etc.); stable within a group preserves
+   * FTS order. Returns [] when nothing matches; a qualified lookup that finds no
+   * exact match returns [] rather than a misleading fuzzy file hit (#173); a
+   * bare name with no exact match falls back to the single top fuzzy result.
+   */
+  private findSymbolMatches(cg: CodeGraph, symbol: string): Node[] {
     const isQualified = /[.\/]|::/.test(symbol);
-    const limit = isQualified ? 50 : 10;
+
+    // For a bare name, enumerate EVERY exact-name definition via the direct index
+    // (not FTS, which caps + ranks): tokio's `poll` has 50+ defs and the one the
+    // caller wants (`Harness::poll` at harness.rs:153) ranks below any search cut,
+    // so it could be neither rendered nor pinned by the file/line disambiguator —
+    // and the agent Read it. With the full set, the multi-overload render + the
+    // file/line filter can both reach it.
+    if (!isQualified) {
+      const exact = cg.getNodesByName(symbol);
+      if (exact.length > 0) {
+        return [...exact].sort((a, b) => (isGeneratedFile(a.filePath) ? 1 : 0) - (isGeneratedFile(b.filePath) ? 1 : 0));
+      }
+      // No exact match — use the single top fuzzy result (e.g. a file basename).
+      const fuzzy = cg.searchNodes(symbol, { limit: 10 });
+      return fuzzy[0] ? [fuzzy[0].node] : [];
+    }
+
+    // Qualified lookup (`Session.request`, `stage_apply::run`): FTS + matchesSymbol.
+    const limit = 50;
     let results = cg.searchNodes(symbol, { limit });
 
-    // FTS strips colons as a special char, so `stage_apply::run` searches
-    // for the literal `stage_applyrun` and finds nothing. Re-search by
-    // the bare last part and let `matchesSymbol` filter by qualifier.
+    // FTS strips colons, so `stage_apply::run` searches the literal
+    // `stage_applyrun` and finds nothing. Re-search by the bare last part and
+    // let `matchesSymbol` filter by qualifier.
     if (isQualified && results.length === 0) {
       const tail = lastQualifierPart(symbol);
       if (tail && tail !== symbol) results = cg.searchNodes(tail, { limit });
     }
 
-    if (results.length === 0 || !results[0]) {
-      return null;
-    }
-
-    const exactMatches = results.filter(r => this.matchesSymbol(r.node, symbol));
+    if (results.length === 0) return [];
 
-    if (exactMatches.length === 1) {
-      return { node: exactMatches[0]!.node, note: '' };
+    const exactMatches = results.filter((r) => this.matchesSymbol(r.node, symbol));
+    if (exactMatches.length === 0) {
+      // No exact match — a qualified lookup must not fall back to a fuzzy file
+      // hit (#173); a bare name may use the single top fuzzy result.
+      return isQualified ? [] : results[0] ? [results[0].node] : [];
     }
 
-    if (exactMatches.length > 1) {
-      // Multiple exact matches - pick first, note the others
-      const picked = exactMatches[0]!.node;
-      const others = exactMatches.slice(1).map(r =>
-        `${r.node.name} (${r.node.kind}) at ${r.node.filePath}:${r.node.startLine}`
-      );
-      const note = `\n\n> **Note:** ${exactMatches.length} symbols named "${symbol}". Showing results for \`${picked.filePath}:${picked.startLine}\`. Others: ${others.join(', ')}`;
-      return { node: picked, note };
-    }
-
-    // No exact match. For qualified lookups, don't silently fall back
-    // to a fuzzy result — the user typed a specific qualifier, and
-    // resolving `stage_apply::nonexistent_fn` to the unrelated
-    // `stage_apply.rs` file would be actively misleading (#173).
-    if (isQualified) return null;
-    return { node: results[0]!.node, note: '' };
+    // Down-rank generated files (.pb.go, .pulsar.go, _grpc.pb.go, …) so a flow
+    // query prefers the keeper implementation over the protobuf-generated stub.
+    return [...exactMatches]
+      .sort((a, b) => (isGeneratedFile(a.node.filePath) ? 1 : 0) - (isGeneratedFile(b.node.filePath) ? 1 : 0))
+      .map((r) => r.node);
   }
 
   /**
@@ -1673,11 +3510,20 @@ export class ToolHandler {
       return { nodes: [node], note: '' };
     }
 
-    const locations = exactMatches.map(r =>
+    // Same generated-file down-rank as findSymbol — keeps callers/callees
+    // /impact aggregation aligned (a query against "Send" returns the
+    // hand-written implementations before the protobuf scaffold).
+    const ranked = [...exactMatches].sort((a, b) => {
+      const aGen = isGeneratedFile(a.node.filePath) ? 1 : 0;
+      const bGen = isGeneratedFile(b.node.filePath) ? 1 : 0;
+      return aGen - bGen;
+    });
+
+    const locations = ranked.map(r =>
       `${r.node.kind} at ${r.node.filePath}:${r.node.startLine}`
     );
-    const note = `\n\n> **Note:** Aggregated results across ${exactMatches.length} symbols named "${symbol}": ${locations.join(', ')}`;
-    return { nodes: exactMatches.map(r => r.node), note };
+    const note = `\n\n> **Note:** Aggregated results across ${ranked.length} symbols named "${symbol}": ${locations.join(', ')}`;
+    return { nodes: ranked.map(r => r.node), note };
   }
 
   /**
@@ -1711,18 +3557,37 @@ export class ToolHandler {
     return lines.join('\n');
   }
 
-  private formatNodeList(nodes: Node[], title: string): string {
+  private formatNodeList(nodes: Node[], title: string, labels?: Map<string, string>): string {
     const lines: string[] = [`## ${title} (${nodes.length} found)`, ''];
 
     for (const node of nodes) {
       const location = node.startLine ? `:${node.startLine}` : '';
-      // Compact: just name, kind, location
-      lines.push(`- ${node.name} (${node.kind}) - ${node.filePath}${location}`);
+      // Compact: just name, kind, location — plus the relationship when it
+      // isn't a plain call (callback registration, instantiation, …).
+      const label = labels?.get(node.id);
+      lines.push(
+        `- ${node.name} (${node.kind}) - ${node.filePath}${location}${label ? ` — via ${label}` : ''}`
+      );
     }
 
     return lines.join('\n');
   }
 
+  /**
+   * Relationship label for a non-`calls` edge in callers/callees lists. A
+   * function-as-value edge (#756) is the high-signal one: `callers(cb)`
+   * showing "via callback registration" tells the agent this is where the
+   * callback is WIRED, not where it's invoked.
+   */
+  private edgeLabel(edge: Edge): string | null {
+    if (edge.kind === 'calls') return null;
+    if (edge.metadata?.fnRef === true) return 'callback registration';
+    if (edge.kind === 'instantiates') return 'instantiation';
+    if (edge.kind === 'imports') return 'import';
+    if (edge.kind === 'references') return 'reference';
+    return edge.kind;
+  }
+
   private formatImpact(symbol: string, impact: Subgraph): string {
     const nodeCount = impact.nodes.size;
 
@@ -1794,16 +3659,15 @@ export class ToolHandler {
       lines.push('', outline, '',
         `> Structural outline only. Read \`${node.filePath}\` or call codegraph_node on a specific member for its body.`);
     } else if (code) {
-      lines.push('', '```' + node.language, code, '```');
+      // Line-numbered (cat -n style, like codegraph_explore and Read) so the
+      // agent can cite/edit exact lines without re-Reading the file for them.
+      const numbered = node.startLine ? numberSourceLines(code, node.startLine) : code;
+      lines.push('', '```' + node.language, numbered, '```');
     }
 
     return lines.join('\n');
   }
 
-  private formatTaskContext(context: TaskContext): string {
-    return context.summary || 'No context found';
-  }
-
   private textResult(text: string): ToolResult {
     return {
       content: [{ type: 'text', text }],
diff --git a/src/mcp/transport.ts b/src/mcp/transport.ts
index 2638600d6..de1038be5 100644
--- a/src/mcp/transport.ts
+++ b/src/mcp/transport.ts
@@ -1,10 +1,21 @@
 /**
- * MCP Stdio Transport
+ * MCP JSON-RPC Transports
  *
- * Handles JSON-RPC 2.0 communication over stdin/stdout for MCP protocol.
+ * Two flavors share the same wire format (newline-delimited JSON-RPC 2.0):
+ *
+ * - `StdioTransport` — original transport; reads/writes the process's
+ *   stdin/stdout. Used by direct-mode MCP servers.
+ * - `SocketTransport` — wraps a single `net.Socket`. Used by the shared-daemon
+ *   architecture (see {@link ./daemon}) to multiplex multiple MCP clients onto
+ *   one CodeGraph instance via per-connection sessions.
+ *
+ * Both implement {@link JsonRpcTransport} so the session-level protocol logic
+ * (initialize / tools/list / tools/call, plus server-initiated `roots/list`)
+ * is identical regardless of where the bytes come from.
  */
 
 import * as readline from 'readline';
+import type { Socket } from 'net';
 
 /**
  * JSON-RPC 2.0 Request
@@ -56,56 +67,41 @@ export const ErrorCodes = {
 export type MessageHandler = (message: JsonRpcRequest | JsonRpcNotification) => Promise<void>;
 
 /**
- * Stdio Transport for MCP
- *
- * Reads JSON-RPC messages from stdin and writes responses to stdout.
+ * Generic JSON-RPC transport interface — common surface for stdio and socket
+ * carriers. Anything below the session layer (initialize, tool dispatch, etc.)
+ * talks to this, not to a concrete transport class.
  */
-export class StdioTransport {
-  private rl: readline.Interface | null = null;
-  private messageHandler: MessageHandler | null = null;
+export interface JsonRpcTransport {
+  start(handler: MessageHandler): void;
+  stop(): void;
+  send(response: JsonRpcResponse): void;
+  notify(method: string, params?: unknown): void;
+  request(method: string, params?: unknown, timeoutMs?: number): Promise<unknown>;
+  sendResult(id: string | number, result: unknown): void;
+  sendError(id: string | number | null, code: number, message: string, data?: unknown): void;
+}
+
+/**
+ * Shared implementation of newline-delimited JSON-RPC 2.0 over any
+ * `Readable`/`Writable` stream pair. Stdio and socket transports both wrap
+ * this — the only difference between them is which streams get plugged in
+ * and how a "close" propagates back to the owning code.
+ */
+abstract class LineBasedJsonRpcTransport implements JsonRpcTransport {
+  protected messageHandler: MessageHandler | null = null;
   // Outstanding server-initiated requests (e.g. roots/list), keyed by the id
   // we sent. Responses from the client are matched back here.
-  private pending = new Map<string | number, {
+  protected pending = new Map<string | number, {
     resolve: (value: unknown) => void;
     reject: (error: Error) => void;
   }>();
-  private nextRequestId = 1;
-
-  /**
-   * Start listening for messages on stdin
-   */
-  start(handler: MessageHandler): void {
-    this.messageHandler = handler;
-
-    this.rl = readline.createInterface({
-      input: process.stdin,
-      output: process.stdout,
-      terminal: false,
-    });
+  protected nextRequestId = 1;
+  protected stopped = false;
 
-    this.rl.on('line', async (line) => {
-      await this.handleLine(line);
-    });
-
-    this.rl.on('close', () => {
-      process.exit(0);
-    });
-  }
-
-  /**
-   * Stop listening
-   */
-  stop(): void {
-    // Fail any in-flight server-initiated requests so their awaiters don't hang.
-    for (const { reject } of this.pending.values()) {
-      reject(new Error('Transport stopped'));
-    }
-    this.pending.clear();
-    if (this.rl) {
-      this.rl.close();
-      this.rl = null;
-    }
-  }
+  abstract start(handler: MessageHandler): void;
+  protected abstract write(line: string): void;
+  protected abstract idPrefix(): string;
+  abstract stop(): void;
 
   /**
    * Send a server-initiated request to the client and await its response.
@@ -116,7 +112,7 @@ export class StdioTransport {
    * on timeout so callers can fall back rather than hang forever.
    */
   request(method: string, params?: unknown, timeoutMs = 5000): Promise<unknown> {
-    const id = `cg-srv-${this.nextRequestId++}`;
+    const id = `${this.idPrefix()}-${this.nextRequestId++}`;
     return new Promise<unknown>((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(id);
@@ -128,56 +124,42 @@ export class StdioTransport {
         resolve: (value) => { clearTimeout(timer); resolve(value); },
         reject: (error) => { clearTimeout(timer); reject(error); },
       });
-      process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+      this.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
     });
   }
 
-  /**
-   * Send a response
-   */
   send(response: JsonRpcResponse): void {
-    const json = JSON.stringify(response);
-    process.stdout.write(json + '\n');
+    this.write(JSON.stringify(response));
   }
 
-  /**
-   * Send a notification (no id)
-   */
   notify(method: string, params?: unknown): void {
-    const notification: JsonRpcNotification = {
-      jsonrpc: '2.0',
-      method,
-      params,
-    };
-    process.stdout.write(JSON.stringify(notification) + '\n');
+    const notification: JsonRpcNotification = { jsonrpc: '2.0', method, params };
+    this.write(JSON.stringify(notification));
   }
 
-  /**
-   * Send a success response
-   */
   sendResult(id: string | number, result: unknown): void {
-    this.send({
-      jsonrpc: '2.0',
-      id,
-      result,
-    });
+    this.send({ jsonrpc: '2.0', id, result });
+  }
+
+  sendError(id: string | number | null, code: number, message: string, data?: unknown): void {
+    this.send({ jsonrpc: '2.0', id, error: { code, message, data } });
   }
 
   /**
-   * Send an error response
+   * Fail any in-flight server-initiated requests so their awaiters don't hang.
+   * Called from `stop()` in subclasses.
    */
-  sendError(id: string | number | null, code: number, message: string, data?: unknown): void {
-    this.send({
-      jsonrpc: '2.0',
-      id,
-      error: { code, message, data },
-    });
+  protected rejectPending(reason: string): void {
+    for (const { reject } of this.pending.values()) {
+      reject(new Error(reason));
+    }
+    this.pending.clear();
   }
 
   /**
-   * Handle an incoming line of JSON
+   * Handle an incoming line of JSON. Both transports feed lines here.
    */
-  private async handleLine(line: string): Promise<void> {
+  protected async handleLine(line: string): Promise<void> {
     const trimmed = line.trim();
     if (!trimmed) return;
 
@@ -254,3 +236,184 @@ export class StdioTransport {
     return true;
   }
 }
+
+export interface StdioTransportOptions {
+  /**
+   * If true, the transport calls `process.exit(0)` when stdin closes. Set to
+   * `false` in shared-daemon mode where the stdio "session" is just *one* of
+   * many clients — losing it shouldn't drag the daemon down. The default
+   * (true) matches the original single-process behavior callers rely on.
+   */
+  exitOnClose?: boolean;
+  /**
+   * Optional callback fired when the stdin stream closes. The daemon uses
+   * this to decrement its connected-clients refcount.
+   */
+  onClose?: () => void;
+}
+
+/**
+ * Stdio Transport for MCP
+ *
+ * Reads JSON-RPC messages from stdin and writes responses to stdout. Used by
+ * the direct (single-process) MCP server path, where the MCP host launches
+ * one server per session and talks to it over the child's stdio. Also used by
+ * shared-daemon mode for the launcher's session (with `exitOnClose: false`)
+ * so the daemon outlives its launcher.
+ */
+export class StdioTransport extends LineBasedJsonRpcTransport {
+  private rl: readline.Interface | null = null;
+  private opts: Required<StdioTransportOptions>;
+
+  constructor(opts: StdioTransportOptions = {}) {
+    super();
+    this.opts = {
+      exitOnClose: opts.exitOnClose ?? true,
+      onClose: opts.onClose ?? (() => { /* no-op */ }),
+    };
+  }
+
+  start(handler: MessageHandler): void {
+    this.messageHandler = handler;
+
+    this.rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      terminal: false,
+    });
+
+    this.rl.on('line', async (line) => {
+      await this.handleLine(line);
+    });
+
+    // readline 'close' fires on a clean stdin EOF. But a socket-backed stdin
+    // (the VS Code stdio shape) can fail with an 'error' (ECONNRESET/hangup)
+    // that readline doesn't surface as 'close' — unhandled, it escalated to
+    // the global uncaughtException handler (which keeps running), orphaning
+    // the server and, on Linux, busy-spinning a POLLHUP fd at 100% CPU. Treat
+    // 'error' as terminal too, and destroy stdin so the fd leaves epoll (#799).
+    let closed = false;
+    const onStreamEnd = (): void => {
+      if (closed) return;
+      closed = true;
+      try { process.stdin.destroy(); } catch { /* already gone */ }
+      this.opts.onClose();
+      if (this.opts.exitOnClose) {
+        process.exit(0);
+      }
+    };
+    this.rl.on('close', onStreamEnd);
+    process.stdin.on('error', onStreamEnd);
+  }
+
+  stop(): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.rejectPending('Transport stopped');
+    if (this.rl) {
+      this.rl.close();
+      this.rl = null;
+    }
+  }
+
+  protected write(line: string): void {
+    process.stdout.write(line + '\n');
+  }
+
+  protected idPrefix(): string {
+    return 'cg-srv';
+  }
+}
+
+/**
+ * Socket Transport for MCP daemon sessions.
+ *
+ * Wraps a single `net.Socket` (Unix domain socket on POSIX, named pipe on
+ * Windows). One instance per connected MCP client. Unlike {@link StdioTransport},
+ * `stop()` and stream-close *don't* call `process.exit` — a daemon-side session
+ * ending must not bring down the whole daemon.
+ */
+export class SocketTransport extends LineBasedJsonRpcTransport {
+  private buffer = '';
+  private closeHandlers: Array<() => void> = [];
+
+  constructor(private socket: Socket, private prefix: string = 'cg-sock') {
+    super();
+  }
+
+  /**
+   * Register a callback fired exactly once when the socket closes (from either
+   * side). Used by the daemon to decrement its connected-clients refcount.
+   */
+  onClose(handler: () => void): void {
+    this.closeHandlers.push(handler);
+  }
+
+  start(handler: MessageHandler): void {
+    this.messageHandler = handler;
+
+    this.socket.setEncoding('utf8');
+    this.socket.on('data', (chunk: string) => {
+      this.buffer += chunk;
+      let idx;
+      // Drain every complete line; tail-fragment stays in the buffer for the
+      // next chunk. The handler is async but we don't await it here — JSON-RPC
+      // permits out-of-order responses, and serializing here would deadlock if
+      // a handler issued a server-initiated request that needed a *later* line
+      // to arrive (e.g. roots/list mid-tools-call).
+      while ((idx = this.buffer.indexOf('\n')) !== -1) {
+        const line = this.buffer.slice(0, idx);
+        this.buffer = this.buffer.slice(idx + 1);
+        void this.handleLine(line);
+      }
+    });
+
+    this.socket.on('close', () => this.handleSocketClose());
+    this.socket.on('error', (err) => {
+      // Don't crash the daemon over a broken pipe; just shut this connection.
+      process.stderr.write(`[CodeGraph daemon] socket error: ${err.message}\n`);
+      this.handleSocketClose();
+    });
+  }
+
+  stop(): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.rejectPending('Transport stopped');
+    if (!this.socket.destroyed) {
+      this.socket.end();
+      this.socket.destroy();
+    }
+  }
+
+  /**
+   * Write a one-shot line directly to the socket (no JSON-RPC framing applied
+   * by this class — caller produces the line). The daemon uses this for the
+   * hello/handshake line that precedes the JSON-RPC stream.
+   */
+  writeRaw(line: string): void {
+    if (!this.socket.destroyed) {
+      this.socket.write(line.endsWith('\n') ? line : line + '\n');
+    }
+  }
+
+  protected write(line: string): void {
+    if (!this.socket.destroyed) {
+      this.socket.write(line + '\n');
+    }
+  }
+
+  protected idPrefix(): string {
+    return this.prefix;
+  }
+
+  private handleSocketClose(): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    this.rejectPending('Socket closed');
+    for (const h of this.closeHandlers) {
+      try { h(); } catch { /* never let a close-handler take the daemon down */ }
+    }
+    this.closeHandlers = [];
+  }
+}
diff --git a/src/mcp/version.ts b/src/mcp/version.ts
new file mode 100644
index 000000000..cef1b7834
--- /dev/null
+++ b/src/mcp/version.ts
@@ -0,0 +1,36 @@
+/**
+ * Resolved package version, computed once at module load.
+ *
+ * The version string is the rendezvous datum between cooperating daemon and
+ * proxy processes: the daemon advertises its version in the hello line, and
+ * the proxy refuses to share IPC across a mismatch (falls back to direct
+ * mode). Keeping the resolution in one place avoids drift between the CLI
+ * `--version` output (which reads `package.json` directly) and the daemon
+ * handshake.
+ *
+ * Resolution strategy: read the bundled `package.json` two levels up from
+ * this file — same relative position whether we're loaded from `src/mcp/` or
+ * the `dist/mcp/` output, since `tsc` preserves the layout. If reading fails
+ * (e.g. the package was unpacked oddly), fall back to "0.0.0-unknown" — a
+ * sentinel that will never match a real version, so the proxy harmlessly
+ * falls back to direct mode.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+function readPackageVersion(): string {
+  try {
+    const pkgPath = path.join(__dirname, '..', '..', 'package.json');
+    const raw = fs.readFileSync(pkgPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.version === 'string' && parsed.version.length > 0) {
+      return parsed.version;
+    }
+  } catch {
+    // Fall through to sentinel.
+  }
+  return '0.0.0-unknown';
+}
+
+export const CodeGraphPackageVersion = readPackageVersion();
diff --git a/src/resolution/callback-synthesizer.ts b/src/resolution/callback-synthesizer.ts
new file mode 100644
index 000000000..ad3f61213
--- /dev/null
+++ b/src/resolution/callback-synthesizer.ts
@@ -0,0 +1,1721 @@
+/**
+ * Callback / observer edge synthesis — Phase 1 + 2.
+ *
+ * Closes dynamic-dispatch holes where a dispatcher invokes callbacks registered
+ * elsewhere. Two channel shapes:
+ *
+ *  (1) Field-backed observer (Phase 1):
+ *      onUpdate(cb) { this.callbacks.add(cb); }            // registrar
+ *      triggerUpdate() { for (cb of this.callbacks) cb(); } // dispatcher
+ *      scene.onUpdate(this.triggerRender)                  // registration
+ *      → synthesize triggerUpdate → triggerRender
+ *
+ *  (2) String-keyed EventEmitter (Phase 2):
+ *      this.on('mount', function onmount(){...})           // registration
+ *      fn.emit('mount', this)                              // dispatch
+ *      → synthesize (method containing emit('mount')) → onmount
+ *
+ * Whole-graph pass after base resolution. High-precision/low-recall by design:
+ * named callbacks only; field channels paired by file+field; EventEmitter
+ * channels capped by event fan-out (generic names like 'error' skipped — they
+ * need receiver-type matching, deferred to Phase 3). All synthesized edges are
+ * tagged `provenance:'heuristic'`. See docs/design/callback-edge-synthesis.md.
+ */
+import type { Edge, Node, NodeKind } from '../types';
+import type { QueryBuilder } from '../db/queries';
+import type { ResolutionContext } from './types';
+import { isGeneratedFile } from '../extraction/generated-detection';
+import { stripCommentsForRegex } from './strip-comments';
+
+const REGISTRAR_NAME = /^(on[A-Z]\w*|subscribe|addListener|addEventListener|register|watch|listen|addCallback)$/;
+const DISPATCHER_NAME = /(emit|trigger|notify|dispatch|fire|publish|flush)/i;
+const MAX_CALLBACKS_PER_CHANNEL = 40;
+const EVENT_FANOUT_CAP = 6; // skip events with more handlers/dispatchers than this (too generic without type info)
+
+const ON_RE = /\.(?:on|once|addListener)\(\s*['"]([^'"]+)['"]\s*,\s*(?:function\s+(\w+)|(?:this\.)?(\w+))/g;
+const EMIT_RE = /\.(?:emit|fire|dispatchEvent)\(\s*['"]([^'"]+)['"]/g;
+const SETSTATE_RE = /this\.setState\s*\(/;
+const FLUTTER_SETSTATE_RE = /\bsetState\s*\(/; // Flutter: setState((){…}) / this.setState
+const JSX_TAG_RE = /<([A-Z][A-Za-z0-9_]*)[\s/>]/g;
+const MAX_JSX_CHILDREN = 30;
+// Vue SFC templates: kebab-case child components (<el-button> → ElButton) and
+// event bindings (@click="fn" / v-on:click="fn"). PascalCase children (<VPNav/>)
+// are already caught by JSX_TAG_RE via the SFC component node.
+const VUE_KEBAB_RE = /<([a-z][a-z0-9]*(?:-[a-z0-9]+)+)[\s/>]/g;
+// PascalCase component tags — `<MediaCard ...>`, `<NavBar/>`. HTML elements are
+// lowercase, so an uppercase-initial tag is a component usage; built-ins
+// (`<NuxtLink>`, `<Transition>`) simply resolve to nothing and emit no edge.
+const VUE_PASCAL_RE = /<([A-Z][A-Za-z0-9]*)[\s/>]/g;
+const VUE_HANDLER_RE = /(?:@|v-on:)([a-zA-Z][\w-]*)(?:\.[\w]+)*\s*=\s*"([^"]+)"/g;
+// Composable/hook destructure: `const { close: closeSidebar } = useSidebarControl()`.
+// Captures the destructure body + the called composable; only `use*` calls qualify.
+const VUE_DESTRUCTURE_RE = /(?:const|let|var)\s*\{([^}]+)\}\s*=\s*(\w+)\s*\(/g;
+
+// Closure-collection dynamic dispatch (language-agnostic, Swift-first). A method
+// appends a closure to a collection property; another method iterates that
+// property *invoking each element* (`coll.forEach { $0() }` / `{ it() }`). The
+// element-invoke (`$0(` / `it(`) PROVES the collection holds closures, so pairing
+// a dispatcher to same-named registrars (`.append`/`.add`/`.push`/`.insert`,
+// incl. Swift `prop.write { $0.append }`) is high-precision. Cross-file/class by
+// design: Alamofire appends in `DataRequest.validate` but iterates in the base
+// `Request.didCompleteTask` — neither same-file nor same-class pairing reaches it.
+const CC_DISPATCH_RE = /(\w+)\.forEach\s*\{\s*(?:\$0|it)\s*\(/g;
+const CC_APPEND_WRITE_RE = /(\w+)\.write\s*\{\s*\$0(?:\.(\w+))?\.(?:append|add|push|insert)\s*\(/g;
+const CC_APPEND_DIRECT_RE = /(\w+)\.(?:append|add|push|insert)\s*\(/g;
+const CC_FANOUT_CAP = 8; // skip a field name with more dispatchers/registrars than this (too generic to pair confidently)
+
+function kebabToPascal(s: string): string {
+  return s.split('-').map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join('');
+}
+
+/**
+ * Nuxt auto-import name for a component, derived from its path UNDER `components/`:
+ * `components/media/Card.vue` → `MediaCard`, `components/base/foo/Bar.vue` →
+ * `BaseFooBar`. Each directory segment and the filename is PascalCased and
+ * concatenated; a directory whose PascalCase name prefixes the next segment is
+ * collapsed (Nuxt's de-dup: `base/BaseButton.vue` → `BaseButton`, not
+ * `BaseBaseButton`). Returns null for a flat component (`components/NavBar.vue`)
+ * — its node is already named by basename, so a direct tag match finds it.
+ */
+function nuxtComponentName(filePath: string): string | null {
+  const marker = filePath.lastIndexOf('components/');
+  if (marker === -1) return null;
+  const rel = filePath.slice(marker + 'components/'.length).replace(/\.(vue|ts|tsx|js|jsx)$/i, '');
+  const segs = rel.split('/').filter(Boolean).map(kebabToPascal);
+  if (segs.length < 2) return null;
+  const out: string[] = [];
+  for (const s of segs) {
+    const prev = out[out.length - 1];
+    if (prev && s.startsWith(prev)) out[out.length - 1] = s;
+    else out.push(s);
+  }
+  return out.join('');
+}
+
+function sliceLines(content: string, startLine?: number, endLine?: number): string | null {
+  if (!startLine || !endLine) return null;
+  return content.split('\n').slice(startLine - 1, endLine).join('\n');
+}
+
+function registrarField(src: string): string | null {
+  const m = src.match(/this\.(\w+)\.(?:add|push|set)\(/);
+  return m ? m[1]! : null;
+}
+
+function dispatcherField(src: string): string | null {
+  const forOf = src.match(/\bof\s+(?:Array\.from\(\s*)?this\.(\w+)/);
+  if (forOf && /\b\w+\s*\(/.test(src)) return forOf[1]!;
+  const forEach = src.match(/this\.(\w+)\.forEach\(/);
+  if (forEach) return forEach[1]!;
+  return null;
+}
+
+const FN_KINDS = new Set(['method', 'function', 'component']);
+
+/** Innermost function/method node whose line range contains `line`. */
+function enclosingFn(nodesInFile: Node[], line: number): Node | null {
+  let best: Node | null = null;
+  for (const n of nodesInFile) {
+    if (!FN_KINDS.has(n.kind)) continue;
+    const end = n.endLine ?? n.startLine;
+    if (n.startLine <= line && end >= line) {
+      if (!best || n.startLine >= best.startLine) best = n; // prefer the tightest (latest-starting) encloser
+    }
+  }
+  return best;
+}
+
+/**
+ * Stream method + function nodes lazily. The synthesizers only scan-and-filter
+ * down to a tiny matched subset, so materializing every function/method (which
+ * is gigabytes on a symbol-dense project) just to iterate it once is what OOM'd
+ * #610. Iterating keeps memory O(1) in the node count.
+ */
+function* methodAndFunctionNodes(queries: QueryBuilder): IterableIterator<Node> {
+  yield* queries.iterateNodesByKind('method');
+  yield* queries.iterateNodesByKind('function');
+}
+
+/** Phase 1: field-backed observer channels (registrar/dispatcher share a store). */
+function fieldChannelEdges(queries: QueryBuilder, ctx: ResolutionContext): Edge[] {
+  const registrars: Array<{ node: Node; field: string }> = [];
+  const dispatchers: Array<{ node: Node; field: string }> = [];
+
+  for (const m of methodAndFunctionNodes(queries)) {
+    const isReg = REGISTRAR_NAME.test(m.name);
+    const isDisp = DISPATCHER_NAME.test(m.name);
+    if (!isReg && !isDisp) continue;
+    const content = ctx.readFile(m.filePath);
+    const src = content && sliceLines(content, m.startLine, m.endLine);
+    if (!src) continue;
+    if (isReg) { const f = registrarField(src); if (f) registrars.push({ node: m, field: f }); }
+    if (isDisp) { const f = dispatcherField(src); if (f) dispatchers.push({ node: m, field: f }); }
+  }
+
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  for (const reg of registrars) {
+    const chDispatchers = dispatchers.filter(
+      (d) => d.node.filePath === reg.node.filePath && d.field === reg.field
+    );
+    if (chDispatchers.length === 0) continue;
+    const argRe = new RegExp(`${reg.node.name}\\s*\\(\\s*(?:this\\.)?(\\w+)`);
+    let added = 0;
+    for (const e of queries.getIncomingEdges(reg.node.id, ['calls'])) {
+      if (added >= MAX_CALLBACKS_PER_CHANNEL) break;
+      if (!e.line) continue;
+      const caller = queries.getNodeById(e.source);
+      if (!caller) continue;
+      const line = ctx.readFile(caller.filePath)?.split('\n')[e.line - 1];
+      const am = line?.match(argRe);
+      if (!am) continue;
+      const fn = ctx.getNodesByName(am[1]!).find((n) => n.kind === 'method' || n.kind === 'function');
+      if (!fn) continue;
+      for (const disp of chDispatchers) {
+        if (disp.node.id === fn.id) continue;
+        const key = `${disp.node.id}>${fn.id}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        edges.push({
+          source: disp.node.id, target: fn.id, kind: 'calls', line: disp.node.startLine,
+          provenance: 'heuristic',
+          metadata: {
+            synthesizedBy: 'callback', via: reg.node.name, field: reg.field,
+            // Where the callback was wired up (`scene.onUpdate(this.triggerRender)`).
+            // This is the #1 thing an agent reads/greps to explain the flow — surface
+            // it so node/trace/context can show it without a callers() + Read round-trip.
+            registeredAt: `${caller.filePath}:${e.line}`,
+          },
+        });
+        added++;
+      }
+    }
+  }
+  return edges;
+}
+
+/**
+ * Closure-collection dispatch: dispatcher iterates a closure-collection property
+ * invoking each element; registrar appends a closure to the same-named property.
+ * Emits dispatcher → registrar so a flow reaches the registration site (where the
+ * appended closure's body — and its callers — live). High-precision: the
+ * dispatcher's element-invoke is the gate (a `.forEach` that does NOT invoke its
+ * element is ignored), so a repo with no closure-collection dispatch yields zero
+ * edges regardless of how many `.append`/`.push` sites it has.
+ *
+ * Pairs globally by field name (cross-file/class is required — see Alamofire's
+ * base-class `Request.didCompleteTask` iterating `validators` appended by the
+ * subclass `DataRequest.validate`), bounded by a fan-out cap so a generic field
+ * name shared across unrelated classes can't fan out into noise.
+ */
+function closureCollectionEdges(queries: QueryBuilder, ctx: ResolutionContext): Edge[] {
+  const dispatchers = new Map<string, Array<{ node: Node; line: number }>>(); // field → dispatcher methods + forEach line
+  const registrars = new Map<string, Array<{ node: Node; line: number }>>();   // field → registrar methods + append line
+
+  const addReg = (field: string | undefined, node: Node, absLine: number) => {
+    if (!field || /^\d+$/.test(field)) return; // `$0.append` mis-captures the `0`; the write-RE owns that field
+    const arr = registrars.get(field) ?? [];
+    if (!arr.some((r) => r.node.id === node.id)) arr.push({ node, line: absLine });
+    registrars.set(field, arr);
+  };
+
+  for (const m of methodAndFunctionNodes(queries)) {
+    const content = ctx.readFile(m.filePath);
+    const src = content && sliceLines(content, m.startLine, m.endLine);
+    if (!src) continue;
+    const hasForEach = src.includes('.forEach');
+    const hasAppend = src.includes('.append(') || src.includes('.add(') || src.includes('.push(') || src.includes('.insert(');
+    if (!hasForEach && !hasAppend) continue;
+    const lineAt = (idx: number) => (m.startLine ?? 1) + src.slice(0, idx).split('\n').length - 1;
+
+    if (hasForEach) {
+      CC_DISPATCH_RE.lastIndex = 0;
+      let d: RegExpExecArray | null;
+      while ((d = CC_DISPATCH_RE.exec(src))) {
+        const arr = dispatchers.get(d[1]!) ?? [];
+        if (!arr.some((n) => n.node.id === m.id)) arr.push({ node: m, line: lineAt(d.index) });
+        dispatchers.set(d[1]!, arr);
+      }
+    }
+    if (hasAppend) {
+      CC_APPEND_WRITE_RE.lastIndex = 0;
+      let w: RegExpExecArray | null;
+      while ((w = CC_APPEND_WRITE_RE.exec(src))) addReg(w[2] || w[1], m, lineAt(w.index)); // nested `$0.streams` else the `.write` receiver
+      CC_APPEND_DIRECT_RE.lastIndex = 0;
+      let a: RegExpExecArray | null;
+      while ((a = CC_APPEND_DIRECT_RE.exec(src))) addReg(a[1], m, lineAt(a.index));
+    }
+  }
+
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  for (const [field, disps] of dispatchers) {
+    const regs = registrars.get(field);
+    if (!regs || regs.length === 0) continue;
+    if (disps.length > CC_FANOUT_CAP || regs.length > CC_FANOUT_CAP) continue; // generic field — can't pair confidently
+    for (const disp of disps) for (const reg of regs) {
+      if (disp.node.id === reg.node.id) continue;
+      const key = `${disp.node.id}>${reg.node.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push({
+        source: disp.node.id, target: reg.node.id, kind: 'calls', line: disp.line,
+        provenance: 'heuristic',
+        metadata: { synthesizedBy: 'closure-collection', field, registeredAt: `${reg.node.filePath}:${reg.line}` },
+      });
+    }
+  }
+  return edges;
+}
+
+/** Phase 2: string-keyed EventEmitter channels (on('e', fn) ↔ emit('e')). */
+function eventEmitterEdges(ctx: ResolutionContext): Edge[] {
+  const emitsByEvent = new Map<string, Set<string>>();          // event → dispatcher node ids
+  const handlersByEvent = new Map<string, Map<string, string>>(); // event → handler id → registration site (file:line)
+
+  for (const file of ctx.getAllFiles()) {
+    const content = ctx.readFile(file);
+    if (!content) continue;
+    const hasEmit = content.includes('.emit(') || content.includes('.fire(') || content.includes('.dispatchEvent(');
+    const hasOn = content.includes('.on(') || content.includes('.once(') || content.includes('.addListener(');
+    if (!hasEmit && !hasOn) continue;
+    const nodesInFile = ctx.getNodesInFile(file);
+    const lineOf = (idx: number) => content.slice(0, idx).split('\n').length;
+
+    if (hasEmit) {
+      EMIT_RE.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = EMIT_RE.exec(content))) {
+        const disp = enclosingFn(nodesInFile, lineOf(m.index));
+        if (!disp) continue;
+        const set = emitsByEvent.get(m[1]!) ?? new Set<string>();
+        set.add(disp.id); emitsByEvent.set(m[1]!, set);
+      }
+    }
+    if (hasOn) {
+      ON_RE.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = ON_RE.exec(content))) {
+        const handlerName = m[2] || m[3];
+        if (!handlerName) continue;
+        const handler = ctx.getNodesByName(handlerName).find((n) => n.kind === 'function' || n.kind === 'method');
+        if (!handler) continue;
+        const map = handlersByEvent.get(m[1]!) ?? new Map<string, string>();
+        map.set(handler.id, `${file}:${lineOf(m.index)}`); handlersByEvent.set(m[1]!, map);
+      }
+    }
+  }
+
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  for (const [event, dispatchers] of emitsByEvent) {
+    const handlers = handlersByEvent.get(event);
+    if (!handlers) continue;
+    // Precision guard: a generic event name with many handlers/dispatchers can't
+    // be matched without receiver-type info (Phase 3) — skip rather than over-link.
+    if (dispatchers.size > EVENT_FANOUT_CAP || handlers.size > EVENT_FANOUT_CAP) continue;
+    for (const d of dispatchers) for (const [h, registeredAt] of handlers) {
+      if (d === h) continue;
+      const key = `${d}>${h}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push({ source: d, target: h, kind: 'calls', provenance: 'heuristic', metadata: { synthesizedBy: 'event-emitter', event, registeredAt } });
+    }
+  }
+  return edges;
+}
+
+/**
+ * Phase 4: React class-component re-render. `this.setState(...)` re-runs the
+ * component's `render()`, but that hop is React-internal — no static edge — so a
+ * flow like "mutation → setState → canvas repaint" dead-ends at setState even
+ * though `render → getRenderableElements → …` is fully call-connected after it.
+ * Bridge it: for each class that has a `render` method, link every sibling method
+ * whose body calls `this.setState(` → `render`. The setState gate keeps this to
+ * React class components (a non-React class with a `render` method won't call
+ * `this.setState`). Over-approximation (all setState methods reach render) is
+ * accepted — it's reachability-correct, like the callback channels.
+ */
+function reactRenderEdges(queries: QueryBuilder, ctx: ResolutionContext): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  for (const cls of queries.getNodesByKind('class')) {
+    const children = queries.getOutgoingEdges(cls.id, ['contains'])
+      .map((e) => queries.getNodeById(e.target))
+      .filter((n): n is Node => !!n && n.kind === 'method');
+    const render = children.find((n) => n.name === 'render');
+    if (!render) continue;
+    let added = 0;
+    for (const m of children) {
+      if (added >= MAX_CALLBACKS_PER_CHANNEL) break;
+      if (m.id === render.id) continue;
+      const content = ctx.readFile(m.filePath);
+      const src = content && sliceLines(content, m.startLine, m.endLine);
+      if (!src || !SETSTATE_RE.test(src)) continue;
+      const key = `${m.id}>${render.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push({
+        source: m.id, target: render.id, kind: 'calls', line: m.startLine,
+        provenance: 'heuristic',
+        metadata: { synthesizedBy: 'react-render', via: 'setState', registeredAt: `${render.filePath}:${render.startLine}` },
+      });
+      added++;
+    }
+  }
+  return edges;
+}
+
+/**
+ * Phase 4b: Flutter setState → build (the Dart analog of react-render). In a
+ * StatefulWidget's State class, `setState(() {…})` re-runs `build(context)`, but
+ * that hop is framework-internal (Flutter calls build), so a flow like
+ * "onPressed → _increment → setState → rebuilt UI" dead-ends at setState. Bridge
+ * it: for each Dart class with a `build` method, link every sibling method whose
+ * body calls `setState(` → `build`. The setState gate + `.dart` file keep this to
+ * Flutter State classes. Over-approximation accepted (reachability-correct).
+ */
+function flutterBuildEdges(queries: QueryBuilder, ctx: ResolutionContext): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  for (const cls of queries.getNodesByKind('class')) {
+    const children = queries.getOutgoingEdges(cls.id, ['contains'])
+      .map((e) => queries.getNodeById(e.target))
+      .filter((n): n is Node => !!n && n.kind === 'method');
+    const build = children.find((n) => n.name === 'build');
+    if (!build || !build.filePath.endsWith('.dart')) continue;
+    let added = 0;
+    for (const m of children) {
+      if (added >= MAX_CALLBACKS_PER_CHANNEL) break;
+      if (m.id === build.id) continue;
+      const content = ctx.readFile(m.filePath);
+      const src = content && sliceLines(content, m.startLine, m.endLine);
+      if (!src || !FLUTTER_SETSTATE_RE.test(src)) continue;
+      const key = `${m.id}>${build.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push({
+        source: m.id, target: build.id, kind: 'calls', line: m.startLine,
+        provenance: 'heuristic',
+        metadata: { synthesizedBy: 'flutter-build', via: 'setState', registeredAt: `${build.filePath}:${build.startLine}` },
+      });
+      added++;
+    }
+  }
+  return edges;
+}
+
+/**
+ * Phase 4c: C++ virtual override. A call through a base/interface pointer
+ * (`db->Get(...)`, `iter->Next()`) dispatches at runtime to a subclass override,
+ * but that hop is a vtable indirection — no static call edge — so a flow stops at
+ * the abstract base method. Bridge it like react-render: for each C++ class that
+ * `extends` a base, link each base method → the subclass method of the same name
+ * (the override), so trace/callees from the interface method reach the
+ * implementation(s). Over-approximation accepted (reachability-correct); capped
+ * per class and gated to C++ to avoid touching other languages' dispatch.
+ */
+function cppOverrideEdges(queries: QueryBuilder): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  const methodsOf = (classId: string): Node[] =>
+    queries
+      .getOutgoingEdges(classId, ['contains'])
+      .map((e) => queries.getNodeById(e.target))
+      .filter((n): n is Node => !!n && n.kind === 'method');
+  for (const cls of queries.getNodesByKind('class')) {
+    const subMethods = methodsOf(cls.id).filter((n) => n.language === 'cpp');
+    if (subMethods.length === 0) continue;
+    for (const ext of queries.getOutgoingEdges(cls.id, ['extends'])) {
+      const base = queries.getNodeById(ext.target);
+      if (!base || base.language !== 'cpp' || base.id === cls.id) continue;
+      const baseMethods = new Map(methodsOf(base.id).map((m) => [m.name, m]));
+      let added = 0;
+      for (const m of subMethods) {
+        if (added >= MAX_CALLBACKS_PER_CHANNEL) break;
+        const bm = baseMethods.get(m.name);
+        if (!bm || bm.id === m.id) continue;
+        const key = `${bm.id}>${m.id}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        edges.push({
+          source: bm.id,
+          target: m.id,
+          kind: 'calls',
+          line: bm.startLine,
+          provenance: 'heuristic',
+          metadata: { synthesizedBy: 'cpp-override', via: m.name, registeredAt: `${m.filePath}:${m.startLine}` },
+        });
+        added++;
+      }
+    }
+  }
+  return edges;
+}
+
+/**
+ * Phase 5.5: interface / abstract dispatch (Java, Kotlin). A call through an
+ * injected interface (`@Autowired FooService svc; svc.list()`) or an abstract
+ * base dispatches at runtime to the implementing class's override — a vtable
+ * indirection with no static call edge — so a request→service flow stops at the
+ * interface method. Bridge it like cpp-override: for each class that
+ * `implements` an interface (or `extends` an abstract base), link each
+ * base/interface method → the class's same-name method (the override) so
+ * trace/callees reach the implementation. Over-approximation accepted
+ * (reachability-correct); capped per class, gated to JVM languages.
+ */
+// Languages whose static `implements`/`extends` edges should bridge an
+// interface (or abstract base) method to the matching concrete-class method.
+// The set is "languages with explicit nominal subtyping and a single class
+// kind that holds methods" — i.e. the shape this loop expects. Swift and
+// Scala fit shape-wise (Swift `protocol`/`class`, Scala `trait`/`class`)
+// and are added below; their concrete-side nodes can be a `struct` (Swift)
+// or an `object` (Scala) so the loop also iterates those kinds.
+const IFACE_OVERRIDE_LANGS = new Set([
+  'java', 'kotlin', 'csharp', 'typescript', 'javascript', 'swift', 'scala', 'go', 'rust',
+]);
+/**
+ * Go implicit interface satisfaction (#584). Go has no `implements` keyword — a
+ * struct satisfies an interface structurally when its method set covers the
+ * interface's. Synthesize the missing `implements` edge (struct → interface) by
+ * matching method-NAME sets, so impl-navigation works and the interface-dispatch
+ * bridge ({@link interfaceOverrideEdges}, now 'go'-enabled) can link an interface
+ * method call to the concrete overrides.
+ *
+ * Name-only matching (signatures ignored) — over-approximation accepted, in line
+ * with the other dispatch synthesizers; capped per interface. Empty interfaces
+ * (`any`) are skipped so they don't match every struct.
+ */
+function goImplementsEdges(queries: QueryBuilder): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+
+  const methodNameSet = (id: string): Set<string> =>
+    new Set(
+      queries
+        .getOutgoingEdges(id, ['contains'])
+        .map((e) => queries.getNodeById(e.target))
+        .filter((n): n is Node => !!n && n.kind === 'method')
+        .map((n) => n.name),
+    );
+
+  const goStructs = queries.getNodesByKind('struct').filter((s) => s.language === 'go');
+  const structMethods = new Map<string, Set<string>>();
+  for (const s of goStructs) structMethods.set(s.id, methodNameSet(s.id));
+
+  for (const iface of queries.getNodesByKind('interface')) {
+    if (iface.language !== 'go') continue;
+    const want = methodNameSet(iface.id);
+    if (want.size === 0) continue; // empty interface (`any`) — would match everything
+    let added = 0;
+    for (const s of goStructs) {
+      if (added >= MAX_CALLBACKS_PER_CHANNEL) break;
+      const have = structMethods.get(s.id);
+      if (!have || have.size < want.size) continue;
+      let all = true;
+      for (const m of want) {
+        if (!have.has(m)) { all = false; break; }
+      }
+      if (!all) continue;
+      const key = `${s.id}>${iface.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push({
+        source: s.id,
+        target: iface.id,
+        kind: 'implements',
+        line: s.startLine,
+        provenance: 'heuristic',
+        metadata: { synthesizedBy: 'go-implements', via: iface.name, registeredAt: `${s.filePath}:${s.startLine}` },
+      });
+      added++;
+    }
+  }
+  return edges;
+}
+
+/**
+ * Cross-file Go method → receiver-type `contains` edges. In Go a type's methods
+ * are commonly declared in a different file from the `type` declaration itself
+ * (`type User struct{…}` in `user.go`, `func (u *User) Save()` in
+ * `user_store.go`). Extraction attaches the struct→method `contains` edge only
+ * when the receiver type is in the SAME file — the owner lookup in
+ * `tree-sitter.ts` is scoped to the file being parsed — so a cross-file method
+ * is left orphaned from its type (it's still `contains`ed by its file, just not
+ * its struct). That breaks `codegraph_node` member outlines, any
+ * callers/callees/impact traversal that goes through the type's `contains`
+ * edges, and the {@link goImplementsEdges} method-set computation (which derives
+ * a struct's method set from those same edges, so it under-counts interfaces a
+ * cross-file struct satisfies).
+ *
+ * Go guarantees a method's receiver type is declared in the SAME PACKAGE as the
+ * method, and a Go package is a single directory — so this is a deterministic
+ * structural link, not a heuristic: find the same-named type in the method's own
+ * directory and add the missing `contains` edge (no `provenance: 'heuristic'`,
+ * matching the same-file edges extraction already emits). Skips methods that
+ * already have a type parent (the same-file case). (#583, cross-file half)
+ */
+function goCrossFileMethodContainsEdges(queries: QueryBuilder): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  const TYPE_KINDS = new Set<NodeKind>(['struct', 'class', 'interface', 'enum', 'type_alias']);
+  const dirOf = (p: string): string => {
+    const i = p.replace(/\\/g, '/').lastIndexOf('/');
+    return i >= 0 ? p.slice(0, i) : '';
+  };
+
+  for (const method of queries.getNodesByKind('method')) {
+    if (method.language !== 'go') continue;
+    // The receiver type is encoded in the method's qualifiedName as `Recv::name`
+    // (extraction sets `${receiverType}::${name}` for receiver methods).
+    const qn = method.qualifiedName;
+    if (!qn) continue;
+    const sep = qn.lastIndexOf('::');
+    if (sep <= 0) continue;
+    const receiver = qn.slice(0, sep);
+    if (!receiver) continue;
+
+    // Already attached to its type (same-file case handled at extraction)?
+    const hasTypeParent = queries
+      .getIncomingEdges(method.id, ['contains'])
+      .some((e) => {
+        const src = queries.getNodeById(e.source);
+        return src != null && TYPE_KINDS.has(src.kind);
+      });
+    if (hasTypeParent) continue;
+
+    // Find the receiver type in the SAME directory (= same Go package). Go forbids
+    // duplicate type names within a package, so a same-name same-dir match is
+    // unambiguous; scoping to the directory avoids linking to a same-named type
+    // in another package.
+    const dir = dirOf(method.filePath);
+    const owner = queries
+      .getNodesByName(receiver)
+      .find((n) => n.language === 'go' && TYPE_KINDS.has(n.kind) && dirOf(n.filePath) === dir);
+    if (!owner) continue;
+
+    const key = `${owner.id}>${method.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    edges.push({ source: owner.id, target: method.id, kind: 'contains', line: method.startLine });
+  }
+  return edges;
+}
+
+/**
+ * Kotlin Multiplatform `expect`/`actual` linking. A `common` source set declares
+ * `expect fun foo()` / `expect class Bar`; each platform source set (jvm, native,
+ * js, …) provides an `actual` implementation with the IDENTICAL fully-qualified
+ * name in a different file. Callers in common code resolve to the `expect`
+ * declaration, so every `actual` impl ends up with zero dependents — invisible to
+ * impact/affected even though editing it can break every caller of the API.
+ *
+ * Synthesize a `calls` edge from the common declaration to each platform `actual`
+ * (mirroring the interface-impl bridge: abstract → concrete), so editing a
+ * platform impl surfaces the common `expect` and its callers, and the impl file
+ * participates in the graph.
+ *
+ * `expect`/`actual` are captured onto the node's `decorators` list at extraction
+ * (kotlin.ts `extractModifiers`). Members of an `expect class` are NOT themselves
+ * keyword-marked, so the declaration side is matched as the same-FQN, same-kind
+ * node that is NOT marked `actual`. Requiring an `actual`-marked counterpart also
+ * gates out plain cross-file overloads (neither side is marked).
+ */
+// Kinds that an `expect`/`actual` pair may legitimately straddle. `expect class`
+// is routinely fulfilled by an `actual typealias` (e.g. `actual typealias
+// CancellationException = …`, `actual typealias SchedulerTask = Task`), so a
+// strict kind match would miss those one-line alias files. Same-FQN + the
+// `actual` marker already gates out unrelated symbols, so widening to the
+// type-like kinds is safe.
+const KMP_TYPE_KINDS = new Set(['class', 'interface', 'struct', 'enum', 'type_alias']);
+function kmpKindsCompatible(a: string, b: string): boolean {
+  return a === b || (KMP_TYPE_KINDS.has(a) && KMP_TYPE_KINDS.has(b));
+}
+
+function kotlinExpectActualEdges(queries: QueryBuilder): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  const actuals = queries
+    .getAllNodes()
+    .filter((n) => n.language === 'kotlin' && !!n.decorators?.includes('actual'));
+  for (const act of actuals) {
+    let added = 0;
+    for (const cand of queries.getNodesByQualifiedNameExact(act.qualifiedName)) {
+      if (added >= MAX_CALLBACKS_PER_CHANNEL) break;
+      // The declaration side: same FQN + compatible kind, a different file, NOT
+      // itself an `actual` (that would be a sibling platform impl, not the decl).
+      if (cand.language !== 'kotlin' || cand.id === act.id) continue;
+      if (!kmpKindsCompatible(cand.kind, act.kind) || cand.filePath === act.filePath) continue;
+      if (cand.decorators?.includes('actual')) continue;
+      const key = `${cand.id}>${act.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push({
+        source: cand.id,
+        target: act.id,
+        kind: 'calls',
+        line: cand.startLine,
+        provenance: 'heuristic',
+        metadata: {
+          synthesizedBy: 'kotlin-expect-actual',
+          via: act.name,
+          registeredAt: `${act.filePath}:${act.startLine}`,
+        },
+      });
+      added++;
+    }
+  }
+  return edges;
+}
+
+function interfaceOverrideEdges(queries: QueryBuilder): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  const methodsOf = (classId: string): Node[] =>
+    queries
+      .getOutgoingEdges(classId, ['contains'])
+      .map((e) => queries.getNodeById(e.target))
+      .filter((n): n is Node => !!n && n.kind === 'method');
+  // Concrete-side kinds vary by language: `class` covers Java / Kotlin /
+  // C# / TS / Swift-classes / Scala-classes; `struct` covers Swift value
+  // types that conform to protocols. Iterate both.
+  const concreteKinds = ['class', 'struct'] as const;
+  for (const kind of concreteKinds) {
+  for (const cls of queries.getNodesByKind(kind)) {
+    const implMethods = methodsOf(cls.id).filter((n) => IFACE_OVERRIDE_LANGS.has(n.language));
+    if (implMethods.length === 0) continue;
+    for (const sup of queries.getOutgoingEdges(cls.id, ['implements', 'extends'])) {
+      const base = queries.getNodeById(sup.target);
+      if (!base || !IFACE_OVERRIDE_LANGS.has(base.language) || base.id === cls.id) continue;
+      // Group impl methods by name to handle OVERLOADS: an interface `list()` and
+      // `list(params)` are distinct nodes and a call may resolve to either, so
+      // link every base overload → every same-name impl overload (keying by name
+      // alone would drop all but one and miss the resolved overload).
+      const implByName = new Map<string, Node[]>();
+      for (const m of implMethods) {
+        const arr = implByName.get(m.name);
+        if (arr) arr.push(m); else implByName.set(m.name, [m]);
+      }
+      let added = 0;
+      for (const bm of methodsOf(base.id)) {
+        if (added >= MAX_CALLBACKS_PER_CHANNEL) break;
+        for (const m of implByName.get(bm.name) ?? []) {
+          if (added >= MAX_CALLBACKS_PER_CHANNEL) break;
+          if (bm.id === m.id) continue;
+          const key = `${bm.id}>${m.id}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          edges.push({
+            source: bm.id,
+            target: m.id,
+            kind: 'calls',
+            line: bm.startLine,
+            provenance: 'heuristic',
+            metadata: { synthesizedBy: 'interface-impl', via: m.name, registeredAt: `${m.filePath}:${m.startLine}` },
+          });
+          added++;
+        }
+      }
+    }
+  }
+  }
+  return edges;
+}
+
+/**
+ * Go gRPC stub → impl bridge. The protoc-gen-go-grpc codegen emits an
+ * `UnimplementedXxxServer` struct in `*_grpc.pb.go` carrying one method
+ * per service RPC; the real handler is a hand-written struct in another
+ * file (`x/bank/keeper/msg_server.go::msgServer.Send` in cosmos-sdk).
+ * Go's structural typing means no `implements` edge exists for our
+ * resolver to follow, so `trace("Send","SendCoins")` lands on the
+ * empty stub and reports "no path" (validated empirically — the cosmos
+ * Q1 r1 trace failure that drove this work).
+ *
+ * Bridge: for each `UnimplementedXxxServer` whose RPC-method names are
+ * a SUBSET of some other Go struct's method names, emit `calls` edges
+ * `stub.method → impl.method` (paired by name). Excludes the gRPC
+ * internal markers `mustEmbedUnimplementedXxxServer` and
+ * `testEmbeddedByValue`, and skips candidate impls that themselves
+ * live in a generated file (their `xxxClient` / sibling stubs would
+ * otherwise look like impls).
+ *
+ * Multiple candidates is allowed and capped at MAX_CALLBACKS_PER_CHANNEL —
+ * a service often has both a production impl and one or more test
+ * mocks; linking to all preserves trace utility without false-favoring.
+ *
+ * Provenance: `heuristic`, `synthesizedBy: 'go-grpc-stub-impl'`. The
+ * stub's source line is the wiring site shown in the trace trail.
+ */
+function goGrpcStubImplEdges(queries: QueryBuilder): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+
+  const STUB_RE = /^Unimplemented.*Server$/;
+  // gRPC internal-helper methods that appear on every Unimplemented*Server;
+  // not part of the service contract, so exclude when computing the RPC-method
+  // signature used to match impls.
+  const isInternalMarker = (n: string) => n.startsWith('mustEmbed') || n === 'testEmbeddedByValue';
+
+  // Methods directly contained by each Go struct, name-only. Built once.
+  const methodNamesByStruct = new Map<string, Set<string>>();
+  const methodNodesByStruct = new Map<string, Node[]>();
+  const goStructs: Node[] = [];
+  for (const s of queries.getNodesByKind('struct')) {
+    if (s.language !== 'go') continue;
+    goStructs.push(s);
+    const ms = queries
+      .getOutgoingEdges(s.id, ['contains'])
+      .map((e) => queries.getNodeById(e.target))
+      .filter((n): n is Node => !!n && n.kind === 'method');
+    methodNodesByStruct.set(s.id, ms);
+    methodNamesByStruct.set(s.id, new Set(ms.map((m) => m.name)));
+  }
+
+  for (const stub of goStructs) {
+    if (!STUB_RE.test(stub.name)) continue;
+    // The stub MUST live in a generated file — that's what tells us this is
+    // a protoc-emitted scaffold rather than someone naming a struct
+    // `UnimplementedXxxServer` by hand. Without this gate we'd also bridge
+    // such hand-written structs and create misleading edges.
+    if (!isGeneratedFile(stub.filePath)) continue;
+
+    const stubMethods = (methodNodesByStruct.get(stub.id) ?? []).filter(
+      (m) => !isInternalMarker(m.name),
+    );
+    if (stubMethods.length === 0) continue;
+    const stubMethodNames = stubMethods.map((m) => m.name);
+
+    for (const cand of goStructs) {
+      if (cand.id === stub.id) continue;
+      // Skip generated-file candidates — they're siblings (msgClient,
+      // UnsafeMsgServer, …) whose method sets coincidentally match.
+      if (isGeneratedFile(cand.filePath)) continue;
+
+      const candNames = methodNamesByStruct.get(cand.id);
+      if (!candNames) continue;
+      // Subset: every RPC method must exist on the candidate by name.
+      // Signature-level match would tighten this further, but name-match
+      // alone already gives one-to-one pairing in real codebases because
+      // gRPC method-name sets are highly distinctive (Send + MultiSend +
+      // UpdateParams + SetSendEnabled is unique to bank's MsgServer).
+      if (!stubMethodNames.every((n) => candNames.has(n))) continue;
+
+      const candMethods = methodNodesByStruct.get(cand.id) ?? [];
+      let added = 0;
+      for (const sm of stubMethods) {
+        if (added >= MAX_CALLBACKS_PER_CHANNEL) break;
+        for (const cm of candMethods) {
+          if (added >= MAX_CALLBACKS_PER_CHANNEL) break;
+          if (cm.name !== sm.name) continue;
+          const key = `${sm.id}>${cm.id}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          edges.push({
+            source: sm.id,
+            target: cm.id,
+            kind: 'calls',
+            line: sm.startLine,
+            provenance: 'heuristic',
+            metadata: {
+              synthesizedBy: 'go-grpc-stub-impl',
+              via: cm.name,
+              registeredAt: `${cm.filePath}:${cm.startLine}`,
+            },
+          });
+          added++;
+        }
+      }
+    }
+  }
+  return edges;
+}
+
+/**
+ * Phase 5: React JSX child rendering. A component that returns `<Child .../>`
+ * mounts Child — React calls it — but JSX instantiation isn't a static call edge,
+ * so a render tree (App.render → StaticCanvas → renderStaticScene) breaks at the
+ * JSX hop. Link parent → each capitalized JSX child it renders. File-oriented
+ * (read each JSX file once). Precision gate: the child name must resolve to a
+ * component/function/class node — TS generics like `Array<Foo>` resolve to a type
+ * (or nothing) and are dropped.
+ */
+function reactJsxChildEdges(ctx: ResolutionContext): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  const PARENT_KINDS = new Set(['method', 'function', 'component']);
+  for (const file of ctx.getAllFiles()) {
+    const content = ctx.readFile(file);
+    if (!content || (!content.includes('</') && !content.includes('/>'))) continue; // JSX-file gate
+    const parents = ctx.getNodesInFile(file).filter((n) => PARENT_KINDS.has(n.kind));
+    for (const parent of parents) {
+      const src = sliceLines(content, parent.startLine, parent.endLine);
+      if (!src || (!src.includes('</') && !src.includes('/>'))) continue;
+      const names = new Set<string>();
+      JSX_TAG_RE.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = JSX_TAG_RE.exec(src))) names.add(m[1]!);
+      let added = 0;
+      for (const name of names) {
+        if (added >= MAX_JSX_CHILDREN) break;
+        const child = ctx.getNodesByName(name).find(
+          (n) => n.kind === 'component' || n.kind === 'function' || n.kind === 'class'
+        );
+        if (!child || child.id === parent.id) continue;
+        const key = `${parent.id}>${child.id}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        edges.push({
+          source: parent.id, target: child.id, kind: 'calls', line: parent.startLine,
+          provenance: 'heuristic',
+          metadata: { synthesizedBy: 'jsx-render', via: name },
+        });
+        added++;
+      }
+    }
+  }
+  return edges;
+}
+
+/**
+ * Phase 6: Vue SFC templates. The `.vue` extractor only parses `<script>`, so
+ * template usage is invisible — child components and event handlers used ONLY in
+ * the template have no edge to them. PascalCase children (`<VPNav/>`) are already
+ * caught by reactJsxChildEdges (which scans the SFC component node), so this adds
+ * the two Vue-specific shapes:
+ *   - kebab-case children: `<el-button>` → `ElButton` component (renders).
+ *   - event bindings: `@click="onClick"` / `v-on:submit="save"` → handler method.
+ * Scoped to the `<template>` block of `.vue` files; resolution gate (kebab→
+ * component, handler→function/method) keeps precision; inline arrows / `$emit`
+ * skipped.
+ */
+function vueTemplateEdges(ctx: ResolutionContext): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  const COMPONENT_KINDS = new Set(['component', 'function', 'class']);
+  const HANDLER_KINDS = new Set(['method', 'function']);
+  // A composable's returned member may be a fn (`function close(){}`) or an
+  // arrow assigned to a const (`const close = () => {}`).
+  const RETURN_KINDS = new Set(['method', 'function', 'variable', 'constant']);
+  // Nuxt auto-imports nested components by a DIRECTORY-PREFIXED name —
+  // `components/media/Card.vue` is used as `<MediaCard/>`, not `<Card/>` — but
+  // the component node is named by basename (`Card`), so a direct tag match
+  // misses it (flat components match by basename and don't need this). Map each
+  // nested component's Nuxt name → node so those template usages resolve.
+  const nuxtComponents = new Map<string, Node>();
+  for (const c of ctx.getNodesByKind('component')) {
+    const nn = nuxtComponentName(c.filePath);
+    if (nn && !nuxtComponents.has(nn)) nuxtComponents.set(nn, c);
+  }
+  for (const file of ctx.getAllFiles()) {
+    if (!file.endsWith('.vue')) continue;
+    const content = ctx.readFile(file);
+    const tpl = content && content.match(/<template[^>]*>([\s\S]*)<\/template>/i)?.[1];
+    if (!tpl) continue;
+    const comp = ctx.getNodesInFile(file).find((n) => n.kind === 'component');
+    if (!comp) continue;
+
+    // Composable-destructure map: alias → { composable, key }. Lets us resolve a
+    // template handler that isn't a local function but a destructured composable
+    // return (`@click="closeSidebar"` ← `const { close: closeSidebar } = useSidebarControl()`).
+    const script = content.match(/<script[^>]*>([\s\S]*?)<\/script>/i)?.[1] ?? '';
+    const destructured = new Map<string, { composable: string; key: string }>();
+    VUE_DESTRUCTURE_RE.lastIndex = 0;
+    let dm: RegExpExecArray | null;
+    while ((dm = VUE_DESTRUCTURE_RE.exec(script))) {
+      if (!/^use[A-Z]/.test(dm[2]!)) continue; // composables / hooks only
+      for (const part of dm[1]!.split(',')) {
+        const pm = part.trim().match(/^(\w+)\s*(?::\s*(\w+))?$/); // key | key: alias
+        if (pm) destructured.set(pm[2] || pm[1]!, { composable: dm[2]!, key: pm[1]! });
+      }
+    }
+
+    let added = 0;
+    const addEdge = (target: Node | undefined, meta: Record<string, unknown>) => {
+      if (added >= MAX_JSX_CHILDREN || !target || target.id === comp.id) return;
+      const k = `${comp.id}>${target.id}>${meta.synthesizedBy}`;
+      if (seen.has(k)) return;
+      seen.add(k);
+      edges.push({ source: comp.id, target: target.id, kind: 'calls', line: comp.startLine, provenance: 'heuristic', metadata: meta });
+      added++;
+    };
+    // Prefer a target in THIS SFC (handlers live in the same file's script) —
+    // avoids cross-file mis-match when a name repeats across a monorepo.
+    const resolve = (name: string, kinds: Set<string>): Node | undefined => {
+      const matches = ctx.getNodesByName(name).filter((n) => kinds.has(n.kind));
+      return matches.find((n) => n.filePath === file) ?? matches[0];
+    };
+
+    let m: RegExpExecArray | null;
+    VUE_KEBAB_RE.lastIndex = 0;
+    while ((m = VUE_KEBAB_RE.exec(tpl))) {
+      const tag = kebabToPascal(m[1]!);
+      addEdge(resolve(tag, COMPONENT_KINDS) ?? nuxtComponents.get(tag), { synthesizedBy: 'jsx-render', via: m[1] });
+    }
+    // PascalCase component tags. Try a direct name match first (flat components
+    // and explicit registrations), then the Nuxt dir-prefixed auto-import name
+    // (`<MediaCard>` → components/media/Card.vue). Built-ins match neither → no edge.
+    VUE_PASCAL_RE.lastIndex = 0;
+    while ((m = VUE_PASCAL_RE.exec(tpl))) {
+      const tag = m[1]!;
+      addEdge(resolve(tag, COMPONENT_KINDS) ?? nuxtComponents.get(tag), { synthesizedBy: 'jsx-render', via: tag });
+    }
+    VUE_HANDLER_RE.lastIndex = 0;
+    while ((m = VUE_HANDLER_RE.exec(tpl))) {
+      const event = m[1]!;
+      const expr = m[2]!.trim();
+      if (expr.includes('=>') || expr.startsWith('$')) continue; // inline arrow / $emit
+      const name = expr.match(/^([A-Za-z_]\w*)/)?.[1];
+      if (!name) continue;
+      const direct = resolve(name, HANDLER_KINDS);
+      if (direct) { addEdge(direct, { synthesizedBy: 'vue-handler', event }); continue; }
+      // Composable-destructure handler → resolve to the composable's returned fn.
+      const d = destructured.get(name);
+      if (!d) continue;
+      const composable = resolve(d.composable, HANDLER_KINDS);
+      // Resolve to the SPECIFIC returned member (e.g. `close`) defined in the
+      // composable's file. No fallback to the composable itself — the component
+      // already has a static `useX()` call edge, so that would just be redundant
+      // and less precise.
+      const keyFn = composable
+        ? ctx.getNodesByName(d.key).find((n) => RETURN_KINDS.has(n.kind) && n.filePath === composable.filePath)
+        : undefined;
+      if (keyFn) addEdge(keyFn, { synthesizedBy: 'vue-handler', event, via: d.composable });
+    }
+  }
+  return edges;
+}
+
+/**
+ * React Native cross-language event channel (Phase 3 of the mixed-iOS/RN
+ * bridging effort). Same shape as `eventEmitterEdges` but cross-language:
+ *
+ *   Native (ObjC, on RCTEventEmitter subclass):
+ *     [self sendEventWithName:@"locationUpdate" body:@{...}];
+ *
+ *   Native (Java/Kotlin, via the JS module dispatcher):
+ *     emitter.emit("locationUpdate", body);
+ *     reactContext.getJSModule(RCTDeviceEventEmitter.class).emit("locationUpdate", body);
+ *
+ *   JS (subscriber):
+ *     new NativeEventEmitter(NativeModules.Geo).addListener("locationUpdate", handler);
+ *     DeviceEventEmitter.addListener("locationUpdate", handler);
+ *
+ * Synthesize: native dispatch site → JS handler, keyed by the literal
+ * event name. Only matches NAMED handlers (the existing `ON_RE` named-
+ * capture form). Inline arrow handlers like `addListener('x', d => …)`
+ * aren't named at extraction time and would need link-through-body
+ * support; matches the deliberate scope of the in-language synthesizer.
+ *
+ * Provenance `'heuristic'`, synthesizedBy `'rn-event-channel'`.
+ */
+// ObjC's `[self sendEventWithName:@"X" body:...]` shape (bracket syntax,
+// `@` string literals).
+const RN_OBJC_SEND_RE = /\bsendEventWithName\s*:\s*@"([^"]+)"/g;
+// Swift's `sendEvent(withName: "X", body: ...)` shape — same RCTEventEmitter
+// method, different call syntax. Both Objective-C and Swift subclass
+// RCTEventEmitter so this catches the Swift-side equivalent emission sites
+// (e.g. RNFusedLocation.swift's `sendEvent(withName: "geolocationDidChange",
+// body: locationData)`).
+const RN_SWIFT_SEND_RE = /\bsendEvent\s*\(\s*withName\s*:\s*"([^"]+)"/g;
+// JVM-side emitter calls: `emitter.emit("X", body)`. Matches both Java
+// and Kotlin syntax because the call form is identical. Restricted to
+// JVM source files in the consumer so we don't re-process JS emits
+// (which `eventEmitterEdges` already handles).
+const RN_JVM_EMIT_RE = /\.emit\s*\(\s*"([^"]+)"\s*,/g;
+// Custom `sendEvent(reactContext, "X", body)` wrapper — extremely common
+// (react-native-device-info and many libs wrap `DeviceEventManagerModule…emit`
+// behind a helper whose `.emit(eventName, …)` uses a VARIABLE, so RN_JVM_EMIT_RE
+// misses it; the literal lives in the wrapper CALL instead). Captures the first
+// string literal inside a `sendEvent(...)` call. `[^;{}]*?` keeps it on one
+// statement and stops at a block boundary, so the wrapper DEFINITION (whose `(`
+// is followed by `… ) {`) never matches. Multi-line tolerant. (java/kotlin/swift)
+const RN_NATIVE_SENDEVENT_RE = /\bsendEvent\s*\([^;{}]*?"([^"]+)"/g;
+
+function rnEventEdges(ctx: ResolutionContext): Edge[] {
+  // Native dispatchers (source = the native method whose body sends the
+  // event) and JS handlers (target = the function/method registered as
+  // the listener) keyed by event name.
+  const nativeDispatchersByEvent = new Map<string, Set<string>>();
+  const jsHandlersByEvent = new Map<string, Map<string, string>>();
+
+  for (const file of ctx.getAllFiles()) {
+    const content = ctx.readFile(file);
+    if (!content) continue;
+
+    const nodesInFile = ctx.getNodesInFile(file);
+    const lineOf = (idx: number) => content.slice(0, idx).split('\n').length;
+    const addDispatcher = (event: string, line: number) => {
+      const disp = enclosingFn(nodesInFile, line);
+      if (!disp) return;
+      const set = nativeDispatchersByEvent.get(event) ?? new Set<string>();
+      set.add(disp.id);
+      nativeDispatchersByEvent.set(event, set);
+    };
+
+    // ObjC side: `sendEventWithName:@"X"` only fires inside `.m`/`.mm`
+    // files (RCTEventEmitter subclasses).
+    if (file.endsWith('.m') || file.endsWith('.mm')) {
+      RN_OBJC_SEND_RE.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = RN_OBJC_SEND_RE.exec(content))) {
+        if (m[1]) addDispatcher(m[1], lineOf(m.index));
+      }
+    }
+
+    // Swift side: same RCTEventEmitter method, parens/named-args syntax.
+    if (file.endsWith('.swift')) {
+      RN_SWIFT_SEND_RE.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = RN_SWIFT_SEND_RE.exec(content))) {
+        if (m[1]) addDispatcher(m[1], lineOf(m.index));
+      }
+      RN_NATIVE_SENDEVENT_RE.lastIndex = 0;
+      while ((m = RN_NATIVE_SENDEVENT_RE.exec(content))) {
+        if (m[1]) addDispatcher(m[1], lineOf(m.index));
+      }
+    }
+
+    // JVM side: `.emit("X", …)` in Java/Kotlin, plus the common
+    // `sendEvent(ctx, "X", body)` wrapper. (We pattern-match anywhere in the
+    // file; the JS in-language path uses a separate emitter object pattern and
+    // is already handled by eventEmitterEdges.)
+    if (file.endsWith('.java') || file.endsWith('.kt')) {
+      let m: RegExpExecArray | null;
+      RN_JVM_EMIT_RE.lastIndex = 0;
+      while ((m = RN_JVM_EMIT_RE.exec(content))) {
+        if (m[1]) addDispatcher(m[1], lineOf(m.index));
+      }
+      RN_NATIVE_SENDEVENT_RE.lastIndex = 0;
+      while ((m = RN_NATIVE_SENDEVENT_RE.exec(content))) {
+        if (m[1]) addDispatcher(m[1], lineOf(m.index));
+      }
+    }
+
+    // JS subscribers (.addListener("X", handler)). Restrict to JS-family
+    // files so a native file's `addListener:` (the ObjC method) doesn't
+    // get mistaken for a JS subscription — they're entirely different
+    // things despite sharing a name.
+    if (
+      file.endsWith('.js') ||
+      file.endsWith('.jsx') ||
+      file.endsWith('.ts') ||
+      file.endsWith('.tsx') ||
+      file.endsWith('.mjs') ||
+      file.endsWith('.cjs')
+    ) {
+      // Match BOTH the named-handler form (`.addListener('x', fn)`) and
+      // an unnamed-handler form (`.addListener('x', listener)` where
+      // `listener` is a parameter — common in RN wrapper APIs like
+      // RNFirebase's `messaging().onMessageReceived(listener)`). For the
+      // unnamed case we attribute the subscription to the ENCLOSING JS
+      // function (the abstraction layer), giving a reachability-correct
+      // hop even when the actual user-side handler lives one call up.
+      const ADDLISTENER_ANY = /\.(?:on|once|addListener)\(\s*['"]([^'"]+)['"]\s*,\s*([A-Za-z_][\w.]*)/g;
+      ADDLISTENER_ANY.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      while ((m = ADDLISTENER_ANY.exec(content))) {
+        const event = m[1];
+        const arg = m[2];
+        if (!event || !arg) continue;
+        const bareName = arg.includes('.') ? arg.slice(arg.lastIndexOf('.') + 1) : arg;
+        // Try a named-symbol match first (matches the in-language semantic).
+        const namedHandler = ctx
+          .getNodesByName(bareName)
+          .find((n) => n.kind === 'function' || n.kind === 'method');
+        let targetId: string | null = namedHandler?.id ?? null;
+        if (!targetId) {
+          // Fall back to the enclosing function — the subscribe-wrapper
+          // pattern means the event fires THROUGH this function on its
+          // way to user code. Reachability-correct attribution.
+          const enclosing = enclosingFn(nodesInFile, lineOf(m.index));
+          targetId = enclosing?.id ?? null;
+        }
+        if (!targetId) {
+          // Broader fallback for JS object-literal API shape
+          // (`const Foo = { watchX(...) { … addListener(...) … } }`):
+          // method shorthand inside an object literal isn't extracted
+          // as a method node, so enclosingFn returns null. Attribute to
+          // the smallest enclosing `constant` / `variable` node — that's
+          // the API surface a downstream caller would `import` and
+          // invoke. Reachability-correct.
+          const line = lineOf(m.index);
+          let smallest: typeof nodesInFile[number] | null = null;
+          for (const n of nodesInFile) {
+            if (n.kind !== 'constant' && n.kind !== 'variable') continue;
+            const end = n.endLine ?? n.startLine;
+            if (n.startLine <= line && end >= line) {
+              if (!smallest || n.startLine >= smallest.startLine) smallest = n;
+            }
+          }
+          targetId = smallest?.id ?? null;
+        }
+        if (!targetId) continue;
+        const map = jsHandlersByEvent.get(event) ?? new Map<string, string>();
+        map.set(targetId, `${file}:${lineOf(m.index)}`);
+        jsHandlersByEvent.set(event, map);
+      }
+    }
+  }
+
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  for (const [event, dispatchers] of nativeDispatchersByEvent) {
+    const handlers = jsHandlersByEvent.get(event);
+    if (!handlers) continue;
+    // Same fan-out guard as the in-language channel: generic event names
+    // (e.g. 'change', 'error', 'data') with many handlers/dispatchers
+    // can't be matched precisely without receiver-type info.
+    if (dispatchers.size > EVENT_FANOUT_CAP || handlers.size > EVENT_FANOUT_CAP) continue;
+    for (const d of dispatchers) {
+      for (const [h, registeredAt] of handlers) {
+        if (d === h) continue;
+        const key = `${d}>${h}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        edges.push({
+          source: d,
+          target: h,
+          kind: 'calls',
+          provenance: 'heuristic',
+          metadata: { synthesizedBy: 'rn-event-channel', event, registeredAt },
+        });
+      }
+    }
+  }
+  return edges;
+}
+
+/**
+ * Phase 6 — React Native Fabric/Codegen view component bridge.
+ *
+ * The Fabric framework extractor (`frameworks/fabric.ts`) emits
+ * `component` nodes named after the JS-visible component (e.g.
+ * `RNSScreenStack`) from each `codegenNativeComponent<Props>('Name')`
+ * spec declaration. The native implementation lives in an ObjC++/.mm or
+ * Kotlin/Java class whose name follows one of RN's conventions:
+ *
+ *   - Exact: `RNSScreenStack`
+ *   - With suffix: `RNSScreenStackView`, `RNSScreenStackViewManager`,
+ *     `RNSScreenStackComponentView`, `RNSScreenStackManager`
+ *
+ * This synthesizer walks every Fabric component node and looks for a
+ * native class matching one of those names; when found, emits a
+ * `calls` edge `component → native class` (provenance `'heuristic'`,
+ * `synthesizedBy:'fabric-native-impl'`) so trace from JSX usage of the
+ * component continues into native.
+ *
+ * The convention-based suffix lookup is precise: there's no name
+ * collision in RN view-manager codebases by design (Codegen output would
+ * conflict otherwise).
+ */
+const FABRIC_NATIVE_SUFFIXES = ['', 'View', 'ViewManager', 'ComponentView', 'Manager'];
+
+/**
+ * Expo Modules cross-platform pairing. An Expo Module exposes the SAME
+ * JS-visible method (`AsyncFunction("getBatteryLevelAsync")`) from BOTH an iOS
+ * (Swift) and an Android (Kotlin) implementation. A JS callsite name-resolves to
+ * only ONE of them, so the other platform's impl looked like nothing called it
+ * (and editing it showed no blast radius). Link the iOS and Android impls of the
+ * same `<module>.<method>` to each other (both directions), so a JS call that
+ * reaches one platform reaches the other, and editing either surfaces the JS
+ * caller. The Expo method nodes are id-prefixed `expo-module:` and qualified
+ * `<file>::<module>.<method>` by the framework extractor.
+ */
+function expoCrossPlatformEdges(queries: QueryBuilder): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  const byKey = new Map<string, Node[]>();
+  for (const m of queries.getNodesByKind('method')) {
+    if (!m.id.startsWith('expo-module:')) continue;
+    const key = m.qualifiedName.split('::').pop(); // `<module>.<method>`
+    if (!key) continue;
+    const arr = byKey.get(key);
+    if (arr) arr.push(m);
+    else byKey.set(key, [m]);
+  }
+  for (const group of byKey.values()) {
+    if (group.length < 2) continue;
+    for (const a of group) {
+      for (const b of group) {
+        if (a.id === b.id || a.language === b.language) continue; // cross-platform only
+        const key = `${a.id}>${b.id}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        edges.push({
+          source: a.id,
+          target: b.id,
+          kind: 'calls',
+          line: a.startLine,
+          provenance: 'heuristic',
+          metadata: { synthesizedBy: 'expo-cross-platform', via: a.name },
+        });
+      }
+    }
+  }
+  return edges;
+}
+
+/**
+ * Classic React Native NativeModules cross-platform pairing. A native module
+ * method (`@ReactMethod` on Android, `RCT_EXPORT_METHOD` on iOS) is implemented
+ * on BOTH platforms, but a JS callsite name-resolves to only ONE — so the other
+ * platform's impl looked like nothing called it. A native method that HAS a JS
+ * caller is a confirmed bridge method; link it to the same-named native method
+ * in another language (the other platform's impl) so a JS call reaching one
+ * platform reaches the other, and editing either surfaces the JS caller.
+ *
+ * Names are normalized to the first selector keyword (`getFreeDiskStorage:` →
+ * `getFreeDiskStorage`) — that's the JS-visible name, and how the iOS selector
+ * lines up with the bare Android method name.
+ */
+function rnCrossPlatformEdges(queries: QueryBuilder): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  const NATIVE = new Set(['java', 'kotlin', 'objc', 'cpp']);
+  const JS = new Set(['typescript', 'tsx', 'javascript', 'jsx']);
+  // RN module INFRASTRUCTURE methods exist on every native module (called by the
+  // RN runtime, not user JS), so pairing them by name would cross-link unrelated
+  // modules in a multi-module repo. Skip them — they aren't user-facing methods.
+  const RN_INFRA = new Set([
+    'addListener', 'removeListeners', 'getConstants', 'constantsToExport', 'getName',
+    'invalidate', 'initialize', 'getDefaultEventTypes', 'supportedEvents',
+    'requiresMainQueueSetup', 'methodQueue',
+  ]);
+  const norm = (name: string): string => {
+    const i = name.indexOf(':');
+    return i >= 0 ? name.slice(0, i) : name;
+  };
+
+  // Index native methods by their JS-visible (normalized) name. Only names with
+  // impls in ≥2 native languages can pair, so the per-method JS-caller check
+  // below only runs for genuine cross-platform candidates.
+  const byName = new Map<string, Node[]>();
+  for (const m of queries.iterateNodesByKind('method')) {
+    if (!NATIVE.has(m.language)) continue;
+    const key = norm(m.name);
+    const arr = byName.get(key);
+    if (arr) arr.push(m);
+    else byName.set(key, [m]);
+  }
+
+  for (const [groupName, group] of byName) {
+    if (RN_INFRA.has(groupName)) continue;
+    const langs = new Set(group.map((m) => m.language));
+    if (langs.size < 2) continue; // single-platform — nothing to pair
+    for (const m of group) {
+      // Is m a bridge method? (a JS-language `calls` edge points at it)
+      const incoming = queries.getIncomingEdges(m.id, ['calls']);
+      if (incoming.length === 0) continue;
+      const sources = queries.getNodesByIds(incoming.map((e) => e.source));
+      const isBridge = incoming.some((e) => {
+        const s = sources.get(e.source);
+        return !!s && JS.has(s.language);
+      });
+      if (!isBridge) continue;
+      // Link to the other-platform impls (both directions).
+      for (const sib of group) {
+        if (sib.id === m.id || sib.language === m.language) continue;
+        for (const [a, b] of [[m, sib], [sib, m]] as const) {
+          const key = `${a.id}>${b.id}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          edges.push({
+            source: a.id,
+            target: b.id,
+            kind: 'calls',
+            line: a.startLine,
+            provenance: 'heuristic',
+            metadata: { synthesizedBy: 'rn-cross-platform', via: norm(m.name) },
+          });
+        }
+      }
+    }
+  }
+  return edges;
+}
+
+function fabricNativeImplEdges(ctx: ResolutionContext): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+
+  // The Fabric extractor IDs are prefixed `fabric-component:` so we can
+  // filter to just those without iterating all `component` nodes.
+  const components = ctx.getNodesByKind('component').filter((n) => n.id.startsWith('fabric-component:'));
+  if (components.length === 0) return edges;
+
+  // Pre-index native classes by name for O(1) lookup.
+  const nativeClassesByName = new Map<string, Node[]>();
+  for (const n of ctx.getNodesByKind('class')) {
+    if (n.language !== 'objc' && n.language !== 'kotlin' && n.language !== 'java' && n.language !== 'cpp') continue;
+    const arr = nativeClassesByName.get(n.name);
+    if (arr) arr.push(n);
+    else nativeClassesByName.set(n.name, [n]);
+  }
+
+  for (const component of components) {
+    for (const suffix of FABRIC_NATIVE_SUFFIXES) {
+      const candidate = component.name + suffix;
+      const matches = nativeClassesByName.get(candidate);
+      if (!matches || matches.length === 0) continue;
+      // Link the component node to every matching native class (iOS +
+      // Android each have one).
+      for (const native of matches) {
+        const key = `${component.id}>${native.id}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        edges.push({
+          source: component.id,
+          target: native.id,
+          kind: 'calls',
+          provenance: 'heuristic',
+          metadata: {
+            synthesizedBy: 'fabric-native-impl',
+            viaSuffix: suffix || '(exact)',
+            componentName: component.name,
+          },
+        });
+      }
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * MyBatis: link a Java mapper interface method to the XML statement that holds
+ * its SQL. The XML extractor (`src/extraction/mybatis-extractor.ts`) qualifies
+ * each `<select|insert|update|delete|sql id="X">` as `<namespace>::<id>` where
+ * `<namespace>` is the Java FQN of the mapper interface. A Java method's
+ * qualifiedName ends with `<ClassName>::<methodName>`, so we suffix-match the
+ * last two segments of the XML qualified name to find a unique Java method by
+ * `<ClassName>::<methodName>` (`ClassName` = last dotted segment of the XML
+ * namespace). Cross-mapper `<include refid="other.X">` references go through
+ * the normal qualified-name resolver — only the Java↔XML bridge is synthetic.
+ *
+ * Precision over recall: ambiguous mappers (multiple Java classes with the
+ * same simple name) are dropped. We need-not bridge by package because Java
+ * mapper interfaces are typically uniquely named within a project.
+ */
+function mybatisJavaXmlEdges(queries: QueryBuilder): Edge[] {
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  // Index Java methods by `<ClassName>::<methodName>` for O(1) lookup.
+  const javaIndex = new Map<string, Node[]>();
+  for (const m of queries.iterateNodesByKind('method')) {
+    if (m.language !== 'java' && m.language !== 'kotlin') continue;
+    const parts = m.qualifiedName.split('::');
+    const last = parts[parts.length - 1];
+    const cls = parts[parts.length - 2];
+    if (!last || !cls) continue;
+    const key = `${cls}::${last}`;
+    const arr = javaIndex.get(key);
+    if (arr) arr.push(m); else javaIndex.set(key, [m]);
+  }
+
+  for (const xml of queries.iterateNodesByKind('method')) {
+    if (xml.language !== 'xml') continue;
+    // Qualified name: `<namespace>::<id>`. Extract the simple class name.
+    const colonIdx = xml.qualifiedName.lastIndexOf('::');
+    if (colonIdx < 0) continue;
+    const namespace = xml.qualifiedName.slice(0, colonIdx);
+    const id = xml.qualifiedName.slice(colonIdx + 2);
+    if (!namespace || !id) continue;
+    const dotIdx = namespace.lastIndexOf('.');
+    const className = dotIdx >= 0 ? namespace.slice(dotIdx + 1) : namespace;
+    const candidates = javaIndex.get(`${className}::${id}`);
+    if (!candidates || candidates.length === 0) continue;
+    // Drop ambiguous matches (multiple same-name classes); the user can
+    // disambiguate by adding the package-suffix match in a future enhancement.
+    if (candidates.length > 1) continue;
+    const java = candidates[0]!;
+    const key = `${java.id}>${xml.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    edges.push({
+      source: java.id,
+      target: xml.id,
+      kind: 'calls',
+      line: java.startLine,
+      provenance: 'heuristic',
+      metadata: {
+        synthesizedBy: 'mybatis-java-xml',
+        via: `${className}.${id}`,
+        registeredAt: `${xml.filePath}:${xml.startLine}`,
+      },
+    });
+  }
+  return edges;
+}
+
+/**
+ * Gin middleware chain. Gin runs its entire handler chain through one dynamic
+ * line in `(*Context).Next`:
+ *     for c.index < len(c.handlers) { c.handlers[c.index](c); c.index++ }
+ * `c.handlers` is a `HandlersChain` (`[]HandlerFunc`) assembled at registration
+ * time by `combineHandlers` from the funcs passed to `r.Use(...)` /
+ * `r.GET("/path", h...)` / `r.Handle(...)`. Because the call is a computed index
+ * into a runtime-built slice, tree-sitter resolves `c.handlers[c.index](c)` to
+ * NOTHING — so `callees(Next)` is just the `len()` helper and the flow
+ * `ServeHTTP → handleHTTPRequest → Next` dead-ends at the exact symbol the
+ * "how do requests flow through the middleware chain" question is about. The
+ * agent then re-queries Next and falls back to Read/grep (validated: the gin
+ * WITH-arm rabbit-holed on precisely this dead-end).
+ *
+ * Bridge it: find the chain DISPATCHER (a Go method whose body invokes a
+ * `handlers` slice by index) and link it → every HandlerFunc registered via a
+ * gin registration call, so `callees(Next)` and `trace(ServeHTTP, <handler>)`
+ * connect end-to-end. Named handlers only (`gin.Logger()` → `Logger`,
+ * `authMiddleware`); inline closures are anonymous and skipped. Like
+ * react-render / interface-impl this is a deliberate over-approximation —
+ * reachability-correct (any registered handler CAN run for some route), capped,
+ * and gated on the dispatcher existing so it never runs on non-gin Go repos.
+ * Provenance `heuristic`, `synthesizedBy:'gin-middleware-chain'`; `registeredAt`
+ * is the `.Use`/`.GET` site an agent would otherwise grep for.
+ */
+const GIN_DISPATCH_RE = /\.handlers\s*\[[^\]]*\]\s*\(/;                 // c.handlers[c.index](c)
+const GIN_REG_RE = /\.(?:Use|GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD|Any|Handle)\s*\(/g;
+
+/** Balanced `(...)` body starting at the '(' index; null if unbalanced. */
+function goBalancedArgs(s: string, openIdx: number): string | null {
+  let depth = 0;
+  for (let i = openIdx; i < s.length; i++) {
+    const c = s[i];
+    if (c === '(') depth++;
+    else if (c === ')') { depth--; if (depth === 0) return s.slice(openIdx + 1, i); }
+  }
+  return null;
+}
+/** Split a top-level comma list, respecting nested () [] {}. */
+function goSplitArgs(args: string): string[] {
+  const out: string[] = [];
+  let depth = 0, cur = '';
+  for (const c of args) {
+    if (c === '(' || c === '[' || c === '{') { depth++; cur += c; }
+    else if (c === ')' || c === ']' || c === '}') { depth--; cur += c; }
+    else if (c === ',' && depth === 0) { out.push(cur); cur = ''; }
+    else cur += c;
+  }
+  if (cur.trim()) out.push(cur);
+  return out;
+}
+/** Tail ident of a handler arg: `gin.Logger()`→`Logger`, `mw`→`mw`; null for string paths / closures. */
+function goHandlerIdent(expr: string): string | null {
+  const cleaned = expr.trim().replace(/\(\s*\)$/, '');                  // drop a trailing call ()
+  if (!cleaned || cleaned.startsWith('"') || cleaned.startsWith('`') || cleaned.startsWith('func')) return null;
+  const m = cleaned.match(/(?:\.|^)([A-Za-z_]\w*)$/);
+  return m ? m[1]! : null;
+}
+
+function ginMiddlewareChainEdges(queries: QueryBuilder, ctx: ResolutionContext): Edge[] {
+  // 1. Find the chain dispatcher(s): a Go method that invokes a `handlers` slice by index.
+  const dispatchers: Node[] = [];
+  for (const n of queries.iterateNodesByKind('method')) {
+    if (n.language !== 'go') continue;
+    const content = ctx.readFile(n.filePath);
+    const src = content && sliceLines(content, n.startLine, n.endLine);
+    if (src && GIN_DISPATCH_RE.test(src)) dispatchers.push(n);
+  }
+  if (dispatchers.length === 0) return [];                              // not a gin repo — bail
+
+  // 2. Collect handler identifiers registered via gin registration calls
+  //    (.Use / .GET / … / .Handle). String args (paths/methods) and inline
+  //    closures are dropped by goHandlerIdent; the rest are HandlerFuncs.
+  const registered = new Map<string, string>();                         // name → registeredAt (file:line)
+  for (const file of ctx.getAllFiles()) {
+    if (!file.endsWith('.go')) continue;
+    const content = ctx.readFile(file);
+    if (!content || (!content.includes('.Use(') && !/\.(?:GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD|Any|Handle)\(/.test(content))) continue;
+    const safe = stripCommentsForRegex(content, 'go');
+    GIN_REG_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = GIN_REG_RE.exec(safe))) {
+      const parenIdx = m.index + m[0].length - 1;
+      const argStr = goBalancedArgs(safe, parenIdx);
+      if (!argStr) continue;
+      const line = safe.slice(0, m.index).split('\n').length;
+      for (const arg of goSplitArgs(argStr)) {
+        const name = goHandlerIdent(arg);
+        if (name && !registered.has(name)) registered.set(name, `${file}:${line}`);
+      }
+    }
+  }
+  if (registered.size === 0) return [];
+
+  // 3. Link each dispatcher → each registered handler node (dedup, capped).
+  const edges: Edge[] = [];
+  const seen = new Set<string>();
+  for (const disp of dispatchers) {
+    let added = 0;
+    for (const [name, registeredAt] of registered) {
+      if (added >= MAX_CALLBACKS_PER_CHANNEL) break;
+      const handler = ctx.getNodesByName(name).find(
+        (n) => (n.kind === 'function' || n.kind === 'method') && n.language === 'go'
+      );
+      if (!handler || handler.id === disp.id) continue;
+      const key = `${disp.id}>${handler.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push({
+        source: disp.id, target: handler.id, kind: 'calls', line: disp.startLine,
+        provenance: 'heuristic',
+        metadata: { synthesizedBy: 'gin-middleware-chain', via: name, registeredAt },
+      });
+      added++;
+    }
+  }
+  return edges;
+}
+
+/**
+ * Delphi form code-behind: a form unit `UFRMAbout.pas` owns its visual form
+ * definition `UFRMAbout.dfm` (VCL) / `.fmx` (FireMonkey) — paired by basename in
+ * the same directory, wired by the `{$R *.dfm}` directive rather than a `uses`
+ * clause. Link the unit → its form so a `.dfm`/`.fmx` used only as a form
+ * definition isn't orphaned, and editing the form surfaces its code-behind unit.
+ */
+function pascalFormEdges(ctx: ResolutionContext): Edge[] {
+  const edges: Edge[] = [];
+  const allFiles = new Set(ctx.getAllFiles());
+  for (const file of allFiles) {
+    if (!/\.(dfm|fmx)$/i.test(file)) continue;
+    const pasFile = file.replace(/\.(dfm|fmx)$/i, '.pas');
+    if (!allFiles.has(pasFile)) continue;
+    const formNode = ctx.getNodesInFile(file).find((n) => n.kind === 'file');
+    const unitNode = ctx.getNodesInFile(pasFile).find((n) => n.kind === 'file');
+    if (!formNode || !unitNode) continue;
+    edges.push({
+      source: unitNode.id,
+      target: formNode.id,
+      kind: 'references',
+      line: unitNode.startLine,
+      provenance: 'heuristic',
+      metadata: { synthesizedBy: 'pascal-form', registeredAt: pasFile },
+    });
+  }
+  return edges;
+}
+
+/**
+ * SvelteKit file-convention data flow. A route directory's `+page.svelte` (a
+ * `component` node) receives its `data` from the sibling `+page.server.{ts,js}`
+ * / `+page.{ts,js}` `load` function and posts forms to its `actions` — wired by
+ * the framework BY FILE PATH, with no static import between them. So editing a
+ * `load` shows no impact on the page it feeds, and the page looks like it has no
+ * server-side dependency. Link the page component to its sibling loader's
+ * `load` / `actions` (same for `+layout`). The pairing is path-deterministic
+ * (same directory, matching `+page`/`+layout` prefix), so it's precise — but
+ * it's a framework-convention edge, so provenance stays `heuristic`.
+ *
+ * Direction: page → load, so `getImpactRadius(load)` surfaces the page (editing
+ * a loader's data shows the page it feeds) and the page's dependencies include
+ * its loader.
+ */
+function svelteKitLoadEdges(ctx: ResolutionContext): Edge[] {
+  const edges: Edge[] = [];
+  const allFiles = new Set(ctx.getAllFiles());
+  const HOOKS = new Set(['load', 'actions']);
+  const HOOK_KINDS = new Set(['function', 'method', 'constant', 'variable']);
+  for (const file of allFiles) {
+    const m = file.match(/(.*\/)(\+(?:page|layout))\.svelte$/);
+    if (!m) continue;
+    const dir = m[1]!;
+    const prefix = m[2]!;
+    const page = ctx.getNodesInFile(file).find((n) => n.kind === 'component');
+    if (!page) continue;
+    for (const ext of ['.server.ts', '.server.js', '.ts', '.js']) {
+      const loaderFile = `${dir}${prefix}${ext}`;
+      if (!allFiles.has(loaderFile)) continue;
+      for (const hook of ctx.getNodesInFile(loaderFile)) {
+        if (!HOOK_KINDS.has(hook.kind) || !HOOKS.has(hook.name)) continue;
+        edges.push({
+          source: page.id,
+          target: hook.id,
+          kind: 'references',
+          line: page.startLine,
+          provenance: 'heuristic',
+          metadata: {
+            synthesizedBy: 'sveltekit-load',
+            via: hook.name,
+            registeredAt: `${loaderFile}:${hook.startLine ?? 0}`,
+          },
+        });
+      }
+    }
+  }
+  return edges;
+}
+
+/**
+ * Synthesize dispatcher→callback edges (field observers + EventEmitters +
+ * React re-render + JSX children + Vue templates + SvelteKit load + RN event
+ * channel + Fabric native-impl + MyBatis Java↔XML + Gin middleware chain).
+ * Returns the count added. Never throws into indexing — callers wrap in try/catch.
+ */
+export function synthesizeCallbackEdges(queries: QueryBuilder, ctx: ResolutionContext): number {
+  // Cross-file Go method→type `contains` edges must be synthesized AND persisted
+  // FIRST: a method declared in a different file from its receiver type is
+  // otherwise orphaned from the struct, and goImplementsEdges (next) derives a
+  // struct's method set from its `contains` edges — so without this it would
+  // under-count the interfaces a cross-file struct satisfies. (#583)
+  const goMethodContains = goCrossFileMethodContainsEdges(queries);
+  if (goMethodContains.length > 0) queries.insertEdges(goMethodContains);
+
+  // Go implicit `implements` edges must be synthesized AND persisted next: the
+  // interface-dispatch bridge below reads `implements` edges from the DB, and
+  // Go has none statically. (Other languages already have static implements
+  // edges from extraction, so they don't need this pre-pass.)
+  const goImpl = goImplementsEdges(queries);
+  if (goImpl.length > 0) queries.insertEdges(goImpl);
+
+  const fieldEdges = fieldChannelEdges(queries, ctx);
+  const closureCollEdges = closureCollectionEdges(queries, ctx);
+  const emitterEdges = eventEmitterEdges(ctx);
+  const renderEdges = reactRenderEdges(queries, ctx);
+  const jsxEdges = reactJsxChildEdges(ctx);
+  const vueEdges = vueTemplateEdges(ctx);
+  const svelteKitEdges = svelteKitLoadEdges(ctx);
+  const pascalEdges = pascalFormEdges(ctx);
+  const flutterEdges = flutterBuildEdges(queries, ctx);
+  const cppEdges = cppOverrideEdges(queries);
+  const ifaceEdges = interfaceOverrideEdges(queries);
+  const kotlinExpectActual = kotlinExpectActualEdges(queries);
+  const goGrpcEdges = goGrpcStubImplEdges(queries);
+  const rnEventEdgesList = rnEventEdges(ctx);
+  const fabricNativeEdges = fabricNativeImplEdges(ctx);
+  const expoXPlatEdges = expoCrossPlatformEdges(queries);
+  const rnXPlatEdges = rnCrossPlatformEdges(queries);
+  const mybatisEdges = mybatisJavaXmlEdges(queries);
+  const ginEdges = ginMiddlewareChainEdges(queries, ctx);
+
+  const merged: Edge[] = [];
+  const seen = new Set<string>();
+  for (const e of [
+    ...fieldEdges,
+    ...closureCollEdges,
+    ...emitterEdges,
+    ...renderEdges,
+    ...jsxEdges,
+    ...vueEdges,
+    ...svelteKitEdges,
+    ...pascalEdges,
+    ...flutterEdges,
+    ...cppEdges,
+    ...ifaceEdges,
+    ...kotlinExpectActual,
+    ...goGrpcEdges,
+    ...rnEventEdgesList,
+    ...fabricNativeEdges,
+    ...expoXPlatEdges,
+    ...rnXPlatEdges,
+    ...mybatisEdges,
+    ...ginEdges,
+  ]) {
+    const key = `${e.source}>${e.target}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(e);
+  }
+  if (merged.length > 0) queries.insertEdges(merged);
+  return merged.length + goImpl.length + goMethodContains.length;
+}
diff --git a/src/resolution/frameworks/astro.ts b/src/resolution/frameworks/astro.ts
new file mode 100644
index 000000000..63e1af132
--- /dev/null
+++ b/src/resolution/frameworks/astro.ts
@@ -0,0 +1,195 @@
+/**
+ * Astro Framework Resolver
+ *
+ * Handles Astro component references, the `Astro` global, `astro:*` virtual
+ * module imports, and Astro's `src/pages/` file-based routing.
+ */
+
+import { Node } from '../../types';
+import { FrameworkResolver, UnresolvedRef, ResolvedRef, ResolutionContext } from '../types';
+
+/**
+ * Astro virtual module prefixes — framework-provided, not user code
+ */
+const ASTRO_VIRTUAL_MODULES = [
+  'astro:content',
+  'astro:assets',
+  'astro:actions',
+  'astro:env',
+  'astro:i18n',
+  'astro:middleware',
+  'astro:transitions',
+  'astro:components',
+  'astro:schema',
+];
+
+export const astroResolver: FrameworkResolver = {
+  name: 'astro',
+
+  detect(context: ResolutionContext): boolean {
+    // Check for astro in package.json
+    const packageJson = context.readFile('package.json');
+    if (packageJson) {
+      try {
+        const pkg = JSON.parse(packageJson);
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (deps.astro) {
+          return true;
+        }
+      } catch {
+        // Invalid JSON
+      }
+    }
+
+    // Check for .astro files in project
+    const allFiles = context.getAllFiles();
+    return allFiles.some((f) => f.endsWith('.astro'));
+  },
+
+  resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null {
+    // Pattern 1: the `Astro` global (Astro.props, Astro.url, Astro.params, …)
+    // — runtime-provided in every component's frontmatter. Resolving it as
+    // framework-provided keeps it from name-matching a user symbol named Astro.
+    if (ref.referenceName === 'Astro' || ref.referenceName.startsWith('Astro.')) {
+      return {
+        original: ref,
+        targetNodeId: ref.fromNodeId,
+        confidence: 1.0,
+        resolvedBy: 'framework',
+      };
+    }
+
+    // Pattern 2: astro:* virtual module imports (astro:content, astro:assets, …)
+    if (ref.referenceKind === 'imports' && ref.referenceName.startsWith('astro:')) {
+      if (ASTRO_VIRTUAL_MODULES.some((prefix) => ref.referenceName.startsWith(prefix))) {
+        return {
+          original: ref,
+          targetNodeId: ref.fromNodeId,
+          confidence: 1.0,
+          resolvedBy: 'framework',
+        };
+      }
+    }
+
+    // Pattern 3: Component references (PascalCase) — resolve to component
+    // nodes. Template tags arrive as `references`, frontmatter expression
+    // usages as `calls`.
+    if (
+      isPascalCase(ref.referenceName) &&
+      (ref.referenceKind === 'references' || ref.referenceKind === 'calls')
+    ) {
+      const result = resolveComponent(ref.referenceName, ref.filePath, context);
+      if (result) {
+        return {
+          original: ref,
+          targetNodeId: result,
+          confidence: 0.8,
+          resolvedBy: 'framework',
+        };
+      }
+    }
+
+    return null;
+  },
+
+  extract(filePath: string, _content: string) {
+    const nodes: Node[] = [];
+    const now = Date.now();
+
+    // Normalize to forward slashes
+    const normalized = filePath.replace(/\\/g, '/');
+
+    // Astro file-based routing lives under src/pages/ — .astro files are
+    // pages, .ts/.js files are API endpoints. (.md/.mdx pages exist too but
+    // aren't indexed as source.) Underscore-prefixed segments are excluded
+    // from routing by Astro.
+    const pagesMatch = /(?:^|\/)src\/pages\//.exec(normalized);
+    if (pagesMatch && /\.(astro|ts|js|mjs)$/.test(normalized)) {
+      const afterPages = normalized.substring(pagesMatch.index + pagesMatch[0].length);
+      const base = afterPages.split('/').pop() || '';
+
+      // Underscore-prefixed segments are excluded from routing by Astro;
+      // a stray `*.config.*` in a pages dir is never a route.
+      if (
+        !afterPages.split('/').some((segment) => segment.startsWith('_')) &&
+        !/\.config\.[a-z]+$/.test(base)
+      ) {
+        const routePath = filePathToAstroRoute(afterPages);
+
+        nodes.push({
+          id: `route:${filePath}:${routePath}:1`,
+          kind: 'route',
+          name: routePath,
+          qualifiedName: `${filePath}::route:${routePath}`,
+          filePath,
+          startLine: 1,
+          endLine: 1,
+          startColumn: 0,
+          endColumn: 0,
+          language: normalized.endsWith('.astro') ? 'astro' : 'typescript',
+          updatedAt: now,
+        });
+      }
+    }
+
+    return { nodes, references: [] };
+  },
+};
+
+/**
+ * Check if string is PascalCase
+ */
+function isPascalCase(str: string): boolean {
+  return /^[A-Z][a-zA-Z0-9]*$/.test(str);
+}
+
+/**
+ * Resolve an Astro component reference using name-based lookup
+ */
+function resolveComponent(
+  name: string,
+  fromFile: string,
+  context: ResolutionContext
+): string | null {
+  // Look for component nodes by name
+  const candidates = context.getNodesByName(name);
+  const components = candidates.filter((n) => n.kind === 'component');
+
+  if (components.length === 0) return null;
+
+  // Prefer same directory
+  const fromDir = fromFile.substring(0, fromFile.lastIndexOf('/'));
+  const sameDir = components.filter((n) => n.filePath.startsWith(fromDir));
+  if (sameDir.length > 0) return sameDir[0]!.id;
+
+  // No positional signal: only an UNAMBIGUOUS name may resolve — picking
+  // components[0] would choose an arbitrary same-named component in a
+  // multi-app monorepo (#764). Ambiguity falls through to the name-matcher,
+  // whose proximity scoring decides.
+  return components.length === 1 ? components[0]!.id : null;
+}
+
+/**
+ * Convert a path under src/pages/ to an Astro route path.
+ *
+ * blog/[slug].astro        -> /blog/:slug
+ * blog/[...path].astro     -> /blog/*path
+ * api/posts.ts             -> /api/posts
+ * index.astro              -> /
+ */
+function filePathToAstroRoute(afterPages: string): string {
+  // Remove the extension
+  const withoutExt = afterPages.replace(/\.(astro|ts|js|mjs)$/, '');
+
+  // index files map to their parent path (index -> /, blog/index -> /blog)
+  const withoutIndex = withoutExt.replace(/(^|\/)index$/, '$1').replace(/\/$/, '');
+
+  // Convert Astro param syntax
+  const route = '/' + withoutIndex
+    .replace(/\[\.\.\.([^\]]+)\]/g, '*$1') // [...rest] -> *rest (catch-all)
+    .replace(/\[([^\]]+)\]/g, ':$1'); // [param] -> :param
+
+  if (route === '/') return '/';
+  // Remove trailing slash
+  return route.replace(/\/$/, '');
+}
diff --git a/src/resolution/frameworks/csharp.ts b/src/resolution/frameworks/csharp.ts
index 73c38f35c..2c342a835 100644
--- a/src/resolution/frameworks/csharp.ts
+++ b/src/resolution/frameworks/csharp.ts
@@ -43,8 +43,22 @@ export const aspnetResolver: FrameworkResolver = {
       return true;
     }
 
-    // Check for Controllers directory
-    return allFiles.some((f) => f.includes('/Controllers/') && f.endsWith('Controller.cs'));
+    // ASP.NET signatures in controller/entrypoint SOURCE — covers feature-folder
+    // apps with no `/Controllers/` dir and a subdir `Program.cs` that the
+    // root-only checks above miss (e.g. realworld: Features/*/FooController.cs).
+    // `.csproj` often isn't in the indexed source set, so source-scan is the
+    // reliable signal.
+    for (const file of allFiles) {
+      if (!/(?:Controller|Program|Startup)\.cs$/.test(file)) continue;
+      const c = context.readFile(file);
+      if (c && (
+        /\[(?:ApiController|Route|Http(?:Get|Post|Put|Patch|Delete))\b/.test(c) ||
+        c.includes('ControllerBase') || c.includes(': Controller') ||
+        c.includes('MapControllers') || c.includes('WebApplication') ||
+        c.includes('Microsoft.AspNetCore')
+      )) return true;
+    }
+    return false;
   },
 
   resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null {
@@ -123,12 +137,20 @@ export const aspnetResolver: FrameworkResolver = {
     const now = Date.now();
     const safe = stripCommentsForRegex(content, 'csharp');
 
-    // [HttpGet("path")], [HttpPost("path")], etc.
-    const attrRegex = /\[(HttpGet|HttpPost|HttpPut|HttpPatch|HttpDelete)\s*\(\s*"([^"]+)"\s*\)\]/g;
+    // Class-level [Route("api/[controller]")] prefix — joined onto each action.
+    let classPrefix = '';
+    const cls = /\[Route\s*\(\s*"([^"]+)"[^)]*\)\]\s*(?:\[[^\]]*\]\s*)*(?:public\s+|sealed\s+|abstract\s+|partial\s+)*class\b/.exec(safe);
+    if (cls) classPrefix = cls[1]!;
+
+    // [HttpGet], [HttpGet("path")], [HttpPost("path", Name="x")] — BARE or with a
+    // path. (The old regex required a string, so bare attributes — with the route
+    // on the class [Route] — were missed; eShopOnWeb was 24 bare / 2 string.)
+    const attrRegex = /\[(HttpGet|HttpPost|HttpPut|HttpPatch|HttpDelete)(?:\s*\(\s*"([^"]+)"[^)]*\))?\s*\]/g;
     let match: RegExpExecArray | null;
     while ((match = attrRegex.exec(safe)) !== null) {
-      const [, verb, routePath] = match;
-      const method = verb!.replace(/^Http/, '').toUpperCase();
+      const verb = match[1]!;
+      const method = verb.replace(/^Http/, '').toUpperCase();
+      const routePath = joinCsPath(classPrefix, match[2] || '');
       const line = safe.slice(0, match.index).split('\n').length;
 
       const routeNode: Node = {
@@ -146,9 +168,10 @@ export const aspnetResolver: FrameworkResolver = {
       };
       nodes.push(routeNode);
 
-      // Capture the next method declaration
-      const tail = safe.slice(match.index + match[0].length);
-      const methodMatch = tail.match(/(?:public|private|protected|internal)\s+[\w<>,\s\[\]]+?\s+(\w+)\s*\(/);
+      // Next method declaration (skip stacked attributes; C# puts the return type
+      // before the name). Bounded so we don't grab a far one.
+      const tail = safe.slice(match.index + match[0].length, match.index + match[0].length + 600);
+      const methodMatch = tail.match(/(?:public|private|protected|internal)\s+[\w<>,\s\[\]?.]+?\s+(\w+)\s*\(/);
       if (methodMatch) {
         references.push({
           fromNodeId: routeNode.id,
@@ -202,6 +225,12 @@ export const aspnetResolver: FrameworkResolver = {
   },
 };
 
+/** Join a class-level [Route] prefix and an action's path into one normalized `/path`. */
+function joinCsPath(prefix: string, sub: string): string {
+  const parts = [prefix, sub].map((p) => p.replace(/^\/+|\/+$/g, '')).filter(Boolean);
+  return '/' + parts.join('/');
+}
+
 /** Extract last identifier from an expression like `MyService.Handler` or `Handler`. */
 function extractCSharpTailIdent(expr: string): string | null {
   const cleaned = expr.trim().replace(/\s+/g, '');
diff --git a/src/resolution/frameworks/drupal.ts b/src/resolution/frameworks/drupal.ts
new file mode 100644
index 000000000..0c7d533ce
--- /dev/null
+++ b/src/resolution/frameworks/drupal.ts
@@ -0,0 +1,414 @@
+/**
+ * Drupal Framework Resolver
+ *
+ * Supports Drupal 8/9/10/11 (Composer-based projects). Drupal 7 is not supported.
+ *
+ * ## What this resolver does
+ *
+ * 1. **Detection** — reads composer.json and checks for any `drupal/*` dependency in
+ *    `require` or `require-dev`.
+ *
+ * 2. **Route extraction** — parses `*.routing.yml` files and emits `route` nodes for each
+ *    Drupal route, with `references` edges to the `_controller`, `_form`, or entity handler
+ *    class/method.
+ *
+ * 3. **Hook detection** — scans `.module`, `.install`, `.theme`, and `.inc` files for Drupal
+ *    hook implementations. Two strategies are used:
+ *      a. Docblock: `@Implements hook_X()` → precise, no false positives.
+ *      b. Name pattern: function `{moduleName}_{hookSuffix}()` → catches hooks without
+ *         docblocks but may produce false positives on helper functions.
+ *    Detected hooks emit an `UnresolvedRef` from the implementing function node to the
+ *    canonical `hook_X` name, linking implementations to the hook when `codegraph_callers`
+ *    is invoked.
+ *
+ * ## Design decisions (review in future iterations)
+ *
+ * - Hook graph resolution (v1): hook references are stored as UnresolvedRef pointing to the
+ *   canonical `hook_X` name. If Drupal core is indexed, these will resolve to core hook
+ *   definitions. Without core, they remain unresolved but are still searchable via
+ *   `codegraph_search("form_alter")`. Full hook-node creation (virtual nodes for every hook)
+ *   is deferred to a future iteration.
+ *
+ * - Services / plugins (out of scope for v1): `*.services.yml` service definitions and plugin
+ *   annotations (`@Block`, `@FormElement`, etc.) are not extracted. Add a TODO below when
+ *   ready to implement.
+ *
+ * - Twig templates (out of scope for v1): `.twig` files are tracked as file nodes but no
+ *   symbol extraction is performed (no tree-sitter Twig grammar). Implement when a Twig
+ *   grammar WASM is available.
+ *
+ * ## TODOs for future iterations
+ *
+ * - TODO: Extract service definitions from `*.services.yml` files (class → service-id edges).
+ * - TODO: Extract plugin annotations (`@Block`, `@FormElement`, `@Field`, etc.) from PHP
+ *   docblocks and emit plugin nodes with references to the annotated class.
+ * - TODO: Add Twig symbol extraction when a tree-sitter Twig grammar becomes available.
+ * - TODO: Improve hook resolution: create virtual `hook_*` nodes so `codegraph_callers`
+ *   returns all implementations even when Drupal core is not indexed.
+ */
+
+import { generateNodeId } from '../../extraction/tree-sitter-helpers';
+import { Node } from '../../types';
+import { FrameworkResolver, ResolutionContext, ResolvedRef, UnresolvedRef } from '../types';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the last PHP namespace segment from a FQCN like `\Drupal\mymodule\Controller\Foo`.
+ * Returns `null` for strings that don't look like a FQCN.
+ */
+function lastSegment(fqcn: string): string | null {
+  const clean = fqcn.replace(/^\\+/, '').trim();
+  if (!clean.includes('\\')) return null;
+  const parts = clean.split('\\');
+  return parts[parts.length - 1] ?? null;
+}
+
+/**
+ * Derive the Drupal module name from a file path.
+ * e.g. `web/modules/custom/my_module/my_module.module` → `my_module`
+ */
+function moduleNameFromPath(filePath: string): string | null {
+  const match = filePath.match(/\/([^/]+)\.[^./]+$/);
+  return match ? match[1]! : null;
+}
+
+// ---------------------------------------------------------------------------
+// Route extraction helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract route nodes and handler references from a Drupal `*.routing.yml` file.
+ *
+ * Drupal routing YAML format:
+ *
+ *   route.name:
+ *     path: '/some/path'
+ *     defaults:
+ *       _controller: '\Drupal\module\Controller\MyController::method'
+ *       _form: '\Drupal\module\Form\MyForm'
+ *       _title: 'Page title'
+ *     requirements:
+ *       _permission: 'access content'
+ *     methods: [GET, POST]   # optional
+ */
+function extractDrupalRoutes(
+  filePath: string,
+  content: string
+): { nodes: Node[]; references: UnresolvedRef[] } {
+  const nodes: Node[] = [];
+  const references: UnresolvedRef[] = [];
+  const now = Date.now();
+
+  const lines = content.split('\n');
+
+  type PendingRoute = { name: string; lineNum: number };
+  let pending: PendingRoute | null = null;
+  let currentPath: string | null = null;
+  let handlerRefs: string[] = [];
+  let methods: string[] = [];
+
+  const flushRoute = () => {
+    if (!pending || !currentPath) return;
+
+    const methodTag = methods.length > 0 ? ` [${methods.join(',')}]` : '';
+    const routeNode: Node = {
+      id: `route:${filePath}:${pending.lineNum}:${currentPath}`,
+      kind: 'route',
+      name: `${currentPath}${methodTag}`,
+      qualifiedName: `${filePath}::${pending.name}`,
+      filePath,
+      startLine: pending.lineNum,
+      endLine: pending.lineNum,
+      startColumn: 0,
+      endColumn: 0,
+      language: 'yaml',
+      updatedAt: now,
+    };
+    nodes.push(routeNode);
+
+    for (const handler of handlerRefs) {
+      references.push({
+        fromNodeId: routeNode.id,
+        referenceName: handler,
+        referenceKind: 'references',
+        line: pending.lineNum,
+        column: 0,
+        filePath,
+        language: 'yaml',
+      });
+    }
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    const trimmed = line.trim();
+
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Top-level route name: no leading whitespace, ends with a colon (no value after)
+    if (/^\S.*:\s*$/.test(line) && !/^\s/.test(line)) {
+      flushRoute();
+      pending = { name: trimmed.slice(0, -1).trim(), lineNum: i + 1 };
+      currentPath = null;
+      handlerRefs = [];
+      methods = [];
+      continue;
+    }
+
+    // path: '/some/path'
+    const pathMatch = trimmed.match(/^path:\s*['"]?([^'"#\n]+?)['"]?\s*(?:#.*)?$/);
+    if (pathMatch) {
+      currentPath = pathMatch[1]!.trim();
+      continue;
+    }
+
+    // _controller: '\Drupal\...\Class::method'
+    const controllerMatch = trimmed.match(/^_controller:\s*['"]?([^'"#\n]+?)['"]?\s*(?:#.*)?$/);
+    if (controllerMatch) {
+      handlerRefs.push(controllerMatch[1]!.trim());
+      continue;
+    }
+
+    // _form: '\Drupal\...\Form\MyForm'
+    const formMatch = trimmed.match(/^_form:\s*['"]?([^'"#\n]+?)['"]?\s*(?:#.*)?$/);
+    if (formMatch) {
+      handlerRefs.push(formMatch[1]!.trim());
+      continue;
+    }
+
+    // _entity_form / _entity_list / _entity_view: entity.type
+    const entityMatch = trimmed.match(/^_(entity_form|entity_list|entity_view):\s*['"]?([^'"#\n]+?)['"]?\s*(?:#.*)?$/);
+    if (entityMatch) {
+      handlerRefs.push(entityMatch[2]!.trim());
+      continue;
+    }
+
+    // methods: [GET, POST]  or  methods: [GET]
+    const methodsMatch = trimmed.match(/^methods:\s*\[([^\]]+)\]/);
+    if (methodsMatch) {
+      methods = methodsMatch[1]!.split(',').map((m) => m.trim().toUpperCase()).filter(Boolean);
+      continue;
+    }
+  }
+
+  flushRoute();
+  return { nodes, references };
+}
+
+// ---------------------------------------------------------------------------
+// Hook detection helpers
+// ---------------------------------------------------------------------------
+
+const HOOK_FILE_EXTENSIONS = ['.module', '.install', '.theme', '.inc'];
+
+function isDrupalHookFile(filePath: string): boolean {
+  return HOOK_FILE_EXTENSIONS.some((ext) => filePath.endsWith(ext));
+}
+
+/**
+ * Extract hook implementation references from a Drupal PHP file.
+ *
+ * Strategy A (primary): look for docblocks containing `Implements hook_X().`
+ * followed immediately by the function definition. This is the Drupal coding
+ * standard and is precise.
+ *
+ * Strategy B (fallback): for functions whose name starts with `{moduleName}_`,
+ * treat the suffix as the hook name. Catches hooks without docblocks but may
+ * produce false positives on non-hook helper functions.
+ *
+ * Each detected hook emits an UnresolvedRef from the implementing function node
+ * (identified by computing the same ID tree-sitter would generate) to the
+ * canonical hook name, e.g. `hook_form_alter`.
+ */
+function extractDrupalHooks(
+  filePath: string,
+  content: string
+): { nodes: Node[]; references: UnresolvedRef[] } {
+  const references: UnresolvedRef[] = [];
+
+  // Build a map of function name → 1-indexed line number for all top-level functions.
+  // This mirrors tree-sitter's line numbering so we can reconstruct node IDs.
+  const funcLineMap = new Map<string, number>();
+  const funcDef = /^function\s+(\w+)\s*\(/gm;
+  let fm: RegExpExecArray | null;
+  while ((fm = funcDef.exec(content)) !== null) {
+    const name = fm[1]!;
+    if (!funcLineMap.has(name)) {
+      // line = number of newlines before match start + 1
+      funcLineMap.set(name, content.slice(0, fm.index).split('\n').length);
+    }
+  }
+
+  const emitHookRef = (hookName: string, funcName: string) => {
+    const lineNum = funcLineMap.get(funcName);
+    if (lineNum === undefined) return;
+    const nodeId = generateNodeId(filePath, 'function', funcName, lineNum);
+    references.push({
+      fromNodeId: nodeId,
+      referenceName: hookName,
+      referenceKind: 'references',
+      line: lineNum,
+      column: 0,
+      filePath,
+      language: 'php',
+    });
+  };
+
+  // Strategy A: docblock `Implements hook_X().` followed by function definition.
+  // The docblock and function may be separated by blank lines.
+  const docblockPattern =
+    /\/\*\*[\s\S]*?(?:@|\*\s+)Implements\s+(hook_\w+)\s*\(\)[\s\S]*?\*\/\s*\n(?:\s*\n)*function\s+(\w+)\s*\(/g;
+  const docblockMatched = new Set<string>();
+  let match: RegExpExecArray | null;
+  while ((match = docblockPattern.exec(content)) !== null) {
+    const [, hookName, funcName] = match;
+    emitHookRef(hookName!, funcName!);
+    docblockMatched.add(funcName!);
+  }
+
+  // Strategy B: fallback name-pattern matching for functions without docblocks.
+  // Only applies to functions whose name starts with {moduleName}_ and that were
+  // not already matched by Strategy A.
+  const moduleName = moduleNameFromPath(filePath);
+  if (moduleName) {
+    const prefix = moduleName + '_';
+    for (const [funcName] of funcLineMap) {
+      if (docblockMatched.has(funcName)) continue;
+      if (!funcName.startsWith(prefix)) continue;
+      const hookSuffix = funcName.slice(prefix.length);
+      if (!hookSuffix) continue;
+      // Emit a reference to hook_{suffix} — the resolver will link it if the
+      // hook is defined somewhere in the indexed graph (e.g. Drupal core).
+      emitHookRef(`hook_${hookSuffix}`, funcName);
+    }
+  }
+
+  return { nodes: [], references };
+}
+
+// ---------------------------------------------------------------------------
+// Resolver
+// ---------------------------------------------------------------------------
+
+export const drupalResolver: FrameworkResolver = {
+  name: 'drupal',
+  languages: ['php', 'yaml'],
+
+  // Drupal route handlers are FQCNs (`\Drupal\…\Class::method`, the single-colon
+  // controller-service form `\Drupal\…\Class:method`, or a bare `\…\FormClass`)
+  // and hook refs are canonical `hook_*` names — none match a declared symbol, so
+  // resolveOne's pre-filter would drop them before resolve() runs. Claim the
+  // shapes resolve() handles (mirrors the Rails `controller#action` claim).
+  claimsReference(name: string): boolean {
+    return (
+      name.startsWith('hook_') ||
+      name.includes('\\') ||
+      /^[A-Za-z_]\w*::?\w+$/.test(name)
+    );
+  },
+
+  detect(context: ResolutionContext): boolean {
+    // Primary: composer.json identifies a Drupal project/module/theme/profile.
+    // A contrib module often has an EMPTY `require` (no `drupal/*` dep) but still
+    // declares `"name": "drupal/<module>"` and `"type": "drupal-module"`, so check
+    // those too — checking deps alone misses every standalone contrib module.
+    const composer = context.readFile('composer.json');
+    if (composer) {
+      try {
+        const json = JSON.parse(composer) as {
+          name?: string;
+          type?: string;
+          require?: Record<string, string>;
+          'require-dev'?: Record<string, string>;
+        };
+        if (typeof json.name === 'string' && json.name.startsWith('drupal/')) return true;
+        if (typeof json.type === 'string' && json.type.startsWith('drupal-')) return true;
+        const deps = { ...json.require, ...(json['require-dev'] ?? {}) };
+        if (Object.keys(deps).some((k) => k.startsWith('drupal/'))) return true;
+      } catch {
+        // malformed composer.json — fall through to file-based detection
+      }
+    }
+
+    // Fallback (composer-less module, or a non-Drupal composer.json): the
+    // unmistakable Drupal signature is a `*.info.yml` manifest alongside a
+    // Drupal PHP/route file. Require both so a stray `.info.yml` elsewhere
+    // doesn't trigger a false positive.
+    const files = context.getAllFiles();
+    const hasInfoYml = files.some((f) => f.endsWith('.info.yml'));
+    if (!hasInfoYml) return false;
+    return files.some(
+      (f) =>
+        f.endsWith('.routing.yml') ||
+        f.endsWith('.module') ||
+        f.endsWith('.install') ||
+        f.endsWith('.theme')
+    );
+  },
+
+  resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null {
+    const name = ref.referenceName;
+
+    // _controller: '\Drupal\module\...\ClassName::methodName' (double colon) or the
+    // single-colon controller-service form '\Drupal\...\ClassName:methodName'.
+    const controllerMatch = name.match(/^\\?(?:Drupal\\[^:]+\\)?([^\\:]+):{1,2}(\w+)$/);
+    if (controllerMatch) {
+      const [, className, methodName] = controllerMatch;
+      const classNodes = context.getNodesByName(className!);
+      for (const cls of classNodes) {
+        if (cls.kind !== 'class') continue;
+        const fileNodes = context.getNodesInFile(cls.filePath);
+        const method = fileNodes.find((n) => n.kind === 'method' && n.name === methodName);
+        if (method) {
+          return { original: ref, targetNodeId: method.id, confidence: 0.9, resolvedBy: 'framework' };
+        }
+        return { original: ref, targetNodeId: cls.id, confidence: 0.7, resolvedBy: 'framework' };
+      }
+    }
+
+    // _form / _entity_form: '\Drupal\module\...\ClassName'  (bare FQCN, no method)
+    if (name.includes('\\') && !name.includes(':')) {
+      const className = lastSegment(name);
+      if (className) {
+        const classNodes = context.getNodesByName(className);
+        const cls = classNodes.find((n) => n.kind === 'class');
+        if (cls) {
+          return { original: ref, targetNodeId: cls.id, confidence: 0.85, resolvedBy: 'framework' };
+        }
+      }
+    }
+
+    // hook_X — find any function whose name ends in _{hookSuffix} in a hook file
+    if (name.startsWith('hook_')) {
+      const hookSuffix = name.slice(5); // strip 'hook_'
+      const candidates = context.getNodesByKind('function').filter(
+        (n) => n.name.endsWith(`_${hookSuffix}`) && isDrupalHookFile(n.filePath)
+      );
+      if (candidates.length > 0) {
+        return {
+          original: ref,
+          targetNodeId: candidates[0]!.id,
+          confidence: 0.75,
+          resolvedBy: 'framework',
+        };
+      }
+    }
+
+    return null;
+  },
+
+  extract(filePath: string, content: string): { nodes: Node[]; references: UnresolvedRef[] } {
+    if (filePath.endsWith('.routing.yml')) {
+      return extractDrupalRoutes(filePath, content);
+    }
+
+    if (isDrupalHookFile(filePath) || filePath.endsWith('.php')) {
+      return extractDrupalHooks(filePath, content);
+    }
+
+    return { nodes: [], references: [] };
+  },
+};
diff --git a/src/resolution/frameworks/expo-modules.ts b/src/resolution/frameworks/expo-modules.ts
new file mode 100644
index 000000000..a9f60174a
--- /dev/null
+++ b/src/resolution/frameworks/expo-modules.ts
@@ -0,0 +1,198 @@
+/**
+ * Expo Modules framework — close the JS → native flow for Expo SDK packages.
+ *
+ * Expo Modules use a Swift / Kotlin DSL distinct from the React Native legacy
+ * bridge. Each native module is a class extending `Module` whose
+ * `definition()` body declares the JS surface via literal `Name(...)`,
+ * `Function(...)`, `AsyncFunction(...)`, `Property(...)`, and `View {...}`
+ * calls. Tree-sitter parses these as ordinary call_expressions with trailing
+ * closures, so the JS-visible methods don't exist as named symbol nodes by
+ * default — `Camera.takePictureAsync(...)` on the JS side has nothing to
+ * resolve to.
+ *
+ * This framework extractor walks the file source for those declarative
+ * literals and emits method nodes named `takePictureAsync` /
+ * `notificationAsync` / `width` / etc., attributed to the Swift / Kotlin
+ * file. The standard name-matcher then resolves JS `Foo.takePictureAsync(...)`
+ * to them via the existing `obj.method` → method-name path — no separate
+ * resolve() branch needed.
+ *
+ * Real-world shape (expo-haptics):
+ *
+ *   public class HapticsModule: Module {
+ *     public func definition() -> ModuleDefinition {
+ *       Name("ExpoHaptics")
+ *       AsyncFunction("notificationAsync") { ... }
+ *       AsyncFunction("impactAsync") { ... }
+ *       AsyncFunction("selectionAsync") { ... }
+ *     }
+ *   }
+ *
+ * Kotlin Module declarations are the same DSL (the API mirrors Swift).
+ *
+ * Anti-goals (deferred):
+ * - The trailing-closure BODY is not extracted as the method's body — it
+ *   remains attributed to `definition()` in the existing extraction. Future
+ *   work could synthesize a body-range for richer `trace` output, but the
+ *   reachability (which is the bridge's main value) is already complete.
+ * - `View { ... }` blocks expose JSX prop bindings; that overlaps with
+ *   Fabric (Phase 6) and is left to that phase.
+ */
+import type { Node } from '../../types';
+import {
+  FrameworkExtractionResult,
+  FrameworkResolver,
+} from '../types';
+
+/**
+ * Match `Function("name")`, `AsyncFunction("name")`, or `Property("name")`
+ * at the start of an expression (line-anchored after optional whitespace).
+ * The trailing closure that follows isn't captured — we just need the name
+ * literal that becomes the JS-visible method.
+ *
+ * NOTE: the regex deliberately requires the open paren to live on the same
+ * line as the keyword, which matches every real Expo Module declaration
+ * style. Multi-line `AsyncFunction(\n"x"\n)` forms aren't a real shape in
+ * the SDK; if any appear we'd extend the regex.
+ *
+ * The optional `<…>` covers Kotlin's GENERIC-typed declarations
+ * (`AsyncFunction<Float>("getBatteryLevelAsync")`, `AsyncFunction<Int, String>(…)`)
+ * — without it, every Android Expo Module method was silently dropped, so a JS
+ * callsite resolved only to the iOS Swift impl and never the Android one.
+ */
+const EXPO_DECL_RE =
+  /\b(Function|AsyncFunction|Property|Constants)\s*(?:<[^(]*>)?\s*\(\s*["']([A-Za-z_][A-Za-z0-9_]*)["']/g;
+
+/**
+ * Match the module name literal `Name("ExpoX")`. Used to enrich each emitted
+ * method's qualifiedName so the same JS callsite to `Foo.fn` doesn't ambiguate
+ * across multiple Expo modules in a monorepo.
+ */
+const EXPO_MODULE_NAME_RE = /\bName\s*\(\s*["']([A-Za-z_][A-Za-z0-9_]*)["']/;
+
+/**
+ * Heuristic class-name match — used as a fallback if `Name(...)` literal
+ * isn't found. Detects `class XxxModule: Module` (Swift) or
+ * `class XxxModule : Module` (Kotlin / with whitespace tolerance).
+ */
+const EXPO_CLASS_RE =
+  /\bclass\s+([A-Za-z_][A-Za-z0-9_]*)\s*:\s*Module\b/;
+
+/**
+ * Detect whether a file is plausibly an Expo Module — looking for both
+ * the `: Module` inheritance and at least one declarative `Function(...)`
+ * / `AsyncFunction(...)` / `Property(...)` / `Name(...)` literal. Any one
+ * of those alone produces too many false positives (random Swift code can
+ * have `class X: Module` for unrelated reasons).
+ */
+function isExpoModuleSource(source: string): boolean {
+  if (!EXPO_CLASS_RE.test(source)) return false;
+  // Reset lastIndex defensively; EXPO_DECL_RE has the `g` flag.
+  EXPO_DECL_RE.lastIndex = 0;
+  return EXPO_DECL_RE.test(source);
+}
+
+/**
+ * Extract Expo Module method declarations from a Swift / Kotlin source
+ * file. Each `Function("X") { … }` / `AsyncFunction("X") { … }` /
+ * `Property("X") { … }` literal becomes a method node named `X`,
+ * attributed to the file at the line of the literal.
+ */
+function extractExpoMethods(filePath: string, source: string, language: 'swift' | 'kotlin'): Node[] {
+  if (!isExpoModuleSource(source)) return [];
+  const nodes: Node[] = [];
+
+  const nameMatch = source.match(EXPO_MODULE_NAME_RE);
+  const classMatch = source.match(EXPO_CLASS_RE);
+  // Prefer the explicit `Name("X")` literal — that's the JS-visible
+  // module name. Class name is the fallback.
+  const moduleName = nameMatch?.[1] ?? classMatch?.[1] ?? 'ExpoModule';
+
+  const now = Date.now();
+  const seenAtLine = new Set<string>();
+  EXPO_DECL_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = EXPO_DECL_RE.exec(source)) !== null) {
+    const kind = m[1]!;
+    const methodName = m[2]!;
+    // Compute line number from match index.
+    const before = source.slice(0, m.index);
+    const startLine = before.split('\n').length;
+    // Avoid duplicates if the same method literal appears twice in one
+    // file (e.g., declared and re-declared inside a `View {...}` block).
+    const dedupKey = `${methodName}:${startLine}`;
+    if (seenAtLine.has(dedupKey)) continue;
+    seenAtLine.add(dedupKey);
+
+    const startColumn = before.length - before.lastIndexOf('\n') - 1;
+    nodes.push({
+      id: `expo-module:${filePath}:${moduleName}:${methodName}:${startLine}`,
+      kind: 'method',
+      name: methodName,
+      qualifiedName: `${filePath}::${moduleName}.${methodName}`,
+      filePath,
+      language,
+      startLine,
+      // We don't extract the closure body's end-line — use the literal's
+      // line as a single-line range. trace/explore still surfaces the
+      // declaration site, which is the main user-visible signal.
+      endLine: startLine,
+      startColumn,
+      endColumn: startColumn + kind.length + 2 + methodName.length + 2,
+      docstring: `Expo Modules ${kind}("${methodName}") in ${moduleName}`,
+      signature: `${kind}("${methodName}")`,
+      isExported: true,
+      updatedAt: now,
+    });
+  }
+
+  return nodes;
+}
+
+export const expoModulesResolver: FrameworkResolver = {
+  name: 'expo-modules',
+  languages: ['swift', 'kotlin'],
+
+  /**
+   * Detect Expo Modules by looking at the project's package.json or
+   * a small scan of source files for the `: Module` + declarative-DSL
+   * markers. Either signal suffices.
+   */
+  detect(context) {
+    const pkg = context.readFile('package.json');
+    if (pkg && /["']expo-modules-core["']\s*:/.test(pkg)) return true;
+    const files = context.getAllFiles();
+    for (let i = 0; i < Math.min(files.length, 200); i++) {
+      const f = files[i];
+      if (!f) continue;
+      if (f.endsWith('.swift') || f.endsWith('.kt')) {
+        const src = context.readFile(f);
+        if (src && isExpoModuleSource(src)) return true;
+      }
+    }
+    return false;
+  },
+
+  /**
+   * Per-file extraction — the orchestrator invokes this for every
+   * `.swift` / `.kt` file in the project. We only emit nodes when the
+   * file looks like an Expo Module; otherwise return empty.
+   */
+  extract(filePath, source): FrameworkExtractionResult {
+    const language = filePath.endsWith('.kt') ? 'kotlin' : 'swift';
+    return {
+      nodes: extractExpoMethods(filePath, source, language),
+      references: [],
+    };
+  },
+
+  /**
+   * No bespoke resolution needed — the synthetic method nodes emitted by
+   * `extract()` get picked up by the standard name-matcher when a JS
+   * callsite like `Foo.takePictureAsync(args)` resolves. Returning null
+   * here is correct.
+   */
+  resolve() {
+    return null;
+  },
+};
diff --git a/src/resolution/frameworks/express.ts b/src/resolution/frameworks/express.ts
index 8db728463..aff2c6407 100644
--- a/src/resolution/frameworks/express.ts
+++ b/src/resolution/frameworks/express.ts
@@ -14,6 +14,39 @@ function extractTailIdent(expr: string): string | null {
   return m ? m[1]! : null;
 }
 
+/**
+ * Index of the delimiter matching the one at `open`, skipping string/template
+ * literals so a `)` or `}` inside a string doesn't throw off the balance.
+ */
+function matchDelim(s: string, open: number, oc: string, cc: string): number {
+  let depth = 0;
+  for (let i = open; i < s.length; i++) {
+    const ch = s[i];
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const q = ch;
+      i++;
+      while (i < s.length && s[i] !== q) { if (s[i] === '\\') i++; i++; }
+      continue;
+    }
+    if (ch === oc) depth++;
+    else if (ch === cc) { depth--; if (depth === 0) return i; }
+  }
+  return -1;
+}
+
+// Express res/req methods + common JS builtins — calls to these inside a handler
+// body are framework/noise, not the business flow we want to surface as route edges.
+const RESERVED_CALLS = new Set([
+  'json', 'jsonp', 'send', 'sendStatus', 'sendFile', 'status', 'end', 'redirect',
+  'render', 'set', 'get', 'header', 'type', 'format', 'attachment', 'download',
+  'cookie', 'clearCookie', 'append', 'location', 'vary', 'links', 'accepts', 'is',
+  'next', 'then', 'catch', 'finally', 'resolve', 'reject', 'all', 'race',
+  'map', 'filter', 'forEach', 'reduce', 'find', 'push', 'pop', 'slice', 'splice',
+  'includes', 'keys', 'values', 'entries', 'assign', 'parse', 'stringify',
+  'log', 'error', 'warn', 'info', 'String', 'Number', 'Boolean', 'Array', 'Object',
+  'Date', 'Math', 'JSON', 'Promise', 'require', 'fail', 'redirect',
+]);
+
 export const expressResolver: FrameworkResolver = {
   name: 'express',
   languages: ['javascript', 'typescript'],
@@ -105,41 +138,83 @@ export const expressResolver: FrameworkResolver = {
     const now = Date.now();
     const lang = detectLanguage(filePath);
     const safe = stripCommentsForRegex(content, lang);
-    // (app|router).METHOD('/path', handler-expr)
-    const regex = /\b(app|router)\.(get|post|put|patch|delete|all|use)\s*\(\s*['"]([^'"]+)['"]\s*,\s*([^)]+)\)/g;
+    // Match the route head up to the first arg: (app|router).METHOD('/path',
+    // (NOT the whole call — handlers are often inline arrows whose `)`/`{}` the
+    // old single-regex couldn't span, so inline-handler routes connected to nothing.)
+    const head = /\b(app|router)\.(get|post|put|patch|delete|all|use)\s*\(\s*['"]([^'"]+)['"]\s*,/g;
     let match: RegExpExecArray | null;
-    while ((match = regex.exec(safe)) !== null) {
-      const [, _obj, method, routePath, handlers] = match;
-      if (method === 'use' && !routePath!.startsWith('/')) continue;
+    while ((match = head.exec(safe)) !== null) {
+      const method = match[2]!;
+      const routePath = match[3]!;
+      if (method === 'use' && !routePath.startsWith('/')) continue;
       const line = safe.slice(0, match.index).split('\n').length;
       const routeNode: Node = {
-        id: `route:${filePath}:${line}:${method!.toUpperCase()}:${routePath}`,
+        id: `route:${filePath}:${line}:${method.toUpperCase()}:${routePath}`,
         kind: 'route',
-        name: `${method!.toUpperCase()} ${routePath}`,
-        qualifiedName: `${filePath}::${method!.toUpperCase()}:${routePath}`,
+        name: `${method.toUpperCase()} ${routePath}`,
+        qualifiedName: `${filePath}::${method.toUpperCase()}:${routePath}`,
         filePath,
         startLine: line,
         endLine: line,
         startColumn: 0,
         endColumn: match[0].length,
-        language: detectLanguage(filePath),
+        language: lang,
         updatedAt: now,
       };
       nodes.push(routeNode);
-      // Handler is the LAST comma-separated argument; earlier ones are middleware.
-      const parts = handlers!.split(',').map((s) => s.trim()).filter(Boolean);
-      const last = parts[parts.length - 1];
-      const handlerName = last ? extractTailIdent(last) : null;
-      if (handlerName) {
-        references.push({
-          fromNodeId: routeNode.id,
-          referenceName: handlerName,
-          referenceKind: 'references',
-          line,
-          column: 0,
-          filePath,
-          language: detectLanguage(filePath),
-        });
+
+      // The full argument list = balanced parens from the route call's open paren.
+      const openParen = safe.indexOf('(', match.index);
+      const closeParen = openParen >= 0 ? matchDelim(safe, openParen, '(', ')') : -1;
+      const args = closeParen > openParen ? safe.slice(openParen + 1, closeParen) : '';
+      const arrowAt = args.indexOf('=>');
+
+      if (arrowAt >= 0) {
+        // Inline arrow handler (`router.post('/x', async (req,res) => {…})`). The
+        // arrow is anonymous, so its body — the actual request→service flow — would
+        // be lost. Attribute the body's calls to the route node as `calls` edges so
+        // `trace(route, service)` connects. Body = balanced `{…}` after `=>`, or the
+        // single-expression tail for `=> expr` arrows.
+        const afterArrow = args.slice(arrowAt + 2);
+        const braceAt = afterArrow.indexOf('{');
+        let body = afterArrow;
+        if (braceAt >= 0 && afterArrow.slice(0, braceAt).trim() === '') {
+          const end = matchDelim(afterArrow, braceAt, '{', '}');
+          if (end > braceAt) body = afterArrow.slice(braceAt + 1, end);
+        }
+        const callRe = /\b([A-Za-z_$][\w$]*)\s*\(/g;
+        const seen = new Set<string>();
+        let cm: RegExpExecArray | null;
+        while ((cm = callRe.exec(body)) !== null) {
+          const name = cm[1]!;
+          if (seen.has(name) || RESERVED_CALLS.has(name)) continue;
+          seen.add(name);
+          references.push({
+            fromNodeId: routeNode.id,
+            referenceName: name,
+            referenceKind: 'calls',
+            line,
+            column: 0,
+            filePath,
+            language: lang,
+          });
+        }
+      } else {
+        // Named handler: the LAST comma-separated arg (earlier ones are middleware).
+        const parts = args.split(',').map((s) => s.trim()).filter(Boolean);
+        const last = parts[parts.length - 1];
+        const handlerName = last ? extractTailIdent(last) : null;
+        if (handlerName) {
+          references.push({
+            fromNodeId: routeNode.id,
+            referenceName: handlerName,
+            referenceKind: 'references',
+            line,
+            column: 0,
+            filePath,
+            language: lang,
+          });
+        }
       }
     }
     return { nodes, references };
diff --git a/src/resolution/frameworks/fabric.ts b/src/resolution/frameworks/fabric.ts
new file mode 100644
index 000000000..308feca68
--- /dev/null
+++ b/src/resolution/frameworks/fabric.ts
@@ -0,0 +1,411 @@
+/**
+ * React Native Fabric / Codegen view components — Phase 6 of the
+ * mixed-iOS/RN bridging effort.
+ *
+ * In the new RN architecture, JS-visible view components are declared via
+ * Codegen TS spec files of the shape:
+ *
+ *   // src/fabric/MyComponentNativeComponent.ts
+ *   import { codegenNativeComponent } from 'react-native';
+ *   import type { ViewProps, CodegenTypes as CT } from 'react-native';
+ *
+ *   export interface NativeProps extends ViewProps {
+ *     color?: ColorValue;
+ *     onTap?: CT.DirectEventHandler<TapEvent>;
+ *   }
+ *
+ *   export default codegenNativeComponent<NativeProps>('MyComponent');
+ *
+ * Codegen then generates a native ComponentDescriptor that wires the JS
+ * component name to a native implementation class — by RN convention,
+ * one of `MyComponent`, `MyComponentView`, `MyComponentComponentView`,
+ * `MyComponentManager`, `MyComponentViewManager`. The actual implementation
+ * lives in ObjC++ (.mm) on iOS or Kotlin/Java on Android.
+ *
+ * Without bridging, JSX `<MyComponent color="red"/>` in a consumer app has
+ * nothing in the graph to land on — the JS-visible name `MyComponent` isn't
+ * a node anywhere (only `MyComponentView` is, in the .mm), and the JSX
+ * synthesizer matches strictly by name.
+ *
+ * What this extractor does:
+ *   1. Parse the spec file's `codegenNativeComponent<Props>('Name', ...)`
+ *      literal — emit a `component` node named `Name`, attributed to the
+ *      spec file.
+ *   2. Parse the `NativeProps` interface and emit one `property` node per
+ *      prop, attributed to the spec file. Props like `onTap` /
+ *      `onFinishTransitioning` are JS-callable event-handler bindings;
+ *      surfacing them as nodes lets the agent discover the JS surface of
+ *      the component.
+ *
+ * A companion synthesizer (`fabricNativeImplEdges` in
+ * callback-synthesizer.ts) links the emitted component node to its
+ * native implementation class via the convention-based name+suffix
+ * lookup — that produces the cross-language hop the JSX synthesizer's
+ * `<MyComponent>` edges naturally chain through.
+ */
+import type { Node } from '../../types';
+import {
+  FrameworkExtractionResult,
+  FrameworkResolver,
+} from '../types';
+
+const CODEGEN_DECL_RE =
+  /codegenNativeComponent\s*(?:<[^>]+>)?\s*\(\s*['"]([A-Za-z_][A-Za-z0-9_]*)['"]/g;
+
+/**
+ * Legacy Paper view manager macros — older RN libs (still very common,
+ * especially small libs that haven't migrated to Codegen) declare a
+ * ViewManager class and expose props via these macros. Both shapes:
+ *
+ *   RCT_EXPORT_VIEW_PROPERTY(values, NSArray)
+ *   RCT_EXPORT_VIEW_PROPERTY(onChange, RCTBubblingEventBlock)
+ *   RCT_CUSTOM_VIEW_PROPERTY(text, NSString, RNCMyView) { … }
+ *   RCT_REMAP_VIEW_PROPERTY(jsName, nativeKeyPath, NSString)
+ *
+ * Capture the FIRST argument — that's the JS-visible prop name.
+ */
+const RCT_VIEW_PROP_RE =
+  /\bRCT_(?:EXPORT|CUSTOM|REMAP)_VIEW_PROPERTY\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)/g;
+
+/**
+ * ObjC `@implementation Foo` extraction. Used to identify the ViewManager
+ * class so we can derive a JS-visible component name (strip the `Manager`
+ * suffix and a leading `RCT` prefix, both standard conventions).
+ */
+const OBJC_IMPL_RE = /@implementation\s+([A-Za-z_][A-Za-z0-9_]*)/;
+
+/**
+ * Derive the JS-visible component name from a native ViewManager class.
+ * Strip a trailing `Manager` (and optionally `ViewManager`) — RN's view
+ * registry maps `XXXManager` ↔ JS `<XXX/>` by this convention. The
+ * leading `RCT` prefix is also stripped (matches what
+ * `defaultObjcModuleName` does for RN's legacy bridge modules).
+ */
+function deriveComponentNameFromManager(className: string): string {
+  let name = className.startsWith('RCT') ? className.slice(3) : className;
+  // Trim ViewManager > Manager > View, in order.
+  if (name.endsWith('ViewManager')) name = name.slice(0, -'ViewManager'.length);
+  else if (name.endsWith('Manager')) name = name.slice(0, -'Manager'.length);
+  return name;
+}
+
+/**
+ * Cheap source-level detector — must contain `codegenNativeComponent` to
+ * be worth parsing. The presence of that import is the canonical Fabric
+ * spec signal.
+ */
+function isFabricSpec(source: string): boolean {
+  return source.includes('codegenNativeComponent');
+}
+
+/**
+ * Pull the `NativeProps` interface body out of a Fabric spec source.
+ * Returns `null` when the interface isn't declared in the expected shape.
+ */
+function findNativePropsBody(source: string): string | null {
+  // Permissive: `export interface NativeProps [extends X, Y] { … }`.
+  const m = source.match(/export\s+interface\s+NativeProps\b[^{]*\{([\s\S]*?)\n\}/);
+  return m?.[1] ?? null;
+}
+
+/**
+ * Parse the NativeProps interface body and return prop names.
+ * Each prop is `name?: Type;` or `name: Type;` on its own line.
+ * We don't care about types — just the JS-visible name.
+ */
+function extractPropNames(body: string): string[] {
+  const props: string[] = [];
+  // Anchor to start-of-line (after optional whitespace), then capture an
+  // identifier, then optional `?`, then `:`. Skip lines that look like
+  // method declarations (`name(`) — those are TurboModule spec methods,
+  // not view props.
+  const regex = /^\s*([A-Za-z_][A-Za-z0-9_]*)\??\s*:/gm;
+  let m: RegExpExecArray | null;
+  while ((m = regex.exec(body)) !== null) {
+    const name = m[1]!;
+    // Exclude any line that immediately turns into a function-shape (e.g.
+    // `onTap?: () => void` is fine — it's a prop, not a method body —
+    // but a literal `name(arg: T): R` is a method declaration).
+    const after = body.slice(m.index + m[0].length, m.index + m[0].length + 80);
+    if (/^\s*\(/.test(after)) continue; // method-shape, skip
+    props.push(name);
+  }
+  return props;
+}
+
+/**
+ * Extract legacy Paper view-manager declarations from a .m/.mm file.
+ * Emits a `component` node named after the JS-visible name (derived from
+ * the @implementation class) plus a `property` node per
+ * `RCT_EXPORT_VIEW_PROPERTY(name, ...)` macro.
+ *
+ * Returns `[]` if the file doesn't look like a ViewManager (no
+ * RCT_EXPORT_VIEW_PROPERTY macros).
+ */
+function extractLegacyViewManagerNodes(filePath: string, source: string): Node[] {
+  // Cheap gate: no view-property macros at all → not a view manager.
+  if (!source.includes('RCT_EXPORT_VIEW_PROPERTY') &&
+      !source.includes('RCT_CUSTOM_VIEW_PROPERTY') &&
+      !source.includes('RCT_REMAP_VIEW_PROPERTY')) {
+    return [];
+  }
+  const implMatch = source.match(OBJC_IMPL_RE);
+  if (!implMatch || !implMatch[1]) return [];
+  const className = implMatch[1];
+  // Only process actual ViewManagers — classes ending in Manager or
+  // (legacy) ViewManager. Classes with view-property macros that don't
+  // follow the naming convention are unusual; skip to keep precision.
+  if (!className.endsWith('Manager') && !className.endsWith('ViewManager')) return [];
+  const componentName = deriveComponentNameFromManager(className);
+  if (!componentName) return [];
+
+  const now = Date.now();
+  const nodes: Node[] = [];
+
+  // Component node — same shape as Codegen Fabric's, so the
+  // fabricNativeImplEdges synthesizer linking component → native class
+  // works for legacy too. The native class IS the manager itself in this
+  // case; the convention-based suffix lookup in the synthesizer
+  // (`Manager`, `ViewManager`) will find it.
+  const before = source.slice(0, implMatch.index ?? 0);
+  const startLine = before.split('\n').length;
+  nodes.push({
+    id: `fabric-component:${filePath}:${componentName}:${startLine}`,
+    kind: 'component',
+    name: componentName,
+    qualifiedName: `${filePath}::${componentName}`,
+    filePath,
+    language: 'objc',
+    startLine,
+    endLine: startLine,
+    startColumn: 0,
+    endColumn: componentName.length,
+    docstring: `Legacy Paper ViewManager component '${componentName}' (from @implementation ${className})`,
+    signature: `RCT_EXPORT_MODULE() // ViewManager: ${className}`,
+    isExported: true,
+    updatedAt: now,
+  });
+
+  // Property nodes per RCT_EXPORT_VIEW_PROPERTY macro.
+  const seen = new Set<string>();
+  RCT_VIEW_PROP_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = RCT_VIEW_PROP_RE.exec(source)) !== null) {
+    const propName = m[1]!;
+    if (seen.has(propName)) continue;
+    seen.add(propName);
+    const propBefore = source.slice(0, m.index);
+    const propLine = propBefore.split('\n').length;
+    nodes.push({
+      id: `fabric-prop:${filePath}:${propName}:${propLine}`,
+      kind: 'property',
+      name: propName,
+      qualifiedName: `${filePath}::${componentName}.${propName}`,
+      filePath,
+      language: 'objc',
+      startLine: propLine,
+      endLine: propLine,
+      startColumn: 0,
+      endColumn: propName.length,
+      docstring: `Legacy Paper view prop '${propName}' on ${componentName}`,
+      isExported: true,
+      updatedAt: now,
+    });
+  }
+  return nodes;
+}
+
+/**
+ * Java/Kotlin `@ReactProp("name")` extraction. The annotation precedes a
+ * setter method on a class that extends `ViewManager` /
+ * `SimpleViewManager` (or in Kotlin, `:` syntax).
+ *
+ * Returns `[]` if no @ReactProp annotations are found.
+ */
+function extractJvmViewManagerNodes(filePath: string, source: string): Node[] {
+  if (!source.includes('@ReactProp')) return [];
+
+  // Class name — looking for `class FooManager [extends ViewManager...]`
+  // (Java) or `class FooManager : ViewManager...` (Kotlin). Either gates
+  // us into a ViewManager file; non-Manager classes with @ReactProp are
+  // unusual.
+  const classMatch = source.match(/\bclass\s+([A-Za-z_][A-Za-z0-9_]*)\b/);
+  if (!classMatch || !classMatch[1]) return [];
+  const className = classMatch[1];
+  if (!className.endsWith('Manager') && !className.endsWith('ViewManager')) return [];
+  const componentName = deriveComponentNameFromManager(className);
+  if (!componentName) return [];
+
+  const language: 'java' | 'kotlin' = filePath.endsWith('.kt') ? 'kotlin' : 'java';
+  const now = Date.now();
+  const nodes: Node[] = [];
+
+  const classBefore = source.slice(0, classMatch.index ?? 0);
+  const startLine = classBefore.split('\n').length;
+  nodes.push({
+    id: `fabric-component:${filePath}:${componentName}:${startLine}`,
+    kind: 'component',
+    name: componentName,
+    qualifiedName: `${filePath}::${componentName}`,
+    filePath,
+    language,
+    startLine,
+    endLine: startLine,
+    startColumn: 0,
+    endColumn: componentName.length,
+    docstring: `Android view-manager component '${componentName}' (from class ${className})`,
+    signature: `class ${className} : ViewManager`,
+    isExported: true,
+    updatedAt: now,
+  });
+
+  // @ReactProp("name") followed (after optional modifiers / args) by a
+  // setter declaration. The annotation argument is the JS-visible prop
+  // name. Permissive about the rest — we only need the literal.
+  const REACT_PROP_RE = /@ReactProp\s*\(\s*(?:name\s*=\s*)?"([^"]+)"/g;
+  const seen = new Set<string>();
+  let m: RegExpExecArray | null;
+  while ((m = REACT_PROP_RE.exec(source)) !== null) {
+    const propName = m[1]!;
+    if (seen.has(propName)) continue;
+    seen.add(propName);
+    const propBefore = source.slice(0, m.index);
+    const propLine = propBefore.split('\n').length;
+    nodes.push({
+      id: `fabric-prop:${filePath}:${propName}:${propLine}`,
+      kind: 'property',
+      name: propName,
+      qualifiedName: `${filePath}::${componentName}.${propName}`,
+      filePath,
+      language,
+      startLine: propLine,
+      endLine: propLine,
+      startColumn: 0,
+      endColumn: propName.length,
+      docstring: `Android @ReactProp prop '${propName}' on ${componentName}`,
+      isExported: true,
+      updatedAt: now,
+    });
+  }
+  return nodes;
+}
+
+function extractFabricNodes(filePath: string, source: string): Node[] {
+  if (!isFabricSpec(source)) return [];
+
+  const now = Date.now();
+  const nodes: Node[] = [];
+
+  CODEGEN_DECL_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = CODEGEN_DECL_RE.exec(source)) !== null) {
+    const componentName = m[1]!;
+    const before = source.slice(0, m.index);
+    const startLine = before.split('\n').length;
+    const startColumn = before.length - before.lastIndexOf('\n') - 1;
+
+    // The component itself — kind: 'component' so the existing
+    // reactJsxChildEdges synthesizer matches `<MyComponent>` JSX tags to
+    // it (its name+kind filter is the gate).
+    const componentId = `fabric-component:${filePath}:${componentName}:${startLine}`;
+    nodes.push({
+      id: componentId,
+      kind: 'component',
+      name: componentName,
+      qualifiedName: `${filePath}::${componentName}`,
+      filePath,
+      // The spec file is .ts or .tsx; use the file's apparent language
+      // by extension. Trim to a known Language value.
+      language: filePath.endsWith('.tsx') ? 'tsx' : 'typescript',
+      startLine,
+      endLine: startLine,
+      startColumn,
+      endColumn: startColumn + 'codegenNativeComponent'.length,
+      docstring: `Fabric/Codegen native component '${componentName}'`,
+      signature: `codegenNativeComponent<NativeProps>('${componentName}')`,
+      isExported: true,
+      updatedAt: now,
+    });
+  }
+
+  // Props from the NativeProps interface. These are not "method" semantic
+  // — they're JS-visible bindings the consumer sets via JSX attributes —
+  // so use `property` kind. (The JSX synthesizer doesn't currently
+  // produce per-attribute edges, but surfacing the prop names as nodes
+  // lets `codegraph_search('onFinishTransitioning')` discover them.)
+  const body = findNativePropsBody(source);
+  if (body) {
+    const props = extractPropNames(body);
+    for (const propName of props) {
+      const propBefore = source.indexOf(propName, source.indexOf(body));
+      const propLine =
+        propBefore >= 0 ? source.slice(0, propBefore).split('\n').length : 1;
+      nodes.push({
+        id: `fabric-prop:${filePath}:${propName}:${propLine}`,
+        kind: 'property',
+        name: propName,
+        qualifiedName: `${filePath}::NativeProps.${propName}`,
+        filePath,
+        language: filePath.endsWith('.tsx') ? 'tsx' : 'typescript',
+        startLine: propLine,
+        endLine: propLine,
+        startColumn: 0,
+        endColumn: propName.length,
+        docstring: `Fabric NativeProps prop '${propName}'`,
+        isExported: true,
+        updatedAt: now,
+      });
+    }
+  }
+
+  return nodes;
+}
+
+export const fabricViewResolver: FrameworkResolver = {
+  name: 'fabric-view',
+  languages: ['typescript', 'tsx', 'objc', 'java', 'kotlin'],
+
+  detect(context) {
+    // Root package.json is the common case. The indexer only tracks
+    // SOURCE files in getAllFiles(), so package.jsons in subpackages
+    // aren't enumerable that way — we have to probe them explicitly via
+    // listDirectories() for monorepos.
+    const checkPkg = (relativePath: string) => {
+      const pkg = context.readFile(relativePath);
+      return pkg ? /["']react-native["']\s*:/.test(pkg) : false;
+    };
+    if (checkPkg('package.json')) return true;
+    // Monorepo escape hatch — react-native-skia and similar workspace
+    // repos have the RN dep only in `packages/<sub>/package.json`. Walk
+    // the common workspace roots one level deep.
+    const list = context.listDirectories;
+    if (!list) return false;
+    for (const root of ['packages', 'apps', 'modules', 'libraries']) {
+      for (const sub of list(root) ?? []) {
+        if (checkPkg(`${root}/${sub}/package.json`)) return true;
+      }
+    }
+    return false;
+  },
+
+  extract(filePath, source): FrameworkExtractionResult {
+    // Pick the right extractor by file language. The framework registry
+    // already filters by `languages` so we only see relevant files.
+    let nodes: Node[] = [];
+    if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) {
+      nodes = extractFabricNodes(filePath, source);
+    } else if (filePath.endsWith('.m') || filePath.endsWith('.mm')) {
+      nodes = extractLegacyViewManagerNodes(filePath, source);
+    } else if (filePath.endsWith('.java') || filePath.endsWith('.kt')) {
+      nodes = extractJvmViewManagerNodes(filePath, source);
+    }
+    return { nodes, references: [] };
+  },
+
+  resolve() {
+    // The companion synthesizer (`fabricNativeImplEdges`) handles
+    // cross-language edges; standard name resolution handles
+    // <MyComponent> → component-node via the JSX synthesizer.
+    return null;
+  },
+};
diff --git a/src/resolution/frameworks/go.ts b/src/resolution/frameworks/go.ts
index 04f697375..b09201946 100644
--- a/src/resolution/frameworks/go.ts
+++ b/src/resolution/frameworks/go.ts
@@ -87,9 +87,12 @@ export const goResolver: FrameworkResolver = {
     const now = Date.now();
     const safe = stripCommentsForRegex(content, 'go');
 
-    // (router|r|mux|app).METHOD("/path", handler)
-    // Handles Gin (GET/POST/...), Chi (Get/Post/...), net/http (HandleFunc/Handle).
-    const routeRegex = /\b(?:router|r|mux|app|e)\.(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD|Get|Post|Put|Patch|Delete|Handle|HandleFunc)\s*\(\s*"([^"]+)"\s*,\s*([^)]+)\)/g;
+    // <anyVar>.METHOD("/path", handler) — Gin (GET/POST/...), Chi (Get/Post/...),
+    // net/http (HandleFunc/Handle). The receiver is ANY identifier, not just
+    // router|r|mux|app|e: real apps route on GROUP vars (`v1.GET`, `PublicGroup.GET`,
+    // `userRouter.POST`), which the fixed name list missed (gin-vue-admin: 4 routes
+    // for 625 files). The verb + string-path + handler-arg gates keep it route-specific.
+    const routeRegex = /\b\w+\.(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD|Get|Post|Put|Patch|Delete|Handle|HandleFunc)\s*\(\s*"([^"]+)"\s*,\s*([^)]+)\)/g;
     let match: RegExpExecArray | null;
     while ((match = routeRegex.exec(safe)) !== null) {
       const [, rawMethod, routePath, handlerExpr] = match;
diff --git a/src/resolution/frameworks/index.ts b/src/resolution/frameworks/index.ts
index 188b5e48a..4fc3c3a5b 100644
--- a/src/resolution/frameworks/index.ts
+++ b/src/resolution/frameworks/index.ts
@@ -6,19 +6,26 @@
 
 import { FrameworkResolver, ResolutionContext } from '../types';
 import type { Language } from '../../types';
+import { drupalResolver } from './drupal';
 import { laravelResolver } from './laravel';
 import { expressResolver } from './express';
 import { nestjsResolver } from './nestjs';
 import { reactResolver } from './react';
 import { svelteResolver } from './svelte';
 import { vueResolver } from './vue';
+import { astroResolver } from './astro';
 import { djangoResolver, flaskResolver, fastapiResolver } from './python';
 import { railsResolver } from './ruby';
 import { springResolver } from './java';
+import { playResolver } from './play';
 import { goResolver } from './go';
 import { rustResolver } from './rust';
 import { aspnetResolver } from './csharp';
 import { swiftUIResolver, uikitResolver, vaporResolver } from './swift';
+import { swiftObjcBridgeResolver } from './swift-objc';
+import { reactNativeBridgeResolver } from './react-native';
+import { expoModulesResolver } from './expo-modules';
+import { fabricViewResolver } from './fabric';
 
 /**
  * All registered framework resolvers
@@ -26,12 +33,14 @@ import { swiftUIResolver, uikitResolver, vaporResolver } from './swift';
 const FRAMEWORK_RESOLVERS: FrameworkResolver[] = [
   // PHP
   laravelResolver,
+  drupalResolver,
   // JavaScript/TypeScript
   expressResolver,
   nestjsResolver,
   reactResolver,
   svelteResolver,
   vueResolver,
+  astroResolver,
   // Python
   djangoResolver,
   flaskResolver,
@@ -40,6 +49,7 @@ const FRAMEWORK_RESOLVERS: FrameworkResolver[] = [
   railsResolver,
   // Java
   springResolver,
+  playResolver,
   // Go
   goResolver,
   // Rust
@@ -50,6 +60,14 @@ const FRAMEWORK_RESOLVERS: FrameworkResolver[] = [
   swiftUIResolver,
   uikitResolver,
   vaporResolver,
+  // Swift ↔ Objective-C cross-language bridging (mixed iOS apps)
+  swiftObjcBridgeResolver,
+  // React Native JS ↔ native bridge (legacy + TurboModules)
+  reactNativeBridgeResolver,
+  // Expo Modules — Function/AsyncFunction/Property DSL on Swift/Kotlin
+  expoModulesResolver,
+  // React Native Fabric / Codegen view components — TS spec → component nodes
+  fabricViewResolver,
 ];
 
 /**
@@ -105,16 +123,23 @@ export function registerFrameworkResolver(resolver: FrameworkResolver): void {
 }
 
 // Re-export framework resolvers
+export { drupalResolver } from './drupal';
 export { laravelResolver, FACADE_MAPPINGS } from './laravel';
 export { expressResolver } from './express';
 export { nestjsResolver } from './nestjs';
 export { reactResolver } from './react';
 export { svelteResolver } from './svelte';
 export { vueResolver } from './vue';
+export { astroResolver } from './astro';
 export { djangoResolver, flaskResolver, fastapiResolver } from './python';
 export { railsResolver } from './ruby';
 export { springResolver } from './java';
+export { playResolver } from './play';
 export { goResolver } from './go';
 export { rustResolver } from './rust';
 export { aspnetResolver } from './csharp';
 export { swiftUIResolver, uikitResolver, vaporResolver } from './swift';
+export { swiftObjcBridgeResolver } from './swift-objc';
+export { reactNativeBridgeResolver } from './react-native';
+export { expoModulesResolver } from './expo-modules';
+export { fabricViewResolver } from './fabric';
diff --git a/src/resolution/frameworks/java.ts b/src/resolution/frameworks/java.ts
index 871816b8f..157f4e409 100644
--- a/src/resolution/frameworks/java.ts
+++ b/src/resolution/frameworks/java.ts
@@ -10,7 +10,15 @@ import { stripCommentsForRegex } from '../strip-comments';
 
 export const springResolver: FrameworkResolver = {
   name: 'spring',
-  languages: ['java'],
+  languages: ['java', 'kotlin', 'yaml', 'properties'],
+
+  claimsReference(name: string): boolean {
+    // `@ConfigurationProperties(prefix="app.cache")` emits a reference whose
+    // name carries the `:prefix` sentinel — there's no declared symbol with
+    // that exact spelling, so the resolver's name-existence pre-filter would
+    // drop it. Opt those through.
+    return name.endsWith(':prefix');
+  },
 
   detect(context: ResolutionContext): boolean {
     // Check for pom.xml with Spring
@@ -50,6 +58,66 @@ export const springResolver: FrameworkResolver = {
   },
 
   resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null {
+    // Spring config-key references — `@Value("${key}")` (single leaf) and
+    // `@ConfigurationProperties(prefix="X")` (entire subtree, marked with the
+    // `:prefix` suffix in extractSpringValueBindings). Lookup goes through
+    // Spring's relaxed binding (kebab/camel/snake → canonical lowercase).
+    if (ref.referenceName.endsWith(':prefix')) {
+      const prefix = ref.referenceName.slice(0, -':prefix'.length);
+      const canonPrefix = canonicalConfigKey(prefix);
+      // Prefer an exact prefix match (one node = the prefix subtree). Without
+      // node-level subtree representation we map to the closest matching key.
+      const candidates = context.getNodesByKind('constant').filter(
+        (n) => (n.language === 'yaml' || n.language === 'properties')
+          && canonicalConfigKey(n.qualifiedName).startsWith(canonPrefix),
+      );
+      if (candidates.length === 0) return null;
+      // Pick the SHORTEST canonical name — it's the closest binding point
+      // (`app.cache` over `app.cache.name.user-token` for prefix=`app.cache`).
+      const best = candidates.reduce((a, b) =>
+        canonicalConfigKey(a.qualifiedName).length <= canonicalConfigKey(b.qualifiedName).length ? a : b,
+      );
+      return { original: ref, targetNodeId: best.id, confidence: 0.85, resolvedBy: 'framework' };
+    }
+    if (ref.referenceName.includes('.') && ref.language !== 'java' && ref.language !== 'kotlin') {
+      // Spring config dotted key — only when the source language is Java/Kotlin
+      // (the bindings come from `@Value`). Skip non-Spring refs that happen to
+      // have dots in them.
+    }
+    if (
+      (ref.language === 'java' || ref.language === 'kotlin') &&
+      ref.referenceName.includes('.') &&
+      !ref.referenceName.includes('::') &&
+      // Exclude method-call style (single-dot, both sides lower-camel). Spring
+      // config keys are typically 3+ segments and contain kebabs/dashes; we
+      // can't filter perfectly but skipping single-dot keeps the lookup tight.
+      ref.referenceName.split('.').length >= 2
+    ) {
+      const canonRef = canonicalConfigKey(ref.referenceName);
+      const candidates = context.getNodesByKind('constant').filter(
+        (n) => n.kind === 'constant'
+          && (n.language === 'yaml' || n.language === 'properties')
+          && canonicalConfigKey(n.qualifiedName) === canonRef,
+      );
+      if (candidates.length === 1) {
+        return { original: ref, targetNodeId: candidates[0]!.id, confidence: 0.9, resolvedBy: 'framework' };
+      }
+      if (candidates.length > 1) {
+        // Multiple profile-specific files (application-dev.yml +
+        // application-prod.yml) can define the same key. Prefer the one with
+        // the shortest profile suffix (the base `application.yml` wins over
+        // profile variants when both exist), then by alphabetical path so the
+        // pick is deterministic across reindexes.
+        const score = (n: Node) => {
+          const base = n.filePath.split('/').pop() ?? '';
+          const isBase = /^(application|bootstrap)\.(yml|yaml|properties)$/i.test(base);
+          return (isBase ? 0 : 1) * 1000 + base.length;
+        };
+        const best = candidates.reduce((a, b) => (score(a) <= score(b) ? a : b));
+        return { original: ref, targetNodeId: best.id, confidence: 0.75, resolvedBy: 'framework' };
+      }
+    }
+
     // Pattern 1: Service references (dependency injection)
     if (ref.referenceName.endsWith('Service')) {
       const result = resolveByNameAndKind(ref.referenceName, SERVICE_KINDS, SERVICE_DIRS, context);
@@ -119,21 +187,42 @@ export const springResolver: FrameworkResolver = {
   },
 
   extract(filePath, content) {
-    if (!filePath.endsWith('.java')) return { nodes: [], references: [] };
+    // Spring config files (application.yml / application.properties /
+    // bootstrap.yml + per-profile variants) are extracted on the framework
+    // path, not in the language extractor, so the keys become first-class
+    // nodes a `@Value("${k}")` reference can resolve to.
+    if (isSpringConfigFile(filePath)) {
+      return extractSpringConfig(filePath, content);
+    }
+    // Spring Boot is used from both Java and Kotlin (identical @GetMapping etc.
+    // annotations); the difference is method syntax — Kotlin `fun name(...)` vs
+    // Java `public X name(...)` — handled in the method regex below.
+    if (!filePath.endsWith('.java') && !filePath.endsWith('.kt')) return { nodes: [], references: [] };
     const nodes: Node[] = [];
     const references: UnresolvedRef[] = [];
     const now = Date.now();
+    const lang: 'java' | 'kotlin' = filePath.endsWith('.kt') ? 'kotlin' : 'java';
     const safe = stripCommentsForRegex(content, 'java');
 
-    // @GetMapping("/path"), @PostMapping(value = "/path"), @RequestMapping("/path")
-    const mappingRegex = /@(GetMapping|PostMapping|PutMapping|PatchMapping|DeleteMapping|RequestMapping)\s*\(\s*(?:value\s*=\s*|path\s*=\s*)?["']([^"']+)["'][^)]*\)/g;
+    // Class-level @RequestMapping prefix (an @RequestMapping whose tail leads to a
+    // `class`). Joined onto each method's path — and, crucially, NOT treated as a
+    // route itself (the old regex did, creating one bogus class route and missing
+    // every BARE method mapping like `@PostMapping` with the path on the class).
+    let classPrefix = '';
+    const cls = /@RequestMapping\s*\(([^)]*)\)\s*(?:@[\w.]+(?:\([^)]*\))?\s*)*(?:public\s+|final\s+|abstract\s+|open\s+|data\s+|sealed\s+)*class\b/.exec(safe);
+    if (cls) classPrefix = parseMappingPath(cls[1]!);
+
+    const VERB: Record<string, string> = {
+      GetMapping: 'GET', PostMapping: 'POST', PutMapping: 'PUT', PatchMapping: 'PATCH', DeleteMapping: 'DELETE',
+    };
+    // Verb-specific method mappings — always method-level, BARE or with a path.
+    const mappingRegex = /@(GetMapping|PostMapping|PutMapping|PatchMapping|DeleteMapping)\b\s*(\([^)]*\))?/g;
     let match: RegExpExecArray | null;
     while ((match = mappingRegex.exec(safe)) !== null) {
-      const [, mappingName, routePath] = match;
+      const method = VERB[match[1]!]!;
+      const sub = parseMappingPath((match[2] || '').replace(/^\(|\)$/g, ''));
+      const routePath = joinPath(classPrefix, sub);
       const line = safe.slice(0, match.index).split('\n').length;
-      const method =
-        mappingName === 'RequestMapping' ? 'ANY' : mappingName!.replace(/Mapping$/, '').toUpperCase();
-
       const routeNode: Node = {
         id: `route:${filePath}:${line}:${method}:${routePath}`,
         kind: 'route',
@@ -144,31 +233,267 @@ export const springResolver: FrameworkResolver = {
         endLine: line,
         startColumn: 0,
         endColumn: match[0].length,
-        language: 'java',
+        language: lang,
         updatedAt: now,
       };
       nodes.push(routeNode);
 
-      // Look for the next public/private/protected method after the annotation
-      const tail = safe.slice(match.index + match[0].length);
-      const methodMatch = tail.match(/\b(?:public|private|protected)\s+[^;{]*?\s+(\w+)\s*\(/);
+      // Method it decorates: first declared method after (skip stacked annotations;
+      // Java puts the return type before the name). Bounded so we don't grab a far one.
+      const tail = safe.slice(match.index + match[0].length, match.index + match[0].length + 600);
+      const methodMatch = tail.match(/\bfun\s+(\w+)\s*\(|\b(?:public|private|protected)\s+[^;{=]*?\s+(\w+)\s*\(/);
       if (methodMatch) {
         references.push({
           fromNodeId: routeNode.id,
-          referenceName: methodMatch[1]!,
+          referenceName: (methodMatch[1] ?? methodMatch[2])!,
           referenceKind: 'references',
           line,
           column: 0,
           filePath,
-          language: 'java',
+          language: lang,
         });
       }
     }
 
+    // Method-level @RequestMapping (older style: `@RequestMapping(value="/x",
+    // method=RequestMethod.GET)` on a method). The class-level @RequestMapping is
+    // the prefix (handled above) — skip it here so it isn't double-counted.
+    const reqRe = /@RequestMapping\b\s*(\([^)]*\))?/g;
+    while ((match = reqRe.exec(safe)) !== null) {
+      const args = (match[1] || '').replace(/^\(|\)$/g, '');
+      const after = safe.slice(match.index + match[0].length, match.index + match[0].length + 600);
+      if (/^\s*(?:@[\w.]+(?:\([^)]*\))?\s*)*(?:public\s+|final\s+|abstract\s+|open\s+|data\s+|sealed\s+)*class\b/.test(after)) continue; // class-level prefix
+      const methodMatch = after.match(/\bfun\s+(\w+)\s*\(|\b(?:public|private|protected)\s+[^;{=]*?\s+(\w+)\s*\(/);
+      if (!methodMatch) continue;
+      const verbM = args.match(/method\s*=\s*(?:RequestMethod\.)?(\w+)/);
+      const method = verbM ? verbM[1]!.toUpperCase() : 'ANY';
+      const routePath = joinPath(classPrefix, parseMappingPath(args));
+      const line = safe.slice(0, match.index).split('\n').length;
+      const routeNode: Node = {
+        id: `route:${filePath}:${line}:${method}:${routePath}`,
+        kind: 'route',
+        name: `${method} ${routePath}`,
+        qualifiedName: `${filePath}::route:${routePath}`,
+        filePath, startLine: line, endLine: line, startColumn: 0, endColumn: match[0].length, language: lang, updatedAt: now,
+      };
+      nodes.push(routeNode);
+      references.push({
+        fromNodeId: routeNode.id,
+        referenceName: (methodMatch[1] ?? methodMatch[2])!,
+        referenceKind: 'references',
+        line, column: 0, filePath, language: lang,
+      });
+    }
+
+    // @Value("${key}") and @ConfigurationProperties(prefix="...") — bind
+    // Spring config-key references in Java/Kotlin source. The reference target
+    // is the corresponding YAML/properties leaf-key node emitted by
+    // extractSpringConfig; springResolver.resolve looks it up with relaxed
+    // binding (kebab/camel/snake collapse).
+    extractSpringValueBindings(filePath, safe, lang, now, nodes, references);
+
     return { nodes, references };
   },
 };
 
+/** Spring config file patterns: application(-profile)?.{yml,yaml,properties} +
+ * bootstrap variants. Matches the basename, not the path, so a project that
+ * vendors `application.yml` under `src/main/resources` and one under `src/test/
+ * resources` are both picked up. */
+function isSpringConfigFile(filePath: string): boolean {
+  const base = filePath.split('/').pop() ?? '';
+  return /^(application|bootstrap)(-[\w.-]+)?\.(yml|yaml|properties)$/i.test(base);
+}
+
+/**
+ * Parse a Spring config file (YAML or .properties) and emit one `constant`
+ * node per LEAF key, with `qualifiedName` = the dotted path. Leaf keys are
+ * what `@Value("${k}")` references hit; intermediate keys aren't bound by
+ * Spring's `@Value` (a `@ConfigurationProperties` class binds a SUBTREE, and
+ * those references are resolved at lookup time by prefix-suffix matching).
+ */
+function extractSpringConfig(
+  filePath: string,
+  content: string,
+): { nodes: Node[]; references: UnresolvedRef[] } {
+  const nodes: Node[] = [];
+  const isProperties = /\.properties$/i.test(filePath);
+  const lang = isProperties ? 'properties' : 'yaml';
+  const now = Date.now();
+
+  const emitLeaf = (dottedKey: string, line: number, valueText: string) => {
+    if (!dottedKey) return;
+    nodes.push({
+      id: `spring-config:${filePath}:${line}:${dottedKey}`,
+      kind: 'constant',
+      name: dottedKey.split('.').pop() ?? dottedKey,
+      qualifiedName: dottedKey,
+      filePath,
+      startLine: line,
+      endLine: line,
+      startColumn: 0,
+      endColumn: valueText.length,
+      language: lang,
+      signature: dottedKey,
+      // SECURITY (#383): store the KEY only, never the value. Config files
+      // routinely hold secrets (DB passwords, API keys, JDBC URLs with embedded
+      // credentials), and surfacing the value here pushes it into agent context
+      // unbidden (it lands in codegraph_node/explore output via the docstring).
+      // The key is all `@Value`/`@ConfigurationProperties` resolution needs; an
+      // agent that genuinely needs a value can read the file directly.
+      updatedAt: now,
+    });
+  };
+
+  if (isProperties) {
+    // Properties format: `k1.k2.k3 = value` (or `:` separator, or no value).
+    // Lines starting with `#`/`!` are comments. Backslash continuations are
+    // valid but rare; we don't try to join them (a continued value is still
+    // a value of the same key).
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      const raw = lines[i] ?? '';
+      const trimmed = raw.trim();
+      if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('!')) continue;
+      const sep = (() => {
+        for (let j = 0; j < raw.length; j++) {
+          const ch = raw[j];
+          if (ch === '=' || ch === ':') return j;
+          if (ch === '\\' && raw[j + 1]) { j++; continue; }
+        }
+        return -1;
+      })();
+      if (sep < 0) continue;
+      const key = raw.slice(0, sep).trim();
+      const val = raw.slice(sep + 1).trim();
+      emitLeaf(key, i + 1, val);
+    }
+    return { nodes, references: [] };
+  }
+
+  // YAML: indent-based. We track a stack of (indent, key) so the dotted path
+  // is built by joining ancestor keys with `.`. A leaf is a line with a value
+  // on the same line (after `:`). List items, flow-style scalars, and `---`
+  // separators are ignored — they don't bind to `@Value` anyway.
+  const stack: Array<{ indent: number; key: string }> = [];
+  const yamlLines = content.split(/\r?\n/);
+  for (let i = 0; i < yamlLines.length; i++) {
+    const raw = yamlLines[i] ?? '';
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.startsWith('#') || trimmed === '---' || trimmed.startsWith('- ')) continue;
+    const indent = raw.length - raw.replace(/^[\t ]+/, '').length;
+    const colonIdx = (() => {
+      let inStr: string | null = null;
+      for (let j = 0; j < raw.length; j++) {
+        const ch = raw[j];
+        if (inStr) { if (ch === inStr && raw[j - 1] !== '\\') inStr = null; continue; }
+        if (ch === '"' || ch === "'") { inStr = ch; continue; }
+        if (ch === ':') return j;
+      }
+      return -1;
+    })();
+    if (colonIdx < 0) continue;
+    const key = raw.slice(indent, colonIdx).trim();
+    if (!key) continue;
+    const after = raw.slice(colonIdx + 1).trim();
+    while (stack.length > 0 && stack[stack.length - 1]!.indent >= indent) stack.pop();
+    const dotted = [...stack.map((s) => s.key), key].join('.');
+    if (after === '' || after.startsWith('#')) {
+      stack.push({ indent, key });
+    } else {
+      // A leaf with an inline value (or a flow-mapping like `{ a: 1 }` — we
+      // emit it as a leaf, not as a subtree; precision is fine for `@Value`).
+      const valStripped = after.replace(/^["']|["']$/g, '');
+      emitLeaf(dotted, i + 1, valStripped);
+    }
+  }
+  return { nodes, references: [] };
+}
+
+/** Append `@Value("${k}")` and `@ConfigurationProperties(prefix=...)`
+ * references discovered in `safe` (comments stripped) into the caller's
+ * `nodes`/`references` arrays. */
+function extractSpringValueBindings(
+  filePath: string,
+  safe: string,
+  lang: 'java' | 'kotlin',
+  now: number,
+  nodes: Node[],
+  references: UnresolvedRef[],
+): void {
+  const valueRe = /@Value\s*\(\s*["']\$\{([^}:]+)(?::[^}]*)?\}["']\s*\)/g;
+  let m: RegExpExecArray | null;
+  while ((m = valueRe.exec(safe)) !== null) {
+    const key = m[1]!.trim();
+    if (!key) continue;
+    const line = safe.slice(0, m.index).split('\n').length;
+    const bindNode: Node = {
+      id: `spring-value:${filePath}:${line}:${key}`,
+      kind: 'constant',
+      name: key,
+      qualifiedName: `${filePath}::@Value:${key}`,
+      filePath,
+      startLine: line,
+      endLine: line,
+      startColumn: 0,
+      endColumn: m[0].length,
+      language: lang,
+      signature: `@Value("${key}")`,
+      updatedAt: now,
+    };
+    nodes.push(bindNode);
+    references.push({
+      fromNodeId: bindNode.id,
+      referenceName: key,
+      referenceKind: 'references',
+      line,
+      column: 0,
+      filePath,
+      language: lang,
+    });
+  }
+
+  const cpRe = /@ConfigurationProperties\s*\(\s*(?:prefix\s*=\s*)?["']([^"']+)["']/g;
+  while ((m = cpRe.exec(safe)) !== null) {
+    const prefix = m[1]!.trim();
+    if (!prefix) continue;
+    const line = safe.slice(0, m.index).split('\n').length;
+    const bindNode: Node = {
+      id: `spring-cp:${filePath}:${line}:${prefix}`,
+      kind: 'constant',
+      name: prefix,
+      qualifiedName: `${filePath}::@ConfigurationProperties:${prefix}`,
+      filePath,
+      startLine: line,
+      endLine: line,
+      startColumn: 0,
+      endColumn: m[0].length,
+      language: lang,
+      signature: `@ConfigurationProperties("${prefix}")`,
+      updatedAt: now,
+    };
+    nodes.push(bindNode);
+    references.push({
+      fromNodeId: bindNode.id,
+      // Mark the reference with a `:prefix` suffix so springResolver.resolve
+      // knows to expand it into the SUBTREE rather than a single key.
+      referenceName: `${prefix}:prefix`,
+      referenceKind: 'references',
+      line,
+      column: 0,
+      filePath,
+      language: lang,
+    });
+  }
+}
+
+/** Spring's relaxed binding (`cache-list` ↔ `cacheList` ↔ `cache_list` ↔
+ * `CACHE_LIST`) collapses on lowercase + dash/underscore removal. We compare
+ * candidate keys to a reference in this canonical form. */
+function canonicalConfigKey(key: string): string {
+  return key.toLowerCase().replace(/[-_]/g, '');
+}
+
 // Directory patterns
 const SERVICE_DIRS = ['/service/', '/services/'];
 const REPO_DIRS = ['/repository/', '/repositories/'];
@@ -179,6 +504,18 @@ const COMPONENT_DIRS = ['/component/', '/components/', '/config/'];
 const CLASS_KINDS = new Set(['class']);
 const SERVICE_KINDS = new Set(['class', 'interface']);
 
+/** Path string from a mapping's args (`"/x"`, `value = "/x"`, `path = "/x"`); '' if bare. */
+function parseMappingPath(args: string): string {
+  const m = args.match(/["']([^"']*)["']/);
+  return m ? m[1]! : '';
+}
+
+/** Join a class-level prefix and a method sub-path into one normalized `/path`. */
+function joinPath(prefix: string, sub: string): string {
+  const parts = [prefix, sub].map((p) => p.replace(/^\/+|\/+$/g, '')).filter(Boolean);
+  return '/' + parts.join('/');
+}
+
 /**
  * Resolve a symbol by name using indexed queries instead of scanning all files.
  */
diff --git a/src/resolution/frameworks/laravel.ts b/src/resolution/frameworks/laravel.ts
index e3940b079..1356adf5d 100644
--- a/src/resolution/frameworks/laravel.ts
+++ b/src/resolution/frameworks/laravel.ts
@@ -44,6 +44,13 @@ export const laravelResolver: FrameworkResolver = {
     return context.fileExists('artisan') || context.fileExists('app/Http/Kernel.php');
   },
 
+  // `Controller@method` route refs name no declared symbol, so resolveOne's
+  // pre-filter would drop them before resolve() runs (Pattern 4). Claim them —
+  // same hook the django ORM / Rails routing work needed.
+  claimsReference(name: string): boolean {
+    return /^[A-Za-z_][A-Za-z0-9_]*Controller@\w+$/.test(name);
+  },
+
   resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null {
     // Pattern 1: Model::method() - Eloquent static calls
     const modelMatch = ref.referenceName.match(/^([A-Z][a-zA-Z]+)::(\w+)$/);
@@ -185,18 +192,21 @@ export const laravelResolver: FrameworkResolver = {
  */
 function extractLaravelHandler(expr: string): string | null {
   const trimmed = expr.trim();
+  const short = (s: string) => s.split('\\').pop()!; // strip namespace
 
-  // [Class::class, 'method'] — grab the string literal
-  const tupleMatch = trimmed.match(/^\[\s*[^,]+,\s*['"]([^'"]+)['"]\s*\]/);
-  if (tupleMatch) return tupleMatch[1]!;
+  // [Class::class, 'method'] → `Class@method` (PRECISE — keep the controller, so
+  // common action names like `index`/`show` resolve to the RIGHT controller, not
+  // whichever one name-matching happens to pick first).
+  const tupleMatch = trimmed.match(/^\[\s*([A-Za-z_\\][\w\\]*)::class\s*,\s*['"]([^'"]+)['"]\s*\]/);
+  if (tupleMatch) return `${short(tupleMatch[1]!)}@${tupleMatch[2]!}`;
 
-  // 'Controller@method'
+  // 'Controller@method' (possibly namespaced) → `Controller@method`
   const atMatch = trimmed.match(/^['"]([^'"@]+)@([^'"]+)['"]$/);
-  if (atMatch) return atMatch[2]!;
+  if (atMatch) return `${short(atMatch[1]!)}@${atMatch[2]!}`;
 
-  // Controller::class
-  const classMatch = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*)::class/);
-  if (classMatch) return classMatch[1]!;
+  // Class::class (Route::resource controller) → `Class`
+  const classMatch = trimmed.match(/^([A-Za-z_\\][\w\\]*)::class/);
+  if (classMatch) return short(classMatch[1]!);
 
   return null;
 }
diff --git a/src/resolution/frameworks/nestjs.ts b/src/resolution/frameworks/nestjs.ts
index 3a8c1e9ac..2b52b24d5 100644
--- a/src/resolution/frameworks/nestjs.ts
+++ b/src/resolution/frameworks/nestjs.ts
@@ -31,6 +31,12 @@ import {
 } from '../types';
 import { stripCommentsForRegex } from '../strip-comments';
 
+// ---------------------------------------------------------------------------
+// Public surface — see comment at top of file. This file owns four NestJS
+// concerns: HTTP routes, GraphQL ops, microservice handlers, WebSocket
+// handlers, and (in postExtract below) cross-file RouterModule prefixing.
+// ---------------------------------------------------------------------------
+
 type JsLang = 'typescript' | 'javascript';
 
 const HTTP_METHODS = ['Get', 'Post', 'Put', 'Patch', 'Delete', 'Head', 'Options', 'All'];
@@ -185,6 +191,79 @@ export const nestjsResolver: FrameworkResolver = {
 
     return { nodes, references };
   },
+
+  /**
+   * Cross-file finalization for `RouterModule.register([...])`. The per-file
+   * extract() above only sees `@Controller(prefix) + @Get(path)` — it can't
+   * learn about the route prefix supplied by a sibling `app.module.ts` like:
+   *
+   *   RouterModule.register([
+   *     { path: 'admin', module: AdminModule, children: [
+   *       { path: 'users', module: UsersModule } ] } ])
+   *
+   * This pass scans every `*.module.{ts,js}` file, walks the registration
+   * tree to build a `Module → /full/prefix` map, walks each `@Module({
+   * controllers: [...] })` to build a `Controller → Module` map, and rewrites
+   * affected route nodes so `GET /` becomes `GET /admin/users` (and
+   * `@Controller('foo') + @Get(':id')` under that same module becomes
+   * `GET /admin/users/foo/:id`).
+   *
+   * The route node's `id` and `qualifiedName` are deliberately preserved
+   * across the update: `id` because existing route→handler edges reference
+   * it, `qualifiedName` because it still encodes the *original* in-file
+   * `method:path` — which keeps this pass idempotent (a second run recovers
+   * the same input regardless of how many times it has already prefixed).
+   */
+  postExtract(context: ResolutionContext): Node[] {
+    const moduleToPrefix = new Map<string, string>();
+    const controllerToModule = new Map<string, string>();
+
+    for (const filePath of context.getAllFiles()) {
+      if (!/\.module\.(m?[jt]s|cjs)$/.test(filePath)) continue;
+      const content = context.readFile(filePath);
+      if (!content) continue;
+      const safe = stripCommentsForRegex(content, detectLanguage(filePath));
+      collectRouterModuleRegistrations(safe, moduleToPrefix);
+      collectModuleControllers(safe, controllerToModule);
+    }
+
+    const controllerToPrefix = new Map<string, string>();
+    for (const [controller, module] of controllerToModule) {
+      const prefix = moduleToPrefix.get(module);
+      // `''` and `'/'` are no-op prefixes; skip them so we don't run updates
+      // that would set name to the value it already has.
+      if (prefix && prefix !== '' && prefix !== '/') {
+        controllerToPrefix.set(controller, prefix);
+      }
+    }
+
+    if (controllerToPrefix.size === 0) return [];
+
+    const updates: Node[] = [];
+    for (const [controllerName, prefix] of controllerToPrefix) {
+      const classes = context
+        .getNodesByName(controllerName)
+        .filter((n) => n.kind === 'class');
+      for (const cls of classes) {
+        const routes = context
+          .getNodesInFile(cls.filePath)
+          .filter((n) => n.kind === 'route');
+        for (const route of routes) {
+          // Multiple controllers can live in one file (covered by the
+          // existing "attributes methods to the right controller" test);
+          // each route must be associated with the controller whose line
+          // range contains it.
+          if (route.startLine < cls.startLine || route.startLine > cls.endLine) {
+            continue;
+          }
+          const updated = applyModulePrefix(route, prefix);
+          if (updated && updated.name !== route.name) updates.push(updated);
+        }
+      }
+    }
+
+    return updates;
+  },
 };
 
 // ---------------------------------------------------------------------------
@@ -436,3 +515,252 @@ function detectLanguage(filePath: string): JsLang {
   if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) return 'typescript';
   return 'javascript';
 }
+
+// ---------------------------------------------------------------------------
+// RouterModule + @Module walkers (used by postExtract above)
+// ---------------------------------------------------------------------------
+
+/**
+ * Walk every `RouterModule.register([...])` call (and the equivalent
+ * `RouterModule.forRoot([...])` and `forChild([...])` aliases) and populate
+ * `out` with `Module → /full/prefix`. Recursive `children` arrays inherit
+ * their parent's prefix.
+ *
+ * First-write-wins: if the same module appears in two registrations we keep
+ * the first prefix seen rather than overwriting. NestJS itself does the same.
+ */
+function collectRouterModuleRegistrations(safe: string, out: Map<string, string>): void {
+  const re = /\bRouterModule\s*\.\s*(?:register|forRoot|forChild)\s*\(/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(safe)) !== null) {
+    const openIndex = m.index + m[0].length - 1;
+    const parsed = readArgs(safe, openIndex);
+    if (!parsed) continue;
+    const items = parseRoutesArray(parsed.args);
+    walkRoutesTree(items, '', out);
+    re.lastIndex = parsed.end;
+  }
+}
+
+interface RouteItem {
+  path: string;
+  moduleName: string | null;
+  children: RouteItem[];
+}
+
+/**
+ * Parse a `[ {...}, {...} ]` argument list into a list of `RouteItem`s. The
+ * args are expected to be an inline literal — references to a `const routes:
+ * Routes = [...]` declared earlier in the file aren't followed (rare in
+ * practice; the registration is usually inline).
+ */
+function parseRoutesArray(args: string): RouteItem[] {
+  const trimmed = args.trim();
+  if (!trimmed.startsWith('[')) return [];
+  // Strip outer [ ... ] respecting balanced brackets.
+  const close = matchingClose(trimmed, 0);
+  if (close < 0) return [];
+  return parseRouteObjects(trimmed.slice(1, close));
+}
+
+function parseRouteObjects(s: string): RouteItem[] {
+  const items: RouteItem[] = [];
+  for (const obj of splitTopLevelObjects(s)) {
+    const path = parseStringField(obj, 'path');
+    const moduleName = parseIdentField(obj, 'module');
+    const childrenStr = parseArrayField(obj, 'children');
+    const children = childrenStr ? parseRouteObjects(childrenStr) : [];
+    items.push({ path, moduleName, children });
+  }
+  return items;
+}
+
+function walkRoutesTree(
+  items: RouteItem[],
+  parentPrefix: string,
+  out: Map<string, string>
+): void {
+  for (const item of items) {
+    const myPrefix = joinHttpPath(parentPrefix, item.path);
+    if (item.moduleName && !out.has(item.moduleName)) {
+      out.set(item.moduleName, myPrefix);
+    }
+    if (item.children.length > 0) {
+      walkRoutesTree(item.children, myPrefix, out);
+    }
+  }
+}
+
+/**
+ * Walk every `@Module(...)` decorator and populate `out` with
+ * `Controller → enclosingModuleClassName`, based on the decorator's
+ * `controllers: [...]` field and the class declaration that follows the
+ * decorator (skipping stacked decorators and export/default/abstract
+ * modifiers).
+ */
+function collectModuleControllers(safe: string, out: Map<string, string>): void {
+  for (const hit of findDecorators(safe, ['Module'])) {
+    const className = classNameAfter(safe, hit.end);
+    if (!className) continue;
+    for (const controller of parseControllersField(hit.args)) {
+      // First-write-wins, same as RouterModule, so a controller listed in two
+      // modules picks up the one declared earliest in source.
+      if (!out.has(controller)) out.set(controller, className);
+    }
+  }
+}
+
+function parseControllersField(args: string): string[] {
+  const inner = parseArrayField(args, 'controllers');
+  if (inner === null) return [];
+  return inner
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => /^[A-Za-z_$][\w$]*$/.test(s));
+}
+
+/**
+ * Starting just after a class decorator's `)`, return the name of the class
+ * it decorates. Mirrors `methodNameAfter` for methods: skips stacked
+ * decorators and `export`/`default`/`abstract` modifiers.
+ */
+function classNameAfter(safe: string, start: number): string | null {
+  let i = start;
+  const ws = /\s*/y;
+  const decoName = /@[\w.]+/y;
+  const classDecl = /(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/y;
+
+  const eatWs = (): void => {
+    ws.lastIndex = i;
+    if (ws.exec(safe)) i = ws.lastIndex;
+  };
+
+  for (;;) {
+    eatWs();
+    if (safe[i] !== '@') break;
+    decoName.lastIndex = i;
+    if (!decoName.exec(safe)) break;
+    i = decoName.lastIndex;
+    eatWs();
+    if (safe[i] === '(') {
+      const parsed = readArgs(safe, i);
+      if (!parsed) return null;
+      i = parsed.end;
+    }
+  }
+
+  eatWs();
+  classDecl.lastIndex = i;
+  const m = classDecl.exec(safe);
+  return m ? m[1]! : null;
+}
+
+/**
+ * Recompute a route node's `name` by prepending `prefix` to the *original*
+ * in-file path. The original is recovered from `qualifiedName`, which the
+ * per-file extract emits as `${filePath}::${method}:${path}` and which this
+ * pass deliberately never mutates — that's what keeps the update idempotent.
+ */
+function applyModulePrefix(route: Node, prefix: string): Node | null {
+  const sep = '::';
+  const idx = route.qualifiedName.indexOf(sep);
+  if (idx < 0) return null;
+  const tail = route.qualifiedName.slice(idx + sep.length);
+  const colon = tail.indexOf(':');
+  if (colon < 0) return null;
+  const method = tail.slice(0, colon);
+  const original = tail.slice(colon + 1);
+  const newName = `${method} ${joinHttpPath(prefix, original)}`;
+  return { ...route, name: newName, updatedAt: Date.now() };
+}
+
+// ---------------------------------------------------------------------------
+// Small string utilities (object/array literal splitters)
+// ---------------------------------------------------------------------------
+
+/** Return the index of the bracket that closes the one at `open`, or -1. */
+function matchingClose(s: string, open: number): number {
+  const opener = s[open];
+  if (opener !== '[' && opener !== '{' && opener !== '(') return -1;
+  let depth = 0;
+  let inStr: string | null = null;
+  for (let i = open; i < s.length; i++) {
+    const ch = s[i]!;
+    if (inStr) {
+      if (ch === '\\') { i++; continue; }
+      if (ch === inStr) inStr = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') { inStr = ch; continue; }
+    if (ch === '{' || ch === '[' || ch === '(') depth++;
+    else if (ch === '}' || ch === ']' || ch === ')') {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Split `s` into the contents of each top-level object literal. Brackets and
+ * string literals are balanced so nested arrays/objects/strings inside an
+ * object don't cause an early split.
+ */
+function splitTopLevelObjects(s: string): string[] {
+  const out: string[] = [];
+  let depth = 0;
+  let objStart = -1;
+  let inStr: string | null = null;
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i]!;
+    if (inStr) {
+      if (ch === '\\') { i++; continue; }
+      if (ch === inStr) inStr = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') { inStr = ch; continue; }
+    if (depth === 0 && ch === '{') {
+      depth = 1;
+      objStart = i;
+      continue;
+    }
+    if (ch === '{' || ch === '[' || ch === '(') depth++;
+    else if (ch === '}' || ch === ']' || ch === ')') {
+      depth--;
+      if (depth === 0 && objStart >= 0 && ch === '}') {
+        out.push(s.slice(objStart + 1, i));
+        objStart = -1;
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Read a string-valued field — `key: 'value'` — out of one object literal's
+ * body. Returns `''` if not present. The leading character class guards
+ * against matching a field whose name *contains* the target as a suffix.
+ */
+function parseStringField(obj: string, name: string): string {
+  const re = new RegExp(`(?:^|[,{\\s])${name}\\s*:\\s*['"\`]([^'"\`]*)['"\`]`);
+  const m = obj.match(re);
+  return m ? m[1]! : '';
+}
+
+/** Read an identifier-valued field — `key: SomeIdent` — out of one object body. */
+function parseIdentField(obj: string, name: string): string | null {
+  const re = new RegExp(`(?:^|[,{\\s])${name}\\s*:\\s*([A-Za-z_$][\\w$]*)`);
+  const m = obj.match(re);
+  return m ? m[1]! : null;
+}
+
+/** Read an array-valued field — `key: [ ... ]` — as the raw inner text. */
+function parseArrayField(obj: string, name: string): string | null {
+  const re = new RegExp(`(?:^|[,{\\s])${name}\\s*:\\s*\\[`);
+  const m = re.exec(obj);
+  if (!m) return null;
+  const open = m.index + m[0].length - 1;
+  const close = matchingClose(obj, open);
+  if (close < 0) return null;
+  return obj.slice(open + 1, close);
+}
diff --git a/src/resolution/frameworks/play.ts b/src/resolution/frameworks/play.ts
new file mode 100644
index 000000000..bc27baf14
--- /dev/null
+++ b/src/resolution/frameworks/play.ts
@@ -0,0 +1,112 @@
+/**
+ * Play Framework (Scala/Java) resolver.
+ *
+ * Play declares HTTP routes in a dedicated `conf/routes` file (and included
+ * `conf/*.routes`), Rails-style:
+ *
+ *   GET   /computers        controllers.Application.list(p: Int ?= 0)
+ *   POST  /computers        controllers.Application.save
+ *   GET   /assets/*file     controllers.Assets.versioned(path = "/public", file: Asset)
+ *
+ * The file is extensionless, so the file walk only indexes it because
+ * `isPlayRoutesFile` (grammars.ts) opts it in; it's processed through the
+ * no-grammar path and this resolver extracts the routes. Each route references
+ * its handler as `Controller.method` (the package prefix is dropped), resolved
+ * to the action method in the controller class.
+ */
+
+import { Node } from '../../types';
+import { FrameworkResolver, ResolutionContext, ResolvedRef, UnresolvedRef } from '../types';
+import { isPlayRoutesFile } from '../../extraction/grammars';
+
+const ROUTE_LINE = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(\S+)\s+(.+)$/;
+const METHOD_KINDS = new Set(['method', 'function']);
+const CLASS_KINDS = new Set(['class']);
+
+export const playResolver: FrameworkResolver = {
+  name: 'play',
+  // `yaml` so this resolver runs on conf/routes (detectLanguage maps it to yaml);
+  // `scala`/`java` so it's active in Play projects of either language.
+  languages: ['scala', 'java', 'yaml'],
+
+  detect(context: ResolutionContext): boolean {
+    const buildSbt = context.readFile('build.sbt');
+    if (buildSbt && /playframework|"play"|sbt-plugin|PlayScala|PlayJava/i.test(buildSbt)) return true;
+    if (context.fileExists('conf/routes')) return true;
+    if (context.fileExists('conf/application.conf')) return true;
+    return false;
+  },
+
+  // The handler is `Controller.method` (a class-qualified action), which names no
+  // bare declared symbol, so resolveOne's pre-filter could drop it — claim it.
+  claimsReference(name: string): boolean {
+    return /^[A-Za-z_]\w*\.[A-Za-z_]\w*$/.test(name);
+  },
+
+  resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null {
+    const m = ref.referenceName.match(/^([A-Za-z_]\w*)\.([A-Za-z_]\w*)$/);
+    if (!m) return null;
+    const [, className, methodName] = m;
+    const classNodes = context.getNodesByName(className!).filter((n) => CLASS_KINDS.has(n.kind));
+    for (const cls of classNodes) {
+      const method = context
+        .getNodesInFile(cls.filePath)
+        .find((n) => METHOD_KINDS.has(n.kind) && n.name === methodName);
+      if (method) {
+        return { original: ref, targetNodeId: method.id, confidence: 0.9, resolvedBy: 'framework' };
+      }
+    }
+    return null;
+  },
+
+  extract(filePath: string, content: string): { nodes: Node[]; references: UnresolvedRef[] } {
+    if (!isPlayRoutesFile(filePath)) return { nodes: [], references: [] };
+    const nodes: Node[] = [];
+    const references: UnresolvedRef[] = [];
+    const now = Date.now();
+
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]!.trim();
+      // Skip comments and `->` route includes (a sub-router mount, not an action).
+      if (!line || line.startsWith('#') || line.startsWith('->')) continue;
+      const m = line.match(ROUTE_LINE);
+      if (!m) continue;
+      const [, method, routePath, action] = m;
+
+      // action: `controllers.Application.list(p: Int ?= 0)` → drop args, keep the
+      // last `Controller.method` segment (package prefix is irrelevant for lookup).
+      const fqn = action!.split('(')[0]!.trim();
+      const parts = fqn.split('.').filter(Boolean);
+      if (parts.length < 2) continue;
+      const handlerRef = parts.slice(-2).join('.'); // Application.list
+
+      const lineNum = i + 1;
+      const routeNode: Node = {
+        id: `route:${filePath}:${lineNum}:${method}:${routePath}`,
+        kind: 'route',
+        name: `${method} ${routePath}`,
+        qualifiedName: `${filePath}::${method}:${routePath}`,
+        filePath,
+        startLine: lineNum,
+        endLine: lineNum,
+        startColumn: 0,
+        endColumn: 0,
+        language: 'scala',
+        updatedAt: now,
+      };
+      nodes.push(routeNode);
+      references.push({
+        fromNodeId: routeNode.id,
+        referenceName: handlerRef,
+        referenceKind: 'references',
+        line: lineNum,
+        column: 0,
+        filePath,
+        language: 'scala',
+      });
+    }
+
+    return { nodes, references };
+  },
+};
diff --git a/src/resolution/frameworks/python.ts b/src/resolution/frameworks/python.ts
index c0a935be9..492cc53d6 100644
--- a/src/resolution/frameworks/python.ts
+++ b/src/resolution/frameworks/python.ts
@@ -35,9 +35,29 @@ export const djangoResolver: FrameworkResolver = {
       const result = resolveByNameAndKind(ref.referenceName, CLASS_KINDS, FORM_DIRS, context);
       if (result) return { original: ref, targetNodeId: result, confidence: 0.8, resolvedBy: 'framework' };
     }
+    // ORM dynamic dispatch: QuerySet._fetch_all (and siblings) call
+    // `self._iterable_class(self)` — a runtime dispatch to the iterable class
+    // (default ModelIterable) whose __iter__ runs the SQL compiler. Static
+    // parsing can't resolve an attribute-as-callable, so it leaves an unresolved
+    // `_iterable_class` ref and a hole in the QuerySet→compiler chain. Bridge it
+    // to ModelIterable.__iter__ so the flow actually exists in the graph.
+    if (ref.referenceName === '_iterable_class') {
+      const target = resolveModelIterableIter(context);
+      if (target) return { original: ref, targetNodeId: target, confidence: 0.7, resolvedBy: 'framework' };
+    }
     return null;
   },
 
+  // Let two ref shapes past resolveOne's "no possible match" pre-filter so they
+  // reach resolution: the ORM dynamic-dispatch `_iterable_class` (a QuerySet
+  // attribute, not a declared symbol), and a Django `include('app.urls')` module
+  // path — a dotted module name with no symbol/import to match, which resolution
+  // (resolvePythonAbsoluteModule) then maps to its `urls.py` file so the included
+  // URLconf records a dependency on the root urlconf.
+  claimsReference(name) {
+    return name === '_iterable_class' || name.endsWith('.urls');
+  },
+
   extract(filePath, content) {
     if (!filePath.endsWith('.py')) return { nodes: [], references: [] };
 
@@ -86,10 +106,54 @@ export const djangoResolver: FrameworkResolver = {
       }
     }
 
+    // DRF router registration: `router.register(r'articles', ArticleViewSet)` →
+    // route → the ViewSet class (the core CRUD endpoints, which path()/url() miss).
+    // The STRING first arg separates this from `admin.site.register(Model, Admin)`
+    // (whose first arg is a model class, not a string); the View/ViewSet suffix on
+    // the 2nd arg keeps it to DRF viewsets.
+    const routerRegex = /\.register\s*\(\s*r?['"]([^'"]+)['"]\s*,\s*([\w.]+)/g;
+    while ((match = routerRegex.exec(safe)) !== null) {
+      const prefix = match[1]!.replace(/^\^|\/?\$$/g, '');
+      const viewset = match[2]!.split('.').pop()!;
+      if (!/View(Set)?$/.test(viewset)) continue;
+      const line = safe.slice(0, match.index).split('\n').length;
+      const routeNode: Node = {
+        id: `route:${filePath}:${line}:VIEWSET:${prefix}`,
+        kind: 'route',
+        name: `VIEWSET /${prefix}`,
+        qualifiedName: `${filePath}::route:${prefix}`,
+        filePath, startLine: line, endLine: line, startColumn: 0, endColumn: match[0].length,
+        language: 'python', updatedAt: now,
+      };
+      nodes.push(routeNode);
+      references.push({
+        fromNodeId: routeNode.id,
+        referenceName: viewset,
+        referenceKind: 'references',
+        line, column: 0, filePath, language: 'python',
+      });
+    }
+
     return { nodes, references };
   },
 };
 
+/**
+ * Find ModelIterable.__iter__ — the default iterable QuerySet invokes via
+ * `self._iterable_class(self)`. Its __iter__ statically calls the SQL compiler,
+ * so linking the dynamic dispatch here closes the QuerySet→SQL call chain.
+ * (Over-approximates to the default iterable; .values()/.values_list() swap in
+ * other BaseIterable subclasses, but ModelIterable is the canonical path.)
+ */
+function resolveModelIterableIter(context: ResolutionContext): string | null {
+  const cls = context.getNodesByName('ModelIterable').find((n) => n.kind === 'class');
+  if (!cls) return null;
+  const iter = context.getNodesByName('__iter__').find(
+    (n) => n.filePath === cls.filePath && n.startLine >= cls.startLine && n.startLine <= cls.endLine
+  );
+  return iter ? iter.id : null;
+}
+
 /**
  * Parse a Django URL handler expression and return the symbol/module to link.
  * Returns null for shapes we can't confidently link (e.g. lambdas).
@@ -117,13 +181,20 @@ export const flaskResolver: FrameworkResolver = {
   languages: ['python'],
 
   detect(context) {
-    const requirements = context.readFile('requirements.txt');
-    if (requirements && /\bflask\b/i.test(requirements)) return true;
-    const pyproject = context.readFile('pyproject.toml');
-    if (pyproject && /\bflask\b/i.test(pyproject)) return true;
-    for (const file of ['app.py', 'application.py', 'main.py', '__init__.py']) {
-      const content = context.readFile(file);
-      if (content && content.includes('Flask(__name__)')) return true;
+    for (const f of ['requirements.txt', 'pyproject.toml', 'Pipfile', 'setup.py']) {
+      const c = context.readFile(f);
+      if (c && /\bflask\b/i.test(c)) return true;
+    }
+    // Any app entrypoint (root OR subdir, e.g. conduit/app.py) that imports flask
+    // and instantiates Flask(...) — covers Flask(__name__), Flask(__name__.split…),
+    // and the app-factory pattern. Bounded to entrypoint-named files.
+    const entrypoints = context
+      .getAllFiles()
+      .filter((f) => /(?:^|\/)(app|application|main|wsgi|__init__)\.py$/.test(f))
+      .slice(0, 50);
+    for (const f of entrypoints) {
+      const c = context.readFile(f);
+      if (c && /\bFlask\s*\(/.test(c) && /\bimport\s+flask\b|\bfrom\s+flask\b/.test(c)) return true;
     }
     return false;
   },
@@ -138,15 +209,23 @@ export const flaskResolver: FrameworkResolver = {
 
   extract(filePath, content) {
     if (!filePath.endsWith('.py')) return { nodes: [], references: [] };
-    return extractDecoratorRoutes(filePath, stripCommentsForRegex(content, 'python'), {
-      // Flask: @x.route('/path', methods=[...])
-      decoratorRegex: /@(\w+)\.route\s*\(\s*['"]([^'"]+)['"](?:\s*,\s*methods\s*=\s*\[([^\]]+)\])?\s*\)\s*\n\s*(?:async\s+)?def\s+(\w+)/g,
+    const safe = stripCommentsForRegex(content, 'python');
+    const decorator = extractDecoratorRoutes(filePath, safe, {
+      // Flask: @x.route('/path', methods=[...] | (...)) — the handler is the next
+      // `def`, allowing intervening decorators (@login_required) and stacked
+      // @x.route() lines. methods may be a list OR a tuple (methods=('GET',)).
+      decoratorRegex: /@(\w+)\.route\s*\(\s*['"]([^'"]*)['"](?:\s*,\s*methods\s*=\s*[[(]([^\])]+)[\])])?\s*\)/g,
       defaultMethod: 'GET',
       methodFromGroup: 3,
       pathGroup: 2,
-      handlerGroup: 4,
+      findHandler: true,
       language: 'python',
     });
+    const restful = extractFlaskRestful(filePath, safe);
+    return {
+      nodes: [...decorator.nodes, ...restful.nodes],
+      references: [...decorator.references, ...restful.references],
+    };
   },
 };
 
@@ -181,8 +260,9 @@ export const fastapiResolver: FrameworkResolver = {
   extract(filePath, content) {
     if (!filePath.endsWith('.py')) return { nodes: [], references: [] };
     return extractDecoratorRoutes(filePath, stripCommentsForRegex(content, 'python'), {
-      // FastAPI: @x.METHOD('/path') -> handler on the next def line
-      decoratorRegex: /@(\w+)\.(get|post|put|patch|delete|options|head)\s*\(\s*['"]([^'"]+)['"]/g,
+      // FastAPI: @x.METHOD('/path') -> handler on the next def line. Path may be
+      // empty ("") for routes mounted at the router/prefix root.
+      decoratorRegex: /@(\w+)\.(get|post|put|patch|delete|options|head)\s*\(\s*['"]([^'"]*)['"]/g,
       defaultMethod: '',
       methodGroup: 2,
       pathGroup: 3,
@@ -218,7 +298,7 @@ function extractDecoratorRoutes(filePath: string, content: string, opts: Decorat
       if (m) method = m[1]!.toUpperCase();
     }
     const line = content.slice(0, match.index).split('\n').length;
-    const name = method ? `${method} ${routePath}` : routePath!;
+    const name = method ? `${method} ${routePath || '/'}` : (routePath || '/');
     const routeNode: Node = {
       id: `route:${filePath}:${line}:${method}:${routePath}`,
       kind: 'route',
@@ -257,6 +337,52 @@ function extractDecoratorRoutes(filePath: string, content: string, opts: Decorat
   return { nodes, references };
 }
 
+/**
+ * Flask-RESTful: `api.add_resource(ResourceClass, '/path'[, '/path2'])`
+ * (and variants like redash's `add_org_resource`). The ResourceClass holds the
+ * HTTP-verb methods (get/post/…), so the route references the class — its verb
+ * methods resolve as the handlers via the class. Method is ANY (the class
+ * decides which verbs it serves).
+ */
+function extractFlaskRestful(filePath: string, safe: string): FrameworkExtractionResult {
+  const nodes: Node[] = [];
+  const references: UnresolvedRef[] = [];
+  const now = Date.now();
+  const re = /\.add\w*[Rr]esource\s*\(\s*(\w+)\s*,\s*((?:['"][^'"]+['"]\s*,?\s*)+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(safe)) !== null) {
+    const className = m[1]!;
+    const paths = (m[2]!.match(/['"]([^'"]+)['"]/g) || []).map((s) => s.slice(1, -1));
+    const line = safe.slice(0, m.index).split('\n').length;
+    for (const routePath of paths) {
+      const routeNode: Node = {
+        id: `route:${filePath}:${line}:ANY:${routePath}`,
+        kind: 'route',
+        name: `ANY ${routePath}`,
+        qualifiedName: `${filePath}::ANY:${routePath}`,
+        filePath,
+        startLine: line,
+        endLine: line,
+        startColumn: 0,
+        endColumn: 0,
+        language: 'python',
+        updatedAt: now,
+      };
+      nodes.push(routeNode);
+      references.push({
+        fromNodeId: routeNode.id,
+        referenceName: className,
+        referenceKind: 'references',
+        line,
+        column: 0,
+        filePath,
+        language: 'python',
+      });
+    }
+  }
+  return { nodes, references };
+}
+
 // Directory patterns
 const MODEL_DIRS = ['models', 'app/models', 'src/models'];
 const VIEW_DIRS = ['views', 'app/views', 'src/views', 'api/views'];
diff --git a/src/resolution/frameworks/react-native.ts b/src/resolution/frameworks/react-native.ts
new file mode 100644
index 000000000..f55fa4e18
--- /dev/null
+++ b/src/resolution/frameworks/react-native.ts
@@ -0,0 +1,481 @@
+/**
+ * React Native cross-language bridge resolver.
+ *
+ * Closes the JS ↔ native flow gap in React Native projects. Covers:
+ *
+ * **Legacy bridge** (older / still-prevalent in mid-tier RN libs):
+ *   - ObjC: `RCT_EXPORT_MODULE([opt_name])` declares a module; the module
+ *     name defaults to the class name minus an `RCT` prefix when no
+ *     argument is given. `RCT_EXPORT_METHOD(selector:(args))` declares a
+ *     JS-callable method whose JS name is the selector's first keyword.
+ *     `RCT_REMAP_METHOD(jsName, nativeSelector:(args))` overrides the JS
+ *     name explicitly.
+ *   - Java/Kotlin: `@ReactMethod` annotated methods on a
+ *     `ReactContextBaseJavaModule` subclass; the module name comes from
+ *     `getName()` returning a literal string.
+ *
+ * **TurboModules** (modern, used by react-native-svg, screens, FBSDK
+ * Next-gen libraries):
+ *   - TS spec interface declared in a `Native<X>.ts` file exporting
+ *     `TurboModuleRegistry.getEnforcing<Spec>('<ModuleName>')` (or
+ *     `.get<Spec>('<ModuleName>')`). The Spec interface methods are the
+ *     JS-callable surface; the matching native implementation is a class
+ *     whose method names match (selector first-keyword on ObjC,
+ *     identifier on Kotlin/Java).
+ *
+ * The two mechanisms share an end shape: a map from `(moduleName,
+ * jsMethodName)` to a native method node, plus a smaller map from
+ * `jsMethodName` alone for cases where the JS callsite doesn't carry
+ * the module qualifier (the most common JS pattern is
+ * `import Geo from './NativeGeolocation'; Geo.getPosition()` — the
+ * receiver is the default export, not literally `NativeModules.<Mod>`,
+ * so name-by-method-only is what actually resolves in practice).
+ *
+ * **Not covered** (deferred to a follow-up phase, per design doc §6):
+ *   - Fabric view components (`RCT_EXPORT_VIEW_PROPERTY` / Codegen view
+ *     specs) — these connect JSX props to native renderers, a different
+ *     flow shape that composes with the existing JSX synthesizer.
+ *   - Native → JS events (`RCTEventEmitter` / `NativeEventEmitter`) —
+ *     belongs in the callback synthesizer's cross-language channel.
+ */
+import type { Node } from '../../types';
+import {
+  FrameworkResolver,
+  ResolutionContext,
+} from '../types';
+
+/**
+ * One native RN method known to the resolver. Indexed by JS-visible name.
+ */
+interface NativeMethod {
+  /** Module name as seen from JS (`Geolocation`, `RNSVGRenderableModule`, …). */
+  moduleName: string;
+  /** JS-visible method name. */
+  jsName: string;
+  /** Native implementation node (ObjC method / Java method / Kotlin function). */
+  node: Node;
+}
+
+/** Per-context lazy map cache. */
+const nativeMethodMaps: WeakMap<
+  ResolutionContext,
+  { byJsName: Map<string, NativeMethod[]> }
+> = new WeakMap();
+
+// ─── Native-side extraction ─────────────────────────────────────────────────
+
+/**
+ * Default ObjC module name when `RCT_EXPORT_MODULE()` has no argument:
+ * strip a leading `RCT` prefix from the class name (Apple's convention)
+ * and treat the rest as the JS-visible module name. `RCTGeolocation` →
+ * `Geolocation`. Class names without an `RCT` prefix are returned
+ * unchanged.
+ */
+function defaultObjcModuleName(className: string): string {
+  return className.startsWith('RCT') && className.length > 3
+    ? className.slice(3)
+    : className;
+}
+
+/**
+ * Parse an ObjC `.m`/`.mm` file's source for `RCT_EXPORT_MODULE` and
+ * `RCT_EXPORT_METHOD` / `RCT_REMAP_METHOD` declarations, returning the
+ * inferred (moduleName, jsMethodName) pairs.
+ *
+ * The macro forms (a single `RCT_EXPORT_MODULE` per file conventionally
+ * matched to a single `@implementation`):
+ *   - `RCT_EXPORT_MODULE()` — module name = class name with `RCT` prefix
+ *     stripped
+ *   - `RCT_EXPORT_MODULE(jsName)` — explicit name
+ *   - `RCT_EXPORT_METHOD(selector:(arg1)label1:(arg2)label2)` — JS name =
+ *     `selector` (the first keyword)
+ *   - `RCT_REMAP_METHOD(jsName, selector:(arg1)label1:(arg2)label2)` —
+ *     JS name = literal `jsName`
+ *
+ * Regex-based scan is sufficient — these macros are highly stylized and
+ * appear at top level. Pulling them out of the full AST would require a
+ * macro-aware ObjC parse the tree-sitter grammar doesn't provide.
+ */
+function parseObjcRNExports(
+  source: string,
+  className: string | null
+): Array<{ moduleName: string; jsName: string; nativeSelectorFirstKw: string; line: number }> {
+  const results: Array<{ moduleName: string; jsName: string; nativeSelectorFirstKw: string; line: number }> = [];
+
+  // RCT_EXPORT_MODULE — one per file by convention. Capture the optional arg.
+  const moduleMatch = source.match(/RCT_EXPORT_MODULE\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)?\s*\)/);
+  // Need a module name to attribute methods. Prefer the explicit macro arg,
+  // then the class name, then bail (no module = nothing useful to register).
+  const moduleName =
+    moduleMatch?.[1] ??
+    (className ? defaultObjcModuleName(className) : null);
+  if (!moduleName) return results;
+
+  const lineOf = (idx: number): number => {
+    let line = 1;
+    for (let i = 0; i < idx && i < source.length; i++) if (source.charCodeAt(i) === 10) line++;
+    return line;
+  };
+
+  // RCT_EXPORT_METHOD(selectorFirstKw:(args)…)
+  // The first keyword (everything up to the first `:` or open paren) is the
+  // JS-visible name. We don't try to parse full multi-keyword selectors —
+  // RN's JS view of the method uses only the first keyword.
+  const exportRegex = /RCT_EXPORT_METHOD\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)/g;
+  let m: RegExpExecArray | null;
+  while ((m = exportRegex.exec(source)) !== null) {
+    const kw = m[1];
+    if (kw) results.push({ moduleName, jsName: kw, nativeSelectorFirstKw: kw, line: lineOf(m.index) });
+  }
+
+  // RCT_REMAP_METHOD(jsName, nativeSelectorFirstKw:(args)…)
+  const remapRegex =
+    /RCT_REMAP_METHOD\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*,\s*([A-Za-z_][A-Za-z0-9_]*)/g;
+  while ((m = remapRegex.exec(source)) !== null) {
+    const jsName = m[1];
+    const nativeKw = m[2];
+    if (jsName && nativeKw) {
+      results.push({ moduleName, jsName, nativeSelectorFirstKw: nativeKw, line: lineOf(m.index) });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Find the `@implementation` class name in an ObjC file — used as the
+ * fallback module name when `RCT_EXPORT_MODULE()` has no argument.
+ * (Categories of the form `@implementation Foo (Bar)` are correctly
+ * captured here as `Foo`, but a category file probably isn't where a
+ * fresh `RCT_EXPORT_MODULE` lives anyway.)
+ */
+function findObjcClassName(source: string): string | null {
+  const m = source.match(/@implementation\s+([A-Za-z_][A-Za-z0-9_]*)/);
+  return m?.[1] ?? null;
+}
+
+/**
+ * Parse a Java/Kotlin source file for `@ReactMethod` annotated methods
+ * and the surrounding class's `getName()` return value (the JS-visible
+ * module name).
+ *
+ * Java: `@ReactMethod public void getCurrentPosition(Callback cb) { … }`
+ * Kotlin: `@ReactMethod fun getCurrentPosition(cb: Callback) { … }`
+ *
+ * Class name comes from `class XxxModule extends ReactContextBaseJavaModule`
+ * (Java) or `class XxxModule : ReactContextBaseJavaModule(...)` (Kotlin).
+ * The JS-visible module name comes from `getName()` returning a literal
+ * string — fall back to the class name with a `Module` suffix stripped
+ * when the literal isn't present.
+ */
+function parseJvmRNExports(
+  source: string
+): Array<{ moduleName: string; jsName: string }> {
+  const results: Array<{ moduleName: string; jsName: string }> = [];
+
+  // getName() literal — Java + Kotlin both look something like:
+  //   public String getName() { return "Geolocation"; }
+  //   fun getName(): String = "Geolocation"
+  //   fun getName() = "Geolocation"
+  const getName = source.match(
+    /\bgetName\s*\([^)]*\)\s*(?::\s*String)?\s*(?:=\s*|\{[^}]*return\s*)"([^"]+)"/
+  );
+  // Class name fallback.
+  const classMatch =
+    source.match(/\bclass\s+([A-Za-z_][A-Za-z0-9_]*)\b[^{]*ReactContextBaseJavaModule/) ??
+    source.match(/\bclass\s+([A-Za-z_][A-Za-z0-9_]*)\b[^{]*ReactPackage/);
+  const moduleName =
+    getName?.[1] ?? (classMatch?.[1] ? classMatch[1].replace(/Module$/, '') : null);
+  if (!moduleName) return results;
+
+  // @ReactMethod annotations — followed (after optional modifiers / args /
+  // newlines) by either `void <name>(` (Java) or `fun <name>(` (Kotlin).
+  const methodRegex =
+    /@ReactMethod\b[^{]*?(?:\bfun\s+|\bvoid\s+|\bpublic\s+\w[\w<>\[\]]*\s+)([A-Za-z_][A-Za-z0-9_]*)\s*\(/g;
+  let m: RegExpExecArray | null;
+  while ((m = methodRegex.exec(source)) !== null) {
+    const jsName = m[1];
+    if (jsName) results.push({ moduleName, jsName });
+  }
+
+  return results;
+}
+
+/**
+ * Parse a TS file for a TurboModule spec declaration. The spec file is
+ * the JS↔native source-of-truth in the new architecture — its interface
+ * lists every JS-visible method, and a `TurboModuleRegistry.get*<Spec>(...)`
+ * default export pins the module name.
+ *
+ * Returns `null` when the file isn't a TurboModule spec.
+ */
+function parseTurboModuleSpec(
+  source: string
+): { moduleName: string; methods: string[] } | null {
+  // `TurboModuleRegistry.getEnforcing<Spec>('ModuleName')` or
+  // `TurboModuleRegistry.get<Spec>('ModuleName')`. The literal must be a
+  // single-or-double-quoted string.
+  const regMatch = source.match(
+    /TurboModuleRegistry\.(?:getEnforcing|get)\s*<[^>]*>\s*\(\s*['"]([^'"]+)['"]\s*\)/
+  );
+  if (!regMatch || !regMatch[1]) return null;
+  const moduleName = regMatch[1];
+
+  // Find `export interface Spec extends TurboModule { … }` and pull each
+  // method declaration's name. We don't need types — just names.
+  const ifaceMatch = source.match(
+    /export\s+interface\s+Spec\b[^{]*\{([\s\S]*?)\n\}/
+  );
+  if (!ifaceMatch || !ifaceMatch[1]) return null;
+  const body = ifaceMatch[1];
+
+  const methods: string[] = [];
+  // Method shape: `name(args): ReturnType;` or `name(): void;`. Skip
+  // properties (no parens before colon).
+  const methodRegex = /^\s*([A-Za-z_][A-Za-z0-9_]*)\s*\(/gm;
+  let m: RegExpExecArray | null;
+  while ((m = methodRegex.exec(body)) !== null) {
+    const name = m[1];
+    if (name) methods.push(name);
+  }
+  return { moduleName, methods };
+}
+
+// ─── Map building ───────────────────────────────────────────────────────────
+
+/**
+ * RCTEventEmitter built-ins that every emitter subclass inherits. JS code
+ * doesn't directly call these — they're internal plumbing for the
+ * `NativeEventEmitter` abstraction. If we leave them in the bridge map,
+ * every JS `addListener` / `remove` call (Firestore subscribers, RxJS
+ * pipelines, plain Array.remove, etc.) gets mis-bridged to whichever
+ * emitter happens to define them. Skip during map building.
+ */
+const RN_EMITTER_BUILTINS = new Set([
+  'addListener',
+  'removeListeners',
+  'remove',
+  'invalidate',
+  'startObserving',
+  'stopObserving',
+]);
+
+function buildRNMaps(context: ResolutionContext): { byJsName: Map<string, NativeMethod[]> } {
+  const cached = nativeMethodMaps.get(context);
+  if (cached) return cached;
+
+  const byJsName = new Map<string, NativeMethod[]>();
+  const allFiles = context.getAllFiles();
+  // Pre-index native methods by name for fast lookup when matching to
+  // their bridge exports.
+  const objcMethodsByFirstKw = new Map<string, Node[]>();
+  const jvmMethodsByName = new Map<string, Node[]>();
+  for (const node of context.getNodesByKind('method')) {
+    if (node.language === 'objc') {
+      const firstKw = node.name.includes(':') ? node.name.split(':')[0] : node.name;
+      if (firstKw) {
+        const arr = objcMethodsByFirstKw.get(firstKw);
+        if (arr) arr.push(node);
+        else objcMethodsByFirstKw.set(firstKw, [node]);
+      }
+    } else if (node.language === 'java' || node.language === 'kotlin') {
+      const arr = jvmMethodsByName.get(node.name);
+      if (arr) arr.push(node);
+      else jvmMethodsByName.set(node.name, [node]);
+    }
+  }
+
+  for (const file of allFiles) {
+    // Legacy bridge — ObjC side.
+    if (file.endsWith('.m') || file.endsWith('.mm')) {
+      const source = context.readFile(file);
+      if (!source) continue;
+      const className = findObjcClassName(source);
+      const exports = parseObjcRNExports(source, className);
+      for (const exp of exports) {
+        if (RN_EMITTER_BUILTINS.has(exp.jsName)) continue;
+        // Resolve to the native node by selector first-keyword. Multiple
+        // ObjC methods may share a first keyword across modules; filter by
+        // file path to attribute the export to this module's
+        // implementation file.
+        const candidates = objcMethodsByFirstKw.get(exp.nativeSelectorFirstKw) ?? [];
+        const node = candidates.find((c) => c.filePath === file) ?? candidates[0];
+        if (!node) continue;
+        const entry: NativeMethod = { moduleName: exp.moduleName, jsName: exp.jsName, node };
+        const arr = byJsName.get(exp.jsName);
+        if (arr) arr.push(entry);
+        else byJsName.set(exp.jsName, [entry]);
+      }
+    }
+
+    // Legacy bridge — Java/Kotlin side.
+    if (file.endsWith('.java') || file.endsWith('.kt')) {
+      const source = context.readFile(file);
+      if (!source) continue;
+      const exports = parseJvmRNExports(source);
+      for (const exp of exports) {
+        if (RN_EMITTER_BUILTINS.has(exp.jsName)) continue;
+        const candidates = jvmMethodsByName.get(exp.jsName) ?? [];
+        const node = candidates.find((c) => c.filePath === file) ?? candidates[0];
+        if (!node) continue;
+        const entry: NativeMethod = { moduleName: exp.moduleName, jsName: exp.jsName, node };
+        const arr = byJsName.get(exp.jsName);
+        if (arr) arr.push(entry);
+        else byJsName.set(exp.jsName, [entry]);
+      }
+    }
+
+    // TurboModule spec — TS side.
+    if (file.endsWith('.ts') || file.endsWith('.tsx')) {
+      const source = context.readFile(file);
+      if (!source) continue;
+      const spec = parseTurboModuleSpec(source);
+      if (!spec) continue;
+      // For each spec method, find a matching native implementation by
+      // name. The spec's module name doesn't determine the native file
+      // path (Codegen wires it via name convention), so we match across
+      // all native methods of the right name.
+      for (const methodName of spec.methods) {
+        if (RN_EMITTER_BUILTINS.has(methodName)) continue;
+        // ObjC first-keyword match, then JVM bare-name match. Don't
+        // require module-name match for ObjC because the native side may
+        // have stripped a prefix.
+        const objcCands = objcMethodsByFirstKw.get(methodName) ?? [];
+        const jvmCands = jvmMethodsByName.get(methodName) ?? [];
+        for (const node of [...objcCands, ...jvmCands]) {
+          const entry: NativeMethod = { moduleName: spec.moduleName, jsName: methodName, node };
+          const arr = byJsName.get(methodName);
+          if (arr) arr.push(entry);
+          else byJsName.set(methodName, [entry]);
+        }
+      }
+    }
+  }
+
+  const result = { byJsName };
+  nativeMethodMaps.set(context, result);
+  return result;
+}
+
+// ─── Resolver ───────────────────────────────────────────────────────────────
+
+export const reactNativeBridgeResolver: FrameworkResolver = {
+  name: 'react-native-bridge',
+  // objc/mm included so `extract()` sees the native files — `resolve()` still
+  // only redirects JS callers (it returns null for native languages).
+  languages: ['javascript', 'typescript', 'tsx', 'jsx', 'objc'],
+
+  /**
+   * Extract `RCT_EXPORT_METHOD` / `RCT_REMAP_METHOD` declarations as method
+   * nodes. These macros parse as a macro-expression (an ERROR node), NOT a
+   * `method_definition`, so the ObjC extractor never made a node for them — the
+   * iOS half of a native module was invisible, so a JS call couldn't resolve to
+   * it and the cross-platform pairing had nothing to pair. The node is named by
+   * the JS-visible name (the selector's first keyword, or the explicit
+   * `RCT_REMAP_METHOD` JS name) so it matches the Android `@ReactMethod` method.
+   */
+  extract(filePath, source) {
+    if (!filePath.endsWith('.m') && !filePath.endsWith('.mm')) return { nodes: [], references: [] };
+    if (!/RCT_EXPORT_MODULE\b/.test(source)) return { nodes: [], references: [] };
+    const exports = parseObjcRNExports(source, findObjcClassName(source));
+    const now = Date.now();
+    const nodes: Node[] = [];
+    const seen = new Set<string>();
+    for (const e of exports) {
+      if (seen.has(e.jsName)) continue;
+      seen.add(e.jsName);
+      nodes.push({
+        id: `rn-export:${filePath}:${e.moduleName}.${e.jsName}`,
+        kind: 'method',
+        name: e.jsName,
+        qualifiedName: `${filePath}::${e.moduleName}.${e.jsName}`,
+        filePath,
+        language: 'objc',
+        startLine: e.line,
+        endLine: e.line,
+        startColumn: 0,
+        endColumn: 0,
+        isExported: true,
+        docstring: `RCT_EXPORT_METHOD ${e.nativeSelectorFirstKw} (module ${e.moduleName})`,
+        signature: `RCT_EXPORT_METHOD(${e.nativeSelectorFirstKw}:…)`,
+        updatedAt: now,
+      });
+    }
+    return { nodes, references: [] };
+  },
+
+  /**
+   * Detect: package.json depends on `react-native`, OR any source file
+   * uses the `RCT_EXPORT_MODULE` / `RCT_EXPORT_METHOD` /
+   * `TurboModuleRegistry` markers. Either signal is enough — different
+   * libraries split the JS package from the native code (`react-native-svg`'s
+   * apple/ + android/ directories vs its src/), so we don't require both.
+   */
+  detect(context) {
+    const pkg = context.readFile('package.json');
+    if (pkg && /["']react-native["']\s*:/.test(pkg)) return true;
+    // Fallback: scan a small number of files for the macro markers — only
+    // looking at the first ones returned by getAllFiles to keep detect()
+    // fast on huge repos.
+    const files = context.getAllFiles();
+    for (let i = 0; i < Math.min(files.length, 200); i++) {
+      const f = files[i];
+      if (!f) continue;
+      if (f.endsWith('.mm') || f.endsWith('.m')) {
+        const src = context.readFile(f);
+        if (src && /RCT_EXPORT_MODULE\b/.test(src)) return true;
+      }
+      if (f.endsWith('.ts') || f.endsWith('.tsx')) {
+        const src = context.readFile(f);
+        if (src && /TurboModuleRegistry\.(?:get|getEnforcing)\s*</.test(src)) return true;
+      }
+    }
+    return false;
+  },
+
+  claimsReference(_name) {
+    // JS-visible method names are ordinary identifiers and are typically
+    // already in `knownNames` (every TurboModule spec method, every
+    // RCT_EXPORT_METHOD, has a node somewhere). So we don't need to
+    // claim through the pre-filter — the ref reaches us via the normal
+    // hasAnyPossibleMatch path.
+    return false;
+  },
+
+  resolve(ref, context) {
+    // We only redirect JS callers — native callers don't need this resolver.
+    if (
+      ref.language !== 'javascript' &&
+      ref.language !== 'typescript' &&
+      ref.language !== 'tsx' &&
+      ref.language !== 'jsx'
+    ) {
+      return null;
+    }
+
+    // JS callsites of `obj.method()` reach the resolver as either
+    // `obj.method` (qualified) or `method` (bare). Strip a single dot
+    // prefix to get the JS-visible method name.
+    const name = ref.referenceName.includes('.')
+      ? ref.referenceName.slice(ref.referenceName.lastIndexOf('.') + 1)
+      : ref.referenceName;
+
+    const maps = buildRNMaps(context);
+    const entries = maps.byJsName.get(name);
+    if (!entries || entries.length === 0) return null;
+
+    // Prefer the iOS (ObjC) target over Android when both exist — iOS is
+    // the conventional first-class platform for RN library docs and most
+    // graph queries. We still record only one edge; a JVM-only resolution
+    // is fine when no ObjC target exists.
+    const objc = entries.find((e) => e.node.language === 'objc');
+    const target = objc ?? entries[0];
+    if (!target) return null;
+    return {
+      original: ref,
+      targetNodeId: target.node.id,
+      confidence: 0.6,
+      resolvedBy: 'framework',
+    };
+  },
+};
diff --git a/src/resolution/frameworks/react.ts b/src/resolution/frameworks/react.ts
index c900d4892..05b0d8288 100644
--- a/src/resolution/frameworks/react.ts
+++ b/src/resolution/frameworks/react.ts
@@ -32,8 +32,19 @@ export const reactResolver: FrameworkResolver = {
   },
 
   resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null {
-    // Pattern 1: Component references (PascalCase)
-    if (isPascalCase(ref.referenceName) && !isBuiltInType(ref.referenceName)) {
+    // Pattern 1: Component references (PascalCase). Only from JSX-capable
+    // files — a component is USED in markup, which only parses in .tsx/.jsx.
+    // Without this gate, every PascalCase TYPE reference in plain .ts files
+    // went through component resolution: in a monorepo with same-named
+    // classes per package (#764, amplication), a `.ts` GraphQL-types file's
+    // own `Account` type alias lost to an arbitrary `Account` CLASS in
+    // another package (the framework's 0.8 outranked the name-matcher's
+    // proximity-correct 0.7).
+    if (
+      (ref.language === 'tsx' || ref.language === 'jsx') &&
+      isPascalCase(ref.referenceName) &&
+      !isBuiltInType(ref.referenceName)
+    ) {
       const result = resolveComponent(ref.referenceName, ref.filePath, context);
       if (result) {
         return {
@@ -76,6 +87,7 @@ export const reactResolver: FrameworkResolver = {
 
   extract(filePath, content) {
     const nodes: Node[] = [];
+    const references: UnresolvedRef[] = [];
     const now = Date.now();
 
     // Extract component definitions
@@ -143,6 +155,89 @@ export const reactResolver: FrameworkResolver = {
       });
     }
 
+    // React Router: <Route path="/x" component={Comp}/> (v5) or
+    // <Route path="/x" element={<Comp/>}/> (v6). Attributes appear in any order,
+    // and element={...} contains a nested `>`, so scan a window after each
+    // <Route rather than trying to match the whole (possibly multi-line) tag.
+    const routeTagRegex = /<Route\b/g;
+    let routeMatch: RegExpExecArray | null;
+    while ((routeMatch = routeTagRegex.exec(content)) !== null) {
+      const window = content.slice(routeMatch.index, routeMatch.index + 400);
+      const pathMatch = window.match(/\bpath\s*=\s*["']([^"']+)["']/);
+      if (!pathMatch) continue; // index/layout routes without a path
+      const routePath = pathMatch[1]!;
+      const compMatch =
+        window.match(/\bcomponent\s*=\s*\{\s*([A-Z][A-Za-z0-9_]*)/) ||
+        window.match(/\belement\s*=\s*\{\s*<\s*([A-Z][A-Za-z0-9_]*)/);
+      const line = content.slice(0, routeMatch.index).split('\n').length;
+      const routeNode: Node = {
+        id: `route:${filePath}:${line}:${routePath}`,
+        kind: 'route',
+        name: routePath,
+        qualifiedName: `${filePath}::route:${routePath}`,
+        filePath,
+        startLine: line,
+        endLine: line,
+        startColumn: 0,
+        endColumn: 0,
+        language: filePath.endsWith('.tsx') ? 'tsx' : 'jsx',
+        updatedAt: now,
+      };
+      nodes.push(routeNode);
+      if (compMatch) {
+        references.push({
+          fromNodeId: routeNode.id,
+          referenceName: compMatch[1]!,
+          referenceKind: 'references',
+          line,
+          column: 0,
+          filePath,
+          language: filePath.endsWith('.tsx') ? 'tsx' : 'jsx',
+        });
+      }
+    }
+
+    // React Router data-router (v6.4+): createBrowserRouter([{ path, element }]).
+    // Only scan files that use the data-router API, then pull each route object's
+    // `path` + `element={<Comp/>}` / `Component: Comp` (a forward window confirms
+    // it's a route object, not a stray `path:` field).
+    if (/\b(?:createBrowserRouter|createHashRouter|createMemoryRouter|createRoutesFromElements)\b/.test(content)) {
+      const objPathRe = /\bpath\s*:\s*['"]([^'"]*)['"]/g;
+      let om: RegExpExecArray | null;
+      while ((om = objPathRe.exec(content)) !== null) {
+        const win = content.slice(om.index, om.index + 300);
+        const compMatch =
+          win.match(/\belement\s*:\s*<\s*([A-Z][A-Za-z0-9_]*)/) ||
+          win.match(/\bComponent\s*:\s*([A-Z][A-Za-z0-9_]*)/);
+        if (!compMatch) continue; // require a component → it's a real route object
+        const routePath = om[1] || '/';
+        const line = content.slice(0, om.index).split('\n').length;
+        const routeNode: Node = {
+          id: `route:${filePath}:${line}:${routePath}`,
+          kind: 'route',
+          name: routePath,
+          qualifiedName: `${filePath}::route:${routePath}`,
+          filePath,
+          startLine: line,
+          endLine: line,
+          startColumn: 0,
+          endColumn: 0,
+          language: filePath.endsWith('.tsx') ? 'tsx' : 'jsx',
+          updatedAt: now,
+        };
+        nodes.push(routeNode);
+        references.push({
+          fromNodeId: routeNode.id,
+          referenceName: compMatch[1]!,
+          referenceKind: 'references',
+          line,
+          column: 0,
+          filePath,
+          language: filePath.endsWith('.tsx') ? 'tsx' : 'jsx',
+        });
+      }
+    }
+
     // Extract Next.js pages/routes (pages directory convention)
     if (filePath.includes('pages/') || filePath.includes('app/')) {
       // Default export in pages becomes a route
@@ -169,7 +264,7 @@ export const reactResolver: FrameworkResolver = {
       }
     }
 
-    return { nodes, references: [] };
+    return { nodes, references };
   },
 };
 
@@ -221,7 +316,10 @@ function resolveComponent(
   );
   if (preferred.length > 0) return preferred[0]!.id;
 
-  return components[0]!.id;
+  // No positional signal: only an UNAMBIGUOUS name may resolve. Returning
+  // components[0] here picked an arbitrary same-named class anywhere in the
+  // repo (#764) — let the name-matcher's proximity scoring decide instead.
+  return components.length === 1 ? components[0]!.id : null;
 }
 
 /**
@@ -279,7 +377,17 @@ function filePathToRoute(filePath: string): string | null {
   // app/page.tsx -> /
   // app/about/page.tsx -> /about
 
-  if (filePath.includes('pages/')) {
+  // Only real page-component files are routes. Exclude non-page extensions
+  // (.mjs/.json/.cjs), config files (next.config.ts, vite.config.ts…), and
+  // Next.js special files (_app/_document). This also stops a `*.config.mjs`
+  // with `export default` in a dir like `nextjs-pages/` from being a "route".
+  const base = filePath.split('/').pop() ?? '';
+  if (!/\.(tsx?|jsx?)$/.test(base)) return null;
+  if (base.startsWith('_') || /\.config\.[a-z]+$/.test(base)) return null;
+
+  // Match pages/ and app/ as PATH SEGMENTS (not a substring — `nextjs-pages/`
+  // must not count as a `pages/` router dir).
+  if (/(?:^|\/)pages\//.test(filePath)) {
     let route = filePath
       .replace(/^.*pages\//, '/')
       .replace(/\/index\.(tsx?|jsx?)$/, '')
@@ -290,7 +398,7 @@ function filePathToRoute(filePath: string): string | null {
     return route;
   }
 
-  if (filePath.includes('app/')) {
+  if (/(?:^|\/)app\//.test(filePath)) {
     // App router - only page.tsx files are routes
     if (!filePath.includes('page.')) {
       return null;
diff --git a/src/resolution/frameworks/ruby.ts b/src/resolution/frameworks/ruby.ts
index 52c6ead25..9c9e5a683 100644
--- a/src/resolution/frameworks/ruby.ts
+++ b/src/resolution/frameworks/ruby.ts
@@ -12,6 +12,13 @@ export const railsResolver: FrameworkResolver = {
   name: 'rails',
   languages: ['ruby'],
 
+  // `controller#action` route refs name no declared symbol, so resolveOne's
+  // pre-filter would drop them before resolve() runs. Claim them (like the django
+  // `_iterable_class` hook) so they reach Pattern 0.
+  claimsReference(name: string): boolean {
+    return /^[\w/]+#\w+$/.test(name);
+  },
+
   detect(context: ResolutionContext): boolean {
     // Check for Gemfile with rails
     const gemfile = context.readFile('Gemfile');
@@ -32,6 +39,18 @@ export const railsResolver: FrameworkResolver = {
   },
 
   resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null {
+    // Pattern 0: route action `controller#action` (from RESTful `resources` or an
+    // explicit route) → the action method in that controller. Precise — avoids the
+    // bare-`action` ambiguity (every controller has an `index`/`show`).
+    const ca = ref.referenceName.match(/^([\w/]+)#(\w+)$/);
+    if (ca) {
+      const result = resolveControllerAction(ca[1]!, ca[2]!, context);
+      if (result) {
+        return { original: ref, targetNodeId: result, confidence: 0.85, resolvedBy: 'framework' };
+      }
+      return null;
+    }
+
     // Pattern 1: Model references (ActiveRecord)
     if (/^[A-Z][a-zA-Z]+$/.test(ref.referenceName)) {
       const result = resolveModel(ref.referenceName, context);
@@ -99,7 +118,7 @@ export const railsResolver: FrameworkResolver = {
     const routeRegex = /\b(get|post|put|patch|delete|match)\s+['"]([^'"]+)['"]\s*(?:,\s*to:\s*|=>\s*)['"]([^#'"]+)#([^'"]+)['"]/g;
     let match: RegExpExecArray | null;
     while ((match = routeRegex.exec(safe)) !== null) {
-      const [, method, routePath, _controller, action] = match;
+      const [, method, routePath, ctrl, action] = match;
       const line = safe.slice(0, match.index).split('\n').length;
       const upper = method!.toUpperCase();
       const routeNode: Node = {
@@ -119,7 +138,7 @@ export const railsResolver: FrameworkResolver = {
 
       references.push({
         fromNodeId: routeNode.id,
-        referenceName: action!,
+        referenceName: `${ctrl}#${action}`, // precise controller#action, not bare action
         referenceKind: 'references',
         line,
         column: 0,
@@ -128,12 +147,94 @@ export const railsResolver: FrameworkResolver = {
       });
     }
 
+    // RESTful resources: `resources :articles` / `resource :user` (the dominant
+    // Rails routing) generate a controller action per REST verb. The old resolver
+    // only saw explicit `get '/x' => 'c#a'` routes, so resource-routed apps had
+    // ZERO route nodes. Expand each into its actions → `controller#action` refs.
+    const resRegex = /\b(resources?)\s+:(\w+)([^\n]*)/g;
+    while ((match = resRegex.exec(safe)) !== null) {
+      const plural = match[1] === 'resources';
+      const resName = match[2]!;
+      const tail = match[3] || '';
+      let actions = plural ? PLURAL_ACTIONS : SINGULAR_ACTIONS;
+      const only = tail.match(/only:\s*\[([^\]]*)\]/);
+      const except = tail.match(/except:\s*\[([^\]]*)\]/);
+      const symList = (s: string) => new Set(s.split(',').map((x) => x.trim().replace(/^:/, '')));
+      if (only) { const s = symList(only[1]!); actions = actions.filter((a) => s.has(a)); }
+      else if (except) { const s = symList(except[1]!); actions = actions.filter((a) => !s.has(a)); }
+      // `resources :articles` → ArticlesController; `resource :user` → UsersController.
+      const ctrl = plural ? resName : pluralize(resName);
+      const line = safe.slice(0, match.index).split('\n').length;
+      for (const action of actions) {
+        const spec = RESTFUL_ROUTES[action]!;
+        const path = spec.path(resName);
+        const routeNode: Node = {
+          id: `route:${filePath}:${line}:${spec.method}:${ctrl}#${action}`,
+          kind: 'route',
+          name: `${spec.method} ${path}`,
+          qualifiedName: `${filePath}::route:${ctrl}#${action}`,
+          filePath, startLine: line, endLine: line, startColumn: 0, endColumn: match[0].length,
+          language: 'ruby', updatedAt: now,
+        };
+        nodes.push(routeNode);
+        references.push({
+          fromNodeId: routeNode.id,
+          referenceName: `${ctrl}#${action}`,
+          referenceKind: 'references',
+          line, column: 0, filePath, language: 'ruby',
+        });
+      }
+    }
+
     return { nodes, references };
   },
 };
 
 // Helper functions
 
+// RESTful action → HTTP verb + path. `resources` gets all seven; a singular
+// `resource` omits `index`.
+const RESTFUL_ROUTES: Record<string, { method: string; path: (r: string) => string }> = {
+  index:   { method: 'GET',    path: (r) => `/${r}` },
+  create:  { method: 'POST',   path: (r) => `/${r}` },
+  new:     { method: 'GET',    path: (r) => `/${r}/new` },
+  show:    { method: 'GET',    path: (r) => `/${r}/:id` },
+  edit:    { method: 'GET',    path: (r) => `/${r}/:id/edit` },
+  update:  { method: 'PATCH',  path: (r) => `/${r}/:id` },
+  destroy: { method: 'DELETE', path: (r) => `/${r}/:id` },
+};
+const PLURAL_ACTIONS = ['index', 'create', 'new', 'show', 'edit', 'update', 'destroy'];
+const SINGULAR_ACTIONS = ['create', 'new', 'show', 'edit', 'update', 'destroy'];
+
+/** Naive ActiveSupport-style pluralize — covers the common resource names. */
+function pluralize(w: string): string {
+  if (/[^aeiou]y$/.test(w)) return w.slice(0, -1) + 'ies';
+  if (/(s|x|z|ch|sh)$/.test(w)) return w + 'es';
+  return w + 's';
+}
+
+/** snake_case → CamelCase (`user_profiles` → `UserProfiles`). */
+function camelize(s: string): string {
+  return s.split('_').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+}
+
+/** Resolve a `controller#action` route ref to the action method in that controller. */
+function resolveControllerAction(ctrlPath: string, action: string, context: ResolutionContext): string | null {
+  // Rails convention: `articles` → app/controllers/articles_controller.rb.
+  const direct = `app/controllers/${ctrlPath}_controller.rb`;
+  if (context.fileExists(direct)) {
+    const m = context.getNodesInFile(direct).find((n) => (n.kind === 'method' || n.kind === 'function') && n.name === action);
+    if (m) return m.id;
+  }
+  // Fall back: controller class by name, then the action method in its file.
+  const cls = camelize(ctrlPath.split('/').pop()!) + 'Controller';
+  for (const ctrl of context.getNodesByName(cls).filter((n) => n.kind === 'class')) {
+    const m = context.getNodesInFile(ctrl.filePath).find((n) => (n.kind === 'method' || n.kind === 'function') && n.name === action);
+    if (m) return m.id;
+  }
+  return null;
+}
+
 function resolveModel(name: string, context: ResolutionContext): string | null {
   // Try direct file path lookup first (Rails convention: CamelCase -> snake_case.rb)
   const snakeName = name.replace(/([A-Z])/g, '_$1').toLowerCase().slice(1);
diff --git a/src/resolution/frameworks/rust.ts b/src/resolution/frameworks/rust.ts
index a94cf50d3..f4828a77a 100644
--- a/src/resolution/frameworks/rust.ts
+++ b/src/resolution/frameworks/rust.ts
@@ -135,13 +135,64 @@ export const rustResolver: FrameworkResolver = {
       }
     }
 
-    // Axum: .route("/path", get(handler))
-    const axumRegex = /\.route\s*\(\s*"([^"]+)"\s*,\s*(get|post|put|patch|delete)\s*\(\s*(\w+)/g;
-    while ((match = axumRegex.exec(safe)) !== null) {
-      const [, routePath, method, handler] = match;
+    // Axum: .route("/path", get(h1).post(h2)…) — balanced-paren scan the route
+    // call, then emit one route node per chained method. Handlers may be
+    // namespaced (`get(module::handler)`, `get(self::list)`); take the last
+    // path segment so the ref names the fn, not the module.
+    const routeOpenRegex = /\.route\s*\(/g;
+    while ((match = routeOpenRegex.exec(safe)) !== null) {
+      const openIdx = safe.indexOf('(', match.index);
+      if (openIdx < 0) continue;
+      const closeIdx = findMatchingParen(safe, openIdx);
+      if (closeIdx < 0) continue;
+
+      const args = safe.slice(openIdx + 1, closeIdx);
+      const pathMatch = args.match(/^\s*"([^"]+)"\s*,/);
+      if (!pathMatch) continue;
+      const routePath = pathMatch[1]!;
       const line = safe.slice(0, match.index).split('\n').length;
-      const upper = method!.toUpperCase();
 
+      const methodBody = args.slice(pathMatch[0].length);
+      const methodHandlerRegex = /\b(get|post|put|patch|delete|head|options|trace)\s*\(\s*([A-Za-z_][\w:]*)/g;
+      let mh: RegExpExecArray | null;
+      while ((mh = methodHandlerRegex.exec(methodBody)) !== null) {
+        const upper = mh[1]!.toUpperCase();
+        const handler = mh[2]!.split('::').filter(Boolean).pop();
+        if (!handler) continue;
+
+        const routeNode: Node = {
+          id: `route:${filePath}:${line}:${upper}:${routePath}`,
+          kind: 'route',
+          name: `${upper} ${routePath}`,
+          qualifiedName: `${filePath}::route:${routePath}`,
+          filePath,
+          startLine: line,
+          endLine: line,
+          startColumn: 0,
+          endColumn: 0,
+          language: 'rust',
+          updatedAt: now,
+        };
+        nodes.push(routeNode);
+
+        references.push({
+          fromNodeId: routeNode.id,
+          referenceName: handler,
+          referenceKind: 'references',
+          line,
+          column: 0,
+          filePath,
+          language: 'rust',
+        });
+      }
+    }
+
+    // Actix-web builder API (the dominant actix routing style; attribute macros
+    // are handled above). The handler lives in `.to(handler)`, not `get(handler)`.
+    const pushActixRoute = (routePath: string, method: string, handlerExpr: string, line: number) => {
+      const handler = handlerExpr.split('::').filter(Boolean).pop();
+      if (!handler) return;
+      const upper = method.toUpperCase();
       const routeNode: Node = {
         id: `route:${filePath}:${line}:${upper}:${routePath}`,
         kind: 'route',
@@ -151,21 +202,53 @@ export const rustResolver: FrameworkResolver = {
         startLine: line,
         endLine: line,
         startColumn: 0,
-        endColumn: match[0].length,
+        endColumn: 0,
         language: 'rust',
         updatedAt: now,
       };
       nodes.push(routeNode);
-
       references.push({
         fromNodeId: routeNode.id,
-        referenceName: handler!,
+        referenceName: handler,
         referenceKind: 'references',
         line,
         column: 0,
         filePath,
         language: 'rust',
       });
+    };
+
+    // web::resource("/path") { .route(web::METHOD().to(h)) | .to(h) } — possibly chained.
+    const resourceRegex = /web::resource\s*\(\s*"([^"]+)"\s*\)/g;
+    while ((match = resourceRegex.exec(safe)) !== null) {
+      const routePath = match[1]!;
+      const startLine = safe.slice(0, match.index).split('\n').length;
+      const after = match.index + match[0].length;
+      // Bound the resource's method chain at the next resource() to avoid bleed.
+      const nextRes = safe.indexOf('web::resource', after);
+      const end = Math.min(after + 500, nextRes === -1 ? safe.length : nextRes);
+      const chain = safe.slice(after, end);
+
+      const methodTo = /web::(get|post|put|patch|delete|head)\s*\(\s*\)\s*\.to\s*\(\s*([A-Za-z_][\w:]*)/g;
+      let m2: RegExpExecArray | null;
+      let found = false;
+      while ((m2 = methodTo.exec(chain)) !== null) {
+        const mLine = startLine + chain.slice(0, m2.index).split('\n').length - 1;
+        pushActixRoute(routePath, m2[1]!, m2[2]!, mLine);
+        found = true;
+      }
+      // Direct `.resource("/x").to(handler)` (all methods) when no explicit verb route.
+      if (!found) {
+        const direct = chain.match(/^\s*\.to\s*\(\s*([A-Za-z_][\w:]*)/);
+        if (direct) pushActixRoute(routePath, 'ANY', direct[1]!, startLine);
+      }
+    }
+
+    // App-level: .route("/path", web::METHOD().to(handler)).
+    const appRouteRegex = /\.route\s*\(\s*"([^"]+)"\s*,\s*web::(get|post|put|patch|delete|head)\s*\(\s*\)\s*\.to\s*\(\s*([A-Za-z_][\w:]*)/g;
+    while ((match = appRouteRegex.exec(safe)) !== null) {
+      const line = safe.slice(0, match.index).split('\n').length;
+      pushActixRoute(match[1]!, match[2]!, match[3]!, line);
     }
 
     return { nodes, references };
@@ -181,6 +264,19 @@ const FUNCTION_KINDS = new Set(['function']);
 const SERVICE_KINDS = new Set(['struct', 'trait']);
 const STRUCT_KINDS = new Set(['struct']);
 
+/** Index of the ')' that matches the '(' at openIdx, or -1 if unbalanced. */
+function findMatchingParen(s: string, openIdx: number): number {
+  let depth = 0;
+  for (let i = openIdx; i < s.length; i++) {
+    if (s[i] === '(') depth++;
+    else if (s[i] === ')') {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
 /**
  * Resolve a symbol by name using indexed queries instead of scanning all files.
  */
diff --git a/src/resolution/frameworks/svelte.ts b/src/resolution/frameworks/svelte.ts
index 8848c8576..684852957 100644
--- a/src/resolution/frameworks/svelte.ts
+++ b/src/resolution/frameworks/svelte.ts
@@ -220,7 +220,11 @@ function resolveComponent(
   const sameDir = components.filter((n) => n.filePath.startsWith(fromDir));
   if (sameDir.length > 0) return sameDir[0]!.id;
 
-  return components[0]!.id;
+  // No positional signal: only an UNAMBIGUOUS name may resolve — picking
+  // components[0] chose an arbitrary same-named component in a multi-app
+  // monorepo (#764). Ambiguity falls through to the name-matcher, whose
+  // proximity scoring decides.
+  return components.length === 1 ? components[0]!.id : null;
 }
 
 /**
diff --git a/src/resolution/frameworks/swift-objc.ts b/src/resolution/frameworks/swift-objc.ts
new file mode 100644
index 000000000..e12e9294a
--- /dev/null
+++ b/src/resolution/frameworks/swift-objc.ts
@@ -0,0 +1,299 @@
+/**
+ * Swift ↔ Objective-C bridge resolver.
+ *
+ * Closes the cross-language flow gap in mixed iOS codebases. The pure
+ * bridging name math lives in `../swift-objc-bridge.ts`; this file wires
+ * it into the resolution pipeline.
+ *
+ * **Two directions to close:**
+ *
+ * 1. **Swift call → ObjC method** — A Swift caller writes
+ *    `imageDownloader.download(url:completion:)`. Tree-sitter-swift parses
+ *    this as a call_expression whose callee identifier is `download`
+ *    (parameter labels live in the argument list, not the callee). The
+ *    name-matcher tries to find any node named `download` and fails (no
+ *    Swift method by that name in this project; the ObjC implementation is
+ *    `-downloadURL:completion:`). We catch it here: from the bare Swift
+ *    name `download`, look up ObjC methods whose bridged Swift base name
+ *    would be `download` (using `swiftBaseNamesForObjcSelector`'s reverse
+ *    map, precomputed once per session).
+ *
+ * 2. **ObjC call → Swift method** — An ObjC caller writes
+ *    `[swiftThing fooWithBar:42]`. Tree-sitter-objc parses this as a
+ *    message_expression with selector `fooWithBar:` (after the multi-
+ *    keyword fix in this branch). The name-matcher tries to find a node
+ *    named `fooWithBar:` — no Swift node has colons in its name, so it
+ *    fails. We catch it: from the ObjC selector, derive candidate Swift
+ *    base names (`['fooWithBar', 'foo']`), and look up Swift methods
+ *    named those.
+ *
+ * **Provenance:** every edge produced here is recorded as a framework-
+ * resolved reference (`resolvedBy: 'framework'`) with `confidence: 0.7`
+ * (matches the django ORM dynamic-dispatch precedent — not exact, but
+ * deterministic from the bridging rule).
+ */
+import { FrameworkResolver, ResolutionContext, ResolvedRef, UnresolvedRef } from '../types';
+import type { Node } from '../../types';
+import {
+  swiftBaseNamesForObjcSelector,
+  isObjcExposed,
+} from '../swift-objc-bridge';
+
+/**
+ * Memoized "Swift base name → ObjC method nodes" map.
+ *
+ * Built lazily on first `resolve()` per resolver instance — the resolver is
+ * recreated when the index is rebuilt, so this naturally invalidates with
+ * the graph. Keyed by ResolutionContext identity so multiple projects sharing
+ * a process (the daemon) don't bleed maps between them.
+ */
+const objcByCandidateSwiftBase: WeakMap<
+  ResolutionContext,
+  Map<string, Node[]>
+> = new WeakMap();
+
+/**
+ * Build the reverse-bridge map: for every ObjC method node in the graph,
+ * compute the Swift base names that would auto-bridge to its selector and
+ * record the node under each.
+ *
+ * Runs once per resolver lifetime; the cost scales linearly with the count
+ * of ObjC method nodes. On Wikipedia-iOS (~2500 files, ~25k ObjC methods)
+ * this is a few hundred ms — much cheaper than re-parsing source on each
+ * unresolved ref.
+ */
+/**
+ * Names that are too generic to bridge with any precision. These are common
+ * Cocoa / NSObject conventions that almost every ObjC class implements; if a
+ * Swift caller writes `init()` or `description`, mapping it to an arbitrary
+ * project-local ObjC method of the same name produces noise, not signal.
+ *
+ * Critically, refs of these names virtually always resolve via the regular
+ * name-matcher (every project has many `init` nodes) — skipping them here
+ * just keeps the bridge from competing with name-match on already-handled
+ * refs.
+ */
+const GENERIC_NAMES = new Set([
+  'init',
+  'description',
+  'debugDescription',
+  'hash',
+  'isEqual',
+  'isEqualTo',
+  'copy',
+  'mutableCopy',
+  'class',
+  'self',
+  'count',
+  'length',
+  'value',
+  'name',
+  'data',
+  'string',
+  'object',
+  'add',
+  'remove',
+  'update',
+  'load',
+  'save',
+  'reload',
+  'cancel',
+  'start',
+  'stop',
+  'pause',
+  'resume',
+  'close',
+  'open',
+  'show',
+  'hide',
+  'toString',
+  'dealloc',
+  'release',
+  'retain',
+  'autorelease',
+]);
+
+function buildObjcMap(context: ResolutionContext): Map<string, Node[]> {
+  const cached = objcByCandidateSwiftBase.get(context);
+  if (cached) return cached;
+
+  const map = new Map<string, Node[]>();
+  const objcMethods = context
+    .getNodesByKind('method')
+    .filter((n) => n.language === 'objc');
+  for (const node of objcMethods) {
+    const candidates = swiftBaseNamesForObjcSelector(node.name);
+    for (const c of candidates) {
+      // Skip the trivial case where the Swift base name equals the ObjC
+      // method name verbatim (no colons) — the regular name-matcher
+      // already handles that and our map would just duplicate the work.
+      if (c === node.name && !node.name.includes(':')) continue;
+      // Skip generic Cocoa names (init, description, etc.) — they would
+      // false-positive against any project-local ObjC method of the same
+      // name. The regular name-matcher handles them.
+      if (GENERIC_NAMES.has(c)) continue;
+      const arr = map.get(c);
+      if (arr) arr.push(node);
+      else map.set(c, [node]);
+    }
+  }
+  objcByCandidateSwiftBase.set(context, map);
+  return map;
+}
+
+/**
+ * Window of source text around a Swift declaration used by `isObjcExposed`
+ * to spot `@objc` / `@nonobjc` annotations. Read line above + the
+ * declaration line — Swift attributes typically sit on the preceding line
+ * (`@objc` on a line of its own) or inline.
+ */
+const SOURCE_PROBE_LINES = 3;
+
+/**
+ * Read a small window of source ending at `node.startLine`, used to
+ * inspect Swift attribute annotations attached to a declaration. Returns
+ * an empty string if the source can't be read.
+ */
+function declarationSourceWindow(node: Node, context: ResolutionContext): string {
+  const content = context.readFile(node.filePath);
+  if (!content) return '';
+  const lines = content.split(/\r?\n/);
+  const startIdx = Math.max(0, node.startLine - 1 - SOURCE_PROBE_LINES);
+  const endIdx = Math.min(lines.length, node.startLine);
+  return lines.slice(startIdx, endIdx).join('\n');
+}
+
+/**
+ * Try to resolve a Swift caller's bare reference to an ObjC implementation.
+ *
+ * Strategy: look up the ObjC reverse-bridge map for nodes whose Swift base
+ * name would match. Return the first match (matches the existing
+ * single-target resolution contract).
+ */
+function resolveSwiftCallToObjc(
+  ref: UnresolvedRef,
+  context: ResolutionContext
+): ResolvedRef | null {
+  // Swift call sites of `obj.foo(bar:)` reach the resolver as either bare
+  // name `foo` (tree-sitter-swift) or qualified `obj.foo` — strip prefix.
+  const rawName = ref.referenceName.includes('.')
+    ? ref.referenceName.slice(ref.referenceName.lastIndexOf('.') + 1)
+    : ref.referenceName;
+
+  const map = buildObjcMap(context);
+  const candidates = map.get(rawName);
+  if (!candidates || candidates.length === 0) return null;
+
+  // Prefer ObjC methods whose corresponding Swift declaration isn't itself
+  // present (so we don't wrongly redirect a Swift call to ObjC when a Swift
+  // method of the same name is the real target — that's the in-language case
+  // and should already be resolved by the name-matcher). Since this resolver
+  // runs AFTER exact-match, any matching Swift node would already have won;
+  // so a candidate reaching us is a legitimate cross-language hit.
+  const target = candidates[0];
+  if (!target) return null;
+  return {
+    original: ref,
+    targetNodeId: target.id,
+    confidence: 0.6,
+    resolvedBy: 'framework',
+  };
+}
+
+/**
+ * Try to resolve an ObjC caller's selector reference to a Swift `@objc`
+ * implementation.
+ *
+ * Strategy: derive candidate Swift base names from the selector via
+ * `swiftBaseNamesForObjcSelector`. For each, look up Swift methods named
+ * that and verify with a source-window check that the declaration is
+ * `@objc`-exposed (filters out false matches where a Swift function
+ * happens to share the name but isn't bridged).
+ */
+function resolveObjcCallToSwift(
+  ref: UnresolvedRef,
+  context: ResolutionContext
+): ResolvedRef | null {
+  // ObjC call sites get receiver-prefixed when the receiver isn't self/super
+  // (see tree-sitter.ts message_expression handling): `[obj foo:bar:]`
+  // becomes `obj.foo:bar:`. Strip the receiver prefix to recover the raw
+  // selector for the bridge math.
+  const rawSelector = ref.referenceName.includes('.')
+    ? ref.referenceName.slice(ref.referenceName.lastIndexOf('.') + 1)
+    : ref.referenceName;
+
+  // Bridge math only applies to selector-shape names (contain `:`).
+  if (!rawSelector.includes(':')) return null;
+
+  const candidates = swiftBaseNamesForObjcSelector(rawSelector);
+  for (const candidate of candidates) {
+    const matches = context
+      .getNodesByName(candidate)
+      .filter((n) => n.language === 'swift' && (n.kind === 'method' || n.kind === 'function'));
+    for (const match of matches) {
+      const window = declarationSourceWindow(match, context);
+      if (isObjcExposed(window)) {
+        return {
+          original: ref,
+          targetNodeId: match.id,
+          confidence: 0.6,
+          resolvedBy: 'framework',
+        };
+      }
+    }
+  }
+  return null;
+}
+
+export const swiftObjcBridgeResolver: FrameworkResolver = {
+  name: 'swift-objc-bridge',
+  // Applies to both languages — bridging crosses the boundary.
+  languages: ['swift', 'objc'],
+
+  /**
+   * Detect: this resolver is relevant when the project has both Swift and
+   * Objective-C source. Either-side-only projects don't need bridging
+   * (and the empty reverse-map would be a no-op anyway).
+   */
+  detect(context) {
+    const files = context.getAllFiles();
+    let hasSwift = false;
+    let hasObjc = false;
+    for (const f of files) {
+      if (f.endsWith('.swift')) hasSwift = true;
+      else if (f.endsWith('.m') || f.endsWith('.mm')) hasObjc = true;
+      if (hasSwift && hasObjc) return true;
+    }
+    return false;
+  },
+
+  /**
+   * Let selector-shape references (anything containing a `:`) through the
+   * resolver's name-exists pre-filter — no Swift node has a colon in its
+   * name, so without this opt-in those refs would be dropped before
+   * `resolve()` sees them. Also opt-in `setX:`-style names that aren't
+   * otherwise declared symbols, in case the Swift side is a property.
+   */
+  claimsReference(name) {
+    if (name.includes(':')) return true;
+    // Bare names without colons are handled by the regular name-exists
+    // pre-filter — no need to opt them in here.
+    return false;
+  },
+
+  /**
+   * Route based on which language the caller is in. The two directions are
+   * symmetric in shape but very different in implementation (forward
+   * direction uses the precomputed reverse-bridge map; reverse direction
+   * uses the deterministic name-derivation).
+   */
+  resolve(ref, context) {
+    if (ref.language === 'swift') {
+      return resolveSwiftCallToObjc(ref, context);
+    }
+    if (ref.language === 'objc') {
+      return resolveObjcCallToSwift(ref, context);
+    }
+    return null;
+  },
+};
diff --git a/src/resolution/frameworks/swift.ts b/src/resolution/frameworks/swift.ts
index 461fe94d7..0dd1513aa 100644
--- a/src/resolution/frameworks/swift.ts
+++ b/src/resolution/frameworks/swift.ts
@@ -341,13 +341,39 @@ export const vaporResolver: FrameworkResolver = {
     const now = Date.now();
     const safe = stripCommentsForRegex(content, 'swift');
 
-    // Vapor: (app|router|routes).METHOD("path", use: handler)
-    const routeRegex = /\b(?:app|router|routes)\.(get|post|put|patch|delete)\s*\(\s*"([^"]+)"\s*,\s*use:\s*([A-Za-z_][A-Za-z0-9_.]*)/g;
+    // Build a group-var → path-prefix map first. Modern Vapor routes live on a
+    // grouped builder (`let todos = routes.grouped("todos"); todos.get(use: index)`
+    // or `routes.group("todos") { todos in todos.get(use: index) }`), so the path
+    // comes from the group, not the call. Roots (app/routes/router) have no prefix.
+    const groupPrefix = new Map<string, string>();
+    const segJoin = (existing: string, segsStr: string): string => {
+      const segs = (segsStr.match(/"([^"]*)"/g) || []).map((s) => s.slice(1, -1));
+      return existing + segs.map((s) => '/' + s).join('');
+    };
+    let gm: RegExpExecArray | null;
+    // let X = Y.grouped("a", "b")
+    const groupedRegex = /\blet\s+(\w+)\s*=\s*(\w+)\.grouped\s*\(([^)]*)\)/g;
+    while ((gm = groupedRegex.exec(safe)) !== null) {
+      groupPrefix.set(gm[1]!, segJoin(groupPrefix.get(gm[2]!) ?? '', gm[3]!));
+    }
+    // Y.group("a") { X in ... }
+    const groupClosureRegex = /\b(\w+)\.group\s*\(([^)]*)\)\s*\{\s*(\w+)\s+in/g;
+    while ((gm = groupClosureRegex.exec(safe)) !== null) {
+      groupPrefix.set(gm[3]!, segJoin(groupPrefix.get(gm[1]!) ?? '', gm[2]!));
+    }
+
+    // Vapor: <builder>.METHOD([path segs,] use: handler). Any receiver (app,
+    // routes, or a grouped var); path segments optional and may be non-string
+    // (`BlogUser.parameter`, `:id`, a path constant) so accept any comma-separated
+    // args before `use:` — the label keeps only the string parts. `use:`
+    // discriminates a real route from Environment.get("X")/req.parameters.get("X").
+    const routeRegex = /\b(\w+)\.(get|post|put|patch|delete|head|options)\s*\(\s*((?:[^,()]+,\s*)*)use:\s*([A-Za-z_][\w.]*)/g;
     let match: RegExpExecArray | null;
     while ((match = routeRegex.exec(safe)) !== null) {
-      const [, method, routePath, handlerExpr] = match;
+      const [, receiver, method, segsStr, handlerExpr] = match;
       const line = safe.slice(0, match.index).split('\n').length;
       const upper = method!.toUpperCase();
+      const routePath = (groupPrefix.get(receiver!) ?? '') + segJoin('', segsStr!) || '/';
 
       const routeNode: Node = {
         id: `route:${filePath}:${line}:${upper}:${routePath}`,
@@ -364,9 +390,8 @@ export const vaporResolver: FrameworkResolver = {
       };
       nodes.push(routeNode);
 
-      // Last segment of dotted path (e.g. UserController.list -> list)
-      const parts = handlerExpr!.split('.');
-      const handlerName = parts[parts.length - 1];
+      // Last segment of a dotted handler (self.list / UserController.list -> list)
+      const handlerName = handlerExpr!.split('.').pop();
       if (handlerName) {
         references.push({
           fromNodeId: routeNode.id,
diff --git a/src/resolution/frameworks/vue.ts b/src/resolution/frameworks/vue.ts
index 14b7760bd..c830885be 100644
--- a/src/resolution/frameworks/vue.ts
+++ b/src/resolution/frameworks/vue.ts
@@ -279,39 +279,32 @@ function resolveComponent(
   fromFile: string,
   context: ResolutionContext
 ): string | null {
-  const allFiles = context.getAllFiles();
-  const vueFiles = allFiles.filter((f) => f.endsWith('.vue'));
-
-  // Check for exact name match (Button -> Button.vue)
-  for (const file of vueFiles) {
+  // Collect ALL basename matches first. The previous version returned the
+  // FIRST `Button.vue` found anywhere in the tree (its same-directory pass
+  // below was unreachable), so a multi-app monorepo with one `Button.vue`
+  // per app resolved to an arbitrary one (#764).
+  const matches: string[] = [];
+  for (const file of context.getAllFiles()) {
+    if (!file.endsWith('.vue')) continue;
     const fileName = file.split(/[/\\]/).pop() || '';
-    const componentName = fileName.replace(/\.vue$/, '');
-    if (componentName === name) {
-      const nodes = context.getNodesInFile(file);
-      const component = nodes.find((n) => n.kind === 'component' && n.name === name);
-      if (component) {
-        return component.id;
-      }
-    }
+    if (fileName.replace(/\.vue$/, '') === name) matches.push(file);
   }
+  if (matches.length === 0) return null;
+
+  const componentIn = (file: string): string | null => {
+    const nodes = context.getNodesInFile(file);
+    const component = nodes.find((n) => n.kind === 'component' && n.name === name);
+    return component ? component.id : null;
+  };
 
-  // Check same directory first for better specificity
+  // Same directory first for specificity
   const fromDir = fromFile.substring(0, fromFile.lastIndexOf('/'));
-  for (const file of vueFiles) {
-    if (file.startsWith(fromDir)) {
-      const fileName = file.split(/[/\\]/).pop() || '';
-      const componentName = fileName.replace(/\.vue$/, '');
-      if (componentName === name) {
-        const nodes = context.getNodesInFile(file);
-        const component = nodes.find((n) => n.kind === 'component');
-        if (component) {
-          return component.id;
-        }
-      }
-    }
-  }
+  const sameDir = matches.filter((f) => f.startsWith(fromDir));
+  if (sameDir.length > 0) return componentIn(sameDir[0]!);
 
-  return null;
+  // No positional signal: only an UNAMBIGUOUS basename may resolve;
+  // ambiguity falls through to the name-matcher's proximity scoring.
+  return matches.length === 1 ? componentIn(matches[0]!) : null;
 }
 
 /**
diff --git a/src/resolution/go-module.ts b/src/resolution/go-module.ts
new file mode 100644
index 000000000..03f6b9b23
--- /dev/null
+++ b/src/resolution/go-module.ts
@@ -0,0 +1,47 @@
+/**
+ * Go module path detection.
+ *
+ * A Go monorepo's cross-package calls (`pkga.FuncX(...)`) only resolve when
+ * the resolver knows the project's module path (the `module ...` directive
+ * in `go.mod`). Without it, `isExternalImport` treats every in-module import
+ * — `github.com/example/myproject/pkga` — as a third-party package, so
+ * resolution falls through to name-matching with path proximity and returns
+ * a tiny fraction of the real call sites. See issue #388.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface GoModule {
+  /** The module path declared in `go.mod`, e.g. `github.com/example/myproject` */
+  modulePath: string;
+  /** Absolute path to the directory containing the `go.mod` file. */
+  rootDir: string;
+}
+
+/**
+ * Read the `go.mod` file at the project root and extract the module path.
+ * Returns `null` if no `go.mod` exists or it has no `module` directive.
+ *
+ * Limitation: only the project-root `go.mod` is read. Nested `go.mod` files
+ * (Go workspaces, monorepos with multiple modules) are not yet resolved —
+ * a follow-up if a real repro shows up.
+ */
+export function loadGoModule(projectRoot: string): GoModule | null {
+  const goModPath = path.join(projectRoot, 'go.mod');
+  let content: string;
+  try {
+    content = fs.readFileSync(goModPath, 'utf-8');
+  } catch {
+    return null;
+  }
+  // `module <path>` is the first non-comment directive in any valid go.mod.
+  // Strip line comments so a `// module foo` doesn't false-match.
+  const stripped = content.replace(/\/\/[^\n]*/g, '');
+  const match = stripped.match(/^\s*module\s+(\S+)\s*$/m);
+  if (!match) return null;
+  // Strip optional quoting around the module path.
+  const modulePath = match[1]!.replace(/^["']|["']$/g, '');
+  if (!modulePath) return null;
+  return { modulePath, rootDir: projectRoot };
+}
diff --git a/src/resolution/import-resolver.ts b/src/resolution/import-resolver.ts
index 5b41a57db..716e10880 100644
--- a/src/resolution/import-resolver.ts
+++ b/src/resolution/import-resolver.ts
@@ -4,10 +4,12 @@
  * Resolves import paths to actual files and symbols.
  */
 
+import * as fs from 'fs';
 import * as path from 'path';
 import { Language, Node } from '../types';
 import { UnresolvedRef, ResolvedRef, ResolutionContext, ImportMapping, ReExport } from './types';
 import { applyAliases } from './path-aliases';
+import { resolveWorkspaceImport } from './workspace-packages';
 
 /**
  * Extension resolution order by language
@@ -17,13 +19,22 @@ const EXTENSION_RESOLUTION: Record<string, string[]> = {
   javascript: ['.js', '.jsx', '.mjs', '.cjs', '/index.js', '/index.jsx'],
   tsx: ['.tsx', '.ts', '.d.ts', '.js', '.jsx', '/index.tsx', '/index.ts', '/index.js'],
   jsx: ['.jsx', '.js', '/index.jsx', '/index.js'],
+  // SFC consumers import plain TS/JS, sibling components, and barrels
+  // (`./lib` → `./lib/index.ts`). Without a list, relative imports from a
+  // `.svelte`/`.vue` file resolve to nothing, so barrel callers vanish (#629).
+  svelte: ['.ts', '.js', '.svelte', '.tsx', '.jsx', '/index.ts', '/index.js', '/index.svelte'],
+  vue: ['.ts', '.js', '.vue', '.tsx', '.jsx', '/index.ts', '/index.js', '/index.vue'],
+  astro: ['.ts', '.js', '.astro', '.tsx', '.jsx', '/index.ts', '/index.js', '/index.astro'],
   python: ['.py', '/__init__.py'],
   go: ['.go'],
   rust: ['.rs', '/mod.rs'],
   java: ['.java'],
+  c: ['.h', '.c'],
+  cpp: ['.h', '.hpp', '.hxx', '.cpp', '.cc', '.cxx'],
   csharp: ['.cs'],
   php: ['.php'],
   ruby: ['.rb'],
+  objc: ['.h', '.m', '.mm'],
 };
 
 /**
@@ -52,9 +63,56 @@ export function resolveImportPath(
   }
 
   // Handle absolute/aliased imports (like @/ or src/)
-  return resolveAliasedImport(importPath, projectRoot, language, context);
+  const aliased = resolveAliasedImport(importPath, projectRoot, language, context);
+  if (aliased) return aliased;
+
+  // C/C++ include directory search: when neither relative nor aliased
+  // resolution found a match, search -I directories from
+  // compile_commands.json or heuristic probing.
+  if (language === 'c' || language === 'cpp') {
+    return resolveCppIncludePath(importPath, language, context);
+  }
+
+  return null;
 }
 
+/**
+ * C and C++ standard library header names (without delimiters).
+ * Used by isExternalImport to filter system includes from resolution.
+ */
+const C_CPP_STDLIB_HEADERS = new Set([
+  // C standard library headers
+  'assert.h', 'complex.h', 'ctype.h', 'errno.h', 'fenv.h', 'float.h',
+  'inttypes.h', 'iso646.h', 'limits.h', 'locale.h', 'math.h', 'setjmp.h',
+  'signal.h', 'stdalign.h', 'stdarg.h', 'stdatomic.h', 'stdbool.h',
+  'stddef.h', 'stdint.h', 'stdio.h', 'stdlib.h', 'stdnoreturn.h',
+  'string.h', 'tgmath.h', 'threads.h', 'time.h', 'uchar.h', 'wchar.h',
+  'wctype.h',
+  // C++ C-library wrappers (cname form)
+  'cassert', 'ccomplex', 'cctype', 'cerrno', 'cfenv', 'cfloat',
+  'cinttypes', 'ciso646', 'climits', 'clocale', 'cmath', 'csetjmp',
+  'csignal', 'cstdalign', 'cstdarg', 'cstdbool', 'cstddef', 'cstdint',
+  'cstdio', 'cstdlib', 'cstring', 'ctgmath', 'ctime', 'cuchar',
+  'cwchar', 'cwctype',
+  // C++ STL headers
+  'algorithm', 'any', 'array', 'atomic', 'barrier', 'bit', 'bitset',
+  'charconv', 'chrono', 'codecvt', 'compare', 'complex', 'concepts',
+  'condition_variable', 'coroutine', 'deque', 'exception', 'execution',
+  'expected', 'filesystem', 'format', 'forward_list', 'fstream',
+  'functional', 'future', 'generator', 'initializer_list', 'iomanip',
+  'ios', 'iosfwd', 'iostream', 'istream', 'iterator', 'latch',
+  'limits', 'list', 'locale', 'map', 'mdspan', 'memory', 'memory_resource',
+  'mutex', 'new', 'numbers', 'numeric', 'optional', 'ostream', 'print',
+  'queue', 'random', 'ranges', 'ratio', 'regex', 'scoped_allocator',
+  'semaphore', 'set', 'shared_mutex', 'source_location', 'span',
+  'spanstream', 'sstream', 'stack', 'stacktrace', 'stdexcept',
+  'stdfloat', 'stop_token', 'streambuf', 'string', 'string_view',
+  'strstream', 'syncstream', 'system_error', 'thread', 'tuple',
+  'type_traits', 'typeindex', 'typeinfo', 'unordered_map',
+  'unordered_set', 'utility', 'valarray', 'variant', 'vector',
+  'version',
+]);
+
 /**
  * Check if an import is external (npm package, etc.)
  *
@@ -73,6 +131,15 @@ function isExternalImport(
     return false;
   }
 
+  // Workspace-member imports (`@scope/ui`, `@scope/ui/widgets`) are LOCAL to
+  // a monorepo even though they look like bare npm specifiers. Consult the
+  // workspace map first so they aren't misclassified as external (#629). The
+  // map is null for single-package repos, so this is a no-op there.
+  const workspaces = context?.getWorkspacePackages?.();
+  if (workspaces && resolveWorkspaceImport(importPath, workspaces)) {
+    return false;
+  }
+
   // Common external patterns
   if (language === 'typescript' || language === 'javascript' || language === 'tsx' || language === 'jsx') {
     // Node built-ins
@@ -102,10 +169,34 @@ function isExternalImport(
   }
 
   if (language === 'go') {
-    // Standard library or external packages
-    if (!importPath.startsWith('.') && !importPath.includes('/internal/')) {
-      return true;
+    // Relative imports (rare in idiomatic Go but the grammar allows them).
+    if (importPath.startsWith('.')) {
+      return false;
     }
+    // In-module imports look like `<module-path>/sub/pkg` — local to
+    // this project. Without the module-path check we'd flag every
+    // cross-package call in a Go monorepo as external (issue #388).
+    const mod = context?.getGoModule?.();
+    if (mod && (importPath === mod.modulePath || importPath.startsWith(mod.modulePath + '/'))) {
+      return false;
+    }
+    // `internal/` packages stay local even when go.mod is missing —
+    // preserves the pre-#388 escape hatch for repos without a parsed module path.
+    if (importPath.includes('/internal/')) {
+      return false;
+    }
+    // Anything else is the Go standard library or a third-party module.
+    return true;
+  }
+
+  if (language === 'c' || language === 'cpp') {
+    // C/C++ standard library headers — both C-style (<stdio.h>) and
+    // C++-style (<cstdio>, <vector>) forms. Checked against the import
+    // path (which the extractor strips of <> or "" delimiters).
+    if (C_CPP_STDLIB_HEADERS.has(importPath)) return true;
+    // C++ headers without .h extension (e.g. "vector", "string")
+    const withoutExt = importPath.replace(/\.h$/, '');
+    if (C_CPP_STDLIB_HEADERS.has(withoutExt)) return true;
   }
 
   return false;
@@ -123,6 +214,24 @@ function resolveRelativeImport(
   const projectRoot = context.getProjectRoot();
   const extensions = EXTENSION_RESOLUTION[language] || [];
 
+  // Python dotted-relative imports (`from .certs import x`, `from ..pkg.mod
+  // import y`): leading dots are PACKAGE levels (1 = current package), and the
+  // remainder is a dotted submodule path. `path.resolve(dir, '.certs')` would
+  // treat `.certs` as a literal hidden filename, so translate the Python form
+  // to a real filesystem-relative path before resolving.
+  if (language === 'python' && importPath.startsWith('.')) {
+    const dots = importPath.length - importPath.replace(/^\.+/, '').length;
+    const up = '../'.repeat(Math.max(0, dots - 1));    // 1 dot = current dir
+    const rest = importPath.slice(dots).replace(/\./g, '/'); // 'sub.mod' -> 'sub/mod'
+    const pyBase = path.resolve(fromDir, up + rest);
+    const pyRel = path.relative(projectRoot, pyBase).replace(/\\/g, '/');
+    for (const ext of extensions) {
+      if (context.fileExists(pyRel + ext)) return pyRel + ext;
+    }
+    if (pyRel && context.fileExists(pyRel)) return pyRel;
+    return null;
+  }
+
   // Try the path as-is first
   const basePath = path.resolve(fromDir, importPath);
   const relativePath = path.relative(projectRoot, basePath).replace(/\\/g, '/');
@@ -180,6 +289,18 @@ function resolveAliasedImport(
     }
   }
 
+  // 1.5 Workspace packages (`@scope/ui/widgets` → `packages/ui/widgets`).
+  //     Resolves a monorepo member import to the member's directory; the
+  //     extension/index permutations below then find its barrel (#629).
+  const workspaces = context.getWorkspacePackages?.();
+  if (workspaces) {
+    const base = resolveWorkspaceImport(importPath, workspaces);
+    if (base) {
+      const hit = tryWithExt(base);
+      if (hit) return hit;
+    }
+  }
+
   // 2. Hard-coded fallback list. Kept for projects that use these
   //    conventional aliases without declaring them in tsconfig.
   const fallbackAliases: Record<string, string> = {
@@ -201,6 +322,255 @@ function resolveAliasedImport(
   return tryWithExt(importPath);
 }
 
+/**
+ * C/C++ include directory cache (keyed by project root).
+ * Loaded once per resolver instance, shared across calls.
+ */
+const cppIncludeDirCache = new Map<string, string[]>();
+
+/**
+ * Clear the C/C++ include directory cache (call between indexing runs)
+ */
+export function clearCppIncludeDirCache(): void {
+  cppIncludeDirCache.clear();
+}
+
+/**
+ * Discover C/C++ include search directories for a project.
+ *
+ * Strategy:
+ * 1. Look for compile_commands.json (Clang compilation database) in the
+ *    project root and common build subdirectories. Parse -I and -isystem
+ *    flags from compiler commands.
+ * 2. If no compilation database is found, probe for common convention
+ *    directories (include/, src/, lib/, api/) and top-level directories
+ *    containing .h/.hpp files.
+ *
+ * Returns paths relative to projectRoot.
+ */
+export function loadCppIncludeDirs(projectRoot: string): string[] {
+  const cached = cppIncludeDirCache.get(projectRoot);
+  if (cached !== undefined) return cached;
+
+  const dirs = loadCppIncludeDirsFromCompileDB(projectRoot)
+    || loadCppIncludeDirsHeuristic(projectRoot);
+
+  cppIncludeDirCache.set(projectRoot, dirs);
+  return dirs;
+}
+
+/**
+ * Try to load include directories from compile_commands.json.
+ * Returns null if no compilation database is found (so the heuristic
+ * fallback can run). Returns an array (possibly empty) otherwise.
+ */
+function loadCppIncludeDirsFromCompileDB(projectRoot: string): string[] | null {
+  const candidates = [
+    path.join(projectRoot, 'compile_commands.json'),
+    path.join(projectRoot, 'build', 'compile_commands.json'),
+    path.join(projectRoot, 'cmake-build-debug', 'compile_commands.json'),
+    path.join(projectRoot, 'cmake-build-release', 'compile_commands.json'),
+    path.join(projectRoot, 'out', 'compile_commands.json'),
+  ];
+
+  let dbPath: string | undefined;
+  for (const c of candidates) {
+    try {
+      if (fs.existsSync(c)) {
+        dbPath = c;
+        break;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  if (!dbPath) return null;
+
+  try {
+    const content = fs.readFileSync(dbPath, 'utf-8');
+    const entries = JSON.parse(content) as Array<{
+      directory: string;
+      command?: string;
+      arguments?: string[];
+    }>;
+    if (!Array.isArray(entries)) return null;
+
+    const dirSet = new Set<string>();
+    for (const entry of entries) {
+      const dir = entry.directory || projectRoot;
+      const args = entry.arguments || (entry.command ? shlexSplit(entry.command) : []);
+      for (let i = 0; i < args.length; i++) {
+        const arg = args[i]!;
+        let includeDir: string | undefined;
+        // -I<dir> (no space)
+        if (arg.startsWith('-I') && arg.length > 2) {
+          includeDir = arg.substring(2);
+        }
+        // -isystem <dir> (space-separated)
+        else if ((arg === '-isystem' || arg === '-I') && i + 1 < args.length) {
+          includeDir = args[i + 1];
+          i++; // skip next arg
+        }
+        if (includeDir) {
+          // Normalize: resolve relative to the compilation directory
+          const absPath = path.isAbsolute(includeDir)
+            ? includeDir
+            : path.resolve(dir, includeDir);
+          const relPath = path.relative(projectRoot, absPath).replace(/\\/g, '/');
+          // Skip system directories and paths outside the project
+          // (relative paths starting with .. or absolute paths like
+          // /usr/include or C:\usr on Windows)
+          if (!relPath.startsWith('..') && relPath.length > 0 && !path.isAbsolute(relPath)) {
+            dirSet.add(relPath);
+          }
+        }
+      }
+    }
+    return Array.from(dirSet);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Minimal shlex-style split for compiler command strings.
+ * Handles double-quoted and single-quoted arguments.
+ */
+function shlexSplit(cmd: string): string[] {
+  const result: string[] = [];
+  let i = 0;
+  while (i < cmd.length) {
+    // Skip whitespace
+    while (i < cmd.length && /\s/.test(cmd[i]!)) i++;
+    if (i >= cmd.length) break;
+    const ch = cmd[i]!;
+    if (ch === '"') {
+      i++;
+      let arg = '';
+      while (i < cmd.length && cmd[i] !== '"') {
+        if (cmd[i] === '\\' && i + 1 < cmd.length) { i++; arg += cmd[i]; }
+        else { arg += cmd[i]; }
+        i++;
+      }
+      i++; // closing quote
+      result.push(arg);
+    } else if (ch === "'") {
+      i++;
+      let arg = '';
+      while (i < cmd.length && cmd[i] !== "'") { arg += cmd[i]; i++; }
+      i++; // closing quote
+      result.push(arg);
+    } else {
+      let arg = '';
+      while (i < cmd.length && !/\s/.test(cmd[i]!)) { arg += cmd[i]; i++; }
+      result.push(arg);
+    }
+  }
+  return result;
+}
+
+/**
+ * Heuristic include directory discovery when no compile_commands.json exists.
+ * Checks common convention directories and scans top-level dirs for headers.
+ */
+function loadCppIncludeDirsHeuristic(projectRoot: string): string[] {
+  const dirs: string[] = [];
+  const conventionDirs = ['include', 'src', 'lib', 'api', 'inc'];
+
+  try {
+    const entries = fs.readdirSync(projectRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const name = entry.name;
+      // Convention directories
+      if (conventionDirs.includes(name.toLowerCase())) {
+        dirs.push(name);
+        continue;
+      }
+      // Any top-level directory containing .h or .hpp files
+      try {
+        const subFiles = fs.readdirSync(path.join(projectRoot, name));
+        if (subFiles.some(f => /\.(h|hpp|hxx|hh)$/i.test(f))) {
+          dirs.push(name);
+        }
+      } catch {
+        // ignore permission errors
+      }
+    }
+  } catch {
+    // ignore
+  }
+
+  return dirs;
+}
+
+/**
+ * Resolve a C/C++ include path by searching include directories.
+ * Called as a fallback after relative and aliased resolution fail.
+ */
+function resolveCppIncludePath(
+  importPath: string,
+  language: Language,
+  context: ResolutionContext
+): string | null {
+  const includeDirs = context.getCppIncludeDirs?.() ?? [];
+  const extensions = EXTENSION_RESOLUTION[language] ?? [];
+
+  for (const dir of includeDirs) {
+    const normalizedDir = dir.replace(/\\/g, '/');
+    for (const ext of extensions) {
+      const candidate = normalizedDir + '/' + importPath + ext;
+      if (context.fileExists(candidate)) return candidate;
+    }
+    // Try as-is (already has extension)
+    const candidate = normalizedDir + '/' + importPath;
+    if (context.fileExists(candidate)) return candidate;
+  }
+
+  return null;
+}
+
+/**
+ * Is this reference a PHP include/require PATH (vs a namespace `use` symbol)?
+ *
+ * include/require emit a file path ("lib.php", "inc/db.php", "../x.php"),
+ * whereas namespace use is an FQN (App\Foo\Bar) or a bare class symbol
+ * (Closure). PHP identifiers contain neither '/' nor '.', so a slash or dot
+ * marks a path-shaped include. Such references resolve to files only — never
+ * to a same-named symbol — so callers must not fall back to the name-matcher.
+ */
+export function isPhpIncludePathRef(ref: UnresolvedRef): boolean {
+  return (
+    ref.language === 'php' &&
+    ref.referenceKind === 'imports' &&
+    (ref.referenceName.includes('/') || ref.referenceName.includes('.'))
+  );
+}
+
+/**
+ * Resolve a PHP include/require path to a project-relative file path.
+ *
+ * PHP resolves includes relative to the including file's directory (the
+ * common case for procedural codebases); php.ini `include_path` is not
+ * modeled. Callers pass an already-extracted static literal path.
+ */
+function resolvePhpIncludePath(
+  includePath: string,
+  fromFile: string,
+  context: ResolutionContext
+): string | null {
+  const projectRoot = context.getProjectRoot();
+  const fromDir = path.dirname(path.join(projectRoot, fromFile));
+  const basePath = path.resolve(fromDir, includePath);
+  const relativePath = path.relative(projectRoot, basePath).replace(/\\/g, '/');
+  if (context.fileExists(relativePath)) return relativePath;
+  // The literal may omit the .php extension (e.g. include "config").
+  for (const ext of EXTENSION_RESOLUTION.php ?? []) {
+    if (context.fileExists(relativePath + ext)) return relativePath + ext;
+  }
+  return null;
+}
+
 /**
  * Extract import mappings from a file
  */
@@ -213,12 +583,27 @@ export function extractImportMappings(
 
   if (language === 'typescript' || language === 'javascript' || language === 'tsx' || language === 'jsx') {
     mappings.push(...extractJSImports(content));
+  } else if (language === 'svelte' || language === 'vue' || language === 'astro') {
+    // Svelte/Vue single-file components import via plain ES6 inside their
+    // `<script>` block (Astro: the `---` frontmatter). Without this, a
+    // `.svelte`/`.vue`/`.astro` consumer produces
+    // zero import mappings, so `resolveViaImport` can't run and a barrel
+    // import (`import { Foo } from './lib'`) falls back to name-matching —
+    // which silently fails whenever the re-export alias differs from the
+    // component's real name, yielding a false 0 callers (#629). The ES6
+    // import regex only matches `import … from '…'`, so running it over the
+    // whole SFC (markup + styles included) is safe.
+    mappings.push(...extractJSImports(content));
   } else if (language === 'python') {
     mappings.push(...extractPythonImports(content));
   } else if (language === 'go') {
     mappings.push(...extractGoImports(content));
+  } else if (language === 'java' || language === 'kotlin') {
+    mappings.push(...extractJavaImports(content));
   } else if (language === 'php') {
     mappings.push(...extractPHPImports(content));
+  } else if (language === 'c' || language === 'cpp') {
+    mappings.push(...extractCppImports(content));
   }
 
   return mappings;
@@ -426,6 +811,49 @@ function extractGoImports(content: string): ImportMapping[] {
   return mappings;
 }
 
+/**
+ * Extract Java / Kotlin import mappings.
+ *
+ * Java/Kotlin imports carry the full qualified name of the imported
+ * symbol — `import com.example.dao.converter.FooConverter;` — which is
+ * exactly the disambiguation signal we need when two packages both
+ * declare a `FooConverter`. Pre-#314 the resolver had no Java branch
+ * here at all, so this mapping was empty and cross-module name
+ * collisions were resolved by file-path proximity (often wrongly).
+ *
+ * `import static com.example.Foo.bar;` is parsed as a local-name `bar`
+ * pointing at FQN `com.example.Foo.bar` so static-method call sites
+ * (`bar(...)`) can resolve through the same import lookup.
+ */
+function extractJavaImports(content: string): ImportMapping[] {
+  const mappings: ImportMapping[] = [];
+  // Strip line and block comments so `// import foo;` doesn't false-match.
+  const stripped = content
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/[^\n]*/g, '');
+  // `import [static] <fqn>[.*];`
+  const re = /^\s*import\s+(static\s+)?([\w.]+(?:\.\*)?)\s*;/gm;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(stripped)) !== null) {
+    const fqn = match[2]!;
+    // `import com.example.*;` — wildcard. We can't materialize a single
+    // local name; skip and let name-matching handle members reachable
+    // through the wildcard. (Future enhancement: enumerate package files.)
+    if (fqn.endsWith('.*')) continue;
+    const parts = fqn.split('.');
+    const localName = parts[parts.length - 1];
+    if (!localName) continue;
+    mappings.push({
+      localName,
+      exportedName: localName,
+      source: fqn,
+      isDefault: false,
+      isNamespace: false,
+    });
+  }
+  return mappings;
+}
+
 /**
  * Extract PHP import mappings (use statements)
  */
@@ -451,6 +879,38 @@ function extractPHPImports(content: string): ImportMapping[] {
   return mappings;
 }
 
+/**
+ * Extract C/C++ import mappings from #include directives.
+ *
+ * #include brings all symbols from the included header into scope
+ * (namespace import), so each mapping uses isNamespace: true and
+ * exportedName: '*'. The localName is set to the header's basename
+ * without extension so that symbol references like `MyClass` can
+ * match against any include that might provide it.
+ */
+function extractCppImports(content: string): ImportMapping[] {
+  const mappings: ImportMapping[] = [];
+
+  // Match both #include <...> and #include "..."
+  const includeRegex = /^\s*#\s*include\s+[<"]([^>"]+)[>"]/gm;
+  let match;
+
+  while ((match = includeRegex.exec(content)) !== null) {
+    const modulePath = match[1]!;
+    // Basename without extension for localName matching
+    const basename = modulePath.split('/').pop()!.replace(/\.(h|hpp|hxx|hh|inl|ipp|cxx|cc|cpp)$/,'');
+    mappings.push({
+      localName: basename || modulePath,
+      exportedName: '*',
+      source: modulePath,
+      isDefault: false,
+      isNamespace: true,
+    });
+  }
+
+  return mappings;
+}
+
 // Cache import mappings per file to avoid re-reading and re-parsing
 const importMappingCache = new Map<string, ImportMapping[]>();
 
@@ -459,6 +919,7 @@ const importMappingCache = new Map<string, ImportMapping[]>();
  */
 export function clearImportMappingCache(): void {
   importMappingCache.clear();
+  cppIncludeDirCache.clear();
 }
 
 /**
@@ -585,16 +1046,230 @@ export function extractReExports(content: string, language: Language): ReExport[
 /**
  * Resolve a reference using import mappings
  */
+/**
+ * JVM (Java / Kotlin) imports use fully-qualified names (`import
+ * com.example.foo.Bar`) decoupled from filenames, so the JS/Python
+ * style filesystem path lookup misses them whenever the file isn't
+ * named after its primary symbol (Kotlin `Utils.kt` exporting `Bar`,
+ * top-level fns, extension fns). Resolve them through the
+ * `qualifiedName` index instead — populated by the package_header /
+ * package_declaration namespace wrappers in the extractor.
+ */
+export function resolveJvmImport(
+  ref: UnresolvedRef,
+  context: ResolutionContext
+): ResolvedRef | null {
+  if (ref.referenceKind !== 'imports') return null;
+  if (ref.language !== 'java' && ref.language !== 'kotlin') return null;
+
+  const fqn = ref.referenceName;
+  const lastDot = fqn.lastIndexOf('.');
+  if (lastDot <= 0) return null;
+  const pkg = fqn.substring(0, lastDot);
+  const sym = fqn.substring(lastDot + 1);
+  // Wildcard imports (`com.example.*`) deliberately punt to name-matcher.
+  if (sym === '*') return null;
+
+  const candidates = context.getNodesByQualifiedName(`${pkg}::${sym}`);
+  if (candidates.length === 0) return null;
+
+  // Kotlin Multiplatform: an `expect` declaration and its `actual`s share one
+  // FQN across source sets (commonMain / androidMain / appleMain). Taking the
+  // first candidate let a single platform `actual` absorb every common-side
+  // import, so the `expect` (the canonical API a commonMain file imports)
+  // looked unused. Prefer the candidate CLOSEST to the importing file by
+  // directory proximity — a commonMain import resolves to the commonMain
+  // declaration — with the `expect` side as a tiebreak.
+  const best = candidates.length === 1 ? candidates[0]! : pickClosestJvmCandidate(candidates, ref.filePath);
+  return {
+    original: ref,
+    targetNodeId: best.id,
+    confidence: 0.95,
+    resolvedBy: 'import',
+  };
+}
+
+/**
+ * Pick the same-FQN candidate closest to `fromPath` by shared directory
+ * prefix, preferring an `expect` declaration on a tie. Used to keep a Kotlin
+ * Multiplatform `expect`/`actual` import resolving within the importer's own
+ * source set instead of an arbitrary platform `actual`.
+ */
+function pickClosestJvmCandidate(candidates: Node[], fromPath: string): Node {
+  const fromDirs = fromPath.split('/').slice(0, -1);
+  const sharedPrefix = (p: string): number => {
+    const d = p.split('/').slice(0, -1);
+    let shared = 0;
+    for (let i = 0; i < Math.min(fromDirs.length, d.length); i++) {
+      if (fromDirs[i] === d[i]) shared++;
+      else break;
+    }
+    return shared;
+  };
+  const isExpect = (n: Node): boolean => Array.isArray(n.decorators) && n.decorators.includes('expect');
+  let best = candidates[0]!;
+  let bestProx = sharedPrefix(best.filePath);
+  for (let i = 1; i < candidates.length; i++) {
+    const c = candidates[i]!;
+    const prox = sharedPrefix(c.filePath);
+    if (prox > bestProx || (prox === bestProx && isExpect(c) && !isExpect(best))) {
+      best = c;
+      bestProx = prox;
+    }
+  }
+  return best;
+}
+
 export function resolveViaImport(
   ref: UnresolvedRef,
   context: ResolutionContext
 ): ResolvedRef | null {
+  // C/C++ #include references — resolve directly to the included file
+  // (file→file edge), bypassing symbol lookup. The extractor emits these
+  // with `referenceKind: 'imports'` and `referenceName: <include path>`
+  // (e.g. "uint256.h" or "common/args.h"). Without this branch the
+  // include-dir scan path inside resolveImportPath never produces an
+  // edge — resolveViaImport's symbol lookup below would search the
+  // resolved file for a symbol named like the file extension and fail.
+  if ((ref.language === 'c' || ref.language === 'cpp') && ref.referenceKind === 'imports') {
+    // C/C++ quoted includes (`#include "X.h"`) resolve relative to the
+    // INCLUDING file's own directory first (the C standard's quoted-include
+    // search order). Prefer a same-directory header over an -I directory or a
+    // same-named header on another platform (windows/code/RNCAsyncStorage.h vs
+    // apple/.../RNCAsyncStorage.h) — the include-dir heuristic below would
+    // otherwise pick an arbitrary same-named header, leaving the real local one
+    // with no dependents.
+    const slash = ref.filePath.lastIndexOf('/');
+    const fromDir = slash >= 0 ? ref.filePath.slice(0, slash) : '';
+    const siblingPath = path.posix.normalize(fromDir ? `${fromDir}/${ref.referenceName}` : ref.referenceName);
+    const siblingBase = siblingPath.split('/').pop()!;
+    const sibling = context
+      .getNodesByName(siblingBase)
+      .find((n) => n.kind === 'file' && n.filePath === siblingPath);
+    if (sibling) {
+      return { original: ref, targetNodeId: sibling.id, confidence: 0.92, resolvedBy: 'import' };
+    }
+    const resolvedPath = resolveImportPath(ref.referenceName, ref.filePath, ref.language, context);
+    if (!resolvedPath) return null;
+    const basename = resolvedPath.split('/').pop()!;
+    const fileNodes = context.getNodesByName(basename).filter((n) => n.kind === 'file');
+    const fileNode = fileNodes.find((n) => n.filePath === resolvedPath);
+    if (fileNode) {
+      return {
+        original: ref,
+        targetNodeId: fileNode.id,
+        confidence: 0.9,
+        resolvedBy: 'import',
+      };
+    }
+    return null;
+  }
+
+  // PHP include/require — resolve the static string path to a file→file
+  // edge, mirroring the C/C++ branch above. Distinguish include PATHS from
+  // namespace `use` symbols by shape: an include path contains a slash or a
+  // file extension ("lib.php", "inc/db.php", "../x.php"), whereas a namespace
+  // use is an FQN (App\Foo\Bar) or a bare class symbol (Closure) — PHP
+  // identifiers contain neither '/' nor '.'. Only path-shaped references are
+  // includes; symbol references fall through to the namespace resolution.
+  if (isPhpIncludePathRef(ref)) {
+    const resolvedPath = resolvePhpIncludePath(ref.referenceName, ref.filePath, context);
+    if (resolvedPath) {
+      const basename = resolvedPath.split('/').pop()!;
+      const fileNode = context
+        .getNodesByName(basename)
+        .find((n) => n.kind === 'file' && n.filePath === resolvedPath);
+      if (fileNode) {
+        return {
+          original: ref,
+          targetNodeId: fileNode.id,
+          confidence: 0.9,
+          resolvedBy: 'import',
+        };
+      }
+    }
+    // A path-shaped include that doesn't resolve to a known project file is a
+    // dead end. Return unresolved rather than falling through to the symbol
+    // name-matcher, which would mis-connect e.g. "inc/db.php" to an unrelated
+    // db.php elsewhere in the tree — a wrong edge is worse than a missing one.
+    return null;
+  }
+
   // Use cached import mappings (avoids re-reading and re-parsing per ref)
   const imports = context.getImportMappings(ref.filePath, ref.language);
   if (imports.length === 0 && !context.readFile(ref.filePath)) {
     return null;
   }
 
+  // Go cross-package calls: `pkga.FuncX(...)` extracts to referenceName
+  // `pkga.FuncX` and the import `github.com/example/myproject/pkga`
+  // maps to a *package directory* containing one or more .go files.
+  // The generic file-based lookup below can't follow that — issue #388.
+  if (ref.language === 'go') {
+    const goResult = resolveGoCrossPackageReference(ref, imports, context);
+    if (goResult) return goResult;
+  }
+
+  // Java / Kotlin: imports are FQNs (`import com.example.Foo;`) — no
+  // resolvable file path the JS/TS-style chain below could follow. Look
+  // up the symbol by name and filter to the candidate whose file path
+  // matches the imported FQN. This is the disambiguation signal that
+  // breaks the same-name class collision the path-proximity matcher
+  // can't resolve (issue #314).
+  if (ref.language === 'java' || ref.language === 'kotlin') {
+    const javaResult = resolveJavaImportedReference(ref, imports, context);
+    if (javaResult) return javaResult;
+  }
+
+  // Python qualified access through an imported MODULE: `certs.where()` after
+  // `from . import certs`, `mod.func()` after `import mod`. The receiver names a
+  // submodule (a file), not a symbol, so the generic symbol lookup below would
+  // search the *package* for `certs` instead of looking inside the module.
+  if (ref.language === 'python') {
+    const pyResult = resolvePythonModuleMember(ref, imports, context);
+    if (pyResult) return pyResult;
+    // Absolute dotted module import: `import conduit.apps.articles.signals`
+    // (the standard Django AppConfig.ready() signal-registration pattern, and
+    // any side-effect `import pkg.mod`). Map the dotted path to its file.
+    const pyModResult = resolvePythonAbsoluteModule(ref, context);
+    if (pyModResult) return pyModResult;
+  }
+
+  // Rust qualified path: resolve the module prefix of `crate::m::Item` /
+  // `self::sub::Item` / `super::m::func` to a file, then find the leaf symbol in
+  // it. Disambiguates common-name `pub use self::read::read` re-exports that
+  // name-matching would land on the wrong same-named symbol.
+  if (ref.language === 'rust' && ref.referenceName.includes('::')) {
+    const rustResult = resolveRustPathReference(ref, context);
+    if (rustResult) return rustResult;
+  }
+
+  // Lua / Luau `require(...)`: a dotted module path (`a.b.c` from
+  // `require("a.b.c")`) or an instance-path leaf (`Signal` from
+  // `require(script.Parent.Signal)`) — map it to a module file. There's no static
+  // import statement, so the generic path-matcher can't bridge the dot↔slash /
+  // leaf↔basename gap; resolve it explicitly to the module file.
+  if ((ref.language === 'lua' || ref.language === 'luau') && ref.referenceKind === 'imports') {
+    const luaResult = resolveLuaRequire(ref, context);
+    if (luaResult) return luaResult;
+  }
+
+  // Whole-module / namespace imports → link the importing file to the module
+  // file. Python `from . import certs` / `import mod`, and TS/JS `import * as ns
+  // from './x'` (so a namespace touched only via a value-member read still
+  // records the dependency). A named TS/JS import returns null here and falls
+  // through to symbol resolution below.
+  if (
+    ref.language === 'python' ||
+    ref.language === 'typescript' ||
+    ref.language === 'tsx' ||
+    ref.language === 'javascript' ||
+    ref.language === 'jsx'
+  ) {
+    const moduleFile = resolveModuleImportToFile(ref, imports, context);
+    if (moduleFile) return moduleFile;
+  }
+
   // Check if the reference name matches any import
   for (const imp of imports) {
     if (imp.localName === ref.referenceName || ref.referenceName.startsWith(imp.localName + '.')) {
@@ -635,6 +1310,490 @@ export function resolveViaImport(
   return null;
 }
 
+/**
+ * Resolve a Python qualified reference whose receiver is an imported MODULE:
+ * `certs.where()` after `from . import certs`, `mod.func()` after `import mod`
+ * or `from pkg import mod`. The receiver names a submodule (a file), not a
+ * symbol, so the generic symbol lookup in `resolveViaImport` can't follow it —
+ * it would search the *package* for `certs`/`mod` instead of looking inside the
+ * module. This is the Python half of the cross-package qualified-call problem
+ * (cf. `resolveGoCrossPackageReference` for Go's `pkg.Func`, issue #388).
+ *
+ * Builds the module's dotted import path from the binding — `from . import
+ * certs` → `.certs`; `from pkg import mod` → `pkg.mod`; `import mod` → `mod` —
+ * resolves it to the module file, and finds the member defined there. Returns
+ * null when no module file exists at that path, so attribute access on an
+ * imported *value* (`helper.attr` where `helper` is a function) falls through
+ * to the other strategies untouched.
+ */
+function resolvePythonModuleMember(
+  ref: UnresolvedRef,
+  imports: ImportMapping[],
+  context: ResolutionContext
+): ResolvedRef | null {
+  const dotIdx = ref.referenceName.indexOf('.');
+  if (dotIdx <= 0) return null;
+  const receiver = ref.referenceName.substring(0, dotIdx);
+  // The immediate member of the module (first segment after the receiver).
+  const member = ref.referenceName.substring(dotIdx + 1).split('.')[0];
+  if (!member) return null;
+
+  for (const imp of imports) {
+    if (imp.localName !== receiver) continue;
+
+    // `import mod` / `import numpy as np` bind the module at `source` itself;
+    // `from . import certs` / `from pkg import mod` bind a SUBMODULE whose
+    // dotted path is the source joined with the imported name.
+    const modulePath = imp.isNamespace
+      ? imp.source
+      : imp.source.endsWith('.')
+        ? imp.source + imp.localName
+        : imp.source + '.' + imp.localName;
+
+    // resolveImportPath only maps RELATIVE dotted paths (`.mod`, `..pkg.mod`); an
+    // ABSOLUTE package path (`pkg.module` from `from pkg import module`, or a bare
+    // `import pkg.mod`) resolves to null there, so fall back to the dotted-module
+    // file lookup — the same asymmetry resolveModuleImportToFile already handles
+    // for the file→file import edge. Without this, a `module.func()` call after
+    // `from pkg import module` dropped its `calls` edge even though the import
+    // edge resolved (#578).
+    let resolvedPath = resolveImportPath(modulePath, ref.filePath, ref.language, context);
+    if (!resolvedPath) {
+      resolvedPath = findPythonModuleFile(modulePath, context, ref.filePath)?.filePath ?? null;
+    }
+    if (!resolvedPath || resolvedPath === ref.filePath) continue;
+
+    // Find the member as a top-level definition in the module file. Exclude
+    // `method` so `mod.foo` never lands on a same-named class method.
+    const target = context.getNodesInFile(resolvedPath).find(
+      (n) =>
+        n.name === member &&
+        (n.kind === 'function' ||
+          n.kind === 'class' ||
+          n.kind === 'variable' ||
+          n.kind === 'constant')
+    );
+    if (target) {
+      return { original: ref, targetNodeId: target.id, confidence: 0.85, resolvedBy: 'import' };
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve a whole-MODULE import to that module's file (a file→file dependency).
+ * The imported name is a module, not a symbol, so there's nothing to resolve to
+ * — but importing a module IS a dependency on it. Covers:
+ *   - Python submodule imports — `from . import certs`, `from pkg import sub`;
+ *   - namespace imports — Python `import mod` / `import numpy as np`, and
+ *     TS/JS `import * as ns from './x'`.
+ *
+ * It is also the robust backstop for {@link resolvePythonModuleMember} and for
+ * TS namespace usage: it records the dependency even when the used member is
+ * re-exported elsewhere (requests' `certs.where`, re-exported from `certifi`),
+ * the usage is module-level code that isn't extracted as a call, or a TS
+ * namespace is touched only via a value-member read (`ns.SOME_CONST`).
+ *
+ * Only fires for dot-free `imports`-kind refs whose module path resolves to a
+ * real file. A NAMED TS/JS import (`import { widget }`) is not a module, so it
+ * returns null and normal symbol resolution handles it.
+ */
+/**
+ * Resolve a Lua/Luau `require(...)` to its module file. The reference name is
+ * either a dotted module path (`telescope.config` → `telescope/config.lua`) or a
+ * Roblox instance-path leaf (`Signal` from `require(script.Parent.Signal)` →
+ * `Signal.luau`). We try `<path>.lua|.luau` and `<path>/init.lua|.luau`, matched
+ * by path suffix (the module root — `lua/`, `src/`, … — is project-specific).
+ * Among suffix matches, the one sharing the longest directory prefix with the
+ * requiring file wins (instance-path requires resolve within the same package).
+ */
+function resolveLuaRequire(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null {
+  const name = ref.referenceName;
+  if (!name) return null;
+  const base = name.includes('.') ? name.replace(/\./g, '/') : name;
+  const suffixes = [`${base}.lua`, `${base}.luau`, `${base}/init.lua`, `${base}/init.luau`];
+  const files = context.getAllFiles();
+  const shared = (a: string, b: string): number => {
+    let i = 0;
+    while (i < a.length && i < b.length && a[i] === b[i]) i++;
+    return i;
+  };
+  for (const suffix of suffixes) {
+    const matches = files.filter((f) => f === suffix || f.endsWith('/' + suffix));
+    if (matches.length === 0) continue;
+    matches.sort((x, y) => shared(y, ref.filePath) - shared(x, ref.filePath));
+    const best = matches[0]!;
+    if (best === ref.filePath) continue;
+    const fileNode = context.getNodesInFile(best).find((n) => n.kind === 'file');
+    if (fileNode) {
+      // Confidence ≥ 0.9 so this deterministic path/suffix match wins over
+      // name-matching, which otherwise resolves the require to the import node
+      // itself (a same-name self-match).
+      return { original: ref, targetNodeId: fileNode.id, confidence: 0.9, resolvedBy: 'import' };
+    }
+  }
+  return null;
+}
+
+function resolveModuleImportToFile(
+  ref: UnresolvedRef,
+  imports: ImportMapping[],
+  context: ResolutionContext
+): ResolvedRef | null {
+  if (ref.referenceKind !== 'imports') return null;
+  if (ref.referenceName.includes('.')) return null;
+
+  for (const imp of imports) {
+    if (imp.localName !== ref.referenceName) continue;
+
+    let modulePath: string;
+    if (imp.isNamespace || imp.isDefault) {
+      // `import * as ns from './x'` (namespace) or `import x from './x'`
+      // (default) — the dependency is on the MODULE FILE. A default import binds
+      // a (possibly renamed) local to whatever the module's default export is
+      // (`import articlesController from './article.controller'` ← `export
+      // default router`), so the binding name can't be found as a symbol — link
+      // the file the import resolves to instead. External modules don't resolve
+      // (no file), so `import React from 'react'` creates no edge.
+      modulePath = imp.source;
+    } else if (ref.language === 'python') {
+      // `from . import certs` — the imported NAME is a submodule of the source.
+      modulePath = imp.source.endsWith('.')
+        ? imp.source + imp.localName
+        : imp.source + '.' + imp.localName;
+    } else {
+      // A named TS/JS import binds a symbol, not a module — leave it alone.
+      continue;
+    }
+
+    const resolvedPath = resolveImportPath(modulePath, ref.filePath, ref.language, context);
+    if (resolvedPath && resolvedPath !== ref.filePath) {
+      const fileNode = context.getNodesInFile(resolvedPath).find((n) => n.kind === 'file');
+      if (fileNode) {
+        return { original: ref, targetNodeId: fileNode.id, confidence: 0.9, resolvedBy: 'import' };
+      }
+    }
+
+    // Python absolute `from a.b import submodule` (a FastAPI router aggregator's
+    // `from app.api.routes import authentication`): resolveImportPath only maps
+    // RELATIVE dotted paths to a file, so resolve the absolute dotted module
+    // directly to its file node.
+    if (ref.language === 'python') {
+      const modFile = findPythonModuleFile(modulePath, context, ref.filePath);
+      if (modFile) {
+        return { original: ref, targetNodeId: modFile.id, confidence: 0.9, resolvedBy: 'import' };
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Find the file node for a Python dotted module path `a.b.c` — a module file
+ * ending in `a/b/c.py`, or a package `a/b/c/__init__.py` (suffix-matched, so a
+ * package rooted under `src/` etc. still resolves). Returns null for
+ * stdlib/external modules (no matching repo file node), so `import os` creates
+ * no edge. Shared by absolute `import a.b.c` and absolute `from a.b import c`
+ * (where `c` is a submodule) resolution.
+ */
+function findPythonModuleFile(
+  mod: string,
+  context: ResolutionContext,
+  excludeFilePath: string
+): Node | null {
+  if (!mod || mod.startsWith('.')) return null; // relative imports handled elsewhere
+  const rel = mod.replace(/\./g, '/');
+  const lastSeg = mod.split('.').pop()!;
+  const endsWith = (p: string, want: string): boolean => p === want || p.endsWith('/' + want);
+  const moduleFile = context
+    .getNodesByName(`${lastSeg}.py`)
+    .find((n) => n.kind === 'file' && n.filePath !== excludeFilePath && endsWith(n.filePath, `${rel}.py`));
+  if (moduleFile) return moduleFile;
+  const pkgFile = context
+    .getNodesByName('__init__.py')
+    .find((n) => n.kind === 'file' && n.filePath !== excludeFilePath && endsWith(n.filePath, `${rel}/__init__.py`));
+  return pkgFile ?? null;
+}
+
+/**
+ * Resolve a Python ABSOLUTE dotted module import (`import a.b.c`) to its file —
+ * the Django `AppConfig.ready(): import myapp.signals` pattern and any
+ * side-effect module import.
+ */
+function resolvePythonAbsoluteModule(
+  ref: UnresolvedRef,
+  context: ResolutionContext
+): ResolvedRef | null {
+  if (ref.referenceKind !== 'imports') return null;
+  // Only a DOTTED `import a.b.c` ref carries its full module path. A bare leaf
+  // (`from app.api.routes import authentication`) is ambiguous on its own — three
+  // `authentication.py` files may exist — so leave it to resolveModuleImportToFile,
+  // which uses the import's source (`app.api.routes`) to build the full path.
+  if (!ref.referenceName.includes('.')) return null;
+  const hit = findPythonModuleFile(ref.referenceName, context, ref.filePath);
+  return hit ? { original: ref, targetNodeId: hit.id, confidence: 0.9, resolvedBy: 'import' } : null;
+}
+
+/**
+ * Resolve a Rust qualified reference `A::B::C` by mapping the MODULE prefix
+ * (`A::B`) to a file and finding the leaf symbol (`C`) in it. This is the Rust
+ * analog of {@link resolvePythonModuleMember} / {@link resolveGoCrossPackageReference}
+ * and the precise answer to common-name re-exports (`pub use self::read::read`)
+ * that name-matching can't disambiguate. Returns null when the prefix isn't a
+ * real module path (e.g. `Widget::new` — `Widget` is a struct, not a module),
+ * so associated-function calls and enum-variant paths fall through untouched.
+ */
+function resolveRustPathReference(
+  ref: UnresolvedRef,
+  context: ResolutionContext
+): ResolvedRef | null {
+  const segments = ref.referenceName.split('::').filter((s) => s.length > 0);
+  if (segments.length < 2) return null;
+  const leaf = segments[segments.length - 1]!;
+  const modSegs = segments.slice(0, -1);
+
+  const file = resolveRustModuleFile(modSegs, ref.filePath, context);
+  if (!file || file === ref.filePath) return null;
+
+  const target = context.getNodesInFile(file).find(
+    (n) =>
+      n.name === leaf &&
+      (n.kind === 'function' ||
+        n.kind === 'struct' ||
+        n.kind === 'enum' ||
+        n.kind === 'trait' ||
+        n.kind === 'type_alias' ||
+        n.kind === 'constant' ||
+        n.kind === 'method' ||
+        n.kind === 'class' ||
+        n.kind === 'interface')
+  );
+  if (target) {
+    return { original: ref, targetNodeId: target.id, confidence: 0.9, resolvedBy: 'import' };
+  }
+  return null;
+}
+
+/** The crate-root directory (holds `lib.rs`/`main.rs`), walking up from a file. */
+function rustCrateRootDir(fromFileAbs: string, context: ResolutionContext): string | null {
+  const projectRoot = context.getProjectRoot();
+  const toRel = (p: string) => path.relative(projectRoot, p).replace(/\\/g, '/');
+  let dir = path.dirname(fromFileAbs);
+  for (let i = 0; i < 64; i++) {
+    if (context.fileExists(toRel(path.join(dir, 'lib.rs'))) ||
+        context.fileExists(toRel(path.join(dir, 'main.rs')))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+  return null;
+}
+
+/** Directory under which the current file's module declares its SUBMODULES. */
+function rustSelfModuleDir(fromFileAbs: string): string {
+  const base = path.basename(fromFileAbs);
+  const dir = path.dirname(fromFileAbs);
+  // mod.rs / lib.rs / main.rs own their directory; `foo.rs`'s submodules live in `foo/`.
+  if (base === 'mod.rs' || base === 'lib.rs' || base === 'main.rs') return dir;
+  return path.join(dir, base.replace(/\.rs$/, ''));
+}
+
+/**
+ * Resolve a Rust module path (segments WITHOUT the leaf symbol) to the file of
+ * the last module segment — `crate::a::b` → `<crate>/a/b.rs` (or `.../b/mod.rs`).
+ * Anchors on `crate` / `self` / `super`; a bare path is tried crate-relative.
+ */
+function resolveRustModuleFile(
+  segments: string[],
+  fromFile: string,
+  context: ResolutionContext
+): string | null {
+  if (segments.length === 0) return null;
+  const projectRoot = context.getProjectRoot();
+  const fromAbs = path.join(projectRoot, fromFile);
+  const toRel = (p: string) => path.relative(projectRoot, p).replace(/\\/g, '/');
+
+  // Walk a sequence of module segments down from `startDir`, mapping each to a
+  // `<seg>.rs` or `<seg>/mod.rs` file. Returns the leaf module's file, or null
+  // if `startDir` is null or any segment has no file on disk.
+  const resolveUnder = (startDir: string | null, rest: string[]): string | null => {
+    if (!startDir) return null;
+    let dir = startDir;
+    let targetFile: string | null = null;
+    for (const seg of rest) {
+      if (seg === 'self' || seg === 'crate' || seg === 'super') continue;
+      const asFile = toRel(path.join(dir, seg + '.rs'));
+      const asMod = toRel(path.join(dir, seg, 'mod.rs'));
+      if (context.fileExists(asFile)) targetFile = asFile;
+      else if (context.fileExists(asMod)) targetFile = asMod;
+      else return null;
+      dir = path.join(dir, seg);
+    }
+    return targetFile;
+  };
+
+  const first = segments[0]!;
+  if (first === 'crate') {
+    return resolveUnder(rustCrateRootDir(fromAbs, context), segments.slice(1));
+  }
+  if (first === 'self') {
+    return resolveUnder(rustSelfModuleDir(fromAbs), segments.slice(1));
+  }
+  if (first === 'super') {
+    let supers = 0;
+    while (segments[supers] === 'super') supers++;
+    let dir: string | null = rustSelfModuleDir(fromAbs);
+    for (let s = 0; s < supers && dir; s++) dir = path.dirname(dir);
+    return resolveUnder(dir, segments.slice(supers));
+  }
+  // Bare path. In expression position (`submodule::item()` — the router-assembly
+  // and general cross-module-call pattern) the prefix is a SUBMODULE of the
+  // current module, i.e. 2018 `self::`-relative — so try self-relative FIRST.
+  // Fall back to crate-relative for 2015-edition / crate-root items. External
+  // crate paths (`serde::de::Error`) miss both and fall through to name-matching.
+  return (
+    resolveUnder(rustSelfModuleDir(fromAbs), segments) ??
+    resolveUnder(rustCrateRootDir(fromAbs, context), segments)
+  );
+}
+
+/**
+ * Resolve a Java/Kotlin reference whose receiver is the simple name of
+ * an imported FQN: `Foo.bar(...)` where `import com.example.Foo;`. The
+ * imported FQN converts to a file-path suffix (`com/example/Foo.java`
+ * or `.kt`) which uniquely identifies the right symbol when multiple
+ * classes share the same simple name.
+ *
+ * Also handles bare references to the imported class itself
+ * (`new Foo()` extraction emits `Foo` as a `references`/`instantiates`
+ * ref) and `import static <Foo>.bar` style imports of a single member.
+ */
+function resolveJavaImportedReference(
+  ref: UnresolvedRef,
+  imports: ImportMapping[],
+  context: ResolutionContext
+): ResolvedRef | null {
+  if (imports.length === 0) return null;
+
+  const ext = ref.language === 'kotlin' ? '.kt' : '.java';
+
+  for (const imp of imports) {
+    const matchesBare = imp.localName === ref.referenceName;
+    const matchesQualified = ref.referenceName.startsWith(imp.localName + '.');
+    if (!matchesBare && !matchesQualified) continue;
+
+    // Convert FQN to a file-path suffix. `com.example.Foo` ->
+    // `com/example/Foo.java` (or `.kt`). The actual file may live
+    // under any source root (`src/main/java/`, `src/`, etc.), so match
+    // by suffix rather than exact path.
+    const fqnPath = imp.source.replace(/\./g, '/') + ext;
+
+    // Which symbol name to look up: the class itself, or a member.
+    const memberName = matchesBare
+      ? imp.localName
+      : ref.referenceName.substring(imp.localName.length + 1);
+
+    const candidates = context.getNodesByName(memberName);
+    for (const node of candidates) {
+      if (node.language !== ref.language) continue;
+      const fp = node.filePath.replace(/\\/g, '/');
+      if (fp.endsWith(fqnPath) || fp.endsWith('/' + fqnPath)) {
+        return {
+          original: ref,
+          targetNodeId: node.id,
+          confidence: 0.9,
+          resolvedBy: 'import',
+        };
+      }
+    }
+
+    // `import static com.example.Foo.bar;` — the FQN's tail is the
+    // member name, the part before is the owner class. Look up the
+    // member named `<imp.localName>` (e.g. `bar`) and prefer the
+    // candidate whose file matches the parent FQN's path.
+    if (matchesBare) {
+      const dot = imp.source.lastIndexOf('.');
+      if (dot > 0) {
+        const ownerFqn = imp.source.substring(0, dot);
+        const ownerPath = ownerFqn.replace(/\./g, '/') + ext;
+        for (const node of candidates) {
+          if (node.language !== ref.language) continue;
+          const fp = node.filePath.replace(/\\/g, '/');
+          if (fp.endsWith(ownerPath) || fp.endsWith('/' + ownerPath)) {
+            return {
+              original: ref,
+              targetNodeId: node.id,
+              confidence: 0.9,
+              resolvedBy: 'import',
+            };
+          }
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve a Go cross-package qualified reference (`pkga.FuncX`) by matching
+ * the package alias against an in-module import, stripping the module prefix
+ * to a project-relative directory, and locating the exported symbol in any
+ * `.go` file under that directory. Returns `null` for stdlib / third-party
+ * imports (no `go.mod`-relative match) so the rest of `resolveViaImport`
+ * can still try the file-based path.
+ */
+function resolveGoCrossPackageReference(
+  ref: UnresolvedRef,
+  imports: ImportMapping[],
+  context: ResolutionContext
+): ResolvedRef | null {
+  const mod = context.getGoModule?.();
+  if (!mod) return null;
+
+  // Qualified call: receiver before `.`, member after. A bare reference
+  // (no dot) is a same-file/in-package call — handled elsewhere.
+  const dotIdx = ref.referenceName.indexOf('.');
+  if (dotIdx <= 0) return null;
+  const receiver = ref.referenceName.substring(0, dotIdx);
+  const memberName = ref.referenceName.substring(dotIdx + 1);
+  if (!memberName) return null;
+
+  for (const imp of imports) {
+    if (imp.localName !== receiver) continue;
+    // Only in-module imports map to a known directory.
+    if (imp.source !== mod.modulePath && !imp.source.startsWith(mod.modulePath + '/')) {
+      continue;
+    }
+    const pkgDir = imp.source === mod.modulePath
+      ? ''
+      : imp.source.substring(mod.modulePath.length + 1);
+
+    // Look up the member by name and pick the candidate whose file lives
+    // directly in the package directory. Match the immediate parent dir
+    // exactly so a call to `pkga.FuncX` doesn't accidentally land on a
+    // `FuncX` declared in `pkga/subpkg/`.
+    const candidates = context.getNodesByName(memberName);
+    for (const node of candidates) {
+      if (node.language !== 'go') continue;
+      if (!node.isExported) continue;
+      const fp = node.filePath.replace(/\\/g, '/');
+      const lastSlash = fp.lastIndexOf('/');
+      const fileDir = lastSlash >= 0 ? fp.substring(0, lastSlash) : '';
+      if (fileDir === pkgDir) {
+        return {
+          original: ref,
+          targetNodeId: node.id,
+          confidence: 0.9,
+          resolvedBy: 'import',
+        };
+      }
+    }
+  }
+  return null;
+}
+
 /** Recursive depth cap for re-export chain following. Real codebases
  *  rarely chain barrels more than 2–3 deep; 8 is a generous safety
  *  net that still bounds worst-case work. */
@@ -671,9 +1830,17 @@ function findExportedSymbol(
 
   // 1. Direct hit: the symbol is declared in this file.
   if (want.isDefault) {
-    const direct = nodesInFile.find(
-      (n) => n.isExported && (n.kind === 'function' || n.kind === 'class')
-    );
+    // Svelte/Vue single-file components ARE the module's default export,
+    // but are extracted as kind 'component' (not function/class). Prefer
+    // the component node; fall back to an exported function/class for the
+    // `.ts`/`.tsx` `export default fn`/`class` case. Without the component
+    // branch, an `export { default as X } from './X.svelte'` barrel never
+    // resolves and the component shows a false 0 callers (#629).
+    const direct =
+      nodesInFile.find((n) => n.isExported && n.kind === 'component') ??
+      nodesInFile.find(
+        (n) => n.isExported && (n.kind === 'function' || n.kind === 'class')
+      );
     if (direct) return direct;
   } else if (want.isNamespace && want.memberName) {
     const direct = nodesInFile.find(
diff --git a/src/resolution/index.ts b/src/resolution/index.ts
index 34aa4b90d..0d7ec4309 100644
--- a/src/resolution/index.ts
+++ b/src/resolution/index.ts
@@ -16,12 +16,49 @@ import {
   FrameworkResolver,
   ImportMapping,
 } from './types';
-import { matchReference } from './name-matcher';
-import { resolveViaImport, extractImportMappings, extractReExports } from './import-resolver';
+import { matchReference, matchFunctionRef, matchDottedCallChain, matchScopedCallChain, sameLanguageFamily, crossesKnownFamily } from './name-matcher';
+import { resolveViaImport, resolveJvmImport, extractImportMappings, extractReExports, loadCppIncludeDirs, isPhpIncludePathRef } from './import-resolver';
 import { detectFrameworks } from './frameworks';
+import { synthesizeCallbackEdges } from './callback-synthesizer';
 import { loadProjectAliases, type AliasMap } from './path-aliases';
+import { loadGoModule, type GoModule } from './go-module';
+import { loadWorkspacePackages, type WorkspacePackages } from './workspace-packages';
 import { logDebug } from '../errors';
 import type { ReExport } from './types';
+import { LRUCache } from './lru-cache';
+
+/** Node kinds that can declare supertypes (extends/implements). */
+const SUPERTYPE_BEARING_KINDS = new Set<Node['kind']>([
+  'class', 'struct', 'interface', 'trait', 'protocol', 'enum',
+]);
+
+/**
+ * Languages whose chained static-factory/fluent calls defer to the conformance
+ * second pass. Dotted-receiver languages resolve via matchDottedCallChain; the
+ * `::`-receiver ones (Rust) via matchScopedCallChain.
+ */
+const CHAIN_LANGUAGES = new Set(['java', 'kotlin', 'csharp', 'swift', 'rust', 'go', 'scala', 'dart', 'objc', 'pascal']);
+const SCOPED_CHAIN_LANGUAGES = new Set(['rust']);
+
+/** The extractor's chained-receiver encoding: `<inner>().<method>`. */
+const CHAIN_SHAPE = /^(.+)\(\)\.(\w+)$/;
+
+/**
+ * Cache size limits. Each per-resolver cache is bounded so memory
+ * stays flat on large codebases (20k+ files). Sizes were chosen to
+ * cover the working set for typical resolution batches without
+ * exceeding a few hundred MB worst-case. Override via the env var
+ * `CODEGRAPH_RESOLVER_CACHE_SIZE` (single integer applied to all
+ * caches) when tuning for very large or very small projects.
+ */
+const DEFAULT_CACHE_LIMIT = 5_000;
+function resolveCacheLimit(): number {
+  const raw = process.env.CODEGRAPH_RESOLVER_CACHE_SIZE;
+  if (!raw) return DEFAULT_CACHE_LIMIT;
+  const parsed = Number.parseInt(raw, 10);
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  return DEFAULT_CACHE_LIMIT;
+}
 
 // Re-export types
 export * from './types';
@@ -111,6 +148,49 @@ const PASCAL_BUILT_INS = new Set([
   'IInterface', 'IUnknown',
 ]);
 
+const C_BUILT_INS = new Set([
+  // Standard C library functions
+  'printf', 'fprintf', 'sprintf', 'snprintf', 'scanf', 'fscanf', 'sscanf',
+  'malloc', 'calloc', 'realloc', 'free',
+  'memcpy', 'memmove', 'memset', 'memcmp', 'memchr',
+  'strlen', 'strcpy', 'strncpy', 'strcat', 'strncat', 'strcmp', 'strncmp',
+  'strstr', 'strchr', 'strrchr', 'strtok', 'strdup',
+  'fopen', 'fclose', 'fread', 'fwrite', 'fgets', 'fputs', 'fputc', 'fgetc',
+  'feof', 'ferror', 'fflush', 'fseek', 'ftell', 'rewind',
+  'exit', 'abort', 'atexit', 'atoi', 'atol', 'atof', 'strtol', 'strtoul', 'strtod',
+  'qsort', 'bsearch',
+  'abs', 'labs', 'rand', 'srand',
+  'sin', 'cos', 'tan', 'sqrt', 'pow', 'log', 'log10', 'exp', 'ceil', 'floor', 'fabs',
+  'time', 'clock', 'difftime', 'mktime', 'localtime', 'gmtime', 'strftime', 'asctime',
+  'assert', 'errno',
+  'perror', 'remove', 'rename', 'tmpfile', 'tmpnam',
+  'getenv', 'system',
+  'signal', 'raise',
+  'setjmp', 'longjmp',
+  'va_start', 'va_end', 'va_arg', 'va_copy',
+  'NULL', 'EOF', 'BUFSIZ', 'FILENAME_MAX', 'RAND_MAX', 'EXIT_SUCCESS', 'EXIT_FAILURE',
+  'size_t', 'ptrdiff_t', 'wchar_t', 'intptr_t', 'uintptr_t',
+  'int8_t', 'int16_t', 'int32_t', 'int64_t',
+  'uint8_t', 'uint16_t', 'uint32_t', 'uint64_t',
+  'FILE',
+  // POSIX additions commonly seen
+  'stat', 'lstat', 'fstat', 'open', 'close', 'read', 'write', 'pipe',
+  'fork', 'exec', 'waitpid', 'getpid', 'getppid', 'kill', 'sleep', 'usleep',
+  'pthread_create', 'pthread_join', 'pthread_mutex_lock', 'pthread_mutex_unlock',
+  'dlopen', 'dlsym', 'dlclose',
+]);
+
+const CPP_BUILT_INS = new Set([
+  // iostream objects (often used without std:: prefix via using)
+  'cout', 'cin', 'cerr', 'clog', 'endl', 'flush', 'ws',
+  'std', // the namespace itself when used as std::something
+  // Common C++ keywords that leak as references
+  'nullptr', 'true', 'false', 'this', 'sizeof', 'alignof', 'typeid',
+  'static_cast', 'dynamic_cast', 'reinterpret_cast', 'const_cast',
+  'make_unique', 'make_shared', 'make_pair',
+  'move', 'forward', 'swap',
+]);
+
 /**
  * Reference Resolver
  *
@@ -121,13 +201,31 @@ export class ReferenceResolver {
   private queries: QueryBuilder;
   private context: ResolutionContext;
   private frameworks: FrameworkResolver[] = [];
-  private nodeCache: Map<string, Node[]> = new Map(); // per-file node cache (bounded)
-  private fileCache: Map<string, string | null> = new Map(); // per-file content cache (bounded)
-  private importMappingCache: Map<string, ImportMapping[]> = new Map();
-  private reExportCache: Map<string, ReExport[]> = new Map();
-  private nameCache: Map<string, Node[]> = new Map(); // name → nodes cache
-  private lowerNameCache: Map<string, Node[]> = new Map(); // lower(name) → nodes cache
-  private qualifiedNameCache: Map<string, Node[]> = new Map(); // qualified_name → nodes cache
+  // Chained static-factory/fluent call refs the first pass couldn't resolve,
+  // collected in-memory (the batched resolver deletes unresolved refs from the
+  // DB, so they can't be re-read). Drained by resolveChainedCallsViaConformance
+  // once implements/extends edges exist, to resolve methods on a supertype the
+  // receiver conforms to (#750).
+  private deferredChainRefs: UnresolvedRef[] = [];
+  // `this.<member>` function-as-value refs whose member is NOT on the
+  // enclosing class itself — possibly inherited. Collected in-memory for the
+  // same reason as deferredChainRefs and drained by
+  // resolveDeferredThisMemberRefs once implements/extends edges exist (#808).
+  private deferredThisMemberRefs: UnresolvedRef[] = [];
+  // Per-`.razor`/`.cshtml`-file `@using` namespace set (own directives + folder
+  // `_Imports.razor`, cascading to the project root). Used to disambiguate a
+  // markup type ref to the right C# namespace.
+  private razorUsingsCache = new Map<string, string[]>();
+  // All per-resolver caches are LRU-bounded. Previously these were
+  // unbounded Maps that grew with every distinct lookup and OOM'd on
+  // codebases with 20k+ files (see issue: unbounded cache growth).
+  private nodeCache: LRUCache<string, Node[]>; // per-file node cache
+  private fileCache: LRUCache<string, string | null>; // per-file content cache
+  private importMappingCache: LRUCache<string, ImportMapping[]>;
+  private reExportCache: LRUCache<string, ReExport[]>;
+  private nameCache: LRUCache<string, Node[]>; // name → nodes cache
+  private lowerNameCache: LRUCache<string, Node[]>; // lower(name) → nodes cache
+  private qualifiedNameCache: LRUCache<string, Node[]>; // qualified_name → nodes cache
   private knownNames: Set<string> | null = null; // all known symbol names for fast pre-filtering
   private knownFiles: Set<string> | null = null;
   private cachesWarmed = false;
@@ -135,10 +233,27 @@ export class ReferenceResolver {
   // `null` = computed and absent. Treated as immutable for the
   // resolver's lifetime; callers re-create the resolver if config changes.
   private projectAliases: AliasMap | null | undefined = undefined;
+  // go.mod module path. Same lazy/immutable convention as projectAliases.
+  private goModule: GoModule | null | undefined = undefined;
+  // Monorepo workspace member packages. Same lazy/immutable convention.
+  private workspacePackages: WorkspacePackages | null | undefined = undefined;
 
   constructor(projectRoot: string, queries: QueryBuilder) {
     this.projectRoot = projectRoot;
     this.queries = queries;
+
+    const limit = resolveCacheLimit();
+    // The content cache is heavier (full file text), so we give it a
+    // smaller budget than the metadata caches.
+    const contentLimit = Math.max(64, Math.floor(limit / 5));
+    this.nodeCache = new LRUCache(limit);
+    this.fileCache = new LRUCache(contentLimit);
+    this.importMappingCache = new LRUCache(limit);
+    this.reExportCache = new LRUCache(limit);
+    this.nameCache = new LRUCache(limit);
+    this.lowerNameCache = new LRUCache(limit);
+    this.qualifiedNameCache = new LRUCache(limit);
+
     this.context = this.createContext();
   }
 
@@ -150,6 +265,35 @@ export class ReferenceResolver {
     this.clearCaches();
   }
 
+  /**
+   * Run each framework resolver's cross-file finalization pass and persist
+   * the returned node updates. Idempotent — safe to call after every indexAll
+   * and every incremental sync. Returns the number of nodes updated.
+   *
+   * Caches are cleared before/after so the post-extract pass sees fresh DB
+   * state and downstream queries see the updated names.
+   */
+  runPostExtract(): number {
+    let updated = 0;
+    this.clearCaches();
+    for (const fw of this.frameworks) {
+      if (!fw.postExtract) continue;
+      try {
+        const nodes = fw.postExtract(this.context);
+        for (const node of nodes) {
+          this.queries.updateNode(node);
+          updated++;
+        }
+      } catch (err) {
+        logDebug(`Framework '${fw.name}' postExtract failed`, {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+    if (updated > 0) this.clearCaches();
+    return updated;
+  }
+
   /**
    * Pre-build lightweight caches for resolution.
    * Node lookups are now handled by indexed SQLite queries instead of
@@ -283,6 +427,29 @@ export class ReferenceResolver {
         return result;
       },
 
+      getNodeById: (id: string) => {
+        return this.queries.getNodeById(id);
+      },
+
+      getSupertypes: (typeName: string, language) => {
+        // Union the `implements`/`extends` targets of every same-named type node.
+        // Matching by simple name (not id) reconciles a type declared in one node
+        // (`KF::Builder`) with conformance declared in a separate extension node
+        // (`KF.Builder: KFOptionSetter`) — both have name `Builder`.
+        const typeNodes = this.context
+          .getNodesByName(typeName)
+          .filter((n) => SUPERTYPE_BEARING_KINDS.has(n.kind) && n.language === language);
+        if (typeNodes.length === 0) return [];
+        const supertypes = new Set<string>();
+        for (const tn of typeNodes) {
+          for (const edge of this.queries.getOutgoingEdges(tn.id, ['implements', 'extends'])) {
+            const target = this.queries.getNodeById(edge.target);
+            if (target?.name && target.name !== typeName) supertypes.add(target.name);
+          }
+        }
+        return [...supertypes];
+      },
+
       getImportMappings: (filePath: string, language) => {
         const cacheKey = filePath;
         const cached = this.importMappingCache.get(cacheKey);
@@ -306,6 +473,20 @@ export class ReferenceResolver {
         return this.projectAliases;
       },
 
+      getGoModule: () => {
+        if (this.goModule === undefined) {
+          this.goModule = loadGoModule(this.projectRoot);
+        }
+        return this.goModule;
+      },
+
+      getWorkspacePackages: () => {
+        if (this.workspacePackages === undefined) {
+          this.workspacePackages = loadWorkspacePackages(this.projectRoot);
+        }
+        return this.workspacePackages;
+      },
+
       getReExports: (filePath: string, language) => {
         const cached = this.reExportCache.get(filePath);
         if (cached) return cached;
@@ -314,10 +495,22 @@ export class ReferenceResolver {
           this.reExportCache.set(filePath, []);
           return [];
         }
-        const reExports = extractReExports(content, language);
+        // Re-exports are a JS/TS-only construct, and what matters is the
+        // BARREL file's own language — not the consuming reference's. A
+        // `.svelte`/`.vue` consumer threads its own language down the
+        // re-export chase, which would make extractReExports() bail on a
+        // `.ts` index barrel and silently break the chain (#629). Re-key
+        // the parse on the barrel's extension so the chase works no matter
+        // what kind of file imports through it.
+        const isJsFamily = /\.(?:d\.ts|[cm]?tsx?|[cm]?jsx?)$/i.test(filePath);
+        const reExports = extractReExports(content, isJsFamily ? 'typescript' : language);
         this.reExportCache.set(filePath, reExports);
         return reExports;
       },
+
+      getCppIncludeDirs: () => {
+        return loadCppIncludeDirs(this.projectRoot);
+      },
     };
   }
 
@@ -407,12 +600,30 @@ export class ReferenceResolver {
       // Also check capitalized receiver (instance-method resolution)
       const capitalized = receiver.charAt(0).toUpperCase() + receiver.slice(1);
       if (this.knownNames.has(capitalized)) return true;
+      // JVM FQN: `com.example.foo.Bar` — the only useful segment is the
+      // last one (`Bar`); the earlier check finds `example.foo.Bar` which
+      // never matches a node name.
+      const lastDot = name.lastIndexOf('.');
+      if (lastDot > dotIdx) {
+        const tail = name.substring(lastDot + 1);
+        if (tail && this.knownNames.has(tail)) return true;
+      }
     }
     const colonIdx = name.indexOf('::');
     if (colonIdx > 0) {
       const receiver = name.substring(0, colonIdx);
       const member = name.substring(colonIdx + 2);
       if (this.knownNames.has(receiver) || this.knownNames.has(member)) return true;
+      // Multi-segment path `a::b::c` (a Rust/C++ module call like
+      // `database::profiles::find`) — the only segment that names a symbol is
+      // the last (`c`); `member` above is `b::c`, which never matches a node
+      // name, so without this the pre-filter drops the ref before the Rust path
+      // resolver ever sees it. Mirror the dotted-name leaf check above.
+      const lastColon = name.lastIndexOf('::');
+      if (lastColon > colonIdx) {
+        const tail = name.substring(lastColon + 2);
+        if (tail && this.knownNames.has(tail)) return true;
+      }
     }
 
     // For path-like references (e.g., "snippets/drawer-menu.liquid"), check the filename
@@ -459,15 +670,60 @@ export class ReferenceResolver {
     // from './barrel'` where the barrel has `export { signIn as login }
     // from './auth'`) intentionally call a name that has no
     // declaration anywhere — only the renamed upstream symbol does.
-    if (!this.hasAnyPossibleMatch(ref.referenceName) && !this.matchesAnyImport(ref)) {
+    if (
+      !this.hasAnyPossibleMatch(ref.referenceName) &&
+      !this.matchesAnyImport(ref) &&
+      !this.frameworks.some((f) => f.claimsReference?.(ref.referenceName))
+    ) {
       return null;
     }
 
+    // Function-as-value refs (#756) get a dedicated, strictly-gated path:
+    // import-based resolution first (an imported callback resolves through its
+    // import, the most precise cross-file signal), then matchFunctionRef
+    // (same-file first, unique-only cross-file, function/method targets only).
+    // They never reach the framework or fuzzy strategies below.
+    if (ref.referenceKind === 'function_ref') {
+      // `this.<member>` values (TS/JS) resolve ONLY against the enclosing
+      // class's own members — never a same-named symbol elsewhere.
+      if (ref.referenceName.startsWith('this.')) {
+        return this.gateLanguage(this.resolveThisMemberFnRef(ref), ref);
+      }
+      const viaImport = this.gateLanguage(resolveViaImport(ref, this.context), ref);
+      if (viaImport) {
+        const target = this.queries.getNodeById(viaImport.targetNodeId);
+        if (target && (target.kind === 'function' || target.kind === 'method')) {
+          return viaImport;
+        }
+      }
+      return this.gateLanguage(matchFunctionRef(ref, this.context), ref);
+    }
+
+    // JVM FQN imports skip framework/name-matcher: `import com.example.Bar`
+    // resolves directly through the qualifiedName index, which is unambiguous
+    // even when several `Bar` classes exist in different packages.
+    const jvmImport = resolveJvmImport(ref, this.context);
+    if (jvmImport) return jvmImport;
+
+    // Razor/Blazor: a markup or `@code` type ref resolves through the file's
+    // `@using` namespaces (incl. folder `_Imports.razor`). This precisely
+    // disambiguates a simple name that exists in several namespaces — e.g.
+    // `CatalogBrand` resolving to `BlazorShared.Models::CatalogBrand` (the DTO,
+    // which the `.razor` `@using`s) rather than the same-named domain entity.
+    if (ref.language === 'razor') {
+      const razorResult = this.resolveRazorUsing(ref);
+      if (razorResult) return razorResult;
+    }
+
     const candidates: ResolvedRef[] = [];
 
-    // Strategy 1: Try framework-specific resolution
+    // Strategy 1: Try framework-specific resolution. Cross-language bridges
+    // are deliberately preserved (Drupal `routing.yml` → PHP controller, RN
+    // JS → native `calls`) — `gateFrameworkLanguage` only drops a type/import
+    // edge between two KNOWN families (see its doc), never a `calls` bridge or
+    // a config↔code edge.
     for (const framework of this.frameworks) {
-      const result = framework.resolve(ref, this.context);
+      const result = this.gateFrameworkLanguage(framework.resolve(ref, this.context), ref);
       if (result) {
         if (result.confidence >= 0.9) return result; // High confidence, return immediately
         candidates.push(result);
@@ -475,19 +731,43 @@ export class ReferenceResolver {
     }
 
     // Strategy 2: Try import-based resolution
-    const importResult = resolveViaImport(ref, this.context);
+    const importResult = this.gateLanguage(resolveViaImport(ref, this.context), ref);
     if (importResult) {
       if (importResult.confidence >= 0.9) return importResult;
       candidates.push(importResult);
     }
 
+    // PHP include/require paths resolve to files via import resolution only.
+    // If that didn't find the file, do NOT fall back to the symbol
+    // name-matcher — it would mis-connect e.g. "inc/db.php" to an unrelated
+    // db.php elsewhere in the tree (a wrong edge is worse than none, #660).
+    if (isPhpIncludePathRef(ref)) {
+      return candidates.length > 0
+        ? candidates.reduce((best, curr) =>
+            curr.confidence > best.confidence ? curr : best
+          )
+        : null;
+    }
+
     // Strategy 3: Try name matching
-    const nameResult = matchReference(ref, this.context);
+    const nameResult = this.gateLanguage(matchReference(ref, this.context), ref);
     if (nameResult) {
       candidates.push(nameResult);
     }
 
-    if (candidates.length === 0) return null;
+    if (candidates.length === 0) {
+      // Defer a chained static-factory/fluent call the first pass couldn't
+      // resolve — its method may live on a supertype the receiver conforms to,
+      // resolvable once implements/extends edges exist (the conformance pass).
+      if (
+        ref.referenceKind === 'calls' &&
+        CHAIN_LANGUAGES.has(ref.language) &&
+        CHAIN_SHAPE.test(ref.referenceName)
+      ) {
+        this.deferredChainRefs.push(ref);
+      }
+      return null;
+    }
 
     // Return highest confidence candidate
     return candidates.reduce((best, curr) =>
@@ -500,7 +780,13 @@ export class ReferenceResolver {
    */
   createEdges(resolved: ResolvedRef[]): Edge[] {
     return resolved.map((ref) => {
-      let kind = ref.original.referenceKind;
+      // `function_ref` (#756) is internal-only: it persists as a `references`
+      // edge (the registration site depends on the callback), distinguishable
+      // by metadata.resolvedBy === 'function-ref'. callers/impact already
+      // traverse `references`, so registration sites surface with no
+      // graph-layer changes.
+      let kind: Edge['kind'] =
+        ref.original.referenceKind === 'function_ref' ? 'references' : ref.original.referenceKind;
 
       // Promote "extends" to "implements" when a class/struct targets an interface
       if (kind === 'extends') {
@@ -534,6 +820,11 @@ export class ReferenceResolver {
         metadata: {
           confidence: ref.confidence,
           resolvedBy: ref.resolvedBy,
+          // Uniform marker for function-as-value edges (#756), regardless of
+          // which strategy resolved them (import vs matchFunctionRef) — lets
+          // tooling label "callback registration" and lets validation diff
+          // exactly the edges this feature added.
+          ...(ref.original.referenceKind === 'function_ref' ? { fnRef: true } : {}),
         },
       };
     });
@@ -570,6 +861,48 @@ export class ReferenceResolver {
     return result;
   }
 
+  /**
+   * Second resolution pass for chained static-factory / fluent calls whose
+   * chained method is defined on a SUPERTYPE the receiver's type conforms to —
+   * a protocol-extension / inherited / default-interface method (#750). The
+   * first pass can't resolve these because `implements`/`extends` edges aren't
+   * built yet; this runs AFTER edges are persisted, so `context.getSupertypes`
+   * (and the conformance fallback in resolveMethodOnType) can walk them.
+   *
+   * Operates only on the leftover unresolved refs that have the `inner().method`
+   * chain shape, for the dotted-chain languages — a small set — and is idempotent
+   * (re-resolving an already-resolved ref is a no-op since it's been deleted).
+   * Returns the number of newly-created edges.
+   */
+  resolveChainedCallsViaConformance(): number {
+    const deferred = this.deferredChainRefs;
+    this.deferredChainRefs = [];
+    if (deferred.length === 0) return 0;
+
+    // Read fresh edges (the main pass built the implements/extends edges after
+    // these refs were deferred). matchDottedCallChain now resolves a method on a
+    // supertype via context.getSupertypes -> resolveMethodOnType's conformance walk.
+    this.clearCaches();
+    const resolved: ResolvedRef[] = [];
+    for (const ref of deferred) {
+      // `::`-receiver languages (Rust) split on `::` (matchScopedCallChain);
+      // dotted-receiver languages on `.` (matchDottedCallChain).
+      const chainMatch = SCOPED_CHAIN_LANGUAGES.has(ref.language)
+        ? matchScopedCallChain(ref, this.context)
+        : matchDottedCallChain(ref, this.context);
+      const match = this.gateLanguage(chainMatch, ref);
+      if (match) resolved.push(match);
+    }
+    if (resolved.length === 0) return 0;
+
+    const edges = this.createEdges(resolved);
+    if (edges.length > 0) {
+      this.queries.insertEdges(edges);
+      this.clearCaches();
+    }
+    return edges.length;
+  }
+
   /**
    * Resolve and persist in batches to keep memory bounded.
    * Processes unresolved references in chunks, persisting edges and cleaning
@@ -592,6 +925,7 @@ export class ReferenceResolver {
 
     // Process in batches. We always read from offset 0 because resolved refs
     // are deleted after each batch, shifting the remaining rows forward.
+    let prevRemaining = Number.POSITIVE_INFINITY;
     while (true) {
       const batch = this.queries.getUnresolvedReferencesBatch(0, batchSize);
       if (batch.length === 0) break;
@@ -645,6 +979,28 @@ export class ReferenceResolver {
       if (result.resolved.length === 0 && result.unresolved.length === batch.length) {
         break;
       }
+
+      // Non-progress guard (defense-in-depth). Because we re-read from offset 0
+      // each pass, the unresolved_refs table MUST shrink every iteration — both
+      // resolved and unresolved refs are deleted above. If it didn't shrink, a
+      // resolver returned a match whose `original.referenceName` differs from the
+      // stored row, so the keyed delete no-ops, and we'd re-read + re-resolve +
+      // re-insert the same rows forever (the runaway that grew a 99-file repo to
+      // 5M edges / 1.4 GB before the Go-fallback fix). Stop rather than grow the
+      // graph without bound.
+      const remaining = this.queries.getUnresolvedReferencesCount();
+      if (remaining >= prevRemaining) break;
+      prevRemaining = remaining;
+    }
+
+    // Dynamic-edge synthesis: now that all base `calls` edges are persisted,
+    // synthesize observer/callback dispatch edges (dispatcher → registered
+    // callbacks) that static parsing leaves out. Best-effort — never fail the
+    // index on it. See docs/design/callback-edge-synthesis.md.
+    try {
+      aggregateStats.byMethod['callback-synthesis'] = synthesizeCallbackEdges(this.queries, this.context);
+    } catch {
+      // synthesis is additive and optional; ignore failures
     }
 
     return {
@@ -709,7 +1065,13 @@ export class ReferenceResolver {
           }
         }
       }
-      if (PYTHON_BUILT_IN_METHODS.has(name)) {
+      // A bare name colliding with a builtin method (index, get, update, count…)
+      // is only a builtin when NOTHING in the codebase declares it. A declared
+      // symbol with that exact name — e.g. a Flask/FastAPI view `def index()` or
+      // `def get()` — is a real reference target. Mirrors the knownNames guard on
+      // the dotted branch above; without it, every handler named after a builtin
+      // method silently loses its route→handler edge.
+      if (PYTHON_BUILT_IN_METHODS.has(name) && !this.knownNames?.has(name)) {
         return true;
       }
     }
@@ -738,6 +1100,24 @@ export class ReferenceResolver {
       }
     }
 
+    // C/C++ standard library symbols (printf, malloc, std::vector, etc.).
+    // Names that collide with user-defined symbols are NOT filtered —
+    // C and C++ projects routinely shadow stdlib names (custom allocators
+    // define `malloc`/`free`, stream wrappers define `read`/`write`/`open`,
+    // containers define `move`/`swap`, logging libs wrap `printf`). Killing
+    // those resolutions makes the graph wrong, not cleaner. We only filter
+    // when there's no user node with this name — then name-matching would
+    // produce zero edges anyway and the filter just short-circuits work.
+    if (ref.language === 'c' || ref.language === 'cpp') {
+      // C++ std:: namespace prefix — safe to filter unconditionally,
+      // since `std::foo` is never a user-defined qualified name in
+      // tree-sitter output.
+      if (name.startsWith('std::')) return true;
+      if (C_BUILT_INS.has(name) || CPP_BUILT_INS.has(name)) {
+        return !this.hasAnyPossibleMatch(name);
+      }
+    }
+
     return false;
   }
 
@@ -756,6 +1136,254 @@ export class ReferenceResolver {
     const node = this.queries.getNodeById(nodeId);
     return node?.language || 'unknown';
   }
+
+  /**
+   * Drop an import/name-strategy resolution that crosses a language family.
+   * Two regimes (mirrors `applyLanguageGate`'s candidate filter):
+   *  - `references` (type usage): STRICT — a `Type.member` static read names a
+   *    same-family type, never a coincidentally same-named symbol in another
+   *    language. Drops any non-same-family target.
+   *  - `imports` (import binding / `#include`): both-known — a C++ `#include
+   *    "X.h"` must not resolve to a same-named ObjC header on another platform
+   *    (basename collision), but a singleton-family / SFC language (`vue` →
+   *    `.ts`) importing across is left alone.
+   * Applies to the import (strategy 2) + name-match (strategy 3) results.
+   */
+  /**
+   * Collect the `@using` namespaces in scope for a `.razor`/`.cshtml` file: its
+   * own `@using` directives plus every `_Imports.razor` from the file's folder up
+   * to the project root (Razor `_Imports` cascade). Cached per file.
+   */
+  private getRazorUsings(filePath: string): string[] {
+    const cached = this.razorUsingsCache.get(filePath);
+    if (cached) return cached;
+    const usings = new Set<string>();
+    const addFrom = (src: string | null): void => {
+      if (!src) return;
+      for (const m of src.matchAll(/^\s*@using\s+(?:static\s+)?([A-Za-z_][\w.]*)/gm)) usings.add(m[1]!);
+    };
+    addFrom(this.context.readFile(filePath));
+    let dir = filePath.includes('/') ? filePath.slice(0, filePath.lastIndexOf('/')) : '';
+    // Walk up to the project root, reading each level's _Imports.razor.
+    for (;;) {
+      addFrom(this.context.readFile(dir ? `${dir}/_Imports.razor` : '_Imports.razor'));
+      if (!dir) break;
+      const slash = dir.lastIndexOf('/');
+      dir = slash >= 0 ? dir.slice(0, slash) : '';
+    }
+    const arr = [...usings];
+    this.razorUsingsCache.set(filePath, arr);
+    return arr;
+  }
+
+  /**
+   * Resolve a Razor/Blazor simple type ref through the file's `@using`
+   * namespaces: `CatalogBrand` + `@using BlazorShared.Models` → the node whose
+   * qualified name is `BlazorShared.Models::CatalogBrand`. Only resolves when the
+   * `@using` set yields exactly ONE type (otherwise it stays ambiguous and falls
+   * through to name-matching).
+   */
+  private resolveRazorUsing(ref: UnresolvedRef): ResolvedRef | null {
+    if (ref.referenceName.includes('.') || ref.referenceName.includes('::')) return null;
+    const usings = this.getRazorUsings(ref.filePath);
+    if (usings.length === 0) return null;
+    const found = new Map<string, Node>();
+    for (const ns of usings) {
+      for (const cand of this.context.getNodesByQualifiedName(`${ns}::${ref.referenceName}`)) {
+        found.set(cand.id, cand);
+      }
+    }
+    if (found.size !== 1) return null;
+    const target = found.values().next().value!;
+    return { original: ref, targetNodeId: target.id, confidence: 0.9, resolvedBy: 'import' };
+  }
+
+  /**
+   * Resolve a `this.<member>` function-as-value reference (#756/#808) to the
+   * ENCLOSING CLASS's own member — never a same-named symbol elsewhere. The
+   * registration idiom (`btn.on('click', this.handleClick)`) names a member
+   * of the class being defined, so the only valid target shares the
+   * from-symbol's qualified-name scope. Function/method targets only — a
+   * property (a data field, post-#808 classification) yields no edge — same
+   * file required, no fallback of any kind.
+   */
+  private resolveThisMemberFnRef(ref: UnresolvedRef): ResolvedRef | null {
+    const member = ref.referenceName.slice('this.'.length);
+    if (!member) return null;
+    const fromNode = this.queries.getNodeById(ref.fromNodeId);
+    if (!fromNode) return null;
+    // A hook declared at class-body level (Ruby `before_action :authenticate`)
+    // attributes to the CLASS node itself — its qualified name IS the scope.
+    // For members, strip the member segment.
+    let classPrefix: string;
+    if (SUPERTYPE_BEARING_KINDS.has(fromNode.kind) || fromNode.kind === 'module') {
+      classPrefix = fromNode.qualifiedName;
+    } else {
+      const sep = fromNode.qualifiedName.lastIndexOf('::');
+      if (sep <= 0) return null; // not inside a class scope
+      classPrefix = fromNode.qualifiedName.slice(0, sep);
+    }
+    const candidates = this.context
+      .getNodesByQualifiedName(`${classPrefix}::${member}`)
+      .filter(
+        (n) =>
+          (n.kind === 'function' || n.kind === 'method') &&
+          n.filePath === ref.filePath &&
+          n.id !== ref.fromNodeId
+      );
+    if (candidates.length === 0) {
+      // Not on the class itself — possibly INHERITED. implements/extends
+      // edges don't exist yet in this pass, so retry in the supertype pass
+      // (resolveDeferredThisMemberRefs) instead of giving up.
+      this.deferredThisMemberRefs.push(ref);
+      return null;
+    }
+    const target = candidates.reduce((a, b) => (a.startLine <= b.startLine ? a : b));
+    return {
+      original: ref,
+      targetNodeId: target.id,
+      confidence: 0.95,
+      resolvedBy: 'function-ref',
+    };
+  }
+
+  /**
+   * Second pass for `this.<member>` refs whose member wasn't on the enclosing
+   * class itself (#808): once implements/extends edges exist, walk the
+   * class's supertypes (transitively, depth-capped) and resolve the member on
+   * the nearest one that declares it — `this.handleSubmit` registered in a
+   * subclass resolves to `FormBase::handleSubmit`. Validated targets only
+   * (function/method kind, same language family); no match → no edge.
+   * Mirrors resolveChainedCallsViaConformance's lifecycle. Returns the number
+   * of newly-created edges.
+   */
+  resolveDeferredThisMemberRefs(): number {
+    const deferred = this.deferredThisMemberRefs;
+    this.deferredThisMemberRefs = [];
+    if (deferred.length === 0) return 0;
+
+    this.clearCaches();
+    const resolved: ResolvedRef[] = [];
+    for (const ref of deferred) {
+      const member = ref.referenceName.slice('this.'.length);
+      const fromNode = this.queries.getNodeById(ref.fromNodeId);
+      if (!fromNode || !member) continue;
+      // Class-body-level hooks (Ruby) attribute to the CLASS node itself.
+      let className: string;
+      if (SUPERTYPE_BEARING_KINDS.has(fromNode.kind) || fromNode.kind === 'module') {
+        className = fromNode.name;
+      } else {
+        const sep = fromNode.qualifiedName.lastIndexOf('::');
+        if (sep <= 0) continue;
+        const classPrefix = fromNode.qualifiedName.slice(0, sep);
+        className = classPrefix.includes('::')
+          ? classPrefix.slice(classPrefix.lastIndexOf('::') + 2)
+          : classPrefix;
+      }
+
+      // NODE-anchored BFS up the supertype graph: start from the class node
+      // in the ref's own file (never a same-named class elsewhere — rails has
+      // a dozen `Engine`s), follow implements/extends EDGES to supertype
+      // NODES, and look members up through `contains` edges. No name-based
+      // unions anywhere — a name-keyed getSupertypes('Engine') merged every
+      // Engine's parents and produced a cross-class wrong edge on rails.
+      let frontierNodes = this.context
+        .getNodesByName(className)
+        .filter(
+          (n) =>
+            SUPERTYPE_BEARING_KINDS.has(n.kind) &&
+            n.filePath === ref.filePath
+        );
+      if (frontierNodes.length === 0) {
+        // The class itself may be declared in another file (partial/reopened
+        // classes); fall back to same-family nodes of that name.
+        frontierNodes = this.context
+          .getNodesByName(className)
+          .filter(
+            (n) =>
+              SUPERTYPE_BEARING_KINDS.has(n.kind) &&
+              sameLanguageFamily(n.language, ref.language)
+          );
+      }
+      const seenNodes = new Set<string>(frontierNodes.map((n) => n.id));
+      let target: Node | null = null;
+      for (let depth = 0; depth < 5 && frontierNodes.length > 0 && !target; depth++) {
+        const next: Node[] = [];
+        for (const typeNode of frontierNodes) {
+          for (const edge of this.queries.getOutgoingEdges(typeNode.id, ['implements', 'extends'])) {
+            const superNode = this.queries.getNodeById(edge.target);
+            if (!superNode || seenNodes.has(superNode.id)) continue;
+            seenNodes.add(superNode.id);
+            if (!SUPERTYPE_BEARING_KINDS.has(superNode.kind)) continue;
+            // Member lookup anchored on the supertype's contains edges.
+            for (const c of this.queries.getOutgoingEdges(superNode.id, ['contains'])) {
+              const m = this.queries.getNodeById(c.target);
+              if (
+                m &&
+                m.name === member &&
+                (m.kind === 'function' || m.kind === 'method') &&
+                sameLanguageFamily(m.language, ref.language)
+              ) {
+                target = m;
+                break;
+              }
+            }
+            if (target) break;
+            next.push(superNode);
+          }
+          if (target) break;
+        }
+        frontierNodes = next;
+      }
+
+      if (target) {
+        resolved.push({
+          original: ref,
+          targetNodeId: target.id,
+          confidence: 0.85,
+          resolvedBy: 'function-ref',
+        });
+      }
+    }
+    if (resolved.length === 0) return 0;
+
+    const edges = this.createEdges(resolved);
+    if (edges.length > 0) {
+      this.queries.insertEdges(edges);
+      this.clearCaches();
+    }
+    return edges.length;
+  }
+
+  private gateLanguage(result: ResolvedRef | null, ref: UnresolvedRef): ResolvedRef | null {
+    if (!result) return result;
+    const tgt = this.getLanguageFromNodeId(result.targetNodeId);
+    if (!tgt || !ref.language) return result;
+    if ((ref.referenceKind === 'references' || ref.referenceKind === 'function_ref') && !sameLanguageFamily(tgt, ref.language)) return null;
+    if (ref.referenceKind === 'imports' && crossesKnownFamily(tgt, ref.language)) return null;
+    return result;
+  }
+
+  /**
+   * Drop a FRAMEWORK-strategy resolution that crosses two *known* language
+   * families for a type-usage (`references`) or import-binding (`imports`)
+   * edge. The framework strategy is intentionally ungated for cross-language
+   * bridges, but those legitimate bridges are either `calls` edges (RN/Expo
+   * JS → native) or config↔code edges whose config side (`yaml`/`blade`/…) is
+   * not a known programming-language family. A `references`/`imports` edge
+   * between two *known* families is always a coincidental name collision — the
+   * React/Svelte/Vue PascalCase component resolvers name-match `getNodesByName`
+   * without a language check, so a TS `<TestRunner>` ref happily matched a
+   * Kotlin `class TestRunner`. Gating only the both-known-cross-family case
+   * lets config bridges and `calls` bridges through untouched.
+   */
+  private gateFrameworkLanguage(result: ResolvedRef | null, ref: UnresolvedRef): ResolvedRef | null {
+    if (!result) return result;
+    if (ref.referenceKind !== 'references' && ref.referenceKind !== 'imports') return result;
+    const tgt = this.getLanguageFromNodeId(result.targetNodeId);
+    if (tgt && ref.language && crossesKnownFamily(tgt, ref.language)) return null;
+    return result;
+  }
 }
 
 /**
diff --git a/src/resolution/lru-cache.ts b/src/resolution/lru-cache.ts
new file mode 100644
index 000000000..2a597ddbe
--- /dev/null
+++ b/src/resolution/lru-cache.ts
@@ -0,0 +1,62 @@
+/**
+ * Simple LRU cache backed by JavaScript's insertion-ordered Map.
+ *
+ * Used by ReferenceResolver to bound the per-resolver caches that
+ * previously grew without limit and OOM'd on large codebases (20k+
+ * files). Each cache is sized independently — see `index.ts` for
+ * the chosen limits per cache type.
+ *
+ * Eviction is plain LRU: on `set`, if the cache is full, the
+ * least-recently-used entry (the first one in iteration order) is
+ * evicted. Touching via `get` moves the entry to the most-recently-used
+ * position so hot keys survive eviction passes.
+ */
+export class LRUCache<K, V> {
+  private readonly max: number;
+  private readonly store = new Map<K, V>();
+
+  constructor(max: number) {
+    if (!Number.isFinite(max) || max <= 0) {
+      throw new Error(`LRUCache max must be a positive finite number, got ${max}`);
+    }
+    this.max = Math.floor(max);
+  }
+
+  get size(): number {
+    return this.store.size;
+  }
+
+  get(key: K): V | undefined {
+    const value = this.store.get(key);
+    if (value === undefined) {
+      // Distinguish "missing" from "stored undefined" by checking has().
+      // We don't store undefined in practice, but be defensive.
+      return this.store.has(key) ? value : undefined;
+    }
+    // Refresh recency by re-inserting.
+    this.store.delete(key);
+    this.store.set(key, value);
+    return value;
+  }
+
+  has(key: K): boolean {
+    return this.store.has(key);
+  }
+
+  set(key: K, value: V): void {
+    if (this.store.has(key)) {
+      this.store.delete(key);
+    } else if (this.store.size >= this.max) {
+      // Evict the oldest entry — first key in iteration order.
+      const oldest = this.store.keys().next().value;
+      if (oldest !== undefined) {
+        this.store.delete(oldest);
+      }
+    }
+    this.store.set(key, value);
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+}
diff --git a/src/resolution/name-matcher.ts b/src/resolution/name-matcher.ts
index 997a44379..9990d690d 100644
--- a/src/resolution/name-matcher.ts
+++ b/src/resolution/name-matcher.ts
@@ -15,7 +15,13 @@ export function matchByFilePath(
   ref: UnresolvedRef,
   context: ResolutionContext
 ): ResolvedRef | null {
-  if (!ref.referenceName.includes('/')) return null;
+  // Path-like (`a/b.liquid`) OR a bare filename ending in a short extension
+  // (`Foo.h` — an Objective-C `#import "Foo.h"`, resolved to the header by
+  // basename). A bare ref WITHOUT an extension is a symbol name, not a file, so
+  // leave it to the symbol-matching strategies.
+  if (!ref.referenceName.includes('/') && !/\.[A-Za-z][A-Za-z0-9]{0,3}$/.test(ref.referenceName)) {
+    return null;
+  }
 
   // Extract the filename from the path
   const fileName = ref.referenceName.split('/').pop();
@@ -38,12 +44,20 @@ export function matchByFilePath(
     };
   }
 
-  // Fall back to suffix match (e.g., ref="snippets/foo.liquid" matches "src/snippets/foo.liquid")
-  const suffixMatch = fileNodes.find(n => n.qualifiedName.endsWith(ref.referenceName) || n.filePath.endsWith(ref.referenceName));
-  if (suffixMatch) {
+  // Fall back to suffix match (e.g., ref="snippets/foo.liquid" matches
+  // "src/snippets/foo.liquid"). When several files share the basename — a
+  // `#include "RNCAsyncStorage.h"` with a same-named header on another platform
+  // (windows/code/ vs apple/) — prefer the one in the includer's own directory,
+  // then by directory proximity / same language family. A C/C++ include (and any
+  // bare-filename import) resolves relative to the including file, not to an
+  // arbitrary same-named header elsewhere in the tree.
+  const suffixMatches = fileNodes.filter(
+    n => n.qualifiedName.endsWith(ref.referenceName) || n.filePath.endsWith(ref.referenceName)
+  );
+  if (suffixMatches.length > 0) {
     return {
       original: ref,
-      targetNodeId: suffixMatch.id,
+      targetNodeId: pickClosestFileNode(suffixMatches, ref).id,
       confidence: 0.85,
       resolvedBy: 'file-path',
     };
@@ -62,6 +76,240 @@ export function matchByFilePath(
   return null;
 }
 
+/**
+ * Among several file nodes that all match a bare include/import by basename,
+ * pick the one closest to the referencing file: same directory first, then by
+ * directory-tree proximity, with the same language family as a tiebreak. A
+ * C/C++ `#include "X.h"` (and any bare-filename import) resolves relative to the
+ * including file — not to an arbitrary same-named header on another platform.
+ */
+function pickClosestFileNode(candidates: Node[], ref: UnresolvedRef): Node {
+  const dirOf = (p: string): string => {
+    const i = p.lastIndexOf('/');
+    return i >= 0 ? p.slice(0, i) : '';
+  };
+  const refDir = dirOf(ref.filePath);
+  const sameDir = candidates.filter((c) => dirOf(c.filePath) === refDir);
+  const pool = sameDir.length > 0 ? sameDir : candidates;
+  let best = pool[0]!;
+  let bestScore = -Infinity;
+  for (const c of pool) {
+    const score =
+      computePathProximity(ref.filePath, c.filePath) +
+      (sameLanguageFamily(c.language, ref.language) ? 5 : 0);
+    if (score > bestScore) {
+      bestScore = score;
+      best = c;
+    }
+  }
+  return best;
+}
+
+/**
+ * Language families that share a type system / runtime, so a same-language-only
+ * reference may still resolve across them (a Kotlin `Foo.BAR` can name a Java
+ * `Foo`). Anything not listed forms its own singleton family.
+ */
+const LANGUAGE_FAMILY: Record<string, string> = {
+  java: 'jvm', kotlin: 'jvm', scala: 'jvm',
+  swift: 'apple', objc: 'apple',
+  typescript: 'web', tsx: 'web', javascript: 'web', jsx: 'web',
+  c: 'c', cpp: 'c',
+  // Razor/Blazor markup names C# types — same family so `@model Foo` /
+  // `<MyComponent/>` resolve to their `.cs` class through the cross-family gate.
+  csharp: 'dotnet', razor: 'dotnet',
+};
+export function sameLanguageFamily(a: string, b: string): boolean {
+  if (a === b) return true;
+  const fa = LANGUAGE_FAMILY[a];
+  return fa !== undefined && fa === LANGUAGE_FAMILY[b];
+}
+/**
+ * True when `lang` belongs to a known multi-language family (jvm/apple/web/c).
+ * Languages not listed (php, python, go, ruby, rust, dart, …) and config
+ * formats (yaml/xml/blade) form their own singleton families and return
+ * `false` — used to leave config↔code framework bridges (whose config side is
+ * never a known programming-language family) out of the cross-family gate.
+ */
+export function isKnownLanguageFamily(lang: string): boolean {
+  return LANGUAGE_FAMILY[lang] !== undefined;
+}
+/**
+ * True when `a` and `b` are two DIFFERENT *known* language families — the
+ * signature of a coincidental cross-language name collision (a TS `import
+ * React` matching a Swift `import React`, a C++ `#include "X.h"` matching a
+ * same-named ObjC header on another platform). The both-*known* test is
+ * deliberately weaker than {@link sameLanguageFamily}'s negation: a
+ * single-file-component language that carries its own tag (`vue`/`svelte`)
+ * importing a `.ts` module, or any singleton-family language (php/go/ruby/…),
+ * returns `false` here and is left alone.
+ */
+export function crossesKnownFamily(a: string, b: string): boolean {
+  return isKnownLanguageFamily(a) && isKnownLanguageFamily(b) && !sameLanguageFamily(a, b);
+}
+/**
+ * Drop cross-language candidates from a name lookup. Two regimes:
+ *  - `references` (type-usage): a type named in language X resolves to a
+ *    SAME-family type, never a coincidentally same-named symbol in another
+ *    language (the Android `BatteryManager` system class vs a JS one). Strict
+ *    same-family filter — cross-language communication is `calls`, not refs.
+ *  - `imports` (import binding): an `import`/`#include` never crosses two
+ *    KNOWN families (TS `import React` ↮ Swift `import React`). Weaker
+ *    both-known filter so `.vue`/`.svelte` (own tag) importing `.ts` survives.
+ */
+function applyLanguageGate(candidates: Node[], ref: UnresolvedRef): Node[] {
+  if (ref.referenceKind === 'references' || ref.referenceKind === 'function_ref') {
+    return candidates.filter((c) => sameLanguageFamily(c.language, ref.language));
+  }
+  if (ref.referenceKind === 'imports') {
+    return candidates.filter((c) => !crossesKnownFamily(c.language, ref.language));
+  }
+  return candidates;
+}
+
+/**
+ * Resolve a function-as-value reference (#756) — a function name used as a
+ * callback/function-pointer value (`register(handler)`, `o->cb = handler`,
+ * `{ .cb = handler }`, `signal(SIGINT, handler)`). The ONLY strategy allowed
+ * for `function_ref` refs: exact name, function/method targets only, same
+ * language family, same-file first, and cross-file only when the match is
+ * UNIQUE. No fuzzy fallback, no qualified-name walking — a wrong callback
+ * edge is worse than none.
+ */
+export function matchFunctionRef(
+  ref: UnresolvedRef,
+  context: ResolutionContext
+): ResolvedRef | null {
+  // `this.<member>` refs are resolved ONLY by the class-scoped resolver in
+  // resolveOne (resolveThisMemberFnRef) — never by name matching here.
+  if (ref.referenceName.startsWith('this.')) return null;
+
+  // In JS/TS/Python a bare identifier can never be a method value (methods
+  // are only reachable through a receiver — `this.m` / `self.m` /
+  // `Cls.m`), so bare fn-refs match FUNCTIONS only. This also sidesteps the
+  // pre-existing TS quirk of class fields extracting as method-kind nodes,
+  // which otherwise soaked up local names passed as arguments (excalidraw
+  // A/B finding; same pattern in vendored docopt.py). Python's `self.m`
+  // form keeps method targets via its own capture shape. C++ likewise: a
+  // bare identifier can only be a FREE function (member values need
+  // `&Cls::method`). PHP string callables name global FUNCTIONS (methods
+  // need the `[$obj, 'm']` array form, which carries its own shape). Other
+  // languages keep method targets: C# method groups, Swift/Dart
+  // implicit-self, Java/Kotlin method references.
+  const bareFnOnly =
+    ref.language === 'typescript' || ref.language === 'tsx' ||
+    ref.language === 'javascript' || ref.language === 'jsx' ||
+    ref.language === 'cpp' || ref.language === 'python' ||
+    ref.language === 'php';
+
+  // Qualified member-pointer (`&Widget::on_click` → "Widget::on_click"):
+  // resolve the member ON THAT SCOPE — exempt from bareFnOnly (the `&Cls::m`
+  // shape is an explicit member reference). Unique-or-drop like everything else.
+  if (ref.referenceName.includes('::')) {
+    const memberName = ref.referenceName.slice(ref.referenceName.lastIndexOf('::') + 2);
+    const scoped = context
+      .getNodesByName(memberName)
+      .filter(
+        (n) =>
+          (n.kind === 'function' || n.kind === 'method') &&
+          sameLanguageFamily(n.language, ref.language) &&
+          n.id !== ref.fromNodeId &&
+          (n.qualifiedName === ref.referenceName ||
+            n.qualifiedName.endsWith(`::${ref.referenceName}`))
+      );
+    if (scoped.length === 0) return null;
+    const sameFileScoped = scoped.filter((n) => n.filePath === ref.filePath);
+    const pool = sameFileScoped.length > 0 ? sameFileScoped : scoped;
+    if (sameFileScoped.length === 0 && scoped.length > 1) return null;
+    const target = pool.reduce((a, b) => (a.startLine <= b.startLine ? a : b));
+    return {
+      original: ref,
+      targetNodeId: target.id,
+      confidence: 0.9,
+      resolvedBy: 'function-ref',
+    };
+  }
+
+  let candidates = context
+    .getNodesByName(ref.referenceName)
+    .filter(
+      (n) =>
+        (n.kind === 'function' || (!bareFnOnly && n.kind === 'method')) &&
+        sameLanguageFamily(n.language, ref.language) &&
+        n.id !== ref.fromNodeId // a function registering itself is not a dependency edge
+    );
+  if (candidates.length === 0) return null;
+
+  // Swift implicit-self: a bare identifier can name a METHOD only of the
+  // ENCLOSING type (`Button(action: handleTap)` written inside that type) —
+  // a same-named method on any OTHER class is a parameter collision
+  // (Alamofire: a `request` parameter resolving to EventMonitor::request).
+  // Scope method candidates to the from-symbol's type; top-level code has no
+  // implicit self, so method targets are excluded there entirely. Free
+  // functions are unaffected.
+  if (ref.language === 'swift' && candidates.some((n) => n.kind === 'method')) {
+    const fromNode = context.getNodeById?.(ref.fromNodeId);
+    const sep = fromNode ? fromNode.qualifiedName.lastIndexOf('::') : -1;
+    const classPrefix = fromNode && sep > 0 ? fromNode.qualifiedName.slice(0, sep) : null;
+    candidates = candidates.filter((n) => {
+      if (n.kind !== 'method') return true;
+      if (!classPrefix) return false;
+      const mSep = n.qualifiedName.lastIndexOf('::');
+      if (mSep <= 0) return false;
+      const methodPrefix = n.qualifiedName.slice(0, mSep);
+      // Accept exact-scope matches plus suffix relationships either way, so
+      // extension-declared members (`Holder::m`) still match a nested
+      // from-scope (`Module::Holder::wire`) and vice versa.
+      return (
+        methodPrefix === classPrefix ||
+        methodPrefix.endsWith(`::${classPrefix}`) ||
+        classPrefix.endsWith(`::${methodPrefix}`)
+      );
+    });
+    if (candidates.length === 0) return null;
+  }
+
+  // Same-file definition wins — the extraction gate guarantees most survivors
+  // have one, and it's the dominant C pattern (static callback registered in
+  // a same-file ops struct).
+  const sameFile = candidates.filter((n) => n.filePath === ref.filePath);
+  if (sameFile.length > 0) {
+    // Swift: several same-named METHODS in one file is an API overload family
+    // (`Session.request(...)` × N), and a bare identifier hitting it is almost
+    // always a same-named parameter, not a method value (Alamofire A/B
+    // finding) — refuse rather than guess. A single method (SwiftUI's
+    // `action: handleTap`) still resolves.
+    if (
+      ref.language === 'swift' &&
+      sameFile.length > 1 &&
+      sameFile.every((n) => n.kind === 'method')
+    ) {
+      return null;
+    }
+    // Same-name overloads in one file are the same conceptual symbol; pick
+    // the first by position for determinism.
+    const target = sameFile.reduce((a, b) => (a.startLine <= b.startLine ? a : b));
+    return {
+      original: ref,
+      targetNodeId: target.id,
+      confidence: sameFile.length === 1 ? 0.95 : 0.9,
+      resolvedBy: 'function-ref',
+    };
+  }
+
+  // Cross-file (imported names the import resolver didn't already claim):
+  // only an unambiguous match resolves.
+  if (candidates.length === 1) {
+    return {
+      original: ref,
+      targetNodeId: candidates[0]!.id,
+      confidence: 0.8,
+      resolvedBy: 'function-ref',
+    };
+  }
+  return null;
+}
+
 /**
  * Try to resolve a reference by exact name match
  */
@@ -69,7 +317,7 @@ export function matchByExactName(
   ref: UnresolvedRef,
   context: ResolutionContext
 ): ResolvedRef | null {
-  const candidates = context.getNodesByName(ref.referenceName);
+  const candidates = applyLanguageGate(context.getNodesByName(ref.referenceName), ref);
 
   if (candidates.length === 0) {
     return null;
@@ -146,6 +394,536 @@ export function matchByQualifiedName(
   return null;
 }
 
+function resolveMethodOnType(
+  typeName: string,
+  methodName: string,
+  ref: UnresolvedRef,
+  context: ResolutionContext,
+  confidence: number,
+  resolvedBy: ResolvedRef['resolvedBy'],
+  /**
+   * Optional FQN that identifies WHICH class declaration `typeName`
+   * refers to in the caller's file. When multiple candidates share
+   * the same qualifiedName (`FooConverter::convert` in both
+   * `dao/converter/` and `service/converter/`), the FQN's
+   * file-path-suffix picks the right one — the disambiguation
+   * signal Java imports carry but the call site doesn't (#314).
+   */
+  preferredFqn?: string,
+  /** Recursion guard for the supertype/conformance walk. */
+  depth = 0,
+): ResolvedRef | null {
+  // Look up methods by name and match by qualifiedName ending in
+  // `<typeName>::<methodName>`. This works whether the method is defined
+  // in-class (`class Foo { int bar() { ... } }`) or out-of-line in a separate
+  // file (`int Foo::bar() { ... }` in foo.cpp while class Foo is in foo.hpp).
+  // The previous same-file approach missed the latter — the typical C++ layout.
+  const methodCandidates = context.getNodesByName(methodName);
+  const want = `${typeName}::${methodName}`;
+  const matches: Node[] = [];
+  for (const m of methodCandidates) {
+    if (m.kind !== 'method') continue;
+    if (m.language !== ref.language) continue;
+    const qn = m.qualifiedName;
+    if (qn === want || qn.endsWith(`::${want}`)) {
+      matches.push(m);
+    }
+  }
+  if (matches.length === 0) {
+    // Conformance fallback: the method may be defined on a supertype `typeName`
+    // extends, or on a protocol / trait it conforms to (e.g. a Swift protocol-
+    // extension method, a C# default-interface or extension method, a Kotlin
+    // extension on a supertype). Walk supertypes transitively (depth-capped) via
+    // the resolved implements/extends edges — empty in the first resolution pass,
+    // populated in the conformance pass. Still VALIDATED (the method must exist on
+    // a supertype), so a wrong inference produces no edge.
+    if (depth < 4 && context.getSupertypes) {
+      for (const supertype of context.getSupertypes(typeName, ref.language)) {
+        const via = resolveMethodOnType(
+          supertype, methodName, ref, context, confidence, resolvedBy, preferredFqn, depth + 1,
+        );
+        if (via) return via;
+      }
+    }
+    return null;
+  }
+
+  if (matches.length > 1 && preferredFqn) {
+    const ext = ref.language === 'kotlin' ? '.kt' : '.java';
+    const fqnPath = preferredFqn.replace(/\./g, '/') + ext;
+    const chosen = matches.find((m) => {
+      const fp = m.filePath.replace(/\\/g, '/');
+      return fp.endsWith(fqnPath) || fp.endsWith('/' + fqnPath);
+    });
+    if (chosen) {
+      return {
+        original: ref,
+        targetNodeId: chosen.id,
+        confidence,
+        resolvedBy,
+      };
+    }
+  }
+
+  return {
+    original: ref,
+    targetNodeId: matches[0]!.id,
+    confidence,
+    resolvedBy,
+  };
+}
+
+// C++ keywords/control-flow tokens that can appear right before a receiver
+// (e.g. `return ptr->m()`) and must NOT be treated as a type.
+const CPP_NON_TYPE_TOKENS = new Set([
+  'return', 'if', 'else', 'for', 'while', 'do', 'switch', 'case', 'default',
+  'break', 'continue', 'goto', 'throw', 'new', 'delete', 'co_await', 'co_yield',
+  'co_return', 'static_cast', 'const_cast', 'dynamic_cast', 'reinterpret_cast',
+  'sizeof', 'alignof', 'typeid', 'and', 'or', 'not', 'xor',
+]);
+
+function normalizeCppTypeName(typeName: string): string | null {
+  const normalized = typeName
+    .replace(/\b(const|volatile|mutable|typename|class|struct)\b/g, ' ')
+    .replace(/[&*]+/g, ' ')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  if (!normalized) return null;
+  const parts = normalized.split(/::/).filter(Boolean);
+  const last = parts[parts.length - 1];
+  if (!last) return null;
+  if (CPP_NON_TYPE_TOKENS.has(last)) return null;
+  return last;
+}
+
+// Declarator regex: matches `Type receiver`, `Type* receiver`, `Type *receiver`,
+// `Type*receiver`, `Type<X> receiver`, etc., REQUIRING a declarator terminator
+// (`;`, `=`, `,`, `)`, `[`, `{`, `(`, or end-of-line) after the receiver. The
+// terminator rules out uses like `return receiver->m()` where the preceding
+// token is a keyword, not a type.
+function buildDeclaratorRegex(escapedReceiver: string): RegExp {
+  return new RegExp(
+    `([A-Za-z_][\\w:]*(?:\\s*<[^;=(){}]+>)?(?:\\s*[*&]+)?)\\s*\\b${escapedReceiver}\\b\\s*(?=[;=,)\\[{(]|$)`,
+  );
+}
+
+function inferCppReceiverType(
+  receiverName: string,
+  ref: UnresolvedRef,
+  context: ResolutionContext,
+  depth = 0,
+): string | null {
+  const source = context.readFile(ref.filePath);
+  if (!source) return null;
+
+  const lines = source.split(/\r?\n/);
+  const callLineIndex = Math.max(0, Math.min(lines.length - 1, ref.line - 1));
+  const escapedReceiver = receiverName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const receiverPattern = new RegExp(`\\b${escapedReceiver}\\b`);
+  const declaratorRegex = buildDeclaratorRegex(escapedReceiver);
+
+  for (let i = callLineIndex; i >= 0; i--) {
+    const line = lines[i];
+    if (!line || !receiverPattern.test(line)) continue;
+
+    const declaratorMatch = line.match(declaratorRegex);
+    if (declaratorMatch) {
+      const normalized = normalizeCppTypeName(declaratorMatch[1] ?? '');
+      if (normalized === 'auto') {
+        // `auto x = Foo::instance();` — the declared type is deduced; recover it
+        // from the initializer (call return type / construction) (#645).
+        const initType = inferCppAutoInitializerType(line, receiverName, ref, context, depth);
+        if (initType) return initType;
+        // No usable initializer on this line — keep scanning earlier ones.
+      } else if (normalized) {
+        return normalized;
+      }
+    }
+  }
+
+  const headerCandidates = [
+    ref.filePath.replace(/\.(?:c|cc|cpp|cxx)$/i, '.h'),
+    ref.filePath.replace(/\.(?:c|cc|cpp|cxx)$/i, '.hpp'),
+    ref.filePath.replace(/\.(?:c|cc|cpp|cxx)$/i, '.hxx'),
+  ].filter((candidate, index, arr) => arr.indexOf(candidate) === index && candidate !== ref.filePath);
+
+  for (const headerPath of headerCandidates) {
+    if (!context.fileExists(headerPath)) continue;
+    const headerSource = context.readFile(headerPath);
+    if (!headerSource) continue;
+
+    for (const line of headerSource.split(/\r?\n/)) {
+      if (!receiverPattern.test(line)) continue;
+      const declaratorMatch = line.match(declaratorRegex);
+      if (!declaratorMatch) continue;
+      const normalized = normalizeCppTypeName(declaratorMatch[1] ?? '');
+      if (normalized && normalized !== 'auto') return normalized;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Last `::`-separated segment of a (possibly namespace-qualified) C++ name.
+ */
+function cppLastSegment(name: string): string {
+  const parts = name.split('::').filter(Boolean);
+  return parts[parts.length - 1] ?? name;
+}
+
+/**
+ * Return type captured at extraction for `Class::method` (or a free function),
+ * read off the indexed node's `returnType` — used by the C++ (#645) and PHP
+ * (#608) chained-call resolvers. Language-filtered. Null when not indexed or no
+ * return type was recorded (a `void`/primitive return).
+ */
+function lookupCalleeReturnType(
+  callee: string,
+  ref: UnresolvedRef,
+  context: ResolutionContext,
+): string | null {
+  let method = callee;
+  let cls: string | null = null;
+  if (callee.includes('::')) {
+    const parts = callee.split('::').filter(Boolean);
+    method = parts[parts.length - 1] ?? callee;
+    cls = parts.slice(0, -1).join('::');
+  }
+  const candidates = context.getNodesByName(method).filter(
+    (n) =>
+      (n.kind === 'method' || n.kind === 'function') &&
+      n.language === ref.language &&
+      !!n.returnType,
+  );
+  if (cls) {
+    const want = `${cls}::${method}`;
+    // The call site may name the class with MORE namespace qualification than
+    // the stored node (`details::registry::instance` at the call vs
+    // `registry::instance` on the node — the receiver type only carries the
+    // immediate class), or LESS. Accept an exact match or either being a
+    // namespace-suffix of the other; the shared `::<class>::<method>` tail keeps
+    // it specific.
+    const m = candidates.find(
+      (n) =>
+        n.qualifiedName === want ||
+        n.qualifiedName.endsWith(`::${want}`) ||
+        want.endsWith(`::${n.qualifiedName}`),
+    );
+    return m?.returnType ?? null;
+  }
+  return candidates.find((n) => n.kind === 'function')?.returnType ?? null;
+}
+
+/** Does the graph contain a class/struct named `name`'s last segment? */
+function cppClassExists(name: string, ref: UnresolvedRef, context: ResolutionContext): boolean {
+  const last = cppLastSegment(name);
+  return context
+    .getNodesByName(last)
+    .some((n) => (n.kind === 'class' || n.kind === 'struct') && n.language === ref.language);
+}
+
+/**
+ * Infer the class produced by a C++ call/construction expression, using return
+ * types captured at extraction (#645). Handles, in order:
+ *   - `make_unique<T>()` / `make_shared<T>()`        → T
+ *   - single-level member call `recv.method()`       → recv's type, then method's return
+ *   - `Class::method()` / free `func()`              → the callee's recorded return type
+ *   - direct construction `Type()` / `ns::Type()`    → Type
+ * Returns null when undeterminable. Callers MUST still validate the outer method
+ * exists on the result before creating an edge, so a wrong guess stays silent.
+ */
+function resolveCppCallResultType(
+  inner: string,
+  ref: UnresolvedRef,
+  context: ResolutionContext,
+  depth = 0,
+): string | null {
+  if (depth > 3) return null; // guard against pathological mutual recursion
+  const expr = inner.trim();
+
+  const make = expr.match(/(?:^|::)(?:make_unique|make_shared)\s*<\s*([A-Za-z_]\w*)/);
+  if (make) return make[1] ?? null;
+
+  // Single-level member call `recv.method` (the `manager.view().render()` shape).
+  const dotIdx = expr.lastIndexOf('.');
+  if (dotIdx > 0) {
+    const recv = expr.slice(0, dotIdx);
+    const method = expr.slice(dotIdx + 1);
+    if (recv.includes('.') || recv.includes('(') || recv.includes('::')) return null; // single level only
+    const recvType = inferCppReceiverType(recv, ref, context, depth + 1);
+    if (!recvType) return null;
+    return lookupCalleeReturnType(`${recvType}::${method}`, ref, context);
+  }
+
+  const ret = lookupCalleeReturnType(expr, ref, context);
+  if (ret) return ret;
+
+  // Direct construction — the callee itself names a class/struct.
+  if (cppClassExists(expr, ref, context)) return cppLastSegment(expr);
+
+  return null;
+}
+
+/**
+ * Recover the type of an `auto`-declared local from its initializer on the
+ * declaration line — `auto x = Foo::instance();`, `auto w = make_unique<W>();`,
+ * `auto p = new W();`, `auto w = Widget();` (#645).
+ */
+function inferCppAutoInitializerType(
+  line: string,
+  receiverName: string,
+  ref: UnresolvedRef,
+  context: ResolutionContext,
+  depth: number,
+): string | null {
+  const escaped = receiverName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const m = line.match(new RegExp(`\\b${escaped}\\b\\s*=\\s*([^;]+)`));
+  if (!m || !m[1]) return null;
+  const init = m[1].trim();
+
+  const neu = init.match(/^new\s+([A-Za-z_][\w:]*)/);
+  if (neu && neu[1]) return cppLastSegment(neu[1]);
+
+  // A call or construction: `Foo(...)`, `A::b(...)`, `make_unique<T>(...)`.
+  const call = init.match(/^([A-Za-z_][\w:]*(?:\s*<[^>;]*>)?)\s*\(/);
+  if (call && call[1]) return resolveCppCallResultType(call[1].replace(/\s+/g, ''), ref, context, depth + 1);
+
+  return null;
+}
+
+/**
+ * Resolve a C++ chained call whose receiver is itself a call — encoded by the
+ * extractor as `<innerCallee>().<method>` (#645). The receiver's type is what
+ * the inner call returns; the outer method is then resolved and VALIDATED on it
+ * (resolveMethodOnType requires `cls::method` to exist), so a wrong inference
+ * produces no edge rather than a wrong one.
+ */
+export function matchCppCallChain(
+  ref: UnresolvedRef,
+  context: ResolutionContext,
+): ResolvedRef | null {
+  const m = ref.referenceName.match(/^(.+)\(\)\.(\w+)$/);
+  if (!m || !m[1] || !m[2]) return null;
+  const cls = resolveCppCallResultType(m[1], ref, context);
+  if (!cls) return null;
+  return resolveMethodOnType(cls, m[2], ref, context, 0.85, 'instance-method');
+}
+
+/**
+ * Resolve a `::`-scoped factory chain whose receiver is a scoped/static call —
+ * PHP `Cls::for($x)->method()` (#608, the per-credential Laravel client idiom) or
+ * Rust `Foo::new().bar()` (an associated-function call) — both encoded by the
+ * extractor as `Cls::factory().method`. The receiver's type is what `Cls::factory`
+ * returns: a `self` marker (PHP `: self`/`: static`, Rust `-> Self`) resolves to
+ * the factory's own type, a concrete return type to that type. The outer method is
+ * then resolved and VALIDATED on it (resolveMethodOnType requires the method to
+ * exist on the type or a supertype it conforms to), so a wrong inference yields no
+ * edge rather than a wrong one. Shared by the `::`-receiver languages (PHP, Rust).
+ */
+export function matchScopedCallChain(
+  ref: UnresolvedRef,
+  context: ResolutionContext,
+): ResolvedRef | null {
+  const m = ref.referenceName.match(/^(.+)\(\)\.(\w+)$/);
+  if (!m || !m[1] || !m[2]) return null;
+  const inner = m[1];
+  const method = m[2];
+  if (!inner.includes('::')) return null; // only static-factory (`Cls::method`) chains
+  const factoryClass = inner.slice(0, inner.lastIndexOf('::'));
+  const ret = lookupCalleeReturnType(inner, ref, context);
+  if (!ret) return null;
+  // `self` (the extractor's marker for self/static/$this) → the factory's class.
+  const resolvedClass = ret === 'self' ? factoryClass : ret;
+  return resolveMethodOnType(resolvedClass, method, ref, context, 0.85, 'instance-method');
+}
+
+/**
+ * Languages where an unprefixed capitalized call `Foo(args)` constructs the
+ * class (so a `Foo(args).method()` receiver's type is `Foo`). Java/C# need `new`,
+ * so a bare `Foo()` there is a method call, not construction — excluded. Scala's
+ * `Foo(args)` is a case-class / companion `apply`, which conventionally returns
+ * `Foo` — and resolveMethodOnType validates, so a non-conventional `apply` that
+ * returns another type simply yields no edge rather than a wrong one. Pascal/Delphi:
+ * a `TFoo(x)` is a TYPECAST whose result is a `TFoo`, so `TFoo(x).method()` resolves
+ * the method on `TFoo` — same shape, same validation.
+ */
+const CONSTRUCTS_VIA_BARE_CALL = new Set(['kotlin', 'swift', 'scala', 'dart', 'pascal']);
+
+/**
+ * Resolve a dotted chained call whose receiver is a static factory / fluent call —
+ * `Foo.getInstance().bar()`, encoded by the extractor as `Foo.getInstance().bar`
+ * (#645/#608 mechanism). The receiver's type is what `Foo.getInstance` returns
+ * (its declared return type); the outer method is then resolved and VALIDATED on
+ * it (resolveMethodOnType requires `Type::method` to exist), so a wrong inference
+ * yields no edge rather than a wrong one (e.g. a same-named `bar()` on an
+ * unrelated class is never matched). Shared by the dot-notation languages
+ * (Java, Kotlin, C#, Swift) — same receiver shape, same `Class::method` qualified names.
+ */
+export function matchDottedCallChain(
+  ref: UnresolvedRef,
+  context: ResolutionContext,
+): ResolvedRef | null {
+  const m = ref.referenceName.match(/^(.+)\(\)\.(\w+)$/);
+  if (!m || !m[1] || !m[2]) return null;
+  const inner = m[1]; // `Foo.getInstance`
+  const method = m[2]; // `bar`
+  const lastDot = inner.lastIndexOf('.');
+
+  if (lastDot <= 0) {
+    // Go: bare package-level factory FUNCTION `New().method()` — the receiver's
+    // type is what `New` returns; resolve the method on that.
+    if (ref.language === 'go') {
+      const ret = lookupCalleeReturnType(inner, ref, context);
+      if (ret) {
+        return resolveMethodOnType(ret, method, ref, context, 0.85, 'instance-method', importedFqnOf(ret, ref, context));
+      }
+      // `inner` isn't a function with a captured return type — typically a
+      // package-level VARIABLE holding a function value (e.g. gin's `engine()`),
+      // whose type we can't recover. Fall back to bare-name resolution of the
+      // method so we don't DROP an edge the un-re-encoded bare path would have
+      // found. (When `inner` IS a real factory function but the method doesn't
+      // exist on its return type, `ret` is truthy and we returned no edge above —
+      // the absent-method safety guarantee is preserved.)
+      //
+      // CRITICAL: resolve the TARGET via a synthetic bare-name ref, but return the
+      // match tied to the ORIGINAL `ref` (referenceName `inner().method`). The
+      // batched resolver (resolveAndPersistBatched) reads unresolved rows from
+      // offset 0 every pass and relies on deleteSpecificResolvedReferences —
+      // keyed on referenceName — to clear each resolved row so the batch empties.
+      // If we propagated the synthetic ref's bare `method` as `.original`, the
+      // delete would never match the stored `inner().method` row, the batch would
+      // never drain, and the loop would re-resolve + re-insert forever (a runaway
+      // that grew gin's graph to 5M edges / 1.4 GB before this fix).
+      const bareRef = { ...ref, referenceName: method };
+      const bareMatch = matchByExactName(bareRef, context) ?? matchFuzzy(bareRef, context);
+      return bareMatch ? { ...bareMatch, original: ref } : null;
+    }
+    // Constructor receiver `Foo(args).method()` (encoded `Foo().method`): a bare,
+    // capitalized inner is a class construction, so the receiver's type is the
+    // class itself — resolve the method on it. Only in languages where an
+    // unprefixed capitalized call constructs the class (Kotlin, Swift); in Java/C#
+    // a bare `Foo()` is a method call (constructors need `new`), so we must not
+    // assume construction. A lowercase bare inner is a top-level `factory().method()`
+    // whose type we can't recover — bail.
+    if (!CONSTRUCTS_VIA_BARE_CALL.has(ref.language) || !/^[A-Z]/.test(inner)) return null;
+    return resolveMethodOnType(inner, method, ref, context, 0.85, 'instance-method', importedFqnOf(inner, ref, context));
+  }
+
+  // Factory/fluent receiver `Receiver.factory(args).method()`: the receiver's
+  // type is what `Receiver.factory` returns (its declared return type).
+  const factoryClass = inner.slice(0, lastDot).split('.').pop(); // simple class name
+  const factoryMethod = inner.slice(lastDot + 1);
+  if (!factoryClass || !factoryMethod) return null;
+  const ret = lookupCalleeReturnType(`${factoryClass}::${factoryMethod}`, ref, context);
+  if (!ret) {
+    // Objective-C: a class-message factory — `[X alloc]`, `[X new]`,
+    // `[X sharedFoo]` — returns an instance of the RECEIVER class `X` by
+    // convention (`instancetype`). So when the factory's own return type isn't
+    // recoverable (its selector returns `instancetype`, or `alloc`/`new` aren't
+    // user-defined nodes at all), the receiver's type is the class `X` itself.
+    // This resolves the ubiquitous `[[X alloc] init]` and singleton chains.
+    // resolveMethodOnType validates against X (and its supertypes), so a class
+    // whose method actually lives elsewhere yields NO edge, not a wrong one — and
+    // crucially this does NOT fire when a concrete return type WAS captured but
+    // simply lacks the method (that already returned null above: absent-method
+    // safety, so a same-named decoy is still never matched).
+    if (ref.language === 'objc' && /^[A-Z]/.test(factoryClass)) {
+      return resolveMethodOnType(factoryClass, method, ref, context, 0.8, 'instance-method', importedFqnOf(factoryClass, ref, context));
+    }
+    // Pascal/Delphi: the extractor only re-encodes a `TFoo`/`IFoo`-prefixed chain
+    // (the type-naming convention), so `factoryClass` is always a real class here.
+    // A factory whose return type wasn't captured is a CONSTRUCTOR
+    // (`TFileMem.Create().SetCachePerformance` — `constructor Create` has no `:
+    // TBar` annotation but returns its own class) or an unannotated function. In
+    // both cases the receiver's type is the class itself, so resolve the method on
+    // `factoryClass`. resolveMethodOnType validates against it (and its
+    // supertypes), so a wrong inference yields no edge — and this never fires when
+    // a return type WAS captured but lacks the method (absent-method safety above).
+    if (ref.language === 'pascal' && /^[TI]/.test(factoryClass)) {
+      return resolveMethodOnType(factoryClass, method, ref, context, 0.8, 'instance-method', importedFqnOf(factoryClass, ref, context));
+    }
+    return null;
+  }
+  return resolveMethodOnType(ret, method, ref, context, 0.85, 'instance-method', importedFqnOf(ret, ref, context));
+}
+
+/**
+ * When several classes share a simple type name, the caller file's import of
+ * that type is the only signal that names WHICH one (#314). Returns the imported
+ * FQN for `typeName` in the ref's file, or undefined.
+ */
+function importedFqnOf(
+  typeName: string,
+  ref: UnresolvedRef,
+  context: ResolutionContext,
+): string | undefined {
+  const imports = context.getImportMappings(ref.filePath, ref.language);
+  return imports.find((i) => i.localName === typeName)?.source;
+}
+
+/**
+ * Java/Kotlin: infer a receiver's declared type by walking field declarations
+ * in the class enclosing the call site. The field's `signature` is already in
+ * the form "<TypeName> <fieldName>" (set by tree-sitter.ts extractField), so we
+ * pull the type from there. Handles Spring `@Resource UserBO userbo;` /
+ * `@Autowired private UserService userService;` where the receiver field name
+ * doesn't match the class name by Java naming convention.
+ *
+ * Returns the bare type name (generics stripped, dotted package stripped) or
+ * null when no matching field is in the enclosing class.
+ */
+function inferJavaFieldReceiverType(
+  receiverName: string,
+  ref: UnresolvedRef,
+  context: ResolutionContext,
+): string | null {
+  const inFile = context.getNodesInFile(ref.filePath);
+  if (inFile.length === 0) return null;
+
+  // Find the class enclosing the call line (tightest match by latest start).
+  let enclosing: Node | null = null;
+  for (const n of inFile) {
+    if (n.kind !== 'class' && n.kind !== 'interface') continue;
+    if (n.language !== ref.language) continue;
+    const end = n.endLine ?? n.startLine;
+    if (n.startLine <= ref.line && end >= ref.line) {
+      if (!enclosing || n.startLine >= enclosing.startLine) enclosing = n;
+    }
+  }
+  if (!enclosing) return null;
+
+  const enclosingEnd = enclosing.endLine ?? enclosing.startLine;
+  const field = inFile.find(
+    (n) =>
+      n.kind === 'field' &&
+      n.name === receiverName &&
+      n.language === ref.language &&
+      n.startLine >= enclosing.startLine &&
+      (n.endLine ?? n.startLine) <= enclosingEnd,
+  );
+  if (!field || !field.signature) return null;
+
+  // Signature shape: "<TypeName> <fieldName>" (extractField). Pull the type,
+  // strip generics + dotted package, drop array/varargs markers.
+  const beforeName = field.signature.slice(
+    0,
+    field.signature.lastIndexOf(field.name),
+  );
+  const typeRaw = beforeName.trim();
+  if (!typeRaw) return null;
+
+  const typeNoGenerics = typeRaw.replace(/<[^>]*>/g, '').trim();
+  const typeNoArray = typeNoGenerics.replace(/\[\s*\]/g, '').replace(/\.\.\.$/, '').trim();
+  const parts = typeNoArray.split(/[.\s]+/).filter(Boolean);
+  const lastPart = parts[parts.length - 1];
+  if (!lastPart) return null;
+  if (!/^[A-Z]/.test(lastPart)) return null; // primitives / lowercase → skip
+  return lastPart;
+}
+
 /**
  * Try to resolve by method name on a class/object
  */
@@ -153,8 +931,16 @@ export function matchMethodCall(
   ref: UnresolvedRef,
   context: ResolutionContext
 ): ResolvedRef | null {
-  // Parse method call patterns like "obj.method" or "Class::method"
-  const dotMatch = ref.referenceName.match(/^(\w+)\.(\w+)$/);
+  // Parse method call patterns like "obj.method" or "Class::method". The method
+  // part allows trailing `:` keywords so Objective-C selectors resolve
+  // (`SDImageCache.storeImage:`, `obj.setX:y:`); colons never appear in other
+  // languages' method refs, so this is a no-op for them.
+  // The receiver allows dots (`builder.Services.AddCoreServices`) so a CHAINED
+  // call resolves by its last segment — Strategy 3 below name-matches the method
+  // (with its existing single-candidate / receiver-overlap guards). Without this
+  // a multi-dot extension-method call (C# DI `builder.Services.AddCoreServices()`,
+  // `Guard.Against.X()`) matched no pattern and never resolved.
+  const dotMatch = ref.referenceName.match(/^([\w.]+)\.(\w+:?(?:\w+:)*)$/);
   const colonMatch = ref.referenceName.match(/^(\w+)::(\w+)$/);
 
   const match = dotMatch || colonMatch;
@@ -164,6 +950,51 @@ export function matchMethodCall(
 
   const [, objectOrClass, methodName] = match;
 
+  if (ref.language === 'cpp' && dotMatch) {
+    const inferredType = inferCppReceiverType(objectOrClass!, ref, context);
+    if (inferredType) {
+      const typedMatch = resolveMethodOnType(
+        inferredType,
+        methodName!,
+        ref,
+        context,
+        0.9,
+        'instance-method',
+      );
+      if (typedMatch) {
+        return typedMatch;
+      }
+    }
+  }
+
+  // Java/Kotlin: receiver may be a field whose name doesn't match the type by
+  // Java naming convention (`userbo` → class `UserBO`, abbreviated). Look up
+  // the field in the enclosing class to get its declared type, then resolve
+  // the method on that type. Covers Spring `@Resource`/`@Autowired` field
+  // injection where the field type is the concrete bean class.
+  if ((ref.language === 'java' || ref.language === 'kotlin') && dotMatch) {
+    const inferredType = inferJavaFieldReceiverType(objectOrClass!, ref, context);
+    if (inferredType) {
+      // When two classes share the same simple name, the caller file's
+      // import is the only signal that names WHICH one — pass the
+      // imported FQN so resolveMethodOnType can disambiguate (#314).
+      const imports = context.getImportMappings(ref.filePath, ref.language);
+      const importedFqn = imports.find((i) => i.localName === inferredType)?.source;
+      const typedMatch = resolveMethodOnType(
+        inferredType,
+        methodName!,
+        ref,
+        context,
+        0.9,
+        'instance-method',
+        importedFqn,
+      );
+      if (typedMatch) {
+        return typedMatch;
+      }
+    }
+  }
+
   // Strategy 1: Direct class name match (existing logic)
   const classCandidates = context.getNodesByName(objectOrClass!);
 
@@ -410,7 +1241,7 @@ export function matchFuzzy(
 
   // Filter to callable kinds only (function, method, class)
   const callableKinds = new Set(['function', 'method', 'class']);
-  const callableCandidates = candidates.filter((n) => callableKinds.has(n.kind));
+  const callableCandidates = applyLanguageGate(candidates.filter((n) => callableKinds.has(n.kind)), ref);
 
   // Prefer same-language matches
   const sameLanguageCandidates = callableCandidates.filter(n => n.language === ref.language);
@@ -436,6 +1267,13 @@ export function matchReference(
   ref: UnresolvedRef,
   context: ResolutionContext
 ): ResolvedRef | null {
+  // Function-as-value refs (#756) resolve ONLY through the dedicated matcher —
+  // never the fuzzy/qualified fallthrough below (a wrong callback edge is
+  // worse than none).
+  if (ref.referenceKind === 'function_ref') {
+    return matchFunctionRef(ref, context);
+  }
+
   // Try strategies in order of confidence
   let result: ResolvedRef | null;
 
@@ -447,6 +1285,45 @@ export function matchReference(
   result = matchByQualifiedName(ref, context);
   if (result) return result;
 
+  // 1b. C++ chained call whose receiver is another call — `Foo::instance().bar()`
+  // encoded as `Foo::instance().bar` by the extractor (#645). Resolve the
+  // receiver's type from what the inner call returns, then the method on it.
+  if (ref.language === 'cpp' || ref.language === 'c') {
+    result = matchCppCallChain(ref, context);
+    if (result) return result;
+  }
+
+  // 1c. `::`-scoped factory chain — PHP `Cls::for($x)->method()` (#608) or Rust
+  // `Foo::new().bar()`, both encoded as `Cls::factory().method`. The receiver's
+  // type is the factory's `self` (PHP `: self`/`: static`, Rust `-> Self`) or
+  // concrete return type.
+  if (ref.language === 'php' || ref.language === 'rust') {
+    result = matchScopedCallChain(ref, context);
+    if (result) return result;
+  }
+
+  // 1d. Dotted chained static-factory / fluent call (Java / Kotlin / C# / Swift /
+  // Go / Scala / Dart / Objective-C) — `Foo.getInstance().bar()` encoded as
+  // `Foo.getInstance().bar`, Go's bare-factory `New().Method()` as `New().Method`,
+  // Scala's companion factory, Dart's static factory / factory-constructor, or
+  // ObjC's chained message send `[[Foo create] doIt]` encoded as `Foo.create().doIt`
+  // (#645/#608 mechanism). Resolve the method's class from the inner call's
+  // declared return type, then validate it.
+  if (
+    ref.language === 'java' ||
+    ref.language === 'kotlin' ||
+    ref.language === 'csharp' ||
+    ref.language === 'swift' ||
+    ref.language === 'go' ||
+    ref.language === 'scala' ||
+    ref.language === 'dart' ||
+    ref.language === 'objc' ||
+    ref.language === 'pascal'
+  ) {
+    result = matchDottedCallChain(ref, context);
+    if (result) return result;
+  }
+
   // 2. Method call pattern
   result = matchMethodCall(ref, context);
   if (result) return result;
diff --git a/src/resolution/swift-objc-bridge.ts b/src/resolution/swift-objc-bridge.ts
new file mode 100644
index 000000000..95db99316
--- /dev/null
+++ b/src/resolution/swift-objc-bridge.ts
@@ -0,0 +1,276 @@
+/**
+ * Swift ↔ Objective-C bridging rules.
+ *
+ * Apple's auto-bridging mechanism exposes Swift declarations to the ObjC
+ * runtime under a deterministic selector name. The full rule set:
+ * https://developer.apple.com/documentation/swift/importing-swift-into-objective-c
+ *
+ * This module is **pure name math** — given a Swift declaration's base name
+ * + parameter external labels (or the raw signature text), produce the
+ * bridged ObjC selector(s); given an ObjC selector, produce the
+ * candidate Swift base names. No graph/DB access here.
+ *
+ * Used by `frameworks/swift-objc.ts` (the framework resolver that wires
+ * the rules into the resolution pipeline) and by its tests.
+ *
+ * ─── Bridging cheat sheet ───────────────────────────────────────────────
+ *
+ *   Swift declaration                             ObjC selector
+ *   ─────────────────────────────────────────     ─────────────────────────
+ *   func play()                                    play
+ *   func play(_ song: String)                      play:
+ *   func play(song: String)                        playWithSong:
+ *   func play(_ song: String, by artist: String)   play:by:
+ *   func play(song: String, by artist: String)     playWithSong:by:
+ *   init(name: String)                             initWithName:
+ *   init(name: String, age: Int)                   initWithName:age:
+ *   var name: String  (getter / setter)            name  /  setName:
+ *   @objc(custom:) func f(_ x: Int)                custom:        (literal override)
+ *
+ * The reverse direction (ObjC → Swift) collapses the bridge: a Swift call
+ * site for `play(song:)` reaches us as the bare base name `play` (Swift's
+ * tree-sitter call_expression strips parameter labels from the callee
+ * name). So `swiftBaseNamesForObjcSelector('playWithSong:')` returns
+ * `['play']` — the resolver looks up Swift methods named `play`.
+ */
+
+/**
+ * Capitalize the first character of a string. Used for the "With"-prefix
+ * form on the first selector keyword when the Swift declaration has an
+ * explicit first-parameter label (e.g. `func play(song:)` → `playWithSong:`).
+ */
+function capFirst(s: string): string {
+  return s.length > 0 ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+
+/**
+ * Lowercase the first character. Used in reverse: `setName:` setter ↔
+ * Swift property `name`.
+ */
+function lowerFirst(s: string): string {
+  return s.length > 0 ? s.charAt(0).toLowerCase() + s.slice(1) : s;
+}
+
+/**
+ * Compute the auto-bridged ObjC selector for a Swift method declaration.
+ *
+ * @param baseName  The Swift method's base name (e.g. `play`).
+ * @param externalLabels  Parameter EXTERNAL labels in declaration order;
+ *                        `null` for a `_` (unlabeled) parameter.
+ *                        `[]` for a no-parameter method.
+ * @param explicitObjcName  If `@objc(customSel:)` was specified, the
+ *                          literal selector — short-circuits the rule
+ *                          and is returned as-is.
+ * @returns The ObjC selector (e.g. `playWithSong:by:`), or `null` if it
+ *          can't be determined.
+ *
+ * **Method rules:**
+ * - No params → base name (no colons)
+ * - Single param, `_` label → `baseName:`
+ * - Single param, explicit label `L` → `baseNameWithL:`
+ * - Multi-param, `_` first label → `baseName:label2:label3:`
+ * - Multi-param, explicit first label `L1` → `baseNameWithL1:label2:label3:`
+ *
+ * Initializer rules are handled by `objcSelectorForSwiftInit`.
+ */
+export function objcSelectorForSwiftMethod(
+  baseName: string,
+  externalLabels: (string | null)[],
+  explicitObjcName?: string | null
+): string | null {
+  if (!baseName) return null;
+  if (explicitObjcName) return explicitObjcName;
+
+  if (externalLabels.length === 0) {
+    return baseName;
+  }
+
+  const [first, ...rest] = externalLabels;
+  // Single param: "_" → "base:" ; "label" → "baseWithLabel:"
+  // Multi-param mirrors the same first-keyword formation, then appends each
+  // subsequent label as its own keyword. A `null` later label is invalid
+  // ObjC (no way to express unlabeled middle params) — keep as `:` to be safe.
+  const firstKeyword =
+    first === null || first === undefined || first === '_' || first === ''
+      ? `${baseName}:`
+      : `${baseName}With${capFirst(first)}:`;
+
+  const restKeywords = rest.map((l) => `${l ?? ''}:`).join('');
+  return firstKeyword + restKeywords;
+}
+
+/**
+ * Compute the bridged ObjC selector for a Swift `init(...)` declaration.
+ *
+ * **Init rules** (different from regular methods — Apple always uses
+ * `initWith` regardless of whether the first label is `_`):
+ * - `init()`                       → `init`
+ * - `init(_ name: String)`         → `initWithName:`  (uses the INTERNAL
+ *                                    name when external is `_`, per Apple's
+ *                                    bridging conventions)
+ * - `init(name: String)`           → `initWithName:`
+ * - `init(name: String, age: Int)` → `initWithName:age:`
+ *
+ * For the `_` case we need the internal (second identifier) name —
+ * passed via `internalNames`.
+ */
+export function objcSelectorForSwiftInit(
+  externalLabels: (string | null)[],
+  internalNames: string[],
+  explicitObjcName?: string | null
+): string | null {
+  if (explicitObjcName) return explicitObjcName;
+
+  if (externalLabels.length === 0) {
+    return 'init';
+  }
+
+  const [firstExt, ...restExt] = externalLabels;
+  const [firstInt] = internalNames;
+  // Use the internal name when external is "_"; ObjC needs *some* keyword,
+  // and Swift's auto-bridger uses the parameter's local name in this case.
+  const firstLabel =
+    firstExt === null || firstExt === '_' || firstExt === ''
+      ? firstInt
+      : firstExt;
+  if (!firstLabel) return null;
+
+  const firstKeyword = `initWith${capFirst(firstLabel)}:`;
+  const restKeywords = restExt
+    .map((label, idx) => {
+      const internal = internalNames[idx + 1];
+      const name = label && label !== '_' ? label : internal ?? '';
+      return `${name}:`;
+    })
+    .join('');
+  return firstKeyword + restKeywords;
+}
+
+/**
+ * Compute the bridged ObjC getter + setter for a Swift `@objc` property.
+ *
+ * - `var name: String`        → getter `name`, setter `setName:`
+ * - `var isReady: Bool`       → getter `isReady`, setter `setIsReady:`
+ *   (no special `is` handling — Swift's `isReady` stays as `isReady` in ObjC;
+ *   `@objc(name:)` overrides if a Cocoa-style getter `isReady` / setter
+ *   `setReady:` pairing is needed — that's the responsibility of the
+ *   declaration's `@objc(customGetter)` annotation, which we surface via
+ *   `explicitObjcName`.)
+ */
+export function objcAccessorsForSwiftProperty(
+  swiftName: string,
+  explicitObjcName?: string | null
+): { getter: string; setter: string } | null {
+  if (!swiftName) return null;
+  // The override syntax `@objc(customGetterName)` re-points the GETTER only;
+  // the setter still follows the `setX:` rule but is keyed off the override.
+  // (`@objc(getX:setY:)` is not currently supported — that's a rarer
+  // shape; can extend later if a real codebase needs it.)
+  const getter = explicitObjcName ?? swiftName;
+  return {
+    getter,
+    setter: `set${capFirst(getter)}:`,
+  };
+}
+
+/**
+ * Reverse: from an ObjC selector, return the candidate Swift base names
+ * the resolver should try when looking for the bridged Swift declaration.
+ *
+ * Examples:
+ *   `play`                 → ['play']
+ *   `play:`                → ['play']
+ *   `playWithSong:`        → ['play', 'playWithSong']
+ *   `play:by:`             → ['play']
+ *   `playWithSong:by:`     → ['play', 'playWithSong']
+ *   `initWithName:`        → ['init']                      (init is its own base name)
+ *   `initWithName:age:`    → ['init']
+ *   `setName:`             → ['name', 'setName']           (could be a setter OR a regular func)
+ *   `tableView:didSel…:`   → ['tableView']
+ *
+ * Returns multiple candidates because the bare base name is ambiguous —
+ * `playWithSong:` could correspond to either `func play(song:)` or
+ * `func playWithSong(_ x:)` (a Swift method literally named that with a
+ * `_` first label). The resolver tries each.
+ */
+export function swiftBaseNamesForObjcSelector(selector: string): string[] {
+  if (!selector) return [];
+
+  // Strip trailing colons and split into keywords.
+  const keywords = selector.replace(/:+$/g, '').split(':');
+  const firstKeyword = keywords[0];
+  if (!firstKeyword) return [];
+
+  const candidates: Set<string> = new Set();
+
+  // Always a candidate: the raw first keyword. Covers
+  //   `play:`           → `play`
+  //   `play:by:`        → `play`
+  //   `playWithSong:`   → `playWithSong` (a literal Swift name)
+  //   `tableView:...:`  → `tableView`
+  candidates.add(firstKeyword);
+
+  // `initWith<X>:` and `initWith<X>:<more>:` always reduce to `init`.
+  if (firstKeyword.startsWith('initWith')) {
+    candidates.add('init');
+  }
+
+  // Preposition-prefix patterns: `<base>(With|For|By|In|On|At|From|To|Of|As)<Cap>:`
+  // covers both Swift's @objc EXPORT rule (always "With") and Cocoa's
+  // IMPORTED selectors which use other prepositions natively (e.g.
+  // `objectForKey:`, `stringWithFormat:`, `compareTo:`,
+  // `imageNamed:inBundle:`). Strip to recover the Swift base name a caller
+  // would use (e.g. `object`, `string`, `compare`, `image`).
+  const prepositionMatch = firstKeyword.match(
+    /^([a-z][a-zA-Z0-9]*?)(?:With|For|By|In|On|At|From|To|Of|As)[A-Z]/
+  );
+  if (prepositionMatch && prepositionMatch[1]) {
+    candidates.add(prepositionMatch[1]);
+  }
+
+  // `setX:` could be a property setter — the Swift property is `x` (lowercase).
+  // Only fires for the obvious shape: `set` + capital letter + ':' (one param).
+  if (
+    keywords.length === 1 &&
+    /^set[A-Z]/.test(firstKeyword) &&
+    selector.endsWith(':')
+  ) {
+    const propName = lowerFirst(firstKeyword.slice(3));
+    if (propName) candidates.add(propName);
+  }
+
+  return Array.from(candidates);
+}
+
+/**
+ * Detect whether a Swift method `@objc` declaration uses the `@objc(custom:)`
+ * override form, returning the literal selector when present.
+ *
+ * Regex-based scan over the small chunk of source preceding the declaration —
+ * tree-sitter would be more precise but this is only consulted as a fallback
+ * when the structured AST isn't available (e.g. resolver-time lookups
+ * via `context.readFile`).
+ *
+ * Returns `null` when the declaration is plain `@objc` (no override) or has
+ * no `@objc` attribute at all.
+ */
+export function detectExplicitObjcName(sourceSlice: string): string | null {
+  // `@objc(customName:)` or `@objc(custom:name:)` — the parens contents are
+  // the literal ObjC selector. Whitespace permitted.
+  const m = sourceSlice.match(/@objc\s*\(\s*([^)\s]+)\s*\)/);
+  return m && m[1] ? m[1] : null;
+}
+
+/**
+ * Detect whether a Swift declaration is `@objc`-exposed by scanning the
+ * source slice that precedes it. Returns true for explicit `@objc`,
+ * `@objc(custom:)`, or membership in a `@objcMembers` class (caller's
+ * responsibility to pass class-level context if relevant).
+ *
+ * `@nonobjc` returns false even if `@objc` also appears (per Swift's rule
+ * that `@nonobjc` opts out of class-level `@objcMembers`).
+ */
+export function isObjcExposed(sourceSlice: string): boolean {
+  if (/@nonobjc\b/.test(sourceSlice)) return false;
+  return /@objc\b/.test(sourceSlice);
+}
diff --git a/src/resolution/types.ts b/src/resolution/types.ts
index 6fe11a031..71366a150 100644
--- a/src/resolution/types.ts
+++ b/src/resolution/types.ts
@@ -4,7 +4,7 @@
  * Types for the reference resolution system.
  */
 
-import { EdgeKind, Language, Node } from '../types';
+import { Language, Node, ReferenceKind } from '../types';
 
 /**
  * An unresolved reference from extraction
@@ -15,7 +15,7 @@ export interface UnresolvedRef {
   /** The name being referenced */
   referenceName: string;
   /** Type of reference */
-  referenceKind: EdgeKind;
+  referenceKind: ReferenceKind;
   /** Line where reference occurs */
   line: number;
   /** Column where reference occurs */
@@ -39,7 +39,7 @@ export interface ResolvedRef {
   /** Confidence score (0-1) */
   confidence: number;
   /** How it was resolved */
-  resolvedBy: 'exact-match' | 'import' | 'qualified-name' | 'framework' | 'fuzzy' | 'instance-method' | 'file-path';
+  resolvedBy: 'exact-match' | 'import' | 'qualified-name' | 'framework' | 'fuzzy' | 'instance-method' | 'file-path' | 'function-ref';
 }
 
 /**
@@ -81,6 +81,23 @@ export interface ResolutionContext {
   getAllFiles(): string[];
   /** Get nodes by lowercase name (O(1) lookup for fuzzy matching) */
   getNodesByLowerName(lowerName: string): Node[];
+  /**
+   * Direct supertypes of the type named `typeName` (same language): the classes
+   * it extends and the interfaces / protocols / traits it implements/conforms to,
+   * by simple name. Backed by the resolved `implements`/`extends` edges, so it is
+   * EMPTY during the first resolution pass (edges aren't built yet) and populated
+   * afterward — the conformance pass uses it to resolve a chained method defined
+   * on a supertype the receiver type conforms to (e.g. a protocol-extension
+   * method). Optional so external/test contexts compile without it.
+   */
+  getSupertypes?(typeName: string, language: Language): string[];
+  /**
+   * Look up a node by its id. Lets matchers derive the FROM-symbol's
+   * enclosing-class scope (Swift implicit-self method scoping, `this.X`
+   * member resolution). Optional so external/test contexts compile
+   * without it.
+   */
+  getNodeById?(id: string): Node | null;
   /** Get cached import mappings for a file */
   getImportMappings(filePath: string, language: Language): ImportMapping[];
   /**
@@ -91,6 +108,21 @@ export interface ResolutionContext {
    * compile without modification; production resolver implements it.
    */
   getProjectAliases?(): import('./path-aliases').AliasMap | null;
+  /**
+   * Go module info from `go.mod` at the project root. Returns `null`
+   * when the project has no `go.mod` (non-Go projects, pre-modules
+   * Go code, or projects whose modules live in subdirectories). Used
+   * by the Go branch of import resolution to distinguish in-module
+   * cross-package imports from third-party packages.
+   */
+  getGoModule?(): import('./go-module').GoModule | null;
+  /**
+   * Monorepo workspace member packages, keyed by declared package name.
+   * Returns `null` for single-package repos (no `workspaces` field).
+   * Lets the resolver treat `@scope/ui/sub` as a local import into the
+   * member's directory instead of an external npm package (#629).
+   */
+  getWorkspacePackages?(): import('./workspace-packages').WorkspacePackages | null;
   /**
    * Re-exports declared by a file (`export { x } from './other'`,
    * `export * from './other'`). Empty array when the file has none.
@@ -107,6 +139,13 @@ export interface ResolutionContext {
    * without modification.
    */
   listDirectories?(relativePath: string): string[];
+  /**
+   * C/C++ include search directories (relative to project root),
+   * extracted from compile_commands.json or discovered by heuristic.
+   * Used by resolveCppIncludePath to search -I directories when
+   * relative resolution fails. Optional so existing callers compile.
+   */
+  getCppIncludeDirs?(): string[];
 }
 
 /**
@@ -131,6 +170,14 @@ export interface FrameworkResolver {
   detect(context: ResolutionContext): boolean;
   /** Resolve a reference using framework-specific patterns */
   resolve(ref: UnresolvedRef, context: ResolutionContext): ResolvedRef | null;
+  /**
+   * Opt a reference NAME through the resolver's name-exists pre-filter, even when
+   * no node is named that. Needed for dynamic dispatch where the call target is
+   * an attribute/descriptor, not a declared symbol (e.g. Django's
+   * `self._iterable_class(...)`, React effect callbacks). Returning true lets the
+   * ref reach `resolve()` instead of being dropped for having no name match.
+   */
+  claimsReference?(name: string): boolean;
   /**
    * Extract framework-specific nodes and references from a file.
    *
@@ -140,6 +187,20 @@ export interface FrameworkResolver {
    * pipeline; the framework's own `resolve()` is one of the strategies tried.
    */
   extract?(filePath: string, content: string): FrameworkExtractionResult;
+  /**
+   * Cross-file finalization pass, called once after all per-file extraction
+   * completes (and again on every incremental sync). Used by frameworks where
+   * a symbol's final representation depends on a sibling file the per-file
+   * `extract()` never saw — e.g. NestJS's `RouterModule.register([...])`
+   * sets route prefixes for controllers declared elsewhere.
+   *
+   * Implementations return route/etc. nodes with mutated fields (typically
+   * `name`); the orchestrator persists each via `updateNode`. The node `id`
+   * MUST be preserved so existing edges (route → handler, etc.) stay intact;
+   * `qualifiedName` SHOULD be preserved so the pass stays idempotent — a
+   * second run can recover the original in-file form from `qualifiedName`.
+   */
+  postExtract?(context: ResolutionContext): Node[];
 }
 
 /**
diff --git a/src/resolution/workspace-packages.ts b/src/resolution/workspace-packages.ts
new file mode 100644
index 000000000..b8f0657a3
--- /dev/null
+++ b/src/resolution/workspace-packages.ts
@@ -0,0 +1,180 @@
+/**
+ * JS/TS workspace (monorepo) package resolution.
+ *
+ * npm / yarn / bun read member packages from the root `package.json`
+ * `workspaces` field; pnpm from `pnpm-workspace.yaml`. A cross-package
+ * import like `@scope/ui/widgets` is LOCAL to the monorepo, but to a
+ * single-package resolver it looks exactly like a third-party npm
+ * specifier — so `isExternalImport` flags it external and the
+ * consumer↔definition edge is never created. For component barrels
+ * (`export { default as X } from './x.svelte'`) that surfaces as a false
+ * `0 callers` on a live component (issue #629).
+ *
+ * This module maps each member package's declared `name` to its
+ * directory so the resolver can rewrite `@scope/ui/widgets` →
+ * `packages/ui/widgets` and then run normal extension/index resolution.
+ *
+ * Scope deliberately small for v1 (mirrors path-aliases.ts):
+ *   - reads `workspaces` (array OR `{ packages: [...] }`) from package.json,
+ *     plus a minimal `pnpm-workspace.yaml` `packages:` list
+ *   - expands one level of `*` / `**` globs (`packages/*`, `apps/*`)
+ *   - subpath resolution is directory-based (`@scope/ui/sub` → `<ui>/sub`);
+ *     it does NOT yet honour a member's `exports` map or `main` field
+ *   - returns null when the project declares no workspaces, so single-
+ *     package repos pay nothing and see no behaviour change.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { logDebug } from '../errors';
+
+export interface WorkspacePackages {
+  /** Member package `name` → directory relative to projectRoot (posix). */
+  byName: Map<string, string>;
+}
+
+/**
+ * Load workspace member packages for `projectRoot`. Returns `null` when
+ * the project declares no workspaces (the common single-package case) —
+ * callers then skip all workspace logic.
+ *
+ * Cheap to call repeatedly only via the resolver's per-instance cache;
+ * this function itself touches the filesystem, so the resolver memoises it
+ * the same way it does {@link loadProjectAliases} / {@link loadGoModule}.
+ */
+export function loadWorkspacePackages(projectRoot: string): WorkspacePackages | null {
+  const patterns = readWorkspaceGlobs(projectRoot);
+  if (patterns.length === 0) return null;
+
+  const byName = new Map<string, string>();
+  for (const pattern of patterns) {
+    for (const dir of expandWorkspaceGlob(projectRoot, pattern)) {
+      const pkgName = readPackageName(path.join(projectRoot, dir));
+      // First declaration wins — workspace patterns are tried in order.
+      if (pkgName && !byName.has(pkgName)) byName.set(pkgName, dir);
+    }
+  }
+  if (byName.size === 0) return null;
+
+  logDebug('workspace packages loaded', { count: byName.size });
+  return { byName };
+}
+
+/**
+ * Rewrite a bare workspace import to a path relative to projectRoot,
+ * WITHOUT an extension — the caller applies the language's extension/index
+ * resolution. `@scope/ui/widgets` → `packages/ui/widgets`; the bare package
+ * name `@scope/ui` → its directory. Returns `null` when no member package
+ * name matches.
+ */
+export function resolveWorkspaceImport(
+  importPath: string,
+  ws: WorkspacePackages
+): string | null {
+  // Longest matching package name wins, so `@scope/ui/core` prefers a
+  // `@scope/ui/core` package over a `@scope/ui` one when both exist.
+  let bestName: string | null = null;
+  for (const name of ws.byName.keys()) {
+    if (importPath === name || importPath.startsWith(name + '/')) {
+      if (!bestName || name.length > bestName.length) bestName = name;
+    }
+  }
+  if (!bestName) return null;
+  const dir = ws.byName.get(bestName)!;
+  const subpath = importPath.slice(bestName.length); // '' or '/widgets'
+  return (dir + subpath).replace(/\/{2,}/g, '/');
+}
+
+/** Read workspace glob patterns from package.json + pnpm-workspace.yaml. */
+function readWorkspaceGlobs(projectRoot: string): string[] {
+  const out: string[] = [];
+
+  // package.json `workspaces` (npm / yarn / bun): array, or Yarn's
+  // `{ packages: [...], nohoist: [...] }` object form.
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf-8')
+    );
+    const ws = pkg?.workspaces;
+    if (Array.isArray(ws)) {
+      out.push(...ws.filter((w: unknown): w is string => typeof w === 'string'));
+    } else if (ws && Array.isArray(ws.packages)) {
+      out.push(...ws.packages.filter((w: unknown): w is string => typeof w === 'string'));
+    }
+  } catch {
+    /* no / invalid package.json — not a workspace root */
+  }
+
+  // pnpm-workspace.yaml `packages:` list. Parsed with a minimal line
+  // scanner so we don't pull in a YAML dependency.
+  try {
+    const yaml = fs.readFileSync(path.join(projectRoot, 'pnpm-workspace.yaml'), 'utf-8');
+    out.push(...parsePnpmPackages(yaml));
+  } catch {
+    /* no pnpm-workspace.yaml */
+  }
+
+  return out;
+}
+
+/**
+ * Minimal pnpm-workspace.yaml `packages:` extractor. Handles the only shape
+ * pnpm actually uses:
+ *   packages:
+ *     - 'packages/*'
+ *     - "apps/*"
+ *     - tools/build
+ */
+function parsePnpmPackages(yaml: string): string[] {
+  const out: string[] = [];
+  const lines = yaml.split(/\r?\n/);
+  let inPackages = false;
+  for (const line of lines) {
+    if (/^\s*packages\s*:/.test(line)) {
+      inPackages = true;
+      continue;
+    }
+    if (inPackages) {
+      const item = line.match(/^\s*-\s*(.+?)\s*$/);
+      if (item) {
+        out.push(item[1]!.replace(/^['"]|['"]$/g, ''));
+        continue;
+      }
+      // A non-list, non-blank line ends the `packages:` block.
+      if (line.trim() !== '' && !/^\s/.test(line)) inPackages = false;
+    }
+  }
+  return out;
+}
+
+/** Expand one level of a `packages/*` / `apps/**` glob to member dirs. */
+function expandWorkspaceGlob(projectRoot: string, pattern: string): string[] {
+  const norm = pattern.replace(/\\/g, '/').replace(/\/+$/, '');
+  const star = norm.indexOf('*');
+  if (star === -1) return [norm]; // exact directory
+
+  // Everything before the wildcard segment is the base to enumerate.
+  const base = norm.slice(0, star).replace(/\/+$/, '');
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(path.join(projectRoot, base), { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out: string[] = [];
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith('.') || e.name === 'node_modules') continue;
+    out.push(base ? `${base}/${e.name}` : e.name);
+  }
+  return out;
+}
+
+/** Read the `name` field from a member directory's package.json. */
+function readPackageName(dirAbs: string): string | null {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(dirAbs, 'package.json'), 'utf-8'));
+    return typeof pkg?.name === 'string' && pkg.name ? pkg.name : null;
+  } catch {
+    return null;
+  }
+}
diff --git a/src/search/query-utils.ts b/src/search/query-utils.ts
index da0645f81..1a7b121fc 100644
--- a/src/search/query-utils.ts
+++ b/src/search/query-utils.ts
@@ -4,9 +4,55 @@
  * Shared module for search term extraction and scoring.
  */
 
+import * as fs from 'fs';
 import * as path from 'path';
 import { Node } from '../types';
 
+/** Normalize a name to a comparable token: lowercase, alphanumerics only. */
+export function normalizeNameToken(raw: string): string {
+  return raw.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+/**
+ * Tokens that name the PROJECT as a whole — its `go.mod` module, `package.json`
+ * name, or repo root directory — rather than any specific symbol. A user
+ * naturally puts the project name in a query as context ("MyApp backend
+ * routes"), but it carries no discriminative signal: when it's also a substring
+ * of a symbol or path on one stack (a `MyAppFrontend/` dir, a `MyAppApp` class)
+ * it lexically inflates that stack and buries the rest (#720).
+ *
+ * Returned normalized (lowercase, alphanumerics only) so a query word can be
+ * compared by its normalized form. Only names ≥5 chars are kept — short ones
+ * (`api`, `app`, `core`, `web`) collide with real query terms too often to
+ * safely down-weight.
+ */
+export function deriveProjectNameTokens(projectRoot: string): Set<string> {
+  const tokens = new Set<string>();
+  const add = (raw: string | undefined | null): void => {
+    if (!raw) return;
+    const norm = normalizeNameToken(raw);
+    if (norm.length >= 5) tokens.add(norm);
+  };
+
+  // go.mod module last segment (the most reliable signal for Go repos).
+  try {
+    const gomod = fs.readFileSync(path.join(projectRoot, 'go.mod'), 'utf-8');
+    const m = gomod.match(/^\s*module\s+(\S+)/m);
+    if (m && m[1]) add(m[1].split('/').pop());
+  } catch { /* no go.mod */ }
+
+  // package.json name (strip an `@scope/` prefix).
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf-8'));
+    if (typeof pkg.name === 'string') add(pkg.name.replace(/^@[^/]+\//, ''));
+  } catch { /* no / invalid package.json */ }
+
+  // Repo root directory name — a fallback when neither manifest names the project.
+  add(path.basename(path.resolve(projectRoot)));
+
+  return tokens;
+}
+
 /**
  * Common stop words to filter from search queries.
  * Includes generic English + code-specific noise words.
@@ -172,24 +218,50 @@ export function extractSearchTerms(query: string, options?: { stems?: boolean })
  * Score path relevance to a query
  * Higher score = more relevant path
  */
-export function scorePathRelevance(filePath: string, query: string): number {
-  // Use base terms only — stem variants inflate path scores by generating
-  // many near-duplicate terms that all match the same path segments.
-  const terms = extractSearchTerms(query, { stems: false });
-  if (terms.length === 0) return 0;
-
+export function scorePathRelevance(
+  filePath: string,
+  query: string,
+  projectNameTokens?: Set<string>,
+): number {
   const pathLower = filePath.toLowerCase();
   const fileName = path.basename(filePath).toLowerCase();
   const dirName = path.dirname(filePath).toLowerCase();
   let score = 0;
 
-  for (const term of terms) {
+  // Score per original query WORD, not per sub-token. A single PascalCase word
+  // splits into many sub-tokens (a project name "SuperBizAgent" →
+  // superbizagent / super / biz / agent) that all match the SAME path segment,
+  // so summing per sub-token boosted that path 4× for one concept — enough to
+  // bury the rest of the query's stack (#720). A word matches a path level if
+  // ANY of its sub-tokens do, and counts ONCE; distinct words still each add.
+  // Split the ORIGINAL-case query into words; extractSearchTerms does the
+  // camelCase/snake split per word (so `getUserName` still matches a
+  // `get_user_name` path) — we just attribute each word's matches once.
+  const allWords = query.split(/\s+/).filter((w) => w.length > 0);
+  if (allWords.length === 0) return 0;
+
+  // A query word that just names the PROJECT (its go.mod / package.json / repo
+  // name) carries no discriminative path signal — drop it so the rest of the
+  // query decides the ranking, instead of every file under a `<ProjectName>…/`
+  // tree winning on the project name alone (#720). Only when OTHER words remain,
+  // so a bare project-name query still scores on its path.
+  const words =
+    projectNameTokens && projectNameTokens.size > 0
+      ? allWords.filter((w) => !projectNameTokens.has(normalizeNameToken(w)))
+      : allWords;
+  const scored = words.length > 0 ? words : allWords;
+
+  for (const word of scored) {
+    // Use base terms only — stem variants inflate path scores by generating
+    // many near-duplicate terms that all match the same path segments.
+    const subtokens = extractSearchTerms(word, { stems: false });
+    if (subtokens.length === 0) continue;
     // Exact filename match (strongest)
-    if (fileName.includes(term)) score += 10;
+    if (subtokens.some((t) => fileName.includes(t))) score += 10;
     // Directory match
-    if (dirName.includes(term)) score += 5;
+    if (subtokens.some((t) => dirName.includes(t))) score += 5;
     // General path match
-    else if (pathLower.includes(term)) score += 3;
+    else if (subtokens.some((t) => pathLower.includes(t))) score += 3;
   }
 
   // Deprioritize test files unless the query is explicitly about tests
@@ -340,3 +412,30 @@ export function kindBonus(kind: Node['kind']): number {
   };
   return bonuses[kind] ?? 0;
 }
+
+/**
+ * Whether a query token looks like a code identifier the user deliberately typed
+ * (camelCase / PascalCase-with-internal-caps / snake_case / has a digit) rather
+ * than a plain dictionary word ("flat", "object", "screen").
+ *
+ * Used to decide whether an EXACT name match earns the "the user named this
+ * symbol" exemption from single-term dampening. A common English word that
+ * happens to exact-match an unrelated symbol — the query "flat object" matching
+ * a constant named `FLAT` — must NOT get that exemption, or the +exact-name
+ * bonus floats it to the top of a prose query on its own.
+ *
+ * Classifies the token AS THE USER TYPED IT, not the matched symbol's name:
+ * "flat" (lowercase, descriptive) is non-distinctive even though it matches
+ * `FLAT`. A leading-capital-only word ("Screen", "Zustand") is also treated as
+ * a plain word — sentence-start capitalization and proper nouns aren't reliable
+ * identifier signals.
+ */
+export function isDistinctiveIdentifier(token: string): boolean {
+  if (!token) return false;
+  // snake_case / SCREAMING_SNAKE, or an embedded digit → a deliberate identifier.
+  if (/[_0-9]/.test(token)) return true;
+  // An uppercase letter anywhere AFTER the first char → a camelCase/PascalCase
+  // boundary (setLastEmail, OrgUserStore) or an acronym (REST, HTTP).
+  if (/[A-Z]/.test(token.slice(1))) return true;
+  return false;
+}
diff --git a/src/sync/git-hooks.ts b/src/sync/git-hooks.ts
index 3344c5ff9..a657d7545 100644
--- a/src/sync/git-hooks.ts
+++ b/src/sync/git-hooks.ts
@@ -44,6 +44,7 @@ export function isGitRepo(projectRoot: string): boolean {
       cwd: projectRoot,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
     }).trim();
     return out === 'true';
   } catch {
@@ -61,6 +62,7 @@ function gitHooksDir(projectRoot: string): string | null {
       cwd: projectRoot,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
     }).trim();
     if (!out) return null;
     return path.isAbsolute(out) ? out : path.resolve(projectRoot, out);
diff --git a/src/sync/index.ts b/src/sync/index.ts
index 1857c5a42..3e2cb4afd 100644
--- a/src/sync/index.ts
+++ b/src/sync/index.ts
@@ -8,11 +8,12 @@
  * - FileWatcher: Debounced fs.watch that auto-triggers sync on file changes
  * - Watch policy: decides when the watcher must be disabled (e.g. WSL2 /mnt)
  * - Git sync hooks: opt-in commit/merge/checkout hooks when watching is off
+ * - Git worktree awareness: detect when a query borrows another tree's index
  * - Content hashing for change detection (in extraction module)
  * - Incremental reindexing (in extraction module)
  */
 
-export { FileWatcher, WatchOptions } from './watcher';
+export { FileWatcher, WatchOptions, PendingFile, LockUnavailableError } from './watcher';
 export { watchDisabledReason, detectWsl } from './watch-policy';
 export {
   installGitSyncHook,
@@ -23,3 +24,10 @@ export {
   type GitHookName,
   type GitHookResult,
 } from './git-hooks';
+export {
+  gitWorktreeRoot,
+  detectWorktreeIndexMismatch,
+  worktreeMismatchWarning,
+  worktreeMismatchNotice,
+  type WorktreeIndexMismatch,
+} from './worktree';
diff --git a/src/sync/watcher.ts b/src/sync/watcher.ts
index 2c16d82a3..9bc654708 100644
--- a/src/sync/watcher.ts
+++ b/src/sync/watcher.ts
@@ -1,20 +1,83 @@
 /**
  * File Watcher
  *
- * Watches the project directory for file changes and triggers
- * debounced sync operations to keep the code graph up-to-date.
+ * Watches the project directory for file changes and triggers debounced sync
+ * operations to keep the code graph up-to-date.
  *
- * Uses Node.js native fs.watch with recursive mode (macOS FSEvents,
- * Windows ReadDirectoryChangesW, Linux inotify on Node 19+).
+ * Uses Node's built-in `fs.watch` directly (no third-party watcher, no native
+ * addon) with a per-platform strategy chosen to keep the open-descriptor /
+ * kernel-watch cost BOUNDED rather than growing with the number of files:
+ *
+ *   - macOS / Windows: a SINGLE recursive `fs.watch(root, {recursive:true})`.
+ *     libuv maps this to one FSEvents stream (macOS) / one
+ *     ReadDirectoryChangesW handle (Windows), so it costs O(1) descriptors no
+ *     matter how large the tree. This is the fix for the macOS file-table
+ *     exhaustion (#644 / #496 / #555 / #628): the previous watcher held one
+ *     open fd PER WATCHED FILE on macOS (tens of thousands of REG fds), which
+ *     exhausted `kern.maxfiles` and crashed unrelated processes system-wide.
+ *
+ *   - Linux: recursive `fs.watch` is unsupported, so we watch each (non-ignored)
+ *     DIRECTORY with one inotify watch — O(directories), NOT O(files). New
+ *     directories are picked up dynamically and an overall watch cap bounds
+ *     inotify usage on pathological monorepos (#579). A single inotify watch on
+ *     a directory already reports create/modify/delete for its children, so
+ *     per-file watches are never needed.
+ *
+ * Excluded trees (node_modules/, dist/, .git/, …) are filtered via the
+ * indexer's `buildDefaultIgnore` (built-in default-ignore dirs + the project's
+ * .gitignore) — on Linux they're never descended into (so they cost no watch),
+ * and on macOS/Windows the single recursive stream still covers them but their
+ * events are dropped before any sync is scheduled. Either way the watcher's
+ * scope matches the indexer's (#276 / #407).
  */
 
 import * as fs from 'fs';
-import { CodeGraphConfig } from '../types';
-import { shouldIncludeFile } from '../extraction';
+import * as path from 'path';
+import type { Ignore } from 'ignore';
+import { isSourceFile, buildDefaultIgnore } from '../extraction';
 import { logDebug, logWarn } from '../errors';
 import { normalizePath } from '../utils';
+import { isCodeGraphDataDir } from '../directory';
 import { watchDisabledReason } from './watch-policy';
 
+/**
+ * Native recursive `fs.watch` is only reliable on macOS and Windows; on Linux
+ * (and AIX) it throws `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM`. We branch on this
+ * to pick the recursive vs per-directory strategy.
+ */
+function supportsRecursiveWatch(): boolean {
+  return process.platform === 'darwin' || process.platform === 'win32';
+}
+
+/**
+ * Upper bound on simultaneously-watched directories on the Linux per-directory
+ * path. Each is one inotify watch; the kernel's `fs.inotify.max_user_watches`
+ * is the hard limit (commonly 8k–128k). We stop adding watches past this and
+ * log once — partial live-watch (with `codegraph sync` as the backstop) is far
+ * better than exhausting the user's inotify budget and breaking watching
+ * system-wide (#579). Tunable via CODEGRAPH_MAX_DIR_WATCHES.
+ */
+const DEFAULT_MAX_DIR_WATCHES = 50_000;
+
+function maxDirWatches(): number {
+  const raw = process.env.CODEGRAPH_MAX_DIR_WATCHES;
+  if (raw && /^\d+$/.test(raw)) {
+    const n = Number(raw);
+    if (n > 0) return n;
+  }
+  return DEFAULT_MAX_DIR_WATCHES;
+}
+
+/**
+ * Test seam (see {@link __emitWatchEventForTests}). Maps a watcher's project
+ * root to its live instance so tests can synthesize a change event
+ * deterministically — real fs.watch delivery latency races under parallel
+ * vitest (the reason the previous chokidar mock existed). Only populated under
+ * a test runner, so production carries no bookkeeping or retained references.
+ */
+const liveWatchersForTests = new Map<string, FileWatcher>();
+const IS_TEST_RUNTIME = !!(process.env.VITEST || process.env.NODE_ENV === 'test');
+
 /**
  * Options for the file watcher
  */
@@ -35,6 +98,50 @@ export interface WatchOptions {
    * Callback when a sync errors (for logging/diagnostics).
    */
   onSyncError?: (error: Error) => void;
+
+  /**
+   * Test-only. When true, `start()` installs NO OS-level fs.watch — the
+   * watcher is "inert" and only the {@link __emitWatchEventForTests} /
+   * {@link FileWatcher.ingestEventForTests} seam drives its pipeline. This
+   * restores the deterministic, OS-free behavior the unit tests need (real
+   * FSEvents/inotify delivery races under parallel vitest). Production never
+   * sets it.
+   */
+  inertForTests?: boolean;
+}
+
+/**
+ * Thrown by a `syncFn` to signal that the underlying sync couldn't acquire
+ * the cross-process write lock (#449). The watcher treats this as "no
+ * progress" — preserves `pendingFiles`, skips `onSyncComplete`, and the
+ * `finally` block reschedules. Quiet (debug-only) because a long-running
+ * external indexer can hit this every debounce cycle.
+ */
+export class LockUnavailableError extends Error {
+  constructor(message = 'CodeGraph file lock unavailable; another process is writing') {
+    super(message);
+    this.name = 'LockUnavailableError';
+  }
+}
+
+/**
+ * Per-file pending entry — tracks a source file the watcher saw an event for
+ * but hasn't yet synced into the index. Exposed via {@link FileWatcher.getPendingFiles}
+ * so MCP tool responses can mark stale results without forcing a wait.
+ */
+export interface PendingFile {
+  /** Project-relative POSIX path (e.g. "src/foo.ts"). */
+  path: string;
+  /** Wall-clock ms at the first event we saw for this path since the last sync. */
+  firstSeenMs: number;
+  /** Wall-clock ms at the most recent event we saw for this path. */
+  lastSeenMs: number;
+  /**
+   * True when a sync is currently in flight that began AFTER this file's most
+   * recent event — i.e. the next successful sync will pick it up. False when
+   * the file is still in the debounce window (no sync running yet).
+   */
+  indexing: boolean;
 }
 
 /**
@@ -42,37 +149,80 @@ export interface WatchOptions {
  * debounced sync operations via a provided callback.
  *
  * Design goals:
- * - Minimal resource usage (native OS file events, no polling)
+ * - Bounded resource usage: O(1) descriptors on macOS/Windows (one recursive
+ *   watch), O(directories) inotify watches on Linux — never O(files), which
+ *   was the system-crashing fd leak on macOS (#644/#496/#555/#628).
  * - Debounced to avoid thrashing on rapid saves
- * - Filters against CodeGraph include/exclude patterns
- * - Ignores .codegraph/ directory changes
+ * - Filters to supported source files by extension
+ * - Ignores .codegraph/ and .git/ regardless of .gitignore
+ * - Tracks per-file pending state so MCP tools can flag stale results
+ *   without blocking on a sync (issue #403)
  */
 export class FileWatcher {
-  private watcher: fs.FSWatcher | null = null;
+  /** macOS/Windows: the single recursive watcher. Null on Linux. */
+  private recursiveWatcher: fs.FSWatcher | null = null;
+  /** Linux: one watcher per watched directory (keyed by absolute path). */
+  private dirWatchers = new Map<string, fs.FSWatcher>();
+  /** Set once the per-directory watch cap is hit, so we log only once. */
+  private dirCapWarned = false;
+  /** Test-only inert mode: started, but with no OS watcher installed. */
+  private inert = false;
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
-  private hasChanges = false;
+  /**
+   * Files seen by the watcher since the last successful sync — populated on
+   * every change event, cleared at the start of a sync, and re-populated by
+   * events that arrive mid-sync (or restored on sync failure). Keyed by the
+   * same project-relative POSIX path the rest of the codebase uses, so a
+   * caller can intersect tool-response file paths against this map cheaply.
+   */
+  private pendingFiles = new Map<string, { firstSeenMs: number; lastSeenMs: number }>();
+  /**
+   * Wall-clock ms at which the in-flight sync began. Combined with
+   * {@link pendingFiles}'s `lastSeenMs`, this distinguishes "still in the
+   * debounce window" (lastSeen > syncStarted, sync hasn't started yet for
+   * this edit) from "currently being indexed" (lastSeen <= syncStarted).
+   */
+  private syncStartedMs = 0;
   private syncing = false;
   private stopped = false;
+  /**
+   * True once the initial watch set is established. Unlike the previous
+   * chokidar implementation there is no asynchronous initial "crawl" emitting
+   * an `add` per existing file — `fs.watch` only reports changes from the
+   * moment it's installed — so this flips to true synchronously at the end of
+   * `start()`. The startup reconcile against on-disk state is handled
+   * separately by the engine's catch-up sync, not by the watcher.
+   */
+  private ready = false;
+  /**
+   * Callbacks that resolve when the watch set is established. Used by tests
+   * (and any production caller that cares about a clean baseline) to
+   * deterministically gate on watcher readiness.
+   */
+  private readyWaiters: Array<() => void> = [];
+  // The shared ignore matcher (built-in defaults + project .gitignore), built
+  // once at start(). Same source of truth the indexer uses, so watcher scope
+  // can never diverge from index scope.
+  private ignoreMatcher: Ignore | null = null;
 
   private readonly projectRoot: string;
-  private readonly config: CodeGraphConfig;
   private readonly debounceMs: number;
   private readonly syncFn: () => Promise<{ filesChanged: number; durationMs: number }>;
   private readonly onSyncComplete?: WatchOptions['onSyncComplete'];
   private readonly onSyncError?: WatchOptions['onSyncError'];
+  private readonly inertForTests: boolean;
 
   constructor(
     projectRoot: string,
-    config: CodeGraphConfig,
     syncFn: () => Promise<{ filesChanged: number; durationMs: number }>,
     options: WatchOptions = {}
   ) {
     this.projectRoot = projectRoot;
-    this.config = config;
     this.syncFn = syncFn;
     this.debounceMs = options.debounceMs ?? 2000;
     this.onSyncComplete = options.onSyncComplete;
     this.onSyncError = options.onSyncError;
+    this.inertForTests = options.inertForTests ?? false;
   }
 
   /**
@@ -80,64 +230,225 @@ export class FileWatcher {
    * Returns true if watching started successfully, false otherwise.
    */
   start(): boolean {
-    if (this.watcher) return true; // Already watching
+    if (this.recursiveWatcher || this.dirWatchers.size > 0 || this.inert) return true; // Already watching
     this.stopped = false;
 
-    // Some environments make recursive fs.watch unusable — most notably WSL2
-    // /mnt/ drives, where setup blocks long enough to break MCP startup
-    // handshakes (issue #199). Skip watching there; callers fall back to
-    // manual `codegraph sync` or the git sync hooks.
+    // Some environments make filesystem watching unusable — most notably
+    // WSL2 /mnt/ drives, where the underlying fs.watch calls block long
+    // enough to break MCP startup handshakes (issue #199). Skip watching
+    // there; callers fall back to manual `codegraph sync` or git sync hooks.
     const disabledReason = watchDisabledReason(this.projectRoot);
     if (disabledReason) {
       logDebug('File watcher disabled', { reason: disabledReason, projectRoot: this.projectRoot });
       return false;
     }
 
+    // Reuse the indexer's ignore set so the watcher and indexer agree on scope.
+    this.ignoreMatcher = buildDefaultIgnore(this.projectRoot);
+
     try {
-      this.watcher = fs.watch(
-        this.projectRoot,
-        { recursive: true },
-        (_eventType, filename) => {
-          if (!filename || this.stopped) return;
-
-          // Normalize path separators
-          const normalized = normalizePath(filename);
-
-          // Ignore .codegraph/ directory changes (our own DB writes)
-          if (
-            normalized === '.codegraph' ||
-            normalized.startsWith('.codegraph/') ||
-            normalized.startsWith('.codegraph\\')
-          ) {
-            return;
-          }
-
-          // Filter against include/exclude patterns
-          if (!shouldIncludeFile(normalized, this.config)) {
-            return;
-          }
-
-          logDebug('File change detected', { file: normalized });
-          this.hasChanges = true;
-          this.scheduleSync();
-        }
-      );
+      if (this.inertForTests) {
+        // Test-only: install no OS watcher; the seam drives events instead.
+        this.inert = true;
+      } else if (supportsRecursiveWatch()) {
+        this.startRecursive();
+      } else {
+        this.startPerDirectory();
+      }
 
-      // Handle watcher errors gracefully
-      this.watcher.on('error', (err) => {
-        logWarn('File watcher error', { error: String(err) });
-        // Don't crash — watcher may recover or user can restart
-      });
+      // No async crawl to wait on: as soon as the watch set is installed we
+      // have a clean baseline (pendingFiles is only populated by post-start
+      // events). Clear defensively and flip ready.
+      this.pendingFiles.clear();
+      this.ready = true;
+      for (const cb of this.readyWaiters) cb();
+      this.readyWaiters.length = 0;
+      if (IS_TEST_RUNTIME) liveWatchersForTests.set(this.projectRoot, this);
 
-      logDebug('File watcher started', { projectRoot: this.projectRoot, debounceMs: this.debounceMs });
+      logDebug('File watcher started', {
+        projectRoot: this.projectRoot,
+        debounceMs: this.debounceMs,
+        mode: this.inertForTests ? 'inert' : supportsRecursiveWatch() ? 'recursive' : 'per-directory',
+        watchedDirs: this.dirWatchers.size || undefined,
+      });
       return true;
     } catch (err) {
-      // Recursive watch not supported (e.g., Linux < Node 19)
-      logWarn('Could not start file watcher — recursive fs.watch not supported on this platform', { error: String(err) });
+      // Watcher setup failed (e.g., permission denied, missing directory).
+      logWarn('Could not start file watcher', { error: String(err) });
+      this.stop();
       return false;
     }
   }
 
+  /**
+   * macOS/Windows: one recursive watcher for the whole tree. O(1) descriptors.
+   * `filename` arrives relative to the project root (with subdirectories), so
+   * it maps straight to a project-relative path.
+   */
+  private startRecursive(): void {
+    this.recursiveWatcher = fs.watch(
+      this.projectRoot,
+      { recursive: true, persistent: true },
+      (_event, filename) => {
+        if (this.stopped || filename == null) return;
+        this.handleChange(normalizePath(String(filename)));
+      }
+    );
+    this.recursiveWatcher.on('error', (err: unknown) => {
+      logWarn('File watcher error', { error: String(err) });
+    });
+  }
+
+  /**
+   * Linux: walk the (non-ignored) tree and watch each directory. One inotify
+   * watch per directory reports create/modify/delete for that directory's
+   * direct children, so we never watch individual files.
+   */
+  private startPerDirectory(): void {
+    this.watchTree(this.projectRoot, /* markExisting */ false);
+  }
+
+  /**
+   * Add an inotify watch for `dir` and recurse into its non-ignored
+   * subdirectories. When `markExisting` is true (a directory that appeared
+   * AFTER startup), the source files already inside it are recorded as pending
+   * — this closes the `mkdir + write` race where files created before the new
+   * directory's watch is installed would otherwise be missed until the next
+   * full sync. The initial startup walk passes false (the engine's catch-up
+   * sync owns the baseline).
+   */
+  private watchTree(dir: string, markExisting: boolean): void {
+    if (this.dirWatchers.has(dir)) return;
+    if (this.dirWatchers.size >= maxDirWatches()) {
+      if (!this.dirCapWarned) {
+        this.dirCapWarned = true;
+        logWarn('File watcher hit directory-watch cap; remaining subtrees rely on manual/periodic sync', {
+          cap: maxDirWatches(),
+        });
+      }
+      return;
+    }
+
+    let w: fs.FSWatcher;
+    try {
+      w = fs.watch(dir, { persistent: true }, (_event, filename) =>
+        this.handleDirEvent(dir, filename)
+      );
+    } catch {
+      // ENOENT / EACCES / too-many-open-files — skip this directory quietly.
+      return;
+    }
+    w.on('error', () => this.unwatchDir(dir));
+    this.dirWatchers.set(dir, w);
+
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const child = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (this.shouldIgnoreDir(child)) continue;
+        this.watchTree(child, markExisting);
+      } else if (markExisting && entry.isFile()) {
+        this.handleChange(normalizePath(path.relative(this.projectRoot, child)));
+      }
+    }
+  }
+
+  /**
+   * Linux per-directory event handler. `filename` is relative to `dir`. A new
+   * sub-directory is picked up by extending the watch tree; everything else is
+   * routed through the shared change handler.
+   */
+  private handleDirEvent(dir: string, filename: string | Buffer | null): void {
+    if (this.stopped || filename == null) return;
+    const full = path.join(dir, String(filename));
+
+    // A newly-created directory needs its own watch (recursive isn't available
+    // on Linux). statSync is cheap and these events are rare relative to file
+    // edits. If the path vanished (rapid create/delete) the stat throws and we
+    // fall through to the change handler, which no-ops on a non-source path.
+    try {
+      if (fs.statSync(full).isDirectory()) {
+        if (!this.shouldIgnoreDir(full)) this.watchTree(full, /* markExisting */ true);
+        return;
+      }
+    } catch {
+      // deleted/inaccessible — treat as a normal change below
+    }
+
+    this.handleChange(normalizePath(path.relative(this.projectRoot, full)));
+  }
+
+  /**
+   * Shared change handler for both watch strategies. `rel` is a
+   * project-relative POSIX path. Applies the ignore + source-file filters and,
+   * for a real source change, records it as pending (#403) and schedules a
+   * debounced sync.
+   *
+   * The recursive (macOS/Windows) watcher reports events for ignored trees too
+   * (one stream covers the whole repo), so the ignore check here is load-bearing
+   * — it drops node_modules/dist/.git churn before any sync is scheduled.
+   */
+  private handleChange(rel: string): void {
+    if (!rel || rel === '.' || rel.startsWith('..')) return;
+    if (this.isAlwaysIgnored(rel)) return;
+    if (this.ignoreMatcher && this.ignoreMatcher.ignores(rel)) return;
+    if (!isSourceFile(rel)) return;
+
+    logDebug('File change detected', { file: rel });
+    if (this.ready) {
+      const now = Date.now();
+      const existing = this.pendingFiles.get(rel);
+      this.pendingFiles.set(rel, {
+        firstSeenMs: existing?.firstSeenMs ?? now,
+        lastSeenMs: now,
+      });
+    }
+    this.scheduleSync();
+  }
+
+  /** Close and forget the watch for a directory that errored/was removed. */
+  private unwatchDir(dir: string): void {
+    const w = this.dirWatchers.get(dir);
+    if (w) {
+      try {
+        w.close();
+      } catch {
+        /* already closed */
+      }
+      this.dirWatchers.delete(dir);
+    }
+  }
+
+  /** Our own dirs are always ignored, regardless of .gitignore. */
+  private isAlwaysIgnored(rel: string): boolean {
+    // First path segment. Ignore any CodeGraph data dir — the active one AND a
+    // sibling like `.codegraph-win` a second environment (Windows/WSL) created
+    // in the same tree, so neither side watches the other's index (#636).
+    const top = rel.split('/')[0] ?? rel;
+    return (
+      isCodeGraphDataDir(top) ||
+      rel === '.git' || rel.startsWith('.git/')
+    );
+  }
+
+  /**
+   * True for any directory that should NOT be watched (used while building the
+   * Linux per-directory watch tree). Tests the directory form of the path so a
+   * dir-only ignore rule like `build/` matches.
+   */
+  private shouldIgnoreDir(dirPath: string): boolean {
+    const rel = normalizePath(path.relative(this.projectRoot, dirPath));
+    if (!rel || rel === '.' || rel.startsWith('..')) return false; // root / outside
+    if (this.isAlwaysIgnored(rel)) return true;
+    if (!this.ignoreMatcher) return false;
+    return this.ignoreMatcher.ignores(rel + '/');
+  }
+
   /**
    * Stop watching for file changes.
    */
@@ -149,20 +460,70 @@ export class FileWatcher {
       this.debounceTimer = null;
     }
 
-    if (this.watcher) {
-      this.watcher.close();
-      this.watcher = null;
+    if (this.recursiveWatcher) {
+      try {
+        this.recursiveWatcher.close();
+      } catch {
+        /* already closed */
+      }
+      this.recursiveWatcher = null;
+    }
+    for (const w of this.dirWatchers.values()) {
+      try {
+        w.close();
+      } catch {
+        /* already closed */
+      }
     }
+    this.dirWatchers.clear();
+    this.dirCapWarned = false;
+    this.inert = false;
 
-    this.hasChanges = false;
+    this.pendingFiles.clear();
+    this.ready = false;
+    this.ignoreMatcher = null;
+    if (IS_TEST_RUNTIME) liveWatchersForTests.delete(this.projectRoot);
     logDebug('File watcher stopped');
   }
 
+  /**
+   * @internal Test-only: feed a synthetic project-relative change through the
+   * same filter → pendingFiles → debounced-sync path a real fs.watch event
+   * takes. Lets the watcher / staleness-banner suites stay deterministic
+   * instead of racing on OS watch-delivery latency. See
+   * {@link __emitWatchEventForTests}.
+   */
+  ingestEventForTests(relPath: string): void {
+    this.handleChange(normalizePath(relPath));
+  }
+
   /**
    * Whether the watcher is currently active.
    */
   isActive(): boolean {
-    return this.watcher !== null && !this.stopped;
+    return (this.recursiveWatcher !== null || this.dirWatchers.size > 0 || this.inert) && !this.stopped;
+  }
+
+  /**
+   * Resolves once the watch set has been installed (or immediately if it
+   * already has). Useful for tests that need a deterministic boundary before
+   * asserting on `pendingFiles`.
+   *
+   * Production callers don't need this: `pendingFiles` is read continuously,
+   * the staleness banner is always correct (empty or populated), and there is
+   * no asynchronous initial-scan window with `fs.watch`.
+   */
+  waitUntilReady(timeoutMs = 10000): Promise<void> {
+    if (this.ready) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const t = setTimeout(() => {
+        const idx = this.readyWaiters.indexOf(handler);
+        if (idx >= 0) this.readyWaiters.splice(idx, 1);
+        reject(new Error(`FileWatcher.waitUntilReady timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      const handler = () => { clearTimeout(t); resolve(); };
+      this.readyWaiters.push(handler);
+    });
   }
 
   /**
@@ -180,28 +541,104 @@ export class FileWatcher {
 
   /**
    * Flush pending changes by running sync.
+   *
+   * pendingFiles is NOT cleared at the start of sync — entries are removed
+   * only after sync commits successfully, and only for entries whose
+   * lastSeenMs <= syncStartedMs. That way, a query that arrives mid-sync
+   * still sees the affected files marked stale (the DB hasn't been updated
+   * yet), and an event that lands mid-sync persists into the follow-up.
+   *
+   * On sync failure pendingFiles is left untouched — every edit is still
+   * unindexed, and the rescheduled sync will absorb the same set next time.
    */
   private async flush(): Promise<void> {
     // If already syncing, the post-sync check will re-trigger
     if (this.syncing || this.stopped) return;
 
-    this.hasChanges = false;
+    this.syncStartedMs = Date.now();
     this.syncing = true;
 
     try {
       const result = await this.syncFn();
+      // Remove entries whose most recent event predates this sync — those
+      // edits are now in the DB. Entries with lastSeenMs > syncStartedMs
+      // arrived mid-sync; whether the in-flight sync captured them depends
+      // on when sync read that file, so we keep them as pending and let
+      // the follow-up sync handle them. We prefer false positives ("shown
+      // stale, actually fresh" → at worst one extra Read) over false
+      // negatives ("shown fresh, actually stale" → misleads the agent).
+      for (const [filePath, info] of this.pendingFiles) {
+        if (info.lastSeenMs <= this.syncStartedMs) {
+          this.pendingFiles.delete(filePath);
+        }
+      }
       this.onSyncComplete?.(result);
     } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      logWarn('Watch sync failed', { error: error.message });
-      this.onSyncError?.(error);
+      if (err instanceof LockUnavailableError) {
+        // Lock-failure no-op (another writer holds the lock). pendingFiles
+        // stays intact and the `finally` block reschedules. Debug-only —
+        // a long external index would otherwise spam stderr every cycle.
+        logDebug('Watch sync skipped: file lock unavailable', {
+          pendingFiles: this.pendingFiles.size,
+        });
+      } else {
+        const error = err instanceof Error ? err : new Error(String(err));
+        logWarn('Watch sync failed', { error: error.message });
+        this.onSyncError?.(error);
+      }
+      // Failure: leave pendingFiles untouched. Every edit it tracks is
+      // still unindexed; the rescheduled sync sees the same set.
     } finally {
       this.syncing = false;
 
-      // If new changes arrived during sync, schedule another
-      if (this.hasChanges && !this.stopped) {
+      // If pending files remain (mid-sync events, or this sync failed),
+      // schedule another pass.
+      if (this.pendingFiles.size > 0 && !this.stopped) {
         this.scheduleSync();
       }
     }
   }
+
+  /**
+   * Snapshot of files seen by the watcher since the last successful sync.
+   *
+   * Used by MCP tool responses to mark stale results without blocking on a
+   * sync: a tool that returns a hit in `src/foo.ts` while `src/foo.ts` is in
+   * this list tells the agent "Read this file directly, the index lags."
+   *
+   * `indexing` is true when a sync is currently in flight whose start time is
+   * AFTER this file's most recent event — i.e. that sync will absorb the
+   * edit. False means the file is still inside the debounce window and no
+   * sync has started yet (a follow-up call a few hundred ms later may show
+   * `indexing: true` or the file may have left the list entirely).
+   *
+   * Cheap: O(pendingFiles.size), no I/O, no locks.
+   */
+  getPendingFiles(): PendingFile[] {
+    const result: PendingFile[] = [];
+    for (const [filePath, info] of this.pendingFiles) {
+      result.push({
+        path: filePath,
+        firstSeenMs: info.firstSeenMs,
+        lastSeenMs: info.lastSeenMs,
+        indexing: this.syncing && this.syncStartedMs >= info.lastSeenMs,
+      });
+    }
+    return result;
+  }
+}
+
+/**
+ * Test-only: synthesize a source-file change for the live watcher running at
+ * `projectRoot`, exercising the real filter → pendingFiles → debounced-sync
+ * logic without depending on fs.watch delivery timing (which races under
+ * parallel vitest). `relPath` is project-relative POSIX (e.g. "src/foo.ts").
+ * Returns false if no live watcher is registered for that root (e.g. outside a
+ * test runtime, where the registry is intentionally not populated).
+ */
+export function __emitWatchEventForTests(projectRoot: string, relPath: string): boolean {
+  const w = liveWatchersForTests.get(projectRoot);
+  if (!w) return false;
+  w.ingestEventForTests(relPath);
+  return true;
 }
diff --git a/src/sync/worktree.ts b/src/sync/worktree.ts
new file mode 100644
index 000000000..bf370b178
--- /dev/null
+++ b/src/sync/worktree.ts
@@ -0,0 +1,115 @@
+/**
+ * Git Worktree Awareness
+ *
+ * A CodeGraph index lives in a `.codegraph/` directory and is resolved by
+ * walking up parent directories to the nearest one (see
+ * `findNearestCodeGraphRoot`). That walk is unaware of git worktrees: when a
+ * worktree is created *inside* the main checkout (e.g. some tools place them
+ * under `.gitignore`d paths like `.claude/worktrees/<name>/`), a command run
+ * from the worktree walks up and silently resolves the MAIN checkout's index.
+ *
+ * Every query then returns results from the main tree's code — usually a
+ * different branch — rather than the worktree the user is actually editing.
+ * Symbols added or changed only in the worktree are invisible. This module
+ * detects that "borrowed index" situation so callers can warn about it.
+ *
+ * Detection is best-effort: when git is unavailable or the path isn't a repo,
+ * it reports "no mismatch" and callers carry on unchanged.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+
+/**
+ * Absolute, symlink-resolved toplevel of the git working tree that `dir`
+ * belongs to, or null when `dir` isn't inside a git repo (or git is missing).
+ *
+ * `git rev-parse --show-toplevel` returns the per-worktree root: the main
+ * checkout and each linked worktree report their own distinct directory, which
+ * is exactly the distinction this module relies on.
+ */
+export function gitWorktreeRoot(dir: string): string | null {
+  try {
+    const out = execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: dir,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      windowsHide: true,
+    }).trim();
+    return out ? realpath(out) : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface WorktreeIndexMismatch {
+  /** The git working tree the command was run from. */
+  worktreeRoot: string;
+  /** The (different) working tree whose `.codegraph` index is being used. */
+  indexRoot: string;
+}
+
+/**
+ * Detect when `startPath` lives in one git working tree but the resolved
+ * CodeGraph index (`indexRoot`) belongs to a *different* working tree.
+ *
+ * Returns null — meaning "nothing to warn about" — when:
+ *   - `startPath` isn't in a git repo (or git is unavailable),
+ *   - the index already lives in `startPath`'s own working tree, or
+ *   - `indexRoot` isn't itself a working-tree root (an unrelated parent dir
+ *     that merely happens to contain a `.codegraph/`), which keeps non-git
+ *     and monorepo-subdir layouts from producing false warnings.
+ */
+export function detectWorktreeIndexMismatch(
+  startPath: string,
+  indexRoot: string,
+): WorktreeIndexMismatch | null {
+  const worktreeRoot = gitWorktreeRoot(startPath);
+  if (!worktreeRoot) return null;
+
+  const resolvedIndexRoot = realpath(indexRoot);
+  if (worktreeRoot === resolvedIndexRoot) return null;
+
+  // Only flag it when the index root is itself a real working-tree root. This
+  // distinguishes "borrowed another worktree's index" from "index sits in a
+  // plain ancestor directory", and avoids warning outside git entirely.
+  if (gitWorktreeRoot(resolvedIndexRoot) !== resolvedIndexRoot) return null;
+
+  return { worktreeRoot, indexRoot: resolvedIndexRoot };
+}
+
+/** One-line-per-fact warning describing a detected mismatch. */
+export function worktreeMismatchWarning(m: WorktreeIndexMismatch): string {
+  return (
+    `This CodeGraph index belongs to a different git working tree.\n` +
+    `  Running in: ${m.worktreeRoot}\n` +
+    `  Index from: ${m.indexRoot}\n` +
+    `Results reflect that tree's code (often a different branch), not this worktree — ` +
+    `symbols changed only here are missing. Run "codegraph init -i" in this worktree ` +
+    `for a worktree-local index.`
+  );
+}
+
+/**
+ * Compact, single-line variant for prefixing a tool's result. Read tools
+ * return their answer inline, so the heads-up has to ride on the same payload
+ * the agent is already reading — a multi-line block would bury the result.
+ */
+export function worktreeMismatchNotice(m: WorktreeIndexMismatch): string {
+  return (
+    `⚠ CodeGraph results below come from a different git worktree (${m.indexRoot}), ` +
+    `not where you're working (${m.worktreeRoot}) — they may reflect another branch, ` +
+    `and symbols changed only here are missing. Run "codegraph init -i" here for a ` +
+    `worktree-local index.`
+  );
+}
+
+/** Resolve symlinks where possible so tmp/realpath quirks don't break equality. */
+function realpath(p: string): string {
+  try {
+    return fs.realpathSync(path.resolve(p));
+  } catch {
+    return path.resolve(p);
+  }
+}
diff --git a/src/types.ts b/src/types.ts
index f7880407e..e57a74229 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -75,6 +75,7 @@ export const LANGUAGES = [
   'c',
   'cpp',
   'csharp',
+  'razor',
   'php',
   'ruby',
   'swift',
@@ -82,11 +83,17 @@ export const LANGUAGES = [
   'dart',
   'svelte',
   'vue',
+  'astro',
   'liquid',
   'pascal',
   'scala',
   'lua',
   'luau',
+  'objc',
+  'yaml',
+  'twig',
+  'xml',
+  'properties',
   'unknown',
 ] as const;
 
@@ -157,6 +164,15 @@ export interface Node {
   /** Generic type parameters */
   typeParameters?: string[];
 
+  /**
+   * Normalized return/result type name for a function/method (the bare class
+   * name, smart-pointer pointee unwrapped). Captured for C/C++ so resolution
+   * can infer a chained receiver's type from what the inner call returns —
+   * `Foo::instance().bar()` resolves `bar` on `Foo` (issue #645). Undefined for
+   * languages/symbols where it isn't captured.
+   */
+  returnType?: string;
+
   /** When the node was last updated */
   updatedAt: number;
 }
@@ -263,6 +279,14 @@ export interface ExtractionError {
   code?: string;
 }
 
+/**
+ * Kinds an unresolved reference can carry. `function_ref` is internal-only —
+ * a function name used as a VALUE (callback registration, #756). It never
+ * becomes an edge kind: resolution maps it to a `references` edge targeting
+ * function/method nodes only (see `matchFunctionRef`).
+ */
+export type ReferenceKind = EdgeKind | 'function_ref';
+
 /**
  * A reference that couldn't be resolved during extraction
  */
@@ -274,7 +298,7 @@ export interface UnresolvedReference {
   referenceName: string;
 
   /** Type of reference (call, type, import, etc.) */
-  referenceKind: EdgeKind;
+  referenceKind: ReferenceKind;
 
   /** Location of the reference */
   line: number;
@@ -306,6 +330,15 @@ export interface Subgraph {
 
   /** Root node IDs (entry points) */
   roots: string[];
+
+  /**
+   * Retrieval confidence for context-style queries. `'low'` means the query
+   * resolved only to isolated common-word matches (no entry point corroborated
+   * by 2+ distinct query terms) — callers should surface an honest handoff to
+   * explore/trace rather than present the results as comprehensive. Undefined
+   * for graph traversals that don't run the search-ranking path.
+   */
+  confidence?: 'high' | 'low';
 }
 
 /**
@@ -424,283 +457,6 @@ export interface CodeBlock {
   node?: Node;
 }
 
-// =============================================================================
-// Configuration Types
-// =============================================================================
-
-/**
- * Framework-specific hints for better extraction
- */
-export interface FrameworkHint {
-  /** Framework name (react, express, django, etc.) */
-  name: string;
-
-  /** Version constraint if relevant */
-  version?: string;
-
-  /** Custom patterns for this framework */
-  patterns?: {
-    /** Component detection patterns */
-    components?: string[];
-    /** Route detection patterns */
-    routes?: string[];
-    /** Model detection patterns */
-    models?: string[];
-  };
-}
-
-/**
- * Configuration for a CodeGraph project
- */
-export interface CodeGraphConfig {
-  /** Schema version for migrations */
-  version: number;
-
-  /** Root directory of the project */
-  rootDir: string;
-
-  /** Glob patterns for files to include */
-  include: string[];
-
-  /** Glob patterns for files to exclude */
-  exclude: string[];
-
-  /** Languages to process (auto-detected if empty) */
-  languages: Language[];
-
-  /** Framework hints for better extraction */
-  frameworks: FrameworkHint[];
-
-  /** Maximum file size to process (in bytes) */
-  maxFileSize: number;
-
-  /** Whether to extract docstrings */
-  extractDocstrings: boolean;
-
-  /** Whether to track call sites */
-  trackCallSites: boolean;
-
-  /** Custom symbol patterns to extract */
-  customPatterns?: {
-    /** Name for this pattern group */
-    name: string;
-    /** Regex pattern to match */
-    pattern: string;
-    /** Node kind to assign */
-    kind: NodeKind;
-  }[];
-}
-
-/**
- * Default configuration values
- */
-export const DEFAULT_CONFIG: CodeGraphConfig = {
-  version: 1,
-  rootDir: '.',
-  include: [
-    // TypeScript/JavaScript
-    '**/*.ts',
-    '**/*.tsx',
-    '**/*.js',
-    '**/*.jsx',
-    // Python
-    '**/*.py',
-    // Go
-    '**/*.go',
-    // Rust
-    '**/*.rs',
-    // Java
-    '**/*.java',
-    // C/C++
-    '**/*.c',
-    '**/*.h',
-    '**/*.cpp',
-    '**/*.hpp',
-    '**/*.cc',
-    '**/*.cxx',
-    // C#
-    '**/*.cs',
-    // PHP
-    '**/*.php',
-    // Ruby
-    '**/*.rb',
-    // Swift
-    '**/*.swift',
-    // Kotlin
-    '**/*.kt',
-    '**/*.kts',
-    // Dart
-    '**/*.dart',
-    // Svelte
-    '**/*.svelte',
-    // Vue
-    '**/*.vue',
-    // Liquid (Shopify themes)
-    '**/*.liquid',
-    // Pascal / Delphi
-    '**/*.pas',
-    '**/*.dpr',
-    '**/*.dpk',
-    '**/*.lpr',
-    '**/*.dfm',
-    '**/*.fmx',
-    // Scala
-    '**/*.scala',
-    '**/*.sc',
-    // Lua
-    '**/*.lua',
-    // Luau
-    '**/*.luau',
-  ],
-  exclude: [
-    // Version control
-    '**/.git/**',
-
-    // Dependencies
-    '**/node_modules/**',
-    '**/vendor/**',
-    '**/Pods/**',
-
-    // Generic build outputs
-    '**/dist/**',
-    '**/build/**',
-    '**/out/**',
-    '**/bin/**',
-    '**/obj/**',
-    '**/target/**',
-
-    // JavaScript/TypeScript
-    '**/*.min.js',
-    '**/*.bundle.js',
-    '**/.next/**',
-    '**/.nuxt/**',
-    '**/.svelte-kit/**',
-    '**/.output/**',
-    '**/.turbo/**',
-    '**/.cache/**',
-    '**/.parcel-cache/**',
-    '**/.vite/**',
-    '**/.astro/**',
-    '**/.docusaurus/**',
-    '**/.gatsby/**',
-    '**/.webpack/**',
-    '**/.nx/**',
-    '**/.yarn/cache/**',
-    '**/.pnpm-store/**',
-    '**/storybook-static/**',
-
-    // React Native / Expo
-    '**/.expo/**',
-    '**/web-build/**',
-    '**/ios/Pods/**',
-    '**/ios/build/**',
-    '**/android/build/**',
-    '**/android/.gradle/**',
-
-    // Python
-    '**/__pycache__/**',
-    '**/.venv/**',
-    '**/venv/**',
-    '**/site-packages/**',
-    '**/dist-packages/**',
-    '**/.pytest_cache/**',
-    '**/.mypy_cache/**',
-    '**/.ruff_cache/**',
-    '**/.tox/**',
-    '**/.nox/**',
-    '**/*.egg-info/**',
-    '**/.eggs/**',
-
-    // Go
-    '**/go/pkg/mod/**',
-
-    // Rust
-    '**/target/debug/**',
-    '**/target/release/**',
-
-    // Java/Kotlin/Gradle
-    '**/.gradle/**',
-    '**/.m2/**',
-    '**/generated-sources/**',
-    '**/.kotlin/**',
-
-    // Dart/Flutter
-    '**/.dart_tool/**',
-
-    // C#/.NET
-    '**/.vs/**',
-    '**/.nuget/**',
-    '**/artifacts/**',
-    '**/publish/**',
-
-    // C/C++
-    '**/cmake-build-*/**',
-    '**/CMakeFiles/**',
-    '**/bazel-*/**',
-    '**/vcpkg_installed/**',
-    '**/.conan/**',
-    '**/Debug/**',
-    '**/Release/**',
-    '**/x64/**',
-    '**/.pio/**',  // Platform.io (IoT/embedded build artifacts and library deps)
-
-    // Electron
-    '**/release/**',
-    '**/*.app/**',
-    '**/*.asar',
-
-    // Swift/iOS/Xcode
-    '**/DerivedData/**',
-    '**/.build/**',
-    '**/.swiftpm/**',
-    '**/xcuserdata/**',
-    '**/Carthage/Build/**',
-    '**/SourcePackages/**',
-
-    // Delphi/Pascal
-    '**/__history/**',
-    '**/__recovery/**',
-    '**/*.dcu',
-
-    // PHP
-    '**/.composer/**',
-    '**/storage/framework/**',
-    '**/bootstrap/cache/**',
-
-    // Ruby
-    '**/.bundle/**',
-    '**/tmp/cache/**',
-    '**/public/assets/**',
-    '**/public/packs/**',
-    '**/.yardoc/**',
-
-    // Testing/Coverage
-    '**/coverage/**',
-    '**/htmlcov/**',
-    '**/.nyc_output/**',
-    '**/test-results/**',
-    '**/.coverage/**',
-
-    // IDE/Editor
-    '**/.idea/**',
-
-    // Logs and temp
-    '**/logs/**',
-    '**/tmp/**',
-    '**/temp/**',
-
-    // Documentation build output
-    '**/_build/**',
-    '**/docs/_build/**',
-    '**/site/**',
-  ],
-  languages: [],
-  frameworks: [],
-  maxFileSize: 1024 * 1024, // 1MB
-  extractDocstrings: true,
-  trackCallSites: true,
-};
-
 // =============================================================================
 // Database Types
 // =============================================================================
diff --git a/src/upgrade/index.ts b/src/upgrade/index.ts
new file mode 100644
index 000000000..bf9d5c303
--- /dev/null
+++ b/src/upgrade/index.ts
@@ -0,0 +1,515 @@
+/**
+ * `codegraph upgrade`
+ *
+ * Self-update for the CLI, whatever way it was installed:
+ *
+ *   - **bundle** — the self-contained runtime+app installed by `install.sh`
+ *     (Linux/macOS) or `install.ps1` (Windows). Upgrading re-runs the SAME
+ *     canonical installer script (single source of truth) so the download /
+ *     version-resolution / PATH logic never drifts between first-install and
+ *     upgrade.
+ *   - **npm** — installed via `npm i -g @colbymchenry/codegraph`. Upgrading
+ *     shells out to npm.
+ *   - **npx** — ephemeral; nothing to upgrade (next `npx` fetches latest).
+ *   - **source** — a git checkout running its own `dist/`; `git pull` + rebuild.
+ *
+ * Detection is structural (see `detectInstallMethod`): a bundle carries a
+ * vendored `node` binary and a `bin/codegraph` launcher next to its `lib/`, so
+ * we can recognize it from the running file's path without a marker file.
+ *
+ * Windows wrinkle: a running `node.exe` is locked and can't be deleted, so the
+ * bundle's `current\` dir can't be overwritten in place by the process doing
+ * the upgrade. We therefore spawn a DETACHED helper that waits for this
+ * process to exit (releasing the lock), then runs `install.ps1`. This is the
+ * conventional Windows self-update dance (rustup/nvm-windows do the same).
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as https from 'https';
+import { spawnSync } from 'child_process';
+
+export const REPO = 'colbymchenry/codegraph';
+export const NPM_PACKAGE = '@colbymchenry/codegraph';
+const RAW_BASE = `https://raw.githubusercontent.com/${REPO}/main`;
+export const INSTALL_SH_URL = `${RAW_BASE}/install.sh`;
+
+// ---------------------------------------------------------------------------
+// Install-method detection (pure — fully unit-testable via injected probes)
+// ---------------------------------------------------------------------------
+
+export type InstallMethod =
+  | { kind: 'bundle'; os: 'unix' | 'windows'; bundleRoot: string; installDir: string | null }
+  | { kind: 'npm'; scope: 'global' | 'local' }
+  | { kind: 'npx' }
+  | { kind: 'source'; root: string }
+  | { kind: 'unknown'; reason: string };
+
+export interface DetectInput {
+  /** `__filename` of the running CLI module — `<…>/dist/bin/codegraph.js`. */
+  filename: string;
+  platform: NodeJS.Platform;
+  cwd: string;
+  /** Injectable existence probe (defaults to fs.existsSync) — for tests. */
+  exists?: (p: string) => boolean;
+}
+
+function toPosix(p: string): string {
+  return p.replace(/\\/g, '/');
+}
+
+/**
+ * Where the bundle installer keeps its install root, derived from the bundle
+ * dir so an upgrade reuses a custom `CODEGRAPH_INSTALL_DIR`. Returns null when
+ * the layout isn't the one the installer creates (then the installer falls
+ * back to its own default).
+ *
+ *   unix:    <installDir>/versions/<vX.Y.Z>   (bundleRoot)  → <installDir>
+ *   windows: <installDir>\current             (bundleRoot)  → <installDir>
+ */
+export function deriveInstallDir(
+  bundleRoot: string,
+  os: 'unix' | 'windows',
+  exists: (p: string) => boolean
+): string | null {
+  // Use the TARGET platform's path semantics (not the host's), so this is
+  // deterministic when reasoning about a Windows layout from a POSIX host (CI)
+  // and vice-versa. In production `os` always matches the running platform.
+  const P = os === 'windows' ? path.win32 : path.posix;
+  if (os === 'windows') {
+    if (P.basename(bundleRoot).toLowerCase() === 'current') {
+      return P.dirname(bundleRoot);
+    }
+    return null;
+  }
+  // unix: bundleRoot is <installDir>/versions/<version>
+  const parent = P.dirname(bundleRoot);
+  if (P.basename(parent) === 'versions') {
+    const installDir = P.dirname(parent);
+    return exists(installDir) ? installDir : P.dirname(parent);
+  }
+  return null;
+}
+
+export function detectInstallMethod(input: DetectInput): InstallMethod {
+  const exists = input.exists ?? fs.existsSync;
+  const isWin = input.platform === 'win32';
+  // Path math keyed on the TARGET platform so detection is host-independent
+  // (a Windows layout resolves correctly even when unit-tested on macOS/Linux).
+  const P = isWin ? path.win32 : path.posix;
+  const binDir = P.dirname(input.filename); // <…>/bin
+
+  // Bundle: <root>/lib/dist/bin/codegraph.js → <root> is up 3 from bin/.
+  // A bundle has a vendored node + a launcher script as siblings of lib/.
+  const bundleRoot = P.resolve(binDir, '..', '..', '..');
+  const vendoredNode = P.join(bundleRoot, isWin ? 'node.exe' : 'node');
+  const launcher = P.join(bundleRoot, 'bin', isWin ? 'codegraph.cmd' : 'codegraph');
+  if (exists(vendoredNode) && exists(launcher)) {
+    const os = isWin ? 'windows' : 'unix';
+    return { kind: 'bundle', os, bundleRoot, installDir: deriveInstallDir(bundleRoot, os, exists) };
+  }
+
+  const norm = toPosix(input.filename);
+
+  // npx cache: <…>/_npx/<hash>/node_modules/@colbymchenry/codegraph/…
+  if (norm.includes('/_npx/')) {
+    return { kind: 'npx' };
+  }
+
+  // npm install (global or local): lives under a node_modules tree.
+  if (norm.includes('/node_modules/')) {
+    const underCwd = norm.startsWith(toPosix(P.resolve(input.cwd)) + '/');
+    return { kind: 'npm', scope: underCwd ? 'local' : 'global' };
+  }
+
+  // Source checkout: running <repo>/dist/bin/codegraph.js with a sibling .git.
+  const repoRoot = P.resolve(binDir, '..', '..');
+  if (exists(P.join(repoRoot, 'package.json')) && exists(P.join(repoRoot, '.git'))) {
+    return { kind: 'source', root: repoRoot };
+  }
+
+  return { kind: 'unknown', reason: `unrecognized install layout at ${input.filename}` };
+}
+
+// ---------------------------------------------------------------------------
+// Version helpers (pure)
+// ---------------------------------------------------------------------------
+
+export interface Semver {
+  major: number;
+  minor: number;
+  patch: number;
+  pre: string | null;
+}
+
+export function parseSemver(version: string): Semver | null {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(version.trim());
+  if (!m) return null;
+  return {
+    major: parseInt(m[1]!, 10),
+    minor: parseInt(m[2]!, 10),
+    patch: parseInt(m[3]!, 10),
+    pre: m[4] ?? null,
+  };
+}
+
+/** Returns >0 if a>b, <0 if a<b, 0 if equal. Throws on unparseable input. */
+export function compareVersions(a: string, b: string): number {
+  const sa = parseSemver(a);
+  const sb = parseSemver(b);
+  if (!sa || !sb) throw new Error(`cannot compare versions: "${a}" vs "${b}"`);
+  if (sa.major !== sb.major) return sa.major - sb.major;
+  if (sa.minor !== sb.minor) return sa.minor - sb.minor;
+  if (sa.patch !== sb.patch) return sa.patch - sb.patch;
+  // A prerelease is "less than" its release (1.0.0-rc < 1.0.0).
+  if (sa.pre && !sb.pre) return -1;
+  if (!sa.pre && sb.pre) return 1;
+  if (sa.pre && sb.pre) return sa.pre < sb.pre ? -1 : sa.pre > sb.pre ? 1 : 0;
+  return 0;
+}
+
+export function isUpdateAvailable(current: string, latest: string): boolean {
+  try {
+    return compareVersions(latest, current) > 0;
+  } catch {
+    // If either is unparseable (e.g. a dev "0.0.0-unknown"), treat differing
+    // strings as "update available" so the user isn't stuck.
+    return normalizeVersion(current) !== normalizeVersion(latest);
+  }
+}
+
+/** `0.9.9` / `v0.9.9` → `v0.9.9` (release tags are v-prefixed). */
+export function normalizeVersion(v: string): string {
+  const t = v.trim();
+  return t.startsWith('v') ? t : `v${t}`;
+}
+
+/** Strip a leading `v`: `v0.9.9` → `0.9.9`. */
+export function stripV(v: string): string {
+  const t = v.trim();
+  return t.startsWith('v') ? t.slice(1) : t;
+}
+
+/**
+ * Parse the release tag out of the `Location` header GitHub returns for
+ * `/releases/latest` → `…/releases/tag/v0.9.9`. Pure so it's unit-tested.
+ */
+export function parseLatestTagFromLocation(location: string | undefined): string | null {
+  if (!location) return null;
+  const m = /\/releases\/tag\/([^/?#]+)/.exec(location);
+  return m ? decodeURIComponent(m[1]!) : null;
+}
+
+// ---------------------------------------------------------------------------
+// Latest-version resolution (network)
+// ---------------------------------------------------------------------------
+
+function httpsGet(
+  url: string,
+  headers: Record<string, string>,
+  timeoutMs: number
+): Promise<{ status: number; headers: Record<string, string | string[] | undefined>; body: string }> {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { headers }, (res) => {
+      let body = '';
+      res.on('data', (c) => (body += c));
+      res.on('end', () => resolve({ status: res.statusCode ?? 0, headers: res.headers, body }));
+    });
+    req.on('error', reject);
+    req.setTimeout(timeoutMs, () => req.destroy(new Error(`request timed out after ${timeoutMs}ms`)));
+  });
+}
+
+/**
+ * Resolve the latest release tag (e.g. `v0.9.9`).
+ *
+ * Primary: read the redirect `Location` from `github.com/<repo>/releases/latest`
+ * — same trick install.sh uses, because the unauthenticated GitHub API is
+ * rate-limited to 60 req/h/IP and 403s on shared/cloud hosts (issue #325). The
+ * redirect has no such limit. Fall back to the API only if the redirect can't
+ * be read.
+ */
+export async function resolveLatestVersion(repo = REPO, timeoutMs = 12000): Promise<string> {
+  try {
+    const res = await httpsGet(
+      `https://github.com/${repo}/releases/latest`,
+      { 'User-Agent': 'codegraph-upgrade' },
+      timeoutMs
+    );
+    const loc = res.headers.location;
+    const tag = parseLatestTagFromLocation(Array.isArray(loc) ? loc[0] : loc);
+    if (tag) return normalizeVersion(tag);
+  } catch {
+    /* fall through to API */
+  }
+  try {
+    const res = await httpsGet(
+      `https://api.github.com/repos/${repo}/releases/latest`,
+      { 'User-Agent': 'codegraph-upgrade', Accept: 'application/vnd.github+json' },
+      timeoutMs
+    );
+    const tag = JSON.parse(res.body)?.tag_name;
+    if (typeof tag === 'string' && tag) return normalizeVersion(tag);
+  } catch {
+    /* fall through to error */
+  }
+  throw new Error(
+    'could not resolve the latest version from GitHub. Check your network, or pin a version: `codegraph upgrade <version>`.'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+export interface UpgradeOptions {
+  /** Pin a specific version (positional arg or CODEGRAPH_VERSION). */
+  version?: string;
+  /** Report current vs latest, don't change anything. */
+  check?: boolean;
+  /** Reinstall even if already on the resolved version. */
+  force?: boolean;
+}
+
+/** Injectable side-effects so the orchestrator stays unit-testable. */
+export interface UpgradeDeps {
+  currentVersion: string;
+  method: InstallMethod;
+  resolveLatest: (pin?: string) => Promise<string>;
+  /** Run a command inheriting stdio; returns its exit code (-1 = spawn failed). */
+  run: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => number;
+  hasCommand: (cmd: string) => boolean;
+  log: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+  platform: NodeJS.Platform;
+}
+
+const c = {
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+};
+
+/** The honest, additive re-index reminder shown after a successful upgrade. */
+export function reindexAdvisory(): string {
+  return [
+    c.dim('Your existing project indexes keep working, but were built by the previous version.'),
+    c.dim('To pick up this version’s extraction improvements, refresh each project:'),
+    `  ${c.cyan('codegraph sync')}        ${c.dim('# incremental, fast')}`,
+    `  ${c.cyan('codegraph index -f')}    ${c.dim('# full rebuild')}`,
+    c.dim('(`codegraph status` flags any index that predates the engine you’re running.)'),
+  ].join('\n');
+}
+
+/**
+ * Returns the process exit code (0 = success / nothing to do, 1 = failure).
+ */
+export async function runUpgrade(opts: UpgradeOptions, deps: UpgradeDeps): Promise<number> {
+  const { currentVersion, method } = deps;
+
+  // Resolve the target version (pinned or latest).
+  let latest: string;
+  try {
+    latest = normalizeVersion(opts.version || (await deps.resolveLatest()));
+  } catch (err) {
+    deps.error(err instanceof Error ? err.message : String(err));
+    return 1;
+  }
+
+  const currentDisplay = normalizeVersion(currentVersion);
+  deps.log(`${c.bold('CodeGraph')}  current ${c.cyan(currentDisplay)}  ${opts.version ? 'target' : 'latest'} ${c.cyan(latest)}`);
+
+  const updateAvailable = isUpdateAvailable(currentVersion, latest);
+
+  if (opts.check) {
+    if (updateAvailable) {
+      deps.log(c.yellow(`An update is available: ${currentDisplay} → ${latest}`));
+      deps.log(c.dim('Run `codegraph upgrade` to install it.'));
+    } else {
+      deps.log(c.green(`You’re on the latest version (${currentDisplay}).`));
+    }
+    return 0;
+  }
+
+  if (!updateAvailable && !opts.force && !opts.version) {
+    deps.log(c.green(`Already up to date (${currentDisplay}).`));
+    deps.log(c.dim('Use `--force` to reinstall, or `codegraph upgrade <version>` to change versions.'));
+    return 0;
+  }
+
+  // Dispatch by install method.
+  switch (method.kind) {
+    case 'bundle':
+      return method.os === 'windows'
+        ? upgradeWindowsBundle(method, latest, deps)
+        : upgradeUnixBundle(method, opts.version ? latest : undefined, deps);
+    case 'npm':
+      // npm version specs have no leading "v" (`@0.9.8`, not `@v0.9.8` — the
+      // latter resolves as a nonexistent dist-tag).
+      return upgradeNpm(method, opts.version ? stripV(latest) : 'latest', deps);
+    case 'npx':
+      deps.log(c.green('npx always runs the latest version on demand — nothing to upgrade.'));
+      deps.log(c.dim(`Force a fresh fetch with: npx ${NPM_PACKAGE}@latest`));
+      return 0;
+    case 'source':
+      deps.warn(`Running from a source checkout at ${method.root}.`);
+      deps.log(c.dim('Upgrade it with: git pull && npm run build'));
+      return 0;
+    default:
+      deps.error(`Couldn’t determine how CodeGraph was installed (${method.reason}).`);
+      deps.log(c.dim(`Reinstall manually — see https://github.com/${REPO}#install`));
+      return 1;
+  }
+}
+
+function upgradeUnixBundle(
+  method: Extract<InstallMethod, { kind: 'bundle' }>,
+  pinned: string | undefined,
+  deps: UpgradeDeps
+): number {
+  const downloader = deps.hasCommand('curl')
+    ? `curl -fsSL ${INSTALL_SH_URL}`
+    : deps.hasCommand('wget')
+      ? `wget -qO- ${INSTALL_SH_URL}`
+      : null;
+  if (!downloader) {
+    deps.error('Neither curl nor wget is available to download the installer.');
+    deps.log(c.dim(`Install curl, or run manually:  ${INSTALL_SH_URL} | sh`));
+    return 1;
+  }
+
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  if (method.installDir) env.CODEGRAPH_INSTALL_DIR = method.installDir;
+  if (pinned) env.CODEGRAPH_VERSION = pinned;
+
+  deps.log(c.dim(`Running the installer (${downloader} | sh)…`));
+  const code = deps.run('sh', ['-c', `${downloader} | sh`], env);
+  if (code !== 0) {
+    deps.error(`Installer exited with code ${code}.`);
+    return 1;
+  }
+  deps.log('');
+  deps.log(c.green('✓ Upgrade complete.') + c.dim(' Open a new terminal if the version looks unchanged (PATH cache).'));
+  deps.log(reindexAdvisory());
+  return 0;
+}
+
+/** Build the in-place Windows upgrade script (exported for unit-testing). */
+export function buildWindowsUpgradeScript(bundleRoot: string, version: string, arch: string): string {
+  const target = `win32-${arch}`;
+  const url = `https://github.com/${REPO}/releases/download/${version}/codegraph-${target}.zip`;
+  // Windows can't DELETE a running exe but CAN rename it, so we upgrade IN
+  // PLACE: download → rename the locked node.exe aside → extract the new bundle
+  // over current\. Synchronous, no detached helper (which dies under SSH/job
+  // objects and has worse UX). The running process keeps its renamed node.exe
+  // mapped; the NEXT `codegraph` invocation uses the new one. We can't reuse
+  // install.ps1 here — it `Remove-Item`s current\, which fails on the locked exe.
+  return [
+    `$ErrorActionPreference='Stop'`,
+    `$dest='${bundleRoot}'`,
+    `$url='${url}'`,
+    `Write-Host "Downloading $url"`,
+    `$tmp=Join-Path $env:TEMP ('cg-up-'+[guid]::NewGuid().ToString('N'))`,
+    `New-Item -ItemType Directory -Force -Path $tmp | Out-Null`,
+    `$zip=Join-Path $tmp 'cg.zip'`,
+    `Invoke-WebRequest -Uri $url -OutFile $zip`,
+    `$stage=Join-Path $tmp 'stage'`,
+    `Expand-Archive -Path $zip -DestinationPath $stage -Force`,
+    `$inner=Join-Path $stage 'codegraph-${target}'`,
+    `$src=if(Test-Path $inner){$inner}else{$stage}`,
+    `$node=Join-Path $dest 'node.exe'`,
+    `if(Test-Path $node){Rename-Item -Path $node -NewName ('node.exe.old-'+[guid]::NewGuid().ToString('N')) -Force}`,
+    `Copy-Item -Path (Join-Path $src '*') -Destination $dest -Recurse -Force`,
+    `Get-ChildItem -Path $dest -Filter 'node.exe.old-*' -ErrorAction SilentlyContinue | ForEach-Object { try { Remove-Item $_.FullName -Force -ErrorAction Stop } catch {} }`,
+    `Remove-Item -Recurse -Force $tmp -ErrorAction SilentlyContinue`,
+    `Write-Host "Installed CodeGraph ${version} to $dest"`,
+  ].join(';');
+}
+
+function upgradeWindowsBundle(
+  method: Extract<InstallMethod, { kind: 'bundle' }>,
+  latest: string,
+  deps: UpgradeDeps
+): number {
+  const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+  const script = buildWindowsUpgradeScript(method.bundleRoot, latest, arch);
+  // -EncodedCommand (base64 UTF-16LE), NOT -Command: Node's Windows argv→command
+  // -line quoting mangles a long multi-statement script, so PowerShell never
+  // parses it. Encoding sidesteps all shell quoting — the canonical approach.
+  const encoded = Buffer.from(script, 'utf16le').toString('base64');
+  deps.log(c.dim(`Downloading and installing ${latest}…`));
+  const code = deps.run('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded]);
+  if (code !== 0) {
+    deps.error(`Installer exited with code ${code}.`);
+    return 1;
+  }
+  deps.log('');
+  deps.log(c.green('✓ Upgrade complete.') + c.dim(' Open a new terminal to be safe (PATH/version cache).'));
+  deps.log(reindexAdvisory());
+  return 0;
+}
+
+function upgradeNpm(
+  method: Extract<InstallMethod, { kind: 'npm' }>,
+  versionSpec: string,
+  deps: UpgradeDeps
+): number {
+  const npm = deps.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const args = method.scope === 'global'
+    ? ['install', '-g', `${NPM_PACKAGE}@${versionSpec}`]
+    : ['install', `${NPM_PACKAGE}@${versionSpec}`];
+  deps.log(c.dim(`Running: ${npm} ${args.join(' ')}`));
+  const code = deps.run(npm, args, process.env);
+  if (code !== 0) {
+    deps.error(`npm exited with code ${code}.`);
+    if (method.scope === 'global') {
+      deps.log(c.dim('If this is a permissions error (EACCES), your global prefix needs sudo, or use a'));
+      deps.log(c.dim('Node version manager (nvm/fnm) so global installs don’t require root.'));
+    }
+    return 1;
+  }
+  deps.log('');
+  deps.log(c.green('✓ Upgrade complete.'));
+  deps.log(reindexAdvisory());
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Production deps wiring (used by the CLI)
+// ---------------------------------------------------------------------------
+
+/**
+ * True if `cmd` resolves to an executable on PATH. A pure-Node PATH scan — NOT
+ * a spawned `command -v`/`which`: `command` is a shell builtin (no standalone
+ * binary on Debian, though macOS ships one), and `which` isn't guaranteed
+ * present on minimal images, so spawning either is unreliable. Scanning PATH
+ * ourselves behaves identically on every platform.
+ */
+export function hasCommand(cmd: string): boolean {
+  const isWin = process.platform === 'win32';
+  const dirs = (process.env.PATH || process.env.Path || '').split(path.delimiter).filter(Boolean);
+  const exts = isWin ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';') : [''];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, cmd + ext);
+      try {
+        if (!fs.statSync(candidate).isFile()) continue;
+        if (isWin) return true;
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return true;
+      } catch {
+        /* not here / not executable — keep scanning */
+      }
+    }
+  }
+  return false;
+}
+
+export function defaultRun(cmd: string, args: string[], env?: NodeJS.ProcessEnv): number {
+  const r = spawnSync(cmd, args, { stdio: 'inherit', env: env ?? process.env });
+  if (r.error) return -1;
+  return r.status ?? -1;
+}
diff --git a/src/utils.ts b/src/utils.ts
index e75e58e07..3c4d78e2d 100644
--- a/src/utils.ts
+++ b/src/utils.ts
@@ -43,25 +43,84 @@ import * as path from 'path';
 const SENSITIVE_PATHS = new Set([
   '/', '/etc', '/usr', '/bin', '/sbin', '/var', '/tmp', '/dev', '/proc', '/sys',
   '/root', '/boot', '/lib', '/lib64', '/opt',
-  'C:\\', 'C:\\Windows', 'C:\\Windows\\System32',
+  'c:\\', 'c:\\windows', 'c:\\windows\\system32',
 ]);
 
 /**
- * Validate that a resolved file path stays within the project root.
- * Prevents path traversal attacks (e.g. node.filePath = "../../etc/passwd").
+ * Config "languages" whose nodes are pure key/value DATA lifted from a config
+ * file (e.g. Spring `application.{yml,properties}`), not source code.
+ */
+export const CONFIG_LEAF_LANGUAGES: ReadonlySet<string> = new Set(['yaml', 'properties']);
+
+/**
+ * A config-leaf node is a single key lifted out of a pure config/data file —
+ * `kind: 'constant'` in a {@link CONFIG_LEAF_LANGUAGES} language. Its on-disk
+ * line is `key = <value>`, and that value is routinely a secret (DB password,
+ * API key, JDBC URL with embedded creds). CodeGraph must surface the KEY only
+ * and never read/return the value, or it pushes secrets into agent context
+ * unbidden — the value isn't needed for resolution, and an agent that genuinely
+ * needs it can read the file directly. (#383)
+ */
+export function isConfigLeafNode(node: { kind: string; language?: string }): boolean {
+  return node.kind === 'constant' && !!node.language && CONFIG_LEAF_LANGUAGES.has(node.language);
+}
+
+/**
+ * Whether `child` is `parent` itself or sits underneath it. Case-insensitive on
+ * Windows — NTFS is case-insensitive, and realpathSync can hand back a different
+ * case than the lexical root, which would otherwise false-reject a valid file.
+ */
+function isWithinDir(child: string, parent: string): boolean {
+  let c = child;
+  let p = parent;
+  if (process.platform === 'win32') {
+    c = c.toLowerCase();
+    p = p.toLowerCase();
+  }
+  return c === p || c.startsWith(p + path.sep);
+}
+
+/**
+ * Validate that a file path stays within the project root, resolving symlinks.
+ *
+ * Two layers: a cheap lexical check that catches `../` traversal, then a
+ * realpath check that catches symlink escapes — an in-repo symlink whose
+ * logical path is inside the root but whose real target points outside it
+ * (issue #527). A symlink that stays within the root is still allowed, so
+ * legitimate in-tree symlinks keep working. Both content-serving read sinks
+ * (codegraph_node `includeCode`, codegraph_explore source) go through here, so
+ * this is the chokepoint that keeps out-of-root file contents from leaking.
  *
  * @param projectRoot - The project root directory
- * @param filePath - The relative file path to validate
- * @returns The resolved absolute path, or null if it escapes the root
+ * @param filePath - The (relative or absolute) file path to validate
+ * @returns The resolved absolute path (realpath when it exists), or null if it
+ *   escapes the root
  */
 export function validatePathWithinRoot(projectRoot: string, filePath: string): string | null {
   const resolved = path.resolve(projectRoot, filePath);
   const normalizedRoot = path.resolve(projectRoot);
 
-  if (!resolved.startsWith(normalizedRoot + path.sep) && resolved !== normalizedRoot) {
+  // 1. Lexical containment — cheap, catches `../` traversal.
+  if (!isWithinDir(resolved, normalizedRoot)) {
+    return null;
+  }
+
+  // 2. Symlink-aware containment — resolve symlinks on both sides and re-check,
+  //    so an in-repo symlink whose real target escapes the root is rejected.
+  try {
+    const realRoot = fs.realpathSync(normalizedRoot);
+    const realResolved = fs.realpathSync(resolved);
+    return isWithinDir(realResolved, realRoot) ? realResolved : null;
+  } catch (err) {
+    // ENOENT: the path doesn't exist yet (a file about to be written, or an
+    // index entry for a since-deleted file) — no symlink to follow, and the
+    // lexical check already passed, so allow the lexical path. Any other
+    // resolution failure (ELOOP, EACCES, …) is treated as unsafe → reject.
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return resolved;
+    }
     return null;
   }
-  return resolved;
 }
 
 /**
@@ -105,47 +164,6 @@ export function validateProjectPath(dirPath: string): string | null {
   return null;
 }
 
-/**
- * Check if a file path resolves to a location within the given root directory.
- *
- * Prevents path traversal attacks by ensuring the resolved absolute path
- * starts with the resolved root path. Handles '..' sequences, symlink-like
- * relative paths, and platform-specific separators.
- *
- * @param filePath - The path to check (can be relative or absolute)
- * @param rootDir - The root directory that filePath must stay within
- * @returns true if filePath resolves to a location within rootDir
- */
-export function isPathWithinRoot(filePath: string, rootDir: string): boolean {
-  const resolvedPath = path.resolve(rootDir, filePath);
-  const resolvedRoot = path.resolve(rootDir);
-  return resolvedPath.startsWith(resolvedRoot + path.sep) || resolvedPath === resolvedRoot;
-}
-
-/**
- * Like isPathWithinRoot but also resolves symlinks via fs.realpathSync.
- *
- * This catches symlink escapes where the logical path appears to be within
- * root but the real path on disk points elsewhere. Falls back to logical
- * path checking if realpath resolution fails (e.g. broken symlink).
- */
-export function isPathWithinRootReal(filePath: string, rootDir: string): boolean {
-  // First do the cheap logical check
-  if (!isPathWithinRoot(filePath, rootDir)) {
-    return false;
-  }
-
-  // Then verify with realpath to catch symlink escapes
-  try {
-    const realPath = fs.realpathSync(path.resolve(rootDir, filePath));
-    const realRoot = fs.realpathSync(rootDir);
-    return realPath.startsWith(realRoot + path.sep) || realPath === realRoot;
-  } catch {
-    // If realpath fails (broken symlink, permissions), fall back to logical check
-    return true;
-  }
-}
-
 /**
  * Safely parse JSON with a fallback value.
  * Prevents crashes from corrupted database metadata.
diff --git a/vitest.config.ts b/vitest.config.ts
index 2449a989e..4a5ad904b 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -5,6 +5,20 @@ export default defineConfig({
     globals: true,
     environment: 'node',
     include: ['__tests__/**/*.test.ts'],
+    /**
+     * Several MCP integration tests (mcp-daemon, mcp-initialize, mcp-ppid-watchdog,
+     * mcp-roots) spawn `dist/bin/codegraph.js serve --mcp` with `process.execPath`
+     * and rely on the child inheriting `process.env`. On a Node >= 25 dev machine
+     * the CLI's hard-block (src/bin/codegraph.ts) would otherwise exit the child
+     * before it ever responds, so every spawn-based test times out — see #478.
+     *
+     * Setting the override here keeps the CLI's runtime guard intact for end
+     * users (it's still enforced when `codegraph` is invoked directly) while
+     * letting the test suite run on whatever Node the contributor happens to
+     * have installed. CI on Node 22/23 is unaffected — the guard doesn't fire
+     * there, so the variable is a no-op.
+     */
+    env: { CODEGRAPH_ALLOW_UNSAFE_NODE: '1' },
     coverage: {
       provider: 'v8',
       reporter: ['text', 'json', 'html'],