@cursor/bdk 0.2.1

package/src/internal/convert-automation/convert-workflow.ts

@@ -0,0 +1,1377 @@
+/**
+ * Pure Workflow → BDK project converter.
+ *
+ * Maps an exported Cursor automation (proto3 workflow JSON + enriched MCP
+ * server list) to project files, warnings, and setup steps. No I/O, no
+ * clock — `exportedAt` comes from the caller.
+ */
+
+import { envPrefixFromName } from "../../channels/slack/credentials.js";
+import { CLI_COMMAND_NAME, PACKAGE_NAME } from "../distribution.js";
+import { MEMORY_TS } from "../init-scaffold.js";
+import { CANONICAL_PROJECT_ROOT, projectPath, type ProjectRoot } from "../project-layout.js";
+import { SlugRegistry, slugify } from "./slug.js";
+import type {
+  ActionJson,
+  ConvertedFile,
+  ConvertedMcpConnection,
+  ConvertMcpServer,
+  ConvertWorkflowInput,
+  ConvertWorkflowResult,
+  GitTriggerJson,
+  PromptJson,
+  SlackActionJson,
+  SlackChannelsTriggerJson,
+  SlackWatchTriggerJson,
+  TriggerJson,
+  WorkflowJson,
+} from "./types.js";
+
+/** Mutable result the emitters append to (also the returned value). */
+interface ConvertOutput {
+  projectRoot: ProjectRoot;
+  files: ConvertedFile[];
+  warnings: string[];
+  setupSteps: string[];
+  mcpConnections: ConvertedMcpConnection[];
+}
+
+export function convertWorkflow(input: ConvertWorkflowInput): ConvertWorkflowResult {
+  const { automation, workflow, mcpServers, exportedAt } = input;
+  const projectRoot = input.projectRoot ?? CANONICAL_PROJECT_ROOT;
+  const out: ConvertOutput = {
+    projectRoot,
+    files: [],
+    warnings: [],
+    setupSteps: [],
+    mcpConnections: [],
+  };
+
+  if (workflow.managedConfig) {
+    out.warnings.push(
+      "This is a Cursor-managed automation: its behavior lives in managed configuration that is not exported. The exported project will NOT reproduce what this automation does.",
+    );
+  }
+
+  // Pin the model the prompt actually ran with; the workflow-level model is
+  // only a fallback. Silently swapping models changes cost and behavior.
+  const promptModel = workflow.prompts?.[0]?.model;
+  const pinnedModel =
+    promptModel !== undefined && promptModel !== "" ? promptModel : workflow.model;
+  if (
+    promptModel !== undefined &&
+    promptModel !== "" &&
+    workflow.model !== undefined &&
+    workflow.model !== "" &&
+    promptModel !== workflow.model
+  ) {
+    out.warnings.push(
+      `The automation ran its prompt with model ${JSON.stringify(promptModel)} (pinned in ${projectPath(projectRoot, "agent.ts")}); its workflow-level default was ${JSON.stringify(workflow.model)}.`,
+    );
+  }
+
+  out.files.push({
+    path: projectPath(projectRoot, "instructions.md"),
+    contents: renderInstructions(automation, workflow, exportedAt, out.warnings, projectRoot),
+  });
+  out.files.push({
+    path: projectPath(projectRoot, "agent.ts"),
+    contents: renderAgentTs(automation, workflow, pinnedModel),
+  });
+
+  const triggers = workflow.triggers ?? [];
+  const scheduleSlugs = new SlugRegistry();
+  const channelSlugs = new SlugRegistry();
+
+  const gitTriggers: TriggerJson[] = [];
+  const slackTriggers: TriggerJson[] = [];
+  const boilerplate: Array<{ trigger: TriggerJson; kind: BoilerplateKind }> = [];
+
+  for (const trigger of triggers) {
+    if (trigger.cron !== undefined) {
+      emitSchedule(automation, trigger, scheduleSlugs, out);
+    } else if (trigger.git !== undefined) {
+      gitTriggers.push(trigger);
+    } else if (isSlackTrigger(trigger)) {
+      slackTriggers.push(trigger);
+    } else {
+      const kind = boilerplateKind(trigger);
+      if (kind === undefined) {
+        out.warnings.push(
+          `Unrecognized trigger (keys: ${Object.keys(trigger).join(", ") || "none"}) was skipped — export it manually.`,
+        );
+      } else {
+        boilerplate.push({ trigger, kind });
+      }
+    }
+  }
+
+  if (gitTriggers.length > 0) {
+    emitGithubChannel(automation, workflow, gitTriggers, channelSlugs, out);
+  }
+  if (slackTriggers.length > 0) {
+    emitSlackChannel(automation, slackTriggers, channelSlugs, out);
+  }
+  for (const { trigger, kind } of boilerplate) {
+    emitBoilerplateChannel(automation, trigger, kind, channelSlugs, out);
+  }
+
+  emitMcpConnections(automation, mcpServers, out);
+  const hasSlackAction = (workflow.actions ?? []).some(
+    action => action.slack !== undefined || action.readSlack !== undefined,
+  );
+  const hasSlackConnection = hasSlackAction && emitSlackAccountConnection(automation, out);
+
+  if (workflow.memoryEnabled === true) {
+    out.files.push({
+      path: projectPath(projectRoot, "hooks/memory.ts"),
+      contents: MEMORY_TS,
+    });
+  }
+
+  out.setupSteps.push(
+    ...behaviorSteps(
+      workflow,
+      out.warnings,
+      {
+        hasSlackChannel: slackTriggers.length > 0,
+        hasSlackConnection,
+      },
+      projectRoot,
+    ),
+  );
+  out.setupSteps.push(
+    `Disable the source automation before deploying this agent so both do not fire on the same events: ${automation.webUrl}${automation.enabled ? "" : " (it is currently disabled — keep it that way)"}`,
+  );
+
+  return out;
+}
+
+// ============================================================================
+// instructions.md
+// ============================================================================
+
+function renderInstructions(
+  automation: ConvertWorkflowInput["automation"],
+  workflow: WorkflowJson,
+  exportedAt: string,
+  warnings: string[],
+  projectRoot: ProjectRoot,
+): string {
+  const header = [
+    "<!--",
+    `  Exported from Cursor automation "${commentSafe(automation.name)}"`,
+    `  uuid: ${commentSafe(automation.uuid)}`,
+    `  source: ${commentSafe(automation.webUrl)}`,
+    `  exported: ${commentSafe(exportedAt)}`,
+    "-->",
+  ].join("\n");
+
+  const prompts = workflow.prompts ?? [];
+  if (prompts.length === 0) {
+    warnings.push(
+      `The source automation has no prompts — ${projectPath(projectRoot, "instructions.md")} contains a placeholder.`,
+    );
+    return `${header}\n\nTODO: the source automation had no prompt text. Write this agent's instructions.\n`;
+  }
+  // Prompt chaining was internal-only and never shipped; export the first
+  // prompt and warn if a legacy row somehow carries more.
+  if (prompts.length > 1) {
+    warnings.push(
+      `The source automation has ${prompts.length} prompts (a legacy internal feature); only the first was exported to ${projectPath(projectRoot, "instructions.md")}.`,
+    );
+  }
+  const prompt = prompts[0];
+  const meta = promptMeta(prompt);
+  const heading = meta === "" ? "" : `<!-- ${meta} -->\n\n`;
+  return `${header}\n\n${heading}${sanitizePromptText(prompt.prompt ?? "", warnings, projectRoot)}\n`;
+}
+
+/**
+ * Strip Cursor-backend prompt markup that means nothing in BDK:
+ * `@[label](action:...)` action tokens become their label text, and
+ * unresolvable `%%INLINECODE<n>%%` storage placeholders are flagged (their
+ * content is not in the export).
+ */
+function sanitizePromptText(text: string, warnings: string[], projectRoot: ProjectRoot): string {
+  let sanitized = text;
+  if (/@\[[^\]]*\]\(action:[^)]*\)/.test(sanitized)) {
+    warnings.push(
+      "The prompt referenced Cursor automation actions (@[...](action:...)); the tokens were replaced with their label text. Wire the equivalent channel/connection (see setup steps) to restore the behavior.",
+    );
+    sanitized = sanitized.replace(/@\[([^\]]*)\]\(action:[^)]*\)/g, "$1");
+  }
+  if (/%%INLINECODE\d+%%/.test(sanitized)) {
+    warnings.push(
+      `${projectPath(projectRoot, "instructions.md")} contains unresolved %%INLINECODE<n>%% placeholders from Cursor's prompt storage — open the automation in the dashboard and paste the original snippet back in.`,
+    );
+  }
+  return sanitized;
+}
+
+const EFFORT_LABELS: Record<string, string> = {
+  PROMPT_EFFORT_LEVEL_STANDARD: "standard",
+  1: "standard",
+  PROMPT_EFFORT_LEVEL_HARD: "hard",
+  10: "hard",
+};
+
+function promptMeta(prompt: PromptJson): string {
+  const parts: string[] = [];
+  const effort = EFFORT_LABELS[String(prompt.effortLevel)];
+  if (effort !== undefined && effort !== "standard") {
+    parts.push(`effort: ${effort}`);
+  }
+  if (prompt.model !== undefined && prompt.model !== "") {
+    parts.push(`model: ${prompt.model}`);
+  }
+  return parts.join("; ");
+}
+
+// ============================================================================
+// agent.ts
+// ============================================================================
+
+function renderAgentTs(
+  automation: ConvertWorkflowInput["automation"],
+  workflow: WorkflowJson,
+  pinnedModel: string | undefined,
+): string {
+  const comments: string[] = [
+    `// Exported from Cursor automation "${commentSafe(automation.name)}"`,
+    `// ${commentSafe(automation.webUrl)}`,
+  ];
+  if (workflow.gitConfig !== undefined) {
+    comments.push("// git_config (repo/branch the automation worked in):");
+    comments.push(...jsonComment(workflow.gitConfig));
+  }
+  if (workflow.agentOptions !== undefined) {
+    comments.push("// agent_options:");
+    comments.push(...jsonComment(workflow.agentOptions));
+  }
+  const body =
+    pinnedModel !== undefined && pinnedModel !== ""
+      ? `export default defineAgent({\n  model: ${JSON.stringify(pinnedModel)},\n});`
+      : "export default defineAgent({\n  // The source automation used Cursor's default model.\n});";
+  return `import { defineAgent } from "${PACKAGE_NAME}";\n\n${comments.join("\n")}\n${body}\n`;
+}
+
+// ============================================================================
+// Schedules (cron triggers)
+// ============================================================================
+
+function emitSchedule(
+  automation: ConvertWorkflowInput["automation"],
+  trigger: TriggerJson,
+  slugs: SlugRegistry,
+  out: ConvertOutput,
+): void {
+  const cron = trigger.cron?.cron;
+  if (cron === undefined || cron === "") {
+    out.warnings.push("A cron trigger had no cron expression and was skipped.");
+    return;
+  }
+  const slug = slugs.claim(slugify(automation.name, "schedule"));
+  const path = projectPath(out.projectRoot, `schedules/${slug}.ts`);
+  const lines = [
+    `import { defineSchedule } from "${PACKAGE_NAME}/schedules";`,
+    "",
+    `// Exported from Cursor automation "${commentSafe(automation.name)}" cron trigger.`,
+    "// Cron is evaluated in UTC in both systems.",
+    "export default defineSchedule({",
+    `  cron: ${JSON.stringify(cron)},`,
+    "  markdown:",
+    `    "Scheduled run: follow the instructions in ${projectPath(out.projectRoot, "instructions.md")}.",`,
+    "});",
+    "",
+  ];
+  out.files.push({ path, contents: lines.join("\n") });
+}
+
+// ============================================================================
+// GitHub channel (git triggers)
+// ============================================================================
+
+const GIT_EVENT_WEBHOOKS: Record<string, string[]> = {
+  pullRequest: ["pull_request"],
+  push: ["push"],
+  ciCompleted: ["check_suite"],
+  issueLabeled: ["issues"],
+  label: [],
+  issueComment: ["issue_comment"],
+  pullRequestReviewComment: ["pull_request_review_comment"],
+  pullRequestReview: ["pull_request_review"],
+  reviewThread: ["pull_request_review_thread"],
+  workflowRun: ["workflow_run"],
+  pullRequestReviewRequested: ["pull_request"],
+  issueAssigned: ["issues"],
+};
+
+/**
+ * `pr.action`-based dispatch condition for one pull_request trigger,
+ * mirroring the backend matcher (`webhookHandler.ts`): OPENED is non-draft
+ * opened-or-ready-for-review; UNSPECIFIED is the legacy opened-or-synchronize
+ * gated by `only_once`; `ignore_draft_prs` applies per trigger.
+ */
+function prConditionFor(
+  prAction: string,
+  eventObject: Record<string, unknown>,
+): string | undefined {
+  const ignoreDrafts = eventObject.ignoreDraftPrs === true;
+  switch (prAction) {
+    case "GIT_PULL_REQUEST_ACTION_UNSPECIFIED": {
+      const base =
+        eventObject.onlyOnce === true
+          ? 'pr.action === "opened"'
+          : '(pr.action === "opened" || pr.action === "synchronize")';
+      return `(${base}${ignoreDrafts ? " && !pr.draft" : ""})`;
+    }
+    case "GIT_PULL_REQUEST_ACTION_OPENED":
+      return '((pr.action === "opened" || pr.action === "ready_for_review") && !pr.draft)';
+    case "GIT_PULL_REQUEST_ACTION_PUSHED":
+      return ignoreDrafts
+        ? '(pr.action === "synchronize" && !pr.draft)'
+        : '(pr.action === "synchronize")';
+    case "GIT_PULL_REQUEST_ACTION_MERGED":
+      return '(pr.action === "closed" && pr.merged)';
+    case "GIT_PULL_REQUEST_ACTION_DRAFT_OPENED":
+      return '(pr.action === "opened" && pr.draft)';
+    case "GIT_PULL_REQUEST_ACTION_LABELED":
+      return '(pr.action === "labeled")';
+    case "GIT_PULL_REQUEST_ACTION_UNLABELED":
+      return '(pr.action === "unlabeled")';
+    default:
+      return undefined;
+  }
+}
+const PR_ACTION_NUMBERS: Record<string, string> = {
+  0: "GIT_PULL_REQUEST_ACTION_UNSPECIFIED",
+  1: "GIT_PULL_REQUEST_ACTION_OPENED",
+  2: "GIT_PULL_REQUEST_ACTION_PUSHED",
+  3: "GIT_PULL_REQUEST_ACTION_MERGED",
+  4: "GIT_PULL_REQUEST_ACTION_COMMENTED",
+  5: "GIT_PULL_REQUEST_ACTION_DRAFT_OPENED",
+  6: "GIT_PULL_REQUEST_ACTION_LABELED",
+  7: "GIT_PULL_REQUEST_ACTION_UNLABELED",
+};
+
+function emitGithubChannel(
+  automation: ConvertWorkflowInput["automation"],
+  workflow: WorkflowJson,
+  triggers: TriggerJson[],
+  slugs: SlugRegistry,
+  out: ConvertOutput,
+): void {
+  const slug = slugs.claim("github");
+  const path = projectPath(out.projectRoot, `channels/${slug}.ts`);
+  const webhookEvents: string[] = [];
+  const repos: string[] = [];
+  let hasOrgs = false;
+
+  // Mechanical filters recovered from the triggers, turned into real hooks
+  // below so the exported channel dispatches on the same events the
+  // automation did instead of shipping inert.
+  const prConditions: string[] = [];
+  let hasCommentedAction = false;
+  let hasIssueCommentTrigger = false;
+  // COMMENTED / review-comment triggers whose backend gates (PR-author
+  // provenance via user_allowlist, commenter_allowlist, comment_contains)
+  // cannot be reproduced by an onComment hook.
+  let commentGatesLost = false;
+  let hasUnknownPrAction = false;
+  const pushBranches: string[] = [];
+  let hasCheckSuite = false;
+  let hasWorkflowRun = false;
+  const issueActions: string[] = [];
+  const userAllowlist: string[] = [];
+
+  for (const trigger of triggers) {
+    const git = trigger.git as GitTriggerJson;
+    userAllowlist.push(...(git.userAllowlist ?? []).filter(user => user !== ""));
+    for (const [eventKey, events] of Object.entries(GIT_EVENT_WEBHOOKS)) {
+      const event = git[eventKey as keyof GitTriggerJson];
+      if (event === undefined || typeof event !== "object") {
+        continue;
+      }
+      webhookEvents.push(...events);
+      const eventObject = event as Record<string, unknown>;
+      if (eventKey === "pullRequest") {
+        const raw = String(eventObject.prAction ?? "");
+        const prAction =
+          PR_ACTION_NUMBERS[raw] ?? (raw === "" ? "GIT_PULL_REQUEST_ACTION_UNSPECIFIED" : raw);
+        if (prAction === "GIT_PULL_REQUEST_ACTION_COMMENTED") {
+          webhookEvents.push("issue_comment");
+          hasCommentedAction = true;
+          if (
+            (git.userAllowlist ?? []).length > 0 ||
+            (Array.isArray(eventObject.commenterAllowlist) &&
+              eventObject.commenterAllowlist.length > 0) ||
+            (typeof eventObject.commentContains === "string" && eventObject.commentContains !== "")
+          ) {
+            commentGatesLost = true;
+          }
+        } else {
+          const condition = prConditionFor(prAction, eventObject);
+          if (condition === undefined) {
+            hasUnknownPrAction = true;
+            out.warnings.push(
+              `A PR trigger${repoLabel(eventObject)} used unrecognized pr_action ${JSON.stringify(raw)} — add its dispatch condition to onPullRequest in ${path} (exported fail-closed).`,
+            );
+          } else {
+            prConditions.push(condition);
+          }
+        }
+      }
+      if (eventKey === "pullRequestReviewRequested") {
+        prConditions.push('(pr.action === "review_requested")');
+      }
+      if (eventKey === "issueComment") {
+        hasIssueCommentTrigger = true;
+        // A separate commenter_allowlist means BOTH lists must pass
+        // (intersection), and comment_contains filters the body — neither
+        // fits the single exported commenter gate.
+        if (
+          (Array.isArray(eventObject.commenterAllowlist) &&
+            eventObject.commenterAllowlist.length > 0) ||
+          (typeof eventObject.commentContains === "string" && eventObject.commentContains !== "")
+        ) {
+          commentGatesLost = true;
+        }
+      }
+      if (eventKey === "pullRequestReviewComment") {
+        // user_allowlist gates the PR author and commenter_allowlist the
+        // commenter here — neither identity is visible to onComment — and
+        // comment_contains filters the body.
+        if (
+          (git.userAllowlist ?? []).length > 0 ||
+          (Array.isArray(eventObject.commenterAllowlist) &&
+            eventObject.commenterAllowlist.length > 0) ||
+          (typeof eventObject.commentContains === "string" && eventObject.commentContains !== "")
+        ) {
+          commentGatesLost = true;
+        }
+      }
+      if (eventKey === "push") {
+        if (typeof eventObject.branch === "string" && eventObject.branch !== "") {
+          pushBranches.push(eventObject.branch);
+        } else {
+          // The backend matcher rejects push triggers without a branch —
+          // they never fired, so exporting a dispatch would invent runs.
+          out.warnings.push(
+            `A push trigger${repoLabel(eventObject)} had no branch filter and never fired in the backend — exported without a dispatch.`,
+          );
+        }
+      }
+      if (eventKey === "ciCompleted") {
+        hasCheckSuite = true;
+      }
+      if (eventKey === "workflowRun") {
+        hasWorkflowRun = true;
+      }
+      if (eventKey === "issueLabeled") {
+        if (typeof eventObject.labelName === "string" && eventObject.labelName !== "") {
+          // The label-name filter is not visible to the typed hooks, so a
+          // dispatch would fire on EVERY label change.
+          out.warnings.push(
+            `An issue-label trigger filtered on label ${JSON.stringify(eventObject.labelName)}, which the exported hooks cannot check — exported without a dispatch; re-add the filter in an onEvent hook reading the raw payload.`,
+          );
+        } else {
+          // `unlabeled: true` flips the legacy trigger to label removal.
+          issueActions.push(eventObject.unlabeled === true ? "unlabeled" : "labeled");
+        }
+      }
+      if (eventKey === "issueAssigned") {
+        issueActions.push("assigned");
+      }
+      // Review events export fail-closed: the backend gated review/thread
+      // state and PR-author provenance, none of which the export can
+      // reproduce. Without an onEvent hook the SDK drops the deliveries.
+      if (eventKey === "pullRequestReview" || eventKey === "reviewThread") {
+        out.warnings.push(
+          `A ${eventKey === "pullRequestReview" ? "pull_request_review" : "review_thread"} trigger exported without a dispatch: the backend's review-state and PR-author provenance gates cannot be exported. Add an onEvent hook in ${path} to re-enable it with your own filters.`,
+        );
+      }
+      if (typeof eventObject.repo === "string" && eventObject.repo !== "") {
+        repos.push(eventObject.repo);
+      }
+      if (Array.isArray(eventObject.repos)) {
+        repos.push(
+          ...eventObject.repos.filter(
+            (repo): repo is string => typeof repo === "string" && repo !== "",
+          ),
+        );
+      }
+      if (Array.isArray(eventObject.orgs) && eventObject.orgs.length > 0) {
+        hasOrgs = true;
+      }
+    }
+    const label = git.label;
+    if (label !== undefined) {
+      const labelObject = label as Record<string, unknown>;
+      // The backend fires only for the configured direction(s); neither
+      // flag set means the trigger never fired.
+      let labelActions = [
+        ...(labelObject.onAdded === true ? ["labeled"] : []),
+        ...(labelObject.onRemoved === true ? ["unlabeled"] : []),
+      ];
+      if (labelActions.length === 0) {
+        out.warnings.push(
+          "A label trigger had neither on_added nor on_removed set and never fired in the backend — exported without a dispatch.",
+        );
+      }
+      if (typeof labelObject.labelName === "string" && labelObject.labelName !== "") {
+        // Label names are not visible to the typed hooks; dispatching would
+        // fire on EVERY label change instead of the filtered one.
+        out.warnings.push(
+          `A label trigger filtered on label ${JSON.stringify(labelObject.labelName)}, which the exported hooks cannot check — exported without a dispatch; re-add the filter in a hook reading the raw payload.`,
+        );
+        labelActions = [];
+      }
+      if (label.pullRequests === true || label.issues !== true) {
+        webhookEvents.push("pull_request");
+        prConditions.push(
+          ...labelActions.map(action => `(pr.action === ${JSON.stringify(action)})`),
+        );
+      }
+      if (label.issues === true) {
+        webhookEvents.push("issues");
+        issueActions.push(...labelActions);
+      }
+    }
+  }
+  if (workflow.gitConfig?.repo !== undefined && workflow.gitConfig.repo !== "") {
+    repos.push(workflow.gitConfig.repo);
+  }
+  repos.push(...(workflow.gitConfig?.repos ?? []));
+
+  const uniqueEvents = dedupe(webhookEvents);
+  const uniqueRepos = dedupe(
+    dedupe(repos.filter(repo => repo !== "")).flatMap(repo => {
+      const normalized = normalizeRepoIdentifier(repo, out);
+      return normalized === undefined ? [] : [normalized];
+    }),
+  );
+
+  if (hasOrgs) {
+    out.warnings.push(
+      `A git trigger watched whole GitHub orgs; the GitHub channel's cursorAccount scope needs explicit repos. List them in ${path}.`,
+    );
+  }
+  out.setupSteps.push(
+    `Review the generated hook filters in ${path} — mechanical trigger filters (PR action, push branch, issue action, user allowlist) were exported, but bespoke conditions Cursor's backend enforced (comment matching, CI conclusions, label names) must be re-added by hand.`,
+  );
+  if (hasCheckSuite || hasWorkflowRun) {
+    out.warnings.push(
+      `A CI trigger (ci_completed / workflow_run) exported FAIL-CLOSED: its backend filters (conclusion, branch, actor allowlist) cannot be exported, so the generated hook in ${path} returns null until you re-add them and dispatch.`,
+    );
+  }
+  if (uniqueRepos.length === 0) {
+    out.setupSteps.push(
+      `No repositories could be derived for the GitHub channel — set githubChannel({ cursorAccount: { repos: [...] } }) or GitHub App credentials in ${path}.`,
+    );
+  }
+
+  const configLines: string[] = [];
+  if (uniqueRepos.length > 0) {
+    configLines.push("  cursorAccount: {");
+    configLines.push(`    repos: [${uniqueRepos.map(repo => JSON.stringify(repo)).join(", ")}],`);
+    configLines.push("  },");
+  }
+  configLines.push(
+    `  webhookEvents: [${uniqueEvents.map(event => JSON.stringify(event)).join(", ")}],`,
+  );
+
+  const uniqueAllowlist = dedupe(userAllowlist.map(user => user.toLowerCase()));
+  if (triggers.length > 1 && uniqueAllowlist.length > 0) {
+    out.warnings.push(
+      `user_allowlist applies per trigger in the backend; the export unions every trigger's allowlist across all hooks in ${path} — tighten per hook if the triggers differed.`,
+    );
+  }
+  // The cursorAccount SCM-event relay delivers PR/comment snapshots only —
+  // no push ref, no issue payload, no CI nodes, and no sender for
+  // non-comment events — so hooks needing those fields only work with a
+  // real GitHub App webhook or `github forward`.
+  const relayLimited = [
+    ...(dedupe(pushBranches).length > 0 ? ["push branch filters"] : []),
+    ...(dedupe(issueActions).length > 0 ? ["issue triggers"] : []),
+    ...(hasCheckSuite || hasWorkflowRun ? ["CI triggers"] : []),
+  ];
+  if (uniqueRepos.length > 0 && relayLimited.length > 0) {
+    out.warnings.push(
+      `cursorAccount event delivery carries PR/comment data only, so ${relayLimited.join(", ")} will NOT fire through it — deliver real GitHub webhooks to the deployed agent (GitHub App or \`github forward\`) for those triggers.`,
+    );
+  }
+
+  const hasCommentEvents =
+    uniqueEvents.includes("issue_comment") || uniqueEvents.includes("pull_request_review_comment");
+  const commentGate: CommentGate = !hasCommentEvents
+    ? "none"
+    : commentGatesLost
+      ? "failClosed"
+      : hasIssueCommentTrigger && uniqueAllowlist.length > 0
+        ? "commenterAllowlist"
+        : "mentionDefault";
+  if (commentGate === "failClosed") {
+    out.warnings.push(
+      `A comment trigger's backend gates (PR-author provenance via user_allowlist, commenter_allowlist, comment_contains) cannot be exported — comments dispatch NOTHING until you re-add them in onComment in ${path}.`,
+    );
+  }
+
+  const { constLines, hookLines, usesAuth } = renderGithubHooks({
+    prConditions: dedupe(prConditions),
+    hasUnknownPrAction,
+    pushBranches: dedupe(pushBranches),
+    hasCheckSuite,
+    hasWorkflowRun,
+    issueActions: dedupe(issueActions),
+    userAllowlist: uniqueAllowlist,
+    hasPullRequestEvents: uniqueEvents.includes("pull_request"),
+    commentGate,
+    hasCommentedAction,
+  });
+  const imports = usesAuth
+    ? "import { defaultGitHubAuth, githubChannel }"
+    : "import { githubChannel }";
+
+  const lines = [
+    `${imports} from "${PACKAGE_NAME}/channels/github";`,
+    "",
+    `// Exported from Cursor automation "${commentSafe(automation.name)}" git trigger(s).`,
+    "// Original trigger config:",
+    ...jsonComment(triggers.map(trigger => trigger.git)),
+    "//",
+    "// The hooks below reproduce the triggers' mechanical filters. Cursor's",
+    "// backend also enforced any bespoke conditions (comment matching, CI",
+    "// conclusions, label names) — re-add those before relying on this.",
+    ...constLines,
+    "export default githubChannel({",
+    ...configLines,
+    ...hookLines,
+    "});",
+    "",
+  ];
+  out.files.push({ path, contents: lines.join("\n") });
+}
+
+type CommentGate = "none" | "mentionDefault" | "commenterAllowlist" | "failClosed";
+
+/** Render the dispatch hooks for {@link emitGithubChannel}. */
+function renderGithubHooks(args: {
+  prConditions: string[];
+  hasUnknownPrAction: boolean;
+  pushBranches: string[];
+  hasCheckSuite: boolean;
+  hasWorkflowRun: boolean;
+  issueActions: string[];
+  userAllowlist: string[];
+  hasPullRequestEvents: boolean;
+  commentGate: CommentGate;
+  hasCommentedAction: boolean;
+}): { constLines: string[]; hookLines: string[]; usesAuth: boolean } {
+  const lines: string[] = [];
+  const hasAllowlist = args.userAllowlist.length > 0;
+  const hasPush = args.pushBranches.length > 0;
+  let allowlistUsed = false;
+  let usesAuth = false;
+
+  if (args.prConditions.length > 0) {
+    lines.push("  onPullRequest: (ctx, pr) => {");
+    if (hasAllowlist) {
+      allowlistUsed = true;
+      lines.push(
+        "    if (",
+        "      pr.authorLogin === undefined ||",
+        "      !ALLOWED_USERS.includes(pr.authorLogin.toLowerCase())",
+        "    ) {",
+        "      return null;",
+        "    }",
+      );
+    }
+    lines.push(
+      "    return (",
+      ...args.prConditions.map(
+        (condition, index) =>
+          `      ${condition}${index < args.prConditions.length - 1 ? " ||" : ""}`,
+      ),
+      "    )",
+      "      ? { auth: defaultGitHubAuth(ctx) }",
+      "      : null;",
+      "  },",
+    );
+    usesAuth = true;
+  } else if (args.hasPullRequestEvents) {
+    // Without this fail-safe the SDK's default gate would dispatch on
+    // opened/reopened/synchronize/ready_for_review — broader than any
+    // exported trigger. COMMENTED triggers get comments via the comment
+    // gate; unrecognized/label-filtered triggers need their condition
+    // re-added here.
+    lines.push("  onPullRequest: () => null,");
+  }
+
+  if (hasPush) {
+    lines.push("  onEvent: (ctx, event) => {");
+    if (hasAllowlist) {
+      allowlistUsed = true;
+      lines.push(
+        "    // The backend gated push on the user allowlist (actor).",
+        "    if (",
+        "      ctx.senderLogin === undefined ||",
+        "      !ALLOWED_USERS.includes(ctx.senderLogin.toLowerCase())",
+        "    ) {",
+        "      return null;",
+        "    }",
+      );
+    }
+    const refs = args.pushBranches.map(branch => JSON.stringify(`refs/heads/${branch}`));
+    lines.push(
+      '    if (event.eventName === "push") {',
+      "      // Branch filter from the original trigger.",
+      "      const ref = (event.payload as { ref?: string }).ref;",
+      refs.length === 1
+        ? `      if (ref !== ${refs[0]}) {`
+        : `      if (ref === undefined || ![${refs.join(", ")}].includes(ref)) {`,
+      "        return null;",
+      "      }",
+      "      return { auth: defaultGitHubAuth(ctx) };",
+      "    }",
+    );
+    usesAuth = true;
+    lines.push("    return null;", "  },");
+  }
+
+  // check_suite / workflow_run only dispatch through their typed hooks —
+  // the onEvent catch-all never sees them. They export FAIL-CLOSED: the
+  // backend filters they relied on (CI conclusion/branch, and for
+  // workflow_run the actor AND triggering-actor allowlist) cannot be
+  // reproduced mechanically, and dispatching unfiltered would let any CI
+  // delivery start an agent turn.
+  if (args.hasCheckSuite) {
+    lines.push(
+      "  onCheckSuite: () => {",
+      "    // Fail closed: re-add the original ci_completed filters —",
+      '    // `suite.action === "completed"`, conclusion/branch, user',
+      "    // allowlist (see the trigger config above) — then dispatch with",
+      "    // `(ctx, suite) => ({ auth: defaultGitHubAuth(ctx) })`.",
+      "    return null;",
+      "  },",
+    );
+  }
+  if (args.hasWorkflowRun) {
+    lines.push(
+      "  onWorkflowRun: () => {",
+      "    // Fail closed: re-add the original workflow_run filters — the",
+      '    // backend required `run.action === "completed"`, a push-origin',
+      "    // same-repo (non-fork) run, and gated the user allowlist on the",
+      "    // run's actor AND triggering actor — then dispatch with",
+      "    // `(ctx, run) => ({ auth: defaultGitHubAuth(ctx) })`.",
+      "    return null;",
+      "  },",
+    );
+  }
+
+  if (args.issueActions.length > 0) {
+    const condition =
+      args.issueActions.length === 1
+        ? `issue.action === ${JSON.stringify(args.issueActions[0])}`
+        : `[${args.issueActions.map(action => JSON.stringify(action)).join(", ")}].includes(issue.action)`;
+    lines.push("  onIssue: (ctx, issue) => {");
+    if (hasAllowlist) {
+      allowlistUsed = true;
+      lines.push(
+        "    // The backend allowlisted the ACTOR (who labeled/assigned),",
+        "    // not the issue author.",
+        "    if (",
+        "      ctx.senderLogin === undefined ||",
+        "      !ALLOWED_USERS.includes(ctx.senderLogin.toLowerCase())",
+        "    ) {",
+        "      return null;",
+        "    }",
+      );
+    }
+    lines.push(`    return ${condition} ? { auth: defaultGitHubAuth(ctx) } : null;`, "  },");
+    usesAuth = true;
+  }
+
+  if (args.commentGate === "failClosed") {
+    lines.push(
+      "  onComment: () => {",
+      "    // Fail closed: the trigger's backend comment gates (PR-author",
+      "    // provenance via user_allowlist, commenter_allowlist,",
+      "    // comment_contains — see the trigger config above) cannot be",
+      "    // exported. Re-add them here (PR author needs a ctx.github",
+      "    // lookup), then return { auth: defaultGitHubAuth(ctx) }.",
+      "    return null;",
+      "  },",
+    );
+  } else if (args.commentGate === "commenterAllowlist" && hasAllowlist) {
+    // issue_comment triggers gate the COMMENTER on user_allowlist — the one
+    // comment gate that is faithfully exportable.
+    allowlistUsed = true;
+    usesAuth = true;
+    lines.push(
+      "  // Replaces the default @mention gate: the original fired on ALL",
+      "  // comments by allowlisted commenters.",
+      "  onComment: (ctx, comment) => {",
+      "    const author = comment.author?.login;",
+      "    if (",
+      "      author === undefined ||",
+      "      !ALLOWED_USERS.includes(author.toLowerCase())",
+      "    ) {",
+      "      return null;",
+      "    }",
+      "    return { auth: defaultGitHubAuth(ctx) };",
+      "  },",
+    );
+  } else if (args.commentGate === "mentionDefault" && lines.length > 0) {
+    lines.push(
+      "  // Comments dispatch via the default @mention gate; the original",
+      "  // fired on ALL comments — declare onComment to widen it.",
+    );
+  }
+
+  const constLines = allowlistUsed
+    ? [
+        "// user_allowlist from the original trigger(s), lowercased — GitHub",
+        "// logins are case-insensitive and the backend compared them that way.",
+        `const ALLOWED_USERS = [${args.userAllowlist.map(user => JSON.stringify(user)).join(", ")}];`,
+        "",
+      ]
+    : [];
+  return { constLines, hookLines: lines, usesAuth };
+}
+
+function repoLabel(eventObject: Record<string, unknown>): string {
+  const repos = dedupe(
+    [
+      typeof eventObject.repo === "string" ? eventObject.repo : "",
+      ...(Array.isArray(eventObject.repos)
+        ? eventObject.repos.filter((repo): repo is string => typeof repo === "string")
+        : []),
+    ].filter(repo => repo !== ""),
+  );
+  return repos.length > 0 ? ` (${repos.join(", ")})` : "";
+}
+
+/**
+ * Normalize a trigger/git_config repo into a GitHub `owner/repo` identifier
+ * for `cursorAccount: { repos: [...] }`. github.com URLs (https or ssh) are
+ * reduced to `owner/repo`; non-GitHub URLs are excluded with a warning;
+ * plain strings pass through.
+ */
+function normalizeRepoIdentifier(raw: string, out: ConvertOutput): string | undefined {
+  let candidate = raw;
+  if (raw.startsWith("git@") && !raw.includes("://")) {
+    // git@host:path SSH shorthand → a parseable ssh:// URL.
+    candidate = `ssh://${raw.replace(":", "/")}`;
+  }
+  if (!candidate.includes("://")) {
+    return raw;
+  }
+  if (!URL.canParse(candidate)) {
+    out.warnings.push(
+      `Repo ${JSON.stringify(raw)} could not be parsed as a URL — excluded from the GitHub channel's cursorAccount repos; list it manually as owner/repo if it is GitHub-hosted.`,
+    );
+    return undefined;
+  }
+  const url = new URL(candidate);
+  const host = url.hostname.toLowerCase();
+  if (host !== "github.com" && host !== "www.github.com") {
+    out.warnings.push(
+      `Repo ${JSON.stringify(raw)} is not GitHub-hosted (host: ${url.hostname}) — excluded from the GitHub channel's cursorAccount repos; cursorAccount can only watch GitHub repositories.`,
+    );
+    // Losing a trigger repo silently halves coverage for dual-host setups,
+    // so surface it as a required setup step, not just a warning.
+    out.setupSteps.push(
+      `Trigger repo ${JSON.stringify(raw)} is not on GitHub, so its events will NOT reach this agent. Re-deliver them yourself (e.g. a webhook to the deployed agent's /v1/channels/github route) or drop that trigger.`,
+    );
+    return undefined;
+  }
+  const segments = url.pathname.split("/").filter(s => s !== "");
+  if (segments.length < 2) {
+    out.warnings.push(
+      `Repo URL ${JSON.stringify(raw)} has no owner/repo path — excluded from the GitHub channel's cursorAccount repos.`,
+    );
+    return undefined;
+  }
+  return `${segments[0]}/${segments[1].replace(/\.git$/, "")}`;
+}
+
+// ============================================================================
+// Slack channel
+// ============================================================================
+
+function isSlackTrigger(trigger: TriggerJson): boolean {
+  return (
+    trigger.slackMention !== undefined ||
+    trigger.slackTrigger !== undefined ||
+    trigger.slackReactionAdded !== undefined ||
+    trigger.slackAnyReactionAdded !== undefined ||
+    trigger.slackChannelCreated !== undefined
+  );
+}
+
+function emitSlackChannel(
+  automation: ConvertWorkflowInput["automation"],
+  triggers: TriggerJson[],
+  slugs: SlugRegistry,
+  out: ConvertOutput,
+): void {
+  const slug = slugs.claim("slack");
+  const path = projectPath(out.projectRoot, `channels/${slug}.ts`);
+
+  const watches = triggers.filter(t => t.slackTrigger !== undefined);
+  const unsupported = triggers.filter(
+    t =>
+      t.slackReactionAdded !== undefined ||
+      t.slackAnyReactionAdded !== undefined ||
+      t.slackChannelCreated !== undefined,
+  );
+  const socketMode = watches.length > 0 || unsupported.length > 0;
+
+  for (const trigger of unsupported) {
+    const kind = trigger.slackChannelCreated !== undefined ? "channel-created" : "reaction-added";
+    out.warnings.push(
+      `Slack ${kind} trigger has no BDK equivalent — its config is inlined as a comment in ${path}; handle the Slack event yourself on a dedicated Socket Mode app.`,
+    );
+  }
+  let reactionDropped = false;
+  for (const watch of watches) {
+    const config = watch.slackTrigger as SlackWatchTriggerJson;
+    if (config.messageContains !== undefined && config.messageContains !== "") {
+      out.warnings.push(
+        `Slack channel-watch message filter (${JSON.stringify(config.messageContains)}) was enforced by Cursor's backend — reimplement it (e.g. onChannelPost) in ${path}.`,
+      );
+    }
+    // The backend defaults a missing/UNSPECIFIED mode to ON (checkmark
+    // reaction); only explicit OFF means no reaction was added.
+    const reactionMode = String(config.slackCompletionReactionMode ?? "");
+    if (reactionMode !== "SLACK_COMPLETION_REACTION_MODE_OFF" && reactionMode !== "2") {
+      reactionDropped = true;
+    }
+  }
+  if (reactionDropped) {
+    out.warnings.push(
+      `The Slack trigger marked triggering messages with a completion reaction; BDK has no completion-reaction option, so that signal is lost unless ${projectPath(out.projectRoot, "instructions.md")} tells the agent to add the reaction itself via Slack tools.`,
+    );
+  }
+  out.setupSteps.push(
+    socketMode
+      ? `Slack channel-watch / reaction / channel-created triggers need a dedicated Socket Mode Slack app: run \`${CLI_COMMAND_NAME} slack create --channel-posts\`, then finish in the dashboard wizard.`
+      : `Slack mentions need a dedicated Socket Mode Slack app: run \`${CLI_COMMAND_NAME} slack create\`, then finish in the dashboard wizard.`,
+  );
+
+  const header = [
+    `import { slackChannel } from "${PACKAGE_NAME}/channels/slack";`,
+    "",
+    `// Exported from Cursor automation "${commentSafe(automation.name)}" Slack trigger(s).`,
+    "// Original trigger config:",
+    ...jsonComment(triggers),
+  ];
+
+  let body: string[];
+  if (socketMode) {
+    const allow = dedupe(watches.flatMap(watch => slackChannelList(watch.slackTrigger)));
+    const anyThreadReplies = watches.some(
+      watch => (watch.slackTrigger as SlackWatchTriggerJson).topLevelOnly === false,
+    );
+    // "Authenticated Cursor users" watches require a linked Cursor account
+    // on the owning team, which bots never have — so the backend blocked
+    // bot posts for them, and the sender gate itself has no SDK equivalent.
+    // The SDK has ONE bot-post setting per channel, so mixed watches must
+    // pick a side: keep bots when any watch allowed everyone (alert /
+    // scorebot watches depend on them), and say so loudly.
+    const blocksUnauthenticated = watches.some(
+      watch =>
+        (watch.slackTrigger as SlackWatchTriggerJson).blockUnauthenticatedSlackUsers === true,
+    );
+    const includeBotPosts =
+      watches.length > 0 &&
+      watches.some(
+        watch =>
+          (watch.slackTrigger as SlackWatchTriggerJson).blockUnauthenticatedSlackUsers !== true,
+      );
+    if (blocksUnauthenticated) {
+      out.warnings.push(
+        includeBotPosts
+          ? "Some Slack watches only fired for authenticated Cursor users while others allowed anyone; BDK has one bot-post setting per channel, so the export keeps bot posts ENABLED (the open watches depend on them) and the authenticated-only watches lose both their sender gate and their bot exclusion. Split the channels or add an onChannelPost gate."
+          : "The Slack trigger only fired for authenticated Cursor users (linked accounts on the owning team); BDK has no equivalent sender gate, so the exported watch dispatches for ANY channel member (bot posts stay excluded). Add an onChannelPost gate in the channel if that matters.",
+      );
+    }
+    const engagement: string[] = [];
+    if (allow.length > 0) {
+      engagement.push("  engagement: {");
+      engagement.push("    channelPosts: {");
+      engagement.push(
+        `      allow: [${allow.map(channel => JSON.stringify(channel)).join(", ")}],`,
+      );
+      if (anyThreadReplies) {
+        engagement.push('      posts: "all",');
+      }
+      if (includeBotPosts) {
+        engagement.push(
+          "      // Cursor's channel-watch dispatched on bot-authored posts",
+          "      // (alerts, scorebots, ...); the SDK drops them by default and",
+          "      // always ignores this agent's own posts.",
+          "      includeBotPosts: true,",
+        );
+      }
+      engagement.push("    },");
+      engagement.push("  },");
+    }
+    body = [
+      "//",
+      `// Run \`${CLI_COMMAND_NAME} slack create --channel-posts\` for a dedicated Slack app.`,
+      ...slackChannelExport(automation.name, engagement),
+    ];
+  } else {
+    body = [
+      "//",
+      `// Run \`${CLI_COMMAND_NAME} slack create\` for a dedicated Slack app.`,
+      ...slackChannelExport(automation.name, []),
+    ];
+  }
+  out.files.push({ path, contents: `${[...header, ...body].join("\n")}\n` });
+}
+
+/**
+ * `slack create` writes `<DIR>_SLACK_*` from the project directory. Convert
+ * names that directory from the automation (`Nightly Triage` →
+ * `nightly-triage` → `NIGHTLY_TRIAGE`). Emit the same prefix so minted
+ * tokens bind.
+ */
+function slackChannelExport(name: string, optionLines: string[]): string[] {
+  const prefix = envPrefixFromName(slugify(name, "automation"));
+  const options = [
+    ...(prefix === "" ? [] : [`  envPrefix: ${JSON.stringify(prefix)},`]),
+    ...optionLines,
+  ];
+  if (options.length === 0) {
+    return ["export default slackChannel();"];
+  }
+  return ["export default slackChannel({", ...options, "});"];
+}
+
+function slackChannelList(trigger: SlackChannelsTriggerJson | undefined): string[] {
+  return [...(trigger?.channels ?? []), trigger?.channel].filter(
+    (channel): channel is string => typeof channel === "string" && channel !== "",
+  );
+}
+
+// ============================================================================
+// Boilerplate webhook channels (Linear / PagerDuty / Sentry / Teams / email / webhook)
+// ============================================================================
+
+type BoilerplateKind = {
+  key:
+    | "linear"
+    | "pagerduty"
+    | "sentry"
+    | "webhook"
+    | "emailReceived"
+    | "microsoftTeamsTrigger"
+    | "microsoftTeamsChannelCreated";
+  slug: string;
+  label: string;
+};
+
+const BOILERPLATE_KINDS: BoilerplateKind[] = [
+  { key: "linear", slug: "linear", label: "Linear" },
+  { key: "pagerduty", slug: "pagerduty", label: "PagerDuty" },
+  { key: "sentry", slug: "sentry", label: "Sentry" },
+  { key: "webhook", slug: "webhook", label: "webhook" },
+  { key: "emailReceived", slug: "email", label: "email received" },
+  {
+    key: "microsoftTeamsTrigger",
+    slug: "teams",
+    label: "Microsoft Teams message",
+  },
+  {
+    key: "microsoftTeamsChannelCreated",
+    slug: "teams-channel-created",
+    label: "Microsoft Teams channel-created",
+  },
+];
+
+function boilerplateKind(trigger: TriggerJson): BoilerplateKind | undefined {
+  return BOILERPLATE_KINDS.find(kind => trigger[kind.key] !== undefined);
+}
+
+function emitBoilerplateChannel(
+  automation: ConvertWorkflowInput["automation"],
+  trigger: TriggerJson,
+  kind: BoilerplateKind,
+  slugs: SlugRegistry,
+  out: ConvertOutput,
+): void {
+  const slug = slugs.claim(kind.slug);
+  const path = projectPath(out.projectRoot, `channels/${slug}.ts`);
+  out.warnings.push(
+    `${kind.label} trigger exported as a boilerplate webhook channel (${path}) — Cursor-managed webhook delivery and event filtering do not carry over.`,
+  );
+  out.setupSteps.push(
+    `Re-register the ${kind.label} webhook against the deployed agent URL (/v1/channels/${slug}) and reimplement event filtering in ${path} — Cursor's backend did both before. The generated route accepts ANY unauthenticated POST and starts a run from it: add auth (e.g. bearerAuth or provider signature verification) before exposing it.`,
+  );
+  const lines = [
+    `import { defineChannel, POST } from "${PACKAGE_NAME}/channels";`,
+    'import { z } from "zod";',
+    "",
+    `// Exported from Cursor automation "${commentSafe(automation.name)}" ${kind.label} trigger.`,
+    "// Original trigger config:",
+    ...jsonComment(trigger[kind.key]),
+    "//",
+    `// TODO: Cursor's backend previously received ${kind.label} webhooks and`,
+    "// applied the filtering above. Re-register the provider webhook against",
+    `// the deployed agent URL (/v1/channels/${slug}) and reimplement the event`,
+    "// filtering in this handler before dispatching.",
+    "export default defineChannel({",
+    "  routes: [",
+    '    POST("/", {',
+    "      bodySchema: z.unknown(),",
+    "      handler: async (_req, { send, body }) => {",
+    "        const session = await send(",
+    "          [",
+    `            "Handle this ${kind.label} event:",`,
+    '            "",',
+    "            JSON.stringify(body, null, 2),",
+    '          ].join("\\n")',
+    "        );",
+    "        return Response.json({ sessionId: session.id });",
+    "      },",
+    "    }),",
+    "  ],",
+    "});",
+    "",
+  ];
+  out.files.push({ path, contents: lines.join("\n") });
+}
+
+// ============================================================================
+// MCP connections
+// ============================================================================
+
+function emitMcpConnections(
+  automation: ConvertWorkflowInput["automation"],
+  mcpServers: ConvertMcpServer[],
+  out: ConvertOutput,
+): void {
+  const slugs = new SlugRegistry();
+  for (const server of mcpServers) {
+    const slug = slugs.claim(slugify(server.name, "mcp-server"));
+    if (server.transportType !== "stdio") {
+      out.mcpConnections.push({ name: slug, kind: "cursorAccount" });
+      const lines = [
+        `import { defineConnection } from "${PACKAGE_NAME}/connections";`,
+        "",
+        `// MCP server "${commentSafe(server.name)}" from Cursor automation "${commentSafe(automation.name)}".`,
+        "// Resolved at runtime through your Cursor account: tools list and",
+        "// execute on the Cursor backend with the account's stored credentials,",
+        "// so no URL or tokens live in this project. Sign this host in",
+        `// (\`${CLI_COMMAND_NAME} login\`) and manage the server's authorization`,
+        "// in Cursor (dashboard -> MCP).",
+        "export default defineConnection({",
+        "  cursorAccount: true,",
+        `  servers: [${JSON.stringify(server.name)}],`,
+        "});",
+        "",
+      ];
+      out.files.push({
+        path: projectPath(out.projectRoot, `mcp-connections/${slug}.ts`),
+        contents: lines.join("\n"),
+      });
+      continue;
+    }
+    out.mcpConnections.push({ name: slug, kind: "stdioStub" });
+    const reason =
+      "it is a stdio server (its command, args, and env stay on Cursor's server). Run the server yourself and point a connection at it.";
+    // A comment-only .ts in mcp-connections/ fails discovery (a connection
+    // module must default-export defineConnection), so the stub is a .md the
+    // framework ignores.
+    const connectionPath = projectPath(out.projectRoot, `mcp-connections/${slug}.ts`);
+    const stubPath = projectPath(out.projectRoot, `mcp-connections/${slug}.todo.md`);
+    out.warnings.push(`MCP server "${server.name}" exported as a stub (${stubPath}): ${reason}`);
+    const lines = [
+      `# TODO: MCP server "${commentSafe(server.name)}"`,
+      "",
+      `The source automation used MCP server "${commentSafe(server.name)}", which could not`,
+      "be exported as a working connection:",
+      "",
+      `- ${reason}`,
+      "",
+      "Credentials are never exported. Once the server is reachable over",
+      `HTTP, create \`${connectionPath}\`:`,
+      "",
+      "```ts",
+      `import { defineConnection } from "${PACKAGE_NAME}/connections";`,
+      "",
+      "export default defineConnection({",
+      '  url: "https://example.com/mcp",',
+      '  oauth: true, // or headers: { authorization: "Bearer <token>" }',
+      "});",
+      "```",
+      "",
+      "This .md file is ignored by the framework; delete it once resolved.",
+      "",
+    ];
+    out.files.push({ path: stubPath, contents: lines.join("\n") });
+  }
+}
+
+/**
+ * The automation posted to / read Slack via Cursor's built-in Slack action;
+ * restore that access with a Cursor-account Slack connection so the exported
+ * agent has Slack tools without any token plumbing. Returns whether the
+ * project ends up with a Slack MCP connection. An MCP server named "slack"
+ * may already have produced an equivalent connection, which counts.
+ */
+function emitSlackAccountConnection(
+  automation: ConvertWorkflowInput["automation"],
+  out: ConvertOutput,
+): boolean {
+  const path = projectPath(out.projectRoot, "mcp-connections/slack.ts");
+  if (out.files.some(file => file.path === path)) {
+    return true;
+  }
+  const lines = [
+    `import { defineConnection } from "${PACKAGE_NAME}/connections";`,
+    "",
+    `// Cursor automation "${commentSafe(automation.name)}" used the built-in Slack action.`,
+    "// This connection restores Slack access through your Cursor account's",
+    "// Slack connector (dashboard -> MCP): tools execute on the Cursor",
+    "// backend with the account's stored credentials.",
+    "export default defineConnection({",
+    "  cursorAccount: true,",
+    '  servers: ["Slack"],',
+    "});",
+    "",
+  ];
+  out.files.push({ path, contents: lines.join("\n") });
+  if (!out.mcpConnections.some(connection => connection.name === "slack")) {
+    out.mcpConnections.push({ name: "slack", kind: "cursorAccount" });
+  }
+  return true;
+}
+
+// ============================================================================
+// Built-in actions → behaviors to verify
+// ============================================================================
+
+function actionSteps(projectRoot: ProjectRoot): Partial<Record<keyof ActionJson, string>> {
+  const instructionsPath = projectPath(projectRoot, "instructions.md");
+  return {
+    gitPr:
+      'Verify: git_pr — the automation auto-opened PRs. Have the agent push and open PRs itself; githubChannel needs permissions: "contents-write" to push code.',
+    prComment: `Verify: pr_comment — githubChannel's default permissions ("pr-write") covers PR comments and reviews; guide comment behavior in ${instructionsPath}.`,
+    manageCheckRun:
+      "Verify: manage_check_run — no built-in equivalent; create/update check runs via ctx.github in a github channel hook.",
+    requestReviewers:
+      "Verify: request_reviewers — no built-in equivalent; request reviewers via ctx.github in a github channel hook.",
+    approvePr: `Verify: approve_pr — PR approval needs githubChannel "pr-write" plus explicit approval guidance in ${instructionsPath}.`,
+    resolveReviewThreads:
+      "Verify: resolve_review_threads — no built-in equivalent; resolve threads via the GitHub GraphQL API in a hook or tool.",
+    microsoftTeams:
+      "Verify: microsoft_teams post — BDK has no Teams channel; wire the Microsoft Teams API yourself.",
+    readMicrosoftTeams:
+      "Verify: read_microsoft_teams — BDK has no Teams tools; wire the Microsoft Teams API yourself.",
+  };
+}
+
+interface SlackIntegrationState {
+  hasSlackChannel: boolean;
+  hasSlackConnection: boolean;
+}
+
+function slackActionStep(
+  action: SlackActionJson,
+  { hasSlackChannel, hasSlackConnection }: SlackIntegrationState,
+  projectRoot: ProjectRoot,
+): string {
+  const channels = dedupe(slackChannelList(action));
+  const target =
+    action.generalized === true
+      ? "any channel (generalized)"
+      : channels.length > 0
+        ? channels.join(", ")
+        : "unspecified channel";
+  if (hasSlackChannel) {
+    return `Verify: slack post (target: ${target}) — the Slack channel replies in the triggering thread; posting to other channels needs Slack tools or a Cursor account MCP connection.`;
+  }
+  if (hasSlackConnection) {
+    return `Verify: slack post (target: ${target}) — ${projectPath(projectRoot, "mcp-connections/slack.ts")} restores Slack through your Cursor account's Slack connector; confirm it is connected in Cursor (dashboard -> MCP) and that ${projectPath(projectRoot, "instructions.md")} names the target channel.`;
+  }
+  return `Verify: slack post (target: ${target}) — the automation posted to Slack, but the exported project has no Slack integration; wire a Slack channel or a Cursor account MCP connection (defineConnection({ cursorAccount: true, servers: ["Slack"] })) to restore it.`;
+}
+
+function behaviorSteps(
+  workflow: WorkflowJson,
+  warnings: string[],
+  slack: SlackIntegrationState,
+  projectRoot: ProjectRoot,
+): string[] {
+  const steps: string[] = [];
+  const knownActionSteps = actionSteps(projectRoot);
+  for (const action of workflow.actions ?? []) {
+    if (action.mcp !== undefined) {
+      continue; // Covered by the exported mcpServers list.
+    }
+    if (action.slack !== undefined) {
+      steps.push(slackActionStep(action.slack, slack, projectRoot));
+      continue;
+    }
+    if (action.readSlack !== undefined) {
+      steps.push(
+        slack.hasSlackConnection
+          ? `Verify: read_slack — Slack read access is available through the generated ${projectPath(projectRoot, "mcp-connections/slack.ts")} (Cursor-account Slack connector).`
+          : 'Verify: read_slack — expose Slack read access via a Cursor account MCP connection (defineConnection({ cursorAccount: true, servers: ["Slack"] })).',
+      );
+      continue;
+    }
+    const step = Object.entries(knownActionSteps).find(
+      ([key]) => action[key as keyof ActionJson] !== undefined,
+    )?.[1];
+    if (step === undefined) {
+      warnings.push(
+        `Unrecognized action (keys: ${Object.keys(action).join(", ") || "none"}) was skipped — verify its behavior manually.`,
+      );
+      continue;
+    }
+    steps.push(step);
+  }
+  const disabled = workflow.disabledDefaultTools ?? [];
+  if (disabled.length > 0) {
+    steps.push(
+      `Verify: disabled_default_tools (${disabled.join(", ")}) — BDK has no default automation tools; enforce the equivalent restriction in ${projectPath(projectRoot, "instructions.md")}.`,
+    );
+  }
+  return steps;
+}
+
+// ============================================================================
+// Shared helpers
+// ============================================================================
+
+/**
+ * Neutralize comment-terminator sequences in server-provided text embedded
+ * in generated comments: JS line terminators (\r, \n, U+2028, U+2029) end a
+ * `//` comment, `-->` ends an HTML comment, and `*` + `/` ends a block
+ * comment. Without this, a crafted automation or MCP server name injects
+ * live code into the generated project.
+ */
+function commentSafe(text: string): string {
+  return text
+    .replace(/[\r\n\u2028\u2029]+/g, " ")
+    .replace(/-->/g, "-- >")
+    .replace(/\*\//g, "* /");
+}
+
+function jsonComment(value: unknown): string[] {
+  // JSON.stringify leaves U+2028/U+2029 raw; both terminate a `//` comment.
+  return JSON.stringify(value, null, 2)
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029")
+    .split("\n")
+    .map(line => `//   ${line}`);
+}
+
+function dedupe(values: string[]): string[] {
+  return [...new Set(values)];
+}