---
title: "v1.0.0"
description: "Release notes for Nuxt AI Ready v1."
canonical_url: "https://nuxtseo.com/docs/ai-ready/releases/v1"
last_updated: "2026-09-25T20:12:29.320Z"
---

## Introduction

This page records the v1 release and its migration path. For a new installation, use the [current guide](/docs/ai-ready/getting-started/installation).

Nuxt AI Ready v1 renamed configuration and hooks, changed endpoint authentication, and adopted mdream v1.

The migration to [mdream v1](https://github.com/harlan-zw/nuxt-ai-ready/commit/931e6ef) changed HTML-to-Markdown options.
The release also unified heading types and fixed cron locking.

Most breaking changes have a **backward compatibility layer** that emits deprecation warnings, for the deprecated patterns listed below. See the full [migration steps](#breaking-changes) and [compat shims](#migration-assistance) below, or paste the [agent migration prompt](#agent-migration-prompt) into your AI coding tool to prepare the migration. Review its changes before deploying.

## 🧠 Mdream v1

The HTML to Markdown engine has been rewritten. mdream v1 ships a native Rust engine, [WebAssembly](https://webassembly.org) for edge runtimes, and a simpler declarative API while keeping the JS engine available as `@mdream/js` for users who need imperative hook based plugins. The `preset` option is replaced by top-level flags, and extraction plugins are now declarative objects instead of function wrappers.

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  aiReady: {
    mdreamOptions: {
      minimal: true,
      clean: true
    }
  }
})
```

## 📊 Enhanced CLI Status

The `nuxt-ai-ready status` command now shows richer diagnostics: activity stats (1h/24h), recent pages, IndexNow backoff status, cron run history, and sitemap health.

## 🔐 Shared Auth Utility

Endpoint authentication is consolidated into a single `requireAuth()`{lang="ts"} utility, replacing duplicated auth logic across 6 route handlers.

## ⚠️ Breaking Changes

### Dependency Version Bumps

The following internal dependencies have new minimum versions. Check their release notes for changes that affect your configuration.

- **nuxt-site-config** v4: [breaking changes](https://github.com/harlan-zw/nuxt-site-config/releases/tag/v4.0.0)
- **@nuxtjs/robots** v6: [breaking changes](https://github.com/nuxt-modules/robots/releases/tag/v6.0.0)
- **@nuxtjs/sitemap** v8: [breaking changes](https://github.com/nuxt-modules/sitemap/releases/tag/v8.0.0)

### mdream Options Shape

`mdreamOptions` changed from `HTMLToMarkdownOptions & { preset?: 'minimal' }` to the new `MdreamOptions` type from mdream v1. The `preset` key no longer exists.

```diff
aiReady: {
-  mdreamOptions: { preset: 'minimal' },
+  mdreamOptions: { minimal: true },
 }
```

### Config Rename

`cacheMaxAgeSeconds` is now `llmsTxtCacheSeconds` to clarify it only controls the llms.txt cache, not markdown route caching.

```diff
aiReady: {
-  cacheMaxAgeSeconds: 600,
+  llmsTxtCacheSeconds: 600,
 }
```

### Type Rename

`BulkDocument` is now `PageDocument`.

```diff
-import type { BulkDocument } from 'nuxt-ai-ready'
+import type { PageDocument } from 'nuxt-ai-ready'
```

### Hook Rename

The Nitro runtime hook `ai-ready:markdown` is now `ai-ready:page:markdown`, matching the build-time hook name.

```diff
-nitroApp.hooks.hook('ai-ready:markdown', (ctx) => {
+nitroApp.hooks.hook('ai-ready:page:markdown', (ctx) => {
   ctx.markdown += '\n\nCustom footer'
 })
```

### Headings Type Unified

`PageEntry.headings` and `PageIndexedContext.headings` changed from `string` (JSON) to `Array<Record<string, string>>`{lang="html"} (already parsed). Remove any `JSON.parse()`{lang="ts"} calls on `.headings`.

```diff
const page = await queryPages(event, { route: '/about' })
-const headings = JSON.parse(page.headings)
+const headings = page.headings // already parsed
```

### Endpoint Auth: Header Instead of Query String

Protected `/__ai-ready/*` endpoints now require an `Authorization: Bearer <token>`{lang="html"} header instead of `?secret=<token>`{lang="html"} in the query string. This prevents secrets from leaking into server logs and referrer headers.

```diff
-fetch('/__ai-ready/poll?secret=TOKEN', { method: 'POST' })
+fetch('/__ai-ready/poll', {
+  method: 'POST',
+  headers: { Authorization: 'Bearer TOKEN' },
+})
```

```diff
-curl -X POST "https://site.com/__ai-ready/poll?secret=TOKEN"
+curl -H "Authorization: Bearer TOKEN" -X POST "https://site.com/__ai-ready/poll"
```

Update CI scripts, external cron jobs, or monitoring tools that call protected endpoints. Prune dry runs did not require authentication.

## 🛟 Migration Assistance

v1 includes a backward compatibility layer to ease migration. The following deprecated patterns still work but emit warnings:

- **`cacheMaxAgeSeconds`** in `nuxt.config.ts` is auto-mapped to `llmsTxtCacheSeconds` with a build warning
- **`mdreamOptions.preset`** triggers a build warning explaining the new shape
- **`?secret=<token>`{lang="html"} query auth** still works on protected `/__ai-ready/*` endpoints but logs a deprecation warning per request

The v1 release planned to remove these shims in v2. This is a historical migration note, not a statement of current shim support.
Use the renamed configuration and Bearer header in new code.

## 🐛 Bug Fixes

- Cron lock race condition fixed with atomic `INSERT ... ON CONFLICT DO UPDATE ... WHERE` instead of check-then-set ([`854551f`](https://github.com/harlan-zw/nuxt-ai-ready/commit/854551f))
- Unsafe `JSON.parse` calls replaced with `safeJsonParse()`{lang="ts"} across query layer ([`854551f`](https://github.com/harlan-zw/nuxt-ai-ready/commit/854551f))
- Input validation added to `poll`, `prune`, and `indexnow` endpoints (limit, timeout, ttl clamping) ([`854551f`](https://github.com/harlan-zw/nuxt-ai-ready/commit/854551f))
- `console.warn` replaced with `logger.warn` in cron runner ([`854551f`](https://github.com/harlan-zw/nuxt-ai-ready/commit/854551f))
- Markdown cache now varies by `Accept` headers ([`f513c08`](https://github.com/harlan-zw/nuxt-ai-ready/commit/f513c08))

## Agent Migration Prompt

Copy this prompt into your AI coding agent (Claude Code, Cursor, Copilot, etc.) to prepare the v1 migration:

```text
I'm upgrading nuxt-ai-ready to v1. Apply these breaking changes to my codebase:

1. mdream options: `mdreamOptions` in nuxt.config.ts changed shape. Replace `{ preset: 'minimal' }` with `{ minimal: true }`. The type changed from `HTMLToMarkdownOptions` to `MdreamOptions`.

2. Config rename: `cacheMaxAgeSeconds` is now `llmsTxtCacheSeconds` in nuxt.config.ts under the `aiReady` key.

3. Type rename: `BulkDocument` is now `PageDocument`. Update all imports from 'nuxt-ai-ready'.

4. Hook rename: The Nitro runtime hook `ai-ready:markdown` is now `ai-ready:page:markdown`. Update all hooks.hook() and hooks.callHook() calls.

5. Headings type change: `PageEntry.headings` and `PageIndexedContext.headings` changed from `string` (JSON) to `Array<Record<string, string>>` (parsed). Remove any JSON.parse() calls on .headings since it's now already parsed.

6. Auth mechanism change: Protected `/__ai-ready/*` endpoints now use `Authorization: Bearer <token>` header instead of `?secret=<token>` query parameter. Update any fetch calls, curl commands, CI scripts, or external cron jobs that hit these endpoints.

Note: v1 includes backward compatibility shims for `cacheMaxAgeSeconds`, `mdreamOptions.preset`, and `?secret=` query auth. These emit deprecation warnings. The v1 release planned their removal in v2; verify support against the target version. After applying changes, verify no deprecation warnings remain in your build output or server logs.

Search my entire codebase for these patterns and apply all necessary changes.
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.