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

java_codebase_rag/installer.py

@@ -190,7 +190,27 @@ def prompt(
         if prompt_type == "checkbox":
             return questionary.checkbox(message, choices=choices, style=no_color_style).ask()
         elif prompt_type == "select":
-            return questionary.select(message, choices=choices, style=no_color_style).ask()
+            # Normalize dict choices to questionary.Choice so ``default`` is
+            # matched by value. questionary.select forwards ``default`` as the
+            # cursor position (initial_choice), but its validation only matches
+            # ``default`` against ``Choice.value`` — a raw dict's value is
+            # invisible there, so passing ``default`` with dict choices raises.
+            # Plain-string choices pass through unchanged.
+            norm_choices = []
+            for c in choices or []:
+                if isinstance(c, dict):
+                    title = c.get("name", c.get("value"))
+                    norm_choices.append(
+                        questionary.Choice(title, value=c.get("value", title))
+                    )
+                else:
+                    norm_choices.append(c)
+            return questionary.select(
+                message,
+                choices=norm_choices,
+                default=default,
+                style=no_color_style,
+            ).ask()
         elif prompt_type == "text":
             return questionary.text(message, default=default, style=no_color_style).ask()
         elif prompt_type == "confirm":
@@ -475,6 +495,21 @@ def select_scope(*, non_interactive: bool, cli_scope: str | None) -> Scope:
     return selected  # type: ignore
 
 
+def _surface_choices() -> list[dict]:
+    """Choice list for a surface select prompt.
+
+    Single source of truth for the surface option labels and order: ``cli`` is
+    listed first and marked "(Recommended)" — the jrag CLI surface is the
+    recommended default for new installs. ``mcp`` remains available. The
+    returned dicts are normalized to ``questionary.Choice`` inside ``prompt``
+    so a value-based ``default`` (cursor position) validates.
+    """
+    return [
+        {"name": "cli (Recommended)", "value": "cli"},
+        {"name": "mcp", "value": "mcp"},
+    ]
+
+
 def select_surface(
     *,
     non_interactive: bool,
@@ -483,15 +518,17 @@ def select_surface(
 ) -> Surface:
     """Select 'mcp' or 'cli' surface (PR-JRAG-5).
 
-    The MCP surface registers the stdio MCP server (today's behavior). The CLI
-    surface ships the ``jrag`` console-script skill+subagent instead — no MCP
-    entry is registered.
+    The MCP surface registers the stdio MCP server. The CLI surface ships the
+    ``jrag`` console-script skill+subagent instead — no MCP entry is registered.
+    The CLI surface is the recommended default (listed first, marked
+    "(Recommended)").
 
     Args:
-        non_interactive: If True, honor ``cli_surface`` (default ``"mcp"``).
+        non_interactive: If True, honor ``cli_surface`` (default ``"cli"``).
         cli_surface: Surface from the ``--surface`` CLI flag.
         prefill: On re-run, the surface recorded in the existing marker file.
-            When set and the user does not pick otherwise, this is preserved.
+            When set, the cursor defaults to it so the user can keep the prior
+            choice with Enter (``cli`` is still shown first + recommended).
 
     Returns:
         Selected surface (``"mcp"`` or ``"cli"``).
@@ -506,25 +543,22 @@ def select_surface(
         return cli_surface  # type: ignore
 
     if non_interactive:
-        # Default to MCP for back-comat when no flag is passed.
-        return "mcp"
+        # Default to the recommended CLI surface when no flag is passed.
+        return "cli"
 
     print(
-        "Note: 'mcp' surface registers the java-codebase-rag MCP server (5 tools: "
-        "search/find/describe/neighbors/resolve)."
+        "Note: 'cli' surface deploys the `jrag` console-script skill+subagent "
+        "(one command per intent, no MCP server) — recommended."
     )
     print(
-        "      'cli' surface deploys the `jrag` console-script skill+subagent "
-        "(one command per intent, no MCP server)."
+        "      'mcp' surface registers the java-codebase-rag MCP server "
+        "(5 tools: search/find/describe/neighbors/resolve)."
     )
 
-    choices = ["mcp", "cli"]
-    if prefill is not None:
-        # Surface the prior choice first so the user can keep it with Enter.
-        choices = [prefill] + [c for c in ("mcp", "cli") if c != prefill]
-        default = prefill
-    else:
-        default = "mcp"
+    # cli is always shown first + recommended; the cursor defaults to the prior
+    # choice (prefill) on re-run so the user can keep it with Enter.
+    choices = _surface_choices()
+    default = prefill if prefill is not None else "cli"
 
     selected = prompt(
         "select",
@@ -1543,6 +1577,133 @@ def _refresh_mcp_config(
         return ArtifactResult(path=config_path, success=False, error=str(e))
 
 
+def _remove_mcp_entry(config_path: Path, *, dry_run: bool) -> ArtifactResult:
+    """Remove the java-codebase-rag entry from an MCP config (surface migration).
+
+    Pops ONLY the ``java-codebase-rag`` key from ``mcpServers`` — other servers
+    and the file itself are preserved. No-op success when the file or our key is
+    absent. Atomic write (same tmp + ``os.replace`` pattern as ``merge_mcp_config``).
+    Used by ``_undeploy_surface`` when switching off the MCP surface.
+    """
+    if not config_path.is_file():
+        return ArtifactResult(path=config_path, success=True, error=None)
+    try:
+        with open(config_path, "r") as f:
+            config = json.load(f)
+    except (json.JSONDecodeError, IOError, OSError) as e:
+        return ArtifactResult(
+            path=config_path, success=False, error=f"Failed to parse {config_path}: {e}"
+        )
+
+    servers = config.get("mcpServers")
+    if not isinstance(servers, dict) or _MCP_SERVER_NAME not in servers:
+        return ArtifactResult(path=config_path, success=True, error=None)
+
+    if dry_run:
+        print(f"Would remove MCP entry from {config_path}")
+        return ArtifactResult(path=config_path, success=True, error=None)
+
+    del servers[_MCP_SERVER_NAME]
+    if not servers:
+        config.pop("mcpServers", None)
+
+    tmp_name = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            dir=config_path.parent,
+            prefix=f".{config_path.name}.",
+            delete=False,
+        ) as tmp:
+            json.dump(config, tmp, indent=2)
+            tmp.flush()
+            os.fsync(tmp.fileno())
+            tmp_name = tmp.name
+        os.replace(tmp_name, config_path)
+        print(f"Removed MCP entry from {config_path}")
+        return ArtifactResult(path=config_path, success=True, error=None)
+    except (IOError, OSError) as e:
+        if tmp_name:
+            try:
+                os.unlink(tmp_name)
+            except OSError:
+                pass
+        return ArtifactResult(
+            path=config_path, success=False, error=f"Failed to write {config_path}: {e}"
+        )
+
+
+def _remove_artifact_file(dest_path: Path, *, dry_run: bool) -> ArtifactResult:
+    """Remove a deployed skill/agent file (surface migration teardown).
+
+    Best-effort prunes the now-empty immediate parent dir (e.g.
+    ``skills/explore-codebase``); leaves it in place if other files remain.
+    No-op success when the file is absent.
+    """
+    if not dest_path.is_file():
+        return ArtifactResult(path=dest_path, success=True, error=None)
+    if dry_run:
+        print(f"Would remove {dest_path}")
+        return ArtifactResult(path=dest_path, success=True, error=None)
+    try:
+        dest_path.unlink()
+        try:
+            dest_path.parent.rmdir()
+        except OSError:
+            # Not empty or not removable — leave the directory in place.
+            pass
+        print(f"Removed {dest_path}")
+        return ArtifactResult(path=dest_path, success=True, error=None)
+    except OSError as e:
+        return ArtifactResult(
+            path=dest_path, success=False, error=f"Failed to remove {dest_path}: {e}"
+        )
+
+
+def _undeploy_surface(
+    host: HostConfig, scope: str, cwd: Path, *, surface: Surface, dry_run: bool
+) -> list[ArtifactResult]:
+    """Tear down every artifact a surface shipped (migration off ``surface``).
+
+    Iterates ``ARTIFACT_MANIFEST[surface]`` so adding/removing an artifact is
+    one manifest edit, not two — mirrors ``deploy_artifacts``/``refresh_artifacts``.
+    The ``mcp`` row removes just our server entry; ``skill``/``agent`` rows
+    remove the file. Returns one ``ArtifactResult`` per manifest row.
+    """
+    results: list[ArtifactResult] = []
+    for kind, _package_path, dest_relative in ARTIFACT_MANIFEST[surface]:
+        if kind == "mcp":
+            mcp_config_path = host.mcp_config_path(scope, cwd)
+            results.append(_remove_mcp_entry(mcp_config_path, dry_run=dry_run))
+        else:
+            dest_path = host.scope_path(scope, cwd) / dest_relative
+            results.append(_remove_artifact_file(dest_path, dry_run=dry_run))
+    return results
+
+
+def _resolve_update_surface(*, surface: str | None, current: Surface) -> Surface | None:
+    """Decide which surface ``run_update`` should target.
+
+    Returns a surface to migrate toward, or ``None`` when no global choice was
+    made (non-TTY, no flag) — in which case ``run_update`` refreshes each host
+    on its OWN recorded surface and migrates nothing.
+
+    - ``surface`` set (``--surface`` flag): validate and use it (enables
+      migration; invalid value raises ``SystemExit(2)`` via ``select_surface``).
+    - TTY, no flag: interactive prompt — ``cli`` recommended, cursor on the
+      current surface so the user can keep it with Enter or switch.
+    - non-TTY, no flag: ``None`` (no migration). Preserves the behavior of
+      non-interactive ``run_update(...)`` callers and, crucially, leaves a
+      mixed-surface marker untouched rather than normalizing it to the first
+      host's surface.
+    """
+    if surface is not None:
+        return select_surface(non_interactive=True, cli_surface=surface)
+    if sys.stdin.isatty():
+        return select_surface(non_interactive=False, cli_surface=None, prefill=current)
+    return None
+
+
 def run_update(
     *,
     force: bool,
@@ -1550,6 +1711,7 @@ def run_update(
     cwd: Path | None = None,
     quiet: bool = False,
     verbose: bool = False,
+    surface: str | None = None,
 ) -> int:
     """Run the update pipeline. Returns exit code.
 
@@ -1561,12 +1723,20 @@ def run_update(
     the indexing chatter that used to print to stdout moves onto the stderr
     renderer framing.
 
+    Surface switching (mcp ↔ cli): a ``surface`` choice different from a host's
+    recorded surface migrates that host — tearing down the old surface's
+    artifacts (``_undeploy_surface``), deploying the new surface's
+    (``deploy_artifacts``), and rewriting the marker so the switch persists.
+
     Args:
         force: If True, overwrite all artifacts even if matching
         dry_run: If True, print changes without writing
         cwd: Current working directory (defaults to Path.cwd())
         quiet: If True, suppress progress output
         verbose: If True, raw-relay subprocess output (no Live region)
+        surface: Target surface (``"mcp"``/``"cli"``) from ``--surface``. When
+            ``None``: a TTY prompts (cursor on the current surface); a non-TTY
+            keeps each host's recorded surface (no migration).
 
     Returns:
         Exit code (0=success, 1=partial, 2=fatal)
@@ -1585,19 +1755,115 @@ def run_update(
 
     print(f"Found {len(configured_hosts)} configured host(s).")
 
-    # Refresh artifacts for each host
+    # Resolve the target surface. ``--surface`` validates + overrides; a TTY
+    # with no flag prompts (cursor on the current surface); a non-TTY with no
+    # flag yields None -> no global choice, so each host refreshes on its OWN
+    # recorded surface and nothing migrates (preserves non-interactive callers
+    # and leaves mixed-surface markers untouched rather than normalizing them).
+    current_surfaces = {ch.surface for ch in configured_hosts}
+    current_surface = configured_hosts[0].surface
+    chosen_surface = _resolve_update_surface(
+        surface=surface, current=current_surface
+    )
+    if len(current_surfaces) > 1:
+        if chosen_surface is None:
+            print(
+                f"Note: configured hosts span multiple surfaces "
+                f"({sorted(current_surfaces)}); refreshing each on its own "
+                f"recorded surface (pass --surface to normalize)."
+            )
+        else:
+            print(
+                f"Note: configured hosts span multiple surfaces "
+                f"({sorted(current_surfaces)}); normalizing to '{chosen_surface}'."
+            )
+
+    # If any host needs to migrate, resolve the target surface's runtime binary
+    # up front so a missing binary fails fast with a clear message rather than a
+    # per-host partial. (For the cli surface ``deploy_artifacts`` ignores the
+    # command, but resolving ``jrag`` confirms the invoked CLI actually exists.)
+    # ``chosen_surface`` is guaranteed non-None here when migration_needed.
+    migration_needed = (
+        chosen_surface is not None
+        and any(ch.surface != chosen_surface for ch in configured_hosts)
+    )
+    deploy_command = ""
+    if migration_needed and not dry_run:
+        try:
+            deploy_command = resolve_mcp_command(
+                non_interactive=not sys.stdin.isatty(), surface=chosen_surface
+            )
+        except SystemExit:
+            binary = "jrag" if chosen_surface == "cli" else "java-codebase-rag-mcp"
+            print(
+                f"Error: `{binary}` not found on PATH — cannot migrate to the "
+                f"'{chosen_surface}' surface."
+            )
+            print(
+                "Ensure `java-codebase-rag` is installed, then re-run `update "
+                f"--surface {chosen_surface}`."
+            )
+            return EXIT_PARTIAL
+
+    # Refresh (or migrate) artifacts for each host. When chosen_surface is None
+    # (non-TTY, no flag) every host takes the refresh branch on its own surface.
     all_results = []
-    for host_config, scope, surface in configured_hosts:
-        print(f"\nRefreshing {host_config.name} ({scope} scope, surface={surface})...")
-        results = refresh_artifacts(
-            host_config,
-            scope,
-            cwd,
-            force=force,
-            dry_run=dry_run,
-            surface=surface,
-        )
-        all_results.extend(results)
+    updated_configured: list[ConfiguredHost] = []
+    migrated = False
+    for host_config, scope, host_surface in configured_hosts:
+        if chosen_surface is not None and host_surface != chosen_surface:
+            migrated = True
+            print(
+                f"\nMigrating {host_config.name} ({scope} scope): "
+                f"{host_surface} → {chosen_surface}..."
+            )
+            if dry_run:
+                print(
+                    f"  Would tear down {host_surface} artifacts and deploy "
+                    f"{chosen_surface} artifacts."
+                )
+                updated_configured.append(
+                    ConfiguredHost(host_config, scope, chosen_surface)
+                )
+                continue
+            teardown_results = _undeploy_surface(
+                host_config, scope, cwd, surface=host_surface, dry_run=False
+            )
+            all_results.extend(teardown_results)
+            # deploy_command was resolved up front (migration_needed && not
+            # dry_run); chosen_surface is non-None on this branch by the guard.
+            deploy_results = deploy_artifacts(
+                [host_config],
+                scope,
+                cwd,
+                non_interactive=True,
+                mcp_command=deploy_command,
+                surface=chosen_surface,
+            )
+            all_results.extend(deploy_results)
+            updated_configured.append(
+                ConfiguredHost(host_config, scope, chosen_surface)
+            )
+        else:
+            print(
+                f"\nRefreshing {host_config.name} ({scope} scope, surface={host_surface})..."
+            )
+            results = refresh_artifacts(
+                host_config,
+                scope,
+                cwd,
+                force=force,
+                dry_run=dry_run,
+                surface=host_surface,
+            )
+            all_results.extend(results)
+            updated_configured.append(
+                ConfiguredHost(host_config, scope, host_surface)
+            )
+
+    # Persist the surface switch so a later ``update`` sees the new surface.
+    if migrated and not dry_run:
+        _write_hosts_marker(cwd, updated_configured)
 
     # Check for partial failures
     partial_failures = [r for r in all_results if not r.success]
@@ -1799,7 +2065,19 @@ def run_install(
         return e.code
 
     # Stage 2: Embedding model
-    resolved_model = resolve_model(model, non_interactive=non_interactive)
+    from java_codebase_rag.pipeline import vector_stack_installed
+
+    if not vector_stack_installed():
+        # Graph-only install (macOS Intel): no torch/lancedb, so there is no vector
+        # index to embed into — the embedding-model choice is inert here. Skip the
+        # prompt and let init build the graph (vectors phase auto-skipped).
+        print(
+            "Skipping embedding model selection: vector stack not installed on this "
+            "platform (graph-only mode)."
+        )
+        resolved_model = "auto"
+    else:
+        resolved_model = resolve_model(model, non_interactive=non_interactive)
 
     # Stage 3-4: Agent host + scope + surface selection
     prior_surface = _prior_surface_from_marker(cwd)

java_codebase_rag/jrag.py

@@ -1058,6 +1058,9 @@ def build_parser() -> argparse.ArgumentParser:
     search.add_argument(
         "--hybrid", action="store_true", help="Enable vector+keyword hybrid search."
     )
+    search.add_argument(
+        "--explain", action="store_true", help="Show score breakdown per hit."
+    )
     search.add_argument(
         "--path-contains", type=str, default=None, dest="path_contains",
         help="Narrow to chunks whose filename contains this substring.",
@@ -1088,6 +1091,11 @@ def build_parser() -> argparse.ArgumentParser:
         default=0,
         help="Page offset (passed to search_v2; paginated via +1-fetch).",
     )
+    search.add_argument(
+        "--chunks",
+        action="store_true",
+        help="Show every chunk (default collapses to one row per symbol/type).",
+    )
     search.set_defaults(handler=_cmd_search, auto_scope=True)
 
     return parser
@@ -1096,20 +1104,26 @@ def build_parser() -> argparse.ArgumentParser:
 def _resolve_cfg(args: argparse.Namespace):  # type: ignore[no-untyped-def]
     """Resolve operator config (reuses the operator's cocoindex-free resolver).
 
-    Same pattern as ``java_codebase_rag.cli._resolved_from_ns``: walks up from
-    cwd to find a project root (config file or ``.java-codebase-rag/`` index),
-    applies CLI ``--index-dir`` if given, and calls ``apply_to_os_environ`` so
-    downstream modules see a consistent env (critically: SBERT_MODEL for
-    ``jrag search`` in PR-JRAG-4).
+    Mirrors ``java_codebase_rag.cli._resolved_from_ns``: pass ``source_root=None``
+    so ``resolve_operator_config`` honors ``JAVA_CODEBASE_RAG_SOURCE_ROOT`` first,
+    then a YAML ``source_root`` field, then walks up from cwd to find a project
+    root. Passing a discovered root explicitly here would OVERRIDE a set env var
+    whenever any ancestor dir has a ``.java-codebase-rag`` marker — silently
+    ignoring the documented subprocess source-root mechanism that
+    ``pipeline.subprocess_env`` sets for the cocoindex child (and that operators
+    set directly).
 
     When the anchor is an index dir with no YAML beside it, resolution follows
     that index's ``config_source`` pointer (see ``config._effective_config_dir``)
     so a config living in a sibling dir is still found from inside a microservice.
+    Applies CLI ``--index-dir`` if given and calls ``apply_to_os_environ`` so
+    downstream modules see a consistent env (critically SBERT_MODEL for ``jrag
+    search``).
     """
-    from java_codebase_rag.config import discover_project_root, resolve_operator_config
+    from java_codebase_rag.config import resolve_operator_config
 
     cfg = resolve_operator_config(
-        source_root=discover_project_root(Path.cwd()),
+        source_root=None,
         cli_index_dir=getattr(args, "index_dir", None),
     )
     cfg.apply_to_os_environ()
@@ -4019,6 +4033,65 @@ def _cmd_overview(args: argparse.Namespace) -> int:
 # ============================================================================
 
 
+def _zero_result_guidance(args: argparse.Namespace, graph) -> str | None:
+    """Hint where matches live when a filtered search returns 0 results.
+
+    Runs ONE cheap unfiltered probe (limit 10) and tallies the filtered
+    dimension across the probe hits, so an agent who filtered to e.g.
+    ``--role SERVICE`` and got nothing learns the matches are under
+    COMPONENT/OTHER instead of guessing. Returns None when no guidance
+    applies: no recognizable single-dimension filter set, the probe is
+    empty (truly no matches for this query), or the probe itself errored
+    (non-fatal — the empty result still renders).
+    """
+    import mcp_v2
+    from collections import Counter
+
+    from java_codebase_rag.jrag_envelope import normalize_enum
+
+    # Only the common single-dimension filters get guidance; first set wins.
+    dims: list[tuple[str, str, str, str]] = []
+    if args.role:
+        dims.append(("role", "role", "roles", normalize_enum(args.role, kind="role")))
+    if args.service:
+        dims.append(("microservice", "service", "services", args.service))
+    if args.module:
+        dims.append(("module", "module", "modules", args.module))
+    if not dims:
+        return None
+    attr, flag, plural, value = dims[0]
+
+    try:
+        probe = mcp_v2.search_v2(
+            args.query,
+            table=args.table,
+            hybrid=args.hybrid,
+            limit=10,
+            offset=0,
+            path_contains=args.path_contains,
+            filter=None,
+            explain=False,
+            graph=graph,
+        )
+    except Exception:
+        return None
+    if not probe.success or not probe.results:
+        return None
+
+    counts: Counter = Counter(getattr(h, attr, None) for h in probe.results)
+    counts.pop(None, None)
+    if not counts:
+        return None
+    total = sum(counts.values())
+    top = counts.most_common(3)
+    alts = ", ".join(f"{v} ({c})" for v, c in top)
+    suggestion = top[0][0]
+    return (
+        f"0 results with --{flag} {value}; {total} matches exist under other {plural}: "
+        f"{alts} — try --{flag} {suggestion}"
+    )
+
+
 def _cmd_search(args: argparse.Namespace) -> int:
     """search <query> — semantic search via search_v2 over Lance tables.
 
@@ -4048,6 +4121,19 @@ def _cmd_search(args: argparse.Namespace) -> int:
 
     limit = min(args.limit if args.limit is not None else 20, 499)
 
+    # --limit 0: short-circuit to a clean empty page. mark_truncated(rows, 0)
+    # would otherwise report truncated=True (a unit test pins the helper's
+    # current behavior, so we fix this in the handler, not the helper), and
+    # there is nothing to search — skip the embedding-model load entirely.
+    if limit == 0:
+        env = Envelope(
+            status="ok", nodes={}, truncated=False,
+            warnings=_auto_scope_notice(args),
+        )
+        next_actions_hook(env)
+        print(render(env, fmt=args.format, detail=args.detail, noun="search"))
+        return 0
+
     # Build NodeFilter from flags (same set as `find` filter mode).
     filter_dict: dict = {}
     if args.service:
@@ -4101,7 +4187,9 @@ def _cmd_search(args: argparse.Namespace) -> int:
         offset=args.offset,
         path_contains=args.path_contains,
         filter=node_filter,
+        explain=args.explain,
         graph=graph,
+        dedup=not getattr(args, "chunks", False),
     )
 
     if not out.success:
@@ -4128,6 +4216,16 @@ def _cmd_search(args: argparse.Namespace) -> int:
             d["id"] = d.get("chunk_id") or d.get("symbol_id") or d.get("fqn") or ""
         if "kind" not in d:
             d["kind"] = "search_hit"
+        # Add explain token when --explain is set
+        if args.explain:
+            from search_lancedb import explain_score_components
+            comps = d.get("score_components")
+            d["explain"] = explain_score_components(
+                comps,
+                role=d.get("role"),
+                hybrid=bool(args.hybrid),
+                graph_expanded=False,
+            )
         hit_dicts.append(d)
 
     # --framework POST-filter: the graph stores `framework` only on Route nodes,
@@ -4156,6 +4254,13 @@ def _cmd_search(args: argparse.Namespace) -> int:
             f"--framework {framework_want!r} filtered out all {framework_dropped} hit(s); "
             f"no symbol's declaring type matched the framework's characteristic annotations"
         )
+    # Zero-result guidance: when a structural filter emptied the page, run one
+    # cheap unfiltered probe and point at where matches actually live (e.g.
+    # "--role SERVICE" returned 0 but matches are under COMPONENT/OTHER).
+    if not hit_dicts and filter_dict:
+        guidance = _zero_result_guidance(args, graph)
+        if guidance:
+            warnings.append(guidance)
     env = Envelope(
         status="ok", nodes=nodes, truncated=truncated,
         warnings=warnings + _auto_scope_notice(args),

java_codebase_rag/jrag_envelope.py

@@ -778,7 +778,7 @@ _BRIEF_NODE_KEYS: frozenset[str] = frozenset(
 # brief + location / classification / ranking. ``file`` is the composed
 # ``filename:start_line`` display field (see :func:`_compose_file`).
 _NORMAL_NODE_KEYS: frozenset[str] = _BRIEF_NODE_KEYS | frozenset(
-    {"module", "role", "symbol_kind", "framework", "file", "score"}
+    {"module", "role", "symbol_kind", "framework", "file", "score", "explain", "chunks"}
 )
 
 # Edge attrs the text renderers read at the default level (target id variants

java_codebase_rag/jrag_render.py

@@ -70,6 +70,8 @@ _NORMAL_INLINE_EXTRAS: tuple[str, ...] = (
     "framework",
     "file",
     "score",
+    "explain",
+    "chunks",
 )
 
 # Identity-adjacent extras shown inline at ``--detail brief``. ``score`` is the
@@ -87,6 +89,13 @@ _EDGE_LINE_KEYS: frozenset[str] = frozenset(
 )
 
 
+def _format_inline_value(value: Any) -> str:
+    """Format a value for inline rendering: round floats to 3 decimals, others verbatim."""
+    if isinstance(value, float):
+        return f"{value:.3f}"
+    return str(value)
+
+
 def _next_action_lines(envelope: Envelope) -> list[str]:
     """Build up to 2 ``next: <hint>`` lines from ``agent_next_actions``.
 
@@ -266,7 +275,7 @@ def _render_listing(envelope: Envelope, *, noun: str, detail: str = "normal") ->
         # of every non-identity key (signature/annotations/snippet/...).
         if detail == "brief":
             extras = [
-                f"{key}={node[key]}"
+                f"{key}={_format_inline_value(node[key])}"
                 for key in _BRIEF_INLINE_EXTRAS
                 if key in node and node[key] not in ("", None)
             ]
@@ -274,9 +283,9 @@ def _render_listing(envelope: Envelope, *, noun: str, detail: str = "normal") ->
                 line += "  " + "  ".join(extras)
         elif detail == "normal":
             extras = [
-                f"{key}={node[key]}"
+                f"{key}={_format_inline_value(node[key])}"
                 for key in _NORMAL_INLINE_EXTRAS
-                if key in node and node[key] not in ("", None)
+                if key in node and node[key] not in ("", None) and not (key == "chunks" and node[key] == 1)
             ]
             if extras:
                 line += "  " + "  ".join(extras)