nuxt-ai-ready 3.1.0 → 3.2.0

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.Dmvy7CIJ.mjs';
+import { A as AGENT_SKILLS_SCHEMA } from '../shared/nuxt-ai-ready.DH9mSayy.mjs';
 import 'node:module';
 import 'node:url';
 import '@nuxt/kit';

package/dist/chunks/prerender.mjs

@@ -6,7 +6,9 @@ import { resolveLocaleFromRoute } from 'nuxtseo-shared/i18n-runtime';
 import { createPrerenderFetch } from 'nuxtseo-shared/prerender';
 import { collectSitemap } from 'sitemapd/parse';
 import { withLeadingSlash, joinURL, withBase } from 'ufo';
-import { l as logger, M as MARKDOWN_LINK_AVAILABILITY_FILE } from '../shared/nuxt-ai-ready.Dmvy7CIJ.mjs';
+import { l as logger, M as MARKDOWN_LINK_AVAILABILITY_FILE } from '../shared/nuxt-ai-ready.DH9mSayy.mjs';
+import { insertLlmsTxtDirective } from '../../dist/runtime/llms-txt-directive.js';
+import { absoluteSiteUrl } from '../../dist/runtime/markdown-links.js';
 import { normalizePagePath, toMarkdownPath } from '../../dist/runtime/markdown-path.js';
 import { toDeployedRoute, toLogicalRoute } from '../../dist/runtime/route-path.js';
 import { initSchema, computeContentHash, insertPage, queryAllPages, exportDbDump } from '../../dist/runtime/server/db/shared.js';
@@ -347,7 +349,8 @@ function setupPrerenderHandler(options, dbPath, siteInfo, llmsTxtConfig, extras)
       await initPromise;
       const parsed = JSON.parse(route.contents || "{}");
       await processMarkdownRoute(state, nuxt, pageRoute, parsed);
-      route.contents = options.sitemapMd === false ? parsed.markdown : appendSitemapSection(parsed.markdown, toDeployedRoute(SITEMAP_MD_ROUTE, nitro.options.baseURL));
+      const withSitemap = options.sitemapMd === false ? parsed.markdown : appendSitemapSection(parsed.markdown, absoluteSiteUrl(toDeployedRoute(SITEMAP_MD_ROUTE, nitro.options.baseURL), siteInfo?.url));
+      route.contents = llmsTxtConfig?.directive?.markdown === false ? withSitemap : insertLlmsTxtDirective(withSitemap, absoluteSiteUrl(toDeployedRoute("/llms.txt", nitro.options.baseURL), siteInfo?.url));
       route.contentType = "text/markdown; charset=utf-8";
       state.totalProcessingTime += Date.now() - pageStartTime;
     });
@@ -409,10 +412,12 @@ function setupPrerenderHandler(options, dbPath, siteInfo, llmsTxtConfig, extras)
       }
       if (state.dbPath && state.llmsTxtConfig?.markdownLinks) {
         const availabilityFile = join(dirname(state.dbPath), MARKDOWN_LINK_AVAILABILITY_FILE);
+        const options2 = nitro.options;
+        const ignoreBaseDir = options2.srcDir || (typeof options2.serverDir === "string" ? options2.serverDir : void 0) || options2.rootDir;
         const paths = await findOutputMarkdownPaths(
           nitro.options.output.publicDir,
           nitro.options.baseURL,
-          nitro.options.srcDir,
+          ignoreBaseDir,
           nitro.options.ignore,
           nitro.options.publicAssets
         );

package/dist/module.json

@@ -4,7 +4,7 @@
     "nuxt": "^4.6.0 || ^5.0.0-0"
   },
   "configKey": "aiReady",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "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.Dmvy7CIJ.mjs';
+export { m as default } from './shared/nuxt-ai-ready.DH9mSayy.mjs';
 import './shared/nuxt-ai-ready.B3hAuOLQ.mjs';
 import '../dist/runtime/route-path.js';
 import '../dist/runtime/server/utils/sitemap-md.js';

package/dist/runtime/llms-txt-directive.d.ts

@@ -0,0 +1,15 @@
+/** The line that points a reader of one page at the whole site's index. */
+export declare function llmsTxtDirective(llmsTxtUrl: string): string;
+/**
+ * Add the llms.txt directive near the top of a page's Markdown, after any
+ * frontmatter so YAML parsers still find it first. An agent that lands on one
+ * page then knows where the full index is.
+ */
+export declare function insertLlmsTxtDirective(markdown: string, llmsTxtUrl: string): string;
+/**
+ * The HTML equivalent: a link at the top of the body, hidden visually but
+ * kept for screen readers and agents that read the raw HTML.
+ */
+export declare function llmsTxtDirectiveHtml(llmsTxtPath: string): string;
+/** Remove the injected HTML link, so a page's Markdown carries the directive once. */
+export declare function stripLlmsTxtDirectiveHtml(html: string): string;

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

@@ -0,0 +1,23 @@
+const RE_FRONTMATTER = /^\uFEFF?---[\t ]*\r?\n(?:[\s\S]*?\r?\n)?---[\t ]*(?:\r?\n|$)/;
+export function llmsTxtDirective(llmsTxtUrl) {
+  return `> Index of every page on this site: [llms.txt](${llmsTxtUrl})`;
+}
+export function insertLlmsTxtDirective(markdown, llmsTxtUrl) {
+  const directive = llmsTxtDirective(llmsTxtUrl);
+  const frontmatter = markdown.match(RE_FRONTMATTER)?.[0] ?? "";
+  const body = markdown.slice(frontmatter.length).replace(/^(?:\r?\n)+/, "");
+  if (body === directive || body.startsWith(`${directive}
+`) || body.startsWith(`${directive}\r
+`))
+    return markdown;
+  return `${frontmatter}${frontmatter ? "\n" : ""}${directive}
+
+${body}`;
+}
+const RE_DIRECTIVE_HTML = /<a [^>]*data-llms-txt-directive[^>]*>[^<]*<\/a>/g;
+export function llmsTxtDirectiveHtml(llmsTxtPath) {
+  return `<a href="${llmsTxtPath}" tabindex="-1" style="position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0" data-llms-txt-directive>Index of every page on this site: llms.txt</a>`;
+}
+export function stripLlmsTxtDirectiveHtml(html) {
+  return html.replace(RE_DIRECTIVE_HTML, "");
+}

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

@@ -4,6 +4,7 @@ import { useRuntimeConfig } from "#nuxtseo/nitro";
 import { getSiteConfig } from "#site-config/server/composables/getSiteConfig";
 import { withSiteTrailingSlash, withSiteUrl } from "#site-config/server/composables/utils";
 import { formatLlmsTxtPageLink, normalizeLlmsTxtConfig } from "./llms-txt-format.js";
+import { absoluteSiteUrl } from "./markdown-links.js";
 import { hasMarkdownTwin, toMarkdownPath } from "./markdown-path.js";
 import { normalizePersistedRoute, toDeployedRoute, toLogicalRoute } from "./route-path.js";
 import { queryPages } from "./server/db/queries.js";
@@ -207,6 +208,8 @@ Canonical Origin: ${canonicalSiteUrl}`);
       return deployedPathname;
     };
   }
+  const resolvePagePath = resolvePageHref;
+  resolvePageHref = (pathname) => absoluteSiteUrl(resolvePagePath(pathname), canonicalSiteUrl);
   for (const page of [...prerendered, ...other])
     page.href = resolvePageHref(page.pathname);
   if (i18nRuntime._tag === "enabled") {

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

@@ -0,0 +1,10 @@
+/**
+ * Resolve root-relative link and image destinations against a site origin.
+ *
+ * A Markdown page read on its own, by an agent or from `llms-full.txt`, has
+ * no page URL to resolve `/docs/api` against, so such a link loses its
+ * target. Fenced code and inline code spans keep their text.
+ */
+export declare function absoluteMarkdownLinks(markdown: string, siteUrl: string): string;
+/** A deployed path on the site's origin, or the path itself when no site URL is known. */
+export declare function absoluteSiteUrl(path: string, siteUrl: string | undefined): string;

package/dist/runtime/markdown-links.js

@@ -0,0 +1,52 @@
+const RE_FENCE = /^ {0,3}(`{3,}|~{3,})/;
+const RE_INLINE_ROOT_LINK = /\]\((<?)\/(?!\/)/g;
+const RE_REFERENCE_ROOT_LINK = /^( {0,3}\[[^\]]+\]:[\t ]*<?)\/(?!\/)/;
+function closesFence(line, fence) {
+  const trimmed = line.trim();
+  return trimmed.length >= fence.length && trimmed[0] === fence[0] && [...trimmed].every((char) => char === fence[0]);
+}
+function backtickRun(line, start) {
+  let end = start;
+  while (line[end] === "`")
+    end++;
+  return end - start;
+}
+function rewriteOutsideCodeSpans(line, rewrite) {
+  let output = "";
+  let last = 0;
+  let index = line.indexOf("`");
+  while (index !== -1) {
+    const length = backtickRun(line, index);
+    let close = line.indexOf("`", index + length);
+    while (close !== -1 && backtickRun(line, close) !== length)
+      close = line.indexOf("`", close + backtickRun(line, close));
+    if (close === -1) {
+      index = line.indexOf("`", index + length);
+      continue;
+    }
+    output += rewrite(line.slice(last, index)) + line.slice(index, close + length);
+    last = close + length;
+    index = line.indexOf("`", last);
+  }
+  return output + rewrite(line.slice(last));
+}
+export function absoluteMarkdownLinks(markdown, siteUrl) {
+  const origin = new URL(siteUrl).origin;
+  let fence;
+  return markdown.split(/(?<=\n)/).map((line) => {
+    if (fence) {
+      if (closesFence(line, fence))
+        fence = void 0;
+      return line;
+    }
+    const opening = line.match(RE_FENCE);
+    if (opening) {
+      fence = opening[1];
+      return line;
+    }
+    return rewriteOutsideCodeSpans(line, (text) => text.replace(RE_REFERENCE_ROOT_LINK, `$1${origin}/`).replace(RE_INLINE_ROOT_LINK, `]($1${origin}/`));
+  }).join("");
+}
+export function absoluteSiteUrl(path, siteUrl) {
+  return siteUrl ? new URL(path, new URL(siteUrl).origin).href : path;
+}

package/dist/runtime/server/middleware/markdown.js

@@ -1,6 +1,8 @@
 import { createError, defineEventHandler, getRequestURL, setHeader, setResponseStatus } from "#nuxtseo/h3";
 import { useNitroApp, useRuntimeConfig } from "#nuxtseo/nitro";
 import { resolveLocaleAlternateUrl } from "../../i18n-url.js";
+import { insertLlmsTxtDirective } from "../../llms-txt-directive.js";
+import { absoluteMarkdownLinks } from "../../markdown-links.js";
 import { logger } from "../logger.js";
 import { computeLocaleAlternates, resolveLocaleFromRoute } from "../utils/i18n.js";
 import { resolveMarkdownRedirect } from "../utils/markdown-redirect.js";
@@ -49,7 +51,12 @@ export default defineEventHandler(async (event) => {
   const ctx = buildNegotiationContext(event, decision.path);
   const { path, config, resolvePath, resolveUrl, routeContext } = ctx;
   const canonicalUrl = resolveUrl(path);
-  const finalizeMarkdown = (markdown) => config.sitemapMd === false ? markdown : appendSitemapSection(markdown, resolvePath(SITEMAP_MD_ROUTE));
+  const finalizeMarkdown = (markdown) => {
+    const withSitemap = config.sitemapMd === false ? markdown : appendSitemapSection(markdown, resolvePath(SITEMAP_MD_ROUTE));
+    const llmsTxt = config.llmsTxt;
+    const withDirective = llmsTxt?.directive?.markdown === false ? withSitemap : insertLlmsTxtDirective(withSitemap, resolveUrl("/llms.txt"));
+    return absoluteMarkdownLinks(withDirective, canonicalUrl);
+  };
   const [
     { tryGetContentMarkdown },
     { fetchRawWithEvent },

package/dist/runtime/server/middleware/markdown.prerender.js

@@ -1,6 +1,7 @@
 import { createError, defineEventHandler } from "#nuxtseo/h3";
 import { useRuntimeConfig } from "#nuxtseo/nitro";
 import { withSiteUrl } from "#site-config/server/composables/utils";
+import { absoluteMarkdownLinks } from "../../markdown-links.js";
 import { toDeployedRoute } from "../../route-path.js";
 import { logger } from "../logger.js";
 import { convertHtmlToMarkdown, extractLastUpdated } from "../utils.js";
@@ -52,7 +53,7 @@ export default defineEventHandler(async (event) => {
       last_updated: contentPage.updatedAt
     });
     const markdown = `${frontmatter}
-${contentPage.markdown}`;
+${absoluteMarkdownLinks(contentPage.markdown, canonicalUrl)}`;
     const headings = extractHeadingsFromMarkdown(contentPage.markdown);
     const keywords2 = extractKeywords(contentPage.markdown, "");
     return JSON.stringify({

package/dist/runtime/server/plugins/llms-txt-directive-html.d.ts

@@ -0,0 +1,3 @@
+/** Registered only with `llmsTxt.directive.html: true`. */
+declare const _default: any;
+export default _default;

package/dist/runtime/server/plugins/llms-txt-directive-html.js

@@ -0,0 +1,8 @@
+import { defineNitroPlugin, useRuntimeConfig } from "#nuxtseo/nitro";
+import { llmsTxtDirectiveHtml } from "../../llms-txt-directive.js";
+import { toDeployedRoute } from "../../route-path.js";
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook("render:html", (html, { event }) => {
+    html.bodyPrepend.unshift(llmsTxtDirectiveHtml(toDeployedRoute("/llms.txt", useRuntimeConfig(event).app.baseURL)));
+  });
+});

package/dist/runtime/server/routes/sitemap.md.get.js

@@ -2,6 +2,7 @@ import { eventHandler, setHeader } from "#nuxtseo/h3";
 import { defineCachedFunction, useRuntimeConfig } from "#nuxtseo/nitro";
 import { getSiteConfig } from "#site-config/server/composables";
 import { publicCacheControl } from "../../cache-control.js";
+import { absoluteSiteUrl } from "../../markdown-links.js";
 import { toMarkdownPath } from "../../markdown-path.js";
 import { toDeployedRoute } from "../../route-path.js";
 import { queryPages } from "../db/queries.js";
@@ -17,11 +18,12 @@ async function buildSitemapMarkdown(event) {
     );
   }
   const baseURL = useRuntimeConfig(event).app.baseURL;
+  const siteConfig = getSiteConfig(event);
   return buildSitemapMd(
     pages.map((page) => ({ route: page.route, title: page.title, updatedAt: page.updatedAt })),
     {
-      siteName: getSiteConfig(event).name,
-      resolveHref: (route) => toDeployedRoute(toMarkdownPath(route), baseURL)
+      siteName: siteConfig.name,
+      resolveHref: (route) => absoluteSiteUrl(toDeployedRoute(toMarkdownPath(route), baseURL), siteConfig.url)
     }
   );
 }

package/dist/runtime/server/utils.js

@@ -1,5 +1,6 @@
 import { htmlToMarkdown } from "mdream";
 import { useNitroApp } from "#nuxtseo/nitro";
+import { stripLlmsTxtDirectiveHtml } from "../llms-txt-directive.js";
 import { hoistMetaDescription } from "./utils/frontmatter.js";
 const RE_NBSP = /\u00A0/g;
 function normalizeWhitespace(text) {
@@ -75,7 +76,7 @@ export async function convertHtmlToMarkdown(html, url, mdreamOptions, opts) {
   await nitroApp.hooks.callHook("ai-ready:mdreamConfig", options);
   const context = {
     html,
-    markdown: hoistMetaDescription(htmlToMarkdown(html, options)),
+    markdown: hoistMetaDescription(htmlToMarkdown(stripLlmsTxtDirectiveHtml(html), options)),
     route: opts.hooks.route,
     title: meta.title,
     description: meta.description,

package/dist/runtime/types.d.ts

@@ -529,9 +529,25 @@ export interface LlmsTxtConfig {
      * Rewrite automatically generated page links to their Markdown representation
      * when the final static output contains the file or the deployment retains
      * the runtime Markdown handler.
-     * @default false
+     * @default true
      */
     markdownLinks?: boolean;
+    /**
+     * Point each page at llms.txt, so an agent that lands on one page finds the
+     * whole site's index.
+     */
+    directive?: {
+        /**
+         * Add a blockquote line after the frontmatter of every page's `.md` response.
+         * @default true
+         */
+        markdown?: boolean;
+        /**
+         * Add a visually hidden link to `/llms.txt` at the top of every HTML page's body.
+         * @default false
+         */
+        html?: boolean;
+    };
     /** The sections of the documentation */
     sections?: LlmsTxtSection[];
     /** Additional heading-free preamble notes rendered before file-list sections */

package/dist/shared/{nuxt-ai-ready.Dmvy7CIJ.mjs → nuxt-ai-ready.DH9mSayy.mjs}

@@ -666,18 +666,42 @@ function cloudflareStaticFallbackPaths(existing, pages, environments = []) {
   const patterns = [...existing || [], ...environments.flatMap((routing) => Array.isArray(routing) ? routing : [])];
   return pagePaths(pages).filter((path) => !patterns.some((pattern) => matchesPattern(path, pattern.startsWith("!") ? pattern.slice(1) : pattern)));
 }
-function cloudflareNegotiationPatterns(existing, pages) {
-  if (existing === true || existing === false || pages.length === 0)
-    return existing;
-  const patterns = [...existing || []];
-  for (const path of cloudflareStaticFallbackPaths(existing, pages)) {
-    if (!patterns.includes(path))
-      patterns.push(path);
+function parentDirectories(path) {
+  const segments = path.split("/").filter(Boolean);
+  return segments.slice(0, -1).map((_, index) => `/${segments.slice(0, index + 1).join("/")}/`);
+}
+function fitWorkerFirstBudget(paths, budget) {
+  let remaining = [...paths];
+  const globs = [];
+  while (remaining.length + globs.length > budget) {
+    const counts = /* @__PURE__ */ new Map();
+    for (const path of remaining) {
+      for (const directory2 of parentDirectories(path))
+        counts.set(directory2, (counts.get(directory2) ?? 0) + 1);
+    }
+    let best;
+    for (const [directory2, count] of counts) {
+      if (!best || count > best[1] || count === best[1] && directory2.length > best[0].length)
+        best = [directory2, count];
+    }
+    if (!best || best[1] < 2)
+      return void 0;
+    const [directory] = best;
+    globs.push(`${directory}*`);
+    remaining = remaining.filter((path) => !path.startsWith(directory) || path === directory);
   }
-  if (patterns.length > MAX_WORKER_FIRST_PATTERNS) {
-    throw new Error("Cloudflare Markdown negotiation exceeds 100 worker-first patterns. Configure broader assets.run_worker_first patterns, or disable aiReady.contentNegotiation.");
+  return [...remaining, ...globs];
+}
+function cloudflareWorkerFirstAdditions(existing, pages) {
+  if (existing === true || existing === false || pages.length === 0)
+    return [];
+  const patterns = existing || [];
+  const paths = cloudflareStaticFallbackPaths(existing, pages).filter((path) => !patterns.includes(path));
+  const additions = fitWorkerFirstBudget(paths, MAX_WORKER_FIRST_PATTERNS - patterns.length);
+  if (!additions) {
+    throw new Error("Cloudflare Markdown negotiation exceeds 100 worker-first patterns, even with directory globs. Configure broader assets.run_worker_first patterns, or disable aiReady.contentNegotiation.");
   }
-  return patterns;
+  return additions;
 }
 
 const CACHE_GUIDE = "https://nuxtseo.com/docs/ai-ready/guides/markdown#cache-safety";
@@ -1219,6 +1243,14 @@ function createMcpServerCardEtag(card) {
   return `"${createHash("sha256").update(JSON.stringify(card)).digest("hex")}"`;
 }
 
+function opaqueJsonModule(exports) {
+  const encode = (value) => JSON.stringify(Buffer.from(JSON.stringify(value), "utf8").toString("base64"));
+  return [
+    "const decode = value => JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(value), char => char.charCodeAt(0))))",
+    ...Object.entries(exports).map(([name, value]) => `export const ${name} = decode(${encode(value)})`)
+  ].join("\n");
+}
+
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -1828,14 +1860,19 @@ ${details}`);
         }))
       });
     }
+    const llmsTxtDirective = {
+      markdown: config.llmsTxt?.directive?.markdown !== false,
+      html: config.llmsTxt?.directive?.html === true
+    };
     const mergedLlmsTxt = config.llmsTxt ? {
-      markdownLinks: config.llmsTxt.markdownLinks ?? false,
+      markdownLinks: config.llmsTxt.markdownLinks ?? true,
+      directive: llmsTxtDirective,
       sections: [
         ...defaultLlmsTxtSections,
         ...config.llmsTxt.sections || []
       ],
       notes: config.llmsTxt.notes
-    } : { markdownLinks: false, sections: defaultLlmsTxtSections };
+    } : { markdownLinks: true, directive: llmsTxtDirective, sections: defaultLlmsTxtSections };
     const llmsTxtPayload = {
       sections: mergedLlmsTxt.sections || [],
       notes: typeof mergedLlmsTxt.notes === "string" ? [mergedLlmsTxt.notes] : mergedLlmsTxt.notes || []
@@ -2160,8 +2197,7 @@ export { unavailable as computeLocaleAlternates, unavailable as localePath, unav
 `;
       };
       nitroConfig.virtual["#ai-ready-virtual/site-tools.mjs"] = `export default ${JSON.stringify(siteToolsConfig)}`;
-      nitroConfig.virtual["#ai-ready-virtual/agent-skills.mjs"] = agentSkillsResult._tag === "Enabled" ? `export const agentSkillsIndex = ${JSON.stringify(agentSkillsResult.index)}
-export const localAgentSkillArtifacts = ${JSON.stringify(agentSkillsResult.localArtifacts)}` : "export const agentSkillsIndex = null\nexport const localAgentSkillArtifacts = {}";
+      nitroConfig.virtual["#ai-ready-virtual/agent-skills.mjs"] = agentSkillsResult._tag === "Enabled" ? opaqueJsonModule({ agentSkillsIndex: agentSkillsResult.index, localAgentSkillArtifacts: agentSkillsResult.localArtifacts }) : "export const agentSkillsIndex = null\nexport const localAgentSkillArtifacts = {}";
       const markdownLinkAvailabilityPath = join(dirname(buildDbPath), MARKDOWN_LINK_AVAILABILITY_FILE);
       nitroConfig.virtual["#ai-ready-virtual/read-page-data.mjs"] = createBuildPageDataVirtual({
         buildDbPath,
@@ -2293,6 +2329,8 @@ export function trackDrizzleWork(event, work) { return work }
     }
     addNitroPlugin(resolve$1(getNitroVersion(nuxt) === 3 ? "./runtime/server/plugins/link-header-nitro3" : "./runtime/server/plugins/link-header"));
     addNitroPlugin(resolve$1("./runtime/server/plugins/markdown-negotiation"));
+    if (llmsTxtDirective.html)
+      addNitroPlugin(resolve$1("./runtime/server/plugins/llms-txt-directive-html"));
     addPlugin({
       mode: "server",
       src: resolve$1("./runtime/app/plugins/md-alternate.server")
@@ -2446,13 +2484,12 @@ export function trackDrizzleWork(event, work) { return work }
           const assets = wrangler.assets ||= {};
           const fileRouting = await readCloudflareAssetRouting(nitro.options.rootDir);
           const routing = defu$1({ value: assets.run_worker_first }, { value: fileRouting.root }).value;
-          cloudflareNegotiationPatterns(routing, pages);
+          const additions = cloudflareWorkerFirstAdditions(routing, pages);
           const environmentConfig = wrangler;
           const configuredEnvironments = Object.values(environmentConfig.env || {}).flatMap((env) => env.assets?.run_worker_first === void 0 ? [] : [env.assets.run_worker_first]);
           const fallbackPaths = cloudflareStaticFallbackPaths(routing, pages, [...fileRouting.environments, ...configuredEnvironments]);
-          const addedPaths = cloudflareStaticFallbackPaths(routing, pages);
-          if (addedPaths.length > 0)
-            assets.run_worker_first = [...Array.isArray(assets.run_worker_first) ? assets.run_worker_first : [], ...addedPaths];
+          if (additions.length > 0)
+            assets.run_worker_first = [...Array.isArray(assets.run_worker_first) ? assets.run_worker_first : [], ...additions];
           nitro.options.runtimeConfig["nuxt-ai-ready"].cloudflarePrerenderedPages = fallbackPaths;
         }
         const plan = planStaticMarkdownHeaderRules(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-ai-ready",
   "type": "module",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Best practice AI & LLM discoverability for Nuxt sites.",
   "author": {
     "name": "Harlan Wilton",

package/skills/nuxt-ai-ready/SKILL.md

@@ -95,6 +95,7 @@ Runtime indexing, database drivers, Cloudflare D1, and the server query helpers:
 - **The same edit in both hooks applies twice.** During prerendering the Nitro `ai-ready:page:markdown` hook runs, then the Nuxt hook of the same name. Put an edit in one of them, not both.
 - **Content source pages skip conversion hooks.** A Nuxt Content page ignores `mdreamOptions` and both Nitro hooks.
 - **Dev has no page data.** Query helpers, MCP tools, and search return empty results in `nuxt dev`. Test with `nuxt build` and `node .output/server/index.mjs`.
+- **Cloudflare static pages negotiate only with `contentNegotiation: true`.** The default leaves prerendered HTML on the asset service, so `Accept: text/markdown` gets HTML there. With `true`, prerendered pages go into `assets.run_worker_first`: exact paths up to Cloudflare's 100 entries, directory globs such as `/docs/*` past that. More than 100 top-level pages fail the build; set broader patterns yourself.
 - **Response caching turns negotiation off.** An ISR, `swr`, or `cache` route rule without `varies: ['accept']` serves HTML to Markdown clients. With `botNegotiation: true`, the rule needs `varies: ['accept', 'sec-fetch-dest', 'user-agent']`. The `.md` URL still works. For a CDN that caches by URL only, set `contentNegotiation: false`.
 - **Emptying `ctx.markdown` does not hide a page.** It drops the body from `llms-full.txt`. The URL stays in `llms.txt` and in the index. Use `sitemap.exclude` for discovery, and access control for private pages.
 - **Root `skills/` folders require explicit publication.** Automatic discovery scans public directories only. Set `agentSkills.dir: 'skills'` to publish root skills intentionally.
@@ -125,7 +126,8 @@ Runtime indexing, database drivers, Cloudflare D1, and the server query helpers:
 
 ## Config
 
-- `llmsTxt.markdownLinks` (`false`): link page entries in `llms.txt` to their `.md` twins.
+- `llmsTxt.directive` (`{ markdown: true, html: false }`): a `> Index of every page on this site: [llms.txt](...)` line after the frontmatter of each page's `.md`; `html: true` adds a visually hidden `/llms.txt` link at the top of each HTML body.
+- `llmsTxt.markdownLinks` (`true`): link page entries in `llms.txt` to their `.md` twins. `false` links canonical URLs. With `site.url` set, page links in `llms.txt`, `sitemap.md`, and `.md` bodies are absolute.
 - `describedby` (`true`): the `describedby` link tag and header.
 - `tools.<listPages|searchPages|getPageMarkdown>.<mcp|webmcp>.enabled`: attach a built in tool to one transport only.
 - `autoI18n` (`true`): with `@nuxtjs/i18n`, adds hreflang `Link` headers and a languages section in `llms.txt`.