workflow 5.0.0-beta.2 → 5.0.0-beta.21

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. |
+| `tasks.trigger()` / `triggerAndWait()` | `start()` and `getRun(runId).returnValue` | Call `start()` directly; wrap `getRun()` collection in a `"use step"` function. |
 | `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,26 +175,19 @@ 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.
-
-```typescript title="workflow/workflows/parent.ts"
-import { start } from 'workflow/api';
+`triggerAndWait()` splits into spawn and collect. In v5, call `start()` directly from the workflow to spawn the child. Wrap `getRun()` and `returnValue` access in a `"use step"` function when you need to collect the result.
 
-async function spawnChild(item: string) {
-  'use step';
-  return start(childWorkflow, [item]); // [!code highlight]
-}
-```
+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.
 
-Await the result in a second step, then orchestrate both from the parent:
+Await the result in a step, then orchestrate both from the parent:
 
 ```typescript title="workflow/workflows/parent.ts"
-import { getRun } from 'workflow/api';
+import { getRun, start } from 'workflow/api';
 
 async function collectResult(runId: string) {
   'use step';
@@ -193,19 +197,21 @@ async function collectResult(runId: string) {
 
 export async function parentWorkflow(item: string) {
   'use workflow';
-  const child = await spawnChild(item);
+  const child = await start(childWorkflow, [item]); // [!code highlight]
   return await collectResult(child.runId);
 }
 ```
 
-To fan out, call `spawnChild` inside a loop, then `Promise.all` the `collectResult` calls. That replaces `batch.triggerAndWait()`.
+To fan out, call `start()` 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 +224,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,10 +261,10 @@ 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`.
+- `triggerAndWait(payload)` → call `start(child, [payload])` from the workflow and return the `Run` object, then read the result with a step that calls `getRun(runId).returnValue`.
 
 ### Step 5: Start runs from the app
 
@@ -279,6 +285,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()`.
@@ -286,7 +315,7 @@ Remove the `@trigger.dev/sdk` dependency, the `trigger.config.ts` file, the `tri
 - Swap `wait.for` / `wait.until` for `sleep()` from `workflow`.
 - Swap `wait.forToken` for `createHook()` (internal) or `createWebhook()` (HTTP).
 - Model `wait.forToken` timeouts as `Promise.race()` between the hook and `sleep()`.
-- Replace `triggerAndWait()` with `"use step"` wrappers around `start()` and `getRun()`.
+- Replace `triggerAndWait()` with direct `start()` calls and a `"use step"` wrapper around `getRun()` when collecting results.
 - Replace `batch.triggerAndWait()` with `Promise.all` over the collected child `Run` handles.
 - Move `schemaTask` validation to the call site; pass typed arguments into the workflow.
 - Replace `AbortTaskRunError` with `FatalError`; model retries per step with `RetryableError` and `maxRetries`.
@@ -294,3 +323,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/docs/observability/attributes.mdx

@@ -0,0 +1,87 @@
+---
+title: Attributes
+description: Attach experimental metadata to workflow runs for observability.
+type: reference
+summary: Add string attributes to a workflow run.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/api-reference/workflow/experimental-set-attributes
+  - /docs/api-reference/workflow-errors/workflow-world-error
+---
+
+<Callout type="warn">
+This feature is experimental and may change before the stable attributes API is released.
+</Callout>
+
+[`experimental_setAttributes`](/docs/api-reference/workflow/experimental-set-attributes) attaches plaintext string metadata to the current workflow run. These attributes are displayed in observability CLI/UI.
+In the future, you'll be able to search and filter runs by attributes.
+
+You can also seed any attributes directly when starting a run:
+
+{/* @skip-typecheck: abbreviated usage; orderWorkflow is defined below */}
+```typescript lineNumbers
+const run = await start(orderWorkflow, ["ord_123"], {
+  attributes: { source: "checkout" }, // [!code highlight]
+})
+```
+
+```typescript lineNumbers
+import { experimental_setAttributes } from "workflow"
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow"
+
+  await experimental_setAttributes({ // [!code highlight]
+    phase: "received", // [!code highlight]
+    orderId, // [!code highlight]
+  }) // [!code highlight]
+
+  // ...work...
+
+  await experimental_setAttributes({ phase: "complete" }) // [!code highlight]
+}
+```
+
+## Usage
+
+Call [`experimental_setAttributes`](/docs/api-reference/workflow/experimental-set-attributes) from a `"use workflow"` function or a `"use step"` function. Plain application code is not supported because there is no active workflow run to attach attributes to.
+
+Values must be strings. Pass `undefined` to remove a key:
+
+```typescript lineNumbers
+import { experimental_setAttributes } from "workflow"
+
+export async function cleanupAttributes() {
+  "use workflow"
+
+  await experimental_setAttributes({ staleKey: undefined }) // [!code highlight]
+}
+```
+
+Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
+
+## Viewing attributes
+
+The run details panel in the observability UI shows the run's current attributes as key-value rows. Reserved `$`-prefixed keys are marked with a badge and sorted after user keys:
+
+![Run details panel showing the Attributes card with reserved keys badged](/screenshots/attributes/run-details-attributes.png)
+
+Each `experimental_setAttributes` call appears on the trace timeline as a diamond marker at the moment the attributes were written:
+
+![Trace timeline with attr_set diamond markers on the run row](/screenshots/attributes/trace-timeline.png)
+
+Expanding an `attr_set` event — in the run sidebar or the Events tab — shows the changed keys, removed keys, and whether the write came from the workflow body or a step (with the attempt number):
+
+![Expanded attr_set events showing changes and the writer](/screenshots/attributes/run-details-attr-set-events.png)
+
+## Experimental Behavior
+
+While attributes are experimental:
+
+- Attributes require a World implementing spec version 4 or later.
+- Writes from workflow and step bodies append native `attr_set` events and immediately materialize `run.attributes`.
+- Storage errors surface rather than being silently ignored: transient errors on workflow-body writes are retried, and a write the World rejects as invalid (for example, exceeding the per-run attribute cap across multiple calls) fails the run with the validation error.
+- Step-body storage errors throw from `experimental_setAttributes` like any other step-side network write. Catch the error inside the step if the attribute is best-effort.
+- Reading and querying attributes is not available yet. A query API is planned.

package/docs/observability/index.mdx

@@ -1,7 +1,7 @@
 ---
 title: Observability
 description: Inspect, monitor, and debug workflows through the CLI and Web UI with powerful observability tools.
-type: guide
+type: overview
 summary: Inspect and debug workflow runs using the CLI and Web UI.
 prerequisites:
   - /docs/foundations
@@ -42,6 +42,19 @@ npx workflow inspect runs --web
 
 ![Workflow SDK Web UI](/o11y-ui.png)
 
+To share a link to a specific run without opening a browser, use the `--url`
+flag. It prints the dashboard deep link to stdout and exits (no browser, no
+local server) — useful for scripts, PR comments, or automation. Add `--json` to
+get `{ "url": "..." }`.
+
+```bash
+# Print the deep-link URL for a run (no browser, no server)
+npx workflow inspect run <run_id> --url
+
+# Vercel runs: add the backend (and --env preview for preview deployments)
+npx workflow inspect run <run_id> --backend vercel --url
+```
+
 ## Backends
 
 The Workflow SDK CLI can inspect data from any [World](/docs/deploying). By default, it inspects data in your local development environment. For example, if you are using Next.js to develop workflows locally, the
@@ -63,3 +76,14 @@ npx workflow inspect runs --backend vercel
 ```
 
 When deployed to Vercel, workflow data is [encrypted end-to-end](/docs/how-it-works/encryption). Encrypted fields display as locked placeholders until you choose to decrypt them using the **Decrypt** button in the web UI or the `--decrypt` flag in the CLI.
+
+## More Observability Features
+
+<Cards>
+    <Card href="/docs/observability/tracing" title="Tracing">
+        Distributed tracing with OpenTelemetry for workflow runs, steps, and queue deliveries.
+    </Card>
+    <Card href="/docs/observability/attributes" title="Attributes">
+        Attach experimental metadata to workflow runs for observability.
+    </Card>
+</Cards>

package/docs/observability/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Observability",
-  "pages": ["observability"]
+  "pages": ["tracing", "attributes"]
 }

package/docs/observability/tracing.mdx

@@ -0,0 +1,106 @@
+---
+title: Tracing
+description: Distributed tracing with OpenTelemetry for workflow runs, steps, and queue deliveries.
+type: guide
+summary: Trace workflow execution end to end with OpenTelemetry.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/observability/attributes
+  - /docs/how-it-works/event-sourcing
+---
+
+The Workflow SDK is instrumented with [OpenTelemetry](https://opentelemetry.io) out of the box. It emits spans for workflow starts, every workflow and step invocation, and the HTTP calls it makes to the workflow backend — and it propagates trace context across queue deliveries so a run remains traceable end to end.
+
+The SDK only depends on the OpenTelemetry **API**, never on an SDK or exporter. If your application does not register an OpenTelemetry SDK, all tracing code is a silent no-op with no overhead and no behavior change.
+
+## Enabling tracing
+
+Register any OpenTelemetry Node SDK in your application. On Vercel with Next.js, the simplest setup is [`@vercel/otel`](https://vercel.com/docs/observability/otel-overview) in `instrumentation.ts`:
+
+```typescript title="instrumentation.ts" lineNumbers
+import { registerOTel } from "@vercel/otel"
+
+export function register() {
+  registerOTel({ serviceName: "my-app" })
+}
+```
+
+No workflow-specific configuration is required. As soon as a tracer provider and propagator are registered, the SDK's spans, context propagation, and span links activate automatically.
+
+## Spans
+
+| Span name | Kind | Emitted when |
+| --- | --- | --- |
+| `workflow.start <name>` | internal | `start()` is called in your application code |
+| `workflow.execute <name>` | consumer (root) | a queue delivery invokes the workflow — replay, orchestration, and inline steps run under it |
+| `step.execute <name>` | internal (inline) / consumer + root (queue-delivered) | a step function executes |
+| `http <method>` | client | the SDK calls the workflow backend (event reads/writes) |
+
+`<name>` is the short function name (for example `processOrder`); the full machine name, including the source module, is available in the `workflow.name` / `step.name` attributes.
+
+## Key attributes
+
+| Attribute | Description |
+| --- | --- |
+| `workflow.run.id` | The run ID (`wrun_...`). Present on every workflow and step span — the primary key for finding all spans of a run. |
+| `workflow.name` | The workflow function name. |
+| `workflow.trace.mode` | The active trace mode (`linked` or `continuous`). |
+| `workflow.trace.propagated` | Whether the invocation received trace context from the queue message. |
+| `workflow.queue.overhead_ms` | Time between the message being enqueued and the handler starting — queue dwell plus any cold start. |
+
+## Trace shape: one trace per invocation
+
+A single workflow run can span hours or days across many separate function invocations: every step completion, `sleep()` wake-up, and retry is a new queue delivery. Stitching all of that into one trace produces giant, slow-loading traces that most tracing backends truncate.
+
+Instead, the SDK creates **one bounded trace per invocation**. Each `workflow.execute` (or background `step.execute`) span starts a new trace root and attaches two **span links**:
+
+- a link to the **enqueue site** — the span that queued the message which triggered this invocation, and
+- a link to the **run origin** — the trace in which `start()` was originally called.
+
+A span link is OpenTelemetry's relationship for "causally related, but in a different trace." It is the standard pattern for asynchronous messaging, where producing and consuming a message can be separated by arbitrary time.
+
+```mermaid
+flowchart LR
+    O["start() request trace"]
+    A["invocation 1"]
+    B["invocation 2"]
+    C["invocation 3 ..."]
+    A -. "link" .-> O
+    B -. "link" .-> O
+    C -. "link" .-> O
+    B -. "link" .-> A
+    C -. "link" .-> B
+
+    style O fill:#a78bfa,stroke:#8b5cf6,color:#000
+```
+
+Each invocation links back to the trace that enqueued it and to the run origin.
+
+To see a whole run, query by attribute rather than by trace ID — for example `workflow.run.id = wrun_...` in your tracing backend — or follow the span links between invocation traces.
+
+## Trace modes
+
+The `WORKFLOW_TRACE_MODE` environment variable controls the shape:
+
+| Mode | Behavior |
+| --- | --- |
+| `linked` (default) | Each invocation is its own trace root with span links to the enqueue site and the run origin. Traces stay small; sampling is decided per invocation. |
+| `continuous` | The run-origin context becomes the **parent** of every invocation, so the entire run shares one trace ID. |
+
+<Callout type="warn">
+This is a behavior change from v4, which always used `continuous`-style tracing. If you have dashboards or queries that assume one trace ID per run, either update them to use `workflow.run.id` and span links, or set `WORKFLOW_TRACE_MODE=continuous` to restore the previous shape. Note that in `linked` mode each invocation root makes its own sampling decision, and the number of root spans increases to one per invocation.
+</Callout>
+
+## Context propagation
+
+When tracing is enabled, the SDK propagates [W3C Trace Context](https://www.w3.org/TR/trace-context/) on its outbound calls:
+
+- **Backend requests** carry `traceparent`, `tracestate`, and `baggage` headers, so backend spans can join your trace.
+- **Queue messages** carry the run-origin trace context in the message payload, and the queue re-delivers the producer's context to the workflow handler, where it becomes the enqueue-site span link.
+- **Baggage** carries `workflow.run_id` and `workflow.name` entries during workflow execution, allowing downstream services you call from steps to tag their own telemetry with the run ID.
+
+<Callout>
+Baggage entries set by your application are propagated as a `baggage` HTTP header on the SDK's backend requests, like any other OpenTelemetry-instrumented HTTP call. Avoid placing sensitive values in baggage.
+</Callout>

package/docs/testing/index.mdx

@@ -109,7 +109,7 @@ That's it. The plugin automatically:
 
 1. Transforms `"use workflow"` and `"use step"` directives via SWC
 2. Builds workflow and step bundles before tests run
-3. Sets up an in-process workflow runtime using a fresh [Local World](/docs/worlds/local) instance in each test worker — all workflow data is cleared automatically between test files for full isolation
+3. Sets up an in-process workflow runtime using a fresh [Local World](/worlds/local) instance in each test worker — all workflow data is cleared automatically between test files for full isolation
 
 <Callout type="info">
 Use a separate Vitest configuration and a distinct file naming convention (e.g. `*.integration.test.ts`) to keep unit tests and integration tests separate. Unit tests run with a standard Vitest config without the workflow plugin, while integration tests use the config above.
@@ -117,7 +117,7 @@ Use a separate Vitest configuration and a distinct file naming convention (e.g.
 
 ### Writing Integration Tests
 
-Use [`start()`](/docs/api-reference/workflow-api/start) to trigger a workflow and [`run.returnValue`](/docs/api-reference/workflow-api/start#returnvalue) to get the result. `returnValue` is a promise that blocks until the workflow completes (or throws if it fails):
+Use [`start()`](/docs/api-reference/workflow-api/start) to trigger a workflow and [`run.returnValue`](/docs/api-reference/workflow-api/start#returns) to get the result. `returnValue` is a promise that blocks until the workflow completes (or throws if it fails):
 
 ```typescript title="workflows/calculate.integration.test.ts" lineNumbers
 import { describe, it, expect } from "vitest";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.2",
+  "version": "5.0.0-beta.21",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -29,6 +29,7 @@
     ".": {
       "types": "./dist/index.d.ts",
       "workflow": "./dist/workflow.js",
+      "node": "./dist/index.js",
       "require": "./dist/typescript-plugin.cjs",
       "default": "./dist/index.js"
     },
@@ -56,18 +57,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.2",
-    "@workflow/core": "5.0.0-beta.2",
-    "@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/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/astro": "5.0.0-beta.21",
+    "@workflow/cli": "5.0.0-beta.21",
+    "@workflow/errors": "5.0.0-beta.8",
+    "@workflow/typescript-plugin": "5.0.0-beta.4",
+    "@workflow/utils": "5.0.0-beta.4",
+    "@workflow/core": "5.0.0-beta.21",
+    "@workflow/next": "5.0.0-beta.21",
+    "@workflow/nest": "5.0.0-beta.21",
+    "@workflow/nitro": "5.0.0-beta.21",
+    "@workflow/nuxt": "5.0.0-beta.21",
+    "@workflow/sveltekit": "5.0.0-beta.21",
+    "@workflow/rollup": "5.0.0-beta.21"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",

package/docs/api-reference/workflow-api/world/meta.json

@@ -1,4 +0,0 @@
-{
-  "title": "World SDK",
-  "pages": ["storage", "streams", "queue", "observability"]
-}