nuxt-ai-ready 3.3.0 → 3.3.1

package/dist/chunks/agent-skills.mjs

@@ -2,7 +2,7 @@ import { createHash } from 'node:crypto';
 import { realpath, readFile, readdir } from 'node:fs/promises';
 import { join, resolve, isAbsolute, relative, sep } from 'node:path';
 import { parseDocument } from 'yaml';
-import { A as AGENT_SKILLS_SCHEMA } from '../shared/nuxt-ai-ready.BwnSMqRn.mjs';
+import { A as AGENT_SKILLS_SCHEMA } from '../shared/nuxt-ai-ready.CKXM1jnE.mjs';
 import 'node:module';
 import 'node:url';
 import '@nuxt/kit';

package/dist/chunks/prerender.mjs

@@ -6,7 +6,7 @@ import { resolveLocaleFromRoute } from 'nuxtseo-shared/i18n-runtime';
 import { createPrerenderFetch } from 'nuxtseo-shared/prerender';
 import { collectSitemap } from 'sitemapd/parse';
 import { parseURL, withLeadingSlash, joinURL, withBase } from 'ufo';
-import { l as logger, M as MARKDOWN_LINK_AVAILABILITY_FILE } from '../shared/nuxt-ai-ready.BwnSMqRn.mjs';
+import { l as logger, M as MARKDOWN_LINK_AVAILABILITY_FILE } from '../shared/nuxt-ai-ready.CKXM1jnE.mjs';
 import { toLogicalRoute, toDeployedRoute } from '../../dist/runtime/route-path.js';
 import { insertLlmsTxtDirective } from '../../dist/runtime/llms-txt-directive.js';
 import { absoluteSiteUrl } from '../../dist/runtime/markdown-links.js';
@@ -325,7 +325,7 @@ async function crawlSitemapEntries(state, nuxt, nitro, entries) {
   logger.debug(`Sitemap crawl complete: ${crawled} crawled, ${skipped} skipped`);
   return crawled;
 }
-async function crawlSitemapContent(state, nuxt, nitro, sitemapContent, seen = /* @__PURE__ */ new Set(), depth = 0, documents = /* @__PURE__ */ new Map()) {
+async function crawlSitemapContent(state, nuxt, nitro, sitemapContent, seen = /* @__PURE__ */ new Set(), depth = 0, documents = /* @__PURE__ */ new Map(), budget = { fetched: 0, warned: false }) {
   logger.debug(`Parsing sitemap XML (${sitemapContent.length} bytes)`);
   const result = await collectSitemap(sitemapContent);
   if (result._tag !== "document") {
@@ -334,24 +334,30 @@ async function crawlSitemapContent(state, nuxt, nitro, sitemapContent, seen = /*
     return 0;
   }
   if (result.document._tag === "index") {
-    if (depth >= 3 || seen.size >= 100) {
-      logger.warn("Sitemap crawl reached its document limit.");
-      return 0;
-    }
     let crawled = 0;
     const origin = new URL(state.siteInfo?.url || "http://localhost").origin;
     for (const entry of result.document.entries) {
       if (parsePrerenderRoute(entry.loc, nitro.options.baseURL)._tag === "Invalid")
         continue;
       const url = new URL(entry.loc, origin);
-      if (url.origin !== origin || seen.has(url.href))
+      if (url.origin !== origin)
+        continue;
+      const documentKey = toLogicalRoute(url.pathname, nitro.options.baseURL);
+      const localDocument = documents.get(documentKey);
+      const identity = localDocument ? `local:${documentKey}` : url.href;
+      if (seen.has(identity))
+        continue;
+      if (!localDocument && (depth >= 3 || budget.fetched >= 100)) {
+        if (!budget.warned) {
+          logger.warn("Sitemap crawl reached its document limit.");
+          budget.warned = true;
+        }
         continue;
-      if (seen.size >= 100) {
-        logger.warn("Sitemap crawl reached its document limit.");
-        break;
       }
-      seen.add(url.href);
-      const content = documents.get(toLogicalRoute(url.pathname, nitro.options.baseURL))?.() ?? await crawlerFetch(state)(`${url.pathname}${url.search}`, {
+      seen.add(identity);
+      if (!localDocument)
+        budget.fetched++;
+      const content = localDocument?.() ?? await crawlerFetch(state)(`${url.pathname}${url.search}`, {
         headers: { "x-nitro-prerender": url.pathname },
         retry: 0,
         signal: AbortSignal.timeout(PRERENDER_PAGE_TIMEOUT)
@@ -360,7 +366,7 @@ async function crawlSitemapContent(state, nuxt, nitro, sitemapContent, seen = /*
         return null;
       });
       if (content)
-        crawled += await crawlSitemapContent(state, nuxt, nitro, content, seen, depth + 1, documents);
+        crawled += await crawlSitemapContent(state, nuxt, nitro, content, seen, depth + Number(!localDocument), documents, budget);
     }
     return crawled;
   }
@@ -371,11 +377,12 @@ async function crawlSitemapContent(state, nuxt, nitro, sitemapContent, seen = /*
 async function crawlConfiguredSitemaps(state, nuxt, nitro, sitemap, documents = /* @__PURE__ */ new Map()) {
   const names = state.llmsTxtConfig?.sitemaps;
   const singleName = (sitemap.sitemapName || "sitemap.xml").replace(/\.xml$/, "");
-  const roots = sitemap.sitemaps && typeof sitemap.sitemaps === "object" ? Object.entries(sitemap.sitemaps).flatMap(([key, definition]) => {
+  const configured = sitemap.sitemaps && typeof sitemap.sitemaps === "object" ? sitemap.sitemaps : void 0;
+  const roots = configured ? Object.entries(configured).flatMap(([key, definition]) => {
     const name = (definition.sitemapName || key).replace(/\.xml$/, "");
     if (key === "index" || names !== void 0 && !names.includes(name))
       return [];
-    const route = definition._route || definition.route;
+    const route = definition._route || definition.route || (key === "chunks" ? configured.index?._route || configured.index?.route : void 0);
     return [route ? toLogicalRoute(route, nitro.options.baseURL) : joinURL(sitemap.sitemapsPathPrefix ?? "/__sitemap__/", `${name}.xml`)];
   }) : names !== void 0 && !names.includes(sitemap.sitemaps ? "chunks" : singleName) ? [] : [sitemap.sitemaps ? "/sitemap_index.xml" : `/${sitemap.sitemapName || "sitemap.xml"}`];
   for (const root of roots) {
@@ -590,7 +597,7 @@ function setupPrerenderHandler(options, dbPath, siteInfo, llmsTxtConfig, extras)
             if (target.origin !== origin)
               continue;
             const path = parsedTarget.route;
-            if (path.startsWith("/llms/") && path.endsWith(".txt"))
+            if (/^\/llms\/[^/]+\.txt$/i.test(path))
               pending.push(path);
           }
         }
@@ -637,4 +644,4 @@ function setupPrerenderHandler(options, dbPath, siteInfo, llmsTxtConfig, extras)
   });
 }
 
-export { createPrerenderDatabase, detectSitemapPrerender, setupPrerenderHandler };
+export { crawlConfiguredSitemaps, crawlSitemapContent, createPrerenderDatabase, detectSitemapPrerender, setupPrerenderHandler };

package/dist/cli.mjs

@@ -10,6 +10,240 @@ import 'node:module';
 import 'node:path';
 import 'node:url';
 
+const capabilities = ["llms", "api-catalog", "ai-catalog", "mcp", "skills"];
+function publicUrl(input, base) {
+  if (!URL.canParse(input, base))
+    return { _tag: "Err", message: "Use an absolute HTTP or HTTPS URL." };
+  const url = new URL(input, base);
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+    return { _tag: "Err", message: "Use an HTTP or HTTPS URL without credentials." };
+  url.hash = "";
+  return { _tag: "Ok", value: url };
+}
+function parseAuditOptions(input) {
+  const url = publicUrl(input.url);
+  if (url._tag === "Err")
+    return url;
+  const base = input.base || "/";
+  if (!base.startsWith("/") || base.startsWith("//") || /[?#\\]/.test(base))
+    return { _tag: "Err", message: "Use an application base path such as /docs/." };
+  const selected = [...new Set((input.capabilities || "").split(",").map((value) => value.trim()).filter(Boolean))];
+  const unknown = selected.filter((value) => !capabilities.includes(value));
+  if (unknown.length)
+    return { _tag: "Err", message: `Unknown capabilities: ${unknown.join(", ")}. Use ${capabilities.join(", ")}.` };
+  return { _tag: "Ok", value: { url: url.value.href, base: `${new URL(base, url.value).pathname.replace(/\/+$/, "")}/`, capabilities: selected } };
+}
+async function readDocument(url, accept, dependencies) {
+  const maxBytes = dependencies.maxBytes ?? 2 * 1024 * 1024;
+  const signal = AbortSignal.timeout(dependencies.timeoutMs ?? 1e4);
+  return Promise.resolve().then(async () => {
+    let current = url;
+    for (let redirects = 0; redirects <= 5; redirects++) {
+      const response = await dependencies.fetch(current, { headers: { accept }, redirect: "manual", signal });
+      if ([301, 302, 303, 307, 308].includes(response.status)) {
+        await response.body?.cancel();
+        const location = response.headers.get("location");
+        const next = location ? publicUrl(location, current) : { _tag: "Err", message: "Redirect has no Location header." };
+        if (next._tag === "Err")
+          return next;
+        current = next.value.href;
+        continue;
+      }
+      if (Number(response.headers.get("content-length")) > maxBytes) {
+        await response.body?.cancel();
+        return { _tag: "Err", message: `Response exceeds the ${maxBytes} byte limit.` };
+      }
+      const reader = response.body?.getReader();
+      const decoder = new TextDecoder();
+      let body = "";
+      let bytes = 0;
+      if (reader) {
+        while (true) {
+          const chunk = await reader.read();
+          if (chunk.done)
+            break;
+          bytes += chunk.value.byteLength;
+          if (bytes > maxBytes) {
+            await reader.cancel();
+            return { _tag: "Err", message: `Response exceeds the ${maxBytes} byte limit.` };
+          }
+          body += decoder.decode(chunk.value, { stream: true });
+        }
+        body += decoder.decode();
+      }
+      return { _tag: "Ok", value: { url: current, status: response.status, headers: response.headers, body } };
+    }
+    return { _tag: "Err", message: "Response exceeds the five redirect limit." };
+  }).catch((error) => ({ _tag: "Err", message: `Request failed: ${error instanceof Error ? error.message : String(error)}` }));
+}
+function responseFailure(document) {
+  if (document._tag === "Err")
+    return document.message;
+  if (document.value.headers.get("cf-mitigated") === "challenge")
+    return "Cloudflare returned a challenge. Check crawler access rules.";
+  if (document.value.status < 200 || document.value.status >= 300)
+    return `HTTP ${document.value.status}. Check this public URL.`;
+}
+function isHtml(body) {
+  return /^\s*(?:<!doctype html|<html|<head|<body)/i.test(body);
+}
+function contentCheck(id, url, document, accepts, success, failure) {
+  const error = responseFailure(document);
+  if (error)
+    return { id, url, status: "fail", detail: error };
+  return document._tag === "Ok" && accepts(document.value) ? { id, url: document.value.url, status: "pass", detail: success } : { id, url, status: "fail", detail: failure };
+}
+function markdown(document) {
+  return /^text\/markdown(?:;|$)/i.test(document.headers.get("content-type") || "") && !!document.body.trim() && !isHtml(document.body);
+}
+function links(header) {
+  const source = header || "";
+  const entries = [];
+  let quoted = false;
+  let target = false;
+  let start = 0;
+  for (let i = 0; i < source.length; i++) {
+    const character = source[i];
+    if (character === '"' && source[i - 1] !== "\\")
+      quoted = !quoted;
+    if (!quoted) {
+      if (character === "<")
+        target = true;
+      if (character === ">")
+        target = false;
+      if (character === "," && !target) {
+        entries.push(source.slice(start, i));
+        start = i + 1;
+      }
+    }
+  }
+  entries.push(source.slice(start));
+  return entries.flatMap((entry) => {
+    const match = entry.match(/^\s*<([^>]+)>([\s\S]*)$/);
+    if (!match)
+      return [];
+    const parameter = (name) => match[2]?.match(new RegExp(`;\\s*${name}\\s*=\\s*(?:"([^"]*)"|([^;\\s]+))`, "i"));
+    const rel = parameter("rel");
+    const type = parameter("type");
+    return [{ href: match[1], rel: (rel?.[1] || rel?.[2] || "").split(/\s+/), type: type?.[1] || type?.[2] || "" }];
+  });
+}
+function policy(header) {
+  const signals = {};
+  for (const part of header.split(",")) {
+    const match = part.trim().match(/^(search|ai-input|ai-train)\s*=\s*(yes|no)$/);
+    if (!match)
+      return { _tag: "Err", message: "Content-Signal has an invalid name or value." };
+    const name = match[1];
+    const value = match[2];
+    if (signals[name] && signals[name] !== value)
+      return { _tag: "Err", message: `Content-Signal contains conflicting ${name} values.` };
+    signals[name] = value;
+  }
+  return { _tag: "Ok", value: signals };
+}
+function policyCheck(html, md, id = "content-signal") {
+  if (html._tag === "Err" || md._tag === "Err" || responseFailure(html) || responseFailure(md))
+    return { id, status: "skip", detail: "Policy comparison requires both public page responses." };
+  const source = html.value.headers.get("content-signal");
+  const converted = md.value.headers.get("content-signal");
+  if (!source && !converted)
+    return { id, status: "warn", detail: "No HTTP Content-Signal. Check whether this matches your content policy." };
+  const parsedSource = source ? policy(source) : void 0;
+  const parsedConverted = converted ? policy(converted) : void 0;
+  for (const parsed of [parsedSource, parsedConverted]) {
+    if (parsed?._tag === "Err")
+      return { id, status: "fail", detail: parsed.message };
+  }
+  if (parsedSource?._tag === "Ok" && (!parsedConverted || parsedConverted._tag !== "Ok" || Object.keys(parsedSource.value).length !== Object.keys(parsedConverted.value).length || Object.entries(parsedSource.value).some(([key, value]) => parsedConverted.value[key] !== value))) {
+    return { id, status: "fail", detail: "Markdown does not preserve the HTML Content-Signal policy." };
+  }
+  return { id, status: "pass", detail: `HTTP policy: ${converted || source}` };
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function parseJson(body) {
+  try {
+    return { _tag: "Ok", value: JSON.parse(body) };
+  } catch {
+    return { _tag: "Err", message: "Discovery response contains invalid JSON." };
+  }
+}
+function discoveryDocument(capability, document) {
+  if (capability === "llms")
+    return !isHtml(document.body) && /^#\s+\S/m.test(document.body);
+  if (!/^application\/(?:[\w.+-]+\+)?json(?:;|$)/i.test(document.headers.get("content-type") || ""))
+    return false;
+  const parsed = parseJson(document.body);
+  if (parsed._tag === "Err")
+    return false;
+  const value = parsed.value;
+  if (!isRecord(value))
+    return false;
+  switch (capability) {
+    case "api-catalog":
+      return Array.isArray(value.linkset) && value.linkset.length > 0 && value.linkset.every((entry) => isRecord(entry) && typeof entry.anchor === "string");
+    case "skills":
+      return Array.isArray(value.skills);
+    case "ai-catalog":
+      return value.specVersion === "1.0" && Array.isArray(value.entries) && value.entries.length > 0 && value.entries.every((entry) => isRecord(entry) && typeof entry.url === "string");
+    case "mcp":
+      return typeof value.name === "string" && typeof value.version === "string" && Array.isArray(value.remotes) && value.remotes.some((remote) => isRecord(remote) && remote.type === "streamable-http" && typeof remote.url === "string");
+  }
+}
+async function auditSite(options, dependencies) {
+  const [html, negotiated] = await Promise.all([
+    readDocument(options.url, "text/html", dependencies),
+    readDocument(options.url, "text/markdown", dependencies)
+  ]);
+  const pageUrl = html._tag === "Ok" && !responseFailure(html) ? html.value.url : options.url;
+  const page = new URL(pageUrl);
+  const site = new URL(options.base, page);
+  const advertised = html._tag === "Ok" ? links(html.value.headers.get("link")) : [];
+  const alternate = advertised.find((link) => link.rel.includes("alternate") && link.type.toLowerCase() === "text/markdown");
+  const linkedUrl = alternate ? publicUrl(alternate.href, pageUrl) : void 0;
+  const direct = new URL(pageUrl);
+  direct.pathname = `${direct.pathname.replace(/\/$/, "") || "/index"}.md`;
+  const robotsUrl = new URL("/robots.txt", page).href;
+  const [directMd, robots] = await Promise.all([
+    readDocument(direct.href, "text/markdown", dependencies),
+    readDocument(robotsUrl, "text/plain", dependencies)
+  ]);
+  const robotsSitemap = robots._tag === "Ok" ? robots.value.body.match(/^sitemap:\s*(\S+)/im)?.[1] : void 0;
+  const sitemapUrl = robotsSitemap ? publicUrl(robotsSitemap, robotsUrl) : publicUrl("sitemap.xml", site.href);
+  const sitemap = sitemapUrl._tag === "Ok" ? await readDocument(sitemapUrl.value.href, "application/xml, text/xml", dependencies) : sitemapUrl;
+  const missingUrl = new URL(".well-known/nuxt-ai-ready-audit-missing", site).href;
+  const missing = await readDocument(missingUrl, "text/markdown", dependencies);
+  const checks = [
+    contentCheck("html", options.url, html, (doc) => /^text\/html(?:;|$)/i.test(doc.headers.get("content-type") || "") && !!doc.body.trim(), "Public HTML is available.", "Expected a non-empty HTML page."),
+    contentCheck("markdown-negotiation", options.url, negotiated, markdown, "Accept: text/markdown returns Markdown.", "Expected a non-empty text/markdown response."),
+    contentCheck("markdown-url", direct.href, directMd, markdown, "The direct Markdown URL is available.", "Expected a non-empty text/markdown response."),
+    { id: "markdown-link", status: linkedUrl?._tag === "Ok" && linkedUrl.value.href === direct.href ? "pass" : "warn", detail: linkedUrl?._tag === "Ok" && linkedUrl.value.href === direct.href ? "The Link header advertises the direct Markdown URL." : alternate ? "Inspect the alternate Markdown Link target." : "No alternate Markdown Link header." },
+    contentCheck("robots", robotsUrl, robots, (doc) => !isHtml(doc.body) && /^user-agent:\s*\S/im.test(doc.body), "robots.txt is available. Inspect its crawler-specific rules.", "Expected robots.txt with a User-agent group."),
+    contentCheck("sitemap", sitemapUrl._tag === "Ok" ? sitemapUrl.value.href : site.href, sitemap, (doc) => /<(?:urlset|sitemapindex)(?:\s|>)/i.test(doc.body) && /<loc>\s*https?:\/\/[^<]+<\/loc>/i.test(doc.body), "A sitemap document is available.", "Expected a sitemap with absolute URL entries."),
+    policyCheck(html, negotiated),
+    policyCheck(html, directMd, "content-signal-markdown-url"),
+    { id: "unknown-route", url: missingUrl, status: missing._tag === "Ok" && [404, 410].includes(missing.value.status) ? "pass" : "fail", detail: missing._tag === "Err" ? missing.message : [404, 410].includes(missing.value.status) ? "Unknown routes return 404 or 410." : `Unknown route returned HTTP ${missing.value.status}. Check fallback routing.` }
+  ];
+  if (negotiated._tag === "Ok" && !responseFailure(negotiated)) {
+    const vary = (negotiated.value.headers.get("vary") || "").toLowerCase().split(",").map((value) => value.trim());
+    checks.push({ id: "vary-accept", status: vary.includes("accept") || vary.includes("*") ? "pass" : "fail", detail: vary.includes("accept") || vary.includes("*") ? "Vary separates HTML and Markdown cache entries." : "Set Vary: Accept on negotiated responses." });
+  }
+  const paths = { "llms": "llms.txt", "api-catalog": ".well-known/api-catalog", "ai-catalog": ".well-known/ai-catalog.json", "mcp": ".well-known/mcp/server-card.json", "skills": ".well-known/agent-skills/index.json" };
+  const discovery = await Promise.all(capabilities.map(async (capability) => {
+    const declaredLink = capability === "api-catalog" ? advertised.find((link) => link.rel.includes("api-catalog")) : void 0;
+    if (!options.capabilities.includes(capability) && !declaredLink)
+      return { id: capability, status: "skip", detail: "Not declared. Use --capabilities to check this feature." };
+    const url = publicUrl(declaredLink?.href || paths[capability], declaredLink ? pageUrl : site.href);
+    if (url._tag === "Err")
+      return { id: capability, status: "fail", detail: url.message };
+    const document = await readDocument(url.value.href, capability === "llms" ? "text/plain" : "application/json", dependencies);
+    return contentCheck(capability, url.value.href, document, (doc) => discoveryDocument(capability, doc), "The discovery document is available.", "The discovery document has an unexpected format.");
+  }));
+  return { schemaVersion: 1, url: options.url, checks: [...checks, ...discovery] };
+}
+
 async function getSecret(cwd) {
   const secretPath = join(cwd, "node_modules/.cache/nuxt/ai-ready/secret");
   if (!existsSync(secretPath)) {
@@ -53,6 +287,31 @@ const main = defineCommand({
     version: await readPackageMetadata(import.meta.url).then((p) => p.version || "0.0.0")
   },
   subCommands: {
+    audit: () => defineCommand({
+      meta: { name: "audit", description: "Check a public page and its agent discovery documents" },
+      args: {
+        url: { type: "positional", required: true, description: "Public page URL" },
+        base: { type: "string", default: "/", description: "Application base path, such as /docs/" },
+        capabilities: { type: "string", description: "Check declared features: llms,api-catalog,ai-catalog,mcp,skills" },
+        json: { type: "boolean", description: "Print structured JSON results" }
+      },
+      async run({ args }) {
+        const parsed = parseAuditOptions(args);
+        if (parsed._tag === "Err")
+          throw new Error(parsed.message);
+        const report = await auditSite(parsed.value, { fetch });
+        if (args.json) {
+          process.stdout.write(`${JSON.stringify(report, null, 2)}
+`);
+        } else {
+          consola.info(`Readiness audit: ${report.url}`);
+          for (const check of report.checks)
+            consola.log(`${check.status.toUpperCase()} ${check.id}: ${check.detail}`);
+        }
+        if (report.checks.some((check) => check.status === "fail"))
+          process.exitCode = 1;
+      }
+    }),
     status: () => defineCommand({
       meta: {
         name: "status",

package/dist/module.json

@@ -4,7 +4,7 @@
     "nuxt": "^4.6.0 || ^5.0.0-0"
   },
   "configKey": "aiReady",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -7,7 +7,7 @@ import '@nuxt/kit';
 import 'defu';
 import 'nuxt-site-config/kit';
 import 'nuxtseo-shared/kit';
-export { m as default } from './shared/nuxt-ai-ready.BwnSMqRn.mjs';
+export { m as default } from './shared/nuxt-ai-ready.CKXM1jnE.mjs';
 import './shared/nuxt-ai-ready.B3hAuOLQ.mjs';
 import '../dist/runtime/llms-txt-files.js';
 import '../dist/runtime/route-path.js';

package/dist/runtime/llms-txt-files.js

@@ -72,13 +72,13 @@ ${lines.join("\n")}
     }
     if (chunk.length)
       chunks.push(chunk);
-    if (chunks.length >= lines.length)
-      throw new Error("llmsTxt.maxLength cannot fit an index. Increase the limit.");
     const links = chunks.map((entries, index) => {
       const child = `/llms/_${prefix}-${level}-${index + 1}.txt`;
       files.set(child, render(header, title, entries));
       return link(`${title} ${index + 1}`, child);
     });
+    if (chunks.length >= lines.length && render(header, title, links).length >= body.length)
+      throw new Error("llmsTxt.maxLength cannot fit an index. Increase the limit.");
     tree(path, prefix, header, title, links, level + 1);
   }
   const sections = [];
@@ -111,11 +111,66 @@ ${preamble}
 ${link("llms.txt", "/llms.txt")}`, section.title, entries);
     sections.push({ ...section, sitemap: void 0, path: void 0, links: [{ title: section.title, href: input.resolveUrl(path), description }] });
   }
-  const rootHeader = `${input.header.trim()}
+  const rootPreamble = `${input.header.trim()}
+
+${normalizeLlmsTxtConfig({ notes: input.config.notes })}${input.rootContent ? `
+
+${input.rootContent}` : ""}`;
+  const pageIndexSpace = input.pages.some((page) => !assigned.has(page.pathname)) ? render("", "Pages", [link("Pages", "/llms/_pages.txt")]).length : 1;
+  let rootHeader = `${input.header.trim()}
 
 ${normalizeLlmsTxtConfig({ ...input.config, sections })}${input.rootContent ? `
 
 ${input.rootContent}` : ""}`;
+  if (rootHeader.length + pageIndexSpace > maxLength) {
+    const references = sections.flatMap((section, index) => {
+      const path = `/llms/_configured-${index + 1}.txt`;
+      if (!section.links?.length) {
+        const context = normalizeLlmsTxtConfig({ sections: [section] });
+        if (!context)
+          return [];
+        const body = `${input.header.trim()}
+
+${context}
+
+${link("llms.txt", "/llms.txt")}
+`;
+        if (body.length > maxLength)
+          throw new Error("An llms.txt entry exceeds llmsTxt.maxLength. Shorten the entry or increase the limit.");
+        files.set(path, body);
+        return [{ title: section.title, links: [{ title: section.title, href: input.resolveUrl(path) }] }];
+      }
+      const text = normalizeLlmsTxtConfig({ sections: [{ ...section, description: section.optional ? section.description : void 0 }] });
+      const lines = text.split("\n").slice(2);
+      const description = Array.isArray(section.description) ? section.description.join(" ") : section.description;
+      const preamble = section.optional ? "" : normalizeLlmsTxtConfig({ notes: description });
+      tree(path, `configured-${index + 1}`, `${input.header.trim()}
+
+${preamble}
+
+${link("llms.txt", "/llms.txt")}`, section.optional ? "Optional" : section.title, lines);
+      return [{ title: section.title, optional: section.optional, links: [{ title: section.title, href: input.resolveUrl(path), description }] }];
+    });
+    rootHeader = `${rootPreamble}
+
+${normalizeLlmsTxtConfig({ sections: references })}`;
+    if (rootHeader.length + pageIndexSpace > maxLength) {
+      const indexes = [];
+      for (const optional of [false, true]) {
+        const selected = references.filter((section) => Boolean(section.optional) === optional);
+        if (!selected.length)
+          continue;
+        const title = optional ? "Optional" : "Sections";
+        const path = optional ? "/llms/_optional.txt" : "/llms/_sections.txt";
+        const text = normalizeLlmsTxtConfig({ sections: selected.map((section) => ({ ...section, optional: true })) });
+        tree(path, optional ? "optional" : "sections", input.header, title, text.split("\n").slice(2));
+        indexes.push({ title, optional, links: [{ title, href: input.resolveUrl(path) }] });
+      }
+      rootHeader = `${rootPreamble}
+
+${normalizeLlmsTxtConfig({ sections: indexes })}`;
+    }
+  }
   const pages = input.pages.filter((page) => !assigned.has(page.pathname)).map(formatLlmsTxtPageLink);
   if (!pages.length && rootHeader.length + 1 <= maxLength) {
     files.set("/llms.txt", `${rootHeader.trim()}

package/dist/runtime/llms-txt-format.js

@@ -1,3 +1,4 @@
+import { escapeMarkdownHtml } from "./markdown-text.js";
 const RE_INLINE_WHITESPACE = /\s+/g;
 const RE_LINK_TITLE_BRACKET = /[[\]]/g;
 const RE_LINK_HREF_UNSAFE = /[\s()]/g;
@@ -6,7 +7,7 @@ function normalizeInlineText(value) {
   return value.trim().replace(RE_INLINE_WHITESPACE, " ");
 }
 function normalizeLinkTitle(value) {
-  return normalizeInlineText(value).replace(RE_LINK_TITLE_BRACKET, (bracket) => bracket === "[" ? "[" : "]");
+  return escapeMarkdownHtml(normalizeInlineText(value)).replace(RE_LINK_TITLE_BRACKET, (bracket) => bracket === "[" ? "[" : "]");
 }
 function normalizeLinkHref(value) {
   return value.trim().replace(RE_LINK_HREF_UNSAFE, (character) => {
@@ -29,7 +30,7 @@ function normalizeLink(link, descriptionPrefixes = []) {
   return `- [${normalizeLinkTitle(link.title)}](${normalizeLinkHref(link.href)})${description ? `: ${description}` : ""}`;
 }
 function normalizeSection(section) {
-  const parts = [`## ${normalizeInlineText(section.title)}`];
+  const parts = [`## ${escapeMarkdownHtml(normalizeInlineText(section.title))}`];
   if (section.links?.length)
     parts.push("", ...section.links.map((link) => normalizeLink(link)));
   return parts.join("\n");
@@ -46,7 +47,7 @@ function normalizePreamble(config) {
       continue;
     const descriptions = normalizePreambleBlocks(section.description);
     if (descriptions.length)
-      parts.push([`**${normalizeInlineText(section.title)}:**`, ...descriptions].join("\n\n"));
+      parts.push([`**${escapeMarkdownHtml(normalizeInlineText(section.title))}:**`, ...descriptions].join("\n\n"));
   }
   return parts;
 }
@@ -67,7 +68,7 @@ export function formatLlmsTxtPageLink(page) {
   const title = normalizedTitle && normalizedTitle !== page.pathname ? normalizedTitle : page.pathname;
   const href = (page.href || page.pathname).trim();
   const truncatedDescription = description ? `${description.substring(0, 160)}${description.length > 160 ? "..." : ""}` : void 0;
-  return normalizeLink({ title, href, description: truncatedDescription });
+  return normalizeLink({ title, href, description: truncatedDescription ? escapeMarkdownHtml(truncatedDescription) : void 0 });
 }
 export function normalizeLlmsTxtConfig(config) {
   const required = config.sections?.filter((section) => !section.optional) ?? [];

package/dist/runtime/markdown-text.d.ts

@@ -0,0 +1,2 @@
+/** Keep plain metadata literal when Markdown allows inline HTML. */
+export declare function escapeMarkdownHtml(value: string): string;

package/dist/runtime/markdown-text.js

@@ -0,0 +1,3 @@
+export function escapeMarkdownHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}

package/dist/runtime/server/db/drizzle/queries.d.ts

@@ -1,6 +1,6 @@
 import type { SitemapCrawlState } from '../../utils/sitemap-crawl-state.js';
 import type { AiReadyDatabaseEvent } from '../context.js';
-import type { SeedRoutesOptions } from '../seed.js';
+import type { SeedRoute, SeedRoutesOptions } from '../seed.js';
 export interface PageInput {
     route: string;
     title: string;
@@ -182,9 +182,5 @@ export declare function resetSitemapErrors(event: AiReadyDatabaseEvent | undefin
  * guard each run bumped `last_seen_at` on every row, which cost millions of
  * D1 row writes a month. Keep the two layers in sync.
  */
-export declare function seedRoutes(event: AiReadyDatabaseEvent | undefined, routes: Array<string | {
-    route: string;
-    locale?: string;
-    url?: string;
-}>, options?: SeedRoutesOptions): Promise<number>;
+export declare function seedRoutes(event: AiReadyDatabaseEvent | undefined, routes: SeedRoute[], options?: SeedRoutesOptions): Promise<number>;
 export {};