From d6ec60d61b1136abd2b5992bfcaaf2548f98ee85 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Sun, 16 Aug 2026 04:45:22 +0000
Subject: [PATCH] feat(www): emit real HTML pages for catalog and footer routes

Homepage catalog and footer links pointed at SPA-only paths. The build
now writes index.html for Documents, Packages, Spec, Install, First
program, Book, and the rest of the docs tree, each with that page's
title and body.

Fixes #14

Co-authored-by: Christoffer Hallas <github@christofferhallas.com>
---
 www/README.md                      |   7 +-
 www/SITE.md                        |  17 +-
 www/index.html                     |   1 +
 www/package.json                   |   2 +-
 www/scripts/verify-docs-pages.mjs  |  69 ++++++--
 www/scripts/verify-prose.mjs       |  19 ++-
 www/scripts/verify-static-dist.mjs |  79 +++++++++
 www/scripts/verify-try.mjs         |   2 +-
 www/src/docs/install-content.ts    | 220 ++++++++++++++++++++++++
 www/src/docs/site.ts               |  79 +++++++++
 www/src/docs/static-html.ts        | 168 ++++++++++++++++++
 www/src/install.tsx                | 262 ++++++++++-------------------
 www/src/router.tsx                 |  52 +-----
 www/src/try.tsx                    |  10 +-
 www/vite.config.ts                 |  35 +++-
 15 files changed, 771 insertions(+), 251 deletions(-)
 create mode 100644 www/scripts/verify-static-dist.mjs
 create mode 100644 www/src/docs/install-content.ts
 create mode 100644 www/src/docs/static-html.ts

diff --git a/www/README.md b/www/README.md
index 5e9d6a27..51903dff 100644
--- a/www/README.md
+++ b/www/README.md
@@ -44,8 +44,11 @@ Same layout as the previous `xo.run` site:
 bindings when the frontend or `std/**/*.echo` changes so Pages can ship the
 playground without a Rust toolchain.
 
-SPA deep links use the same `public/404.html` → `/?/path` bounce and
-`index.html` restore script as before. Custom domain: `public/CNAME` → `xo.run`.
+Content routes (Documents, Packages, Spec, Install, First program, Book, and
+the rest of the docs tree) are written as `dist/<path>/index.html` so those
+URLs are real pages. Unknown paths still use the `public/404.html` → `/?/path`
+bounce and `index.html` restore script. Custom domain: `public/CNAME` →
+`xo.run`. Wasm bindings stay in `public/echo-wasm/`.
 
 ## Search
 
diff --git a/www/SITE.md b/www/SITE.md
index f1176ddd..6342d1c5 100644
--- a/www/SITE.md
+++ b/www/SITE.md
@@ -136,6 +136,7 @@ maturity.
 ## Primary nav
 
 The logo is the only Home control. Book stays at `/book` and in the footer.
+Catalog, footer, and nav destinations are real HTML files at those paths.
 
 | Item              | Path        | Notes                                         |
 | ----------------- | ----------- | --------------------------------------------- |
@@ -161,6 +162,10 @@ The home page is a language-docs front door. Copy and links live in
 3. First-class links: Documents (`/docs`), Packages (`/docs/std`), Spec (`/e26`)
 4. Footer
 
+Each of those links, plus Install, First program, Book, and Try, is a real
+page (`path/index.html`) with that page title and body. A destination
+without a document is removed from the catalog or footer.
+
 Homepage trust stays factual. Rust, LLVM, the public edition, and the
 machine-checked suite are implementation facts.
 
@@ -169,7 +174,7 @@ machine-checked suite are implementation facts.
 `/docs` is a short catalog. Groups: Start (install, first program, project),
 Language (the Echo 2026 form pages), Packages (std + API index), Spec
 (Echo 2026 + Language Spec). Each entry has a title, one-line description,
-and a working path.
+and a working path that the build writes as HTML.
 
 ## Echo 2026 section
 
@@ -183,6 +188,16 @@ and a working path.
 
 Cross-links: Reference ↔ Spec ↔ suite pages keep the triangle explicit.
 
+## Static pages
+
+`npm run build` writes `index.html` for every content route: the homepage,
+`/install`, `/try`, and each page in `docsPages` (Documents, Packages, Spec,
+Book, First program, and the rest of the Reference / std / suite pages).
+Each file keeps the SPA shell and a noscript body from the same modules the
+React app renders. Unknown paths still use the `404.html` bounce.
+
+Wasm bindings stay in `www/public/echo-wasm/`.
+
 ## Playground
 
 `/try` runs the shared compiler frontend in WebAssembly (`just wasm`). It
diff --git a/www/index.html b/www/index.html
index 95d8716e..be058abb 100644
--- a/www/index.html
+++ b/www/index.html
@@ -4,6 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Echo Programming Language</title>
+    <meta name="description" content="Echo is a compiled language." />
     <script>
       (function () {
         var redirect = window.location.search;
diff --git a/www/package.json b/www/package.json
index df8a39ae..1bde3d8f 100644
--- a/www/package.json
+++ b/www/package.json
@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "npm run sync:tree-sitter && tsc -b && vite build",
+    "build": "npm run sync:tree-sitter && tsc -b && vite build && node scripts/verify-static-dist.mjs",
     "build:semantic": "DOCS_EMBEDDINGS=true npm run build",
     "format": "oxfmt --check .",
     "lint": "oxlint . --ignore-pattern public/echo-wasm",
diff --git a/www/scripts/verify-docs-pages.mjs b/www/scripts/verify-docs-pages.mjs
index bc070964..d62e77ca 100644
--- a/www/scripts/verify-docs-pages.mjs
+++ b/www/scripts/verify-docs-pages.mjs
@@ -5,6 +5,7 @@
  * - Documents hub catalog groups
  * - every language-feature catalog entry is a real page with a summary
  *   and at least one Echo code block
+ * - catalog, footer, and nav destinations have static HTML snapshots
  *
  * Loads src/docs/site.ts, src/docs/content.ts, and src/lib/current-release.ts
  * through Vite SSR. Also checks that /install, README, and docs/install.md
@@ -36,9 +37,12 @@ try {
     languageFeatureEntries,
     primaryNav,
     primaryNavItemIsActive,
+    publicChromePaths,
     renderStaticHomeAndHub,
   } = site;
   const { docsPageByPath } = content;
+  const staticHtml = await server.ssrLoadModule("/src/docs/static-html.ts");
+  const { distFileForPath, staticPageByPath } = staticHtml;
 
   const failures = [];
 
@@ -160,22 +164,27 @@ try {
 
   const repoRoot = path.resolve(root, "..");
   const installPage = readFileSync(path.join(root, "src/install.tsx"), "utf8");
+  const installContent = readFileSync(path.join(root, "src/docs/install-content.ts"), "utf8");
+  const installSources = `${installPage}\n${installContent}`;
   const readme = readFileSync(path.join(repoRoot, "README.md"), "utf8");
   const installDoc = readFileSync(path.join(repoRoot, "docs/install.md"), "utf8");
   const installSh = readFileSync(path.join(repoRoot, "scripts/install.sh"), "utf8");
   if (
-    !installPage.includes("./lib/current-release") ||
-    !installPage.includes("currentPrereleaseTag")
+    !installSources.includes("current-release") ||
+    !installSources.includes("currentPrereleaseTag")
   ) {
-    fail("src/install.tsx must render the current prerelease from current-release.ts");
+    fail("install page must render the current prerelease from current-release.ts");
   }
-  if (!installPage.includes("from-release") || !installPage.includes("currentPrereleaseTag")) {
+  if (
+    !installSources.includes("from-release") ||
+    !installSources.includes("currentPrereleaseTag")
+  ) {
     fail("install page must show from-release and how to pin the current tag");
   }
-  if (/windows-x86_64/.test(installPage)) {
-    fail("src/install.tsx must not claim a Windows tarball");
+  if (/windows-x86_64/.test(installSources)) {
+    fail("install page must not claim a Windows tarball");
   }
-  if (!/prerelease/i.test(installPage) || !/prerelease/i.test(readme)) {
+  if (!/prerelease/i.test(installSources) || !/prerelease/i.test(readme)) {
     fail("install page and README must say published builds are prereleases");
   }
   for (const [label, text] of [
@@ -196,11 +205,11 @@ try {
       fail(`${label} must not present /releases/latest as working`);
     }
   }
-  if (/latest GitHub release/i.test(installPage)) {
-    fail("src/install.tsx must not present a GitHub latest release");
+  if (/latest GitHub release/i.test(installSources)) {
+    fail("install page must not present a GitHub latest release");
   }
-  if (/releases\/latest/.test(installPage) && !/404/.test(installPage)) {
-    fail("src/install.tsx must not present /releases/latest as working");
+  if (/releases\/latest/.test(installSources) && !/404/.test(installSources)) {
+    fail("install page must not present /releases/latest as working");
   }
   if (!installSh.includes("releases?per_page=")) {
     fail("install.sh from-release must list published releases, including prereleases");
@@ -224,6 +233,43 @@ try {
     }
   }
 
+  const pages = staticPageByPath();
+  const requiredChrome = [
+    ["/docs", "Documents"],
+    ["/docs/std", "Standard library"],
+    ["/e26", "Echo 2026"],
+    ["/install", "Install Echo"],
+    ["/docs/first-program", "First program"],
+    ["/book", "Introduction"],
+  ];
+  for (const [path, heading] of requiredChrome) {
+    const page = pages.get(path);
+    if (!page) {
+      fail(`${path}: missing static page for catalog/footer link`);
+      continue;
+    }
+    if (!page.body.includes(`<h1>${heading}</h1>`)) {
+      fail(`${path}: static page must include <h1>${heading}</h1>`);
+    }
+    if (!page.title.trim() || !page.description.trim()) {
+      fail(`${path}: static page needs a title and description`);
+    }
+    if (distFileForPath(path) !== `${path.slice(1)}/index.html`) {
+      fail(`${path}: expected dist file ${path.slice(1)}/index.html`);
+    }
+  }
+
+  for (const path of publicChromePaths()) {
+    const page = pages.get(path);
+    if (!page) {
+      fail(`${path}: catalog/nav/footer link has no static page`);
+      continue;
+    }
+    if (!page.body.includes("<h1>")) {
+      fail(`${path}: static page is missing an h1`);
+    }
+  }
+
   if (failures.length) {
     console.error(JSON.stringify({ ok: false, failures }, null, 2));
     process.exitCode = 1;
@@ -236,6 +282,7 @@ try {
           nav: primaryNav.map((item) => item.label),
           languagePages: languageFeatureEntries.map((entry) => entry.to),
           hubGroups: docsHubCatalog.map((group) => group.title),
+          chromePaths: publicChromePaths(),
         },
         null,
         2,
diff --git a/www/scripts/verify-prose.mjs b/www/scripts/verify-prose.mjs
index 591322b0..716077b7 100644
--- a/www/scripts/verify-prose.mjs
+++ b/www/scripts/verify-prose.mjs
@@ -128,7 +128,9 @@ try {
 
   const { docsPages, docsPageByPath } = content;
   const { stdModules } = ref;
-  const { homePage, docsHubCatalog } = site;
+  const { homePage, docsHubCatalog, tryPage } = site;
+  const install = await server.ssrLoadModule("/src/docs/install-content.ts");
+  const { installPage, inlineText } = install;
 
   const failures = [];
   const prose = [];
@@ -150,6 +152,13 @@ try {
 
   prose.push({ where: "home definition", text: homePage.definition });
   prose.push({ where: "home lead", text: homePage.lead });
+  prose.push({ where: "try lead", text: tryPage.lead });
+  prose.push({ where: "install lead", text: inlineText(installPage.lead) });
+  for (const section of installPage.sections) {
+    for (const paragraph of section.paragraphs) {
+      prose.push({ where: `install ${section.title}`, text: inlineText(paragraph) });
+    }
+  }
   for (const link of homePage.links) {
     prose.push({ where: `home link ${link.title}`, text: link.description });
   }
@@ -189,7 +198,13 @@ try {
   }
 
   // High-visibility TSX chrome: em dashes + slogan templates inside string literals
-  const tsxFiles = ["src/app.tsx", "src/install.tsx", "src/router.tsx", "src/docs/site.ts"];
+  const tsxFiles = [
+    "src/app.tsx",
+    "src/install.tsx",
+    "src/router.tsx",
+    "src/docs/site.ts",
+    "src/docs/install-content.ts",
+  ];
   const stringLitRe = /"(?:\\.|[^"\\])*"|`(?:\\.|[^`\\])*`/g;
   for (const rel of tsxFiles) {
     const src = readFileSync(path.join(root, rel), "utf8");
diff --git a/www/scripts/verify-static-dist.mjs b/www/scripts/verify-static-dist.mjs
new file mode 100644
index 00000000..de1dfbe5
--- /dev/null
+++ b/www/scripts/verify-static-dist.mjs
@@ -0,0 +1,79 @@
+/**
+ * After vite build, every catalog / footer / nav destination must exist as a
+ * real HTML file with that page's title and body. SPA-only copies of index.html
+ * are not enough.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createServer } from "vite";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const dist = path.join(root, "dist");
+
+const server = await createServer({
+  root,
+  logLevel: "error",
+  server: { middlewareMode: true },
+  appType: "custom",
+});
+
+try {
+  const site = await server.ssrLoadModule("/src/docs/site.ts");
+  const staticHtml = await server.ssrLoadModule("/src/docs/static-html.ts");
+  const { publicChromePaths } = site;
+  const { distFileForPath, staticPageByPath } = staticHtml;
+  const pages = staticPageByPath();
+  const failures = [];
+
+  function fail(message) {
+    failures.push(message);
+  }
+
+  if (!existsSync(path.join(dist, "index.html"))) {
+    fail("dist/index.html is missing; run this script after vite build");
+  }
+
+  for (const route of publicChromePaths()) {
+    const page = pages.get(route);
+    if (!page) {
+      fail(`${route}: renderer has no static page`);
+      continue;
+    }
+
+    const file = path.join(dist, distFileForPath(route));
+    if (!existsSync(file)) {
+      fail(`${route}: missing ${path.relative(root, file)}`);
+      continue;
+    }
+
+    const html = readFileSync(file, "utf8");
+    if (!html.includes(`<title>${page.title}</title>`)) {
+      fail(`${route}: ${path.relative(root, file)} is missing title ${page.title}`);
+    }
+    if (!html.includes(page.body)) {
+      fail(`${route}: ${path.relative(root, file)} is missing the page body`);
+    }
+    if (route !== "/" && html.includes(`<h1>${site.homePage.definition}</h1>`)) {
+      fail(`${route}: ${path.relative(root, file)} still has the homepage snapshot`);
+    }
+  }
+
+  if (failures.length) {
+    console.error(JSON.stringify({ ok: false, failures }, null, 2));
+    process.exitCode = 1;
+  } else {
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          files: publicChromePaths().map((route) => distFileForPath(route)),
+        },
+        null,
+        2,
+      ),
+    );
+  }
+} finally {
+  await server.close();
+}
diff --git a/www/scripts/verify-try.mjs b/www/scripts/verify-try.mjs
index dd5ecb84..05531432 100644
--- a/www/scripts/verify-try.mjs
+++ b/www/scripts/verify-try.mjs
@@ -57,7 +57,7 @@ try {
     }
   }
 
-  const trySource = readFileSync(trySourcePath, "utf8");
+  const trySource = `${readFileSync(trySourcePath, "utf8")}\n${site.tryPage.lead}`;
   if (/\bxo run\b/.test(trySource)) {
     fail("/try must not describe itself as xo run");
   }
diff --git a/www/src/docs/install-content.ts b/www/src/docs/install-content.ts
new file mode 100644
index 00000000..449018c9
--- /dev/null
+++ b/www/src/docs/install-content.ts
@@ -0,0 +1,220 @@
+/**
+ * Install page copy shared by the React page and the static HTML snapshot.
+ * Prerelease tag and archives come from current-release.ts.
+ */
+
+import {
+  currentPrereleaseAssets,
+  currentPrereleaseTag,
+  currentPrereleaseUrl,
+  releasesIndexUrl,
+} from "../lib/current-release";
+
+export type CodePart = { code: string };
+export type LinkPart = { href: string; label: string };
+export type InlinePart = string | CodePart | LinkPart;
+
+export type InstallSection = {
+  title: string;
+  paragraphs: InlinePart[][];
+  assets?: boolean;
+  code?: string;
+};
+
+export type InstallNextStep = {
+  title: string;
+  text: string;
+  to: string;
+  label: string;
+  variant?: "primary" | "secondary";
+};
+
+export const PREBUILT_INSTALL = `# Newest published prerelease for this machine (linux-x86_64 / macos-arm64)
+curl -fsSL https://raw.githubusercontent.com/modoterra/echo/main/scripts/install.sh \\
+  | bash -s -- from-release
+
+# Pin this tag
+# … | bash -s -- from-release ${currentPrereleaseTag}
+
+xo --help
+xo doctor 2>/dev/null || true`;
+
+export const CLONE_BUILD = `git clone https://github.com/modoterra/echo.git
+cd echo
+cargo build -p xo
+./target/debug/xo --help`;
+
+export const USER_INSTALL = `# From the checkout: release build + XDG install + ~/.local/bin/xo
+./scripts/install.sh
+./scripts/install.sh doctor
+
+# Newest published prerelease, or pin a tag
+./scripts/install.sh from-release
+./scripts/install.sh from-release ${currentPrereleaseTag}
+
+# Upgrade (keeps prior toolchain dirs)
+./scripts/install.sh upgrade
+
+# Uninstall toolchain (add --purge to also clear $XO_HOME packages)
+./scripts/uninstall.sh`;
+
+export const FIRST_RUN = `# After from-release / install.sh, xo is on PATH
+xo run examples/misc/hello.echo
+
+# Or from a debug build in a checkout
+./target/debug/xo run examples/misc/hello.echo
+./target/debug/xo run examples/misc/sum_list.echo`;
+
+export function isLinkPart(part: object | string): part is LinkPart {
+  return typeof part === "object" && "href" in part;
+}
+
+export function isCodePart(part: object | string): part is CodePart {
+  return typeof part === "object" && "code" in part && !("href" in part);
+}
+
+function archiveParts(): InlinePart[] {
+  const parts: InlinePart[] = [];
+  for (const [index, asset] of currentPrereleaseAssets.entries()) {
+    if (index > 0) {
+      parts.push(" and ");
+    }
+    parts.push({ code: asset.archive });
+  }
+  return parts;
+}
+
+export const installPage = {
+  title: "Install Echo",
+  lead: [
+    "The public CLI is ",
+    { code: "xo" },
+    ". Published builds are prereleases. The current tag is ",
+    { href: currentPrereleaseUrl, label: currentPrereleaseTag },
+    ". Take a prebuilt when you only need to run programs. Build from source when you edit the compiler.",
+  ] satisfies InlinePart[],
+  sections: [
+    {
+      title: "Prebuilt (recommended)",
+      paragraphs: [
+        [
+          { code: currentPrereleaseTag },
+          " ships ",
+          ...archiveParts(),
+          ". The script downloads ",
+          { code: "xo" },
+          ", ",
+          { code: "libecho_runtime.a" },
+          ", and ",
+          { code: "std/" },
+          " for that host, then links ",
+          { code: "~/.local/bin/xo" },
+          ".",
+        ],
+        [
+          { code: "from-release" },
+          " with no tag installs the newest published prerelease. Pass a tag to pin. GitHub ",
+          { code: "/releases/latest" },
+          " only resolves a non-prerelease and 404s today. See the ",
+          { href: releasesIndexUrl, label: "releases list" },
+          ".",
+        ],
+      ],
+      assets: true,
+      code: PREBUILT_INSTALL,
+    },
+    {
+      title: "Requirements",
+      paragraphs: [
+        [
+          "To run programs you need ",
+          { code: "clang" },
+          " on ",
+          { code: "PATH" },
+          " for AOT link. Building this repository also expects Rust (edition 2024), ",
+          { code: "mold" },
+          ", and ",
+          { code: "sccache" },
+          ". The workspace Cargo config selects those tools directly. Compiling the toolchain needs LLVM as well.",
+        ],
+      ],
+    },
+    {
+      title: "Build from source",
+      paragraphs: [
+        ["Clone the repository and build the CLI package when you develop Echo itself."],
+      ],
+      code: CLONE_BUILD,
+    },
+    {
+      title: "Install to PATH (XDG)",
+      paragraphs: [
+        [
+          "From a checkout, install co-located ",
+          { code: "xo" },
+          " and ",
+          { code: "std" },
+          " under XDG data, link ",
+          { code: "~/.local/bin/xo" },
+          ", and create package cache and state dirs. Upgrade flips ",
+          { code: "current" },
+          " without wiping packages. The checkout file ",
+          { code: "docs/install.md" },
+          " records install layout details.",
+        ],
+      ],
+      code: USER_INSTALL,
+    },
+    {
+      title: "Run an example",
+      paragraphs: [
+        [
+          "Point ",
+          { code: "xo" },
+          " at a sample program from a checkout, or at any path after install.",
+        ],
+      ],
+      code: FIRST_RUN,
+    },
+  ] satisfies InstallSection[],
+  nextTitle: "From here",
+  nextSteps: [
+    {
+      title: "First program",
+      text: "the minimal shape and the same commands you just ran.",
+      to: "/docs/first-program",
+      label: "First program",
+    },
+    {
+      title: "Reference",
+      text: "form sheets for leaders, Result, structs, and the rest of Echo 2026.",
+      to: "/docs",
+      label: "Reference",
+      variant: "secondary",
+    },
+    {
+      title: "Language Spec",
+      text: "edition TOC that maps Reference pages to the suite.",
+      to: "/e26/spec",
+      label: "Language Spec",
+      variant: "secondary",
+    },
+  ] satisfies InstallNextStep[],
+  projectLead: "Longer project shape and workflow notes live under ",
+  projectLabel: "Project setup",
+  projectTo: "/docs/project",
+};
+
+export function inlineText(parts: readonly InlinePart[]): string {
+  return parts
+    .map((part) => {
+      if (typeof part === "string") {
+        return part;
+      }
+      if (isLinkPart(part)) {
+        return part.label;
+      }
+      return part.code;
+    })
+    .join("");
+}
diff --git a/www/src/docs/site.ts b/www/src/docs/site.ts
index 3bc77591..9858ecf1 100644
--- a/www/src/docs/site.ts
+++ b/www/src/docs/site.ts
@@ -38,6 +38,85 @@ export const primaryNav: SiteNavItem[] = [
 
 export const installCta: SiteNavItem = { label: "Install", to: "/install" };
 
+export type FooterLink = {
+  label: string;
+  href: string;
+  disabled?: boolean;
+};
+
+export type FooterLinkGroup = {
+  title: string;
+  links: FooterLink[];
+};
+
+export const footerLinkGroups: FooterLinkGroup[] = [
+  {
+    title: "Learn",
+    links: [
+      { label: "Install", href: "/install" },
+      { label: "Try Echo", href: "/try" },
+      { label: "First program", href: "/docs/first-program" },
+      { label: "Documents", href: "/docs" },
+      { label: "Book", href: "/book" },
+      { label: "Echo 2026", href: "/e26" },
+    ],
+  },
+  {
+    title: "Community",
+    links: [
+      {
+        label: "GitHub",
+        href: "https://github.com/modoterra/echo",
+      },
+      { label: "Discord", href: "#", disabled: true },
+    ],
+  },
+  {
+    title: "About",
+    links: [
+      {
+        label: "Modoterra",
+        href: "https://modoterra.xyz",
+      },
+    ],
+  },
+];
+
+export const tryPage = {
+  title: "Try Echo",
+  lead: "This page checks with the shared compiler frontend. A playground run then executes the checked program and captures io.print. Filesystem, net, process, and tasks stay unavailable here. Install xo to compile through LLVM.",
+};
+
+/**
+ * Internal homepage, nav, Documents hub, and footer destinations.
+ * Each path must ship as a real HTML file, or the link must come down.
+ */
+export function publicChromePaths(): string[] {
+  const paths = new Set<string>();
+
+  for (const item of primaryNav) {
+    paths.add(item.to);
+  }
+  paths.add(installCta.to);
+  for (const link of homePage.links) {
+    paths.add(link.to);
+  }
+  for (const group of docsHubCatalog) {
+    for (const entry of group.entries) {
+      paths.add(entry.to);
+    }
+  }
+  for (const group of footerLinkGroups) {
+    for (const link of group.links) {
+      if (!link.disabled && link.href.startsWith("/")) {
+        paths.add(link.href);
+      }
+    }
+  }
+
+  return [...paths].sort();
+}
+
 /**
  * Documents stays active on language and guide pages. Packages owns /docs/std.
  */
diff --git a/www/src/docs/static-html.ts b/www/src/docs/static-html.ts
new file mode 100644
index 00000000..f8cea7ed
--- /dev/null
+++ b/www/src/docs/static-html.ts
@@ -0,0 +1,168 @@
+/**
+ * Static HTML snapshots for public routes. The build writes one index.html
+ * per path so catalog and footer links are real documents, not SPA-only hops.
+ */
+import { docsPages, type DocsBlock, type DocsPage, type DocsTextPart } from "./content";
+import { installPage, inlineText, isLinkPart, type InlinePart } from "./install-content";
+import { currentPrereleaseAssets } from "../lib/current-release";
+import { homePage, renderStaticHomeAndHub, tryPage } from "./site";
+
+export type StaticPage = {
+  path: string;
+  title: string;
+  description: string;
+  body: string;
+};
+
+export function escapeHtml(text: string): string {
+  return text
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+function renderInline(parts: readonly DocsTextPart[] | readonly InlinePart[]): string {
+  return parts
+    .map((part) => {
+      if (typeof part === "string") {
+        return escapeHtml(part);
+      }
+      if (isLinkPart(part)) {
+        return `<a href="${escapeHtml(part.href)}">${escapeHtml(part.label)}</a>`;
+      }
+      return `<code>${escapeHtml(part.code)}</code>`;
+    })
+    .join("");
+}
+
+function renderBlock(block: DocsBlock): string {
+  if (block.kind === "paragraph") {
+    return `<p>${renderInline(block.text)}</p>`;
+  }
+  if (block.kind === "catalog") {
+    const items = block.entries
+      .map(
+        (entry) =>
+          `<li><a href="${escapeHtml(entry.to)}">${escapeHtml(entry.title)}</a> ${escapeHtml(entry.description)}</li>`,
+      )
+      .join("");
+    return `<ul>${items}</ul>`;
+  }
+  return `<pre>${escapeHtml(block.code)}</pre>`;
+}
+
+export function renderStaticDocsPage(page: DocsPage): string {
+  const sections = page.sections
+    .map((section) => {
+      const blocks = section.blocks.map(renderBlock).join("");
+      return `<section><h2>${escapeHtml(section.title)}</h2>${blocks}</section>`;
+    })
+    .join("");
+
+  return [
+    `<main>`,
+    `<p>${escapeHtml(page.category)}</p>`,
+    `<h1>${escapeHtml(page.title)}</h1>`,
+    `<p>${escapeHtml(page.summary)}</p>`,
+    sections,
+    `</main>`,
+  ].join("");
+}
+
+export function renderStaticInstall(): string {
+  const sections = installPage.sections
+    .map((section) => {
+      const paragraphs = section.paragraphs.map((text) => `<p>${renderInline(text)}</p>`).join("");
+      const assets = section.assets
+        ? `<ul>${currentPrereleaseAssets
+            .map(
+              (asset) =>
+                `<li><code>${escapeHtml(asset.archive)}</code> · ${escapeHtml(asset.host)}</li>`,
+            )
+            .join("")}</ul>`
+        : "";
+      const code = section.code ? `<pre>${escapeHtml(section.code)}</pre>` : "";
+      return `<section><h2>${escapeHtml(section.title)}</h2>${paragraphs}${assets}${code}</section>`;
+    })
+    .join("");
+  const next = installPage.nextSteps
+    .map(
+      (step, index) =>
+        `<li><a href="${escapeHtml(step.to)}">${index + 1}. ${escapeHtml(step.title)}</a>: ${escapeHtml(step.text)}</li>`,
+    )
+    .join("");
+
+  return [
+    `<main>`,
+    `<h1>${escapeHtml(installPage.title)}</h1>`,
+    `<p>${renderInline(installPage.lead)}</p>`,
+    sections,
+    `<section>`,
+    `<h2>${escapeHtml(installPage.nextTitle)}</h2>`,
+    `<ol>${next}</ol>`,
+    `<p>${escapeHtml(installPage.projectLead)}<a href="${escapeHtml(installPage.projectTo)}">${escapeHtml(installPage.projectLabel)}</a>.</p>`,
+    `</section>`,
+    `</main>`,
+  ].join("");
+}
+
+export function renderStaticTry(): string {
+  return [
+    `<main>`,
+    `<h1>${escapeHtml(tryPage.title)}</h1>`,
+    `<p>${escapeHtml(tryPage.lead)}</p>`,
+    `<p>The playground needs JavaScript. Install xo to compile through LLVM.</p>`,
+    `<p><a href="/install">Install xo</a> <a href="/docs/first-program">First program</a></p>`,
+    `</main>`,
+  ].join("");
+}
+
+function documentTitle(pageTitle: string): string {
+  return `${pageTitle} · Echo`;
+}
+
+export function staticPages(): StaticPage[] {
+  const pages: StaticPage[] = [
+    {
+      path: "/",
+      title: "Echo Programming Language",
+      description: homePage.lead,
+      body: renderStaticHomeAndHub(),
+    },
+    {
+      path: "/install",
+      title: documentTitle(installPage.title),
+      description: inlineText(installPage.lead),
+      body: renderStaticInstall(),
+    },
+    {
+      path: "/try",
+      title: documentTitle(tryPage.title),
+      description: tryPage.lead,
+      body: renderStaticTry(),
+    },
+  ];
+
+  for (const page of docsPages) {
+    pages.push({
+      path: page.path,
+      title: documentTitle(page.title),
+      description: page.summary,
+      body: renderStaticDocsPage(page),
+    });
+  }
+
+  return pages;
+}
+
+export function staticPageByPath(): Map<string, StaticPage> {
+  return new Map(staticPages().map((page) => [page.path, page]));
+}
+
+export function distFileForPath(path: string): string {
+  if (path === "/") {
+    return "index.html";
+  }
+  return `${path.replace(/^\//, "")}/index.html`;
+}
diff --git a/www/src/install.tsx b/www/src/install.tsx
index 5e18559b..b980d308 100644
--- a/www/src/install.tsx
+++ b/www/src/install.tsx
@@ -1,48 +1,35 @@
 import { Link } from "@tanstack/react-router";
 import { CtaLink } from "./components/cta-link";
 import { InstallSnippet } from "./components/install-snippet";
-import {
-  currentPrereleaseTag,
-  currentPrereleaseAssets,
-  currentPrereleaseUrl,
-  releasesIndexUrl,
-} from "./lib/current-release";
-
-const PREBUILT_INSTALL = `# Newest published prerelease for this machine (linux-x86_64 / macos-arm64)
-curl -fsSL https://raw.githubusercontent.com/modoterra/echo/main/scripts/install.sh \\
-  | bash -s -- from-release
-
-# Pin this tag
-# … | bash -s -- from-release ${currentPrereleaseTag}
-
-xo --help
-xo doctor 2>/dev/null || true`;
-
-const CLONE_BUILD = `git clone https://github.com/modoterra/echo.git
-cd echo
-cargo build -p xo
-./target/debug/xo --help`;
-
-const USER_INSTALL = `# From the checkout: release build + XDG install + ~/.local/bin/xo
-./scripts/install.sh
-./scripts/install.sh doctor
-
-# Newest published prerelease, or pin a tag
-./scripts/install.sh from-release
-./scripts/install.sh from-release ${currentPrereleaseTag}
-
-# Upgrade (keeps prior toolchain dirs)
-./scripts/install.sh upgrade
-
-# Uninstall toolchain (add --purge to also clear $XO_HOME packages)
-./scripts/uninstall.sh`;
-
-const FIRST_RUN = `# After from-release / install.sh, xo is on PATH
-xo run examples/misc/hello.echo
-
-# Or from a debug build in a checkout
-./target/debug/xo run examples/misc/hello.echo
-./target/debug/xo run examples/misc/sum_list.echo`;
+import { installPage, isCodePart, isLinkPart, type InlinePart } from "./docs/install-content";
+import { currentPrereleaseAssets, currentPrereleaseTag } from "./lib/current-release";
+
+function renderInline(parts: readonly InlinePart[]) {
+  return parts.map((part, index) => {
+    if (typeof part === "string") {
+      return <span key={index}>{part}</span>;
+    }
+    if (isLinkPart(part)) {
+      return (
+        <a
+          className="font-mono font-semibold text-slate-800 underline-offset-4 hover:underline"
+          href={part.href}
+          key={index}
+        >
+          {part.label}
+        </a>
+      );
+    }
+    if (isCodePart(part)) {
+      return (
+        <span key={index} className="font-mono font-semibold text-slate-800">
+          {part.code}
+        </span>
+      );
+    }
+    return null;
+  });
+}
 
 /**
  * Product install page: current prerelease assets + source build fallback.
@@ -52,161 +39,82 @@ export function InstallPage() {
     <main className="min-h-screen bg-white px-6 pb-24 pt-32 text-slate-950 sm:pt-36">
       <div className="mx-auto w-full max-w-3xl">
         <h1 className="text-3xl font-semibold tracking-normal text-slate-950 sm:text-4xl">
-          Install Echo
+          {installPage.title}
         </h1>
         <p className="mt-4 text-pretty text-lg leading-8 text-slate-600">
-          The public CLI is <span className="font-mono font-semibold text-slate-800">xo</span>.
-          Published builds are prereleases. The current tag is{" "}
-          <a
-            className="font-mono font-semibold text-slate-800 underline-offset-4 hover:underline"
-            href={currentPrereleaseUrl}
-          >
-            {currentPrereleaseTag}
-          </a>
-          . Take a prebuilt when you only need to run programs. Build from source when you edit the
-          compiler.
+          {renderInline(installPage.lead)}
         </p>
 
-        <section className="mt-14">
-          <h2 className="text-xl font-semibold tracking-normal text-slate-950 sm:text-2xl">
-            Prebuilt (recommended)
-          </h2>
-          <p className="mt-4 text-pretty text-base leading-7 text-slate-600 sm:text-lg sm:leading-8">
-            <span className="font-mono text-slate-800">{currentPrereleaseTag}</span> ships{" "}
-            {currentPrereleaseAssets.map((asset, index) => (
-              <span key={asset.archive}>
-                {index > 0 ? " and " : ""}
-                <span className="font-mono text-slate-800">{asset.archive}</span>
-              </span>
+        {installPage.sections.map((section) => (
+          <section className="mt-14" key={section.title}>
+            <h2 className="text-xl font-semibold tracking-normal text-slate-950 sm:text-2xl">
+              {section.title}
+            </h2>
+            {section.paragraphs.map((paragraph, index) => (
+              <p
+                className="mt-4 text-pretty text-base leading-7 text-slate-600 sm:text-lg sm:leading-8"
+                key={index}
+              >
+                {renderInline(paragraph)}
+              </p>
             ))}
-            . The script downloads <span className="font-mono text-slate-800">xo</span>,{" "}
-            <span className="font-mono text-slate-800">libecho_runtime.a</span>, and{" "}
-            <span className="font-mono text-slate-800">std/</span> for that host, then links{" "}
-            <span className="font-mono font-semibold text-slate-800">~/.local/bin/xo</span>.
-          </p>
-          <p className="mt-4 text-pretty text-base leading-7 text-slate-600 sm:text-lg sm:leading-8">
-            <span className="font-mono text-slate-800">from-release</span> with no tag installs the
-            newest published prerelease. Pass a tag to pin. GitHub{" "}
-            <span className="font-mono text-slate-800">/releases/latest</span> only resolves a
-            non-prerelease and 404s today. See the{" "}
-            <a
-              className="font-semibold text-slate-800 underline-offset-4 hover:underline"
-              href={releasesIndexUrl}
-            >
-              releases list
-            </a>
-            .
-          </p>
-          <ul className="mt-6 space-y-2 text-base leading-7 text-slate-600">
-            {currentPrereleaseAssets.map((asset) => (
-              <li key={asset.artifact}>
-                <span className="font-mono font-semibold text-slate-800">{asset.archive}</span>
-                {" · "}
-                {asset.host}
-              </li>
-            ))}
-          </ul>
-          <div className="mt-6">
-            <InstallSnippet code={PREBUILT_INSTALL} />
-          </div>
-        </section>
-
-        <section className="mt-14">
-          <h2 className="text-xl font-semibold tracking-normal text-slate-950 sm:text-2xl">
-            Requirements
-          </h2>
-          <p className="mt-4 text-pretty text-base leading-7 text-slate-600 sm:text-lg sm:leading-8">
-            To <span className="font-semibold text-slate-800">run</span> programs you need{" "}
-            <span className="font-mono font-semibold text-slate-800">clang</span> on{" "}
-            <span className="font-semibold text-slate-800">PATH</span> for AOT link. Building this
-            repository also expects Rust (edition 2024),{" "}
-            <span className="font-mono font-semibold text-slate-800">mold</span>, and{" "}
-            <span className="font-mono font-semibold text-slate-800">sccache</span>. The workspace
-            Cargo config selects those tools directly. Compiling the toolchain needs LLVM as well.
-          </p>
-        </section>
-
-        <section className="mt-14">
-          <h2 className="text-xl font-semibold tracking-normal text-slate-950 sm:text-2xl">
-            Build from source
-          </h2>
-          <p className="mt-4 text-pretty text-base leading-7 text-slate-600 sm:text-lg sm:leading-8">
-            Clone the repository and build the CLI package when you develop Echo itself.
-          </p>
-          <div className="mt-6">
-            <InstallSnippet code={CLONE_BUILD} />
-          </div>
-        </section>
+            {section.assets ? (
+              <ul className="mt-6 space-y-2 text-base leading-7 text-slate-600">
+                {currentPrereleaseAssets.map((asset) => (
+                  <li key={asset.artifact}>
+                    <span className="font-mono font-semibold text-slate-800">{asset.archive}</span>
+                    {" · "}
+                    {asset.host}
+                  </li>
+                ))}
+              </ul>
+            ) : null}
+            {section.code ? (
+              <div className="mt-6">
+                <InstallSnippet code={section.code} />
+              </div>
+            ) : null}
+          </section>
+        ))}
 
         <section className="mt-14">
           <h2 className="text-xl font-semibold tracking-normal text-slate-950 sm:text-2xl">
-            Install to PATH (XDG)
-          </h2>
-          <p className="mt-4 text-pretty text-base leading-7 text-slate-600 sm:text-lg sm:leading-8">
-            From a checkout, install co-located{" "}
-            <span className="font-mono font-semibold text-slate-800">xo</span> and{" "}
-            <span className="font-mono font-semibold text-slate-800">std</span> under XDG data, link{" "}
-            <span className="font-mono font-semibold text-slate-800">~/.local/bin/xo</span>, and
-            create package cache and state dirs. Upgrade flips{" "}
-            <span className="font-mono text-slate-800">current</span> without wiping packages. The
-            checkout file <span className="font-mono text-slate-800">docs/install.md</span> records
-            install layout details.
-          </p>
-          <div className="mt-6">
-            <InstallSnippet code={USER_INSTALL} />
-          </div>
-        </section>
-
-        <section className="mt-14">
-          <h2 className="text-xl font-semibold tracking-normal text-slate-950 sm:text-2xl">
-            Run an example
-          </h2>
-          <p className="mt-4 text-pretty text-base leading-7 text-slate-600 sm:text-lg sm:leading-8">
-            Point <span className="font-mono font-semibold text-slate-800">xo</span> at a sample
-            program from a checkout, or at any path after install.
-          </p>
-          <div className="mt-6">
-            <InstallSnippet code={FIRST_RUN} />
-          </div>
-        </section>
-
-        <section className="mt-14">
-          <h2 className="text-xl font-semibold tracking-normal text-slate-950 sm:text-2xl">
-            From here
+            {installPage.nextTitle}
           </h2>
           <ol className="mt-6 space-y-4 text-base leading-7 text-slate-600">
-            <li>
-              <span className="font-semibold text-slate-950">1. First program</span>: the minimal
-              shape and the same commands you just ran.
-            </li>
-            <li>
-              <span className="font-semibold text-slate-950">2. Reference</span>: form sheets for
-              leaders, Result, structs, and the rest of Echo 2026.
-            </li>
-            <li>
-              <span className="font-semibold text-slate-950">3. Language Spec</span>: edition TOC
-              that maps Reference pages to the suite.
-            </li>
+            {installPage.nextSteps.map((step, index) => (
+              <li key={step.to}>
+                <span className="font-semibold text-slate-950">
+                  {index + 1}. {step.title}
+                </span>
+                : {step.text}
+              </li>
+            ))}
           </ol>
           <div className="mt-8 flex flex-wrap gap-3">
-            <CtaLink to={"/docs/first-program"}>First program</CtaLink>
-            <CtaLink to={"/docs"} variant="secondary">
-              Reference
-            </CtaLink>
-            <CtaLink to={"/e26/spec"} variant="secondary">
-              Language Spec
-            </CtaLink>
+            {installPage.nextSteps.map((step) => (
+              <CtaLink
+                key={step.to}
+                to={step.to as "/"}
+                variant={step.variant === "secondary" ? "secondary" : undefined}
+              >
+                {step.label}
+              </CtaLink>
+            ))}
           </div>
           <p className="mt-8 text-sm leading-6 text-slate-500">
-            Longer project shape and workflow notes live under{" "}
+            {installPage.projectLead}
             <Link
               className="font-semibold text-slate-800 underline-offset-4 hover:underline"
-              to={"/docs/project" as "/"}
+              to={installPage.projectTo as "/"}
             >
-              Project setup
+              {installPage.projectLabel}
             </Link>
             .
           </p>
+          <p className="sr-only">
+            Current prerelease {currentPrereleaseTag}. Use from-release to install it.
+          </p>
         </section>
       </div>
     </main>
diff --git a/www/src/router.tsx b/www/src/router.tsx
index ccf9d454..af4517b5 100644
--- a/www/src/router.tsx
+++ b/www/src/router.tsx
@@ -38,51 +38,13 @@ import {
   type DocsPage,
   type DocsTextPart,
 } from "./docs/content";
-import { installCta, primaryNav, primaryNavItemIsActive, type SiteLink } from "./docs/site";
-
-type FooterLink = {
-  label: string;
-  href: string;
-  disabled?: boolean;
-};
-
-type FooterLinkGroup = {
-  title: string;
-  links: FooterLink[];
-};
-
-const footerLinkGroups: FooterLinkGroup[] = [
-  {
-    title: "Learn",
-    links: [
-      { label: "Install", href: "/install" },
-      { label: "Try Echo", href: "/try" },
-      { label: "First program", href: "/docs/first-program" },
-      { label: "Documents", href: "/docs" },
-      { label: "Book", href: "/book" },
-      { label: "Echo 2026", href: "/e26" },
-    ],
-  },
-  {
-    title: "Community",
-    links: [
-      {
-        label: "GitHub",
-        href: "https://github.com/modoterra/echo",
-      },
-      { label: "Discord", href: "#", disabled: true },
-    ],
-  },
-  {
-    title: "About",
-    links: [
-      {
-        label: "Modoterra",
-        href: "https://modoterra.xyz",
-      },
-    ],
-  },
-];
+import {
+  footerLinkGroups,
+  installCta,
+  primaryNav,
+  primaryNavItemIsActive,
+  type SiteLink,
+} from "./docs/site";
 
 type DocsShellProps = {
   category: string;
diff --git a/www/src/try.tsx b/www/src/try.tsx
index 1ba39fca..31f4d5a4 100644
--- a/www/src/try.tsx
+++ b/www/src/try.tsx
@@ -1,5 +1,6 @@
 import { useEffect, useMemo, useRef, useState } from "react";
 import { CtaLink } from "./components/cta-link";
+import { tryPage } from "./docs/site";
 import {
   EchoWasmMissingError,
   loadEchoCheck,
@@ -228,15 +229,10 @@ export function TryPage() {
           Playground
         </p>
         <h1 className="mt-4 text-3xl font-semibold tracking-normal text-slate-950 sm:text-4xl">
-          Try Echo
+          {tryPage.title}
         </h1>
         <p className="mt-4 max-w-3xl text-pretty text-lg leading-8 text-slate-600">
-          This page checks with the shared compiler frontend. A playground run then executes the
-          checked program and captures{" "}
-          <span className="font-mono font-semibold text-slate-800">io.print</span>. Filesystem, net,
-          process, and tasks stay unavailable here. Install{" "}
-          <span className="font-mono font-semibold text-slate-800">xo</span> to compile through
-          LLVM.
+          {tryPage.lead}
         </p>
         <div className="mt-6 flex flex-wrap gap-3">
           <CtaLink to="/install">Install xo</CtaLink>
diff --git a/www/vite.config.ts b/www/vite.config.ts
index 1954726c..0806831a 100644
--- a/www/vite.config.ts
+++ b/www/vite.config.ts
@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { copyFileSync, mkdirSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { defineConfig, type Plugin } from "vite";
 import react from "@vitejs/plugin-react";
@@ -11,6 +11,7 @@ import {
   type DocsSemanticAsset,
 } from "./src/docs/search";
 import { renderStaticHomeAndHub } from "./src/docs/site";
+import { distFileForPath, escapeHtml, staticPages, type StaticPage } from "./src/docs/static-html";
 
 const docsSearchIndexDevFileName = "indices/search.json";
 const docsSemanticIndexDevFileName = "indices/semantic.json";
@@ -214,6 +215,23 @@ function docsIndexFileName(name: "search" | "semantic", checksum: string) {
   return `indices/${name}.${checksum}.json`;
 }
 
+function applyStaticPage(html: string, page: StaticPage): string {
+  const titled = html.replace(
+    /<title>[^<]*<\/title>/,
+    () => `<title>${escapeHtml(page.title)}</title>`,
+  );
+  const described = titled.replace(
+    /<meta name="description" content="[^"]*"\s*\/?>/,
+    () => `<meta name="description" content="${escapeHtml(page.description)}" />`,
+  );
+  if (!described.includes('<noscript id="docs-first-fallback">')) {
+    throw new Error("built index.html is missing the docs-first noscript marker");
+  }
+  return described.replace(/<noscript id="docs-first-fallback">[\s\S]*?<\/noscript>/, () => {
+    return `<noscript id="docs-first-fallback">${page.body}</noscript>`;
+  });
+}
+
 function docsFirstStaticPlugin(): Plugin {
   const fallbackMarker = '<noscript id="docs-first-fallback"></noscript>';
 
@@ -223,6 +241,9 @@ function docsFirstStaticPlugin(): Plugin {
       if (!html.includes(fallbackMarker)) {
         throw new Error("index.html is missing the docs-first noscript marker");
       }
+      if (!html.includes('name="description"')) {
+        throw new Error("index.html is missing the description meta");
+      }
       return html.replace(
         fallbackMarker,
         `<noscript id="docs-first-fallback">${renderStaticHomeAndHub()}</noscript>`,
@@ -230,9 +251,15 @@ function docsFirstStaticPlugin(): Plugin {
     },
     writeBundle() {
       const indexPath = path.resolve("dist/index.html");
-      const docsDir = path.resolve("dist/docs");
-      mkdirSync(docsDir, { recursive: true });
-      copyFileSync(indexPath, path.join(docsDir, "index.html"));
+      const built = readFileSync(indexPath, "utf8");
+      const pages = staticPages();
+
+      for (const page of pages) {
+        const relative = distFileForPath(page.path);
+        const outPath = path.resolve("dist", relative);
+        mkdirSync(path.dirname(outPath), { recursive: true });
+        writeFileSync(outPath, applyStaticPage(built, page));
+      }
     },
   };
 }