@lupinum/nuxt-email 1.0.0-beta.3 → 1.0.0-beta.5

package/dist/agent/pages/docs/components/tailwind.md

@@ -0,0 +1,41 @@
+---
+title: "Tailwind"
+description: "ETailwind compiles Tailwind v4 utilities into email-safe inline styles and head rules during server rendering."
+url: "https://nuxt-email.lupinum.com/docs/components/tailwind"
+route: "/docs/components/tailwind"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Tailwind
+
+> ETailwind compiles Tailwind v4 utilities into email-safe inline styles and head rules during server rendering.
+
+## ETailwind
+
+`ETailwind` is the server-only Tailwind v4 boundary. It compiles utilities used by its subtree during rendering. Wrap the whole document so a `<head>` is available inside the boundary.
+
+| Prop | Type | Default | Required |
+| --- | --- | --- | --- |
+| `config` | Tailwind config except `content` | — | No |
+| `theme` | `string` | — | No |
+| `utility` | `string` | — | No |
+
+Utility classes on descendants become inline styles when possible. Rules that cannot be inlined move to a `<style>` in `<head>`. Rendering fails if such a rule has no head inside the boundary. Nested `ETailwind` boundaries also fail.
+
+The [Tailwind guide](/raw/docs/guides/tailwind.md) owns precedence, tokens, nesting, nested components, dark and responsive behavior, animation, limits, and compatibility evidence.
+
+```vue
+<ETailwind>
+  <EHtml lang="en">
+    <EHead />
+    <EBody class="bg-gray-100">
+      <EContainer class="p-4">
+        <EText class="text-red-500">Styled with Tailwind</EText>
+      </EContainer>
+    </EBody>
+  </EHtml>
+</ETailwind>
+```

package/dist/agent/pages/docs/components.md

@@ -0,0 +1,56 @@
+---
+title: "Overview"
+description: "The built-in E-prefixed components, optional ECodeBlock, and their shared safety rules."
+url: "https://nuxt-email.lupinum.com/docs/components"
+route: "/docs/components"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Overview
+
+> The built-in E-prefixed components, optional ECodeBlock, and their shared safety rules.
+
+Nuxt Email provides **eighteen built-in** E-prefixed components. They are auto-imported into email templates — you never import them. Configuring `codeBlock` adds `ECodeBlock`. All composition uses ordinary Vue slots, and all attributes use Vue and HTML names rather than React prop aliases.
+
+## The components
+
+<cards cols="2">
+<card title="Structure" description="EHtml, EHead, EBody, EPreview, EFont" icon="lucide:layout-template" to="/docs/components/structure" />
+
+<card title="Layout" description="EContainer, ESection, ERow, EColumn" icon="lucide:columns-3" to="/docs/components/layout" />
+
+<card title="Content" description="EText, EHeading, ELink, EImg, EHr, EButton" icon="lucide:type" to="/docs/components/content" />
+
+<card title="Code" description="ECodeInline and optional ECodeBlock" icon="lucide:code" to="/docs/components/code" />
+
+<card title="Markdown" description="EMarkdown" icon="lucide:file-text" to="/docs/components/markdown" />
+
+<card title="Tailwind" description="ETailwind" icon="lucide:paintbrush" to="/docs/components/tailwind" />
+</cards>
+
+| Component | Reference |
+| --- | --- |
+| `EHtml`, `EHead`, `EBody`, `EPreview`, `EFont` | [Structure](/raw/docs/components/structure.md#ehtml), [EHead](/raw/docs/components/structure.md#ehead), [EBody](/raw/docs/components/structure.md#ebody), [EPreview](/raw/docs/components/structure.md#epreview), [EFont](/raw/docs/components/structure.md#efont) |
+| `EContainer`, `ESection`, `ERow`, `EColumn` | [EContainer](/raw/docs/components/layout.md#econtainer), [ESection](/raw/docs/components/layout.md#esection), [ERow](/raw/docs/components/layout.md#erow), [EColumn](/raw/docs/components/layout.md#ecolumn) |
+| `EText`, `EHeading`, `ELink`, `EImg`, `EHr`, `EButton` | [EText](/raw/docs/components/content.md#etext), [EHeading](/raw/docs/components/content.md#eheading), [ELink](/raw/docs/components/content.md#elink), [EImg](/raw/docs/components/content.md#eimg), [EHr](/raw/docs/components/content.md#ehr), [EButton](/raw/docs/components/content.md#ebutton) |
+| `ECodeInline`, `ECodeBlock` | [ECodeInline](/raw/docs/components/code.md#ecodeinline), [ECodeBlock](/raw/docs/components/code.md#ecodeblock) |
+| `EMarkdown` | [EMarkdown](/raw/docs/components/markdown.md#emarkdown) |
+| `ETailwind` | [ETailwind](/raw/docs/components/tailwind.md#etailwind) |
+
+## Rules every component shares
+
+- **Native attributes and `class` are forwarded** unless a component fixes an email-safety invariant (documented per component).
+- **`style` accepts the normal Vue object, string, or array forms.** Object keys may be camelCase or kebab-case.
+- **Vue interpolation and attribute serialization escape text by default.**
+- **No raw HTML, no scripts.** Every component rejects `innerHTML`, `textContent`, and any attribute name beginning with `on` (case-insensitively). There is no raw-HTML primitive, and event handlers have no place in rendered email.
+- **Required strings must be non-empty at runtime** — for example `href` and `src`.
+- **No React shorthand props.** React Email conveniences such as `mx` are not supported; use ordinary CSS in `style`.
+
+## A note on security
+
+Nuxt Email renders trusted application templates. Supply untrusted values through normal escaped Vue bindings. It is **not** an HTML sanitizer.
+
+General `href` and `src` values are escaped, but their URL schemes are not validated. Validate application-controlled URLs before rendering. `EMarkdown` is stricter: it rejects raw HTML and unsafe URL schemes. See the renderer's [security boundary](/raw/docs/reference/render-email.md#security-boundary).

package/dist/agent/pages/docs/getting-started/choose-a-tool.md

@@ -0,0 +1,38 @@
+---
+title: "Choose the right tool"
+description: "Compare Nuxt Email with the closest Vue, Nuxt, standalone, and React email workflows."
+url: "https://nuxt-email.lupinum.com/docs/getting-started/choose-a-tool"
+route: "/docs/getting-started/choose-a-tool"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Choose the right tool
+
+> Compare Nuxt Email with the closest Vue, Nuxt, standalone, and React email workflows.
+
+Email tools often share components, Tailwind support, and a preview. The important difference is where templates run and who owns the surrounding workflow.
+
+## Product boundaries
+
+| Tool | Use it when |
+| --- | --- |
+| **Nuxt Email** | One Nuxt application owns request-time transactional rendering. Template names and Vue props become one typed Nitro API. Preview, tests, and production use the same renderer; delivery stays in the application. |
+| **[Nuxt Email Renderer](https://nuxt.com/modules/nuxt-email-renderer) / [Vue Email](https://vuemail.net/getting-started)** | You want a broader Vue component and utility model. Nuxt Email Renderer adds a Nuxt-focused live preview and documented internationalization support. Vue Email also documents provider integrations and Nuxt support. Compare their current configuration and delivery model with your application needs. |
+| **[Maizzle](https://maizzle.com/docs/introduction)** | You need a standalone or Vite-based email project, static builds, marketing workflows, or a configurable transformation pipeline. Maizzle 6 uses Vue single-file components and Tailwind CSS 4, and it also has an official [Nuxt integration](https://maizzle.com/docs/installation/frameworks/nuxt). |
+| **[React Email](https://react.email/docs/introduction)** | Your application uses React, or your team wants React Email's component ecosystem and direct [provider integration guides](https://react.email/docs/integrations/overview). Its render utility produces HTML and plain text at send time. |
+
+Claims on this page were checked against the linked primary documentation on 2026-08-22. Product boundaries can change, so check those sources before a migration.
+
+## Choose Nuxt Email when
+
+- Email templates belong to one Nuxt application.
+- You want template names and props checked at the Nitro call site.
+- You want email-safe Tailwind v4 without loading the application's browser CSS.
+- You want rendering only. Your application will keep recipients, credentials, attachments, and delivery policy.
+
+Choose another tool when its boundary matches the job more closely. Nuxt Email does not provide a campaign system, a provider abstraction, a general registry protocol, or a client-side renderer.
+
+Next, [install the published beta](/raw/docs/getting-started/installation.md).

package/dist/agent/pages/docs/getting-started/first-email.md

@@ -0,0 +1,99 @@
+---
+title: "Your first email"
+description: "Write a Vue email template under app/emails/, add a typed preview fixture, and understand template naming."
+url: "https://nuxt-email.lupinum.com/docs/getting-started/first-email"
+route: "/docs/getting-started/first-email"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Your first email
+
+> Write a Vue email template under app/emails/, add a typed preview fixture, and understand template naming.
+
+Every `.vue` file under `app/emails/` is an email template. Nested paths become slash-separated names; `app/emails/account/reset-password.vue` is named `account/reset-password`. The `app/emails/components/` folder is reserved for your own supporting components and is not discovered as a template.
+
+## Write the template
+
+<card title="Complete-document requirement" icon="lucide:alert-triangle">
+A template must render exactly one `<html>` root containing exactly one `<body>`. `EHtml` and `EBody` are the supported wrappers. Fragments, text-only roots, and multiple roots fail with `EmailRenderError`. The renderer does not repair or wrap an incomplete document.
+</card>
+
+```vue [app/emails/welcome.vue]
+<script setup lang="ts">
+import { defineEmail } from '@lupinum/nuxt-email/define-email'
+
+const props = defineProps<{
+  firstName: string
+  activationUrl: string
+}>()
+
+defineEmail({
+  subject: () => `Welcome aboard, ${props.firstName}`,
+})
+</script>
+
+<template>
+  <ETailwind>
+    <EHtml lang="en">
+      <EHead>
+        <title>Activate your account</title>
+      </EHead>
+      <EBody class="m-0 bg-slate-100 p-6">
+        <EPreview>Your account is ready.</EPreview>
+        <EContainer class="rounded-lg bg-white p-6">
+          <EHeading class="m-0 text-2xl text-slate-900">Welcome, {{ firstName }}</EHeading>
+          <EText class="text-slate-600">Finish setting up your account.</EText>
+          <EButton class="rounded-md bg-blue-600 px-5 py-3 text-white" :href="activationUrl">
+            Activate account
+          </EButton>
+        </EContainer>
+      </EBody>
+    </EHtml>
+  </ETailwind>
+</template>
+```
+
+You do not import the `E*` components — the module auto-imports eighteen built-ins and adds `ECodeBlock` when configured. Use normal `defineProps()`, slots, `v-if`, `v-for`, Tailwind v4 classes, HTML attributes, and Vue style bindings. `defineEmail` is an explicit server-only import; its closure captures the template's actual props.
+
+## Standalone renderer boundary
+
+Email templates are `.vue` files compiled in a dedicated Nitro Rollup graph. Each render uses a fresh Vue server-side rendering (SSR) application. Vue compiler macros such as `defineProps`, `defineOptions`, and `defineSlots` remain available without imports. Import other Vue APIs explicitly:
+
+```vue
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = defineProps<{ firstName: string }>()
+const greeting = computed(() => `Welcome, ${props.firstName}`)
+</script>
+```
+
+Nuxt app auto-imports and host application context are not part of the email-rendering contract. Do not rely on these features inside a template:
+
+- bare APIs such as `ref`;
+- `useNuxtApp` or context-dependent composables;
+- application plugins; or
+- app-level provides.
+
+Pass application data through typed props. Import standalone utilities explicitly. This boundary keeps output deterministic and lets the package testing helper use the same component.
+
+## Add a preview fixture
+
+To see the template in the [development preview](/raw/docs/guides/preview-workflow.md), add one exact sibling `.fixtures.ts` file with deterministic sample props:
+
+```ts [app/emails/welcome.fixtures.ts]
+import type { EmailComponentProps } from '@lupinum/nuxt-email'
+import type WelcomeEmail from './welcome.vue'
+
+export default {
+  firstName: 'Ada',
+  activationUrl: 'https://example.com/activate',
+} satisfies EmailComponentProps<typeof WelcomeEmail>
+```
+
+The file must default-export one object, and only the exact `.fixtures.ts` suffix is recognized. The `satisfies` expression makes fixture values obey the same prop type used by the generated render API. Fixtures are excluded from production builds — never import them into production code.
+
+Next, [open the development preview](/raw/docs/guides/preview-workflow.md) and inspect the fixture.

package/dist/agent/pages/docs/getting-started/installation.md

@@ -0,0 +1,85 @@
+---
+title: "Installation"
+description: "Add @lupinum/nuxt-email to a supported Nuxt application and optionally configure syntax highlighting."
+url: "https://nuxt-email.lupinum.com/docs/getting-started/installation"
+route: "/docs/getting-started/installation"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Installation
+
+> Add @lupinum/nuxt-email to a supported Nuxt application and optionally configure syntax highlighting.
+
+Nuxt Email installs into an existing, supported Nuxt 4 application. Its email discovery and rendering conventions require no configuration.
+
+## 1. Add the Nuxt module
+
+```bash
+pnpm add @lupinum/nuxt-email@next
+```
+
+<card title="Use the scoped name" icon="lucide:info">
+The unscoped `nuxt-email` package on npm is unrelated to this project. Always install and import `@lupinum/nuxt-email`.
+</card>
+
+Register the unversioned package name in Nuxt configuration:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-email'],
+})
+```
+
+### Set up a coding agent
+
+The package ships its documentation for coding agents such as Claude Code,
+Codex and Cursor, so they read pages that match the installed version. Give
+your coding agent this task:
+
+```text
+Set up @lupinum/nuxt-email for coding agents as described under "Agent setup" in its README.
+```
+
+The steps are in the [README's Agent setup section](https://github.com/lupinum-dev/nuxt-email#agent-setup).
+
+## 2. Confirm the TypeScript entry point
+
+If your app does not already have one, add the ordinary Nuxt `tsconfig.json`:
+
+```json [tsconfig.json]
+{
+  "extends": "./.nuxt/tsconfig.json"
+}
+```
+
+## Optional code blocks
+
+Syntax highlighting is opt-in. Nuxt Email uses the Shiki syntax highlighter. Configure exactly the languages your templates use and one theme:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@lupinum/nuxt-email'],
+  nuxtEmail: {
+    codeBlock: {
+      languages: ['typescript'],
+      theme: 'github-dark',
+    },
+  },
+})
+```
+
+Without `codeBlock`, `ECodeBlock` is not registered. Shiki is not loaded during module setup or included in the production server bundle.
+
+Shiki remains an installation-time dependency of `@lupinum/nuxt-email`. The option controls build and runtime cost, not package download cost. Discovery directories, the preview route, and the render API remain fixed. See the [module behavior reference](/raw/docs/reference/module.md) for the full contract.
+
+## What the module registers
+
+- Server-only auto-imports for eighteen built-in `E*` components, plus `ECodeBlock` when configured.
+- A Nitro-only `renderEmail(name, props)` auto-import, typed from `app/emails/`.
+- The explicit `@lupinum/nuxt-email/define-email` entry point for declaring a subject inside a template.
+- A development-only preview application at `/__email` (never present in production output).
+
+Next, [author your first email](/raw/docs/getting-started/first-email.md).

package/dist/agent/pages/docs/getting-started/render-from-nitro.md

@@ -0,0 +1,59 @@
+---
+title: "Render from Nitro"
+description: "Call the typed, server-only renderEmail auto-import and pass its html and text to your provider SDK."
+url: "https://nuxt-email.lupinum.com/docs/getting-started/render-from-nitro"
+route: "/docs/getting-started/render-from-nitro"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Render from Nitro
+
+> Call the typed, server-only renderEmail auto-import and pass its html and text to your provider SDK.
+
+`renderEmail(name, props)` is the one public application rendering path. It is a **Nitro-only auto-import** generated from `app/emails/` — available in server handlers and other Nitro server code, never in Vue components, client plugins, or client bundles.
+
+## Call it from a handler
+
+```ts [server/api/welcome.get.ts]
+export default defineEventHandler(async () => {
+  const { html, text, subject } = await renderEmail('welcome', {
+    firstName: 'Ada',
+    activationUrl: 'https://example.com/activate',
+  })
+
+  // Hand these values to your provider SDK. Nuxt Email does not send mail.
+  return { html, text, subject }
+})
+```
+
+Do not import `renderEmail` from `@lupinum/nuxt-email` or `#imports`; it is injected as a server auto-import. TypeScript checks the template name `'welcome'` and its exact props.
+
+## The result shape
+
+The promise resolves to `RenderedEmail`, which is available as a type-only root import when you need to annotate application code:
+
+```ts
+import type { RenderedEmail } from '@lupinum/nuxt-email'
+```
+
+- `html` begins with the XHTML 1.0 Transitional doctype and is deterministic.
+- `text` is authored metadata when `defineEmail` declares `text`. Otherwise, it is derived from the final HTML.
+- `subject` is present only when the template declares one via [`defineEmail`](/raw/docs/guides/subject-lines.md).
+
+Nuxt Email owns the body content. Recipients, sender identity, credentials, attachments, and delivery stay in your provider SDK. See the [renderEmail reference](/raw/docs/reference/render-email.md) for the full contract.
+
+## Generate and verify types
+
+The generated server declarations change when templates are added, renamed, or deleted:
+
+```bash
+pnpm exec nuxt prepare
+pnpm exec vue-tsc --noEmit -p .nuxt/tsconfig.server.json
+```
+
+If an editor was open before `nuxt prepare`, restart its TypeScript service once so it reloads the generated server config.
+
+Next, [hand the rendered result to your provider](/raw/docs/guides/sending-email.md).

package/dist/agent/pages/docs/getting-started.md

@@ -0,0 +1,64 @@
+---
+title: "Introduction"
+description: "What Nuxt Email is, why its output is trustworthy, and how it is compared with a fixed React Email version."
+url: "https://nuxt-email.lupinum.com/docs/getting-started"
+route: "/docs/getting-started"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Introduction
+
+> What Nuxt Email is, why its output is trustworthy, and how it is compared with a fixed React Email version.
+
+Nuxt Email is typed transactional email for Nuxt, with email-safe Tailwind v4. You write Vue single-file components (`.vue` files) in `app/emails/`. The module discovers them, generates typed Nitro render calls, and compiles Tailwind utilities into email output.
+
+It does one job and stops there. Nuxt Email does not send mail, choose providers, or manage recipients. You hand the rendered `html`, `text`, and optional computed `subject` to your provider SDK.
+
+## Where it fits
+
+Choose Nuxt Email when transactional messages belong to a Nuxt application and should share its Vue authoring model, TypeScript contracts, and Nitro deployment. The generated `renderEmail('welcome', props)` call is the product: no sidecar renderer, separate registry, or module configuration.
+
+Nuxt Email is one focused option among Vue, Nuxt, standalone, and React email tools. [Compare the product boundaries](/raw/docs/getting-started/choose-a-tool.md) before installing it.
+
+## Why the output is trustworthy
+
+Email HTML is unforgiving: clients strip `<style>`, break flexbox, and mangle padding. Nuxt Email combines conservative primitives with reproducible checks while keeping live-client claims separate.
+
+- **Checked against React Email.** Covered behaviors are compared, case by case, with fixed versions of [React Email](https://react.email) (`6.11.0`) and `@react-email/render` (`2.1.0`). The [conformance report](/raw/docs/reference/conformance.md) records the tested scope and intentional differences. It is regression evidence, not a universal inbox-rendering guarantee.
+- **Tailwind v4 for email.** `ETailwind` inlines compatible utilities, preserves author-style precedence, and moves media-query and pseudo-class rules into the head.
+- **Deterministic.** Two renders of the same template and props return byte-identical HTML and a matching plain-text fallback. No IDs, timestamps, hydration payload, or mutable renderer state.
+- **Server-only and typed.** `renderEmail('welcome', props)` is generated from your `app/emails/` folder. Unknown template names, missing props, and wrong types fail at compile time.
+- **Limits are documented.** No global "React Email compatible" claim exists. Differences are recorded per behavior in the [conformance report](/raw/docs/reference/conformance.md) and [migration guide](/raw/docs/reference/migration.md).
+
+<cards cols="2">
+<card title="Choose the right tool" description="Compare the closest workflows by where templates run and who owns delivery." icon="lucide:signpost" to="/docs/getting-started/choose-a-tool" />
+
+<card title="Install the module" description="Add the scoped package to a supported Nuxt app and register it." icon="lucide:download" to="/docs/getting-started/installation" />
+
+<card title="Author your first email" description="Write a Vue .vue file and add a preview fixture." icon="lucide:file-code" to="/docs/getting-started/first-email" />
+
+<card title="Render from Nitro" description="Call renderEmail from a server handler and read the result." icon="lucide:server" to="/docs/getting-started/render-from-nitro" />
+
+<card title="Component reference" description="The built-in E* primitives and optional syntax-highlighted code blocks." icon="lucide:blocks" to="/docs/components" />
+</cards>
+
+## Release status
+
+The 1.0.0 beta is published on npm's [`next` tag](https://www.npmjs.com/package/@lupinum/nuxt-email?activeTab=versions). The [three-client beta smoke test](https://github.com/lupinum-dev/nuxt-email/blob/main/docs/release/client-qa-checklist.md#100-beta1-smoke-test) passed against beta.1. The full eight-client checklist and an external transactional beta still block stable `1.0.0`.
+
+The package identity is `@lupinum/nuxt-email`; the unscoped npm package is unrelated.
+
+## Supported environment
+
+- **Node.js** `^22.18.0 || ^24.11.0 || ^26.0.0` — the supported even-numbered Node 22, 24, and 26 lines.
+- **Nuxt** `>=4.5.1 <5`.
+- **Vue** `^3.5.40`.
+
+Nuxt `4.5.1` and Vue `3.5.40` are the compatibility baseline. Release consumers verify that minimum and the current compatible Nuxt 4 and Vue 3 versions without a dependency shim. CI covers Node 22, 24, and 26. Other Node majors, Nuxt 3, Nuxt 5, edge runtimes, and client-side email rendering are outside the support contract.
+
+The Node range follows the supported even-numbered Node release lines that can run the Nuxt baseline. Keeping that range narrow lets the renderer use the platform Nuxt already requires and avoids compatibility code for old or short-lived Node releases.
+
+Questions? Ask in the [Lupinum OSS Discord](https://discord.lupinum.com).

package/dist/agent/pages/docs/guides/client-compatibility.md

@@ -0,0 +1,65 @@
+---
+title: "Client compatibility and proofs"
+description: "What is automatically proven, and the manual email-client QA checklist that closes the remaining gap."
+url: "https://nuxt-email.lupinum.com/docs/guides/client-compatibility"
+route: "/docs/guides/client-compatibility"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Client compatibility and proofs
+
+> What is automatically proven, and the manual email-client QA checklist that closes the remaining gap.
+
+Nuxt Email separates automated compatibility evidence from manual client results.
+
+## What is automatically proven
+
+The [conformance suite](/raw/docs/reference/conformance.md) compares covered behavior with fixed React Email versions. It checks exact bytes, normalized output, or specific semantics. Presentation tables, Outlook-specific button spacers, preview hiding, font declarations, and Tailwind inlining have regression cases.
+
+This is useful implementation evidence, but it is a comparison to a reference renderer, not proof that every email client will display a message identically.
+
+## Completed beta smoke test
+
+Matthias completed the owner-run `1.0.0-beta.1` smoke test on 2026-08-22. The same `proof-kit` message passed in Gmail web, Apple Mail on macOS, and Outlook classic on Windows in light and dark modes. The [signed QA record](https://github.com/lupinum-dev/nuxt-email/blob/main/docs/release/client-qa-checklist.md#100-beta1-smoke-test) records the tested commit and artifact hashes.
+
+This smoke test is enough for the published beta. It does not complete the full eight-client checklist required for stable `1.0.0`. An external transactional beta also remains pending.
+
+## Run the stable checklist
+
+Automated tests do not open real email clients. Run the stable checklist against the fixed `proof-kit` fixture.
+
+<steps>
+### Render the fixture
+
+Run `pnpm proofs:generate`, then use the committed `proof-kit` template and props. Optionally replace only the logo URL with an HTTPS image you control.
+
+### Send with your own account
+
+Send the exact rendered `html` and `text` to test mailboxes through a provider SDK you choose. Nuxt Email does not send mail.
+
+### Inspect in three clients
+
+Open the same message in **Gmail web**, **Apple Mail** (macOS or iOS), and **Outlook for Windows**.
+
+### Record the result
+
+Note client versions, screenshots, defects, and a final accept/reject decision.
+</steps>
+
+## Required checks
+
+- Inbox preview shows only the intended preview sentence and does not expose filler characters.
+- The remote logo has useful alternative text when images are blocked.
+- Heading, paragraphs, divider, and footer links retain readable spacing.
+- The activation button is clickable, visually centered, and has comparable horizontal and vertical padding **in Outlook**.
+- Two columns stay in one row at desktop email widths and remain readable when the client narrows the message.
+- Link destinations and the `mailto:` link are correct.
+- Plain-text fallback contains the meaningful content and destinations but excludes preview filler and images.
+- No script, hydration payload, framework state, or event-handler attribute is present.
+
+<card title="Beta QA is not stable approval" icon="lucide:shield-alert">
+The three-client smoke test is complete. Stable `1.0.0` still waits for the full eight-client record and external beta evidence.
+</card>

package/dist/agent/pages/docs/guides/plain-text.md

@@ -0,0 +1,42 @@
+---
+title: "Plain text"
+description: "How the plain-text fallback is produced from the rendered HTML, what it excludes, and how to control table output."
+url: "https://nuxt-email.lupinum.com/docs/guides/plain-text"
+route: "/docs/guides/plain-text"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Plain text
+
+> How the plain-text fallback is produced from the rendered HTML, what it excludes, and how to control table output.
+
+Every render returns a `text` string alongside `html`. By default it is a deterministic fallback produced from the **final rendered HTML**. Nuxt Email uses a fixed `html-to-text` version with no line wrapping.
+
+When automatic conversion is not good enough, the template can declare authored text with `defineEmail({ text: '…' })` or a synchronous `text` function. Authored text replaces derivation for that render; it does not create a second template or rendering path.
+
+## What plain text includes and excludes
+
+- **Excluded:** head content, images, `<script>`/`<style>` content, and any element marked `data-skip-in-text="true"`. `EPreview` is therefore absent from the fallback.
+- **Links:** destinations are retained when the visible text differs from the URL. Fragment links and `mailto:` links follow the recorded React Email comparison behavior.
+- **Structure:** nested lists, ordered-list starts, blockquotes, hard breaks, preformatted content, Unicode, and ordinary tables all have exact conformance cases.
+
+## Controlling table output
+
+By default tables render as plain rows. When you specifically need aligned, column-formatted output for a table, add `data-text-format="dataTable"` to that table:
+
+```vue
+<table data-text-format="dataTable">
+  <!-- rows -->
+</table>
+```
+
+## Inspect it every time
+
+Plain text is a real deliverable that some recipients and spam filters read. Inspect it in the [development preview](/raw/docs/guides/preview-workflow.md)'s **Plain text** tab for every transactional template, exactly as you would review the HTML.
+
+<card title="ECodeInline appears once" icon="lucide:info">
+`ECodeInline` keeps two copies in HTML for `Orange.fr` compatibility, but marks the hidden copy to be skipped by plain-text generation. Recipients therefore receive the code once in the text alternative. This is an intentional divergence from React Email.
+</card>

package/dist/agent/pages/docs/guides/preview-workflow.md

@@ -0,0 +1,83 @@
+---
+title: "Preview workflow"
+description: "Use the development-only /__email preview, add fixtures, and monitor exact rendered size without treating it as a client guarantee."
+url: "https://nuxt-email.lupinum.com/docs/guides/preview-workflow"
+route: "/docs/guides/preview-workflow"
+locale: "en"
+section: "Documentation"
+collection: "docs"
+source: "ginko-content"
+---
+
+# Preview workflow
+
+> Use the development-only /__email preview, add fixtures, and monitor exact rendered size without treating it as a client guarantee.
+
+Nuxt Email exposes `/__email` while the development server is running. The path follows the configured Nuxt base URL. Open `/__email` with the default base URL, or `/sub/__email` with `app.baseURL: '/sub/'`.
+
+The preview lists every template under `app/emails/` and marks templates without fixture data. It shows rendered HTML, exact HTML source, or plain text. The visible page polls once per second, so saved template and fixture changes appear without a restart. Polling pauses in a hidden tab.
+
+When Nuxt DevTools is available, its **Nuxt Email** iframe shortcut opens the same baseURL-aware preview. The shortcut adds no second preview application or route.
+
+The preview calls the same server-only registry and `renderEmail()` implementation your handlers use. It is a rendering and debugging tool — not a second rendering path and not an email-client compatibility guarantee.
+
+## Add a fixture
+
+Place one exact sibling file beside a template. Only the `.fixtures.ts` suffix is recognized, and it must default-export one props object:
+
+```ts [app/emails/welcome.fixtures.ts]
+import type { EmailComponentProps } from '@lupinum/nuxt-email'
+import type WelcomeEmail from './welcome.vue'
+
+export default {
+  firstName: 'Ada',
+  activationUrl: 'https://example.com/activate',
+} satisfies EmailComponentProps<typeof WelcomeEmail>
+```
+
+The preview intentionally supports **one fixed scenario per template** and does not accept request-provided props or generate editing forms.
+
+## Inspect output
+
+<steps>
+### Preview
+
+Loads the raw rendered HTML in a sandboxed iframe (no script permission).
+
+### HTML
+
+Displays the exact `html` returned by `renderEmail()`.
+
+### Plain text
+
+Displays the exact `text` returned by `renderEmail()`.
+
+### Copy / Open
+
+**Copy** copies the active representation; **Open** opens the raw development render in a separate tab.
+</steps>
+
+Render failures show the template name, the `EmailRenderError` stack, and its original cause. Use the [error reference](/raw/docs/reference/errors.md) to find the recovery step by symptom.
+
+A template without a fixture remains in the list. Add its sibling fixture before trying to render it.
+
+## Mind the approximate Gmail clipping budget
+
+Gmail is commonly observed clipping messages around **102 KB**, but behavior can vary with the account, message, and delivery path. Nuxt Email reports the rendered HTML's exact UTF-8 byte count; the Gmail-specific interpretation is an approximate authoring warning, not a guarantee:
+
+```ts
+const { html } = await renderEmail('welcome', props)
+console.log('bytes:', Buffer.byteLength(html, 'utf8'))
+```
+
+Keep the rendered HTML comfortably below the warning area and test the delivered message in your target Gmail accounts. Inlined Tailwind utilities and repeated markup add up quickly, so measure your largest, most dynamic template.
+
+The preview has no dark-mode simulation. Email clients transform dark-mode content differently, so test dark rendering in the real clients you support.
+
+## Production boundary
+
+The preview page, endpoints, and fixture imports exist **only in development**. Production builds contain none of their routes or fixture data. The raw render endpoint uses a restrictive content security policy. Its iframe has no script permission.
+
+The development endpoints cannot become production render or send APIs. Use the typed server-only [`renderEmail`](/raw/docs/reference/render-email.md) in your handlers.
+
+Next, [render the template from Nitro](/raw/docs/getting-started/render-from-nitro.md).