@synap-core/cli 1.7.0 → 1.10.0

package/dist/lib/targets.js

@@ -11,11 +11,13 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { exec, execFileSync } from "node:child_process";
 import chalk from "chalk";
 import ora from "ora";
 import prompts from "prompts";
 import { log } from "../utils/logger.js";
-import { installSkills, SKILL_NAMES } from "./skills-installer.js";
+import { installSkills, getDeliverableSkills } from "./skills-installer.js";
+import { resolveUserId, hubPatch, } from "./hub-client.js";
 const CLAUDE_DESKTOP_MACOS = path.join(os.homedir(), "Library", "Application Support", "Claude");
 const CLAUDE_DESKTOP_WINDOWS = path.join(process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"), "Claude");
 const CLAUDE_DESKTOP_LINUX = path.join(os.homedir(), ".config", "Claude");
@@ -29,6 +31,38 @@ 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",
@@ -58,8 +92,8 @@ export const TARGETS = {
     raycast: {
         name: "raycast",
         label: "Raycast",
-        description: "Native extension with 9 AI tools + commands (credentials auto-read from CLI config)",
-        supports: { skills: false, mcp: false },
+        description: "Native MCP server (via mcp-remote bridge) — all Synap tools in Raycast AI",
+        supports: { skills: false, mcp: true },
     },
     openclaw: {
         name: "openclaw",
@@ -80,6 +114,43 @@ export const TARGETS = {
         mcpConfigPath: () => path.join(os.homedir(), ".codex", "config.yaml"),
         skillsDir: () => path.join(os.homedir(), ".codex"),
     },
+    opencode: {
+        name: "opencode",
+        label: "opencode",
+        description: "Synap IS as AI provider + Synap pod as MCP tools in ~/.config/opencode/opencode.json",
+        supports: { skills: false, mcp: true },
+    },
+    aider: {
+        name: "aider",
+        label: "aider",
+        description: "Write Synap IS as the OpenAI-compatible provider in ~/.aider.conf.yml",
+        supports: { skills: false, mcp: false },
+    },
+    windsurf: {
+        name: "windsurf",
+        label: "Windsurf",
+        description: "Codeium Windsurf editor — MCP config at ~/.codeium/windsurf/mcp_config.json",
+        supports: { skills: false, mcp: true },
+        mcpConfigPath: () => path.join(os.homedir(), ".codeium", "windsurf", "mcp_config.json"),
+    },
+    goose: {
+        name: "goose",
+        label: "Goose",
+        description: "Block's AI agent — MCP extension in ~/.config/goose/config.yaml",
+        supports: { skills: false, mcp: true },
+    },
+    zed: {
+        name: "zed",
+        label: "Zed",
+        description: "Zed editor — context_servers entry in Zed settings.json (via mcp-remote)",
+        supports: { skills: false, mcp: true },
+    },
+    vscode: {
+        name: "vscode",
+        label: "VS Code (Kilo Code / Cline / Continue / Copilot)",
+        description: "VS Code native MCP — one config read by Kilo Code, Cline, Continue, and Copilot",
+        supports: { skills: false, mcp: true },
+    },
     generic: {
         name: "generic",
         label: "Generic MCP Client",
@@ -90,6 +161,103 @@ export const TARGETS = {
 export function isTargetName(value) {
     return value in TARGETS;
 }
+/**
+ * Build the pod's /mcp URL with optional scope lenses:
+ *   ?workspaceId= — workspace lens (an app-lens of a project)
+ *   ?projectId=   — project focus lens (orthogonal; narrows every tool call)
+ * Both are opt-in and compose. Omitting both = pod-wide.
+ */
+export function buildMcpUrl(podUrl, workspaceId, projectId) {
+    const podBase = podUrl.replace(/\/$/, "");
+    const params = new URLSearchParams();
+    if (workspaceId)
+        params.set("workspaceId", workspaceId);
+    if (projectId)
+        params.set("projectId", projectId);
+    const qs = params.toString();
+    return qs ? `${podBase}/mcp?${qs}` : `${podBase}/mcp`;
+}
+/**
+ * Shared preamble for MCP surface installers: provision a dedicated agent key,
+ * enroll the agent into the caller's workspaces, and resolve the scoped MCP URL.
+ */
+async function prepareMcpSurface(cfg, agentType) {
+    const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, agentType);
+    await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
+    return { effectiveApiKey, agentUserId, mcpUrl: buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId) };
+}
+// ─── Agent context configuration ──────────────────────────────────────────────
+export async function configureAgentContext(podUrl, apiKey, agentType, agentUserId, info) {
+    const { AGENT_TEMPLATES, getTemplate } = await import("./agent-templates.js");
+    log.blank();
+    log.heading("Configure your agent");
+    // Agent scope model (mirrors the user model): an agent is a POD-WIDE actor —
+    // it is NOT bound to a workspace. Its memory is automatic (the user/global/work
+    // lanes), so there's no "memory workspace" to pick. It was already enrolled
+    // across the pod's workspaces; focus is a runtime lens (a project), not a
+    // setup-time workspace choice. So the only thing to configure is the template.
+    log.dim("This agent is pod-wide. Its memory is automatic — nothing to scope here. Just pick a behaviour template.");
+    // No memory/product workspace prompts anymore — the agent is global by default.
+    const memoryWorkspace = undefined;
+    const productWorkspaces = [];
+    // ── Template ──────────────────────────────────────────────────────────────
+    log.blank();
+    log.info(chalk.bold("Agent template"));
+    log.dim("The template sets the agent's default behaviour and routing rules.");
+    log.blank();
+    // Non-interactive callers (bridge-setup, pods/init provisioning, `agents
+    // create`) still get a routing file — just with the MINIMAL default template,
+    // since there's no TTY to prompt on.
+    let templateId;
+    if (process.stdin.isTTY) {
+        ({ templateId } = await prompts({
+            type: "select",
+            name: "templateId",
+            message: "Pick a template:",
+            choices: AGENT_TEMPLATES.map((t) => ({
+                title: `${t.label}  ${chalk.dim(t.description)}`,
+                value: t.id,
+            })),
+        }));
+    }
+    const template = getTemplate(templateId);
+    // ── Generate and write CONTEXT.md ─────────────────────────────────────────
+    const content = template.generateContext({
+        agentType,
+        podUrl,
+        memoryWorkspace,
+        productWorkspaces,
+    });
+    // Clear any stale per-agent workspace routing from older connects. The agent
+    // is pod-wide now: capture/recall default to the active workspace / pod-wide,
+    // not a pre-pinned "memory" or "product" workspace.
+    const { setAgentWorkspaceRouting } = await import("./pod.js");
+    setAgentWorkspaceRouting({ memoryWorkspaceId: undefined, productWorkspaceIds: [] });
+    // Always write to ~/.synap/contexts/<surface>.md
+    const contextDir = path.join(os.homedir(), ".synap", "contexts");
+    if (!fs.existsSync(contextDir))
+        fs.mkdirSync(contextDir, { recursive: true });
+    const globalContextPath = path.join(contextDir, `${agentType}.md`);
+    fs.writeFileSync(globalContextPath, content, { mode: 0o600 });
+    // For skills-capable surfaces, also write alongside SKILL.md
+    const skillsDir = info?.skillsDir?.();
+    if (skillsDir) {
+        const synapSkillDir = path.join(skillsDir, "synap");
+        if (!fs.existsSync(synapSkillDir))
+            fs.mkdirSync(synapSkillDir, { recursive: true });
+        fs.writeFileSync(path.join(synapSkillDir, "CONTEXT.md"), content, { mode: 0o600 });
+        log.success(`Agent context written to ${synapSkillDir}/CONTEXT.md`);
+    }
+    else {
+        log.success(`Agent context written to ${globalContextPath}`);
+        log.dim("For MCP-only surfaces the context is available as a reference; load it manually if needed.");
+    }
+    // Summary
+    log.blank();
+    log.info(`  Template     ${chalk.bold(template.label)}`);
+    log.info(`  Scope        ${chalk.bold("pod-wide")} ${chalk.dim("· memory is automatic · focus a project at runtime")}`);
+    log.blank();
+}
 export function listTargets() {
     log.heading("Supported targets");
     for (const t of Object.values(TARGETS)) {
@@ -112,50 +280,90 @@ export async function installForTarget(target, cfg) {
         return false;
     }
     log.heading(`Installing for ${info.label}`);
+    let result;
     switch (target) {
         case "claude-code":
-            return installClaudeCode(info, cfg);
+            result = await installClaudeCode(info, cfg);
+            break;
         case "claude-desktop":
-            return installClaudeDesktop(info, cfg);
+            result = await installClaudeDesktop(info, cfg);
+            break;
         case "cursor":
-            return installCursor(info, cfg);
+            result = await installCursor(info, cfg);
+            break;
         case "raycast":
-            return installRaycast(cfg);
+            result = await installRaycast(cfg);
+            break;
         case "openclaw":
-            return installOpenclaw(cfg);
+            result = await installOpenclaw(cfg);
+            break;
         case "openwebui":
-            return installOpenWebUI(cfg);
+            result = await installOpenWebUI(cfg);
+            break;
         case "codex":
-            return installCodex(info, cfg);
+            result = await installCodex(info, cfg);
+            break;
+        case "opencode":
+            result = await installOpencode(cfg);
+            break;
+        case "aider":
+            result = await installAider(cfg);
+            break;
+        case "windsurf":
+            result = await installWindsurf(info, cfg);
+            break;
+        case "goose":
+            result = await installGoose(cfg);
+            break;
+        case "zed":
+            result = await installZed(cfg);
+            break;
+        case "vscode":
+            result = await installVSCode(cfg);
+            break;
         case "generic":
-            return installGeneric(cfg);
+            result = await installGeneric(cfg);
+            break;
     }
+    // Post-install: configure agent workspace context for all successful MCP installs.
+    if (result && info.supports.mcp && target !== "generic") {
+        const { getSurfaceAgentKey } = await import("./pod.js");
+        const saved = getSurfaceAgentKey(target);
+        const agentUserId = saved?.agentUserId ?? "";
+        try {
+            await configureAgentContext(cfg.podUrl, cfg.apiKey, target, agentUserId, info);
+        }
+        catch (err) {
+            log.warn(`Agent context wizard failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return result;
 }
 // ─── Claude Code ─────────────────────────────────────────────────────────────
 async function installClaudeCode(info, cfg) {
     // ── What to install? ────────────────────────────────────────────────────
-    // Skills = CLAUDE.md context files (instructions, schema, UI patterns)
-    // MCP    = live tool server (read/write entities, search, memory, etc.)
-    // Both is the recommended default — skills give the model Synap knowledge,
-    // MCP gives it the actual tools to act on data.
+    // Claude Code is a CLI-first agent: it reads/writes Synap via `synap` shell
+    // commands (capture, recall, search, create, etc.) — not via MCP tool calls.
+    // Skills give it Synap knowledge; the agent key lets it call the CLI directly.
+    // MCP is available as an opt-in for users who prefer the tool-call interface.
     const { mode } = await prompts({
         type: "select",
         name: "mode",
         message: "What do you want to install?",
         choices: [
             {
-                title: "Both — Skills + MCP tools  (recommended)",
-                description: "Skills give Claude context about Synap; MCP tools let it read & write data",
+                title: "MCP + Skills + agent key  (recommended)",
+                description: "MCP tools are always present (ambient) so the AI knows Synap on every session; skills + CLI add the rich power-user path",
                 value: "both",
             },
             {
-                title: "MCP tools only",
-                description: "Live tool server — search, create, update entities, memory, channels",
+                title: "MCP server only",
+                description: "Ambient tool-call interface only — skip skills and CLI setup. Best for non-terminal clients",
                 value: "mcp",
             },
             {
-                title: "Skills only",
-                description: "Context files (CLAUDE.md) — no live data access",
+                title: "Skills + agent key (no MCP)",
+                description: "CLI-driven only — Synap is known only when the skill is loaded. Lighter, but not ambient",
                 value: "skills",
             },
         ],
@@ -169,32 +377,28 @@ async function installClaudeCode(info, cfg) {
         if (dir) {
             const installed = await installSkills({
                 destDir: dir,
-                skills: cfg.skills ?? SKILL_NAMES,
+                skills: cfg.skills ?? getDeliverableSkills(),
             });
             if (installed) {
                 log.success(`Skills installed to ~/.claude/skills/`);
             }
         }
     }
-    // ── MCP ─────────────────────────────────────────────────────────────────
+    // ── Agent key + optional MCP ─────────────────────────────────────────────
+    // writeClaudeCodeEnv always provisions the agent key and writes env vars.
+    // writeMcp=true additionally registers the mcpServers entry.
     if (mode === "both" || mode === "mcp") {
         await writeClaudeCodeEnv(cfg);
-        log.success("MCP server 'synap' added to ~/.claude/settings.json");
-        if (cfg.workspaceId) {
-            log.dim(`Scoped to workspace: ${cfg.workspaceId}`);
-        }
-        else {
-            log.dim("Not scoped — all workspaces accessible.");
-        }
+        log.success("Agent key provisioned and MCP server registered in ~/.claude/settings.json");
     }
     else {
-        // Skills-only: still write env vars (pod URL useful for skills referencing
-        // SYNAP_POD_URL) but don't add the mcpServers entry
-        await writeClaudeCodeEnv({ ...cfg, workspaceId: cfg.workspaceId }, { writeMcp: false });
+        await writeClaudeCodeEnv(cfg, { writeMcp: false });
+        log.success("Agent key provisioned and pod env vars written to ~/.claude/settings.json");
+        log.dim("Claude Code will use `synap` CLI commands to read/write the pod.");
     }
     log.blank();
-    log.success("Claude Code config updated.");
-    log.dim("Restart Claude Code (or open a new window) to pick up the MCP server and env vars.");
+    log.success("Claude Code configured.");
+    log.dim("Open a new Claude Code window to pick up the updated env vars.");
     return true;
 }
 /**
@@ -275,9 +479,11 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
     // Both steps are required — fail loudly if either is unreachable.
     const meRes = await fetch(`${podBase}/api/hub/users/me`, {
         headers: { Authorization: `Bearer ${cfg.apiKey}` },
-        signal: AbortSignal.timeout(5000),
+        signal: AbortSignal.timeout(30000),
     });
     if (!meRes.ok) {
+        if (meRes.status === 401)
+            throw new Error(credentialError("claude-code", 401, await meRes.text().catch(() => "")));
         throw new Error(`Could not reach pod at ${cfg.podUrl} (HTTP ${meRes.status}). Check your pod URL and API key.`);
     }
     const me = await meRes.json();
@@ -286,20 +492,82 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
     const agentSetupRes = await fetch(`${podBase}/api/hub/setup/agent`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${cfg.apiKey}` },
-        body: JSON.stringify({ agentType: "claude-code", idempotent: false }),
-        signal: AbortSignal.timeout(10000),
+        body: JSON.stringify({ agentType: "claude-code", idempotent: true }),
+        signal: AbortSignal.timeout(30000),
     });
     if (!agentSetupRes.ok) {
         const text = await agentSetupRes.text().catch(() => agentSetupRes.statusText);
-        throw new Error(`Failed to provision agent key for claude-code (HTTP ${agentSetupRes.status}): ${text}\nEnsure your API key has hub-protocol.write scope.`);
+        throw new Error(credentialError("claude-code", agentSetupRes.status, text));
     }
     const agentSetup = await agentSetupRes.json();
-    if (!agentSetup.hubApiKey)
-        throw new Error("setup/agent succeeded but returned no hubApiKey — check pod logs.");
-    effectiveApiKey = agentSetup.hubApiKey;
+    if (agentSetup.alreadyValid) {
+        // Idempotent path — pod says the agent key is still valid but doesn't re-transmit it.
+        // Resolution priority: stored agentKey config > settings.json env var.
+        // Self-heal: verify the candidate resolves to the expected agent user, not the human user.
+        const { getSurfaceAgentKey: readSurfaceKey } = await import("./pod.js");
+        const storedKey = readSurfaceKey("claude-code");
+        const candidate = storedKey?.hubApiKey ??
+            settings.env?.["SYNAP_HUB_API_KEY"] ??
+            null;
+        const expectedAgentUserId = agentSetup.agentUserId ?? storedKey?.agentUserId;
+        let candidateIsValid = false;
+        if (candidate && expectedAgentUserId) {
+            try {
+                // Use auth/status — it returns the key's actual owner userId.
+                // For agent keys this is the agent userId, not the human userId.
+                // users/me always returns the human owner regardless of key type.
+                const verifyRes = await fetch(`${podBase}/api/hub/auth/status`, {
+                    headers: { Authorization: `Bearer ${candidate}` },
+                    signal: AbortSignal.timeout(30000),
+                });
+                if (verifyRes.ok) {
+                    const verifyStatus = await verifyRes.json();
+                    candidateIsValid = verifyStatus.userId === expectedAgentUserId;
+                }
+            }
+            catch { /* reprovision below */ }
+        }
+        if (candidateIsValid && candidate) {
+            effectiveApiKey = candidate;
+        }
+        else {
+            // Self-heal: stored key is stale, wrong identity, or never persisted.
+            // Reprovision without idempotent flag to get a fresh agent key.
+            const reproRes = await fetch(`${podBase}/api/hub/setup/agent`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: `Bearer ${cfg.apiKey}` },
+                body: JSON.stringify({ agentType: "claude-code" }),
+                signal: AbortSignal.timeout(30000),
+            });
+            if (reproRes.ok) {
+                const repro = await reproRes.json();
+                effectiveApiKey = repro.hubApiKey ?? candidate ?? cfg.apiKey;
+                if (repro.agentUserId)
+                    agentSetup.agentUserId = repro.agentUserId;
+            }
+            else {
+                // Reprovision failed — fall back to whatever we have, warn clearly
+                effectiveApiKey = candidate ?? cfg.apiKey;
+                log.warn("Could not reprovision agent key — using fallback. Run `synap connect --target=claude-code` to fix.");
+            }
+        }
+    }
+    else {
+        if (!agentSetup.hubApiKey)
+            throw new Error("setup/agent succeeded but returned no hubApiKey — check pod logs.");
+        effectiveApiKey = agentSetup.hubApiKey;
+    }
+    // Persist the provisioned key to agentKeys["claude-code"] so SYNAP_AGENT=claude-code
+    // works in CLI sessions outside of this env (e.g. terminal, not just inside Claude Code).
+    const { setSurfaceAgentKey: saveSurfaceKey } = await import("./pod.js");
+    saveSurfaceKey("claude-code", { hubApiKey: effectiveApiKey, agentUserId: agentSetup.agentUserId ?? "", podUrl: cfg.podUrl });
     // Enroll the new agent user into the caller's workspaces using the HUMAN key
     // (before switching to the agent key). Scoped to one workspace when chosen.
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentSetup.agentUserId ?? "", cfg.workspaceId);
+    // Set per-agent governance — prompt once per agent, idempotent.
+    if (agentSetup.agentUserId) {
+        await ensureAgentGovernance(cfg, agentSetup.agentUserId);
+    }
     const env = (settings.env ?? {});
     env["SYNAP_POD_URL"] = cfg.podUrl;
     env["SYNAP_HUB_API_KEY"] = effectiveApiKey;
@@ -309,34 +577,111 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
         env["SYNAP_WORKSPACE_ID"] = cfg.workspaceId;
     else
         delete env["SYNAP_WORKSPACE_ID"];
+    if (cfg.projectId)
+        env["SYNAP_PROJECT_ID"] = cfg.projectId;
+    else
+        delete env["SYNAP_PROJECT_ID"];
     if (me.scopes?.length)
         env["SYNAP_KEY_SCOPES"] = me.scopes.join(",");
     settings.env = env;
-    // ── MCP server entry (HTTP transport, native Claude Code format) ─────────
-    if (writeMcp) {
-        // Append ?workspaceId= when one is set so every tool call is pre-scoped.
-        const mcpUrl = cfg.workspaceId
-            ? `${podBase}/mcp?workspaceId=${encodeURIComponent(cfg.workspaceId)}`
-            : `${podBase}/mcp`;
-        const mcpServers = (settings.mcpServers ?? {});
-        mcpServers["synap"] = {
-            url: mcpUrl,
-            headers: { Authorization: `Bearer ${effectiveApiKey}` },
-        };
-        settings.mcpServers = mcpServers;
+    // ── Clean up the dead settings.json mcpServers entry ─────────────────────
+    // Claude Code does NOT load MCP servers from ~/.claude/settings.json — they
+    // live in the `claude mcp` registry (~/.claude.json, user scope). A `synap`
+    // entry written here by older CLI versions is inert (confirmed: `claude mcp
+    // list` never showed it). Strip it so the only source of truth is the registry.
+    if (settings.mcpServers && typeof settings.mcpServers === "object") {
+        delete settings.mcpServers["synap"];
+        if (Object.keys(settings.mcpServers).length === 0)
+            delete settings.mcpServers;
     }
     if (!fs.existsSync(settingsDir)) {
         fs.mkdirSync(settingsDir, { recursive: true });
     }
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    // ── 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,
+    // which Claude Code ignores. This is what makes a relaunch actually load the
+    // synap tools.
+    if (writeMcp) {
+        const mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
+        registerClaudeCodeMcp(mcpUrl, effectiveApiKey);
+    }
+}
+/**
+ * Register the Synap MCP server with Claude Code via the official CLI, into the
+ * user-scope registry (`claude mcp list` truth). Idempotent: drops any prior
+ * entry first. Best-effort: if the `claude` binary isn't on PATH, prints the
+ * exact command to run by hand rather than failing the whole connect.
+ */
+function registerClaudeCodeMcp(mcpUrl, apiKey) {
+    const header = `Authorization: Bearer ${apiKey}`;
+    try {
+        try {
+            execFileSync("claude", ["mcp", "remove", "synap"], { stdio: "ignore" });
+        }
+        catch {
+            /* no prior entry — fine */
+        }
+        execFileSync("claude", ["mcp", "add", "--transport", "http", "synap", mcpUrl, "--header", header, "--scope", "user"], { stdio: "ignore" });
+        log.success("MCP server registered with Claude Code (`claude mcp add`, user scope). Relaunch Claude Code to load the synap tools.");
+    }
+    catch {
+        log.dim("Could not run `claude mcp add` (is the claude CLI on PATH?). Register it by hand:");
+        log.dim(`  claude mcp add --transport http synap ${mcpUrl} --header "${header}" --scope user`);
+    }
 }
 // ─── Agent key provisioning helper ──────────────────────────────────────────
+/**
+ * Build an actionable error for a failed agent-key provision. A 401 here almost
+ * always means the pod key saved by `synap login` is expired or REVOKED (the
+ * `/setup/agent` endpoint accepts a CP JWT, a provisioning token, or a Hub key
+ * with the `setup.agent` scope) — so the fix is to re-authenticate, NOT to fiddle
+ * with scopes. Don't mislead with "needs hub-protocol.write".
+ */
+function credentialError(agentType, status, body) {
+    if (status === 401) {
+        return (`Can't provision the agent key for ${agentType} (HTTP 401): your saved pod key is invalid, expired, or revoked.\n` +
+            `Fix: run \`synap login --reconnect\` to re-authenticate this pod and mint a fresh key, then retry.\n` +
+            `(Plain \`synap login\` only health-checks — it won't refresh a revoked key.)\n` +
+            (body ? `Server said: ${body}` : ""));
+    }
+    return (`Failed to provision agent key for ${agentType} (HTTP ${status}): ${body}\n` +
+        `If this persists, re-authenticate with \`synap login --reconnect\`.`);
+}
+function openBrowserUrl(url) {
+    const safe = url.replace(/"/g, "%22");
+    const cmd = process.platform === "darwin" ? `open "${safe}"` :
+        process.platform === "win32" ? `start "" "${safe}"` :
+            `xdg-open "${safe}"`;
+    exec(cmd, () => { });
+}
+async function waitForKeyApproval(podBase, humanApiKey, pendingToken, agentType) {
+    // Shared poll loop (also backs CP `synap login`) — see lib/approval-poll.ts.
+    const { pollForApproval } = await import("./approval-poll.js");
+    await pollForApproval({
+        url: `${podBase}/api/hub/setup/agent/pending/${pendingToken}`,
+        headers: { Authorization: `Bearer ${humanApiKey}` },
+        isApproved: (d) => d.status === "active",
+        isRejected: (d) => d.status === "rejected",
+        onApproved: () => undefined,
+        rejectedError: `Agent key for ${agentType} was rejected in the browser. Run connect again to re-request.`,
+        timeoutError: `Timed out waiting for approval of ${agentType} agent key (120s). ` +
+            `Open the review URL manually or run connect again.`,
+    });
+}
 /**
  * Provision an agent-owned API key for the given surface via POST /api/hub/setup/agent.
- * Returns both the key and the new agent's userId so callers can enroll it in workspaces.
+ * When requireApproval is true the key is created inactive; the user must approve in the
+ * browser before this function returns.
  * Throws on failure — callers must not silently fall back to a human key.
  */
-async function provisionAgentKey(podUrl, humanApiKey, agentType) {
+export async function provisionAgentKey(podUrl, humanApiKey, agentType, { requireApproval = true, idempotent = false, } = {}) {
+    // `idempotent: true` reuses the pod's existing valid key for this agentType
+    // instead of minting a fresh one + revoking the old — required by callers whose
+    // running process holds a long-lived key (e.g. `bridge-setup`), so re-running
+    // setup doesn't break a live bridge. Default false preserves the mint-fresh
+    // behavior every other caller (connect / pods / init) already relied on.
     const podBase = podUrl.replace(/\/$/, "");
     let res;
     try {
@@ -346,8 +691,8 @@ async function provisionAgentKey(podUrl, humanApiKey, agentType) {
                 "Content-Type": "application/json",
                 Authorization: `Bearer ${humanApiKey}`,
             },
-            body: JSON.stringify({ agentType, idempotent: false }),
-            signal: AbortSignal.timeout(10000),
+            body: JSON.stringify({ agentType, idempotent, requireApproval }),
+            signal: AbortSignal.timeout(30000),
         });
     }
     catch (err) {
@@ -356,15 +701,84 @@ async function provisionAgentKey(podUrl, humanApiKey, agentType) {
     }
     if (!res.ok) {
         const text = await res.text().catch(() => res.statusText);
-        throw new Error(`Failed to provision agent key for ${agentType} (HTTP ${res.status}): ${text}\n` +
-            `Ensure your API key has hub-protocol.write scope.`);
+        throw new Error(credentialError(agentType, res.status, text));
     }
     const body = await res.json();
+    // Idempotent-reuse response: the pod already has a valid key for this agentType
+    // and returns { alreadyValid: true } WITHOUT a hubApiKey — the plaintext exists
+    // only at mint time and is never recoverable from the stored hash.
+    //
+    // The whole POINT of idempotent reuse is to NOT rotate: a live service (e.g. the
+    // Discord bridge) holds the plaintext in its .env and would 401 on every request
+    // until redeployed if we minted a fresh key + revoked the old one. So on reuse we
+    // recover the plaintext from LOCAL storage (where the last successful provision
+    // saved it), verify it still resolves to this agent, and hand it back untouched —
+    // no rotation, no redeploy. We mint fresh ONLY when no valid local key exists
+    // (e.g. a brand-new machine). This generalizes the claude-code self-heal.
+    if (!body.hubApiKey && body.alreadyValid && idempotent) {
+        const { getSurfaceAgentKey } = await import("./pod.js");
+        const stored = getSurfaceAgentKey(agentType);
+        const candidate = stored?.hubApiKey;
+        const expectedAgentUserId = body.agentUserId ?? stored?.agentUserId;
+        if (candidate && expectedAgentUserId) {
+            // auth/status returns the KEY's owner userId (the agent's, for agent keys).
+            const verify = await fetch(`${podBase}/api/hub/auth/status`, {
+                headers: { Authorization: `Bearer ${candidate}` },
+                signal: AbortSignal.timeout(30000),
+            }).catch(() => null);
+            // Rotate ONLY on POSITIVE invalidation. A transient failure (network blip,
+            // timeout, 5xx) must NOT trigger a rotate — that would revoke the live
+            // service's working key and 401 it until redeploy, the exact harm this
+            // reuse path exists to avoid. So:
+            //   • ok + userId matches   → reuse (definitely valid)
+            //   • 401/403               → key is dead → rotate
+            //   • ok + userId MISMATCH  → wrong identity → rotate
+            //   • unreachable / 5xx / ambiguous → reuse as-is (a blip ≠ a dead key)
+            if (verify?.ok) {
+                const st = (await verify.json().catch(() => ({})));
+                if (st.userId === expectedAgentUserId) {
+                    return { hubApiKey: candidate, agentUserId: expectedAgentUserId, reused: true };
+                }
+                // userId mismatch → fall through to rotate (positive invalidation).
+            }
+            else if (verify && (verify.status === 401 || verify.status === 403)) {
+                // Pod actively rejected the key → dead → fall through to rotate.
+            }
+            else {
+                // Unreachable or ambiguous (5xx/timeout) — do not revoke a probably-live
+                // key on a transient pod hiccup. Reuse; the operator will notice a real
+                // 401 later and can force a fresh provision.
+                return { hubApiKey: candidate, agentUserId: expectedAgentUserId, reused: true };
+            }
+        }
+        // No candidate, OR positive invalidation above — rotate (mint fresh, revoke
+        // old). The caller MUST persist + redeploy the new key. idempotent:false can't
+        // re-enter this branch (the server gates alreadyValid on idempotent===true).
+        return provisionAgentKey(podUrl, humanApiKey, agentType, {
+            requireApproval,
+            idempotent: false,
+        });
+    }
     if (!body.hubApiKey) {
         throw new Error(`setup/agent succeeded but returned no hubApiKey for ${agentType}. ` +
             `This is a server-side bug — check the pod logs.`);
     }
-    return { hubApiKey: body.hubApiKey, agentUserId: body.agentUserId ?? "" };
+    if (body.requiresApproval && body.pendingToken && body.reviewUrl) {
+        log.info(`\n  Opening your pod to review this agent key request…`);
+        log.dim(`  ${body.reviewUrl}`);
+        openBrowserUrl(body.reviewUrl);
+        process.stdout.write(chalk.dim("  Waiting for approval"));
+        const ticker = setInterval(() => process.stdout.write(chalk.dim(".")), 2000);
+        try {
+            await waitForKeyApproval(podBase, humanApiKey, body.pendingToken, agentType);
+        }
+        finally {
+            clearInterval(ticker);
+            process.stdout.write("\n");
+        }
+        log.success(`  Approved! Writing ${agentType} agent key.`);
+    }
+    return { hubApiKey: body.hubApiKey, agentUserId: body.agentUserId ?? "", reused: false };
 }
 /**
  * Enroll an agent user into the caller's workspaces via POST /api/hub/workspaces/enroll-agent.
@@ -373,10 +787,14 @@ async function provisionAgentKey(podUrl, humanApiKey, agentType) {
  * @param callerKey  The key of the user whose workspaces to enroll into (pod profile key).
  * @param agentUserId  The agent user to enroll.
  * @param workspaceId  When set, enroll in that one workspace only; omit for all.
+ * @param opts.role  Workspace role to grant the agent. Defaults to "editor" — the
+ *   one safe default callers get unless they explicitly ask for another role.
  */
-async function enrollAgentIfNeeded(podUrl, callerKey, agentUserId, workspaceId) {
+export async function enrollAgentIfNeeded(podUrl, callerKey, agentUserId, workspaceId, opts) {
     if (!agentUserId)
         return;
+    const quiet = opts?.quiet === true; // suppress status logs (e.g. --json callers)
+    const role = opts?.role ?? "editor";
     const podBase = podUrl.replace(/\/$/, "");
     try {
         const res = await fetch(`${podBase}/api/hub/workspaces/enroll-agent`, {
@@ -385,25 +803,27 @@ async function enrollAgentIfNeeded(podUrl, callerKey, agentUserId, workspaceId)
             body: JSON.stringify({
                 agentUserId,
                 ...(workspaceId ? { workspaceId } : {}),
-                role: "editor",
+                role,
             }),
-            signal: AbortSignal.timeout(10000),
+            signal: AbortSignal.timeout(30000),
         });
         if (res.ok) {
             const data = await res.json();
-            if (data.enrolled?.length) {
+            if (data.enrolled?.length && !quiet) {
                 log.dim(`  Agent enrolled in ${data.enrolled.length} workspace(s).`);
             }
         }
-        else {
+        else if (!quiet) {
             const text = await res.text().catch(() => res.statusText);
             log.warn(`  Workspace enrollment failed (HTTP ${res.status}): ${text}`);
             log.dim("  Access can be added manually via pod settings.");
         }
     }
     catch (err) {
-        log.warn(`  Workspace enrollment unreachable: ${err.message}`);
-        log.dim("  Access can be added manually via pod settings.");
+        if (!quiet) {
+            log.warn(`  Workspace enrollment unreachable: ${err.message}`);
+            log.dim("  Access can be added manually via pod settings.");
+        }
     }
 }
 // ─── Claude Desktop ──────────────────────────────────────────────────────────
@@ -418,10 +838,10 @@ async function installClaudeDesktop(info, cfg) {
     //
     // Reference: https://www.npmjs.com/package/mcp-remote
     const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, "claude-desktop");
+    const { setSurfaceAgentKey: saveDesktopKey } = await import("./pod.js");
+    saveDesktopKey("claude-desktop", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
-    const desktopMcpUrl = cfg.workspaceId
-        ? `${cfg.podUrl.replace(/\/$/, "")}/mcp?workspaceId=${encodeURIComponent(cfg.workspaceId)}`
-        : `${cfg.podUrl.replace(/\/$/, "")}/mcp`;
+    const desktopMcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
     writeMcpServerEntry(mcpPath, "synap", {
         command: "npx",
         args: ["-y", "mcp-remote", desktopMcpUrl, "--header", `Authorization: Bearer ${effectiveApiKey}`],
@@ -436,10 +856,10 @@ async function installClaudeDesktop(info, cfg) {
     if (skillsDir) {
         const installed = await installSkills({
             destDir: skillsDir,
-            skills: cfg.skills ?? SKILL_NAMES,
+            skills: cfg.skills ?? getDeliverableSkills(),
         });
         if (installed) {
-            log.success(`Synap skills installed to ${path.relative(os.homedir(), skillsDir)}/ (${(cfg.skills ?? SKILL_NAMES).join(", ")})`);
+            log.success(`Synap skills installed to ${path.relative(os.homedir(), skillsDir)}/ (${(cfg.skills ?? getDeliverableSkills()).join(", ")})`);
         }
         else {
             log.warn("Skill install reported no files written — verify ~/Library/Application Support/Claude/skills/ exists after relaunch.");
@@ -461,10 +881,10 @@ async function installCursor(info, cfg) {
     if (!mcpPath)
         return false;
     const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, "cursor");
+    const { setSurfaceAgentKey: saveCursorKey } = await import("./pod.js");
+    saveCursorKey("cursor", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
-    const cursorMcpUrl = cfg.workspaceId
-        ? `${cfg.podUrl.replace(/\/$/, "")}/mcp?workspaceId=${encodeURIComponent(cfg.workspaceId)}`
-        : `${cfg.podUrl.replace(/\/$/, "")}/mcp`;
+    const cursorMcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
     writeMcpServerEntry(mcpPath, "synap", {
         url: cursorMcpUrl,
         headers: { Authorization: `Bearer ${effectiveApiKey}` },
@@ -481,58 +901,75 @@ async function installCursor(info, cfg) {
 }
 // ─── Raycast ─────────────────────────────────────────────────────────────────
 async function installRaycast(cfg) {
-    // Raycast reads credentials from ~/.synap/config.json (Tier 0 — highest priority).
-    // Persist the workspace choice so Raycast immediately sees the right scope.
-    const { setActiveWorkspaceId, clearActiveWorkspaceId, setSurfaceAgentKey } = await import("./pod.js");
+    // Raycast reads credentials from ~/.synap/config.json (Tier 0) for its native
+    // extension commands, AND from mcp-config.json for the MCP server. Persist the
+    // workspace choice so both paths see the right scope.
+    const { setActiveWorkspaceId, clearActiveWorkspaceId } = await import("./pod.js");
     if (cfg.workspaceId) {
         setActiveWorkspaceId(cfg.workspaceId);
     }
     else {
         clearActiveWorkspaceId();
     }
-    // Provision a dedicated named agent key for Raycast so its AI tools run as
-    // "raycast" agent identity (separate from the human user key used by UI commands).
-    const provisionSpinner = ora("Provisioning Raycast agent identity...").start();
-    try {
-        const agentKey = await provisionAgentKey(cfg.podUrl, cfg.apiKey, "raycast");
-        setSurfaceAgentKey("raycast", agentKey);
-        provisionSpinner.text = "Enrolling agent in workspaces...";
-        await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentKey.agentUserId, cfg.workspaceId);
-        provisionSpinner.succeed("Raycast agent identity provisioned.");
+    // Provision a dedicated "raycast" agent identity + resolve the scoped MCP URL.
+    const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "raycast");
+    const { setSurfaceAgentKey } = await import("./pod.js");
+    setSurfaceAgentKey("raycast", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
+    // ── Write the 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.
+    const synapServerEntry = {
+        command: "npx",
+        args: [
+            "-y",
+            "mcp-remote",
+            mcpUrl,
+            "--header",
+            `Authorization: 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 {
+                    fs.copyFileSync(existingPath, `${existingPath}.bak`);
+                }
+                catch { /* best-effort */ }
+            }
+            mcpConfig.mcpServers = mcpConfig.mcpServers ?? {};
+            mcpConfig.mcpServers["synap"] = synapServerEntry;
+            fs.writeFileSync(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' → 'synap' 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}`);
+        }
     }
-    catch (err) {
-        // Non-fatal: Raycast still works with the human key, agent provisioning is best-effort.
-        provisionSpinner.warn(`Could not provision dedicated Raycast agent key: ${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 'synap' entry below into \"mcpServers\", then save:");
+        log.blank();
+        log.dim(JSON.stringify({ mcpServers: { synap: synapServerEntry } }, null, 2));
+        log.blank();
+        log.dim("  (Re-running `synap connect --target=raycast` after step 2 writes it for you.)");
     }
-    log.success("Credentials and workspace written to ~/.synap/config.json — Raycast picks them up automatically.");
-    log.blank();
-    log.info("1. Install the Synap extension from the Raycast Store:");
-    log.dim("   Open Raycast → search 'Raycast Store' → search 'Synap' → Install");
-    log.blank();
-    log.info("2. Commands available immediately after install:");
-    log.dim("   Search Synap          — search your knowledge graph");
-    log.dim("   Quick Capture         — capture selected text or clipboard as an entity");
-    log.dim("   Capture Browser Tab   — save current browser tab");
-    log.dim("   Create Task           — create a task directly");
-    log.dim("   Synap Status          — menu bar: pending tasks + proposals");
-    log.blank();
-    log.info("3. Raycast AI has 9 native Synap tools (no MCP, no extra setup):");
-    log.dim("   search-entities · get-tasks · create-entity · update-entity · get-entity");
-    log.dim("   store-memory · recall-memory · send-to-channel · get-recent");
-    log.blank();
-    log.info("4. Behavioral guidance is built into the extension.");
-    log.dim("   Raycast AI knows how to use Synap — search before answering,");
-    log.dim("   save proactively, link entities, persist facts to memory.");
-    log.dim("   No system prompt to paste.");
     log.blank();
     log.dim(`   Pod: ${cfg.podUrl}`);
-    if (cfg.workspaceId) {
-        log.dim(`   Workspace: ${cfg.workspaceId}`);
-    }
-    else {
-        log.dim("   Workspace: all workspaces");
-    }
-    log.dim("   To switch later: synap use <workspace-id>  or  synap pods use <profile>");
+    log.dim(`   Scope: ${cfg.workspaceId ? `workspace ${cfg.workspaceId}` : "all workspaces (pod-wide)"}`);
     return true;
 }
 // ─── OpenClaw (wraps existing flow with saved pod config) ───────────────────
@@ -559,17 +996,14 @@ async function installOpenclaw(cfg) {
     log.success("Wrote OpenClaw config");
     log.blank();
     log.info("Install the skills:");
-    for (const name of cfg.skills ?? SKILL_NAMES) {
+    for (const name of cfg.skills ?? getDeliverableSkills()) {
         log.dim(`  openclaw skills install ${name}`);
     }
     return true;
 }
 // ─── Open WebUI ──────────────────────────────────────────────────────────────
 async function installOpenWebUI(cfg) {
-    const podBase = cfg.podUrl.replace(/\/$/, "");
-    const mcpUrl = cfg.workspaceId
-        ? `${podBase}/mcp?workspaceId=${encodeURIComponent(cfg.workspaceId)}`
-        : `${podBase}/mcp`;
+    const mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
     const podHost = new URL(cfg.podUrl).host;
     log.info("Open WebUI connects to Synap in two ways:");
     log.blank();
@@ -597,12 +1031,142 @@ async function installOpenWebUI(cfg) {
     log.success(`Connection details saved to ~/.synap/openwebui-mcp.json`);
     return true;
 }
-// ─── Generic MCP client ───────────────────────────────────────────────────────
+// ─── Windsurf ────────────────────────────────────────────────────────────────
+async function installWindsurf(info, cfg) {
+    const configPath = info.mcpConfigPath?.() ?? path.join(os.homedir(), ".codeium", "windsurf", "mcp_config.json");
+    const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "windsurf");
+    writeMcpServerEntry(configPath, "synap", { url: mcpUrl, headers: { Authorization: `Bearer ${effectiveApiKey}` } });
+    const { setSurfaceAgentKey: save } = await import("./pod.js");
+    save("windsurf", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
+    log.success(`Windsurf MCP config updated: ${configPath}`);
+    log.dim("Restart Windsurf to pick up the new MCP server.");
+    return true;
+}
+// ─── Goose ───────────────────────────────────────────────────────────────────
+async function installGoose(cfg) {
+    const configDir = path.join(os.homedir(), ".config", "goose");
+    const configPath = path.join(configDir, "config.yaml");
+    if (!fs.existsSync(configDir))
+        fs.mkdirSync(configDir, { recursive: true });
+    const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "goose");
+    const marker = "  synap:";
+    const block = [
+        "  synap:",
+        "    name: synap",
+        "    type: streamable_http",
+        `    uri: "${mcpUrl}"`,
+        "    env_keys: []",
+        "    timeout: 300",
+        `    headers:`,
+        `      Authorization: "Bearer ${effectiveApiKey}"`,
+    ].join("\n");
+    let existing = "";
+    if (fs.existsSync(configPath)) {
+        try {
+            existing = fs.readFileSync(configPath, "utf-8");
+        }
+        catch { /* ignore */ }
+    }
+    let updated;
+    if (existing.includes(marker)) {
+        updated = existing.replace(/  synap:[\s\S]*?(?=\n  [a-zA-Z_]|\s*$)/, block);
+    }
+    else if (/^extensions:/m.test(existing)) {
+        updated = existing.trimEnd() + "\n" + block + "\n";
+    }
+    else {
+        updated = (existing ? existing.trimEnd() + "\n\n" : "") + "extensions:\n" + block + "\n";
+    }
+    fs.writeFileSync(configPath, updated, { mode: 0o600 });
+    const { setSurfaceAgentKey: save } = await import("./pod.js");
+    save("goose", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
+    log.success(`Goose config updated: ${configPath}`);
+    log.dim("Run `goose session` to pick up the new MCP extension.");
+    return true;
+}
+// ─── Zed ─────────────────────────────────────────────────────────────────────
+function zedSettingsPath() {
+    switch (process.platform) {
+        case "darwin": return path.join(os.homedir(), "Library", "Application Support", "Zed", "settings.json");
+        case "win32": return path.join(process.env.APPDATA ?? os.homedir(), "Zed", "settings.json");
+        default: return path.join(os.homedir(), ".config", "zed", "settings.json");
+    }
+}
+async function installZed(cfg) {
+    const settingsPath = zedSettingsPath();
+    const settingsDir = path.dirname(settingsPath);
+    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 */ }
+    }
+    const contextServers = (settings.context_servers ?? {});
+    contextServers["synap"] = {
+        source: "custom",
+        command: {
+            path: "npx",
+            args: ["-y", "mcp-remote@latest", mcpUrl, "--header", `Authorization: Bearer ${effectiveApiKey}`],
+        },
+        settings: {},
+    };
+    settings.context_servers = contextServers;
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    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("Reload Zed to pick up the new context server (mcp-remote bridge).");
+    return true;
+}
+// ─── VS Code (Kilo Code / Cline / Continue / Copilot) ────────────────────────
+function vsCodeUserDataDir() {
+    switch (process.platform) {
+        case "darwin": return path.join(os.homedir(), "Library", "Application Support", "Code", "User");
+        case "win32": return path.join(process.env.APPDATA ?? os.homedir(), "Code", "User");
+        default: return path.join(os.homedir(), ".config", "Code", "User");
+    }
+}
+async function installVSCode(cfg) {
+    const mcpJsonPath = path.join(vsCodeUserDataDir(), "mcp.json");
+    const mcpDir = path.dirname(mcpJsonPath);
+    if (!fs.existsSync(mcpDir))
+        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 */ }
+    }
+    existing.servers = existing.servers ?? {};
+    existing.servers["synap"] = {
+        type: "http",
+        url: mcpUrl,
+        headers: { Authorization: `Bearer ${effectiveApiKey}` },
+    };
+    fs.writeFileSync(mcpJsonPath, JSON.stringify(existing, null, 2) + "\n", { mode: 0o600 });
+    const { setSurfaceAgentKey: save } = await import("./pod.js");
+    save("vscode", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
+    log.success(`VS Code MCP config updated: ${mcpJsonPath}`);
+    log.dim("Picked up automatically by Kilo Code, Cline, Continue, and GitHub Copilot.");
+    log.dim("Reload VS Code (or open the MCP panel) to activate.");
+    return true;
+}
 async function installGeneric(cfg) {
-    const podBase = cfg.podUrl.replace(/\/$/, "");
-    const mcpUrl = cfg.workspaceId
-        ? `${podBase}/mcp?workspaceId=${encodeURIComponent(cfg.workspaceId)}`
-        : `${podBase}/mcp`;
+    const mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
     const httpConfig = {
         synap: {
             url: mcpUrl,
@@ -649,10 +1213,7 @@ async function installCodex(info, cfg) {
     // Build MCP server entry
     const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, "codex");
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
-    const podBase = cfg.podUrl.replace(/\/$/, "");
-    const mcpUrl = cfg.workspaceId
-        ? `${podBase}/mcp?workspaceId=${encodeURIComponent(cfg.workspaceId)}`
-        : `${podBase}/mcp`;
+    const mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
     // Inject/replace the synap mcpServers block using simple string manipulation
     // (avoid requiring a YAML parser dependency)
     const mcpBlock = [
@@ -706,6 +1267,141 @@ async function installCodex(info, cfg) {
     log.dim("Restart Codex CLI to pick up the new MCP server.");
     return true;
 }
+async function fetchCredentials(podUrl, apiKey) {
+    const { fetchPodCredentials } = await import("../commands/providers.js");
+    return fetchPodCredentials(podUrl, apiKey);
+}
+/** Prompt the user to pick a provider from the pod and return it with its resolved key. */
+async function pickProvider(podUrl, apiKey) {
+    const spinner = ora("Fetching providers from pod vault...").start();
+    let providers;
+    try {
+        providers = await fetchCredentials(podUrl, apiKey);
+        spinner.stop();
+    }
+    catch (err) {
+        spinner.fail(`Could not fetch providers: ${err.message}`);
+        return null;
+    }
+    const withKeys = providers.filter((p) => p.apiKey);
+    if (withKeys.length === 0) {
+        log.warn("No providers with API keys found on this pod.");
+        log.dim("Add providers and keys in pod admin → Intelligence → Providers.");
+        return null;
+    }
+    if (withKeys.length === 1)
+        return withKeys[0];
+    const { choice } = await prompts({
+        type: "select",
+        name: "choice",
+        message: "Which AI provider do you want to use?",
+        choices: withKeys.map((p) => ({
+            title: `${p.name}  ${chalk.dim(p.providerId)}`,
+            value: p.providerId,
+        })),
+    });
+    return withKeys.find((p) => p.providerId === choice) ?? null;
+}
+export async function installOpencode(cfg) {
+    const provider = await pickProvider(cfg.podUrl, cfg.apiKey);
+    if (!provider || !provider.apiKey)
+        return false;
+    // Build model map from the chosen provider
+    if (provider.models.length === 0) {
+        log.warn(`No model IDs found for ${provider.name} — configure models in pod admin → Intelligence → Providers`);
+        return false;
+    }
+    const models = {};
+    let defaultModel = "";
+    for (const m of provider.models) {
+        const key = `${provider.providerId}/${m.id}`;
+        models[key] = {
+            name: m.id,
+            ...(m.contextWindow ? { contextLength: m.contextWindow } : {}),
+        };
+        if (!defaultModel)
+            defaultModel = key;
+    }
+    const configDir = path.join(os.homedir(), ".config", "opencode");
+    const configPath = path.join(configDir, "opencode.json");
+    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 {
+            fs.copyFileSync(configPath, `${configPath}.bak`);
+            log.warn("Existing opencode.json unreadable — backed up to opencode.json.bak");
+        }
+    }
+    const providerBlock = (existing.provider ?? {});
+    providerBlock[provider.providerId] = {
+        npm: "@ai-sdk/openai-compatible",
+        name: provider.name,
+        options: { baseURL: provider.baseUrl, apiKey: provider.apiKey },
+        models,
+    };
+    // Provision an agent key so the MCP server runs under its own identity
+    const { hubApiKey: agentKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, "opencode");
+    await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
+    const podBase = cfg.podUrl.replace(/\/$/, "");
+    const mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
+    const mcpBlock = (existing.mcp ?? {});
+    mcpBlock["synap"] = { type: "remote", url: mcpUrl, headers: { Authorization: `Bearer ${agentKey}` } };
+    const updated = {
+        $schema: "https://opencode.ai/config.json",
+        ...existing,
+        provider: providerBlock,
+        mcp: mcpBlock,
+        ...(existing.model ? {} : { model: defaultModel }),
+    };
+    fs.writeFileSync(configPath, JSON.stringify(updated, null, 2) + "\n", { mode: 0o600 });
+    const { setSurfaceAgentKey: save } = await import("./pod.js");
+    save("opencode", { hubApiKey: agentKey, agentUserId, podUrl: cfg.podUrl });
+    log.success(`opencode configured: ~/.config/opencode/opencode.json`);
+    log.dim(`  AI provider: ${provider.name}  (${Object.keys(models).length} model(s))`);
+    log.dim(`  MCP tools:   synap pod at ${podBase}`);
+    log.blank();
+    log.dim("Restart opencode to pick up the new provider and MCP server.");
+    return true;
+}
+// ─── aider ───────────────────────────────────────────────────────────────────
+export async function installAider(cfg) {
+    const provider = await pickProvider(cfg.podUrl, cfg.apiKey);
+    if (!provider || !provider.apiKey)
+        return false;
+    const defaultModel = provider.models[0]?.id ?? "default";
+    const confPath = path.join(os.homedir(), ".aider.conf.yml");
+    let existing = "";
+    if (fs.existsSync(confPath)) {
+        try {
+            existing = fs.readFileSync(confPath, "utf-8");
+        }
+        catch { /* ignore */ }
+    }
+    const marker = "# synap-provider";
+    const block = [
+        marker,
+        `openai-api-base: ${provider.baseUrl}`,
+        `openai-api-key: ${provider.apiKey}`,
+        `model: openai/${defaultModel}`,
+        "",
+    ].join("\n");
+    const updated = existing.includes(marker)
+        ? existing.replace(/# synap-provider[\s\S]*?(?=\n[a-zA-Z#]|\s*$)/, block.trimEnd())
+        : existing ? `${existing.trimEnd()}\n\n${block}` : block;
+    fs.writeFileSync(confPath, updated.trimEnd() + "\n", { mode: 0o600 });
+    log.success(`${provider.name} configured in ~/.aider.conf.yml`);
+    log.dim(`  Base URL: ${provider.baseUrl}`);
+    log.dim(`  Model:    openai/${defaultModel}`);
+    log.blank();
+    log.dim("Aider picks up ~/.aider.conf.yml automatically.");
+    return true;
+}
+// ─── MCP config writer ───────────────────────────────────────────────────────
 export function writeMcpServerEntry(configPath, serverName, server) {
     const dir = path.dirname(configPath);
     if (!fs.existsSync(dir)) {
@@ -729,4 +1425,90 @@ export function writeMcpServerEntry(configPath, serverName, server) {
         mode: 0o600,
     });
 }
+// Governance presets — MUST stay in sync with GOVERNANCE_MODES in the backend
+// `@synap/governance-policy`. (Single-source TODO: have the backend resolve a
+// mode NAME so the CLI never re-states the autoApproveFor list — until then,
+// this is the one place to mirror when the backend presets change.)
+const GOVERNANCE_PRESETS = {
+    safe: {
+        autoApproveFor: [
+            "search.*", "memory.recall", "entity.read", "document.read",
+            "context.*", "filesystem.read", "bento.arrange",
+        ],
+        writesRequireProposal: true,
+    },
+    normal: {
+        autoApproveFor: [
+            "search.*", "memory.recall", "entity.read", "document.read",
+            "context.*", "filesystem.read", "bento.arrange",
+            "entity.create", "document.create", "relation.create",
+            "view.create", "profile.create", "property_def.create",
+            "channel.create",
+            // Non-destructive edits are instant too (merge / field-level partial —
+            // mirrors backend NORMAL). Full-REPLACE writes (document.update,
+            // view.update) + destructive ops stay proposal-gated.
+            "entity.update", "relation.update", "profile.update", "property_def.update",
+            // Capability-substrate creates — "creates are instant" (mirrors backend).
+            "automation.create", "playbook.create", "link.create",
+            "tool.create", "skill.create",
+            "playbook.read", "tool.read", "link.read", "capability.read",
+            "terminal.read_logs", "filesystem.write_workspace",
+            // Kind + Facets — additive role attach/update/detach (detach is a
+            // reversible soft-delete), same tier as entity.create/update (mirrors
+            // backend DEFAULT_AUTO_APPROVE / GOVERNANCE_MODES.normal).
+            "facet.attach", "facet.update", "facet.detach",
+        ],
+        writesRequireProposal: false,
+    },
+    crazy: {
+        autoApproveFor: ["*"],
+        writesRequireProposal: false,
+    },
+};
+export async function ensureAgentGovernance(cfg, agentUserId, presetMode) {
+    const userId = await resolveUserId(cfg);
+    const hubCfg = { ...cfg, userId };
+    // Non-interactive when a preset is passed (e.g. `--governance normal`);
+    // otherwise prompt (Normal pre-selected, Enter = <1s).
+    let mode = presetMode;
+    if (!mode) {
+        const res = await prompts({
+            type: "select",
+            name: "mode",
+            message: "Governance — how should this agent's actions be gated?",
+            choices: [
+                {
+                    title: "Safe — every change requires your approval in Synap Studio",
+                    description: "Creates, updates, and deletes all go through proposals. Maximum control.",
+                    value: "safe",
+                },
+                {
+                    title: "Normal — creating & editing are instant, deletes need approval (recommended)",
+                    description: "Agents create and edit data immediately (edits merge, never wipe fields); deletes and full-content rewrites go through proposals.",
+                    value: "normal",
+                },
+                {
+                    title: "Crazy — everything is instant; revert in Studio if needed",
+                    description: "All actions auto-execute. You can revert anything in Synap Studio.",
+                    value: "crazy",
+                },
+            ],
+            initial: 1,
+        });
+        if (!res.mode)
+            return;
+        mode = res.mode;
+    }
+    const profile = GOVERNANCE_PRESETS[mode] ?? GOVERNANCE_PRESETS.normal;
+    try {
+        await hubPatch(`/agent-users/${agentUserId}/governance`, {
+            autoApproveFor: profile.autoApproveFor,
+            writesRequireProposal: profile.writesRequireProposal,
+        }, hubCfg);
+        log.success(`Agent governance set to "${mode}"`);
+    }
+    catch (err) {
+        log.warn(`Could not apply agent governance: ${err.message}`);
+    }
+}
 //# sourceMappingURL=targets.js.map