From 60645c451e6a8dd18f9983c5ade9afba6c057cbd Mon Sep 17 00:00:00 2001
From: chenchen <chenchen@simular.ai>
Date: Tue, 3 Nov 2026 07:47:25 +0800
Subject: [PATCH 1/5] cli: one-command install for box (connect, doctor,
 remove)

Adds @simular-ai/box (bin simular-box), which detects Claude Code, Codex,
Cursor, OpenCode, Hermes, OpenClaw and VS Code, and writes the box MCP server
into each app's native config. It merges without clobbering other entries,
backs up each file and is idempotent. Claude Code reuses the claude/ plugin.
Every app signs in with OAuth; Hermes and OpenClaw can use a personal key
(--auth key) kept in the app's .env, with the gateway restarted when it
changes. doctor checks config, endpoint and key; remove undoes connect.
BOX_MCP_URL overrides the single URL constant. A cli-v* tag publishes to npm
with provenance.

Closes #3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/release-cli.yml       |  36 +++
 .github/workflows/test-cli.yml          |  26 ++
 README.md                               |   2 +
 cli/.gitignore                          |   1 +
 cli/README.md                           |  69 +++++
 cli/bin/simular-box.js                  |  10 +
 cli/package-lock.json                   |  91 +++++++
 cli/package.json                        |  51 ++++
 cli/src/args.js                         |  38 +++
 cli/src/cli.js                          | 341 ++++++++++++++++++++++++
 cli/src/clients/claude-code.js          | 141 ++++++++++
 cli/src/clients/claude-desktop.js       |  36 +++
 cli/src/clients/codex.js                |  66 +++++
 cli/src/clients/cursor.js               |  16 ++
 cli/src/clients/hermes.js               | 116 ++++++++
 cli/src/clients/index.js                |  18 ++
 cli/src/clients/json-client.js          |  87 ++++++
 cli/src/clients/openclaw.js             | 165 ++++++++++++
 cli/src/clients/opencode.js             |  25 ++
 cli/src/clients/vscode.js               |  20 ++
 cli/src/constants.js                    |  43 +++
 cli/src/context.js                      |  67 +++++
 cli/src/formats.js                      | 235 ++++++++++++++++
 cli/src/fsutil.js                       |  70 +++++
 cli/src/probe.js                        |  97 +++++++
 cli/test/cli.test.js                    | 106 ++++++++
 cli/test/clients.test.js                | 202 ++++++++++++++
 cli/test/fixtures/broken.json           |   1 +
 cli/test/fixtures/codex.after.toml      |  12 +
 cli/test/fixtures/codex.before.toml     |  19 ++
 cli/test/fixtures/cursor.before.json    |   7 +
 cli/test/fixtures/hermes.before.yaml    |   7 +
 cli/test/fixtures/opencode.before.jsonc |   8 +
 cli/test/fixtures/vscode.before.json    |   6 +
 cli/test/fsutil.test.js                 |  39 +++
 cli/test/helpers.js                     |  81 ++++++
 36 files changed, 2355 insertions(+)
 create mode 100644 .github/workflows/release-cli.yml
 create mode 100644 .github/workflows/test-cli.yml
 create mode 100644 cli/.gitignore
 create mode 100644 cli/README.md
 create mode 100755 cli/bin/simular-box.js
 create mode 100644 cli/package-lock.json
 create mode 100644 cli/package.json
 create mode 100644 cli/src/args.js
 create mode 100644 cli/src/cli.js
 create mode 100644 cli/src/clients/claude-code.js
 create mode 100644 cli/src/clients/claude-desktop.js
 create mode 100644 cli/src/clients/codex.js
 create mode 100644 cli/src/clients/cursor.js
 create mode 100644 cli/src/clients/hermes.js
 create mode 100644 cli/src/clients/index.js
 create mode 100644 cli/src/clients/json-client.js
 create mode 100644 cli/src/clients/openclaw.js
 create mode 100644 cli/src/clients/opencode.js
 create mode 100644 cli/src/clients/vscode.js
 create mode 100644 cli/src/constants.js
 create mode 100644 cli/src/context.js
 create mode 100644 cli/src/formats.js
 create mode 100644 cli/src/fsutil.js
 create mode 100644 cli/src/probe.js
 create mode 100644 cli/test/cli.test.js
 create mode 100644 cli/test/clients.test.js
 create mode 100644 cli/test/fixtures/broken.json
 create mode 100644 cli/test/fixtures/codex.after.toml
 create mode 100644 cli/test/fixtures/codex.before.toml
 create mode 100644 cli/test/fixtures/cursor.before.json
 create mode 100644 cli/test/fixtures/hermes.before.yaml
 create mode 100644 cli/test/fixtures/opencode.before.jsonc
 create mode 100644 cli/test/fixtures/vscode.before.json
 create mode 100644 cli/test/fsutil.test.js
 create mode 100644 cli/test/helpers.js

diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml
new file mode 100644
index 0000000..2ab18ec
--- /dev/null
+++ b/.github/workflows/release-cli.yml
@@ -0,0 +1,36 @@
+name: Release CLI
+
+# Push a tag `cli-vX.Y.Z` that matches cli/package.json's version. The workflow tests the CLI and
+# publishes @simular-ai/box to npm with provenance, then creates a GitHub release.
+# Needs the repository secret NPM_TOKEN (an npm automation token with publish rights on @simular-ai).
+on:
+  push:
+    tags: ['cli-v*']
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write # npm provenance
+    defaults:
+      run:
+        working-directory: cli
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+      - name: Tag matches cli/package.json
+        run: test "cli-v$(node -p "require('./package.json').version")" = "$GITHUB_REF_NAME"
+      - run: npm ci
+      - run: npm test
+      - name: Publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --provenance --access public
+      - name: Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes "npx @simular-ai/box connect. See cli/README.md." --latest=false
diff --git a/.github/workflows/test-cli.yml b/.github/workflows/test-cli.yml
new file mode 100644
index 0000000..1cb5e76
--- /dev/null
+++ b/.github/workflows/test-cli.yml
@@ -0,0 +1,26 @@
+name: Test CLI
+
+on:
+  pull_request:
+    paths: ['cli/**', '.github/workflows/test-cli.yml']
+  push:
+    branches: [main]
+    paths: ['cli/**']
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        node: [18, 24]
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        working-directory: cli
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm ci
+      - run: npm test
diff --git a/README.md b/README.md
index f88db24..ca6b014 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,7 @@ Most agents need no plugin: add the MCP server `https://relay.simular.cloud/mcp`
 | --- | --- | --- | --- |
 | Claude Code and Cowork | [`claude/`](claude/) | OAuth, once in the browser | `/plugin marketplace add simular-ai/box-plugin`, then `/plugin install box@simular-box` |
 | DeepSeek Harness (dsh) | [`dsh/`](dsh/) | Personal key (`cb_...`) | [dsh/README.md](dsh/README.md) |
+| Any of Claude Code, Codex, Cursor, OpenCode, Hermes, OpenClaw, VS Code (and steps for Claude Desktop) | [`cli/`](cli/) | OAuth; personal key with `--auth key` for Hermes and OpenClaw | `npx @simular-ai/box connect` (check with `npx @simular-ai/box doctor`) |
 
 ## Adding an agent
 
@@ -17,3 +18,4 @@ Add a folder named after the agent with its own manifest, MCP config and, where
 
 - `claude/`: bump `version` in `claude/.claude-plugin/plugin.json`; Claude Code picks it up from the marketplace.
 - `dsh/`: bump `version` in `dsh/package.json`, then push a tag `dsh-vX.Y.Z`. The release workflow attaches `dsh-box.tgz`.
+- `cli/`: bump `version` in `cli/package.json`, then push a tag `cli-vX.Y.Z`. The release workflow tests it and publishes `@simular-ai/box` to npm with provenance (needs the `NPM_TOKEN` secret). When the box endpoint moves, change `DEFAULT_MCP_URL` in `cli/src/constants.js` and release.
diff --git a/cli/.gitignore b/cli/.gitignore
new file mode 100644
index 0000000..6b1d0bf
--- /dev/null
+++ b/cli/.gitignore
@@ -0,0 +1 @@
+LICENSE
diff --git a/cli/README.md b/cli/README.md
new file mode 100644
index 0000000..cacf868
--- /dev/null
+++ b/cli/README.md
@@ -0,0 +1,69 @@
+# @simular-ai/box
+
+Connect [box](https://box.simular.ai) to your AI apps in one command. box gives your AI agent a computer of its own: a cloud Linux desktop with Chrome and a shell, driven over MCP.
+
+```bash
+npx @simular-ai/box connect
+```
+
+The CLI finds the AI apps on this computer, asks which ones should use box, and adds the box MCP server (`https://relay.simular.cloud/mcp`) to each one in its own format. Other servers and settings in those files are left alone, each changed file gets a backup next to it (`*.box-backup-<time>`), and running it again changes nothing.
+
+```bash
+npx @simular-ai/box doctor     # is box set up right in each app? is the endpoint up? is the key valid?
+npx @simular-ai/box remove     # undo connect
+```
+
+The command is `simular-box` (`box` belongs to box.com's CLI), so after `npm i -g @simular-ai/box` it is `simular-box connect`.
+
+## Apps
+
+| App | `--client` | What connect does | Sign-in |
+| --- | --- | --- | --- |
+| Claude Code | `claude-code` | Installs the [`claude/`](../claude/) plugin (box server + box skill) with `claude plugin install box@simular-box`. With `BOX_MCP_URL` set, `claude mcp add --scope user --transport http box <url>` instead | OAuth: `/mcp` → box → Authenticate |
+| Codex | `codex` | Writes `[mcp_servers.box]` to `$CODEX_HOME/config.toml` (default `~/.codex`) | OAuth: `codex mcp login box` |
+| Cursor | `cursor` | Merges `mcpServers.box` into `~/.cursor/mcp.json` | OAuth: Settings → MCP → Login |
+| OpenCode | `opencode` | Merges `mcp.box` (`type: remote`) into `~/.config/opencode/opencode.json(c)` | OAuth: `opencode mcp auth box` |
+| Hermes Agent | `hermes` | Writes `mcp_servers.box` to `$HERMES_HOME/config.yaml` (default `~/.hermes`); restarts a running gateway | OAuth (`hermes mcp login box`) or `--auth key` |
+| OpenClaw | `openclaw` | `openclaw mcp set box …` with `transport: streamable-http`; restarts a running Gateway when the key changes | OAuth (`openclaw mcp login box`) or `--auth key` |
+| VS Code | `vscode` | Merges `servers.box` (`type: http`) into the user `mcp.json` | OAuth, when the server starts |
+| Claude Desktop | `claude-desktop` | Writes nothing: remote servers are connectors in the app. Prints the steps | OAuth in the app |
+
+Pick apps without prompts with `--client cursor,codex --yes`; `--yes` alone picks every app found. `--dry-run` shows what would change.
+
+## Sign-in
+
+Every app signs in with OAuth by default: the app opens a browser page, you sign in to box and click Approve. No key to copy.
+
+Hermes and OpenClaw often run around the clock on a server, where an expired OAuth sign-in waits for a person. For those, `--auth key` uses a personal key instead:
+
+```bash
+# create a key at https://box.simular.ai/keys, then:
+BOX_TOKEN=cb_... npx @simular-ai/box connect --client hermes,openclaw --auth key
+```
+
+Without `BOX_TOKEN`, an interactive run asks for the key with hidden input. The key is never accepted as a command-line argument and never printed. It goes only where the app reads secrets: `MCP_BOX_API_KEY` in `$HERMES_HOME/.env`, `BOX_TOKEN` in `~/.openclaw/.env` (both `0600`). The app config holds only a `${...}` reference to it. OpenClaw's Gateway reads `.env` only at start, and a running Hermes gateway keeps the old key, so connect restarts them when the key changes.
+
+## Doctor
+
+`doctor` checks, for each app it finds:
+
+- box is configured, points at the current URL, and no old `box-control` server is left
+- the endpoint answers an unauthenticated request with `401` and a `WWW-Authenticate` link to its sign-in metadata
+- a configured personal key is accepted (the key is sent to the box endpoint only, never printed)
+
+It prints a fix for each problem. `--json` prints a machine-readable report; the exit code is 1 when something needs fixing. OAuth sign-ins are stored by each app, so doctor can't see whether you've signed in.
+
+## Other endpoints
+
+`BOX_MCP_URL` points everything at another endpoint (for example staging): `BOX_MCP_URL=https://… npx @simular-ai/box connect`. When box's endpoint moves, a new CLI version changes the default and `connect` updates each app.
+
+## Development
+
+```bash
+cd cli && npm install && npm test
+node bin/simular-box.js connect --dry-run
+```
+
+Test against a temporary home, never your own configs: `HOME=$(mktemp -d) node bin/simular-box.js connect --client cursor --yes`.
+
+Release: bump `version` in `package.json`, then push a tag `cli-vX.Y.Z`. The release workflow runs the tests and publishes to npm with provenance.
diff --git a/cli/bin/simular-box.js b/cli/bin/simular-box.js
new file mode 100755
index 0000000..f1092da
--- /dev/null
+++ b/cli/bin/simular-box.js
@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js'
+
+main(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    process.stderr.write(`simular-box: ${err.message}\n`)
+    process.exit(1)
+  },
+)
diff --git a/cli/package-lock.json b/cli/package-lock.json
new file mode 100644
index 0000000..1b1255c
--- /dev/null
+++ b/cli/package-lock.json
@@ -0,0 +1,91 @@
+{
+  "name": "@simular-ai/box",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@simular-ai/box",
+      "version": "0.1.0",
+      "license": "MIT",
+      "dependencies": {
+        "@clack/prompts": "0.11.0",
+        "jsonc-parser": "3.3.1",
+        "smol-toml": "1.9.1",
+        "yaml": "2.9.1"
+      },
+      "bin": {
+        "simular-box": "bin/simular-box.js"
+      },
+      "engines": {
+        "node": ">=18.17"
+      }
+    },
+    "node_modules/@clack/core": {
+      "version": "0.5.0",
+      "resolved": "https://registry.npmjs.org/@clack/core/-/core-0.5.0.tgz",
+      "integrity": "sha512-p3y0FIOwaYRUPRcMO7+dlmLh8PSRcrjuTndsiA0WAFbWES0mLZlrjVoBRZ9DzkPFJZG6KGkJmoEAY0ZcVWTkow==",
+      "license": "MIT",
+      "dependencies": {
+        "picocolors": "^1.0.0",
+        "sisteransi": "^1.0.5"
+      }
+    },
+    "node_modules/@clack/prompts": {
+      "version": "0.11.0",
+      "resolved": "https://registry.npmjs.org/@clack/prompts/-/prompts-0.11.0.tgz",
+      "integrity": "sha512-pMN5FcrEw9hUkZA4f+zLlzivQSeQf5dRGJjSUbvVYDLvpKCdQx5OaknvKzgbtXOizhP+SJJJjqEbOe55uKKfAw==",
+      "license": "MIT",
+      "dependencies": {
+        "@clack/core": "0.5.0",
+        "picocolors": "^1.0.0",
+        "sisteransi": "^1.0.5"
+      }
+    },
+    "node_modules/jsonc-parser": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz",
+      "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==",
+      "license": "MIT"
+    },
+    "node_modules/picocolors": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
+      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
+      "license": "ISC"
+    },
+    "node_modules/sisteransi": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz",
+      "integrity": "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==",
+      "license": "MIT"
+    },
+    "node_modules/smol-toml": {
+      "version": "1.9.1",
+      "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.9.1.tgz",
+      "integrity": "sha512-j7WyPdf0CJoutMzMoPLF/bVXHtKZIT9Rb4eGeEbWw8X2t5oirjPgpL+OpaENZrILYaXqYwnVH+qgUwVbl+pUJQ==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">= 18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/cyyynthia"
+      }
+    },
+    "node_modules/yaml": {
+      "version": "2.9.1",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz",
+      "integrity": "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==",
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    }
+  }
+}
diff --git a/cli/package.json b/cli/package.json
new file mode 100644
index 0000000..2220e95
--- /dev/null
+++ b/cli/package.json
@@ -0,0 +1,51 @@
+{
+  "name": "@simular-ai/box",
+  "version": "0.1.0",
+  "description": "Connect box by Simular (a cloud computer your AI agent drives over MCP) to Claude Code, Codex, Cursor, OpenCode, Hermes, OpenClaw and more in one command.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "simular-box": "bin/simular-box.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepack": "cp ../LICENSE LICENSE"
+  },
+  "dependencies": {
+    "@clack/prompts": "0.11.0",
+    "jsonc-parser": "3.3.1",
+    "smol-toml": "1.9.1",
+    "yaml": "2.9.1"
+  },
+  "homepage": "https://box.simular.ai/install",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simular-ai/box-plugin.git",
+    "directory": "cli"
+  },
+  "bugs": "https://github.com/simular-ai/box-plugin/issues",
+  "keywords": [
+    "mcp",
+    "box",
+    "simular",
+    "computer-use",
+    "claude-code",
+    "codex",
+    "cursor",
+    "opencode",
+    "hermes",
+    "openclaw"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}
diff --git a/cli/src/args.js b/cli/src/args.js
new file mode 100644
index 0000000..711f2ee
--- /dev/null
+++ b/cli/src/args.js
@@ -0,0 +1,38 @@
+// Tiny argument parser: no dependency for a handful of flags.
+const BOOLEAN = new Set(['yes', 'json', 'dry-run', 'help', 'version', 'all'])
+const VALUE = new Set(['client', 'auth'])
+const ALIASES = { y: 'yes', h: 'help', v: 'version', c: 'client' }
+
+export function parseArgs(argv) {
+  const out = { command: null, flags: {}, rest: [] }
+  for (let i = 0; i < argv.length; i++) {
+    let arg = argv[i]
+    if (arg === '--') {
+      out.rest.push(...argv.slice(i + 1))
+      break
+    }
+    if (arg.startsWith('-')) {
+      let value
+      const eq = arg.indexOf('=')
+      if (eq !== -1) {
+        value = arg.slice(eq + 1)
+        arg = arg.slice(0, eq)
+      }
+      let name = arg.replace(/^--?/, '')
+      name = ALIASES[name] || name
+      if (BOOLEAN.has(name)) out.flags[name] = true
+      else if (VALUE.has(name)) {
+        if (value === undefined) value = argv[++i]
+        if (value === undefined || value.startsWith('-')) throw new Error(`--${name} needs a value`)
+        if (name === 'auth') {
+          if (value !== 'oauth' && value !== 'key') throw new Error('--auth must be oauth or key')
+          out.flags.auth = value
+        } else out.flags[name] = [...(out.flags[name] || []), ...value.split(',').map((s) => s.trim()).filter(Boolean)]
+      } else if (name === 'key' || name === 'token') {
+        throw new Error('pass the key in the BOX_TOKEN environment variable or at the prompt, never as an argument (it would end up in shell history)')
+      } else throw new Error(`unknown option ${arg}`)
+    } else if (!out.command) out.command = arg
+    else out.rest.push(arg)
+  }
+  return out
+}
diff --git a/cli/src/cli.js b/cli/src/cli.js
new file mode 100644
index 0000000..90961a7
--- /dev/null
+++ b/cli/src/cli.js
@@ -0,0 +1,341 @@
+import { createRequire } from 'node:module'
+import * as p from '@clack/prompts'
+import { parseArgs } from './args.js'
+import { createContext } from './context.js'
+import { CLIENTS, findClient } from './clients/index.js'
+import { DEFAULT_MCP_URL, KEY_ENV, KEYS_URL, WATCH_URL, INSTALL_URL, SUPPORT_EMAIL, looksLikeKey } from './constants.js'
+import { probeEndpoint, checkKey } from './probe.js'
+
+const VERSION = createRequire(import.meta.url)('../package.json').version
+
+const HELP = `simular-box ${VERSION}: connect box (a cloud computer for your AI agent) to your AI apps.
+
+Usage:
+  npx @simular-ai/box connect [--client <ids>] [--auth oauth|key] [--yes] [--dry-run]
+  npx @simular-ai/box doctor  [--client <ids>] [--json]
+  npx @simular-ai/box remove  [--client <ids>] [--yes] [--dry-run]
+
+Clients: ${CLIENTS.map((c) => c.id).join(', ')}
+
+Options:
+  -c, --client <ids>  Comma-separated client ids (default: pick from the detected ones)
+      --auth key      Hermes and OpenClaw: use a personal key instead of OAuth (for
+                      always-on servers with no browser). Other apps always use OAuth.
+  -y, --yes           Don't ask; with no --client, use every detected client
+      --dry-run       Show what would change without writing anything
+      --json          doctor: machine-readable output
+
+Sign-in: every app signs in with OAuth in the browser by default (no key). With --auth key, the key
+comes from ${KEY_ENV} or a hidden prompt (create one at ${KEYS_URL}); it is never accepted as an
+argument and never printed.
+Set BOX_MCP_URL to use another box endpoint (default ${DEFAULT_MCP_URL}).
+`
+
+export async function main(argv, { env = process.env, stdout = process.stdout, isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY) } = {}) {
+  const args = parseArgs(argv)
+  if (args.flags.version) {
+    stdout.write(`${VERSION}\n`)
+    return 0
+  }
+  if (args.flags.help || !args.command || args.command === 'help') {
+    stdout.write(HELP)
+    return args.command || args.flags.help ? 0 : 1
+  }
+  const ctx = createContext({ env, dryRun: Boolean(args.flags['dry-run']) })
+  const interactive = isTTY && !args.flags.yes && !args.flags.json
+  switch (args.command) {
+    case 'connect':
+    case 'add':
+    case 'install':
+      return connect(ctx, args.flags, { interactive, env, isTTY })
+    case 'doctor':
+    case 'status':
+      return doctor(ctx, args.flags, { stdout })
+    case 'remove':
+    case 'uninstall':
+      return remove(ctx, args.flags, { interactive })
+    default:
+      throw new Error(`unknown command "${args.command}"; run with --help`)
+  }
+}
+
+function selectedFromFlags(flags) {
+  return (flags.client || []).map((id) => {
+    const c = findClient(id)
+    if (!c) throw new Error(`unknown client "${id}"; known: ${CLIENTS.map((x) => x.id).join(', ')}`)
+    return c
+  })
+}
+
+function detectAll(ctx) {
+  return CLIENTS.map((client) => ({ client, detected: safe(() => client.detect(ctx), { installed: false }) }))
+}
+
+function safe(fn, fallback) {
+  try {
+    return fn()
+  } catch {
+    return fallback
+  }
+}
+
+function cancelled(value) {
+  if (p.isCancel(value)) {
+    p.cancel('Nothing changed.')
+    return true
+  }
+  return false
+}
+
+async function chooseClients(ctx, flags, { interactive, verb }) {
+  const explicit = selectedFromFlags(flags)
+  if (explicit.length) return explicit
+  const found = detectAll(ctx).filter((d) => d.detected.installed)
+  if (!found.length) {
+    p.log.warn(`No supported AI apps found. Supported: ${CLIENTS.map((c) => c.name).join(', ')}.`)
+    p.log.info(`Install one, or pick one anyway with --client <id>. Manual steps: ${INSTALL_URL}`)
+    return []
+  }
+  if (!interactive) {
+    if (!flags.yes) throw new Error(`no --client given; pass --client ${found.map((d) => d.client.id).join(',')} or --yes for all detected`)
+    return found.map((d) => d.client)
+  }
+  const picked = await p.multiselect({
+    message: `Which apps should ${verb} box? (space to toggle, enter to confirm)`,
+    options: found.map(({ client, detected }) => ({
+      value: client.id,
+      label: client.name,
+      hint: `${client.manual ? 'shows the steps' : client.supportsKey ? 'OAuth or personal key' : 'sign in in the browser'}${detected.cliMissing ? '; CLI not on PATH' : ''}`,
+    })),
+    initialValues: found.map((d) => d.client.id),
+    required: true,
+  })
+  if (cancelled(picked)) return null
+  return picked.map(findClient)
+}
+
+async function chooseModes(clients, flags, { interactive }) {
+  const modes = {}
+  for (const c of clients) modes[c.id] = c.auth === 'key' ? 'key' : 'oauth'
+  const flexible = clients.filter((c) => c.supportsKey)
+  if (!flexible.length) return modes
+  if (flags.auth) {
+    for (const c of flexible) modes[c.id] = flags.auth
+    return modes
+  }
+  if (!interactive) return modes
+  for (const c of flexible) {
+    const choice = await p.select({
+      message: `How should ${c.name} sign in to box?`,
+      options: [
+        { value: 'oauth', label: 'Sign in in the browser (OAuth)', hint: 'desktop with a browser' },
+        { value: 'key', label: 'Personal key (cb_...)', hint: 'always-on server; OAuth sign-ins expire and need a person' },
+      ],
+      initialValue: 'oauth',
+    })
+    if (cancelled(choice)) return null
+    modes[c.id] = choice
+  }
+  return modes
+}
+
+async function getKey(ctx, clients, { interactive, env }) {
+  const fromEnv = (env[KEY_ENV] || '').trim()
+  if (fromEnv) {
+    if (!looksLikeKey(fromEnv)) throw new Error(`${KEY_ENV} is set but does not look like a box personal key (cb_...)`)
+    return fromEnv
+  }
+  // Re-runs keep the key a client already has.
+  const missing = clients.filter((c) => !safe(() => c.status(ctx), {}).keyConfigured)
+  if (!missing.length) return null
+  if (!interactive) {
+    throw new Error(`${missing.map((c) => c.name).join(', ')} sign in with a personal key. Create one at ${KEYS_URL} and run again with ${KEY_ENV}=cb_... in the environment`)
+  }
+  p.log.info(`${missing.map((c) => c.name).join(', ')} can't sign in in the browser, so ${missing.length > 1 ? 'they use' : 'it uses'} a personal key.\nCreate one at ${KEYS_URL} (Create key under Personal keys; it is shown once).`)
+  const key = await p.password({
+    message: 'Paste the key (cb_...)',
+    mask: '*',
+    validate: (v) => (looksLikeKey(v) ? undefined : 'A box personal key starts with cb_'),
+  })
+  if (cancelled(key)) return undefined
+  return key.trim()
+}
+
+async function connect(ctx, flags, { interactive, env, isTTY }) {
+  p.intro(`box ${ctx.dryRun ? '(dry run) ' : ''}-> ${ctx.url}`)
+  const clients = await chooseClients(ctx, flags, { interactive, verb: 'use' })
+  if (!clients?.length) return clients === null ? 1 : 0
+  const modes = await chooseModes(clients, flags, { interactive })
+  if (!modes) return 1
+  const keyClients = clients.filter((c) => modes[c.id] === 'key')
+  let key = null
+  if (keyClients.length) {
+    key = await getKey(ctx, keyClients, { interactive, env })
+    if (key === undefined) return 1
+  }
+  let failed = 0
+  const next = []
+  for (const client of clients) {
+    // The spinner draws with escape codes; in logs and CI print plain lines instead.
+    const spin = isTTY ? p.spinner() : { start() {}, stop: (msg, code) => (code ? p.log.error(msg) : p.log.success(msg)) }
+    spin.start(`${client.name}`)
+    try {
+      const res = await client.connect(ctx, { key, mode: modes[client.id] })
+      spin.stop(`${client.name}: ${res.actions.length ? res.actions.join('; ') : 'already set up'}`)
+      for (const b of res.backups || []) p.log.message(`  backup: ${b}`)
+      for (const w of res.warnings || []) p.log.warn(`  ${w}`)
+      for (const n of res.next || []) next.push(`${client.name}: ${n}`)
+    } catch (err) {
+      failed++
+      spin.stop(`${client.name}: failed`, 1)
+      p.log.error(`  ${err.message}`)
+    }
+  }
+  if (next.length) p.note(next.join('\n'), 'Next')
+  p.outro(`Watch your box live: ${WATCH_URL}  |  Keys and connected apps: ${KEYS_URL}  |  Check: npx @simular-ai/box doctor`)
+  return failed ? 1 : 0
+}
+
+async function remove(ctx, flags, { interactive }) {
+  p.intro(`Remove box ${ctx.dryRun ? '(dry run)' : ''}`)
+  let clients = selectedFromFlags(flags)
+  if (!clients.length) {
+    const configured = detectAll(ctx)
+      .filter((d) => d.detected.installed)
+      .map((d) => d.client)
+      .filter((c) => {
+        const s = safe(() => c.status(ctx), null)
+        return s && (s.entries.length || s.legacy.length || s.keyConfigured)
+      })
+    if (!configured.length) {
+      p.outro('box is not set up in any detected app.')
+      return 0
+    }
+    if (interactive) {
+      const picked = await p.multiselect({
+        message: 'Remove box from which apps?',
+        options: configured.map((c) => ({ value: c.id, label: c.name })),
+        initialValues: configured.map((c) => c.id),
+        required: true,
+      })
+      if (cancelled(picked)) return 1
+      clients = picked.map(findClient)
+    } else if (flags.yes) clients = configured
+    else throw new Error(`no --client given; pass --client ${configured.map((c) => c.id).join(',')} or --yes`)
+  }
+  let failed = 0
+  for (const client of clients) {
+    try {
+      const res = await client.remove(ctx)
+      p.log.success(`${client.name}: ${res.actions.length ? res.actions.join('; ') : 'nothing to remove'}`)
+      for (const b of res.backups || []) p.log.message(`  backup: ${b}`)
+      for (const n of res.next || []) p.log.info(`  ${n}`)
+    } catch (err) {
+      failed++
+      p.log.error(`${client.name}: ${err.message}`)
+    }
+  }
+  p.outro(`To revoke a key or a signed-in app, open ${KEYS_URL}.`)
+  return failed ? 1 : 0
+}
+
+export async function runDoctor(ctx, flags, { probe = probeEndpoint, check = checkKey } = {}) {
+  const report = { url: ctx.url, defaultUrl: DEFAULT_MCP_URL, endpoint: null, clients: [] }
+  report.endpoint = await probe(ctx.url)
+  const explicit = selectedFromFlags(flags)
+  const rows = explicit.length ? explicit.map((client) => ({ client, detected: safe(() => client.detect(ctx), { installed: false }) })) : detectAll(ctx).filter((d) => d.detected.installed)
+  for (const { client, detected } of rows) {
+    const row = { id: client.id, name: client.name, auth: client.auth, installed: detected.installed, configured: false, entries: [], problems: [], fixes: [] }
+    report.clients.push(row)
+    let st
+    try {
+      st = client.status(ctx)
+    } catch (err) {
+      row.problems.push(`cannot read config: ${err.message}`)
+      row.fixes.push(`fix or move aside ${client.configLocation(ctx)}, then: npx @simular-ai/box connect --client ${client.id}`)
+      continue
+    }
+    if (st.manual) {
+      row.manual = true
+      row.problems = []
+      row.fixes = []
+      row.notes = [`can't be checked from here: add or check the box connector in ${client.configLocation(ctx)} (URL ${ctx.url})`]
+      row.ok = true
+      continue
+    }
+    row.entries = st.entries.map(({ where, url, enabled }) => ({ where, url: url || null, enabled: enabled !== false }))
+    row.configured = st.entries.length > 0
+    const keyMode = st.entries.some((e) => e.mode === 'key')
+    const fix = `npx @simular-ai/box connect --client ${client.id}${keyMode ? ' --auth key' : ''}`
+    if (!row.configured) {
+      row.problems.push('box is not configured')
+      row.fixes.push(fix)
+    }
+    for (const e of st.entries) {
+      if (e.url && e.url !== ctx.url) {
+        row.problems.push(`${e.where} points at ${e.url}, not ${ctx.url}`)
+        row.fixes.push(fix)
+      }
+      if (e.enabled === false) {
+        row.problems.push(`${e.where} is disabled`)
+        row.fixes.push(fix)
+      }
+    }
+    if (st.entries.length > 1) row.problems.push(`box is configured ${st.entries.length} times; the app may show it twice`)
+    if (st.legacy.length) {
+      row.problems.push(`old server ${st.legacy.join(', ')} is still configured`)
+      row.fixes.push(fix)
+    }
+    for (const w of st.warnings || []) row.problems.push(w)
+    for (const f of st.fixes || []) row.fixes.push(f)
+    if (keyMode || client.auth === 'key' || st.key) {
+      if (!st.key) {
+        row.key = { configured: false }
+        if (row.configured) {
+          row.problems.push('no personal key is configured')
+          row.fixes.push(`create a key at ${KEYS_URL}, then: ${KEY_ENV}=cb_... npx @simular-ai/box connect --client ${client.id} --auth key`)
+        }
+      } else if (report.endpoint.ok || report.endpoint.status) {
+        const r = await check(ctx.url, st.key)
+        row.key = { configured: true, valid: r.valid, status: r.status }
+        if (r.valid === false) {
+          row.problems.push(`the configured key was rejected (${r.error})`)
+          row.fixes.push(`create a new key at ${KEYS_URL}, then: ${KEY_ENV}=cb_... npx @simular-ai/box connect --client ${client.id} --auth key`)
+        } else if (r.valid === null) row.problems.push(`could not check the key: ${r.error}`)
+      } else row.key = { configured: true, valid: null }
+    }
+    row.fixes = [...new Set(row.fixes)]
+    row.ok = row.problems.length === 0
+  }
+  report.ok = report.endpoint.ok && report.clients.every((c) => c.ok)
+  return report
+}
+
+async function doctor(ctx, flags, { stdout }) {
+  const report = await runDoctor(ctx, flags)
+  if (flags.json) {
+    stdout.write(JSON.stringify(report, null, 2) + '\n')
+    return report.ok ? 0 : 1
+  }
+  p.intro('box doctor')
+  if (ctx.url !== DEFAULT_MCP_URL) p.log.info(`BOX_MCP_URL is set: checking ${ctx.url}`)
+  const ep = report.endpoint
+  if (ep.ok) p.log.success(`Endpoint ${ep.url} is up (401 + sign-in metadata, authorization server ${ep.authorizationServer})`)
+  else p.log.error(`Endpoint: ${ep.error}. Check your network or proxy; status: https://box.simular.ai`)
+  if (!report.clients.length) p.log.warn('No supported AI apps found.')
+  for (const c of report.clients) {
+    const lines = []
+    for (const e of c.entries) lines.push(`${e.where} -> ${e.url || '(url unknown)'}`)
+    if (c.key) lines.push(`personal key: ${c.key.configured ? (c.key.valid === true ? 'valid' : c.key.valid === false ? 'rejected' : 'not checked') : 'none'}`)
+    for (const pr of c.problems) lines.push(`problem: ${pr}`)
+    for (const f of c.fixes) lines.push(`fix: ${f}`)
+    for (const n of c.notes || []) lines.push(n)
+    const how = c.manual ? 'connector in the app' : c.key ? 'personal key' : 'OAuth'
+    const msg = `${c.name} (${how})\n${lines.map((l) => `  ${l}`).join('\n')}`
+    if (c.ok) p.log.success(msg)
+    else p.log.warn(msg)
+  }
+  if (report.clients.some((c) => !c.manual && !c.key)) p.log.info('OAuth sign-ins are kept by each app, so doctor cannot see them: if box asks you to sign in, do it in that app.')
+  p.outro(report.ok ? 'All good.' : `Something needs fixing (above). Help: ${SUPPORT_EMAIL}`)
+  return report.ok ? 0 : 1
+}
diff --git a/cli/src/clients/claude-code.js b/cli/src/clients/claude-code.js
new file mode 100644
index 0000000..3e192dc
--- /dev/null
+++ b/cli/src/clients/claude-code.js
@@ -0,0 +1,141 @@
+// Claude Code. Uses Claude Code's own CLI, never edits ~/.claude.json directly.
+// Default URL: installs this repo's claude/ plugin (box MCP server + the box skill) from the
+// `simular-box` marketplace. With BOX_MCP_URL set, the plugin's pinned URL would be wrong, so a
+// user-scope server is added with `claude mcp add` instead.
+// Docs: https://code.claude.com/docs/en/mcp , https://code.claude.com/docs/en/plugins
+import fs from 'node:fs'
+import path from 'node:path'
+import { DEFAULT_MCP_URL, LEGACY_SERVER_NAMES, SERVER_NAME } from '../constants.js'
+
+const MARKETPLACE_SOURCE = 'simular-ai/box-plugin'
+const MARKETPLACE = 'simular-box'
+const PLUGIN = `box@${MARKETPLACE}`
+
+function configDir(ctx) {
+  return ctx.env.CLAUDE_CONFIG_DIR || path.join(ctx.home, '.claude')
+}
+
+function userConfigFile(ctx) {
+  return ctx.env.CLAUDE_CONFIG_DIR ? path.join(ctx.env.CLAUDE_CONFIG_DIR, '.claude.json') : path.join(ctx.home, '.claude.json')
+}
+
+function readUserServers(ctx) {
+  try {
+    return JSON.parse(fs.readFileSync(userConfigFile(ctx), 'utf8')).mcpServers || {}
+  } catch {
+    return {}
+  }
+}
+
+function pluginState(ctx) {
+  const res = ctx.run('claude', ['plugin', 'list', '--json'])
+  if (res.status !== 0) return null
+  try {
+    return JSON.parse(res.stdout).find((p) => p.id === PLUGIN) || null
+  } catch {
+    return null
+  }
+}
+
+function must(res, what) {
+  if (res.status !== 0) throw new Error(`${what} failed: ${(res.stderr || res.stdout).trim().split('\n').pop()}`)
+}
+
+export default {
+  id: 'claude-code',
+  name: 'Claude Code',
+  auth: 'oauth',
+
+  detect(ctx) {
+    if (ctx.which('claude')) return { installed: true, via: 'claude on PATH' }
+    if (fs.existsSync(configDir(ctx))) return { installed: true, via: configDir(ctx), cliMissing: true }
+    return { installed: false }
+  },
+
+  configLocation(ctx) {
+    return userConfigFile(ctx)
+  },
+
+  status(ctx) {
+    const user = readUserServers(ctx)
+    const plugin = ctx.which('claude') ? pluginState(ctx) : null
+    const entries = []
+    // A disabled plugin next to a user-scope server is how connect sets up a BOX_MCP_URL override.
+    if (plugin && (plugin.enabled || !user[SERVER_NAME])) {
+      entries.push({ where: `plugin ${PLUGIN}${plugin.enabled ? '' : ' (disabled)'}`, url: plugin.mcpServers?.box?.url, enabled: plugin.enabled })
+    }
+    if (user[SERVER_NAME]) entries.push({ where: `user scope in ${userConfigFile(ctx)}`, url: user[SERVER_NAME].url, enabled: true })
+    const legacy = LEGACY_SERVER_NAMES.filter((n) => user[n])
+    return { entries, legacy, keyConfigured: false }
+  },
+
+  connect(ctx) {
+    if (!ctx.which('claude')) throw new Error('the `claude` command is not on PATH; install Claude Code first (https://code.claude.com)')
+    const actions = []
+    const user = readUserServers(ctx)
+    for (const name of LEGACY_SERVER_NAMES) {
+      if (user[name]) {
+        if (!ctx.dryRun) ctx.run('claude', ['mcp', 'remove', '--scope', 'user', name])
+        actions.push(`removed old server ${name}`)
+      }
+    }
+
+    if (ctx.url === DEFAULT_MCP_URL) {
+      const plugin = pluginState(ctx)
+      if (!plugin) {
+        if (!ctx.dryRun) {
+          const list = ctx.run('claude', ['plugin', 'marketplace', 'list', '--json'])
+          if (!list.stdout.includes(`"${MARKETPLACE}"`)) {
+            must(ctx.run('claude', ['plugin', 'marketplace', 'add', MARKETPLACE_SOURCE], { timeoutMs: 180000 }), 'claude plugin marketplace add')
+          }
+          must(ctx.run('claude', ['plugin', 'install', PLUGIN, '--scope', 'user'], { timeoutMs: 180000 }), 'claude plugin install')
+        }
+        actions.push(`installed plugin ${PLUGIN} (box server + box skill)`)
+      } else if (!plugin.enabled) {
+        if (!ctx.dryRun) must(ctx.run('claude', ['plugin', 'enable', PLUGIN]), 'claude plugin enable')
+        actions.push(`enabled plugin ${PLUGIN}`)
+      }
+      // A user-scope `box` next to the plugin would show box twice.
+      if (user[SERVER_NAME]) {
+        if (!ctx.dryRun) ctx.run('claude', ['mcp', 'remove', '--scope', 'user', SERVER_NAME])
+        actions.push('removed the user-scope box server (the plugin provides it)')
+      }
+    } else {
+      const current = user[SERVER_NAME]
+      if (!current || current.url !== ctx.url || current.type !== 'http') {
+        if (!ctx.dryRun) {
+          if (current) ctx.run('claude', ['mcp', 'remove', '--scope', 'user', SERVER_NAME])
+          must(ctx.run('claude', ['mcp', 'add', '--scope', 'user', '--transport', 'http', SERVER_NAME, ctx.url]), 'claude mcp add')
+        }
+        actions.push(`added user-scope server box -> ${ctx.url}`)
+      }
+      const plugin = pluginState(ctx)
+      if (plugin?.enabled) {
+        if (!ctx.dryRun) ctx.run('claude', ['plugin', 'disable', PLUGIN])
+        actions.push(`disabled plugin ${PLUGIN} (it points at the default URL)`)
+      }
+    }
+    const label = ctx.url === DEFAULT_MCP_URL ? 'plugin:box:box' : 'box'
+    return {
+      actions,
+      next: [`Start Claude Code, run /mcp, pick ${label} and choose Authenticate; sign in and click Approve in the browser.`],
+    }
+  },
+
+  remove(ctx) {
+    if (!ctx.which('claude')) throw new Error('the `claude` command is not on PATH')
+    const actions = []
+    const user = readUserServers(ctx)
+    for (const name of [SERVER_NAME, ...LEGACY_SERVER_NAMES]) {
+      if (user[name]) {
+        if (!ctx.dryRun) ctx.run('claude', ['mcp', 'remove', '--scope', 'user', name])
+        actions.push(`removed user-scope server ${name}`)
+      }
+    }
+    if (pluginState(ctx)) {
+      if (!ctx.dryRun) must(ctx.run('claude', ['plugin', 'uninstall', PLUGIN]), 'claude plugin uninstall')
+      actions.push(`uninstalled plugin ${PLUGIN}`)
+    }
+    return { actions, next: [] }
+  },
+}
diff --git a/cli/src/clients/claude-desktop.js b/cli/src/clients/claude-desktop.js
new file mode 100644
index 0000000..68c619d
--- /dev/null
+++ b/cli/src/clients/claude-desktop.js
@@ -0,0 +1,36 @@
+// Claude Desktop and claude.ai: remote servers are added as custom connectors in the app, not in
+// claude_desktop_config.json (that file only takes local stdio servers). We can't add a connector
+// for the user, so `connect` prints the steps and writes nothing.
+// Docs: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp
+import fs from 'node:fs'
+import path from 'node:path'
+
+const appDir = (ctx) => path.join(ctx.appData, 'Claude')
+
+export default {
+  id: 'claude-desktop',
+  name: 'Claude Desktop',
+  auth: 'oauth',
+  manual: true,
+  aliases: ['claude-ai', 'claude.ai'],
+  detect(ctx) {
+    if (fs.existsSync(appDir(ctx))) return { installed: true, via: appDir(ctx) }
+    if (ctx.platform === 'darwin' && fs.existsSync('/Applications/Claude.app')) return { installed: true, via: '/Applications/Claude.app' }
+    return { installed: false }
+  },
+  configLocation() {
+    return 'Settings -> Connectors in the Claude app'
+  },
+  status() {
+    return { entries: [], legacy: [], keyConfigured: false, manual: true }
+  },
+  connect(ctx) {
+    return {
+      actions: ['nothing written: Claude Desktop adds remote servers as connectors in the app'],
+      next: [`Open Settings -> Connectors -> Add custom connector, name it box, paste ${ctx.url}, click Connect, sign in and Approve.`],
+    }
+  },
+  remove() {
+    return { actions: [], next: ['Remove the box connector in Settings -> Connectors.'] }
+  },
+}
diff --git a/cli/src/clients/codex.js b/cli/src/clients/codex.js
new file mode 100644
index 0000000..8d0c0c7
--- /dev/null
+++ b/cli/src/clients/codex.js
@@ -0,0 +1,66 @@
+// Codex CLI: $CODEX_HOME/config.toml (default ~/.codex), `[mcp_servers.box]` with `url`.
+// Codex runs OAuth itself (`codex mcp login box`). We edit the TOML instead of running
+// `codex mcp add`, because `add` starts the browser sign-in inline and would block a scripted run.
+// Sources: https://github.com/openai/codex/blob/main/codex-rs/cli/src/mcp_cmd.rs ,
+// https://github.com/openai/codex/blob/main/codex-rs/config/src/mcp_types.rs
+import fs from 'node:fs'
+import path from 'node:path'
+import { LEGACY_SERVER_NAMES, SERVER_NAME } from '../constants.js'
+import { readText, updateFile } from '../fsutil.js'
+import { parseToml, removeTomlServers, upsertTomlServer } from '../formats.js'
+
+const home = (ctx) => ctx.env.CODEX_HOME || path.join(ctx.home, '.codex')
+const file = (ctx) => path.join(home(ctx), 'config.toml')
+
+export default {
+  id: 'codex',
+  name: 'Codex',
+  auth: 'oauth',
+  aliases: ['codex-cli'],
+
+  detect(ctx) {
+    if (ctx.which('codex')) return { installed: true, via: 'codex on PATH' }
+    if (fs.existsSync(home(ctx))) return { installed: true, via: home(ctx), cliMissing: true }
+    return { installed: false }
+  },
+
+  configLocation: file,
+
+  status(ctx) {
+    const f = file(ctx)
+    const servers = parseToml(readText(f), f).mcp_servers || {}
+    const box = servers[SERVER_NAME]
+    const warnings = []
+    if (box && (box.bearer_token_env_var || box.http_headers || box.env_http_headers)) {
+      warnings.push('box has a bearer token or headers set; Codex then skips OAuth. Re-run connect to reset it')
+    }
+    return {
+      entries: box ? [{ where: f, url: box.url, enabled: box.enabled !== false }] : [],
+      legacy: LEGACY_SERVER_NAMES.filter((n) => servers[n]),
+      keyConfigured: false,
+      warnings,
+    }
+  },
+
+  connect(ctx) {
+    const f = file(ctx)
+    const res = updateFile(f, (text) => upsertTomlServer(text, SERVER_NAME, { url: ctx.url }, { legacy: LEGACY_SERVER_NAMES, file: f }), {
+      dryRun: ctx.dryRun,
+    })
+    return {
+      actions: res.changed ? [`${ctx.dryRun ? 'would write' : 'wrote'} [mcp_servers.box] to ${f}`] : [],
+      backups: res.backup ? [res.backup] : [],
+      next: ['Run `codex mcp login box`, sign in in the browser and click Approve.'],
+    }
+  },
+
+  remove(ctx) {
+    const f = file(ctx)
+    const res = updateFile(f, (text) => removeTomlServers(text, [SERVER_NAME, ...LEGACY_SERVER_NAMES], { file: f }), { dryRun: ctx.dryRun })
+    return {
+      actions: res.changed ? [`${ctx.dryRun ? 'would remove' : 'removed'} [mcp_servers.box] from ${f}`] : [],
+      backups: res.backup ? [res.backup] : [],
+      next: res.changed ? ['To also drop the stored sign-in: `codex mcp logout box` (before removing) or revoke it at https://box.simular.ai/keys.'] : [],
+    }
+  },
+}
diff --git a/cli/src/clients/cursor.js b/cli/src/clients/cursor.js
new file mode 100644
index 0000000..6f68a2b
--- /dev/null
+++ b/cli/src/clients/cursor.js
@@ -0,0 +1,16 @@
+// Cursor: ~/.cursor/mcp.json, `mcpServers`. Cursor signs in to remote servers with OAuth
+// (DCR + PKCE) itself. Docs: https://cursor.com/docs/context/mcp
+import path from 'node:path'
+import { jsonClient } from './json-client.js'
+
+export default jsonClient({
+  id: 'cursor',
+  name: 'Cursor',
+  auth: 'oauth',
+  file: (ctx) => path.join(ctx.home, '.cursor', 'mcp.json'),
+  container: ['mcpServers'],
+  entry: (ctx) => ({ url: ctx.url }),
+  bins: ['cursor', 'agent', 'cursor-agent'],
+  dirs: (ctx) => [path.join(ctx.home, '.cursor'), ...(ctx.platform === 'darwin' ? ['/Applications/Cursor.app'] : [])],
+  next: ['Open Cursor Settings -> MCP (Tools & MCP) and click Login next to box; sign in and click Approve.'],
+})
diff --git a/cli/src/clients/hermes.js b/cli/src/clients/hermes.js
new file mode 100644
index 0000000..9738975
--- /dev/null
+++ b/cli/src/clients/hermes.js
@@ -0,0 +1,116 @@
+// Hermes Agent: $HERMES_HOME/config.yaml (default ~/.hermes), `mcp_servers.box`.
+// OAuth (default): `{url, auth: oauth}`; Hermes signs in with `hermes mcp login box`.
+// Personal key (--auth key, for always-on servers): the header references ${MCP_BOX_API_KEY}, the
+// name `hermes mcp add --auth header` itself uses, and the key goes to $HERMES_HOME/.env (0600),
+// where Hermes loads secrets from. A running gateway caches the old key, so it is restarted.
+// We write the YAML directly because `hermes mcp add` is interactive and cancels without a TTY.
+// Sources: https://github.com/NousResearch/hermes-agent/blob/main/hermes_cli/mcp_config.py ,
+// https://github.com/NousResearch/hermes-agent/blob/main/tools/mcp_tool.py ,
+// https://github.com/NousResearch/hermes-agent/blob/main/hermes_constants.py
+import fs from 'node:fs'
+import path from 'node:path'
+import { LEGACY_SERVER_NAMES, SERVER_NAME } from '../constants.js'
+import { readText, updateFile } from '../fsutil.js'
+import { readEnvValue, readYaml, removeEnvValue, removeYamlServers, upsertEnvValue, upsertYamlServer } from '../formats.js'
+
+export const HERMES_KEY_ENV = 'MCP_BOX_API_KEY'
+const KEY_REF = `Bearer \${${HERMES_KEY_ENV}}`
+
+function home(ctx) {
+  if (ctx.env.HERMES_HOME) return ctx.env.HERMES_HOME
+  if (ctx.platform === 'win32' && ctx.env.LOCALAPPDATA) return path.join(ctx.env.LOCALAPPDATA, 'hermes')
+  return path.join(ctx.home, '.hermes')
+}
+const configFile = (ctx) => path.join(home(ctx), 'config.yaml')
+const envFile = (ctx) => path.join(home(ctx), '.env')
+
+function serverEntry(ctx) {
+  const f = configFile(ctx)
+  return (readYaml(readText(f), f).mcp_servers || {})
+}
+
+export default {
+  id: 'hermes',
+  name: 'Hermes Agent',
+  auth: 'oauth',
+  supportsKey: true,
+
+  detect(ctx) {
+    if (ctx.which('hermes')) return { installed: true, via: 'hermes on PATH' }
+    if (fs.existsSync(home(ctx))) return { installed: true, via: home(ctx), cliMissing: true }
+    return { installed: false }
+  },
+
+  configLocation: configFile,
+
+  status(ctx) {
+    const servers = serverEntry(ctx)
+    const box = servers[SERVER_NAME]
+    const usesKey = Boolean(box?.headers && JSON.stringify(box.headers).includes(HERMES_KEY_ENV))
+    const key = usesKey ? readEnvValue(readText(envFile(ctx)), HERMES_KEY_ENV) || ctx.env[HERMES_KEY_ENV] : undefined
+    const warnings = []
+    if (usesKey && !key) warnings.push(`box reads ${HERMES_KEY_ENV}, but it is not set in ${envFile(ctx)}`)
+    return {
+      entries: box ? [{ where: configFile(ctx), url: box.url, enabled: box.enabled !== false, mode: usesKey ? 'key' : 'oauth' }] : [],
+      legacy: LEGACY_SERVER_NAMES.filter((n) => servers[n]),
+      key,
+      keyConfigured: Boolean(key),
+      warnings,
+    }
+  },
+
+  connect(ctx, { mode = 'oauth', key } = {}) {
+    const f = configFile(ctx)
+    const entry =
+      mode === 'key'
+        ? { url: ctx.url, headers: { Authorization: KEY_REF }, enabled: true }
+        : { url: ctx.url, auth: 'oauth', enabled: true }
+    const actions = []
+    const backups = []
+    const next = []
+    let keyChanged = false
+    if (mode === 'key') {
+      const useKey = key || this.status(ctx).key
+      if (!useKey) throw new Error('a personal key is needed')
+      const r = updateFile(envFile(ctx), (text) => upsertEnvValue(text, HERMES_KEY_ENV, useKey), { mode: 0o600, dryRun: ctx.dryRun })
+      if (r.changed) {
+        keyChanged = true
+        actions.push(`${ctx.dryRun ? 'would save' : 'saved'} the key as ${HERMES_KEY_ENV} in ${envFile(ctx)}`)
+      }
+      if (r.backup) backups.push(r.backup)
+    }
+    const r = updateFile(f, (text) => upsertYamlServer(text, 'mcp_servers', SERVER_NAME, entry, { legacy: LEGACY_SERVER_NAMES, file: f }), {
+      dryRun: ctx.dryRun,
+    })
+    if (r.changed) actions.push(`${ctx.dryRun ? 'would write' : 'wrote'} mcp_servers.box (${mode === 'key' ? 'personal key' : 'OAuth'}) to ${f}`)
+    if (r.backup) backups.push(r.backup)
+
+    if (mode === 'oauth') next.push('Run `hermes mcp login box`, sign in in the browser and click Approve (on a server without a browser: `hermes mcp login box --flow device`, or use --auth key).')
+    if ((keyChanged || r.changed) && !ctx.dryRun) {
+      // A running gateway keeps the old config and key until it restarts.
+      if (ctx.which('hermes')) {
+        const st = ctx.run('hermes', ['gateway', 'status'], { timeoutMs: 20000 })
+        if (st.status === 0 && /running/i.test(st.stdout) && !/not running/i.test(st.stdout)) {
+          const rr = ctx.run('hermes', ['gateway', 'restart'], { timeoutMs: 60000 })
+          if (rr.status === 0) actions.push('restarted the Hermes gateway so it picks up the change')
+          else next.push('Run `hermes gateway restart` so the gateway picks up the change.')
+        }
+      } else next.push('If a Hermes gateway is running, run `hermes gateway restart` so it picks up the change.')
+    }
+    next.push('In an open Hermes chat, run /reload-mcp (or start a new session).')
+    return { actions, backups, next }
+  },
+
+  remove(ctx) {
+    const actions = []
+    const backups = []
+    const f = configFile(ctx)
+    const r = updateFile(f, (text) => removeYamlServers(text, 'mcp_servers', [SERVER_NAME, ...LEGACY_SERVER_NAMES], { file: f }), { dryRun: ctx.dryRun })
+    if (r.changed) actions.push(`${ctx.dryRun ? 'would remove' : 'removed'} mcp_servers.box from ${f}`)
+    if (r.backup) backups.push(r.backup)
+    const e = updateFile(envFile(ctx), (text) => removeEnvValue(text, HERMES_KEY_ENV), { dryRun: ctx.dryRun })
+    if (e.changed) actions.push(`${ctx.dryRun ? 'would remove' : 'removed'} ${HERMES_KEY_ENV} from ${envFile(ctx)}`)
+    if (e.backup) backups.push(e.backup)
+    return { actions, backups, next: actions.length ? ['Run `hermes gateway restart` if a gateway is running.'] : [] }
+  },
+}
diff --git a/cli/src/clients/index.js b/cli/src/clients/index.js
new file mode 100644
index 0000000..0744fde
--- /dev/null
+++ b/cli/src/clients/index.js
@@ -0,0 +1,18 @@
+import claudeCode from './claude-code.js'
+import claudeDesktop from './claude-desktop.js'
+import codex from './codex.js'
+import cursor from './cursor.js'
+import hermes from './hermes.js'
+import openclaw from './openclaw.js'
+import opencode from './opencode.js'
+import vscode from './vscode.js'
+
+export const CLIENTS = [claudeCode, codex, cursor, opencode, hermes, openclaw, vscode, claudeDesktop]
+
+const ALIASES = { claude: 'claude-code', 'claude-code-cli': 'claude-code' }
+
+export function findClient(id) {
+  const key = String(id).toLowerCase()
+  const target = ALIASES[key] || key
+  return CLIENTS.find((c) => c.id === target || (c.aliases || []).includes(target))
+}
diff --git a/cli/src/clients/json-client.js b/cli/src/clients/json-client.js
new file mode 100644
index 0000000..0ff8afa
--- /dev/null
+++ b/cli/src/clients/json-client.js
@@ -0,0 +1,87 @@
+// Shared logic for clients whose config is a JSON/JSONC file with a map of servers.
+import fs from 'node:fs'
+import { LEGACY_SERVER_NAMES, SERVER_NAME } from '../constants.js'
+import { readText, updateFile } from '../fsutil.js'
+import { getPath, parseJsonc, removeJsonServer, upsertJsonServer } from '../formats.js'
+
+/**
+ * @param {object} spec
+ * @param {string} spec.id
+ * @param {string} spec.name
+ * @param {'oauth'|'key'} spec.auth
+ * @param {(ctx) => string} spec.file          config file path
+ * @param {string[]} spec.container             JSON path of the servers map
+ * @param {(ctx, key) => object} spec.entry     the box entry to write
+ * @param {(entry) => string|undefined} [spec.entryUrl]
+ * @param {(entry) => string|undefined} [spec.entryKey]
+ * @param {string[]} [spec.bins]                binaries that mean "installed"
+ * @param {(ctx) => string[]} [spec.dirs]       directories that mean "installed"
+ * @param {string[]} [spec.next]
+ * @param {(ctx) => object} [spec.extraStatus]
+ */
+export function jsonClient(spec) {
+  const entryUrl = spec.entryUrl || ((e) => e?.url)
+  const entryKey = spec.entryKey || (() => undefined)
+  return {
+    id: spec.id,
+    name: spec.name,
+    auth: spec.auth,
+    aliases: spec.aliases || [],
+
+    detect(ctx) {
+      for (const bin of spec.bins || []) if (ctx.which(bin)) return { installed: true, via: `${bin} on PATH` }
+      for (const dir of spec.dirs ? spec.dirs(ctx) : []) if (fs.existsSync(dir)) return { installed: true, via: dir }
+      return { installed: false }
+    },
+
+    configLocation(ctx) {
+      return spec.file(ctx)
+    },
+
+    status(ctx) {
+      const file = spec.file(ctx)
+      const doc = parseJsonc(readText(file), file)
+      const servers = getPath(doc, spec.container) || {}
+      const entry = servers[SERVER_NAME]
+      const entries = entry ? [{ where: file, url: entryUrl(entry), enabled: entry.enabled !== false && entry.disabled !== true }] : []
+      const key = entry ? entryKey(entry) : undefined
+      return {
+        entries,
+        legacy: LEGACY_SERVER_NAMES.filter((n) => servers[n]),
+        key,
+        keyConfigured: Boolean(key),
+        ...(spec.extraStatus ? spec.extraStatus(ctx, entry) : {}),
+      }
+    },
+
+    connect(ctx, { key } = {}) {
+      const file = spec.file(ctx)
+      let useKey = key
+      if (spec.auth === 'key' && !useKey) useKey = this.status(ctx).key
+      if (spec.auth === 'key' && !useKey) throw new Error('a personal key is needed')
+      const entry = spec.entry(ctx, useKey)
+      const res = updateFile(
+        file,
+        (text) => upsertJsonServer(text, spec.container, SERVER_NAME, entry, { legacy: LEGACY_SERVER_NAMES, file }),
+        { dryRun: ctx.dryRun, mode: spec.auth === 'key' ? 0o600 : undefined },
+      )
+      return {
+        actions: res.changed ? [`${ctx.dryRun ? 'would write' : 'wrote'} box to ${file}`] : [],
+        backups: res.backup ? [res.backup] : [],
+        next: typeof spec.next === 'function' ? spec.next(ctx) : spec.next || [],
+      }
+    },
+
+    remove(ctx) {
+      const file = spec.file(ctx)
+      const res = updateFile(file, (text) => removeJsonServer(text, spec.container, [SERVER_NAME, ...LEGACY_SERVER_NAMES], { file }), {
+        dryRun: ctx.dryRun,
+      })
+      return {
+        actions: res.changed ? [`${ctx.dryRun ? 'would remove' : 'removed'} box from ${file}`] : [],
+        backups: res.backup ? [res.backup] : [],
+        next: [],
+      }
+    },
+  }
+}
diff --git a/cli/src/clients/openclaw.js b/cli/src/clients/openclaw.js
new file mode 100644
index 0000000..0e5ebc2
--- /dev/null
+++ b/cli/src/clients/openclaw.js
@@ -0,0 +1,165 @@
+// OpenClaw: `mcp.servers.box` in openclaw.json (JSON5, managed by OpenClaw). Written through
+// OpenClaw's own `openclaw mcp set/show/unset`, so its config journal and paths stay right.
+// OAuth (default): `{url, transport: "streamable-http", auth: "oauth"}`, then `openclaw mcp login box`.
+// Without `transport` OpenClaw defaults to SSE, so it is always set.
+// Personal key (--auth key): the header is `Bearer ${BOX_TOKEN}` and the key goes to the state
+// dir's .env (0600). OpenClaw substitutes ${VAR} from its own process environment and sends the
+// placeholder literally when the variable is unset (the 401 seen in box-plugin#2): a Gateway
+// started by launchd/systemd never sees a shell export, but it does load <state dir>/.env, and
+// only at start, hence the restart.
+// Sources: https://github.com/openclaw/openclaw/blob/main/src/cli/mcp-cli.ts ,
+// https://github.com/openclaw/openclaw/blob/main/src/config/env-substitution.ts ,
+// https://github.com/openclaw/openclaw/blob/main/docs/help/environment.md
+import fs from 'node:fs'
+import path from 'node:path'
+import { KEY_ENV, LEGACY_SERVER_NAMES, SERVER_NAME } from '../constants.js'
+import { readText, updateFile } from '../fsutil.js'
+import { parseJsonc, readEnvValue, removeEnvValue, sameValue, upsertEnvValue } from '../formats.js'
+
+const KEY_REF = `Bearer \${${KEY_ENV}}`
+
+function stateDir(ctx) {
+  if (ctx.env.OPENCLAW_STATE_DIR) return ctx.env.OPENCLAW_STATE_DIR
+  const base = ctx.env.OPENCLAW_HOME || ctx.home
+  const profile = (ctx.env.OPENCLAW_PROFILE || '').trim()
+  return path.join(base, profile && profile !== 'default' ? `.openclaw-${profile}` : '.openclaw')
+}
+const envFile = (ctx) => path.join(stateDir(ctx), '.env')
+const configFile = (ctx) => ctx.env.OPENCLAW_CONFIG_PATH || path.join(stateDir(ctx), 'openclaw.json')
+
+function show(ctx, name) {
+  const res = ctx.run('openclaw', ['mcp', 'show', name, '--json'], { timeoutMs: 30000 })
+  if (res.status !== 0) return undefined
+  try {
+    return JSON.parse(res.stdout.slice(res.stdout.indexOf('{')))
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The entry as written in the file. `openclaw mcp show` prints values with ${VAR} already
+ * substituted (it would show the key), so compare and inspect the raw file when we can parse it;
+ * OpenClaw itself writes plain JSON. Falls back to `show` for hand-written JSON5.
+ */
+function rawEntry(ctx, name) {
+  const file = configFile(ctx)
+  const text = readText(file)
+  if (text === null) return { known: true, entry: undefined }
+  try {
+    return { known: true, entry: parseJsonc(text, file).mcp?.servers?.[name] }
+  } catch {
+    return { known: false, entry: show(ctx, name) }
+  }
+}
+
+function must(res, what) {
+  if (res.status === 0) return
+  const msg = (res.stderr || res.stdout).trim().split('\n').filter(Boolean).pop() || `exit ${res.status}`
+  if (/gateway/i.test(msg) && /running/i.test(msg)) {
+    throw new Error(`${what}: ${msg}. Run \`openclaw gateway stop\`, run connect again, then \`openclaw gateway start\``)
+  }
+  throw new Error(`${what} failed: ${msg}`)
+}
+
+function gatewayUp(ctx) {
+  return ctx.run('openclaw', ['gateway', 'health'], { timeoutMs: 20000 }).status === 0
+}
+
+export default {
+  id: 'openclaw',
+  name: 'OpenClaw',
+  auth: 'oauth',
+  supportsKey: true,
+
+  detect(ctx) {
+    if (ctx.which('openclaw')) return { installed: true, via: 'openclaw on PATH' }
+    if (fs.existsSync(stateDir(ctx))) return { installed: true, via: stateDir(ctx), cliMissing: true }
+    return { installed: false }
+  },
+
+  configLocation: configFile,
+
+  status(ctx) {
+    if (!ctx.which('openclaw')) throw new Error('the `openclaw` command is not on PATH, so its config cannot be read')
+    const box = rawEntry(ctx, SERVER_NAME).entry
+    const legacy = LEGACY_SERVER_NAMES.filter((n) => rawEntry(ctx, n).entry !== undefined)
+    const header = box?.headers?.Authorization || box?.headers?.authorization
+    const usesKeyRef = typeof header === 'string' && header.includes(`\${${KEY_ENV}}`)
+    const literal = typeof header === 'string' && /^Bearer\s+cb_/.test(header) ? header.replace(/^Bearer\s+/, '') : undefined
+    const key = literal || (usesKeyRef ? readEnvValue(readText(envFile(ctx)), KEY_ENV) : undefined)
+    const warnings = []
+    if (box && box.transport !== 'streamable-http') warnings.push(`box uses transport ${box.transport || 'sse (the default)'}; box needs streamable-http`)
+    if (usesKeyRef && !key) warnings.push(`box sends \${${KEY_ENV}}, but ${KEY_ENV} is not in ${envFile(ctx)}; OpenClaw would send the placeholder and get 401`)
+    if (literal) warnings.push('the key is written into openclaw.json in plain text; re-run connect to move it to .env')
+    return {
+      entries: box ? [{ where: configFile(ctx), url: box.url, enabled: box.enabled !== false, mode: header ? 'key' : 'oauth' }] : [],
+      legacy,
+      key,
+      keyConfigured: Boolean(key),
+      warnings,
+    }
+  },
+
+  connect(ctx, { mode = 'oauth', key } = {}) {
+    if (!ctx.which('openclaw')) throw new Error('the `openclaw` command is not on PATH; install OpenClaw first')
+    const actions = []
+    const backups = []
+    const next = []
+    let keyChanged = false
+    if (mode === 'key') {
+      const useKey = key || readEnvValue(readText(envFile(ctx)), KEY_ENV)
+      if (!useKey) throw new Error('a personal key is needed')
+      const r = updateFile(envFile(ctx), (text) => upsertEnvValue(text, KEY_ENV, useKey), { mode: 0o600, dryRun: ctx.dryRun })
+      if (r.changed) {
+        keyChanged = true
+        actions.push(`${ctx.dryRun ? 'would save' : 'saved'} the key as ${KEY_ENV} in ${envFile(ctx)}`)
+      }
+      if (r.backup) backups.push(r.backup)
+    }
+    const entry =
+      mode === 'key'
+        ? { url: ctx.url, transport: 'streamable-http', headers: { Authorization: KEY_REF } }
+        : { url: ctx.url, transport: 'streamable-http', auth: 'oauth' }
+    const current = rawEntry(ctx, SERVER_NAME).entry
+    let configChanged = false
+    if (!sameValue(current, entry)) {
+      if (!ctx.dryRun) must(ctx.run('openclaw', ['mcp', 'set', SERVER_NAME, JSON.stringify(entry)], { timeoutMs: 60000 }), 'openclaw mcp set')
+      configChanged = true
+      actions.push(`${ctx.dryRun ? 'would set' : 'set'} mcp.servers.box (${mode === 'key' ? 'personal key from .env' : 'OAuth'}) via openclaw mcp set`)
+    }
+    for (const name of LEGACY_SERVER_NAMES) {
+      if (rawEntry(ctx, name).entry !== undefined) {
+        if (!ctx.dryRun) ctx.run('openclaw', ['mcp', 'unset', name])
+        actions.push(`removed old server ${name}`)
+      }
+    }
+    if (!ctx.dryRun && (configChanged || keyChanged)) {
+      if (keyChanged && gatewayUp(ctx)) {
+        // The Gateway reads .env only when it starts.
+        const rr = ctx.run('openclaw', ['gateway', 'restart'], { timeoutMs: 120000 })
+        if (rr.status === 0) actions.push('restarted the OpenClaw Gateway so it loads the key')
+        else next.push('Run `openclaw gateway restart` so the Gateway loads the key.')
+      } else if (configChanged) ctx.run('openclaw', ['mcp', 'reload'], { timeoutMs: 30000 })
+      if (keyChanged && !gatewayUp(ctx)) next.push('The key is read when the Gateway starts: `openclaw gateway start` (or restart it if it runs elsewhere).')
+    }
+    if (mode === 'oauth') next.push('Run `openclaw mcp login box`, sign in in the browser and click Approve. On a server without a browser, use --auth key instead.')
+    return { actions, backups, next }
+  },
+
+  remove(ctx) {
+    if (!ctx.which('openclaw')) throw new Error('the `openclaw` command is not on PATH')
+    const actions = []
+    const backups = []
+    for (const name of [SERVER_NAME, ...LEGACY_SERVER_NAMES]) {
+      if (rawEntry(ctx, name).entry !== undefined) {
+        if (!ctx.dryRun) must(ctx.run('openclaw', ['mcp', 'unset', name]), 'openclaw mcp unset')
+        actions.push(`removed mcp.servers.${name}`)
+      }
+    }
+    const e = updateFile(envFile(ctx), (text) => removeEnvValue(text, KEY_ENV), { dryRun: ctx.dryRun, mode: 0o600 })
+    if (e.changed) actions.push(`${ctx.dryRun ? 'would remove' : 'removed'} ${KEY_ENV} from ${envFile(ctx)}`)
+    if (e.backup) backups.push(e.backup)
+    return { actions, backups, next: [] }
+  },
+}
diff --git a/cli/src/clients/opencode.js b/cli/src/clients/opencode.js
new file mode 100644
index 0000000..0f468fb
--- /dev/null
+++ b/cli/src/clients/opencode.js
@@ -0,0 +1,25 @@
+// OpenCode: ~/.config/opencode/opencode.json(c), `mcp`, `{ type: "remote", url }`. OpenCode
+// detects the 401 and runs OAuth (DCR) itself; `opencode mcp auth box` signs in.
+// Docs: https://opencode.ai/docs/mcp-servers/ , https://opencode.ai/docs/config/
+import fs from 'node:fs'
+import path from 'node:path'
+import { jsonClient } from './json-client.js'
+
+function file(ctx) {
+  if (ctx.env.OPENCODE_CONFIG) return ctx.env.OPENCODE_CONFIG
+  const dir = path.join(ctx.xdgConfig, 'opencode')
+  const jsonc = path.join(dir, 'opencode.jsonc')
+  return fs.existsSync(jsonc) ? jsonc : path.join(dir, 'opencode.json')
+}
+
+export default jsonClient({
+  id: 'opencode',
+  name: 'OpenCode',
+  auth: 'oauth',
+  file,
+  container: ['mcp'],
+  entry: (ctx) => ({ type: 'remote', url: ctx.url, enabled: true }),
+  bins: ['opencode'],
+  dirs: (ctx) => [path.join(ctx.xdgConfig, 'opencode')],
+  next: ['Run `opencode mcp auth box`, sign in in the browser and click Approve.'],
+})
diff --git a/cli/src/clients/vscode.js b/cli/src/clients/vscode.js
new file mode 100644
index 0000000..f1594a3
--- /dev/null
+++ b/cli/src/clients/vscode.js
@@ -0,0 +1,20 @@
+// VS Code (GitHub Copilot agent mode): user-profile mcp.json, `servers`, `type: "http"`.
+// VS Code runs the OAuth sign-in itself. Docs:
+// https://code.visualstudio.com/docs/agents/reference/mcp-configuration
+// Detection uses the user-data folder, not `code` on PATH: Cursor also installs a `code` shim.
+import path from 'node:path'
+import { jsonClient } from './json-client.js'
+
+const userDir = (ctx) => path.join(ctx.appData, 'Code', 'User')
+
+export default jsonClient({
+  id: 'vscode',
+  name: 'VS Code',
+  auth: 'oauth',
+  aliases: ['code', 'copilot'],
+  file: (ctx) => path.join(userDir(ctx), 'mcp.json'),
+  container: ['servers'],
+  entry: (ctx) => ({ type: 'http', url: ctx.url }),
+  dirs: (ctx) => [userDir(ctx)],
+  next: ['In VS Code, open the Command Palette -> MCP: List Servers -> box -> Start, then allow the sign-in and click Approve.'],
+})
diff --git a/cli/src/constants.js b/cli/src/constants.js
new file mode 100644
index 0000000..34cfeee
--- /dev/null
+++ b/cli/src/constants.js
@@ -0,0 +1,43 @@
+// The one place the box MCP endpoint lives. When the endpoint moves (planned: mcp.box.simular.ai),
+// change DEFAULT_MCP_URL and release a new CLI version. BOX_MCP_URL overrides it (e.g. staging).
+export const DEFAULT_MCP_URL = 'https://relay.simular.cloud/mcp'
+
+/** Servers named here are removed on connect: older box setups added them next to `box`. */
+export const LEGACY_SERVER_NAMES = ['box-control']
+
+export const SERVER_NAME = 'box'
+export const KEY_ENV = 'BOX_TOKEN'
+export const KEYS_URL = 'https://box.simular.ai/keys'
+export const WATCH_URL = 'https://box.simular.ai/box'
+export const INSTALL_URL = 'https://box.simular.ai/install'
+export const SUPPORT_EMAIL = 'support@simular.ai'
+
+export function mcpUrl(env = process.env) {
+  const override = (env.BOX_MCP_URL || '').trim()
+  if (!override) return DEFAULT_MCP_URL
+  let parsed
+  try {
+    parsed = new URL(override)
+  } catch {
+    throw new Error(`BOX_MCP_URL is not a valid URL: ${override}`)
+  }
+  if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && isLoopback(parsed.hostname))) {
+    throw new Error('BOX_MCP_URL must use https (http is allowed only for localhost)')
+  }
+  return parsed.toString().replace(/\/$/, '')
+}
+
+function isLoopback(host) {
+  return host === 'localhost' || host === '127.0.0.1' || host === '[::1]'
+}
+
+/** A personal key looks like `cb_` followed by url-safe characters. */
+export function looksLikeKey(value) {
+  return typeof value === 'string' && /^cb_[A-Za-z0-9_-]{4,}$/.test(value.trim())
+}
+
+/** For display only: never print a key, only that one is set and how it starts. */
+export function maskKey(value) {
+  if (!value) return '(none)'
+  return value.startsWith('cb_') ? 'cb_****' : '****'
+}
diff --git a/cli/src/context.js b/cli/src/context.js
new file mode 100644
index 0000000..aedf58b
--- /dev/null
+++ b/cli/src/context.js
@@ -0,0 +1,67 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { mcpUrl } from './constants.js'
+
+/**
+ * Everything a client adapter may touch about the machine goes through this context, so tests can
+ * point it at a temporary HOME and a fake PATH.
+ */
+export function createContext({ env = process.env, platform = process.platform, dryRun = false, log = () => {} } = {}) {
+  const home = env.HOME || env.USERPROFILE || os.homedir()
+  const ctx = {
+    env,
+    home,
+    platform,
+    dryRun,
+    log,
+    url: mcpUrl(env),
+    /** XDG config dir, falling back to ~/.config (also on macOS, as most CLIs do). */
+    xdgConfig: env.XDG_CONFIG_HOME || path.join(home, '.config'),
+    /** Platform app-data dir: ~/Library/Application Support, %APPDATA%, or XDG config. */
+    appData:
+      platform === 'darwin'
+        ? path.join(home, 'Library', 'Application Support')
+        : platform === 'win32'
+          ? env.APPDATA || path.join(home, 'AppData', 'Roaming')
+          : env.XDG_CONFIG_HOME || path.join(home, '.config'),
+    which(bin) {
+      return which(bin, env, platform)
+    },
+    /**
+     * Run a client's own CLI. Arguments are passed as an array (no shell), so nothing is
+     * interpolated. Secrets must never be passed here: they would show up in `ps`.
+     */
+    run(bin, args, { input, timeoutMs = 60000 } = {}) {
+      const resolved = ctx.which(bin)
+      if (!resolved) return { status: 127, stdout: '', stderr: `${bin} not found` }
+      const res = spawnSync(resolved, args, {
+        env,
+        input,
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        shell: platform === 'win32' && /\.(cmd|bat)$/i.test(resolved),
+      })
+      return { status: res.status ?? 1, stdout: res.stdout || '', stderr: res.stderr || String(res.error || '') }
+    },
+  }
+  return ctx
+}
+
+export function which(bin, env = process.env, platform = process.platform) {
+  const dirs = (env.PATH || env.Path || '').split(path.delimiter).filter(Boolean)
+  const exts = platform === 'win32' ? (env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : ['']
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, bin + ext)
+      try {
+        const st = fs.statSync(candidate)
+        if (st.isFile() && (platform === 'win32' || st.mode & 0o111)) return candidate
+      } catch {
+        // not here
+      }
+    }
+  }
+  return null
+}
diff --git a/cli/src/formats.js b/cli/src/formats.js
new file mode 100644
index 0000000..f045dec
--- /dev/null
+++ b/cli/src/formats.js
@@ -0,0 +1,235 @@
+// Format-preserving edits. We change only the keys we own and keep comments, ordering and
+// every other server the user has.
+import * as jsonc from 'jsonc-parser'
+import * as TOML from 'smol-toml'
+import YAML from 'yaml'
+
+const FORMAT = { formattingOptions: { insertSpaces: true, tabSize: 2, eol: '\n' } }
+
+/** Parse JSON or JSONC. Throws on a file we cannot parse: never overwrite what we can't read. */
+export function parseJsonc(text, file = 'config') {
+  if (text === null || text.trim() === '') return {}
+  const errors = []
+  const value = jsonc.parse(text, errors, { allowTrailingComma: true, disallowComments: false })
+  if (errors.length) {
+    const e = errors[0]
+    throw new Error(`${file} is not valid JSON (${jsonc.printParseErrorCode(e.error)} at offset ${e.offset}); fix it or move it aside, then run again`)
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${file} does not hold a JSON object; fix it or move it aside, then run again`)
+  }
+  return value
+}
+
+/** Set (or with value undefined, delete) the value at `jsonPath`, keeping the rest of the text. */
+export function setJsoncPath(text, jsonPath, value, file) {
+  const base = text === null || text.trim() === '' ? '{}\n' : text
+  parseJsonc(base, file)
+  const edits = jsonc.modify(base, jsonPath, value, FORMAT)
+  let out = jsonc.applyEdits(base, edits)
+  if (!out.endsWith('\n')) out += '\n'
+  return out
+}
+
+export function getPath(obj, jsonPath) {
+  let cur = obj
+  for (const key of jsonPath) {
+    if (cur === null || typeof cur !== 'object') return undefined
+    cur = cur[key]
+  }
+  return cur
+}
+
+/** Equal for config purposes (key order ignored). */
+export function sameValue(a, b) {
+  return JSON.stringify(sortKeys(a)) === JSON.stringify(sortKeys(b))
+}
+
+function sortKeys(v) {
+  if (Array.isArray(v)) return v.map(sortKeys)
+  if (v && typeof v === 'object') {
+    return Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])]))
+  }
+  return v
+}
+
+/**
+ * Upsert `servers[name] = entry` under `containerPath` in a JSON/JSONC document and delete legacy
+ * names. Returns the new text, or the old text when nothing changes.
+ */
+export function upsertJsonServer(text, containerPath, name, entry, { legacy = [], file } = {}) {
+  const doc = parseJsonc(text, file)
+  let out = text
+  const current = getPath(doc, [...containerPath, name])
+  if (!sameValue(current, entry)) out = setJsoncPath(out, [...containerPath, name], entry, file)
+  for (const old of legacy) {
+    if (getPath(parseJsonc(out, file), [...containerPath, old]) !== undefined) {
+      out = setJsoncPath(out, [...containerPath, old], undefined, file)
+    }
+  }
+  return out
+}
+
+export function removeJsonServer(text, containerPath, names, { file } = {}) {
+  if (text === null) return null
+  let out = text
+  for (const name of names) {
+    if (getPath(parseJsonc(out, file), [...containerPath, name]) !== undefined) {
+      out = setJsoncPath(out, [...containerPath, name], undefined, file)
+    }
+  }
+  return out
+}
+
+// ---- dotenv files (KEY=value lines) ----
+
+const envLine = (name) => new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=.*$`, 'm')
+
+export function readEnvValue(text, name) {
+  if (!text) return undefined
+  const m = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=\\s*(.*)$`, 'm').exec(text)
+  if (!m) return undefined
+  return m[1].trim().replace(/^(['"])(.*)\1$/, '$2')
+}
+
+/** Set NAME=value, replacing an existing line in place and keeping every other line. */
+export function upsertEnvValue(text, name, value) {
+  const line = `${name}=${value}`
+  if (text && envLine(name).test(text)) {
+    if (readEnvValue(text, name) === value) return text
+    return text.replace(envLine(name), line)
+  }
+  const base = text ? text.replace(/\n*$/, '\n') : ''
+  return `${base}${line}\n`
+}
+
+export function removeEnvValue(text, name) {
+  if (!text || !envLine(name).test(text)) return text
+  return text.replace(new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=.*(?:\\r?\\n|$)`, 'm'), '')
+}
+
+// ---- TOML (Codex): surgical table edits, so comments and formatting elsewhere survive ----
+
+
+export function parseToml(text, file = 'config.toml') {
+  if (!text || !text.trim()) return {}
+  try {
+    return TOML.parse(text)
+  } catch (err) {
+    throw new Error(`${file} is not valid TOML (${err.message.split('\n')[0]}); fix it or move it aside, then run again`)
+  }
+}
+
+function splitDotted(key) {
+  const parts = []
+  let cur = ''
+  let quote = null
+  for (const ch of key) {
+    if (quote) {
+      if (ch === quote) quote = null
+      else cur += ch
+    } else if (ch === '"' || ch === "'") quote = ch
+    else if (ch === '.') {
+      parts.push(cur.trim())
+      cur = ''
+    } else cur += ch
+  }
+  parts.push(cur.trim())
+  return parts
+}
+
+const HEADER = /^\s*\[(\[?)\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$/
+
+/** Remove `[table]` blocks whose key path starts with any of `prefixes` (arrays of key parts). */
+export function removeTomlTables(text, prefixes) {
+  if (!text) return text
+  const lines = text.split('\n')
+  const out = []
+  let dropping = false
+  for (const line of lines) {
+    const m = HEADER.exec(line)
+    if (m) {
+      const parts = splitDotted(m[2])
+      dropping = prefixes.some((pre) => pre.every((p, i) => parts[i] === p))
+    }
+    if (!dropping) out.push(line)
+  }
+  return out.join('\n')
+}
+
+const tomlString = (s) => JSON.stringify(s)
+
+/**
+ * Set `[mcp_servers.<name>]` to `fields` (flat string values), removing legacy names. Throws when
+ * the server is defined in a way we can't edit safely (inline table or dotted keys elsewhere).
+ */
+export function upsertTomlServer(text, name, fields, { legacy = [], file } = {}) {
+  const doc = parseToml(text, file)
+  const current = doc.mcp_servers?.[name]
+  const hasLegacy = legacy.some((n) => doc.mcp_servers?.[n] !== undefined)
+  if (current && sameValue(current, fields) && !hasLegacy) return text
+  let out = removeTomlTables(text || '', [name, ...legacy].map((n) => ['mcp_servers', n]))
+  const check = parseToml(out, file)
+  for (const n of [name, ...legacy]) {
+    if (check.mcp_servers?.[n] !== undefined) {
+      throw new Error(`${file} defines mcp_servers.${n} inline; remove it by hand, then run again`)
+    }
+  }
+  const body = Object.entries(fields)
+    .map(([k, v]) => `${k} = ${tomlString(v)}`)
+    .join('\n')
+  out = `${out.replace(/\s*$/, '')}${out.trim() ? '\n\n' : ''}[mcp_servers.${name}]\n${body}\n`
+  const final = parseToml(out, file)
+  if (!sameValue(final.mcp_servers?.[name], fields)) throw new Error(`could not update ${file} safely; nothing was written`)
+  return out
+}
+
+export function removeTomlServers(text, names, { file } = {}) {
+  if (!text) return text
+  const doc = parseToml(text, file)
+  if (!names.some((n) => doc.mcp_servers?.[n] !== undefined)) return text
+  const out = removeTomlTables(text, names.map((n) => ['mcp_servers', n])).replace(/\n{3,}/g, '\n\n')
+  const check = parseToml(out, file)
+  for (const n of names) {
+    if (check.mcp_servers?.[n] !== undefined) throw new Error(`${file} defines mcp_servers.${n} inline; remove it by hand`)
+  }
+  return out
+}
+
+// ---- YAML (Hermes): Document API keeps comments and key order ----
+
+
+export function parseYamlDoc(text, file = 'config.yaml') {
+  const doc = YAML.parseDocument(text || '')
+  if (doc.errors.length) throw new Error(`${file} is not valid YAML (${doc.errors[0].message.split('\n')[0]}); fix it or move it aside, then run again`)
+  const root = doc.toJS()
+  if (root !== null && root !== undefined && (typeof root !== 'object' || Array.isArray(root))) {
+    throw new Error(`${file} does not hold a YAML mapping`)
+  }
+  return doc
+}
+
+export function upsertYamlServer(text, containerKey, name, entry, { legacy = [], file } = {}) {
+  const doc = parseYamlDoc(text, file)
+  const js = doc.toJS() || {}
+  const servers = js[containerKey] || {}
+  const hasLegacy = legacy.some((n) => servers[n] !== undefined)
+  if (sameValue(servers[name], entry) && !hasLegacy) return text
+  if (!doc.contents) doc.contents = doc.createNode({})
+  doc.setIn([containerKey, name], doc.createNode(entry))
+  for (const n of legacy) if (servers[n] !== undefined) doc.deleteIn([containerKey, n])
+  return String(doc)
+}
+
+export function removeYamlServers(text, containerKey, names, { file } = {}) {
+  if (!text) return text
+  const doc = parseYamlDoc(text, file)
+  const servers = (doc.toJS() || {})[containerKey] || {}
+  if (!names.some((n) => servers[n] !== undefined)) return text
+  for (const n of names) if (servers[n] !== undefined) doc.deleteIn([containerKey, n])
+  return String(doc)
+}
+
+export function readYaml(text, file) {
+  return parseYamlDoc(text, file).toJS() || {}
+}
diff --git a/cli/src/fsutil.js b/cli/src/fsutil.js
new file mode 100644
index 0000000..83940bd
--- /dev/null
+++ b/cli/src/fsutil.js
@@ -0,0 +1,70 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+export function readText(file) {
+  try {
+    return fs.readFileSync(file, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return null
+    throw err
+  }
+}
+
+export function exists(file) {
+  try {
+    fs.accessSync(file)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Copy `file` to `file.box-backup-<timestamp>` before we change it. Returns the backup path,
+ * or null when there was nothing to back up.
+ */
+export function backup(file, now = new Date()) {
+  if (!exists(file)) return null
+  const stamp = now.toISOString().replace(/[:.]/g, '-')
+  const target = `${file}.box-backup-${stamp}`
+  fs.copyFileSync(file, target)
+  try {
+    fs.chmodSync(target, fs.statSync(file).mode & 0o777)
+  } catch {
+    // best effort: the copy keeps the default mode
+  }
+  return target
+}
+
+/**
+ * Write atomically (temp file + rename) so a crash never leaves a half-written config.
+ * Keeps the existing file's mode; `mode` applies to new files (0600 for files that hold a key).
+ */
+export function writeAtomic(file, text, { mode } = {}) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  let finalMode = mode
+  if (exists(file)) {
+    const current = fs.statSync(file).mode & 0o777
+    finalMode = mode === undefined ? current : current & mode
+  }
+  const tmp = `${file}.box-tmp-${process.pid}`
+  fs.writeFileSync(tmp, text, { mode: finalMode ?? 0o644 })
+  if (finalMode !== undefined) fs.chmodSync(tmp, finalMode)
+  fs.renameSync(tmp, file)
+}
+
+/**
+ * Apply `transform(oldText|null) -> newText|null` to a file. Returns {changed, backup}.
+ * A null result or an unchanged text leaves the file alone (idempotent re-runs, no backup spam).
+ */
+export function updateFile(file, transform, { mode, dryRun = false } = {}) {
+  const before = readText(file)
+  const after = transform(before)
+  if (after === null || after === before) return { changed: false, backup: null }
+  if (dryRun) return { changed: true, backup: null, preview: after }
+  const backupPath = backup(file)
+  // A backup of a file that holds a key is a copy of that key: keep it as private as the file.
+  if (backupPath && mode !== undefined) fs.chmodSync(backupPath, (fs.statSync(backupPath).mode & 0o777) & mode)
+  writeAtomic(file, after, { mode })
+  return { changed: true, backup: backupPath }
+}
diff --git a/cli/src/probe.js b/cli/src/probe.js
new file mode 100644
index 0000000..73b0f70
--- /dev/null
+++ b/cli/src/probe.js
@@ -0,0 +1,97 @@
+// Network checks for `doctor`. Uses Node's built-in fetch (Node >= 18).
+
+const INIT_BODY = JSON.stringify({
+  jsonrpc: '2.0',
+  id: 1,
+  method: 'initialize',
+  params: {
+    protocolVersion: '2025-06-18',
+    capabilities: {},
+    clientInfo: { name: 'simular-box-doctor', version: '0' },
+  },
+})
+
+const HEADERS = {
+  'content-type': 'application/json',
+  accept: 'application/json, text/event-stream',
+}
+
+async function post(url, headers, { timeoutMs = 10000, fetchImpl = fetch } = {}) {
+  return fetchImpl(url, {
+    method: 'POST',
+    headers: { ...HEADERS, ...headers },
+    body: INIT_BODY,
+    signal: AbortSignal.timeout(timeoutMs),
+    redirect: 'manual',
+  })
+}
+
+/** Parse `Bearer resource_metadata="...", scope="...", error="..."`. */
+export function parseWwwAuthenticate(value) {
+  if (!value) return null
+  const match = /^\s*Bearer\b(.*)$/i.exec(value)
+  if (!match) return null
+  const params = {}
+  for (const m of match[1].matchAll(/([a-zA-Z_]+)="([^"]*)"/g)) params[m[1]] = m[2]
+  return params
+}
+
+/**
+ * Unauthenticated probe. A healthy box endpoint answers 401 with a WWW-Authenticate header that
+ * points at its protected-resource metadata (RFC 9728), which names the authorization server.
+ */
+export async function probeEndpoint(url, opts = {}) {
+  const result = { url, ok: false, status: null, resourceMetadata: null, authorizationServer: null, error: null }
+  let res
+  try {
+    res = await post(url, {}, opts)
+  } catch (err) {
+    result.error = `cannot reach ${url}: ${err.cause?.code || err.name || err.message}`
+    return result
+  }
+  result.status = res.status
+  if (res.status !== 401) {
+    result.error = `expected 401 from an unauthenticated request, got ${res.status}`
+    return result
+  }
+  const auth = parseWwwAuthenticate(res.headers.get('www-authenticate'))
+  if (!auth?.resource_metadata) {
+    result.error = '401 without a WWW-Authenticate resource_metadata link; OAuth clients cannot discover sign-in'
+    return result
+  }
+  result.resourceMetadata = auth.resource_metadata
+  try {
+    const meta = await (opts.fetchImpl || fetch)(auth.resource_metadata, {
+      signal: AbortSignal.timeout(opts.timeoutMs || 10000),
+    })
+    if (!meta.ok) throw new Error(`HTTP ${meta.status}`)
+    const doc = await meta.json()
+    result.authorizationServer = doc.authorization_servers?.[0] || null
+    if (!result.authorizationServer) throw new Error('no authorization_servers')
+  } catch (err) {
+    result.error = `protected-resource metadata at ${auth.resource_metadata} is unusable: ${err.message}`
+    return result
+  }
+  result.ok = true
+  return result
+}
+
+/**
+ * Check a personal key without printing it. 200 = valid; 401 with error="invalid_token" = rejected.
+ */
+export async function checkKey(url, key, opts = {}) {
+  let res
+  try {
+    res = await post(url, { authorization: `Bearer ${key}` }, opts)
+  } catch (err) {
+    return { valid: null, status: null, error: `cannot reach ${url}: ${err.cause?.code || err.name}` }
+  }
+  // Drain the body so the connection can close; it may be an SSE stream, so do not wait on it.
+  res.body?.cancel?.().catch(() => {})
+  if (res.status >= 200 && res.status < 300) return { valid: true, status: res.status, error: null }
+  if (res.status === 401 || res.status === 403) {
+    const auth = parseWwwAuthenticate(res.headers.get('www-authenticate'))
+    return { valid: false, status: res.status, error: auth?.error || 'rejected' }
+  }
+  return { valid: null, status: res.status, error: `unexpected HTTP ${res.status}` }
+}
diff --git a/cli/test/cli.test.js b/cli/test/cli.test.js
new file mode 100644
index 0000000..fba9a03
--- /dev/null
+++ b/cli/test/cli.test.js
@@ -0,0 +1,106 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from '../src/args.js'
+import { mcpUrl, maskKey, DEFAULT_MCP_URL } from '../src/constants.js'
+import { parseWwwAuthenticate, probeEndpoint, checkKey } from '../src/probe.js'
+import { runDoctor } from '../src/cli.js'
+import { sandbox } from './helpers.js'
+
+const BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'simular-box.js')
+const KEY = 'cb_test_fake_key_123'
+
+test('args: --client lists, --auth, and keys are never accepted as arguments', () => {
+  assert.deepEqual(parseArgs(['connect', '--client', 'cursor,codex', '-c', 'hermes', '--yes']).flags, { client: ['cursor', 'codex', 'hermes'], yes: true })
+  assert.equal(parseArgs(['connect', '--auth=key']).flags.auth, 'key')
+  assert.throws(() => parseArgs(['connect', '--key', KEY]), /never as an argument/)
+  assert.throws(() => parseArgs(['connect', '--auth', 'password']), /oauth or key/)
+})
+
+test('url: one default, BOX_MCP_URL override, https only (http for localhost)', () => {
+  assert.equal(mcpUrl({}), DEFAULT_MCP_URL)
+  assert.equal(mcpUrl({ BOX_MCP_URL: 'https://mcp.box.simular.ai/mcp/' }), 'https://mcp.box.simular.ai/mcp')
+  assert.equal(mcpUrl({ BOX_MCP_URL: 'http://127.0.0.1:8080/mcp' }), 'http://127.0.0.1:8080/mcp')
+  assert.throws(() => mcpUrl({ BOX_MCP_URL: 'http://evil.example/mcp' }), /https/)
+  assert.equal(maskKey(KEY), 'cb_****')
+})
+
+test('probe: parses WWW-Authenticate and follows resource metadata', async () => {
+  assert.deepEqual(parseWwwAuthenticate('Bearer resource_metadata="https://r/.well-known/x", scope="boxes", error="invalid_token"'), {
+    resource_metadata: 'https://r/.well-known/x',
+    scope: 'boxes',
+    error: 'invalid_token',
+  })
+  const fetchImpl = async (url, init) => {
+    if (url.includes('.well-known')) return new Response(JSON.stringify({ authorization_servers: ['https://as'] }), { status: 200 })
+    if (init.headers.authorization === `Bearer ${KEY}`) return new Response('{}', { status: 200 })
+    return new Response(null, { status: 401, headers: { 'www-authenticate': `Bearer resource_metadata="https://r/.well-known/x"${init.headers.authorization ? ', error="invalid_token"' : ''}` } })
+  }
+  const ep = await probeEndpoint('https://r/mcp', { fetchImpl })
+  assert.equal(ep.ok, true)
+  assert.equal(ep.authorizationServer, 'https://as')
+  assert.equal((await checkKey('https://r/mcp', KEY, { fetchImpl })).valid, true)
+  assert.deepEqual(await checkKey('https://r/mcp', 'cb_wrong_key', { fetchImpl }), { valid: false, status: 401, error: 'invalid_token' })
+  const down = await probeEndpoint('https://r/mcp', { fetchImpl: async () => new Response('', { status: 200 }) })
+  assert.match(down.error, /expected 401/)
+})
+
+test('doctor: flags a stale URL, a legacy server and a rejected key, with fixes', async () => {
+  const sb = sandbox()
+  sb.write('.cursor/mcp.json', JSON.stringify({ mcpServers: { box: { url: 'https://relay.simular.cloud/old' }, 'box-control': { url: 'x' } } }))
+  sb.write('.hermes/config.yaml', 'mcp_servers:\n  box:\n    url: https://relay.simular.cloud/mcp\n    headers:\n      Authorization: Bearer ${MCP_BOX_API_KEY}\n')
+  sb.write('.hermes/.env', `MCP_BOX_API_KEY=${KEY}\n`)
+  const report = await runDoctor(sb.ctx, {}, {
+    probe: async (url) => ({ url, ok: true, status: 401 }),
+    check: async () => ({ valid: false, status: 401, error: 'invalid_token' }),
+  })
+  const cursor = report.clients.find((c) => c.id === 'cursor')
+  assert.equal(cursor.ok, false)
+  assert.match(cursor.problems.join('\n'), /points at https:\/\/relay.simular.cloud\/old/)
+  assert.match(cursor.problems.join('\n'), /box-control/)
+  assert.deepEqual(cursor.fixes, ['npx @simular-ai/box connect --client cursor'])
+  const hermes = report.clients.find((c) => c.id === 'hermes')
+  assert.deepEqual(hermes.key, { configured: true, valid: false, status: 401 })
+  assert.ok(hermes.fixes.some((f) => f.includes('--auth key')))
+  assert.ok(!JSON.stringify(report).includes(KEY), 'the report never contains the key')
+  assert.equal(report.ok, false)
+})
+
+function run(args, sb, extraEnv = {}) {
+  return spawnSync(process.execPath, [BIN, ...args], { env: { ...sb.env, PATH: `${sb.env.PATH}${path.delimiter}${path.dirname(process.execPath)}`, ...extraEnv }, encoding: 'utf8' })
+}
+
+test('real CLI: connect --client cursor,codex --yes in a temp HOME, then remove', () => {
+  const sb = sandbox()
+  const res = run(['connect', '--client', 'cursor,codex', '--yes'], sb)
+  assert.equal(res.status, 0, res.stderr + res.stdout)
+  assert.match(res.stdout, /codex mcp login box/)
+  assert.deepEqual(JSON.parse(sb.read('.cursor/mcp.json')), { mcpServers: { box: { url: DEFAULT_MCP_URL } } })
+  assert.match(sb.read('.codex/config.toml'), /\[mcp_servers\.box\]\nurl = "https:\/\/relay\.simular\.cloud\/mcp"/)
+  const rm = run(['remove', '--client', 'cursor,codex', '--yes'], sb)
+  assert.equal(rm.status, 0, rm.stderr)
+  assert.deepEqual(JSON.parse(sb.read('.cursor/mcp.json')), { mcpServers: {} })
+})
+
+test('real CLI: key mode without a key fails clearly; with BOX_TOKEN it never prints the key', () => {
+  const sb = sandbox()
+  sb.write('.hermes/config.yaml', '')
+  const noKey = run(['connect', '--client', 'hermes', '--auth', 'key', '--yes'], sb)
+  assert.notEqual(noKey.status, 0)
+  assert.match(noKey.stderr, /BOX_TOKEN=cb_/)
+  const withKey = run(['connect', '--client', 'hermes', '--auth', 'key', '--yes'], sb, { BOX_TOKEN: KEY })
+  assert.equal(withKey.status, 0, withKey.stderr)
+  assert.ok(!(withKey.stdout + withKey.stderr).includes(KEY))
+  assert.match(sb.read('.hermes/.env'), new RegExp(`^MCP_BOX_API_KEY=${KEY}$`, 'm'))
+  const bad = run(['connect', '--client', 'hermes', '--auth', 'key', '--yes'], sb, { BOX_TOKEN: 'not-a-key' })
+  assert.notEqual(bad.status, 0)
+})
+
+test('real CLI: unknown client and missing --client in non-interactive mode', () => {
+  const sb = sandbox()
+  assert.match(run(['connect', '--client', 'notepad'], sb).stderr, /unknown client/)
+  sb.write('.cursor/mcp.json', '{}')
+  assert.match(run(['connect'], sb).stderr, /--client cursor/)
+})
diff --git a/cli/test/clients.test.js b/cli/test/clients.test.js
new file mode 100644
index 0000000..e8f95f5
--- /dev/null
+++ b/cli/test/clients.test.js
@@ -0,0 +1,202 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+import * as TOML from 'smol-toml'
+import YAML from 'yaml'
+import * as jsonc from 'jsonc-parser'
+import { findClient } from '../src/clients/index.js'
+import { DEFAULT_MCP_URL } from '../src/constants.js'
+import { FAKE_CLAUDE, FAKE_OPENCLAW, fixture, sandbox } from './helpers.js'
+
+const KEY = 'cb_test_fake_key_123'
+const client = (id) => findClient(id)
+const plain = (v) => JSON.parse(JSON.stringify(v))
+const backups = (dir) => fs.readdirSync(dir).filter((f) => f.includes('.box-backup-'))
+
+test('cursor: merges into mcpServers, keeps comments and other servers, drops box-control, idempotent', () => {
+  const sb = sandbox()
+  const file = sb.write('.cursor/mcp.json', fixture('cursor.before.json'))
+  const first = client('cursor').connect(sb.ctx)
+  assert.equal(first.actions.length, 1)
+  assert.equal(first.backups.length, 1)
+  const text = sb.read('.cursor/mcp.json')
+  assert.match(text, /\/\/ Cursor servers the user already has/)
+  const doc = jsonc.parse(text)
+  assert.deepEqual(doc.mcpServers.box, { url: DEFAULT_MCP_URL })
+  assert.deepEqual(doc.mcpServers.github, { url: 'https://api.githubcopilot.com/mcp/' })
+  assert.equal(doc.mcpServers['box-control'], undefined)
+  const again = client('cursor').connect(sb.ctx)
+  assert.deepEqual(again.actions, [])
+  assert.equal(backups(path.dirname(file)).length, 1, 'a no-op re-run makes no new backup')
+  client('cursor').remove(sb.ctx)
+  const after = jsonc.parse(sb.read('.cursor/mcp.json'))
+  assert.equal(after.mcpServers.box, undefined)
+  assert.ok(after.mcpServers.github)
+})
+
+test('cursor: refuses to touch a file it cannot parse', () => {
+  const sb = sandbox()
+  sb.write('.cursor/mcp.json', fixture('broken.json'))
+  assert.throws(() => client('cursor').connect(sb.ctx), /not valid JSON/)
+  assert.equal(sb.read('.cursor/mcp.json'), fixture('broken.json'))
+})
+
+test('cursor: creates the file when missing; BOX_MCP_URL overrides the URL', () => {
+  const sb = sandbox({ env: { BOX_MCP_URL: 'https://staging.example.test/mcp' } })
+  client('cursor').connect(sb.ctx)
+  assert.deepEqual(JSON.parse(sb.read('.cursor/mcp.json')), { mcpServers: { box: { url: 'https://staging.example.test/mcp' } } })
+})
+
+test('codex: rewrites only [mcp_servers.box] (and its subtables), keeps comments, removes box-control', () => {
+  const sb = sandbox()
+  sb.write('.codex/config.toml', fixture('codex.before.toml'))
+  client('codex').connect(sb.ctx)
+  assert.equal(sb.read('.codex/config.toml'), fixture('codex.after.toml'))
+  assert.deepEqual(client('codex').connect(sb.ctx).actions, [])
+  const st = client('codex').status(sb.ctx)
+  assert.equal(st.entries[0].url, DEFAULT_MCP_URL)
+  client('codex').remove(sb.ctx)
+  const doc = TOML.parse(sb.read('.codex/config.toml'))
+  assert.equal(doc.mcp_servers.box, undefined)
+  assert.deepEqual(plain(doc.mcp_servers.docs), { command: 'npx', args: ['docs-mcp'] })
+  assert.match(sb.read('.codex/config.toml'), /# keep this comment/)
+})
+
+test('codex: honours CODEX_HOME', () => {
+  const sb = sandbox()
+  const codexHome = path.join(sb.home, 'elsewhere')
+  const ctx = { ...sb.ctx, env: { ...sb.env, CODEX_HOME: codexHome } }
+  client('codex').connect(ctx)
+  assert.deepEqual(plain(TOML.parse(fs.readFileSync(path.join(codexHome, 'config.toml'), 'utf8'))), { mcp_servers: { box: { url: DEFAULT_MCP_URL } } })
+})
+
+test('codex: refuses an inline box table it cannot edit safely', () => {
+  const sb = sandbox()
+  const text = 'mcp_servers = { box = { url = "https://x" } }\n'
+  sb.write('.codex/config.toml', text)
+  assert.throws(() => client('codex').connect(sb.ctx), /inline/)
+  assert.equal(sb.read('.codex/config.toml'), text)
+})
+
+test('opencode: prefers opencode.jsonc, writes a remote entry, keeps comments', () => {
+  const sb = sandbox()
+  sb.write('.config/opencode/opencode.jsonc', fixture('opencode.before.jsonc'))
+  client('opencode').connect(sb.ctx)
+  const text = sb.read('.config/opencode/opencode.jsonc')
+  assert.match(text, /\/\/ theme first/)
+  const doc = jsonc.parse(text)
+  assert.deepEqual(doc.mcp.box, { type: 'remote', url: DEFAULT_MCP_URL, enabled: true })
+  assert.ok(doc.mcp.local)
+  assert.equal(sb.read('.config/opencode/opencode.json'), null)
+})
+
+test('vscode: writes servers.box with type http next to other servers', () => {
+  const sb = sandbox()
+  sb.write('.config/Code/User/mcp.json', fixture('vscode.before.json'))
+  client('vscode').connect(sb.ctx)
+  const doc = JSON.parse(sb.read('.config/Code/User/mcp.json'))
+  assert.deepEqual(doc.servers.box, { type: 'http', url: DEFAULT_MCP_URL })
+  assert.ok(doc.servers.playwright)
+  assert.deepEqual(doc.inputs, [])
+})
+
+test('hermes: OAuth entry keeps comments; key mode puts the key only in .env (0600)', () => {
+  const sb = sandbox()
+  sb.write('.hermes/config.yaml', fixture('hermes.before.yaml'))
+  client('hermes').connect(sb.ctx, { mode: 'oauth' })
+  let text = sb.read('.hermes/config.yaml')
+  assert.match(text, /# GitHub server/)
+  assert.deepEqual(YAML.parse(text).mcp_servers.box, { url: DEFAULT_MCP_URL, auth: 'oauth', enabled: true })
+
+  sb.write('.hermes/.env', 'OPENROUTER_API_KEY=sk-other\n', 0o644)
+  client('hermes').connect(sb.ctx, { mode: 'key', key: KEY })
+  text = sb.read('.hermes/config.yaml')
+  assert.ok(!text.includes(KEY), 'the key is never written to config.yaml')
+  assert.deepEqual(YAML.parse(text).mcp_servers.box, { url: DEFAULT_MCP_URL, headers: { Authorization: 'Bearer ${MCP_BOX_API_KEY}' }, enabled: true })
+  assert.equal(sb.read('.hermes/.env'), `OPENROUTER_API_KEY=sk-other\nMCP_BOX_API_KEY=${KEY}\n`)
+  assert.equal(fs.statSync(path.join(sb.home, '.hermes/.env')).mode & 0o777, 0o600)
+  for (const b of backups(path.join(sb.home, '.hermes')).filter((f) => f.startsWith('.env'))) {
+    assert.equal(fs.statSync(path.join(sb.home, '.hermes', b)).mode & 0o777, 0o600, 'a backup of .env is private too')
+  }
+  const st = client('hermes').status(sb.ctx)
+  assert.equal(st.key, KEY)
+  assert.equal(st.entries[0].mode, 'key')
+  // Re-run without a key keeps the stored one.
+  assert.deepEqual(client('hermes').connect(sb.ctx, { mode: 'key' }).actions, [])
+
+  client('hermes').remove(sb.ctx)
+  assert.equal(sb.read('.hermes/.env'), 'OPENROUTER_API_KEY=sk-other\n')
+  assert.equal(YAML.parse(sb.read('.hermes/config.yaml')).mcp_servers.box, undefined)
+  assert.ok(YAML.parse(sb.read('.hermes/config.yaml')).mcp_servers.github)
+})
+
+test('openclaw: OAuth via `openclaw mcp set` with streamable-http; key mode references ${BOX_TOKEN} from .env', () => {
+  const sb = sandbox({ bins: { openclaw: FAKE_OPENCLAW } })
+  client('openclaw').connect(sb.ctx, { mode: 'oauth' })
+  const cfg = () => JSON.parse(sb.read('.openclaw/openclaw.json'))
+  assert.deepEqual(cfg().mcp.servers.box, { url: DEFAULT_MCP_URL, transport: 'streamable-http', auth: 'oauth' })
+
+  client('openclaw').connect(sb.ctx, { mode: 'key', key: KEY })
+  assert.deepEqual(cfg().mcp.servers.box, { url: DEFAULT_MCP_URL, transport: 'streamable-http', headers: { Authorization: 'Bearer ${BOX_TOKEN}' } })
+  assert.ok(!sb.read('.openclaw/openclaw.json').includes(KEY))
+  assert.equal(sb.read('.openclaw/.env'), `BOX_TOKEN=${KEY}\n`)
+  assert.equal(fs.statSync(path.join(sb.home, '.openclaw/.env')).mode & 0o777, 0o600)
+
+  const st = client('openclaw').status(sb.ctx)
+  assert.equal(st.key, KEY)
+  assert.deepEqual(st.warnings, [], '`mcp show` substitutes the key, but status reads the raw file')
+  const setsBefore = sb.read('fake-openclaw-calls.log').split('\n').filter((l) => l.startsWith('mcp set')).length
+  assert.deepEqual(client('openclaw').connect(sb.ctx, { mode: 'key' }).actions, [])
+  const setsAfter = sb.read('fake-openclaw-calls.log').split('\n').filter((l) => l.startsWith('mcp set')).length
+  assert.equal(setsAfter, setsBefore, 'idempotent re-run does not call mcp set')
+
+  client('openclaw').remove(sb.ctx)
+  assert.equal(cfg().mcp.servers.box, undefined)
+  assert.equal(sb.read('.openclaw/.env'), '')
+})
+
+test('openclaw: warns when the header references BOX_TOKEN but .env lacks it (the literal-placeholder 401)', () => {
+  const sb = sandbox({ bins: { openclaw: FAKE_OPENCLAW } })
+  sb.write('.openclaw/openclaw.json', JSON.stringify({ mcp: { servers: { box: { url: DEFAULT_MCP_URL, transport: 'streamable-http', headers: { Authorization: 'Bearer ${BOX_TOKEN}' } } } } }))
+  const st = client('openclaw').status(sb.ctx)
+  assert.match(st.warnings.join(' '), /placeholder and get 401/)
+})
+
+test('claude-code: default URL installs the plugin from the marketplace; override uses claude mcp add', () => {
+  const sb = sandbox({ bins: { claude: FAKE_CLAUDE } })
+  sb.write('.claude.json', JSON.stringify({ mcpServers: { 'box-control': { url: 'x' }, box: { type: 'http', url: DEFAULT_MCP_URL }, other: { command: 'y' } } }))
+  client('claude').connect(sb.ctx)
+  const state = () => JSON.parse(sb.read('fake-claude-state.json'))
+  assert.deepEqual(state().plugins, { 'box@simular-box': { enabled: true } })
+  assert.deepEqual(Object.keys(JSON.parse(sb.read('.claude.json')).mcpServers), ['other'])
+  assert.ok(state().calls.includes('plugin marketplace add simular-ai/box-plugin'))
+  assert.deepEqual(client('claude').connect(sb.ctx).actions, [])
+
+  const ctx = { ...sb.ctx, url: 'https://staging.example.test/mcp' }
+  client('claude').connect(ctx)
+  assert.deepEqual(JSON.parse(sb.read('.claude.json')).mcpServers.box, { type: 'http', url: 'https://staging.example.test/mcp' })
+  assert.equal(state().plugins['box@simular-box'].enabled, false)
+  assert.equal(client('claude').status(ctx).entries.length, 1)
+
+  client('claude').remove(sb.ctx)
+  assert.deepEqual(state().plugins, {})
+  assert.equal(JSON.parse(sb.read('.claude.json')).mcpServers.box, undefined)
+})
+
+test('claude-desktop: writes nothing, prints connector steps', () => {
+  const sb = sandbox()
+  const res = client('claude-desktop').connect(sb.ctx)
+  assert.match(res.next[0], /Add custom connector/)
+  assert.deepEqual(fs.readdirSync(sb.home), ['.bin'])
+})
+
+test('dry run writes nothing for file-based clients', () => {
+  const sb = sandbox()
+  const ctx = { ...sb.ctx, dryRun: true }
+  for (const id of ['cursor', 'codex', 'opencode', 'vscode', 'hermes']) {
+    const res = client(id).connect(ctx, { mode: 'oauth' })
+    assert.ok(res.actions[0].startsWith('would'), id)
+  }
+  assert.deepEqual(fs.readdirSync(sb.home), ['.bin'])
+})
diff --git a/cli/test/fixtures/broken.json b/cli/test/fixtures/broken.json
new file mode 100644
index 0000000..86a71ee
--- /dev/null
+++ b/cli/test/fixtures/broken.json
@@ -0,0 +1 @@
+{ "mcpServers": { "github": { "url": "x" }
diff --git a/cli/test/fixtures/codex.after.toml b/cli/test/fixtures/codex.after.toml
new file mode 100644
index 0000000..f8dff24
--- /dev/null
+++ b/cli/test/fixtures/codex.after.toml
@@ -0,0 +1,12 @@
+# Codex config written by hand
+model = "gpt-5"
+
+[mcp_servers.docs]
+command = "npx"
+args = ["docs-mcp"] # keep this comment
+
+[profiles.fast]
+model = "gpt-5-mini"
+
+[mcp_servers.box]
+url = "https://relay.simular.cloud/mcp"
diff --git a/cli/test/fixtures/codex.before.toml b/cli/test/fixtures/codex.before.toml
new file mode 100644
index 0000000..4efe927
--- /dev/null
+++ b/cli/test/fixtures/codex.before.toml
@@ -0,0 +1,19 @@
+# Codex config written by hand
+model = "gpt-5"
+
+[mcp_servers.docs]
+command = "npx"
+args = ["docs-mcp"] # keep this comment
+
+[mcp_servers.box]
+url = "https://old.example.com/mcp"
+bearer_token_env_var = "OLD"
+
+[mcp_servers.box.tools.shell]
+approval_mode = "approve"
+
+[mcp_servers."box-control"]
+url = "https://relay.simular.cloud/control"
+
+[profiles.fast]
+model = "gpt-5-mini"
diff --git a/cli/test/fixtures/cursor.before.json b/cli/test/fixtures/cursor.before.json
new file mode 100644
index 0000000..7efb675
--- /dev/null
+++ b/cli/test/fixtures/cursor.before.json
@@ -0,0 +1,7 @@
+{
+  // Cursor servers the user already has
+  "mcpServers": {
+    "github": { "url": "https://api.githubcopilot.com/mcp/" },
+    "box-control": { "url": "https://relay.simular.cloud/control" },
+  },
+}
diff --git a/cli/test/fixtures/hermes.before.yaml b/cli/test/fixtures/hermes.before.yaml
new file mode 100644
index 0000000..b38b7a7
--- /dev/null
+++ b/cli/test/fixtures/hermes.before.yaml
@@ -0,0 +1,7 @@
+# Hermes settings
+model:
+  default: anthropic/claude-sonnet-4.5
+mcp_servers:
+  github:
+    command: npx   # GitHub server
+    args: [github-mcp]
diff --git a/cli/test/fixtures/opencode.before.jsonc b/cli/test/fixtures/opencode.before.jsonc
new file mode 100644
index 0000000..ecee7b9
--- /dev/null
+++ b/cli/test/fixtures/opencode.before.jsonc
@@ -0,0 +1,8 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  // theme first
+  "theme": "tokyonight",
+  "mcp": {
+    "local": { "type": "local", "command": ["bun", "x", "my-mcp"] }
+  }
+}
diff --git a/cli/test/fixtures/vscode.before.json b/cli/test/fixtures/vscode.before.json
new file mode 100644
index 0000000..56cddbd
--- /dev/null
+++ b/cli/test/fixtures/vscode.before.json
@@ -0,0 +1,6 @@
+{
+  "inputs": [],
+  "servers": {
+    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }
+  }
+}
diff --git a/cli/test/fsutil.test.js b/cli/test/fsutil.test.js
new file mode 100644
index 0000000..7a00a13
--- /dev/null
+++ b/cli/test/fsutil.test.js
@@ -0,0 +1,39 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { updateFile } from '../src/fsutil.js'
+
+test('updateFile backs up, writes atomically, and is a no-op when nothing changes', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'box-fs-'))
+  const file = path.join(dir, 'a.json')
+  fs.writeFileSync(file, 'old\n', { mode: 0o640 })
+  const first = updateFile(file, () => 'new\n')
+  assert.equal(first.changed, true)
+  assert.equal(fs.readFileSync(first.backup, 'utf8'), 'old\n')
+  assert.equal(fs.readFileSync(file, 'utf8'), 'new\n')
+  assert.equal(fs.statSync(file).mode & 0o777, 0o640)
+  const second = updateFile(file, () => 'new\n')
+  assert.deepEqual(second, { changed: false, backup: null })
+  assert.equal(fs.readdirSync(dir).length, 2)
+})
+
+test('updateFile creates new key files 0600 and tightens existing ones', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'box-fs-'))
+  const fresh = path.join(dir, 'sub', 'new.env')
+  updateFile(fresh, () => 'X=1\n', { mode: 0o600 })
+  assert.equal(fs.statSync(fresh).mode & 0o777, 0o600)
+  const loose = path.join(dir, 'loose.env')
+  fs.writeFileSync(loose, 'A=1\n', { mode: 0o644 })
+  updateFile(loose, (t) => t + 'B=2\n', { mode: 0o600 })
+  assert.equal(fs.statSync(loose).mode & 0o777, 0o600)
+})
+
+test('dry run changes nothing', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'box-fs-'))
+  const file = path.join(dir, 'a.json')
+  const res = updateFile(file, () => 'x', { dryRun: true })
+  assert.equal(res.changed, true)
+  assert.equal(fs.existsSync(file), false)
+})
diff --git a/cli/test/helpers.js b/cli/test/helpers.js
new file mode 100644
index 0000000..e78b001
--- /dev/null
+++ b/cli/test/helpers.js
@@ -0,0 +1,81 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createContext } from '../src/context.js'
+
+export const FIXTURES = path.join(path.dirname(fileURLToPath(import.meta.url)), 'fixtures')
+export const fixture = (name) => fs.readFileSync(path.join(FIXTURES, name), 'utf8')
+
+/** A temporary HOME with an empty bin dir on PATH; nothing outside it is touched. */
+export function sandbox({ env = {}, bins = {} } = {}) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'box-cli-test-'))
+  const bin = path.join(home, '.bin')
+  fs.mkdirSync(bin)
+  for (const [name, source] of Object.entries(bins)) {
+    const file = path.join(bin, name)
+    fs.writeFileSync(file, `#!${process.execPath}\n${source}`, { mode: 0o755 })
+  }
+  const fullEnv = { HOME: home, PATH: bin, ...env }
+  const ctx = createContext({ env: fullEnv, platform: 'linux' })
+  const write = (rel, text, mode) => {
+    const file = path.join(home, rel)
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, text, mode ? { mode } : undefined)
+    return file
+  }
+  const read = (rel) => {
+    try {
+      return fs.readFileSync(path.join(home, rel), 'utf8')
+    } catch {
+      return null
+    }
+  }
+  return { home, ctx, write, read, env: fullEnv }
+}
+
+/** Fake `claude`: records calls and keeps plugin / user-scope server state in $HOME. */
+export const FAKE_CLAUDE = String.raw`
+const fs = require('fs'), path = require('path')
+const home = process.env.HOME
+const stateFile = path.join(home, 'fake-claude-state.json')
+const cfgFile = path.join(home, '.claude.json')
+const state = fs.existsSync(stateFile) ? JSON.parse(fs.readFileSync(stateFile, 'utf8')) : { marketplaces: [], plugins: {}, calls: [] }
+const cfg = fs.existsSync(cfgFile) ? JSON.parse(fs.readFileSync(cfgFile, 'utf8')) : {}
+const a = process.argv.slice(2)
+state.calls.push(a.join(' '))
+const save = () => { fs.writeFileSync(stateFile, JSON.stringify(state)); fs.writeFileSync(cfgFile, JSON.stringify(cfg)) }
+const is = (...w) => w.every((x, i) => a[i] === x)
+if (is('plugin', 'list')) console.log(JSON.stringify(Object.entries(state.plugins).map(([id, p]) => ({ id, enabled: p.enabled, mcpServers: { box: { type: 'http', url: 'https://relay.simular.cloud/mcp' } } }))))
+else if (is('plugin', 'marketplace', 'list')) console.log(JSON.stringify(state.marketplaces.map((name) => ({ name }))))
+else if (is('plugin', 'marketplace', 'add')) state.marketplaces.push('simular-box')
+else if (is('plugin', 'install')) { if (!state.marketplaces.includes('simular-box')) { console.error('marketplace not found'); process.exit(1) } state.plugins[a[2]] = { enabled: true } }
+else if (is('plugin', 'enable')) state.plugins[a[2]].enabled = true
+else if (is('plugin', 'disable')) state.plugins[a[2]].enabled = false
+else if (is('plugin', 'uninstall')) delete state.plugins[a[2]]
+else if (is('mcp', 'add')) { cfg.mcpServers = cfg.mcpServers || {}; cfg.mcpServers[a[a.length - 2]] = { type: 'http', url: a[a.length - 1] } }
+else if (is('mcp', 'remove')) { if (cfg.mcpServers) delete cfg.mcpServers[a[a.length - 1]] }
+else { console.error('unexpected: ' + a.join(' ')); process.exit(2) }
+save()
+`
+
+/** Fake `openclaw`: like the real one, `mcp show` prints values with ${VAR} substituted from .env. */
+export const FAKE_OPENCLAW = String.raw`
+const fs = require('fs'), path = require('path')
+const dir = path.join(process.env.HOME, '.openclaw')
+const file = path.join(dir, 'openclaw.json')
+const calls = path.join(process.env.HOME, 'fake-openclaw-calls.log')
+const a = process.argv.slice(2)
+fs.appendFileSync(calls, a.slice(0, 3).join(' ') + '\n')
+const cfg = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {}
+const servers = (cfg.mcp && cfg.mcp.servers) || {}
+const envText = fs.existsSync(path.join(dir, '.env')) ? fs.readFileSync(path.join(dir, '.env'), 'utf8') : ''
+const sub = (s) => s.replace(/\$\{([A-Z_]+)\}/g, (m, k) => { const r = new RegExp('^' + k + '=(.*)$', 'm').exec(envText); return r ? r[1] : m })
+const save = () => { fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(file, JSON.stringify(cfg, null, 2)) }
+if (a[0] === 'mcp' && a[1] === 'show') { if (!servers[a[2]]) { console.error('unknown'); process.exit(1) } console.log(sub(JSON.stringify(servers[a[2]]))) }
+else if (a[0] === 'mcp' && a[1] === 'set') { cfg.mcp = cfg.mcp || {}; cfg.mcp.servers = { ...servers, [a[2]]: JSON.parse(a[3]) }; save(); console.log('Saved MCP server "' + a[2] + '" to ' + file) }
+else if (a[0] === 'mcp' && a[1] === 'unset') { delete servers[a[2]]; cfg.mcp.servers = servers; save() }
+else if (a[0] === 'mcp' && a[1] === 'reload') {}
+else if (a[0] === 'gateway' && a[1] === 'health') process.exit(1)
+else { console.error('unexpected: ' + a.join(' ')); process.exit(2) }
+`

From a4f0ac804fd5cf03d2e950a5ebb1291648096238 Mon Sep 17 00:00:00 2001
From: chenchen <chenchen@simular.ai>
Date: Tue, 3 Nov 2026 08:21:49 +0800
Subject: [PATCH 2/5] cli: CI with real-client install matrix, live staging
 checks, OIDC publish

- One workflow, publish-cli.yml, modeled on sai-sdk's publish-sai-mcp.yml. It
  replaces release-cli.yml and test-cli.yml:
  - check: lint, test and smoke on Linux, macOS, Windows, plus Node 18
  - plugins: each agent's validator over the plugin folders
  - clients (Layer 1): the real CLI against real Claude Code, Codex, Cursor
    (cursor-agent), OpenCode, Hermes and OpenClaw in an isolated HOME
  - live (Layer 2): a staging key proves Hermes and OpenClaw list box's tools;
    never runs on fork PRs
  - publish: only on cli-v* tags, through npm trusted publishing (OIDC, no
    token) with provenance, then a GitHub release
- Actions pinned by SHA, persist-credentials false, a draft guard and a
  concurrency group.
- Client versions are pinned in cli/e2e/clients.json.
- cross-spawn runs the client CLIs, so Windows .cmd shims get proper quoting.
  The home dir follows os.homedir() on Windows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/publish-cli.yml |  284 ++++++++
 .github/workflows/release-cli.yml |   36 -
 .github/workflows/test-cli.yml    |   26 -
 README.md                         |    2 +-
 cli/README.md                     |   17 +-
 cli/e2e/clients.json              |    9 +
 cli/e2e/install-matrix.mjs        |  130 ++++
 cli/e2e/isolated-env.mjs          |   27 +
 cli/e2e/live.mjs                  |   53 ++
 cli/e2e/mcp-tools.mjs             |   41 ++
 cli/e2e/smoke.mjs                 |   33 +
 cli/eslint.config.js              |   11 +
 cli/package-lock.json             | 1097 +++++++++++++++++++++++++++++
 cli/package.json                  |   10 +-
 cli/src/context.js                |   18 +-
 cli/test/clients.test.js          |   13 +-
 cli/test/fsutil.test.js           |    4 +-
 17 files changed, 1728 insertions(+), 83 deletions(-)
 create mode 100644 .github/workflows/publish-cli.yml
 delete mode 100644 .github/workflows/release-cli.yml
 delete mode 100644 .github/workflows/test-cli.yml
 create mode 100644 cli/e2e/clients.json
 create mode 100644 cli/e2e/install-matrix.mjs
 create mode 100644 cli/e2e/isolated-env.mjs
 create mode 100644 cli/e2e/live.mjs
 create mode 100644 cli/e2e/mcp-tools.mjs
 create mode 100644 cli/e2e/smoke.mjs
 create mode 100644 cli/eslint.config.js

diff --git a/.github/workflows/publish-cli.yml b/.github/workflows/publish-cli.yml
new file mode 100644
index 0000000..0c60528
--- /dev/null
+++ b/.github/workflows/publish-cli.yml
@@ -0,0 +1,284 @@
+name: Publish CLI
+
+# CI + npm publish for @simular-ai/box (cli/). Modeled on simular-ai/sai-sdk's publish-sai-mcp.yml.
+#
+# Every non-draft PR that touches the CLI or a plugin folder runs:
+#   check    lint, unit tests, smoke test on Linux, macOS and Windows (plus Node 18 on Linux)
+#   plugins  each agent's own validator over the plugin folders
+#   clients  Layer 1: the real CLI against each real, installed client in an isolated HOME
+#            (versions pinned in cli/e2e/clients.json). No secrets.
+#   live     Layer 2: a real staging key (secret BOX_CI_KEY, variable BOX_CI_MCP_URL) proves the
+#            headless clients reach box and list its tools. Never on PRs from forks.
+# Publishing happens only when a tag `cli-vX.Y.Z` (or `cli-vX.Y.Z-rc.N`, dist-tag "next") is pushed.
+#
+# Cutting a release: bump "version" in cli/package.json, merge to main, then
+#   git tag cli-v<X.Y.Z> && git push origin cli-v<X.Y.Z>
+#
+# Auth: npm trusted publishing (OIDC). The publish job's `id-token: write` lets the npm CLI swap
+# a GitHub OIDC token for a short-lived publish token: no NPM_TOKEN secret. Requires the
+# trusted-publisher config on npmjs.com (package @simular-ai/box -> Settings -> Trusted
+# Publisher): organization "simular-ai", repository "box-plugin", workflow filename
+# "publish-cli.yml", no environment. npm only lets you configure it on a package that already
+# exists, so the very first version is published once by hand (see cli/README.md).
+# The repo is public, so npm attaches a provenance attestation.
+#
+# TODO(layer 3): nightly run against the latest client versions plus a real agent task on a box.
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, converted_to_draft]
+    paths:
+      - 'cli/**'
+      - 'claude/**'
+      - 'dsh/**'
+      - 'hermes/**'
+      - 'openclaw/**'
+      - '.claude-plugin/**'
+      - '.github/workflows/publish-cli.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'cli/**'
+      - '.github/workflows/publish-cli.yml'
+    tags:
+      - 'cli-v*'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  check:
+    name: Check (${{ matrix.os }}, Node ${{ matrix.node }})
+    # Draft PRs run nothing; `ready_for_review` starts the checks. Non-PR events read `draft` as null.
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node: [24]
+        include:
+          - os: ubuntu-latest
+            node: 18
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    defaults:
+      run:
+        working-directory: cli
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+          cache-dependency-path: cli/package-lock.json
+      - run: npm ci
+      - name: Lint
+        if: matrix.node == 24
+        run: npm run lint
+      - name: Unit tests
+        run: npm test
+      - name: Smoke test
+        run: npm run smoke
+      - name: Pack
+        run: npm pack --dry-run
+
+  plugins:
+    name: Validate plugin folders
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: 24
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - name: Install validators (versions from cli/e2e/clients.json)
+        run: |
+          set -euo pipefail
+          spec() { node -p "require('./cli/e2e/clients.json')['$1'].npm"; }
+          npm install -g "$(spec claude-code)" "$(spec openclaw)"
+          tag=$(node -p "require('./cli/e2e/clients.json').hermes.tag")
+          git clone --quiet --depth 1 --branch "$tag" https://github.com/NousResearch/hermes-agent "$RUNNER_TEMP/hermes"
+          (cd "$RUNNER_TEMP/hermes" && uv sync --frozen --extra mcp --quiet)
+          echo "$RUNNER_TEMP/hermes/.venv/bin" >> "$GITHUB_PATH"
+      - name: Claude Code marketplace and plugin
+        run: |
+          set -euo pipefail
+          export HOME="$(mktemp -d)"
+          claude plugin validate .
+          claude plugin validate ./claude
+      - name: DeepSeek Harness package
+        run: npm pack ./dsh --dry-run
+      - name: Hermes plugin
+        run: |
+          set -euo pipefail
+          if [ ! -d hermes ]; then echo "no hermes/ folder on this ref; skipped"; exit 0; fi
+          export HOME="$(mktemp -d)"
+          hermes plugins validate ./hermes
+      - name: OpenClaw plugin
+        run: |
+          set -euo pipefail
+          if [ ! -d openclaw ]; then echo "no openclaw/ folder on this ref; skipped"; exit 0; fi
+          export HOME="$(mktemp -d)"
+          openclaw plugins install ./openclaw --force --accept-capabilities
+          openclaw plugins inspect box
+          openclaw plugins doctor
+
+  clients:
+    name: Install matrix (${{ matrix.client }}, ${{ matrix.os }})
+    if: github.event_name != 'pull_request' || !github.event.pull_request.draft
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        client: [claude-code, codex, cursor, opencode, hermes, openclaw]
+        exclude:
+          # cursor-agent ships for Linux and macOS only.
+          - os: windows-latest
+            client: cursor
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: cli/package-lock.json
+      - run: npm ci
+        working-directory: cli
+      - name: Install ${{ matrix.client }}
+        env:
+          CLIENT: ${{ matrix.client }}
+        run: |
+          set -euo pipefail
+          get() { node -p "(require('./cli/e2e/clients.json')['$CLIENT'] || {})['$1'] || ''"; }
+          if [ -n "$(get npm)" ]; then
+            npm install -g "$(get npm)"
+          elif [ "$CLIENT" = hermes ]; then
+            git clone --quiet --depth 1 --branch "$(get tag)" "$(get git)" "$RUNNER_TEMP/hermes"
+          elif [ "$CLIENT" = cursor ]; then
+            os=$(uname -s | tr '[:upper:]' '[:lower:]'); arch=$(uname -m)
+            case "$arch" in x86_64|amd64) arch=x64;; arm64|aarch64) arch=arm64;; esac
+            mkdir -p "$RUNNER_TEMP/cursor-agent"
+            curl -fsSL "https://downloads.cursor.com/lab/$(get cursorAgent)/$os/$arch/agent-cli-package.tar.gz" \
+              | tar --strip-components=1 -xzf - -C "$RUNNER_TEMP/cursor-agent"
+            echo "$RUNNER_TEMP/cursor-agent" >> "$GITHUB_PATH"
+          fi
+      - if: matrix.client == 'hermes'
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - name: Install Hermes dependencies
+        if: matrix.client == 'hermes'
+        run: |
+          set -euo pipefail
+          cd "$RUNNER_TEMP/hermes"
+          uv sync --frozen --extra mcp --quiet
+          if [ -d .venv/Scripts ]; then echo "$(cygpath -w "$PWD/.venv/Scripts")" >> "$GITHUB_PATH"; else echo "$PWD/.venv/bin" >> "$GITHUB_PATH"; fi
+      - name: connect, list, re-run, doctor, remove
+        working-directory: cli
+        run: node e2e/install-matrix.mjs ${{ matrix.client }}
+
+  live:
+    name: Live staging (headless clients)
+    # Needs secrets: push to main, tags, manual runs, and PRs from this repository only, never forks.
+    if: >-
+      (github.event_name != 'pull_request' || !github.event.pull_request.draft) &&
+      (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: cli/package-lock.json
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+      - run: npm ci
+        working-directory: cli
+      - name: Install OpenClaw and Hermes
+        run: |
+          set -euo pipefail
+          npm install -g "$(node -p "require('./cli/e2e/clients.json').openclaw.npm")"
+          git clone --quiet --depth 1 --branch "$(node -p "require('./cli/e2e/clients.json').hermes.tag")" https://github.com/NousResearch/hermes-agent "$RUNNER_TEMP/hermes"
+          (cd "$RUNNER_TEMP/hermes" && uv sync --frozen --extra mcp --quiet)
+          echo "$RUNNER_TEMP/hermes/.venv/bin" >> "$GITHUB_PATH"
+      - name: Key valid, clients connect and list box's tools
+        working-directory: cli
+        env:
+          BOX_MCP_URL: ${{ vars.BOX_CI_MCP_URL }}
+          BOX_TOKEN: ${{ secrets.BOX_CI_KEY }}
+        run: |
+          echo "::add-mask::$BOX_TOKEN"
+          node e2e/live.mjs hermes openclaw
+
+  publish:
+    name: Publish to npm
+    needs: [check, plugins, clients]
+    if: startsWith(github.ref, 'refs/tags/cli-v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: write # create the GitHub Release
+      id-token: write # npm trusted publishing (OIDC) and provenance
+    defaults:
+      run:
+        working-directory: cli
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      # No `registry-url`: setup-node would write an .npmrc with `_authToken=${NODE_AUTH_TOKEN}`,
+      # which shadows the OIDC handshake. Node 24 ships npm 11 (trusted publishing needs >= 11.5.1).
+      - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: cli/package-lock.json
+      - run: npm ci
+      - name: Verify tag matches package version and pick the dist-tag
+        id: release
+        run: |
+          set -euo pipefail
+          TAG_NAME="${GITHUB_REF#refs/tags/}"
+          TAG_VERSION="${TAG_NAME#cli-v}"
+          PKG_VERSION="$(node -p "require('./package.json').version")"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag version ($TAG_VERSION) does not match cli/package.json ($PKG_VERSION)." >&2
+            exit 1
+          fi
+          if echo "$TAG_VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "dist-tag=latest" >> "$GITHUB_OUTPUT"
+          elif echo "$TAG_VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+-rc\.[0-9]+$'; then
+            echo "dist-tag=next" >> "$GITHUB_OUTPUT"
+          else
+            echo "::error::Tag '$TAG_NAME' is not a release tag (expected cli-vX.Y.Z or cli-vX.Y.Z-rc.N)." >&2
+            exit 1
+          fi
+      - name: Publish to npmjs.org
+        run: npm publish --provenance --access public --tag "${{ steps.release.outputs.dist-tag }}"
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG_NAME: ${{ github.ref_name }}
+          PRERELEASE_FLAG: ${{ steps.release.outputs.dist-tag == 'next' && '--prerelease' || '' }}
+        run: |
+          gh release create "$TAG_NAME" --title "$TAG_NAME" --generate-notes --latest=false $PRERELEASE_FLAG
diff --git a/.github/workflows/release-cli.yml b/.github/workflows/release-cli.yml
deleted file mode 100644
index 2ab18ec..0000000
--- a/.github/workflows/release-cli.yml
+++ /dev/null
@@ -1,36 +0,0 @@
-name: Release CLI
-
-# Push a tag `cli-vX.Y.Z` that matches cli/package.json's version. The workflow tests the CLI and
-# publishes @simular-ai/box to npm with provenance, then creates a GitHub release.
-# Needs the repository secret NPM_TOKEN (an npm automation token with publish rights on @simular-ai).
-on:
-  push:
-    tags: ['cli-v*']
-
-jobs:
-  release:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      id-token: write # npm provenance
-    defaults:
-      run:
-        working-directory: cli
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 24
-          registry-url: https://registry.npmjs.org
-      - name: Tag matches cli/package.json
-        run: test "cli-v$(node -p "require('./package.json').version")" = "$GITHUB_REF_NAME"
-      - run: npm ci
-      - run: npm test
-      - name: Publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: npm publish --provenance --access public
-      - name: Release
-        env:
-          GH_TOKEN: ${{ github.token }}
-        run: gh release create "$GITHUB_REF_NAME" --title "$GITHUB_REF_NAME" --notes "npx @simular-ai/box connect. See cli/README.md." --latest=false
diff --git a/.github/workflows/test-cli.yml b/.github/workflows/test-cli.yml
deleted file mode 100644
index 1cb5e76..0000000
--- a/.github/workflows/test-cli.yml
+++ /dev/null
@@ -1,26 +0,0 @@
-name: Test CLI
-
-on:
-  pull_request:
-    paths: ['cli/**', '.github/workflows/test-cli.yml']
-  push:
-    branches: [main]
-    paths: ['cli/**']
-
-jobs:
-  test:
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-        node: [18, 24]
-    runs-on: ${{ matrix.os }}
-    defaults:
-      run:
-        working-directory: cli
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node }}
-      - run: npm ci
-      - run: npm test
diff --git a/README.md b/README.md
index ca6b014..2cddbd3 100644
--- a/README.md
+++ b/README.md
@@ -18,4 +18,4 @@ Add a folder named after the agent with its own manifest, MCP config and, where
 
 - `claude/`: bump `version` in `claude/.claude-plugin/plugin.json`; Claude Code picks it up from the marketplace.
 - `dsh/`: bump `version` in `dsh/package.json`, then push a tag `dsh-vX.Y.Z`. The release workflow attaches `dsh-box.tgz`.
-- `cli/`: bump `version` in `cli/package.json`, then push a tag `cli-vX.Y.Z`. The release workflow tests it and publishes `@simular-ai/box` to npm with provenance (needs the `NPM_TOKEN` secret). When the box endpoint moves, change `DEFAULT_MCP_URL` in `cli/src/constants.js` and release.
+- `cli/`: bump `version` in `cli/package.json`, then push a tag `cli-vX.Y.Z`. The `publish-cli.yml` workflow tests it and publishes `@simular-ai/box` to npm through trusted publishing (OIDC), with provenance; the one-time npm setup is in [cli/README.md](cli/README.md#releasing). When the box endpoint moves, change `DEFAULT_MCP_URL` in `cli/src/constants.js` and release.
diff --git a/cli/README.md b/cli/README.md
index cacf868..e998b71 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -66,4 +66,19 @@ node bin/simular-box.js connect --dry-run
 
 Test against a temporary home, never your own configs: `HOME=$(mktemp -d) node bin/simular-box.js connect --client cursor --yes`.
 
-Release: bump `version` in `package.json`, then push a tag `cli-vX.Y.Z`. The release workflow runs the tests and publishes to npm with provenance.
+CI (`.github/workflows/publish-cli.yml`) runs on every non-draft PR:
+- `check`: lint, unit tests and a smoke test on Linux, macOS and Windows.
+- `clients` (Layer 1): installs each real client at the version pinned in `e2e/clients.json`, then runs `e2e/install-matrix.mjs <client>` in an isolated HOME: connect, the client's own listing, re-run, doctor, remove. No secrets.
+- `live` (Layer 2): `e2e/live.mjs` with the staging key. It doesn't run on fork PRs.
+
+Any `e2e/` script can be run locally the same way, with the client on PATH. They never touch your HOME.
+
+### Releasing
+
+Bump `version` in `package.json`, merge, then push a tag `cli-vX.Y.Z`. A `cli-vX.Y.Z-rc.N` tag publishes under the dist-tag `next`. The workflow publishes with npm trusted publishing (OIDC, no token) and provenance, then creates a GitHub release.
+
+One-time setup, done by an owner of the `@simular-ai` npm org:
+
+1. **Publish the first version by hand.** npm can only attach a trusted publisher to a package that already exists. `npm help trust` says: "Package must exist: The package you're configuring must already exist on the npm registry". From `cli/` on `main`, with 2FA: `npm publish --access public`. This version has no provenance, because provenance comes only from CI.
+2. **Add the trusted publisher.** Either on npmjs.com (package → Settings → Trusted Publisher) or with npm >= 11.10.0: `npm trust github @simular-ai/box --repo simular-ai/box-plugin --file publish-cli.yml`. The values are organization `simular-ai`, repository `box-plugin`, workflow `publish-cli.yml`, no environment.
+3. **Push the next tag within 2 days.** A new trusted-publisher configuration expires if its first publish doesn't happen within 2 days.
diff --git a/cli/e2e/clients.json b/cli/e2e/clients.json
new file mode 100644
index 0000000..ebc259c
--- /dev/null
+++ b/cli/e2e/clients.json
@@ -0,0 +1,9 @@
+{
+  "//": "Client versions the CI install matrix tests against. Bump here only.",
+  "claude-code": { "npm": "@anthropic-ai/claude-code@2.1.316" },
+  "codex": { "npm": "@openai/codex@0.166.0" },
+  "opencode": { "npm": "opencode-ai@1.19.5" },
+  "openclaw": { "npm": "openclaw@2026.10.9" },
+  "hermes": { "git": "https://github.com/NousResearch/hermes-agent", "tag": "v0.22.6" },
+  "cursor": { "cursorAgent": "2026.10.22-27dcf5f" }
+}
diff --git a/cli/e2e/install-matrix.mjs b/cli/e2e/install-matrix.mjs
new file mode 100644
index 0000000..30b0faa
--- /dev/null
+++ b/cli/e2e/install-matrix.mjs
@@ -0,0 +1,130 @@
+// Layer 1: run the real CLI against a real, installed client in an isolated HOME.
+//   node e2e/install-matrix.mjs <client>
+// Seeds an unrelated server, runs `connect --client <client> --yes`, checks with the client's own
+// listing command that box is there, re-runs connect (must change nothing), runs `doctor`, then
+// `remove`, and checks that the unrelated server survived. No secrets, no sign-in.
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import spawn from 'cross-spawn'
+import { isolatedEnv } from './isolated-env.mjs'
+import { createContext } from '../src/context.js'
+import { findClient } from '../src/clients/index.js'
+
+const CLI = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'simular-box.js')
+const URL_RE = /relay\.simular\.cloud\/mcp/
+const id = process.argv[2]
+const client = findClient(id)
+if (!client) throw new Error(`unknown client ${id}`)
+
+const { home, env } = isolatedEnv()
+const ctx = createContext({ env })
+console.log(`isolated HOME: ${home}`)
+
+function sh(bin, args, { allowFail = false, timeout = 180000 } = {}) {
+  const res = spawn.sync(bin, args, { env, cwd: home, encoding: 'utf8', timeout })
+  const out = `${res.stdout || ''}${res.stderr || ''}`
+  console.log(`$ ${bin} ${args.join(' ')}  (exit ${res.status})\n${out.trim().split('\n').map((l) => `  ${l}`).join('\n')}`)
+  if (!allowFail && res.status !== 0) throw new Error(`${bin} ${args.join(' ')} failed with exit ${res.status}`)
+  return out
+}
+const box = (...args) => sh(process.execPath, [CLI, ...args])
+const writeJson = (file, value) => {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(value, null, 2))
+}
+function backups() {
+  const found = []
+  const walk = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, e.name)
+      if (e.isDirectory() && !['node_modules', '.git', 'plugins', 'cache'].includes(e.name)) walk(p)
+      else if (e.name.includes('.box-backup-')) found.push(p)
+    }
+  }
+  walk(home)
+  return found.sort()
+}
+
+const ADAPTERS = {
+  'claude-code': {
+    bin: 'claude',
+    seed: () => sh('claude', ['mcp', 'add', '--scope', 'user', '--transport', 'http', 'other', 'https://example.com/mcp']),
+    list: () => sh('claude', ['mcp', 'list']),
+    present: (out) => /plugin:box:box/.test(out) && URL_RE.test(out),
+    needsAuth: /needs authentication/i,
+    otherKept: (out) => /\bother\b/.test(out),
+  },
+  codex: {
+    bin: 'codex',
+    seed: () => sh('codex', ['mcp', 'add', 'other', '--', 'npx', '-y', 'other-mcp']),
+    list: () => sh('codex', ['mcp', 'list']),
+    present: (out) => /^box\s+https:\/\/relay\.simular\.cloud\/mcp/m.test(out),
+    needsAuth: /not logged in/i,
+    otherKept: (out) => /^other\s/m.test(out),
+  },
+  opencode: {
+    bin: 'opencode',
+    seed: () => writeJson(client.configLocation(ctx), { $schema: 'https://opencode.ai/config.json', mcp: { other: { type: 'remote', url: 'https://example.com/mcp', enabled: false } } }),
+    list: () => sh('opencode', ['mcp', 'list']),
+    present: (out) => /\bbox\b/.test(out) && URL_RE.test(out),
+    needsAuth: /needs authentication/i,
+    otherKept: (out) => /\bother\b/.test(out),
+  },
+  openclaw: {
+    bin: 'openclaw',
+    seed: () => sh('openclaw', ['mcp', 'set', 'other', JSON.stringify({ command: 'npx', args: ['-y', 'other-mcp'] })]),
+    list: () => sh('openclaw', ['mcp', 'list']) + sh('openclaw', ['mcp', 'show', 'box', '--json'], { allowFail: true }),
+    present: (out) => /-\s+box\b/.test(out) && /streamable-http/.test(out) && URL_RE.test(out),
+    otherKept: (out) => /-\s+other\b/.test(out),
+  },
+  hermes: {
+    bin: 'hermes',
+    seed: () => {
+      const file = client.configLocation(ctx)
+      fs.mkdirSync(path.dirname(file), { recursive: true })
+      fs.writeFileSync(file, '# seeded by the e2e test\nmcp_servers:\n  other:\n    command: npx\n    args: [-y, other-mcp]\n    enabled: false\n')
+    },
+    list: () => sh('hermes', ['mcp', 'list']),
+    present: (out) => /\bbox\s+https:\/\/relay\.simular/.test(out),
+    otherKept: (out) => /\bother\b/.test(out),
+  },
+  cursor: {
+    bin: 'cursor-agent',
+    seed: () => writeJson(client.configLocation(ctx), { mcpServers: { other: { url: 'https://example.com/mcp' } } }),
+    list: () => sh('cursor-agent', ['mcp', 'list']),
+    present: (out) => /^box:/m.test(out),
+    otherKept: (out) => /^other:/m.test(out),
+  },
+}
+
+const a = ADAPTERS[client.id]
+if (!a) throw new Error(`no install-matrix adapter for ${client.id}`)
+if (!ctx.which(a.bin)) throw new Error(`${a.bin} is not on PATH; install the client first`)
+
+a.seed()
+let out = box('connect', '--client', client.id, '--yes')
+assert.match(out, new RegExp(`${client.name}: `), 'connect reports the client')
+
+out = a.list()
+assert.ok(a.present(out), `${a.bin}'s own listing shows box at the box URL`)
+if (a.needsAuth) assert.match(out, a.needsAuth, 'and says it needs sign-in')
+assert.ok(a.otherKept(out), 'the seeded server is still listed after connect')
+
+const before = backups()
+out = box('connect', '--client', client.id, '--yes')
+assert.match(out, new RegExp(`${client.name}: already set up`), 're-run is a no-op')
+assert.deepEqual(backups(), before, 're-run writes no new backup')
+
+const report = JSON.parse(box('doctor', '--client', client.id, '--json'))
+const row = report.clients[0]
+assert.equal(report.endpoint.ok, true, 'prod endpoint answers 401 + metadata')
+assert.equal(row.configured, true)
+assert.deepEqual(row.problems, [], 'doctor finds no problem')
+
+box('remove', '--client', client.id, '--yes')
+out = a.list()
+assert.ok(!a.present(out), 'box is gone after remove')
+assert.ok(a.otherKept(out), 'the seeded server survived remove')
+console.log(`\nOK: ${client.name} (${a.bin})`)
diff --git a/cli/e2e/isolated-env.mjs b/cli/e2e/isolated-env.mjs
new file mode 100644
index 0000000..31dcd70
--- /dev/null
+++ b/cli/e2e/isolated-env.mjs
@@ -0,0 +1,27 @@
+// An environment whose every home/config/data dir points into a fresh temp dir, so a real
+// client run in CI (or on a laptop) can never read or write the user's own configs.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const STRIP = /^(CLAUDE_CONFIG_DIR|CODEX_HOME|HERMES_HOME|OPENCODE_CONFIG|OPENCODE_CONFIG_DIR|OPENCLAW_.*|XDG_.*|BOX_MCP_URL|BOX_TOKEN|MCP_BOX_API_KEY)$/i
+
+export function isolatedEnv(base = process.env, { keep = [] } = {}) {
+  const home = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'box-e2e-')))
+  const env = {}
+  for (const [k, v] of Object.entries(base)) if (!STRIP.test(k) || keep.includes(k)) env[k] = v
+  Object.assign(env, {
+    HOME: home,
+    USERPROFILE: home,
+    APPDATA: path.join(home, 'AppData', 'Roaming'),
+    LOCALAPPDATA: path.join(home, 'AppData', 'Local'),
+    XDG_CONFIG_HOME: path.join(home, '.config'),
+    XDG_DATA_HOME: path.join(home, '.local', 'share'),
+    XDG_STATE_HOME: path.join(home, '.local', 'state'),
+    XDG_CACHE_HOME: path.join(home, '.cache'),
+    NO_COLOR: '1',
+    CI: base.CI || '1',
+  })
+  for (const d of [env.APPDATA, env.LOCALAPPDATA, env.XDG_CONFIG_HOME, env.XDG_DATA_HOME, env.XDG_STATE_HOME, env.XDG_CACHE_HOME]) fs.mkdirSync(d, { recursive: true })
+  return { home, env }
+}
diff --git a/cli/e2e/live.mjs b/cli/e2e/live.mjs
new file mode 100644
index 0000000..9b8e003
--- /dev/null
+++ b/cli/e2e/live.mjs
@@ -0,0 +1,53 @@
+// Layer 2: with a real staging key, prove each headless client can reach box and list its tools.
+//   BOX_MCP_URL=<staging> BOX_TOKEN=cb_... node e2e/live.mjs [clients...]
+// Uses an isolated HOME. Never prints the key; tool calls are never made.
+import assert from 'node:assert/strict'
+import dns from 'node:dns/promises'
+import net from 'node:net'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import spawn from 'cross-spawn'
+import { isolatedEnv } from './isolated-env.mjs'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const CLI = path.join(HERE, '..', 'bin', 'simular-box.js')
+const url = process.env.BOX_MCP_URL
+const key = process.env.BOX_TOKEN
+if (!url || !key) throw new Error('set BOX_MCP_URL and BOX_TOKEN')
+const clients = process.argv.slice(2).length ? process.argv.slice(2) : ['hermes', 'openclaw']
+
+// A host that resolves to a private address is only reachable on the internal network.
+const { hostname } = new URL(url)
+const addrs = await dns.lookup(hostname, { all: true })
+const isPrivate = (ip) => net.isIPv4(ip) && /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(ip)
+if (addrs.every((a) => isPrivate(a.address))) {
+  throw new Error(`${hostname} resolves to a private address (${addrs.map((a) => a.address).join(', ')}); this runner can't reach it. Point BOX_CI_MCP_URL at a public endpoint or run on a runner inside the network.`)
+}
+
+const { env } = isolatedEnv(process.env, { keep: ['BOX_MCP_URL', 'BOX_TOKEN'] })
+const scrub = (s) => s.split(key).join('***')
+function sh(bin, args, { allowFail = false } = {}) {
+  const res = spawn.sync(bin, args, { env, encoding: 'utf8', timeout: 180000 })
+  const out = scrub(`${res.stdout || ''}${res.stderr || ''}`)
+  console.log(`$ ${bin} ${args.join(' ')}  (exit ${res.status})\n${out.trim().split('\n').map((l) => `  ${l}`).join('\n')}`)
+  if (!allowFail && res.status !== 0) throw new Error(`${bin} ${args.join(' ')} failed`)
+  return out
+}
+
+sh(process.execPath, [path.join(HERE, 'mcp-tools.mjs')])
+sh(process.execPath, [CLI, 'connect', '--client', clients.join(','), '--auth', 'key', '--yes'])
+const report = JSON.parse(sh(process.execPath, [CLI, 'doctor', '--client', clients.join(','), '--json'], { allowFail: true }))
+assert.equal(report.endpoint.ok, true, 'endpoint answers 401 + metadata')
+for (const row of report.clients) {
+  assert.equal(row.key?.valid, true, `${row.name}: the key is valid`)
+  assert.equal(row.ok, true, `${row.name}: doctor is clean (${row.problems.join('; ')})`)
+}
+if (clients.includes('openclaw')) {
+  const out = sh('openclaw', ['mcp', 'probe', 'box'])
+  assert.match(out, /box: [1-9]\d* tools/, 'openclaw lists box tools')
+}
+if (clients.includes('hermes')) {
+  const out = sh('hermes', ['mcp', 'test', 'box'])
+  assert.match(out, /tools? (discovered|found)|✓ Connected/i, 'hermes connects and lists tools')
+}
+console.log('\nOK: live checks passed')
diff --git a/cli/e2e/mcp-tools.mjs b/cli/e2e/mcp-tools.mjs
new file mode 100644
index 0000000..732e9bc
--- /dev/null
+++ b/cli/e2e/mcp-tools.mjs
@@ -0,0 +1,41 @@
+// Minimal MCP client: initialize + tools/list over streamable HTTP with a bearer key.
+// Lists tools only; never calls one (calling would wake the box or act on it).
+//   BOX_MCP_URL=... BOX_TOKEN=cb_... node e2e/mcp-tools.mjs
+const url = process.env.BOX_MCP_URL
+const key = process.env.BOX_TOKEN
+if (!url || !key) throw new Error('set BOX_MCP_URL and BOX_TOKEN')
+
+let session
+async function rpc(method, params, id) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      accept: 'application/json, text/event-stream',
+      authorization: `Bearer ${key}`,
+      ...(session ? { 'mcp-session-id': session } : {}),
+      ...(method !== 'initialize' ? { 'mcp-protocol-version': '2025-06-18' } : {}),
+    },
+    body: JSON.stringify({ jsonrpc: '2.0', method, ...(params ? { params } : {}), ...(id !== undefined ? { id } : {}) }),
+    signal: AbortSignal.timeout(60000),
+  })
+  if (res.status === 401) throw new Error('401: the key was rejected')
+  if (!res.ok && res.status !== 202) throw new Error(`${method}: HTTP ${res.status}`)
+  session = res.headers.get('mcp-session-id') || session
+  if (id === undefined) return null
+  const type = res.headers.get('content-type') || ''
+  const text = await res.text()
+  const messages = type.includes('text/event-stream')
+    ? text.split('\n').filter((l) => l.startsWith('data:')).map((l) => JSON.parse(l.slice(5)))
+    : [JSON.parse(text)]
+  const reply = messages.find((m) => m.id === id)
+  if (!reply) throw new Error(`${method}: no reply`)
+  if (reply.error) throw new Error(`${method}: ${reply.error.message}`)
+  return reply.result
+}
+
+const init = await rpc('initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'box-ci', version: '0' } }, 1)
+await rpc('notifications/initialized')
+const { tools } = await rpc('tools/list', {}, 2)
+console.log(`server ${init.serverInfo?.name} ${init.serverInfo?.version}: ${tools.length} tools: ${tools.map((t) => t.name).join(', ')}`)
+if (!tools.length) throw new Error('no tools listed')
diff --git a/cli/e2e/smoke.mjs b/cli/e2e/smoke.mjs
new file mode 100644
index 0000000..1f25a5a
--- /dev/null
+++ b/cli/e2e/smoke.mjs
@@ -0,0 +1,33 @@
+// Smoke test of the packed CLI entry point in an isolated HOME: version, help, a dry run that
+// must write nothing, and a doctor run that must emit valid JSON.
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+import { createRequire } from 'node:module'
+import { fileURLToPath } from 'node:url'
+import spawn from 'cross-spawn'
+import { isolatedEnv } from './isolated-env.mjs'
+
+const root = path.join(path.dirname(fileURLToPath(import.meta.url)), '..')
+const CLI = path.join(root, 'bin', 'simular-box.js')
+const { version } = createRequire(import.meta.url)(path.join(root, 'package.json'))
+const { home, env } = isolatedEnv()
+const run = (...args) => spawn.sync(process.execPath, [CLI, ...args], { env, encoding: 'utf8' })
+
+let r = run('--version')
+assert.equal(r.status, 0)
+assert.equal(r.stdout.trim(), version)
+r = run('--help')
+assert.equal(r.status, 0)
+assert.match(r.stdout, /npx @simular-ai\/box connect/)
+
+const before = fs.readdirSync(home).sort()
+r = run('connect', '--client', 'cursor,codex,opencode,vscode,hermes', '--yes', '--dry-run')
+assert.equal(r.status, 0, r.stderr)
+assert.match(r.stdout, /would write/)
+assert.deepEqual(fs.readdirSync(home).sort(), before, 'dry run writes nothing')
+
+r = run('doctor', '--client', 'cursor', '--json')
+const report = JSON.parse(r.stdout)
+assert.equal(report.clients[0].configured, false)
+console.log(`smoke OK: simular-box ${version}`)
diff --git a/cli/eslint.config.js b/cli/eslint.config.js
new file mode 100644
index 0000000..285dd51
--- /dev/null
+++ b/cli/eslint.config.js
@@ -0,0 +1,11 @@
+import js from '@eslint/js'
+import globals from 'globals'
+
+export default [
+  js.configs.recommended,
+  {
+    languageOptions: { ecmaVersion: 2022, sourceType: 'module', globals: { ...globals.node } },
+    rules: { 'no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }] },
+  },
+  { ignores: ['node_modules/'] },
+]
diff --git a/cli/package-lock.json b/cli/package-lock.json
index 1b1255c..49a9045 100644
--- a/cli/package-lock.json
+++ b/cli/package-lock.json
@@ -10,6 +10,7 @@
       "license": "MIT",
       "dependencies": {
         "@clack/prompts": "0.11.0",
+        "cross-spawn": "7.0.6",
         "jsonc-parser": "3.3.1",
         "smol-toml": "1.9.1",
         "yaml": "2.9.1"
@@ -17,6 +18,11 @@
       "bin": {
         "simular-box": "bin/simular-box.js"
       },
+      "devDependencies": {
+        "@eslint/js": "9.39.5",
+        "eslint": "9.39.5",
+        "globals": "17.14.0"
+      },
       "engines": {
         "node": ">=18.17"
       }
@@ -42,18 +48,1022 @@
         "sisteransi": "^1.0.5"
       }
     },
+    "node_modules/@eslint-community/eslint-utils": {
+      "version": "4.10.1",
+      "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.10.1.tgz",
+      "integrity": "sha512-cuadcxVFE8sDK6iWJbs8Sn0av2Nrh2QSGQhVlBW9AaAHqHwjWsZHT8LJ4hFGPh7ASBV2deFdM7H/DPjulmh8rg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "eslint-visitor-keys": "^3.4.3"
+      },
+      "engines": {
+        "node": "^12.22.0 || ^14.17.0 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      },
+      "peerDependencies": {
+        "eslint": "^6.0.0 || ^7.0.0 || >=8.0.0"
+      }
+    },
+    "node_modules/@eslint-community/eslint-utils/node_modules/eslint-visitor-keys": {
+      "version": "3.4.3",
+      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-3.4.3.tgz",
+      "integrity": "sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": "^12.22.0 || ^14.17.0 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
+    "node_modules/@eslint-community/regexpp": {
+      "version": "4.12.2",
+      "resolved": "https://registry.npmjs.org/@eslint-community/regexpp/-/regexpp-4.12.2.tgz",
+      "integrity": "sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^12.0.0 || ^14.0.0 || >=16.0.0"
+      }
+    },
+    "node_modules/@eslint/config-array": {
+      "version": "0.21.2",
+      "resolved": "https://registry.npmjs.org/@eslint/config-array/-/config-array-0.21.2.tgz",
+      "integrity": "sha512-nJl2KGTlrf9GjLimgIru+V/mzgSK0ABCDQRvxw5BjURL7WfH5uoWmizbH7QB6MmnMBd8cIC9uceWnezL1VZWWw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@eslint/object-schema": "^2.1.7",
+        "debug": "^4.3.1",
+        "minimatch": "^3.1.5"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@eslint/config-helpers": {
+      "version": "0.4.2",
+      "resolved": "https://registry.npmjs.org/@eslint/config-helpers/-/config-helpers-0.4.2.tgz",
+      "integrity": "sha512-gBrxN88gOIf3R7ja5K9slwNayVcZgK6SOUORm2uBzTeIEfeVaIhOpCtTox3P6R7o2jLFwLFTLnC7kU/RGcYEgw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@eslint/core": "^0.17.0"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@eslint/core": {
+      "version": "0.17.0",
+      "resolved": "https://registry.npmjs.org/@eslint/core/-/core-0.17.0.tgz",
+      "integrity": "sha512-yL/sLrpmtDaFEiUj1osRP4TI2MDz1AddJL+jZ7KSqvBuliN4xqYY54IfdN8qD8Toa6g1iloph1fxQNkjOxrrpQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@types/json-schema": "^7.0.15"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@eslint/eslintrc": {
+      "version": "3.3.7",
+      "resolved": "https://registry.npmjs.org/@eslint/eslintrc/-/eslintrc-3.3.7.tgz",
+      "integrity": "sha512-F42g89Qd5oAWtp0k0nnSrjziAKza7w8SVT4mStc18LZMaRb4J1HQAHLCalEtDCxrTuksx7NU9qsmeLwpOfPqWw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ajv": "^6.14.0",
+        "debug": "^4.3.2",
+        "espree": "^10.0.1",
+        "globals": "^14.0.0",
+        "ignore": "^5.2.0",
+        "import-fresh": "^3.2.1",
+        "js-yaml": "^4.3.2",
+        "minimatch": "^3.1.5",
+        "strip-json-comments": "^3.1.1"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
+    "node_modules/@eslint/eslintrc/node_modules/globals": {
+      "version": "14.0.0",
+      "resolved": "https://registry.npmjs.org/globals/-/globals-14.0.0.tgz",
+      "integrity": "sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/@eslint/js": {
+      "version": "9.39.5",
+      "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.39.5.tgz",
+      "integrity": "sha512-QywQuszQh77pIXCsq998c8hbhSTI/azTty1Z6N53dmAudKHhy573j3yvRLsX2BSp8YpLtoCEG8E9DJe+8zUh4A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://eslint.org/donate"
+      }
+    },
+    "node_modules/@eslint/object-schema": {
+      "version": "2.1.7",
+      "resolved": "https://registry.npmjs.org/@eslint/object-schema/-/object-schema-2.1.7.tgz",
+      "integrity": "sha512-VtAOaymWVfZcmZbp6E2mympDIHvyjXs/12LqWYjVw6qjrfF+VK+fyG33kChz3nnK+SU5/NeHOqrTEHS8sXO3OA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@eslint/plugin-kit": {
+      "version": "0.4.1",
+      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.4.1.tgz",
+      "integrity": "sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@eslint/core": "^0.17.0",
+        "levn": "^0.4.1"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      }
+    },
+    "node_modules/@humanfs/core": {
+      "version": "0.19.2",
+      "resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.2.tgz",
+      "integrity": "sha512-UhXNm+CFMWcbChXywFwkmhqjs3PRCmcSa/hfBgLIb7oQ5HNb1wS0icWsGtSAUNgefHeI+eBrA8I1fxmbHsGdvA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@humanfs/types": "^0.15.0"
+      },
+      "engines": {
+        "node": ">=18.18.0"
+      }
+    },
+    "node_modules/@humanfs/node": {
+      "version": "0.16.8",
+      "resolved": "https://registry.npmjs.org/@humanfs/node/-/node-0.16.8.tgz",
+      "integrity": "sha512-gE1eQNZ3R++kTzFUpdGlpmy8kDZD/MLyHqDwqjkVQI0JMdI1D51sy1H958PNXYkM2rAac7e5/CnIKZrHtPh3BQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@humanfs/core": "^0.19.2",
+        "@humanfs/types": "^0.15.0",
+        "@humanwhocodes/retry": "^0.4.0"
+      },
+      "engines": {
+        "node": ">=18.18.0"
+      }
+    },
+    "node_modules/@humanfs/types": {
+      "version": "0.15.0",
+      "resolved": "https://registry.npmjs.org/@humanfs/types/-/types-0.15.0.tgz",
+      "integrity": "sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18.18.0"
+      }
+    },
+    "node_modules/@humanwhocodes/module-importer": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@humanwhocodes/module-importer/-/module-importer-1.0.1.tgz",
+      "integrity": "sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.22"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/nzakas"
+      }
+    },
+    "node_modules/@humanwhocodes/retry": {
+      "version": "0.4.3",
+      "resolved": "https://registry.npmjs.org/@humanwhocodes/retry/-/retry-0.4.3.tgz",
+      "integrity": "sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=18.18"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/nzakas"
+      }
+    },
+    "node_modules/@types/estree": {
+      "version": "1.0.10",
+      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.10.tgz",
+      "integrity": "sha512-lTyOMnOcmRBzdCv6/4zUZCrEhV0xrqQiUZBZtVcbmLHBXKLnN8q89v/wKRF/Q0HbwVsqbIG3o5HDoFl9sduM+g==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@types/json-schema": {
+      "version": "7.0.15",
+      "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz",
+      "integrity": "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/acorn": {
+      "version": "8.19.0",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.19.0.tgz",
+      "integrity": "sha512-oJlA3XiRm7Cyk6qFD2Jn8ak9B7jSy0qy00ADO3+8dpT0LSjFihQYv4C02LFCSYJV3Q37xYwwRy5m+IpIiUzqWw==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "acorn": "bin/acorn"
+      },
+      "engines": {
+        "node": ">=0.4.0"
+      }
+    },
+    "node_modules/acorn-jsx": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz",
+      "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==",
+      "dev": true,
+      "license": "MIT",
+      "peerDependencies": {
+        "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0"
+      }
+    },
+    "node_modules/ajv": {
+      "version": "6.15.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.15.0.tgz",
+      "integrity": "sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.1",
+        "fast-json-stable-stringify": "^2.0.0",
+        "json-schema-traverse": "^0.4.1",
+        "uri-js": "^4.2.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "dev": true,
+      "license": "Python-2.0"
+    },
+    "node_modules/balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/brace-expansion": {
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.21.tgz",
+      "integrity": "sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "node_modules/callsites": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz",
+      "integrity": "sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/chalk": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz",
+      "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.1.0",
+        "supports-color": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/chalk?sponsor=1"
+      }
+    },
+    "node_modules/color-convert": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
+      "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "color-name": "~1.1.4"
+      },
+      "engines": {
+        "node": ">=7.0.0"
+      }
+    },
+    "node_modules/color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/cross-spawn": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+      "license": "MIT",
+      "dependencies": {
+        "path-key": "^3.1.0",
+        "shebang-command": "^2.0.0",
+        "which": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/debug": {
+      "version": "4.4.3",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+      "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ms": "^2.1.3"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/deep-is": {
+      "version": "0.1.4",
+      "resolved": "https://registry.npmjs.org/deep-is/-/deep-is-0.1.4.tgz",
+      "integrity": "sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/escape-string-regexp": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
+      "integrity": "sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/eslint": {
+      "version": "9.39.5",
+      "resolved": "https://registry.npmjs.org/eslint/-/eslint-9.39.5.tgz",
+      "integrity": "sha512-DgZS62aPLXKlnxILS/AYCoRvHaZeXceIzlXPkkGGzJWSow1aEk0lbTlxUSlyjC8jcaKxAdOnTDz+o1JFSBsyjw==",
+      "deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@eslint-community/eslint-utils": "^4.8.0",
+        "@eslint-community/regexpp": "^4.12.1",
+        "@eslint/config-array": "^0.21.2",
+        "@eslint/config-helpers": "^0.4.2",
+        "@eslint/core": "^0.17.0",
+        "@eslint/eslintrc": "^3.3.6",
+        "@eslint/js": "9.39.5",
+        "@eslint/plugin-kit": "^0.4.1",
+        "@humanfs/node": "^0.16.6",
+        "@humanwhocodes/module-importer": "^1.0.1",
+        "@humanwhocodes/retry": "^0.4.2",
+        "@types/estree": "^1.0.6",
+        "ajv": "^6.14.0",
+        "chalk": "^4.0.0",
+        "cross-spawn": "^7.0.6",
+        "debug": "^4.3.2",
+        "escape-string-regexp": "^4.0.0",
+        "eslint-scope": "^8.4.0",
+        "eslint-visitor-keys": "^4.2.1",
+        "espree": "^10.4.0",
+        "esquery": "^1.5.0",
+        "esutils": "^2.0.2",
+        "fast-deep-equal": "^3.1.3",
+        "file-entry-cache": "^8.0.0",
+        "find-up": "^5.0.0",
+        "glob-parent": "^6.0.2",
+        "ignore": "^5.2.0",
+        "imurmurhash": "^0.1.4",
+        "is-glob": "^4.0.0",
+        "json-stable-stringify-without-jsonify": "^1.0.1",
+        "lodash.merge": "^4.6.2",
+        "minimatch": "^3.1.5",
+        "natural-compare": "^1.4.0",
+        "optionator": "^0.9.3"
+      },
+      "bin": {
+        "eslint": "bin/eslint.js"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://eslint.org/donate"
+      },
+      "peerDependencies": {
+        "jiti": "*"
+      },
+      "peerDependenciesMeta": {
+        "jiti": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/eslint-scope": {
+      "version": "8.4.0",
+      "resolved": "https://registry.npmjs.org/eslint-scope/-/eslint-scope-8.4.0.tgz",
+      "integrity": "sha512-sNXOfKCn74rt8RICKMvJS7XKV/Xk9kA7DyJr8mJik3S7Cwgy3qlkkmyS2uQB3jiJg6VNdZd/pDBJu0nvG2NlTg==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "esrecurse": "^4.3.0",
+        "estraverse": "^5.2.0"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
+    "node_modules/eslint-visitor-keys": {
+      "version": "4.2.1",
+      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz",
+      "integrity": "sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
+    "node_modules/espree": {
+      "version": "10.4.0",
+      "resolved": "https://registry.npmjs.org/espree/-/espree-10.4.0.tgz",
+      "integrity": "sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "acorn": "^8.15.0",
+        "acorn-jsx": "^5.3.2",
+        "eslint-visitor-keys": "^4.2.1"
+      },
+      "engines": {
+        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/eslint"
+      }
+    },
+    "node_modules/esquery": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.7.0.tgz",
+      "integrity": "sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "estraverse": "^5.1.0"
+      },
+      "engines": {
+        "node": ">=0.10"
+      }
+    },
+    "node_modules/esrecurse": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/esrecurse/-/esrecurse-4.3.0.tgz",
+      "integrity": "sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "estraverse": "^5.2.0"
+      },
+      "engines": {
+        "node": ">=4.0"
+      }
+    },
+    "node_modules/estraverse": {
+      "version": "5.3.0",
+      "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz",
+      "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=4.0"
+      }
+    },
+    "node_modules/esutils": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/esutils/-/esutils-2.0.3.tgz",
+      "integrity": "sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fast-json-stable-stringify": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz",
+      "integrity": "sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fast-levenshtein": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz",
+      "integrity": "sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/file-entry-cache": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-8.0.0.tgz",
+      "integrity": "sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "flat-cache": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=16.0.0"
+      }
+    },
+    "node_modules/find-up": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/find-up/-/find-up-5.0.0.tgz",
+      "integrity": "sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "locate-path": "^6.0.0",
+        "path-exists": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/flat-cache": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/flat-cache/-/flat-cache-4.0.1.tgz",
+      "integrity": "sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "flatted": "^3.2.9",
+        "keyv": "^4.5.4"
+      },
+      "engines": {
+        "node": ">=16"
+      }
+    },
+    "node_modules/flatted": {
+      "version": "3.4.4",
+      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.4.4.tgz",
+      "integrity": "sha512-5+ybhBZANEJxaH3X5evAFatUxLfEHSr7n6kYJ+1Qd0mUqr4eu9gIf6GDbWHf8RJijHrjjO8G+la14SlL2SeS1Q==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/glob-parent": {
+      "version": "6.0.2",
+      "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-6.0.2.tgz",
+      "integrity": "sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "is-glob": "^4.0.3"
+      },
+      "engines": {
+        "node": ">=10.13.0"
+      }
+    },
+    "node_modules/globals": {
+      "version": "17.14.0",
+      "resolved": "https://registry.npmjs.org/globals/-/globals-17.14.0.tgz",
+      "integrity": "sha512-UtdkTVyAJePQv0J2M9Xe4L0ruNSDV314XiIJsADI2Zf40bcdAonE/D/OhAU8AT99oij9mhLByb+NvA3QWZYgCg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/has-flag": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz",
+      "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/ignore": {
+      "version": "5.3.2",
+      "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz",
+      "integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 4"
+      }
+    },
+    "node_modules/import-fresh": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/import-fresh/-/import-fresh-3.3.1.tgz",
+      "integrity": "sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "parent-module": "^1.0.0",
+        "resolve-from": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/imurmurhash": {
+      "version": "0.1.4",
+      "resolved": "https://registry.npmjs.org/imurmurhash/-/imurmurhash-0.1.4.tgz",
+      "integrity": "sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.8.19"
+      }
+    },
+    "node_modules/is-extglob": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
+      "integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/is-glob": {
+      "version": "4.0.3",
+      "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
+      "integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-extglob": "^2.1.1"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/isexe": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+      "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+      "license": "ISC"
+    },
+    "node_modules/js-yaml": {
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.2.tgz",
+      "integrity": "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/puzrin"
+        },
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/nodeca"
+        }
+      ],
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
+    "node_modules/json-buffer": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/json-buffer/-/json-buffer-3.0.1.tgz",
+      "integrity": "sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/json-schema-traverse": {
+      "version": "0.4.1",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz",
+      "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/json-stable-stringify-without-jsonify": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz",
+      "integrity": "sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/jsonc-parser": {
       "version": "3.3.1",
       "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz",
       "integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==",
       "license": "MIT"
     },
+    "node_modules/keyv": {
+      "version": "4.5.4",
+      "resolved": "https://registry.npmjs.org/keyv/-/keyv-4.5.4.tgz",
+      "integrity": "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "json-buffer": "3.0.1"
+      }
+    },
+    "node_modules/levn": {
+      "version": "0.4.1",
+      "resolved": "https://registry.npmjs.org/levn/-/levn-0.4.1.tgz",
+      "integrity": "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "prelude-ls": "^1.2.1",
+        "type-check": "~0.4.0"
+      },
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
+    "node_modules/locate-path": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz",
+      "integrity": "sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "p-locate": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/lodash.merge": {
+      "version": "4.6.2",
+      "resolved": "https://registry.npmjs.org/lodash.merge/-/lodash.merge-4.6.2.tgz",
+      "integrity": "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/minimatch": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "brace-expansion": "^1.1.7"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.1.3",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+      "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/natural-compare": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/natural-compare/-/natural-compare-1.4.0.tgz",
+      "integrity": "sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/optionator": {
+      "version": "0.9.4",
+      "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.4.tgz",
+      "integrity": "sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "deep-is": "^0.1.3",
+        "fast-levenshtein": "^2.0.6",
+        "levn": "^0.4.1",
+        "prelude-ls": "^1.2.1",
+        "type-check": "^0.4.0",
+        "word-wrap": "^1.2.5"
+      },
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
+    "node_modules/p-limit": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz",
+      "integrity": "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "yocto-queue": "^0.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/p-locate": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/p-locate/-/p-locate-5.0.0.tgz",
+      "integrity": "sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "p-limit": "^3.0.2"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/parent-module": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz",
+      "integrity": "sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "callsites": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/path-exists": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/path-exists/-/path-exists-4.0.0.tgz",
+      "integrity": "sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/path-key": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
       "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
       "license": "ISC"
     },
+    "node_modules/prelude-ls": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz",
+      "integrity": "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
+    "node_modules/punycode": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz",
+      "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/resolve-from": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz",
+      "integrity": "sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/shebang-command": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+      "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+      "license": "MIT",
+      "dependencies": {
+        "shebang-regex": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/shebang-regex": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/sisteransi": {
       "version": "1.0.5",
       "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz",
@@ -72,6 +1082,80 @@
         "url": "https://github.com/sponsors/cyyynthia"
       }
     },
+    "node_modules/strip-json-comments": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz",
+      "integrity": "sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/supports-color": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
+      "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "has-flag": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/type-check": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz",
+      "integrity": "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "prelude-ls": "^1.2.1"
+      },
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
+    "node_modules/uri-js": {
+      "version": "4.4.1",
+      "resolved": "https://registry.npmjs.org/uri-js/-/uri-js-4.4.1.tgz",
+      "integrity": "sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "dependencies": {
+        "punycode": "^2.1.0"
+      }
+    },
+    "node_modules/which": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/node-which"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/word-wrap": {
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.5.tgz",
+      "integrity": "sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/yaml": {
       "version": "2.9.1",
       "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz",
@@ -86,6 +1170,19 @@
       "funding": {
         "url": "https://github.com/sponsors/eemeli"
       }
+    },
+    "node_modules/yocto-queue": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
+      "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
     }
   }
 }
diff --git a/cli/package.json b/cli/package.json
index 2220e95..5f79d65 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -17,11 +17,14 @@
     "node": ">=18.17"
   },
   "scripts": {
+    "lint": "eslint . --max-warnings 0",
     "test": "node --test",
-    "prepack": "cp ../LICENSE LICENSE"
+    "smoke": "node e2e/smoke.mjs",
+    "prepack": "node -e \"require('fs').copyFileSync('../LICENSE', 'LICENSE')\""
   },
   "dependencies": {
     "@clack/prompts": "0.11.0",
+    "cross-spawn": "7.0.6",
     "jsonc-parser": "3.3.1",
     "smol-toml": "1.9.1",
     "yaml": "2.9.1"
@@ -47,5 +50,10 @@
   ],
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.5",
+    "eslint": "9.39.5",
+    "globals": "17.14.0"
   }
 }
diff --git a/cli/src/context.js b/cli/src/context.js
index aedf58b..eda56de 100644
--- a/cli/src/context.js
+++ b/cli/src/context.js
@@ -1,7 +1,7 @@
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
-import { spawnSync } from 'node:child_process'
+import spawn from 'cross-spawn'
 import { mcpUrl } from './constants.js'
 
 /**
@@ -9,7 +9,8 @@ import { mcpUrl } from './constants.js'
  * point it at a temporary HOME and a fake PATH.
  */
 export function createContext({ env = process.env, platform = process.platform, dryRun = false, log = () => {} } = {}) {
-  const home = env.HOME || env.USERPROFILE || os.homedir()
+  // Match os.homedir(), which the apps themselves use: USERPROFILE on Windows, HOME elsewhere.
+  const home = (platform === 'win32' ? env.USERPROFILE || env.HOME : env.HOME || env.USERPROFILE) || os.homedir()
   const ctx = {
     env,
     home,
@@ -30,19 +31,14 @@ export function createContext({ env = process.env, platform = process.platform,
       return which(bin, env, platform)
     },
     /**
-     * Run a client's own CLI. Arguments are passed as an array (no shell), so nothing is
-     * interpolated. Secrets must never be passed here: they would show up in `ps`.
+     * Run a client's own CLI. Arguments are passed as an array; cross-spawn quotes them for
+     * Windows .cmd shims (npm-installed CLIs), where a plain spawn needs a shell. Secrets must
+     * never be passed here: they would show up in `ps`.
      */
     run(bin, args, { input, timeoutMs = 60000 } = {}) {
       const resolved = ctx.which(bin)
       if (!resolved) return { status: 127, stdout: '', stderr: `${bin} not found` }
-      const res = spawnSync(resolved, args, {
-        env,
-        input,
-        encoding: 'utf8',
-        timeout: timeoutMs,
-        shell: platform === 'win32' && /\.(cmd|bat)$/i.test(resolved),
-      })
+      const res = spawn.sync(resolved, args, { env, input, encoding: 'utf8', timeout: timeoutMs })
       return { status: res.status ?? 1, stdout: res.stdout || '', stderr: res.stderr || String(res.error || '') }
     },
   }
diff --git a/cli/test/clients.test.js b/cli/test/clients.test.js
index e8f95f5..377ea22 100644
--- a/cli/test/clients.test.js
+++ b/cli/test/clients.test.js
@@ -11,6 +11,9 @@ import { FAKE_CLAUDE, FAKE_OPENCLAW, fixture, sandbox } from './helpers.js'
 
 const KEY = 'cb_test_fake_key_123'
 const client = (id) => findClient(id)
+const WIN = process.platform === 'win32'
+// Fake client CLIs are shebang scripts, and Windows has no POSIX file modes.
+const NO_FAKE_BINS = WIN && 'fake CLIs are shebang scripts; Windows runs the real clients in the install matrix'
 const plain = (v) => JSON.parse(JSON.stringify(v))
 const backups = (dir) => fs.readdirSync(dir).filter((f) => f.includes('.box-backup-'))
 
@@ -115,8 +118,8 @@ test('hermes: OAuth entry keeps comments; key mode puts the key only in .env (06
   assert.ok(!text.includes(KEY), 'the key is never written to config.yaml')
   assert.deepEqual(YAML.parse(text).mcp_servers.box, { url: DEFAULT_MCP_URL, headers: { Authorization: 'Bearer ${MCP_BOX_API_KEY}' }, enabled: true })
   assert.equal(sb.read('.hermes/.env'), `OPENROUTER_API_KEY=sk-other\nMCP_BOX_API_KEY=${KEY}\n`)
-  assert.equal(fs.statSync(path.join(sb.home, '.hermes/.env')).mode & 0o777, 0o600)
-  for (const b of backups(path.join(sb.home, '.hermes')).filter((f) => f.startsWith('.env'))) {
+  if (!WIN) assert.equal(fs.statSync(path.join(sb.home, '.hermes/.env')).mode & 0o777, 0o600)
+  for (const b of WIN ? [] : backups(path.join(sb.home, '.hermes')).filter((f) => f.startsWith('.env'))) {
     assert.equal(fs.statSync(path.join(sb.home, '.hermes', b)).mode & 0o777, 0o600, 'a backup of .env is private too')
   }
   const st = client('hermes').status(sb.ctx)
@@ -131,7 +134,7 @@ test('hermes: OAuth entry keeps comments; key mode puts the key only in .env (06
   assert.ok(YAML.parse(sb.read('.hermes/config.yaml')).mcp_servers.github)
 })
 
-test('openclaw: OAuth via `openclaw mcp set` with streamable-http; key mode references ${BOX_TOKEN} from .env', () => {
+test('openclaw: OAuth via `openclaw mcp set` with streamable-http; key mode references ${BOX_TOKEN} from .env', { skip: NO_FAKE_BINS }, () => {
   const sb = sandbox({ bins: { openclaw: FAKE_OPENCLAW } })
   client('openclaw').connect(sb.ctx, { mode: 'oauth' })
   const cfg = () => JSON.parse(sb.read('.openclaw/openclaw.json'))
@@ -156,14 +159,14 @@ test('openclaw: OAuth via `openclaw mcp set` with streamable-http; key mode refe
   assert.equal(sb.read('.openclaw/.env'), '')
 })
 
-test('openclaw: warns when the header references BOX_TOKEN but .env lacks it (the literal-placeholder 401)', () => {
+test('openclaw: warns when the header references BOX_TOKEN but .env lacks it (the literal-placeholder 401)', { skip: NO_FAKE_BINS }, () => {
   const sb = sandbox({ bins: { openclaw: FAKE_OPENCLAW } })
   sb.write('.openclaw/openclaw.json', JSON.stringify({ mcp: { servers: { box: { url: DEFAULT_MCP_URL, transport: 'streamable-http', headers: { Authorization: 'Bearer ${BOX_TOKEN}' } } } } }))
   const st = client('openclaw').status(sb.ctx)
   assert.match(st.warnings.join(' '), /placeholder and get 401/)
 })
 
-test('claude-code: default URL installs the plugin from the marketplace; override uses claude mcp add', () => {
+test('claude-code: default URL installs the plugin from the marketplace; override uses claude mcp add', { skip: NO_FAKE_BINS }, () => {
   const sb = sandbox({ bins: { claude: FAKE_CLAUDE } })
   sb.write('.claude.json', JSON.stringify({ mcpServers: { 'box-control': { url: 'x' }, box: { type: 'http', url: DEFAULT_MCP_URL }, other: { command: 'y' } } }))
   client('claude').connect(sb.ctx)
diff --git a/cli/test/fsutil.test.js b/cli/test/fsutil.test.js
index 7a00a13..95694cb 100644
--- a/cli/test/fsutil.test.js
+++ b/cli/test/fsutil.test.js
@@ -13,13 +13,13 @@ test('updateFile backs up, writes atomically, and is a no-op when nothing change
   assert.equal(first.changed, true)
   assert.equal(fs.readFileSync(first.backup, 'utf8'), 'old\n')
   assert.equal(fs.readFileSync(file, 'utf8'), 'new\n')
-  assert.equal(fs.statSync(file).mode & 0o777, 0o640)
+  if (process.platform !== 'win32') assert.equal(fs.statSync(file).mode & 0o777, 0o640)
   const second = updateFile(file, () => 'new\n')
   assert.deepEqual(second, { changed: false, backup: null })
   assert.equal(fs.readdirSync(dir).length, 2)
 })
 
-test('updateFile creates new key files 0600 and tightens existing ones', () => {
+test('updateFile creates new key files 0600 and tightens existing ones', { skip: process.platform === 'win32' && 'no POSIX file modes on Windows' }, () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'box-fs-'))
   const fresh = path.join(dir, 'sub', 'new.env')
   updateFile(fresh, () => 'X=1\n', { mode: 0o600 })

From 1b5d218c7634b0203a71b40888904a10ac009a84 Mon Sep 17 00:00:00 2001
From: chenchen <chenchen@simular.ai>
Date: Tue, 3 Nov 2026 08:33:43 +0800
Subject: [PATCH 3/5] cli: fix Windows test isolation, keep CRLF in TOML and
 JSON edits

- Unit-test sandbox sets USERPROFILE, APPDATA and LOCALAPPDATA. On Windows,
  libuv copies USERPROFILE from the parent into a child env that lacks it, so
  the spawned CLI was writing to the runner's real profile.
- The install matrix sets CODEX_HOME for Codex on Windows. Codex finds its home
  through the OS profile API and ignores USERPROFILE.
- TOML and JSONC edits keep the file's line endings. Removing the last TOML
  table keeps the final newline.
- Test fixtures are checked out with LF line endings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 cli/.gitattributes         |  1 +
 cli/e2e/install-matrix.mjs |  7 +++++++
 cli/src/formats.js         | 23 +++++++++++++++--------
 cli/test/clients.test.js   |  9 +++++++++
 cli/test/helpers.js        | 11 ++++++++++-
 5 files changed, 42 insertions(+), 9 deletions(-)
 create mode 100644 cli/.gitattributes

diff --git a/cli/.gitattributes b/cli/.gitattributes
new file mode 100644
index 0000000..36fcc5d
--- /dev/null
+++ b/cli/.gitattributes
@@ -0,0 +1 @@
+test/fixtures/** text eol=lf
diff --git a/cli/e2e/install-matrix.mjs b/cli/e2e/install-matrix.mjs
index 30b0faa..6caf83c 100644
--- a/cli/e2e/install-matrix.mjs
+++ b/cli/e2e/install-matrix.mjs
@@ -19,6 +19,13 @@ const client = findClient(id)
 if (!client) throw new Error(`unknown client ${id}`)
 
 const { home, env } = isolatedEnv()
+if (client.id === 'codex' && process.platform === 'win32') {
+  // On Windows, Codex finds the home folder through the OS profile API, not USERPROFILE, so a
+  // temp HOME alone would point it at the runner's real profile. CODEX_HOME is its own override,
+  // which the CLI honours too.
+  env.CODEX_HOME = path.join(home, '.codex')
+  fs.mkdirSync(env.CODEX_HOME, { recursive: true })
+}
 const ctx = createContext({ env })
 console.log(`isolated HOME: ${home}`)
 
diff --git a/cli/src/formats.js b/cli/src/formats.js
index f045dec..4d7d180 100644
--- a/cli/src/formats.js
+++ b/cli/src/formats.js
@@ -25,9 +25,10 @@ export function parseJsonc(text, file = 'config') {
 export function setJsoncPath(text, jsonPath, value, file) {
   const base = text === null || text.trim() === '' ? '{}\n' : text
   parseJsonc(base, file)
-  const edits = jsonc.modify(base, jsonPath, value, FORMAT)
+  const eol = /\r\n/.test(base) ? '\r\n' : '\n'
+  const edits = jsonc.modify(base, jsonPath, value, { formattingOptions: { ...FORMAT.formattingOptions, eol } })
   let out = jsonc.applyEdits(base, edits)
-  if (!out.endsWith('\n')) out += '\n'
+  if (!out.endsWith('\n')) out += eol
   return out
 }
 
@@ -138,12 +139,12 @@ function splitDotted(key) {
   return parts
 }
 
-const HEADER = /^\s*\[(\[?)\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$/
+const HEADER = /^\s*\[(\[?)\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?\r?$/
 
 /** Remove `[table]` blocks whose key path starts with any of `prefixes` (arrays of key parts). */
 export function removeTomlTables(text, prefixes) {
   if (!text) return text
-  const lines = text.split('\n')
+  const lines = text.split('\n') // a CRLF line keeps its \r, which HEADER tolerates
   const out = []
   let dropping = false
   for (const line of lines) {
@@ -154,7 +155,11 @@ export function removeTomlTables(text, prefixes) {
     }
     if (!dropping) out.push(line)
   }
-  return out.join('\n')
+  // A dropped block at the end also drops the file's final newline: restore it.
+  const eol = /\r\n/.test(text) ? '\r\n' : '\n'
+  let result = out.join('\n').replace(/\r$/, '')
+  if (/\n$/.test(text) && !/\n$/.test(result) && result) result += eol
+  return result
 }
 
 const tomlString = (s) => JSON.stringify(s)
@@ -175,10 +180,12 @@ export function upsertTomlServer(text, name, fields, { legacy = [], file } = {})
       throw new Error(`${file} defines mcp_servers.${n} inline; remove it by hand, then run again`)
     }
   }
+  // Keep the file's line endings (CRLF on Windows-edited files).
+  const eol = /\r\n/.test(text || '') ? '\r\n' : '\n'
   const body = Object.entries(fields)
     .map(([k, v]) => `${k} = ${tomlString(v)}`)
-    .join('\n')
-  out = `${out.replace(/\s*$/, '')}${out.trim() ? '\n\n' : ''}[mcp_servers.${name}]\n${body}\n`
+    .join(eol)
+  out = `${out.replace(/\s*$/, '')}${out.trim() ? eol + eol : ''}[mcp_servers.${name}]${eol}${body}${eol}`
   const final = parseToml(out, file)
   if (!sameValue(final.mcp_servers?.[name], fields)) throw new Error(`could not update ${file} safely; nothing was written`)
   return out
@@ -188,7 +195,7 @@ export function removeTomlServers(text, names, { file } = {}) {
   if (!text) return text
   const doc = parseToml(text, file)
   if (!names.some((n) => doc.mcp_servers?.[n] !== undefined)) return text
-  const out = removeTomlTables(text, names.map((n) => ['mcp_servers', n])).replace(/\n{3,}/g, '\n\n')
+  const out = removeTomlTables(text, names.map((n) => ['mcp_servers', n])).replace(/(\r?\n){3,}/g, (m) => (m.includes('\r') ? '\r\n\r\n' : '\n\n'))
   const check = parseToml(out, file)
   for (const n of names) {
     if (check.mcp_servers?.[n] !== undefined) throw new Error(`${file} defines mcp_servers.${n} inline; remove it by hand`)
diff --git a/cli/test/clients.test.js b/cli/test/clients.test.js
index 377ea22..a7531ae 100644
--- a/cli/test/clients.test.js
+++ b/cli/test/clients.test.js
@@ -66,6 +66,15 @@ test('codex: rewrites only [mcp_servers.box] (and its subtables), keeps comments
   assert.match(sb.read('.codex/config.toml'), /# keep this comment/)
 })
 
+test('codex: keeps CRLF line endings', () => {
+  const sb = sandbox()
+  sb.write('.codex/config.toml', 'model = "gpt-5"\r\n\r\n[mcp_servers.box]\r\nurl = "https://old"\r\n\r\n[profiles.x]\r\nmodel = "m"\r\n')
+  client('codex').connect(sb.ctx)
+  assert.equal(sb.read('.codex/config.toml'), 'model = "gpt-5"\r\n\r\n[profiles.x]\r\nmodel = "m"\r\n\r\n[mcp_servers.box]\r\nurl = "https://relay.simular.cloud/mcp"\r\n')
+  client('codex').remove(sb.ctx)
+  assert.equal(sb.read('.codex/config.toml'), 'model = "gpt-5"\r\n\r\n[profiles.x]\r\nmodel = "m"\r\n')
+})
+
 test('codex: honours CODEX_HOME', () => {
   const sb = sandbox()
   const codexHome = path.join(sb.home, 'elsewhere')
diff --git a/cli/test/helpers.js b/cli/test/helpers.js
index e78b001..ccffbd6 100644
--- a/cli/test/helpers.js
+++ b/cli/test/helpers.js
@@ -16,7 +16,16 @@ export function sandbox({ env = {}, bins = {} } = {}) {
     const file = path.join(bin, name)
     fs.writeFileSync(file, `#!${process.execPath}\n${source}`, { mode: 0o755 })
   }
-  const fullEnv = { HOME: home, PATH: bin, ...env }
+  // On Windows, libuv copies USERPROFILE (and a few others) from the parent into a child env
+  // that lacks them, so point every home-like variable into the sandbox explicitly.
+  const fullEnv = {
+    HOME: home,
+    USERPROFILE: home,
+    APPDATA: path.join(home, 'AppData', 'Roaming'),
+    LOCALAPPDATA: path.join(home, 'AppData', 'Local'),
+    PATH: bin,
+    ...env,
+  }
   const ctx = createContext({ env: fullEnv, platform: 'linux' })
   const write = (rel, text, mode) => {
     const file = path.join(home, rel)

From 04c9bc61e1efca36a1ebd9c15bafeb763a4e4bb6 Mon Sep 17 00:00:00 2001
From: chenchen <chenchen@simular.ai>
Date: Tue, 3 Nov 2026 08:39:40 +0800
Subject: [PATCH 4/5] cli: never touch someone else's "box"; symlinks, key
 backups, publish gating

- connect and remove act only on servers whose URL host is box by Simular:
  relay.simular.cloud, the staging relay, mcp.box.simular.ai, or the host in
  BOX_MCP_URL.
  - Any other server named box (e.g. box.com's MCP server) stops connect with
    a clear message and is left alone by remove.
  - --name installs box under another name.
  - Legacy box-control entries are removed only if they are ours.
  - Applies to every client, including Claude Code's user scope.
- Codex keeps other settings and subtables of our own table, such as tool
  approvals and timeouts. When a table is removed, the comment and blank lines
  above the next table stay with it.
- Writes go through symlinks to the real file, so the link survives.
- .env files that hold keys get no backup, so rotation and remove leave no old
  key on disk.
- The publish job runs in the GitHub environment "npm" and refuses tags that
  are not on main.
- The live job skips with a notice when the endpoint is unreachable from the
  runner (staging resolves to a private address).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/publish-cli.yml   |  21 ++++-
 cli/README.md                       |   6 +-
 cli/e2e/live.mjs                    |  22 +++++-
 cli/src/args.js                     |   5 +-
 cli/src/cli.js                      |  15 +++-
 cli/src/clients/claude-code.js      |  57 ++++++++------
 cli/src/clients/codex.js            |  32 +++++---
 cli/src/clients/cursor.js           |   2 +-
 cli/src/clients/hermes.js           |  33 ++++----
 cli/src/clients/json-client.js      |  66 ++++++++--------
 cli/src/clients/openclaw.js         |  39 ++++++----
 cli/src/clients/opencode.js         |   2 +-
 cli/src/clients/vscode.js           |   2 +-
 cli/src/constants.js                |  36 +++++++++
 cli/src/context.js                  |  10 ++-
 cli/src/formats.js                  |  58 ++++++++++----
 cli/src/fsutil.js                   |  10 ++-
 cli/test/cli.test.js                |   2 +-
 cli/test/clients.test.js            | 115 +++++++++++++++++++++++++++-
 cli/test/fixtures/codex.after.toml  |   5 ++
 cli/test/fixtures/codex.before.toml |   4 +-
 21 files changed, 401 insertions(+), 141 deletions(-)

diff --git a/.github/workflows/publish-cli.yml b/.github/workflows/publish-cli.yml
index 0c60528..cc67c2c 100644
--- a/.github/workflows/publish-cli.yml
+++ b/.github/workflows/publish-cli.yml
@@ -15,11 +15,14 @@ name: Publish CLI
 #   git tag cli-v<X.Y.Z> && git push origin cli-v<X.Y.Z>
 #
 # Auth: npm trusted publishing (OIDC). The publish job's `id-token: write` lets the npm CLI swap
-# a GitHub OIDC token for a short-lived publish token: no NPM_TOKEN secret. Requires the
-# trusted-publisher config on npmjs.com (package @simular-ai/box -> Settings -> Trusted
-# Publisher): organization "simular-ai", repository "box-plugin", workflow filename
-# "publish-cli.yml", no environment. npm only lets you configure it on a package that already
+# a GitHub OIDC token for a short-lived publish token, so no long-lived npm token is stored.
+# Requires the trusted-publisher config on npmjs.com (package @simular-ai/box -> Settings ->
+# Trusted Publisher): organization "simular-ai", repository "box-plugin", workflow filename
+# "publish-cli.yml", environment "npm". npm only lets you configure it on a package that already
 # exists, so the very first version is published once by hand (see cli/README.md).
+#
+# Gating: the publish job runs in the GitHub environment "npm" (add required reviewers there)
+# and refuses a tag whose commit is not on main. A tag ruleset on `cli-v*` limits who can push one.
 # The repo is public, so npm attaches a provenance attestation.
 #
 # TODO(layer 3): nightly run against the latest client versions plus a real agent task on a box.
@@ -236,6 +239,7 @@ jobs:
     if: startsWith(github.ref, 'refs/tags/cli-v')
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    environment: npm
     permissions:
       contents: write # create the GitHub Release
       id-token: write # npm trusted publishing (OIDC) and provenance
@@ -246,6 +250,15 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           persist-credentials: false
+          fetch-depth: 0
+      - name: Tagged commit is on main
+        run: |
+          set -euo pipefail
+          git fetch --quiet origin main
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::$GITHUB_REF_NAME points at $GITHUB_SHA, which is not on main. Tag a commit on main." >&2
+            exit 1
+          fi
       # No `registry-url`: setup-node would write an .npmrc with `_authToken=${NODE_AUTH_TOKEN}`,
       # which shadows the OIDC handshake. Node 24 ships npm 11 (trusted publishing needs >= 11.5.1).
       - uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
diff --git a/cli/README.md b/cli/README.md
index e998b71..69fb8ee 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -30,6 +30,8 @@ The command is `simular-box` (`box` belongs to box.com's CLI), so after `npm i -
 
 Pick apps without prompts with `--client cursor,codex --yes`; `--yes` alone picks every app found. `--dry-run` shows what would change.
 
+The CLI only changes or removes a server that points at box by Simular (`relay.simular.cloud`, its staging host, `mcp.box.simular.ai`, or your `BOX_MCP_URL`). If an app already has a different server named `box`, such as box.com's MCP server, `connect` stops without changing anything, and `remove` leaves it alone. To add box next to it, use `--name simular-box`. A symlinked config stays a symlink: the file it points to is updated.
+
 ## Sign-in
 
 Every app signs in with OAuth by default: the app opens a browser page, you sign in to box and click Approve. No key to copy.
@@ -41,7 +43,7 @@ Hermes and OpenClaw often run around the clock on a server, where an expired OAu
 BOX_TOKEN=cb_... npx @simular-ai/box connect --client hermes,openclaw --auth key
 ```
 
-Without `BOX_TOKEN`, an interactive run asks for the key with hidden input. The key is never accepted as a command-line argument and never printed. It goes only where the app reads secrets: `MCP_BOX_API_KEY` in `$HERMES_HOME/.env`, `BOX_TOKEN` in `~/.openclaw/.env` (both `0600`). The app config holds only a `${...}` reference to it. OpenClaw's Gateway reads `.env` only at start, and a running Hermes gateway keeps the old key, so connect restarts them when the key changes.
+Without `BOX_TOKEN`, an interactive run asks for the key with hidden input. The key is never accepted as a command-line argument and never printed. It goes only where the app reads secrets: `MCP_BOX_API_KEY` in `$HERMES_HOME/.env`, `BOX_TOKEN` in `~/.openclaw/.env` (both `0600`). The app config holds only a `${...}` reference to it. No backup is kept of those `.env` files, because a backup would keep an old or removed key on disk. OpenClaw's Gateway reads `.env` only at start, and a running Hermes gateway keeps the old key, so connect restarts them when the key changes.
 
 ## Doctor
 
@@ -80,5 +82,5 @@ Bump `version` in `package.json`, merge, then push a tag `cli-vX.Y.Z`. A `cli-vX
 One-time setup, done by an owner of the `@simular-ai` npm org:
 
 1. **Publish the first version by hand.** npm can only attach a trusted publisher to a package that already exists. `npm help trust` says: "Package must exist: The package you're configuring must already exist on the npm registry". From `cli/` on `main`, with 2FA: `npm publish --access public`. This version has no provenance, because provenance comes only from CI.
-2. **Add the trusted publisher.** Either on npmjs.com (package → Settings → Trusted Publisher) or with npm >= 11.10.0: `npm trust github @simular-ai/box --repo simular-ai/box-plugin --file publish-cli.yml`. The values are organization `simular-ai`, repository `box-plugin`, workflow `publish-cli.yml`, no environment.
+2. **Add the trusted publisher.** Either on npmjs.com (package → Settings → Trusted Publisher) or with npm >= 11.10.0: `npm trust github @simular-ai/box --repo simular-ai/box-plugin --file publish-cli.yml --env npm`. The values are organization `simular-ai`, repository `box-plugin`, workflow `publish-cli.yml`, environment `npm`.
 3. **Push the next tag within 2 days.** A new trusted-publisher configuration expires if its first publish doesn't happen within 2 days.
diff --git a/cli/e2e/live.mjs b/cli/e2e/live.mjs
index 9b8e003..440df6d 100644
--- a/cli/e2e/live.mjs
+++ b/cli/e2e/live.mjs
@@ -16,12 +16,26 @@ const key = process.env.BOX_TOKEN
 if (!url || !key) throw new Error('set BOX_MCP_URL and BOX_TOKEN')
 const clients = process.argv.slice(2).length ? process.argv.slice(2) : ['hermes', 'openclaw']
 
-// A host that resolves to a private address is only reachable on the internal network.
+// Skip, loudly, when this runner can't reach the endpoint at all (e.g. a staging host that only
+// resolves to a private address): that is a setup choice, not a box or CLI failure.
+function skip(why) {
+  const msg = `Live checks skipped: ${why}. Options: run against prod with a dedicated test key, use a self-hosted runner inside the network, or expose a public staging MCP host.`
+  console.log(process.env.GITHUB_ACTIONS ? `::notice title=Live checks skipped::${msg}` : msg)
+  process.exit(0)
+}
 const { hostname } = new URL(url)
-const addrs = await dns.lookup(hostname, { all: true })
+let addrs
+try {
+  addrs = await dns.lookup(hostname, { all: true })
+} catch (err) {
+  skip(`${hostname} does not resolve here (${err.code})`)
+}
 const isPrivate = (ip) => net.isIPv4(ip) && /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/.test(ip)
-if (addrs.every((a) => isPrivate(a.address))) {
-  throw new Error(`${hostname} resolves to a private address (${addrs.map((a) => a.address).join(', ')}); this runner can't reach it. Point BOX_CI_MCP_URL at a public endpoint or run on a runner inside the network.`)
+if (addrs.every((a) => isPrivate(a.address))) skip(`${hostname} resolves only to private addresses (${addrs.map((a) => a.address).join(', ')})`)
+try {
+  await fetch(url, { method: 'POST', signal: AbortSignal.timeout(15000) })
+} catch (err) {
+  skip(`${url} is unreachable from this runner (${err.cause?.code || err.name})`)
 }
 
 const { env } = isolatedEnv(process.env, { keep: ['BOX_MCP_URL', 'BOX_TOKEN'] })
diff --git a/cli/src/args.js b/cli/src/args.js
index 711f2ee..2a07ec1 100644
--- a/cli/src/args.js
+++ b/cli/src/args.js
@@ -1,6 +1,6 @@
 // Tiny argument parser: no dependency for a handful of flags.
 const BOOLEAN = new Set(['yes', 'json', 'dry-run', 'help', 'version', 'all'])
-const VALUE = new Set(['client', 'auth'])
+const VALUE = new Set(['client', 'auth', 'name'])
 const ALIASES = { y: 'yes', h: 'help', v: 'version', c: 'client' }
 
 export function parseArgs(argv) {
@@ -24,7 +24,8 @@ export function parseArgs(argv) {
       else if (VALUE.has(name)) {
         if (value === undefined) value = argv[++i]
         if (value === undefined || value.startsWith('-')) throw new Error(`--${name} needs a value`)
-        if (name === 'auth') {
+        if (name === 'name') out.flags.name = value
+        else if (name === 'auth') {
           if (value !== 'oauth' && value !== 'key') throw new Error('--auth must be oauth or key')
           out.flags.auth = value
         } else out.flags[name] = [...(out.flags[name] || []), ...value.split(',').map((s) => s.trim()).filter(Boolean)]
diff --git a/cli/src/cli.js b/cli/src/cli.js
index 90961a7..8498d5e 100644
--- a/cli/src/cli.js
+++ b/cli/src/cli.js
@@ -3,7 +3,7 @@ import * as p from '@clack/prompts'
 import { parseArgs } from './args.js'
 import { createContext } from './context.js'
 import { CLIENTS, findClient } from './clients/index.js'
-import { DEFAULT_MCP_URL, KEY_ENV, KEYS_URL, WATCH_URL, INSTALL_URL, SUPPORT_EMAIL, looksLikeKey } from './constants.js'
+import { DEFAULT_MCP_URL, KEY_ENV, KEYS_URL, WATCH_URL, INSTALL_URL, SUPPORT_EMAIL, looksLikeKey, validServerName } from './constants.js'
 import { probeEndpoint, checkKey } from './probe.js'
 
 const VERSION = createRequire(import.meta.url)('../package.json').version
@@ -19,6 +19,7 @@ Clients: ${CLIENTS.map((c) => c.id).join(', ')}
 
 Options:
   -c, --client <ids>  Comma-separated client ids (default: pick from the detected ones)
+      --name <name>   Server name to use instead of "box" (when another "box" server exists)
       --auth key      Hermes and OpenClaw: use a personal key instead of OAuth (for
                       always-on servers with no browser). Other apps always use OAuth.
   -y, --yes           Don't ask; with no --client, use every detected client
@@ -41,7 +42,7 @@ export async function main(argv, { env = process.env, stdout = process.stdout, i
     stdout.write(HELP)
     return args.command || args.flags.help ? 0 : 1
   }
-  const ctx = createContext({ env, dryRun: Boolean(args.flags['dry-run']) })
+  const ctx = createContext({ env, dryRun: Boolean(args.flags['dry-run']), serverName: args.flags.name ? validServerName(args.flags.name) : undefined })
   const interactive = isTTY && !args.flags.yes && !args.flags.json
   switch (args.command) {
     case 'connect':
@@ -229,6 +230,7 @@ async function remove(ctx, flags, { interactive }) {
       const res = await client.remove(ctx)
       p.log.success(`${client.name}: ${res.actions.length ? res.actions.join('; ') : 'nothing to remove'}`)
       for (const b of res.backups || []) p.log.message(`  backup: ${b}`)
+      for (const w of res.warnings || []) p.log.warn(`  ${w}`)
       for (const n of res.next || []) p.log.info(`  ${n}`)
     } catch (err) {
       failed++
@@ -263,11 +265,16 @@ export async function runDoctor(ctx, flags, { probe = probeEndpoint, check = che
       row.ok = true
       continue
     }
+    if (st.foreign) {
+      row.problems.push(`a server named "${ctx.name}" in ${st.foreign.where} points at ${st.foreign.url}, which is not box by Simular`)
+      row.fixes.push(`npx @simular-ai/box connect --client ${client.id} --name simular-box`)
+    }
     row.entries = st.entries.map(({ where, url, enabled }) => ({ where, url: url || null, enabled: enabled !== false }))
     row.configured = st.entries.length > 0
     const keyMode = st.entries.some((e) => e.mode === 'key')
-    const fix = `npx @simular-ai/box connect --client ${client.id}${keyMode ? ' --auth key' : ''}`
-    if (!row.configured) {
+    const nameFlag = ctx.name !== 'box' ? ` --name ${ctx.name}` : ''
+    const fix = `npx @simular-ai/box connect --client ${client.id}${nameFlag}${keyMode ? ' --auth key' : ''}`
+    if (!row.configured && !st.foreign) {
       row.problems.push('box is not configured')
       row.fixes.push(fix)
     }
diff --git a/cli/src/clients/claude-code.js b/cli/src/clients/claude-code.js
index 3e192dc..a2023cf 100644
--- a/cli/src/clients/claude-code.js
+++ b/cli/src/clients/claude-code.js
@@ -5,7 +5,7 @@
 // Docs: https://code.claude.com/docs/en/mcp , https://code.claude.com/docs/en/plugins
 import fs from 'node:fs'
 import path from 'node:path'
-import { DEFAULT_MCP_URL, LEGACY_SERVER_NAMES, SERVER_NAME } from '../constants.js'
+import { DEFAULT_MCP_URL, ForeignServerError, LEGACY_SERVER_NAMES, SERVER_NAME } from '../constants.js'
 
 const MARKETPLACE_SOURCE = 'simular-ai/box-plugin'
 const MARKETPLACE = 'simular-box'
@@ -58,26 +58,33 @@ export default {
 
   status(ctx) {
     const user = readUserServers(ctx)
+    const mine = (n) => user[n] && ctx.ours(user[n].url)
     const plugin = ctx.which('claude') ? pluginState(ctx) : null
     const entries = []
     // A disabled plugin next to a user-scope server is how connect sets up a BOX_MCP_URL override.
-    if (plugin && (plugin.enabled || !user[SERVER_NAME])) {
+    if (plugin && (plugin.enabled || !mine(ctx.name))) {
       entries.push({ where: `plugin ${PLUGIN}${plugin.enabled ? '' : ' (disabled)'}`, url: plugin.mcpServers?.box?.url, enabled: plugin.enabled })
     }
-    if (user[SERVER_NAME]) entries.push({ where: `user scope in ${userConfigFile(ctx)}`, url: user[SERVER_NAME].url, enabled: true })
-    const legacy = LEGACY_SERVER_NAMES.filter((n) => user[n])
-    return { entries, legacy, keyConfigured: false }
+    if (mine(ctx.name)) entries.push({ where: `user scope in ${userConfigFile(ctx)}`, url: user[ctx.name].url, enabled: true })
+    // The plugin's server is named plugin:box:box, so a foreign user-scope `box` only matters
+    // when connect would add a user-scope server itself (BOX_MCP_URL set).
+    const foreign = user[ctx.name] && !mine(ctx.name) && ctx.url !== DEFAULT_MCP_URL ? { where: userConfigFile(ctx), url: user[ctx.name].url } : undefined
+    return { entries, legacy: LEGACY_SERVER_NAMES.filter(mine), keyConfigured: false, foreign }
   },
 
   connect(ctx) {
     if (!ctx.which('claude')) throw new Error('the `claude` command is not on PATH; install Claude Code first (https://code.claude.com)')
     const actions = []
     const user = readUserServers(ctx)
-    for (const name of LEGACY_SERVER_NAMES) {
-      if (user[name]) {
-        if (!ctx.dryRun) ctx.run('claude', ['mcp', 'remove', '--scope', 'user', name])
-        actions.push(`removed old server ${name}`)
-      }
+    const mine = (n) => user[n] && ctx.ours(user[n].url)
+    if (ctx.url !== DEFAULT_MCP_URL && user[ctx.name] && !mine(ctx.name)) {
+      throw new ForeignServerError(`Claude Code (user scope, ${userConfigFile(ctx)})`, ctx.name, user[ctx.name].url || user[ctx.name].command)
+    }
+    // `claude mcp remove/add` edit ~/.claude.json; Claude Code keeps its own backups of it
+    // under ~/.claude/backups.
+    for (const name of LEGACY_SERVER_NAMES.filter(mine)) {
+      if (!ctx.dryRun) ctx.run('claude', ['mcp', 'remove', '--scope', 'user', name])
+      actions.push(`removed old server ${name}`)
     }
 
     if (ctx.url === DEFAULT_MCP_URL) {
@@ -95,19 +102,19 @@ export default {
         if (!ctx.dryRun) must(ctx.run('claude', ['plugin', 'enable', PLUGIN]), 'claude plugin enable')
         actions.push(`enabled plugin ${PLUGIN}`)
       }
-      // A user-scope `box` next to the plugin would show box twice.
-      if (user[SERVER_NAME]) {
+      // Our own user-scope box next to the plugin would show box twice. Someone else's stays.
+      if (mine(SERVER_NAME)) {
         if (!ctx.dryRun) ctx.run('claude', ['mcp', 'remove', '--scope', 'user', SERVER_NAME])
         actions.push('removed the user-scope box server (the plugin provides it)')
       }
     } else {
-      const current = user[SERVER_NAME]
+      const current = user[ctx.name]
       if (!current || current.url !== ctx.url || current.type !== 'http') {
         if (!ctx.dryRun) {
-          if (current) ctx.run('claude', ['mcp', 'remove', '--scope', 'user', SERVER_NAME])
-          must(ctx.run('claude', ['mcp', 'add', '--scope', 'user', '--transport', 'http', SERVER_NAME, ctx.url]), 'claude mcp add')
+          if (current) ctx.run('claude', ['mcp', 'remove', '--scope', 'user', ctx.name])
+          must(ctx.run('claude', ['mcp', 'add', '--scope', 'user', '--transport', 'http', ctx.name, ctx.url]), 'claude mcp add')
         }
-        actions.push(`added user-scope server box -> ${ctx.url}`)
+        actions.push(`added user-scope server ${ctx.name} -> ${ctx.url}`)
       }
       const plugin = pluginState(ctx)
       if (plugin?.enabled) {
@@ -115,7 +122,7 @@ export default {
         actions.push(`disabled plugin ${PLUGIN} (it points at the default URL)`)
       }
     }
-    const label = ctx.url === DEFAULT_MCP_URL ? 'plugin:box:box' : 'box'
+    const label = ctx.url === DEFAULT_MCP_URL ? 'plugin:box:box' : ctx.name
     return {
       actions,
       next: [`Start Claude Code, run /mcp, pick ${label} and choose Authenticate; sign in and click Approve in the browser.`],
@@ -125,17 +132,21 @@ export default {
   remove(ctx) {
     if (!ctx.which('claude')) throw new Error('the `claude` command is not on PATH')
     const actions = []
+    const warnings = []
     const user = readUserServers(ctx)
-    for (const name of [SERVER_NAME, ...LEGACY_SERVER_NAMES]) {
-      if (user[name]) {
-        if (!ctx.dryRun) ctx.run('claude', ['mcp', 'remove', '--scope', 'user', name])
-        actions.push(`removed user-scope server ${name}`)
+    for (const name of [...new Set([ctx.name, SERVER_NAME, ...LEGACY_SERVER_NAMES])]) {
+      if (!user[name]) continue
+      if (!ctx.ours(user[name].url)) {
+        if (name === ctx.name) warnings.push(`left user-scope server ${name}: it points at ${user[name].url || user[name].command}, not box by Simular`)
+        continue
       }
+      if (!ctx.dryRun) ctx.run('claude', ['mcp', 'remove', '--scope', 'user', name])
+      actions.push(`${ctx.dryRun ? 'would remove' : 'removed'} user-scope server ${name}`)
     }
     if (pluginState(ctx)) {
       if (!ctx.dryRun) must(ctx.run('claude', ['plugin', 'uninstall', PLUGIN]), 'claude plugin uninstall')
-      actions.push(`uninstalled plugin ${PLUGIN}`)
+      actions.push(`${ctx.dryRun ? 'would uninstall' : 'uninstalled'} plugin ${PLUGIN}`)
     }
-    return { actions, next: [] }
+    return { actions, warnings, next: [] }
   },
 }
diff --git a/cli/src/clients/codex.js b/cli/src/clients/codex.js
index 8d0c0c7..dd4b6ad 100644
--- a/cli/src/clients/codex.js
+++ b/cli/src/clients/codex.js
@@ -5,12 +5,14 @@
 // https://github.com/openai/codex/blob/main/codex-rs/config/src/mcp_types.rs
 import fs from 'node:fs'
 import path from 'node:path'
-import { LEGACY_SERVER_NAMES, SERVER_NAME } from '../constants.js'
+import { ForeignServerError, LEGACY_SERVER_NAMES } from '../constants.js'
 import { readText, updateFile } from '../fsutil.js'
 import { parseToml, removeTomlServers, upsertTomlServer } from '../formats.js'
 
 const home = (ctx) => ctx.env.CODEX_HOME || path.join(ctx.home, '.codex')
 const file = (ctx) => path.join(home(ctx), 'config.toml')
+const servers = (ctx) => parseToml(readText(file(ctx)), file(ctx)).mcp_servers || {}
+const ourLegacy = (ctx, map) => LEGACY_SERVER_NAMES.filter((n) => map[n] && ctx.ours(map[n].url))
 
 export default {
   id: 'codex',
@@ -28,15 +30,16 @@ export default {
 
   status(ctx) {
     const f = file(ctx)
-    const servers = parseToml(readText(f), f).mcp_servers || {}
-    const box = servers[SERVER_NAME]
+    const map = servers(ctx)
+    const box = map[ctx.name]
+    if (box && !ctx.ours(box.url)) return { entries: [], legacy: [], keyConfigured: false, foreign: { where: f, url: box.url || box.command } }
     const warnings = []
     if (box && (box.bearer_token_env_var || box.http_headers || box.env_http_headers)) {
       warnings.push('box has a bearer token or headers set; Codex then skips OAuth. Re-run connect to reset it')
     }
     return {
       entries: box ? [{ where: f, url: box.url, enabled: box.enabled !== false }] : [],
-      legacy: LEGACY_SERVER_NAMES.filter((n) => servers[n]),
+      legacy: ourLegacy(ctx, map),
       keyConfigured: false,
       warnings,
     }
@@ -44,23 +47,32 @@ export default {
 
   connect(ctx) {
     const f = file(ctx)
-    const res = updateFile(f, (text) => upsertTomlServer(text, SERVER_NAME, { url: ctx.url }, { legacy: LEGACY_SERVER_NAMES, file: f }), {
+    const map = servers(ctx)
+    const current = map[ctx.name]
+    if (current && !ctx.ours(current.url)) throw new ForeignServerError(f, ctx.name, current.url || current.command)
+    const res = updateFile(f, (text) => upsertTomlServer(text, ctx.name, { url: ctx.url }, { legacy: ourLegacy(ctx, map), file: f }), {
       dryRun: ctx.dryRun,
     })
     return {
-      actions: res.changed ? [`${ctx.dryRun ? 'would write' : 'wrote'} [mcp_servers.box] to ${f}`] : [],
+      actions: res.changed ? [`${ctx.dryRun ? 'would write' : 'wrote'} [mcp_servers.${ctx.name}] to ${f}`] : [],
       backups: res.backup ? [res.backup] : [],
-      next: ['Run `codex mcp login box`, sign in in the browser and click Approve.'],
+      next: [`Run \`codex mcp login ${ctx.name}\`, sign in in the browser and click Approve.`],
     }
   },
 
   remove(ctx) {
     const f = file(ctx)
-    const res = updateFile(f, (text) => removeTomlServers(text, [SERVER_NAME, ...LEGACY_SERVER_NAMES], { file: f }), { dryRun: ctx.dryRun })
+    const map = servers(ctx)
+    const names = [ctx.name, ...LEGACY_SERVER_NAMES].filter((n) => map[n] && ctx.ours(map[n].url))
+    const warnings = map[ctx.name] && !names.includes(ctx.name) ? [`left [mcp_servers.${ctx.name}] in ${f}: it is not box by Simular`] : []
+    // Drop the stored sign-in too, while Codex still knows the server (best effort).
+    if (names.includes(ctx.name) && !ctx.dryRun && ctx.which('codex')) ctx.run('codex', ['mcp', 'logout', ctx.name], { timeoutMs: 30000 })
+    const res = updateFile(f, (text) => removeTomlServers(text, names, { file: f }), { dryRun: ctx.dryRun })
     return {
-      actions: res.changed ? [`${ctx.dryRun ? 'would remove' : 'removed'} [mcp_servers.box] from ${f}`] : [],
+      actions: res.changed ? [`${ctx.dryRun ? 'would remove' : 'removed'} ${names.map((n) => `[mcp_servers.${n}]`).join(', ')} from ${f}`] : [],
       backups: res.backup ? [res.backup] : [],
-      next: res.changed ? ['To also drop the stored sign-in: `codex mcp logout box` (before removing) or revoke it at https://box.simular.ai/keys.'] : [],
+      warnings,
+      next: [],
     }
   },
 }
diff --git a/cli/src/clients/cursor.js b/cli/src/clients/cursor.js
index 6f68a2b..adbd730 100644
--- a/cli/src/clients/cursor.js
+++ b/cli/src/clients/cursor.js
@@ -12,5 +12,5 @@ export default jsonClient({
   entry: (ctx) => ({ url: ctx.url }),
   bins: ['cursor', 'agent', 'cursor-agent'],
   dirs: (ctx) => [path.join(ctx.home, '.cursor'), ...(ctx.platform === 'darwin' ? ['/Applications/Cursor.app'] : [])],
-  next: ['Open Cursor Settings -> MCP (Tools & MCP) and click Login next to box; sign in and click Approve.'],
+  next: (ctx) => [`Open Cursor Settings -> MCP (Tools & MCP) and click Login next to ${ctx.name}; sign in and click Approve.`],
 })
diff --git a/cli/src/clients/hermes.js b/cli/src/clients/hermes.js
index 9738975..b5d2d61 100644
--- a/cli/src/clients/hermes.js
+++ b/cli/src/clients/hermes.js
@@ -9,7 +9,7 @@
 // https://github.com/NousResearch/hermes-agent/blob/main/hermes_constants.py
 import fs from 'node:fs'
 import path from 'node:path'
-import { LEGACY_SERVER_NAMES, SERVER_NAME } from '../constants.js'
+import { ForeignServerError, LEGACY_SERVER_NAMES } from '../constants.js'
 import { readText, updateFile } from '../fsutil.js'
 import { readEnvValue, readYaml, removeEnvValue, removeYamlServers, upsertEnvValue, upsertYamlServer } from '../formats.js'
 
@@ -26,8 +26,9 @@ const envFile = (ctx) => path.join(home(ctx), '.env')
 
 function serverEntry(ctx) {
   const f = configFile(ctx)
-  return (readYaml(readText(f), f).mcp_servers || {})
+  return readYaml(readText(f), f).mcp_servers || {}
 }
+const ourLegacy = (ctx, map) => LEGACY_SERVER_NAMES.filter((n) => map[n] && ctx.ours(map[n].url))
 
 export default {
   id: 'hermes',
@@ -45,14 +46,15 @@ export default {
 
   status(ctx) {
     const servers = serverEntry(ctx)
-    const box = servers[SERVER_NAME]
+    const box = servers[ctx.name]
+    if (box && !ctx.ours(box.url)) return { entries: [], legacy: [], keyConfigured: false, foreign: { where: configFile(ctx), url: box.url || box.command } }
     const usesKey = Boolean(box?.headers && JSON.stringify(box.headers).includes(HERMES_KEY_ENV))
     const key = usesKey ? readEnvValue(readText(envFile(ctx)), HERMES_KEY_ENV) || ctx.env[HERMES_KEY_ENV] : undefined
     const warnings = []
     if (usesKey && !key) warnings.push(`box reads ${HERMES_KEY_ENV}, but it is not set in ${envFile(ctx)}`)
     return {
       entries: box ? [{ where: configFile(ctx), url: box.url, enabled: box.enabled !== false, mode: usesKey ? 'key' : 'oauth' }] : [],
-      legacy: LEGACY_SERVER_NAMES.filter((n) => servers[n]),
+      legacy: ourLegacy(ctx, servers),
       key,
       keyConfigured: Boolean(key),
       warnings,
@@ -61,6 +63,8 @@ export default {
 
   connect(ctx, { mode = 'oauth', key } = {}) {
     const f = configFile(ctx)
+    const servers = serverEntry(ctx)
+    if (servers[ctx.name] && !ctx.ours(servers[ctx.name].url)) throw new ForeignServerError(f, ctx.name, servers[ctx.name].url || servers[ctx.name].command)
     const entry =
       mode === 'key'
         ? { url: ctx.url, headers: { Authorization: KEY_REF }, enabled: true }
@@ -72,20 +76,20 @@ export default {
     if (mode === 'key') {
       const useKey = key || this.status(ctx).key
       if (!useKey) throw new Error('a personal key is needed')
-      const r = updateFile(envFile(ctx), (text) => upsertEnvValue(text, HERMES_KEY_ENV, useKey), { mode: 0o600, dryRun: ctx.dryRun })
+      const r = updateFile(envFile(ctx), (text) => upsertEnvValue(text, HERMES_KEY_ENV, useKey), { mode: 0o600, dryRun: ctx.dryRun, secret: true })
       if (r.changed) {
         keyChanged = true
-        actions.push(`${ctx.dryRun ? 'would save' : 'saved'} the key as ${HERMES_KEY_ENV} in ${envFile(ctx)}`)
+        actions.push(`${ctx.dryRun ? 'would save' : 'saved'} the key as ${HERMES_KEY_ENV} in ${envFile(ctx)} (no backup of that file is kept: it holds keys)`)
       }
       if (r.backup) backups.push(r.backup)
     }
-    const r = updateFile(f, (text) => upsertYamlServer(text, 'mcp_servers', SERVER_NAME, entry, { legacy: LEGACY_SERVER_NAMES, file: f }), {
+    const r = updateFile(f, (text) => upsertYamlServer(text, 'mcp_servers', ctx.name, entry, { legacy: ourLegacy(ctx, servers), file: f }), {
       dryRun: ctx.dryRun,
     })
-    if (r.changed) actions.push(`${ctx.dryRun ? 'would write' : 'wrote'} mcp_servers.box (${mode === 'key' ? 'personal key' : 'OAuth'}) to ${f}`)
+    if (r.changed) actions.push(`${ctx.dryRun ? 'would write' : 'wrote'} mcp_servers.${ctx.name} (${mode === 'key' ? 'personal key' : 'OAuth'}) to ${f}`)
     if (r.backup) backups.push(r.backup)
 
-    if (mode === 'oauth') next.push('Run `hermes mcp login box`, sign in in the browser and click Approve (on a server without a browser: `hermes mcp login box --flow device`, or use --auth key).')
+    if (mode === 'oauth') next.push(`Run \`hermes mcp login ${ctx.name}\`, sign in in the browser and click Approve (on a server without a browser: \`hermes mcp login ${ctx.name} --flow device\`, or use --auth key).`)
     if ((keyChanged || r.changed) && !ctx.dryRun) {
       // A running gateway keeps the old config and key until it restarts.
       if (ctx.which('hermes')) {
@@ -105,12 +109,15 @@ export default {
     const actions = []
     const backups = []
     const f = configFile(ctx)
-    const r = updateFile(f, (text) => removeYamlServers(text, 'mcp_servers', [SERVER_NAME, ...LEGACY_SERVER_NAMES], { file: f }), { dryRun: ctx.dryRun })
-    if (r.changed) actions.push(`${ctx.dryRun ? 'would remove' : 'removed'} mcp_servers.box from ${f}`)
+    const servers = serverEntry(ctx)
+    const names = [ctx.name, ...LEGACY_SERVER_NAMES].filter((n) => servers[n] && ctx.ours(servers[n].url))
+    const warnings = servers[ctx.name] && !names.includes(ctx.name) ? [`left mcp_servers.${ctx.name} in ${f}: it is not box by Simular`] : []
+    const r = updateFile(f, (text) => removeYamlServers(text, 'mcp_servers', names, { file: f }), { dryRun: ctx.dryRun })
+    if (r.changed) actions.push(`${ctx.dryRun ? 'would remove' : 'removed'} mcp_servers.${names.join(', ')} from ${f}`)
     if (r.backup) backups.push(r.backup)
-    const e = updateFile(envFile(ctx), (text) => removeEnvValue(text, HERMES_KEY_ENV), { dryRun: ctx.dryRun })
+    const e = updateFile(envFile(ctx), (text) => removeEnvValue(text, HERMES_KEY_ENV), { dryRun: ctx.dryRun, secret: true })
     if (e.changed) actions.push(`${ctx.dryRun ? 'would remove' : 'removed'} ${HERMES_KEY_ENV} from ${envFile(ctx)}`)
     if (e.backup) backups.push(e.backup)
-    return { actions, backups, next: actions.length ? ['Run `hermes gateway restart` if a gateway is running.'] : [] }
+    return { actions, backups, warnings, next: actions.length ? ['Run `hermes gateway restart` if a gateway is running.'] : [] }
   },
 }
diff --git a/cli/src/clients/json-client.js b/cli/src/clients/json-client.js
index 0ff8afa..6902d4a 100644
--- a/cli/src/clients/json-client.js
+++ b/cli/src/clients/json-client.js
@@ -1,6 +1,6 @@
 // Shared logic for clients whose config is a JSON/JSONC file with a map of servers.
 import fs from 'node:fs'
-import { LEGACY_SERVER_NAMES, SERVER_NAME } from '../constants.js'
+import { ForeignServerError, LEGACY_SERVER_NAMES } from '../constants.js'
 import { readText, updateFile } from '../fsutil.js'
 import { getPath, parseJsonc, removeJsonServer, upsertJsonServer } from '../formats.js'
 
@@ -8,20 +8,24 @@ import { getPath, parseJsonc, removeJsonServer, upsertJsonServer } from '../form
  * @param {object} spec
  * @param {string} spec.id
  * @param {string} spec.name
- * @param {'oauth'|'key'} spec.auth
+ * @param {'oauth'} spec.auth
  * @param {(ctx) => string} spec.file          config file path
  * @param {string[]} spec.container             JSON path of the servers map
- * @param {(ctx, key) => object} spec.entry     the box entry to write
+ * @param {(ctx) => object} spec.entry          the box entry to write
  * @param {(entry) => string|undefined} [spec.entryUrl]
- * @param {(entry) => string|undefined} [spec.entryKey]
  * @param {string[]} [spec.bins]                binaries that mean "installed"
  * @param {(ctx) => string[]} [spec.dirs]       directories that mean "installed"
- * @param {string[]} [spec.next]
- * @param {(ctx) => object} [spec.extraStatus]
+ * @param {string[]|((ctx) => string[])} [spec.next]
  */
 export function jsonClient(spec) {
-  const entryUrl = spec.entryUrl || ((e) => e?.url)
-  const entryKey = spec.entryKey || (() => undefined)
+  const entryUrl = spec.entryUrl || ((e) => e?.url ?? e?.serverUrl)
+  const servers = (ctx) => {
+    const file = spec.file(ctx)
+    return getPath(parseJsonc(readText(file), file), spec.container) || {}
+  }
+  // Only entries that point at box by Simular are ours to change or remove.
+  const ourLegacy = (ctx, map) => LEGACY_SERVER_NAMES.filter((n) => map[n] && ctx.ours(entryUrl(map[n])))
+
   return {
     id: spec.id,
     name: spec.name,
@@ -40,33 +44,27 @@ export function jsonClient(spec) {
 
     status(ctx) {
       const file = spec.file(ctx)
-      const doc = parseJsonc(readText(file), file)
-      const servers = getPath(doc, spec.container) || {}
-      const entry = servers[SERVER_NAME]
-      const entries = entry ? [{ where: file, url: entryUrl(entry), enabled: entry.enabled !== false && entry.disabled !== true }] : []
-      const key = entry ? entryKey(entry) : undefined
+      const map = servers(ctx)
+      const entry = map[ctx.name]
+      if (entry && !ctx.ours(entryUrl(entry))) {
+        return { entries: [], legacy: [], keyConfigured: false, foreign: { where: file, url: entryUrl(entry) } }
+      }
       return {
-        entries,
-        legacy: LEGACY_SERVER_NAMES.filter((n) => servers[n]),
-        key,
-        keyConfigured: Boolean(key),
-        ...(spec.extraStatus ? spec.extraStatus(ctx, entry) : {}),
+        entries: entry ? [{ where: file, url: entryUrl(entry), enabled: entry.enabled !== false && entry.disabled !== true }] : [],
+        legacy: ourLegacy(ctx, map),
+        keyConfigured: false,
       }
     },
 
-    connect(ctx, { key } = {}) {
+    connect(ctx) {
       const file = spec.file(ctx)
-      let useKey = key
-      if (spec.auth === 'key' && !useKey) useKey = this.status(ctx).key
-      if (spec.auth === 'key' && !useKey) throw new Error('a personal key is needed')
-      const entry = spec.entry(ctx, useKey)
-      const res = updateFile(
-        file,
-        (text) => upsertJsonServer(text, spec.container, SERVER_NAME, entry, { legacy: LEGACY_SERVER_NAMES, file }),
-        { dryRun: ctx.dryRun, mode: spec.auth === 'key' ? 0o600 : undefined },
-      )
+      const map = servers(ctx)
+      if (map[ctx.name] && !ctx.ours(entryUrl(map[ctx.name]))) throw new ForeignServerError(file, ctx.name, entryUrl(map[ctx.name]))
+      const res = updateFile(file, (text) => upsertJsonServer(text, spec.container, ctx.name, spec.entry(ctx), { legacy: ourLegacy(ctx, map), file }), {
+        dryRun: ctx.dryRun,
+      })
       return {
-        actions: res.changed ? [`${ctx.dryRun ? 'would write' : 'wrote'} box to ${file}`] : [],
+        actions: res.changed ? [`${ctx.dryRun ? 'would write' : 'wrote'} ${ctx.name} to ${file}`] : [],
         backups: res.backup ? [res.backup] : [],
         next: typeof spec.next === 'function' ? spec.next(ctx) : spec.next || [],
       }
@@ -74,12 +72,14 @@ export function jsonClient(spec) {
 
     remove(ctx) {
       const file = spec.file(ctx)
-      const res = updateFile(file, (text) => removeJsonServer(text, spec.container, [SERVER_NAME, ...LEGACY_SERVER_NAMES], { file }), {
-        dryRun: ctx.dryRun,
-      })
+      const map = servers(ctx)
+      const names = [ctx.name, ...LEGACY_SERVER_NAMES].filter((n) => map[n] && ctx.ours(entryUrl(map[n])))
+      const warnings = map[ctx.name] && !names.includes(ctx.name) ? [`left "${ctx.name}" in ${file}: it points at ${entryUrl(map[ctx.name])}, not box by Simular`] : []
+      const res = updateFile(file, (text) => removeJsonServer(text, spec.container, names, { file }), { dryRun: ctx.dryRun })
       return {
-        actions: res.changed ? [`${ctx.dryRun ? 'would remove' : 'removed'} box from ${file}`] : [],
+        actions: res.changed ? [`${ctx.dryRun ? 'would remove' : 'removed'} ${names.join(', ')} from ${file}`] : [],
         backups: res.backup ? [res.backup] : [],
+        warnings,
         next: [],
       }
     },
diff --git a/cli/src/clients/openclaw.js b/cli/src/clients/openclaw.js
index 0e5ebc2..2628fcb 100644
--- a/cli/src/clients/openclaw.js
+++ b/cli/src/clients/openclaw.js
@@ -12,7 +12,7 @@
 // https://github.com/openclaw/openclaw/blob/main/docs/help/environment.md
 import fs from 'node:fs'
 import path from 'node:path'
-import { KEY_ENV, LEGACY_SERVER_NAMES, SERVER_NAME } from '../constants.js'
+import { ForeignServerError, KEY_ENV, LEGACY_SERVER_NAMES } from '../constants.js'
 import { readText, updateFile } from '../fsutil.js'
 import { parseJsonc, readEnvValue, removeEnvValue, sameValue, upsertEnvValue } from '../formats.js'
 
@@ -82,8 +82,9 @@ export default {
 
   status(ctx) {
     if (!ctx.which('openclaw')) throw new Error('the `openclaw` command is not on PATH, so its config cannot be read')
-    const box = rawEntry(ctx, SERVER_NAME).entry
-    const legacy = LEGACY_SERVER_NAMES.filter((n) => rawEntry(ctx, n).entry !== undefined)
+    const box = rawEntry(ctx, ctx.name).entry
+    if (box && !ctx.ours(box.url)) return { entries: [], legacy: [], keyConfigured: false, foreign: { where: configFile(ctx), url: box.url || box.command } }
+    const legacy = LEGACY_SERVER_NAMES.filter((n) => ctx.ours(rawEntry(ctx, n).entry?.url))
     const header = box?.headers?.Authorization || box?.headers?.authorization
     const usesKeyRef = typeof header === 'string' && header.includes(`\${${KEY_ENV}}`)
     const literal = typeof header === 'string' && /^Bearer\s+cb_/.test(header) ? header.replace(/^Bearer\s+/, '') : undefined
@@ -103,6 +104,8 @@ export default {
 
   connect(ctx, { mode = 'oauth', key } = {}) {
     if (!ctx.which('openclaw')) throw new Error('the `openclaw` command is not on PATH; install OpenClaw first')
+    const current = rawEntry(ctx, ctx.name).entry
+    if (current && !ctx.ours(current.url)) throw new ForeignServerError(configFile(ctx), ctx.name, current.url || current.command)
     const actions = []
     const backups = []
     const next = []
@@ -110,10 +113,10 @@ export default {
     if (mode === 'key') {
       const useKey = key || readEnvValue(readText(envFile(ctx)), KEY_ENV)
       if (!useKey) throw new Error('a personal key is needed')
-      const r = updateFile(envFile(ctx), (text) => upsertEnvValue(text, KEY_ENV, useKey), { mode: 0o600, dryRun: ctx.dryRun })
+      const r = updateFile(envFile(ctx), (text) => upsertEnvValue(text, KEY_ENV, useKey), { mode: 0o600, dryRun: ctx.dryRun, secret: true })
       if (r.changed) {
         keyChanged = true
-        actions.push(`${ctx.dryRun ? 'would save' : 'saved'} the key as ${KEY_ENV} in ${envFile(ctx)}`)
+        actions.push(`${ctx.dryRun ? 'would save' : 'saved'} the key as ${KEY_ENV} in ${envFile(ctx)} (no backup of that file is kept: it holds keys)`)
       }
       if (r.backup) backups.push(r.backup)
     }
@@ -121,15 +124,14 @@ export default {
       mode === 'key'
         ? { url: ctx.url, transport: 'streamable-http', headers: { Authorization: KEY_REF } }
         : { url: ctx.url, transport: 'streamable-http', auth: 'oauth' }
-    const current = rawEntry(ctx, SERVER_NAME).entry
     let configChanged = false
     if (!sameValue(current, entry)) {
-      if (!ctx.dryRun) must(ctx.run('openclaw', ['mcp', 'set', SERVER_NAME, JSON.stringify(entry)], { timeoutMs: 60000 }), 'openclaw mcp set')
+      if (!ctx.dryRun) must(ctx.run('openclaw', ['mcp', 'set', ctx.name, JSON.stringify(entry)], { timeoutMs: 60000 }), 'openclaw mcp set')
       configChanged = true
-      actions.push(`${ctx.dryRun ? 'would set' : 'set'} mcp.servers.box (${mode === 'key' ? 'personal key from .env' : 'OAuth'}) via openclaw mcp set`)
+      actions.push(`${ctx.dryRun ? 'would set' : 'set'} mcp.servers.${ctx.name} (${mode === 'key' ? 'personal key from .env' : 'OAuth'}) via openclaw mcp set`)
     }
     for (const name of LEGACY_SERVER_NAMES) {
-      if (rawEntry(ctx, name).entry !== undefined) {
+      if (ctx.ours(rawEntry(ctx, name).entry?.url)) {
         if (!ctx.dryRun) ctx.run('openclaw', ['mcp', 'unset', name])
         actions.push(`removed old server ${name}`)
       }
@@ -143,7 +145,7 @@ export default {
       } else if (configChanged) ctx.run('openclaw', ['mcp', 'reload'], { timeoutMs: 30000 })
       if (keyChanged && !gatewayUp(ctx)) next.push('The key is read when the Gateway starts: `openclaw gateway start` (or restart it if it runs elsewhere).')
     }
-    if (mode === 'oauth') next.push('Run `openclaw mcp login box`, sign in in the browser and click Approve. On a server without a browser, use --auth key instead.')
+    if (mode === 'oauth') next.push(`Run \`openclaw mcp login ${ctx.name}\`, sign in in the browser and click Approve. On a server without a browser, use --auth key instead.`)
     return { actions, backups, next }
   },
 
@@ -151,15 +153,20 @@ export default {
     if (!ctx.which('openclaw')) throw new Error('the `openclaw` command is not on PATH')
     const actions = []
     const backups = []
-    for (const name of [SERVER_NAME, ...LEGACY_SERVER_NAMES]) {
-      if (rawEntry(ctx, name).entry !== undefined) {
-        if (!ctx.dryRun) must(ctx.run('openclaw', ['mcp', 'unset', name]), 'openclaw mcp unset')
-        actions.push(`removed mcp.servers.${name}`)
+    const warnings = []
+    for (const name of [ctx.name, ...LEGACY_SERVER_NAMES]) {
+      const entry = rawEntry(ctx, name).entry
+      if (entry === undefined) continue
+      if (!ctx.ours(entry.url)) {
+        if (name === ctx.name) warnings.push(`left mcp.servers.${name}: it is not box by Simular`)
+        continue
       }
+      if (!ctx.dryRun) must(ctx.run('openclaw', ['mcp', 'unset', name]), 'openclaw mcp unset')
+      actions.push(`${ctx.dryRun ? 'would remove' : 'removed'} mcp.servers.${name}`)
     }
-    const e = updateFile(envFile(ctx), (text) => removeEnvValue(text, KEY_ENV), { dryRun: ctx.dryRun, mode: 0o600 })
+    const e = updateFile(envFile(ctx), (text) => removeEnvValue(text, KEY_ENV), { dryRun: ctx.dryRun, mode: 0o600, secret: true })
     if (e.changed) actions.push(`${ctx.dryRun ? 'would remove' : 'removed'} ${KEY_ENV} from ${envFile(ctx)}`)
     if (e.backup) backups.push(e.backup)
-    return { actions, backups, next: [] }
+    return { actions, backups, warnings, next: [] }
   },
 }
diff --git a/cli/src/clients/opencode.js b/cli/src/clients/opencode.js
index 0f468fb..aa1f16d 100644
--- a/cli/src/clients/opencode.js
+++ b/cli/src/clients/opencode.js
@@ -21,5 +21,5 @@ export default jsonClient({
   entry: (ctx) => ({ type: 'remote', url: ctx.url, enabled: true }),
   bins: ['opencode'],
   dirs: (ctx) => [path.join(ctx.xdgConfig, 'opencode')],
-  next: ['Run `opencode mcp auth box`, sign in in the browser and click Approve.'],
+  next: (ctx) => [`Run \`opencode mcp auth ${ctx.name}\`, sign in in the browser and click Approve.`],
 })
diff --git a/cli/src/clients/vscode.js b/cli/src/clients/vscode.js
index f1594a3..dcd92a4 100644
--- a/cli/src/clients/vscode.js
+++ b/cli/src/clients/vscode.js
@@ -16,5 +16,5 @@ export default jsonClient({
   container: ['servers'],
   entry: (ctx) => ({ type: 'http', url: ctx.url }),
   dirs: (ctx) => [userDir(ctx)],
-  next: ['In VS Code, open the Command Palette -> MCP: List Servers -> box -> Start, then allow the sign-in and click Approve.'],
+  next: (ctx) => [`In VS Code, open the Command Palette -> MCP: List Servers -> ${ctx.name} -> Start, then allow the sign-in and click Approve.`],
 })
diff --git a/cli/src/constants.js b/cli/src/constants.js
index 34cfeee..067af57 100644
--- a/cli/src/constants.js
+++ b/cli/src/constants.js
@@ -6,6 +6,42 @@ export const DEFAULT_MCP_URL = 'https://relay.simular.cloud/mcp'
 export const LEGACY_SERVER_NAMES = ['box-control']
 
 export const SERVER_NAME = 'box'
+
+/** Hosts that serve box by Simular. An existing server named `box` elsewhere is not ours. */
+export const OUR_HOSTS = ['relay.simular.cloud', 'staging.relay.simular.cloud', 'mcp.box.simular.ai']
+
+/** Whether `url` points at box by Simular (a known host, or the host of the current endpoint). */
+export function isOurUrl(url, currentUrl) {
+  if (typeof url !== 'string') return false
+  let host
+  try {
+    host = new URL(url).host
+  } catch {
+    return false
+  }
+  if (OUR_HOSTS.includes(host)) return true
+  try {
+    return host === new URL(currentUrl).host
+  } catch {
+    return false
+  }
+}
+
+/** Thrown when a server with our name already exists but points somewhere else. */
+export class ForeignServerError extends Error {
+  constructor(where, name, url) {
+    super(
+      `${where} already has a server named "${name}" that points at ${url || 'something else'}, which is not box by Simular. ` +
+        'Nothing was changed. To add box next to it, run again with --name <another-name> (for example --name simular-box).',
+    )
+    this.foreign = true
+  }
+}
+
+export function validServerName(name) {
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name)) throw new Error('--name may use letters, digits, - and _ (up to 64)')
+  return name
+}
 export const KEY_ENV = 'BOX_TOKEN'
 export const KEYS_URL = 'https://box.simular.ai/keys'
 export const WATCH_URL = 'https://box.simular.ai/box'
diff --git a/cli/src/context.js b/cli/src/context.js
index eda56de..10e7593 100644
--- a/cli/src/context.js
+++ b/cli/src/context.js
@@ -2,13 +2,13 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import spawn from 'cross-spawn'
-import { mcpUrl } from './constants.js'
+import { mcpUrl, SERVER_NAME, isOurUrl } from './constants.js'
 
 /**
  * Everything a client adapter may touch about the machine goes through this context, so tests can
  * point it at a temporary HOME and a fake PATH.
  */
-export function createContext({ env = process.env, platform = process.platform, dryRun = false, log = () => {} } = {}) {
+export function createContext({ env = process.env, platform = process.platform, dryRun = false, log = () => {}, serverName = SERVER_NAME } = {}) {
   // Match os.homedir(), which the apps themselves use: USERPROFILE on Windows, HOME elsewhere.
   const home = (platform === 'win32' ? env.USERPROFILE || env.HOME : env.HOME || env.USERPROFILE) || os.homedir()
   const ctx = {
@@ -18,6 +18,12 @@ export function createContext({ env = process.env, platform = process.platform,
     dryRun,
     log,
     url: mcpUrl(env),
+    /** The name box is installed under (--name); `box` unless that name is taken by another server. */
+    name: serverName,
+    /** Whether a configured URL is box by Simular (and so ours to change or remove). */
+    ours(url) {
+      return isOurUrl(url, this.url)
+    },
     /** XDG config dir, falling back to ~/.config (also on macOS, as most CLIs do). */
     xdgConfig: env.XDG_CONFIG_HOME || path.join(home, '.config'),
     /** Platform app-data dir: ~/Library/Application Support, %APPDATA%, or XDG config. */
diff --git a/cli/src/formats.js b/cli/src/formats.js
index 4d7d180..dc91eb7 100644
--- a/cli/src/formats.js
+++ b/cli/src/formats.js
@@ -98,7 +98,7 @@ export function upsertEnvValue(text, name, value) {
   const line = `${name}=${value}`
   if (text && envLine(name).test(text)) {
     if (readEnvValue(text, name) === value) return text
-    return text.replace(envLine(name), line)
+    return text.replace(envLine(name), () => line)
   }
   const base = text ? text.replace(/\n*$/, '\n') : ''
   return `${base}${line}\n`
@@ -141,19 +141,33 @@ function splitDotted(key) {
 
 const HEADER = /^\s*\[(\[?)\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?\r?$/
 
-/** Remove `[table]` blocks whose key path starts with any of `prefixes` (arrays of key parts). */
-export function removeTomlTables(text, prefixes) {
+/**
+ * Remove `[table]` blocks whose key path starts with any of `prefixes` (arrays of key parts), or
+ * equals one of them when `exact`. Comment and blank lines just above a table we keep stay with
+ * that table (they usually describe it).
+ */
+export function removeTomlTables(text, prefixes, { exact = false } = {}) {
   if (!text) return text
   const lines = text.split('\n') // a CRLF line keeps its \r, which HEADER tolerates
   const out = []
   let dropping = false
+  let pending = [] // comment/blank lines seen while dropping; kept if a kept table follows
   for (const line of lines) {
     const m = HEADER.exec(line)
     if (m) {
       const parts = splitDotted(m[2])
-      dropping = prefixes.some((pre) => pre.every((p, i) => parts[i] === p))
+      const wasDropping = dropping
+      dropping = prefixes.some((pre) => (exact ? pre.length === parts.length : true) && pre.every((p, i) => parts[i] === p))
+      if (wasDropping && !dropping) {
+        const blank = (l) => /^\s*\r?$/.test(l)
+        if (!out.length || blank(out[out.length - 1])) while (pending.length && blank(pending[0])) pending.shift()
+        out.push(...pending)
+      }
+      pending = []
     }
     if (!dropping) out.push(line)
+    else if (/^\s*(#.*)?\r?$/.test(line)) pending.push(line)
+    else pending = []
   }
   // A dropped block at the end also drops the file's final newline: restore it.
   const eol = /\r\n/.test(text) ? '\r\n' : '\n'
@@ -164,30 +178,42 @@ export function removeTomlTables(text, prefixes) {
 
 const tomlString = (s) => JSON.stringify(s)
 
+/** Keys that select how Codex connects; anything else on our table (timeouts, tool lists) is kept. */
+const CONNECTION_KEYS = new Set(['url', 'command', 'args', 'env', 'cwd', 'bearer_token', 'bearer_token_env_var', 'http_headers', 'env_http_headers'])
+
 /**
- * Set `[mcp_servers.<name>]` to `fields` (flat string values), removing legacy names. Throws when
- * the server is defined in a way we can't edit safely (inline table or dotted keys elsewhere).
+ * Set `[mcp_servers.<name>]` so it connects with `fields`, removing legacy names. Other settings
+ * on the table and its subtables (e.g. tool approvals) are kept. The caller checks that an
+ * existing table is ours. Throws when the server is defined in a way we can't edit safely.
  */
 export function upsertTomlServer(text, name, fields, { legacy = [], file } = {}) {
   const doc = parseToml(text, file)
   const current = doc.mcp_servers?.[name]
+  const kept = {}
+  for (const [k, v] of Object.entries(current || {})) {
+    if (!CONNECTION_KEYS.has(k) && (v === null || typeof v !== 'object' || Array.isArray(v) || v instanceof Date)) kept[k] = v
+  }
+  const connection = Object.fromEntries(Object.entries(current || {}).filter(([k]) => CONNECTION_KEYS.has(k)))
   const hasLegacy = legacy.some((n) => doc.mcp_servers?.[n] !== undefined)
-  if (current && sameValue(current, fields) && !hasLegacy) return text
-  let out = removeTomlTables(text || '', [name, ...legacy].map((n) => ['mcp_servers', n]))
+  if (current && sameValue(connection, fields) && !hasLegacy) return text
+  let out = removeTomlTables(text || '', [['mcp_servers', name]], { exact: true })
+  out = removeTomlTables(out, legacy.map((n) => ['mcp_servers', n]))
   const check = parseToml(out, file)
-  for (const n of [name, ...legacy]) {
-    if (check.mcp_servers?.[n] !== undefined) {
-      throw new Error(`${file} defines mcp_servers.${n} inline; remove it by hand, then run again`)
-    }
+  for (const n of legacy) {
+    if (check.mcp_servers?.[n] !== undefined) throw new Error(`${file} defines mcp_servers.${n} inline; remove it by hand, then run again`)
+  }
+  const leftover = check.mcp_servers?.[name]
+  if (leftover && Object.values(leftover).some((v) => v === null || typeof v !== 'object' || Array.isArray(v))) {
+    throw new Error(`${file} defines mcp_servers.${name} inline or with dotted keys; remove it by hand, then run again`)
   }
   // Keep the file's line endings (CRLF on Windows-edited files).
   const eol = /\r\n/.test(text || '') ? '\r\n' : '\n'
-  const body = Object.entries(fields)
-    .map(([k, v]) => `${k} = ${tomlString(v)}`)
-    .join(eol)
+  const keptLines = Object.keys(kept).length ? TOML.stringify(kept).trim().split(/\r?\n/) : []
+  const body = [...Object.entries(fields).map(([k, v]) => `${k} = ${tomlString(v)}`), ...keptLines].join(eol)
   out = `${out.replace(/\s*$/, '')}${out.trim() ? eol + eol : ''}[mcp_servers.${name}]${eol}${body}${eol}`
   const final = parseToml(out, file)
-  if (!sameValue(final.mcp_servers?.[name], fields)) throw new Error(`could not update ${file} safely; nothing was written`)
+  const got = Object.fromEntries(Object.entries(final.mcp_servers?.[name] || {}).filter(([k]) => CONNECTION_KEYS.has(k)))
+  if (!sameValue(got, fields)) throw new Error(`could not update ${file} safely; nothing was written`)
   return out
 }
 
diff --git a/cli/src/fsutil.js b/cli/src/fsutil.js
index 83940bd..15e007f 100644
--- a/cli/src/fsutil.js
+++ b/cli/src/fsutil.js
@@ -40,7 +40,9 @@ export function backup(file, now = new Date()) {
  * Write atomically (temp file + rename) so a crash never leaves a half-written config.
  * Keeps the existing file's mode; `mode` applies to new files (0600 for files that hold a key).
  */
-export function writeAtomic(file, text, { mode } = {}) {
+export function writeAtomic(linkOrFile, text, { mode } = {}) {
+  // Write through a symlinked config (dotfile repos): replace the target, keep the link.
+  const file = exists(linkOrFile) ? fs.realpathSync(linkOrFile) : linkOrFile
   fs.mkdirSync(path.dirname(file), { recursive: true })
   let finalMode = mode
   if (exists(file)) {
@@ -56,13 +58,15 @@ export function writeAtomic(file, text, { mode } = {}) {
 /**
  * Apply `transform(oldText|null) -> newText|null` to a file. Returns {changed, backup}.
  * A null result or an unchanged text leaves the file alone (idempotent re-runs, no backup spam).
+ * `secret: true` (a .env holding keys) keeps no backup: a backup would keep an old or removed
+ * key on disk. Those edits only add, replace or delete one line.
  */
-export function updateFile(file, transform, { mode, dryRun = false } = {}) {
+export function updateFile(file, transform, { mode, dryRun = false, secret = false } = {}) {
   const before = readText(file)
   const after = transform(before)
   if (after === null || after === before) return { changed: false, backup: null }
   if (dryRun) return { changed: true, backup: null, preview: after }
-  const backupPath = backup(file)
+  const backupPath = secret ? null : backup(exists(file) ? fs.realpathSync(file) : file)
   // A backup of a file that holds a key is a copy of that key: keep it as private as the file.
   if (backupPath && mode !== undefined) fs.chmodSync(backupPath, (fs.statSync(backupPath).mode & 0o777) & mode)
   writeAtomic(file, after, { mode })
diff --git a/cli/test/cli.test.js b/cli/test/cli.test.js
index fba9a03..5f52f33 100644
--- a/cli/test/cli.test.js
+++ b/cli/test/cli.test.js
@@ -49,7 +49,7 @@ test('probe: parses WWW-Authenticate and follows resource metadata', async () =>
 
 test('doctor: flags a stale URL, a legacy server and a rejected key, with fixes', async () => {
   const sb = sandbox()
-  sb.write('.cursor/mcp.json', JSON.stringify({ mcpServers: { box: { url: 'https://relay.simular.cloud/old' }, 'box-control': { url: 'x' } } }))
+  sb.write('.cursor/mcp.json', JSON.stringify({ mcpServers: { box: { url: 'https://relay.simular.cloud/old' }, 'box-control': { url: 'https://relay.simular.cloud/control' } } }))
   sb.write('.hermes/config.yaml', 'mcp_servers:\n  box:\n    url: https://relay.simular.cloud/mcp\n    headers:\n      Authorization: Bearer ${MCP_BOX_API_KEY}\n')
   sb.write('.hermes/.env', `MCP_BOX_API_KEY=${KEY}\n`)
   const report = await runDoctor(sb.ctx, {}, {
diff --git a/cli/test/clients.test.js b/cli/test/clients.test.js
index a7531ae..643a368 100644
--- a/cli/test/clients.test.js
+++ b/cli/test/clients.test.js
@@ -64,11 +64,12 @@ test('codex: rewrites only [mcp_servers.box] (and its subtables), keeps comments
   assert.equal(doc.mcp_servers.box, undefined)
   assert.deepEqual(plain(doc.mcp_servers.docs), { command: 'npx', args: ['docs-mcp'] })
   assert.match(sb.read('.codex/config.toml'), /# keep this comment/)
+  assert.match(sb.read('.codex/config.toml'), /# Profiles: keep this comment with its table\n\[profiles\.fast\]/)
 })
 
 test('codex: keeps CRLF line endings', () => {
   const sb = sandbox()
-  sb.write('.codex/config.toml', 'model = "gpt-5"\r\n\r\n[mcp_servers.box]\r\nurl = "https://old"\r\n\r\n[profiles.x]\r\nmodel = "m"\r\n')
+  sb.write('.codex/config.toml', 'model = "gpt-5"\r\n\r\n[mcp_servers.box]\r\nurl = "https://relay.simular.cloud/old"\r\n\r\n[profiles.x]\r\nmodel = "m"\r\n')
   client('codex').connect(sb.ctx)
   assert.equal(sb.read('.codex/config.toml'), 'model = "gpt-5"\r\n\r\n[profiles.x]\r\nmodel = "m"\r\n\r\n[mcp_servers.box]\r\nurl = "https://relay.simular.cloud/mcp"\r\n')
   client('codex').remove(sb.ctx)
@@ -85,7 +86,7 @@ test('codex: honours CODEX_HOME', () => {
 
 test('codex: refuses an inline box table it cannot edit safely', () => {
   const sb = sandbox()
-  const text = 'mcp_servers = { box = { url = "https://x" } }\n'
+  const text = 'mcp_servers = { box = { url = "https://relay.simular.cloud/mcp-old" } }\n'
   sb.write('.codex/config.toml', text)
   assert.throws(() => client('codex').connect(sb.ctx), /inline/)
   assert.equal(sb.read('.codex/config.toml'), text)
@@ -177,7 +178,7 @@ test('openclaw: warns when the header references BOX_TOKEN but .env lacks it (th
 
 test('claude-code: default URL installs the plugin from the marketplace; override uses claude mcp add', { skip: NO_FAKE_BINS }, () => {
   const sb = sandbox({ bins: { claude: FAKE_CLAUDE } })
-  sb.write('.claude.json', JSON.stringify({ mcpServers: { 'box-control': { url: 'x' }, box: { type: 'http', url: DEFAULT_MCP_URL }, other: { command: 'y' } } }))
+  sb.write('.claude.json', JSON.stringify({ mcpServers: { 'box-control': { url: 'https://relay.simular.cloud/control' }, box: { type: 'http', url: DEFAULT_MCP_URL }, other: { command: 'y' } } }))
   client('claude').connect(sb.ctx)
   const state = () => JSON.parse(sb.read('fake-claude-state.json'))
   assert.deepEqual(state().plugins, { 'box@simular-box': { enabled: true } })
@@ -191,7 +192,8 @@ test('claude-code: default URL installs the plugin from the marketplace; overrid
   assert.equal(state().plugins['box@simular-box'].enabled, false)
   assert.equal(client('claude').status(ctx).entries.length, 1)
 
-  client('claude').remove(sb.ctx)
+  // remove runs with the same BOX_MCP_URL, so the staging host counts as ours.
+  client('claude').remove(ctx)
   assert.deepEqual(state().plugins, {})
   assert.equal(JSON.parse(sb.read('.claude.json')).mcpServers.box, undefined)
 })
@@ -212,3 +214,108 @@ test('dry run writes nothing for file-based clients', () => {
   }
   assert.deepEqual(fs.readdirSync(sb.home), ['.bin'])
 })
+
+// ---- someone else's `box` (e.g. box.com's MCP server) is never ours to change or remove ----
+
+const BOX_COM = 'https://mcp.box.com'
+
+test('json clients: a foreign box blocks connect, survives remove, and --name installs next to it', () => {
+  const cases = [
+    ['cursor', '.cursor/mcp.json', ['mcpServers']],
+    ['opencode', '.config/opencode/opencode.json', ['mcp']],
+    ['vscode', '.config/Code/User/mcp.json', ['servers']],
+  ]
+  for (const [id, rel, container] of cases) {
+    const sb = sandbox()
+    const foreign = { url: BOX_COM, headers: { Authorization: 'Bearer box-com-token' } }
+    const original = JSON.stringify(container.reduceRight((acc, k) => ({ [k]: acc }), { box: foreign }), null, 2)
+    sb.write(rel, original)
+    assert.throws(() => client(id).connect(sb.ctx), (e) => e.foreign && /--name/.test(e.message), id)
+    assert.equal(sb.read(rel), original, `${id}: file untouched`)
+    const rm = client(id).remove(sb.ctx)
+    assert.equal(sb.read(rel), original, `${id}: remove leaves it`)
+    assert.match(rm.warnings.join(' '), /not box by Simular/)
+    assert.ok(client(id).status(sb.ctx).foreign, `${id}: status reports it`)
+
+    const named = { ...sb.ctx, name: 'simular-box' }
+    client(id).connect(named)
+    let doc = jsonc.parse(sb.read(rel))
+    let map = container.reduce((acc, k) => acc[k], doc)
+    assert.deepEqual(map.box, foreign, `${id}: foreign box kept`)
+    assert.equal(map['simular-box'].url, DEFAULT_MCP_URL)
+    client(id).remove(named)
+    doc = jsonc.parse(sb.read(rel))
+    map = container.reduce((acc, k) => acc[k], doc)
+    assert.deepEqual(Object.keys(map), ['box'])
+  }
+})
+
+test('codex: a foreign [mcp_servers.box] is left alone, fields and all', () => {
+  const sb = sandbox()
+  const original = `[mcp_servers.box]\nurl = "${BOX_COM}"\nbearer_token_env_var = "BOX_COM_TOKEN"\n`
+  sb.write('.codex/config.toml', original)
+  assert.throws(() => client('codex').connect(sb.ctx), /not box by Simular/)
+  client('codex').remove(sb.ctx)
+  assert.equal(sb.read('.codex/config.toml'), original)
+  client('codex').connect({ ...sb.ctx, name: 'simular-box' })
+  const doc = plain(TOML.parse(sb.read('.codex/config.toml')))
+  assert.deepEqual(doc.mcp_servers.box, { url: BOX_COM, bearer_token_env_var: 'BOX_COM_TOKEN' })
+  assert.deepEqual(doc.mcp_servers['simular-box'], { url: DEFAULT_MCP_URL })
+})
+
+test('codex: removing box keeps the comment above the next table', () => {
+  const sb = sandbox()
+  sb.write('.codex/config.toml', `model = "o3"\n\n[mcp_servers.box]\nurl = "${DEFAULT_MCP_URL}"\n\n# Linear: my work tracker (keep!)\n[mcp_servers.linear]\nurl = "https://mcp.linear.app/mcp"\n`)
+  client('codex').remove(sb.ctx)
+  assert.equal(sb.read('.codex/config.toml'), `model = "o3"\n\n# Linear: my work tracker (keep!)\n[mcp_servers.linear]\nurl = "https://mcp.linear.app/mcp"\n`)
+})
+
+test('hermes: a foreign box blocks connect and survives remove', () => {
+  const sb = sandbox()
+  const original = `mcp_servers:\n  box:\n    url: ${BOX_COM}\n    headers:\n      Authorization: Bearer \${BOX_COM_TOKEN}\n`
+  sb.write('.hermes/config.yaml', original)
+  assert.throws(() => client('hermes').connect(sb.ctx, { mode: 'oauth' }), /--name/)
+  client('hermes').remove(sb.ctx)
+  assert.equal(sb.read('.hermes/config.yaml'), original)
+})
+
+test('openclaw: a foreign box blocks connect and survives remove', { skip: NO_FAKE_BINS }, () => {
+  const sb = sandbox({ bins: { openclaw: FAKE_OPENCLAW } })
+  sb.write('.openclaw/openclaw.json', JSON.stringify({ mcp: { servers: { box: { url: BOX_COM, transport: 'streamable-http' } } } }))
+  assert.throws(() => client('openclaw').connect(sb.ctx, { mode: 'oauth' }), /--name/)
+  const rm = client('openclaw').remove(sb.ctx)
+  assert.deepEqual(rm.actions, [])
+  assert.equal(JSON.parse(sb.read('.openclaw/openclaw.json')).mcp.servers.box.url, BOX_COM)
+})
+
+test('claude-code: a foreign user-scope box is never removed', { skip: NO_FAKE_BINS }, () => {
+  const sb = sandbox({ bins: { claude: FAKE_CLAUDE } })
+  sb.write('.claude.json', JSON.stringify({ mcpServers: { box: { type: 'http', url: BOX_COM } } }))
+  client('claude').connect(sb.ctx) // plugin route: its server is plugin:box:box, no clash
+  assert.equal(JSON.parse(sb.read('.claude.json')).mcpServers.box.url, BOX_COM)
+  const override = { ...sb.ctx, url: 'https://staging.relay.simular.cloud/mcp' }
+  assert.throws(() => client('claude').connect(override), /--name/)
+  client('claude').remove(sb.ctx)
+  assert.equal(JSON.parse(sb.read('.claude.json')).mcpServers.box.url, BOX_COM)
+  assert.ok(!JSON.parse(sb.read('fake-claude-state.json')).calls.some((c) => c.startsWith('mcp remove')))
+})
+
+test('a symlinked config stays a symlink and the target is updated', { skip: WIN && 'symlinks need admin on Windows' }, () => {
+  const sb = sandbox()
+  const real = sb.write('dotfiles/cursor-mcp.json', '{ "mcpServers": {} }\n')
+  fs.mkdirSync(path.join(sb.home, '.cursor'))
+  fs.symlinkSync(real, path.join(sb.home, '.cursor', 'mcp.json'))
+  client('cursor').connect(sb.ctx)
+  assert.ok(fs.lstatSync(path.join(sb.home, '.cursor', 'mcp.json')).isSymbolicLink())
+  assert.equal(JSON.parse(fs.readFileSync(real, 'utf8')).mcpServers.box.url, DEFAULT_MCP_URL)
+})
+
+test('key files: no backup keeps an old key after rotation or remove', () => {
+  const sb = sandbox()
+  client('hermes').connect(sb.ctx, { mode: 'key', key: KEY })
+  client('hermes').connect(sb.ctx, { mode: 'key', key: 'cb_rotated_key_456' })
+  client('hermes').remove(sb.ctx)
+  const leftovers = fs.readdirSync(path.join(sb.home, '.hermes')).filter((f) => f.startsWith('.env'))
+  assert.deepEqual(leftovers, ['.env'])
+  assert.equal(sb.read('.hermes/.env'), '')
+})
diff --git a/cli/test/fixtures/codex.after.toml b/cli/test/fixtures/codex.after.toml
index f8dff24..ab02a4a 100644
--- a/cli/test/fixtures/codex.after.toml
+++ b/cli/test/fixtures/codex.after.toml
@@ -5,8 +5,13 @@ model = "gpt-5"
 command = "npx"
 args = ["docs-mcp"] # keep this comment
 
+[mcp_servers.box.tools.shell]
+approval_mode = "approve"
+
+# Profiles: keep this comment with its table
 [profiles.fast]
 model = "gpt-5-mini"
 
 [mcp_servers.box]
 url = "https://relay.simular.cloud/mcp"
+startup_timeout_sec = 30
diff --git a/cli/test/fixtures/codex.before.toml b/cli/test/fixtures/codex.before.toml
index 4efe927..76a1154 100644
--- a/cli/test/fixtures/codex.before.toml
+++ b/cli/test/fixtures/codex.before.toml
@@ -6,8 +6,9 @@ command = "npx"
 args = ["docs-mcp"] # keep this comment
 
 [mcp_servers.box]
-url = "https://old.example.com/mcp"
+url = "https://relay.simular.cloud/old-mcp"
 bearer_token_env_var = "OLD"
+startup_timeout_sec = 30
 
 [mcp_servers.box.tools.shell]
 approval_mode = "approve"
@@ -15,5 +16,6 @@ approval_mode = "approve"
 [mcp_servers."box-control"]
 url = "https://relay.simular.cloud/control"
 
+# Profiles: keep this comment with its table
 [profiles.fast]
 model = "gpt-5-mini"

From c53292334215adfd9a3d827ac7b5991ec35f7e70 Mon Sep 17 00:00:00 2001
From: chenchen <chenchen@simular.ai>
Date: Tue, 3 Nov 2026 08:48:00 +0800
Subject: [PATCH 5/5] cli: find Hermes's .env through its adapter in the
 real-CLI test (LOCALAPPDATA on Windows)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 cli/test/cli.test.js | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/cli/test/cli.test.js b/cli/test/cli.test.js
index 5f52f33..623ca7e 100644
--- a/cli/test/cli.test.js
+++ b/cli/test/cli.test.js
@@ -8,6 +8,9 @@ import { mcpUrl, maskKey, DEFAULT_MCP_URL } from '../src/constants.js'
 import { parseWwwAuthenticate, probeEndpoint, checkKey } from '../src/probe.js'
 import { runDoctor } from '../src/cli.js'
 import { sandbox } from './helpers.js'
+import fs from 'node:fs'
+import { createContext } from '../src/context.js'
+import { findClient } from '../src/clients/index.js'
 
 const BIN = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'bin', 'simular-box.js')
 const KEY = 'cb_test_fake_key_123'
@@ -93,7 +96,9 @@ test('real CLI: key mode without a key fails clearly; with BOX_TOKEN it never pr
   const withKey = run(['connect', '--client', 'hermes', '--auth', 'key', '--yes'], sb, { BOX_TOKEN: KEY })
   assert.equal(withKey.status, 0, withKey.stderr)
   assert.ok(!(withKey.stdout + withKey.stderr).includes(KEY))
-  assert.match(sb.read('.hermes/.env'), new RegExp(`^MCP_BOX_API_KEY=${KEY}$`, 'm'))
+  // Hermes keeps its home in %LOCALAPPDATA%\\hermes on Windows and ~/.hermes elsewhere.
+  const hermesEnv = path.join(path.dirname(findClient('hermes').configLocation(createContext({ env: sb.env }))), '.env')
+  assert.match(fs.readFileSync(hermesEnv, 'utf8'), new RegExp(`^MCP_BOX_API_KEY=${KEY}$`, 'm'))
   const bad = run(['connect', '--client', 'hermes', '--auth', 'key', '--yes'], sb, { BOX_TOKEN: 'not-a-key' })
   assert.notEqual(bad.status, 0)
 })