docs: add workflow migration guides and skill (#1584)

* docs: add workflow migration guides and migration skill

Create migration guides for AWS Step Functions, Inngest, and Temporal under
docs/content/docs/getting-started/. Each guide provides side-by-side code
comparisons and a realistic order-processing saga example.

Add skills/migrating-to-vercel-workflow/ with SKILL.md, reference docs for
each source platform (aws-step-functions, inngest, temporal), shared patterns,
resume routing, runtime targets, and 5 eval scenarios.

Update create-webhook API reference with webhook resume choice clarifications.
Update getting-started meta.json to include migration guide navigation entries.

* In PR #1584 (migration-guides branch), make two changes to the migration guides:

1. Move migration guides to a top-level "Migration Guides" nav section:
   - Create docs/content/docs/migration-guides/ directory
   - Move the 3 migrating-from-*.mdx files from getting-started/ into migration-guides/
   - Create migration-guides/meta.json with title "Migration Guides" listing temporal, inngest, aws-step-functions
   - Add "migration-guides" between "errors" and "api-reference" in docs/content/docs/meta.json
   - Remove the 3 migration entries from getting-started/meta.json

2. Replace all "Vercel Workflow" language with "Workflow SDK" across docs and skills:
   - In all 3 MDX migration guides: replace "Vercel Workflow" with "the Workflow SDK" or "Workflow SDK" in frontmatter, headings, table headers, and body text
   - Replace "shipping on Vercel" with neutral phrasing, "Vercel-managed execution" with "managed execution", "Vercel's infrastructure" with neutral phrasing
   - Replace Vercel-specific pricing paragraphs with generic "Efficient resource usage" bullet
   - Replace "Deploy to Vercel first..." checklist items with neutral deployment guidance
   - Keep vercel-world prerequisite links (real package name)
   - Rename skills/migrating-to-vercel-workflow/ to skills/migrating-to-workflow-sdk/
   - Update all skill SKILL.md, evals/, and references/ files to replace "Vercel Workflow" with "Workflow SDK"
   - Update runtime-targets.md section headers from "Non-Vercel" to "Self-hosted"

* fix type checks

---------

Co-authored-by: Karthik Kalyanaraman <karthik.kalyanaraman@vercel.com>

Author: johnlindquist

docs/content/docs/api-reference/workflow/create-webhook.mdx

@@ -55,9 +55,25 @@ The returned `Webhook` object has:
 
 - `url`: The HTTP endpoint URL that external systems can call
 - `token`: The unique token identifying this webhook
-- Implements `AsyncIterable<RequestWithResponse>` for handling multiple requests
+- Implements `AsyncIterable<T>` for handling multiple requests, where `T` is `Request` (default) or `RequestWithResponse` (manual mode)
 
-The `RequestWithResponse` type extends the standard `Request` interface with a `respondWith(response: Response)` method for sending custom responses back to the caller.
+When using `createWebhook({ respondWith: 'manual' })`, the resolved request type is `RequestWithResponse`, which extends the standard `Request` interface with a `respondWith(response: Response): Promise<void>` method for sending custom responses back to the caller.
+
+<Callout type="info">
+Use the simplest option that satisfies the prompt:
+
+- `createWebhook()` — generated callback URL, and the default `202 Accepted` response is fine
+- `createWebhook({ respondWith: 'manual' })` — generated callback URL, but you must send a custom body, status, or headers
+- `createHook()` + `resumeHook()` — the app resumes from server-side code with a deterministic business token instead of a generated callback URL
+</Callout>
+
+<details>
+<summary>Common wrong turns</summary>
+
+- Do not use `respondWith: 'manual'` just because the flow has a callback URL.
+- Do not use `RequestWithResponse` unless you chose manual mode.
+- Do not invent a custom callback route when `webhook.url` is the intended callback surface.
+</details>
 
 ## Examples
 
@@ -84,27 +100,29 @@ export async function basicWebhookWorkflow() {
 }
 ```
 
-### Responding to Webhook Requests
+### Responding to Webhook Requests (Manual Mode)
+
+Use this section only when the caller requires a non-default HTTP response. If `202 Accepted` is acceptable, use `createWebhook()` without `respondWith: "manual"`.
 
-Use the `respondWith()` method to send custom HTTP responses. Note that `respondWith()` must be called from within a step function:
+Pass `{ respondWith: "manual" }` to get a `RequestWithResponse` object with a `respondWith()` method. Note that `respondWith()` must be called from within a step function:
 
 ```typescript lineNumbers
 import { createWebhook, type RequestWithResponse } from "workflow"
 
-async function sendResponse(request: RequestWithResponse) { // [!code highlight]
-  "use step"; // [!code highlight]
-  await request.respondWith( // [!code highlight]
-    new Response(JSON.stringify({ success: true, message: "Received!" }), { // [!code highlight]
-      status: 200, // [!code highlight]
-      headers: { "Content-Type": "application/json" } // [!code highlight]
-    }) // [!code highlight]
-  ); // [!code highlight]
-} // [!code highlight]
+async function sendResponse(request: RequestWithResponse): Promise<void> {
+  "use step";
+  await request.respondWith(
+    new Response(JSON.stringify({ success: true, message: "Received!" }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" }
+    })
+  );
+}
 
 export async function respondingWebhookWorkflow() {
   "use workflow";
 
-  using webhook = createWebhook();
+  using webhook = createWebhook({ respondWith: "manual" });
   console.log("Webhook URL:", webhook.url);
 
   const request = await webhook;
@@ -117,7 +135,7 @@ export async function respondingWebhookWorkflow() {
   await processData(data);
 }
 
-async function processData(data: any) {
+async function processData(data: any): Promise<void> {
   "use step";
   // Process the webhook data
   console.log("Processing:", data);
@@ -165,6 +183,7 @@ export async function eventCollectorWorkflow() {
 
 ## Related Functions
 
-- [`createHook()`](/docs/api-reference/workflow/create-hook) - Lower-level hook primitive for arbitrary payloads
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper
-- [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) - Resume a webhook from an API route
+- [`createHook()`](/docs/api-reference/workflow/create-hook) — Use when the app resumes from server-side code with a deterministic business token.
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) — Pairs with `createHook()` for deterministic server-side resume.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) — Type-safe hook helper.
+- [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) — Low-level runtime API. Most integrations should call `webhook.url` directly instead of adding a custom callback route.

docs/content/docs/meta.json

@@ -10,6 +10,7 @@
     "testing",
     "deploying",
     "errors",
+    "migration-guides",
     "api-reference"
   ]
 }

docs/content/docs/migration-guides/index.mdx

@@ -0,0 +1,23 @@
+---
+title: Migration Guides
+description: Move your existing durable workflow system to the Workflow SDK with side-by-side code comparisons and realistic migration examples.
+type: overview
+summary: Migrate from Temporal, Inngest, or AWS Step Functions to the Workflow SDK.
+related:
+  - /docs/foundations/workflows-and-steps
+  - /docs/getting-started
+---
+
+Migrate your existing orchestration system to the Workflow SDK. Each guide includes concept mappings, side-by-side code comparisons, and a full end-to-end migration example.
+
+<Cards>
+    <Card href="/docs/migration-guides/migrating-from-temporal" title="Migrating from Temporal">
+        Replace Activities, Workers, Signals, and Child Workflows with Workflows, Steps, Hooks, and start()/getRun().
+    </Card>
+    <Card href="/docs/migration-guides/migrating-from-inngest" title="Migrating from Inngest">
+        Replace createFunction, step.run(), step.sleep(), step.waitForEvent(), and step.invoke() with Workflows, Steps, and Hooks.
+    </Card>
+    <Card href="/docs/migration-guides/migrating-from-aws-step-functions" title="Migrating from AWS Step Functions">
+        Replace JSON state definitions, Task/Choice/Wait/Parallel states, and .waitForTaskToken callbacks with idiomatic TypeScript.
+    </Card>
+</Cards>

docs/content/docs/migration-guides/meta.json

@@ -0,0 +1,8 @@
+{
+  "title": "Migration Guides",
+  "pages": [
+    "migrating-from-temporal",
+    "migrating-from-inngest",
+    "migrating-from-aws-step-functions"
+  ]
+}