[Feature] Colocate Forward Email provisioning in packages/post-kit-email + agent skill

[patoperpetua]

Parent: #2
Imported from: singleton-sd/poc-plattform-kit#274

Goal

Colocate Forward Email provisioning (management API + Route53 DNS) with @singleton-sd/post-kit-email so deploy-time ops live next to runtime send code, and add an agent skill that lets operators say “create this email config” and get Forward Email domain + alias + DNS records provisioned end-to-end.

In poc-plattform-kit, TypeScript helpers live in packages/email/src/provisioning/ while the idempotent Route53 writer is a repo-root PowerShell script (scripts/provision-forward-email.ps1). After the library lift, both belong in packages/post-kit-email/. AWS credentials and zone IDs come from pc-provision (Key Vault + route53.zones.map) and must not be duplicated in this repo.

Scope

1. Provisioning next to the email package

   • Prefer a TypeScript CLI (pnpm --filter @singleton-sd/post-kit-email provision or pnpm email:provision) that calls ForwardEmailManagementClient + Route53 UPSERT.
   • Keep PowerShell only if cross-platform TS is blocked; document the choice in docs/email-forward-email.md.
   • Single source of truth for DNS record shapes (MX, verification TXT, SPF merge, DKIM, Return-Path, DMARC) and domain/alias ensure + verify-records / verify-smtp.

2. pc-provision integration (credentials + zones)

   • Primary: Azure Key Vault ssd-devtools-kv-prod-ae secrets aws-access-key-id / aws-secret-access-key.
   • Zone lookup: singletonsd.com hosted zone id from pc-provision route53.zones.map.
   • Do not move AWS keys into post-kit.

3. Declarative email config

   • Versioned config (e.g. packages/post-kit-email/config/email-domains.json) with domain, zoneDomain, optional hostedZoneId, aliases[].
   • CLI/skill reads config → provisions Forward Email + Route53 idempotently.

4. Agent skill: “create this email config”

   • .cursor/skills/forward-email/SKILL.md (ported from poc): dry-run first, never log tokens, pc-provision for Route53 auth.

Out of scope

• Runtime send changes (ForwardEmailProvider) beyond the library lift.
• Moving DNS zone ownership or AWS IAM out of pc-provision.
• EmailBuilder / blob templates (epics Epic: Define Git-backed email templates, compilation, and publishing #3–Epic: Build the reusable EmailBuilder.js admin editor package #5).
• BIMI / automated branding validation (separate imported issue).

Acceptance criteria

• Provisioner lives under packages/post-kit-email/ (TS CLI preferred).
• Shared module defines DNS record expectations used by tests and the live provisioner.
• Declarative config file exists with example domains (no secrets).
• Provisioner loads AWS creds via documented pc-provision Key Vault flow.
• Dry-run prints planned Forward Email + Route53 changes without mutating.
• Agent skill documents the workflow with safety rules (no token logging, dry-run first).
• Docs updated; no leftover poc-only scripts/provision-forward-email.ps1 as the source of truth.

Constraints

• Secrets: FORWARD_EMAIL_TOKEN and AWS keys never in git or issue bodies. KV names only.
• Runtime vs deploy-time: Function App runtime must not import Route53 writers.
• DNS safety: merge SPF; do not drop unrelated TXT; skip DMARC overwrite on organisational conflict unless explicit force flag.
• Preview safety: EMAIL_PROVIDER=development remains the default for local/PR.

Agent-ready checklist

• Goal/problem statement is clear
• Scope is sufficient to start work without further business clarification
• Acceptance criteria are explicit
• Relevant constraints are stated
• Depends on: library lift (packages/post-kit-email) on main