@useshifu/coding-harness 0.3.22 → 0.3.23

package/README.md

@@ -32,7 +32,7 @@ To disconnect this device, run `npx --yes @useshifu/coding-harness disconnect --
 
 ## Operate
 
-Version `0.3.22` retrieves context at substantive task starts and new topics, tracks current topic coverage, and surfaces Shifu-attributed support or discrepancies alongside proposals and actions. Current user instructions take precedence over historical context; adopted choices and rationale remain available to existing session sync.
+Version `0.3.23` is the npm `latest` release. It retrieves context at substantive task starts and new topics, tracks current topic coverage, and surfaces Shifu-attributed support or discrepancies alongside proposals and actions. Current user instructions take precedence over historical context; adopted choices and rationale remain available to existing session sync.
 
 Version `0.3.21` adds meaningful decision and reflection checkpoints to the managed context guidance: historical reinforcement, discrepancies and goal-aware coaching, with current-context reuse and optional clarification. Existing managed blocks refresh on upgrade.
 
@@ -91,7 +91,7 @@ The AI Profile page shows detected categories, model and thinking labels, and Je
 
 The connection endpoint returns `recommendedPackageVersion`, pinned to a published release. Before `sync`, `sync-files`, `approve`, or `scheduled-sync`, the runner compares its embedded release version with that property. An older runner installs the exact recommended release through npm and resumes the original command with the updated runner. Equal or newer runners continue unchanged. Explicitly recommended major releases follow the same comparison rule. Missing or invalid recommendations, connection failures, and npm failures do not block sync. The connection, pending work, checkpoints, and schedule are preserved.
 
-This update mechanism first ships in `0.3.10`. Runners from earlier releases need a one-time installation of a release containing it (`npx --yes @useshifu/coding-harness@0.3.14 install --harness codex`). Raise the server recommendation only after the target release is published and its backend requirements are deployed.
+This update mechanism first ships in `0.3.10`. Runners from earlier releases need a one-time installation of a release containing it (`npx --yes @useshifu/coding-harness@0.3.23 install --harness codex`). Raise the server recommendation only after the target release is published and its backend requirements are deployed.
 
 ## Force sync local work
 
@@ -122,7 +122,7 @@ Setup preserves other instruction text and MCP settings. Package installation re
 The context branch adds a remote MCP connection using the same saved Codex key:
 
 ```sh
-npx --yes @useshifu/coding-harness@0.3.22 mcp-setup --harness codex --mcp-url https://YOUR-BRANCH-HOST/mcp
+npx --yes @useshifu/coding-harness@0.3.23 mcp-setup --harness codex --mcp-url https://YOUR-BRANCH-HOST/mcp
 ```
 
 For development, install dependencies and run from the checkout root:
@@ -153,23 +153,27 @@ Official configuration reference: https://learn.chatgpt.com/docs/config-file/con
 OpenCode uses the same `/mcp` endpoint and three tools, authenticated with its own saved OpenCode connection key:
 
 ```sh
-npx --yes @useshifu/coding-harness@0.3.22 mcp-setup --harness opencode --mcp-url https://YOUR-SHIFU-HOST/mcp
+npx --yes @useshifu/coding-harness@0.3.23 mcp-setup --harness opencode --mcp-url https://YOUR-SHIFU-HOST/mcp
 ```
 
 For checkout usage, install dependencies with `npm ci --prefix packages/shifu-coding-harness --ignore-scripts` from the checkout root, then run the checkout CLI with the same arguments. Setup preserves existing sync settings and other MCP servers, checks authenticated initialization and tool discovery, and installs the `shifu-context` usage instructions. A missing OpenCode connection prompts for its key in the terminal. A Codex key cannot authorize an OpenCode connection.
 
-The installer adds a remote `shifu` entry with `oauth: false` to OpenCode's JSON or JSONC configuration, preserving existing content and comments. Its Authorization header uses OpenCode's `{file:...}` substitution to read a protected local credential file; the key stays out of configuration, command arguments and chat. Replacing the saved connection key refreshes that file; disconnect removes it. Restart OpenCode and start a new session after setup. Project-specific configuration can override global MCP settings; inspect `opencode mcp list` in the project if tools do not appear.
+The installer detects OpenCode 1.x or 2.x and validates configuration through that installed client before changing files. V1 uses `mcp.shifu`; V2 uses `mcp.servers.shifu`, direct tool exposure (`codemode: false`), and separate startup/catalog (30 seconds) and execution (300 seconds) budgets. Older V2 builds that discard these options fail validation with an update instruction. Existing unrelated settings and comments are preserved. A managed V1 Shifu entry in the selected file moves to the V2 location during setup.
+
+The installer adds a remote `shifu` entry with `oauth: false` to OpenCode's JSON or JSONC configuration, preserving existing content and comments. Its Authorization header uses OpenCode's `{file:...}` substitution to read a protected local credential file; the key stays out of configuration, command arguments and chat. Replacing the saved connection key refreshes that file; disconnect removes it. Restart OpenCode and start a new session after setup. For V2, run `opencode service stop` before reopening it so the background service loads the new connection. Project-specific configuration can override global MCP settings; inspect `opencode mcp list` in the project if tools do not appear.
 
 The API derives the harness and tenant from the authenticated connector key. Memory updates from OpenCode carry `opencode` provenance; personal eligibility, general retrieval and evidence verification use the same rules as Codex. Coding-session sync remains separate. No additional local MCP server or OpenCode plugin is required.
 
-Official references: [MCP servers](https://docs.opencode.ai/docs/mcp-servers/) and [configuration](https://docs.opencode.ai/docs/config/).
+Official references: [V1 MCP servers](https://opencode.ai/docs/mcp-servers/), [V2 MCP servers](https://opencode.ai/v2/docs/mcp-servers/) and [V2 migration](https://opencode.ai/v2/docs/migrate-v1/).
+
+For the optional native integration gate, set `SHIFU_TEST_OPENCODE_BIN` to a temporary official OpenCode 2.x binary and run `node --test test/opencode-native.test.js` from this package. It uses isolated configuration, a synthetic credential and local MCP/model fixtures; it checks setup, native credential-file authentication, discovery and a model-driven tool call without a user key or paid model.
 
 ## Claude Code context and memory
 
 Claude Code connects to the same `/mcp` endpoint and three tools with its own saved connection key:
 
 ```sh
-npx --yes @useshifu/coding-harness@0.3.22 mcp-setup --harness claude_code --mcp-url https://YOUR-SHIFU-HOST/mcp
+npx --yes @useshifu/coding-harness@0.3.23 mcp-setup --harness claude_code --mcp-url https://YOUR-SHIFU-HOST/mcp
 ```
 
 For checkout usage, install dependencies as above and run the checkout CLI with these arguments. Setup checks the existing Claude Code key, authenticated initialization and tool discovery, and installs the `shifu-context` skill. It preserves the sync endpoint, schedule, checkpoints and other MCP servers. A missing connection prompts for a Claude Code key in the terminal; do not substitute a Codex or OpenCode key.

package/bin/shifu-harness.js

@@ -40,7 +40,7 @@ const MAX_TURNS_PER_SEGMENT = 12;
 const MAX_TITLE_LENGTH = 160;
 const MAX_WORK_DETAIL_LENGTH = 600;
 const CONFIG_VERSION = 2;
-const RUNNER_VERSION = "0.3.22";
+const RUNNER_VERSION = "0.3.23";
 const REDACTION_VERSION = 4;
 const DEFAULT_INTERVAL_HOURS = 1;
 const LEGACY_INTERVAL_HOURS = 4;
@@ -1430,7 +1430,7 @@ async function validateConnection(apiUrl, token, harness) {
 
 async function connect(harness, readKey = readSecret) {
   const existing = readJSON(configPath(harness), undefined);
-  const refreshContextKey = harness === "opencode" && existing?.mcpUrl && openCodeMcpConfigs().some((config) => managedOpenCodeMcp(config.value?.mcp?.shifu));
+  const refreshContextKey = harness === "opencode" && existing?.mcpUrl && openCodeMcpConfigs(existing.mcpConfigMajor).some((config) => managedOpenCodeMcp(config.value?.mcp?.shifu) || managedOpenCodeMcp(config.value?.mcp?.servers?.shifu));
   const token = (await readKey()).trim();
   if (!TOKEN_PATTERN.test(token)) throw new Error("The connection key is invalid.");
   const apiUrl = requireSafeApiUrl(option("--api-url") || existing?.apiUrl || process.env.SHIFU_API_URL || DEFAULT_API_URL);
@@ -1609,8 +1609,18 @@ function openCodeTokenPath() {
   return file;
 }
 
-function openCodeMcpConfigs() {
-  return ["config.json", "opencode.json", "opencode.jsonc"].map((name) => {
+function openCodeVersion() {
+  try {
+    const output = execFileSync(process.env.SHIFU_OPENCODE_BIN || "opencode", ["--version"], { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", timeout: 10_000, maxBuffer: 1024 * 1024 });
+    const version = output.trim().match(/^(?:opencode\s+)?v?(\d+\.\d+\.\d+)(?:[-+][\w.-]+)?$/)?.[1];
+    if (version && [1, 2].includes(Number(version.split(".")[0]))) return version;
+  } catch { /* Native output can contain settings; report only the remedy. */ }
+  throw new Error("Could not identify a supported OpenCode 1.x or 2.x client. Install or update OpenCode before MCP setup; nothing was changed.");
+}
+
+function openCodeMcpConfigs(major = 1) {
+  const names = major === 2 ? ["opencode.json", "opencode.jsonc"] : ["config.json", "opencode.json", "opencode.jsonc"];
+  return names.map((name) => {
     const file = path.join(openCodeConfigRoot(), name);
     const exists = fs.existsSync(file);
     if (exists && !fs.lstatSync(file).isFile()) throw new Error("OpenCode configuration must be a regular file, not a link. Nothing was changed.");
@@ -1620,7 +1630,7 @@ function openCodeMcpConfigs() {
     if (errors.length || !value || typeof value !== "object" || Array.isArray(value) || (value.mcp !== undefined && (!value.mcp || typeof value.mcp !== "object" || Array.isArray(value.mcp)))) {
       throw new Error("OpenCode configuration is invalid. Fix its JSON/JSONC before MCP setup; nothing was changed.");
     }
-    if (value.$schema && value.$schema !== "https://opencode.ai/config.json") throw new Error("This OpenCode configuration schema is unsupported. Use the OpenCode v1 config.json schema before MCP setup.");
+    if (value.$schema && value.$schema !== "https://opencode.ai/config.json") throw new Error("This OpenCode configuration schema is unsupported. Use the official OpenCode config.json schema before MCP setup.");
     return { file, original, exists, value };
   });
 }
@@ -1629,8 +1639,9 @@ function managedOpenCodeMcp(config) {
   return config?.type === "remote" && config.headers?.Authorization === `Bearer {file:${openCodeTokenPath()}}`;
 }
 
-function editOpenCodeMcp(original, value) {
-  return jsonc.applyEdits(original || "{}\n", jsonc.modify(original || "{}\n", ["mcp", "shifu"], value, { formattingOptions: { insertSpaces: true, tabSize: 2, eol: "\n" } }));
+function editOpenCodeMcp(original, value, major = 1) {
+  const target = major === 2 ? ["mcp", "servers", "shifu"] : ["mcp", "shifu"];
+  return jsonc.applyEdits(original || "{}\n", jsonc.modify(original || "{}\n", target, value, { formattingOptions: { insertSpaces: true, tabSize: 2, eol: "\n" } }));
 }
 
 function writePrivateText(file, text) {
@@ -1648,12 +1659,15 @@ function unchangedConfig(config) {
   return fs.existsSync(config.file) === config.exists && (config.exists ? fs.readFileSync(config.file, "utf8") : "") === config.original;
 }
 
-function validateOpenCodeMcpConfig(configs, prepared, mcpUrl) {
+function validateOpenCodeMcpConfig(configs, prepared, mcpUrl, major) {
   const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "shifu-opencode-mcp-"));
   const configDirectory = path.join(temporary, "config", "opencode");
   const probeToken = path.join(temporary, "probe.key");
   const environment = { ...process.env, HOME: temporary, XDG_CONFIG_HOME: path.join(temporary, "config"), XDG_DATA_HOME: path.join(temporary, "data"), XDG_CACHE_HOME: path.join(temporary, "cache"), XDG_STATE_HOME: path.join(temporary, "state"), OPENCODE_DISABLE_PROJECT_CONFIG: "1" };
-  for (const key of ["OPENCODE_CONFIG", "OPENCODE_CONFIG_DIR", "OPENCODE_CONFIG_CONTENT", "OPENCODE_PERMISSION"]) delete environment[key];
+  for (const key of Object.keys(environment)) {
+    if (major === 2 ? key.startsWith("OPENCODE_") : ["OPENCODE_CONFIG", "OPENCODE_CONFIG_DIR", "OPENCODE_CONFIG_CONTENT", "OPENCODE_PERMISSION"].includes(key)) delete environment[key];
+  }
+  environment.OPENCODE_DISABLE_PROJECT_CONFIG = "1";
   try {
     fs.mkdirSync(configDirectory, { recursive: true, mode: 0o700 });
     fs.writeFileSync(probeToken, "shifu-probe-only", { mode: 0o600 });
@@ -1667,34 +1681,57 @@ function validateOpenCodeMcpConfig(configs, prepared, mcpUrl) {
       });
       fs.writeFileSync(path.join(configDirectory, path.basename(config.file)), text, { mode: 0o600 });
     }
-    const output = execFileSync(process.env.SHIFU_OPENCODE_BIN || "opencode", ["debug", "config", "--pure"], { cwd: temporary, env: environment, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", timeout: 30_000, maxBuffer: 8 * 1024 * 1024 });
-    const resolved = JSON.parse(output).mcp?.shifu;
-    if (resolved?.type !== "remote" || resolved.url !== mcpUrl || resolved.enabled !== true || resolved.oauth !== false || resolved.timeout !== 120_000 || resolved.headers?.Authorization !== "Bearer shifu-probe-only") {
+    const command = process.env.SHIFU_OPENCODE_BIN || "opencode";
+    const options = { cwd: temporary, env: environment, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", timeout: 30_000, maxBuffer: 8 * 1024 * 1024 };
+    // V2 debug commands otherwise attach to a shared daemon, even with an isolated HOME.
+    if (major === 2) execFileSync(command, ["service", "set", "disabled", "true"], options);
+    const args = major === 2 ? ["debug", "config"] : ["debug", "config", "--pure"];
+    const output = execFileSync(command, args, options);
+    const report = JSON.parse(output);
+    const resolved = major === 2
+      ? report.find((source) => source.type === "document" && source.path === path.join(configDirectory, path.basename(prepared.file)))?.info?.mcp?.servers?.shifu
+      : report.mcp?.shifu;
+    const accepted = major === 2
+      ? resolved?.disabled !== true && resolved?.codemode === false && resolved?.timeout?.startup === 30_000 && resolved?.timeout?.catalog === 30_000 && resolved?.timeout?.execution === 300_000 && resolved?.headers?.Authorization === "***"
+      : resolved?.enabled === true && resolved?.timeout === 120_000 && resolved?.headers?.Authorization === "Bearer shifu-probe-only";
+    if (resolved?.type !== "remote" || resolved.url !== mcpUrl || resolved.oauth !== false || !accepted) {
       throw new Error("OpenCode did not accept the expected Shifu remote MCP configuration.");
     }
   } catch (error) {
     if (error?.code === "ENOENT") throw new Error("The opencode command is unavailable. Install OpenCode CLI before MCP setup.");
     // Native diagnostics may contain expanded secrets from existing settings.
-    throw new Error("OpenCode could not validate its v1 remote MCP configuration. Update OpenCode or fix its existing config; nothing was changed.");
+    throw new Error(`OpenCode could not validate its ${major}.x remote MCP configuration. Update OpenCode or fix its existing config; nothing was changed.`);
   } finally {
     fs.rmSync(temporary, { recursive: true, force: true });
   }
 }
 
 function prepareOpenCodeMcpConfig(mcpUrl) {
-  const configs = openCodeMcpConfigs();
+  const major = Number(openCodeVersion().split(".")[0]);
+  const configs = openCodeMcpConfigs(major);
   const selected = configs.findLast((config) => config.exists) || configs.at(-1);
-  const entry = { type: "remote", url: mcpUrl, enabled: true, oauth: false, timeout: 120_000, headers: { Authorization: `Bearer {file:${openCodeTokenPath()}}` } };
-  const prepared = { ...selected, candidate: editOpenCodeMcp(selected.original, entry), configs };
-  validateOpenCodeMcpConfig(configs, prepared, mcpUrl);
+  const entry = {
+    type: "remote", url: mcpUrl, oauth: false,
+    headers: { Authorization: `Bearer {file:${openCodeTokenPath()}}` },
+    ...(major === 2
+      ? { disabled: false, codemode: false, timeout: { startup: 30_000, catalog: 30_000, execution: 300_000 } }
+      : { enabled: true, timeout: 120_000 }),
+  };
+  let candidate = selected.original;
+  if (major === 2 && managedOpenCodeMcp(selected.value.mcp?.shifu)) candidate = editOpenCodeMcp(candidate, undefined);
+  const prepared = { ...selected, candidate: editOpenCodeMcp(candidate, entry, major), configs, openCodeMajor: major };
+  validateOpenCodeMcpConfig(configs, prepared, mcpUrl, major);
   return prepared;
 }
 
-function removeOpenCodeMcpConfig() {
-  const updates = openCodeMcpConfigs().filter((config) => managedOpenCodeMcp(config.value?.mcp?.shifu));
+function removeOpenCodeMcpConfig(major) {
+  const updates = openCodeMcpConfigs(major).filter((config) => managedOpenCodeMcp(config.value?.mcp?.shifu) || managedOpenCodeMcp(config.value?.mcp?.servers?.shifu));
   for (const config of updates) {
     if (!unchangedConfig(config)) throw new Error("OpenCode configuration changed during disconnect. Retry to preserve those changes.");
-    writePrivateText(config.file, editOpenCodeMcp(config.original, undefined));
+    let candidate = config.original;
+    if (managedOpenCodeMcp(config.value?.mcp?.shifu)) candidate = editOpenCodeMcp(candidate, undefined);
+    if (managedOpenCodeMcp(config.value?.mcp?.servers?.shifu)) candidate = editOpenCodeMcp(candidate, undefined, 2);
+    writePrivateText(config.file, candidate);
   }
   fs.rmSync(openCodeTokenPath(), { force: true });
 }
@@ -1802,7 +1839,7 @@ function contextInstructionFile(harness) {
     // Older clients fall back to XDG rules; current clients use the custom home.
     let version;
     try {
-      version = execFileSync(process.env.SHIFU_OPENCODE_BIN || "opencode", ["--version"], { stdio: ["ignore", "pipe", "pipe"], encoding: "utf8", timeout: 10_000, maxBuffer: 1024 * 1024 }).match(/^(\d+\.\d+\.\d+)\b/m)?.[1];
+      version = openCodeVersion();
     } catch { /* Diagnostics can contain settings; report only the remedy. */ }
     if (!version || olderPackageVersion(version, "1.18.30")) throw new Error("OpenCode's custom instruction home conflicts with existing XDG rules. Upgrade to OpenCode 1.18.30 or later, or unset OPENCODE_CONFIG_DIR before MCP setup; nothing was changed.");
   }
@@ -1899,17 +1936,18 @@ async function setupMcp(harness) {
   if (!unchangedContextInstructions(instructions)) throw new Error("The global instructions changed during setup. Run mcp-setup again to preserve those changes.");
   if (harness === "opencode") writePrivateText(openCodeTokenPath(), config.token);
   writePrivateText(prepared.file, prepared.candidate);
-  writeJSON(configPath(harness), { ...config, mcpUrl, ...(harness === "claude_code" ? { mcpHeadersHelper: helper } : {}) });
+  writeJSON(configPath(harness), { ...config, mcpUrl, ...(harness === "opencode" ? { mcpConfigMajor: prepared.openCodeMajor } : {}), ...(harness === "claude_code" ? { mcpHeadersHelper: helper } : {}) });
   writeContextInstructions(instructions);
   console.error(`Verified Shifu MCP tools: ${tools.join(", ")}. ${HARNESS_NAMES[harness]} configuration and usage instructions are installed.`);
   console.error(`The existing connection key is read ${harness === "opencode" ? "from a private credential file" : "by a local credential helper"}; it was not copied into MCP configuration. The sync endpoint and schedule were preserved.`);
-  console.error(`Proactive context guidance is installed at ${instructions.file}. Reload ${HARNESS_NAMES[harness]} or start a new chat to load the MCP tools and instructions. This setup check does not prove the current chat has loaded them or enforce tool calls.`);
+  const reload = prepared.openCodeMajor === 2 ? "Run opencode service stop, reopen OpenCode and start a new chat" : `Reload ${HARNESS_NAMES[harness]} or start a new chat`;
+  console.error(`Proactive context guidance is installed at ${instructions.file}. ${reload} to load the MCP tools and instructions. This setup check does not prove the current chat has loaded them or enforce tool calls.`);
 }
 
 function disconnect(harness) {
   const config = readConfig(harness);
   if (fs.existsSync(lockPath(harness))) throw new Error("A Shifu sync is running. Try disconnecting again after it finishes.");
-  if (harness === "opencode" && (config.mcpUrl || fs.existsSync(openCodeTokenPath()))) removeOpenCodeMcpConfig();
+  if (harness === "opencode" && (config.mcpUrl || fs.existsSync(openCodeTokenPath()))) removeOpenCodeMcpConfig(config.mcpConfigMajor);
   if (harness === "claude_code" && config.mcpUrl) removeClaudeMcpConfig(config.mcpHeadersHelper || helperCommand("claude_code"));
   removeSchedule(harness);
   for (const file of [configPath(harness), statePath(harness), pendingPath(harness)]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useshifu/coding-harness",
-  "version": "0.3.22",
+  "version": "0.3.23",
   "description": "Scheduled, redacted coding-harness activity sync for Shifu",
   "bin": {
     "coding-harness": "bin/shifu-harness.js",

package/skills/shifu-context/SKILL.md

@@ -10,12 +10,12 @@ description: Retrieve relevant work context at substantive task starts and new t
 When asked to connect Shifu context, run:
 
 ```sh
-npx --yes @useshifu/coding-harness@0.3.22 mcp-setup --harness codex
+npx --yes @useshifu/coding-harness@0.3.23 mcp-setup --harness codex
 ```
 
 For a branch deployment, append `--mcp-url` with the user's supplied HTTPS endpoint ending in `/mcp`. Keep the existing sync API endpoint. The CLI reuses this harness's saved key, checks the authenticated tools, and preserves existing settings. Codex and Claude Code use local credential helpers; OpenCode uses its native `{file:...}` substitution pointing to a private credential file. The key is never placed literally in MCP configuration. If no connection exists, the CLI asks for this harness's key in the terminal. Never request or print the key in chat or place it in command arguments. When input is unavailable, have the user run the command in an interactive terminal. Do not substitute plaintext credentials for an unsupported credential mechanism.
 
-Setup also installs a managed read-only context policy in the harness’s native global instruction file, preserving existing instructions. Reload the harness or start a new chat after setup. Check that the tools are actually available before claiming this chat can use them. Setup supports local macOS/Linux connections; remote execution environments cannot read this device's credential helper or file. OpenCode requires the v1 config schema (verified with 1.18.30). Claude Code requires HTTP MCP with `headersHelper` (verified with 2.1.295); setup validates it through the installed CLI. If Claude Code is outdated, help the user update it using official installation instructions before retrying. The connection uses user scope and honors `CLAUDE_CONFIG_DIR`. Restart Claude Code and start a new session, or use `/mcp` to reconnect after rotating the saved key. Unsupported versions or config schemas fail before MCP settings change.
+Setup also installs a managed read-only context policy in the harness’s native global instruction file, preserving existing instructions. Reload the harness or start a new chat after setup. Check that the tools are actually available before claiming this chat can use them. Setup supports local macOS/Linux connections; remote execution environments cannot read this device's credential helper or file. OpenCode setup detects 1.x or 2.x, writes the matching MCP shape and validates it through the installed client. V2 exposes Shifu tools directly and uses separate startup, catalog and execution budgets. The saved OpenCode key remains in its private credential file. After V2 setup, tell the user to run `opencode service stop`, reopen OpenCode and start a new chat; do not stop a running user service automatically. Claude Code requires HTTP MCP with `headersHelper` (verified with 2.1.295); setup validates it through the installed CLI. If Claude Code is outdated, help the user update it using official installation instructions before retrying. The connection uses user scope and honors `CLAUDE_CONFIG_DIR`. Restart Claude Code and start a new session, or use `/mcp` to reconnect after rotating the saved key. Unsupported versions or config schemas fail before MCP settings change.
 
 ## Consult context