nuxt-ai-ready 3.0.4 → 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.iq1L3kll.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.iq1L3kll.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/devtools/lib/ai-ready/types.ts

@@ -4,7 +4,7 @@ export interface DevtoolsConfig {
   sitemapPrerendered: boolean
   markdownCacheHeaders: { maxAge: number, swr: boolean }
   llmsTxtCacheSeconds: number
-  contentSignal: false | { aiTrain: boolean, search: boolean, aiInput: boolean }
+  contentSignal: false | { aiTrain?: boolean, search?: boolean, aiInput?: boolean }
   mcp: { enabled: boolean, tools: boolean, resources: boolean }
   cron: boolean
 }

package/dist/module.json

@@ -4,7 +4,7 @@
     "nuxt": "^4.6.0 || ^5.0.0-0"
   },
   "configKey": "aiReady",
-  "version": "3.0.4",
+  "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.iq1L3kll.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

@@ -200,7 +200,12 @@ export interface ModuleOptions {
      */
     describedby?: boolean;
     /**
-     * Content Signal Directives
+     * Content Signal directives for robots.txt.
+     *
+     * Unset, robots.txt gets `Content-Signal: search=yes, ai-input=yes` and no
+     * `ai-train` preference, unless a robots group already sets one. An object
+     * states the whole policy: each permission left out is sent as `no`.
+     * `false` sends no Content-Signal line.
      */
     contentSignal?: false | {
         /**
@@ -524,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.iq1L3kll.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";
@@ -748,6 +772,58 @@ function resolveConfigurationWarnings(input) {
   return warnings;
 }
 
+const DEFAULT_CONTENT_SIGNAL = "search=yes, ai-input=yes";
+function resolveContentSignalPolicy(option) {
+  if (option === false)
+    return { _tag: "Disabled" };
+  if (option === void 0)
+    return { _tag: "Default" };
+  const value = (allowed) => allowed ? "yes" : "no";
+  return {
+    _tag: "Configured",
+    // One comma-separated line: validators reject one line per signal.
+    contentSignal: `ai-train=${value(option.aiTrain)}, search=${value(option.search)}, ai-input=${value(option.aiInput)}`,
+    ...option.contentUsage !== false && { contentUsage: `train-ai=${option.aiTrain ? "y" : "n"}` }
+  };
+}
+function hasContentSignal(value) {
+  if (Array.isArray(value))
+    return value.some(Boolean);
+  if (value && typeof value === "object")
+    return Object.keys(value).length > 0;
+  return Boolean(value);
+}
+function isWildcardGroup(group) {
+  const userAgents = Array.isArray(group.userAgent) ? group.userAgent : [group.userAgent ?? "*"];
+  return userAgents.length === 1 && userAgents[0] === "*";
+}
+function wildcardGroup(groups) {
+  const existing = groups.find(isWildcardGroup);
+  if (existing)
+    return existing;
+  const group = { userAgent: ["*"], disallow: [""] };
+  groups.push(group);
+  return group;
+}
+function applyContentSignalPolicy(groups, policy) {
+  switch (policy._tag) {
+    case "Disabled":
+      return;
+    case "Default": {
+      if (groups.some((group) => hasContentSignal(group.contentSignal)))
+        return;
+      wildcardGroup(groups).contentSignal = [DEFAULT_CONTENT_SIGNAL];
+      return;
+    }
+    case "Configured": {
+      const group = wildcardGroup(groups);
+      group.contentSignal = [policy.contentSignal];
+      if (policy.contentUsage)
+        group.contentUsage = [policy.contentUsage];
+    }
+  }
+}
+
 const DATABASE_TYPE_NONE = "none";
 const DATABASE_DEPENDENT_OPTIONS = ["runtimeSync", "cron"];
 const DATABASE_CONSUMER_LABELS = {
@@ -1071,6 +1147,7 @@ function parseMcpServerCardConfig(input) {
     }
   };
 }
+const MCP_SERVER_CARD_WELL_KNOWN_PATHS = ["/.well-known/mcp/server-card.json", "/.well-known/mcp.json"];
 function resolveMcpServerCardRoute(mcpRoute) {
   return `${mcpRoute.replace(/\/+$/, "") || "/mcp"}/server-card`;
 }
@@ -1166,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, "\\$&");
 }
@@ -1744,25 +1829,11 @@ ${details}`);
         (paths.resources ||= []).push(`${mcpRuntimeDir}/resources`);
     });
     const contentSource = await resolveContentSource(config.contentSource !== false);
-    if (typeof config.contentSignal === "object") {
-      const robotsOpts = nuxt.options.robots || {};
-      nuxt.options.robots = robotsOpts;
-      const groups = robotsOpts.groups || [];
-      robotsOpts.groups = groups;
-      const group = {
-        userAgent: "*",
-        // Preserve nuxt-robots' default wildcard rule so the injected group remains valid.
-        disallow: [""],
-        // Object form renders one comma-separated line; an array renders one line per entry, which validators reject.
-        contentSignal: {
-          "ai-train": config.contentSignal.aiTrain ? "yes" : "no",
-          "search": config.contentSignal.search ? "yes" : "no",
-          "ai-input": config.contentSignal.aiInput ? "yes" : "no"
-        }
-      };
-      if (config.contentSignal.contentUsage !== false)
-        group.contentUsage = [`train-ai=${config.contentSignal.aiTrain ? "y" : "n"}`];
-      groups.push(group);
+    const contentSignalPolicy = resolveContentSignalPolicy(config.contentSignal);
+    if (contentSignalPolicy._tag !== "Disabled") {
+      nuxt.hook("robots:config", (robotsConfig) => {
+        applyContentSignalPolicy(robotsConfig.groups, contentSignalPolicy);
+      });
     }
     registerTypeTemplates({ config, nitroCompatibility });
     const defaultLlmsTxtSections = [];
@@ -1789,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 || []
@@ -1876,18 +1952,21 @@ ${details}`);
           updateSeoProFeatures(seoProModules);
         return;
       }
-      const mcpLink = {
-        title: "MCP",
-        href: withSiteUrl(finalMcpToolkitState.route, { withBase: true }),
-        description: config.mcp?.tools !== false && hasMcpSiteTools ? "Use this MCP endpoint when you need information from this site's indexed pages." : "Model Context Protocol server endpoint for AI agent integration."
-      };
-      const firstSection = mergedLlmsTxt.sections?.[0];
-      if (firstSection) {
-        firstSection.links ||= [];
-        if (!firstSection.links.some((link) => link.title === mcpLink.title))
-          firstSection.links.push(mcpLink);
-      } else {
-        mergedLlmsTxt.sections = [{ title: "LLM Tools", links: [mcpLink] }];
+      if (mcpServerCardResult._tag === "Enabled") {
+        const endpoint = withSiteUrl(finalMcpToolkitState.route, { withBase: true });
+        const mcpLink = {
+          title: "MCP server card",
+          href: withSiteUrl(MCP_SERVER_CARD_WELL_KNOWN_PATHS[0].slice(1), { withBase: true }),
+          description: config.mcp?.tools !== false && hasMcpSiteTools ? `Connect an MCP client to ${endpoint} when you need information from this site's indexed pages.` : `Connect an MCP client to ${endpoint} to use this site's Model Context Protocol server.`
+        };
+        const firstSection = mergedLlmsTxt.sections?.[0];
+        if (firstSection) {
+          firstSection.links ||= [];
+          if (!firstSection.links.some((link) => link.title === mcpLink.title))
+            firstSection.links.push(mcpLink);
+        } else {
+          mergedLlmsTxt.sections = [{ title: "LLM Tools", links: [mcpLink] }];
+        }
       }
       const mcpServerCardRoute = resolveMcpServerCardRoute(finalMcpToolkitState.route);
       if (siteConfig.url && config.apiCatalog !== false) {
@@ -1964,21 +2043,23 @@ ${details}`);
         etag
       };
       const handler = resolve$1("./runtime/server/routes/mcp-server-card");
-      addServerHandler({ route: mcpServerCardRoute, method: "get", handler, lazy: true });
-      addServerHandler({ route: mcpServerCardRoute, method: "head", handler, lazy: true });
-      addServerHandler({ route: mcpServerCardRoute, method: "options", handler, lazy: true });
-      extendRouteRules(mcpServerCardRoute, {
-        sitemap: false,
-        headers: {
-          "Access-Control-Allow-Headers": "Content-Type, If-None-Match",
-          "Access-Control-Allow-Methods": "GET, HEAD",
-          "Access-Control-Allow-Origin": "*",
-          "Access-Control-Expose-Headers": "ETag",
-          "Cache-Control": `public, max-age=${mcpServerCardResult.config.cacheMaxAge}`,
-          "Content-Type": MCP_SERVER_CARD_MEDIA_TYPE,
-          "ETag": etag
-        }
-      });
+      for (const route of [mcpServerCardRoute, ...MCP_SERVER_CARD_WELL_KNOWN_PATHS]) {
+        addServerHandler({ route, method: "get", handler, lazy: true });
+        addServerHandler({ route, method: "head", handler, lazy: true });
+        addServerHandler({ route, method: "options", handler, lazy: true });
+        extendRouteRules(route, {
+          sitemap: false,
+          headers: {
+            "Access-Control-Allow-Headers": "Content-Type, If-None-Match",
+            "Access-Control-Allow-Methods": "GET, HEAD",
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Expose-Headers": "ETag",
+            "Cache-Control": `public, max-age=${mcpServerCardResult.config.cacheMaxAge}`,
+            "Content-Type": MCP_SERVER_CARD_MEDIA_TYPE,
+            "ETag": etag
+          }
+        });
+      }
       if (siteConfig.url) {
         const document = resolveAiCatalog({
           siteUrl: siteConfig.url,
@@ -2116,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,
@@ -2188,7 +2268,7 @@ export function trackDrizzleWork(event, work) { return work }
       const schemaPath = database._tag === "Enabled" && (database.type === "neon" || database.type === "postgres") ? "#ai-ready/server/db/schema/postgres" : "#ai-ready/server/db/schema/sqlite";
       nitroConfig.virtual["#ai-ready-virtual/db-schema.mjs"] = database._tag === "Enabled" ? `export * from '${schemaPath}'` : "export {}";
       nitroConfig.virtual["#ai-ready-virtual/devtools-meta.mjs"] = `export const devtoolsMeta = ${JSON.stringify({
-        contentSignal: config.contentSignal || false,
+        contentSignal: config.contentSignal ?? { search: true, aiInput: true },
         mcp: { enabled: mcpAvailable, tools: mcpAvailable && config.mcp?.tools !== false && hasMcpSiteTools, resources: mcpAvailable && config.mcp?.resources !== false },
         cron: !!config.cron
       })}`;
@@ -2249,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")
@@ -2402,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.0.4",
+  "version": "3.2.0",
   "description": "Best practice AI & LLM discoverability for Nuxt sites.",
   "author": {
     "name": "Harlan Wilton",

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

@@ -39,8 +39,9 @@ With no `aiReady` config, the module adds:
 - `/sitemap.md`, and a `## Sitemap` footer on every generated `.md` page. Set `sitemapMd: false` to remove both.
 - Nuxt Content v3 `page` collections: the `.md` route serves the source Markdown, not converted HTML. Set `contentSource: false` to convert HTML.
 - Agent skills: `public/skills/<name>/SKILL.md` in the project or a local layer is published at `/.well-known/agent-skills/`, `/skills/<name>/SKILL.md`, and in `llms.txt`. Custom public directories are supported. One local skill is also served at `/SKILL.md`. Set `agentSkills: false` to publish nothing.
+- `Content-Signal: search=yes, ai-input=yes` in `robots.txt`. Set `contentSignal: false` to remove it.
 
-Off by default: Content Signals, MCP, WebMCP, runtime sync, cron, and the database.
+Off by default: MCP, WebMCP, runtime sync, cron, and the database.
 
 ## Common tasks
 
@@ -76,14 +77,14 @@ export default defineNitroPlugin((nitroApp) => {
 })
 ```
 
-Allow Content Signals. An omitted permission renders as `no`:
+Content Signals. Without config, robots.txt gets `Content-Signal: search=yes, ai-input=yes` and no `ai-train`. A robots group or merged robots.txt that already sets `Content-Signal` replaces the default. `contentSignal: false` removes the line. An object states the whole policy, so an omitted permission renders as `no`:
 
 ```ts
-export default defineNuxtConfig({ aiReady: { contentSignal: { search: true } } })
-// robots.txt: Content-Signal: ai-train=no, search=yes, ai-input=no
+export default defineNuxtConfig({ aiReady: { contentSignal: { search: true, aiInput: true, aiTrain: false } } })
+// robots.txt: Content-Signal: ai-train=no, search=yes, ai-input=yes
 ```
 
-MCP: install `@nuxtjs/mcp-toolkit` and add it to `modules`. The module then registers `list_pages`, `search_pages`, and `get_page_markdown` at `/mcp`. These tools need the database, so also run `npx nypm add drizzle-orm@1.0.0-rc.4`. MCP needs a running server; `nuxt generate` output cannot host it.
+MCP: install `@nuxtjs/mcp-toolkit` and add it to `modules`. The module then registers `list_pages`, `search_pages`, and `get_page_markdown` at `/mcp`. These tools need the database, so also run `npx nypm add drizzle-orm@1.0.0-rc.4`. MCP needs a running server; `nuxt generate` output cannot host it. The server card is served at `/mcp/server-card`, `/.well-known/mcp/server-card.json`, and `/.well-known/mcp.json`. llms.txt links the card, never the endpoint, because the endpoint answers GET with 405 or 406. `mcpServerCard: false` removes the card routes and the llms.txt entry.
 
 WebMCP: set `webmcp: true`. This registers the same three tools in the browser and auto-imports `useWebMcpTool()` and `useWebMcpSupported()`. The tools need the database and `drizzle-orm`. Without `webmcp`, those composables are not defined.
 
@@ -94,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.
@@ -124,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`.