Cadence-lang redesign + AI tools (MCP, federated search, llms.txt, AI chat, integrations)

.env.example

@@ -1,6 +1,12 @@
+# Site URL for OG meta tags (no trailing slash)
+VITE_SITE_URL=https://cadence-lang.org
 
-TYPESENSE_NODE="<TYPESENSE_NODE>"
-TYPESENSE_SEARCH_ONLY_API_KEY="<TYPESENSE_SEARCH_ONLY_API_KEY>"
-TYPESENSE_ADMIN_API_KEY="<TYPESENSE_ADMIN_API_KEY>"
+# Skills command org name (shown on homepage: npx skills add <ORG>/cadence-lang.org)
+# Set to "outblock" for Outblock deployment, defaults to "onflow" if unset
+VITE_SKILLS_ORG=onflow
 
-MIXPANEL_PROJECT_TOKEN="<MIXPANEL_PROJECT_TOKEN>"
+# Anthropic API key for AI chat (server-only, never sent to browser)
+ANTHROPIC_API_KEY=
+
+# Analytics (optional)
+VITE_GTAG=

.gitignore

@@ -1,21 +1,31 @@
 # Dependencies
-/node_modules
+node_modules
 
-# Production
+# Build output
+/.output
+/.vercel/output
+dist
 /build
 
 # Generated files
-.docusaurus
-.cache-loader
+.source
+.vinxi
+.tanstack
+src/routeTree.gen.ts
+public/sitemap.xml
+
+# IDE
+.idea
+.vscode
 
 # Misc
 .DS_Store
 .env.local
 .env.development.local
 .env.test.local
 .env.production.local
+.env
 
 npm-debug.log*
 yarn-debug.log*
-yarn-error.log*
-.env
+bun-debug.log*

CLAUDE.md

@@ -0,0 +1,76 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Documentation and marketing site for the **Cadence** programming language (Flow blockchain). Built with TanStack Start + Fumadocs + Tailwind CSS v4, deployed on Vercel.
+
+## Commands
+
+```bash
+npm run dev          # Dev server on port 3000
+npm run build        # Production build + sitemap generation
+npm run start        # Run built server (node .output/server/index.mjs)
+npm run types:check  # TypeScript + MDX type checking (fumadocs-mdx && tsc --noEmit)
+```
+
+The Cadence MCP server is bundled with the Flow CLI as `flow mcp` (Flow CLI ≥ v2.16.0); it lives at [onflow/flow-cli/internal/mcp](https://github.com/onflow/flow-cli/tree/master/internal/mcp), not in this repo.
+
+## Architecture
+
+### Framework Stack
+- **TanStack Start** — file-based routing with SSR via Nitro (Vercel preset)
+- **Fumadocs** — MDX docs engine (`fumadocs-core`, `fumadocs-ui`, `fumadocs-mdx`)
+- **Tailwind CSS v4** — styling via `@tailwindcss/vite` plugin (no separate config file)
+- **@vercel/og** — server-side OG image generation (Satori + resvg-wasm)
+
+### Key Directories
+- `src/routes/` — TanStack Start file-based routes
+- `src/routes/api/` — Server-only API endpoints (chat, search)
+- `src/routes/og.*.tsx` — OG image generation routes (server handlers)
+- `src/components/` — React components; `ui/` has shadcn-style primitives
+- `src/lib/` — Utilities, Fumadocs source config, Cadence TextMate grammar
+- `content/docs/` — All MDX documentation files
+- `.source/` — Auto-generated by Fumadocs (do not edit)
+
+### Routing Patterns
+- `docs/$.tsx` — catch-all route for doc pages via Fumadocs
+- `og.docs.$.tsx` — dynamic OG images per doc page
+- `llms.txt.ts` / `llms-full.txt.ts` — LLM-optimized doc endpoints
+- Server-only handlers use `createFileRoute().server.handlers.GET/POST`
+- `routeTree.gen.ts` is auto-generated; never edit manually
+
+### Docs Content
+- MDX files in `content/docs/` with YAML frontmatter (`title`, `description`, optional `icon`)
+- Cadence syntax highlighting via custom TextMate grammar (`src/lib/cadence.tmLanguage.json`)
+- Shiki dual themes: `github-light` (light mode) + `github-dark` (dark mode), controlled by CSS variables in `src/styles/app.css`
+- Admonition types configured in `source.config.ts`: note, tip, info, warn, warning, danger, important, success
+- Fumadocs source loader in `src/lib/source.ts`
+
+### OG Images
+- Generated at request time using `@vercel/og` (not pre-rendered)
+- Satori **cannot render SVG `<path>` elements** — use PNG base64 data URIs for icons (`src/lib/og-icon.ts`)
+- `VITE_SITE_URL` env var controls the domain in meta tags (defaults to `https://cadence-lang.org`)
+
+### AI Chat
+- `/api/chat` endpoint is server-only (`ANTHROPIC_API_KEY` never reaches client)
+- Uses `ai` SDK with streaming; frontend uses `useChat` from `@ai-sdk/react`
+- Search panel: `src/components/search.tsx` (Cmd+/ hotkey, draggable, localStorage persistence)
+
+## Environment Variables
+
+```bash
+VITE_SITE_URL=https://cadence-lang.org  # OG/meta tag URLs (no trailing slash)
+VITE_SKILLS_ORG=onflow                  # Homepage skills command org
+VITE_GTAG=                              # Google Analytics (optional)
+ANTHROPIC_API_KEY=                       # Server-only, for /api/chat
+```
+
+## Conventions
+
+- Use `cn()` from `src/lib/cn.ts` for Tailwind class merging (clsx + tailwind-merge)
+- Theme colors defined as CSS variables in `src/styles/app.css` (`--accent`, Fumadocs overrides)
+- Dark mode uses `dark` class on `<html>` (Fumadocs convention)
+- Nav links and layout options configured in `src/lib/layout.shared.tsx`
+- Site URL centralized in `src/lib/site.ts` (strips trailing slashes)

Dockerfile

@@ -0,0 +1,41 @@
+FROM oven/bun:1
+
+USER root
+WORKDIR /app
+
+# Install Flow CLI to /usr/local/bin
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends curl ca-certificates \
+    && curl -fsSL https://raw.githubusercontent.com/onflow/flow-cli/master/install.sh | sh \
+    && ls -la /root/.local/bin/flow* \
+    && cp /root/.local/bin/flow /usr/local/bin/flow \
+    && chmod +x /usr/local/bin/flow \
+    && /usr/local/bin/flow version \
+    && apt-get remove -y curl \
+    && apt-get autoremove -y \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy and install deps
+COPY mcp-server/package.json mcp-server/bun.lock ./mcp-server/
+RUN cd mcp-server && bun install --frozen-lockfile || bun install
+
+# Copy source
+COPY mcp-server/src/ ./mcp-server/src/
+COPY mcp-server/flow.json ./mcp-server/flow.json
+COPY content/ ./content/
+
+# Clone Flow ecosystem docs for MCP search
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends git \
+    && git clone --depth 1 https://github.com/onflow/docs.git /app/external/onflow-docs \
+    && apt-get remove -y git \
+    && apt-get autoremove -y \
+    && rm -rf /var/lib/apt/lists/* /app/external/onflow-docs/.git
+
+WORKDIR /app/mcp-server
+
+ENV PORT=3001
+ENV FLOW_CMD=/usr/local/bin/flow
+EXPOSE 3001
+
+CMD ["bun", "src/http.ts"]

README.md

@@ -1,24 +1,41 @@
 # cadence-lang.org
 
-If you're looking for the live site, you can find it at [cadence-lang.org](https://cadence-lang.org).
+The official documentation site for [Cadence](https://github.com/onflow/cadence), the resource-oriented programming language for the [Flow blockchain](https://flow.com).
 
-## Technical
+Live at [cadence-lang.org](https://cadence-lang.org).
 
-cadence-lang.org uses [Docusaurus2](https://docusaurus.io).
+## AI Integration
 
-### Running locally
+### Skills
 
-Requirements:
+Install Flow's Claude Code skill suite from the [`onflow/flow-ai-tools`](https://github.com/onflow/flow-ai-tools) marketplace. In Claude Code:
 
-- [Git](https://git-scm.com/)
-- [Node.js](https://nodejs.org/en)
+```bash
+/plugin marketplace add onflow/flow-ai-tools
+/plugin install flow-dev@flow-ai-tools
+/reload-plugins
+```
+
+### MCP Server
 
-To run the site locally, enter the following commands into a terminal window:
+The Cadence MCP server is built into the [Flow CLI](https://developers.flow.com/tools/flow-cli) (≥ v2.16.0) as `flow mcp`. Source: [onflow/flow-cli/internal/mcp](https://github.com/onflow/flow-cli/tree/master/internal/mcp).
 
 ```sh
-git clone https://github.com/onflow/cadence-lang.org.git
-cd cadence-lang.org
-npm i
-npm run start
-open "http://localhost:3000"
+claude mcp add --scope user cadence-mcp -- flow mcp
 ```
+
+### LLM Context
+
+| Endpoint | Description |
+|----------|-------------|
+| [cadence-lang.org/llms.txt](https://cadence-lang.org/llms.txt) | Cadence doc index for LLMs |
+| [cadence-lang.org/llms-full.txt](https://cadence-lang.org/llms-full.txt) | Full Cadence documentation as plain text |
+
+## Tech Stack
+
+- [TanStack Start](https://tanstack.com/start) — SSR framework with file-based routing
+- [Fumadocs](https://fumadocs.vercel.app/) — MDX documentation engine
+- [Tailwind CSS v4](https://tailwindcss.com/) — styling
+- [Shiki](https://shiki.style/) — syntax highlighting with custom Cadence TextMate grammar
+- [@vercel/og](https://vercel.com/docs/functions/og-image-generation) — dynamic OG image generation
+- Deployed on [Vercel](https://vercel.com)