fix(shell-docs): critical-path content fixes — imports, links, model names, premium walkthrough (CopilotKit#4497)

## Summary

Critical-path content fixes from the shell-docs QA triage. Fixes
everything that breaks copy-paste or click-through on existing pages.

**Items addressed:**
- 2.2, 8.1, 13.1, 13.2 — code-block import hygiene
- 12.1, 14.1, 15.1, 15.2, 22.1 — cross-page link sweep
- 9.1, 9.2 — `gpt-5.2*` → `gpt-5.4*` sweep + extend model-name CI
validator
- 7.1 — `migrations.enabled` premium walkthrough corrections

## Visual inspection

1. Start the dev server:
   ```bash
   nx run shell-docs:dev
   ```
   Open http://localhost:3003.

2. **Imports — copy-paste check.** Visit each page below; copy each
`route.ts` / `app/layout.tsx` / `app/page.tsx` block into a scratch
TypeScript file and verify it has all needed imports:
- `/built-in-agent/quickstart` (BIA, default integration — should now
import `CopilotKit` from `@copilotkit/react-core/v2`)
   - `/agent-spec/quickstart`
   - `/microsoft-agent-framework/quickstart`
- Switch framework picker to each of: `langgraph`, `mastra`,
`pydantic-ai`, `adk`, `agno`, `aws-strands`, `llamaindex`. Re-check the
same blocks.
- `/auth`, `/agentic-protocols/mcp`, `/backend/copilot-runtime`,
`/multimodal-attachments` — verify code blocks now show import lines.

3. **Links — click-through check.** On each page below, click every
external link in the prose:
- `/agentic-protocols` (the index — 7 link rewrites; all should resolve)
   - `/multimodal-attachments` (the migration Callout should be GONE)
- `/faq` ("What's available?" table — the rows should be plain bold
labels, not links)
- `/langgraph/agent-app-context` (mid-prose link should now point at
langgraph fw page, not BIA)
- `/inspector` (the agent-app-context relative link should resolve to
langgraph fw page)
- `/troubleshooting/common-issues` (the `copilot-runtime` and
`model-selection` links should now resolve)

4. **Model names — search check.** In the dev server (or via grep),
confirm `gpt-5.2` and `gpt-5.2-mini` no longer appear anywhere in
`showcase/shell-docs/src/content/`. All references should now be
`gpt-5.4` / `gpt-5.4-mini`.

5. **Premium walkthrough — read-through.** Walk `/premium/self-hosting`
end to end as if installing fresh. The walkthrough should now tell you
to set `migrations.enabled: true` BEFORE the install command. The "Job
will appear as Completed" prose should only fire if migrations were
enabled.

6. **Anti-checks (these should NOT have changed):**
- The legitimate `gpt-4o`, `gpt-4.1`, `gpt-5.4` references in JSDoc /
source code.
- Code blocks where imports were intentionally omitted because a prior
block on the same page established them.
- Reference pages under `/reference/v1/` (those are owned by a separate
PR).

Author: samjulien

scripts/validate-doc-model-names.ts

@@ -22,6 +22,12 @@ interface Violation {
 
 const DOCS_DIR = path.resolve(__dirname, "../docs");
 const ALLOWLIST_PATH = path.join(DOCS_DIR, "model-allowlist.json");
+// Additional roots to scan. The main legacy Nextra tree under `docs/` is the
+// primary canonical home, but the new shell-docs surface (`showcase/shell-docs/`)
+// is now also authored content and must obey the same allowlist.
+const EXTRA_DOCS_DIRS = [
+  path.resolve(__dirname, "../showcase/shell-docs/src/content"),
+];
 
 // Provider prefixes stripped before matching (e.g. "openai/gpt-4o" -> "gpt-4o")
 const PROVIDER_PREFIXES = [
@@ -274,6 +280,10 @@ function main() {
   }
 
   const violations = validateFiles(DOCS_DIR, ALLOWLIST_PATH);
+  for (const extra of EXTRA_DOCS_DIRS) {
+    if (!fs.existsSync(extra)) continue;
+    violations.push(...validateFiles(extra, ALLOWLIST_PATH));
+  }
 
   if (violations.length === 0) {
     console.log("All model names in docs are valid.");

showcase/shell-docs/src/content/docs/agentic-protocols/index.mdx

@@ -75,7 +75,7 @@ Learn about these protocols and how to connect your app to agents which support
           verticalAlign: "top",
         }}
       >
-        <a href="./ag-ui-protocol">
+        <a href="/agentic-protocols/ag-ui">
           <strong>AG-UI</strong>
         </a>
         <br />
@@ -103,7 +103,7 @@ Learn about these protocols and how to connect your app to agents which support
           verticalAlign: "top",
         }}
       >
-        <a href="./connect-mcp-servers">
+        <a href="/agentic-protocols/mcp">
           <strong>MCP</strong>
         </a>
         <br />
@@ -131,7 +131,7 @@ Learn about these protocols and how to connect your app to agents which support
           verticalAlign: "top",
         }}
       >
-        <a href="./a2a-protocol">
+        <a href="/agentic-protocols/a2a">
           <strong>A2A</strong>
         </a>
         <br />
@@ -147,16 +147,15 @@ Learn about these protocols and how to connect your app to agents which support
         <strong>Agent ↔ Generative UI </strong>
       </td>
       <td style={{ padding: "12px", verticalAlign: "top" }}>
-        <strong>[A2UI](./generative-ui/specs/a2ui)</strong> (Google)
+        <strong>[A2UI](/generative-ui/a2ui)</strong> (Google)
         <br />
-        <strong>[MCP Apps](./generative-ui/specs/mcp-apps)</strong> (MCP
+        <strong>[MCP Apps](/generative-ui/mcp-apps)</strong> (MCP
         Ecosystem)
         <br />
-        <strong>[Open-JSON-UI](./generative-ui/specs/open-json-ui)</strong>{" "}
-        (OpenAI)
+        <strong>Open-JSON-UI</strong> (OpenAI)
       </td>
       <td style={{ padding: "12px" }}>
-        Declarative, LLM-friendly [generative UI specs](./generative-ui/specs)
+        Declarative, LLM-friendly [generative UI specs](/generative-ui)
         that define <em>what</em> to render and how to structure agent responses
         visually. CopilotKit fully supports all of these.
       </td>

showcase/shell-docs/src/content/docs/agentic-protocols/mcp.mdx

@@ -102,6 +102,7 @@ For further reading, check out the [Model Context Protocol](https://modelcontext
         ```tsx
         "use client";
 
+        import { CopilotKit } from "@copilotkit/react-core/v2";
 
         export default function App() {
           return (
@@ -120,6 +121,8 @@ For further reading, check out the [Model Context Protocol](https://modelcontext
         ```tsx
         "use client";
 
+        import { useEffect } from "react";
+        import { useCopilotKit } from "@copilotkit/react-core/v2";
 
         function McpServerManager() {
           const { setMcpServers } = useCopilotKit();
@@ -148,6 +151,7 @@ For further reading, check out the [Model Context Protocol](https://modelcontext
         ```tsx
         "use client";
 
+        import { CopilotChat } from "@copilotkit/react-core/v2";
 
         export default function ChatInterface() {
           return (
@@ -169,6 +173,7 @@ For further reading, check out the [Model Context Protocol](https://modelcontext
         ```tsx
         "use client";
 
+        import {
           useFrontendTool,
           CatchAllActionRenderProps,
         } from "@copilotkit/react-core/v2";
@@ -195,6 +200,7 @@ For further reading, check out the [Model Context Protocol](https://modelcontext
         ```tsx
         "use client";
 
+        import { CopilotKit, CopilotChat } from "@copilotkit/react-core/v2";
 
         export default function Page() {
           return (
@@ -331,10 +337,12 @@ For detailed implementation guidance, refer to the [official MCP SDK documentati
 Here's a basic example of configuring the runtime:
 
 ```tsx
+import {
   CopilotRuntime,
   OpenAIAdapter,
   copilotRuntimeNextJSAppRouterEndpoint,
 } from "@copilotkit/runtime";
+import { NextRequest } from "next/server";
 
 const serviceAdapter = new OpenAIAdapter();
 

showcase/shell-docs/src/content/docs/auth.mdx

@@ -25,6 +25,8 @@ If you don't need any of those, skip auth entirely. The agent runs anonymously a
 Pass your token via the `headers` prop on `<CopilotKit>`. CopilotKit forwards every request with that header attached.
 
 ```tsx title="frontend/src/app/page.tsx"
+import { CopilotKit } from "@copilotkit/react-core/v2";
+
 <CopilotKit
   runtimeUrl="/api/copilotkit"
   headers={{
@@ -82,6 +84,8 @@ export const GET = (req: NextRequest) => handler(req);
 Pass your token via the `properties` prop. CopilotKit forwards it to LangGraph as a Bearer token automatically.
 
 ```tsx title="frontend/src/app/page.tsx"
+import { CopilotKit } from "@copilotkit/react-core/v2";
+
 <CopilotKit
   runtimeUrl="/api/copilotkit"
   properties={{
@@ -185,6 +189,8 @@ async def my_agent_node(state: AgentState, config: RunnableConfig):
 Pass your token via the `properties` prop. CopilotKit forwards it to AG2's `/chat` endpoint as a request header.
 
 ```tsx title="frontend/src/app/page.tsx"
+import { CopilotKit } from "@copilotkit/react-core/v2";
+
 <CopilotKit
   runtimeUrl="/api/copilotkit"
   properties={{
@@ -210,7 +216,7 @@ from autogen.ag_ui import AGUIStream, RunAgentInput
 agent = ConversableAgent(
     name="assistant",
     system_message="You are a helpful assistant.",
-    llm_config=LLMConfig({"model": "gpt-5.2-mini"}),
+    llm_config=LLMConfig({"model": "gpt-5.4-mini"}),
 )
 
 stream = AGUIStream(agent)
@@ -268,6 +274,8 @@ def get_account_data(
 Microsoft Agent Framework's AG-UI host expects authentication on a request header rather than the runtime properties channel. Pass the token via `<CopilotKit headers={...}>`:
 
 ```tsx title="frontend/src/app/page.tsx"
+import { CopilotKit } from "@copilotkit/react-core/v2";
+
 <CopilotKit
   runtimeUrl="/api/copilotkit"
   headers={{

showcase/shell-docs/src/content/docs/backend/copilot-runtime.mdx

@@ -40,6 +40,8 @@ export const POST = async (req: NextRequest) => {
 Then point your frontend at the endpoint:
 
 ```tsx
+import { CopilotKitProvider } from "@copilotkit/react-core/v2";
+
 <CopilotKitProvider runtimeUrl="/api/copilotkit">
   <YourApp />
 </CopilotKitProvider>
@@ -59,6 +61,8 @@ The runtime supports multiple agent types. `BuiltInAgent` is the primary agent c
 If you register an agent under the name `"default"`, CopilotKit's prebuilt UI components will use it automatically without any additional configuration on the frontend. This is useful when you have one primary agent and don't want to specify an `agentId` everywhere.
 
 ```ts title="app/api/copilotkit/route.ts"
+import { BuiltInAgent } from "@copilotkit/runtime/v2";
+
 const runtime = new CopilotRuntime({
   agents: {
     // This agent is used automatically by CopilotPopup, CopilotSidebar, etc.
@@ -111,6 +115,8 @@ a2ui: { agents: ["my-agent"] }
 On the frontend, the A2UI renderer activates automatically — no extra configuration needed. If you want to override the default theme, pass an `a2ui` prop to `<CopilotKitProvider>`:
 
 ```tsx
+import { CopilotKitProvider } from "@copilotkit/react-core/v2";
+
 <CopilotKitProvider runtimeUrl="/api/copilotkit" a2ui={{ theme: myCustomTheme }}>
   {children}
 </CopilotKitProvider>
@@ -139,6 +145,7 @@ CopilotKit is built on the [AG-UI protocol](./ag-ui), which is an open standard.
 
 ```tsx
 import { HttpAgent } from "@ag-ui/client";
+import { CopilotKitProvider } from "@copilotkit/react-core/v2";
 
 const myAgent = new HttpAgent({
   url: "https://my-agent.example.com",

showcase/shell-docs/src/content/docs/faq.mdx

@@ -38,29 +38,29 @@ We've got answers to some common questions!
     Beautiful, powerful and customizable chat components just an import away.
     | | |
     |---------|-------------|
-    | [**Chat**](/reference/v1/components/chat/CopilotChat) | Simple and powerful chat interface |
-    | [**Pop-up**](/reference/v1/components/chat/CopilotPopup) | The Chat component in a pop-up format |
-    | [**Sidebar**](/reference/v1/components/chat/CopilotSidebar) | The Chat component in a sidebar format |
-    | [**Copilot Textarea**](/reference/v1/components/CopilotTextarea) | Powerful AI autocompletion as a drop-in replacement for any textarea |
+    | **Chat** | Simple and powerful chat interface |
+    | **Pop-up** | The Chat component in a pop-up format |
+    | **Sidebar** | The Chat component in a sidebar format |
+    | **Copilot Textarea** | Powerful AI autocompletion as a drop-in replacement for any textarea |
     | [**Headless**](/custom-look-and-feel/slots) | Full customization of the chat interfaces |
 
     ### Deeply integrated Copilots
     Give Copilots the ability to execute tools directly in your application.
     |  |  |
     |---------|-------------|
-    | [**Copilot Readable State**](/reference/v1/hooks/useCopilotReadable) | Enables Copilots to read and understand the application state |
-    | [**Frontend Tools**](/reference/v1/hooks/useFrontendTool) | Copilots can execute tools in the application |
+    | **Copilot Readable State** | Enables Copilots to read and understand the application state |
+    | **Frontend Tools** | Copilots can execute tools in the application |
     | [**Generative UI**](/generative-ui/your-components/display-only) | Render any component in the copilot chat interface |
-    | [**AI Autosuggestions**](/reference/v1/hooks/useCopilotChatSuggestions) | AI-powered autosuggestions in your AI chat interface |
-    | [**Copilot Tasks**](/reference/v1/classes/CopilotTask) | Let your copilots execute tools proactively based on application state |
+    | **AI Autosuggestions** | AI-powered autosuggestions in your AI chat interface |
+    | **Copilot Tasks** | Let your copilots execute tools proactively based on application state |
 
     ### Rich agentic experiences
     Integrate your LangChain agents into your product with ease.
     | |  |
     |---------|-------------|
-    | [**Deep support for LangChain**](/langgraph/quickstart) | Bring your LangChain agents directly into your product |
-    | [**Human-in-the-loop**](/langgraph/human-in-the-loop) | Allow your users to work with your agents to solve complex problems |
-    | [**Shared state**](/langgraph/shared-state) | Render the state of your LangChain agents with less than 10 lines of code |
+    | **Deep support for LangChain** | Bring your LangChain agents directly into your product |
+    | **Human-in-the-loop** | Allow your users to work with your agents to solve complex problems |
+    | **Shared state** | Render the state of your LangChain agents with less than 10 lines of code |
 
   </Accordion>
   <Accordion title="How does it all work?">

showcase/shell-docs/src/content/docs/inspector.mdx

@@ -24,7 +24,7 @@ The **CopilotKit Inspector** is a built-in debugging overlay that sits on top of
 | **Available Agents** | Which agents CopilotKit has discovered via `/info` and which one is currently active. |
 | **Agent State** | The current `agent.state` tree, rerendered as it updates. Great for debugging [shared state](./shared-state) flows. |
 | **Frontend Tools** | Every tool registered via `useFrontendTool`, `useComponent`, `useHumanInTheLoop`, or `useRenderTool`, along with its parameter schema. |
-| **Context** | The [`useAgentContext`](./agent-app-context) entries the agent currently receives, plus any document context you've attached. |
+| **Context** | The [`useAgentContext`](/langgraph-python/agent-app-context) entries the agent currently receives, plus any document context you've attached. |
 
 ## When should I use it?
 

showcase/shell-docs/src/content/docs/integrations/adk/quickstart.mdx

@@ -221,10 +221,13 @@ Before you begin, you'll need the following:
                 Create an API route to connect CopilotKit to your ADK agent:
 
                 ```tsx title="app/api/copilotkit/route.ts"
+                import {
                   CopilotRuntime,
                   ExperimentalEmptyAdapter,
                   copilotRuntimeNextJSAppRouterEndpoint,
                 } from "@copilotkit/runtime";
+                import { HttpAgent } from "@ag-ui/client";
+                import { NextRequest } from "next/server";
 
                 const serviceAdapter = new ExperimentalEmptyAdapter();
 
@@ -251,6 +254,9 @@ 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/v2"; // [!code highlight]
+                import "@copilotkit/react-ui/v2/styles.css"; // [!code highlight]
+                import './globals.css';
 
                 // ...
 
@@ -274,6 +280,7 @@ Before you begin, you'll need the following:
               Add the CopilotSidebar component to your page:
 
               ```tsx title="app/page.tsx"
+              import { CopilotSidebar } from "@copilotkit/react-core/v2"; // [!code highlight]
 
               export default function Page() {
                 return (

showcase/shell-docs/src/content/docs/integrations/ag2/frontend-tools.mdx

@@ -103,7 +103,7 @@ Without frontend actions, agents are limited to just processing and returning da
                 agent = ConversableAgent(
                     name="assistant",
                     system_message="You are a helpful assistant.",
-                    llm_config=LLMConfig({"model": "gpt-5.2-mini"}),
+                    llm_config=LLMConfig({"model": "gpt-5.4-mini"}),
                 )
 
                 stream = AGUIStream(agent)

showcase/shell-docs/src/content/docs/integrations/ag2/generative-ui/state-rendering.mdx

@@ -71,7 +71,7 @@ is a situation where a user and an agent are working together to solve a problem
             "You are a helpful assistant for storing searches. "
             "Use `add_search` once per query, then call `run_searches`."
         ),
-        llm_config=LLMConfig({"model": "gpt-5.2-mini"}),
+        llm_config=LLMConfig({"model": "gpt-5.4-mini"}),
     )