diff --git a/.changeset/feat-system-prompts-metadata.md b/.changeset/feat-system-prompts-metadata.md
deleted file mode 100644
index 21db0cf71..000000000
--- a/.changeset/feat-system-prompts-metadata.md
+++ /dev/null
@@ -1,86 +0,0 @@
----
-'@tanstack/ai': minor
-'@tanstack/ai-anthropic': minor
-'@tanstack/ai-event-client': patch
-'@tanstack/ai-gemini': patch
-'@tanstack/ai-ollama': patch
-'@tanstack/ai-openai': patch
-'@tanstack/ai-openrouter': patch
-'@tanstack/openai-base': patch
----
-
-feat(ai): `systemPrompts` accept `{ content, metadata }` with adapter-inferred metadata typing
-
-`chat({ systemPrompts })` now accepts either a plain string (the existing
-shape — fully backward compatible) or `{ content, metadata }`. The `metadata`
-field's type is inferred from the adapter via a new
-`TSystemPromptMetadata` generic on `TextAdapter` / `BaseTextAdapter`:
-
-- `@tanstack/ai-anthropic` declares `AnthropicSystemPromptMetadata` →
-  users get `cache_control` autocomplete and type-checking on
-  `systemPrompts[i].metadata` for Anthropic chats.
-- Adapters with no per-prompt metadata (OpenAI, Gemini, Ollama,
-  OpenRouter, openai-base) inherit the default `never`, which means the
-  `metadata` field carries no meaningful value at the call site —
-  TypeScript only accepts `undefined` there. Provider-foreign metadata
-  that reaches an adapter via JS / `as any` is silently dropped, never
-  written to the wire.
-
-```ts
-import { chat } from '@tanstack/ai'
-import { anthropicText } from '@tanstack/ai-anthropic'
-
-// Anthropic — `cache_control` is autocompleted, no `satisfies` needed.
-chat({
-  adapter: anthropicText({ apiKey }, 'claude-sonnet-4-6'),
-  systemPrompts: [
-    {
-      content: 'Stable instructions — cache me.',
-      metadata: { cache_control: { type: 'ephemeral' } },
-    },
-    'Volatile per-request instruction.',
-  ],
-})
-
-// OpenAI — `metadata` is `never`; only `undefined` is assignable, so the
-// field is effectively unusable. The object form without `metadata` still
-// works for portability.
-chat({
-  adapter: openaiText({ apiKey }, 'gpt-4o-mini'),
-  systemPrompts: [
-    'Plain string.',
-    { content: 'Object form without metadata is allowed.' },
-  ],
-})
-```
-
-New exports:
-
-- `@tanstack/ai`: `SystemPrompt`, `NormalizedSystemPrompt` types and the
-  `normalizeSystemPrompts()` helper adapters use to normalize the wide
-  input shape to `{ content, metadata? }` before consumption.
-- `@tanstack/ai-anthropic`: `AnthropicSystemPromptMetadata` interface
-  (currently exposes `cache_control` for prompt caching).
-
-Internal:
-
-- New `TSystemPromptMetadata = never` generic on `TextAdapter` /
-  `BaseTextAdapter`, surfaced via `'~types'['systemPromptMetadata']`
-  for inference at the `chat()` call site.
-- Anthropic adapter reads `metadata.cache_control` and attaches it to
-  the corresponding `TextBlockParam`.
-- All other text adapters call `normalizeSystemPrompts()` and join
-  `.content` for their respective `instructions` / `system` /
-  `systemInstruction` fields. Foreign metadata that reaches them via JS
-  / `as any` is dropped (never written to the wire).
-- `normalizeSystemPrompts()` is the public API boundary and throws
-  `TypeError` (naming the offending index) for object-form entries whose
-  `content` isn't a string — preventing literal `"undefined"` from
-  reaching the model on stale call sites.
-- OpenTelemetry middleware attaches per-prompt metadata as the
-  `tanstack.ai.system_prompt.metadata` JSON span attribute when
-  `captureContent: true` and at least one entry carries metadata, so
-  observability backends can distinguish cache hit/miss for Anthropic.
-- `@tanstack/ai-event-client` mirrors the `SystemPrompt` shape locally
-  (avoids a circular import) and projects metadata away on the devtools
-  wire — devtools UI still receives `Array<string>`.
diff --git a/packages/typescript/ai-anthropic/CHANGELOG.md b/packages/typescript/ai-anthropic/CHANGELOG.md
index 39818cc49..c05955887 100644
--- a/packages/typescript/ai-anthropic/CHANGELOG.md
+++ b/packages/typescript/ai-anthropic/CHANGELOG.md
@@ -1,5 +1,87 @@
 # @tanstack/ai-anthropic
 
+## 0.10.0
+
+### Minor Changes
+
+- feat(ai): `systemPrompts` accept `{ content, metadata }` with adapter-inferred metadata typing ([#575](https://github.com/TanStack/ai/pull/575))
+
+  `chat({ systemPrompts })` now accepts either a plain string (the existing
+  shape — fully backward compatible) or `{ content, metadata }`. The `metadata`
+  field's type is inferred from the adapter via a new
+  `TSystemPromptMetadata` generic on `TextAdapter` / `BaseTextAdapter`:
+  - `@tanstack/ai-anthropic` declares `AnthropicSystemPromptMetadata` →
+    users get `cache_control` autocomplete and type-checking on
+    `systemPrompts[i].metadata` for Anthropic chats.
+  - Adapters with no per-prompt metadata (OpenAI, Gemini, Ollama,
+    OpenRouter, openai-base) inherit the default `never`, which means the
+    `metadata` field carries no meaningful value at the call site —
+    TypeScript only accepts `undefined` there. Provider-foreign metadata
+    that reaches an adapter via JS / `as any` is silently dropped, never
+    written to the wire.
+
+  ```ts
+  import { chat } from '@tanstack/ai'
+  import { anthropicText } from '@tanstack/ai-anthropic'
+
+  // Anthropic — `cache_control` is autocompleted, no `satisfies` needed.
+  chat({
+    adapter: anthropicText({ apiKey }, 'claude-sonnet-4-6'),
+    systemPrompts: [
+      {
+        content: 'Stable instructions — cache me.',
+        metadata: { cache_control: { type: 'ephemeral' } },
+      },
+      'Volatile per-request instruction.',
+    ],
+  })
+
+  // OpenAI — `metadata` is `never`; only `undefined` is assignable, so the
+  // field is effectively unusable. The object form without `metadata` still
+  // works for portability.
+  chat({
+    adapter: openaiText({ apiKey }, 'gpt-4o-mini'),
+    systemPrompts: [
+      'Plain string.',
+      { content: 'Object form without metadata is allowed.' },
+    ],
+  })
+  ```
+
+  New exports:
+  - `@tanstack/ai`: `SystemPrompt`, `NormalizedSystemPrompt` types and the
+    `normalizeSystemPrompts()` helper adapters use to normalize the wide
+    input shape to `{ content, metadata? }` before consumption.
+  - `@tanstack/ai-anthropic`: `AnthropicSystemPromptMetadata` interface
+    (currently exposes `cache_control` for prompt caching).
+
+  Internal:
+  - New `TSystemPromptMetadata = never` generic on `TextAdapter` /
+    `BaseTextAdapter`, surfaced via `'~types'['systemPromptMetadata']`
+    for inference at the `chat()` call site.
+  - Anthropic adapter reads `metadata.cache_control` and attaches it to
+    the corresponding `TextBlockParam`.
+  - All other text adapters call `normalizeSystemPrompts()` and join
+    `.content` for their respective `instructions` / `system` /
+    `systemInstruction` fields. Foreign metadata that reaches them via JS
+    / `as any` is dropped (never written to the wire).
+  - `normalizeSystemPrompts()` is the public API boundary and throws
+    `TypeError` (naming the offending index) for object-form entries whose
+    `content` isn't a string — preventing literal `"undefined"` from
+    reaching the model on stale call sites.
+  - OpenTelemetry middleware attaches per-prompt metadata as the
+    `tanstack.ai.system_prompt.metadata` JSON span attribute when
+    `captureContent: true` and at least one entry carries metadata, so
+    observability backends can distinguish cache hit/miss for Anthropic.
+  - `@tanstack/ai-event-client` mirrors the `SystemPrompt` shape locally
+    (avoids a circular import) and projects metadata away on the devtools
+    wire — devtools UI still receives `Array<string>`.
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+
 ## 0.9.0
 
 ### Minor Changes
diff --git a/packages/typescript/ai-anthropic/package.json b/packages/typescript/ai-anthropic/package.json
index 25ffd8e35..7266fe510 100644
--- a/packages/typescript/ai-anthropic/package.json
+++ b/packages/typescript/ai-anthropic/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-anthropic",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Anthropic Claude adapter for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-client/CHANGELOG.md b/packages/typescript/ai-client/CHANGELOG.md
index 7701e6800..f45fe5b8b 100644
--- a/packages/typescript/ai-client/CHANGELOG.md
+++ b/packages/typescript/ai-client/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-client
 
+## 0.11.2
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-event-client@0.3.5
+
 ## 0.11.1
 
 ### Patch Changes
diff --git a/packages/typescript/ai-client/package.json b/packages/typescript/ai-client/package.json
index 258e06d4a..74dc5673f 100644
--- a/packages/typescript/ai-client/package.json
+++ b/packages/typescript/ai-client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-client",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "Framework-agnostic headless client for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-code-mode-skills/CHANGELOG.md b/packages/typescript/ai-code-mode-skills/CHANGELOG.md
index 4883209d8..59c7040f8 100644
--- a/packages/typescript/ai-code-mode-skills/CHANGELOG.md
+++ b/packages/typescript/ai-code-mode-skills/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-code-mode-skills
 
+## 0.1.15
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-code-mode@0.1.15
+
 ## 0.1.14
 
 ### Patch Changes
diff --git a/packages/typescript/ai-code-mode-skills/package.json b/packages/typescript/ai-code-mode-skills/package.json
index 92b765f25..c7d653116 100644
--- a/packages/typescript/ai-code-mode-skills/package.json
+++ b/packages/typescript/ai-code-mode-skills/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-code-mode-skills",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Persistent skill library for TanStack AI Code Mode - LLM-created reusable code snippets",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-code-mode/CHANGELOG.md b/packages/typescript/ai-code-mode/CHANGELOG.md
index 79efb0058..112e7c671 100644
--- a/packages/typescript/ai-code-mode/CHANGELOG.md
+++ b/packages/typescript/ai-code-mode/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @tanstack/ai-code-mode
 
+## 0.1.15
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+
 ## 0.1.14
 
 ### Patch Changes
diff --git a/packages/typescript/ai-code-mode/package.json b/packages/typescript/ai-code-mode/package.json
index 73308ce91..028487119 100644
--- a/packages/typescript/ai-code-mode/package.json
+++ b/packages/typescript/ai-code-mode/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-code-mode",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Code Mode for TanStack AI - LLM-driven code execution in secure sandboxes",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-devtools/CHANGELOG.md b/packages/typescript/ai-devtools/CHANGELOG.md
index fca8f0bc9..72b4b45aa 100644
--- a/packages/typescript/ai-devtools/CHANGELOG.md
+++ b/packages/typescript/ai-devtools/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-devtools-core
 
+## 0.3.32
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-event-client@0.3.5
+
 ## 0.3.31
 
 ### Patch Changes
diff --git a/packages/typescript/ai-devtools/package.json b/packages/typescript/ai-devtools/package.json
index f9219925e..63d2dc01b 100644
--- a/packages/typescript/ai-devtools/package.json
+++ b/packages/typescript/ai-devtools/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-devtools-core",
-  "version": "0.3.31",
+  "version": "0.3.32",
   "description": "Core TanStack AI Devtools",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-elevenlabs/CHANGELOG.md b/packages/typescript/ai-elevenlabs/CHANGELOG.md
index b957b49f3..4a2f78bc9 100644
--- a/packages/typescript/ai-elevenlabs/CHANGELOG.md
+++ b/packages/typescript/ai-elevenlabs/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-elevenlabs
 
+## 0.2.7
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-client@0.11.2
+
 ## 0.2.6
 
 ### Patch Changes
diff --git a/packages/typescript/ai-elevenlabs/package.json b/packages/typescript/ai-elevenlabs/package.json
index bdd793d53..e510fe8cb 100644
--- a/packages/typescript/ai-elevenlabs/package.json
+++ b/packages/typescript/ai-elevenlabs/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-elevenlabs",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "ElevenLabs adapter for TanStack AI realtime voice",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-event-client/CHANGELOG.md b/packages/typescript/ai-event-client/CHANGELOG.md
index 18c8c0f4d..527fcb67c 100644
--- a/packages/typescript/ai-event-client/CHANGELOG.md
+++ b/packages/typescript/ai-event-client/CHANGELOG.md
@@ -1,5 +1,85 @@
 # @tanstack/ai-event-client
 
+## 0.3.5
+
+### Patch Changes
+
+- feat(ai): `systemPrompts` accept `{ content, metadata }` with adapter-inferred metadata typing ([#575](https://github.com/TanStack/ai/pull/575))
+
+  `chat({ systemPrompts })` now accepts either a plain string (the existing
+  shape — fully backward compatible) or `{ content, metadata }`. The `metadata`
+  field's type is inferred from the adapter via a new
+  `TSystemPromptMetadata` generic on `TextAdapter` / `BaseTextAdapter`:
+  - `@tanstack/ai-anthropic` declares `AnthropicSystemPromptMetadata` →
+    users get `cache_control` autocomplete and type-checking on
+    `systemPrompts[i].metadata` for Anthropic chats.
+  - Adapters with no per-prompt metadata (OpenAI, Gemini, Ollama,
+    OpenRouter, openai-base) inherit the default `never`, which means the
+    `metadata` field carries no meaningful value at the call site —
+    TypeScript only accepts `undefined` there. Provider-foreign metadata
+    that reaches an adapter via JS / `as any` is silently dropped, never
+    written to the wire.
+
+  ```ts
+  import { chat } from '@tanstack/ai'
+  import { anthropicText } from '@tanstack/ai-anthropic'
+
+  // Anthropic — `cache_control` is autocompleted, no `satisfies` needed.
+  chat({
+    adapter: anthropicText({ apiKey }, 'claude-sonnet-4-6'),
+    systemPrompts: [
+      {
+        content: 'Stable instructions — cache me.',
+        metadata: { cache_control: { type: 'ephemeral' } },
+      },
+      'Volatile per-request instruction.',
+    ],
+  })
+
+  // OpenAI — `metadata` is `never`; only `undefined` is assignable, so the
+  // field is effectively unusable. The object form without `metadata` still
+  // works for portability.
+  chat({
+    adapter: openaiText({ apiKey }, 'gpt-4o-mini'),
+    systemPrompts: [
+      'Plain string.',
+      { content: 'Object form without metadata is allowed.' },
+    ],
+  })
+  ```
+
+  New exports:
+  - `@tanstack/ai`: `SystemPrompt`, `NormalizedSystemPrompt` types and the
+    `normalizeSystemPrompts()` helper adapters use to normalize the wide
+    input shape to `{ content, metadata? }` before consumption.
+  - `@tanstack/ai-anthropic`: `AnthropicSystemPromptMetadata` interface
+    (currently exposes `cache_control` for prompt caching).
+
+  Internal:
+  - New `TSystemPromptMetadata = never` generic on `TextAdapter` /
+    `BaseTextAdapter`, surfaced via `'~types'['systemPromptMetadata']`
+    for inference at the `chat()` call site.
+  - Anthropic adapter reads `metadata.cache_control` and attaches it to
+    the corresponding `TextBlockParam`.
+  - All other text adapters call `normalizeSystemPrompts()` and join
+    `.content` for their respective `instructions` / `system` /
+    `systemInstruction` fields. Foreign metadata that reaches them via JS
+    / `as any` is dropped (never written to the wire).
+  - `normalizeSystemPrompts()` is the public API boundary and throws
+    `TypeError` (naming the offending index) for object-form entries whose
+    `content` isn't a string — preventing literal `"undefined"` from
+    reaching the model on stale call sites.
+  - OpenTelemetry middleware attaches per-prompt metadata as the
+    `tanstack.ai.system_prompt.metadata` JSON span attribute when
+    `captureContent: true` and at least one entry carries metadata, so
+    observability backends can distinguish cache hit/miss for Anthropic.
+  - `@tanstack/ai-event-client` mirrors the `SystemPrompt` shape locally
+    (avoids a circular import) and projects metadata away on the devtools
+    wire — devtools UI still receives `Array<string>`.
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+
 ## 0.3.4
 
 ### Patch Changes
diff --git a/packages/typescript/ai-event-client/package.json b/packages/typescript/ai-event-client/package.json
index 28c8d5b48..b3d6e4319 100644
--- a/packages/typescript/ai-event-client/package.json
+++ b/packages/typescript/ai-event-client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-event-client",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Event client for TanStack AI devtools integration",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-fal/CHANGELOG.md b/packages/typescript/ai-fal/CHANGELOG.md
index 50c9f9e89..69e8d5591 100644
--- a/packages/typescript/ai-fal/CHANGELOG.md
+++ b/packages/typescript/ai-fal/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @tanstack/ai-fal
 
+## 0.7.8
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+
 ## 0.7.7
 
 ### Patch Changes
diff --git a/packages/typescript/ai-fal/package.json b/packages/typescript/ai-fal/package.json
index 1e34d1dc8..46be381c9 100644
--- a/packages/typescript/ai-fal/package.json
+++ b/packages/typescript/ai-fal/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-fal",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "description": "fal.ai adapter for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-gemini/CHANGELOG.md b/packages/typescript/ai-gemini/CHANGELOG.md
index b907527ad..cd457a7fc 100644
--- a/packages/typescript/ai-gemini/CHANGELOG.md
+++ b/packages/typescript/ai-gemini/CHANGELOG.md
@@ -1,5 +1,85 @@
 # @tanstack/ai-gemini
 
+## 0.10.7
+
+### Patch Changes
+
+- feat(ai): `systemPrompts` accept `{ content, metadata }` with adapter-inferred metadata typing ([#575](https://github.com/TanStack/ai/pull/575))
+
+  `chat({ systemPrompts })` now accepts either a plain string (the existing
+  shape — fully backward compatible) or `{ content, metadata }`. The `metadata`
+  field's type is inferred from the adapter via a new
+  `TSystemPromptMetadata` generic on `TextAdapter` / `BaseTextAdapter`:
+  - `@tanstack/ai-anthropic` declares `AnthropicSystemPromptMetadata` →
+    users get `cache_control` autocomplete and type-checking on
+    `systemPrompts[i].metadata` for Anthropic chats.
+  - Adapters with no per-prompt metadata (OpenAI, Gemini, Ollama,
+    OpenRouter, openai-base) inherit the default `never`, which means the
+    `metadata` field carries no meaningful value at the call site —
+    TypeScript only accepts `undefined` there. Provider-foreign metadata
+    that reaches an adapter via JS / `as any` is silently dropped, never
+    written to the wire.
+
+  ```ts
+  import { chat } from '@tanstack/ai'
+  import { anthropicText } from '@tanstack/ai-anthropic'
+
+  // Anthropic — `cache_control` is autocompleted, no `satisfies` needed.
+  chat({
+    adapter: anthropicText({ apiKey }, 'claude-sonnet-4-6'),
+    systemPrompts: [
+      {
+        content: 'Stable instructions — cache me.',
+        metadata: { cache_control: { type: 'ephemeral' } },
+      },
+      'Volatile per-request instruction.',
+    ],
+  })
+
+  // OpenAI — `metadata` is `never`; only `undefined` is assignable, so the
+  // field is effectively unusable. The object form without `metadata` still
+  // works for portability.
+  chat({
+    adapter: openaiText({ apiKey }, 'gpt-4o-mini'),
+    systemPrompts: [
+      'Plain string.',
+      { content: 'Object form without metadata is allowed.' },
+    ],
+  })
+  ```
+
+  New exports:
+  - `@tanstack/ai`: `SystemPrompt`, `NormalizedSystemPrompt` types and the
+    `normalizeSystemPrompts()` helper adapters use to normalize the wide
+    input shape to `{ content, metadata? }` before consumption.
+  - `@tanstack/ai-anthropic`: `AnthropicSystemPromptMetadata` interface
+    (currently exposes `cache_control` for prompt caching).
+
+  Internal:
+  - New `TSystemPromptMetadata = never` generic on `TextAdapter` /
+    `BaseTextAdapter`, surfaced via `'~types'['systemPromptMetadata']`
+    for inference at the `chat()` call site.
+  - Anthropic adapter reads `metadata.cache_control` and attaches it to
+    the corresponding `TextBlockParam`.
+  - All other text adapters call `normalizeSystemPrompts()` and join
+    `.content` for their respective `instructions` / `system` /
+    `systemInstruction` fields. Foreign metadata that reaches them via JS
+    / `as any` is dropped (never written to the wire).
+  - `normalizeSystemPrompts()` is the public API boundary and throws
+    `TypeError` (naming the offending index) for object-form entries whose
+    `content` isn't a string — preventing literal `"undefined"` from
+    reaching the model on stale call sites.
+  - OpenTelemetry middleware attaches per-prompt metadata as the
+    `tanstack.ai.system_prompt.metadata` JSON span attribute when
+    `captureContent: true` and at least one entry carries metadata, so
+    observability backends can distinguish cache hit/miss for Anthropic.
+  - `@tanstack/ai-event-client` mirrors the `SystemPrompt` shape locally
+    (avoids a circular import) and projects metadata away on the devtools
+    wire — devtools UI still receives `Array<string>`.
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+
 ## 0.10.6
 
 ### Patch Changes
diff --git a/packages/typescript/ai-gemini/package.json b/packages/typescript/ai-gemini/package.json
index ee3ca1116..7bda5cc93 100644
--- a/packages/typescript/ai-gemini/package.json
+++ b/packages/typescript/ai-gemini/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-gemini",
-  "version": "0.10.6",
+  "version": "0.10.7",
   "description": "Google Gemini adapter for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-grok/CHANGELOG.md b/packages/typescript/ai-grok/CHANGELOG.md
index b0f5d3dd2..7c4ca4e0c 100644
--- a/packages/typescript/ai-grok/CHANGELOG.md
+++ b/packages/typescript/ai-grok/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-grok
 
+## 0.8.4
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/openai-base@0.3.3
+
 ## 0.8.3
 
 ### Patch Changes
diff --git a/packages/typescript/ai-grok/package.json b/packages/typescript/ai-grok/package.json
index e0faa7f9d..f06addfa6 100644
--- a/packages/typescript/ai-grok/package.json
+++ b/packages/typescript/ai-grok/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-grok",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "Grok (xAI) adapter for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-groq/CHANGELOG.md b/packages/typescript/ai-groq/CHANGELOG.md
index cc09512f3..9d9d93cea 100644
--- a/packages/typescript/ai-groq/CHANGELOG.md
+++ b/packages/typescript/ai-groq/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-groq
 
+## 0.2.3
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/openai-base@0.3.3
+
 ## 0.2.2
 
 ### Patch Changes
diff --git a/packages/typescript/ai-groq/package.json b/packages/typescript/ai-groq/package.json
index ebcb60430..af6896459 100644
--- a/packages/typescript/ai-groq/package.json
+++ b/packages/typescript/ai-groq/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-groq",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "description": "Groq adapter for TanStack AI",
   "author": "",
diff --git a/packages/typescript/ai-isolate-cloudflare/CHANGELOG.md b/packages/typescript/ai-isolate-cloudflare/CHANGELOG.md
index f2c52f644..2cfed9e25 100644
--- a/packages/typescript/ai-isolate-cloudflare/CHANGELOG.md
+++ b/packages/typescript/ai-isolate-cloudflare/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @tanstack/ai-isolate-cloudflare
 
+## 0.2.6
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/ai-code-mode@0.1.15
+
 ## 0.2.5
 
 ### Patch Changes
diff --git a/packages/typescript/ai-isolate-cloudflare/package.json b/packages/typescript/ai-isolate-cloudflare/package.json
index 0ee3b8394..35a342a34 100644
--- a/packages/typescript/ai-isolate-cloudflare/package.json
+++ b/packages/typescript/ai-isolate-cloudflare/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-isolate-cloudflare",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Cloudflare Workers driver for TanStack AI Code Mode - execute code on the edge",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-isolate-node/CHANGELOG.md b/packages/typescript/ai-isolate-node/CHANGELOG.md
index 9337b6933..e4b4446d3 100644
--- a/packages/typescript/ai-isolate-node/CHANGELOG.md
+++ b/packages/typescript/ai-isolate-node/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @tanstack/ai-isolate-node
 
+## 0.1.15
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/ai-code-mode@0.1.15
+
 ## 0.1.14
 
 ### Patch Changes
diff --git a/packages/typescript/ai-isolate-node/package.json b/packages/typescript/ai-isolate-node/package.json
index 23b348cfc..6c01938a1 100644
--- a/packages/typescript/ai-isolate-node/package.json
+++ b/packages/typescript/ai-isolate-node/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-isolate-node",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Node.js isolated-vm driver for TanStack AI Code Mode",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-isolate-quickjs/CHANGELOG.md b/packages/typescript/ai-isolate-quickjs/CHANGELOG.md
index dd138f061..e80e7c3af 100644
--- a/packages/typescript/ai-isolate-quickjs/CHANGELOG.md
+++ b/packages/typescript/ai-isolate-quickjs/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @tanstack/ai-isolate-quickjs
 
+## 0.1.15
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/ai-code-mode@0.1.15
+
 ## 0.1.14
 
 ### Patch Changes
diff --git a/packages/typescript/ai-isolate-quickjs/package.json b/packages/typescript/ai-isolate-quickjs/package.json
index 64f9d807c..154d5cb69 100644
--- a/packages/typescript/ai-isolate-quickjs/package.json
+++ b/packages/typescript/ai-isolate-quickjs/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-isolate-quickjs",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "QuickJS WASM driver for TanStack AI Code Mode - runs everywhere",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-ollama/CHANGELOG.md b/packages/typescript/ai-ollama/CHANGELOG.md
index d1d4b1239..acd471b9f 100644
--- a/packages/typescript/ai-ollama/CHANGELOG.md
+++ b/packages/typescript/ai-ollama/CHANGELOG.md
@@ -1,5 +1,85 @@
 # @tanstack/ai-ollama
 
+## 0.6.18
+
+### Patch Changes
+
+- feat(ai): `systemPrompts` accept `{ content, metadata }` with adapter-inferred metadata typing ([#575](https://github.com/TanStack/ai/pull/575))
+
+  `chat({ systemPrompts })` now accepts either a plain string (the existing
+  shape — fully backward compatible) or `{ content, metadata }`. The `metadata`
+  field's type is inferred from the adapter via a new
+  `TSystemPromptMetadata` generic on `TextAdapter` / `BaseTextAdapter`:
+  - `@tanstack/ai-anthropic` declares `AnthropicSystemPromptMetadata` →
+    users get `cache_control` autocomplete and type-checking on
+    `systemPrompts[i].metadata` for Anthropic chats.
+  - Adapters with no per-prompt metadata (OpenAI, Gemini, Ollama,
+    OpenRouter, openai-base) inherit the default `never`, which means the
+    `metadata` field carries no meaningful value at the call site —
+    TypeScript only accepts `undefined` there. Provider-foreign metadata
+    that reaches an adapter via JS / `as any` is silently dropped, never
+    written to the wire.
+
+  ```ts
+  import { chat } from '@tanstack/ai'
+  import { anthropicText } from '@tanstack/ai-anthropic'
+
+  // Anthropic — `cache_control` is autocompleted, no `satisfies` needed.
+  chat({
+    adapter: anthropicText({ apiKey }, 'claude-sonnet-4-6'),
+    systemPrompts: [
+      {
+        content: 'Stable instructions — cache me.',
+        metadata: { cache_control: { type: 'ephemeral' } },
+      },
+      'Volatile per-request instruction.',
+    ],
+  })
+
+  // OpenAI — `metadata` is `never`; only `undefined` is assignable, so the
+  // field is effectively unusable. The object form without `metadata` still
+  // works for portability.
+  chat({
+    adapter: openaiText({ apiKey }, 'gpt-4o-mini'),
+    systemPrompts: [
+      'Plain string.',
+      { content: 'Object form without metadata is allowed.' },
+    ],
+  })
+  ```
+
+  New exports:
+  - `@tanstack/ai`: `SystemPrompt`, `NormalizedSystemPrompt` types and the
+    `normalizeSystemPrompts()` helper adapters use to normalize the wide
+    input shape to `{ content, metadata? }` before consumption.
+  - `@tanstack/ai-anthropic`: `AnthropicSystemPromptMetadata` interface
+    (currently exposes `cache_control` for prompt caching).
+
+  Internal:
+  - New `TSystemPromptMetadata = never` generic on `TextAdapter` /
+    `BaseTextAdapter`, surfaced via `'~types'['systemPromptMetadata']`
+    for inference at the `chat()` call site.
+  - Anthropic adapter reads `metadata.cache_control` and attaches it to
+    the corresponding `TextBlockParam`.
+  - All other text adapters call `normalizeSystemPrompts()` and join
+    `.content` for their respective `instructions` / `system` /
+    `systemInstruction` fields. Foreign metadata that reaches them via JS
+    / `as any` is dropped (never written to the wire).
+  - `normalizeSystemPrompts()` is the public API boundary and throws
+    `TypeError` (naming the offending index) for object-form entries whose
+    `content` isn't a string — preventing literal `"undefined"` from
+    reaching the model on stale call sites.
+  - OpenTelemetry middleware attaches per-prompt metadata as the
+    `tanstack.ai.system_prompt.metadata` JSON span attribute when
+    `captureContent: true` and at least one entry carries metadata, so
+    observability backends can distinguish cache hit/miss for Anthropic.
+  - `@tanstack/ai-event-client` mirrors the `SystemPrompt` shape locally
+    (avoids a circular import) and projects metadata away on the devtools
+    wire — devtools UI still receives `Array<string>`.
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+
 ## 0.6.17
 
 ### Patch Changes
diff --git a/packages/typescript/ai-ollama/package.json b/packages/typescript/ai-ollama/package.json
index 68bce909d..4a1eea6a4 100644
--- a/packages/typescript/ai-ollama/package.json
+++ b/packages/typescript/ai-ollama/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-ollama",
-  "version": "0.6.17",
+  "version": "0.6.18",
   "description": "Ollama adapter for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-openai/CHANGELOG.md b/packages/typescript/ai-openai/CHANGELOG.md
index 0e7a4a74d..24be2f44c 100644
--- a/packages/typescript/ai-openai/CHANGELOG.md
+++ b/packages/typescript/ai-openai/CHANGELOG.md
@@ -1,5 +1,87 @@
 # @tanstack/ai-openai
 
+## 0.9.4
+
+### Patch Changes
+
+- feat(ai): `systemPrompts` accept `{ content, metadata }` with adapter-inferred metadata typing ([#575](https://github.com/TanStack/ai/pull/575))
+
+  `chat({ systemPrompts })` now accepts either a plain string (the existing
+  shape — fully backward compatible) or `{ content, metadata }`. The `metadata`
+  field's type is inferred from the adapter via a new
+  `TSystemPromptMetadata` generic on `TextAdapter` / `BaseTextAdapter`:
+  - `@tanstack/ai-anthropic` declares `AnthropicSystemPromptMetadata` →
+    users get `cache_control` autocomplete and type-checking on
+    `systemPrompts[i].metadata` for Anthropic chats.
+  - Adapters with no per-prompt metadata (OpenAI, Gemini, Ollama,
+    OpenRouter, openai-base) inherit the default `never`, which means the
+    `metadata` field carries no meaningful value at the call site —
+    TypeScript only accepts `undefined` there. Provider-foreign metadata
+    that reaches an adapter via JS / `as any` is silently dropped, never
+    written to the wire.
+
+  ```ts
+  import { chat } from '@tanstack/ai'
+  import { anthropicText } from '@tanstack/ai-anthropic'
+
+  // Anthropic — `cache_control` is autocompleted, no `satisfies` needed.
+  chat({
+    adapter: anthropicText({ apiKey }, 'claude-sonnet-4-6'),
+    systemPrompts: [
+      {
+        content: 'Stable instructions — cache me.',
+        metadata: { cache_control: { type: 'ephemeral' } },
+      },
+      'Volatile per-request instruction.',
+    ],
+  })
+
+  // OpenAI — `metadata` is `never`; only `undefined` is assignable, so the
+  // field is effectively unusable. The object form without `metadata` still
+  // works for portability.
+  chat({
+    adapter: openaiText({ apiKey }, 'gpt-4o-mini'),
+    systemPrompts: [
+      'Plain string.',
+      { content: 'Object form without metadata is allowed.' },
+    ],
+  })
+  ```
+
+  New exports:
+  - `@tanstack/ai`: `SystemPrompt`, `NormalizedSystemPrompt` types and the
+    `normalizeSystemPrompts()` helper adapters use to normalize the wide
+    input shape to `{ content, metadata? }` before consumption.
+  - `@tanstack/ai-anthropic`: `AnthropicSystemPromptMetadata` interface
+    (currently exposes `cache_control` for prompt caching).
+
+  Internal:
+  - New `TSystemPromptMetadata = never` generic on `TextAdapter` /
+    `BaseTextAdapter`, surfaced via `'~types'['systemPromptMetadata']`
+    for inference at the `chat()` call site.
+  - Anthropic adapter reads `metadata.cache_control` and attaches it to
+    the corresponding `TextBlockParam`.
+  - All other text adapters call `normalizeSystemPrompts()` and join
+    `.content` for their respective `instructions` / `system` /
+    `systemInstruction` fields. Foreign metadata that reaches them via JS
+    / `as any` is dropped (never written to the wire).
+  - `normalizeSystemPrompts()` is the public API boundary and throws
+    `TypeError` (naming the offending index) for object-form entries whose
+    `content` isn't a string — preventing literal `"undefined"` from
+    reaching the model on stale call sites.
+  - OpenTelemetry middleware attaches per-prompt metadata as the
+    `tanstack.ai.system_prompt.metadata` JSON span attribute when
+    `captureContent: true` and at least one entry carries metadata, so
+    observability backends can distinguish cache hit/miss for Anthropic.
+  - `@tanstack/ai-event-client` mirrors the `SystemPrompt` shape locally
+    (avoids a circular import) and projects metadata away on the devtools
+    wire — devtools UI still receives `Array<string>`.
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/openai-base@0.3.3
+  - @tanstack/ai-client@0.11.2
+
 ## 0.9.3
 
 ### Patch Changes
diff --git a/packages/typescript/ai-openai/package.json b/packages/typescript/ai-openai/package.json
index afc04e21d..f073bb8af 100644
--- a/packages/typescript/ai-openai/package.json
+++ b/packages/typescript/ai-openai/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-openai",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "OpenAI adapter for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-openrouter/CHANGELOG.md b/packages/typescript/ai-openrouter/CHANGELOG.md
index 48bff83a2..a6c7429d8 100644
--- a/packages/typescript/ai-openrouter/CHANGELOG.md
+++ b/packages/typescript/ai-openrouter/CHANGELOG.md
@@ -1,5 +1,85 @@
 # @tanstack/ai-openrouter
 
+## 0.9.4
+
+### Patch Changes
+
+- feat(ai): `systemPrompts` accept `{ content, metadata }` with adapter-inferred metadata typing ([#575](https://github.com/TanStack/ai/pull/575))
+
+  `chat({ systemPrompts })` now accepts either a plain string (the existing
+  shape — fully backward compatible) or `{ content, metadata }`. The `metadata`
+  field's type is inferred from the adapter via a new
+  `TSystemPromptMetadata` generic on `TextAdapter` / `BaseTextAdapter`:
+  - `@tanstack/ai-anthropic` declares `AnthropicSystemPromptMetadata` →
+    users get `cache_control` autocomplete and type-checking on
+    `systemPrompts[i].metadata` for Anthropic chats.
+  - Adapters with no per-prompt metadata (OpenAI, Gemini, Ollama,
+    OpenRouter, openai-base) inherit the default `never`, which means the
+    `metadata` field carries no meaningful value at the call site —
+    TypeScript only accepts `undefined` there. Provider-foreign metadata
+    that reaches an adapter via JS / `as any` is silently dropped, never
+    written to the wire.
+
+  ```ts
+  import { chat } from '@tanstack/ai'
+  import { anthropicText } from '@tanstack/ai-anthropic'
+
+  // Anthropic — `cache_control` is autocompleted, no `satisfies` needed.
+  chat({
+    adapter: anthropicText({ apiKey }, 'claude-sonnet-4-6'),
+    systemPrompts: [
+      {
+        content: 'Stable instructions — cache me.',
+        metadata: { cache_control: { type: 'ephemeral' } },
+      },
+      'Volatile per-request instruction.',
+    ],
+  })
+
+  // OpenAI — `metadata` is `never`; only `undefined` is assignable, so the
+  // field is effectively unusable. The object form without `metadata` still
+  // works for portability.
+  chat({
+    adapter: openaiText({ apiKey }, 'gpt-4o-mini'),
+    systemPrompts: [
+      'Plain string.',
+      { content: 'Object form without metadata is allowed.' },
+    ],
+  })
+  ```
+
+  New exports:
+  - `@tanstack/ai`: `SystemPrompt`, `NormalizedSystemPrompt` types and the
+    `normalizeSystemPrompts()` helper adapters use to normalize the wide
+    input shape to `{ content, metadata? }` before consumption.
+  - `@tanstack/ai-anthropic`: `AnthropicSystemPromptMetadata` interface
+    (currently exposes `cache_control` for prompt caching).
+
+  Internal:
+  - New `TSystemPromptMetadata = never` generic on `TextAdapter` /
+    `BaseTextAdapter`, surfaced via `'~types'['systemPromptMetadata']`
+    for inference at the `chat()` call site.
+  - Anthropic adapter reads `metadata.cache_control` and attaches it to
+    the corresponding `TextBlockParam`.
+  - All other text adapters call `normalizeSystemPrompts()` and join
+    `.content` for their respective `instructions` / `system` /
+    `systemInstruction` fields. Foreign metadata that reaches them via JS
+    / `as any` is dropped (never written to the wire).
+  - `normalizeSystemPrompts()` is the public API boundary and throws
+    `TypeError` (naming the offending index) for object-form entries whose
+    `content` isn't a string — preventing literal `"undefined"` from
+    reaching the model on stale call sites.
+  - OpenTelemetry middleware attaches per-prompt metadata as the
+    `tanstack.ai.system_prompt.metadata` JSON span attribute when
+    `captureContent: true` and at least one entry carries metadata, so
+    observability backends can distinguish cache hit/miss for Anthropic.
+  - `@tanstack/ai-event-client` mirrors the `SystemPrompt` shape locally
+    (avoids a circular import) and projects metadata away on the devtools
+    wire — devtools UI still receives `Array<string>`.
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+
 ## 0.9.3
 
 ### Patch Changes
diff --git a/packages/typescript/ai-openrouter/package.json b/packages/typescript/ai-openrouter/package.json
index 16c1d50ba..8f9e5cc5c 100644
--- a/packages/typescript/ai-openrouter/package.json
+++ b/packages/typescript/ai-openrouter/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-openrouter",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "OpenRouter adapter for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-preact/CHANGELOG.md b/packages/typescript/ai-preact/CHANGELOG.md
index 5ea9455da..68c75b777 100644
--- a/packages/typescript/ai-preact/CHANGELOG.md
+++ b/packages/typescript/ai-preact/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-preact
 
+## 0.6.27
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-client@0.11.2
+
 ## 0.6.26
 
 ### Patch Changes
diff --git a/packages/typescript/ai-preact/package.json b/packages/typescript/ai-preact/package.json
index 5b4e43276..40203aa64 100644
--- a/packages/typescript/ai-preact/package.json
+++ b/packages/typescript/ai-preact/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-preact",
-  "version": "0.6.26",
+  "version": "0.6.27",
   "description": "Preact hooks for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-react/CHANGELOG.md b/packages/typescript/ai-react/CHANGELOG.md
index e83c3e409..1fa7dbccf 100644
--- a/packages/typescript/ai-react/CHANGELOG.md
+++ b/packages/typescript/ai-react/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-react
 
+## 0.11.2
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-client@0.11.2
+
 ## 0.11.1
 
 ### Patch Changes
diff --git a/packages/typescript/ai-react/package.json b/packages/typescript/ai-react/package.json
index 641910fb0..57c4078aa 100644
--- a/packages/typescript/ai-react/package.json
+++ b/packages/typescript/ai-react/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-react",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "React hooks for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-solid/CHANGELOG.md b/packages/typescript/ai-solid/CHANGELOG.md
index 2f165b4f7..18604fe39 100644
--- a/packages/typescript/ai-solid/CHANGELOG.md
+++ b/packages/typescript/ai-solid/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-solid
 
+## 0.10.2
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-client@0.11.2
+
 ## 0.10.1
 
 ### Patch Changes
diff --git a/packages/typescript/ai-solid/package.json b/packages/typescript/ai-solid/package.json
index bb4f513e2..27709911c 100644
--- a/packages/typescript/ai-solid/package.json
+++ b/packages/typescript/ai-solid/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-solid",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Solid hooks for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-svelte/CHANGELOG.md b/packages/typescript/ai-svelte/CHANGELOG.md
index 7330d6f43..985fadb0e 100644
--- a/packages/typescript/ai-svelte/CHANGELOG.md
+++ b/packages/typescript/ai-svelte/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-svelte
 
+## 0.10.2
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-client@0.11.2
+
 ## 0.10.1
 
 ### Patch Changes
diff --git a/packages/typescript/ai-svelte/package.json b/packages/typescript/ai-svelte/package.json
index 7c5d25afb..73e955551 100644
--- a/packages/typescript/ai-svelte/package.json
+++ b/packages/typescript/ai-svelte/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-svelte",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Svelte bindings for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai-vue-ui/CHANGELOG.md b/packages/typescript/ai-vue-ui/CHANGELOG.md
index f7b5aa743..dd68299e8 100644
--- a/packages/typescript/ai-vue-ui/CHANGELOG.md
+++ b/packages/typescript/ai-vue-ui/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @tanstack/ai-vue-ui
 
+## 0.1.39
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/ai-vue@0.10.3
+
 ## 0.1.38
 
 ### Patch Changes
diff --git a/packages/typescript/ai-vue-ui/package.json b/packages/typescript/ai-vue-ui/package.json
index f4c19dccb..da5347436 100644
--- a/packages/typescript/ai-vue-ui/package.json
+++ b/packages/typescript/ai-vue-ui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-vue-ui",
-  "version": "0.1.38",
+  "version": "0.1.39",
   "description": "Headless Vue components for building AI chat interfaces",
   "module": "./src/index.ts",
   "types": "./src/index.ts",
diff --git a/packages/typescript/ai-vue/CHANGELOG.md b/packages/typescript/ai-vue/CHANGELOG.md
index 63798df37..2c59e9c21 100644
--- a/packages/typescript/ai-vue/CHANGELOG.md
+++ b/packages/typescript/ai-vue/CHANGELOG.md
@@ -1,5 +1,13 @@
 # @tanstack/ai-vue
 
+## 0.10.3
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+  - @tanstack/ai-client@0.11.2
+
 ## 0.10.2
 
 ### Patch Changes
diff --git a/packages/typescript/ai-vue/package.json b/packages/typescript/ai-vue/package.json
index 7ce13bec0..268f37aee 100644
--- a/packages/typescript/ai-vue/package.json
+++ b/packages/typescript/ai-vue/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-vue",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "description": "Vue hooks for TanStack AI",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/ai/CHANGELOG.md b/packages/typescript/ai/CHANGELOG.md
index 175b34a74..5dd176004 100644
--- a/packages/typescript/ai/CHANGELOG.md
+++ b/packages/typescript/ai/CHANGELOG.md
@@ -1,5 +1,87 @@
 # @tanstack/ai
 
+## 0.20.0
+
+### Minor Changes
+
+- feat(ai): `systemPrompts` accept `{ content, metadata }` with adapter-inferred metadata typing ([#575](https://github.com/TanStack/ai/pull/575))
+
+  `chat({ systemPrompts })` now accepts either a plain string (the existing
+  shape — fully backward compatible) or `{ content, metadata }`. The `metadata`
+  field's type is inferred from the adapter via a new
+  `TSystemPromptMetadata` generic on `TextAdapter` / `BaseTextAdapter`:
+  - `@tanstack/ai-anthropic` declares `AnthropicSystemPromptMetadata` →
+    users get `cache_control` autocomplete and type-checking on
+    `systemPrompts[i].metadata` for Anthropic chats.
+  - Adapters with no per-prompt metadata (OpenAI, Gemini, Ollama,
+    OpenRouter, openai-base) inherit the default `never`, which means the
+    `metadata` field carries no meaningful value at the call site —
+    TypeScript only accepts `undefined` there. Provider-foreign metadata
+    that reaches an adapter via JS / `as any` is silently dropped, never
+    written to the wire.
+
+  ```ts
+  import { chat } from '@tanstack/ai'
+  import { anthropicText } from '@tanstack/ai-anthropic'
+
+  // Anthropic — `cache_control` is autocompleted, no `satisfies` needed.
+  chat({
+    adapter: anthropicText({ apiKey }, 'claude-sonnet-4-6'),
+    systemPrompts: [
+      {
+        content: 'Stable instructions — cache me.',
+        metadata: { cache_control: { type: 'ephemeral' } },
+      },
+      'Volatile per-request instruction.',
+    ],
+  })
+
+  // OpenAI — `metadata` is `never`; only `undefined` is assignable, so the
+  // field is effectively unusable. The object form without `metadata` still
+  // works for portability.
+  chat({
+    adapter: openaiText({ apiKey }, 'gpt-4o-mini'),
+    systemPrompts: [
+      'Plain string.',
+      { content: 'Object form without metadata is allowed.' },
+    ],
+  })
+  ```
+
+  New exports:
+  - `@tanstack/ai`: `SystemPrompt`, `NormalizedSystemPrompt` types and the
+    `normalizeSystemPrompts()` helper adapters use to normalize the wide
+    input shape to `{ content, metadata? }` before consumption.
+  - `@tanstack/ai-anthropic`: `AnthropicSystemPromptMetadata` interface
+    (currently exposes `cache_control` for prompt caching).
+
+  Internal:
+  - New `TSystemPromptMetadata = never` generic on `TextAdapter` /
+    `BaseTextAdapter`, surfaced via `'~types'['systemPromptMetadata']`
+    for inference at the `chat()` call site.
+  - Anthropic adapter reads `metadata.cache_control` and attaches it to
+    the corresponding `TextBlockParam`.
+  - All other text adapters call `normalizeSystemPrompts()` and join
+    `.content` for their respective `instructions` / `system` /
+    `systemInstruction` fields. Foreign metadata that reaches them via JS
+    / `as any` is dropped (never written to the wire).
+  - `normalizeSystemPrompts()` is the public API boundary and throws
+    `TypeError` (naming the offending index) for object-form entries whose
+    `content` isn't a string — preventing literal `"undefined"` from
+    reaching the model on stale call sites.
+  - OpenTelemetry middleware attaches per-prompt metadata as the
+    `tanstack.ai.system_prompt.metadata` JSON span attribute when
+    `captureContent: true` and at least one entry carries metadata, so
+    observability backends can distinguish cache hit/miss for Anthropic.
+  - `@tanstack/ai-event-client` mirrors the `SystemPrompt` shape locally
+    (avoids a circular import) and projects metadata away on the devtools
+    wire — devtools UI still receives `Array<string>`.
+
+### Patch Changes
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai-event-client@0.3.5
+
 ## 0.19.1
 
 ### Patch Changes
diff --git a/packages/typescript/ai/package.json b/packages/typescript/ai/package.json
index 1d6677911..752cb97b0 100644
--- a/packages/typescript/ai/package.json
+++ b/packages/typescript/ai/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "Core TanStack AI library - Open source AI SDK",
   "author": "Tanner Linsley",
   "license": "MIT",
diff --git a/packages/typescript/openai-base/CHANGELOG.md b/packages/typescript/openai-base/CHANGELOG.md
index 131f01ce5..d2566fc02 100644
--- a/packages/typescript/openai-base/CHANGELOG.md
+++ b/packages/typescript/openai-base/CHANGELOG.md
@@ -1,5 +1,85 @@
 # @tanstack/openai-base
 
+## 0.3.3
+
+### Patch Changes
+
+- feat(ai): `systemPrompts` accept `{ content, metadata }` with adapter-inferred metadata typing ([#575](https://github.com/TanStack/ai/pull/575))
+
+  `chat({ systemPrompts })` now accepts either a plain string (the existing
+  shape — fully backward compatible) or `{ content, metadata }`. The `metadata`
+  field's type is inferred from the adapter via a new
+  `TSystemPromptMetadata` generic on `TextAdapter` / `BaseTextAdapter`:
+  - `@tanstack/ai-anthropic` declares `AnthropicSystemPromptMetadata` →
+    users get `cache_control` autocomplete and type-checking on
+    `systemPrompts[i].metadata` for Anthropic chats.
+  - Adapters with no per-prompt metadata (OpenAI, Gemini, Ollama,
+    OpenRouter, openai-base) inherit the default `never`, which means the
+    `metadata` field carries no meaningful value at the call site —
+    TypeScript only accepts `undefined` there. Provider-foreign metadata
+    that reaches an adapter via JS / `as any` is silently dropped, never
+    written to the wire.
+
+  ```ts
+  import { chat } from '@tanstack/ai'
+  import { anthropicText } from '@tanstack/ai-anthropic'
+
+  // Anthropic — `cache_control` is autocompleted, no `satisfies` needed.
+  chat({
+    adapter: anthropicText({ apiKey }, 'claude-sonnet-4-6'),
+    systemPrompts: [
+      {
+        content: 'Stable instructions — cache me.',
+        metadata: { cache_control: { type: 'ephemeral' } },
+      },
+      'Volatile per-request instruction.',
+    ],
+  })
+
+  // OpenAI — `metadata` is `never`; only `undefined` is assignable, so the
+  // field is effectively unusable. The object form without `metadata` still
+  // works for portability.
+  chat({
+    adapter: openaiText({ apiKey }, 'gpt-4o-mini'),
+    systemPrompts: [
+      'Plain string.',
+      { content: 'Object form without metadata is allowed.' },
+    ],
+  })
+  ```
+
+  New exports:
+  - `@tanstack/ai`: `SystemPrompt`, `NormalizedSystemPrompt` types and the
+    `normalizeSystemPrompts()` helper adapters use to normalize the wide
+    input shape to `{ content, metadata? }` before consumption.
+  - `@tanstack/ai-anthropic`: `AnthropicSystemPromptMetadata` interface
+    (currently exposes `cache_control` for prompt caching).
+
+  Internal:
+  - New `TSystemPromptMetadata = never` generic on `TextAdapter` /
+    `BaseTextAdapter`, surfaced via `'~types'['systemPromptMetadata']`
+    for inference at the `chat()` call site.
+  - Anthropic adapter reads `metadata.cache_control` and attaches it to
+    the corresponding `TextBlockParam`.
+  - All other text adapters call `normalizeSystemPrompts()` and join
+    `.content` for their respective `instructions` / `system` /
+    `systemInstruction` fields. Foreign metadata that reaches them via JS
+    / `as any` is dropped (never written to the wire).
+  - `normalizeSystemPrompts()` is the public API boundary and throws
+    `TypeError` (naming the offending index) for object-form entries whose
+    `content` isn't a string — preventing literal `"undefined"` from
+    reaching the model on stale call sites.
+  - OpenTelemetry middleware attaches per-prompt metadata as the
+    `tanstack.ai.system_prompt.metadata` JSON span attribute when
+    `captureContent: true` and at least one entry carries metadata, so
+    observability backends can distinguish cache hit/miss for Anthropic.
+  - `@tanstack/ai-event-client` mirrors the `SystemPrompt` shape locally
+    (avoids a circular import) and projects metadata away on the devtools
+    wire — devtools UI still receives `Array<string>`.
+
+- Updated dependencies [[`496db9c`](https://github.com/TanStack/ai/commit/496db9c42a7d3051a1295091eae29ae1c31ef997)]:
+  - @tanstack/ai@0.20.0
+
 ## 0.3.2
 
 ### Patch Changes
diff --git a/packages/typescript/openai-base/package.json b/packages/typescript/openai-base/package.json
index e7231f4a5..30af4d8c2 100644
--- a/packages/typescript/openai-base/package.json
+++ b/packages/typescript/openai-base/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/openai-base",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Shared base adapters for OpenAI-SDK-backed providers in TanStack AI (Chat Completions and Responses)",
   "author": "",
   "license": "MIT",
diff --git a/packages/typescript/preact-ai-devtools/CHANGELOG.md b/packages/typescript/preact-ai-devtools/CHANGELOG.md
index f8178c2d9..ecad33cb7 100644
--- a/packages/typescript/preact-ai-devtools/CHANGELOG.md
+++ b/packages/typescript/preact-ai-devtools/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @tanstack/preact-ai-devtools
 
+## 0.1.36
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/ai-devtools-core@0.3.32
+
 ## 0.1.35
 
 ### Patch Changes
diff --git a/packages/typescript/preact-ai-devtools/package.json b/packages/typescript/preact-ai-devtools/package.json
index 532d4cd6f..6c13fd5a0 100644
--- a/packages/typescript/preact-ai-devtools/package.json
+++ b/packages/typescript/preact-ai-devtools/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/preact-ai-devtools",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "description": "Preact Devtools for TanStack AI.",
   "author": "tannerlinsley",
   "license": "MIT",
diff --git a/packages/typescript/react-ai-devtools/CHANGELOG.md b/packages/typescript/react-ai-devtools/CHANGELOG.md
index 7fd712111..0cc9b2e64 100644
--- a/packages/typescript/react-ai-devtools/CHANGELOG.md
+++ b/packages/typescript/react-ai-devtools/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @tanstack/react-ai-devtools
 
+## 0.2.36
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/ai-devtools-core@0.3.32
+
 ## 0.2.35
 
 ### Patch Changes
diff --git a/packages/typescript/react-ai-devtools/package.json b/packages/typescript/react-ai-devtools/package.json
index 0a4c68dbd..1cd8ead7d 100644
--- a/packages/typescript/react-ai-devtools/package.json
+++ b/packages/typescript/react-ai-devtools/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-ai-devtools",
-  "version": "0.2.35",
+  "version": "0.2.36",
   "description": "React Devtools for TanStack AI.",
   "author": "tannerlinsley",
   "license": "MIT",
diff --git a/packages/typescript/solid-ai-devtools/CHANGELOG.md b/packages/typescript/solid-ai-devtools/CHANGELOG.md
index 4494113ad..377d09b73 100644
--- a/packages/typescript/solid-ai-devtools/CHANGELOG.md
+++ b/packages/typescript/solid-ai-devtools/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @tanstack/solid-ai-devtools
 
+## 0.2.36
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @tanstack/ai-devtools-core@0.3.32
+
 ## 0.2.35
 
 ### Patch Changes
diff --git a/packages/typescript/solid-ai-devtools/package.json b/packages/typescript/solid-ai-devtools/package.json
index 639d840b5..fd9841d7a 100644
--- a/packages/typescript/solid-ai-devtools/package.json
+++ b/packages/typescript/solid-ai-devtools/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/solid-ai-devtools",
-  "version": "0.2.35",
+  "version": "0.2.36",
   "description": "Solid TanStack AI Devtools",
   "author": "",
   "license": "MIT",