feat(cli): interactive init P2 — clack, vendor CLIs, pinned MCP, update

README.md

@@ -4,7 +4,27 @@
 
 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
+## Install (candidate wizard)
+
+Use Node.js 22 or newer. The interactive `init` wizard is **not in published 2.2.0**; it ships in the unreleased candidate. To try it after release (or from a local `npm pack`):
+
+```bash
+npx -y codebase-context@latest init
+```
+
+[![Install MCP Server in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/link/mcp%2Finstall?name=codebase-context&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImNvZGViYXNlLWNvbnRleHQiXX0%3D) [![Install in VS Code](https://img.shields.io/badge/VS%20Code-Install%20MCP-blue?logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22:%22codebase-context%22,%22command%22:%22npx%22,%22args%22:%5B%22-y%22,%22codebase-context%22%5D%7D)
+
+The wizard detects installed tools, lets you choose clients (`@clack/prompts`), merges MCP config files under the project root, and supports `--dry-run` (print only, no writes). Default configs pin `codebase-context@<installed-version>`; use `--track-latest` for `@latest`.
+
+CI example (candidate):
+
+```bash
+npx -y codebase-context@latest init --yes --clients cursor --clients opencode --dry-run
+```
+
+For the **current npm release**, use the manual client commands below — not `init`.
+
+## Set up your AI client manually
 
 Use Node.js 22 or newer. These commands use the current npm release of Codebase Context:
 
@@ -21,14 +41,7 @@ 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, 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.
+This repository's `init` command is the supported setup path (see **Install** above). Registry metadata for future publishing lives in [`server.json`](./server.json) (not published to the MCP registry in this PR).
 
 Start a new agent session in your project, then ask:
 
@@ -64,10 +77,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                      | `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`            |
+| Cursor                      | `codebase-context init --clients cursor` (candidate) or add `.cursor/mcp.json` |
+| VS Code with GitHub Copilot | add `.vscode/mcp.json` manually (see client setup guide) |
 | GitHub Copilot CLI          | `copilot mcp add codebase-context -- npx -y codebase-context` |
-| Windsurf                    | `codebase-context init --client windsurf` or add `~/.codeium/windsurf/mcp_config.json` |
+| Windsurf                    | add `~/.codeium/windsurf/mcp_config.json` manually (not in `init` yet)        |
 
 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.
 

docs/client-setup.md

@@ -103,42 +103,32 @@ On October 6 the exact published `2.2.0` `npx` entrypoint was tested without a f
 
 ## Setup wizard in the unreleased candidate
 
-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:
+The interactive wizard is not in published 2.2.0. From your project root (candidate package or local build):
 
 ```bash
-# 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
-
-# Inspect selected source files and exclusions without writing client config.
-node /path/to/codebase-context/dist/index.js init --root /path/to/project --preview
+npx -y codebase-context@latest init
+npx -y codebase-context@latest init --yes --dry-run
+npx -y codebase-context@latest init --yes --clients codex --clients cursor --root /path/to/project
 ```
 
-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.
+With a TTY, omit `--yes` to pick clients (Space toggles, Enter confirms), review diffs, and confirm before writing. `--clients` is repeatable (`--client` is an alias; comma-separated values work). `--root` takes priority over `CODEBASE_ROOT` and the current folder. `--dry-run` prints previews and writes nothing. `--track-latest` writes `codebase-context@latest` instead of pinning the installed package version.
 
-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.
+Init merges project MCP configs for Claude Code (`.mcp.json`), Codex (`.codex/config.toml`), Cursor (`.cursor/mcp.json`), VS Code (`.vscode/mcp.json`), and OpenCode (`opencode.json`). Existing unrelated settings are preserved. A conflicting custom Codebase Context entry stops setup before writes. Restart clients and approve trust if asked.
 
-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.
+Record the wizard for docs with [VHS](https://github.com/charmbracelet/vhs) using [`docs/demo/install.tape`](./demo/install.tape); generate `install.gif` locally and avoid committing large binaries.
 
-New candidate indexes default to model-free search and do not initialize the optional model packages. Existing indexes keep their recorded mode; semantic indexing remains an explicit option.
+The older interactive HTTP wizard remains the behavior of published 2.2.0. A successful candidate wizard exit alone does not establish working client registration.
 
 ## 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", "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@latest", "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 reindex
 ```
 
-The older interactive HTTP wizard remains the behavior of published 2.2.0. A successful candidate wizard exit alone does not establish working client registration.
-
 ## Gemini CLI
 
 **Status:** Config written locally

docs/demo.md

@@ -6,6 +6,8 @@ These commands use the current npm release. The output shown below is historical
 
 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`; 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).
 
+Record the setup wizard with VHS: `vhs docs/demo/install.tape` (writes `docs/demo/install.gif`; keep large GIFs out of git).
+
 The saved output below is from an earlier CLI run, not from the current commands. 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

docs/demo/install.tape

@@ -0,0 +1,19 @@
+# Terminal recording for docs/demo/install.gif (generate locally; do not commit the GIF if large).
+Output docs/demo/install.gif
+Require vhs
+Set Shell bash
+Set FontSize 14
+Set Width 1200
+Set Height 700
+Set Theme "Catppuccin Mocha"
+
+Hide
+Type "cd /path/to/your/project"
+Enter
+Sleep 500ms
+Type "npx -y codebase-context@latest init --yes --dry-run"
+Enter
+Sleep 3s
+Show
+
+Sleep 2s

package.json

@@ -1,5 +1,6 @@
 {
   "name": "codebase-context",
+  "mcpName": "io.github.patricksys/codebase-context",
   "version": "2.3.0",
   "description": "Bounded conventions map and local-pattern discovery for AI coding agents. Local-first MCP server with AST-backed hybrid search.",
   "type": "module",
@@ -52,6 +53,7 @@
     "grammars",
     "README.md",
     "LICENSE",
+    "server.json",
     "docs/cli.md",
     "docs/capabilities.md",
     "docs/client-setup.md",
@@ -135,7 +137,7 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@inquirer/prompts": "^3.0.0",
+    "@clack/prompts": "^0.10.1",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@typescript-eslint/typescript-estree": "^8.51.0",
     "chokidar": "^4.0.3",