workflow 5.0.0-beta.35 → 5.0.0-beta.37

package/docs/configuration/worlds.mdx

@@ -4,9 +4,9 @@ description: Configure the Workflow backend that stores runs and delivers queue
 type: reference
 summary: Select and configure Local, Postgres, Vercel, or custom Worlds.
 related:
-  - /docs/deploying/world/local-world
-  - /docs/deploying/world/postgres-world
-  - /docs/deploying/world/vercel-world
+  - /worlds/local
+  - /worlds/postgres
+  - /worlds/vercel
 ---
 
 A [World](/docs/deploying) stores workflow state and delivers queue messages.
@@ -21,6 +21,12 @@ A [World](/docs/deploying) stores workflow state and delivers queue messages.
 
 Outside Vercel, Workflow defaults to the Local World. On Vercel, leave `WORKFLOW_TARGET_WORLD` unset for the normal case; Workflow detects the Vercel deployment and selects the Vercel World automatically.
 
+The World is selected when your app is **built**, not when it runs, and compiled into the server bundles. Detection therefore reads the build environment: `VERCEL_DEPLOYMENT_ID` when it is available, otherwise `VERCEL=1` for builds where no deployment exists yet. A dev server is never affected, because `VERCEL_ENV=development` and `NODE_ENV=development` both keep the Local World selected — including when `vercel env pull` has written `VERCEL=1` into `.env.local`.
+
+If your build environment does not expose Vercel's system environment variables — for example a build that runs in a container of your own before uploading, or one where [system environment variables](https://vercel.com/docs/environment-variables/system-environment-variables) are disabled for the project — set `WORKFLOW_TARGET_WORLD=vercel` in the build environment. Without it, the deployment is built against the Local World and every run fails writing to a read-only filesystem. Switching this value requires a rebuild; changing it at runtime has no effect.
+
+The mirror image applies when a build that looks like Vercel is served somewhere else: a production server started locally or in CI with an env file from `vercel env pull` has `VERCEL=1`, so it is built against the Vercel World and then has no `VERCEL_DEPLOYMENT_ID` at runtime. Starting a run in that server fails with an error saying so. To run the same code against your filesystem, set `WORKFLOW_TARGET_WORLD=local` and rebuild.
+
 Set `WORKFLOW_TARGET_WORLD` only when you want to use a custom or self-hosted World:
 
 - `local` - alias for `@workflow/world-local`.
@@ -95,8 +101,8 @@ The Local World is the default outside Vercel and is intended for development.
 ### `streamFlushIntervalMs`
 
 - Environment variable fallback: `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
-- Default: `10`
-- Flush interval for buffered stream writes. The World option wins when set.
+- Default: `0` (dispatch the leading chunk of an idle stream immediately)
+- Group-commit window for the leading chunk of an idle stream; a positive value trades first-chunk latency for larger groups. The `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` environment variable, when set, overrides this option; otherwise the World option governs, including the very first chunk.
 
 ## Postgres World
 
@@ -128,6 +134,14 @@ The Postgres World is a self-hosted durable backend for long-running server proc
 - Number of concurrent workers polling for jobs.
 - Also bounds concurrent parent-to-child workflow return-value polls.
 
+### `applicationManagedShutdown`
+
+- Environment variable: `WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN` (`1` enables)
+- Default: `false`
+- Whether the application coordinates shutdown instead of Graphile Worker responding automatically.
+- Set to `true` only when the application awaits `world.close()` before closing its workflow HTTP server and caller-owned pool.
+- Prevents Graphile Worker's default handler from terminating the process before the application's remaining cleanup finishes.
+
 ### `maxPoolSize`
 
 - Environment variable: `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
@@ -143,8 +157,8 @@ The Postgres World is a self-hosted durable backend for long-running server proc
 ### `streamFlushIntervalMs`
 
 - Environment variable fallback: `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
-- Default: `10`
-- Flush interval for buffered stream writes. The World option wins when set.
+- Default: `0` (dispatch the leading chunk of an idle stream immediately)
+- Group-commit window for the leading chunk of an idle stream; a positive value trades first-chunk latency for larger groups. The `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` environment variable, when set, overrides this option; otherwise the World option governs, including the very first chunk.
 
 ## Vercel World
 
@@ -201,7 +215,7 @@ Platform-provided values such as `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, an
 - Default: disabled
 - Set `1` to serialize orchestrator (flow) invocations per run: each run's replays get their own queue topic and the flow trigger is generated with `maxConcurrency: 1`. Inline step executions get per-step topics and keep full parallelism.
 - Read at **both build time and runtime** — set it as a project-level environment variable so the generated trigger and the runtime queue routing agree.
-- Routing each run through a dedicated `maxConcurrency: 1` topic might lead to higher queue performance overhead. See [Vercel World](/docs/deploying/world/vercel-world#workflow_sequential_replays) for details.
+- Routing each run through a dedicated `maxConcurrency: 1` topic might lead to higher queue performance overhead. See [Vercel World](/worlds/vercel#workflow_sequential_replays) for details.
 
 ### `VERCEL_WORKFLOW_SERVER_URL`
 

package/docs/cookbook/advanced/publishing-libraries.mdx

@@ -2,11 +2,11 @@
 title: Publishing Libraries
 description: Structure and publish npm packages that export workflow functions for consumers to use with Workflow SDK.
 type: guide
-summary: Learn how to build, export, and test npm packages that ship workflow and step functions — including package.json exports, re-exporting for stable workflow IDs, keeping step I/O clean, and integration testing.
+summary: Learn how to build, export, and test npm packages that ship workflow and step functions — including package.json exports, re-exporting so the consumer's compiler discovers your workflows, keeping step I/O clean, and integration testing.
 ---
 
 <CopyPrompt
-  text="Package these workflow functions as a publishable npm library. Give the package a dedicated workflows entry point (for example `exports[&quot;./workflows&quot;]`) that ships the workflow and step source for the consumer's compiler to process. Keep every workflow and step input and output serializable, and read credentials from environment variables inside steps instead of accepting client instances. Document the consumer re-export requirement: consumers create a file in their `workflows/` directory containing `export * from &quot;<pkg>/workflows&quot;` so their build assigns stable workflow IDs and replay can resolve functions after cold starts. Add an integration test that runs a library workflow end to end from a consumer-style setup. Verify the build, stable IDs across deployments, and replay safety."
+  text="Package these workflow functions as a publishable npm library. Give the package a dedicated workflows entry point (for example `exports[&quot;./workflows&quot;]`) that ships the workflow and step source for the consumer's compiler to process. Keep every workflow and step input and output serializable, and read credentials from environment variables inside steps instead of accepting client instances. Document the consumer re-export requirement: consumers create a file in their `workflows/` directory containing `export * from &quot;<pkg>/workflows&quot;` so their build discovers and compiles the library's workflow and step files and replay can resolve them after cold starts. Add an integration test that runs a library workflow end to end from a consumer-style setup. Verify the build, that the library's workflows and steps show up as compiled entries, and replay safety."
 />
 
 import { File, Folder, Files } from "fumadocs-ui/components/files";
@@ -114,31 +114,35 @@ export default defineConfig({
 });
 ```
 
-## Re-Exporting for Workflow ID Stability
+## Re-Exporting for Compiler Discovery
 
-Workflow SDK's compiler assigns each workflow function a stable ID based on its position in the source file that the build system processes. When a consumer imports a pre-built workflow from an npm package, the compiler never sees the original source — it only sees the compiled output. This means workflow IDs won't match between the library's development environment and the consumer's app.
+The workflow compiler only transforms files it discovers, and discovery starts from the consumer's `workflows/` directory and follows imports out from there. A library's workflow functions are not on that graph by default, so nothing compiles them and the runtime has no definition to run.
 
-The fix is a **re-export file**. The consumer creates a file in their `workflows/` directory that re-exports the library's workflows. The build system then processes this file and assigns stable IDs.
+The fix is a **re-export file**. The consumer creates a file in their `workflows/` directory that re-exports the library's workflows, which pulls the library's source onto the discovery graph and gives its entry point an address the runtime can resolve.
 
 ### Consumer Setup
 
 ```typescript lineNumbers
 // workflows/media.ts (in the consumer's project)
-// Re-export library workflows so the build system assigns stable IDs
+// Re-export library workflows so the compiler discovers and transforms them
 export * from "@acme/media/workflows"; // [!code highlight]
 ```
 
-This one-line file is all that's needed. The workflow compiler transforms this file, discovers the workflow and step functions from the library, and assigns IDs that are stable across deployments.
+This one-line file is all that's needed. The compiler follows the re-export into the package, transforms the workflow and step functions it finds, and registers them under IDs the runtime can resolve.
 
 ### Why This Is Necessary
 
-Without re-exporting, the workflow runtime cannot match a running workflow to its function definition. When a workflow run is replayed after a cold start, the runtime looks up functions by their compiler-assigned IDs. If the IDs don't exist (because the compiler never processed the library's source), replay fails.
+Without re-exporting, the workflow runtime cannot match a running workflow to its function definition. When a run is replayed after a cold start, the runtime looks up functions by their compiler-assigned IDs. If those functions were never compiled, the IDs don't exist and replay fails.
 
-The re-export pattern ensures:
+Point the re-export at the package's dedicated workflows entry point rather than a deep path into `dist/`. Files reachable through the package's `exports` map get an ID of the form `name/subpath@version`; a deep, non-exported file falls back to a path-based ID instead.
 
-1. **Stable IDs** — the compiler assigns IDs based on the consumer's source tree
-2. **Replay safety** — IDs persist across deployments and cold starts
-3. **Version upgrades** — re-exported IDs remain stable as long as the consumer's file doesn't change
+<Callout type="info">
+**IDs for code you ship embed your package version.** A step in `@acme/media` version `1.4.0` gets the ID `step//@acme/media/workflows@1.4.0//transcode`, so publishing `1.5.0` renames every workflow and step the package ships.
+
+That is safe on worlds with deployment pinning, such as Vercel, because runs are pinned to the deployment that started them. A run records its deployment ID and every resume targets that same deployment, so after a consumer upgrades, new runs execute the new version while runs already in flight keep replaying against the old one. Consumers do not need to drain anything before upgrading.
+
+The re-export file does not change any of this. An ID is derived from where the file lives, not from how it was imported, so a package file keeps its `name@version` ID whether or not a consumer re-exports it.
+</Callout>
 
 ## Keeping Step I/O Clean
 
@@ -252,7 +256,7 @@ Some libraries want to be useful to consumers who *aren't* using Workflow SDK at
 Two rules for isomorphic packages:
 
 1. **Any runtime reference to the `workflow` package must be loaded via dynamic `import("workflow")` inside a try/catch.** A static top-level import makes the module fail to load for consumers who haven't installed workflow.
-2. **The `"use workflow"` and `"use step"` directives are safe to keep in your library source.** When a consumer compiles your code with the Workflow SDK toolchain (via the [re-export pattern](#re-exporting-for-workflow-id-stability) above), the SWC plugin transforms them into durable-execution glue. When they're not compiled — plain Node, plain tests, a consumer without the runtime — they are just string expression statements and run as no-ops.
+2. **The `"use workflow"` and `"use step"` directives are safe to keep in your library source.** When a consumer compiles your code with the Workflow SDK toolchain (via the [re-export pattern](#re-exporting-for-compiler-discovery) above), the SWC plugin transforms them into durable-execution glue. When they're not compiled — plain Node, plain tests, a consumer without the runtime — they are just string expression statements and run as no-ops.
 </Callout>
 
 ### Optional peer dependency

package/docs/cookbook/common-patterns/idempotency.mdx

@@ -90,6 +90,6 @@ The workflow should create the deterministic hook and check `await hook.getConfl
 - [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) -- declares step functions with full Node.js access
 - [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata) -- provides the deterministic `stepId` for idempotency keys
 - [`createHook()`](/docs/api-reference/workflow/create-hook) -- creates a hook with an optional deterministic token
-- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) -- finds the active hook for a token
+- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) -- finds the Hook that owns a token
 - [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) -- resumes the active hook when the duplicate request carries data
 - [`start()`](/docs/api-reference/workflow-api/start) -- starts a new workflow run

package/docs/{deploying/index.mdx → deploying.mdx}

@@ -1,15 +1,13 @@
 ---
 title: Deploying
-icon: Rocket
 description: Deploy workflows locally, on Vercel, or anywhere using pluggable World adapters.
 type: overview
 summary: Learn how to deploy workflows to different environments using World adapters.
-manualCards: true
 related:
-  - /docs/deploying/world/local-world
-  - /docs/deploying/world/postgres-world
-  - /docs/deploying/world/vercel-world
-  - /docs/deploying/building-a-world
+  - /worlds/local
+  - /worlds/postgres
+  - /worlds/vercel
+  - /worlds/building-a-world
 ---
 
 Workflows are designed to be highly portable. The same workflow code can run locally during development, on Vercel with zero configuration, or on any infrastructure using **Worlds** — pluggable adapters that handle storage, queuing, and communication.
@@ -54,7 +52,7 @@ vercel deploy
 <FluidComputeCallout />
 
 <Callout>
-  Learn more about the [Vercel World](/docs/deploying/world/vercel-world) and its capabilities, including [multi-region](/docs/deploying/world/vercel-world#multi-region).
+  Learn more about the [Vercel World](/worlds/vercel) and its capabilities, including [multi-region](/worlds/vercel#multi-region).
 </Callout>
 
 ## Self-Hosting & Other Providers
@@ -65,7 +63,7 @@ For self-hosting or deploying to other cloud providers, you can use community-ma
   <Card title="Explore Worlds" href="/worlds">
     Browse official and community World implementations with compatibility status and performance benchmarks.
   </Card>
-  <Card title="Build Your Own" href="/docs/deploying/building-a-world">
+  <Card title="Build Your Own" href="/worlds/building-a-world">
     Learn how to implement a custom World for your infrastructure.
   </Card>
 </Cards>

package/docs/foundations/hooks.mdx

@@ -112,7 +112,7 @@ export async function orderWorkflow(orderId: string) {
 }
 ```
 
-Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the hook registration, then resolves with `null` once the hook is registered and ready to receive payloads, or with a `Run` handle for the run that owns the token if another active hook already claimed it (see [`HookConflictError`](/docs/errors/hook-conflict)). For `hook_conflict` events persisted by older worlds that did not record the owning run's ID, `getConflict()` rejects with `HookConflictError` instead of resolving with an incomplete handle. The conflicting run's accessors are durable steps, so the workflow can inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` — see [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies.
+Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the hook registration, then resolves with `null` once the hook is registered and ready to receive payloads, or with a `Run` handle for the run that owns the token (see [`HookConflictError`](/docs/errors/hook-conflict)). For `hook_conflict` events persisted by older worlds that did not record the owning run's ID, `getConflict()` rejects with `HookConflictError` instead of resolving with an incomplete handle. The conflicting run's accessors are durable steps, so the workflow can inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` — see [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies.
 
 ### Custom Tokens for Deterministic Hooks
 

package/docs/foundations/idempotency.mdx

@@ -96,7 +96,7 @@ export async function processOrder(orderId: string): Promise<OrderResult> {
 }
 ```
 
-The runtime creates the hook atomically. At most one active hook can own `order:${orderId}`, so duplicate workflow runs converge on one active owner. A duplicate run observes `getConflict()` resolving with the owner's `Run` and returns before it reaches `chargeOrder()`. The conflicting run's accessors (`status`, `returnValue`, `cancel()`, …) are durable steps, so the duplicate run can do more than report the owner — see [conflict-handling strategies](#conflict-handling-strategies) below.
+The runtime creates the hook atomically. At most one hook can own `order:${orderId}`, so duplicate workflow runs converge on one owner. A duplicate run observes `getConflict()` resolving with the owner's `Run` and returns before it reaches `chargeOrder()`. The conflicting run's accessors (`status`, `returnValue`, `cancel()`, …) are durable steps, so the duplicate run can do more than report the owner — see [conflict-handling strategies](#conflict-handling-strategies) below.
 
 Outside the workflow, try to resume the hook first. If the hook is not registered yet, start the workflow and retry the resume until the new run creates the hook:
 
@@ -149,7 +149,7 @@ export async function POST(request: Request) {
 This avoids creating a new run only after the first run has registered its hook. Because `start()` returns before the run body executes and calls `createHook()`, two concurrent requests can both observe "no hook yet" and each call `start()`. The race is resolved inside the workflow body, where the losing run observes `getConflict()` resolving with the active owner and returns without doing duplicate-sensitive work — and the route detects it by comparing the resumed hook's `runId` against the run it just started, without waiting for either run to finish. A native API for atomically starting a run and registering a hook is in the works. Until then, model recovery inside the workflow by checking `hook.getConflict()`.
 </Callout>
 
-This is active-run coordination. When the workflow completes and disposes the hook, the token can be used again. If a duplicate request after completion must return the original result instead of starting fresh work, persist that completed result under the same domain key.
+This coordinates active runs by default: the token becomes available when its workflow ends. Set `experimental_minRetention` to keep it unavailable to late duplicates. After the workflow ends, the Hook can still be found with `getHookByToken()` until retention ends, but it cannot be resumed. See [`createHook()` minimum retention](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) for examples and supported values.
 
 ### Conflict-handling strategies
 
@@ -182,7 +182,7 @@ export async function processOrder(orderId: string) {
 }
 ```
 
-**Inspect the owner before deciding.** Branch on the owner's live state:
+**Inspect the owner before deciding.** Reuse a completed owner's result, but reject other duplicates:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -200,17 +200,17 @@ export async function processOrder(orderId: string) {
   const conflict = await request.getConflict();
   if (conflict) {
     const status = await conflict.status; // [!code highlight]
-    if (status === "running") {
-      return { status: "duplicate" as const, runId: conflict.runId };
+    if (status === "completed") {
+      return await conflict.returnValue;
     }
-    // Owner already reached a terminal state; its hook will be released.
+    return { status: "duplicate" as const, runId: conflict.runId };
   }
 
   return await processOwnedOrder(orderId);
 }
 ```
 
-**Signal the owner instead of doing the work.** The duplicate run knows the token, so it can deliver this run's input to the owner's hook from a step:
+**Signal the owner instead of doing the work.** A conflict can refer to a finished run when `experimental_minRetention` is set, so check its status before sending data to its Hook:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -230,16 +230,19 @@ export async function processOrder(orderId: string, confirmed: boolean) {
   using request = createHook<OrderRequest>({ token });
 
   const conflict = await request.getConflict();
-  if (conflict) {
+  if (conflict && ["pending", "running"].includes(await conflict.status)) {
     await forwardToOwner(token, { confirmed }); // [!code highlight]
     return { status: "forwarded" as const, runId: conflict.runId };
   }
+  if (conflict) {
+    return { status: "duplicate" as const, runId: conflict.runId };
+  }
 
   // ... own the token and do the work
 }
 ```
 
-**Supersede the owner.** Newest-wins: cancel the active run, then claim the released token. Cancellation disposes the owner's hooks; the retry loop covers the window where that disposal has not propagated yet:
+**Supersede the owner.** Without minimum retention, cancel the active run, then claim the released token. The retry loop covers the window where cancellation cleanup has not propagated yet:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -272,6 +275,10 @@ export async function processOrderNewestWins(orderId: string) {
 }
 ```
 
+<Callout type="warn">
+This pattern does not work with `experimental_minRetention`: cancelling the old run does not make its token available early.
+</Callout>
+
 If duplicate requests should only reuse the active run without sending data, use [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) as an advisory pre-check before calling `start()`. The workflow should still check `hook.getConflict()`, because the lookup and `start()` are not atomic.
 
 Because this pattern uses hooks for idempotency, duplicate requests can also inject additional data and steer the existing run. The route example above uses `resumeHook()` for that: if the hook already exists, the duplicate request resumes the active workflow; if the hook is not registered yet, the route starts the workflow and retries `resumeHook()` so the payload is not dropped.

package/docs/getting-started/astro.mdx

@@ -160,7 +160,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.
 
@@ -252,7 +252,7 @@ Additionally, check the [Deploying](/docs/deploying) section to learn how your w
 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.
+'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:

package/docs/getting-started/express.mdx

@@ -185,7 +185,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.
 
@@ -273,7 +273,7 @@ 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.
+'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:

package/docs/getting-started/fastify.mdx

@@ -174,7 +174,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.
 
@@ -260,7 +260,7 @@ 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.
+'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:

package/docs/getting-started/hono.mdx

@@ -170,7 +170,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.
 
@@ -255,7 +255,7 @@ 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.
+'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:

package/docs/getting-started/index.mdx

@@ -83,11 +83,11 @@ import { SiReactrouter } from "@icons-pack/react-simple-icons";
         <Badge variant="secondary">Beta</Badge>
       </div>
     </Card>
-    <Card className="opacity-50">
+    <Card href="/docs/getting-started/nestjs">
       <div className="flex flex-col items-center justify-center gap-2">
-        <Nest className="size-16 dark:invert grayscale" />
+        <Nest className="size-16 dark:invert" />
         <span className="font-medium">NestJS</span>
-        <Badge variant="secondary">Coming soon</Badge>
+        <Badge variant="secondary">Experimental</Badge>
       </div>
     </Card>
 </Cards>

package/docs/getting-started/meta.json

@@ -12,7 +12,8 @@
     "sveltekit",
     "tanstack-start",
     "vite",
-    "python"
+    "python",
+    "nestjs"
   ],
   "defaultOpen": true
 }

package/docs/getting-started/nestjs.mdx

@@ -16,7 +16,8 @@ related:
 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.
 
 <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>
 
 ---
@@ -288,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.
 
@@ -361,6 +362,66 @@ 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>
 
 ---
@@ -409,7 +470,7 @@ 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.
+'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:

package/docs/getting-started/next.mdx

@@ -7,7 +7,7 @@ prerequisites:
   - /docs/getting-started
 related:
   - /docs/api-reference/workflow-next
-  - /docs/deploying/world/vercel-world
+  - /worlds/vercel
 ---
 
 <CopyPrompt
@@ -192,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.
 
@@ -316,7 +316,7 @@ 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.
+'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:

package/docs/getting-started/nitro.mdx

@@ -172,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.
 
@@ -261,7 +261,7 @@ 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.
+'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:

package/docs/getting-started/nuxt.mdx

@@ -149,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.
 
@@ -240,7 +240,7 @@ 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.
+'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:

package/docs/getting-started/sveltekit.mdx

@@ -157,7 +157,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.
 
@@ -245,7 +245,7 @@ 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.
+'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:

package/docs/getting-started/tanstack-start.mdx

@@ -155,7 +155,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.
 

package/docs/getting-started/vite.mdx

@@ -160,7 +160,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.
 
@@ -245,7 +245,7 @@ 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.
+'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: