docs: update for explicit check_engine install flow

Author: Broccolito

CHANGELOG.md

@@ -6,8 +6,11 @@
 - Python proxy shim (paths, bootstrap, proxy, error shim).
 - Vendored CodeGraph engine from upstream v0.9.7.
 - Verified `build-bundle.sh` produces a working local-platform bundle.
-- Fixed `_launcher_path` in `bootstrap.py`: tarball extracts to
-  `engine/codegraph-<tag>/bin/codegraph` (not `engine/bin/codegraph`);
-  updated path to include the platform subdirectory.
-- End-to-end smoke test verified: shim spawns engine, tools list returns ~9
+- End-to-end smoke test verified: shim spawns engine, tools list returns ~10
   codegraph_* tools, symlink + DB materialize at expected paths.
+- **UX revision:** the engine binary (~45 MB) is no longer downloaded
+  silently on first start. Instead, the shim exposes a single
+  `codegraphagent_check_engine` tool that the agent must call first to
+  trigger the download. Subsequent calls return immediately. This replaces
+  a silent 30-60s stall during MCP initialize with a visible, deliberate
+  tool call.

README.md

@@ -6,22 +6,41 @@ trace) via a vendored fork of [CodeGraph](https://github.com/colbymchenry/codegr
 
 ## What it does
 
-CodeGraphAgent installs into a BioRouter session and exposes 9 MCP tools
+CodeGraphAgent installs into a BioRouter session and exposes 10 MCP tools
 (`codegraph_search`, `codegraph_callers`, `codegraph_callees`,
 `codegraph_trace`, `codegraph_impact`, `codegraph_node`, `codegraph_explore`,
-`codegraph_context`, `codegraph_status`) that let the agent answer "where is X
-used?", "what does Y call?", and "what breaks if I change Z?" against the
-current project — without re-parsing the codebase on every query.
+`codegraph_context`, `codegraph_status`, `codegraph_files`) that let the
+agent answer "where is X used?", "what does Y call?", and "what breaks if I
+change Z?" against the current project — without re-parsing the codebase on
+every query.
 
-The index lives at `<project>/.biorouter/codegraph/codegraph.db`. On first
-use the extension downloads a vendored CodeGraph engine bundle (~50 MB) from
-this repo's GitHub Releases.
+The index lives at `<project>/.biorouter/codegraph/codegraph.db`.
+
+## First-time install flow
+
+When you first enable CodeGraphAgent in a session, the engine binary (~45 MB)
+is **not** downloaded automatically. Instead, the extension exposes a single
+tool, `codegraphagent_check_engine`. Ask the agent to call it, or call it
+yourself — it'll download + verify + extract the engine, taking about
+30-60 seconds. After that, all the `codegraph_*` tools become available and
+work transparently.
+
+This is intentional: the download is deliberate and visible, rather than
+hidden in a silent stall during MCP initialize.
 
 ## Install
 
 Once a `.brxt` release is published, BioRouter installs the extension via:
 `Settings → Extensions → Install from file → codegraphagent.brxt`.
 
+## Configuration (optional env vars)
+
+| Variable | Purpose |
+| --- | --- |
+| `CODEGRAPH_ENGINE_PATH` | Path to an already-extracted engine bundle. Skips the on-first-use download — useful for air-gapped or CI environments. |
+| `CODEGRAPH_ENGINE_VERSION` | Override the pinned engine release tag. |
+| `CODEGRAPH_NO_WATCH` | Set to `1` to disable the file watcher (slow filesystems like WSL2). |
+
 ## Status
 
 v0.1.0-rc1 — initial release wrapping upstream CodeGraph unchanged.

manifest.json

@@ -1,7 +1,7 @@
 {
   "name": "codegraphagent",
   "display_name": "CodeGraphAgent",
-  "description": "Pre-indexed code knowledge graph (callers, callees, impact, trace) via vendored CodeGraph engine. Per-project index stored at <project>/.biorouter/codegraph/.",
+  "description": "Pre-indexed code knowledge graph (callers, callees, impact, trace) via a vendored CodeGraph engine. First use: call codegraphagent_check_engine to download the ~45 MB engine bundle (one-time, takes 30-60s). After that, the codegraph_* tools become available. Per-project index stored at <project>/.biorouter/codegraph/.",
   "version": "0.1.0",
   "entry_point": "codegraphagent",
   "repository": "https://github.com/Broccolito/CodeGraphAgent",