radiant-docs 0.1.66 → 0.1.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "radiant-docs",
-  "version": "0.1.66",
+  "version": "0.1.67",
   "description": "CLI tool for previewing Radiant documentation locally",
   "type": "module",
   "bin": {

package/template/astro.config.mjs

@@ -311,6 +311,24 @@ function resolveDocsSiteConfig() {
 const docsSiteConfig = resolveDocsSiteConfig();
 globalThis.__RADIANT_DOCS_BASE_PATH__ = docsSiteConfig.base;
 
+function isInternalDocsRoutePathname(pathname) {
+  const basePath = docsSiteConfig.base === "/" ? "" : docsSiteConfig.base;
+  const relativePath =
+    basePath && pathname.startsWith(`${basePath}/`)
+      ? pathname.slice(basePath.length)
+      : pathname;
+
+  return relativePath === "/-" || relativePath.startsWith("/-/");
+}
+
+function shouldIncludeSitemapPage(page) {
+  try {
+    return !isInternalDocsRoutePathname(new URL(page).pathname);
+  } catch {
+    return !page.startsWith("/-/");
+  }
+}
+
 const markdownProcessor = unified({
   remarkPlugins: [
     remarkGfm,
@@ -387,7 +405,9 @@ export default defineConfig({
     assetsPrefix: configuredAssetsPrefix,
   },
   integrations: [
-    sitemap(),
+    sitemap({
+      filter: shouldIncludeSitemapPage,
+    }),
     preact({
       compat: true,
     }),

package/template/package-lock.json

@@ -28,7 +28,7 @@
         "@fontsource-variable/source-serif-4": "^5.2.9",
         "@iconify-json/fluent": "^1.2.47",
         "@iconify-json/lucide": "^1.2.79",
-        "@iconify-json/simple-icons": "^1.2.69",
+        "@iconify-json/simple-icons": "^1.2.87",
         "@iconify/react": "^6.0.2",
         "@paper-design/shaders": "^0.0.76",
         "@preact/preset-vite": "^2.10.3",
@@ -2343,9 +2343,9 @@
       }
     },
     "node_modules/@iconify-json/simple-icons": {
-      "version": "1.2.69",
-      "resolved": "https://registry.npmjs.org/@iconify-json/simple-icons/-/simple-icons-1.2.69.tgz",
-      "integrity": "sha512-T/rhy5n7pzE0ZOxQVlF68SNPCYYjRBpddjgjrJO5WWVRG8es5BQmvxIE9kKF+t2hhPGvuGQFpXmUyqbOtnxirQ==",
+      "version": "1.2.87",
+      "resolved": "https://registry.npmjs.org/@iconify-json/simple-icons/-/simple-icons-1.2.87.tgz",
+      "integrity": "sha512-8YciStObhSji3OZFmWAWK6kBujyqO5bLCxeDwLxf3CR3F4PVelq7keC2LBvgTqviWzSTysj5/g4PCFLiAMVGsw==",
       "license": "CC0-1.0",
       "dependencies": {
         "@iconify/types": "*"

package/template/package.json

@@ -27,7 +27,7 @@
     "@fontsource-variable/source-serif-4": "^5.2.9",
     "@iconify-json/fluent": "^1.2.47",
     "@iconify-json/lucide": "^1.2.79",
-    "@iconify-json/simple-icons": "^1.2.69",
+    "@iconify-json/simple-icons": "^1.2.87",
     "@iconify/react": "^6.0.2",
     "@paper-design/shaders": "^0.0.76",
     "@preact/preset-vite": "^2.10.3",

package/template/src/components/MdxPage.astro

@@ -19,6 +19,7 @@ import ComponentPreview from "./user/ComponentPreview.astro";
 import ComponentPreviewBlock from "./user/ComponentPreviewBlock.astro";
 import type { MdxRoute, Route } from "../lib/routes";
 import PagePagination from "./PagePagination.astro";
+import PageAiActions from "./PageAiActions.astro";
 import { PREVIEW_HEADING_ID_PREFIX } from "../lib/mdx/rehype-prefix-preview-heading-ids";
 
 interface Props {
@@ -67,10 +68,19 @@ const tocHeadings = headings.filter(
 <Layout pageTitle={title} pageDescription={description}>
   <div class="flex w-full min-w-0 justify-between gap-x-10">
     <div class="mx-auto max-w-3xl w-full">
-      <header class="mb-6">
-        <h1 class="rd-document-heading text-4xl font-semibold tracking-tight">
+      <header
+        class="mb-8 flex flex-col gap-4 sm:flex-row sm:items-end sm:justify-between"
+      >
+        <h1
+          class="rd-document-heading min-w-0 text-4xl font-semibold tracking-tight"
+        >
           {title}
         </h1>
+        <PageAiActions
+          title={title}
+          routeSlug={route.slug}
+          description={description}
+        />
       </header>
       <article class="prose-rules">
         <Content components={components} />

package/template/src/components/OpenApiPage.astro

@@ -10,6 +10,7 @@ import ResponseFieldTree from "./endpoint/ResponseFieldTree.astro";
 import PlaygroundBar from "./endpoint/PlaygroundBar.astro";
 import PlaygroundForm from "./endpoint/PlaygroundForm.astro";
 import PlaygroundButton from "./endpoint/PlaygroundButton.astro";
+import PageAiActions from "./PageAiActions.astro";
 import { getConfig } from "../lib/validation";
 import {
   getOpenApiOperationDoc,
@@ -59,11 +60,20 @@ const snippetStickyClass = hasTopbarNavigationTabs
 ---
 
 <Layout pageTitle={title}>
-  <article>
-    <header class="mb-6">
-      <h1 class="rd-document-heading text-4xl font-semibold tracking-tight">
+  <article class="mx-auto w-full max-w-7xl">
+    <header
+      class="mb-8 flex flex-col gap-4 sm:flex-row sm:items-end sm:justify-between"
+    >
+      <h1
+        class="rd-document-heading min-w-0 text-4xl font-semibold tracking-tight"
+      >
         {title}
       </h1>
+      <PageAiActions
+        title={title}
+        routeSlug={route.slug}
+        description={description}
+      />
     </header>
     <div class="flex flex-row-reverse justify-between gap-6 w-full">
       <aside class="flex-1 min-w-0 hidden xl:block">

package/template/src/components/PageAiActions.astro

@@ -0,0 +1,715 @@
+---
+import { Buffer } from "node:buffer";
+import Icon from "./ui/Icon.astro";
+import { prependBasePath } from "../lib/base-path";
+
+interface Props {
+  title: string;
+  routeSlug: string;
+  description?: string;
+}
+
+type MenuItem = {
+  type: "button" | "link";
+  icon: string;
+  title: string;
+  description: string;
+  href?: string;
+  target?: string;
+  rel?: string;
+  external?: boolean;
+  copyMarkdown?: boolean;
+  copyMcp?: string;
+  hasActionLabel?: boolean;
+  openApp?: string;
+};
+
+function getMarkdownPathForSlug(routeSlug: string): string {
+  const normalizedSlug = routeSlug.replace(/^\/+/, "").replace(/\/+$/, "");
+  return normalizedSlug ? `/${normalizedSlug}.md` : "/index.md";
+}
+
+function getPagePathForSlug(routeSlug: string): string {
+  const normalizedSlug = routeSlug.replace(/^\/+/, "").replace(/\/+$/, "");
+  return normalizedSlug ? `/${normalizedSlug}` : "/";
+}
+
+function getInstallNameFromUrl(url: string): string {
+  try {
+    const hostname = new URL(url).hostname;
+    const normalized = hostname
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 48);
+
+    return normalized || "docs";
+  } catch {
+    return "docs";
+  }
+}
+
+function getCursorInstallNameFromUrl(url: string): string {
+  try {
+    return new URL(url).hostname.toLowerCase() || "docs";
+  } catch {
+    return "docs";
+  }
+}
+
+function toBase64(value: string): string {
+  return Buffer.from(value, "utf8").toString("base64");
+}
+
+function buildAssistantPrompt(pageUrl: string): string {
+  return `Read from ${pageUrl} so I can ask questions about it.`;
+}
+
+const { routeSlug } = Astro.props;
+const parsedOrgTier = Number.parseInt(
+  (import.meta.env.ORG_TIER ?? "1").toString(),
+  10,
+);
+const orgTier =
+  Number.isFinite(parsedOrgTier) && parsedOrgTier > 0 ? parsedOrgTier : 1;
+const isDev = import.meta.env.DEV;
+const mcpEnabled = isDev || orgTier >= 3;
+const markdownPath = prependBasePath(getMarkdownPathForSlug(routeSlug));
+const pagePath = prependBasePath(getPagePathForSlug(routeSlug));
+const pageUrl = new URL(pagePath, Astro.site ?? Astro.url).toString();
+const mcpPath = prependBasePath("/_mcp/server");
+const mcpUrl = new URL(mcpPath, Astro.site ?? Astro.url).toString();
+const installName = getInstallNameFromUrl(mcpUrl);
+const cursorInstallName = getCursorInstallNameFromUrl(mcpUrl);
+const cursorServerConfig = {
+  name: cursorInstallName,
+  url: mcpUrl,
+};
+const cursorInstallUrl = `cursor://anysphere.cursor-deeplink/mcp/install?name=${encodeURIComponent(cursorInstallName)}&config=${encodeURIComponent(toBase64(JSON.stringify(cursorServerConfig)))}`;
+const prompt = buildAssistantPrompt(pageUrl);
+const chatGptUrl = `https://chatgpt.com/?q=${encodeURIComponent(prompt)}`;
+const claudeUrl = `https://claude.ai/new?q=${encodeURIComponent(prompt)}`;
+
+const menuItemClass =
+  "group cursor-pointer flex w-full items-center gap-2.5 rounded-lg p-1.5 text-left transition-colors hover:bg-neutral-100/80 focus-visible:outline focus-visible:outline-2 focus-visible:outline-neutral-900 dark:hover:bg-neutral-900/80 dark:focus-visible:outline-white";
+const menuIconClass =
+  "inline-flex size-[32px] shrink-0 items-center justify-center rounded-sm border border-neutral-900/10 text-neutral-500 dark:border-white/6 dark:text-neutral-400";
+const menuTitleClass =
+  "block text-sm font-medium leading-5 text-neutral-900 dark:text-white";
+const menuDescriptionClass =
+  "block text-xs leading-4 text-neutral-500 dark:text-neutral-400";
+
+const menuItems: MenuItem[] = [
+  {
+    type: "button",
+    icon: "lucide:copy",
+    title: "Copy page",
+    description: "Copy page as Markdown for LLMs",
+    copyMarkdown: true,
+    hasActionLabel: true,
+  },
+  {
+    type: "link",
+    icon: "simple-icons:markdown",
+    title: "View as Markdown",
+    description: "Open the Markdown version of this page",
+    href: markdownPath,
+    target: "_blank",
+    rel: "noopener noreferrer",
+    external: true,
+  },
+  {
+    type: "link",
+    icon: "simple-icons:openai",
+    title: "Open in ChatGPT",
+    description: "Ask questions about this page",
+    href: chatGptUrl,
+    target: "_blank",
+    rel: "noopener noreferrer",
+    external: true,
+  },
+  {
+    type: "link",
+    icon: "simple-icons:claude",
+    title: "Open in Claude",
+    description: "Ask questions about this page",
+    href: claudeUrl,
+    target: "_blank",
+    rel: "noopener noreferrer",
+    external: true,
+  },
+  ...(mcpEnabled
+    ? [
+        {
+          type: "button",
+          icon: "lucide:terminal",
+          title: "Copy MCP install command",
+          description: "Copy command to install MCP server",
+          copyMcp: "install",
+          hasActionLabel: true,
+        },
+        {
+          type: "link",
+          icon: "simple-icons:cursor",
+          title: "Connect to Cursor",
+          description: "Install MCP Server on Cursor",
+          href: cursorInstallUrl,
+          openApp: "cursor",
+          external: true,
+        },
+        {
+          type: "button",
+          icon: "simple-icons:claudecode",
+          title: "Connect to Claude Code",
+          description: "Copy command for Claude Code",
+          copyMcp: "claudeCode",
+          hasActionLabel: true,
+        },
+        {
+          type: "button",
+          icon: "custom:codex",
+          title: "Connect to Codex",
+          description: "Copy command for Codex",
+          copyMcp: "codexCli",
+          hasActionLabel: true,
+        },
+      ]
+    : []),
+];
+---
+
+<nav
+  class="relative flex w-max shrink-0 justify-end"
+  data-rd-page-actions
+  data-markdown-url={markdownPath}
+  data-mcp-url={mcpUrl}
+  data-install-name={installName}
+  aria-label="Page AI actions"
+>
+  <div class="relative inline-flex w-max shrink-0 flex-col items-end">
+    <div
+      class="inline-flex w-max shrink-0 overflow-hidden rounded-lg border-[0.5px] border-neutral-900/12 bg-neutral-50/50 text-sm text-neutral-700 shadow-[0_.5px_1px_rgba(0,0,0,0.15),0_5px_12px_-6px_rgba(0,0,0,0.08)] dark:border-white/6 dark:bg-(--rd-code-surface) dark:text-neutral-200 dark:shadow-[0_-.5px_1px_rgba(255,255,255,0.15),0_5px_12px_-6px_rgba(0,0,0,0.2)]"
+    >
+      <button
+        type="button"
+        class="cursor-pointer inline-flex h-8 shrink-0 items-center gap-1.5 whitespace-nowrap pl-2.5 pr-2 transition-colors hover:bg-white/80 hover:text-neutral-950 focus-visible:z-10 focus-visible:outline focus-visible:outline-2 focus-visible:outline-neutral-900 dark:hover:bg-white/6 dark:hover:text-white dark:focus-visible:outline-white"
+        data-rd-copy-markdown
+      >
+        <span
+          class="relative inline-flex size-3.5 shrink-0 items-center justify-center"
+        >
+          <Icon
+            name="lucide:copy"
+            class="size-3.5 origin-center scale-100 rotate-0 opacity-100 transition-all duration-250 ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform motion-reduce:transition-none"
+            data-rd-copy-icon
+            aria-hidden="true"
+          />
+          <Icon
+            name="lucide:check"
+            class="absolute size-3.5 stroke-3 origin-center scale-50 rotate-6 opacity-0 text-green-700/80 transition-all duration-250 ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform motion-reduce:transition-none dark:text-green-400/90"
+            data-rd-copy-check
+            aria-hidden="true"
+          />
+          <Icon
+            name="lucide:x"
+            class="absolute size-3.5 stroke-3 origin-center -rotate-6 scale-50 opacity-0 text-red-600/80 transition-all duration-250 ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform motion-reduce:transition-none dark:text-red-400/90"
+            data-rd-copy-error
+            aria-hidden="true"
+          />
+        </span>
+        <span data-rd-action-label>Copy page</span>
+      </button>
+
+      <button
+        type="button"
+        class="cursor-pointer inline-flex h-8 w-8 pr-0.5 items-center justify-center border-l-[0.5px] border-neutral-900/12 transition-colors hover:bg-white/80 hover:text-neutral-950 focus-visible:z-10 focus-visible:outline focus-visible:outline-2 focus-visible:outline-neutral-900 dark:border-white/6 dark:hover:bg-white/6 dark:hover:text-white dark:focus-visible:outline-white"
+        data-rd-page-actions-trigger
+        aria-expanded="false"
+        aria-haspopup="true"
+        aria-label="More page actions"
+      >
+        <Icon
+          name="lucide:chevron-down"
+          class="size-3.5 transition-transform"
+          aria-hidden="true"
+          data-rd-page-actions-chevron
+        />
+      </button>
+    </div>
+
+    <div
+      class="rd-page-actions-dropdown absolute left-0 right-auto top-full z-30 mt-1 w-max max-w-[calc(100vw-2rem)] rounded-xl border-[0.5px] border-neutral-200 bg-white p-1 text-neutral-700 shadow-2xl shadow-neutral-900/12 sm:left-auto sm:right-0 dark:border-neutral-800 dark:bg-(--rd-code-surface) dark:text-neutral-200 dark:shadow-black/40"
+      data-origin="responsive"
+      data-rd-page-actions-menu
+      hidden
+    >
+      {
+        menuItems.map((item) =>
+          item.type === "button" ? (
+            <button
+              type="button"
+              class={menuItemClass}
+              data-rd-copy-markdown={item.copyMarkdown ? true : undefined}
+              data-rd-copy-mcp={item.copyMcp}
+            >
+              <span class={menuIconClass}>
+                {item.copyMarkdown || item.copyMcp ? (
+                  <span class="relative inline-flex size-4 items-center justify-center">
+                    {item.icon === "custom:codex" ? (
+                      <svg
+                        xmlns="http://www.w3.org/2000/svg"
+                        viewBox="0 0 24 24"
+                        fill="currentColor"
+                        fill-rule="evenodd"
+                        class="size-4 origin-center scale-100 rotate-0 opacity-100 transition-all duration-250 ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform motion-reduce:transition-none"
+                        data-rd-copy-icon
+                        aria-hidden="true"
+                      >
+                        <path
+                          clip-rule="evenodd"
+                          d="M8.086.457a6.105 6.105 0 013.046-.415c1.333.153 2.521.72 3.564 1.7a.117.117 0 00.107.029c1.408-.346 2.762-.224 4.061.366l.063.03.154.076c1.357.703 2.33 1.77 2.918 3.198.278.679.418 1.388.421 2.126a5.655 5.655 0 01-.18 1.631.167.167 0 00.04.155 5.982 5.982 0 011.578 2.891c.385 1.901-.01 3.615-1.183 5.14l-.182.22a6.063 6.063 0 01-2.934 1.851.162.162 0 00-.108.102c-.255.736-.511 1.364-.987 1.992-1.199 1.582-2.962 2.462-4.948 2.451-1.583-.008-2.986-.587-4.21-1.736a.145.145 0 00-.14-.032c-.518.167-1.04.191-1.604.185a5.924 5.924 0 01-2.595-.622 6.058 6.058 0 01-2.146-1.781c-.203-.269-.404-.522-.551-.821a7.74 7.74 0 01-.495-1.283 6.11 6.11 0 01-.017-3.064.166.166 0 00.008-.074.115.115 0 00-.037-.064 5.958 5.958 0 01-1.38-2.202 5.196 5.196 0 01-.333-1.589 6.915 6.915 0 01.188-2.132c.45-1.484 1.309-2.648 2.577-3.493.282-.188.55-.334.802-.438.286-.12.573-.22.861-.304a.129.129 0 00.087-.087A6.016 6.016 0 015.635 2.31C6.315 1.464 7.132.846 8.086.457zm-.804 7.85a.848.848 0 00-1.473.842l1.694 2.965-1.688 2.848a.849.849 0 001.46.864l1.94-3.272a.849.849 0 00.007-.854l-1.94-3.393zm5.446 6.24a.849.849 0 000 1.695h4.848a.849.849 0 000-1.696h-4.848z"
+                        />
+                      </svg>
+                    ) : (
+                      <Icon
+                        name={item.copyMarkdown ? "lucide:copy" : item.icon}
+                        class="size-4 origin-center scale-100 rotate-0 opacity-100 transition-all duration-250 ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform motion-reduce:transition-none"
+                        data-rd-copy-icon
+                        aria-hidden="true"
+                      />
+                    )}
+                    <Icon
+                      name="lucide:check"
+                      class="absolute size-4 stroke-3 origin-center scale-50 rotate-6 opacity-0 text-green-700/80 transition-all duration-250 ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform motion-reduce:transition-none dark:text-green-400/90"
+                      data-rd-copy-check
+                      aria-hidden="true"
+                    />
+                    <Icon
+                      name="lucide:x"
+                      class="absolute size-4 stroke-3 origin-center -rotate-6 scale-50 opacity-0 text-red-600/80 transition-all duration-250 ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform motion-reduce:transition-none dark:text-red-400/90"
+                      data-rd-copy-error
+                      aria-hidden="true"
+                    />
+                  </span>
+                ) : item.icon === "custom:codex" ? (
+                  <svg
+                    xmlns="http://www.w3.org/2000/svg"
+                    viewBox="0 0 24 24"
+                    fill="currentColor"
+                    fill-rule="evenodd"
+                    class="size-4"
+                    aria-hidden="true"
+                  >
+                    <path
+                      clip-rule="evenodd"
+                      d="M8.086.457a6.105 6.105 0 013.046-.415c1.333.153 2.521.72 3.564 1.7a.117.117 0 00.107.029c1.408-.346 2.762-.224 4.061.366l.063.03.154.076c1.357.703 2.33 1.77 2.918 3.198.278.679.418 1.388.421 2.126a5.655 5.655 0 01-.18 1.631.167.167 0 00.04.155 5.982 5.982 0 011.578 2.891c.385 1.901-.01 3.615-1.183 5.14l-.182.22a6.063 6.063 0 01-2.934 1.851.162.162 0 00-.108.102c-.255.736-.511 1.364-.987 1.992-1.199 1.582-2.962 2.462-4.948 2.451-1.583-.008-2.986-.587-4.21-1.736a.145.145 0 00-.14-.032c-.518.167-1.04.191-1.604.185a5.924 5.924 0 01-2.595-.622 6.058 6.058 0 01-2.146-1.781c-.203-.269-.404-.522-.551-.821a7.74 7.74 0 01-.495-1.283 6.11 6.11 0 01-.017-3.064.166.166 0 00.008-.074.115.115 0 00-.037-.064 5.958 5.958 0 01-1.38-2.202 5.196 5.196 0 01-.333-1.589 6.915 6.915 0 01.188-2.132c.45-1.484 1.309-2.648 2.577-3.493.282-.188.55-.334.802-.438.286-.12.573-.22.861-.304a.129.129 0 00.087-.087A6.016 6.016 0 015.635 2.31C6.315 1.464 7.132.846 8.086.457zm-.804 7.85a.848.848 0 00-1.473.842l1.694 2.965-1.688 2.848a.849.849 0 001.46.864l1.94-3.272a.849.849 0 00.007-.854l-1.94-3.393zm5.446 6.24a.849.849 0 000 1.695h4.848a.849.849 0 000-1.696h-4.848z"
+                    />
+                  </svg>
+                ) : (
+                  <Icon name={item.icon} class="size-4" aria-hidden="true" />
+                )}
+              </span>
+              <span class="min-w-0 pr-3">
+                <span
+                  class={menuTitleClass}
+                  data-rd-action-label={item.hasActionLabel ? true : undefined}
+                >
+                  {item.title}
+                </span>
+                <span class={menuDescriptionClass}>{item.description}</span>
+              </span>
+            </button>
+          ) : (
+            <a
+              href={item.href}
+              target={item.target}
+              rel={item.rel}
+              class={menuItemClass}
+              data-rd-open-app={item.openApp}
+            >
+              <span class={menuIconClass}>
+                {item.icon === "custom:codex" ? (
+                  <svg
+                    xmlns="http://www.w3.org/2000/svg"
+                    viewBox="0 0 24 24"
+                    fill="currentColor"
+                    fill-rule="evenodd"
+                    class="size-4"
+                    aria-hidden="true"
+                  >
+                    <path
+                      clip-rule="evenodd"
+                      d="M8.086.457a6.105 6.105 0 013.046-.415c1.333.153 2.521.72 3.564 1.7a.117.117 0 00.107.029c1.408-.346 2.762-.224 4.061.366l.063.03.154.076c1.357.703 2.33 1.77 2.918 3.198.278.679.418 1.388.421 2.126a5.655 5.655 0 01-.18 1.631.167.167 0 00.04.155 5.982 5.982 0 011.578 2.891c.385 1.901-.01 3.615-1.183 5.14l-.182.22a6.063 6.063 0 01-2.934 1.851.162.162 0 00-.108.102c-.255.736-.511 1.364-.987 1.992-1.199 1.582-2.962 2.462-4.948 2.451-1.583-.008-2.986-.587-4.21-1.736a.145.145 0 00-.14-.032c-.518.167-1.04.191-1.604.185a5.924 5.924 0 01-2.595-.622 6.058 6.058 0 01-2.146-1.781c-.203-.269-.404-.522-.551-.821a7.74 7.74 0 01-.495-1.283 6.11 6.11 0 01-.017-3.064.166.166 0 00.008-.074.115.115 0 00-.037-.064 5.958 5.958 0 01-1.38-2.202 5.196 5.196 0 01-.333-1.589 6.915 6.915 0 01.188-2.132c.45-1.484 1.309-2.648 2.577-3.493.282-.188.55-.334.802-.438.286-.12.573-.22.861-.304a.129.129 0 00.087-.087A6.016 6.016 0 015.635 2.31C6.315 1.464 7.132.846 8.086.457zm-.804 7.85a.848.848 0 00-1.473.842l1.694 2.965-1.688 2.848a.849.849 0 001.46.864l1.94-3.272a.849.849 0 00.007-.854l-1.94-3.393zm5.446 6.24a.849.849 0 000 1.695h4.848a.849.849 0 000-1.696h-4.848z"
+                    />
+                  </svg>
+                ) : (
+                  <Icon name={item.icon} class="size-4" aria-hidden="true" />
+                )}
+              </span>
+              <span class="min-w-0 pr-3">
+                <span class={menuTitleClass}>
+                  {item.title}
+                  {item.external && (
+                    <Icon
+                      name="lucide:arrow-up-right"
+                      class="ml-[3px] mb-[3px] inline size-3 self-start"
+                      aria-hidden="true"
+                    />
+                  )}
+                </span>
+                <span class={menuDescriptionClass}>{item.description}</span>
+              </span>
+            </a>
+          ),
+        )
+      }
+    </div>
+  </div>
+</nav>
+
+<style>
+  [data-rd-page-actions] {
+    --dropdown-open-dur: 250ms;
+    --dropdown-close-dur: 150ms;
+    --dropdown-pre-scale: 0.97;
+    --dropdown-closing-scale: 0.99;
+    --dropdown-ease: cubic-bezier(0.22, 1, 0.36, 1);
+  }
+
+  .rd-page-actions-dropdown {
+    transform-origin: top right;
+    transform: scale(var(--dropdown-pre-scale));
+    opacity: 0;
+    pointer-events: none;
+    transition:
+      transform var(--dropdown-open-dur) var(--dropdown-ease),
+      opacity var(--dropdown-open-dur) var(--dropdown-ease);
+    will-change: transform, opacity;
+  }
+
+  .rd-page-actions-dropdown[data-origin="top-left"] {
+    transform-origin: top left;
+  }
+
+  .rd-page-actions-dropdown[data-origin="top-center"] {
+    transform-origin: top center;
+  }
+
+  .rd-page-actions-dropdown[data-origin="top-right"] {
+    transform-origin: top right;
+  }
+
+  .rd-page-actions-dropdown[data-origin="responsive"] {
+    transform-origin: top left;
+  }
+
+  @media (min-width: 640px) {
+    .rd-page-actions-dropdown[data-origin="responsive"] {
+      transform-origin: top right;
+    }
+  }
+
+  .rd-page-actions-dropdown.is-open {
+    transform: scale(1);
+    opacity: 1;
+    pointer-events: auto;
+  }
+
+  .rd-page-actions-dropdown.is-closing {
+    transform: scale(var(--dropdown-closing-scale));
+    opacity: 0;
+    pointer-events: none;
+    transition:
+      transform var(--dropdown-close-dur) var(--dropdown-ease),
+      opacity var(--dropdown-close-dur) var(--dropdown-ease);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .rd-page-actions-dropdown {
+      transition: none !important;
+    }
+  }
+</style>
+
+<script is:inline data-astro-rerun>
+  (() => {
+    const script = document.currentScript;
+    let root = script?.previousElementSibling;
+    while (
+      root &&
+      (!(root instanceof HTMLElement) ||
+        !root.hasAttribute("data-rd-page-actions"))
+    ) {
+      root = root.previousElementSibling;
+    }
+
+    if (
+      !(root instanceof HTMLElement) ||
+      root.dataset.pageActionsBound === "true"
+    ) {
+      return;
+    }
+    root.dataset.pageActionsBound = "true";
+
+    const trigger = root.querySelector("[data-rd-page-actions-trigger]");
+    const menu = root.querySelector("[data-rd-page-actions-menu]");
+    const chevron = root.querySelector("[data-rd-page-actions-chevron]");
+    const markdownUrl = root.dataset.markdownUrl || "/index.md";
+    const mcpUrl = root.dataset.mcpUrl || "/_mcp/server";
+    const installName = root.dataset.installName || "docs";
+    const closeDurationMs = 150;
+    const copyFeedbackDurationMs = 1400;
+    let closeTimeout;
+    let mcpMetadataPromise;
+    const copyFeedbackTimeouts = new WeakMap();
+
+    function fallbackCopy(text) {
+      const textarea = document.createElement("textarea");
+      textarea.value = text;
+      textarea.setAttribute("readonly", "");
+      textarea.style.position = "fixed";
+      textarea.style.opacity = "0";
+      document.body.appendChild(textarea);
+      textarea.select();
+      const copied = document.execCommand("copy");
+      document.body.removeChild(textarea);
+      return copied;
+    }
+
+    async function copyToClipboard(text) {
+      try {
+        if (navigator.clipboard?.writeText) {
+          await navigator.clipboard.writeText(text);
+          return true;
+        }
+      } catch {
+        // Fallback below when clipboard API is unavailable or blocked.
+      }
+
+      return fallbackCopy(text);
+    }
+
+    function setExpanded(nextExpanded) {
+      if (!(trigger instanceof HTMLElement)) return;
+      trigger.setAttribute("aria-expanded", String(nextExpanded));
+      if (chevron instanceof HTMLElement) {
+        chevron.classList.toggle("rotate-180", nextExpanded);
+      }
+    }
+
+    function openMenu() {
+      if (!(menu instanceof HTMLElement)) return;
+      window.clearTimeout(closeTimeout);
+      menu.hidden = false;
+      menu.classList.remove("is-closing");
+      menu.classList.add("is-open");
+      setExpanded(true);
+    }
+
+    function closeMenu() {
+      if (!(menu instanceof HTMLElement) || menu.hidden) return;
+      window.clearTimeout(closeTimeout);
+      menu.classList.remove("is-open");
+      menu.classList.add("is-closing");
+      setExpanded(false);
+      closeTimeout = window.setTimeout(() => {
+        menu.classList.remove("is-closing");
+        menu.hidden = true;
+      }, closeDurationMs);
+    }
+
+    function toggleMenu() {
+      if (!(menu instanceof HTMLElement)) return;
+      if (menu.hidden || !menu.classList.contains("is-open")) {
+        openMenu();
+      } else {
+        closeMenu();
+      }
+    }
+
+    function setLabelFeedback(button, copiedText = "Copied") {
+      const label = button.querySelector("[data-rd-action-label]");
+      if (!(label instanceof HTMLElement)) return;
+
+      const defaultText = label.dataset.defaultLabel || label.textContent || "";
+      label.dataset.defaultLabel = defaultText;
+      label.textContent = copiedText;
+      window.setTimeout(() => {
+        label.textContent = label.dataset.defaultLabel || defaultText;
+      }, copyFeedbackDurationMs);
+    }
+
+    function setCopyIconState(button, state) {
+      const copyIcon = button.querySelector("[data-rd-copy-icon]");
+      const checkIcon = button.querySelector("[data-rd-copy-check]");
+      const errorIcon = button.querySelector("[data-rd-copy-error]");
+
+      if (!copyIcon || !checkIcon || !errorIcon) return false;
+
+      const showCopy = () => {
+        copyIcon.classList.remove("scale-50", "opacity-0", "-rotate-6");
+        copyIcon.classList.add("scale-100", "opacity-100", "rotate-0");
+      };
+
+      const hideCopy = () => {
+        copyIcon.classList.add("scale-50", "opacity-0", "-rotate-6");
+        copyIcon.classList.remove("scale-100", "opacity-100", "rotate-0");
+      };
+
+      const showStatusIcon = (icon) => {
+        icon.classList.remove("scale-50", "opacity-0", "rotate-6", "-rotate-6");
+        icon.classList.add("scale-110", "opacity-100", "rotate-0");
+      };
+
+      const hideStatusIcon = (icon, rotationClass) => {
+        icon.classList.remove("scale-110", "opacity-100", "rotate-0");
+        icon.classList.add("scale-50", "opacity-0", rotationClass);
+      };
+
+      if (state === "success") {
+        hideCopy();
+        showStatusIcon(checkIcon);
+        hideStatusIcon(errorIcon, "-rotate-6");
+        return true;
+      }
+
+      if (state === "error") {
+        hideCopy();
+        hideStatusIcon(checkIcon, "rotate-6");
+        showStatusIcon(errorIcon);
+        return true;
+      }
+
+      showCopy();
+      hideStatusIcon(checkIcon, "rotate-6");
+      hideStatusIcon(errorIcon, "-rotate-6");
+      return true;
+    }
+
+    function setCopyFeedback(button, state, fallbackText) {
+      if (setCopyIconState(button, state)) {
+        const existingTimeout = copyFeedbackTimeouts.get(button);
+        if (existingTimeout) window.clearTimeout(existingTimeout);
+
+        const timeout = window.setTimeout(() => {
+          setCopyIconState(button, "idle");
+          copyFeedbackTimeouts.delete(button);
+        }, copyFeedbackDurationMs);
+        copyFeedbackTimeouts.set(button, timeout);
+        return;
+      }
+
+      setLabelFeedback(
+        button,
+        fallbackText || (state === "error" ? "Failed" : "Copied"),
+      );
+    }
+
+    function getTomlServerKey() {
+      return (
+        installName.replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "") ||
+        "docs"
+      );
+    }
+
+    function buildFallbackMcpMetadata() {
+      return {
+        usage: {
+          install: `npx add-mcp ${mcpUrl}`,
+          claudeCode: `claude mcp add --transport http ${installName} ${mcpUrl}`,
+          codexCli: `codex mcp add ${installName} --url ${mcpUrl}`,
+          cursor: `Add "${mcpUrl}" to your MCP server configuration`,
+          codex: `[mcp_servers.${getTomlServerKey()}]\nurl = "${mcpUrl}"`,
+        },
+      };
+    }
+
+    async function getMcpMetadata() {
+      if (!mcpMetadataPromise) {
+        mcpMetadataPromise = fetch(mcpUrl, {
+          headers: { Accept: "application/json" },
+        })
+          .then((response) => {
+            if (!response.ok) throw new Error("MCP metadata request failed");
+            return response.json();
+          })
+          .catch(() => buildFallbackMcpMetadata());
+      }
+
+      return mcpMetadataPromise;
+    }
+
+    async function copyMarkdown(button) {
+      const response = await fetch(markdownUrl, {
+        headers: { Accept: "text/markdown,text/plain;q=0.9,*/*;q=0.1" },
+      });
+      if (!response.ok) {
+        throw new Error("Markdown request failed");
+      }
+
+      const text = await response.text();
+      const copied = await copyToClipboard(text);
+      if (!copied) throw new Error("Clipboard write failed");
+      setCopyFeedback(button, "success");
+    }
+
+    async function copyMcpUsage(button) {
+      const key = button.getAttribute("data-rd-copy-mcp");
+      const metadata = await getMcpMetadata();
+      const usage = metadata?.usage || buildFallbackMcpMetadata().usage;
+      const fallbackUsage = buildFallbackMcpMetadata().usage;
+      const usageKey = key && key in fallbackUsage ? key : "cursor";
+      const value = usage[usageKey] || fallbackUsage[usageKey] || mcpUrl;
+
+      const copied = await copyToClipboard(value || mcpUrl);
+      if (!copied) throw new Error("Clipboard write failed");
+      setCopyFeedback(button, "success");
+    }
+
+    trigger?.addEventListener("click", (event) => {
+      event.stopPropagation();
+      toggleMenu();
+    });
+
+    menu?.addEventListener("click", (event) => {
+      event.stopPropagation();
+    });
+
+    document.addEventListener("click", (event) => {
+      if (!root.contains(event.target)) closeMenu();
+    });
+
+    document.addEventListener("keydown", (event) => {
+      if (event.key === "Escape") closeMenu();
+    });
+
+    root.querySelectorAll("[data-rd-copy-markdown]").forEach((button) => {
+      if (!(button instanceof HTMLButtonElement)) return;
+      button.addEventListener("click", async () => {
+        try {
+          await copyMarkdown(button);
+        } catch {
+          setCopyFeedback(button, "error", "Failed");
+        }
+      });
+    });
+
+    root.querySelectorAll("[data-rd-copy-mcp]").forEach((button) => {
+      if (!(button instanceof HTMLButtonElement)) return;
+      button.addEventListener("click", async () => {
+        try {
+          await copyMcpUsage(button);
+        } catch {
+          setCopyFeedback(button, "error", "Failed");
+        }
+      });
+    });
+
+    root.querySelectorAll("[data-rd-open-app]").forEach((link) => {
+      if (!(link instanceof HTMLAnchorElement)) return;
+      link.addEventListener("click", () => {
+        closeMenu();
+      });
+    });
+  })();
+</script>

package/template/src/layouts/Layout.astro

@@ -75,6 +75,8 @@ const navigationTabs = config.navigation.tabs as
 const hasNavigationTabs =
   Array.isArray(navigationTabs?.items) && navigationTabs.items.length > 0;
 const tabsPresentation = navigationTabs?.presentation ?? "topbar";
+const hasTopbarNavigationTabs =
+  hasNavigationTabs && tabsPresentation === "topbar";
 ---
 
 <!doctype html>
@@ -356,7 +358,10 @@ const tabsPresentation = navigationTabs?.presentation ?? "topbar";
 
     <!-- Main Content -->
     <div
-      class="mx-1 mt-1 px-4 sm:px-6 lg:pl-[calc(288px+32px)] pt-16 lg:pr-8 bg-background"
+      class:list={[
+        "mx-1 mt-1 px-4 sm:px-6 lg:pl-[calc(288px+32px)] pt-16 lg:pr-8 bg-background",
+        hasTopbarNavigationTabs && "lg:pt-[108px]",
+      ]}
     >
       <main class="mx-auto pt-16 pb-20 min-h-[calc(100vh-64px)]">
         <slot />

package/template/src/lib/ai-artifacts.ts

@@ -9,6 +9,7 @@ import {
   type MdxRoute,
   type OpenApiRoute,
 } from "./routes";
+import { parseOpenApiEndpoint } from "./utils";
 import {
   getOpenApiOperationDoc,
   OPENAPI_REQUEST_SECTION_LABELS,
@@ -18,10 +19,19 @@ import {
   type OpenApiRequestSectionVariantData,
 } from "./openapi/operation-doc";
 import { resolvePageDescription } from "./page-description";
-import { getConfig } from "./validation";
+import {
+  getConfig,
+  type DocsConfig,
+  type NavGroup,
+  type NavMenu,
+  type NavOpenApi,
+  type NavOpenApiPage,
+  type NavPage,
+} from "./validation";
 
 const DOCS_ROOT = path.join(process.cwd(), "src/content/docs");
 const MAX_DESCRIPTION_LENGTH = 300;
+const PRO_TIER = 3;
 
 const OPENAPI_SPEC_EXTENSIONS = new Set([".json", ".yaml", ".yml"]);
 
@@ -29,6 +39,7 @@ export const MARKDOWN_CONTENT_TYPE = "text/markdown; charset=utf-8";
 export const PLAIN_TEXT_CONTENT_TYPE = "text/plain; charset=utf-8";
 
 export type AiMarkdownPage = {
+  routeIdentity?: string;
   filePath: string;
   routeSlug?: string;
   title: string;
@@ -90,6 +101,24 @@ function buildPublicUrl(pathname: string): string {
   return new URL(publicPath, siteOrigin).toString();
 }
 
+function getOrgTier(): number {
+  const parsed = Number.parseInt((process.env.ORG_TIER ?? "1").trim(), 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 1;
+}
+
+function formatMcpSection(): string[] {
+  if (getOrgTier() < PRO_TIER) return [];
+
+  return [
+    "## MCP",
+    "",
+    "This documentation exposes a read-only MCP server for AI agents:",
+    "",
+    `- MCP server: ${buildPublicUrl("/_mcp/server")}`,
+    "- Tool: searchDocs(query)",
+  ];
+}
+
 function getMarkdownPathForSlug(routeSlug: string): string {
   const normalizedSlug = routeSlug.replace(/^\/+/, "").replace(/\/+$/, "");
   return normalizedSlug ? `/${normalizedSlug}.md` : "/index.md";
@@ -142,19 +171,23 @@ async function getMdxEntryByFilePath(filePath: string) {
 async function createMarkdownPage(args: {
   filePath: string;
   routeSlug?: string;
+  routeIdentity?: string;
   title?: string;
   markdownPath?: string;
   canonicalPath?: string;
 }): Promise<AiMarkdownPage> {
   const entry = await getMdxEntryByFilePath(args.filePath);
   if (!entry) {
-    throw new Error(`Could not find content collection entry for "${args.filePath}".`);
+    throw new Error(
+      `Could not find content collection entry for "${args.filePath}".`,
+    );
   }
 
   const { sourcePath, source } = await readMdxSource(args.filePath);
   const routeSlug = args.routeSlug ?? "";
   const markdownPath = args.markdownPath ?? getMarkdownPathForSlug(routeSlug);
-  const canonicalPath = args.canonicalPath ?? getCanonicalPathForSlug(routeSlug);
+  const canonicalPath =
+    args.canonicalPath ?? getCanonicalPathForSlug(routeSlug);
   const title =
     args.title ??
     resolveMdxPageTitle({
@@ -164,6 +197,7 @@ async function createMarkdownPage(args: {
   const config = await getConfig();
 
   return {
+    routeIdentity: args.routeIdentity,
     filePath: normalizeDocsRootRelativePath(args.filePath),
     routeSlug,
     title,
@@ -205,6 +239,7 @@ export async function getLlmsListedMarkdownPages(): Promise<AiMarkdownPage[]> {
       await createMarkdownPage({
         filePath: config.home,
         routeSlug: "",
+        routeIdentity: homeRoute?.routeIdentity,
         title: homeRoute?.title,
         markdownPath: "/index.md",
         canonicalPath: "/",
@@ -277,6 +312,234 @@ function formatDocsListItem(page: AiMarkdownPage): string {
   return `- [${page.title}](${page.markdownUrl})${description}`;
 }
 
+type LlmsTxtSection = {
+  title: string;
+  pages: AiMarkdownPage[];
+};
+
+type LlmsNavPageItem = string | NavPage | NavGroup | NavOpenApiPage;
+
+type LlmsNavigationContainer = {
+  pages?: LlmsNavPageItem[];
+  menu?: NavMenu;
+  openapi?: string | NavOpenApi;
+};
+
+function getAiMarkdownPageKey(page: AiMarkdownPage): string {
+  return page.routeIdentity ?? `${page.filePath}:${page.markdownUrl}`;
+}
+
+function buildLlmsSectionTitle(parts: string[]): string {
+  const title = parts
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .join(": ");
+
+  return title || "Docs";
+}
+
+function isNavPageItem(item: LlmsNavPageItem): item is string | NavPage {
+  return typeof item === "string" || "page" in item;
+}
+
+function isNavGroupItem(item: LlmsNavPageItem): item is NavGroup {
+  return typeof item !== "string" && "group" in item;
+}
+
+function isNavOpenApiPageItem(
+  item: LlmsNavPageItem,
+): item is NavOpenApiPage {
+  return typeof item !== "string" && "openapi" in item;
+}
+
+function getNavPageRouteIdentity(item: string | NavPage): string {
+  return `mdx:${typeof item === "string" ? item : item.page}`;
+}
+
+function getNavOpenApiPageRouteIdentity(item: NavOpenApiPage): string | null {
+  const parsedEndpoint = parseOpenApiEndpoint(item.openapi.endpoint);
+  if (!parsedEndpoint) return null;
+
+  return `openapi:${item.openapi.source}:${parsedEndpoint.method} ${parsedEndpoint.path}`;
+}
+
+function getNavOpenApiSource(openapi: string | NavOpenApi): string {
+  return typeof openapi === "string" ? openapi : openapi.source;
+}
+
+function getOpenApiEndpointKey(method: string, pathStr: string): string {
+  return `${method.toUpperCase()} ${pathStr.toLowerCase()}`;
+}
+
+function matchesOpenApiEndpointFilter(
+  route: OpenApiRoute,
+  endpoints: string[],
+): boolean {
+  const routeEndpointKey = getOpenApiEndpointKey(
+    route.openApiMethod,
+    route.openApiPath,
+  );
+
+  return endpoints.some((endpoint) => {
+    const parsedEndpoint = parseOpenApiEndpoint(endpoint);
+    if (!parsedEndpoint) return false;
+
+    return (
+      getOpenApiEndpointKey(parsedEndpoint.method, parsedEndpoint.path) ===
+      routeEndpointKey
+    );
+  });
+}
+
+function getOpenApiFileRouteIdentities(
+  openapi: string | NavOpenApi,
+  routes: Route[],
+): string[] {
+  const source = getNavOpenApiSource(openapi);
+  const include = typeof openapi === "string" ? undefined : openapi.include;
+  const exclude = typeof openapi === "string" ? undefined : openapi.exclude;
+
+  return routes
+    .filter((route): route is OpenApiRoute => {
+      if (route.type !== "openapi" || route.filePath !== source) return false;
+      if (include && !matchesOpenApiEndpointFilter(route, include)) {
+        return false;
+      }
+      if (exclude && matchesOpenApiEndpointFilter(route, exclude)) {
+        return false;
+      }
+
+      return true;
+    })
+    .map((route) => route.routeIdentity);
+}
+
+function buildLlmsTxtSections(args: {
+  config: DocsConfig;
+  pages: AiMarkdownPage[];
+  routes: Route[];
+}): LlmsTxtSection[] {
+  const pageByRouteIdentity = new Map(
+    args.pages
+      .filter((page) => page.routeIdentity)
+      .map((page) => [page.routeIdentity as string, page]),
+  );
+  const emittedPageKeys = new Set<string>();
+  const sections: LlmsTxtSection[] = [];
+
+  const appendSection = (titleParts: string[], routeIdentities: string[]) => {
+    const sectionPages: AiMarkdownPage[] = [];
+
+    for (const routeIdentity of routeIdentities) {
+      const page = pageByRouteIdentity.get(routeIdentity);
+      if (!page) continue;
+
+      const pageKey = getAiMarkdownPageKey(page);
+      if (emittedPageKeys.has(pageKey)) continue;
+
+      emittedPageKeys.add(pageKey);
+      sectionPages.push(page);
+    }
+
+    if (sectionPages.length === 0) return;
+
+    const title = buildLlmsSectionTitle(titleParts);
+    const existingSection = sections.find((section) => section.title === title);
+
+    if (existingSection) {
+      existingSection.pages.push(...sectionPages);
+      return;
+    }
+
+    sections.push({
+      title,
+      pages: sectionPages,
+    });
+  };
+
+  const collectPages = (items: LlmsNavPageItem[], titleParts: string[]) => {
+    let directRouteIdentities: string[] = [];
+    const flushDirectPages = () => {
+      appendSection(titleParts, directRouteIdentities);
+      directRouteIdentities = [];
+    };
+
+    for (const item of items) {
+      if (isNavPageItem(item)) {
+        directRouteIdentities.push(getNavPageRouteIdentity(item));
+        continue;
+      }
+
+      if (isNavOpenApiPageItem(item)) {
+        const routeIdentity = getNavOpenApiPageRouteIdentity(item);
+        if (routeIdentity) directRouteIdentities.push(routeIdentity);
+        continue;
+      }
+
+      if (isNavGroupItem(item)) {
+        flushDirectPages();
+        collectNavigationContainer(
+          { pages: item.pages },
+          [...titleParts, item.group],
+        );
+      }
+    }
+
+    flushDirectPages();
+  };
+
+  const collectNavigationContainer = (
+    container: LlmsNavigationContainer,
+    titleParts: string[],
+  ) => {
+    if (container.pages) {
+      collectPages(container.pages, titleParts);
+    }
+
+    if (container.openapi) {
+      appendSection(
+        titleParts.length ? titleParts : ["API Reference"],
+        getOpenApiFileRouteIdentities(container.openapi, args.routes),
+      );
+    }
+
+    if (container.menu) {
+      for (const menuItem of container.menu.items) {
+        collectNavigationContainer(menuItem, [...titleParts, menuItem.label]);
+      }
+    }
+  };
+
+  const navigation = args.config.navigation;
+
+  if (navigation.pages) {
+    collectPages(navigation.pages, []);
+  } else if (navigation.menu) {
+    collectNavigationContainer({ menu: navigation.menu }, []);
+  } else if (navigation.openapi) {
+    collectNavigationContainer({ openapi: navigation.openapi }, [
+      "API Reference",
+    ]);
+  } else if (navigation.tabs) {
+    for (const tabItem of navigation.tabs.items) {
+      collectNavigationContainer(tabItem, [tabItem.label]);
+    }
+  }
+
+  const remainingPages = args.pages.filter(
+    (page) => !emittedPageKeys.has(getAiMarkdownPageKey(page)),
+  );
+
+  if (remainingPages.length > 0) {
+    sections.push({
+      title: sections.length ? "Additional Docs" : "Docs",
+      pages: remainingPages,
+    });
+  }
+
+  return sections;
+}
+
 function normalizeLocalOpenApiSource(source: string): string {
   return normalizeDocsRootRelativePath(source);
 }
@@ -297,7 +560,9 @@ function getOpenApiSpecLabel(source: string): string {
   if (isRemoteUrl(source)) {
     try {
       const url = new URL(source);
-      return path.posix.basename(url.pathname).replace(/\.[^.]+$/, "") || source;
+      return (
+        path.posix.basename(url.pathname).replace(/\.[^.]+$/, "") || source
+      );
     } catch {
       return source;
     }
@@ -344,7 +609,9 @@ function createOpenApiSpecArtifact(source: string): OpenApiSpecArtifact | null {
   };
 }
 
-export async function getOpenApiSpecArtifacts(): Promise<OpenApiSpecArtifact[]> {
+export async function getOpenApiSpecArtifacts(): Promise<
+  OpenApiSpecArtifact[]
+> {
   const routes = await getAllRoutes();
   const sources = new Set(
     routes
@@ -566,10 +833,7 @@ function getResponseContentTypes(response: any): string[] {
   return Object.keys(content);
 }
 
-function appendOpenApiResponsesMarkdown(
-  lines: string[],
-  responses: unknown,
-) {
+function appendOpenApiResponsesMarkdown(lines: string[], responses: unknown) {
   if (!responses || typeof responses !== "object") return;
 
   const responseEntries = Object.entries(responses).filter(
@@ -662,6 +926,7 @@ async function createOpenApiMarkdownPage(args: {
     args.canonicalPath ?? getCanonicalPathForSlug(routeSlug);
 
   return {
+    routeIdentity: args.route.routeIdentity,
     filePath: normalizeDocsRootRelativePath(args.route.filePath),
     routeSlug,
     title: args.route.title,
@@ -690,6 +955,7 @@ async function createRouteMarkdownPage(
     return createMarkdownPage({
       filePath: route.filePath,
       routeSlug: route.slug,
+      routeIdentity: route.routeIdentity,
       title: route.title,
       ...overrides,
     });
@@ -729,16 +995,30 @@ export async function getLlmsTxt(): Promise<string> {
 
   const config = await getConfig();
   const pages = await getLlmsListedMarkdownPages();
+  const routes = await getAllRoutes();
   const specs = await getOpenApiSpecArtifacts();
-  const lines = [`# ${config.title}`, "", "## Docs", ""];
-
-  lines.push(...pages.map(formatDocsListItem));
+  const sections = buildLlmsTxtSections({ config, pages, routes });
+  const lines = [`# ${config.title}`];
+
+  for (const section of sections) {
+    lines.push(
+      "",
+      `## ${section.title}`,
+      "",
+      ...section.pages.map(formatDocsListItem),
+    );
+  }
 
   const specsSection = formatOpenApiSpecsSection(specs);
   if (specsSection.length > 0) {
     lines.push("", ...specsSection);
   }
 
+  const mcpSection = formatMcpSection();
+  if (mcpSection.length > 0) {
+    lines.push("", ...mcpSection);
+  }
+
   return `${lines.join("\n").trimEnd()}\n`;
 }
 
@@ -785,7 +1065,9 @@ export async function getLlmsFullTxt(): Promise<string> {
       continue;
     }
 
-    sections.push(formatLlmsFullSpec(spec, await readOpenApiSpecArtifact(spec)));
+    sections.push(
+      formatLlmsFullSpec(spec, await readOpenApiSpecArtifact(spec)),
+    );
   }
 
   return `${sections.join("\n\n---\n\n").trimEnd()}\n`;

package/template/src/pages/{[...slug]/index.md.ts → [...slug].md.ts}

@@ -3,7 +3,7 @@ import {
   getMarkdownRoutePages,
   MARKDOWN_CONTENT_TYPE,
   type AiMarkdownPage,
-} from "../../lib/ai-artifacts";
+} from "../lib/ai-artifacts";
 
 export async function getStaticPaths() {
   const pages = await getMarkdownRoutePages();