docs: type-check the package READMEs and fix their broken examples

README.md

@@ -165,6 +165,7 @@ input and output types:
 ```typescript
 import { toolDefinition } from '@tanstack/ai'
 import { z } from 'zod'
+import { db } from './db'
 
 const getProducts = toolDefinition({
   name: 'getProducts',

kiira.config.ts

@@ -2,8 +2,15 @@ import { defineConfig } from 'kiira-core'
 
 export default defineConfig({
   // skills/** are the repo-level discovery skills; packages/*/skills are the
-  // per-package skills that ship in each npm package.
-  include: ['docs/**/*.md', 'skills/**/*.md', 'packages/*/skills/**/*.md'],
+  // per-package skills that ship in each npm package. The READMEs ship in
+  // each npm package too, and npm shows them on the package page.
+  include: [
+    'docs/**/*.md',
+    'skills/**/*.md',
+    'packages/*/skills/**/*.md',
+    'README.md',
+    'packages/*/README.md',
+  ],
   tsconfig: 'tsconfig.docs.json',
   exclude: [
     // docs/reference/** is auto-generated by TypeDoc (`pnpm generate-docs`);
@@ -17,6 +24,7 @@ export default defineConfig({
     // ai-angular exposes a source-resolvable entry.
     'docs/api/ai-angular.md',
     'docs/ui/angular.md',
+    'packages/ai-angular/README.md',
     // docs/superpowers/** are internal planning/spec artifacts (design docs and
     // implementation plans), not published, curated examples. Their snippets are
     // illustrative pseudo-code, not meant to compile against package source.
@@ -83,14 +91,24 @@ export default defineConfig({
     // hook that returns a decision or continues), which is valid and shouldn't
     // force an explicit return type or trailing `return`.
     {
-      include: ['docs/**/*.md', 'skills/**/*.md', 'packages/*/skills/**/*.md'],
+      include: [
+        'docs/**/*.md',
+        'skills/**/*.md',
+        'packages/*/skills/**/*.md',
+        'README.md',
+        'packages/*/README.md',
+      ],
       jsx: 'react-jsx',
       jsxImportSource: 'react',
       noImplicitReturns: false,
     },
     // Solid snippets compile JSX through solid-js.
     {
-      include: ['docs/api/ai-solid.md', 'docs/ui/solid.md'],
+      include: [
+        'docs/api/ai-solid.md',
+        'docs/ui/solid.md',
+        'packages/ai-solid/README.md',
+      ],
       jsx: 'preserve',
       jsxImportSource: 'solid-js',
     },
@@ -106,7 +124,11 @@ export default defineConfig({
     // kiira's paths["*"] does not read exports, so `octane/dist` points
     // at dist/jsx-runtime.d.ts, which exists on disk.
     {
-      include: ['docs/api/ai-octane.md', 'docs/ui/octane.md'],
+      include: [
+        'docs/api/ai-octane.md',
+        'docs/ui/octane.md',
+        'packages/ai-octane/README.md',
+      ],
       jsx: 'react-jsx',
       jsxImportSource: 'octane/dist',
     },

nx.json

@@ -68,6 +68,8 @@
         "{workspaceRoot}/packages/*/src/**/*",
         "{workspaceRoot}/packages/*/skills/**/*",
         "{workspaceRoot}/skills/**/*",
+        "{workspaceRoot}/README.md",
+        "{workspaceRoot}/packages/*/README.md",
         "{workspaceRoot}/kiira.config.ts",
         "{workspaceRoot}/tsconfig.docs.json",
         "{workspaceRoot}/packages/ai-persistence/skills-test/stubs/**/*"

packages/ai-acp/README.md

@@ -182,65 +182,77 @@ pattern every ACP harness adapter follows:
 
 ```typescript
 import { chat } from '@tanstack/ai'
+import type { TextOptions } from '@tanstack/ai'
 import {
   AsyncQueue,
   resolveInteractivePermission,
   spawnHandleToAcpTransport,
   startAcpSession,
   translateAcpStream,
 } from '@tanstack/ai-acp'
+import type {
+  AcpCompatibleProviderOptions,
+  AcpStreamEvent,
+} from '@tanstack/ai-acp'
 import { withSandbox } from '@tanstack/ai-sandbox'
+import type { HostToolBridge, SandboxHandle } from '@tanstack/ai-sandbox'
 
-// Inside your adapter's chatStream():
-const proc = await sandbox.process.spawn('my-cli --acp -m auto', {
-  cwd: '/workspace',
-})
+declare const sandbox: SandboxHandle
+declare const bridge: HostToolBridge | undefined
+declare const bridgedToolNames: ReadonlySet<string>
+declare const userText: string
 
-const queue = new AsyncQueue()
-const session = await startAcpSession({
-  transport: { kind: 'stdio', process: proc },
-  cwd: '/workspace',
-  authMethodId: 'gemini-api-key', // when the harness advertises it
-  resumeSessionId: options.modelOptions?.sessionId,
-  mcpServers: bridge
-    ? [
-        {
-          name: bridge.name,
-          url: bridge.url,
-          headers: [{ name: 'Authorization', value: `Bearer ${bridge.token}` }],
-        },
-      ]
-    : undefined,
-  onUpdate: (update) => queue.push({ kind: 'update', update }),
-  onPermissionRequest: (request) =>
-    resolveInteractivePermission(
-      request,
-      'acceptEdits',
-      bridgedToolNames,
-      options.approvals,
-      'my-harness',
-    ).outcome,
-})
+async function* chatStream(options: TextOptions<AcpCompatibleProviderOptions>) {
+  const proc = await sandbox.process.spawn('my-cli --acp -m auto', {
+    cwd: '/workspace',
+  })
 
-queue.push({ kind: 'session', sessionId: session.sessionId })
+  const queue = new AsyncQueue<AcpStreamEvent>()
+  const session = await startAcpSession({
+    transport: { kind: 'stdio', process: proc },
+    cwd: '/workspace',
+    authMethodId: 'gemini-api-key', // when the harness advertises it
+    resumeSessionId: options.modelOptions?.sessionId,
+    mcpServers: bridge
+      ? [
+          {
+            name: bridge.name,
+            url: bridge.url,
+            headers: [
+              { name: 'Authorization', value: `Bearer ${bridge.token}` },
+            ],
+          },
+        ]
+      : undefined,
+    onUpdate: (update) => queue.push({ kind: 'update', update }),
+    onPermissionRequest: (request) =>
+      resolveInteractivePermission(
+        request,
+        'acceptEdits',
+        bridgedToolNames,
+        options.approvals,
+        'my-harness',
+      ).outcome,
+  })
 
-session
-  .prompt(userText)
-  .then(({ stopReason, usage }) => {
-    queue.push({
-      kind: 'done',
-      stopReason,
-      ...(usage !== undefined && { usage }),
+  queue.push({ kind: 'session', sessionId: session.sessionId })
+
+  session
+    .prompt(userText)
+    .then(({ stopReason, usage }) => {
+      queue.push({
+        kind: 'done',
+        stopReason,
+        ...(usage !== undefined && { usage }),
+      })
+      queue.end()
     })
-    queue.end()
-  })
-  .catch((error) => queue.fail(error))
+    .catch((error) => queue.fail(error))
 
-yield *
-  translateAcpStream(queue, {
+  yield* translateAcpStream(queue, {
     model: 'auto',
-    runId,
-    threadId,
+    runId: options.runId ?? crypto.randomUUID(),
+    threadId: options.threadId,
     genId: () => crypto.randomUUID(),
     labels: {
       sessionIdEvent: 'my-harness.session-id',
@@ -249,6 +261,7 @@ yield *
     },
     bridgedToolNames,
   })
+}
 ```
 
 Wire the adapter into `chat()` with `withSandbox(...)` like any other harness package.
@@ -262,11 +275,20 @@ ACP can run over **stdio** (newline-delimited JSON-RPC on the child process pipe
 Use when the sandbox can write to process stdin (`capabilities.writableStdin === true`):
 
 ```typescript
-import { spawnHandleToAcpTransport } from '@tanstack/ai-acp'
+import { spawnHandleToAcpTransport, startAcpSession } from '@tanstack/ai-acp'
+import type { StartAcpSessionOptions } from '@tanstack/ai-acp'
+import type { SandboxHandle } from '@tanstack/ai-sandbox'
+
+declare const sandbox: SandboxHandle
+declare const cwd: string
+declare const sessionOptions: Omit<StartAcpSessionOptions, 'transport'>
 
 const proc = await sandbox.process.spawn('grok agent --acp -m auto', { cwd })
 // spawnHandleToAcpTransport adapts SpawnHandle stdout/stdin for ndJsonStream
-await startAcpSession({ transport: { kind: 'stdio', process: proc }, ... })
+await startAcpSession({
+  transport: { kind: 'stdio', process: proc },
+  ...sessionOptions,
+})
 ```
 
 On providers without writable stdin (e.g. Cloudflare Containers), adapters feed the prompt via a shell redirect instead of a host stdin write — that workaround lives in each harness adapter, not in `@tanstack/ai-acp`.
@@ -280,23 +302,39 @@ import {
   buildGrokServeWebSocketUrl,
   resolveAcpTransportMode,
   startAcpServerInSandbox,
+  startAcpSession,
 } from '@tanstack/ai-acp'
+import type { StartAcpSessionOptions } from '@tanstack/ai-acp'
+import type { SandboxHandle } from '@tanstack/ai-sandbox'
+
+declare const sandbox: SandboxHandle
+declare const secret: string
+declare const signal: AbortSignal
+declare const sessionOptions: Omit<StartAcpSessionOptions, 'transport'>
 
 const mode = resolveAcpTransportMode(sandbox, 'auto') // 'stdio' | 'websocket'
 
 const server = await startAcpServerInSandbox(sandbox, {
   port: 2419,
   cwd: '/workspace',
-  command: 'grok agent -m composer-2.5 --always-approve serve --bind 0.0.0.0:2419 --secret …',
+  command:
+    'grok agent -m composer-2.5 --always-approve serve --bind 0.0.0.0:2419 --secret …',
   buildWsUrl: ({ channel }) => buildGrokServeWebSocketUrl(channel.url, secret),
   readyMarker: 'WebSocket URL:',
   framing: 'frame',
 })
 
 const { stream, close } = await server.connect(signal)
 await startAcpSession({
-  transport: { kind: 'stream', stream, dispose: async () => { close(); await server.dispose() } },
-  ...
+  transport: {
+    kind: 'stream',
+    stream,
+    dispose: async () => {
+      close()
+      await server.dispose()
+    },
+  },
+  ...sessionOptions,
 })
 ```
 
@@ -327,7 +365,13 @@ The returned `AcpSessionHandle` exposes `{ sessionId, resumed, prompt, cancel, d
 On the first run, `translateAcpStream` emits a CUSTOM chunk:
 
 ```typescript
-{ type: 'CUSTOM', name: 'my-harness.session-id', value: { sessionId: '…' } }
+import type { CustomEvent } from '@tanstack/ai'
+
+const chunk: CustomEvent = {
+  type: 'CUSTOM',
+  name: 'my-harness.session-id',
+  value: { sessionId: '…' },
+}
 ```
 
 Thread that `sessionId` through `modelOptions.sessionId` on the next `chat()` call so `startAcpSession` can `loadSession` and only send the trailing user message.
@@ -362,13 +406,24 @@ ACP → AG-UI mapping (high level):
 Harnesses can pause mid-turn and ask the client to approve a tool call. Wire `onPermissionRequest` on `startAcpSession`:
 
 ```typescript
+import type { TextOptions } from '@tanstack/ai'
 import {
   resolvePermission,
   resolveInteractivePermission,
 } from '@tanstack/ai-acp'
+import type {
+  AcpPermissionMode,
+  AcpPermissionRequest,
+  PermissionHandler,
+} from '@tanstack/ai-acp'
+
+declare const permissionMode: AcpPermissionMode
+declare const bridgedToolNames: ReadonlySet<string>
+declare const request: AcpPermissionRequest
+declare const options: TextOptions
 
 // Headless / sandboxed: auto-approve bridged tools + edits, reject everything else
-onPermissionRequest: (request) =>
+const onPermissionRequest: PermissionHandler = (request) =>
   resolvePermission(request, permissionMode, bridgedToolNames)
 
 // Interactive: same policy, but emit approval-requested events for 'ask' actions

packages/ai-anthropic/README.md

@@ -103,6 +103,9 @@ export async function POST(request: Request) {
 Set how hard Claude thinks with `reasoning` on `chat()`. The adapter sends the right thinking fields for the model:
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+
 const stream = chat({
   adapter: anthropicText('claude-sonnet-5'),
   messages: [{ role: 'user', content: 'Plan a database migration.' }],
@@ -119,6 +122,9 @@ Models that think with a token budget, such as Claude Haiku 4.5, also take `reas
 Mark a content part with `cache_control` to cache it:
 
 ```typescript
+import { chat } from '@tanstack/ai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+
 const stream = chat({
   adapter: anthropicText('claude-sonnet-4-6'),
   messages: [

packages/ai-bedrock/README.md

@@ -101,6 +101,8 @@ itself; the OpenAI-compatible chat/responses paths sign via the bundled
 the standard credential chain (env vars, shared config, instance role):
 
 ```typescript
+import { bedrockText } from '@tanstack/ai-bedrock'
+
 const adapter = bedrockText('us.anthropic.claude-haiku-4-5-20251001-v1:0', {
   auth: 'sigv4',
   region: 'us-east-1',

packages/ai-byteplus/README.md

@@ -136,15 +136,17 @@ the resulting chunk stream to your transport:
 import { generateVideo, toServerSentEventsResponse } from '@tanstack/ai'
 import { byteplusVideo } from '@tanstack/ai-byteplus'
 
-const stream = generateVideo({
-  adapter: byteplusVideo('seedance-1-5-pro-251215'),
-  threadId: 'thread-1',
-  prompt: 'a guitar being played in a store',
-  stream: true,
-  pollingInterval: 5000,
-})
-
-return toServerSentEventsResponse(stream)
+export function POST() {
+  const stream = generateVideo({
+    adapter: byteplusVideo('seedance-1-5-pro-251215'),
+    threadId: 'thread-1',
+    prompt: 'a guitar being played in a store',
+    stream: true,
+    pollingInterval: 5000,
+  })
+
+  return toServerSentEventsResponse(stream)
+}
 ```
 
 **Generated video URLs expire after 24 hours** (the task record itself is kept

packages/ai-client/README.md

@@ -165,6 +165,7 @@ input and output types:
 ```typescript
 import { toolDefinition } from '@tanstack/ai'
 import { z } from 'zod'
+import { db } from './db'
 
 const getProducts = toolDefinition({
   name: 'getProducts',