Add CopilotKit agent framework guide (#1031)

* Add CopilotKit agent framework guide

Add a guide for using Arcade tools with CopilotKit, mirroring the existing
Mastra and Vercel AI framework pages. It covers wrapping Arcade tools with
defineTool, the authorize-then-execute pattern, a single-route CopilotRuntime,
and rendering the authorization step as generative UI with useRenderTool.

- New page: app/en/get-started/agent-frameworks/copilotkit/page.mdx
- Register the page in agent-frameworks/_meta.tsx
- Add a CopilotKit card to the JavaScript tab in agent-framework-tabs.tsx
- Add public/images/icons/copilotkit.svg
- Add tests/copilotkit-guide.test.ts (contract test, written test-first)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Use the official CopilotKit logo mark

Replace the placeholder icon with CopilotKit's authoritative brand mark
and drop invertInDark on the card, since the mark is full-color (matching
the CrewAI / Google ADK full-color icon pattern rather than the monochrome
invert pattern).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Harden the CopilotKit guide after code review

A 7-reviewer pass surfaced a false-success render path and a dropped
security note; fix both and tighten the contract test.

- Render: show the "email sent" card only on the positive success
  discriminant (authorizationRequired === false). An unparseable or
  missing tool result now renders an error card instead of a false
  green "sent" card, in both the inline snippet and the full-file
  listing. This matches the guide's own "failures come back as data"
  Callout, which the render layer previously contradicted.
- Restore a "Before you expose this publicly" warning callout
  (authenticate the runtime, scope every call to a server-verified
  user, disposable keys + rate limiting + security headers) that the
  adaptation had dropped from the upstream recipe.
- Bump the Node prerequisite to 20+ (the CopilotKit v2 / Next.js stack
  needs it; Node 18 is end-of-life).
- Tighten the contract test: assert the _meta key and title together,
  require non-empty frontmatter values, check the SVG closing tag, and
  hoist regexes to module scope. Update the stale header comment.

Deferred as matching the authoritative Arcade-authored recipe / SDK
contract: the success===false failure check and the runtime auth gate's
dev-open default (the restored callout documents the hardening steps).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Fix Nextra compile error: use filename= on code fences

`title=` on code fences (carried over from the upstream Starlight-based
recipe) broke Nextra's rehype pipeline with "Cannot convert undefined or
null to object", returning a 500 for the page. The Arcade docs use
`filename=` for code-block labels (150 existing usages); switch all six
fences to match. Caught by rendering the page in the local dev server —
the unit tests and an mdx-js compile check don't exercise Nextra's loader.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Add page title and a CopilotKit scaffold command

Local preview review surfaced two gaps:
- The page rendered no title. Nextra does not promote the frontmatter
  `title` to an on-page H1 (the Vercel AI guide includes an explicit
  one); add `# Build an AI agent with Arcade and CopilotKit`.
- Step 1 linked to the quickstart but showed no create command, unlike
  the Mastra/Vercel guides. Add `npx copilotkit@latest init` (CopilotKit
  CLI) in the package-manager tabs before the Arcade SDK install.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(copilotkit): fix scaffold path, typed tool result, and provider wiring

Validated the guide by building it as a runnable app — a Next.js demo that
reproduces the three "Complete code" files verbatim. The build surfaced fixes:

- Step 1: replace `copilotkit init` (interactive-only, account-gated, and with
  no Built-in Agent template) with `create-next-app` plus explicit installs,
  the path that actually reproduces the app.
- Install `zod` (both files import it; it otherwise resolves only as a peer
  dependency of the CopilotKit packages).
- `app/page.tsx`: parse into a discriminated-union `ToolResult` instead of
  `any`, so the sample passes `eslint` (no-explicit-any) as well as `tsc`.
- Show the `<CopilotKit>` provider wiring (`app/providers.tsx` and
  `app/layout.tsx`); the provider is a client component the prose only described.
- Note that `BuiltInAgent` model ids are `provider/model` strings.

Extend the contract test to lock in these invariants.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: GeneralJerel <85066839+GeneralJerel@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: jerelvelarde

app/_components/agent-framework-tabs.tsx

@@ -78,6 +78,12 @@ export function AgentFrameworkTabs() {
             name="Vercel AI"
             type="Agent Framework"
           />
+          <PlatformCard
+            icon="/images/icons/copilotkit.svg"
+            link="/en/get-started/agent-frameworks/copilotkit"
+            name="CopilotKit"
+            type="Agent Framework"
+          />
           <PlatformCard
             icon="https://avatars.githubusercontent.com/u/72518640?s=200&v=4"
             link="/en/get-started/agent-frameworks/tanstack-ai"

app/en/get-started/agent-frameworks/_meta.tsx

@@ -10,6 +10,9 @@ export const meta: MetaRecord = {
   ag2: {
     title: "AG2",
   },
+  copilotkit: {
+    title: "CopilotKit",
+  },
   crewai: {
     title: "CrewAI",
   },