feat(docs): setup Fumadocs documentation portal on GitHub Pages and streamline README

.github/workflows/deploy-docs.yaml

@@ -0,0 +1,66 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: docs/pnpm-lock.yaml
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Install dependencies
+        working-directory: docs
+        run: pnpm install --frozen-lockfile
+
+      - name: Build documentation
+        working-directory: docs
+        env:
+          BASE_PATH: /alexandria
+        run: pnpm build
+
+      - name: Add .nojekyll
+        run: touch docs/out/.nojekyll
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/out
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -4,6 +4,7 @@
 *.exe
 *.test
 
+
 # Binary that "go build ./..." drops in the repository root
 /alexandria
 
@@ -39,3 +40,10 @@ coverage.html
 /docs/artifacts/
 CURRENT_NOTES.md
 /CLAUDE.md
+
+# Documentation site (Fumadocs)
+/docs/node_modules/
+/docs/.next/
+/docs/out/
+/docs/.source/
+

Taskfile.yaml

@@ -314,6 +314,16 @@ tasks:
     desc: Scan for known vulnerabilities.
     cmds: ["go run golang.org/x/vuln/cmd/govulncheck@latest ./..."]
 
+  docs:dev:
+    desc: Start the Fumadocs documentation dev server.
+    dir: docs
+    cmds: ["pnpm dev"]
+
+  docs:build:
+    desc: Build static documentation for GitHub Pages.
+    dir: docs
+    cmds: ["pnpm build"]
+
   check:
     desc: "Full pipeline: format, lint and tests."
     cmds:

docs/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+.next
+out
+.source
+.DS_Store

docs/README.md

@@ -0,0 +1,32 @@
+# Alexandria Documentation Site
+
+Documentation portal for Alexandria, built with [Fumadocs](https://fumadocs.dev) and [Next.js](https://nextjs.org), deployed statically to GitHub Pages.
+
+## Local Development
+
+From the repository root:
+```bash
+task docs:dev
+```
+Or directly from `docs/`:
+```bash
+pnpm dev
+```
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+## Static Build
+
+To build the static export for GitHub Pages:
+```bash
+task docs:build
+```
+Or:
+```bash
+pnpm build
+```
+This generates the static files in `docs/out/` with the `/alexandria` base path.
+
+To test the static build locally:
+```bash
+pnpm start
+```

docs/app/(home)/layout.tsx

@@ -0,0 +1,6 @@
+import { HomeLayout } from 'fumadocs-ui/layouts/home';
+import { baseOptions } from '@/lib/layout.shared';
+
+export default function Layout({ children }: LayoutProps<'/'>) {
+  return <HomeLayout {...baseOptions()}>{children}</HomeLayout>;
+}

docs/app/(home)/page.tsx

@@ -0,0 +1,238 @@
+import Image from 'next/image';
+import Link from 'next/link';
+import bannerImg from '@/public/banner.png';
+import {
+  BookOpen,
+  Globe,
+  FileCheck,
+  Wallet,
+  ShieldCheck,
+  Layers,
+  ArrowRight,
+  Sparkles,
+  Terminal,
+  ExternalLink,
+} from 'lucide-react';
+
+export default function HomePage() {
+  const features = [
+    {
+      icon: BookOpen,
+      category: 'Vocabulary Hub',
+      title: 'Single Source of Semantic Truth',
+      description:
+        'Author, version, document, and publish domain ontologies, RDF vocabularies, and dataset profiles to unify meaning across dataspace participants.',
+      link: '/docs/getting-started',
+    },
+    {
+      icon: Globe,
+      category: 'Runtime Semantics',
+      title: 'Dynamic Term Dereferencing',
+      description:
+        'Connectors resolve unknown attribute IRIs in Self-Descriptions on the fly, dereferencing machine-readable RDF schemas, property classes, and multilingual labels.',
+      link: '/docs/getting-started',
+    },
+    {
+      icon: FileCheck,
+      category: 'Conformance & Testing',
+      title: 'Remote Conformance Tests',
+      description:
+        'Automated semantic verification using SHACL constraint shapes. Validates that connector payloads, catalogs, and dataset offerings strictly conform to dataspace rules.',
+      link: '/docs/development/conformance',
+    },
+    {
+      icon: Wallet,
+      category: 'Trust & SSI Anchor',
+      title: 'Unified Wallet Port',
+      description:
+        'Cryptographic keys and signing material never reside in the node. Pluggable adapters decouple domain logic from Fafnir and Eclipse EDC IdentityHub.',
+      link: '/docs/architecture/wallet-port',
+    },
+    {
+      icon: ShieldCheck,
+      category: 'Access Control',
+      title: 'Node-Terminated OIDC IAM',
+      description:
+        'Authentication terminates at the node with encrypted HttpOnly session cookies and PKCE via Zitadel. Protects vocabulary authoring and remote testing endpoints.',
+      link: '/docs/development/authentication',
+    },
+    {
+      icon: Layers,
+      category: 'Architecture',
+      title: 'In-Process Seams & Full TLS',
+      description:
+        'Engineered as an in-process modular monolith with strict Go package seams, full TLS reverse proxy parity via Caddy, and one-command startup.',
+      link: '/docs/architecture/bounded-contexts',
+    },
+  ];
+
+  return (
+    <div className="flex flex-col flex-1 pb-20">
+      {/* Hero Section */}
+      <section className="relative overflow-hidden pt-12 sm:pt-20 pb-16 px-4 sm:px-6">
+        <div className="max-w-5xl mx-auto text-center">
+          {/* Badge */}
+          <div className="inline-flex items-center gap-2 px-3.5 py-1.5 mb-8 rounded-full border border-fd-border bg-fd-card/80 backdrop-blur-md text-xs font-medium text-fd-foreground shadow-xs">
+            <Sparkles className="size-3.5 text-[#e6007e]" />
+            <span>Semantic Interoperability & Dataspace Ontologies</span>
+          </div>
+
+          {/* Headline */}
+          <h1 className="text-4xl sm:text-6xl font-extrabold tracking-tight mb-6 leading-[1.15]">
+            The Vocabulary Hub for{' '}
+            <span className="text-alexandria-gradient">Sovereign Dataspaces</span>
+          </h1>
+
+          {/* Subtitle */}
+          <p className="max-w-3xl mx-auto text-base sm:text-lg text-fd-muted-foreground leading-relaxed mb-10">
+            Publish and maintain domain ontologies, dereference semantic terms in real-time for dataspace connectors, and run automated remote conformance tests with verifiable trust.
+          </p>
+
+          {/* CTAs */}
+          <div className="flex flex-wrap items-center justify-center gap-4">
+            <Link
+              href="/docs/getting-started"
+              className="inline-flex items-center gap-2 rounded-xl bg-alexandria-gradient text-white px-6 py-3 text-sm font-semibold shadow-md shadow-[#e6007e]/20 transition-all hover:scale-[1.02] hover:shadow-lg hover:shadow-[#e6007e]/30"
+            >
+              <span>Explore Vocabulary Hub</span>
+              <ArrowRight className="size-4" />
+            </Link>
+
+            <Link
+              href="/docs/development/conformance"
+              className="inline-flex items-center gap-2 rounded-xl border border-fd-border bg-fd-card px-6 py-3 text-sm font-semibold transition-colors hover:bg-fd-accent hover:text-fd-accent-foreground shadow-xs"
+            >
+              <FileCheck className="size-4 text-[#ff3366]" />
+              <span>Remote Conformance & API</span>
+            </Link>
+
+            <a
+              href="https://github.com/caparicio-esd/alexandria"
+              target="_blank"
+              rel="noreferrer"
+              className="inline-flex items-center gap-2 rounded-xl border border-fd-border/70 bg-fd-card/50 px-5 py-3 text-sm font-medium text-fd-muted-foreground hover:text-fd-foreground hover:border-fd-border transition-colors"
+            >
+              <span>GitHub</span>
+              <ExternalLink className="size-3.5" />
+            </a>
+          </div>
+
+          {/* Hero Banner Visual */}
+          <div className="relative mt-14 sm:mt-18 mx-auto max-w-5xl group">
+            <div className="absolute -inset-1 bg-gradient-to-r from-[#e6007e] via-[#ff3366] to-[#ff7a00] rounded-2xl blur-xl opacity-20 dark:opacity-30 transition duration-700 group-hover:opacity-40" />
+            <div className="relative overflow-hidden rounded-2xl border border-fd-border bg-fd-card shadow-2xl p-2 sm:p-3">
+              <Image
+                src={bannerImg}
+                alt="Alexandria Vocabulary Hub Ecosystem"
+                priority
+                className="w-full h-auto rounded-xl object-cover"
+              />
+            </div>
+          </div>
+        </div>
+      </section>
+
+      {/* Feature Cards Section */}
+      <section className="max-w-6xl mx-auto px-4 sm:px-6 py-16">
+        <div className="text-center max-w-2xl mx-auto mb-14">
+          <h2 className="text-2xl sm:text-3xl font-bold tracking-tight mb-3">
+            Core Semantic & Architectural Pillars
+          </h2>
+          <p className="text-sm sm:text-base text-fd-muted-foreground">
+            Enabling frictionless semantic interoperability and verified compliance across heterogeneous dataspace connectors.
+          </p>
+        </div>
+
+        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+          {features.map((feature, idx) => {
+            const Icon = feature.icon;
+            return (
+              <Link
+                key={idx}
+                href={feature.link}
+                className="group relative flex flex-col justify-between p-6 rounded-2xl border border-fd-border bg-fd-card transition-all hover:border-[#ff3366]/50 hover:shadow-lg hover:shadow-[#ff3366]/5"
+              >
+                <div>
+                  <div className="flex items-center justify-between mb-4">
+                    <span className="p-2.5 rounded-xl bg-fd-accent text-[#e6007e] dark:text-[#ff3e73] transition-colors group-hover:scale-110">
+                      <Icon className="size-5" />
+                    </span>
+                    <span className="text-xs font-medium text-fd-muted-foreground uppercase tracking-wider">
+                      {feature.category}
+                    </span>
+                  </div>
+                  <h3 className="text-base font-semibold mb-2 group-hover:text-[#e6007e] dark:group-hover:text-[#ff3e73] transition-colors">
+                    {feature.title}
+                  </h3>
+                  <p className="text-sm text-fd-muted-foreground leading-relaxed">
+                    {feature.description}
+                  </p>
+                </div>
+                <div className="mt-5 flex items-center gap-1.5 text-xs font-semibold text-[#e6007e] dark:text-[#ff3e73]">
+                  <span>Explore documentation</span>
+                  <ArrowRight className="size-3 transition-transform group-hover:translate-x-1" />
+                </div>
+              </Link>
+            );
+          })}
+        </div>
+      </section>
+
+      {/* Quick Launch Terminal Preview */}
+      <section className="max-w-4xl mx-auto px-4 sm:px-6 py-8">
+        <div className="rounded-2xl border border-fd-border bg-fd-card overflow-hidden shadow-xl">
+          <div className="flex items-center justify-between px-4 py-3 border-b border-fd-border bg-fd-muted/50">
+            <div className="flex items-center gap-2">
+              <span className="size-3 rounded-full bg-red-500/80" />
+              <span className="size-3 rounded-full bg-yellow-500/80" />
+              <span className="size-3 rounded-full bg-green-500/80" />
+              <span className="ml-2 text-xs font-mono text-fd-muted-foreground flex items-center gap-1.5">
+                <Terminal className="size-3" />
+                alexandria — dev:auto
+              </span>
+            </div>
+            <span className="text-[11px] font-mono text-fd-muted-foreground">bash</span>
+          </div>
+          <div className="p-5 font-mono text-xs sm:text-sm bg-black/90 text-neutral-200 overflow-x-auto leading-relaxed">
+            <div className="text-neutral-400"># Start the full stack with TLS, IAM, and wallet link:</div>
+            <div className="text-[#ff3e73] mt-1 font-semibold">$ task dev:auto</div>
+            <div className="text-neutral-400 mt-3">✔ Caddy Reverse Proxy:      https://alexandria.127.0.0.1.nip.io:8443</div>
+            <div className="text-neutral-400">✔ Zitadel IAM Provider:     https://auth.127.0.0.1.nip.io:8443</div>
+            <div className="text-neutral-400">✔ Vocabulary Engine:        Active (RDF / OWL / SHACL registry)</div>
+            <div className="text-neutral-400">✔ Remote Conformance Suite: Ready for connector validation</div>
+            <div className="text-neutral-400">✔ Identity & Wallet Link:   DID resolvable at /.well-known/did.json</div>
+            <div className="text-emerald-400 mt-2">✨ Alexandria Vocabulary Hub running with live reload</div>
+          </div>
+        </div>
+      </section>
+
+      {/* Bottom CTA Banner */}
+      <section className="max-w-5xl mx-auto px-4 sm:px-6 pt-12">
+        <div className="relative rounded-2xl overflow-hidden p-8 sm:p-12 text-center border border-fd-border bg-fd-card">
+          <div className="absolute -top-24 left-1/2 -translate-x-1/2 w-96 h-96 bg-alexandria-gradient rounded-full blur-3xl opacity-10 pointer-events-none" />
+          <h2 className="text-2xl sm:text-3xl font-bold tracking-tight mb-4">
+            Powering Semantic Interoperability in Sovereign Dataspaces
+          </h2>
+          <p className="max-w-2xl mx-auto text-sm sm:text-base text-fd-muted-foreground mb-8">
+            Learn how Alexandria manages vocabulary lifecycles, dereferences term IRIs in real time, and executes remote SHACL conformance tests to certify dataspace data models.
+          </p>
+          <div className="flex flex-wrap items-center justify-center gap-4">
+            <Link
+              href="/docs/getting-started"
+              className="inline-flex items-center gap-2 rounded-xl bg-fd-primary text-fd-primary-foreground px-6 py-2.5 text-sm font-semibold shadow-xs hover:bg-fd-primary/90 transition-colors"
+            >
+              <span>Explore the Guide</span>
+              <ArrowRight className="size-4" />
+            </Link>
+            <Link
+              href="/docs/development/conformance"
+              className="inline-flex items-center gap-2 rounded-xl border border-fd-border bg-fd-card px-6 py-2.5 text-sm font-semibold hover:bg-fd-accent hover:text-fd-accent-foreground transition-colors shadow-xs"
+            >
+              <span>Remote Conformance & Testing</span>
+            </Link>
+          </div>
+        </div>
+      </section>
+    </div>
+  );
+}

docs/app/api/search/route.ts

@@ -0,0 +1,9 @@
+import { source } from '@/lib/source';
+import { createFromSource } from 'fumadocs-core/search/server';
+
+export const revalidate = false;
+
+export const { staticGET: GET } = createFromSource(source, {
+  // https://docs.orama.com/docs/orama-js/supported-languages
+  language: 'english',
+});