Claude Code — Reglas, Skills, Hooks y más para nuestro Claudio

# CLAUDE.md

## Project Overview

**Berrus** is a browser-based RPG set in Spain (Terra Alta, Catalonia) after "The Sin" — a catastrophe that ended technology, not nature. The world is still green, beautiful, and full of life. Turn-based combat, procedural dungeons, idle jobs, and crafting.

**Tone**: Gritty dark humor celebrating Iberian culture

## Tech Stack

**Frontend**: Vite, React 19, TanStack Router, Tailwind v4, Shadcn/ui, Zustand, TanStack Query

**Backend**: Elysia + Eden (type-safe), PostgreSQL, Drizzle ORM

**Validation**: TypeBox (`import { t } from "elysia"`) - NOT Zod

```typescriptimport { Elysia, t } from "elysia";
import { db, Transaction } from "@/db";
import { eq, and } from "drizzle-orm";
import { Link } from "@tanstack/react-router";```

## Project Structure

```src/
├── api/              # Elysia API routes
│   ├── public/       # Unauthenticated endpoints
│   ├── protected/    # Authenticated endpoints
│   ├── domains/      # Server-only domain logic (character, item, combat, dungeons, etc.)
│   └── infra/        # Cross-cutting infra (auth, session, request-context, error-handler)
├── routes/           # TanStack Router file-based routes
│   ├── _auth/g/c/$slug/  # Character-specific game routes
│   └── hiscores/     # Leaderboards
├── components/
│   ├── ui/           # Shadcn/ui base components
│   ├── shared/       # Reusable (ItemViewer, CharacterViewer, etc.)
│   └── combat/       # Combat UI
├── db/
│   ├── schema.ts     # Drizzle schema (snake_case)
│   └── drizzle/      # Generated migrations
├── domains/          # All business logic by domain
│   ├── abilities/    # 37 abilities × 4 tiers
│   ├── buffs/        # Buffs, blessings, system buffs
│   ├── character/    # Character logic, stats, skills
│   ├── combat/       # Combat engine, arenas
│   ├── cooking/      # Cooking recipes and food
│   ├── dungeons/     # Dungeon generation, editor
│   ├── enemy/        # Enemy generation and types
│   ├── item/         # Item blueprints and utilities
│   ├── jobs/         # Idle job system
│   ├── loot/         # Loot generation, drop tables
│   ├── spells/       # Spells, enchanting, alchemy
│   ├── warehouse/    # Crafting structures, La Era
│   └── world/        # World tiles, travel, pathfinding
├── hooks/            # React hooks
└── lib/              # Shared utilities

tests/unit/           # Playwright unit tests```

### Domain File Conventions

Each domain directory in `src/domains/` contains all code for that domain — business logic, schemas, UI components, and API handlers. Files use naming suffixes to indicate their role and boundary:

| Suffix         | Meaning                              | Example                |
| -------------- | ------------------------------------ | ---------------------- |
| `*.shared.ts`  | Imported by both server and client   | `buff.utils.shared.ts` |
| `*.schema.ts`  | TypeBox schemas (types + validation) | `items.schema.ts`      |
| `*.api.ts`     | Server-only API logic                | `skills-xp.api.ts`     |
| `*.tsx`        | React components (client-only)       | `buff-viewer.tsx`      |
| `*.ts` (plain) | Domain-internal logic                | `buff.service.ts`      |

```typescript// Schema imports use @/domains/DOMAIN/NAME.schema
import { RuntimeItemSchema } from "@/domains/item/items.schema";

// Shared imports use @/domains/DOMAIN/NAME.shared
import { getTieredAbilityById } from "@/domains/abilities/abilities.blueprint.shared";```

`src/api/` contains **only server-side route wiring** — endpoint files that import from domains. No business logic or schemas live there.

## Commands

```bash# Development
pnpm run dev                  # Start dev server + crons + item type watcher
pnpm run dev:no-cron          # Start without crons

# Quality (run after every task)
pnpm run lint && pnpm run format

# Database
pnpm run db:generate          # Generate migration from schema changes
pnpm run db:generate --custom # Generate empty migration for manual SQL
pnpm run db:migrate           # Apply migrations
pnpm run db:push              # Direct sync (dev only, no migration history)

# IMPORTANT: For custom SQL migrations (data transforms, triggers, functions):
# ALWAYS use `pnpm run db:generate --name=my-migration --custom` to generate an empty file
# NEVER manually create migration files - drizzle-kit manages the journal automatically

# Item Types (after modifying blueprints)
pnpm run generate:item-types

# Testing
pnpm run test:unit
pnpm run typecheck```

**Post-Task**: After completing any coding task (writing or modifying code), you MUST automatically run `/simplify` first, then `/post-work-review`. Do NOT wait for the user to ask — invoke them proactively via the Skill tool as soon as the task is done. Skip this for non-coding tasks (questions, research, chatting).

## Critical Rules & Best Practices

### No Re-exports for "Backward Compatibility"

**CRITICAL**: Never re-export types or values "for backward compatibility". This creates unnecessary indirection and makes the codebase harder to maintain.

```typescript// DON'T: Re-export from another file
export { EnemyTypeSchema, type EnemyType } from "./enemy-types"; // WRONG!
export { SomeUtil } from "./utils"; // for backward compatibility - WRONG!

// DO: Import directly from the source
import { EnemyTypeSchema } from "@/domains/enemy/enemy-types.schema";```

When moving code to a new location, update ALL imports to point to the new location. Never leave re-exports behind.

### NEVER Run Destructive Commands Without Explicit Approval

**CRITICAL:** Never run these commands without explicit user approval:

- `git checkout -- .` or `git restore .` - **DISCARDS ALL UNCOMMITTED WORK PERMANENTLY**
- `git reset --hard` - Discards commits and changes
- `git clean -fd` - Deletes untracked files
- `git stash` - **NEVER stash without explicit user permission** — can hide work-in-progress and lead to lost changes
- `pnpm run lint --fix` or `oxlint --fix` on the entire codebase - Can modify hundreds of files

Before running any of these, you MUST:

1. Explain exactly what will be lost/changed
2. Ask for explicit confirmation
3. Wait for user approval

### NEVER Run Migrations Autonomously

**CRITICAL:** Never run `pnpm run db:migrate` or any migration command autonomously. Migrations must always be run by the user manually. You may generate migration files (`pnpm run db:generate`), but **never apply them**.

### Don't Touch Unrelated Files

**NEVER modify files unrelated to your task.** If lint shows errors in other files, leave them alone.

### UI Styling

- **No rounded corners**: Never use `rounded-*` classes
- **Member badge**: Use `MEMBER_TOKEN_IMAGE_URL` with `grayscale` filter for non-members
- **Button loading states**: Use `isLoading` prop on Button component instead of changing button text (e.g., "Requesting..."). Don't add `gap-*` classes to buttons - they handle spacing internally.

### No Hard Caps - Use Diminishing Returns

**NEVER use `Math.min(value, CAP)` for stats.** Use diminishing returns instead:

```typescriptimport {
  logarithmicDiminishing,
  hyperbolicDiminishing,
  exponentialDiminishing,
} from "@/lib/diminishing-returns";

// Logarithmic: steady but slowing growth, no ceiling
const effective = logarithmicDiminishing(rawValue, scale);

// Hyperbolic: approaches soft cap asymptotically
const effective = hyperbolicDiminishing(rawValue, softCap);

// Exponential: approaches maximum value smoothly (for percentages)
const effective = exponentialDiminishing(rawValue, maxValue, scale);```

### Type Safety

```typescript// DON'T: Use Zod
import { z } from "zod"; // WRONG!

// DO: Use TypeBox from Elysia
import { t } from "elysia";

// NEVER: Use `as any` or `as Type` to bypass type checking
const response = await (fetcher as any).someRoute.get(); // FORBIDDEN!
return response.data as SomeType; // FORBIDDEN!

// DO: Define proper interfaces and transform data explicitly
interface MyItem {
  id: string;
  name: string;
}

async function fetchData(): Promise<MyItem[]> {
  const response = await fetcher.route.get();
  if (response.error) throw response.error;
  // Transform and return - types flow from Eden
  return response.data.items.map((item) => ({
    id: item.id,
    name: item.name,
  }));
}```

**Eden types flow automatically** from Elysia routes - never claim they "need regeneration". If types are wrong, the route registration is wrong.

### Transactions

```typescript// DON'T: Use db inside transaction
await db.transaction(async (tx) => {
  await db.insert(items)...  // WRONG! Use tx
});

// DO: Use tx everywhere
await db.transaction(async (tx) => {
  await tx.insert(items)...
  await someFunction(tx, ...);
});```

### Use FOR UPDATE When Reading Items Before Mutation

Any `SELECT` that reads an item row (or any row with a `quantity` field) followed by an `UPDATE`/`DELETE` on that same row **must** use `.for("update")` to prevent race conditions:

```typescript// DON'T: Read-then-write without lock
const [item] = await tx.select().from(items).where(eq(items.id, id));
await tx
  .update(items)
  .set({ quantity: item.quantity - 1 })
  .where(eq(items.id, id));

// DO: Lock the row first
const [item] = await tx
  .select()
  .from(items)
  .where(eq(items.id, id))
  .for("update");
await tx
  .update(items)
  .set({ quantity: item.quantity - 1 })
  .where(eq(items.id, id));```

This applies to all utility functions (`mergeStackableItems`, `consumeItems`, `splitStackableItem`, `transferItem`, pesetas operations, etc.).

### Promise.all() for Independent Operations

When async operations have no interdependencies, execute them concurrently:

```typescript// DON'T: Sequential (3 round trips)
const user = await fetchUser();
const posts = await fetchPosts();
const comments = await fetchComments();

// DO: Parallel (1 round trip, 2-10× faster)
const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments(),
]);```

### Avoid Barrel File Imports

Import directly from source files, not barrel files (index.js re-exports):

```typescript// DON'T: Loads entire library
import { something } from "lodash";

// DO: Direct imports
import something from "lodash/something";```

Affected: `@mui/*`, `lodash`, `date-fns`, `@radix-ui/*`

**Exception**: `lucide-react` — use barrel imports (`from "lucide-react"`). Direct imports lack TypeScript declarations and cause TS7016 errors.

### Frontend Inventory Display

```typescript// DON'T: Show required as available
<ItemViewer quantityDivided={{ available: cost.quantity, required: cost.quantity }} />

// DO: Check actual inventory
const available = getItemQuantityInInventory(inventory, slug);
<ItemViewer quantityDivided={{ available, required: cost.quantity }} />```

## API Development

**Route Pattern**:

```typescriptimport { Elysia, t } from "elysia";
import { getCharacterFromRequest } from "@/api/domains/character/character";

export const myRoute = new Elysia().post(
  "/my-action",
  async ({ request, body, set }) => {
    const character = getCharacterFromRequest(request);

    return await db.transaction(async (tx) => {
      // character already has all fields - don't re-query!
      return { success: true, data: { ... } };
    });
  },
  {
    body: t.Object({
      itemId: t.String(),
      quantity: t.Number({ minimum: 1 }),
    }),
    response: {
      200: t.Object({ success: t.Boolean(), data: t.Any() }),
      400: t.Object({ error: t.String() }),
    },
  }
);```

**Register Route**:

```typescript// In /src/api/protected/character/[slug]/protected/index.ts
import { myRoute } from "./my-action";
export const characterProtectedRoutes = new Elysia().use(myRoute);```

## Database

**Migration Workflow**:

1. Modify `schema.ts`
2. `pnpm run db:generate --name=descriptive-name`
3. Review SQL in `/src/db/drizzle/`
4. `pnpm run db:migrate` (local test)
5. Commit schema + migration files
6. Push → Railway auto-runs migrations

**Manual SQL** (triggers, functions): `pnpm run db:generate --custom`

## WIP Features

### Fishing Minigame (WIP)

A self-contained React fishing minigame component. No backend integration yet.

- **Location**: `src/domains/fishing/fishing-game.tsx` (`FishingGame` component)
- **Test route**: `src/routes/_auth/g/c/$slug/fishing-test/`
- **Phases**: idle → casting → waiting → teasing → hooking → reeling → result
- **Key patterns**: rAF game loop with DOM-direct manipulation (no 60fps React re-renders), CSS `@property` for animatable custom properties, `reelingDoneRef` to freeze loop on catch
- **Status**: UI complete, needs backend API integration (fish tables, inventory, XP rewards)

## Git Worktree

```bashpnpm install  # Install deps (worktrees don't share node_modules)```

Quote bracket paths: `"src/api/protected/character/[slug]/..."`