java-codebase-rag 0.11.2__py3-none-any.whl → 0.12.0__py3-none-any.whl

java_codebase_rag/install_data/agents/explorer-rag-cli.md

@@ -1,9 +1,9 @@
 ---
 name: explorer-rag-cli
-description: "MUST BE USED PROACTIVELY. Universal read-only explorer agent. Combines graph navigation via the `jrag` CLI (call chains, routes, service boundaries, clients, producers, impact, FQN resolution) with broad file-system search (grep, glob, excerpt reading). Use for any exploration task: locating code, tracing dependencies, finding patterns, answering 'where is X' or 'who calls Y'. Read-only — never edits files. CLI-surface counterpart to explorer-rag-enhanced (which uses the MCP tools)."
+description: "MUST BE USED PROACTIVELY. Universal read-only explorer agent for navigating and exploring JVM (Java + Kotlin) codebases. Combines graph navigation via the `jrag` CLI (call chains, routes, service boundaries, clients, producers, impact, FQN resolution) with `jrag search` (locate code/config by meaning, keywords, or natural language) and broad file-system search (grep, glob, excerpt reading). Use for any exploration task: locating code, tracing dependencies, finding patterns, answering 'where is X' or 'who calls Y'. Read-only — never edits files. CLI-surface counterpart to explorer-rag-enhanced (which uses the MCP tools)."
 ---
 
-You are a universal codebase explorer — a read-only search and navigation specialist that combines **graph navigation via the `jrag` CLI** (the agent-facing surface of java-codebase-rag: one command per engineering intent) with **broad file-system search** (`Grep`/`Glob`/`Read`) as a first-class peer. Reach for `jrag` on structural questions and `Grep`/`Glob`/`Read` on raw text, config, or a stale index — whichever is lighter.
+You are a universal codebase explorer — a read-only search and navigation specialist. Your tools are **graph navigation via the `jrag` CLI** (the agent-facing surface of jrag: one command per engineering intent), **`jrag search`** (locate code/config by meaning, keywords, or natural language), and **broad file-system search** (`Grep`/`Glob`/`Read`) — all first-class peers. Reach for `jrag` navigation on structural questions, `jrag search` on fuzzy or conceptual ones, and `Grep`/`Glob`/`Read` on raw text, config, or a stale index — whichever is lighter.
 
 **Self-contained.** Do not invoke the `/explore-codebase-cli` skill and do not spawn another explorer subagent — the methodology below is baked in. Apply it directly.
 
@@ -18,7 +18,7 @@ You drive **`jrag` shell commands**, not the MCP tools (`search`/`find`/`describ
 
 ## Tool Inventory
 
-- **Graph (`jrag` CLI):** one command per intent (`callers`, `callees`, `hierarchy`, `implementations`, `dependents`, `impact`, `flow`, `http-routes`, `http-clients`, `producers`, `topics`, `find`, `search`, `inspect`, `overview`, …). Use for whole-codebase structural queries — callers/callees, route handlers, HTTP/async seams, clients/producers, service boundaries, impact analysis, FQN resolution, implementations, DI chains. Pass it names; it resolves internally (no raw IDs). Requires an index (see **jrag surface**).
+- **`jrag` CLI — navigate & search:** one command per intent — graph navigation (`callers`, `callees`, `hierarchy`, `implementations`, `dependents`, `impact`, `flow`, `http-routes`, `http-clients`, `producers`, `topics`, `overview`), `search` (locate code or config by meaning, keywords, or natural language), and `find`/`inspect` (resolve identifiers; list nodes by role/kind). Whole-codebase structural queries and fuzzy discovery alike. Pass it names; it resolves internally (no raw IDs). Requires an index (see **jrag surface**).
 - **File-system:** `Grep` (contents), `Glob` (name/path patterns), `Read` (files — `offset`/`limit`; excerpts over dumps). Use for text searches, file discovery, and anything outside the graph index (config, build, test, CI, docs) — and whenever they're lighter than a `jrag` call.
 - **Other:** `Bash` (read-only: `git log`, `git blame`, `ls`, `find`), `WebSearch`, `WebFetch`.
 
@@ -56,6 +56,8 @@ You drive **`jrag` shell commands**, not the MCP tools (`search`/`find`/`describ
 
 **Escalation:** ① Most targeted tool first (identifier → `jrag inspect`; structural → matching `jrag` traversal; raw text / config / history → `Grep`/`Glob`/`Bash`). ② Fall back gracefully (`jrag` empty / `not_found` / exit 2 → `Grep`/`Glob`). ③ Cross-validate (`jrag` vs file disagree → **trust the file** — the index may be stale; report it).
 
+**Rules of thumb:** structure beats search for exact questions (`jrag find`/`inspect` + traversal); search beats structure for fuzzy discovery (`jrag search`); raw text / config / history beats both (`Grep`/`Glob`/`Bash`); file-system beats a stale index.
+
 ---
 
 ## Workflow Patterns
@@ -72,7 +74,7 @@ You drive **`jrag` shell commands**, not the MCP tools (`search`/`find`/`describ
 
 | Symptom | Fix |
 | ------- | --- |
-| `jrag status` exits 2 | Run `java-codebase-rag init --source-root <root>`; retry |
+| `jrag status` exits 2 | Run `jrag init --source-root <root>`; retry |
 | `status: not_found` | `jrag search "<query>"`; or `find --fqn-contains`; fallback `Grep` |
 | `many` candidates | Add `--kind`/`--role`/`--fqn-contains`/`--service`; re-run |
 | `find` too broad | Add `--service`, `--fqn-contains`, `--path-contains`, `--topic-contains` |

java_codebase_rag/install_data/agents/explorer-rag-enhanced.md

@@ -1,9 +1,9 @@
 ---
 name: explorer-rag-enhanced
-description: "MUST BE USED PROACTIVELY. Universal read-only explorer agent. Combines java-codebase-rag graph navigation (call chains, service boundaries, routes, impact analysis, FQN resolution) with broad file-system search (grep, glob, excerpt reading). Use for any exploration task: locating code, tracing dependencies, finding patterns, answering 'where is X' or 'who calls Y' questions. Read-only — never edits files."
+description: "MUST BE USED PROACTIVELY. Universal read-only explorer agent. Combines jrag graph navigation (call chains, service boundaries, routes, impact analysis, FQN resolution) with broad file-system search (grep, glob, excerpt reading). Use for any exploration task: locating code, tracing dependencies, finding patterns, answering 'where is X' or 'who calls Y' questions. Read-only — never edits files."
 ---
 
-You are a universal codebase explorer — a read-only search and navigation specialist that combines **graph-based structural analysis** (java-codebase-rag MCP) with **broad file-system search** (grep, glob, file reading).
+You are a universal codebase explorer — a read-only search and navigation specialist that combines **graph-based structural analysis** (jrag MCP) with **broad file-system search** (grep, glob, file reading).
 
 ## Core Principles
 
@@ -14,7 +14,7 @@ You are a universal codebase explorer — a read-only search and navigation spec
 
 ## Tool Inventory
 
-- **Graph (java-codebase-rag MCP):** `search`, `find`, `describe`, `neighbors`, `resolve`. Use for whole-codebase structural queries — callers/callees, route handlers, HTTP/async seams, clients/producers, service boundaries, impact analysis, FQN resolution, implementations, DI chains. Node kinds: `Symbol` (types/methods), `Route` (HTTP/messaging entry points), `Client` (outbound HTTP), `Producer` (outbound async). Indexed content: Java + SQL + YAML (`table`: `java`, `sql`, `yaml`, `all`). **Do NOT use** for specific known files, git history, test/build/CI files, or anything answerable from open context.
+- **Graph (jrag MCP):** `search`, `find`, `describe`, `neighbors`, `resolve`. Use for whole-codebase structural queries — callers/callees, route handlers, HTTP/async seams, clients/producers, service boundaries, impact analysis, FQN resolution, implementations, DI chains. Node kinds: `Symbol` (types/methods), `Route` (HTTP/messaging entry points), `Client` (outbound HTTP), `Producer` (outbound async). Indexed content: Java + SQL + YAML (`table`: `java`, `sql`, `yaml`, `all`). **Do NOT use** for specific known files, git history, test/build/CI files, or anything answerable from open context.
 - **File-system:** `Grep` (contents), `Glob` (name/path patterns), `Read` (files — `offset`/`limit` for large; excerpts over dumps). Use for text searches, file discovery, and any content outside the graph index (config, build, test, CI, docs).
 - **Other:** `Bash` (read-only: `git log`, `git blame`, `ls`, `find`), `WebSearch`, `WebFetch`.
 
@@ -45,7 +45,7 @@ You are a universal codebase explorer — a read-only search and navigation spec
 
 ---
 
-## Graph Navigation Reference (java-codebase-rag MCP)
+## Graph Navigation Reference (jrag MCP)
 
 ### Forced reasoning preamble (every MCP call)
 

java_codebase_rag/install_data/skills/explore-codebase/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: explore-codebase
-description: "MUST BE USED PROACTIVELY. Universal read-only codebase exploration. Combines java-codebase-rag graph navigation (call chains, routes, service boundaries, impact analysis, FQN resolution) with broad file-system search (grep, glob, file reading). Use for any exploration: locating code, tracing dependencies, finding patterns, 'where is X', 'who calls Y', 'find all controllers', 'trace the flow from A to B'. Do NOT use when the answer is already in open context or for a single known file — read that file directly."
+description: "MUST BE USED PROACTIVELY. Universal read-only codebase exploration. Combines jrag graph navigation (call chains, routes, service boundaries, impact analysis, FQN resolution) with broad file-system search (grep, glob, file reading). Use for any exploration: locating code, tracing dependencies, finding patterns, 'where is X', 'who calls Y', 'find all controllers', 'trace the flow from A to B'. Do NOT use when the answer is already in open context or for a single known file — read that file directly."
 ---
 
 # /explore-codebase — Universal codebase exploration
 
-Read-only exploration combining **java-codebase-rag graph navigation** with **broad file-system search**.
+Read-only exploration combining **jrag graph navigation** with **broad file-system search**.
 
 Use any time you must search, locate, navigate, or explore. **Do NOT use when** the answer is already in context or for a single known file — read it directly.
 
@@ -17,7 +17,7 @@ Use any time you must search, locate, navigate, or explore. **Do NOT use when**
 
 ## Tool Inventory
 
-- **Graph (java-codebase-rag MCP):** `search`, `find`, `describe`, `neighbors`, `resolve`. Node kinds: `Symbol` (types/methods), `Route` (HTTP/messaging entry points), `Client` (outbound HTTP), `Producer` (outbound async). Indexed content: Java + SQL + YAML (`table`: `java`, `sql`, `yaml`, `all`).
+- **Graph (jrag MCP):** `search`, `find`, `describe`, `neighbors`, `resolve`. Node kinds: `Symbol` (types/methods), `Route` (HTTP/messaging entry points), `Client` (outbound HTTP), `Producer` (outbound async). Indexed content: Java + SQL + YAML (`table`: `java`, `sql`, `yaml`, `all`).
 - **File-system:** `Grep` (content/regex), `Glob` (name/path patterns), `Read` (`offset`/`limit` for large files).
 - **Other:** `Bash` (read-only: `git log`, `git blame`, `ls`, `find`), `WebSearch`/`WebFetch`.
 
@@ -50,7 +50,7 @@ Use any time you must search, locate, navigate, or explore. **Do NOT use when**
 
 ---
 
-## Graph Navigation Reference (java-codebase-rag MCP)
+## Graph Navigation Reference (jrag MCP)
 
 **Ontology: 17.** If results look structurally wrong or empty across tools, the index may be missing/stale — ask the operator to rebuild. Responses may carry `hints_structured` (suggested next calls) and `advisories` — advisory only; ignore when `success` is false.
 

java_codebase_rag/install_data/skills/explore-codebase-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: explore-codebase-cli
-description: "MUST BE USED PROACTIVELY. Universal codebase exploration (CLI surface). Use for any exploration task: locating code, tracing dependencies, finding patterns, 'where is X', 'who calls Y', 'find all controllers', 'trace the flow from A to B'. Do NOT use when the answer is already in open context or for a single known file — read that file directly."
+description: "MUST BE USED PROACTIVELY. Universal JVM (Java + Kotlin) codebase exploration (CLI surface): graph navigation (`jrag` callers/callees/routes/impact/flow/…) plus `jrag search` (locate code/config by meaning or keywords) and file-system search. Use for any exploration task: locating code, tracing dependencies, finding patterns, 'where is X', 'who calls Y', 'find all controllers', 'trace the flow from A to B'. Do NOT use when the answer is already in open context or for a single known file — read that file directly."
 ---
 
 ## Core Principles
@@ -11,7 +11,7 @@ description: "MUST BE USED PROACTIVELY. Universal codebase exploration (CLI surf
 
 ## Tool Inventory
 
-- **Graph (`jrag` CLI):** one command per intent — `callers`, `callees`, `hierarchy`, `implementations`, `dependents`, `impact`, `flow`, `http-routes`, `http-clients`, `producers`, `topics`, `find`, `search`, `inspect`, `overview`, … Drives the same index as the MCP server. Fast path for structural questions: call chains, route handlers, HTTP/async seams, clients/producers, service boundaries, impact, FQN resolution, implementations, DI chains. Pass it names (FQN / simple name / route path / topic) — it resolves internally; raw node IDs are never required. Requires an index; if unindexed every command exits 2 (see **jrag surface**).
+- **`jrag` CLI — navigate & search:** one command per intent — graph navigation (`callers`, `callees`, `hierarchy`, `implementations`, `dependents`, `impact`, `flow`, `http-routes`, `http-clients`, `producers`, `topics`, `overview`), `search` (locate code or config by meaning, keywords, or natural language), and `find`/`inspect` (resolve identifiers; list nodes by role/kind). Drives the same index as the MCP server. Fast path for structural questions (call chains, route handlers, HTTP/async seams, clients/producers, service boundaries, impact, FQN resolution, implementations, DI chains) and fuzzy discovery alike. Pass it names (FQN / simple name / route path / topic) — it resolves internally; raw node IDs are never required. Requires an index; if unindexed every command exits 2 (see **jrag surface**).
 - **File-system:** `Grep` (content/regex), `Glob` (name/path patterns), `Read` (`offset`/`limit`). First-class for text searches, file discovery, and anything outside the graph index (config, build, test, CI, docs) — and the right answer whenever they're lighter than a `jrag` call.
 - **Other:** `Bash` (read-only: `git log`, `git blame`, `ls`, `find`), `WebSearch`/`WebFetch`.
 
@@ -51,7 +51,7 @@ description: "MUST BE USED PROACTIVELY. Universal codebase exploration (CLI surf
 
 **Escalation:** ① Most targeted tool first (identifier → `jrag inspect`; structural → matching `jrag` traversal; raw text / config / history → `Grep`/`Glob`/`Bash`). ② Fall back gracefully (`jrag` empty / `not_found` / exit 2 → `Grep`/`Glob`). ③ Cross-validate (`jrag` vs file disagree → **trust the file** — the index may be stale; report it).
 
-**Rules of thumb:** structure beats vector for exact questions (`jrag find`/`inspect` + traversal); vector beats structure for fuzzy discovery (`jrag search`); raw text / config / history beats both (`Grep`/`Glob`/`Bash`); file-system beats a stale index.
+**Rules of thumb:** structure beats search for exact questions (`jrag find`/`inspect` + traversal); search beats structure for fuzzy discovery (`jrag search`); raw text / config / history beats both (`Grep`/`Glob`/`Bash`); file-system beats a stale index.
 
 ---
 
@@ -70,13 +70,13 @@ description: "MUST BE USED PROACTIVELY. Universal codebase exploration (CLI surf
 
 | Symptom | Fix |
 | ------- | --- |
-| `status: error` "No index at …" | Run `java-codebase-rag init --source-root <root>`; retry |
+| `status: error` "No index at …" | Run `jrag init --source-root <root>`; retry |
 | `status: not_found` | `jrag search "<query>"`; or `find --fqn-contains …`; fallback `Grep` |
 | `many` candidates | Add `--kind`/`--role`/`--fqn-contains`/`--service`; re-run |
 | `find` too broad | Add `--service`, `--fqn-contains`, `--path-contains`, `--topic-contains` |
 | Empty `search` | Try `--table all`; `find --fqn-contains`; `Grep` |
 | `truncated: true` | Narrow, or page with `--offset` (`find`/`search` only) |
-| Empty across commands | Index missing/stale → `Grep`/`Glob`/`Read`; ask operator to rebuild (`java-codebase-rag reprocess`) |
+| Empty across commands | Index missing/stale → `Grep`/`Glob`/`Read`; ask operator to rebuild (`jrag reprocess`) |
 | CLI vs file disagree | **Trust the file**; report stale index |
 | `--offset` rejected | Only `find`/`search` accept it; others narrow via filters |
 | Wrong node picked | Resolve ambiguous — pass `--kind` |

java_codebase_rag/installer.py

@@ -1,4 +1,4 @@
-"""Interactive installer module for java-codebase-rag.
+"""Interactive installer module for jrag.
 
 This module provides the `install` subcommand that walks users through:
 1. Java source detection
@@ -605,13 +605,13 @@ def resolve_mcp_command(*, non_interactive: bool, surface: Surface = "mcp") -> s
         print(f"Error: `{display_name}` not found on PATH.")
         if surface == "mcp":
             print(
-                "Ensure `java-codebase-rag` is installed, then re-run with "
+                "Ensure `jrag` is installed, then re-run with "
                 "`--non-interactive --agent <host>`."
             )
         else:
             print(
-                "Ensure `java-codebase-rag` is installed (provides the `jrag` "
-                "console script), then re-run with `--non-interactive --agent <host>`."
+                "Ensure the `jrag` console script is installed, "
+                "then re-run with `--non-interactive --agent <host>`."
             )
         raise SystemExit(2)
 
@@ -982,7 +982,7 @@ def update_gitignore(cwd: Path) -> None:
 
     if not already_present:
         lines.append("")
-        lines.append("# java-codebase-rag index directory")
+        lines.append("# jrag index directory")
         lines.append(".java-codebase-rag/")
         gitignore_path.write_text("\n".join(lines), encoding="utf-8")
 
@@ -998,7 +998,7 @@ def _index_progress_header(subcommand: str, source_root: Path, index_dir: Path)
 
     print(
         bold(
-            f"java-codebase-rag {subcommand} · source={source_root.resolve()} "
+            f"jrag {subcommand} · source={source_root.resolve()} "
             f"· index={index_dir.resolve()}"
         ),
         file=sys.stderr,
@@ -1013,7 +1013,7 @@ def _index_progress_footer(subcommand: str, started: float, *, ok: bool) -> None
     elapsed = time.perf_counter() - started
     marker = styled_check() if ok else styled_cross()
     print(
-        f"{marker} {bold(f'java-codebase-rag {subcommand} · finished in {elapsed:.2f}s')}",
+        f"{marker} {bold(f'jrag {subcommand} · finished in {elapsed:.2f}s')}",
         file=sys.stderr,
         flush=True,
     )
@@ -1061,7 +1061,7 @@ def run_init_if_needed(
 
     has_existing, _ = index_dir_has_existing_artifacts(index_dir)
     if has_existing:
-        print("Index already exists. Run `java-codebase-rag reprocess` to rebuild.")
+        print("Index already exists. Run `jrag reprocess` to rebuild.")
         return None  # skipped, not failed
 
     cfg = resolve_operator_config(
@@ -1109,7 +1109,7 @@ def run_init_if_needed(
         else:
             if vectors_skipped:
                 print(
-                    "java-codebase-rag: vectors skipped — vector stack not installed on this "
+                    "jrag: vectors skipped — vector stack not installed on this "
                     "platform (graph-only mode). Building graph only; semantic search is unavailable.",
                     file=sys.stderr,
                 )
@@ -1750,7 +1750,7 @@ def run_update(
 
     if not configured_hosts:
         print("No configured agent hosts found.")
-        print("Run `java-codebase-rag install` first.")
+        print("Run `jrag install` first.")
         return EXIT_FATAL
 
     print(f"Found {len(configured_hosts)} configured host(s).")
@@ -1800,7 +1800,7 @@ def run_update(
                 f"'{chosen_surface}' surface."
             )
             print(
-                "Ensure `java-codebase-rag` is installed, then re-run `update "
+                "Ensure `jrag` is installed, then re-run `update "
                 f"--surface {chosen_surface}`."
             )
             return EXIT_PARTIAL
@@ -1907,11 +1907,11 @@ def run_update(
 
     if not index_exists:
         print("\nNo index found.")
-        print("Run `java-codebase-rag install` to create one.")
+        print("Run `jrag install` to create one.")
         return EXIT_PARTIAL if has_artifact_failures else EXIT_SUCCESS
 
     # Run increment: LanceDB catch-up + incremental graph rebuild.
-    # Mirrors `java-codebase-rag increment` so both index layers stay current.
+    # Mirrors `jrag increment` so both index layers stay current.
     # The "graph not implemented" warning belongs only on the vectors-only path
     # (increment --vectors-only), where the graph step is deliberately skipped.
     if not dry_run:
@@ -1955,7 +1955,7 @@ def run_update(
             else:
                 if vectors_skipped:
                     print(
-                        "java-codebase-rag: vectors skipped — vector stack not installed on this "
+                        "jrag: vectors skipped — vector stack not installed on this "
                         "platform (graph-only mode). Running graph catch-up only.",
                         file=sys.stderr,
                     )
@@ -1977,7 +1977,7 @@ def run_update(
                     # check + the Warning line carrying the graph caveat.
                     print(
                         f"\nWarning: incremental graph update failed (exit {g.returncode}). "
-                        "Run `java-codebase-rag reprocess` for a full rebuild.",
+                        "Run `jrag reprocess` for a full rebuild.",
                         file=sys.stderr,
                     )
         except BaseException:

java_codebase_rag/jrag.py

@@ -1095,8 +1095,9 @@ def build_parser() -> argparse.ArgumentParser:
         help="List imports declared in a file (tree-sitter parse + resolve_v2).",
         parents=[_common_parser()],
         description=(
-            "Parse <file> with tree-sitter (ast_java.parse_java), walk its "
-            "import_declaration nodes, and resolve each imported FQN via resolve_v2 "
+            "Parse <file> with tree-sitter via the language backend "
+            "(backend_for(...).parse — parse_java for .java, parse_kotlin for "
+            ".kt), walk its import nodes, and resolve each imported FQN via resolve_v2 "
             "against the graph. Returns one node per import: resolved graph Symbol "
             "when resolve_v2 hits, or an unresolved placeholder carrying the raw FQN "
             "otherwise. Static and wildcard imports are included (marked in the row)."
@@ -1355,7 +1356,7 @@ def _load_graph(cfg):  # type: ignore[no-untyped-def]
     """Load the LadybugGraph with actionable error envelopes.
 
     * missing index -> ``_IndexNotFound`` (caught in ``main`` -> envelope with
-      a ``java-codebase-rag init --source-root <root>`` remediation).
+      a ``jrag init --source-root <root>`` remediation).
     * ontology-mismatch (``RuntimeError`` from ``LadybugGraph.get``) ->
       ``_IndexStale`` (caught in ``main`` -> envelope with a rebuild hint).
     """
@@ -1365,7 +1366,7 @@ def _load_graph(cfg):  # type: ignore[no-untyped-def]
     if not LadybugGraph.exists(ladybug_path):
         raise _IndexNotFound(
             f"No index at {cfg.ladybug_path}. "
-            "Run: java-codebase-rag init --source-root <root>"
+            "Run: jrag init --source-root <root>"
         )
     try:
         return LadybugGraph.get(ladybug_path)
@@ -3604,12 +3605,13 @@ def _cmd_imports(args: argparse.Namespace) -> int:
     """imports <file> — tree-sitter parse + resolve_v2 per imported FQN.
 
     Reads <file> from disk (cfg.source_root / <file> for relative paths),
-    parses with ast_java.parse_java, walks explicit_imports (dict: simple_name
+    parses via the language backend (backend_for(...).parse — parse_java for
+    .java, parse_kotlin for .kt), walks explicit_imports (dict: simple_name
     -> FQN), then resolves each FQN via resolve_v2 against the graph. Returns
     a node per import: resolved graph Symbol when resolve_v2 hits (status=one),
     or an unresolved placeholder carrying the raw FQN otherwise.
     """
-    from java_codebase_rag.ast.ast_java import parse_java
+    from java_codebase_rag.ast.language import backend_for
     from java_codebase_rag.analysis.resolve_service import resolve_v2
 
     from java_codebase_rag.jrag_envelope import Envelope, next_actions_hook
@@ -3638,14 +3640,26 @@ def _cmd_imports(args: argparse.Namespace) -> int:
         print(render(env, fmt=args.format, detail=args.detail))
         return 2
 
-    # parse_java is robust to invalid source (returns an empty JavaFileAst on
-    # parse errors, never raises). It builds imports from the
-    # `import_declaration` tree-sitter nodes via `_import_declaration_is_static`
-    # (ast_java.py:905) and the scoped_identifier child walk (ast_java.py:2658).
+    # The backend parse (backend_for(...).parse — parse_java / parse_kotlin)
+    # is robust to invalid source (returns an empty JavaFileAst on parse
+    # errors, never raises). It builds imports from the `import_declaration`
+    # tree-sitter nodes (Java path: `_import_declaration_is_static` at
+    # ast_java.py:905 and the scoped_identifier child walk at ast_java.py:2658).
     # explicit_imports: dict[str, str] = simple_name -> FQN (non-wildcard,
     # non-static); we also surface wildcard/static imports as unresolved rows so
     # the agent sees the full import block.
-    ast = parse_java(src, filename=args.file)
+    backend = backend_for(args.file)
+    if backend is None:
+        env = Envelope(
+            status="error",
+            message=(
+                f"no language backend registered for {args.file!r} "
+                f"(suffix {Path(args.file).suffix!r} not in registry)"
+            ),
+        )
+        print(render(env, fmt=args.format, detail=args.detail))
+        return 2
+    ast = backend.parse(src, filename=args.file)
     nodes: dict[str, dict] = {}
     edges: list[dict] = []
     warnings: list[str] = []

java_codebase_rag/lance_optimize.py

@@ -139,7 +139,7 @@ async def optimize_lance_tables(
                 existing = await _list_table_names(db)
             except Exception as exc:
                 print(
-                    f"java-codebase-rag: optimize: failed to list tables in "
+                    f"jrag: optimize: failed to list tables in "
                     f"{index_dir}: {exc}",
                     file=sys.stderr,
                 )
@@ -151,7 +151,7 @@ async def optimize_lance_tables(
                     results[name] = "skipped"
                     if not quiet:
                         print(
-                            f"java-codebase-rag: optimize: {name} absent, skipped",
+                            f"jrag: optimize: {name} absent, skipped",
                             file=sys.stderr,
                         )
                     continue
@@ -161,7 +161,7 @@ async def optimize_lance_tables(
                     results[name] = f"error: open failed: {exc}"
                     failed = True
                     print(
-                        f"java-codebase-rag: optimize: {name} open failed: {exc}",
+                        f"jrag: optimize: {name} open failed: {exc}",
                         file=sys.stderr,
                     )
                     continue
@@ -205,7 +205,7 @@ async def optimize_lance_tables(
                             w in low for w in ("exist", "duplicate", "already", "same name")
                         ) and not quiet:
                             print(
-                                f"java-codebase-rag: optimize: {name} id-index skipped: {exc}",
+                                f"jrag: optimize: {name} id-index skipped: {exc}",
                                 file=sys.stderr,
                             )
                     # Best-effort FTS index at index time (PR-SEARCH-3) so hybrid
@@ -223,19 +223,19 @@ async def optimize_lance_tables(
                             w in low for w in ("exist", "duplicate", "already", "same name")
                         ) and not quiet:
                             print(
-                                f"java-codebase-rag: optimize: {name} fts skipped: {exc}",
+                                f"jrag: optimize: {name} fts skipped: {exc}",
                                 file=sys.stderr,
                             )
                     if not quiet:
                         print(
-                            f"java-codebase-rag: optimize: {name} ok",
+                            f"jrag: optimize: {name} ok",
                             file=sys.stderr,
                         )
                 else:
                     results[name] = f"error: {last_exc}"
                     failed = True
                     print(
-                        f"java-codebase-rag: optimize: {name} failed: {last_exc}",
+                        f"jrag: optimize: {name} failed: {last_exc}",
                         file=sys.stderr,
                     )
         finally:

java_codebase_rag/mcp/mcp_v2.py

@@ -1265,7 +1265,7 @@ def find_v2(
 _DESCRIBE_UCS_ID_MESSAGE = (
     "UnresolvedCallSite ids (ucs:…) are not describable — use describe(caller_method_id) "
     "for record.data.unresolved_call_sites, neighbors(..., include_unresolved=True), "
-    "or java-codebase-rag unresolved-calls list --method-id <caller_id>"
+    "or jrag unresolved-calls list --method-id <caller_id>"
 )
 
 
@@ -1363,7 +1363,7 @@ def describe_v2(
                 if total > len(inline):
                     data["unresolved_call_sites_footer"] = (
                         f"{total} unresolved call sites — see "
-                        f"java-codebase-rag unresolved-calls list --method-id {node_id} for the full list"
+                        f"jrag unresolved-calls list --method-id {node_id} for the full list"
                     )
         record = NodeRecord(id=ref.id, kind=kind, fqn=ref.fqn, data=data, edge_summary=edge_summary)
         raw_struct, raw_advisories = _hints_or_skip("describe", {"success": True, "record": record.model_dump()})

java_codebase_rag/mcp/server.py

@@ -9,6 +9,7 @@ import time
 from pathlib import Path
 from typing import Literal
 
+from java_codebase_rag._deprecation import maybe_warn_legacy_alias
 from java_codebase_rag.mcp import mcp_v2
 from java_codebase_rag.analysis import resolve_service
 from java_codebase_rag.search.index_common import SBERT_MODEL
@@ -52,7 +53,7 @@ _INSTRUCTIONS = (
     "Successful responses from any tool may include `hints_structured` (tool call suggestions with a `reason` field) and `advisories` (pure informational text) when hints are enabled. "
     "Edge labels: EXTENDS, IMPLEMENTS, INJECTS, OVERRIDES, DECLARES, DECLARES_CLIENT, DECLARES_PRODUCER, CALLS, EXPOSES, HTTP_CALLS, ASYNC_CALLS; "
     "type Symbols may also use composed neighbors edge_types DECLARES.DECLARES_CLIENT, DECLARES.DECLARES_PRODUCER, DECLARES.EXPOSES (out only, type Symbol origin). "
-    "Reprocess/init, meta, tables, diagnose-ignore, analyze-pr: use java-codebase-rag CLI — not MCP."
+    "Reprocess/init, meta, tables, diagnose-ignore, analyze-pr: use jrag CLI — not MCP."
 )
 
 
@@ -249,7 +250,7 @@ def _graph_meta_output() -> GraphMetaOutput:
             success=True,
             enabled=False,
             db_path=resolve_ladybug_path(),
-            message="Ladybug graph not present; run java-codebase-rag reprocess or build_ast_graph.py",
+            message="Ladybug graph not present; run jrag reprocess or build_ast_graph.py",
         )
     try:
         graph = LadybugGraph.get()
@@ -480,7 +481,7 @@ async def run_refresh_pipeline(
         await drop_proc.communicate()
     except Exception as exc:
         print(
-            f"java-codebase-rag: drop-before-reprocess failed ({exc!s}); "
+            f"jrag: drop-before-reprocess failed ({exc!s}); "
             "falling back to in-place update",
             file=sys.stderr,
         )
@@ -575,7 +576,7 @@ async def run_refresh_pipeline(
             await optimize_lance_tables(idx_dir, quiet=quiet, on_progress=on_progress)
         except Exception as exc:
             optimize_error = f"lance optimize failed: {exc}"
-            print(f"java-codebase-rag: {optimize_error}", file=sys.stderr)
+            print(f"jrag: {optimize_error}", file=sys.stderr)
         graph_code, graph_out, graph_err, graph_started = await _run_graph_phase(
             root, quiet=quiet, verbose=verbose,
             on_progress=on_progress, on_progress_console=on_progress_console,
@@ -861,6 +862,7 @@ def create_mcp_server() -> FastMCP:
 
 
 def main() -> None:
+    maybe_warn_legacy_alias()
     raise_fd_limit()
     emit_legacy_env_hints_if_present()
 

java_codebase_rag/pipeline.py

@@ -24,7 +24,7 @@ COCOINDEX_TARGET = "java_index_flow_lancedb.py:JavaCodeIndexLance"
 # Single source of truth — imported by cli.py (init/increment) and server.py
 # (reprocess) so the wording can't drift between the two paths.
 VECTORS_SKIPPED_GRAPH_ONLY = (
-    "java-codebase-rag: vectors skipped — vector stack not installed on this platform "
+    "jrag: vectors skipped — vector stack not installed on this platform "
     "(graph-only mode). The graph is built/refreshed; semantic search is unavailable."
 )
 
@@ -212,7 +212,7 @@ def run_cocoindex_update(
         drop = run_cocoindex_drop(env, quiet=quiet)
         if drop.returncode != 0 and not is_cocoindex_preflight_blocker(drop):
             print(
-                "java-codebase-rag: drop-before-reprocess failed "
+                "jrag: drop-before-reprocess failed "
                 f"(exit {drop.returncode}); falling back to in-place update: "
                 f"{(drop.stderr or '').strip()[:200]}",
                 file=sys.stderr,
@@ -252,7 +252,7 @@ def _maybe_run_serialized_optimize(
     idx_raw = env.get("JAVA_CODEBASE_RAG_INDEX_DIR", "").strip()
     if not idx_raw:
         print(
-            "java-codebase-rag: optimize skipped — JAVA_CODEBASE_RAG_INDEX_DIR "
+            "jrag: optimize skipped — JAVA_CODEBASE_RAG_INDEX_DIR "
             "not set in subprocess env",
             file=sys.stderr,
         )
@@ -263,7 +263,7 @@ def _maybe_run_serialized_optimize(
         asyncio.run(optimize_lance_tables(Path(idx_raw), quiet=quiet, on_progress=on_progress))
     except Exception as exc:
         # Never crash the CLI on an optimize failure — surface on stderr only.
-        print(f"java-codebase-rag: optimize failed: {exc}", file=sys.stderr)
+        print(f"jrag: optimize failed: {exc}", file=sys.stderr)
 
 
 def is_cocoindex_preflight_blocker(proc: subprocess.CompletedProcess[str]) -> bool:

java_codebase_rag/progress.py

@@ -531,7 +531,7 @@ class ProgressRelay:
                 self._renderer.apply(ev)
             except Exception as exc:
                 sys.stderr.write(
-                    f"java-codebase-rag: progress renderer error: {exc}\n"
+                    f"jrag: progress renderer error: {exc}\n"
                 )
                 sys.stderr.flush()
             return

java_codebase_rag/search/search_lexical.py

@@ -300,7 +300,7 @@ def run_lexical_search(
     if graph is None and not LadybugGraph.exists():
         raise RuntimeError(
             "lexical search unavailable: no symbol graph found; "
-            "run `java-codebase-rag init` or `java-codebase-rag reprocess` to build one"
+            "run `jrag init` or `jrag reprocess` to build one"
         )
     g = graph or LadybugGraph.get()
 

java_codebase_rag/search/search_scoring.py

@@ -37,7 +37,7 @@ _SYMBOL_MATCH_BONUS_CAP = 0.06
 
 # Action verbs that typically mark behavioural entry points in this codebase.
 # A chunk whose symbols begin with one of these verbs earns a small flat bump
-# — again only for java chunks and only when role-filtering is off.
+# — again only for JVM (Java/Kotlin) chunks and only when role-filtering is off.
 _ACTION_VERB_PREFIXES: tuple[str, ...] = (
     "process", "handle", "on", "pick", "select", "assign",
     "notify", "dispatch", "publish", "consume", "route",
@@ -64,7 +64,7 @@ _STOPWORDS: frozenset[str] = frozenset({
     "may", "might", "happens", "happen", "happened", "get", "gets", "got",
 })
 
-# Role-aware reweighting for Java chunks. Positive values favour actionable
+# Role-aware reweighting for Java/Kotlin chunks. Positive values favour actionable
 # behavioural code (entrypoints, orchestrators, integrations) over configuration,
 # schema, and persistence stubs for "what happens when..."-style queries.
 # Applied to the similarity score (higher = better); distance-based sort subtracts
@@ -236,13 +236,27 @@ def build_fts_query(text: str) -> str:
     return " ".join(out)
 
 
+def _is_jvm_row(r: dict) -> bool:
+    """True when a row is Java or Kotlin source (both indexed in the java table).
+
+    The additive role/bonus weighting applies to both JVM languages. Kotlin
+    chunks live in the java LanceDB table (``_kind == "java"``), but we key off
+    the semantic ``language`` field when present so detection is robust to the
+    row's table-key and any future language-keyed table split.
+    """
+    lang = str(r.get("language") or "").lower()
+    if lang in ("java", "kotlin"):
+        return True
+    return str(r.get("_kind", "")) == "java"
+
+
 def _symbol_bonus(r: dict, query_toks: set[str]) -> float:
-    """Symbol-name overlap + action-verb bump for java chunks.
+    """Symbol-name overlap + action-verb bump for Java/Kotlin chunks.
 
     Caps at `_SYMBOL_MATCH_BONUS_CAP + _ACTION_VERB_BONUS` to avoid runaway
     ranks on chunks declaring many symbols.
     """
-    if str(r.get("_kind", "")) != "java":
+    if not _is_jvm_row(r):
         return 0.0
     raw = r.get("symbols") or []
     if isinstance(raw, str):
@@ -289,7 +303,7 @@ def _role_weight(r: dict) -> float:
     cached = comps.get("role_weight")
     if cached is not None:
         return float(cached)
-    if r.get("_skip_role_weight") or str(r.get("_kind", "")) != "java":
+    if r.get("_skip_role_weight") or not _is_jvm_row(r):
         comps["role_weight"] = 0.0
         return 0.0
     role = (r.get("role") or "").upper()

java_codebase_rag/watch/lock.py

@@ -2,7 +2,7 @@
 
 ``ProjectLock`` is the single-writer primitive the watch daemon (Task 11)
 acquires so that at most one watcher — and no concurrent manual
-``java-codebase-rag increment`` — runs per project.
+``jrag increment`` — runs per project.
 
 The lock is keyed on the project's index dir: the pidfile path comes from
 ``paths.pid_path(index_dir)`` (Task 3). We hold an advisory exclusive flock on