@autono/open-pages 0.8.0 → 0.9.0

package/dist/{config-p-TWNXbv.d.ts → config-IkwICvOe.d.ts}

@@ -1,4 +1,4 @@
-import { t as Locale } from "./types-DDdUFUIS.js";
+import { t as Locale } from "./types-B-9WXL93.js";
 //#region src/config.d.ts
 type OpenPagesBuildConfig = {
   showPageBrowser?: boolean;
@@ -7,6 +7,7 @@ type OpenPagesBuildConfig = {
 type OpenPagesConfig = {
   base?: string;
   pagesDir?: string;
+  emailsDir?: string;
   themesDir?: string;
   assetsDir?: string;
   port?: number;

package/dist/{dev-CTrB263u.js → dev-B7x-G-wk.js}

@@ -1,5 +1,5 @@
+import { s as DEV_SUPERVISED_ENV, t as createViteConfig } from "./config-CYLBzMMb.js";
 import { a as printUrls, i as printShortcutsHint, n as formatError, o as shortcutsEnabled, r as printHeader, s as startupDuration, t as createCliLogger } from "./cli/bin.js";
-import { n as DEV_SUPERVISED_ENV, t as createViteConfig } from "./config-D_U_aCQz.js";
 import path from "node:path";
 import { existsSync } from "node:fs";
 import { fork } from "node:child_process";

package/dist/{export-enKL9R7x.js → export-BxMksWEc.js}

@@ -1,11 +1,11 @@
-import { a as openPagesPlugin, i as loadUserConfig, n as findPages, t as extractMeta } from "./open-pages-plugin-C8cFhMB9.js";
+import { a as renderEmail, c as extractMeta, d as openPagesPlugin, i as findEmails, l as findPages, o as stripLocTags, t as createViteConfig, u as loadUserConfig } from "./config-CYLBzMMb.js";
 import path from "node:path";
 import chalk from "chalk";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
 import tailwindcss from "@tailwindcss/vite";
 import react from "@vitejs/plugin-react";
-import { build } from "vite";
+import { build, createServer } from "vite";
 //#region src/cli/export.ts
 function escapeHtml(s) {
 	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
@@ -99,21 +99,72 @@ function extractDescription(src) {
 	const end = src.indexOf("};", metaStart);
 	return src.slice(metaStart, end === -1 ? void 0 : end).match(META_DESCRIPTION_RE)?.[1] ?? null;
 }
+/**
+* Render emails without a browser: a middleware-mode dev server loads each
+* entry through Vite SSR, and `react-email` from the workspace renders it.
+* Each email lands as `<outDir>/<id>/index.html` plus `index.txt`.
+*/
+async function exportEmails(opts) {
+	const { userCwd, config, entries, outDir } = opts;
+	if (entries.length === 0) return;
+	const base = await createViteConfig({
+		userCwd,
+		config,
+		mode: "serve"
+	});
+	const server = await createServer({
+		...base,
+		logLevel: "error",
+		appType: "custom",
+		cacheDir: path.join(userCwd, "node_modules", ".open-pages", "email-render"),
+		optimizeDeps: {
+			noDiscovery: true,
+			include: []
+		},
+		server: {
+			...base.server,
+			middlewareMode: true,
+			watch: null,
+			hmr: false
+		}
+	});
+	try {
+		for (const entry of entries) {
+			const started = performance.now();
+			const rendered = await renderEmail(server, userCwd, entry);
+			const target = path.join(outDir, entry.id);
+			await mkdir(target, { recursive: true });
+			await writeFile(path.join(target, "index.html"), stripLocTags(rendered.html), "utf8");
+			await writeFile(path.join(target, "index.txt"), rendered.text, "utf8");
+			opts.onDone?.(entry, target, Math.round(performance.now() - started));
+		}
+	} finally {
+		await server.close();
+	}
+}
 async function exportPages(opts = {}) {
 	const userCwd = process.cwd();
 	const config = await loadUserConfig(userCwd);
 	const pagesDir = config.pagesDir ?? "pages";
+	const emailsDir = config.emailsDir ?? "emails";
 	const outDir = path.resolve(userCwd, opts.outDir ?? "export");
 	const entries = await findPages(userCwd, pagesDir);
-	const idsOnDisk = entries.map((e) => e.id);
-	if (idsOnDisk.length === 0) throw new Error(`No pages found under ${pagesDir}/`);
-	const requested = opts.pages && opts.pages.length > 0 ? opts.pages : idsOnDisk;
-	const unknown = requested.filter((id) => !idsOnDisk.includes(id));
-	if (unknown.length > 0) throw new Error(`Page not found: ${unknown.join(", ")} (available: ${idsOnDisk.join(", ")})`);
-	const { readCoreVersion } = await import("./version-DZrXLoAD.js").then((n) => n.i);
+	const emailEntries = await findEmails(userCwd, emailsDir);
+	const pageIds = entries.map((e) => e.id);
+	const emailIds = emailEntries.map((e) => e.id);
+	if (pageIds.length === 0 && emailIds.length === 0) throw new Error(`No pages found under ${pagesDir}/ and no emails under ${emailsDir}/`);
+	const explicit = opts.pages && opts.pages.length > 0 ? opts.pages : null;
+	const unknown = (explicit ?? []).filter((id) => !pageIds.includes(id) && !emailIds.includes(id));
+	if (unknown.length > 0) {
+		const available = [...pageIds, ...emailIds.map((id) => `${id} (email)`)].join(", ");
+		throw new Error(`Page not found: ${unknown.join(", ")} (available: ${available})`);
+	}
+	const requestedPages = explicit ? pageIds.filter((id) => explicit.includes(id)) : pageIds;
+	const requestedEmails = explicit ? emailIds.filter((id) => explicit.includes(id)) : emailIds;
+	const { readCoreVersion } = await import("./config-CYLBzMMb.js").then((n) => n.r);
 	const coreVersion = readCoreVersion();
 	await mkdir(outDir, { recursive: true });
-	for (const id of requested) {
+	for (const id of requestedPages) {
 		const entry = entries.find((e) => e.id === id);
 		if (!entry) continue;
 		const started = performance.now();
@@ -128,8 +179,19 @@ async function exportPages(opts = {}) {
 		const ms = Math.round(performance.now() - started);
 		process.stdout.write(`${chalk.green("ok")}  ${path.relative(userCwd, target)}/  ${chalk.dim(`${entry.kind} · ${ms}ms`)}\n`);
 	}
-	const n = requested.length;
-	process.stdout.write(chalk.dim(`${n} ${n === 1 ? "page" : "pages"} → ${path.relative(userCwd, outDir)}/\n`));
+	await exportEmails({
+		userCwd,
+		config,
+		entries: emailEntries.filter((e) => requestedEmails.includes(e.id)),
+		outDir: path.join(outDir, "emails"),
+		onDone: (_entry, target, ms) => {
+			process.stdout.write(`${chalk.green("ok")}  ${path.relative(userCwd, target)}/  ${chalk.dim(`email · ${ms}ms`)}\n`);
+		}
+	});
+	const parts = [];
+	if (requestedPages.length > 0) parts.push(`${requestedPages.length} ${requestedPages.length === 1 ? "page" : "pages"}`);
+	if (requestedEmails.length > 0) parts.push(`${requestedEmails.length} ${requestedEmails.length === 1 ? "email" : "emails"}`);
+	process.stdout.write(chalk.dim(`${parts.join(", ")} → ${path.relative(userCwd, outDir)}/\n`));
 }
 //#endregion
-export { buildPage, exportPages };
+export { buildPage, exportEmails, exportPages };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { n as Plural, t as Locale } from "./types-DDdUFUIS.js";
-import { t as OpenPagesConfig } from "./config-p-TWNXbv.js";
+import { n as Plural, t as Locale } from "./types-B-9WXL93.js";
+import { t as OpenPagesConfig } from "./config-IkwICvOe.js";
 import { ComponentType } from "react";
 //#region src/app/lib/design.d.ts
 type DesignPalette = {
@@ -50,5 +50,25 @@ type PageModule = {
   meta?: PageMeta;
   design?: DesignSystem;
 };
+type EmailMeta = {
+  /** Display name in the workspace. Default: the folder name. */
+  title?: string;
+  /** Subject line the email is meant to be sent with. */
+  subject?: string;
+  /** What the email is for; shown on the workspace card. */
+  description?: string;
+  /** ISO 8601 timestamp. Set once at scaffold time; used to sort the email list. */
+  createdAt?: string;
+};
+/**
+ * An email is one react-email component rendered on the server to a single
+ * HTML document with inlined styles, plus a plain-text alternative derived
+ * from it. It never runs in a browser: no hooks with effects, no state, no
+ * browser APIs.
+ */
+type EmailModule = {
+  default: ComponentType;
+  meta?: EmailMeta;
+};
 //#endregion
-export type { DesignFonts, DesignPalette, DesignSystem, DesignTypeScale, Locale, OpenPagesConfig, PageComponent, PageKind, PageMeta, PageModule, Plural };
+export type { DesignFonts, DesignPalette, DesignSystem, DesignTypeScale, EmailMeta, EmailModule, Locale, OpenPagesConfig, PageComponent, PageKind, PageMeta, PageModule, Plural };

package/dist/locale/index.d.ts

@@ -1,4 +1,4 @@
-import { n as Plural, t as Locale } from "../types-DDdUFUIS.js";
+import { n as Plural, t as Locale } from "../types-B-9WXL93.js";
 //#region src/locale/en.d.ts
 export declare const en: Locale;
 //#endregion

package/dist/locale/index.js

@@ -22,6 +22,7 @@ const en = {
 		duplicate: "Duplicate",
 		themes: "Themes",
 		assets: "Assets",
+		emails: "Emails",
 		folders: "Folders",
 		pages: "Pages",
 		menu: "Menu",
@@ -190,6 +191,7 @@ const en = {
 		placeholder: "Search pages or run a command…",
 		empty: "No results.",
 		groupDocs: "Pages",
+		groupEmails: "Emails",
 		groupFolders: "Folders",
 		groupNavigation: "Go to",
 		groupAppearance: "Appearance",
@@ -207,6 +209,28 @@ const en = {
 		dark: "Dark",
 		system: "System"
 	},
+	emails: {
+		title: "Emails",
+		noEmailsTitle: "No emails yet",
+		noEmailsHintPrefix: "Run ",
+		noEmailsHintSuffix: " in your agent to scaffold one under emails/.",
+		subjectLabel: "Subject",
+		noSubject: "No subject set",
+		openEmailAria: "Open email {name}",
+		backToEmails: "Back to emails",
+		viewHtml: "HTML",
+		viewText: "Text",
+		viewportDesktop: "Desktop",
+		viewportMobile: "Mobile",
+		copyHtml: "Copy HTML",
+		copiedHtml: "HTML copied",
+		copyHtmlFailed: "Could not copy the HTML",
+		reload: "Reload email",
+		openInTab: "Open the rendered email by itself in a new tab",
+		notFound: "Email not found: {id}",
+		unresolvedCount: "{count} classes did not compile",
+		unresolvedTitle: "Tailwind utilities the email compiler could not inline (check components/email/email-theme.ts):"
+	},
 	themes: {
 		title: "Themes",
 		noThemesTitle: "No themes yet",
@@ -259,6 +283,7 @@ const ja = {
 		duplicate: "複製",
 		themes: "テーマ",
 		assets: "アセット",
+		emails: "メール",
 		folders: "フォルダ",
 		pages: "スライド",
 		menu: "メニュー",
@@ -427,6 +452,7 @@ const ja = {
 		placeholder: "スライドを検索、またはコマンドを実行…",
 		empty: "結果がありません。",
 		groupDocs: "スライド",
+		groupEmails: "メール",
 		groupFolders: "フォルダ",
 		groupNavigation: "移動",
 		groupAppearance: "外観",
@@ -444,6 +470,28 @@ const ja = {
 		dark: "ダーク",
 		system: "システム"
 	},
+	emails: {
+		title: "メール",
+		noEmailsTitle: "メールはまだありません",
+		noEmailsHintPrefix: "エージェントで ",
+		noEmailsHintSuffix: " を実行すると emails/ に作成されます。",
+		subjectLabel: "件名",
+		noSubject: "件名が未設定",
+		openEmailAria: "メール {name} を開く",
+		backToEmails: "メール一覧へ戻る",
+		viewHtml: "HTML",
+		viewText: "テキスト",
+		viewportDesktop: "デスクトップ",
+		viewportMobile: "モバイル",
+		copyHtml: "HTML をコピー",
+		copiedHtml: "HTML をコピーしました",
+		copyHtmlFailed: "HTML をコピーできませんでした",
+		reload: "メールを再読み込み",
+		openInTab: "レンダリングされたメールを新しいタブで開く",
+		notFound: "メールが見つかりません: {id}",
+		unresolvedCount: "{count} 個のクラスが変換されませんでした",
+		unresolvedTitle: "メールコンパイラがインライン化できなかった Tailwind ユーティリティ (components/email/email-theme.ts を確認):"
+	},
 	themes: {
 		title: "テーマ",
 		noThemesTitle: "テーマがまだありません",
@@ -485,6 +533,7 @@ const zhCN = {
 		duplicate: "复制",
 		themes: "主题",
 		assets: "素材",
+		emails: "邮件",
 		folders: "頁面夹",
 		pages: "幻灯片",
 		menu: "菜单",
@@ -653,6 +702,7 @@ const zhCN = {
 		placeholder: "搜索幻灯片或执行命令…",
 		empty: "没有匹配的结果。",
 		groupDocs: "幻灯片",
+		groupEmails: "邮件",
 		groupFolders: "頁面夹",
 		groupNavigation: "前往",
 		groupAppearance: "外观",
@@ -670,6 +720,28 @@ const zhCN = {
 		dark: "深色",
 		system: "系统"
 	},
+	emails: {
+		title: "邮件",
+		noEmailsTitle: "还没有邮件",
+		noEmailsHintPrefix: "在你的代理中运行 ",
+		noEmailsHintSuffix: " 即可在 emails/ 下创建一封。",
+		subjectLabel: "主题",
+		noSubject: "未设置主题",
+		openEmailAria: "打开邮件 {name}",
+		backToEmails: "返回邮件列表",
+		viewHtml: "HTML",
+		viewText: "纯文本",
+		viewportDesktop: "桌面",
+		viewportMobile: "移动端",
+		copyHtml: "复制 HTML",
+		copiedHtml: "已复制 HTML",
+		copyHtmlFailed: "无法复制 HTML",
+		reload: "重新加载邮件",
+		openInTab: "在新标签页中单独打开渲染后的邮件",
+		notFound: "找不到邮件: {id}",
+		unresolvedCount: "{count} 个类未能编译",
+		unresolvedTitle: "邮件编译器无法内联的 Tailwind 工具类 (请检查 components/email/email-theme.ts):"
+	},
 	themes: {
 		title: "主题",
 		noThemesTitle: "尚无主题",
@@ -711,6 +783,7 @@ const zhTW = {
 		duplicate: "複製",
 		themes: "主題",
 		assets: "素材",
+		emails: "郵件",
 		folders: "資料夾",
 		pages: "投影片",
 		menu: "選單",
@@ -879,6 +952,7 @@ const zhTW = {
 		placeholder: "搜尋簡報或執行指令…",
 		empty: "沒有符合的結果。",
 		groupDocs: "簡報",
+		groupEmails: "郵件",
 		groupFolders: "資料夾",
 		groupNavigation: "前往",
 		groupAppearance: "外觀",
@@ -896,6 +970,28 @@ const zhTW = {
 		dark: "深色",
 		system: "系統"
 	},
+	emails: {
+		title: "郵件",
+		noEmailsTitle: "還沒有郵件",
+		noEmailsHintPrefix: "在你的代理中執行 ",
+		noEmailsHintSuffix: " 即可在 emails/ 下建立一封。",
+		subjectLabel: "主旨",
+		noSubject: "未設定主旨",
+		openEmailAria: "開啟郵件 {name}",
+		backToEmails: "返回郵件列表",
+		viewHtml: "HTML",
+		viewText: "純文字",
+		viewportDesktop: "桌面",
+		viewportMobile: "行動裝置",
+		copyHtml: "複製 HTML",
+		copiedHtml: "已複製 HTML",
+		copyHtmlFailed: "無法複製 HTML",
+		reload: "重新載入郵件",
+		openInTab: "在新分頁中單獨開啟渲染後的郵件",
+		notFound: "找不到郵件: {id}",
+		unresolvedCount: "{count} 個類別未能編譯",
+		unresolvedTitle: "郵件編譯器無法內聯的 Tailwind 工具類別 (請檢查 components/email/email-theme.ts):"
+	},
 	themes: {
 		title: "主題",
 		noThemesTitle: "尚無主題",

package/dist/{preview-Dmzyd1cf.js → preview-CMv1lGOC.js}

@@ -1,5 +1,5 @@
+import { t as createViteConfig } from "./config-CYLBzMMb.js";
 import { a as printUrls, i as printShortcutsHint, o as shortcutsEnabled, r as printHeader, s as startupDuration, t as createCliLogger } from "./cli/bin.js";
-import { t as createViteConfig } from "./config-D_U_aCQz.js";
 import { mergeConfig, preview as preview$1 } from "vite";
 //#region src/cli/preview.ts
 async function preview(opts = {}) {

package/dist/{types-DDdUFUIS.d.ts → types-B-9WXL93.d.ts}

@@ -26,6 +26,7 @@ type Locale = {
     duplicate: string;
     themes: string;
     assets: string;
+    emails: string;
     folders: string;
     pages: string;
     menu: string;
@@ -195,6 +196,7 @@ type Locale = {
     placeholder: string;
     empty: string;
     groupDocs: string;
+    groupEmails: string;
     groupFolders: string;
     groupNavigation: string;
     groupAppearance: string;
@@ -212,6 +214,28 @@ type Locale = {
     dark: string;
     system: string;
   };
+  emails: {
+    title: string;
+    noEmailsTitle: string;
+    noEmailsHintPrefix: string;
+    noEmailsHintSuffix: string;
+    subjectLabel: string;
+    noSubject: string;
+    openEmailAria: string;
+    backToEmails: string;
+    viewHtml: string;
+    viewText: string;
+    viewportDesktop: string;
+    viewportMobile: string;
+    copyHtml: string;
+    copiedHtml: string;
+    copyHtmlFailed: string;
+    reload: string;
+    openInTab: string;
+    notFound: string;
+    unresolvedCount: string;
+    unresolvedTitle: string;
+  };
   themes: {
     title: string;
     noThemesTitle: string;

package/dist/vite/index.d.ts

@@ -1,4 +1,4 @@
-import { t as OpenPagesConfig } from "../config-p-TWNXbv.js";
+import { t as OpenPagesConfig } from "../config-IkwICvOe.js";
 import { InlineConfig } from "vite";
 //#region src/vite/config.d.ts
 type CreateViteConfigOptions = {

package/dist/vite/index.js

@@ -1,2 +1,2 @@
-import { t as createViteConfig } from "../config-D_U_aCQz.js";
+import { t as createViteConfig } from "../config-CYLBzMMb.js";
 export { createViteConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autono/open-pages",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Runtime and CLI for open-pages — live preview of React and HTML pages, click-to-comment inspector, and static export.",
   "type": "module",
   "exports": {

package/skills/apply-comments/SKILL.md

@@ -1,15 +1,17 @@
 ---
 name: apply-comments
-description: Apply pending @page-comment markers written by the open-pages inspector tool. Use when the user asks to "apply comments", "process page comments", "apply the inspector comments", or references markers left inside `pages/<id>/index.tsx` (or its `components/*.tsx`).
+description: Apply pending @page-comment markers written by the open-pages inspector tool. Use when the user asks to "apply comments", "process page comments", "apply the inspector comments", or references markers left inside `pages/<id>/index.tsx`, `emails/<id>/index.tsx`, or their `components/*.tsx`.
 ---
 
 # Apply page comments
 
-The open-pages viewer has an inspector that lets the user click any element on the live page and attach a textual comment (e.g. *"make this red"*, *"change to 'Open Pages Rocks'"*). Each comment is persisted as an in-source JSX marker inside the page's source — usually `pages/<pageId>/index.tsx`, occasionally a file under `pages/<pageId>/components/`.
+The open-pages viewer has an inspector that lets the user click any element on the live page (or rendered email) and attach a textual comment (e.g. *"make this red"*, *"change to 'Open Pages Rocks'"*). Each comment is persisted as an in-source JSX marker inside the source — usually `pages/<pageId>/index.tsx`, occasionally a file under `pages/<pageId>/components/`; for emails, `emails/<id>/index.tsx` and `emails/<id>/components/`.
 
 Your job: read those markers, perform the described edits, and delete the markers.
 
 > **Before making any page edit**, consult the **`page-authoring`** skill (and the **`shadcn`** skill for component props and variants) — it is the technical reference for how a page is structured (file contract, `className` styling, layout and responsive rules, type scale, interactivity). A comment like *"make this bigger"* or *"change the accent colour"* should be applied in a way that stays consistent with those rules and still works on mobile.
+>
+> **For a marker under `emails/`**, consult the **`create-email`** skill instead: emails are react-email components with email-safe Tailwind only (no flex/grid, no `ui/` components, no hooks), and the edit must keep both the HTML and the derived plain text sensible.
 
 ## Marker format
 
@@ -29,7 +31,7 @@ Your job: read those markers, perform the described edits, and delete the marker
 
 1. **Identify the target page(s).**
    - If the user names one (`launch`, `pricing`, etc.), work on that single page's source files.
-   - If they say "all" or don't specify, scan every `pages/*/index.tsx` and `pages/*/components/*.tsx`. Process each page one at a time.
+   - If they say "all" or don't specify, scan every `pages/*/index.tsx`, `pages/*/components/*.tsx`, `emails/*/index.tsx`, and `emails/*/components/*.tsx`. Process each page or email one at a time.
 
 2. **Read the file and find all markers.**
    - Run the regex above against the whole file.
@@ -56,7 +58,7 @@ Your job: read those markers, perform the described edits, and delete the marker
    - After all edits, re-read the file and confirm the only remaining markers are ones you reported as skipped.
    - Confirm the edited JSX is well-formed (balanced tags, no dangling attributes) and that changed `className` strings are literal Tailwind utilities. If the project's `package.json` has typecheck/lint scripts, run them with the project's package manager; scaffolded projects ship neither TypeScript nor a linter — there, rely on the running dev server (or the `build` script) to surface compile errors. Fix any errors you introduced.
    - For layout changes, mentally check the Mobile viewport (390px): did the edit introduce a fixed width or a grid with no stacking fallback?
-   - When a comment changed interactive elements, forms, motion, or layout, run the `web-design-guidelines` skill on the page and fix any regression it reports before you report.
+   - When a comment changed interactive elements, forms, motion, or layout, run the `web-design-guidelines` skill on the page and fix any regression it reports before you report. (Not for emails: check the email's HTML and Text views in the viewer instead.)
 
 7. **Report.**
    - Summarise: `N applied, M skipped` plus a one-line description of each change (including the page id).

package/skills/create-email/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: create-email
+description: Use this skill when the user wants to create, build, draft, or edit an email template in this open-pages repo — a welcome email, receipt, password reset, newsletter, notification, invite, or any HTML email. Triggers on phrases like "make an email for X", "email template", "transactional email", "newsletter", "onboarding email", or when the user asks to add or change content under `emails/`. Do NOT use for web pages (that is `create-page`) or for the framework itself.
+---
+
+# Create an email in open-pages
+
+An email is one folder under `emails/<id>/` with an `index.tsx` that default-exports a [react-email](https://react.email) component. The workspace renders it on the server to a single HTML document with inlined styles plus a plain-text alternative, previews both live, and exports them with `open-pages export`. Nothing in an email runs in a browser: no hooks with effects, no state, no event handlers, no browser APIs.
+
+This skill owns both the **workflow** and the **technical reference** for emails. The `page-authoring` skill does not apply here: emails are not web pages, and the shadcn `ui/` set cannot be used in them.
+
+You only write files under `emails/<id>/`, plus whatever `npx shadcn@latest add @emailcn/...` installs under `components/email/`. Never modify `package.json`, `open-pages.config.ts`, `components.json`, or other emails.
+
+## Step 1 — Clarify requirements (MUST ask before writing code)
+
+Lock in the decisions below with `AskUserQuestion` before writing. Skip a question only when the user's message already answers it unambiguously, and restate your assumption when you skip.
+
+1. **Email type** — offer the closest fits: transactional (welcome / onboarding, receipt, password reset, magic link, OTP, invite, notification) or marketing (newsletter, announcement, promotion). Mark the best fit "(Recommended)". Transactional emails are short, one action, no images required; marketing emails carry sections and imagery.
+
+2. **Starting point** — offer: an emailcn block (Recommended when one matches: `block-onboarding-*`, `block-receipt-*`, `block-auth-*`, `block-invite-*`, `block-newsletter-*`, `block-notification-*`), emailcn components composed by you (headers, heroes, CTAs, footers, stats, pricing tables), or react-email primitives from scratch. The block route is fastest and already email-client-safe.
+
+3. **Look** — list every `components/email/theme-<id>.ts` that pairs with a `themes/<id>.md` first (Recommended when one exists: the email will match the workspace's pages), then the emailcn themes that fit the brand: `theme-default` (neutral), `theme-linear`, `theme-vercel`, `theme-stripe`, `theme-notion`, `theme-slack`, `theme-github`, `theme-raycast`, `theme-apple`, `theme-airbnb`, `theme-dropbox`, `theme-nike`, `theme-twitch`, `theme-stack-overflow`. Step 3b covers applying a workspace theme.
+
+4. **Content** — the subject line, the preheader (the preview text mail clients show next to the subject), the sender name or product name, the one thing the reader should do (CTA label + URL), and any real copy, prices, or names. Real emails live on real content; ask rather than invent.
+
+Ask follow-ups only if still unclear: logo URL, brand color, footer address and unsubscribe URL (marketing emails legally need both).
+
+## Step 2 — Pick an email id
+
+Kebab-case, short, descriptive: `welcome`, `receipt`, `password-reset`, `weekly-digest`, `invite-teammate`. Check `emails/` to avoid collisions. Page ids and email ids are separate namespaces, so `welcome` can be both a page and an email.
+
+## Step 3 — Install what the email needs
+
+The workspace ships `react-email` (components, `Tailwind`, `render`) and a `components.json` with the `@emailcn` registry registered. Everything else is installed per item with the shadcn CLI:
+
+```bash
+# a full email as a block (installs its theme, fonts, sections)
+npx shadcn@latest add @emailcn/react-email/block-onboarding-default
+
+# individual sections and a theme
+npx shadcn@latest add @emailcn/react-email/theme-linear @emailcn/react-email/split-hero @emailcn/react-email/navigation-footer
+
+# see everything available
+curl -s https://emailcn.run/r/registry.json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(JSON.parse(s).items.filter(i=>i.name.startsWith("react-email/")).map(i=>i.name).join("\n")))'
+```
+
+Files land under `components/email/` (`email-theme.ts`, `theme-<id>.ts`, `email-assets.ts`, one file per section or block). They are the email equivalent of `ui/`: shared by every email, read but not edited per email. Wrap or extend a section inside `emails/<id>/components/` when one email needs a different look. Always use the `react-email/` variants of registry items; the `mjml-react/` and `jsx-email/` variants need packages this workspace does not install.
+
+### Step 3b — Using a workspace theme
+
+Every workspace theme authored by `create-theme` ships `components/email/theme-<id>.ts`, the same palette as an `EmailTheme` object (mail clients cannot read `themes/<id>.css`). To put an email on that theme:
+
+```tsx
+import { createEmailTailwindConfig } from '@/components/email/email-theme';
+import { autonoTheme } from '@/components/email/theme-autono';
+
+<Tailwind config={createEmailTailwindConfig(autonoTheme)}>…</Tailwind>
+```
+
+emailcn **sections** (`split-hero`, `call-to-action`, `navigation-footer`, `button`, …) take a `theme` prop and default to `defaultTheme`, so pass the workspace theme to each one you compose. emailcn **blocks** (`block-*`) pin `defaultTheme` (or their named theme) inside the file; to put a block on a workspace theme, copy it into `emails/<id>/components/` and swap the theme import there rather than editing the shared copy.
+
+If `themes/<id>.css` exists but `components/email/theme-<id>.ts` does not, generate it the way `create-theme` does instead of converting colors by hand:
+
+```bash
+node .agents/skills/create-theme/references/email-theme-from-css.mjs themes/<id>.css <id> > components/email/theme-<id>.ts
+```
+
+(`components/email/email-theme.ts` must exist first: `npx shadcn@latest add @emailcn/react-email/theme-default` installs it.)
+
+## Step 4 — Write `emails/<id>/index.tsx`
+
+### File contract
+
+```tsx
+import type { EmailMeta } from '@autono/open-pages';
+import { Body, Button, Container, Head, Heading, Html, Preview, Section, Tailwind, Text } from 'react-email';
+import { createEmailTailwindConfig } from '@/components/email/email-theme';
+import { defaultTheme } from '@/components/email/theme-default';
+
+export const meta: EmailMeta = {
+  title: 'Welcome',
+  subject: 'Welcome to Acme',
+  description: 'Sent right after signup.',
+  createdAt: '2026-09-27T20:00:00.000Z',
+};
+
+export default function Welcome() {
+  return (
+    <Html lang="en">
+      <Head />
+      <Preview>Your workspace is ready. Here is how to get started.</Preview>
+      <Tailwind config={createEmailTailwindConfig(defaultTheme)}>
+        <Body className="bg-bg font-sans">
+          <Container className="mx-auto max-w-email p-8">
+            <Heading className="m-0 font-24 text-fg">Welcome to Acme</Heading>
+            <Text className="font-16 text-fg-2">Your workspace is ready.</Text>
+            <Section className="my-6">
+              <Button href="https://acme.example/app" className="rounded bg-brand px-5 py-3 font-14 font-medium text-brand-fg">
+                Open Acme
+              </Button>
+            </Section>
+          </Container>
+        </Body>
+      </Tailwind>
+    </Html>
+  );
+}
+```
+
+- **`meta`** — `title` is the workspace card name; `subject` is the subject line the email ships with; `description` is what it is for; `createdAt` is an ISO literal set once (the framework reads these with a regex, so keep them plain string literals).
+- **The default export** takes no props. When composing an emailcn block that takes props (`_firstName`, `ctaHref`, …), pass sample values in the email; the sending system will substitute real ones later. Keep sample data plausible, not `Lorem ipsum`.
+- **Structure** is always `Html > Head + Preview + Tailwind > Body > Container`. `Preview` is the preheader; keep it under 90 characters and make it continue the subject line, not repeat it.
+- **Helper components** go under `emails/<id>/components/`. Split sections out when `index.tsx` passes ~120 lines.
+- **Images** must be absolute `https://` URLs with `width`, `height`, and `alt`. Email clients do not load relative paths or local files. emailcn's `emailAsset()` helper points at hosted sample imagery; replace it with the user's hosted assets before shipping.
+
+### What react-email gives you
+
+`Html`, `Head`, `Preview`, `Body`, `Container` (centered column, set `max-w-container` or `max-w-[600px]`), `Section` (a table row band), `Row` + `Column` (side-by-side cells), `Heading`, `Text`, `Link`, `Button` (a padded anchor that survives Outlook), `Img`, `Hr`, `Font` (web font with fallback), `Markdown`, `CodeBlock` / `CodeInline`. Every one of them renders to nested tables and inline styles; you never write `<table>` yourself.
+
+`Tailwind` compiles the utilities in `className` to inline styles at render time. Only utilities it can read literally are compiled (no runtime string building), and only properties email clients support survive: spacing, colors, typography, borders, widths, alignment. `flex`, `grid`, `gap`, `position`, `transform`, `transition`, `hover:` and `dark:` variants, and CSS variables are not email-safe; use `Row` / `Column` for layout and `Section` padding for spacing. A utility the compiler cannot resolve is left behind as a `class` attribute and does nothing in mail clients; the viewer shows an amber "N classes did not compile" chip (hover it for the list) and the dev server logs the same.
+
+The emailcn theme config (`components/email/email-theme.ts`) adds semantic names on top of Tailwind: colors `bg`, `bg-2`, `bg-3`, `fg`, `fg-2`, `fg-3`, `brand`, `brand-fg`, `brand-hover`, `stroke`, `danger`, `success`, `warning` (so `bg-bg`, `text-fg-2`, `bg-brand text-brand-fg`, `border-stroke`), `max-w-email` for the 600px column, `rounded` / `rounded-lg` from the theme radii, `font-11` … `font-28` type steps, and a `mobile:` variant. Read that file for the current list before inventing names. Prefer these over raw hex so swapping the theme file restyles the email.
+
+**Registry quirk, handled for you.** emailcn's react-email blocks and sections use `bg-background`, `text-foreground`, `text-foreground-muted`, `bg-primary`, `text-primary-fg`, `border-border`, and `max-w-container`, which the `email-theme.ts` the same registry installs does not define. open-pages patches that module at load time so those names resolve to the matching theme fields (`colorBackground`, `colorText`, `colorPrimary`, `containerWidth`, …) in dev, export, and build. Both vocabularies work in your own emails; do not edit `components/email/email-theme.ts` to add them by hand.
+
+### Email constraints that differ from pages
+
+- **One column, 600px.** Multi-column layouts stack on phones only when built with `Row` / `Column`; keep them to two columns and put the important one first.
+- **Fonts**: a web font via `<Font>` with a system fallback, or a plain stack (`-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif`). Gmail ignores web fonts; the fallback must look right on its own.
+- **Type**: 16px body (14px minimum), 24–32px headings, line-height 1.5. Dark text on light backgrounds; many clients force-invert dark designs unpredictably.
+- **Buttons** are `<Button href>` with padding classes, never `<button>`; there is no JavaScript.
+- **Footer** of a marketing email: physical address and an unsubscribe link. Transactional emails: a one-line reason ("You are receiving this because you created an account.").
+- **Plain text** is derived automatically from the HTML. Make sure the HTML reads top to bottom as prose: the CTA text plus its URL, no meaning carried only by images.
+- **No `window`, `document`, `useState`, `useEffect`, `fetch`, event handlers** anywhere. The module is evaluated in Node.
+
+## Step 5 — Preview and check
+
+The dev server renders the email at `http://localhost:5173/e/<id>` with **HTML** and **Text** views, a **Mobile** (375px) toggle, **Copy HTML**, and **Open** (the raw document by itself). The frame re-renders on every save of the email or of anything it imports. An error banner in the frame means the module threw on the server; the dev server output has the stack.
+
+Check both views. In Text, every link should read as `label URL`, and nothing important should be missing. If the header shows an amber "classes did not compile" chip, resolve every name it lists before handing off; a shipped email must have zero.
+
+## Step 6 — Self-review
+
+- [ ] `emails/<id>/index.tsx` default-exports one zero-prop component; `meta` has `title`, `subject`, and a fresh `createdAt` literal.
+- [ ] `Preview` is set, under 90 characters, and does not repeat the subject.
+- [ ] Only `react-email` components and files under `components/email/` are imported. Nothing from `@/ui`, `@/lib`, `@/hooks`, `lucide-react`, or any browser-only package.
+- [ ] No hooks, state, effects, handlers, or browser globals.
+- [ ] Every `className` is a literal Tailwind utility the email compiler supports; layout uses `Section` / `Row` / `Column`, not flex or grid. The viewer reports zero uncompiled classes.
+- [ ] Every `Img` has an absolute `https://` `src`, `width`, `height`, and `alt`.
+- [ ] Every CTA is a `<Button href>` or `<Link href>` with an absolute URL, and the primary CTA appears once.
+- [ ] Body text is 14px or larger; the layout holds at 375px in the Mobile toggle.
+- [ ] Marketing emails carry a physical address and an unsubscribe link; transactional emails carry a one-line reason for receipt.
+- [ ] The Text view reads as complete prose with every link's URL present.
+- [ ] Nothing under `components/email/` was edited for this one email; nothing outside `emails/<id>/` changed except emailcn installs.
+
+## Step 7 — Hand off to the user
+
+Tell the user:
+
+- The email id, its file path, and the `subject` it carries.
+- The preview URL — `http://localhost:5173/e/<id>` — with HTML / Text views, a Mobile toggle, Copy HTML, and Inspect (press `i`, click any element, leave a note, then ask you to run `apply-comments`).
+- That `open-pages export <id>` writes `export/emails/<id>/index.html` and `index.txt`, ready to paste into Resend, SendGrid, Postmark, Mailchimp, Customer.io, or any sender that takes raw HTML; `Copy HTML` in the viewer gives the same document.
+- That the email's look comes from `components/email/theme-*.ts`; swapping the theme import restyles it without touching its structure.
+- If dev isn't running: run the project's `dev` script from the project root with its package manager (`npm run dev`, `pnpm dev`, … — match the lockfile).
+
+Don't run the dev server yourself unless asked.