---
name: general
description: "Use ALWAYS, before any other skill here, for every code change in this project. Defines the approved stack (TanStack, Vite+, MUI), TypeScript and naming conventions, date formatting, light/dark theming, testing and the validation command, and the src/ and tests/ folder layout that decides where each new file goes."
metadata:
  type: convention
  library: wcz-layout
---

> This is the default skill. Reference it in combination with more specific skills (e.g., `forms`, `table`, `dialogs`) for targeted tasks. For the full catalogue of every `wcz-layout` import subpath and what it exports, read [references/exports.md](references/exports.md).

## Preferred Technology Stack

Favor the established platform before introducing custom code or a new dependency:

- **TanStack ecosystem:** Reach for the TanStack library that owns the problem instead of hand-rolling it — Start for the full-stack app and server functions, Router for routing and route-level data loading, DB for client-side collections and live queries, AI for LLM-backed chat and streaming, Form for form state and validation, Hotkeys for keyboard shortcuts, Virtual for long lists and grids, Pacer for debouncing, throttling, rate limiting and queueing.
- **Vite+:** Use Vite+ for the development server, formatting, linting and testing.
- **Material UI:** Use Material UI for interface components and icons. When an advanced capability is needed, consider MUI X Charts for data visualization, Tree View for hierarchical data, Scheduler for calendars and timelines, and Chat for AI-powered conversations.

Before implementing an external library feature, consult the current documentation through Context7 MCP. Do not add a new dependency when one of these platform libraries already covers the requirement.

When the requirement is not covered above and a well-maintained, popular library solves it, use that library instead of writing your own implementation.

## Coding Conventions

- Write strict ES2023 TypeScript. Preserve local inference, type public boundaries and never use explicit `any`.
- Stick to double quotes, semicolons, and the `~/` alias for `src/` imports.
- Avoid `useMemo` / `useCallback`; the React Compiler handles memoization.
- Keep code self-documenting; only add comments to clarify non-obvious intent.
- Run the narrow relevant test, then `vp check --fix`. It formats, lints and type-checks.

## User Interface

- Translate every user-facing string via `useTranslation` (or `t` outside components).
- Format all client-side dates with `"L LT"` or `"L"`.
- Build skeletons for loading states.
- When building UI, always design for both light and dark mode; this app uses
  `colorSchemeSelector: "data-mui-color-scheme"`, so prefer `theme.applyStyles("dark", ...)`
  for mode-specific styling.

## Testing

- Tests run on `vp test` (bundled in vite-plus).

## File Organization

Use this ownership model for new application code. Keep feature-specific code close to its route; promote it to a root directory only when it is shared across multiple features. One database table = one file per layer: every `<table>` slot below is the same singular camelCase table name, never grouped with its parent or child tables.

```txt
src/                               # client-first architecture
├── components/                    # shared components across multiple routes
├── db/                            # TanStack DB
│   ├── collections/               # collection descriptors
│   │   └── <table>.ts
│   ├── queries/                   # live query option objects
│   │   └── <table>.ts
│   └── persistence.ts             # browser SQLite persistence
├── env.ts                         # clientEnv + serverEnv via createEnv
├── hooks/                         # shared hooks across multiple routes
│   └── useTheme.ts                # MUI theme + color schemes
├── lib/                           # isomorphic/shared logic usable by client and server
│   ├── auth/
│   │   ├── permissions.ts         # as const satisfies Permissions
│   │   └── scopes.ts              # as const satisfies Scopes
│   ├── locales/
│   │   ├── cs.json
│   │   └── en.json
│   └── schemas/                   # shared Zod schemas
│       └── <table>.ts
├── router.tsx                     # QueryClient, DbClient, router options
├── routes/                        # TanStack Router file-based routing
│   ├── __root.tsx
│   ├── index.tsx
│   ├── login.tsx                  # required by requireAuth
│   ├── auth/                      # OAuth handlers
│   │   ├── login.ts
│   │   ├── callback.ts
│   │   └── logout.ts
│   ├── api/                       # REST API routes (only when a public API is required)
│   │   └── features/
│   │       ├── index.ts
│   │       └── $id.ts
│   └── features/                  # feature folder with multiple routes (kebab-case, plural)
│       ├── -components/           # route-specific components
│       ├── -hooks/                # route-specific hooks
│       ├── index.tsx
│       ├── create.tsx
│       ├── $id.tsx
│       └── edit.$id.tsx
├── server/                        # server-only code, never imported from a component
│   ├── actions/
│   │   └── <table>.ts
│   ├── db/
│   │   ├── migrations/
│   │   ├── schemas/               # Drizzle schemas
│   │   │   ├── <table>.ts
│   │   │   └── relations.ts
│   │   └── index.ts               # pool, search_path, auto-migrate
│   └── middleware/
│       └── databaseMiddleware.ts  # app-local, not a library export
├── start.ts                       # request middleware, incl. CSRF
├── types/
│   ├── i18next.d.ts               # types t() against en.json
│   └── wcz-layout.d.ts            # declares virtual:wcz-layout
tests/
├── unit/
│   ├── lib/
│   │   └── schemas/
│   │       └── <table>.test.ts
│   ├── hooks/
│   │   └── useX.test.ts
│   └── routes/
│       └── features/
│           └── -components/
│               └── XCard.test.tsx
├── integration/
│   ├── server/
│   │   └── actions/
│   │       └── <table>.test.ts
│   └── db/
│       └── collections/
│           └── <table>.test.ts
└── e2e/
    └── features/
        └── create.spec.ts
```