@voltro/cli 0.30.1 → 0.31.0

package/templates/agent-docs/plugins/governance.md

@@ -0,0 +1,143 @@
+# Governance
+
+> Data governance — retention TTL sweep, GDPR export + erasure, consent ledger, and field-level encryption for .encrypted() columns. Builds on audit + soft-delete.
+
+
+
+---
+
+<!-- source: en/plugins/governance.md -->
+## Governance
+
+_Data governance — retention TTL sweep, GDPR export + erasure, consent ledger, and field-level encryption for .encrypted() columns. Builds on audit + soft-delete._
+
+`@voltro/plugin-governance` is the compliance layer: a periodic **retention sweep** that deletes or anonymises stale rows, **GDPR export + erasure** across every table that references a subject, a **consent ledger**, and **field-level encryption** for `.encrypted()` columns. It pairs with `@voltro/plugin-audit` (who/when) and `@voltro/plugin-soft-delete` (recoverable deletes).
+
+## Wiring
+
+```ts
+// app.config.ts
+import { governancePlugin } from '@voltro/plugin-governance'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [
+    governancePlugin({
+      // Retention: delete/anonymise rows past a TTL on a periodic sweep.
+      retention: [
+        { table: 'events', ttlMs: 90 * 86_400_000 },                                  // delete after 90 days
+        { table: 'users', ttlMs: 365 * 86_400_000, action: 'anonymize', anonymizeFields: ['email', 'name'] },
+      ],
+      // GDPR: which tables reference a subject + by which column.
+      subjectScopes: [
+        { table: 'users', subjectField: 'id' },
+        { table: 'posts', subjectField: 'userId' },
+        { table: 'comments', subjectField: 'authorId' },
+      ],
+      sweepIntervalMs: 3_600_000,   // default 1h
+    }),
+  ],
+}
+```
+
+## Retention
+
+`runRetention` walks each policy's table and, for rows older than `ttlMs` (measured from `dateField`, default `createdAt`), either deletes them (`action: 'delete'`, default) or nulls `anonymizeFields` (`action: 'anonymize'`). The sweep is armed in `bindDataStore` and stopped on `onDeactivate`; trigger it manually via the service's `runRetentionNow()`. On a multi-replica SQL deployment the sweep is **cluster-coordinated** — it runs on only ONE replica per tick (via the same claim gate the cron scheduler uses), so N replicas no longer each run the full paged scan; single-process / memory / SQLite deployments run it locally every tick. No configuration — it's automatic.
+
+## GDPR — export + erasure (admin-gated)
+
+Two admin-only routes (guarded by `requireScope(ADMIN_SCOPE)`) walk `subjectScopes`:
+
+- **`governance.export`** `{ subjectId }` → a portable bundle `{ [table]: rows[] }` of everything referencing the subject.
+- **`governance.erase`** `{ subjectId, mode? }` → deletes (or anonymises) the subject across every scope; returns an immutable `ErasureLogEntry` (`{ subjectId, at, mode, affected: [{ table, count }] }`).
+
+The same operations are available in-handler via `GovernanceService` (`exportSubject` / `eraseSubject`).
+
+## Consent ledger
+
+`governance.consent` `{ purpose, granted }` records the calling subject's decision; `governance.hasConsent` `{ purpose }` reads the latest (latest-write-wins per `(subject, purpose)`).
+
+The default store is **in-memory** — per-process + restart-cleared, so a consent recorded on one replica is invisible to others (the plugin **warns at boot** when it runs under this default). For production pass `consent: 'datastore'` for the shipped **durable, cross-instance** store: it contributes a `_voltro_consent` table (via `extendSchema`, under the `store:write` permission the plugin already declares) and appends one row per decision, so a consent recorded on any replica is visible everywhere and the full history persists for audit. Or pass a custom `ConsentStore`.
+
+```ts
+governancePlugin({ consent: 'datastore' })   // durable + cross-instance
+```
+
+```ts
+import { GovernanceService } from '@voltro/plugin-governance'
+
+export default (input, ctx) => Effect.gen(function* () {
+  const gov = yield* GovernanceService
+  if (!(yield* Effect.promise(() => gov.hasConsent(ctx.request.subject.id, 'marketing')))) return { skipped: true }
+  // … send the marketing email …
+})
+```
+
+## Field-level encryption
+
+Flag a column `.encrypted()` in the schema and `fieldEncryption: true` registers an AES-256-GCM cipher that the store middleware applies transparently — writes encrypt, reads decrypt, handlers always see plaintext, the column stores an opaque `enc:v1:…` string on every dialect.
+
+```ts
+// schema — database/patients.entity.ts
+export const patients = table('patients', {
+  id:   id(),
+  name: text(),
+  ssn:  text().encrypted(),       // AES-256-GCM at rest
+  notes: json().encrypted(),      // any column type — JSON-encoded then encrypted
+})
+
+// app.config.ts
+governancePlugin({ fieldEncryption: true })   // key from secret VOLTRO_FIELD_ENCRYPTION_KEY
+// or: fieldEncryption: { secretKey: 'MY_KEY_NAME' }
+```
+
+The key resolves through the [Secrets-Resolver](/docs/configuration/secrets) — pass a 64-hex-char string for raw key bytes, or any passphrase (scrypt-derived). Rules:
+
+- **Lose the key, lose the data.** GCM authentication fails closed — a wrong/tampered value throws on read, never silently corrupts. The failure is a typed `FieldDecryptionError` naming the `table.column` (not a raw `malformed ciphertext` with no context, and never the ciphertext itself), so you can see WHICH column and `Effect.catchTag` it server-side. If it reaches the wire UNCAUGHT, it collapses to a generic `InternalError` for the client (the `table.column` and cause stay in the server log) — never an `ExitEncoded` schema dump.
+- An `.encrypted()` column **can't be filtered or sorted by plaintext in SQL** (it's ciphertext on disk). Encrypt only what you read back whole — PII, tokens, free-text notes.
+- Boot fails loud if an `.encrypted()` column exists but no cipher is registered (enable `fieldEncryption`), or if `fieldEncryption` is on but the key can't resolve.
+- Reads of rows written *before* encryption was enabled pass through untouched (only `enc:v1:…` values are decrypted), so you can turn it on incrementally.
+
+### Restoring a snapshot encrypted under a different key
+
+Importing a prod/staging DB dump into a dev DB brings ciphertext bound to the
+*source* key — your dev `VOLTRO_FIELD_ENCRYPTION_KEY` can't read it, and by
+default one such row throws a `FieldDecryptionError` that fails the whole read
+(including its readable siblings). For dev/migration only, set:
+
+```bash
+VOLTRO_FIELD_DECRYPT_ON_ERROR=null
+```
+
+Now an undecryptable column degrades to `null` with one deduped warning per
+`table.column` (scope `store.fieldEncryption`) instead of nuking the read — the
+row's other columns still decrypt. This is the difference between "re-enter your
+Jira PAT" and "the whole section 500s". **Never set it in production**, where a
+key mismatch must fail loud. A cutover tool that writes rows into `.encrypted()`
+columns should `NULL` those columns on import — the source ciphertext is useless
+without the source key, and users re-enter the credential so it re-encrypts under
+the local one.
+
+### Raw-SQL escape hatch — `encryptField` / `decryptField`
+
+Transparent encryption runs INSIDE the `ctx.store` middleware, so a code path that reaches the DB by **raw SQL** — an auth strategy writing/reading a session token with no store handle, a one-off backfill — bypasses it. For those, `@voltro/runtime` exposes the SAME registered cipher standalone:
+
+```ts
+import { encryptField, decryptField } from '@voltro/runtime'
+
+// write path (raw SQL): encrypt by hand
+await sql`INSERT INTO sessions (id, token) VALUES (${id}, ${encryptField(pat)})`
+// read path (raw SQL): decrypt by hand
+const token = decryptField(row.token)   // a non-ciphertext value returns unchanged
+```
+
+`decryptField` returns a non-`enc:v1:…` value **unchanged**, so you can switch a raw-SQL path to encryption while pre-existing plaintext rows keep working until they're re-written. Both throw a clear error if no cipher is registered (enable `fieldEncryption`). Encryption stops being all-or-nothing tied to going through `ctx.store`.
+
+## Dashboard panel
+
+Both dashboards ship a **Governance** panel (api apps): retention-policy status + field-encryption state + last-sweep results (with a **Run sweep now** button), a **GDPR runner** (enter a subject id → Export / Erase delete / Erase anonymize), a consent-ledger lookup, and the erasure log. Write-actions gate on the `canRunGovernance` capability. Backed by `/_voltro/inspect/plugins/governance/{status,erasures,consent,export,erase,sweep}`.
+
+## Permissions
+
+`store:write` (retention sweep + GDPR erasure mutate rows; field encryption rides the store middleware) + `inspect:read` (dashboard panel).

package/templates/agent-docs/plugins/licensing.md

@@ -0,0 +1,74 @@
+# Licensing
+
+> Offline-verified EdDSA license keys + cloud-issued entitlement snapshots that feed plugin-billing; pricing decided server-side, never baked into a published version.
+
+
+
+---
+
+<!-- source: en/plugins/licensing.md -->
+## Licensing
+
+_Offline-verified EdDSA license keys + cloud-issued entitlement snapshots that feed plugin-billing; pricing decided server-side, never baked into a published version._
+
+`@voltro/plugin-licensing` lets a **cloud** decide a customer's plan entitlements and pricing, and enforces them in a **running app** — without baking anything into an immutable published version. The license is a compact **EdDSA (Ed25519)** token, verified **offline** with a public key the app embeds. It's asymmetric on purpose: the signing secret never leaves the cloud, so a customer cannot forge a license.
+
+The plugin does not enforce quotas itself — it feeds [`plugin-billing`](/docs/plugins/billing), which meters and enforces them via a new `resolveEntitlementLimit` seam.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { licensingPlugin, entitlementResolver } from '@voltro/plugin-licensing'
+import { billingPlugin } from '@voltro/plugin-billing'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [
+    licensingPlugin(),                          // reads VOLTRO_LICENSE_* env
+    billingPlugin({
+      plans: { free: { entitlements: { projects: 1 } } },  // static fallback
+      resolveEntitlementLimit: entitlementResolver,        // license overrides per-tenant
+    }),
+  ],
+}
+```
+
+With a valid `pro` license granting `{ projects: 3 }`, `requireEntitlement(ctx, 'projects', 1)` allows three and then fails `EntitlementExceeded`. With no license, the static `free` plan (`projects: 1`) applies — the resolver returns `null` and billing falls back to its own registry.
+
+## Keys
+
+Generate a signing keypair:
+
+```sh
+voltro secret keypair
+# VOLTRO_LICENSE_SIGNING_KEY  (Ed25519 private, cloud-only — signs licenses, NEVER ship)
+# VOLTRO_LICENSE_PUBLIC_KEY   (Ed25519 public — ship to apps for offline verify)
+```
+
+Keep the private key in the cloud; the public key is safe to embed. The app reads `VOLTRO_LICENSE_PUBLIC_KEY` + `VOLTRO_LICENSE_KEY` (or the `publicKey` / `licenseKey` options).
+
+## Options
+
+| Option | Env fallback | Meaning |
+|---|---|---|
+| `publicKey` | `VOLTRO_LICENSE_PUBLIC_KEY` | Ed25519 public key (SPKI/PEM). |
+| `licenseKey` | `VOLTRO_LICENSE_KEY` | The signed license token, verified at boot. |
+| `snapshotUrl` | — | URL to periodically re-fetch a fresh license (entitlement sync). |
+| `refreshMs` | — | Refresh cadence for `snapshotUrl` (default 15 min, cluster-coordinated). |
+| `graceSeconds` | — | Seconds an expired license is still honored (default 0). |
+
+## API
+
+- **`entitlementResolver(tenantId, key)`** — pass to `billingPlugin({ resolveEntitlementLimit })`. Returns the license's limit for the pair, or `null` to fall back to the static plan registry.
+- **`LicenseService`** — `yield* LicenseService` in a handler to read `limitFor` / `hasFeature` / `allowsPlugin` / `edition` / `snapshot` directly.
+- **`licenseAllowsPlugin(name)` / `requireLicensedPlugin(name)`** — the plugin gate ("installed ≠ billable"). A license carries a `plugins: string[]` grant; `requireLicensedPlugin` fails `PluginNotLicensed` when a plugin's production use isn't licensed. Metered plugin pricing uses entitlement keys (`plugin:<name>:<meter>`); plan-gated plugins use the grant. Pricing is decided server-side and travels in the signed license — no `plugin_definitions` table needed in the app.
+- **`verifyLicense(token, publicKeyPem)`** — offline EdDSA verify → `LicenseClaims`.
+- **`@voltro/plugin-licensing/sign` → `signLicense(input, privateKeyPem)`** — server-only signer for the cloud/CLI to mint licenses.
+
+## Notes
+
+- **Server-only** (imports `jose`) — never import from a browser-loaded descriptor.
+- **Fail-closed**: an invalid/expired token grants nothing; billing falls back to the static plan. The last-good snapshot is honored within `graceSeconds`.
+- Cloud-side issuance (a license endpoint + `voltro cloud register`) ships in a later milestone; today licenses are provided via env / config.

package/templates/agent-docs/plugins/logship.md

@@ -0,0 +1,56 @@
+# Log shipping
+
+> Ship structured logs to Better Stack / Axiom / Loki / any HTTP sink — batched, redacted, fail-soft. Rides the framework log-sink hook.
+
+
+
+---
+
+<!-- source: en/plugins/logship.md -->
+## Log shipping
+
+_Ship structured logs to Better Stack / Axiom / Loki / any HTTP sink — batched, redacted, fail-soft. Rides the framework log-sink hook._
+
+`@voltro/plugin-logship` forwards the framework's structured `@voltro/logger` stream to a log backend. It rides the log-sink hook (`addSink`), batches records, redacts secrets, and fails soft — a backend outage never disturbs the app.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { logshipPlugin } from '@voltro/plugin-logship'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [
+    // Pick ONE backend (discriminated union):
+    logshipPlugin({ backend: 'betterstack', token: process.env.BETTERSTACK_TOKEN! }),
+    // logshipPlugin({ backend: 'axiom', token: process.env.AXIOM_TOKEN!, dataset: 'voltro' }),
+    // logshipPlugin({ backend: 'loki', endpoint: process.env.LOKI_URL!, tags: { app: 'api' } }),
+    // logshipPlugin({ backend: 'http', endpoint: 'https://logs.example.com/ingest', headers: { ... } }),
+  ],
+}
+```
+
+## Behaviour
+
+- **Batching** — records buffer and flush on a size/interval threshold (one HTTP POST per batch, not per line). The batch is bounded on BOTH axes: record count (`maxBatch`, default 200) and approximate payload bytes (`maxBatchBytes`, default 900 000 — headroom under the ~1 MB tiers Better Stack / Axiom / Loki cap at). A burst of large records flushes early so a batch can't exceed the intake's payload limit; a single record larger than the cap still ships alone (the cap bounds the batch, not the record).
+- **Redaction** — a `redact: (record) => record` hook rewrites each record before shipping (drop or mask fields), e.g. `redact: (r) => ({ ...r, fields: { ...r.fields, token: undefined } })`.
+- **Fail-soft** — a backend error logs a local warning and drops the batch; the app keeps running. Logs are observability, not a hard dependency.
+- **Trace correlation** — every record carries `fields.traceId`, so the shipped logs join the same end-to-end chain `voltro logs --trace <id>` shows locally.
+- **Deliberately not shipped (yet)** — no gzip compression (batches ship uncompressed; `maxBatchBytes` bounds the uncompressed payload), no built-in sampling (shed by severity with `minLevel` or by predicate with `redact`), and no bounded retry (a failed batch is dropped, not requeued — the shed-don't-requeue fail-soft posture). Each is additive and roadmap, not a phantom advertised feature.
+
+## Backends
+
+| `backend` | Required | Endpoint |
+|---|---|---|
+| `betterstack` | `token` (opt. `endpoint`, `tags`) | Better Stack Logs ingest |
+| `axiom` | `token`, `dataset` (opt. `endpoint`, `tags`) | Axiom `/v1/datasets/<dataset>/ingest` |
+| `loki` | `endpoint` (opt. `tags`) | Grafana Loki `/loki/api/v1/push` |
+| `http` | `endpoint` (opt. `headers`, `tags`) | any JSON-array ingest |
+
+The request shaping per backend is pure (`betterStackRequest` / `axiomRequest` / `lokiRequest` / `httpRequest` → a `ShipRequest`), so the mapping is unit-tested without a network.
+
+## Permissions
+
+`network:outbound:<host>` (declared from the backend host) — the plugin only ships to the configured host.

package/templates/agent-docs/plugins/mail.md

@@ -0,0 +1,334 @@
+# Mail
+
+> Transactional email — Resend / Postmark / SendGrid / SMTP, React-Email templates with auto-discovery, per-tenant suppression, bounce/complaint handling, durable delivery via workflows.
+
+
+
+---
+
+<!-- source: en/plugins/mail.md -->
+## Mail
+
+_Transactional email — Resend / Postmark / SendGrid / SMTP, React-Email templates with auto-discovery, per-tenant suppression, bounce/complaint handling, durable delivery via workflows._
+
+`@voltro/plugin-mail` is transactional email behind one `MailService`. It ships
+provider adapters, React-Email templates discovered from `*.email.tsx` files, a
+per-tenant suppression list fed by bounce/complaint webhooks, and a dev
+allowlist. Durable delivery rides the framework's workflow engine — there is no
+separate queue/worker to run.
+
+## Quick start
+
+```ts
+// app.config.ts
+import { mailPlugin } from '@voltro/plugin-mail'
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  plugins: [
+    mailPlugin({
+      provider: 'resend',                 // reads RESEND_API_KEY
+      from:     'Acme <hello@acme.com>',
+      // suppression: 'postgres',         // multi-node bounce/complaint list
+      // allowlist:  ['me@acme.com'],     // dev-only: don't email real users
+    }),
+  ],
+}
+```
+
+In any handler, pull the service off the plugin's services layer:
+
+```ts
+import { MailService } from '@voltro/plugin-mail'
+import { Effect } from 'effect'
+
+export default (input: { email: string }) =>
+  Effect.gen(function* () {
+    const mail = yield* MailService
+    yield* mail.send({ to: input.email, subject: 'Hi', html: '<p>welcome</p>' })
+    return { sent: true }
+  })
+```
+
+## Attachments
+
+Both raw and template messages take an `attachments` list — `MailAttachment` is `{ filename, content, contentType? }` where `content` is base64. It maps to each transport's native attachment shape (Resend / Postmark / SendGrid / SMTP):
+
+```ts
+yield* mail.send({
+  to: user.email,
+  subject: 'Your invoice',
+  html: '<p>Attached.</p>',
+  attachments: [{ filename: 'invoice.pdf', content: pdfBase64, contentType: 'application/pdf' }],
+})
+```
+
+## Providers
+
+One `MailProvider` contract, several adapters. `provider` is a string (built
+from env) or a `MailProvider` object (the exported factories / bring-your-own).
+
+| Provider | `provider` | Transport | Key (env) |
+|---|---|---|---|
+| Resend | `'resend'` | REST (`fetch`) | `RESEND_API_KEY` |
+| Postmark | `'postmark'` | REST (`fetch`) | `POSTMARK_SERVER_TOKEN` |
+| SendGrid | `'sendgrid'` | REST (`fetch`) | `SENDGRID_API_KEY` |
+| SES | `'ses'` | SESv2 REST (HttpClient, SigV4) | `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN?` |
+| Mailgun | `'mailgun'` | REST (HttpClient, form) | `MAILGUN_API_KEY`, `MAILGUN_DOMAIN`, `MAILGUN_BASE_URL?` |
+| SMTP | `'smtp'` | nodemailer | `SMTP_URL` or `SMTP_HOST`/`SMTP_PORT`/`SMTP_USER`/`SMTP_PASS` |
+| console | `'console'` | logs to stdout | — (zero-config default) |
+| memory | `'memory'` | in-process buffer | — (tests: `readMailBuffer()`) |
+
+```ts
+// string + env (default: MAIL_PROVIDER env, else 'console')
+mailPlugin({ provider: 'postmark', from: '…' })
+
+// explicit factory — full control / DI
+import { resendProvider } from '@voltro/plugin-mail'
+mailPlugin({ provider: resendProvider({ apiKey: process.env.RESEND_API_KEY! }), from: '…' })
+```
+
+Resend / Postmark / SendGrid use `fetch`; SES + Mailgun go through the
+framework-native `@effect/platform` HttpClient (SES is SigV4-signed with
+`node:crypto` — no `@aws-sdk`); SMTP uses `nodemailer` (optional dep, loaded
+only when used). None pull a vendor SDK. Policy — default `from`, transient
+retry, suppression, allowlist, scheduling, batching, idempotency — lives in the
+service, not the adapters. A failed send fails with a typed `MailError` whose
+`transient` flag (429 / 5xx / network) drove the retry.
+
+**SES + Mailgun setup.** SES resolves from `AWS_REGION` +
+`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` (+ optional `AWS_SESSION_TOKEN`
+for STS creds); the endpoint is derived from the region. Mailgun resolves from
+`MAILGUN_API_KEY` (sent as the HTTP basic-auth password for user `api`) +
+`MAILGUN_DOMAIN`, with `MAILGUN_BASE_URL=https://api.eu.mailgun.net` for the EU
+region. Secrets are read from env / options and never logged.
+
+## Templates — `*.email.tsx`
+
+Author emails as React-Email components. `defineEmail` pairs a name + an
+effect/Schema for the props + the subject line + the render function:
+
+```tsx
+// apps/api/emails/welcome.email.tsx
+import { defineEmail } from '@voltro/plugin-mail'
+import { Html, Head, Body, Text, Button } from '@react-email/components'
+import { Schema } from 'effect'
+
+export const welcome = defineEmail({
+  name:    'welcome',
+  props:   Schema.Struct({ name: Schema.String }),
+  preview: { name: 'Mario' },               // dashboard preview pre-fill
+  subject: (p) => `Welcome, ${p.name}!`,
+  render:  (p) => (
+    <Html>
+      <Head />
+      <Body>
+        <Text>Hi {p.name},</Text>
+        <Button href="https://acme.com/dashboard">Open dashboard</Button>
+      </Body>
+    </Html>
+  ),
+})
+```
+
+Send it by name — props are validated against the Schema, the subject is
+derived, and the component is rendered to **HTML + plain-text**:
+
+```ts
+yield* mail.send({ to: user.email, template: 'welcome', props: { name: user.name } })
+```
+
+**Auto-discovery:** `voltro dev` walks `*.email.tsx` files and registers their
+`defineEmail(...)` exports automatically — you don't list them in
+`app.config.ts`. (To register by hand, e.g. in a test, pass
+`mailPlugin({ templates: [welcome] })`; explicit templates win over discovered
+ones.)
+
+**Locales:** add a `locale` and the matching variant is picked, falling back to
+the base template:
+
+```tsx
+export const welcomeDe = defineEmail({ name: 'welcome', locale: 'de', /* … */ })
+```
+
+```ts
+yield* mail.send({ to, template: 'welcome', props, locale: 'de' }) // → welcome.de, else welcome
+```
+
+Rendered output is cached by `(template, locale, props)`. `react` +
+`@react-email/render` are optional peers — apps that never send a template
+never load them.
+
+## Suppression — bounces & complaints
+
+Bounced or complained addresses land on a per-tenant suppression list; the send
+path silently drops suppressed recipients (and skips the send entirely if none
+remain). Backend is `'memory'` (default, single-node) or `'postgres'` (own pool
+from the same `DB_*`/`PG_*` env; creates `_voltro_mail_suppression`). Both fail
+OPEN — a suppression-db blip never blocks legitimate mail.
+
+```ts
+mailPlugin({ provider: 'resend', from: '…', suppression: 'postgres' })
+```
+
+Manage it from a handler — the `MailService` exposes the list directly:
+
+```ts
+const mail = yield* MailService
+yield* mail.suppress(tenantId, 'dead@x.com', 'manual')
+yield* mail.unsuppress(tenantId, 'recovered@x.com')
+const blocked = yield* mail.isSuppressed(tenantId, 'dead@x.com')
+```
+
+Pass `tenantId` on a message to scope the check; omit it for app-global
+suppression:
+
+```ts
+yield* mail.send({ to: user.email, tenantId: user.tenantId, subject: '…', html: '…' })
+```
+
+### Bounce / complaint webhooks
+
+Providers POST delivery events; `parseMailEvent` normalises each provider's
+shape and `handleMailEvents` applies them — bounces + complaints auto-suppress.
+Mount it from a `*.webhook.tsx` incoming query (signature-verified by
+`@voltro/plugin-webhooks`):
+
+```tsx
+// apps/api/webhooks/resend.webhook.tsx
+import { defineIncomingWebhook } from '@voltro/plugin-webhooks'
+import { genericProvider } from '@voltro/plugin-webhooks/providers'
+import { handleMailEvents, memorySuppressionStore } from '@voltro/plugin-mail'
+import { Effect, Schema } from 'effect'
+
+// Use the SAME suppression store the mail plugin uses (export it from a
+// shared module, or use the postgres store which is process-global).
+const suppression = memorySuppressionStore()
+
+export default defineIncomingWebhook({
+  id: 'resend',
+  provider: genericProvider(),            // verifies the signing secret
+  payload: Schema.Any,
+  handler: async (ctx) =>
+    Effect.runPromise(handleMailEvents('resend', ctx.body, suppression, ctx.headers['x-tenant'] ?? null)),
+})
+```
+
+- `parseMailEvent(provider, payload)` → normalised `MailEvent[]`
+  (`delivered | bounced | complained | opened | clicked`) for `'resend'`,
+  `'postmark'`, and `'sendgrid'` (SendGrid posts an array).
+- `handleMailEvents(provider, payload, store, tenantId?)` parses **and**
+  suppresses bounced/complained addresses in one call, returning the events
+  for logging/auditing.
+
+## Send-time scheduling
+
+Pass `scheduledAt: Date` to deliver later. Providers that schedule natively —
+Resend (`scheduled_at`), SendGrid (`send_at`), Mailgun (`o:deliverytime`) —
+get it on the wire. For the rest (`console` / `memory` / `smtp` / `ses`) the
+service **holds** the message and a background flush loop delivers it once the
+due time passes:
+
+```ts
+yield* mail.send({
+  to: user.email,
+  subject: 'Trial reminder',
+  html: '<p>Your trial ends tomorrow.</p>',
+  scheduledAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
+})
+```
+
+A held send returns `{ id: 'scheduled', provider: 'scheduled' }` right away; a
+`scheduledAt` in the past sends immediately. The hold store is in-memory by
+default (single-node) — pass a durable `ScheduleStore` via
+`mailPlugin({ schedule })` for cross-replica, restart-surviving schedules, or
+use a workflow step (below) for the crash-proof path.
+
+## Bulk / batch send
+
+`sendBatch` sends N **personalized** messages (each with its own subject,
+body, and template vars) in one provider call where the transport supports it
+(Resend `/emails/batch`, SendGrid N `personalizations`), falling back to a
+looped `send` otherwise. Allowlist, suppression, default-`from`, scheduling and
+idempotency apply per entry:
+
+```ts
+const mail = yield* MailService
+yield* mail.sendBatch([
+  { to: 'ana@x.com', template: 'welcome', props: { name: 'Ana' } },
+  { to: 'bob@x.com', template: 'welcome', props: { name: 'Bob' } },
+])
+```
+
+It returns one `SendResult` per input, in order.
+
+## Idempotency — webhook-retry double-send guard
+
+Pass `idempotencyKey` to guard against an at-least-once webhook / retry
+double-send **outside** a workflow step. The first send with a given key (per
+tenant) delivers and records its result; a replay with the same key is a no-op
+that returns the recorded `SendResult` — one delivery:
+
+```ts
+yield* mail.send({ to: user.email, subject: 'Receipt', html, idempotencyKey: webhookEvent.id })
+```
+
+The reservation is an atomic `INSERT … ON CONFLICT DO NOTHING`, so exactly one
+replica wins the key fleet-wide. Unlike suppression this store fails **closed**
+— a dedup-DB blip skips the send rather than risk a double. In-memory by
+default; set `mailPlugin({ idempotency: 'postgres' })` for cross-replica dedup.
+
+## Durable delivery — via workflows, not a queue
+
+There is **no separate mail queue or worker**. Durable execution in Voltro is
+`@effect/workflow` (the framework forbids parallel job runners). For a send
+that must survive a crash / retry from where it died, call `mail.send` inside a
+workflow `step` — the step result is journaled and replayed on resume:
+
+```tsx
+// apps/api/workflows/onboarding.workflow.tsx
+import { workflow, step } from '@voltro/workflow'
+import { MailService } from '@voltro/plugin-mail'
+import { Effect, Schema } from 'effect'
+
+export const Onboard = workflow({
+  name: 'onboarding',
+  payload: { email: Schema.String, name: Schema.String },
+  success: Schema.Struct({ ok: Schema.Boolean }),
+})
+
+const buildExecute = () => ({ email, name }: { email: string; name: string }) =>
+  Effect.gen(function* () {
+    const mail = yield* MailService
+    yield* step({
+      name: 'send-welcome',
+      success: Schema.Struct({ id: Schema.String, provider: Schema.String }),
+      execute: mail.send({ to: email, template: 'welcome', props: { name } }),
+    })
+    return { ok: true }
+  })
+
+export default buildExecute
+```
+
+A plain `mail.send` (outside a workflow) retries transient failures in-process
+but does not survive a crash. Use the workflow step when durability matters
+(onboarding, billing receipts); a bare `send` is right for best-effort
+notifications.
+
+## Dev safety — allowlist
+
+Outside production, set an allowlist so a staging run can't email real users.
+Recipients not on the list are dropped (logged); production bypasses it.
+
+```ts
+mailPlugin({ provider: 'resend', from: '…', allowlist: ['me@acme.com'] })
+// or env: MAIL_ALLOWLIST=me@acme.com,qa@acme.com
+```
+
+## See also
+
+- [Webhooks](/docs/plugins/webhooks) — mounting the provider bounce/complaint query
+- [Rate limiting](/docs/plugins/ratelimit) — the sibling interceptor plugin
+- [Multi-tenancy](/docs/multi-tenancy) — where per-tenant suppression scoping comes from

package/templates/agent-docs/plugins/moderation.md

@@ -0,0 +1,65 @@
+# Moderation
+
+> Moderate user content before it commits — keyword denylist or AI provider, block or flag via rpc interceptor, plus an in-handler redact helper.
+
+
+
+---
+
+<!-- source: en/plugins/moderation.md -->
+## Moderation
+
+_Moderate user content before it commits — keyword denylist or AI provider, block or flag via rpc interceptor, plus an in-handler redact helper._
+
+`@voltro/plugin-moderation` screens user-submitted content. A rule matches an rpc tag + fields; the configured provider classifies the text; the interceptor **blocks** (typed `ContentRejected`, the write never commits) or **flags** (annotates, lets it through). Because the interceptor can't rewrite input, **redact** is an in-handler helper.
+
+## Wiring
+
+```ts
+// app.config.ts
+import { moderationPlugin, keywordProvider, aiProvider } from '@voltro/plugin-moderation'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [
+    moderationPlugin({
+      provider: keywordProvider(['spam', 'scam', 'http://badsite']),  // or aiProvider() — uses @voltro/ai
+      rules: [
+        { match: 'posts.create', fields: ['title', 'body'], action: 'block' },
+        { match: /^comments\./, fields: ['text'], action: 'flag' },
+      ],
+    }),
+  ],
+}
+```
+
+## Providers
+
+- **`keywordProvider(terms)`** — pure denylist; zero deps, deterministic, instant. Best for a known set of banned terms / URLs.
+- **`aiProvider(opts?)`** — lazy `@voltro/ai` classification (`@voltro/ai` is an optional dep). **Fails open**: a provider error resolves to `CLEAN` so an AI outage can't block all writes. Use for nuanced toxicity/abuse detection.
+- Custom — any function with the provider signature `(text) => Effect.Effect<ModerationVerdict>` plugs into the same `provider` slot. The verdict is `{ flagged, categories?, score?, reason? }`.
+
+## Block vs flag vs redact
+
+- **`block`** — interceptor fails the call with typed `ContentRejected` (`{ tag, categories, reason }`, merged into the wire-error union). The write never commits.
+- **`flag`** — lets the write through; surfaces the classification for downstream review (e.g. a moderation queue).
+- **Redact** — the interceptor can't mutate input, so there is no `redact` action. Instead, call the in-handler `moderate(text)` helper: it **classifies** the text against the configured provider (returning a `ModerationVerdict` — it does NOT return redacted text) and the handler decides what to store:
+
+```ts
+import { moderate } from '@voltro/plugin-moderation'
+
+export default (input: { body: string }, ctx) => Effect.gen(function* () {
+  const verdict = yield* moderate(input.body)   // classifies via the configured provider
+  const body = verdict.flagged ? '[redacted]' : input.body
+  return yield* Effect.tryPromise(() => ctx.store.insert('posts', { body }))
+})
+```
+
+## Dashboard panel
+
+Both dashboards ship a **Moderation** panel (api apps): block/flag counts + the **review queue** of flagged content (tag, categories, reason, subject), each pending item with **Confirm** (real violation) / **Dismiss** (false positive) actions. Resolving gates on the `canModerateContent` capability. Backed by `/_voltro/inspect/plugins/moderation/{flagged,resolve}`.
+
+## Permissions
+
+`rpc:intercept:mutation` + `rpc:intercept:action` (moderation gates both writes and external-I/O actions) + `inspect:read` (dashboard panel).