Beta: usable setup (combines #139 + #140, fixes 5 dogfood blockers)

README.md

@@ -12,13 +12,17 @@ Use Node.js 22 or newer. These commands use the current npm release of Codebase
 # Claude Code
 claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context
 
-# Codex CLI
+# Codex CLI (this is the Codex setup line)
 codex mcp add codebase-context -- npx -y codebase-context
 
 # OpenCode 1.x (keep the quoted separator on Windows)
 opencode mcp add codebase-context '--' npx -y codebase-context
 ```
 
+`npx -y codebase-context --version` prints the installed package version. `npx -y codebase-context map` builds a file index when the project does not have one, then prints the map. A low-confidence search includes a hint: the matches are weak, and that is not a finding that the code is absent.
+
+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.
+
 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, wait for indexing if needed, and open the relevant source files.

docs/cli.md

@@ -36,7 +36,7 @@ CODEBASE_CONTEXT_ASCII=1 npx -y codebase-context patterns
 
 ## Commands
 
-- `map` — conventions map: architecture layers, patterns, golden files
+- `map` — conventions map: architecture layers, patterns, golden files. Builds a file index first when the project does not have one, so a fresh checkout does not report 0 files
 - `metadata` — tech stack overview
 - `patterns` — team conventions + adoption/trends
 - `search --query <q>` — ranked results; add `--intent edit` for a preflight card
@@ -46,13 +46,14 @@ 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); `init` is an interactive HTTP setup wizard with the limitations described there
+- MCP client registration — `init` detects Claude Code, Codex, Cursor, and OpenCode and configures the selected tools together. See the [client setup guide](./client-setup.md). Codex setup line: `codex mcp add codebase-context -- npx -y codebase-context`
+- `--version` — print the installed package version
 
 ---
 
 ## First use
 
-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:
+Run these CLI commands from the project root. `map` indexes the project files when no index exists yet. `reindex` builds or refreshes the full index, including local embeddings; the first embedding run downloads a local model. Time depends on repository size, CPU and model.
 
 ```bash
 npx -y codebase-context reindex
@@ -69,7 +70,7 @@ npx -y codebase-context reindex
 npx -y codebase-context 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.
+The conventions map - run this first on an unfamiliar repo. If the project has no index, `map` builds the file index before it prints, so the file count is not stuck at 0. 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. That automatic index skips embeddings; run `reindex` when you want semantic search.
 
 Example output (truncated):
 
@@ -148,6 +149,8 @@ npx -y codebase-context reindex
 npx -y codebase-context search --query "file watcher" --intent edit --limit 3
 ```
 
+A low-confidence result includes a hint. The hint means the matches are weak. It is not a finding that the code is absent.
+
 Example output (truncated):
 
 ```text

docs/client-setup.md

@@ -103,23 +103,26 @@ On October 6 the exact published `2.2.0` `npx` entrypoint was tested without a f
 
 ## Interactive setup wizard
 
-> **Requires 2.4.0 (not yet published)**: The non-interactive `--client` and `--yes` flags are not available in published 2.2.0 (which runs an interactive HTTP wizard). These commands require the unpublished 2.4.0 release and will not work with the current npm release.
+> **Requires 2.4.0 (not yet published)**: One `init` command detects Claude Code, Codex, Cursor, and OpenCode and configures them together. Published 2.2.0 still runs an older interactive wizard. These commands require the unpublished 2.4.0 release and will not work with the current npm release.
 
-Run setup from the project you want the client to search:
+Run setup from the project you want the clients to search:
 
 ```bash
-# Claude Code (requires 2.4.0, not yet published)
-npx -y codebase-context@2.4.0 init --client claude-code --yes
-
-# Codex (requires 2.4.0, not yet published)
-npx -y codebase-context@2.4.0 init --client codex --yes
+# requires the unpublished 2.4.0
+npx -y codebase-context@2.4.0 init --yes
 ```
 
-Claude Code writes `.mcp.json`; Codex writes `.codex/config.toml`. Both configs start the installed server with the selected project. Setup uses the current folder unless `--root` or `CODEBASE_ROOT` selects another one; `--root` takes priority.
+That writes `.mcp.json` for Claude Code, `.codex/config.toml` for Codex, `.cursor/mcp.json` for Cursor, and `opencode.json` for OpenCode. Each file saves the Node binary that ran `init` and the package file from the npx cache, plus the project folder. The client starts that file directly and does not look up `npx` again.
+
+Codex setup line, including for the published package:
+
+```bash
+codex mcp add codebase-context -- npx -y codebase-context
+```
 
-`--yes` writes the config without prompts. In 2.2.0, running `init` without flags starts the older interactive wizard. Cursor and OpenCode still use HTTP and need a separately running server.
+Repeat `--client` to choose tools, for example `--client claude-code --client codex`. `--root` selects another folder and takes priority over `CODEBASE_ROOT`. With a terminal and without `--yes`, detected tools start checked.
 
-Existing settings are kept. If a different Codebase Context entry is already present, setup leaves the file unchanged and reports the conflict. Restart the client after setup and approve the server if asked. The first use builds the code index. Rerun setup if the Codebase Context installation moves, because the config uses its installed location.
+`--yes` writes the config without prompts. Existing settings are kept. A recognized generated launch is updated when you rerun setup, including when the npx cache path moves. A different Codebase Context entry is left unchanged and reported. Restart the client after setup and approve the server if asked. `map` builds the file index when one is missing.
 
 ## Optional fixed-folder setup and CLI preparation
 
@@ -131,7 +134,7 @@ To prepare the index separately, run from the project folder:
 npx -y codebase-context reindex
 ```
 
-The interactive wizard limitations described above are still present in the current source. A successful wizard exit alone does not establish working client registration.
+A successful setup exit alone does not establish working client registration.
 
 ## Gemini CLI