@warlock.js/core 4.0.174 → 4.1.2

package/skills/run-app/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: run-app
+description: 'Three operational commands — `warlock dev` (HMR + type-gen + health checks), `warlock build` (esbuild bundle), `warlock start` (spawn the production bundle). All flags, all `warlock.config.ts` knobs that shape them. Triggers: `warlock dev`, `warlock build`, `warlock start`, `devServer`, `--fresh`, `--skip-typings`, `--skip-health`, `outDirectory`, `outFile`, `sourcemap`; "start the dev server", "build for production", "run the bundle", "skip type generation", "tune watch globs"; typical config `warlock.config.ts > devServer / build`. Skip: writing a custom CLI — `@warlock.js/core/write-cli-command/SKILL.md`; config shape — `@warlock.js/core/configure-app/SKILL.md`; competing tooling `nodemon`, `tsx`, `ts-node-dev`, `esbuild` direct.'
+---
+
+# Warlock — run the app
+
+Three commands move the app through its lifecycle: `dev` while you're editing, `build` once when you're ready to ship, `start` on the server. Each is a real `CLICommand` shipped in core — same factory and preload shape as any custom command you'd write.
+
+## The shape
+
+```bash
+# Local development
+yarn warlock dev
+
+# Production build
+yarn warlock build
+
+# Run the built bundle
+yarn warlock start
+```
+
+`dev` and `start` are **persistent** (long-running, no auto-exit). `build` is one-shot — it exits when the bundle is written.
+
+## `warlock dev` — development server
+
+Boots the framework in dev mode: file watcher, HMR-style module reload, on-disk transpile cache, background type generation, health checkers. The `runtimeStrategy` is set to `"development"` for the lifetime of the process.
+
+### Flags
+
+| Flag                  | Default | Purpose                                                                                                  |
+| --------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `--fresh, -f`         | off     | Delete `.warlock/manifest.json` before start — forces a full re-parse from disk. Use after odd boot states. |
+| `--skip-typings, -st` | off     | Skip background type generation **for this run**. Overrides `devServer.generateTypings` config.           |
+| `--skip-health, -sh`  | off     | Skip file health checkers **for this run**. Overrides `devServer.healthCheckers` config.                  |
+
+When a flag is **not** passed, the corresponding `warlock.config.ts > devServer.*` value applies. When passed, the flag wins.
+
+### What it preloads
+
+```ts
+preload: {
+  runtimeStrategy: "development",
+  config: true,        // all src/config/*.ts
+  bootstrap: true,     // env + app + prestart hooks
+  prestart: true,      // src/app/prestart.ts if present
+  connectors: true,    // Early-phase connectors only (db, cache, logger, ...)
+}
+```
+
+HTTP + Socket connectors are **Late** phase — they boot later in the dev-server startup sequence, after app modules load. That ordering is what guarantees `app.http` / `app.socket` are live by the time your `main.ts` runs.
+
+### `devServer.*` config knobs
+
+```ts title="warlock.config.ts"
+import { defineConfig } from "@warlock.js/core";
+
+export default defineConfig({
+  devServer: {
+    watch: {
+      include: ["**/*.{ts,tsx}"],
+      exclude: ["**/node_modules/**", "**/dist/**", "**/.warlock/**", "**/.git/**"],
+    },
+    generateTypings: true,             // background type generation
+    healthCheckers: [...] /* or false */,
+    transpileCacheDebug: false,        // name cache files <slug>.<hash>.js w/ // @source markers
+  },
+});
+```
+
+- **`watch.include` / `watch.exclude`** — globs piped into the file watcher. Override when you have non-`.ts(x)` files driving reloads (e.g. SQL fixtures), or to exclude a generated folder.
+- **`generateTypings`** — turn off if you're committing generated typings and don't want them rewritten on every boot. The `--skip-typings` flag is the per-run version.
+- **`healthCheckers`** — custom file health checker contracts (or `false` to disable). The `--skip-health` flag is the per-run version.
+- **`transpileCacheDebug`** — diagnostic only. Names `.warlock/transpile/*.js` files `<slug>.<hash>.js` and appends `// @source <path>` markers so you can eyeball which cache entry came from which source. Leave off in normal use.
+
+## `warlock build` — production bundle
+
+esbuild bundle of the app down to a single JS file in `dist/`. No flags — every setting comes from `warlock.config.ts > build`.
+
+### `build.*` config knobs
+
+```ts title="warlock.config.ts"
+export default defineConfig({
+  build: {
+    outDirectory: "dist",        // default — relative or absolute
+    outFile: "app.js",            // default — bundle filename
+    minify: true,                 // default — esbuild minify
+    sourcemap: true,              // default — true | false | "inline" | "linked"
+  },
+});
+```
+
+Defaults are sensible for the typical "Node service" deployment. Knobs to actually reach for:
+
+- **`outDirectory`** — override when your deployment pipeline expects a different folder (e.g. `build/`, `.build/`).
+- **`outFile`** — override when bundling multiple Warlock apps into one image and they need distinct entry filenames.
+- **`minify: false`** — flip to debug a production-only bug. Larger bundle, readable stack traces.
+- **`sourcemap: "inline"`** — embed the source map in the bundle. Useful when your error reporter only captures the bundle and can't fetch a `.map` sidecar.
+- **`sourcemap: false`** — skip source maps entirely. Smaller artifact, but stack traces in production logs lose their file:line precision (and `warlock start` will not enable `--enable-source-maps` since there's nothing to map).
+
+### What it preloads
+
+Just `warlockConfig: true`. Build doesn't need the app booted — it reads `warlock.config.ts`, runs esbuild, writes the file. Fast.
+
+### Where the bundle lands
+
+```
+<cwd>/<outDirectory>/<outFile>
+└─ default: <cwd>/dist/app.js
+```
+
+`warlock start` uses the same `resolveBuildConfig()` helper to find the bundle, so the two commands stay in sync no matter how you override the config. If `build` and `start` disagree on where the bundle is, it's because `warlock.config.ts` is being read with different cwds — never the case in normal operation.
+
+## `warlock start` — run the production bundle
+
+Spawns `node <entryPath>` as a child process, forwarding signals (SIGINT / SIGTERM). `entryPath` is resolved from the same `build` config that produced the bundle.
+
+### Behavior
+
+```bash
+yarn warlock start                        # → spawns node --enable-source-maps dist/app.js
+yarn warlock start --inspect              # → spawns node --enable-source-maps --inspect dist/app.js
+yarn warlock start --max-old-space-size=4096  # → spawns node --enable-source-maps --max-old-space-size=4096 dist/app.js
+```
+
+Everything you pass after `start` is forwarded to the spawned Node process. Use this to attach a debugger (`--inspect`), tune memory (`--max-old-space-size`), or pass any other Node flag without editing the command.
+
+### Source maps
+
+If `build.sourcemap !== false`, `warlock start` adds `--enable-source-maps` automatically. You see real `.ts` paths and lines in stack traces. If you set `sourcemap: false` in build config, source maps stay off in `start` too — the two configs are tied.
+
+### What it preloads
+
+Just `warlockConfig: true` — same as `build`. The actual app bootstrap happens inside the spawned child process, when the bundle imports and runs framework startup.
+
+### Signal handling
+
+- `SIGINT` (Ctrl+C) — passes through to the child naturally; both processes get it. The parent waits for the child to exit, then exits with the child's code.
+- `SIGTERM` — explicitly forwarded to the child by the parent (Windows doesn't auto-propagate this one).
+
+Means `docker stop` / `kubectl delete pod` works as expected: SIGTERM reaches the bundle, your graceful-shutdown hooks fire, then the parent exits.
+
+## Picking which mode you're in
+
+`Application.environment` and `Application.runtimeStrategy` are separate axes:
+
+| Mode             | `environment`   | `runtimeStrategy` | How                                       |
+| ---------------- | --------------- | ----------------- | ----------------------------------------- |
+| `warlock dev`    | `development`*  | `development`     | preload force-sets `runtimeStrategy`      |
+| `warlock build`  | n/a (no app boots) | n/a            | only loads warlock.config.ts              |
+| `warlock start`  | `production`*   | `production`*     | usually set via `NODE_ENV` in the env     |
+
+`*` — `environment` follows `NODE_ENV`. The dev command doesn't force it, but the default in most projects is `development`. `start` doesn't force it either; deployments set `NODE_ENV=production` themselves.
+
+If you need conditional behavior, branch on `Application.environment` (the orthogonal "what world am I talking to?" axis), not `runtimeStrategy` (the "how is the framework itself running?" axis). See [`use-app-context/SKILL.md`](../use-app-context/SKILL.md).
+
+## Common patterns
+
+### Standard `package.json` scripts
+
+```json title="package.json"
+{
+  "scripts": {
+    "dev": "warlock dev",
+    "build": "warlock build",
+    "start": "warlock start"
+  }
+}
+```
+
+Now `yarn dev` / `yarn build` / `yarn start`. Standard Node hosting providers (Render, Fly, Railway, Heroku) recognize this layout.
+
+### Production Dockerfile
+
+```dockerfile
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+COPY . .
+RUN yarn warlock build
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/package.json ./
+COPY --from=build /app/warlock.config.ts ./
+ENV NODE_ENV=production
+CMD ["yarn", "warlock", "start"]
+```
+
+Two-stage build trims `devDependencies` out of the runtime image. Keep `warlock.config.ts` in the runtime stage — `start` reads it to resolve the bundle path.
+
+### Bundle into a different folder per environment
+
+```ts title="warlock.config.ts"
+import { defineConfig, env } from "@warlock.js/core";
+
+export default defineConfig({
+  build: {
+    outDirectory: env("BUILD_OUT", "dist"),
+    outFile: env("BUILD_FILE", "app.js"),
+  },
+});
+```
+
+CI sets `BUILD_OUT=build/<sha>` per pipeline. `warlock start` reads the same config and finds the bundle without any hardcoded paths.
+
+### Skip type-gen on machines without write access
+
+```bash
+yarn warlock dev --skip-typings
+```
+
+Or persist it:
+
+```ts title="warlock.config.ts"
+export default defineConfig({
+  devServer: {
+    generateTypings: false,
+  },
+});
+```
+
+Useful in a containerized dev environment where `.warlock/typings.d.ts` is read-only.
+
+### Memory-tune the production process
+
+```bash
+yarn warlock start --max-old-space-size=4096
+```
+
+Or via `NODE_OPTIONS` in the deployment env if you don't want to change the start invocation:
+
+```bash
+NODE_OPTIONS=--max-old-space-size=4096 yarn warlock start
+```
+
+## Gotchas
+
+- **`warlock dev` is persistent — `Ctrl+C` to stop.** The framework's `persistent: true` flag keeps the process alive after `action` returns. Same for `start`.
+- **`--fresh` only deletes the manifest, not the transpile cache.** If you're chasing a stale-compile bug, `rm -rf .warlock/` clears everything. The manifest restoring is what `--fresh` solves.
+- **`warlock build` does NOT run migrations.** Production bundles ship the migration files but don't apply them. Run `yarn warlock migrate` against the production DB separately.
+- **`warlock start` requires a built bundle.** Run `warlock build` first, or you'll spawn `node` against a non-existent file and crash immediately.
+- **`outDirectory` is the directory, `outFile` is the filename within it.** A common mistake is putting the full path in one and leaving the other default — you end up with `<full-path>/app.js` or `dist/<full-path>`. They concatenate.
+- **`sourcemap: false` cascades to `start`.** Stack traces lose `.ts` precision. Keep sourcemaps on unless artifact size is a hard constraint.
+- **`NODE_ENV` is not set by these commands.** The deployment env (your Dockerfile, CI, hosting provider) sets it. Forget it on a production server and `Application.isProduction` returns `false`, which flips cookie security, CORS, logging — silently. Always set `NODE_ENV=production` in production deployments.
+- **`prestart` runs once on dev boot, not on reload.** If you're seeding test data in `src/app/prestart.ts`, it fires on `warlock dev` startup only. HMR reloads don't re-run it.
+
+## See also
+
+- [`write-cli-command/SKILL.md`](../write-cli-command/SKILL.md) — author a custom CLI command + the rest of the built-in commands (migrate / seed / generate.* / add / storage.put / jwt.generate).
+- [`configure-app/SKILL.md`](../configure-app/SKILL.md) — `warlock.config.ts` shape and `defineConfig`.
+- [`use-app-context/SKILL.md`](../use-app-context/SKILL.md) — `Application.environment` vs `Application.runtimeStrategy`.
+- [`add-connector/SKILL.md`](../add-connector/SKILL.md) — Early vs Late connector phases (why HTTP/socket boot late in dev).

package/skills/send-mail/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: send-mail
+description: 'Send transactional email — `Mail` fluent builder, `sendMail()` direct call, React Email components. Test mode auto-captures into an in-memory mailbox; dev mode logs. Triggers: `Mail.to`, `sendMail`, `setMailMode`, `mailEvents`, `assertMailSent`, `getTestMailbox`, `wasMailSentTo`, `closeAllMailers`; "send a transactional email", "build a React Email template", "configure SMTP or SES", "assert an email was sent in tests"; typical import `import { Mail, sendMail } from "@warlock.js/core"`. Skip: per-config wiring — `@warlock.js/core/configure-app/SKILL.md`; layered service patterns — `@warlock.js/core/warlock-conventions/SKILL.md`; competing libs `nodemailer` direct, `@sendgrid/mail`, `resend`, `mailgun.js`.'
+---
+
+# Warlock — send a mail
+
+Two APIs over the same engine. The fluent `Mail` builder reads top-to-bottom in services; the functional `sendMail({...})` is best when the payload is already built. Both run through the same render → normalize → pool → transport pipeline, with a mode switch (`production` / `development` / `test`) deciding whether to actually send, log, or capture.
+
+## The shape
+
+```ts
+import { Mail } from "@warlock.js/core";
+
+await Mail.to("user@example.com")
+  .subject("Welcome!")
+  .text("Thanks for joining.")
+  .send();
+```
+
+Or:
+
+```ts
+import { sendMail } from "@warlock.js/core";
+
+await sendMail({
+  to: "user@example.com",
+  subject: "Welcome!",
+  text: "Thanks for joining.",
+});
+```
+
+`send()` / `sendMail()` resolves to a `MailResult` (`{ success, messageId, accepted, rejected, response, envelope }`).
+
+## Configuration
+
+`src/config/mail.ts` is the global default config — a single `MailConfigurations` object:
+
+```ts title="src/config/mail.ts"
+import type { MailConfigurations } from "@warlock.js/core";
+import { env } from "@warlock.js/core";
+
+const mailConfigurations: MailConfigurations = {
+  host: env("MAIL_HOST"),
+  username: env("MAIL_USERNAME"),
+  password: env("MAIL_PASSWORD"),
+  port: env("MAIL_PORT"),
+  secure: env("MAIL_SECURE"),
+  from: {
+    name: env("MAIL_FROM_NAME"),
+    address: env("MAIL_FROM_ADDRESS"),
+  },
+};
+
+export default mailConfigurations;
+```
+
+For named mailers (multi-provider apps), export a `MailersConfig` instead:
+
+```ts
+const config: MailersConfig = {
+  default: { host: "smtp.sendgrid.net", port: 587, username: "apikey", password: env("SENDGRID_KEY") },
+  mailers: {
+    marketing: { host: "smtp.mailchimp.com", port: 587, username: env("MC_USER"), password: env("MC_PASS") },
+    transactional: { host: "smtp.postmark.com", port: 587, username: env("PM_USER"), password: env("PM_PASS") },
+  },
+};
+```
+
+Then route a single mail through a specific mailer:
+
+```ts
+await Mail.mailer("marketing").to("user@example.com").subject("Promo").html(...).send();
+```
+
+For AWS SES, set `driver: "ses"`:
+
+```ts
+const config: MailConfigurations = {
+  driver: "ses",
+  accessKeyId: env("AWS_ACCESS_KEY_ID"),
+  secretAccessKey: env("AWS_SECRET_ACCESS_KEY"),
+  region: env("AWS_REGION"),
+  from: { name: "My App", address: "noreply@app.com" },
+};
+```
+
+Requires `@aws-sdk/client-sesv2` installed (`yarn add @aws-sdk/client-sesv2`).
+
+## Mail modes
+
+The mail pipeline switches behavior on a global mode:
+
+```ts
+import { setMailMode } from "@warlock.js/core";
+
+setMailMode("production");   // actually send (default)
+setMailMode("development");  // log subject + recipient, no send
+setMailMode("test");         // capture to test mailbox, no send
+```
+
+Production sends. Development logs and returns a fake-success `MailResult`. Test captures every call into an in-memory mailbox (cleared between tests) and returns success — handy for asserting "the welcome email got sent" without hitting SMTP.
+
+## The fluent builder — `Mail`
+
+`Mail` is built per call. `to(...)` / `config(...)` / `mailer(...)` start a new builder; each setter returns `this`. The final `.send()` validates and pipes through `sendMail()`.
+
+### Recipients + addressing
+
+```ts
+await Mail.to("a@example.com")
+  .to(["a@example.com", "b@example.com"])      // override
+  .cc("manager@example.com")
+  .bcc("audit@example.com")
+  .replyTo("support@example.com")
+  .from({ name: "Support", address: "support@example.com" })
+  .subject("Subject line")
+  .send();
+```
+
+`from` overrides the configured default. Pass a plain string or `{ name, address }`.
+
+### Content (pick one — `text`, `html`, or `component`)
+
+```ts
+// Plain text
+Mail.to("u@e.com").subject("Plain").text("Hi.").send();
+
+// HTML
+Mail.to("u@e.com").subject("Html").html("<p>Hi.</p>").send();
+
+// React component (renders via @react-email/render if installed, fallback to renderToStaticMarkup)
+Mail.to("u@e.com").subject("React").component(<WelcomeEmail name="Hasan" />).send();
+```
+
+`.send()` throws if all three are missing.
+
+### Attachments
+
+```ts
+await Mail.to("u@e.com")
+  .subject("Invoice")
+  .html("<p>See attached.</p>")
+  .attach(pdfBuffer, "invoice.pdf", "application/pdf")
+  .attachFile("/abs/path/to/terms.pdf", "terms.pdf")
+  .send();
+```
+
+`attach(content, filename, contentType?)` for buffers/strings; `attachFile(path, filename?, contentType?)` reads from disk at send time. `attachments([...])` accepts a pre-built array.
+
+### Other knobs
+
+| Method                                | Purpose                                       |
+| ------------------------------------- | --------------------------------------------- |
+| `.priority("high" \| "normal" \| "low")` | priority header                            |
+| `.headers({ "X-Foo": "bar" })`        | replace custom headers                        |
+| `.header("X-Foo", "bar")`             | add one header                                |
+| `.tags(["welcome"])` / `.tag("transactional")` | categorization tags                  |
+| `.correlationId("req-123")`           | tracking id (logged with sends)               |
+| `.config(MailConfigurations)`         | one-off override of the global config         |
+| `.mailer("marketing")`                | route via a named mailer from config          |
+
+### Per-mail event handlers
+
+The builder exposes four lifecycle handlers:
+
+```ts
+await Mail.to("u@e.com")
+  .subject("…")
+  .text("…")
+  .beforeSending((mail) => {
+    // mutate `mail` or return false to cancel
+  })
+  .onSent((mail, result, error) => {})    // always fires after attempt
+  .onSuccess((mail, result) => {})        // only on success
+  .onError((mail, error) => {})           // only on failure
+  .send();
+```
+
+Returning `false` from `beforeSending` cancels the send and resolves with `success: false`.
+
+## The functional API — `sendMail`
+
+Same options as the builder, passed as one object:
+
+```ts
+import { sendMail } from "@warlock.js/core";
+
+await sendMail({
+  to: "user@example.com",
+  cc: ["manager@example.com"],
+  subject: "Welcome",
+  component: <WelcomeEmail name="Hasan" />,
+  config: tenant.mailSettings,    // multi-tenant override
+  tags: ["welcome"],
+  onSuccess: (mail, result) => {},
+});
+```
+
+Use this when the payload is already an object — e.g. inside a queue worker iterating over a list. Both APIs share the same `MailOptions` shape.
+
+## React templates
+
+Pass a React element directly via `.component(<Template/>)` (builder) or `component:` (sendMail). The renderer:
+
+1. Tries `@react-email/render` (full React Email pipeline — install with `warlock add react-email`, which also drops a sample `emails/welcome-email.tsx` and patches `tsconfig.json` to include it).
+2. Falls back to `react-dom/server`'s `renderToStaticMarkup` wrapped in a minimal `<html>` shell.
+
+```tsx
+import { Html, Heading, Text } from "@react-email/components";
+
+export function WelcomeEmail({ name }: { name: string }) {
+  return (
+    <Html>
+      <Heading>Welcome, {name}</Heading>
+      <Text>Thanks for joining.</Text>
+    </Html>
+  );
+}
+```
+
+The renderer takes care of inlining styles and building the HTML page. You don't need to add a `<head>` or wrap in `<Mjml>`.
+
+## Global event hooks
+
+For app-wide observability (metrics, logging, audit), subscribe to global mail events:
+
+```ts
+import { mailEvents } from "@warlock.js/core";
+
+mailEvents.onSuccess((mail, result) => {
+  console.log("mail sent", result.messageId);
+});
+
+mailEvents.onError((mail, error) => {
+  console.error("mail failed", error.code, error.message);
+});
+
+mailEvents.onBeforeSending((mail) => {
+  // return false to cancel globally
+});
+```
+
+Global hooks fire for **every** mail. Per-mail handlers from the builder / `sendMail` fire only for that one send.
+
+For correlated tracking of a specific mail, generate an id and subscribe by id:
+
+```ts
+import { generateMailId, mailEvents, sendMail } from "@warlock.js/core";
+
+const mailId = generateMailId();
+
+mailEvents.onMailSuccess(mailId, (mail, result) => {
+  // fires only for this specific mail
+});
+
+await sendMail({ id: mailId, to: "u@e.com", subject: "…", text: "…" });
+```
+
+## Testing — the test mailbox
+
+In test mode, every send is captured instead of dispatched. Helpers live as named exports — there is no `testMailbox` object:
+
+```ts
+import {
+  setMailMode,
+  clearTestMailbox,
+  getTestMailbox,
+  getLastMail,
+  findMailsTo,
+  findMailsBySubject,
+  wasMailSentTo,
+  wasMailSentWithSubject,
+  getMailboxSize,
+  assertMailSent,
+  assertMailCount,
+} from "@warlock.js/core";
+
+beforeEach(() => {
+  setMailMode("test");
+  clearTestMailbox();
+});
+
+it("sends a welcome email on signup", async () => {
+  await signupUserService({ email: "u@e.com" });
+
+  expect(wasMailSentTo("u@e.com")).toBe(true);
+  expect(wasMailSentWithSubject("Welcome!")).toBe(true);
+
+  const mail = assertMailSent((m) => m.options.to === "u@e.com");
+  expect(mail.options.subject).toBe("Welcome!");
+});
+```
+
+Captured mail shape:
+
+```ts
+type CapturedMail = {
+  options: MailOptions;       // original payload
+  normalized: NormalizedMail; // post-normalization (arrays, resolved from)
+  timestamp: Date;
+  result?: MailResult;        // in test mode, always success
+  error?: MailError;
+};
+```
+
+`assertMailSent(predicate)` throws if no mail matches. `assertMailCount(n)` throws if the captured count isn't `n`.
+
+## Connection pooling
+
+Transports (one per unique config hash) are cached in an in-process pool. The first send creates a connection; subsequent sends reuse it. On shutdown:
+
+```ts
+import { closeAllMailers } from "@warlock.js/core";
+
+closeAllMailers();
+```
+
+`closeAllMailers()` is synchronous (returns `void`) — it closes every transport in the pool and clears it. You rarely call this manually — the framework closes the pool on shutdown.
+
+## Common patterns
+
+### Welcome email after signup
+
+```ts
+import { Mail } from "@warlock.js/core";
+import { WelcomeEmail } from "../emails/welcome.email";
+
+export async function sendWelcomeEmail(user: User) {
+  return Mail.to(user.email)
+    .subject(`Welcome, ${user.name}`)
+    .component(<WelcomeEmail name={user.name} />)
+    .tags(["welcome", "transactional"])
+    .send();
+}
+```
+
+### Per-tenant SMTP
+
+```ts
+await Mail.config(tenant.mailSettings)
+  .to(invitation.email)
+  .subject(`You've been invited to ${tenant.name}`)
+  .text(`Click here to accept: ${url}`)
+  .send();
+```
+
+### Cancel via beforeSending (e.g. user has opted out)
+
+```ts
+await Mail.to(user.email)
+  .subject("Newsletter")
+  .html(content)
+  .beforeSending(async (mail) => {
+    if (await hasOptedOut(user.id)) return false;
+  })
+  .send();
+```
+
+## Gotchas
+
+- **`.send()` validates** — `to`, `subject`, and at least one of `text`/`html`/`component` are required. Missing any throws synchronously.
+- **`@react-email/render` is optional.** Without it you get the basic fallback (inline styles, no MSO conditionals). Install it for production-quality HTML.
+- **`nodemailer` is loaded lazily** at import time. If you see `nodemailer is not installed` errors, run `warlock add mail` (or `yarn add nodemailer`).
+- **`secure: true` requires port 465.** For port 587 use `secure: false` and `tls: true` (STARTTLS).
+- **Test mode is process-global.** Set it in `beforeAll`/`beforeEach`; reset with `setMailMode("production")` (or rely on test runner isolation).
+- **Per-mail handlers don't replace global ones** — both fire. Avoid double-counting metrics.
+
+## See also
+
+- [`configure-app/SKILL.md`](../configure-app/SKILL.md) — `src/config/mail.ts` shape and `env()` patterns.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — where mail-sending services live.