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

java_codebase_rag/installer.py

@@ -22,10 +22,19 @@ from typing import Literal, NamedTuple
 import yaml
 
 Scope = Literal["project", "user"]
+Surface = Literal["mcp", "cli"]
 
 # MCP server name constant
 _MCP_SERVER_NAME = "java-codebase-rag"
 
+# Marker file written at install time so a CLI-only install (no MCP entry) is
+# still visible to ``update``. Lives at the project/source root alongside
+# ``.java-codebase-rag.yml``. JSON shape:
+#   {"version": 1, "hosts": [{"host": "claude-code", "scope": "project",
+#                             "surface": "mcp"|"cli"}, ...]}
+_MARKER_FILE_NAME = ".java-codebase-rag.hosts"
+_MARKER_FILE_VERSION = 1
+
 # Exit code constants
 EXIT_SUCCESS = 0
 EXIT_PARTIAL = 1
@@ -40,6 +49,20 @@ class ArtifactResult(NamedTuple):
     error: str | None
 
 
+class ConfiguredHost(NamedTuple):
+    """A host installed on this machine: which host, which scope, which surface.
+
+    Replaces the prior 2-tuple ``(HostConfig, scope)`` returned by
+    ``detect_configured_hosts`` so ``update`` can route the refresh through the
+    correct ``Surface`` (an MCP-surface install refreshes MCP+skill+agent; a
+    CLI-surface install refreshes the CLI skill+agent only).
+    """
+
+    host: "HostConfig"
+    scope: Scope
+    surface: Surface
+
+
 @dataclass(frozen=True)
 class HostConfig:
     """Configuration for an agent host."""
@@ -94,6 +117,37 @@ HOSTS: dict[str, HostConfig] = {
 }
 
 
+# ---------------------------------------------------------------------------
+# ArtifactManifest — single source of truth for which artifacts each surface
+# ships. Iterated by both ``deploy_artifacts`` and ``refresh_artifacts`` so
+# adding/removing an artifact is one edit, not two.
+#
+# Each entry is a 3-tuple ``(kind, package_path, dest_relative)``:
+#   - ``kind``: "mcp" dispatches to ``_deploy_mcp_config`` / ``_refresh_mcp_config``
+#     (the MCP config path is host/scope-resolved inside those helpers —
+#     ``package_path`` and ``dest_relative`` are unused for this kind).
+#   - ``kind``: "skill" | "agent" dispatches to ``_deploy_file`` / ``_refresh_file``.
+#   - ``package_path``: relative path under ``install_data/``.
+#   - ``dest_relative``: relative path under ``host.scope_path(scope, cwd)``.
+#
+# The ``mcp`` surface carries the MCP config entry; the ``cli`` surface does
+# NOT (a CLI install never registers an MCP server).
+# ---------------------------------------------------------------------------
+ArtifactManifestEntry = tuple[str, str, str]
+
+ARTIFACT_MANIFEST: dict[Surface, list[ArtifactManifestEntry]] = {
+    "mcp": [
+        ("mcp", "", ""),
+        ("skill", "skills/explore-codebase/SKILL.md", "skills/explore-codebase/SKILL.md"),
+        ("agent", "agents/explorer-rag-enhanced.md", "agents/explorer-rag-enhanced.md"),
+    ],
+    "cli": [
+        ("skill", "skills/explore-codebase-cli/SKILL.md", "skills/explore-codebase-cli/SKILL.md"),
+        ("agent", "agents/explorer-rag-cli.md", "agents/explorer-rag-cli.md"),
+    ],
+}
+
+
 def prompt(
     prompt_type: str,
     message: str,
@@ -136,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":
@@ -421,36 +495,131 @@ def select_scope(*, non_interactive: bool, cli_scope: str | None) -> Scope:
     return selected  # type: ignore
 
 
-def resolve_mcp_command(*, non_interactive: bool) -> str:
-    """Resolve the absolute path to java-codebase-rag-mcp.
+def _surface_choices() -> list[dict]:
+    """Choice list for a surface select prompt.
 
-    Returns the path string for use as MCP 'command' value.
+    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,
+    cli_surface: str | None,
+    prefill: Surface | None = None,
+) -> Surface:
+    """Select 'mcp' or 'cli' surface (PR-JRAG-5).
+
+    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, exit with code 2 when not found
+        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, the cursor defaults to it so the user can keep the prior
+            choice with Enter (``cli`` is still shown first + recommended).
 
     Returns:
-        Absolute path to java-codebase-rag-mcp executable
+        Selected surface (``"mcp"`` or ``"cli"``).
 
     Raises:
-        SystemExit(2): If not found and non-interactive, or user aborts
+        SystemExit(2): if ``cli_surface`` is invalid.
     """
-    mcp_path = shutil.which("java-codebase-rag-mcp")
+    if cli_surface:
+        if cli_surface not in ("mcp", "cli"):
+            print(f"Error: Invalid surface '{cli_surface}'. Must be 'mcp' or 'cli'.")
+            raise SystemExit(2)
+        return cli_surface  # type: ignore
+
+    if non_interactive:
+        # Default to the recommended CLI surface when no flag is passed.
+        return "cli"
+
+    print(
+        "Note: 'cli' surface deploys the `jrag` console-script skill+subagent "
+        "(one command per intent, no MCP server) — recommended."
+    )
+    print(
+        "      'mcp' surface registers the java-codebase-rag MCP server "
+        "(5 tools: search/find/describe/neighbors/resolve)."
+    )
 
-    if mcp_path:
-        return mcp_path
+    # 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",
+        "Select agent surface:",
+        choices=choices,
+        default=default,
+    )
+
+    if not selected:
+        return default
+    return selected  # type: ignore
+
+
+def resolve_mcp_command(*, non_interactive: bool, surface: Surface = "mcp") -> str:
+    """Resolve the absolute path to the runtime binary for the chosen surface.
+
+    - ``surface="mcp"`` (today's behavior): resolve ``java-codebase-rag-mcp``;
+      on missing + non-interactive, exit with code 2.
+    - ``surface="cli"``: resolve the ``jrag`` console script instead. The CLI
+      surface registers no MCP server, so the MCP binary is irrelevant —
+      never raise ``SystemExit(2)`` for a missing MCP binary on this surface.
+      If ``jrag`` is missing, fall through to the interactive prompt (or
+      non-interactive exit) parameterized for ``jrag``.
+
+    Args:
+        non_interactive: If True, exit with code 2 when the target binary
+            is not found.
+        surface: Which surface's binary to resolve.
+
+    Returns:
+        Absolute path to the resolved executable.
+
+    Raises:
+        SystemExit(2): If not found and non-interactive, or user aborts.
+    """
+    binary_name, display_name = _surface_binary(surface)
+    resolved = shutil.which(binary_name)
+
+    if resolved:
+        return resolved
 
     # Not found on PATH
     if non_interactive:
-        print("Error: `java-codebase-rag-mcp` not found on PATH.")
-        print("Ensure `java-codebase-rag` is installed, then re-run with `--non-interactive --agent <host>`.")
+        print(f"Error: `{display_name}` not found on PATH.")
+        if surface == "mcp":
+            print(
+                "Ensure `java-codebase-rag` 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>`."
+            )
         raise SystemExit(2)
 
     # Interactive: prompt user for path
-    print("Warning: `java-codebase-rag-mcp` not found on PATH.")
+    print(f"Warning: `{display_name}` not found on PATH.")
     user_path = prompt(
         "text",
-        "Enter the full path to java-codebase-rag-mcp (or 'abort'):",
+        f"Enter the full path to {display_name} (or 'abort'):",
         default="abort",
     )
 
@@ -466,7 +635,7 @@ def resolve_mcp_command(*, non_interactive: bool) -> str:
         print(f"Error: Path {path_obj} does not exist or is not a file.")
         user_path = prompt(
             "text",
-            "Enter the full path to java-codebase-rag-mcp (or 'abort'):",
+            f"Enter the full path to {display_name} (or 'abort'):",
             default="abort",
         )
         if user_path == "abort" or not user_path:
@@ -482,6 +651,18 @@ def resolve_mcp_command(*, non_interactive: bool) -> str:
     return str(path_obj.resolve())
 
 
+def _surface_binary(surface: Surface) -> tuple[str, str]:
+    """Return ``(shutil_which_target, user_display_name)`` for a surface.
+
+    The CLI surface resolves the ``jrag`` console script (no MCP server is
+    registered, so the MCP binary is irrelevant). The MCP surface keeps
+    today's behavior.
+    """
+    if surface == "cli":
+        return ("jrag", "jrag")
+    return ("java-codebase-rag-mcp", "java-codebase-rag-mcp")
+
+
 def merge_mcp_config(config_path: Path, host: HostConfig, *, mcp_command: str) -> bool:
     """Read, merge, write MCP config. Returns True if entry was added/updated.
 
@@ -536,7 +717,7 @@ def merge_mcp_config(config_path: Path, host: HostConfig, *, mcp_command: str) -
             tmp_name = tmp.name
 
         # Atomic rename
-        os.rename(tmp_name, config_path)
+        os.replace(tmp_name, config_path)
         return True
     except (IOError, OSError) as e:
         if tmp_name:
@@ -562,53 +743,52 @@ def deploy_artifacts(
     *,
     non_interactive: bool,
     mcp_command: str,
+    surface: Surface = "mcp",
 ) -> list[ArtifactResult]:
     """Deploy artifacts (MCP config, skill, agent) to selected hosts.
 
+    Iterates ``ARTIFACT_MANIFEST[surface]`` so both surfaces share one source
+    of truth. The keyword-only ``surface`` defaults to ``"mcp"`` so existing
+    direct-call sites in tests keep working unchanged.
+
     Args:
         hosts: List of HostConfig objects to deploy to
         scope: Installation scope ("project" or "user")
         cwd: Current working directory
         non_interactive: If True, skip overwrite prompts
-        mcp_command: Resolved absolute path to java-codebase-rag-mcp
+        mcp_command: Resolved absolute path to the runtime binary
+            (``java-codebase-rag-mcp`` for ``mcp`` surface; ``jrag`` for
+            ``cli`` surface — unused for the latter since CLI ships no MCP
+            config).
+        surface: Which artifact set to deploy (default ``"mcp"`` for back-comat).
 
     Returns:
         List of ArtifactResult objects for each deployment
     """
     results = []
+    manifest = ARTIFACT_MANIFEST[surface]
 
     for host in hosts:
-        # Deploy MCP config
-        mcp_config_path = host.mcp_config_path(scope, cwd)
-        mcp_result = _deploy_mcp_config(
-            mcp_config_path,
-            host,
-            non_interactive=non_interactive,
-            mcp_command=mcp_command,
-        )
-        results.append(mcp_result)
-
-        # Deploy skill
-        skills_dir = host.skills_dir(scope, cwd)
-        skill_dest = skills_dir / "explore-codebase" / "SKILL.md"
-        skill_result = _deploy_file(
-            skill_dest,
-            "skills/explore-codebase/SKILL.md",
-            artifact_type="skill",
-            non_interactive=non_interactive,
-        )
-        results.append(skill_result)
-
-        # Deploy agent
-        agents_dir = host.agents_dir(scope, cwd)
-        agent_dest = agents_dir / "explorer-rag-enhanced.md"
-        agent_result = _deploy_file(
-            agent_dest,
-            "agents/explorer-rag-enhanced.md",
-            artifact_type="agent",
-            non_interactive=non_interactive,
-        )
-        results.append(agent_result)
+        for kind, package_path, dest_relative in manifest:
+            if kind == "mcp":
+                # Only the MCP surface carries this entry; the CLI manifest
+                # has no "mcp" row by construction.
+                mcp_config_path = host.mcp_config_path(scope, cwd)
+                result = _deploy_mcp_config(
+                    mcp_config_path,
+                    host,
+                    non_interactive=non_interactive,
+                    mcp_command=mcp_command,
+                )
+            else:
+                dest_path = host.scope_path(scope, cwd) / dest_relative
+                result = _deploy_file(
+                    dest_path,
+                    package_path,
+                    artifact_type=kind,
+                    non_interactive=non_interactive,
+                )
+            results.append(result)
 
     return results
 
@@ -847,8 +1027,8 @@ def run_init_if_needed(
     non_interactive: bool,
     quiet: bool,
     verbose: bool = False,
-) -> bool:
-    """Run init if index directory has no artifacts. Return True if init was run.
+) -> bool | None:
+    """Run init if index directory has no artifacts.
 
     The indexing sub-step (CocoIndex update + AST graph build) renders the
     unified ``Vectors → Optimize → Graph`` progress on **stderr** in default
@@ -867,18 +1047,22 @@ def run_init_if_needed(
         verbose: If True, raw-relay subprocess output (no Live region)
 
     Returns:
-        True if init was run, False if skipped
+        True if init ran and succeeded; False if it ran and failed (cocoindex or
+        graph build returned non-zero); None if skipped because the index already
+        exists. Callers must distinguish ``False`` (failure) from ``None`` (skip)
+        so a failed index does not report success (issue #351).
     """
     from java_codebase_rag.config import (
         index_dir_has_existing_artifacts,
         resolve_operator_config,
+        write_config_source_pointer,
     )
-    from java_codebase_rag.pipeline import run_build_ast_graph, run_cocoindex_update
+    from java_codebase_rag.pipeline import is_cocoindex_preflight_blocker, run_build_ast_graph, run_cocoindex_update
 
     has_existing, _ = index_dir_has_existing_artifacts(index_dir)
     if has_existing:
         print("Index already exists. Run `java-codebase-rag reprocess` to rebuild.")
-        return False
+        return None  # skipped, not failed
 
     cfg = resolve_operator_config(
         source_root=source_root,
@@ -912,13 +1096,23 @@ def run_init_if_needed(
             on_progress=on_progress,
             on_progress_console=on_progress_console,
         )
-        if coco.returncode != 0:
+        # Graph-only install (cocoindex absent, e.g. macOS Intel): skip the vectors phase
+        # and build the graph rather than failing install. A genuine non-zero cocoindex
+        # exit still fails.
+        vectors_skipped = is_cocoindex_preflight_blocker(coco)
+        if coco.returncode != 0 and not vectors_skipped:
             print(
                 f"Error: CocoIndex update failed with code {coco.returncode}",
                 file=sys.stderr,
             )
             index_ok = False
         else:
+            if vectors_skipped:
+                print(
+                    "java-codebase-rag: vectors skipped — vector stack not installed on this "
+                    "platform (graph-only mode). Building graph only; semantic search is unavailable.",
+                    file=sys.stderr,
+                )
             g = run_build_ast_graph(
                 source_root=cfg.source_root,
                 ladybug_path=cfg.ladybug_path,
@@ -944,6 +1138,12 @@ def run_init_if_needed(
         if renderer is not None:
             renderer.stop()
             _index_progress_footer("install", started, ok=index_ok)
+    if index_ok:
+        # Remember which YAML built this index so discovery from a sibling/cwd
+        # can relocate the config (e.g. a config beside, not inside, the tree).
+        write_config_source_pointer(
+            index_dir=cfg.index_dir, yaml_config_path=cfg.yaml_config_path
+        )
     return index_ok
 
 
@@ -998,32 +1198,137 @@ def handle_rerun(cwd: Path, *, non_interactive: bool) -> dict | None:
         return existing_config
 
 
-def detect_configured_hosts(cwd: Path) -> list[tuple[HostConfig, str]]:
-    """Scan project + user config files for java-codebase-rag MCP entries.
+def detect_configured_hosts(cwd: Path) -> list[ConfiguredHost]:
+    """Detect hosts installed under ``cwd`` (project) and ``$HOME`` (user).
+
+    Reads the marker file (``.java-codebase-rag.hosts``) written at install
+    time. Falls back to the legacy MCP-entry scan with ``surface="mcp"`` when
+    the marker is absent (pre-marker installs from earlier versions).
+
+    The marker is the single source of truth for CLI-surface installs (which
+    register no MCP entry); without it, a CLI-only install would be invisible
+    to ``update`` (the legacy scan only finds MCP entries).
 
     Args:
-        cwd: Current working directory (for project-scope configs)
+        cwd: Current working directory (project root for project-scope configs)
 
     Returns:
-        List of (host_config, scope) tuples where scope is "project" or "user"
+        List of ``ConfiguredHost(host, scope, surface)`` tuples in marker order
+        (or MCP-scan order in the legacy fallback path).
     """
-    detected = []
-
-    # Check all hosts in both project and user scopes
+    marker_hosts = _read_hosts_marker(cwd)
+    if marker_hosts is not None:
+        return marker_hosts
+
+    # Legacy fallback: scan MCP entries + assume ``mcp`` surface. Pre-marker
+    # installs only ever shipped the MCP surface, so this back-comat mapping
+    # is exact.
+    detected: list[ConfiguredHost] = []
     for host_name, host_config in HOSTS.items():
         # Check project scope
         project_mcp_path = host_config.mcp_config_path("project", cwd)
         if _has_java_codebase_rag_entry(project_mcp_path):
-            detected.append((host_config, "project"))
+            detected.append(ConfiguredHost(host_config, "project", "mcp"))
 
         # Check user scope
         user_mcp_path = host_config.mcp_config_path("user", cwd)
         if _has_java_codebase_rag_entry(user_mcp_path):
-            detected.append((host_config, "user"))
+            detected.append(ConfiguredHost(host_config, "user", "mcp"))
 
     return detected
 
 
+def _marker_path(cwd: Path) -> Path:
+    """Return the marker file path for a project root."""
+    return cwd / _MARKER_FILE_NAME
+
+
+def _write_hosts_marker(
+    project_root: Path, configured: list[ConfiguredHost]
+) -> None:
+    """Write the marker file recording the installed host/scope/surface set.
+
+    Round-trips with ``_read_hosts_marker``. Silently overwrites an existing
+    marker so re-runs (install over an existing install) reflect the latest
+    wizard answers.
+    """
+    payload = {
+        "version": _MARKER_FILE_VERSION,
+        "hosts": [
+            {"host": ch.host.name, "scope": ch.scope, "surface": ch.surface}
+            for ch in configured
+        ],
+    }
+    tmp_name = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            dir=project_root,
+            prefix=f".{_MARKER_FILE_NAME}.",
+            delete=False,
+        ) as tmp:
+            json.dump(payload, tmp, indent=2)
+            tmp.flush()
+            os.fsync(tmp.fileno())
+            tmp_name = tmp.name
+        # os.replace (not os.rename): on Windows, os.rename raises when the
+        # destination exists — the documented re-run path overwrites the prior
+        # marker. os.replace atomically overwrites cross-platform (PR #371
+        # fixed this same pattern elsewhere).
+        os.replace(tmp_name, _marker_path(project_root))
+    except (IOError, OSError) as e:
+        if tmp_name:
+            try:
+                os.unlink(tmp_name)
+            except OSError:
+                pass
+        # Non-fatal: ``update`` will fall back to the MCP-entry scan. Surface
+        # a warning so the operator notices, but do not abort the install.
+        print(f"Warning: failed to write {_marker_path(project_root)}: {e}")
+
+
+def _read_hosts_marker(cwd: Path) -> list[ConfiguredHost] | None:
+    """Read the marker file. Return ``None`` if missing or unparseable.
+
+    On parse/version errors, returns ``None`` so the caller falls back to the
+    MCP-entry scan rather than crashing mid-update.
+    """
+    marker = _marker_path(cwd)
+    if not marker.is_file():
+        return None
+    try:
+        with open(marker, "r") as f:
+            payload = json.load(f)
+    except (json.JSONDecodeError, IOError, OSError):
+        return None
+
+    if not isinstance(payload, dict):
+        return None
+
+    raw_hosts = payload.get("hosts", [])
+    if not isinstance(raw_hosts, list):
+        return None
+
+    configured: list[ConfiguredHost] = []
+    for entry in raw_hosts:
+        if not isinstance(entry, dict):
+            return None
+        host_name = entry.get("host")
+        scope = entry.get("scope")
+        surface = entry.get("surface", "mcp")
+        if host_name not in HOSTS:
+            return None
+        if scope not in ("project", "user"):
+            return None
+        if surface not in ("mcp", "cli"):
+            return None
+        configured.append(
+            ConfiguredHost(HOSTS[host_name], scope, surface)  # type: ignore[arg-type]
+        )
+
+    return configured
+
+
 def _has_java_codebase_rag_entry(config_path: Path) -> bool:
     """Check if MCP config file has a java-codebase-rag entry.
 
@@ -1053,49 +1358,47 @@ def refresh_artifacts(
     *,
     force: bool,
     dry_run: bool,
+    surface: Surface = "mcp",
 ) -> list[ArtifactResult]:
     """Overwrite skill and agent files from package data. Skip MCP if entry is correct.
 
+    Iterates ``ARTIFACT_MANIFEST[surface]`` so both surfaces share one source
+    of truth (PR-JRAG-5). The keyword-only ``surface`` defaults to ``"mcp"``
+    so existing direct-call sites in tests keep working unchanged.
+
     Args:
         host: HostConfig for the agent host
         scope: Installation scope ("project" or "user")
         cwd: Current working directory
         force: If True, overwrite all files even if matching
         dry_run: If True, print changes without writing
+        surface: Which artifact set to refresh (default ``"mcp"`` for back-comat).
 
     Returns:
         List of ArtifactResult objects for each artifact
     """
     results = []
-
-    # Refresh skill file
-    skills_dir = host.skills_dir(scope, cwd)
-    skill_dest = skills_dir / "explore-codebase" / "SKILL.md"
-    skill_result = _refresh_file(
-        skill_dest,
-        "skills/explore-codebase/SKILL.md",
-        artifact_type="skill",
-        force=force,
-        dry_run=dry_run,
-    )
-    results.append(skill_result)
-
-    # Refresh agent file
-    agents_dir = host.agents_dir(scope, cwd)
-    agent_dest = agents_dir / "explorer-rag-enhanced.md"
-    agent_result = _refresh_file(
-        agent_dest,
-        "agents/explorer-rag-enhanced.md",
-        artifact_type="agent",
-        force=force,
-        dry_run=dry_run,
-    )
-    results.append(agent_result)
-
-    # Refresh MCP config (update command path if needed)
-    mcp_config_path = host.mcp_config_path(scope, cwd)
-    mcp_result = _refresh_mcp_config(mcp_config_path, host, force=force, dry_run=dry_run)
-    results.append(mcp_result)
+    manifest = ARTIFACT_MANIFEST[surface]
+
+    for kind, package_path, dest_relative in manifest:
+        if kind == "mcp":
+            # Refresh MCP config (update command path if needed).
+            # NOTE: only the MCP surface has a "mcp" row in its manifest —
+            # ``_refresh_mcp_config`` (and therefore ``resolve_mcp_command``)
+            # is NEVER reached on the CLI surface by construction. The CLI
+            # surface ships no MCP entry, so there is nothing to refresh.
+            mcp_config_path = host.mcp_config_path(scope, cwd)
+            result = _refresh_mcp_config(mcp_config_path, host, force=force, dry_run=dry_run)
+        else:
+            dest_path = host.scope_path(scope, cwd) / dest_relative
+            result = _refresh_file(
+                dest_path,
+                package_path,
+                artifact_type=kind,
+                force=force,
+                dry_run=dry_run,
+            )
+        results.append(result)
 
     return results
 
@@ -1255,7 +1558,7 @@ def _refresh_mcp_config(
                 tmp_name = tmp.name
 
             # Atomic rename
-            os.rename(tmp_name, config_path)
+            os.replace(tmp_name, config_path)
             print(f"Updated MCP config at {config_path}")
             return ArtifactResult(path=config_path, success=True, error=None)
 
@@ -1274,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,
@@ -1281,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.
 
@@ -1292,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)
@@ -1316,12 +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 in configured_hosts:
-        print(f"\nRefreshing {host_config.name} ({scope} scope)...")
-        results = refresh_artifacts(host_config, scope, cwd, force=force, dry_run=dry_run)
-        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]
@@ -1336,8 +1878,9 @@ def run_update(
         discover_project_root,
         index_dir_has_existing_artifacts,
         resolve_operator_config,
+        write_config_source_pointer,
     )
-    from java_codebase_rag.pipeline import run_cocoindex_update, run_incremental_graph
+    from java_codebase_rag.pipeline import is_cocoindex_preflight_blocker, run_cocoindex_update, run_incremental_graph
 
     project_root = discover_project_root(cwd)
     if project_root is None:
@@ -1400,13 +1943,22 @@ def run_update(
                 on_progress=on_progress,
                 on_progress_console=on_progress_console,
             )
-            if coco.returncode != 0:
+            # Graph-only install (cocoindex absent): skip the vectors catch-up and run the
+            # graph catch-up only. A genuine non-zero cocoindex exit still fails.
+            vectors_skipped = is_cocoindex_preflight_blocker(coco)
+            if coco.returncode != 0 and not vectors_skipped:
                 print(
                     f"Error: Lance index update failed with code {coco.returncode}",
                     file=sys.stderr,
                 )
                 index_ok = False
             else:
+                if vectors_skipped:
+                    print(
+                        "java-codebase-rag: vectors skipped — vector stack not installed on this "
+                        "platform (graph-only mode). Running graph catch-up only.",
+                        file=sys.stderr,
+                    )
                 g = run_incremental_graph(
                     source_root=cfg.source_root,
                     ladybug_path=cfg.ladybug_path,
@@ -1440,6 +1992,11 @@ def run_update(
                 _index_progress_footer("update", started, ok=index_ok)
         if not index_ok:
             return 1
+        # Refresh the config pointer so a config moved/renamed since the last
+        # index is relocated correctly by discovery from a sibling/cwd.
+        write_config_source_pointer(
+            index_dir=cfg.index_dir, yaml_config_path=cfg.yaml_config_path
+        )
     else:
         print("\nWould run incremental index update (Lance + graph).")
 
@@ -1457,6 +2014,7 @@ def run_install(
     agents: list[str] | None,
     scope: str | None,
     model: str | None,
+    surface: str | None = None,
     source_root: Path | None = None,
     quiet: bool = False,
     verbose: bool = False,
@@ -1468,6 +2026,7 @@ def run_install(
         agents: List of agent names from CLI flags
         scope: Scope from CLI flag
         model: Model from CLI flag
+        surface: Surface from CLI flag (``"mcp"`` or ``"cli"``; default ``"mcp"``)
         source_root: Source root path (defaults to cwd if None)
         quiet: If True, suppress output
         verbose: If True, raw-relay subprocess indexing output (no Live region)
@@ -1506,23 +2065,44 @@ 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 selection
+    # Stage 3-4: Agent host + scope + surface selection
+    prior_surface = _prior_surface_from_marker(cwd)
     try:
         hosts = select_hosts(non_interactive=non_interactive, cli_agents=agents)
         selected_scope = select_scope(non_interactive=non_interactive, cli_scope=scope)
+        selected_surface = select_surface(
+            non_interactive=non_interactive,
+            cli_surface=surface,
+            prefill=prior_surface,
+        )
     except SystemExit as e:
         return e.code
 
-    # Stage 5: Artifact deployment
-    mcp_command = resolve_mcp_command(non_interactive=non_interactive)
+    # Stage 5: Artifact deployment (manifest iterates the chosen surface)
+    mcp_command = resolve_mcp_command(
+        non_interactive=non_interactive, surface=selected_surface
+    )
     results = deploy_artifacts(
         hosts,
         selected_scope,
         source_root,
         non_interactive=non_interactive,
         mcp_command=mcp_command,
+        surface=selected_surface,
     )
 
     # Check for partial failures
@@ -1531,6 +2111,13 @@ def run_install(
         print("Warning: Some artifacts failed to deploy:")
         for r in partial_failures:
             print(f"  {r.path}: {r.error}")
+        # Severity model: only MCP config (.json/.yml/.yaml) deploy failures are
+        # critical (return 1) -- a broken MCP config means the server cannot start.
+        # Skill/agent (.md / dir) failures are downgraded to non-critical: the
+        # server still runs and the affected host simply lacks those hints. Issue
+        # #351's "treat skill/agent deploy failures as critical for the affected
+        # host" is intentionally DEFERRED here -- promoting them to critical is a
+        # product decision (recoverable vs. fatal) best made explicitly, not bundled.
         if all(
             r.success
             for r in results
@@ -1542,6 +2129,14 @@ def run_install(
             # Critical failures
             return 1
 
+    # Record the host/scope/surface set so a later ``update`` can route the
+    # refresh through the right surface — critical for CLI-only installs (no
+    # MCP entry to scan).
+    configured = [
+        ConfiguredHost(h, selected_scope, selected_surface) for h in hosts
+    ]
+    _write_hosts_marker(source_root, configured)
+
     # Stage 6: Index + finish
     # Generate YAML config
     yaml_content = generate_yaml_config(
@@ -1561,9 +2156,12 @@ def run_install(
     if not quiet:
         print("Configuration written to", config_path)
 
-    # Run init if index directory is empty
+    # Run init if index directory is empty. run_init_if_needed returns True (ran
+    # OK), False (ran and failed — cocoindex/graph non-zero exit), or None
+    # (skipped: index already exists). A failed index must NOT report success in
+    # CI/automation; a skip is not a failure (issue #351).
     index_dir = (source_root / ".java-codebase-rag").resolve()
-    run_init_if_needed(
+    init_outcome = run_init_if_needed(
         source_root,
         index_dir,
         resolved_model,
@@ -1571,5 +2169,20 @@ def run_install(
         quiet=quiet,
         verbose=verbose,
     )
-
+    if init_outcome is False:
+        return 1
     return 0
+
+
+def _prior_surface_from_marker(cwd: Path) -> Surface | None:
+    """Return the (single) surface recorded in the existing marker, if any.
+
+    On multi-surface installs (rare but possible across hosts), returns the
+    first recorded surface — the wizard prefill is a UX nicety, not a contract.
+    Returns ``None`` when no marker exists (fresh install) or the marker is
+    unparseable.
+    """
+    configured = _read_hosts_marker(cwd)
+    if not configured:
+        return None
+    return configured[0].surface