workflow 5.0.0-beta.4 → 5.0.0-beta.41

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>
@@ -88,7 +93,7 @@ This API is provided as a convenience to easily use `fetch` in workflow, but oft
 
 ### Customizing Fetch Behavior
 
-Here's an example of a custom fetch wrapper that provides more sophisticated error handling with custom retry logic:
+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:
 
 ```typescript lineNumbers
 import { FatalError, RetryableError } from "workflow"
@@ -99,7 +104,7 @@ export async function customFetch(
 ) {
     "use step"
 
-    const response = await fetch(url, init)
+    const response = await globalThis.fetch(url, init)
 
     // Handle client errors (4xx) - don't retry
     if (response.status >= 400 && response.status < 500) {
@@ -140,7 +145,6 @@ export async function customFetch(
 
 This example demonstrates:
 
-- Setting custom `maxRetries` to 5 retries (6 total attempts including the initial attempt).
 - Throwing [`FatalError`](/docs/api-reference/workflow/fatal-error) for client errors (400-499) to prevent retries.
 - Handling 429 rate limiting by reading the `Retry-After` header and using [`RetryableError`](/docs/api-reference/workflow/retryable-error).
-- Allowing automatic retries for server errors (5xx).
+- Allowing automatic retries for server errors (5xx) by throwing a plain `Error`.

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/set-attributes" title="setAttributes()">
+        Attach string metadata to the current workflow run.
+    </Card>
 </Cards>
 
 ## Error Classes

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

@@ -0,0 +1,61 @@
+---
+title: setAttributes
+description: Attach string metadata to workflow run for observability.
+type: reference
+summary: Use 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.
+
+```typescript lineNumbers
+import { setAttributes } from "workflow"
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow"
+
+  await setAttributes({
+    phase: "received",
+    orderId,
+  })
+}
+```
+
+## API Signature
+
+### Parameters
+
+<TSDoc
+definition={`
+import { setAttributes } from "workflow";
+export default setAttributes;`}
+showSections={['parameters']}
+/>
+
+## Usage
+
+Call `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 { setAttributes } from "workflow"
+
+export async function cleanupAttributes() {
+  "use workflow"
+
+  await 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 `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/sleep.mdx

@@ -14,7 +14,7 @@ Suspends a workflow for a specified duration or until an end date without consum
 This is useful when you want to resume a workflow after some duration or date.
 
 <Callout>
-`sleep` is a *special* type of step function and should be called directly inside workflow functions.
+`sleep` is a built-in workflow runtime function (backed by a timer event in the event log, not a step) and should be called directly inside workflow functions.
 </Callout>
 
 ```typescript lineNumbers

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 — see the [migration guide](https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent).
+</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-ai/index.mdx

@@ -13,9 +13,9 @@ Helpers for integrating AI SDK for building AI-powered workflows.
 
 <Cards>
     <Card title="DurableAgent" href="/docs/api-reference/workflow-ai/durable-agent">
-      A class for building durable AI agents that maintain state across workflow steps and handle tool execution with automatic retries.
+      Deprecated — use AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent). Reference kept for existing `@workflow/ai/agent` imports.
     </Card>
     <Card title="WorkflowChatTransport" href="/docs/api-reference/workflow-ai/workflow-chat-transport">
-      A drop-in transport for the AI SDK for automatic reconnection in interrupted streams.
+      Deprecated — use AI SDK's [`WorkflowChatTransport`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#resumable-streaming-with-workflowchattransport) from `@ai-sdk/workflow`. Reference kept for existing `@workflow/ai` imports.
     </Card>
 </Cards>

package/docs/api-reference/workflow-ai/workflow-chat-transport.mdx

@@ -9,6 +9,10 @@ related:
   - /docs/ai/resumable-streams
 ---
 
+<Callout type="warn">
+`WorkflowChatTransport` from `@workflow/ai` is deprecated. AI SDK ships a 1:1 port — use [`WorkflowChatTransport` from `@ai-sdk/workflow`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#resumable-streaming-with-workflowchattransport) instead. This reference is kept for existing applications that still import it from `@workflow/ai`.
+</Callout>
+
 A chat transport implementation for the AI SDK that provides reliable message streaming with automatic reconnection to interrupted streams. This transport is a drop-in replacement for the default AI SDK transport, enabling seamless recovery from network issues, page refreshes, or Vercel Function timeouts.
 
 <Callout>
@@ -250,9 +254,48 @@ export default function ChatWithCustomConfig() {
 }
 ```
 
+## Mid-part resumes
+
+A workflow stream is a flat sequence of chunks, but the AI SDK's UI protocol groups chunks into logical parts: a `text-start` opens a text part that subsequent `text-delta`s extend and a `text-end` closes, and the same shape applies to `reasoning-*` and `tool-input-*`. The AI SDK client enforces that grammar — a `reasoning-delta` whose `reasoning-start` was never seen throws and breaks the chat.
+
+A non-zero `startIndex` (in particular a negative `initialStartIndex`) resolves to a chunk offset with no awareness of those part boundaries, so it can land in the middle of an open part. When that happens, `WorkflowChatTransport` will **drop chunks that reference a part it didn't see a start for** and log a one-time warning. The chat keeps working, but any partial part overlapping the resume cursor is discarded. Tool calls are an exception: `tool-input-available` / `tool-input-error` chunks are self-contained (they carry the full input), so a tool call is recovered as soon as one of those chunks appears in the resumed window — only its streamed input deltas are lost.
+
+To preserve those partial parts, rewind to a step boundary on the server before returning the readable. `start-step` / `finish-step` chunks are the natural seams — no UI part is ever open across them. Sketch:
+
+{/*@skip-typecheck: incomplete code sample*/}
+
+```typescript title="app/api/chat/[id]/stream/route.ts"
+const run = getRun(id);
+const tailIndex = await run.getReadable().getTailIndex();
+
+let resolved = startIndex < 0
+  ? Math.max(0, tailIndex + 1 + startIndex)
+  : startIndex;
+
+if (startIndex !== 0) {
+  // Walk back from `resolved` to the most recent start-step (or chunk 0),
+  // capping the lookback so a single huge step can't trigger an unbounded scan.
+  const LOOKBACK = 200;
+  const probe = run.getReadable({ startIndex: Math.max(0, resolved - LOOKBACK) });
+  let i = Math.max(0, resolved - LOOKBACK);
+  let lastBoundary = i;
+  for await (const chunk of probe as unknown as AsyncIterable<{ type: string }>) {
+    if (i >= resolved) break;
+    if (chunk.type === "start-step") lastBoundary = i;
+    i++;
+  }
+  resolved = lastBoundary;
+}
+
+return createUIMessageStreamResponse({
+  stream: run.getReadable({ startIndex: resolved }),
+  headers: { "x-workflow-stream-tail-index": String(tailIndex) },
+});
+```
+
 ## See Also
 
-- [DurableAgent](/docs/api-reference/workflow-ai/durable-agent) - Building durable AI agents within workflows
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) - Building durable, resumable AI agents (replaces `DurableAgent`)
 - [AI SDK `useChat` Documentation](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) - Using `useChat` with custom transports
 - [Workflows and Steps](/docs/foundations/workflows-and-steps) - Understanding workflow fundamentals
 - ["flight-booking-app" Example](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) - An example application which uses `WorkflowChatTransport`

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

@@ -5,14 +5,22 @@ 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.
 
+When `experimental_minRetention` is set, this function continues to return the Hook after its workflow ends until retention ends. That Hook cannot be resumed. Use `getRun(hook.runId)` to inspect the finished run.
+
 <Callout type="warn">
 `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 +186,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";
 
@@ -164,6 +170,25 @@ const { stoppedCount } = await run.wakeUp({
 });
 ```
 
+### Cancel a Run
+
+Cancel a workflow run. You can pass an optional free-text `cancelReason` (up to 512 characters) that is recorded on the run's cancellation event and shown in the run detail view:
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+export async function POST(req: Request) {
+  const { runId } = await req.json();
+  const run = getRun(runId);
+
+  await run.cancel({ cancelReason: "Superseded by a newer submission" }); // [!code highlight]
+
+  return Response.json({ cancelled: true });
+}
+```
+
+The options object is optional — `await run.cancel()` cancels the run without recording a reason.
+
 ## Related Functions
 
 - [`start()`](/docs/api-reference/workflow-api/start) - Start a new workflow and get its run ID.

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,12 +7,15 @@ 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.
 
 It creates a `hook_received` event and re-triggers the workflow to continue execution.
 
+A Hook kept by `experimental_minRetention` after its workflow ends cannot be resumed. `resumeHook()` throws `HookNotFoundError` in that case.
+
 <Callout type="warn">
 `resumeHook` is a runtime function that must be called from outside a workflow function.
 </Callout>
@@ -47,7 +50,7 @@ showSections={["parameters"]}
 
 ### Returns
 
-Returns a `Promise<Hook>` that resolves to:
+Returns a `Promise<ResumedHook>` — a `Hook` extended with an optional `resilientResume` flag. Resolving means the resume was accepted and the workflow will continue, whether the `hook_received` event was written directly or, on the parallel fast path, delivered through the workflow queue for the runtime to materialize (see the [lazy hook resume changelog](/docs/changelog/resilient-resume)). `resilientResume` is `true` only when the direct event write failed transiently and the resume was recovered through the queue; on the happy path it is absent. The resolved hook:
 
 <TSDoc
 definition={`
@@ -155,8 +158,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/resume-webhook.mdx

@@ -50,11 +50,13 @@ showSections={['parameters']}
 
 ### Returns
 
-Returns a `Promise<Response>` that resolves to:
+Returns a `Promise<Response>` that resolves to one of:
 
-- `Response`: The HTTP response from the workflow's `respondWith()` call
+- A `202 Accepted` response when the webhook was created in the default mode (no `respondWith` option).
+- The exact `Response` object configured via `createWebhook({ respondWith: new Response(...) })`.
+- The workflow's manual `Response` when the webhook was created with `createWebhook({ respondWith: "manual" })` and a step calls `request.respondWith(response)`.
 
-Throws an error if the webhook token is not found or invalid.
+Throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active webhook.
 
 ## Usage Note
 
@@ -81,7 +83,7 @@ export async function POST(request: Request) {
 
   try {
     const response = await resumeWebhook(token, request); // [!code highlight]
-    return response; // Returns the workflow's custom response
+    return response; // 202 Accepted, a configured static Response, or a manual workflow response
   } catch (error) {
     return new Response("Webhook not found", { status: 404 });
   }

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,14 +52,17 @@ 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 [`setAttributes`](/docs/api-reference/workflow/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).
+If `start()` throws `'start' received an invalid workflow function. Ensure the Workflow SDK 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).
 </Callout>
 
 ## Examples
@@ -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">
@@ -105,3 +113,28 @@ When using `deploymentId: "latest"`, the workflow run will execute on a potentia
 - **Workflow identity**: The workflow ID is derived from the function name and file path. If the latest deployment has renamed the workflow function or moved it to a different directory, the workflow ID will no longer match and the run will fail to start.
 - **Input and output compatibility**: The arguments passed to `start()` are serialized by the calling deployment but deserialized by the target deployment. Similarly, the workflow's return value is serialized by the target deployment but deserialized by the caller. If the workflow's expected arguments or return type have changed (e.g. added required fields, removed fields, or changed types), the run may fail or behave unexpectedly. Ensure that input and output schemas remain backward-compatible across deployments.
 </Callout>
+
+### Inside a Workflow Function
+
+`start()` can be called directly from a workflow function to spawn a child run. It is step-backed, so the spawn records a deterministic step boundary in the parent's event log.
+
+```typescript
+import { start } from "workflow/api";
+import { childWorkflow } from "./workflows/child";
+
+export async function parentWorkflow(value: number) {
+  "use workflow";
+
+  const childRun = await start(childWorkflow, [value]); // [!code highlight]
+  const result = await childRun.returnValue; // [!code highlight]
+  return { childRunId: childRun.runId, result };
+}
+```
+
+<Callout type="info">
+The returned `Run` object is fully functional inside a workflow. Each property access or method call (`.status`, `.returnValue`, `.cancel()`) executes as a separate step. See [Workflow Composition](/cookbook/common-patterns/workflow-composition) for choosing between spawning a child run and awaiting a workflow function directly.
+</Callout>
+
+<Callout type="warn">
+`returnValue` polls the child run every second and holds the polling step's worker slot open for as long as the child takes to finish. For long-running children, spawn without awaiting `returnValue` and have the child resume a [hook](/docs/foundations/hooks) when it completes — see the [`startAndWait()` pattern](/cookbook/advanced/child-workflows).
+</Callout>

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