PatrickSys · Oct 30, 2026
diff --git a/README.md b/README.md
@@ -21,7 +21,14 @@ opencode mcp add codebase-context '--' npx -y codebase-context
 
 In the unreleased candidate, `--version` prints the installed package version and `map` builds a missing index before printing the map. A low-confidence search includes a hint that weak matches do not establish that code is absent. These additions require the built candidate; the unpinned commands above install published 2.2.0.
 
-This repository's `init` command detects Claude Code, Codex, Cursor, and OpenCode and writes a project config for each selected tool. The saved launch is the Node binary and the package file from the npx cache. That command is in this source and is not part of published 2.2.0. Until it is published, use the copy-paste lines above. The [client setup guide](./docs/client-setup.md) marks the unpublished command.
+This repository's `init` command detects Claude Code, Codex, Cursor, VS Code (Copilot), Windsurf, and OpenCode, then writes or merges each tool's MCP config in one pass. It follows the official VS Code `servers` and Windsurf user-config shapes (same pattern as the [@modelcontextprotocol/server-filesystem](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem) workspace examples). Use `--dry-run` to preview changes before writing.
+
+```bash
+npx codebase-context init --yes              # configure detected tools
+npx codebase-context init --dry-run --yes    # show Would create/update lines only
+```
+
+The saved launch is the Node binary and the package file from the npx cache. That command is in this source and is not part of published 2.2.0. Until it is published, use the copy-paste lines above. The [client setup guide](./docs/client-setup.md) marks the unpublished command.
 
 Start a new agent session in your project, then ask:
 
@@ -31,7 +38,7 @@ Replace `[feature]` with something you want to find. The first run downloads a l
 
 ### Planned for 2.4.0 (not yet published)
 
-The unreleased source candidate starts new indexes without a model download. Semantic embeddings are optional; existing indexes keep their recorded mode. Its setup wizard can configure Claude Code, Codex, Cursor and OpenCode using the Node binary and package file that ran setup. These changes are not in the current npm release.
+The unreleased source candidate starts new indexes without a model download. Semantic embeddings are optional; existing indexes keep their recorded mode. Its setup wizard configures Claude Code, Codex, Cursor, VS Code (Copilot), Windsurf, and OpenCode using the Node binary and package file that ran setup, with `--dry-run` to preview MCP config changes. These changes are not in the current npm release.
 
 - NestJS support from community contributor Aaron Olin. See the [analyzer details](./docs/capabilities.md#analyzers).
 - Better React/Next.js detection and a fix for reranker passage scoring.
@@ -57,10 +64,10 @@ Other clients use their own setup commands:
 | Client                      | Shortest current setup                                                       |
 | --------------------------- | ---------------------------------------------------------------------------- |
 | Gemini CLI                  | `gemini mcp add --scope user codebase-context npx -y codebase-context` |
-| Cursor                      | Add `.cursor/mcp.json`                                                       |
-| VS Code with GitHub Copilot | Add `.vscode/mcp.json`                                                       |
+| Cursor                      | `codebase-context init --client cursor` or add `.cursor/mcp.json`            |
+| VS Code with GitHub Copilot | `codebase-context init --client vscode` or add `.vscode/mcp.json`            |
 | GitHub Copilot CLI          | `copilot mcp add codebase-context -- npx -y codebase-context` |
-| Windsurf                    | Add `~/.codeium/windsurf/mcp_config.json`                                    |
+| Windsurf                    | `codebase-context init --client windsurf` or 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 and the interactive setup wizard's limitations.
 

diff --git a/docs/cli.md b/docs/cli.md
@@ -46,16 +46,17 @@ CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context 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 recipes in the [client setup guide](./client-setup.md). Published 2.2.0 has the older interactive HTTP wizard; the four-client wizard below requires the unreleased candidate.
+- MCP client registration — use the recipes in the [client setup guide](./client-setup.md). Published 2.2.0 has the older interactive HTTP wizard; the six-client wizard below requires the unreleased candidate.
 
 ## `init` in the unreleased candidate
 
-`init` detects Claude Code, Codex, Cursor and OpenCode, then configures the selected tools together. In a terminal, detected tools start selected; use Space to change the selection and Enter to apply it. Without a terminal, it configures all detected tools.
+`init` detects Claude Code, Codex, Cursor, VS Code (Copilot), Windsurf, and OpenCode, then configures the selected tools together. In a terminal, detected tools start selected; use Space to change the selection and Enter to apply it. Without a terminal, it configures all detected tools. Add `--dry-run` to print `Would create`, `Would update`, or `Unchanged` without writing files.
 
 ```powershell
 codebase-context init --help
 codebase-context init
 codebase-context init --yes
+codebase-context init --dry-run --yes
 codebase-context init --client codex --client cursor --root "C:\path\to\project"
 ```
 

diff --git a/docs/client-setup.md b/docs/client-setup.md
@@ -106,9 +106,12 @@ On October 6 the exact published `2.2.0` `npx` entrypoint was tested without a f
 The four-client wizard is not in published 2.2.0. From a built checkout or a locally installed candidate, run its actual entrypoint from the project you want to search:
 
 ```bash
-# Detect Claude Code, Codex, Cursor and OpenCode, then configure the detected clients.
+# Detect Claude Code, Codex, Cursor, VS Code, Windsurf, and OpenCode, then configure the detected clients.
 node /path/to/codebase-context/dist/index.js init --yes
 
+# Preview MCP config changes without writing files.
+node /path/to/codebase-context/dist/index.js init --dry-run --yes
+
 # Configure one client for an explicit project.
 node /path/to/codebase-context/dist/index.js init --client codex --root /path/to/project --yes
 
@@ -118,7 +121,7 @@ node /path/to/codebase-context/dist/index.js init --root /path/to/project --prev
 
 Replace the paths with the candidate installation and project folders. With an interactive terminal, omit `--yes` to select clients together. `--client` is repeatable. `--root` takes priority over `CODEBASE_ROOT` and the current folder.
 
-Claude Code uses `.mcp.json`, Codex uses `.codex/config.toml`, Cursor uses `.cursor/mcp.json`, and OpenCode uses `opencode.json`. Generated configs save the running Node binary, the actual package entrypoint and the project folder. If setup ran through `npx`, that entrypoint is in its package cache. Rerun setup if that installation or cache is removed or moved.
+Claude Code uses `.mcp.json`, Codex uses `.codex/config.toml`, Cursor uses `.cursor/mcp.json`, VS Code uses `.vscode/mcp.json` (`servers`), Windsurf uses `~/.codeium/windsurf/mcp_config.json`, and OpenCode uses `opencode.json`. Generated configs save the running Node binary, the actual package entrypoint and the project folder. If setup ran through `npx`, that entrypoint is in its package cache. Rerun setup if that installation or cache is removed or moved.
 
 Existing unrelated settings are preserved. A conflicting custom Codebase Context launch stops setup before selected config files are written. To replace a custom launch, remove only its Codebase Context entry from the client config, keep the other settings, and rerun setup. Restart the client and approve the server or project trust if asked. Config generation and SDK launch tests do not establish acceptance in each native client.