workflow 5.0.0-beta.9 → 5.0.0

package/docs/foundations/streaming.mdx

@@ -1,8 +1,8 @@
 ---
 title: Streaming
-description: Stream data in real-time to clients for progress updates and incremental content delivery.
+description: Stream data in real time to clients for progress updates and incremental content delivery.
 type: conceptual
-summary: Stream real-time data to clients without waiting for workflow completion.
+summary: Stream data to clients in real time without waiting for workflow completion.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
@@ -10,9 +10,9 @@ related:
   - /docs/ai/resumable-streams
 ---
 
-Workflows can stream data in real-time to clients without waiting for the entire workflow to complete. This enables progress updates, AI-generated content, log messages, and other incremental data to be delivered as workflows execute.
+Workflows can stream data to clients in real time without waiting for the entire workflow to complete. Clients can receive progress updates, AI-generated content, log messages, and other incremental data as workflows execute.
 
-## Getting Started with `getWritable()`
+## Getting started with `getWritable()`
 
 Every workflow run has a default writable stream that steps can write to using [`getWritable()`](/docs/api-reference/workflow/get-writable). Data written to this stream becomes immediately available to clients consuming the workflow's output.
 
@@ -38,7 +38,7 @@ export async function simpleStreamingWorkflow() {
 }
 ```
 
-### Consuming the Stream
+### Consuming the stream
 
 Use the `Run` object's `readable` property to consume the stream from your API route:
 
@@ -58,7 +58,31 @@ export async function POST() {
 
 When a client makes a request to this endpoint, they'll receive each message as it's written, without waiting for the workflow to complete.
 
-### Resuming Streams from a Specific Point
+### Avoiding function timeouts after client disconnects
+
+On Vercel, `run.readable` and `run.getReadable()` reconnect to Workflow's stream storage while the workflow is still running. By default, a client disconnect does not terminate the Vercel Function serving the stream. If a user closes the page or stops the request, the function can therefore keep reconnecting until it reaches its maximum duration and fails with `FUNCTION_INVOCATION_TIMEOUT`.
+
+For streaming routes using the Node.js runtime, opt in to [request cancellation](https://vercel.com/docs/functions/functions-api-reference#enable-cancellation) in `vercel.json`:
+
+```json filename="vercel.json"
+{
+  "functions": {
+    "app/api/stream/route.ts": {
+      "supportsCancellation": true
+    }
+  }
+}
+```
+
+Replace the function path with the path or glob for your streaming route. When the downstream client disconnects, Vercel terminates the matching function invocation instead of leaving its stream reader running. The workflow run and its durable stream continue independently, so the client can reconnect through another route invocation later.
+
+<Callout type="warn">
+Cancellation applies to every function matching the configured path or glob, even if the route does not listen to `request.signal`. Any other work in that invocation which is not wrapped in [`waitUntil`](https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package#waituntil) or [`after`](https://nextjs.org/docs/app/api-reference/functions/after) can be lost. Only enable it for routes that are safe to terminate when their client disconnects.
+</Callout>
+
+This setting prevents abandoned stream readers from consuming the rest of a function invocation. It does not extend the function's maximum duration. An actively connected streaming response can still reach the configured limit, at which point the client should reconnect to the durable stream.
+
+### Resuming streams from a specific point
 
 Use `run.getReadable({ startIndex })` to resume a stream from a specific position. This is useful for reconnecting after timeouts or network interruptions:
 
@@ -85,7 +109,7 @@ export async function GET(
 }
 ```
 
-This allows clients to reconnect and continue receiving data from where they left off, rather than restarting from the beginning.
+Clients can reconnect and continue receiving data from where they left off instead of restarting from the beginning.
 
 `startIndex` also supports **negative values** to read relative to the end of the stream. For example, `startIndex: -5` starts 5 chunks before the current end. This is useful when you want to show the most recent output without reading the entire stream history.
 
@@ -103,31 +127,32 @@ If the absolute value exceeds the total number of chunks, reading starts from th
 Because streams are live and continue receiving chunks, negative `startIndex` values resolve to different absolute positions on each call. Accurate pagination over a live stream requires cursor-based access, which is not yet supported. Keep this in mind when building clients that paginate over stream data.
 </Callout>
 
-## Streams as Data Types
+## Streams as data types
 
-[`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) are standard Web Streams API types that Workflow SDK makes serializable. These are not custom types - they follow the web standard - but Workflow SDK adds the ability to pass them between functions while maintaining their streaming capabilities.
+[`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) are standard Web Streams API types that Workflow SDK makes serializable. Workflow SDK lets you pass these standard types between functions while maintaining their streaming capabilities.
 
 Unlike regular values that are fully serialized to the [event log](/docs/how-it-works/event-sourcing), streams maintain their streaming capabilities when passed between functions.
 
 **Key properties:**
+
 - Stream references can be passed between workflow and step functions
 - Stream data flows directly without being stored in the event log
 - Streams preserve their state across workflow suspension points
 
 <Callout type="info">
-**How Streams Persist Across Workflow Suspensions**
+**How streams persist across workflow suspensions**
 
-Streams in Workflow SDK are backed by persistent, resumable storage provided by the "world" implementation. This is what enables streams to maintain their state even when workflows suspend and resume:
+Persistent, resumable storage from the World implementation lets Workflow SDK streams maintain their state when workflows suspend and resume:
 
 - **Vercel deployments**: Streams are backed by a performant Redis-based stream
 - **Local development**: Stream chunks are stored in the filesystem
 </Callout>
 
-### Passing Streams as Arguments
+### Passing streams as arguments
 
-Since streams are serializable data types, you don't need to use the special [`getWritable()`](/docs/api-reference/workflow/get-writable). You can even wire your own streams through workflows, passing them as arguments from outside into steps.
+Because streams are serializable data types, you don't need to use [`getWritable()`](/docs/api-reference/workflow/get-writable). You can pass your own streams as arguments from outside a workflow into steps.
 
-Here's an example of passing a request body stream through a workflow to a step that processes it:
+The following example passes a request body stream through a workflow to a step that processes it:
 
 ```typescript title="app/api/upload/route.ts" lineNumbers
 import { start } from "workflow/api";
@@ -167,15 +192,15 @@ async function processInputStream(input: ReadableStream<Uint8Array>) {
 }
 ```
 
-## Important Limitation
+## Important limitation
 
 <Callout type="info">
-**Streams Cannot Be Used Directly in Workflow Context**
+**Streams cannot be used directly in workflow context**
 
 You cannot read from or write to streams directly within a workflow function. All stream operations must happen in step functions.
 </Callout>
 
-Workflow functions must be deterministic to support replay. Since streams bypass the [event log](/docs/how-it-works/event-sourcing) for performance, reading stream data in a workflow would break determinism - each replay could see different data. By requiring all stream operations to happen in steps, the framework ensures consistent behavior.
+Workflow functions must be deterministic to support replay. Streams bypass the [event log](/docs/how-it-works/event-sourcing) for performance, so reading stream data in a workflow would break determinism because each replay could see different data. Requiring all stream operations to happen in steps ensures consistent behavior.
 
 For more on determinism and replay, see [Workflows and Steps](/docs/foundations/workflows-and-steps).
 
@@ -214,7 +239,7 @@ async function writeToStream(data: string) {
 }
 ```
 
-## Namespaced Streams
+## Namespaced streams
 
 Use `getWritable({ namespace: 'name' })` to create multiple independent streams for different types of data. This is useful when you want to separate logs, metrics, data outputs, or other distinct channels.
 
@@ -264,7 +289,7 @@ export async function multiStreamWorkflow() {
 }
 ```
 
-### Consuming Namespaced Streams
+### Consuming namespaced streams
 
 Use `run.getReadable({ namespace: 'name' })` to access specific streams:
 
@@ -289,9 +314,37 @@ export async function POST(request: Request) {
 }
 ```
 
-## Common Patterns
+## Writing to another run's stream
+
+`getRun(runId).getWritable()` appends to a stream owned by another run. This lets short-lived runs contribute to a long-lived holder run's stream using only its ID.
 
-### Progress Updates for Long-Running Tasks
+```typescript title="workflows/turn.ts" lineNumbers
+import { getRun } from "workflow/api";
+
+type SessionEvent = { turn: number; text: string };
+
+async function runTurn(holderRunId: string, turn: number) {
+  "use step";
+
+  const writable = getRun(holderRunId).getWritable<SessionEvent>(); // [!code highlight]
+  const writer = writable.getWriter();
+
+  await writer.write({ turn, text: "done" });
+  writer.releaseLock(); // [!code highlight]
+}
+```
+
+Pass `{ namespace: "name" }` to target a [namespaced stream](#namespaced-streams). The writable can also be forwarded through `start()` and into steps.
+
+<Callout type="warn">
+Contributors should call `releaseLock()`, which flushes pending writes. Calling `close()` closes the shared stream for every writer.
+</Callout>
+
+The API grants append access, not read access or additional authorization. The owning run controls the stream's lifecycle, and writes to an unknown run fail.
+
+## Common patterns
+
+### Progress updates for long-running tasks
 
 Send incremental progress updates to keep users informed during lengthy workflows:
 
@@ -345,29 +398,19 @@ export async function batchProcessingWorkflow(items: string[]) {
 }
 ```
 
-### Streaming AI Responses with `DurableAgent`
+### Streaming AI responses with `WorkflowAgent`
 
-Stream AI-generated content using [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) from `@workflow/ai`. Tools can also emit progress updates to the same stream using [data chunks](https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data#streaming-custom-data) with the [`UIMessageChunk`](https://ai-sdk.dev/docs/ai-sdk-ui/stream-protocol) type from the AI SDK:
+Stream AI-generated content using AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) from `@ai-sdk/workflow`. The agent writes `ModelCallStreamPart` chunks to the workflow stream, and route handlers convert them to UI message chunks with `createModelCallToUIChunkTransform()` before returning the response:
 
 ```typescript title="workflows/ai-assistant.ts" lineNumbers
-import { DurableAgent } from "@workflow/ai/agent";
+import { WorkflowAgent, type ModelCallStreamPart } from "@ai-sdk/workflow";
+import { tool } from "ai";
 import { getWritable } from "workflow";
 import { z } from "zod";
-import type { UIMessageChunk } from "ai";
 
 async function searchFlights({ query }: { query: string }) {
   "use step";
 
-  // Tools can emit progress updates to the stream
-  const writable = getWritable<UIMessageChunk>(); // [!code highlight]
-  const writer = writable.getWriter(); // [!code highlight]
-  await writer.write({ // [!code highlight]
-    type: "data-progress", // [!code highlight]
-    data: { message: `Searching flights for ${query}...` }, // [!code highlight]
-    transient: true, // [!code highlight]
-  }); // [!code highlight]
-  writer.releaseLock(); // [!code highlight]
-
   // ... search logic ...
   return { flights: [/* results */] };
 }
@@ -375,27 +418,28 @@ async function searchFlights({ query }: { query: string }) {
 export async function aiAssistantWorkflow(userMessage: string) {
   "use workflow";
 
-  const agent = new DurableAgent({
-    model: "anthropic/claude-haiku-4.5",
-    system: "You are a helpful flight assistant.",
+  const agent = new WorkflowAgent({
+    model: "spacexai/grok-4.6",
+    instructions: "You are a helpful flight assistant.",
     tools: {
-      searchFlights: {
+      searchFlights: tool({
         description: "Search for flights",
         inputSchema: z.object({ query: z.string() }),
         execute: searchFlights,
-      },
+      }),
     },
   });
 
   // LLM response will be streamed to the run's writable
   await agent.stream({
     messages: [{ role: "user", content: userMessage }],
-    writable: getWritable<UIMessageChunk>(), // [!code highlight]
+    writable: getWritable<ModelCallStreamPart>(), // [!code highlight]
   });
 }
 ```
 
 ```typescript title="app/api/ai-assistant/route.ts" lineNumbers
+import { createModelCallToUIChunkTransform } from "@ai-sdk/workflow";
 import { createUIMessageStreamResponse } from "ai";
 import { start } from "workflow/api";
 import { aiAssistantWorkflow } from "./workflows/ai";
@@ -406,16 +450,16 @@ export async function POST(request: Request) {
   const run = await start(aiAssistantWorkflow, [message]);
 
   return createUIMessageStreamResponse({
-    stream: run.readable,
+    stream: run.readable.pipeThrough(createModelCallToUIChunkTransform()), // [!code highlight]
   });
 }
 ```
 
 <Callout type="info">
-For a complete implementation, see the [flight booking example](https://github.com/vercel/workflow-examples/tree/main/flight-booking-app) which demonstrates streaming AI responses with tool progress updates.
+For the full agent API and migration notes, see the [`WorkflowAgent` documentation](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent).
 </Callout>
 
-### Streaming Between Steps
+### Streaming between steps
 
 One step produces a stream and another step consumes it:
 
@@ -456,7 +500,7 @@ async function consumeData(readable: ReadableStream<number>) {
 }
 ```
 
-### Processing Large Files Without Memory Overhead
+### Processing large files without memory overhead
 
 Process large files by streaming chunks through transformation steps:
 
@@ -497,7 +541,11 @@ async function uploadResult(stream: ReadableStream<Uint8Array>) {
 }
 ```
 
-## Best Practices
+## Best practices
+
+**Batching and first-chunk latency:**
+
+Writes are flushed immediately by default. The leading chunk of an idle stream dispatches as soon as it is written, and chunks arriving while a flush is in flight coalesce into the next batch. If you write bursts of many tiny chunks and prefer fewer round trips over first-chunk latency, set a group-commit window with the World's `streamFlushIntervalMs` option or the `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` environment variable. See [Worlds configuration](/docs/configuration/worlds#streamflushintervalms).
 
 **Release locks properly:**
 
@@ -515,7 +563,7 @@ Stream locks acquired in a step only apply within that step, not across other st
 </Callout>
 
 <Callout type="warn">
-If a lock is not released, the step function's HTTP request cannot terminate. Even though the step returns and the workflow continues, the underlying request will remain active until it times out—wasting compute resources unnecessarily.
+If a lock is not released, the invocation that ran the step cannot terminate. Even though the step returns and the workflow continues, the underlying request remains active until it times out and wastes compute resources.
 </Callout>
 
 **Close streams when done:**
@@ -541,7 +589,7 @@ const writer = writable.getWriter();
 await writer.write({ /* typed data */ });
 ```
 
-## Stream Failures
+## Stream failures
 
 When a step returns a stream, the step is considered successful once it returns, even if the stream later encounters an error. The workflow won't automatically retry the step. The consumer of the stream must handle errors gracefully. For more on retry behavior, see [Errors and Retries](/docs/foundations/errors-and-retries).
 
@@ -584,17 +632,17 @@ export async function streamErrorWorkflow() {
 ```
 
 <Callout type="info">
-Stream errors don't trigger automatic retries for the producer step. Design your stream consumers to handle errors appropriately. Since the stream is already in an errored state, retrying the consumer won't help - use `FatalError` to fail the workflow immediately.
+Stream errors don't trigger automatic retries for the producer step. Design your stream consumers to handle errors. Because the stream is already in an errored state, retrying the consumer won't help. Use `FatalError` to fail the workflow immediately.
 </Callout>
 
-## Related Documentation
-
-- [`getWritable()` API Reference](/docs/api-reference/workflow/get-writable) - Get the workflow's writable stream
-- [`sleep()` API Reference](/docs/api-reference/workflow/sleep) - Pause workflow execution for a duration
-- [`start()` API Reference](/docs/api-reference/workflow-api/start) - Start workflows and access the `Run` object
-- [`getRun()` API Reference](/docs/api-reference/workflow-api/get-run) - Retrieve runs and their streams later
-- [world.streams](/docs/api-reference/workflow-api/world/streams) - Low-level stream read/write/close via World SDK
-- [DurableAgent](/docs/api-reference/workflow-ai/durable-agent) - AI agents with built-in streaming support
-- [Errors and Retries](/docs/foundations/errors-and-retries) - Understanding error handling and retry behavior
-- [Serialization](/docs/foundations/serialization) - Understanding what data types can be passed in workflows
-- [Workflows and Steps](/docs/foundations/workflows-and-steps) - Core concepts of workflow execution
+## Related documentation
+
+- [`getWritable()` API reference](/docs/api-reference/workflow/get-writable): Get the workflow's writable stream
+- [`sleep()` API reference](/docs/api-reference/workflow/sleep): Pause workflow execution for a duration
+- [`start()` API reference](/docs/api-reference/workflow-api/start): Start workflows and access the `Run` object
+- [`getRun()` API reference](/docs/api-reference/workflow-api/get-run): Retrieve runs and their streams later
+- [`world.streams`](/docs/api-reference/workflow-runtime/world/streams): Use low-level stream read, write, and close operations through the World SDK
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent): Build AI agents with durable, resumable streaming support
+- [Errors and retries](/docs/foundations/errors-and-retries): Understand error handling and retry behavior
+- [Serialization](/docs/foundations/serialization): Understand which data types you can pass in workflows
+- [Workflows and steps](/docs/foundations/workflows-and-steps): Learn the core concepts of workflow execution

package/docs/foundations/versioning.mdx

@@ -75,7 +75,7 @@ Sometimes you deploy because the old code had a bug. The safest fix is usually e
 3. Cancel the old runs if they are still running.
 4. Rerun them on the latest deployment with the same inputs.
 
-This keeps the version boundary visible. The old run ends as cancelled or failed, and the replacement run starts fresh on the fixed deployment. This is a good fit for one-off, ad-hoc upgrades where you explicitly opt in to moving affected runs onto a new version.
+This keeps the version boundary visible. The old run ends as canceled or failed, and the replacement run starts fresh on the fixed deployment. This is a good fit for one-off, ad-hoc upgrades where you explicitly opt in to moving affected runs onto a new version.
 
 ```bash
 # Inspect affected runs and copy the exact workflowName value.
@@ -94,7 +94,7 @@ npx workflow cancel \
   --backend vercel
 ```
 
-The `--workflowName` filter expects the generated workflow ID, not only the exported function's short name. Use the `workflowName` value from `workflow inspect runs`, and use [`parseWorkflowName()`](/docs/api-reference/workflow-api/world/observability) when you need display-friendly names.
+The `--workflowName` filter expects the generated workflow ID, not only the exported function's short name. Use the `workflowName` value from `workflow inspect runs`, and use [`parseWorkflowName()`](/docs/api-reference/workflow-observability/parse-workflow-name) when you need display-friendly names.
 
 In the [observability UI](/docs/observability), use **Rerun on latest** to enqueue the workflow again with the same inputs against the latest deployment.
 
@@ -121,9 +121,9 @@ export async function POST(request: Request) {
 
 ## Self upgrading workflows
 
-Some workflows are expected to run for a very long time. Scheduled loops, recurring jobs, agents, and chat sessions often should not stay on one deployment forever.
+Some workflows are expected to run for long periods. Scheduled loops, recurring jobs, agents, and chat sessions often should not stay on one deployment forever.
 
-Model those as a sequence of runs. Each run does a bounded piece of work, then starts the next run on the latest deployment and exits. This is similar to `continueAsNew` in other durable execution systems, but in Workflow SDK it is just [explicit recursion through `start()`](/cookbook/common-patterns/workflow-composition).
+Model those as a sequence of runs. Each run does a bounded piece of work, then starts the next run on the latest deployment and exits. This is similar to `continueAsNew` in other durable execution systems, but Workflow SDK uses [explicit recursion through `start()`](/cookbook/common-patterns/workflow-composition).
 
 ```typescript title="workflows/daily-digest.ts" lineNumbers
 import { sleep } from "workflow";

package/docs/foundations/workflows-and-steps.mdx

@@ -14,18 +14,18 @@ import { File, Folder, Files } from "fumadocs-ui/components/files";
 
 Workflows (a.k.a. *durable functions*) are a programming model for building long-running, stateful application logic that can maintain its execution state across restarts, failures, or user events. Unlike traditional serverless functions that lose all state when they terminate, workflows persist their progress and can resume exactly where they left off.
 
-Moreover, workflows let you easily model complex multi-step processes in simple, elegant code. To do this, we introduce two fundamental entities:
+Workflows let you model complex multi-step processes in code. To do this, we introduce two fundamental entities:
 
 1. **Workflow Functions**: Functions that orchestrate/organize steps
 2. **Step Functions**: Functions that carry out the actual work
 
-## Workflow Functions
+## Workflow functions
 
 *Directive: `"use workflow"`*
 
 Workflow functions define the entrypoint of a workflow and organize how step functions are called. This type of function does not have access to the Node.js runtime, and usable `npm` packages are limited.
 
-Although this may seem limiting initially, this feature is important in order to suspend and accurately resume execution of workflows.
+Although this may seem limiting initially, this feature is required to suspend and accurately resume workflow execution.
 
 It helps to think of the workflow function less like a full JavaScript runtime and more like "stitching together" various steps using conditionals, loops, try/catch handlers, `Promise.all`, and other language primitives.
 
@@ -51,7 +51,7 @@ Determinism in the workflow is required to resume the workflow from a suspension
 
 The sandboxed environment that workflows run in already ensures determinism. For instance, `Math.random` and `Date` constructors are fixed in workflow runs, so you are safe to use them, and the framework ensures that the values don't change across replays.
 
-## Step Functions
+## Step functions
 
 *Directive: `"use step"`*
 
@@ -115,10 +115,10 @@ export async function POST() {
 ```
 
 <Callout type="info">
-Keep in mind that calling a step function outside of a workflow function will not have retry semantics, nor will it be observable. Additionally, certain workflow-specific functions like [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata) will throw an error when used inside a step that's called outside a workflow.
+Calling a step function outside a workflow function provides neither retry semantics nor observability. Additionally, certain workflow-specific functions like [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata) will throw an error when used inside a step that's called outside a workflow.
 </Callout>
 
-### Suspension and Resumption
+### Suspension and resumption
 
 Workflow functions have the ability to automatically suspend while they wait on asynchronous work. While suspended, the workflow's state is stored via the [event log](/docs/how-it-works/event-sourcing) and no compute resources are used until the workflow resumes execution.
 
@@ -126,7 +126,7 @@ Workflow functions have the ability to automatically suspend while they wait on
 
 There are multiple ways a workflow can suspend:
 
-- Waiting on a step function: the workflow yields while the step runs in the step runtime.
+- Waiting on a step function: the workflow yields while the step body runs. The step usually executes inline in the same invocation; when the invocation's inline budget is exhausted or its timeout approaches, the step is handed to the queue and the workflow resumes in a later invocation.
 - Using `sleep()` to pause for some fixed duration.
 - Awaiting on a promise returned by [`createWebhook()`](/docs/api-reference/workflow/create-webhook), which resumes the workflow when an external system passes data into the workflow.
 
@@ -150,9 +150,9 @@ export async function documentReviewProcess(userId: string) {
 }
 ```
 
-## Writing Workflows
+## Writing workflows
 
-### Basic Structure
+### Basic structure
 
 The simplest workflow consists of a workflow function and one or more step functions.
 

package/docs/getting-started/astro.mdx

@@ -9,16 +9,20 @@ related:
   - /docs/foundations/workflows-and-steps
 ---
 
-This guide will walk through setting up your first workflow in an Astro app. Along the way, you'll learn more about the concepts that are fundamental to using the Workflow SDK in your own projects.
+<CopyPrompt
+  text="In this Astro app, run `npm i workflow`. In `astro.config.mjs`, import `workflow` from `workflow/astro` and add `integrations: [workflow()]`. Add the TypeScript plugin `{ &quot;name&quot;: &quot;workflow&quot; }` to `tsconfig.json` if TypeScript is used. Create `src/workflows/user-signup.ts` exporting `handleUserSignup(email)` with `&quot;use workflow&quot;`, `sleep` from `workflow`, and `&quot;use step&quot;` helpers. Add `src/pages/api/signup.ts` exporting `POST: APIRoute` that reads `{ email }`, calls `start(handleUserSignup, [email])` from `workflow/api`, returns `Response.json`, and sets `prerender = false`. Run `npm run dev`, call `curl -X POST --json '{&quot;email&quot;:&quot;hello@example.com&quot;}' http://localhost:4321/api/signup`, and inspect with `npx workflow inspect runs`."
+/>
+
+Set up your first durable workflow in an Astro app and learn the core Workflow SDK concepts.
 
 ---
 
 <Steps>
 
 <Step>
-## Create Your Astro Project
+## Create your Astro project
 
-Start by creating a new Astro project. This command will create a new directory named `my-workflow-app` and setup a minimal Astro project inside it.
+Create an Astro project in a new directory named `my-workflow-app`:
 
 ```bash
 npm create astro@latest my-workflow-app -- --template minimal --install --yes
@@ -55,16 +59,16 @@ export default defineConfig({
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Set to `false` for smaller function bundles (useful for staying under the Vercel 250MB function size limit) at the cost of stack traces pointing at generated code. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+| `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, which helps stay under the Vercel 250 MB function size limit). Set it explicitly, or use the `WORKFLOW_SOURCEMAP` environment variable, to override in either environment. |
 
 <Accordion type="single" collapsible>
   <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
     <AccordionTrigger className="text-sm">
-      ### Setup IntelliSense for TypeScript (Optional)
+      ### Set up IntelliSense for TypeScript (optional)
     </AccordionTrigger>
     <AccordionContent className="[&_p]:my-2">
 
-To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
+To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`:
 
 ```json title="tsconfig.json" lineNumbers
 {
@@ -87,7 +91,7 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 
 <Step>
 
-## Create Your First Workflow
+## Create your first workflow
 
 Create a new file for our first workflow:
 
@@ -108,14 +112,14 @@ export async function handleUserSignup(email: string) {
 
 ```
 
-We'll fill in those functions next, but let's take a look at this code:
+We'll fill in those functions next, but first review this code:
 
 * We define a **workflow** function with the directive `"use workflow"`. Think of the workflow function as the _orchestrator_ of individual **steps**.
 * The Workflow SDK's `sleep` function allows us to suspend execution of the workflow without using up any resources. A sleep can be a few seconds, hours, days, or even months long.
 
-## Create Your Workflow Steps
+## Create your workflow steps
 
-Let's now define those missing functions.
+Define the missing functions.
 
 ```typescript title="src/workflows/user-signup.ts" lineNumbers
 import { FatalError } from "workflow"
@@ -156,7 +160,7 @@ async function sendOnboardingEmail(user: { id: string; email: string}) {
 
 Taking a look at this code:
 
-* Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+* Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 * If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 * Steps can throw a `FatalError` if an error is intentional and should not be retried.
 
@@ -168,7 +172,7 @@ We'll dive deeper into workflows, steps, and other ways to suspend or handle eve
 
 <Step>
 
-## Create Your Route Handler
+## Create your route handler
 
 To invoke your new workflow, we'll have to add your workflow to a `POST` API route handler, `src/pages/api/signup.ts` with the following code:
 
@@ -200,7 +204,7 @@ Workflows can be triggered from API routes or any server-side code.
 
 </Steps>
 
-## Run in Development
+## Run in development
 
 To start your development server, run the following command in your terminal in the Vite root directory:
 
@@ -227,9 +231,9 @@ npx workflow inspect runs
 
 ---
 
-## Deploying to Production
+## Deploying to production
 
-Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
+Workflow SDK apps currently work best when deployed to [Vercel](https://vercel.com/home) and need no special configuration.
 
 <FluidComputeCallout />
 
@@ -247,8 +251,8 @@ Additionally, check the [Deploying](/docs/deploying) section to learn how your w
 
 If you see this error:
 
-```
-'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+```text
+'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.
 ```
 
 Check both of these first:
@@ -258,7 +262,7 @@ Check both of these first:
 
 See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
 
-## Next Steps
+## Next steps
 
 * Learn more about the [Foundations](/docs/foundations).
 * Check [Errors](/docs/errors) if you encounter issues.