@tanstack/ai 0.10.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Core TanStack AI library - Open source AI SDK",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -32,7 +32,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "skills"
   ],
   "keywords": [
     "ai",
@@ -40,11 +41,12 @@
     "sdk",
     "llm",
     "chat",
-    "embeddings"
+    "embeddings",
+    "tanstack-intent"
   ],
   "dependencies": {
     "partial-json": "^0.1.7",
-    "@tanstack/ai-event-client": "0.2.0"
+    "@tanstack/ai-event-client": "0.2.1"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",

package/skills/ai-core/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: ai-core
+description: >
+  Entry point for TanStack AI skills. Routes to chat-experience, tool-calling,
+  media-generation, structured-outputs, adapter-configuration, ag-ui-protocol,
+  middleware, and custom-backend-integration. Use chat() not streamText(),
+  openaiText() not createOpenAI(), toServerSentEventsResponse() not manual SSE,
+  middleware hooks not onEnd callbacks.
+type: core
+library: tanstack-ai
+library_version: '0.10.0'
+---
+
+# TanStack AI — Core Concepts
+
+TanStack AI is a type-safe, provider-agnostic AI SDK. Server-side functions
+live in `@tanstack/ai` and provider adapter packages. Client-side hooks live
+in framework packages (`@tanstack/ai-react`, `@tanstack/ai-solid`, etc.).
+Always import from the framework package on the client — never from
+`@tanstack/ai-client` directly (unless vanilla JS).
+
+## Sub-Skills
+
+| Need to...                                        | Read                                        |
+| ------------------------------------------------- | ------------------------------------------- |
+| Build a chat UI with streaming                    | ai-core/chat-experience/SKILL.md            |
+| Add tool calling (server, client, or both)        | ai-core/tool-calling/SKILL.md               |
+| Generate images, video, speech, or transcriptions | ai-core/media-generation/SKILL.md           |
+| Get typed JSON responses from the LLM             | ai-core/structured-outputs/SKILL.md         |
+| Choose and configure a provider adapter           | ai-core/adapter-configuration/SKILL.md      |
+| Implement AG-UI streaming protocol server-side    | ai-core/ag-ui-protocol/SKILL.md             |
+| Add analytics, logging, or lifecycle hooks        | ai-core/middleware/SKILL.md                 |
+| Connect to a non-TanStack-AI backend              | ai-core/custom-backend-integration/SKILL.md |
+| Set up Code Mode (LLM code execution)             | See `@tanstack/ai-code-mode` package skills |
+
+## Quick Decision Tree
+
+- Setting up a chatbot? → ai-core/chat-experience
+- Adding function calling? → ai-core/tool-calling
+- Generating media (images, audio, video)? → ai-core/media-generation
+- Need structured JSON output? → ai-core/structured-outputs
+- Choosing/configuring a provider? → ai-core/adapter-configuration
+- Building a server-only AG-UI backend? → ai-core/ag-ui-protocol
+- Adding analytics or post-stream events? → ai-core/middleware
+- Connecting to a custom backend? → ai-core/custom-backend-integration
+- Debugging mistakes? → Check Common Mistakes in the relevant sub-skill
+
+## Critical Rules
+
+1. **This is NOT the Vercel AI SDK.** Use `chat()` not `streamText()`. Use `openaiText()` not `createOpenAI()`. Import from `@tanstack/ai`, not `ai`.
+2. **Import from framework package on client.** Use `@tanstack/ai-react` (or solid/vue/svelte/preact), not `@tanstack/ai-client`.
+3. **Use `toServerSentEventsResponse()`** to convert streams to HTTP responses. Never implement SSE manually.
+4. **Use middleware for lifecycle events.** No `onEnd`/`onFinish` callbacks on `chat()` — use `middleware: [{ onFinish: ... }]`.
+5. **Ask the user which adapter and model** they want. Suggest the latest model. Also ask if they want Code Mode.
+6. **Tools must be passed to both server and client.** Server gets the tool in `chat({ tools })`, client gets the definition in `useChat({ clientTools })`.
+
+## Version
+
+Targets TanStack AI v0.10.0.

package/skills/ai-core/adapter-configuration/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: ai-core/adapter-configuration
+description: >
+  Provider adapter selection and configuration: openaiText, anthropicText,
+  geminiText, ollamaText, grokText, groqText, openRouterText. Per-model
+  type safety with modelOptions, reasoning/thinking configuration,
+  runtime adapter switching, extendAdapter() for custom models, createModel().
+  API key env vars: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY/GEMINI_API_KEY,
+  XAI_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, OLLAMA_HOST.
+type: sub-skill
+library: tanstack-ai
+library_version: '0.10.0'
+sources:
+  - 'TanStack/ai:docs/adapters/openai.md'
+  - 'TanStack/ai:docs/adapters/anthropic.md'
+  - 'TanStack/ai:docs/adapters/gemini.md'
+  - 'TanStack/ai:docs/adapters/ollama.md'
+  - 'TanStack/ai:docs/advanced/per-model-type-safety.md'
+  - 'TanStack/ai:docs/advanced/runtime-adapter-switching.md'
+  - 'TanStack/ai:docs/advanced/extend-adapter.md'
+---
+
+# Adapter Configuration
+
+> **Dependency:** This skill builds on ai-core. Read it first for critical rules.
+
+> **Before implementing:** Ask the user which provider and model they want.
+> Then fetch the latest available models from the provider's source code
+> (check the adapter's model metadata file, e.g. `packages/typescript/ai-openai/src/model-meta.ts`)
+> or from the provider's API/docs to recommend the most current model.
+> The model lists in this skill and its reference files may be outdated.
+> Always verify against the source before recommending a specific model.
+
+## Setup
+
+Create an adapter and use it with `chat()`:
+
+```typescript
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+const stream = chat({
+  adapter: openaiText('gpt-5.2'),
+  messages,
+  temperature: 0.7,
+  maxTokens: 1000,
+})
+
+return toServerSentEventsResponse(stream)
+```
+
+The adapter factory function takes the model name as a string literal and an
+optional config object (API key, base URL, etc.). The model name is passed
+into the factory, not into `chat()`.
+
+## Core Patterns
+
+### 1. Adapter Selection
+
+Each provider has a dedicated package with tree-shakeable adapter factories.
+The text adapter is the primary one for chat/completions:
+
+| Provider   | Package                   | Factory          | Env Var                                           |
+| ---------- | ------------------------- | ---------------- | ------------------------------------------------- |
+| OpenAI     | `@tanstack/ai-openai`     | `openaiText`     | `OPENAI_API_KEY`                                  |
+| Anthropic  | `@tanstack/ai-anthropic`  | `anthropicText`  | `ANTHROPIC_API_KEY`                               |
+| Gemini     | `@tanstack/ai-gemini`     | `geminiText`     | `GOOGLE_API_KEY` or `GEMINI_API_KEY`              |
+| Grok (xAI) | `@tanstack/ai-grok`       | `grokText`       | `XAI_API_KEY`                                     |
+| Groq       | `@tanstack/ai-groq`       | `groqText`       | `GROQ_API_KEY`                                    |
+| OpenRouter | `@tanstack/ai-openrouter` | `openRouterText` | `OPENROUTER_API_KEY`                              |
+| Ollama     | `@tanstack/ai-ollama`     | `ollamaText`     | `OLLAMA_HOST` (default: `http://localhost:11434`) |
+
+```typescript
+// Each factory takes model as first arg, optional config as second
+import { openaiText } from '@tanstack/ai-openai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { geminiText } from '@tanstack/ai-gemini'
+import { grokText } from '@tanstack/ai-grok'
+import { groqText } from '@tanstack/ai-groq'
+import { openRouterText } from '@tanstack/ai-openrouter'
+import { ollamaText } from '@tanstack/ai-ollama'
+
+// Model string is passed to the factory, NOT to chat()
+const adapter = openaiText('gpt-5.2')
+const adapter2 = anthropicText('claude-sonnet-4-6')
+const adapter3 = geminiText('gemini-2.5-pro')
+const adapter4 = grokText('grok-4')
+const adapter5 = groqText('llama-3.3-70b-versatile')
+const adapter6 = openRouterText('anthropic/claude-sonnet-4')
+const adapter7 = ollamaText('llama3.3')
+
+// Optional: pass explicit API key
+const adapterWithKey = openaiText('gpt-5.2', {
+  apiKey: 'sk-...',
+})
+```
+
+### 2. Runtime Adapter Switching
+
+Use an adapter factory map to switch providers dynamically based on user
+input or configuration:
+
+```typescript
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import type { TextAdapter } from '@tanstack/ai/adapters'
+import { openaiText } from '@tanstack/ai-openai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { geminiText } from '@tanstack/ai-gemini'
+
+// Define a map of provider+model to adapter factory calls
+const adapters: Record<string, () => TextAdapter> = {
+  'openai/gpt-5.2': () => openaiText('gpt-5.2'),
+  'anthropic/claude-sonnet-4-6': () => anthropicText('claude-sonnet-4-6'),
+  'gemini/gemini-2.5-pro': () => geminiText('gemini-2.5-pro'),
+}
+
+export function handleChat(providerModel: string, messages: Array<any>) {
+  const createAdapter = adapters[providerModel]
+  if (!createAdapter) {
+    throw new Error(`Unknown provider/model: ${providerModel}`)
+  }
+
+  const stream = chat({
+    adapter: createAdapter(),
+    messages,
+  })
+
+  return toServerSentEventsResponse(stream)
+}
+```
+
+### 3. Configuring Reasoning / Thinking
+
+Different providers expose reasoning/thinking through their `modelOptions`:
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+import { anthropicText } from '@tanstack/ai-anthropic'
+import { geminiText } from '@tanstack/ai-gemini'
+
+// OpenAI: reasoning with effort and summary
+const openaiStream = chat({
+  adapter: openaiText('gpt-5.2'),
+  messages,
+  modelOptions: {
+    reasoning: {
+      effort: 'high',
+      summary: 'auto',
+    },
+  },
+})
+
+// Anthropic: extended thinking with budget_tokens
+const anthropicStream = chat({
+  adapter: anthropicText('claude-sonnet-4-6'),
+  messages,
+  maxTokens: 16000,
+  modelOptions: {
+    thinking: {
+      type: 'enabled',
+      budget_tokens: 8000, // must be >= 1024 and < maxTokens
+    },
+  },
+})
+
+// Anthropic: adaptive thinking (claude-sonnet-4-6 and newer)
+const adaptiveStream = chat({
+  adapter: anthropicText('claude-sonnet-4-6'),
+  messages,
+  maxTokens: 16000,
+  modelOptions: {
+    thinking: {
+      type: 'adaptive',
+    },
+    effort: 'high', // 'max' | 'high' | 'medium' | 'low'
+  },
+})
+
+// Gemini: thinking config with budget or level
+const geminiStream = chat({
+  adapter: geminiText('gemini-2.5-pro'),
+  messages,
+  modelOptions: {
+    thinkingConfig: {
+      includeThoughts: true,
+      thinkingBudget: 4096,
+    },
+  },
+})
+```
+
+### 4. Extending Adapters with Custom Models
+
+Use `extendAdapter()` and `createModel()` to add custom or fine-tuned models
+while preserving type safety for the original models:
+
+```typescript
+import { extendAdapter, createModel } from '@tanstack/ai'
+import { openaiText } from '@tanstack/ai-openai'
+
+// Define custom models
+const customModels = [
+  createModel('ft:gpt-5.2:my-org:custom-model:abc123', ['text', 'image']),
+  createModel('my-local-proxy-model', ['text']),
+] as const
+
+// Create extended factory - original models still fully typed
+const myOpenai = extendAdapter(openaiText, customModels)
+
+// Use original models - full type inference preserved
+const gpt5 = myOpenai('gpt-5.2')
+
+// Use custom models - accepted by the type system
+const custom = myOpenai('ft:gpt-5.2:my-org:custom-model:abc123')
+
+// Type error: 'nonexistent-model' is not a valid model
+// myOpenai('nonexistent-model')
+```
+
+At runtime, `extendAdapter` simply passes through to the original factory.
+The `_customModels` parameter is only used for type inference.
+
+## Common Mistakes
+
+### a. HIGH: Confusing legacy monolithic with tree-shakeable adapter
+
+The legacy `openai()` (and `anthropic()`, etc.) monolithic adapters are
+deprecated. They take the model in `chat()`, not in the factory.
+
+```typescript
+// WRONG: Legacy monolithic adapter pattern
+import { openai } from '@tanstack/ai-openai'
+chat({ adapter: openai(), model: 'gpt-5.2', messages })
+
+// CORRECT: Tree-shakeable adapter, model in factory
+import { openaiText } from '@tanstack/ai-openai'
+chat({ adapter: openaiText('gpt-5.2'), messages })
+```
+
+Source: docs/migration/migration.md
+
+### b. MEDIUM: Wrong API key environment variable name
+
+Each provider uses a specific env var name. Using the wrong one causes a
+runtime error:
+
+| Provider   | Correct Env Var                      | Common Mistake                                                           |
+| ---------- | ------------------------------------ | ------------------------------------------------------------------------ |
+| OpenAI     | `OPENAI_API_KEY`                     |                                                                          |
+| Anthropic  | `ANTHROPIC_API_KEY`                  |                                                                          |
+| Gemini     | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | `GOOGLE_GENAI_API_KEY` (does not work)                                   |
+| Grok (xAI) | `XAI_API_KEY`                        | `GROK_API_KEY` (does not work)                                           |
+| Groq       | `GROQ_API_KEY`                       |                                                                          |
+| OpenRouter | `OPENROUTER_API_KEY`                 |                                                                          |
+| Ollama     | `OLLAMA_HOST`                        | No API key needed, just the host URL (default: `http://localhost:11434`) |
+
+Source: adapter source code (`utils/client.ts` in each adapter package).
+
+## References
+
+Detailed per-adapter reference files:
+
+- [OpenAI Adapter](references/openai-adapter.md)
+- [Anthropic Adapter](references/anthropic-adapter.md)
+- [Gemini Adapter](references/gemini-adapter.md)
+- [Ollama Adapter](references/ollama-adapter.md)
+- [Grok Adapter](references/grok-adapter.md)
+- [Groq Adapter](references/groq-adapter.md)
+- [OpenRouter Adapter](references/openrouter-adapter.md)
+
+## Tension
+
+**HIGH Tension: Type safety vs. quick prototyping** -- Per-model type safety
+requires specific model string literals. Quick prototyping wants dynamic
+selection with `string` variables. Agents optimizing for quick setup silently
+lose type safety. If model names come from user input or config files, use
+`extendAdapter()` to add custom names.
+
+## Cross-References
+
+- See also: `ai-core/chat-experience/SKILL.md` -- Adapter choice affects chat setup
+- See also: `ai-core/structured-outputs/SKILL.md` -- `outputSchema` handles provider differences transparently

package/skills/ai-core/adapter-configuration/references/anthropic-adapter.md

@@ -0,0 +1,97 @@
+# Anthropic Adapter Reference
+
+## Package
+
+```
+@tanstack/ai-anthropic
+```
+
+## Adapter Factories
+
+| Factory              | Type      | Description        |
+| -------------------- | --------- | ------------------ |
+| `anthropicText`      | Text/Chat | Chat completions   |
+| `anthropicSummarize` | Summarize | Text summarization |
+
+## Import
+
+```typescript
+import { anthropicText } from '@tanstack/ai-anthropic'
+```
+
+## Key Chat Models
+
+| Model               | Context Window | Max Output | Notes                           |
+| ------------------- | -------------- | ---------- | ------------------------------- |
+| `claude-opus-4-6`   | 200K           | 128K       | Most capable, adaptive thinking |
+| `claude-sonnet-4-6` | 1M             | 64K        | Best balance, adaptive thinking |
+| `claude-sonnet-4-5` | 200K           | 64K        | Previous gen balanced           |
+| `claude-opus-4-5`   | 200K           | 32K        | Previous gen most capable       |
+| `claude-haiku-4-5`  | 200K           | 64K        | Fast and affordable             |
+| `claude-sonnet-4`   | 200K           | 64K        | Older balanced model            |
+| `claude-opus-4`     | 200K           | 32K        | Older most capable              |
+
+Note: Model IDs use the format `claude-opus-4-6`, `claude-sonnet-4-6`, etc.
+
+## Provider-Specific modelOptions
+
+```typescript
+chat({
+  adapter: anthropicText('claude-sonnet-4-6'),
+  messages,
+  maxTokens: 16000,
+  modelOptions: {
+    // Extended thinking (budget-based)
+    thinking: {
+      type: 'enabled',
+      budget_tokens: 8000, // must be >= 1024 and < maxTokens
+    },
+    // Adaptive thinking (claude-sonnet-4-6, claude-opus-4-6+)
+    thinking: {
+      type: 'adaptive',
+    },
+    effort: 'high', // 'max' | 'high' | 'medium' | 'low'
+    // Service tier
+    service_tier: 'auto', // 'auto' | 'standard_only'
+    // Stop sequences
+    stop_sequences: ['END'],
+    // Tool choice
+    tool_choice: { type: 'auto' },
+    // Context management
+    context_management: {
+      /* BetaContextManagementConfig */
+    },
+    // MCP servers (max 20)
+    mcp_servers: [
+      {
+        name: 'my-server',
+        url: 'https://mcp.example.com',
+        type: 'url',
+        tool_configuration: { enabled: true },
+      },
+    ],
+    // Container (skills)
+    container: {
+      id: 'container-id',
+      skills: [{ skill_id: 'analysis', type: 'anthropic' }],
+    },
+    // Sampling
+    top_k: 40,
+  },
+})
+```
+
+## Environment Variable
+
+```
+ANTHROPIC_API_KEY
+```
+
+## Gotchas
+
+- `thinking.budget_tokens` must be >= 1024 AND less than `maxTokens`.
+  Failing either check throws a validation error.
+- Cannot set both `top_p` and `temperature` at the same time (throws error).
+- `claude-3-5-haiku` and `claude-3-haiku` do NOT support extended thinking.
+- System prompts support prompt caching via `cache_control` on `TextBlockParam[]`.
+- All Claude models accept `text`, `image`, and `document` (PDF) input.

package/skills/ai-core/adapter-configuration/references/gemini-adapter.md

@@ -0,0 +1,102 @@
+# Gemini Adapter Reference
+
+## Package
+
+```
+@tanstack/ai-gemini
+```
+
+## Adapter Factories
+
+| Factory           | Type      | Description                   |
+| ----------------- | --------- | ----------------------------- |
+| `geminiText`      | Text/Chat | Chat completions              |
+| `geminiImage`     | Image     | Image generation (Imagen)     |
+| `geminiSpeech`    | TTS       | Text-to-speech (experimental) |
+| `geminiSummarize` | Summarize | Text summarization            |
+
+## Import
+
+```typescript
+import { geminiText } from '@tanstack/ai-gemini'
+import { geminiImage } from '@tanstack/ai-gemini'
+```
+
+## Key Chat Models
+
+| Model                           | Max Input | Max Output | Notes                        |
+| ------------------------------- | --------- | ---------- | ---------------------------- |
+| `gemini-3.1-pro-preview`        | 1M        | 65K        | Latest flagship, thinking    |
+| `gemini-3-pro-preview`          | 1M        | 65K        | Previous flagship            |
+| `gemini-3-flash-preview`        | 1M        | 65K        | Fast, thinking, multimodal   |
+| `gemini-3.1-flash-lite-preview` | 1M        | 65K        | Budget, still capable        |
+| `gemini-2.5-pro`                | 1M        | 65K        | Stable release, all features |
+| `gemini-2.5-flash`              | 1M        | 65K        | Fast stable release          |
+
+All Gemini text models accept `text`, `image`, `audio`, `video`, and `document` input.
+
+## Provider-Specific modelOptions
+
+```typescript
+chat({
+  adapter: geminiText('gemini-2.5-pro'),
+  messages,
+  modelOptions: {
+    // Thinking (budget-based)
+    thinkingConfig: {
+      includeThoughts: true,
+      thinkingBudget: 4096,
+    },
+    // Thinking (level-based, advanced models)
+    thinkingConfig: {
+      thinkingLevel: 'THINKING_LEVEL_HIGH',
+    },
+    // Safety settings
+    safetySettings: [
+      {
+        category: 'HARM_CATEGORY_HATE_SPEECH',
+        threshold: 'BLOCK_MEDIUM_AND_ABOVE',
+      },
+    ],
+    // Tool config
+    toolConfig: {
+      /* ToolConfig */
+    },
+    // Structured output
+    responseMimeType: 'application/json',
+    responseSchema: {
+      /* Schema */
+    },
+    // Cached content
+    cachedContent: 'cachedContents/abc123',
+    // Response modalities
+    responseModalities: ['TEXT'],
+    // Sampling
+    topK: 40,
+    seed: 42,
+    presencePenalty: 0.5,
+    frequencyPenalty: 0.5,
+    candidateCount: 1,
+    stopSequences: ['END'],
+  },
+})
+```
+
+## Environment Variable
+
+```
+GOOGLE_API_KEY  (preferred)
+GEMINI_API_KEY  (also accepted)
+```
+
+The adapter checks `GOOGLE_API_KEY` first, then falls back to `GEMINI_API_KEY`.
+Note: `GOOGLE_GENAI_API_KEY` does NOT work.
+
+## Gotchas
+
+- All Gemini models are multimodal (text, image, audio, video, document input).
+- Image generation models (`gemini-3-pro-image-preview`, etc.) have smaller
+  input limits (65K tokens) compared to text models (1M tokens).
+- `thinkingConfig.thinkingLevel` (level-based) and `thinkingConfig.thinkingBudget`
+  (budget-based) serve different models. Check which your model supports.
+- `cachedContent` must follow the format `cachedContents/{id}`.

package/skills/ai-core/adapter-configuration/references/grok-adapter.md

@@ -0,0 +1,77 @@
+# Grok (xAI) Adapter Reference
+
+## Package
+
+```
+@tanstack/ai-grok
+```
+
+## Adapter Factories
+
+| Factory         | Type      | Description        |
+| --------------- | --------- | ------------------ |
+| `grokText`      | Text/Chat | Chat completions   |
+| `grokImage`     | Image     | Image generation   |
+| `grokSummarize` | Summarize | Text summarization |
+
+## Import
+
+```typescript
+import { grokText } from '@tanstack/ai-grok'
+import { grokImage } from '@tanstack/ai-grok'
+```
+
+## Key Chat Models
+
+| Model                         | Context Window | Notes                        |
+| ----------------------------- | -------------- | ---------------------------- |
+| `grok-4-1-fast-reasoning`     | 2M             | Latest, fast reasoning       |
+| `grok-4-1-fast-non-reasoning` | 2M             | Latest, no reasoning         |
+| `grok-code-fast-1`            | 256K           | Code-specialized, reasoning  |
+| `grok-4`                      | 256K           | Full reasoning, tool calling |
+| `grok-4-fast-reasoning`       | 2M             | Fast reasoning variant       |
+| `grok-3`                      | 131K           | Previous gen, no reasoning   |
+| `grok-3-mini`                 | 131K           | Budget reasoning             |
+| `grok-2-vision-1212`          | 32K            | Vision input                 |
+
+Image model: `grok-2-image-1212`
+
+## Provider-Specific modelOptions
+
+Grok uses an OpenAI-compatible API. Options are straightforward:
+
+```typescript
+chat({
+  adapter: grokText('grok-4'),
+  messages,
+  modelOptions: {
+    temperature: 0.7,
+    max_tokens: 4096,
+    top_p: 0.9,
+    frequency_penalty: 0.5,
+    presence_penalty: 0.5,
+    stop: ['\n\n'],
+    user: 'user-123',
+  },
+})
+```
+
+## Environment Variable
+
+```
+XAI_API_KEY
+```
+
+**Important:** The env var is `XAI_API_KEY`, not `GROK_API_KEY`.
+The adapter uses the OpenAI SDK with xAI's base URL (`https://api.x.ai/v1`).
+
+## Gotchas
+
+- Uses the OpenAI SDK under the hood with a custom `baseURL`.
+- `grok-4-1-fast-non-reasoning` and `grok-4-fast-non-reasoning` explicitly
+  do NOT support reasoning. Other grok-4+ models do.
+- `grok-2-vision-1212` is the only model with image input support in the
+  older generation.
+- The grok-4-1 fast models have a massive 2M context window.
+- Provider options are simpler than OpenAI's (no Responses API features,
+  no structured outputs config, no metadata).