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

package/docs/how-it-works/cancellation.mdx

@@ -18,30 +18,30 @@ This guide explains how cancellation works internally. Understanding these detai
 
 When you write `new AbortController()` in a workflow function, Workflow DevKit creates a durable controller backed by two existing primitives: a [hook](/docs/foundations/hooks) and a [stream](/docs/foundations/streaming). This page explains why both are needed and how they work together.
 
-## The Problem
+## The problem
 
-`AbortController` and `AbortSignal` are inherently stateful — an abort happens once and is permanent. In a durable workflow, this state must:
+`AbortController` and `AbortSignal` are inherently stateful: an abort happens once and is permanent. In a durable workflow, this state must:
 
-1. **Survive replay** — If `abort()` was called, `signal.aborted` must return `true` on every subsequent replay of the workflow.
-2. **Propagate in real-time** — A running step on a different compute instance must receive the abort immediately, not on the next replay.
+1. **Survive replay**: If `abort()` was called, `signal.aborted` must return `true` on every subsequent replay of the workflow.
+2. **Propagate in real-time**: A running step on a different compute instance must receive the abort immediately, not on the next replay.
 
 No single primitive solves both. Hooks provide durable event log state but can't reach into a running step. Streams provide real-time cross-process communication but aren't part of the event log. The solution is to use both.
 
-## Dual Backing: Hook + Stream
+## Dual backing: hook + stream
 
 Every `AbortController` in the workflow context is backed by:
 
-### Hook (Durable State)
+### Hook (durable state)
 
-When `new AbortController()` is called in a workflow, an internal hook is created — similar to calling `createHook()`. This hook is registered in the workflow's invocations queue and produces events in the [event log](/docs/how-it-works/event-sourcing):
+When `new AbortController()` is called in a workflow, an internal hook is created, similar to calling `createHook()`. This hook is registered in the workflow's invocations queue and produces events in the [event log](/docs/how-it-works/event-sourcing):
 
 - **On creation**: A `hook_created` event records that the controller exists
 - **On abort**: The hook is resumed (producing a `hook_received` event), recording the abort permanently
 - **On replay**: The event consumer processes the `hook_received` event and updates `signal.aborted` to `true` at the same point in the replay as the original abort
 
-This gives the workflow deterministic access to the abort state — `controller.signal.aborted` always returns the correct value, even after cold starts.
+This gives the workflow deterministic access to the abort state: `controller.signal.aborted` always returns the correct value, even after cold starts.
 
-### Stream (Real-Time Propagation)
+### Stream (real-time propagation)
 
 When `controller.signal` is serialized as a step argument, a stream name is included in the serialized form. Inside the step, the deserialized `AbortSignal` listens on this stream:
 
@@ -50,7 +50,7 @@ When `controller.signal` is serialized as a step argument, a stream name is incl
 
 This gives steps real-time cancellation without waiting for the workflow to replay.
 
-### Why Both?
+### Why both?
 
 | Mechanism | Solves | Doesn't Solve |
 |---|---|---|
@@ -60,18 +60,18 @@ This gives steps real-time cancellation without waiting for the workflow to repl
 
 ## Lifecycle
 
-### 1. Controller Created in Workflow
+### 1. Controller created in workflow
 
-```
+```text
 new AbortController()
         │
         ├─→ Internal hook created (registered in invocations queue)
         └─→ Stream name generated (deterministic ULID)
 ```
 
-### 2. Signal Passed to Step
+### 2. Signal passed to step
 
-```
+```text
 stepFunction(controller.signal)
         │
         ├─→ Signal serialized as { streamName, hookToken, aborted }
@@ -80,9 +80,9 @@ stepFunction(controller.signal)
                 └─→ Background reader listens on stream for abort packet
 ```
 
-### 3. abort() Called in Workflow
+### 3. abort() called in workflow
 
-```
+```text
 controller.abort()
         │
         ├─→ signal.aborted set to true (synchronous, local state)
@@ -92,13 +92,13 @@ controller.abort()
                 ├─→ Suspension handler creates hook_received event
                 ├─→ Suspension handler writes cancellation packet to stream
                 │       │
-                │       └─→ Step receives packet → local signal fires → fetch cancelled
+                │       └─→ Step receives packet → local signal fires → fetch canceled
                 └─→ Workflow re-enqueued for replay
 ```
 
-### 4. Workflow Replays After Abort
+### 4. Workflow replays after abort
 
-```
+```text
 Replay starts → events loaded
         │
         ├─→ new AbortController() → hook created → event consumer subscribes
@@ -107,34 +107,34 @@ Replay starts → events loaded
         └─→ Workflow code sees signal.aborted === true at the correct point in replay
 ```
 
-On replay, the events consumer re-applies the abort by calling `_setAborted` when it encounters the `hook_received` event in the log — at the same point in execution where the original `abort()` happened. This is what makes the abort deterministic across replays.
+On replay, the events consumer re-applies the abort by calling `_setAborted` when it encounters the `hook_received` event in the log, at the same point in execution where the original `abort()` happened. This is what makes the abort deterministic across replays.
 
-## Where the Hook Is Created
+## Where the hook is created
 
 The backing hook is set up whenever an `AbortController` or `AbortSignal` enters the workflow context:
 
-**`new AbortController()` in a workflow function** — The workflow VM provides a durable `AbortController` implementation (similar to how it provides deterministic `Date` and serializable `Request`/`Response`). The hook is created in the constructor using the orchestrator context injected via VM globals.
+**`new AbortController()` in a workflow function**: The workflow VM provides a durable `AbortController` implementation (similar to how it provides deterministic `Date` and serializable `Request`/`Response`). The hook is created in the constructor using the orchestrator context injected via VM globals.
 
-**Returned from a step** — A step can create a plain `new AbortController()` and return it. The step-side serializer generates a stream name and hook token (using a random ULID) and includes them in the serialized payload. When the return value is deserialized into the workflow via `hydrateStepReturnValue`, the workflow reviver reads the token from the payload and sets up the hook with that token. Since the serialized payload is stored in the event log (as part of the `step_completed` event), the same token is used on every replay — no deterministic generation needed in the workflow.
+**Returned from a step**: A step can create a plain `new AbortController()` and return it. The step-side serializer generates a stream name and hook token (using a random ULID) and includes them in the serialized payload. When the return value is deserialized into the workflow via `hydrateStepReturnValue`, the workflow reviver reads the token from the payload and sets up the hook with that token. Since the serialized payload is stored in the event log (as part of the `step_completed` event), the same token is used on every replay, so no deterministic generation is needed in the workflow.
 
-**Passed as workflow input** — Conceptually the same as "returned from a step". The **external reducer** handles it at serialization time:
+**Passed as workflow input**: Conceptually the same as "returned from a step". The **external reducer** handles it at serialization time:
 
 1. Generates a stream name and hook token (random ULID)
 2. Attaches an `abort` event listener on the source signal: when the external code calls `controller.abort()`, the listener writes the cancellation packet to the stream
 3. Pushes the listener's async work into `ops` (awaited via `waitUntil`)
 4. Serializes the reference as `{ streamName, hookToken, aborted }`
 
-The serialized payload (including the generated token) is stored in the event log as part of the workflow's input. When the workflow deserializes the input, the reviver reads the token from the payload and creates the hook — identical to the "returned from a step" case. On replay, the same token is read from the event log, so the hook matches the same events.
+The serialized payload (including the generated token) is stored in the event log as part of the workflow's input. When the workflow deserializes the input, the reviver reads the token from the payload and creates the hook, identical to the "returned from a step" case. On replay, the same token is read from the event log, so the hook matches the same events.
 
 If the external code calls `abort()` while the process is still alive (within the `waitUntil` window), the stream packet arrives in the workflow, and the workflow can resume the hook to record it in the event log.
 
 <Callout type="info">
-Since the external `AbortController` is a plain JavaScript object (not the workflow VM's durable version), the stream write depends on the originating process still being alive. This is the same constraint that applies to passing a `ReadableStream` as a workflow argument — the stream pipe runs via `waitUntil` and requires the process to remain active until the data is written.
+Since the external `AbortController` is a plain JavaScript object (not the workflow VM's durable version), the stream write depends on the originating process still being alive. This is the same constraint that applies to passing a `ReadableStream` as a workflow argument: the stream pipe runs via `waitUntil` and requires the process to remain active until the data is written.
 </Callout>
 
-## Serialization & Deserialization
+## Serialization & deserialization
 
-### Serialized Form
+### Serialized form
 
 An `AbortController` or `AbortSignal` is serialized as:
 
@@ -148,23 +148,23 @@ An `AbortController` or `AbortSignal` is serialized as:
 }
 ```
 
-The `streamName` and `hookToken` are generated once at serialization time (in the step or external context) and stored in the event log as part of the serialized payload. On replay, the workflow reviver reads them from the payload — it never generates them itself. This is the same pattern used by `ReadableStream` and `WritableStream` serialization.
+The `streamName` and `hookToken` are generated once at serialization time (in the step or external context) and stored in the event log as part of the serialized payload. On replay, the workflow reviver reads them from the payload; it never generates them itself. This is the same pattern used by `ReadableStream` and `WritableStream` serialization.
 
-### Reducers (Serialization)
+### Reducers (serialization)
 
 **In step context** (`getStepReducers`): When a step returns an `AbortController`, the reducer captures the stream name. If `abort()` was called in the step, `aborted: true` is recorded.
 
-**In workflow context** (`getWorkflowReducers`): The reducer captures the stream name and hook token. These are handles — no I/O happens during serialization in the workflow.
+**In workflow context** (`getWorkflowReducers`): The reducer captures the stream name and hook token. These are handles; no I/O happens during serialization in the workflow.
 
 **In external context** (`getExternalReducers`): When an `AbortController` is passed as a workflow argument from outside, the reducer creates the backing stream and serializes the reference.
 
-### Revivers (Deserialization)
+### Revivers (deserialization)
 
 **Into step context** (`getStepRevivers`): Creates a real `AbortController`. If `aborted: true`, calls `abort()` immediately. Otherwise, pushes a stream reader into the step's `ops` array that listens for the cancellation packet and calls `abort()` when received.
 
 **Into workflow context** (`getWorkflowRevivers`): Creates the durable AbortController with hook backing. Subscribes to the events consumer for the hook's correlation ID. If the event log contains a `hook_received` event, `signal.aborted` is `true`.
 
-### abort() in a Step
+### abort() in a step
 
 When `abort()` is called on a deserialized `AbortController` inside a step:
 
@@ -172,18 +172,18 @@ When `abort()` is called on a deserialized `AbortController` inside a step:
 2. The stream write (cancellation packet) is pushed into `ctx.ops`
 3. The hook resume (`resumeHook`) is pushed into `ctx.ops`
 
-The step's `ops` array is awaited via `waitUntil(Promise.all(ops))` after the step function returns — the same mechanism used by [`getWritable()`](/docs/api-reference/workflow/get-writable). This keeps `abort()` synchronous from the caller's perspective while ensuring the async work completes.
+The step's `ops` array is awaited via `waitUntil(Promise.all(ops))` after the step function returns, the same mechanism used by [`getWritable()`](/docs/api-reference/workflow/get-writable). This keeps `abort()` synchronous from the caller's perspective while ensuring the async work completes.
 
-### Abort Errors Are Wrapped in FatalError
+### Abort errors are wrapped in FatalError
 
-When a step throws due to an abort — whether from `fetch` throwing `AbortError`, `signal.throwIfAborted()`, or any other abort-induced error — the step executor wraps the error in `FatalError` before recording it in the event log. This ensures:
+When a step throws due to an abort (whether from `fetch` throwing `AbortError`, `signal.throwIfAborted()`, or any other abort-induced error), the step executor wraps the error in `FatalError` before recording it in the event log. This ensures:
 
-- **No retries**: An abort is intentional cancellation, not a transient failure. Retrying would just abort again.
+- **No retries**: An abort is intentional cancellation, not a transient failure. Retrying would abort again.
 - **Immediate propagation**: The error bubbles up to the workflow as a `FatalError`, which the workflow can catch with `FatalError.is(err)`.
 
 The wrapping happens in `runtime/step-executor.ts` during error hydration. When the step's thrown error is an `AbortError` (checked via `err.name === 'AbortError'`), it is treated as fatal regardless of the step's `maxRetries` configuration.
 
-### abort() in the Workflow
+### abort() in the workflow
 
 When `abort()` is called in the workflow context:
 
@@ -194,7 +194,7 @@ When `abort()` is called in the workflow context:
    - Creates a `hook_received` event in the event log
    - Writes the cancellation packet to the stream (for real-time step propagation)
    - Re-enqueues the workflow for replay
-4. On replay, the event consumer processes the `hook_received` event, updating `signal.aborted` to `true` at the deterministically correct point
+5. On replay, the event consumer processes the `hook_received` event, updating `signal.aborted` to `true` at the deterministically correct point
 
 `signal.aborted` is updated synchronously so that the workflow can immediately check the state and serialization captures `aborted: true` when passing the signal to steps. On replay, the event consumer also processes the `hook_received` event, ensuring the state is consistent.
 
@@ -203,55 +203,55 @@ For abort specifically, this ensures that:
 - The abort's `hook_received` event is created in the event log
 - The cancellation stream packet is written to propagate to running steps
 
-## Race Conditions
+## Race conditions
 
-### Abort Before Hook Exists
+### Abort before hook exists
 
 When an `AbortSignal` is passed as a workflow argument via `start()`, the external reducer attaches a listener at serialization time. If the external code calls `abort()` before the workflow has started and created the internal hook, the stream packet is written but the hook doesn't exist yet.
 
 This is resolved through eventual consistency:
 
-1. The stream packet is durable — it persists in storage
+1. The stream packet is durable; it persists in storage
 2. When the workflow runs and passes the signal to a step, the step's reviver reads from the stream starting at index 0
 3. The step sees the existing packet, aborts locally, and resumes the hook (via `ops`)
 4. On the next workflow replay, the hook event is in the log and `signal.aborted` is `true`
 
-**Important:** There is a window where the workflow's `signal.aborted` returns `false` even though the external code has already called `abort()`. This lasts until a step processes the stream packet and resumes the hook. This is analogous to hooks — `resumeHook()` doesn't take effect until the workflow replays.
+**Important:** There is a window where the workflow's `signal.aborted` returns `false` even though the external code has already called `abort()`. This lasts until a step processes the stream packet and resumes the hook. This is analogous to hooks: `resumeHook()` doesn't take effect until the workflow replays.
 
-### Abort at Serialization Time
+### Abort at serialization time
 
 To prevent a micro-window where `abort()` is called between checking `signal.aborted` and attaching the listener, the external reducer uses this order:
 
 1. Attach the `abort` event listener first
-2. Then check `signal.aborted` — if already `true`, the listener won't fire, so handle immediately
+2. Then check `signal.aborted`; if already `true`, the listener won't fire, so handle immediately
 
 This ensures no abort events are missed regardless of timing.
 
-## Stream/Hook Consistency
+## Stream/hook consistency
 
 Since abort involves two operations (stream write + hook resume), partial failure is possible:
 
-### Stream Succeeds, Hook Fails
+### Stream succeeds, hook fails
 
 - Steps see the abort and throw `AbortError` (stream worked)
 - Workflow doesn't see `signal.aborted === true` on the next replay (hook not resumed)
 - The workflow sees the step failure as an error, which it can handle with try/catch
-- **Recovery:** The step-side `resumeHook` call is best-effort — if it throws, the failure is swallowed. Convergence comes from the next replay: when the step's reviver re-reads the stream, it sees the abort packet and calls `resumeHook` again. There's no in-process retry loop; the dual-mechanism design relies on either the stream or the hook eventually landing.
+- **Recovery:** The step-side `resumeHook` call is best-effort: if it throws, the failure is swallowed. Convergence comes from the next replay: when the step's reviver re-reads the stream, it sees the abort packet and calls `resumeHook` again. There's no in-process retry loop; the dual-mechanism design relies on either the stream or the hook eventually landing.
 
-### Hook Succeeds, Stream Fails
+### Hook succeeds, stream fails
 
 - Workflow sees `signal.aborted === true` on replay (hook worked)
-- Steps don't receive real-time cancellation (stream failed) — they run to completion
+- Steps don't receive real-time cancellation (stream failed), so they run to completion
 - On the next suspension, the workflow knows the abort happened and can stop calling more steps
-- **Recovery:** Natural convergence — no active harm, just missed real-time cancellation for in-flight steps.
+- **Recovery:** Natural convergence. No active harm, only missed real-time cancellation for in-flight steps.
 
-### Both Fail
+### Both fail
 
-- Abort is lost — no propagation
-- No crash or corruption — the system continues as if abort was never called
+- Abort is lost; no propagation
+- No crash or corruption; the system continues as if abort was never called
 - **Recovery:** The caller can retry the abort. If using a hook for external cancellation, the hook's retry semantics apply.
 
-The dual mechanism provides natural resilience — if either one succeeds, the system converges on the correct state.
+The dual mechanism provides natural resilience: if either one succeeds, the system converges on the correct state.
 
 ## `AbortSignal.timeout()` in Workflow VM
 
@@ -264,7 +264,7 @@ The dual mechanism provides natural resilience — if either one succeeds, the s
 A `Request`'s `.signal` is forwarded by the `Request` reducer in two cases:
 
 1. **The signal is already aborted.** The serialized payload preserves `aborted: true` and the abort `reason`, so the deserialized step sees the cancellation that happened before the boundary.
-2. **The signal is workflow-managed** (i.e., it has the `ABORT_STREAM_NAME` symbol — produced by a workflow-context `AbortController`). Its hook + stream backing carries through, and the deserialized step listens on the stream as usual.
+2. **The signal is workflow-managed** (i.e., it has the `ABORT_STREAM_NAME` symbol, produced by a workflow-context `AbortController`). Its hook + stream backing carries through, and the deserialized step listens on the stream as usual.
 
 Plain non-aborted native signals are intentionally dropped, including the auto-generated signal that `new Request(url)` synthesizes when no `signal` is passed. Forwarding every Request signal would mint stream infrastructure for the throwaway auto-signals on every Request, even ones the caller never intended to use for cancellation.
 
@@ -278,10 +278,10 @@ await fetchStep(req); // signal carries through
 controller.abort();   // step-side fetch sees the abort
 ```
 
-## Related Documentation
+## Related documentation
 
-- [Cancellation](/docs/foundations/cancellation) — Usage patterns and API
-- [Event Sourcing](/docs/how-it-works/event-sourcing) — How the event log works
-- [Hooks](/docs/foundations/hooks) — The hook primitive
-- [Streaming](/docs/foundations/streaming) — The stream primitive
-- [Serialization](/docs/foundations/serialization) — Serializable types
+- [Cancellation](/docs/foundations/cancellation): Usage patterns and API
+- [Event Sourcing](/docs/how-it-works/event-sourcing): How the event log works
+- [Hooks](/docs/foundations/hooks): The hook primitive
+- [Streaming](/docs/foundations/streaming): The stream primitive
+- [Serialization](/docs/foundations/serialization): Serializable types

package/docs/how-it-works/code-transform.mdx

@@ -1,5 +1,5 @@
 ---
-title: How the Directives Work
+title: How the directives work
 description: Deep dive into the internals of how Workflow SDK directives transform your code.
 type: conceptual
 summary: Learn how the compiler transforms directive-annotated code into three execution modes.
@@ -10,16 +10,15 @@ related:
 ---
 
 <Callout>
-This is an advanced guide that dives into internals of the Workflow SDK directive and is not required reading to use workflows. To simply use the Workflow SDK, check out the [getting started](/docs/getting-started) guides for your framework.
+This advanced guide covers the internals of Workflow SDK directives. To start using Workflow SDK, see the [getting started](/docs/getting-started) guide for your framework.
 </Callout>
 
-Workflows use special directives to mark code for transformation by the Workflow SDK compiler. This page explains how `"use workflow"` and `"use step"` directives work, what transformations are applied, and why they're necessary for durable execution.
+Workflows use special directives to mark code for transformation by the Workflow SDK compiler. The `"use workflow"` and `"use step"` directives apply the transformations required for durable execution.
 
-## Directives Overview
+## Directives overview
 
 Workflows use two directives to mark functions for special handling:
 
-{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 export async function handleUserSignup(email: string) {
   "use workflow"; // [!code highlight]
@@ -44,7 +43,7 @@ async function createUser(email: string) {
 
 These directives trigger the `@workflow/swc-plugin` compiler to transform your code in different ways depending on the execution context.
 
-## The Three Transformation Modes
+## The three transformation modes
 
 The compiler operates in three distinct modes, transforming the same source code differently for each execution context:
 
@@ -52,39 +51,47 @@ The compiler operates in three distinct modes, transforming the same source code
 flowchart LR
     A["Source Code<br/>with directives"] --> B["Step Mode"]
     A --> C["Workflow Mode"]
-    A --> D["Client Mode"]
+    A --> D["Detect Mode"]
     B --> E["Step registration bundle"]
+    B --> G["Your App Code<br/>(Enables `start`)"]
     C --> F["Workflow bundle"]
     E --> H["Combined flow handler"]
     F --> H
-    D --> G["Your App Code<br/>(Enables `start`)"]
+    D --> I["Build manifest<br/>(discovery)"]
 ```
 
-### Comparison Table
+### Comparison table
 
 | Mode     | Used In    | Purpose                        | Runtime role | Required? |
 |----------|------------|--------------------------------|--------------|-----------|
-| Step     | Build time | Registers executable step functions | Imported by the combined flow handler | Yes |
+| Step     | Build time + your app code | Registers executable step functions; gives app code workflow IDs for `start()` | Imported by the combined flow handler, and applied to application code by the framework loader | Yes |
 | Workflow | Build time | Bundles workflow orchestrators | Executed by `.well-known/workflow/v1/flow` | Yes |
-| Client   | Build/Runtime | Provides workflow IDs and types to `start` | Your application code | Optional* |
+| Detect   | Build time | Discovers workflows, steps, and serialization classes without transforming code | Feeds the build's discovery phase and manifest | Yes (build-internal) |
 
-\* Client mode is **recommended** for better developer experience—it provides automatic ID generation and type safety. Without it, you must manually construct workflow IDs or use the build manifest.
+<Callout type="info">
+  Earlier releases had a separate **client mode** for application code. In 5.0 it merged into step mode, which produces the same app-code behavior (workflow functions throw on direct calls and carry `workflowId` for `start()`) while also registering step functions. Build integrations that passed `mode: "client"` now pass `mode: "step"`.
+</Callout>
 
-## Detailed Transformation Examples
+## Detailed transformation examples
 
-<Tabs items={["Step Mode", "Workflow Mode", "Client Mode"]}>
+<Tabs items={["Step Mode", "Workflow Mode", "Detect Mode"]}>
 <Tab value="Step Mode">
 
-**Step Mode** creates a registration bundle that the combined flow handler imports. It is not an HTTP route.
+**Step Mode** creates the registration bundle that the combined flow handler imports (it is not an HTTP route), and is also the transform framework loaders apply to your application code.
 
 **Input:**
 
-{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 export async function createUser(email: string) {
   "use step";
   return { id: crypto.randomUUID(), email };
 }
+
+export async function handleUserSignup(email: string) {
+  "use workflow";
+  const user = await createUser(email);
+  return { userId: user.id };
+}
 ```
 
 **Output:**
@@ -99,18 +106,25 @@ export async function createUser(email: string) {
     __wf_reg.set(__wf_id, __wf_fn); // [!code highlight]
     __wf_fn.stepId = __wf_id; // [!code highlight]
 })(createUser, "step//workflows/user.js//createUser"); // [!code highlight]
+
+export async function handleUserSignup(email: string) {
+  throw new Error("You attempted to execute ..."); // [!code highlight]
+}
+handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup"; // [!code highlight]
 ```
 
 **What happens:**
 
 - The `"use step"` directive is removed
-- The function body is kept completely intact (no transformation)
-- The function is registered with the runtime via an inline IIFE (no imports needed)
+- Step function bodies are kept completely intact (no transformation)
+- Each step function is registered with the runtime via an inline IIFE (no imports needed)
 - Step functions run with full Node.js/Deno/Bun access
+- Workflow function bodies are **replaced** with an error throw, and a `workflowId` property is attached. Launch workflow functions with [`start()`](/docs/api-reference/workflow-api/start) instead of calling them directly. The ID identifies the workflow to `start()`
+- A dead-code-elimination pass removes code reachable only from the replaced workflow bodies
 
-**Why no transformation?** Step functions execute in your main runtime with full access to Node.js APIs, file system, databases, etc. They don't need any special handling—they just run normally.
+**Why no step transformation?** Step functions execute in your main runtime with full access to Node.js APIs, the file system, databases, and other resources. They run normally without special handling.
 
-**ID Format:** Step IDs follow the pattern `step//{filepath}//{functionName}`, where the filepath is relative to your project root.
+**ID format:** Step IDs follow the pattern `step//{filepath}//{functionName}`, where the file path is relative to your project root.
 
 </Tab>
 <Tab value="Workflow Mode">
@@ -119,7 +133,6 @@ export async function createUser(email: string) {
 
 **Input:**
 
-{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 export async function createUser(email: string) {
   "use step";
@@ -151,7 +164,7 @@ handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup"; /
 **What happens:**
 
 - Step function bodies are **replaced** with calls to `globalThis[Symbol.for("WORKFLOW_USE_STEP")]`
-- Workflow function bodies remain **intact**—they execute deterministically during replay
+- Workflow function bodies remain **intact**, so they execute deterministically during replay
 - The workflow function gets a `workflowId` property for runtime identification
 - The `"use workflow"` directive is removed
 
@@ -159,14 +172,14 @@ handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup"; /
 
 1. Checks if the step has already been executed (in the event log)
 2. If yes: Returns the cached result
-3. If no: Triggers a suspension and enqueues the step for background execution
+3. If no: Suspends the replay and executes the step, usually inline in the same invocation. The runtime returns the run to the queue only when the invocation's inline budget is exhausted or its timeout approaches
 
-**ID Format:** Workflow IDs follow the pattern `workflow//{filepath}//{functionName}`. The `workflowId` property is attached to the function to allow [`start()`](/docs/api-reference/workflow-api/start) to work at runtime.
+**ID format:** Workflow IDs follow the pattern `workflow//{filepath}//{functionName}`. The `workflowId` property is attached to the function so [`start()`](/docs/api-reference/workflow-api/start) works at runtime.
 
 </Tab>
-<Tab value="Client Mode">
+<Tab value="Detect Mode">
 
-**Client Mode** transforms workflow functions in your application code to prevent direct execution.
+**Detect Mode** is a lightweight, non-transforming mode used during the build's discovery phase.
 
 **Input:**
 
@@ -183,35 +196,30 @@ export async function handleUserSignup(email: string) {
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript
+/**__internal_workflows{"workflows":{"user.js":{"handleUserSignup":{"workflowId":"workflow//workflows/user.js//handleUserSignup"}}}}*/; // [!code highlight]
 export async function handleUserSignup(email: string) {
-  throw new Error("You attempted to execute ..."); // [!code highlight]
+  "use workflow";
+  const user = await createUser(email);
+  return { userId: user.id };
 }
-handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup"; // [!code highlight]
 ```
 
 **What happens:**
 
-- Workflow function bodies are **replaced** with an error throw
-- The `workflowId` property is added (same as workflow mode)
-- Step functions are not transformed in client mode
-
-**Why this transformation?** Workflow functions cannot be called directly from application code—they must be started using [`start()`](/docs/api-reference/workflow-api/start). The error prevents accidental direct execution while the `workflowId` property allows the `start()` function to identify which workflow to launch.
+- The code is **not modified**. Detect mode only walks the AST
+- Discovered workflows, steps, and custom-serialization classes are emitted as a JSON manifest comment
+- The build uses this to decide which files feed the step and workflow bundles
 
-The IDs are generated exactly like in workflow mode to ensure they can be directly referenced at runtime.
+**Why a separate mode?** The build system first runs a fast regular expression pre-scan to find candidate files containing directive-like strings. It then runs detect mode on those candidates to validate them at the abstract syntax tree (AST) level. The plugin eliminates false positives, such as a directive-like string inside a template literal, because it only recognizes genuine directive statements.
 
 <Callout type="info">
-  **Client mode is optional:** While recommended for better developer experience (automatic IDs and type safety), you can skip client mode and instead:
-  - Manually construct workflow IDs using the pattern `workflow//{filepath}//{functionName}`
-  - Use the workflow manifest file generated during build to lookup IDs
-  - Pass IDs directly to `start()` as strings
-
-  All framework integrations include client mode as a loader by default.
+  **Working without the app-code loader:** Frameworks apply the step-mode transform to application code by default, which is what gives `start(handleUserSignup)` its automatic IDs and type safety. If your setup can't run the loader, you can instead construct workflow IDs manually using the pattern `workflow//{filepath}//{functionName}`, look them up in the build manifest, and pass them to `start()` as strings.
 </Callout>
 
 </Tab>
 </Tabs>
 
-## Generated Files
+## Generated files
 
 When you build your application, the Workflow SDK generates a combined flow handler, an internal step registration bundle, and a webhook handler. Exact filenames vary by framework.
 
@@ -224,7 +232,7 @@ Contains all workflow functions transformed in **workflow mode**. This file is i
 All workflow code is bundled together and embedded as a string inside `flow.js`. When a workflow needs to execute, this bundled code is run inside a **Node.js VM** (virtual machine) to ensure:
 
 - **Determinism**: The same inputs always produce the same outputs
-- **Side-effect prevention**: Direct access to Node.js APIs, file system, network, etc. is blocked
+- **Side-effect prevention**: Direct access to Node.js APIs, the file system, the network, and other resources is blocked
 - **Sandboxed execution**: Workflow orchestration logic is isolated from the main runtime
 
 **Build-time validation:**
@@ -259,6 +267,10 @@ Contains all step functions transformed in **step mode**. The combined flow hand
 
 This module must not be exposed as an HTTP endpoint.
 
+<Callout type="info">
+  **Changed in 5.0:** In 4.x, the step bundle was served as its own HTTP route at `POST /.well-known/workflow/v1/step`, with step messages delivered on a separate `__wkf_step_*` queue topic. v5 merged both into the combined flow handler. The step bundle became a registration module imported by `flow.js`, and step messages arrive on the shared workflow queue. Use the version picker to see the old layout on the v4 version of this page.
+</Callout>
+
 ### `webhook.js`
 
 Contains webhook handling logic for delivering external data to running workflows via [`createWebhook()`](/docs/api-reference/workflow/create-webhook).
@@ -269,24 +281,24 @@ Contains webhook handling logic for delivering external data to running workflow
 - Validates tokens and routes data to the correct workflow run
 - Resumes workflow execution after webhook delivery
 
-**Note:** The webhook file structure varies by framework. Next.js generates `webhook/[token]/route.js` to leverage App Router's dynamic routing, while other frameworks generate a single `webhook.js` or `webhook.mjs` handler.
+The webhook file structure varies by framework. Next.js generates `webhook/[token]/route.js` to use App Router's dynamic routing, while other frameworks generate a single `webhook.js` or `webhook.mjs` handler.
 
-## Why Three Modes?
+## Why three modes?
 
 The multi-mode transformation enables the Workflow SDK's durable execution model:
 
-1. **Step Mode** (required) - Bundles executable step functions that can access the full runtime
-2. **Workflow Mode** (required) - Creates orchestration logic that can replay from event logs
-3. **Client Mode** (optional) - Prevents direct execution and enables type-safe workflow references
+1. **Step mode** (required): Bundles executable step functions that can access the full runtime and serves as the application-code transform that prevents direct workflow execution and enables type-safe `start()` references
+2. **Workflow mode** (required): Creates orchestration logic that can replay from event logs
+3. **Detect mode** (build-internal): Discovers directive-marked functions for the build without changing the code
 
 This separation allows:
 
 - **Deterministic replay**: Workflows can be safely replayed from event logs without re-executing side effects
 - **Sandboxed orchestration**: Workflow logic runs in a controlled VM without direct runtime access
 - **Stateless execution**: Your compute can scale to zero and resume from any point in the workflow
-- **Type safety**: TypeScript works seamlessly with workflow references (when using client mode)
+- **Type safety**: TypeScript supports workflow references passed to `start()`
 
-## Determinism and Replay
+## Determinism and replay
 
 A key aspect of the transformation is maintaining **deterministic replay** for workflow functions.
 
@@ -296,7 +308,7 @@ A key aspect of the transformation is maintaining **deterministic replay** for w
 - No direct side effects (no API calls, no database writes, no file I/O)
 - Can use seeded random/time APIs provided by the VM (`Math.random()`, `Date.now()`, etc.)
 
-Because workflow functions are deterministic and have no side effects, they can be safely re-run multiple times to calculate what the next step should be. This is why workflow function bodies remain intact in workflow mode—they're pure orchestration logic.
+Because workflow functions are deterministic and have no side effects, they can be safely rerun multiple times to calculate the next step. Workflow function bodies remain intact in workflow mode because they're pure orchestration logic.
 
 **Step functions can be non-deterministic:**
 
@@ -306,7 +318,7 @@ Because workflow functions are deterministic and have no side effects, they can
 
 Learn more about [Workflows and Steps](/docs/foundations/workflows-and-steps).
 
-## ID Generation
+## ID generation
 
 The compiler generates stable IDs for workflows and steps based on file paths and function names:
 
@@ -328,15 +340,15 @@ The compiler generates stable IDs for workflows and steps based on file paths an
   Although IDs can change when files are moved or functions are renamed, Workflow SDK functions assume [atomic versioning](/docs/foundations/versioning) in the World. This means changing IDs won't break old workflows from running, but will prevent runs from being upgraded and will cause your workflow/step names to change in observability across deployments.
 </Callout>
 
-## Framework Integration
+## Framework integration
 
-These transformations are framework-agnostic—they output standard JavaScript that works anywhere.
+These transformations are framework-agnostic. They output standard JavaScript that works anywhere.
 
 **For users**: Your framework handles all transformations automatically. See the [Getting Started](/docs/getting-started) guide for your framework.
 
 **For framework authors**: Learn how to integrate these transformations into your framework in [Building Framework Integrations](/docs/how-it-works/framework-integrations).
 
-## Debugging Transformed Code
+## Debugging transformed code
 
 If you need to debug transformation issues, you can inspect the generated files: