@synap-core/cli 1.11.0 → 1.13.0

package/dist/commands/bridge-setup.js

@@ -18,27 +18,133 @@
  * Hidden on purpose: this is a dogfood/dev convenience, not a first-class
  * surface. Not shown in `synap --help`.
  *
+ * The bridge lands data POD-WIDE by default. An OPTIONAL project scope can be
+ * picked interactively (or via --project-id); --workspace-id remains an
+ * advanced/legacy escape hatch to pin a single workspace, never prompted.
+ *
  * Usage:
  *   synap bridge-setup --client-id <discord-app-id> [--bridge-dir <path>]
- *     [--pod <profile-name>] [--workspace-id <uuid>]
+ *     [--pod <profile-name>] [--workspace-id <uuid>] [--project-id <uuid>]
  *     [--proactive-channel <discord-channel-id>] [--enable-react]
  *     [--pod-url <url>] [--api-key <key>]
  */
 import path from "node:path";
 import os from "node:os";
 import fs from "node:fs";
+import { writeSecretFile } from "../lib/atomic-file.js";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
 import ora from "ora";
 import prompts from "prompts";
-import { hubGet, hubPost, hubPatch, resolveUserId } from "../lib/hub-client.js";
+import { hubGet, hubPost, hubPatch, resolveUserId, renderHubError } from "../lib/hub-client.js";
 import { unwrapList } from "../lib/unwrapList.js";
-import { discoverSkillDirs, parseSkillDir, importSkill } from "../lib/skill-import.js";
+import { fetchProjects } from "../lib/project.js";
+import { parseSkillDir, importSkill } from "../lib/skill-import.js";
+import { CLI_TEMPLATES_DIR, resolveAgencySkillDirs, resolveAutomationTemplatesDir, resolveInstalledCatalogRoot, } from "../lib/catalog-templates.js";
 import { checkPodHealth, getSurfaceAgentKey, setSurfaceAgentKey, listPodProfiles, getSurfacePodName, setSurfacePod, podNotFoundError, } from "../lib/pod.js";
 import { enrollAgentIfNeeded, ensureAgentGovernance, provisionAgentKey, configureAgentContext, } from "../lib/targets.js";
 import { log, banner } from "../utils/logger.js";
 const DEFAULT_BRIDGE_DIR = path.join(os.homedir(), "Documents", "Code", "telegram-discord-bridge");
+/** Parse a dotenv file into KEY→value. Values are used, never printed. */
+function readEnvFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return {};
+    const out = {};
+    for (const line of fs.readFileSync(filePath, "utf-8").split("\n")) {
+        const m = line.match(/^([A-Z0-9_]+)=(.*)$/);
+        if (m)
+            out[m[1]] = m[2].trim();
+    }
+    return out;
+}
+/** Local-only detection — no network, so it runs before the first prompt. */
+function detectPriorState(bridgeDir) {
+    const envPath = path.join(bridgeDir, ".env");
+    const env = readEnvFile(envPath);
+    const podName = getSurfacePodName("discord");
+    const hasAgentKey = Boolean(getSurfaceAgentKey("discord")?.hubApiKey);
+    const ctx = path.join(os.homedir(), ".synap", "contexts", "discord.md");
+    const vaultRef = env.SYNAP_DISCORD_TOKEN_REF || undefined;
+    return {
+        isReRun: Boolean(podName || hasAgentKey || env.SYNAP_POD_URL || vaultRef),
+        bridgeProvisioned: Boolean(hasAgentKey || env.SYNAP_POD_URL || vaultRef),
+        envPath,
+        podName,
+        hasAgentKey,
+        contextPath: fs.existsSync(ctx) ? ctx : null,
+        vaultRef,
+        secretId: vaultRef?.startsWith("vault://")
+            ? vaultRef.slice("vault://".length)
+            : undefined,
+        workspaceId: env.SYNAP_WORKSPACE_ID || undefined,
+        projectId: env.SYNAP_PROJECT_ID || undefined,
+        guildId: env.DISCORD_GUILD_ID || undefined,
+    };
+}
+/**
+ * Report what is already configured BEFORE any prompt, so the operator can see
+ * this is a re-run rather than a first run — and can see exactly what will be
+ * reused vs. re-asked. Silent on a genuine first run (unchanged experience).
+ */
+function printPriorState(prior, reconfigure) {
+    if (!prior.isReRun)
+        return;
+    log.blank();
+    log.heading(reconfigure
+        ? "Existing setup detected — --reconfigure: re-asking everything"
+        : "Existing setup detected — reusing what is already configured");
+    const found = [];
+    const ask = [];
+    const item = (label, detail, ifMissing) => {
+        if (detail)
+            found.push(`  ${chalk.green("✓")} ${label.padEnd(20)}${detail}`);
+        else
+            ask.push(`${label.toLowerCase()} (${ifMissing})`);
+    };
+    item("Pod profile", prior.podName && `${prior.podName} ${chalk.dim("(discord surface)")}`, "will ask");
+    item("Discord agent key", prior.hasAgentKey ? "stored locally — reused, not rotated" : null, "will be minted");
+    item("Agent template", prior.contextPath, "will ask");
+    item("Bot token", prior.vaultRef ? `in the pod vault ${chalk.dim(prior.vaultRef)} — not re-asked` : null, "will ask");
+    item("Workspace pin", prior.workspaceId ?? null, "pod-wide");
+    item("Project pin", prior.projectId ?? null, "pod-wide");
+    item("Discord server id", prior.guildId ?? null, "pass --guild-id");
+    if (reconfigure) {
+        // Nothing below is reused — say so rather than listing it as "found".
+        log.dim("  Every question is asked again and every step re-provisioned.");
+    }
+    else {
+        for (const line of found)
+            console.log(line);
+        log.dim(ask.length
+            ? `  Still to configure: ${ask.join(", ")}`
+            : "  Nothing left to ask — everything above is reused.");
+    }
+    log.dim("  Capabilities, skills and automations re-apply idempotently — each reports its own line below.");
+    if (!reconfigure) {
+        log.dim(`  To re-ask everything instead: ${chalk.cyan("synap bridge-setup --reconfigure")}`);
+    }
+    log.blank();
+}
+/**
+ * Confirm the bot token a previous run vaulted is STILL in the vault, before
+ * deciding not to ask for it. Never returns or logs the secret itself.
+ *
+ *  - "present" → skip the prompt, reuse the ref
+ *  - "missing" → the .env ref is stale; ask for the token again (and say why)
+ *  - "unknown" → the read failed / the door isn't deployed; keep the ref
+ *                WITHOUT re-asking, and say it could not be verified
+ */
+async function checkVaultSecret(cfg, workspaceId, secretId) {
+    try {
+        const res = await hubGet("/vault/secrets", { workspaceId }, cfg);
+        const rows = unwrapList(res, ["secrets"]);
+        return rows.some((r) => r.id === secretId) ? "present" : "missing";
+    }
+    catch {
+        return "unknown";
+    }
+}
 // Bot invite permissions — the full set the bridge's features actually use.
 // Bits per Discord's permission reference (https://discord.com/developers/docs/topics/permissions).
 // BigInt because thread permissions exceed 2^31. Least-privilege *within* what we
@@ -73,10 +179,11 @@ const BOT_PERMISSIONS = Object.values(BOT_PERMISSION_BITS)
  * Discord bridge points at a different (e.g. team / client) pod.
  *
  * Order: explicit --pod-url/--api-key escape hatch → --pod <name> →
- * single saved profile (auto) → interactive picker (default = the pod already
- * assigned to the discord surface, else the CLI-active one).
+ * single saved profile (auto) → the pod THIS BRIDGE is already connected to
+ * (re-run, no prompt) → interactive picker (default = the pod already assigned
+ * to the discord surface, else the CLI-active one).
  */
-async function resolveBridgePod(opts) {
+async function resolveBridgePod(opts, prior, reconfigure) {
     // 1. Raw URL+key escape hatch — bypasses profiles entirely.
     if (opts.podUrl && opts.apiKey) {
         return {
@@ -99,6 +206,14 @@ async function resolveBridgePod(opts) {
         chosen = profiles[0];
         log.dim(`Using your only saved pod profile: ${chosen.name}`);
     }
+    else if (!reconfigure &&
+        prior.podName &&
+        profiles.some((p) => p.name === prior.podName)) {
+        // Re-run: the bridge is already bound to a pod (discord surface override).
+        // Re-asking would only invite a mis-click that repoints a live bridge.
+        chosen = profiles.find((p) => p.name === prior.podName);
+        log.dim(`  [skip] pod — already connected to "${chosen.name}" (--pod or --reconfigure to change)`);
+    }
     else {
         const defaultName = getSurfacePodName("discord") ?? profiles.find((p) => p.active)?.name ?? profiles[0].name;
         const initial = Math.max(0, profiles.findIndex((p) => p.name === defaultName));
@@ -124,7 +239,9 @@ async function resolveBridgePod(opts) {
         cfg: {
             podUrl: c.podUrl,
             apiKey: c.hubApiKey,
-            userId: c.agentUserId,
+            // Acting user asked of the pod; the key's agent id rides apart (HubConfig.userId).
+            userId: "cli",
+            agentUserId: c.agentUserId || undefined,
             workspaceId: c.workspaceId || undefined,
         },
         podName: chosen.name,
@@ -133,11 +250,17 @@ async function resolveBridgePod(opts) {
 export async function bridgeSetup(opts) {
     banner();
     log.heading("Discord bridge — one-shot setup");
+    // ── 0. Detect what a previous run already configured, and SAY SO before we
+    //      ask anything. Purely local — no network, no prompt. ────────────────
+    const bridgeDir = opts.bridgeDir ?? DEFAULT_BRIDGE_DIR;
+    const reconfigure = Boolean(opts.reconfigure) || process.env.SYNAP_BRIDGE_SETUP_RECONFIGURE === "1";
+    const prior = detectPriorState(bridgeDir);
+    printPriorState(prior, reconfigure);
     // ── 1. Choose the pod the BRIDGE connects to (independent of the CLI pod) ──
     let cfg;
     let bridgePodName = null;
     try {
-        const resolved = await resolveBridgePod(opts);
+        const resolved = await resolveBridgePod(opts, prior, reconfigure);
         cfg = resolved.cfg;
         bridgePodName = resolved.podName;
     }
@@ -157,13 +280,11 @@ export async function bridgeSetup(opts) {
         process.exit(1);
     }
     log.success(`Pod healthy: ${cfg.podUrl}${bridgePodName ? ` (profile: ${bridgePodName})` : ""}`);
-    // ── 3. Resolve workspace ───────────────────────────────────────────────
-    const workspaceId = await resolveWorkspaceId(opts.workspaceId, cfg.workspaceId, cfg);
-    if (!workspaceId) {
-        log.error("Could not resolve a workspace. Pass --workspace-id <uuid>.");
-        process.exit(1);
-    }
-    log.dim(`Workspace: ${workspaceId}`);
+    // ── 3. Resolve scope — pod-wide by default, workspace/project optional ───
+    const { workspaceId, projectId } = await resolveScope(opts, cfg, prior, reconfigure);
+    log.dim(workspaceId ? `Workspace: ${workspaceId} (explicit pin)` : "Workspace: pod-wide (no pin)");
+    if (projectId)
+        log.dim(`Project: ${projectId}`);
     // ── 3b. Key + scope sanity check (GET /capabilities needs hub-protocol.read) ─
     const probe = ora("Checking key scope…").start();
     try {
@@ -172,7 +293,7 @@ export async function bridgeSetup(opts) {
     }
     catch (err) {
         probe.fail("Key/scope check failed");
-        log.error(err.message);
+        renderHubError(err);
         log.dim("The key may be expired or missing scope. Run `synap keys rotate` or `synap init`.");
         process.exit(1);
     }
@@ -182,33 +303,65 @@ export async function bridgeSetup(opts) {
     // reads to the operator's data floor (hub-protocol-rest.ts auth middleware)
     // while attributing writes to the agent for governed proposals. All the
     // operator-key work below (capability apply, vault grant) keeps using `cfg`.
-    const agentKey = await provisionDiscordAgentKey(cfg.podUrl, cfg.apiKey, cfg.workspaceId);
+    const agentKey = await provisionDiscordAgentKey(cfg.podUrl, cfg.apiKey, cfg.workspaceId, !reconfigure ? prior.contextPath : null);
     // ── 4. Provision the capability (vault credential + tool + skill) ─────────
-    const bridgeDir = opts.bridgeDir ?? DEFAULT_BRIDGE_DIR;
-    const botToken = await resolveBotToken(opts.botToken);
-    const { vaultRef, secretId } = await applyBridgeCapability(bridgeDir, workspaceId, cfg, botToken);
+    // The bot token is the sharpest re-run case: it is ALREADY in the pod vault,
+    // so re-prompting for it asks the operator to paste a live secret the system
+    // holds. Verify the vaulted secret instead, and only ask when it is genuinely
+    // gone (or when --reconfigure / --bot-token says to rotate it).
+    let botToken;
+    let reuseVaultRef;
+    if (opts.botToken) {
+        botToken = opts.botToken;
+    }
+    else if (!reconfigure && prior.secretId) {
+        const state = await checkVaultSecret(cfg, workspaceId, prior.secretId);
+        if (state === "present") {
+            reuseVaultRef = prior.vaultRef;
+            log.dim(`  [skip] bot token — already in the pod vault (${prior.vaultRef}); not re-asked`);
+        }
+        else if (state === "unknown") {
+            reuseVaultRef = prior.vaultRef;
+            log.warn(`  [warn] bot token — could not read the vault to confirm ${prior.vaultRef}; ` +
+                "keeping it rather than asking you to paste the token again (--reconfigure to re-enter).");
+        }
+        else {
+            log.warn(`  [warn] bot token — the vault no longer holds ${prior.vaultRef} (deleted or on another pod); asking again.`);
+            botToken = await resolveBotToken(undefined);
+        }
+    }
+    else {
+        botToken = await resolveBotToken(undefined);
+    }
+    const { vaultRef, secretId, error: capabilityError } = await applyBridgeCapability(bridgeDir, workspaceId, cfg, botToken, reuseVaultRef);
     // ── 4. Choose agent governance mode ──────────────────────────────────
     const discordAgentUserId = getSurfaceAgentKey("discord")?.agentUserId;
     if (discordAgentUserId) {
-        await ensureAgentGovernance(cfg, discordAgentUserId, opts.governance);
+        // A re-run leaves the agent's governance exactly as the operator set it.
+        // (The pod exposes no GET for it, so we say "unchanged" — never claim a
+        // specific mode we did not read.)
+        if (!opts.governance && !reconfigure && prior.bridgeProvisioned) {
+            log.dim("  [skip] governance — left unchanged from your previous run " +
+                "(--governance safe|normal|crazy, or --reconfigure, to change it)");
+        }
+        else {
+            await ensureAgentGovernance(cfg, discordAgentUserId, opts.governance);
+        }
     }
     // ── 4b. Seed the bundled instruction skills FIRST, then the capabilities ────
-    // Order matters: the `stellar-scf-grants-advisor` skill now ALSO ships embedded
-    // in the stellar-grant-client capability (so a plain `packages/apply` install
-    // stands it up with NO bridge-setup). Seeding the bundled SKILL.md dir first
-    // attaches its full reference-doc corpus; the capability apply below then
-    // REUSES that same pod-scoped skill row by name (create-from-definition is
-    // idempotent) instead of creating a docless instruction-only copy.
+    // Order matters: seeding the bundled SKILL.md dirs first attaches their full
+    // reference-doc corpus; a capability apply below that embeds a skill of the
+    // same name REUSES that pod-scoped row (create-from-definition is idempotent)
+    // instead of creating a docless instruction-only copy.
     await applyAgencySkills(cfg);
     // ── 4c. Apply the agency capability templates (idempotent, self-healing) ────
     await applyAgencyCapabilities(cfg, workspaceId);
     // ── 4e. Seed the GENERIC automation templates (idempotent, event-driven) ────
-    // Only the domain-agnostic automations live in templates/automations/ now
-    // (mail-feed, url/bookmark capture). The grant-specific automations
-    // (stellar-grant-provision + proactive-grant-review) SHIP INSIDE the
-    // stellar-grant-client capability's automations[] (seeded above via
-    // applyAgencyCapabilities), so any install door — including a plain
-    // packages/apply with no bridge-setup — stands them up. Thread the operator's
+    // Only the domain-agnostic automations are seeded here (mail-feed,
+    // url/bookmark capture), read from the installed catalog package when it
+    // ships them, else from templates/automations/. The grant operation itself
+    // ships with the `grants` workspace template (its "Grant Process" method +
+    // automations). Thread the operator's
     // chosen proactive channel through — output nodes pin their post target with it
     // when it's a Synap channels.id (see the note in applyAutomationTemplates).
     await applyAutomationTemplates(cfg, workspaceId, opts.proactiveChannel);
@@ -219,16 +372,22 @@ export async function bridgeSetup(opts) {
         await setDiscordToolConfig(cfg, workspaceId, { reactCapture: true });
     }
     // ── 4d. Grant the bridge redeem access — token lives ONLY in the vault ─────
+    // Re-run path: `secretId` is recovered from the .env vault ref, so the grant
+    // is re-verified (it answers "(existing)") WITHOUT the token being re-entered.
     let granted = false;
-    if (secretId && botToken) {
+    if (secretId) {
         // Grant to the AGENT (the bridge's redeem identity), not the operator.
         const agentUserId = getSurfaceAgentKey("discord")?.agentUserId;
         granted = await grantRedeemAccess(secretId, cfg, agentUserId);
     }
     // ── 5. Proactive delivery routing (optional) ─────────────────────────────
-    if (opts.proactiveChannel) {
+    // Delivery preferences live ON a workspace — pod-wide has none to route to.
+    if (opts.proactiveChannel && workspaceId) {
         await configureProactive(workspaceId, opts.proactiveChannel, cfg);
     }
+    else if (opts.proactiveChannel) {
+        log.warn("Proactive routing needs a workspace — pass --workspace-id to enable it.");
+    }
     // ── 6. Write the bridge .env ─────────────────────────────────────────────
     const envPath = path.join(bridgeDir, ".env");
     const managed = {
@@ -237,12 +396,14 @@ export async function bridgeSetup(opts) {
         // the operator's raw key. Reads remap to the operator floor; writes are
         // governed as the agent.
         SYNAP_HUB_API_KEY: agentKey,
-        SYNAP_WORKSPACE_ID: workspaceId,
     };
-    // Project is a peer lens to workspace — only injected when the resolved
-    // config carries one (e.g. via the durable `activeProjectId` or session lens).
-    if (cfg.projectId)
-        managed.SYNAP_PROJECT_ID = cfg.projectId;
+    // Pod-wide by default: SYNAP_WORKSPACE_ID/SYNAP_PROJECT_ID are only written
+    // when the operator explicitly pinned a workspace (--workspace-id) or chose
+    // a project in the picker. Neither is required.
+    if (workspaceId)
+        managed.SYNAP_WORKSPACE_ID = workspaceId;
+    if (projectId)
+        managed.SYNAP_PROJECT_ID = projectId;
     // The token is NEVER written to .env — it lives in the pod vault and the
     // bridge redeems it on boot via this ref. (Requires the grant below to land;
     // if it didn't, we warn loudly rather than leaking the token to env.)
@@ -253,8 +414,15 @@ export async function bridgeSetup(opts) {
     if (opts.proactiveChannel)
         managed.SYNAP_PROACTIVE_CHANNEL_ID = opts.proactiveChannel;
     try {
-        // Once the token is in the vault, purge any stale env copy of it.
-        upsertEnv(envPath, managed, vaultRef ? ["DISCORD_BOT_TOKEN"] : []);
+        // Once the token is in the vault, purge any stale env copy of it. Also
+        // purge a stale scope pin from a prior run — re-running pod-wide (no
+        // --workspace-id / no project picked) must actually clear an old pin.
+        const removeKeys = [
+            ...(vaultRef ? ["DISCORD_BOT_TOKEN"] : []),
+            ...(workspaceId ? [] : ["SYNAP_WORKSPACE_ID"]),
+            ...(projectId ? [] : ["SYNAP_PROJECT_ID"]),
+        ];
+        upsertEnv(envPath, managed, removeKeys);
         log.success(`Wrote pod credentials → ${envPath}`);
     }
     catch (err) {
@@ -270,10 +438,12 @@ export async function bridgeSetup(opts) {
     const envHasGuild = fs.existsSync(envPath) &&
         /^DISCORD_GUILD_ID=.+/m.test(fs.readFileSync(envPath, "utf-8"));
     printNextSteps(opts.clientId, bridgeDir, {
-        hasToken: Boolean(botToken),
+        hasToken: Boolean(botToken) || Boolean(reuseVaultRef),
         hasGuild: Boolean(opts.guildId) || envHasGuild,
         vaultRef,
         granted,
+        reusedToken: Boolean(reuseVaultRef),
+        capabilityError,
     });
     await printSynapNextSteps(cfg, workspaceId);
 }
@@ -295,11 +465,6 @@ export async function bridgeSetup(opts) {
 const AGENCY_CAPABILITY_PLAN = [
     { key: "nango-google", needs: null, params: {}, workspaceScoped: false },
     { key: "agency-skills", needs: null, params: {}, workspaceScoped: true },
-    // stellar-grant-client bundles the grant PLAYBOOK, all four grant AUTOMATIONS
-    // (including stellar-grant-provision + proactive-grant-review, moved here from
-    // templates/automations/), and the stellar-scf-grants-advisor SKILL — so one
-    // capability apply stands up the whole grant operation on ANY install door.
-    { key: "stellar-grant-client", needs: null, params: {}, workspaceScoped: true },
     // Cal.com scheduling connector — requires a `calApiKey` param (a `cal_live_...`
     // token), so gate it like the other keyed connectors: skip gracefully unless
     // CALCOM_API_KEY is set. Seeds the `cal_com` tool + booking skills + vault key,
@@ -326,25 +491,6 @@ const AGENCY_CAPABILITY_PLAN = [
         workspaceScoped: false,
     },
 ];
-/**
- * Resolve the automations templates directory — CLI-BUNDLED (like the skills at
- * templates/skills). The backend stays agnostic: it ships no feature templates;
- * automation config is bundled with the CLI that seeds it.
- *
- * Resolution order:
- *   1. AUTOMATION_TEMPLATES_DIR env var (override for CI / custom installs)
- *   2. CLI-bundled default: <cli-package-root>/templates/automations
- */
-function resolveAutomationsTemplatesDir() {
-    if (process.env.AUTOMATION_TEMPLATES_DIR) {
-        const override = process.env.AUTOMATION_TEMPLATES_DIR;
-        return fs.existsSync(override) ? override : null;
-    }
-    const thisFile = fileURLToPath(import.meta.url);
-    const cliRoot = path.resolve(path.dirname(thisFile), "..", "..");
-    const candidate = path.resolve(cliRoot, "templates", "automations");
-    return fs.existsSync(candidate) ? candidate : null;
-}
 /**
  * Apply the agency capability templates idempotently via the Control Plane catalog.
  *
@@ -367,6 +513,12 @@ async function applyAgencyCapabilities(cfg, workspaceId) {
             log.dim(`  [skip] ${item.key} — set ${item.needs} to seed it`);
             continue;
         }
+        // Playbook-bundling capabilities require a workspace to land in — pod-wide
+        // (no --workspace-id) has none, so skip rather than round-trip a known 4xx.
+        if (item.workspaceScoped && !workspaceId) {
+            log.dim(`  [skip] ${item.key} — bundles playbooks; pass --workspace-id to seed it`);
+            continue;
+        }
         try {
             const res = (await hubPost("/capabilities/apply", item.workspaceScoped
                 ? { templateKey: item.key, params: item.params, workspaceId }
@@ -396,19 +548,22 @@ export function resolveBundledSkillsDir() {
     return fs.existsSync(candidate) ? candidate : null;
 }
 /**
- * Seed the bundled Synap-native skills from templates/skills/ (standard SKILL.md
- * directories). Each becomes a pod-wide instruction skill via /agent-skills/import;
- * references/ files become linked documents. Idempotent (slug-unique guard).
+ * Seed the Synap-native skills (standard SKILL.md directories): the agency
+ * skills from the installed catalog package when it ships them, else from
+ * templates/skills/; the CLI runtime skills from templates/skills/. Each becomes
+ * a pod-wide instruction skill via /agent-skills/import; references/ files
+ * become linked documents. Idempotent (slug-unique guard).
  */
 async function applyAgencySkills(cfg) {
-    const skillsDir = resolveBundledSkillsDir();
-    if (!skillsDir) {
+    const catalogRoot = resolveInstalledCatalogRoot();
+    const { dirs, fromCatalog } = resolveAgencySkillDirs({ cliSkillsDir: resolveBundledSkillsDir(), catalogRoot });
+    if (dirs.length === 0) {
         log.warn("Bundled skill templates not found — skipping.");
         return;
     }
     const userId = await resolveUserId(cfg);
-    const dirs = discoverSkillDirs(skillsDir);
-    log.dim(`Seeding ${dirs.length} bundled skill(s) from ${skillsDir}…`);
+    log.dim(`Seeding ${dirs.length} skill(s)` +
+        (fromCatalog.length ? ` (${fromCatalog.length} from ${catalogRoot})` : "") + "…");
     for (const dir of dirs) {
         const parsed = parseSkillDir(dir);
         if (!parsed)
@@ -559,8 +714,8 @@ async function resolveGoogleConnectionId(cfg, workspaceId) {
         const google = containers.find((c) => /google/i.test(c.name ?? ""));
         if (!google?.id)
             return null;
-        const connRes = await hubGet(`/capabilities/${google.id}/connections`, {}, cfg);
-        const conns = unwrapList(connRes, ["connections"]);
+        const connRes = await hubGet(`/capabilities/${google.id}/credentials`, {}, cfg);
+        const conns = unwrapList(connRes, ["credentials"]);
         if (conns.length === 0)
             return null;
         return (conns.find((c) => c.isDefault) ?? conns[0]).id;
@@ -570,7 +725,9 @@ async function resolveGoogleConnectionId(cfg, workspaceId) {
     }
 }
 /**
- * Apply automation templates from the CLI-bundled templates/automations/*.automation.json.
+ * Apply the *.automation.json templates: AUTOMATION_TEMPLATES_DIR when set, else
+ * the installed catalog package's automations/ when it ships them, else the
+ * CLI's templates/automations/.
  *
  * For each file:
  *  - Fill placeholders + validate references in the flowDefinition:
@@ -588,7 +745,11 @@ async function resolveGoogleConnectionId(cfg, workspaceId) {
  *  - Aborts (never partial) if the prerequisite skills/automations fetch fails.
  */
 async function applyAutomationTemplates(cfg, workspaceId, feedChannelId) {
-    const templatesDir = resolveAutomationsTemplatesDir();
+    const templatesDir = resolveAutomationTemplatesDir({
+        override: process.env.AUTOMATION_TEMPLATES_DIR,
+        catalogRoot: resolveInstalledCatalogRoot(),
+        cliDir: path.join(CLI_TEMPLATES_DIR, "automations"),
+    });
     if (!templatesDir) {
         log.warn("Automation templates dir not found — skipping. " +
             "Set AUTOMATION_TEMPLATES_DIR=<path> to seed from a custom location.");
@@ -613,6 +774,32 @@ async function applyAutomationTemplates(cfg, workspaceId, feedChannelId) {
         log.warn(`Could not fetch existing automations — aborting seeding: ${err.message}`);
         return;
     }
+    // Fetch the capability catalog's verb ids once — needed for capability-node
+    // validation. This is a DIFFERENT namespace from `/skills`: a catalog verb's
+    // backing skill need not appear in the `/skills` list at all. Dogfood: the
+    // `ai.generate` verb on "Synap Core" is `enabled: true, runnable: true` and is
+    // what every AI automation node uses, yet its backing skill
+    // (e441519b-…) is absent from all 50 rows `/skills` returns. Validating verbs
+    // against skill NAMES therefore marked every AI automation as missing and
+    // silently skipped it.
+    let catalogVerbIds = new Set();
+    try {
+        const res = await hubGet("/capabilities/catalog", { userId, workspaceId }, cfg);
+        for (const cap of unwrapList(res, [
+            "capabilities",
+        ])) {
+            for (const v of cap.verbs ?? [])
+                if (v.verbId)
+                    catalogVerbIds.add(v.verbId);
+        }
+    }
+    catch (err) {
+        // NON-fatal, unlike the skills fetch: an empty verb set must not skip every
+        // AI automation. Fall back to accepting any verbId and let the runtime be the
+        // judge — a seeded automation that fails loudly beats one silently not seeded.
+        log.warn(`Could not fetch the capability catalog — verb ids will not be pre-validated: ${err.message}`);
+        catalogVerbIds = new Set();
+    }
     // Fetch existing skills once — needed for skill-node injection.
     let existingSkills = [];
     try {
@@ -660,11 +847,16 @@ async function applyAutomationTemplates(cfg, workspaceId, feedChannelId) {
                         missing ??= `skill "${skillName}"`;
                 }
             }
-            // `capability` node → validate verbId (a verb IS a seeded skill NAME) and
-            // fill an empty/placeholder connection id with the Google/Nango connection.
+            // `capability` node → validate verbId against the CAPABILITY CATALOG first
+            // (its real home), falling back to seeded skill names for verbs that are
+            // skill-backed by name. When the catalog could not be fetched the set is
+            // empty and we do not pre-validate at all — see the fetch above.
             if (node.type === "capability") {
                 const data = node.data;
-                if (data.verbId && !existingSkills.some((s) => s.name === data.verbId)) {
+                if (data.verbId &&
+                    catalogVerbIds.size > 0 &&
+                    !catalogVerbIds.has(data.verbId) &&
+                    !existingSkills.some((s) => s.name === data.verbId)) {
                     missing ??= `verb "${data.verbId}"`;
                 }
                 const sel = data.connectionSelector;
@@ -800,9 +992,12 @@ async function applyAutomationTemplates(cfg, workspaceId, feedChannelId) {
  * @param podUrl      Pod base URL.
  * @param operatorKey The operator's raw hub key (authorizes the provisioning).
  * @param workspaceId Workspace to enroll the agent into (omit for all).
+ * @param existingContextPath Path to the CONTEXT.md a previous run already
+ *   wrote — when set, the agent-template wizard is SKIPPED (same reuse-and-say-so
+ *   contract as the agent key itself). Pass null to run it.
  * @returns the Discord agent key to write as SYNAP_HUB_API_KEY.
  */
-async function provisionDiscordAgentKey(podUrl, operatorKey, workspaceId) {
+async function provisionDiscordAgentKey(podUrl, operatorKey, workspaceId, existingContextPath) {
     const spinner = ora("Provisioning Discord agent key…").start();
     let hubApiKey;
     let agentUserId;
@@ -833,44 +1028,67 @@ async function provisionDiscordAgentKey(podUrl, operatorKey, workspaceId) {
     // Enroll the agent user into the operator's workspace(s) using the OPERATOR
     // key (before the bridge ever uses the agent key).
     await enrollAgentIfNeeded(podUrl, operatorKey, agentUserId, workspaceId);
-    // Same CONTEXT.md routing file every other provisioned agent gets.
-    try {
-        await configureAgentContext(podUrl, operatorKey, "discord", agentUserId);
+    // Same CONTEXT.md routing file every other provisioned agent gets — written
+    // once. A re-run keeps the template the operator already picked.
+    if (existingContextPath) {
+        log.dim(`  [skip] agent template — already configured (${existingContextPath}); --reconfigure to pick another`);
     }
-    catch (err) {
-        log.warn(`Agent context wizard failed: ${err instanceof Error ? err.message : String(err)}`);
+    else {
+        try {
+            await configureAgentContext(podUrl, operatorKey, "discord", agentUserId);
+        }
+        catch (err) {
+            log.warn(`Agent context wizard failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
     }
     return hubApiKey;
 }
-async function resolveWorkspaceId(explicit, defaultWs, cfg) {
-    // An explicit --workspace-id wins outright. Otherwise ALWAYS ask (with the
-    // saved profile workspace pre-selected) — the operator must consciously pick
-    // the workspace every channel + entity the bridge creates will live in (e.g.
-    // your CRM workspace), instead of silently inheriting the saved default.
-    if (explicit)
-        return explicit;
-    let list = [];
-    try {
-        const res = (await hubGet("/workspaces", {}, cfg));
-        const arr = unwrapList(res, ["workspaces"]);
-        list = arr.filter((w) => w?.id);
+/**
+ * Resolve the OPTIONAL scope the bridge writes into — pod-wide by default.
+ *
+ * Workspace: an explicit --workspace-id is the only way to pin one (advanced/
+ * legacy escape hatch) — never prompted, never required.
+ *
+ * Project: a peer, independent lens. --project-id skips the prompt; otherwise
+ * offer a picker with "Pod-wide (no project)" as the default alongside the
+ * operator's existing projects. No projects on the pod → skip the prompt.
+ *
+ * Re-run: BOTH lenses are inherited from the bridge's own .env instead of being
+ * re-asked. That also fixes a real re-run defect — re-running without
+ * --workspace-id used to silently UNPIN a bridge that had been pinned (the .env
+ * key is purged), which in turn silently skipped every playbook-bundling
+ * capability. --reconfigure restores the ask-me-everything behaviour.
+ */
+async function resolveScope(opts, cfg, prior, reconfigure) {
+    let workspaceId = opts.workspaceId;
+    if (!workspaceId && !reconfigure && prior.workspaceId) {
+        workspaceId = prior.workspaceId;
+        log.dim(`  [skip] workspace — keeping the pin from your previous run (${workspaceId}); --reconfigure to clear it`);
+    }
+    let projectId = opts.projectId;
+    if (!projectId && !reconfigure && prior.bridgeProvisioned) {
+        projectId = prior.projectId;
+        log.dim(prior.projectId
+            ? `  [skip] project — keeping ${prior.projectId} from your previous run (--project-id or --reconfigure to change)`
+            : "  [skip] project — you chose pod-wide previously; keeping it (--project-id or --reconfigure to change)");
+    }
+    else if (!projectId) {
+        const projects = await fetchProjects(cfg);
+        if (projects.length > 0) {
+            const { picked } = await prompts({
+                type: "select",
+                name: "picked",
+                message: "Which project should the bridge write into? (optional — pod-wide by default)",
+                initial: 0,
+                choices: [
+                    { title: "Pod-wide (no project)", value: "" },
+                    ...projects.map((p) => ({ title: p.name, description: p.id, value: p.id })),
+                ],
+            });
+            projectId = picked || undefined;
+        }
     }
-    catch {
-        return defaultWs;
-    }
-    if (list.length === 0)
-        return defaultWs;
-    if (list.length === 1)
-        return list[0].id;
-    const defaultIdx = defaultWs ? list.findIndex((w) => w.id === defaultWs) : -1;
-    const { ws } = await prompts({
-        type: "select",
-        name: "ws",
-        message: "Which workspace should the bridge write into? (channels + entities land here)",
-        choices: list.map((w) => ({ title: `${w.name ?? "(unnamed)"}  ${chalk.dim(w.id)}`, value: w.id })),
-        initial: defaultIdx >= 0 ? defaultIdx : 0,
-    });
-    return ws || defaultWs;
+    return { workspaceId, projectId };
 }
 async function resolveBotToken(provided) {
     if (provided)
@@ -882,8 +1100,27 @@ async function resolveBotToken(provided) {
     });
     return token || undefined;
 }
-async function applyBridgeCapability(bridgeDir, workspaceId, cfg, botToken) {
+/**
+ * @param existingVaultRef `vault://<id>` from a previous run. When there is no
+ *   NEW token but the credential is already vaulted, the definition is applied
+ *   with the vault entry dropped (we must never store a `{{botToken}}`
+ *   placeholder) while the tools' credentialRef is REPOINTED at the existing
+ *   secret — which is byte-identical to what a token-carrying apply produces,
+ *   since createVaultSecret reuses the same secret id. Without this the re-run
+ *   would strip the tool's credentialRef and break a working bridge.
+ */
+async function applyBridgeCapability(bridgeDir, workspaceId, cfg, botToken, existingVaultRef) {
     const spinner = ora("Provisioning capability…").start();
+    // What we still know about the vaulted credential if the apply can't run —
+    // returning it keeps the .env + grant + summary truthful on a re-run.
+    const reuse = existingVaultRef
+        ? {
+            vaultRef: existingVaultRef,
+            secretId: existingVaultRef.startsWith("vault://")
+                ? existingVaultRef.slice("vault://".length)
+                : undefined,
+        }
+        : {};
     // Read the capability definition from the bridge repo — ONE source of truth.
     const capPath = path.join(bridgeDir, "src", "synapCapabilities.js");
     let rawDef;
@@ -899,11 +1136,11 @@ async function applyBridgeCapability(bridgeDir, workspaceId, cfg, botToken) {
         spinner.fail("Capability definition not found");
         log.dim(`  Looked in: ${capPath}`);
         log.dim(`  ${err.message}`);
-        return {};
+        return { ...reuse, error: `capability definition not found at ${capPath}` };
     }
     if (!rawDef) {
         spinner.fail("No CAPABILITY_DEFINITION export in the bridge");
-        return {};
+        return { ...reuse, error: "no CAPABILITY_DEFINITION export in the bridge" };
     }
     // Deep-clone + inject the bot token into the vault credential. With no token,
     // drop the vault + credentialRef so we never store an empty/placeholder secret.
@@ -916,25 +1153,32 @@ async function applyBridgeCapability(bridgeDir, workspaceId, cfg, botToken) {
         }
     }
     else {
-        // No token → drop the vault and any tool credentialRef that referenced it
-        // (a bare template-local ref or a vault:// string), so we never store a
-        // placeholder secret or leave a dangling reference.
+        // No NEW token → drop the vault entry, so we never store a placeholder
+        // secret. Two cases for the tools that referenced it:
+        //   · re-run (existingVaultRef) → REPOINT at the already-vaulted secret,
+        //     preserving the exact wiring a token-carrying apply would produce.
+        //   · first run with no token   → delete the ref (no dangling reference).
         const vaultRefs = new Set((def.vault ?? []).map((v) => v.ref).filter((r) => Boolean(r)));
         delete def.vault;
         for (const t of def.tools ?? []) {
             if (t.credentialRef &&
                 (vaultRefs.has(t.credentialRef) || t.credentialRef.startsWith("vault://"))) {
-                delete t.credentialRef;
+                if (existingVaultRef)
+                    t.credentialRef = existingVaultRef;
+                else
+                    delete t.credentialRef;
             }
         }
-        spinner.text = "Provisioning capability (no token → structure only)…";
+        spinner.text = existingVaultRef
+            ? "Provisioning capability (token already vaulted → reusing the credential)…"
+            : "Provisioning capability (no token → structure only)…";
     }
     try {
         const res = (await hubPost("/capabilities/apply", { definition: def, workspaceId }, cfg));
         const tools = res.created?.tools?.length ?? 0;
         const skills = res.created?.skills?.length ?? 0;
-        const vaultRef = res.created?.vault?.[0]?.vaultRef;
-        const secretId = res.created?.vault?.[0]?.secretId;
+        const vaultRef = res.created?.vault?.[0]?.vaultRef ?? reuse.vaultRef;
+        const secretId = res.created?.vault?.[0]?.secretId ?? reuse.secretId;
         spinner.succeed(`Capability provisioned: ${res.capabilityKey ?? "?"} (${vaultRef ? "vault + " : ""}${tools} tool, ${skills} skill)`);
         return { vaultRef, secretId };
     }
@@ -942,6 +1186,14 @@ async function applyBridgeCapability(bridgeDir, workspaceId, cfg, botToken) {
         const msg = err.message;
         spinner.fail("Capability apply failed");
         log.error(`  ${msg}`);
+        if (existingVaultRef) {
+            // Re-run: the pod already holds a working credential + tool wiring, so a
+            // failed RE-apply is not fatal — but it is not a "skip" either. Say what
+            // failed, say what was left alone, and carry it into the final summary.
+            log.dim("  The capability was NOT re-applied — the pod's existing wiring is untouched.");
+            log.dim("  Setup continues; nothing below depends on this apply succeeding.");
+            return { ...reuse, error: msg };
+        }
         if (botToken) {
             // The bot token MUST be vaulted for the bridge to run — continuing to write
             // a .env and printing "Done" would leave a crash-looping bridge (redeem
@@ -954,7 +1206,7 @@ async function applyBridgeCapability(bridgeDir, workspaceId, cfg, botToken) {
             }
             process.exit(1);
         }
-        return {};
+        return { ...reuse, error: msg };
     }
 }
 /**
@@ -971,6 +1223,14 @@ async function grantRedeemAccess(secretId, cfg, agentUserId) {
         // with no_grant. Fall back to the operator only if the agent id is unknown.
         const principal = agentUserId || (await resolveUserId(cfg));
         const res = (await hubPost(`/vault/secrets/${secretId}/grant`, { grantedTo: principal, scope: "permanent" }, cfg));
+        if (res.status === "proposed") {
+            // An agent key cannot grant vault access by itself: the pod filed it for
+            // the secret owner's approval. Nothing is granted until it is approved.
+            spinner.warn("Redeem access is waiting for your approval");
+            if (res.reviewUrl)
+                log.dim(`  Approve it: ${res.reviewUrl}`);
+            return false;
+        }
         spinner.succeed(`Redeem access granted${res.reused ? " (existing)" : ""} — token stays in the vault`);
         return Boolean(res.grantId);
     }
@@ -1041,7 +1301,7 @@ function upsertEnv(filePath, kv, remove = []) {
         for (const [k, v] of remaining)
             out.push(`${k}=${v}`);
     }
-    fs.writeFileSync(filePath, out.join("\n"), { mode: 0o600 });
+    writeSecretFile(filePath, out.join("\n"), { mode: 0o600 });
 }
 /**
  * Data-aware "what you must do next INSIDE Synap" — the discoverability layer:
@@ -1079,8 +1339,14 @@ function printNextSteps(clientId, bridgeDir, state) {
     log.blank();
     log.heading("Done");
     log.blank();
-    if (state.vaultRef && state.granted) {
-        console.log(`  ${chalk.green("✓")} Bot token in the pod vault, bridge granted redeem access — no env token  ${chalk.dim(state.vaultRef)}`);
+    if (state.capabilityError) {
+        console.log(`  ${chalk.yellow("⚠")} Capability was not re-applied: ${state.capabilityError}`);
+        console.log(`     Everything else below still ran; the pod's existing capability wiring was left untouched.`);
+    }
+    if (state.vaultRef && state.granted && state.reusedToken) {
+        console.log(`  ${chalk.green("✓")} Bot token reused from the pod vault (never re-entered), redeem access confirmed  ${chalk.dim(state.vaultRef)}`);
+    }
+    else if (state.vaultRef && state.granted) {
     }
     else if (state.vaultRef && state.hasToken) {
         console.log(`  ${chalk.yellow("⚠")} Token stored in the vault (${chalk.dim(state.vaultRef)}) but the redeem GRANT did not land.`);