@synap-core/cli 1.8.0 → 1.11.0

package/dist/lib/targets.js

@@ -11,12 +11,13 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { exec } from "node:child_process";
+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");
@@ -30,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",
@@ -59,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",
@@ -128,47 +161,21 @@ export const TARGETS = {
 export function isTargetName(value) {
     return value in TARGETS;
 }
-async function fetchWorkspaces(podUrl, apiKey) {
-    try {
-        const res = await fetch(`${podUrl.replace(/\/$/, "")}/api/hub/workspaces`, {
-            headers: { Authorization: `Bearer ${apiKey}` },
-            signal: AbortSignal.timeout(8000),
-        });
-        if (!res.ok)
-            return [];
-        const data = await res.json();
-        return Array.isArray(data) ? data : (data.workspaces ?? []);
-    }
-    catch {
-        return [];
-    }
-}
-async function provisionAgentWorkspace(podUrl, apiKey, agentUserId, workspaceName) {
-    try {
-        const res = await fetch(`${podUrl.replace(/\/$/, "")}/api/hub/workspaces/provision-agent`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
-            body: JSON.stringify({ agentUserId, workspaceName }),
-            signal: AbortSignal.timeout(10000),
-        });
-        if (!res.ok)
-            return null;
-        const data = await res.json();
-        const resolvedId = data.workspaceId ?? data.id ?? (data.workspace?.id);
-        if (data.workspace)
-            return data.workspace;
-        return resolvedId ? { id: resolvedId, name: data.name ?? workspaceName } : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** Build the pod's /mcp URL, appending ?workspaceId= when a workspace is scoped. */
-function buildMcpUrl(podUrl, workspaceId) {
+/**
+ * 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(/\/$/, "");
-    return workspaceId
-        ? `${podBase}/mcp?workspaceId=${encodeURIComponent(workspaceId)}`
-        : `${podBase}/mcp`;
+    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,
@@ -177,118 +184,42 @@ function buildMcpUrl(podUrl, workspaceId) {
 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) };
+    return { effectiveApiKey, agentUserId, mcpUrl: buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId) };
 }
 // ─── Agent context configuration ──────────────────────────────────────────────
-async function configureAgentContext(podUrl, apiKey, agentType, agentUserId, info) {
+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  (3 steps)");
-    log.dim("Set up where this agent keeps its own memory, which team workspaces it writes to, and its skill template.");
-    // Fetch workspaces once — reused by step 1 and step 2 (no duplicate network calls)
-    const wsSpinner = ora("Fetching workspaces…").start();
-    const allWorkspaces = await fetchWorkspaces(podUrl, apiKey);
-    wsSpinner.stop();
-    // ── Step 1 · Agent memory workspace ──────────────────────────────────────
-    log.blank();
-    log.info(chalk.bold("Step 1 of 3 — Agent memory"));
-    log.dim("A private workspace for this agent's own notes, learned patterns, and session context.");
-    log.blank();
-    let memoryWorkspace;
-    const CREATE_SENTINEL = "__create__";
-    const SKIP_SENTINEL = "__skip__";
-    // Score workspaces by name relevance to "agent memory" — higher = better suggestion
-    function memoryScore(w) {
-        const n = w.name.toLowerCase();
-        return ["memory", "agent", "assistant", agentType.toLowerCase()]
-            .reduce((s, kw) => s + (n.includes(kw) ? 1 : 0), 0);
-    }
-    const bestMemIdx = allWorkspaces.length > 0
-        ? allWorkspaces.reduce((bi, w, i) => memoryScore(w) > memoryScore(allWorkspaces[bi]) ? i : bi, 0)
-        : -1;
-    const hasSuggestion = bestMemIdx >= 0 && memoryScore(allWorkspaces[bestMemIdx]) > 0;
-    const memoryChoices = [
-        ...allWorkspaces.map((w, i) => {
-            const hint = (i === bestMemIdx && hasSuggestion) ? chalk.green("  ← suggested") : "";
-            return { title: `${chalk.bold(w.name)}  ${chalk.dim(w.id)}${hint}`, value: w.id };
-        }),
-        { title: chalk.cyan("Create a new workspace…"), value: CREATE_SENTINEL },
-        { title: chalk.dim("None — skip"), value: SKIP_SENTINEL },
-    ];
-    // Default: suggested workspace if one matches, otherwise "Create a new workspace"
-    const memoryDefaultIdx = hasSuggestion ? bestMemIdx : allWorkspaces.length;
-    const { memoryPickedId } = await prompts({
-        type: "select",
-        name: "memoryPickedId",
-        message: "Which workspace is this agent's private memory?",
-        choices: memoryChoices,
-        initial: memoryDefaultIdx,
-    });
-    if (memoryPickedId && memoryPickedId !== SKIP_SENTINEL) {
-        if (memoryPickedId === CREATE_SENTINEL) {
-            const defaultName = `${agentType} Memory`;
-            const { newName } = await prompts({
-                type: "text",
-                name: "newName",
-                message: "Workspace name:",
-                initial: defaultName,
-                validate: (v) => v.trim().length > 0 || "Name is required",
-            });
-            const finalName = (newName ?? "").trim() || defaultName;
-            if (!agentUserId) {
-                log.warn("Agent identity not available — cannot provision a workspace. Reconnect to try again.");
-            }
-            else {
-                const createSpinner = ora(`Creating "${finalName}"…`).start();
-                const ws = await provisionAgentWorkspace(podUrl, apiKey, agentUserId, finalName);
-                if (ws) {
-                    memoryWorkspace = ws;
-                    createSpinner.succeed(`Created: ${chalk.bold(ws.name)}  ${chalk.dim(ws.id)}`);
-                }
-                else {
-                    createSpinner.fail("Could not create workspace — check pod logs. You can set one up manually later.");
-                }
-            }
-        }
-        else {
-            memoryWorkspace = allWorkspaces.find((w) => w.id === memoryPickedId);
-        }
-    }
-    // ── Step 2 · Team / product workspaces ───────────────────────────────────
-    log.blank();
-    log.info(chalk.bold("Step 2 of 3 — Team workspaces"));
-    log.dim("Workspaces where the agent posts updates, tasks, and decisions for your team to see.");
+    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();
-    // Reuse the already-fetched list — exclude whichever workspace was chosen as memory
-    const candidates = allWorkspaces.filter((w) => w.id !== memoryWorkspace?.id);
-    let productWorkspaces = [];
-    if (candidates.length === 0) {
-        log.dim("No other workspaces found — you can configure this later by re-running connect.");
-    }
-    else {
-        log.dim("Space to select/deselect, enter to confirm. Skip to leave unset.");
-        const { productIds } = await prompts({
-            type: "multiselect",
-            name: "productIds",
-            message: "Which workspace(s) should the agent write to?",
-            choices: candidates.map((w) => ({ title: `${w.name}  ${chalk.dim(w.id)}`, value: w.id })),
-        });
-        productWorkspaces = candidates.filter((w) => (productIds ?? []).includes(w.id));
-    }
-    // ── Step 3 · Template ─────────────────────────────────────────────────────
-    log.blank();
-    log.info(chalk.bold("Step 3 of 3 — Agent template"));
+    log.info(chalk.bold("Agent template"));
     log.dim("The template sets the agent's default behaviour and routing rules.");
     log.blank();
-    const { 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,
-        })),
-    });
+    // 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({
@@ -297,12 +228,11 @@ async function configureAgentContext(podUrl, apiKey, agentType, agentUserId, inf
         memoryWorkspace,
         productWorkspaces,
     });
-    // Persist workspace routing to config — drives capture/recall defaults
+    // 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: memoryWorkspace?.id,
-        productWorkspaceIds: productWorkspaces.map((w) => w.id),
-    });
+    setAgentWorkspaceRouting({ memoryWorkspaceId: undefined, productWorkspaceIds: [] });
     // Always write to ~/.synap/contexts/<surface>.md
     const contextDir = path.join(os.homedir(), ".synap", "contexts");
     if (!fs.existsSync(contextDir))
@@ -310,7 +240,7 @@ async function configureAgentContext(podUrl, apiKey, agentType, agentUserId, inf
     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?.();
+    const skillsDir = info?.skillsDir?.();
     if (skillsDir) {
         const synapSkillDir = path.join(skillsDir, "synap");
         if (!fs.existsSync(synapSkillDir))
@@ -325,18 +255,7 @@ async function configureAgentContext(podUrl, apiKey, agentType, agentUserId, inf
     // Summary
     log.blank();
     log.info(`  Template     ${chalk.bold(template.label)}`);
-    if (memoryWorkspace) {
-        log.info(`  Memory       ${chalk.bold(memoryWorkspace.name)}  ${chalk.dim(memoryWorkspace.id)}`);
-    }
-    else {
-        log.info(`  Memory       ${chalk.dim("(none)")}`);
-    }
-    if (productWorkspaces.length > 0) {
-        log.info(`  Product      ${productWorkspaces.map((w) => chalk.bold(w.name)).join(", ")}`);
-    }
-    else {
-        log.info(`  Product      ${chalk.dim("(none)")}`);
-    }
+    log.info(`  Scope        ${chalk.bold("pod-wide")} ${chalk.dim("· memory is automatic · focus a project at runtime")}`);
     log.blank();
 }
 export function listTargets() {
@@ -433,20 +352,20 @@ async function installClaudeCode(info, cfg) {
         message: "What do you want to install?",
         choices: [
             {
-                title: "Skills + agent key  (recommended)",
-                description: "Claude Code reads/writes Synap via synap CLI commands — no MCP overhead",
-                value: "skills",
-            },
-            {
-                title: "Skills + agent key + MCP server",
-                description: "Also registers a live MCP tool server (for users who prefer tool-call access)",
+                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 server only",
-                description: "Tool-call interface only — skip skills and CLI setup",
+                description: "Ambient tool-call interface only — skip skills and CLI setup. Best for non-terminal clients",
                 value: "mcp",
             },
+            {
+                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",
+            },
         ],
         initial: 0,
     });
@@ -458,7 +377,7 @@ 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/`);
@@ -560,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();
@@ -572,11 +493,11 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
         method: "POST",
         headers: { "Content-Type": "application/json", Authorization: `Bearer ${cfg.apiKey}` },
         body: JSON.stringify({ agentType: "claude-code", idempotent: true }),
-        signal: AbortSignal.timeout(10000),
+        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.alreadyValid) {
@@ -597,7 +518,7 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
                 // 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(5000),
+                    signal: AbortSignal.timeout(30000),
                 });
                 if (verifyRes.ok) {
                     const verifyStatus = await verifyRes.json();
@@ -616,7 +537,7 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
                 method: "POST",
                 headers: { "Content-Type": "application/json", Authorization: `Bearer ${cfg.apiKey}` },
                 body: JSON.stringify({ agentType: "claude-code" }),
-                signal: AbortSignal.timeout(10000),
+                signal: AbortSignal.timeout(30000),
             });
             if (reproRes.ok) {
                 const repro = await reproRes.json();
@@ -639,10 +560,14 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
     // 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 ?? "" });
+    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;
@@ -652,26 +577,78 @@ 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 = buildMcpUrl(cfg.podUrl, cfg.workspaceId);
-        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}"` :
@@ -680,31 +657,18 @@ function openBrowserUrl(url) {
     exec(cmd, () => { });
 }
 async function waitForKeyApproval(podBase, humanApiKey, pendingToken, agentType) {
-    const pollUrl = `${podBase}/api/hub/setup/agent/pending/${pendingToken}`;
-    const deadline = Date.now() + 120_000;
-    while (Date.now() < deadline) {
-        await new Promise((r) => setTimeout(r, 2000));
-        let poll;
-        try {
-            poll = await fetch(pollUrl, {
-                headers: { Authorization: `Bearer ${humanApiKey}` },
-                signal: AbortSignal.timeout(5000),
-            });
-        }
-        catch {
-            continue;
-        }
-        if (!poll.ok)
-            continue;
-        const data = await poll.json();
-        if (data.status === "active")
-            return;
-        if (data.status === "rejected") {
-            throw new Error(`Agent key for ${agentType} was rejected in the browser. Run connect again to re-request.`);
-        }
-    }
-    throw new Error(`Timed out waiting for approval of ${agentType} agent key (120s). ` +
-        `Open the review URL manually or run connect again.`);
+    // 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.
@@ -712,7 +676,12 @@ async function waitForKeyApproval(podBase, humanApiKey, pendingToken, agentType)
  * browser before this function returns.
  * Throws on failure — callers must not silently fall back to a human key.
  */
-async function provisionAgentKey(podUrl, humanApiKey, agentType, { requireApproval = true } = {}) {
+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 {
@@ -722,8 +691,8 @@ async function provisionAgentKey(podUrl, humanApiKey, agentType, { requireApprov
                 "Content-Type": "application/json",
                 Authorization: `Bearer ${humanApiKey}`,
             },
-            body: JSON.stringify({ agentType, idempotent: false, requireApproval }),
-            signal: AbortSignal.timeout(10000),
+            body: JSON.stringify({ agentType, idempotent, requireApproval }),
+            signal: AbortSignal.timeout(30000),
         });
     }
     catch (err) {
@@ -732,10 +701,64 @@ async function provisionAgentKey(podUrl, humanApiKey, agentType, { requireApprov
     }
     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.`);
@@ -755,7 +778,7 @@ async function provisionAgentKey(podUrl, humanApiKey, agentType, { requireApprov
         }
         log.success(`  Approved! Writing ${agentType} agent key.`);
     }
-    return { hubApiKey: body.hubApiKey, agentUserId: body.agentUserId ?? "" };
+    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.
@@ -764,10 +787,14 @@ async function provisionAgentKey(podUrl, humanApiKey, agentType, { requireApprov
  * @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`, {
@@ -776,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 ──────────────────────────────────────────────────────────
@@ -810,9 +839,9 @@ 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 });
+    saveDesktopKey("claude-desktop", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
-    const desktopMcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId);
+    const desktopMcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
     writeMcpServerEntry(mcpPath, "synap", {
         command: "npx",
         args: ["-y", "mcp-remote", desktopMcpUrl, "--header", `Authorization: Bearer ${effectiveApiKey}`],
@@ -827,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.");
@@ -853,9 +882,9 @@ async function installCursor(info, cfg) {
         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 });
+    saveCursorKey("cursor", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
-    const cursorMcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId);
+    const cursorMcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
     writeMcpServerEntry(mcpPath, "synap", {
         url: cursorMcpUrl,
         headers: { Authorization: `Bearer ${effectiveApiKey}` },
@@ -872,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) ───────────────────
@@ -950,14 +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 mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId);
+    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();
@@ -991,7 +1037,7 @@ async function installWindsurf(info, cfg) {
     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 });
+    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;
@@ -1033,7 +1079,7 @@ async function installGoose(cfg) {
     }
     fs.writeFileSync(configPath, updated, { mode: 0o600 });
     const { setSurfaceAgentKey: save } = await import("./pod.js");
-    save("goose", { hubApiKey: effectiveApiKey, agentUserId });
+    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;
@@ -1077,7 +1123,7 @@ async function installZed(cfg) {
     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 });
+    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).");
@@ -1113,14 +1159,14 @@ async function installVSCode(cfg) {
     };
     fs.writeFileSync(mcpJsonPath, JSON.stringify(existing, null, 2) + "\n", { mode: 0o600 });
     const { setSurfaceAgentKey: save } = await import("./pod.js");
-    save("vscode", { hubApiKey: effectiveApiKey, agentUserId });
+    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 mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId);
+    const mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
     const httpConfig = {
         synap: {
             url: mcpUrl,
@@ -1167,7 +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 mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId);
+    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 = [
@@ -1302,7 +1348,7 @@ export async function installOpencode(cfg) {
     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);
+    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 = {
@@ -1314,7 +1360,7 @@ export async function installOpencode(cfg) {
     };
     fs.writeFileSync(configPath, JSON.stringify(updated, null, 2) + "\n", { mode: 0o600 });
     const { setSurfaceAgentKey: save } = await import("./pod.js");
-    save("opencode", { hubApiKey: agentKey, agentUserId });
+    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}`);
@@ -1379,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