docs: March docs audit and alignment (#1466)

* docs: clarify Next monorepo setup

Prevent confusion when Next.js apps live below the repository root and workflow code imports sibling workspace packages.

This documents the output tracing root requirement at the point where users configure withWorkflow, so monorepo setups follow the same working patterns as the shipped Next.js integration instead of failing due to unresolved workspace imports.

Ploop-Iter: 1

* ploop: iteration 2 checkpoint

Automated checkpoint commit.

Ploop-Iter: 2

* ploop: iteration 3 checkpoint

Automated checkpoint commit.

Ploop-Iter: 3

* docs: audit recent documentation coverage

Capture recent workflow documentation updates so the public docs and package guidance stay aligned with the implementation and current docs-typecheck behavior.

Ploop-Iter: 1

* docs: align docs-typecheck docs

Document the current docs verification contract so contributors do not assume JavaScript examples are type-checked when only TypeScript snippets are enforced today.

Add regression coverage around the README language and framework integration guidance to keep those docs aligned with the implemented Next.js and docs-typecheck behavior as future changes land.

Ploop-Iter: 2

* docs: add start() troubleshooting guidance

Document the most common causes of the invalid workflow function error so users can resolve start() failures from the API docs and Next.js setup flow without having to infer build-time requirements from runtime behavior.

Keep the new troubleshooting page aligned with the shipped runtime message and add regression coverage so future wording or cross-link changes do not silently break that guidance.

Ploop-Iter: 3

* docs: align NestJS setup docs

Document both supported NestJS module formats and add a regression check so the getting-started guide stays aligned with the package README as the integration evolves.

Ploop-Iter: 1

* docs: tighten NestJS CommonJS guidance

Keep the NestJS getting-started guide consistent across the ESM and CommonJS paths so readers do not mix module settings or import styles mid-setup.

Strengthen the docs regression coverage around the later guide sections so future edits are more likely to preserve the supported CommonJS path documented in the package README.

Ploop-Iter: 2

* docs: align docs with recent workflow guidance

Document the recently added troubleshooting and observability patterns so the public docs stay aligned with the behavior users now encounter in practice.

This keeps the NestJS guide, workflow API reference, and docs regression coverage in sync with the runtime-facing guidance from recent changes.

Ploop-Iter: 3

* docs: audit docs coverage

Why: keep the docs aligned with recent API and runtime behavior changes so examples and reference pages don’t drift from the supported surface.

Ploop-Iter: 1

* test: add docs audit guards

Add regression coverage for doc surfaces that are easy to drift from implementation so docs audits catch mismatches early and keep published guidance aligned with the supported API surface.

Ploop-Iter: 2

* docs: add docs audit guards

Keep new observability and server-testing guidance anchored to machine-readable interfaces so follow-up implementation changes do not silently drift away from the documented agent and automation patterns.

Ploop-Iter: 3

* docs: align observability troubleshooting guidance

Keep the docs consistent so users get the same guidance when debugging hook token collisions and correlating workflow events with platform logs.

This prevents the event-sourcing reference from drifting away from the observability and error docs, and adds guard tests to catch regressions.

Ploop-Iter: 1

* Remove the unreferenced image file img-a-clean-minimal-technical-architecture-d-2026-02-27T14-07-52-1.png from the repo root, workbench/fastify/public/index.html (a Nitro example mistakenly placed in the fastify workbench by a ploop checkpoint), all .claude/worktrees/* submodule references, and all 15 string-presence audit guard tests in packages/docs-typecheck/src/__tests__/ (they only assert keyword presence, not semantic correctness). None of these belong in the docs audit PR.

* Address all PR #1466 review feedback from VaguelySerious, pranaygp, and ijjk:

1. Remove the "Machine-Readable Surfaces" section from docs/content/docs/observability/index.mdx (reviewers say it's unnecessary and already in world docs)
2. Remove all @skip-typecheck annotations from durable-agent.mdx (8) and server-based.mdx (1) — types exist in built packages/ai/dist after pnpm build
3. In durable-agent.mdx, change "machine-readable tool activity" to "tool call details" in the stream() return description
4. In durable-agent.mdx "Aborting Long-Running Streams" section, add a warning callout that abortSignal is not yet supported (blocked by #1301), recommend timeout instead
5. In event-sourcing.mdx, update requestId description: "On Vercel, requestId is the platform request ID when available. Other worlds are not expected to provide a requestId."
6. In get-world.mdx, change "user-friendly names from the machine-readable workflowName field" to "human-readable names from the workflowName field"
7. In start-invalid-workflow-function.mdx, add "// Does NOT work" comment above the bad example line
8. In with-workflow.mdx: reframe outputFileTracingRoot as a workaround (Next.js auto-detects by default per ijjk); change options description from "control local development behavior" to "configure the Next.js integration"; scope the callout to "workflows.local options only affect local development"
9. Drop the withWorkflow() options callout from docs/content/docs/getting-started/next.mdx
10. Remove the Next.js-specific outputFileTracingRoot callout from framework-integrations.mdx
11. Add a Troubleshooting section with the start() invalid-workflow-function error to all 9 non-Next getting-started guides (astro, express, fastify, hono, nestjs, nitro, nuxt, sveltekit, vite), each with framework-appropriate config check in point 2

* docs: absorb unique accuracy fixes from PR #1200

Cherry-picked 6 still-needed fixes from #1200 that aren't covered by
this audit PR or #1516:
- Fix npx workflow description (observability)
- Remove fetch from restricted modules list (errors)
- Fix package name @workflow-worlds/postgres → @workflow/world-postgres (deploying)
- Fix stream wording (foundations/starting-workflows)
- Fix import path simple → simple-streaming (foundations/streaming)
- Add close(), getEncryptionKeyForRun(), writeToStreamMulti() to World interface,
  update create() and streamer signatures (deploying/building-a-world)

* docs: address review feedback on March docs audit

- durable-agent.mdx: "structured tool activity" → "tool call information"
  per VaguelySerious's suggestion
- next.mdx: drop monorepo callout from getting-started per pranaygp
  (too much context too early; info is in withWorkflow API ref)

* docs: fix 2 typecheck failures in encryption and nestjs guides

- encryption.mdx: add skip-typecheck for interface signature block
  (getEncryptionKeyForRun overloads are not runnable code)
- nestjs.mdx: add skip-typecheck for WorkflowModule.forRoot config
  snippet (fragment inside callout, full import shown above)

Verified: pnpm vitest run passes 300/300 in docs-typecheck.

Author: johnlindquist

docs/content/docs/api-reference/workflow-ai/durable-agent.mdx

@@ -213,7 +213,7 @@ export default OutputSpecification;`}
 - Tools can use core library features like `sleep()` and Hooks within their `execute` functions
 - The agent processes tool calls iteratively until completion or `maxSteps` is reached
 - **Default `maxSteps` is unlimited** - set a value to limit the number of LLM calls
-- The `stream()` method returns `{ messages, steps, experimental_output, uiMessages }` containing the full conversation history, step details, optional structured output, and optionally accumulated UI messages
+- The `stream()` method returns `{ messages, steps, toolCalls, toolResults, experimental_output, uiMessages }` containing the full conversation history, step details, tool call details, optional structured output, and optionally accumulated UI messages
 - Use `collectUIMessages: true` to accumulate `UIMessage[]` during streaming, useful for persisting conversation state without re-reading the stream
 - The `prepareStep` callback runs before each step and can modify model, messages, generation settings, tool choice, and context
 - Generation settings (temperature, maxOutputTokens, etc.) can be set on the constructor and overridden per-stream call
@@ -842,6 +842,91 @@ async function saveConversation(messages: UIMessage[]) {
 The `uiMessages` property is only available when `collectUIMessages` is set to `true`. When disabled, `uiMessages` is `undefined`.
 </Callout>
 
+### Machine-Readable Tool Results
+
+`stream()` returns tool call information you can inspect programmatically. Compare `toolCalls` with `toolResults` to find unresolved tool calls that need client-side handling:
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import { z } from "zod";
+import type { UIMessageChunk } from "ai";
+
+async function checkOrderStatus({ orderId }: { orderId: string }) {
+  "use step";
+  return `Order ${orderId}: shipped`;
+}
+
+async function agentWithToolInspection(userMessage: string) {
+  "use workflow";
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-haiku-4.5",
+    tools: {
+      checkOrderStatus: {
+        description: "Check order status",
+        inputSchema: z.object({ orderId: z.string() }),
+        execute: checkOrderStatus,
+      },
+    },
+  });
+
+  const result = await agent.stream({
+    messages: [{ role: "user", content: userMessage }],
+    writable: getWritable<UIMessageChunk>(),
+  });
+
+  const unresolved = result.toolCalls.filter( // [!code highlight]
+    (tc) => !result.toolResults.some((tr) => tr.toolCallId === tc.toolCallId) // [!code highlight]
+  ); // [!code highlight]
+
+  if (unresolved.length > 0) {
+    return {
+      status: "needs-client-tools",
+      unresolved,
+    };
+  }
+
+  return {
+    status: "complete",
+    messages: result.messages,
+    toolResults: result.toolResults,
+  };
+}
+```
+
+<Callout type="info">
+`toolCalls` and `toolResults` reflect the *last step* of the agent loop. Tools without an `execute` function will appear in `toolCalls` but not in `toolResults`, which is how you detect calls that need client-side handling.
+</Callout>
+
+### Aborting Long-Running Streams
+
+Use `timeout` to abort a stream automatically after a fixed duration:
+
+<Callout type="warn">
+`abortSignal` is not yet supported and will be available in a future release. Use `timeout` for now.
+</Callout>
+
+```typescript lineNumbers
+import { DurableAgent } from "@workflow/ai/agent";
+import { getWritable } from "workflow";
+import type { UIMessageChunk } from "ai";
+
+async function agentWithTimeout(userMessage: string) {
+  "use workflow";
+
+  const agent = new DurableAgent({
+    model: "anthropic/claude-haiku-4.5",
+  });
+
+  await agent.stream({
+    messages: [{ role: "user", content: userMessage }],
+    writable: getWritable<UIMessageChunk>(),
+    timeout: 30_000, // [!code highlight]
+  });
+}
+```
+
 ## See Also
 
 - [Building Durable AI Agents](/docs/ai) - Complete guide to creating durable agents

docs/content/docs/api-reference/workflow-api/get-world.mdx

@@ -66,6 +66,57 @@ const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highl
 
 See [Observability Utilities](/docs/api-reference/workflow-api/world/observability) for the full hydration, parsing, and encryption API.
 
+### List Workflow Runs (Display Names)
+
+List workflow runs and derive human-readable names from the `workflowName` field:
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { parseWorkflowName } from "@workflow/utils/parse-name"; // [!code highlight]
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const cursor = url.searchParams.get("cursor") ?? undefined;
+
+  try {
+    const world = getWorld(); // [!code highlight]
+    const runs = await world.runs.list({
+      pagination: { cursor },
+      resolveData: "none",
+    });
+
+    return Response.json({
+      data: runs.data.map((run) => {
+        const parsed = parseWorkflowName(run.workflowName); // [!code highlight]
+
+        return {
+          runId: run.runId,
+          // Use shortName for UI display (e.g., "processOrder") // [!code highlight]
+          displayName: parsed?.shortName ?? run.workflowName, // [!code highlight]
+          // Module info available for debugging // [!code highlight]
+          module: parsed?.moduleSpecifier, // [!code highlight]
+          status: run.status,
+          startedAt: run.startedAt,
+          completedAt: run.completedAt,
+        };
+      }),
+      cursor: runs.cursor,
+    });
+  } catch (error) {
+    return Response.json(
+      { error: "Failed to list workflow runs" },
+      { status: 500 }
+    );
+  }
+}
+```
+
+<Callout type="info">
+  The `workflowName` field contains a machine-readable identifier like `workflow//./src/workflows/order//processOrder`.
+  Use `parseWorkflowName()` from `@workflow/utils/parse-name` to extract the `shortName` (e.g., `"processOrder"`)
+  and `moduleSpecifier` for display in your UI.
+</Callout>
+
 ## Related Functions
 
 - [`getRun()`](/docs/api-reference/workflow-api/get-run) - Higher-level API for working with individual runs by ID.

docs/content/docs/api-reference/workflow-api/start.mdx

@@ -56,6 +56,10 @@ Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-
 * All arguments must be [serializable](/docs/foundations/serialization).
 * When `deploymentId` is provided, the argument types and return type become `unknown` since there is no guarantee the workflow function's types will be consistent across different deployments.
 
+<Callout type="info">
+If `start()` throws `'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.`, the passed function was not transformed as a workflow. The two most common causes are a missing `"use workflow"` directive or missing framework integration. See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function).
+</Callout>
+
 ## Examples
 
 ### With Arguments

docs/content/docs/api-reference/workflow-next/with-workflow.mdx

@@ -27,6 +27,57 @@ const workflowConfig = {}
 export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]
 ```
 
+### Monorepos and Workspace Imports
+
+By default, Next.js detects the correct workspace root automatically. If your Next.js app lives in a subdirectory such as `apps/web` and workspace resolution is not working correctly, you can set `outputFileTracingRoot` as a workaround:
+
+```typescript title="apps/web/next.config.ts" lineNumbers
+import { resolve } from "node:path";
+import type { NextConfig } from "next";
+import { withWorkflow } from "workflow/next";
+
+const nextConfig: NextConfig = {
+  outputFileTracingRoot: resolve(process.cwd(), "../.."),
+};
+
+export default withWorkflow(nextConfig);
+```
+
+<Callout type="info">
+Use the smallest directory that contains every workspace package imported by your workflows. If your app already lives at the repository root, you do not need to set `outputFileTracingRoot`.
+</Callout>
+
+## Options
+
+`withWorkflow` accepts an optional second argument to configure the Next.js integration.
+
+```typescript title="next.config.ts" lineNumbers
+import type { NextConfig } from "next";
+import { withWorkflow } from "workflow/next";
+
+const nextConfig: NextConfig = {};
+
+export default withWorkflow(nextConfig, {
+  workflows: {
+    lazyDiscovery: true,
+    local: {
+      port: 4000,
+    },
+  },
+});
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `workflows.lazyDiscovery` | `boolean` | `false` | When `true`, defers workflow discovery until files are requested instead of scanning eagerly at startup. Useful for large projects where startup time matters. |
+| `workflows.local.port` | `number` | — | Overrides the `PORT` environment variable for local development. Has no effect when deployed to Vercel. |
+
+<Callout type="info">
+The `workflows.local` options only affect local development. When deployed to Vercel, the runtime ignores `local` settings and uses the Vercel world automatically.
+</Callout>
+
+## Exporting a Function
+
 If you are exporting a function in your `next.config` you will need to ensure you call the function returned from `withWorkflow`.
 
 ```typescript title="next.config.ts" lineNumbers

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

@@ -34,10 +34,13 @@ A World connects workflows to the infrastructure that powers them. The World int
 ```typescript
 interface World extends Storage, Queue, Streamer {
   start?(): Promise<void>;
+  close?(): Promise<void>;
+  getEncryptionKeyForRun?(run: WorkflowRun): Promise<Uint8Array | undefined>;
+  getEncryptionKeyForRun?(runId: string, context?: Record<string, unknown>): Promise<Uint8Array | undefined>;
 }
 ```
 
-The optional `start()` method initializes any background tasks needed by your World (e.g., queue polling).
+The optional `start()` method initializes background tasks (for example, queue polling). The optional `close()` method releases resources like connection pools and listeners. The optional `getEncryptionKeyForRun()` method returns the AES-256 key used to encrypt data for a run; if it is not implemented, encryption is disabled.
 
 ## The Event Log Model
 
@@ -63,8 +66,8 @@ interface Storage {
   };
 
   events: {
-    // Create a new workflow run (runId must be null - server generates it)
-    create(runId: null, data: RunCreatedEventRequest, params?: CreateEventParams): Promise<EventResult>;
+    // Create a new workflow run (runId may be client-provided or null for server generation)
+    create(runId: string | null, data: RunCreatedEventRequest, params?: CreateEventParams): Promise<EventResult>;
 
     // Create an event for an existing run
     create(runId: string, data: CreateEventRequest, params?: CreateEventParams): Promise<EventResult>;
@@ -88,7 +91,7 @@ interface Storage {
 2. Atomically update the affected entity (run, step, or hook)
 3. Return both the created event and the updated entity
 
-**Run Creation:** For `run_created` events, the `runId` parameter is `null`. Your World generates and returns a new `runId`.
+**Run Creation:** For `run_created` events, the `runId` parameter may be a client-provided string or `null`. When `null`, your World generates and returns a new `runId`.
 
 **Hook Tokens:** Hook tokens must be unique. If a `hook_created` event conflicts with an existing token, return a `hook_conflict` event instead.
 
@@ -165,13 +168,19 @@ The Streamer interface enables real-time data streaming:
 interface Streamer {
   writeToStream(
     name: string,
-    runId: string | Promise<string>,
+    runId: string,
     chunk: string | Uint8Array
   ): Promise<void>;
 
+  writeToStreamMulti?(
+    name: string,
+    runId: string,
+    chunks: (string | Uint8Array)[]
+  ): Promise<void>;
+
   closeStream(
     name: string,
-    runId: string | Promise<string>
+    runId: string
   ): Promise<void>;
 
   readFromStream(
@@ -202,6 +211,7 @@ interface Streamer {
 ```
 
 Streams are identified by a combination of `runId` and `name`. Each workflow run can have multiple named streams.
+`writeToStreamMulti()` is an optional optimization for batching multiple writes.
 
 `getStreamChunks` returns a paginated snapshot of currently available chunks (unlike `readFromStream` which returns a live `ReadableStream` that waits for new chunks). `getStreamInfo` returns the tail index (last chunk index, 0-based, or `-1` when empty) and whether the stream is complete — useful for resolving negative `startIndex` values into absolute positions.
 

docs/content/docs/deploying/index.mdx

@@ -73,7 +73,7 @@ For self-hosting or deploying to other cloud providers, you can use community-ma
 To use a different World implementation, set the `WORKFLOW_TARGET_WORLD` environment variable:
 
 ```bash
-export WORKFLOW_TARGET_WORLD=@workflow-worlds/postgres
+export WORKFLOW_TARGET_WORLD=@workflow/world-postgres
 # Plus any world-specific configuration
 export DATABASE_URL=postgres://...
 ```
@@ -89,7 +89,7 @@ The [Observability tools](/docs/observability) work with any World backend. By d
 npx workflow inspect runs
 
 # Inspect remote workflows
-npx workflow inspect runs --backend @workflow-worlds/postgres
+npx workflow inspect runs --backend @workflow/world-postgres
 ```
 
 Learn more about [Observability](/docs/observability) tools.

docs/content/docs/errors/hook-conflict.mdx

@@ -15,7 +15,7 @@ This error occurs when you try to create a hook with a token that is already in
 ## Error Message
 
 ```
-Hook token conflict: Hook with token <token> already exists for this project
+Hook token "<token>" is already in use by another workflow
 ```
 
 ## Why This Happens

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

@@ -69,7 +69,7 @@ async function read(filePath: string) {
 These common Node.js core modules cannot be used in workflow functions:
 
 - File system: `fs`, `path`
-- Network: `http`, `https`, `net`, `dns`, `fetch`
+- Network: `http`, `https`, `net`, `dns`
 - Process: `child_process`, `cluster`
 - Crypto: `crypto` (use Web Crypto API instead)
 - Operating system: `os`