@synap-core/cli 1.12.2 → 1.13.1-next.20261102.246dc73

package/dist/lib/targets.js

@@ -17,8 +17,9 @@ import chalk from "chalk";
 import ora from "ora";
 import prompts from "prompts";
 import { log } from "../utils/logger.js";
-import { writeSecretFile, copySecretBackup, ensureSecretDir } from "./atomic-file.js";
-import { redactKey } from "./mcp-snippets.js";
+import { writeSecretFile, ensureSecretDir, readClientConfig, writeClientConfig, clientConfigBackupPath, } from "./atomic-file.js";
+import { redactKey, mcpRemoteArgs, MCP_REMOTE_PACKAGE } from "./mcp-snippets.js";
+import { MANAGED_MCP_URL } from "./auth.js";
 import { installSkills, getDeliverableSkills } from "./skills-installer.js";
 import { TARGET_KEY_MINT, takePreApprovedKey } from "./batch-approval.js";
 import { agentTypeOfSurface, machineInstanceId, machineInstanceLabel } from "./machine-instance.js";
@@ -144,38 +145,6 @@ function claudeDesktopBaseDir() {
             return CLAUDE_DESKTOP_LINUX;
     }
 }
-/** Raycast app-support root (macOS only — Raycast is macOS-only). */
-function raycastSupportDir() {
-    return path.join(os.homedir(), "Library", "Application Support", "com.raycast.macos");
-}
-/**
- * Locate Raycast's EXISTING `mcp-config.json`. Raycast stores all non-dev MCP
- * servers in ONE file inside the "Manage MCP Servers" extension's support
- * directory — an opaque UUID folder under `…/com.raycast.macos/extensions/`.
- * The folder name is only known to Raycast and the file is created lazily the
- * first time the user opens "Manage MCP Servers".
- *
- * We therefore scan the support dirs for an EXISTING `mcp-config.json` and
- * return its path (so we can merge into it). Returns `null` when none exists —
- * the caller then prints the block for the user to paste via Raycast's
- * "Show Config File in Finder" action (the only reliable first-time path).
- */
-function raycastMcpConfigPath() {
-    const extensionsDir = path.join(raycastSupportDir(), "extensions");
-    try {
-        for (const entry of fs.readdirSync(extensionsDir, { withFileTypes: true })) {
-            if (!entry.isDirectory())
-                continue;
-            const candidate = path.join(extensionsDir, entry.name, "mcp-config.json");
-            if (fs.existsSync(candidate))
-                return candidate;
-        }
-    }
-    catch {
-        /* extensions dir missing — Raycast not installed or never opened */
-    }
-    return null;
-}
 export const TARGETS = {
     "claude-code": {
         name: "claude-code",
@@ -207,9 +176,11 @@ export const TARGETS = {
     },
     raycast: {
         name: "raycast",
-        keyStore: { format: "json", path: () => raycastMcpConfigPath() },
+        keyStore: {
+            none: "Raycast keeps its MCP sign-in in its own store; the commands' key is in ~/.synap/config.json",
+        },
         label: "Raycast",
-        description: "Native Synap extension (@synap) catalog — full MCP opt-in via --with-mcp",
+        description: "Synap extension commands + the pod's MCP server in Raycast AI (HTTP, OAuth)",
         supports: { skills: false, mcp: true },
     },
     openwebui: {
@@ -347,7 +318,7 @@ async function prepareMcpSurface(cfg, agentType, opts) {
     // site keeps showing "validate this proposal" on every reconnect. The pod
     // returns `alreadyValid` for an existing key; we recover the plaintext from
     // local storage and reuse it, rotating only on positive invalidation.
-    const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, agentType, { idempotent: opts?.idempotent ?? true });
+    const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, agentType, { idempotent: opts?.idempotent ?? true, toolProfile: opts?.toolProfile });
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
     return { effectiveApiKey, agentUserId, mcpUrl: buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId) };
 }
@@ -495,8 +466,8 @@ export async function installForTarget(target, cfg, opts) {
             result = await installGeneric(cfg);
             break;
     }
-    // Post-install: agent context wizard for MCP targets. Skip Raycast — native
-    // and --with-mcp use the extension catalog / opt-in MCP; CONTEXT.md has no Raycast consumer.
+    // Post-install: agent context wizard for MCP targets. Skip Raycast — its AI
+    // reads the pod's MCP instructions; CONTEXT.md has no Raycast consumer.
     if (result && info.supports.mcp && target !== "generic" && target !== "raycast") {
         const { getSurfaceAgentKey } = await import("./pod.js");
         const saved = getSurfaceAgentKey(target);
@@ -666,13 +637,10 @@ export async function resolveWorkspaceId(cfg) {
 export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
     const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
     const settingsDir = path.dirname(settingsPath);
-    let settings = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
-        }
-        catch { /* start fresh */ }
-    }
+    // Throws when the file exists but cannot be parsed: an unreadable
+    // settings.json is never rewritten as `{}` (it holds every hook, permission
+    // and env the person set).
+    const settings = readClientConfig(settingsPath);
     // ── Resolve human user ID and provision an agent-owned API key ──────────
     // SYNAP_USER_ID = human user (for entity attribution)
     // SYNAP_HUB_API_KEY = agent-owned key (identity encoded in the key itself)
@@ -756,7 +724,7 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
     if (!fs.existsSync(settingsDir)) {
         fs.mkdirSync(settingsDir, { recursive: true });
     }
-    writeSecretFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    writeClientConfig(settingsPath, settings);
     // ── Register the MCP server where Claude Code actually reads it ───────────
     // The official `claude mcp add` writes to the user-scope registry that
     // `claude mcp list` + the runtime consult — unlike settings.json mcpServers,
@@ -778,9 +746,11 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
  * Server name is pod-derived (`mcpServerNameFromPodUrl`) so multi-pod setups
  * (perso + team) do not overwrite each other — same pattern as Grok/Cursor.
  */
-function registerClaudeCodeMcp(mcpUrl, apiKey, serverName) {
+export function registerClaudeCodeMcp(mcpUrl, apiKey, serverName) {
     const header = `Authorization: Bearer ${apiKey}`;
     const bridge = claudeCodeMcpTransport() === "bridge";
+    const invocation = bridge ? resolveBridgeInvocation() : null;
+    const bridgeCommand = invocation ? synapBridgeCommand(mcpUrl, invocation) : [];
     try {
         // Remove legacy single-name entry and any prior pod-derived name.
         for (const name of new Set(["synap", serverName])) {
@@ -795,9 +765,14 @@ function registerClaudeCodeMcp(mcpUrl, apiKey, serverName) {
             ? // Stdio: Claude Code hands a stdio server its own session id, which
                 // the bridge forwards — see lib/mcp-bridge.ts. The key rides in the
                 // server's env, as the header does for http.
-                ["mcp", "add", "--scope", "user", "-e", `SYNAP_MCP_API_KEY=${apiKey}`, serverName, "--", ...synapBridgeCommand(mcpUrl)]
+                // `-e` is variadic in Claude Code's CLI: the server name must come
+                // BEFORE it, or `-e` swallows it as an env var.
+                ["mcp", "add", "--scope", "user", serverName, "-e", `SYNAP_MCP_API_KEY=${apiKey}`, "--", ...bridgeCommand]
             : ["mcp", "add", "--transport", "http", serverName, mcpUrl, "--header", header, "--scope", "user"], { stdio: "ignore" });
         log.success(`MCP server '${serverName}' registered with Claude Code (\`claude mcp add\`, user scope${bridge ? ", via the synap stdio bridge" : ""}). Relaunch Claude Code to load the tools.`);
+        const note = invocation && bridgeInvocationNote(invocation);
+        if (note)
+            log.dim(note);
         if (serverName !== "synap") {
             log.dim("Multi-pod: connect each profile separately — server names are derived from the pod host so they don't overwrite:");
             log.dim("  synap connect --target=claude-code --name=perso");
@@ -812,15 +787,20 @@ function registerClaudeCodeMcp(mcpUrl, apiKey, serverName) {
         try {
             ensureSecretDir(path.dirname(keyFile));
             writeSecretFile(keyFile, `export SYNAP_MCP_KEY='${apiKey}'\n`);
-            log.dim("Could not run `claude mcp add` (is the claude CLI on PATH?). Register it by hand (the key is in a 0600 file, not on this screen):");
+            log.dim(`Could not run \`claude mcp add\` (is the claude CLI on PATH?). The '${serverName}' MCP server may now be UNREGISTERED in Claude Code. Register it by hand (the key is in a 0600 file, not on this screen):`);
             log.dim(`  source ${keyFile}`);
-            log.dim(`  claude mcp add --transport http ${serverName} ${mcpUrl} --header 'Authorization: Bearer \${SYNAP_MCP_KEY}' --scope user`);
+            log.dim(bridge
+                ? `  claude mcp add --scope user ${serverName} -e SYNAP_MCP_API_KEY="$SYNAP_MCP_KEY" -- ${bridgeCommand.map(shellQuote).join(" ")}`
+                : `  claude mcp add --transport http ${serverName} ${mcpUrl} --header 'Authorization: Bearer \${SYNAP_MCP_KEY}' --scope user`);
         }
         catch {
             log.dim("Could not run `claude mcp add` (is the claude CLI on PATH?) and could not save the key file — run `synap mcp url` instead.");
         }
     }
 }
+function shellQuote(arg) {
+    return /^[A-Za-z0-9_\-./:=@]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
 /**
  * How Claude Code reaches the pod's MCP: `"http"` (direct) or `"bridge"` (the
  * synap stdio bridge, which tells the pod which Claude Code conversation each
@@ -844,13 +824,8 @@ export function claudeCodeMcpTransport() {
  */
 export function setClaudeCodeMcpTransport(transport) {
     const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
-    let settings;
-    try {
-        settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
-    }
-    catch {
-        return null;
-    }
+    // Missing → `{}` → no stored pod → null. Unreadable → throws (never rewritten).
+    const settings = readClientConfig(settingsPath);
     const env = (settings.env ?? {});
     const podUrl = env["SYNAP_POD_URL"];
     const apiKey = env["SYNAP_HUB_API_KEY"];
@@ -861,24 +836,59 @@ export function setClaudeCodeMcpTransport(transport) {
     else
         delete env["SYNAP_MCP_TRANSPORT"];
     settings.env = env;
-    writeSecretFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    writeClientConfig(settingsPath, settings);
     const serverName = mcpServerNameFromPodUrl(podUrl);
     registerClaudeCodeMcp(buildMcpUrl(podUrl, env["SYNAP_WORKSPACE_ID"], env["SYNAP_PROJECT_ID"]), apiKey, serverName);
     return serverName;
 }
-/**
- * The command Claude Code spawns for the bridge: THIS CLI by absolute path (the
- * one running `use-bridge` is the one known to have the bridge — a `synap` on
- * PATH may be an older install without it), unless this run is a throwaway
- * `npx` copy, whose cache path can vanish; then the `synap` on PATH.
- */
-function synapBridgeCommand(mcpUrl) {
-    const args = ["mcp", "bridge", "--url", mcpUrl];
-    const self = process.argv[1];
-    if (self && !self.includes(`${path.sep}_npx${path.sep}`)) {
-        return [process.execPath, fs.realpathSync(self), ...args];
+export function resolveBridgeInvocation(self = process.argv[1], execPath = process.execPath) {
+    const nm = `${path.sep}node_modules${path.sep}`;
+    if (!self || self.includes(`${path.sep}_npx${path.sep}`))
+        return { kind: "npx", command: ["synap"] };
+    const entry = path.resolve(self);
+    const realEntry = fs.realpathSync(entry);
+    const isLink = fs.lstatSync(entry).isSymbolicLink();
+    if (!isLink && !entry.includes(nm))
+        return { kind: "checkout", command: [execPath, realEntry], realEntry };
+    // Run through the package path (`<prefix>/lib/node_modules/@synap-core/cli/dist/index.js`):
+    // the bin npm installed next to it, when it leads to this same entry.
+    let installed = entry;
+    const pkgDir = `${nm}@synap-core${path.sep}cli${path.sep}`;
+    const at = entry.lastIndexOf(pkgDir);
+    if (!isLink && at >= 0) {
+        const prefix = entry.slice(0, at);
+        const bins = [
+            path.join(path.dirname(prefix), "bin", "synap"), // global: <prefix>/lib/node_modules → <prefix>/bin
+            path.join(prefix, "node_modules", ".bin", "synap"), // local: <dir>/node_modules → <dir>/node_modules/.bin
+        ];
+        for (const bin of bins) {
+            try {
+                if (fs.realpathSync(bin) === realEntry) {
+                    installed = bin;
+                    break;
+                }
+            }
+            catch {
+                /* no such bin — try the next */
+            }
+        }
     }
-    return ["synap", ...args];
+    return { kind: realEntry.includes(nm) ? "installed" : "linked", command: [execPath, installed], realEntry };
+}
+/** The command Claude Code spawns for the bridge (see `resolveBridgeInvocation`). */
+function synapBridgeCommand(mcpUrl, invocation) {
+    return [...invocation.command, "mcp", "bridge", "--url", mcpUrl];
+}
+/** One line on what the bridge runs, when it is not an installed release. */
+export function bridgeInvocationNote(invocation) {
+    const install = "To run a release instead: `npm install -g @synap-core/cli@next`, then `synap mcp use-bridge`.";
+    if (invocation.kind === "checkout") {
+        return `The MCP bridge runs this checkout build (${invocation.realEntry}), not an installed CLI. ${install}`;
+    }
+    if (invocation.kind === "linked") {
+        return `The MCP bridge runs the installed \`synap\` (${invocation.command[1]}), which is a link to a checkout (${invocation.realEntry}). ${install}`;
+    }
+    return null;
 }
 // ─── Agent key provisioning helper ──────────────────────────────────────────
 /**
@@ -923,7 +933,7 @@ export class AgentKeyMintError extends Error {
  *                     differs from the CLI surface (e.g. ChatGPT provisions under
  *                     "generic" but the CLI surface is "chatgpt").
  */
-export async function provisionAgentKey(podUrl, humanApiKey, agentType, { requireApproval = true, idempotent = false, surfaceName, deferApproval = false, instanceId, fallbackCandidate, } = {}) {
+export async function provisionAgentKey(podUrl, humanApiKey, agentType, { requireApproval = true, idempotent = false, surfaceName, deferApproval = false, instanceId, fallbackCandidate, toolProfile, } = {}) {
     // `synap init` already minted — and the person approved — this key in one
     // step with the others (`approveAgentKeysAtOnce`): hand it over, mint nothing.
     if (!deferApproval) {
@@ -988,6 +998,7 @@ export async function provisionAgentKey(podUrl, humanApiKey, agentType, { requir
                 requireApproval,
                 instanceId: instance,
                 instanceLabel: machineInstanceLabel(),
+                ...(toolProfile ? { toolProfile } : {}),
             }),
             signal: AbortSignal.timeout(30000),
         });
@@ -1059,6 +1070,7 @@ export async function provisionAgentKey(podUrl, humanApiKey, agentType, { requir
             surfaceName,
             deferApproval,
             instanceId: instance,
+            toolProfile,
         });
     }
     if (!body.hubApiKey) {
@@ -1204,7 +1216,7 @@ async function installClaudeDesktop(info, cfg) {
         command: "npx",
         // The header value rides in env (this file is 0600), never in the
         // mcp-remote process's argv where any local `ps` can read it.
-        args: ["-y", "mcp-remote", desktopMcpUrl, "--header", "Authorization:${SYNAP_AUTH}"],
+        args: mcpRemoteArgs(desktopMcpUrl),
         env: { SYNAP_AUTH: `Bearer ${effectiveApiKey}` },
     });
     if (desktopServerName !== "synap")
@@ -1276,10 +1288,20 @@ async function installCursor(info, cfg) {
     return true;
 }
 // ─── Raycast ─────────────────────────────────────────────────────────────────
+/**
+ * Raycast has two halves (decision B1, 2026-10-21):
+ *   - the Synap extension's native COMMANDS (search, capture, review…) call Hub
+ *     REST with a dedicated `raycast` agent key, read from ~/.synap/config.json;
+ *   - Raycast AI talks to the pod's own MCP server over HTTP (Streamable HTTP),
+ *     signed in with OAuth, or with that same agent key in a header as the
+ *     fallback. The extension ships no AI tools of its own any more.
+ *
+ * Raycast keeps its MCP servers in its own store, filled through its "Install
+ * MCP Server" form; its file format for an HTTP server is not documented, so we
+ * print the form's fields rather than write a guessed shape into Raycast's
+ * config. The key is never printed: the fallback header lives in a 0600 file.
+ */
 async function installRaycast(cfg) {
-    // Default path: native Synap extension (@synap) is the catalog. Persist
-    // workspace + provision a dedicated raycast agent key for extension writes.
-    // Full MCP (mcp-remote → mcp-config.json) is opt-in via cfg.withMcp.
     const { setActiveWorkspaceId, clearActiveWorkspaceId } = await import("./pod.js");
     if (cfg.workspaceId) {
         setActiveWorkspaceId(cfg.workspaceId);
@@ -1287,73 +1309,29 @@ async function installRaycast(cfg) {
     else {
         clearActiveWorkspaceId();
     }
-    const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "raycast");
+    // A key minted here lists the 9-tool starter set on /mcp and loads more on
+    // demand (`entry`); an existing live key is reused as it is.
+    const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "raycast", {
+        toolProfile: "entry",
+    });
     const { setSurfaceAgentKey } = await import("./pod.js");
     setSurfaceAgentKey("raycast", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
-    log.success("Raycast agent key stored for the Synap extension (@synap).");
-    log.dim("The native extension is your catalog — open Synap in Raycast (or run Connect there) if needed.");
-    log.blank();
+    const { writeMcpSnippetFiles } = await import("./mcp-snippets.js");
+    const files = writeMcpSnippetFiles(mcpUrl, effectiveApiKey, agentUserId);
+    log.success("Raycast agent key stored for the Synap extension's commands.");
     log.dim(`   Pod: ${cfg.podUrl}`);
     log.dim(`   Scope: ${cfg.workspaceId ? `workspace ${cfg.workspaceId}` : "all workspaces (pod-wide)"}`);
-    if (!cfg.withMcp) {
-        log.blank();
-        log.dim("Full MCP (mcp-remote) is opt-in: synap connect --target=raycast --with-mcp");
-        return true;
-    }
-    // ── Opt-in power door: write Raycast MCP server config (merge, never clobber) ─
-    // Raycast's native MCP is stdio-only — bridge the HTTP /mcp endpoint with the
-    // `mcp-remote` npm package (npx spawns it). Same bridge as Claude Desktop/Zed.
-    // Tool names will overlap the @synap extension catalog.
     log.blank();
-    const raycastServerName = mcpServerNameFromPodUrl(cfg.podUrl);
-    log.info(`Installing full MCP power door via mcp-remote as '${raycastServerName}' — names overlap @synap.`);
-    const synapServerEntry = {
-        command: "npx",
-        args: ["-y", "mcp-remote", mcpUrl, "--header", "Authorization:${SYNAP_AUTH}"],
-        // Header value via env, not argv (see Claude Desktop above).
-        env: { SYNAP_AUTH: `Bearer ${effectiveApiKey}` },
-    };
-    // The mcp-config.json lives in an opaque UUID folder Raycast creates the first
-    // time "Manage MCP Servers" is opened. If it already exists we merge into it;
-    // otherwise we can't know the folder, so we print the block to paste.
-    const existingPath = raycastMcpConfigPath();
-    let wrote = false;
-    if (existingPath) {
-        try {
-            let mcpConfig = {};
-            try {
-                mcpConfig = JSON.parse(fs.readFileSync(existingPath, "utf-8"));
-            }
-            catch {
-                try {
-                    copySecretBackup(existingPath, `${existingPath}.bak`);
-                }
-                catch { /* best-effort */ }
-            }
-            mcpConfig.mcpServers = mcpConfig.mcpServers ?? {};
-            mcpConfig.mcpServers[raycastServerName] = synapServerEntry;
-            if (raycastServerName !== "synap")
-                delete mcpConfig.mcpServers["synap"];
-            writeSecretFile(existingPath, JSON.stringify(mcpConfig, null, 2) + "\n", { mode: 0o600 });
-            wrote = true;
-            log.success(`Synap MCP server added to Raycast: ${existingPath}`);
-            log.dim(`Reopen Raycast → 'Manage MCP Servers' → '${raycastServerName}' is connected with all tools.`);
-            log.dim("First call spawns 'npx mcp-remote' (needs Node on PATH).");
-        }
-        catch (err) {
-            log.warn(`Could not write Raycast MCP config: ${err.message}`);
-        }
-    }
-    if (!wrote) {
-        log.info("To add Synap to Raycast as an MCP server:");
-        log.dim("  1. Open Raycast → run 'Manage MCP Servers'");
-        log.dim("  2. Action 'Show Config File in Finder' → open mcp-config.json");
-        log.dim(`  3. Paste the '${raycastServerName}' entry below into "mcpServers", then save:`);
-        log.blank();
-        log.dim(JSON.stringify({ mcpServers: { [raycastServerName]: synapServerEntry } }, null, 2));
-        log.blank();
-        log.dim("  (Re-running `synap connect --target=raycast --with-mcp` after step 2 writes it for you.)");
-    }
+    const serverName = mcpServerNameFromPodUrl(cfg.podUrl);
+    log.info("Add Synap to Raycast AI (one time, Raycast Pro):");
+    log.dim("  1. In Raycast, run “Install MCP Server”.");
+    log.dim(`  2. Name: ${serverName}   Transport: HTTP   URL: ${mcpUrl}`);
+    log.dim("  3. Authentication: OAuth → Dynamic → Sign In, then approve on your pod's consent page.");
+    log.dim("     Fallback, if Sign In fails: no OAuth; add the HTTP header");
+    log.dim(`     Authorization: Bearer ${redactKey(effectiveApiKey)}   (full value: ${files.jsonFile}, 0600)`);
+    log.dim("  4. Press “Install MCP Server” (⌘↵). In Raycast AI, mention the server and ask anything.");
+    log.blank();
+    log.dim("Raycast AI starts with the 9 essential Synap tools; it loads more when a task needs them.");
     return true;
 }
 // ─── Open WebUI ──────────────────────────────────────────────────────────────
@@ -1396,7 +1374,7 @@ async function installOpenWebUI(cfg) {
  *
  * OAuth: ChatGPT also supports OAuth (no header field). The pod's /mcp is
  * Bearer-only, so OAuth for a SINGLE pod isn't available — it lives on the
- * Control Plane (`https://api.synap.live/mcp`), which is an OAuth MCP server
+ * Control Plane (`https://mcp.synap.live`), which is an OAuth MCP server
  * exposing `list_pods` / `connect_pod` / 14 proxied `pod__*` tools. That path
  * is multi-pod and managed; `synap mcp connect-claude` prints it for
  * claude.ai, and the same URL works for ChatGPT's OAuth connector.
@@ -1425,7 +1403,7 @@ async function installChatGpt(cfg) {
             headers: { Authorization: `Bearer ${effectiveApiKey}` },
         },
         oauthAlternative: {
-            url: "https://api.synap.live/mcp",
+            url: MANAGED_MCP_URL,
             note: "ChatGPT OAuth connector (no header field). Multi-pod: list_pods, " +
                 "connect_pod, then proxied pod__* tools. Same URL as claude.ai.",
         },
@@ -1447,7 +1425,7 @@ async function installChatGpt(cfg) {
     log.info("Path 2 — OAuth (multi-pod, no key to paste):");
     log.blank();
     log.info("  ChatGPT → Settings → Connectors → Add custom connector");
-    log.info("  URL:     https://api.synap.live/mcp");
+    log.info(`  URL:     ${MANAGED_MCP_URL}`);
     log.info("  Auth:    OAuth (leave API key blank)");
     log.blank();
     log.dim("  After OAuth, ask ChatGPT to 'list my Synap pods' (list_pods) and connect " +
@@ -1575,19 +1553,10 @@ async function installZed(cfg) {
     if (!fs.existsSync(settingsDir))
         fs.mkdirSync(settingsDir, { recursive: true });
     const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "zed");
-    let settings = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            const raw = fs.readFileSync(settingsPath, "utf-8");
-            // Zed settings.json is JSONC — strip // line comments and /* block comments */
-            // before parsing. Comments will not be preserved in the rewritten file.
-            const stripped = raw
-                .replace(/\/\*[\s\S]*?\*\//g, "")
-                .replace(/\/\/[^\n]*/g, "");
-            settings = JSON.parse(stripped);
-        }
-        catch { /* malformed — start from scratch */ }
-    }
+    // Zed settings.json is JSONC. The strings-aware reader keeps the `//` of the
+    // URLs inside it (a regex strip ate them and the parse failure wiped the
+    // file); a file that still does not parse is refused, never replaced.
+    const settings = readClientConfig(settingsPath);
     const contextServers = (settings.context_servers ?? {});
     // Pod-derived name — a second pod must not overwrite the first.
     const zedServerName = mcpServerNameFromPodUrl(cfg.podUrl);
@@ -1597,17 +1566,17 @@ async function installZed(cfg) {
         source: "custom",
         command: {
             path: "npx",
-            args: ["-y", "mcp-remote@latest", mcpUrl, "--header", "Authorization:${SYNAP_AUTH}"],
+            args: mcpRemoteArgs(mcpUrl),
             env: { SYNAP_AUTH: `Bearer ${effectiveApiKey}` },
         },
         settings: {},
     };
     settings.context_servers = contextServers;
-    writeSecretFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    writeClientConfig(settingsPath, settings);
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("zed", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     log.success(`Zed settings updated: ${settingsPath}`);
-    log.dim("Note: Zed settings are JSONC — any existing // comments were removed during rewrite.");
+    log.dim(`Note: Zed settings are JSONC — comments are not kept in the rewrite. The previous file is at ${clientConfigBackupPath(settingsPath)}.`);
     log.dim("Reload Zed to pick up the new context server (mcp-remote bridge).");
     return true;
 }
@@ -1626,13 +1595,8 @@ async function installVSCode(cfg) {
         fs.mkdirSync(mcpDir, { recursive: true });
     const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "vscode");
     // VS Code 1.99+ global MCP format uses "servers" (not "mcpServers")
-    let existing = {};
-    if (fs.existsSync(mcpJsonPath)) {
-        try {
-            existing = JSON.parse(fs.readFileSync(mcpJsonPath, "utf-8"));
-        }
-        catch { /* ignore */ }
-    }
+    // VS Code's mcp.json is JSONC (comments, trailing commas). Unreadable → refused.
+    const existing = readClientConfig(mcpJsonPath);
     existing.servers = existing.servers ?? {};
     // Pod-derived name — a second pod must not overwrite the first.
     const vscodeServerName = mcpServerNameFromPodUrl(cfg.podUrl);
@@ -1643,7 +1607,7 @@ async function installVSCode(cfg) {
         url: mcpUrl,
         headers: { Authorization: `Bearer ${effectiveApiKey}` },
     };
-    writeSecretFile(mcpJsonPath, JSON.stringify(existing, null, 2) + "\n", { mode: 0o600 });
+    writeClientConfig(mcpJsonPath, existing);
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("vscode", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     log.success(`VS Code MCP config updated: ${mcpJsonPath}`);
@@ -1758,7 +1722,7 @@ async function installGeneric(cfg) {
     log.dim(`headers = { Authorization = "Bearer ${shown}" }`);
     log.blank();
     log.info("stdio bridge (mcp-remote) — key via env, not argv:");
-    log.dim(`  command: npx -y mcp-remote ${mcpUrl} --header "Authorization:\${SYNAP_AUTH}"`);
+    log.dim(`  command: npx -y ${MCP_REMOTE_PACKAGE} ${mcpUrl} --header "Authorization:\${SYNAP_AUTH}"`);
     log.dim(`  env:     SYNAP_AUTH="Bearer ${shown}"`);
     log.dim("  Real key: ~/.synap/mcp-config.json (0600).");
     log.blank();
@@ -1766,19 +1730,10 @@ async function installGeneric(cfg) {
     ensureSecretDir(synapDir);
     const configFile = path.join(synapDir, "mcp-config.json");
     // Merge with existing so dual-pod generic installs don't clobber each other
-    let existing = {};
-    if (fs.existsSync(configFile)) {
-        try {
-            existing = JSON.parse(fs.readFileSync(configFile, "utf-8"));
-        }
-        catch {
-            /* replace */
-        }
-    }
+    // Unreadable → refused: it may hold another pod's entry.
+    const existing = readClientConfig(configFile);
     const merged = { ...existing, ...httpConfig };
-    writeSecretFile(configFile, JSON.stringify(merged, null, 2) + "\n", {
-        mode: 0o600,
-    });
+    writeClientConfig(configFile, merged);
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("generic", {
         hubApiKey: effectiveApiKey,
@@ -1881,8 +1836,15 @@ async function pickProvider(podUrl, apiKey) {
     const spinner = ora("Fetching providers from pod vault...").start();
     let providers;
     try {
-        providers = await fetchCredentials(podUrl, apiKey);
+        const creds = await fetchCredentials(podUrl, apiKey);
         spinner.stop();
+        if (creds.masked) {
+            // A masked key written into a tool's config would fail on its first call.
+            log.warn("This pod gives provider keys only to its own services, not to an agent key.");
+            log.dim("Point the tool at the pod's OpenAI-compatible endpoint instead: synap providers pull --target show");
+            return null;
+        }
+        providers = creds.providers;
     }
     catch (err) {
         spinner.fail(`Could not fetch providers: ${err.message}`);
@@ -1932,16 +1894,8 @@ export async function installOpencode(cfg) {
     if (!fs.existsSync(configDir)) {
         fs.mkdirSync(configDir, { recursive: true });
     }
-    let existing = {};
-    if (fs.existsSync(configPath)) {
-        try {
-            existing = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-        }
-        catch {
-            copySecretBackup(configPath, `${configPath}.bak`);
-            log.warn("Existing opencode.json unreadable — backed up to opencode.json.bak");
-        }
-    }
+    // opencode.json is JSONC. Unreadable → refused, never replaced.
+    const existing = readClientConfig(configPath);
     const providerBlock = (existing.provider ?? {});
     providerBlock[provider.providerId] = {
         npm: "@ai-sdk/openai-compatible",
@@ -1967,7 +1921,7 @@ export async function installOpencode(cfg) {
         mcp: mcpBlock,
         ...(existing.model ? {} : { model: defaultModel }),
     };
-    writeSecretFile(configPath, JSON.stringify(updated, null, 2) + "\n", { mode: 0o600 });
+    writeClientConfig(configPath, updated);
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("opencode", { hubApiKey: agentKey, agentUserId, podUrl: cfg.podUrl });
     log.success(`opencode configured: ~/.config/opencode/opencode.json`);
@@ -2016,38 +1970,25 @@ export function writeMcpServerEntry(configPath, serverName, server) {
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    let config = {};
-    if (fs.existsSync(configPath)) {
-        try {
-            config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
-        }
-        catch {
-            // corrupt or unreadable — back up and start fresh
-            const backup = `${configPath}.bak-${Date.now()}`;
-            copySecretBackup(configPath, backup);
-            log.warn(`Existing config unreadable; backed up to ${path.basename(backup)}`);
-        }
-    }
+    // Unreadable → refused (it holds the person's other MCP servers), never
+    // "backed up and started fresh".
+    const config = readClientConfig(configPath);
     config.mcpServers = config.mcpServers ?? {};
     config.mcpServers[serverName] = server;
-    writeSecretFile(configPath, JSON.stringify(config, null, 2) + "\n", {
-        mode: 0o600,
-    });
+    writeClientConfig(configPath, config);
 }
 /** Best-effort remove of a named MCP server entry (e.g. legacy `"synap"`). */
 function removeMcpServerEntry(configPath, serverName) {
     if (!fs.existsSync(configPath))
         return;
     try {
-        const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        const config = readClientConfig(configPath);
         if (!config.mcpServers?.[serverName])
             return;
         delete config.mcpServers[serverName];
         if (Object.keys(config.mcpServers).length === 0)
             delete config.mcpServers;
-        writeSecretFile(configPath, JSON.stringify(config, null, 2) + "\n", {
-            mode: 0o600,
-        });
+        writeClientConfig(configPath, config);
     }
     catch {
         /* leave config alone if unreadable */