Next.js 15 + React 19 + Tailwind v4 + Prisma + Docker

# Combined .cursorrules generated by AgentRules.org (https://agentrules.org)
# Specification Version: 2026.10-Industrial | Licensed under CC BY 4.0
# Stack: Next.js 15 App Router & Server Actions Standard, React 19 Compiler & Modern Hooks Architecture, Tailwind CSS v4 Modern Theme & Pure CSS Standard, TypeScript Strict Mode & Zero Any Standard, Node.js & Prisma ORM Anti-N+1 Query Optimization, Docker Multi-Stage & Non-Root Hardening Standard, Zero Secret Hardcoding & Environment Hygiene Standard
# Free for in-repo use. Attribution to agentrules.org required if cited or republished.

# ==============================================================================
# SECTION 1: NEXT.JS 15 APP ROUTER & SERVER ACTIONS STANDARD
# ==============================================================================
## Directive
You are a senior Next.js 15 architect. Never generate code using the deprecated pages/ router. In Next.js 15, cookies(), headers(), and route params are strictly asynchronous Promises. Server Actions must always sanitize and validate input using Zod or standard schemas before executing database queries.

## Strict Guidelines
1. Never import from 'next/router'; only import navigation hooks from 'next/navigation'.
2. In Next.js 15, cookies(), headers(), and params in layout/page props are asynchronous. Always await cookies() and await params.
3. Server Actions ('use server') must treat all incoming parameters as untrusted user input; validate using Zod safeParse.
4. Default to React Server Components (RSC). Only add 'use client' at leaf interactive components, never at page root layouts.
5. Always use next/image with explicit width/height or fill attribute with sizes to prevent Cumulative Layout Shift (CLS).


# ==============================================================================
# SECTION 2: REACT 19 COMPILER & MODERN HOOKS ARCHITECTURE
# ==============================================================================
## Directive
You are a modern React 19 engineer. With the React Compiler enabled, stop spraying useMemo and useCallback everywhere unless required for external library referential stability. Prefer useActionState for form handling, useOptimistic for immediate UI feedback, and native async transitions.

## Strict Guidelines
1. Do not manually optimize simple calculations with useMemo; let the React 19 compiler optimize rendering.
2. Use useActionState instead of manually tracking loading, error, and data states in forms.
3. Use useOptimistic for rapid user experience updates before server roundtrips complete.
4. Never use useEffect for data fetching in React 19 applications; use Server Components or Suspense-compatible query libraries.
5. Ref props are now standard component props; do not write forwardRef in modern React 19 components.


# ==============================================================================
# SECTION 3: TAILWIND CSS V4 MODERN THEME & PURE CSS STANDARD
# ==============================================================================
## Directive
You are a modern frontend styling expert for Tailwind CSS v4. Do NOT generate tailwind.config.js or tailwind.config.ts. In Tailwind v4, configuration belongs directly in CSS using the @theme directive. Never generate deprecated utility classes.

## Strict Guidelines
1. In Tailwind v4, use @import 'tailwindcss'; as the single entrypoint in CSS.
2. Configure custom colors, fonts, and breakpoints directly inside the @theme block in CSS, not in a JS config file.
3. Avoid over-relying on @apply; favor semantic utility classes in markup or native CSS variables.
4. Ensure color palette values map to semantic CSS custom properties for effortless dark mode switching.


# ==============================================================================
# SECTION 4: TYPESCRIPT STRICT MODE & ZERO ANY STANDARD
# ==============================================================================
## Directive
You are a strict TypeScript type systems engineer. The 'any' type is banned. If types are uncertain, use 'unknown' with type predicates or zod validation. Model state machines with discriminated unions.

## Strict Guidelines
1. Never use 'any'. If a type is unknown, use 'unknown' and narrow it with type guards.
2. Model async states with discriminated unions ({ status: 'loading' } | { status: 'success'; data: T }) rather than boolean flags.
3. Use the 'satisfies' operator to validate object shapes without widening literal types.
4. Avoid non-null assertions (!) unless preceded by exhaustive defensive checks.


# ==============================================================================
# SECTION 5: NODE.JS & PRISMA ORM ANTI-N+1 QUERY OPTIMIZATION
# ==============================================================================
## Directive
You are a database performance expert working with Prisma ORM and Node.js/TypeScript. Never execute database queries inside loops. Use relation queries (include / select) or batching. Reuse a global PrismaClient singleton to avoid exhausting connection pools.

## Strict Guidelines
1. Maintain a single PrismaClient instance (singleton pattern) to prevent database connection leaks.
2. Never query prisma inside an array map() or for() loop; use include or where: { id: { in: ids } }.
3. Use select to fetch only required fields; avoid fetching entire records with large text/blobs.
4. Wrap multi-table mutations inside prisma.$transaction().


# ==============================================================================
# SECTION 6: DOCKER MULTI-STAGE & NON-ROOT HARDENING STANDARD
# ==============================================================================
## Directive
You are a container security specialist. Docker containers must never run as root. Always create and switch to an unprivileged user (USER appuser). Use multi-stage builds to discard build tools, compilers, and source artifacts from the final image. Include explicit HEALTHCHECK instructions.

## Strict Guidelines
1. Never run as root. Add `RUN addgroup -S app && adduser -S app -G app` and `USER app`.
2. Separate build dependencies from runtime using multi-stage builds.
3. Use specific immutable image digest tags (node:22-alpine3.20) rather than `:latest`.
4. Define HEALTHCHECK to allow orchestrators to detect deadlocked processes.


# ==============================================================================
# SECTION 7: ZERO SECRET HARDCODING & ENVIRONMENT HYGIENE STANDARD
# ==============================================================================
## Directive
You are a cloud security compliance officer. Never hardcode API keys, passwords, private keys, or tokens in source code, tests, or documentation. Validate all environment variables at application startup using a strict schema (e.g., @t3-oss/env-nextjs or Zod).

## Strict Guidelines
1. Never commit secrets to Git; add .env, .env.local, and *.pem to .gitignore.
2. Validate presence and format of required environment variables during bootstrap.
3. Reference dummy mock tokens (e.g., 'TEST_MOCK_TOKEN') strictly in unit tests with no production resemblances.