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

Author: johnlindquist

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

@@ -17,8 +17,6 @@ The `DurableAgent` class enables you to create AI-powered agents that can mainta
 
 Tool calls can be implemented as workflow steps for automatic retries, or as regular workflow-level logic utilizing core library features such as [`sleep()`](/docs/api-reference/workflow/sleep) and [Hooks](/docs/foundations/hooks).
 
-{/* @skip-typecheck - uses DurableAgentOptions properties not yet in published dist types */}
-
 ```typescript lineNumbers
 import { DurableAgent } from "@workflow/ai/agent";
 import { getWritable } from "workflow";
@@ -215,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, toolCalls, toolResults, experimental_output, uiMessages }` containing the full conversation history, per-step details, machine-readable tool activity, 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
@@ -226,8 +224,6 @@ export default OutputSpecification;`}
 
 ### Basic Agent with Tools
 
-{/* @skip-typecheck - uses DurableAgentOptions.instructions not yet in published dist types */}
-
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
 import { getWritable } from "workflow";
@@ -442,8 +438,6 @@ async function agentWithLibraryFeaturesWorkflow(userRequest: string) {
 
 Use `prepareStep` to modify settings before each step in the agent loop:
 
-{/* @skip-typecheck - uses DurableAgentStreamOptions.prepareStep not yet in published dist types */}
-
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
 import { getWritable } from "workflow";
@@ -488,8 +482,6 @@ async function agentWithPrepareStep(userMessage: string) {
 
 Inject messages from external sources (like hooks) before each LLM call:
 
-{/* @skip-typecheck - uses DurableAgentStreamOptions.prepareStep not yet in published dist types */}
-
 ```typescript
 import { DurableAgent } from "@workflow/ai/agent";
 import { getWritable, defineHook } from "workflow";
@@ -670,8 +662,6 @@ async function agentWithCallbacks() {
 
 Parse structured data from the LLM response using `Output.object`:
 
-{/* @skip-typecheck - uses OutputSpecification not yet in published dist types */}
-
 ```typescript
 import { DurableAgent, Output } from "@workflow/ai/agent";
 import { getWritable } from "workflow";
@@ -814,8 +804,6 @@ async function agentWithContext(userId: string) {
 
 Use `collectUIMessages` to accumulate `UIMessage[]` during streaming. This is useful when you need to persist the conversation without re-reading the run's output stream:
 
-{/* @skip-typecheck - uses collectUIMessages/uiMessages not yet in published dist types */}
-
 ```typescript lineNumbers
 import { DurableAgent } from "@workflow/ai/agent";
 import { getWritable } from "workflow";
@@ -858,8 +846,6 @@ The `uiMessages` property is only available when `collectUIMessages` is set to `
 
 `stream()` returns structured tool activity you can inspect programmatically. Compare `toolCalls` with `toolResults` to find unresolved tool calls that need client-side handling:
 
-{/* @skip-typecheck - uses toolCalls/toolResults not yet in published dist types */}
-
 ```typescript lineNumbers
 import { DurableAgent } from "@workflow/ai/agent";
 import { getWritable } from "workflow";
@@ -915,9 +901,11 @@ async function agentWithToolInspection(userMessage: string) {
 
 ### Aborting Long-Running Streams
 
-Use `timeout` to abort a stream automatically after a fixed duration. If both `timeout` and `abortSignal` are provided, whichever triggers first will abort the operation:
+Use `timeout` to abort a stream automatically after a fixed duration:
 
-{/* @skip-typecheck - uses DurableAgentStreamOptions.timeout not yet in published dist types */}
+<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";

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

@@ -198,7 +198,7 @@ export async function GET(req: Request) {
 
 ### List Workflow Runs (Display Names)
 
-List workflow runs and derive user-friendly names from the machine-readable `workflowName` field:
+List workflow runs and derive human-readable names from the `workflowName` field:
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";

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

@@ -29,7 +29,7 @@ export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]
 
 ### Monorepos and Workspace Imports
 
-If your Next.js app lives in a subdirectory such as `apps/web` and your workflows import code from sibling workspace packages, set `outputFileTracingRoot` to the workspace root. `withWorkflow()` uses this value as the builder project root so workflow transforms can resolve workspace module specifiers correctly.
+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";
@@ -49,7 +49,7 @@ Use the smallest directory that contains every workspace package imported by you
 
 ## Options
 
-`withWorkflow` accepts an optional second argument to control local development behavior.
+`withWorkflow` accepts an optional second argument to configure the Next.js integration.
 
 ```typescript title="next.config.ts" lineNumbers
 import type { NextConfig } from "next";
@@ -73,7 +73,7 @@ export default withWorkflow(nextConfig, {
 | `workflows.local.port` | `number` | — | Overrides the `PORT` environment variable for local development. Has no effect when deployed to Vercel. |
 
 <Callout type="info">
-These options only affect local development. When deployed to Vercel, the runtime ignores `local` settings and uses the Vercel world automatically.
+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

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

@@ -98,6 +98,7 @@ import { start } from "workflow/api";
 import { sendReminder } from "./workflows/send-reminder";
 
 export async function POST() {
+  // Does NOT work
   await start(async () => sendReminder("hello@example.com"));
   return new Response("ok");
 }

docs/content/docs/getting-started/astro.mdx

@@ -235,6 +235,23 @@ npx astro add vercel
 
 Additionally, check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+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.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your `astro.config.mjs` includes the `workflow()` integration.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 * Learn more about the [Foundations](/docs/foundations).

docs/content/docs/getting-started/express.mdx

@@ -262,6 +262,23 @@ Workflow DevKit apps currently work best when deployed to [Vercel](https://verce
 
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+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.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your Nitro config includes the `workflow/nitro` module.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 - Learn more about the [Foundations](/docs/foundations).

docs/content/docs/getting-started/fastify.mdx

@@ -249,6 +249,23 @@ Workflow DevKit apps currently work best when deployed to [Vercel](https://verce
 
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+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.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your Nitro config includes the `workflow/nitro` module.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 - Learn more about the [Foundations](/docs/foundations).

docs/content/docs/getting-started/hono.mdx

@@ -244,6 +244,23 @@ Workflow DevKit apps currently work best when deployed to [Vercel](https://verce
 
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+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.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your Nitro config includes the `workflow/nitro` module.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 - Learn more about the [Foundations](/docs/foundations).

docs/content/docs/getting-started/nestjs.mdx

@@ -392,6 +392,23 @@ Workflow DevKit apps currently work best when deployed to [Vercel](https://verce
 
 Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
 
+## Troubleshooting
+
+### `start()` says it received an invalid workflow function
+
+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.
+```
+
+Check both of these first:
+
+1. The workflow function includes `"use workflow"`.
+2. Your NestJS app imports and registers the `WorkflowModule`.
+
+See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function) for full examples and fixes.
+
 ## Next Steps
 
 - Learn more about the [Foundations](/docs/foundations).

docs/content/docs/getting-started/next.mdx

@@ -52,10 +52,6 @@ export default withWorkflow(nextConfig); // [!code highlight]
 If your Next.js app lives inside a monorepo and your workflows import code from sibling workspace packages, set `outputFileTracingRoot` to the workspace root. See [`withWorkflow()`](/docs/api-reference/workflow-next/with-workflow#monorepos-and-workspace-imports) for the full example.
 </Callout>
 
-<Callout type="info">
-You can pass a second argument to `withWorkflow()` to control local development behavior, such as enabling lazy workflow discovery or overriding the local port. See [`withWorkflow()` Options](/docs/api-reference/workflow-next/with-workflow#options) for details.
-</Callout>
-
 <Accordion type="single" collapsible>
   <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
     <AccordionTrigger className="text-sm">