java-codebase-rag 0.9.7__py3-none-any.whl → 0.10.0__py3-none-any.whl

java_codebase_rag/watch/warm.py

@@ -0,0 +1,105 @@
+"""Warm-resources holder for the ``jrag watch`` daemon.
+
+``WarmResources`` keeps two expensive objects resident for the daemon's lifetime:
+
+  * the ``SentenceTransformer`` embedding model (loaded once, reused for every
+    query), and
+  * a read-only ``LadybugGraph`` over ``cfg.ladybug_path``.
+
+It also owns the graph copy-on-write snapshot lifecycle (design §4.7): while a
+graph-reindex subprocess writes the ORIGINAL ``code_graph.lbug``, the daemon serves
+graph reads from a file COPY (sidecar) so readers and the single-writer subprocess
+never collide. The ``ladybug`` engine has no transaction API and is single-writer,
+which is why graph builds run as subprocesses and reads are served from a copy.
+"""
+from __future__ import annotations
+
+import logging
+import shutil
+import threading
+from pathlib import Path
+
+from java_codebase_rag.config import ResolvedOperatorConfig
+from java_codebase_rag.graph.ladybug_queries import LadybugGraph
+from java_codebase_rag.mcp.mcp_v2 import _get_sentence_transformer
+
+log = logging.getLogger(__name__)
+
+
+class WarmResources:
+    """Holder for the warm embedding model + the read-only graph reader.
+
+    The model is cached automatically by ``mcp_v2``'s module global, so ``model()``
+    returning the same instance across calls is the warmth win. ``graph()`` returns
+    the snapshot reader when a snapshot is active, else the original reader. Both are
+    safe to call from server threads (the underlying singletons are lock-guarded).
+
+    The snapshot flip (``begin_graph_snapshot`` / ``commit_graph_snapshot``) is
+    serialized against ``graph()`` reads by ``self._lock`` so a reader can never
+    observe a torn state (e.g. read ``_snapshot_path=None`` after ``begin`` has
+    already reset the original singleton but before it set the sidecar, then
+    re-cache the original a subprocess is concurrently overwriting). Lock ordering:
+    ``WarmResources._lock`` is always the OUTER lock; ``LadybugGraph._lock`` (taken
+    inside ``get``/``reset_for_path``) is INNER — never reversed. The lock is held
+    only across the in-process flip + read, NEVER across the long reindex
+    subprocess (the watcher calls ``begin`` before it and ``commit`` after).
+    """
+
+    def __init__(self, cfg: ResolvedOperatorConfig) -> None:
+        self.cfg = cfg
+        self._snapshot_path: Path | None = None
+        # Serializes the snapshot flip against graph() reads (see class docstring).
+        self._lock = threading.Lock()
+
+    def model(self):
+        """Return the warm ``SentenceTransformer`` (cached by the module global)."""
+        return _get_sentence_transformer(self.cfg.embedding_model, self.cfg.embedding_device)
+
+    def graph(self) -> LadybugGraph:
+        """Return the current graph reader: the sidecar if a snapshot is active, else the original.
+
+        The read of ``_snapshot_path`` and the matching ``LadybugGraph.get(...)`` are
+        atomic w.r.t. the snapshot flip (held under ``self._lock``) so a reader always
+        pairs the right path with the right cached singleton.
+        """
+        with self._lock:
+            if self._snapshot_path is not None:
+                return LadybugGraph.get(str(self._snapshot_path))
+            return LadybugGraph.get(str(self.cfg.ladybug_path))
+
+    def begin_graph_snapshot(self) -> None:
+        """Copy the graph to a sidecar and serve subsequent ``graph()`` reads from it.
+
+        Drops the cached original reader (so the subprocess is free to overwrite the
+        original file) and switches ``graph()`` to a fresh reader on the sidecar copy.
+        The whole flip runs under ``self._lock`` so no ``graph()`` read can observe an
+        intermediate state (original reset but sidecar not yet set).
+        """
+        with self._lock:
+            sidecar = self.cfg.ladybug_path.with_suffix(".lbug.snapshot")
+            shutil.copy2(self.cfg.ladybug_path, sidecar)
+            LadybugGraph.reset_for_path(str(self.cfg.ladybug_path))
+            self._snapshot_path = sidecar
+
+    def commit_graph_snapshot(self) -> None:
+        """Drop the sidecar reader, remove the sidecar, and reopen the updated original.
+
+        After this call ``graph()`` reads the original again (which the subprocess has
+        just rewritten), and the sidecar file is gone. Idempotent no-op when no
+        snapshot is active. The whole flip runs under ``self._lock`` so no ``graph()``
+        read can observe the sidecar mid-teardown.
+        """
+        with self._lock:
+            if self._snapshot_path is None:
+                return
+            sidecar = self._snapshot_path
+            LadybugGraph.reset_for_path(str(sidecar))
+            try:
+                sidecar.unlink(missing_ok=True)
+            except OSError:
+                log.warning("Failed to remove graph snapshot sidecar %s", sidecar, exc_info=True)
+            finally:
+                # Clear state and reopen the original even if unlink failed, so a
+                # possibly-deleted sidecar isn't kept serving reads.
+                self._snapshot_path = None
+                LadybugGraph.reset_for_path(str(self.cfg.ladybug_path))

java_codebase_rag/watch/watcher.py

@@ -0,0 +1,352 @@
+"""File watcher + debounced per-type reindex dispatcher for ``jrag watch``.
+
+``SourceWatcher`` observes the project source tree and, after a debounce window,
+re-runs the minimal reindex for the changed file types:
+
+  * a ``.java`` change -> vectors THEN graph. The graph reindex runs as a
+    subprocess under a copy-on-write snapshot (design §4.7) so concurrent graph
+    reads keep being served from a sidecar copy while the single-writer
+    subprocess overwrites the original. ``ladybug`` has no transactions and is
+    single-writer, which is why graph builds are subprocesses and reads are
+    served from a copy.
+  * a matching ``.sql`` / ``.yml`` / ``.yaml`` resource change -> vectors only
+    (the graph does not index SQL/YAML, so no snapshot is needed).
+
+Change bursts are coalesced: the leading event arms a ``debounce_ms`` timer that
+keeps getting re-armed while events keep arriving, and a single ``reindex`` fires
+once the window goes quiet. ``reindex`` runs on a dedicated background thread so
+the watchdog observer thread is never blocked.
+
+The cocoindex flow indexes three sets (``**/*.java``,
+``**/src/main/resources/db/migration/*.sql``,
+``**/src/main/resources/application*.yml``/``.yaml``). There is NO shared
+iterator (``iter_java_source_files`` yields ``.java`` only), so the watcher
+defines this UNION and classifies each event path into a reindex kind.
+
+All status is reported via ``on_event(kind, detail)`` callbacks (kinds:
+``indexing_started`` / ``vectors`` / ``graph`` / ``indexing_done`` / ``error``);
+the watcher never prints directly.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable
+
+from watchdog.events import FileSystemEventHandler
+from watchdog.observers import Observer
+from watchdog.observers.polling import PollingObserver
+
+from java_codebase_rag.graph.path_filtering import LayeredIgnore
+from java_codebase_rag.pipeline import run_cocoindex_update, run_incremental_graph
+
+if TYPE_CHECKING:
+    from java_codebase_rag.config import ResolvedOperatorConfig
+    from java_codebase_rag.watch.warm import WarmResources
+
+log = logging.getLogger(__name__)
+
+# Suffixes the watcher treats as java sources. The non-java resource types are
+# matched by the glob helpers below (the cocoindex set has no shared iterator).
+INDEXED_SUFFIXES: tuple[str, ...] = (".java",)
+_YAML_SUFFIXES: tuple[str, ...] = (".yml", ".yaml")
+
+# Project-relative anchored prefixes for the two non-java resource globs:
+#   **/src/main/resources/db/migration/*.sql
+#   **/src/main/resources/application*.yml / .yaml
+_SQL_MIGRATION_PREFIX = "src/main/resources/db/migration/"
+_RESOURCES_PREFIX = "src/main/resources/"
+
+
+def _is_migration_sql(rel_posix: str) -> bool:
+    """True iff ``rel_posix`` is a ``.sql`` directly under a ``.../db/migration/`` dir."""
+    if not rel_posix.endswith(".sql"):
+        return False
+    idx = rel_posix.rfind(_SQL_MIGRATION_PREFIX)
+    if idx == -1:
+        return False
+    # The file must sit directly under migration/ (no further path segment).
+    return "/" not in rel_posix[idx + len(_SQL_MIGRATION_PREFIX):]
+
+
+def _is_application_yaml(rel_posix: str) -> bool:
+    """True iff ``rel_posix`` is ``application*.yml``/``.yaml`` directly under
+    a ``.../src/main/resources/`` dir."""
+    name = rel_posix.rsplit("/", 1)[-1]
+    if not name.startswith("application"):
+        return False
+    if not name.endswith((".yml", ".yaml")):
+        return False
+    idx = rel_posix.rfind(_RESOURCES_PREFIX)
+    if idx == -1:
+        return False
+    return "/" not in rel_posix[idx + len(_RESOURCES_PREFIX):]
+
+
+class _ChangeHandler(FileSystemEventHandler):
+    """Bridge watchdog events to the watcher's classify+schedule path.
+
+    Directory events are ignored. Each file event's path (and, for moves, the
+    destination) is classified; if it matches an indexed type and survives
+    ``LayeredIgnore`` its kind is scheduled.
+    """
+
+    def __init__(self, watcher: "SourceWatcher") -> None:
+        super().__init__()
+        self._watcher = watcher
+
+    def on_any_event(self, event) -> None:  # type: ignore[override]
+        if event.is_directory:
+            return
+        self._watcher._handle_path(event.src_path)
+        dest = getattr(event, "dest_path", None)
+        if dest:
+            self._watcher._handle_path(dest)
+
+
+class SourceWatcher:
+    """Watch ``cfg.source_root`` and dispatch debounced per-type reindexes.
+
+    Thread model: watchdog's observer thread calls the handler (which only does a
+    quick classify + schedule -- never blocks). A single dedicated debounce
+    worker thread runs ``reindex`` so the observer is never held up by a build.
+    """
+
+    def __init__(
+        self,
+        cfg: "ResolvedOperatorConfig",
+        warm: "WarmResources",
+        *,
+        debounce_ms: int,
+        backend: str,
+        poll_interval_ms: int,
+        on_event: Callable[[str, dict[str, Any]] | None] = None,
+    ) -> None:
+        self.cfg = cfg
+        self.warm = warm
+        self._debounce_s = max(int(debounce_ms), 1) / 1000.0
+        self._backend = backend
+        # watchdog's PollingObserver takes a float timeout in SECONDS (it flows
+        # straight into ``threading.Event.wait``); a timedelta crashes the emitter.
+        self._poll_interval_s = max(int(poll_interval_ms), 1) / 1000.0
+        self._on_event = on_event
+
+        self._ignore = LayeredIgnore(cfg.source_root)
+        self._source_root_resolved = Path(cfg.source_root).resolve()
+
+        self._observer = self._make_observer()
+        self._handler = _ChangeHandler(self)
+
+        # Debounce state -- touched by the observer thread and the debounce worker.
+        self._lock = threading.Lock()
+        self._pending: set[str] = set()
+        self._activity = threading.Event()
+        self._stop = threading.Event()
+        self._debounce_thread = threading.Thread(
+            target=self._debounce_loop, name="jrag-watch-debounce", daemon=True
+        )
+
+        # In-memory reindex state, refreshed after each successful reindex.
+        self.last_reindex: dict[str, Any] | None = None
+
+    # -- observer backend ----------------------------------------------------
+
+    def _make_observer(self):
+        if self._backend == "polling":
+            return PollingObserver(timeout=self._poll_interval_s)
+        # "watchdog" and "auto" both prefer the native observer; "auto" falls
+        # back to polling in :meth:`start` if the native backend cannot start.
+        return Observer()
+
+    # -- lifecycle -----------------------------------------------------------
+
+    def start(self) -> None:
+        """Schedule the observer on ``cfg.source_root`` (recursive) and start the
+        debounce loop. Under ``backend="auto"`` a native observer that fails to
+        start (e.g. on some network filesystems) falls back to polling."""
+        self._observer.schedule(self._handler, str(self.cfg.source_root), recursive=True)
+        try:
+            self._observer.start()
+        except Exception as exc:
+            if self._backend != "auto":
+                raise
+            self._emit(
+                "error",
+                {"phase": "observer", "fallback": "polling", "error": repr(exc)},
+            )
+            self._observer = PollingObserver(timeout=self._poll_interval_s)
+            self._observer.schedule(self._handler, str(self.cfg.source_root), recursive=True)
+            self._observer.start()
+        self._debounce_thread.start()
+
+    def stop(self) -> None:
+        """Stop the observer and the debounce loop; join both."""
+        self._stop.set()
+        self._activity.set()  # unblock the debounce worker's wait
+        try:
+            if self._observer.is_alive():
+                self._observer.stop()
+                self._observer.join(timeout=5.0)
+        except Exception:
+            log.warning("watchdog observer stop failed", exc_info=True)
+        if (
+            self._debounce_thread.is_alive()
+            and threading.current_thread() is not self._debounce_thread
+        ):
+            self._debounce_thread.join(timeout=10.0)
+
+    # -- event classification (observer thread) ------------------------------
+    #
+    # The watcher fires on exactly the cocoindex-indexed set (``.java`` plus the
+    # SQL/YAML resource patterns below) filtered through ``LayeredIgnore``.
+    # ``target/generated-sources/**/*.java`` therefore correctly fires: generated
+    # sources are first-class, cocoindex does NOT exclude ``target/``, so the
+    # watcher must fire to keep them fresh. ``LayeredIgnore.is_ignored`` does NOT
+    # prune build-output dirs (``target/``/``build``/``out``) -- that pruning lives
+    # in ``iter_java_source_files``'s ``os.walk`` (``_is_build_output_dir``), used
+    # by the graph builder, not by cocoindex. (Compiled ``.class`` output under
+    # ``target/`` doesn't match the ``.java`` suffix anyway.)
+
+    def _handle_path(self, src_path: object) -> None:
+        """Classify one observed path and schedule its kind if indexed & not ignored."""
+        kinds = self._classify(Path(str(src_path)))
+        if kinds:
+            self._schedule(kinds)
+
+    def _classify(self, path: Path) -> set[str]:
+        """Return the set of reindex kinds for ``path`` (empty if ignored/unknown).
+
+        ``LayeredIgnore`` wins: an ignored path yields no kind even when its
+        suffix is ``.java``. Outside-source-root paths also yield nothing.
+        """
+        try:
+            if self._ignore.is_ignored(path):
+                return set()
+        except Exception:
+            return set()
+        try:
+            rel = path.resolve().relative_to(self._source_root_resolved).as_posix()
+        except ValueError:
+            return set()
+        suffix = path.suffix.lower()
+        if suffix == ".java":
+            return {"java"}
+        if suffix == ".sql":
+            return {"sql"} if _is_migration_sql(rel) else set()
+        if suffix in _YAML_SUFFIXES:
+            return {"yaml"} if _is_application_yaml(rel) else set()
+        return set()
+
+    def _schedule(self, kinds: set[str]) -> None:
+        """Union ``kinds`` into the debounce collector and (re)arm the debounce window."""
+        if not kinds:
+            return
+        with self._lock:
+            self._pending |= kinds
+        self._activity.set()
+
+    # -- debounce worker thread ----------------------------------------------
+
+    def _debounce_loop(self) -> None:
+        """Fire ``reindex`` once per quiet period, coalescing bursts.
+
+        Leading edge: the first event arms a ``debounce_ms`` window. Each further
+        event during the window re-arms it. When the window expires with no new
+        events, the accumulated kinds are flushed to ``reindex`` in ONE call.
+        """
+        while not self._stop.is_set():
+            # Wait for the leading edge of a burst.
+            self._activity.wait()
+            if self._stop.is_set():
+                return
+            # Re-arm while events keep arriving (debounce).
+            while not self._stop.is_set():
+                self._activity.clear()
+                if self._activity.wait(timeout=self._debounce_s):
+                    continue  # new activity -> reset the window
+                break  # quiet period elapsed -> fire
+            if self._stop.is_set():
+                return
+            with self._lock:
+                kinds = self._pending
+                self._pending = set()
+            if kinds:
+                try:
+                    self.reindex(kinds)
+                except Exception:  # noqa: BLE001 -- reindex emits its own error; never kill the worker
+                    log.warning("reindex raised unexpectedly", exc_info=True)
+
+    # -- reindex (runs on the debounce worker thread) ------------------------
+
+    def reindex(self, kinds: set[str]) -> None:
+        """Run one debounced reindex: vectors always; graph only when java changed.
+
+        COW lifecycle (design §4.7): the graph subprocess writes the ORIGINAL
+        graph while reads are served from a sidecar copy. ``begin_graph_snapshot``
+        is called BEFORE the subprocess and ``commit_graph_snapshot`` ALWAYS
+        (success OR failure) so a snapshot reader is never left dangling -- on
+        graph failure the existing ``.graph_increment_in_progress`` crash marker
+        drives the next full rebuild. Lance needs no snapshot (commits are atomic
+        per version; fresh per-query reads are fine).
+        """
+        if not kinds:
+            return
+        kind_list = sorted(kinds)
+        self._emit("indexing_started", {"kinds": kind_list})
+        try:
+            # Vectors run for every indexed type (java/sql/yaml all flow through cocoindex).
+            self._emit("vectors", {"kinds": kind_list})
+            vres = run_cocoindex_update(
+                self.cfg.subprocess_env(),
+                full_reprocess=False,
+                quiet=True,
+                verbose=False,
+            )
+
+            graph_rc = 0
+            if "java" in kinds:
+                # Graph indexes java only; reindex under a COW snapshot so graph
+                # reads continue (from the sidecar) during the subprocess write.
+                self._emit("graph", {"kinds": kind_list})
+                try:
+                    # begin/commit paired in this try/finally. begin_graph_snapshot
+                    # sets ``_snapshot_path`` last, so if it raises commit no-ops;
+                    # moving begin inside the try keeps the pairing locally evident.
+                    self.warm.begin_graph_snapshot()
+                    gres = run_incremental_graph(
+                        source_root=self.cfg.source_root,
+                        ladybug_path=self.cfg.ladybug_path,
+                        verbose=False,
+                        quiet=True,
+                        env=self.cfg.subprocess_env(),
+                    )
+                    graph_rc = gres.returncode
+                finally:
+                    # ALWAYS drop the snapshot reader -- even on failure -- so it
+                    # is never left dangling. No-ops when no snapshot is active.
+                    self.warm.commit_graph_snapshot()
+
+            if vres.returncode != 0:
+                self._emit("error", {"phase": "vectors", "returncode": vres.returncode})
+                return
+            if graph_rc != 0:
+                self._emit("error", {"phase": "graph", "returncode": graph_rc})
+                return
+
+            self.last_reindex = {"time": time.time(), "kinds": kind_list}
+            self._emit("indexing_done", {"kinds": kind_list})
+        except Exception as exc:  # noqa: BLE001 -- the daemon must survive any reindex error
+            self._emit("error", {"phase": "reindex", "error": repr(exc)})
+
+    # -- status --------------------------------------------------------------
+
+    def _emit(self, kind: str, detail: dict[str, Any]) -> None:
+        """Forward a status callback to the UI; never let it crash the watcher."""
+        if self._on_event is None:
+            return
+        try:
+            self._on_event(kind, detail)
+        except Exception:  # noqa: BLE001 -- a UI callback must not crash the watcher
+            log.warning("on_event callback raised", exc_info=True)

{java_codebase_rag-0.9.7.dist-info → java_codebase_rag-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.9.7
+Version: 0.10.0
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -21,21 +21,22 @@ Classifier: Operating System :: Microsoft :: Windows
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: cocoindex[lancedb]<2,>=1.0.7; sys_platform != "darwin" or platform_machine != "x86_64"
+Requires-Dist: cocoindex[lancedb]<2,>=1.0.15; sys_platform != "darwin" or platform_machine != "x86_64"
 Requires-Dist: ladybug<0.18,>=0.17.1
-Requires-Dist: lancedb<0.31,>=0.25.3; sys_platform != "darwin" or platform_machine != "x86_64"
+Requires-Dist: lancedb<0.36,>=0.34; sys_platform != "darwin" or platform_machine != "x86_64"
 Requires-Dist: mcp<2,>=1.27.0
 Requires-Dist: numpy<2.5,>=1.26.4
 Requires-Dist: pathspec<2,>=1.0.4
-Requires-Dist: pyarrow<24,>=23.0.1
+Requires-Dist: pyarrow<26,>=23.0.1
 Requires-Dist: pydantic<3,>=2.0
 Requires-Dist: PyYAML<7,>=6.0.3
 Requires-Dist: questionary<3,>=2.0
-Requires-Dist: rich<15,>=14
+Requires-Dist: rich<16,>=14
 Requires-Dist: sentence-transformers<6,>=5.4.0; sys_platform != "darwin" or platform_machine != "x86_64"
 Requires-Dist: tree-sitter<0.26,>=0.25.2
 Requires-Dist: tree-sitter-java<0.24,>=0.23.5
 Requires-Dist: unidiff<1,>=0.7.3
+Requires-Dist: watchdog<7,>=6
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
@@ -45,18 +46,16 @@ Dynamic: license-file
 
 # java-codebase-rag
 
-A graph-native code intelligence layer for Java microservice estates — usable as an **MCP server** or a **CLI** (`jrag`), two surfaces over the same graph.
+A graph-native code intelligence layer for Java microservice estates, surfaced through the **`jrag` CLI** — one command per engineering intent. A **legacy MCP server** (`search` / `find` / `describe` / `neighbors` / `resolve`) is also available for existing setups. Both are thin surfaces over the same **AST Graph**: a deterministic property graph extracted from Java source with tree-sitter, stored **locally** in **LadybugDB** (graph) alongside a **LanceDB** vector index (chunks). There is no server to host and no cloud round-trip — the index lives on your disk and your source never leaves the machine. Both surfaces collapse onto three primitive 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 two agent surfaces, picked at install time (`java-codebase-rag install --surface mcp|cli`): the **MCP** surface ships five tools — `search`, `find`, `describe`, `neighbors`, `resolve` — over stdio; the **CLI** surface ships `jrag`, one command per engineering intent. Both collapse onto three primitive operations: **locate**, **inspect**, **walk**.
-
-> **What this MCP is:** a **GPS for code navigation**, not a reasoning engine.
+> **What this is: a GPS for code navigation**, not a reasoning engine.
 > Agents use a simple loop:
 >
-> 1. **Locate** entry nodes (`search` / `find`, or identifier-shaped **`resolve`**)
-> 2. **Inspect** what a node is (`describe`)
-> 3. **Walk** one hop at a time (`neighbors`) until enough evidence is gathered
+> 1. **Locate** entry nodes (`jrag find`, `jrag search`, or identifier-shaped lookup)
+> 2. **Inspect** what a node is (`jrag inspect`)
+> 3. **Walk** one hop at a time (`jrag callers` / `callees` / `hierarchy` / …) until enough evidence is gathered
 >
-> The MCP exposes structure and adjacency; the agent owns multi-hop reasoning and stop conditions.
+> The tool exposes structure and adjacency; the agent owns multi-hop reasoning and stop conditions.
 
 For the design rationale, the GPS metaphor, and the full ontology, see [`docs/paper/paper.pdf`](./docs/paper/paper.pdf) (architecture report).
 
@@ -66,7 +65,7 @@ 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 (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.
+- **Hybrid RAG + AST Graph, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (the LadybugDB AST 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`, `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.
 
@@ -86,7 +85,7 @@ The rest of this README is the install, the tool/command orientation, and the re
 pip install java-codebase-rag
 ```
 
-Python **3.11+** required, on **Linux, macOS, and Windows**. On Linux, Windows, and **Apple Silicon** Macs every native dependency (LanceDB, LadybugDB/kuzu, CocoIndex) ships a wheel and you get the full semantic + graph search. **Intel Macs (x86_64) install graph-only**: PyTorch ≥2.3 and LanceDB ≥0.26 dropped macOS Intel wheels, so the vector stack is auto-excluded via PEP 508 markers — `pip install java-codebase-rag` works out of the box, the graph layer (`find` / `describe` / `neighbors` / `resolve`) is fully usable, and the `search` tool falls back to **lexical (keyword) search** over the symbol graph (same tool contract, keyword-ranked instead of semantic; an advisory notes the mode). Semantic/vector search needs Apple Silicon, Linux, or Windows. After install, `java-codebase-rag --help` should print the CLI groups.
+Python **3.11+** required, on **Linux, macOS, and Windows**. On Linux, Windows, and **Apple Silicon** Macs every native dependency (LanceDB, LadybugDB, CocoIndex) ships a wheel and you get the full semantic + graph search. **Intel Macs (x86_64) install graph-only**: PyTorch ≥2.3 and LanceDB ≥0.26 dropped macOS Intel wheels, so the vector stack is auto-excluded via PEP 508 markers — `pip install java-codebase-rag` works out of the box, the graph layer (`find` / `describe` / `neighbors` / `resolve`) is fully usable, and the `search` tool falls back to **lexical search** over the symbol graph — BM25-ranked over a LadybugDB full-text index (same tool contract, keyword-ranked instead of semantic; an advisory notes the mode). Semantic/vector search needs Apple Silicon, Linux, or Windows. After install, `java-codebase-rag --help` should print the CLI groups.
 The package includes the CocoIndex lifecycle dependency used by `init`, `increment`, `reprocess`, and `erase` on platforms that have it (it is absent on Intel Mac).
 
 ### Interactive setup (recommended)
@@ -122,19 +121,7 @@ If you prefer manual configuration, see [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs
 
 ## Tools & commands at a glance
 
-Pick a surface at install time — `java-codebase-rag install --surface mcp|cli` (default `cli`, recommended). Both surfaces walk the same LanceDB vectors + LadybugDB graph. Switch an existing install later with `java-codebase-rag update --surface mcp|cli`.
-
-**MCP surface — five tools over stdio**
-
-| Tool | Purpose | Required args |
-|---|---|---|
-| `search` | Locate nodes by NL / code text. | `query` |
-| `find` | Locate nodes by structured filter. | `kind`, `filter` |
-| `describe` | Full record + edge counts for one node. | `id` |
-| `resolve` | Identifier-shaped lookup (FQN-collision-safe). Returns `one` / `many` / `none`. | `identifier` |
-| `neighbors` | Graph walk, one hop. | `ids`, `direction`, `edge_types` |
-
-Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live in [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md). Edge types and traversal directions are listed in [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md).
+`jrag` is the default and recommended surface (`java-codebase-rag install --surface cli`). The **MCP server** (`--surface mcp`) is kept as a **legacy** option for existing setups. Both surfaces walk the same LanceDB vectors + LadybugDB **AST Graph**. Switch an existing install later with `java-codebase-rag update --surface mcp|cli`.
 
 **CLI surface — `jrag`, one command per engineering intent**
 
@@ -143,7 +130,7 @@ Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live
 jrag status                    # index health (ontology version, freshness, counts)
 jrag microservices             # microservices with resolved type counts
 jrag map                       # counts per kind per service/module
-jrag map --module              # group by module instead
+jrag map --by module           # group by module instead (--module filters)
 jrag conventions               # dominant roles + framework tallies
 jrag overview chat-core        # bundle for a microservice
 jrag overview /chat/assign     # route flow (inbound callers + outbound CALLS)
@@ -191,9 +178,21 @@ jrag search "audit" --offset 5            # paginated
 
 Every `<query>` command takes human-readable identifiers (FQN / simple name / route path / topic) — never raw node IDs. Output contract, flags, and the resolve-first rule are in [`jrag` — agent CLI](#jrag--agent-cli) below.
 
+**MCP surface — five tools over stdio (legacy)**
+
+| Tool | Purpose | Required args |
+|---|---|---|
+| `search` | Locate nodes by NL / code text. | `query` |
+| `find` | Locate nodes by structured filter. | `kind`, `filter` |
+| `describe` | Full record + edge counts for one node. | `id` |
+| `resolve` | Identifier-shaped lookup (FQN-collision-safe). Returns `one` / `many` / `none`. | `identifier` |
+| `neighbors` | Graph walk, one hop. | `ids`, `direction`, `edge_types` |
+
+Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live in [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md). Edge types and traversal directions are listed in [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md).
+
 ### Three-layer architecture
 
-Layer 1 (storage) → Layer 2 (5 MCP tools **or** the `jrag` CLI) → Layer 3 (skill). The MCP-surface skill **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** documents the 5-tool MCP; the CLI-surface skill **[`/explore-codebase-cli`](./skills/explore-codebase-cli/SKILL.md)** documents the `jrag` CLI (PR-JRAG-5). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
+Layer 1 (storage) → Layer 2 (the `jrag` CLI, **or** the legacy 5-tool MCP) → Layer 3 (skill). The CLI-surface skill **[`/explore-codebase-cli`](./skills/explore-codebase-cli/SKILL.md)** documents the `jrag` CLI; the MCP-surface skill **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** documents the legacy 5-tool MCP (PR-JRAG-5). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
 
 ---
 
@@ -303,7 +302,7 @@ full design and per-PR breakdown.
 | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | Environment variables, project YAML, graph ontology, brownfield overrides, ignore patterns. |
 | [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) | CLI operator playbook: workflows, exit codes, env alignment. |
 | [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. |
-| [`skills/`](./skills/) | `/explore-codebase` (MCP surface) + `/explore-codebase-cli` (CLI surface) skills — operating manuals for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
+| [`skills/`](./skills/) | `/explore-codebase-cli` (CLI surface) + `/explore-codebase` (legacy MCP surface) skills — operating manuals for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
 | [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. |
 | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. |
 | [`docs/PRODUCT-VISION.md`](./docs/PRODUCT-VISION.md) | Long-term product direction. |