codecortex 0.14.2__tar.gz → 0.15.2__tar.gz

{codecortex-0.14.2/src/codecortex.egg-info → codecortex-0.15.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.14.2
+Version: 0.15.2
 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
@@ -9,7 +9,7 @@ Project-URL: Repository, https://github.com/hamilton-sky/codeintel
 Project-URL: Issues, https://github.com/hamilton-sky/codeintel/issues
 Project-URL: Changelog, https://github.com/hamilton-sky/codeintel/blob/main/CHANGELOG.md
 Keywords: mcp,model-context-protocol,code-intelligence,code-search,llm,agents,lsp,semantic-search,knowledge-graph,static-analysis,developer-tools
-Classifier: Development Status :: 5 - Production/Stable
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Environment :: Console
 Classifier: Operating System :: OS Independent
@@ -40,6 +40,16 @@ Dynamic: license-file
 **One MCP tool that lets a coding agent search, trace, and *understand* a codebase — structurally, not by grepping.** codeintel unifies three engines — a call/import **graph**, an **LSP** for exact symbols, and **semantic** embedding search — behind a single `code.query` call that routes to the right engine, caches the answer, and **never throws**. The agent always gets back a clean, well-formed result to reason over.
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/codecortex.svg)](https://pypi.org/project/codecortex/)
+[![Python](https://img.shields.io/pypi/pyversions/codecortex.svg)](https://pypi.org/project/codecortex/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> **Status: beta (`0.x`), and young.** The `code.query` surface is one call and has been stable
+> since `0.8`, the suite is thorough, and every release is gated by a canary that runs a real query
+> against a built wheel. But this is a new project with a single maintainer, and each time it has
+> been pointed at an unfamiliar codebase it has found real bugs. **Use it locally, on a developer
+> machine, for a single user** — that is the case it is built and tested for. Before relying on it
+> for anything beyond that, read **[Project status](#project-status)**.
 
 ![codeintel's own call graph — an interactive, self-contained HTML view with force / radial / layered / module layouts, complexity-sized nodes, and click-to-inspect metrics.](docs/images/graph-codeintel.png)
 
@@ -85,10 +95,24 @@ 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 |
+| 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) |
 
 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
+
+`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.
+
+**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.
+
 **Example — "who uses `safe_null_result`?"**
 
 ```jsonc
@@ -262,13 +286,25 @@ Every `Gateway.query()` call returns a dict with exactly these keys:
 {"ok": true, "op": "search", "target": "auth", "result": null, "engine": "semantic", "cached": false}
 ```
 
-`ok` is always `true`. `result` is `null` when no provider has an answer — never an exception, never a 500. An optional `reason` key explains null results (e.g. `"engine-unavailable"`, `"no-result"`). Callers must check `result is not None` before using the value.
+`ok` is always `true`. `result` is `null` when no provider has an answer — never an exception, never a 500. Callers must check `result is not None` before using the value.
+
+The optional keys are the ones worth reading when an answer surprises you:
+
+| Key | Meaning |
+|---|---|
+| `reason` | Why `result` is null — `engine-unavailable`, `no-result`, `not-in-graph` (the symbol isn't in the index — usually a stale index), `project-not-indexed`, `unsupported-op`, `root-not-allowed-for-role` (RBAC) |
+| `hint` | The specific command that resolves this `reason`, when there is one |
+| `engine` | Which engine actually answered — not necessarily the one you asked for, under `auto` |
+| `cached` | Whether it came from the content-hash cache |
+| `reindexing` | Present and `true` when a reindex was running, i.e. the answer reflects the last *completed* index. See [Keeping answers fresh](#keeping-answers-fresh) |
+
+`codeintel query --json` prints this envelope from the CLI.
 
 ## Engines
 
 | Engine | Key ops | Install prereq |
 |---|---|---|
-| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` CLI on PATH — see [docs/graph.md](docs/graph.md) |
+| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` **0.9.x** on PATH (`pip install 'codebase-memory-mcp==0.9.*'`) — 0.10.x changed its response format and returns nothing for every op but resolution; see [docs/graph.md](docs/graph.md) |
 | `lsp` | `symbol`, `overview`, `context` | `uvx` on PATH — serena is fetched from GitHub on first use; see [docs/lsp.md](docs/lsp.md) |
 | `semantic` | `search`, `context` | `fastembed` + `sqlite-vec` (installed with the package) — see [docs/semantic.md](docs/semantic.md) |
 
@@ -325,7 +361,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `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) |
-| `codeintel query --op OP --target TARGET [--engine auto] [--project-root DIR]` | Run a single query and print the result |
+| `codeintel query --op OP --target TARGET [--engine auto] [--project-root DIR] [--json]` | Run a single query and print the result |
 | `codeintel status [project_root]` | Show engine availability and index age |
 | `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
 | `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
@@ -335,6 +371,14 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 
 Human-facing commands (`doctor`, `status`, `query`, `setup`, `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 `$?`:
+
+| | |
+|---|---|
+| `0` | The command did its job. For `query` this includes an empty result — "nothing found" is an answer, not a failure. |
+| `1` | The command could not do its job: a file it exists to write wasn't written (`map`, `graph`), an index didn't happen (`index`), a project root doesn't exist, or an engine is unhealthy (`doctor`, `setup`). |
+| `2` | Bad usage — an unknown command or a missing required flag. |
+
 ## Config
 
 Create `.codeintel.toml` at your project root to override defaults:
@@ -362,6 +406,7 @@ Config is **validated on load** — an out-of-range number, a misspelled enum, o
 | `CODEINTEL_HTTP_ACCESS_LOG=1` | One log line per HTTP request (method, path, status, latency) |
 | `CODEINTEL_DEBUG=1` | Log the full traceback of any error the never-throw contract swallows (silent by default) — the switch for diagnosing an unexpected `null` |
 | `CODEINTEL_REINDEX=off` | Disable the background reindexer; queries then index inline to stay fresh |
+| `CODEINTEL_HOME` | Where the index cache lives (default `~/.codeintel`). Set this when the process has **no resolvable home directory** — a container running as a UID with no passwd entry and no `$HOME`, which is common when an agent runs in one. Without it, `Path.home()` raises and every command fails somewhere far from the cause. |
 
 ## Privacy & dependencies
 
@@ -439,6 +484,63 @@ docker build -t codeintel . && docker run -p 127.0.0.1:8766:8766 \
   -e CODEINTEL_HTTP_TOKEN="$(openssl rand -hex 32)" codeintel
 ```
 
+## Project status
+
+An honest picture, so you can decide what to trust this with.
+
+**What's solid.** The suite is large and real — more test code than source, a coverage floor
+enforced in CI, and fault-injection tests behind the never-raise contract. CI runs lint, `mypy`,
+and the full suite on Python 3.11/3.12/3.13, then builds the wheel, installs it into a clean
+environment, and runs a **release canary** that registers the build with Codex and Claude Code in a
+throwaway `HOME`, boots the server those configs name, and asserts on the answer text of a real
+`code.query`. A release that installs into a file no host reads, or that boots and answers nothing,
+fails before it ships. The `code.query` envelope has been stable since `0.8`.
+
+**What's young.** The project is pre-1.0 and moves fast. The honest signal is in the
+[CHANGELOG](CHANGELOG.md): `0.15.0` and `0.15.1` were written almost entirely from pointing the
+tool at four repositories it had never seen, and several of those defects had survived multiple
+adversarial review rounds. **The rate at which new codebases surface new bugs has not yet flattened.**
+Expect to be the first person to hit something, and please report it — see below.
+
+**Use it for.** Local, single-user code intelligence on a developer machine. That is the designed
+case, it is the tested case, and the blast radius of a wrong answer is a wasted tool call: the
+safe-null contract means a failing engine degrades to `null` with a reason, so your agent falls
+back to grep rather than crashing.
+
+**Be careful with.**
+
+| Area | Why |
+|---|---|
+| `deadcode` | It suggests deletions and cannot see every caller — [read the caveat](#deadcode-is-a-candidate-list-not-a-delete-list). |
+| 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.
+
+**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.
+
+**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
+engines safe-null and you get a fraction of the capability table above. `codeintel setup --all`
+installs what it can and `codeintel doctor` tells you exactly what is missing and how to fix it.
+Run `doctor` first if the tool seems quieter than the docs suggest.
+
+**Maintenance.** One maintainer, MIT licensed, issues and PRs welcome. There is no support
+guarantee — factor that into anything load-bearing.
+
 ## Reporting a problem
 
 `codeintel doctor --json` prints a complete, machine-readable picture of what's installed, what's
@@ -452,9 +554,16 @@ codeintel doctor --json
 It reports only local engine and index state. Over the HTTP transport the `registrations` field —
 which names agent config files on the machine running the server — is deliberately omitted.
 
-If a *result* looks wrong rather than a command failing, include the exact `code.query` call and
-its full envelope. `reason`, `hint`, `engine`, `cached`, and `reindexing` between them explain
-which engine answered and how current its index was, which is usually the whole diagnosis.
+If a *result* looks wrong rather than a command failing, send the envelope rather than the
+rendered text:
+
+```bash
+codeintel query --op callers --target yourSymbol --json
+```
+
+`engine` says which engine answered, `cached` whether it came from the cache, `reindexing` whether
+the index was mid-rebuild, and `reason`/`hint` why an empty answer was empty. Those five fields are
+usually the whole diagnosis.
 
 ## Development
 
@@ -463,7 +572,7 @@ git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
 
-pytest tests/ -q            # ~494 tests, ~35s; fails under 83% coverage
+pytest tests/ -q            # ~620 tests, ~30s; fails under 83% coverage
 ruff check src tests        # lint
 mypy                        # types (src/ only)
 ```

{codecortex-0.14.2 → codecortex-0.15.2}/README.md

@@ -3,6 +3,16 @@
 **One MCP tool that lets a coding agent search, trace, and *understand* a codebase — structurally, not by grepping.** codeintel unifies three engines — a call/import **graph**, an **LSP** for exact symbols, and **semantic** embedding search — behind a single `code.query` call that routes to the right engine, caches the answer, and **never throws**. The agent always gets back a clean, well-formed result to reason over.
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/codecortex.svg)](https://pypi.org/project/codecortex/)
+[![Python](https://img.shields.io/pypi/pyversions/codecortex.svg)](https://pypi.org/project/codecortex/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> **Status: beta (`0.x`), and young.** The `code.query` surface is one call and has been stable
+> since `0.8`, the suite is thorough, and every release is gated by a canary that runs a real query
+> against a built wheel. But this is a new project with a single maintainer, and each time it has
+> been pointed at an unfamiliar codebase it has found real bugs. **Use it locally, on a developer
+> machine, for a single user** — that is the case it is built and tested for. Before relying on it
+> for anything beyond that, read **[Project status](#project-status)**.
 
 ![codeintel's own call graph — an interactive, self-contained HTML view with force / radial / layered / module layouts, complexity-sized nodes, and click-to-inspect metrics.](docs/images/graph-codeintel.png)
 
@@ -48,10 +58,24 @@ 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 |
+| 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) |
 
 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
+
+`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.
+
+**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.
+
 **Example — "who uses `safe_null_result`?"**
 
 ```jsonc
@@ -225,13 +249,25 @@ Every `Gateway.query()` call returns a dict with exactly these keys:
 {"ok": true, "op": "search", "target": "auth", "result": null, "engine": "semantic", "cached": false}
 ```
 
-`ok` is always `true`. `result` is `null` when no provider has an answer — never an exception, never a 500. An optional `reason` key explains null results (e.g. `"engine-unavailable"`, `"no-result"`). Callers must check `result is not None` before using the value.
+`ok` is always `true`. `result` is `null` when no provider has an answer — never an exception, never a 500. Callers must check `result is not None` before using the value.
+
+The optional keys are the ones worth reading when an answer surprises you:
+
+| Key | Meaning |
+|---|---|
+| `reason` | Why `result` is null — `engine-unavailable`, `no-result`, `not-in-graph` (the symbol isn't in the index — usually a stale index), `project-not-indexed`, `unsupported-op`, `root-not-allowed-for-role` (RBAC) |
+| `hint` | The specific command that resolves this `reason`, when there is one |
+| `engine` | Which engine actually answered — not necessarily the one you asked for, under `auto` |
+| `cached` | Whether it came from the content-hash cache |
+| `reindexing` | Present and `true` when a reindex was running, i.e. the answer reflects the last *completed* index. See [Keeping answers fresh](#keeping-answers-fresh) |
+
+`codeintel query --json` prints this envelope from the CLI.
 
 ## Engines
 
 | Engine | Key ops | Install prereq |
 |---|---|---|
-| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` CLI on PATH — see [docs/graph.md](docs/graph.md) |
+| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` **0.9.x** on PATH (`pip install 'codebase-memory-mcp==0.9.*'`) — 0.10.x changed its response format and returns nothing for every op but resolution; see [docs/graph.md](docs/graph.md) |
 | `lsp` | `symbol`, `overview`, `context` | `uvx` on PATH — serena is fetched from GitHub on first use; see [docs/lsp.md](docs/lsp.md) |
 | `semantic` | `search`, `context` | `fastembed` + `sqlite-vec` (installed with the package) — see [docs/semantic.md](docs/semantic.md) |
 
@@ -288,7 +324,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `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) |
-| `codeintel query --op OP --target TARGET [--engine auto] [--project-root DIR]` | Run a single query and print the result |
+| `codeintel query --op OP --target TARGET [--engine auto] [--project-root DIR] [--json]` | Run a single query and print the result |
 | `codeintel status [project_root]` | Show engine availability and index age |
 | `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
 | `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
@@ -298,6 +334,14 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 
 Human-facing commands (`doctor`, `status`, `query`, `setup`, `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 `$?`:
+
+| | |
+|---|---|
+| `0` | The command did its job. For `query` this includes an empty result — "nothing found" is an answer, not a failure. |
+| `1` | The command could not do its job: a file it exists to write wasn't written (`map`, `graph`), an index didn't happen (`index`), a project root doesn't exist, or an engine is unhealthy (`doctor`, `setup`). |
+| `2` | Bad usage — an unknown command or a missing required flag. |
+
 ## Config
 
 Create `.codeintel.toml` at your project root to override defaults:
@@ -325,6 +369,7 @@ Config is **validated on load** — an out-of-range number, a misspelled enum, o
 | `CODEINTEL_HTTP_ACCESS_LOG=1` | One log line per HTTP request (method, path, status, latency) |
 | `CODEINTEL_DEBUG=1` | Log the full traceback of any error the never-throw contract swallows (silent by default) — the switch for diagnosing an unexpected `null` |
 | `CODEINTEL_REINDEX=off` | Disable the background reindexer; queries then index inline to stay fresh |
+| `CODEINTEL_HOME` | Where the index cache lives (default `~/.codeintel`). Set this when the process has **no resolvable home directory** — a container running as a UID with no passwd entry and no `$HOME`, which is common when an agent runs in one. Without it, `Path.home()` raises and every command fails somewhere far from the cause. |
 
 ## Privacy & dependencies
 
@@ -402,6 +447,63 @@ docker build -t codeintel . && docker run -p 127.0.0.1:8766:8766 \
   -e CODEINTEL_HTTP_TOKEN="$(openssl rand -hex 32)" codeintel
 ```
 
+## Project status
+
+An honest picture, so you can decide what to trust this with.
+
+**What's solid.** The suite is large and real — more test code than source, a coverage floor
+enforced in CI, and fault-injection tests behind the never-raise contract. CI runs lint, `mypy`,
+and the full suite on Python 3.11/3.12/3.13, then builds the wheel, installs it into a clean
+environment, and runs a **release canary** that registers the build with Codex and Claude Code in a
+throwaway `HOME`, boots the server those configs name, and asserts on the answer text of a real
+`code.query`. A release that installs into a file no host reads, or that boots and answers nothing,
+fails before it ships. The `code.query` envelope has been stable since `0.8`.
+
+**What's young.** The project is pre-1.0 and moves fast. The honest signal is in the
+[CHANGELOG](CHANGELOG.md): `0.15.0` and `0.15.1` were written almost entirely from pointing the
+tool at four repositories it had never seen, and several of those defects had survived multiple
+adversarial review rounds. **The rate at which new codebases surface new bugs has not yet flattened.**
+Expect to be the first person to hit something, and please report it — see below.
+
+**Use it for.** Local, single-user code intelligence on a developer machine. That is the designed
+case, it is the tested case, and the blast radius of a wrong answer is a wasted tool call: the
+safe-null contract means a failing engine degrades to `null` with a reason, so your agent falls
+back to grep rather than crashing.
+
+**Be careful with.**
+
+| Area | Why |
+|---|---|
+| `deadcode` | It suggests deletions and cannot see every caller — [read the caveat](#deadcode-is-a-candidate-list-not-a-delete-list). |
+| 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.
+
+**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.
+
+**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
+engines safe-null and you get a fraction of the capability table above. `codeintel setup --all`
+installs what it can and `codeintel doctor` tells you exactly what is missing and how to fix it.
+Run `doctor` first if the tool seems quieter than the docs suggest.
+
+**Maintenance.** One maintainer, MIT licensed, issues and PRs welcome. There is no support
+guarantee — factor that into anything load-bearing.
+
 ## Reporting a problem
 
 `codeintel doctor --json` prints a complete, machine-readable picture of what's installed, what's
@@ -415,9 +517,16 @@ codeintel doctor --json
 It reports only local engine and index state. Over the HTTP transport the `registrations` field —
 which names agent config files on the machine running the server — is deliberately omitted.
 
-If a *result* looks wrong rather than a command failing, include the exact `code.query` call and
-its full envelope. `reason`, `hint`, `engine`, `cached`, and `reindexing` between them explain
-which engine answered and how current its index was, which is usually the whole diagnosis.
+If a *result* looks wrong rather than a command failing, send the envelope rather than the
+rendered text:
+
+```bash
+codeintel query --op callers --target yourSymbol --json
+```
+
+`engine` says which engine answered, `cached` whether it came from the cache, `reindexing` whether
+the index was mid-rebuild, and `reason`/`hint` why an empty answer was empty. Those five fields are
+usually the whole diagnosis.
 
 ## Development
 
@@ -426,7 +535,7 @@ git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
 
-pytest tests/ -q            # ~494 tests, ~35s; fails under 83% coverage
+pytest tests/ -q            # ~620 tests, ~30s; fails under 83% coverage
 ruff check src tests        # lint
 mypy                        # types (src/ only)
 ```

{codecortex-0.14.2 → codecortex-0.15.2}/pyproject.toml

@@ -19,7 +19,11 @@ keywords = [
     "lsp", "semantic-search", "knowledge-graph", "static-analysis", "developer-tools",
 ]
 classifiers = [
-    "Development Status :: 5 - Production/Stable",
+    # Beta, deliberately. The package is well-tested and the `code.query` surface has been stable
+    # since 0.8, but the project is young, pre-1.0, and still finding real defects each time it
+    # meets an unfamiliar repository. "Production/Stable" is a claim to make after that curve
+    # flattens and external users have exercised it — not before.
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "Environment :: Console",
     "Operating System :: OS Independent",

{codecortex-0.14.2 → codecortex-0.15.2/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.14.2
+Version: 0.15.2
 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
@@ -9,7 +9,7 @@ Project-URL: Repository, https://github.com/hamilton-sky/codeintel
 Project-URL: Issues, https://github.com/hamilton-sky/codeintel/issues
 Project-URL: Changelog, https://github.com/hamilton-sky/codeintel/blob/main/CHANGELOG.md
 Keywords: mcp,model-context-protocol,code-intelligence,code-search,llm,agents,lsp,semantic-search,knowledge-graph,static-analysis,developer-tools
-Classifier: Development Status :: 5 - Production/Stable
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Environment :: Console
 Classifier: Operating System :: OS Independent
@@ -40,6 +40,16 @@ Dynamic: license-file
 **One MCP tool that lets a coding agent search, trace, and *understand* a codebase — structurally, not by grepping.** codeintel unifies three engines — a call/import **graph**, an **LSP** for exact symbols, and **semantic** embedding search — behind a single `code.query` call that routes to the right engine, caches the answer, and **never throws**. The agent always gets back a clean, well-formed result to reason over.
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/codecortex.svg)](https://pypi.org/project/codecortex/)
+[![Python](https://img.shields.io/pypi/pyversions/codecortex.svg)](https://pypi.org/project/codecortex/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> **Status: beta (`0.x`), and young.** The `code.query` surface is one call and has been stable
+> since `0.8`, the suite is thorough, and every release is gated by a canary that runs a real query
+> against a built wheel. But this is a new project with a single maintainer, and each time it has
+> been pointed at an unfamiliar codebase it has found real bugs. **Use it locally, on a developer
+> machine, for a single user** — that is the case it is built and tested for. Before relying on it
+> for anything beyond that, read **[Project status](#project-status)**.
 
 ![codeintel's own call graph — an interactive, self-contained HTML view with force / radial / layered / module layouts, complexity-sized nodes, and click-to-inspect metrics.](docs/images/graph-codeintel.png)
 
@@ -85,10 +95,24 @@ 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 |
+| 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) |
 
 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
+
+`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.
+
+**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.
+
 **Example — "who uses `safe_null_result`?"**
 
 ```jsonc
@@ -262,13 +286,25 @@ Every `Gateway.query()` call returns a dict with exactly these keys:
 {"ok": true, "op": "search", "target": "auth", "result": null, "engine": "semantic", "cached": false}
 ```
 
-`ok` is always `true`. `result` is `null` when no provider has an answer — never an exception, never a 500. An optional `reason` key explains null results (e.g. `"engine-unavailable"`, `"no-result"`). Callers must check `result is not None` before using the value.
+`ok` is always `true`. `result` is `null` when no provider has an answer — never an exception, never a 500. Callers must check `result is not None` before using the value.
+
+The optional keys are the ones worth reading when an answer surprises you:
+
+| Key | Meaning |
+|---|---|
+| `reason` | Why `result` is null — `engine-unavailable`, `no-result`, `not-in-graph` (the symbol isn't in the index — usually a stale index), `project-not-indexed`, `unsupported-op`, `root-not-allowed-for-role` (RBAC) |
+| `hint` | The specific command that resolves this `reason`, when there is one |
+| `engine` | Which engine actually answered — not necessarily the one you asked for, under `auto` |
+| `cached` | Whether it came from the content-hash cache |
+| `reindexing` | Present and `true` when a reindex was running, i.e. the answer reflects the last *completed* index. See [Keeping answers fresh](#keeping-answers-fresh) |
+
+`codeintel query --json` prints this envelope from the CLI.
 
 ## Engines
 
 | Engine | Key ops | Install prereq |
 |---|---|---|
-| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` CLI on PATH — see [docs/graph.md](docs/graph.md) |
+| `graph` | `impact`, `callers`, `callees`, `chain`, `pattern`, `overview`, `context` | `codebase-memory-mcp` **0.9.x** on PATH (`pip install 'codebase-memory-mcp==0.9.*'`) — 0.10.x changed its response format and returns nothing for every op but resolution; see [docs/graph.md](docs/graph.md) |
 | `lsp` | `symbol`, `overview`, `context` | `uvx` on PATH — serena is fetched from GitHub on first use; see [docs/lsp.md](docs/lsp.md) |
 | `semantic` | `search`, `context` | `fastembed` + `sqlite-vec` (installed with the package) — see [docs/semantic.md](docs/semantic.md) |
 
@@ -325,7 +361,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 | `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) |
-| `codeintel query --op OP --target TARGET [--engine auto] [--project-root DIR]` | Run a single query and print the result |
+| `codeintel query --op OP --target TARGET [--engine auto] [--project-root DIR] [--json]` | Run a single query and print the result |
 | `codeintel status [project_root]` | Show engine availability and index age |
 | `codeintel doctor [project_root] [--deep] [--json]` | Diagnose per-engine health + repo index status, with a fix for each gap |
 | `codeintel map [project_root]` | Generate the `CODE_INTEL.md` orientation file |
@@ -335,6 +371,14 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 
 Human-facing commands (`doctor`, `status`, `query`, `setup`, `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 `$?`:
+
+| | |
+|---|---|
+| `0` | The command did its job. For `query` this includes an empty result — "nothing found" is an answer, not a failure. |
+| `1` | The command could not do its job: a file it exists to write wasn't written (`map`, `graph`), an index didn't happen (`index`), a project root doesn't exist, or an engine is unhealthy (`doctor`, `setup`). |
+| `2` | Bad usage — an unknown command or a missing required flag. |
+
 ## Config
 
 Create `.codeintel.toml` at your project root to override defaults:
@@ -362,6 +406,7 @@ Config is **validated on load** — an out-of-range number, a misspelled enum, o
 | `CODEINTEL_HTTP_ACCESS_LOG=1` | One log line per HTTP request (method, path, status, latency) |
 | `CODEINTEL_DEBUG=1` | Log the full traceback of any error the never-throw contract swallows (silent by default) — the switch for diagnosing an unexpected `null` |
 | `CODEINTEL_REINDEX=off` | Disable the background reindexer; queries then index inline to stay fresh |
+| `CODEINTEL_HOME` | Where the index cache lives (default `~/.codeintel`). Set this when the process has **no resolvable home directory** — a container running as a UID with no passwd entry and no `$HOME`, which is common when an agent runs in one. Without it, `Path.home()` raises and every command fails somewhere far from the cause. |
 
 ## Privacy & dependencies
 
@@ -439,6 +484,63 @@ docker build -t codeintel . && docker run -p 127.0.0.1:8766:8766 \
   -e CODEINTEL_HTTP_TOKEN="$(openssl rand -hex 32)" codeintel
 ```
 
+## Project status
+
+An honest picture, so you can decide what to trust this with.
+
+**What's solid.** The suite is large and real — more test code than source, a coverage floor
+enforced in CI, and fault-injection tests behind the never-raise contract. CI runs lint, `mypy`,
+and the full suite on Python 3.11/3.12/3.13, then builds the wheel, installs it into a clean
+environment, and runs a **release canary** that registers the build with Codex and Claude Code in a
+throwaway `HOME`, boots the server those configs name, and asserts on the answer text of a real
+`code.query`. A release that installs into a file no host reads, or that boots and answers nothing,
+fails before it ships. The `code.query` envelope has been stable since `0.8`.
+
+**What's young.** The project is pre-1.0 and moves fast. The honest signal is in the
+[CHANGELOG](CHANGELOG.md): `0.15.0` and `0.15.1` were written almost entirely from pointing the
+tool at four repositories it had never seen, and several of those defects had survived multiple
+adversarial review rounds. **The rate at which new codebases surface new bugs has not yet flattened.**
+Expect to be the first person to hit something, and please report it — see below.
+
+**Use it for.** Local, single-user code intelligence on a developer machine. That is the designed
+case, it is the tested case, and the blast radius of a wrong answer is a wasted tool call: the
+safe-null contract means a failing engine degrades to `null` with a reason, so your agent falls
+back to grep rather than crashing.
+
+**Be careful with.**
+
+| Area | Why |
+|---|---|
+| `deadcode` | It suggests deletions and cannot see every caller — [read the caveat](#deadcode-is-a-candidate-list-not-a-delete-list). |
+| 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.
+
+**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.
+
+**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
+engines safe-null and you get a fraction of the capability table above. `codeintel setup --all`
+installs what it can and `codeintel doctor` tells you exactly what is missing and how to fix it.
+Run `doctor` first if the tool seems quieter than the docs suggest.
+
+**Maintenance.** One maintainer, MIT licensed, issues and PRs welcome. There is no support
+guarantee — factor that into anything load-bearing.
+
 ## Reporting a problem
 
 `codeintel doctor --json` prints a complete, machine-readable picture of what's installed, what's
@@ -452,9 +554,16 @@ codeintel doctor --json
 It reports only local engine and index state. Over the HTTP transport the `registrations` field —
 which names agent config files on the machine running the server — is deliberately omitted.
 
-If a *result* looks wrong rather than a command failing, include the exact `code.query` call and
-its full envelope. `reason`, `hint`, `engine`, `cached`, and `reindexing` between them explain
-which engine answered and how current its index was, which is usually the whole diagnosis.
+If a *result* looks wrong rather than a command failing, send the envelope rather than the
+rendered text:
+
+```bash
+codeintel query --op callers --target yourSymbol --json
+```
+
+`engine` says which engine answered, `cached` whether it came from the cache, `reindexing` whether
+the index was mid-rebuild, and `reason`/`hint` why an empty answer was empty. Those five fields are
+usually the whole diagnosis.
 
 ## Development
 
@@ -463,7 +572,7 @@ git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
 
-pytest tests/ -q            # ~494 tests, ~35s; fails under 83% coverage
+pytest tests/ -q            # ~620 tests, ~30s; fails under 83% coverage
 ruff check src tests        # lint
 mypy                        # types (src/ only)
 ```