workflow 5.0.0-beta.14 → 5.0.0-beta.15

package/docs/api-reference/index.mdx

@@ -17,9 +17,33 @@ All the functions and primitives that come with Workflow SDK by package.
     <Card title="workflow/api" href="/docs/api-reference/workflow-api">
         API reference for runtime functions from the `workflow/api` package.
     </Card>
+    <Card title="workflow/runtime" href="/docs/api-reference/workflow-runtime">
+        Runtime functions for resolving the World instance and the low-level World SDK.
+    </Card>
+    <Card title="workflow/observability" href="/docs/api-reference/workflow-observability">
+        Utilities to hydrate step I/O, parse display names, and decrypt workflow data.
+    </Card>
     <Card title="workflow/next" href="/docs/api-reference/workflow-next">
         Next.js integration for Workflow SDK that automatically configures bundling and runtime support.
     </Card>
+    <Card title="workflow/nitro" href="/docs/api-reference/workflow-nitro">
+        Nitro module for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/nuxt" href="/docs/api-reference/workflow-nuxt">
+        Nuxt module for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/sveltekit" href="/docs/api-reference/workflow-sveltekit">
+        SvelteKit Vite plugin for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/astro" href="/docs/api-reference/workflow-astro">
+        Astro integration for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/vite" href="/docs/api-reference/workflow-vite">
+        Standalone Vite plugin for workflow bundling and runtime support.
+    </Card>
+    <Card title="workflow/nest" href="/docs/api-reference/workflow-nest">
+        NestJS module for workflow bundling and runtime support.
+    </Card>
     <Card title="workflow/errors" href="/docs/api-reference/workflow-errors">
         Semantic error types for handling workflow storage backend failures.
     </Card>

package/docs/api-reference/meta.json

@@ -4,7 +4,15 @@
     "workflow-globals",
     "workflow",
     "workflow-api",
+    "workflow-runtime",
+    "workflow-observability",
     "workflow-next",
+    "workflow-nitro",
+    "workflow-nuxt",
+    "workflow-sveltekit",
+    "workflow-astro",
+    "workflow-vite",
+    "workflow-nest",
     "workflow-errors",
     "workflow-serde",
     "workflow-ai",

package/docs/api-reference/vitest/index.mdx

@@ -11,7 +11,6 @@ The `@workflow/vitest` package provides a Vitest plugin and test helpers for run
 
 Returns a Vite plugin array that handles SWC transforms, bundle building, and in-process handler registration automatically.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { defineConfig } from "vitest/config";
@@ -24,7 +23,6 @@ export default defineConfig({
 
 Pass a [`WorkflowTestOptions`](#workflowtestoptions) object when your project uses a non-standard layout — for example, a monorepo where `workflows/` does not live at the Vitest config's directory, or when the default `.workflow-data` / `.workflow-vitest` output locations need to move. The plugin forwards these paths to `buildWorkflowTests()` and `setupWorkflowTests()` through Vitest's per-project provided context, so each Vitest workspace project stays isolated.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { defineConfig } from "vitest/config";
@@ -54,7 +52,6 @@ export default defineConfig({
 
 Builds workflow and step bundles to disk. Called automatically by the `workflow()` plugin in `globalSetup`. Use directly only for [manual setup](/docs/testing#manual-setup).
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { buildWorkflowTests } from "@workflow/vitest";
@@ -76,7 +73,6 @@ Sets up an in-process workflow runtime in each test worker. Imports pre-built bu
 
 Called automatically by the `workflow()` plugin in `setupFiles`. Use directly only for [manual setup](/docs/testing#manual-setup).
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { beforeAll, afterAll } from "vitest";
@@ -118,7 +114,6 @@ Tears down the workflow test world. Clears the global world and closes the Local
 
 Polls the event log until the workflow has a pending `sleep()` call — one with a `wait_created` event but no corresponding `wait_completed` event. Returns the correlation ID of the pending sleep, which can be passed to [`wakeUp()`](/docs/api-reference/workflow-api/get-run) to target a specific sleep.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { waitForSleep } from "@workflow/vitest"; // [!code highlight]
@@ -147,7 +142,6 @@ await getRun(run.runId).wakeUp({ correlationIds: [sleepId] }); // [!code highlig
 
 Polls the hook list and event log until a hook matching the optional `token` filter exists that hasn't been received yet. Returns the matching hook object.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { waitForHook } from "@workflow/vitest"; // [!code highlight]

package/docs/api-reference/workflow/create-hook.mdx

@@ -65,6 +65,8 @@ export default Hook;`}
 
 The returned `Hook` object also implements `AsyncIterable<T>`, which allows you to iterate over incoming payloads using `for await...of` syntax.
 
+Use `hook.getConflict()` to check whether the hook token is already claimed by another active hook, without waiting for hook payload data. Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the registration, then resolves with `null` once `hook_created` is recorded, or with the conflicting [`Run`](/docs/api-reference/workflow-api/get-run) if another active hook already owns the same token.
+
 ## Examples
 
 ### Basic Usage
@@ -112,6 +114,36 @@ export async function slackBotWorkflow(channelId: string) {
 }
 ```
 
+### Detecting Token Conflicts
+
+Use `hook.getConflict()` when the workflow needs to claim a hook token before doing other work, but does not need a payload yet:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function chargeOrder(orderId: string): Promise<void>; // @setup
+
+async function processOrder(orderId: string) {
+  "use workflow";
+
+  using hook = createHook({ // [!code highlight]
+    token: `order:${orderId}` // [!code highlight]
+  }); // [!code highlight]
+
+  const conflict = await hook.getConflict(); // [!code highlight]
+  if (conflict) { // [!code highlight]
+    // Another active workflow run already owns this token.
+    return { dedupedTo: conflict.runId };
+  }
+
+  await chargeOrder(orderId);
+}
+```
+
+Because `createHook()` alone does not suspend the workflow, awaiting `hook.getConflict()` is what actually suspends the run and commits the hook registration. It only waits for registration — to receive payload data from a future `resumeHook()` call, await the hook itself or iterate it with `for await...of`.
+
+On a conflict, the resolved value is a `Run` handle for the run that currently owns the token, with durable step-backed accessors. The duplicate run can decide in code how to handle it: return or log `conflict.runId`, inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` and continue in the current run. See [Idempotency](/docs/foundations/idempotency) for these strategies in context.
+
 ### Waiting for Multiple Payloads
 
 You can also wait for multiple payloads by using the `for await...of` syntax.

package/docs/api-reference/workflow/create-webhook.mdx

@@ -55,6 +55,7 @@ The returned `Webhook` object has:
 
 - `url`: The HTTP endpoint URL that external systems can call
 - `token`: The unique token identifying this webhook
+- `getConflict()`: A promise that resolves with the conflicting run if another active hook already owns this token, or `null` once the webhook endpoint has been registered
 - Implements `AsyncIterable<T>` for handling multiple requests, where `T` is `Request` (default) or `RequestWithResponse` (manual mode)
 
 When using `createWebhook({ respondWith: 'manual' })`, the resolved request type is `RequestWithResponse`, which extends the standard `Request` interface with a `respondWith(response: Response): Promise<void>` method for sending custom responses back to the caller.

package/docs/api-reference/workflow/experimental-set-attributes.mdx

@@ -60,4 +60,6 @@ Attribute keys must be 1-256 characters, values must be strings up to 256 bytes,
 
 Validation errors throw [`FatalError`](/docs/api-reference/workflow/fatal-error) and fail the run before an attribute write is attempted.
 
-When called from a workflow body, the write is recorded through an internal step. When called from a step body, the step posts the attributes directly to the World. Storage errors from step-body calls throw from `experimental_setAttributes`, so catch them inside the step if the write should be best-effort.
+Calls from both workflow and step bodies append a native `attr_set` event, which the World materializes onto `run.attributes`. Workflow-originated events record a workflow writer; step-originated events record the originating step ID and attempt.
+
+Native attributes require spec version 4 or later. Step-body storage errors throw from `experimental_setAttributes`; catch them inside the step if the write should be best-effort. Workflow-body writes are committed when the workflow suspends: transient storage errors are retried with the suspension, while a write the World rejects as invalid — such as exceeding the per-run attribute cap across multiple calls — fails the run with the validation error.

package/docs/api-reference/workflow-api/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: "workflow/api"
-description: Runtime functions to inspect runs, start workflows, and access world data.
+description: Runtime functions to inspect runs, start workflows, and manage hooks.
 type: overview
 summary: Explore runtime functions for starting workflows, inspecting runs, and managing hooks.
 ---
@@ -9,7 +9,7 @@ API reference for runtime functions from the `workflow/api` package.
 
 ## Functions
 
-The API package is for access and introspection of workflow data to inspect runs, start new runs, or access anything else directly accessible by the world.
+The API package is for access and introspection of workflow data to inspect runs, start new runs, and manage hooks.
 
 <Cards>
     <Card href="/docs/api-reference/workflow-api/start" title="start()">
@@ -27,10 +27,8 @@ The API package is for access and introspection of workflow data to inspect runs
     <Card href="/docs/api-reference/workflow-api/get-run" title="getRun()">
         Get workflow run status and metadata without waiting for completion.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/get-world" title="getWorld()">
-        Async: resolve the World instance for storage, queuing, and streaming backends.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world" title="World SDK">
-        Low-level API for inspecting runs, steps, events, hooks, streams, and queues.
-    </Card>
 </Cards>
+
+<Callout type="info">
+  Looking for `getWorld()` and the World SDK? They are exported from `workflow/runtime` — see the [`workflow/runtime` reference](/docs/api-reference/workflow-runtime).
+</Callout>

package/docs/api-reference/workflow-api/start.mdx

@@ -56,6 +56,7 @@ Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-
 * The function returns immediately after enqueuing the workflow - it doesn't wait for the workflow to complete.
 * All arguments must be [serializable](/docs/foundations/serialization).
 * When `deploymentId` is provided, the argument types and return type become `unknown` since there is no guarantee the workflow function's types will be consistent across different deployments.
+* `attributes` seeds plaintext run metadata as part of creation and requires a World implementing spec version 4 or later.
 
 <Callout type="info">
 If `start()` throws `'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.`, the passed function was not transformed as a workflow. The two most common causes are a missing `"use workflow"` directive or missing framework integration. See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function).
@@ -79,7 +80,8 @@ import { start } from "workflow/api";
 import { myWorkflow } from "./workflows/my-workflow";
 
 const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
-  deploymentId: "custom-deployment-id" // [!code highlight]
+  deploymentId: "custom-deployment-id", // [!code highlight]
+  attributes: { source: "checkout" } // [!code highlight]
 }); // [!code highlight]
 ```
 

package/docs/api-reference/workflow-astro/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "workflow/astro"
+description: Astro integration for automatic workflow bundling and route registration.
+type: overview
+summary: Explore the Astro integration for automatic workflow bundling and runtime support.
+related:
+  - /docs/getting-started/astro
+---
+
+Astro integration for Workflow SDK that transforms workflow code and builds the workflow bundles.
+
+## Functions
+
+<Cards>
+    <Card title="workflow()" href="/docs/api-reference/workflow-astro/workflow">
+        Astro integration that transforms workflow code (`"use step"`/`"use workflow"` directives)
+    </Card>
+</Cards>

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

@@ -0,0 +1,4 @@
+{
+  "title": "workflow/astro",
+  "pages": ["workflow"]
+}

package/docs/api-reference/workflow-astro/workflow.mdx

@@ -0,0 +1,45 @@
+---
+title: workflow
+description: Configure Astro to transform workflow directives.
+type: reference
+summary: Add the workflow integration to your Astro config to enable workflow directive transformation.
+prerequisites:
+  - /docs/getting-started/astro
+---
+
+Returns an Astro integration that transforms workflow code (`"use step"`/`"use workflow"` directives) and builds the workflow bundles.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflow()` to the `integrations` array of your Astro config.
+
+```typescript title="astro.config.mjs" lineNumbers
+// @ts-check
+import { defineConfig } from "astro/config";
+import { workflow } from "workflow/astro"; // [!code highlight]
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [workflow()], // [!code highlight]
+});
+```
+
+The integration registers the workflow Vite transform plugins during `astro:config:setup` and builds the workflow bundles — locally during config setup, or via the Vercel builder after `astro:build:done` when deploying to Vercel.
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `WorkflowPluginOptions` | Optional. Configures the workflow build. |
+
+#### WorkflowPluginOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Set to `false` for smaller function bundles (useful for staying under the Vercel 250MB function size limit) at the cost of stack traces pointing at generated code. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+
+### Returns
+
+Returns an `AstroIntegration` object to include in the `integrations` array of your Astro config.

package/docs/api-reference/workflow-errors/hook-conflict-error.mdx

@@ -0,0 +1,60 @@
+---
+title: HookConflictError
+description: Thrown when creating a hook with a token that is already in use by another workflow run.
+type: reference
+summary: Catch HookConflictError when a hook token is already claimed by another active workflow run.
+related:
+  - /docs/api-reference/workflow/create-hook
+  - /docs/foundations/hooks
+  - /docs/errors/hook-conflict
+---
+
+`HookConflictError` is thrown when creating a hook with a token that is already in use by another active workflow run. Hook tokens must be unique across all running workflows — see the [hook-conflict](/docs/errors/hook-conflict) error guide for resolution strategies.
+
+```typescript lineNumbers
+import { HookConflictError } from "workflow/errors"
+declare function startApprovalWorkflow(token: string): Promise<void>; // @setup
+declare const token: string; // @setup
+
+try {
+  await startApprovalWorkflow(token);
+} catch (error) {
+  if (HookConflictError.is(error)) { // [!code highlight]
+    console.error(
+      `Token "${error.token}" already in use by run ${error.conflictingRunId}`
+    );
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface HookConflictError {
+  /** The hook token that conflicted. */
+  token: string;
+  /** The run ID of the workflow currently holding the token, when known. */
+  conflictingRunId?: string;
+  /** The error message. */
+  message: string;
+}
+export default HookConflictError;`}
+/>
+
+### Static Methods
+
+#### `HookConflictError.is(value)`
+
+Type-safe check for `HookConflictError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { HookConflictError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (HookConflictError.is(error)) {
+  // error is typed as HookConflictError
+}
+```

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

@@ -1,16 +1,21 @@
 {
   "title": "workflow/errors",
   "pages": [
+    "workflow-error",
     "hook-not-found-error",
+    "hook-conflict-error",
     "step-not-registered-error",
     "workflow-not-registered-error",
     "workflow-run-not-found-error",
     "workflow-run-failed-error",
     "workflow-run-cancelled-error",
+    "workflow-run-not-completed-error",
+    "workflow-runtime-error",
     "workflow-world-error",
     "throttle-error",
     "entity-conflict-error",
     "run-expired-error",
+    "run-not-supported-error",
     "too-early-error"
   ]
 }

package/docs/api-reference/workflow-errors/run-not-supported-error.mdx

@@ -0,0 +1,58 @@
+---
+title: RunNotSupportedError
+description: Thrown when a workflow run requires a newer workflow spec version than the installed SDK supports.
+type: reference
+summary: Catch RunNotSupportedError when stored run data requires a newer workflow package version.
+related:
+  - /docs/foundations/versioning
+---
+
+`RunNotSupportedError` is thrown when reading a workflow run whose data was written with a newer workflow spec version than the running SDK supports. This typically means the run was created by a newer version of the `workflow` package — upgrade the package to process it.
+
+```typescript lineNumbers
+import { RunNotSupportedError } from "workflow/errors"
+declare function readRun(runId: string): Promise<unknown>; // @setup
+declare const runId: string; // @setup
+
+try {
+  await readRun(runId);
+} catch (error) {
+  if (RunNotSupportedError.is(error)) { // [!code highlight]
+    console.error(
+      `Run requires spec v${error.runSpecVersion}, world supports v${error.worldSpecVersion}`
+    );
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface RunNotSupportedError {
+  /** The spec version the run's stored data requires. */
+  runSpecVersion: number;
+  /** The spec version the current World supports. */
+  worldSpecVersion: number;
+  /** The error message. */
+  message: string;
+}
+export default RunNotSupportedError;`}
+/>
+
+### Static Methods
+
+#### `RunNotSupportedError.is(value)`
+
+Type-safe check for `RunNotSupportedError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { RunNotSupportedError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (RunNotSupportedError.is(error)) {
+  // error is typed as RunNotSupportedError
+}
+```

package/docs/api-reference/workflow-errors/workflow-error.mdx

@@ -0,0 +1,52 @@
+---
+title: WorkflowError
+description: Base class for all workflow error types.
+type: reference
+summary: All errors thrown by the Workflow SDK extend WorkflowError.
+related:
+  - /docs/foundations/errors-and-retries
+---
+
+`WorkflowError` is the base class that all Workflow SDK error types extend, such as [`WorkflowRunFailedError`](/docs/api-reference/workflow-errors/workflow-run-failed-error) and [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error). It extends `Error` with an optional `cause` and, for some subclasses, a link to the relevant error documentation appended to the message.
+
+```typescript lineNumbers
+import { WorkflowError } from "workflow/errors"
+
+const error = new WorkflowError("something went wrong", {
+  cause: new Error("underlying cause"),
+});
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowError {
+  /** The error message. */
+  message: string;
+  /** The underlying cause, when provided. */
+  cause?: unknown;
+}
+export default WorkflowError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowError.is(value)`
+
+Type-safe check for `WorkflowError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+<Callout type="warn">
+  `WorkflowError.is()` matches only direct `WorkflowError` instances — not subclasses, which override the error name it checks. To handle a specific error type, use that subclass's own `.is()` method (e.g. `WorkflowRunFailedError.is(error)`).
+</Callout>
+
+```typescript
+import { WorkflowError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowError.is(error)) {
+  // error is typed as WorkflowError
+}
+```

package/docs/api-reference/workflow-errors/workflow-run-not-completed-error.mdx

@@ -0,0 +1,58 @@
+---
+title: WorkflowRunNotCompletedError
+description: Thrown when requesting the result of a workflow run that has not completed yet.
+type: reference
+summary: Catch WorkflowRunNotCompletedError when reading the return value of a run that is still pending or running.
+related:
+  - /docs/api-reference/workflow-api/get-run
+---
+
+`WorkflowRunNotCompletedError` is thrown when requesting the result of a workflow run that has not completed yet. The run's current status (for example `pending` or `running`) is available on the error.
+
+[`run.returnValue()`](/docs/api-reference/workflow-api/get-run) handles this error internally — it polls until the run completes — so you will mainly encounter it when building custom polling logic on lower-level APIs.
+
+```typescript lineNumbers
+import { WorkflowRunNotCompletedError } from "workflow/errors"
+declare function readRunResult(runId: string): Promise<unknown>; // @setup
+declare const runId: string; // @setup
+
+try {
+  const result = await readRunResult(runId);
+} catch (error) {
+  if (WorkflowRunNotCompletedError.is(error)) { // [!code highlight]
+    console.log(`Run ${error.runId} is still ${error.status}`);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRunNotCompletedError {
+  /** The workflow run ID. */
+  runId: string;
+  /** The run's status at the time of the error (e.g. "pending", "running"). */
+  status: string;
+  /** The error message. */
+  message: string;
+}
+export default WorkflowRunNotCompletedError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowRunNotCompletedError.is(value)`
+
+Type-safe check for `WorkflowRunNotCompletedError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { WorkflowRunNotCompletedError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRunNotCompletedError.is(error)) {
+  // error is typed as WorkflowRunNotCompletedError
+}
+```

package/docs/api-reference/workflow-errors/workflow-runtime-error.mdx

@@ -0,0 +1,58 @@
+---
+title: WorkflowRuntimeError
+description: Thrown when the workflow runtime encounters an execution error, such as serialization failures or timeouts.
+type: reference
+summary: Catch WorkflowRuntimeError for runtime-level failures like unserializable values or workflow timeouts.
+related:
+  - /docs/foundations/serialization
+  - /docs/foundations/errors-and-retries
+---
+
+`WorkflowRuntimeError` is thrown when the workflow runtime encounters an error executing a workflow. Common causes include:
+
+- Values crossing the workflow/step boundary that cannot be serialized
+- Workflow execution timeouts
+- Invalid runtime state, such as misconfigured streams
+
+```typescript lineNumbers
+import { WorkflowRuntimeError } from "workflow/errors"
+declare function runWorkflowOperation(): Promise<void>; // @setup
+
+try {
+  await runWorkflowOperation();
+} catch (error) {
+  if (WorkflowRuntimeError.is(error)) { // [!code highlight]
+    console.error("Workflow runtime error:", error.message);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRuntimeError {
+  /** The error message. */
+  message: string;
+  /** The underlying cause, when provided. */
+  cause?: unknown;
+}
+export default WorkflowRuntimeError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowRuntimeError.is(value)`
+
+Type-safe check for `WorkflowRuntimeError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { WorkflowRuntimeError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRuntimeError.is(error)) {
+  // error is typed as WorkflowRuntimeError
+}
+```

package/docs/api-reference/workflow-nest/configure-workflow-controller.mdx

@@ -0,0 +1,33 @@
+---
+title: configureWorkflowController
+description: Point WorkflowController at the generated workflow bundles.
+type: reference
+summary: Configure the directory WorkflowController loads workflow bundles from.
+prerequisites:
+  - /docs/getting-started/nestjs
+---
+
+Configures the output directory that [`WorkflowController`](/docs/api-reference/workflow-nest/workflow-controller) loads the generated workflow bundles (`steps.mjs`, `workflows.mjs`, `webhook.mjs`, `manifest.json`) from.
+
+[`WorkflowModule.forRoot()`](/docs/api-reference/workflow-nest/workflow-module) calls this for you with its resolved `outDir` — call it yourself only when registering `WorkflowController` manually. The controller's route handlers throw if no directory has been configured.
+
+## Usage
+
+```typescript title="src/app.module.ts" lineNumbers
+import { join } from "node:path";
+import { configureWorkflowController } from "workflow/nest"; // [!code highlight]
+
+configureWorkflowController(join(process.cwd(), ".nestjs/workflow")); // [!code highlight]
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `outDir` | `string` | Directory containing the generated workflow bundles. Should match the `outDir` used by the builder (default: `.nestjs/workflow` in the working directory). |
+
+### Returns
+
+Returns `void`.