@mars-stack/core 0.4.0

package/README.md

@@ -0,0 +1,32 @@
+# @mars-stack/core
+
+Core infrastructure for MARS apps -- auth, database, rate limiting, email, logging, and more.
+
+## Installation
+
+```bash
+yarn add @mars-stack/core
+```
+
+## What's included
+
+- **Auth** -- Session management (JWE), CSRF protection, password hashing (bcrypt + SHA-256 prehash), input validation
+- **Database** -- Prisma proxy with structured error diagnostics
+- **Rate limiting** -- Upstash Redis with in-memory fallback
+- **Email** -- Provider-agnostic email service (SendGrid, Resend, console)
+- **Logger** -- Structured logging via Pino
+- **Env** -- Zod-based environment validation with human-readable errors
+- **SEO** -- Metadata helpers and JSON-LD generation
+- **Test utils** -- Mock factories, request helpers, render utilities
+
+## Usage
+
+```ts
+import { checkRateLimit, RATE_LIMITS } from '@mars-stack/core/rate-limit';
+import { hashPassword, verifyPassword } from '@mars-stack/core/auth/password';
+import { apiSchemas } from '@mars-stack/core/auth/validation';
+```
+
+## License
+
+MIT

package/cursor/manifest.json

@@ -0,0 +1,304 @@
+{
+  "version": "1.0.0",
+  "description": "Mars skill manifest. Lists all available skills with triggers, dependencies, and capabilities.",
+  "skills": {
+    "add-api-route": {
+      "file": "skills/mars-add-api-route/SKILL.md",
+      "triggers": ["add api route", "create api endpoint", "new route handler"],
+      "dependencies": [],
+      "capabilities": ["file-edit"]
+    },
+    "add-component": {
+      "file": "skills/mars-add-component/SKILL.md",
+      "triggers": ["add component", "create component", "new component"],
+      "dependencies": [],
+      "capabilities": ["file-edit"]
+    },
+    "add-crud-routes": {
+      "file": "skills/mars-add-crud-routes/SKILL.md",
+      "triggers": ["add crud", "create crud routes", "add rest endpoints"],
+      "dependencies": ["add-api-route", "add-prisma-model"],
+      "capabilities": ["file-edit"]
+    },
+    "add-e2e-test": {
+      "file": "skills/mars-add-e2e-test/SKILL.md",
+      "triggers": ["add e2e test", "add playwright test", "add end to end test"],
+      "dependencies": [],
+      "capabilities": ["file-edit"]
+    },
+    "add-feature": {
+      "file": "skills/mars-add-feature/SKILL.md",
+      "triggers": ["add feature", "add module", "new feature"],
+      "dependencies": ["add-prisma-model", "add-api-route", "add-page"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "add-middleware": {
+      "file": "skills/mars-add-middleware/SKILL.md",
+      "triggers": ["add middleware", "create middleware"],
+      "dependencies": [],
+      "capabilities": ["file-edit"]
+    },
+    "add-page": {
+      "file": "skills/mars-add-page/SKILL.md",
+      "triggers": ["add page", "create page", "new page"],
+      "dependencies": [],
+      "capabilities": ["file-edit"]
+    },
+    "add-prisma-model": {
+      "file": "skills/mars-add-prisma-model/SKILL.md",
+      "triggers": ["add model", "add prisma model", "create database model"],
+      "dependencies": [],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "add-protected-resource": {
+      "file": "skills/mars-add-protected-resource/SKILL.md",
+      "triggers": ["add protected resource", "add auth resource"],
+      "dependencies": ["add-api-route"],
+      "capabilities": ["file-edit"]
+    },
+    "add-role": {
+      "file": "skills/mars-add-role/SKILL.md",
+      "triggers": ["add role", "create role", "new user role"],
+      "dependencies": [],
+      "capabilities": ["file-edit"]
+    },
+    "add-server-action": {
+      "file": "skills/mars-add-server-action/SKILL.md",
+      "triggers": ["add server action", "create server action"],
+      "dependencies": [],
+      "capabilities": ["file-edit"]
+    },
+    "add-webhook": {
+      "file": "skills/mars-add-webhook/SKILL.md",
+      "triggers": ["add webhook", "create webhook endpoint"],
+      "dependencies": ["add-api-route"],
+      "capabilities": ["file-edit"]
+    },
+    "build-dashboard": {
+      "file": "skills/mars-build-dashboard/SKILL.md",
+      "triggers": ["build dashboard", "create dashboard"],
+      "dependencies": ["add-page"],
+      "capabilities": ["file-edit"]
+    },
+    "build-data-table": {
+      "file": "skills/mars-build-data-table/SKILL.md",
+      "triggers": ["build data table", "create table view", "add table"],
+      "dependencies": ["add-component"],
+      "capabilities": ["file-edit"]
+    },
+    "build-form": {
+      "file": "skills/mars-build-form/SKILL.md",
+      "triggers": ["build form", "create form", "add form"],
+      "dependencies": ["add-component"],
+      "capabilities": ["file-edit"]
+    },
+    "build-landing-page": {
+      "file": "skills/mars-build-landing-page/SKILL.md",
+      "triggers": ["build landing page", "create landing page", "homepage"],
+      "dependencies": ["add-page"],
+      "capabilities": ["file-edit"]
+    },
+    "configure-email": {
+      "file": "skills/mars-configure-email/SKILL.md",
+      "triggers": ["configure email", "setup email", "add email provider"],
+      "dependencies": [],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-oauth": {
+      "file": "skills/mars-configure-oauth/SKILL.md",
+      "triggers": ["configure oauth", "add google login", "setup social auth"],
+      "dependencies": [],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-ai": {
+      "file": "skills/mars-configure-ai/SKILL.md",
+      "triggers": ["configure ai", "add openai", "add anthropic", "setup llm", "add chatbot", "add embeddings"],
+      "dependencies": ["add-feature", "add-api-route"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-i18n": {
+      "file": "skills/mars-configure-i18n/SKILL.md",
+      "triggers": ["configure i18n", "add translations", "setup internationalization", "add multi-language", "add localization"],
+      "dependencies": [],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-notifications": {
+      "file": "skills/mars-configure-notifications/SKILL.md",
+      "triggers": ["configure notifications", "add notifications", "add notification bell", "setup alerts", "add activity feed"],
+      "dependencies": ["add-feature", "add-api-route"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-jobs": {
+      "file": "skills/mars-configure-jobs/SKILL.md",
+      "triggers": ["configure jobs", "add background jobs", "setup task queue", "add cron jobs", "async processing"],
+      "dependencies": ["add-feature"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-multi-tenancy": {
+      "file": "skills/mars-configure-multi-tenancy/SKILL.md",
+      "triggers": ["configure multi-tenancy", "add organizations", "add teams", "add workspaces", "multi-tenant"],
+      "dependencies": ["add-feature", "add-prisma-model"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-payments": {
+      "file": "skills/mars-configure-payments/SKILL.md",
+      "triggers": ["configure payments", "add stripe", "setup billing"],
+      "dependencies": ["add-feature", "add-webhook"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-realtime": {
+      "file": "skills/mars-configure-realtime/SKILL.md",
+      "triggers": ["configure realtime", "add live updates", "add websockets", "add SSE", "add Pusher", "add Ably", "realtime notifications"],
+      "dependencies": ["add-feature"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-search": {
+      "file": "skills/mars-configure-search/SKILL.md",
+      "triggers": ["configure search", "add search", "setup full-text search", "add algolia", "add meilisearch"],
+      "dependencies": ["add-feature"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-storage": {
+      "file": "skills/mars-configure-storage/SKILL.md",
+      "triggers": ["configure storage", "add file upload", "setup blob storage"],
+      "dependencies": ["add-api-route"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "create-seed": {
+      "file": "skills/mars-create-seed/SKILL.md",
+      "triggers": ["create seed", "add seed data", "database seed"],
+      "dependencies": [],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "design-tokens": {
+      "file": "skills/mars-design-tokens/SKILL.md",
+      "triggers": ["design tokens", "customize theme", "change colors", "brand colors"],
+      "dependencies": [],
+      "capabilities": ["file-edit"]
+    },
+    "setup-project": {
+      "file": "skills/mars-setup-project/SKILL.md",
+      "triggers": ["setup project", "initialize project", "get started"],
+      "dependencies": [],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "test-api-route": {
+      "file": "skills/mars-test-api-route/SKILL.md",
+      "triggers": ["test api route", "add api test", "test endpoint"],
+      "dependencies": [],
+      "capabilities": ["file-edit"]
+    },
+    "configure-email-verification": {
+      "file": "skills/mars-configure-email-verification/SKILL.md",
+      "triggers": ["configure email verification", "add email verification", "verify email", "resend verification"],
+      "dependencies": ["configure-email"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-magic-links": {
+      "file": "skills/mars-configure-magic-links/SKILL.md",
+      "triggers": ["configure magic links", "add passwordless login", "magic link auth", "email login"],
+      "dependencies": ["configure-email"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-two-factor": {
+      "file": "skills/mars-configure-two-factor/SKILL.md",
+      "triggers": ["configure 2fa", "add two-factor", "add totp", "add authenticator", "add backup codes"],
+      "dependencies": ["add-feature"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-dark-mode": {
+      "file": "skills/mars-configure-dark-mode/SKILL.md",
+      "triggers": ["configure dark mode", "add dark mode", "add theme toggle", "light dark switch"],
+      "dependencies": ["design-tokens"],
+      "capabilities": ["file-edit"]
+    },
+    "configure-onboarding": {
+      "file": "skills/mars-configure-onboarding/SKILL.md",
+      "triggers": ["configure onboarding", "add onboarding", "setup wizard", "welcome flow", "first-time user"],
+      "dependencies": ["add-feature", "add-prisma-model"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "add-blog": {
+      "file": "skills/mars-add-blog/SKILL.md",
+      "triggers": ["add blog", "create blog", "add mdx blog", "add articles", "add posts"],
+      "dependencies": ["add-page"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-analytics": {
+      "file": "skills/mars-configure-analytics/SKILL.md",
+      "triggers": ["configure analytics", "add analytics", "add tracking", "add vercel analytics", "add posthog", "add google analytics"],
+      "dependencies": [],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "add-command-palette": {
+      "file": "skills/mars-add-command-palette/SKILL.md",
+      "triggers": ["add command palette", "add cmd k", "add spotlight", "add quick search", "add keyboard shortcuts"],
+      "dependencies": ["add-component"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "configure-feature-flags": {
+      "file": "skills/mars-configure-feature-flags/SKILL.md",
+      "triggers": ["configure feature flags", "add feature toggles", "feature flags", "gradual rollout", "a/b testing"],
+      "dependencies": ["add-feature", "add-prisma-model"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "add-audit-log": {
+      "file": "skills/mars-add-audit-log/SKILL.md",
+      "triggers": ["add audit log", "add activity tracking", "audit logging", "compliance logging"],
+      "dependencies": ["add-prisma-model", "add-api-route"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "add-error-boundary": {
+      "file": "skills/mars-add-error-boundary/SKILL.md",
+      "triggers": ["add error boundary", "error handling", "add error page", "sentry integration", "global error handler"],
+      "dependencies": ["add-component"],
+      "capabilities": ["file-edit", "terminal"]
+    },
+    "deploy-to-vercel": {
+      "file": "skills/mars-deploy-to-vercel/SKILL.md",
+      "triggers": ["deploy to vercel", "vercel deployment", "deploy to production", "go live", "publish app"],
+      "dependencies": [],
+      "capabilities": ["terminal"]
+    },
+    "create-execution-plan": {
+      "file": "skills/mars-create-execution-plan/SKILL.md",
+      "triggers": ["create execution plan", "create plan", "plan work", "track progress"],
+      "dependencies": [],
+      "capabilities": ["file-edit"]
+    },
+    "update-architecture-docs": {
+      "file": "skills/mars-update-architecture-docs/SKILL.md",
+      "triggers": ["update docs", "update architecture", "sync docs", "update quality score", "refresh documentation"],
+      "dependencies": [],
+      "capabilities": ["file-edit"]
+    },
+    "build-complete-feature": {
+      "file": "skills/mars-build-complete-feature/SKILL.md",
+      "triggers": ["build complete feature", "add full feature", "build feature end to end", "implement feature"],
+      "dependencies": ["create-execution-plan", "add-prisma-model", "add-feature", "add-api-route", "add-crud-routes", "add-page", "test-api-route", "add-e2e-test", "update-architecture-docs"],
+      "capabilities": ["file-edit", "terminal"],
+      "meta": true
+    },
+    "setup-billing": {
+      "file": "skills/mars-setup-billing/SKILL.md",
+      "triggers": ["setup billing", "add subscriptions", "add paywall", "stripe end to end", "billing system"],
+      "dependencies": ["create-execution-plan", "configure-payments", "add-prisma-model", "add-webhook", "add-feature", "add-api-route", "add-page", "test-api-route", "update-architecture-docs"],
+      "capabilities": ["file-edit", "terminal"],
+      "meta": true
+    },
+    "setup-teams": {
+      "file": "skills/mars-setup-teams/SKILL.md",
+      "triggers": ["setup teams", "add organizations", "add team management", "multi-tenancy end to end", "org switching"],
+      "dependencies": ["create-execution-plan", "configure-multi-tenancy", "add-prisma-model", "add-feature", "add-crud-routes", "add-page", "test-api-route", "update-architecture-docs"],
+      "capabilities": ["file-edit", "terminal"],
+      "meta": true
+    },
+    "capture-conversation-context": {
+      "file": "skills/mars-capture-conversation-context/SKILL.md",
+      "triggers": ["capture context", "feed back", "save decisions", "document conversation", "end of session"],
+      "dependencies": ["create-execution-plan", "update-architecture-docs"],
+      "capabilities": ["file-edit"],
+      "meta": true
+    }
+  }
+}

package/cursor/rules/mars-composition-patterns.mdc

@@ -0,0 +1,186 @@
+---
+description: React composition patterns — compound components, state lifting, explicit variants
+globs: **/*.tsx
+alwaysApply: false
+---
+
+## Composition Over Configuration
+
+When building components, prefer composition over boolean props. These patterns apply to all feature components and any new primitives/patterns added to `@mars-stack/ui`.
+
+Source: [Vercel Composition Patterns](https://github.com/vercel-labs/agent-skills/tree/main/skills/composition-patterns)
+
+## 1. No Boolean Prop Proliferation (CRITICAL)
+
+Don't add boolean props like `isThread`, `isEditing`, `isCompact` to customise component behaviour. Each boolean doubles possible states and creates unmaintainable conditional logic.
+
+**Wrong:**
+
+```tsx
+function Composer({ isThread, isEditing, isForwarding, showAttachments }: Props) {
+  return (
+    <form>
+      <Input />
+      {isThread ? <ThreadField /> : isEditing ? <EditActions /> : <DefaultActions />}
+      {showAttachments && <Attachments />}
+    </form>
+  );
+}
+```
+
+**Right — create explicit variants that compose shared parts:**
+
+```tsx
+function ThreadComposer({ channelId }: { channelId: string }) {
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <AlsoSendToChannelField channelId={channelId} />
+      <Composer.Footer>
+        <Composer.Submit />
+      </Composer.Footer>
+    </Composer.Frame>
+  );
+}
+
+function EditComposer() {
+  return (
+    <Composer.Frame>
+      <Composer.Input />
+      <Composer.Footer>
+        <Composer.CancelEdit />
+        <Composer.SaveEdit />
+      </Composer.Footer>
+    </Composer.Frame>
+  );
+}
+```
+
+## 2. Compound Components with Shared Context (HIGH)
+
+Structure complex components as compound components. Subcomponents access shared state via context, not props. Consumers compose the pieces they need.
+
+```tsx
+const ComposerContext = createContext<ComposerContextValue | null>(null);
+
+function ComposerFrame({ children }: { children: React.ReactNode }) {
+  return <form>{children}</form>;
+}
+
+function ComposerInput() {
+  const { state, actions: { update } } = use(ComposerContext);
+  return <TextInput value={state.input} onChangeText={(text) => update((s) => ({ ...s, input: text }))} />;
+}
+
+const Composer = {
+  Frame: ComposerFrame,
+  Input: ComposerInput,
+  Submit: ComposerSubmit,
+  // ...
+};
+```
+
+Export compound components as a namespace object, not individual exports.
+
+## 3. Generic Context Interfaces (HIGH)
+
+Define context with three parts: `state`, `actions`, `meta`. This interface is a contract that any provider can implement — enabling the same UI to work with different state implementations.
+
+```tsx
+interface ComposerContextValue {
+  state: { input: string; attachments: Attachment[]; isSubmitting: boolean };
+  actions: { update: (updater: (s: State) => State) => void; submit: () => void };
+  meta: { inputRef: React.RefObject<HTMLTextAreaElement> };
+}
+```
+
+UI components consume the interface. Providers implement it. Swap the provider, keep the UI.
+
+## 4. Lift State into Providers (HIGH)
+
+Move state into dedicated provider components. This lets sibling components outside the main UI access state without prop drilling.
+
+**Wrong — state trapped in component:**
+
+```tsx
+function ForwardDialog() {
+  return (
+    <Dialog>
+      <ForwardComposer />
+      <MessagePreview /> {/* Can't access composer state */}
+      <ForwardButton /> {/* Can't call submit */}
+    </Dialog>
+  );
+}
+```
+
+**Right — state in provider, UI siblings can access it:**
+
+```tsx
+function ForwardDialog() {
+  return (
+    <ForwardProvider>
+      <Dialog>
+        <ForwardComposer />
+        <MessagePreview /> {/* Reads state from context */}
+        <ForwardButton /> {/* Calls submit from context */}
+      </Dialog>
+    </ForwardProvider>
+  );
+}
+```
+
+Components that need shared state don't have to be visually nested — they just need to be within the same provider.
+
+## 5. Decouple State from UI (MEDIUM)
+
+The provider is the only place that knows how state is managed. UI components consume the context interface — they don't know if state comes from `useState`, Zustand, or a server sync.
+
+```tsx
+// Local state provider
+function ForwardProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = useState(initialState);
+  return <Composer.Provider state={state} actions={{ update: setState, submit }}>{children}</Composer.Provider>;
+}
+
+// Global synced state provider — same UI works with both
+function ChannelProvider({ channelId, children }: Props) {
+  const { state, update, submit } = useGlobalChannel(channelId);
+  return <Composer.Provider state={state} actions={{ update, submit }}>{children}</Composer.Provider>;
+}
+```
+
+## 6. Children Over Render Props (MEDIUM)
+
+Use `children` for composition. Use render props only when the parent needs to pass data back to the child (e.g., list items with index).
+
+**Wrong:**
+
+```tsx
+<Composer renderHeader={() => <Header />} renderFooter={() => <Footer />} />
+```
+
+**Right:**
+
+```tsx
+<Composer.Frame>
+  <Header />
+  <Composer.Input />
+  <Footer />
+</Composer.Frame>
+```
+
+## 7. React 19 APIs
+
+This project uses React 19. Follow these conventions:
+
+- **No `forwardRef`** — `ref` is a regular prop in React 19.
+- **Use `use()` instead of `useContext()`** — `use()` can be called conditionally.
+
+```tsx
+// Right (React 19)
+function ComposerInput({ ref, ...props }: Props & { ref?: React.Ref<HTMLTextAreaElement> }) {
+  const { state } = use(ComposerContext);
+  return <textarea ref={ref} value={state.input} {...props} />;
+}
+```

package/cursor/rules/mars-data-access.mdc

@@ -0,0 +1,26 @@
+---
+description: Database and data access patterns
+globs: **/server/**
+alwaysApply: false
+---
+
+## Prisma
+
+- Import the lazy-loaded client: `import { prisma } from '@/lib/prisma'`.
+- User-scoped queries MUST include `userId` from the authenticated session in the `where` clause, never from request parameters.
+- Use `$transaction` for multi-step writes that must be atomic.
+- New models go in `prisma/schema/` as separate `.prisma` files (multi-file schema).
+- After changing the schema: `yarn db:push` (dev) or `yarn db:migrate dev` (with migration history).
+
+## Error Handling
+
+- API route catch blocks MUST use `handleApiError(error, { endpoint })` from `@/lib/mars`.
+- `handleApiError` automatically detects Prisma errors and logs actionable diagnostics (connection refused, auth failed, missing tables, SSL issues) to the terminal.
+- Database errors return HTTP 503 to clients. Zod validation errors return 400. Everything else returns 500.
+- Never expose raw database error messages to the client.
+
+## File Handling
+
+- File proxy routes MUST stream `response.body` instead of buffering with `arrayBuffer()`.
+- Enforce max file size checks from the DB record before fetching.
+- Sanitize filenames in `Content-Disposition` headers.

package/cursor/rules/mars-project-structure.mdc

@@ -0,0 +1,34 @@
+---
+description: Project structure and import conventions
+globs:
+alwaysApply: true
+---
+
+## Directory Layout
+
+- `src/lib/` -- Wiring layer: `mars.ts` (re-exports logger, email, api-error, auth middleware, session, CSRF from `@mars-stack/core`) and `prisma.ts` (database client).
+- UI primitives (Button, Input, Select, etc.) and patterns (Card, Modal, FormField) come from the `@mars-stack/ui` package.
+- Shared hooks come from `@mars-stack/ui/hooks`.
+- `src/features/<name>/` -- Feature modules with their own `components/`, `server/`, `hooks/`, `validation/`.
+- `src/config/` -- `app.config.ts` (single source of truth) and `routes.ts`.
+- `src/styles/` -- Design tokens: `primitives.css` → `tokens.css` → `theme.css`.
+
+## Import Rules
+
+- Use `@/lib/prisma` for the database client, `@/lib/mars` for core infrastructure (logger, email, api-error, auth wrappers, session, CSRF).
+- Use `@mars-stack/ui` for UI primitives and patterns, `@mars-stack/ui/hooks` for shared hooks.
+- Use `@mars-stack/core/rate-limit` for rate limiting, `@mars-stack/core/test-utils` for test utilities, `@mars-stack/core/auth/hooks` for auth hooks, `@mars-stack/core/auth/validation` for auth validation schemas.
+- `features/` may import from `@/lib/`, `@mars-stack/*`, and `config/`. Features MUST NOT import from other features.
+- `app/` may import from anywhere.
+
+## Naming
+
+- Use named exports. Default exports only for Next.js pages/layouts.
+- Prefer explicit TypeScript types. No `any` -- use `unknown` and narrow.
+- Barrel exports (`index.ts`) at the boundary of each module for clean imports.
+
+## Config
+
+- `app.config.ts` is the single source of truth for app identity, feature flags, theme, and service providers.
+- Check `appConfig.features.*` before wiring up optional functionality.
+- Environment variables are validated lazily via `src/core/env/`. Add new vars to `buildEnvSchema()`.

package/cursor/rules/mars-security.mdc

@@ -0,0 +1,25 @@
+---
+description: Security guardrails for all code changes
+globs:
+alwaysApply: true
+---
+
+## Authentication & Authorization
+
+- Every API route under `src/app/api/protected/` MUST use `withAuth`, `withAuthNoParams`, `withRole`, or `withOwnership` from `@/lib/mars`.
+- Admin-only routes MUST use `withRole(['admin'], ...)` which verifies the role against the database on every request. Never trust the JWT role claim alone.
+- Ownership-gated routes MUST use `withOwnership`. Never accept a `userId` parameter from the client for authorization.
+- Public auth endpoints (`login`, `signup`, `forgot`, `reset`, `verify`) MUST call `checkRateLimit` with the appropriate `RATE_LIMITS` config from `@mars-stack/core/rate-limit`.
+
+## Secrets
+
+- Use constant-time comparison (`constantTimeEqual`) for all secret/token/signature comparisons. Never use `===` for secrets.
+- CSRF keys are derived from `JWT_SECRET` via HMAC with a domain separator; never reuse `JWT_SECRET` directly.
+- Never log secrets, tokens, or full authorization headers.
+- Server-only modules MUST import `"server-only"` at the top to prevent client-side bundling.
+
+## Serverless Constraints
+
+- No `setInterval` / `setTimeout` for background cleanup; use lazy-on-read patterns.
+- No in-memory queues or global mutable state that assumes process persistence.
+- Background processing should fire a separate HTTP request, not rely on fire-and-forget promises.

package/cursor/rules/mars-testing.mdc

@@ -0,0 +1,24 @@
+---
+description: Testing conventions
+globs: **/*.test.ts,**/*.test.tsx
+alwaysApply: false
+---
+
+## Framework
+
+- Unit tests: Vitest (`yarn test`). Config at `vitest.config.ts`.
+- E2E tests: Playwright (`yarn test:e2e`). Config at `playwright.config.ts`.
+- Test files live next to the code they test: `route.test.ts` beside `route.ts`.
+
+## Mocking
+
+- Use `@mars-stack/core/test-utils/mock-auth` to mock authenticated sessions in API route tests.
+- Use `@mars-stack/core/test-utils/factories` for consistent test data.
+- Mock Prisma with `vi.mock('@/lib/prisma')` and provide typed mocks for each model method.
+
+## Patterns
+
+- Test API routes by calling the exported handler directly, not via HTTP.
+- Assert both the response body and status code.
+- Test error paths: invalid input (Zod), unauthorized, not found, database errors.
+- Unit tests MUST NOT depend on external services (database, Redis, email). Mock everything.

package/cursor/rules/mars-ui-conventions.mdc

@@ -0,0 +1,29 @@
+---
+description: UI component and styling conventions
+globs: **/*.tsx
+alwaysApply: false
+---
+
+## Design Token System
+
+MARS uses a three-layer CSS token system. Never use raw Tailwind colour classes (e.g., `text-gray-900`). Always use semantic tokens:
+
+- **Surfaces**: `bg-surface-background`, `bg-surface-card`, `bg-surface-elevated`, `bg-surface-input`
+- **Text**: `text-text-primary`, `text-text-secondary`, `text-text-muted`, `text-text-link`, `text-text-error`
+- **Borders**: `border-border-default`, `border-border-input`, `border-border-focus`, `border-border-error`
+- **Brand**: `bg-brand-primary`, `bg-brand-primary-hover`, `text-text-on-brand`
+- **Feedback**: `bg-success-muted`, `text-text-success`, `bg-error-muted`, `text-text-error`
+- **Interactive**: `bg-ghost-hover`, `bg-ghost-active`, `bg-danger-bg`, `focus:ring-ring-focus`
+
+## Component Architecture
+
+- **Primitives** (`@mars-stack/ui`): Single-responsibility, fully styled via tokens, accept `className` for overrides. Examples: `Button`, `Input`, `Badge`, `Avatar`, `Spinner`.
+- **Patterns** (`@mars-stack/ui`): Compose primitives, no business logic. Examples: `Card`, `Modal`, `Toast`, `FormField`, `EmptyState`.
+- **Feature components** (`src/features/<name>/components/`): Contain business logic, compose primitives and patterns.
+
+## Rules
+
+- Always import components from `@mars-stack/ui` (both primitives and patterns are exported from this package).
+- Use `clsx` for conditional class composition.
+- New shared primitives go in the `@mars-stack/ui` package.
+- Components MUST support dark mode via the token system (tokens swap automatically with `.dark` class).