artdaw · artdaw · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026
diff --git a/website/README.md b/website/README.md
@@ -6,16 +6,47 @@ Vite + React 19 + TypeScript documentation site for the KNDL project.
 
 ## Routes
 
-Uses `createHashRouter` — all routes are prefixed with `#` (e.g. `/#/spec`) so the site works on static hosting without a server-side fallback.
-
-| Hash path | Page | Description |
-|-----------|------|-------------|
-| `/#/` | LandingPage | Hero, v0.2 feature highlights, quick-start snippet |
-| `/#/spec` | SpecPage | Language reference with 8-domain tabbed examples + live playground |
-| `/#/spec/full` | SpecFullPage | Full rendered SPECIFICATION.md |
-| `/#/workflow` | WorkflowPage | 6-stage agent pipeline animation |
-| `/#/explorer` | ExplorerPage | Force-directed graph explorer (pan/zoom/drag, detail panel) |
-| `/#/mcp` | McpPage | MCP server docs and tool reference |
+Uses `createBrowserRouter` with a GitHub Pages SPA fallback (`public/404.html` stashes the intended pathname in `sessionStorage`; `main.tsx` replays it on boot). Clean URLs (no `#`) are required for real SEO.
+
+| Path | Page | Description |
+|------|------|-------------|
+| `/` | LandingPage | Hero, v1.0 feature highlights, quick-start snippet |
+| `/spec` | SpecPage | Language reference with 8-domain tabbed examples + live playground |
+| `/spec/full` | SpecFullPage | Full rendered SPECIFICATION.md with sticky TOC |
+| `/workflow` | WorkflowPage | 6-stage agent pipeline animation (per-stage insight + highlighted layer) |
+| `/explorer` | ExplorerPage | Force-directed graph explorer (pan/zoom/drag, detail panel) |
+| `/mcp` | McpPage | MCP server docs and tool reference |
+
+## Machine-readable discovery surfaces
+
+Everything below is served as a static file and is meant to be fetched by AI agents, search engines, and scripts.
+
+| URL | Format | Purpose |
+|-----|--------|---------|
+| `/llms.txt` | markdown | Concise [llmstxt.org](https://llmstxt.org) index of the whole project |
+| `/llms-full.txt` | markdown | Spec + EBNF + example index concatenated — single-fetch bundle for LLMs |
+| `/spec/SPECIFICATION.md` | markdown | Canonical language reference (mirrored from repo `spec/`) |
+| `/spec/kndl.ebnf` | text | Authoritative EBNF grammar (mirrored from repo `spec/grammar/`) |
+| `/examples/index.md` | markdown | Index of curated `.kndl` snippets |
+| `/examples/*.kndl` | text | Runnable examples (basic-building, intent-overheat, process-shipment, query-aggregation, healthcare-observation, fintech-transaction, robotics-pose, logistics-trace) |
+| `/sitemap.xml` | xml | Every indexable URL on the site |
+| `/robots.txt` | text | Explicitly allows major AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot, …) |
+| `/.well-known/security.txt` | text | Security contact per [securitytxt.org](https://securitytxt.org) |
+
+The Vite plugin `kndlSpecAssets` in `vite.config.ts` mirrors `spec/SPECIFICATION.md` and `spec/grammar/kndl.ebnf` from the repo root into the built output at these URLs and serves them in dev. It also regenerates `llms-full.txt` from source on each build.
+
+## SEO per route
+
+`src/components/SEO.tsx` is a tiny runtime component that each page renders. It updates:
+
+- `<title>` and `<meta name="description">`
+- `<meta name="robots">` with `max-image-preview:large`
+- Open Graph (`og:title`, `og:description`, `og:url`, `og:type`, `og:image`, `og:site_name`)
+- Twitter cards (`twitter:*`)
+- `<link rel="canonical">` and `<link rel="alternate">` (llm index)
+- Per-page JSON-LD (`TechArticle` for docs, `SoftwareSourceCode` for the landing page)
+
+`index.html` also contains a page-level JSON-LD `@graph` covering Organization, WebSite, SoftwareSourceCode, and TechArticle, plus a `<noscript>` pointer to the machine-readable surfaces for crawlers that don't execute JS.
 
 ## Stack
 

diff --git a/website/index.html b/website/index.html
@@ -3,14 +3,23 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#0b0f14" />
+
+    <!-- Default SEO — per-route pages override these via <SEO> at runtime. -->
     <title>KNDL — Knowledge Node Description Language</title>
-    <meta name="description" content="KNDL is a graph-based knowledge representation language for AI agents — typed nodes, confidence scores, temporal decay, and native intent blocks." />
+    <meta name="description" content="KNDL is a graph-based knowledge representation language for AI agents — typed nodes, 0.0–1.0 confidence scores, temporal decay, cryptographic provenance, and native intent/process blocks." />
+    <meta name="keywords" content="knowledge graph, AI agent memory, KNDL, confidence score, temporal decay, provenance, MCP, LLM memory, semantic data, knowledge representation" />
+    <meta name="author" content="Gleb Galkin" />
+    <meta name="robots" content="index,follow,max-image-preview:large" />
+
+    <link rel="canonical" href="https://kndl.artdaw.com/" />
 
     <!-- Open Graph -->
     <meta property="og:type" content="website" />
+    <meta property="og:site_name" content="KNDL" />
     <meta property="og:url" content="https://kndl.artdaw.com/" />
     <meta property="og:title" content="KNDL — Knowledge Node Description Language" />
-    <meta property="og:description" content="A graph-based knowledge representation language for AI agents — typed nodes, confidence scores, temporal decay, and native intent blocks." />
+    <meta property="og:description" content="A graph-based knowledge representation language for AI agents — typed nodes, confidence scores, temporal decay, and native intent/process blocks." />
     <meta property="og:image" content="https://kndl.artdaw.com/kndl.png" />
     <meta property="og:image:width" content="1860" />
     <meta property="og:image:height" content="864" />
@@ -19,16 +28,102 @@
     <meta name="twitter:card" content="summary_large_image" />
     <meta name="twitter:url" content="https://kndl.artdaw.com/" />
     <meta name="twitter:title" content="KNDL — Knowledge Node Description Language" />
-    <meta name="twitter:description" content="A graph-based knowledge representation language for AI agents — typed nodes, confidence scores, temporal decay, and native intent blocks." />
+    <meta name="twitter:description" content="A graph-based knowledge representation language for AI agents — typed nodes, confidence scores, temporal decay, and native intent/process blocks." />
     <meta name="twitter:image" content="https://kndl.artdaw.com/kndl.png" />
 
+    <!-- Machine-readable discovery -->
+    <link rel="sitemap" type="application/xml" href="/sitemap.xml" />
+    <link rel="alternate" type="text/markdown" href="/spec/SPECIFICATION.md" title="KNDL Specification (markdown)" />
+    <link rel="alternate" type="text/plain" href="/spec/kndl.ebnf" title="KNDL EBNF Grammar" />
+    <link rel="alternate" type="text/plain" href="/llms.txt" title="LLM index (llmstxt.org)" />
+    <link rel="alternate" type="text/plain" href="/llms-full.txt" title="LLM full bundle" />
+
+    <!-- Fonts -->
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link
       href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;600;700&family=Newsreader:ital,wght@0,300;0,400;0,600;1,300;1,400&display=swap"
       rel="stylesheet"
     />
+
+    <!-- JSON-LD: the language itself, as a SoftwareSourceCode / CreativeWork. -->
+    <script type="application/ld+json">
+    {
+      "@context": "https://schema.org",
+      "@graph": [
+        {
+          "@type": "Organization",
+          "@id": "https://kndl.artdaw.com/#org",
+          "name": "KNDL",
+          "url": "https://kndl.artdaw.com/",
+          "logo": "https://kndl.artdaw.com/kndl.png",
+          "sameAs": ["https://github.com/artdaw/KNDL"]
+        },
+        {
+          "@type": "WebSite",
+          "@id": "https://kndl.artdaw.com/#site",
+          "url": "https://kndl.artdaw.com/",
+          "name": "KNDL",
+          "description": "Graph-based knowledge representation language for AI agents.",
+          "inLanguage": "en",
+          "publisher": { "@id": "https://kndl.artdaw.com/#org" }
+        },
+        {
+          "@type": "SoftwareSourceCode",
+          "@id": "https://kndl.artdaw.com/#software",
+          "name": "KNDL — Knowledge Node Description Language",
+          "codeRepository": "https://github.com/artdaw/KNDL",
+          "programmingLanguage": "KNDL",
+          "url": "https://kndl.artdaw.com/",
+          "description": "A graph-based knowledge representation language for AI agents — typed nodes, confidence scores, temporal decay, cryptographic provenance, and native intent/process blocks.",
+          "license": "https://opensource.org/licenses/MIT",
+          "author": { "@id": "https://kndl.artdaw.com/#org" }
+        },
+        {
+          "@type": "TechArticle",
+          "@id": "https://kndl.artdaw.com/spec/full#article",
+          "headline": "KNDL Language Specification v1.0",
+          "description": "Complete reference for the Knowledge Node Description Language version 1.0.",
+          "url": "https://kndl.artdaw.com/spec/full",
+          "dateModified": "2026-04-23",
+          "inLanguage": "en",
+          "mainEntityOfPage": "https://kndl.artdaw.com/spec/full",
+          "publisher": { "@id": "https://kndl.artdaw.com/#org" }
+        }
+      ]
+    }
+    </script>
   </head>
   <body>
     <div id="root"></div>
+
+    <!-- No-script discovery fallback for crawlers that don't run JS. -->
+    <noscript>
+      <h1>KNDL — Knowledge Node Description Language</h1>
+      <p>
+        KNDL is a graph-based knowledge representation language for AI agents.
+        Every assertion carries a 0.0–1.0 confidence score, bitemporal
+        validity, provenance (URI or cryptographic signature), and typed
+        relationships. Intents and processes live alongside knowledge.
+      </p>
+      <p>Machine-readable resources:</p>
+      <ul>
+        <li><a href="/llms.txt">/llms.txt</a> — concise index for LLMs (<a href="https://llmstxt.org">llmstxt.org</a> format)</li>
+        <li><a href="/llms-full.txt">/llms-full.txt</a> — spec + EBNF + examples concatenated</li>
+        <li><a href="/spec/SPECIFICATION.md">/spec/SPECIFICATION.md</a> — canonical language reference</li>
+        <li><a href="/spec/kndl.ebnf">/spec/kndl.ebnf</a> — authoritative grammar</li>
+        <li><a href="/examples/index.md">/examples/</a> — curated .kndl snippets</li>
+        <li><a href="/sitemap.xml">/sitemap.xml</a> — full URL index</li>
+      </ul>
+      <p>Human-facing pages:
+        <a href="/spec">Spec overview</a> ·
+        <a href="/spec/full">Full spec</a> ·
+        <a href="/workflow">Agent workflow</a> ·
+        <a href="/mcp">MCP server</a> ·
+        <a href="/explorer">Graph explorer</a>.
+      </p>
+    </noscript>
+
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>
diff --git a/website/package.json b/website/package.json
@@ -5,7 +5,8 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "tsc -b && vite build",
+    "build": "tsc -b && vite build && node scripts/prerender.mjs",
+    "prerender": "node scripts/prerender.mjs",
     "preview": "vite preview",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -21,6 +22,7 @@
     "@testing-library/jest-dom": "^6.4.6",
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.5.2",
+    "@types/node": "^25.6.0",
     "@types/react": "19.2.14",
     "@types/react-dom": "19.2.3",
     "@vitejs/plugin-react": "6.0.1",

diff --git a/website/pnpm-lock.yaml b/website/pnpm-lock.yaml
diff --git a/website/public/.nojekyll b/website/public/.nojekyll
diff --git a/website/public/.well-known/security.txt b/website/public/.well-known/security.txt
@@ -0,0 +1,7 @@
+# Security contact for the KNDL project.
+# See https://securitytxt.org/ for the format.
+
+Contact: mailto:me@artdaw.com
+Expires: 2027-04-24T00:00:00Z
+Preferred-Languages: en
+Canonical: https://kndl.artdaw.com/.well-known/security.txt
diff --git a/website/public/404.html b/website/public/404.html
@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="robots" content="noindex,follow" />
+    <title>KNDL — redirecting…</title>
+    <script>
+      // GitHub Pages SPA fallback. The direct URL (e.g. /spec/full) served
+      // this 404.html. Stash the intended path so main.tsx can restore it
+      // after the root index.html boots the router.
+      (function () {
+        var path = window.location.pathname + window.location.search + window.location.hash;
+        try {
+          sessionStorage.setItem("kndl:redirect", path);
+        } catch (_) {}
+        window.location.replace("/");
+      })();
+    </script>
+    <link rel="canonical" href="https://kndl.artdaw.com/" />
+  </head>
+  <body>
+    <p>
+      You were headed somewhere specific. If you are not redirected automatically, go to
+      <a href="https://kndl.artdaw.com/">kndl.artdaw.com</a>.
+    </p>
+    <p>
+      Agents looking for machine-readable content:
+      <a href="https://kndl.artdaw.com/llms.txt">/llms.txt</a> ·
+      <a href="https://kndl.artdaw.com/spec/SPECIFICATION.md">/spec/SPECIFICATION.md</a> ·
+      <a href="https://kndl.artdaw.com/spec/kndl.ebnf">/spec/kndl.ebnf</a>.
+    </p>
+  </body>
+</html>