docs(shell-docs): audit v2 package guidance

tylerslaton · tylerslaton · commit a4fc41aae292 · 2026-06-02T10:53:41.000-07:00
diff --git a/showcase/shell-docs/src/content/docs/agent-spec/quickstart.mdx b/showcase/shell-docs/src/content/docs/agent-spec/quickstart.mdx
@@ -346,7 +346,7 @@ hideTOC: true
 
           ```tsx title="app/layout.tsx"
           import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
-          import "@copilotkit/react-ui/v2/styles.css";
+          import "@copilotkit/react-core/v2/styles.css";
           import './globals.css';
 
           // ...
diff --git a/showcase/shell-docs/src/content/docs/agentic-protocols/mcp.mdx b/showcase/shell-docs/src/content/docs/agentic-protocols/mcp.mdx
@@ -200,8 +200,7 @@ For further reading, check out the [Model Context Protocol](https://modelcontext
         ```tsx
         "use client";
 
-        import { CopilotKit } from "@copilotkit/react-core/v2";
-        import { CopilotChat } from "@copilotkit/react-core/v2";
+        import { CopilotKit, CopilotChat } from "@copilotkit/react-core/v2";
 
         export default function Page() {
           return (
diff --git a/showcase/shell-docs/src/content/docs/integrations/adk/quickstart.mdx b/showcase/shell-docs/src/content/docs/integrations/adk/quickstart.mdx
@@ -254,7 +254,7 @@ Before you begin, you'll need the following:
 
                 ```tsx title="app/layout.tsx"
                 import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
-                import "@copilotkit/react-ui/v2/styles.css";
+                import "@copilotkit/react-core/v2/styles.css";
                 import './globals.css';
 
                 // ...
diff --git a/showcase/shell-docs/src/content/docs/integrations/agent-spec/quickstart.mdx b/showcase/shell-docs/src/content/docs/integrations/agent-spec/quickstart.mdx
@@ -346,7 +346,7 @@ hideTOC: true
 
           ```tsx title="app/layout.tsx"
           import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
-          import "@copilotkit/react-ui/v2/styles.css";
+          import "@copilotkit/react-core/v2/styles.css";
           import './globals.css';
 
           // ...
diff --git a/showcase/shell-docs/src/content/docs/integrations/agno/quickstart.mdx b/showcase/shell-docs/src/content/docs/integrations/agno/quickstart.mdx
@@ -220,8 +220,8 @@ Before you begin, you'll need the following:
                 Wrap your application with the CopilotKit provider:
 
                 ```tsx title="app/layout.tsx"
-                import { CopilotKit } from "@copilotkit/react-core"; // [!code highlight]
-                import "@copilotkit/react-ui/v2/styles.css";
+                import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
+                import "@copilotkit/react-core/v2/styles.css";
                 import './globals.css';
 
                 // ...
diff --git a/showcase/shell-docs/src/content/docs/integrations/aws-strands/quickstart.mdx b/showcase/shell-docs/src/content/docs/integrations/aws-strands/quickstart.mdx
@@ -309,7 +309,7 @@ Before you begin, you'll need the following:
 
                 ```tsx title="app/layout.tsx"
                 import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
-                import "@copilotkit/react-ui/v2/styles.css";
+                import "@copilotkit/react-core/v2/styles.css";
                 import './globals.css';
 
                 // ...
diff --git a/showcase/shell-docs/src/content/docs/integrations/built-in-agent/quickstart.mdx b/showcase/shell-docs/src/content/docs/integrations/built-in-agent/quickstart.mdx
@@ -106,8 +106,8 @@ Before you begin, you'll need the following:
         Wrap your application with the CopilotKit provider:
 
         ```tsx title="app/layout.tsx"
-        import { CopilotKit } from "@copilotkit/react-core"; // [!code highlight]
-        import "@copilotkit/react-ui/v2/styles.css"; // [!code highlight]
+        import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
+        import "@copilotkit/react-core/v2/styles.css"; // [!code highlight]
         import './globals.css';
 
         // ...
diff --git a/showcase/shell-docs/src/content/docs/integrations/built-in-agent/tutorials/ai-powered-textarea/step-2-setup-copilotkit.mdx b/showcase/shell-docs/src/content/docs/integrations/built-in-agent/tutorials/ai-powered-textarea/step-2-setup-copilotkit.mdx
@@ -55,7 +55,7 @@ In order to use CopilotKit, we'll need to configure the CopilotKit provider.
 
 import { EmailThread } from "@/components/EmailThread";
 import { EmailsProvider } from "@/lib/hooks/use-emails";
-import { CopilotKit } from "@copilotkit/react-core"; // [!code highlight]
+import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
 import "@copilotkit/react-textarea/styles.css"; // [!code highlight]
 
 export default function Home() {
@@ -79,7 +79,7 @@ export default function Home() {
 
 Let's break this down:
 
-- First, we imported the `CopilotKit` provider from `@copilotkit/react-core`.
+- First, we imported the `CopilotKit` provider from `@copilotkit/react-core/v2`.
 - Then, we wrapped the page with the `<CopilotKit>` provider.
 - We imported the built-in styles from `@copilotkit/react-textarea`.
 
diff --git a/showcase/shell-docs/src/content/docs/integrations/built-in-agent/tutorials/ai-todo-app/step-2-setup-copilotkit.mdx b/showcase/shell-docs/src/content/docs/integrations/built-in-agent/tutorials/ai-todo-app/step-2-setup-copilotkit.mdx
@@ -73,9 +73,9 @@ In this tutorial, we'll use the `<CopilotPopup/>` component to display the chat
 
 import { TasksList } from "@/components/TasksList";
 import { TasksProvider } from "@/lib/hooks/use-tasks";
-import { CopilotKit } from "@copilotkit/react-core";
+import { CopilotKit } from "@copilotkit/react-core/v2";
 import { CopilotPopup } from "@copilotkit/react-core/v2"; // [!code highlight]
-import "@copilotkit/react-ui/v2/styles.css"; // [!code highlight]
+import "@copilotkit/react-core/v2/styles.css"; // [!code highlight]
 
 export default function Home() {
   return (
diff --git a/showcase/shell-docs/src/content/docs/integrations/deepagents/quickstart.mdx b/showcase/shell-docs/src/content/docs/integrations/deepagents/quickstart.mdx
@@ -341,7 +341,7 @@ Before you begin, you'll need the following:
 
         ```tsx title="app/layout.tsx"
         import { CopilotKit } from "@copilotkit/react-core/v2";
-        import "@copilotkit/react-ui/v2/styles.css";
+        import "@copilotkit/react-core/v2/styles.css";
 
         // ...
 
diff --git a/showcase/shell-docs/src/content/docs/integrations/langgraph/quickstart.mdx b/showcase/shell-docs/src/content/docs/integrations/langgraph/quickstart.mdx
@@ -369,7 +369,7 @@ Before you begin, you'll need the following:
               ```tsx title="app/layout.tsx"
               // [!code highlight:2]
               import { CopilotKit } from "@copilotkit/react-core/v2";
-              import "@copilotkit/react-ui/v2/styles.css";
+              import "@copilotkit/react-core/v2/styles.css";
               import './globals.css';
 
               // ...
diff --git a/showcase/shell-docs/src/content/docs/integrations/llamaindex/quickstart.mdx b/showcase/shell-docs/src/content/docs/integrations/llamaindex/quickstart.mdx
@@ -261,8 +261,8 @@ Before you begin, you'll need the following:
                 Wrap your application with the CopilotKit provider:
 
                 ```tsx title="app/layout.tsx"
-                import { CopilotKit } from "@copilotkit/react-core"; // [!code highlight]
-                import "@copilotkit/react-ui/v2/styles.css";
+                import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
+                import "@copilotkit/react-core/v2/styles.css";
                 import './globals.css';
 
                 // ...
diff --git a/showcase/shell-docs/src/content/docs/integrations/llamaindex/shared-state/predictive-state-updates.mdx b/showcase/shell-docs/src/content/docs/integrations/llamaindex/shared-state/predictive-state-updates.mdx
@@ -200,7 +200,7 @@ When your agent finishes executing, **its final state becomes the single source
 
     import { useAgent } from "@copilotkit/react-core/v2";
     import { CopilotSidebar } from '@copilotkit/react-ui';
-    import '@copilotkit/react-ui/v2/styles.css';
+    import '@copilotkit/react-core/v2/styles.css';
 
     interface Step {
         description: string;
diff --git a/showcase/shell-docs/src/content/docs/integrations/mastra/quickstart.mdx b/showcase/shell-docs/src/content/docs/integrations/mastra/quickstart.mdx
@@ -230,8 +230,8 @@ Before you begin, you'll need the following:
                 Wrap your application with the CopilotKit provider:
 
                 ```tsx title="app/layout.tsx"
-                import { CopilotKit } from "@copilotkit/react-core"; // [!code highlight]
-                import "@copilotkit/react-ui/v2/styles.css";
+                import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
+                import "@copilotkit/react-core/v2/styles.css";
                 import './globals.css';
 
                 // ...
diff --git a/showcase/shell-docs/src/content/docs/integrations/microsoft-agent-framework/quickstart.mdx b/showcase/shell-docs/src/content/docs/integrations/microsoft-agent-framework/quickstart.mdx
@@ -356,7 +356,7 @@ Before you begin, you'll need the following:
 
                 ```tsx title="app/layout.tsx"
                 import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
-                import "@copilotkit/react-ui/v2/styles.css";
+                import "@copilotkit/react-core/v2/styles.css";
                 import './globals.css';
 
                 export default function RootLayout({ children }: {children: React.ReactNode}) {
diff --git a/showcase/shell-docs/src/content/docs/integrations/pydantic-ai/quickstart.mdx b/showcase/shell-docs/src/content/docs/integrations/pydantic-ai/quickstart.mdx
@@ -175,7 +175,7 @@ Before you begin, you'll need the following:
                 Wrap your application with the CopilotKit provider:
 
                 ```tsx title="app/layout.tsx"
-                import { CopilotKit } from "@copilotkit/react-core"; // [!code highlight]
+                import { CopilotKit } from "@copilotkit/react-core/v2"; // [!code highlight]
 
                 // ...
 
diff --git a/showcase/shell-docs/src/content/docs/premium/observability.mdx b/showcase/shell-docs/src/content/docs/premium/observability.mdx
@@ -22,8 +22,7 @@ All observability hooks require a `publicLicenseKey` (self-hosted) or `publicApi
 Track user interactions and chat events:
 
 ```tsx
-import { CopilotKit } from "@copilotkit/react-core/v2";
-import { CopilotChat } from "@copilotkit/react-core/v2";
+import { CopilotKit, CopilotChat } from "@copilotkit/react-core/v2";
 
 export default function App() {
   return (
diff --git a/showcase/shell-docs/src/content/docs/tutorials/ai-powered-textarea/step-2-setup-copilotkit.mdx b/showcase/shell-docs/src/content/docs/tutorials/ai-powered-textarea/step-2-setup-copilotkit.mdx
@@ -66,7 +66,7 @@ export default function Home() {
 
 Let's break this down:
 
-- First, we imported the `CopilotKit` provider from `@copilotkit/react-core`.
+- First, we imported the `CopilotKit` provider from `@copilotkit/react-core/v2`.
 - Then, we wrapped the page with the `<CopilotKit>` provider.
 - We imported the built-in styles from `@copilotkit/react-textarea`.
 
diff --git a/showcase/shell-docs/src/content/reference/components/CopilotKit.mdx b/showcase/shell-docs/src/content/reference/components/CopilotKit.mdx
@@ -4,8 +4,8 @@ description: "The CopilotKit provider component, wrapping your application."
 ---
 
 <Callout type="info">
-  This provider is shared across v1 and v2 APIs. It must be imported from the
-  root package (`@copilotkit/react-core`), not from the v2 subpackage.
+  This provider is shared across v1 and v2 APIs. In v2 docs, import it from
+  `@copilotkit/react-core/v2`.
 </Callout>
 
 This component will typically wrap your entire application (or a sub-tree of your application where you want to have a copilot). It provides the copilot context to all other components and hooks.
@@ -15,6 +15,8 @@ This component will typically wrap your entire application (or a sub-tree of you
 You can find more information about self-hosting CopilotKit [here](/direct-to-llm/guides/self-hosting).
 
 ```tsx
+import { CopilotKit } from "@copilotkit/react-core/v2";
+
 <CopilotKit runtimeUrl="<your-runtime-url>">// ... your app ...</CopilotKit>
 ```
 
diff --git a/showcase/shell-docs/src/content/reference/index.mdx b/showcase/shell-docs/src/content/reference/index.mdx
@@ -3,14 +3,14 @@ title: "API Reference"
 description: "API Reference for the next-generation CopilotKit React API."
 ---
 
-The v2 React API (`@copilotkit/react-core`) is the next-generation interface for building copilot-powered applications. It provides a streamlined set of hooks and components built on top of the [AG-UI](https://docs.ag-ui.com) agent protocol.
+The v2 React API (`@copilotkit/react-core/v2`) is the next-generation interface for building copilot-powered applications. It provides a streamlined set of hooks and components built on top of the [AG-UI](https://docs.ag-ui.com) agent protocol.
 
 ## Provider Setup
 
 The v2 API uses the [`<CopilotKit>`](/reference/components/CopilotKit) provider. Wrap your application with it to configure the runtime connection:
 
 ```tsx
-// CopilotKit is imported from the root package, not from the v2 subpackage
+import { CopilotKit } from "@copilotkit/react-core/v2";
 
 function App() {
   return (
@@ -25,12 +25,14 @@ function App() {
 <Accordion title="Advanced: Using CopilotKit directly">
 
 <Callout type="warn">
-  `CopilotKit` is a low-level provider intended for advanced use cases. Most applications should use the `<CopilotKit>` component from `@copilotkit/react-core` instead.
+  `CopilotKit` is a low-level provider intended for advanced use cases. Most applications should use the `<CopilotKit>` component from `@copilotkit/react-core/v2` instead.
 </Callout>
 
-If you need direct control over the v2 provider (e.g. for custom integrations), you can import `CopilotKit` from `@copilotkit/react-core`:
+If you need direct control over the v2 provider (e.g. for custom integrations), import `CopilotKit` from `@copilotkit/react-core/v2`:
 
 ```tsx
+import { CopilotKit } from "@copilotkit/react-core/v2";
+
 <CopilotKit runtimeUrl="/api/copilotkit">
   <App />
 </CopilotKit>
diff --git a/showcase/shell-docs/src/lib/__tests__/docs-render.test.ts b/showcase/shell-docs/src/lib/__tests__/docs-render.test.ts
@@ -9,6 +9,7 @@ vi.mock("../registry", () => ({
 import {
   buildFrameworkNav,
   buildFrameworkOnlyNav,
+  CONTENT_DIR,
   inlineSnippets,
   loadDoc,
   SNIPPET_MAP,
@@ -47,6 +48,14 @@ function hasSectionPage(navTree: NavNode[], section: string, page: string) {
   return false;
 }
 
+function collectMdxFiles(dir: string): string[] {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+    const filePath = path.join(dir, entry.name);
+    if (entry.isDirectory()) return collectMdxFiles(filePath);
+    return entry.isFile() && entry.name.endsWith(".mdx") ? [filePath] : [];
+  });
+}
+
 describe("inlineSnippets", () => {
   it("recursively inlines helper components imported from snippets", () => {
     const helperRel = writeSnippet("helper.mdx", "Helper body\n");
@@ -153,6 +162,55 @@ describe("migration docs", () => {
     );
     expect(snippet).not.toContain("CopilotKitProvider");
   });
+
+  it("keeps v2 reference pages aligned with the CopilotKit v2 entrypoint", () => {
+    const referenceIndex = fs.readFileSync(
+      path.join(CONTENT_DIR, "..", "reference/index.mdx"),
+      "utf8",
+    );
+    const componentReference = fs.readFileSync(
+      path.join(CONTENT_DIR, "..", "reference/components/CopilotKit.mdx"),
+      "utf8",
+    );
+
+    expect(referenceIndex).toContain(
+      'import { CopilotKit } from "@copilotkit/react-core/v2";',
+    );
+    expect(referenceIndex).not.toContain(
+      "CopilotKit is imported from the root package",
+    );
+    expect(referenceIndex).not.toContain(
+      "import `CopilotKit` from `@copilotkit/react-core`",
+    );
+    expect(componentReference).toContain("`@copilotkit/react-core/v2`");
+    expect(componentReference).not.toContain("not from the v2 subpackage");
+  });
+
+  it("does not recommend stale v2 package paths in authored docs", () => {
+    const authoredDocFiles = collectMdxFiles(CONTENT_DIR);
+    const allowedRootProviderImports = new Set([
+      path.join(CONTENT_DIR, "migrate/v2.mdx"),
+    ]);
+
+    const rootProviderImports = authoredDocFiles.filter((filePath) => {
+      if (allowedRootProviderImports.has(filePath)) return false;
+      return fs
+        .readFileSync(filePath, "utf8")
+        .includes('import { CopilotKit } from "@copilotkit/react-core";');
+    });
+
+    const oldV2StyleImports = [
+      ...authoredDocFiles,
+      ...collectMdxFiles(SNIPPETS_DIR),
+    ].filter((filePath) =>
+      fs
+        .readFileSync(filePath, "utf8")
+        .includes("@copilotkit/react-ui/v2/styles.css"),
+    );
+
+    expect(rootProviderImports).toEqual([]);
+    expect(oldV2StyleImports).toEqual([]);
+  });
 });
 
 describe("framework nav", () => {
