feat(docs): AI-friendly docs — llms.txt + Copy-for-AI

apps/docs/app/docs/[slug]/llms.txt/route.ts

@@ -0,0 +1,31 @@
+import { hookToMarkdown } from "@/lib/hook-markdown";
+import { HOOKS, getHook } from "@/lib/hooks-registry";
+
+/* /docs/<slug>/llms.txt — the machine-readable twin of every hook page: that
+   one hook rendered through the shared Markdown renderer. Prerendered for every
+   hook alongside its HTML page. */
+export function generateStaticParams() {
+  return HOOKS.map(({ slug }) => ({ slug }));
+}
+
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ slug: string }> },
+): Promise<Response> {
+  const { slug } = await params;
+  const hook = getHook(slug);
+
+  if (!hook) {
+    return new Response("Not found\n", {
+      status: 404,
+      headers: { "Content-Type": "text/plain; charset=utf-8" },
+    });
+  }
+
+  return new Response(`${hookToMarkdown(hook)}\n`, {
+    headers: {
+      "Content-Type": "text/plain; charset=utf-8",
+      "Cache-Control": "public, max-age=0, must-revalidate",
+    },
+  });
+}

apps/docs/app/docs/page.tsx

@@ -1,6 +1,7 @@
 import type { Metadata } from "next";
 import { CodeBlock } from "@/components/code-block";
 import { HookCard } from "@/components/hook-card";
+import { ArrowRightIcon } from "@/components/icons";
 import { InstallCommand } from "@/components/install-command";
 import {
   CATEGORY_LABELS,
@@ -46,6 +47,39 @@ export default function DocsIndexPage() {
         can try it before you install it.
       </p>
 
+      <section
+        aria-label="Use hookli with AI"
+        className="surface mt-8 flex flex-col gap-4 rounded-xl p-5 sm:flex-row sm:items-center sm:justify-between"
+      >
+        <div className="min-w-0">
+          <h2 className="text-base font-semibold text-fg">Building with an LLM?</h2>
+          <p className="mt-1 max-w-xl text-sm leading-relaxed text-gray-body">
+            Every hook — signatures, usage and source — as plain Markdown for AI
+            assistants and coding agents, generated from this site so it never
+            drifts.
+          </p>
+        </div>
+        <div className="flex shrink-0 flex-wrap items-center gap-2">
+          <a
+            href="/llms-full.txt"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="flex min-h-11 items-center gap-2 rounded-md bg-accent px-5 text-sm font-semibold text-ground transition-opacity duration-200 hover:opacity-90"
+          >
+            Copy all hooks for AI
+            <ArrowRightIcon className="size-4" aria-hidden="true" />
+          </a>
+          <a
+            href="/llms.txt"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="inline-flex min-h-11 items-center rounded-md px-3 font-mono text-sm text-accent underline-offset-4 transition-colors duration-200 hover:text-accent-hover hover:underline"
+          >
+            llms.txt
+          </a>
+        </div>
+      </section>
+
       <h2 className="mt-12 text-2xl">Quick start</h2>
       <ol className="mt-4 grid gap-3 sm:grid-cols-3">
         <li className="surface flex flex-col rounded-xl p-5">

apps/docs/app/globals.css

@@ -266,6 +266,12 @@ body {
   animation: donate-bob 3.5s ease-in-out infinite;
 }
 
+/* Smooth in-page anchor scrolling (e.g. the hero → #ai trigger). The
+   reduced-motion block below forces this back to `auto` when requested. */
+html {
+  scroll-behavior: smooth;
+}
+
 @media (prefers-reduced-motion: reduce) {
   *,
   *::before,

apps/docs/app/layout.tsx

@@ -27,6 +27,15 @@ export const metadata: Metadata = {
     default: "hookli — simple React hooks",
   },
   description: TAGLINE,
+  alternates: {
+    // Advertise the machine-readable llmstxt.org representations of the site.
+    types: {
+      "text/plain": [
+        { url: "/llms.txt", title: "hookli llms.txt" },
+        { url: "/llms-full.txt", title: "hookli llms-full.txt" },
+      ],
+    },
+  },
   openGraph: {
     type: "website",
     siteName: "hookli",

apps/docs/app/llms-full.txt/route.ts

@@ -0,0 +1,14 @@
+import { buildLlmsFull } from "@/lib/llms";
+
+/* /llms-full.txt — the whole library in one Markdown document (every hook via
+   the shared renderer). No request input, so it is prerendered at build time. */
+export const dynamic = "force-static";
+
+export function GET(): Response {
+  return new Response(buildLlmsFull(), {
+    headers: {
+      "Content-Type": "text/plain; charset=utf-8",
+      "Cache-Control": "public, max-age=0, must-revalidate",
+    },
+  });
+}

apps/docs/app/llms.txt/route.ts

@@ -0,0 +1,14 @@
+import { buildLlmsIndex } from "@/lib/llms";
+
+/* /llms.txt — the concise, llmstxt.org-standard index. No request input, so it
+   is prerendered to a static file at build time. */
+export const dynamic = "force-static";
+
+export function GET(): Response {
+  return new Response(buildLlmsIndex(), {
+    headers: {
+      "Content-Type": "text/plain; charset=utf-8",
+      "Cache-Control": "public, max-age=0, must-revalidate",
+    },
+  });
+}

apps/docs/app/page.tsx

@@ -5,6 +5,7 @@ import { ArrowRightIcon, GitHubIcon } from "@/components/icons";
 import { ComparisonSection } from "@/components/comparison-section";
 import { FeaturesSection } from "@/components/features-section";
 import { LiveProofSection } from "@/components/live-proof-section";
+import { AiSection } from "@/components/ai-section";
 import { HooksIndexSection } from "@/components/hooks-index-section";
 import { SupportSection } from "@/components/support-section";
 import { BottomCtaSection } from "@/components/bottom-cta-section";
@@ -25,7 +26,15 @@ export default function Home() {
         <div aria-hidden="true" className="pointer-events-none absolute inset-0 hero-grid" />
         <div aria-hidden="true" className="pointer-events-none absolute inset-0 hero-glow" />
         <div className="relative mx-auto flex max-w-3xl flex-col items-center px-4 py-20 text-center sm:px-6 sm:py-28">
-          <p className="reveal inline-flex items-center gap-2 rounded-full border border-slate-syntax bg-ground-raised/60 px-3 py-1 text-xs font-medium text-gray-body backdrop-blur">
+          <a
+            href="#ai"
+            className="reveal group mb-4 inline-flex items-center gap-2 rounded-full border border-accent/30 bg-accent/10 px-3 py-1 text-xs font-medium text-accent transition-colors duration-200 hover:bg-accent/15"
+          >
+            <span aria-hidden="true" className="size-1.5 rounded-full bg-accent" />
+            New — hookli speaks AI
+            <ArrowRightIcon className="size-3 rotate-90 transition-transform duration-200 group-hover:translate-y-0.5" />
+          </a>
+          <p className="reveal reveal-d1 inline-flex items-center gap-2 rounded-full border border-slate-syntax bg-ground-raised/60 px-3 py-1 text-xs font-medium text-gray-body backdrop-blur">
             <span aria-hidden="true" className="size-1.5 rounded-full bg-accent" />
             {TAGLINE_SHORT}
           </p>
@@ -66,6 +75,7 @@ export default function Home() {
       <FeaturesSection />
       <ComparisonSection />
       <LiveProofSection />
+      <AiSection />
       <HooksIndexSection />
       <SupportSection />
       <BottomCtaSection />

apps/docs/app/robots.ts

@@ -3,7 +3,9 @@ import { SITE_URL } from "@/lib/site";
 
 export default function robots(): MetadataRoute.Robots {
   return {
-    rules: { userAgent: "*", allow: "/" },
+    // The llms.txt files are explicitly surfaced (already covered by "/", but
+    // listing them advertises the AI-friendly index and full dump to crawlers).
+    rules: { userAgent: "*", allow: ["/", "/llms.txt", "/llms-full.txt"] },
     sitemap: `${SITE_URL}/sitemap.xml`,
   };
 }

apps/docs/app/sitemap.ts

@@ -24,5 +24,17 @@ export default function sitemap(): MetadataRoute.Sitemap {
       changeFrequency: "yearly",
       priority: 0.4,
     },
+    {
+      url: `${SITE_URL}/llms.txt`,
+      lastModified,
+      changeFrequency: "monthly",
+      priority: 0.3,
+    },
+    {
+      url: `${SITE_URL}/llms-full.txt`,
+      lastModified,
+      changeFrequency: "monthly",
+      priority: 0.3,
+    },
   ];
 }

apps/docs/components/ai-section.tsx

@@ -0,0 +1,116 @@
+import { CopyButton } from "@/components/copy-button";
+import { SectionHeading } from "@/components/section-heading";
+import { BracesIcon, CopyIcon, ExternalLinkIcon } from "@/components/icons";
+import { buildLlmsIndex } from "@/lib/llms";
+import { HOOKS } from "@/lib/hooks-registry";
+import { SITE_URL } from "@/lib/site";
+
+/* Landing section that surfaces the AI-friendly surfaces (llms.txt, per-hook
+   Copy-for-AI, Open-in-ChatGPT/Claude) so visitors know the docs are built to
+   be read by a model, not just a human. Server component: the /llms.txt body
+   is built once from the registry and handed to the client CopyButton leaf. */
+
+const CARDS = [
+  {
+    Icon: BracesIcon,
+    title: "One file, the whole library",
+    body: (
+      <>
+        Point any model at{" "}
+        <code className="text-sm">/llms.txt</code> for the map, or{" "}
+        <code className="text-sm">/llms-full.txt</code> for every signature,
+        usage and source — generated from the same registry the docs use.
+      </>
+    ),
+  },
+  {
+    Icon: CopyIcon,
+    title: "Copy any hook for AI",
+    body: (
+      <>
+        Every hook page has a one-click <strong className="text-fg">Copy for AI</strong> —
+        clean Markdown, ready to paste into your chat and start building.
+      </>
+    ),
+  },
+  {
+    Icon: ExternalLinkIcon,
+    title: "Straight into your chat",
+    body: (
+      <>
+        Jump into ChatGPT or Claude prefilled with the hook&apos;s context and a
+        live docs link. Your AI pair is in the loop from line one.
+      </>
+    ),
+  },
+];
+
+export function AiSection() {
+  const llmsIndex = buildLlmsIndex();
+  const prompt = `I'm using hookli, a zero-dependency, typed, SSR-safe React hooks library (${HOOKS.length} hooks). Full reference: ${SITE_URL}/llms-full.txt — help me pick and use the right hooks for my app.`;
+  const chatgptUrl = `https://chatgpt.com/?q=${encodeURIComponent(prompt)}`;
+  const claudeUrl = `https://claude.ai/new?q=${encodeURIComponent(prompt)}`;
+  const linkClass =
+    "inline-flex min-h-11 items-center gap-1.5 text-sm text-gray-body underline-offset-4 transition-colors duration-200 hover:text-fg hover:underline";
+
+  return (
+    <section id="ai" className="mx-auto w-full max-w-5xl scroll-mt-24 px-4 py-20 sm:px-6">
+      <SectionHeading
+        eyebrow="AI-ready"
+        title="Bring your AI — it speaks hookli"
+        subtitle={
+          <>
+            Vibe-coding with an LLM? hookli ships a machine-readable map of all{" "}
+            {HOOKS.length} hooks, so your assistant recommends and wires them up
+            correctly — no stale copy-paste.
+          </>
+        }
+      />
+
+      <div className="mt-12 grid gap-4 md:grid-cols-3">
+        {CARDS.map(({ Icon, title, body }) => (
+          <div key={title} className="surface flex flex-col gap-4 rounded-xl p-6">
+            <span
+              aria-hidden="true"
+              className="surface flex size-11 items-center justify-center rounded-lg text-accent"
+            >
+              <Icon className="size-5" />
+            </span>
+            <h3 className="text-base font-semibold text-fg">{title}</h3>
+            <p className="text-sm text-gray-body">{body}</p>
+          </div>
+        ))}
+      </div>
+
+      <div className="mt-8 flex flex-col items-center justify-center gap-x-6 gap-y-3 sm:flex-row sm:flex-wrap">
+        <CopyButton
+          text={llmsIndex}
+          copyLabel="Copy llms.txt"
+          label="Copy the hookli llms.txt index to your clipboard"
+        />
+        <a href="/llms.txt" className={linkClass}>
+          <BracesIcon className="size-4" aria-hidden="true" />
+          View /llms.txt
+        </a>
+        <a
+          href={chatgptUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          className={linkClass}
+        >
+          Open in ChatGPT
+          <ExternalLinkIcon className="size-3.5" aria-hidden="true" />
+        </a>
+        <a
+          href={claudeUrl}
+          target="_blank"
+          rel="noopener noreferrer"
+          className={linkClass}
+        >
+          Open in Claude
+          <ExternalLinkIcon className="size-3.5" aria-hidden="true" />
+        </a>
+      </div>
+    </section>
+  );
+}

apps/docs/components/copy-button.tsx

@@ -6,10 +6,14 @@ import { CheckIcon, CopyIcon } from "@/components/icons";
 export function CopyButton({
   text,
   label = "Copy to clipboard",
+  copyLabel,
   className = "",
 }: {
   text: string;
   label?: string;
+  /* When set, renders the labeled pill variant with this visible text (e.g.
+     "Copy for AI") instead of the default icon-only square. */
+  copyLabel?: string;
   className?: string;
 }) {
   const [copied, setCopied] = useState(false);
@@ -32,6 +36,27 @@ export function CopyButton({
     timeoutRef.current = setTimeout(() => setCopied(false), 2000);
   }
 
+  if (copyLabel !== undefined) {
+    return (
+      <button
+        type="button"
+        onClick={copy}
+        aria-label={label}
+        className={`inline-flex min-h-11 items-center gap-2 rounded-lg border border-gray-outline px-4 text-sm font-medium text-fg transition-colors duration-200 hover:border-accent hover:text-accent ${className}`}
+      >
+        {copied ? (
+          <CheckIcon className="copy-pop size-4 text-accent" aria-hidden="true" />
+        ) : (
+          <CopyIcon className="size-4" aria-hidden="true" />
+        )}
+        <span>{copied ? "Copied" : copyLabel}</span>
+        <span aria-live="polite" className="sr-only">
+          {copied ? "Copied to clipboard" : ""}
+        </span>
+      </button>
+    );
+  }
+
   return (
     <button
       type="button"