codecortex 0.12.1__tar.gz → 0.13.1__tar.gz

{codecortex-0.12.1 → codecortex-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.12.1
+Version: 0.13.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
@@ -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 :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Environment :: Console
 Classifier: Operating System :: OS Independent
@@ -29,7 +29,10 @@ Requires-Dist: fastembed>=0.3
 Requires-Dist: tree-sitter-language-pack>=1.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
 Requires-Dist: numpy>=1.24; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
 Dynamic: license-file
 
 # codeintel
@@ -108,7 +111,7 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 - **It never throws.** Every call returns the same JSON envelope; a missing or broken backend degrades to `null` *with a reason*. No exceptions, no 500s, no malformed output for the agent to trip over — so you never wrap `code.query` in a `try`.
 - **One tool, not three.** Register a single MCP server and it auto-routes each question to graph, LSP, or semantic — instead of wiring up three backends with three response shapes and three failure modes.
 - **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.
+- **Fast on repeat, and the cache never lies.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index, so you never read a cached answer for code that moved on. The cache is bounded (LRU), so a long-running server holds steady memory. (The *cache* is always consistent with the index; how current the index itself is depends on the engine — see [Keeping answers fresh](#keeping-answers-fresh).)
 - **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` 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.
 
@@ -271,6 +274,28 @@ Every `Gateway.query()` call returns a dict with exactly these keys:
 
 Run `codeintel doctor` at any time to see which engines are actually ready for a repo and how to fix the ones that aren't.
 
+### Keeping answers fresh
+
+The three engines have genuinely different freshness models, and it's worth knowing which you're
+reading:
+
+| Engine | Freshness |
+|---|---|
+| `lsp` | **Live.** Reads your files at query time — always current, no refresh needed. |
+| `semantic` | **Incremental.** A background reindex re-embeds only what changed; `codeintel status` shows the index age. |
+| `graph` | **Snapshot.** Built by `codeintel index` and stale until the next one. |
+
+So a `callers`/`impact`/`hotspots` answer is only as current as your last index. If a result
+describes code you just changed — or a symbol you just added comes back
+`reason: "not-in-graph"` — that's the signal to re-run:
+
+```bash
+codeintel index /path/to/repo
+```
+
+The reply names the fix when it can: a missing symbol now returns a `hint` with the exact command
+rather than a bare reason.
+
 Pass `--engine auto` (the default) and codeintel chooses the best engine per operation. Pass `--engine both` or `--engine all` to fan out to multiple engines and merge results.
 
 ## Documentation
@@ -294,12 +319,12 @@ 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]` | Run a single query and print the result |
+| `codeintel query --op OP --target TARGET [--engine auto] [--project-root DIR]` | 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 |
 | `codeintel graph [project_root] [--html] [--out FILE] [--limit N]` | Emit the call graph as `{nodes,edges}` JSON, or `--html` a self-contained interactive viewer — see [docs/graph-viewer.md](docs/graph-viewer.md) |
-| `codeintel reset [project_root] [--all] [--yes]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
+| `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 
 Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.
@@ -414,7 +439,19 @@ 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            # ~410 tests, ~35s (live graph/LSP backend tests skip when absent)
+
+pytest tests/ -q            # ~494 tests, ~35s; fails under 83% coverage
+ruff check src tests        # lint
+mypy                        # types (src/ only)
+```
+
+**Your local run is not CI's run.** A dev machine usually has `codebase-memory-mcp` and `uvx`
+installed; CI has neither, so the live graph/LSP tests skip there *and* the never-raise envelopes
+take different `reason`/`hint` paths. A bug reachable only on the no-backend path passes at your
+desk and fails in CI. To see CI's shape before you push:
+
+```bash
+env PATH="$(dirname "$(which python)"):/usr/bin:/bin" pytest -q
 ```
 
 **Release gate.** The unit suite runs against the source tree, so it cannot see a packaging break, a

codecortex-0.12.1/src/codecortex.egg-info/PKG-INFO → codecortex-0.13.1/README.md

@@ -1,37 +1,3 @@
-Metadata-Version: 2.4
-Name: codecortex
-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
-Project-URL: Homepage, https://github.com/hamilton-sky/codeintel
-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 :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Environment :: Console
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: Software Development :: Quality Assurance
-Classifier: Typing :: Typed
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: mcp>=1.0
-Requires-Dist: sqlite-vec>=0.1
-Requires-Dist: fastembed>=0.3
-Requires-Dist: tree-sitter-language-pack>=1.0
-Provides-Extra: dev
-Requires-Dist: pytest>=8; extra == "dev"
-Requires-Dist: numpy>=1.24; extra == "dev"
-Dynamic: license-file
-
 # codeintel
 
 **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.
@@ -108,7 +74,7 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 - **It never throws.** Every call returns the same JSON envelope; a missing or broken backend degrades to `null` *with a reason*. No exceptions, no 500s, no malformed output for the agent to trip over — so you never wrap `code.query` in a `try`.
 - **One tool, not three.** Register a single MCP server and it auto-routes each question to graph, LSP, or semantic — instead of wiring up three backends with three response shapes and three failure modes.
 - **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.
+- **Fast on repeat, and the cache never lies.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index, so you never read a cached answer for code that moved on. The cache is bounded (LRU), so a long-running server holds steady memory. (The *cache* is always consistent with the index; how current the index itself is depends on the engine — see [Keeping answers fresh](#keeping-answers-fresh).)
 - **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` 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.
 
@@ -271,6 +237,28 @@ Every `Gateway.query()` call returns a dict with exactly these keys:
 
 Run `codeintel doctor` at any time to see which engines are actually ready for a repo and how to fix the ones that aren't.
 
+### Keeping answers fresh
+
+The three engines have genuinely different freshness models, and it's worth knowing which you're
+reading:
+
+| Engine | Freshness |
+|---|---|
+| `lsp` | **Live.** Reads your files at query time — always current, no refresh needed. |
+| `semantic` | **Incremental.** A background reindex re-embeds only what changed; `codeintel status` shows the index age. |
+| `graph` | **Snapshot.** Built by `codeintel index` and stale until the next one. |
+
+So a `callers`/`impact`/`hotspots` answer is only as current as your last index. If a result
+describes code you just changed — or a symbol you just added comes back
+`reason: "not-in-graph"` — that's the signal to re-run:
+
+```bash
+codeintel index /path/to/repo
+```
+
+The reply names the fix when it can: a missing symbol now returns a `hint` with the exact command
+rather than a bare reason.
+
 Pass `--engine auto` (the default) and codeintel chooses the best engine per operation. Pass `--engine both` or `--engine all` to fan out to multiple engines and merge results.
 
 ## Documentation
@@ -294,12 +282,12 @@ 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]` | Run a single query and print the result |
+| `codeintel query --op OP --target TARGET [--engine auto] [--project-root DIR]` | 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 |
 | `codeintel graph [project_root] [--html] [--out FILE] [--limit N]` | Emit the call graph as `{nodes,edges}` JSON, or `--html` a self-contained interactive viewer — see [docs/graph-viewer.md](docs/graph-viewer.md) |
-| `codeintel reset [project_root] [--all] [--yes]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
+| `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 
 Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.
@@ -414,7 +402,19 @@ 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            # ~410 tests, ~35s (live graph/LSP backend tests skip when absent)
+
+pytest tests/ -q            # ~494 tests, ~35s; fails under 83% coverage
+ruff check src tests        # lint
+mypy                        # types (src/ only)
+```
+
+**Your local run is not CI's run.** A dev machine usually has `codebase-memory-mcp` and `uvx`
+installed; CI has neither, so the live graph/LSP tests skip there *and* the never-raise envelopes
+take different `reason`/`hint` paths. A bug reachable only on the no-backend path passes at your
+desk and fails in CI. To see CI's shape before you push:
+
+```bash
+env PATH="$(dirname "$(which python)"):/usr/bin:/bin" pytest -q
 ```
 
 **Release gate.** The unit suite runs against the source tree, so it cannot see a packaging break, a

codecortex-0.13.1/pyproject.toml

@@ -0,0 +1,139 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution name is `codecortex` because `codeintel` is taken on PyPI and `codeintel-*` names
+# are rejected as "too similar" to it. The import package and the CLI are still `codeintel`
+# (i.e. `pip install codecortex` installs the `codeintel` command).
+name = "codecortex"
+dynamic = ["version"]
+description = "Local-first, MCP-native code-intelligence server — graph, LSP, and semantic search behind one safe code.query tool for coding agents."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Shammai Hamilton" }]
+keywords = [
+    "mcp", "model-context-protocol", "code-intelligence", "code-search", "llm", "agents",
+    "lsp", "semantic-search", "knowledge-graph", "static-analysis", "developer-tools",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+    "Typing :: Typed",
+]
+dependencies = [
+    "mcp>=1.0",
+    "sqlite-vec>=0.1",
+    "fastembed>=0.3",
+    "tree-sitter-language-pack>=1.0",  # def-aligned chunking for non-Python languages (P3)
+]
+
+[project.urls]
+Homepage = "https://github.com/hamilton-sky/codeintel"
+Repository = "https://github.com/hamilton-sky/codeintel"
+Issues = "https://github.com/hamilton-sky/codeintel/issues"
+Changelog = "https://github.com/hamilton-sky/codeintel/blob/main/CHANGELOG.md"
+
+[project.scripts]
+codeintel = "codeintel.__main__:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5", "numpy>=1.24", "ruff>=0.16", "mypy>=1.11"]
+
+# Single source of truth for the version: read from codeintel.__version__ (AST-parsed, no import).
+[tool.setuptools.dynamic]
+version = { attr = "codeintel.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Ship the self-contained interactive graph viewer template with the wheel, and the PEP 561 marker
+# without which the `Typing :: Typed` classifier is a promise the installed package cannot keep —
+# type checkers ignore an installed package's annotations entirely unless py.typed is present.
+[tool.setuptools.package-data]
+"codeintel.viewer" = ["*.html"]
+"codeintel" = ["py.typed"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E", "W",   # pycodestyle
+    "F",        # pyflakes
+    "I",        # import sorting
+    "UP",       # pyupgrade — this is a >=3.11 package, so modern syntax is always available
+    "B",        # bugbear
+    "C4",       # comprehensions
+    "SIM",      # simplify
+    "PIE", "PERF", "RUF",
+    "S",        # bandit — the HTTP transport is a real network surface
+]
+ignore = [
+    # The never-raise contract IS the architecture: providers and handlers degrade to a `reason`
+    # string rather than propagate, and the best-effort refresh paths (graph reindex, map rewrite)
+    # are deliberately allowed to fail silently. These three rules flag that design at ~190 sites,
+    # so enforcing them would mean 190 `noqa`s asserting the same thing the module docstrings say.
+    "S110",     # try-except-pass
+    "S112",     # try-except-continue
+    "SIM105",   # "use contextlib.suppress" — see below
+    "S603",     # subprocess call — every one is an explicit argv list, never a shell string
+]
+# On SIM105 specifically: the suppressed blocks carry their reason on the `pass` line itself
+# (`pass  # code_embeddings is created lazily at first embed — may not exist yet`), and
+# contextlib.suppress has nowhere to put that. Losing 13 such explanations to gain a context
+# manager is a bad trade in code whose whole contract is degrading quietly.
+
+[tool.ruff.lint.per-file-ignores]
+# Tests stand up fake servers on loopback, assert on hardcoded fixture tokens, and shell out to
+# the CLI under test. Flagging that as a security finding is noise.
+"tests/*" = [
+    "S101", "S104", "S105", "S106", "S108", "S404", "S607",
+    "S310",     # urlopen against the loopback test server this same test just started
+    "E402",     # a few modules import after a skip guard, so a missing backend skips, not errors
+    "E501",     # fixture payloads (graph JSON, serena responses) are copied verbatim; rewrapping
+                # them would make them stop matching what the real backend returns
+    "E702",     # `a = 1; b = 2` setup one-liners
+    "SIM115",   # ad-hoc open() in assertions, inside tmp_path — nothing to leak
+    "UP031",    # %-format is the readable choice for templating source into a fake server
+]
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src/codeintel"]
+# Deliberately not --strict: the provider seams cross into untyped third-party backends (mcp,
+# fastembed, sqlite-vec, tree-sitter), where demanding annotations buys noise rather than safety.
+# These flags catch the errors that actually bite — unreachable branches, bad returns, silent Any
+# propagation out of our own typed code.
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_unreachable = true
+warn_no_return = true
+no_implicit_optional = true
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+# Don't type-check the backends themselves, and don't follow into them: `python_version = "3.11"`
+# makes mypy parse their stubs under 3.11 syntax rules, and numpy's (reached transitively through
+# fastembed) use 3.12 `type` statements — an error in a dependency's own stubs, not in our code.
+module = ["mcp.*", "fastembed.*", "sqlite_vec.*", "tree_sitter_language_pack.*", "numpy.*"]
+ignore_missing_imports = true
+follow_imports = "skip"
+
+[tool.pytest.ini_options]
+# The floor sits below the current number (85.3% with every backend present) on purpose: the live
+# graph/LSP tests skip when codebase-memory-mcp and uvx/serena are absent, which is exactly the
+# case in CI, and that costs ~0.4 points. A floor pinned to today's measurement would go red on a
+# runner's toolchain rather than on a real coverage regression. Ratchet it up deliberately.
+addopts = "--cov=codeintel --cov-report=term-missing:skip-covered --cov-fail-under=83"

codecortex-0.12.1/README.md → codecortex-0.13.1/src/codecortex.egg-info/PKG-INFO

@@ -1,3 +1,40 @@
+Metadata-Version: 2.4
+Name: codecortex
+Version: 0.13.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
+Project-URL: Homepage, https://github.com/hamilton-sky/codeintel
+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: Intended Audience :: Developers
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0
+Requires-Dist: sqlite-vec>=0.1
+Requires-Dist: fastembed>=0.3
+Requires-Dist: tree-sitter-language-pack>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: numpy>=1.24; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Dynamic: license-file
+
 # codeintel
 
 **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.
@@ -74,7 +111,7 @@ The agent hands `result` straight to the model. If the graph backend isn't insta
 - **It never throws.** Every call returns the same JSON envelope; a missing or broken backend degrades to `null` *with a reason*. No exceptions, no 500s, no malformed output for the agent to trip over — so you never wrap `code.query` in a `try`.
 - **One tool, not three.** Register a single MCP server and it auto-routes each question to graph, LSP, or semantic — instead of wiring up three backends with three response shapes and three failure modes.
 - **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.
+- **Fast on repeat, and the cache never lies.** A content-hash cache returns instantly for unchanged code and self-invalidates when a background reindex advances the index, so you never read a cached answer for code that moved on. The cache is bounded (LRU), so a long-running server holds steady memory. (The *cache* is always consistent with the index; how current the index itself is depends on the engine — see [Keeping answers fresh](#keeping-answers-fresh).)
 - **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` 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.
 
@@ -237,6 +274,28 @@ Every `Gateway.query()` call returns a dict with exactly these keys:
 
 Run `codeintel doctor` at any time to see which engines are actually ready for a repo and how to fix the ones that aren't.
 
+### Keeping answers fresh
+
+The three engines have genuinely different freshness models, and it's worth knowing which you're
+reading:
+
+| Engine | Freshness |
+|---|---|
+| `lsp` | **Live.** Reads your files at query time — always current, no refresh needed. |
+| `semantic` | **Incremental.** A background reindex re-embeds only what changed; `codeintel status` shows the index age. |
+| `graph` | **Snapshot.** Built by `codeintel index` and stale until the next one. |
+
+So a `callers`/`impact`/`hotspots` answer is only as current as your last index. If a result
+describes code you just changed — or a symbol you just added comes back
+`reason: "not-in-graph"` — that's the signal to re-run:
+
+```bash
+codeintel index /path/to/repo
+```
+
+The reply names the fix when it can: a missing symbol now returns a `hint` with the exact command
+rather than a bare reason.
+
 Pass `--engine auto` (the default) and codeintel chooses the best engine per operation. Pass `--engine both` or `--engine all` to fan out to multiple engines and merge results.
 
 ## Documentation
@@ -260,12 +319,12 @@ 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]` | Run a single query and print the result |
+| `codeintel query --op OP --target TARGET [--engine auto] [--project-root DIR]` | 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 |
 | `codeintel graph [project_root] [--html] [--out FILE] [--limit N]` | Emit the call graph as `{nodes,edges}` JSON, or `--html` a self-contained interactive viewer — see [docs/graph-viewer.md](docs/graph-viewer.md) |
-| `codeintel reset [project_root] [--all] [--yes]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
+| `codeintel reset [project_root] [--all] [--yes] [--json]` | Clear the semantic index (this repo, or `--all`) to recover from a corrupt/stale DB |
 | `codeintel gen-token` | Print a secure random bearer token (for `serve-http` / RBAC `auth.toml`) |
 
 Human-facing commands (`doctor`, `status`, `query`, `setup`, `reset`) honor `--no-color` / `NO_COLOR` and `--ascii`, and auto-degrade to plain text when piped.
@@ -380,7 +439,19 @@ 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            # ~410 tests, ~35s (live graph/LSP backend tests skip when absent)
+
+pytest tests/ -q            # ~494 tests, ~35s; fails under 83% coverage
+ruff check src tests        # lint
+mypy                        # types (src/ only)
+```
+
+**Your local run is not CI's run.** A dev machine usually has `codebase-memory-mcp` and `uvx`
+installed; CI has neither, so the live graph/LSP tests skip there *and* the never-raise envelopes
+take different `reason`/`hint` paths. A bug reachable only on the no-backend path passes at your
+desk and fails in CI. To see CI's shape before you push:
+
+```bash
+env PATH="$(dirname "$(which python)"):/usr/bin:/bin" pytest -q
 ```
 
 **Release gate.** The unit suite runs against the source tree, so it cannot see a packaging break, a

{codecortex-0.12.1 → codecortex-0.13.1}/src/codecortex.egg-info/SOURCES.txt

@@ -25,6 +25,7 @@ src/codeintel/metrics.py
 src/codeintel/onboarding.py
 src/codeintel/policy.py
 src/codeintel/provider.py
+src/codeintel/py.typed
 src/codeintel/reindexer.py
 src/codeintel/reset.py
 src/codeintel/searcher.py
@@ -32,6 +33,20 @@ src/codeintel/semantic_db.py
 src/codeintel/server.py
 src/codeintel/term.py
 src/codeintel/verify.py
+src/codeintel/commands/__init__.py
+src/codeintel/commands/_common.py
+src/codeintel/commands/doctor.py
+src/codeintel/commands/gen_token.py
+src/codeintel/commands/graph.py
+src/codeintel/commands/index.py
+src/codeintel/commands/install.py
+src/codeintel/commands/map.py
+src/codeintel/commands/query.py
+src/codeintel/commands/reset.py
+src/codeintel/commands/serve.py
+src/codeintel/commands/serve_http.py
+src/codeintel/commands/setup.py
+src/codeintel/commands/status.py
 src/codeintel/providers/__init__.py
 src/codeintel/providers/graph.py
 src/codeintel/providers/lsp.py
@@ -41,6 +56,7 @@ src/codeintel/viewer/__init__.py
 src/codeintel/viewer/graph_template.html
 tests/test_cache.py
 tests/test_chunking.py
+tests/test_cli_commands.py
 tests/test_cli_help.py
 tests/test_config.py
 tests/test_doctor.py

{codecortex-0.12.1 → codecortex-0.13.1}/src/codecortex.egg-info/requires.txt

@@ -5,4 +5,7 @@ tree-sitter-language-pack>=1.0
 
 [dev]
 pytest>=8
+pytest-cov>=5
 numpy>=1.24
+ruff>=0.16
+mypy>=1.11

codecortex-0.13.1/src/codeintel/__init__.py

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