@folpe/loom 0.2.0 → 0.3.0

package/data/skills/react-query-patterns/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: react-query-patterns
+description: "TanStack React Query for data fetching, caching, mutations, and optimistic updates. Use when managing server state in client components, implementing data fetching hooks, or caching API responses."
+---
+
+# React Query Patterns
+
+## Critical Rules
+
+- **Query keys are structured** — use the factory pattern from `query-keys.ts`.
+- **Custom hooks for reuse** — wrap `useQuery`/`useMutation` in domain hooks.
+- **Invalidate on mutation** — always invalidate related queries after writes.
+- **Optimistic updates for UX** — use for edits and deletes where latency matters.
+- **Prefetch in RSC** — hydrate queries in server components for instant loads.
+- **Never fetch in useEffect** — use React Query instead.
+
+## Setup
+
+```tsx
+// src/providers/query-provider.tsx
+"use client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useState } from "react";
+
+export function QueryProvider({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            staleTime: 60 * 1000, // 1 minute
+            refetchOnWindowFocus: false,
+          },
+        },
+      })
+  );
+
+  return (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}
+```
+
+## Query Keys Convention
+
+```ts
+// src/lib/query-keys.ts
+export const queryKeys = {
+  users: {
+    all: ["users"] as const,
+    list: (filters: UserFilters) => ["users", "list", filters] as const,
+    detail: (id: string) => ["users", "detail", id] as const,
+  },
+  posts: {
+    all: ["posts"] as const,
+    list: (filters: PostFilters) => ["posts", "list", filters] as const,
+    detail: (id: string) => ["posts", "detail", id] as const,
+    comments: (postId: string) => ["posts", postId, "comments"] as const,
+  },
+} as const;
+```
+
+## Queries
+
+### Basic Query
+
+```tsx
+"use client";
+import { useQuery } from "@tanstack/react-query";
+import { queryKeys } from "@/lib/query-keys";
+
+export function UserList() {
+  const { data: users, isLoading, error } = useQuery({
+    queryKey: queryKeys.users.all,
+    queryFn: () => fetch("/api/users").then((r) => r.json()),
+  });
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <ErrorMessage error={error} />;
+
+  return <ul>{users.map((u) => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+### Query with Server Action
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { getUserList } from "@/actions/user.actions";
+
+const { data } = useQuery({
+  queryKey: queryKeys.users.list(filters),
+  queryFn: () => getUserList(filters),
+});
+```
+
+## Mutations
+
+### Basic Mutation
+
+```tsx
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { createUser } from "@/actions/user.actions";
+import { queryKeys } from "@/lib/query-keys";
+import { toast } from "sonner";
+
+export function useCreateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: createUser,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+      toast.success("User created");
+    },
+    onError: (error) => {
+      toast.error(error.message);
+    },
+  });
+}
+```
+
+### Optimistic Update
+
+```tsx
+export function useUpdateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: ({ id, data }: { id: string; data: UpdateUserInput }) =>
+      updateUser(id, data),
+    onMutate: async ({ id, data }) => {
+      await queryClient.cancelQueries({ queryKey: queryKeys.users.detail(id) });
+      const previous = queryClient.getQueryData(queryKeys.users.detail(id));
+      queryClient.setQueryData(queryKeys.users.detail(id), (old: User) => ({
+        ...old,
+        ...data,
+      }));
+      return { previous };
+    },
+    onError: (_err, { id }, context) => {
+      queryClient.setQueryData(queryKeys.users.detail(id), context?.previous);
+    },
+    onSettled: (_data, _err, { id }) => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.users.detail(id) });
+    },
+  });
+}
+```
+
+## Custom Hooks
+
+```ts
+// src/hooks/use-users.ts
+export function useUsers(filters?: UserFilters) {
+  return useQuery({
+    queryKey: queryKeys.users.list(filters ?? {}),
+    queryFn: () => getUserList(filters),
+  });
+}
+
+export function useUser(id: string) {
+  return useQuery({
+    queryKey: queryKeys.users.detail(id),
+    queryFn: () => getUserById(id),
+    enabled: !!id,
+  });
+}
+```
+
+## Prefetching with RSC
+
+```tsx
+// app/users/page.tsx (Server Component)
+import { HydrationBoundary, dehydrate, QueryClient } from "@tanstack/react-query";
+import { getUserList } from "@/actions/user.actions";
+import { queryKeys } from "@/lib/query-keys";
+import { UserList } from "./user-list";
+
+export default async function UsersPage() {
+  const queryClient = new QueryClient();
+  await queryClient.prefetchQuery({
+    queryKey: queryKeys.users.all,
+    queryFn: getUserList,
+  });
+
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <UserList />
+    </HydrationBoundary>
+  );
+}
+```

package/data/skills/resend-email/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: resend-email
+description: "Email sending patterns with Resend and React Email templates. Use when implementing transactional emails, creating email templates, or adding i18n email support."
+---
+
+# Resend Email Patterns
+
+## Critical Rules
+
+- **Emails via service layer** — never send directly from routes.
+- **React Email for templates** — type-safe, previewable components.
+- **I18n support** — every email must support multiple locales.
+- **Inline styles only** — CSS classes don't work in most email clients.
+- **Handle delivery webhooks** — bounces and complaints must be processed.
+- **Preview emails locally** — use `email dev` command during development.
+
+## Setup
+
+```ts
+// src/lib/resend.ts
+import { Resend } from "resend";
+
+export const resend = new Resend(process.env.RESEND_API_KEY);
+```
+
+## Email Service Layer
+
+- Emails are sent from a dedicated service — never from routes or components directly.
+- Located in `src/services/email.service.ts`.
+
+```ts
+// src/services/email.service.ts
+import { resend } from "@/lib/resend";
+import { WelcomeEmail } from "@/emails/welcome";
+import { InviteEmail } from "@/emails/invite";
+
+const FROM = "App Name <noreply@yourdomain.com>";
+
+export async function sendWelcomeEmail(to: string, name: string, locale: string) {
+  return resend.emails.send({
+    from: FROM,
+    to,
+    subject: getSubject("welcome", locale),
+    react: WelcomeEmail({ name, locale }),
+  });
+}
+
+export async function sendInviteEmail(
+  to: string,
+  inviterName: string,
+  orgName: string,
+  inviteUrl: string,
+  locale: string
+) {
+  return resend.emails.send({
+    from: FROM,
+    to,
+    subject: getSubject("invite", locale, { orgName }),
+    react: InviteEmail({ inviterName, orgName, inviteUrl, locale }),
+  });
+}
+```
+
+## React Email Templates
+
+```tsx
+// src/emails/welcome.tsx
+import {
+  Html, Head, Body, Container, Section, Text, Button, Hr,
+} from "@react-email/components";
+import { getEmailTranslations } from "@/lib/email-i18n";
+
+interface WelcomeEmailProps {
+  name: string;
+  locale: string;
+}
+
+export function WelcomeEmail({ name, locale }: WelcomeEmailProps) {
+  const t = getEmailTranslations(locale, "welcome");
+
+  return (
+    <Html>
+      <Head />
+      <Body style={body}>
+        <Container style={container}>
+          <Text style={heading}>{t("title", { name })}</Text>
+          <Text style={paragraph}>{t("description")}</Text>
+          <Section style={buttonSection}>
+            <Button style={button} href="https://app.yourdomain.com/dashboard">
+              {t("cta")}
+            </Button>
+          </Section>
+          <Hr style={hr} />
+          <Text style={footer}>{t("footer")}</Text>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+
+// Inline styles for email compatibility
+const body = { backgroundColor: "#f6f9fc", fontFamily: "sans-serif" };
+const container = { margin: "0 auto", padding: "40px 20px", maxWidth: "560px" };
+const heading = { fontSize: "24px", fontWeight: "bold", marginBottom: "16px" };
+const paragraph = { fontSize: "16px", lineHeight: "1.5", color: "#333" };
+const buttonSection = { textAlign: "center" as const, margin: "32px 0" };
+const button = {
+  backgroundColor: "#000", color: "#fff", padding: "12px 24px",
+  borderRadius: "6px", fontSize: "16px", textDecoration: "none",
+};
+const hr = { borderColor: "#e6ebf1", margin: "32px 0" };
+const footer = { fontSize: "12px", color: "#8898aa" };
+```
+
+## I18n for Emails
+
+```ts
+// src/lib/email-i18n.ts
+const emailMessages: Record<string, Record<string, Record<string, string>>> = {
+  en: {
+    welcome: {
+      title: "Welcome, {name}!",
+      description: "We're excited to have you on board.",
+      cta: "Go to Dashboard",
+      footer: "You received this email because you created an account.",
+    },
+    invite: {
+      title: "{inviterName} invited you to {orgName}",
+      description: "Click below to accept the invitation.",
+      cta: "Accept Invitation",
+    },
+  },
+  fr: {
+    welcome: {
+      title: "Bienvenue, {name} !",
+      description: "Nous sommes ravis de vous compter parmi nous.",
+      cta: "Aller au tableau de bord",
+      footer: "Vous avez reçu cet e-mail car vous avez créé un compte.",
+    },
+  },
+};
+
+export function getEmailTranslations(locale: string, namespace: string) {
+  const messages = emailMessages[locale]?.[namespace] ?? emailMessages.en[namespace];
+
+  return (key: string, params?: Record<string, string>) => {
+    let message = messages[key] ?? key;
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        message = message.replace(`{${k}}`, v);
+      }
+    }
+    return message;
+  };
+}
+```
+
+## Webhook for Delivery Status
+
+```ts
+// src/app/api/webhook/resend/route.ts
+import { NextResponse } from "next/server";
+
+export async function POST(request: Request) {
+  const payload = await request.json();
+
+  switch (payload.type) {
+    case "email.delivered":
+      // Log successful delivery
+      break;
+    case "email.bounced":
+      // Mark email as bounced, disable future sends
+      break;
+    case "email.complained":
+      // Unsubscribe user
+      break;
+  }
+
+  return NextResponse.json({ received: true });
+}
+```

package/data/skills/seo-optimization/SKILL.md

@@ -1,11 +1,19 @@
 ---
 name: seo-optimization
-description: "SEO best practices for structured data, meta tags, Core Web Vitals, and indexing. Use when building landing pages, marketing sites, or public-facing content."
-allowed-tools: "Read, Write, Edit, Glob, Grep"
+description: "SEO best practices for structured data, meta tags, Core Web Vitals, and indexing. Use when building landing pages, optimizing page metadata, adding JSON-LD structured data, generating sitemaps, or improving search engine performance."
 ---
 
 # SEO Optimization
 
+## Critical Rules
+
+- **Every page must have unique `title` and `description`** — never duplicate meta tags.
+- **One `<h1>` per page** — use proper heading hierarchy `h1` -> `h2` -> `h3`.
+- **Use semantic HTML** — `<main>`, `<article>`, `<section>`, `<nav>`, `<aside>`, `<footer>`.
+- **All images must have `alt` text** — descriptive, not keyword-stuffed.
+- **Target Core Web Vitals** — LCP < 2.5s, INP < 200ms, CLS < 0.1.
+- **Generate `sitemap.xml` and `robots.txt`** — never leave them missing on public sites.
+
 ## Meta Tags
 
 - Every page must have unique `title` and `description` meta tags:

package/data/skills/server-actions-patterns/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: server-actions-patterns
+description: "Next.js Server Actions with safe wrappers, validation, and error handling. Use when implementing mutations, creating form handlers, or building 'use server' functions."
+---
+
+# Server Actions Patterns
+
+## Critical Rules
+
+- **Always validate inputs** — never trust client data.
+- **Always check auth** — every action must verify the user session.
+- **Never expose internal errors** — return generic messages to the client.
+- **Revalidate after mutations** — stale UI is a bug.
+- **Keep actions thin** — delegate to facades/services for business logic.
+- **One action per mutation** — avoid multi-purpose actions.
+- **Never import server-only code in client files** — pass actions via props or use wrappers.
+
+## File Organization
+
+- Server Actions are defined in `src/actions/` directory.
+- One file per domain entity: `src/actions/{entity}.actions.ts`.
+- Every action file starts with `"use server"` directive at the top.
+
+```
+src/actions/
+  user.actions.ts
+  post.actions.ts
+  organization.actions.ts
+```
+
+## Safe Server Action Wrapper
+
+Use a `safeAction` wrapper for consistent validation, auth, and error handling:
+
+```ts
+// src/lib/safe-action.ts
+"use server";
+import { z } from "zod";
+import { getCurrentUser } from "@/lib/auth";
+
+type ActionResult<T> = { success: true; data: T } | { success: false; error: string };
+
+export function createSafeAction<TInput extends z.ZodType, TOutput>(
+  schema: TInput,
+  handler: (input: z.infer<TInput>, user: AuthUser) => Promise<TOutput>
+) {
+  return async (input: z.infer<TInput>): Promise<ActionResult<TOutput>> => {
+    try {
+      const user = await getCurrentUser();
+      if (!user) return { success: false, error: "Unauthorized" };
+
+      const parsed = schema.safeParse(input);
+      if (!parsed.success) {
+        return { success: false, error: parsed.error.errors[0].message };
+      }
+
+      const data = await handler(parsed.data, user);
+      return { success: true, data };
+    } catch (error) {
+      console.error("Action error:", error);
+      return { success: false, error: "An unexpected error occurred" };
+    }
+  };
+}
+```
+
+## Action Implementation
+
+```ts
+// src/actions/user.actions.ts
+"use server";
+
+import { z } from "zod";
+import { revalidatePath } from "next/cache";
+import { createSafeAction } from "@/lib/safe-action";
+import { updateUserProfile } from "@/facades/user.facade";
+
+const UpdateProfileSchema = z.object({
+  name: z.string().min(2).max(100),
+  bio: z.string().max(500).optional(),
+});
+
+export const updateProfile = createSafeAction(
+  UpdateProfileSchema,
+  async (input, user) => {
+    const result = await updateUserProfile(user.id, input);
+    revalidatePath("/profile");
+    return result;
+  }
+);
+```
+
+## Server-Only Modules
+
+- Mark server-only modules with the `server-only` package:
+```ts
+import "server-only";
+```
+- Use `"use server"` only in action files — never in utility or service files.
+
+## Integration with Forms
+
+### With useActionState (React 19)
+
+```tsx
+"use client";
+import { useActionState } from "react";
+import { updateProfile } from "@/actions/user.actions";
+
+export function ProfileForm() {
+  const [state, formAction, isPending] = useActionState(updateProfile, null);
+
+  return (
+    <form action={formAction}>
+      <input name="name" />
+      {state?.error && <p className="text-destructive">{state.error}</p>}
+      <button type="submit" disabled={isPending}>
+        {isPending ? "Saving..." : "Save"}
+      </button>
+    </form>
+  );
+}
+```
+
+### With react-hook-form
+
+```tsx
+"use client";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useTransition } from "react";
+import { updateProfile } from "@/actions/user.actions";
+import { toast } from "sonner";
+
+export function ProfileForm() {
+  const [isPending, startTransition] = useTransition();
+  const form = useForm({ resolver: zodResolver(UpdateProfileSchema) });
+
+  const onSubmit = form.handleSubmit((data) => {
+    startTransition(async () => {
+      const result = await updateProfile(data);
+      if (result.success) toast.success("Profile updated");
+      else toast.error(result.error);
+    });
+  });
+
+  return <form onSubmit={onSubmit}>{/* fields */}</form>;
+}
+```
+
+## Revalidation
+
+- Always call `revalidatePath()` or `revalidateTag()` after mutations.
+- Use path revalidation for simple cases: `revalidatePath("/users")`.
+- Use tag revalidation for granular cache control: `revalidateTag("user-list")`.
+- Redirect with `redirect()` after create operations when appropriate.

package/data/skills/shadcn-ui/SKILL.md

@@ -1,11 +1,19 @@
 ---
 name: shadcn-ui
-description: "ShadCN UI component patterns, composition, and accessibility guidelines. Use when building interfaces with ShadCN components. Inspired by ibelick/ui-skills baseline-ui."
-allowed-tools: "Read, Write, Edit, Glob, Grep"
+description: "ShadCN UI component patterns, forms, data tables, and page layouts. Use when building interfaces with ShadCN components, creating forms with react-hook-form, tables with TanStack Table, or designing page layouts."
 ---
 
 # ShadCN UI Patterns
 
+## Critical Rules
+
+- **Always use ShadCN primitives first** — before building custom components.
+- **Never rebuild keyboard or focus behavior** — use the component primitives.
+- **Never mix primitive systems** — don't combine Radix, Headless UI, React Aria in the same surface.
+- **Never use `h-screen`** — use `h-dvh` for correct mobile viewport.
+- **Empty states must have one clear next action** — never blank screens.
+- **No gradients or glow effects** unless explicitly requested.
+
 ## Installation & Setup
 
 - Install components individually with `npx shadcn@latest add <component>` — never install all at once.
@@ -27,8 +35,6 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
   - `Badge` for tags and status indicators
   - `Tabs` for content switching
   - `Toast` / `Sonner` for notifications
-- Never rebuild keyboard or focus behavior by hand — use the component primitives.
-- Never mix primitive systems (Radix, Headless UI, React Aria) within the same surface.
 
 ## Forms
 
@@ -52,6 +58,8 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
   - Add row actions via `DropdownMenu`.
 - Use `tabular-nums` on numeric columns for alignment.
 - Add loading skeletons with ShadCN `Skeleton` for async data.
+- **Toolbar pattern**: search input + result counter + limit selector in every table.
+- Hide columns progressively by breakpoint: `hidden sm:table-cell`, `hidden md:table-cell`.
 
 ## Dialogs & Alerts
 
@@ -60,6 +68,40 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 - Keep dialog content focused — one primary action per dialog.
 - Always provide a way to dismiss (close button, escape key, outside click).
 
+## Page Layout Pattern
+
+Structure pages with Cards for consistent visual hierarchy:
+
+```tsx
+// Header → Cards → Footer pattern
+<div className="space-y-6">
+  <div className="flex items-center justify-between">
+    <h1 className="text-3xl font-bold tracking-tight">Page Title</h1>
+    <Button>Primary Action</Button>
+  </div>
+
+  <Card>
+    <CardHeader><CardTitle>Section</CardTitle></CardHeader>
+    <CardContent>{/* content */}</CardContent>
+  </Card>
+</div>
+```
+
+- Multi-Card forms: split complex forms into logical Card sections.
+- Use `CardHeader` + `CardTitle` + `CardDescription` for section context.
+
+## Charts
+
+- Use `ChartContainer` from ShadCN with Recharts for data visualization.
+- Wrap charts in a `Card` with descriptive `CardHeader`.
+- Always include a `ChartTooltip` for data point details.
+
+## File Upload
+
+- Use a `FileUpload` dropzone component with drag-and-drop support.
+- Show preview for images, file name + size for documents.
+- Validate file type and size client-side before upload.
+
 ## Theming
 
 - Use CSS variables from the ShadCN theme system: `bg-background`, `text-foreground`, `bg-card`, `text-muted-foreground`, `bg-primary`, etc.
@@ -82,11 +124,3 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 - Keep interaction feedback under 200ms.
 - Avoid animating layout properties (`width`, `height`, `margin`, `padding`) — use `transform` and `opacity` only.
 - Respect `prefers-reduced-motion` media query.
-
-## Anti-Patterns to Avoid
-
-- Never use `h-screen` — use `h-dvh` for correct mobile viewport.
-- Never use arbitrary `z-index` values — use a fixed scale.
-- Never use gradients or glow effects unless explicitly requested.
-- Never use custom easing curves unless explicitly requested.
-- Empty states must have one clear next action.

package/data/skills/stripe-integration/SKILL.md

@@ -1,11 +1,19 @@
 ---
 name: stripe-integration
-description: "Stripe payment integration patterns for checkout, subscriptions, and webhooks. Use when building e-commerce, SaaS billing, or any payment flow."
-allowed-tools: "Read, Write, Edit, Glob, Grep"
+description: "Stripe payment integration patterns for checkout, subscriptions, webhooks, and customer portal. Use when implementing payments, building SaaS billing, handling Stripe webhooks, creating checkout flows, or managing subscription lifecycle."
 ---
 
 # Stripe Integration
 
+## Critical Rules
+
+- **Always use Stripe Checkout or Payment Elements** — never collect card details directly.
+- **Always verify webhook signatures** — never trust unverified payloads.
+- **Never expose `STRIPE_SECRET_KEY` to the client** — server-side only.
+- **Make webhook handlers idempotent** — the same event may arrive multiple times.
+- **Use `metadata` to link Stripe objects to database records** — always pass `userId`, `orderId`.
+- **Use `idempotencyKey` for critical operations** — prevent duplicate charges.
+
 ## Setup
 
 - Install `stripe` (server) and `@stripe/stripe-js` + `@stripe/react-stripe-js` (client).
@@ -21,7 +29,7 @@ allowed-tools: "Read, Write, Edit, Glob, Grep"
 
 ## Checkout
 
-- **Always use Stripe Checkout or Payment Elements** — never collect card details directly.
+- Always use Stripe Checkout or Payment Elements — never collect card details directly.
 - Create a Checkout Session server-side, redirect client-side:
   ```ts
   const session = await stripe.checkout.sessions.create({