@levr-one/cli 0.11.2 → 0.11.4

package/README.md

@@ -23,7 +23,7 @@ replaces the `levr` bin from the deprecated `@levr-one/setup` package.
 ### Or run it without a global install
 
 ```bash
-npx @levr-one/cli --help
+npx @levr-one/cli@latest --help
 ```
 
 `npx` is right for one-shot use (`mcp add`, trying a command). Two things to
@@ -40,18 +40,22 @@ In scripts and CI, pass `--yes` — **in a terminal the prompt blocks until it i
 answered**, so an unattended run with a TTY hangs rather than failing:
 
 ```bash
-npx --yes @levr-one/cli push ./test-results.xml
+npx --yes @levr-one/cli@latest push ./test-results.xml
 ```
 
-Two things to get right:
+Three things to get right:
 
-- **Always `npx @levr-one/cli`, never `npx levr`.** npx treats the first
+- **Add `@latest`.** Without a version, npx runs any copy of `@levr-one/cli`
+  already installed on the machine, however old, and an old copy does not know
+  newer commands and flags (`No flag registered for --workspace`).
+- **Always `npx @levr-one/cli@latest`, never `npx levr`.** npx treats the first
   positional as a _package_ name, so `npx levr` would fetch and run whatever
   package is published under the unscoped name `levr` — which is not ours.
-- **npm's flags go before the package name.** `npx @levr-one/cli --yes` passes
+- **npm's flags go before the package name.** `npx @levr-one/cli@latest --yes` passes
   `--yes` to `levr`, not to npm.
 
-For reproducible CI, pin `@levr-one/cli` to a version you have validated.
+The examples here use `@latest`. For reproducible CI, replace it with a
+version you have validated, such as `@levr-one/cli@0.11.1`.
 
 ## Quick start
 
@@ -59,7 +63,7 @@ For reproducible CI, pin `@levr-one/cli` to a version you have validated.
 the client opens a browser to authorize the first time it connects:
 
 ```bash
-npx @levr-one/cli mcp add
+npx @levr-one/cli@latest mcp add
 ```
 
 **Pushing test results?** Authentication is all you need — log in once (or
@@ -82,40 +86,72 @@ levr mcp add --dry-run       # preview the changes without writing
 levr mcp add --client cursor,zed --yes   # non-interactive selection
 ```
 
-What it writes is **credential-free** — a `levr` server entry that connects
-via `mcp-remote`. No token or secret is stored; your client opens the browser
-to authorize with Levr on its first connection. After a run, restart the
-client(s) and authorize once.
+What it writes is **credential-free** — a `levr` server entry holding only
+the server's address. No token or secret is stored; your client opens the
+browser to authorize with Levr on its first connection. After a run, restart
+the client(s) and authorize once.
+
+Clients that speak HTTP MCP themselves (Claude Code, VS Code, Gemini CLI,
+Codex CLI, Grok Build, Antigravity) connect to the URL directly. Claude
+Desktop, Cursor, Windsurf and Zed get an entry that runs
+`npx -y mcp-remote <url>`, which connects on their behalf.
 
 **Supported clients:**
 
-| Client         | How it's configured                                                            |
-| -------------- | ------------------------------------------------------------------------------ |
-| Claude Desktop | config file (`claude_desktop_config.json`)                                     |
-| Claude Code    | prints the `claude mcp add --transport http levr <url>` command for you to run |
-| Cursor         | config file (`~/.cursor/mcp.json`)                                             |
-| Windsurf       | config file (`~/.codeium/windsurf/mcp_config.json`)                            |
-| Zed            | config file (`settings.json`, `context_servers`)                               |
-| VS Code, Codex | listed but not yet installable (coming soon)                                   |
+| Client                  | How it's configured                                                                                                              |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Claude Desktop          | config file (`claude_desktop_config.json`)                                                                                       |
+| Claude Code             | runs `claude mcp add --transport http --scope user levr <url>` for you (prints it instead when `claude` is not on your `PATH`) |
+| Cursor                  | config file (`~/.cursor/mcp.json`)                                                                                               |
+| Windsurf                | config file (`~/.codeium/windsurf/mcp_config.json`)                                                                              |
+| Zed                     | config file (`settings.json`, `context_servers`)                                                                                 |
+| VS Code                 | config file (`Code/User/mcp.json` in your VS Code settings folder; `.vscode/mcp.json` with `--scope project`)                    |
+| Gemini CLI              | config file (`~/.gemini/settings.json`)                                                                                          |
+| Codex CLI               | config file (`~/.codex/config.toml`, TOML)                                                                                       |
+| Grok Build              | config file (`~/.grok/config.toml`, TOML)                                                                                        |
+| Antigravity (CLI + IDE) | config file (`~/.gemini/config/mcp_config.json`)                                                                                 |
 
 Config edits are **safe and repeatable**: existing MCP servers and comments
-in your config files are preserved (jsonc-aware merge), and re-running is a
-no-op that reports "already set up".
+in your config files are preserved, and re-running reports "already set up".
+An entry of the same name that points at a different address is left alone
+and reported; pass `--replace` to switch it.
 
 **Flags:**
 
-| Flag              | Alias | Description                                           |
-| ----------------- | ----- | ----------------------------------------------------- |
-| `--client <id,…>` |       | Set up these client ids (comma-separated or repeated) |
-| `--all`           |       | Set up every detected, installable client             |
-| `--yes`           | `-y`  | Non-interactive; auto-select detected clients         |
-| `--dry-run`       |       | Show the changes without writing                      |
-| `--url <url>`     |       | MCP server URL (default derived from the API server)  |
+| Flag                             | Alias | Description                                                                         |
+| -------------------------------- | ----- | ----------------------------------------------------------------------------------- |
+| `--client <id,…>`                |       | Set up these client ids (comma-separated or repeated)                               |
+| `--all`                          |       | Set up every detected, installable client                                           |
+| `--yes`                          | `-y`  | Non-interactive; auto-select detected clients                                       |
+| `--dry-run`                      |       | Show the changes without writing                                                    |
+| `--scope <user\|project\|local>` |       | Where the entry lands: every project (default), this repo for everyone, or just you |
+| `--workspace <url_key\|name>`    |       | Pin the entry to one workspace (needs `levr auth login`)                            |
+| `--name <entry>`                 |       | Name of the client entry (default `levr`), to keep a second one beside it          |
+| `--replace`                      |       | Switch an existing entry of this name to the new address                            |
+| `--url <url>`                    |       | MCP server URL (default derived from the API server)                                |
 
 Runs non-interactively whenever `--all`, `--client`, or `--yes` is passed —
 or automatically when not attached to a terminal (CI). Unknown client ids and
 failed writes exit non-zero.
 
+### More than one workspace
+
+If your account is in more than one workspace, the plain MCP URL does not know
+which one you mean, and its tools reply that no workspace is selected. Connect
+each workspace by its own URL, `https://ai.levr.one/api/v1/mcp/w/<url_key>`:
+
+```bash
+levr auth login
+levr mcp add --workspace acme                   # pin the levr entry to acme
+levr mcp add --workspace beta --name levr-beta  # add a second entry beside it
+levr mcp add --workspace beta --replace         # or switch the entry to beta
+```
+
+Each entry lists every Levr tool once more. A URL for a workspace you are not
+in is refused with `403`; connect the plain URL and ask for `list_workspaces`
+to see the URLs you can use. Full guide:
+[levr CLI Overview › More than one workspace](https://doc.levr.one/cli/levr-cli-overview#more-than-one-workspace).
+
 ## Push test results
 
 ```bash
@@ -233,7 +269,7 @@ levr import ./cases.csv --team-id <uuid> --map "State=labels:state"
   env:
     LEVR_TOKEN: ${{ secrets.LEVR_TOKEN }}
     # LEVR_TEAM_ID is optional — server resolves from automation source or workspace default
-  run: npx --yes @levr-one/cli push ./test-results.xml
+  run: npx --yes @levr-one/cli@latest push ./test-results.xml
 ```
 
 ### GitLab CI
@@ -241,7 +277,7 @@ levr import ./cases.csv --team-id <uuid> --map "State=labels:state"
 ```yaml
 push-results:
   script:
-    - npx --yes @levr-one/cli push ./test-results.xml
+    - npx --yes @levr-one/cli@latest push ./test-results.xml
   variables:
     LEVR_TOKEN: $LEVR_TOKEN
 ```
@@ -250,13 +286,14 @@ push-results:
 
 ```groovy
 withEnv(["LEVR_TOKEN=${LEVR_TOKEN}"]) {
-  sh 'npx --yes @levr-one/cli push ./test-results.xml'
+  sh 'npx --yes @levr-one/cli@latest push ./test-results.xml'
 }
 ```
 
 ## Authentication
 
-Needed for `push` and `workspace` commands (`mcp add` needs none). Three modes:
+Needed for `push` and `workspace` commands, and for `mcp add --workspace`.
+Three modes:
 
 ### Interactive (browser) — default
 

package/dist/{addHandler-Dh4elBBV.js → addHandler-DC1U672-.js}

@@ -143,7 +143,10 @@ const CLAUDE_CODE_COMMAND = [
 	"{name}",
 	"{url}"
 ];
-/** `~/.claude.json` on every platform — read for detection, never written by us. */
+/**
+* `~/.claude.json` on every platform — read for detection, never written by us.
+* `~` is `$CLAUDE_CONFIG_DIR` when that is set (see `configDirEnv`).
+*/
 const CLAUDE_CODE_LOCATIONS = [
 	{
 		platform: "darwin",
@@ -232,6 +235,7 @@ const HARNESSES = [
 		docsUrl: "https://docs.anthropic.com/en/docs/claude-code/mcp",
 		verifiedVersion: UNVERIFIED_LEGACY,
 		verifiedOn: UNVERIFIED_LEGACY,
+		configDirEnv: "CLAUDE_CONFIG_DIR",
 		detectSignals: [
 			{
 				platform: "darwin",
@@ -275,7 +279,7 @@ const HARNESSES = [
 				installKind: "cli-command",
 				locations: CLAUDE_CODE_LOCATIONS,
 				command: CLAUDE_CODE_COMMAND,
-				cwdKeyedUnder: "projects"
+				projectKeyedUnder: "projects"
 			}
 		]
 	},
@@ -775,9 +779,20 @@ function defaultEnv() {
 		platform: process.platform,
 		homedir: homedir(),
 		pathVar: process.env.PATH ?? "",
-		cwd: process.cwd()
+		cwd: process.cwd(),
+		vars: process.env
 	};
 }
+/**
+* The directory `~` means for this harness's config paths and signals: the
+* harness's `configDirEnv` when that variable is set, else the home directory
+* (ENG-6696). A relative value resolves against `env.cwd`, the directory a
+* spawned client CLI runs in, so the probe and the client read one file.
+*/
+function configHome(harness, env) {
+	const dir = harness.configDirEnv ? env.vars?.[harness.configDirEnv] : void 0;
+	return dir ? resolve(env.cwd, dir) : env.homedir;
+}
 /** Expand a leading `~` / `~/…` to the given home directory. */
 function expandTilde(p, home) {
 	if (p === "~") return home;
@@ -807,7 +822,7 @@ function resolveConfigPath(harness, env, scope = defaultScope(harness)) {
 	if (def.projectPath) return join(resolveProjectRoot(env).root, ...def.projectPath.split("/"));
 	const loc = locationFor(harness, env.platform, scope);
 	if (!loc) return void 0;
-	return expandTilde(loc.configPath, env.homedir);
+	return expandTilde(loc.configPath, configHome(harness, env));
 }
 /**
 * Nearest ancestor of `cwd` containing `.git`, or `undefined`.
@@ -846,25 +861,75 @@ function resolveProjectRoot(env) {
 	};
 }
 /**
+* The key Claude Code files a `local`-scope entry under, in `projects[...]`,
+* for a client run from `env.cwd` (ENG-6696, observed on 2.1.296).
+*
+* It is the PROJECT, not the directory: from `repo/sub` the key is `repo`.
+* A linked git worktree keys to its MAIN checkout (the parent of the common
+* `.git`), a worktree of a bare repository to the bare directory, and a
+* submodule or `--separate-git-dir` checkout to its own work tree. Outside a
+* repository it is the directory itself. Always a real path, with `/`
+* separators on Windows (unverified there: drive-letter case). Claude reads
+* only this key, so an entry under any other key is invisible to it, and a
+* probe that looked elsewhere missed the entry and let `claude mcp add`
+* refuse.
+*/
+function projectKeyFor(env) {
+	return configKey(projectDir(env), env.platform);
+}
+/** Claude Code writes `projects` keys with `/` on Windows too. */
+function configKey(dir, platform) {
+	return platform === "win32" ? dir.replaceAll("\\", "/") : dir;
+}
+function projectDir(env) {
+	const cwd = realOrResolved(env.cwd);
+	const workTree = findRepoRoot(cwd);
+	if (!workTree) return cwd;
+	const dotGit = join(workTree, ".git");
+	let gitDir = dotGit;
+	try {
+		if (statSync(dotGit).isFile()) {
+			const m = /^gitdir:\s*([^\r\n]+)/.exec(readFileSync(dotGit, "utf8").trim());
+			if (!m?.[1]) return workTree;
+			gitDir = resolve(workTree, m[1].trim());
+		}
+	} catch {
+		return workTree;
+	}
+	const commonFile = readTextOrNull(join(gitDir, "commondir"));
+	if (commonFile === null) return workTree;
+	const common = realOrResolved(resolve(gitDir, commonFile.trim()));
+	if (!existsSync(common)) return workTree;
+	if (realOrResolved(dirname(gitDir)) !== join(common, "worktrees")) return workTree;
+	const back = readTextOrNull(join(gitDir, "gitdir"));
+	if (back === null || realOrResolved(dirname(resolve(gitDir, back.trim()))) !== workTree) return workTree;
+	if (basename(common) === ".git") return dirname(common);
+	return existsSync(join(common, ".git")) ? workTree : common;
+}
+function realOrResolved(p) {
+	try {
+		return realpathSync(p);
+	} catch {
+		return resolve(p);
+	}
+}
+/**
 * Where our server entry sits INSIDE a scope's config file.
 *
 * Usually `[<serverProperty>, 'levr']` at the top level. A scope declaring
-* `cwdKeyedUnder` nests one level deeper, keyed by the launch directory:
-* Claude Code's `local` scope lives at
-* `projects[<cwd>].mcpServers.levr` in `~/.claude.json`.
+* `projectKeyedUnder` nests one level deeper, under the project key: Claude
+* Code's `local` scope lives at `projects[<key>].mcpServers.levr` in
+* `~/.claude.json`, with `<key>` from {@link projectKeyFor}.
 *
-* `cwdKey` is passed in rather than read off the env because the key is
-* specifically the directory the CLIENT was launched in — which is NOT the
-* repo root, and callers should have to say which directory they mean.
 * Shared by detect and install so the two can never disagree about where an
 * entry lives.
 */
-function entryPathFor(harness, scope, cwdKey, serverName = DEFAULT_SERVER_NAME) {
+function entryPathFor(harness, scope, projectKey, serverName = DEFAULT_SERVER_NAME) {
 	const tail = [serverPropertyFor(harness, scope), serverName];
-	const nest = scopeDef(harness, scope)?.cwdKeyedUnder;
+	const nest = scopeDef(harness, scope)?.projectKeyedUnder;
 	return nest ? [
 		nest,
-		cwdKey,
+		projectKey,
 		...tail
 	] : tail;
 }
@@ -916,13 +981,14 @@ function collidingScope(harness, env, scope) {
 	if (!scopeDef(harness, scope)?.projectPath) return void 0;
 	const target = resolveConfigPath(harness, env, scope);
 	if (!target) return void 0;
-	const targetEntry = entryPathFor(harness, scope, env.cwd).join("\0");
+	const key = projectKeyFor(env);
+	const targetEntry = entryPathFor(harness, scope, key).join("\0");
 	for (const other of harness.scopes) {
 		if (other.scope === scope) continue;
 		const otherPath = resolveConfigPath(harness, env, other.scope);
 		if (!otherPath) continue;
 		if (!pathsResolveSame(target, otherPath, env.platform)) continue;
-		if (entryPathFor(harness, other.scope, env.cwd).join("\0") === targetEntry) return other.scope;
+		if (entryPathFor(harness, other.scope, key).join("\0") === targetEntry) return other.scope;
 	}
 }
 const WIN_EXTS = [
@@ -958,22 +1024,23 @@ function whichSync(bin, env) {
 	return whichPathSync(bin, env) !== void 0;
 }
 /** Does one `installSignals` entry match on this machine? Supports
-* `which:<bin>`, `~`-prefixed paths, and absolute (app-bundle) paths. */
-function signalMatches(signal, env) {
+* `which:<bin>`, `~`-prefixed paths, and absolute (app-bundle) paths. `home`
+* is what `~` means for the harness — see {@link configHome}. */
+function signalMatches(signal, env, home = env.homedir) {
 	if (signal.startsWith("which:")) return whichSync(signal.slice(6), env);
-	return existsSync(signal.startsWith("~") ? expandTilde(signal, env.homedir) : signal);
+	return existsSync(signal.startsWith("~") ? expandTilde(signal, home) : signal);
 }
 /**
 * The value our server key currently holds for this scope, or `undefined`.
 *
-* Presence alone is not enough for a `cli-command` scope: `claude mcp add` is
-* a no-op when the key exists, so telling "already correct" from "present but
-* pointing somewhere else" needs the value.
+* Presence alone is not enough for a `cli-command` scope: `claude mcp add`
+* refuses when the key exists and never updates its URL, so telling "already
+* correct" from "present but pointing somewhere else" needs the value.
 */
-function readServerEntry(harness, scope, configPath, cwdKey, parseJsonc, serverName = DEFAULT_SERVER_NAME) {
+function readServerEntry(harness, scope, configPath, projectKey, parseJsonc, serverName = DEFAULT_SERVER_NAME) {
 	const text = readTextOrNull(configPath);
 	if (!text) return void 0;
-	return getAtPath(parseJsonc(text), entryPathFor(harness, scope, cwdKey, serverName));
+	return getAtPath(parseJsonc(text), entryPathFor(harness, scope, projectKey, serverName));
 }
 /** Read a text file, or `null` if it doesn't exist / can't be read. */
 function readTextOrNull(path$1) {
@@ -1425,10 +1492,10 @@ function adapterFor(harness) {
 * not by which file is read — hence the entry path rather than a bare
 * top-level lookup.
 */
-function isServerConfigured(harness, scope, configPath, cwdKey) {
+function isServerConfigured(harness, scope, configPath, projectKey) {
 	const text = readTextOrNull(configPath);
 	if (!text) return false;
-	const read = adapterFor(harness).readAt(text, entryPathFor(harness, scope, cwdKey));
+	const read = adapterFor(harness).readAt(text, entryPathFor(harness, scope, projectKey));
 	return read.kind === "value" && read.value !== null;
 }
 function detectScope(harness, env, def) {
@@ -1441,13 +1508,13 @@ function detectScope(harness, env, def) {
 		installKind: def.installKind,
 		configPath: available ? configPath ?? "" : "",
 		available,
-		alreadyConfigured: available && configPath ? isServerConfigured(harness, def.scope, configPath, env.cwd) : false
+		alreadyConfigured: available && configPath ? isServerConfigured(harness, def.scope, configPath, projectKeyFor(env)) : false
 	};
 }
 function detectOne(harness, env) {
 	const scopes = harness.scopes.map((def) => detectScope(harness, env, def));
 	const available = scopes.some((s) => s.available);
-	const installed = detectSignalsFor(harness, env.platform).some((s) => signalMatches(s, env)) || scopes.some((s) => s.configPath !== "" && existsSync(s.configPath));
+	const installed = detectSignalsFor(harness, env.platform).some((s) => signalMatches(s, env, configHome(harness, env))) || scopes.some((s) => s.configPath !== "" && existsSync(s.configPath));
 	const fallback = scopes.find((s) => s.scope === defaultScope(harness));
 	return {
 		id: harness.id,
@@ -1472,6 +1539,21 @@ const COMMAND_TIMEOUT_MS = 3e4;
 /** Keep a failing client's diagnostics readable in a multi-client report. */
 const MAX_STDERR = 2e3;
 /**
+* The variables a client CLI is spawned with: the real environment minus every
+* catalog `configDirEnv`, then `env.vars` on top (ENG-6696). A config
+* directory therefore reaches the child only when the caller's env carries it
+* — the one the probe read — so `claude` never writes a file the installer
+* did not look at, while PATH and the rest still come through.
+*/
+function childVars(env) {
+	const vars = { ...process.env };
+	for (const h of HARNESSES) if (h.configDirEnv) delete vars[h.configDirEnv];
+	return {
+		...vars,
+		...env.vars
+	};
+}
+/**
 * Windows batch launchers (`.cmd` / `.bat`) cannot be spawned directly.
 *
 * Since the CVE-2024-27980 fix (Node 18.20.2 / 20.12.2 / 21.7.2),
@@ -1532,7 +1614,7 @@ function runHarnessCommandSync(argv, opts = {}) {
 			],
 			timeout: COMMAND_TIMEOUT_MS,
 			env: {
-				...process.env,
+				...childVars(env),
 				HOME: env.homedir,
 				USERPROFILE: env.homedir
 			},
@@ -1587,7 +1669,7 @@ function currentEntry(harness, env, scope, serverName) {
 	const configPath = resolveConfigPath(harness, env, scope);
 	if (!configPath) return { present: false };
 	const adapter = adapterFor(harness);
-	const entry = readServerEntry(harness, scope, configPath, env.cwd, (t) => {
+	const entry = readServerEntry(harness, scope, configPath, projectKeyFor(env), (t) => {
 		const read = adapter.readAt(t, []);
 		return read.kind === "value" ? read.value : void 0;
 	}, serverName);
@@ -1729,7 +1811,7 @@ function installHarnessSync(harness, mcpUrl, opts = {}) {
 	};
 	const { path: path$1 } = target;
 	const entryValue = buildServerEntry(harness, mcpUrl, scope, serverName)[serverName];
-	const modPath = entryPathFor(harness, scope, env.cwd, serverName);
+	const modPath = entryPathFor(harness, scope, projectKeyFor(env), serverName);
 	const adapter = adapterFor(harness);
 	const existing = readTextOrNull(path$1);
 	const baseText = existing && existing.trim() ? existing : adapter.empty;
@@ -2186,7 +2268,7 @@ function runNonInteractive(options, url, urlSource, deps) {
 	};
 }
 /** Why an install was refused, in the user's terms rather than the enum's. */
-function failureText(o, switchCommand) {
+function failureText(o, switchCommand, entryName) {
 	const r = o.result;
 	const harness = getHarness(o.id);
 	switch (r.reason) {
@@ -2198,10 +2280,23 @@ function failureText(o, switchCommand) {
 		case "write-failed": return `its config could not be written` + (r.detail ? ` (${r.detail})` : "") + `; check the file's permissions and re-run`;
 		case "unsupported-config-shape": return `its config could not be edited safely` + (r.detail ? ` (${r.detail})` : "") + `; fix the file or add the entry by hand`;
 		default:
-			if (r.commandError) return `\`${r.command}\` (${r.commandError})${restoreText(r)}`;
+			if (r.commandError) return `\`${r.command}\` (${r.commandError})${restoreText(r)}` + alreadyExistsHint(o, r.commandError, entryName);
 			return "no config location on this platform";
 	}
 }
+/**
+* The client's CLI refused because the entry already exists, in a config the
+* installer did not read — otherwise it would have reported already set up,
+* or a url-mismatch naming --replace. --replace cannot reach an entry it
+* cannot see, so the way out is another name, or removing that entry with the
+* client's own CLI (ENG-6696).
+*/
+function alreadyExistsHint(o, commandError, entryName) {
+	if (!/already exists/i.test(commandError)) return "";
+	const name = entryName ?? DEFAULT_SERVER_NAME;
+	const scope = /already exists in (user|project|local) config/i.exec(commandError)?.[1]?.toLowerCase() ?? o.result.scope;
+	return `; to keep it, add this one beside it with --name <other>; to switch it, remove it with ${o.id === "claude-code" ? `\`claude mcp remove --scope ${scope} ${name}\`` : "the client's own CLI"} and re-run`;
+}
 /** What happened to the entry a failed `--replace` removed (ENG-6300 D6). */
 function restoreText(r) {
 	if (r.restored === void 0) return "";
@@ -2209,13 +2304,13 @@ function restoreText(r) {
 	return `; the previous entry (${r.replacedUrl}) could NOT be restored` + (r.restoreError ? ` (${r.restoreError})` : "") + " — this client has no Levr entry of that name now";
 }
 /** One human-readable status line per outcome. */
-function outcomeLine(o, dryRun, switchCommand) {
+function outcomeLine(o, dryRun, switchCommand, entryName) {
 	const r = o.result;
 	const note = o.fallbackFrom ? ` [${o.fallbackFrom} scope unsupported — used ${r.scope}]` : "";
 	const where = r.path ? ` → ${r.path}` : "";
 	const backup = r.backupPath ? dryRun ? ` [original would be backed up to ${r.backupPath}]` : ` [original backed up to ${r.backupPath}]` : "";
 	const replaced = r.replacedUrl ? dryRun ? ` [would replace ${r.replacedUrl}]` : ` [replaced ${r.replacedUrl}]` : "";
-	if (!r.ok) return `${o.label}: failed — ${failureText(o, switchCommand)}`;
+	if (!r.ok) return `${o.label}: failed — ${failureText(o, switchCommand, entryName)}`;
 	if (r.alreadyConfigured) return `${o.label}: already set up (${r.scope})${where}${note}`;
 	if (r.command) {
 		if (r.executed) return `${o.label}: installed (${r.scope}) via \`${r.command}\`${replaced}${note}`;
@@ -2230,7 +2325,7 @@ function formatReport(report) {
 	const lines = [];
 	lines.push(`MCP URL: ${report.url} (${report.urlSource})`);
 	if (report.outcomes.length === 0) lines.push("No clients selected.");
-	else for (const o of report.outcomes) lines.push(outcomeLine(o, report.dryRun, report.switchCommand));
+	else for (const o of report.outcomes) lines.push(outcomeLine(o, report.dryRun, report.switchCommand, report.entryName));
 	if (report.unknownClients.length > 0) lines.push(`Unknown clients (skipped): ${report.unknownClients.join(", ")}`);
 	if (report.outcomes.some((o) => o.id === "claude-code" && o.result.ok)) lines.push(PLUGIN_TIP);
 	return lines.join("\n");
@@ -2240,7 +2335,7 @@ const PLUGIN_TIP = "Tip: the Levr plugin adds /levr:work, /levr:file and /levr:d
 /** Next-steps blurb after a run. */
 function nextStepsText(report) {
 	if (report.dryRun) return "Dry run — re-run without --dry-run to apply these changes.";
-	if (!report.outcomes.some((o) => o.result.wrote || o.result.executed || o.result.command)) return "Nothing to do.";
+	if (!report.outcomes.some((o) => o.result.ok && !o.result.alreadyConfigured && (o.result.wrote || o.result.executed || o.result.command))) return report.outcomes.some((o) => !o.result.ok) ? "Nothing was installed." : "Nothing to do.";
 	const lines = ["Next: restart the client(s) above — each will prompt you to authorize", "Levr once in the browser. Then ask it: \"What issues are assigned to me?\""];
 	if (report.outcomes.some((o) => o.result.scope === "project" && o.result.wrote)) lines.push("", "Project-scoped config was written into this repository — commit it to", "share the Levr MCP with everyone who checks it out.");
 	return lines.join("\n");
@@ -2380,7 +2475,8 @@ async function mcpAddHandler(flags) {
 	if (options.all || clients.length > 0 || options.yes || !process.stdout.isTTY) {
 		const report = {
 			...runNonInteractive(options, url, source, depsFor(entry)),
-			switchCommand: switchCommandFor(flags, urlKey)
+			switchCommand: switchCommandFor(flags, urlKey),
+			entryName: entry.serverName
 		};
 		this.process.stdout.write(`${formatReport(report)}\n`);
 		if (!isScopedMcpUrl(url) && servedBySessionApi(url)) {
@@ -2513,7 +2609,8 @@ async function interactive(ctx, dryRun, baseUrl, baseSource, flags, entry, resol
 		outcomes,
 		unknownClients: [],
 		dryRun,
-		switchCommand: switchCommandFor(flags, urlKey)
+		switchCommand: switchCommandFor(flags, urlKey),
+		entryName: entry.serverName
 	};
 	p.note(formatReport(report), "Results");
 	p.outro(nextStepsText(report));

package/dist/cli.js

@@ -135,7 +135,7 @@ or when not running in a terminal (CI). Config edits preserve existing
 servers and comments, and re-running is a no-op.
 
 Examples:
-  npx @levr-one/cli mcp add            # detect clients and pick interactively
+  npx @levr-one/cli@latest mcp add     # detect clients and pick interactively
   levr mcp add --all                   # set up every detected client
   levr mcp add --client cursor --yes
   levr mcp add --scope project         # commit the config to this repo
@@ -207,7 +207,7 @@ Examples:
 		aliases: { y: "yes" }
 	},
 	loader: async () => {
-		const { mcpAddHandler } = await import("./addHandler-Dh4elBBV.js");
+		const { mcpAddHandler } = await import("./addHandler-DC1U672-.js");
 		return mcpAddHandler;
 	}
 });
@@ -563,12 +563,17 @@ Examples:
 //#region src/commands/workspace/select.ts
 const selectCommand = buildCommand({
 	docs: {
-		brief: "Select a workspace",
+		brief: "Select the CLI workspace (MCP client configs are unchanged)",
 		fullDescription: `Select a workspace by ID.
 
-The selected workspace is used for all subsequent commands.
+The selected workspace is used for all subsequent levr commands.
 Use 'levr workspace list' to see available workspaces.
 
+It does not change MCP client configs: each AI client keeps using the
+workspace its MCP URL names. To point a client at a workspace, run
+'levr mcp add --workspace <url_key>' (add --replace to switch an existing
+entry).
+
 Requires JWT authentication (levr auth login).
 
 Examples:
@@ -869,7 +874,7 @@ Examples:
 
 //#endregion
 //#region package.json
-var version = "0.11.2";
+var version = "0.11.4";
 
 //#endregion
 //#region src/app.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levr-one/cli",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "The command-line interface for Levr",
   "type": "module",
   "license": "MIT",