@cursor/july 0.1.109 → 0.1.112

package/dist/docs/guides/convert-automation.md

@@ -1,171 +1,180 @@
 # Convert a Cursor Automation
 
-`convert-automation` exports a dashboard Automation into a local Agent
-SDK project. Use it when you need to edit, test, or deploy the
-Automation as code. Keep using the dashboard if you only need to change
-its prompt or trigger.
+Convert a dashboard Automation when you want to edit its behavior as
+code, test it locally, or deploy it as an Agent SDK project. If you only
+need to change the prompt or trigger, the dashboard remains the shorter
+path.
 
-The converter refuses Cursor-managed Automations because their behavior
-lives in managed configuration. The
-[CLI reference](/docs/reference/cli.md#convert-automation) lists flags and
-exit codes.
+`convert-automation` carries over what it can prove from the exported
+configuration and prints a checklist for everything that still needs
+your judgment.
 
-## Run the conversion
+## Convert and run locally
 
-Sign in before converting. Unlike `init`, this command does not start a
-login flow.
+The command creates a project named after the Automation, installs its
+dependencies, and prints the generated files along with warnings and
+setup steps. Once `dev` starts, you can exercise the converted agent in
+the playground before reconnecting any live trigger.
 
 ```bash
 agent-sdk login
-# or: export CURSOR_API_KEY=key_...
-agent-sdk whoami
+agent-sdk convert-automation \
+  https://cursor.com/automations/0a1b2c3d-0000-1111-2222-333344445555
+
+cd nightly-triage
+agent-sdk validate
+agent-sdk dev
 ```
 
-Pass the Automation's dashboard URL or UUID. The URL must end with
-`/automations/<uuid>` or `/custom-agents/<uuid>`. Do not add path
-segments after the UUID.
+The project includes the Automation's prompt and model plus any
+schedules, channels, and account connections the converter could
+represent directly. The
+[CLI reference](/docs/reference/cli.md#convert-automation) covers custom
+output directories, JSON output, and command failures.
+
+## Reconnect account-backed actions
+
+For an HTTP or SSE MCP server, the converter writes a name-based
+connection instead of copying its URL or credentials. After you connect
+the same server under MCP in Cursor and sign in the local host, the
+converted agent can use that server's tools through your account.
+
+```ts
+// agent/mcp-connections/linear.ts
+import { defineConnection } from "@cursor/july/connections";
+
+export default defineConnection({
+  cursorAccount: true,
+  servers: ["Linear"],
+});
+```
+
+The summary adds a `Verify:` step when an original dashboard action
+does not map to one generated tool. Treat that step as a behavior test:
+run the converted agent with a representative input and confirm the
+same external write happens before you consider the action restored.
+
+## Bring a Slack trigger online
+
+After you create the dedicated Slack app, mentions wake the converted
+agent and its answers land in the same thread. A channel watch also
+wakes on allowed posts, but only after you subscribe the app with
+`--channel-posts`.
 
 ```bash
-agent-sdk convert-automation https://cursor.com/automations/0a1b2c3d-0000-1111-2222-333344445555
+agent-sdk slack create --dir . --channel-posts
 ```
 
-The summary prints the output directory. Change into it before running
-any setup command. For an Automation named "Nightly triage":
+The converter preserves the watch allowlist. If a warning says Cursor
+previously filtered messages by text, add that decision to the
+generated channel before inviting the bot:
+
+```ts
+export default slackChannel({
+  envPrefix: "NIGHTLY_TRIAGE",
+  engagement: {
+    channelPosts: { allow: ["C123"] },
+  },
+  onChannelPost: async (_ctx, message) => {
+    if (!message.markdown.includes("deploy")) {
+      return null;
+    }
+    // `{}` starts a model turn as the sender.
+    return {};
+  },
+});
+```
+
+For mention-only Automations, run `agent-sdk slack create --dir .`
+without `--channel-posts`. The [Slack guide](/docs/guides/slack.md) covers the
+reply experience and app setup.
+
+## Bring a GitHub trigger online
+
+The generated GitHub channel keeps mechanical filters such as PR
+actions, branches, issue actions, repositories, and simple user
+allowlists. Conditions that depended on backend-only context stay
+fail-closed, so the corresponding hook returns `null` until you replace
+it.
+
+For example, a converted CI trigger can wake only when the suite fails:
+
+```ts
+import {
+  defaultGitHubAuth,
+  githubChannel,
+} from "@cursor/july/channels/github";
+
+export default githubChannel({
+  cursorAccount: { repos: ["acme/api"] },
+  webhookEvents: ["check_suite"],
+  onCheckSuite: (ctx, suite) => {
+    if (suite.conclusion !== "failure") {
+      return null;
+    }
+    // `auth` starts a model turn running as the sender.
+    return { auth: defaultGitHubAuth(ctx) };
+  },
+});
+```
+
+Replay a PR with a failing check before connecting live delivery:
 
 ```bash
-cd nightly-triage
+agent-sdk github replay acme/api#42 \
+  --dir . \
+  --events '*' \
+  --conclusion failure
 ```
 
-The command fetches the Automation before writing files. A 404 means it
-was not found, you do not have access, or convert is not enabled for
-your team. A 422 means it is Cursor-managed. The command writes nothing
-after either error.
+Cursor-account delivery carries PR and comment events. Push, issue, and
+CI triggers need real GitHub webhook delivery through a GitHub App or
+`github forward`. The [GitHub guide](/docs/guides/github.md) covers both paths.
 
-The command runs `npm install` after writing the project. If the install
-fails, the files remain. Run `npm install` in the output directory
-before `dev`.
+## Treat warnings as the migration checklist
 
-## What the project contains
+A successful conversion means the project was generated, not that
+every source behavior survived. Read the warnings and setup steps before
+turning on a live trigger:
 
-A cron Automation with a Linear MCP server might produce:
+- A setup step names something you must connect or configure.
 
-```
-nightly-triage/
-  package.json
-  tsconfig.json
-  agent/
-    agent.ts
-    instructions.md
-    schedules/nightly-triage.ts
-    mcp-connections/linear.ts
-  evals/
-```
+- A `Verify:` step names an external action whose behavior needs a test.
+
+- A fail-closed hook intentionally starts no turns until you restore its
+  filter.
+
+- A `.todo.md` file is ignored by the framework and marks a connection
+  you must replace.
+
+Keep the source Automation enabled while you work through this list, so
+you still have its behavior as a reference.
+
+## Know the conversion boundary
+
+The converter can reproduce configuration that has a direct home in an
+Agent SDK project: instructions, the selected model, cron schedules,
+mechanical GitHub filters, Slack mentions and watch allowlists, and
+named Cursor-account MCP connections.
+
+It cannot infer policy that lived behind the dashboard. Bespoke trigger
+conditions, provider webhook registration and auth, credentials,
+unsupported trigger semantics, and built-in action behavior remain
+warnings, comments, or TODO files for you to resolve. Credentials are
+never exported.
+
+Cursor-managed Automations do not convert because their behavior lives
+entirely in managed configuration.
+
+## Related
 
-The command adds missing `init` scaffold files but omits the demo
-`echo` tool. It writes the memory hook only when memory was enabled.
-File generation leaves existing paths unchanged and marks them as
-`exist`. This does not cover `npm install`, which may update lockfiles
-or run lifecycle scripts from an existing `package.json`.
-
-| Automation input | Project output |
-| --- | --- |
-| First prompt | Copies text to `agent/instructions.md`. Action markup such as `@[label](action:...)` becomes the label text. |
-| Prompt model | Pins the model on `defineAgent` in `agent/agent.ts`. `git_config` and `agent_options` remain comments. |
-| Cron trigger | Creates `agent/schedules/<slug>.ts` with `defineSchedule` in UTC. |
-| GitHub trigger | Creates `agent/channels/github.ts`. It converts pull-request action, push branch, issue action, and user allowlist filters. |
-| Slack trigger | Creates `agent/channels/slack.ts` as Socket Mode with `envPrefix` from the automation name (same names `slack create` writes). Watches add `engagement.channelPosts`. Run `agent-sdk slack create` for the bot. |
-| Linear, PagerDuty, Sentry, Teams, or generic webhook | Creates a boilerplate `agent/channels/<slug>.ts`. |
-| HTTP or SSE MCP server | Creates a name-based Cursor-account connection under `agent/mcp-connections/`. The project contains no server URL or credentials. |
-| Stdio MCP server | Writes `agent/mcp-connections/<slug>.todo.md`. |
-| Slack post or read action | Adds `agent/mcp-connections/slack.ts`. The summary includes a `Verify:` step for the original action. |
-| Other built-in dashboard action | Adds a `Verify:` setup step instead of an Agent SDK tool. |
-
-## Finish unsupported behavior
-
-Warnings and setup steps identify behavior the converter could not
-reproduce.
-
-### Prompt snippets
-
-The export omits the source text for unresolved `%%INLINECODE<n>%%`
-placeholders. Restore those snippets in `instructions.md`.
-
-### GitHub filters
-
-Comment text, CI conclusion, label name, and review-state filters stay
-fail-closed. The generated hooks return `null` until you add them.
-The generated Cursor-account event relay includes only pull-request and
-comment data. Push, issue, and CI triggers need a GitHub App webhook or
-`github forward`. Add repositories for org-wide watches. The converter
-drops non-GitHub remotes.
-
-### Slack triggers
-
-Reaction and channel-created triggers have no Agent SDK equivalent. The
-converter keeps their configuration in comments but adds no handler.
-Re-add any `messageContains` filter or completion reaction you need.
-These triggers and channel watches require a dedicated Socket Mode app.
-Run `agent-sdk slack create --channel-posts`, then finish the dashboard
-wizard.
-
-### Provider webhooks
-
-Linear, PagerDuty, Sentry, Teams, and generic webhook channels mount
-`POST /` under their channel route. Every accepted body starts a run.
-In default multi-agent mode, the route is
-`/<agent-slug>/v1/channels/<channel-id>`. Single mode uses
-`/v1/channels/<channel-id>`.
-
-Restore the filters and auth before registering the provider. A hosted
-alias requires `X-Agent-Alias-Token`. If the provider cannot send that
-header, use `publicEndpoint()` with signature verification in the
-handler, put an alias-token relay in front, or self-host.
-
-### Stdio MCP servers
-
-The converter does not export the command, arguments, or environment.
-Run the server, then replace the `.todo.md` stub with a reachable
-connection.
-
-### Disabled default tools
-
-The converter cannot preserve this restriction. Do not rely on
-`instructions.md` as enforcement. Use the
-[`tools` allowlist](/docs/reference/agent-config.md#allowlist-built-in-harness-tools),
-remove unwanted authored or MCP tools, and limit channel permissions.
-
-## Review and run the project
-
-1. Read every warning and setup step.
-2. Open the generated channel files. Fail-closed GitHub hooks dispatch
-   nothing until you add their filters. Add auth to boilerplate webhook
-   routes.
-3. Confirm the account MCP servers are connected under MCP in the Cursor
-   dashboard. The serving host must be signed in with `agent-sdk login`
-   or `CURSOR_API_KEY`.
-4. Run the printed next steps:
-
-   ```bash
-   agent-sdk validate
-   agent-sdk dev
-   ```
-
-5. Before you [deploy](/docs/deployment.md), disable the source Automation
-   so both versions do not respond to the same events. The final setup
-   step includes its dashboard URL.
-6. A hosted deployment uses a separate service account. After the first
-   deploy, run `agent-sdk mcp oauth <connection>` for each generated
-   Cursor-account connection.
-
-## What's next
-
-- [CLI](/docs/reference/cli.md#convert-automation): flags, `--json`, exit
-  codes
+- [CLI reference](/docs/reference/cli.md#convert-automation): arguments,
+  JSON output, and failures
 - [MCP connections](/docs/reference/connections.md): Cursor-account
-  connectors
-- [GitHub](/docs/guides/github.md): hook filters and replay; use
-  [`github forward`](/docs/reference/cli.md#github) for live delivery
-- [Slack](/docs/guides/slack.md): Cursor connection vs Socket Mode
-- [Webhooks](/docs/guides/webhooks.md): auth on a custom channel route
-- [Deployment](/docs/deployment.md): hosted engines after you have reviewed
-  the project
+  connectors and hosted authorization
+- [GitHub](/docs/guides/github.md): event delivery, hook filters, and replay
+- [Slack](/docs/guides/slack.md): mentions, channel watches, and reply modes
+- [Webhooks](/docs/guides/webhooks.md): auth and filtering for generated provider
+  routes
+- [Deployment](/docs/deployment.md): deploy the reviewed project, then
+  disable the source Automation before enabling the same live triggers