npm - @mars-stack/cli - Versions diffs - 0.2.0 → 1.0.2 - Mend

@mars-stack/cli 0.2.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (175) hide show

package/dist/index.js +137 -12
package/dist/index.js.map +1 -1
package/package.json +4 -3
package/template/.cursor/rules/composition-patterns.mdc +186 -0
package/template/.cursor/rules/data-access.mdc +29 -0
package/template/.cursor/rules/project-structure.mdc +34 -0
package/template/.cursor/rules/security.mdc +25 -0
package/template/.cursor/rules/testing.mdc +24 -0
package/template/.cursor/rules/ui-conventions.mdc +29 -0
package/template/.cursor/skills/add-api-route/SKILL.md +122 -0
package/template/.cursor/skills/add-audit-log/SKILL.md +375 -0
package/template/.cursor/skills/add-blog/SKILL.md +447 -0
package/template/.cursor/skills/add-command-palette/SKILL.md +438 -0
package/template/.cursor/skills/add-component/SKILL.md +158 -0
package/template/.cursor/skills/add-crud-routes/SKILL.md +221 -0
package/template/.cursor/skills/add-e2e-test/SKILL.md +227 -0
package/template/.cursor/skills/add-error-boundary/SKILL.md +472 -0
package/template/.cursor/skills/add-feature/SKILL.md +174 -0
package/template/.cursor/skills/add-middleware/SKILL.md +135 -0
package/template/.cursor/skills/add-page/SKILL.md +151 -0
package/template/.cursor/skills/add-prisma-model/SKILL.md +148 -0
package/template/.cursor/skills/add-protected-resource/SKILL.md +192 -0
package/template/.cursor/skills/add-role/SKILL.md +156 -0
package/template/.cursor/skills/add-server-action/SKILL.md +167 -0
package/template/.cursor/skills/add-webhook/SKILL.md +192 -0
package/template/.cursor/skills/build-complete-feature/SKILL.md +227 -0
package/template/.cursor/skills/build-dashboard/SKILL.md +211 -0
package/template/.cursor/skills/build-data-table/SKILL.md +283 -0
package/template/.cursor/skills/build-form/SKILL.md +231 -0
package/template/.cursor/skills/build-landing-page/SKILL.md +248 -0
package/template/.cursor/skills/configure-ai/SKILL.md +617 -0
package/template/.cursor/skills/configure-analytics/SKILL.md +413 -0
package/template/.cursor/skills/configure-dark-mode/SKILL.md +309 -0
package/template/.cursor/skills/configure-email/SKILL.md +170 -0
package/template/.cursor/skills/configure-email-verification/SKILL.md +333 -0
package/template/.cursor/skills/configure-feature-flags/SKILL.md +361 -0
package/template/.cursor/skills/configure-i18n/SKILL.md +518 -0
package/template/.cursor/skills/configure-jobs/SKILL.md +500 -0
package/template/.cursor/skills/configure-magic-links/SKILL.md +385 -0
package/template/.cursor/skills/configure-multi-tenancy/SKILL.md +611 -0
package/template/.cursor/skills/configure-notifications/SKILL.md +569 -0
package/template/.cursor/skills/configure-oauth/SKILL.md +217 -0
package/template/.cursor/skills/configure-onboarding/SKILL.md +483 -0
package/template/.cursor/skills/configure-payments/SKILL.md +243 -0
package/template/.cursor/skills/configure-realtime/SKILL.md +733 -0
package/template/.cursor/skills/configure-search/SKILL.md +581 -0
package/template/.cursor/skills/configure-storage/SKILL.md +273 -0
package/template/.cursor/skills/configure-two-factor/SKILL.md +518 -0
package/template/.cursor/skills/create-execution-plan/SKILL.md +204 -0
package/template/.cursor/skills/create-seed/SKILL.md +191 -0
package/template/.cursor/skills/deploy-to-vercel/SKILL.md +300 -0
package/template/.cursor/skills/design-tokens/SKILL.md +138 -0
package/template/.cursor/skills/mars-capture-conversation-context/SKILL.md +119 -0
package/template/.cursor/skills/setup-billing/SKILL.md +322 -0
package/template/.cursor/skills/setup-project/SKILL.md +104 -0
package/template/.cursor/skills/setup-teams/SKILL.md +682 -0
package/template/.cursor/skills/test-api-route/SKILL.md +219 -0
package/template/.cursor/skills/update-architecture-docs/SKILL.md +99 -0
package/template/AGENTS.md +104 -0
package/template/ARCHITECTURE.md +102 -0
package/template/docs/QUALITY_SCORE.md +20 -0
package/template/docs/design-docs/conversation-as-system-record.md +70 -0
package/template/docs/design-docs/core-beliefs.md +43 -0
package/template/docs/design-docs/index.md +8 -0
package/template/docs/exec-plans/active/.gitkeep +0 -0
package/template/docs/exec-plans/completed/.gitkeep +0 -0
package/template/docs/exec-plans/tech-debt.md +7 -0
package/template/docs/generated/.gitkeep +0 -0
package/template/docs/product-specs/index.md +7 -0
package/template/docs/references/index.md +18 -0
package/template/e2e/api.spec.ts +20 -0
package/template/e2e/auth.spec.ts +24 -0
package/template/e2e/public.spec.ts +25 -0
package/template/eslint.config.mjs +24 -0
package/template/next-env.d.ts +6 -0
package/template/next.config.ts +45 -0
package/template/package.json +80 -0
package/template/playwright.config.ts +31 -0
package/template/postcss.config.mjs +8 -0
package/template/prisma/generated/prisma/browser.ts +49 -0
package/template/prisma/generated/prisma/client.ts +73 -0
package/template/prisma/generated/prisma/commonInputTypes.ts +406 -0
package/template/prisma/generated/prisma/enums.ts +15 -0
package/template/prisma/generated/prisma/internal/class.ts +254 -0
package/template/prisma/generated/prisma/internal/prismaNamespace.ts +1240 -0
package/template/prisma/generated/prisma/internal/prismaNamespaceBrowser.ts +190 -0
package/template/prisma/generated/prisma/models/Account.ts +1543 -0
package/template/prisma/generated/prisma/models/File.ts +1529 -0
package/template/prisma/generated/prisma/models/Session.ts +1415 -0
package/template/prisma/generated/prisma/models/Subscription.ts +1455 -0
package/template/prisma/generated/prisma/models/User.ts +2235 -0
package/template/prisma/generated/prisma/models/VerificationToken.ts +1099 -0
package/template/prisma/generated/prisma/models.ts +17 -0
package/template/prisma/schema/auth.prisma +69 -0
package/template/prisma/schema/base.prisma +8 -0
package/template/prisma/schema/file.prisma +15 -0
package/template/prisma/schema/subscription.prisma +17 -0
package/template/prisma.config.ts +13 -0
package/template/scripts/check-architecture.ts +221 -0
package/template/scripts/check-doc-freshness.ts +242 -0
package/template/scripts/ensure-db.mjs +291 -0
package/template/scripts/generate-docs.ts +143 -0
package/template/scripts/generate-env-example.ts +89 -0
package/template/scripts/seed.ts +56 -0
package/template/scripts/update-quality-score.ts +263 -0
package/template/src/__tests__/architecture.test.ts +114 -0
package/template/src/app/(auth)/forgotten-password/page.tsx +92 -0
package/template/src/app/(auth)/layout.tsx +11 -0
package/template/src/app/(auth)/register/page.tsx +162 -0
package/template/src/app/(auth)/reset-password/page.tsx +109 -0
package/template/src/app/(auth)/sign-in/page.tsx +122 -0
package/template/src/app/(auth)/verify/[token]/page.tsx +87 -0
package/template/src/app/(auth)/verify/page.tsx +56 -0
package/template/src/app/(protected)/admin/page.tsx +108 -0
package/template/src/app/(protected)/dashboard/loading.tsx +20 -0
package/template/src/app/(protected)/dashboard/page.tsx +22 -0
package/template/src/app/(protected)/layout.tsx +262 -0
package/template/src/app/(protected)/settings/page.tsx +370 -0
package/template/src/app/api/auth/forgot/route.ts +63 -0
package/template/src/app/api/auth/login/route.ts +121 -0
package/template/src/app/api/auth/logout/route.ts +19 -0
package/template/src/app/api/auth/me/route.ts +30 -0
package/template/src/app/api/auth/reset/route.ts +45 -0
package/template/src/app/api/auth/signup/route.ts +85 -0
package/template/src/app/api/auth/verify/route.ts +46 -0
package/template/src/app/api/csrf/route.ts +12 -0
package/template/src/app/api/health/route.ts +10 -0
package/template/src/app/api/protected/admin/users/route.ts +24 -0
package/template/src/app/api/protected/billing/checkout/route.ts +83 -0
package/template/src/app/api/protected/billing/portal/route.ts +39 -0
package/template/src/app/api/protected/files/[fileId]/route.ts +86 -0
package/template/src/app/api/protected/files/upload/route.ts +64 -0
package/template/src/app/api/protected/user/password/route.ts +63 -0
package/template/src/app/api/protected/user/profile/route.ts +35 -0
package/template/src/app/api/protected/user/sessions/[sessionId]/route.ts +33 -0
package/template/src/app/api/protected/user/sessions/route.ts +22 -0
package/template/src/app/api/readiness/route.ts +15 -0
package/template/src/app/api/webhooks/stripe/route.ts +166 -0
package/template/src/app/error.tsx +33 -0
package/template/src/app/layout.tsx +29 -0
package/template/src/app/not-found.tsx +20 -0
package/template/src/app/page.tsx +136 -0
package/template/src/app/privacy/page.tsx +178 -0
package/template/src/app/providers.tsx +8 -0
package/template/src/app/terms/page.tsx +139 -0
package/template/src/config/app.config.ts +70 -0
package/template/src/config/routes.ts +17 -0
package/template/src/features/admin/index.ts +11 -0
package/template/src/features/admin/permissions.ts +64 -0
package/template/src/features/auth/context/AuthContext.tsx +96 -0
package/template/src/features/auth/context/index.ts +2 -0
package/template/src/features/auth/index.ts +3 -0
package/template/src/features/auth/server/consent.ts +66 -0
package/template/src/features/auth/server/session-revocation.ts +20 -0
package/template/src/features/auth/server/sessions.ts +66 -0
package/template/src/features/auth/server/user.ts +166 -0
package/template/src/features/auth/types.ts +19 -0
package/template/src/features/auth/validators.ts +29 -0
package/template/src/features/billing/server/index.ts +66 -0
package/template/src/features/billing/types.ts +43 -0
package/template/src/features/uploads/server/index.ts +49 -0
package/template/src/features/uploads/types.ts +26 -0
package/template/src/lib/core/email/templates/base-layout.ts +122 -0
package/template/src/lib/core/email/templates/index.ts +4 -0
package/template/src/lib/core/email/templates/password-reset-email.ts +42 -0
package/template/src/lib/core/email/templates/verification-email.ts +41 -0
package/template/src/lib/core/email/templates/welcome-email.ts +40 -0
package/template/src/lib/mars.ts +56 -0
package/template/src/lib/prisma.ts +19 -0
package/template/src/proxy.ts +92 -0
package/template/src/styles/brand.css +15 -0
package/template/src/styles/globals.css +7 -0
package/template/tsconfig.json +59 -0
package/template/vitest.config.ts +41 -0
package/template/vitest.setup.ts +24 -0

package/template/.cursor/skills/configure-dark-mode/SKILL.md ADDED Viewed

@@ -0,0 +1,309 @@
+# Skill: Configure Dark Mode
+Set up a dark mode toggle with system preference detection and persistence in a MARS application.
+## When to Use
+Use this skill when the user asks to add dark mode, a theme toggle, light/dark switching, or system theme preference support.
+## Prerequisites
+- MARS design tokens configured (the token system already supports `.dark` class on `<html>`)
+- Tailwind CSS configured with `darkMode: 'class'`
+## Architecture
+MARS uses OKLCH-based design tokens with semantic names like `--color-surface-primary`. The `.dark` class on `<html>` swaps all token values to their dark variants. This skill adds:
+1. **Theme context provider** — manages current theme state
+2. **Persistence** — saves preference to `localStorage`
+3. **System detection** — respects `prefers-color-scheme` media query
+4. **Flash prevention** — inline script prevents FOUC (flash of unstyled content)
+5. **Toggle component** — UI control for switching themes
+## Step 1: Theme Configuration
+Add theme settings to `src/config/app.config.ts`:
+```typescript
+ui: {
+  theme: {
+    default: 'system' as 'light' | 'dark' | 'system',
+    enableToggle: true,
+  },
+},
+```
+## Step 2: Prevent Flash of Wrong Theme
+Add an inline script to `src/app/layout.tsx` that runs before React hydration:
+```typescript
+// src/app/layout.tsx
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `
+              (function() {
+                try {
+                  var stored = localStorage.getItem('mars-theme');
+                  var prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+                  var theme = stored || '${appConfig.ui.theme.default}';
+                  var isDark = theme === 'dark' || (theme === 'system' && prefersDark);
+                  document.documentElement.classList.toggle('dark', isDark);
+                } catch (e) {}
+              })();
+            `,
+          }}
+        />
+      </head>
+      <body>
+        <ThemeProvider>{children}</ThemeProvider>
+      </body>
+    </html>
+  );
+}
+```
+## Step 3: Theme Context Provider
+```typescript
+// src/lib/shared/components/providers/ThemeProvider.tsx
+'use client';
+import { createContext, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+type Theme = 'light' | 'dark' | 'system';
+interface ThemeContextValue {
+  theme: Theme;
+  resolvedTheme: 'light' | 'dark';
+  setTheme: (theme: Theme) => void;
+}
+const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);
+const STORAGE_KEY = 'mars-theme';
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  const [theme, setThemeState] = useState<Theme>('system');
+  const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>('light');
+  const applyTheme = useCallback((newTheme: Theme) => {
+    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+    const isDark = newTheme === 'dark' || (newTheme === 'system' && prefersDark);
+    document.documentElement.classList.toggle('dark', isDark);
+    setResolvedTheme(isDark ? 'dark' : 'light');
+  }, []);
+  const setTheme = useCallback(
+    (newTheme: Theme) => {
+      setThemeState(newTheme);
+      localStorage.setItem(STORAGE_KEY, newTheme);
+      applyTheme(newTheme);
+    },
+    [applyTheme],
+  );
+  useEffect(() => {
+    const stored = localStorage.getItem(STORAGE_KEY) as Theme | null;
+    const initial = stored || 'system';
+    setThemeState(initial);
+    applyTheme(initial);
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    function handleChange() {
+      const current = localStorage.getItem(STORAGE_KEY) as Theme | null;
+      if (!current || current === 'system') {
+        applyTheme('system');
+      }
+    }
+    mediaQuery.addEventListener('change', handleChange);
+    return () => mediaQuery.removeEventListener('change', handleChange);
+  }, [applyTheme]);
+  const value = useMemo(
+    () => ({ theme, resolvedTheme, setTheme }),
+    [theme, resolvedTheme, setTheme],
+  );
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+export function useTheme(): ThemeContextValue {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error('useTheme must be used within a ThemeProvider');
+  }
+  return context;
+}
+```
+## Step 4: Theme Toggle Component
+```typescript
+// src/lib/shared/components/patterns/ThemeToggle.tsx
+'use client';
+import { useTheme } from '@/lib/shared/components/providers/ThemeProvider';
+export function ThemeToggle() {
+  const { theme, setTheme, resolvedTheme } = useTheme();
+  return (
+    <div className="flex items-center gap-1 rounded-lg bg-surface-secondary p-1">
+      <button
+        onClick={() => setTheme('light')}
+        className={`rounded-md px-3 py-1.5 text-sm transition-colors ${
+          theme === 'light'
+            ? 'bg-surface-primary text-content-primary shadow-sm'
+            : 'text-content-tertiary hover:text-content-secondary'
+        }`}
+        aria-label="Light theme"
+      >
+        <SunIcon className="h-4 w-4" />
+      </button>
+      <button
+        onClick={() => setTheme('system')}
+        className={`rounded-md px-3 py-1.5 text-sm transition-colors ${
+          theme === 'system'
+            ? 'bg-surface-primary text-content-primary shadow-sm'
+            : 'text-content-tertiary hover:text-content-secondary'
+        }`}
+        aria-label="System theme"
+      >
+        <MonitorIcon className="h-4 w-4" />
+      </button>
+      <button
+        onClick={() => setTheme('dark')}
+        className={`rounded-md px-3 py-1.5 text-sm transition-colors ${
+          theme === 'dark'
+            ? 'bg-surface-primary text-content-primary shadow-sm'
+            : 'text-content-tertiary hover:text-content-secondary'
+        }`}
+        aria-label="Dark theme"
+      >
+        <MoonIcon className="h-4 w-4" />
+      </button>
+    </div>
+  );
+}
+function SunIcon({ className }: { className?: string }) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className={className}>
+      <path d="M10 2a.75.75 0 01.75.75v1.5a.75.75 0 01-1.5 0v-1.5A.75.75 0 0110 2zm0 13a.75.75 0 01.75.75v1.5a.75.75 0 01-1.5 0v-1.5A.75.75 0 0110 15zm8-5a.75.75 0 01-.75.75h-1.5a.75.75 0 010-1.5h1.5A.75.75 0 0118 10zM5 10a.75.75 0 01-.75.75h-1.5a.75.75 0 010-1.5h1.5A.75.75 0 015 10zm10.657-5.657a.75.75 0 010 1.06l-1.06 1.061a.75.75 0 11-1.061-1.06l1.06-1.061a.75.75 0 011.061 0zm-9.193 9.193a.75.75 0 010 1.06l-1.06 1.061a.75.75 0 11-1.061-1.06l1.06-1.061a.75.75 0 011.061 0zm9.193 0a.75.75 0 01-1.06 0l-1.061-1.06a.75.75 0 011.06-1.061l1.061 1.06a.75.75 0 010 1.061zM5.464 6.525a.75.75 0 01-1.06 0L3.343 5.464a.75.75 0 011.06-1.06l1.061 1.06a.75.75 0 010 1.061zM10 6.5a3.5 3.5 0 100 7 3.5 3.5 0 000-7z" />
+    </svg>
+  );
+}
+function MoonIcon({ className }: { className?: string }) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className={className}>
+      <path fillRule="evenodd" d="M7.455 2.004a.75.75 0 01.26.77 7 7 0 009.958 7.967.75.75 0 011.067.853A8.5 8.5 0 116.647 1.921a.75.75 0 01.808.083z" clipRule="evenodd" />
+    </svg>
+  );
+}
+function MonitorIcon({ className }: { className?: string }) {
+  return (
+    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" className={className}>
+      <path fillRule="evenodd" d="M2 4.25A2.25 2.25 0 014.25 2h11.5A2.25 2.25 0 0118 4.25v8.5A2.25 2.25 0 0115.75 15h-3.105a3.501 3.501 0 001.1 1.677A.75.75 0 0113.26 18H6.74a.75.75 0 01-.484-1.323A3.501 3.501 0 007.355 15H4.25A2.25 2.25 0 012 12.75v-8.5zm1.5 0a.75.75 0 01.75-.75h11.5a.75.75 0 01.75.75v7.5a.75.75 0 01-.75.75H4.25a.75.75 0 01-.75-.75v-7.5z" clipRule="evenodd" />
+    </svg>
+  );
+}
+```
+## Step 5: Simple Toggle (Alternative)
+For a minimal sun/moon toggle button:
+```typescript
+// src/lib/shared/components/patterns/ThemeToggleSimple.tsx
+'use client';
+import { useTheme } from '@/lib/shared/components/providers/ThemeProvider';
+export function ThemeToggleSimple() {
+  const { resolvedTheme, setTheme } = useTheme();
+  function toggle() {
+    setTheme(resolvedTheme === 'dark' ? 'light' : 'dark');
+  }
+  return (
+    <button
+      onClick={toggle}
+      className="rounded-md p-2 text-content-secondary hover:bg-surface-secondary hover:text-content-primary transition-colors"
+      aria-label={`Switch to ${resolvedTheme === 'dark' ? 'light' : 'dark'} mode`}
+    >
+      {resolvedTheme === 'dark' ? <SunIcon className="h-5 w-5" /> : <MoonIcon className="h-5 w-5" />}
+    </button>
+  );
+}
+```
+## Step 6: Add to Navbar
+```typescript
+import { ThemeToggle } from '@/lib/shared/components/patterns/ThemeToggle';
+// In your navbar component:
+<nav className="flex items-center gap-4">
+  {/* ... other nav items */}
+  <ThemeToggle />
+</nav>
+```
+## Step 7: Tailwind Configuration
+Ensure `tailwind.config.ts` uses class-based dark mode:
+```typescript
+import type { Config } from 'tailwindcss';
+const config: Config = {
+  darkMode: 'class',
+  // ... rest of config
+};
+```
+The design token CSS variables already swap under `.dark`:
+```css
+:root {
+  --color-surface-primary: oklch(1 0 0);
+  --color-content-primary: oklch(0.15 0 0);
+  /* ... */
+}
+.dark {
+  --color-surface-primary: oklch(0.15 0 0);
+  --color-content-primary: oklch(0.95 0 0);
+  /* ... */
+}
+```
+## Testing
+1. Click the toggle — verify the theme switches and the `.dark` class toggles on `<html>`.
+2. Refresh the page — verify the theme persists (no flash).
+3. Set to "system", change OS preference — verify the theme follows.
+4. Clear `localStorage`, reload — verify it defaults to the `app.config.ts` setting.
+5. Verify all semantic token colors update (surfaces, content, borders, interactive).
+## Checklist
+- [ ] `darkMode: 'class'` set in `tailwind.config.ts`
+- [ ] Flash-prevention script added to `<head>` in root layout
+- [ ] `ThemeProvider` wraps the app in root layout
+- [ ] `useTheme` hook exports `theme`, `resolvedTheme`, `setTheme`
+- [ ] `localStorage` persistence with `mars-theme` key
+- [ ] System preference listener for `prefers-color-scheme`
+- [ ] Theme toggle component placed in navbar/header
+- [ ] No raw color classes used — only semantic tokens
+- [ ] `suppressHydrationWarning` on `<html>` element

package/template/.cursor/skills/configure-email/SKILL.md ADDED Viewed

@@ -0,0 +1,170 @@
+# Skill: Configure Email Service
+Set up and switch between email providers in a MARS application.
+## When to Use
+Use this skill when the user asks to configure email, set up SendGrid, add Resend, switch email providers, or send transactional emails.
+## Architecture
+MARS uses a pluggable email service re-exported via `@/lib/mars`. The active provider is set in `appConfig.services.email.provider`.
+Available providers:
+- `console` -- logs emails to terminal (default, no setup needed)
+- `sendgrid` -- SendGrid API
+- `resend` -- Resend API (to be added)
+## Switching Providers
+### Step 1: Update `app.config.ts`
+```typescript
+services: {
+  email: { provider: 'sendgrid' },
+  // ...
+}
+```
+### Step 2: Set Environment Variables
+**SendGrid:**
+```bash
+SENDGRID_API_KEY="SG.your-api-key"
+SENDGRID_FROM_EMAIL="noreply@yourdomain.com"
+```
+**Resend:**
+```bash
+RESEND_API_KEY="re_your-api-key"
+RESEND_FROM_EMAIL="noreply@yourdomain.com"
+```
+### Step 3: Update Env Validation
+In `src/core/env/index.ts`, the schema already conditionally validates email vars:
+```typescript
+if (appConfig.services.email.provider !== 'console') {
+  base.SENDGRID_API_KEY = z.string().min(1).optional();
+  base.SENDGRID_FROM_EMAIL = z.string().email().optional();
+}
+```
+## Adding a New Provider (Resend)
+### Step 1: Install the SDK
+```bash
+yarn add resend
+```
+### Step 2: Add the Provider
+In the email service module (wired through `@/lib/mars`):
+```typescript
+async function sendWithResend(params: SendEmailParams): Promise<void> {
+  const { Resend } = await import('resend');
+  const apiKey = process.env.RESEND_API_KEY;
+  const fromEmail = process.env.RESEND_FROM_EMAIL;
+  if (!apiKey) throw new Error('RESEND_API_KEY is not set');
+  if (!fromEmail) throw new Error('RESEND_FROM_EMAIL is not set');
+  const resend = new Resend(apiKey);
+  await resend.emails.send({
+    from: `${appConfig.name} <${fromEmail}>`,
+    to: params.to,
+    subject: params.subject,
+    html: params.html,
+    text: params.text,
+  });
+}
+export async function sendEmail(params: SendEmailParams): Promise<void> {
+  const provider = appConfig.services.email.provider;
+  switch (provider) {
+    case 'sendgrid':
+      return sendWithSendGrid(params);
+    case 'resend':
+      return sendWithResend(params);
+    case 'console':
+    default:
+      return sendWithConsole(params);
+  }
+}
+```
+### Step 3: Update the Config Type
+In `app.config.ts`, add the new provider to the union:
+```typescript
+email: { provider: 'console' as 'sendgrid' | 'resend' | 'console' },
+```
+## Sending Emails
+All email sending goes through `sendEmail()`:
+```typescript
+import { sendEmail } from '@/lib/mars';
+import { appConfig } from '@/config/app.config';
+await sendEmail({
+  to: user.email,
+  subject: `Welcome to ${appConfig.name}`,
+  text: `Hello ${user.name}, welcome!`,
+  html: `<h1>Hello ${user.name}</h1><p>Welcome to ${appConfig.name}!</p>`,
+});
+```
+## Email Templates
+For complex emails, create template functions:
+```typescript
+// src/features/auth/server/email-templates.ts
+import { appConfig } from '@/config/app.config';
+export function welcomeEmail(name: string, verifyUrl: string) {
+  return {
+    subject: `Welcome to ${appConfig.name} - Verify Your Email`,
+    text: `Hi ${name},\n\nVerify your email: ${verifyUrl}`,
+    html: `
+      <div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px;">
+        <h2>Welcome to ${appConfig.name}!</h2>
+        <p>Hi ${name},</p>
+        <p>Click the button below to verify your email:</p>
+        <div style="text-align: center; margin: 30px 0;">
+          <a href="${verifyUrl}" style="background-color: #2563eb; color: white; padding: 12px 24px; text-decoration: none; border-radius: 6px; display: inline-block;">
+            Verify Email
+          </a>
+        </div>
+        <p style="color: #6b7280; font-size: 14px;">This link expires in 24 hours.</p>
+      </div>
+    `,
+  };
+}
+```
+## Development Workflow
+1. Start with `console` provider -- emails are logged to terminal.
+2. Switch to `sendgrid` or `resend` when ready for real delivery.
+3. Use the console output to verify email content during development.
+## Checklist
+- [ ] Provider set in `appConfig.services.email.provider`
+- [ ] API key and from email in `.env`
+- [ ] Env validation updated for the provider's variables
+- [ ] Provider function added to the email service module
+- [ ] `sendEmail` switch statement updated
+- [ ] Email templates use `appConfig.name` for branding
+- [ ] Tested with `console` provider first
+- [ ] No secrets hardcoded in templates