Ports the entire Docusaurus content tree to apps/docs-next:

Sections ported (from apps/docs/docs):
- adapters/        (1 page)
- agents/          (4 pages: tools, skills, runtime, delegation)
- chat-uis/        (4 pages: react, ink, components, theming)
- components/      (1 page)
- contributing/    (1 page)
- data-layer/      (3 pages: adapters, memory, rag)
- examples/        (12 pages)
- getting-started/ (read-this-first, for-ai-agents — quickstart and installation already authored fresh in #277)
- hooks/           (3 pages: useChat, useStream, useReactive)
- infrastructure/  (4 pages: cli, eval, observability, sandbox)
- packages/        (3 pages)
- theming/         (1 page)

Total: 56 routes generated, build clean, all routes return 200.

Frontmatter handling:
- Stripped Docusaurus 'sidebar_position' (replaced by meta.json ordering)
- Auto-extracted title from first H1 when missing
- Auto-extracted description from first paragraph when missing
- Quoted 20 frontmatter values containing @ : ` characters (would
  otherwise break YAML parsing)

Examples cleanup:
- Replaced 11 Docusaurus-only inline JSX placeholders (<SupportBot />,
  <RAGChat />, etc.) with explanatory callouts. The interactive sandboxes
  will be reintroduced in a follow-up using AgentsKit's own components
  (dogfooding moment).

Wiring:
- pnpm docs        → now points to docs-next (Fumadocs dev)
- pnpm docs:legacy → preserves the Docusaurus site for transition
- pnpm docs:build  → Fumadocs production build

Decision recorded in:
- docs/architecture/adrs/0007-docs-platform-fumadocs.md

What lands in follow-ups (Phase 0 #211):
- Visual identity (logo, OG image, custom Tailwind tokens)
- docs.agentskit.io domain wiring (depends on #235)
- i18n strategy decision (Crowdin / LLM / freeze)
- Recipes section (#229)
- Migration guides — Vercel AI / LangChain (#241, #242)
- Embedded docs assistant (RAG over docs)
- TypeDoc API reference integration
- Archive apps/docs once parity confirmed and traffic moved

Refs #238 #211

Closes #228. Writes complete Concepts pages for adapter, tool, skill,
memory, retriever, runtime — replacing the placeholder stubs from #277.

Each page follows the same structure:
- One-paragraph definition (what it is, what it isn't)
- Minimal interface (TypeScript code block)
- Built-in usage example
- When to write your own
- Common pitfalls table
- Link to the canonical ADR for full invariants

Content density:
- adapter:    83 lines  (~600 words)
- tool:      139 lines  (~900 words)
- skill:     145 lines  (~950 words)
- memory:    118 lines  (~800 words)
- retriever: 130 lines  (~850 words)
- runtime:   176 lines  (~1100 words)

Built and verified: 56 routes, all 200 in production server.

Aligned with the manifesto principle 'docs are product, not afterthought'
and the load-bearing distinctions:
- Tool (what model calls) vs Skill (what model becomes)
- ChatMemory vs VectorMemory (split, not unified)
- Empty results vs error (the asymmetry across contracts)

Refs #228 #211

Closes #229. Adds a Recipes section with 10 self-contained, copy-paste
recipes plus an index page, all wired into the sidebar.

Recipes (each end-to-end and runnable as written):
- rag-chat                 — streaming React chat grounded in your docs
- pdf-qa                   — CLI Q&A over a local PDF
- code-reviewer            — agent that reads diff, runs tests, posts review
- discord-bot              — bot with per-channel memory and tools
- research-team            — planner + researcher + writer multi-agent
- cost-guarded-chat        — abort the run when budget exceeded (observer)
- persistent-memory        — chat that remembers across processes
- confirmation-gated-tool  — security-critical tool with onConfirm
- custom-adapter           — wrap any LLM API in 30 lines (incl. mock pattern)
- eval-suite               — vitest-based agent quality scoring in CI

Each page follows the same shape:
- One-paragraph framing
- 'Install' line
- Working code (with KEY placeholder)
- 'Run it' command
- 'What's happening' / 'Why this works' explainer
- 'Tighten the recipe' for next steps
- 'Related' links to Concepts + sibling recipes

Notable design choices:
- Index has a table of recipes with elapsed-time estimates (5-15 min)
- All recipes link back to Concepts pages and ADRs for deeper reading
- 'Cost-guarded chat' demonstrates that observers + AbortController are
  enough — no special primitive needed
- 'Custom adapter' includes the deterministic mock-adapter pattern
- 'Eval suite' includes both hard-coded scoring AND llm-as-judge

Build: 67 routes, all 200. Recipes appear in the sidebar between
Concepts and Adapters.

Refs #229 #211

Closes #241. New 'Migrating' section in the sidebar with an index and
the full Vercel AI SDK → AgentsKit migration guide.

Content:
- TL;DR table mapping Vercel AI SDK exports to AgentsKit equivalents
  (streamText, useChat, tool, generateText, experimental_StreamData,
  provider helpers, route handler patterns)
- Six side-by-side migration examples:
  1. Basic streaming chat (client hook)
  2. Securing the API key (server action + route handler variants)
  3. Tool calling (Zod → JSON Schema 7 conversion)
  4. Multi-provider swap
  5. Agent runtime with memory + retrieval (biggest win)
  6. Multi-agent / delegation
  7. Observability / telemetry
- 'Where Vercel AI SDK still wins' — honest callouts:
  generateObject (until Fase 2), consumer chat SDK footprint,
  Vercel-ecosystem investment, v1.0 maturity today
- Incremental migration path (keep existing, add AgentsKit for new
  features, consolidate via the Adapter contract)

Design notes:
- Before/after code blocks preserve the 'recognize my code' feeling;
  no tricks, no cherry-picking
- Callouts cross-link to ADRs so readers can verify claims
- Index page previews LangChain and Mastra guides (follow-ups #242)
- Sidebar order: Getting Started → Concepts → Recipes → Migrating → ...

Refs #241 #211

Closes #242. New page in the Migrating section mapping LangChain.js
patterns to AgentsKit equivalents.

Content:
- TL;DR equivalence table (ChatOpenAI, .invoke/.stream, ChatPromptTemplate,
  StructuredTool, AgentExecutor, BufferMemory, VectorStore, RetrievalQAChain,
  RunnableSequence, LangGraph, callbacks)
- 9 side-by-side migration examples:
  1. Basic chat with streaming
  2. Prompts and templates (no template engine in core — plain JS works)
  3. Tool calling (Zod → JSON Schema 7 bridge)
  4. AgentExecutor → Runtime (biggest win, hard maxSteps cap)
  5. Memory hierarchy → split ChatMemory/VectorMemory
  6. Retrieval / RetrievalQAChain → RAG as a Retriever
  7. Chains / LCEL → plain JavaScript composition
  8. LangGraph → delegation (with honest deferral of durable execution)
  9. Callbacks → Observers
- 'Where LangChain.js still wins' — honest callouts:
  integrations catalog, LangSmith ecosystem, LangGraph today,
  one-library-many-solutions preference, team familiarity
- Incremental migration path (keep LangChain for existing pipelines,
  adopt AgentsKit for new features, port chat layer first)
- Dependency size check (du -sh) showing the 100-200 MB delta

Rationale for the 'honest win' section: LangChain still has the broadest
integration catalog and LangSmith is genuinely useful. Pretending
otherwise loses credibility. The README's 'when NOT to use AgentsKit'
principle applied to this specific migration.

Refs #242 #211

Closes #243. Adds lightweight, privacy-respecting PostHog integration to
the Fumadocs docs site.

Design:
- Opt-in via NEXT_PUBLIC_POSTHOG_KEY. Unset means PostHog never loads —
  localhost, CI, and any deployment without the env var are telemetry-free.
- AnalyticsProvider wraps the app; no-op when key is absent.
- Captures $pageview on every Next.js route change (automatic capture
  disabled, manual via usePathname + useSearchParams so SPA navigation
  is tracked correctly).
- Captures $pageleave for time-on-page.
- Enriches $pageview with a 'section' property inferred from the path
  (home, getting-started, concepts, recipes, migrating, etc.) for easy
  funnel analysis.
- No identify(), no PII, no session recordings.
- Respects Do-Not-Track (respect_dnt: true).
- EU/US host selectable via NEXT_PUBLIC_POSTHOG_HOST.

Exports:
- AnalyticsProvider (used in app/layout.tsx)
- track(event, properties) helper for custom events; no-op when disabled

Docs:
- apps/docs-next/ANALYTICS.md — full audit trail of what's tracked,
  what isn't, enable/disable instructions, privacy notes
- apps/docs-next/.env.example — the two relevant env vars

Verified:
- Build clean, 70 routes all static
- Without key set, HTML contains zero PostHog references (grep 0)
- Suspense boundary around the provider avoids Next 16's
  useSearchParams prerender bailout

Refs #243 #211

Completes the trio of migration guides (Vercel AI SDK + LangChain + Mastra).

Mastra is the closest philosophical cousin to AgentsKit — agent-first,
plug-and-play, not chat-first. That makes the guide the most honest of
the three: the case for migrating is weaker here than from the other two.

Content:
- TL;DR equivalence table (Agent class, createTool, Memory, RAGAgent,
  Workflows, Mastra orchestrator, telemetry)
- 8 side-by-side migration examples:
  1. Basic agent (inline + Skill flavors)
  2. Tool calling (Zod → JSON Schema 7 bridge)
  3. Memory (split working/semantic into ChatMemory + Retriever)
  4. RAG (as a Retriever, not a specialized Agent)
  5. Workflows → delegation (with honest deferral of durable execution)
  6. Evals (shape differences only)
  7. Telemetry (Observer contract vs built-in OTEL)
  8. No orchestrator container (why the Runtime is the smallest unit)
- Generous 'Where Mastra still wins' section:
  - Voice (shipped in Mastra, planned in AgentsKit)
  - Durable long-running workflows (Phase 3 in AgentsKit)
  - Class-per-agent mental model (taste)
  - Mastra Cloud / Studio ecosystem
  - Integration catalog breadth
- Pragmatic migration checklist (7 steps, leave voice in Mastra until shipped)
- Bundle-size check

Key framing: AgentsKit and Mastra agree on philosophy (agent-first,
composable, plug-and-play). The difference is shape and scope —
formal contracts vs evolving class hierarchy, narrow core vs feature-rich
orchestrator. Readers should stay on Mastra if voice, durable workflows,
or Mastra Cloud are load-bearing for them.

Build: 70 routes, all 200.

Refs #211

Ships the chosen brand direction across the docs site. Variant 1.4
from the brand-preview-logos selection (3-circle triangle, foam
monochrome, B-palette terminal background).

Logo:
- public/brand/logo-mark.svg — glyph alone, currentColor, 72x64
- public/brand/logo-wordmark.svg — glyph + 'agentskit' lockup in
  JetBrains Mono Bold
- public/favicon.svg — square with rounded background, baked colors
- public/apple-touch-icon.svg — same shape, 180x180

Open Graph:
- app/api/og/route.tsx — edge runtime, Next.js ImageResponse
- Renders 1200x630 PNG with logo + title + description + tagline strip
- Accepts ?title= and ?description= query params for per-page OG
- public/brand/og-default.png — pre-rendered fallback (28KB)

Theme:
- app/global.css — adds AgentsKit token set under :root and Tailwind
  @theme: ak-midnight, ak-foam, ak-graphite, ak-surface, ak-border,
  ak-green, ak-blue, ak-red, font-mono
- Maps Fumadocs's .dark theme variables to the B palette so the docs
  shell uses our colors out of the box

Layout:
- app/layout.tsx — wires favicon, apple-touch-icon, openGraph,
  twitter card metadata. Adds JetBrains Mono via next/font with
  --font-mono CSS variable. Updates metadataBase to agentskit.io
- app/layout.config.tsx — Fumadocs nav now shows the inline LogoMark
  + 'agentskit' wordmark in mono (no more bare text title)
- app/(home)/page.tsx — landing hero rebuilt around the logo, with
  the new 'JavaScript actually deserves' tagline matching the README

Docs:
- public/brand/README.md — what's where, palette, usage rules,
  token reference

Verified locally:
- pnpm exec next build → 71 routes (added /api/og)
- /api/og returns 1200x630 PNG (28 KB)
- All assets serve 200 in production server
- Logo inherits currentColor, works in dark and light contexts

Refs #211 (Phase 0 visual identity)

Avoids the pnpm fallback that opens npmjs.com when running 'pnpm docs'
from inside apps/docs-next instead of the repo root.

Both work now:
  pnpm docs                    # from repo root (turbo filter)
  cd apps/docs-next && pnpm docs   # from inside the package