@hogsend/cli 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,7 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "vitest": "^4.1.7",
-    "@hogsend/studio": "^0.10.0",
+    "@hogsend/studio": "^0.11.0",
     "@repo/typescript-config": "0.0.0"
   },
   "engines": {
@@ -40,7 +40,10 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.5.0",
-    "picocolors": "^1.1.1"
+    "better-auth": "^1.6.11",
+    "picocolors": "^1.1.1",
+    "@hogsend/db": "^0.11.0",
+    "@hogsend/engine": "^0.11.0"
   },
   "scripts": {
     "prebuild": "node scripts/bundle-studio.mjs",

package/skills/hogsend-authoring-emails/references/tracking-and-unsubscribe.md

@@ -17,12 +17,13 @@ emailService.send({ template, props, to, ... })   // or sendEmail({...}) in a jo
         (both skipped when skipPreferenceCheck is set)
   2. getTemplate(key, props, registry) → resolve element + subject + category
   3. insert email_sends row  → gives the send a stable emailSendId (status "queued")
-  4. renderToHtml(element), then prepareTrackedHtml(html, emailSendId, baseUrl, db):
+  4. renderToHtml(element) ALWAYS (HTML-only wire — no React crosses the provider),
+     then prepareTrackedHtml(html, emailSendId, baseUrl, db):
         • rewriteLinks()    — every <a href="https?://…"> → /v1/t/c/:linkId
         • injectOpenPixel() — <img src="/v1/t/o/:emailSendId"> before </body>
-        (only when baseUrl + prepareTrackedHtml are present; else send the raw react element)
-  5. provider.send(...)     — Resend gets the already-rewritten HTML
-  6. update email_sends → resendId + status "sent" (or "failed" on throw)
+        (rewrite/pixel only when baseUrl + prepareTrackedHtml are present; else send the plain rendered HTML)
+  5. provider.send(...)     — the provider gets the already-rendered HTML
+  6. update email_sends → messageId + status "sent" (or "failed" on throw)
 ```
 
 Tracking comes along regardless of which provider you supply, because steps 2–4

package/skills/hogsend-cli/SKILL.md

@@ -4,7 +4,7 @@ description: Use when an agent needs to inspect or operate a running Hogsend lif
 license: MIT
 metadata:
   author: withSeismic
-  version: "1.1.0"
+  version: "1.3.0"
 ---
 
 # Hogsend CLI
@@ -75,6 +75,8 @@ Most commands READ (admin API). A handful WRITE through the data plane — marke
 | `hogsend events send <name>` | **(write)** Push an event → `POST /v1/events`. `--email`/`--user-id` (≥1 required), `--prop`/`--props` (event props), `--contact-prop`/`--contact-props` (contact props), `--list`/`--unlist`, `--idempotency-key`, `--timestamp`. |
 | `hogsend emails send <template>` | **(write)** Send a transactional email → `POST /v1/emails`. `--to`/`--user-id` (≥1 required), `--prop`/`--props`, `--subject`, `--from`, `--reply-to`, `--category`, `--idempotency-key`, `--skip-preference-check` (needs full-admin). |
 | `hogsend webhooks list/get/create/update/delete/rotate-secret/test` | Manage **outbound** signed webhook endpoints (the event stream Hogsend emits to your URLs) → `/v1/admin/webhooks`. Needs the **admin key**, not the data key. `create --url <url>` + repeatable `--event <type>` or `--all-events`; the signing secret prints ONCE on `create` + `rotate-secret`. |
+| `hogsend studio` | Serve the bundled Studio admin SPA locally (optionally against a remote `--base-url`). |
+| `hogsend studio admin create/reset/list` | **Shell-gated** Studio admin create + recovery — DB-DIRECT, not HTTP. Gated by holding `DATABASE_URL` + `BETTER_AUTH_SECRET` (read from the ENVIRONMENT, not a `.env` file); writes passwords via Better Auth (scrypt, internal adapter), never raw SQL. Public sign-up is disabled, so this CLI (and the `STUDIO_ADMIN_EMAIL` boot bootstrap) are the ONLY ways to mint an admin. `create` bootstraps the first admin, `reset --email <e>` rotates a forgotten password (revokes sessions unless `--no-revoke`), `list` shows admins (no secrets). |
 | `hogsend skills list/add` | Manage these bundled agent skills. |
 | `hogsend upgrade` | Bump `@hogsend/*` deps to latest + refresh vendored skills. |
 | `hogsend setup` | Interactive LOCAL onboarding (docker, secret, migrate). |
@@ -106,3 +108,32 @@ Run `hogsend <command> --help` for per-command usage.
    make sure a data key resolves (`--data-key` > `HOGSEND_DATA_KEY` >
    `HOGSEND_API_KEY`) for the data-plane writes.
 4. Use `--limit`/`--offset` for pagination instead of dumping everything.
+5. `studio admin` is the ONE family that does NOT use the HTTP API — it talks to
+   the database directly and is gated by `DATABASE_URL` + `BETTER_AUTH_SECRET`
+   (no `--url`/`--admin-key`). It's admin create/recovery, not data ops — prefer
+   the masked password prompt over `--password` (which can leak into shell
+   history). Those two vars are read from the ENVIRONMENT only (NOT a `.env`
+   file), so run it with env loaded: locally `pnpm studio:admin` (the scaffold's
+   `node --env-file=.env … hogsend studio admin create` wrapper) or
+   `dotenvx run -- hogsend studio admin create`; on Railway `railway run hogsend
+   studio admin create` (or `railway ssh`).
+
+## First admin & closed sign-up
+
+Public sign-up is DISABLED at the auth layer (`disableSignUp`) — `POST
+/api/auth/sign-up/email` returns `400 EMAIL_PASSWORD_SIGN_UP_DISABLED` for
+everyone, so there is NO unauthenticated network path that creates a user. The
+first Studio admin is minted in one of two ways, both in-network:
+
+- **CLI:** `hogsend studio admin create` (or the scaffold's `pnpm studio:admin`),
+  gated by `DATABASE_URL` + `BETTER_AUTH_SECRET`. The only explicit path.
+- **Env bootstrap:** set `STUDIO_ADMIN_EMAIL` (+ optional `STUDIO_ADMIN_PASSWORD`)
+  in the deploy env. On boot, IF the user table is empty, the API mints that
+  admin (idempotent, race-safe). With no password set, a strong one is
+  auto-generated and printed ONCE to the server log — rotate it via the Studio
+  forgot/reset flow. Once an admin exists it never re-mints.
+
+If you (an agent) need an admin on a fresh instance and have shell access to the
+DB + secret, `studio admin create` is the move; otherwise tell the operator to
+set `STUDIO_ADMIN_EMAIL` and restart. There is no web "create admin" form to
+drive. Login + forgot/reset stay fully enabled over HTTP.

package/skills/hogsend-extending/SKILL.md

@@ -62,7 +62,10 @@ mirrored to a tool, durably? → a destination (3).
   provider. They come along regardless of which provider you supply.
 - **Defaults.** Pass nothing and you get Resend (built from `RESEND_API_KEY`) +
   PostHog (from `POSTHOG_API_KEY`). Inbound delivery webhooks land at the
-  engine-owned route `POST /v1/webhooks/resend`.
+  engine-owned route `POST /v1/webhooks/email/:providerId` (`:providerId` =
+  `meta.id`, so `…/email/resend` for the default; `POST /v1/webhooks/resend` is a
+  deprecated alias). The provider's `verifyWebhook` normalizes the payload into an
+  `EmailEvent` the engine maps to `email_sends` status + suppression.
 - ⚠️ The contract's `SendEmailOptions` imports from `@hogsend/core` (or
   `@hogsend/plugin-resend`), **not** `@hogsend/engine` — the engine's own
   `SendEmailOptions` is a different, higher-level send type.

package/skills/hogsend-extending/references/swap-a-provider.md

@@ -4,110 +4,328 @@ A capability provider is a **swappable implementation of an engine-owned
 contract**. The engine drives the capability and routes to whatever you supply.
 Today there are two: email (`EmailProvider`) and analytics (`PostHogService`).
 
+## Postmark is already shipped — install it, don't reimplement it
+
+As of **0.10.0** Postmark is a **shipped reference implementation**:
+`@hogsend/plugin-postmark` (`createPostmarkProvider`). You do **not** implement
+the contract to use it — you install the package and opt in. Resend stays the
+default; the engine type-checks identically with or without the package
+installed (it's an engine `optionalDependency`, lazily `import()`-ed only when
+`POSTMARK_SERVER_TOKEN` is set).
+
+```bash
+pnpm add @hogsend/plugin-postmark@latest
+```
+
+Implementing the `EmailProvider` contract yourself is the path for a provider
+that does **not** ship a plugin yet (e.g. SES). The contract below is what you
+implement in that case — and what the shipped Resend/Postmark providers already
+satisfy.
+
 ## The `EmailProvider` contract
 
 Defined in `@hogsend/core`, re-exported canonically from `@hogsend/engine`. It is
 a **dumb wire** — delivery + webhook parse/verify only. No tracking, DB,
-preference, or render logic lives here.
+preference, or render logic lives here. React **never** crosses this boundary:
+the engine always renders React → HTML (via `@hogsend/email` `renderToHtml`)
+before calling `send`, so the wire is **HTML-only** — there is no `react` field.
 
 ```ts
 import type { EmailProvider } from "@hogsend/engine";
 
 interface EmailProvider {
-  send(options: SendEmailOptions): Promise<SendResult>;            // → { id }
+  readonly meta?: EmailProviderMeta;                 // { id, name, description? }
+  readonly capabilities?: EmailProviderCapabilities; // tracking/scheduled/signed flags
+
+  // Deliver one / a batch. SendResult is { id } (the provider message id).
+  send(options: SendEmailOptions): Promise<SendResult>;
   sendBatch(emails: BatchEmailItem[]): Promise<{ results: SendResult[] }>;
-  // Verify a provider webhook signature and return the parsed event.
-  // Throws if the signature is missing/invalid.
-  verifyWebhook(opts: { payload: string; headers: Record<string, string> }): WebhookEvent;
+
+  // Verify the provider's webhook (owns its OWN secrets, constructed-in) and
+  // return a normalized EmailEvent. Throws on a bad signature. Throws
+  // WebhookHandshakeSignal for non-status handshakes (the route 200s those).
+  // MAY be async (SES must GET the SNS SubscribeURL).
+  verifyWebhook(opts: {
+    payload: string;
+    headers: Record<string, string>;
+  }): Promise<EmailEvent> | EmailEvent;
+
   // Parse an unsigned payload (trusted contexts/tests).
-  parseWebhook(payload: string): WebhookEvent;
+  parseWebhook(payload: string): EmailEvent;
 }
 ```
 
-`SendEmailOptions`, `BatchEmailItem`, `SendResult`, and `WebhookEvent` are the
-contract's supporting types. **Import the contract types from `@hogsend/engine`**,
-**except `SendEmailOptions`**, which collides with the engine's higher-level send
-type — import that one from `@hogsend/core`:
+`meta` and `capabilities`:
+
+- **`meta`** (`{ id, name, description? }`) — `meta.id` is the registry key **and**
+  the `:providerId` that `POST /v1/webhooks/email/:providerId` dispatches on. It
+  is OPTIONAL for back-compat (the registry falls back to `"resend"` when
+  absent) but becomes required in a later breaking phase — **always supply it**.
+- **`capabilities`** (`{ nativeTracking?, scheduledSend?, signedWebhooks? }`) —
+  optional; absent is treated conservatively. `nativeTracking: true` (Resend)
+  means the provider's own open/click tracking is an account-level toggle the
+  engine can't reach → the engine logs a boot WARN telling you to disable it
+  (first-party tracking is the single source of truth). `nativeTracking: false`
+  (Postmark, SES) means the provider disables its own tracking per-send and the
+  engine **trusts** it — no WARN. `scheduledSend` gates
+  `SendEmailOptions.scheduledAt`; `signedWebhooks: false` means the provider
+  fails-closed on its own (Postmark basic-auth).
+
+The webhook wire normalized into `EmailEvent`:
+
+```ts
+type EmailEventType =
+  | "email.sent" | "email.delivered" | "email.bounced" | "email.complained"
+  | "email.delivery_delayed" | "email.opened" | "email.clicked";
+
+type BounceClass = "permanent" | "transient" | "complaint" | "unknown";
+
+interface EmailEvent {
+  type: EmailEventType;
+  messageId: string;        // Resend email_id | Postmark MessageID | SES mail.messageId
+  recipients: string[];     // ALL recipients
+  occurredAt: string;       // ISO 8601
+  bounce?: { class: BounceClass; code: string; reason?: string }; // on bounced/complained
+  click?: { url: string; at?: string; ip?: string; ua?: string }; // on clicked (native echo only)
+  raw: unknown;             // untouched provider payload (escape hatch)
+}
+```
+
+`bounce.class` drives suppression: `permanent` auto-suppresses (the engine
+increments `bounceCount`), `complaint` suppresses immediately, `transient` is
+recorded but **never** suppresses, `unknown` is the conservative default.
+
+The send wire is HTML-only:
+
+```ts
+interface SendEmailOptions {
+  from: string;
+  to: string | string[];
+  subject: string;
+  html: string;             // REQUIRED — the engine renders React → HTML before the wire
+  text?: string;            // optional plain-text alternative
+  replyTo?: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  tags?: Array<{ name: string; value: string }>; // neutral; each provider maps natively
+  headers?: Record<string, string>;
+  scheduledAt?: string;     // honored only when capabilities.scheduledSend; else logged + ignored
+}
+
+type BatchEmailItem = Omit<SendEmailOptions, "scheduledAt">;
+interface SendResult { id: string }
+```
+
+> **Migrating from a pre-0.10.0 provider:** the old `WebhookEvent` union and the
+> nested `event.data.email_id` shape are **gone from the wire** — `verifyWebhook`
+> / `parseWebhook` now return the provider-neutral `EmailEvent`. There is **no
+> `react` field** on `SendEmailOptions`. The deprecated `WebhookEvent` union
+> survives **only** as a frozen `event.raw` cast target (alias
+> `LegacyResendWebhookEvent`) for one minor — a handler still on the old shape
+> casts `event.raw as LegacyResendWebhookEvent`, but the supported path is
+> `event.messageId` / `event.bounce` / `event.type`.
+
+All of these types — plus the `defineEmailProvider` factory and the
+`normalizeRecipients` / `joinRecipients` helpers — are exported from
+`@hogsend/core` (re-exported canonically from `@hogsend/engine`):
 
 ```ts
-import type { EmailProvider, SendResult, WebhookEvent } from "@hogsend/engine";
-import type { SendEmailOptions } from "@hogsend/core";
+import {
+  defineEmailProvider,
+  joinRecipients,
+  type BatchEmailItem,
+  type BounceClass,
+  type EmailEvent,
+  type EmailEventType,
+  type EmailProvider,
+  type SendEmailOptions,
+  type SendResult,
+  WebhookHandshakeSignal,
+} from "@hogsend/core";
 ```
 
-## A provider skeleton
+## A provider skeleton (implementing the contract yourself, e.g. SES)
 
-The reference implementation to copy is `createResendProvider`
-(`packages/plugin-resend/src/provider.ts`). A custom one mirrors it:
+The shipped reference implementations to copy are `createResendProvider`
+(`packages/plugin-resend/src/provider.ts`) and `createPostmarkProvider`
+(`packages/plugin-postmark/src/index.ts`). Use `defineEmailProvider` so a typo
+in `meta` or a missing method is caught at definition time. A custom one mirrors
+them:
 
 ```ts
 // src/lib/my-email-provider.ts — your content
-import type { SendEmailOptions } from "@hogsend/core";
-import type { EmailProvider, SendResult, WebhookEvent } from "@hogsend/engine";
+import {
+  defineEmailProvider,
+  joinRecipients,
+  type EmailEvent,
+  type EmailProvider,
+  type SendEmailOptions,
+  type SendResult,
+  WebhookHandshakeSignal,
+} from "@hogsend/core";
+
+export function createMyEmailProvider(config: {
+  apiKey: string;
+  webhookSecret?: string;
+}): EmailProvider {
+  return defineEmailProvider({
+    meta: { id: "myvendor", name: "MyVendor" }, // meta.id = registry key + :providerId
+    capabilities: {
+      nativeTracking: false, // disable your own tracking per-send → engine trusts it
+      scheduledSend: false,  // honor SendEmailOptions.scheduledAt? else it's dropped + WARN
+      signedWebhooks: true,  // false ⇒ you must fail-closed yourself
+    },
 
-export function createMyEmailProvider(config: { apiKey: string; webhookSecret?: string }): EmailProvider {
-  return {
     async send(options: SendEmailOptions): Promise<SendResult> {
-      // Call your vendor's SDK. The engine hands you HTML already rewritten for
-      // link/open tracking (options.html) on the tracked path; render
-      // options.react yourself (renderToHtml/renderToPlainText from
-      // @hogsend/email) only if your vendor can't take React.
-      const id = await myVendor.send({ from: options.from, to: options.to, subject: options.subject, html: options.html });
+      // Call your vendor's SDK. The engine hands you HTML already rendered +
+      // rewritten for link/open tracking (options.html) — no React on the wire.
+      const id = await myVendor.send({
+        from: options.from,
+        to: options.to,
+        subject: options.subject,
+        html: options.html,
+      });
       return { id };
     },
+
     async sendBatch(emails) {
-      const results = await Promise.all(emails.map((e) => this.send(e as never)));
+      const results = await Promise.all(emails.map((e) => this.send(e)));
       return { results };
     },
-    verifyWebhook({ payload, headers }): WebhookEvent {
-      if (!config.webhookSecret) throw new Error("webhookSecret required to verify webhooks");
-      // Verify with your vendor's scheme, then NORMALIZE into the engine's
-      // WebhookEvent shape ({ type: "email.delivered" | "email.bounced" | ... }).
-      return normalizeMyVendorEvent(verify(payload, headers, config.webhookSecret));
+
+    verifyWebhook({ payload, headers }): EmailEvent {
+      if (!config.webhookSecret) {
+        throw new Error("webhookSecret required to verify webhooks");
+      }
+      const raw = verify(payload, headers, config.webhookSecret);
+      // A non-delivery-status handshake (subscription confirmations, etc.)?
+      // Throw WebhookHandshakeSignal — the engine route 200s it without sniffing
+      // the body. Body-shape knowledge stays INSIDE the provider.
+      if (isHandshake(raw)) throw new WebhookHandshakeSignal("confirm-subscription");
+      // Otherwise NORMALIZE into the provider-neutral EmailEvent
+      // ({ type: "email.delivered" | "email.bounced" | ..., messageId, recipients, ... }).
+      return normalizeMyVendorEvent(raw);
     },
-    parseWebhook(payload): WebhookEvent {
+
+    parseWebhook(payload): EmailEvent {
       return normalizeMyVendorEvent(JSON.parse(payload));
     },
-  };
+  });
 }
 ```
 
-## Wire it
+## Wire it / opt in
+
+### Opt into Postmark (env, no code)
+
+The simplest path — the engine builds the Postmark provider from env and
+activates it. Setting `POSTMARK_SERVER_TOKEN` builds the preset but does **not**
+change the active provider; you must also set `EMAIL_PROVIDER=postmark`.
+
+```bash
+EMAIL_PROVIDER=postmark
+POSTMARK_SERVER_TOKEN=pm-server-xxxxxxxx   # required — also gates the lazy import of the plugin
+POSTMARK_MESSAGE_STREAM=outbound           # optional
+POSTMARK_WEBHOOK_USER=hook                 # Postmark has no HMAC — Basic-auth in the webhook URL
+POSTMARK_WEBHOOK_PASS=super-secret         # BOTH required together to enable verify
+EMAIL_FROM=noreply@yourdomain.com          # neutral from; else falls back to RESEND_FROM_EMAIL
+# RESEND_API_KEY is now OPTIONAL — omit it entirely for a Postmark-only deploy
+```
+
+If `EMAIL_PROVIDER` names a provider that isn't registered, the container throws
+at boot with the list of registered ids. If `POSTMARK_SERVER_TOKEN` is set but
+`@hogsend/plugin-postmark` isn't installed, the preset is skipped — and if
+Postmark was the active provider, boot fails with a "not registered" error
+directing you to install it.
+
+### Opt into a provider (code)
 
 ```ts
 // src/index.ts — your content
 import { createHogsendClient } from "@hogsend/engine";
+import { createPostmarkProvider } from "@hogsend/plugin-postmark";
 import { templates } from "./emails/registry.js";
-import { createMyEmailProvider } from "./lib/my-email-provider.js";
 
 const client = createHogsendClient({
   journeys,
   email: {
     templates,                                            // REQUIRED, nested under email
-    provider: createMyEmailProvider({ apiKey: process.env.MY_API_KEY! }),
+    provider: createPostmarkProvider({                    // merged LAST → wins on id collision
+      serverToken: process.env.POSTMARK_SERVER_TOKEN!,
+      webhookBasicAuth: { user: "hook", pass: process.env.POSTMARK_WEBHOOK_PASS! },
+    }),
+    defaultProvider: "postmark",                          // the active provider the mailer sends through
   },
   // analytics: createMyAnalytics(...),                   // top-level (engine uses it)
 });
 ```
 
-Pass nothing under `email.provider` and the engine builds the **default Resend
-provider** from `RESEND_API_KEY` / `RESEND_WEBHOOK_SECRET`.
+For a provider you implemented yourself, swap in `createMyEmailProvider({ ... })`
+the same way.
+
+### Register many providers
+
+To register **more than one** provider (so `POST /v1/webhooks/email/:providerId`
+can verify each) use `providers: [...]` and pick the active one with
+`defaultProvider`:
+
+```ts
+import { createResendProvider } from "@hogsend/plugin-resend";
+import { createPostmarkProvider } from "@hogsend/plugin-postmark";
+
+const client = createHogsendClient({
+  email: {
+    templates,
+    providers: [
+      createResendProvider({
+        apiKey: process.env.RESEND_API_KEY!,
+        webhookSecret: process.env.RESEND_WEBHOOK_SECRET,
+      }),
+      createPostmarkProvider({
+        serverToken: process.env.POSTMARK_SERVER_TOKEN!,
+        webhookBasicAuth: { user: "hook", pass: process.env.POSTMARK_WEBHOOK_PASS! },
+      }),
+    ],
+    defaultProvider: "postmark", // resolution: defaultProvider ?? EMAIL_PROVIDER ?? "resend"
+  },
+});
+```
+
+Registry merge order is last-writer-wins: env presets **first** →
+`email.providers` → `email.provider` **last**. The container does a registry
+lookup for the resolved active id and **throws at boot** if it isn't registered
+(`email provider "<id>" is not registered (registered: <ids>)`) — it never
+silently falls back for a non-`resend` id. If the active provider declares
+`capabilities.nativeTracking === true` (Resend), the engine logs a boot WARN to
+disable native tracking; Postmark (`nativeTracking: false`) gets no WARN.
+
+Pass nothing under `email` and the engine builds the **default Resend provider**
+from `RESEND_API_KEY` / `RESEND_WEBHOOK_SECRET` (active id `"resend"`).
 
 ## What comes along for free
 
 Everything except the wire. The engine's `createTrackedMailer` runs, in order:
-check preferences/suppression → frequency cap → resolve + render the template →
-write the `email_sends` row (status `queued`) → rewrite links + inject the open
-pixel → **then** `provider.send(...)` → update status. So a swapped provider
-keeps **all** of tracking, rendering, preferences, and the `email_sends`
-pipeline.
+check preferences/suppression → frequency cap → resolve + render the template
+(React → HTML) → write the `email_sends` row (column `message_id`) → rewrite
+links + inject the open pixel → **then** `provider.send(...)` → update status. So
+a swapped provider keeps **all** of tracking, rendering, preferences, and the
+`email_sends` pipeline.
+
+Reading the result of a send: use `result.messageId` (`TrackedSendResult.messageId`,
+the provider-neutral id — Resend `email_id` / Postmark `MessageID`). The old
+`result.resendId` still works but is `@deprecated` — it mirrors `messageId` for
+one minor, then is removed. The persisted DB column is `message_id` (there is no
+`resend_id` column).
 
 ## Inbound webhooks
 
-The engine owns one inbound email-webhook route: `POST /v1/webhooks/resend`. It
-reads the raw body + headers and calls your provider's `verifyWebhook`, then maps
-the normalized `WebhookEvent` to `email_sends` status updates and
-bounce/complaint → suppression. Your provider only has to verify + normalize; the
-DB effects are engine-owned.
+The engine owns the inbound email-webhook route `POST /v1/webhooks/email/:providerId`
+(`:providerId` = your `meta.id`; `POST /v1/webhooks/resend` is a deprecated static
+alias for `…/email/resend`). It reads the raw body + headers, resolves the
+matching provider from the registry, and calls that provider's `verifyWebhook`,
+then maps the normalized `EmailEvent` to `email_sends` status updates (keyed by
+`event.messageId`) and bounce/complaint → suppression. Your provider only has to
+verify + normalize; the DB effects are engine-owned.
 
 ## Analytics (`PostHogService`)
 
@@ -133,7 +351,11 @@ provider must still satisfy:
 
 ## Don't over-reach
 
-You are implementing a contract, not building a framework. There is no provider
-registry, no marketplace, and no `@hogsend/provider-*` packages — to support a
-new vendor you implement `EmailProvider` (or `PostHogService`) and pass it in.
-That's the whole story.
+You are implementing a contract, not building a framework. Two shipped reference
+implementations exist — `@hogsend/plugin-resend` (the default) and
+`@hogsend/plugin-postmark` — so before reimplementing, check whether a plugin
+already covers your vendor and just install + opt in. For a vendor with **no**
+plugin yet (e.g. SES) you implement `EmailProvider` (or `PostHogService`) with
+`defineEmailProvider` and register it — there's an `EmailProviderRegistry` keyed
+by `meta.id`, but no marketplace and no provider discovery. That's the whole
+story.