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

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

@@ -0,0 +1,65 @@
+---
+title: experimental_setAttributes
+description: Attach string metadata to workflow run for observability.
+type: reference
+summary: Use experimental_setAttributes inside a workflow or step function to set run attributes.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability/attributes
+  - /docs/api-reference/workflow/fatal-error
+---
+
+Attaches string metadata to the current workflow run.
+
+<Callout>
+This API is experimental and may change before the stable attributes API is released.
+</Callout>
+
+```typescript lineNumbers
+import { experimental_setAttributes } from "workflow"
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow"
+
+  await experimental_setAttributes({
+    phase: "received",
+    orderId,
+  })
+}
+```
+
+## API Signature
+
+### Parameters
+
+<TSDoc
+definition={`
+import { experimental_setAttributes } from "workflow";
+export default experimental_setAttributes;`}
+showSections={['parameters']}
+/>
+
+## Usage
+
+Call `experimental_setAttributes` from a `"use workflow"` function or a `"use step"` function. Calling it from plain application code is not supported because there is no active workflow run.
+
+Attribute values must be strings. Pass `undefined` to remove an attribute:
+
+```typescript lineNumbers
+import { experimental_setAttributes } from "workflow"
+
+export async function cleanupAttributes() {
+  "use workflow"
+
+  await experimental_setAttributes({ staleKey: undefined })
+}
+```
+
+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.
+
+Validation errors throw [`FatalError`](/docs/api-reference/workflow/fatal-error) and fail the run before an attribute write is attempted.
+
+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/fetch.mdx

@@ -7,12 +7,17 @@ prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
   - /docs/errors/fetch-in-workflow
+  - /docs/foundations/idempotency
 ---
 
 Makes HTTP requests from within a workflow. This is a special step function that wraps the standard `fetch` API, automatically handling serialization and providing retry semantics.
 
 This is useful when you need to call external APIs or services from within your workflow.
 
+<Callout type="warn">
+Because workflow `fetch()` has retry semantics, use idempotency keys when the request mutates an external system, such as creating a charge, sending an email, or enqueueing work. See [Idempotency](/docs/foundations/idempotency).
+</Callout>
+
 <Callout>
 `fetch` is a *special* type of step function provided and should be called directly inside workflow functions.
 </Callout>

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

@@ -47,6 +47,9 @@ Workflow SDK contains the following functions you can use inside your workflow f
     <Card href="/docs/api-reference/workflow/get-writable" title="getWritable()">
         Access the current workflow run's default stream.
     </Card>
+    <Card href="/docs/api-reference/workflow/experimental-set-attributes" title="experimental_setAttributes()">
+        Attach experimental string metadata to the current workflow run.
+    </Card>
 </Cards>
 
 ## Error Classes

package/docs/api-reference/workflow-ai/durable-agent.mdx

@@ -1,59 +1,21 @@
 ---
 title: DurableAgent
-description: Create AI agents that maintain state, call tools, and handle interruptions gracefully.
+description: Deprecated DurableAgent API reference; use WorkflowAgent for new durable agents.
 type: reference
-summary: Use DurableAgent to build AI agents that maintain state across steps and survive interruptions.
+summary: "Deprecated: use AI SDK's WorkflowAgent instead of DurableAgent."
 prerequisites:
   - /docs/ai
 related:
   - /docs/ai/defining-tools
 ---
 
-The `DurableAgent` class enables you to create AI-powered agents that can maintain state across workflow steps, call tools, and gracefully handle interruptions and resumptions.
-
-Tool calls can be implemented as workflow steps for automatic retries, or as regular workflow-level logic utilizing core library features such as [`sleep()`](/docs/api-reference/workflow/sleep) and [Hooks](/docs/foundations/hooks).
-
-```typescript lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
-import { getWritable } from "workflow";
-import { z } from "zod";
-import type { UIMessageChunk } from "ai";
-
-async function getWeather({ city }: { city: string }) {
-  "use step";
-
-  return `Weather in ${city} is sunny`;
-}
-
-async function myAgent() {
-  "use workflow";
-
-  const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
-    instructions: "You are a helpful weather assistant.",
-    temperature: 0.7,
-    tools: {
-      getWeather: {
-        description: "Get weather for a city",
-        inputSchema: z.object({ city: z.string() }),
-        execute: getWeather,
-      },
-    },
-  });
-
-  // The agent will stream its output to the workflow
-  // run's default output stream
-  const writable = getWritable<UIMessageChunk>();
+<Callout type="warn">
+`DurableAgent` is deprecated. Use AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) for new durable agents and migration guidance.
+</Callout>
 
-  const result = await agent.stream({
-    messages: [{ role: "user", content: "How is the weather in San Francisco?" }],
-    writable,
-  });
+This reference is kept for existing applications that still import `DurableAgent` from `@workflow/ai/agent`. Do not use `DurableAgent` for new code.
 
-  // result contains messages, steps, and optional structured output
-  console.log(result.messages);
-}
-```
+For current examples and implementation guidance, see AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) docs. For legacy code, the API surface below documents the existing `DurableAgent` exports.
 
 ## API Signature
 

package/docs/api-reference/workflow-api/get-hook-by-token.mdx

@@ -5,6 +5,8 @@ type: reference
 summary: Use getHookByToken to look up a hook's metadata and associated workflow run before resuming it.
 prerequisites:
   - /docs/foundations/hooks
+related:
+  - /docs/foundations/idempotency
 ---
 
 Retrieves a hook by its unique token, returning the associated workflow run information and any metadata that was set when the hook was created. This function is useful for inspecting hook details before deciding whether to resume a workflow.
@@ -13,6 +15,10 @@ Retrieves a hook by its unique token, returning the associated workflow run info
 `getHookByToken` is a runtime function that must be called from outside a workflow function.
 </Callout>
 
+<Callout type="info">
+Looking up a deterministic hook token is useful in hook-based idempotency flows, but it is only an advisory check. If no hook exists yet, another request can still start the same workflow before your `start()` call registers its hook. Use the lookup to avoid obvious duplicate starts, and handle the race inside the workflow by checking `await hook.getConflict()` before duplicate-sensitive work — on a conflict it resolves with the run that owns the token, so the duplicate can route the caller to the active owner. If duplicates must be rejected before a workflow body runs, keep a durable request record until native atomic start-and-hook registration exists. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript lineNumbers
 import { getHookByToken } from "workflow/api";
 
@@ -178,3 +184,4 @@ export async function POST(request: Request) {
 - [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) - Resume a hook with a payload.
 - [`createHook()`](/docs/api-reference/workflow/create-hook) - Create a hook in a workflow.
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper.
+- [Idempotency](/docs/foundations/idempotency) - Deduplicate step side effects and workflow starts.

package/docs/api-reference/workflow-api/get-run.mdx

@@ -5,12 +5,18 @@ type: reference
 summary: Use getRun to check a workflow run's status and metadata without blocking on completion.
 prerequisites:
   - /docs/foundations/starting-workflows
+related:
+  - /docs/foundations/idempotency
 ---
 
 Retrieves the workflow run metadata and status information for a given run ID. This function provides immediate access to workflow run details without waiting for completion, making it ideal for status checking and monitoring.
 
 Use this function when you need to check workflow status, get timing information, or access workflow metadata without blocking on workflow completion.
 
+<Callout type="info">
+`getRun()` retrieves a run when you already have its `runId`. It does not look up runs by a business key. For retried requests that should route to one active workflow, use a deterministic hook token and [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token). After a hook conflict, `HookConflictError.conflictingRunId` can be passed to `getRun()` to inspect, stream, or return the active owner. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript lineNumbers
 import { getRun } from "workflow/api";
 

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/resume-hook.mdx

@@ -7,6 +7,7 @@ prerequisites:
   - /docs/foundations/hooks
 related:
   - /docs/api-reference/workflow-api/resume-webhook
+  - /docs/foundations/idempotency
 ---
 
 Resumes a workflow run by sending a payload to a hook identified by its token.
@@ -155,8 +156,64 @@ export async function POST(request: Request) {
 }
 ```
 
+### Resume or Start
+
+A common endpoint shape is "resume or start": one route that resumes the active workflow run for a business key if one exists, or starts a new run otherwise. This comes up when the workflow uses a deterministic hook token as its idempotency key — for example, one active run per order or conversation.
+
+`resumeHook()` is the resume half of that flow. Try it first; if it throws `HookNotFoundError`, no active run owns the token yet, so start the workflow. One subtlety: `start()` returns before the new run executes and registers its hook, so you cannot resume immediately after starting. Retry the resume until the hook is registered — if you drop the payload and only start the workflow, the data from this request is lost.
+
+```typescript lineNumbers
+import { resumeHook, start } from "workflow/api";
+import { HookNotFoundError } from "workflow/errors";
+import { processOrder } from "./workflows/process-order";
+
+type OrderRequest = { confirmed: boolean };
+
+async function resumeWithRetry(token: string, payload: OrderRequest) {
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      return await resumeHook(token, payload); // [!code highlight]
+    } catch (error) {
+      if (!HookNotFoundError.is(error)) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  throw new Error("Workflow did not register its hook in time");
+}
+
+export async function POST(request: Request) {
+  const { orderId, confirmed } = await request.json();
+  const token = `order:${orderId}`;
+  const payload = { confirmed };
+
+  try {
+    // An active run already owns this token: resume it.
+    const hook = await resumeHook(token, payload); // [!code highlight]
+    return Response.json({ runId: hook.runId, reused: true });
+  } catch (error) {
+    if (!HookNotFoundError.is(error)) throw error;
+  }
+
+  // No hook yet: start a new run, then retry the resume so this
+  // request's payload still reaches the workflow.
+  const run = await start(processOrder, [orderId]); // [!code highlight]
+  const resumed = await resumeWithRetry(token, payload);
+
+  // A concurrent request can win the race between `start()` and hook
+  // registration; the resume always reaches the actual active owner.
+  return Response.json({
+    runId: resumed.runId,
+    reused: resumed.runId !== run.runId,
+  });
+}
+```
+
+See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for the full pattern, including how the workflow claims the token with `hook.getConflict()` and how concurrent starts converge on one active owner.
+
 ## Related Functions
 
 - [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) - Get hook details before resuming.
 - [`createHook()`](/docs/api-reference/workflow/create-hook) - Create a hook in a workflow.
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper.
+- [Idempotency](/docs/foundations/idempotency) - Deduplicate step side effects and workflow starts.

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

@@ -2,9 +2,11 @@
 title: start
 description: Start and enqueue a new workflow run.
 type: reference
-summary: Use start to programmatically enqueue a new workflow run from outside a workflow function.
+summary: Use start to programmatically enqueue a new workflow run.
 prerequisites:
   - /docs/foundations/starting-workflows
+related:
+  - /docs/foundations/idempotency
 ---
 
 Start/enqueue a new workflow run.
@@ -50,11 +52,14 @@ Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-
 
 ## Good to Know
 
-* The `start()` function is used in runtime/non-workflow contexts to programmatically trigger workflow executions.
+* The `start()` function is used in runtime contexts to programmatically trigger workflow executions.
+* In v5, `start()` can also be called directly from a workflow function to spawn a child run or continue work in a new run. See [Workflow Composition](/cookbook/common-patterns/workflow-composition) and [Versioning](/docs/foundations/versioning).
 * This is different from calling workflow functions directly, which is the typical pattern in Next.js applications.
 * The function returns immediately after enqueuing the workflow - it doesn't wait for the workflow to complete.
+* Each call to `start()` creates a new workflow run. If retried requests must route to one active workflow, have the workflow create a deterministic hook token and use [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) to reuse an already-registered active hook. The lookup is not atomic with `start()`, so concurrent callers can still create extra runs before the hook is registered; handle that race inside the workflow by checking `await hook.getConflict()` before duplicate-sensitive work — on a conflict it resolves with the run that owns the token, so the duplicate can return the active owner to the caller. If duplicates must be rejected before a workflow body runs, keep a durable request record until native atomic start-and-hook registration exists. See [Idempotency](/docs/foundations/idempotency#run-idempotency).
 * 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. Keys that start with `$` are reserved for framework and library code; framework-level callers can pass `allowReservedAttributes: true` to seed reserved keys, with the same semantics as the [`experimental_setAttributes`](/docs/api-reference/workflow/experimental-set-attributes) option of the same name.
 
 <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).
@@ -78,13 +83,14 @@ 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]
 ```
 
 ### Using `deploymentId: "latest"`
 
-Set `deploymentId` to `"latest"` to automatically resolve the most recent deployment for the current environment. This is useful when you want to ensure a workflow run targets the latest deployed version of your application rather than the deployment that initiated the call.
+Set `deploymentId` to `"latest"` to automatically resolve the most recent deployment for the current environment. This is useful when you want to ensure a workflow run targets the latest deployed version of your application rather than the deployment that initiated the call. For when to use this and how it fits with default run pinning, see [Versioning](/docs/foundations/versioning).
 
 ```typescript
 import { start } from "workflow/api";
@@ -96,7 +102,9 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
 ```
 
 <Callout type="info">
-The `deploymentId` option is currently a Vercel-specific feature. The `"latest"` value resolves to the most recent deployment matching your current environment — the same production target for production deployments, or the same git branch for preview deployments.
+The `deploymentId` option is currently a Vercel-specific feature. Other Worlds may implement this option differently to match their own deployment runtimes, and the World spec may rename it from `deploymentId` to `version` in a future SDK version. On Vercel, `"latest"` resolves to the most recent deployment matching your current environment — the same production target for production deployments, or the same git branch for preview deployments.
+
+In Worlds without atomic, immutable deployments (such as local development or self-hosted Postgres), there is no notion of multiple deployments to resolve between, so `deploymentId: "latest"` has no effect: the SDK logs a warning and the run targets the current deployment. This means a workflow that opts into `"latest"` on Vercel still runs unchanged in local development.
 </Callout>
 
 <Callout type="warn">

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'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Defaults to `'inline'` in development and `false` in production (smaller function bundles — helps stay under the Vercel 250MB function size limit). Set it explicitly, or use the `WORKFLOW_SOURCEMAP` environment variable, to override in either environment. |
+
+### 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/index.mdx

@@ -0,0 +1,85 @@
+---
+title: "workflow/errors"
+description: Semantic error types thrown by the Workflow SDK and its storage backends.
+type: overview
+summary: Explore the error classes exported from workflow/errors for handling workflow failures.
+related:
+  - /docs/foundations/errors-and-retries
+---
+
+API reference for the error classes exported from the `workflow/errors` package.
+
+All errors extend [`WorkflowError`](/docs/api-reference/workflow-errors/workflow-error), so you can catch any SDK error with a single `instanceof` check, or narrow to a specific class for fine-grained handling.
+
+## Base Classes
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/workflow-error" title="WorkflowError">
+        Base class for all workflow error types.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-world-error" title="WorkflowWorldError">
+        Base error for failures from workflow storage backends.
+    </Card>
+</Cards>
+
+## Registration Errors
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/workflow-not-registered-error" title="WorkflowNotRegisteredError">
+        Thrown when a workflow function is not registered in the current deployment.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/step-not-registered-error" title="StepNotRegisteredError">
+        Thrown when a step function is not registered in the current deployment.
+    </Card>
+</Cards>
+
+## Run Errors
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/workflow-run-not-found-error" title="WorkflowRunNotFoundError">
+        Thrown when operating on a workflow run that does not exist.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-run-failed-error" title="WorkflowRunFailedError">
+        Thrown when awaiting the return value of a failed workflow run.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-run-cancelled-error" title="WorkflowRunCancelledError">
+        Thrown when awaiting the return value of a cancelled workflow run.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-run-not-completed-error" title="WorkflowRunNotCompletedError">
+        Thrown when requesting the result of a workflow run that has not completed yet.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-runtime-error" title="WorkflowRuntimeError">
+        Thrown when the workflow runtime encounters an execution error, such as serialization failures or timeouts.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/run-expired-error" title="RunExpiredError">
+        Thrown when a workflow run has expired and can no longer be operated on.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/run-not-supported-error" title="RunNotSupportedError">
+        Thrown when a workflow run requires a newer workflow spec version than the installed SDK supports.
+    </Card>
+</Cards>
+
+## Hook Errors
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/hook-not-found-error" title="HookNotFoundError">
+        Thrown when resuming a hook that does not exist.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/hook-conflict-error" title="HookConflictError">
+        Thrown when creating a hook with a token that is already in use by another workflow run.
+    </Card>
+</Cards>
+
+## Backend Errors
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/throttle-error" title="ThrottleError">
+        Thrown when a request is rate-limited by the workflow backend.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/entity-conflict-error" title="EntityConflictError">
+        Thrown when a storage operation conflicts with the current entity state.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/too-early-error" title="TooEarlyError">
+        Thrown when a request is made before the system is ready to process it.
+    </Card>
+</Cards>

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"
   ]
 }