From ea8f56ecbea82892a0d0796e78d62cc5c739e9ac Mon Sep 17 00:00:00 2001
From: Joe Blau <im@joeblau.com>
Date: Sat, 26 Sep 2026 14:25:41 -0700
Subject: [PATCH] feat(docs): make the Hyperliquid SDK docs agent-ready

- llms.txt with when-to-use guidance, call examples, and every docs page (generated from the docs source)
- llms-full.txt with every page's Markdown, links made absolute
- sitemap.xml with lastmod for every page
- SoftwareApplication + Organization (with contactPoint) + WebSite JSON-LD on the homepage
- llms.txt alternate link on every page; footer links to About, Contact, Privacy, llms.txt
- branded 404 page linking the docs, sitemap, and llms.txt
- unit tests for the generators; verify-export now gates on the agent files; CI runs the tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/docs.yml         |   4 +
 website/app/global.css             |  10 ++
 website/app/llms-full.txt/route.ts |  10 ++
 website/app/llms.txt/route.ts      |   8 ++
 website/app/not-found.tsx          |  38 ++++++
 website/app/page.tsx               |  18 ++-
 website/app/sitemap.ts             |  11 ++
 website/lib/agent-pages.ts         |  30 +++++
 website/lib/agent.test.ts          | 124 ++++++++++++++++++
 website/lib/agent.ts               | 197 +++++++++++++++++++++++++++++
 website/lib/social.ts              |   3 +-
 website/package.json               |   1 +
 website/scripts/verify-export.ts   |  75 ++++++++++-
 13 files changed, 524 insertions(+), 5 deletions(-)
 create mode 100644 website/app/llms-full.txt/route.ts
 create mode 100644 website/app/llms.txt/route.ts
 create mode 100644 website/app/not-found.tsx
 create mode 100644 website/app/sitemap.ts
 create mode 100644 website/lib/agent-pages.ts
 create mode 100644 website/lib/agent.test.ts
 create mode 100644 website/lib/agent.ts

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 1118e343..addfb6ab 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -66,6 +66,10 @@ jobs:
         working-directory: website
         run: bun run check
 
+      - name: Test documentation website helpers
+        working-directory: website
+        run: bun run test
+
       - name: Build static documentation website
         working-directory: website
         run: bun run build
diff --git a/website/app/global.css b/website/app/global.css
index bb406508..350294ff 100644
--- a/website/app/global.css
+++ b/website/app/global.css
@@ -169,6 +169,11 @@ textarea:focus-visible {
   line-height: 1.7;
   color: var(--color-text-muted);
 }
+.hero-description a {
+  color: var(--color-accent);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
 .hero-actions {
   display: flex;
   align-items: center;
@@ -389,6 +394,11 @@ textarea:focus-visible {
 .landing-footer a:hover {
   color: var(--color-accent);
 }
+.footer-links {
+  display: flex;
+  flex-wrap: wrap;
+  gap: --spacing(4);
+}
 
 /* Entrance: three attention layers, 200 ms apart — headline, then supporting copy and actions,
    then the code window. `translate` composes with the code window's resting `transform`. */
diff --git a/website/app/llms-full.txt/route.ts b/website/app/llms-full.txt/route.ts
new file mode 100644
index 00000000..39befba8
--- /dev/null
+++ b/website/app/llms-full.txt/route.ts
@@ -0,0 +1,10 @@
+import { llmsFullText } from "@/lib/agent";
+import { agentPagesWithMarkdown } from "@/lib/agent-pages";
+
+export const dynamic = "force-static";
+
+export async function GET() {
+  return new Response(llmsFullText(await agentPagesWithMarkdown()), {
+    headers: { "Content-Type": "text/plain; charset=utf-8" },
+  });
+}
diff --git a/website/app/llms.txt/route.ts b/website/app/llms.txt/route.ts
new file mode 100644
index 00000000..d5264087
--- /dev/null
+++ b/website/app/llms.txt/route.ts
@@ -0,0 +1,8 @@
+import { llmsText } from "@/lib/agent";
+import { agentPages } from "@/lib/agent-pages";
+
+export const dynamic = "force-static";
+
+export function GET() {
+  return new Response(llmsText(agentPages()), { headers: { "Content-Type": "text/plain; charset=utf-8" } });
+}
diff --git a/website/app/not-found.tsx b/website/app/not-found.tsx
new file mode 100644
index 00000000..4fd15864
--- /dev/null
+++ b/website/app/not-found.tsx
@@ -0,0 +1,38 @@
+import { HomeLayout } from "fumadocs-ui/layouts/home";
+import { ArrowRight } from "lucide-react";
+import type { Metadata } from "next";
+import Link from "next/link";
+import { baseOptions } from "@/lib/layout.shared";
+
+export const metadata: Metadata = { title: "Page not found", robots: { index: false } };
+
+export default function NotFound() {
+  const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? "";
+  return (
+    <HomeLayout {...baseOptions()}>
+      <main className="landing">
+        <div className="hero">
+          <div className="hero-copy">
+            <p className="eyebrow">
+              <span /> 404 · PAGE NOT FOUND
+            </p>
+            <h1>This page does not exist.</h1>
+            <p className="hero-description">
+              The Hyperliquid SDK documentation has no page at this address. It may have moved. Start from the docs, or
+              use the <a href={`${basePath}/sitemap.xml`}>sitemap</a> or <a href={`${basePath}/llms.txt`}>llms.txt</a>{" "}
+              to find every page.
+            </p>
+            <div className="hero-actions">
+              <Link className="button-primary" href="/docs/">
+                Open the docs <ArrowRight size={16} aria-hidden />
+              </Link>
+              <Link className="button-secondary" href="/">
+                Back to home <ArrowRight size={16} aria-hidden />
+              </Link>
+            </div>
+          </div>
+        </div>
+      </main>
+    </HomeLayout>
+  );
+}
diff --git a/website/app/page.tsx b/website/app/page.tsx
index 3962afdd..13114617 100644
--- a/website/app/page.tsx
+++ b/website/app/page.tsx
@@ -2,6 +2,7 @@ import { HomeLayout } from "fumadocs-ui/layouts/home";
 import { ArrowRight, ArrowUpRight } from "lucide-react";
 import Link from "next/link";
 import { InstallCommand } from "@/components/install-command";
+import { homeStructuredData, jsonLdScript, organization } from "@/lib/agent";
 import { baseOptions } from "@/lib/layout.shared";
 
 const features = [
@@ -28,6 +29,11 @@ const features = [
 export default function Home() {
   return (
     <HomeLayout {...baseOptions()}>
+      <script
+        type="application/ld+json"
+        // biome-ignore lint/security/noDangerouslySetInnerHtml: static JSON-LD, escaped by jsonLdScript.
+        dangerouslySetInnerHTML={{ __html: jsonLdScript(homeStructuredData()) }}
+      />
       <main className="landing">
         <div className="hero">
           <div className="hero-copy">
@@ -106,9 +112,15 @@ export default function Home() {
         </div>
         <footer className="landing-footer">
           <span>Built by Bloxwap. Open source, MIT licensed.</span>
-          <a href="https://github.com/bloxwap/hyperliquid">
-            View on GitHub <ArrowUpRight size={14} aria-hidden />
-          </a>
+          <nav className="footer-links" aria-label="Company and agent resources">
+            <a href={organization.about}>About</a>
+            <a href={organization.contact}>Contact</a>
+            <a href={organization.privacy}>Privacy</a>
+            <a href={`${process.env.NEXT_PUBLIC_BASE_PATH ?? ""}/llms.txt`}>llms.txt</a>
+            <a href="https://github.com/bloxwap/hyperliquid">
+              View on GitHub <ArrowUpRight size={14} aria-hidden />
+            </a>
+          </nav>
         </footer>
       </main>
     </HomeLayout>
diff --git a/website/app/sitemap.ts b/website/app/sitemap.ts
new file mode 100644
index 00000000..cdf44b65
--- /dev/null
+++ b/website/app/sitemap.ts
@@ -0,0 +1,11 @@
+import type { MetadataRoute } from "next";
+import { pageUrl } from "@/lib/agent";
+import { source } from "@/lib/source";
+
+export const dynamic = "force-static";
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  // Every page is rebuilt on each deploy, so the build time is each page's last modification.
+  const lastModified = new Date();
+  return ["/", ...source.getPages().map((page) => page.url)].map((url) => ({ url: pageUrl(url), lastModified }));
+}
diff --git a/website/lib/agent-pages.ts b/website/lib/agent-pages.ts
new file mode 100644
index 00000000..54b87364
--- /dev/null
+++ b/website/lib/agent-pages.ts
@@ -0,0 +1,30 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { type AgentPage, agentMarkdown } from "./agent";
+import { source } from "./source";
+
+// Next runs route handlers from the website directory at build time; the docs live beside it.
+const docsDir = resolve(process.cwd(), "../docs");
+
+export function agentPages(): AgentPage[] {
+  return source
+    .getPages()
+    .map((page) => ({ url: page.url, title: page.data.title, description: page.data.description }));
+}
+
+/** Every docs page with its Markdown source, read from the same files GitHub renders. */
+export async function agentPagesWithMarkdown(): Promise<(AgentPage & { markdown: string })[]> {
+  return Promise.all(
+    source.getPages().map(async (page) => {
+      // Fumadocs sees README.md as index.md (see lib/source.ts); read the original file.
+      const sourcePath = page.path.replace(/(^|\/)index\.md$/, "$1README.md");
+      const raw = await readFile(resolve(docsDir, sourcePath), "utf8");
+      return {
+        url: page.url,
+        title: page.data.title,
+        description: page.data.description,
+        markdown: agentMarkdown(raw, sourcePath),
+      };
+    }),
+  );
+}
diff --git a/website/lib/agent.test.ts b/website/lib/agent.test.ts
new file mode 100644
index 00000000..19109155
--- /dev/null
+++ b/website/lib/agent.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, test } from "bun:test";
+import {
+  agentMarkdown,
+  homeStructuredData,
+  jsonLdScript,
+  llmsFullText,
+  llmsText,
+  organization,
+  pageUrl,
+} from "./agent";
+
+const site = "https://bloxwap.github.io/hyperliquid/";
+const pages = [
+  { url: "/docs/clients", title: "Clients", description: "Use the clients." },
+  { url: "/docs", title: "Introduction" },
+];
+
+describe("pageUrl", () => {
+  test("publishes routes under the project base path with a trailing slash", () => {
+    expect(pageUrl("/")).toBe(site);
+    expect(pageUrl("/docs")).toBe(`${site}docs/`);
+    expect(pageUrl("/docs/guides/market-orders/")).toBe(`${site}docs/guides/market-orders/`);
+  });
+});
+
+describe("llmsText", () => {
+  const text = llmsText(pages);
+
+  test("follows the llms.txt layout: H1, blockquote summary, then H2 sections", () => {
+    const lines = text.split("\n");
+    expect(lines[0]).toBe("# Hyperliquid SDK (@bloxwap/hyperliquid)");
+    expect(lines[2]?.startsWith("> ")).toBe(true);
+    expect(text.match(/^# /gm)).toHaveLength(1);
+    expect(text).toContain("\n## When to use this\n");
+    expect(text).toContain("\n## How to call it\n");
+    expect(text).toContain("\n## Docs\n");
+    expect(text).toContain("\n## Optional\n");
+  });
+
+  test("links every docs page by its published URL, in a stable order", () => {
+    const docs = text.split("\n## Docs\n\n")[1]?.split("\n\n")[0];
+    expect(docs).toBe(`- [Introduction](${site}docs/)\n- [Clients](${site}docs/clients/): Use the clients.`);
+  });
+
+  test("points at the full text, sitemap, and company trust pages", () => {
+    for (const url of [
+      `${site}llms-full.txt`,
+      `${site}sitemap.xml`,
+      organization.about,
+      organization.contact,
+      organization.privacy,
+    ]) {
+      expect(text).toContain(`](${url})`);
+    }
+  });
+});
+
+describe("agentMarkdown", () => {
+  test("drops front matter", () => {
+    expect(agentMarkdown("---\ntitle: X\ndescription: Y\n---\n\n# X\n\nBody.\n", "clients.md")).toBe("# X\n\nBody.");
+  });
+
+  test("turns relative Markdown links into absolute website URLs", () => {
+    const raw = [
+      "[a](clients.md#info-endpoint)",
+      "[b](guides/README.md)",
+      "[c](../signing.md)",
+      "[d](README.md)",
+      "[e](https://example.com/x.md)",
+      "[f](#local)",
+    ].join("\n");
+    expect(agentMarkdown(raw, "README.md").split("\n").slice(0, 2)).toEqual([
+      `[a](${site}docs/clients/#info-endpoint)`,
+      `[b](${site}docs/guides/)`,
+    ]);
+    expect(agentMarkdown(raw, "guides/market-orders.md").split("\n")).toEqual([
+      `[a](${site}docs/guides/clients/#info-endpoint)`,
+      `[b](${site}docs/guides/guides/)`,
+      `[c](${site}docs/signing/)`,
+      `[d](${site}docs/guides/)`,
+      "[e](https://example.com/x.md)",
+      "[f](#local)",
+    ]);
+  });
+});
+
+describe("llmsFullText", () => {
+  test("concatenates every page with its source URL and links back to llms.txt", () => {
+    const text = llmsFullText(pages.map((page) => ({ ...page, markdown: `# ${page.title}` })));
+    expect(text).toContain(`${site}llms.txt`);
+    expect(text).toContain(`<!-- Source: ${site}docs/clients/ -->\n\n# Clients`);
+    expect(text).toContain(`<!-- Source: ${site}docs/ -->\n\n# Introduction`);
+  });
+});
+
+describe("homeStructuredData", () => {
+  const graph = homeStructuredData()["@graph"] as Record<string, unknown>[];
+  const byType = (type: string) => graph.find((node) => node["@type"] === type);
+
+  test("describes the SDK as free, MIT-licensed software published by the organization", () => {
+    const software = byType("SoftwareApplication");
+    expect(software).toMatchObject({
+      name: "@bloxwap/hyperliquid",
+      url: site,
+      applicationCategory: "DeveloperApplication",
+      license: "https://opensource.org/licenses/MIT",
+      offers: { "@type": "Offer", price: "0" },
+      publisher: { "@id": organization.id },
+    });
+    expect(software?.softwareVersion).toMatch(/^\d+\.\d+\.\d+/);
+  });
+
+  test("gives the organization a contact point and shares its @id with the root site", () => {
+    expect(byType("Organization")).toMatchObject({
+      "@id": "https://bloxwap.github.io/#organization",
+      contactPoint: [{ "@type": "ContactPoint", contactType: "customer support", email: organization.email }],
+    });
+  });
+
+  test("serializes safely inside a script element", () => {
+    expect(jsonLdScript({ a: "</script><script>" })).toBe('{"a":"\\u003c/script>\\u003cscript>"}');
+    expect(JSON.parse(jsonLdScript(homeStructuredData()))).toEqual(homeStructuredData());
+  });
+});
diff --git a/website/lib/agent.ts b/website/lib/agent.ts
new file mode 100644
index 00000000..21234899
--- /dev/null
+++ b/website/lib/agent.ts
@@ -0,0 +1,197 @@
+// Machine-readable files for AI agents and crawlers: llms.txt, llms-full.txt, and homepage JSON-LD.
+// GitHub Pages serves static files only, so everything here is rendered once at build time.
+import sdkPackage from "../../package.json";
+import { homeDescription, siteUrl } from "./social";
+
+export const origin = siteUrl.origin;
+export const repository = "https://github.com/bloxwap/hyperliquid";
+export const npmPackage = "https://www.npmjs.com/package/@bloxwap/hyperliquid";
+
+/** Company facts shared with the bloxwap.github.io root site. Keep them true. */
+export const organization = {
+  id: `${origin}/#organization`,
+  name: "Bloxwap, Inc.",
+  url: "https://bloxwap.com",
+  email: "support@bloxwap.com",
+  sameAs: [
+    "https://x.com/bloxwap",
+    "https://github.com/bloxwap",
+    "https://discord.com/invite/cEfkcg6JHT",
+    "https://bloxwap.com",
+    "https://bloxwap.pro",
+  ],
+  about: `${origin}/about/`,
+  contact: `${origin}/contact/`,
+  privacy: `${origin}/privacy/`,
+};
+
+export type AgentPage = { url: string; title: string; description?: string };
+
+/** The published URL of a site path such as `/docs/clients/` or `llms.txt`. */
+export function absoluteUrl(path: string): string {
+  return new URL(path.replace(/^\/+/, ""), siteUrl).href;
+}
+
+/** The published URL of a page route such as `/docs/clients`, with the site's trailing slash. */
+export function pageUrl(url: string): string {
+  const path = url.replace(/^\/+|\/+$/g, "");
+  return absoluteUrl(path ? `${path}/` : "");
+}
+
+/** The llms.txt index (https://llmstxt.org): when to use the SDK, how to call it, and every docs page. */
+export function llmsText(pages: AgentPage[]): string {
+  const docs = [...pages]
+    .sort((a, b) => a.url.localeCompare(b.url))
+    .map((page) => `- [${page.title}](${pageUrl(page.url)})${page.description ? `: ${page.description}` : ""}`);
+
+  return `# Hyperliquid SDK (@bloxwap/hyperliquid)
+
+> ${homeDescription} \`@bloxwap/hyperliquid\` is an MIT-licensed, community-supported TypeScript client for the Hyperliquid exchange API, published on npm by Bloxwap, Inc.
+
+It covers the whole public Hyperliquid API: the Info endpoint (market data and account state), the Exchange endpoint (signed trading and account actions), WebSocket subscriptions, and the Explorer endpoint. Requests and responses are fully typed and validated. It runs on Bun 1.3.3+, Node.js 22.12+, modern browsers, and React Native, on mainnet or testnet.
+
+## When to use this
+
+Use \`@bloxwap/hyperliquid\` when an agent or developer, working in TypeScript or JavaScript, needs to:
+
+- Read Hyperliquid market data: mid prices, order books, candles, funding, asset metadata, and perp or spot contexts (\`InfoClient\`).
+- Read a user's positions, open orders, fills, balances, vault equity, or portfolio history (\`InfoClient\`).
+- Place, modify, or cancel orders; move funds; manage leverage, agent wallets, vaults, sub-accounts, or multi-sig accounts (\`ExchangeClient\`).
+- Stream live prices, trades, order books, and account events over WebSocket with automatic reconnection and resubscription (\`SubscriptionClient\`).
+- Look up blocks, transactions, and addresses (\`ExplorerClient\`).
+- Sign Hyperliquid L1 and user-signed actions with a viem account, a browser wallet, or a raw private key (\`@bloxwap/hyperliquid/signing\`).
+- Format prices and sizes to Hyperliquid's precision rules and map symbols to asset IDs (\`@bloxwap/hyperliquid/utils\`).
+
+Do not use it for other exchanges, for languages other than TypeScript or JavaScript (use Hyperliquid's official Python SDK instead), or as a hosted trading service: it is a client library that runs in your code and never holds keys or funds for you.
+
+## How to call it
+
+Install with \`npm i @bloxwap/hyperliquid\` (or \`bun add\`, \`pnpm add\`, \`yarn add\`), then:
+
+\`\`\`ts
+import { HttpTransport, InfoClient } from "@bloxwap/hyperliquid";
+
+const info = new InfoClient({ transport: new HttpTransport() });
+const mids = await info.allMids(); // { BTC: "…", ETH: "…", … }
+\`\`\`
+
+Trading needs a wallet. Test with \`new HttpTransport({ isTestnet: true })\` before using a funded key:
+
+\`\`\`ts
+import { ExchangeClient, HttpTransport } from "@bloxwap/hyperliquid";
+import { privateKeyToAccount } from "viem/accounts";
+
+const exchange = new ExchangeClient({ transport: new HttpTransport(), wallet: privateKeyToAccount("0x...") });
+await exchange.order({
+  orders: [{ a: 0, b: true, p: "50000", s: "0.01", r: false, t: { limit: { tif: "Gtc" } } }],
+  grouping: "na",
+});
+\`\`\`
+
+Every client method takes the Hyperliquid API's own request fields and returns its typed response. Errors are typed classes (\`ApiRequestError\`, \`HttpRequestError\`, \`WebSocketRequestError\`, \`ValidationError\`); see Error handling below.
+
+## Docs
+
+${docs.join("\n")}
+
+## Optional
+
+- [Full documentation as Markdown](${absoluteUrl("llms-full.txt")}): Every docs page above in one plain-text file.
+- [Sitemap](${absoluteUrl("sitemap.xml")}): Every page on this site.
+- [Source code](${repository}): MIT-licensed repository and issue tracker.
+- [npm package](${npmPackage}): Current version ${sdkPackage.version}.
+- [About Bloxwap](${organization.about}): The company that maintains the SDK.
+- [Contact](${organization.contact}): ${organization.email}, GitHub issues, X, and Discord.
+- [Privacy](${organization.privacy}): No cookies or analytics on this site.
+`;
+}
+
+/**
+ * Prepares a docs source file for agents: drops YAML front matter and turns relative Markdown links
+ * (as written for GitHub, e.g. `../clients.md#info-endpoint`) into absolute website URLs.
+ * `sourcePath` is the file's path inside `docs/`, such as `guides/README.md`.
+ */
+export function agentMarkdown(raw: string, sourcePath: string): string {
+  const body = raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n+/, "");
+  const base = new URL(`docs/${sourcePath}`, "https://docs.invalid/");
+  return body
+    .replace(/\]\(([^)\s]+\.md(?:#[^)\s]*)?)\)/g, (match, href: string) => {
+      if (/^(?:[a-z][a-z\d+.-]*:|\/|#)/i.test(href)) return match;
+      const target = new URL(href, base);
+      const page = target.pathname.replace(/(^|\/)README\.md$/i, "$1").replace(/\.md$/i, "/");
+      return `](${absoluteUrl(page)}${target.hash})`;
+    })
+    .trim();
+}
+
+/** llms-full.txt: the llms.txt header followed by every docs page's Markdown. */
+export function llmsFullText(pages: (AgentPage & { markdown: string })[]): string {
+  const sections = pages.map((page) => `<!-- Source: ${pageUrl(page.url)} -->\n\n${page.markdown}`);
+  return `# Hyperliquid SDK (@bloxwap/hyperliquid): full documentation
+
+> ${homeDescription} The index of these pages, with guidance on when to use the SDK, is at ${absoluteUrl("llms.txt")}.
+
+${sections.join("\n\n---\n\n")}
+`;
+}
+
+/** Homepage JSON-LD: the SDK as a SoftwareApplication, published by the organization. */
+export function homeStructuredData(): Record<string, unknown> {
+  const home = siteUrl.href;
+  return {
+    "@context": "https://schema.org",
+    "@graph": [
+      {
+        "@type": "Organization",
+        "@id": organization.id,
+        name: organization.name,
+        alternateName: "Bloxwap",
+        url: organization.url,
+        logo: `${origin}/icon.svg`,
+        email: organization.email,
+        sameAs: organization.sameAs,
+        contactPoint: [
+          {
+            "@type": "ContactPoint",
+            contactType: "customer support",
+            email: organization.email,
+            url: organization.contact,
+            availableLanguage: "English",
+          },
+        ],
+      },
+      {
+        "@type": "SoftwareApplication",
+        "@id": `${home}#software`,
+        name: sdkPackage.name,
+        alternateName: "Bloxwap Hyperliquid SDK",
+        description: homeDescription,
+        url: home,
+        applicationCategory: "DeveloperApplication",
+        applicationSubCategory: "API client library",
+        operatingSystem: "Node.js, Bun, Web browser, React Native",
+        programmingLanguage: "TypeScript",
+        softwareVersion: sdkPackage.version,
+        license: "https://opensource.org/licenses/MIT",
+        codeRepository: repository,
+        downloadUrl: npmPackage,
+        isAccessibleForFree: true,
+        offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
+        publisher: { "@id": organization.id },
+      },
+      {
+        "@type": "WebSite",
+        "@id": `${home}#website`,
+        name: "Hyperliquid SDK documentation",
+        url: home,
+        inLanguage: "en",
+        publisher: { "@id": organization.id },
+      },
+    ],
+  };
+}
+
+/** Serializes JSON-LD for a <script> element; `<` is escaped so content cannot close the tag. */
+export function jsonLdScript(data: unknown): string {
+  return JSON.stringify(data).replace(/</g, "\\u003c");
+}
diff --git a/website/lib/social.ts b/website/lib/social.ts
index 63901bf9..70907b79 100644
--- a/website/lib/social.ts
+++ b/website/lib/social.ts
@@ -18,7 +18,8 @@ export function socialMetadata(pageUrl: string, title: string, description: stri
 
   return {
     description,
-    alternates: { canonical },
+    // Point agents at the plain-text index of the whole site from every page.
+    alternates: { canonical, types: { "text/plain": new URL("llms.txt", siteUrl).href } },
     openGraph: {
       type: "website",
       siteName: "Bloxwap",
diff --git a/website/package.json b/website/package.json
index 49e16c6f..b92cc59c 100644
--- a/website/package.json
+++ b/website/package.json
@@ -7,6 +7,7 @@
     "preview": "bun run scripts/preview.ts",
     "build": "next build && bun run scripts/verify-export.ts",
     "check": "fumadocs-mdx && next typegen && tsc --noEmit",
+    "test": "bun test lib/",
     "postinstall": "fumadocs-mdx"
   },
   "dependencies": {
diff --git a/website/scripts/verify-export.ts b/website/scripts/verify-export.ts
index c0efa2cf..5168c726 100644
--- a/website/scripts/verify-export.ts
+++ b/website/scripts/verify-export.ts
@@ -277,6 +277,79 @@ if (!searchArtifact) {
   }
 }
 
+// Agent and crawler files: GitHub Pages serves them as-is, so verify their exported content.
+const publishedPages = [...contentPages.values()].map((route) => `${publishedOrigin}${publishedBasePath}${route}`);
+async function exportedText(path: string): Promise<string | undefined> {
+  if (!files.has(path)) {
+    errors.add(`Missing exported ${path}.`);
+    return undefined;
+  }
+  return Bun.file(resolve(outDir, path)).text();
+}
+
+const sitemap = await exportedText("sitemap.xml");
+if (sitemap !== undefined) {
+  if (!sitemap.startsWith("<?xml") || !sitemap.includes('xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"')) {
+    errors.add("sitemap.xml: expected an XML urlset in the sitemaps.org 0.9 namespace.");
+  }
+  const entries = [...sitemap.matchAll(/<url>\s*<loc>([^<]+)<\/loc>\s*<lastmod>([^<]+)<\/lastmod>/g)];
+  const locs = new Set(entries.map((entry) => entry[1]));
+  for (const url of publishedPages) if (!locs.has(url)) errors.add(`sitemap.xml: missing ${url}.`);
+  if (locs.size !== publishedPages.length) {
+    errors.add(`sitemap.xml: expected ${publishedPages.length} URLs with lastmod, found ${locs.size}.`);
+  }
+  for (const [, loc, lastmod] of entries) {
+    if (Number.isNaN(Date.parse(lastmod ?? ""))) errors.add(`sitemap.xml: invalid lastmod for ${loc}.`);
+  }
+}
+
+const llms = await exportedText("llms.txt");
+if (llms !== undefined) {
+  if (!llms.startsWith("# ") || !/\n> \S/.test(llms)) errors.add("llms.txt: must open with an H1 and a blockquote.");
+  if (!llms.includes("\n## When to use this\n")) errors.add("llms.txt: missing the 'When to use this' section.");
+  for (const url of publishedPages.filter((url) => url.includes("/docs/"))) {
+    if (!llms.includes(`](${url})`)) errors.add(`llms.txt: missing a link to ${url}.`);
+  }
+}
+
+const llmsFull = await exportedText("llms-full.txt");
+if (llmsFull !== undefined) {
+  for (const url of publishedPages.filter((url) => url.includes("/docs/"))) {
+    if (!llmsFull.includes(`<!-- Source: ${url} -->`)) errors.add(`llms-full.txt: missing the page ${url}.`);
+  }
+  if (/-->\n\n---\n/.test(llmsFull)) errors.add("llms-full.txt: front matter was not removed.");
+  if (/\]\((?![a-z]+:|#)[^)]*\.md\b/i.test(llmsFull)) errors.add("llms-full.txt: has relative Markdown links.");
+}
+
+const home = await exportedText("index.html");
+if (home !== undefined) {
+  const types = new Set<string>();
+  for (const [, json] of home.matchAll(/<script type="application\/ld\+json">([\s\S]*?)<\/script>/g)) {
+    try {
+      const data = JSON.parse(json ?? "") as { "@graph"?: { "@type"?: string; contactPoint?: unknown }[] };
+      for (const node of data["@graph"] ?? []) {
+        if (node["@type"]) types.add(node["@type"]);
+        if (node["@type"] === "Organization" && !node.contactPoint) {
+          errors.add("index.html: Organization JSON-LD needs a contactPoint.");
+        }
+      }
+    } catch {
+      errors.add("index.html: JSON-LD is not valid JSON.");
+    }
+  }
+  for (const type of ["Organization", "SoftwareApplication", "WebSite"]) {
+    if (!types.has(type)) errors.add(`index.html: missing ${type} JSON-LD.`);
+  }
+  if (!/<html[^>]* lang="en"/.test(home)) errors.add('index.html: missing <html lang="en">.');
+}
+
+const notFound = await exportedText("404.html");
+if (notFound !== undefined) {
+  for (const link of ["/sitemap.xml", "/llms.txt"]) {
+    if (!notFound.includes(`href="${basePath}${link}"`)) errors.add(`404.html: missing a link to ${link}.`);
+  }
+}
+
 if (errors.size > 0) {
   console.error(`Static export verification failed (${errors.size} issue${errors.size === 1 ? "" : "s"}):`);
   for (const error of [...errors].sort().slice(0, 60)) console.error(`- ${error}`);
@@ -286,6 +359,6 @@ if (errors.size > 0) {
 
 console.log(
   `Verified ${docsFiles.length} docs pages, ${htmlFiles.length} HTML files, ${checkedLinks} internal links/assets, ` +
-    `${checkedAnchors} anchors, ${checkedCards} unique social cards, static search, and .nojekyll ` +
+    `${checkedAnchors} anchors, ${checkedCards} unique social cards, static search, agent files, and .nojekyll ` +
     `(base path: ${basePath || "/"}).`,
 );