---
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-05-06T21:36:23.059Z"
---

## Introduction

Nuxt AI Ready v1 focuses on **API consistency**, **security**, and **reliability**.

The headline change is the migration to [mdream v1](https://github.com/harlan-zw/mdream), a rewrite of the HTML to markdown engine with a cleaner API and better output. Alongside this, v1 tightens endpoint security, unifies type inconsistencies, and fixes race conditions in the cron system.

Most breaking changes have a **backward compatibility layer** that emits deprecation warnings, so upgrading won't immediately break your app. 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 upgrade automatically.

## 🧠 Mdream v1

The HTML to Markdown engine has been rewritten. mdream v1 ships a native Rust engine (up to 8x faster), [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()` utility, replacing duplicated auth logic across 6 route handlers.

## ⚠️ Breaking Changes

### Dependency Version Bumps

The following internal dependencies have new minimum versions. These shouldn't have any direct effect on your site, however, you may want to double check their release notes.

- **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>>` (already parsed). Remove any `JSON.parse()` 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

All `/__ai-ready/*` endpoints now require an `Authorization: Bearer <token>` header instead of `?secret=<token>` 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 any CI scripts, external cron jobs, or monitoring tools that call these endpoints.

## 🛟 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> query auth** still works on all `/__ai-ready/*` endpoints but logs a deprecation warning per request

These compatibility shims will be removed in v2. Update your config and endpoints at your earliest convenience.

## 🐛 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()` 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 migrate automatically:

```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: All `/__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 and will be removed in v2. 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.
```