java-codebase-rag 0.6.6__tar.gz → 0.8.0__tar.gz

{java_codebase_rag-0.6.6/java_codebase_rag.egg-info → java_codebase_rag-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.6.6
+Version: 0.8.0
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -15,12 +15,15 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: cocoindex[lancedb]<2,>=1.0.0a43
+Requires-Dist: cocoindex[lancedb]<2,>=1.0.7; sys_platform != "darwin" or platform_machine != "x86_64"
 Requires-Dist: ladybug<0.18,>=0.17.1
-Requires-Dist: lancedb<0.31,>=0.25.3
+Requires-Dist: lancedb<0.31,>=0.25.3; 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
@@ -29,7 +32,7 @@ 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: sentence-transformers<6,>=5.4.0
+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
@@ -42,9 +45,9 @@ Dynamic: license-file
 
 # java-codebase-rag
 
-A graph-native code intelligence layer for Java microservice estates, exposed to LLM agents via the **Model Context Protocol (MCP)**.
+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.
 
-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**.
+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.
 > Agents use a simple loop:
@@ -73,7 +76,7 @@ Generic code-search tools (grep, ctags, vector-only RAG) hit a ceiling on real J
 
 - **Brownfield annotations as a first-class override.** Real Java estates have hand-rolled HTTP clients, dynamic topic names, reflection-heavy routing. `@CodebaseHttpRoute`, `@CodebaseAsyncRoute`, `@CodebaseHttpClient`, and `@CodebaseProducer` let you pin the truth in source. They have **exclusive priority** — when a symbol is annotated, framework-convention inference is skipped entirely. You get a correct graph on legacy code without rewriting it.
 
-The rest of this README is the install, walkthrough, and tool cheat sheet for putting that to work.
+The rest of this README is the install, the tool/command orientation, and the reference for putting that to work.
 
 ---
 
@@ -83,8 +86,8 @@ The rest of this README is the install, walkthrough, and tool cheat sheet for pu
 pip install java-codebase-rag
 ```
 
-Python **3.11+** required. 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`.
+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` (semantic) tool reports it is unavailable rather than failing. 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)
 
@@ -117,89 +120,11 @@ If you prefer manual configuration, see [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs
 
 ---
 
-## 5-minute walkthrough — index this repo's bank-chat fixture
+## Tools & commands at a glance
 
-This repo ships a small multi-module Spring fixture under [`tests/bank-chat-system/`](./tests/bank-chat-system/) (`chat-core` + `chat-assign`) that the test suite uses for calibration. You can index it and confirm the install works end-to-end in under five minutes — no agent host required.
+Pick a surface once at install time — `java-codebase-rag install --surface mcp|cli` (default `mcp`). Both surfaces walk the same LanceDB vectors + LadybugDB graph.
 
-```bash
-# 1. Clone the repo to get the fixture (the published package doesn't include tests/)
-git clone https://github.com/HumanBean17/java-codebase-rag
-cd java-codebase-rag
-
-# 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
-
-# 3. Inspect what landed (resolved config, edge counts, ontology version)
-java-codebase-rag meta --source-root tests/bank-chat-system --index-dir /tmp/bank-chat-index
-```
-
-Smoke-test the index with two checks (`search_lancedb` ships with the package):
-
-```bash
-# Vector search — proves the LanceDB side works
-JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
-  python -m search_lancedb "chat ingress controller" --table java --limit 3
-
-# 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
-```
-
-If vector hits come back and graph expansion adds neighbor symbols, the install works end-to-end. Wire it into your agent next — the five MCP tools (`search`, `find`, `describe`, `neighbors`, `resolve`) are reachable over stdio.
-
----
-
-## Wire into an MCP host
-
-> **Quick setup:** Run `java-codebase-rag install` from your Java project root. The interactive wizard handles MCP registration, skill deployment, and configuration for Claude Code, Qwen Code, and GigaCode in one step.
-
-### Claude Code (manual)
-
-With the package installed, the console script `java-codebase-rag-mcp` is on your `PATH`. Register it project-scoped:
-
-```bash
-claude mcp add --transport stdio java-codebase-rag -- java-codebase-rag-mcp
-```
-
-**Zero-env-var configuration:** The tool automatically walks up the directory tree to find `.java-codebase-rag.yml`, so you don't need to set `JAVA_CODEBASE_RAG_SOURCE_ROOT` when working from within a project. Just place the config file at your project root and the tool will find it. See [`mcp.json.example`](./mcp.json.example) for the minimal configuration.
-
-If you need to override defaults, you can set env vars (`JAVA_CODEBASE_RAG_INDEX_DIR`, `JAVA_CODEBASE_RAG_SOURCE_ROOT`, `SBERT_MODEL`, …) in `.mcp.json` or your shell profile. For a full configuration template, see [`mcp.json.example`](./mcp.json.example). Official docs: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings).
-
-### Claude Desktop
-
-Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`) and add under `mcpServers`:
-
-```json
-{
-  "mcpServers": {
-    "java-codebase-rag": {
-      "command": "java-codebase-rag-mcp",
-      "env": {
-        "JAVA_CODEBASE_RAG_INDEX_DIR": "/ABSOLUTE/PATH/TO/.java-codebase-rag",
-        "JAVA_CODEBASE_RAG_SOURCE_ROOT": "/ABSOLUTE/PATH/TO/your-java-project"
-      }
-    }
-  }
-}
-```
-
-See [`mcp.json.example`](./mcp.json.example) for the same shape in `.mcp.json` (Claude Code project-scoped) form.
-
-### Driving the MCP from an agent
-
-Pick **one** of two options (not both — they cover the same navigation intents):
-
-1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and navigation patterns. Self-contained — no external file dependencies.
-
-2. **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** (for hosts with skill discovery) — single self-contained skill with the complete operating manual. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), load `/explore-codebase` to get the full tool reference, edge taxonomy, decision tree, and recovery playbook in one shot.
-
-Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md)** — 7-phase agent-driven verification you run after indexing your real project.
-
----
-
-## The five tools, at a glance
+**MCP surface — five tools over stdio**
 
 | Tool | Purpose | Required args |
 |---|---|---|
@@ -211,9 +136,63 @@ Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHE
 
 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).
 
+**CLI surface — `jrag`, one command per engineering intent**
+
+```bash
+# Orientation
+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 conventions               # dominant roles + framework tallies
+jrag overview chat-core        # bundle for a microservice
+jrag overview /chat/assign     # route flow (inbound callers + outbound CALLS)
+jrag overview banking.chat     # topic producers + consumers
+jrag overview chat-core --as microservice  # override auto-detection
+
+# Locate
+jrag find ChatService          # exact name/FQN lookup (symbols)
+jrag find --role CONTROLLER    # filter mode (NodeFilter flags)
+jrag inspect ChatService       # full node details + edge_summary
+jrag outline src/main/.../Foo.java  # all symbols declared in a file
+jrag imports src/main/.../Foo.java   # imports resolved to graph nodes
+
+# Listings
+jrag http-routes               # HTTP routes
+jrag http-clients              # HTTP clients (Feign / RestTemplate / WebClient)
+jrag producers                 # async message producers (Kafka / StreamBridge)
+jrag topics                    # message topics grouped by producer
+jrag jobs                      # scheduled tasks (@Scheduled)
+jrag listeners                 # message listeners (@KafkaListener etc.)
+jrag entities                  # JPA entities
+
+# Traversals (all resolve-first)
+jrag callers ChatService#assign(Request)   # who calls me?
+jrag callees ChatService#assign(Request)   # what do I call?
+jrag hierarchy AbstractBase               # type tree (parents + children)
+jrag implementations PaymentProcessor     # classes implementing an interface
+jrag subclasses AbstractRepository        # classes extending a type
+jrag overrides Impl#run()                 # methods this overrides (dispatch UP)
+jrag overridden-by Iface#run()            # methods overriding this (dispatch DOWN)
+jrag dependents PaymentGateway            # who injects this type?
+jrag dependencies ChatService             # types this injects
+jrag impact PaymentGateway                # fleet-wide blast radius
+jrag decompose ChatIngressController#assign   # role-waterfall flow
+jrag flow /chat/assign                    # request flow through a route
+jrag connection chat-core                 # cross-service connections
+
+# Semantic search
+jrag search "assign a chat agent"         # semantic over Lance (java table)
+jrag search "kafka" --table all           # java + sql + yaml tables
+jrag search "audit" --hybrid              # vector + keyword hybrid
+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.
+
 ### Three-layer architecture
 
-Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skill). The [`/explore-codebase`](./skills/explore-codebase/SKILL.md) skill provides the full operating manual for Layer 2. See the [architecture diagram in `skills/README.md`](./skills/README.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).
 
 ---
 
@@ -249,6 +228,71 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 
 ---
 
+## jrag — agent CLI
+
+`jrag` is a separate console script (alongside `java-codebase-rag`) built for AI
+coding agents. It gives the agent **one command per engineering intent** and
+takes human-readable identifiers (FQN / simple name / route path / topic) —
+never raw node IDs. Every `<query>` command resolves the identifier via
+`resolve_v2` as the first step; on `many` it returns candidates and stops, on
+`none` it returns `not_found`. Auto-pick is forbidden.
+
+The default output is compact text (a deliberate divergence from the operator
+CLI's TTY heuristic — `jrag` is agent-facing/non-TTY). `--format json` emits the
+shared envelope verbatim. Every command emits the same envelope shape:
+
+```json
+{
+  "status": "ok",
+  "nodes": {"com.example.Foo": {"kind": "symbol", "fqn": "com.example.Foo"}},
+  "edges": [{"edge_type": "CALLS", "confidence": 0.9, "target": "com.example.Bar#baz()"}],
+  "root": "com.example.Foo",
+  "agent_next_actions": ["jrag callees com.example.Foo#bar()"],
+  "truncated": false
+}
+```
+
+No raw graph node id ever appears on either surface: `nodes` is keyed by each
+node's natural identifier (FQN for symbols, `METHOD path` for routes,
+`member_fqn->target` for clients, `topic:<name>` for topics), `root` is the
+root's natural identifier, and each edge carries `target` (the referenced node's
+identifier) instead of a graph id. The agent reuses these identifiers directly
+as the next command's `<query>` — there is nothing else to pass.
+
+`agent_next_actions` carries up to 5 contextual next-step hints (e.g. after
+`inspect`, the agent sees `jrag callers <fqn>`, `jrag callees <fqn>`, etc. for
+the edges the root actually has). Omitted from JSON when empty.
+
+The full command catalog lives in [Tools & commands at a glance](#tools--commands-at-a-glance).
+
+### Flags
+
+| Flag | Scope | Effect |
+|------|-------|--------|
+| `--format text\|json` | all | output format (default: text) |
+| `--service <name>` | listings/traversals | filter by microservice |
+| `--module <name>` | listings/traversals | filter by module |
+| `--limit <n>` | listings/traversals | cap results (default 20; `limit+1` fetch detects truncation) |
+| `--offset <n>` | `find`, `search` only | paginate (other commands reject it) |
+| `--kind symbol\|route\|client\|producer` | `<query>` commands | resolve hint |
+| `--java-kind`, `--role`, `--fqn-contains` | `<query>` commands | client-side post-filters |
+| `--index-dir <path>` | all | override index directory |
+
+`--offset` is intentionally NOT a global flag: only `find` and `search` route
+through backends that accept it. Every other command rejects it.
+
+A missing or stale index produces an actionable `status: error` envelope (exit
+2) rather than a traceback:
+
+```
+error: No index at /path/to/code_graph.lbug. Run: java-codebase-rag init --source-root <root>
+```
+
+See [`plans/active/PLAN-JRAG-CLI.md`](./plans/active/PLAN-JRAG-CLI.md) for the
+full design and per-PR breakdown.
+
+---
+
 ## Further reading
 
 | Document | What's in it |
@@ -258,10 +302,9 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 | [`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/) | Single `/explore-codebase` skill — complete MCP operating manual for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
+| [`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). |
 | [`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. |
-| [`automation/cursor_propose_only/README.md`](./automation/cursor_propose_only/README.md) | Optional proposal orchestration workflow (single-command autopilot, planning bundles, automated execution/review loops). |
 | [`docs/PRODUCT-VISION.md`](./docs/PRODUCT-VISION.md) | Long-term product direction. |
 
 ---
@@ -272,7 +315,7 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 git clone https://github.com/HumanBean17/java-codebase-rag
 cd java-codebase-rag
 python3 -m venv .venv
-.venv/bin/pip install -r requirements.txt
+.venv/bin/pip install -e ".[dev]"
 ```
 
 The `cocoindex` package powers lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation do not invoke it directly.

{java_codebase_rag-0.6.6 → java_codebase_rag-0.8.0}/README.md

@@ -1,8 +1,8 @@
 # java-codebase-rag
 
-A graph-native code intelligence layer for Java microservice estates, exposed to LLM agents via the **Model Context Protocol (MCP)**.
+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.
 
-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**.
+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.
 > Agents use a simple loop:
@@ -31,7 +31,7 @@ Generic code-search tools (grep, ctags, vector-only RAG) hit a ceiling on real J
 
 - **Brownfield annotations as a first-class override.** Real Java estates have hand-rolled HTTP clients, dynamic topic names, reflection-heavy routing. `@CodebaseHttpRoute`, `@CodebaseAsyncRoute`, `@CodebaseHttpClient`, and `@CodebaseProducer` let you pin the truth in source. They have **exclusive priority** — when a symbol is annotated, framework-convention inference is skipped entirely. You get a correct graph on legacy code without rewriting it.
 
-The rest of this README is the install, walkthrough, and tool cheat sheet for putting that to work.
+The rest of this README is the install, the tool/command orientation, and the reference for putting that to work.
 
 ---
 
@@ -41,8 +41,8 @@ The rest of this README is the install, walkthrough, and tool cheat sheet for pu
 pip install java-codebase-rag
 ```
 
-Python **3.11+** required. 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`.
+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` (semantic) tool reports it is unavailable rather than failing. 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)
 
@@ -75,89 +75,11 @@ If you prefer manual configuration, see [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs
 
 ---
 
-## 5-minute walkthrough — index this repo's bank-chat fixture
+## Tools & commands at a glance
 
-This repo ships a small multi-module Spring fixture under [`tests/bank-chat-system/`](./tests/bank-chat-system/) (`chat-core` + `chat-assign`) that the test suite uses for calibration. You can index it and confirm the install works end-to-end in under five minutes — no agent host required.
+Pick a surface once at install time — `java-codebase-rag install --surface mcp|cli` (default `mcp`). Both surfaces walk the same LanceDB vectors + LadybugDB graph.
 
-```bash
-# 1. Clone the repo to get the fixture (the published package doesn't include tests/)
-git clone https://github.com/HumanBean17/java-codebase-rag
-cd java-codebase-rag
-
-# 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
-
-# 3. Inspect what landed (resolved config, edge counts, ontology version)
-java-codebase-rag meta --source-root tests/bank-chat-system --index-dir /tmp/bank-chat-index
-```
-
-Smoke-test the index with two checks (`search_lancedb` ships with the package):
-
-```bash
-# Vector search — proves the LanceDB side works
-JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
-  python -m search_lancedb "chat ingress controller" --table java --limit 3
-
-# 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
-```
-
-If vector hits come back and graph expansion adds neighbor symbols, the install works end-to-end. Wire it into your agent next — the five MCP tools (`search`, `find`, `describe`, `neighbors`, `resolve`) are reachable over stdio.
-
----
-
-## Wire into an MCP host
-
-> **Quick setup:** Run `java-codebase-rag install` from your Java project root. The interactive wizard handles MCP registration, skill deployment, and configuration for Claude Code, Qwen Code, and GigaCode in one step.
-
-### Claude Code (manual)
-
-With the package installed, the console script `java-codebase-rag-mcp` is on your `PATH`. Register it project-scoped:
-
-```bash
-claude mcp add --transport stdio java-codebase-rag -- java-codebase-rag-mcp
-```
-
-**Zero-env-var configuration:** The tool automatically walks up the directory tree to find `.java-codebase-rag.yml`, so you don't need to set `JAVA_CODEBASE_RAG_SOURCE_ROOT` when working from within a project. Just place the config file at your project root and the tool will find it. See [`mcp.json.example`](./mcp.json.example) for the minimal configuration.
-
-If you need to override defaults, you can set env vars (`JAVA_CODEBASE_RAG_INDEX_DIR`, `JAVA_CODEBASE_RAG_SOURCE_ROOT`, `SBERT_MODEL`, …) in `.mcp.json` or your shell profile. For a full configuration template, see [`mcp.json.example`](./mcp.json.example). Official docs: [Claude Code settings](https://docs.anthropic.com/en/docs/claude-code/settings).
-
-### Claude Desktop
-
-Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`) and add under `mcpServers`:
-
-```json
-{
-  "mcpServers": {
-    "java-codebase-rag": {
-      "command": "java-codebase-rag-mcp",
-      "env": {
-        "JAVA_CODEBASE_RAG_INDEX_DIR": "/ABSOLUTE/PATH/TO/.java-codebase-rag",
-        "JAVA_CODEBASE_RAG_SOURCE_ROOT": "/ABSOLUTE/PATH/TO/your-java-project"
-      }
-    }
-  }
-}
-```
-
-See [`mcp.json.example`](./mcp.json.example) for the same shape in `.mcp.json` (Claude Code project-scoped) form.
-
-### Driving the MCP from an agent
-
-Pick **one** of two options (not both — they cover the same navigation intents):
-
-1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and navigation patterns. Self-contained — no external file dependencies.
-
-2. **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** (for hosts with skill discovery) — single self-contained skill with the complete operating manual. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), load `/explore-codebase` to get the full tool reference, edge taxonomy, decision tree, and recovery playbook in one shot.
-
-Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md)** — 7-phase agent-driven verification you run after indexing your real project.
-
----
-
-## The five tools, at a glance
+**MCP surface — five tools over stdio**
 
 | Tool | Purpose | Required args |
 |---|---|---|
@@ -169,9 +91,63 @@ Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHE
 
 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).
 
+**CLI surface — `jrag`, one command per engineering intent**
+
+```bash
+# Orientation
+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 conventions               # dominant roles + framework tallies
+jrag overview chat-core        # bundle for a microservice
+jrag overview /chat/assign     # route flow (inbound callers + outbound CALLS)
+jrag overview banking.chat     # topic producers + consumers
+jrag overview chat-core --as microservice  # override auto-detection
+
+# Locate
+jrag find ChatService          # exact name/FQN lookup (symbols)
+jrag find --role CONTROLLER    # filter mode (NodeFilter flags)
+jrag inspect ChatService       # full node details + edge_summary
+jrag outline src/main/.../Foo.java  # all symbols declared in a file
+jrag imports src/main/.../Foo.java   # imports resolved to graph nodes
+
+# Listings
+jrag http-routes               # HTTP routes
+jrag http-clients              # HTTP clients (Feign / RestTemplate / WebClient)
+jrag producers                 # async message producers (Kafka / StreamBridge)
+jrag topics                    # message topics grouped by producer
+jrag jobs                      # scheduled tasks (@Scheduled)
+jrag listeners                 # message listeners (@KafkaListener etc.)
+jrag entities                  # JPA entities
+
+# Traversals (all resolve-first)
+jrag callers ChatService#assign(Request)   # who calls me?
+jrag callees ChatService#assign(Request)   # what do I call?
+jrag hierarchy AbstractBase               # type tree (parents + children)
+jrag implementations PaymentProcessor     # classes implementing an interface
+jrag subclasses AbstractRepository        # classes extending a type
+jrag overrides Impl#run()                 # methods this overrides (dispatch UP)
+jrag overridden-by Iface#run()            # methods overriding this (dispatch DOWN)
+jrag dependents PaymentGateway            # who injects this type?
+jrag dependencies ChatService             # types this injects
+jrag impact PaymentGateway                # fleet-wide blast radius
+jrag decompose ChatIngressController#assign   # role-waterfall flow
+jrag flow /chat/assign                    # request flow through a route
+jrag connection chat-core                 # cross-service connections
+
+# Semantic search
+jrag search "assign a chat agent"         # semantic over Lance (java table)
+jrag search "kafka" --table all           # java + sql + yaml tables
+jrag search "audit" --hybrid              # vector + keyword hybrid
+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.
+
 ### Three-layer architecture
 
-Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skill). The [`/explore-codebase`](./skills/explore-codebase/SKILL.md) skill provides the full operating manual for Layer 2. See the [architecture diagram in `skills/README.md`](./skills/README.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).
 
 ---
 
@@ -207,6 +183,71 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 
 ---
 
+## jrag — agent CLI
+
+`jrag` is a separate console script (alongside `java-codebase-rag`) built for AI
+coding agents. It gives the agent **one command per engineering intent** and
+takes human-readable identifiers (FQN / simple name / route path / topic) —
+never raw node IDs. Every `<query>` command resolves the identifier via
+`resolve_v2` as the first step; on `many` it returns candidates and stops, on
+`none` it returns `not_found`. Auto-pick is forbidden.
+
+The default output is compact text (a deliberate divergence from the operator
+CLI's TTY heuristic — `jrag` is agent-facing/non-TTY). `--format json` emits the
+shared envelope verbatim. Every command emits the same envelope shape:
+
+```json
+{
+  "status": "ok",
+  "nodes": {"com.example.Foo": {"kind": "symbol", "fqn": "com.example.Foo"}},
+  "edges": [{"edge_type": "CALLS", "confidence": 0.9, "target": "com.example.Bar#baz()"}],
+  "root": "com.example.Foo",
+  "agent_next_actions": ["jrag callees com.example.Foo#bar()"],
+  "truncated": false
+}
+```
+
+No raw graph node id ever appears on either surface: `nodes` is keyed by each
+node's natural identifier (FQN for symbols, `METHOD path` for routes,
+`member_fqn->target` for clients, `topic:<name>` for topics), `root` is the
+root's natural identifier, and each edge carries `target` (the referenced node's
+identifier) instead of a graph id. The agent reuses these identifiers directly
+as the next command's `<query>` — there is nothing else to pass.
+
+`agent_next_actions` carries up to 5 contextual next-step hints (e.g. after
+`inspect`, the agent sees `jrag callers <fqn>`, `jrag callees <fqn>`, etc. for
+the edges the root actually has). Omitted from JSON when empty.
+
+The full command catalog lives in [Tools & commands at a glance](#tools--commands-at-a-glance).
+
+### Flags
+
+| Flag | Scope | Effect |
+|------|-------|--------|
+| `--format text\|json` | all | output format (default: text) |
+| `--service <name>` | listings/traversals | filter by microservice |
+| `--module <name>` | listings/traversals | filter by module |
+| `--limit <n>` | listings/traversals | cap results (default 20; `limit+1` fetch detects truncation) |
+| `--offset <n>` | `find`, `search` only | paginate (other commands reject it) |
+| `--kind symbol\|route\|client\|producer` | `<query>` commands | resolve hint |
+| `--java-kind`, `--role`, `--fqn-contains` | `<query>` commands | client-side post-filters |
+| `--index-dir <path>` | all | override index directory |
+
+`--offset` is intentionally NOT a global flag: only `find` and `search` route
+through backends that accept it. Every other command rejects it.
+
+A missing or stale index produces an actionable `status: error` envelope (exit
+2) rather than a traceback:
+
+```
+error: No index at /path/to/code_graph.lbug. Run: java-codebase-rag init --source-root <root>
+```
+
+See [`plans/active/PLAN-JRAG-CLI.md`](./plans/active/PLAN-JRAG-CLI.md) for the
+full design and per-PR breakdown.
+
+---
+
 ## Further reading
 
 | Document | What's in it |
@@ -216,10 +257,9 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 | [`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/) | Single `/explore-codebase` skill — complete MCP operating manual for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
+| [`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). |
 | [`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. |
-| [`automation/cursor_propose_only/README.md`](./automation/cursor_propose_only/README.md) | Optional proposal orchestration workflow (single-command autopilot, planning bundles, automated execution/review loops). |
 | [`docs/PRODUCT-VISION.md`](./docs/PRODUCT-VISION.md) | Long-term product direction. |
 
 ---
@@ -230,7 +270,7 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 git clone https://github.com/HumanBean17/java-codebase-rag
 cd java-codebase-rag
 python3 -m venv .venv
-.venv/bin/pip install -r requirements.txt
+.venv/bin/pip install -e ".[dev]"
 ```
 
 The `cocoindex` package powers lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation do not invoke it directly.

{java_codebase_rag-0.6.6 → java_codebase_rag-0.8.0}/ast_java.py

@@ -1868,6 +1868,11 @@ def _collect_outgoing_calls(
     file_rel: str,
 ) -> list[OutgoingCallDecl]:
     del project_root
+    from java_ontology import (  # deferred: java_ontology imports ast_java
+        CLIENT_KIND_FEIGN_METHOD,
+        CLIENT_KIND_REST_TEMPLATE,
+        CLIENT_KIND_WEB_CLIENT,
+    )
     out: list[OutgoingCallDecl] = []
     method_fqn = f"{type_fqn}#{method_decl.signature}"
     type_mods = _find_modifiers_child(type_node) if type_node is not None else None
@@ -1899,7 +1904,7 @@ def _collect_outgoing_calls(
             OutgoingCallDecl(
                 method_fqn=method_fqn,
                 method_sig=method_decl.signature,
-                client_kind="feign_method",
+                client_kind=CLIENT_KIND_FEIGN_METHOD,
                 channel="http",
                 feign_target_name=feign_target_name,
                 feign_target_url=feign_target_url,
@@ -1998,7 +2003,7 @@ def _collect_outgoing_calls(
                     OutgoingCallDecl(
                         method_fqn=method_fqn,
                         method_sig=method_decl.signature,
-                        client_kind="rest_template",
+                        client_kind=CLIENT_KIND_REST_TEMPLATE,
                         channel="http",
                         feign_target_name="",
                         feign_target_url="",
@@ -2051,7 +2056,7 @@ def _collect_outgoing_calls(
                     OutgoingCallDecl(
                         method_fqn=method_fqn,
                         method_sig=method_decl.signature,
-                        client_kind="web_client",
+                        client_kind=CLIENT_KIND_WEB_CLIENT,
                         channel="http",
                         feign_target_name="",
                         feign_target_url="",