codecortex 0.15.5__tar.gz → 0.16.0__tar.gz

{codecortex-0.15.5/src/codecortex.egg-info → codecortex-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.15.5
+Version: 0.16.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
@@ -95,45 +95,61 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | 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 | **withdrawn** — measured wrong in both directions on real repos; safe-nulls with `reason: "op-withdrawn"` unless you opt in — [why, and what to use instead](#deadcode-is-withdrawn) |
+| Unreferenced (dead) code | `deadcode` | graph | **withdrawn and now retired** — a labelled corpus measured its precision at 25%; safe-nulls with `reason: "op-withdrawn"`, and no flag brings it back — [the measurement, and what to use instead](#deadcode-is-retired) |
 
 Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
 
-#### `deadcode` is withdrawn
+`callers`, `callees` and `impact` resolve the target by its **unqualified name**. When several
+symbols share it, each matched symbol's rows are reported separately under its own heading and the
+result says how many it found — narrow to one with a qualified target (`core.Group.invoke`) or a file
+hint (`invoke@src/click/testing.py`); see
+[when several symbols share a name](docs/graph.md#when-several-symbols-share-a-name).
 
-`deadcode` is withdrawn: it returns a safe-null (`reason: "op-withdrawn"`) instead of running. It
-was measured wrong in **both** directions on real repositories — on one it named five candidates of
-which four were live code (a rollup plugin hook; two entries of a `Record<string, fn>` reached by a
-runtime string; a `predicate` passed inline to the call that consumes it), and on another it
-reported "(none found)" for a 4,883-function codebase that had at least three genuinely unreferenced
-private helpers. It is the one op whose output is an instruction to delete code, so it needs the
-highest evidence bar of any op here, and currently has the least. It returns when a labelled corpus
-measures its precision and recall — not before.
+#### `deadcode` is retired
 
-**Use `callers` on a specific symbol instead.** "Does anything call this?" is exactly the question
-`deadcode` was trying to answer in bulk, and `callers` answers it accurately, one symbol at a time.
+`deadcode` no longer exists. Asking for it returns a safe-null (`reason: "op-withdrawn"`) with a hint
+naming what to use instead, and **no flag brings it back** — the implementation has been deleted.
 
-**Escape hatch, if you understand the risk.** Set `CODEINTEL_ENABLE_UNVERIFIED_OPS=1` to run it
-anyway. It still re-reads the source before reporting a hit, which removes the *common* false
-positives — but that verification is exactly what was measured wrong on the repositories above, so
-**review every hit before deleting anything, and never wire it into an agent that deletes without a
-human in the loop.**
+It was withdrawn pending one condition: *"it returns when a labelled corpus measures its precision
+and recall — not before."* That corpus now exists, in
+[`tests/test_corpus.py`](tests/test_corpus.py), and the measurement is what retired it.
 
-**Example — "who uses `safe_null_result`?"**
+**How it was measured.** Two pinned real Python repositories (`pallets/click`, `psf/requests`), with
+every function and method collected from the **AST** — 2,425 definitions, `async def` and class
+methods included, because a verification whose population comes from a pattern like `^\s*def ` cannot
+see half of them. Each is labelled live or dead with the reference behind the label recorded beside
+it. The oracle errs toward *live*: a decorator, a dunder, an override of an external interface, a
+string-dispatch mention, or public-API status is each enough to call a symbol live, so "dead" is only
+what survives all of them. That biases the numbers against the op, which is the correct direction for
+a check whose output is an instruction to delete code. Known-answer canaries are planted in both trees
+so recall has a denominator at all.
 
-```jsonc
-// request
-{ "op": "callers", "target": "safe_null_result", "engine": "auto" }
+**The numbers.**
 
-// response — always this exact envelope; `result` is ready-to-read markdown
-{
-  "ok": true, "op": "callers", "target": "safe_null_result",
-  "engine": "graph", "cached": false,
-  "result": "## Callers of safe_null_result (7)\n- …gateway [USAGE] (src/codeintel/gateway.py)\n- …providers.graph [USAGE] (src/codeintel/providers/graph.py)\n- …server [USAGE] (src/codeintel/server.py)\n- … (4 more)"
-}
-```
+| | precision | recall |
+|---|---|---|
+| as shipped | **25%** (6 of 24) | 60% (6 of 10) |
+| with the two repairs this codebase already contains elsewhere | 89% (8 of 9) | 80% (8 of 10) |
+
+And the measurement that decided it — **real code only, canaries removed**: the op as shipped named
+**18 candidates across those two repositories, and every one of them was live.** All 18 were Makefile
+targets, which the graph backend indexes as `Function` nodes. Repaired, it names exactly one, and
+that one is `MockRequest.get_type` in requests — a method `http.cookiejar` calls by duck-typed
+convention, whose name appears once in the source.
+
+**Why it was not repaired further.** The verification was a name-frequency scan over the source, so it
+fails on exactly one condition: a symbol whose name appears once and is called by a convention
+outside the source. Two repositories produced three distinct instances of that condition — non-code
+nodes labelled `Function`, interpreter-called dunders, and stdlib duck-typed protocol methods — and
+the earlier TypeScript evidence adds a rollup plugin hook and object-literal properties. The set is
+not enumerable: no specification lists `get_type`. Every repository added revealed a new member of it.
+
+Weighed against that: in 2,425 real definitions across two maintained repositories there was **not
+one** dead private symbol to find. An op whose measured yield on real code is zero true positives has
+no benefit to set against that error rate.
 
-The agent hands `result` straight to the model. If the graph backend isn't installed, the identical call returns `"result": null, "reason": "engine-unavailable"` — no exception, and the agent just falls back to its own search.
+**Use `callers` on a specific symbol instead.** "Does anything call this?" is exactly the question
+`deadcode` was trying to answer in bulk, and `callers` answers it accurately, one symbol at a time.
 
 ## What makes it good
 
@@ -181,6 +197,21 @@ codeintel install            # registers with the agents you actually have insta
 codeintel query --op search --target "authentication middleware"
 ```
 
+### Or: have your agent set it up
+
+Prefer to let your coding agent run the steps? Generate a paste-ready prompt, tailored to this
+machine and agent:
+
+```bash
+codeintel prompt                    # this repo — probes health, emits only the steps still outstanding
+codeintel prompt --fresh | pbcopy   # the full sequence from `pip install`, to send a friend
+```
+
+It runs a `doctor` probe and prints a block you copy into Claude Code / Codex / Gemini / Zed: the
+exact remaining commands (or "just restart me" when everything is already healthy and registered),
+a `doctor --deep` verification, and the reminder to restart the agent so the MCP tools load. The
+prompt goes to stdout (so `| pbcopy` grabs exactly it); the "paste this" note goes to stderr.
+
 ### Enable native Codex integration
 
 `codeintel` is an MCP server, so Codex can call its tools directly rather than invoking the CLI.
@@ -364,6 +395,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel help` | Every command grouped by task, with descriptions and examples (also the bare `codeintel`). A mistyped command suggests what you meant. |
 | `codeintel install [--agent auto\|claude\|codex\|gemini\|zed\|all] [--no-verify] [--relative-command]` | Register codeintel with the agents installed on this machine (`auto`, the default), then prove it by completing a real MCP handshake against the registered command |
 | `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 prompt [project_root] [--agent auto\|claude\|codex\|gemini\|zed] [--fresh] [--deep]` | Print a paste-to-your-agent setup prompt; probes health and emits only the outstanding steps (or "just restart me" when already healthy). `--fresh` = the full sequence from `pip install`, to send a friend |
 | `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) |
@@ -517,7 +549,7 @@ back to grep rather than crashing.
 
 | Area | Why |
 |---|---|
-| `deadcode` | Withdrawn by default (`reason: "op-withdrawn"`) — measured wrong in both directions on real repos. Use `callers` on a specific symbol instead — [details](#deadcode-is-withdrawn). |
+| `deadcode` | Withdrawn, then **retired** (`reason: "op-withdrawn"`) — a labelled corpus measured 25% precision. Use `callers` on a specific symbol instead — [the measurement](#deadcode-is-retired). |
 | Non-loopback serving | `serve-http` is stdlib `http.server`. It binds loopback by default for a reason; front it with a reverse proxy and see [docs/deploy.md](docs/deploy.md). |
 | RBAC between **untrusting** tenants | It separates privilege levels among callers you already trust. It is not a wall against an adversary with write access to their own root — see the warning in [docs/deploy.md](docs/deploy.md). |
 | Unattended automation | Anything that acts on a result without a human reading it deserves a pilot first. |
@@ -541,7 +573,7 @@ not write, and that is where its bugs have come from — every fix in `0.15.x` c
 at an unfamiliar codebase. Its characteristic failure mode is **answering confidently from the
 wrong index rather than failing loudly**, which the never-raise contract makes harder to notice: a
 wrong answer and a right one are the same shape. Run `codeintel doctor` before trusting a repo-wide
-answer — and `deadcode` in particular is withdrawn rather than merely caveated (see above) — and if
+answer — and `deadcode` in particular is retired rather than merely caveated (see above) — and if
 something looks off please [report it](#reporting-a-problem) — an issue from someone who is not the
 author is the single most useful thing this project can receive right now.
 

{codecortex-0.15.5 → codecortex-0.16.0}/README.md

@@ -58,45 +58,61 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | 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 | **withdrawn** — measured wrong in both directions on real repos; safe-nulls with `reason: "op-withdrawn"` unless you opt in — [why, and what to use instead](#deadcode-is-withdrawn) |
+| Unreferenced (dead) code | `deadcode` | graph | **withdrawn and now retired** — a labelled corpus measured its precision at 25%; safe-nulls with `reason: "op-withdrawn"`, and no flag brings it back — [the measurement, and what to use instead](#deadcode-is-retired) |
 
 Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
 
-#### `deadcode` is withdrawn
+`callers`, `callees` and `impact` resolve the target by its **unqualified name**. When several
+symbols share it, each matched symbol's rows are reported separately under its own heading and the
+result says how many it found — narrow to one with a qualified target (`core.Group.invoke`) or a file
+hint (`invoke@src/click/testing.py`); see
+[when several symbols share a name](docs/graph.md#when-several-symbols-share-a-name).
 
-`deadcode` is withdrawn: it returns a safe-null (`reason: "op-withdrawn"`) instead of running. It
-was measured wrong in **both** directions on real repositories — on one it named five candidates of
-which four were live code (a rollup plugin hook; two entries of a `Record<string, fn>` reached by a
-runtime string; a `predicate` passed inline to the call that consumes it), and on another it
-reported "(none found)" for a 4,883-function codebase that had at least three genuinely unreferenced
-private helpers. It is the one op whose output is an instruction to delete code, so it needs the
-highest evidence bar of any op here, and currently has the least. It returns when a labelled corpus
-measures its precision and recall — not before.
+#### `deadcode` is retired
 
-**Use `callers` on a specific symbol instead.** "Does anything call this?" is exactly the question
-`deadcode` was trying to answer in bulk, and `callers` answers it accurately, one symbol at a time.
+`deadcode` no longer exists. Asking for it returns a safe-null (`reason: "op-withdrawn"`) with a hint
+naming what to use instead, and **no flag brings it back** — the implementation has been deleted.
 
-**Escape hatch, if you understand the risk.** Set `CODEINTEL_ENABLE_UNVERIFIED_OPS=1` to run it
-anyway. It still re-reads the source before reporting a hit, which removes the *common* false
-positives — but that verification is exactly what was measured wrong on the repositories above, so
-**review every hit before deleting anything, and never wire it into an agent that deletes without a
-human in the loop.**
+It was withdrawn pending one condition: *"it returns when a labelled corpus measures its precision
+and recall — not before."* That corpus now exists, in
+[`tests/test_corpus.py`](tests/test_corpus.py), and the measurement is what retired it.
 
-**Example — "who uses `safe_null_result`?"**
+**How it was measured.** Two pinned real Python repositories (`pallets/click`, `psf/requests`), with
+every function and method collected from the **AST** — 2,425 definitions, `async def` and class
+methods included, because a verification whose population comes from a pattern like `^\s*def ` cannot
+see half of them. Each is labelled live or dead with the reference behind the label recorded beside
+it. The oracle errs toward *live*: a decorator, a dunder, an override of an external interface, a
+string-dispatch mention, or public-API status is each enough to call a symbol live, so "dead" is only
+what survives all of them. That biases the numbers against the op, which is the correct direction for
+a check whose output is an instruction to delete code. Known-answer canaries are planted in both trees
+so recall has a denominator at all.
 
-```jsonc
-// request
-{ "op": "callers", "target": "safe_null_result", "engine": "auto" }
+**The numbers.**
 
-// response — always this exact envelope; `result` is ready-to-read markdown
-{
-  "ok": true, "op": "callers", "target": "safe_null_result",
-  "engine": "graph", "cached": false,
-  "result": "## Callers of safe_null_result (7)\n- …gateway [USAGE] (src/codeintel/gateway.py)\n- …providers.graph [USAGE] (src/codeintel/providers/graph.py)\n- …server [USAGE] (src/codeintel/server.py)\n- … (4 more)"
-}
-```
+| | precision | recall |
+|---|---|---|
+| as shipped | **25%** (6 of 24) | 60% (6 of 10) |
+| with the two repairs this codebase already contains elsewhere | 89% (8 of 9) | 80% (8 of 10) |
+
+And the measurement that decided it — **real code only, canaries removed**: the op as shipped named
+**18 candidates across those two repositories, and every one of them was live.** All 18 were Makefile
+targets, which the graph backend indexes as `Function` nodes. Repaired, it names exactly one, and
+that one is `MockRequest.get_type` in requests — a method `http.cookiejar` calls by duck-typed
+convention, whose name appears once in the source.
+
+**Why it was not repaired further.** The verification was a name-frequency scan over the source, so it
+fails on exactly one condition: a symbol whose name appears once and is called by a convention
+outside the source. Two repositories produced three distinct instances of that condition — non-code
+nodes labelled `Function`, interpreter-called dunders, and stdlib duck-typed protocol methods — and
+the earlier TypeScript evidence adds a rollup plugin hook and object-literal properties. The set is
+not enumerable: no specification lists `get_type`. Every repository added revealed a new member of it.
+
+Weighed against that: in 2,425 real definitions across two maintained repositories there was **not
+one** dead private symbol to find. An op whose measured yield on real code is zero true positives has
+no benefit to set against that error rate.
 
-The agent hands `result` straight to the model. If the graph backend isn't installed, the identical call returns `"result": null, "reason": "engine-unavailable"` — no exception, and the agent just falls back to its own search.
+**Use `callers` on a specific symbol instead.** "Does anything call this?" is exactly the question
+`deadcode` was trying to answer in bulk, and `callers` answers it accurately, one symbol at a time.
 
 ## What makes it good
 
@@ -144,6 +160,21 @@ codeintel install            # registers with the agents you actually have insta
 codeintel query --op search --target "authentication middleware"
 ```
 
+### Or: have your agent set it up
+
+Prefer to let your coding agent run the steps? Generate a paste-ready prompt, tailored to this
+machine and agent:
+
+```bash
+codeintel prompt                    # this repo — probes health, emits only the steps still outstanding
+codeintel prompt --fresh | pbcopy   # the full sequence from `pip install`, to send a friend
+```
+
+It runs a `doctor` probe and prints a block you copy into Claude Code / Codex / Gemini / Zed: the
+exact remaining commands (or "just restart me" when everything is already healthy and registered),
+a `doctor --deep` verification, and the reminder to restart the agent so the MCP tools load. The
+prompt goes to stdout (so `| pbcopy` grabs exactly it); the "paste this" note goes to stderr.
+
 ### Enable native Codex integration
 
 `codeintel` is an MCP server, so Codex can call its tools directly rather than invoking the CLI.
@@ -327,6 +358,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel help` | Every command grouped by task, with descriptions and examples (also the bare `codeintel`). A mistyped command suggests what you meant. |
 | `codeintel install [--agent auto\|claude\|codex\|gemini\|zed\|all] [--no-verify] [--relative-command]` | Register codeintel with the agents installed on this machine (`auto`, the default), then prove it by completing a real MCP handshake against the registered command |
 | `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 prompt [project_root] [--agent auto\|claude\|codex\|gemini\|zed] [--fresh] [--deep]` | Print a paste-to-your-agent setup prompt; probes health and emits only the outstanding steps (or "just restart me" when already healthy). `--fresh` = the full sequence from `pip install`, to send a friend |
 | `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) |
@@ -480,7 +512,7 @@ back to grep rather than crashing.
 
 | Area | Why |
 |---|---|
-| `deadcode` | Withdrawn by default (`reason: "op-withdrawn"`) — measured wrong in both directions on real repos. Use `callers` on a specific symbol instead — [details](#deadcode-is-withdrawn). |
+| `deadcode` | Withdrawn, then **retired** (`reason: "op-withdrawn"`) — a labelled corpus measured 25% precision. Use `callers` on a specific symbol instead — [the measurement](#deadcode-is-retired). |
 | Non-loopback serving | `serve-http` is stdlib `http.server`. It binds loopback by default for a reason; front it with a reverse proxy and see [docs/deploy.md](docs/deploy.md). |
 | RBAC between **untrusting** tenants | It separates privilege levels among callers you already trust. It is not a wall against an adversary with write access to their own root — see the warning in [docs/deploy.md](docs/deploy.md). |
 | Unattended automation | Anything that acts on a result without a human reading it deserves a pilot first. |
@@ -504,7 +536,7 @@ not write, and that is where its bugs have come from — every fix in `0.15.x` c
 at an unfamiliar codebase. Its characteristic failure mode is **answering confidently from the
 wrong index rather than failing loudly**, which the never-raise contract makes harder to notice: a
 wrong answer and a right one are the same shape. Run `codeintel doctor` before trusting a repo-wide
-answer — and `deadcode` in particular is withdrawn rather than merely caveated (see above) — and if
+answer — and `deadcode` in particular is retired rather than merely caveated (see above) — and if
 something looks off please [report it](#reporting-a-problem) — an issue from someone who is not the
 author is the single most useful thing this project can receive right now.
 

{codecortex-0.15.5 → codecortex-0.16.0/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.15.5
+Version: 0.16.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
@@ -95,45 +95,61 @@ It's one call: `code.query(op, target, engine="auto")`. In `auto` mode (the defa
 | 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 | **withdrawn** — measured wrong in both directions on real repos; safe-nulls with `reason: "op-withdrawn"` unless you opt in — [why, and what to use instead](#deadcode-is-withdrawn) |
+| Unreferenced (dead) code | `deadcode` | graph | **withdrawn and now retired** — a labelled corpus measured its precision at 25%; safe-nulls with `reason: "op-withdrawn"`, and no flag brings it back — [the measurement, and what to use instead](#deadcode-is-retired) |
 
 Pin one engine with `--engine graph│lsp│semantic`, or fan out with `--engine both` / `all` to merge results.
 
-#### `deadcode` is withdrawn
+`callers`, `callees` and `impact` resolve the target by its **unqualified name**. When several
+symbols share it, each matched symbol's rows are reported separately under its own heading and the
+result says how many it found — narrow to one with a qualified target (`core.Group.invoke`) or a file
+hint (`invoke@src/click/testing.py`); see
+[when several symbols share a name](docs/graph.md#when-several-symbols-share-a-name).
 
-`deadcode` is withdrawn: it returns a safe-null (`reason: "op-withdrawn"`) instead of running. It
-was measured wrong in **both** directions on real repositories — on one it named five candidates of
-which four were live code (a rollup plugin hook; two entries of a `Record<string, fn>` reached by a
-runtime string; a `predicate` passed inline to the call that consumes it), and on another it
-reported "(none found)" for a 4,883-function codebase that had at least three genuinely unreferenced
-private helpers. It is the one op whose output is an instruction to delete code, so it needs the
-highest evidence bar of any op here, and currently has the least. It returns when a labelled corpus
-measures its precision and recall — not before.
+#### `deadcode` is retired
 
-**Use `callers` on a specific symbol instead.** "Does anything call this?" is exactly the question
-`deadcode` was trying to answer in bulk, and `callers` answers it accurately, one symbol at a time.
+`deadcode` no longer exists. Asking for it returns a safe-null (`reason: "op-withdrawn"`) with a hint
+naming what to use instead, and **no flag brings it back** — the implementation has been deleted.
 
-**Escape hatch, if you understand the risk.** Set `CODEINTEL_ENABLE_UNVERIFIED_OPS=1` to run it
-anyway. It still re-reads the source before reporting a hit, which removes the *common* false
-positives — but that verification is exactly what was measured wrong on the repositories above, so
-**review every hit before deleting anything, and never wire it into an agent that deletes without a
-human in the loop.**
+It was withdrawn pending one condition: *"it returns when a labelled corpus measures its precision
+and recall — not before."* That corpus now exists, in
+[`tests/test_corpus.py`](tests/test_corpus.py), and the measurement is what retired it.
 
-**Example — "who uses `safe_null_result`?"**
+**How it was measured.** Two pinned real Python repositories (`pallets/click`, `psf/requests`), with
+every function and method collected from the **AST** — 2,425 definitions, `async def` and class
+methods included, because a verification whose population comes from a pattern like `^\s*def ` cannot
+see half of them. Each is labelled live or dead with the reference behind the label recorded beside
+it. The oracle errs toward *live*: a decorator, a dunder, an override of an external interface, a
+string-dispatch mention, or public-API status is each enough to call a symbol live, so "dead" is only
+what survives all of them. That biases the numbers against the op, which is the correct direction for
+a check whose output is an instruction to delete code. Known-answer canaries are planted in both trees
+so recall has a denominator at all.
 
-```jsonc
-// request
-{ "op": "callers", "target": "safe_null_result", "engine": "auto" }
+**The numbers.**
 
-// response — always this exact envelope; `result` is ready-to-read markdown
-{
-  "ok": true, "op": "callers", "target": "safe_null_result",
-  "engine": "graph", "cached": false,
-  "result": "## Callers of safe_null_result (7)\n- …gateway [USAGE] (src/codeintel/gateway.py)\n- …providers.graph [USAGE] (src/codeintel/providers/graph.py)\n- …server [USAGE] (src/codeintel/server.py)\n- … (4 more)"
-}
-```
+| | precision | recall |
+|---|---|---|
+| as shipped | **25%** (6 of 24) | 60% (6 of 10) |
+| with the two repairs this codebase already contains elsewhere | 89% (8 of 9) | 80% (8 of 10) |
+
+And the measurement that decided it — **real code only, canaries removed**: the op as shipped named
+**18 candidates across those two repositories, and every one of them was live.** All 18 were Makefile
+targets, which the graph backend indexes as `Function` nodes. Repaired, it names exactly one, and
+that one is `MockRequest.get_type` in requests — a method `http.cookiejar` calls by duck-typed
+convention, whose name appears once in the source.
+
+**Why it was not repaired further.** The verification was a name-frequency scan over the source, so it
+fails on exactly one condition: a symbol whose name appears once and is called by a convention
+outside the source. Two repositories produced three distinct instances of that condition — non-code
+nodes labelled `Function`, interpreter-called dunders, and stdlib duck-typed protocol methods — and
+the earlier TypeScript evidence adds a rollup plugin hook and object-literal properties. The set is
+not enumerable: no specification lists `get_type`. Every repository added revealed a new member of it.
+
+Weighed against that: in 2,425 real definitions across two maintained repositories there was **not
+one** dead private symbol to find. An op whose measured yield on real code is zero true positives has
+no benefit to set against that error rate.
 
-The agent hands `result` straight to the model. If the graph backend isn't installed, the identical call returns `"result": null, "reason": "engine-unavailable"` — no exception, and the agent just falls back to its own search.
+**Use `callers` on a specific symbol instead.** "Does anything call this?" is exactly the question
+`deadcode` was trying to answer in bulk, and `callers` answers it accurately, one symbol at a time.
 
 ## What makes it good
 
@@ -181,6 +197,21 @@ codeintel install            # registers with the agents you actually have insta
 codeintel query --op search --target "authentication middleware"
 ```
 
+### Or: have your agent set it up
+
+Prefer to let your coding agent run the steps? Generate a paste-ready prompt, tailored to this
+machine and agent:
+
+```bash
+codeintel prompt                    # this repo — probes health, emits only the steps still outstanding
+codeintel prompt --fresh | pbcopy   # the full sequence from `pip install`, to send a friend
+```
+
+It runs a `doctor` probe and prints a block you copy into Claude Code / Codex / Gemini / Zed: the
+exact remaining commands (or "just restart me" when everything is already healthy and registered),
+a `doctor --deep` verification, and the reminder to restart the agent so the MCP tools load. The
+prompt goes to stdout (so `| pbcopy` grabs exactly it); the "paste this" note goes to stderr.
+
 ### Enable native Codex integration
 
 `codeintel` is an MCP server, so Codex can call its tools directly rather than invoking the CLI.
@@ -364,6 +395,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel help` | Every command grouped by task, with descriptions and examples (also the bare `codeintel`). A mistyped command suggests what you meant. |
 | `codeintel install [--agent auto\|claude\|codex\|gemini\|zed\|all] [--no-verify] [--relative-command]` | Register codeintel with the agents installed on this machine (`auto`, the default), then prove it by completing a real MCP handshake against the registered command |
 | `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 prompt [project_root] [--agent auto\|claude\|codex\|gemini\|zed] [--fresh] [--deep]` | Print a paste-to-your-agent setup prompt; probes health and emits only the outstanding steps (or "just restart me" when already healthy). `--fresh` = the full sequence from `pip install`, to send a friend |
 | `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) |
@@ -517,7 +549,7 @@ back to grep rather than crashing.
 
 | Area | Why |
 |---|---|
-| `deadcode` | Withdrawn by default (`reason: "op-withdrawn"`) — measured wrong in both directions on real repos. Use `callers` on a specific symbol instead — [details](#deadcode-is-withdrawn). |
+| `deadcode` | Withdrawn, then **retired** (`reason: "op-withdrawn"`) — a labelled corpus measured 25% precision. Use `callers` on a specific symbol instead — [the measurement](#deadcode-is-retired). |
 | Non-loopback serving | `serve-http` is stdlib `http.server`. It binds loopback by default for a reason; front it with a reverse proxy and see [docs/deploy.md](docs/deploy.md). |
 | RBAC between **untrusting** tenants | It separates privilege levels among callers you already trust. It is not a wall against an adversary with write access to their own root — see the warning in [docs/deploy.md](docs/deploy.md). |
 | Unattended automation | Anything that acts on a result without a human reading it deserves a pilot first. |
@@ -541,7 +573,7 @@ not write, and that is where its bugs have come from — every fix in `0.15.x` c
 at an unfamiliar codebase. Its characteristic failure mode is **answering confidently from the
 wrong index rather than failing loudly**, which the never-raise contract makes harder to notice: a
 wrong answer and a right one are the same shape. Run `codeintel doctor` before trusting a repo-wide
-answer — and `deadcode` in particular is withdrawn rather than merely caveated (see above) — and if
+answer — and `deadcode` in particular is retired rather than merely caveated (see above) — and if
 something looks off please [report it](#reporting-a-problem) — an issue from someone who is not the
 author is the single most useful thing this project can receive right now.
 

{codecortex-0.15.5 → codecortex-0.16.0}/src/codecortex.egg-info/SOURCES.txt

@@ -9,12 +9,16 @@ src/codecortex.egg-info/requires.txt
 src/codecortex.egg-info/top_level.txt
 src/codeintel/__init__.py
 src/codeintel/__main__.py
+src/codeintel/agent_prompt.py
 src/codeintel/auth.py
 src/codeintel/cache.py
 src/codeintel/config.py
 src/codeintel/containment.py
 src/codeintel/doctor.py
 src/codeintel/gateway.py
+src/codeintel/graph_backend.py
+src/codeintel/graph_render.py
+src/codeintel/graph_resolution.py
 src/codeintel/grapher.py
 src/codeintel/http_server.py
 src/codeintel/indexer.py
@@ -46,6 +50,7 @@ src/codeintel/commands/graph.py
 src/codeintel/commands/index.py
 src/codeintel/commands/install.py
 src/codeintel/commands/map.py
+src/codeintel/commands/prompt.py
 src/codeintel/commands/query.py
 src/codeintel/commands/reset.py
 src/codeintel/commands/serve.py
@@ -59,6 +64,8 @@ src/codeintel/providers/none.py
 src/codeintel/providers/semantic.py
 src/codeintel/viewer/__init__.py
 src/codeintel/viewer/graph_template.html
+tests/test_agent_prompt.py
+tests/test_backend_reaper.py
 tests/test_cache.py
 tests/test_chunking.py
 tests/test_cli_commands.py

codecortex-0.16.0/src/codeintel/__init__.py

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

{codecortex-0.15.5 → codecortex-0.16.0}/src/codeintel/__main__.py

@@ -18,6 +18,7 @@ _COMMAND_GROUPS: list[tuple[str, list[tuple[str, str]]]] = [
         ("setup", "Prepare backends + index this repo (--all does everything automatable)"),
         ("index", "Index a project for semantic search"),
         ("install", "Register codeintel with the AI agents installed on this machine"),
+        ("prompt", "Print a paste-to-your-agent setup prompt, tailored to this machine"),
     ]),
     ("Check health", [
         ("doctor", "Per-engine health + index status, with the fix for each gap"),
@@ -44,6 +45,7 @@ _MODULES = {
     "setup": "setup",
     "index": "index",
     "install": "install",
+    "prompt": "prompt",
     "doctor": "doctor",
     "status": "status",
     "reset": "reset",
@@ -236,6 +238,18 @@ def main() -> None:
     setup_parser.add_argument("--warm", action="store_true", help="Boot serena now (first run pulls it via uvx; slow)")
     setup_parser.add_argument("--json", action="store_true", help="Emit the structured JSON report")
 
+    # prompt subcommand
+    prompt_parser = subparsers.add_parser("prompt", parents=[color_parent],
+                                          help="Print a paste-to-your-agent setup prompt for this repo")
+    prompt_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    prompt_parser.add_argument("--agent", default="auto",
+                               help="Agent the prompt targets: claude|codex|gemini|zed|auto (default: auto)")
+    prompt_parser.add_argument("--fresh", action="store_true",
+                               help="Emit the full sequence from `pip install`, ignoring local state "
+                                    "(a template to paste to a friend on a clean machine)")
+    prompt_parser.add_argument("--deep", action="store_true",
+                               help="Boot-check serena while probing (slower; sharper 'already set up' result)")
+
     # reset subcommand
     reset_parser = subparsers.add_parser("reset", parents=[color_parent],
                                          help="Clear the semantic index (recover from a corrupt/stale DB)")

codecortex-0.16.0/src/codeintel/agent_prompt.py

@@ -0,0 +1,107 @@
+"""`codeintel prompt` — generate a paste-to-your-agent setup prompt, tailored to this machine.
+
+`setup` DOES the bring-up and `install` REGISTERS the MCP server; this hands the same job to your
+coding agent instead. It runs a doctor probe, sees which engines are actually missing and whether
+this agent is already registered, and prints a natural-language prompt you copy into Claude Code /
+Codex / etc. — telling it the exact remaining commands for THIS repo, to verify with `doctor`, and to
+have you restart it so the MCP tools load. A static prompt would just repeat the README; reflecting
+the live health is what makes it worth a command.
+
+Two modes: the default reflects this machine (it drops steps already satisfied, and when everything
+is healthy and registered it reduces to "just restart me"); `--fresh` ignores local state and emits
+the full sequence from `pip install`, for pasting to a friend on a clean machine.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from codeintel.installer import _AGENTS, detect_agents
+
+# On PyPI the distribution is `codecortex` (the name `codeintel` was taken); the CLI and import stay
+# `codeintel`. A pasted prompt has to name the installable, so this is the one place the CLI spells it.
+_PYPI_PACKAGE = "codecortex"
+
+
+def resolve_agent(agent: str) -> str:
+    """Which agent the prompt targets. A named agent is honoured; `auto` picks the one installed on
+    this machine (the first, if several); `""` when none is detected → the prompt says 'your agent'
+    and omits the `--agent` flag rather than guessing a host you do not have."""
+    a = (agent or "auto").strip().lower()
+    if a in _AGENTS:
+        return a
+    detected = detect_agents()
+    return detected[0] if detected else ""
+
+
+def build_prompt(project_root: str, agent: str, report: dict[str, Any], *, fresh: bool = False) -> str:
+    """The paste-ready prompt, tailored to what *report* (a doctor report) says is still missing.
+
+    Pure and side-effect-free so a test can assert the tailoring without a live backend. With
+    ``fresh=True`` the local state is ignored and every step is emitted."""
+    engines = {} if fresh else (report.get("engines") or {})
+
+    def _ok(name: str) -> bool:
+        return (engines.get(name) or {}).get("status") == "ok"
+
+    graph_ok, lsp_ok, semantic_ok = _ok("graph"), _ok("lsp"), _ok("semantic")
+    healthy = (not fresh) and bool((report.get("summary") or {}).get("healthy"))
+    registered = (not fresh) and any(
+        r.get("agent") == agent and r.get("runnable")
+        for r in (report.get("registrations") or [])
+    )
+    install_flag = f" --agent {agent}" if agent else ""
+    tools = "code.query, code.doctor, code.map"
+
+    # Already fully set up: the one thing an agent cannot do for itself is get restarted.
+    if healthy and registered:
+        return (
+            f"codeintel is already installed and healthy for this project ({project_root}) and "
+            f"registered as one of your MCP servers — nothing to install. Confirm with "
+            f"`codeintel doctor --deep {project_root}` (expect \"ready 3/3, healthy\"), then tell me "
+            f"to restart you so your codeintel MCP tools ({tools}) load."
+        )
+
+    # Emit only the steps that are actually outstanding.
+    steps: list[str] = []
+    pip_targets: list[str] = []
+    if not semantic_ok:
+        pip_targets.append(_PYPI_PACKAGE)
+    if not graph_ok:
+        pip_targets.append("'codebase-memory-mcp==0.9.*'")
+    if pip_targets:
+        adds = " and ".join(
+            part for part in (
+                "the codeintel CLI + semantic engine" if not semantic_ok else "",
+                "the graph engine" if not graph_ok else "",
+            ) if part
+        )
+        steps.append(f"`pip install {' '.join(pip_targets)}` — installs {adds}")
+    # setup --all installs uv, indexes, and warms serena — needed unless all three engines are
+    # already ok (in which case the repo is indexed too, and only registration can be outstanding).
+    if not (graph_ok and lsp_ok and semantic_ok):
+        steps.append(
+            f"`codeintel setup --all {project_root}` — installs uv (the LSP engine), indexes this "
+            f"repo, and warms serena; idempotent, safe to re-run"
+        )
+    if not registered:
+        steps.append(f"`codeintel install{install_flag}` — registers codeintel as my MCP server")
+
+    numbered = "\n".join(f"{i}. {s}" for i, s in enumerate(steps, 1))
+    return (
+        f"Set up the codeintel code-intelligence tool for this project ({project_root}) and wire it "
+        f"into me. Run these in order, showing me the output of each:\n\n{numbered}\n\n"
+        f"Then run `codeintel doctor --deep {project_root}` and show me the result — I expect "
+        f"\"ready 3/3, healthy\". If any engine is not \"ok\", run the exact remediation `doctor` "
+        f"prints for it and re-check. When it is healthy, tell me to restart you so my codeintel MCP "
+        f"tools ({tools}) load."
+    )
+
+
+def run_prompt(project_root: str, agent: str = "auto", *, fresh: bool = False, deep: bool = False) -> str:
+    """Probe (unless ``fresh``) and render the prompt. Never raises here — the command wrapper also
+    guards, but keeping the probe optional means `--fresh` needs no backend at all."""
+    report: dict[str, Any] = {}
+    if not fresh:
+        from codeintel import doctor as _doctor
+        report = _doctor.run_doctor(project_root, deep=deep)
+    return build_prompt(project_root, resolve_agent(agent), report, fresh=fresh)