From 42fc1df1007e87c517e1fd0def1a0d0ffd035d67 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Patrick=20Rossell=C3=B3=20Colom?=
 <74001504+PatrickSys@users.noreply.github.com>
Date: Tue, 6 Oct 2026 16:04:54 +0200
Subject: [PATCH 1/6] docs: align 2.4.0 release guidance

---
 README.md              | 36 ++++++++++++++-----------
 docs/capabilities.md   | 21 ++++++++-------
 docs/cli.md            | 50 +++++++++++++++++------------------
 docs/client-setup.md   | 60 +++++++++++++++++++++---------------------
 docs/demo.md           | 12 ++++-----
 docs/review-context.md |  4 +--
 6 files changed, 94 insertions(+), 89 deletions(-)

diff --git a/README.md b/README.md
index 6249c02..2e86d5d 100644
--- a/README.md
+++ b/README.md
@@ -10,31 +10,31 @@ Codebase Context gives an agent a local view of that information through code se
 
 ## Set up your AI client
 
-Choose your coding tool and run its command once. Use Node.js 22 or newer. These commands use published npm `2.2.0` and do not require a project folder in your configuration:
+Choose your coding tool and run its command once. Use Node.js 22 or newer. These commands use published npm `2.4.0` and do not require a project folder in your configuration:
 
 ```bash
 # Claude Code
-claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.2.0
+claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.4.0
 
 # Codex CLI
-codex mcp add codebase-context -- npx -y codebase-context@2.2.0
+codex mcp add codebase-context -- npx -y codebase-context@2.4.0
 
 # OpenCode 1.x (keep the quoted separator on Windows)
-opencode mcp add codebase-context '--' npx -y codebase-context@2.2.0
+opencode mcp add codebase-context '--' npx -y codebase-context@2.4.0
 ```
 
 Start a new agent session in your project, then ask:
 
 > Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project when checking get_indexing_status and searching. Wait for indexing if needed, read codebase://context, then search_codebase and open a returned source file. Show me the relevant files.
 
-Replace `[feature]` with something you want to find. The agent supplies the repository path in its tool calls, so the registration can serve different projects. Initial indexing may need a local model download. The October 6 isolated checks proved these client registrations and published-package project selection/search; they did not establish a full native agent investigation.
+Replace `[feature]` with something you want to find. The agent supplies the repository path in its tool calls, so the registration can serve different projects. Initial indexing may need a local model download. The October 6 isolated checks exercised published `2.2.0` client registrations and project selection/search. They did not verify `2.4.0` or establish a full native agent investigation.
 
 For Codex Desktop, create or merge `.codex/config.toml` in the project you want to search:
 
 ```toml
 [mcp_servers.codebase-context]
 command = "npx"
-args = ["-y", "codebase-context@2.2.0"]
+args = ["-y", "codebase-context@2.4.0"]
 startup_timeout_sec = 120
 ```
 
@@ -44,13 +44,13 @@ Other clients use their own setup commands:
 
 | Client                      | Shortest current setup                                                       |
 | --------------------------- | ---------------------------------------------------------------------------- |
-| Gemini CLI                  | `gemini mcp add --scope user codebase-context npx -y codebase-context@2.2.0` |
+| Gemini CLI                  | `gemini mcp add --scope user codebase-context npx -y codebase-context@2.4.0` |
 | Cursor                      | Add `.cursor/mcp.json`                                                       |
 | VS Code with GitHub Copilot | Add `.vscode/mcp.json`                                                       |
-| GitHub Copilot CLI          | `copilot mcp add codebase-context -- npx -y codebase-context@2.2.0` |
+| GitHub Copilot CLI          | `copilot mcp add codebase-context -- npx -y codebase-context@2.4.0` |
 | Windsurf                    | Add `~/.codeium/windsurf/mcp_config.json`                                    |
 
-Check an existing same-name entry before replacing it. To give the server a default folder, append that folder's absolute path to the `npx` arguments. The [client setup guide](./docs/client-setup.md) covers scopes, optional fixed-folder configuration, verification limits and the unreleased installer. Published `2.2.0`'s interactive `init` has registration bugs; use the commands above.
+Check an existing same-name entry before replacing it. To give the server a default folder, append that folder's absolute path to the `npx` arguments. The [client setup guide](./docs/client-setup.md) covers scopes, optional fixed-folder configuration, the `2.4.0` project installer and its verification limits. The registration bugs found in `2.2.0` are historical.
 
 The [client setup guide](./docs/client-setup.md) has the exact commands and config for every client, plus what was checked locally and what still relies on official instructions.
 
@@ -64,12 +64,16 @@ The default connection is `stdio` (standard input/output): your client starts th
 
 ### Team patterns and examples
 
-`get_team_patterns` shows the approaches used in the repository and points to representative files. Published `2.2.0` includes dedicated analyzers for Angular, React and Next.js, with a generic analyzer for other stacks. NestJS support belongs to the newer source candidate.
+`get_team_patterns` shows the approaches used in the repository and points to representative files. Published `2.4.0` includes dedicated analyzers for Angular, React, Next.js and NestJS, with a generic analyzer for other stacks.
 
 ### Project memory
 
 `remember` stores a convention, decision, gotcha, or past failure for the project. `get_memory` retrieves relevant entries in later sessions, including when the agent or editor changes.
 
+### Review context
+
+The `codebase-context-review` CLI creates a bounded context packet from a committed Git diff. It gives a reviewer context; it does not review code or prove review quality. See the [review-context guide](./docs/review-context.md).
+
 ## How it works
 
 1. **Index locally.** Codebase Context scans the project, builds a keyword index, and creates local semantic embeddings - numeric representations used to match code by meaning as well as exact words.
@@ -80,16 +84,16 @@ The same information is available from the terminal. Run these commands from you
 
 ```bash
 # Build or refresh the local index
-npx -y codebase-context@2.2.0 reindex
+npx -y codebase-context@2.4.0 reindex
 
 # Repository structure, patterns, and representative files
-npx -y codebase-context@2.2.0 map
+npx -y codebase-context@2.4.0 map
 
 # Ranked code search
-npx -y codebase-context@2.2.0 search --query "auth middleware"
+npx -y codebase-context@2.4.0 search --query "auth middleware"
 
 # Current team patterns
-npx -y codebase-context@2.2.0 patterns
+npx -y codebase-context@2.4.0 patterns
 ```
 
 One stdio server can route across several repositories. Supply `project` in tool calls to select the intended repository; a successful selection becomes the default for later calls in that process. Some clients also announce workspace roots: one root can auto-select, while an ambiguous selection asks for a project instead of guessing. MCP deprecated Roots in its July 2026 revision, so explicit project selection is the documented default rather than a dependency on client discovery.
@@ -145,8 +149,8 @@ The method and failures are documented so the measurements can be inspected with
 - Retrieval measurements describe expected-file coverage, file precision, and reported `peakPrivateGb`, not patch correctness or end-to-end coding quality.
 - The paired token observation covers two frozen investigation tasks and records observed agent behavior; it is not a universal token or time guarantee.
 - Setup checks differ by client. The detailed guide distinguishes a written config, a config recognized by the client, a local connection, and instructions checked only against official docs.
-- Published `2.2.0` has dedicated Angular, React and Next.js analyzers; NestJS support is in the newer source candidate. Other projects use the generic analyzer and the language parsers available for that stack.
-- The default searchable-chunk limit is 5,000 per project. Larger repositories can raise it in `.codebase-context/config.json`.
+- Published `2.4.0` has dedicated Angular, React, Next.js and NestJS analyzers. Other projects use the generic analyzer and the language parsers available for that stack.
+- The default searchable-chunk limit is 5,000 per project. In `~/.codebase-context/config.json`, set `projects[].parsing.maxChunks` for a project that needs a higher limit.
 - The agent must identify its repository in tool calls when no default or unambiguous client root is available. Concurrent HTTP client isolation is not established by the stdio routing checks.
 
 ## Reference
diff --git a/docs/capabilities.md b/docs/capabilities.md
index 748d5a1..536c736 100644
--- a/docs/capabilities.md
+++ b/docs/capabilities.md
@@ -8,8 +8,8 @@ The server supports two transport modes:
 
 | Mode                | Command                                           | MCP endpoint                 |
 | ------------------- | ------------------------------------------------- | ---------------------------- |
-| **stdio** (default) | `npx -y codebase-context@2.2.0`                   | Spawned process stdin/stdout |
-| **HTTP**            | `npx -y codebase-context@2.2.0 --http [--port N]` | `http://127.0.0.1:3100/mcp`  |
+| **stdio** (default) | `npx -y codebase-context@2.4.0`                   | Spawned process stdin/stdout |
+| **HTTP**            | `npx -y codebase-context@2.4.0 --http [--port N]` | `http://127.0.0.1:3100/mcp`  |
 
 HTTP defaults to `127.0.0.1:3100`. Override with `--port`, `CODEBASE_CONTEXT_PORT`, or `server.port` in `~/.codebase-context/config.json`.
 
@@ -20,13 +20,14 @@ Per-project config overrides supported today:
 - `projects[].excludePatterns`: merged with the built-in exclusion set for that project at index time
 - `projects[].analyzerHints.analyzer`: prefers a registered analyzer by name for that project and falls back safely when the name is missing or invalid
 - `projects[].analyzerHints.extensions`: adds project-local source extensions for indexing and auto-refresh watching without changing defaults for other projects
+- `projects[].parsing.maxChunks`: sets the maximum number of searchable chunks indexed for that project
 
 Copy-pasteable client config templates are shipped in the package:
 
 - `templates/mcp/stdio/.mcp.json` — stdio setup for `.mcp.json`-style clients
 - `templates/mcp/http/.mcp.json` — HTTP setup for `.mcp.json`-style clients
 
-Use Node.js 22 or newer with the published 2.2.0 commands shown here. For client registration recipes and their verification limits, see the [client setup guide](./client-setup.md).
+Use Node.js 22 or newer with the published 2.4.0 commands shown here. For client registration recipes and their verification limits, see the [client setup guide](./client-setup.md).
 
 ## CLI Reference
 
@@ -49,15 +50,15 @@ For a command gallery with examples, see `docs/cli.md`.
 | `memory add`           | `--type`, `--category`, `--memory`, `--reason`                                                             | `remember`                             |
 | `memory remove <id>`   | —                                                                                                          | —                                      |
 
-Commands that list `--json` above support raw JSON output. For MCP client registration, follow the [published client setup recipes](./client-setup.md); do not use the broken `init` setup command in published 2.2.0. Errors go to stderr with exit code 1.
+Commands that list `--json` above support raw JSON output. For MCP client registration, follow the [published client setup recipes](./client-setup.md). The registration failures documented for `init` apply to published 2.2.0; see that guide for current 2.4.0 setup instructions. Errors go to stderr with exit code 1.
 
 ```bash
 # Quick examples
-npx -y codebase-context@2.2.0 status
-npx -y codebase-context@2.2.0 search --query "auth middleware" --intent edit
-npx -y codebase-context@2.2.0 refs --symbol "UserService" --limit 10
-npx -y codebase-context@2.2.0 cycles --scope src/features
-npx -y codebase-context@2.2.0 reindex --incremental
+npx -y codebase-context@2.4.0 status
+npx -y codebase-context@2.4.0 search --query "auth middleware" --intent edit
+npx -y codebase-context@2.4.0 refs --symbol "UserService" --limit 10
+npx -y codebase-context@2.4.0 cycles --scope src/features
+npx -y codebase-context@2.4.0 reindex --incremental
 ```
 
 ## Tool Surface
@@ -301,6 +302,6 @@ Reproducible evaluation is shipped as a CLI entrypoint backed by shared scoring
 
 - **Symbol refs are not a call-graph.** `get_symbol_references` counts identifier-node occurrences in the AST (comments/strings excluded via Tree-sitter). It does not distinguish call sites from type annotations, variable assignments, or imports. Full call-site-specific analysis (`call_expression` nodes only) is a roadmap item.
 - **Impact is 2-hop max.** `computeImpactCandidates` walks direct importers then their importers. Full BFS reachability is on the roadmap.
-- **Published 2.2.0 has dedicated Angular, React, and Next.js analyzers.** NestJS support is in a newer source candidate and is not part of published 2.2.0. Other languages use the Generic analyzer (30+ languages, chunking + import graph, no framework-specific signal extraction).
+- **Published 2.4.0 has dedicated Angular, React, Next.js and NestJS analyzers.** Other languages use the Generic analyzer (30+ languages, chunking + import graph, no framework-specific signal extraction).
 - **Default embedding model is `bge-small-en-v1.5` (512-token context).** Granite (8192 context) is opt-in via `EMBEDDING_MODEL`. OpenAI is opt-in via `EMBEDDING_PROVIDER=openai` — sends code externally.
 - **Patterns are file-level frequency counts.** Not semantic clustering. Rising/Declining trend is derived from git commit recency for files using each pattern, not from usage semantics.
diff --git a/docs/cli.md b/docs/cli.md
index dfda760..d9dc407 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -10,18 +10,18 @@
 
 > Output depends on the repo you run it against. The examples below are illustrative (paths, counts, and detected frameworks will vary).
 >
-> These examples show an earlier CLI run; they do not verify the current package or an MCP connection.
+> These output examples come from an earlier CLI run; they were not captured from published `2.4.0` and do not verify an MCP connection.
 >
-> The commands below use published `codebase-context@2.2.0` and require Node.js 22 or newer. The CLI is intentionally single-project per invocation and targets one root via `CODEBASE_ROOT` or the current working directory. MCP registration and project selection are covered in the [client setup guide](./client-setup.md).
+> The commands below use published `codebase-context@2.4.0` and require Node.js 22 or newer. The CLI is intentionally single-project per invocation and targets one root via `CODEBASE_ROOT` or the current working directory. MCP registration and project selection are covered in the [client setup guide](./client-setup.md).
 
 ## How to run
 
 ```bash
 # CLI only: run from a repo root, or set CODEBASE_ROOT explicitly:
-CODEBASE_ROOT=/path/to/repo npx -y codebase-context@2.2.0 status
+CODEBASE_ROOT=/path/to/repo npx -y codebase-context@2.4.0 status
 
 # Commands that show --json in their help support machine output. Human mode is default.
-npx -y codebase-context@2.2.0 patterns --json
+npx -y codebase-context@2.4.0 patterns --json
 ```
 
 ### ASCII fallback
@@ -29,7 +29,7 @@ npx -y codebase-context@2.2.0 patterns --json
 If your terminal doesn’t render Unicode box-drawing cleanly:
 
 ```bash
-CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context@2.2.0 patterns
+CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context@2.4.0 patterns
 ```
 
 ## Commands
@@ -44,7 +44,7 @@ CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context@2.2.0 patterns
 - `reindex` — rebuild index (full or incremental)
 - `style-guide` — find style guide sections in docs
 - `memory list|add|remove` — manage team memory (stored in `.codebase-context/memory.json`)
-- MCP client registration — use the published 2.2.0 commands in the [client setup guide](./client-setup.md); published `init` is not a reliable setup route
+- MCP client registration — use the published 2.4.0 recipes in the [client setup guide](./client-setup.md); the setup failures documented for `init` apply to 2.2.0
 
 ---
 
@@ -53,9 +53,9 @@ CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context@2.2.0 patterns
 Run these CLI commands from the project root. Build or refresh the local index first; the first index may take a while while the project is scanned and local embeddings are created. Then inspect the conventions map and search for the code you need:
 
 ```bash
-npx -y codebase-context@2.2.0 reindex
-npx -y codebase-context@2.2.0 map
-npx -y codebase-context@2.2.0 search --query "auth middleware"
+npx -y codebase-context@2.4.0 reindex
+npx -y codebase-context@2.4.0 map
+npx -y codebase-context@2.4.0 search --query "auth middleware"
 ```
 
 This is the CLI preparation flow. It is separate from MCP client registration and does not by itself show that an MCP client connected successfully.
@@ -63,8 +63,8 @@ This is the CLI preparation flow. It is separate from MCP client registration an
 ## `map`
 
 ```bash
-npx -y codebase-context@2.2.0 reindex
-npx -y codebase-context@2.2.0 map
+npx -y codebase-context@2.4.0 reindex
+npx -y codebase-context@2.4.0 map
 ```
 
 The conventions map - run this first on an unfamiliar repo. It shows architecture layers, active patterns with adoption rates and trend direction, and the golden files the team treats as the strongest examples. This is also what the MCP server delivers to AI agents via the `codebase://context` resource on first call, before search narrows to a specific local example.
@@ -99,7 +99,7 @@ Example output (truncated):
 ## `metadata`
 
 ```bash
-npx -y codebase-context@2.2.0 metadata
+npx -y codebase-context@2.4.0 metadata
 ```
 
 Example output:
@@ -120,7 +120,7 @@ Example output:
 ## `patterns`
 
 ```bash
-npx -y codebase-context@2.2.0 patterns
+npx -y codebase-context@2.4.0 patterns
 ```
 
 Example output (truncated):
@@ -142,8 +142,8 @@ Example output (truncated):
 ## `search`
 
 ```bash
-npx -y codebase-context@2.2.0 reindex
-npx -y codebase-context@2.2.0 search --query "file watcher" --intent edit --limit 3
+npx -y codebase-context@2.4.0 reindex
+npx -y codebase-context@2.4.0 search --query "file watcher" --intent edit --limit 3
 ```
 
 Example output (truncated):
@@ -164,7 +164,7 @@ Example output (truncated):
 ## `refs`
 
 ```bash
-npx -y codebase-context@2.2.0 refs --symbol "startFileWatcher" --limit 10
+npx -y codebase-context@2.4.0 refs --symbol "startFileWatcher" --limit 10
 ```
 
 Example output (truncated):
@@ -183,7 +183,7 @@ Example output (truncated):
 ## `cycles`
 
 ```bash
-npx -y codebase-context@2.2.0 cycles --scope src
+npx -y codebase-context@2.4.0 cycles --scope src
 ```
 
 Example output:
@@ -199,7 +199,7 @@ Example output:
 ## `status`
 
 ```bash
-npx -y codebase-context@2.2.0 status
+npx -y codebase-context@2.4.0 status
 ```
 
 Example output:
@@ -218,8 +218,8 @@ Example output:
 ## `reindex`
 
 ```bash
-npx -y codebase-context@2.2.0 reindex
-npx -y codebase-context@2.2.0 reindex --incremental --reason "changed watcher logic"
+npx -y codebase-context@2.4.0 reindex
+npx -y codebase-context@2.4.0 reindex --incremental --reason "changed watcher logic"
 ```
 
 > **MCP server mode**: if you're running codebase-context as an MCP server (long-running process), the index auto-refreshes via a file watcher — you don't need to call `reindex` between edits. Use `reindex` for one-shot CLI runs or to force a full rebuild.
@@ -227,7 +227,7 @@ npx -y codebase-context@2.2.0 reindex --incremental --reason "changed watcher lo
 ## `style-guide`
 
 ```bash
-npx -y codebase-context@2.2.0 style-guide --query "naming"
+npx -y codebase-context@2.4.0 style-guide --query "naming"
 ```
 
 Example output:
@@ -240,14 +240,14 @@ No style guides found.
 ## `memory`
 
 ```bash
-npx -y codebase-context@2.2.0 memory list
-npx -y codebase-context@2.2.0 memory list --query "watcher"
+npx -y codebase-context@2.4.0 memory list
+npx -y codebase-context@2.4.0 memory list --query "watcher"
 
-npx -y codebase-context@2.2.0 memory add \
+npx -y codebase-context@2.4.0 memory add \
   --type gotcha \
   --category tooling \
   --memory "Use pnpm, not npm" \
   --reason "Workspace support and speed"
 
-npx -y codebase-context@2.2.0 memory remove <id>
+npx -y codebase-context@2.4.0 memory remove <id>
 ```
diff --git a/docs/client-setup.md b/docs/client-setup.md
index 7770e7f..384cef0 100644
--- a/docs/client-setup.md
+++ b/docs/client-setup.md
@@ -1,6 +1,6 @@
 # Client Setup
 
-Codebase Context runs as a local MCP server: a tool your AI editor or command-line client can call while it works. Register it without a fixed folder, then let the agent supply its current repository through the `project` tool parameter. These examples use published npm `2.2.0`.
+Codebase Context runs as a local MCP server: a tool your AI editor or command-line client can call while it works. Register it without a fixed folder, then let the agent supply its current repository through the `project` tool parameter. These recipes target published npm `2.4.0`.
 
 Use Node.js 22 or newer for these recipes. The package declares Node 18+, but native dependency requirements are narrower than that broad declaration; these checks do not establish Node 18.0 compatibility.
 
@@ -25,7 +25,7 @@ After registration, start a new agent session in your project and ask:
 
 > Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project when checking get_indexing_status and searching. Wait for indexing if needed, read codebase://context, then search_codebase and open a returned source file. Show me the relevant files.
 
-The first index may take a while and download a local model. You can prepare it separately with `npx -y codebase-context@2.2.0 reindex` from the project folder. Index readiness, client connection and useful agent behavior are separate checks.
+The first index may take a while and download a local model. You can prepare it separately with `npx -y codebase-context@2.4.0 reindex` from the project folder. Index readiness, client connection and useful agent behavior are separate checks.
 
 ## Claude Code
 
@@ -38,13 +38,13 @@ The first index may take a while and download a local model. You can prepare it
 User setup:
 
 ```bash
-claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.2.0
+claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.4.0
 ```
 
 Optional shared project setup:
 
 ```bash
-claude mcp add --scope project --transport stdio codebase-context -- npx -y codebase-context@2.2.0
+claude mcp add --scope project --transport stdio codebase-context -- npx -y codebase-context@2.4.0
 ```
 
 `--scope project` writes shared `.mcp.json` and requires project-server approval. `--scope local` instead stores a private association for the current project in `~/.claude.json`; it does not write `.mcp.json`.
@@ -64,7 +64,7 @@ claude mcp add --scope project --transport stdio codebase-context -- npx -y code
 **Scope:** The command writes user config. A trusted project can use a project `.codex/config.toml` instead.
 
 ```bash
-codex mcp add codebase-context -- npx -y codebase-context@2.2.0
+codex mcp add codebase-context -- npx -y codebase-context@2.4.0
 ```
 
 Equivalent project config:
@@ -72,7 +72,7 @@ Equivalent project config:
 ```toml
 [mcp_servers.codebase-context]
 command = "npx"
-args = ["-y", "codebase-context@2.2.0"]
+args = ["-y", "codebase-context@2.4.0"]
 startup_timeout_sec = 120
 ```
 
@@ -82,28 +82,28 @@ startup_timeout_sec = 120
 
 **Official docs:** [Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). The supported `startup_timeout_sec` option defaults to ten seconds; the project example allows 120 seconds for initial `npx` package preparation. This does not prove Desktop startup or guarantee completion of a cold download.
 
-## Codex Desktop: published 2.2.0
+## Codex Desktop: 2.4.0 recipe
 
 Create or merge `.codex/config.toml` in the project you want to search. Preserve any existing settings:
 
 ```toml
 [mcp_servers.codebase-context]
 command = "npx"
-args = ["-y", "codebase-context@2.2.0"]
+args = ["-y", "codebase-context@2.4.0"]
 startup_timeout_sec = 120
 ```
 
 Trust the project if asked, restart Codex and start a new task there. Use the first-use prompt above so the agent selects the current repository. The CLI command in the preceding section writes user-level config; this recipe uses a trusted project's config instead.
 
-**Verification boundary:** isolated Windows CLI and SDK/MCP checks on October 5 indexed a six-file fixture with published `2.2.0`, selected its project, retrieved context and found a source that the host could open. The exact `npx -y codebase-context@2.2.0 <project>` entrypoint also passed using a warmed isolated npm cache and prepared index. This does not establish a fully cold download or a fresh Codex Desktop agent session. The September Desktop session below used a packed candidate; keep it separate from published-package acceptance.
+**Verification boundary:** isolated Windows CLI and SDK/MCP checks on October 5 exercised published `2.2.0` on a six-file fixture; the exact `npx -y codebase-context@2.2.0 <project>` entrypoint passed with a warmed isolated npm cache and prepared index. This is historical evidence for `2.2.0`, not verification of `2.4.0`, a fully cold download or a fresh Codex Desktop agent session. The September Desktop session below used a packed candidate; keep it separate from published-package acceptance.
 
-On October 6 the exact published `npx` entrypoint was also tested without a folder, environment root or MCP roots, launched from an unrelated directory. Its first tool call returned `selection_required`; an explicit `project` call selected the prepared fixture, search found the expected symbol, context returned its map, and the runner host opened the returned source. A later call without `project` retained that selection. This is SDK/protocol and runner-host evidence with warmed caches and a pre-indexed fixture, not a native Desktop task.
+On October 6 the exact published `2.2.0` `npx` entrypoint was tested without a folder, environment root or MCP roots, launched from an unrelated directory. That check does not verify the `2.4.0` package. Its first tool call returned `selection_required`; an explicit `project` call selected the prepared fixture, search found the expected symbol, context returned its map, and the runner host opened the returned source. A later call without `project` retained that selection. This is SDK/protocol and runner-host evidence with warmed caches and a pre-indexed fixture, not a native Desktop task.
 
-## Unreleased installer candidate
+## Project-scoped installer in 2.4.0
 
-The next release is expected to support one project-only command from the target project:
+Published `2.4.0` includes a project-only setup command that you can run from the target project:
 
-The `init --client codex --yes` flow is an unreleased source candidate. Published npm `2.2.0` does not include these flags. Use the published configuration above rather than an `@latest` installer command; candidate verification uses an exact built or installed candidate.
+The `init --client codex --yes` flow was checked before release from an exact built or packed candidate. Those checks document that candidate; they do not verify the published `2.4.0` package. Use the version-pinned recipes above rather than an `@latest` installer command.
 
 A successful `init --client codex --yes` writes the project-scoped `.codex/config.toml` and prepares the index for that root. If config writing or index preparation fails, setup is incomplete and Codex is not ready to use.
 
@@ -119,21 +119,21 @@ node C:\path\to\codebase-context\dist\index.js init --client codex --yes
 
 Use `--root C:\path\to\project` when the command is run from elsewhere. Here, `root` means the project folder to configure and index. The candidate writes the project-scoped `<project>/.codex/config.toml`, preserves unrelated Codex settings, prepares the index for that folder, and does not write `AGENTS.md` or global client configuration. After a successful result, trust the project in Codex Desktop if prompted, restart or reopen Codex, start a new task in that project, and ask a small project question. A written config and ready index do not prove that Codex loaded or queried the server.
 
-Before release, the generated `npx` server command still resolves the published package unless the candidate is installed in the target project's `node_modules`. Our packaged test installs the candidate in a disposable project and checks its file hash. Running the built setup command alone does not prove that Codex will launch that same candidate.
+At candidate-check time, the generated `npx` server command resolved the published package unless the candidate was installed in the target project's `node_modules`. The packaged test installed the candidate in a disposable project and checked its file hash. Running the built setup command alone did not prove that Codex would launch that same candidate or that the published `2.4.0` package behaves identically.
 
-**Checked on 2026-09-15:** the packed candidate installed and indexed an isolated Windows project. A fresh Codex Desktop task then called the actual `search_codebase` MCP tool and located the requested chart component with its source file and lines. The normal Desktop task flow established project trust; no trust-file edits or replacement CLI/SDK search were used for that answer. This covers the small prepared project with shared caches, not a cold-machine install or the published npm package.
+**Checked on 2026-09-15:** the packed candidate installed and indexed an isolated Windows project. A fresh Codex Desktop task then called the actual `search_codebase` MCP tool and located the requested chart component with its source file and lines. The normal Desktop task flow established project trust; no trust-file edits or replacement CLI/SDK search were used for that answer. This covers the small prepared project with shared caches, not a cold-machine install or the published npm `2.4.0` package.
 
 ## Optional fixed-folder setup and CLI preparation
 
-To set a default project before the first tool call, append its full path to the server arguments, for example `args = ["-y", "codebase-context@2.2.0", "C:/projects/my-app"]`. Use a quoted literal shell argument in registration commands. This makes the default fixed across repositories when the registration is user-scoped; explicit tool selection can still choose another allowed project.
+To set a default project before the first tool call, append its full path to the server arguments, for example `args = ["-y", "codebase-context@2.4.0", "C:/projects/my-app"]`. Use a quoted literal shell argument in registration commands. This makes the default fixed across repositories when the registration is user-scoped; explicit tool selection can still choose another allowed project.
 
 To prepare the index separately, run from the project folder:
 
 ```powershell
-npx -y codebase-context@2.2.0 reindex
+npx -y codebase-context@2.4.0 reindex
 ```
 
-Do not use published `2.2.0`'s interactive `init` as the setup route. October 6 isolated checks found that it ignores `--help`, `--client` and `--yes`; its Claude/Codex registration executes `mcp` instead of the client executable, and its HTTP recipes require a separately started server. It can exit zero after registration fails. The unreleased installer above is a separate implementation.
+The setup failures below are specific to published `2.2.0`'s interactive `init`: October 6 isolated checks found that it ignores `--help`, `--client` and `--yes`; its Claude/Codex registration executes `mcp` instead of the client executable, and its HTTP recipes require a separately started server. It can exit zero after registration fails. These findings do not describe the `2.4.0` installer documented above.
 
 ## Gemini CLI
 
@@ -146,13 +146,13 @@ Do not use published `2.2.0`'s interactive `init` as the setup route. October 6
 User setup:
 
 ```bash
-gemini mcp add --scope user codebase-context npx -y codebase-context@2.2.0
+gemini mcp add --scope user codebase-context npx -y codebase-context@2.4.0
 ```
 
 Project setup:
 
 ```bash
-gemini mcp add --scope project codebase-context npx -y codebase-context@2.2.0
+gemini mcp add --scope project codebase-context npx -y codebase-context@2.4.0
 ```
 
 Gemini writes an `mcpServers` entry in its settings. Claude, Codex, and Copilot CLI use `--`; Gemini does not.
@@ -178,7 +178,7 @@ Create `.cursor/mcp.json`:
   "mcpServers": {
     "codebase-context": {
       "command": "npx",
-      "args": ["-y", "codebase-context@2.2.0"]
+      "args": ["-y", "codebase-context@2.4.0"]
     }
   }
 }
@@ -203,7 +203,7 @@ Checked config shape: `.cursor/mcp.json with mcpServers.codebase-context command
 Official user command:
 
 ```powershell
-code --add-mcp '{"name":"codebase-context","command":"npx","args":["-y","codebase-context@2.2.0"]}'
+code --add-mcp '{"name":"codebase-context","command":"npx","args":["-y","codebase-context@2.4.0"]}'
 ```
 
 Deterministic workspace config at `.vscode/mcp.json`:
@@ -213,7 +213,7 @@ Deterministic workspace config at `.vscode/mcp.json`:
   "servers": {
     "codebase-context": {
       "command": "npx",
-      "args": ["-y", "codebase-context@2.2.0"]
+      "args": ["-y", "codebase-context@2.4.0"]
     }
   }
 }
@@ -234,7 +234,7 @@ Deterministic workspace config at `.vscode/mcp.json`:
 **Scope:** User config.
 
 ```bash
-copilot mcp add codebase-context -- npx -y codebase-context@2.2.0
+copilot mcp add codebase-context -- npx -y codebase-context@2.4.0
 ```
 
 **What was checked:** The command ran with an isolated `--config-dir` and wrote the expected `mcp-config.json` command, arguments, and tool filter.
@@ -254,7 +254,7 @@ copilot mcp add codebase-context -- npx -y codebase-context@2.2.0
 Run once:
 
 ```bash
-opencode mcp add codebase-context '--' npx -y codebase-context@2.2.0
+opencode mcp add codebase-context '--' npx -y codebase-context@2.4.0
 ```
 
 Keep the quoted `'--'`: the installed Windows PowerShell npm shim consumes an unquoted separator. The quoted form also works in POSIX shells.
@@ -267,7 +267,7 @@ For a project-local alternative, merge this into `opencode.json`:
   "mcp": {
     "codebase-context": {
       "type": "local",
-      "command": ["npx", "-y", "codebase-context@2.2.0"],
+      "command": ["npx", "-y", "codebase-context@2.4.0"],
       "enabled": true,
       "timeout": 120000
     }
@@ -300,7 +300,7 @@ Create `~/.codeium/windsurf/mcp_config.json`:
   "mcpServers": {
     "codebase-context": {
       "command": "npx",
-      "args": ["-y", "codebase-context@2.2.0"]
+      "args": ["-y", "codebase-context@2.4.0"]
     }
   }
 }
@@ -319,8 +319,8 @@ Checked config shape: `~/.codeium/windsurf/mcp_config.json with mcpServers.codeb
 Use `stdio` for the simplest setup. HTTP can let several clients share one long-running local process, but support depends on the client and this path is not part of the default setup proof:
 
 ```bash
-npx -y codebase-context@2.2.0 --http
-npx -y codebase-context@2.2.0 --http --port 4000
+npx -y codebase-context@2.4.0 --http
+npx -y codebase-context@2.4.0 --http --port 4000
 ```
 
 The documented default endpoint is `http://127.0.0.1:3100/mcp`. Config-shape templates are available in [`templates/mcp/stdio/.mcp.json`](../templates/mcp/stdio/.mcp.json) and [`templates/mcp/http/.mcp.json`](../templates/mcp/http/.mcp.json); pin the published package as in the recipes above. HTTP does not discover a client's project folder; the agent still has to select its repository.
@@ -339,7 +339,7 @@ Some clients also announce workspace roots. One valid root can auto-select; seve
 
 [MCP deprecated Roots on July 28, 2026](https://modelcontextprotocol.io/specification/2026-07-28/client/roots), recommending explicit directories/files in tool parameters, resource URIs or server configuration. CBC's older Roots support remains a compatibility aid rather than a required setup step.
 
-October 6 verification: 18 focused current-source routing tests passed, including ambiguous roots, explicit selection, subsequent calls and root changes. The exact published server also switched between two isolated prepared repositories A to B to A in one no-roots stdio process: search paths, context map and subsequent status calls followed each selection. The runner host opened the expected distinct sources. A native agent session across real repositories remains a validation step; stdio process-local selection does not establish concurrent HTTP isolation.
+October 6 verification: 18 focused current-source routing tests passed, including ambiguous roots, explicit selection, subsequent calls and root changes. The exact published `2.2.0` server also switched between two isolated prepared repositories A to B to A in one no-roots stdio process; search paths, context map and subsequent status calls followed each selection, and the runner host opened the expected distinct sources. This historical package check does not verify published `2.4.0` or establish concurrent HTTP isolation. A native agent session across real repositories remains a validation step.
 
 A follow-up recorded raw `search_codebase` calls containing only `query` and `mode`, with no `project`: they returned A, B and A after those explicit selections. The caller does not automatically add the full path; CBC routes omitted-project calls using its selected project. This state lasts for that stdio process. Select again after a server restart or when changing repositories.
 
diff --git a/docs/demo.md b/docs/demo.md
index 8b06f23..926860a 100644
--- a/docs/demo.md
+++ b/docs/demo.md
@@ -2,14 +2,14 @@
 
 This walkthrough shows real CLI output captured from the open-source `angular-spotify` repository during a local proof run. That sample checkout is not bundled here.
 
-To try the same CLI flow, use Node.js 22 or newer and open a terminal in the repository you want to inspect. These commands use published `codebase-context@2.2.0`; the CLI uses the current directory as the project root. MCP registration and project selection are covered in the [client setup guide](./client-setup.md).
+To try the same CLI flow, use Node.js 22 or newer and open a terminal in the repository you want to inspect. These commands target published `codebase-context@2.4.0`; the CLI uses the current directory as the project root. MCP registration and project selection are covered in the [client setup guide](./client-setup.md).
 
-The saved output below is from an earlier CLI run, not the published-package commands shown here. The machine-specific repository root is omitted from the returned file path. This capture does not verify the current package or an MCP connection.
+The saved output below is from an earlier CLI run, not from published `2.4.0` or the commands shown here. The machine-specific repository root is omitted from the returned file path. This capture does not verify the current package or an MCP connection.
 
 ## 0. Build The Local Index
 
 ```bash
-npx -y codebase-context@2.2.0 reindex
+npx -y codebase-context@2.4.0 reindex
 ```
 
 Run this before the first map or search in a repository. Later runs can use `reindex --incremental` after the code changes.
@@ -17,7 +17,7 @@ Run this before the first map or search in a repository. Later runs can use `rei
 ## 1. Start With The Conventions Map
 
 ```bash
-npx -y codebase-context@2.2.0 map --json
+npx -y codebase-context@2.4.0 map --json
 ```
 
 Captured output excerpt:
@@ -50,7 +50,7 @@ What this shows:
 ## 2. Search With Edit Intent
 
 ```bash
-npx -y codebase-context@2.2.0 search --query "auth headers" --intent edit --limit 3 --json
+npx -y codebase-context@2.4.0 search --query "auth headers" --intent edit --limit 3 --json
 ```
 
 Captured output excerpt:
@@ -91,7 +91,7 @@ What this shows:
 ## 3. Check A Team Pattern Directly
 
 ```bash
-npx -y codebase-context@2.2.0 patterns --category state --json
+npx -y codebase-context@2.4.0 patterns --category state --json
 ```
 
 Captured output excerpt:
diff --git a/docs/review-context.md b/docs/review-context.md
index e35df6a..f1ae2e2 100644
--- a/docs/review-context.md
+++ b/docs/review-context.md
@@ -26,13 +26,13 @@ node dist/review-bin.js --base origin/main --head HEAD
 After package publication, the package also exposes:
 
 ```bash
-npx codebase-context-review --base origin/main --head HEAD
+npm exec --yes --package=codebase-context@2.4.0 -- codebase-context-review --base origin/main --head HEAD
 ```
 
 Use `--json` for the complete machine-readable packet:
 
 ```bash
-npx codebase-context-review \
+npm exec --yes --package=codebase-context@2.4.0 -- codebase-context-review \
   --base origin/main \
   --head HEAD \
   --max-queries 8 \

From 8340d0cd3403c81448d1ecc5a8a54460e56bf44b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Patrick=20Rossell=C3=B3=20Colom?=
 <74001504+PatrickSys@users.noreply.github.com>
Date: Tue, 6 Oct 2026 16:09:22 +0200
Subject: [PATCH 2/6] fix: align release workflow with 2.4.0

---
 .github/workflows/publish-npm-on-release.yml | 4 ++--
 docs/client-setup.md                         | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/publish-npm-on-release.yml b/.github/workflows/publish-npm-on-release.yml
index 4ca7cf4..9b964d7 100644
--- a/.github/workflows/publish-npm-on-release.yml
+++ b/.github/workflows/publish-npm-on-release.yml
@@ -8,9 +8,9 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Tag to publish (e.g. v2.3.0)'
+        description: 'Tag to publish (e.g. v2.4.0)'
         required: true
-        default: 'v2.3.0'
+        default: 'v2.4.0'
 
 permissions:
   contents: read
diff --git a/docs/client-setup.md b/docs/client-setup.md
index 384cef0..b1af9bd 100644
--- a/docs/client-setup.md
+++ b/docs/client-setup.md
@@ -339,7 +339,7 @@ Some clients also announce workspace roots. One valid root can auto-select; seve
 
 [MCP deprecated Roots on July 28, 2026](https://modelcontextprotocol.io/specification/2026-07-28/client/roots), recommending explicit directories/files in tool parameters, resource URIs or server configuration. CBC's older Roots support remains a compatibility aid rather than a required setup step.
 
-October 6 verification: 18 focused current-source routing tests passed, including ambiguous roots, explicit selection, subsequent calls and root changes. The exact published `2.2.0` server also switched between two isolated prepared repositories A to B to A in one no-roots stdio process; search paths, context map and subsequent status calls followed each selection, and the runner host opened the expected distinct sources. This historical package check does not verify published `2.4.0` or establish concurrent HTTP isolation. A native agent session across real repositories remains a validation step.
+October 6 verification: 18 focused current-source routing tests passed, including ambiguous roots, explicit selection, subsequent calls and root changes. The exact published `2.2.0` server also switched between two isolated prepared repositories A to B to A in one no-roots stdio process; search paths, context map and subsequent status calls followed each selection, and the runner host opened the expected distinct sources. This historical package check does not verify published `2.4.0` or establish concurrent HTTP isolation. A native agent session across real repositories remains a validation step; stdio process-local selection does not establish concurrent HTTP isolation.
 
 A follow-up recorded raw `search_codebase` calls containing only `query` and `mode`, with no `project`: they returned A, B and A after those explicit selections. The caller does not automatically add the full path; CBC routes omitted-project calls using its selected project. This state lasts for that stdio process. Select again after a server restart or when changing repositories.
 

From 87fbe228ed428f2cc0a0a3033f605a65c7260662 Mon Sep 17 00:00:00 2001
From: PatrickSys <rossellocolompatrick@gmail.com>
Date: Thu, 15 Oct 2026 23:46:11 +0200
Subject: [PATCH 3/6] docs: explain real setup and 2.4.0 changes

---
 README.md            | 30 ++++++++++++++++++------------
 docs/capabilities.md |  5 +++--
 docs/cli.md          |  8 ++++----
 docs/client-setup.md | 40 +++++++++++-----------------------------
 docs/demo.md         |  4 ++--
 5 files changed, 38 insertions(+), 49 deletions(-)

diff --git a/README.md b/README.md
index 2e86d5d..b70d86f 100644
--- a/README.md
+++ b/README.md
@@ -2,15 +2,11 @@
 
 [![npm version](https://img.shields.io/npm/v/codebase-context)](https://www.npmjs.com/package/codebase-context) [![license](https://img.shields.io/npm/l/codebase-context)](./LICENSE) [![node](https://img.shields.io/node/v/codebase-context)](https://github.com/PatrickSys/codebase-context/blob/master/package.json)
 
-## Your coding agent doesn't understand your codebase.
-
-Coding agents can read files, but they still have to discover how your repository is organized, which patterns your team follows, and which examples are worth copying.
-
-Codebase Context gives an agent a local view of that information through code search, team patterns, strong examples, and project memory. It runs as an MCP server - a local tool that your editor or command-line agent can call while it works - and keeps the index on your machine by default.
+Codebase Context gives coding agents a map of your repository through MCP, for developers who want their agent to find relevant code and follow the team's patterns. Search, examples and project memory run locally by default.
 
 ## Set up your AI client
 
-Choose your coding tool and run its command once. Use Node.js 22 or newer. These commands use published npm `2.4.0` and do not require a project folder in your configuration:
+Use Node.js 22 or newer. Choose your coding tool and run its command once; the examples target the 2.4.0 release:
 
 ```bash
 # Claude Code
@@ -25,9 +21,19 @@ opencode mcp add codebase-context '--' npx -y codebase-context@2.4.0
 
 Start a new agent session in your project, then ask:
 
-> Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project when checking get_indexing_status and searching. Wait for indexing if needed, read codebase://context, then search_codebase and open a returned source file. Show me the relevant files.
+> Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project, wait for indexing if needed, and open the relevant source files.
+
+Replace `[feature]` with something you want to find. The first run downloads a local model and indexes the repository; time depends on repository size, CPU and model.
+
+### New in 2.4.0
+
+- Opt-in NestJS support from community contributor Aaron Olin. See the [analyzer options](./docs/capabilities.md#analyzers).
+- Better React/Next.js detection and a fix for reranker passage scoring.
+- Transformers.js v4 for local models.
+
+Known limits: [Intel Mac indexing crash (#68)](https://github.com/PatrickSys/codebase-context/issues/68), [custom OpenAI endpoints (#70)](https://github.com/PatrickSys/codebase-context/issues/70) and [Ollama (#71)](https://github.com/PatrickSys/codebase-context/issues/71) remain open.
 
-Replace `[feature]` with something you want to find. The agent supplies the repository path in its tool calls, so the registration can serve different projects. Initial indexing may need a local model download. The October 6 isolated checks exercised published `2.2.0` client registrations and project selection/search. They did not verify `2.4.0` or establish a full native agent investigation.
+The existing [benchmark](https://github.com/PatrickSys/codebase-context/blob/master/docs/benchmark.md) reports 25.7% expected-file recovery versus jCodeMunch's 27.1% in a fixed retrieval comparison; it does not establish a winner or coding quality.
 
 For Codex Desktop, create or merge `.codex/config.toml` in the project you want to search:
 
@@ -50,7 +56,7 @@ Other clients use their own setup commands:
 | GitHub Copilot CLI          | `copilot mcp add codebase-context -- npx -y codebase-context@2.4.0` |
 | Windsurf                    | Add `~/.codeium/windsurf/mcp_config.json`                                    |
 
-Check an existing same-name entry before replacing it. To give the server a default folder, append that folder's absolute path to the `npx` arguments. The [client setup guide](./docs/client-setup.md) covers scopes, optional fixed-folder configuration, the `2.4.0` project installer and its verification limits. The registration bugs found in `2.2.0` are historical.
+Check an existing same-name entry before replacing it. To give the server a default folder, append that folder's absolute path to the `npx` arguments. The [client setup guide](./docs/client-setup.md) covers scopes, optional fixed-folder configuration and the interactive setup wizard's limitations.
 
 The [client setup guide](./docs/client-setup.md) has the exact commands and config for every client, plus what was checked locally and what still relies on official instructions.
 
@@ -64,7 +70,7 @@ The default connection is `stdio` (standard input/output): your client starts th
 
 ### Team patterns and examples
 
-`get_team_patterns` shows the approaches used in the repository and points to representative files. Published `2.4.0` includes dedicated analyzers for Angular, React, Next.js and NestJS, with a generic analyzer for other stacks.
+`get_team_patterns` shows the approaches used in the repository and points to representative files. Version `2.4.0` includes dedicated analyzers for Angular, React, Next.js and opt-in NestJS, with a generic analyzer for other stacks.
 
 ### Project memory
 
@@ -80,7 +86,7 @@ The `codebase-context-review` CLI creates a bounded context packet from a commit
 2. **Understand the repository.** The agent can request a compact codebase map with structure, patterns, and representative files.
 3. **Find the code for the task.** Search returns ranked files and symbols; the agent reads the selected files before editing.
 
-The same information is available from the terminal. Run these commands from your project root. The first index can take a while because it scans the project and creates local embeddings; once it is ready, inspect the map and search for the code you need:
+The same information is available from the terminal. Run these commands from your project root. The first run downloads a local model and indexes the repository; time depends on repository size, CPU and model. Once it is ready, inspect the map and search for the code you need:
 
 ```bash
 # Build or refresh the local index
@@ -149,7 +155,7 @@ The method and failures are documented so the measurements can be inspected with
 - Retrieval measurements describe expected-file coverage, file precision, and reported `peakPrivateGb`, not patch correctness or end-to-end coding quality.
 - The paired token observation covers two frozen investigation tasks and records observed agent behavior; it is not a universal token or time guarantee.
 - Setup checks differ by client. The detailed guide distinguishes a written config, a config recognized by the client, a local connection, and instructions checked only against official docs.
-- Published `2.4.0` has dedicated Angular, React, Next.js and NestJS analyzers. Other projects use the generic analyzer and the language parsers available for that stack.
+- Version `2.4.0` has dedicated Angular, React, Next.js and opt-in NestJS analyzers. Other projects use the generic analyzer and the language parsers available for that stack.
 - The default searchable-chunk limit is 5,000 per project. In `~/.codebase-context/config.json`, set `projects[].parsing.maxChunks` for a project that needs a higher limit.
 - The agent must identify its repository in tool calls when no default or unambiguous client root is available. Concurrent HTTP client isolation is not established by the stdio routing checks.
 
diff --git a/docs/capabilities.md b/docs/capabilities.md
index 536c736..6f2729e 100644
--- a/docs/capabilities.md
+++ b/docs/capabilities.md
@@ -27,7 +27,7 @@ Copy-pasteable client config templates are shipped in the package:
 - `templates/mcp/stdio/.mcp.json` — stdio setup for `.mcp.json`-style clients
 - `templates/mcp/http/.mcp.json` — HTTP setup for `.mcp.json`-style clients
 
-Use Node.js 22 or newer with the published 2.4.0 commands shown here. For client registration recipes and their verification limits, see the [client setup guide](./client-setup.md).
+Use Node.js 22 or newer with the 2.4.0 commands shown here. For client registration recipes and their verification limits, see the [client setup guide](./client-setup.md).
 
 ## CLI Reference
 
@@ -50,7 +50,7 @@ For a command gallery with examples, see `docs/cli.md`.
 | `memory add`           | `--type`, `--category`, `--memory`, `--reason`                                                             | `remember`                             |
 | `memory remove <id>`   | —                                                                                                          | —                                      |
 
-Commands that list `--json` above support raw JSON output. For MCP client registration, follow the [published client setup recipes](./client-setup.md). The registration failures documented for `init` apply to published 2.2.0; see that guide for current 2.4.0 setup instructions. Errors go to stderr with exit code 1.
+Commands that list `--json` above support raw JSON output. For MCP client registration, follow the [published client setup recipes](./client-setup.md). The existing `init` wizard is interactive and generates HTTP setup; see that guide for its current limitations. Errors go to stderr with exit code 1.
 
 ```bash
 # Quick examples
@@ -274,6 +274,7 @@ Impact is 2-hop transitive: direct importers (hop 1) and their importers (hop 2)
 - **Angular**: signals, standalone components, control flow syntax, lifecycle hooks, DI patterns, component metadata
 - **React**: function/class components, custom hooks, context usage, memoization, Suspense, ecosystem signal extraction
 - **Next.js**: App Router and Pages Router detection, route/API classification, route paths, `"use client"`, metadata exports
+- **NestJS (opt-in)**: modules, controllers, providers and route handlers, contributed by Aaron Olin. The library indexer accepts `config: { analyzers: { nestjs: { enabled: true } } }`; the CLI/server project configuration does not currently expose analyzer enablement.
 - **Generic**: 30+ have indexing/retrieval coverage including PHP, Ruby, Swift, Scala, Shell, config/markup., 10 languages have full symbol extraction (Tree-sitter: TypeScript, JavaScript, Python, Java, Kotlin, C, C++, C#, Go, Rust).
 
 Notes:
diff --git a/docs/cli.md b/docs/cli.md
index d9dc407..06de2c9 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -10,9 +10,9 @@
 
 > Output depends on the repo you run it against. The examples below are illustrative (paths, counts, and detected frameworks will vary).
 >
-> These output examples come from an earlier CLI run; they were not captured from published `2.4.0` and do not verify an MCP connection.
+> These output examples come from an earlier CLI run; they were not captured from `2.4.0` and do not verify an MCP connection.
 >
-> The commands below use published `codebase-context@2.4.0` and require Node.js 22 or newer. The CLI is intentionally single-project per invocation and targets one root via `CODEBASE_ROOT` or the current working directory. MCP registration and project selection are covered in the [client setup guide](./client-setup.md).
+> The commands below use `codebase-context@2.4.0` and require Node.js 22 or newer. The CLI is intentionally single-project per invocation and targets one root via `CODEBASE_ROOT` or the current working directory. MCP registration and project selection are covered in the [client setup guide](./client-setup.md).
 
 ## How to run
 
@@ -44,13 +44,13 @@ CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context@2.4.0 patterns
 - `reindex` — rebuild index (full or incremental)
 - `style-guide` — find style guide sections in docs
 - `memory list|add|remove` — manage team memory (stored in `.codebase-context/memory.json`)
-- MCP client registration — use the published 2.4.0 recipes in the [client setup guide](./client-setup.md); the setup failures documented for `init` apply to 2.2.0
+- MCP client registration — use the 2.4.0 recipes in the [client setup guide](./client-setup.md); `init` is an interactive HTTP setup wizard with the limitations described there
 
 ---
 
 ## First use
 
-Run these CLI commands from the project root. Build or refresh the local index first; the first index may take a while while the project is scanned and local embeddings are created. Then inspect the conventions map and search for the code you need:
+Run these CLI commands from the project root. Build or refresh the local index first; the first run downloads a local model and indexes the repository; time depends on repository size, CPU and model. Then inspect the conventions map and search for the code you need:
 
 ```bash
 npx -y codebase-context@2.4.0 reindex
diff --git a/docs/client-setup.md b/docs/client-setup.md
index b1af9bd..a397615 100644
--- a/docs/client-setup.md
+++ b/docs/client-setup.md
@@ -1,12 +1,12 @@
 # Client Setup
 
-Codebase Context runs as a local MCP server: a tool your AI editor or command-line client can call while it works. Register it without a fixed folder, then let the agent supply its current repository through the `project` tool parameter. These recipes target published npm `2.4.0`.
+Codebase Context runs as a local MCP server: a tool your AI editor or command-line client can call while it works. Register it without a fixed folder, then let the agent supply its current repository through the `project` tool parameter. These recipes target the 2.4.0 release.
 
-Use Node.js 22 or newer for these recipes. The package declares Node 18+, but native dependency requirements are narrower than that broad declaration; these checks do not establish Node 18.0 compatibility.
+Use Node.js 22 or newer for these recipes. The package still declares Node 18+, but the built pack failed to index source on Node 18.20.4 with `ReferenceError: crypto is not defined` in UUID chunk creation. Node 22 is the lowest version used successfully in the package check; the engine declaration remains an open compatibility issue.
 
 The copyable registration commands target PowerShell or a POSIX terminal. Windows Command Prompt was not tested; OpenCode's quoted separator is shell-dependent.
 
-## Current published-package recipes (updated 2026-10-06)
+## Client recipes for 2.4.0
 
 Claude Code, Codex CLI and OpenCode registration commands were checked again on October 6 without a project argument. The other clients retain their older config-shape evidence; no-folder native agent use is unverified for them. See the dated notes below.
 
@@ -25,7 +25,7 @@ After registration, start a new agent session in your project and ask:
 
 > Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project when checking get_indexing_status and searching. Wait for indexing if needed, read codebase://context, then search_codebase and open a returned source file. Show me the relevant files.
 
-The first index may take a while and download a local model. You can prepare it separately with `npx -y codebase-context@2.4.0 reindex` from the project folder. Index readiness, client connection and useful agent behavior are separate checks.
+The first run downloads a local model and indexes the repository; time depends on repository size, CPU and model. You can prepare it separately with `npx -y codebase-context@2.4.0 reindex` from the project folder. Index readiness, client connection and useful agent behavior are separate checks.
 
 ## Claude Code
 
@@ -95,33 +95,15 @@ startup_timeout_sec = 120
 
 Trust the project if asked, restart Codex and start a new task there. Use the first-use prompt above so the agent selects the current repository. The CLI command in the preceding section writes user-level config; this recipe uses a trusted project's config instead.
 
-**Verification boundary:** isolated Windows CLI and SDK/MCP checks on October 5 exercised published `2.2.0` on a six-file fixture; the exact `npx -y codebase-context@2.2.0 <project>` entrypoint passed with a warmed isolated npm cache and prepared index. This is historical evidence for `2.2.0`, not verification of `2.4.0`, a fully cold download or a fresh Codex Desktop agent session. The September Desktop session below used a packed candidate; keep it separate from published-package acceptance.
+**Verification boundary:** isolated Windows CLI and SDK/MCP checks on October 5 exercised published `2.2.0` on a six-file fixture; the exact `npx -y codebase-context@2.2.0 <project>` entrypoint passed with a warmed isolated npm cache and prepared index. This is historical evidence for `2.2.0`, not verification of `2.4.0`, a fully cold download or a fresh Codex Desktop agent session.
 
 On October 6 the exact published `2.2.0` `npx` entrypoint was tested without a folder, environment root or MCP roots, launched from an unrelated directory. That check does not verify the `2.4.0` package. Its first tool call returned `selection_required`; an explicit `project` call selected the prepared fixture, search found the expected symbol, context returned its map, and the runner host opened the returned source. A later call without `project` retained that selection. This is SDK/protocol and runner-host evidence with warmed caches and a pre-indexed fixture, not a native Desktop task.
 
-## Project-scoped installer in 2.4.0
+## Interactive setup wizard
 
-Published `2.4.0` includes a project-only setup command that you can run from the target project:
+Run `npx -y codebase-context@2.4.0 init` from the target project to open the existing interactive wizard. It asks you to choose Claude Code, Cursor, Codex or OpenCode, previews HTTP configuration and asks before applying it. It separately offers to write an instruction block to `CLAUDE.md`, `.cursorrules` or `AGENTS.md` where applicable.
 
-The `init --client codex --yes` flow was checked before release from an exact built or packed candidate. Those checks document that candidate; they do not verify the published `2.4.0` package. Use the version-pinned recipes above rather than an `@latest` installer command.
-
-A successful `init --client codex --yes` writes the project-scoped `.codex/config.toml` and prepares the index for that root. If config writing or index preparation fails, setup is incomplete and Codex is not ready to use.
-
-For candidate verification before publication, build the source checkout and run its absolute `dist/index.js` path from the project you want to configure:
-
-```powershell
-# In the codebase-context source checkout
-npm run build
-
-# In the target project, using the built CLI path
-node C:\path\to\codebase-context\dist\index.js init --client codex --yes
-```
-
-Use `--root C:\path\to\project` when the command is run from elsewhere. Here, `root` means the project folder to configure and index. The candidate writes the project-scoped `<project>/.codex/config.toml`, preserves unrelated Codex settings, prepares the index for that folder, and does not write `AGENTS.md` or global client configuration. After a successful result, trust the project in Codex Desktop if prompted, restart or reopen Codex, start a new task in that project, and ask a small project question. A written config and ready index do not prove that Codex loaded or queried the server.
-
-At candidate-check time, the generated `npx` server command resolved the published package unless the candidate was installed in the target project's `node_modules`. The packaged test installed the candidate in a disposable project and checked its file hash. Running the built setup command alone did not prove that Codex would launch that same candidate or that the published `2.4.0` package behaves identically.
-
-**Checked on 2026-09-15:** the packed candidate installed and indexed an isolated Windows project. A fresh Codex Desktop task then called the actual `search_codebase` MCP tool and located the requested chart component with its source file and lines. The normal Desktop task flow established project trust; no trust-file edits or replacement CLI/SDK search were used for that answer. This covers the small prepared project with shared caches, not a cold-machine install or the published npm `2.4.0` package.
+The wizard does not accept non-interactive client/root flags or prepare an index. Its HTTP configurations need a separately started server. In the current source, Claude/Codex registration attempts to execute `mcp` directly and can report failure while the wizard still exits successfully. Use the direct stdio commands or configuration above for those clients; the wizard is not a verified one-step setup.
 
 ## Optional fixed-folder setup and CLI preparation
 
@@ -133,7 +115,7 @@ To prepare the index separately, run from the project folder:
 npx -y codebase-context@2.4.0 reindex
 ```
 
-The setup failures below are specific to published `2.2.0`'s interactive `init`: October 6 isolated checks found that it ignores `--help`, `--client` and `--yes`; its Claude/Codex registration executes `mcp` instead of the client executable, and its HTTP recipes require a separately started server. It can exit zero after registration fails. These findings do not describe the `2.4.0` installer documented above.
+The interactive wizard limitations described above are still present in the 2.4.0 source. A successful wizard exit alone does not establish working client registration.
 
 ## Gemini CLI
 
@@ -277,7 +259,7 @@ For a project-local alternative, merge this into `opencode.json`:
 
 Checked config shape: `opencode.json with a local command array and timeout 120000`.
 
-The longer timeout is intentional because the isolated cold start took about 38 seconds while `npx` prepared the package and server.
+The longer timeout allows for initial `npx` package preparation and server startup; that time varies with the machine, network and cache.
 
 **What was checked:** With home, config, data, cache, temporary and workspace paths redirected, the no-folder command wrote user configuration and `opencode mcp list` reported Connected. An August 11 check with OpenCode 1.18.5 also connected using the project config shape and an explicit folder; the no-folder project variant is not a new native acceptance check.
 
@@ -339,7 +321,7 @@ Some clients also announce workspace roots. One valid root can auto-select; seve
 
 [MCP deprecated Roots on July 28, 2026](https://modelcontextprotocol.io/specification/2026-07-28/client/roots), recommending explicit directories/files in tool parameters, resource URIs or server configuration. CBC's older Roots support remains a compatibility aid rather than a required setup step.
 
-October 6 verification: 18 focused current-source routing tests passed, including ambiguous roots, explicit selection, subsequent calls and root changes. The exact published `2.2.0` server also switched between two isolated prepared repositories A to B to A in one no-roots stdio process; search paths, context map and subsequent status calls followed each selection, and the runner host opened the expected distinct sources. This historical package check does not verify published `2.4.0` or establish concurrent HTTP isolation. A native agent session across real repositories remains a validation step; stdio process-local selection does not establish concurrent HTTP isolation.
+October 6 verification: 18 focused current-source routing tests passed, including ambiguous roots, explicit selection, subsequent calls and root changes. The exact published `2.2.0` server also switched between two isolated prepared repositories A to B to A in one no-roots stdio process; search paths, context map and subsequent status calls followed each selection, and the runner host opened the expected distinct sources. This historical package check does not verify `2.4.0` or establish concurrent HTTP isolation. A native agent session across real repositories remains a validation step; stdio process-local selection does not establish concurrent HTTP isolation.
 
 A follow-up recorded raw `search_codebase` calls containing only `query` and `mode`, with no `project`: they returned A, B and A after those explicit selections. The caller does not automatically add the full path; CBC routes omitted-project calls using its selected project. This state lasts for that stdio process. Select again after a server restart or when changing repositories.
 
diff --git a/docs/demo.md b/docs/demo.md
index 926860a..b3ad6d4 100644
--- a/docs/demo.md
+++ b/docs/demo.md
@@ -2,9 +2,9 @@
 
 This walkthrough shows real CLI output captured from the open-source `angular-spotify` repository during a local proof run. That sample checkout is not bundled here.
 
-To try the same CLI flow, use Node.js 22 or newer and open a terminal in the repository you want to inspect. These commands target published `codebase-context@2.4.0`; the CLI uses the current directory as the project root. MCP registration and project selection are covered in the [client setup guide](./client-setup.md).
+To try the same CLI flow, use Node.js 22 or newer and open a terminal in the repository you want to inspect. These commands target `codebase-context@2.4.0`; the CLI uses the current directory as the project root. MCP registration and project selection are covered in the [client setup guide](./client-setup.md).
 
-The saved output below is from an earlier CLI run, not from published `2.4.0` or the commands shown here. The machine-specific repository root is omitted from the returned file path. This capture does not verify the current package or an MCP connection.
+The saved output below is from an earlier CLI run, not from `2.4.0` or the commands shown here. The machine-specific repository root is omitted from the returned file path. This capture does not verify the current package or an MCP connection.
 
 ## 0. Build The Local Index
 

From 6fa4b025f427f8d53125ad6e28453856835f7ac0 Mon Sep 17 00:00:00 2001
From: PatrickSys <rossellocolompatrick@gmail.com>
Date: Fri, 16 Oct 2026 07:37:07 +0200
Subject: [PATCH 4/6] fix(release): require an explicit manual publish tag

---
 .github/workflows/publish-npm-on-release.yml |  4 ++--
 README.md                                    |  2 ++
 docs/client-setup.md                         |  2 ++
 tests/release-truth-surfaces.test.ts         | 13 ++++++++++---
 4 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/publish-npm-on-release.yml b/.github/workflows/publish-npm-on-release.yml
index 9b964d7..68755f1 100644
--- a/.github/workflows/publish-npm-on-release.yml
+++ b/.github/workflows/publish-npm-on-release.yml
@@ -8,9 +8,9 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: 'Tag to publish (e.g. v2.4.0)'
+        description: 'Release tag to publish'
         required: true
-        default: 'v2.4.0'
+        type: string
 
 permissions:
   contents: read
diff --git a/README.md b/README.md
index b70d86f..c8f510d 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,8 @@ Codebase Context gives coding agents a map of your repository through MCP, for d
 
 ## Set up your AI client
 
+**2.4.0 setup preview:** use these commands only after that version is available on npm. To install published 2.2.0, follow the [versioned setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
+
 Use Node.js 22 or newer. Choose your coding tool and run its command once; the examples target the 2.4.0 release:
 
 ```bash
diff --git a/docs/client-setup.md b/docs/client-setup.md
index a397615..708ab77 100644
--- a/docs/client-setup.md
+++ b/docs/client-setup.md
@@ -1,5 +1,7 @@
 # Client Setup
 
+**2.4.0 setup preview:** use these commands only after that version is available on npm. To install published 2.2.0, follow the [versioned setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
+
 Codebase Context runs as a local MCP server: a tool your AI editor or command-line client can call while it works. Register it without a fixed folder, then let the agent supply its current repository through the `project` tool parameter. These recipes target the 2.4.0 release.
 
 Use Node.js 22 or newer for these recipes. The package still declares Node 18+, but the built pack failed to index source on Node 18.20.4 with `ReferenceError: crypto is not defined` in UUID chunk creation. Node 22 is the lowest version used successfully in the package check; the engine declaration remains an open compatibility issue.
diff --git a/tests/release-truth-surfaces.test.ts b/tests/release-truth-surfaces.test.ts
index f362ba4..c643dcf 100644
--- a/tests/release-truth-surfaces.test.ts
+++ b/tests/release-truth-surfaces.test.ts
@@ -114,8 +114,15 @@ describe('release truth surfaces', () => {
     expect(visualsDoc).toContain('Historical snapshot');
   });
 
-  it('keeps the manual publish fallback aligned to the package version', () => {
-    expect(workflow).toContain(`description: 'Tag to publish (e.g. v${expectedVersion})'`);
-    expect(workflow).toContain(`default: 'v${expectedVersion}'`);
+  it('requires an explicit release tag for the manual publish fallback', () => {
+    const manualTagInput = workflow.match(/^ {6}tag:\r?\n((?: {8}[^\r\n]*\r?\n)+)/m)?.[1] ?? '';
+
+    expect(manualTagInput).toMatch(/^\s*required:\s*true\s*$/m);
+    expect(manualTagInput).toMatch(/^\s*type:\s*string\s*$/m);
+    expect(manualTagInput).not.toMatch(/^\s*default:/m);
+    expect(workflow).toMatch(/^  release:\r?\n {4}types: \[published\]/m);
+    expect(workflow).toContain(
+      'ref: ${{ github.event.inputs.tag || github.event.release.tag_name }}'
+    );
   });
 });

From df7590d7eaeff395f7e2b7f9c9cbf06eebd75210 Mon Sep 17 00:00:00 2001
From: PatrickSys <rossellocolompatrick@gmail.com>
Date: Fri, 16 Oct 2026 08:18:03 +0200
Subject: [PATCH 5/6] docs: qualify unreleased version commands across guides

---
 docs/capabilities.md                 | 10 ++++---
 docs/cli.md                          |  2 ++
 docs/demo.md                         |  2 ++
 docs/review-context.md               |  2 ++
 tests/release-truth-surfaces.test.ts | 40 ++++++++++++++++++++++++++++
 5 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/docs/capabilities.md b/docs/capabilities.md
index 6f2729e..4d57ec7 100644
--- a/docs/capabilities.md
+++ b/docs/capabilities.md
@@ -1,6 +1,8 @@
 # Capabilities Reference
 
-Technical reference for what `codebase-context` ships today. The public product posture is map first, find second: the bounded conventions map is the first-call surface, and search narrows to the right local example after that. For the user-facing overview, see [README.md](../README.md).
+Technical reference for the 2.4.0 setup preview. The public product posture is map first, find second: the bounded conventions map is the first-call surface, and search narrows to the right local example after that. For the user-facing overview, see [README.md](../README.md).
+
+**2.4.0 setup preview:** use these commands only after that version is available on npm. To install published 2.2.0, follow the [versioned setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
 
 ## Transport Modes
 
@@ -27,7 +29,7 @@ Copy-pasteable client config templates are shipped in the package:
 - `templates/mcp/stdio/.mcp.json` — stdio setup for `.mcp.json`-style clients
 - `templates/mcp/http/.mcp.json` — HTTP setup for `.mcp.json`-style clients
 
-Use Node.js 22 or newer with the 2.4.0 commands shown here. For client registration recipes and their verification limits, see the [client setup guide](./client-setup.md).
+Use Node.js 22 or newer with the 2.4.0 commands shown here. For 2.4.0 setup preview recipes and their verification limits, see the [client setup guide](./client-setup.md).
 
 ## CLI Reference
 
@@ -50,7 +52,7 @@ For a command gallery with examples, see `docs/cli.md`.
 | `memory add`           | `--type`, `--category`, `--memory`, `--reason`                                                             | `remember`                             |
 | `memory remove <id>`   | —                                                                                                          | —                                      |
 
-Commands that list `--json` above support raw JSON output. For MCP client registration, follow the [published client setup recipes](./client-setup.md). The existing `init` wizard is interactive and generates HTTP setup; see that guide for its current limitations. Errors go to stderr with exit code 1.
+Commands that list `--json` above support raw JSON output. For MCP client registration, follow the [2.4.0 setup preview recipes](./client-setup.md). The existing `init` wizard is interactive and generates HTTP setup; see that guide for its current limitations. Errors go to stderr with exit code 1.
 
 ```bash
 # Quick examples
@@ -303,6 +305,6 @@ Reproducible evaluation is shipped as a CLI entrypoint backed by shared scoring
 
 - **Symbol refs are not a call-graph.** `get_symbol_references` counts identifier-node occurrences in the AST (comments/strings excluded via Tree-sitter). It does not distinguish call sites from type annotations, variable assignments, or imports. Full call-site-specific analysis (`call_expression` nodes only) is a roadmap item.
 - **Impact is 2-hop max.** `computeImpactCandidates` walks direct importers then their importers. Full BFS reachability is on the roadmap.
-- **Published 2.4.0 has dedicated Angular, React, Next.js and NestJS analyzers.** Other languages use the Generic analyzer (30+ languages, chunking + import graph, no framework-specific signal extraction).
+- **The 2.4.0 preview source has dedicated Angular, React, Next.js and NestJS analyzers.** Other languages use the Generic analyzer (30+ languages, chunking + import graph, no framework-specific signal extraction).
 - **Default embedding model is `bge-small-en-v1.5` (512-token context).** Granite (8192 context) is opt-in via `EMBEDDING_MODEL`. OpenAI is opt-in via `EMBEDDING_PROVIDER=openai` — sends code externally.
 - **Patterns are file-level frequency counts.** Not semantic clustering. Rising/Declining trend is derived from git commit recency for files using each pattern, not from usage semantics.
diff --git a/docs/cli.md b/docs/cli.md
index 06de2c9..21e0c53 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -10,6 +10,8 @@
 
 > Output depends on the repo you run it against. The examples below are illustrative (paths, counts, and detected frameworks will vary).
 >
+> **2.4.0 setup preview:** use these commands only after that version is available on npm. To install published 2.2.0, follow the [versioned setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
+>
 > These output examples come from an earlier CLI run; they were not captured from `2.4.0` and do not verify an MCP connection.
 >
 > The commands below use `codebase-context@2.4.0` and require Node.js 22 or newer. The CLI is intentionally single-project per invocation and targets one root via `CODEBASE_ROOT` or the current working directory. MCP registration and project selection are covered in the [client setup guide](./client-setup.md).
diff --git a/docs/demo.md b/docs/demo.md
index b3ad6d4..3c9c916 100644
--- a/docs/demo.md
+++ b/docs/demo.md
@@ -2,6 +2,8 @@
 
 This walkthrough shows real CLI output captured from the open-source `angular-spotify` repository during a local proof run. That sample checkout is not bundled here.
 
+**2.4.0 setup preview:** use these commands only after that version is available on npm. To install published 2.2.0, follow the [versioned setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
+
 To try the same CLI flow, use Node.js 22 or newer and open a terminal in the repository you want to inspect. These commands target `codebase-context@2.4.0`; the CLI uses the current directory as the project root. MCP registration and project selection are covered in the [client setup guide](./client-setup.md).
 
 The saved output below is from an earlier CLI run, not from `2.4.0` or the commands shown here. The machine-specific repository root is omitted from the returned file path. This capture does not verify the current package or an MCP connection.
diff --git a/docs/review-context.md b/docs/review-context.md
index f1ae2e2..11c7700 100644
--- a/docs/review-context.md
+++ b/docs/review-context.md
@@ -4,6 +4,8 @@
 
 It is deliberately **not** an AI reviewer. It does not call an LLM, decide whether code is correct, or post comments. Its job is narrower and testable: compile the changed surface, stable diff signals, related codebase context, and current conventions into a versioned input for a reviewer or evaluation harness.
 
+**2.4.0 setup preview:** use the package command below only after that version is available on npm. To install published 2.2.0, follow the [versioned setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
+
 ## Why this exists
 
 A PR reviewer needs more than the patch, but dumping an entire repository into a model is expensive and hard to reproduce. The review-context path creates a clean boundary between:
diff --git a/tests/release-truth-surfaces.test.ts b/tests/release-truth-surfaces.test.ts
index c643dcf..7ec1419 100644
--- a/tests/release-truth-surfaces.test.ts
+++ b/tests/release-truth-surfaces.test.ts
@@ -125,4 +125,44 @@ describe('release truth surfaces', () => {
       'ref: ${{ github.event.inputs.tag || github.event.release.tag_name }}'
     );
   });
+
+  it('marks 2.4.0 commands as a setup preview before the first runnable command', () => {
+    const previewNotice = '**2.4.0 setup preview:**';
+    const currentVersionGuide =
+      'https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md';
+    const previewPages = [
+      ['docs/capabilities.md', '| **stdio** (default) |'],
+      ['docs/cli.md', 'CODEBASE_ROOT=/path/to/repo npx -y codebase-context@2.4.0 status'],
+      ['docs/demo.md', 'npx -y codebase-context@2.4.0 reindex'],
+      ['docs/review-context.md', 'pnpm build']
+    ] as const;
+
+    for (const [path, firstCommand] of previewPages) {
+      const page = readText(path);
+      const noticeIndex = page.indexOf(previewNotice);
+      const guideIndex = page.indexOf(currentVersionGuide);
+      const commandIndex = page.indexOf(firstCommand);
+
+      expect(
+        noticeIndex,
+        `${path} should include the current-version fallback`
+      ).toBeGreaterThanOrEqual(0);
+      expect(guideIndex, `${path} should link the published 2.2.0 setup`).toBeGreaterThan(
+        noticeIndex
+      );
+      expect(page.slice(noticeIndex, guideIndex)).toContain('available on npm');
+      expect(page.slice(noticeIndex, guideIndex)).toContain('published 2.2.0');
+      expect(commandIndex, `${path} should retain its first runnable command`).toBeGreaterThan(0);
+      expect(noticeIndex, `${path} should qualify commands before they appear`).toBeLessThan(
+        commandIndex
+      );
+    }
+  });
+
+  it('does not describe the unpublished 2.4.0 preview as current or published', () => {
+    const capabilities = readText('docs/capabilities.md');
+
+    expect(capabilities).not.toContain('what `codebase-context` ships today');
+    expect(capabilities).not.toContain('Published 2.4.0 has');
+  });
 });

From fb5911d0450e801310fd37b532646f28d89353f4 Mon Sep 17 00:00:00 2001
From: PatrickSys <rossellocolompatrick@gmail.com>
Date: Fri, 16 Oct 2026 18:39:45 +0200
Subject: [PATCH 6/6] Fix 2.4.0 setup notices

---
 README.md                            |  2 +-
 docs/capabilities.md                 |  2 +-
 docs/cli.md                          |  2 +-
 docs/client-setup.md                 |  2 +-
 docs/demo.md                         |  2 +-
 docs/review-context.md               |  2 +-
 tests/release-truth-surfaces.test.ts | 26 ++++++++++++++++++--------
 7 files changed, 24 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index c8f510d..a6ee760 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ Codebase Context gives coding agents a map of your repository through MCP, for d
 
 ## Set up your AI client
 
-**2.4.0 setup preview:** use these commands only after that version is available on npm. To install published 2.2.0, follow the [versioned setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
+**These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
 
 Use Node.js 22 or newer. Choose your coding tool and run its command once; the examples target the 2.4.0 release:
 
diff --git a/docs/capabilities.md b/docs/capabilities.md
index 4d57ec7..59806d6 100644
--- a/docs/capabilities.md
+++ b/docs/capabilities.md
@@ -2,7 +2,7 @@
 
 Technical reference for the 2.4.0 setup preview. The public product posture is map first, find second: the bounded conventions map is the first-call surface, and search narrows to the right local example after that. For the user-facing overview, see [README.md](../README.md).
 
-**2.4.0 setup preview:** use these commands only after that version is available on npm. To install published 2.2.0, follow the [versioned setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
+**These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
 
 ## Transport Modes
 
diff --git a/docs/cli.md b/docs/cli.md
index 21e0c53..88d5b96 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -10,7 +10,7 @@
 
 > Output depends on the repo you run it against. The examples below are illustrative (paths, counts, and detected frameworks will vary).
 >
-> **2.4.0 setup preview:** use these commands only after that version is available on npm. To install published 2.2.0, follow the [versioned setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
+> **These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
 >
 > These output examples come from an earlier CLI run; they were not captured from `2.4.0` and do not verify an MCP connection.
 >
diff --git a/docs/client-setup.md b/docs/client-setup.md
index 708ab77..3d47d49 100644
--- a/docs/client-setup.md
+++ b/docs/client-setup.md
@@ -1,6 +1,6 @@
 # Client Setup
 
-**2.4.0 setup preview:** use these commands only after that version is available on npm. To install published 2.2.0, follow the [versioned setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
+**These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
 
 Codebase Context runs as a local MCP server: a tool your AI editor or command-line client can call while it works. Register it without a fixed folder, then let the agent supply its current repository through the `project` tool parameter. These recipes target the 2.4.0 release.
 
diff --git a/docs/demo.md b/docs/demo.md
index 3c9c916..81d0021 100644
--- a/docs/demo.md
+++ b/docs/demo.md
@@ -2,7 +2,7 @@
 
 This walkthrough shows real CLI output captured from the open-source `angular-spotify` repository during a local proof run. That sample checkout is not bundled here.
 
-**2.4.0 setup preview:** use these commands only after that version is available on npm. To install published 2.2.0, follow the [versioned setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
+**These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
 
 To try the same CLI flow, use Node.js 22 or newer and open a terminal in the repository you want to inspect. These commands target `codebase-context@2.4.0`; the CLI uses the current directory as the project root. MCP registration and project selection are covered in the [client setup guide](./client-setup.md).
 
diff --git a/docs/review-context.md b/docs/review-context.md
index 11c7700..f21b3d6 100644
--- a/docs/review-context.md
+++ b/docs/review-context.md
@@ -4,7 +4,7 @@
 
 It is deliberately **not** an AI reviewer. It does not call an LLM, decide whether code is correct, or post comments. Its job is narrower and testable: compile the changed surface, stable diff signals, related codebase context, and current conventions into a versioned input for a reviewer or evaluation harness.
 
-**2.4.0 setup preview:** use the package command below only after that version is available on npm. To install published 2.2.0, follow the [versioned setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
+**These commands use 2.4.0.** If that version is not available on npm yet, use the published 2.2.0 [setup guide](https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md).
 
 ## Why this exists
 
diff --git a/tests/release-truth-surfaces.test.ts b/tests/release-truth-surfaces.test.ts
index 7ec1419..49d56d4 100644
--- a/tests/release-truth-surfaces.test.ts
+++ b/tests/release-truth-surfaces.test.ts
@@ -126,32 +126,42 @@ describe('release truth surfaces', () => {
     );
   });
 
-  it('marks 2.4.0 commands as a setup preview before the first runnable command', () => {
-    const previewNotice = '**2.4.0 setup preview:**';
+  it('keeps 2.4.0 setup guidance accurate before and after publication', () => {
+    const versionNotice = 'These commands use 2.4.0.';
+    const fallbackNotice = 'If that version is not available on npm yet, use the published 2.2.0';
     const currentVersionGuide =
       'https://github.com/PatrickSys/codebase-context/blob/10ba0a635ff73cd5c5b011ffd5b31e7ed4656c65/docs/client-setup.md';
-    const previewPages = [
+    const setupPages = [
+      [
+        'README.md',
+        'claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.4.0'
+      ],
+      [
+        'docs/client-setup.md',
+        'claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context@2.4.0'
+      ],
       ['docs/capabilities.md', '| **stdio** (default) |'],
       ['docs/cli.md', 'CODEBASE_ROOT=/path/to/repo npx -y codebase-context@2.4.0 status'],
       ['docs/demo.md', 'npx -y codebase-context@2.4.0 reindex'],
       ['docs/review-context.md', 'pnpm build']
     ] as const;
 
-    for (const [path, firstCommand] of previewPages) {
+    for (const [path, firstCommand] of setupPages) {
       const page = readText(path);
-      const noticeIndex = page.indexOf(previewNotice);
+      const noticeIndex = page.indexOf(versionNotice);
       const guideIndex = page.indexOf(currentVersionGuide);
       const commandIndex = page.indexOf(firstCommand);
 
       expect(
         noticeIndex,
-        `${path} should include the current-version fallback`
+        `${path} should explain the current-version fallback`
       ).toBeGreaterThanOrEqual(0);
       expect(guideIndex, `${path} should link the published 2.2.0 setup`).toBeGreaterThan(
         noticeIndex
       );
-      expect(page.slice(noticeIndex, guideIndex)).toContain('available on npm');
-      expect(page.slice(noticeIndex, guideIndex)).toContain('published 2.2.0');
+      expect(page.slice(noticeIndex, guideIndex)).toContain(fallbackNotice);
+      expect(page.slice(noticeIndex, guideIndex)).toContain('[setup guide](');
+      expect(page).not.toContain('**2.4.0 setup preview:**');
       expect(commandIndex, `${path} should retain its first runnable command`).toBeGreaterThan(0);
       expect(noticeIndex, `${path} should qualify commands before they appear`).toBeLessThan(
         commandIndex