@damiangilgonzalez/harness 1.3.7

package/skills/elixir/references/otp-patterns.md

@@ -0,0 +1,96 @@
+# OTP patterns
+
+Depth offloaded from SKILL.md. Pick the lightest behaviour that fits.
+
+## Choosing an OTP behaviour
+
+| Need | Reach for | Notes |
+|---|---|---|
+| State behind a custom API, callbacks | `GenServer` | The workhorse; full control over messages |
+| Trivial state, get/update by function | `Agent` | A thin GenServer wrapper; no custom protocol |
+| One-off concurrent computation | `Task` | `Task.async/await`, or `Task.async_stream` for bounded fan-out |
+| Supervised fire-and-forget jobs | `Task.Supervisor` | Crashes isolated, no result needed |
+| Many dynamic, identical children | `DynamicSupervisor` + `Registry` | Start/stop children at runtime, look them up by key |
+| Explicit state machine with phases | `:gen_statem` (Erlang) | When transitions/events dominate; usable directly from Elixir |
+| Shared read-heavy data | `:ets` | Concurrent lock-free reads; one owner process holds the table |
+
+## DynamicSupervisor + Registry recipe
+
+Use this when you want one process per logical entity (per user, per connection, per token bucket) started on demand and addressable by a key.
+
+```elixir
+# In application.ex children, before the workers:
+#   {Registry, keys: :unique, name: MyApp.Registry},
+#   {DynamicSupervisor, name: MyApp.WorkerSup, strategy: :one_for_one}
+
+defmodule MyApp.Worker do
+  use GenServer
+
+  def start_link(id) do
+    GenServer.start_link(__MODULE__, id, name: via(id))
+  end
+
+  defp via(id), do: {:via, Registry, {MyApp.Registry, id}}
+
+  # Start (or return existing) a worker for `id`.
+  def ensure_started(id) do
+    case DynamicSupervisor.start_child(MyApp.WorkerSup, {__MODULE__, id}) do
+      {:ok, pid} -> {:ok, pid}
+      {:error, {:already_started, pid}} -> {:ok, pid}
+      other -> other
+    end
+  end
+
+  @impl true
+  def init(id), do: {:ok, %{id: id}}
+end
+```
+
+`{:via, Registry, {Registry, key}}` lets you address a process by `key` without ever touching its pid. The Registry entry is removed automatically when the process dies — no stale-pid bookkeeping.
+
+## Timeouts, backpressure, and mailbox growth
+
+- `GenServer.call/3` defaults to a **5000 ms** timeout. If the server is slow, the *caller* gets an `:timeout` exit. Raise the timeout only when the operation is legitimately long; otherwise the slowness is the bug.
+- A **growing mailbox** means messages arrive faster than `handle_*` drains them. Causes: an unbounded `cast` producer, an expensive `handle_info`, or a process doing too much. Fixes:
+  - Switch hot producers from `cast` to `call` so the caller blocks (natural backpressure).
+  - Move heavy work out of the GenServer (into a `Task` it supervises).
+  - Shard the work across many processes instead of one.
+  - For true streaming/backpressure, use `GenStage`/`Flow` (external deps).
+- `handle_continue/2` runs immediately after `init` (or after the returning callback) before the next message — use it for post-init warm-up so `start_link` returns fast.
+
+## Task and Task.Supervisor
+
+```elixir
+# Bounded concurrent fan-out — never spawns more than max_concurrency at once.
+ids
+|> Task.async_stream(&fetch/1, max_concurrency: 10, timeout: 30_000)
+|> Enum.map(fn {:ok, result} -> result end)
+
+# Supervised fire-and-forget (add {Task.Supervisor, name: MyApp.Tasks} to children):
+Task.Supervisor.start_child(MyApp.Tasks, fn -> do_async_thing() end)
+```
+
+Prefer `Task.async_stream` over manually spawning N tasks — it bounds concurrency and applies a per-item timeout.
+
+## Agent (when GenServer is overkill)
+
+```elixir
+{:ok, agent} = Agent.start_link(fn -> %{} end)
+Agent.update(agent, &Map.put(&1, :k, 1))
+Agent.get(agent, &Map.get(&1, :k))
+```
+
+Note: every `Agent.get`/`update` runs its function in the agent process — keep them tiny, or you recreate the god-process bottleneck.
+
+## ETS for shared read state
+
+```elixir
+:ets.new(:cache, [:named_table, :set, :public, read_concurrency: true])
+:ets.insert(:cache, {:key, value})
+case :ets.lookup(:cache, :key) do
+  [{:key, v}] -> {:ok, v}
+  [] -> :error
+end
+```
+
+ETS gives concurrent lock-free reads, so a read-heavy cache does not bottleneck on a single GenServer mailbox. Have one process own and create the table (so the table dies with it, or use `:heir` to transfer ownership on crash).

package/skills/elixir/scripts/verify.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# verify.sh — read-only checks for an Elixir/OTP target.
+#
+# Checks (only when the toolchain and artifacts are present):
+#   - `mix format --check-formatted` (style)
+#   - `mix compile --warnings-as-errors` (warning-free compile) at a mix project root
+#
+# Never blocks a toolchain-free or empty target: exits 0 with a skip note when
+# Elixir/mix is absent or there is nothing to check. No network, no writes.
+#
+# Usage: bash scripts/verify.sh [TARGET_DIR]   (default: current directory)
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify: target '$TARGET' is not a directory — nothing to check. SKIP."
+  exit 0
+fi
+
+# Toolchain gate: no mix on PATH -> skip cleanly (do not fail CI without a toolchain).
+if ! command -v mix >/dev/null 2>&1; then
+  echo "verify: 'mix' not found on PATH — Elixir toolchain not installed. SKIP."
+  exit 0
+fi
+
+# Find a mix project root (a directory containing mix.exs), shallowest first.
+mix_root=""
+if [ -f "$TARGET/mix.exs" ]; then
+  mix_root="$TARGET"
+else
+  mix_root="$(find "$TARGET" -maxdepth 4 -name mix.exs -not -path '*/deps/*' -not -path '*/_build/*' 2>/dev/null \
+    | awk '{ print gsub(/\//,"/"), $0 }' | sort -n | head -n1 | cut -d' ' -f2- || true)"
+  [ -n "$mix_root" ] && mix_root="$(dirname "$mix_root")"
+fi
+
+# Count loose Elixir sources in the target (excludes deps/_build).
+ex_count="$(find "$TARGET" \( -name '*.ex' -o -name '*.exs' \) \
+  -not -path '*/deps/*' -not -path '*/_build/*' 2>/dev/null | wc -l | tr -d ' ')"
+
+if [ -z "$mix_root" ] && [ "$ex_count" = "0" ]; then
+  echo "verify: no mix.exs and no .ex/.exs files under '$TARGET' — nothing to check. SKIP."
+  exit 0
+fi
+
+status=0
+
+if [ -n "$mix_root" ]; then
+  echo "verify: mix project root -> $mix_root"
+
+  echo "verify: mix format --check-formatted"
+  if ! ( cd "$mix_root" && mix format --check-formatted ); then
+    echo "verify: FAIL — files are not formatted (run: mix format)"
+    status=1
+  fi
+
+  echo "verify: mix compile --warnings-as-errors"
+  if ! ( cd "$mix_root" && mix compile --warnings-as-errors ); then
+    echo "verify: FAIL — compile produced warnings or errors"
+    status=1
+  fi
+else
+  # Loose .ex/.exs without a mix project: format check only (compile needs a project).
+  echo "verify: no mix.exs found; checking formatting of $ex_count loose Elixir file(s)"
+  echo "verify: mix format --check-formatted"
+  if ! ( cd "$TARGET" && mix format --check-formatted ); then
+    echo "verify: FAIL — files are not formatted (run: mix format)"
+    status=1
+  fi
+fi
+
+if [ "$status" -eq 0 ]; then
+  echo "verify: OK"
+fi
+exit "$status"

package/skills/email-connector/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: email-connector
+description: "Use when wiring server code to send transactional or bulk email via Resend, SendGrid, or Postmark: a provider-agnostic sendEmail() seam, idempotent retries, 100-cap batches with partial failures, transactional-vs-broadcast streams, bounce webhooks feeding a suppression list. NOT SPF/DKIM/DMARC inbox reputation (that is `email-deliverability`)."
+tags: [email, transactional-email, resend, sendgrid, postmark, webhooks, idempotency]
+recommends: [email-deliverability, newsletter, webhooks, secure-coding, api-connector-builder, automation-flows]
+origin: risco
+---
+
+# email-connector — put transactional & bulk email on the wire
+
+You wire the *send*. A welcome mail, a password reset, a receipt, a 4,000-row
+digest — your job is the server code that hands it to a provider, makes it safe
+to retry, and keeps the suppression list honest. You do **not** own the inbox
+(SPF/DKIM/DMARC/reputation is `../email-deliverability/SKILL.md`) and you do
+**not** own the words (subject lines and growth are `../newsletter/SKILL.md`,
+launch copy is `../marketing/SKILL.md`). Generic typed clients for *any* REST API
+are `../api-connector-builder/SKILL.md`; deciding *when* a multi-step sequence
+fires is `../automation-flows/SKILL.md`.
+
+Stack as of June 2026: `resend` 6.12.4, `@sendgrid/mail` 8.1.6, Postmark via its
+HTTP API, React Email 5.0 (React 19.2 / Next.js 16, Tailwind 4), Node 20+ / TS.
+
+`scripts/verify.sh` is read-only and greps a target for the four invariants this
+skill exists to hold: env-sourced key, idempotency, a single `sendEmail()` seam,
+and a webhook signature checked on the raw body.
+
+## Step 1 — pick a provider
+
+| Provider | Best default fit | Native idempotency | Template model | Batch cap | Pick when |
+|----------|------------------|--------------------|----------------|-----------|-----------|
+| **Resend** | Greenfield, React/Next shops | Yes — `{ idempotencyKey }`, 24h, ≤256 chars | React Email JSX via `react:` | 100/call | You want JSX templates and the least ceremony |
+| **SendGrid (Twilio)** | High volume, marketing+txn mix | No — dedupe yourself | `d-` dynamic templates + `dynamicTemplateData` | per-send `personalizations` | You need 10k req/s scale or already on Twilio |
+| **Postmark** | Pure transactional, deliverability-first | No — self-dedupe via your key + webhooks | Postmark server templates | per-stream | Receipts/resets must never queue behind marketing |
+
+Idempotency support changes your strategy, not just your config — see Step 4.
+Full per-provider matrix (auth header, SDK + version, single/batch signatures,
+idempotency model, stream/subdomain model, dynamic-template syntax, webhook event
+names, rate limits, when to pick each) plus a suppression-webhook handler skeleton
+per provider is in `references/providers.md`.
+
+## Step 2 — the `sendEmail()` seam
+
+One provider-agnostic function. The rest of the app calls `sendEmail(...)` and
+never imports a provider SDK. *Why:* swapping SendGrid→Postmark is then one file,
+not a grep across every call site. That one file reads the key from
+`process.env` — never a `re_…` / `SG.…` / server-token literal, because a
+committed key is a send-as-you credential and burns your reputation with it.
+
+```ts
+// lib/email/index.ts — the only place a provider SDK is imported
+export type SendArgs = {
+  to: string | string[];
+  subject: string;
+  react?: React.ReactElement; // template component
+  html?: string;
+  text?: string;
+  idempotencyKey: string;     // required for transactional sends
+  stream?: 'transactional' | 'broadcast';
+};
+export async function sendEmail(args: SendArgs): Promise<{ id: string }> { /* provider impl */ }
+```
+
+```ts
+// lib/email/resend.ts
+import { Resend } from 'resend';
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+export async function sendEmail(a: SendArgs) {
+  const { data, error } = await resend.emails.send(
+    { from: 'YourApp <noreply@notify.yourdomain.com>', to: a.to, subject: a.subject, react: a.react, html: a.html, text: a.text },
+    { idempotencyKey: a.idempotencyKey }, // 2nd arg, retained 24h, ≤256 chars
+  );
+  if (error) throw new Error(error.message);
+  return { id: data!.id };
+}
+```
+
+```ts
+// lib/email/sendgrid.ts
+import sgMail from '@sendgrid/mail';
+sgMail.setApiKey(process.env.SENDGRID_API_KEY!);
+
+export async function sendEmail(a: SendArgs) {
+  const [res] = await sgMail.send({
+    from: 'noreply@notify.yourdomain.com',
+    to: a.to, subject: a.subject, html: a.html, text: a.text,
+    // SendGrid has no idempotency key — guard with your own dedupe (Step 4)
+  });
+  return { id: res.headers['x-message-id'] };
+}
+```
+
+```ts
+// lib/email/postmark.ts — raw HTTP, X-Postmark-Server-Token header
+export async function sendEmail(a: SendArgs) {
+  // Postmark has no idempotency key: self-dedupe BEFORE calling (Step 4)
+  const r = await fetch('https://api.postmarkapp.com/email', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      'X-Postmark-Server-Token': process.env.POSTMARK_SERVER_TOKEN!,
+    },
+    body: JSON.stringify({
+      From: 'noreply@notify.yourdomain.com',
+      To: Array.isArray(a.to) ? a.to.join(',') : a.to,
+      Subject: a.subject, HtmlBody: a.html, TextBody: a.text,
+      MessageStream: a.stream === 'broadcast' ? 'broadcast' : 'outbound',
+    }),
+  });
+  if (!r.ok) throw new Error(`Postmark ${r.status}`);
+  return { id: (await r.json()).MessageID };
+}
+```
+
+Bad → Good:
+
+```ts
+// Bad — provider SDK called directly in a route handler, key inline
+import { Resend } from 'resend';
+await new Resend('re_live_123abc').emails.send({ to, subject, html });
+```
+```ts
+// Good — call the seam; key is in env, swap is one file
+import { sendEmail } from '@/lib/email';
+await sendEmail({ to, subject, react: <Welcome name={n} />, idempotencyKey });
+```
+
+## Step 3 — templates
+
+Templates are typed components, not string concat. *Why:* JSX escapes
+interpolated values; hand-built HTML invites injection and broken markup.
+
+React Email 5.0 renamed `renderAsync` → `render`. The Resend SDK lazily imports
+`@react-email/render` when you pass `react:`, so you usually pass the component
+directly and skip manual rendering.
+
+```tsx
+// emails/welcome.tsx
+import { Html, Button, Text } from '@react-email/components';
+export function Welcome({ name, url }: { name: string; url: string }) {
+  return (
+    <Html>
+      <Text>Welcome, {name}.</Text>
+      <Button href={url}>Confirm your email</Button>
+    </Html>
+  );
+}
+```
+
+```ts
+// SendGrid: dynamic template referenced by a d- id, data passed separately
+await sgMail.send({
+  to, from: 'noreply@notify.yourdomain.com',
+  templateId: 'd-abc123...',                  // dynamic template id starts with d-
+  dynamicTemplateData: { name, confirm_url },  // values, not pre-rendered HTML
+});
+```
+
+```ts
+// Bad — string concat, unescaped user input straight into HTML
+const html = '<h1>Hi ' + req.body.name + '</h1>'; // XSS + broken layout risk
+```
+
+## Step 4 — idempotency & retries
+
+Every transactional send carries a key, because queues retry, serverless
+functions re-fire, and users double-click — without a stable key one password
+reset becomes three. Derive it from the *event*, not the clock. Same event → same
+key → provider (or your table) collapses the duplicate.
+
+```ts
+const idempotencyKey = `pwreset:${userId}:${tokenVersion}`; // stable across retries
+```
+
+- **Resend:** native. Pass `{ idempotencyKey }` as the 2nd arg; retained 24h,
+  ≤256 chars. For a batch, the key represents the whole batch (e.g.
+  `team-quota/123456789`), not each row.
+- **Postmark / SendGrid:** no idempotency feature. You must self-dedupe: write
+  the key to a `sent_emails` table inside the same transaction as the send,
+  unique-constrain it, and skip if it already exists.
+
+```ts
+// Self-dedupe seam for providers without native keys
+const inserted = await db.sentEmails.insertIfAbsent({ key: idempotencyKey });
+if (!inserted) return; // already sent — do not re-fire
+await sendEmail({ to, subject, html, idempotencyKey });
+```
+
+```ts
+// Bad — no key; queue retry sends the reset 3×
+await sendEmail({ to, subject, react: <Reset url={url} /> } as any);
+```
+
+## Step 5 — batch / bulk
+
+`resend.batch.send([...])` is capped at **100 emails per call** and forbids
+attachments/scheduling. Chunk larger runs, then inspect *both* arrays for
+partial failure — a 200 response can still contain per-row errors.
+
+Checklist for a bulk run:
+
+- [ ] Filter the recipient list against the suppression list (Step 7) first.
+- [ ] Chunk into ≤100; one `idempotencyKey` per chunk.
+- [ ] Use `batchValidation: 'permissive'` so one bad address does not nuke the chunk.
+- [ ] Iterate results: collect succeeded ids and failed rows separately.
+- [ ] Re-queue only the failed rows; never replay the whole chunk.
+
+```ts
+function chunk<T>(xs: T[], n = 100) { const o: T[][] = []; for (let i = 0; i < xs.length; i += n) o.push(xs.slice(i, i + n)); return o; }
+
+for (const [i, group] of chunk(recipients).entries()) {
+  const { data } = await resend.batch.send(
+    group.map((r) => ({ from, to: r.email, subject, react: <Digest items={r.items} /> })),
+    { idempotencyKey: `digest-2026-06/${i}`, batchValidation: 'permissive' },
+  );
+  data?.data?.forEach((d) => markSent(d.id));      // succeeded rows
+  // inspect per-row errors and re-queue only those — do not replay the chunk
+}
+```
+
+## Step 6 — transactional vs broadcast split
+
+Reputation isolation. Give each stream a distinct From, subdomain, and
+stream/IP so they cannot poison each other:
+
+| Stream | From | Subdomain | Provider stream |
+|--------|------|-----------|-----------------|
+| Transactional | `noreply@notify.yourdomain.com` | `notify.` | Resend default / Postmark `outbound` |
+| Broadcast | `news@promo.yourdomain.com` | `promo.` | dedicated marketing stream / `broadcast` |
+
+*Why:* a marketing send that trips a blocklist must never take password resets
+down with it. The DNS/auth setup for those subdomains is
+`../email-deliverability/SKILL.md`'s job; you just send on the right one.
+
+## Step 7 — delivery/bounce/complaint webhook → suppression
+
+The provider POSTs bounce and complaint events. Verify the signature on the
+**raw** body (parse after verifying), then write the address to a suppression
+list and check that list before every future send. The verification is absolute
+because this hook mutates the suppression list: unverified, anyone can suppress
+— or un-suppress — your users.
+
+```ts
+// app/api/email/webhook/route.ts (Next.js 16) — verify BEFORE parsing
+export async function POST(req: Request) {
+  const raw = await req.text();                       // raw body, not req.json()
+  if (!verifyProviderSignature(raw, req.headers)) return new Response('bad sig', { status: 401 });
+  const event = JSON.parse(raw);
+  if (event.type === 'email.bounced' || event.type === 'email.complained') {
+    await db.suppressions.upsert({ email: event.data.to, reason: event.type });
+  }
+  return new Response('ok');
+}
+```
+
+```ts
+// Before any send: skip suppressed addresses
+const recipients = candidates.filter(async (e) => !(await db.suppressions.has(e)));
+```
+
+Generic webhook hardening (replay windows, queueing, retries beyond email) is
+`../webhooks/SKILL.md`. The address-validity question (is this mailbox real
+before I ever send) is `../lead-gen/SKILL.md` / `../email-deliverability/SKILL.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|--------------|--------------|------------|
+| API key hard-coded (`re_…`, `SG.…`, server token) | Committed credential = send-as-you abuse | Read from `process.env`; rotate via `../secure-coding/SKILL.md` |
+| No idempotency key on transactional sends | Queue/serverless retry double-sends | Deterministic `event:userId:version` key |
+| One stream for everything | Marketing hit poisons reset/receipt deliverability | Split From + subdomain + stream (Step 6) |
+| String-concatenated HTML with user input | XSS + broken layout | React Email component or `d-` dynamic template |
+| Ignoring per-row `data.errors` in a batch | Silent partial loss; "looked like 200" | Inspect both arrays; re-queue only failures |
+| Trusting the webhook without signature check | Anyone can poison your suppression list | Verify signature on raw body, then parse |
+| Sending to a bounced/complained address | Reputation damage, ISP penalties | Filter against suppression list before send |
+| Calling the provider SDK at scattered call sites | Provider swap = grep across the app | One `sendEmail()` seam (Step 2) |

package/skills/email-connector/evals/README.md

@@ -0,0 +1,19 @@
+# Evals — email-connector
+
+`cases.yaml` holds three blocks. `should_trigger` (5 prompts) are situations
+this skill must own — including the non-obvious "emails double-send on retry"
+(idempotency) and a Spanish bounce-webhook phrasing. `should_not_trigger` (4
+prompts) are near-misses that each route to a real sibling (`newsletter`,
+`email-deliverability`, `google-workspace`, `api-connector-builder`) so the
+routing boundary is checked, not just recall. `capability` (1 scenario) is an
+end-to-end SaaS wiring task with a `must_include` rubric covering the seam, env
+key, idempotency, templating, batch partial-failure, stream split, webhook
+signature, and suppression.
+
+There is no automated runner here. To evaluate, paste each `should_trigger` /
+`should_not_trigger` prompt into an agent loaded with the catalog and confirm it
+selects (or declines to) `email-connector` and routes to the named sibling. For
+`capability`, run the scenario and check the produced integration against every
+`must_include` line — then run `scripts/verify.sh <path-to-integration>` to
+mechanically confirm the env-key, idempotency, seam, and webhook-signature
+invariants on the generated code.

package/skills/email-connector/evals/cases.yaml

@@ -0,0 +1,39 @@
+skill: email-connector
+
+should_trigger:
+  - prompt: "Send a password-reset email from my Next.js app with Resend when a user requests one."
+    why: "Core wiring: hook a transactional send into app code through a provider — squarely the seam this skill owns."
+  - prompt: "Our emails double-send when the background queue retries the job. How do we stop the duplicates?"
+    why: "Non-obvious phrasing — the user names a symptom, not 'idempotency'. The fix is a deterministic idempotency key on the send, exactly this skill's Step 4."
+  - prompt: "We want to switch off SendGrid onto Postmark without rewriting every call site in the app."
+    why: "Provider swap behind a sendEmail() seam — the skill's central abstraction; the answer is the seam, not a one-off rewrite."
+  - prompt: "Send a digest to 4,000 users in one run and handle the ones that fail without re-sending the rest."
+    why: "Batch/bulk with partial-failure handling: 100-cap chunking and inspecting per-row errors, the skill's Step 5."
+  - prompt: "Montar el webhook de bounces para que actualice la lista de supresión cuando un correo rebota."
+    why: "Spanish phrasing for the inbound delivery/bounce webhook feeding a suppression list — the skill's Step 7, including verifying the signature on the raw body."
+
+should_not_trigger:
+  - prompt: "Write the subject line and the welcome-email sequence for our newsletter, optimized for opens."
+    route_to: newsletter
+    why: "Copy and the open/click growth system — words and strategy, not the send wiring this skill produces."
+  - prompt: "Our receipts keep landing in spam. Fix our SPF, DKIM, and DMARC records."
+    route_to: email-deliverability
+    why: "Inbox auth/reputation at the DNS layer — under the wire, not the wire. This skill sends on the right subdomain but does not own the DNS."
+  - prompt: "Send this email straight from my own Gmail account through the API, not a transactional provider."
+    route_to: google-workspace
+    why: "Sending from a user's own mailbox via OAuth — a different transport entirely from an HTTP email provider."
+  - prompt: "Build a generic typed client wrapper for the Acme REST API with retries and pagination."
+    route_to: api-connector-builder
+    why: "Generic HTTP-client scaffolding for any third-party API, with no email-specific surface."
+
+capability:
+  - scenario: "Wire transactional email for a SaaS on Next.js 16: pick a provider, expose a provider-agnostic sendEmail() seam, render a React Email template, make the send idempotent, send a bulk digest with partial-failure handling, split transactional from broadcast, and add a bounce webhook that updates a suppression list."
+    must_include:
+      - "A single provider-agnostic sendEmail() seam; the provider SDK is imported in one place, not at scattered call sites"
+      - "API key read from process.env, never a hard-coded re_/SG./server-token literal"
+      - "A deterministic idempotency key on each transactional send (Resend native 2nd arg; self-dedupe table for SendGrid/Postmark)"
+      - "Templates rendered as React Email components (react:) or SendGrid d- dynamic templates with dynamicTemplateData — not string-concatenated HTML"
+      - "Batch send chunked to the 100-cap with per-row errors inspected and only failed rows re-queued"
+      - "Transactional and broadcast traffic separated by From + subdomain + stream"
+      - "Webhook signature verified against the raw body before parsing"
+      - "Suppression list updated on bounce/complaint and checked before every send"

package/skills/email-connector/references/providers.md

@@ -0,0 +1,107 @@
+# Provider matrix — Resend / SendGrid / Postmark
+
+Side-by-side reference for the three HTTP email providers `email-connector`
+supports. Versions current as of June 2026. The SKILL.md body is the
+instructional path; this file is the branch-specific lookup.
+
+## At a glance
+
+| Dimension | Resend | SendGrid (Twilio) | Postmark |
+|-----------|--------|-------------------|----------|
+| Node SDK | `resend` 6.12.4 | `@sendgrid/mail` 8.1.6 | none official — raw HTTP |
+| Auth | `new Resend(process.env.RESEND_API_KEY)` (Bearer) | `sgMail.setApiKey(process.env.SENDGRID_API_KEY)` | `X-Postmark-Server-Token` header |
+| Single send | `resend.emails.send({from,to,subject,html|text|react})` | `sgMail.send(msg)` | `POST /email` |
+| Batch | `resend.batch.send([...])`, ≤100, no attachments/scheduling | `personalizations[]` in one Mail Send call | per-stream send / `POST /email/batch` |
+| Native idempotency | Yes — 2nd arg `{ idempotencyKey }`, 24h, ≤256 chars | No → self-dedupe | No → self-dedupe |
+| Batch idempotency | key represents whole batch (`team-quota/123456789`) | n/a | n/a |
+| Template model | React Email JSX via `react:` (lazy `@react-email/render`) | `templateId: 'd-…'` + `dynamicTemplateData` | server-side Postmark templates |
+| Stream model | sending domains / separate API keys | suppression groups + IP pools | Message Streams: `outbound` (txn) + `broadcast` |
+| Rate limit | per-plan | up to 10,000 req/s on Mail Send; 429 over | per-plan; broadcast throttled separately |
+
+## Resend
+
+```ts
+import { Resend } from 'resend';
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+// single
+await resend.emails.send(
+  { from: 'App <noreply@notify.yourdomain.com>', to, subject, react: <Welcome /> },
+  { idempotencyKey: `welcome:${userId}:v3` }, // ≤256 chars, retained 24h
+);
+
+// batch — ≤100 per call, no attachments/scheduling
+await resend.batch.send(rows.map((r) => ({ from, to: r.email, subject, react: <Digest /> })),
+  { idempotencyKey: `digest-2026-06/${chunkIndex}`, batchValidation: 'permissive' });
+```
+
+Webhook events: `email.sent`, `email.delivered`, `email.bounced`,
+`email.complained`, `email.opened`, `email.clicked`. Signature is verified via
+the Svix headers on the raw payload.
+
+## SendGrid (Twilio) v3 Mail Send
+
+```ts
+import sgMail from '@sendgrid/mail';
+sgMail.setApiKey(process.env.SENDGRID_API_KEY!);
+
+await sgMail.send({
+  to, from: 'noreply@notify.yourdomain.com',
+  templateId: 'd-abc123…',                 // dynamic template, id starts with d-
+  dynamicTemplateData: { name, confirm_url },
+});
+// bulk: one call, multiple personalizations[] entries
+```
+
+No idempotency key: dedupe against your own `sent_emails` table before sending.
+Mail Send allows up to 10,000 requests/second and returns 429 over the limit —
+back off and retry with the same dedupe key. Event webhook posts
+`delivered`, `bounce`, `dropped`, `spamreport`, `unsubscribe`; verify the
+signed event-webhook signature on the raw body.
+
+## Postmark
+
+```ts
+await fetch('https://api.postmarkapp.com/email', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json', Accept: 'application/json',
+    'X-Postmark-Server-Token': process.env.POSTMARK_SERVER_TOKEN!,
+  },
+  body: JSON.stringify({
+    From: 'noreply@notify.yourdomain.com', To: to, Subject: subject,
+    HtmlBody: html, TextBody: text,
+    MessageStream: 'outbound', // 'broadcast' for marketing — never mix
+  }),
+});
+```
+
+No idempotency key — self-dedupe on your own id and reconcile with the message
+and bounce webhooks. Message Streams hard-separate transactional (`outbound`)
+from `broadcast` so a marketing reputation hit cannot reach receipts/resets.
+Webhook event types include `Delivery`, `Bounce`, `SpamComplaint`,
+`SubscriptionChange`; verify the configured webhook auth before parsing.
+
+## Suppression-webhook handler skeleton
+
+Same shape for all three: read raw body → verify signature → parse → on a
+bounce/complaint event upsert the address into the suppression table.
+
+```ts
+export async function POST(req: Request) {
+  const raw = await req.text();
+  if (!verifyProviderSignature(raw, req.headers)) return new Response('bad sig', { status: 401 });
+  const e = JSON.parse(raw);
+  const bounced =
+    e.type === 'email.bounced' || e.type === 'email.complained' || // Resend
+    e.event === 'bounce' || e.event === 'spamreport' ||            // SendGrid
+    e.RecordType === 'Bounce' || e.RecordType === 'SpamComplaint'; // Postmark
+  if (bounced) await db.suppressions.upsert({ email: addressFrom(e), reason: kindOf(e) });
+  return new Response('ok');
+}
+```
+
+Then filter every outbound recipient list against `db.suppressions` before
+sending (single or batch). Generic webhook hardening lives in
+`../../webhooks/SKILL.md`; inbox auth/reputation in
+`../../email-deliverability/SKILL.md`.