no-mistakes(document): align static-model, engine-path and profile docs with code

Author: anvanster

README.md

@@ -117,10 +117,11 @@ The model is not bundled with any client — it needs a local model directory
 - Otherwise fetch the prebuilt one with `scripts/fetch-static-model.sh`, or
   distill your own from any sentence-transformer (Apache-2.0 Jina-Code by
   default) in ~30 s on CPU: `python scripts/distill_static_model.py`.
-- In VS Code set `codegraph.staticModelPath` to the model directory; in
-  JetBrains use *Settings → Tools → CodeGraph → Embeddings → Static model
-  directory*. Both IDE clients pass it to the server as
-  `CODEGRAPH_STATIC_MODEL`.
+- A model in the default location needs no IDE setting: both IDE clients leave
+  `CODEGRAPH_STATIC_MODEL` unset and let the engine resolve it. To use a model
+  kept somewhere else, set `codegraph.staticModelPath` in VS Code, or
+  *Settings → Tools → CodeGraph → Embeddings → Static model directory* in
+  JetBrains; each client then passes that path as `CODEGRAPH_STATIC_MODEL`.
 
 #### `CODEGRAPH_SKIP_MEMORY_CHECK` — force the embedding model past the RAM gate
 
@@ -151,19 +152,10 @@ The full 42-tool surface is convenient but inflates the agent's prompt-context c
 
 ### VS Code settings
 
-```jsonc
-{
-  "codegraph.indexOnStartup": true,
-  "codegraph.indexPaths": ["/path/to/project-a", "/path/to/project-b"],
-  "codegraph.excludePatterns": ["**/cmake-build-debug/**", "**/generated/**"],
-  "codegraph.embeddingModel": "bge-small",        // or "static" for ~100× faster indexing
-  "codegraph.staticModelPath": "",                // required when embeddingModel is "static": the model2vec model dir
-  "codegraph.maxFileSizeKB": 1024,
-  "codegraph.codeLens.enabled": true,             // caller / test / complexity counts above functions
-  "codegraph.hover.enabled": true,                // the same stats on hover
-  "codegraph.debug": false
-}
-```
+The `codegraph.*` settings are documented once, next to the extension that
+reads them:
+
+→ **[vscode/README.md — Configuration](vscode/README.md#configuration)**
 
 Full-body embeddings are enabled by default. Function body text is captured at parse time with zero I/O overhead.
 

mcp-package/README.md

@@ -22,9 +22,14 @@ npx codegraph-mcp-fetch-engine          # --force re-downloads an engine that is
 ```
 
 For air-gapped machines, or if you vendor the binary yourself, set
-`CODEGRAPH_SKIP_BINARY_FETCH=1` to skip the download and place the engine at
-`<package>/bin/codegraph-server-<platform>-<arch>` (`.exe` on Windows) yourself -
-that is the path `codegraph-mcp` launches.
+`CODEGRAPH_SKIP_BINARY_FETCH=1` to skip the download and supply the engine one
+of two ways:
+
+- place it at `<package>/bin/codegraph-server-<platform>-<arch>` (`.exe` on
+  Windows) - the path `codegraph-mcp` launches by default; or
+- point `CODEGRAPH_SERVER_PATH` at the engine wherever it already lives. This
+  wins over the bundled path, and `codegraph-mcp` fails with a clear message
+  rather than falling back if nothing is there.
 
 ## Usage
 
@@ -62,13 +67,17 @@ Pass flags after `--`:
 }
 ```
 
+Leave the transport out of `args`: `codegraph-mcp` already puts the engine in
+MCP (stdio) mode, so `--mcp`, `--stdio` and `--connect` are dropped from
+whatever the client passes rather than forwarded twice.
+
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--workspace <path>` | current dir | Directories to index (repeatable) |
 | `--exclude <dir>` | — | Directories to skip (repeatable) |
-| `--embedding-model <model>` | `bge-small` | `bge-small`, `jina-code-v2`, `granite-97m` (32K, multilingual), or `static` (model2vec, ~100× faster indexing, ~90% of BGE quality; needs a local model dir via `CODEGRAPH_STATIC_MODEL`) |
+| `--embedding-model <model>` | `bge-small` | `bge-small`, `jina-code-v2`, `granite-97m` (32K, multilingual), or `static` (model2vec, ~100× faster indexing, ~90% of BGE quality; needs a local model dir - this install downloads one to `~/.codegraph/static_models/jina-code-static-256`, or point `CODEGRAPH_STATIC_MODEL` elsewhere) |
 | `--max-files <n>` | 5000 | Maximum files to index |
-| `--profile <name>` | `all` | Scope tool surface: `core` (8), `graph` (16), `memory` (14), `security` (pro), `all` (42) |
+| `--profile <name>` | `all` | Scope tool surface: `core` (8), `graph` (17), `memory` (14), `security` (pro), `all` (42) |
 | `--graph-only` | off | Skip embeddings — graph + structural tools only. No ONNX model load, 10-50× faster indexing. For CI / one-shot graph queries. |
 | `--run-tool <name>` | — | One-shot: index, run a single tool, print result, exit. No MCP handshake. Pair with `--tool-args '<json>'`. |
 

scripts/fetch-static-model.sh

@@ -9,8 +9,9 @@
 #
 # The model is no longer staged into the VS Code extension bundle: the VSIX
 # excludes bin/** (see vscode/.vscodeignore), so a copy placed there would be
-# dropped at package time. IDE users point codegraph.staticModelPath at the
-# directory this script writes instead.
+# dropped at package time. The IDE clients leave CODEGRAPH_STATIC_MODEL unset
+# unless the user names a directory, so the default path this script writes is
+# what they pick up - no per-client setting needed.
 #
 # Usage: scripts/fetch-static-model.sh [DEST_DIR] [MODEL_NAME]
 #   DEST_DIR    default ~/.codegraph/static_models/<MODEL_NAME>

vscode/README.md

@@ -62,7 +62,7 @@ CodeGraph's Symbols and Memories views live in the CodeGraph activity-bar contai
   "codegraph.indexPaths": ["/path/to/project-a", "/path/to/project-b"],
   "codegraph.excludePatterns": ["**/cmake-build-debug/**", "**/generated/**"],
   "codegraph.embeddingModel": "bge-small",        // or "static" for ~100× faster indexing
-  "codegraph.staticModelPath": "",                // required when embeddingModel is "static": the model2vec model dir
+  "codegraph.staticModelPath": "",                // only to override the default model2vec model dir
   "codegraph.maxFileSizeKB": 1024,
   "codegraph.codeLens.enabled": true,             // caller / test / complexity counts above functions
   "codegraph.hover.enabled": true,                // the same stats on hover
@@ -71,7 +71,8 @@ CodeGraph's Symbols and Memories views live in the CodeGraph activity-bar contai
 ```
 
 The static (model2vec) model is not bundled with the extension.
-Distill one with [`scripts/distill_static_model.py`](https://github.com/codegraph-ai/codegraph/blob/main/scripts/distill_static_model.py), or reuse the copy the `@astudioplus/codegraph-mcp` npm install puts in `~/.codegraph/static_models/jina-code-static-256`, and point `codegraph.staticModelPath` at it.
+The engine looks for it in `~/.codegraph/static_models/jina-code-static-256`, which is where the `@astudioplus/codegraph-mcp` npm install puts it, so a model in that location needs no setting at all.
+Set `codegraph.staticModelPath` only to point at a model somewhere else - for instance one you distilled yourself with [`scripts/distill_static_model.py`](https://github.com/codegraph-ai/codegraph/blob/main/scripts/distill_static_model.py).
 
 Full-body embeddings are enabled by default. Function body text is captured at parse time with zero I/O overhead.
 

vscode/package.json

@@ -304,15 +304,15 @@
                     "enumDescriptions": [
                         "BGE-Small-EN-v1.5 (384d) — fast, good quality with full-body embeddings. ~127MB download.",
                         "Jina Code V2 (768d) — 6x slower indexing, no quality advantage with full-body embeddings. ~642MB download.",
-                        "Static (model2vec, 256d) — ~100x faster indexing, no ONNX runtime or 1.5GB RAM gate, ~90% of BGE quality in hybrid search. Requires a local model dir in codegraph.staticModelPath."
+                        "Static (model2vec, 256d) — ~100x faster indexing, no ONNX runtime or 1.5GB RAM gate, ~90% of BGE quality in hybrid search. Needs a local model dir: ~/.codegraph/static_models/jina-code-static-256 by default, or codegraph.staticModelPath."
                     ],
                     "description": "Embedding model for semantic search and code similarity"
                 },
                 "codegraph.staticModelPath": {
                     "type": "string",
                     "default": "",
                     "scope": "resource",
-                    "description": "Directory of the model2vec static model (config.json + tokenizer.json + model.safetensors). Required when embeddingModel is 'static' - the model is not bundled with the extension. Installing @astudioplus/codegraph-mcp from npm puts a copy in ~/.codegraph/static_models/jina-code-static-256, or distill one with scripts/distill_static_model.py."
+                    "description": "Directory of the model2vec static model (config.json + tokenizer.json + model.safetensors). Only set this to use a model outside the default location: left empty, the engine resolves ~/.codegraph/static_models/jina-code-static-256, which is where installing @astudioplus/codegraph-mcp from npm puts it. The model is not bundled with the extension - distill one with scripts/distill_static_model.py if you have neither."
                 },
                 "codegraph.fullBodyEmbedding": {
                     "type": "boolean",