codesearch-mcp 0.2.3-alpha → 0.4.0-alpha

package/README.md

@@ -7,7 +7,7 @@ Ask your AI agent things like *"where is the payment retry logic?"* or *"show me
 **Why codesearch-mcp:**
 
 - **Dramatically fewer tokens** — without RAG, answering a cross-project question means discovery calls, directory listings, and reading several wrong files before finding the right one; a workspace of 10 projects can easily mean 50 000+ lines to sift through. With RAG, one `search_codebase` call returns 5 targeted chunks (~200–500 lines total) from across *all* projects at once — the model gets the right code immediately, with no exploration overhead
-- **Reranker narrows the result further** — a cross-encoder reranker (enabled by default) re-scores the candidate pool so the top results are the most relevant, not just the closest vector; fewer results means less context consumed per answer
+- **Reranker narrows the result further** — a cross-encoder reranker (on by default with the local Infinity backend; local or Voyage AI) re-scores the candidate pool so the top results are the most relevant, not just the closest vector; fewer results means less context consumed per answer
 - **Semantic, not grep** — embeddings capture intent; queries in plain English or pseudocode find the relevant code regardless of naming
 - **Local and private** — default setup runs entirely on your machine (Infinity embeddings + PostgreSQL); no code leaves your network
 - **Code-structure aware** — chunks align to function and class boundaries; each result shows which declaration it belongs to (`InvoiceService.create`, `collectFiles`, …), so the model understands context without reading the surrounding file
@@ -30,8 +30,8 @@ See `CHANGELOG.md` for version history.
 
 ## Requirements
 
-- Node.js 18+
-- PostgreSQL 15+ with pgvector (the symbol index's unique index relies on `NULLS NOT DISTINCT`, added in PostgreSQL 15)
+- Node.js `^22.13.0` or `>=23.5.0`
+- PostgreSQL 15+ with pgvector (the symbol index's unique index relies on `NULLS NOT DISTINCT`, added in PostgreSQL 15); pgvector ≥ 0.8 recommended (filtered search on large projects; older versions work with reduced recall)
 - Docker (for local DB + Infinity) — or bring your own PostgreSQL with pgvector + an embedding backend (see [Embedding providers](#embedding-providers))
 
 ## Installation
@@ -48,7 +48,8 @@ rag-setup
 
 Walks you through:
 - **Database** — enter connection details; optionally starts Docker containers automatically
-- **Embedding backend** — pick a provider (`infinity` / `openai-compatible` / `voyage`), its model, and an API key if the provider needs one (see [Embedding providers](#embedding-providers))
+- **Embedding backend** — pick a provider (`infinity` / `openai-compatible` / `voyage`), its model, and an API key if the provider needs one (see [Embedding providers](#embedding-providers)), then a reranker
+  - **`voyage`** is a short path: the API key comes first and is required (stored once in `.env` as `VOYAGE_API_KEY`); no base URL is asked. The embedding model is picked from a numbered list (`voyage-code-4` default, `voyage-4-large`, `voyage-4`, `voyage-4-lite`) — enter a number, press Enter for the default, or type any model name. Then `Enable Voyage reranker? (y/n) (y)`: `y` picks `rerank-3` (default) or `rerank-3-lite` the same way and reuses the same key (`reranker.apiKey: env:VOYAGE_API_KEY`); `n` turns reranking off. Other rerankers for a Voyage embedder (an `openai-compatible` `/rerank` server, a separate Voyage key) are set with `rag-config` — see [Reranker with a cloud embedder](#reranker-with-a-cloud-or-external-embedder)
 - **Logging** — choose log level and directory (defaults: `error` level, `~/.config/codesearch-mcp/logs/`)
 
 Config is saved to `~/.config/codesearch-mcp/config.json`.
@@ -76,15 +77,28 @@ rag-index --select --reindex
 rag-index --project billing-service           # scope this run to one project, by exact name
 rag-index --reindex --project billing-service # force a full reindex of just that project
 rag-index --project                           # no name — pick one from an interactive prompt
+rag-index --project billing-service --require-cwd # refuse the run unless the current directory is that project's directory
 ```
 
 `--project` leaves every other indexed project untouched: it skips the `.ragprojects`/`.ragskip` selector entirely and never prunes projects outside the one(s) it resolves to. A name that doesn't match any discovered project or monorepo unit exits with an error before touching the database — matching exactly, no partial or fuzzy match.
 
+`--require-cwd` is for scripts that must not read another checkout's index by accident: run from a linked worktree, a second clone, or a subdirectory of the project, `rag-index` prints both directories and exits 1 before any database or embedding work. It needs `--project <name>`; without a name it is a usage error, never a prompt. Directories are compared by real path, against the unit's directory when a unit name matched, else the leaf project's, and a relative `workspaceRoot` is refused. In a root-level Nx workspace with no discovered project at its root, no `--project` name matches that root, so `--require-cwd` refuses every run from there.
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | No file failed and nothing else failed. This includes an interrupted run, which may have left files unindexed. |
+| `2` | The run finished with failed files and the rest of the index is usable. `Indexing finished with <n> of <total> file(s) failed.` is on stderr, and the next run retries those files. |
+| `1` | Any other failure, including failed files in a run that was interrupted, skipped no file and stored no chunks, failed to prune, or ended with the database or the embedding backend unavailable (`Indexing backend unavailable: <cause>`). |
+
+A failed file does not stop the run: the summary is still printed, and unless the run is interrupted the remaining files and projects are still indexed and the project graph is still produced.
+
 ## Monorepo support
 
 If `workspaceRoot` is an [Nx](https://nx.dev) workspace (detected by `nx.json`), `rag-index` discovers each project under `apps/`, `libs/`, and `packages/` as a **separate indexed project** rather than scanning the workspace as one blob. Cross-project imports like `@scope/shared` resolve through the workspace `tsconfig.base.json` path aliases, so `get_dependencies` / `get_dependents` report edges **across** projects.
 
-**Nested Nx repos.** `workspaceRoot` may also be a plain directory that *contains* an Nx repo in one of its immediate subdirectories (alongside ordinary projects). That nested repo is detected and expanded into its own projects, named `<repo>/<project>` (e.g. `micros-learning/account`), each resolved with the repo's own `tsconfig.base.json`. In the project selector the whole Nx repo appears as **one** selectable entry (so `.ragprojects` stores just `micros-learning`); selecting it indexes all its sub-projects. Ordinary sibling directories are unaffected.
+**Nested Nx repos.** `workspaceRoot` may also be a plain directory that *contains* an Nx repo in one of its immediate subdirectories (alongside ordinary projects). That nested repo is detected and expanded into its own projects, named `<repo>/<project>` (e.g. `mu-monorepo/account`), each resolved with the repo's own `tsconfig.base.json`. In the project selector the whole Nx repo appears as **one** selectable entry (so `.ragprojects` stores just `mu-monorepo`); selecting it indexes all its sub-projects. Ordinary sibling directories are unaffected.
 
 No configuration needed — detection is automatic. Plain (non-Nx) workspaces keep the original behavior: each immediate subdirectory with a `package.json` is one project.
 
@@ -106,7 +120,7 @@ Every file or directory argument is **workspace-relative** (relative to `workspa
 
 | Tool | Description |
 |------|-------------|
-| `search_codebase` | Semantic search across all indexed projects. Accepts `include_graph_context` to append direct imports/dependents to each result, `include_neighbors` for surrounding chunks, `threshold` to override the similarity threshold for that query, and `rerank` to force reranking on/off for that call regardless of `reranker.enabled` |
+| `search_codebase` | Semantic search across all indexed projects. Accepts `include_graph_context` to append direct imports/dependents to each result, `include_neighbors` for surrounding chunks, `threshold` to override the similarity threshold for that query, `rerank` to force reranking on/off for that call regardless of `reranker.enabled`, and `per_file` (default 2) to cap how many results come from one file |
 | `list_projects` | List projects with metadata, chunk counts and each project's directory (`path:` line) |
 | `find_symbol` | Find a declaration or member by exact name — bare, qualified (`Class.method`), quoted, or computed — faster than semantic search. Also finds a NestJS GraphQL operation, resolve field or type by its GraphQL name (`kind: graphql_query`/`graphql_mutation`/`graphql_subscription`/`graphql_field`/`graphql_type`) |
 | `list_files` | Browse the directory tree of any workspace directory |
@@ -126,7 +140,7 @@ Add `.ragmeta.json` to a project root to enrich `list_projects` and generate a v
   "stack": "NestJS, GraphQL, PostgreSQL",
   "notes": "Uses optimistic locking — see order-service/docs/concurrency.md",
   "relations": {
-    "consumed_by": ["crm-frontend"],
+    "consumed_by": ["beta-frontend"],
     "consumes": ["billing-service", "auth-service"]
   }
 }
@@ -143,14 +157,14 @@ Pass `include_graph_context: true` to `search_codebase` to see direct imports an
 **Symbol:** InvoiceService.create
 **Line:** 45
 ...code...
-**Relevance:** 0.32
+**Distance:** 0.32
 **Imports:** src/repositories/InvoiceRepo.ts · src/dto/CreateInvoiceDto.ts
 **Used by:** src/controllers/InvoiceController.ts
 ```
 
 Useful for immediately understanding a file's role in the dependency graph.
 
-Each result also shows a **Symbol** breadcrumb — the declaration the chunk belongs to (`InvoiceService.create`, `collectFiles`, …) — so you can see the enclosing class/method without opening the file. It is omitted for module-scope chunks and for projects indexed before this feature (re-index to populate).
+Each result also shows a **Symbol** breadcrumb — the smallest declaration containing all of the chunk's declaration code (`InvoiceService.create`, `collectFiles`, …) — so you can see the enclosing class/method without opening the file. A chunk packing several small members shows their class. Module-scope code (top-level statements, enums, `declare module`) belongs to no declaration, so a chunk packing it with one small declaration shows that declaration; the breadcrumb is omitted for a chunk of module-scope code only, for chunks packing several small top-level declarations, and for projects indexed before this feature (re-index to populate).
 
 ## Excluding files
 
@@ -174,6 +188,12 @@ npx pino-pretty < ~/.config/codesearch-mcp/logs/indexer/current.log
 # Detailed indexing diagnostics (timing per file: deps / embed / db)
 rag-config set logging.level debug
 
+# See what an agent called (needs logging.level info or debug), grouped by session and connection
+jq -c 'select(.msg=="tool call") | {session, connectionId, callId, tool, args, isError, ms}' \
+  ~/.config/codesearch-mcp/logs/mcp/current.log
+jq -s 'map(select(.msg=="tool call")) | group_by(.session, .connectionId) | map({session: .[0].session, connectionId: .[0].connectionId, calls: map(.tool)})' \
+  ~/.config/codesearch-mcp/logs/mcp/current.log
+
 # Disable file logging
 rag-config set logging.dir false
 ```
@@ -204,13 +224,13 @@ rag-config edit                      # open config in $EDITOR; validates on save
 | `embedding.model` | `jinaai/jina-embeddings-v2-base-code` | Embedding model |
 | `embedding.dimensions` | (derived) | Vector width override; required for models whose native width exceeds 2000 (Matryoshka). Otherwise derived from model → registry → runtime probe |
 | `embedding.batchSize` | `32` | Texts per batch embedding request |
-| `search.similarityThreshold` | `0.6` | Max cosine distance — raise if search returns nothing |
-| `reranker.enabled` | `true` | Enable cross-encoder reranking; requires `reranker.model` |
-| `reranker.provider` | `openai-compatible` | Rerank backend — `openai-compatible` `/rerank` only (Infinity, TEI, vLLM) |
-| `reranker.baseURL` | `embedding.baseURL` | Rerank server base URL (Infinity serves embed + rerank from one server) |
-| `reranker.model` | `mixedbread-ai/mxbai-rerank-xsmall-v1` | Reranker model name |
-| `reranker.overfetch` | `5` | Candidate multiplier before reranking (`limit × N`) |
-| `reranker.candidateFloor` | `80` | Minimum candidate pool fed to the reranker regardless of `limit` — `fetchLimit = min(max(limit × overfetch, candidateFloor), 200)`. Raise on GPU/fast hosts for better recall; lower on weak CPU to cut latency |
+| `search.similarityThreshold` | per model | Max cosine distance, lower = stricter. Auto per model unless set: the recommended value of `embedding.model` (`0.95` for `voyage-code-4`, `voyage-4`, `voyage-4-large` and `voyage-4-lite`, `0.6` for `jinaai/jina-embeddings-v2-base-code`), `1.0` for a model with none. An explicit value more than `0.1` from the recommendation produces a warning in the MCP server instructions and the log, and on the eval console |
+| `reranker.enabled` | context | Enable cross-encoder reranking. When absent: on with `infinity` embedding or when the `reranker` block names a server (`provider`/`baseURL`/`url`), off otherwise |
+| `reranker.provider` | `openai-compatible` | Rerank backend — `openai-compatible` `/rerank` (Infinity, vLLM) or `voyage` (Voyage AI, needs `reranker.apiKey`) |
+| `reranker.baseURL` | per-provider | Rerank server base URL — `embedding.baseURL` for `openai-compatible` (Infinity serves embed + rerank from one server), `https://api.voyageai.com/v1` for `voyage` |
+| `reranker.model` | per-provider | Reranker model name — `mixedbread-ai/mxbai-rerank-xsmall-v1` for `openai-compatible`, `rerank-3` for `voyage` |
+| `reranker.overfetch` | `5` | Candidate multiplier before reranking (`limit × N`); also sizes the pool of a search without reranking whose `per_file` is below `limit` |
+| `reranker.candidateFloor` | `80` | Minimum candidate pool fed to the reranker regardless of `limit` — `fetchLimit = min(max(limit × overfetch, candidateFloor), 200)`. The same pool serves a search without reranking whose `per_file` is below `limit`. Raise on GPU/fast hosts for better recall; lower on weak CPU to cut latency |
 | `indexing.chunkSize` | `1500` | Max characters per chunk |
 | `indexing.chunkOverlap` | `200` | Overlap between chunks |
 | `indexing.embedBatchSize` | `5` | Parallel embedding requests per batch |
@@ -218,9 +238,8 @@ rag-config edit                      # open config in $EDITOR; validates on save
 | `indexing.chunkStrategy` | `ast` | How TS/JS files are chunked: `ast` = boundaries aligned to functions/classes, `character` = fixed-size splitter. Re-index to apply |
 | `search.defaultLimit` | `5` | Default result count returned by `search_codebase` |
 | `search.maxLimit` | `20` | Hard cap on result count |
-| `logging.level` | `error` | Log level written to file: `error` \| `warn` \| `info` \| `debug` |
+| `logging.level` | `error` | Log level written to file: `error` \| `warn` \| `info` \| `debug`. `info` adds one `tool call` line per MCP tool call and one `search metrics` line per search |
 | `logging.dir` | `~/.config/codesearch-mcp/logs` | Base log directory, or `"false"` to disable |
-| `logging.searchMetrics` | `false` | Emit one structured search-tuning line per query (at `info`, independent of `logging.level`) — use it to size `candidateFloor`/`overfetch`/`threshold` for your hardware |
 
 ## Embedding providers
 
@@ -234,7 +253,7 @@ rag-config edit                      # open config in $EDITOR; validates on save
 | `openai-compatible` | OpenAI cloud, or any OpenAI-style server (TEI, vLLM, LM Studio, LocalAI, **or Ollama via its `/v1` endpoint**). | `baseURL` (+ `apiKey` for cloud) |
 | `voyage` | Voyage AI cloud, code-specialized embeddings. | Voyage `apiKey` |
 
-Easiest path: `rag-setup` asks for the provider, model, and any API key. Haven't run setup? It's the place to start. To change things later, edit config directly (below).
+Easiest path: `rag-setup` asks for the provider, model, any API key, and a reranker. Haven't run setup? It's the place to start. To change things later, edit config directly (below).
 
 ### Switching provider or changing the model
 
@@ -246,14 +265,14 @@ rag-config set embedding.provider openai-compatible
 rag-config set embedding.baseURL  https://api.openai.com/v1
 rag-config set embedding.model    text-embedding-3-small
 rag-config set embedding.apiKey   env:OPENAI_API_KEY     # key lives in .env, not config.json
-rag-config set reranker.enabled   false                  # OpenAI has no /rerank endpoint
+rag-config set reranker.enabled   false                  # only if rag-setup chose the `infinity` reranker: it stays aimed at the old server
 rag-index --reindex
 
 # Switch to Voyage AI
 rag-config set embedding.provider voyage
-rag-config set embedding.model    voyage-code-3
+rag-config set embedding.model    voyage-code-4
 rag-config set embedding.apiKey   env:VOYAGE_API_KEY     # key lives in .env, not config.json
-rag-config set reranker.enabled   false                  # Voyage has no /rerank endpoint
+rag-config set reranker.enabled   false                  # only if rag-setup chose the `infinity` reranker (or configure the Voyage reranker, below)
 rag-index --reindex
 
 # Change only the model on the current provider
@@ -272,9 +291,9 @@ rag-index --reindex
 Per-provider notes:
 
 - **infinity** — the model set is bound at container startup, so changing `embedding.model` (or the reranker model) **recreates** the managed container on the next `rag-setup`/`rag-index`/dashboard save. Defaults: `jinaai/jina-embeddings-v2-base-code` + reranker `mixedbread-ai/mxbai-rerank-xsmall-v1`. Both models are included in the compose template and reranking is **enabled by default** (`reranker.enabled: true`).
-- **openai-compatible** — point `embedding.baseURL` at the server; set `embedding.apiKey` (as `env:VAR`) for cloud, leave empty for local servers (TEI/vLLM/LM Studio/**Ollama**). E.g. `text-embedding-3-small`, `text-embedding-3-large`. Cloud endpoints (OpenAI, Azure) don't expose `/rerank` — disable the reranker or point it at a separate server (see [Reranker with a cloud embedder](#reranker-with-a-cloud-or-external-embedder)).
+- **openai-compatible** — point `embedding.baseURL` at the server; set `embedding.apiKey` (as `env:VAR`) for cloud, leave empty for local servers (TEI/vLLM/LM Studio/**Ollama**). E.g. `text-embedding-3-small`, `text-embedding-3-large`. Cloud endpoints (OpenAI, Azure) don't expose `/rerank`, so without a `reranker` block reranking stays off unless you configure a separate rerank server; a block from `rag-setup`'s `infinity` reranker choice keeps reranking on at the old server until you set `reranker.enabled false` (see [Reranker with a cloud embedder](#reranker-with-a-cloud-or-external-embedder)).
 - **Ollama** (via `openai-compatible`) — set `embedding.baseURL` to `http://localhost:11434/v1` and `embedding.model` to any model you've pulled (e.g. `bge-m3`). No dedicated code path, no auto-pull — pull the model yourself with `ollama pull <model>` first.
-- **voyage** — set `embedding.apiKey` (as `env:VAR`); e.g. `voyage-code-3`, `voyage-3`. Voyage doesn't expose a `/rerank` endpoint in the OpenAI-compatible format — disable the reranker or point it at a separate server (see [Reranker with a cloud embedder](#reranker-with-a-cloud-or-external-embedder)).
+- **voyage** — set `embedding.apiKey` (as `env:VAR`); e.g. `voyage-code-4` (default in `rag-setup`), `voyage-4-large`, `voyage-4`, `voyage-4-lite`. Older names such as `voyage-code-3` still work — their dimension is probed. Without a `reranker` block, reranking stays off unless you configure one (a block from `rag-setup`'s `infinity` reranker choice keeps it on at the old server until you set `reranker.enabled false`) — e.g. the Voyage reranker (see [Reranker with a cloud embedder](#reranker-with-a-cloud-or-external-embedder)).
 
 The vector **dimension** is derived automatically (model registry → one-shot probe); set `embedding.dimensions` only to force a Matryoshka-reduced width for models whose native size exceeds 2000.
 
@@ -291,23 +310,36 @@ The same "already running?" probe applies everywhere: a reachable backend defaul
 
 ### Reranker with a cloud or external embedder
 
-The reranker is **enabled by default** (`reranker.enabled: true`) and `reranker.baseURL` defaults to `embedding.baseURL`. Cloud embedding endpoints (OpenAI, Voyage, Azure) don't serve `/rerank` — the reranker call will fail silently and fall back to vector order on every query. Fix it one of two ways:
+With a cloud embedder (OpenAI, Voyage, Azure) and no `reranker` block, reranking is **off** — those endpoints don't serve `/rerank`. `rag-setup` configures a reranker after the embedding step for every provider and always writes an explicit `reranker` block: a Voyage embedder gets one question, `Enable Voyage reranker?`, and shares its `VOYAGE_API_KEY`; other embedders choose `voyage` (own key, `VOYAGE_RERANK_API_KEY`), `openai-compatible` or `none`, plus `infinity` for an Infinity embedder. To configure one by hand:
 
-**Option A — disable reranking** (simplest, recommended for cloud-only setups):
+These recipes edit whatever `reranker` block is already stored, so each one sets `reranker.enabled true` (an explicit `false` from `rag-setup`'s `none` choice, or the `n` answer to a Voyage embedder's `Enable Voyage reranker?`, would otherwise win) and clears the keys that would point the requests at the old server.
+
+**Voyage reranker** (works with any embedder; with a Voyage embedder `reranker.apiKey` can point at the same `env:VOYAGE_API_KEY` instead of a separate key):
 
 ```bash
-rag-config set reranker.enabled false
+echo 'VOYAGE_RERANK_API_KEY=pa-…' >> ~/.config/codesearch-mcp/.env
+rag-config set   reranker.enabled  true
+rag-config set   reranker.provider voyage
+rag-config set   reranker.model    rerank-3                  # or rerank-3-lite
+rag-config set   reranker.apiKey   env:VOYAGE_RERANK_API_KEY
+rag-config reset reranker.baseURL                           # a stored Infinity baseURL would win over the Voyage default
+rag-config reset reranker.url
 ```
 
-**Option B — point the reranker at a separate server** (e.g. a local Infinity or TEI instance while using Voyage/OpenAI for embeddings):
+Without `reranker.apiKey` a Voyage reranker stays disabled and a warning is written to the log — visible only at `logging.level` `warn` or lower (the default `error` hides it).
+
+**A separate `/rerank` server** (e.g. a local Infinity or vLLM instance while using Voyage/OpenAI for embeddings):
 
 ```bash
-rag-config set reranker.baseURL http://localhost:7997
-rag-config set reranker.model   mixedbread-ai/mxbai-rerank-xsmall-v1
-# reranker.enabled is already true
+rag-config set   reranker.enabled  true
+rag-config set   reranker.provider openai-compatible       # a stored voyage provider would send the Voyage wire format
+rag-config set   reranker.baseURL  http://localhost:7997
+rag-config set   reranker.model    mixedbread-ai/mxbai-rerank-xsmall-v1
+rag-config reset reranker.url
+rag-config reset reranker.apiKey                          # unless the server needs one
 ```
 
-The embedding and reranking servers are fully independent — any combination works: Voyage embeddings + local Infinity reranker, OpenAI embeddings + remote TEI reranker, etc.
+The embedding and reranking servers are fully independent — any combination works: Voyage embeddings + local Infinity reranker, OpenAI embeddings + remote vLLM reranker, etc.
 
 ### Secrets & external embedders
 
@@ -320,18 +352,20 @@ Switching the embedding model, provider, or dimension is applied by **re-indexin
 When reranking is enabled, `search_codebase` fetches a **candidate pool** by cosine distance, reranks it with the cross-encoder, and returns the top `limit`. Three knobs and one relationship govern how good the results are and how long they take:
 
 - **Pool size** — `fetchLimit = min(max(limit × overfetch, candidateFloor), 200)`. `candidateFloor` (default `80`) guarantees the reranker a large enough menu even at the default `limit = 5`; without it a small `limit` starves the reranker (only `5 × 5 = 25` candidates) and its best matches never enter the window.
-- **Threshold ↔ window** — raising `search.similarityThreshold` lets *more* chunks under the bar, so the pool must be wide enough to reach them; a strict threshold with a small pool silently truncates recall. Widen `candidateFloor`/`overfetch` when you raise the threshold.
+- **Threshold ↔ window** — distance scales differ per embedding model, so an unset `search.similarityThreshold` follows the model. Raising the threshold lets *more* chunks under the bar, so the pool must be wide enough to reach them; when more chunks are under the threshold than the window takes, recall is silently truncated. Widen `candidateFloor`/`overfetch` when you raise the threshold.
 - **Latency** — the reranker cost grows with pool size (on CPU, tens of seconds; a rough guide is a large fixed cost plus a per-candidate increment). Bigger pool = better recall, slower query. GPU/fast hosts can raise `candidateFloor`; ultra-constrained hosts lower it.
 
+The pool is reachable on large projects too. The HNSW index scan stops after `hnsw.ef_search` rows (PostgreSQL default 40) and only then applies the `project` filter and the threshold, so a scoped search on a project of a few thousand chunks or more (measured from ~5.8 k; the crossover depends on table statistics) — or an unscoped one — used to get at most 40 candidates, often far fewer. Each search now sets `hnsw.ef_search` to the requested row count (at least 40, at most 1000) and, on pgvector ≥ 0.8, `hnsw.iterative_scan = relaxed_order` for its own query, so `candidateFloor` / `overfetch` size the pool the reranker actually receives, unless the iterative scan stops at `hnsw.max_scan_tuples` (20 000) first. On an older pgvector only `ef_search` is raised, and one `warn` line per process names the version — or `unknown` if the first version read failed, with no later line naming it. Like the Voyage warning above, it is visible only at `logging.level` `warn` or lower.
+
 To size these for **your** hardware, turn on telemetry:
 
 ```bash
-rag-config set logging.searchMetrics true
+rag-config set logging.level info
 ```
 
-Each search then writes one `info` line (independent of `logging.level`) with, among others: `fetchLimit`, `candidatesReturned`, `poolSaturated`, `maxCosineRankSurvived`, `distinctFilesInResult`, `topFileShare`, and `embedMs`/`rerankMs`/`dbMs`/`totalMs`. Read them as:
+Each search then writes one `search metrics` line with, among others: `fetchLimit`, `candidatesReturned`, `poolSaturated`, `maxCosineRankSurvived`, `distinctFilesInResult`, `topFileShare`, `efSearch`/`iterativeScan` (the HNSW settings sent with the query), and `embedMs`/`rerankMs`/`dbMs`/`totalMs`. Read them as:
 
-- **`poolSaturated: true`** — more chunks were under the threshold than the window took → recall is being truncated; raise `candidateFloor`/`overfetch`.
+- **`poolSaturated: true`** — more chunks were under the threshold than the window took → recall is being truncated; raise `candidateFloor`/`overfetch`. Under the `1.0` fallback (a model with no recommended value) nearly every chunk is under the threshold, so in a scope holding more chunks than the window this stays true at any pool size, and every search that reranks sends the full pool to the reranker; set `search.similarityThreshold` instead of widening the pool.
 - **`maxCosineRankSurvived`** — the deepest cosine rank that survived reranking. If it stays well below `fetchLimit`, the pool is bigger than needed → shrink it to save latency; if it approaches `fetchLimit`, widen.
 
 ## Index consistency
@@ -349,13 +383,13 @@ A failure pruning one project does not block the others or stop indexing of the
 
 ## Architecture
 
-**Stack:** TypeScript on Node.js 18+ · PostgreSQL 17 + pgvector (HNSW, cosine distance) via Drizzle ORM · ts-morph for AST/symbol/call-graph extraction · `@langchain/textsplitters` for chunk fallback · MCP SDK over stdio · Zod v4 for config validation and JSON-Schema generation · pino + pino-roll for logging · plain `node:http` dashboard with vis-network · Vitest · Docker Compose for Postgres + Infinity.
+**Stack:** TypeScript on Node.js 22.13+ · PostgreSQL 17 + pgvector (HNSW, cosine distance) via Drizzle ORM · ts-morph for AST/symbol/call-graph extraction · `@langchain/textsplitters` for chunk fallback · MCP SDK over stdio · Zod v4 for config validation and JSON-Schema generation · pino + pino-roll for logging · plain `node:http` dashboard with vis-network · Vitest · Docker Compose for Postgres + Infinity.
 
 **Design:**
 - **Composition root + manual DI** — `src/container.ts` builds every service once and wires it through constructors; no module-level singletons, no DI framework.
-- **Dependency inversion** — services depend on interfaces (`IEmbedder`, `IDatabase`, `IAstParser`, `IChunker`, `ISearcher`, `IProjectDiscovery`, `IMonorepoResolver`, `IMcpToolHandler`), so providers (OpenAI-compatible/Voyage/Infinity — Ollama via `openai-compatible`), chunking strategy (`ast`/`character`), and monorepo resolvers are swappable.
+- **Dependency inversion** — services depend on interfaces (`IEmbedder`, `IDatabase`, `IAstParser`, `IChunker`, the role interfaces of the search and path parts (`IChunkSearch`, `IToolPaths`, `ISymbolLookup`, …), `IProjectDiscovery`, `IMonorepoResolver`, `IMcpToolHandler`), so providers (OpenAI-compatible/Voyage/Infinity — Ollama via `openai-compatible`), chunking strategy (`ast`/`character`), and monorepo resolvers are swappable.
 - **Command pattern** — each CLI mode (`rag-index`, `rag-mcp`, `rag-config`, `rag-web`) is its own `ICommand`; `app.ts` only dispatches.
-- **Registry / Open-Closed** — MCP tools are `IMcpToolHandler` implementations registered in a `Map`; adding a tool never touches `McpServer`.
+- **Registry / Open-Closed** — MCP tools extend `McpTool`, which implements `IMcpToolHandler`, and are registered in a `Map` by `McpServer.createTools()`; adding a tool means extending `McpTool` and registering it there, and the dispatch logic never changes.
 - **Fallback chains** — vector dimension: config override → model registry → runtime probe; `find_symbol`/`get_dependents`: indexed table → grep; failed rerank → vector order.
 - **Incremental indexing** — mtime fast path, SHA-256 fallback for clones/transfers, AST-aligned chunk boundaries so declarations aren't split arbitrarily.
 - **Index/model consistency guard** — `index_meta` tracks the embedding model that built the index; search refuses with a clear re-index message on mismatch instead of returning noise.
@@ -364,4 +398,6 @@ Full internals (per-file responsibilities, every pattern with file:line referenc
 
 ## License
 
-MIT
+Copyright (C) 2026 Oleksandr Antoniuk.
+
+Licensed under the [GNU Affero General Public License v3.0 only](LICENSE) (`AGPL-3.0-only`). Versions up to and including `0.3.0-alpha` were released under the MIT License and remain available under it.

package/dist/app.js

@@ -37,6 +37,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const help_1 = require("./src/help");
+const index_args_1 = require("./src/index-args");
 const container_1 = require("./src/container");
 const config_1 = require("./src/config");
 const config_store_1 = require("./src/config-store");
@@ -46,20 +47,13 @@ const McpCommand_1 = require("./src/commands/McpCommand");
 const ConfigCommand_1 = require("./src/commands/ConfigCommand");
 const WebCommand_1 = require("./src/commands/WebCommand");
 const setup_1 = require("./src/setup");
-/**
- * Load `~/.config/codesearch-mcp/.env` into `process.env` before config is read.
- * All five binaries share this file — `rag-mcp` in particular is spawned by the
- * MCP client and does not inherit shell exports. A real `process.env` value
- * always wins over the file. Minimal `KEY=VALUE` parser (no `dotenv` dep):
- * skips blanks and `#` comments, strips one layer of surrounding quotes.
- */
 function loadDotEnv(file) {
     let text;
     try {
         text = fs.readFileSync(file, 'utf-8');
     }
     catch {
-        return; // absent / unreadable → no-op
+        return;
     }
     for (const rawLine of text.split(/\r?\n/)) {
         const line = rawLine.trim();
@@ -76,7 +70,7 @@ function loadDotEnv(file) {
             val = val.slice(1, -1);
         }
         if (!(key in process.env))
-            process.env[key] = val; // real env wins
+            process.env[key] = val;
     }
 }
 async function main() {
@@ -88,8 +82,6 @@ async function main() {
     const isConfig = argv1 === 'rag-config' || process.argv[2] === 'config' || process.argv[2] === 'rag-config';
     const isWeb = argv1 === 'rag-web' || process.argv[2] === 'web' || process.argv[2] === 'rag-web';
     const isBinary = ['rag-index', 'rag-mcp', 'rag-setup', 'rag-config', 'rag-web'].includes(argv1);
-    // `rag-index eval` — a sub-mode of index, not its own binary, so it sits one
-    // token deeper than the other modes (`rag-index eval` / `index eval`).
     const evalSubArg = isBinary ? process.argv[2] : process.argv[3];
     const isEval = isIndex && evalSubArg === 'eval';
     const mode = isEval ? 'eval' : isIndex ? 'index' : isMcp ? 'mcp' : isSetup ? 'setup' : isConfig ? 'config' : isWeb ? 'web' : (process.argv[2] ?? '');
@@ -99,7 +91,6 @@ async function main() {
         process.exit(0);
     }
     const effectiveArgs = process.argv.slice(isEval ? (isBinary ? 3 : 4) : (isBinary ? 2 : 3));
-    // Arg validation
     if (mode === 'eval') {
         const valueFlags = new Set(['--suite', '--baseline', '--project']);
         const unknown = [];
@@ -108,7 +99,7 @@ async function main() {
             if (valueFlags.has(a)) {
                 const next = effectiveArgs[i + 1];
                 if (next !== undefined && !next.startsWith('-'))
-                    i++; // consume the value
+                    i++;
                 continue;
             }
             unknown.push(a);
@@ -120,25 +111,17 @@ async function main() {
         }
     }
     else if (mode === 'index') {
-        const boolFlags = new Set(['--reindex', '--select']);
-        const unknown = [];
-        for (let i = 0; i < effectiveArgs.length; i++) {
-            const a = effectiveArgs[i];
-            if (boolFlags.has(a))
-                continue;
-            if (a === '--project') {
-                const next = effectiveArgs[i + 1];
-                if (next !== undefined && !next.startsWith('-'))
-                    i++; // consume the name
-                continue;
-            }
-            unknown.push(a);
-        }
-        if (unknown.length > 0) {
-            console.error(`Unexpected argument: ${unknown[0]}\n`);
+        const unexpected = (0, index_args_1.findUnexpectedIndexArg)(effectiveArgs);
+        if (unexpected !== undefined) {
+            console.error(`Unexpected argument: ${unexpected}\n`);
             (0, help_1.printHelp)(isBinary ? argv1 : 'rag-index');
             process.exit(1);
         }
+        const cwdCause = (0, index_args_1.unreadableCwdCause)(effectiveArgs);
+        if (cwdCause !== undefined) {
+            console.error(`\n${cwdCause}`);
+            process.exit(1);
+        }
     }
     else if (mode === 'mcp' || mode === 'setup') {
         if (effectiveArgs.length > 0) {
@@ -158,7 +141,7 @@ async function main() {
                     process.exit(1);
                 }
                 i++;
-                continue; // skip its (validated) value
+                continue;
             }
             console.error(`Unexpected argument: ${effectiveArgs[i]}\n`);
             (0, help_1.printHelp)(isBinary ? argv1 : 'rag-web');
@@ -173,7 +156,6 @@ async function main() {
         await new ConfigCommand_1.ConfigCommand(effectiveArgs).execute();
         process.exit(0);
     }
-    // All other modes require a valid config.json
     const loggerName = mode === 'index' || mode === 'eval' ? 'indexer' : mode === 'mcp' ? 'mcp' : mode === 'web' ? 'web' : undefined;
     let container;
     try {
@@ -193,14 +175,11 @@ async function main() {
         console.error(`workspaceRoot is not configured. ${hint}`);
         process.exit(1);
     }
-    // Construct only the selected command — building every command eagerly would
-    // run each constructor's arg parsing (e.g. WebCommand's --port) for modes that
-    // never use it.
     const factories = {
-        index: () => new IndexCommand_1.IndexCommand(container, argv1),
-        eval: () => new EvalCommand_1.EvalCommand(container, argv1),
-        mcp: () => new McpCommand_1.McpCommand(container),
-        web: () => new WebCommand_1.WebCommand(container, effectiveArgs),
+        index: () => new IndexCommand_1.IndexCommand(container.db, container.embedder, container.indexer, container.search.dependencies, container.discovery, container.config, argv1),
+        eval: () => new EvalCommand_1.EvalCommand(container.db, container.search.chunks, container.search.catalog, container.config, argv1),
+        mcp: () => new McpCommand_1.McpCommand(container.readiness, container.mcp, container.logger),
+        web: () => new WebCommand_1.WebCommand(container.db, container.embedder, container.search.catalog, container.search.dependencies, container.config, container.logger, effectiveArgs),
     };
     const factory = factories[mode];
     if (!factory) {

package/dist/src/ast/CallExtractor.d.ts

@@ -0,0 +1,8 @@
+import { type SourceFile } from 'ts-morph';
+import type { CallEdge } from '../interfaces/IAstParser';
+import type { IIndexedNodeResolver } from '../interfaces';
+export declare class CallExtractor {
+    private readonly resolver;
+    constructor(resolver: IIndexedNodeResolver);
+    extractCalls(sourceFile: SourceFile, filePath: string, serviceName: string): CallEdge[];
+}

package/dist/src/ast/CallExtractor.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallExtractor = void 0;
+const ts_morph_1 = require("ts-morph");
+class CallExtractor {
+    resolver;
+    constructor(resolver) {
+        this.resolver = resolver;
+    }
+    extractCalls(sourceFile, filePath, serviceName) {
+        const calls = [];
+        for (const callExpr of sourceFile.getDescendantsOfKind(ts_morph_1.SyntaxKind.CallExpression)) {
+            const expr = callExpr.getExpression();
+            let calleeName = null;
+            let calleeFile = null;
+            let calleeDecl;
+            try {
+                if (ts_morph_1.Node.isPropertyAccessExpression(expr)) {
+                    calleeName = expr.getName();
+                    const sym = expr.getNameNode().getSymbol();
+                    const decl = sym?.getDeclarations()?.[0];
+                    const declPath = decl?.getSourceFile().getFilePath();
+                    if (declPath && !declPath.includes('/node_modules/')) {
+                        calleeFile = declPath;
+                        calleeDecl = decl;
+                    }
+                }
+                else if (ts_morph_1.Node.isIdentifier(expr)) {
+                    calleeName = expr.getText();
+                    const sym = expr.getSymbol();
+                    if (sym) {
+                        const firstDecl = sym.getDeclarations()?.[0];
+                        const resolved = firstDecl && ts_morph_1.Node.isImportSpecifier(firstDecl)
+                            ? (sym.getAliasedSymbol() ?? sym)
+                            : sym;
+                        const decl = resolved.getDeclarations()?.[0];
+                        const declPath = decl?.getSourceFile().getFilePath();
+                        if (declPath && !declPath.includes('/node_modules/')) {
+                            calleeFile = declPath;
+                            calleeDecl = decl;
+                        }
+                    }
+                }
+            }
+            catch {
+            }
+            if (!calleeName || !calleeFile)
+                continue;
+            const described = calleeDecl ? this.resolver.describeIndexedNode(calleeDecl) : null;
+            const calleeSymbol = described ? this.resolver.qualifiedName(described) : null;
+            const fromSymbol = this.resolver.findFromSymbol(callExpr);
+            const pos = sourceFile.compilerNode
+                .getLineAndCharacterOfPosition(callExpr.getStart());
+            calls.push({
+                project: serviceName,
+                fromFile: filePath,
+                fromSymbol,
+                calleeName,
+                calleeFile,
+                calleeSymbol,
+                line: pos.line + 1,
+                col: pos.character + 1,
+            });
+        }
+        return calls;
+    }
+}
+exports.CallExtractor = CallExtractor;

package/dist/src/ast/GraphqlNameExtractor.d.ts

@@ -0,0 +1,22 @@
+import { type SourceFile } from 'ts-morph';
+import type { SymbolEntry } from '../interfaces/IAstParser';
+import type { ILogger, IIndexedNodeResolver } from '../interfaces';
+import type { DeclarationCandidate } from '../declarations/DeclarationTreeBuilder';
+import { type ResolveDeclaration } from './node-helpers';
+export declare class GraphqlNameExtractor {
+    private readonly resolver;
+    private readonly logger;
+    private readonly resolveDeclaration;
+    constructor(resolver: IIndexedNodeResolver, logger: ILogger, resolveDeclaration?: ResolveDeclaration);
+    private buildGraphqlImportMap;
+    private recognizedDecorator;
+    private deriveGraphqlName;
+    private logGraphqlSkip;
+    private declarationNameFor;
+    private classGraphqlTypeName;
+    private resolveResolverParentType;
+    private extractClassTypeRows;
+    private extractResolveFieldRow;
+    private extractMethodOperationRows;
+    extractGraphqlNames(sourceFile: SourceFile, filePath: string, serviceName: string, ownRows: DeclarationCandidate[]): SymbolEntry[];
+}