Type check all the docs and READMEs (#715)

* Type check all the docs and READMEs

* mdx

DCO Remediation Commit for Malte Ubl <[email protected]>

I, Malte Ubl <[email protected]>, hereby add my Signed-off-by to this commit: f61880c

Signed-off-by: Malte Ubl <[email protected]>

* mdx2

DCO Remediation Commit for Malte Ubl <[email protected]>

I, Malte Ubl <[email protected]>, hereby add my Signed-off-by to this commit: 98dd484

Signed-off-by: Malte Ubl <[email protected]>

* remove temp AI scripts and fix one docs issue

* Fix code review issue

* add empty changeset

---------

Signed-off-by: Malte Ubl <[email protected]>
Co-authored-by: Pranay Prakash <[email protected]>

Author: cramforce

.changeset/bitter-guests-flow.md

@@ -0,0 +1,2 @@
+---
+---

.github/workflows/docs-typecheck.yml

@@ -0,0 +1,46 @@
+name: Docs Typecheck
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "!*"
+  pull_request:
+
+concurrency:
+  # Unique group for this workflow and branch
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  docs-typecheck:
+    name: Documentation Code Samples
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    env:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 10.14.0
+
+      - name: Setup Node.js 22.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: "pnpm"
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build packages
+        run: pnpm build
+
+      - name: Type-check documentation code samples
+        run: pnpm test:docs

docs/content/docs/ai/human-in-the-loop.mdx

@@ -71,6 +71,7 @@ export const bookingApprovalHook = defineHook({
 
 Create a tool that creates a hook instance using the tool call ID as the token. The UI will use this ID to submit the approval.
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript title="workflows/chat/steps/tools.ts" lineNumbers
 import { z } from "zod";
 
@@ -236,6 +237,7 @@ export function BookingApproval({ toolCallId, input, output }: BookingApprovalPr
 
 Use the component we just created to render the tool call and approval controls in your chat interface:
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript title="app/page.tsx" lineNumbers
 // ... existing imports ...
 import { BookingApproval } from "@/components/booking-approval";

docs/content/docs/ai/index.mdx

@@ -78,6 +78,7 @@ OPENAI_API_KEY=...
 
 Then modify your API endpoint to use the OpenAI provider:
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript title="app/api/chat/route.ts" lineNumbers
 // ...
 import { openai } from "@workflow/ai/openai"; // [!code highlight]
@@ -240,6 +241,7 @@ export default withWorkflow(nextConfig);
 
 Move the agent logic into a separate function, which will serve as our workflow definition.
 
+{/* @skip-typecheck: Shows two mutually exclusive model options */}
 ```typescript title="workflows/chat/workflow.ts" lineNumbers
 import { DurableAgent } from "@workflow/ai/agent"; // [!code highlight]
 import { getWritable } from "workflow"; // [!code highlight]
@@ -313,6 +315,7 @@ Key changes:
 
 Mark all tool definitions with `"use step"` to make them durable. This enables automatic retries and observability for each tool call:
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript title="workflows/chat/steps/tools.ts​" lineNumbers
 // ...
 

docs/content/docs/ai/resumable-streams.mdx

@@ -20,6 +20,7 @@ Let's add stream resumption to our Flight Booking Agent that we build in the [Bu
 
 Modify your chat endpoint to include the workflow run ID in a response header. The Run ID uniquely identifies the run's stream, so it allows the client to know which stream to reconnect to.
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript title="app/api/chat/route.ts" lineNumbers
 // ... imports ...
 

docs/content/docs/ai/sleep-and-delays.mdx

@@ -63,6 +63,7 @@ export const flightBookingTools = {
 
 To round it off, extend the UI to display the tool call status. This can be done either by displaying the tool call information directly, or by emitting custom data parts to the stream (see [Streaming Updates from Tools](/docs/ai/streaming-updates-from-tools) for more details). In this case, since there aren't any fine-grained progress updates to show, we'll just display the tool call information directly:
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript title="app/page.tsx" lineNumbers
 export default function ChatPage() {
 
@@ -194,6 +195,8 @@ export async function pollForResult(jobId: string) {
 async function checkJobStatus(jobId: string) {
   "use step";
   // Check job status...
+  const response = await fetch(`/api/jobs/${jobId}`);
+  return response.json();
 }
 ```
 

docs/content/docs/ai/streaming-updates-from-tools.mdx

@@ -38,6 +38,7 @@ The `type` field must be a string starting with `data-` followed by your custom
 
 Use [`getWritable()`](/docs/api-reference/workflow/get-writable) inside a step function to get a handle to the stream. This is the same stream that the LLM and other tools calls are writing to, so we can inject out own data packets directly.
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript title="workflows/chat/steps/tools.ts" lineNumbers
 import { getWritable } from "workflow"; // [!code highlight]
 import type { UIMessageChunk } from "ai";
@@ -88,6 +89,7 @@ Key points:
 
 Update your chat component to detect and render the custom data parts. Data parts are stored in the message's `parts` array alongside text and tool invocation parts:
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript title="app/page.tsx" lineNumbers
 {message.parts.map((part, partIndex) => {
   // Render text parts

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

@@ -274,10 +274,13 @@ async function streamTextStep(
   }
 
   reader.releaseLock();
-
-  // Close the stream
-  writer.close();
   writer.releaseLock();
+
+  // Return the result for the workflow to use
+  return {
+    messages: await result.response.then((r) => r.messages),
+    finishReason: await result.finishReason,
+  };
 }
 
 async function endStream(writable: WritableStream<UIMessageChunk>) {

docs/content/docs/deploying/world/local-world.mdx

@@ -47,6 +47,7 @@ The queue automatically detects your development server's port and adjusts the q
 
 The local world provides a simple authentication implementation since no authentication is required or enforced in local development.
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 getAuthHeaders(): Promise<Record<string, string>> {
   return Promise.resolve({});
@@ -67,6 +68,7 @@ export WORKFLOW_LOCAL_DATA_DIR=./custom-workflow-data
 
 **Programmatically:**
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 import { createLocalWorld } from "@workflow/world-local";
 
@@ -79,6 +81,7 @@ By default, the local world **automatically detects** which port your applicatio
 
 **Auto-detection example** (recommended):
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 import { createLocalWorld } from "@workflow/world-local";
 
@@ -92,6 +95,7 @@ If auto-detection fails, the world will fall back to the `PORT` environment vari
 
 You can override the auto-detected port by specifying it explicitly:
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 import { createLocalWorld } from "@workflow/world-local";
 
@@ -116,6 +120,7 @@ export WORKFLOW_LOCAL_BASE_URL=https://local.example.com:3000
 
 **Programmatically:**
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 import { createLocalWorld } from "@workflow/world-local";
 
@@ -207,6 +212,7 @@ For production deployments, use the [Vercel World](/docs/deploying/world/vercel-
 
 Creates a local world instance:
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 function createLocalWorld(
   args?: Partial<{
@@ -230,6 +236,7 @@ function createLocalWorld(
 
 **Examples:**
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 import { createLocalWorld } from "@workflow/world-local";
 

docs/content/docs/deploying/world/vercel-world.mdx

@@ -135,6 +135,7 @@ The Vercel world implements security best practices:
 
 Creates a Vercel world instance:
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 function createVercelWorld(
   config?: APIConfig
@@ -156,6 +157,7 @@ function createVercelWorld(
 
 **Example:**
 
+{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 import { createVercelWorld } from "@workflow/world-vercel";