@trigger.dev/sdk 4.7.2 → 4.7.4

package/docs/cli-env-commands.mdx

@@ -7,7 +7,6 @@ description: "List, get, set, and pull environment variables for a Trigger.dev p
 import CommonOptions from "/snippets/cli-options-common.mdx";
 import ConfigFileOptions from "/snippets/cli-options-config-file.mdx";
 import ProjectRefOptions from "/snippets/cli-options-project-ref.mdx";
-import BranchOptions from "/snippets/cli-options-branch.mdx";
 
 These commands manage environment variables on a project environment. They default to `prod`. Use `--env staging` or `--env preview` (with `--branch`) for the other environments. There is no `dev` target: local `trigger dev` reads your local `.env`.
 
@@ -82,7 +81,7 @@ npx trigger.dev@latest env set STRIPE_KEY sk_live_abc --secret
 
 ## env pull
 
-Writes the project's environment variables to a local file. Defaults to `.env.local`. Fails if the file already exists unless you pass `--force`.
+Writes the project's environment variables to a local file. Defaults to `.env.local`. Asks you to confirm before overwriting an existing file unless you pass `--force`. `TRIGGER_` system variables are omitted.
 
 ```bash
 npx trigger.dev@latest env pull
@@ -94,7 +93,7 @@ npx trigger.dev@latest env pull --output .env.trigger --force
 </ParamField>
 
 <ParamField body="Force" type="--force">
-  Overwrite the output file if it exists.
+  Overwrite the output file if it exists, without asking.
 </ParamField>
 
 ## Options
@@ -105,7 +104,9 @@ npx trigger.dev@latest env pull --output .env.trigger --force
 
 <ConfigFileOptions />
 <ProjectRefOptions />
-<BranchOptions />
+<ParamField body="Preview branch" type="--branch | -b">
+  Required when using `--env preview`. Specify the branch, e.g. `--branch my-branch` or `-b my-branch`.
+</ParamField>
 
 ### Common options
 

package/docs/cli-init-commands.mdx

@@ -24,6 +24,12 @@ yarn dlx trigger.dev@latest init
 
 </CodeGroup>
 
+## Arguments
+
+<ParamField body="Project path" type="[path]">
+  The path to the project. Defaults to `.`.
+</ParamField>
+
 ## Options
 
 <ParamField body="Javascript" type="--javascript">
@@ -36,7 +42,7 @@ yarn dlx trigger.dev@latest init
 </ParamField>
 
 <ParamField body="Package tag" type="--tag | -t">
-  The version of the `@trigger.dev/sdk` package to install. Defaults to `latest`.
+  The version of the `@trigger.dev/sdk` package to install. Defaults to the CLI version.
 </ParamField>
 
 <ParamField body="Skip package install" type="--skip-package-install">
@@ -47,6 +53,26 @@ yarn dlx trigger.dev@latest init
   Override the existing config file if it exists.
 </ParamField>
 
+<ParamField body="Project name" type="--project-name <name>">
+  The name of the project to create when your account has no projects yet.
+</ParamField>
+
+<ParamField body="Organization name" type="--org-name <name>">
+  The organization to create the first project in. Matches an existing organization by name, or creates it if you have none.
+</ParamField>
+
+<ParamField body="Runtime" type="-r, --runtime <runtime>">
+  The runtime to use: `node`, `node-22`, `node-24`, `node-26` or `bun`. Defaults to `node-24`.
+</ParamField>
+
+<ParamField body="Yes" type="-y, --yes">
+  Skip all prompts. Requires `--project-ref`, or `--project-name` with `--org-name` for a new account.
+</ParamField>
+
+<ParamField body="No browser" type="--no-browser">
+  Do not open the browser during login. Print the URL only.
+</ParamField>
+
 <ParamField body="Package arguments" type="--pkg-args">
   Additional arguments to pass to the package manager. Accepts CSV for multiple args.
 </ParamField>

package/docs/cli-login-commands.mdx

@@ -26,6 +26,26 @@ yarn dlx trigger.dev@latest login
 
 ## Options
 
+<ParamField body="No browser" type="--no-browser">
+  Do not open the browser. Print the URL only.
+</ParamField>
+
+<ParamField body="Email" type="--email <email>">
+  Prefill the email on the login page.
+</ParamField>
+
+<ParamField body="Name" type="--name <name>">
+  Set your name after authorization. Only applies to a new account that has not set its details yet.
+</ParamField>
+
+<ParamField body="Cancel pending" type="--cancel-pending">
+  Cancel a pending login and keep the current account.
+</ParamField>
+
+<ParamField body="No wait" type="--no-wait">
+  Save the authorization and exit so login can be resumed later.
+</ParamField>
+
 ### Common options
 
 These options are available on most commands.

package/docs/cli-projects-commands.mdx

@@ -1,7 +1,7 @@
 ---
 title: "CLI projects commands"
 sidebarTitle: "projects"
-description: "Create, inspect, and rename Trigger.dev projects from the terminal."
+description: "List, create, inspect, and rename Trigger.dev projects from the terminal."
 ---
 
 import CommonOptions from "/snippets/cli-options-common.mdx";
@@ -37,6 +37,18 @@ yarn dlx trigger.dev@latest projects create
   The name of the new project.
 </ParamField>
 
+## projects list
+
+Lists your projects with the runtime and version of their current Production deployment.
+
+```bash
+npx trigger.dev@latest projects list
+```
+
+<ParamField body="Needs update" type="--needs-update">
+  Only show projects using Node.js 21 in Production.
+</ParamField>
+
 ## projects get
 
 Prints the name, ref, slug, organization, default runtime and region of a project.

package/docs/cli-runs-commands.mdx

@@ -7,7 +7,6 @@ description: "Use these commands to list, inspect, replay and cancel runs from y
 import CommonOptions from "/snippets/cli-options-common.mdx";
 import ConfigFileOptions from "/snippets/cli-options-config-file.mdx";
 import ProjectRefOptions from "/snippets/cli-options-project-ref.mdx";
-import BranchOptions from "/snippets/cli-options-branch.mdx";
 
 ## runs list
 
@@ -85,7 +84,9 @@ npx trigger.dev@latest runs cancel run_abc123
 
 <ConfigFileOptions />
 <ProjectRefOptions />
-<BranchOptions />
+<ParamField body="Preview branch" type="--branch | -b">
+  Required when using `--env preview`. Specify the branch, e.g. `--branch my-branch` or `-b my-branch`.
+</ParamField>
 
 ### Common options
 

package/docs/cli-update-commands.mdx

@@ -14,19 +14,25 @@ Run the command like this:
 <CodeGroup>
 
 ```bash npm
-npx trigger.dev@latest update
+npx trigger.dev@latest update [path]
 ```
 
 ```bash pnpm
-pnpm dlx trigger.dev@latest update
+pnpm dlx trigger.dev@latest update [path]
 ```
 
 ```bash yarn
-yarn dlx trigger.dev@latest update
+yarn dlx trigger.dev@latest update [path]
 ```
 
 </CodeGroup>
 
+## Arguments
+
+<ParamField body="Project path" type="[path]">
+  The directory that contains the `package.json` file. Defaults to `.`.
+</ParamField>
+
 ## Options
 
 ### Common options

package/docs/cli-whoami-commands.mdx

@@ -26,6 +26,18 @@ yarn dlx trigger.dev@latest whoami
 
 ## Options
 
+<ParamField body="Config file" type="-c, --config <config file>">
+  The name of the config file.
+</ParamField>
+
+<ParamField body="Project ref" type="-p, --project-ref <project ref>">
+  The project ref. Overrides the project in the config file.
+</ParamField>
+
+<ParamField body="Env file" type="--env-file <env file>">
+  Path to a `.env` file to read `TRIGGER_PROJECT_REF` from. Defaults to `.env`, `.env.development`, `.env.local`, `.env.development.local` and `dev.vars` in the current directory.
+</ParamField>
+
 ### Common options
 
 These options are available on most commands.

package/docs/concurrency.mdx

@@ -367,6 +367,38 @@ await concurrencyLimits.reset("openai");
 
 Overrides survive deploys: redeploying your code keeps an active override until you reset it.
 
+### Overriding a limit for one key
+
+Pass `concurrencyKey` to override a limit's `perKey` for a single key, for example to let one session run more (or fewer) runs at once than the limit allows every other key:
+
+```ts
+import { concurrencyLimits } from "@trigger.dev/sdk";
+
+// this session may run 3 at once under "subagents", for the next 7 days
+await concurrencyLimits.override("subagents", {
+  concurrencyKey: sessionId,
+  perKey: 3,
+  ttl: "7d",
+});
+
+// read it back: the key's bound, the override, and when it expires
+const view = await concurrencyLimits.retrieve("subagents", { concurrencyKey: sessionId });
+console.log(view.perKey.override, view.perKey.expiresAt, view.running);
+
+// clear it early
+await concurrencyLimits.reset("subagents", { concurrencyKey: sessionId });
+```
+
+A per-key override behaves differently from a limit override:
+
+- **It is temporary.** It expires after `ttl` (a duration such as `"7d"` or a number of seconds). The default is 7 days and the maximum is 30 days. Call `override` again to extend it. Nothing warns you when it lapses, so check `expiresAt` if a key must keep its cap for longer than a week.
+- **It changes one limit only.** The limit's own bounds and every other limit the run holds are untouched. A tenant-wide limit keeps applying on top of a per-session override.
+- **It applies to every task holding the limit**, because the key's pool under a shared named limit is one pool.
+- **It needs a `perKey` to override.** A limit declared with only a `total` has no per-key bound, so the call is rejected, and if a later deploy removes a limit's `perKey` its per-key overrides stop applying. A task's inline limit is addressed as `task/<task-id>`. `total` is not per key, so `concurrencyKey` goes with `perKey` (and optionally `ttl`) and never with `total`; the SDK's types enforce this.
+- **`perKey: 0` blocks the key.** A paused limit stays paused whatever the override says.
+- **It does not stop runs.** Lowering a key's cap takes effect at the next run to start; runs already executing continue.
+- **`reset(name)` without a key leaves per-key overrides alone**; clear them with `reset(name, { concurrencyKey })` or let them expire.
+
 ### Pausing a limit
 
 Pause a limit to stop every run holding it from being dequeued; runs that are already executing continue to completion. The configured bounds are kept, and resuming restores them:

package/docs/config/extensions/audioWaveform.mdx

@@ -14,7 +14,10 @@ export default defineConfig({
   project: "<project ref>",
   // Your other config settings...
   build: {
-    extensions: [audioWaveform()], // uses verson 1.1.0 of audiowaveform by default
+    extensions: [audioWaveform()], // uses version 1.10.1 of audiowaveform by default
   },
 });
 ```
+
+To use a different version, pass the `version` and `checksum` options to `audioWaveform()`.
+

package/docs/config/extensions/overview.mdx

@@ -51,6 +51,8 @@ Trigger.dev provides a set of built-in extensions that you can use to customize
 | [prismaExtension](/config/extensions/prismaExtension)                 | Using prisma in your Trigger.dev tasks                                         |
 | [pythonExtension](/config/extensions/pythonExtension)                 | Execute Python scripts in your project                                         |
 | [puppeteer](/config/extensions/puppeteer)                             | Use Puppeteer in your Trigger.dev tasks                                        |
+| [playwright](/config/extensions/playwright)                           | Use Playwright in your Trigger.dev tasks                                       |
+| [lightpanda](/config/extensions/lightpanda)                           | Use Lightpanda in your Trigger.dev tasks                                       |
 | [ffmpeg](/config/extensions/ffmpeg)                                   | Use FFmpeg in your Trigger.dev tasks                                           |
 | [aptGet](/config/extensions/aptGet)                                   | Install system packages in your build image                                    |
 | [additionalFiles](/config/extensions/additionalFiles)                 | Copy additional files to your build image                                      |

package/docs/config/extensions/prismaExtension.mdx

@@ -641,7 +641,7 @@ prismaExtension({
 ```prisma
 generator client {
   provider      = "prisma-client-js"
-  binaryTargets = ["native", "linux-arm64-openssl-3.0.x"]
+  binaryTargets = ["native", "debian-openssl-3.0.x"]
 }
 ```
 
@@ -885,7 +885,7 @@ export const db = new PrismaClient({
 generator client {
   provider      = "prisma-client-js"
   output        = "../src/generated/prisma"
-  binaryTargets = ["native", "linux-arm64-openssl-3.0.x"]
+  binaryTargets = ["native", "debian-openssl-3.0.x"]
 }
 
 datasource db {
@@ -913,7 +913,6 @@ datasource db {
 prismaExtension({
   mode: "engine-only",
   version: "6.19.0",
-  binaryTarget: "linux-arm64-openssl-3.0.x",
 });
 ```
 

package/docs/config/extensions/puppeteer.mdx

@@ -4,6 +4,8 @@ sidebarTitle: "puppeteer"
 description: "Use the puppeteer build extension to enable support for Puppeteer in your project"
 ---
 
+import ScrapingWarning from "/snippets/web-scraping-warning.mdx";
+
 <ScrapingWarning />
 
 To use Puppeteer in your project, add these build settings to your `trigger.config.ts` file:
@@ -21,10 +23,6 @@ export default defineConfig({
 });
 ```
 
-And add the following environment variable in your Trigger.dev dashboard on the Environment Variables page:
-
-```bash
-PUPPETEER_EXECUTABLE_PATH: "/usr/bin/google-chrome-stable",
-```
+The extension installs Chrome and sets `PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome-stable` for deployed builds automatically, so you do not need to set it. Don't set it in your Dev environment: the extension does nothing in Dev, and locally Puppeteer uses the browser it downloads on install.
 
 Follow [this example](/guides/examples/puppeteer) to get setup with Trigger.dev and Puppeteer in your project.

package/docs/config/extensions/pythonExtension.mdx

@@ -103,6 +103,14 @@ export default defineConfig({
 
 This will install the packages specified in the `requirements.txt` file during the build process. You can then use these packages in your Python scripts.
 
+You can also list requirements inline with the `requirements` option instead. You can't use it together with `requirementsFile`:
+
+```ts
+pythonExtension({
+  requirements: ["pandas"],
+});
+```
+
 <Note>
   The `requirementsFile` option is only available in production mode. In development mode, you can
   install the required packages manually using the `pip` command.
@@ -145,7 +153,7 @@ export const myStreamingScript = task({
     const result = python.stream.runScript("./python/my_script.py", ["hello", "world"]);
 
     // result is an async iterable/readable stream
-    for await (const chunk of streamingResult) {
+    for await (const chunk of result) {
       console.log(chunk);
     }
   },

package/docs/config/extensions/syncEnvVars.mdx

@@ -31,6 +31,9 @@ The callback is passed a context object with the following properties:
 - `environment`: The environment name that the task is being deployed to (e.g. `production`, `staging`, etc.)
 - `projectRef`: The project ref of the Trigger.dev project
 - `env`: The environment variables that are currently set in the Trigger.dev project
+- `branch`: The preview branch name, if deploying to a preview branch (optional)
+
+`syncEnvVars` also accepts a second argument with an `override` option (defaults to `true`). When `true`, synced variables overwrite variables with the same name that are already set in the environment you're deploying to. Set it to `false` to only sync variables that aren't set there yet.
 
 ### Marking variables as secrets
 
@@ -168,12 +171,15 @@ export default defineConfig({
         projectId: "your-vercel-project-id",
         vercelAccessToken: "your-vercel-access-token", // optional, we recommend to keep it as env variable
         vercelTeamId: "your-vercel-team-id", // optional
+        branch: "your-preview-branch", // optional
       }),
     ],
   },
 });
 ```
 
+The `branch` option filters branch-specific Vercel variables for preview branches. It defaults to the `VERCEL_PREVIEW_BRANCH` environment variable, then the Trigger.dev preview branch. The access token is read from `VERCEL_ACCESS_TOKEN`, falling back to `VERCEL_TOKEN`.
+
 ### syncNeonEnvVars
 
 The `syncNeonEnvVars` build extension syncs environment variables from your Neon database project to Trigger.dev. It automatically detects branches and builds the appropriate database connection strings for your environment.

package/docs/deploy-environment-variables.mdx

@@ -14,7 +14,7 @@ We deploy your tasks and scale them up and down when they are triggered. So any
 <Steps>
 
 <Step title="Go to the Environment Variables page">
-  In the sidebar select the "Environment Variables" page, then press the "New environment variable"
+  In the sidebar select the "Environment Variables" page, then press the "Add new"
   button. ![Environment variables page](/images/environment-variables-page.jpg)
 </Step>
 

package/docs/deployment/atomic-deployment.mdx

@@ -443,6 +443,8 @@ If you use the [Vercel integration](/vercel-integration), version skew protectio
 
 This covers production, staging and preview alike.
 
+In production, the integration also gates the release on the task build. Each production deployment from your production branch carries a blocking **Trigger.dev Build** check, so a commit whose tasks fail to build never goes live and its runs never wait on a deployment that won't arrive. Re-run the **Trigger.dev deployment** check in GitHub to build that commit again. See [Production waits for your tasks](/vercel-integration#production-waits-for-your-tasks).
+
 ### Opting out
 
 Set `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` to `0` on your Vercel project. A `0` you set today stays `0` through every subsequent build.

package/docs/deployment/dev-branches.mdx

@@ -59,7 +59,7 @@ You can also set the branch with the `TRIGGER_DEV_BRANCH` environment variable i
 
 ## Archive a branch
 
-Archive a branch from the CLI when you no longer need it. The CLI detects your local git branch, or you can name one with `--branch`:
+Archive a branch from the CLI when you no longer need it. Pass the branch with `--branch` (or set `TRIGGER_DEV_BRANCH`); it's required, and the `default` branch can't be archived:
 
 <CodeGroup>
 
@@ -81,12 +81,12 @@ You can also create and archive branches from the **Dev branches** page in the d
 
 ## Limits on active branches
 
-Each branch has its own concurrency, so we limit how many can be active per project. Archive a branch at any time to unlock another slot.
+Each branch has its own concurrency, so we limit how many dev branches each developer can have active per project. The `default` development environment counts toward this limit. If you are at the limit when you run `dev --branch`, the CLI automatically archives up to 3 of your branches that have no connected dev session and have been idle for over an hour, to make room. You can also archive a branch any time to free a slot.
 
 | Plan  | Active dev branches |
 | ----- | ------------------- |
-| Free  | 25                  |
-| Hobby | 25                  |
-| Pro   | 25                  |
+| Free  | 50                  |
+| Hobby | 50                  |
+| Pro   | 50                  |
 
 Need more? [Get in touch](https://trigger.dev/contact) and we'll raise the limit.

package/docs/deployment/overview.mdx

@@ -6,7 +6,7 @@ description: "Learn how to deploy your tasks to Trigger.dev."
 
 import CorepackError from "/snippets/corepack-error.mdx";
 
-Before you can run production workloads on Trigger.dev, you need to deploy your tasks. The only way to do this at the moment is through the [deploy CLI command](/cli-deploy-commands):
+Before you can run production workloads on Trigger.dev, you need to deploy your tasks. The manual way to do this is the [deploy CLI command](/cli-deploy-commands). You can also deploy automatically with the [GitHub integration](/github-integration) or the [Vercel integration](/vercel-integration):
 
 <CodeGroup>
 
@@ -100,8 +100,9 @@ When you deploy, the version number is automatically incremented, and the new ve
 The current version defines which version of the code new task runs will execute against. When a task run starts, it is locked to the current version. This ensures that the task run is not affected by changes to the code. Retries of the task run will also be locked to the original version.
 
 <Note>
-  When you Replay a run in the dashboard we will create a new run, locked to the current version and
-  not necessarily the version of the original run.
+  When you Replay a run in the dashboard we create a new run that uses the current version by default
+  (in deployed environments you can pick a specific version in the replay dialog), not necessarily
+  the version of the original run.
 </Note>
 
 ### Version locking
@@ -186,10 +187,10 @@ For additional environments beyond `prod` and `staging`, you can use [preview br
 
 ## Local builds
 
-By default we use a remote build provider to speed up builds. However, you can also force the build to happen locally on your machine using the `--force-local-build` flag:
+By default we use a remote build provider to speed up builds. However, you can also force the build to happen locally on your machine using the `--local-build` flag:
 
 ```bash
-npx trigger.dev deploy --force-local-build
+npx trigger.dev deploy --local-build
 ```
 
 <Tip>
@@ -205,7 +206,7 @@ To use local builds, you need the following tools installed on your machine:
 
 ## Environment variables
 
-To add custom environment variables to your deployed tasks, you need to add them to your project in the Trigger.dev dashboard, or automatically sync them using our [syncEnvVars](/config/config-file#syncenvvars) or [syncVercelEnvVars](/config/config-file#syncvercelenvvars) build extensions.
+To add custom environment variables to your deployed tasks, you need to add them to your project in the Trigger.dev dashboard, or automatically sync them using our [syncEnvVars](/config/extensions/syncEnvVars) or [syncVercelEnvVars](/config/extensions/syncEnvVars#syncvercelenvvars) build extensions.
 
 For more information on environment variables, see our [environment variables](/deploy-environment-variables) guide.
 
@@ -235,7 +236,7 @@ You can run the deploy command with `--log-level debug` at the end. This will pr
 
 There should be a link below the error message to the full build logs on your machine. Take a look at these to see what went wrong. Join [our Discord](https://trigger.dev/discord) and you share it privately with us if you can't figure out what's going wrong. Do NOT share these publicly as the verbose logs might reveal private information about your project.
 
-Sometimes these errors are caused by upstream availability issues with our remote build provider. In this case, you can try deploying with a local build using the `--force-local-build` flag. Refer to the [Local builds](#local-builds) section for more information.
+Sometimes these errors are caused by upstream availability issues with our remote build provider. In this case, you can try deploying with a local build using the `--local-build` flag. Refer to the [Local builds](#local-builds) section for more information.
 
 #### `Deployment encountered an error`
 

package/docs/deployment/preview-branches.mdx

@@ -18,10 +18,13 @@ The process to use preview branches looks like this:
 3. Create a named **Trigger only** API key in the Preview environment, then trigger runs using the key (`TRIGGER_SECRET_KEY`) and branch name (`TRIGGER_PREVIEW_BRANCH`).
 4. Archive the preview branch when the branch is done.
 
-There are two main ways to do this:
+There are three main ways to do this:
 
-1. Automatically: using GitHub Actions (recommended).
-2. Manually: in the dashboard and/or using the CLI.
+1. Automatically: using the [GitHub integration](/github-integration), which deploys pull requests to preview branches and archives them when the PR is merged or closed, without a GitHub Action.
+2. Automatically: using GitHub Actions, if you deploy from your own CI workflows.
+3. Manually: in the dashboard and/or using the CLI.
+
+Pick one of the automatic options, not both.
 
 ### Limits on active preview branches
 

package/docs/errors-retrying.mdx

@@ -15,8 +15,8 @@ You can configure retrying in two ways:
 <Note>Task-level retry settings override the defaults in your `trigger.config` file.</Note>
 
 <Note>
-  By default when you create your project using the CLI init command we disabled retrying in the DEV
-  environment. You can enable it in your [trigger.config file](/config/config-file).
+  By default when you create your project using the CLI init command, retrying is enabled in the DEV
+  environment. You can disable it by setting `enabledInDev: false` in your [trigger.config file](/config/config-file).
 </Note>
 
 ## A simple example with OpenAI
@@ -112,7 +112,7 @@ import { task, logger, retry } from "@trigger.dev/sdk";
 
 export const taskWithFetchRetries = task({
   id: "task-with-fetch-retries",
-  run: async ({ payload, ctx }) => {
+  run: async (payload: any, { ctx }) => {
     //if the Response is a 429 (too many requests), it will retry using the data from the response. A lot of good APIs send these headers.
     const headersResponse = await retry.fetch("http://my.host/test-headers", {
       retry: {
@@ -182,7 +182,7 @@ export const taskWithFetchRetries = task({
 
 ## Advanced error handling and retrying
 
-We provide a `catchError` callback on the task and in your `trigger.config` file. This gets called when an uncaught error is thrown in your task.
+We provide a `catchError` callback on the task, and you can register one globally with `tasks.catchError()`. This gets called when an uncaught error is thrown in your task.
 
 You can
 

package/docs/how-it-works.mdx

@@ -6,7 +6,7 @@ description: "Understand how Trigger.dev works and how it can help you."
 
 ## Introduction
 
-Trigger.dev v3 allows you to integrate long-running async tasks into your application and run them in the background. This allows you to offload tasks that take a long time to complete, such as sending multi-day email campaigns, processing videos, or running long chains of AI tasks.
+Trigger.dev allows you to integrate long-running async tasks into your application and run them in the background. This allows you to offload tasks that take a long time to complete, such as sending multi-day email campaigns, processing videos, or running long chains of AI tasks.
 
 For example, the below task processes a video with `ffmpeg` and sends the results to an s3 bucket, then updates a database with the results and sends an email to the user.
 
@@ -278,8 +278,8 @@ export const convertVideo = task({
     // Update database
     await updateVideoUrl(videoId, s3Url);
 
-    // Send email, we don't need to wait for this to finish
-    await sendUserEmail.trigger({ videoId, s3Url }, { idempotencyKey });
+    // Send email
+    await sendUserEmail.triggerAndWait({ videoId, s3Url }, { idempotencyKey }).unwrap();
 
     return { success: true, s3Url };
   },
@@ -420,7 +420,7 @@ When you run `npx trigger.dev@latest dev`, we run your task code locally on your
 - Changes are automatically detected and a new version is spun up when you save your code.
 - Add debuggers and breakpoints to your code and debug it locally.
 - Each task is run in a separate process, so you can run multiple tasks in parallel.
-- Auto-cancels tasks when you stop the dev server.
+- Stopping the dev server stops your local task processes. If the CLI is killed abruptly (for example by a package manager sending SIGKILL), in-flight runs are cancelled automatically. After a normal Ctrl-C stop, in-flight runs are not cancelled and can end with a `TASK_RUN_STALLED_EXECUTING` error once the 5 minute heartbeat timeout passes.
 
 <Note>
   Trigger.dev currently does not support "offline" dev mode, where you can run tasks without an
@@ -430,7 +430,7 @@ When you run `npx trigger.dev@latest dev`, we run your task code locally on your
 
 ## Staging and production environments
 
-Trigger.dev supports deploying to `prod` and `staging` environments. This allows you to test your tasks in a staging environment before deploying them to production. You can deploy to a different environment by running `npx trigger.dev@latest deploy --env <env>`, where `<env>` is either `prod` or `staging`. Each environment has its own API Key, which you can use to trigger tasks in that environment.
+Trigger.dev supports deploying to `prod` and `staging` environments. This allows you to test your tasks in a staging environment before deploying them to production. You can deploy to a different environment by running `npx trigger.dev@latest deploy --env <env>`, where `<env>` is `prod`, `staging` or `preview` (the branch is detected from git, or you can pass `--branch`). Each environment has its own API Key, which you can use to trigger tasks in that environment.
 
 For additional isolated environments, you can use [preview branches](/deployment/preview-branches), which allow you to create separate environments for each branch of your code.
 

package/docs/introduction.mdx

@@ -5,6 +5,8 @@ description: "Build and run durable AI agents and workflows in TypeScript. Long-
 mode: "center"
 ---
 
+import AgentSetupPrompt from "/snippets/agent-setup-prompt.mdx";
+
 <CardGroup cols={2}>
   <Card title="Quick start" icon="rocket" href="/quick-start" color="#A8FF53">
     Go from zero to your first task in 3 minutes.
@@ -20,6 +22,10 @@ mode: "center"
   </Card>
 </CardGroup>
 
+## Set up with AI
+
+<AgentSetupPrompt />
+
 ## What is Trigger.dev?
 
 Trigger.dev is the open source platform for building and running durable AI agents and workflows in TypeScript. Run them for hours, configure automatic retries, control concurrency, and manage queues. There's no execution timeout, and no queue or worker infrastructure for you to build.