docs(cookbook): rewrite core recipes, dedupe, and reorder sidebar

[karthikscale3]

Pass over the cookbook focused on correctness, concrete examples, and tighter information architecture.

Rewrites

• Saga / Batching / Scheduling — rewrote around concrete use cases (order fulfillment, CSV import, cancellable drip campaign); each page now has When to use / How it works / Adapting to your use case sections and drops abstract/variation noise.
• Durable Agent / Human-in-the-Loop / Agent Cancellation — fixed broken patterns: tool invocations don't stream to the client before the tool returns (so prepareStep flag-checking and state === "call" tricks never fire). Replaced with Promise.race(stream, hook) + explicit emit* steps that write custom data parts (data-approval-needed, data-approval-resolved, data-stopped) to the durable stream.
• Agent Cancellation (agent-patterns/agent-cancellation.mdx, formerly stop-workflow.mdx) — renamed from "Stop Workflow" → "Agent Stop Signal" → "Agent Cancellation" and broadened to cover two named patterns as equal-weight peers: Hard Cancellation via getRun(runId).cancel() for forced termination, and Stop Signal via a hook + Promise.race for a graceful exit with cleanup and final stream notification (data-stopped part). The page opens with a ## Choosing an approach comparison hub (bullets + 7-row trade-off table covering mechanism, speed, cleanup behavior, stream notification, return-value semantics, code complexity, and recommended use case) before the per-pattern deep dives. A <Callout type="warn"> scoped to the Stop Signal section documents that the underlying model stream isn't cancelled — tokens generated after the signal still bill — and cross-links to Distributed Abort Controller for hard cross-process cancellation. Removed the misleading "Cost control" use case from "When to use this".
• AI SDK integration (integrations/ai-sdk.mdx) — refocused from a DurableAgent showcase to lower-level streamText(); main example is a multi-turn session pattern (one workflow run per conversation, hook created once, durable stream sliced per turn via manual pumping). Added deep links to ai-sdk.dev for each primitive and a dedicated Pitfalls section (snapshot tailIndex before resuming the hook; don't call writable.close() in a workflow function; release — don't cancel — the source reader).
• Sandbox integration (integrations/sandbox.mdx) — rewrote around the real @vercel/sandbox SDK surface (previous page had multiple API errors: template → runtime, sandbox.id → sandbox.sandboxId, destroy() doesn't exist). Flagship pattern is now one workflow run = one persistent sandbox session that outlives the 5-hour hard cap via proactive snapshot + recreate. Links out to Open Agents as the canonical adopter.
• Chat SDK integration (integrations/chat-sdk.mdx) — full rewrite. Previous page was titled "Chat SDK" but documented AI SDK's useChat primitive and was effectively a duplicate of the AI SDK page. New page targets chat-sdk.dev (unified Slack / Teams / Discord / Telegram / GitHub / Linear / WhatsApp / Google Chat bot SDK) and shows how Workflow makes its sessions durable via one-workflow-run-per-thread + hook-driven inbound message routing. Uses a Mermaid flowchart TD (ASCII diagrams alias visibly at the site's rendered line-height).
• Publishing Libraries (advanced/publishing-libraries.mdx) — swapped the ASCII file tree for Fumadocs <Files> / <Folder> / <File> components (font-independent SVG). Corrected the isomorphic-packages callout: "use workflow" / "use step" directives are safe in library source — they're string expression statements and no-op when the SWC plugin doesn't process them. Added Mux AI and World ID adopter examples with canonical blog links.

New cookbook recipes (foundations → cookbook migration)

The foundations/common-patterns.mdx page mixed three independent topics (timeouts, sequential/parallel execution, workflow composition) and lived in the foundations section despite being recipe-shaped content. Split into three dedicated cookbook pages under common-patterns/, each with the standard cookbook frame (When to use this / How it works / Adapting to your use case / Key APIs):

• common-patterns/timeouts.mdx — soft timeouts via Promise.race(operation, sleep(deadline)) with discriminated result tagging. Examples for slow steps and webhook deadlines. <Callout type="warn"> documenting that Promise.race doesn't cancel the losing branch (matters for side-effecting or expensive operations) — same caveat as the Agent Cancellation page, cross-linked to Distributed Abort Controller for hard cross-process cancellation.
• common-patterns/sequential-and-parallel.mdx — sequential pipelines, Promise.all / Promise.allSettled for parallel fan-out, and Promise.race for first-wins between webhooks and timers. Includes the full Birthday Card Generator demo as the integrated example.
• common-patterns/workflow-composition.mdx — composing workflows from other workflows. Covers both direct await (the parent flattens the child's events into its own log) and background execution via start() (the child runs as an independent run with its own runId). Comparison table contrasting the two and a deploymentId: "latest" note for cross-deployment composition.

The original foundations/common-patterns.mdx is deleted; a permanent redirect from /docs/foundations/common-patterns → /cookbook lands callers on the cookbook overview where the three split pages are linked.

Deletions (redundant or flawed)

• Fan-Out & Parallel Delivery, Conditional Routing — redundant with Batching / not workflow-specific.
• Tool Streaming, Tool Orchestration — already covered by foundations/streaming and ai/defining-tools in the main docs.
• Durable Objects — correctness bugs (hook.create() inside a while(true) throws HookConflictError; counter example's read path doesn't return a value to the caller). Framing ("workflow run = entity with methods") doesn't hold up — start() mints its own runId so you still need an external entity → runId map.
• Custom Serialization — redundant with foundations/serialization. The one unique detail (class registry symbol name) was folded into the foundations page.
• Isomorphic Packages — merged into publishing-libraries.mdx; overlap was already large (peer-dep snippet + runtime-detection snippet) and both targeted npm library authors.
• foundations/common-patterns.mdx — replaced by the three dedicated cookbook recipes above.

Sidebar restructure

• Reordered categories: Overview → Agent Patterns → Common Patterns → Integrations → Advanced (was Overview → Common → Agent → Integrations → Advanced). Agent Patterns leads since it drives most new-visitor traffic.
• Moved Child Workflows and Distributed Abort Controller from common-patterns/ to advanced/ — they're composition / cancellation concerns, not common reliability recipes.
• Removed Common Patterns from the foundations sidebar after the migration above; foundations/index.mdx and foundations/starting-workflows.mdx updated to point at the cookbook for follow-ups instead of the deleted foundations page.
• File moves used git mv so rename history survives git log --follow.

Redirects

Permanent redirects added in next.config.ts so no inbound links 404 — covers search indexes, bookmarks, and external references in the workflow-init skill and CI smoke tests:

• /cookbook/agent-patterns/stop-workflow → /cookbook/agent-patterns/agent-cancellation
• /cookbook/agent-patterns/agent-stop-signal → /cookbook/agent-patterns/agent-cancellation
• /cookbook/common-patterns/child-workflows → /cookbook/advanced/child-workflows
• /cookbook/common-patterns/distributed-abort-controller → /cookbook/advanced/distributed-abort-controller
• /docs/foundations/common-patterns → /cookbook
• /docs/foundations/control-flow-patterns → /cookbook (existing redirect updated to point at the cookbook overview)

Both prior URLs for the renamed agent cancellation page redirect directly to the current location — no chain hops.

Made with Cursor