feat(docs): migrate the docs site to Fumadocs + shared landing package

.github/workflows/docs.yml

@@ -1,18 +1,20 @@
 name: Docs
 
-# Build the VitePress site (bespoke landing in public/, guides, and TypeDoc-generated
-# API reference) and deploy it to GitHub Pages on every push to main that touches
+# Build the Fumadocs site (website/, a Next.js static export with the shared
+# light-landing-page home, the MDX guides, and a TypeDoc-generated API
+# reference) and deploy it to GitHub Pages on every push to main that touches
 # the docs sources or the public surface they describe.
 
 on:
   push:
     branches: [main]
     paths:
-      - 'docs/**'
+      - 'website/**'
       - 'src/**'
+      - 'scripts/gen-fumadocs-api.mjs'
+      - 'typedoc.json'
       - 'package.json'
       - 'package-lock.json'
-      - 'typedoc.json'
       - '.github/workflows/docs.yml'
   workflow_dispatch:
 
@@ -29,30 +31,39 @@ permissions:
 
 jobs:
   build:
-    name: Build VitePress site
+    name: Build Fumadocs site
     runs-on: ubuntu-latest
 
     steps:
       - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0  # lastUpdated needs the full history
 
       - name: Setup Node.js 24
         uses: actions/setup-node@v6
         with:
           node-version: 24
           cache: npm
 
-      - name: Install dependencies
+      # Root deps (typedoc + typedoc-plugin-markdown) power the API generation.
+      - name: Install root dependencies
         run: npm ci
 
-      - name: Regenerate TypeDoc markdown + build VitePress
-        run: npm run docs
+      # Regenerate the API reference from the current src/ so it can never
+      # drift from the code.
+      - name: Regenerate the API reference
+        run: npm run docs:api
+
+      # The website is its own package; it pulls the shared landing
+      # (light-landing-page) via its lockfile.
+      - name: Install website dependencies
+        run: npm --prefix website ci
+
+      - name: Build the static export
+        run: npm --prefix website run build
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: docs/.vitepress/dist
+          path: website/out
 
   deploy:
     name: Deploy to GitHub Pages

.husky/pre-commit

@@ -1,14 +1,14 @@
-# Regenerates docs/api/ ONLY if files under src/ are staged. Keeps the commit
-# UX snappy for pure-test or pure-config commits.
+# Regenerates the Fumadocs API reference ONLY if files under src/ are staged.
+# Keeps the commit UX snappy for pure-test or pure-config commits.
 
 set -e
 
 staged=$(git diff --cached --name-only --diff-filter=ACMR)
 echo "$staged" | grep -qE '^src/' || exit 0
 
-echo "[pre-commit] src/ changed - regenerating docs/api/ ..."
-npm run --silent docs:typedoc > /dev/null
+echo "[pre-commit] src/ changed - regenerating the API reference ..."
+npm run --silent docs:api > /dev/null
 
-git add docs/api/
+git add website/content/docs/api/
 
-echo "[pre-commit] docs/api/ updated and staged."
+echo "[pre-commit] website/content/docs/api/ updated and staged."