@lunora/cli 1.0.0-alpha.362 → 1.0.0-alpha.363

package/skills/lunora-setup-hyperdrive-global/SKILL.md

@@ -1,67 +1,55 @@
 ---
 name: lunora-setup-hyperdrive-global
-description: Use PlanetScale (Postgres/MySQL via Cloudflare Hyperdrive) as a first-class, REACTIVE `.global()` storage backend for a Lunora app — and migrate an existing D1 `.global()` dataset to it. Use for `@lunora/hyperdrive/global`, `.global({ backend: "hyperdrive" })`, `createHyperdriveGlobalCtxDb`, the app-builder `.hyperdriveGlobal()` declaration, the `HYPERDRIVE` binding pointing at PlanetScale, and `lunora migrate d1-to-hyperdrive`. NOT the same as `@lunora/hyperdrive` (which is an action-only, non-reactive `ctx.sql`).
+description: Stores a Lunora app's own `.global()` tables in Postgres or MySQL (PlanetScale, Neon, RDS, or any Hyperdrive-reachable database) through Cloudflare Hyperdrive instead of D1. Lunora owns the schema, and live queries stay fully reactive. Also migrates an existing D1 `.global()` dataset with `lunora migrate d1-to-hyperdrive`. Covers `.global({ backend: "hyperdrive" })`, `@lunora/hyperdrive/global` (`buildPgExec` / `buildMysqlExec`, `createHyperdriveGlobalCtxDb`), the app builder's `.hyperdriveGlobal({ engine, exec })`, and the `HYPERDRIVE` binding. Use when the user wants to "move global tables to PlanetScale/Postgres", "use Postgres instead of D1", or "migrate off D1", or edits `.global({ backend: "hyperdrive" })`. For querying an existing, externally owned database from an action (non-reactive `ctx.sql`), use `lunora-setup-hyperdrive` instead.
 ---
 
 # Lunora Setup: Hyperdrive Global Backend (Postgres/MySQL)
 
-Store Lunora `.global()` tables in a **Postgres or MySQL database reached
-through [Cloudflare Hyperdrive](https://developers.cloudflare.com/hyperdrive/)**
-— **PlanetScale**, Neon, RDS, or any Hyperdrive-reachable database — instead of
-D1, as a **drop-in, fully reactive** backend. (PlanetScale on Cloudflare is the
-headline use case; nothing here is PlanetScale-specific.)
+Store `.global()` (cross-tenant) tables in a Postgres or MySQL database reached
+through Cloudflare Hyperdrive instead of D1. PlanetScale on Cloudflare is the
+typical case, but nothing here is PlanetScale-specific.
 
-> **`@lunora/hyperdrive/global` vs. `@lunora/hyperdrive` (`ctx.sql`).** The
-> `ctx.sql` surface is an action-only, **non-reactive** escape hatch for
-> integrating a legacy database. `@lunora/hyperdrive/global` is different: Lunora
-> **owns** the schema (column-per-field, like D1) and routes every write through
-> its own store core, so live queries stay reactive — the writer is injected as
-> `globalDb` and the shard DO's broadcast hook re-runs subscriptions exactly as
-> with D1.
-
-## When to Use
-
-- You want `.global()` (cross-tenant) tables to live in PlanetScale rather than
-  D1 — e.g. for larger datasets, existing SQL tooling, or unified Cloudflare
-  billing.
-- You're migrating an existing D1 `.global()` dataset to PlanetScale.
+> **This is not `ctx.sql`.** `@lunora/hyperdrive`'s `ctx.sql`
+> (`lunora-setup-hyperdrive`) is an action-only, non-reactive client for a
+> database Lunora doesn't own. `.global({ backend: "hyperdrive" })` is the opposite:
+> Lunora owns the tables (one column per field, like D1), and every write goes
+> through Lunora's store core. Subscriptions re-run exactly as they do with D1.
+> The live-query guarantee covers only writes made through Lunora (`ctx.db`).
+> Rows written to the database directly are invisible to live queries.
 
 ## When Not to Use
 
-- You only need to read/write a **legacy** external DB from an action — use
-  `@lunora/hyperdrive` (`ctx.sql`) instead; it's lighter and action-scoped.
-- Your global data is small and D1 is fine — bare `.global()` (D1) needs no
-  extra binding or driver.
+- You only need to read or write a legacy database from an action: use
+  `lunora-setup-hyperdrive`.
+- Your global data is small and D1 is fine: bare `.global()` needs no extra
+  binding or driver.
 
 ## How it works
 
-PlanetScale reuses Lunora's dialect-parameterized store core (the same one D1
-uses): a `SqlDialect` (Postgres or MySQL) shapes the SQL, and a Hyperdrive-backed
-`SqlExec` runs it from inside the Durable Object that hosts the global writer.
-Values are stored SQLite-shaped (boolean → 1/0, JSON → text/json, bigint →
-decimal), so the value codec is shared with D1.
+The same dialect-parameterized store core that backs D1 runs here with a
+Postgres or MySQL `SqlDialect`. A Hyperdrive-backed `SqlExec` executes it from
+inside the Durable Object that hosts the global writer. Values are stored in the
+same shapes D1 uses (boolean → 1/0, JSON → text/json, bigint → decimal).
 
-## Step 1: Install the package + a driver
+## Step 1: Install
 
 ```bash
-pnpm add @lunora/hyperdrive/global
-# choose the driver matching your engine (optional peer deps — none is bundled):
-pnpm add postgres        # PlanetScale Postgres → fromPostgresJs
-# or
-pnpm add mysql2          # PlanetScale MySQL    → mysql2/promise
+pnpm add @lunora/hyperdrive @lunora/sql-store
+pnpm add postgres   # Postgres engine → buildPgExec(fromPostgresJs(...))
+# or: pnpm add mysql2  → buildMysqlExec(mysql2/promise pool), MySQL 8.0+
 ```
 
-## Step 2: Create the Hyperdrive binding pointing at PlanetScale
+`@lunora/hyperdrive/global` is a subpath export of `@lunora/hyperdrive`, not a
+separate package. Codegen requires `@lunora/sql-store` too, because the generated
+`_generated/app.ts` imports its `SqlExec` types. Install the driver that matches
+your engine. Drivers are optional peer dependencies.
 
-Create a PlanetScale database from the Cloudflare dashboard (unified billing),
-then a Hyperdrive config over its connection string:
+## Step 2: Create the Hyperdrive binding
 
 ```bash
 wrangler hyperdrive create my-db --connection-string="postgres://user:pass@host/db" # gitleaks:allow -- placeholder
 ```
 
-Add the binding to `wrangler.jsonc` (use `localConnectionString` for `lunora dev`):
-
 ```jsonc
 {
     "hyperdrive": [
@@ -70,15 +58,14 @@ Add the binding to `wrangler.jsonc` (use `localConnectionString` for `lunora dev
 }
 ```
 
-The binding is required, not optional: with no `hyperdrive` entry at all,
-`lunora dev` and `lunora deploy` both refuse to start. The NAME is yours — the
-validator only checks that some binding exists, because your `exec` selector is
-what picks it.
+A binding is required. Without any `hyperdrive` entry, config validation errors
+and `lunora dev` / `lunora deploy` won't start. You choose the name: the
+validator only checks that at least one binding exists, and your `exec` selector picks it.
 
-> **Read-your-writes:** point the Hyperdrive config at the **primary** (or pin
-> writes to it) so a write then immediate read isn't served by a stale replica.
+Point Hyperdrive at the primary (or pin writes to it) so you can read your own
+writes. A replica can serve a stale read right after a write.
 
-## Step 3: Mark tables `.global({ backend: "hyperdrive" })`
+## Step 3: Mark tables
 
 ```ts
 // lunora/schema.ts
@@ -89,88 +76,99 @@ export default defineSchema({
 });
 ```
 
-A bare `.global()` stays on D1. **One backend per app** — mixing D1- and
-PlanetScale-backed global tables in the same app isn't supported yet (codegen
-errors clearly).
+Bare `.global()` stays on D1. An app can use only one global backend: codegen fails
+if the schema mixes D1 and Hyperdrive global tables.
 
-## Step 4: Wire `.hyperdriveGlobal()` in the app composition
+## Step 4: Wire `.hyperdriveGlobal()`
 
-Codegen emits a `.hyperdriveGlobal()` builder method. Supply the engine and an `exec`
-built from the Hyperdrive binding (cache the driver on the DO instance; rebuild
-lazily after hibernation):
+Codegen emits a `.hyperdriveGlobal({ engine, exec, origin? })` builder method.
+`exec` builds a `SqlExec` from `env`:
 
 ```ts
-import { buildPgExec } from "@lunora/hyperdrive/global";
 import { fromPostgresJs } from "@lunora/hyperdrive";
+import { buildPgExec } from "@lunora/hyperdrive/global";
 import postgres from "postgres";
 
-export default defineApp<Env>()
+import { defineApp } from "../lunora/_generated/app.js";
+
+const app = defineApp<Env>()
     .shard((env) => env.SHARD)
     .hyperdriveGlobal({
         engine: "postgres",
         exec: (env) => buildPgExec(fromPostgresJs(postgres(env.HYPERDRIVE.connectionString))),
-    });
+    })
+    .build();
+
+export const ShardDO = app.ShardDO;
 ```
 
-For MySQL, create the pool with the **`FOUND_ROWS`** flag (the optimistic-concurrency
-guard needs matched-row counts, or idempotent writes raise spurious conflicts):
+For MySQL, create the pool with the `FOUND_ROWS` flag. The optimistic-concurrency
+guard needs matched-row counts. Without the flag, an idempotent write reports
+zero affected rows and raises a spurious conflict. `buildMysqlExec` throws at
+construction when the flag is missing. If it can't read the flag, it warns once instead.
 
 ```ts
 import { buildMysqlExec } from "@lunora/hyperdrive/global";
 import mysql from "mysql2/promise";
 
+// inside the builder chain:
 .hyperdriveGlobal({
     engine: "mysql",
     exec: (env) => buildMysqlExec(mysql.createPool({ uri: env.HYPERDRIVE.connectionString, flags: ["FOUND_ROWS"] })),
-});
+})
 ```
 
-## Step 5: Regenerate + run
+Outside the app builder, for example in tests or a custom host,
+`createHyperdriveGlobalCtxDb({ engine, exec, ... })` builds the same reactive writer
+directly.
+
+## Step 5: Regenerate and run
 
 ```bash
-lunora codegen   # wires config.hyperdriveGlobal and the .hyperdriveGlobal() method
+lunora codegen
 lunora dev
 ```
 
-Tables auto-provision on first use (the runtime runs the PlanetScale DDL through
-the dialect — no manual migration needed), and subscriptions are reactive.
+Tables provision automatically on first use, because the runtime runs the DDL
+through the dialect. You don't write or commit SQL migrations. `CREATE TABLE IF NOT EXISTS` never
+reshapes an existing table, though. When a column's validator starts accepting
+null, the store reports the `ALTER` statement to run. MySQL tables created before
+the `utf8mb4_0900_bin` column collation need a one-off
+`ALTER TABLE … CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_bin`.
+See `lunora-migration-helper` for schema changes.
 
-## Migrating an existing D1 dataset → PlanetScale
+**Verify:** subscribe to a query over a hyperdrive-backed table, write through a
+mutation, and confirm that the subscription updates.
 
-Blue-green: deploy the new PlanetScale-backed worker alongside the old D1 one,
-then copy the `.global()` data:
+Postgres deployments can also serve `ctx.vectors` from pgvector instead of a Vectorize
+binding with `createPgVectorIndex` (from `@lunora/hyperdrive/global`). It supports
+equality-only metadata filters.
+
+## Migrating an existing D1 dataset
+
+The flow is blue-green: deploy the Hyperdrive-backed worker next to the D1 one,
+then copy the data:
 
 ```bash
 lunora migrate d1-to-hyperdrive \
-  --from-url https://old-d1.example.com   --from-token "$D1_ADMIN_TOKEN" \
-  --to-url   https://new-ps.example.com   --to-token   "$PS_ADMIN_TOKEN" \
-  --tables settings,orders                # omit to move every global table
-  # --out dump.ndjson                      # keep the intermediate dump to inspect
+  --from-url https://old-d1.example.com --from-token "$D1_ADMIN_TOKEN" \
+  --to-url   https://new-hd.example.com --to-token   "$HD_ADMIN_TOKEN" \
+  --tables settings,orders   # omit to move every global table; --out dump.ndjson keeps the dump
 ```
 
-It streams the source's global rows to NDJSON, imports them into the target
-(whose `.global({ backend: "hyperdrive" })` tables route the writes to
-PlanetScale), and verifies the row counts match. Rows whose `_id` already exists
-are reported as conflicts, not duplicated.
-
-> **Direct external writes** to PlanetScale (bypassing Lunora) are invisible to
-> live queries — same as D1. Let Lunora own the writes.
+The command exports the source's global rows to NDJSON, imports them into the
+target, and compares row counts. It refuses to run when the source and target
+resolve to the same URL, and non-localhost URLs must use https. Rows whose `_id`
+already exists in the target are reported as conflicts and not duplicated.
+A count mismatch is a warning: inspect it with `--out`, resolve it, and re-run.
+Tokens default to `--token` / `LUNORA_ADMIN_TOKEN`.
 
 ## Common Pitfalls
 
-1. **Mixing backends.** One global backend per app (codegen errors on a mix).
-2. **Missing driver.** `postgres`/`mysql2` are optional peer deps — install the
-   one matching your engine.
-3. **Stale-replica reads.** Point Hyperdrive at the primary for read-your-writes.
-4. **Expecting external writes to be reactive.** They aren't — route writes
-   through Lunora (`ctx.db`).
-
-## Checklist
-
-- [ ] `@lunora/hyperdrive/global` + the engine's driver installed.
-- [ ] Hyperdrive binding (`HYPERDRIVE`) created over the PlanetScale connection
-      string, with a `localConnectionString` for dev.
-- [ ] Target tables marked `.global({ backend: "hyperdrive" })` (one backend per app).
-- [ ] `.hyperdriveGlobal({ engine, exec })` wired in the app composition.
-- [ ] `lunora codegen` run; `lunora dev` serves the tables reactively.
-- [ ] (Migrating) `lunora migrate d1-to-hyperdrive` run; row counts verified.
+1. **Installing `@lunora/hyperdrive/global` as a package name.** It's a subpath.
+   Install `@lunora/hyperdrive` and `@lunora/sql-store`.
+2. **Mixing D1 and Hyperdrive global tables.** Codegen rejects this.
+3. **Missing `FOUND_ROWS` on MySQL.** It causes spurious OCC conflicts on idempotent writes.
+4. **Stale-replica reads.** Point Hyperdrive at the primary.
+5. **Writing to the database directly.** Live queries won't see those writes. Route writes
+   through `ctx.db`.

package/skills/lunora-setup-mail/SKILL.md

@@ -1,157 +1,123 @@
 ---
 name: lunora-setup-mail
-description: Adds transactional email to a Lunora app. Use for sending mail (verification, password reset, invites, notifications) via `lunora registry add mail`, the `sendEmail` / `queueEmail` actions, the `SEND_EMAIL` Cloudflare Email Workers binding, Resend, React email templates, and the dev mail catcher.
+description: Adds transactional email to a Lunora app with the `mail` registry item (`@lunora/mail`). Covers the server-only `internal.mail.sendEmail` / `queueEmail` actions, the `SEND_EMAIL` Cloudflare Email Workers binding, Resend via `RESEND_API_KEY`, `react-email` templates via `renderEmail`, the dev mail catcher (Studio Mail tab), E2E inbox helpers, and inbound mail. Use when the user wants to send verification, password-reset, invite or notification email, runs `lunora add email` or `lunora registry add mail`, edits `lunora/mail/index.ts`, asks why mail isn't delivered or doesn't show up in the Studio, or wants to receive email.
 ---
 
 # Lunora Setup Mail
 
-Wire transactional email into a Lunora app using the `mail` registry item, which
-is built on `@lunora/mail` (a Cloudflare Email Workers transport with
-header-injection-safe address handling) and exposes a `sendEmail` `internalAction`
-plus a fire-and-forget `queueEmail` `internalAction` — server-only, because a
-client-callable general-purpose mailer is an open relay. In dev, every send is captured into the
-Studio Mail tab instead of going out.
+The `mail` registry item wraps `@lunora/mail`, which validates addresses against
+header injection before sending. It exposes two `internalAction`s, `sendEmail`
+and `queueEmail`. Both are server-only on purpose: a mailer that lets the client
+pick the recipient, subject and body is an open relay for phishing through your
+verified domain. In dev, every send is captured into the Studio Mail tab and
+nothing is delivered.
 
-## When to Use
-
-- Sending app→user mail: invites, notifications, receipts.
-- Delivering verification / password-reset mail from `@lunora/auth`.
-- Using a React (`react-email`) template or a hosted provider (Resend).
-
-## When Not to Use
-
-- The project has no Lunora backend yet — use `lunora-quickstart` first.
-- Mail is already installed and you just want to send — call
-  `ctx.runAction(internal.mail.sendEmail, …)` from a server handler.
-
-## Workflow
-
-1. Add the `mail` item.
-2. Configure the `SEND_EMAIL` binding (or a provider) and `MAIL_FROM`.
-3. Regenerate types with `lunora codegen`.
-4. Send mail from a server function; render a React template if needed.
+If the project has no Lunora backend yet, start with `lunora-quickstart`.
 
 ## Step 1: Add the item
 
 ```bash
-lunora registry add mail
+lunora add email                          # asks for the verified destination address
+lunora add email --mail-to ops@example.com
+lunora registry add mail                  # low-level: leaves the REPLACE_ME@example.com placeholder
 ```
 
-This:
+Then run `pnpm install` and `lunora codegen`. The item does the following:
 
-1. Adds `@lunora/mail` and `@lunora/server` to `package.json` (run
-   `pnpm install` afterwards).
-2. Copies `lunora/mail/index.ts` (the `sendEmail` / `queueEmail`
-   **`internalAction`s**) into your project — it is **yours** to edit.
-3. Adds a `send_email` binding (`SEND_EMAIL`, with a `destination_address`
-   placeholder) to `wrangler.jsonc` and scaffolds `MAIL_FROM` (the default
-   sender) into `.dev.vars`.
+1. Adds `@lunora/mail` and `@lunora/server`.
+2. Copies `lunora/mail/index.ts` into the project. The project owns this file. It defines `sendEmail`, which returns `{ id }`, and `queueEmail`, which returns `{ queued: true }`.
+3. Adds a `send_email` binding named `SEND_EMAIL` (with `destination_address`) to `wrangler.jsonc`.
+4. Writes `MAIL_FROM` to `.dev.vars`.
 
-## Step 2: Configure delivery
+Codegen emits the two functions as `internal.mail.sendEmail` and
+`internal.mail.queueEmail`. They are not in the client-reachable `api`. A client
+call to them returns `FUNCTION_NOT_FOUND`.
 
-| Name             | Where                                | Notes                                                                             |
-| ---------------- | ------------------------------------ | --------------------------------------------------------------------------------- |
-| `SEND_EMAIL`     | `wrangler.jsonc` → `send_email[]`    | Cloudflare Email Workers binding. Single-recipient; only verified destinations.   |
-| `MAIL_FROM`      | var (`.dev.vars` / `wrangler.jsonc`) | Default sender address.                                                           |
-| `RESEND_API_KEY` | secret (optional)                    | Use a hosted provider instead — pass `apiKey` to `createMailer` in `lunora/mail`. |
+## Step 2: Choose the delivery path
 
-For production with Cloudflare Email Workers, set up
-[Email Routing](https://developers.cloudflare.com/email-routing/): verify a
-destination address and replace the `REPLACE_ME@example.com` placeholder. Prefer
-Resend? Pass `apiKey` (or a custom `transport`) to `createMailer` in your copied
-`lunora/mail/index.ts`.
+The copied file builds its mailer with `createMailerFromEnv`. That function
+picks the transport in this order:
 
-In `lunora dev` (`WORKER_ENV=development`) the scaffold swaps in `@lunora/mail`'s
-**capture transport** automatically: every send — including `@lunora/auth`'s
-verification and forgot-password mail — is intercepted and surfaced in the
-**Studio Mail tab**. Nothing leaves your machine and no provider setup is needed.
+| Condition                                             | Transport                                           |
+| ----------------------------------------------------- | --------------------------------------------------- |
+| `LUNORA_MAIL_CAPTURE=1`, or a dev environment (below) | **Capture** into the Studio Mail tab                |
+| `SEND_EMAIL` binding present                          | Cloudflare Email Workers                            |
+| no binding, `RESEND_API_KEY` secret set               | Resend                                              |
+| none of the above                                     | throws on send (production never captures silently) |
 
-## Step 3: Regenerate types
+- **Cloudflare Email Workers.** The binding sends to a single recipient, and only to verified [Email Routing](https://developers.cloudflare.com/email-routing/) destinations. That fits app-to-operator mail. Verify the address and replace the placeholder.
+- **Resend.** Use this to send to arbitrary users. Run `wrangler secret put RESEND_API_KEY` and remove the `send_email` binding. While the binding exists it takes precedence over Resend.
+- **Capture.** Capture turns on when every env-name var (`WORKER_ENV`, `NODE_ENV`, …) looks like dev. `lunora dev` sets `WORKER_ENV=development`, so capture is on in dev. Capture writes to the root shard. If `SHARD` or `LUNORA_ADMIN_TOKEN` is missing, captured mail is discarded and a one-time warning is logged. To deliver for real from dev, set `LUNORA_MAIL_CAPTURE=0`.
 
-```bash
-lunora codegen
-```
-
-The functions surface in the generated **`internal`** (server-only) namespace as
-`internal.mail.sendEmail` and `internal.mail.queueEmail` — they are deliberately
-**not** in the client-reachable `api`.
+`MAIL_FROM` is required on every path. It accepts `Name <addr@host>` or a bare
+address.
 
-## Step 4: Send mail
+## Step 3: Send from a server function
 
-### From another function
-
-`sendEmail` is an **`internalAction`** (sending is non-transactional network
-I/O). From a mutation, schedule it as a follow-up so the request is not blocked:
+`sendEmail` is an action because sending is non-transactional network I/O. From
+a mutation, schedule it so the send runs only after the mutation commits:
 
 ```ts
-import { internalMutation, v } from "#lunora/_generated/server.js";
-
-import { internal } from "./_generated/internal";
+import { internal } from "#lunora/_generated/internal.js";
+import { mutation, v } from "#lunora/_generated/server.js";
 
-export const inviteUser = internalMutation.input({ email: v.string() }).mutation(async ({ ctx, args: { email } }) => {
-    // ...authenticate the caller and persist the invite, then send the mail as a
-    // follow-up action. The recipient is decided server-side — never forward a
-    // client-chosen `to`/`from`/`html` straight through.
+export const inviteMember = mutation.input({ teamId: v.id("teams"), email: v.string() }).mutation(async ({ ctx, args }) => {
+    // Authorize the caller and persist the invite first. The server decides
+    // the recipient and the content: never forward a client-chosen to/from/html.
     await ctx.scheduler.runAfter(0, internal.mail.sendEmail, {
-        to: email,
+        to: args.email,
         subject: "You're invited",
         html: "<p>Click the link to join.</p>",
     });
 });
 ```
 
-### Not from a client
+Sending to an arbitrary `args.email` needs the Resend path in production: the
+`SEND_EMAIL` binding only reaches its verified destination.
 
-There is no `client.action("mail/sendEmail", …)` path, and adding one is the
-mistake this item exists to prevent: a general-purpose mailer that lets the
-caller pick recipient, subject and body is an open relay for phishing through
-your verified domain. If you need a client-callable send, write a
-_purpose-specific_ public `action` that takes only safe business inputs (e.g.
-`{ orderId }`), checks `ctx.auth`/RBAC, derives the recipient server-side,
-rate-limits it (`@lunora/ratelimit`), and calls `internal.mail.sendEmail`.
+From an action, call `await ctx.runAction(internal.mail.sendEmail, { … })`.
 
-### With a React email template
+If a client needs to trigger a send, write a public action for that one purpose.
+It should take only business inputs (for example `{ orderId }`), check
+`ctx.auth`, derive the recipient on the server, rate-limit the call
+(`@lunora/ratelimit`), and then call `internal.mail.sendEmail`.
 
-React elements are not JSON-serializable across the RPC boundary, so the
-`sendEmail` args take `html` / `text`. To use a `react-email` template, render it
-where you call the mailer — edit `lunora/mail/index.ts` to pass `react` straight
-into `mailer.send`:
+### React templates
 
-```ts
-import { createMailer } from "@lunora/mail";
-import { env } from "cloudflare:workers";
+A React element can't be serialized across the RPC boundary, so render it to
+`html` and `text` first. Rendering this way keeps dev capture working:
 
-import { WelcomeEmail } from "./emails/Welcome";
+```tsx
+import { renderEmail } from "@lunora/mail"; // needs `react` installed
 
-await createMailer({ apiKey: env.RESEND_API_KEY as string, from: env.MAIL_FROM as string }).send({
-    to: "alice@example.com",
-    subject: "Welcome",
-    react: <WelcomeEmail name="Alice" />,
-});
+import { WelcomeEmail } from "./emails/welcome";
+
+const { html, text } = await renderEmail(<WelcomeEmail name={name} />);
+await ctx.runAction(internal.mail.sendEmail, { to, subject: "Welcome", html, text });
 ```
 
-## Common Pitfalls
-
-1. **Expecting prod email to "just work".** Dev captures into the Studio;
-   production needs the `SEND_EMAIL` binding (a verified destination) or
-   `RESEND_API_KEY`.
-2. **Calling `sendEmail` from the client, or as a query/mutation.** It is an
-   `internalAction` — invoke it via `ctx.runAction` / `ctx.scheduler.runAfter`
-   from a server handler. A client `client.action("mail/sendEmail", …)` is not
-   reachable and answers `FUNCTION_NOT_FOUND`.
-3. **Using `queueEmail` without a Queue binding.** It requires a Cloudflare
-   Queue producer binding; until you add one, `@lunora/mail` throws
-   `` `queue` binding is required for mailer.queue() ``. The item does not add
-   the Queue for you — see the `mail` README's "Queueing" section.
-4. **Passing a React element through the action args.** Render it inside the
-   mailer (`mailer.send({ react })`), not across the RPC boundary.
-
-## Checklist
-
-- [ ] `lunora registry add mail` run, `pnpm install` done.
-- [ ] `SEND_EMAIL` binding configured (verified destination) or
-      `RESEND_API_KEY` set; `MAIL_FROM` set.
-- [ ] `lunora codegen` run so `internal.mail.*` is generated.
-- [ ] Mail sent from a server function (`ctx.scheduler.runAfter` / `ctx.runAction`
-      with `internal.mail.sendEmail`) — never from the client.
-- [ ] Verified the send appears in the Studio Mail tab in dev.
+For the auth flows, `lunora add auth-emails` adds ready-made templates.
+
+### Queueing (optional)
+
+`queueEmail` requires a Cloudflare Queue producer binding passed as
+`createMailerFromEnv(env, { queue })` in `mailer()`, and the item doesn't add one. Without it, the call
+throws `` `queue` binding is required for mailer.queue() ``, except under
+capture, where it sends straight to the capture inbox so dev flows keep working.
+A consumer builds its mailer with `createMailerFromEnv` too, drains the queue
+with `consumeQueuedSend(mailer, message.body)` and then calls `message.ack()`
+for each message. With a queue bound in dev, the message still goes through the
+queue and the consumer's mailer captures it into the inbox. Queues deliver at least once: with
+per-message acks a later throw retries only the unacknowledged messages, while
+without them a single throw resends the whole batch. The full wiring is in the "Queueing"
+section of the item README.
+
+## Testing and inbound
+
+- **E2E.** `@lunora/mail/testing` exports `waitForMail({ baseUrl, adminToken, to, subjectMatch })` and `extractLink(mail, { match })`. Together they let you read the captured inbox and pull out a verification or reset link.
+- **Receiving mail.** `@lunora/mail/inbound` provides `createInboundEmailHandler`, `parseInboundEmail` and `dispatchToLunoraFunction`. They route Email Routing messages into a Lunora function. Mount them with the generated builder's `.onEmail(...)`.
+
+## Verify
+
+1. Run `lunora dev` and trigger a send. With `SHARD` and `LUNORA_ADMIN_TOKEN` set, the message should appear in the Studio Mail tab; if either is missing, capture discards it and logs a warning.
+2. Before deploying, run `lunora doctor`. It flags the placeholder destination. Confirm that `MAIL_FROM` is set, and that either the binding uses a verified destination or `RESEND_API_KEY` is set with the binding removed.