nuxt-ai-ready 2.4.1 → 2.5.0

package/README.md

@@ -3,6 +3,13 @@
 [![npm version][npm-version-src]][npm-version-href]
 [![npm downloads][npm-downloads-src]][npm-downloads-href]
 [![Nuxt][nuxt-src]][nuxt-href]
+<a href="https://skilld.dev/gh/harlan-zw/nuxt-ai-ready">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://skilld.dev/b/harlan-zw/nuxt-ai-ready?theme=dark">
+    <source media="(prefers-color-scheme: light)" srcset="https://skilld.dev/b/harlan-zw/nuxt-ai-ready?theme=light">
+    <img alt="Skill repository on skilld.dev" src="https://skilld.dev/b/harlan-zw/nuxt-ai-ready?theme=light">
+  </picture>
+</a>
 
 > Best practice AI & LLM discoverability for Nuxt sites. Score 100 on [`npx @vercel/agent-readability audit <URL>`](https://github.com/vercel-labs/agent-readability).
 
@@ -38,10 +45,7 @@ npx nuxi@latest module add nuxt-ai-ready
 ```
 
 > [!TIP]
-> Generate an Agent Skill for this package using [skilld](https://github.com/harlan-zw/skilld):
-> ```bash
-> npx skilld add nuxt-ai-ready
-> ```
+> Using an AI agent? Get the nuxt-ai-ready Skill on [skilld.dev/gh/harlan-zw/nuxt-ai-ready](https://skilld.dev/gh/harlan-zw/nuxt-ai-ready).
 
 💡 Made your site AI-ready? Preview how a page converts to LLM-readable markdown with the free [HTML→Markdown tool](https://nuxtseo.com/tools/html-to-markdown), or track how AI engines index, rank and cite your site with [Nuxt SEO Pro](https://nuxtseo.com/pro).
 

package/dist/chunks/agent-skills.mjs

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

package/dist/chunks/prerender.mjs

@@ -5,7 +5,7 @@ import { colorize } from 'consola/utils';
 import { resolveLocaleFromRoute } from 'nuxtseo-shared/i18n-runtime';
 import { collectSitemap } from 'sitemapd/parse';
 import { withLeadingSlash, joinURL, withBase } from 'ufo';
-import { l as logger, s as supportsNativeNodeSqlite, M as MARKDOWN_LINK_AVAILABILITY_FILE } from '../shared/nuxt-ai-ready.CxJE2WLA.mjs';
+import { l as logger, s as supportsNativeNodeSqlite, M as MARKDOWN_LINK_AVAILABILITY_FILE } from '../shared/nuxt-ai-ready.DsokNmXc.mjs';
 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';

package/dist/module.json

@@ -4,7 +4,7 @@
     "nuxt": ">=4.0.0"
   },
   "configKey": "aiReady",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -7,7 +7,7 @@ import 'defu';
 import 'nuxt-site-config/kit';
 import 'nuxtseo-shared/kit';
 import 'pkg-types';
-export { m as default } from './shared/nuxt-ai-ready.CxJE2WLA.mjs';
+export { m as default } from './shared/nuxt-ai-ready.DsokNmXc.mjs';
 import '../dist/runtime/markdown-path.js';
 import '../dist/runtime/server/utils/sitemap-md.js';
 import '../dist/runtime/server/utils/discovery-response.js';

package/dist/runtime/app/plugins/md-hints.prerender.js

@@ -1,6 +1,5 @@
-import { isPathFile } from "nuxt-site-config/urls";
 import { defineNuxtPlugin, prerenderRoutes } from "nuxt/app";
-import { toMarkdownPath } from "../../markdown-path.js";
+import { markdownAlternatePath } from "../../markdown-path.js";
 export default defineNuxtPlugin({
   setup(nuxtApp) {
     if (!import.meta.prerender) {
@@ -8,10 +7,11 @@ export default defineNuxtPlugin({
     }
     nuxtApp.hooks.hook("app:rendered", (ctx) => {
       const url = ctx.ssrContext?.url || "";
-      if (isPathFile(url) || ctx.ssrContext?.error || ctx.ssrContext?.noSSR) {
+      const markdownPath = markdownAlternatePath(url);
+      if (!markdownPath || ctx.ssrContext?.error || ctx.ssrContext?.noSSR) {
         return;
       }
-      prerenderRoutes(toMarkdownPath(url));
+      prerenderRoutes(markdownPath);
     });
   }
 });

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

@@ -4,16 +4,12 @@ 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 { isReservedPath, toMarkdownPath } from "./markdown-path.js";
+import { hasMarkdownTwin, toMarkdownPath } from "./markdown-path.js";
 import { normalizePersistedRoute, toDeployedRoute, toLogicalRoute } from "./route-path.js";
 import { queryPages } from "./server/db/queries.js";
 import { logger } from "./server/logger.js";
 import { fetchSitemapUrls } from "./server/utils/sitemap.js";
 export { normalizeLlmsTxtConfig };
-function hasRuntimeMarkdownHandler(pathname) {
-  const lastSegment = pathname.split("/").pop() || "";
-  return !isReservedPath(pathname) && !lastSegment.includes(".");
-}
 async function findMarkdownLinkAvailability() {
   if (!import.meta.prerender) {
     return {
@@ -205,7 +201,7 @@ Canonical Origin: ${canonicalSiteUrl}`);
     resolvePageHref = (pathname) => {
       const deployedPathname = resolvePath(pathname);
       const markdownPath = resolvePath(toMarkdownPath(pathname));
-      if (markdownLinkAvailability.paths.has(decodePath(markdownPath)) || markdownLinkAvailability.runtimeMarkdownAvailable && hasRuntimeMarkdownHandler(pathname)) {
+      if (markdownLinkAvailability.paths.has(decodePath(markdownPath)) || markdownLinkAvailability.runtimeMarkdownAvailable && hasMarkdownTwin(pathname)) {
         return markdownPath;
       }
       return deployedPathname;

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

@@ -3,9 +3,13 @@ export declare function isReservedPath(path: string): boolean;
 export declare function normalizePagePath(path: string): string;
 export declare function toMarkdownPath(path: string): string;
 /**
- * The `.md` sibling a page may advertise, or null when it has none.
+ * True when a path names a page with a `.md` twin: outside the reserved
+ * namespaces, and not a file such as `/feed.xml`. A dot alone does not make a
+ * file, so `/v1.2` is a page.
  *
- * Advertising and serving read the same predicate here, so a page cannot link
- * a representation the markdown handler declines.
+ * Prerendering and every advertisement read this one predicate, so a page
+ * cannot link a representation the build or the markdown handler lacks.
  */
+export declare function hasMarkdownTwin(path: string): boolean;
+/** The `.md` sibling a page may advertise, or null when it has none. */
 export declare function markdownAlternatePath(path: string): string | null;

package/dist/runtime/markdown-path.js

@@ -1,4 +1,5 @@
 const RE_TRAILING_SLASHES = /\/+$/;
+const RE_FILE_EXTENSION = /\.[a-z][a-z\d]*$/i;
 const RE_RESERVED_PATH = /^\/(?:api(?:\/|$)|_|@(?:id|fs|vite|react-refresh)(?:\/|$))/;
 export function isReservedPath(path) {
   return RE_RESERVED_PATH.test(path);
@@ -12,11 +13,10 @@ export function toMarkdownPath(path) {
     return "/index.md";
   return `${normalizedPath}.md`;
 }
-export function markdownAlternatePath(path) {
-  if (isReservedPath(path))
-    return null;
+export function hasMarkdownTwin(path) {
   const lastSegment = normalizePagePath(path).split("/").pop() || "";
-  if (lastSegment.includes("."))
-    return null;
-  return toMarkdownPath(path);
+  return !isReservedPath(path) && !RE_FILE_EXTENSION.test(lastSegment);
+}
+export function markdownAlternatePath(path) {
+  return hasMarkdownTwin(path) ? toMarkdownPath(path) : null;
 }

package/dist/runtime/server/db/queries.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "uncrypto";
 import { useEvent, useRuntimeConfig } from "#nuxtseo/nitro";
+import { checkAndHandleStale } from "../utils/checkStale.js";
 import { parseSitemapCrawlState, serializeSitemapCrawlState } from "../utils/sitemap-crawl-state.js";
 import { initSchema } from "./drizzle/queries.js";
 import { useRawDb } from "./drizzle/raw.js";
@@ -17,6 +18,24 @@ function getEventFromContext(providedEvent) {
 }
 let devWarningShown = false;
 let schemaInitializationState = { _tag: "Uninitialized" };
+let dumpSyncState = { _tag: "Pending" };
+function syncBuildDump(event) {
+  if (dumpSyncState._tag === "Synced")
+    return Promise.resolve();
+  if (dumpSyncState._tag === "Syncing")
+    return dumpSyncState.promise;
+  const promise = checkAndHandleStale(event).then(
+    () => {
+      dumpSyncState = { _tag: "Synced" };
+    },
+    (error) => {
+      dumpSyncState = { _tag: "Pending" };
+      throw error;
+    }
+  );
+  dumpSyncState = { _tag: "Syncing", promise };
+  return promise;
+}
 const RE_FTS_CHARS = /[*:^"()]/g;
 const RE_WHITESPACE = /\s+/;
 async function getDb(event) {
@@ -32,7 +51,8 @@ async function getDb(event) {
   }
   const resolvedEvent = getEventFromContext(event);
   const cfg = useRuntimeConfig(resolvedEvent);
-  if (cfg["nuxt-ai-ready"]?.database?._tag === "Disabled")
+  const database = cfg["nuxt-ai-ready"]?.database?._tag;
+  if (database === "Disabled")
     return null;
   const db = await useRawDb(resolvedEvent);
   if (schemaInitializationState._tag === "Uninitialized") {
@@ -46,6 +66,8 @@ async function getDb(event) {
   }
   if (schemaInitializationState._tag === "Initializing")
     await schemaInitializationState.promise;
+  if (database === "Enabled")
+    await syncBuildDump(resolvedEvent);
   return db;
 }
 async function getPrerenderDb() {

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

@@ -165,7 +165,7 @@ ${contentPage.markdown}`);
     canonicalUrl,
     config.mdreamOptions,
     {
-      hooks: { route: path, event },
+      hooks: { route: path, event, isPrerender: false },
       additionalFrontmatter
     }
   );

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

@@ -104,6 +104,7 @@ ${contentPage.markdown}`;
     runtimeConfig.mdreamOptions,
     {
       extractUpdatedAt: true,
+      hooks: { route: path, event, isPrerender: true },
       additionalFrontmatter: {
         canonical_url: canonicalUrl,
         ...lastUpdated && { last_updated: lastUpdated }

package/dist/runtime/server/utils/checkStale.js

@@ -10,9 +10,17 @@ import {
 import { decompressFromBase64, importDbDump } from "../db/shared.js";
 import { logger } from "../logger.js";
 import { fetchPublicAsset } from "./cloudflare.js";
+function parseBuildMeta(value) {
+  if (!value || typeof value !== "object")
+    return null;
+  const { buildId, pageCount, createdAt } = value;
+  if (typeof buildId !== "string" || !buildId || typeof pageCount !== "number")
+    return null;
+  return { buildId, pageCount, createdAt: typeof createdAt === "string" ? createdAt : "" };
+}
 async function fetchBuildMeta(event) {
   logger.debug("[stale-check] Fetching meta...");
-  return fetchPublicAsset(event, "/__ai-ready/pages.meta.json");
+  return parseBuildMeta(await fetchPublicAsset(event, "/__ai-ready/pages.meta.json"));
 }
 async function fetchDump(event) {
   logger.debug("[stale-check] Fetching dump...");
@@ -22,7 +30,10 @@ async function fetchDump(event) {
     return null;
   }
   logger.debug(`[stale-check] Decompressing dump (${(dumpData.length / 1024).toFixed(1)}kb)...`);
-  return decompressFromBase64(dumpData);
+  return decompressFromBase64(dumpData).catch((error) => {
+    logger.warn("[stale-check] Build dump is unreadable, skipping restore:", error);
+    return null;
+  });
 }
 async function getStoredBuildId(event) {
   return getInfoValue(event, "build_id");

package/dist/runtime/server/utils/cloudflare.js

@@ -1,3 +1,5 @@
+import { withBase } from "ufo";
+import { useRuntimeConfig } from "#nuxtseo/nitro";
 const FETCH_TIMEOUT = 5e3;
 function unavailablePublicAsset(_error) {
   return null;
@@ -29,7 +31,7 @@ export async function fetchPublicAsset(event, path, options) {
   }
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
-  return globalThis.$fetch(path, {
+  return globalThis.$fetch(withBase(path, useRuntimeConfig(event).app.baseURL), {
     baseURL: "/",
     signal: controller.signal,
     responseType

package/dist/runtime/server/utils/frontmatter.d.ts

@@ -12,4 +12,10 @@ interface FrontmatterFields {
 }
 export declare function buildFrontmatter(fields: FrontmatterFields): string;
 export declare function layerFrontmatter(fields: FrontmatterFields, markdown: string): string;
+/**
+ * Move mdream's `meta.description` to a root `description` field, the shape
+ * Content source pages and hand-built frontmatter already use. Other `meta`
+ * fields stay where mdream put them.
+ */
+export declare function hoistMetaDescription(markdown: string): string;
 export {};

package/dist/runtime/server/utils/frontmatter.js

@@ -1,4 +1,4 @@
-import { isMap, parseDocument } from "yaml";
+import { isMap, isScalar, parseDocument } from "yaml";
 function escapeYamlString(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
@@ -43,3 +43,25 @@ ${document.toString({ lineWidth: 0 }).trimEnd()}
 
 ${body}`;
 }
+export function hoistMetaDescription(markdown) {
+  const match = markdown.match(FRONTMATTER_RE);
+  if (!match)
+    return markdown;
+  const document = parseDocument(match[1]);
+  const root = document.contents;
+  const meta = document.get("meta");
+  if (document.errors.length || !isMap(root) || !isMap(meta) || !meta.has("description"))
+    return markdown;
+  const description = meta.get("description", true);
+  meta.delete("description");
+  if (!meta.items.length)
+    document.delete("meta");
+  if (!document.has("description")) {
+    const titleIndex = root.items.findIndex((pair) => isScalar(pair.key) && pair.key.value === "title");
+    root.items.splice(titleIndex + 1, 0, document.createPair("description", description));
+  }
+  return `---
+${document.toString({ lineWidth: 0 }).trimEnd()}
+---
+${markdown.slice(match[0].length)}`;
+}

package/dist/runtime/server/utils/indexPage.js

@@ -19,7 +19,10 @@ export async function indexPage(route, html, options = {}, event) {
   const isError = html.includes("__NUXT_ERROR__") || html.includes("nuxt-error-page");
   const { siteUrl } = createUniversalContext(event);
   const fullUrl = siteUrl ? `${siteUrl}${route}` : route;
-  const result = await convertHtmlToMarkdown(html, fullUrl, config.mdreamOptions, { extractUpdatedAt: true });
+  const result = await convertHtmlToMarkdown(html, fullUrl, config.mdreamOptions, {
+    extractUpdatedAt: true,
+    hooks: { route, event, isPrerender: false }
+  });
   const headings = JSON.stringify(result.headings);
   const keywords = extractKeywords(result.textContent, result.metaKeywords);
   const contentHash = await computeContentHash(result.markdown);

package/dist/runtime/server/utils/sitemap-routes.js

@@ -1,8 +1,9 @@
+import { hasMarkdownTwin } from "../../markdown-path.js";
 export function mapSitemapRoutes(urls) {
   const routeToUrl = /* @__PURE__ */ new Map();
   for (const url of urls) {
     const route = url._path?.pathname ?? (url.loc.startsWith("/") ? url.loc.split("?")[0] ?? url.loc : new URL(url.loc).pathname);
-    if (!route.includes("."))
+    if (hasMarkdownTwin(route))
       routeToUrl.set(route, url);
   }
   return routeToUrl;

package/dist/runtime/server/utils.d.ts

@@ -4,15 +4,19 @@ export declare function extractLastUpdated(html: string): string | undefined;
 interface ConvertHtmlOptions {
     /** Extract updatedAt from meta tags */
     extractUpdatedAt?: boolean;
-    /** Call runtime hooks (ai-ready:mdreamConfig, ai-ready:page:markdown) */
-    hooks?: {
+    /**
+     * Context for the Nitro hooks (ai-ready:mdreamConfig, ai-ready:page:markdown).
+     * Every conversion runs them, so prerender, runtime and indexing agree.
+     */
+    hooks: {
         route: string;
-        event: H3Event;
+        event?: H3Event;
+        isPrerender: boolean;
     };
     /** Extra fields to inject at the root of mdream's emitted YAML frontmatter */
     additionalFrontmatter?: Record<string, string>;
 }
-export declare function convertHtmlToMarkdown(html: string, url: string, mdreamOptions: ModuleOptions['mdreamOptions'], opts?: ConvertHtmlOptions): Promise<{
+export declare function convertHtmlToMarkdown(html: string, url: string, mdreamOptions: ModuleOptions['mdreamOptions'], opts: ConvertHtmlOptions): Promise<{
     updatedAt?: string | undefined;
     markdown: string;
     title: string;

package/dist/runtime/server/utils.js

@@ -1,5 +1,6 @@
 import { htmlToMarkdown } from "mdream";
 import { useNitroApp } from "#nuxtseo/nitro";
+import { hoistMetaDescription } from "./utils/frontmatter.js";
 const RE_NBSP = /\u00A0/g;
 function normalizeWhitespace(text) {
   return text.replace(RE_NBSP, " ");
@@ -67,27 +68,22 @@ export function extractLastUpdated(html) {
   }
   return void 0;
 }
-export async function convertHtmlToMarkdown(html, url, mdreamOptions, opts = {}) {
+export async function convertHtmlToMarkdown(html, url, mdreamOptions, opts) {
   const meta = { title: "", description: "", metaKeywords: "", headings: [], textContent: [] };
   const options = buildMdreamOptions(url, mdreamOptions, meta, opts.extractUpdatedAt ?? false, opts.additionalFrontmatter ?? {});
-  let markdown;
-  if (opts.hooks) {
-    const nitroApp = useNitroApp();
-    await nitroApp.hooks.callHook("ai-ready:mdreamConfig", options);
-    const context = {
-      html,
-      markdown: htmlToMarkdown(html, options),
-      route: opts.hooks.route,
-      title: meta.title,
-      description: meta.description,
-      isPrerender: false,
-      event: opts.hooks.event
-    };
-    await nitroApp.hooks.callHook("ai-ready:page:markdown", context);
-    markdown = context.markdown;
-  } else {
-    markdown = htmlToMarkdown(html, options);
-  }
+  const nitroApp = useNitroApp();
+  await nitroApp.hooks.callHook("ai-ready:mdreamConfig", options);
+  const context = {
+    html,
+    markdown: hoistMetaDescription(htmlToMarkdown(html, options)),
+    route: opts.hooks.route,
+    title: meta.title,
+    description: meta.description,
+    isPrerender: opts.hooks.isPrerender,
+    event: opts.hooks.event
+  };
+  await nitroApp.hooks.callHook("ai-ready:page:markdown", context);
+  const markdown = context.markdown;
   return {
     markdown: normalizeWhitespace(markdown),
     title: normalizeWhitespace(meta.title),

package/dist/runtime/types.d.ts

@@ -406,8 +406,9 @@ export interface PageDocument {
 /**
  * Hook context for markdown processing (Nitro runtime hook)
  *
- * This hook is called during HTML→Markdown conversion in the runtime middleware.
- * You can modify the markdown content before it's returned to the client.
+ * This hook is called for every HTML→Markdown conversion: runtime `.md`
+ * requests, prerendering, and page indexing. Modify the markdown content
+ * before the module serves, writes, or stores it.
  *
  * @example Modify markdown content
  * nitroApp.hooks.hook('ai-ready:page:markdown', async (context) => {
@@ -438,8 +439,11 @@ export interface MarkdownContext {
     description: string;
     /** Whether this is during prerendering (true) or runtime (false) */
     isPrerender: boolean;
-    /** The H3 event object for accessing request/response */
-    event: H3Event;
+    /**
+     * The H3 event object for accessing request/response. Undefined when
+     * indexing runs outside a request, such as a scheduled task.
+     */
+    event?: H3Event;
 }
 /**
  * Markdown a site already holds for a route, supplied instead of converting the

package/dist/shared/{nuxt-ai-ready.CxJE2WLA.mjs → nuxt-ai-ready.DsokNmXc.mjs}

@@ -2,13 +2,13 @@ import { createHash, randomBytes } from 'node:crypto';
 import { readFile, mkdir, writeFile, access } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import { dirname, basename, join } from 'node:path';
-import { hasNuxtModule, useNuxt, useLogger, addTypeTemplate, addTemplate, defineNuxtModule, createResolver, addServerImports, addServerPlugin, addServerHandler, extendRouteRules, addPlugin, addImports } from '@nuxt/kit';
+import { hasNuxtModule, useNuxt, useLogger, addTypeTemplate, addTemplate, defineNuxtModule, createResolver, addServerImports, addServerHandler, extendRouteRules, addServerPlugin, addPlugin, addImports } from '@nuxt/kit';
 import defu$1, { defu } from 'defu';
 import { installNuxtSiteConfig, useSiteConfig, withSiteUrl } from 'nuxt-site-config/kit';
 import { resolveNuxtContentVersion, renderNitroTypeAugmentations, setupNitroRuntimeCompatibility } from 'nuxtseo-shared/kit';
 import { readPackageJSON, resolvePackageJSON } from 'pkg-types';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { isReservedPath, normalizePagePath, toMarkdownPath } from '../../dist/runtime/markdown-path.js';
+import { hasMarkdownTwin, normalizePagePath, toMarkdownPath } from '../../dist/runtime/markdown-path.js';
 import { SITEMAP_MD_ROUTE } from '../../dist/runtime/server/utils/sitemap-md.js';
 import { publicCacheControl } from '../../dist/runtime/cache-control.js';
 import { MCP_SERVER_CARD_MEDIA_TYPE, AI_CATALOG_MEDIA_TYPE } from '../../dist/runtime/server/utils/discovery-response.js';
@@ -912,11 +912,7 @@ const RE_MD_EXT = /\.md$/;
 function isStaticMarkdownSourceRoute(route) {
   if (route.includes("*") || route.includes(":"))
     return false;
-  const path = route.split("?")[0] || route;
-  if (isReservedPath(path))
-    return false;
-  const lastSegment = path.split("/").pop() || "";
-  return !lastSegment.includes(".");
+  return hasMarkdownTwin(route.split("?")[0] || route);
 }
 function staticDescribedbyEntry(baseURL) {
   return `<${encodeURI(toDeployedRoute("/llms.txt", baseURL))}>; rel="describedby"`;
@@ -1467,8 +1463,6 @@ ${details}`);
           updateSeoProFeatures(seoProModules);
         return;
       }
-      if (databaseEnabled)
-        addServerPlugin(resolve("./runtime/server/plugins/mcp-data"));
       const mcpLink = {
         title: "MCP",
         href: withSiteUrl(finalMcpToolkitState.route, { withBase: true }),
@@ -1610,7 +1604,7 @@ ${details}`);
     if (!runtimeSyncSecret && runtimeSyncEnabled) {
       runtimeSyncSecret = randomBytes(32).toString("hex");
       if (!nuxt.options.dev && !nuxt.options._prepare)
-        logger.info(`Generated runtimeSyncSecret (use NUXT_AI_READY_RUNTIME_SYNC_SECRET env to set explicitly)`);
+        logger.info("Generated a new runtimeSyncSecret for this build. If an external scheduler calls /__ai-ready/*, set NUXT_AI_READY_RUNTIME_SYNC_SECRET; the generated secret changes on every build.");
     }
     if (runtimeSyncSecret) {
       const cacheDir = join(nuxt.options.rootDir, "node_modules/.cache/nuxt/ai-ready");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-ai-ready",
   "type": "module",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "description": "Best practice AI & LLM discoverability for Nuxt sites.",
   "author": {
     "name": "Harlan Wilton",
@@ -42,12 +42,12 @@
   "files": [
     "dist",
     "mcp.d.ts",
+    "skills",
     "webmcp.d.ts"
   ],
   "peerDependencies": {
     "@libsql/client": "^0.18.0",
     "@neondatabase/serverless": "^1.0.0",
-    "@nuxtjs/sitemap": ">=8.3.1",
     "better-sqlite3": "^11.0.0 || ^12.0.0 || ^13.0.0",
     "postgres": "^3.4.9"
   },
@@ -68,6 +68,8 @@
   "dependencies": {
     "@mdream/js": "^1.7.2",
     "@nuxt/kit": "^4.5.2",
+    "@nuxtjs/robots": "^6.2.3",
+    "@nuxtjs/sitemap": "^8.5.1",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "defu": "^6.1.7",
@@ -93,8 +95,6 @@
     "@nuxt/test-utils": "^4.3.2",
     "@nuxtjs/eslint-config-typescript": "^12.1.0",
     "@nuxtjs/mcp-toolkit": "^0.21.0",
-    "@nuxtjs/robots": "^6.2.3",
-    "@nuxtjs/sitemap": "^8.5.1",
     "@types/better-sqlite3": "^9.6.0",
     "@vitest/coverage-v8": "^5.0.1",
     "@vue/test-utils": "^2.5.1",

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

@@ -0,0 +1,123 @@
+---
+name: nuxt-ai-ready
+description: Add, configure, or debug AI and LLM discoverability in a Nuxt site with the nuxt-ai-ready module. Use when a task mentions llms.txt, llms-full.txt, serving pages as Markdown (.md routes, Accept text/markdown), an MCP server for site content, WebMCP or useWebMcpTool, Content Signals in robots.txt, agent skills discovery, runtime page indexing, queryPages or searchPages, or the aiReady config key. Gives the automatic outputs, the build versus runtime split, and the traps that leave output empty or stale.
+---
+
+# nuxt-ai-ready
+
+Tested against `nuxt-ai-ready` 2.4.1 plus its unreleased fixes on `main`, on Nuxt 4.5 and Node 24 (requires Nuxt `>=4.0.0`).
+The module converts rendered pages to Markdown with mdream and publishes `llms.txt`, `llms-full.txt`, and `.md` twins.
+Optional parts add MCP tools, WebMCP tools, and a runtime page index. Config key: `aiReady`. Docs: https://nuxtseo.com/ai-ready
+
+## Setup
+
+The package installs `@nuxtjs/robots` and `@nuxtjs/sitemap` and loads them as module dependencies. Configure them with the `robots` and `sitemap` keys.
+
+```bash
+pnpm add nuxt-ai-ready
+```
+
+Set `site.url`. Canonical URLs, `Link` headers, and `/.well-known/ai-catalog.json` use it.
+Prerender the pages you want in `llms-full.txt` and in the page index (`nuxi generate`, or `nitro.prerender.routes`).
+A page visit in dev or production does not index anything.
+
+## Automatic behaviour
+
+With no `aiReady` config, the module adds:
+
+- `/llms.txt`: site name, description, resource links, and a `## Pages` list. In dev it lists sitemap routes without titles.
+- `/llms-full.txt`: the full Markdown of each prerendered page. Only prerendered pages go in the static file.
+- A `.md` twin per page. `/about` becomes `/about.md`, and `/` becomes `/index.md`. Paths under `/api` and `/_` get none.
+- Accept negotiation: a request that prefers `text/markdown`, or a known AI bot user agent, gets a `307` to the `.md` URL.
+- `<link rel="alternate" type="text/markdown">` and `<link rel="describedby" href="/llms.txt">` in HTML, plus matching `Link` headers.
+- `/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: every `skills/<name>/SKILL.md` in the project root or a local layer is published at `/.well-known/agent-skills/`, at `/skills/<name>/SKILL.md`, and in `llms.txt`. With one skill it is also served at `/SKILL.md`. Set `agentSkills: false` to publish nothing.
+
+Off by default: Content Signals, MCP, WebMCP, runtime sync, cron, and the database.
+
+## Common tasks
+
+Add llms.txt sections. `notes` renders before the first heading:
+
+```ts
+export default defineNuxtConfig({
+  aiReady: {
+    llmsTxt: {
+      sections: [{ title: 'API Reference', links: [{ title: 'REST API', href: '/docs/api', description: 'API docs' }] }],
+      notes: 'Built with Nuxt AI Ready',
+    },
+  },
+})
+```
+
+Remove an element from the Markdown on every path, build and runtime. Put it in `mdreamOptions`; the defaults `minimal` and `clean` stay on:
+
+```ts
+export default defineNuxtConfig({
+  aiReady: { mdreamOptions: { filter: { exclude: ['.author-bio'] } } },
+})
+```
+
+Change the Markdown text. The Nitro hook covers runtime `.md` responses, prerendered `.md` files, `llms-full.txt`, and indexed pages. `ctx.isPrerender` is `true` only during prerendering:
+
+```ts
+// server/plugins/markdown.ts
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('ai-ready:page:markdown', (ctx) => {
+    ctx.markdown += '\n\nSee /support.'
+  })
+})
+```
+
+Allow Content Signals. 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
+```
+
+MCP: install `@nuxtjs/mcp-toolkit` and add it to `modules`. The module then registers `list_pages`, `search_pages`, and `get_page_markdown` at `/mcp`. MCP needs a running server; `nuxi generate` output cannot host it.
+
+WebMCP: set `webmcp: true`. This registers the same three tools in the browser and auto-imports `useWebMcpTool()` and `useWebMcpSupported()`. Without `webmcp`, those composables are not defined.
+
+Runtime indexing, database drivers, Cloudflare D1, and the server query helpers: see [references/runtime-indexing.md](references/runtime-indexing.md).
+
+## Traps
+
+- **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 `nuxi dev`. Test with `nuxi build` and `node .output/server/index.mjs`.
+- **Response caching turns negotiation off.** An ISR, `swr`, or `cache` route rule without `varies: ['accept', 'sec-fetch-dest', 'user-agent']` serves HTML to Markdown clients. 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.
+- **A project `skills/` folder is public.** Agent skills discovery publishes it with no opt in. Rename the folder with `agentSkills.dir`, or set `agentSkills: false`.
+- **The same hook name exists twice.** `ai-ready:page:markdown` is a Nuxt hook (`nuxt.config` `hooks`, prerender only) and a Nitro hook (`nitroApp.hooks`, every HTML conversion). They receive different context. The Nitro `ctx.event` is undefined when indexing runs outside a request.
+- **`database: false` conflicts with `runtimeSync` and `cron`.** The build fails and names the option.
+
+## Version limits
+
+- v2 removed IndexNow. The `indexNow` option and `/__ai-ready/indexnow` no longer exist. Submit URLs from the `ai-ready:page:indexed` Nitro hook: https://nuxtseo.com/docs/ai-ready/advanced/indexnow
+- v1 renamed these. Do not write the old form:
+
+| Old | New |
+|-----|-----|
+| `mdreamOptions: { preset: 'minimal' }` | `mdreamOptions: { minimal: true }` |
+| `cacheMaxAgeSeconds` | `llmsTxtCacheSeconds` |
+| Nitro hook `ai-ready:markdown` | `ai-ready:page:markdown` |
+| `BulkDocument` type | `PageDocument` |
+| `JSON.parse(page.headings)` | `page.headings` (already an array) |
+| `?secret=TOKEN` on `/__ai-ready/*` | `Authorization: Bearer TOKEN` header |
+
+## Config
+
+- `llmsTxt.markdownLinks` (`false`): link page entries in `llms.txt` to their `.md` twins.
+- `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`.
+- Other options: https://nuxtseo.com/docs/ai-ready/api/config
+
+## Debug
+
+- `curl -H 'Accept: text/markdown' -D - -o /dev/null <url>` must return `307` with `Location: <path>.md`. A `200` means a cache rule turned negotiation off.
+- `/__ai-ready__/debug.json` exists in dev, or with `debug: true`.
+- Nuxt DevTools has an AI Ready tab.

package/skills/nuxt-ai-ready/references/runtime-indexing.md

@@ -0,0 +1,75 @@
+# Runtime indexing and the page database
+
+Read this when pages change between deployments, or when server code queries stored pages.
+If each deployment prerenders all content, you do not need runtime sync.
+
+## When the database is on
+
+The database stays off until a feature needs it: `runtimeSync`, `cron`, MCP page tools, WebMCP page tools, or an explicit `database` config.
+Prerendering always writes a temporary SQLite index and a dump at `/__ai-ready/pages.dump`.
+
+Driver selection:
+
+| Platform | Driver | Install |
+|----------|--------|---------|
+| Node 22.13 and later | `node:sqlite` | nothing |
+| Node before 22.13 | `better-sqlite3` | `better-sqlite3`, or the build fails |
+| Bun | `bun:sqlite` | nothing |
+| Cloudflare preset | D1 | a binding |
+| Vercel with `POSTGRES_URL` | Neon | nothing |
+| `database: { type: 'postgres' }` | PostgreSQL | `postgres` |
+
+The build machine always uses SQLite, also for a D1 deployment.
+For D1, set `database: { type: 'd1', bindingName: 'AI_READY_DB' }` and create the binding yourself. The default binding name is `DB`.
+
+## Runtime sync
+
+```ts
+export default defineNuxtConfig({
+  aiReady: {
+    runtimeSync: { ttl: 3600, batchSize: 50, pruneTtl: 0 },
+    runtimeSyncSecret: process.env.NUXT_AI_READY_RUNTIME_SYNC_SECRET,
+    cron: true, // every 5 minutes, also enables runtimeSync
+  },
+})
+```
+
+Set `runtimeSyncSecret`. Without it, each build generates a new random secret, and external schedulers lose access after the next deployment.
+
+Every control endpoint needs `Authorization: Bearer <secret>`, including `GET /__ai-ready/status`. Only `POST /__ai-ready/prune?dry=true` works without it.
+
+| Request | Effect |
+|---------|--------|
+| `POST /__ai-ready/poll` | Index at most 50 pending pages. Repeat while `remaining > 0`. |
+| `POST /__ai-ready/reindex?route=/about` | Index one route now. The route does not need to be in the sitemap. |
+| `POST /__ai-ready/restore` | Replace stored pages with the build dump. |
+| `POST /__ai-ready/prune?ttl=604800` | Delete routes missing from the sitemap for that long. |
+| `GET /__ai-ready/cron` | Production only. For hosts without native cron. |
+
+Traps:
+
+- **TTL expiry does not reindex a page.** Poll and cron process only pending rows. After a CMS edit, call `reindex` for that route.
+- **Only prerendered pages are in the dump.** Each server process loads the dump before its first database query. A page that was not prerendered stays out of the index until poll, cron, or `reindex` adds it.
+- **Cloudflare Pages has no cron triggers.** Keep `cron: true` and call `GET /__ai-ready/cron` from an external scheduler. On Workers the module adds the trigger.
+
+## Server query helpers
+
+`queryPages`, `searchPages`, `countPages`, `streamPages`, `indexPage`, and `indexPageByRoute` are auto-imported in Nitro code. Other exports need `import { ... } from '#ai-ready'`.
+
+```ts
+// server/api/search.get.ts
+export default defineEventHandler(async (event) => {
+  const q = getQuery(event).q
+  if (typeof q !== 'string' || !q.trim())
+    return []
+  return searchPages(event, q, { limit: 10 })
+})
+```
+
+- `searchPages` returns `[]` in dev and during prerender. On SQLite and D1, `score` is BM25 and lower ranks first. PostgreSQL returns `score: 0`.
+- `queryPages(event, { route })` returns one page or `undefined`. Without `route` it returns an array. Add `includeMarkdown: true` for the body.
+- Raw SQL: `useRawDb` from `#ai-ready`. `useDatabase` does not exist.
+- The event goes in a different position: `indexPage(route, html, options, event)` and `indexPageByRoute(route, event, options)`.
+- `indexPage` throws on failure. `indexPageByRoute` returns `{ success: false, error }`.
+
+React to a changed page with the `ai-ready:page:indexed` Nitro hook. Check `ctx.contentChanged`; a forced reindex of the same content still fires the hook.

package/dist/runtime/server/plugins/mcp-data.d.ts

@@ -1,10 +0,0 @@
-import type { H3Event } from '#nuxtseo/h3';
-interface McpDataNitroApp {
-    hooks: {
-        hook: (name: 'mcp:config:resolved', handler: (payload: {
-            event: H3Event;
-        }) => Promise<void>) => unknown;
-    };
-}
-export default function mcpDataPlugin(nitroApp: McpDataNitroApp): void;
-export {};

package/dist/runtime/server/plugins/mcp-data.js

@@ -1,22 +0,0 @@
-import { checkAndHandleStale } from "../utils/checkStale.js";
-export default function mcpDataPlugin(nitroApp) {
-  let state = { _tag: "Idle" };
-  const ensureData = (event) => {
-    if (state._tag === "Ready")
-      return Promise.resolve();
-    if (state._tag === "Running")
-      return state.promise;
-    const promise = checkAndHandleStale(event).then(
-      () => {
-        state = { _tag: "Ready" };
-      },
-      (error) => {
-        state = { _tag: "Idle" };
-        return Promise.reject(error);
-      }
-    );
-    state = { _tag: "Running", promise };
-    return promise;
-  };
-  nitroApp.hooks.hook("mcp:config:resolved", ({ event }) => ensureData(event));
-}