codecortex 0.11.0__tar.gz → 0.12.0__tar.gz

{codecortex-0.11.0/src/codecortex.egg-info → codecortex-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.11.0
+Version: 0.12.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
@@ -38,6 +38,22 @@ Dynamic: license-file
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
 
+![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)
+
+> *codeintel visualizing its own codebase.* One command — `codeintel graph <repo> --html` — turns any indexed repo into a **self-contained, interactive call graph** you can open offline or share as a file. Layouts, complexity-sized nodes, click-to-inspect metrics, and JSON/Markdown/SVG/PNG export. See **[docs/graph-viewer.md](docs/graph-viewer.md)**.
+
+Prefer plain text? `codeintel map` writes a **readable architecture overview** to `CODE_INTEL.md` — node/edge counts, ranked symbols by caller count, and entry points — for skimming or for MCP hosts that can't render a graph:
+
+<img src="docs/images/code-intel-map.png" width="520" alt="CODE_INTEL.md — the codeintel map: an architecture overview with node/edge counts and symbols ranked by caller count.">
+
+**What `CODE_INTEL.md` is for.** It's a *static, committable* snapshot of a codebase's shape — meant to be read (by a person or an agent) **first**, instead of reconstructing structure by grepping. It covers the cases the live `code.query` tool doesn't:
+
+- **Agents & hosts that don't speak MCP.** Not every agent supports MCP, and the server isn't always running. `codeintel map` writes a plain file any agent can read; `codeintel map --inject` also drops a pointer into `CLAUDE.md` / `AGENTS.md`, so an agent picks up the codebase's structure automatically at the start of a session.
+- **A committed, diffable overview.** It lives *in the repo* — reviewable in a PR, browsable on GitHub, available offline. Re-run `codeintel map` after `codeintel index` to refresh it.
+- **The load-bearing code at a glance.** Ranking symbols by caller count surfaces what most of the codebase depends on (the risky-to-change core) plus the entry points — the first things a newcomer, or an agent, should understand before touching anything.
+
+See **[docs/map-file.md](docs/map-file.md)** for the format and the `--inject` flow.
+
 ## Why an agent needs it
 
 Without structural tools, an agent dropped into unfamiliar code falls back on `grep` and reads whole files to reconstruct relationships by hand — burning tokens, missing call sites, and guessing at blast radius before it edits anything. codeintel answers those questions directly instead:
@@ -94,7 +110,7 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 - **Degrades instead of breaking.** No graph backend installed? That engine returns `null` and the agent falls back to grep. The semantic engine needs nothing external, so codeintel is useful the moment it's installed and only gets sharper as you add backends.
 - **Fast on repeat, never stale.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index — answers stay both quick *and* fresh. The cache is bounded (LRU), so a long-running server holds steady memory.
 - **Concurrency-safe.** The HTTP transport handles requests on threads, so one slow query (an LSP session warming, a first-time index) can't block every other agent.
-- **Honest about its own health.** `codeintel doctor` reports exactly which engines are ready for a repo and the single command to fix each gap — no guessing why a query came back empty.
+- **Honest about its own health.** `codeintel doctor` answers three separate questions per engine — *installed?* *runnable?* *is this repo indexed?* — with the single command to fix each gap, so "installed" is never mistaken for "working". And a readiness claim is one a query can actually honor: install a missing backend mid-session and the running server picks it up on the next call, rather than reporting the engine healthy while quietly routing around it until you restart the host.
 
 ## Quickstart
 
@@ -128,10 +144,91 @@ pip install -e .
 Register with your AI agent(s), then query:
 
 ```bash
-codeintel install            # registers with Claude, Codex, Gemini, Zed
+codeintel install            # registers with the agents you actually have installed
 codeintel query --op search --target "authentication middleware"
 ```
 
+### Enable native Codex integration
+
+`codeintel` is an MCP server, so Codex can call its tools directly rather than invoking the CLI.
+After installing the package, explicitly register it with Codex:
+
+```bash
+codeintel install --agent codex
+```
+
+This safely adds a `[mcp_servers.codeintel]` entry to `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`
+when that is set) without changing your other Codex settings. Registration is deliberately opt-in:
+installing a Python package should not silently modify an agent's configuration. Start a new Codex
+task (or restart Codex) after registration; the refreshed task will have native `code.query`,
+`code.status`, `code.doctor`, and `code.map` MCP tools available.
+
+For a fully prepared local setup, run:
+
+```bash
+codeintel setup --all /path/to/your/project && codeintel install --agent codex
+```
+
+### Enable native Claude Code integration
+
+After installing the package, explicitly register it with Claude Code:
+
+```bash
+codeintel install --agent claude
+```
+
+This adds the `codeintel` MCP server to `~/.claude.json` (or `$CLAUDE_CONFIG_DIR/.claude.json`)
+while preserving your existing configuration — that is the file Claude Code reads for user-scope
+MCP servers, and you can confirm the entry with `claude mcp list`. Start a new Claude Code session
+after registration so it can load the native `code.query`, `code.status`, `code.doctor`, and
+`code.map` MCP tools.
+
+> **Upgrading from ≤ 0.11.1?** Earlier versions wrote this block to `~/.claude/settings.json`,
+> which Claude Code ignores for MCP registration — so codeintel never actually loaded. Re-run
+> `codeintel install --agent claude`; it registers in the right place and points out the stale
+> entry so you can delete it.
+
+For a fully prepared local setup, run:
+
+```bash
+codeintel setup --all /path/to/your/project && codeintel install --agent claude
+```
+
+### Registration is verified, not assumed
+
+**It only touches agents you have.** `codeintel install` defaults to `--agent auto`: it registers
+the hosts whose config root already exists on this machine and *names the ones it skipped*.
+Installing a Python package should not create `~/.gemini/` and `~/.config/zed/` for someone who has
+neither. Force a specific host with `--agent claude|codex|gemini|zed`, or every supported host with
+`--agent all`.
+
+**It registers an absolute path.** The bare name `codeintel` is resolved by the *host*, not by the
+shell you ran `install` in — and a GUI-launched desktop agent does not source your shell profile, so
+a command your terminal finds is routinely invisible to the app. That is the one failure a handshake
+run in your terminal cannot catch, because it inherits the PATH that works. Pass
+`--relative-command` for the bare name. If a later upgrade moves the binary, re-running
+`codeintel install` repairs the stale path in place, leaving the rest of your config untouched.
+
+Then it launches the exact command it registered and drives a real MCP handshake —
+`initialize` → `tools/list` — and reports what came back:
+
+```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)
+```
+
+If the command is not on `PATH`, or the server fails to start, install says so and exits non-zero
+instead of reporting a success your agent cannot use. Pass `--no-verify` to skip the handshake.
+
+The same principle gates releases. Because every result is a safe envelope with `ok: true` and the
+CLI never throws, an exit-code smoke test passes against a build that boots cleanly and answers
+nothing — so **[`scripts/release_canary.py`](scripts/release_canary.py)** runs before every publish
+against the built wheel in a clean environment: it registers Codex and Claude Code into a throwaway
+`HOME`, launches the command those config files name, and asserts on the **answer text** of a real
+`code.query` over a fixture repo. A release that writes a config no host reads, or that returns
+`ok: true` with nothing in it, fails there instead of on your machine.
+
 ## How it works
 
 A `Gateway` receives every query and dispatches it to one of three providers — graph (structural relationships), LSP (precise symbol resolution), or semantic (embedding-based search) — based on the operation type. Each provider is fully isolated: if it is unavailable or raises an exception, the gateway catches it and returns a safe-null envelope. The caller always gets a well-formed response with no exception to catch.
@@ -187,7 +284,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 
 | Command | Purpose |
 |---|---|
-| `codeintel install [--agent claude\|codex\|gemini\|zed\|all]` | Register codeintel with AI agent(s) |
+| `codeintel 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 index [project_root]` | Index a project for semantic search |
 | `codeintel serve` | Start the MCP server (stdio transport) |
@@ -255,7 +352,7 @@ Register codeintel as an MCP server (`codeintel install`) and the agent gets fou
 | MCP tool | HTTP equivalent | Purpose |
 |---|---|---|
 | `code.query` | `POST /code/query` | The main call — search, trace, understand (the `op` table above) |
-| `code.status` | `GET /code/status` | Which engines are live + whether an index exists |
+| `code.status` | `GET /code/status` | Per-engine `installed` / `runnable` / `repo_indexed`, probed against the live engines a query actually hits |
 | `code.doctor` | `POST /code/doctor` | Per-engine health + repo index status, with a fix for each gap |
 | `code.map` | — | Generate/refresh `CODE_INTEL.md`, a static orientation file for hosts without MCP |
 
@@ -312,5 +409,16 @@ docker build -t codeintel . && docker run -p 127.0.0.1:8766:8766 \
 git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
-pytest tests/ -q            # full suite (~15s — includes live graph/LSP backend tests)
+pytest tests/ -q            # ~390 tests, ~35s (live graph/LSP backend tests skip when absent)
 ```
+
+**Release gate.** The unit suite runs against the source tree, so it cannot see a packaging break, a
+missing entry point, a host config written where nobody reads it, or a server that boots and answers
+nothing. Run the canary against the built wheel in a clean environment — the same check CI runs
+before publishing:
+
+```bash
+python -m build && python -m venv /tmp/canary && /tmp/canary/bin/python -m pip install dist/*.whl && /tmp/canary/bin/python scripts/release_canary.py
+```
+
+It exits non-zero on the first failed check and cleans up the temporary `HOME` it installs into.

{codecortex-0.11.0 → codecortex-0.12.0}/README.md

@@ -4,6 +4,22 @@
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
 
+![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)
+
+> *codeintel visualizing its own codebase.* One command — `codeintel graph <repo> --html` — turns any indexed repo into a **self-contained, interactive call graph** you can open offline or share as a file. Layouts, complexity-sized nodes, click-to-inspect metrics, and JSON/Markdown/SVG/PNG export. See **[docs/graph-viewer.md](docs/graph-viewer.md)**.
+
+Prefer plain text? `codeintel map` writes a **readable architecture overview** to `CODE_INTEL.md` — node/edge counts, ranked symbols by caller count, and entry points — for skimming or for MCP hosts that can't render a graph:
+
+<img src="docs/images/code-intel-map.png" width="520" alt="CODE_INTEL.md — the codeintel map: an architecture overview with node/edge counts and symbols ranked by caller count.">
+
+**What `CODE_INTEL.md` is for.** It's a *static, committable* snapshot of a codebase's shape — meant to be read (by a person or an agent) **first**, instead of reconstructing structure by grepping. It covers the cases the live `code.query` tool doesn't:
+
+- **Agents & hosts that don't speak MCP.** Not every agent supports MCP, and the server isn't always running. `codeintel map` writes a plain file any agent can read; `codeintel map --inject` also drops a pointer into `CLAUDE.md` / `AGENTS.md`, so an agent picks up the codebase's structure automatically at the start of a session.
+- **A committed, diffable overview.** It lives *in the repo* — reviewable in a PR, browsable on GitHub, available offline. Re-run `codeintel map` after `codeintel index` to refresh it.
+- **The load-bearing code at a glance.** Ranking symbols by caller count surfaces what most of the codebase depends on (the risky-to-change core) plus the entry points — the first things a newcomer, or an agent, should understand before touching anything.
+
+See **[docs/map-file.md](docs/map-file.md)** for the format and the `--inject` flow.
+
 ## Why an agent needs it
 
 Without structural tools, an agent dropped into unfamiliar code falls back on `grep` and reads whole files to reconstruct relationships by hand — burning tokens, missing call sites, and guessing at blast radius before it edits anything. codeintel answers those questions directly instead:
@@ -60,7 +76,7 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 - **Degrades instead of breaking.** No graph backend installed? That engine returns `null` and the agent falls back to grep. The semantic engine needs nothing external, so codeintel is useful the moment it's installed and only gets sharper as you add backends.
 - **Fast on repeat, never stale.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index — answers stay both quick *and* fresh. The cache is bounded (LRU), so a long-running server holds steady memory.
 - **Concurrency-safe.** The HTTP transport handles requests on threads, so one slow query (an LSP session warming, a first-time index) can't block every other agent.
-- **Honest about its own health.** `codeintel doctor` reports exactly which engines are ready for a repo and the single command to fix each gap — no guessing why a query came back empty.
+- **Honest about its own health.** `codeintel doctor` answers three separate questions per engine — *installed?* *runnable?* *is this repo indexed?* — with the single command to fix each gap, so "installed" is never mistaken for "working". And a readiness claim is one a query can actually honor: install a missing backend mid-session and the running server picks it up on the next call, rather than reporting the engine healthy while quietly routing around it until you restart the host.
 
 ## Quickstart
 
@@ -94,10 +110,91 @@ pip install -e .
 Register with your AI agent(s), then query:
 
 ```bash
-codeintel install            # registers with Claude, Codex, Gemini, Zed
+codeintel install            # registers with the agents you actually have installed
 codeintel query --op search --target "authentication middleware"
 ```
 
+### Enable native Codex integration
+
+`codeintel` is an MCP server, so Codex can call its tools directly rather than invoking the CLI.
+After installing the package, explicitly register it with Codex:
+
+```bash
+codeintel install --agent codex
+```
+
+This safely adds a `[mcp_servers.codeintel]` entry to `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`
+when that is set) without changing your other Codex settings. Registration is deliberately opt-in:
+installing a Python package should not silently modify an agent's configuration. Start a new Codex
+task (or restart Codex) after registration; the refreshed task will have native `code.query`,
+`code.status`, `code.doctor`, and `code.map` MCP tools available.
+
+For a fully prepared local setup, run:
+
+```bash
+codeintel setup --all /path/to/your/project && codeintel install --agent codex
+```
+
+### Enable native Claude Code integration
+
+After installing the package, explicitly register it with Claude Code:
+
+```bash
+codeintel install --agent claude
+```
+
+This adds the `codeintel` MCP server to `~/.claude.json` (or `$CLAUDE_CONFIG_DIR/.claude.json`)
+while preserving your existing configuration — that is the file Claude Code reads for user-scope
+MCP servers, and you can confirm the entry with `claude mcp list`. Start a new Claude Code session
+after registration so it can load the native `code.query`, `code.status`, `code.doctor`, and
+`code.map` MCP tools.
+
+> **Upgrading from ≤ 0.11.1?** Earlier versions wrote this block to `~/.claude/settings.json`,
+> which Claude Code ignores for MCP registration — so codeintel never actually loaded. Re-run
+> `codeintel install --agent claude`; it registers in the right place and points out the stale
+> entry so you can delete it.
+
+For a fully prepared local setup, run:
+
+```bash
+codeintel setup --all /path/to/your/project && codeintel install --agent claude
+```
+
+### Registration is verified, not assumed
+
+**It only touches agents you have.** `codeintel install` defaults to `--agent auto`: it registers
+the hosts whose config root already exists on this machine and *names the ones it skipped*.
+Installing a Python package should not create `~/.gemini/` and `~/.config/zed/` for someone who has
+neither. Force a specific host with `--agent claude|codex|gemini|zed`, or every supported host with
+`--agent all`.
+
+**It registers an absolute path.** The bare name `codeintel` is resolved by the *host*, not by the
+shell you ran `install` in — and a GUI-launched desktop agent does not source your shell profile, so
+a command your terminal finds is routinely invisible to the app. That is the one failure a handshake
+run in your terminal cannot catch, because it inherits the PATH that works. Pass
+`--relative-command` for the bare name. If a later upgrade moves the binary, re-running
+`codeintel install` repairs the stale path in place, leaving the rest of your config untouched.
+
+Then it launches the exact command it registered and drives a real MCP handshake —
+`initialize` → `tools/list` — and reports what came back:
+
+```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)
+```
+
+If the command is not on `PATH`, or the server fails to start, install says so and exits non-zero
+instead of reporting a success your agent cannot use. Pass `--no-verify` to skip the handshake.
+
+The same principle gates releases. Because every result is a safe envelope with `ok: true` and the
+CLI never throws, an exit-code smoke test passes against a build that boots cleanly and answers
+nothing — so **[`scripts/release_canary.py`](scripts/release_canary.py)** runs before every publish
+against the built wheel in a clean environment: it registers Codex and Claude Code into a throwaway
+`HOME`, launches the command those config files name, and asserts on the **answer text** of a real
+`code.query` over a fixture repo. A release that writes a config no host reads, or that returns
+`ok: true` with nothing in it, fails there instead of on your machine.
+
 ## How it works
 
 A `Gateway` receives every query and dispatches it to one of three providers — graph (structural relationships), LSP (precise symbol resolution), or semantic (embedding-based search) — based on the operation type. Each provider is fully isolated: if it is unavailable or raises an exception, the gateway catches it and returns a safe-null envelope. The caller always gets a well-formed response with no exception to catch.
@@ -153,7 +250,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 
 | Command | Purpose |
 |---|---|
-| `codeintel install [--agent claude\|codex\|gemini\|zed\|all]` | Register codeintel with AI agent(s) |
+| `codeintel 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 index [project_root]` | Index a project for semantic search |
 | `codeintel serve` | Start the MCP server (stdio transport) |
@@ -221,7 +318,7 @@ Register codeintel as an MCP server (`codeintel install`) and the agent gets fou
 | MCP tool | HTTP equivalent | Purpose |
 |---|---|---|
 | `code.query` | `POST /code/query` | The main call — search, trace, understand (the `op` table above) |
-| `code.status` | `GET /code/status` | Which engines are live + whether an index exists |
+| `code.status` | `GET /code/status` | Per-engine `installed` / `runnable` / `repo_indexed`, probed against the live engines a query actually hits |
 | `code.doctor` | `POST /code/doctor` | Per-engine health + repo index status, with a fix for each gap |
 | `code.map` | — | Generate/refresh `CODE_INTEL.md`, a static orientation file for hosts without MCP |
 
@@ -278,5 +375,16 @@ docker build -t codeintel . && docker run -p 127.0.0.1:8766:8766 \
 git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
-pytest tests/ -q            # full suite (~15s — includes live graph/LSP backend tests)
+pytest tests/ -q            # ~390 tests, ~35s (live graph/LSP backend tests skip when absent)
 ```
+
+**Release gate.** The unit suite runs against the source tree, so it cannot see a packaging break, a
+missing entry point, a host config written where nobody reads it, or a server that boots and answers
+nothing. Run the canary against the built wheel in a clean environment — the same check CI runs
+before publishing:
+
+```bash
+python -m build && python -m venv /tmp/canary && /tmp/canary/bin/python -m pip install dist/*.whl && /tmp/canary/bin/python scripts/release_canary.py
+```
+
+It exits non-zero on the first failed check and cleans up the temporary `HOME` it installs into.

{codecortex-0.11.0 → codecortex-0.12.0/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.11.0
+Version: 0.12.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
@@ -38,6 +38,22 @@ Dynamic: license-file
 
 [![CI](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml/badge.svg)](https://github.com/hamilton-sky/codeintel/actions/workflows/ci.yml)
 
+![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)
+
+> *codeintel visualizing its own codebase.* One command — `codeintel graph <repo> --html` — turns any indexed repo into a **self-contained, interactive call graph** you can open offline or share as a file. Layouts, complexity-sized nodes, click-to-inspect metrics, and JSON/Markdown/SVG/PNG export. See **[docs/graph-viewer.md](docs/graph-viewer.md)**.
+
+Prefer plain text? `codeintel map` writes a **readable architecture overview** to `CODE_INTEL.md` — node/edge counts, ranked symbols by caller count, and entry points — for skimming or for MCP hosts that can't render a graph:
+
+<img src="docs/images/code-intel-map.png" width="520" alt="CODE_INTEL.md — the codeintel map: an architecture overview with node/edge counts and symbols ranked by caller count.">
+
+**What `CODE_INTEL.md` is for.** It's a *static, committable* snapshot of a codebase's shape — meant to be read (by a person or an agent) **first**, instead of reconstructing structure by grepping. It covers the cases the live `code.query` tool doesn't:
+
+- **Agents & hosts that don't speak MCP.** Not every agent supports MCP, and the server isn't always running. `codeintel map` writes a plain file any agent can read; `codeintel map --inject` also drops a pointer into `CLAUDE.md` / `AGENTS.md`, so an agent picks up the codebase's structure automatically at the start of a session.
+- **A committed, diffable overview.** It lives *in the repo* — reviewable in a PR, browsable on GitHub, available offline. Re-run `codeintel map` after `codeintel index` to refresh it.
+- **The load-bearing code at a glance.** Ranking symbols by caller count surfaces what most of the codebase depends on (the risky-to-change core) plus the entry points — the first things a newcomer, or an agent, should understand before touching anything.
+
+See **[docs/map-file.md](docs/map-file.md)** for the format and the `--inject` flow.
+
 ## Why an agent needs it
 
 Without structural tools, an agent dropped into unfamiliar code falls back on `grep` and reads whole files to reconstruct relationships by hand — burning tokens, missing call sites, and guessing at blast radius before it edits anything. codeintel answers those questions directly instead:
@@ -94,7 +110,7 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 - **Degrades instead of breaking.** No graph backend installed? That engine returns `null` and the agent falls back to grep. The semantic engine needs nothing external, so codeintel is useful the moment it's installed and only gets sharper as you add backends.
 - **Fast on repeat, never stale.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index — answers stay both quick *and* fresh. The cache is bounded (LRU), so a long-running server holds steady memory.
 - **Concurrency-safe.** The HTTP transport handles requests on threads, so one slow query (an LSP session warming, a first-time index) can't block every other agent.
-- **Honest about its own health.** `codeintel doctor` reports exactly which engines are ready for a repo and the single command to fix each gap — no guessing why a query came back empty.
+- **Honest about its own health.** `codeintel doctor` answers three separate questions per engine — *installed?* *runnable?* *is this repo indexed?* — with the single command to fix each gap, so "installed" is never mistaken for "working". And a readiness claim is one a query can actually honor: install a missing backend mid-session and the running server picks it up on the next call, rather than reporting the engine healthy while quietly routing around it until you restart the host.
 
 ## Quickstart
 
@@ -128,10 +144,91 @@ pip install -e .
 Register with your AI agent(s), then query:
 
 ```bash
-codeintel install            # registers with Claude, Codex, Gemini, Zed
+codeintel install            # registers with the agents you actually have installed
 codeintel query --op search --target "authentication middleware"
 ```
 
+### Enable native Codex integration
+
+`codeintel` is an MCP server, so Codex can call its tools directly rather than invoking the CLI.
+After installing the package, explicitly register it with Codex:
+
+```bash
+codeintel install --agent codex
+```
+
+This safely adds a `[mcp_servers.codeintel]` entry to `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`
+when that is set) without changing your other Codex settings. Registration is deliberately opt-in:
+installing a Python package should not silently modify an agent's configuration. Start a new Codex
+task (or restart Codex) after registration; the refreshed task will have native `code.query`,
+`code.status`, `code.doctor`, and `code.map` MCP tools available.
+
+For a fully prepared local setup, run:
+
+```bash
+codeintel setup --all /path/to/your/project && codeintel install --agent codex
+```
+
+### Enable native Claude Code integration
+
+After installing the package, explicitly register it with Claude Code:
+
+```bash
+codeintel install --agent claude
+```
+
+This adds the `codeintel` MCP server to `~/.claude.json` (or `$CLAUDE_CONFIG_DIR/.claude.json`)
+while preserving your existing configuration — that is the file Claude Code reads for user-scope
+MCP servers, and you can confirm the entry with `claude mcp list`. Start a new Claude Code session
+after registration so it can load the native `code.query`, `code.status`, `code.doctor`, and
+`code.map` MCP tools.
+
+> **Upgrading from ≤ 0.11.1?** Earlier versions wrote this block to `~/.claude/settings.json`,
+> which Claude Code ignores for MCP registration — so codeintel never actually loaded. Re-run
+> `codeintel install --agent claude`; it registers in the right place and points out the stale
+> entry so you can delete it.
+
+For a fully prepared local setup, run:
+
+```bash
+codeintel setup --all /path/to/your/project && codeintel install --agent claude
+```
+
+### Registration is verified, not assumed
+
+**It only touches agents you have.** `codeintel install` defaults to `--agent auto`: it registers
+the hosts whose config root already exists on this machine and *names the ones it skipped*.
+Installing a Python package should not create `~/.gemini/` and `~/.config/zed/` for someone who has
+neither. Force a specific host with `--agent claude|codex|gemini|zed`, or every supported host with
+`--agent all`.
+
+**It registers an absolute path.** The bare name `codeintel` is resolved by the *host*, not by the
+shell you ran `install` in — and a GUI-launched desktop agent does not source your shell profile, so
+a command your terminal finds is routinely invisible to the app. That is the one failure a handshake
+run in your terminal cannot catch, because it inherits the PATH that works. Pass
+`--relative-command` for the bare name. If a later upgrade moves the binary, re-running
+`codeintel install` repairs the stale path in place, leaving the rest of your config untouched.
+
+Then it launches the exact command it registered and drives a real MCP handshake —
+`initialize` → `tools/list` — and reports what came back:
+
+```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)
+```
+
+If the command is not on `PATH`, or the server fails to start, install says so and exits non-zero
+instead of reporting a success your agent cannot use. Pass `--no-verify` to skip the handshake.
+
+The same principle gates releases. Because every result is a safe envelope with `ok: true` and the
+CLI never throws, an exit-code smoke test passes against a build that boots cleanly and answers
+nothing — so **[`scripts/release_canary.py`](scripts/release_canary.py)** runs before every publish
+against the built wheel in a clean environment: it registers Codex and Claude Code into a throwaway
+`HOME`, launches the command those config files name, and asserts on the **answer text** of a real
+`code.query` over a fixture repo. A release that writes a config no host reads, or that returns
+`ok: true` with nothing in it, fails there instead of on your machine.
+
 ## How it works
 
 A `Gateway` receives every query and dispatches it to one of three providers — graph (structural relationships), LSP (precise symbol resolution), or semantic (embedding-based search) — based on the operation type. Each provider is fully isolated: if it is unavailable or raises an exception, the gateway catches it and returns a safe-null envelope. The caller always gets a well-formed response with no exception to catch.
@@ -187,7 +284,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 
 | Command | Purpose |
 |---|---|
-| `codeintel install [--agent claude\|codex\|gemini\|zed\|all]` | Register codeintel with AI agent(s) |
+| `codeintel 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 index [project_root]` | Index a project for semantic search |
 | `codeintel serve` | Start the MCP server (stdio transport) |
@@ -255,7 +352,7 @@ Register codeintel as an MCP server (`codeintel install`) and the agent gets fou
 | MCP tool | HTTP equivalent | Purpose |
 |---|---|---|
 | `code.query` | `POST /code/query` | The main call — search, trace, understand (the `op` table above) |
-| `code.status` | `GET /code/status` | Which engines are live + whether an index exists |
+| `code.status` | `GET /code/status` | Per-engine `installed` / `runnable` / `repo_indexed`, probed against the live engines a query actually hits |
 | `code.doctor` | `POST /code/doctor` | Per-engine health + repo index status, with a fix for each gap |
 | `code.map` | — | Generate/refresh `CODE_INTEL.md`, a static orientation file for hosts without MCP |
 
@@ -312,5 +409,16 @@ docker build -t codeintel . && docker run -p 127.0.0.1:8766:8766 \
 git clone https://github.com/hamilton-sky/codeintel.git
 cd codeintel
 pip install -e .[dev]
-pytest tests/ -q            # full suite (~15s — includes live graph/LSP backend tests)
+pytest tests/ -q            # ~390 tests, ~35s (live graph/LSP backend tests skip when absent)
 ```
+
+**Release gate.** The unit suite runs against the source tree, so it cannot see a packaging break, a
+missing entry point, a host config written where nobody reads it, or a server that boots and answers
+nothing. Run the canary against the built wheel in a clean environment — the same check CI runs
+before publishing:
+
+```bash
+python -m build && python -m venv /tmp/canary && /tmp/canary/bin/python -m pip install dist/*.whl && /tmp/canary/bin/python scripts/release_canary.py
+```
+
+It exits non-zero on the first failed check and cleans up the temporary `HOME` it installs into.

{codecortex-0.11.0 → codecortex-0.12.0}/src/codecortex.egg-info/SOURCES.txt

@@ -31,6 +31,7 @@ src/codeintel/searcher.py
 src/codeintel/semantic_db.py
 src/codeintel/server.py
 src/codeintel/term.py
+src/codeintel/verify.py
 src/codeintel/providers/__init__.py
 src/codeintel/providers/graph.py
 src/codeintel/providers/lsp.py
@@ -43,6 +44,7 @@ tests/test_chunking.py
 tests/test_config.py
 tests/test_doctor.py
 tests/test_e2e.py
+tests/test_engine_adoption.py
 tests/test_enterprise.py
 tests/test_gateway.py
 tests/test_graph_provider.py
@@ -57,6 +59,7 @@ tests/test_integration.py
 tests/test_lsp_provider.py
 tests/test_lsp_real.py
 tests/test_mapper.py
+tests/test_mcp_handshake.py
 tests/test_mcp_server.py
 tests/test_model_dimension.py
 tests/test_never_raise.py
@@ -67,4 +70,6 @@ tests/test_rerank.py
 tests/test_reset.py
 tests/test_semantic_provider.py
 tests/test_term.py
-tests/test_treesitter.py
+tests/test_treesitter.py
+tests/test_verify.py
+tests/test_verify_call.py

codecortex-0.12.0/src/codeintel/__init__.py

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