mcp-subagents-opencode 1.0.0

package/build/templates/overlays/coder-supabase.mdx

@@ -0,0 +1,268 @@
+## SUPABASE-SPECIFIC GUIDELINES
+
+You are working in a codebase that uses **Supabase**. Apply these principles with zero exceptions.
+
+### Client Initialization — Choose the Right Client
+
+- **Browser / Client Components:** Use `createBrowserClient` from `@supabase/ssr` — NOT `createClient` from `@supabase/supabase-js`
+- **Server Components / Server Actions / Route Handlers:** Use `createServerClient` from `@supabase/ssr` with cookie methods (`getAll`, `setAll`)
+- **Edge Functions / server-only scripts:** Use `createClient` from `@supabase/supabase-js` — this is the ONLY place it belongs in an SSR app
+- **Service role client:** Create with `createServerClient` using the service role key and empty cookie methods (`getAll: () => []`). NEVER use in client code
+- **NEVER create a singleton server client** — server clients are request-scoped (cookies are per-request). Use a factory function like `createServerSupabaseClient()` called per-request
+- **ALWAYS pass `<Database>` generic** to every client: `createClient<Database>(url, key)`
+- Project structure: `lib/supabase/client.ts` (browser), `lib/supabase/server.ts` (server), `lib/supabase/middleware.ts` (session refresh)
+
+### Middleware — NON-NEGOTIABLE for SSR Auth
+
+- **ALWAYS implement middleware** that calls `updateSession()` on every request — without it, sessions silently expire, causing random logouts
+- Use `matcher` config to exclude static assets: `matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)']`
+- The middleware refreshes the JWT and sets updated cookies — if you skip this, auth WILL break
+- Wrap `setAll` in try/catch in Server Components (cookies are read-only there)
+
+### TypeScript Types — Generate and Use Them
+
+- **ALWAYS generate types:** `npx supabase gen types typescript --project-id "$PROJECT_ID" > src/database.types.ts`
+- For local dev: `npx supabase gen types typescript --local > src/database.types.ts`
+- Add a `package.json` script: `"gen:types": "supabase gen types typescript --project-id $PROJECT_ID > src/database.types.ts"`
+- **Extract row types properly:** `type User = Database['public']['Tables']['users']['Row']`
+- **Insert types:** `type NewUser = Database['public']['Tables']['users']['Insert']`
+- **Update types:** `type UserUpdate = Database['public']['Tables']['users']['Update']`
+- Regenerate types after EVERY schema change — never hand-edit `database.types.ts`
+- If a view column appears incorrectly as nullable, use `MergeDeep` from `type-fest` to override
+- Known issue: field ordering in generated types can be inconsistent across runs — do NOT rely on git diff of types for CI gates
+
+### Row Level Security (RLS) — ALWAYS ENABLE
+
+- **Enable RLS on EVERY table** in the `public` schema — no exceptions. Tables without RLS are fully exposed via the API
+- RLS with no policies = zero access (not even authenticated users). Always create policies after enabling
+- **Wrap auth functions in `(select ...)`** for performance: use `(select auth.uid()) = user_id` NOT `auth.uid() = user_id` — this caches the result per-statement instead of evaluating per-row (100x+ improvement on large tables)
+- **Target specific roles:** Add `TO authenticated` on policies — don't rely on `auth.uid()` alone to exclude `anon`
+- **Separate policies per operation:** Create distinct SELECT, INSERT, UPDATE, DELETE policies — never one catch-all
+- **NEVER use `user_metadata` in RLS policies** — users can modify their own `user_metadata` via the API
+- **Add indexes on RLS-referenced columns** — e.g., if policy checks `user_id`, add `CREATE INDEX idx_table_user_id ON table(user_id)`
+- For team/tenant access patterns: `team_id IN (SELECT team_id FROM team_members WHERE user_id = (select auth.uid()))` — always put the user filter in the subquery, not the outer query
+- **Use security definer functions** for complex RLS logic — but put them in a non-public schema to prevent API exposure
+- Views bypass RLS by default. For Postgres 15+, use `CREATE VIEW ... WITH (security_invoker = true)`
+
+### Database Queries — Correct Patterns
+
+```typescript
+// CORRECT: Select with typed response
+const { data, error } = await supabase
+  .from('posts')
+  .select('id, title, author:profiles(name, avatar_url)')
+  .eq('published', true)
+  .order('created_at', { ascending: false })
+  .limit(20)
+
+// CORRECT: Insert with returning data
+const { data, error } = await supabase
+  .from('posts')
+  .insert({ title, body, user_id: userId })
+  .select()
+  .single()
+
+// CORRECT: Update with filter
+const { data, error } = await supabase
+  .from('posts')
+  .update({ title: newTitle })
+  .eq('id', postId)
+  .select()
+  .single()
+
+// CORRECT: Null check — use .is(), NOT .eq()
+const { data } = await supabase
+  .from('posts')
+  .select()
+  .is('deleted_at', null)
+```
+
+- **ALWAYS handle `error`** — never destructure only `data`. Check `if (error) throw error` or handle gracefully
+- **Select only needed columns** — `.select('id, name')` not `.select('*')` — reduces payload and improves performance
+- Use `.single()` when expecting exactly one row, `.maybeSingle()` when zero or one
+- For joins: `.select('*, comments(*)')` uses PostgREST resource embedding — requires foreign key relationships
+- For `.rpc()` joins to work, Postgres functions MUST use `RETURNS SETOF <table_name>` — NOT `RETURNS TABLE(...)`
+- Use `.or()` for OR conditions: `.or('status.eq.active,status.eq.pending')`
+- Paginate with `.range(from, to)` — never fetch unbounded results
+
+### Auth — Patterns and Anti-Patterns
+
+```typescript
+// CORRECT: Server-side user check (ALWAYS use getUser, not getSession for auth checks)
+const { data: { user }, error } = await supabase.auth.getUser()
+if (!user) redirect('/login')
+
+// CORRECT: Sign up
+const { data, error } = await supabase.auth.signUp({
+  email,
+  password,
+  options: { data: { full_name: name } } // goes to user_metadata
+})
+
+// CORRECT: Sign in with password
+const { data, error } = await supabase.auth.signInWithPassword({ email, password })
+
+// CORRECT: Magic link / OTP
+const { error } = await supabase.auth.signInWithOtp({
+  email,
+  options: { shouldCreateUser: false } // prevent auto-signup
+})
+
+// CORRECT: OAuth
+const { data, error } = await supabase.auth.signInWithOAuth({
+  provider: 'google',
+  options: { redirectTo: `${origin}/auth/callback` }
+})
+
+// CORRECT: Auth callback route handler (app/auth/callback/route.ts)
+const { searchParams } = new URL(request.url)
+const code = searchParams.get('code')
+if (code) {
+  const supabase = await createServerSupabaseClient()
+  await supabase.auth.exchangeCodeForSession(code)
+}
+return NextResponse.redirect(new URL('/dashboard', request.url))
+```
+
+- **Use `getUser()` for auth verification, not `getSession()`** — `getSession` reads from cookies without server validation; `getUser` makes a server call to verify the JWT
+- **PKCE flow is the default** in `@supabase/ssr` — don't switch to implicit flow
+- **ALWAYS implement the `/auth/callback` route** for PKCE code exchange
+- Never store tokens manually — `@supabase/ssr` handles cookie storage automatically
+- For magic links: edit the email template to use `{{ .TokenHash }}` with `type=magiclink` params for PKCE compatibility
+- Session data from the server can be passed to client via React Context (`AuthProvider`) to avoid redundant `getUser()` calls
+
+### Storage — Buckets and Uploads
+
+- **Default to private buckets** — public buckets bypass download access control entirely
+- Private bucket access requires either: a valid JWT in the Authorization header, or a signed URL
+- **RLS policies on `storage.objects`** control all storage operations — no policies = no uploads allowed
+- **Use signed upload URLs** for client-side uploads to avoid body size limits (Next.js defaults to 1MB):
+
+```typescript
+// Server Action: create signed upload URL
+const { data, error } = await supabase.storage
+  .from('avatars')
+  .createSignedUploadUrl(`${userId}/${fileName}`)
+
+// Client: upload to signed URL
+const { error } = await supabase.storage
+  .from('avatars')
+  .uploadToSignedUrl(data.path, data.token, file)
+```
+
+- **Scope file paths to user IDs:** `{user_id}/filename.ext` — then write RLS policies that match `(storage.foldername(name))[1] = (select auth.uid())::text`
+- Signed download URLs have a configurable expiry — keep it as short as practical
+- For public assets (logos, static images): use a public bucket but understand anyone with the URL can access the file
+- **Upsert requires SELECT + UPDATE + INSERT policies** — not just INSERT
+
+### Edge Functions — Deno Runtime
+
+```typescript
+// CORRECT: Modern Edge Function pattern
+Deno.serve(async (req: Request) => {
+  // CORS handling
+  if (req.method === 'OPTIONS') {
+    return new Response('ok', {
+      headers: {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'POST, OPTIONS',
+        'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
+      },
+    })
+  }
+
+  // Create Supabase client with user's JWT
+  const supabase = createClient<Database>(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_ANON_KEY')!,
+    { global: { headers: { Authorization: req.headers.get('Authorization')! } } }
+  )
+
+  const { data: { user } } = await supabase.auth.getUser()
+  // ... function logic
+
+  return new Response(JSON.stringify({ success: true }), {
+    headers: { 'Content-Type': 'application/json' },
+  })
+})
+```
+
+- **Use `Deno.serve()`** — do NOT import `serve` from `deno.land/std`
+- **Import specifiers:** Use `npm:@supabase/supabase-js` — NOT bare `@supabase/supabase-js`. Always pin versions: `npm:express@4.18.2`
+- **Pre-populated env vars:** `SUPABASE_URL`, `SUPABASE_ANON_KEY`, `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_DB_URL` are available automatically — do NOT set them manually
+- **Shared code** goes in `supabase/functions/_shared/` — import via relative path. Never cross-import between functions
+- **Fat functions pattern:** Group related routes into one function using Hono or Express — minimizes cold starts
+- Use `EdgeRuntime.waitUntil(promise)` for background tasks that shouldn't block the response
+- File writes only allowed in `/tmp`
+- Design for idempotency — Edge Functions can be retried
+
+### Realtime — Use Wisely
+
+```typescript
+// Postgres Changes (simple, but doesn't scale well)
+const channel = supabase
+  .channel('posts-changes')
+  .on('postgres_changes',
+    { event: 'INSERT', schema: 'public', table: 'posts', filter: 'room_id=eq.123' },
+    (payload) => handleNewPost(payload.new)
+  )
+  .subscribe()
+
+// Broadcast (preferred for most real-time use cases)
+const channel = supabase.channel('room-123')
+channel.on('broadcast', { event: 'cursor-move' }, ({ payload }) => {
+  updateCursor(payload)
+})
+channel.subscribe()
+channel.send({ type: 'broadcast', event: 'cursor-move', payload: { x, y } })
+
+// Presence
+const channel = supabase.channel('room-123')
+channel.on('presence', { event: 'sync' }, () => {
+  const state = channel.presenceState()
+  updateOnlineUsers(state)
+})
+channel.subscribe(async (status) => {
+  if (status === 'SUBSCRIBED') {
+    await channel.track({ user_id: userId, online_at: new Date().toISOString() })
+  }
+})
+```
+
+- **Prefer Broadcast over Postgres Changes** for scale — Postgres Changes checks RLS for every subscriber on every change (100 subscribers = 100 reads per change)
+- **Unsubscribe on cleanup:** `supabase.removeChannel(channel)` in `useEffect` cleanup / `onUnmounted`
+- Postgres Changes are processed on a single thread — they do NOT scale with compute upgrades
+- Realtime does NOT guarantee delivery — design your app to handle missed messages
+- Default limits: 100 channels per tenant, 200 concurrent users per channel, 100 events/second
+- For high-throughput: use a dedicated "broadcast" table without RLS and filter on the client
+
+### API Keys — Critical Security Rules
+
+- **Anon key / publishable key** (`NEXT_PUBLIC_SUPABASE_ANON_KEY`): Safe for client-side. RLS protects your data. This key is meant to be public
+- **Service role key / secret key**: Bypasses ALL RLS. **NEVER expose in client code, NEVER prefix with `NEXT_PUBLIC_`**
+- The service role key goes in server-only environment variables
+- When creating a client with the service role key, the `Authorization` header defaults to that key — so ALL queries bypass RLS automatically
+- **Key rotation:** Supabase is migrating from JWT-based anon/service_role keys to publishable (`sb_publishable_...`) and secret keys. Be aware that Edge Functions may need `--no-verify-jwt` with the new key format
+- In Edge Functions: verify the user via `supabase.auth.getUser()` — do NOT trust the JWT blindly
+
+### Connection Management
+
+- **Use Supavisor (connection pooler)** for server-side connections from ORMs (Prisma, Drizzle) — port `6543` for Transaction Mode, port `5432` for Session Mode
+- **Transaction Mode** (port 6543): Shares connections, higher throughput, but NO prepared statements — incompatible with Prisma unless using `@prisma/adapter-pg`
+- **Session Mode** (port 5432): Supports prepared statements, required by Prisma's default adapter
+- If using the Supabase client library (`supabase-js`), you do NOT need Supavisor — it uses the REST API (PostgREST), not direct Postgres connections
+- Keep pooler usage under 40% of max connections if also using REST API, Auth, Realtime, and Storage (they share the connection pool)
+- Add `?pgbouncer=true` to connection strings when using Prisma with Supavisor
+
+### Common Anti-Patterns — NEVER Do These
+
+- **NEVER disable RLS** "to make things work" — fix your policies instead
+- **NEVER use `select('*')` in production** — select only the columns you need
+- **NEVER put business logic in RLS policies** — keep RLS simple (auth checks only), put business logic in application code or Edge Functions
+- **NEVER manage schema through the Dashboard UI in production** — use migrations (`supabase migration new`, SQL files in `supabase/migrations/`)
+- **NEVER call `getSession()` for auth verification** on the server — it reads cookies without validating the JWT. Use `getUser()` instead
+- **NEVER store the service role key in `NEXT_PUBLIC_*` env vars** or any client-accessible location
+- **NEVER use `user_metadata` for authorization decisions** — users can modify their own metadata
+- **NEVER create tables without thinking about RLS first** — add policies immediately after table creation
+- **NEVER use bare `catch` without handling** — Supabase errors contain `code`, `message`, `details`, and `hint` fields. Log them all
+- **NEVER dump everything into the `public` schema** — use custom schemas for internal tables, keeping only API-facing tables in `public`

package/build/templates/overlays/coder-supastarter.mdx

@@ -0,0 +1,313 @@
+## SUPASTARTER CODING GUIDELINES
+
+You are working in a **Supastarter** monorepo (Next.js App Router). Follow these conventions exactly.
+
+---
+
+### MONOREPO STRUCTURE
+
+```
+apps/
+  web/                    # Next.js SaaS app (App Router)
+  mail-preview/           # Email template previewer
+  docs/                   # Documentation site
+packages/
+  api/                    # oRPC procedures & Hono handlers
+  auth/                   # Better Auth config
+  database/               # Prisma + Drizzle schema & queries
+  ui/                     # Shadcn UI components
+  mail/                   # React Email templates
+  payments/               # Stripe/Polar/other providers
+  ai/                     # Vercel AI SDK wrappers
+  i18n/                   # next-intl config & translations
+  logs/                   # Logger utilities
+  storage/                # S3/file storage
+  utils/                  # Shared utilities
+config/                   # Workspace-level config
+tooling/                  # Build tooling & shared configs
+```
+
+---
+
+### IMPORTS & PATH ALIASES
+
+Always use path aliases. Never use deep relative imports.
+
+```typescript
+// Good
+import { Button } from "@repo/ui/components/button";
+import { cn } from "@repo/ui";
+import { getSession } from "@saas/auth/lib/server";
+import { db } from "@repo/database";
+
+// Bad
+import { Button } from "../../../packages/ui/components/button.tsx";
+```
+
+| Alias | Maps To |
+|-------|---------|
+| `@/*` | `apps/web/*` |
+| `@marketing/*` | `apps/web/modules/marketing/*` |
+| `@saas/*` | `apps/web/modules/saas/*` |
+| `@shared/*` | `apps/web/modules/shared/*` |
+| `@repo/*` | `packages/*` |
+
+---
+
+### REACT SERVER COMPONENTS
+
+Default to Server Components. Only add `"use client"` for interactivity, browser APIs, hooks (`useQuery`, `useMutation`), or forms.
+
+```typescript
+// Server Component (default)
+import { getSession } from "@saas/auth/lib/server";
+import { redirect } from "next/navigation";
+
+export default async function ProtectedPage() {
+  const session = await getSession();
+  if (!session) redirect("/auth/login");
+  return <div>Welcome, {session.user.name}</div>;
+}
+
+// Client Component (only when necessary)
+"use client";
+import { useState } from "react";
+export function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+Keep client components small and focused.
+
+---
+
+### MODULE ORGANIZATION
+
+```
+apps/web/modules/
+  saas/
+    auth/           # components/, hooks/, lib/, constants/, config.ts
+    organizations/  # components/, hooks/, lib/
+    payments/
+    settings/
+    admin/
+    ai/
+  shared/           # Cross-cutting components, hooks, lib
+  marketing/        # Marketing-only components, lib
+```
+
+---
+
+### API LAYER (oRPC)
+
+Procedures live at `packages/api/modules/[feature]/procedures/[action].ts`:
+
+```typescript
+import { protectedProcedure } from "../../../orpc/procedures";
+import { z } from "zod";
+import { ORPCError } from "@orpc/client";
+
+export const submitContactForm = publicProcedure
+  .route({ method: "POST", path: "/contact", tags: ["Contact"] })
+  .input(z.object({
+    name: z.string().min(3),
+    email: z.string().email(),
+    message: z.string().min(10),
+  }))
+  .use(localeMiddleware)
+  .handler(async ({ input, context }) => {
+    // Implementation
+  });
+```
+
+**Procedure types:** `publicProcedure` (no auth), `protectedProcedure` (requires session), `adminProcedure` (requires admin role).
+
+**Client-side data fetching:**
+```typescript
+"use client";
+import { useQuery } from "@tanstack/react-query";
+import { orpc } from "@shared/lib/orpc-query-utils";
+
+export function UsersList() {
+  const { data, isLoading } = useQuery(orpc.users.list.queryOptions());
+  if (isLoading) return <Skeleton />;
+  return <ul>{data?.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+---
+
+### DATABASE (Drizzle)
+
+```typescript
+import { eq } from "drizzle-orm";
+import { db } from "../client";
+
+export async function getUserById(id: string) {
+  return await db.query.user.findFirst({
+    where: (user, { eq }) => eq(user.id, id),
+  });
+}
+
+export async function createUser(data: UserCreateInput) {
+  const [{ id }] = await db
+    .insert(user)
+    .values({ ...data, createdAt: new Date(), updatedAt: new Date() })
+    .returning({ id: user.id });
+  return await getUserById(id);
+}
+```
+
+Import from `@repo/database` exports — never raw Prisma imports.
+
+---
+
+### AUTH (Better Auth)
+
+```typescript
+// Server-side (ALWAYS use getSession from @saas/auth/lib/server)
+const session = await getSession();
+if (!session) redirect("/auth/login");
+
+// Client-side
+"use client";
+import { useSession } from "@saas/auth/hooks/use-session";
+const { user, loaded } = useSession();
+```
+
+Features: email/password, OAuth (Google, GitHub), magic link, passkey, 2FA, organization-scoped.
+
+---
+
+### UI COMPONENTS (Shadcn + CVA)
+
+```typescript
+import { cva } from "class-variance-authority";
+import { cn } from "../lib";
+
+const buttonVariants = cva(
+  "flex items-center justify-center font-medium transition-colors",
+  {
+    variants: {
+      variant: { primary: "bg-primary text-primary-foreground", secondary: "bg-secondary" },
+      size: { sm: "h-6 px-3 text-xs", md: "h-9 px-4 text-sm", lg: "h-12 px-6 text-base" },
+    },
+    defaultVariants: { variant: "secondary", size: "md" },
+  },
+);
+```
+
+Use `cn()` for class merging. Use `<Button loading={...}>` prop for loading states.
+
+---
+
+### FORMS (React Hook Form + Zod)
+
+```typescript
+"use client";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useForm } from "react-hook-form";
+import { z } from "zod";
+import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@repo/ui/components/form";
+
+const formSchema = z.object({ email: z.string().email(), name: z.string().min(3) });
+
+export function ContactForm() {
+  const form = useForm({ resolver: zodResolver(formSchema), defaultValues: { email: "", name: "" } });
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        <FormField control={form.control} name="email"
+          render={({ field }) => (
+            <FormItem><FormLabel>Email</FormLabel><FormControl><Input {...field} /></FormControl><FormMessage /></FormItem>
+          )} />
+        <Button type="submit" loading={form.formState.isSubmitting}>Submit</Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+---
+
+### I18N (next-intl)
+
+```typescript
+// Server Component
+import { getTranslations, setRequestLocale } from "next-intl/server";
+const t = await getTranslations();
+return <h1>{t("home.welcome.title")}</h1>;
+
+// Client Component
+"use client";
+import { useTranslations } from "next-intl";
+const t = useTranslations();
+```
+
+---
+
+### NAMING CONVENTIONS
+
+| Type | Convention | Example |
+|------|-----------|---------|
+| Directories | kebab-case | `components/auth-form/` |
+| Components | PascalCase.tsx | `LoginForm.tsx` |
+| Functions | camelCase | `getUser()`, `handleSubmit()` |
+| Booleans | is/has/can prefix | `isLoading`, `hasError` |
+| Constants | SCREAMING_SNAKE | `MAX_RETRIES` |
+| Types | PascalCase | `UserProps`, `AuthConfig` |
+
+---
+
+### TYPESCRIPT RULES
+
+- Named exports only — never default exports
+- `as const` assertions — never enums
+- Strict typing — no `any` without justification
+- Client env vars: prefix with `NEXT_PUBLIC_`
+- Use `@repo/logs` logger — never `console.log` in production
+
+---
+
+### CONFIGURATION
+
+```typescript
+// apps/web/config.ts
+export const config = {
+  appName: "supastarter",
+  saas: { enabled: true, redirectAfterSignIn: "/app" },
+  marketing: { enabled: true },
+} as const;
+
+// Import: import { config } from "@/config";
+```
+
+Each package has scoped config. Import via `@repo/[package]/config`.
+
+---
+
+### BUILD & TOOLING
+
+```bash
+pnpm dev          # Start dev (Turbo)
+pnpm build        # Build all packages
+pnpm type-check   # TypeScript check
+pnpm lint         # Biome lint
+pnpm format       # Biome format
+pnpm e2e          # Playwright E2E tests
+```
+
+---
+
+### ANTI-PATTERNS
+
+- Deep relative imports — use path aliases
+- Default exports — use named exports
+- Enums — use `as const` + type extraction
+- `select('*')` — select only needed columns
+- Raw Prisma imports — use `@repo/database`
+- `console.log` — use `@repo/logs` logger
+- Hardcoded strings — use i18n translations
+- Missing `NEXT_PUBLIC_` prefix — server vars won't reach the client
+- Singleton server Supabase clients — server clients are request-scoped

package/build/templates/overlays/coder-swift.mdx

@@ -0,0 +1,56 @@
+## SWIFT-SPECIFIC GUIDELINES
+
+You are working in a **Swift** codebase. Apply these principles with zero exceptions.
+
+### Protocol-Oriented Programming
+- Prefer **protocols** over class inheritance — Swift is protocol-oriented, not class-oriented
+- Use protocol extensions for default implementations — avoid abstract base classes
+- Use `associatedtype` for generic protocol requirements
+- Compose behavior with multiple protocol conformances: `struct User: Identifiable, Codable, Hashable`
+- Use `some Protocol` (opaque return types) to hide implementation details
+
+### Optionals — Safety First
+- Use `guard let` for early exit unwrapping — keep the happy path unindented
+- Use `if let` for conditional unwrapping when the `else` case continues execution
+- **Never force-unwrap** (`!`) in production code — use `guard let`, `if let`, or `??`
+- Use nil-coalescing `??` for default values: `let name = user?.name ?? "Unknown"`
+- Use optional chaining `?.` for accessing nested optionals
+- Use `compactMap` to filter out nils from collections
+
+### Value vs Reference Types
+- Prefer **structs** (value types) over classes — structs are the default in Swift
+- Use **classes** only when you need: identity (reference semantics), inheritance, deinit, or Objective-C interop
+- Use `mutating` keyword on struct methods that modify `self`
+- Understand copy-on-write behavior for large value types (Array, String, Dictionary have COW built in)
+
+### Error Handling
+- Use `throws` functions with typed errors when possible (Swift 6+)
+- Create error enums conforming to `Error`: `enum AuthError: Error { case invalidToken, expired }`
+- Use `do/try/catch` with specific error cases — avoid `try?` unless you intentionally want to discard the error
+- Use `Result<Success, Failure>` for asynchronous error handling in callback-based APIs
+
+### Modern Swift Patterns
+- Use **async/await** for concurrency (Swift 5.5+) — prefer over completion handlers
+- Use **actors** for thread-safe mutable state
+- Use `@Sendable` closures and `Sendable` types for concurrency safety
+- Use `Task` and `TaskGroup` for structured concurrency
+- Use `@MainActor` for UI-related code
+
+### SwiftUI Patterns (if applicable)
+- Use `@State` for view-local state, `@Binding` for parent-owned state
+- Use `@ObservedObject` / `@StateObject` for reference-type view models
+- Use `@Environment` for dependency injection from the environment
+- Keep views small — extract subviews as separate structs
+- Use `ViewModifier` for reusable view modifications
+
+### Naming Conventions
+- `camelCase` for functions, methods, properties, variables
+- `PascalCase` for types, protocols, enums
+- Follow Swift API Design Guidelines: methods read as English phrases
+- Factory methods: `make*` (e.g., `makeIterator()`)
+- Boolean properties: `is*`, `has*`, `can*`, `should*`
+
+### Testing Considerations
+- Use protocol-based dependency injection for testability
+- Prefer value types that are `Equatable` — easy to assert in tests
+- Use `XCTAssert*` or project's testing framework conventions