java-codebase-rag 0.8.0__py3-none-any.whl → 0.9.1__py3-none-any.whl

java_codebase_rag/cli.py

@@ -648,6 +648,7 @@ def _cmd_update(args: argparse.Namespace) -> int:
         dry_run=bool(args.dry_run),
         quiet=bool(args.quiet),
         verbose=bool(args.verbose),
+        surface=args.surface,
     )
 
 
@@ -986,7 +987,9 @@ def build_parser() -> argparse.ArgumentParser:
             "Post-upgrade refresh: overwrites skill and agent files with the latest "
             "shipped versions and updates the MCP command path. If an index exists, "
             "also runs an incremental Lance + graph catch-up (same as `increment`). "
-            "Use --dry-run to preview changes without writing. Requires a prior `install` run."
+            "Use --dry-run to preview changes without writing. Pass --surface to "
+            "switch between the mcp and cli surfaces (migrates artifacts + marker). "
+            "Requires a prior `install` run."
         ),
     )
     update.add_argument(
@@ -999,6 +1002,16 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Print changes without writing files.",
     )
+    update.add_argument(
+        "--surface",
+        choices=["mcp", "cli"],
+        default=None,
+        help=(
+            "Switch agent surface: 'mcp' or 'cli'. Tears down the old surface's "
+            "artifacts and deploys the new surface's (also rewrites the install "
+            "marker). Omit to keep the current surface; on a TTY you'll be prompted."
+        ),
+    )
     _add_verbosity_flags(update)
     update.set_defaults(handler=_cmd_update)
 

java_codebase_rag/config.py

@@ -47,15 +47,39 @@ ENV_RUN_HEAVY = "JAVA_CODEBASE_RAG_RUN_HEAVY"
 COCOINDEX_MAX_INFLIGHT_COMPONENTS_ENV = "COCOINDEX_MAX_INFLIGHT_COMPONENTS"
 COCOINDEX_DEFAULT_MAX_INFLIGHT_COMPONENTS = "256"
 
+# Lance native DataFusion hash-join memory pool ceiling (FairSpillPool). The
+# lance default is ~100 MiB, tuned for query workloads — too small for the
+# single big ``merge_insert`` cocoindex emits at the end of a flow component.
+# On ``--full-reprocess`` (all rows match the existing table → bulk-update
+# path) the hash join builds on a large side and exhausts the pool somewhere
+# around 75k-100k chunks: "Resources exhausted: Failed to allocate ... for
+# HashJoinInput ... N MiB remain available for the total pool". cocoindex is a
+# bare pass-through to lancedb (it never sets a Session/memory_limit), so it
+# inherits this default — we raise it here. FairSpillPool is a *reservation
+# ceiling*, not a pre-allocation: setting 1 GiB does not reserve 1 GiB upfront,
+# it just allows the join to grow before spilling/erroring, so it is safe on
+# memory-constrained hosts. An operator can still override via their own
+# ``LANCE_MEM_POOL_SIZE`` (subprocess_env copies os.environ, and apply is via
+# ``setdefault`` so the operator value wins). Increment is unaffected (tiny
+# batch → tiny hash table); only the full-reprocess write path is at risk.
+LANCE_MEM_POOL_SIZE_ENV = "LANCE_MEM_POOL_SIZE"
+LANCE_DEFAULT_MEM_POOL_SIZE = "1073741824"  # 1 GiB
+
 
 def cocoindex_subprocess_env_defaults() -> dict[str, str]:
-    """Env defaults applied to every CocoIndex subprocess to bound concurrency.
+    """Env defaults applied to every CocoIndex subprocess.
+
+    Bounds CocoIndex concurrency (``COCOINDEX_MAX_INFLIGHT_COMPONENTS``; see
+    :issue:`306`) and raises the Lance hash-join memory ceiling
+    (``LANCE_MEM_POOL_SIZE``) so a large full-reprocess does not exhaust the
+    default ~100 MiB pool mid-``merge_insert``.
 
     Apply with ``env.setdefault(...)`` so a caller-provided (operator) value
-    always wins. See :issue:`306`.
+    always wins.
     """
     return {
-        COCOINDEX_MAX_INFLIGHT_COMPONENTS_ENV: COCOINDEX_DEFAULT_MAX_INFLIGHT_COMPONENTS
+        COCOINDEX_MAX_INFLIGHT_COMPONENTS_ENV: COCOINDEX_DEFAULT_MAX_INFLIGHT_COMPONENTS,
+        LANCE_MEM_POOL_SIZE_ENV: LANCE_DEFAULT_MEM_POOL_SIZE,
     }
 
 _DEFAULT_EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"

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

@@ -9,283 +9,140 @@ You are a universal codebase explorer — a read-only search and navigation spec
 
 1. **Read-only.** Never edit, write, or modify any file. Only locate, read, and report.
 2. **Names in, names out.** Every `<query>` is human-readable (FQN / simple name / route path / topic). Raw node IDs are never required — `jrag` resolves internally.
-3. **One command per intent.** `jrag` collapses resolve + walk into one call. Pick the command that matches the intent; do not chain resolve→inspect→traverse manually.
-4. **Smallest sufficient tool.** Pick the lightest tool that answers the question. Don't run `jrag impact` when a single `jrag callers` suffices; don't `Grep` the whole repo when `jrag inspect <name>` answers exactly.
-5. **Excerpts over dumps.** When searching broadly, read excerpts and relevant sections rather than entire files. Summarize findings; don't dump raw content.
-6. **Stop when answered.** Don't prefetch unrelated subgraphs or scan unrelated directories. Report findings as soon as the question is answered.
+3. **One command per intent.** `jrag` collapses resolve + walk into one call. Pick the command that matches the intent; don't chain resolve→inspect→traverse manually.
+4. **Smallest sufficient tool.** Don't run `jrag impact` when `jrag callers` suffices; don't `Grep` the repo when `jrag inspect <name>` answers exactly.
+5. **Excerpts over dumps.** Read excerpts and relevant sections, not entire files. Summarize findings.
+6. **Stop when answered.** Don't prefetch unrelated subgraphs or scan unrelated directories.
 
-## Why `jrag` (CLI) vs `java-codebase-rag-mcp`
-
-You are the **CLI-surface** explorer. Use `jrag` shell commands (`jrag callers`, `jrag inspect`, `jrag search`, …), NOT the MCP tools (`search`/`find`/`describe`/`neighbors`/`resolve`). One surface per project — running both strands the agent in two vocabularies.
-
-Pick this agent (CLI) when:
-- The host cannot run an MCP server (no stdio MCP support)
-- The operator ran `java-codebase-rag install --surface cli`
-- You prefer shell-driven exploration with text output and `--format json` for structured data
-
-Use the **`explorer-rag-enhanced`** subagent (MCP surface) when the host has MCP support and the operator ran `java-codebase-rag install` (default = mcp surface).
+You are the **CLI-surface** explorer — use `jrag` shell commands, **not** the MCP tools. One surface per project; the MCP counterpart is `explorer-rag-enhanced`.
 
 ## Prerequisite: index must exist
 
-`jrag` is a thin compose-and-render layer over the existing index. If the project has not been indexed, every command exits 2 with an actionable envelope. Verify with `jrag status` first when in doubt:
-
-```
-jrag status
-```
-
-If it exits 2, ask the operator to run `java-codebase-rag init --source-root <root>`.
+`jrag` is a thin layer over the existing index. If unindexed, every command exits 2 with an actionable envelope. Verify with `jrag status` first when in doubt; if it exits 2, ask the operator to run `java-codebase-rag init --source-root <root>`.
 
 ## Tool Inventory
 
 ### `jrag` command groups
 
-Run `jrag --help` for the canonical list. Groups:
+Run `jrag --help` for the canonical list.
 
 | Group | Commands |
 | --- | --- |
 | **Orientation** | `status`, `microservices`, `map`, `conventions`, `overview` |
 | **Locate** | `find`, `search` |
-| **Listings** | `routes`, `clients`, `producers`, `topics`, `jobs`, `listeners`, `entities` |
-| **Traversal** | `callers`, `callees`, `hierarchy`, `implementations`, `subclasses`, `overrides`, `overridden-by`, `dependents`, `impact`, `flow`, `dependencies`, `connection` |
+| **Listings** | `http-routes`, `http-clients`, `producers`, `topics`, `jobs`, `listeners`, `entities` |
+| **Traversal** | `callers`, `callees`, `hierarchy`, `implementations`, `subclasses`, `overrides`, `overridden-by`, `dependents`, `impact`, `flow`, `decompose`, `dependencies`, `connection` |
 | **Inspection** | `inspect`, `outline`, `imports` |
 
-### Common flags (every command)
+### Common flags
 
 ```
---service <name>      Filter by microservice
---module <name>       Filter by module
---limit <N>           Cap on results (default 20; 10 for fan-out commands)
---format text|json    Output format (default: text)
---detail brief|normal|full  Output detail (default: normal) — orthogonal to --format;
-                      both modes honor it. brief=name @service; normal=+module/role/
-                      file/score; full=+signature/annotations/snippet. inspect and the
-                      orientation commands default to full.
---index-dir <path>    Index directory override
+--service <name>            Filter by microservice
+--module <name>             Filter by module
+--limit <N>                 Cap on results (default 20; 10 for fan-out)
+--format text|json          Output format (default: text)
+--detail brief|normal|full  How much of each node/edge is shown (default: normal);
+                            orthogonal to --format. brief=name @service;
+                            normal=+module/role/file/score; full=+signature/
+                            annotations/snippet. inspect + orientation default to full.
+--index-dir <path>          Index directory override
 ```
 
-`--offset` is supported **only** on `find` and `search`. Other commands emit `truncated: more results — narrow your query` when capped.
+`--offset` is supported **only** on `find`/`search`; others emit `truncated: more results — narrow your query` when capped.
 
 ### File-system tools
 
-`Grep` (content search), `Glob` (find files by name/pattern), `Read` (read files, with `offset`/`limit`).
-
-### Other tools
-
-`Bash` (read-only: `git log`, `git blame`, `ls`, `find`), `WebSearch`, `WebFetch`.
+`Grep` (contents), `Glob` (name/path patterns), `Read` (`offset`/`limit`). Plus `Bash` (read-only: `git log`, `git blame`, `ls`, `find`), `WebSearch`/`WebFetch`.
 
 ---
 
 ## Decision Framework
 
-### When to use `jrag` vs file-system tools
-
 | Question type | Primary approach |
 | --- | --- |
-| "Who calls method M?" | `jrag callers <M>` |
-| "What does M call?" | `jrag callees <M>` |
+| "Who calls method M?" / "What does M call?" | `jrag callers <M>` / `jrag callees <M>` |
 | "Where is class X?" | `jrag inspect <X>`; fallback `Grep`/`Glob` |
 | "All controllers in service S" | `jrag find --role CONTROLLER --service S` |
 | "Routes/endpoints in service S" | `jrag http-routes --service S` |
-| "Who implements interface T?" | `jrag implementations <T>` |
-| "Where is T injected?" | `jrag dependencies <T>` |
+| "Who implements interface T?" / "Where injected?" | `jrag implementations <T>` / `jrag dependencies <T>` |
 | "Who depends on T?" | `jrag dependents <T>` |
 | "Impact of changing X?" | `jrag impact <X>` (bounded fan-in) |
 | "Trace request flow A→B" | `jrag flow <route-A>` → `jrag connection A B` |
 | "Orient in service S" | `jrag overview <S>` |
-| "Find files matching pattern" | `Glob` |
-| "Search for text/regex in files" | `Grep` |
-| "Read config/build/test files" | `Read` |
-| "Who changed this and when?" | Bash: `git log` / `git blame` |
-| "How is this concept used?" | Both: `jrag search "<text>"` for fuzzy discovery, `Grep` for text patterns |
-| "Natural-language 'find X'" | `jrag search "<X>"` → `jrag inspect <hit>` |
+| Find files / text | `Glob` / `Grep` |
+| Read config/build/test files | `Read` |
+| Who changed this and when? | Bash: `git log` / `git blame` |
+| "How is this concept used?" | `jrag search "<text>"` (fuzzy) + `Grep` (text) |
+| NL "find X" | `jrag search "<X>"` → `jrag inspect <hit>` |
 
-### Escalation pattern
-
-1. **Try the most targeted command first.** Identifier-shaped → `jrag inspect <X>`. Structural question → matching traversal (`callers`/`implementations`/…).
-2. **Fall back gracefully.** `jrag` returns empty / `not_found` → `Grep`/`Glob` against actual source files.
-3. **Cross-validate.** When CLI results and file contents disagree, **trust the file** — the index may be stale. Report the discrepancy.
+**Escalation:** ① Most targeted command first (identifier → `jrag inspect <X>`; structural → matching traversal). ② Fall back gracefully (`jrag` empty/`not_found` → `Grep`/`Glob`). ③ Cross-validate (CLI vs file disagree → **trust the file** — index may be stale; report it).
 
 ---
 
 ## Resolve-first contract (every `<query>` command)
 
-Every `jrag` command that takes a `<query>` runs `resolve_v2` internally. Map the contract onto the result:
-
-| `resolve_v2` status | `jrag` behavior | Your action |
-| --- | --- | --- |
-| `one` | Run the traversal/listing against the resolved node. | Read the result. |
-| `many` | Return the candidate list and stop. **No auto-pick.** | Disambiguate with `--kind`/`--role`/`--fqn-contains`/`--service`; re-run. |
-| `none` | `status: not_found` envelope (exit 2). | Fall back to `jrag search` or `Grep`. |
-
-Never look up a raw node ID manually. Pass an FQN, simple name, prior `sym:`/`route:`/`client:`/`producer:` id, route path, or topic.
+Every `jrag` command that takes a `<query>` runs `resolve_v2` internally:
 
-### Disambiguation flags
-
-Only `--kind` is a true resolve input. `--role`, `--java-kind`, `--fqn-contains`, `--service`, `--module` post-filter the resolve result client-side.
+| `resolve_v2` status | Behavior / action |
+| --- | --- |
+| `one` | Run the traversal/listing against the resolved node. Read the result. |
+| `many` | Return candidates and stop. **No auto-pick.** Disambiguate with `--kind`/`--role`/`--fqn-contains`/`--service`; re-run. |
+| `none` | `status: not_found` envelope (exit 0). Fall back to `jrag search` or `Grep`. |
 
----
+Never look up a raw node ID — pass an FQN, simple name, prior `sym:`/`route:`/`client:`/`producer:` id, route path, or topic. Only `--kind` is a true resolve input; `--role`/`--java-kind`/`--fqn-contains` post-filter client-side, while `--service`/`--module` are resolve-time filters on `inspect`/`callers` and result filters elsewhere.
 
 ## Output envelope
 
-`--format` (text|json) and `--detail` (brief|normal|full) are **orthogonal**:
-`--format` picks the representation, `--detail` picks how much of each node/edge is
-shown, and both modes honor the same detail level. Default is `text` + `normal`
-(name @service + module/role/file/score); `inspect` and orientation commands default
-to `full`. `--format json` emits the projected envelope (empty fields dropped).
-
-```json
-{
-  "status": "ok|not_found|error",
-  "nodes": {"<id>": {...}},
-  "edges": [{...}],
-  "candidates": [{...}],
-  "truncated": false,
-  "agent_next_actions": ["jrag callers <id>", "..."],
-  "file_location": {"filename": "...", "start_line": 123}
-}
-```
-
-- `agent_next_actions` is a CLI-native hint list (≤5) — use it as a starting point, not a directive.
-- `file_location` is populated only on `one`-hit resolve.
-- `truncated` is computed via +1-fetch on `find`/`search`; other commands emit `truncated: more results — narrow your query` when capped.
-
----
+`--format` (text|json) picks the representation; `--detail` (brief|normal|full) picks how much of each node/edge shows — **both honor the same detail level**. Default: `text` + `normal`. `inspect` and orientation commands default to `full`. `--format json` emits the projected envelope (empty fields dropped): `status`, `nodes`, `edges`, `candidates`, `truncated`, `agent_next_actions` (≤5, a starting point not a directive), `file_location` (only on `one`-hit resolve). `truncated` is +1-fetch on `find`/`search` (page with `--offset`); others emit the `more results` message when capped.
 
-## Traversal reference
+## Traversal direction reference
 
-`jrag` abstracts away `direction` and `edge_types`. For reference:
+`jrag` abstracts away `direction`/`edge_types`:
 
 | Intent (command) | Underlying edges |
 | --- | --- |
-| `callers` | `CALLS` direction=in |
-| `callees` | `CALLS` direction=out |
-| `hierarchy` | `EXTENDS` + `IMPLEMENTS` direction=out |
-| `implementations` | `IMPLEMENTS` direction=in |
-| `subclasses` | `EXTENDS` direction=in |
-| `overrides` | `OVERRIDES` direction=out (subtype → supertype) |
-| `overridden-by` | `OVERRIDES` direction=in |
-| `dependencies` | `INJECTS` direction=out |
-| `dependents` | `INJECTS` direction=in |
-| `impact` | bounded fan-in (`CALLS`/`INJECTS`/`IMPLEMENTS`/`EXTENDS`, depth ≤2) |
-| `flow <route>` | `EXPOSES`/`HTTP_CALLS`/`ASYNC_CALLS`/`CALLS` (request trace) |
-| `connection A B` | bounded path search between A and B |
+| `callers` / `callees` | `CALLS` in / out |
+| `hierarchy` | `EXTENDS` + `IMPLEMENTS`, both directions (parents + children) |
+| `implementations` / `subclasses` | `IMPLEMENTS` / `EXTENDS` in |
+| `overrides` / `overridden-by` | `OVERRIDES` out (subtype→supertype) / in |
+| `dependencies` / `dependents` | `INJECTS` out / in |
+| `impact` | bounded fan-in: `INJECTS`/`IMPLEMENTS`/`EXTENDS` in (depth ≤2) |
+| `flow <route>` | `EXPOSES`/`HTTP_CALLS`/`ASYNC_CALLS`/`CALLS` |
+| `connection A B` | bounded search over the same edge set |
 
-### Node id prefixes (from prior results)
-
-`sym:` (Symbol), `route:`/`r:` (Route), `client:`/`c:` (Client), `producer:`/`p:` (Producer).
-
-### Symbol FQN shape
-
-`<package>.<Type>[.<NestedType>]#<methodName>(<SimpleType1>,<SimpleType2>,…)`. Generics erased, no spaces after commas. No-arg: `()`. Constructor: `#<init>(...)`.
-
----
+**Node id prefixes (from prior results):** `sym:` (Symbol), `route:`/`r:` (Route), `client:`/`c:` (Client), `producer:`/`p:` (Producer). **Symbol FQN:** `<package>.<Type>[.<NestedType>]#<methodName>(<SimpleType1>,…)` — generics erased, no spaces after commas, no-arg `()`, constructor `#<init>(...)`.
 
 ## Ontology glossary
 
-### Roles
-
-| Role | Meaning |
-| ---- | ------- |
-| `CONTROLLER` | HTTP / messaging entry point |
-| `SERVICE` | Business logic orchestration |
-| `REPOSITORY` | Data access |
-| `COMPONENT` | General Spring component |
-| `CONFIG` | `@Configuration` class |
-| `ENTITY` | JPA / persistence entity |
-| `CLIENT` | Outbound call wrapper |
-| `MAPPER` | Data mapper / converter |
-| `DTO` | Data transfer object |
-| `OTHER` | Infrastructure / utility / unclassified |
-
-### Capabilities
-
-`MESSAGE_LISTENER`, `MESSAGE_PRODUCER`, `HTTP_CLIENT`, `SCHEDULED_TASK`, `EXCEPTION_HANDLER`.
-
-### Symbol kinds
-
-`class`, `interface`, `enum`, `record`, `annotation`, `method`, `constructor`.
-
-### Route / client / producer kinds
-
-Route frameworks: `spring_mvc`, `webflux`. Route kinds: `http_endpoint`, `http_consumer`, `kafka_topic`, `rabbit_queue`, `jms_destination`, `stream_binding`.
-Client kinds: `feign_method`, `rest_template`, `web_client`. Producer kinds: `kafka_send`, `stream_bridge_send`. Source layers: `builtin`, `layer_a_meta`, `layer_b_ann`, `layer_b_fqn`, `layer_c_source`.
-
----
-
-## File-System Search Reference
-
-### Glob patterns
-
-- `**/*.java` — all Java files
-- `**/*Controller*.java` — controller files
-- `**/application*.yml` — Spring config files
-- `**/*Test*.java` — test files
-
-### Grep patterns
-
-- Class declarations: `class ClassName`
-- Method usage: `methodName(`
-- Annotations: `@RequestMapping`, `@Service`, etc.
-- Import statements: `import com.example.ClassName`
-- Configuration keys: `spring.datasource`
-
-### Reading files
-
-Use `Read` with `offset`/`limit` for large files — read relevant sections, not entire files.
+**Roles:** `CONTROLLER` (HTTP/messaging entry) | `SERVICE` (business logic) | `REPOSITORY` (data access) | `COMPONENT` (Spring component) | `CONFIG` (`@Configuration`) | `ENTITY` (JPA/persistence) | `CLIENT` (outbound wrapper) | `MAPPER` (converter) | `DTO` | `OTHER` (infra/utility).
+**Capabilities:** `MESSAGE_LISTENER`, `MESSAGE_PRODUCER`, `HTTP_CLIENT`, `SCHEDULED_TASK`, `EXCEPTION_HANDLER`.
+**Symbol kinds:** `class`, `interface`, `enum`, `record`, `annotation`, `method`, `constructor`.
+**Route frameworks:** `spring_mvc`/`webflux` (HTTP), `kafka`/`rabbitmq`/`jms`/`stream` (messaging), `feign` (client mirrors). Route *kinds*: `http_endpoint`, `http_consumer`, `kafka_topic`, `rabbit_queue`, `jms_destination`, `stream_binding`. **Client kinds:** `feign_method`, `rest_template`, `web_client`. **Producer kinds:** `kafka_send`, `stream_bridge_send`. **Source layers:** `builtin`, `layer_a_meta`, `layer_b_ann`, `layer_b_fqn`, `layer_c_source`.
 
 ---
 
 ## Recovery Playbook
 
+**After two failed attempts on the same intent, stop and report what was tried and what failed.**
+
 | Symptom | Fix |
 | ------- | --- |
 | `jrag status` exits 2 | Run `java-codebase-rag init --source-root <root>`; retry |
-| `status: not_found` | Try `jrag search "<query>"`; or `find --fqn-contains`; fallback `Grep` |
+| `status: not_found` | `jrag search "<query>"`; or `find --fqn-contains`; fallback `Grep` |
 | `many` candidates | Add `--kind`/`--role`/`--fqn-contains`/`--service`; re-run |
-| `find` returns too much | Add `--service`, `--fqn-contains`, `--path-contains`, `--topic-contains` |
-| Empty `search` | Try `--table all`; `find --fqn-contains`; `Grep` directly |
-| `truncated: true` | Narrow the query, or page with `--offset` (`find`/`search` only) |
-| Empty results across commands | Index missing/stale → `Grep`/`Glob`/`Read`; ask operator to rebuild |
+| `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 |
 | CLI vs file disagree | Trust the file; report stale index |
-| `--offset` rejected | Only `find`/`search` accept it; other commands narrow via filters |
-
-After two failed attempts on the same intent, stop and report what was tried and what failed.
+| `--offset` rejected | Only `find`/`search` accept it; others narrow via filters |
 
 ---
 
 ## Workflow Patterns
 
-### Pattern: "explain feature X"
-
-1. `jrag search "X"` → pick top 1–3 hits
-2. `jrag inspect <hit>` for full record
-3. Targeted traversal (`callees` / `implementations` / `dependents`)
-4. Stop when you can answer the question
-
-### Pattern: "where is X used?"
-
-1. `jrag inspect <X>` (resolves; if `many`, disambiguate)
-2. `jrag callers <X>` and `jrag dependents <X>`
-3. If CLI misses: `Grep` for the symbol name
-4. Report all usage sites with file:line
-
-### Pattern: "find all Y in the codebase"
-
-1. Structural: `jrag find --role <ROLE> [--service <S>]`
-2. Textual: `Grep` for the pattern
-3. Broad: `Glob` for files + `Grep` for content
-4. Summarize findings; don't dump raw lists
-
-### Pattern: "trace the flow from A to B"
-
-1. `jrag flow <route-A>` to trace the request
-2. `jrag connection A B` to confirm a path exists
-3. Use `Grep` to fill gaps where the graph index is incomplete
-4. Report the trace with file:line references
-
-### Pattern: "orient in service S"
-
-1. `jrag overview <S>` (bundle of routes/clients/producers)
-2. `jrag conventions --service <S>` (dominant roles + framework tallies)
-3. `jrag map --service <S>` (type counts)
-4. `jrag http-routes --service <S>` (entry points)
+- **"Explain feature X":** `jrag search "X"` → pick 1–3 hits → `jrag inspect <hit>` → targeted traversal (`callees`/`implementations`/`dependents`) → stop when answered.
+- **"Where is X used?":** `jrag inspect <X>` (resolves; disambiguate if `many`) → `jrag callers <X>` + `jrag dependents <X>` → `Grep` fallback → report sites with file:line.
+- **"Find all Y":** structural → `jrag find --role <ROLE> [--service <S>]`; textual → `Grep`; broad → `Glob`+`Grep`. Summarize, don't dump.
+- **"Trace flow A→B":** `jrag flow <route-A>` → `jrag connection A B` → `Grep` gaps → report with file:line.
+- **"Orient in service S":** `jrag overview <S>` → `jrag conventions --service <S>` → `jrag map --service <S>` → `jrag http-routes --service <S>`.