workflow 5.0.0-beta.2 → 5.0.0-beta.4

package/docs/migration-guides/migrating-from-aws-step-functions.mdx

@@ -30,7 +30,12 @@ npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-
 - Streaming is built in. Write durable progress from steps with `getWritable()` and named streams. No DynamoDB or SNS glue to surface status to clients.
 - Infrastructure lives in one deployment. No separate state machine, per-task Lambda, IAM role wiring, or callback SQS queues.
 - Error handling is TypeScript-native: step-level retries, `RetryableError`, and `FatalError` replace per-state Retry/Catch blocks.
-- Agent-first tooling: the `npx workflow` CLI, `@workflow/ai` integration, and the Claude skill are available out of the box.
+- The `npx workflow` CLI and `npx workflow web` observability UI ship out of the box.
+- AI/agent helpers — `@workflow/ai` for AI-SDK integration and the Claude migration skill — are available as separate installs.
+
+## Before you migrate
+
+This guide assumes **Standard** workflows. Express workflows have different semantics (at-least-once, 5-minute max duration, no execution history) and may need a different target — consider keeping them on Step Functions, moving them to a queue consumer, or ensuring your steps are idempotent before replaying the pattern here.
 
 ## What changes when you leave Step Functions?
 
@@ -49,8 +54,9 @@ The migration replaces declarative configuration with idiomatic TypeScript and c
 | Choice state | `if` / `else` / `switch` | Native TypeScript control flow. |
 | Wait state | `sleep()` | Import `sleep` from `workflow`. |
 | Parallel state | `Promise.all()` | Standard concurrency primitives. |
-| Map state | Loop + `Promise.all()` or child workflows | Iterate with `for`/`map`. |
+| Map state | Inline sequential → `for` loop; bounded parallel (`MaxConcurrency: N`) → batched `Promise.all` or a concurrency limiter like `p-limit`; Distributed Map / large fan-out → step-wrapped `start()` per item, then step-wrapped `getRun()` to collect. | Match the concurrency mode of the original Map. |
 | Retry / Catch | Step retries, `RetryableError`, `FatalError` | Retry logic moves to step boundaries. |
+| `Catch` to a compensation state | `try`/`catch` in the workflow function, calling compensation steps in reverse order (push/pop a rollback stack) | See [`/docs/foundations/errors-and-retries`](/docs/foundations/errors-and-retries) for the SAGA pattern. |
 | `.waitForTaskToken` | `createHook()` or `createWebhook()` | Hooks for typed signals; webhooks for HTTP. |
 | Child state machine (`StartExecution`) | `"use step"` around `start()` / `getRun()` | Return the `Run` object, await its result from another step. |
 | Execution event history | Workflow event log | Same durable replay model. |
@@ -73,6 +79,10 @@ Start with a single Task state. In ASL, even "call one Lambda" requires a state
 }
 ```
 
+<Callout type="info">
+Examples use JSONPath mode. If your state machine sets `QueryLanguage: 'JSONata'`, the shape of `Arguments`/`Output` fields differs but the TypeScript translation is identical.
+</Callout>
+
 ```typescript title="workflow/workflows/order.ts (Workflow SDK)"
 export async function processOrder(orderId: string) {
   'use workflow'; // [!code highlight]
@@ -101,7 +111,7 @@ export async function processOrder(orderId: string) {
 }
 ```
 
-`await` replaces `"Next"`. Each new step is a new function with `"use step"`; no additional deployment.
+`await` replaces `"Next"`. Each new step is a new function with `"use step"`; no additional deployment. The second version also reshapes the return value; the workflow return type can be anything serializable.
 
 ### Starting from an API route
 
@@ -118,6 +128,20 @@ export async function POST(request: Request) {
 }
 ```
 
+### Waiting for a fixed duration
+
+A `Wait` state becomes `sleep()`:
+
+```json title="stateMachine.asl.json (Step Functions)"
+{ "Type": "Wait", "Seconds": 60, "Next": "Next" }
+```
+
+{/* @skip-typecheck: one-line snippet fragment */}
+
+```typescript title="workflow/workflows/order.ts (Workflow SDK)"
+await sleep('1m');
+```
+
 ## Wait for an external signal
 
 The minimal ASL for a callback is a Task with `.waitForTaskToken`:
@@ -198,7 +222,7 @@ import { start } from 'workflow/api';
 
 async function spawnChild(item: string) {
   'use step'; // [!code highlight]
-  return start(childWorkflow, [item]);
+  return await start(childWorkflow, [item]);
 }
 
 export async function parentWorkflow(item: string) {
@@ -232,9 +256,13 @@ Moving off Step Functions removes these surfaces from the application:
 - Per-task Lambda functions, their IAM roles, and CloudFormation/CDK wiring.
 - Task-token delivery infrastructure (SQS queues, callback Lambdas).
 - Separate progress channels (DynamoDB, SNS) for client-visible updates.
-- CloudWatch and X-Ray configuration for orchestrator observability.
+- Remove CloudWatch and X-Ray wiring that was specific to orchestrator state transitions. Keep (or re-wire) any application-level CloudWatch alarms, log retention policies, or X-Ray propagation that the rest of your AWS footprint still depends on. Workflow SDK exports OTEL traces, so existing OTEL-compatible backends can continue to ingest them.
+
+Workflow and step functions live in the same deployment as the application. State transitions are ordinary control flow (`await`, `if`, `Promise.all`, `for`). Progress streaming, retries, and observability are built in.
 
-Workflow and step functions live in the same deployment as the application. State transitions are `await` calls. Progress streaming, retries, and observability are built in.
+### What you take on
+
+Steps that previously invoked AWS services via optimized integrations (EventBridge, DynamoDB, Bedrock, ECS.RunTask.sync, etc.) become ordinary SDK calls inside `'use step'` functions. Credentials and retries move into the step, and `.sync`-style waits for long-running jobs become explicit polling loops or hook-based callbacks.
 
 ## Step-by-step first migration
 
@@ -276,6 +304,18 @@ async function loadOrder(id: string) {
 
 Swap the task-token callback Lambda for `createHook()`. Callers `resumeHook(token, payload)` instead of `SendTaskSuccess`.
 
+Move Retry/Catch off per-state configuration and onto step boundaries. Set `maxRetries` as a function property; throw `RetryableError` or `FatalError` to control retry behavior:
+
+```typescript
+async function chargePayment(orderId: string) {
+  "use step";
+  // ...
+}
+chargePayment.maxRetries = 5;
+```
+
+See [`/docs/foundations/errors-and-retries`](/docs/foundations/errors-and-retries) for the full retry and SAGA compensation patterns.
+
 ### Step 5: Start runs from an API route
 
 Delete the `StartExecution` call and IAM wiring. Launch runs directly from a route handler:
@@ -293,7 +333,16 @@ export async function POST(req: Request) {
 
 ### Step 6: Retire the Step Functions infrastructure
 
-Delete the ASL JSON, per-task Lambda deployments, IAM roles, and callback queues. Remove CloudWatch and X-Ray wiring used for orchestrator observability. Verify the run in `npx workflow web` before shipping.
+Delete the ASL JSON, per-task Lambda deployments, IAM roles, and callback queues. Remove CloudWatch and X-Ray wiring that was specific to orchestrator state transitions — keep alarms, log retention, and traces for resources you still depend on. Verify the run in `npx workflow web` before shipping.
+
+## Features without a 1:1 equivalent
+
+- **Express workflows.** At-least-once semantics and 5-minute duration make them a poor fit for the SDK's durable replay model. Consider keeping them on Step Functions or migrating to a queue consumer.
+- **Distributed Map state.** Up to 10,000 concurrent child executions with S3 item sources has no 1:1 analog; fan out with step-wrapped `start()` per item, then `Promise.all` with `p-limit` to bound concurrency.
+- **Optimized AWS service integrations (`arn:aws:states:::dynamodb:*`, `eventbridge:*`, `bedrock:*`, `ecs:runTask.sync`, etc.).** These become regular SDK calls inside `'use step'` functions — credentials, retries, and polling move into the step.
+- **Per-state IAM roles.** ASL lets each state run under its own IAM role. In the SDK, all steps share the deployment's credentials; scope secrets and roles at deployment time.
+- **CloudWatch alarms / X-Ray cross-service traces / CloudWatch Logs retention.** The SDK event log + observability UI replaces orchestrator state transitions, not AWS-wide observability. Keep alarms and traces for other resources.
+- **`JSONata` `QueryLanguage` mode.** Valid at the source; the TS translation is identical regardless of mode.
 
 ## Quick-start checklist
 
@@ -302,10 +351,13 @@ Delete the ASL JSON, per-task Lambda deployments, IAM roles, and callback queues
 - Replace Choice states with `if`/`else`/`switch`.
 - Replace Wait states with `sleep()` from `workflow`.
 - Replace Parallel states with `Promise.all()`.
-- Replace Map states with loops or `Promise.all()`. For large fan-outs, wrap `start()` in a step.
+- Replace Map states based on their concurrency mode: inline sequential → `for` loop; bounded parallel (`MaxConcurrency: N`) → batched `Promise.all` or a concurrency limiter like `p-limit`; Distributed Map / large fan-out → step-wrapped `start()` per item, then step-wrapped `getRun()` to collect.
 - Replace `StartExecution` child machines with `"use step"` wrappers around `start()` and `getRun()`.
 - Replace `.waitForTaskToken` with `createHook()` (internal callers) or `createWebhook()` (HTTP callers).
 - Move Retry/Catch to step boundaries using `maxRetries`, `RetryableError`, and `FatalError`.
 - Use `getStepMetadata().stepId` as the idempotency key for external side effects.
 - Stream progress from steps with `getWritable()` instead of polling DynamoDB or SNS.
 - Deploy and verify runs end-to-end with built-in observability.
+
+---
+*Verified against `workflow@5.0.0-beta.1` and the AWS Step Functions Amazon States Language spec on 2026-04-16.*

package/docs/migration-guides/migrating-from-inngest.mdx

@@ -1,6 +1,6 @@
 ---
 title: Migrating from Inngest
-description: Move an Inngest TypeScript app to the Workflow SDK by replacing createFunction, step.run(), step.sleep(), step.waitForEvent(), and step.invoke() with Workflows, Steps, Hooks, and start()/getRun().
+description: Move an Inngest TypeScript SDK v3 or v4 app to the Workflow SDK by replacing createFunction, step.run(), step.sleep(), step.waitForEvent(), and step.invoke() with Workflows, Steps, Hooks, and start()/getRun().
 type: guide
 summary: Translate an Inngest app into the Workflow SDK with side-by-side code examples.
 prerequisites:
@@ -29,6 +29,8 @@ npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-
 - TypeScript-first DX. Steps are named async functions marked with `"use step"`. No inline closures tied to a framework-specific lifecycle.
 - Agent-first tooling: the `npx workflow` CLI, `@workflow/ai` integration for durable AI agents, and a Claude skill for generating workflows.
 
+Inngest code samples in this guide use the v4 two-argument `createFunction({ id, triggers }, handler)` shape. If the app is still on Inngest v3, treat the three-argument form `createFunction({ id }, { event: '...' }, handler)` as equivalent — the `triggers` option in v4 replaces the second argument in v3.
+
 ## What changes when you leave Inngest
 
 Inngest defines functions with `inngest.createFunction()`, registers them through a `serve()` handler, and breaks work into steps with `step.run()`, `step.sleep()`, and `step.waitForEvent()`. The platform routes events, schedules steps, and applies retries.
@@ -37,13 +39,17 @@ The Workflow SDK replaces that with `"use workflow"` functions that orchestrate
 
 Migration collapses the SDK abstraction into plain async functions. Business logic stays the same.
 
+<Callout type="info">
+Inngest's event-bus model is loosely coupled — publishers don't know consumers. `start()` requires the caller to import the workflow function directly, giving stronger type safety but tighter coupling. For event-bus-like fan-out, wrap `start()` in a shared publisher module.
+</Callout>
+
 ## Concept mapping
 
 | Inngest | Workflow SDK | Migration note |
 | --- | --- | --- |
 | `inngest.createFunction()` | `"use workflow"` function started with `start()` | No wrapper needed. |
 | `step.run()` | `"use step"` function | Standalone async function with Node.js access. |
-| `step.sleep()` / `step.sleepUntil()` | `sleep()` | Import from `workflow`. |
+| `step.sleep()` / `step.sleepUntil()` | `sleep()` | `sleep('5m')` for a duration; `sleep(date)` for sleep-until. |
 | `step.waitForEvent()` | `createHook()` or `createWebhook()` | Hooks for typed signals, webhooks for HTTP. |
 | `step.invoke()` | `"use step"` wrappers around `start()` / `getRun()` | Spawn a child run, pass `runId` forward. |
 | `inngest.send()` / event triggers | `start()` from your app boundary | Start workflows directly. |
@@ -60,7 +66,7 @@ Start with the shell of a function. Inngest wraps it in `createFunction`; Workfl
 export const processOrder = inngest.createFunction(
   {
     id: 'process-order',
-    triggers: [{ event: 'order/created' }],
+    triggers: { event: 'order/created' },
   },
   async ({ event, step }) => {
     return { orderId: event.data.orderId, status: 'completed' };
@@ -165,6 +171,8 @@ Event matching disappears. A hook's token encodes the routing (for example, `ref
 
 `step.invoke()` splits into two steps: spawn and collect. `start()` and `getRun()` are runtime APIs, so wrap them in `"use step"` functions. Return the `Run` object from the spawn step so observability can deep-link into the child run.
 
+You can return either the full `Run` object (enables deep-linking) or just `run.runId` (simpler).
+
 {/* @skip-typecheck: snippet without imports */}
 ```typescript title="workflow/workflows/parent.ts"
 async function spawnChild(item: string) {
@@ -206,7 +214,7 @@ Pick one Inngest function and migrate it end-to-end before touching the rest. Th
 
 ### Step 1: Install the Workflow SDK
 
-Add the runtime and the framework integration that matches the app.
+Install the SDK. Framework integrations (`workflow/next`, `workflow/nitro`, `workflow/nuxt`, etc.) are subpath exports of the same `workflow` package — no additional install needed.
 
 ```bash
 pnpm add workflow
@@ -219,7 +227,7 @@ Replace the factory call with a plain async export. Move the handler body up. Th
 ```ts title="workflows/order.ts"
 // Before (Inngest)
 // export const processOrder = inngest.createFunction(
-//   { id: "process-order", triggers: [{ event: "order.created" }] },
+//   { id: "process-order", triggers: { event: "order/created" } },
 //   async ({ event, step }) => { ... }
 // );
 
@@ -237,10 +245,23 @@ Each inline callback becomes a named function with `"use step"` on the first lin
 ```ts
 async function loadOrder(id: string) {
   "use step"; // [!code highlight]
-  return fetch(`/api/orders/${id}`).then((r) => r.json());
+  return fetch(`https://example.com/api/orders/${id}`).then((r) => r.json());
+}
+```
+
+Configure per-step retry counts by assigning `maxRetries` as a function property:
+
+```ts
+async function callApi(endpoint: string) {
+  "use step";
+  const response = await fetch(endpoint);
+  return response.json();
 }
+callApi.maxRetries = 5;
 ```
 
+See [Errors and retries](/docs/foundations/errors-and-retries) for full retry docs.
+
 ### Step 4: Replace `waitForEvent`, `sleep`, and `invoke`
 
 - `step.waitForEvent(...)` → `createHook({ token })` + `await hook`. Resume it from an API route with `resumeHook(token, payload)`.
@@ -266,6 +287,13 @@ export async function POST(req: Request) {
 
 Remove the `inngest` client, the `serve()` route, event schemas, and the Inngest Dev Server from the app. Verify the run in `npx workflow web` before shipping.
 
+## Features without a 1:1 equivalent
+
+- **Cron / scheduled functions (`triggers: { cron: '...' }`).** The SDK has no built-in scheduler. Trigger runs from Vercel Cron or a system cron calling `start()` from an API route.
+- **Concurrency, throttling, rate limiting, debounce, singleton, priority, and `batchEvents`.** These function-level settings have no direct analog. Enforce limits inside steps (semaphores, external rate-limiter service) or debounce at the publisher before calling `start()`.
+- **`EventSchemas` / typed events.** The event-bus indirection goes away; publishers import the workflow function directly, giving the same type safety through a different mechanism.
+- **Event-bus fan-out by name match.** `inngest.send()` that triggered multiple functions by event name must be replaced by explicit `start()` calls for each target workflow.
+
 ## Quick-start checklist
 
 - Replace `inngest.createFunction()` with a `"use workflow"` function; launch it with `start()`.
@@ -280,3 +308,7 @@ Remove the `inngest` client, the `serve()` route, event schemas, and the Inngest
 - Use `getStepMetadata().stepId` as the idempotency key for external side effects.
 - Replace `step.realtime.publish()` with `getWritable()`.
 - Deploy and verify end-to-end with the built-in observability UI.
+
+---
+
+*Verified against `workflow@5.0.0-beta.1` and Inngest TypeScript SDK v4 on 2026-04-16.*

package/docs/migration-guides/migrating-from-temporal.mdx

@@ -27,7 +27,7 @@ npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-
 - Streaming is built in. Durable progress writes go to named streams via `getWritable({ namespace })`, and clients read them directly. No separate WebSocket, SSE, or progress-polling layer to operate.
 - Infrastructure and orchestration live in a single deployment. There is no separate Worker fleet or Temporal Server to run. The runtime, step logic, and orchestration share the app's observability and log aggregation.
 - TypeScript-first developer experience. Workflows and steps live in the same file with plain `await` control flow, `try/catch`, and `Promise.all`.
-- Agent-first tooling. A first-class CLI (`npx workflow`), `@workflow/ai` integration for durable AI agents, and a bundled Claude skill for AI-assisted authoring.
+- Agent-first tooling. A first-class CLI (`npx workflow`), [`@workflow/ai` integration for durable AI agents](/docs/ai), and a bundled Claude skill for AI-assisted authoring.
 - Per-step retry controls. `RetryableError`, `FatalError`, and `maxRetries` live at the step boundary instead of an Activity-level retry policy configured elsewhere.
 
 ## What changes when you leave Temporal
@@ -36,6 +36,8 @@ Temporal requires operating a control plane (Temporal Server or Cloud), a Worker
 
 The Workflow SDK runs on managed infrastructure. Write `"use workflow"` functions that orchestrate `"use step"` functions in the same file, in plain TypeScript. There are no Workers, Task Queues, or separate Activity modules. Durable replay, automatic retries, and event history are handled by the runtime.
 
+Workflow functions must still be deterministic — no `Date.now()`, `Math.random()`, direct network I/O, or wall-clock branches inside `"use workflow"`. Move any such logic into a step, as you do today with Activities.
+
 Migration removes infrastructure and collapses indirection. Business logic stays as regular async TypeScript.
 
 ## Concept mapping
@@ -47,10 +49,10 @@ Migration removes infrastructure and collapses indirection. Business logic stays
 | Worker + Task Queue | Managed execution | No worker fleet or polling loop to operate. |
 | Signal | `createHook()` or `createWebhook()` | Use hooks for typed resume signals; webhooks for HTTP callbacks. |
 | Query | `getWritable({ namespace: 'status' })` stream | Durably stream status updates from the workflow. Clients read from the stream instead of polling a database. |
-| Update | `createHook()` + `resumeHook()` | Writes go through hooks. |
+| Update | `createHook()` + `resumeHook()` (one-way) | Temporal Updates return a value to the caller; hooks do not. If the Update returns data, either write the result to a named stream via `getWritable()` and have the caller read from it, or keep an HTTP read route that fetches the workflow's current state. |
 | Child Workflow | `"use step"` wrappers around `start()` / `getRun()` | Spawn from a step and return the `Run` object so observability can deep-link into child runs. |
 | Activity retry policy | Step retries, `RetryableError`, `FatalError`, `maxRetries` | Retries live at the step boundary. |
-| Event History | Workflow event log / run timeline | Same durable replay, fewer surfaces to manage. |
+| Event History | Workflow event log / run timeline | Same durable replay; built-in observability UI replaces Temporal Web. Search attributes and visibility APIs have no direct equivalent — filter by run status and timestamps instead. |
 
 ## Translate your first workflow
 
@@ -60,6 +62,9 @@ Start with the directive change. The Temporal definition proxies activities thro
 
 {/* @skip-typecheck: Temporal SDK types not available */}
 ```typescript title="workflows/order.ts (Temporal)"
+import * as wf from '@temporalio/workflow';
+import type * as activities from './activities';
+
 const { chargePayment } = wf.proxyActivities<typeof activities>({
   startToCloseTimeout: '5 minutes',
 });
@@ -143,6 +148,8 @@ export async function refundWorkflow(refundId: string) {
 
 The workflow suspends durably at `await approval` until resumed. No polling, no handler registration.
 
+Requires TypeScript 5.2+ for the `using` keyword. On older TypeScript, assign the hook to a `const` and call `resumeHook()` from the consuming code path.
+
 ### Resuming from an API route
 
 Any HTTP caller can resume by token:
@@ -201,6 +208,22 @@ Call both steps from the parent in sequence: `const result = await collectResult
 
 <Callout type="warn">
 Activity retry policy moves to the step boundary. Use `maxRetries`, `RetryableError`, and `FatalError` on each step instead of a single workflow-wide retry block.
+
+Temporal's per-activity timeouts (`startToCloseTimeout`, `scheduleToCloseTimeout`, `heartbeatTimeout`) have no direct Workflow SDK equivalent. Enforce per-step deadlines inside the step using `AbortSignal.timeout(ms)` (e.g. on `fetch`), or wrap the call from the workflow in `Promise.race(step(), sleep('5m'))` to bail out after a bounded duration.
+
+Temporal's retry policy knobs (`initialInterval`, `backoffCoefficient`, `maximumInterval`, `nonRetryableErrorTypes`) don't port 1:1 — only `maxRetries` is configurable at the step boundary. Classify retryability with `RetryableError` (retryable) and `FatalError` (terminal) instead of listing error types, and control the delay between attempts with `new RetryableError(msg, { retryAfter: '5s' })`.
+
+Set `maxRetries` as a property assignment on the step function:
+
+```typescript
+async function chargePayment(orderId: string) {
+  "use step";
+  // ...
+}
+chargePayment.maxRetries = 5;
+```
+
+See [/docs/foundations/errors-and-retries](/docs/foundations/errors-and-retries) for full retry docs.
 </Callout>
 
 ## What you stop operating
@@ -250,7 +273,7 @@ export async function processOrder(orderId: string) {
 
 ### Step 4: Replace Signals with hooks
 
-Swap `defineSignal` + `setHandler` for `createHook()`. Callers `resumeHook(token, payload)` instead of `client.workflow.signal(...)`.
+Swap `defineSignal` + `setHandler` for `createHook()`. Callers `resumeHook(token, payload)` instead of `handle.signal(signalDef, payload)` on a `WorkflowHandle` obtained from `client.workflow.getHandle(workflowId)`.
 
 ### Step 5: Start runs from an API route or server action
 
@@ -271,6 +294,14 @@ export async function POST(req: Request) {
 
 Remove the Worker process, `@temporalio/*` dependencies, and the Temporal Server or Cloud connection. Verify the run in the built-in observability UI (`npx workflow web`) before shipping.
 
+## Features without a 1:1 equivalent
+
+- **Search attributes / visibility queries.** Temporal's search attribute system has no direct analog. Filter runs by status and timestamps via `getRun()` / observability UI.
+- **Event history archival.** Temporal archives histories to S3/GCS for long-term retention. Workflow SDK event logs are durable, but retention depends on the integration you are using. For example, see [Vercel Workflow Storage Retention](https://vercel.com/docs/workflows/pricing#storage-retention) for Vercel.
+- **Per-activity timeouts (`startToCloseTimeout`, `scheduleToCloseTimeout`, `heartbeatTimeout`).** Implement deadlines inside the step with `AbortSignal.timeout(ms)`, or wrap the call in `Promise.race(step(), sleep(...))` from the workflow.
+- **Rich retry policy (`initialInterval`, `backoffCoefficient`, `maximumInterval`, `nonRetryableErrorTypes`).** Only `maxRetries` is configurable. Classify retryability with `RetryableError`/`FatalError`; control delay between attempts via `new RetryableError(msg, { retryAfter: '5s' })`.
+- **Workers + task queues.** Managed deployments replace workers; self-hosted deployments still need a `World` implementation (see [/docs/deploying/world](/docs/deploying/world)).
+
 ## Quick-start checklist
 
 - Move orchestration into a `"use workflow"` function.
@@ -282,3 +313,6 @@ Remove the Worker process, `@temporalio/*` dependencies, and the Temporal Server
 - Use `getStepMetadata().stepId` as the idempotency key for external side effects.
 - Stream status and progress from steps with `getWritable({ namespace: 'status' })`, and have clients read from the stream instead of polling.
 - Deploy the app and verify runs end-to-end in the built-in observability UI.
+
+---
+*Verified against `workflow@5.0.0-beta.1` and `@temporalio/workflow@1.16` on 2026-04-16.*

package/docs/migration-guides/migrating-from-trigger-dev.mdx

@@ -32,7 +32,7 @@ npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-
 
 ## What changes when you leave trigger.dev?
 
-trigger.dev v3 defines durable work with `task()` or `schemaTask()` from `@trigger.dev/sdk/v3`, deploys tasks to the trigger.dev cloud or a self-hosted instance, and triggers runs via `tasks.trigger()`. A separate worker fleet picks up runs, applies retry policies, and routes `wait.for`, `wait.forToken`, and `metadata.stream` calls through the platform.
+trigger.dev v3 defines durable work with `task()` or `schemaTask()` from `@trigger.dev/sdk` (trigger.dev v3), deploys tasks to the trigger.dev cloud or a self-hosted instance, and triggers runs via `tasks.trigger()`. A separate worker fleet picks up runs, applies retry policies, and routes `wait.for`, `wait.forToken`, and `metadata.stream` calls through the platform.
 
 The Workflow SDK replaces that with `"use workflow"` functions that orchestrate `"use step"` functions in plain TypeScript. There is no task registry, separate deploy target, or SDK client. Durable replay, retries, and event history ship with the runtime.
 
@@ -46,21 +46,25 @@ Migration collapses the task abstraction into plain async functions. Business lo
 | `schemaTask({ schema, run })` | Typed function + `"use workflow"` | Validate inputs at the call site. |
 | Inline `run` body | `"use step"` function | Side effects move into named steps. |
 | `logger` / `metadata.set` | `console` + `getWritable({ namespace: 'status' })` | Logs flow through the run timeline. Status writes go on a named stream. |
-| `wait.for({ seconds })` / `wait.until({ date })` | `sleep()` | Import from `workflow`. |
+| `wait.for({ seconds \| minutes \| hours \| days })` / `wait.until({ date })` | `sleep()` | Import from `workflow`. |
 | `wait.forToken({ timeout })` | `createHook()` + `Promise.race` with `sleep()` | Hooks carry a typed token. |
 | `tasks.trigger()` / `triggerAndWait()` | `start()` and `getRun(runId).returnValue` | Wrap both in `"use step"` functions. |
 | `batch.triggerAndWait()` | `Promise.all(runIds.map(collectResult))` | Fan out via standard concurrency. |
 | `AbortTaskRunError` | `FatalError` | Stops retries immediately. |
-| `retry.onThrow` / `retry.fetch` | `RetryableError`, `FatalError`, `maxRetries` | Retry lives on the step. Exponential backoff is a step `maxRetries` config, not a helper. |
-| `metadata.stream()` / Realtime | `getWritable()` / `getWritable({ namespace })` | Named streams are the canonical read channel. Clients read from the end of the stream for current status. Do not poll `getRun()` or persist status to a database for client reads. |
+| `retry.onThrow` / `retry.fetch` | `RetryableError`, `FatalError`, `maxRetries` | Retry count lives on the step via `myStep.maxRetries = N` (default 3). Control delay between attempts by throwing `new RetryableError(msg, { retryAfter: '5s' })` — there is no built-in exponential helper; compute the delay yourself based on `getStepMetadata().attempt` if you need one. |
+| `metadata.stream()` / Realtime | `getWritable()` / `getWritable({ namespace })` | For granular business status (progress updates, current-stage messages), prefer writing to `getWritable({ namespace: 'status' })` from a step and reading from the end of the named stream on the client. Use `getRun(runId).status` for terminal/lifecycle state only. |
 | Self-hosted worker + dashboard | Managed execution + built-in UI | No worker fleet to operate. |
 
 ## Translate your first workflow
 
+<Callout type="warn">
+trigger.dev's `task.run` body has full Node.js access. The SDK's `'use workflow'` body runs in a sandboxed VM — side effects (I/O, `Date.now()`, `Math.random()`, DB, fetch) must live inside `'use step'` functions. Orchestration stays in the workflow body.
+</Callout>
+
 Start with the shell. trigger.dev wraps the handler in `task()`; the Workflow SDK marks the function with a directive.
 
 ```typescript title="trigger/order.ts (trigger.dev)"
-import { task } from '@trigger.dev/sdk/v3';
+import { task } from '@trigger.dev/sdk';
 
 export const processOrder = task({
   id: 'process-order',
@@ -116,7 +120,7 @@ No id lookup, no API key, no separate worker. `start()` returns a handle immedia
 
 {/* @skip-typecheck: trigger.dev SDK types not available */}
 ```typescript title="workflow/workflows/refund.ts (trigger.dev, abbreviated)"
-// import { wait } from '@trigger.dev/sdk/v3';
+// import { wait } from '@trigger.dev/sdk';
 const token = await wait.createToken({ timeout: '7d' });
 const approval = await wait.forToken<{ approved: boolean }>(token.id).unwrap();
 // External system resumes with: await wait.completeToken(token.id, { approved: true });
@@ -130,10 +134,17 @@ using approval = createHook<{ approved: boolean }>({ // [!code highlight]
 const payload = await approval;
 ```
 
-**What changed:** the platform-issued opaque token becomes an app-owned string. The caller that resumes the run supplies that same string, so there is no token lookup.
+**What changed:** the platform-issued opaque token becomes an app-owned string. The caller that resumes the run supplies that same string, so there is no token lookup. (trigger.dev also exposes `token.url` for external callers; the SDK analog is `createWebhook().url`).
 
 ### Resume from an API route
 
+There are two shapes of resume, and `wait.forToken` can map to either:
+
+- **Server-side resume (known token):** `createHook<T>({ token: 'business-token' })` + `resumeHook(token, payload)` from an API route. Use this when your app knows the token shape and controls the resume call.
+- **Third-party callback URL (generated token):** `createWebhook({ respondWith: 'default' })` + pass `webhook.url` to the external system. The external system hits the URL to resume.
+
+See [`/docs/foundations/hooks`](/docs/foundations/hooks) for both surfaces.
+
 trigger.dev completes a token with `wait.completeToken(tokenId, { approved })`. The SDK equivalent is `resumeHook`:
 
 ```typescript title="app/api/refunds/[refundId]/approve/route.ts"
@@ -164,13 +175,15 @@ return { refundId, status: 'approved' };
 ```
 
 <Callout type="info">
-A hook is an inbound write channel. The caller that knows the token resumes the run with a typed payload. To expose in-flight state to a dashboard, write updates from a step with `getWritable()` (or `getWritable({ namespace: 'status' })`), and have the client read from the end of that named stream.
+A hook is an inbound write channel. The caller that knows the token resumes the run with a typed payload. For granular business status (progress updates, current-stage messages), prefer writing to `getWritable({ namespace: 'status' })` from a step and reading from the end of the named stream on the client. Use `getRun(runId).status` for terminal/lifecycle state only.
 </Callout>
 
 ## Spawn a child workflow
 
 `triggerAndWait()` splits into two steps: spawn and collect. `start()` and `getRun()` are runtime APIs, so wrap them in `"use step"` functions. Return the full `Run` object from `spawnChild` so observability tooling can deep-link to the child run.
 
+You can return either the full `Run` object (enables deep-linking) or just `run.runId` (simpler). The runtime serializes `Run` to its `runId` in the event log either way.
+
 ```typescript title="workflow/workflows/parent.ts"
 import { start } from 'workflow/api';
 
@@ -200,12 +213,14 @@ export async function parentWorkflow(item: string) {
 
 To fan out, call `spawnChild` inside a loop, then `Promise.all` the `collectResult` calls. That replaces `batch.triggerAndWait()`.
 
+`Promise.all` rejects on first failure; use `Promise.allSettled` if you need batch-mode error tolerance similar to trigger.dev's `{ ok, output, error }` per-run result.
+
 ## What you stop operating
 
 Dropping the trigger.dev SDK removes several moving parts:
 
 - **No task registry or `id` strings.** Workflow files carry directive annotations and export plain functions.
-- **No `@trigger.dev/sdk/v3` client or API key.** `start()` launches runs directly from API routes or server actions.
+- **No `@trigger.dev/sdk` client or API key.** `start()` launches runs directly from API routes or server actions.
 - **No worker fleet or self-hosted instance.** The runtime schedules execution inside the app's deploy target.
 - **No separate Realtime channel.** `getWritable()` streams updates from steps over the run's durable stream.
 - **No dashboard account.** The built-in observability UI (`npx workflow web`) reads the same event log the runtime writes.
@@ -218,7 +233,7 @@ Pick one trigger.dev task and migrate it end-to-end before touching the rest. Th
 
 ### Step 1: Install the Workflow SDK
 
-Add the runtime. The Next.js integration ships as the `workflow/next` subpath of the same package.
+Add the runtime. Framework integrations (Next.js, Nitro, Nuxt, SvelteKit, Astro, Nest) are subpath exports of the same `workflow` package, e.g. `workflow/next` — no additional install needed.
 
 ```bash
 pnpm add workflow
@@ -255,7 +270,7 @@ async function loadOrder(id: string) {
 
 ### Step 4: Replace `wait.*` with hooks and `sleep`
 
-- `wait.for({ seconds })` / `wait.until({ date })` → `sleep('5m')` or `sleep(date)` from `workflow`.
+- `wait.for({ seconds | minutes | hours | days })` / `wait.until({ date })` → `sleep('5m')` or `sleep(date)` from `workflow`.
 - `wait.forToken(token)` → `createHook({ token })` + `await`. Complete it with `resumeHook(token, payload)` from an API route.
 - `wait.forToken({ timeout })` → `Promise.race([hook, sleep(timeout)])`.
 - `triggerAndWait(payload)` → wrap `start(child, [payload])` in a `"use step"` function and return the `Run` object, then read the result with a second step that calls `getRun(runId).returnValue`.
@@ -279,6 +294,29 @@ export async function POST(req: Request) {
 
 Remove the `@trigger.dev/sdk` dependency, the `trigger.config.ts` file, the `trigger/` directory, and any self-hosted worker deployment. Delete dashboard API keys from the environment. Verify the run in `npx workflow web` before shipping.
 
+## Retries on steps
+
+Retry count lives on the step function itself. Set it as a property on the step:
+
+```typescript
+async function chargePayment(orderId: string) {
+  "use step";
+  // ...
+}
+chargePayment.maxRetries = 5;
+```
+
+Throw `new RetryableError(msg, { retryAfter: '5s' })` to control delay between attempts, or `FatalError` to stop retries immediately. See [`/docs/foundations/errors-and-retries`](/docs/foundations/errors-and-retries).
+
+## Features without a 1:1 equivalent
+
+- **`schedules.task()` / cron triggers.** The SDK has no built-in scheduler. Trigger runs from Vercel Cron or a system cron calling `start()`.
+- **Concurrency keys / queue concurrency limits.** No direct analog. Enforce limits inside steps (semaphores, external coordinator) or debounce at the publisher.
+- **`machine` presets / custom images.** Machine specs are per-task in trigger.dev; in the SDK, function resources are per-deployment (configure via your hosting platform).
+- **Realtime / `subscribeToRun`.** Use `getRun(runId).getReadable()` plus named `getWritable()` streams for live progress.
+- **`onFailure` lifecycle hook.** No equivalent. Handle cleanup in the workflow body with a try/catch + compensation-stack pattern.
+- **Trigger.dev dashboard.** Workflow SDK ships `npx workflow web` for local inspection and the Vercel Observability tab for deployed runs.
+
 ## Quick-start checklist
 
 - Replace `task({ id, run })` with a `"use workflow"` function; launch it with `start()`.
@@ -294,3 +332,6 @@ Remove the `@trigger.dev/sdk` dependency, the `trigger.config.ts` file, the `tri
 - Replace `metadata.stream()` and Realtime with `getWritable()`.
 - Remove the `@trigger.dev/sdk` dependency, `trigger.config.ts`, and any self-hosted worker.
 - Deploy and verify runs end-to-end with the built-in observability UI.
+
+---
+*Verified against `workflow@5.0.0-beta.1` and `@trigger.dev/sdk` v3 on 2026-04-16.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.2",
+  "version": "5.0.0-beta.4",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -56,18 +56,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.2",
-    "@workflow/core": "5.0.0-beta.2",
+    "@workflow/astro": "5.0.0-beta.4",
+    "@workflow/cli": "5.0.0-beta.4",
+    "@workflow/core": "5.0.0-beta.4",
     "@workflow/errors": "5.0.0-beta.1",
-    "@workflow/cli": "5.0.0-beta.2",
-    "@workflow/typescript-plugin": "5.0.0-beta.2",
-    "@workflow/next": "5.0.0-beta.2",
+    "@workflow/typescript-plugin": "5.0.0-beta.3",
     "@workflow/utils": "5.0.0-beta.1",
-    "@workflow/nuxt": "5.0.0-beta.2",
-    "@workflow/nest": "5.0.0-beta.2",
-    "@workflow/nitro": "5.0.0-beta.2",
-    "@workflow/sveltekit": "5.0.0-beta.2",
-    "@workflow/rollup": "5.0.0-beta.2"
+    "@workflow/next": "5.0.0-beta.4",
+    "@workflow/nest": "5.0.0-beta.4",
+    "@workflow/nuxt": "5.0.0-beta.4",
+    "@workflow/sveltekit": "5.0.0-beta.4",
+    "@workflow/rollup": "5.0.0-beta.4",
+    "@workflow/nitro": "5.0.0-beta.4"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",