refactor(docs): create migration-guides section, move migration pages from troubleshooting

AlemTuzlak · AlemTuzlak · commit 0fd3ddf960bd · 2026-04-06T14:55:09.000+02:00
- New docs/(root)/migration-guides/ section with migrate-to-v2, migrate-attachments, migrate-to-1.10.X, migrate-to-1.8.2 - Troubleshooting now only contains error-debugging, observability-connectors, common-issues - Update all @deprecated JSDoc URLs from /troubleshooting/ to /migration-guides/ - Update doc cross-links (multimodal-attachments page, snippet import) - Move snippet to snippets/shared/migration-guides/ - Set minimum version to v1.56.0 (was vX.Y.Z placeholder)
diff --git a/docs/content/docs/(root)/meta.json b/docs/content/docs/(root)/meta.json
@@ -20,6 +20,8 @@
     "...backend",
     "---Premium Features---",
     "...premium",
+    "---Migration Guides---",
+    "...migration-guides",
     "---Troubleshooting---",
     "...troubleshooting",
     "---Other---",
diff --git a/docs/content/docs/(root)/migration-guides/meta.json b/docs/content/docs/(root)/migration-guides/meta.json
@@ -0,0 +1,10 @@
+{
+  "title": "Migration Guides",
+  "icon": "lucide/RefreshCw",
+  "pages": [
+    "migrate-to-v2",
+    "migrate-attachments",
+    "migrate-to-1.10.X",
+    "migrate-to-1.8.2"
+  ]
+}
diff --git a/docs/content/docs/(root)/migration-guides/migrate-attachments.mdx b/docs/content/docs/(root)/migration-guides/migrate-attachments.mdx
@@ -4,6 +4,6 @@ description: Migration guide for upgrading from imageUploadsEnabled to the new a
 icon: "lucide/RefreshCw"
 ---
 
-import MigrateAttachments from "@/snippets/shared/troubleshooting/migrate-attachments.mdx";
+import MigrateAttachments from "@/snippets/shared/migration-guides/migrate-attachments.mdx";
 
 <MigrateAttachments components={props.components} />
diff --git a/docs/content/docs/(root)/migration-guides/migrate-to-1.10.X.mdx b/docs/content/docs/(root)/migration-guides/migrate-to-1.10.X.mdx
diff --git a/docs/content/docs/(root)/migration-guides/migrate-to-1.8.2.mdx b/docs/content/docs/(root)/migration-guides/migrate-to-1.8.2.mdx
diff --git a/docs/content/docs/(root)/migration-guides/migrate-to-v2.mdx b/docs/content/docs/(root)/migration-guides/migrate-to-v2.mdx
diff --git a/docs/content/docs/(root)/multimodal-attachments.mdx b/docs/content/docs/(root)/multimodal-attachments.mdx
@@ -179,5 +179,5 @@ When a user attaches files and sends a message, CopilotKit:
 The attachments are part of the standard AG-UI `InputContent` schema, so any AG-UI-compatible agent (BuiltInAgent, LangGraph, custom) can receive them.
 
 <Callout type="info">
-  Migrating from the old `imageUploadsEnabled` prop? See the [migration guide](/troubleshooting/migrate-attachments) for a step-by-step walkthrough.
+  Migrating from the old `imageUploadsEnabled` prop? See the [migration guide](/migration-guides/migrate-attachments) for a step-by-step walkthrough.
 </Callout>
diff --git a/docs/content/docs/(root)/troubleshooting/meta.json b/docs/content/docs/(root)/troubleshooting/meta.json
@@ -1,11 +1,7 @@
 {
   "pages": [
-    "migrate-to-v2",
-    "migrate-attachments",
     "error-debugging",
     "observability-connectors",
-    "common-issues",
-    "migrate-to-1.10.X",
-    "migrate-to-1.8.2"
+    "common-issues"
   ]
 }
diff --git a/docs/snippets/shared/migration-guides/migrate-attachments.mdx b/docs/snippets/shared/migration-guides/migrate-attachments.mdx
@@ -24,7 +24,7 @@ These deprecated APIs will continue to work until the next major version but wil
 
 ## Minimum Version
 
-- **New `attachments` API:** available from vX.Y.Z
+- **New `attachments` API:** available from v1.56.0
 - **Deprecated APIs removed:** next major version
 
 ## Before / After
diff --git a/packages/react-ui/src/components/chat/AttachmentQueue.tsx b/packages/react-ui/src/components/chat/AttachmentQueue.tsx
@@ -119,7 +119,7 @@ function AttachmentPreview({ attachment }: { attachment: Attachment }) {
  * @deprecated Use `AttachmentQueue` from `@copilotkit/react-ui` instead.
  * `ImageUploadQueue` only displayed image previews. `AttachmentQueue` supports
  * images, audio, video, and documents.
- * See https://docs.copilotkit.ai/troubleshooting/migrate-attachments
+ * See https://docs.copilotkit.ai/migration-guides/migrate-attachments
  * @since 1.56.0
  */
 export { AttachmentQueue as ImageUploadQueue };
diff --git a/packages/react-ui/src/components/chat/Chat.tsx b/packages/react-ui/src/components/chat/Chat.tsx
@@ -215,7 +215,7 @@ export interface CopilotChatProps {
    * @deprecated Use `attachments={{ enabled: true }}` instead.
    * `imageUploadsEnabled` only supports images. The new `attachments` prop supports
    * images, audio, video, and documents.
-   * See https://docs.copilotkit.ai/troubleshooting/migrate-attachments
+   * See https://docs.copilotkit.ai/migration-guides/migrate-attachments
    * @since 1.56.0
    *
    * Enable image upload button (image inputs only supported on some models)
@@ -225,7 +225,7 @@ export interface CopilotChatProps {
   /**
    * @deprecated Use `attachments={{ enabled: true, accept: "..." }}` instead.
    * The `accept` field on the `attachments` prop replaces `inputFileAccept`.
-   * See https://docs.copilotkit.ai/troubleshooting/migrate-attachments
+   * See https://docs.copilotkit.ai/migration-guides/migrate-attachments
    * @since 1.56.0
    *
    * The 'accept' attribute for the file input used for image uploads.
@@ -334,7 +334,7 @@ export interface CopilotChatProps {
 
   /**
    * @deprecated Use the v2 `CopilotChat` attachment system instead.
-   * See https://docs.copilotkit.ai/troubleshooting/migrate-attachments
+   * See https://docs.copilotkit.ai/migration-guides/migrate-attachments
    *
    * A custom image rendering component to use instead of the default.
    */
@@ -380,7 +380,7 @@ export interface CopilotChatProps {
  * @deprecated Use the `Attachment` type from `@copilotkit/react-ui` instead.
  * `ImageUpload` only described image payloads. `Attachment` supports images,
  * audio, video, and documents.
- * See https://docs.copilotkit.ai/troubleshooting/migrate-attachments
+ * See https://docs.copilotkit.ai/migration-guides/migrate-attachments
  * @since 1.56.0
  */
 export type ImageUpload = {
@@ -446,7 +446,7 @@ export function CopilotChat({
       deprecationWarning(
         "imageUploadsEnabled",
         "imageUploadsEnabled is deprecated. Use attachments={{ enabled: true }} instead. " +
-          "See https://docs.copilotkit.ai/troubleshooting/migrate-attachments",
+          "See https://docs.copilotkit.ai/migration-guides/migrate-attachments",
       );
       return { enabled: true, accept: inputFileAccept || "image/*" };
     }
diff --git a/packages/react-ui/src/components/chat/messages/ImageRenderer.tsx b/packages/react-ui/src/components/chat/messages/ImageRenderer.tsx
@@ -4,7 +4,7 @@ import { ImageRendererProps } from "../props";
 /**
  * @deprecated Use `CopilotChatAttachmentRenderer` from `@copilotkit/react-core/v2` instead.
  * `ImageRenderer` only handles images. The v2 attachment renderer supports images, audio, video, and documents.
- * See https://docs.copilotkit.ai/troubleshooting/migrate-attachments
+ * See https://docs.copilotkit.ai/migration-guides/migrate-attachments
  * @since 1.56.0
  */
 export const ImageRenderer: React.FC<ImageRendererProps> = ({
diff --git a/packages/react-ui/src/components/chat/props.ts b/packages/react-ui/src/components/chat/props.ts
@@ -350,15 +350,15 @@ export interface RenderSuggestionsListProps {
 
 /**
  * @deprecated Use `CopilotChatAttachmentRenderer` from `@copilotkit/react-core/v2` instead.
- * See https://docs.copilotkit.ai/troubleshooting/migrate-attachments
+ * See https://docs.copilotkit.ai/migration-guides/migrate-attachments
  * @since 1.56.0
  */
 export interface ImageRendererProps {
   /**
    * @deprecated Use `source` (type `InputContentSource`) instead.
    * `image` only carried base64 image data. `source` supports both data and URL
    * sources for any modality.
-   * See https://docs.copilotkit.ai/troubleshooting/migrate-attachments
+   * See https://docs.copilotkit.ai/migration-guides/migrate-attachments
    * @since 1.56.0
    */
   image?: ImageData;
diff --git a/packages/shared/src/types/message.ts b/packages/shared/src/types/message.ts
@@ -18,7 +18,7 @@ export type {
  * @deprecated Use `InputContentSource` from `@ag-ui/core` (re-exported from `@copilotkit/shared`) instead.
  * `ImageData` only described base64 image payloads. `InputContentSource` supports
  * data and URL sources for images, audio, video, and documents.
- * See https://docs.copilotkit.ai/troubleshooting/migrate-attachments
+ * See https://docs.copilotkit.ai/migration-guides/migrate-attachments
  * @since 1.56.0
  */
 export interface ImageData {
@@ -46,7 +46,7 @@ export type AIMessage = agui.AssistantMessage & {
   state?: any;
   /**
    * @deprecated Use multimodal `content` array with `InputContent` parts instead.
-   * See https://docs.copilotkit.ai/troubleshooting/migrate-attachments
+   * See https://docs.copilotkit.ai/migration-guides/migrate-attachments
    * @since 1.56.0
    */
   image?: ImageData;

Original file line number	Diff line number	Diff line change
`@@ -1,11 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"pages": [`
`3`		`- "migrate-to-v2",`
`4`		`- "migrate-attachments",`
`5`	`3`	`"error-debugging",`
`6`	`4`	`"observability-connectors",`
`7`		`- "common-issues",`
`8`		`- "migrate-to-1.10.X",`
`9`		`- "migrate-to-1.8.2"`
	`5`	`+ "common-issues"`
`10`	`6`	`]`
`11`	`7`	`}`