vybekiit 0.7.3 → 0.7.7

package/dist/global-skills/eas-simulator/references/troubleshooting.md

@@ -4,15 +4,17 @@ Concrete errors seen while validating this flow, and the fix.
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| `Command simulator:start not found` | `eas-cli` too old (commands are hidden but present from ≥ 20.3.0) | Run via `npx eas-cli@latest …`, or upgrade `eas-cli`. |
+| `Command simulator:start not found` | `eas-cli` too old (commands are hidden but present from ≥ 20.3.0) | Run via `npx --yes eas-cli@latest …`, or upgrade `eas-cli`. |
+| `simulator:start` rejects `--name` (e.g. `Nonexistent flag: --name`) | `eas-cli` too old — `--name` was added after `simulator:start` itself | Run via `npx --yes eas-cli@latest …`, or upgrade `eas-cli`. If you can't upgrade, retry once **without** `--name`; the session starts unnamed. |
 | `An Expo user account is required` / `whoami` shows logged-out | No browser login on a cloud/CI/headless box, or `EXPO_TOKEN` unset/invalid | Set **`EXPO_TOKEN`** (expo.dev → Account → Access Tokens) in the env; verify `npx --yes eas-cli@latest whoami`. (Interactive machines can `eas login`.) |
 | `simulator:start`/`build`: no linked project / missing `projectId` | A fresh `create-expo-app` isn't linked to EAS | `npx --yes eas-cli@latest init` to create/link it (writes `extra.eas.projectId`). |
 | `prebuild`/`eas build` prompts for or fails on a missing **iOS bundle identifier** | A fresh app often has no `ios.bundleIdentifier` | Set it in app config (e.g. `dev.<owner>.<slug>`); confirm via `npx expo config --json` (may live in `app.config.js`). |
-| `--max-duration-minutes` rejected, or `simulator:start` denied / not-allowlisted / quota error | The flag is **paid-plan only**, or the experimental feature isn't enabled for the account | Drop `--max-duration-minutes` for the default; check the plan / that EAS Simulator is enabled for the account. |
+| `--max-duration-minutes` rejected | The flag is **paid-plan only** | Drop `--max-duration-minutes` to use the default. |
+| `simulator:start` fails with `not enabled for this account` / not-allowlisted | EAS Simulator is limited-access and isn't enabled for this account | Don't retry. Confirm with `simulator:availability`, then hand off gracefully — tell the user and fall back to a local sim / EAS Build (see SKILL.md *Check availability first*). |
 | `start` keeps "Waiting for … session to be ready" but it never returns | `start`'s readiness poll can miss a session that's actually live | Don't rely on it — poll `npx --yes eas-cli@latest simulator:get --id <id> --json` for `status: IN_PROGRESS` + a populated `remoteConfig`. |
 | `ERR_NGROK_3200` / endpoint offline; `Remote daemon is unavailable` | The session's tunnel/daemon dropped — left idle and timed out, or the VM was torn down | A drop invalidates the **whole** session (installed app, `@e` refs, Metro). **Don't retry the failed verb** — start a fresh session, reset the dotenv, and re-run install→open→drive from the top, acting immediately. |
-| Two sessions running / orphaned session / surprise double billing | A second `start` (e.g. to "retry" a slow boot) creates a second billed session and overwrites the dotenv id, orphaning the first | Never `start` again to retry — poll the existing session instead. Find orphans with `simulator:list --status IN_PROGRESS` and stop each with `simulator:stop --id <id>`. |
-| A device verb hangs (no return for a minute+) | Slow daemon; `press`/`screenshot` can block ~90s | Wrap verbs in `timeout 120 …`; on timeout `snapshot -i` to see if the action landed before retrying (taps can double-fire). Don't blind-retry. |
+| Two sessions running / orphaned session / surprise double billing | A second `start` (e.g. to "retry" a slow boot) creates a second billed session and overwrites the dotenv id, orphaning the first | Never `start` again to retry — poll the existing session instead. Find orphans with `simulator:list --status in-progress` and stop each with `simulator:stop --id <id>`. |
+| A device verb hangs (no return for a minute+) | Slow daemon; `press`/`screenshot` can block ~90s | Bound it with agent-device's own `--timeout <ms>` (e.g. `--timeout 120000`) — **not** a shell `timeout` wrapper (macOS has no `timeout` binary, so `timeout 120 …` fails with `command not found` and skips the verb). On timeout `snapshot -i` to see if the action landed before retrying (taps can double-fire). Don't blind-retry. |
 | `install requires an active session or an explicit device selector` | `install` can't infer the device | Pass `--platform ios` (or `open` something first to establish a session). |
 | `Unknown command: tap` | The tap verb is `press` | Use `press <ref\|selector>` (e.g. `press @e2` or `press 'label="Open"'`). |
 | `SESSION_NOT_FOUND: No active session. Run open first.` | A verb (e.g. `screenshot`) ran before any app/session was opened | `open <app\|url>` first (or pass `--platform ios`). |
@@ -23,12 +25,13 @@ Concrete errors seen while validating this flow, and the fix.
 | (Mode C) Deep-link `open` lands on the dev-client launcher, not the app | Opening the deep link triggers a system "Open in '<app>'?" dialog; and the launcher only auto-discovers Metro on the LAN | `press 'label="Open"'` to dismiss the dialog, then "Enter URL manually" → `fill` the `https://<host>.on.expo.app` manifest URL → "Connect". |
 | (Mode C) App shows expo-router "Unmatched Route" | The connect URL was parsed as a route path | `press 'label="Go back"'` (or navigate to `/`). |
 | (Mode C) Dev client shows a `?` placeholder / blank after connect | Bundle not fetched yet | `press 'label="Reload"'` and wait ~40-60s for the first build+transfer over the tunnel. |
-| (Mode C) `expo start` fails: "port 8081 already in use" | A Metro is already bound to 8081 (often one from earlier in the session) | Don't relaunch onto it. Reuse if it's yours (`curl -sf localhost:8081/status`), else free it (`PIDS=$(lsof -ti:8081); [ -n "$PIDS" ] && kill $PIDS`) then start one. There is only ever one Metro. |
+| (Mode C) `expo start` fails: "port 8081 already in use" | Something already owns that port (often another Metro) | Don't kill it — start on another port (`--port <N>`, e.g. 8082). Each `expo start --tunnel` gets its own tunnel URL, so ports coexist. Only reuse a running Metro if you started it this session. |
 | (Mode C) `expo start` / `node` killed with **exit 137** | 137 = SIGKILL — almost always the **OOM killer** (memory pressure, common in constrained cloud sandboxes, esp. a native build + Metro at once). **Not** a port clash. | Reduce memory pressure: don't run a native build and Metro concurrently; give the sandbox more memory; retry. |
 | (Mode C) Edits won't live-reload no matter how often you reconnect | A **release** build is installed — its JS is baked in, so it ignores Metro | Stop reconnecting: **install the dev (Debug) build**, connect it to Metro, reload. Reconnecting a release build to Metro is a no-op. |
 | `expo start --tunnel` errors for a robot/`EXPO_TOKEN` user | The ngrok robot-user guard | Use tunnel v2: `EXPO_UNSTABLE_TUNNEL_V2=1 expo start --tunnel`. |
 | Unexpected charges / a session you forgot | `start --non-interactive` does NOT auto-stop | Always `npx --yes eas-cli@latest simulator:stop --id <id>`. List leftovers with `npx --yes eas-cli@latest simulator:list`. |
 | Screenshot shows **old content** / my recent edits don't appear | Running a **release build (Mode A/B)** whose JS was baked in *before* your edits — typically a reused/stale build | A/B reflect code at build time, not now. **Rebuild** (ensure the build's fingerprint matches current source), or use **Mode C** (dev + Metro) so live edits show via Fast Refresh. The screenshot itself is fresh — it's the build that's stale. (`9:41` in the status bar is the sim default, not staleness.) |
+| (argent) Every `argent run`/`tools` call returns `401 Unauthorized` right after linking | `argent link` without `--yes` no-ops on an already-linked URL ("Already linked. No changes."), keeping a stale token from a previous session | Re-link with `--yes` so the new token is written — see the link command in [controllers.md](./controllers.md). |
 
 ## Performance expectations
 

package/dist/global-skills/eas-update-insights/SKILL.md

@@ -228,3 +228,11 @@ Human-readable group details plus 30 days of launches/failures per platform —
 - **Fresh publishes** may show zeros for a short period while the metrics pipeline catches up.
 - **Installs are downloads, not launches**: the `installs` / "Launches" field counts users who downloaded the manifest and launch asset. A confirmed run only registers on the user's *next* update check (typically up to 24h later, depending on the app's update policy). So metrics lag the real-world state slightly.
 - **Crashes are self-reported**: `failedInstalls` / "Crashes" counts updates that errored during install/launch and were reported on the next update check. Crashes that don't trigger an update request (e.g. process kill before recovery) won't appear.
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "eas-update-insights" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

package/dist/global-skills/eas-workflows/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: eas-workflows
 description: EAS service (paid). Helps understand and write EAS workflow YAML files for Expo projects. Use this skill when the user asks about CI/CD or workflows in an Expo or EAS context, mentions .eas/workflows/, or wants help with EAS build pipelines or deployment automation.
-allowed-tools: "Read,Write,Bash(node:*)"
+allowed-tools: "Read,Write,Bash(node:*),Bash(npx *eas-cli@*)"
 version: 1.0.0
 license: MIT License
 ---
@@ -14,7 +14,7 @@ Help developers write and edit EAS CI/CD workflow YAML files.
 
 ## Reference Documentation
 
-Fetch these resources before generating or validating workflow files. First resolve this skill's directory, then use the fetch script in its `scripts/` directory. It is implemented using Node.js and caches responses using ETags for efficiency:
+Fetch these resources before generating or editing workflow files, or when answering syntax questions. First resolve this skill's directory, then use the fetch script in its `scripts/` directory. It is implemented using Node.js and caches responses using ETags for efficiency:
 
 ```bash
 # Fetch resources
@@ -23,7 +23,7 @@ node <skill-dir>/scripts/fetch.js <url>
 
 1. **JSON Schema** — https://api.expo.dev/v2/workflows/schema
    - It is NECESSARY to fetch this schema
-   - Source of truth for validation
+   - Source of truth for the workflow YAML structure; EAS CLI remains the authoritative final validator
    - All job types and their required/optional parameters
    - Trigger types and configurations
    - Runner types, VM images, and all enums
@@ -41,7 +41,7 @@ Do not rely on memorized values; these resources evolve as new features are adde
 
 ## Workflow File Location
 
-Workflows live in `.eas/workflows/*.yml` (or `.yaml`).
+Workflows live in `.eas/workflows/*.yml` (or `.yaml`). Each file must be 16 KiB or smaller.
 
 ## Top-Level Structure
 
@@ -78,17 +78,22 @@ When generating or editing workflows:
 
 ## Validation
 
-After generating or editing a workflow file, validate it against the schema:
+After generating or editing a workflow file, validate it with EAS CLI from the Expo project root:
 
 ```sh
-# Install dependencies if missing
-[ -d "<skill-dir>/scripts/node_modules" ] || npm install --prefix <skill-dir>/scripts
-
-node <skill-dir>/scripts/validate.js <workflow.yml> [workflow2.yml ...]
+npx -y eas-cli@latest workflow:validate .eas/workflows/<workflow.yml> --non-interactive
 ```
 
-The validator fetches the latest schema and checks the YAML structure. Fix any reported errors before considering the workflow complete.
+Run the command separately for each changed workflow file. It requires a logged-in EAS CLI session and a linked Expo project. Unlike schema-only validation, it also checks build profile references against the project's `eas.json` and performs EAS server-side validation. Fix every reported error and rerun the command until it prints `Workflow configuration YAML is valid.` Do not replace this command with a local YAML or JSON Schema validator.
 
 ## Answering Questions
 
 When users ask about available options (job types, triggers, runner types, etc.), fetch the schema and derive the answer from it rather than relying on potentially outdated information.
+
+## Submitting Feedback
+If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
+```bash
+npx --yes submit-expo-feedback@latest --category skills --subject "eas-workflows" "<actionable feedback>"
+```
+Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
+If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

package/dist/global-skills/eas-workflows/scripts/package.json

@@ -1,11 +1,6 @@
 {
-  "name": "@expo/cicd-workflows-skill",
+  "name": "@expo/eas-workflows-skill",
   "version": "0.0.0",
   "private": true,
-  "type": "module",
-  "dependencies": {
-    "ajv": "^8.17.1",
-    "ajv-formats": "^3.0.1",
-    "js-yaml": "^4.1.0"
-  }
+  "type": "module"
 }

package/dist/global-skills/email-best-practices/.github/workflows/sync-skills.yml

@@ -0,0 +1,30 @@
+name: Sync Skills
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'SKILL.md'
+      - 'references/**'
+      - 'scripts/**'
+      - 'assets/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger sync on resend-skills
+        env:
+          GH_TOKEN: ${{ secrets.SYNC_SKILLS_TO_RESEND_SKILLS }}
+        run: |
+          gh workflow run sync-from-repo.yml \
+            --repo resend/resend-skills \
+            --field repo=email-best-practices \
+            --field skill-path=. \
+            --field skill-name=email-best-practices \
+            --field sha=${{ github.sha }} \
+            --field reviewer=${{ github.actor }}

package/dist/global-skills/email-best-practices/README.md

@@ -0,0 +1,63 @@
+```
+  ╔══════════════════════════════════════╗
+  ║   _____ __  __    _    ___ _         ║
+  ║  | ____|  \/  |  / \  |_ _| |        ║
+  ║  |  _| | |\/| | / _ \  | || |        ║
+  ║  | |___| |  | |/ ___ \ | || |___     ║
+  ║  |_____|_|  |_/_/   \_\___|_____|    ║
+  ║                                      ║
+  ║           Best Practices             ║
+  ╚══════════════════════════════════════╝
+```
+
+# Email Best Practices Skill
+
+A comprehensive agent skill for building production-ready email systems. Covers everything from DNS authentication to webhook processing, with a focus on deliverability, compliance, and reliability.
+
+## Installation
+
+```bash
+npx skills add resend/email-best-practices
+```
+
+## What This Skill Covers
+
+**Getting Started**
+- Planning which emails your app needs (password reset, verification, order confirmations)
+- Setting up email authentication (SPF, DKIM, DMARC) so emails reach inboxes
+
+**Sending Emails**
+- Transactional email design (subject lines, content structure, mobile-first)
+- Marketing email best practices (consent, segmentation, unsubscribe)
+- Compliance requirements by region (CAN-SPAM, GDPR, CASL)
+
+**Production Infrastructure**
+- Idempotency and retry logic to prevent duplicates
+- Webhook processing for delivery events
+- Suppression lists and list hygiene automation
+
+## Structure
+
+```
+email-best-practices/
+├── SKILL.md                             # Start here - routes to the right resource
+└── references/
+    ├── deliverability.md                # SPF/DKIM/DMARC, sender reputation
+    ├── transactional-emails.md          # Password resets, OTPs, confirmations
+    ├── transactional-email-catalog.md   # Email combinations by app type
+    ├── marketing-emails.md              # Newsletters, campaigns, consent
+    ├── email-capture.md                 # Validation, verification, opt-in
+    ├── compliance.md                    # CAN-SPAM, GDPR, CASL
+    ├── email-types.md                   # Transactional vs marketing
+    ├── sending-reliability.md           # Idempotency, retry logic, errors
+    ├── webhooks-events.md               # Delivery events, webhook setup
+    └── list-management.md               # Suppression lists, hygiene
+```
+
+## Quick Start
+
+Open `SKILL.md` - it has a routing table that directs you to the right resource based on what you need to do.
+
+## License
+
+MIT

package/dist/global-skills/email-best-practices/references/accessibility.md

@@ -0,0 +1,189 @@
+# Email Accessibility
+
+Emails must be readable by screen readers, dark-mode clients, translation tools, and AI agents — not just sighted readers on a default inbox. The rules below are mechanical. Apply them every time.
+
+## Rules
+
+### Set `lang` and `dir` on `<html>` and on `<body>`'s direct children (Serious)
+
+Both attributes are needed in **two places**: on `<html>` *and* on the direct children of `<body>`. Several email clients strip the attributes from `<html>`, which is why duplicating them on the body's children is the single most common accessibility failure in production email.
+
+```html
+<html lang="en" dir="ltr">
+  <head>
+    <title>Your weekly product updates</title>
+  </head>
+  <body>
+    <div lang="en" dir="ltr">
+      <!-- email content -->
+    </div>
+  </body>
+</html>
+```
+
+- `lang`: a [BCP 47 language tag](https://developer.mozilla.org/en-US/docs/Glossary/BCP_47_language_tag) (`en`, `pt-BR`, `ja`, `ar`)
+- `dir`: `ltr`, `rtl`, or `auto`
+
+**Fallbacks when the correct values aren't available** (use only when you genuinely don't know):
+
+- `dir="auto"` — lets the user agent infer direction from content
+- `lang="und"` — marks the language as undetermined
+
+Both fallbacks are worse than the correct value but much better than nothing. For multi-locale templates, pass the locale through; do not hardcode `en`.
+
+### Mark layout tables as presentational (Serious)
+
+Any `<table>` used for layout must have `role="presentation"` (or the equivalent `role="none"`). Otherwise screen readers announce "table, row 1 of N" for every layout row and the email becomes unusable. Prefer avoiding layout tables entirely; when you can't, mark them.
+
+```html
+<table role="presentation" cellpadding="0" cellspacing="0" border="0">
+  <tr>
+    <td>...</td>
+  </tr>
+</table>
+```
+
+Leave a `<table>` without `role="presentation"` only when the data is genuinely tabular (line items, comparison rows). Tabular data should also use `<th scope="col">` for column headers.
+
+### Use a single `<h1>` and nest headings in order (Mild)
+
+Most emails should have one `<h1>` that names the email, with subheadings nested in order:`<h1>` → `<h2>` → `<h3>`. Never skip levels. Never fake a heading with bold `<p>`.
+
+```html
+<h1>Order confirmation</h1>
+  <h2>Items</h2>
+  <h2>Shipping</h2>
+    <h3>Address</h3>
+    <h3>Tracking</h3>
+```
+
+Headings are how assistive tech and AI clients navigate and summarize the email.
+
+**Exception:** very short messages (SMS-style notifications, single-sentence alerts) may not need a heading at all. If the email body is one or two sentences, skip the `<h1>` rather than wrap a heading around the only content.
+
+### Every link must have discernible text (Serious)
+
+Every `<a>` must contain text content that a screen reader can announce. The most common failure is a linked image with no alt text.
+
+A **linked image is never decorative.** It's functional, so its `alt` must describe what clicking does, not just what the image looks like.
+
+```html
+<!-- Wrong: linked image with no accessible name -->
+<a href="/order/123">
+  <img src="view-order.png" alt="">
+</a>
+
+<!-- Right: alt describes the action -->
+<a href="/order/123">
+  <img src="view-order.png" alt="View order #123">
+</a>
+
+<!-- Also right: visible text alongside the image -->
+<a href="/order/123">
+  <img src="icon.png" alt="">
+  View order #123
+</a>
+```
+
+When the visible link text can't carry enough information, add visually hidden text inside the `<a>` (see [goodemailcode.com/email-accessibility/visually-hidden-text](https://www.goodemailcode.com/email-accessibility/visually-hidden-text)). `aria-label` and `title` on `<a>` have limited support in email clients. Prefer real text content or visually hidden text.
+
+### Link text must describe the destination (Moderate)
+
+Even when a link has text, it must describe where the link goes. Never use "click here," "learn more," "read more," or bare URLs. Screen reader users often navigate by jumping between link texts with no surrounding context.
+
+```html
+<!-- Wrong -->
+<a href="...">click here</a>
+<a href="...">https://resend.com/blog/...</a>
+
+<!-- Right -->
+<a href="...">Read the 2026 accessibility report</a>
+```
+
+### Write meaningful alt text — and use `alt=""` for decorative images (Critical)
+
+Two distinct rules, both mandatory. `alt` must always be present; the value depends on the image's role.
+
+**Meaningful images** (product shots, charts, screenshots, anything carrying information): describe purpose and key details in context.
+
+```html
+<!-- Wrong: redundant, vague -->
+<img src="..." alt="image">
+<img src="..." alt="photo of a bike">
+
+<!-- Right: purpose + key details -->
+<img src="..." alt="Red bicycle leaning against a brick wall on a rainy street">
+```
+
+**Decorative images** (spacers, dividers, background flourishes, pure branding ornaments): use an empty `alt=""`. This tells screen readers to skip them. Never omit the attribute entirely — omitting it and `alt=""` are not equivalent; some screen readers announce the filename when `alt` is absent.
+
+```html
+<img src="divider.png" alt="" role="presentation">
+```
+
+If an image conveys no information that isn't already in the surrounding text, it is decorative. If it's inside an `<a>`, it is **not** decorative — see the "Every link must have discernible text" rule.
+
+### Include a `<title>` tag (Serious)
+
+Many clients and assistive technologies read `<title>` before anything else. It's also shown when the email is viewed as a web page. Treat it like the subject line, not the brand name.
+
+```html
+<head>
+  <title>Your weekly product updates from Resend</title>
+</head>
+```
+
+If the per-email title is hard to populate, a generic but specific fallback like `"Email from {Brand Name}"` still beats nothing.
+
+### Hit 4.5:1 color contrast, then check dark mode (Serious)
+
+- Body text and links: **4.5:1** minimum against the background (WCAG AA)
+- Large text (≥18pt, or ≥14pt bold): **3:1** minimum
+- Never rely on color alone to convey meaning (error states, status badges) — pair it with text or an icon
+
+Verify with the [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) or browser devtools.
+
+**Dark mode.** Outlook, Apple Mail, and others force dark mode and derive dark colors from your light ones. Healthy starting contrast keeps the auto-inverted version readable. Always preview in dark mode before shipping.
+
+## Priority order
+
+When you can't fix everything, fix in this order:
+
+1. **Critical** — missing or misused `alt` on images
+2. **Serious** — `lang`/`dir` (on `<html>` and body children), `role="presentation"` on layout tables, links without discernible text, missing `<title>`, color contrast
+3. **Moderate** — non-descriptive link text ("click here")
+4. **Mild** — missing `<h1>` (skip the fix for very short messages)
+
+## Authoring checklist
+
+Run this on every template:
+
+- [ ] `<html>` has `lang` and `dir`; direct children of `<body>` also have `lang` and `dir`
+- [ ] `<title>` set on `<head>`, specific to this email (not the brand name)
+- [ ] Layout `<table>` elements have `role="presentation"` (or `role="none"`)
+- [ ] At most one `<h1>` (or none, for very short messages); `<h2>`/`<h3>` nested in order
+- [ ] Every `<a>` has discernible text — visible text, descriptive alt on linked images, or visually hidden text
+- [ ] Every link describes its destination — no "click here," "learn more," or bare URLs
+- [ ] Every meaningful image has descriptive `alt`; every decorative image has an explicit `alt=""`
+- [ ] No linked image with `alt=""` (linked images are functional, never decorative)
+- [ ] Body text passes 4.5:1 contrast and stays readable in dark mode
+- [ ] Plain-text alternative is sent alongside the HTML version
+
+## Testing
+
+- **Automated.** Run the email through [Parcel's accessibility checker](https://parcel.io/docs/dev-tools/accessibility-checker) (the same tool the EMC report uses; available on the free plan). It catches most of the rules above.
+- **Screen reader pass.** macOS VoiceOver (`Cmd+F5`) or NVDA on Windows. Listen top to bottom; if anything is confusing, fix the markup.
+- **Contrast.** [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/).
+- **Dark mode.** Send a test to Outlook (Windows/web), Apple Mail with dark appearance, Gmail iOS and Android.
+
+Automated tests do not catch everything. They will not tell you whether alt text actually matches the image, whether headings make semantic sense, or whether text inside an image is readable on narrow viewports. Even the three brands that passed every automated check in the EMC 2026 report had judgment-level issues like generic alt text on decorative images, alt text that didn't match the image, and 10px footer text. Treat automation as a floor, not a ceiling.
+
+## Related
+
+- [Transactional Emails](./transactional-emails.md) — content patterns for password resets, OTPs, receipts
+- [Marketing Emails](./marketing-emails.md) — newsletter and campaign best practices
+- [Compliance](./compliance.md) — legal requirements that overlap with accessibility (e.g., clear unsubscribe text)
+
+## Tooling
+
+When generating templates with React Email, the latest version handles several of the structural rules: `<Html>` sets `lang`/`dir`, `<Img>` defaults to `alt=""`, `<Markdown>` tables render `role="presentation"`, and `<Preview>` emits a `<title>`. Upgrade with `npm install react-email@latest`. The content rules — heading hierarchy, descriptive alt and link text, contrast, the linked-image rule — still have to be applied by hand.

package/dist/global-skills/email-best-practices/references/compliance.md

@@ -0,0 +1,125 @@
+# Email Compliance
+
+Legal requirements for email by jurisdiction. **Not legal advice—consult an attorney for your specific situation.**
+
+## Quick Reference
+
+| Law | Region | Key Requirement | Penalty |
+|-----|--------|-----------------|---------|
+| CAN-SPAM | US | Opt-out mechanism, physical address | $53k/email |
+| GDPR | EU | Explicit opt-in consent | €20M or 4% revenue |
+| CASL | Canada | Express consent, opt-out mechanism | $1M (individual) to $10M (organization) CAD |
+
+## CAN-SPAM (United States)
+
+**Requirements:**
+- Accurate header info (From, To, Reply-To)
+- Non-deceptive subject lines
+- Physical mailing address in every email
+- Clear opt-out mechanism
+- Honor opt-out within 10 business days
+
+**Transactional emails:** Can send without opt-in if related to a transaction and not promotional.
+
+## GDPR (European Union)
+
+**Requirements:**
+- Explicit opt-in consent (not pre-checked boxes)
+- Consent must be freely given, specific, informed
+- Easy to withdraw consent (as easy as giving it)
+- Right to access data and deletion ("right to be forgotten")
+- Process unsubscribe immediately
+
+**Consent records:** Document who, when, how, and what they consented to.
+
+**Transactional emails:** Can send based on contract fulfillment or legitimate interest.
+
+## CASL (Canada)
+
+**Consent types:**
+- **Express consent:** Explicit opt-in (ideal)
+- **Implied consent:** Existing business relationship (2 years) or inquiry (6 months)
+
+**Requirements:**
+- Clear sender identification that will be valid for 60 days after send
+- Unsubscribe functional for 60 days after send
+- Process unsubscribe no later than 10 business days
+- Keep consent records 3 years after expiration
+
+## Other Regions
+
+| Region | Law | Key Points |
+|--------|-----|------------|
+| Australia | Spam Act 2003 | Consent required, honor unsubscribe within 5 days |
+| UK | PECR + GDPR | Same as GDPR |
+| Brazil | LGPD | Similar to GDPR, explicit consent for marketing |
+
+## Unsubscribe Requirements Summary
+
+| Law | Timing | Notes |
+|-----|--------|-------|
+| CAN-SPAM | 10 business days | Must work 30 days after send |
+| GDPR | Immediately | Must be as easy as opting in |
+| CASL | 10 business days | Must work 60 days after send |
+
+**Universal best practices:** Prominent link, one-click when possible, no login required, free, confirm action.
+
+### List-Unsubscribe Header (Required for Bulk Senders)
+
+Gmail, Yahoo, and Microsoft require `List-Unsubscribe` headers. Without them, bulk emails may be rejected or spam-filtered.
+
+**Required headers:**
+
+```typescript
+headers: {
+  'List-Unsubscribe': '<https://example.com/unsubscribe>',
+  'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
+}
+```
+
+**Your unsubscribe endpoint must:**
+- Accept POST requests — return `200` or `202` with a blank page
+- Display standard unsubscribe page for GET requests
+- Stop sending within 48 hours of the request
+
+## Managing preferences vs Unsubscribe from all
+
+Most legistlations require a one-click unsubscribe. `Managing preferences` is a nice-to-have and can lead to lower unsubscribe rate but doesn't replace `Unsubscribe`. If possible, offer both.
+
+## Consent Management
+
+**Record:**
+- Email address
+- Date/time of consent
+- Method (form, checkbox)
+- What they consented to
+- Source (which page/form)
+
+**Storage:** Database with timestamps, audit trail of changes, link to user account.
+
+## Data Retention
+
+| Law | Requirement |
+|-----|-------------|
+| GDPR | Keep only as long as necessary, delete when no longer needed |
+| CASL | Keep consent records 3 years after expiration |
+
+**Best practice:** Have clear retention policy, honor deletion requests promptly, review and clean regularly.
+
+## Privacy Policy Must Include
+
+- What data you collect
+- How you use data
+- Who you share data with
+- User rights (access, deletion)
+- How to contact about privacy
+
+## International Sending
+
+**Best practice:** Follow the most restrictive requirements (usually GDPR) to ensure compliance across all regions.
+
+## Related
+
+- [Email Capture](./email-capture.md) - Implement consent forms and double opt-in
+- [Marketing Emails](./marketing-emails.md) - Consent and unsubscribe requirements
+- [List Management](./list-management.md) - Handle unsubscribes and deletion requests