opencode-starterkit 1.0.1

package/baseline/skill/resend/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: resend
+description: Use when working with Resend email platform - sending transactional emails, receiving inbound emails, creating email templates with React Email, handling webhooks, or integrating email into applications.
+references:
+  - send-email
+  - receive-email
+  - react-email
+version: 1.0.0
+tags: [integration, mcp]
+dependencies: []
+---
+
+# Resend Email Platform
+
+## When to Use
+
+- When integrating Resend for sending/receiving emails or building React Email templates.
+
+## When NOT to Use
+
+- When email delivery is handled by a different provider or not required.
+
+
+## How to Use This Skill
+
+### Reference File Structure
+
+Each feature in `./references/` contains documentation for specific use cases:
+
+| File               | Purpose                      | When to Read                                   |
+| ------------------ | ---------------------------- | ---------------------------------------------- |
+| `send-email.md`    | Sending transactional emails | Single/batch sends, attachments, scheduling    |
+| `receive-email.md` | Receiving inbound emails     | Webhooks, processing received mail, forwarding |
+| `react-email.md`   | Building email templates     | React components, styling, rendering           |
+
+### Reading Order
+
+1. Start with this file for quick routing
+2. Then read the relevant reference file for your task
+
+## Quick Decision Tree
+
+### "I need to send emails"
+
+```
+Need to send emails?
+├─ Single email (transactional) → send-email.md
+├─ Batch emails (max 100) → send-email.md
+├─ Email with attachments → send-email.md (single only)
+├─ Scheduled emails → send-email.md (single only)
+├─ Marketing/bulk campaigns → Use Resend Broadcasts (dashboard)
+└─ AI agent sending emails → send-email.md + moltbot patterns
+```
+
+### "I need to receive emails"
+
+```
+Need to receive emails?
+├─ Set up inbound domain → receive-email.md
+├─ Process webhook events → receive-email.md
+├─ Get email body/content → receive-email.md (Receiving API)
+├─ Download attachments → receive-email.md
+├─ Forward received emails → receive-email.md
+└─ AI agent receiving emails → receive-email.md + moltbot patterns
+```
+
+### "I need to build email templates"
+
+```
+Need email templates?
+├─ React-based templates → react-email.md
+├─ Cross-client compatibility → react-email.md
+├─ Reusable components → react-email.md
+├─ Tailwind styling → react-email.md
+└─ Plain HTML templates → Use Resend dashboard templates
+```
+
+## Common Setup
+
+### API Key
+
+Store in environment variable (never commit to code):
+
+```bash
+export RESEND_API_KEY=re_xxxxxxxxx
+```
+
+### SDK Installation
+
+**Node.js:**
+
+```bash
+npm install resend
+```
+
+**Python:**
+
+```bash
+pip install resend
+```
+
+**Go:**
+
+```bash
+go get github.com/resend/resend-go/v2
+```
+
+### Basic Usage (Node.js)
+
+```typescript
+import { Resend } from "resend";
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+// Send email
+const { data, error } = await resend.emails.send({
+  from: "Acme <hello@acme.com>",
+  to: ["user@example.com"],
+  subject: "Hello World",
+  html: "<p>Email body here</p>",
+});
+
+if (error) {
+  console.error("Failed:", error.message);
+}
+```
+
+## Critical Best Practices
+
+### Always Do
+
+| Practice                      | Why                                |
+| ----------------------------- | ---------------------------------- |
+| **Idempotency keys**          | Prevent duplicate emails on retry  |
+| **Verify webhook signatures** | Prevent spoofed events             |
+| **Use test addresses**        | `delivered@resend.dev` for testing |
+| **Warm up new domains**       | Gradual volume increase            |
+| **Include plain text**        | Accessibility and deliverability   |
+
+### Never Do
+
+| Anti-Pattern                             | Why                        |
+| ---------------------------------------- | -------------------------- |
+| Test with fake emails (`test@gmail.com`) | Destroys sender reputation |
+| Skip webhook verification                | Security vulnerability     |
+| Retry 400/422 errors                     | Fix the request instead    |
+| Use "no-reply" addresses                 | Hurts deliverability       |
+| Send high volume from new domain         | Triggers spam filters      |
+
+## Webhook Events
+
+| Event              | Use Case                      |
+| ------------------ | ----------------------------- |
+| `email.sent`       | Confirm email accepted        |
+| `email.delivered`  | Confirm delivery to inbox     |
+| `email.bounced`    | Remove from list, alert user  |
+| `email.complained` | Unsubscribe (spam complaint)  |
+| `email.opened`     | Track engagement (marketing)  |
+| `email.clicked`    | Track link clicks (marketing) |
+| `email.received`   | Process inbound emails        |
+
+## Error Handling
+
+| Code     | Action                              |
+| -------- | ----------------------------------- |
+| 400, 422 | Fix request parameters, don't retry |
+| 401, 403 | Check API key / verify domain       |
+| 409      | Idempotency conflict - use new key  |
+| 429      | Rate limited - exponential backoff  |
+| 500      | Server error - retry with backoff   |
+
+## Resources
+
+- [Resend Documentation](https://resend.com/docs)
+- [API Reference](https://resend.com/docs/api-reference)
+- [React Email](https://react.email)
+- [Dashboard](https://resend.com/emails)

package/baseline/skill/resend/references/react-email.md

@@ -0,0 +1,287 @@
+# React Email
+
+Build and send HTML emails using React components. A modern, component-based approach to email development that works across all major email clients by compiling to compatible HTML.
+
+## When to Use
+
+- Creating transactional emails (welcome, password reset, order confirmation)
+- Building notification or marketing email templates
+- Need consistent rendering across Gmail, Outlook, Apple Mail, Yahoo
+- Want component reusability and TypeScript support in emails
+- Integrating with email providers like Resend, SendGrid, Postmark
+
+**When NOT to use:**
+
+- Simple plain-text emails
+- Emails that don't need cross-client compatibility
+- Projects without React/Node.js
+
+## Installation
+
+### New Project
+
+```bash
+npx create-email@latest
+cd react-email-starter
+npm install
+npm run dev
+```
+
+The server runs at localhost:3000 with a preview interface for templates in the `emails` folder.
+
+### Existing Project
+
+```bash
+npm install react-email @react-email/preview-server -D -E
+npm install @react-email/components react react-dom -E
+```
+
+Add script to package.json:
+
+```json
+{
+  "scripts": {
+    "email:dev": "email dev --dir src/emails"
+  }
+}
+```
+
+## Basic Email Template
+
+```tsx
+import {
+  Html,
+  Head,
+  Preview,
+  Body,
+  Container,
+  Heading,
+  Text,
+  Button,
+  Tailwind,
+  pixelBasedPreset,
+} from "@react-email/components";
+
+interface WelcomeEmailProps {
+  name: string;
+  verificationUrl: string;
+}
+
+export default function WelcomeEmail({ name, verificationUrl }: WelcomeEmailProps) {
+  return (
+    <Html lang="en">
+      <Tailwind
+        config={{
+          presets: [pixelBasedPreset],
+          theme: {
+            extend: {
+              colors: {
+                brand: "#007bff",
+              },
+            },
+          },
+        }}
+      >
+        <Head />
+        <Body className="bg-gray-100 font-sans">
+          <Preview>Welcome - Verify your email</Preview>
+          <Container className="max-w-xl mx-auto p-5">
+            <Heading className="text-2xl text-gray-800">Welcome!</Heading>
+            <Text className="text-base text-gray-800">Hi {name}, thanks for signing up!</Text>
+            <Button
+              href={verificationUrl}
+              className="bg-brand text-white px-5 py-3 rounded block text-center no-underline box-border"
+            >
+              Verify Email
+            </Button>
+          </Container>
+        </Body>
+      </Tailwind>
+    </Html>
+  );
+}
+
+WelcomeEmail.PreviewProps = {
+  name: "John Doe",
+  verificationUrl: "https://example.com/verify/abc123",
+} satisfies WelcomeEmailProps;
+
+export { WelcomeEmail };
+```
+
+## Essential Components
+
+**Core Structure:**
+
+- `Html` - Root wrapper with `lang` attribute
+- `Head` - Meta elements, styles, fonts
+- `Body` - Main content wrapper
+- `Container` - Centers content (max-width layout)
+- `Section` - Layout sections
+- `Row` & `Column` - Multi-column layouts (table-based)
+- `Tailwind` - Enables Tailwind CSS utility classes
+
+**Content:**
+
+- `Preview` - Inbox preview text (place after `Body` opening tag)
+- `Heading` - h1-h6 headings
+- `Text` - Paragraphs
+- `Button` - Styled link buttons
+- `Link` - Hyperlinks
+- `Img` - Images (use absolute URLs)
+- `Hr` - Horizontal dividers
+
+**Specialized:**
+
+- `CodeBlock` - Syntax-highlighted code
+- `CodeInline` - Inline code
+- `Markdown` - Render markdown
+- `Font` - Custom web fonts
+
+## Styling Rules
+
+### Always Do
+
+| Rule                           | Why                                           |
+| ------------------------------ | --------------------------------------------- |
+| Use `pixelBasedPreset`         | Email clients don't support `rem` units       |
+| Use `Row`/`Column` for layouts | Table-based layouts work everywhere           |
+| Specify border type            | Always: `border-solid`, `border-dashed`, etc. |
+| Use `box-border` on buttons    | Consistent sizing                             |
+| Use PNG/JPEG images            | SVG/WEBP not supported                        |
+| Use absolute image URLs        | Relative paths won't work                     |
+
+### Never Do
+
+| Rule                             | Why                                      |
+| -------------------------------- | ---------------------------------------- |
+| Use flexbox/grid                 | Not supported in email clients           |
+| Use media queries (`sm:`, `md:`) | Most email clients ignore them           |
+| Use theme selectors (`dark:`)    | Inconsistent support                     |
+| Use SVG/WEBP images              | Not supported                            |
+| Write template vars in JSX       | Use props: `{props.name}` not `{{name}}` |
+
+## Rendering
+
+### Convert to HTML
+
+```tsx
+import { render } from "@react-email/components";
+import { WelcomeEmail } from "./emails/welcome";
+
+const html = await render(
+  <WelcomeEmail name="John" verificationUrl="https://example.com/verify" />,
+);
+```
+
+### Convert to Plain Text
+
+```tsx
+const text = await render(
+  <WelcomeEmail name="John" verificationUrl="https://example.com/verify" />,
+  { plainText: true },
+);
+```
+
+## Sending with Resend
+
+```tsx
+import { Resend } from "resend";
+import { WelcomeEmail } from "./emails/welcome";
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+const { data, error } = await resend.emails.send({
+  from: "Acme <onboarding@resend.dev>",
+  to: ["user@example.com"],
+  subject: "Welcome to Acme",
+  react: <WelcomeEmail name="John" verificationUrl="https://example.com/verify" />,
+});
+
+if (error) {
+  console.error("Failed to send:", error);
+}
+```
+
+Resend accepts React components directly. It automatically generates a plain-text version if not provided.
+
+## Common Patterns
+
+### Responsive Container
+
+```tsx
+<Container className="max-w-xl mx-auto p-5">
+  {/* Content stays centered and readable on all devices */}
+</Container>
+```
+
+### Two-Column Layout
+
+```tsx
+<Row>
+  <Column className="w-1/2">
+    <Text>Left content</Text>
+  </Column>
+  <Column className="w-1/2">
+    <Text>Right content</Text>
+  </Column>
+</Row>
+```
+
+**Note:** Columns won't stack on mobile. Design with this in mind.
+
+### CTA Button
+
+```tsx
+<Button
+  href="https://example.com"
+  className="bg-blue-600 text-white px-6 py-3 rounded block text-center no-underline box-border"
+>
+  Click Here
+</Button>
+```
+
+### Footer with Links
+
+```tsx
+<Section className="text-center text-gray-500 text-sm">
+  <Text>
+    <Link href="https://example.com/unsubscribe" className="text-gray-500 underline">
+      Unsubscribe
+    </Link>
+    {" | "}
+    <Link href="https://example.com/preferences" className="text-gray-500 underline">
+      Preferences
+    </Link>
+  </Text>
+  <Text>123 Main St, City, State 12345</Text>
+</Section>
+```
+
+## Best Practices
+
+1. **Test across clients** - Gmail, Outlook, Apple Mail, Yahoo
+2. **Keep responsive** - Max-width ~600px
+3. **Use absolute image URLs** - Host on reliable CDN
+4. **Provide plain text version** - Required for accessibility
+5. **Add TypeScript types** - Define interfaces for all props
+6. **Include PreviewProps** - For development testing
+7. **Keep under 102KB** - Gmail clips larger emails
+
+## Common Mistakes
+
+| Mistake                           | Fix                                      |
+| --------------------------------- | ---------------------------------------- |
+| Using flexbox/grid                | Use `Row` and `Column` components        |
+| Using `rem` units                 | Use `pixelBasedPreset` with Tailwind     |
+| Using SVG images                  | Use PNG or JPG instead                   |
+| Using media queries               | Design mobile-first with stacked layouts |
+| Template vars in JSX (`{{name}}`) | Use props: `{props.name}`                |
+| Missing border type               | Always specify: `border-solid`, etc.     |
+| Emails over 102KB                 | Gmail clips - reduce size                |
+
+## Resources
+
+- [React Email Documentation](https://react.email/docs)
+- [React Email GitHub](https://github.com/resend/react-email)
+- [Email Client CSS Support](https://www.caniemail.com)

package/baseline/skill/resend/references/receive-email.md

@@ -0,0 +1,248 @@
+# Receive Emails with Resend
+
+## Overview
+
+Resend processes incoming emails for your domain and sends webhook events to your endpoint. **Webhooks contain metadata only** - you must call separate APIs to retrieve email body and attachments.
+
+## Quick Start
+
+1. **Configure receiving domain** - Use Resend's `.resend.app` domain or add MX record for custom domain
+2. **Set up webhook** - Subscribe to `email.received` event
+3. **Retrieve content** - Call Receiving API for body, Attachments API for files
+
+## Domain Setup
+
+### Option 1: Resend-Managed Domain (Fastest)
+
+Use your auto-generated address: `<anything>@<your-id>.resend.app`
+
+No DNS configuration needed. Find your address in Dashboard -> Emails -> Receiving -> "Receiving address".
+
+### Option 2: Custom Domain
+
+Add MX record to receive at `<anything>@yourdomain.com`.
+
+| Setting      | Value                        |
+| ------------ | ---------------------------- |
+| **Type**     | MX                           |
+| **Host**     | Your domain or subdomain     |
+| **Value**    | Provided in Resend dashboard |
+| **Priority** | 10 (lowest number wins)      |
+
+**Critical:** Your MX record must have the lowest priority value, or emails won't route to Resend.
+
+### Subdomain Recommendation
+
+If you already have MX records (e.g., Google Workspace, Microsoft 365):
+
+| Approach                        | Result                                                        |
+| ------------------------------- | ------------------------------------------------------------- |
+| **Use subdomain** (recommended) | `support.acme.com` -> Resend, `acme.com` -> existing provider |
+| **Use root domain**             | All email routes to Resend (breaks existing email)            |
+
+```dns
+# Receive at support.acme.com without affecting acme.com
+support.acme.com.  MX  10  <resend-mx-value>
+```
+
+## Webhook Setup
+
+### Subscribe to `email.received`
+
+Dashboard -> Webhooks -> Add Webhook -> Select `email.received`
+
+For local development, use tunneling:
+
+```bash
+ngrok http 3000
+# Use https://abc123.ngrok.io/api/webhook as endpoint
+```
+
+### Webhook Payload Structure
+
+**Important:** Payload contains metadata only, not email body or attachments.
+
+```json
+{
+  "type": "email.received",
+  "created_at": "2024-02-22T23:41:12.126Z",
+  "data": {
+    "email_id": "a1b2c3d4-...",
+    "from": "sender@example.com",
+    "to": ["support@acme.com"],
+    "cc": [],
+    "bcc": [],
+    "subject": "Question about my order",
+    "attachments": [
+      {
+        "id": "att_abc123",
+        "filename": "receipt.pdf",
+        "content_type": "application/pdf"
+      }
+    ]
+  }
+}
+```
+
+### Verify Webhook Signatures
+
+Always verify signatures to prevent spoofed events:
+
+```typescript
+import { Resend } from "resend";
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+export async function POST(req: Request) {
+  const payload = await req.text();
+
+  const event = resend.webhooks.verify({
+    payload,
+    headers: {
+      "svix-id": req.headers.get("svix-id"),
+      "svix-timestamp": req.headers.get("svix-timestamp"),
+      "svix-signature": req.headers.get("svix-signature"),
+    },
+    secret: process.env.RESEND_WEBHOOK_SECRET,
+  });
+
+  if (event.type === "email.received") {
+    // Process the email
+  }
+
+  return new Response("OK", { status: 200 });
+}
+```
+
+## Retrieving Email Content
+
+Webhooks exclude email body. Call the Receiving API:
+
+```typescript
+if (event.type === "email.received") {
+  const { data: email } = await resend.emails.receiving.get(event.data.email_id);
+
+  console.log(email.html); // HTML body
+  console.log(email.text); // Plain text body
+  console.log(email.headers); // Email headers
+}
+```
+
+**Why this design?** Serverless environments have request body size limits. Separating content retrieval supports large emails and attachments.
+
+## Handling Attachments
+
+### Get Attachment Metadata and Download URLs
+
+```typescript
+const { data: attachments } = await resend.emails.receiving.attachments.list({
+  emailId: event.data.email_id,
+});
+
+for (const attachment of attachments) {
+  console.log(attachment.filename);
+  console.log(attachment.download_url); // Valid for 1 hour
+  console.log(attachment.expires_at);
+}
+```
+
+### Download Attachment Content
+
+```typescript
+const response = await fetch(attachment.download_url);
+const buffer = await response.arrayBuffer();
+
+// Save to storage, process, etc.
+await saveToStorage(attachment.filename, buffer);
+```
+
+**Important:** `download_url` expires after 1 hour. Call the API again for a fresh URL if needed.
+
+## Forwarding Emails
+
+Complete workflow to receive and forward an email with attachments:
+
+```typescript
+import { Resend } from "resend";
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+export async function POST(req: Request) {
+  const payload = await req.text();
+  const event = resend.webhooks.verify({
+    /* ... */
+  });
+
+  if (event.type === "email.received") {
+    // 1. Get email content
+    const { data: email } = await resend.emails.receiving.get(event.data.email_id);
+
+    // 2. Get attachments (if any)
+    const { data: attachmentList } = await resend.emails.receiving.attachments.list({
+      emailId: event.data.email_id,
+    });
+
+    // 3. Download and encode attachments
+    const attachments = await Promise.all(
+      attachmentList.map(async (att) => {
+        const res = await fetch(att.download_url);
+        const buffer = Buffer.from(await res.arrayBuffer());
+        return {
+          filename: att.filename,
+          content: buffer.toString("base64"),
+        };
+      }),
+    );
+
+    // 4. Forward the email
+    await resend.emails.send({
+      from: "Support System <system@acme.com>",
+      to: ["team@acme.com"],
+      subject: `Fwd: ${email.subject}`,
+      html: email.html,
+      text: email.text,
+      attachments,
+    });
+  }
+
+  return new Response("OK", { status: 200 });
+}
+```
+
+## Routing by Recipient
+
+All emails to your domain arrive at the same webhook. Route based on the `to` field:
+
+```typescript
+if (event.type === "email.received") {
+  const recipient = event.data.to[0];
+
+  if (recipient.includes("support@")) {
+    await handleSupportEmail(event.data);
+  } else if (recipient.includes("billing@")) {
+    await handleBillingEmail(event.data);
+  } else {
+    await handleUnknownEmail(event.data);
+  }
+}
+```
+
+## Common Mistakes
+
+| Mistake                                      | Fix                                                              |
+| -------------------------------------------- | ---------------------------------------------------------------- |
+| Expecting body in webhook payload            | Webhook has metadata only - call `resend.emails.receiving.get()` |
+| MX record not lowest priority                | Ensure Resend's MX has lowest number (highest priority)          |
+| Adding MX to root domain with existing email | Use subdomain to avoid breaking existing email service           |
+| Using expired download_url                   | URLs expire after 1 hour - call attachments API again            |
+| Not verifying webhook signatures             | Always verify - attackers can send fake events                   |
+| Forgetting to return 200 OK                  | Resend retries on non-200 responses                              |
+
+## Storage Note
+
+Resend stores received emails even if:
+
+- Webhook isn't configured yet
+- Webhook endpoint is down
+
+View all received emails in Dashboard -> Emails -> Receiving tab.