codecortex 0.8.5__tar.gz → 0.10.0__tar.gz

{codecortex-0.8.5/src/codecortex.egg-info → codecortex-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.8.5
+Version: 0.10.0
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -60,10 +60,13 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | Who calls this? | `callers` | graph | caller symbols + files |
 | What does this call? | `callees` | graph | callee symbols + files |
 | Blast radius of a change | `impact` | graph | callers **and** callees together |
-| Trace a call chain up/downstream | `chain` | graph | ordered hops |
+| Trace a call chain up/downstream | `chain` | graph | ordered, risk-labeled hops |
 | Find symbols by pattern | `pattern` | graph | matching nodes + locations |
 | Project shape at a glance | `overview` | graph → lsp | modules, node/edge counts, languages |
 | Everything about one symbol | `context` | graph + lsp | both views merged |
+| **Impact of your uncommitted edits** | `changed` | graph | changed files → impacted symbols |
+| Refactor-risk hotspots | `hotspots` | graph | highest complexity / fan-in symbols |
+| Unreferenced (dead) code | `deadcode` | graph | non-test symbols with no callers |
 
 Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
 
@@ -99,11 +102,21 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 pip install codecortex
 ```
 
-This installs the `codeintel` CLI; the **semantic** engine works out of the box. The **graph**
-and **LSP** engines use external backends (`codebase-memory-mcp`, and serena via `uvx`) —
-run `codeintel doctor` to see what's available and how to enable the rest. (On PyPI the
+This installs the `codeintel` CLI; the **semantic** engine works out of the box. (On PyPI the
 distribution is `codecortex` because `codeintel` was taken; the CLI and import stay `codeintel`.)
 
+**One command prepares the rest and indexes your repo:**
+
+```bash
+codeintel setup --all /path/to/your/project
+```
+
+This installs `uv` (for the LSP engine), warms serena, downloads the embedding model, indexes the
+repo, and prints a health report ending in a **Next:** list — exactly what's ready and the one
+remaining step. It's idempotent, so re-running is safe. The **graph** engine (`codebase-memory-mcp`)
+is an *optional* external binary that adds who-calls / impact / hotspots / `changed`; codeintel is
+fully usable without it.
+
 Or from source:
 
 ```bash
@@ -112,17 +125,10 @@ cd codeintel
 pip install -e .
 ```
 
-Register with your AI agent(s):
+Register with your AI agent(s), then query:
 
 ```bash
 codeintel install            # registers with Claude, Codex, Gemini, Zed
-```
-
-Index a project, check what's ready, and run your first query:
-
-```bash
-codeintel index /path/to/your/project
-codeintel doctor /path/to/your/project    # which engines are ready + how to fix the rest
 codeintel query --op search --target "authentication middleware"
 ```
 
@@ -174,6 +180,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 - **[Architecture](docs/architecture.md)** — layers, the `CodeProvider` protocol, the safe-null contract, caching, freshness (ASCII + Mermaid).
 - **[Query flow](docs/query-flow.md)** — request lifecycle, engine selection, fan-out & merge, and why it never throws.
 - **[Map file](docs/map-file.md)** — the static `CODE_INTEL.md` orientation layer for hosts with no MCP support.
+- **[Benchmarks](docs/benchmarks.md)** — real numbers at scale: 25 k chunks indexed in ~8 min, ~235 ms warm queries, 60 MB index.
 - Engine references: **[graph](docs/graph.md)** · **[lsp](docs/lsp.md)** · **[semantic](docs/semantic.md)**.
 
 ## CLI reference
@@ -181,7 +188,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | Command | Purpose |
 |---|---|
 | `codeintel install [--agent claude\|codex\|gemini\|zed\|all]` | Register codeintel with AI agent(s) |
-| `codeintel setup [project_root] [--index] [--warm] [--install-uv]` | Check backends + optionally index this repo; ends with a health report |
+| `codeintel setup [project_root] [--all] [--index] [--warm] [--install-uv] [--install-deps] [--json]` | Prepare backends + index this repo (`--all` = one command: do everything automatable, idempotent); ends with a health report + **Next:** steps |
 | `codeintel index [project_root]` | Index a project for semantic search |
 | `codeintel serve` | Start the MCP server (stdio transport) |
 | `codeintel serve-http [--host HOST] [--port 8766] [--allow-remote] [--token TOKEN]` | Start the HTTP transport (loopback-only unless `--allow-remote`; `--token` requires a bearer token on every request) |

{codecortex-0.8.5 → codecortex-0.10.0}/README.md

@@ -26,10 +26,13 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | Who calls this? | `callers` | graph | caller symbols + files |
 | What does this call? | `callees` | graph | callee symbols + files |
 | Blast radius of a change | `impact` | graph | callers **and** callees together |
-| Trace a call chain up/downstream | `chain` | graph | ordered hops |
+| Trace a call chain up/downstream | `chain` | graph | ordered, risk-labeled hops |
 | Find symbols by pattern | `pattern` | graph | matching nodes + locations |
 | Project shape at a glance | `overview` | graph → lsp | modules, node/edge counts, languages |
 | Everything about one symbol | `context` | graph + lsp | both views merged |
+| **Impact of your uncommitted edits** | `changed` | graph | changed files → impacted symbols |
+| Refactor-risk hotspots | `hotspots` | graph | highest complexity / fan-in symbols |
+| Unreferenced (dead) code | `deadcode` | graph | non-test symbols with no callers |
 
 Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
 
@@ -65,11 +68,21 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 pip install codecortex
 ```
 
-This installs the `codeintel` CLI; the **semantic** engine works out of the box. The **graph**
-and **LSP** engines use external backends (`codebase-memory-mcp`, and serena via `uvx`) —
-run `codeintel doctor` to see what's available and how to enable the rest. (On PyPI the
+This installs the `codeintel` CLI; the **semantic** engine works out of the box. (On PyPI the
 distribution is `codecortex` because `codeintel` was taken; the CLI and import stay `codeintel`.)
 
+**One command prepares the rest and indexes your repo:**
+
+```bash
+codeintel setup --all /path/to/your/project
+```
+
+This installs `uv` (for the LSP engine), warms serena, downloads the embedding model, indexes the
+repo, and prints a health report ending in a **Next:** list — exactly what's ready and the one
+remaining step. It's idempotent, so re-running is safe. The **graph** engine (`codebase-memory-mcp`)
+is an *optional* external binary that adds who-calls / impact / hotspots / `changed`; codeintel is
+fully usable without it.
+
 Or from source:
 
 ```bash
@@ -78,17 +91,10 @@ cd codeintel
 pip install -e .
 ```
 
-Register with your AI agent(s):
+Register with your AI agent(s), then query:
 
 ```bash
 codeintel install            # registers with Claude, Codex, Gemini, Zed
-```
-
-Index a project, check what's ready, and run your first query:
-
-```bash
-codeintel index /path/to/your/project
-codeintel doctor /path/to/your/project    # which engines are ready + how to fix the rest
 codeintel query --op search --target "authentication middleware"
 ```
 
@@ -140,6 +146,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 - **[Architecture](docs/architecture.md)** — layers, the `CodeProvider` protocol, the safe-null contract, caching, freshness (ASCII + Mermaid).
 - **[Query flow](docs/query-flow.md)** — request lifecycle, engine selection, fan-out & merge, and why it never throws.
 - **[Map file](docs/map-file.md)** — the static `CODE_INTEL.md` orientation layer for hosts with no MCP support.
+- **[Benchmarks](docs/benchmarks.md)** — real numbers at scale: 25 k chunks indexed in ~8 min, ~235 ms warm queries, 60 MB index.
 - Engine references: **[graph](docs/graph.md)** · **[lsp](docs/lsp.md)** · **[semantic](docs/semantic.md)**.
 
 ## CLI reference
@@ -147,7 +154,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | Command | Purpose |
 |---|---|
 | `codeintel install [--agent claude\|codex\|gemini\|zed\|all]` | Register codeintel with AI agent(s) |
-| `codeintel setup [project_root] [--index] [--warm] [--install-uv]` | Check backends + optionally index this repo; ends with a health report |
+| `codeintel setup [project_root] [--all] [--index] [--warm] [--install-uv] [--install-deps] [--json]` | Prepare backends + index this repo (`--all` = one command: do everything automatable, idempotent); ends with a health report + **Next:** steps |
 | `codeintel index [project_root]` | Index a project for semantic search |
 | `codeintel serve` | Start the MCP server (stdio transport) |
 | `codeintel serve-http [--host HOST] [--port 8766] [--allow-remote] [--token TOKEN]` | Start the HTTP transport (loopback-only unless `--allow-remote`; `--token` requires a bearer token on every request) |

{codecortex-0.8.5 → codecortex-0.10.0/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.8.5
+Version: 0.10.0
 Summary: Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents.
 Author: Shammai Hamilton
 License-Expression: MIT
@@ -60,10 +60,13 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | Who calls this? | `callers` | graph | caller symbols + files |
 | What does this call? | `callees` | graph | callee symbols + files |
 | Blast radius of a change | `impact` | graph | callers **and** callees together |
-| Trace a call chain up/downstream | `chain` | graph | ordered hops |
+| Trace a call chain up/downstream | `chain` | graph | ordered, risk-labeled hops |
 | Find symbols by pattern | `pattern` | graph | matching nodes + locations |
 | Project shape at a glance | `overview` | graph → lsp | modules, node/edge counts, languages |
 | Everything about one symbol | `context` | graph + lsp | both views merged |
+| **Impact of your uncommitted edits** | `changed` | graph | changed files → impacted symbols |
+| Refactor-risk hotspots | `hotspots` | graph | highest complexity / fan-in symbols |
+| Unreferenced (dead) code | `deadcode` | graph | non-test symbols with no callers |
 
 Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
 
@@ -99,11 +102,21 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 pip install codecortex
 ```
 
-This installs the `codeintel` CLI; the **semantic** engine works out of the box. The **graph**
-and **LSP** engines use external backends (`codebase-memory-mcp`, and serena via `uvx`) —
-run `codeintel doctor` to see what's available and how to enable the rest. (On PyPI the
+This installs the `codeintel` CLI; the **semantic** engine works out of the box. (On PyPI the
 distribution is `codecortex` because `codeintel` was taken; the CLI and import stay `codeintel`.)
 
+**One command prepares the rest and indexes your repo:**
+
+```bash
+codeintel setup --all /path/to/your/project
+```
+
+This installs `uv` (for the LSP engine), warms serena, downloads the embedding model, indexes the
+repo, and prints a health report ending in a **Next:** list — exactly what's ready and the one
+remaining step. It's idempotent, so re-running is safe. The **graph** engine (`codebase-memory-mcp`)
+is an *optional* external binary that adds who-calls / impact / hotspots / `changed`; codeintel is
+fully usable without it.
+
 Or from source:
 
 ```bash
@@ -112,17 +125,10 @@ cd codeintel
 pip install -e .
 ```
 
-Register with your AI agent(s):
+Register with your AI agent(s), then query:
 
 ```bash
 codeintel install            # registers with Claude, Codex, Gemini, Zed
-```
-
-Index a project, check what's ready, and run your first query:
-
-```bash
-codeintel index /path/to/your/project
-codeintel doctor /path/to/your/project    # which engines are ready + how to fix the rest
 codeintel query --op search --target "authentication middleware"
 ```
 
@@ -174,6 +180,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 - **[Architecture](docs/architecture.md)** — layers, the `CodeProvider` protocol, the safe-null contract, caching, freshness (ASCII + Mermaid).
 - **[Query flow](docs/query-flow.md)** — request lifecycle, engine selection, fan-out & merge, and why it never throws.
 - **[Map file](docs/map-file.md)** — the static `CODE_INTEL.md` orientation layer for hosts with no MCP support.
+- **[Benchmarks](docs/benchmarks.md)** — real numbers at scale: 25 k chunks indexed in ~8 min, ~235 ms warm queries, 60 MB index.
 - Engine references: **[graph](docs/graph.md)** · **[lsp](docs/lsp.md)** · **[semantic](docs/semantic.md)**.
 
 ## CLI reference
@@ -181,7 +188,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | Command | Purpose |
 |---|---|
 | `codeintel install [--agent claude\|codex\|gemini\|zed\|all]` | Register codeintel with AI agent(s) |
-| `codeintel setup [project_root] [--index] [--warm] [--install-uv]` | Check backends + optionally index this repo; ends with a health report |
+| `codeintel setup [project_root] [--all] [--index] [--warm] [--install-uv] [--install-deps] [--json]` | Prepare backends + index this repo (`--all` = one command: do everything automatable, idempotent); ends with a health report + **Next:** steps |
 | `codeintel index [project_root]` | Index a project for semantic search |
 | `codeintel serve` | Start the MCP server (stdio transport) |
 | `codeintel serve-http [--host HOST] [--port 8766] [--allow-remote] [--token TOKEN]` | Start the HTTP transport (loopback-only unless `--allow-remote`; `--token` requires a bearer token on every request) |

codecortex-0.10.0/src/codeintel/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.10.0"

{codecortex-0.8.5 → codecortex-0.10.0}/src/codeintel/__main__.py

@@ -77,6 +77,9 @@ def main() -> None:
     # setup subcommand
     setup_parser = subparsers.add_parser("setup", parents=[color_parent], help="Prepare backends and optionally index this repo")
     setup_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    setup_parser.add_argument("--all", action="store_true", dest="all_steps",
+                              help="One-command setup: do everything automatable (uv + deps + index + "
+                                   "warm serena). Idempotent — skips what's already installed.")
     setup_parser.add_argument("--install-uv", action="store_true", help="Run `pip install uv` (provides uvx for the LSP engine)")
     setup_parser.add_argument("--install-deps", action="store_true", help="Run `pip install -e .` (semantic engine deps)")
     setup_parser.add_argument("--index", action="store_true", help="Index this repo now (first run downloads the ~50MB model)")
@@ -284,12 +287,13 @@ def main() -> None:
             from codeintel import onboarding
 
             project_root = args.project_root or os.getcwd()
+            all_steps = getattr(args, "all_steps", False)  # --all implies every automatable step
             report = onboarding.run_setup(
                 project_root,
-                install_uv=args.install_uv,
-                install_deps=args.install_deps,
-                do_index=args.index,
-                warm_lsp=args.warm,
+                install_uv=args.install_uv or all_steps,
+                install_deps=args.install_deps or all_steps,
+                do_index=args.index or all_steps,
+                warm_lsp=args.warm or all_steps,
             )
             if args.json:
                 import json as _json

{codecortex-0.8.5 → codecortex-0.10.0}/src/codeintel/doctor.py

@@ -11,6 +11,9 @@ import os
 from typing import Any, Callable, Optional
 
 _ENGINES = ("graph", "lsp", "semantic")
+# Graph needs an external native binary (codebase-memory-mcp) codeintel can't auto-install, so a
+# missing graph engine does NOT make a repo "unhealthy" — the tool is fully usable on semantic + lsp.
+_OPTIONAL_ENGINES = frozenset({"graph"})
 
 
 def _status_for(report: dict) -> str:
@@ -112,13 +115,17 @@ def run_doctor(
         treesitter = False
 
     ready = sum(1 for e in engines.values() if e.get("status") != "fail")
+    # "healthy" ignores OPTIONAL engines (graph): a repo with semantic + lsp ready is healthy even
+    # without the external graph binary. `ready`/`total` stay literal (all three) for transparency.
+    healthy = all(
+        e.get("status") != "fail" for n, e in engines.items() if n not in _OPTIONAL_ENGINES
+    )
     return {
         "ok": True,
         "project_root": root,
         "deep": bool(deep),
         "treesitter": treesitter,
-        "summary": {"ready": ready, "total": len(engines),
-                    "healthy": all(e.get("status") != "fail" for e in engines.values())},
+        "summary": {"ready": ready, "total": len(engines), "healthy": healthy},
         "engines": engines,
     }
 
@@ -168,10 +175,16 @@ def render_doctor_text(report: dict) -> str:
     tail = "" if report.get("deep") else c.dim("  (run with --deep to boot-check serena)")
     out.append("")
     out.append(f"  {count} engines ready for this repo.{tail}")
+    opt_down = [n for n in _ENGINES
+                if n in _OPTIONAL_ENGINES and (engines.get(n) or {}).get("status") == "fail"]
+    if opt_down:
+        out.append("  " + c.dim(
+            f"({', '.join(opt_down)} optional — an external backend; codeintel works without it)"
+        ))
     if healthy is False:
         out.append("  " + c.dim(
-            "tip: `codeintel setup --install-uv --install-deps --index` bootstraps the "
-            "pip-installable backends; each fix: line above has the per-engine command."
+            "tip: `codeintel setup --all` installs + indexes everything automatable in one command; "
+            "each fix: line above has the per-engine command."
         ))
     if report.get("treesitter") is False:
         out.append("  " + c.dim(

{codecortex-0.8.5 → codecortex-0.10.0}/src/codeintel/gateway.py

@@ -20,11 +20,21 @@ _AUTO_ENGINE: dict[str, str] = {
     "chain": "graph",
     "pattern": "graph",
     "overview": "graph",
+    "changed": "graph",
+    "changes": "graph",
+    "deadcode": "graph",
+    "hotspots": "graph",
     "symbol": "lsp",
     "search": "semantic",
     "context": "both",  # fan-out; resolved in Phase 4
 }
 
+# Ops whose answer depends on live, unhashable state (the git worktree) rather than the indexed
+# content the cache key is built from — caching them would serve a stale answer within a freshness
+# generation. `changed` reads uncommitted edits; `deadcode`/`hotspots` are pure functions of the
+# index and stay cached (correctly keyed by the freshness generation).
+_UNCACHED_OPS: frozenset[str] = frozenset({"changed", "changes"})
+
 
 class Gateway:
     def __init__(self, graph=None, lsp=None, semantic=None, policy: TieringPolicy | None = None, reindexer: Reindexer | None = None):
@@ -199,9 +209,17 @@ class Gateway:
             except Exception:
                 freshness = 0
 
+            # Ops that read live, unhashable state (the git worktree) must never be served from the
+            # content-hash cache — it can't see uncommitted edits. Computed ONCE here so it covers
+            # BOTH the fan-out and the single-engine paths below (a miss on either serves a stale diff).
+            uncacheable = op_str in _UNCACHED_OPS
+
             # Fan-out: dispatch to multiple engines concurrently and merge
             if engine_str in _FANOUT_ENGINES:
-                cached_result = self._cache.get(op_str, target_str, engine_str, root_str, freshness)
+                cached_result = (
+                    None if uncacheable
+                    else self._cache.get(op_str, target_str, engine_str, root_str, freshness)
+                )
                 if cached_result is not None:
                     return {**cached_result, "cached": True}
                 if engine_str == "both":
@@ -210,11 +228,15 @@ class Gateway:
                     engines = ["graph", "lsp", "semantic"]
                 fan_results = self._fan_out(engines, op_str, target_str, budget, project_root)
                 result = self._merge(fan_results, op_str, target_str, engine_str)
-                self._cache.put(op_str, target_str, engine_str, root_str, result, freshness)
+                if not uncacheable:
+                    self._cache.put(op_str, target_str, engine_str, root_str, result, freshness)
                 return result
 
-            # Single-engine dispatch
-            cached_result = self._cache.get(op_str, target_str, engine_str, root_str, freshness)
+            # Single-engine dispatch (`uncacheable`, computed above, also guards this path).
+            cached_result = (
+                None if uncacheable
+                else self._cache.get(op_str, target_str, engine_str, root_str, freshness)
+            )
             if cached_result is not None:
                 return {**cached_result, "cached": True}
             provider = self._provider_for(engine_str)
@@ -236,7 +258,8 @@ class Gateway:
                 if lsp_result.get("result") is not None:
                     result = lsp_result
 
-            self._cache.put(op_str, target_str, engine_str, root_str, result, freshness)
+            if not uncacheable:
+                self._cache.put(op_str, target_str, engine_str, root_str, result, freshness)
             return result
 
         except Exception as exc:

{codecortex-0.8.5 → codecortex-0.10.0}/src/codeintel/onboarding.py

@@ -17,12 +17,25 @@ from codeintel import doctor
 _ENGINES = ("graph", "lsp", "semantic")
 
 
+def _platform_tag() -> str:
+    """Best-effort ``System/arch`` (e.g. ``Darwin/arm64``) for platform-specific guidance."""
+    try:
+        import platform
+        return f"{platform.system() or 'your-OS'}/{platform.machine() or 'your-arch'}"
+    except Exception:
+        return "your platform"
+
+
 def _guidance_for(engine: str, probe: dict) -> str:
     """One-line install instructions for an engine that is not installed."""
     try:
         if engine == "graph":
-            return ("install codebase-memory-mcp (a platform-specific binary) and ensure "
-                    "it's on PATH — see its project; then `codeintel index`")
+            # codebase-memory-mcp is a standalone native binary distributed by its own project —
+            # codeintel can't (and shouldn't) auto-download a third-party binary. Frame it as the
+            # OPTIONAL add-on it is: the tool is fully usable on semantic + LSP without it.
+            return (f"OPTIONAL (adds who-calls / impact / hotspots / changed): install the "
+                    f"codebase-memory-mcp binary for {_platform_tag()} on PATH, then re-run setup — "
+                    f"codeintel works without it")
         if engine == "lsp":
             return "install uv (provides uvx): pip install uv — serena is fetched on first use"
         if engine == "semantic":
@@ -123,10 +136,10 @@ def run_setup(
         root = str(project_root or "")
 
     try:
-        if warm_lsp:
-            print("  first serena launch fetches it via uvx; this can be slow the first time…", file=out)
         try:
-            report0 = doctor.run_doctor(root, deep=warm_lsp, lsp_deep_timeout_s=lsp_warm_timeout_s)
+            # Shallow diagnose only — the warm/deep serena boot happens AFTER the install loop (below)
+            # so a freshly-installed uv is visible to it (see the warm_lsp block).
+            report0 = doctor.run_doctor(root, deep=False)
             engines0 = report0.get("engines", {}) if isinstance(report0, dict) else {}
         except Exception as exc:
             engines0 = {}
@@ -136,11 +149,18 @@ def run_setup(
             if probe.get("installed") is False:
                 _step(f"{name}: preflight", probe.get("status", "fail"), _guidance_for(name, probe))
 
-        for flag, pkg_args, step_name in (
-            (install_uv, ["uv"], "install uv"),
-            (install_deps, ["-e", "."], "install deps (-e .)"),
+        # Idempotent installs: skip when the engine already reports installed, so `--all` and re-runs
+        # don't reinstall (lsp installed ⇒ uv/uvx present; semantic installed ⇒ deps present).
+        lsp_installed = (engines0.get("lsp") or {}).get("installed") is True
+        semantic_installed = (engines0.get("semantic") or {}).get("installed") is True
+        for flag, pkg_args, step_name, already in (
+            (install_uv, ["uv"], "install uv", lsp_installed),
+            (install_deps, ["-e", "."], "install deps (-e .)", semantic_installed),
         ):
             if flag:
+                if already:
+                    _step(step_name, "ok", "already satisfied — skipped")
+                    continue
                 r = _pip_install(pkg_args, out=out)
                 _step(step_name, "ok" if r["ok"] else "fail", r["detail"])
 
@@ -157,8 +177,17 @@ def run_setup(
                 _step("index: graph", "warn", f"graph reindex skipped ({type(exc).__name__})")
 
         if warm_lsp:
-            lsp = engines0.get("lsp") or {}
-            _step("warm lsp", lsp.get("status", "warn"), lsp.get("detail", ""))
+            # Warm with a FRESH deep probe AFTER the install loop: on a fresh machine uv was just
+            # installed above, so the pre-install preflight would report lsp missing — emitting a
+            # stale, self-contradictory "warm lsp: fail" under "install uv: ok". Re-probe so the boot
+            # actually runs against the now-present uvx.
+            print("  first serena launch fetches it via uvx; this can be slow the first time…", file=out)
+            try:
+                from codeintel.providers.lsp import LspProvider
+                wl = LspProvider().probe(root, deep=True, timeout_s=lsp_warm_timeout_s)
+                _step("warm lsp", doctor._status_for({**wl, "engine": "lsp"}), wl.get("detail", ""))
+            except Exception as exc:
+                _step("warm lsp", "warn", f"warm attempt failed ({type(exc).__name__})")
 
         try:
             final_doctor = doctor.run_doctor(root)
@@ -170,6 +199,31 @@ def run_setup(
                 "detail": f"setup failed ({type(exc).__name__})"}
 
 
+def _next_steps(doctor_report: dict, root: str) -> list[str]:
+    """The crisp 'what's left' list after a setup pass, computed from the final doctor state —
+    so a user knows the ONE remaining action instead of parsing the engine table."""
+    try:
+        out: list[str] = []
+        engines = doctor_report.get("engines") if isinstance(doctor_report, dict) else None
+        engines = engines if isinstance(engines, dict) else {}
+        _get = lambda name: engines.get(name) if isinstance(engines.get(name), dict) else {}
+        sem, lsp, graph = _get("semantic"), _get("lsp"), _get("graph")
+        if sem.get("installed") is not True:
+            out.append("Semantic engine deps missing — pip install fastembed sqlite-vec")
+        elif sem.get("repo_indexed") is False:
+            out.append(f"Index this repo — codeintel index {root}")
+        if lsp.get("installed") is not True:
+            out.append("LSP engine — pip install uv  (serena auto-fetched on first use)")
+        if graph.get("installed") is not True:
+            out.append(f"Graph engine (OPTIONAL — who-calls/impact/hotspots/changed) — put the "
+                       f"codebase-memory-mcp binary for {_platform_tag()} on PATH")
+        # Always the last mile: an installed+indexed tool does nothing until the agent knows about it.
+        out.append("Make your AI agent use it — codeintel install")
+        return out
+    except Exception:
+        return []
+
+
 def render_setup_text(report: dict) -> str:
     """Human CLI view: a ``[n/N]`` step list, the doctor table, then the overall summary."""
     from codeintel.term import c  # imported at call time so the CLI's term.configure() is honored
@@ -184,14 +238,24 @@ def render_setup_text(report: dict) -> str:
             tail = f"  {c.dim(str(detail))}" if detail else ""
             name = c.bold(str(step.get("name", "")))
             lines.append(f"  [{i}/{n}] {c.glyph(step.get('status', 'na'))} {name}{tail}")
-        if not steps:
-            lines.append(c.dim("  (nothing to do — no opt-in flags set)"))
+        _ACTION_STEPS = {"install uv", "install deps (-e .)", "index: semantic", "index: graph", "warm lsp"}
+        if not any(s.get("name") in _ACTION_STEPS for s in steps):
+            lines.append(c.dim("  (diagnose only — run `codeintel setup --all` to install + index "
+                               "everything automatically)"))
         lines.append("")
         try:
             from codeintel.doctor import render_doctor_text
             lines.append(render_doctor_text(report.get("doctor") or {}))
         except Exception:
             lines.append(c.dim("(doctor report unavailable)"))
+
+        nexts = _next_steps(report.get("doctor") or {}, root)
+        if nexts:
+            lines.append("")
+            lines.append(c.bold("Next:"))
+            for step in nexts:
+                lines.append("  " + c.cyan("→") + " " + step)
+
         lines.append("")
         lines.append(c.green("setup finished") if report.get("ok") else c.red("setup did not complete cleanly"))
         return "\n".join(lines)