@ivannxbt/ai-config 0.1.0

package/.agents/skills/email-best-practices/resources/transactional-email-catalog.md

@@ -0,0 +1,418 @@
+# Transactional Email Catalog
+
+A comprehensive catalog of transactional emails organized by category, plus recommended email combinations for different app types.
+
+## When to Use This
+
+- Planning what transactional emails your app needs
+- Choosing the right emails for your app type
+- Understanding what content each email type should include
+- Implementing transactional email features
+
+## Email Combinations by App Type
+
+Use these combinations as a starting point based on what you're building.
+
+### Authentication-Focused App
+
+Apps where user accounts and security are core (login systems, identity providers, account management).
+
+**Essential:**
+- Email verification
+- Password reset
+- OTP / 2FA codes
+- Security alerts (new device, password change)
+- Account update notifications
+
+**Optional:**
+- Welcome email (must not be promotional)
+- Account deletion confirmation
+
+### Newsletter / Content Platform
+
+Apps focused on content delivery and subscriptions.
+
+**Essential:**
+- Email verification
+- Password reset
+- Welcome email (must not be promotional)
+- Subscription confirmation
+
+**Optional:**
+- OTP / 2FA codes
+- Account update notifications
+
+### E-commerce / Marketplace
+
+Apps where users buy products or services.
+
+**Essential:**
+- Email verification
+- Password reset
+- Welcome email (must not be promotional)
+- Order confirmation
+- Shipping notifications
+- Invoice / receipt
+- Payment failed notices
+
+**Optional:**
+- OTP / 2FA codes
+- Security alerts
+- Subscription confirmations (for recurring orders)
+
+### SaaS / Subscription Service
+
+Apps with paid subscription tiers and ongoing billing.
+
+**Essential:**
+- Email verification
+- Password reset
+- Welcome email (must not be promotional)
+- OTP / 2FA codes
+- Security alerts
+- Subscription confirmation
+- Subscription renewal notice
+- Payment failed notices
+- Invoice / receipt
+
+**Optional:**
+- Account update notifications
+- Feature change notifications (for breaking changes)
+
+### Financial / Fintech App
+
+Apps handling money, payments, or sensitive financial data.
+
+**Essential:**
+- Email verification
+- Password reset
+- OTP / 2FA codes (required for sensitive actions)
+- Security alerts (all types)
+- Account update notifications
+- Transaction confirmations
+- Invoice / receipt
+- Payment failed notices
+
+**Optional:**
+- Welcome email (must not be promotional)
+- Compliance notices
+
+### Social / Community Platform
+
+Apps focused on user interaction and community features.
+
+**Essential:**
+- Email verification
+- Password reset
+- Welcome email (must not be promotional)
+- Security alerts
+
+**Optional:**
+- OTP / 2FA codes
+- Account update notifications
+- Activity notifications (mentions, replies)
+
+### Developer Tools / API Platform
+
+Apps targeting developers with API access and integrations.
+
+**Essential:**
+- Email verification
+- Password reset
+- OTP / 2FA codes
+- Security alerts
+- API key notifications (creation, expiration)
+- Subscription confirmation
+- Payment failed notices
+
+**Optional:**
+- Welcome email (must not be promotional)
+- Usage alerts (approaching limits)
+- Feature change notifications
+
+### Healthcare / HIPAA-Compliant App
+
+Apps handling protected health information.
+
+**Essential:**
+- Email verification
+- Password reset
+- OTP / 2FA codes (required)
+- Security alerts (all types, detailed)
+- Account update notifications
+- Appointment confirmations
+
+**Optional:**
+- Welcome email (must not be promotional)
+- Compliance notices
+
+**Note:** Healthcare apps have strict requirements. Emails should contain minimal PHI and link to secure portals for sensitive information.
+
+---
+
+## Full Email Catalog
+
+### Authentication & Security
+
+#### Email Verification / Account Verification
+
+**When to send:** Immediately after user signs up or changes email address.
+
+**Purpose:** Verify the email address belongs to the user.
+
+**Content should include:**
+- Clear verification link or code
+- Expiration time (typically 24-48 hours)
+- Instructions on what to do
+- Security notice if link is clicked by mistake
+
+**Best practices:**
+- Send immediately (within seconds)
+- Include expiration notice
+- Provide resend option
+- Link to support if issues
+
+#### OTP / 2FA Codes
+
+**When to send:** When user requests two-factor authentication code.
+
+**Purpose:** Provide time-sensitive authentication code.
+
+**Content should include:**
+- The OTP code (clearly displayed)
+- Expiration time (typically 5-10 minutes)
+- Security warnings
+- Instructions on what to do if not requested
+
+**Best practices:**
+- Send immediately
+- Code should be large and easy to read
+- Include expiration prominently
+- Warn about sharing codes
+- Provide "I didn't request this" link
+
+#### Password Reset
+
+**When to send:** When user requests password reset.
+
+**Purpose:** Allow user to securely reset forgotten password.
+
+**Content should include:**
+- Reset link (with token)
+- Expiration time (typically 1 hour)
+- Security warnings
+- Instructions if not requested
+
+**Best practices:**
+- Send immediately
+- Link expires quickly (1 hour)
+- Include IP address and location if available
+- Provide "I didn't request this" link
+- Don't include the old password
+
+#### Security Alerts
+
+**When to send:** When security-relevant events occur (login from new device, password change, etc.).
+
+**Purpose:** Notify user of account security events.
+
+**Content should include:**
+- What happened (clear description)
+- When it happened
+- Location/IP if available
+- Action to take if suspicious
+- Link to security settings
+
+**Best practices:**
+- Send immediately
+- Be clear and specific
+- Include actionable steps
+- Provide way to report suspicious activity
+
+### Account Management
+
+#### Welcome Email
+
+**When to send:** Immediately after successful account creation and verification.
+
+**Purpose:** Welcome new users and guide them to next steps (must not be promotional).
+
+**Content should include:**
+- Welcome message
+- Key features or next steps
+- Links to important resources
+- Support contact information
+
+**Best practices:**
+- Send after email verification
+- Keep it focused and actionable
+- Don't overwhelm with information
+- Set expectations about future emails
+
+#### Account Update Notifications
+
+**When to send:** When user changes account settings (email, password, profile, etc.).
+
+**Purpose:** Confirm account changes and provide security notice.
+
+**Content should include:**
+- What changed
+- When it changed
+- Action to take if unauthorized
+- Link to account settings
+
+**Best practices:**
+- Send immediately after change
+- Be specific about what changed
+- Include security notice
+- Provide easy way to revert if needed
+
+### E-commerce & Transactions
+
+#### Order Confirmations
+
+**When to send:** Immediately after order is placed.
+
+**Purpose:** Confirm order details and provide receipt.
+
+**Content should include:**
+- Order number
+- Items ordered with quantities
+- Pricing breakdown
+- Shipping address
+- Estimated delivery date
+- Order tracking link (if available)
+
+**Best practices:**
+- Send within minutes of order
+- Include all order details
+- Make it easy to print or save
+- Provide customer service contact
+
+#### Shipping Notifications
+
+**When to send:** When order ships, with tracking updates.
+
+**Purpose:** Notify user that order has shipped and provide tracking.
+
+**Content should include:**
+- Order number
+- Tracking number
+- Carrier information
+- Expected delivery date
+- Tracking link
+- Shipping address confirmation
+
+**Best practices:**
+- Send when order ships
+- Include tracking number prominently
+- Provide carrier tracking link
+- Update on major tracking milestones
+
+#### Invoices and Receipts
+
+**When to send:** After payment is processed.
+
+**Purpose:** Provide payment confirmation and receipt.
+
+**Content should include:**
+- Invoice/receipt number
+- Payment amount
+- Payment method
+- Items/services purchased
+- Payment date
+- Downloadable PDF (if applicable)
+
+**Best practices:**
+- Send immediately after payment
+- Include all payment details
+- Make it easy to download/save
+- Include tax information if applicable
+
+### Subscriptions & Billing
+
+#### Subscription Confirmations
+
+**When to send:** When user subscribes or changes subscription.
+
+**Purpose:** Confirm subscription details and billing information.
+
+**Content should include:**
+- Subscription plan details
+- Billing amount and frequency
+- Next billing date
+- Payment method
+- Link to manage subscription
+
+**Best practices:**
+- Send immediately after subscription
+- Clearly state billing terms
+- Provide easy cancellation option
+- Include support contact
+
+#### Subscription Renewal Notices
+
+**When to send:** Before subscription renews (typically 3-7 days before).
+
+**Purpose:** Notify user of upcoming renewal and charge.
+
+**Content should include:**
+- Renewal date
+- Amount to be charged
+- Payment method on file
+- Link to update payment method
+- Link to cancel if desired
+
+**Best practices:**
+- Send with enough notice (3-7 days)
+- Be clear about amount and date
+- Make it easy to update payment method
+- Provide cancellation option
+
+#### Payment Failed Notices
+
+**When to send:** When subscription payment fails.
+
+**Purpose:** Notify user of payment failure and provide resolution steps.
+
+**Content should include:**
+- What happened
+- Amount that failed
+- Reason for failure (if available)
+- Steps to resolve
+- Link to update payment method
+- Consequences if not resolved
+
+**Best practices:**
+- Send immediately after failure
+- Be clear about consequences
+- Provide easy resolution path
+- Include support contact
+
+### Notifications & Updates
+
+#### Feature Announcements (Transactional)
+
+**When to send:** When a feature the user is using changes significantly.
+
+**Purpose:** Notify users of changes that affect their use of the service.
+
+**Content should include:**
+- What changed
+- How it affects the user
+- What action (if any) is needed
+- Link to more information
+
+**Best practices:**
+- Only for significant changes
+- Focus on user impact
+- Provide clear next steps
+- Link to documentation
+
+**Note:** General feature announcements are marketing emails. Only send as transactional if the change directly affects an active feature the user is using.
+
+## Related Topics
+
+- [Email Types](./email-types.md) - Understanding transactional vs marketing
+- [Transactional Emails](./transactional-emails.md) - Best practices for sending transactional emails
+- [Compliance](./compliance.md) - Legal requirements for each email type

package/.agents/skills/email-best-practices/resources/transactional-emails.md

@@ -0,0 +1,92 @@
+# Transactional Email Best Practices
+
+Clear, actionable emails that users expect and need—password resets, confirmations, OTPs.
+
+## Core Principles
+
+1. **Clarity over creativity** - Users need to understand and act quickly
+2. **Action-oriented** - Clear purpose, obvious primary action
+3. **Time-sensitive** - Send immediately (within seconds)
+
+## Subject Lines
+
+**Be specific and include context:**
+
+| ✅ Good | ❌ Bad |
+|---------|--------|
+| Reset your password for [App] | Action required |
+| Your order #12345 has shipped | Update on your order |
+| Your 2FA code for [App] | Security code: 12345 |
+| Verify your email for [App] | Verify your email |
+
+Include identifiers when helpful: order numbers, account names, expiration times.
+
+## Pre-Header
+
+The text snippet after subject line. Use it to:
+- Reinforce subject ("This link expires in 1 hour")
+- Add urgency or context
+- Call-to-action preview
+
+Keep under 90 characters.
+
+## Content Structure
+
+**Above the fold (first screen):**
+- Clear purpose
+- Primary action button
+- Time-sensitive details (expiration)
+
+**Hierarchy:** Header → Primary message → Details → Action button → Secondary info
+
+**Format:** Short paragraphs (2-3 sentences), bullet points, bold for emphasis, white space.
+
+## Mobile-First Design
+
+60%+ emails are opened on mobile.
+
+- **Layout:** Single column, stack vertically
+- **Buttons:** 44x44px minimum, full-width on mobile
+- **Text:** 16px minimum body, 20-24px headings
+- **OTP codes:** 24-32px, monospace font
+
+## Sender Configuration
+
+| Field | Best Practice | Example |
+|-------|--------------|---------|
+| From Name | App/company name, consistent | [App Name] |
+| From Email | Subdomain, real address | hello@mail.yourdomain.com |
+| Reply-To | Monitored inbox | support@yourdomain.com |
+
+Avoid `noreply@` - users reply to transactional emails.
+
+## Code and Link Display
+
+**OTP/Verification codes:**
+- Large (24-32px), monospace font
+- Centered, clear label
+- Include expiration nearby
+- Make copyable
+
+**Buttons:**
+- Large, tappable (44x44px+)
+- Contrasting colors
+- Clear action text ("Reset Password", "Verify Email")
+- HTTPS links only
+
+## Error Handling
+
+**Resend functionality:**
+- Allow after 60 seconds
+- Limit attempts (3 per hour)
+- Show countdown timer
+
+**Expired links:**
+- Clear "expired" message
+- Offer to send new link
+- Provide support contact
+
+**"I didn't request this":**
+- Include in password resets, OTPs, security alerts
+- Link to security contact
+- Log clicks for monitoring

package/.agents/skills/email-best-practices/resources/webhooks-events.md

@@ -0,0 +1,167 @@
+# Webhooks and Events
+
+Receiving and processing email delivery events in real-time.
+
+## Event Types
+
+| Event | When Fired | Use For |
+|-------|------------|---------|
+| `email.sent` | Email accepted by Resend | Confirming send initiated |
+| `email.delivered` | Email delivered to recipient server | Confirming delivery |
+| `email.bounced` | Email bounced (hard or soft) | List hygiene, alerting |
+| `email.complained` | Recipient marked as spam | Immediate unsubscribe |
+| `email.opened` | Recipient opened email | Engagement tracking |
+| `email.clicked` | Recipient clicked link | Engagement tracking |
+
+## Webhook Setup
+
+### 1. Create Endpoint
+
+Your endpoint must:
+- Accept POST requests
+- Return 2xx status quickly (within 5 seconds)
+- Handle duplicate events (idempotent processing)
+
+```typescript
+app.post('/webhooks/resend', async (req, res) => {
+  // Return 200 immediately to acknowledge receipt
+  res.status(200).send('OK');
+
+  // Process asynchronously
+  processWebhookAsync(req.body).catch(console.error);
+});
+```
+
+### 2. Verify Signatures
+
+Always verify webhook signatures to prevent spoofing.
+
+```typescript
+import { Webhook } from 'svix';
+
+const webhook = new Webhook(process.env.RESEND_WEBHOOK_SECRET);
+
+app.post('/webhooks/resend', (req, res) => {
+  try {
+    const payload = webhook.verify(
+      JSON.stringify(req.body),
+      {
+        'svix-id': req.headers['svix-id'],
+        'svix-timestamp': req.headers['svix-timestamp'],
+        'svix-signature': req.headers['svix-signature'],
+      }
+    );
+    // Process verified payload
+  } catch (err) {
+    return res.status(400).send('Invalid signature');
+  }
+});
+```
+
+### 3. Register Webhook URL
+
+Configure your webhook endpoint in the Resend dashboard or via API.
+
+## Processing Events
+
+### Bounce Handling
+
+```typescript
+async function handleBounce(event) {
+  const { email_id, email, bounce_type } = event.data;
+
+  if (bounce_type === 'hard') {
+    // Permanent failure - remove from all lists
+    await suppressEmail(email, 'hard_bounce');
+    await removeFromAllLists(email);
+  } else {
+    // Soft bounce - track and remove after threshold
+    await incrementSoftBounce(email);
+    const count = await getSoftBounceCount(email);
+    if (count >= 3) {
+      await suppressEmail(email, 'soft_bounce_limit');
+    }
+  }
+}
+```
+
+### Complaint Handling
+
+```typescript
+async function handleComplaint(event) {
+  const { email } = event.data;
+
+  // Immediate suppression - no exceptions
+  await suppressEmail(email, 'complaint');
+  await removeFromAllLists(email);
+  await logComplaint(event); // For analysis
+}
+```
+
+### Delivery Confirmation
+
+```typescript
+async function handleDelivered(event) {
+  const { email_id } = event.data;
+  await updateEmailStatus(email_id, 'delivered');
+}
+```
+
+## Idempotent Processing
+
+Webhooks may be sent multiple times. Use event IDs to prevent duplicate processing.
+
+```typescript
+async function processWebhook(event) {
+  const eventId = event.id;
+
+  // Check if already processed
+  if (await isEventProcessed(eventId)) {
+    return; // Skip duplicate
+  }
+
+  // Process event
+  await handleEvent(event);
+
+  // Mark as processed
+  await markEventProcessed(eventId);
+}
+```
+
+## Error Handling
+
+### Retry Behavior
+
+If your endpoint returns non-2xx, webhooks will retry with exponential backoff:
+- Retry 1: ~30 seconds
+- Retry 2: ~1 minute
+- Retry 3: ~5 minutes
+- (continues for ~24 hours)
+
+### Best Practices
+
+- **Return 200 quickly** - Process asynchronously to avoid timeouts
+- **Be idempotent** - Handle duplicate deliveries gracefully
+- **Log everything** - Store raw events for debugging
+- **Alert on failures** - Monitor webhook processing errors
+- **Queue for processing** - Use a job queue for complex handling
+
+## Testing Webhooks
+
+**Local development:** Use ngrok or similar to expose localhost.
+
+```bash
+ngrok http 3000
+# Use the ngrok URL as your webhook endpoint
+```
+
+**Verify handling:** Send test events through Resend dashboard or manually trigger each event type.
+
+## Ingest webhooks for data storage
+- [Open source repo](https://github.com/resend/resend-webhooks-ingester)
+- [Why store data](https://resend.com/docs/dashboard/webhooks/how-to-store-webhooks-data)
+
+## Related
+
+- [List Management](./list-management.md) - What to do with bounce/complaint data
+- [Sending Reliability](./sending-reliability.md) - Retry logic when sends fail

package/.agents/skills/email-best-practices/tests/README.md

@@ -0,0 +1,35 @@
+# Skill Tests
+
+Tests for the `email-best-practices` skill using the RED-GREEN methodology from [writing-skills](https://github.com/yourorg/writing-skills).
+
+## Skill Type
+
+This is a **reference/technique** skill (not discipline-enforcing), so tests focus on:
+
+- **Retrieval** — Does the agent find the right resource for a given problem?
+- **Application** — Does the agent produce correct, specific guidance?
+- **Gap** — Are common email scenarios adequately covered?
+
+## Test Scenarios
+
+| # | Scenario | Tests | Key Resource(s) |
+|---|----------|-------|-----------------|
+| 1 | Emails going to spam | Retrieval + Application | deliverability.md |
+| 2 | Multi-region compliance | Retrieval + Application | compliance.md |
+| 3 | Retry logic + idempotency | Application | sending-reliability.md |
+| 4 | Webhook bounce/complaint handling | Application | webhooks-events.md, list-management.md |
+| 5 | New SaaS email infrastructure | Retrieval + Application + Gap | All resources |
+
+## Running Tests
+
+Each scenario in `scenarios/` is a self-contained prompt. Run with a subagent:
+
+**RED (baseline):** Run the prompt as-is — no skill loaded. The agent uses only general knowledge.
+
+**GREEN (with skill):** Prepend: `You have access to an email best practices skill with resources in <path>. Read SKILL.md first, then read the relevant resource file(s).`
+
+Compare outputs against `results.md` for expected correctness criteria.
+
+## Results
+
+See `results.md` for the full RED vs GREEN comparison and gap analysis from the initial test campaign.