workflow 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/getting-started/nestjs.mdx

@@ -9,10 +9,15 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
-This guide will walk through setting up your first workflow in a NestJS app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
+<CopyPrompt
+  text="In this NestJS app, run `npm i workflow @workflow/nest` and `npm i -D @swc/cli @swc/core`. Configure `nest-cli.json` with `compilerOptions.builder: &quot;swc&quot;` and `deleteOutDir: true`. Run `npx @workflow/nest init`, add `.swcrc` to `.gitignore`, and set package scripts `prebuild: &quot;npx @workflow/nest init --force&quot;` and `start:dev: &quot;npx @workflow/nest init --force && nest start --watch&quot;`. Import `WorkflowModule.forRoot()` from `@workflow/nest` in `src/app.module.ts` (use `{ moduleType: &quot;commonjs&quot;, distDir: &quot;dist&quot; }` if compiling CommonJS). Create `src/workflows/user-signup.ts` with `&quot;use workflow&quot;`, `sleep`, and `&quot;use step&quot;` helpers. Add a `POST /signup` controller method that reads `email`, calls `start(handleUserSignup, [email])` from `workflow/api`, and returns JSON. Run `npm run start:dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
+Set up your first durable workflow in a NestJS app and learn the core Workflow SDK concepts.
 
 <Callout>
-NestJS integration is experimental and not yet supported for deployment to Vercel.
+NestJS integration is experimental. Deployment to Vercel is supported via the
+`workflow-nest build --vercel` command. See [Deploy to Vercel](#deploy-to-vercel) below.
 </Callout>
 
 ---
@@ -20,7 +25,7 @@ NestJS integration is experimental and not yet supported for deployment to Verce
 <Steps>
 
 <Step>
-## Create Your NestJS Project
+## Create your NestJS project
 
 Start by creating a new NestJS project using the NestJS CLI.
 
@@ -41,7 +46,7 @@ cd my-workflow-app
 npm i workflow @workflow/nest
 ```
 
-### Choose Your Module Format
+### Choose your module format
 
 NestJS projects using `@workflow/nest` can compile as either ESM or CommonJS. Choose the setup that matches your SWC output instead of assuming ESM is required.
 
@@ -107,7 +112,7 @@ Ensure your `nest-cli.json` has SWC as the builder:
 }
 ```
 
-### Initialize SWC Configuration
+### Initialize SWC configuration
 
 Run the init command to generate the SWC configuration:
 
@@ -115,7 +120,7 @@ Run the init command to generate the SWC configuration:
 npx @workflow/nest init
 ```
 
-This creates a `.swcrc` file configured with the Workflow SWC plugin for client-mode transformations.
+This creates a `.swcrc` file configured with the Workflow SWC plugin for step-mode transformations.
 
 <Callout>
 Add `.swcrc` to your `.gitignore` as it contains machine-specific absolute paths that shouldn't be committed.
@@ -138,10 +143,10 @@ Add scripts to regenerate the SWC configuration before builds:
 <Accordion type="single" collapsible>
   <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
     <AccordionTrigger className="[&_p]:my-0 text-lg [&_p]:text-foreground">
-      Setup IntelliSense for TypeScript (Optional)
+      Set up IntelliSense for TypeScript (optional)
     </AccordionTrigger>
     <AccordionContent className="[&_p]:my-2">
-To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
+To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`:
 
 ```json title="tsconfig.json" lineNumbers
 {
@@ -203,7 +208,7 @@ The `WorkflowModule` handles workflow bundle building and provides HTTP routing
 
 <Step>
 
-## Create Your First Workflow
+## Create your first workflow
 
 Create a new file for our first workflow in the `src/workflows` directory:
 
@@ -236,14 +241,14 @@ export async function handleUserSignup(email: string) {
 }
 ```
 
-We'll fill in those functions next, but let's take a look at this code:
+We'll fill in those functions next, but first review this code:
 
 - We define a **workflow** function with the directive `"use workflow"`. Think of the workflow function as the _orchestrator_ of individual **steps**.
 - The Workflow SDK's `sleep` function allows us to suspend execution of the workflow without using up any resources. A sleep can be a few seconds, hours, days, or even months long.
 
-## Create Your Workflow Steps
+## Create your workflow steps
 
-Let's now define those missing functions.
+Define the missing functions.
 
 ```typescript title="src/workflows/user-signup.ts" lineNumbers
 import { FatalError } from "workflow";
@@ -284,7 +289,7 @@ async function sendOnboardingEmail(user: { id: string; email: string }) {
 
 Taking a look at this code:
 
-- Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+- Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 - If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 - Steps can throw a `FatalError` if an error is intentional and should not be retried.
 
@@ -297,7 +302,7 @@ Taking a look at this code:
 
 <Step>
 
-## Create Your Controller
+## Create your controller
 
 To invoke your new workflow, update your controller with a new endpoint:
 
@@ -357,11 +362,71 @@ npx workflow inspect runs
 
 </Step>
 
+<Step>
+
+## Deploy to Vercel
+
+Because NestJS is not a Vercel-native framework, the Workflow SDK produces a
+[Build Output API](https://vercel.com/docs/build-output-api) directory for you. This emits the
+workflow queue-consumer function (registered with `experimentalTriggers` so Vercel's queue can
+discover it) alongside your NestJS app as a catch-all function. Without it, workflow runs stay
+`pending` because nothing consumes the queue.
+
+Add a Vercel-specific entry module that default-exports your Nest app's underlying Node handler:
+
+```typescript title="_vercel/entry.ts" lineNumbers
+import 'reflect-metadata';
+import { NestFactory } from '@nestjs/core';
+import type { NestExpressApplication } from '@nestjs/platform-express';
+import express from 'express';
+import { AppModule } from '../dist/app.module.js';
+
+let ready: Promise<express.Express> | undefined;
+
+async function createHandler() {
+  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
+    bodyParser: false,
+  });
+  app.use(express.json());
+  await app.init();
+  return app.getHttpAdapter().getInstance();
+}
+
+export default async function handler(req: express.Request, res: express.Response) {
+  ready ??= createHandler();
+  return (await ready)(req, res);
+}
+```
+
+Skip the in-process build on Vercel (the bundles are pre-built) by passing `skipBuild` when
+`VERCEL` is set:
+
+{/* @skip-typecheck - config snippet, WorkflowModule imported above */}
+```typescript title="src/app.module.ts"
+WorkflowModule.forRoot({ skipBuild: Boolean(process.env.VERCEL) });
+```
+
+Then set your build command so the Build Output is produced after `nest build`:
+
+```json title="package.json" lineNumbers
+{
+  "scripts": {
+    "vercel-build": "workflow-nest init --force && nest build && workflow-nest build --vercel --dirs src/workflows --entry _vercel/entry.ts"
+  }
+}
+```
+
+Deploy as usual. `workflow-nest build --vercel` runs automatically on Vercel (it also detects the
+`VERCEL` environment variable), writing `.vercel/output` with the consumer function so your runs
+execute instead of staying `pending`.
+
+</Step>
+
 </Steps>
 
 ---
 
-## Configuration Options
+## Configuration options
 
 The `WorkflowModule.forRoot()` method accepts optional configuration:
 
@@ -387,10 +452,11 @@ WorkflowModule.forRoot({
   // Should match the outDir in your tsconfig.json
   distDir: 'dist',
 
-  // Source maps on generated workflow bundles (default: 'inline').
+  // Source maps on generated workflow bundles (default: 'inline' in
+  // development, false in production).
   // Accepts the same values as esbuild's sourcemap option: true, false,
   // 'inline', 'linked', 'external', 'both'. Set to false for smaller
-  // function bundles (useful for staying under the Vercel 250MB function
+  // function bundles (useful for staying under the Vercel 250 MB function
   // size limit) at the cost of stack traces pointing at generated code.
   // Can also be set via the WORKFLOW_SOURCEMAP environment variable.
   sourcemap: 'inline',
@@ -403,8 +469,8 @@ WorkflowModule.forRoot({
 
 If you see this error:
 
-```
-'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```text
+'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.
 ```
 
 Check both of these first:
@@ -413,7 +479,8 @@ Check both of these first:
 2. Your NestJS app imports and registers the `WorkflowModule`.
 
 See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
-## Next Steps
+
+## Next steps
 
 - Learn more about the [Foundations](/docs/foundations).
 - Check [Errors](/docs/errors) if you encounter issues.

package/docs/getting-started/next.mdx

@@ -7,13 +7,17 @@ prerequisites:
   - /docs/getting-started
 related:
   - /docs/api-reference/workflow-next
-  - /docs/deploying/world/vercel-world
+  - /worlds/vercel
 ---
 
+<CopyPrompt
+  text="In this Next.js app, run `npm i workflow`. Wrap `next.config.ts` with `withWorkflow` from `workflow/next`. If the app has `proxy.ts` or middleware, exclude `.well-known/workflow/` from its matcher. Add `workflows/user-signup.ts` exporting `handleUserSignup(email)` with `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` helper functions that create a user, send a welcome email, and send an onboarding email. Add `app/api/signup/route.ts` with a POST handler that reads `{ email }`, calls `start(handleUserSignup, [email])` from `workflow/api`, and returns JSON. Run `npm run dev`, trigger `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 <Steps>
 
 <Step>
-## Create Your Next.js Project
+## Create your Next.js project
 
 Start by creating a new Next.js project. This command will create a new directory named `my-workflow-app` and set up a Next.js project inside it.
 
@@ -75,9 +79,9 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 </Accordion>
 
 <Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
+  <AccordionItem value="configure-proxy-handler" className="[&_h3]:my-0">
     <AccordionTrigger className="text-sm">
-      ### Configure Proxy Handler (if applicable)
+      <h3 id="configure-proxy-handler">Configure Proxy Handler (if applicable)</h3>
     </AccordionTrigger>
     <AccordionContent className="[&_p]:my-2">
 
@@ -85,7 +89,9 @@ If your Next.js app has a [proxy handler](https://nextjs.org/docs/app/api-refere
 (formerly known as "middleware"), you'll need to update the matcher pattern to exclude Workflow's
 internal paths to prevent the proxy handler from running on them.
 
-Add `.well-known/workflow/*` to your middleware's exclusion list:
+If you see `[local world] Queue operation failed` with `Cannot perform ArrayBuffer.prototype.slice on a detached ArrayBuffer`, your proxy matcher is still intercepting Workflow's internal `POST /.well-known/workflow/v1/flow` request. This issue can be hard to spot in Next.js 16, where `proxy.ts` replaced `middleware.ts`.
+
+Add `.well-known/workflow/*` to your matcher exclusion list:
 
 ```typescript title="proxy.ts" lineNumbers
 import { NextResponse } from "next/server";
@@ -115,7 +121,7 @@ This ensures that internal Workflow paths are not intercepted by your middleware
 
 <Step>
 
-## Create Your First Workflow
+## Create your first workflow
 
 Create a new file for our first workflow:
 
@@ -138,14 +144,14 @@ export async function handleUserSignup(email: string) {
 
 ```
 
-We'll fill in those functions next, but let's take a look at this code:
+We'll fill in those functions next. The current code does the following:
 
 * We define a **workflow** function with the directive `"use workflow"`. Think of the workflow function as the _orchestrator_ of individual **steps**.
 * The Workflow SDK's `sleep` function allows us to suspend execution of the workflow without using up any resources. A sleep can be a few seconds, hours, days, or even months long.
 
-## Create Your Workflow Steps
+## Create your workflow steps
 
-Let's now define those missing functions.
+Define the missing functions.
 
 ```typescript title="workflows/user-signup.ts" lineNumbers
 import { FatalError } from "workflow"
@@ -186,7 +192,7 @@ async function sendOnboardingEmail(user: { id: string; email: string}) {
 
 Taking a look at this code:
 
-* Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+* Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 * If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 * Steps can throw a `FatalError` if an error is intentional and should not be retried.
 
@@ -198,7 +204,7 @@ We'll dive deeper into workflows, steps, and other ways to suspend or handle eve
 
 <Step>
 
-## Create Your Route Handler
+## Create your route handler
 
 To invoke your new workflow, we'll need to add your workflow to a `POST` API Route Handler, `app/api/signup/route.ts`, with the following code:
 
@@ -270,12 +276,12 @@ Check the [Deploying](/docs/deploying) section to learn how your workflows can b
 
 If you see this error when upgrading to Next.js 16.1 or later:
 
-```
+```text
 Build error occurred
 Error: Cannot find module 'next/dist/lib/server-external-packages.json'
 ```
 
-Upgrade to `workflow@4.0.1-beta.26` or later:
+Upgrade `workflow` to the latest release:
 
 ```package-install
 workflow@latest
@@ -309,8 +315,8 @@ Without this configuration, you may experience intermittent issues where workflo
 
 If you see this error:
 
-```
-'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```text
+'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.
 ```
 
 Check both of these first:
@@ -320,7 +326,7 @@ Check both of these first:
 
 See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
 
-## Next Steps
+## Next steps
 
 * Learn more about the [Foundations](/docs/foundations).
 * Check [Errors](/docs/errors) if you encounter issues.

package/docs/getting-started/nitro.mdx

@@ -1,6 +1,6 @@
 ---
 title: Nitro
-description: This guide will walk through setting up your first workflow in a Nitro v3 project. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
+description: Set up your first durable workflow in a Nitro v3 project.
 type: guide
 summary: Set up Workflow SDK in a Nitro app.
 prerequisites:
@@ -9,12 +9,16 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Nitro app, run `npm i workflow`. In `nitro.config.ts`, use `defineConfig` from `nitro`, set `serverDir: &quot;./server&quot;`, and add `modules: [&quot;workflow/nitro&quot;]`. Add the TypeScript plugin `{ &quot;name&quot;: &quot;workflow&quot; }` to `tsconfig.json` if TypeScript is used. Create `workflows/user-signup.ts` with `handleUserSignup(email)`, `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` helpers. Add `server/api/signup.post.ts` using `defineEventHandler` from `nitro/h3` and `start` from `workflow/api` to start the workflow from `{ email }`. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, then inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 <Steps>
 
 <Step>
-## Create Your Nitro Project
+## Create your Nitro project
 
-Start by creating a new [Nitro v3](https://v3.nitro.build/) project. This command will create a new directory named `nitro-app` and setup a Nitro project inside it.
+Create a [Nitro v3](https://v3.nitro.build/) project in a new directory named `nitro-app`:
 
 ```bash
 npx create-nitro-app
@@ -34,7 +38,7 @@ npm i workflow
 
 ### Configure Nitro
 
-Add `workflow/nitro` module to your `nitro.config.ts` This enables usage of the `"use workflow"` and `"use step"` directives.
+Add the `workflow/nitro` module to your `nitro.config.ts`. This enables the `"use workflow"` and `"use step"` directives.
 
 ```typescript title="nitro.config.ts" lineNumbers
 import { defineConfig } from "nitro";
@@ -66,15 +70,15 @@ export default defineConfig({
 | --- | --- | --- | --- |
 | `dirs` | `string[]` | — | Directories to scan for workflows and steps. By default, `workflows/` is scanned from the project root and all layer source directories. |
 | `runtime` | `string` | `'nodejs22.x'` | Node.js runtime version for Vercel Functions (e.g. `'nodejs22.x'`, `'nodejs24.x'`). |
-| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Set to `false` for smaller function bundles (useful for staying under the Vercel 250MB function size limit) at the cost of stack traces pointing at generated code. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Defaults to `'inline'` in development and `false` in production (smaller function bundles, which helps stay under the Vercel 250 MB function size limit). Set it explicitly, or use the `WORKFLOW_SOURCEMAP` environment variable, to override in either environment. |
 
 <Accordion type="single" collapsible>
   <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
     <AccordionTrigger className="[&_p]:my-0 text-lg [&_p]:text-foreground">
-      Setup IntelliSense for TypeScript (Optional)
+      Set up IntelliSense for TypeScript (optional)
     </AccordionTrigger>
     <AccordionContent className="[&_p]:my-2">
-To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
+To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`:
 
 ```json title="tsconfig.json" lineNumbers
 {
@@ -98,7 +102,7 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 
 <Step>
 
-## Create Your First Workflow
+## Create your first workflow
 
 Create a new file for our first workflow:
 
@@ -120,14 +124,14 @@ export async function handleUserSignup(email: string) {
 }
 ```
 
-We'll fill in those functions next, but let's take a look at this code:
+We'll fill in those functions next, but first review this code:
 
 - We define a **workflow** function with the directive `"use workflow"`. Think of the workflow function as the _orchestrator_ of individual **steps**.
 - The Workflow SDK's `sleep` function allows us to suspend execution of the workflow without using up any resources. A sleep can be a few seconds, hours, days, or even months long.
 
-## Create Your Workflow Steps
+## Create your workflow steps
 
-Let's now define those missing functions.
+Define the missing functions.
 
 ```typescript title="workflows/user-signup.ts" lineNumbers
 import { FatalError } from "workflow";
@@ -168,7 +172,7 @@ async function sendOnboardingEmail(user: { id: string; email: string }) {
 
 Taking a look at this code:
 
-- Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+- Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 - If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 - Steps can throw a `FatalError` if an error is intentional and should not be retried.
 
@@ -181,7 +185,7 @@ Taking a look at this code:
 
 <Step>
 
-## Create Your Route Handler
+## Create your route handler
 
 To invoke your new workflow, we'll create a new API route handler at `server/api/signup.post.ts` with the following code:
 
@@ -200,7 +204,7 @@ export default defineEventHandler(async ({ req }) => {
 });
 ```
 
-This Route Handler creates a `POST` request endpoint at `/api/signup` that will trigger your workflow.
+This route handler creates a `POST` request endpoint at `/api/signup` that triggers your workflow.
 
 <Callout>
   Workflows can be triggered from API routes or any server-side
@@ -244,7 +248,7 @@ npx workflow inspect runs
 
 ## Deploying to production
 
-Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
+Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and need no special configuration.
 
 <FluidComputeCallout />
 
@@ -256,8 +260,8 @@ Check the [Deploying](/docs/deploying) section to learn how your workflows can b
 
 If you see this error:
 
-```
-'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```text
+'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.
 ```
 
 Check both of these first:
@@ -267,7 +271,7 @@ Check both of these first:
 
 See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
 
-## Next Steps
+## Next steps
 
 - Learn more about the [Foundations](/docs/foundations).
 - Check [Errors](/docs/errors) if you encounter issues.

package/docs/getting-started/nuxt.mdx

@@ -9,10 +9,14 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
+<CopyPrompt
+  text="In this Nuxt app, run `npm i workflow`. In `nuxt.config.ts`, add `modules: [&quot;workflow/nuxt&quot;]` and keep `compatibilityDate: &quot;latest&quot;`. Create `workflows/user-signup.ts` exporting `handleUserSignup(email)` with `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` helpers that create a user and send emails. Add `server/api/signup.post.ts` using `defineEventHandler` from `h3` or `nitro/h3` and `start` from `workflow/api` to read `{ email }` and start the workflow. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:3000/api/signup`, and inspect with `npx workflow web` or `npx workflow inspect runs`."
+/>
+
 <Steps>
 
 <Step>
-## Create Your Nuxt Project
+## Create your Nuxt project
 
 Start by creating a new Nuxt project. This command will create a new directory named `nuxt-app` and setup a Nuxt project inside it.
 
@@ -75,7 +79,7 @@ export default defineNuxtConfig({
 
 <Step>
 
-## Create Your First Workflow
+## Create your first workflow
 
 Create a new file for our first workflow:
 
@@ -97,14 +101,14 @@ export async function handleUserSignup(email: string) {
 }
 ```
 
-We'll fill in those functions next, but let's take a look at this code:
+We'll fill in those functions next. The current code does the following:
 
 - We define a **workflow** function with the directive `"use workflow"`. Think of the workflow function as the _orchestrator_ of individual **steps**.
 - The Workflow SDK's `sleep` function allows us to suspend execution of the workflow without using up any resources. A sleep can be a few seconds, hours, days, or even months long.
 
-## Create Your Workflow Steps
+## Create your workflow steps
 
-Let's now define those missing functions.
+Define the missing functions.
 
 ```typescript title="server/workflows/user-signup.ts" lineNumbers
 import { FatalError } from "workflow";
@@ -145,7 +149,7 @@ async function sendOnboardingEmail(user: { id: string; email: string }) {
 
 Taking a look at this code:
 
-- Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+- Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 - If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 - Steps can throw a `FatalError` if an error is intentional and should not be retried.
 
@@ -158,7 +162,7 @@ Taking a look at this code:
 
 <Step>
 
-## Create Your API Route
+## Create your API route
 
 To invoke your new workflow, we'll create a new API route handler at `server/api/signup.post.ts` with the following code:
 
@@ -223,7 +227,7 @@ npx workflow inspect runs
 
 ## Deploying to production
 
-Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
+Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and need no special configuration.
 
 <FluidComputeCallout />
 
@@ -235,8 +239,8 @@ Check the [Deploying](/docs/deploying) section to learn how your workflows can b
 
 If you see this error:
 
-```
-'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```text
+'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.
 ```
 
 Check both of these first:
@@ -246,7 +250,7 @@ Check both of these first:
 
 See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
 
-## Next Steps
+## Next steps
 
 - Learn more about the [Foundations](/docs/foundations).
 - Check [Errors](/docs/errors) if you encounter issues.