docs: make setup instructions clear before and after the release

.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: 'Release tag to publish'
         required: true
-        default: 'v2.3.0'
+        type: string
 
 permissions:
   contents: read

README.md

@@ -2,39 +2,47 @@
 
 [![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.2.0` and do not require a project folder in your configuration:
+**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:
 
 ```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.
+> 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
 
-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.
+- 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.
+
+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:
 
 ```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 +52,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 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,32 +72,36 @@ 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. 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
 
 `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.
 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
-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 +157,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`.
+- 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.
 
 ## Reference

docs/capabilities.md

@@ -1,15 +1,17 @@
 # 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).
+
+**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
 
 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 +22,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 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
 
@@ -49,15 +52,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 [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
-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
@@ -273,6 +276,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:
@@ -301,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.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).
+- **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.