diff --git a/AGENTS.md b/AGENTS.md
index d85ad92..7a35838 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -74,8 +74,8 @@ when needed.
 |------|------|
 | `server.py` | MCP stdio server. Every `@mcp.tool` lives here. |
 | `search_lancedb.py` | Vector / hybrid / graph-expanded search; ranking. |
-| `build_ast_graph.py` | Tree-sitter → Kuzu graph builder (full rebuild). Owns `pass1`–`pass6` (`pass5` emits `HTTP_CALLS` / `ASYNC_CALLS` caller edges; `pass6_match_edges` resolves cross-service / intra-service / ambiguous / phantom / unresolved match outcomes — ontology 7). |
-| `kuzu_queries.py` | Read-only Cypher helpers used by the server. Includes `meta()` decoder for the Kuzu MAP-as-STRING JSON-blob columns. |
+| `build_ast_graph.py` | Tree-sitter → LadybugDB graph builder (full rebuild). Owns `pass1`–`pass6` (`pass5` emits `HTTP_CALLS` / `ASYNC_CALLS` caller edges; `pass6_match_edges` resolves cross-service / intra-service / ambiguous / phantom / unresolved match outcomes — ontology 7). |
+| `ladybug_queries.py` | Read-only Cypher helpers used by the server. Includes `meta()` decoder for the LadybugDB MAP-as-STRING JSON-blob columns. |
 | `ast_java.py` | Tree-sitter Java parsing, role/capability inference, `_string_value_atoms` helper (shared by route/client/producer extractors), `_collect_outgoing_calls` for caller-side detection. |
 | `graph_enrich.py` | `module` / `microservice` resolution, `BrownfieldOverrides` (route + role + capability + http client + async producer), meta-annotation walk, `resolve_routes_for_method` / `resolve_http_client_for_method` / `resolve_async_producer_for_method`. |
 | `java_ontology.py` | Source of truth for `VALID_ROLES`, `VALID_CAPABILITIES`, `VALID_CLIENT_KINDS`, `VALID_HTTP_CALL_STRATEGIES`, `VALID_ASYNC_CALL_STRATEGIES`, `VALID_HTTP_CALL_MATCHES`. |
@@ -90,7 +90,7 @@ when needed.
 
 ## Test layout
 
-- `tests/conftest.py` — session-scoped Kuzu graph fixture.
+- `tests/conftest.py` — session-scoped LadybugDB graph fixture.
 - `tests/bank-chat-system/` — deterministic Java corpus (fixture, not production model).
 - `tests/fixtures/call_graph_smoke/` — mini Maven tree calibrated against the call-graph resolver.
 - `tests/fixtures/brownfield_route_stubs/` — `@CodebaseRoute` / `@CodebaseRoutes` source stubs (PR-A3).
@@ -188,7 +188,7 @@ template):
   `VALID_ASYNC_CALL_STRATEGIES`, `VALID_HTTP_CALL_MATCHES`,
   `VALID_ROUTE_FRAMEWORKS`, `VALID_ROUTE_KINDS`, `VALID_PRODUCER_KINDS`,
   `VALID_RESOLVE_REASONS`, `VALID_UNRESOLVED_CALL_REASONS`.
-- Schema changes that affect the Lance index or Kuzu graph need a
+- Schema changes that affect the Lance index or LadybugDB graph need a
   matching update to the README "Re-index required" callout. Bump
   `ontology_version` when enrichment semantics change (currently **17**).
 - Brownfield is a first-class surface: any new auto-detection (route,
@@ -199,10 +199,10 @@ template):
   union when any brownfield layer fires on a method (single network packet
   → single edge). See `plans/completed/PLAN-TIER1B-COMPLETION.md` §
   "Caller-side composition divergence".
-- Kuzu's Python binder rejects `dict` for `MAP` columns. Store all
+- LadybugDB's Python binder rejects `dict` for `MAP` columns. Store all
   map-shaped graph_meta data (`routes_by_framework`, `routes_by_layer`,
   `http_calls_by_strategy`, `async_calls_by_strategy`, etc.) as `STRING`
-  JSON blobs and decode in `kuzu_queries.meta()`.
+  JSON blobs and decode in `ladybug_queries.meta()`.
 - `server.py` is a stdio MCP server: anything reachable from a tool
   handler must not write to **stdout** (that's the JSON-RPC transport).
   Diagnostics go to stderr.
@@ -216,10 +216,10 @@ template):
   support. `BrownfieldOverrides` already holds route, role, capability,
   http client, and async producer dicts — extend it in place.
 
-## Kuzu Cypher pitfalls
+## LadybugDB Cypher pitfalls
 
-When adding or editing Cypher run against Kuzu (for example in
-`kuzu_queries.py`, `mcp_v2.py`, or any `KuzuGraph._rows` caller):
+When adding or editing Cypher run against LadybugDB (for example in
+`ladybug_queries.py`, `mcp_v2.py`, or any `LadybugGraph._rows` caller):
 
 - **Do not filter relationship types with** `label(e) IN $list` **or**
   `label(e) IN ["A","B"]` **in** `WHERE`. On supported versions this can
@@ -252,7 +252,7 @@ When adding or editing Cypher run against Kuzu (for example in
   ```bash
   rm -rf /tmp/check && .venv/bin/python build_ast_graph.py \
     --source-root tests/bank-chat-system \
-    --kuzu-path /tmp/check/code_graph.kuzu --verbose
+    --ladybug-path /tmp/check/code_graph.lbug --verbose
   ```
 
 ## Commit and PR
@@ -289,7 +289,7 @@ When adding or editing Cypher run against Kuzu (for example in
 ## Cursor Cloud specific instructions
 
 This is a self-contained Python project — no external services
-(no Postgres, Kafka, Docker) are needed. All storage (Kuzu, LanceDB,
+(no Postgres, Kafka, Docker) are needed. All storage (LadybugDB, LanceDB,
 CocoIndex state) is embedded/file-based.
 
 ### Environment
@@ -317,12 +317,12 @@ first run. They are not required for normal development.
 
 ### Hello-world verification
 
-Build the Kuzu graph from the test fixture and inspect it:
+Build the LadybugDB graph from the test fixture and inspect it:
 
 ```bash
 rm -rf /tmp/check && .venv/bin/python build_ast_graph.py \
   --source-root tests/bank-chat-system \
-  --kuzu-path /tmp/check/code_graph.kuzu --verbose
+  --ladybug-path /tmp/check/code_graph.lbug --verbose
 .venv/bin/java-codebase-rag meta \
   --source-root tests/bank-chat-system --index-dir /tmp/check
 ```
diff --git a/README.md b/README.md
index 1f2b68a..00cb46c 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 A graph-native code intelligence layer for Java microservice estates, exposed to LLM agents via the **Model Context Protocol (MCP)**.
 
-The system extracts a deterministic property graph from Java source (tree-sitter), stores it in **Kuzu** (graph) alongside a **LanceDB** vector index (chunks), and exposes a deliberately small MCP surface — **five tools**: `search`, `find`, `describe`, `neighbors`, `resolve` — that collapse onto three primitive agent operations: **locate**, **inspect**, **walk**.
+The system extracts a deterministic property graph from Java source (tree-sitter), stores it in **LadybugDB** (graph) alongside a **LanceDB** vector index (chunks), and exposes a deliberately small MCP surface — **five tools**: `search`, `find`, `describe`, `neighbors`, `resolve` — that collapse onto three primitive agent operations: **locate**, **inspect**, **walk**.
 
 > **What this MCP is:** a **GPS for code navigation**, not a reasoning engine.
 > Agents use a simple loop:
@@ -21,9 +21,9 @@ For the design rationale, the GPS metaphor, and the full ontology, see [`docs/pa
 
 Generic code-search tools (grep, ctags, vector-only RAG) hit a ceiling on real Java microservice estates: they find files but lose the structure that makes a Spring/JAX-RS system navigable. This project is built around five choices that target that gap.
 
-- **Hybrid RAG + GraphRAG, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (Kuzu property graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `DECLARES_ROUTE`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
+- **Hybrid RAG + GraphRAG, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (LadybugDB property graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `EXPOSES`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
 
-- **A Java-tuned role model.** Symbols are labelled with stereotypes inferred from Spring and JAX-RS conventions — `CONTROLLER`, `SERVICE`, `REPOSITORY`, `CLIENT`, `PRODUCER`, `MAPPER`, `DTO`. Agents can ask "list controllers" or "who injects this repository" directly, instead of grep-ing for `@RestController` and hoping for the best. Roles drive both filtering (`find` with a `NodeFilter`) and ranking.
+- **A Java-tuned role model.** Symbols are labelled with stereotypes inferred from Spring and JAX-RS conventions — `CONTROLLER`, `SERVICE`, `REPOSITORY`, `COMPONENT`, `CONFIG`, `ENTITY`, `CLIENT`, `MAPPER`, `DTO`. Agents can ask "list controllers" or "who injects this repository" directly, instead of grep-ing for `@RestController` and hoping for the best. Roles drive both filtering (`find` with a `NodeFilter`) and ranking.
 
 - **Ranking specialized for Java codebases.** The composite ranker is aware of role, microservice, and FQN structure — not a generic BM25. A search for `"chat ingress"` surfaces controllers before utility classes; a search scoped to one microservice doesn't drown in matches from the other 19. Defaults are tuned on the bank-chat fixture and exposed in `docs/CONFIGURATION.md` for per-repo overrides.
 
@@ -71,7 +71,7 @@ All indexing lifecycle commands (`init`, `increment`, `reprocess`, `install`, `u
 
 If you prefer manual configuration, see [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) for the full CLI reference.
 
-> **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/Kuzu schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change.
+> **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/LadybugDB schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change.
 
 ---
 
@@ -84,7 +84,7 @@ This repo ships a small multi-module Spring fixture under [`tests/bank-chat-syst
 git clone https://github.com/HumanBean17/java-codebase-rag
 cd java-codebase-rag
 
-# 2. Build the index (Lance vectors + Kuzu graph). First run downloads the
+# 2. Build the index (Lance vectors + LadybugDB graph). First run downloads the
 #    embedding model (~90 MB) and takes ~30-60s on the fixture.
 java-codebase-rag init --source-root tests/bank-chat-system --index-dir /tmp/bank-chat-index
 
@@ -99,7 +99,7 @@ Smoke-test the index with two checks (`search_lancedb` ships with the package):
 JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
   python -m search_lancedb "chat ingress controller" --table java --limit 3
 
-# Vector + graph expansion — proves Kuzu is wired in
+# Vector + graph expansion — proves LadybugDB is wired in
 JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
   python -m search_lancedb "chat ingress controller" --table java --limit 3 \
     --graph-expand --expand-depth 2
@@ -199,8 +199,8 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 | Setup | `install` | Interactive setup wizard: config, MCP registration, skill/agent deployment, indexing. |
 | Setup | `update` | Refresh shipped artifacts (skill, agent, MCP entry) + incremental Lance/graph catch-up after pip upgrade. |
 | Lifecycle | `init` | First-time index. Refuses if artifacts already exist. |
-| Lifecycle | `increment` | CocoIndex catch-up + incremental Kuzu update. `--vectors-only` for Lance only. |
-| Lifecycle | `reprocess` | Full Lance + Kuzu rebuild. `--vectors-only` / `--graph-only` for a single phase. |
+| Lifecycle | `increment` | CocoIndex catch-up + incremental LadybugDB update. `--vectors-only` for Lance only. |
+| Lifecycle | `reprocess` | Full Lance + LadybugDB rebuild. `--vectors-only` / `--graph-only` for a single phase. |
 | Lifecycle | `erase` | Delete index artifacts. Requires `--yes` or TTY confirm. |
 | Introspection | `meta`, `tables`, `diagnose-ignore`, `unresolved-calls` | Health, table listing, ignore-layer diagnostics, receiver-failure call sites. |
 | Analysis | `analyze-pr` | Blast-radius / risk from a unified diff. |
@@ -235,7 +235,7 @@ python3 -m venv .venv
 
 The `cocoindex` package powers lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation do not invoke it directly.
 
-The default embedding model is `sentence-transformers/all-MiniLM-L6-v2` (downloaded on first `init`). Override via the `EMBEDDING_MODEL` env var — see [`docs/CONFIGURATION.md` §1](./docs/CONFIGURATION.md#1-environment-variables).
+The default embedding model is `sentence-transformers/all-MiniLM-L6-v2` (downloaded on first `init`). Override via the `SBERT_MODEL` env var — see [`docs/CONFIGURATION.md` §1](./docs/CONFIGURATION.md#1-environment-variables).
 
 ---
 
diff --git a/ast_java.py b/ast_java.py
index 5922641..f6bf063 100644
--- a/ast_java.py
+++ b/ast_java.py
@@ -1565,62 +1565,20 @@ def _parse_codebase_http_route_inner_annotation(
     return out
 
 
-def _codebase_route_inner_annotation_nodes(container_ann: Node, src: bytes) -> list[Node]:
-    found: list[Node] = []
-
-    def visit(n: Node) -> None:
-        if n.type == "annotation":
-            name_node = n.child_by_field_name("name")
-            n_simple = _txt(name_node, src).rsplit(".", 1)[-1] if name_node is not None else ""
-            if n_simple == "CodebaseHttpRoute":
-                found.append(n)
-        for c in n.children:
-            visit(c)
-
-    visit(container_ann)
-    return found
-
-
-def _codebase_async_route_inner_annotation_nodes(container_ann: Node, src: bytes) -> list[Node]:
-    found: list[Node] = []
-
-    def visit(n: Node) -> None:
-        if n.type == "annotation":
-            name_node = n.child_by_field_name("name")
-            n_simple = _txt(name_node, src).rsplit(".", 1)[-1] if name_node is not None else ""
-            if n_simple == "CodebaseAsyncRoute":
-                found.append(n)
-        for c in n.children:
-            visit(c)
-
-    visit(container_ann)
-    return found
-
+def _inner_annotation_nodes(container_ann: Node, src: bytes, target_simple: str) -> list[Node]:
+    """Collect nested ``@<target_simple>`` annotations anywhere under ``container_ann``.
 
-def _codebase_http_client_inner_annotation_nodes(container_ann: Node, src: bytes) -> list[Node]:
-    found: list[Node] = []
-
-    def visit(n: Node) -> None:
-        if n.type == "annotation":
-            name_node = n.child_by_field_name("name")
-            n_simple = _txt(name_node, src).rsplit(".", 1)[-1] if name_node is not None else ""
-            if n_simple == "CodebaseHttpClient":
-                found.append(n)
-        for c in n.children:
-            visit(c)
-
-    visit(container_ann)
-    return found
-
-
-def _codebase_producer_inner_annotation_nodes(container_ann: Node, src: bytes) -> list[Node]:
+    Shared by the four brownfield container walkers — ``CodebaseHttpRoute``,
+    ``CodebaseAsyncRoute``, ``CodebaseHttpClient``, ``CodebaseProducer`` — which
+    differ only by the target annotation simple name.
+    """
     found: list[Node] = []
 
     def visit(n: Node) -> None:
         if n.type == "annotation":
             name_node = n.child_by_field_name("name")
             n_simple = _txt(name_node, src).rsplit(".", 1)[-1] if name_node is not None else ""
-            if n_simple == "CodebaseProducer":
+            if n_simple == target_simple:
                 found.append(n)
         for c in n.children:
             visit(c)
@@ -1842,7 +1800,7 @@ def _outgoing_calls_from_codebase_http_client_producer_annotations(
                 ),
             )
         elif simple == "CodebaseHttpClients":
-            for inner in _codebase_http_client_inner_annotation_nodes(ann, src):
+            for inner in _inner_annotation_nodes(ann, src, "CodebaseHttpClient"):
                 out.append(
                     _parse_codebase_http_client_annotation(
                         inner,
@@ -1869,7 +1827,7 @@ def _outgoing_calls_from_codebase_http_client_producer_annotations(
                 ),
             )
         elif simple == "CodebaseProducers":
-            for inner in _codebase_producer_inner_annotation_nodes(ann, src):
+            for inner in _inner_annotation_nodes(ann, src, "CodebaseProducer"):
                 out.append(
                     _parse_codebase_producer_annotation(
                         inner,
@@ -2343,7 +2301,7 @@ def _collect_routes(
                 ),
             )
         elif simple == "CodebaseHttpRoutes":
-            for inner in _codebase_route_inner_annotation_nodes(node, src):
+            for inner in _inner_annotation_nodes(node, src, "CodebaseHttpRoute"):
                 routes.extend(
                     _parse_codebase_http_route_inner_annotation(
                         inner,
@@ -2359,7 +2317,7 @@ def _collect_routes(
         elif simple in ("CodebaseAsyncRoute", "CodebaseAsyncRoutes"):
             nodes = [node]
             if simple == "CodebaseAsyncRoutes":
-                nodes = list(_codebase_async_route_inner_annotation_nodes(node, src))
+                nodes = list(_inner_annotation_nodes(node, src, "CodebaseAsyncRoute"))
             for ann in nodes:
                 pairs, _ = _annotation_kv_nodes(ann, src)
                 topic_node = pairs.get("topic")
diff --git a/build_ast_graph.py b/build_ast_graph.py
index 6b2c377..403d790 100644
--- a/build_ast_graph.py
+++ b/build_ast_graph.py
@@ -2010,8 +2010,21 @@ def _producer_id(
     return f"p:{hashlib.sha1(key.encode()).hexdigest()[:16]}"
 
 
+# The four brownfield source layers — single source of truth. Consumed by the
+# client/producer source-layer classifiers, the *_from_brownfield_pct stats
+# (via brownfield_strategies), and the brownfield_only authoritativeness gate in
+# _is_brownfield_sourced. codebase_client/codebase_producer are caller-side
+# declaration strategies, not layers — they extend brownfield_strategies only.
+_BROWNFIELD_LAYERS = frozenset({
+    "layer_a_meta",
+    "layer_b_ann",
+    "layer_b_fqn",
+    "layer_c_source",
+})
+
+
 def _client_source_layer(strategy: str) -> str:
-    if strategy in {"layer_a_meta", "layer_b_ann", "layer_b_fqn", "layer_c_source"}:
+    if strategy in _BROWNFIELD_LAYERS:
         return strategy
     # Some caller extraction paths emit client kind as strategy; treat those
     # as builtin-source declarations instead of warning on every row.
@@ -2023,7 +2036,7 @@ def _client_source_layer(strategy: str) -> str:
 
 
 def _producer_source_layer(strategy: str) -> str:
-    if strategy in {"layer_a_meta", "layer_b_ann", "layer_b_fqn", "layer_c_source"}:
+    if strategy in _BROWNFIELD_LAYERS:
         return strategy
     if strategy in VALID_PRODUCER_KINDS:
         return "builtin"
@@ -2458,15 +2471,14 @@ def _phantom_async_route_id(call: OutgoingCallDecl) -> str:
         tables.producer_stats.producers_by_kind = defaultdict(int)
         for row in tables.producer_rows:
             tables.producer_stats.producers_by_kind[row.producer_kind] += 1
-        brownfield_strategies = frozenset(
-            (
-                "layer_b_ann",
-                "layer_a_meta",
-                "layer_c_source",
-                "layer_b_fqn",
-                "codebase_client",
-                "codebase_producer",
-            ),
+        # brownfield_strategies = the four brownfield layers plus the two
+        # caller-side declaration strategies (@CodebaseHttpClient /
+        # @CodebaseProducer). These extend _BROWNFIELD_LAYERS deliberately:
+        # the *_from_brownfield_pct stats count annotation-declared callers as
+        # brownfield-sourced even though they are not "layers" and so do not
+        # gate brownfield_only authoritativeness in _is_brownfield_sourced.
+        brownfield_strategies = _BROWNFIELD_LAYERS | frozenset(
+            {"codebase_client", "codebase_producer"},
         )
         if tables.call_edge_stats.http_calls_total:
             n_http = sum(
@@ -2568,14 +2580,6 @@ def _match_call_edge(
     return "cross_service", candidates
 
 
-_BROWNFIELD_LAYERS = frozenset({
-    "layer_c_source",
-    "layer_b_ann",
-    "layer_b_fqn",
-    "layer_a_meta",
-})
-
-
 def _is_brownfield_sourced(
     call_strategy: str,
     candidates: list[RouteRow],
diff --git a/docs/AGENT-GUIDE.md b/docs/AGENT-GUIDE.md
index ea6fc91..c469418 100644
--- a/docs/AGENT-GUIDE.md
+++ b/docs/AGENT-GUIDE.md
@@ -14,7 +14,7 @@ Copy the block between `<!-- BEGIN` and `<!-- END` into your project's `AGENTS.m
 
 **Indexed content:** Java production sources plus SQL and YAML (use `search` `table`: `java`, `sql`, `yaml`, or `all`).
 
-**Ontology: 16** — if results look structurally wrong or empty across tools, the index may be missing, stale, or built with a different `ontology_version`; you cannot re-index via MCP — ask the operator to rebuild.
+**Ontology: 17** — if results look structurally wrong or empty across tools, the index may be missing, stale, or built with a different `ontology_version`; you cannot re-index via MCP — ask the operator to rebuild.
 
 **Responses:** On success, `search`, `find`, `describe`, `neighbors`, and `resolve` may include two top-level fields: `hints_structured` (≤5 suggested next-tool calls) and `advisories` (≤5 pure informational strings). Each `hints_structured` entry has `tool`, `args`, `actionable`, `label`, and `reason`. `actionable=true` means you can call the tool directly with `args`; `actionable=false` means partial/advisory — fill missing values or use as guidance. `reason` explains why the hint was emitted. `advisories` carry context education (fuzzy strategy warnings, role collision explanations, etc.) with no tool call suggestion. For `search`/`find`, echoed `limit`/`offset`. Hints are advisory; ignore them when `success` is false.
 
@@ -245,7 +245,7 @@ Returns **edges** with `attrs` (`confidence`, `strategy`, `match`, … on cross-
 
 **Symbol kinds (`symbol_kind` / `symbol_kinds`):** `class`, `interface`, `enum`, `record`, `annotation`, `method`, `constructor`.
 
-**Route `framework` (closed set on stored routes):** `spring_mvc`, `webflux`, `kafka`, `rabbitmq`, `jms`, `stream`, `feign`.
+**Route `framework` (closed set on stored routes):** `spring_mvc`, `webflux`. (The `kafka` / `rabbitmq` / `jms` / `stream` values are route *kinds*, not frameworks; `feign` is a client kind.)
 
 **Client kinds:** `feign_method`, `rest_template`, `web_client`.
 
diff --git a/docs/CODEBASE_REQUIREMENTS.md b/docs/CODEBASE_REQUIREMENTS.md
index 8442ba2..6578828 100644
--- a/docs/CODEBASE_REQUIREMENTS.md
+++ b/docs/CODEBASE_REQUIREMENTS.md
@@ -1,7 +1,7 @@
 # Codebase requirements & MCP tuning guide
 
 This document explains how to get the best out of the `java-codebase-rag` MCP
-(LanceDB vector index + Kuzu AST graph + role-aware ranking) on a Java
+(LanceDB vector index + LadybugDB AST graph + role-aware ranking) on a Java
 codebase, and — if you cannot or will not change the codebase — exactly
 **which files in this bundle to edit** so the MCP adapts to your project.
 
@@ -33,7 +33,7 @@ inside the MCP.
     (only `*.java`).
 - **Source under `src/main/java/...`.** Test sources under
   `src/test/java/` and `src/test/resources/` are intentionally excluded
-  from both the LanceDB vector index and the Kuzu graph build.
+  from both the LanceDB vector index and the LadybugDB graph build.
   - See: `java_index_v1_common.py::COMMON_EXCLUDED_PATH_PATTERNS`.
 - **Two location concepts: `module` and `microservice`.** The MCP
   infers both by walking up from each `.java` file until it finds a
@@ -107,8 +107,8 @@ method-level local, distinct names) is fine.
 
 The checklist in `propose/completed/CALL-GRAPH-PROPOSE.md` §7.1 is covered across `tests/test_ast_java_calls.py`
 (parse-only), `tests/test_call_graph_smoke_roundtrip.py` plus `tests/fixtures/call_graph_smoke/`
-(mini Maven tree for scope / overload / wildcard / method-ref graph checks), the session Kuzu
-fixture (`tests/conftest.py`), `tests/test_ast_graph_build.py`, `tests/test_kuzu_queries.py`,
+(mini Maven tree for scope / overload / wildcard / method-ref graph checks), the session LadybugDB
+fixture (`tests/conftest.py`), `tests/test_ast_graph_build.py`, `tests/test_ladybug_queries.py`,
 `tests/test_call_graph_receiver_resolution.py`, and MCP smoke tests — not as one numbered test
 per bullet.
 
@@ -193,16 +193,16 @@ require a graph built with `ontology_version` **14** or newer — confirm with
 See **Brownfield overrides** in `README.md` for the full schema, usage
 examples, and execution order.
 
-**Layer A index sources:** Kuzu and Lance both use
+**Layer A index sources:** LadybugDB and Lance both use
 `graph_enrich.collect_annotation_meta_chain` (one disk walk: sorted
 `iter_java_source_files` + the same `COMMON_EXCLUDED_PATH_PATTERNS` as
 `build_ast_graph.py`, stderr on parse errors, first-seen FQN wins on duplicate
 simple names after sorted iteration). The graph’s `pass1` walk is still used to
 **build** `GraphTables`, but default Layer A is **not** taken from that graph in
-isolation. See `README.md` (Brownfield — Kuzu vs Lance, Limitations, full
+isolation. See `README.md` (Brownfield — LadybugDB vs Lance, Limitations, full
 rebuild).
 
-**Graph `Symbol` row scope:** in Kuzu, only **type** `Symbol` rows (class,
+**Graph `Symbol` row scope:** in LadybugDB, only **type** `Symbol` rows (class,
 interface, record, etc.) are populated with brownfield `role` /
 `capabilities`. **Method** and **constructor** `Symbol` nodes keep
 `role=OTHER` and `capabilities=[]` (the model is type-centric; per-method
@@ -320,9 +320,9 @@ The CocoIndex flow indexes only:
   parser handles syntax errors robustly (partial AST is still indexed),
   but very large files with complex nesting may produce noisy chunk
   boundaries.
-- **Kuzu graph sidecar location.** The graph defaults to
-  `<JAVA_CODEBASE_RAG_INDEX_DIR>/code_graph.kuzu` (see `docs/CONFIGURATION.md` §1 for the
-  default index dir). If Lance tables and Kuzu are split across directories
+- **LadybugDB graph sidecar location.** The graph defaults to
+  `<JAVA_CODEBASE_RAG_INDEX_DIR>/code_graph.lbug` (see `docs/CONFIGURATION.md` §1 for the
+  default index dir). If Lance tables and LadybugDB are split across directories
   by mistake, the MCP can silently operate in vector-only mode (no graph-backed
   `find` / `describe` / `neighbors`). Verify `java-codebase-rag meta` reports the
   paths you expect.
@@ -430,7 +430,7 @@ If you need a different *mechanism* (e.g. method-level Guice `@Provides`),
 you'll need to extend `build_ast_graph.py::_emit_injects` — that is
 where field/constructor/setter scanning happens.
 
-Rebuild the Kuzu graph after editing.
+Rebuild the LadybugDB graph after editing.
 
 ### B.4 Change module / microservice inference / pruning
 
@@ -562,10 +562,10 @@ This is a larger change; rough map:
 2. `build_ast_graph.py` — add a new `_emit_xxx` pass and a new
    `EdgeRow` subclass; wire it in `pass2_edges`; add a schema string
    like `_SCHEMA_KAFKA = "CREATE REL TABLE KAFKA_LISTEN(...)"`.
-3. `kuzu_queries.py` — add helper queries that traverse the new
+3. `ladybug_queries.py` — add helper queries that traverse the new
    relation.
 4. `mcp_v2.py` / `server.py` — wire the new relation into `neighbors` (and
-   document the new label in README + agent guide), or add a focused Kuzu
+   document the new label in README + agent guide), or add a focused LadybugDB
    helper called from those handlers.
 
 See `propose/completed/CALL-GRAPH-PROPOSE.md` for the shipped shape of
@@ -587,7 +587,7 @@ the same conventions.
 | Recently re-indexed but search is stale | Restart the MCP server; re-run `java-codebase-rag reprocess` |
 | `context_before` / `context_after` empty | Set `JAVA_CODEBASE_RAG_DEBUG_CONTEXT=1` (see `docs/CONFIGURATION.md` §3) |
 | Graph has lots of phantom nodes | Expected for external libs; inspect via `java-codebase-rag meta` — only worry if domain types are phantoms (means resolution is failing; check imports). Use `find` / `neighbors` and filter or interpret `resolved` flags on symbols as needed. |
-| Graph tools unavailable / silent failures | Kuzu DB missing or wrong path — verify `<index-dir>/code_graph.kuzu` exists and `JAVA_CODEBASE_RAG_INDEX_DIR` matches (see `docs/CONFIGURATION.md` §3). |
+| Graph tools unavailable / silent failures | LadybugDB DB missing or wrong path — verify `<index-dir>/code_graph.lbug` exists and `JAVA_CODEBASE_RAG_INDEX_DIR` matches (see `docs/CONFIGURATION.md` §3). |
 
 ---
 
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 9820b1f..8d44046 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -4,7 +4,7 @@ Everything that didn't fit in the README's 5-minute walkthrough lives here: envi
 
 For the architecture rationale (the GPS metaphor, three-layer design, future work), see [`paper/paper.pdf`](./paper/paper.pdf). For agent-facing tool shapes and recovery moves, see [`AGENT-GUIDE.md`](./AGENT-GUIDE.md). For the CLI playbook, see [`JAVA-CODEBASE-RAG-CLI.md`](./JAVA-CODEBASE-RAG-CLI.md).
 
-> **Stability disclaimer.** MCP tool contracts, env vars, Lance/Kuzu schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change (see [Re-index required when ontology changes](#re-index-required-when-ontology-changes)).
+> **Stability disclaimer.** MCP tool contracts, env vars, Lance/LadybugDB schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change (see [Re-index required when ontology changes](#re-index-required-when-ontology-changes)).
 
 ---
 
@@ -12,7 +12,7 @@ For the architecture rationale (the GPS metaphor, three-layer design, future wor
 
 1. [Environment variables](#1-environment-variables)
 2. [Project YAML reference (`.java-codebase-rag.yml`)](#2-project-yaml-reference-java-codebase-ragyml)
-3. [Graph layer — Kuzu schema, edges, capabilities, ranking](#3-graph-layer)
+3. [Graph layer — LadybugDB schema, edges, capabilities, ranking](#3-graph-layer)
 4. [Brownfield overrides — config + in-source annotations](#4-brownfield-overrides)
 5. [Ignore patterns](#5-ignore-patterns)
 
@@ -43,7 +43,7 @@ This walk-up behavior means you no longer need to set environment variables or p
 
 | Variable | Purpose |
 |---|---|
-| `JAVA_CODEBASE_RAG_INDEX_DIR` | Local filesystem **directory** for Lance tables, the Kuzu file `code_graph.kuzu`, and cocoindex state (`cocoindex.db`). Not a `lancedb://` or cloud URI — use a path. Default: `./.java-codebase-rag/` under the resolved Java tree root. |
+| `JAVA_CODEBASE_RAG_INDEX_DIR` | Local filesystem **directory** for Lance tables, the LadybugDB file `code_graph.lbug`, and cocoindex state (`cocoindex.db`). Not a `lancedb://` or cloud URI — use a path. Default: `./.java-codebase-rag/` under the resolved Java tree root. |
 | `SBERT_MODEL` | Hub id or local directory; must match indexer. Overridable via `.java-codebase-rag.yml` `embedding.model` and `--embedding-model`. |
 | `SBERT_DEVICE` | Optional: `cpu`, `cuda`, `mps`. Overridable via YAML `embedding.device` and `--embedding-device`. |
 | `JAVA_CODEBASE_RAG_DEBUG_CONTEXT` | When truthy, verbose stderr logging for chunk context expansion (diagnostics only). |
@@ -56,7 +56,7 @@ Only the names in the table above (plus `JAVA_CODEBASE_RAG_SOURCE_ROOT` for MCP
 
 **Paths and conventions** (for scripts and operators):
 
-- **`JAVA_CODEBASE_RAG_INDEX_DIR`** — filesystem path to the index directory (not a URI). Lance opens this directory; Kuzu is always `<index-dir>/code_graph.kuzu`; cocoindex keeps **`cocoindex.db`** next to them.
+- **`JAVA_CODEBASE_RAG_INDEX_DIR`** — filesystem path to the index directory (not a URI). Lance opens this directory; LadybugDB is always `<index-dir>/code_graph.lbug`; cocoindex keeps **`cocoindex.db`** next to them.
 - **Java tree root** — CLI: `--source-root` (else cwd). MCP stdio: set `JAVA_CODEBASE_RAG_SOURCE_ROOT` when the Java repo root differs from the server process cwd.
 - **`microservice_roots`** — configure only under **`microservice_roots:`** in `.java-codebase-rag.yml` (or `.yaml`).
 - **Chunk context diagnostics / heavy tests** — `JAVA_CODEBASE_RAG_DEBUG_CONTEXT`, `JAVA_CODEBASE_RAG_RUN_HEAVY` (see the table above).
@@ -85,7 +85,7 @@ A single file at the project root (the directory you pass as `--source-root`, or
 # - Default: the directory containing this config file (for walk-up discovery).
 # source_root: ../java-project
 
-# Index directory: where Lance tables, code_graph.kuzu, and cocoindex.db live.
+# Index directory: where Lance tables, code_graph.lbug, and cocoindex.db live.
 # - Tilde (`~`) is expanded; `$VAR` is NOT (use absolute paths or `~`).
 # - Relative paths resolve against the config file's parent directory (same
 #   base as source_root), not cwd. The bare default ./.java-codebase-rag
@@ -235,7 +235,7 @@ async_producer_overrides:
 
 - **The config file may live anywhere under your project, including a subdirectory of the Java tree.** Both the CLI (`init` / `increment` / `reprocess`) and the MCP server walk up from cwd to find `.java-codebase-rag.yml`, then resolve `source_root` and `index_dir` relative to the config file's directory. So a config living in `my-context/` next to `source_root: ../` and `index_dir: ../.java-codebase-rag` resolves identically for the CLI and the MCP server. Keep the file under your project (not `$HOME`); set `JAVA_CODEBASE_RAG_SOURCE_ROOT` (MCP) or `--source-root` (CLI) only to override the discovered location.
 - **Don't commit secrets** into this YAML — it sits next to your source tree and is read by every operator who clones it.
-- **Rebuild after editing brownfield overrides.** Run a full `java-codebase-rag reprocess` (no flags) so Lance and Kuzu stay coherent, or use `--graph-only` / `--vectors-only` when you know only one store needs invalidation. Editing `embedding.model` requires a vector rebuild (`reprocess` or `--vectors-only`).
+- **Rebuild after editing brownfield overrides.** Run a full `java-codebase-rag reprocess` (no flags) so Lance and LadybugDB stay coherent, or use `--graph-only` / `--vectors-only` when you know only one store needs invalidation. Editing `embedding.model` requires a vector rebuild (`reprocess` or `--vectors-only`).
 - **Diagnose what's loaded.** `java-codebase-rag meta` prints the resolved config and each value's `*_source` (`cli` / `env` / `yaml` / `default`) — see `embedding_model_source`, `embedding_device_source`, `index_dir_source`.
 - **`embedding.model` and `$` in directory names.** `expandvars` treats `$VAR` / `${VAR}` like the shell. HuggingFace hub ids never contain `$`. If a local filesystem path contains a literal `$` in a directory name, use an absolute path that avoids `$`-expansion patterns, or expect `expandvars` to interpret `$` sequences.
 
@@ -245,7 +245,7 @@ Deeper documentation for the brownfield blocks (`role_overrides`, `route_overrid
 
 ## 3. Graph layer
 
-A deterministic property graph derived from tree-sitter Java parsing lives next to the LanceDB tables under the index directory (default `${JAVA_CODEBASE_RAG_INDEX_DIR:-./.java-codebase-rag}/code_graph.kuzu`). Current ontology version: **15** (see [`EDGE-NAVIGATION.md`](./EDGE-NAVIGATION.md) for MCP-traversable edge shapes).
+A deterministic property graph derived from tree-sitter Java parsing lives next to the LanceDB tables under the index directory (default `${JAVA_CODEBASE_RAG_INDEX_DIR:-./.java-codebase-rag}/code_graph.lbug`). Current ontology version: **17** (see [`EDGE-NAVIGATION.md`](./EDGE-NAVIGATION.md) for MCP-traversable edge shapes).
 
 ### Node kinds
 
@@ -309,7 +309,7 @@ Resolution order for `microservice`:
 
 ### Re-index required when ontology changes
 
-Current ontology version is **15**. Any index built before this version must be rebuilt via `cocoindex update ... --full-reprocess -f` or a full `java-codebase-rag reprocess` (no selective flags) so vectors and graph stay aligned. Until re-indexed, the server defensively JSON-decodes string-form list columns so nothing explodes, but filters like `array_contains` will not work.
+Current ontology version is **17**. Any index built before this version must be rebuilt via `cocoindex update ... --full-reprocess -f` or a full `java-codebase-rag reprocess` (no selective flags) so vectors and graph stay aligned. Until re-indexed, the server defensively JSON-decodes string-form list columns so nothing explodes, but filters like `array_contains` will not work.
 
 Ontology **15** (CALLS-NOISE) adds `CALLS.callee_declaring_role`, `GraphMeta.pass3_unresolved_phantom_receiver` / `pass3_unresolved_chained`, and **supertype-walk dedup** at build time. PR-2 adds `edge_filter` on `neighbors`. **PR-3 (breaking):** receiver-failure sites (`chained_receiver`, unresolved-receiver `phantom`) are no longer `CALLS` rows — they live on `UnresolvedCallSite` + `UNRESOLVED_AT`. Default `neighbors(..., ['CALLS'])` returns fewer rows; use `include_unresolved=True` for a source-ordered interleaved transcript (`row_kind`), `describe(method_id).unresolved_call_sites` (capped), or `java-codebase-rag unresolved-calls list|stats`. Known-receiver-external JDK rows stay on `CALLS` with `resolved=false`.
 
@@ -602,15 +602,15 @@ When a brownfield caller override specifies only part of what built-in detection
 - **Incremental indexing and annotation sources.** The indexer may only reprocess changed files. If you edit an `@interface` declaration (e.g. remove a `@Service` meta-annotation from a wrapper), every class that used it may need re-enrichment; the pipeline does not track that dependency automatically. **Run a full `java-codebase-rag reprocess` after changing any `@interface` used as a custom stereotype.**
 - **`Symbol` rows scope.** `role` and `capabilities` on the graph are computed for **type** nodes (classes, interfaces, etc.). Method and constructor `Symbol` rows use defaults `role=OTHER` and `capabilities=[]`.
 
-### 4.6 Lance / Kuzu consistency
+### 4.6 Lance / LadybugDB consistency
 
-Both the Kuzu graph writer and Lance chunk enrichment call **one** function — `graph_enrich.collect_annotation_meta_chain` — which scans the project with sorted `*.java` paths, the same layered ignore rules as `build_ast_graph` / `path_filtering.iter_java_source_files`, parse-error warnings on stderr, and deterministic *first wins* for duplicate annotation simple names. Kuzu and Lance **should** agree; they can still diverge if the same file is handled differently elsewhere in the pipeline (e.g. parse edge cases). If graph tools and `search` disagree on a type, run a full reindex and compare.
+Both the LadybugDB graph writer and Lance chunk enrichment call **one** function — `graph_enrich.collect_annotation_meta_chain` — which scans the project with sorted `*.java` paths, the same layered ignore rules as `build_ast_graph` / `path_filtering.iter_java_source_files`, parse-error warnings on stderr, and deterministic *first wins* for duplicate annotation simple names. LadybugDB and Lance **should** agree; they can still diverge if the same file is handled differently elsewhere in the pipeline (e.g. parse edge cases). If graph tools and `search` disagree on a type, run a full reindex and compare.
 
 ---
 
 ## 5. Ignore patterns
 
-Java file discovery for the Kuzu graph, annotation meta-chain collection, and the CocoIndex Lance pipeline share the same layered ignore model (`path_filtering.LayeredIgnore`):
+Java file discovery for the LadybugDB graph, annotation meta-chain collection, and the CocoIndex Lance pipeline share the same layered ignore model (`path_filtering.LayeredIgnore`):
 
 1. **Builtin default** — hardcoded patterns applied to every project.
 2. **Project root** — optional `<project>/.java-codebase-rag/ignore` (gitignore syntax, including negation with `!`).
diff --git a/docs/JAVA-CODEBASE-RAG-CLI.md b/docs/JAVA-CODEBASE-RAG-CLI.md
index 06a6dd3..4e655f3 100644
--- a/docs/JAVA-CODEBASE-RAG-CLI.md
+++ b/docs/JAVA-CODEBASE-RAG-CLI.md
@@ -112,7 +112,7 @@ All five lifecycle commands that build the index (`init`, `increment`, `reproces
 
 - **Vectors** — the `cocoindex update` Lance catch-up / full reprocess.
 - **Optimize** — the serialized Lance table compaction that runs after a successful vectors phase.
-- **Graph** — the `build_ast_graph.py` Kuzu/LadybugDB build (full or incremental).
+- **Graph** — the `build_ast_graph.py` LadybugDB/LadybugDB build (full or incremental).
 
 **Determinate vs indeterminate per command:**
 
@@ -141,7 +141,7 @@ All five lifecycle commands that build the index (`init`, `increment`, `reproces
 
 | Variable | Role |
 | -------- | ---- |
-| `JAVA_CODEBASE_RAG_INDEX_DIR` | Root directory for Lance tables, the Kuzu file `code_graph.kuzu`, and default cocoindex state. Default: `./.java-codebase-rag/` under the resolved Java tree root. Overridden by `--index-dir` or YAML `index_dir:`. |
+| `JAVA_CODEBASE_RAG_INDEX_DIR` | Root directory for Lance tables, the LadybugDB file `code_graph.lbug`, and default cocoindex state. Default: `./.java-codebase-rag/` under the resolved Java tree root. Overridden by `--index-dir` or YAML `index_dir:`. |
 | `SBERT_MODEL` / `SBERT_DEVICE` | Embedding model and device; must match the index. Overridden by `--embedding-model` / `--embedding-device` or YAML `embedding.model` / `embedding.device`. |
 | `JAVA_CODEBASE_RAG_DEBUG_CONTEXT` | Verbose stderr logging for context expansion (diagnostic). |
 | `JAVA_CODEBASE_RAG_RUN_HEAVY` | Test-only gate for slow end-to-end indexer tests (`pytest`). |
@@ -160,7 +160,7 @@ Every subcommand accepts (all optional unless noted):
 | `--index-dir DIR` | Index directory (default: `./.java-codebase-rag` under the resolved source root, or `JAVA_CODEBASE_RAG_INDEX_DIR`). |
 | `--embedding-model` / `--embedding-device` | Override embedding resolution for subprocesses that honor env. |
 
-Kuzu always resolves to `<index-dir>/code_graph.kuzu`.
+LadybugDB always resolves to `<index-dir>/code_graph.lbug`.
 
 Relative paths for `diagnose-ignore <path>` are resolved against the MCP/CLI project root helper (`--source-root` when given, else cwd semantics described in `--help`).
 
@@ -176,7 +176,7 @@ Relative paths for `diagnose-ignore <path>` are resolved against the MCP/CLI pro
 
 ### `init`
 
-Creates a **new** index (cocoindex catch-up from empty + full `build_ast_graph.py`). **Refuses** if `code_graph.kuzu` or `code_index_*` Lance tables already exist under the resolved index dir (exit **2**).
+Creates a **new** index (cocoindex catch-up from empty + full `build_ast_graph.py`). **Refuses** if `code_graph.lbug` or `code_index_*` Lance tables already exist under the resolved index dir (exit **2**).
 
 ```bash
 java-codebase-rag init --source-root /path/to/java/repo --index-dir /path/to/.java-codebase-rag --quiet
@@ -184,7 +184,7 @@ java-codebase-rag init --source-root /path/to/java/repo --index-dir /path/to/.ja
 
 ### `increment`
 
-Runs cocoindex **catch-up** and **incremental Kuzu graph update**. Only changed files and their single-hop dependents are re-parsed and re-written to the graph. Passes 5–6 (client/producer extraction and cross-service matching) run globally. Falls back to full `reprocess` if:
+Runs cocoindex **catch-up** and **incremental LadybugDB graph update**. Only changed files and their single-hop dependents are re-parsed and re-written to the graph. Passes 5–6 (client/producer extraction and cross-service matching) run globally. Falls back to full `reprocess` if:
 - No previous graph exists (first run)
 - Graph schema is outdated (missing `source_file` on edges)
 - Previous incremental run crashed (crash marker detected)
@@ -201,7 +201,7 @@ java-codebase-rag increment --source-root /path/to/java/repo --index-dir /path/t
 
 ### `reprocess`
 
-**Default (no extra flags):** full **Lance** reprocess (cocoindex `--full-reprocess`) then full **Kuzu** rebuild via `build_ast_graph.py`, in that order. This remains the recommended **coherence** operation when both stores might be out of date.
+**Default (no extra flags):** full **Lance** reprocess (cocoindex `--full-reprocess`) then full **LadybugDB** rebuild via `build_ast_graph.py`, in that order. This remains the recommended **coherence** operation when both stores might be out of date.
 
 **Selective flags (mutually exclusive):**
 
@@ -240,7 +240,7 @@ java-codebase-rag reprocess --source-root /path/to/java/repo --index-dir /path/t
 
 ### `erase`
 
-Deletes cocoindex state, the Kuzu directory, and Lance tables under the index dir. Requires **`--yes`** or interactive confirmation on a TTY. Non-TTY without `--yes` exits **2**.
+Deletes cocoindex state, the LadybugDB directory, and Lance tables under the index dir. Requires **`--yes`** or interactive confirmation on a TTY. Non-TTY without `--yes` exits **2**.
 
 ```bash
 java-codebase-rag erase --source-root /path/to/java/repo --index-dir /path/to/.java-codebase-rag --yes
@@ -254,7 +254,7 @@ java-codebase-rag erase --source-root /path/to/java/repo --index-dir /path/to/.j
 
 ### `meta`
 
-Graph metadata, ontology version, counts, `edge_counts`, plus resolved embedding fields and provenance (`embedding_model_source`, `embedding_device_source`, `index_dir`, `kuzu_path`, …).
+Graph metadata, ontology version, counts, `edge_counts`, plus resolved embedding fields and provenance (`embedding_model_source`, `embedding_device_source`, `index_dir`, `ladybug_path`, …).
 
 ```bash
 java-codebase-rag meta --source-root /path/to/java/repo --index-dir /path/to/.java-codebase-rag
@@ -289,7 +289,7 @@ java-codebase-rag unresolved-calls list --method-id sym:... --limit 100 --source
 
 ## Analysis: `analyze-pr`
 
-Maps a **unified diff** to changed symbols, blast radius, routes touched, and risk band. Requires a **built Kuzu graph** at `<index-dir>/code_graph.kuzu`.
+Maps a **unified diff** to changed symbols, blast radius, routes touched, and risk band. Requires a **built LadybugDB graph** at `<index-dir>/code_graph.lbug`.
 
 Provide exactly one of:
 
@@ -334,10 +334,10 @@ java-codebase-rag analyze-pr --diff-file /tmp/pr.diff --source-root /path/to/jav
 
 ## Graph-only escape hatch
 
-Prefer **`java-codebase-rag reprocess --graph-only`** when you only need Kuzu rebuilt from the current Lance snapshot. To run the graph builder **without** going through the CLI (advanced / scripting):
+Prefer **`java-codebase-rag reprocess --graph-only`** when you only need LadybugDB rebuilt from the current Lance snapshot. To run the graph builder **without** going through the CLI (advanced / scripting):
 
 ```bash
-.venv/bin/python build_ast_graph.py --source-root /path/to/java/repo --kuzu-path /path/to/.java-codebase-rag/code_graph.kuzu --verbose
+.venv/bin/python build_ast_graph.py --source-root /path/to/java/repo --ladybug-path /path/to/.java-codebase-rag/code_graph.lbug --verbose
 ```
 
 ## See also
diff --git a/docs/MANUAL-VERIFICATION-CHECKLIST.md b/docs/MANUAL-VERIFICATION-CHECKLIST.md
index 3d0695f..b218f25 100644
--- a/docs/MANUAL-VERIFICATION-CHECKLIST.md
+++ b/docs/MANUAL-VERIFICATION-CHECKLIST.md
@@ -47,7 +47,7 @@ rm -rf "$JAVA_CODEBASE_RAG_INDEX_DIR"
 mkdir -p "$JAVA_CODEBASE_RAG_INDEX_DIR"
 .venv/bin/python build_ast_graph.py \
   --source-root "$JAVA_CODEBASE_RAG_SOURCE_ROOT" \
-  --kuzu-path "$JAVA_CODEBASE_RAG_INDEX_DIR/code_graph.kuzu" --verbose 2>&1 | tee /tmp/verify_build.log
+  --ladybug-path "$JAVA_CODEBASE_RAG_INDEX_DIR/code_graph.lbug" --verbose 2>&1 | tee /tmp/verify_build.log
 
 # 2. Read the summary lines (last ~10 lines of the log)
 tail -12 /tmp/verify_build.log
@@ -515,11 +515,11 @@ cd /path/to/java-codebase-rag
 rm -rf /tmp/calib_index
 .venv/bin/python build_ast_graph.py \
   --source-root tests/bank-chat-system \
-  --kuzu-path /tmp/calib_index/code_graph.kuzu \
+  --ladybug-path /tmp/calib_index/code_graph.lbug \
   --verbose
 java-codebase-rag meta --source-root tests/bank-chat-system --index-dir /tmp/calib_index
 ```
 
-`build_ast_graph.py` still takes `--kuzu-path` (the Kuzu file). Point it at `<index-dir>/code_graph.kuzu` so it matches the layout `java-codebase-rag meta --index-dir` expects under that directory.
+`build_ast_graph.py` still takes `--ladybug-path` (the LadybugDB file). Point it at `<index-dir>/code_graph.lbug` so it matches the layout `java-codebase-rag meta --index-dir` expects under that directory.
 
 Current snapshot: `tests/bank-chat-system`, `chore/docs-sync @ 1fa1b28`, ontology **13**.
diff --git a/docs/PRODUCT-VISION.md b/docs/PRODUCT-VISION.md
index 1976ea0..515da44 100644
--- a/docs/PRODUCT-VISION.md
+++ b/docs/PRODUCT-VISION.md
@@ -4,7 +4,7 @@
 
 Vector-only RAG, as used in most CocoIndex-based setups, excels at semantic similarity but fails systematically on multi-hop architectural reasoning — `controller → service → repository` chains, interface-driven dependency injection, and inheritance trees. AST-derived GraphRAG (DKB) is the correct addition, not a replacement: it layers a deterministic structural knowledge graph on top of the existing vector index, enabling bidirectional traversal at query time to supply context that similarity search structurally cannot find. A 2026 benchmark on Java codebases (Shopizer, ThingsBoard, OpenMRS Core) confirmed DKB achieves **15/15 (100%)** answer correctness on architecture-tracing queries, compared to 6/15 for pure vector RAG, at only ~2× the query cost and with indexing times under 15 seconds.[^1][^2][^3][^4]
 
-**This repository’s reference implementation** pairs **LanceDB** (embeddings, optional full-text + vector hybrid via RRF) with a **Kuzu** sidecar graph (default `code_graph.kuzu` colocated with the LanceDB data directory). Search and the MCP server do not require a running CocoIndex process—only the built artifacts and Python dependencies (see the bundle `README`).
+**This repository’s reference implementation** pairs **LanceDB** (embeddings, optional full-text + vector hybrid via RRF) with a **LadybugDB** sidecar graph (default `code_graph.lbug` colocated with the LanceDB data directory). Search and the MCP server do not require a running CocoIndex process—only the built artifacts and Python dependencies (see the bundle `README`).
 
 ***
 
@@ -36,7 +36,7 @@ The two layers are orthogonal and complementary. A **hybrid retrieval** system t
 
 ### 2.1 Architecture overview
 
-The integration adds a **parallel graph index** alongside the **vector index**. Both are built from the same source files; the graph is derived deterministically from AST parsing, not from embeddings.[^2] In this bundle, that split is **LanceDB + Kuzu**.
+The integration adds a **parallel graph index** alongside the **vector index**. Both are built from the same source files; the graph is derived deterministically from AST parsing, not from embeddings.[^2] In this bundle, that split is **LanceDB + LadybugDB**.
 
 ```
 Java Microservices
@@ -51,7 +51,7 @@ Java Microservices
                 ├── Two-pass ontology extractor
                 │     ├── Pass 1: class/interface/enum nodes, …
                 │     └── Pass 2: injects/extends/implements (Phase 1 edges)
-                └── Kuzu (code_graph.kuzu) ──────────► Graph retriever (Cypher)
+                └── LadybugDB (code_graph.lbug) ──────────► Graph retriever (Cypher)
                                                               │
                                                     BFS + bidirectional closure
                                                     (MCP: expand, impact, …)
@@ -77,33 +77,33 @@ The DKB (Deterministic Knowledge Base) approach, as validated in the 2026 benchm
 - `EXTENDS` — class inheritance
 - `IMPLEMENTS` — interface implementation
 - `INJECTS` — field-type DI (Spring `@Autowired`, constructor injection)
-- `CALLS` — method-to-method call sites (requires call resolution) — *planned* (not yet in the Kuzu schema)
+- `CALLS` — method-to-method call sites (requires call resolution) — *shipped*
 - `HTTP_CALLS` — cross-service REST calls (Feign clients, `RestTemplate`)[^11] — *shipped*
 - `ASYNC_CALLS` — Kafka, messaging patterns[^11] — *shipped*
 
-**Shipped in the Kuzu sidecar:** `EXTENDS`, `IMPLEMENTS`, `INJECTS`, `CALLS`, `HTTP_CALLS`, `ASYNC_CALLS`.
+**Shipped in the LadybugDB sidecar:** `EXTENDS`, `IMPLEMENTS`, `INJECTS`, `CALLS`, `HTTP_CALLS`, `ASYNC_CALLS`.
 
 The two-pass extraction strategy matters: Pass 1 builds all node records (so every class/interface in the codebase is known); Pass 2 resolves edge targets using the completed node registry, eliminating forward-reference gaps.[^2]
 
 **Why deterministic extraction beats LLM-based graph construction:**
 In the benchmark, LLM-KB skipped 377 out of 1210 files (31.2% miss rate), reducing chunk coverage to 64.1% and node coverage to 72.7% of DKB's graph. Indexing time for LLM-KB was 200 seconds vs. 2.8 seconds for DKB on the same codebase, and cost was ~20× higher. For a production codebase you maintain incrementally, stochastic extraction failures create silent blind spots.[^1][^2]
 
-### 2.3 How this bundle wires CocoIndex, LanceDB, and Kuzu
+### 2.3 How this bundle wires CocoIndex, LanceDB, and LadybugDB
 
 1. **Vector / chunk index (LanceDB):** a CocoIndex flow (e.g. `java_index_flow_lancedb.py` in the repo) walks sources, applies Tree-sitter-based chunking, embeds, and writes **LanceDB** tables. At query time the MCP / CLI loads embeddings from the resolved index directory (`JAVA_CODEBASE_RAG_INDEX_DIR`, default `.java-codebase-rag/` under the Java tree) and runs vector search, optional **FTS + vector RRF** (`auto_hybrid`), and filters on enriched columns (`role`, `microservice`, `module`, …).[^6][^7]
 
-2. **Graph index (Kuzu):** `build_ast_graph.py` runs **in parallel** (same repo root, same `.java` sources). It is **not** required for read-only search if the Kuzu file already exists. Output defaults to `code_graph.kuzu` next to the LanceDB directory. Query-time access is read-only Cypher from Python (`kuzu`).
+2. **Graph index (LadybugDB):** `build_ast_graph.py` runs **in parallel** (same repo root, same `.java` sources). It is **not** required for read-only search if the LadybugDB file already exists. Output defaults to `code_graph.lbug` next to the LanceDB directory. Query-time access is read-only Cypher from Python (`ladybug`).
 
 3. **Cross-service `HTTP_CALLS` / `ASYNC_CALLS` (future):** Feign / `RestTemplate` / Kafka static patterns belong in a later pass once method- and service-level edges are modeled; see §8.[^14][^15][^11]
 
-4. **Incremental updates:** CocoIndex can incrementally update LanceDB chunks. The Kuzu build in Phase 1 is a **full rebuild** when the graph is regenerated; incremental graph diffing is a future improvement (bundle `README`).
+4. **Incremental updates:** CocoIndex can incrementally update LanceDB chunks. The LadybugDB build in Phase 1 is a **full rebuild** when the graph is regenerated; incremental graph diffing is a future improvement (bundle `README`).
 
-### 2.4 Why Kuzu (and what LanceDB covers)
+### 2.4 Why LadybugDB (and what LanceDB covers)
 
 - **LanceDB** holds dense retrieval: embeddings, optional FTS, and chunk metadata (package, FQN, role, capabilities, `microservice` / `module`, …) produced with the same Tree-sitter chunks the agent reads.
-- **Kuzu** is an **embedded** property graph with **Cypher**, no separate server process, and a small on-disk footprint beside the resolved Lance index directory (default `.java-codebase-rag/` under the Java tree). It matches the “structural retriever + parallel to vectors” model without running Neo4j or another cluster alongside the MCP process.
+- **LadybugDB** is an **embedded** property graph with **Cypher**, no separate server process, and a small on-disk footprint beside the resolved Lance index directory (default `.java-codebase-rag/` under the Java tree). It matches the “structural retriever + parallel to vectors” model without running Neo4j or another cluster alongside the MCP process.
 
-Research stacks often cite pgvector or other vector stores; functionally, **LanceDB plays that role here**, paired with Kuzu for graph traversals.[^12]
+Research stacks often cite pgvector or other vector stores; functionally, **LanceDB plays that role here**, paired with LadybugDB for graph traversals.[^12]
 
 ***
 
@@ -348,7 +348,7 @@ For complex multi-hop questions, add a self-correction loop:[^10][^23]
 ## 7. Implementation stack in this repository
 
 - **Vector store:** **LanceDB** (tables produced by the Java/SQL/Yaml CocoIndex flows the repo uses for indexing).
-- **Graph store:** **Kuzu** (`code_graph.kuzu`), populated by `build_ast_graph.py` using **tree_sitter_java** in the DKB style (two-pass ontology, phantom nodes for unresolved targets).[^2]
+- **Graph store:** **LadybugDB** (`code_graph.lbug`), populated by `build_ast_graph.py` using **tree_sitter_java** in the DKB style (two-pass ontology, phantom nodes for unresolved targets).[^2]
 - **Query / agent surface:** `server.py` (MCP) + `search_lancedb.py` (CLI); RRF in hybrid search and in `graph_expand`.[^8][^10]
 - For broader **literature and alternatives** (other parsers, third-party graph DBs, and hybrid-retrieval studies), see the DKB paper and the references list below.[^1][^16][^11]
 
@@ -364,7 +364,7 @@ The DKB benchmark paper has a public GitHub repository (`graph-based-rag-ast-vs-
 
 - Parse all 5 microservices (or a monorepo) with `tree_sitter_java`
 - Extract Class/Interface/Method nodes + `EXTENDS` / `IMPLEMENTS` / `INJECTS` edges
-- Store in **Kuzu** (`code_graph.kuzu`); run **LanceDB** + hybrid / `graph_expand` over the same project
+- Store in **LadybugDB** (`code_graph.lbug`); run **LanceDB** + hybrid / `graph_expand` over the same project
 - Verify graph completeness (node count, edge count per service)
 - *Status:* implemented via `build_ast_graph.py` + `java_index_flow_lancedb.py` + MCP; graph rebuild is currently full, not incremental.
 
@@ -391,7 +391,7 @@ The DKB benchmark paper has a public GitHub repository (`graph-based-rag-ast-vs-
 
 ## Key Takeaways
 
-- **GraphRAG is an additive layer:** keep **LanceDB** for dense retrieval; add a deterministic AST graph in **Kuzu** alongside it. The two are complementary retrieval primitives, not competitors.[^5][^1]
+- **GraphRAG is an additive layer:** keep **LanceDB** for dense retrieval; add a deterministic AST graph in **LadybugDB** alongside it. The two are complementary retrieval primitives, not competitors.[^5][^1]
 - **Use AST parsing (DKB), not LLM-based graph extraction:** LLM-KB skips ~30% of files and costs 20–45× more. Tree-sitter completes in seconds and is fully deterministic.[^2]
 - **Your 5-service topology is a first-class graph asset (roadmap):** model inter-service Feign/Kafka dependencies as `HTTP_CALLS` and `ASYNC_CALLS` edges when Phase 2 lands.[^21][^11]
 - **Bidirectional traversal is non-negotiable:** successor-only graphs miss upstream consumers (controllers that inject services); the interface-consumer expansion fixes Spring DI wiring gaps.[^1][^2]
diff --git a/graph_enrich.py b/graph_enrich.py
index 02119b2..97e54e3 100644
--- a/graph_enrich.py
+++ b/graph_enrich.py
@@ -23,7 +23,7 @@
 from dataclasses import dataclass, field, replace
 from functools import lru_cache
 from pathlib import Path
-from typing import Any
+from typing import Any, TypeVar
 from ast_java import (
     AnnotationRef,
     JavaFileAst,
@@ -820,7 +820,15 @@ def _route_path_atom(raw_value: str, value_kind: str | None) -> tuple[str, str,
     return "", "constant_ref", 0.7, False
 
 
-def _route_hint_lookup(ann: AnnotationRef, hints: dict[str, RouteHint]) -> RouteHint | None:
+_HINT = TypeVar("_HINT")
+
+
+def _hint_lookup(ann: AnnotationRef, hints: dict[str, _HINT]) -> _HINT | None:
+    """Resolve a brownfield hint by qualified name, then simple name, then suffix.
+
+    Shared by route / http-client / async-producer hint resolution; the three
+    former copies differed only in the hint value type.
+    """
     q = ann.qualified.strip()
     if q in hints:
         return hints[q]
@@ -1118,7 +1126,7 @@ def resolve_routes_for_method(
 
     # ----- Step 2: Layer B — annotation route hints -----
     for _is_m, ann in combined_anns:
-        hint = _route_hint_lookup(ann, overrides.annotation_to_route_hint)
+        hint = _hint_lookup(ann, overrides.annotation_to_route_hint)
         if hint is None:
             continue
         working.append(
@@ -1172,36 +1180,6 @@ def resolve_routes_for_method(
     return working
 
 
-def _client_hint_lookup(
-    ann: AnnotationRef,
-    hints: dict[str, HttpClientHint],
-) -> HttpClientHint | None:
-    q = ann.qualified.strip()
-    if q in hints:
-        return hints[q]
-    if ann.name in hints:
-        return hints[ann.name]
-    for k, h in sorted(hints.items(), key=lambda kv: kv[0]):
-        if k.endswith("." + ann.name):
-            return h
-    return None
-
-
-def _async_hint_lookup(
-    ann: AnnotationRef,
-    hints: dict[str, AsyncProducerHint],
-) -> AsyncProducerHint | None:
-    q = ann.qualified.strip()
-    if q in hints:
-        return hints[q]
-    if ann.name in hints:
-        return hints[ann.name]
-    for k, h in sorted(hints.items(), key=lambda kv: kv[0]):
-        if k.endswith("." + ann.name):
-            return h
-    return None
-
-
 def _call_from_http_hint(
     *,
     hint: HttpClientHint,
@@ -1296,7 +1274,7 @@ def resolve_http_client_for_method(
     anchor = builtin_http[0] if builtin_http else (layer_c_src[0] if layer_c_src else None)
 
     for _is_m, ann in combined_anns:
-        hint = _client_hint_lookup(ann, overrides.annotation_to_http_client_hint)
+        hint = _hint_lookup(ann, overrides.annotation_to_http_client_hint)
         if hint is None:
             continue
         brownfield_calls.append(
@@ -1388,7 +1366,7 @@ def resolve_async_producer_for_method(
     anchor = builtin_async[0] if builtin_async else (layer_c_src[0] if layer_c_src else None)
 
     for _is_m, ann in combined_anns:
-        hint = _async_hint_lookup(ann, overrides.annotation_to_async_producer_hint)
+        hint = _hint_lookup(ann, overrides.annotation_to_async_producer_hint)
         if hint is None:
             continue
         brownfield_calls.append(
diff --git a/java_codebase_rag/cli.py b/java_codebase_rag/cli.py
index 58a44b2..817cd08 100644
--- a/java_codebase_rag/cli.py
+++ b/java_codebase_rag/cli.py
@@ -251,7 +251,7 @@ def _startup_hints(cfg: ResolvedOperatorConfig) -> None:
 
 def _add_index_embedding_flags(p: argparse.ArgumentParser) -> None:
     p.add_argument("--source-root", type=str, default=None, help="Java repository root (default: cwd)")
-    p.add_argument("--index-dir", type=str, default=None, help="Index directory (Lance + Kuzu + cocoindex state)")
+    p.add_argument("--index-dir", type=str, default=None, help="Index directory (Lance + LadybugDB + cocoindex state)")
     p.add_argument("--embedding-model", type=str, default=None, help="Override SBERT_MODEL / YAML embedding.model")
     p.add_argument("--embedding-device", type=str, default=None, help="Override SBERT_DEVICE / YAML embedding.device")
 
@@ -536,7 +536,7 @@ def work(progress: "PipelineProgress | None") -> int:
             _emit_reprocess_outcome(payload, selective_tty_mode="graph" if ok else None)
             return _reprocess_exit_code(payload)
 
-        import server  # lazy: pulls sentence_transformers/torch/lancedb/kuzu
+        import server  # lazy: pulls sentence_transformers/torch/lancedb/ladybug
 
         result = asyncio.run(
             server.run_refresh_pipeline(
@@ -715,7 +715,7 @@ def _cmd_unresolved_calls_list(args: argparse.Namespace) -> int:
     from ladybug_queries import LadybugGraph  # lazy
 
     if not LadybugGraph.exists():
-        _emit({"success": False, "message": "Kuzu graph not found"})
+        _emit({"success": False, "message": "LadybugDB graph not found"})
         return 1
     graph = LadybugGraph.get()
     rows = graph.list_unresolved_call_sites(
@@ -736,7 +736,7 @@ def _cmd_unresolved_calls_stats(args: argparse.Namespace) -> int:
     from ladybug_queries import LadybugGraph  # lazy
 
     if not LadybugGraph.exists():
-        _emit({"success": False, "message": "Kuzu graph not found"})
+        _emit({"success": False, "message": "LadybugDB graph not found"})
         return 1
     graph = LadybugGraph.get()
     buckets = graph.stats_unresolved_call_sites(by=args.by)
@@ -761,7 +761,7 @@ def _cmd_analyze_pr(args: argparse.Namespace) -> int:
     from ladybug_queries import LadybugGraph  # lazy
 
     if not LadybugGraph.exists():
-        _emit({"success": False, "message": "Kuzu graph not found"})
+        _emit({"success": False, "message": "LadybugDB graph not found"})
         return 1
     graph = LadybugGraph.get()
     report = pr_analysis.analyze_pr_pipeline(graph, diff_text)
@@ -801,7 +801,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="Create a fresh index from a Java repository.",
         description=(
             "First-time index creation. Refuses if the resolved index directory "
-            "already contains a Kuzu graph or Lance tables. Exit 2 on refusal."
+            "already contains a LadybugDB graph or Lance tables. Exit 2 on refusal."
         ),
     )
     _add_index_embedding_flags(init)
@@ -870,7 +870,7 @@ def build_parser() -> argparse.ArgumentParser:
     increment = subparsers.add_parser(
         "increment",
         help="Pick up changes since the last index update.",
-        description="Runs cocoindex catch-up and incremental Kuzu graph update. Use --vectors-only to skip graph update.",
+        description="Runs cocoindex catch-up and incremental LadybugDB graph update. Use --vectors-only to skip graph update.",
     )
     _add_index_embedding_flags(increment)
     _add_verbosity_flags(increment)
@@ -883,9 +883,9 @@ def build_parser() -> argparse.ArgumentParser:
 
     reprocess = subparsers.add_parser(
         "reprocess",
-        help="Rebuild vectors and/or Kuzu (default: both full phases).",
+        help="Rebuild vectors and/or LadybugDB (default: both full phases).",
         description=(
-            "Default: full Lance reprocess (cocoindex --full-reprocess) then full Kuzu graph rebuild. "
+            "Default: full Lance reprocess (cocoindex --full-reprocess) then full LadybugDB graph rebuild. "
             "Use --vectors-only or --graph-only to run a single phase (mutually exclusive)."
         ),
     )
@@ -907,7 +907,7 @@ def build_parser() -> argparse.ArgumentParser:
     erase = subparsers.add_parser(
         "erase",
         help="Delete the index from disk.",
-        description="Runs cocoindex drop, removes Kuzu, and drops Lance tables. Requires --yes or TTY confirmation.",
+        description="Runs cocoindex drop, removes LadybugDB, and drops Lance tables. Requires --yes or TTY confirmation.",
     )
     _add_index_embedding_flags(erase)
     erase.add_argument("--yes", action="store_true", help="Confirm destructive deletion (required in CI)")
diff --git a/java_codebase_rag/install_data/agents/explorer-rag-enhanced.md b/java_codebase_rag/install_data/agents/explorer-rag-enhanced.md
index 5ee33f7..8f8b2b8 100644
--- a/java_codebase_rag/install_data/agents/explorer-rag-enhanced.md
+++ b/java_codebase_rag/install_data/agents/explorer-rag-enhanced.md
@@ -151,15 +151,15 @@ Simple types in parentheses; generics erased. No spaces after commas. No-arg: `(
 
 ### Shared NodeFilter
 
-For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`.
+For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`; invalid enum values (e.g. wrong case) are rejected earlier at the schema layer with the valid set listed.
 
 | Keys | Applies to |
 | ---- | ---------- |
 | `microservice`, `module` | All kinds |
 | `role`, `exclude_roles`, `annotation`, `capability`, `fqn_prefix`, `symbol_kind`, `symbol_kinds` | **symbol** |
 | `http_method`, `path_prefix`, `framework` | **route** |
-| `client_kind`, `target_service`, `target_path_prefix`, `http_method` | **client** |
-| `producer_kind`, `topic_prefix` | **producer** |
+| `source_layer`, `client_kind`, `target_service`, `target_path_prefix`, `http_method` | **client** |
+| `source_layer`, `producer_kind`, `topic_prefix` | **producer** |
 
 No wildcards in prefix fields — use `search(query=…)` for fuzzy text.
 
diff --git a/java_codebase_rag/install_data/skills/explore-codebase/SKILL.md b/java_codebase_rag/install_data/skills/explore-codebase/SKILL.md
index 267a14b..5562d52 100644
--- a/java_codebase_rag/install_data/skills/explore-codebase/SKILL.md
+++ b/java_codebase_rag/install_data/skills/explore-codebase/SKILL.md
@@ -125,15 +125,15 @@ Use these strings **verbatim** in `neighbors(..., edge_types=[...])`.
 
 ### NodeFilter (`find`, `search.filter`, `neighbors.filter`)
 
-For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`.
+For `find`, `filter` is required — `{}` means no predicates. **Strict frame:** unknown keys or inapplicable populated fields → `success=false`; invalid enum values (e.g. wrong case) are rejected earlier at the schema layer with the valid set listed.
 
 | Applicable to | Keys |
 | ------------- | ---- |
 | All kinds | `microservice`, `module` |
 | **symbol** only | `role`, `exclude_roles`, `annotation`, `capability`, `fqn_prefix`, `symbol_kind`, `symbol_kinds` |
 | **route** only | `http_method`, `path_prefix`, `framework` |
-| **client** only | `client_kind`, `target_service`, `target_path_prefix`, `http_method` |
-| **producer** only | `producer_kind`, `topic_prefix` |
+| **client** only | `source_layer`, `client_kind`, `target_service`, `target_path_prefix`, `http_method` |
+| **producer** only | `source_layer`, `producer_kind`, `topic_prefix` |
 
 No wildcards in prefix fields — use `search(query=…)` for ranked text.
 
@@ -166,8 +166,8 @@ Exclude `DTO`, `OTHER`, `MAPPER` with `exclude_roles` when tracing business logi
 
 **Symbol kinds:** `class`, `interface`, `enum`, `record`, `annotation`, `method`, `constructor`.
 
-**Route frameworks:** `spring_mvc`, `webflux`, `kafka`, `rabbitmq`, `jms`, `stream`, `codebase_async_route`, …
-**Client kinds:** `feign_method`, `rest_template`, `web_client`. **Producer kinds:** `kafka_send`, `stream_bridge_send`.
+**Route frameworks:** `spring_mvc`, `webflux`. (Route *kinds* are `http_endpoint`, `http_consumer`, `kafka_topic`, `rabbit_queue`, `jms_destination`, `stream_binding`.)
+**Client kinds:** `feign_method`, `rest_template`, `web_client`. **Producer kinds:** `kafka_send`, `stream_bridge_send`. **Source layers (client/producer):** `builtin`, `layer_a_meta`, `layer_b_ann`, `layer_b_fqn`, `layer_c_source`.
 **Match types:** `cross_service`, `intra_service`, `ambiguous`, `phantom`, `unresolved`.
 
 ---
diff --git a/java_index_flow_lancedb.py b/java_index_flow_lancedb.py
index 10425a2..0f6edac 100644
--- a/java_index_flow_lancedb.py
+++ b/java_index_flow_lancedb.py
@@ -198,12 +198,12 @@ def _excluded(rel_posix: str) -> bool:
                 continue
             # Java: **/*.java
             if fn.endswith(".java"):
-                if not ignore.is_ignored(full)[0]:
+                if not ignore.is_ignored(full):
                     total += 1
                 continue
             # SQL: **/src/main/resources/db/migration/*.sql
             if fn.endswith(".sql") and "/db/migration/" in rel:
-                if not ignore.is_ignored(full)[0]:
+                if not ignore.is_ignored(full):
                     total += 1
                 continue
             # YAML: **/src/main/resources/application*.yml / .yaml
@@ -214,7 +214,7 @@ def _excluded(rel_posix: str) -> bool:
             # total below the actual done count. The ``rel``-based
             # ``"/src/main/resources/"`` gate stays (full path component).
             if fn.endswith((".yml", ".yaml")) and fn.startswith("application") and "/src/main/resources/" in rel:
-                if not ignore.is_ignored(full)[0]:
+                if not ignore.is_ignored(full):
                     total += 1
     return total
 
@@ -313,7 +313,7 @@ async def process_java_file(
 ) -> None:
     embedder = coco.use_context(EMBEDDER)
     project_root = coco.use_context(PROJECT_ROOT)
-    if LayeredIgnore(project_root).is_ignored((project_root / file.file_path.path).resolve())[0]:
+    if LayeredIgnore(project_root).is_ignored((project_root / file.file_path.path).resolve()):
         return
     try:
         content = await file.read_text()
@@ -379,7 +379,7 @@ async def process_sql_file(
 ) -> None:
     embedder = coco.use_context(EMBEDDER)
     project_root = coco.use_context(PROJECT_ROOT)
-    if LayeredIgnore(project_root).is_ignored((project_root / file.file_path.path).resolve())[0]:
+    if LayeredIgnore(project_root).is_ignored((project_root / file.file_path.path).resolve()):
         return
     try:
         content = await file.read_text()
@@ -425,7 +425,7 @@ async def process_yaml_file(
 ) -> None:
     embedder = coco.use_context(EMBEDDER)
     project_root = coco.use_context(PROJECT_ROOT)
-    if LayeredIgnore(project_root).is_ignored((project_root / file.file_path.path).resolve())[0]:
+    if LayeredIgnore(project_root).is_ignored((project_root / file.file_path.path).resolve()):
         return
     try:
         content = await file.read_text()
diff --git a/ladybug_queries.py b/ladybug_queries.py
index 77ae32b..66204b0 100644
--- a/ladybug_queries.py
+++ b/ladybug_queries.py
@@ -1161,8 +1161,11 @@ def _method_ids_for_call_graph_needle(self, needle: str, *, limit: int) -> list[
         )
         return [str(r["id"]) for r in rows2 if r.get("id")]
 
-    def find_callers(
-        self, needle: str, *,
+    def _walk_calls(
+        self,
+        needle: str,
+        *,
+        side: str,
         depth: int = 1,
         limit: int = 100,
         min_confidence: float = 0.0,
@@ -1170,6 +1173,17 @@ def find_callers(
         module: str | None = None,
         microservice: str | None = None,
     ) -> list[CallEdge]:
+        """BFS the CALLS graph outward from ``needle`` along one relationship end.
+
+        ``side="callers"`` treats the needle as the callee: the frontier matches
+        the ``callee`` end and discovered/expanded/external-filtered nodes are the
+        ``caller`` (src) end. ``side="callees"`` is the mirror. The two public
+        methods differ only in that orientation, so the BFS body is shared here.
+        """
+        if side == "callers":
+            scope_alias, frontier_end, discovered = "caller", "callee", "src"
+        else:
+            scope_alias, frontier_end, discovered = "callee", "caller", "dst"
         frontier = self._method_ids_for_call_graph_needle(needle, limit=max(limit, 50))
         if not frontier:
             return []
@@ -1182,8 +1196,8 @@ def find_callers(
                 "frontier": list(frontier),
                 "minc": float(min_confidence),
             }
-            sc = _scope_filters("caller", module=module, microservice=microservice, params=params)
-            wh_parts = ["callee.id IN $frontier", "c.confidence >= $minc"]
+            sc = _scope_filters(scope_alias, module=module, microservice=microservice, params=params)
+            wh_parts = [f"{frontier_end}.id IN $frontier", "c.confidence >= $minc"]
             wh_parts.extend(sc)
             wh = " AND ".join(wh_parts)
             q = (
@@ -1197,16 +1211,19 @@ def find_callers(
             next_frontier: list[str] = []
             for row in self._rows(q, params):
                 ce = _row_to_call_edge(row)
-                # Filter only discovered callers (src). Needle may be external
-                # (e.g. java.util.List#add) while still listing internal callers.
-                if exclude_external and _is_external_fqn(ce.src.fqn):
+                # The needle itself may be external (e.g. java.util.List#add);
+                # filter only the discovered end so internal callers/callees
+                # that touch it are still surfaced.
+                disc_fqn = ce.src.fqn if discovered == "src" else ce.dst.fqn
+                disc_id = ce.src.id if discovered == "src" else ce.dst.id
+                if exclude_external and _is_external_fqn(disc_fqn):
                     continue
                 key = (ce.src.id, ce.dst.id, ce.call_site_line, ce.call_site_byte)
                 if key in seen:
                     continue
                 seen.add(key)
                 out.append(ce)
-                next_frontier.append(ce.src.id)
+                next_frontier.append(disc_id)
                 if len(out) >= limit:
                     return out
             frontier = list(dict.fromkeys(next_frontier))
@@ -1214,6 +1231,21 @@ def find_callers(
                 break
         return out
 
+    def find_callers(
+        self, needle: str, *,
+        depth: int = 1,
+        limit: int = 100,
+        min_confidence: float = 0.0,
+        exclude_external: bool = True,
+        module: str | None = None,
+        microservice: str | None = None,
+    ) -> list[CallEdge]:
+        return self._walk_calls(
+            needle, side="callers", depth=depth, limit=limit,
+            min_confidence=min_confidence, exclude_external=exclude_external,
+            module=module, microservice=microservice,
+        )
+
     def find_callees(
         self, needle: str, *,
         depth: int = 1,
@@ -1223,49 +1255,11 @@ def find_callees(
         module: str | None = None,
         microservice: str | None = None,
     ) -> list[CallEdge]:
-        frontier = self._method_ids_for_call_graph_needle(needle, limit=max(limit, 50))
-        if not frontier:
-            return []
-        caller_proj = ", ".join(f"caller.{c} AS caller_{c}" for c in _SYM_COLS)
-        callee_proj = ", ".join(f"callee.{c} AS callee_{c}" for c in _SYM_COLS)
-        out: list[CallEdge] = []
-        seen: set[tuple[str, str, int, int]] = set()
-        for _ in range(max(1, int(depth))):
-            params: dict[str, Any] = {
-                "frontier": list(frontier),
-                "minc": float(min_confidence),
-            }
-            sc = _scope_filters("callee", module=module, microservice=microservice, params=params)
-            wh_parts = ["caller.id IN $frontier", "c.confidence >= $minc"]
-            wh_parts.extend(sc)
-            wh = " AND ".join(wh_parts)
-            q = (
-                f"MATCH (caller:Symbol)-[c:CALLS]->(callee:Symbol) WHERE {wh} "
-                f"RETURN {caller_proj}, {callee_proj}, "
-                f"c.call_site_line AS call_site_line, c.call_site_byte AS call_site_byte, "
-                f"c.arg_count AS arg_count, c.confidence AS confidence, c.strategy AS strategy, "
-                f"c.source AS source, c.resolved AS resolved "
-                f"LIMIT {int(limit) * 8}"
-            )
-            next_frontier: list[str] = []
-            for row in self._rows(q, params):
-                ce = _row_to_call_edge(row)
-                # Filter only discovered callees (dst). Needle may be external while
-                # still listing non-external outbound calls when any exist.
-                if exclude_external and _is_external_fqn(ce.dst.fqn):
-                    continue
-                key = (ce.src.id, ce.dst.id, ce.call_site_line, ce.call_site_byte)
-                if key in seen:
-                    continue
-                seen.add(key)
-                out.append(ce)
-                next_frontier.append(ce.dst.id)
-                if len(out) >= limit:
-                    return out
-            frontier = list(dict.fromkeys(next_frontier))
-            if not frontier:
-                break
-        return out
+        return self._walk_calls(
+            needle, side="callees", depth=depth, limit=limit,
+            min_confidence=min_confidence, exclude_external=exclude_external,
+            module=module, microservice=microservice,
+        )
 
     def expand_methods(
         self, fqns: list[str], *, depth: int = 1,
diff --git a/mcp_v2.py b/mcp_v2.py
index 5b5087b..86807ed 100644
--- a/mcp_v2.py
+++ b/mcp_v2.py
@@ -817,7 +817,7 @@ def _merge_overrides_edge_summary(
     """Reconcile `OVERRIDES` with `override_axis_rollup_for` without clobbering stored `in`.
 
     Rollup rows reuse the ``OVERRIDES`` key for dispatch-up counts only (``in`` is always
-    zero there). Stored ``[:OVERRIDES]`` edges contribute real ``in``/``out`` from Kuzu;
+    zero there). Stored ``[:OVERRIDES]`` edges contribute real ``in``/``out`` from LadybugDB;
     merge per direction with ``max`` so inbound override edges stay visible.
     """
     roll = _incident_counts(summary_after_rollups.get("OVERRIDES"))
@@ -1095,9 +1095,9 @@ def describe_v2(
         has_id = bool(id and str(id).strip())
         has_fqn = bool(fqn and str(fqn).strip())
         if not has_id and not has_fqn:
-            return DescribeOutput(success=False, message="id or fqn required", hints=[])
+            return DescribeOutput(success=False, message="id or fqn required")
         if has_id and str(id).strip().startswith("ucs:"):
-            return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE, hints=[])
+            return DescribeOutput(success=False, message=_DESCRIBE_UCS_ID_MESSAGE)
         hint_message: str | None = None
         node_id: str
         if has_id:
@@ -1109,7 +1109,7 @@ def describe_v2(
                 {"fqn": fqn_val},
             )
             if not rows:
-                return DescribeOutput(success=False, message=f"No Symbol found for fqn='{fqn_val}'", hints=[])
+                return DescribeOutput(success=False, message=f"No Symbol found for fqn='{fqn_val}'")
             node_id = str(rows[0]["id"] or "")
             if len(rows) > 1:
                 hint_message = (
@@ -1784,7 +1784,7 @@ def neighbors_v2(
             )
         except ValueError as exc:
             _log_fail_loud("edge_filter")
-            return NeighborsOutput(success=False, message=str(exc), hints=[], requested_edge_types=[])
+            return NeighborsOutput(success=False, message=str(exc), requested_edge_types=[])
         if include_unresolved and ef is not None:
             return NeighborsOutput(
                 success=False,
@@ -1792,21 +1792,18 @@ def neighbors_v2(
                     "include_unresolved=True is incompatible with edge_filter; "
                     "UnresolvedCallSite rows have no edge attributes to filter on"
                 ),
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         if include_unresolved and requested_edge_types != ["CALLS"]:
             return NeighborsOutput(
                 success=False,
                 message="include_unresolved requires edge_types=['CALLS']",
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         if include_unresolved and direction != "out":
             return NeighborsOutput(
                 success=False,
                 message='include_unresolved requires direction="out"',
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         if ef and (err := _edgefilter_applicability_error(requested_edge_types, ef)):
@@ -1814,17 +1811,15 @@ def neighbors_v2(
             return NeighborsOutput(
                 success=False,
                 message=err,
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         if nf and (err := _validate_no_wildcards(nf)):
             _log_fail_loud("wildcard")
-            return NeighborsOutput(success=False, message=err, hints=[], requested_edge_types=[])
+            return NeighborsOutput(success=False, message=err, requested_edge_types=[])
         if composed_keys and direction != "out":
             return NeighborsOutput(
                 success=False,
                 message='Composed edge types require direction="out"',
-                hints=[],
                 requested_edge_types=requested_edge_types,
             )
         use_calls_path = flat_labels == ["CALLS"] and not composed_keys
@@ -1849,7 +1844,6 @@ def neighbors_v2(
                     return NeighborsOutput(
                         success=False,
                         message=axis_msg,
-                        hints=[],
                         requested_edge_types=requested_edge_types,
                     )
                 origin_row = _load_node_record(g, origin_id, "symbol")
@@ -1865,7 +1859,6 @@ def neighbors_v2(
                     return NeighborsOutput(
                         success=False,
                         message=err,
-                        hints=[],
                         requested_edge_types=requested_edge_types,
                     )
             if use_calls_path:
@@ -1891,7 +1884,6 @@ def neighbors_v2(
                     return NeighborsOutput(
                         success=False,
                         message=str(exc),
-                        hints=[],
                         requested_edge_types=requested_edge_types,
                     )
                 if (
@@ -1904,7 +1896,7 @@ def neighbors_v2(
                 results.extend(origin_edges)
                 continue
             if flat_labels:
-                # Kuzu 0.11.x can drop `label(e) IN $list` in WHERE; use OR of scalar equalities.
+                # Some Cypher binders can drop `label(e) IN $list` in WHERE; use OR of scalar equalities.
                 label_params = [f"l{i}" for i in range(len(flat_labels))]
                 label_predicate = "(" + " OR ".join(f"label(e) = ${name}" for name in label_params) + ")"
                 q_params = {"id": origin_id, **dict(zip(label_params, flat_labels, strict=True))}
@@ -1941,7 +1933,7 @@ def neighbors_v2(
                     if nf and (err := _nodefilter_applicability_error(other_kind, nf)):
                         _log_fail_loud("applicability")
                         return NeighborsOutput(
-                            success=False, message=err, hints=[], requested_edge_types=[]
+                            success=False, message=err, requested_edge_types=[]
                         )
                     if not _node_matches_filter(other_kind, other_rec, nf):
                         continue
@@ -1968,7 +1960,7 @@ def neighbors_v2(
                     if nf and (err := _nodefilter_applicability_error(other_kind, nf)):
                         _log_fail_loud("applicability")
                         return NeighborsOutput(
-                            success=False, message=err, hints=[], requested_edge_types=[]
+                            success=False, message=err, requested_edge_types=[]
                         )
                     if not _node_matches_filter(other_kind, other_rec, nf):
                         continue
diff --git a/path_filtering.py b/path_filtering.py
index 6275f17..4ff36db 100644
--- a/path_filtering.py
+++ b/path_filtering.py
@@ -342,24 +342,22 @@ def _mega(self, rel_project: str) -> tuple[list[str], GitIgnoreSpec, list[tuple[
         )
         return mega, GitIgnoreSpec.from_lines(mega), meta
 
-    def is_ignored(self, path: Path) -> tuple[bool, IgnoreLayer | None]:
-        """Return whether ``path`` is ignored and which layer last matched."""
+    def is_ignored(self, path: Path) -> bool:
+        """Return whether ``path`` is ignored by any configured layer.
+
+        Boolean-only fast path for the per-file index walk. It deliberately does
+        not compute *which* layer/source last matched: that attribution is
+        O(rules²) via :func:`_winning_row` (one ``GitIgnoreSpec`` rebuild per
+        rule prefix) and is only needed for ``diagnose-ignore``, so it lives in
+        :meth:`diagnose_dict` and is never paid on the hot path.
+        """
         rel = self._rel_project(path)
         if rel is None:
-            return False, None
-        mega, spec, meta = self._mega(rel)
+            return False
+        mega, spec, _ = self._mega(rel)
         if not mega:
-            return False, None
-        ignored = spec.match_file(rel)
-        if not ignored:
-            return False, None
-        src, fp, ln, _pat = _winning_row(rel, mega, meta)
-        return True, IgnoreLayer(
-            root=self.project_root,
-            spec=spec,
-            source=src,
-            ignore_file=fp,
-        )
+            return False
+        return spec.match_file(rel)
 
     def diagnose(self, path: Path) -> str:
         """Human-readable, multi-line explanation of the ignore decision."""
@@ -466,7 +464,6 @@ def iter_java_source_files(
             if not fn.endswith(".java"):
                 continue
             p = Path(dirpath) / fn
-            ign, _ = ignore_ctx.is_ignored(p)
-            if ign:
+            if ignore_ctx.is_ignored(p):
                 continue
             yield p
diff --git a/plans/active/AGENT-PROMPTS-INDEX-OUTPUT-REWORK.md b/plans/completed/AGENT-PROMPTS-INDEX-OUTPUT-REWORK.md
similarity index 100%
rename from plans/active/AGENT-PROMPTS-INDEX-OUTPUT-REWORK.md
rename to plans/completed/AGENT-PROMPTS-INDEX-OUTPUT-REWORK.md
diff --git a/plans/active/PLAN-INDEX-OUTPUT-REWORK.md b/plans/completed/PLAN-INDEX-OUTPUT-REWORK.md
similarity index 100%
rename from plans/active/PLAN-INDEX-OUTPUT-REWORK.md
rename to plans/completed/PLAN-INDEX-OUTPUT-REWORK.md
diff --git a/plans/active/PLAN-LADYBUG-DB-MIGRATE.md b/plans/completed/PLAN-LADYBUG-DB-MIGRATE.md
similarity index 100%
rename from plans/active/PLAN-LADYBUG-DB-MIGRATE.md
rename to plans/completed/PLAN-LADYBUG-DB-MIGRATE.md
diff --git a/pr_analysis.py b/pr_analysis.py
index 874d24c..e0b49c4 100644
--- a/pr_analysis.py
+++ b/pr_analysis.py
@@ -152,7 +152,7 @@ def _resolve_graph_filename(
     *,
     ambiguity_notes: list[str] | None = None,
 ) -> str | None:
-    """Map a diff path to `Symbol.filename` values stored in Kuzu."""
+    """Map a diff path to `Symbol.filename` values stored in LadybugDB."""
     variants = {_strip_ab_prefix(path)}
     for v in list(variants):
         if v.startswith("./"):
@@ -362,7 +362,7 @@ def _is_public_interface_method(graph: Any, sym: SymbolHit) -> bool:
 
 
 def _route_ids_for_symbol(graph: Any, symbol_id: str) -> list[str]:
-    # Note: Kuzu rejects `ORDER BY r.id` together with `RETURN DISTINCT r.id` (binder loses `r`).
+    # Note: LadybugDB rejects `ORDER BY r.id` together with `RETURN DISTINCT r.id` (binder loses `r`).
     q = (
         "MATCH (s:Symbol)-[e:EXPOSES]->(r:Route) WHERE s.id = $sid "
         "RETURN r.id AS id ORDER BY id"
@@ -384,7 +384,6 @@ def compute_risk(graph: Any, changed: list[ChangedSymbol]) -> PrRiskReport:
     bump (up to +1.0) after normalization so they influence rank while
     preserving the public scalar contract.
     """
-    notes: list[str] = []
     blast_by: dict[str, int] = {}
     blast_total = 0
     routes: list[str] = []
@@ -495,7 +494,7 @@ def _normalize(x: float, ceiling: float) -> float:
         routes_touched=routes,
         risk_score=score,
         risk_band=band,
-        notes=notes,
+        notes=[],
     )
 
 
diff --git a/propose/active/INDEX-OUTPUT-REWORK-PROPOSE.md b/propose/completed/INDEX-OUTPUT-REWORK-PROPOSE.md
similarity index 100%
rename from propose/active/INDEX-OUTPUT-REWORK-PROPOSE.md
rename to propose/completed/INDEX-OUTPUT-REWORK-PROPOSE.md
diff --git a/propose/active/LADYBUG-DB-MIGRATE-PROPOSE.md b/propose/completed/LADYBUG-DB-MIGRATE-PROPOSE.md
similarity index 100%
rename from propose/active/LADYBUG-DB-MIGRATE-PROPOSE.md
rename to propose/completed/LADYBUG-DB-MIGRATE-PROPOSE.md
diff --git a/pyproject.toml b/pyproject.toml
index 449b523..ea4d579 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "java-codebase-rag"
-version = "0.6.2"
+version = "0.6.3"
 description = "MCP server for semantic + structural search over Java codebases"
 readme = "README.md"
 requires-python = ">=3.11"
diff --git a/search_lancedb.py b/search_lancedb.py
index 9029c6a..d617268 100644
--- a/search_lancedb.py
+++ b/search_lancedb.py
@@ -677,8 +677,8 @@ def _graph_expand_merge(
     expand_depth: int,
     ladybug_path: str | None,
 ) -> list[dict]:
-    """Expand vector top-k through the Kuzu graph and fuse (RRF) with the original list."""
-    # Lazy import so the module works without kuzu installed when graph_expand=False.
+    """Expand vector top-k through the LadybugDB graph and fuse (RRF) with the original list."""
+    # Lazy import so the module works without ladybug installed when graph_expand=False.
     try:
         from ladybug_queries import LadybugGraph
     except Exception:
diff --git a/skills/explore-codebase/SKILL.md b/skills/explore-codebase/SKILL.md
index eaa2e33..5562d52 100644
--- a/skills/explore-codebase/SKILL.md
+++ b/skills/explore-codebase/SKILL.md
@@ -166,7 +166,7 @@ Exclude `DTO`, `OTHER`, `MAPPER` with `exclude_roles` when tracing business logi
 
 **Symbol kinds:** `class`, `interface`, `enum`, `record`, `annotation`, `method`, `constructor`.
 
-**Route frameworks:** `spring_mvc`, `webflux`, `kafka`, `rabbitmq`, `jms`, `stream`, `feign`.
+**Route frameworks:** `spring_mvc`, `webflux`. (Route *kinds* are `http_endpoint`, `http_consumer`, `kafka_topic`, `rabbit_queue`, `jms_destination`, `stream_binding`.)
 **Client kinds:** `feign_method`, `rest_template`, `web_client`. **Producer kinds:** `kafka_send`, `stream_bridge_send`. **Source layers (client/producer):** `builtin`, `layer_a_meta`, `layer_b_ann`, `layer_b_fqn`, `layer_c_source`.
 **Match types:** `cross_service`, `intra_service`, `ambiguous`, `phantom`, `unresolved`.
 
diff --git a/tests/README.md b/tests/README.md
index 3c65ab7..5abb96c 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -2,10 +2,10 @@
 
 These tests exercise:
 
-1. `build_ast_graph.py` — the Tree-sitter Java -> Kuzu graph builder.
-2. `kuzu_queries.py` — read-only Cypher helpers used by the MCP server.
+1. `build_ast_graph.py` — the Tree-sitter Java -> LadybugDB graph builder.
+2. `ladybug_queries.py` — read-only Cypher helpers used by the MCP server.
 3. The MCP tool surface in `server.py` (every `@mcp.tool` is hit at least once,
-   either with a real Kuzu graph fixture or via its error-path when LanceDB
+   either with a real LadybugDB graph fixture or via its error-path when LanceDB
    isn't available).
 
 The fixture corpus lives under `tests/bank-chat-system/`. It is a *toy* but
@@ -37,7 +37,7 @@ cd /path/to/java-codebase-rag
 .venv/bin/python -m pytest tests -v
 ```
 
-**Kuzu Cypher:** When writing queries or asserting on edge filters, follow the pitfalls note in [`AGENTS.md`](../AGENTS.md) (avoid `label(e) IN $list` for type filters; be careful with typed union rel patterns).
+**LadybugDB Cypher:** When writing queries or asserting on edge filters, follow the pitfalls note in [`AGENTS.md`](../AGENTS.md) (avoid `label(e) IN $list` for type filters; be careful with typed union rel patterns).
 
 ## CI merge gate and fixture tiers
 
@@ -49,19 +49,19 @@ cd /path/to/java-codebase-rag
 
 | Tier | When | Pattern |
 | --- | --- | --- |
-| **1** | Read-only assertions against `tests/bank-chat-system/` | Use session `corpus_root` → `kuzu_db_path` → `kuzu_graph` / `mcp_server`. The session bank graph is built **once** per pytest process with pass1–5 + `write_kuzu` (**no pass6**), matching the bank caller-edge tests without strengthening pass6 match-resolution semantics. |
-| **2** | Read-only use of a static tree under `tests/fixtures/<name>/` | Prefer session fixtures in `conftest.py` (for example `kuzu_db_path_call_graph_smoke`, `kuzu_db_path_route_extraction_smoke`, `kuzu_graph_route_extraction_smoke`, `kuzu_db_path_cross_service_smoke`, `kuzu_db_path_fqn_collision_smoke`, `kuzu_db_path_http_caller_smoke`) or `graph_tables_cross_service_smoke` when tests need in-memory `GraphTables`. **Audit each file:** if a test copies the fixture into `tmp_path` and mutates files or YAML, it stays Tier 3 — do not point it at a shared session DB or shared `GraphTables`. |
-| **3** | Per-test corpora under `tmp_path` (brownfield stubs, generated YAML, etc.) | Keep per-test isolation; build via helpers in [`tests/_builders.py`](./_builders.py) (`build_kuzu_into`, `build_kuzu_imperative_into`, `build_kuzu_full_into`, or `build_graph_tables_to`) instead of duplicating `pass*` imports. |
+| **1** | Read-only assertions against `tests/bank-chat-system/` | Use session `corpus_root` → `ladybug_db_path` → `ladybug_graph` / `mcp_server`. The session bank graph is built **once** per pytest process with pass1–5 + `write_ladybug` (**no pass6**), matching the bank caller-edge tests without strengthening pass6 match-resolution semantics. |
+| **2** | Read-only use of a static tree under `tests/fixtures/<name>/` | Prefer session fixtures in `conftest.py` (for example `ladybug_db_path_call_graph_smoke`, `ladybug_db_path_route_extraction_smoke`, `ladybug_graph_route_extraction_smoke`, `ladybug_db_path_cross_service_smoke`, `ladybug_db_path_fqn_collision_smoke`, `ladybug_db_path_http_caller_smoke`) or `graph_tables_cross_service_smoke` when tests need in-memory `GraphTables`. **Audit each file:** if a test copies the fixture into `tmp_path` and mutates files or YAML, it stays Tier 3 — do not point it at a shared session DB or shared `GraphTables`. |
+| **3** | Per-test corpora under `tmp_path` (brownfield stubs, generated YAML, etc.) | Keep per-test isolation; build via helpers in [`tests/_builders.py`](./_builders.py) (`build_ladybug_into`, `build_ladybug_imperative_into`, `build_ladybug_full_into`, or `build_graph_tables_to`) instead of duplicating `pass*` imports. |
 
-**Consumer matrix (bank-chat and call invariant):** When changing the session bank pipeline (`kuzu_db_path`) or adding a parallel bank fixture, update the PR description with a short matrix of which tests depend on which pass depth. Conflicting requirements (for example pass6 changing HTTP_CALLS match rows that tests still expect as `unresolved`) must be resolved with a **separate** named session fixture or per-test builds — not by silently changing semantics.
+**Consumer matrix (bank-chat and call invariant):** When changing the session bank pipeline (`ladybug_db_path`) or adding a parallel bank fixture, update the PR description with a short matrix of which tests depend on which pass depth. Conflicting requirements (for example pass6 changing HTTP_CALLS match rows that tests still expect as `unresolved`) must be resolved with a **separate** named session fixture or per-test builds — not by silently changing semantics.
 
 | Test / area | Fixture / build | Pass depth | Semantics note |
 | --- | --- | --- | --- |
-| Session bank (`kuzu_db_path`, `kuzu_graph`, MCP) | `conftest` | pass1–5 + write, **no pass6** | Keeps bank `HTTP_CALLS` / `ASYNC_CALLS` matches `unresolved` for `test_call_edges_e2e`. |
-| `test_call_invariant_inert_on_bank_chat_system` | `kuzu_graph` | same as session bank | **Was** pass1–3 + write only. `pass3_skipped_cross_service` is a pass3 counter persisted on `GraphMeta`; passes 4–5 do not re-run pass3 or rewrite that field, so the value `0` for bank-chat is unchanged vs the old per-test build. |
-| `test_call_invariant_inert_on_clean_fixtures` | `kuzu_db_path_cross_service_smoke` | pass1–6 + write | **Was** pass1–3 + write on a fresh copy. Assertion is still `pass3_skipped_cross_service == 0` (pass3-only meta); later passes do not alter that counter for this fixture tree. |
+| Session bank (`ladybug_db_path`, `ladybug_graph`, MCP) | `conftest` | pass1–5 + write, **no pass6** | Keeps bank `HTTP_CALLS` / `ASYNC_CALLS` matches `unresolved` for `test_call_edges_e2e`. |
+| `test_call_invariant_inert_on_bank_chat_system` | `ladybug_graph` | same as session bank | **Was** pass1–3 + write only. `pass3_skipped_cross_service` is a pass3 counter persisted on `GraphMeta`; passes 4–5 do not re-run pass3 or rewrite that field, so the value `0` for bank-chat is unchanged vs the old per-test build. |
+| `test_call_invariant_inert_on_clean_fixtures` | `ladybug_db_path_cross_service_smoke` | pass1–6 + write | **Was** pass1–3 + write on a fresh copy. Assertion is still `pass3_skipped_cross_service == 0` (pass3-only meta); later passes do not alter that counter for this fixture tree. |
 
-**Tier-3 on copied `cross_service_smoke`:** `test_cross_service_resolution_flag.py` and `test_client_role_rename.py` copy the fixture into `tmp_path`, edit YAML/Java, then build. They **cannot** use the read-only session graph or shared `graph_tables_cross_service_smoke`; they call `build_graph_tables_to` / `build_kuzu_to` from `_builders.py` on each **mutable** copy so pass chains stay centralized.
+**Tier-3 on copied `cross_service_smoke`:** `test_cross_service_resolution_flag.py` and `test_client_role_rename.py` copy the fixture into `tmp_path`, edit YAML/Java, then build. They **cannot** use the read-only session graph or shared `graph_tables_cross_service_smoke`; they call `build_graph_tables_to` / `build_ladybug_to` from `_builders.py` on each **mutable** copy so pass chains stay centralized.
 
 **`test_mcp_v2.test_find_client_by_target_service`:** The seed row must come from `list_clients()` rows with a real `target_service` column. Using the first token of the display `fqn` was incorrect when `target_service` is empty (more client rows after pass5). That is a test bugfix, not a fixture-speed change — call it out in the PR.
 
@@ -72,7 +72,7 @@ Feign clients were added to bank-chat, verify `client_kind` via `list_clients()`
 
 **Timing:** Large fixture refactors should note rough wall-time before and after in the PR body (see the plan propose).
 
-The session-scoped fixtures in `conftest.py` materialize Kuzu (and, where needed, in-memory `GraphTables`) under `tmp_path_factory` so the static trees under `tests/` are never written at test time.
+The session-scoped fixtures in `conftest.py` materialize LadybugDB (and, where needed, in-memory `GraphTables`) under `tmp_path_factory` so the static trees under `tests/` are never written at test time.
 
 The heavier end-to-end test that runs `cocoindex` + a real LanceDB index is
 gated behind `JAVA_CODEBASE_RAG_RUN_HEAVY=1` because it downloads the embedding
@@ -140,9 +140,9 @@ When adding tests, please follow these rules:
 
 7. **Call graph proposal §7.1 vs tests.** The checklist in
    `propose/completed/CALL-GRAPH-PROPOSE.md` §7.1 is distributed across
-   `test_ast_java_calls.py`, `test_call_graph_smoke_roundtrip.py` (Kuzu build
-   of `tests/fixtures/call_graph_smoke/` only), the session Kuzu build,
-   `test_kuzu_queries.py`, `test_ast_graph_build.py`,
+   `test_ast_java_calls.py`, `test_call_graph_smoke_roundtrip.py` (LadybugDB build
+   of `tests/fixtures/call_graph_smoke/` only), the session LadybugDB build,
+   `test_ladybug_queries.py`, `test_ast_graph_build.py`,
    `tests/fixtures/call_graph_smoke/`, and `test_call_graph_receiver_resolution.py`
    — not as a single enumerated matrix. For an edge case the bank corpus cannot
    isolate, add a minimal tmp_path fixture or a tiny extra tree under
diff --git a/tests/conftest.py b/tests/conftest.py
index e42b4cc..400d4dc 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -2,7 +2,7 @@
 
 Session-scoped graphs are built once per static corpus (see ``tests/README.md``).
 The bank-chat chain ``corpus_root → ladybug_db_path → mcp_env → ladybug_graph → mcp_server``
-runs pass1–5 + ``write_kuzu`` (no pass6) so Tier-1 caller-edge tests match the
+runs pass1–5 + ``write_ladybug`` (no pass6) so Tier-1 caller-edge tests match the
 pre-refactor bank pipeline while avoiding a second full parse for MCP tests.
 
 ⚠️  Do not bake fixture-specific assumptions into the production code under
@@ -50,7 +50,7 @@ def _session_db_path(tmp_path_factory: pytest.TempPathFactory, name: str) -> Pat
 
 @pytest.fixture(scope="session")
 def ladybug_db_path(tmp_path_factory, corpus_root: Path) -> Path:
-    """Bank-chat Kuzu DB: pass1–5 + ``write_kuzu`` (no pass6)."""
+    """Bank-chat Kuzu DB: pass1–5 + ``write_ladybug`` (no pass6)."""
     import ladybug
 
     from _builders import build_ladybug_to
diff --git a/tests/test_path_filtering.py b/tests/test_path_filtering.py
index c33f695..78e40f3 100644
--- a/tests/test_path_filtering.py
+++ b/tests/test_path_filtering.py
@@ -55,10 +55,9 @@ def test_39_builtin_default_ignores_class_file(tmp_path: Path) -> None:
     f = root / "Foo.class"
     f.write_text("", encoding="utf-8")
     li = LayeredIgnore(root, use_gitignore=False)
-    ign, layer = li.is_ignored(f)
-    assert ign is True
-    assert layer is not None
-    assert layer.source == "builtin_default"
+    assert li.is_ignored(f) is True
+    d = li.diagnose_dict(f)
+    assert d["layer"] == "builtin_default"
 
 
 def test_40_project_root_negation_unignores(tmp_path: Path) -> None:
@@ -70,7 +69,7 @@ def test_40_project_root_negation_unignores(tmp_path: Path) -> None:
     f = root / "Foo.class"
     f.write_text("", encoding="utf-8")
     li = LayeredIgnore(root, use_gitignore=False)
-    assert li.is_ignored(f)[0] is False
+    assert li.is_ignored(f) is False
 
 
 def test_41_nested_ignore_only_under_subtree(tmp_path: Path) -> None:
@@ -84,8 +83,8 @@ def test_41_nested_ignore_only_under_subtree(tmp_path: Path) -> None:
     sibling.parent.mkdir(parents=True)
     sibling.write_text("class GeneratedBar {}\n", encoding="utf-8")
     li = LayeredIgnore(root, use_gitignore=False)
-    assert li.is_ignored(hit)[0] is True
-    assert li.is_ignored(sibling)[0] is False
+    assert li.is_ignored(hit) is True
+    assert li.is_ignored(sibling) is False
 
 
 def test_42_innermost_nested_reincludes(tmp_path: Path) -> None:
@@ -100,7 +99,7 @@ def test_42_innermost_nested_reincludes(tmp_path: Path) -> None:
     f.parent.mkdir(parents=True, exist_ok=True)
     f.write_text("class GeneratedX {}\n", encoding="utf-8")
     li = LayeredIgnore(root, use_gitignore=False)
-    assert li.is_ignored(f)[0] is False
+    assert li.is_ignored(f) is False
 
 
 def test_43_gitignore_layer(tmp_path: Path) -> None:
@@ -111,9 +110,10 @@ def test_43_gitignore_layer(tmp_path: Path) -> None:
     f.parent.mkdir(parents=True)
     f.write_text("class X {}\n", encoding="utf-8")
     li_on = LayeredIgnore(root, use_gitignore=True)
-    assert li_on.is_ignored(f)[0] is True
-    assert li_on.is_ignored(f)[1] is not None
-    assert li_on.is_ignored(f)[1].source == "gitignore"
+    assert li_on.is_ignored(f) is True
+    d = li_on.diagnose_dict(f)
+    assert d["ignored"] is True
+    assert d["layer"] == "gitignore"
 
 
 def test_44_gitignore_disabled(tmp_path: Path) -> None:
@@ -124,7 +124,7 @@ def test_44_gitignore_disabled(tmp_path: Path) -> None:
     f.parent.mkdir(parents=True)
     f.write_text("class X {}\n", encoding="utf-8")
     li = LayeredIgnore(root, use_gitignore=False)
-    assert li.is_ignored(f)[0] is False
+    assert li.is_ignored(f) is False
 
 
 def test_45_diagnose_nested_cites_line(tmp_path: Path) -> None:
@@ -151,7 +151,7 @@ def test_46_outside_project_not_ignored(tmp_path: Path) -> None:
     outside = tmp_path / "outside" / "Foo.java"
     outside.parent.mkdir(parents=True)
     outside.write_text("class Foo {}\n", encoding="utf-8")
-    assert li.is_ignored(outside) == (False, None)
+    assert li.is_ignored(outside) is False
 
 
 def test_bank_chat_java_count_no_lancedb_ignore_gitignore_off_matches_legacy(
@@ -195,7 +195,7 @@ def test_out_as_java_package_dir_is_walked_when_no_build_indicator_sibling(
     li = LayeredIgnore(root, use_gitignore=False)
     files = list(iter_java_source_files(root, ignore=li))
     assert f in files
-    ign, _ = li.is_ignored(f)
+    ign = li.is_ignored(f)
     assert ign is False