@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/domain/remotion-best-practices/rules/videos.md

@@ -0,0 +1,171 @@
+---
+name: videos
+description: Embedding videos in Remotion - trimming, volume, speed, looping, pitch
+metadata:
+  tags: video, media, trim, volume, speed, loop, pitch
+---
+
+# Using videos in Remotion
+
+## Prerequisites
+
+First, the @remotion/media package needs to be installed.  
+If it is not, use the following command:
+
+```bash
+npx remotion add @remotion/media # If project uses npm
+bunx remotion add @remotion/media # If project uses bun
+yarn remotion add @remotion/media # If project uses yarn
+pnpm exec remotion add @remotion/media # If project uses pnpm
+```
+
+Use `<Video>` from `@remotion/media` to embed videos into your composition.
+
+```tsx
+import { Video } from "@remotion/media";
+import { staticFile } from "remotion";
+
+export const MyComposition = () => {
+  return <Video src={staticFile("video.mp4")} />;
+};
+```
+
+Remote URLs are also supported:
+
+```tsx
+<Video src="https://remotion.media/video.mp4" />
+```
+
+## Trimming
+
+Use `trimBefore` and `trimAfter` to remove portions of the video. Values are in seconds.
+
+```tsx
+const { fps } = useVideoConfig();
+
+return (
+  <Video
+    src={staticFile("video.mp4")}
+    trimBefore={2 * fps} // Skip the first 2 seconds
+    trimAfter={10 * fps} // End at the 10 second mark
+  />
+);
+```
+
+## Delaying
+
+Wrap the video in a `<Sequence>` to delay when it appears:
+
+```tsx
+import { Sequence, staticFile } from "remotion";
+import { Video } from "@remotion/media";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Sequence from={1 * fps}>
+    <Video src={staticFile("video.mp4")} />
+  </Sequence>
+);
+```
+
+The video will appear after 1 second.
+
+## Sizing and Position
+
+Use the `style` prop to control size and position:
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  style={{
+    width: 500,
+    height: 300,
+    position: "absolute",
+    top: 100,
+    left: 50,
+    objectFit: "cover",
+  }}
+/>
+```
+
+## Volume
+
+Set a static volume (0 to 1):
+
+```tsx
+<Video src={staticFile("video.mp4")} volume={0.5} />
+```
+
+Or use a callback for dynamic volume based on the current frame:
+
+```tsx
+import { interpolate } from "remotion";
+
+const { fps } = useVideoConfig();
+
+return (
+  <Video
+    src={staticFile("video.mp4")}
+    volume={(f) =>
+      interpolate(f, [0, 1 * fps], [0, 1], { extrapolateRight: "clamp" })
+    }
+  />
+);
+```
+
+Use `muted` to silence the video entirely:
+
+```tsx
+<Video src={staticFile("video.mp4")} muted />
+```
+
+## Speed
+
+Use `playbackRate` to change the playback speed:
+
+```tsx
+<Video src={staticFile("video.mp4")} playbackRate={2} /> {/* 2x speed */}
+<Video src={staticFile("video.mp4")} playbackRate={0.5} /> {/* Half speed */}
+```
+
+Reverse playback is not supported.
+
+## Looping
+
+Use `loop` to loop the video indefinitely:
+
+```tsx
+<Video src={staticFile("video.mp4")} loop />
+```
+
+Use `loopVolumeCurveBehavior` to control how the frame count behaves when looping:
+
+- `"repeat"`: Frame count resets to 0 each loop (for `volume` callback)
+- `"extend"`: Frame count continues incrementing
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  loop
+  loopVolumeCurveBehavior="extend"
+  volume={(f) => interpolate(f, [0, 300], [1, 0])} // Fade out over multiple loops
+/>
+```
+
+## Pitch
+
+Use `toneFrequency` to adjust the pitch without affecting speed. Values range from 0.01 to 2:
+
+```tsx
+<Video
+  src={staticFile("video.mp4")}
+  toneFrequency={1.5} // Higher pitch
+/>
+<Video
+  src={staticFile("video.mp4")}
+  toneFrequency={0.8} // Lower pitch
+/>
+```
+
+Pitch shifting only works during server-side rendering, not in the Remotion Studio preview or in the `<Player />`.

package/.merlin-core/skills/domain/resend-email/SKILL.md

@@ -0,0 +1,377 @@
+---
+name: resend-email
+description: Expert email delivery skill using Resend — transactional emails, React Email templates, audience management, and agentic MCP integration. Activates when sending emails, building email templates, or integrating email into any project.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "1.0.0"
+  auto_activate:
+    [resend-email, send-email, email-template, react-email, transactional-email]
+  tool_reminders:
+    [
+      Sending real emails to real users is a HIGH-stake action — require explicit human approval,
+      Always verify RESEND_API_KEY is set in environment before executing send,
+      Always use a verified sending domain in production (not onboarding.resend.dev),
+      Prefer React Email components for rich templates; plain text as fallback,
+    ]
+references:
+  - resend.com/docs
+  - react.email/docs
+---
+
+## Resend Email — Expert Protocol
+
+Resend is the email delivery platform of choice for developer-centric projects. It provides a clean REST API, first-class TypeScript SDK, React Email template engine, and an MCP server for agentic email sending.
+
+---
+
+## 1. MCP Server Setup (Claude Code / Merlin)
+
+Add to `.mcp.json` at project root:
+
+```json
+{
+  "mcpServers": {
+    "resend": {
+      "command": "npx",
+      "args": ["-y", "resend-mcp"],
+      "env": {
+        "RESEND_API_KEY": "re_xxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+This unlocks 56+ Resend tools directly in agent context: send, schedule, manage contacts, audiences, domains, and webhooks.
+
+> **Security**: Never commit the API key. Use environment variables or `.env.local` (gitignored).
+
+---
+
+## 2. SDK Installation
+
+```bash
+# TypeScript / Node.js
+npm install resend
+
+# With React Email templates (recommended)
+npm install resend @react-email/components react react-dom
+```
+
+---
+
+## 3. Approval Levels
+
+| Action                             | Approval Level |
+| ---------------------------------- | -------------- |
+| Send email to real user            | HIGH           |
+| Create/modify audience or contacts | HIGH           |
+| Send bulk or scheduled campaign    | HIGH           |
+| Delete domain or API key           | HIGH           |
+| Send to test address only          | MEDIUM         |
+| Preview / render template locally  | LOW            |
+| Read email logs / analytics        | LOW            |
+
+---
+
+## 4. Email Types — When to Use Each
+
+| Type           | Trigger                             | Template Style       |
+| -------------- | ----------------------------------- | -------------------- |
+| Transactional  | User action (signup, purchase, etc) | Branded, personal    |
+| Notification   | System event (alert, digest)        | Minimal, scannable   |
+| Welcome        | First login / signup completion     | Warm, value-focused  |
+| Password Reset | Auth flow                           | Secure, time-limited |
+| Invite         | Team member / referral flow         | Action-driven CTA    |
+| Marketing      | Campaign / newsletter               | Rich layout, imagery |
+
+---
+
+## 5. TypeScript SDK — Core Usage
+
+### Basic Send
+
+```typescript
+import { Resend } from "resend";
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+const { data, error } = await resend.emails.send({
+  from: "Merlin <noreply@yourdomain.com>",
+  to: ["user@example.com"],
+  subject: "Welcome to the project",
+  html: "<p>You're in.</p>",
+});
+
+if (error) {
+  console.error("Email failed:", error);
+  throw new Error(error.message);
+}
+```
+
+### With React Email Template
+
+```typescript
+import { Resend } from "resend";
+import { WelcomeEmail } from "./emails/WelcomeEmail";
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+await resend.emails.send({
+  from: "Merlin <noreply@yourdomain.com>",
+  to: [user.email],
+  subject: `Welcome, ${user.name}`,
+  react: <WelcomeEmail name={user.name} loginUrl={loginUrl} />,
+});
+```
+
+### Scheduled Send
+
+```typescript
+await resend.emails.send({
+  from: "Merlin <noreply@yourdomain.com>",
+  to: ["user@example.com"],
+  subject: "Your weekly digest",
+  html: digestHtml,
+  scheduled_at: "in 1 hour", // or ISO 8601: "2026-03-10T09:00:00Z"
+});
+```
+
+### With Attachments
+
+```typescript
+import { readFileSync } from "fs";
+
+await resend.emails.send({
+  from: "Reports <reports@yourdomain.com>",
+  to: ["client@example.com"],
+  subject: "Your monthly report",
+  html: "<p>Please find your report attached.</p>",
+  attachments: [
+    {
+      filename: "report-march-2026.pdf",
+      content: readFileSync("./report.pdf"),
+    },
+  ],
+});
+```
+
+### Idempotent Send (prevent duplicates)
+
+```typescript
+await resend.emails.send(
+  {
+    from: "Merlin <noreply@yourdomain.com>",
+    to: [user.email],
+    subject: "Payment confirmed",
+    html: receiptHtml,
+  },
+  {
+    idempotencyKey: `payment-${transactionId}`, // max 256 chars, 24h expiry
+  },
+);
+```
+
+---
+
+## 6. React Email — Template Patterns
+
+### File structure
+
+```
+emails/
+  WelcomeEmail.tsx
+  PasswordReset.tsx
+  Notification.tsx
+  _components/
+    Header.tsx
+    Footer.tsx
+    Button.tsx
+```
+
+### Minimal template
+
+```tsx
+import {
+  Html,
+  Head,
+  Body,
+  Container,
+  Heading,
+  Text,
+  Button,
+  Hr,
+  Preview,
+} from "@react-email/components";
+
+interface WelcomeEmailProps {
+  name: string;
+  loginUrl: string;
+}
+
+export function WelcomeEmail({ name, loginUrl }: WelcomeEmailProps) {
+  return (
+    <Html lang="pt-BR">
+      <Head />
+      <Preview>Bem-vindo, {name}. Sua conta esta pronta.</Preview>
+      <Body style={body}>
+        <Container style={container}>
+          <Heading style={h1}>Bem-vindo, {name}</Heading>
+          <Text style={text}>
+            Sua conta foi criada com sucesso. Clique abaixo para acessar.
+          </Text>
+          <Button href={loginUrl} style={button}>
+            Acessar plataforma
+          </Button>
+          <Hr style={hr} />
+          <Text style={footer}>
+            Se nao solicitou este acesso, ignore este e-mail.
+          </Text>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+
+// Inline styles (required for email client compatibility)
+const body = { backgroundColor: "#f6f9fc", fontFamily: "sans-serif" };
+const container = {
+  maxWidth: "600px",
+  margin: "0 auto",
+  backgroundColor: "#ffffff",
+  padding: "40px",
+  borderRadius: "8px",
+};
+const h1 = { fontSize: "24px", color: "#1a1a1a", marginBottom: "16px" };
+const text = { fontSize: "16px", color: "#444444", lineHeight: "1.6" };
+const button = {
+  backgroundColor: "#000000",
+  color: "#ffffff",
+  padding: "12px 24px",
+  borderRadius: "6px",
+  textDecoration: "none",
+  display: "inline-block",
+  marginTop: "16px",
+};
+const hr = { borderColor: "#e6ebf1", margin: "24px 0" };
+const footer = { fontSize: "12px", color: "#8898aa" };
+```
+
+### Preview locally
+
+```bash
+npx react-email dev --dir emails --port 3001
+```
+
+---
+
+## 7. Great Email Design — Non-Negotiable Rules
+
+1. **Single clear CTA** — one button, one action per email
+2. **Subject line ≤ 50 chars** — front-load the value
+3. **Preview text** — always set `<Preview>` (shown in inbox before open)
+4. **Mobile-first** — max-width 600px, font-size ≥ 14px, tap targets ≥ 44px
+5. **Inline styles only** — email clients strip `<style>` tags; use style objects
+6. **Plain text fallback** — Resend auto-generates from HTML, but review it
+7. **No image-only emails** — always include text content alongside images
+8. **Sender name matters** — `"ProjectName <noreply@domain>"` beats bare email
+9. **Unsubscribe link** — required for marketing emails (legal compliance)
+10. **Test before sending** — use `delivered@resend.dev` or your own address first
+
+---
+
+## 8. Domain Verification Checklist
+
+Before sending to real users in production:
+
+- [ ] Add domain at resend.com/domains
+- [ ] Add DNS records: SPF, DKIM (3 TXT records), DMARC
+- [ ] Wait for verification (usually < 5 min with Cloudflare/Vercel DNS)
+- [ ] Update `from` address to use verified domain
+- [ ] Remove `onboarding.resend.dev` from any production code
+
+---
+
+## 9. Audience & Contact Management
+
+```typescript
+// Create audience
+const { data: audience } = await resend.audiences.create({
+  name: "Product Updates",
+});
+
+// Add contact
+await resend.contacts.create({
+  audienceId: audience.id,
+  email: "user@example.com",
+  firstName: "Maria",
+  unsubscribed: false,
+});
+
+// Send to audience (via broadcast)
+await resend.broadcasts.create({
+  audienceId: audience.id,
+  from: "Merlin <news@yourdomain.com>",
+  subject: "v2.0 is here",
+  html: newsletterHtml,
+  scheduledAt: "2026-03-10T10:00:00Z",
+});
+```
+
+---
+
+## 10. Error Handling Pattern
+
+```typescript
+async function sendEmail(payload: EmailPayload): Promise<void> {
+  const { data, error } = await resend.emails.send(payload);
+
+  if (error) {
+    // Log with structured context
+    console.error("[resend] send failed", {
+      code: error.name,
+      message: error.message,
+      to: payload.to,
+      subject: payload.subject,
+    });
+
+    // Rethrow with context for upstream handling
+    throw new Error(`Email delivery failed: ${error.message}`);
+  }
+
+  console.info("[resend] sent", { id: data?.id, to: payload.to });
+}
+```
+
+---
+
+## 11. Environment Variables
+
+```bash
+# Required
+RESEND_API_KEY=re_xxxxxxxxx
+
+# Recommended in project .env.example (commit this)
+RESEND_API_KEY=
+EMAIL_FROM=noreply@yourdomain.com
+EMAIL_FROM_NAME=YourProject
+```
+
+Never hardcode `RESEND_API_KEY`. Always load from `process.env`.
+
+---
+
+## 12. Integration Points in Merlin Projects
+
+When scaffolding a new project, offer email integration at these lifecycle events:
+
+| Event             | Email to send        |
+| ----------------- | -------------------- |
+| User signup       | Welcome + verify     |
+| Password change   | Security alert       |
+| Invite sent       | Invite with CTA link |
+| Purchase complete | Receipt / invoice    |
+| Trial expiring    | Upgrade nudge        |
+| Weekly activity   | Digest summary       |
+| Error / alert     | Ops notification     |

package/.merlin-core/skills/general/adversarial-review/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: adversarial-review
+description: Adversarial code review methodology — actively find problems, not verify correctness. 7-axis structured attack surface analysis.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: [adversarial, attack-surface, red-team, break-code, find-bugs]
+---
+
+# Adversarial Review
+
+Your job is to **BREAK it**, not verify it. Assume the code has bugs. Find them.
+
+## Mindset Shift
+
+| Traditional Review | Adversarial Review         |
+| ------------------ | -------------------------- |
+| "Does it work?"    | "How can it fail?"         |
+| Verify correctness | Find defects               |
+| Check happy path   | Explore edge cases         |
+| Trust the author   | Challenge every assumption |
+| Pass by default    | Fail by default            |
+
+## 7-Axis Attack Surface
+
+Systematically analyze every change across these seven dimensions:
+
+### Axis 1: Security
+
+- User input passed unsanitized to shell commands, SQL, or file paths?
+- Authentication/authorization checks present on all endpoints?
+- Sensitive data logged or exposed in error messages?
+- Hardcoded secrets, tokens, or credentials?
+- Path traversal, SSRF, or open redirect vulnerabilities?
+- Dependencies with known CVEs introduced?
+- CORS, CSP, or other security headers misconfigured?
+- Cryptographic operations using weak algorithms?
+
+### Axis 2: Logic Errors
+
+- Off-by-one errors in loops or array indexing?
+- Race conditions in async operations?
+- State corruption from concurrent access?
+- Missing null/undefined checks at trust boundaries?
+- Incorrect boolean logic (de Morgan's law violations)?
+- Unreachable code branches?
+- Incorrect error propagation (swallowed errors)?
+
+### Axis 3: Edge Cases
+
+- Empty inputs, null, undefined, NaN handled?
+- Maximum value inputs (MAX_SAFE_INTEGER, very long strings)?
+- Unicode, emoji, RTL text handled correctly?
+- Concurrent access, timeout scenarios?
+- Network failures, partial responses?
+- Disk full, permissions denied?
+
+### Axis 4: Spec Deviation (Article IV)
+
+- Every changed file traces to a plan item?
+- Every plan item has a corresponding code change?
+- No invented features not in the specification?
+- Behavior matches plan intent, not just letter?
+- Out-of-scope changes introduced?
+
+### Axis 5: Untested Paths
+
+- Code paths with no test coverage?
+- Error handlers never exercised in tests?
+- Edge case scenarios not tested?
+- Integration points tested in isolation only?
+- Negative test cases missing?
+
+### Axis 6: Performance
+
+- N+1 queries or unbounded database calls?
+- Unbounded loops or recursion without limits?
+- Memory leaks (event listeners not removed, closures holding references)?
+- Large allocations without streaming?
+- Missing pagination on list endpoints?
+- Synchronous operations blocking the event loop?
+
+### Axis 7: Scale
+
+- What breaks first at 10x current load?
+- And at 100x?
+- Database queries that scan full tables or miss indexes?
+- In-memory data structures that grow unbounded?
+- Single points of failure with no horizontal scaling path?
+- Missing connection pooling or pool exhaustion risk?
+- Cache stampede scenarios (many requests hitting cold cache simultaneously)?
+- Rate limiting absent on resource-intensive endpoints?
+
+## Git-Reality Cross-Reference
+
+This is the most critical step. Compare plan vs actual:
+
+1. Run `git diff main...HEAD --stat` to get all changed files
+2. For each plan item: verify there's a corresponding file change
+3. For each file change: verify it traces to a plan item
+4. Flag orphan changes (code changes not in plan) as potential Article IV violations
+5. Flag missing changes (plan items with no code change) as incomplete implementation
+
+## Severity Classification
+
+| Severity     | Meaning                                            | Action                 |
+| ------------ | -------------------------------------------------- | ---------------------- |
+| **CRITICAL** | Security vulnerability, data loss, or crash        | Blocks ship. Must fix. |
+| **HIGH**     | Logic error, missing validation, spec deviation    | Must fix before merge. |
+| **MEDIUM**   | Missing test, potential edge case, minor deviation | Should fix.            |
+| **LOW**      | Style issue, minor optimization opportunity        | Nice to fix.           |
+| **INFO**     | Observation, suggestion, or note for future        | No action required.    |
+
+## Verdict
+
+- **CLEAR:** No critical or high findings. Safe to proceed.
+- **CONDITIONAL:** High findings exist but can be fixed quickly. Fix, then re-review.
+- **BLOCKED:** Critical findings. Do not merge. Fix and re-submit.
+
+## Output Format
+
+```markdown
+## Adversarial Review: [Feature/Module]
+
+Date: [date]
+Reviewer: Quinn (Adversarial Mode)
+Plan: [plan reference]
+Verdict: [CLEAR | CONDITIONAL | BLOCKED]
+
+### Git-Reality Cross-Reference
+
+- Plan items: [N] | Code changes: [M] | Orphans: [X] | Missing: [Y]
+
+### Findings
+
+1. [CRITICAL] [Axis] Description — file:line
+2. [HIGH] [Axis] Description — file:line
+3. [MEDIUM] [Axis] Description — file:line
+
+### Summary
+
+[1-2 sentence overall assessment]
+```