workflow 4.2.0-beta.73 → 4.2.0-beta.75

package/docs/api-reference/workflow-api/world/steps.mdx

@@ -0,0 +1,216 @@
+---
+title: world.steps
+description: List and inspect workflow step execution data with input/output hydration.
+type: reference
+summary: "Methods: get(), list(). Query step metadata, hydrate serialized I/O, calculate durations."
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+related:
+  - /docs/api-reference/workflow-api/world/runs
+  - /docs/api-reference/workflow-api/world/observability
+keywords:
+  - world.steps
+  - world.steps.get
+  - world.steps.list
+  - Step
+  - step input output
+  - hydrateResourceIO
+  - step duration
+  - resolveData
+  - parseStepName
+  - devalue serialization
+---
+
+The `world.steps` interface provides access to individual step execution data within workflow runs. Use it to list steps, inspect their input/output, and build progress dashboards.
+
+## Import
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const steps = world.steps; // [!code highlight]
+```
+
+## Methods
+
+### get()
+
+Retrieve a single step by run ID and step ID.
+
+```typescript lineNumbers
+const step = await world.steps.get(runId, stepId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `stepId` | `string` | The step ID |
+| `params.resolveData` | `'all' \| 'none'` | Whether to hydrate input/output data. Default: `'all'` |
+
+**Returns:** `Step`
+
+### list()
+
+List steps with cursor pagination.
+
+```typescript lineNumbers
+const result = await world.steps.list({ // [!code highlight]
+  runId,
+  pagination: { cursor },
+}); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.runId` | `string` | Filter steps by run ID |
+| `params.pagination.cursor` | `string` | Cursor for the next page |
+| `params.resolveData` | `'all' \| 'none'` | Whether to hydrate input/output data |
+
+**Returns:** `{ data: Step[], cursor?: string }`
+
+## Types
+
+### Step
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `runId` | `string` | Parent workflow run ID |
+| `stepId` | `string` | Unique step identifier |
+| `stepName` | `string` | Machine-readable step identifier |
+| `status` | `string` | Step status: `'running'`, `'completed'`, `'failed'` |
+| `input` | `any` | Step input data (when `resolveData: 'all'`) |
+| `output` | `any` | Step output data (when `resolveData: 'all'`) |
+| `error` | `any` | Error data if the step failed |
+| `attempt` | `number` | Current retry attempt number |
+| `startedAt` | `string` | ISO timestamp when the step started |
+| `completedAt` | `string \| null` | ISO timestamp when the step completed |
+| `retryAfter` | `string \| null` | ISO timestamp for next retry attempt |
+
+<Callout type="info">
+  Step I/O is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Use `hydrateResourceIO()` from `workflow/observability` to deserialize it for display. See [Observability Utilities](/docs/api-reference/workflow-api/world/observability).
+</Callout>
+
+## Examples
+
+### List Steps for a Run without Data
+
+Use `resolveData: 'none'` to efficiently get step metadata for progress dashboards:
+
+```typescript lineNumbers
+// app/api/workflow-steps/route.ts
+import { getWorld } from "workflow/runtime";
+import { parseStepName } from "workflow/observability"; // [!code highlight]
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const runId = url.searchParams.get("runId");
+
+  if (!runId) {
+    return Response.json({ error: "runId required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const steps = await world.steps.list({ // [!code highlight]
+    runId,
+    resolveData: "none", // Skip I/O for performance // [!code highlight]
+  }); // [!code highlight]
+
+  const progress = steps.data.map((step) => {
+    const parsed = parseStepName(step.stepName); // [!code highlight]
+    return {
+      stepId: step.stepId,
+      displayName: parsed?.shortName ?? step.stepName, // [!code highlight]
+      module: parsed?.moduleSpecifier,
+      status: step.status,
+      startedAt: step.startedAt,
+      completedAt: step.completedAt,
+    };
+  });
+
+  return Response.json({ progress, cursor: steps.cursor });
+}
+```
+
+### Get Step with Hydrated Input and Output Data
+
+Retrieve a step with its full serialized data and hydrate it for display:
+
+```typescript lineNumbers
+// app/api/workflow-steps/[stepId]/route.ts
+import { getWorld } from "workflow/runtime";
+import { parseStepName } from "workflow/observability";
+import { // [!code highlight]
+  hydrateResourceIO, // [!code highlight]
+  observabilityRevivers, // [!code highlight]
+} from "workflow/observability"; // [!code highlight]
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const runId = url.searchParams.get("runId");
+  const stepId = url.searchParams.get("stepId");
+
+  if (!runId || !stepId) {
+    return Response.json({ error: "runId and stepId required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const step = await world.steps.get(runId, stepId); // [!code highlight]
+
+  const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+  const parsed = parseStepName(step.stepName);
+
+  return Response.json({
+    stepId: hydrated.stepId,
+    displayName: parsed?.shortName ?? step.stepName,
+    status: hydrated.status,
+    attempt: hydrated.attempt,
+    input: hydrated.input, // [!code highlight]
+    output: hydrated.output, // [!code highlight]
+  });
+}
+```
+
+### Calculate Step Duration from Timestamps
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const steps = await world.steps.list({ runId });
+
+for (const step of steps.data) {
+  if (step.completedAt) {
+    const start = new Date(step.startedAt).getTime();
+    const end = new Date(step.completedAt).getTime();
+    const durationMs = end - start; // [!code highlight]
+    console.log(`${step.stepName}: ${durationMs}ms`);
+  }
+}
+```
+
+### Parse Step Display Name from Machine-Readable ID
+
+The `stepName` field contains a machine-readable identifier like `step//./src/workflows/order//processPayment`. Use `parseStepName()` to extract display-friendly names:
+
+```typescript lineNumbers
+import { parseStepName } from "workflow/observability"; // [!code highlight]
+
+const parsed = parseStepName(step.stepName); // [!code highlight]
+// parsed.shortName → "processPayment"
+// parsed.moduleSpecifier → "./src/workflows/order"
+```
+
+<Callout type="warn">
+  The `stepName` field is a machine-readable identifier, not a display name. Always use `parseStepName()` from `workflow/observability` to extract the `shortName` for UI display.
+</Callout>
+
+## Related
+
+- [world.runs](/docs/api-reference/workflow-api/world/runs) — List and inspect workflow runs
+- [Observability Utilities](/docs/api-reference/workflow-api/world/observability) — Hydrate step I/O and parse display names
+- [Workflows and Steps](/docs/foundations/workflows-and-steps) — Core concepts for steps

package/docs/api-reference/workflow-api/world/streams.mdx

@@ -0,0 +1,152 @@
+---
+title: Streams
+description: Read, write, and manage real-time data streams for workflow runs.
+type: reference
+summary: "Methods: writeToStream(), readFromStream(), closeStream(), listStreamsByRunId(). Stream methods live directly on the world object."
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+related:
+  - /docs/foundations/streaming
+  - /docs/api-reference/workflow/get-writable
+keywords:
+  - writeToStream
+  - readFromStream
+  - closeStream
+  - listStreamsByRunId
+  - Streamer interface
+  - real-time streaming
+  - stream lifecycle
+---
+
+Stream methods live directly on the `world` object returned by `getWorld()`. Use them to write chunks, read streams, and manage stream lifecycle outside of the standard `getWritable()` pattern.
+
+<Callout type="info">
+  For most streaming use cases, use [`getWritable()`](/docs/api-reference/workflow/get-writable) inside steps. Direct stream methods are for advanced scenarios like building custom stream consumers or managing streams from outside a workflow.
+</Callout>
+
+## Import
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld(); // [!code highlight]
+// Stream methods are called directly on world — e.g. world.writeToStream()
+```
+
+## Methods
+
+### writeToStream()
+
+Write a data chunk to a named stream for a workflow run.
+
+```typescript lineNumbers
+await world.writeToStream("default", runId, chunk); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The stream name |
+| `runId` | `string` | The workflow run ID |
+| `chunk` | `string \| Uint8Array` | Data to write to the stream |
+
+### readFromStream()
+
+Read data from a named stream as a `ReadableStream`. Returns a live stream that waits for new chunks in real time.
+
+```typescript lineNumbers
+const readable = await world.readFromStream("default"); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The stream name |
+| `startIndex` | `number` | Optional starting index for partial reads. Negative values read from the tail (e.g. `-3` starts 3 chunks from the end). |
+
+**Returns:** `ReadableStream<Uint8Array>`
+
+### closeStream()
+
+Close a stream when done writing.
+
+```typescript lineNumbers
+await world.closeStream("default", runId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The stream name |
+| `runId` | `string` | The workflow run ID |
+
+### listStreamsByRunId()
+
+List all stream names associated with a workflow run.
+
+```typescript lineNumbers
+const streamNames = await world.listStreamsByRunId(runId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+
+**Returns:** `string[]` — Array of stream names
+
+## Examples
+
+### List All Streams for a Workflow Run
+
+```typescript lineNumbers
+// app/api/workflow-streams/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const runId = url.searchParams.get("runId");
+
+  if (!runId) {
+    return Response.json({ error: "runId required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const streamNames = await world.listStreamsByRunId(runId); // [!code highlight]
+
+  return Response.json({ streams: streamNames });
+}
+```
+
+### Read a Stream as a Response
+
+```typescript lineNumbers
+// app/api/workflow-streams/read/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const streamName = url.searchParams.get("name");
+
+  if (!streamName) {
+    return Response.json({ error: "name required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const readable = await world.readFromStream(streamName); // [!code highlight]
+
+  return new Response(readable, {
+    headers: { "Content-Type": "application/octet-stream" },
+  });
+}
+```
+
+## Related
+
+- [Streaming](/docs/foundations/streaming) — Core concepts for streaming data from workflows
+- [getWritable()](/docs/api-reference/workflow/get-writable) — The standard way to write to streams from within steps
+- [world.runs](/docs/api-reference/workflow-api/world/runs) — List runs that may have associated streams

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

@@ -0,0 +1,102 @@
+---
+title: Workflow Globals
+description: Global APIs available inside workflow functions.
+type: reference
+summary: Reference of all global APIs available inside workflow functions.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/errors/node-js-module-in-workflow
+  - /docs/errors/fetch-in-workflow
+  - /docs/errors/timeout-in-workflow
+  - /docs/how-it-works/code-transform
+---
+
+Workflow functions run in a restricted environment that prevents access to non-deterministic or side-effecting APIs. This page lists all global APIs available inside `"use workflow"` functions.
+
+For full Node.js runtime access, use [step functions](/docs/foundations/workflows-and-steps#step-functions).
+
+## Deterministic APIs
+
+These APIs are available but are **seeded or fixed** to ensure deterministic behavior across replays.
+
+| API | Behavior |
+|-----|----------|
+| [`Math.random()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random) | Seeded random number generator — same seed produces the same sequence every replay |
+| [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) / `Date.now()` / `new Date()` | Returns a fixed timestamp that advances with the workflow's logical clock |
+| [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) | Seeded — produces deterministic output for a given workflow run |
+| [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) | Seeded — produces deterministic UUIDs for a given workflow run |
+| [`crypto.subtle.digest()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest) | Passes through to the real implementation (SHA-256, etc. are deterministic by nature) |
+
+<Callout type="info">
+You can safely use `Math.random()`, `Date.now()`, and `crypto.randomUUID()` in workflow functions. The framework ensures these return the same values across replays.
+</Callout>
+
+## Web Platform APIs
+
+These standard Web APIs are available in workflow functions:
+
+- [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers)
+- [`TextEncoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder) / [`TextDecoder`](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder)
+- [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) / [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
+- [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) / [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) — custom implementations with [special behavior in the workflow context](/docs/foundations/serialization#request--response). Body methods like `.json()` and `.text()` are automatically treated as step invocations.
+- [`console`](https://developer.mozilla.org/en-US/docs/Web/API/console)
+- [`structuredClone`](https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone)
+- [`atob`](https://developer.mozilla.org/en-US/docs/Web/API/Window/atob) / [`btoa`](https://developer.mozilla.org/en-US/docs/Web/API/Window/btoa)
+
+## Environment Variables
+
+`process.env` is available as a **read-only, frozen** snapshot of the environment variables at the time the workflow was started. You cannot modify it.
+
+```typescript
+export async function myWorkflow() {
+  "use workflow";
+
+  const apiKey = process.env.API_KEY; // works
+  process.env.FOO = "bar"; // throws — process.env is frozen
+}
+```
+
+## Binary Data
+
+Standard JavaScript typed arrays (`Uint8Array`, `Int32Array`, `Float64Array`, etc.) are available in workflow functions.
+
+### Base64 and hex encoding
+
+The workflow environment provides [`Uint8Array` base64 and hex methods](https://tc39.es/proposal-arraybuffer-base64/) for encoding and decoding binary data:
+
+{/* @skip-typecheck: polyfilled methods not available in host TypeScript */}
+```typescript
+// Encode to base64
+const bytes = new Uint8Array([72, 101, 108, 108, 111]);
+bytes.toBase64(); // "SGVsbG8="
+bytes.toBase64({ alphabet: "base64url" }); // URL-safe variant
+bytes.toBase64({ omitPadding: true }); // "SGVsbG8"
+
+// Decode from base64
+Uint8Array.fromBase64("SGVsbG8="); // Uint8Array([72, 101, 108, 108, 111])
+
+// Encode to hex
+bytes.toHex(); // "48656c6c6f"
+
+// Decode from hex
+Uint8Array.fromHex("48656c6c6f"); // Uint8Array([72, 101, 108, 108, 111])
+
+// Write into an existing array
+const target = new Uint8Array(5);
+target.setFromBase64("SGVsbG8="); // { read: 8, written: 5 }
+target.setFromHex("48656c6c6f"); // { read: 10, written: 5 }
+```
+
+<Callout type="info">
+These methods are polyfilled in the workflow environment. When the JavaScript runtime ships native support, the polyfill is automatically bypassed.
+</Callout>
+
+## Not Available
+
+The following are **not available** in workflow functions. Move this logic to [step functions](/docs/foundations/workflows-and-steps#step-functions) instead.
+
+- **Node.js core modules**: `fs`, `path`, `http`, `https`, `net`, `dns`, `child_process`, `cluster`, `os`, `stream`, `crypto` (Node.js version), etc. See [node-js-module-in-workflow](/docs/errors/node-js-module-in-workflow).
+- **Global `fetch`**: Use [`import { fetch } from "workflow"`](/docs/api-reference/workflow/fetch) instead. See [fetch-in-workflow](/docs/errors/fetch-in-workflow).
+- **Timers**: `setTimeout`, `setInterval`, `setImmediate`, and their `clear*` counterparts. Use [`sleep()`](/docs/api-reference/workflow/sleep) instead. See [timeout-in-workflow](/docs/errors/timeout-in-workflow).
+- **`Buffer`**: Node.js-specific API. Use `Uint8Array` with `toBase64()` / `fromBase64()` / `toHex()` / `fromHex()` for binary data encoding, or `atob()` / `btoa()` for string-based base64.

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

@@ -7,7 +7,7 @@ related:
   - /docs/getting-started/next
 ---
 
-Next.js integration for Workflow DevKit that automatically configures bundling and runtime support.
+Next.js integration for Workflow SDK that automatically configures bundling and runtime support.
 
 ## Functions
 

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

@@ -2,7 +2,7 @@
 title: "@workflow/serde"
 ---
 
-Serialization symbols for custom class serialization in Workflow DevKit.
+Serialization symbols for custom class serialization in Workflow SDK.
 
 ## Installation
 
@@ -12,7 +12,7 @@ npm i @workflow/serde
 
 ## Overview
 
-By default, Workflow DevKit can serialize standard JavaScript types like primitives, objects, arrays, `Date`, `Map`, `Set`, and more. However, custom class instances are not serializable by default because the serialization system doesn't know how to reconstruct them.
+By default, Workflow SDK can serialize standard JavaScript types like primitives, objects, arrays, `Date`, `Map`, `Set`, and more. However, custom class instances are not serializable by default because the serialization system doesn't know how to reconstruct them.
 
 The `@workflow/serde` package provides two symbols that allow you to define custom serialization and deserialization logic for your classes, enabling them to be passed between workflow and step functions.
 

package/docs/changelog/index.mdx

@@ -1,12 +1,12 @@
 ---
 title: Changelog
-description: Latest updates and new features in Workflow DevKit.
+description: Latest updates and new features in Workflow SDK.
 type: overview
 ---
 
 # Changelog
 
-Stay up to date with the latest changes to Workflow DevKit.
+Stay up to date with the latest changes to Workflow SDK.
 
 ---
 

package/docs/deploying/building-a-world.mdx

@@ -214,7 +214,7 @@ Study these implementations for guidance:
 
 ## Testing Your World
 
-Workflow DevKit includes an E2E test suite that validates World implementations. Once your World is published to npm:
+Workflow SDK includes an E2E test suite that validates World implementations. Once your World is published to npm:
 
 1. Add your world to [`worlds-manifest.json`](https://github.com/vercel/workflow/blob/main/worlds-manifest.json)
 2. Open a PR to the Workflow repository

package/docs/deploying/world/vercel-world.mdx

@@ -23,8 +23,6 @@ Deploy your application to Vercel:
 vercel deploy
 ```
 
-<FluidComputeCallout />
-
 That's it. Vercel automatically:
 
 - Selects the Vercel World backend
@@ -32,6 +30,24 @@ That's it. Vercel automatically:
 - Provisions storage and queuing infrastructure
 - Isolates data per environment (production, preview, development)
 
+<FluidComputeCallout />
+
+## Vercel platform documentation
+
+For complete details on pricing, usage limits, and included allotments on Vercel, see the official Vercel documentation:
+
+- **[Vercel Workflow](https://vercel.com/docs/workflow)** — Pricing details, concepts, and observability for Workflow on Vercel
+- **[Vercel limits](https://vercel.com/docs/limits)** — Platform-wide limits including Workflow-specific constraints
+- **[Vercel Hobby plan](https://vercel.com/docs/plans/hobby)** — Free tier included usage for Workflow and other resources
+
+For self-hosted deployments, use the [Postgres World](/worlds/postgres). For local development, use the [Local World](/worlds/local).
+
+## Limitations
+
+- **Single-region deployment** - The backend infrastructure is currently deployed only in `iad1`. Applications in other regions will route workflow requests to `iad1`, which may result in higher latency. For best performance, deploy your Vercel apps using Workflow to `iad1`. Global deployment is planned to colocate the backend closer to your applications.
+
+- **Data residency** - The Vercel World is currently deployed in the `iad1` region. This means independently of the deployment location of your application, the data for your workflows will be stored in the `iad1` region.
+
 ## Observability
 
 Workflow observability is built into the Vercel dashboard on your project page. It respects your existing authentication and project permission settings.
@@ -97,7 +113,8 @@ Custom base URL for the Vercel workflow API. Automatically detected.
 
 ### Programmatic configuration
 
-{/* @skip-typecheck: incomplete code sample */}
+{/*@skip-typecheck: incomplete code sample*/}
+
 ```typescript title="workflow.config.ts" lineNumbers
 import { createVercelWorld } from "@workflow/world-vercel";
 
@@ -131,13 +148,3 @@ The Vercel World uses Vercel's infrastructure for workflow execution:
 - **Authentication** - OIDC tokens provide secure, automatic authentication
 
 For more details, see the [Vercel Workflow documentation](https://vercel.com/docs/workflow).
-
-## Pricing and More
-
-See the [Vercel Workflow documentation](https://vercel.com/docs/workflow) for current pricing and to learn more.
-
-For self-hosted deployments, use the [Postgres World](/worlds/postgres). For local development, use the [Local World](/worlds/local).
-
-## Limitations
-
-- **Single-region deployment** - The backend infrastructure is currently deployed only in `iad1`. Applications in other regions will route workflow requests to `iad1`, which may result in higher latency. For best performance, deploy your Vercel apps using Workflow to `iad1`. Global deployment is planned to colocate the backend closer to your applications.

package/docs/errors/index.mdx

@@ -7,7 +7,7 @@ related:
   - /docs/foundations/errors-and-retries
 ---
 
-Fix common mistakes when creating and executing workflows in the **Workflow DevKit**.
+Fix common mistakes when creating and executing workflows in the **Workflow SDK**.
 
 <Cards>
     <Card href="/docs/errors/fetch-in-workflow" title="fetch-in-workflow">

package/docs/errors/node-js-module-in-workflow.mdx

@@ -76,5 +76,5 @@ These common Node.js core modules cannot be used in workflow functions:
 - Streams: `stream` (use Web Streams API instead)
 
 <Callout type="info">
-You can use Web Platform APIs in workflow functions (like `Headers`, `crypto.randomUUID()`, `Response`, etc.), since these are available in the sandboxed environment.
+You can use Web Platform APIs in workflow functions (like `Headers`, `crypto.randomUUID()`, `Response`, etc.), since these are available in the sandboxed environment. See [Workflow Globals](/docs/api-reference/workflow-globals) for the full list.
 </Callout>

package/docs/errors/serialization-failed.mdx

@@ -109,7 +109,7 @@ async function greetStep(userData: { name: string }) {
 
 ## Supported Serializable Types
 
-Workflow DevKit supports these types across execution boundaries:
+Workflow SDK supports these types across execution boundaries:
 
 ### Standard JSON Types
 

package/docs/errors/start-invalid-workflow-function.mdx

@@ -9,18 +9,18 @@ related:
   - /docs/api-reference/workflow-api/start
 ---
 
-This error occurs when you try to call `start()` with a function that is not a valid workflow function or when the Workflow DevKit is not configured correctly.
+This error occurs when you try to call `start()` with a function that is not a valid workflow function or when the Workflow SDK is not configured correctly.
 
 ## Error Message
 
 ```
-'start' received an invalid workflow function. Ensure the Workflow DevKit
+'start' received an invalid workflow function. Ensure the Workflow SDK
 is configured correctly and the function includes a 'use workflow' directive.
 ```
 
 ## Why This Happens
 
-The `start()` function expects a workflow function that has been properly processed by Workflow DevKit's build system. During the build process, workflow functions are transformed and marked with special metadata that `start()` uses to identify and execute them.
+The `start()` function expects a workflow function that has been properly processed by Workflow SDK's build system. During the build process, workflow functions are transformed and marked with special metadata that `start()` uses to identify and execute them.
 
 This error typically happens when:
 

package/docs/foundations/errors-and-retries.mdx

@@ -10,7 +10,7 @@ related:
   - /docs/api-reference/workflow/retryable-error
 ---
 
-By default, errors thrown inside steps are retried. Additionally, Workflow DevKit provides two new types of errors you can use to customize retries.
+By default, errors thrown inside steps are retried. Additionally, Workflow SDK provides two new types of errors you can use to customize retries.
 
 ## Default Retrying
 

package/docs/foundations/hooks.mdx

@@ -219,7 +219,11 @@ While hooks are powerful, they require you to manually handle HTTP requests and
 2. Provides an automatically addressable `url` property pointing to the generated webhook endpoint
 3. Handles sending HTTP [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects back to the caller
 
-When using Workflow DevKit, webhooks are automatically wired up at `/.well-known/workflow/v1/webhook/:token` without any additional setup.
+When using Workflow SDK, webhooks are automatically wired up at `/.well-known/workflow/v1/webhook/:token` without any additional setup.
+
+<Callout type="warn">
+`createWebhook()` exposes a public route at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests. This is convenient for prototypes and a simple developer experience because you can share the webhook URL (endpoint) without 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>
 
 <Callout type="info">
 See the full API reference for [`createWebhook()`](/docs/api-reference/workflow/create-webhook) for all available options.