create-tigra 1.1.0 → 2.0.1

package/template/_claude/rules/client/03-data-and-state.md

@@ -0,0 +1,156 @@
+> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
+
+# Data, State & API Integration
+
+## State Decision Matrix
+
+| State Type | Tool | When |
+|---|---|---|
+| Server data (initial page load) | Server Components | SEO-critical, page-level data |
+| Server data (client-triggered) | React Query | User actions, real-time updates, mutations |
+| Global client state | Redux | Auth user + init/logout state — **nothing else** |
+| Local UI state | `useState` / `useReducer` | Modals, hover, form inputs |
+| URL-shareable state | `useSearchParams` | Filters, pagination, search query |
+
+### Anti-patterns
+
+- **No server state in Redux.** Use Server Components or React Query.
+- **No UI state in Redux** (modals, loading). Use local state.
+- **Prefer Server Component fetch** over client-side `useQuery` when the data is available at page level.
+
+---
+
+## React Query Config
+
+Defaults in `app/providers.tsx`:
+
+```typescript
+staleTime: 5 * 60 * 1000    // 5 min
+gcTime: 10 * 60 * 1000      // 10 min
+refetchOnWindowFocus: false
+retry: 1
+```
+
+### Query Key Factory Pattern
+
+```typescript
+export const itemKeys = {
+  all: ['items'] as const,
+  lists: () => [...itemKeys.all, 'list'] as const,
+  list: (filters: ItemFilters) => [...itemKeys.lists(), filters] as const,
+  details: () => [...itemKeys.all, 'detail'] as const,
+  detail: (id: string) => [...itemKeys.details(), id] as const,
+};
+```
+
+### Mutations
+
+On success: invalidate related queries, show toast, navigate if needed.
+On error: `toast.error(getErrorMessage(error))`.
+
+---
+
+## Redux
+
+**Scope**: Auth only. Single slice: `authSlice` with actions: `setUser`, `setInitialized`, `setLoggingOut`, `logout`.
+
+Typed hooks in `store/hooks.ts`: `useAppDispatch`, `useAppSelector`.
+
+State shape:
+```typescript
+{ user: IUser | null; isAuthenticated: boolean; isInitializing: boolean; isLoggingOut: boolean }
+```
+
+**Not persisted to localStorage** — auth state is hydrated on page load by `AuthInitializer` calling `getMe()`. Tokens are stored in httpOnly cookies (not accessible from JS).
+
+---
+
+## Axios Config
+
+`lib/api/axios.config.ts` — singleton `apiClient`:
+
+- **Base URL**: `process.env.NEXT_PUBLIC_API_BASE_URL` (fallback `http://localhost:8000/api/v1`)
+- **Timeout**: 30s
+- **`withCredentials: true`**: Sends httpOnly cookies automatically with every request.
+- **No request interceptor** — cookies handle auth, no `Authorization` header needed.
+- **Response interceptor**: On 401, attempts token refresh via `/auth/refresh` (cookie sent automatically). Queues concurrent 401s to avoid multiple refresh attempts. If refresh fails, dispatches `logout()` and redirects to `/login`.
+
+---
+
+## Service Pattern
+
+Services are **classes**, singleton-exported, using `apiClient` and `API_ENDPOINTS`.
+
+```typescript
+class ItemService {
+  async getItems(params?: ItemFilters & PaginationParams): Promise<PaginatedData<Item>>
+  async getItem(id: string): Promise<Item>
+  async createItem(data: CreateItemRequest): Promise<Item>
+  async updateItem(id: string, data: UpdateItemRequest): Promise<Item>
+  async deleteItem(id: string): Promise<void>
+}
+export const itemService = new ItemService();
+```
+
+Auth service methods: `register`, `login`, `logout`, `refreshToken`, `getMe`, `verifyEmail`, `requestPasswordReset`, `resetPassword`.
+
+---
+
+## Error Handling
+
+```typescript
+// lib/utils/error.ts
+export const getErrorMessage = (error: unknown): string => {
+  // Checks: axios error → ApiError shape → network error → generic Error → fallback string
+};
+```
+
+**Toast library**: `sonner`. Use `toast.success()`, `toast.error(getErrorMessage(error))`.
+
+---
+
+## Next.js Caching Defaults
+
+| Data type | Strategy | Example |
+|---|---|---|
+| General content | `next: { revalidate: 60 }` | Items list |
+| User-specific | `cache: 'no-store'` | User profile |
+| Static lookups | `cache: 'force-cache'` | Categories, settings |
+
+Use `revalidatePath()` / `revalidateTag()` in Server Actions after mutations.
+
+---
+
+## Forms
+
+**Approach**: Hybrid — React Hook Form + Zod for client-side validation, Server Action for submission.
+
+### Password Schema Requirements
+
+```typescript
+z.string()
+  .min(8, 'Min 8 characters')
+  .regex(/[A-Z]/, 'Must contain uppercase')
+  .regex(/[a-z]/, 'Must contain lowercase')
+  .regex(/[0-9]/, 'Must contain number')
+```
+
+### File Upload Validation
+
+- Allowed types: `image/jpeg`, `image/png`, `image/webp`
+- Max size: 5MB
+- Validate extension AND MIME type
+
+### Form Rules
+
+- Show field-level errors below the field (red text + red border).
+- Disable submit button during submission.
+- Never clear the form on error — preserve user input.
+- Use `useFormStatus` for pending states in Server Action forms.
+
+---
+
+## Utility Defaults
+
+- **Default currency**: `USD` for `formatCurrency`.
+- **Date format**: `Intl.DateTimeFormat('en-US', { year: 'numeric', month: 'long', day: 'numeric' })`.

package/template/_claude/rules/client/04-design-system.md

@@ -0,0 +1,185 @@
+> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
+
+# Design System
+
+## Philosophy: "Neuro-Minimalism"
+
+Clean, airy, "expensive" look inspired by Linear, Vercel, Stripe, Arc. Every visual decision reduces cognitive load.
+
+---
+
+## CSS Architecture (Source of Truth)
+
+This project uses **Tailwind CSS v4** with **OKLCH color space** and the `@theme inline` directive (not the legacy `tailwind.config.ts`).
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+  /* ... maps all semantic tokens to Tailwind */
+}
+
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --primary: oklch(0.45 0.2 260);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.45 0.2 260);
+  --success: oklch(0.52 0.17 155);
+  --success-foreground: oklch(1 0 0);
+  --warning: oklch(0.75 0.18 75);
+  --warning-foreground: oklch(0.2 0 0);
+  --info: oklch(0.55 0.15 240);
+  --info-foreground: oklch(1 0 0);
+  --chart-1 through --chart-5  /* Data visualization colors */
+  --sidebar, --sidebar-foreground, etc.  /* Sidebar-specific tokens */
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  /* ... dark mode overrides for all tokens */
+}
+```
+
+**Key differences from Tailwind v3:**
+- No `tailwind.config.ts` — all config is CSS-based via `@theme inline`
+- Colors use **OKLCH** (perceptually uniform) not HSL
+- `@custom-variant dark` replaces `darkMode: 'class'`
+- No `@layer base { :root { } }` — variables defined directly on `:root`
+
+## Color Usage
+
+| Token | Purpose | Example use |
+|---|---|---|
+| `primary` | Main CTAs, links, active states | "Get started" button |
+| `secondary` | Secondary actions | Cancel, back |
+| `destructive` | Delete, errors | Delete button, error alert |
+| `success` | Success states | "Action completed" |
+| `warning` | Warnings | "Pending approval" |
+| `info` | Information | "New feature" badge |
+| `muted` | Disabled, placeholders | Disabled input |
+| `accent` | Highlights | "Featured" badge |
+| `card` | Card backgrounds | Content card |
+| `border` | Borders, dividers | Card border |
+
+### Color Rules
+
+1. **Never hardcode**: No `bg-blue-500`, no `bg-[#3b82f6]`, no `style={{ color }}`. Always semantic tokens.
+2. **Semantic names by purpose**: `bg-destructive` not `bg-red`.
+3. **Always pair bg + foreground**: `bg-primary text-primary-foreground` for contrast.
+4. **Single source of truth**: Change colors only in `globals.css` variables.
+5. **90% monochrome**: 90% of UI uses `background`, `foreground`, `muted`, `border`. Color is the exception.
+6. **Opacity for hierarchy**: Use `bg-primary/10`, `bg-primary/5` for tinted backgrounds.
+
+---
+
+## Surfaces & Depth
+
+- **Border radius**: `rounded-xl` (12px) or `rounded-2xl` (16px) for cards, modals, containers.
+- **Shadows** (layered by elevation):
+  - Resting cards: `shadow-sm`
+  - Hovered/elevated: `shadow-md` to `shadow-lg`
+  - Modals/popovers: `shadow-xl`
+- **Glassmorphism**: Only on sticky headers, floating toolbars, modal backdrops. Never on content cards.
+  `backdrop-filter: blur(12px) saturate(1.5); background: oklch(from var(--background) l c h / 0.8);`
+- **No pure black/white**: Use `--background` and `--foreground` tokens (already off-pure).
+
+---
+
+## Typography
+
+- **Font**: Inter v4 (variable) or Geist Sans via `next/font`.
+- **Headings**: `text-wrap: balance`, `leading-tight`. H1: `text-3xl`–`text-4xl`, H2: `text-2xl`.
+- **Body**: `text-base`, `leading-relaxed`. Max reading width: `max-w-prose` (~65ch).
+- **Data/numbers**: Always `tabular-nums` for alignment.
+- **Captions/meta**: `text-sm text-muted-foreground`.
+
+---
+
+## Spacing
+
+- **Whitespace IS the divider.** Prefer spacing over visible borders/lines.
+- **Section gap = 2x internal gap**: `space-y-16` between sections, `space-y-6` within.
+- **Stick to scale**: `4, 6, 8, 12, 16, 20, 24` from Tailwind. Avoid arbitrary values.
+- **Container**: `container mx-auto px-4 md:px-6 lg:px-8`.
+
+---
+
+## Motion & Interactions
+
+Every interactive element MUST have visible `:hover`, `:active`, and `:focus-visible` states.
+
+### Standard Patterns
+```
+Button:  transition-all duration-200 ease-out hover:brightness-110 active:scale-[0.98]
+Card:    transition-all duration-300 ease-out hover:shadow-lg hover:-translate-y-0.5
+Link:    transition-colors duration-150 hover:text-primary
+```
+
+### Rules
+- **Transform + opacity only** — never animate layout properties (`width`, `height`, `top`).
+- **Respect `prefers-reduced-motion`**: Use `motion-safe:` / `motion-reduce:` variants.
+- **Motion budget**: Max 2-3 animated elements in viewport at once.
+- **Zero CLS**: Animations must never cause layout shift.
+
+---
+
+## Images
+
+- **Format priority**: AVIF > WebP > JPEG (Next.js `<Image>` handles this).
+- **LCP image**: Always add `priority` prop.
+- **Blur placeholder**: Use `placeholder="blur"` with `blurDataURL`.
+- **Always set** explicit `width`/`height` or use `aspect-ratio` to prevent CLS.
+
+---
+
+## Modern CSS Features (Use Where Appropriate)
+
+| Feature | Use for |
+|---|---|
+| `@container` | Component-level responsive behavior |
+| CSS Subgrid | Child alignment with parent grid |
+| `dvh` | Full-height layouts (avoids mobile browser bar) |
+| `<dialog>` | Modals (with glassmorphism backdrop) |
+| Popover API | Dropdowns, tooltips |
+| `:has()` | Parent-based styling without JS |
+| `content-visibility: auto` | Long lists/pages performance |
+| `@starting-style` | Entry animations |
+
+---
+
+## Component Visual Patterns
+
+- **Cards**: `rounded-xl border border-border/50 bg-card shadow-sm transition-all duration-300 hover:shadow-md hover:-translate-y-0.5`
+- **Empty states**: Centered, muted icon, 2-line text max, one clear CTA.
+- **Loading**: Skeleton loaders matching content shape. Show immediately, no delay.
+- **Modals**: Max `max-w-lg`. Dismissible with Escape + backdrop click. Glassmorphism backdrop.
+
+---
+
+## Dark Mode
+
+- Use `next-themes` with `attribute="class"`, `defaultTheme="system"`.
+- Reduce shadow visibility in dark mode (use subtle light borders instead).
+- Consider `brightness-90` on images in dark mode.
+- Add `suppressHydrationWarning` to `<html>` tag.

package/template/_claude/rules/client/05-security.md

@@ -0,0 +1,55 @@
+> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
+
+# Security
+
+## Token Storage
+
+- **httpOnly cookies** (`access_token` + `refresh_token`) set by the server via `Set-Cookie` headers.
+- Tokens are **never accessible from JavaScript** — no localStorage, no Redux token state.
+- Axios sends cookies automatically via `withCredentials: true`.
+- `AuthInitializer` hydrates user state on page load by calling `getMe()` (cookie sent automatically).
+- On logout: call logout API endpoint (server clears cookies), dispatch `logout()` action, redirect to `/login`.
+
+## Environment Variables
+
+- **Never prefix secrets with `NEXT_PUBLIC_`** — only public values (API URL, app name) get the prefix.
+- Server-only secrets (DB URL, JWT secret) have no prefix and are only accessible in Server Components / Server Actions.
+- Validate env with Zod at startup.
+
+## File Upload Validation
+
+- Allowed types: `image/jpeg`, `image/png`, `image/webp`
+- Max size: 5MB
+- Validate both MIME type AND file extension.
+
+## Security Headers (`next.config.ts`)
+
+```
+X-Frame-Options: DENY
+X-Content-Type-Options: nosniff
+Referrer-Policy: origin-when-cross-origin
+X-XSS-Protection: 1; mode=block
+```
+
+## Content Security Policy
+
+```
+default-src 'self';
+script-src 'self' 'unsafe-eval' 'unsafe-inline';
+style-src 'self' 'unsafe-inline';
+img-src 'self' blob: data: https:;
+font-src 'self';
+object-src 'none';
+base-uri 'self';
+form-action 'self';
+frame-ancestors 'none';
+connect-src 'self' ${NEXT_PUBLIC_API_BASE_URL};
+```
+
+## Rules
+
+1. **Never inject raw HTML** without sanitizing it first (use DOMPurify with allowed tags/attrs).
+2. **Never log sensitive data** (tokens, passwords, full user objects). Dev-only: log IDs at most.
+3. **Validate all inputs** with Zod — client-side (UX) AND server-side (security).
+4. **External links**: Always `target="_blank" rel="noopener noreferrer"`.
+5. **Sanitize URLs**: Only allow `http:`, `https:`, `mailto:` protocols before rendering as links.

package/template/_claude/rules/client/06-ux-checklist.md

@@ -0,0 +1,81 @@
+> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
+
+# Neuro-UX Checklist
+
+## Cognitive Load — Miller's Law
+
+- **Max 5-7 interactive elements** per viewport section. Use progressive disclosure (tabs, accordions, "Show more") for more.
+
+## Gestalt Principles
+
+- **Proximity**: Related items close together. Gap between groups = 2x gap within groups.
+- **Grid alignment**: All elements on a strict grid. No floating/misaligned elements.
+- **Similarity**: Same action = same visual style across all pages.
+- **Common region**: Group related controls in a visual container (`bg-muted/50` or subtle border).
+
+## Instant Feedback
+
+| User action | Required feedback | Timing |
+|---|---|---|
+| Click button | Press state (`active:scale-[0.98]`) | Instant |
+| Submit form | Loading state on button + disable | Instant |
+| Successful action | Toast notification | <500ms |
+| Failed action | Inline error OR toast | <500ms |
+| Navigate | Skeleton or page transition | Instant |
+| Hover interactive | Color/shadow/scale change | <100ms |
+
+- **Optimistic UI**: Update UI immediately before server confirms. Revert on error.
+- **Skeletons over spinners. Always.** Spinners only inside buttons during submission.
+
+## Nielsen's 10 Heuristics
+
+1. **System status**: Show loading, toast on completion, inline validation as user types.
+2. **Real-world match**: Human language ("Sign in" not "Authenticate"). Locale-formatted dates/currencies.
+3. **User control**: Every modal dismissible with Escape + backdrop. Undo for destructive actions. Back always works.
+4. **Consistency**: Same action = same button style, position, label everywhere.
+5. **Error prevention**: Real-time validation. Disable submit until valid. Type-appropriate inputs. Confirm destructive actions.
+6. **Recognition > recall**: Visible labels (not placeholder-only). Show recent searches. Visible nav on desktop.
+7. **Flexibility**: Keyboard shortcuts (Cmd+K). Preserve filters in URL. Bulk actions where appropriate.
+8. **Minimalist design**: Every element earns its place. Prefer whitespace over separators.
+9. **Error recovery**: Say what went wrong + how to fix it. Highlight the field. Never clear form on error.
+10. **Help**: Contextual tooltips on complex features. Dismissible onboarding hints.
+
+## Performance Targets
+
+| Metric | Target |
+|---|---|
+| Lighthouse Performance | 98+ |
+| Lighthouse Accessibility | 98+ |
+| LCP | <2.5s |
+| CLS | 0 |
+| INP | <200ms |
+
+## Accessibility
+
+- All interactive elements reachable via Tab in logical order.
+- Focus rings: `:focus-visible` only (not `:focus`). Style: `ring-2 ring-primary/50`.
+- Icon-only buttons: must have `aria-label`.
+- One `h1` per page. No skipped heading levels.
+- Dynamic content updates: `aria-live="polite"`.
+- All animations in `motion-safe:` variant.
+- WCAG AA contrast: 4.5:1 for text, 3:1 for large text/UI.
+
+## Microcopy
+
+- **Buttons**: Action verbs — "Save changes", "Create item", "Delete account". Never "Submit" or "OK".
+- **Toasts**: Under 10 words. Success: confirm. Error: what happened + what to do.
+- **Empty states**: Explain what this area is for + CTA to fill it. ("No items yet. Create your first one.")
+- **Form errors**: Specific to the field. Below the field. Red text + red border.
+
+## Page Audit Checklist
+
+1. Interactive elements per section ≤ 7?
+2. All elements on grid?
+3. Every button/link has hover + active + focus-visible?
+4. Skeletons for all async content?
+5. Inline field-level errors on forms?
+6. Every modal dismissible with Escape?
+7. Tab through all elements in logical order?
+8. Text passes WCAG AA contrast?
+9. All animation in `motion-safe:`?
+10. LCP image has `priority`?

package/template/_claude/rules/client/core.md

@@ -0,0 +1,42 @@
+> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
+
+# Client Rules — Core Index
+
+**Read only the file relevant to your current task.**
+
+| You are doing... | Read this |
+|---|---|
+| Creating files, folders, feature modules | `01-project-structure.md` |
+| Building components, writing types/interfaces | `02-components-and-types.md` |
+| Fetching data, managing state, calling APIs, forms | `03-data-and-state.md` |
+| Choosing colors, styling, typography, spacing, motion | `04-design-system.md` |
+| Auth tokens, env vars, security headers | `05-security.md` |
+| UX psychology, cognitive load, a11y, performance | `06-ux-checklist.md` |
+
+---
+
+## Architecture
+
+```
+Page (Server Component — fetches data)
+  → Feature Components (Server or Client)
+    → UI (shadcn/ui + Tailwind)
+
+State: Server data (SSR) → Server Components
+       Server data (client) → React Query
+       Global client state → Redux (auth only)
+       Local state → useState / useReducer
+       URL state → useSearchParams
+```
+
+---
+
+## Non-negotiable rules
+
+1. **Server Components by default.** Only add `'use client'` when you need hooks, state, or event handlers.
+2. **Component limits**: Max 250 lines, max 5 props, max 3 JSX nesting levels.
+3. **No hardcoded colors**: Use Tailwind semantic tokens (`bg-primary`, `text-foreground`). Never hex/rgb.
+4. **No inline styles**: Tailwind only. Use `cn()` for conditional classes.
+5. **Import order**: React/Next → third-party → UI → local → hooks → services → types → utils.
+6. **Forms**: Validate with Zod. Always validate client-side AND server-side.
+7. **Security**: Never inject raw HTML without sanitization. Never prefix secrets with `NEXT_PUBLIC_`.

package/template/_claude/rules/global/core.md

@@ -0,0 +1,77 @@
+> **SCOPE**: These rules apply to the **entire workspace** (server + client). Always active.
+
+# Global Rules
+
+These rules are always in effect regardless of which directory you are working in.
+
+---
+
+## New Project Setup
+
+When the user asks to create, scaffold, or start a new server or client project, **always run `/create-server` or `/create-client` first** before writing any code. These commands contain the full scaffolding templates, dependency lists, and boilerplate that match our architecture. Do not attempt to scaffold a project from memory.
+
+---
+
+## Safe Editing
+
+1. **Small, focused changes**: Only modify what's necessary. Don't restructure code unless asked.
+2. **Preserve signatures**: Don't change existing function signatures, exports, or imports unless explicitly requested.
+3. **Extend, don't rewrite**: Add to existing modules. Don't gut and rebuild.
+4. **Protect critical flows**: Never break existing auth, core business flows, or payment logic.
+5. **No half-done work**: If something is incomplete, add a `// TODO:` with explanation.
+6. **No noisy logs**: No debug logs in production code. Mark temporary ones with `// TODO: remove debug log`.
+7. **Call out breaking changes**: If a breaking change is unavoidable, state it clearly in your explanation.
+8. **Assume production**: Treat this as a real production project. Avoid destructive or experimental changes.
+
+---
+
+## TypeScript
+
+- **Strict mode ON** in both client and server. No exceptions.
+- **No `any`** — use `unknown` if the type is truly unknown.
+- **Explicit return types** on all functions.
+- **Always `import type`** for type-only imports.
+- **Validate all inputs with Zod** — client-side for UX, server-side for security.
+
+---
+
+## Git & Branching
+
+- **Branch naming**: `feature/<name>`, `fix/<name>`, `chore/<name>`, `hotfix/<name>`.
+- **Commit messages**: Use conventional commits — `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`, `test:`.
+  - Keep the subject line under 72 characters.
+  - Use imperative mood: "Add search filter" not "Added search filter".
+- **Never commit**: `.env` files, secrets, `node_modules`, build artifacts, OS files (`.DS_Store`, `Thumbs.db`).
+- **One logical change per commit**. Don't mix unrelated changes.
+
+---
+
+## Environment & Configuration
+
+- **`.env` files are never committed.** Use `.env.example` as the template with placeholder values.
+- **Adding a new env var**: Add it to `.env.example` with a comment, and document where it's used.
+- **Secrets** (DB URLs, JWT secrets, API keys) must never be prefixed with `NEXT_PUBLIC_` and must never appear in client-side code.
+- **Public values only** (API base URL, app name) get the `NEXT_PUBLIC_` prefix.
+
+---
+
+## Testing
+
+- **New features and bug fixes should include tests** unless the change is trivial (copy, config, styling).
+- **Test naming**: `describe('<ModuleName>')` → `it('should <expected behavior>')`.
+- **Tests must be deterministic**: No reliance on real time, network, or random values. Mock external dependencies.
+- **Don't test implementation details** — test behavior and outputs.
+
+---
+
+## Code Review Checklist
+
+Before considering work done, verify:
+
+- [ ] No `any` types.
+- [ ] No hardcoded values (URLs, colors, magic numbers) — use constants and tokens.
+- [ ] No `console.log` left in code.
+- [ ] No commented-out code without a `// TODO:` explaining why.
+- [ ] Inputs validated with Zod.
+- [ ] Error cases handled (not just the happy path).
+- [ ] Existing tests still pass.

package/template/_claude/rules/server/core.md

@@ -0,0 +1,50 @@
+> **SCOPE**: These rules apply specifically to the **server** directory (Fastify backend).
+
+# Server Rules — Core Index
+
+**Do NOT read every rule file upfront.** Use this index to find the right rules for your current task.
+
+---
+
+## When to read which file
+
+| You are doing... | Read this |
+|------------------|-----------|
+| Setting up a module, organizing code, understanding the stack | `project-conventions.md` |
+| Creating or modifying a route / controller | `project-conventions.md` + `response-handling.md` |
+| Returning data (success, error, or paginated) | `response-handling.md` |
+| Handling or throwing errors | `response-handling.md` |
+| Writing service or business logic | `project-conventions.md` (Layer Responsibilities) |
+| Changing DB schema, migrations, indexes | `database.md` |
+| Adding or changing API endpoints | `project-conventions.md` (Postman Collection) |
+| Unsure where to start | This file |
+
+---
+
+## Architecture at a glance
+
+```
+Request
+  -> Route (Fastify plugin, defines HTTP method + path)
+  -> Controller (validates input with Zod, calls service, returns response)
+  -> Service (business logic, throws typed errors)
+  -> Repository (Prisma queries, returns raw data)
+  -> Database
+```
+
+**Three strict boundaries:**
+1. **Controllers** — parse input, call services, format responses. No business logic. No direct DB access.
+2. **Services** — all business logic. No Fastify concepts (request, reply). Throw typed `AppError` instances.
+3. **Repositories** — Prisma queries only. No business logic. No error formatting.
+
+---
+
+## Non-negotiable rules (always apply)
+
+1. **Response format**: All controllers use `successResponse()` / `paginatedResponse()`. No custom shapes.
+2. **Error handling**: Only throw `AppError` subclasses. Never raw `Error` or strings. Global error handler formats all errors.
+3. **Validation**: All input validated with Zod schemas before reaching services.
+4. **Database changes**: Always via Prisma migrations. Never raw DDL.
+5. **Logging**: Use `logger` from `src/libs/logger`. Never `console.log`.
+6. **Routes**: All prefixed with `/api/v1`. Registered as Fastify plugins.
+7. **Postman**: Every new or modified endpoint must be reflected in `postman/collection.json`. Create the collection if it doesn't exist.