codecortex 0.11.1__tar.gz → 0.12.1__tar.gz

{codecortex-0.11.1/src/codecortex.egg-info → codecortex-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.11.1
+Version: 0.12.1
 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
@@ -110,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
 
@@ -144,10 +144,94 @@ 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.
+
+> Full reference — what each host reads, the absolute-path rationale, and troubleshooting:
+> **[docs/install.md](docs/install.md)**.
+
 ## 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.
@@ -194,6 +278,7 @@ Pass `--engine auto` (the default) and codeintel chooses the best engine per ope
 Full system docs live in [`docs/`](docs/) — start with the index:
 
 - **[Architecture](docs/architecture.md)** — layers, the `CodeProvider` protocol, the safe-null contract, caching, freshness (ASCII + Mermaid).
+- **[Install & registration](docs/install.md)** — what each agent host actually reads, why the registered command is an absolute path, and the three levels of proof that registration worked.
 - **[Query flow](docs/query-flow.md)** — request lifecycle, engine selection, fan-out & merge, and why it never throws.
 - **[Map file](docs/map-file.md)** — the static `CODE_INTEL.md` orientation layer for hosts with no MCP support.
 - **[Benchmarks](docs/benchmarks.md)** — real numbers at scale: 25 k chunks indexed in ~8 min, ~235 ms warm queries, 60 MB index.
@@ -203,7 +288,8 @@ 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 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 index [project_root]` | Index a project for semantic search |
 | `codeintel serve` | Start the MCP server (stdio transport) |
@@ -271,7 +357,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 |
 
@@ -328,5 +414,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            # ~410 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.1 → codecortex-0.12.1}/README.md

@@ -76,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
 
@@ -110,10 +110,94 @@ 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.
+
+> Full reference — what each host reads, the absolute-path rationale, and troubleshooting:
+> **[docs/install.md](docs/install.md)**.
+
 ## 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.
@@ -160,6 +244,7 @@ Pass `--engine auto` (the default) and codeintel chooses the best engine per ope
 Full system docs live in [`docs/`](docs/) — start with the index:
 
 - **[Architecture](docs/architecture.md)** — layers, the `CodeProvider` protocol, the safe-null contract, caching, freshness (ASCII + Mermaid).
+- **[Install & registration](docs/install.md)** — what each agent host actually reads, why the registered command is an absolute path, and the three levels of proof that registration worked.
 - **[Query flow](docs/query-flow.md)** — request lifecycle, engine selection, fan-out & merge, and why it never throws.
 - **[Map file](docs/map-file.md)** — the static `CODE_INTEL.md` orientation layer for hosts with no MCP support.
 - **[Benchmarks](docs/benchmarks.md)** — real numbers at scale: 25 k chunks indexed in ~8 min, ~235 ms warm queries, 60 MB index.
@@ -169,7 +254,8 @@ 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 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 index [project_root]` | Index a project for semantic search |
 | `codeintel serve` | Start the MCP server (stdio transport) |
@@ -237,7 +323,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 |
 
@@ -294,5 +380,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            # ~410 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.1 → codecortex-0.12.1/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.11.1
+Version: 0.12.1
 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
@@ -110,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
 
@@ -144,10 +144,94 @@ 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.
+
+> Full reference — what each host reads, the absolute-path rationale, and troubleshooting:
+> **[docs/install.md](docs/install.md)**.
+
 ## 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.
@@ -194,6 +278,7 @@ Pass `--engine auto` (the default) and codeintel chooses the best engine per ope
 Full system docs live in [`docs/`](docs/) — start with the index:
 
 - **[Architecture](docs/architecture.md)** — layers, the `CodeProvider` protocol, the safe-null contract, caching, freshness (ASCII + Mermaid).
+- **[Install & registration](docs/install.md)** — what each agent host actually reads, why the registered command is an absolute path, and the three levels of proof that registration worked.
 - **[Query flow](docs/query-flow.md)** — request lifecycle, engine selection, fan-out & merge, and why it never throws.
 - **[Map file](docs/map-file.md)** — the static `CODE_INTEL.md` orientation layer for hosts with no MCP support.
 - **[Benchmarks](docs/benchmarks.md)** — real numbers at scale: 25 k chunks indexed in ~8 min, ~235 ms warm queries, 60 MB index.
@@ -203,7 +288,8 @@ 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 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 index [project_root]` | Index a project for semantic search |
 | `codeintel serve` | Start the MCP server (stdio transport) |
@@ -271,7 +357,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 |
 
@@ -328,5 +414,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            # ~410 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.1 → codecortex-0.12.1}/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
@@ -40,9 +41,11 @@ src/codeintel/viewer/__init__.py
 src/codeintel/viewer/graph_template.html
 tests/test_cache.py
 tests/test_chunking.py
+tests/test_cli_help.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 +60,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 +71,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.1/src/codeintel/__init__.py

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