refactor(website): adopt Fumadocs and Astryx

website/.gitignore

@@ -12,13 +12,15 @@
 
 # testing
 /coverage
+/output/
+/.playwright-cli/
 
 # next.js
 /.next/
 /out/
 
-# docs synced from ../docs at build time (single source of truth lives there)
-/content/docs/
+# Fumadocs' generated source adapter (the Markdown itself stays in the repo root)
+/.source/
 
 # test262 dashboard snapshot synced from CI artifacts at build time
 /content/test262/

website/README.md

@@ -1,6 +1,6 @@
 # GocciaScript website
 
-The marketing/docs site for GocciaScript — a Next.js 16 app under `website/`. Markdown content for the docs section is synced from `../docs/` at build time via `scripts/sync-docs.mjs`.
+The marketing/docs site for GocciaScript — a Next.js 16 app under `website/`. Fumadocs reads `../README.md` and `../docs/**/*.md` directly, while Astryx provides the shared shell and generic controls. The warm-paper GocciaScript theme remains project-owned.
 
 Bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
 
@@ -9,20 +9,15 @@ Bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/
 First, run the development server:
 
 ```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+bun install --frozen-lockfile
+bun run dev
 ```
 
 Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
 
-You can start editing the page by modifying `src/app/page.tsx`. The page auto-updates as you edit the file.
+Edit route UI under `src/app/` and `src/components/`. Edit documentation in the repository root; `source.config.ts` defines the collection and generated routes update automatically.
 
-Fonts (Instrument Serif + IBM Plex Sans) are loaded directly in `src/app/layout.tsx` via `<link>` from Google Fonts; the OG image generator (`src/app/opengraph-image.tsx`) fetches the same `.ttf` files at build time.
+Fonts (Instrument Serif, IBM Plex Sans, and JetBrains Mono) are loaded through `next/font` in `src/app/layout.tsx`; the OG image generator (`src/app/opengraph-image.tsx`) embeds the matching display and body fonts.
 
 ## Learn More
 

website/next.config.d.mts

@@ -0,0 +1,4 @@
+import type { NextConfig } from "next";
+
+declare const nextConfig: NextConfig;
+export default nextConfig;

website/next.config.ts → website/next.config.mjs

@@ -1,7 +1,10 @@
-import type { NextConfig } from "next";
-import { AGENT_DISCOVERY_LINK_HEADER } from "./src/lib/agent-discovery";
+import { fileURLToPath } from "node:url";
+import { createMDX } from "fumadocs-mdx/next";
+import { AGENT_DISCOVERY_LINK_HEADER } from "./src/lib/agent-discovery-header.mjs";
 
-const nextConfig: NextConfig = {
+const withMDX = createMDX();
+
+const nextConfig = {
   async headers() {
     return [
       {
@@ -28,6 +31,11 @@ const nextConfig: NextConfig = {
     "/api/execute": ["./vendor/**"],
     "/api/test": ["./vendor/**"],
   },
+  // The documentation collection deliberately lives one level above the
+  // Next.js package. Turbopack otherwise refuses to resolve those files.
+  turbopack: {
+    root: fileURLToPath(new URL("..", import.meta.url)),
+  },
 };
 
-export default nextConfig;
+export default withMDX(nextConfig);

website/package.json

@@ -3,17 +3,15 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "sync-docs": "node scripts/sync-docs.mjs",
     "publish-test262": "bun scripts/publish-test262-results.ts",
     "publish-awfy": "bun scripts/publish-awfy-report.ts",
     "publish-jetstream": "bun scripts/publish-jetstream-report.ts",
     "publish-web-tooling": "bun scripts/publish-web-tooling-report.ts",
     "backfill-test262": "bun scripts/backfill-test262-dashboard.ts",
-    "predev": "node scripts/sync-docs.mjs",
-    "prebuild": "node scripts/sync-docs.mjs && bun scripts/fetch-binaries.ts",
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start",
+    "prebuild": "bun scripts/fetch-binaries.ts",
+    "dev": "bun --bun next dev",
+    "build": "bun --bun next build",
+    "start": "bun --bun next start",
     "lint": "biome check",
     "format": "biome format --write",
     "test": "bun test"
@@ -34,7 +32,11 @@
     ]
   },
   "dependencies": {
+    "@astryxdesign/core": "^0.1.6",
+    "@stylexjs/stylex": "^0.19.0",
     "@vercel/blob": "^2.4.0",
+    "fumadocs-core": "^16.11.5",
+    "fumadocs-mdx": "^15.2.0",
     "mermaid": "^11.15.0",
     "next": "16.2.9",
     "posthog-js": "^1.372.1",
@@ -47,6 +49,7 @@
     "@biomejs/biome": "2.4.13",
     "@tailwindcss/postcss": "^4",
     "@types/bun": "^1.3.13",
+    "@types/mdx": "^2.0.13",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",

website/source.config.ts

@@ -0,0 +1,53 @@
+import { defineConfig, defineDocs } from "fumadocs-mdx/config";
+import { z } from "zod";
+
+function titleFromMarkdown(source: string, path: string): string {
+  const heading = source.match(/^#\s+(.+)$/m)?.[1]?.trim();
+  if (heading) {
+    return heading
+      .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+      .replace(/[*_`]/g, "");
+  }
+  return (
+    path
+      .replace(/(?:^|\/)README\.md$/i, "")
+      .replace(/\.mdx?$/i, "")
+      .split("/")
+      .at(-1)
+      ?.replace(/[-_]+/g, " ") ?? "GocciaScript"
+  );
+}
+
+export const docs = defineDocs({
+  // The repository Markdown is the source of truth. Fumadocs compiles it in
+  // place, so the website no longer needs a copied content tree.
+  dir: "..",
+  docs: {
+    files: ["README.md", "docs/**/*.md"],
+    // Existing docs use their first H1 as the title. Adapt that convention at
+    // the collection boundary rather than adding website-only frontmatter to
+    // every repository document.
+    schema: ({ source, path }) =>
+      z
+        .object({
+          title: z.string().optional(),
+          description: z.string().optional(),
+        })
+        .transform((frontmatter) => ({
+          ...frontmatter,
+          title: frontmatter.title ?? titleFromMarkdown(source, path),
+        })),
+    lastModified: true,
+    postprocess: {
+      includeProcessedMarkdown: true,
+    },
+  },
+  // There are no Fumadocs ordering files in the repository. Narrowing the
+  // meta glob prevents the repo-root collection from treating unrelated JSON
+  // files (including dependencies) as documentation metadata.
+  meta: {
+    files: ["docs/**/meta.json"],
+  },
+});
+
+export default defineConfig();

website/src/__tests__/agent-discovery.test.ts

@@ -26,7 +26,7 @@ import {
   sha256Digest,
   versionFromReleaseTag,
 } from "@/lib/agent-discovery";
-import nextConfig from "../../next.config";
+import nextConfig from "../../next.config.mjs";
 
 describe("agent discovery", () => {
   test("homepage advertises agent-useful Link relations", async () => {