diff --git a/docs/ai/agent.md b/docs/ai/agent.md
index d9a512d..f63ebd5 100644
--- a/docs/ai/agent.md
+++ b/docs/ai/agent.md
@@ -7,6 +7,10 @@ keywords: AI agents, Anthropic, OpenAI, Google Gemini, LLM, tool calling, stream
 
 # AI Agents
 
+::: warning Active development
+The AI package is under active development. APIs may change without notice as we experiment with the best integration patterns. Use with caution in production.
+:::
+
 FastAPI Startkit includes a declarative, **LangChain-powered AI agent module** that lets you build provider-agnostic LLM agents as plain Python classes. Swap between Anthropic, OpenAI, and Google with a single environment variable; attach tools, documents, structured-output schemas, and middleware; and test everything offline with built-in faking and record/replay utilities.
 
 ## Introduction
diff --git a/docs/ai/audio.md b/docs/ai/audio.md
index 9c884b9..43a49b5 100644
--- a/docs/ai/audio.md
+++ b/docs/ai/audio.md
@@ -7,6 +7,10 @@ keywords: audio generation, text-to-speech, TTS, OpenAI, Google Gemini, ElevenLa
 
 # Audio Generation
 
+::: warning Active development
+The AI package is under active development. APIs may change without notice as we experiment with the best integration patterns. Use with caution in production.
+:::
+
 FastAPI Startkit ships a fluent, provider-agnostic **text-to-speech** API. Turn any string into spoken audio, pick a voice, and persist the result to any configured storage disk — all in a single chained expression.
 
 ## Introduction
diff --git a/docs/ai/image.md b/docs/ai/image.md
index 7b2f8a2..8e94ee5 100644
--- a/docs/ai/image.md
+++ b/docs/ai/image.md
@@ -7,6 +7,10 @@ keywords: image generation, text-to-image, DALL-E, Imagen, OpenAI, Google Gemini
 
 # Image Generation
 
+::: warning Active development
+The AI package is under active development. APIs may change without notice as we experiment with the best integration patterns. Use with caution in production.
+:::
+
 FastAPI Startkit ships a fluent, provider-agnostic **image generation** API. Describe an image in plain text, optionally attach a source photo for editing, and persist the result to any configured storage disk — all with a single chained expression.
 
 ## Introduction
diff --git a/docs/ai/mcp.md b/docs/ai/mcp.md
index 69631ed..71cb401 100644
--- a/docs/ai/mcp.md
+++ b/docs/ai/mcp.md
@@ -7,6 +7,10 @@ keywords: MCP, Model Context Protocol, JSON-RPC, AI tools, FastAPI, fastapi-star
 
 # MCP (Model Context Protocol)
 
+::: warning Active development
+The AI package is under active development. APIs may change without notice as we experiment with the best integration patterns. Use with caution in production.
+:::
+
 The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is a JSON-RPC 2.0 standard that lets AI assistants — such as Claude, Cursor, and other MCP-compatible clients — discover and call capabilities exposed by your application. `fastapi-startkit` includes built-in support for MCP: define servers, tools, prompts, and resources as plain Python classes and mount them on your app with a single line.
 
 ## Getting Started
diff --git a/docs/ai/skills.md b/docs/ai/skills.md
index 0e05cc6..782584e 100644
--- a/docs/ai/skills.md
+++ b/docs/ai/skills.md
@@ -7,6 +7,10 @@ keywords: AI skills, Claude Code, Gemini CLI, artisan, fastapi-startkit
 
 # Skills
 
+::: warning Active development
+The AI package is under active development. APIs may change without notice as we experiment with the best integration patterns. Use with caution in production.
+:::
+
 The Skills module syncs provider-declared `SKILL.md` documents to your local AI coding tools — [Claude Code](https://claude.ai/code) and [Gemini CLI](https://github.com/google-gemini/gemini-cli).
 
 ## Registration