nuxt-ai-ready 2.4.1 → 2.5.1

package/node_modules/pathe/dist/utils.cjs

@@ -0,0 +1,82 @@
+'use strict';
+
+const _path = require('./shared/pathe.BSlhyZSM.cjs');
+
+const pathSeparators = /* @__PURE__ */ new Set(["/", "\\", void 0]);
+const normalizedAliasSymbol = Symbol.for("pathe:normalizedAlias");
+const SLASH_RE = /[/\\]/;
+function normalizeAliases(_aliases) {
+  if (_aliases[normalizedAliasSymbol]) {
+    return _aliases;
+  }
+  const aliases = Object.fromEntries(
+    Object.entries(_aliases).sort(([a], [b]) => _compareAliases(a, b))
+  );
+  for (const key in aliases) {
+    for (const alias in aliases) {
+      if (alias === key || key.startsWith(alias)) {
+        continue;
+      }
+      if (aliases[key]?.startsWith(alias) && pathSeparators.has(aliases[key][alias.length])) {
+        aliases[key] = aliases[alias] + aliases[key].slice(alias.length);
+      }
+    }
+  }
+  Object.defineProperty(aliases, normalizedAliasSymbol, {
+    value: true,
+    enumerable: false
+  });
+  return aliases;
+}
+function resolveAlias(path, aliases) {
+  const _path$1 = _path.normalizeWindowsPath(path);
+  aliases = normalizeAliases(aliases);
+  for (const [alias, to] of Object.entries(aliases)) {
+    if (!_path$1.startsWith(alias)) {
+      continue;
+    }
+    const _alias = hasTrailingSlash(alias) ? alias.slice(0, -1) : alias;
+    if (hasTrailingSlash(_path$1[_alias.length])) {
+      return _path.join(to, _path$1.slice(alias.length));
+    }
+  }
+  return _path$1;
+}
+function reverseResolveAlias(path, aliases) {
+  const _path$1 = _path.normalizeWindowsPath(path);
+  aliases = normalizeAliases(aliases);
+  const matches = [];
+  for (const [to, alias] of Object.entries(aliases)) {
+    if (!_path$1.startsWith(alias)) {
+      continue;
+    }
+    const _alias = hasTrailingSlash(alias) ? alias.slice(0, -1) : alias;
+    if (hasTrailingSlash(_path$1[_alias.length])) {
+      matches.push(_path.join(to, _path$1.slice(alias.length)));
+    }
+  }
+  return matches.sort((a, b) => b.length - a.length);
+}
+function filename(path) {
+  const base = path.split(SLASH_RE).pop();
+  if (!base) {
+    return void 0;
+  }
+  const separatorIndex = base.lastIndexOf(".");
+  if (separatorIndex <= 0) {
+    return base;
+  }
+  return base.slice(0, separatorIndex);
+}
+function _compareAliases(a, b) {
+  return b.split("/").length - a.split("/").length;
+}
+function hasTrailingSlash(path = "/") {
+  const lastChar = path[path.length - 1];
+  return lastChar === "/" || lastChar === "\\";
+}
+
+exports.filename = filename;
+exports.normalizeAliases = normalizeAliases;
+exports.resolveAlias = resolveAlias;
+exports.reverseResolveAlias = reverseResolveAlias;

package/node_modules/pathe/dist/utils.d.cts

@@ -0,0 +1,32 @@
+/**
+ * Normalises alias mappings, ensuring that more specific aliases are resolved before less specific ones.
+ * This function also ensures that aliases do not resolve to themselves cyclically.
+ *
+ * @param _aliases - A set of alias mappings where each key is an alias and its value is the actual path it points to.
+ * @returns a set of normalised alias mappings.
+ */
+declare function normalizeAliases(_aliases: Record<string, string>): Record<string, string>;
+/**
+ * Resolves a path string to its alias if applicable, otherwise returns the original path.
+ * This function normalises the path, resolves the alias and then joins it to the alias target if necessary.
+ *
+ * @param path - The path string to resolve.
+ * @param aliases - A set of alias mappings to use for resolution.
+ * @returns the resolved path as a string.
+ */
+declare function resolveAlias(path: string, aliases: Record<string, string>): string;
+/**
+ * Resolves a path string to its possible alias.
+ *
+ * Returns an array of possible alias resolutions (could be empty), sorted by specificity (longest first).
+ */
+declare function reverseResolveAlias(path: string, aliases: Record<string, string>): string[];
+/**
+ * Extracts the filename from a given path, excluding any directory paths and the file extension.
+ *
+ * @param path - The full path of the file from which to extract the filename.
+ * @returns the filename without the extension, or `undefined` if the filename cannot be extracted.
+ */
+declare function filename(path: string): string | undefined;
+
+export { filename, normalizeAliases, resolveAlias, reverseResolveAlias };

package/node_modules/pathe/dist/utils.d.mts

@@ -0,0 +1,32 @@
+/**
+ * Normalises alias mappings, ensuring that more specific aliases are resolved before less specific ones.
+ * This function also ensures that aliases do not resolve to themselves cyclically.
+ *
+ * @param _aliases - A set of alias mappings where each key is an alias and its value is the actual path it points to.
+ * @returns a set of normalised alias mappings.
+ */
+declare function normalizeAliases(_aliases: Record<string, string>): Record<string, string>;
+/**
+ * Resolves a path string to its alias if applicable, otherwise returns the original path.
+ * This function normalises the path, resolves the alias and then joins it to the alias target if necessary.
+ *
+ * @param path - The path string to resolve.
+ * @param aliases - A set of alias mappings to use for resolution.
+ * @returns the resolved path as a string.
+ */
+declare function resolveAlias(path: string, aliases: Record<string, string>): string;
+/**
+ * Resolves a path string to its possible alias.
+ *
+ * Returns an array of possible alias resolutions (could be empty), sorted by specificity (longest first).
+ */
+declare function reverseResolveAlias(path: string, aliases: Record<string, string>): string[];
+/**
+ * Extracts the filename from a given path, excluding any directory paths and the file extension.
+ *
+ * @param path - The full path of the file from which to extract the filename.
+ * @returns the filename without the extension, or `undefined` if the filename cannot be extracted.
+ */
+declare function filename(path: string): string | undefined;
+
+export { filename, normalizeAliases, resolveAlias, reverseResolveAlias };

package/node_modules/pathe/dist/utils.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Normalises alias mappings, ensuring that more specific aliases are resolved before less specific ones.
+ * This function also ensures that aliases do not resolve to themselves cyclically.
+ *
+ * @param _aliases - A set of alias mappings where each key is an alias and its value is the actual path it points to.
+ * @returns a set of normalised alias mappings.
+ */
+declare function normalizeAliases(_aliases: Record<string, string>): Record<string, string>;
+/**
+ * Resolves a path string to its alias if applicable, otherwise returns the original path.
+ * This function normalises the path, resolves the alias and then joins it to the alias target if necessary.
+ *
+ * @param path - The path string to resolve.
+ * @param aliases - A set of alias mappings to use for resolution.
+ * @returns the resolved path as a string.
+ */
+declare function resolveAlias(path: string, aliases: Record<string, string>): string;
+/**
+ * Resolves a path string to its possible alias.
+ *
+ * Returns an array of possible alias resolutions (could be empty), sorted by specificity (longest first).
+ */
+declare function reverseResolveAlias(path: string, aliases: Record<string, string>): string[];
+/**
+ * Extracts the filename from a given path, excluding any directory paths and the file extension.
+ *
+ * @param path - The full path of the file from which to extract the filename.
+ * @returns the filename without the extension, or `undefined` if the filename cannot be extracted.
+ */
+declare function filename(path: string): string | undefined;
+
+export { filename, normalizeAliases, resolveAlias, reverseResolveAlias };

package/node_modules/pathe/dist/utils.mjs

@@ -0,0 +1,77 @@
+import { g as normalizeWindowsPath, j as join } from './shared/pathe.M-eThtNZ.mjs';
+
+const pathSeparators = /* @__PURE__ */ new Set(["/", "\\", void 0]);
+const normalizedAliasSymbol = Symbol.for("pathe:normalizedAlias");
+const SLASH_RE = /[/\\]/;
+function normalizeAliases(_aliases) {
+  if (_aliases[normalizedAliasSymbol]) {
+    return _aliases;
+  }
+  const aliases = Object.fromEntries(
+    Object.entries(_aliases).sort(([a], [b]) => _compareAliases(a, b))
+  );
+  for (const key in aliases) {
+    for (const alias in aliases) {
+      if (alias === key || key.startsWith(alias)) {
+        continue;
+      }
+      if (aliases[key]?.startsWith(alias) && pathSeparators.has(aliases[key][alias.length])) {
+        aliases[key] = aliases[alias] + aliases[key].slice(alias.length);
+      }
+    }
+  }
+  Object.defineProperty(aliases, normalizedAliasSymbol, {
+    value: true,
+    enumerable: false
+  });
+  return aliases;
+}
+function resolveAlias(path, aliases) {
+  const _path = normalizeWindowsPath(path);
+  aliases = normalizeAliases(aliases);
+  for (const [alias, to] of Object.entries(aliases)) {
+    if (!_path.startsWith(alias)) {
+      continue;
+    }
+    const _alias = hasTrailingSlash(alias) ? alias.slice(0, -1) : alias;
+    if (hasTrailingSlash(_path[_alias.length])) {
+      return join(to, _path.slice(alias.length));
+    }
+  }
+  return _path;
+}
+function reverseResolveAlias(path, aliases) {
+  const _path = normalizeWindowsPath(path);
+  aliases = normalizeAliases(aliases);
+  const matches = [];
+  for (const [to, alias] of Object.entries(aliases)) {
+    if (!_path.startsWith(alias)) {
+      continue;
+    }
+    const _alias = hasTrailingSlash(alias) ? alias.slice(0, -1) : alias;
+    if (hasTrailingSlash(_path[_alias.length])) {
+      matches.push(join(to, _path.slice(alias.length)));
+    }
+  }
+  return matches.sort((a, b) => b.length - a.length);
+}
+function filename(path) {
+  const base = path.split(SLASH_RE).pop();
+  if (!base) {
+    return void 0;
+  }
+  const separatorIndex = base.lastIndexOf(".");
+  if (separatorIndex <= 0) {
+    return base;
+  }
+  return base.slice(0, separatorIndex);
+}
+function _compareAliases(a, b) {
+  return b.split("/").length - a.split("/").length;
+}
+function hasTrailingSlash(path = "/") {
+  const lastChar = path[path.length - 1];
+  return lastChar === "/" || lastChar === "\\";
+}
+
+export { filename, normalizeAliases, resolveAlias, reverseResolveAlias };

package/node_modules/pathe/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "pathe",
+  "version": "2.0.3",
+  "description": "Universal filesystem path utils",
+  "repository": "unjs/pathe",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./utils": {
+      "import": {
+        "types": "./dist/utils.d.mts",
+        "default": "./dist/utils.mjs"
+      },
+      "require": {
+        "types": "./dist/utils.d.cts",
+        "default": "./dist/utils.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "utils.d.ts"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.13.1",
+    "@vitest/coverage-v8": "^3.0.5",
+    "changelogen": "^0.5.7",
+    "esbuild": "^0.25.0",
+    "eslint": "^9.20.1",
+    "eslint-config-unjs": "^0.4.2",
+    "jiti": "^2.4.2",
+    "prettier": "^3.5.0",
+    "typescript": "^5.7.3",
+    "unbuild": "^3.3.1",
+    "vitest": "^3.0.5",
+    "zeptomatch": "^2.0.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "dev": "vitest",
+    "lint": "eslint . && prettier -c src test",
+    "lint:fix": "eslint . --fix && prettier -w src test",
+    "release": "pnpm test && pnpm build && changelogen --release && pnpm publish && git push --follow-tags",
+    "test": "pnpm lint && vitest run --coverage",
+    "test:types": "tsc --noEmit"
+  }
+}

package/node_modules/pathe/utils.d.ts

@@ -0,0 +1 @@
+export * from "./dist/utils";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-ai-ready",
   "type": "module",
-  "version": "2.4.1",
+  "version": "2.5.1",
   "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"
   },
@@ -66,13 +66,15 @@
     }
   },
   "dependencies": {
-    "@mdream/js": "^1.7.2",
+    "@mdream/js": "2.0.0-beta.1",
     "@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",
     "drizzle-orm": "1.0.0-rc.4",
-    "mdream": "^1.7.2",
+    "mdream": "2.0.0-beta.1",
     "nuxt-site-config": "^4.2.3",
     "nuxtseo-shared": "^5.3.16",
     "pathe": "^2.0.3",
@@ -83,66 +85,8 @@
     "uncrypto": "^0.1.3",
     "yaml": "^2.9.1"
   },
-  "devDependencies": {
-    "@antfu/eslint-config": "^9.5.1",
-    "@arethetypeswrong/cli": "^0.18.5",
-    "@harlan-zw/comark-content": "^0.1.5",
-    "@libsql/client": "^0.18.0",
-    "@nuxt/content": "^3.16.1",
-    "@nuxt/module-builder": "^1.0.3",
-    "@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",
-    "@vueuse/nuxt": "^15.0.0",
-    "better-sqlite3": "^13.0.3",
-    "bumpp": "^12.3.0",
-    "eslint": "^10.11.0",
-    "eslint-plugin-harlanzw": "^0.23.0",
-    "execa": "^10.0.1",
-    "h3": "^1.15.11",
-    "happy-dom": "^20.14.5",
-    "nitropack": "^2.13.4",
-    "nuxt": "^4.5.2",
-    "nuxt-site-config": "^4.2.3",
-    "nuxtseo-layer-devtools": "^5.3.16",
-    "playwright": "^1.63.0",
-    "playwright-core": "^1.63.0",
-    "postgres": "^3.4.9",
-    "tinyglobby": "^0.2.17",
-    "typescript": "6.0.3",
-    "unbuild": "^3.6.1",
-    "vitest": "^5.0.1",
-    "vue": "^3.5.43",
-    "vue-router": "^5.3.1",
-    "vue-tsc": "^3.3.11",
-    "wrangler": "^4.136.3",
-    "zod": "^4.6.5"
-  },
-  "scripts": {
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "build": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt-module-build build && pnpm run build:devtools && pnpm run test:dist",
-    "build:devtools": "node -e \"require('fs').cpSync('devtools','dist/devtools',{recursive:true})\"",
-    "dev": "nuxt dev playground",
-    "dev:minimal": "nuxt dev playground",
-    "prepare:fixtures": "nuxt prepare playground && nuxt prepare playground && nuxt prepare test/fixtures/basic",
-    "dev:build": "nuxt build playground",
-    "dev:build:minimal": "nuxt build playground",
-    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt-module-build build && nuxt prepare playground && pnpm run build:devtools",
-    "dev:prepare:minimal": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt-module-build build && nuxt prepare playground",
-    "release": "pnpm build && bumpp -x \"npx changelogen --output=CHANGELOG.md\"",
-    "test": "pnpm run prepare:fixtures && vitest",
-    "test:run": "pnpm run prepare:fixtures && vitest run && pnpm test:nuxt5",
-    "test:unit": "vitest run --project=unit",
-    "test:e2e": "pnpm run prepare:fixtures && vitest run --project=e2e",
-    "test:dist": "node scripts/check-dist-imports.mjs",
-    "typecheck": "nuxt typecheck && tsc -p test/types/tsconfig.json",
-    "test:attw": "attw --pack",
-    "test:nuxt5": "pnpm pack --out test/fixtures/nuxt5/module.tgz && pnpm install --dir test/fixtures/nuxt5 --no-frozen-lockfile --force --update-checksums && pnpm --dir test/fixtures/nuxt5 test"
-  }
-}
+  "bundledDependencies": [
+    "mdream",
+    "@mdream/js"
+  ]
+}

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));
-}