workflow 5.0.0-beta.43 → 5.0.0-beta.44

package/docs/ai/resumable-streams.mdx

@@ -13,14 +13,14 @@ related:
 ---
 
 <Callout type="warn">
-`WorkflowChatTransport` now ships in AI SDK as a 1:1 port — import it from `@ai-sdk/workflow` (the `@workflow/ai` export is deprecated). See [Resumable Streaming with `WorkflowChatTransport`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#resumable-streaming-with-workflowchattransport) for the full reference.
+`WorkflowChatTransport` now ships in AI SDK as a 1:1 port, so import it from `@ai-sdk/workflow` (the `@workflow/ai` export is deprecated). See [Resumable Streaming with `WorkflowChatTransport`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#resumable-streaming-with-workflowchattransport) for the full reference.
 </Callout>
 
-When building chat interfaces, it's common to run into network interruptions, page refreshes, or serverless function timeouts, which can break the connection to an in-progress agent.
+Network interruptions, page refreshes, or Vercel Functions timeouts can break a chat interface's connection to an in-progress agent.
 
-Where a standard chat implementation would require the user to resend their message and wait for the entire response again, workflow runs are durable, and so are the streams attached to them. This means a stream can be resumed at any point, optionally only syncing the data that was missed since the last connection.
+Workflow runs and their attached streams are durable, so users can resume a stream without resending a message or waiting for the entire response again. The client can optionally sync only the data missed since the last connection.
 
-Resumable streams come out of the box with Workflow SDK, however, the client needs to recognize that a stream exists, and needs to know which stream to reconnect to, and needs to know where to start from. For this, Workflow SDK provides the [`WorkflowChatTransport`](/docs/api-reference/workflow-ai/workflow-chat-transport) helper, a drop-in transport for the AI SDK that handles client-side resumption logic for you.
+Workflow SDK supports resumable streams, but the client must identify the stream and the position from which to reconnect. The [`WorkflowChatTransport`](/docs/api-reference/workflow-ai/workflow-chat-transport) helper is a drop-in AI SDK transport that handles this client-side resumption logic.
 
 <Callout type="info">
 When deploying a streaming route to Vercel, enable request cancellation so a browser disconnect terminates that route's abandoned stream reader instead of letting the function run until `FUNCTION_INVOCATION_TIMEOUT`. See [Avoiding Function Timeouts After Client Disconnects](/docs/foundations/streaming#avoiding-function-timeouts-after-client-disconnects).
@@ -28,15 +28,15 @@ When deploying a streaming route to Vercel, enable request cancellation so a bro
 
 ## Implementing stream resumption
 
-Let's add stream resumption to our Flight Booking Agent that we build in the [Building Durable AI Agents](/docs/ai) guide.
+Add stream resumption to the Flight Booking Agent from the [Building Durable AI Agents](/docs/ai) guide.
 
 <Steps>
 
 <Step>
 
-### Return the Run ID from Your API
+### Return the run ID from your API
 
-Modify your chat endpoint to include the workflow run ID in a response header. The Run ID uniquely identifies the run's stream, so it allows the client to know which stream to reconnect to.
+Modify your chat endpoint to include the workflow run ID in a response header. The run ID uniquely identifies the stream so the client knows which stream to reconnect to.
 
 {/*@skip-typecheck: incomplete code sample*/}
 
@@ -62,9 +62,9 @@ export async function POST(req: Request) {
 
 <Step>
 
-### Add a Stream Reconnection Endpoint
+### Add a stream reconnection endpoint
 
-Currently we only have one API endpoint that always creates a new run, so we need to create a new API route that returns the stream for an existing run:
+Create an API route that returns the stream for an existing run. The current endpoint always creates a new run.
 
 ```typescript title="app/api/chat/[id]/stream/route.ts" lineNumbers
 import { createUIMessageStreamResponse } from "ai";
@@ -100,16 +100,16 @@ export async function GET(
 }
 ```
 
-The `startIndex` parameter ensures the client can choose where to resume the stream from. For instance, if the function times out during streaming, the chat transport will use `startIndex` to resume the stream exactly from the last token it received. Negative values are also supported (e.g. `-5` starts 5 chunks before the end), which is useful for custom stream consumers (such as a dashboard showing recent output) that want to show the most recent output without replaying the full stream.
+The `startIndex` parameter lets the client choose where to resume the stream. For example, if the function times out during streaming, the chat transport uses `startIndex` to resume from the last token it received. Negative values are also supported. A value of `-5` starts 5 chunks before the end, which is useful for custom stream consumers that show recent output without replaying the full stream.
 
-When using a negative `startIndex`, your stream endpoint must return a `x-workflow-stream-tail-index` header in order for relative resumption to work. Missing the header will fall back to replaying the entire stream.
+When using a negative `startIndex`, your stream endpoint must return an `x-workflow-stream-tail-index` header for relative resumption. If the header is missing, the transport replays the entire stream.
 </Step>
 
 <Step>
 
-### Use `WorkflowChatTransport` in the Client
+### Use `WorkflowChatTransport` in the client
 
-Replace the default transport in AI-SDK's `useChat` with [`WorkflowChatTransport`](
+Replace the default transport in AI SDK's `useChat` with [`WorkflowChatTransport`](
   /docs/api-reference/workflow-ai/workflow-chat-transport
 ), and update the callbacks to store and use the latest run ID. For now, we'll store the run ID in localStorage. For your own app, this would be stored wherever you store session information.
 
@@ -166,23 +166,23 @@ export default function ChatPage() {
 
 </Steps>
 
-Now try the flight booking example again. Open it up in a separate tab, or spam the refresh button, and see how the client connects to the same chat stream every time.
+Open the flight booking example in another tab or refresh the page repeatedly. The client reconnects to the same chat stream each time.
 
-## How It Works
+## How it works
 
-1. When the user sends a message, `WorkflowChatTransport` makes a POST to `/api/chat`
-2. The API starts a workflow and returns the run ID in the `x-workflow-run-id` header
-3. `onChatSendMessage` stores this run ID in localStorage
-4. If the stream is interrupted before receiving a "finish" chunk, the transport automatically reconnects
-5. `prepareReconnectToStreamRequest` builds the reconnection URL using the stored run ID, pointing to the new endpoint `/api/chat/{runId}/stream`
-6. The reconnection endpoint returns the stream from where the client left off
-7. When the stream completes, `onChatEnd` clears the stored run ID
+1. When the user sends a message, `WorkflowChatTransport` makes a `POST` request to `/api/chat`.
+2. The API starts a workflow and returns the run ID in the `x-workflow-run-id` header.
+3. `onChatSendMessage` stores this run ID in `localStorage`.
+4. If the stream is interrupted before receiving a `finish` chunk, the transport automatically reconnects.
+5. `prepareReconnectToStreamRequest` builds the reconnection URL using the stored run ID and points to `/api/chat/{runId}/stream`.
+6. The reconnection endpoint returns the stream from where the client left off.
+7. When the stream completes, `onChatEnd` clears the stored run ID.
 
-This approach also handles page refreshes, as the client will automatically reconnect to the stream from the last known position when the UI loads with a stored run ID, following the behavior of [AI SDK's stream resumption](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot-resume-streams#chatbot-resume-streams).
+This approach also handles page refreshes, as the client will automatically reconnect to the stream from the last known position when the user interface (UI) loads with a stored run ID, following the behavior of [AI SDK's stream resumption](https://ai-sdk.dev/docs/ai-sdk-ui/chatbot-resume-streams#chatbot-resume-streams).
 
 ### Resuming from the end of the stream
 
-By default, reconnecting replays the entire stream from the beginning (`startIndex: 0`). If you only need to show recent output — for example, when resuming a long conversation after a page refresh — you can set `initialStartIndex` to a negative value to read from the end of the stream instead:
+By default, reconnecting replays the entire stream from the beginning (`startIndex: 0`). If you only need to show recent output (for example, when resuming a long conversation after a page refresh), you can set `initialStartIndex` to a negative value to read from the end of the stream instead:
 
 {/*@skip-typecheck: incomplete code sample*/}
 
@@ -206,8 +206,8 @@ When using a negative `initialStartIndex`, the reconnection endpoint **must** re
 
 A workflow stream is a flat sequence of chunks, but the AI SDK's UI protocol groups chunks into logical parts (`text-*`, `reasoning-*`, `tool-input-*`) that must be opened with a `*-start` before any `*-delta` or `*-end`. A non-zero `startIndex` can land in the middle of an open part. See [`WorkflowChatTransport` → Mid-part resumes](/docs/api-reference/workflow-ai/workflow-chat-transport#mid-part-resumes) for how this is handled and an example of rewinding to a step boundary on the server.
 
-## Related Documentation
+## Related documentation
 
-- [`WorkflowChatTransport` API Reference](/docs/api-reference/workflow-ai/workflow-chat-transport) - Full configuration options
-- [Streaming](/docs/foundations/streaming) - Understanding workflow streams
-- [`getRun()` API Reference](/docs/api-reference/workflow-api/get-run) - Retrieving existing runs
+- [`WorkflowChatTransport` API reference](/docs/api-reference/workflow-ai/workflow-chat-transport): Full configuration options
+- [Streaming](/docs/foundations/streaming): Understanding workflow streams
+- [`getRun()` API reference](/docs/api-reference/workflow-api/get-run): Retrieving existing runs

package/docs/ai/sleep-and-delays.mdx

@@ -12,7 +12,7 @@ related:
   - /docs/api-reference/workflow/sleep
 ---
 
-AI agents sometimes need to pause execution in order to schedule recurring or future actions, wait before retrying an operation (e.g. for rate limiting), or wait for external state to be available.
+AI agents sometimes need to pause execution to schedule recurring or future actions, wait before retrying an operation (e.g. for rate limiting), or wait for external state to be available.
 
 Workflow SDK's `sleep` function enables Agents to pause execution without consuming resources, and resume at a specified time, after a specified duration, or in response to an external event. Workflow operation that suspend will survive restarts, new deploys, and infrastructure changes, independent of whether the suspense takes seconds or months.
 
@@ -20,15 +20,15 @@ Workflow SDK's `sleep` function enables Agents to pause execution without consum
 See the [`sleep()` API Reference](/docs/api-reference/workflow/sleep) for the full list of supported duration formats and detailed API documentation, and see the [hooks](/docs/foundations/hooks) documentation for more information on how to resume in response to external events.
 </Callout>
 
-## Adding a Sleep Tool
+## Adding a sleep tool
 
-Sleep is a built-in function in Workflow SDK, so exposing it as a tool is as simple as wrapping it in a tool definition. Learn more about how to define tools in [Patterns for Defining Tools](/docs/ai/defining-tools).
+Sleep is a built-in function in Workflow SDK. To expose it as a tool, wrap it in a tool definition. Learn more about how to define tools in [Patterns for Defining Tools](/docs/ai/defining-tools).
 
 <Steps>
 
 <Step>
 
-### Define the Tool
+### Define the tool
 
 Add a new "sleep" tool to the `tools` defined in `workflows/chat/steps/tools.ts`:
 
@@ -60,7 +60,7 @@ export const flightBookingTools = {
 ```
 
 <Callout type="info">
-  Note that the `sleep()` function must be called from within a workflow context, not from within a step. This is why `executeSleep` does not have `"use step"` - it runs in the workflow context where `sleep()` is available.
+  Call `sleep()` from within a workflow context, not from within a step. `executeSleep` does not have `"use step"` because it runs in the workflow context where `sleep()` is available.
 </Callout>
 
  This already makes the full sleep functionality available to the Agent!
@@ -71,7 +71,7 @@ export const flightBookingTools = {
 
 ### Show the tool status in the UI
 
-To round it off, extend the UI to display the tool call status. This can be done either by displaying the tool call information directly, or by emitting custom data parts to the stream (see [Streaming Updates from Tools](/docs/ai/streaming-updates-from-tools) for more details). In this case, since there aren't any fine-grained progress updates to show, we'll just display the tool call information directly:
+To round it off, extend the UI to display the tool call status. This can be done either by displaying the tool call information directly, or by emitting custom data parts to the stream (see [Streaming Updates from Tools](/docs/ai/streaming-updates-from-tools) for more details). Since there aren't any fine-grained progress updates to show, we'll display the tool call information directly:
 
 {/*@skip-typecheck: incomplete code sample*/}
 
@@ -153,11 +153,11 @@ function renderToolOutput(part: any) {
 
 Now, try out the Flight Booking Agent again, and ask it to sleep for 10 seconds before checking any flight. You'll see the agent pause, and the UI reflect the tool call status.
 
-## Use Cases
+## Use cases
 
 Aside from providing `sleep()` as a tool, there are other use cases for Agents that commonly call for suspension and resumption.
 
-### Rate Limiting
+### Rate limiting
 
 When hitting API rate limits, use `RetryableError` with a delay:
 
@@ -180,7 +180,7 @@ async function callRateLimitedAPI(endpoint: string) {
 }
 ```
 
-## Related Documentation
+## Related documentation
 
 - [`sleep()` API Reference](/docs/api-reference/workflow/sleep) - Full API documentation with all duration formats
 - [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding workflow context

package/docs/ai/streaming-updates-from-tools.mdx

@@ -22,7 +22,7 @@ As an example, we'll extend out Flight Booking Agent to use emit more granular p
 
 <Step>
 
-### Define Your Data Part Type
+### Define your data part type
 
 First, define a TypeScript type for your custom data part. This ensures type safety across your tool and client code:
 
@@ -44,7 +44,7 @@ The `type` field must be a string starting with `data-` followed by your custom
 
 <Step>
 
-### Emit Updates from Your Tool
+### Emit updates from your tool
 
 Use [`getWritable()`](/docs/api-reference/workflow/get-writable) inside a step function to get a handle to the stream. This is the same stream that the LLM and other tools calls are writing to, so we can inject out own data packets directly.
 
@@ -95,7 +95,7 @@ Key points:
 </Step>
 
 <Step>
-### Handle Data Parts in the Client
+### Handle data parts in the client
 
 Update your chat component to detect and render the custom data parts. Data parts are stored in the message's `parts` array alongside text and tool invocation parts:
 
@@ -143,7 +143,7 @@ The pattern is:
 
 Now, when you run the agent to search for flights, you'll see the flight results pop up one after another. This will be most useful if you have tool calls that take minutes to complete, and you need to show granular progress updates to the user.
 
-## Related Documentation
+## Related documentation
 
 - [Building Durable AI Agents](/docs/ai) - Complete guide to durable agents
 - [`getWritable()` API Reference](/docs/api-reference/workflow/get-writable) - Stream API details

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

@@ -3,7 +3,7 @@ title: "@workflow/vitest"
 description: Vitest plugin and test helpers for integration testing workflows in-process.
 ---
 
-The `@workflow/vitest` package provides a Vitest plugin and test helpers for running full workflow integration tests in-process — no server required.
+The `@workflow/vitest` package provides a Vitest plugin and test helpers for running full workflow integration tests in-process, no server required.
 
 ## Plugin
 
@@ -21,7 +21,7 @@ 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.
+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.
 
 
 ```typescript
@@ -46,7 +46,7 @@ export default defineConfig({
 
 **Returns:** `Plugin[]`
 
-## Setup Functions
+## Setup functions
 
 ### `buildWorkflowTests()`
 
@@ -108,11 +108,11 @@ Tears down the workflow test world. Clears the global world and closes the Local
 | `dataDir` | `string` | `<rootDir>/.workflow-data` | Directory for workflow runtime data written by the test world. Relative paths resolve against `cwd`. |
 | `outDir` | `string` | `<rootDir>/.workflow-vitest` | Directory for generated workflow and step bundles. Relative paths resolve against `cwd`. |
 
-## Test Helpers
+## Test helpers
 
 ### `waitForSleep()`
 
-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.
+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.
 
 
 ```typescript
@@ -131,9 +131,9 @@ await getRun(run.runId).wakeUp({ correlationIds: [sleepId] }); // [!code highlig
 | `run` | `Run<any>` | The workflow run to monitor |
 | `options?` | `WaitOptions` | Polling and timeout configuration |
 
-**Returns:** `Promise<string>` — The correlation ID of the first pending sleep. Pass this to `wakeUp({ correlationIds: [id] })` to target a specific sleep.
+**Returns:** `Promise<string>`, the correlation ID of the first pending sleep. Pass this to `wakeUp({ correlationIds: [id] })` to target a specific sleep.
 
-#### Behavior with Multiple Sleeps
+#### Behavior with multiple sleeps
 
 - **Sequential sleeps**: `waitForSleep()` returns each sleep as the workflow reaches it. After waking one, call `waitForSleep()` again for the next.
 - **Parallel sleeps**: `waitForSleep()` returns whichever pending sleep is found first. After waking it, call `waitForSleep()` again to get the next one.
@@ -159,7 +159,7 @@ await resumeHook(hook.token, { approved: true }); // [!code highlight]
 | `run` | `Run<any>` | The workflow run to monitor |
 | `options?` | `WaitOptions & { token?: string }` | Polling, timeout, and optional token filter |
 
-**Returns:** `Promise<Hook>` — The first pending hook matching the filter. The hook object includes `token`, `hookId`, and `runId`.
+**Returns:** `Promise<Hook>`, the first pending hook matching the filter. The hook object includes `token`, `hookId`, and `runId`.
 
 ### `WaitOptions`
 

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

@@ -26,7 +26,7 @@ export async function hookWorkflow() {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -66,11 +66,11 @@ 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 hook, including one kept reserved after its run ends, 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).
+Use `hook.getConflict()` to check whether the hook token is already claimed by another hook, including one kept reserved after its run ends, 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).
 
 ## Examples
 
-### Basic Usage
+### Basic usage
 
 When creating a hook, you can specify a payload type for automatic type safety:
 
@@ -91,7 +91,7 @@ export async function approvalWorkflow() {
 }
 ```
 
-### Customizing Tokens
+### Customizing tokens
 
 Tokens are used to identify a specific hook. You can customize the token to be more specific to a use case.
 
@@ -115,7 +115,7 @@ export async function slackBotWorkflow(channelId: string) {
 }
 ```
 
-### Detecting Token Conflicts
+### 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:
 
@@ -141,7 +141,7 @@ async function processOrder(orderId: string) {
 }
 ```
 
-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`.
+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 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 [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies in context.
 
@@ -149,7 +149,7 @@ On a conflict, the resolved value is a `Run` handle for the run that owns the to
 Custom hook tokens are the recommended way to coordinate active workflow runs. Use a deterministic token from your domain, such as an order ID or conversation ID, create the hook near the beginning of the workflow, and check `await hook.getConflict()` before work that depends on owning the token. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
 </Callout>
 
-### Keep a Token Unavailable After the Run Ends
+### Keep a token unavailable after the run ends
 
 By default, another Hook can use the token after its workflow ends. Set `experimental_minRetention` to keep the token unavailable for at least a specific time after `createHook()` runs:
 
@@ -190,7 +190,7 @@ After the workflow ends, [`getHookByToken()`](/docs/api-reference/workflow-api/g
 This option is experimental. Worlds can limit how long tokens are retained; see [World configuration](/docs/configuration/worlds) for each World's limit. If the configured World does not support minimum retention, the workflow fails when registering the Hook. `createWebhook()` does not accept this option.
 </Callout>
 
-### Waiting for Multiple Payloads
+### Waiting for multiple payloads
 
 You can also wait for multiple payloads by using the `for await...of` syntax.
 
@@ -213,7 +213,7 @@ export async function collectHookWorkflow() {
 }
 ```
 
-### Disposing Hooks Early
+### Disposing hooks early
 
 You can dispose a hook early to release its token for reuse by another workflow. This is useful for handoff patterns where one workflow needs to transfer a hook token to another workflow while still running.
 
@@ -242,7 +242,7 @@ export async function handoffWorkflow(channelId: string) {
 
 After calling `dispose()`, the hook will no longer receive events and its token becomes available for other workflows to use.
 
-### Automatic Disposal with `using`
+### Automatic disposal with `using`
 
 Hooks implement the [TC39 Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management) proposal, allowing automatic disposal with the `using` keyword:
 
@@ -268,9 +268,9 @@ export async function scopedHookWorkflow(channelId: string) {
 
 This is equivalent to manually calling `dispose()` but ensures the hook is always cleaned up, even if an error occurs.
 
-## Related Functions
+## Related functions
 
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper
-- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) - Resume a hook with a payload
-- [`createWebhook()`](/docs/api-reference/workflow/create-webhook) - Higher-level HTTP webhook abstraction
-- [Idempotency](/docs/foundations/idempotency) - Deduplicate step side effects and workflow starts
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Type-safe hook helper
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook): Resume a hook with a payload
+- [`createWebhook()`](/docs/api-reference/workflow/create-webhook): Higher-level HTTP webhook abstraction
+- [Idempotency](/docs/foundations/idempotency): Deduplicate step side effects and workflow starts

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

@@ -14,7 +14,7 @@ Creates a webhook that can be used to suspend and resume a workflow run upon rec
 Webhooks provide a way for external systems to send HTTP requests directly to your workflow. Unlike hooks which accept arbitrary payloads, webhooks work with standard HTTP `Request` objects and can return HTTP `Response` objects.
 
 <Callout type="warn">
-`createWebhook()` creates a public endpoint at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests resuming that webhook. This is convenient for prototypes and simple resume links because it avoids creating another route, but if you need stronger security, prefer [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own route and authorize the request before calling [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) to avoid unauthenticated workflow resumptions.
+`createWebhook()` creates a public endpoint at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests resuming that webhook. This is convenient for prototypes and basic resume links because it avoids creating another route, but if you need stronger security, prefer [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own route and authorize the request before calling [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) to avoid unauthenticated workflow resumptions.
 </Callout>
 
 ```ts lineNumbers
@@ -31,7 +31,7 @@ export async function webhookWorkflow() {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -63,22 +63,22 @@ When using `createWebhook({ respondWith: 'manual' })`, the resolved request type
 <Callout type="info">
 Use the simplest option that satisfies the prompt:
 
-- `createWebhook()` — generated callback URL, and the default `202 Accepted` response is fine
-- `createWebhook({ respondWith: 'manual' })` — generated callback URL, but you must send a custom body, status, or headers
-- `createHook()` + `resumeHook()` — the app resumes from server-side code with a deterministic business token instead of a generated callback URL
+- `createWebhook()`: generated callback URL, and the default `202 Accepted` response is fine
+- `createWebhook({ respondWith: 'manual' })`: generated callback URL, but you must send a custom body, status, or headers
+- `createHook()` + `resumeHook()`: the app resumes from server-side code with a deterministic business token instead of a generated callback URL
 </Callout>
 
 <details>
 <summary>Common wrong turns</summary>
 
-- Do not use `respondWith: 'manual'` just because the flow has a callback URL.
+- A callback URL alone does not require `respondWith: 'manual'`.
 - Do not use `RequestWithResponse` unless you chose manual mode.
 - Do not invent a custom callback route when `webhook.url` is the intended callback surface.
 </details>
 
 ## Examples
 
-### Basic Usage
+### Basic usage
 
 Create a webhook that receives HTTP requests and logs the request details:
 
@@ -101,11 +101,11 @@ export async function basicWebhookWorkflow() {
 }
 ```
 
-### Responding to Webhook Requests (Manual Mode)
+### Responding to webhook requests (manual mode)
 
 Use this section only when the caller requires a non-default HTTP response. If `202 Accepted` is acceptable, use `createWebhook()` without `respondWith: "manual"`.
 
-Pass `{ respondWith: "manual" }` to get a `RequestWithResponse` object with a `respondWith()` method. Note that `respondWith()` must be called from within a step function:
+Pass `{ respondWith: "manual" }` to get a `RequestWithResponse` object with a `respondWith()` method. Call `respondWith()` from within a step function:
 
 ```typescript lineNumbers
 import { createWebhook, type RequestWithResponse } from "workflow"
@@ -143,7 +143,7 @@ async function processData(data: any): Promise<void> {
 }
 ```
 
-### Waiting for Multiple Requests
+### Waiting for multiple requests
 
 You can also wait for multiple requests by using the `for await...of` syntax.
 
@@ -182,9 +182,9 @@ export async function eventCollectorWorkflow() {
 }
 ```
 
-## Related Functions
+## Related functions
 
-- [`createHook()`](/docs/api-reference/workflow/create-hook) — Use when the app resumes from server-side code with a deterministic business token.
-- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) — Pairs with `createHook()` for deterministic server-side resume.
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) — Type-safe hook helper.
-- [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) — Low-level runtime API. Most integrations should call `webhook.url` directly instead of adding a custom callback route.
+- [`createHook()`](/docs/api-reference/workflow/create-hook): Use when the app resumes from server-side code with a deterministic business token.
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook): Pairs with `createHook()` for deterministic server-side resume.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Type-safe hook helper.
+- [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook): Low-level runtime API. Most integrations should call `webhook.url` directly instead of adding a custom callback route.

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

@@ -33,7 +33,7 @@ export async function nameWorkflow() {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -59,11 +59,11 @@ interface TypedHook<TInput, TOutput> {
 export default TypedHook;`}
 />
 
-`create()` is called inside a `"use workflow"` function to create the hook; `resume()` is called from runtime code (an API route or server action). When a `schema` is provided, `resume()` accepts the raw input type (`TInput`) and the workflow receives the validated and possibly transformed output type (`TOutput`); without a schema, `TOutput` defaults to `TInput`. `resume()` throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active hook — it does not return `null`.
+`create()` is called inside a `"use workflow"` function to create the hook; `resume()` is called from runtime code (an API route or server action). When a `schema` is provided, `resume()` accepts the raw input type (`TInput`) and the workflow receives the validated and possibly transformed output type (`TOutput`); without a schema, `TOutput` defaults to `TInput`. `resume()` throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active hook. It does not return `null`.
 
 ## Examples
 
-### Basic Type-Safe Hook Definition
+### Basic type-safe hook definition
 
 By defining the hook once with a specific payload type, you can reuse it in multiple workflows and API routes with automatic type safety.
 
@@ -88,7 +88,7 @@ export async function workflowWithApproval() {
 }
 ```
 
-### Resuming with Type Safety
+### Resuming with type safety
 
 Hooks can be resumed using the same defined hook and a token. By using the same hook, you can ensure that the payload matches the defined type when resuming a hook. `resume()` resolves to the resumed hook and throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active hook.
 
@@ -116,7 +116,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### Validate and Transform with Schema
+### Validate and transform with schema
 
 You can provide runtime validation and transformation of hook payloads using the `schema` option. This option accepts any validator that conforms to the [Standard Schema v1](https://standardschema.dev) specification.
 
@@ -174,7 +174,7 @@ export async function POST(request: Request) {
 }
 ```
 
-#### Using Other Standard Schema Libraries
+#### Using other Standard Schema libraries
 
 The same pattern works with any Standard Schema v1 compliant library. Here's an example with [Valibot](https://valibot.dev):
 
@@ -190,7 +190,7 @@ export const approvalHook = defineHook({
 });
 ```
 
-### Customizing Tokens
+### Customizing tokens
 
 Tokens are used to identify a specific hook and for resuming a hook. You can customize the token to be more specific to a use case.
 
@@ -211,7 +211,7 @@ export async function slackBotWorkflow(channelId: string) {
 }
 ```
 
-## Related Functions
+## Related functions
 
-* [`createHook()`](/docs/api-reference/workflow/create-hook) - Create a hook in a workflow.
-* [`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.
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook): Resume a hook with a payload.

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

@@ -27,7 +27,7 @@ async function fallibleStep() {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Constructor
 
@@ -50,7 +50,7 @@ interface FatalError {
 export default FatalError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `FatalError.is(value)`
 

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

@@ -34,7 +34,7 @@ async function apiWorkflow() {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -60,9 +60,9 @@ showSections={['returns']}
 
 ## Examples
 
-### Basic Usage
+### Basic usage
 
-Here's a simple example of how you can use `fetch` inside your workflow.
+Here's an example of how you can use `fetch` inside your workflow.
 
 ```typescript lineNumbers
 import { fetch } from "workflow"
@@ -87,13 +87,13 @@ async function apiWorkflow() {
 }
 ```
 
-We call `fetch()` with a URL and optional request options, just like the standard fetch API. The workflow runtime automatically handles the response serialization.
+We call `fetch()` with a URL and optional request options, like the standard fetch API. The workflow runtime automatically handles the response serialization.
 
-This API is provided as a convenience to easily use `fetch` in workflow, but often, you might want to extend and implement your own fetch for more powerful error handing and retry logic.
+This API lets you use `fetch` in a workflow. You can also implement a custom fetch for different error handling and retry logic.
 
-### Customizing Fetch Behavior
+### Customizing fetch behavior
 
-Here's an example of a custom fetch wrapper that provides more sophisticated error handling with custom retry logic. Call `globalThis.fetch` inside your own `"use step"` function — calling the workflow `fetch` imported from `workflow` would nest a step inside a step:
+The following custom fetch wrapper provides more advanced error handling with custom retry logic. Call `globalThis.fetch` inside your own `"use step"` function because calling the workflow `fetch` imported from `workflow` would nest a step inside a step:
 
 ```typescript lineNumbers
 import { FatalError, RetryableError } from "workflow"

package/docs/api-reference/workflow/get-step-metadata.mdx

@@ -34,7 +34,7 @@ async function logStepId() {
 }
 ```
 
-### Example: Use `stepId` as an idempotency key
+### Example: use `stepId` as an idempotency key
 
 ```typescript lineNumbers
 import { getStepMetadata } from "workflow";
@@ -61,7 +61,7 @@ async function chargeUser(userId: string, amount: number) {
   <a href="/docs/foundations/idempotency">Idempotency</a> guide.
 </Callout>
 
-## API Signature
+## API signature
 
 ### Parameters