codecortex 0.12.0__tar.gz → 0.13.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.12.0
+Version: 0.13.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
@@ -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
@@ -229,6 +232,9 @@ against the built wheel in a clean environment: it registers Codex and Claude Co
 `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.
@@ -275,6 +281,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.
@@ -284,6 +291,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 
 | Command | Purpose |
 |---|---|
+| `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 |
@@ -409,7 +417,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            # ~390 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.0 → codecortex-0.13.0}/README.md

@@ -195,6 +195,9 @@ against the built wheel in a clean environment: it registers Codex and Claude Co
 `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.
@@ -241,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.
@@ -250,6 +254,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 
 | Command | Purpose |
 |---|---|
+| `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 |
@@ -375,7 +380,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            # ~390 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.0/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.0 → codecortex-0.13.0/src/codecortex.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecortex
-Version: 0.12.0
+Version: 0.13.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
@@ -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
@@ -229,6 +232,9 @@ against the built wheel in a clean environment: it registers Codex and Claude Co
 `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.
@@ -275,6 +281,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.
@@ -284,6 +291,7 @@ Full system docs live in [`docs/`](docs/) — start with the index:
 
 | Command | Purpose |
 |---|---|
+| `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 |
@@ -409,7 +417,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            # ~390 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.0 → codecortex-0.13.0}/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,8 @@ 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
 tests/test_e2e.py

{codecortex-0.12.0 → codecortex-0.13.0}/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.0/src/codeintel/__init__.py

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

codecortex-0.13.0/src/codeintel/__main__.py

@@ -0,0 +1,273 @@
+import argparse
+import difflib
+import sys
+from importlib import import_module
+
+from codeintel import __version__
+
+# Commands grouped by what you are trying to DO. argparse lists them in declaration order with no
+# grouping, which turns "what can this thing do?" into reading twelve lines to find the one verb you
+# wanted. Each entry is (command, one-line description).
+_COMMAND_GROUPS: list[tuple[str, list[tuple[str, str]]]] = [
+    ("Understand your code", [
+        ("query", "Ask one question — search, callers, callees, impact, chain, symbol, hotspots"),
+        ("map", "Write CODE_INTEL.md — a committable architecture overview"),
+        ("graph", "Interactive call-graph viewer (--html), or the graph as JSON"),
+    ]),
+    ("Set up", [
+        ("setup", "Prepare backends + index this repo (--all does everything automatable)"),
+        ("index", "Index a project for semantic search"),
+        ("install", "Register codeintel with the AI agents installed on this machine"),
+    ]),
+    ("Check health", [
+        ("doctor", "Per-engine health + index status, with the fix for each gap"),
+        ("status", "Engine readiness and index age at a glance"),
+        ("reset", "Clear the semantic index (recover from a corrupt or stale DB)"),
+    ]),
+    ("Run as a server", [
+        ("serve", "Start the MCP server over stdio — what an agent host launches"),
+        ("serve-http", "Start the HTTP transport (loopback only unless --allow-remote)"),
+        ("gen-token", "Print a secure random bearer token for serve-http / RBAC"),
+    ]),
+]
+
+_COMMANDS = [name for _group, items in _COMMAND_GROUPS for name, _desc in items]
+
+# Each command's body lives in codeintel.commands.<module> as `run(args) -> int`. The mapping is
+# spelled out rather than derived from the command name so the target of any command is greppable,
+# and the import happens at dispatch time so `codeintel serve` never pays for the semantic
+# engine's imports (nor serve-http for the graph's).
+_MODULES = {
+    "query": "query",
+    "map": "map",
+    "graph": "graph",
+    "setup": "setup",
+    "index": "index",
+    "install": "install",
+    "doctor": "doctor",
+    "status": "status",
+    "reset": "reset",
+    "serve": "serve",
+    "serve-http": "serve_http",
+    "gen-token": "gen_token",
+}
+
+_EXAMPLES = [
+    ("codeintel setup --all .", "prepare backends and index this repo"),
+    ("codeintel install", "register with the agents you have"),
+    ("codeintel query --op callers --target my_function", "who calls it?"),
+    ("codeintel doctor", "why is a query coming back empty?"),
+]
+
+
+def render_help() -> str:
+    """The `codeintel` / `codeintel help` screen: grouped, colored, with real examples.
+
+    Color comes from codeintel.term, so it auto-degrades on a pipe, under NO_COLOR, and on a dumb
+    terminal — same as every other human-facing command."""
+    from codeintel.term import c
+
+    width = max(len(name) for name in _COMMANDS)
+    out = [
+        c.bold("codeintel") + c.dim(f" {__version__}")
+        + c.dim("  —  code intelligence for AI agents: graph + LSP + semantic search"),
+        "",
+        c.dim("usage: ") + "codeintel <command> [options]",
+    ]
+    for group, items in _COMMAND_GROUPS:
+        out.append("")
+        out.append("  " + c.bold(group))
+        for name, desc in items:
+            out.append("    " + c.cyan(name.ljust(width)) + "  " + desc)
+
+    out.append("")
+    out.append("  " + c.bold("Examples"))
+    # Width from the content, not a guess — a hardcoded column silently loses its gutter the moment
+    # one example grows past it, and ljust() will not pad below the string's own length.
+    cmd_width = max(len(cmd) for cmd, _why in _EXAMPLES) + 2
+    for cmd, why in _EXAMPLES:
+        out.append("    " + cmd.ljust(cmd_width) + c.dim("# " + why))
+
+    out.append("")
+    out.append("  " + c.dim("codeintel <command> --help") + "   full options for one command")
+    out.append("  " + c.dim("docs: https://github.com/hamilton-sky/codeintel"))
+    return "\n".join(out)
+
+
+def _suggest(unknown: str) -> list[str]:
+    """Commands a typo probably meant. Close matches first, then prefix matches — `gragh` should
+    land on `graph`, and a bare `serv` on both `serve` and `serve-http`."""
+    close = difflib.get_close_matches(unknown, _COMMANDS, n=3, cutoff=0.5)
+    prefix = [cmd for cmd in _COMMANDS if cmd.startswith(unknown) and cmd not in close]
+    return (close + prefix)[:3]
+
+
+def _unknown_command(name: str) -> int:
+    """Report an unrecognized command with a way forward. argparse's own error dumps the full list
+    of choices and stops there, which is a dead end for a one-character typo."""
+    from codeintel.term import c_err as e
+
+    print(e.red(f"unknown command: {name!r}"), file=sys.stderr)
+    matches = _suggest(name)
+    if matches:
+        joined = " or ".join(e.cyan(m) for m in matches)
+        print(f"\n  did you mean {joined}?", file=sys.stderr)
+    print("\n  " + e.dim("run `codeintel help` to see every command"), file=sys.stderr)
+    return 2
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="codeintel")
+    parser.add_argument("--version", action="version", version=f"codeintel {__version__}")
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Shared flags for the human-facing (styled) commands.
+    color_parent = argparse.ArgumentParser(add_help=False)
+    color_parent.add_argument("--no-color", action="store_true", help="Disable ANSI color output")
+    color_parent.add_argument("--ascii", action="store_true", help="Use ASCII-only glyphs")
+
+    subparsers.add_parser("serve", help="Start the MCP server")
+
+    # index subcommand
+    index_parser = subparsers.add_parser("index", help="Index a project for semantic search")
+    index_parser.add_argument(
+        "project_root",
+        nargs="?",
+        default=None,
+        help="Project root directory (default: cwd)",
+    )
+
+    # query subcommand
+    query_parser = subparsers.add_parser("query", help="Query the code intelligence engine")
+    query_parser.add_argument("--op", required=True, help="Query operation (e.g. search, symbol)")
+    query_parser.add_argument("--target", required=True, help="Query target")
+    query_parser.add_argument("--engine", default="auto", help="Engine to use (default: auto)")
+    query_parser.add_argument(
+        "--project-root",
+        default=None,
+        help="Project root directory (default: cwd)",
+    )
+
+    # status subcommand
+    status_parser = subparsers.add_parser("status", help="Show code intelligence engine status")
+    status_parser.add_argument(
+        "project_root",
+        nargs="?",
+        default=None,
+        help="Project root directory (default: cwd)",
+    )
+
+    # serve-http subcommand
+    http_parser = subparsers.add_parser("serve-http", help="Start the HTTP transport server")
+    http_parser.add_argument("--port", type=int, default=8766, help="Port to listen on (default: 8766)")
+    http_parser.add_argument("--host", default="127.0.0.1", help="Host to bind to (default: 127.0.0.1)")
+    http_parser.add_argument("--allow-remote", action="store_true",
+                             help="Permit binding a non-loopback host (use with --token, or the "
+                                  "endpoint is UNAUTHENTICATED)")
+    http_parser.add_argument("--token", default=None,
+                             help="Require this bearer token on every request (or set "
+                                  "CODEINTEL_HTTP_TOKEN). Strongly recommended with --allow-remote.")
+
+    # install subcommand
+    install_parser = subparsers.add_parser("install", help="Register codeintel with AI agents")
+    install_parser.add_argument(
+        "--agent",
+        choices=["auto", "claude", "codex", "gemini", "zed", "all"],
+        default="auto",
+        help="Agent to register with (default: auto — only agents installed on this machine; "
+             "`all` forces every supported agent)",
+    )
+    install_parser.add_argument(
+        "--no-verify",
+        action="store_true",
+        help="Skip the post-registration MCP handshake (verification is on by default)",
+    )
+    install_parser.add_argument(
+        "--relative-command",
+        action="store_true",
+        help="Register the bare `codeintel` name instead of its absolute path (the absolute path "
+             "is the default because a GUI-launched agent does not inherit your shell's PATH)",
+    )
+
+    # map subcommand
+    map_parser = subparsers.add_parser("map", help="Generate CODE_INTEL.md orientation file")
+    map_parser.add_argument("project_root", nargs="?", default=None)
+    map_parser.add_argument("--inject", action="store_true", help="Inject reference block into CLAUDE.md/AGENTS.md")
+    map_parser.add_argument("--budget", type=int, default=32768, help="Byte budget for CODE_INTEL.md (default: 32768)")
+
+    # graph subcommand — interactive call-graph view (HTML) or the raw {nodes,edges} JSON
+    graph_parser = subparsers.add_parser(
+        "graph", help="Build an interactive call-graph view (--html) or emit the graph as JSON — "
+                      "works on any indexed repo")
+    graph_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    graph_parser.add_argument("--html", action="store_true",
+                              help="Write a self-contained interactive HTML viewer (default: print JSON)")
+    graph_parser.add_argument("--out", default=None, help="Output path for --html (default: codeintel-graph.html)")
+    graph_parser.add_argument("--limit", type=int, default=220, help="Max call edges to include (default: 220)")
+
+    # doctor subcommand
+    doctor_parser = subparsers.add_parser("doctor", parents=[color_parent],
+                                          help="Diagnose engine health + index status for a repo")
+    doctor_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    doctor_parser.add_argument("--deep", action="store_true",
+                               help="Also boot-check serena (slower; first boot pulls it via uvx)")
+    doctor_parser.add_argument("--json", action="store_true",
+                               help="Emit the structured JSON report instead of the table")
+
+    # setup subcommand
+    setup_parser = subparsers.add_parser("setup", parents=[color_parent],
+                                         help="Prepare backends and optionally index this repo")
+    setup_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    setup_parser.add_argument("--all", action="store_true", dest="all_steps",
+                              help="One-command setup: do everything automatable (uv + deps + index + "
+                                   "warm serena). Idempotent — skips what's already installed.")
+    setup_parser.add_argument("--install-uv", action="store_true",
+                              help="Run `pip install uv` (provides uvx for the LSP engine)")
+    setup_parser.add_argument("--install-deps", action="store_true",
+                              help="Run `pip install -e .` (semantic engine deps)")
+    setup_parser.add_argument("--index", action="store_true",
+                              help="Index this repo now (first run downloads the ~50MB model)")
+    setup_parser.add_argument("--warm", action="store_true", help="Boot serena now (first run pulls it via uvx; slow)")
+    setup_parser.add_argument("--json", action="store_true", help="Emit the structured JSON report")
+
+    # reset subcommand
+    reset_parser = subparsers.add_parser("reset", parents=[color_parent],
+                                         help="Clear the semantic index (recover from a corrupt/stale DB)")
+    reset_parser.add_argument("project_root", nargs="?", default=None, help="Project root (default: cwd)")
+    reset_parser.add_argument("--all", action="store_true",
+                              help="Clear the ENTIRE index (all projects), not just this repo")
+    reset_parser.add_argument("--yes", "-y", action="store_true", help="Skip the confirmation prompt")
+    reset_parser.add_argument("--json", action="store_true", help="Emit the structured JSON report")
+
+    subparsers.add_parser("gen-token", help="Print a secure random bearer token (for serve-http / RBAC auth.toml)")
+    subparsers.add_parser("help", help="Show every command, grouped, with examples")
+
+    # Intercept an unrecognized command BEFORE argparse, whose error prints the full choice list and
+    # stops — a dead end for a one-character typo. Only a bare word is claimed here; anything
+    # starting with `-` (--version, --help) still goes to argparse.
+    argv = sys.argv[1:]
+    if argv and not argv[0].startswith("-") and argv[0] not in [*_COMMANDS, "help"]:
+        sys.exit(_unknown_command(argv[0]))
+    if not argv or argv[0] == "help":
+        from codeintel import term
+        term.configure(no_color=False, ascii_mode=None)
+        print(render_help())
+        sys.exit(0)
+
+    args = parser.parse_args()
+
+    from codeintel import term
+    term.configure(
+        no_color=getattr(args, "no_color", False),
+        ascii_mode=(True if getattr(args, "ascii", False) else None),
+    )
+
+    module = _MODULES.get(args.command)
+    if module is None:          # unreachable via argparse; a bare `codeintel` is handled above
+        print(render_help())
+        sys.exit(0)
+    sys.exit(import_module(f"codeintel.commands.{module}").run(args))
+
+
+if __name__ == "__main__":
+    main()