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

package/docs/how-it-works/understanding-directives.mdx

@@ -21,7 +21,7 @@ This page explores how directives enable this execution model and the design pri
 
 To understand how directives work, let's first understand what workflows and steps are in the Workflow SDK.
 
-## Workflows and Steps Primer
+## Workflows and steps primer
 
 The Workflow SDK has two types of functions:
 
@@ -58,7 +58,7 @@ export async function onboardUser(userId: string) {
 **The key insight:** Workflows resume from suspension by replaying their code using cached step results from the [event log](/docs/how-it-works/event-sourcing). When a step like `await fetchUserData(userId)` is called:
 
 - **If already executed:** Returns the cached result immediately from the event log
-- **If not yet executed:** Suspends the workflow, enqueues the step for background execution, and resumes later with the result
+- **If not yet executed:** Suspends the workflow, executes the step (usually inline in the same invocation, or through the queue when the invocation runs out of inline budget or nears its timeout), then resumes with the result
 
 This replay mechanism requires deterministic code. If `Math.random()` weren't seeded, the first execution might return `0.7` (sending the email) but replay might return `0.3` (skipping it), thus breaking resumption. The Workflow SDK sandbox provides seeded `Math.random()` and `Date` to ensure consistent behavior across replays.
 
@@ -66,9 +66,9 @@ This replay mechanism requires deterministic code. If `Math.random()` weren't se
 For a deeper dive into workflows and steps, see [Workflows and Steps](/docs/foundations/workflows-and-steps).
 </Callout>
 
-## The Core Challenge
+## The core challenge
 
-This execution model enables powerful durability features - workflows can suspend for days, survive restarts, and resume from any point. However, it also requires a semantic boundary in the code that tells **the compiler, runtime, and developer** that execution semantics have changed.
+This execution model provides durability: workflows can suspend for days, survive restarts, and resume from any point. However, it also requires a semantic boundary in the code that tells **the compiler, runtime, and developer** that execution semantics have changed.
 
 The challenge: how do we mark this boundary in a way that:
 
@@ -77,7 +77,7 @@ The challenge: how do we mark this boundary in a way that:
 3. Allows static analysis of workflow structure
 4. Feels natural to JavaScript developers
 
-Let's look at where directives have been used before, and the alternatives we considered:
+Directives have prior uses, and we considered several alternatives:
 
 ## Prior art on directives
 
@@ -104,11 +104,11 @@ The `"use workflow"` directive is also used by the Language Server Plugin shippe
 
 But we didn't get here immediately. This took some discovery to arrive at:
 
-## Alternatives We Explored
+## Alternatives we explored
 
-Before settling on directives, we prototyped several other approaches. Each had significant limitations that made them unsuitable for production use.
+Before settling on directives, we prototyped several other approaches. Each had limitations that made them unsuitable for production use.
 
-### Runtime-Only "Suspense" API
+### Runtime-only "Suspense" API
 
 Our first proof of concept used a wrapper-based API without a build step:
 
@@ -140,7 +140,7 @@ export const myWorkflow = workflow(async () => {
 });
 ```
 
-This was verbose and easy to forget. Moreover, if a developer forgot to wrap something innocent like using `Date.now()`, it led to unstable runtime behavior.
+This was verbose and developers could forget it. If a developer forgot to wrap something like `Date.now()`, it led to unstable runtime behavior.
 
 For example:
 
@@ -200,7 +200,7 @@ export const myWorkflow = workflow(async () => {
 });
 ```
 
-### Generator-Based API
+### Generator-based API
 
 We explored using generators for explicit suspension points, inspired by libraries like Effect.ts:
 
@@ -220,7 +220,7 @@ We're big fans of [Effect.ts](https://effect.website/) and the power of generato
 
 **1. Syntax felt more like a DSL than JavaScript**
 
-Generators require a custom mental model that differs significantly from familiar async/await patterns. The `yield*` syntax and generator delegation were unfamiliar to many developers:
+Generators require a custom mental model that differs from familiar async/await patterns. The `yield*` syntax and generator delegation were unfamiliar to many developers:
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript lineNumbers
@@ -267,7 +267,7 @@ export const myWorkflow = workflow(function*() {
 
 The generator syntax addressed suspension but didn't solve the fundamental sandboxing problem.
 
-### File System-Based Conventions
+### File system-based conventions
 
 We explored using file system conventions to identify workflows and steps, similar to how modern frameworks handle routing (Next.js, Hono, Nitro, SvelteKit):
 
@@ -282,7 +282,7 @@ We explored using file system conventions to identify workflows and steps, simil
   </Folder>
 </Files>
 
-With this approach, any function in the `workflows/` directory would be transformed as a workflow, and any function in `steps/` would be a step. No directives needed, just file locations.
+With this approach, any function in the `workflows/` directory would be transformed as a workflow, and any function in `steps/` would be a step. File locations would replace directives.
 
 **Why this could work:**
 
@@ -308,9 +308,9 @@ The directive approach solved all these issues: it works in any project structur
 
 ### Decorators
 
-We considered decorators, but they presented significant challenges both technical and ergonomic.
+We considered decorators, but they presented technical and ergonomic challenges.
 
-**Decorators are non-yet-standard and class-focused**
+**Decorators are not-yet-standard and class-focused**
 
 Decorators are not yet a standard syntax ([TC39 proposal](https://github.com/tc39/proposal-decorators)) and they currently only work with classes. A class decorator approach could look like this:
 
@@ -349,7 +349,7 @@ While decorators can be handled at compile-time with build tool support, they pr
 See the [Macro Wrapper](#macro-wrapper-approach) section below for a deeper dive into why this approach breaks down with concrete examples.
 </Callout>
 
-### Macro Wrapper Approach
+### Macro wrapper approach
 
 We also explored compile-time macro approaches - using a compiler to transform wrapper functions or decorators into directive-based code:
 
@@ -385,7 +385,7 @@ export const processOrder = async (orderId: string) => {
 };
 ```
 
-The benefit is that macros could enforce types and provide "Go To Definition" or other LSP features out of the box.
+The benefit is that macros could enforce types and provide "Go To Definition" or other LSP features without additional configuration.
 
 However, **the core problem remains: Workflows aren't runtime values**
 
@@ -431,7 +431,7 @@ To detect that `processOrder` is actually a workflow, the compiler would need wh
 
 This level of cross-function analysis is impractical for build tools - it would require analyzing every function call chain in your entire codebase and all dependencies. The compiler can only reliably detect direct `useWorkflow` calls, not calls hidden behind abstractions.
 
-## How Directives Solve These Problems
+## How directives solve these problems
 
 Directives address all the issues we encountered with previous approaches:
 
@@ -527,7 +527,7 @@ export async function processOrder(orderId: string) {
 
 The `"use step"` directive maintains consistency. While steps run in the full Node.js runtime and *could* work without a directive, they need some way to signal to the workflow runtime that they're steps.
 
-We could have used a function wrapper just for steps:
+We could have used a function wrapper for steps:
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript lineNumbers
@@ -584,7 +584,7 @@ By requiring explicit `"use step"` directives, developers have fine-grained cont
 To understand how directives are transformed at compile time, see [How the Code Transform Works](/docs/how-it-works/code-transform).
 </Callout>
 
-## What Directives Enable
+## What directives enable
 
 Because `"use workflow"` defines a compile-time semantic boundary, we can provide:
 
@@ -603,7 +603,7 @@ Because `"use workflow"` defines a compile-time semantic boundary, we can provid
   </Card>
 </Cards>
 
-## Directives as a JavaScript Pattern
+## Directives as a JavaScript pattern
 
 Directives in JavaScript have always been contracts between the developer and the execution environment. `"use strict"` made this pattern familiar - it's a string literal that changes how code is interpreted.
 
@@ -611,7 +611,7 @@ While JavaScript doesn't yet have first-class support for custom directives (lik
 
 As TC39 members, we at Vercel are actively working with the standards body and broader ecosystem to explore formal specifications for pragma-like syntax or macro annotations that can express execution semantics.
 
-## Closing Thoughts
+## Closing thoughts
 
 Directives aren't about syntax preference, they're about expressing semantic boundaries. `"use workflow"` tells the compiler, developer, and runtime that this code is deterministic, resumable, and sandboxed.
 

package/docs/internal/index.mdx

@@ -8,12 +8,14 @@ type: overview
 This page is only visible on preview deployments and local development. It does not appear in production.
 </Callout>
 
-## Preview Package
+## Preview package
 
 <PreviewInstall />
 
-## Draft Changelogs
+## Draft changelogs
 
-Changelog entries staged here for review before publishing to the Vercel website.
+Review these changelog entries before publishing them to the Vercel website.
 
-- [Serializable AbortController and AbortSignal](/docs/internal/serializable-abort-controller) — March 12, 2026
+- [Local web UI in Nitro dev](/docs/internal/nitro-web-ui): Unreleased (ships in 5.0.0)
+- [Native Nitro v3 bundling for workflows](/docs/internal/nitro-native-build): May 22, 2026
+- [Serializable AbortController and AbortSignal](/docs/internal/serializable-abort-controller): March 12, 2026

package/docs/internal/meta.json

@@ -1,5 +1,10 @@
 {
   "title": "Internal",
-  "pages": ["index", "serializable-abort-controller"],
+  "pages": [
+    "index",
+    "nitro-web-ui",
+    "nitro-native-build",
+    "serializable-abort-controller"
+  ],
   "defaultOpen": false
 }

package/docs/internal/nitro-native-build.mdx

@@ -0,0 +1,38 @@
+---
+title: Native Nitro v3 bundling for workflows
+description: Workflow routes are now bundled by Nitro v3, so steps run in your app's runtime and can call any server-side Nitro API.
+type: overview
+---
+
+# Native Nitro v3 bundling for workflows
+
+<span className="text-sm text-fd-muted-foreground">May 22, 2026</span>
+
+Workflow routes are now handled as Nitro v3 handlers and bundled by Nitro, rather than built separately for the Vercel Build Output API. Your workflows are part of the same bundle as the rest of your app.
+
+## What's new
+
+- **Call any server-side Nitro API from a step.** Workflow steps now run inside the same bundled runtime as the rest of your Nitro app, so you can call `useStorage()`, `useDatabase()`, `useRuntimeConfig()`, virtual imports, and any other server-side Nitro API directly from a `"use step"` function.
+- **Workflows are part of your Nitro bundle.** Workflow routes are bundled by Nitro alongside your application code, instead of being built into a separate output. There's nothing extra to configure.
+- **Minimal runtime output.** During bundling, Nitro automatically traces native dependencies and tree-shakes unused code to produce a minimal runtime output.
+- **Nitro v2 is unchanged.** This applies to Nitro v3. Apps on Nitro v2 keep their existing behavior.
+
+## Using Nitro APIs from a step
+
+Because steps run inside your Nitro runtime, server-side utilities work directly inside a `"use step"` function:
+
+```typescript
+export async function cacheResult(key: string, value: string) {
+  "use step";
+
+  const storage = useStorage("cache");
+  await storage.setItem(key, value);
+
+  return { cached: true };
+}
+```
+
+## Learn more
+
+- [Nitro](/docs/getting-started/nitro): Set up Workflow SDK in a Nitro v3 app
+- [Deploying](/docs/deploying): How workflow bundles are deployed

package/docs/internal/nitro-web-ui.mdx

@@ -0,0 +1,24 @@
+---
+title: Local web UI in Nitro dev
+description: Inspect, monitor, and debug your workflow runs from the /_workflow route during Nitro development.
+type: overview
+---
+
+# Local web UI in Nitro dev
+
+{/* TODO: unreleased. Changeset .changeset/nitro-dashboard-route.md is pending; ships in @workflow/nitro 5.0.0. Update this date on publish. */}
+<span className="text-sm text-fd-muted-foreground">June 2, 2026</span>
+
+The Workflow SDK web UI is now built into the Nitro dev server. During development, open `/_workflow` in your browser to inspect, monitor, and debug your workflow runs.
+
+## What's new
+
+- **Built-in `/_workflow` route in development.** The route starts the local web UI and redirects to it without requiring a separate command or process.
+- **Inspect runs in place.** Inspect, monitor, and debug your workflow runs directly from the dev server you're already running.
+
+![Workflow SDK web UI on the /_workflow route](/local-web-ui.png)
+
+## Learn more
+
+- [Observability](/docs/observability): Inspect runs with the web UI and CLI
+- [Nitro](/docs/getting-started/nitro): Set up Workflow SDK in a Nitro v3 app

package/docs/internal/serializable-abort-controller.mdx

@@ -8,7 +8,7 @@ type: overview
 
 <span className="text-sm text-fd-muted-foreground">March 12, 2026</span>
 
-`AbortController` and `AbortSignal` now work natively in workflow functions. Create a controller, pass its signal to steps, and call `abort()` — no special imports or wrapper functions needed.
+`AbortController` and `AbortSignal` now work natively in workflow functions. Create a controller, pass its signal to steps, and call `abort()`; no special imports or wrapper functions needed.
 
 ## What's new
 
@@ -17,8 +17,8 @@ type: overview
 - **Cooperative cancellation.** Steps receive the abort in real time and can respond by checking `signal.aborted`, calling `signal.throwIfAborted()`, or passing the signal to APIs like `fetch`.
 - **Abort errors skip retries.** When a step throws due to an abort (e.g., `fetch` throws `AbortError`), the error is automatically wrapped in `FatalError` so it skips retries and bubbles up immediately.
 - **`AbortSignal.timeout()` blocked in workflow VM.** Because it relies on real-time timers that break deterministic replay, `AbortSignal.timeout()` throws a helpful error pointing to the `sleep()` + `AbortController` pattern instead.
-- **`Request.signal` preserved when it carries abort state.** A `Request`'s `.signal` is serialized when it's already aborted (so the cancellation that happened pre-serialization is preserved) or when it's a workflow-managed signal (so its hook + stream backing carries through). Plain non-aborted native signals — including the auto-generated signal on `new Request(url)` — are dropped to avoid minting stream infrastructure for every `Request`. To get cross-boundary cancellation through a `Request`, build it with the signal from a workflow-context `AbortController`.
-- **Pending queue items drain on completion.** If you call `abort()` (or `dispose` a hook, or kick off a `void sleep('1d')`, or fire a `void someStep()`) without a suspension point between that call and the workflow's return, the runtime now treats end-of-run as a final suspension and commits all pending operations before the run is marked terminal. This matches normal JS semantics — `setTimeout` etc. continue running after the surrounding function returns. The most important case: `controller.abort()` called as the last statement of a workflow now actually propagates to in-flight steps on other compute instances.
+- **`Request.signal` preserved when it carries abort state.** A `Request`'s `.signal` is serialized when it's already aborted (so the cancellation that happened pre-serialization is preserved) or when it's a workflow-managed signal (so its hook + stream backing carries through). Plain non-aborted native signals (including the auto-generated signal on `new Request(url)`) are dropped to avoid minting stream infrastructure for every `Request`. To get cross-boundary cancellation through a `Request`, build it with the signal from a workflow-context `AbortController`.
+- **Pending queue items drain on completion.** If you call `abort()` (or `dispose` a hook, or kick off a `void sleep('1d')`, or fire a `void someStep()`) without a suspension point between that call and the workflow's return, the runtime now treats end-of-run as a final suspension and commits all pending operations before the run is marked terminal. This matches normal JS semantics: `setTimeout` etc. continue running after the surrounding function returns. The most important case: `controller.abort()` called as the last statement of a workflow now actually propagates to in-flight steps on other compute instances.
 
 ## Timeout with cancellation
 
@@ -106,7 +106,7 @@ export async function userCancellableWorkflow(jobId: string) {
 
 ## Step-initiated abort
 
-A step can receive the full `AbortController` and call `abort()` to cancel parallel work — useful for watchdog patterns like quota monitoring:
+A step can receive the full `AbortController` and call `abort()` to cancel parallel work, useful for watchdog patterns like quota monitoring:
 
 ```typescript
 declare function processData(url: string, signal: AbortSignal): Promise<{ processed: boolean }>; // @setup
@@ -143,6 +143,6 @@ async function monitorQuota(userId: string, controller: AbortController) {
 
 ## Learn more
 
-- [Cancellation](/docs/foundations/cancellation) — Full guide with all usage patterns
-- [How Cancellation Works](/docs/how-it-works/cancellation) — Hook and stream internals
-- [AbortSignal.timeout() in Workflow](/docs/errors/abort-signal-timeout-in-workflow) — Why `AbortSignal.timeout()` is blocked and what to use instead
+- [Cancellation](/docs/foundations/cancellation): Full guide with all usage patterns
+- [How Cancellation Works](/docs/how-it-works/cancellation): Hook and stream internals
+- [AbortSignal.timeout() in Workflow](/docs/errors/abort-signal-timeout-in-workflow): Why `AbortSignal.timeout()` is blocked and what to use instead

package/docs/meta.json

@@ -1,7 +1,7 @@
 {
   "pages": [
-    "introduction",
     "---",
+    "whats-new",
     "getting-started",
     "foundations",
     "how-it-works",
@@ -10,7 +10,8 @@
     "testing",
     "deploying",
     "errors",
-    "migration-guides",
+    "comparisons",
+    "configuration",
     "api-reference"
   ]
 }

package/docs/observability/attributes.mdx

@@ -0,0 +1,134 @@
+---
+title: Attributes
+description: Attach 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/set-attributes
+  - /docs/api-reference/workflow-errors/workflow-world-error
+---
+
+[`setAttributes`](/docs/api-reference/workflow/set-attributes) attaches plaintext string metadata to the current workflow run. These attributes appear in the Workflow CLI and web UI, and you can search and filter runs by them from either the [CLI](#from-the-cli) or the [Analytics API](/docs/api-reference/workflow-runtime/world/analytics).
+
+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 { setAttributes } from "workflow"
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow"
+
+  await setAttributes({ // [!code highlight]
+    phase: "received", // [!code highlight]
+    orderId, // [!code highlight]
+  }) // [!code highlight]
+
+  // ...work...
+
+  await setAttributes({ phase: "complete" }) // [!code highlight]
+}
+```
+
+## Usage
+
+Call [`setAttributes`](/docs/api-reference/workflow/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 { setAttributes } from "workflow"
+
+export async function cleanupAttributes() {
+  "use workflow"
+
+  await 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.
+
+## Reserved keys
+
+When `start()` is called from inside a running workflow or step, the new run is automatically tagged with two reserved attributes:
+
+- `$parentRunId`: the run that started it.
+- `$rootRunId`: the root of the chain. It is inherited, so every run in a daisy chain or fan-out shares one root id.
+
+Top-level runs (started outside any workflow or step) are not tagged.
+
+## 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 `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)
+
+## Searching and filtering by attributes
+
+### From the CLI
+
+`workflow inspect attributes` lists the keys recorded on this project's runs,
+with how many runs carry each and when it was first and last seen:
+
+```bash
+workflow inspect attributes
+```
+
+Pass one or more `--attribute key=value` pairs to `inspect runs` to list the
+runs carrying them. Repeatable up to 8 times:
+
+```bash
+workflow inspect runs --attribute phase=received --status running
+```
+
+Both require a backend with the analytics read path. `--attribute` is ignored
+with a warning on backends without one, and `inspect attributes` reports that
+it is unavailable.
+
+### From the Analytics API
+
+The [Analytics API](/docs/api-reference/workflow-runtime/world/analytics) can discover which attribute keys exist and filter run listings by them. The `analytics` namespace is optional on `World`, so feature-detect it before use; it is absent on local, Postgres, and other custom Worlds:
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = await getWorld();
+if (!world.analytics) {
+  throw new Error("This World does not support analytics queries"); // [!code highlight]
+}
+
+// Which attribute keys exist, and on how many runs?
+const keys = await world.analytics.attributes.list();
+
+// List runs whose latest attributes match every pair
+const stuck = await world.analytics.runs.list({
+  attributes: { phase: "received" }, // [!code highlight]
+});
+```
+
+Matching is latest-write-wins: once the run above writes `phase: "complete"`, it stops matching `phase: "received"`.
+
+## Behavior
+
+- 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 `setAttributes` like any other step-side network write. Catch the error inside the step if the attribute is best-effort.
+- Reading and querying: each run's current attributes are returned on the run objects from the [Storage](/docs/api-reference/workflow-runtime/world/storage) and [Analytics](/docs/api-reference/workflow-runtime/world/analytics) APIs, and the Analytics API supports discovering attribute keys and filtering run listings by key=value pairs (see [Searching and filtering by attributes](#searching-and-filtering-by-attributes)). On Worlds without the optional `analytics` namespace, attributes are readable on run objects but not searchable.

package/docs/observability/index.mdx

@@ -1,8 +1,8 @@
 ---
 title: Observability
-description: Inspect, monitor, and debug workflows through the CLI and Web UI with powerful observability tools.
-type: guide
-summary: Inspect and debug workflow runs using the CLI and Web UI.
+description: Inspect, monitor, and debug workflows through the CLI and web UI.
+type: overview
+summary: Inspect and debug workflow runs using the CLI and web UI.
 prerequisites:
   - /docs/foundations
 related:
@@ -10,15 +10,15 @@ related:
   - /docs/how-it-works/encryption
 ---
 
-Workflow SDK provides powerful tools to inspect, monitor, and debug your workflows through the CLI and Web UI. These tools allow you to inspect workflow runs, steps, webhooks, [events](/docs/how-it-works/event-sourcing), and stream output.
+Workflow SDK provides a Workflow CLI and web UI to inspect, monitor, and debug workflows. You can inspect workflow runs, steps, webhooks, [events](/docs/how-it-works/event-sourcing), and stream output.
 
-## Quick Start
+## Quick start
 
 ```bash
 npx workflow
 ```
 
-The CLI comes pre-installed with the Workflow SDK and registers the `workflow` command. If the `workflow` package is not already installed, `npx workflow` will download and run the CLI temporarily, or use the local installed version if available.
+The CLI comes pre-installed with the Workflow SDK and registers the `workflow` command. If the `workflow` package is not already installed, `npx workflow` will download and run the CLI temporarily, or use the locally installed version if available.
 
 Get started inspecting your local workflows:
 
@@ -33,15 +33,33 @@ npx workflow inspect runs
 ## Web UI
 
 Workflow SDK ships with a local web UI for inspecting your workflows. The CLI
-will locally serve the Web UI when using the `--web` flag.
+serves the web UI locally when you use the `--web` flag.
 
 ```bash
-# Launch Web UI for visual exploration
+# Launch the web UI for visual exploration
 npx workflow inspect runs --web
 ```
 
 ![Workflow SDK Web UI](/o11y-ui.png)
 
+On [Nitro](/docs/getting-started/nitro), the dev server has the web UI built
+in: open `/_workflow` while `nitro dev` is running. No separate command is required.
+
+In the runs table, select one or more runs and choose **Cancel** to cancel the batch in a single request. Runs that fail with a retryable error stay selected so you can retry them.
+
+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), which is 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
@@ -53,9 +71,9 @@ If you're deploying workflows to a production environment, but want to inspect t
 Backends might require additional configuration. If you're missing environment variables, the World package should provide instructions on how to configure it.
 </Callout>
 
-### Vercel Backend
+### Vercel backend
 
-To inspect workflows running on Vercel, ensure you're logged in to the Vercel CLI and have linked your project. See [Vercel CLI authentication and project linking docs](https://vercel.com/docs/cli/project-linking) for more information. Then, simply specify the backend as `vercel`.
+To inspect workflows running on Vercel, ensure you're logged in to the Vercel CLI and have linked your project. See [Vercel CLI authentication and project linking docs](https://vercel.com/docs/cli/project-linking) for more information. Then, specify the backend as `vercel`.
 
 ```bash
 # Inspect workflows running on Vercel
@@ -63,3 +81,7 @@ 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
+
+<AutoCards />

package/docs/observability/meta.json

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

package/docs/observability/retention.mdx

@@ -0,0 +1,93 @@
+---
+title: Data retention
+description: Control how long a run's data is kept after it finishes.
+type: reference
+summary: Control how long a run's data is kept after the run ends.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/api-reference/workflow-api/start
+---
+
+A finished run leaves data behind: the inputs and outputs of the workflow and
+each of its steps, the payloads on its event log, and anything written to its
+streams. How long that data is kept is decided by the World you are running
+on, not by the SDK.
+
+`experimental_retention` on [`start()`](/docs/api-reference/workflow-api/start)
+lets a run ask for a specific retention period, rather than the World's default.
+
+## Deleting a run's data as soon as it ends
+
+{/* @skip-typecheck: abbreviated usage; processDocumentWorkflow is the reader's own workflow */}
+```typescript lineNumbers
+const run = await start(processDocumentWorkflow, [documentId], {
+  experimental_retention: 0, // [!code highlight]
+})
+```
+
+`0` asks the World to delete the run's **user data** the moment the run
+completes or fails, rather than keeping it for the World's default window.
+
+Two values are accepted today:
+
+| Value | Meaning |
+| --- | --- |
+| `0` | Delete user data as soon as the run reaches a terminal state. |
+| `'default'` | Use the World's default. Identical to omitting the option. |
+
+<Callout type="warn">
+  The option is prefixed `experimental_` because both its name and the set of
+  values it accepts are expected to change.
+</Callout>
+
+## What is deleted, and what is not
+
+**Deleted:** the run's input, output and error; every step's input, output and
+error; the payloads on the event log; and stream contents.
+
+**Kept:** the run, step and event records themselves — their ids, timestamps,
+status, step names, and any [attributes](/docs/observability/attributes) you
+set. They are kept for the World's default period so the run stays visible in
+the CLI and web UI. A purged run is still listed and still traceable; its
+payloads simply read back as expired.
+
+Inspecting a purged run shows it as expired rather than failing. The Workflow
+CLI renders the run's own input, output and error as `<data expired>`:
+
+```bash
+workflow inspect runs wrun_...
+```
+
+Step, hook and event payloads read back empty. On the Vercel World they also
+render as `<data expired>`; on Worlds that clear the stored value outright
+they simply show as empty. Either way the data is gone — the difference is
+only in how the absence is labelled.
+
+<Callout type="warn">
+  **You cannot read the return value of a run started with
+  `experimental_retention: 0`.** The deletion races your own read of the
+  result and generally wins, so `await run.returnValue` throws
+  [`RunExpiredError`](/docs/errors/run-expired) instead of resolving.
+
+  This is a known limitation. If you need the result, send it somewhere you
+  control, e.g. a step that writes it to your own store, rather than reading it back off the run.
+</Callout>
+
+`RunExpiredError` is not specific to `experimental_retention: 0`. Any run read
+after its retention window has passed throws it, and the error carries
+`runId`, `runStatus` and `expiredAt` when the World still has them — so a
+caller can tell a successful run whose result is gone from a failed one whose
+error is gone. If the run's metadata is gone too, the World reports the run as
+missing and you get `WorkflowRunNotFoundError` instead.
+
+## Retention is implemented by the World
+
+The SDK records your preference; it does not enforce it. `start()` writes the
+value onto the run as the reserved `$retention` attribute, and the World
+decides what to do when the run ends.
+A World that does not implement retention
+**keeps the data**. If you need certainty that a specific World deletes your data,
+confirm it against that World's own documentation rather than the presence of this
+option.