codecortex 0.15.4__tar.gz → 0.16.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.15.4
+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,39 +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 | non-test symbols with no callers, **verified against the source** — [treat as candidates, not instructions](#deadcode-is-a-candidate-list-not-a-delete-list) |
+| 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 a candidate list, not a delete list
+`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 the one op whose output invites a destructive action, so it gets an explicit caveat.
-Every hit is re-read and verified against the source before it is reported, which removes the
-common false positives — but **no reachability analysis sees every caller.** Dynamic dispatch,
-registries and decorators, `getattr` lookups, entry points declared in packaging metadata, plugin
-discovery, reflection, and calls from languages the graph does not parse are all invisible to it.
-Through `0.14.x` it was systematically wrong on callback-heavy code and confident about it; that
-class of defect is fixed, but the underlying limit is structural and permanent.
+#### `deadcode` is retired
 
-**So: review each hit before deleting anything, and never wire `deadcode` into an agent that
-deletes without a human in the loop.** Used as a ranked list of *places worth looking*, it is
-genuinely useful. Used as a work order, it will eventually remove live code.
+`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.
 
-**Example — "who uses `safe_null_result`?"**
+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.
 
-```jsonc
-// request
-{ "op": "callers", "target": "safe_null_result", "engine": "auto" }
+**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.
 
-// 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)"
-}
-```
+**The numbers.**
+
+| | 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
 
@@ -175,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.
@@ -358,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) |
@@ -511,26 +549,33 @@ back to grep rather than crashing.
 
 | Area | Why |
 |---|---|
-| `deadcode` | It suggests deletions and cannot see every caller — [read the caveat](#deadcode-is-a-candidate-list-not-a-delete-list). |
+| `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. |
 
 **On the test numbers.** The suite is large and the coverage floor is enforced, but read the figure
-with its caveat: the graph and LSP backends are external binaries that are **not installed in CI**,
-so those two engines are exercised against hand-authored mocks rather than the real wire contract,
-and the release canary — which does assert on real answer text against a built wheel — currently
-covers the semantic engine only. Line coverage measures how much of the intended behavior runs, not
-how much of reality it has met.
+with its caveat. In the **main test job** the graph and LSP backends are absent, so their live tests
+skip and those engines run against hand-authored mocks rather than the real wire contract. Separate
+jobs cover the contract itself: `graph-contract` installs the pinned `codebase-memory-mcp` and runs
+the live graph tests — and **fails if they skipped**, because a silently-skipped contract test is
+how a total backend outage stayed green here once — while the nightly corpus job runs that same
+real backend against pinned third-party repositories. `lsp-contract` runs the live serena tests but
+is **`continue-on-error`**: serena is fetched from an upstream git HEAD this project does not
+control, so a breakage there must be visible without blocking an unrelated release. Read that as
+the LSP wire contract being *watched* rather than *gated*. The release canary — the only check that
+asserts on real answer text from a built wheel — still covers **the semantic engine only**.
+
+Line coverage measures how much of the intended behavior runs, not how much of reality it has met.
 
 **The honest one-paragraph version.** codeintel has been run on very few repositories its author did
 not write, and that is where its bugs have come from — every fix in `0.15.x` came from pointing it
 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, treat `deadcode` as candidates for review, 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.
+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.
 
 **Engine coverage depends on external binaries.** Semantic search works out of the box. The graph
 engine needs `codebase-memory-mcp` and the LSP engine needs `uvx` on `PATH` — without them those

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

@@ -58,39 +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 | non-test symbols with no callers, **verified against the source** — [treat as candidates, not instructions](#deadcode-is-a-candidate-list-not-a-delete-list) |
+| 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 a candidate list, not a delete list
+`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 the one op whose output invites a destructive action, so it gets an explicit caveat.
-Every hit is re-read and verified against the source before it is reported, which removes the
-common false positives — but **no reachability analysis sees every caller.** Dynamic dispatch,
-registries and decorators, `getattr` lookups, entry points declared in packaging metadata, plugin
-discovery, reflection, and calls from languages the graph does not parse are all invisible to it.
-Through `0.14.x` it was systematically wrong on callback-heavy code and confident about it; that
-class of defect is fixed, but the underlying limit is structural and permanent.
+#### `deadcode` is retired
 
-**So: review each hit before deleting anything, and never wire `deadcode` into an agent that
-deletes without a human in the loop.** Used as a ranked list of *places worth looking*, it is
-genuinely useful. Used as a work order, it will eventually remove live code.
+`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.
 
-**Example — "who uses `safe_null_result`?"**
+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.
 
-```jsonc
-// request
-{ "op": "callers", "target": "safe_null_result", "engine": "auto" }
+**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.
 
-// 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)"
-}
-```
+**The numbers.**
+
+| | 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
 
@@ -138,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.
@@ -321,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) |
@@ -474,26 +512,33 @@ back to grep rather than crashing.
 
 | Area | Why |
 |---|---|
-| `deadcode` | It suggests deletions and cannot see every caller — [read the caveat](#deadcode-is-a-candidate-list-not-a-delete-list). |
+| `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. |
 
 **On the test numbers.** The suite is large and the coverage floor is enforced, but read the figure
-with its caveat: the graph and LSP backends are external binaries that are **not installed in CI**,
-so those two engines are exercised against hand-authored mocks rather than the real wire contract,
-and the release canary — which does assert on real answer text against a built wheel — currently
-covers the semantic engine only. Line coverage measures how much of the intended behavior runs, not
-how much of reality it has met.
+with its caveat. In the **main test job** the graph and LSP backends are absent, so their live tests
+skip and those engines run against hand-authored mocks rather than the real wire contract. Separate
+jobs cover the contract itself: `graph-contract` installs the pinned `codebase-memory-mcp` and runs
+the live graph tests — and **fails if they skipped**, because a silently-skipped contract test is
+how a total backend outage stayed green here once — while the nightly corpus job runs that same
+real backend against pinned third-party repositories. `lsp-contract` runs the live serena tests but
+is **`continue-on-error`**: serena is fetched from an upstream git HEAD this project does not
+control, so a breakage there must be visible without blocking an unrelated release. Read that as
+the LSP wire contract being *watched* rather than *gated*. The release canary — the only check that
+asserts on real answer text from a built wheel — still covers **the semantic engine only**.
+
+Line coverage measures how much of the intended behavior runs, not how much of reality it has met.
 
 **The honest one-paragraph version.** codeintel has been run on very few repositories its author did
 not write, and that is where its bugs have come from — every fix in `0.15.x` came from pointing it
 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, treat `deadcode` as candidates for review, 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.
+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.
 
 **Engine coverage depends on external binaries.** Semantic search works out of the box. The graph
 engine needs `codebase-memory-mcp` and the LSP engine needs `uvx` on `PATH` — without them those

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.15.4
+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,39 +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 | non-test symbols with no callers, **verified against the source** — [treat as candidates, not instructions](#deadcode-is-a-candidate-list-not-a-delete-list) |
+| 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 a candidate list, not a delete list
+`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 the one op whose output invites a destructive action, so it gets an explicit caveat.
-Every hit is re-read and verified against the source before it is reported, which removes the
-common false positives — but **no reachability analysis sees every caller.** Dynamic dispatch,
-registries and decorators, `getattr` lookups, entry points declared in packaging metadata, plugin
-discovery, reflection, and calls from languages the graph does not parse are all invisible to it.
-Through `0.14.x` it was systematically wrong on callback-heavy code and confident about it; that
-class of defect is fixed, but the underlying limit is structural and permanent.
+#### `deadcode` is retired
 
-**So: review each hit before deleting anything, and never wire `deadcode` into an agent that
-deletes without a human in the loop.** Used as a ranked list of *places worth looking*, it is
-genuinely useful. Used as a work order, it will eventually remove live code.
+`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.
 
-**Example — "who uses `safe_null_result`?"**
+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.
 
-```jsonc
-// request
-{ "op": "callers", "target": "safe_null_result", "engine": "auto" }
+**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.
 
-// 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)"
-}
-```
+**The numbers.**
+
+| | 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
 
@@ -175,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.
@@ -358,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) |
@@ -511,26 +549,33 @@ back to grep rather than crashing.
 
 | Area | Why |
 |---|---|
-| `deadcode` | It suggests deletions and cannot see every caller — [read the caveat](#deadcode-is-a-candidate-list-not-a-delete-list). |
+| `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. |
 
 **On the test numbers.** The suite is large and the coverage floor is enforced, but read the figure
-with its caveat: the graph and LSP backends are external binaries that are **not installed in CI**,
-so those two engines are exercised against hand-authored mocks rather than the real wire contract,
-and the release canary — which does assert on real answer text against a built wheel — currently
-covers the semantic engine only. Line coverage measures how much of the intended behavior runs, not
-how much of reality it has met.
+with its caveat. In the **main test job** the graph and LSP backends are absent, so their live tests
+skip and those engines run against hand-authored mocks rather than the real wire contract. Separate
+jobs cover the contract itself: `graph-contract` installs the pinned `codebase-memory-mcp` and runs
+the live graph tests — and **fails if they skipped**, because a silently-skipped contract test is
+how a total backend outage stayed green here once — while the nightly corpus job runs that same
+real backend against pinned third-party repositories. `lsp-contract` runs the live serena tests but
+is **`continue-on-error`**: serena is fetched from an upstream git HEAD this project does not
+control, so a breakage there must be visible without blocking an unrelated release. Read that as
+the LSP wire contract being *watched* rather than *gated*. The release canary — the only check that
+asserts on real answer text from a built wheel — still covers **the semantic engine only**.
+
+Line coverage measures how much of the intended behavior runs, not how much of reality it has met.
 
 **The honest one-paragraph version.** codeintel has been run on very few repositories its author did
 not write, and that is where its bugs have come from — every fix in `0.15.x` came from pointing it
 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, treat `deadcode` as candidates for review, 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.
+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.
 
 **Engine coverage depends on external binaries.** Semantic search works out of the box. The graph
 engine needs `codebase-memory-mcp` and the LSP engine needs `uvx` on `PATH` — without them those

{codecortex-0.15.4 → 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
@@ -66,6 +73,8 @@ tests/test_cli_help.py
 tests/test_cold_process.py
 tests/test_config.py
 tests/test_corpus.py
+tests/test_docs_ci_claims.py
+tests/test_docs_deadcode_withdrawal.py
 tests/test_doctor.py
 tests/test_e2e.py
 tests/test_engine_adoption.py
@@ -100,4 +109,5 @@ tests/test_source_kind.py
 tests/test_term.py
 tests/test_treesitter.py
 tests/test_verify.py
-tests/test_verify_call.py
+tests/test_verify_call.py
+tests/test_version_skew.py

codecortex-0.16.0/src/codeintel/__init__.py

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

{codecortex-0.15.4 → 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)")