codecortex 0.15.5__tar.gz → 0.17.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.15.5
+Version: 0.17.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.
@@ -248,7 +279,7 @@ Then it launches the exact command it registered and drives a real MCP handshake
 ```text
 v claude: registered at /Users/you/.claude.json
 
-v verified: codeintel 0.11.2 — 4 tools (code.query, code.status, code.doctor, code.map)
+v verified: codeintel 0.16.0 — 4 tools (code.query, code.status, code.doctor, code.map)
 ```
 
 If the command is not on `PATH`, or the server fails to start, install says so and exits non-zero
@@ -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) |
@@ -375,7 +407,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 
-Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.
+Human-facing commands (`doctor`, `setup`, `prompt`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.
 
 **Exit codes**, so a `make` target or CI step can gate on `$?`:
 
@@ -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.
 
@@ -585,7 +617,7 @@ git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
 
-pytest tests/ -q            # ~620 tests, ~30s; fails under 83% coverage
+pytest tests/ -q            # ~740 tests, ~30s; fails under 83% coverage
 ruff check src tests        # lint
 mypy                        # types (src/ only)
 ```

{codecortex-0.15.5 → codecortex-0.17.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.
@@ -211,7 +242,7 @@ Then it launches the exact command it registered and drives a real MCP handshake
 ```text
 v claude: registered at /Users/you/.claude.json
 
-v verified: codeintel 0.11.2 — 4 tools (code.query, code.status, code.doctor, code.map)
+v verified: codeintel 0.16.0 — 4 tools (code.query, code.status, code.doctor, code.map)
 ```
 
 If the command is not on `PATH`, or the server fails to start, install says so and exits non-zero
@@ -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) |
@@ -338,7 +370,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 
-Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.
+Human-facing commands (`doctor`, `setup`, `prompt`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.
 
 **Exit codes**, so a `make` target or CI step can gate on `$?`:
 
@@ -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.
 
@@ -548,7 +580,7 @@ git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
 
-pytest tests/ -q            # ~620 tests, ~30s; fails under 83% coverage
+pytest tests/ -q            # ~740 tests, ~30s; fails under 83% coverage
 ruff check src tests        # lint
 mypy                        # types (src/ only)
 ```

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.15.5
+Version: 0.17.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.
@@ -248,7 +279,7 @@ Then it launches the exact command it registered and drives a real MCP handshake
 ```text
 v claude: registered at /Users/you/.claude.json
 
-v verified: codeintel 0.11.2 — 4 tools (code.query, code.status, code.doctor, code.map)
+v verified: codeintel 0.16.0 — 4 tools (code.query, code.status, code.doctor, code.map)
 ```
 
 If the command is not on `PATH`, or the server fails to start, install says so and exits non-zero
@@ -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) |
@@ -375,7 +407,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 
-Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.
+Human-facing commands (`doctor`, `setup`, `prompt`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.
 
 **Exit codes**, so a `make` target or CI step can gate on `$?`:
 
@@ -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.
 
@@ -585,7 +617,7 @@ git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
 
-pytest tests/ -q            # ~620 tests, ~30s; fails under 83% coverage
+pytest tests/ -q            # ~740 tests, ~30s; fails under 83% coverage
 ruff check src tests        # lint
 mypy                        # types (src/ only)
 ```

{codecortex-0.15.5 → codecortex-0.17.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
@@ -27,6 +31,7 @@ src/codeintel/metrics.py
 src/codeintel/onboarding.py
 src/codeintel/outcome.py
 src/codeintel/policy.py
+src/codeintel/progress.py
 src/codeintel/provider.py
 src/codeintel/py.typed
 src/codeintel/redact.py
@@ -46,6 +51,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 +65,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
@@ -82,6 +90,8 @@ tests/test_hardening.py
 tests/test_http_auth.py
 tests/test_http_server.py
 tests/test_incompleteness.py
+tests/test_index_progress.py
+tests/test_indexer_binary.py
 tests/test_installer.py
 tests/test_integration.py
 tests/test_loc_census.py

codecortex-0.17.0/src/codeintel/__init__.py

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