# Repository Guidelines

## Project Structure & Module Organization

This is a Bun-powered Next.js frontend using Feature-Sliced Design. Route files live in `app/`; keep the root `pages/` directory because Next.js build compatibility depends on it. Product code is organized under `src/` by layer: `src/pages`, `src/widgets`, `src/features`, `src/entities`, and `src/shared`. Static assets belong in `public/`; shared source assets live in `src/shared/assets/`. End-to-end tests and support code are in `tests/e2e/`, with shared test assets in `tests/assets/`.

## Build, Test, and Development Commands

- `bun install` installs dependencies from `bun.lock`.
- `bun dev` or `bun run dev` starts the Next.js development server.
- `bun run build` creates a production Next.js build.
- `bun run start` serves the production build.
- `bun run lint` runs the configured lint pipeline; keep `lint:es` and `lint:prettier` scripts aligned if you edit `package.json`.
- `bunx jest` runs unit tests configured by `jest.config.ts`.
- `bun run test:e2e` runs headed Playwright tests against the mock API.
- `bun run test:integration` runs headed Playwright tests whose filenames include `.integration.`.
- `bun run gen:api-types` regenerates API types using `.env.production`.

## Coding Style & Naming Conventions

Use TypeScript and React function components. Prettier is configured for tabs, double quotes, no semicolons, and trailing commas. SCSS modules follow `Component.module.scss`; component folders usually expose `Component.tsx`, `Component.d.ts`, and `index.ts`. Hooks use `useName.ts` naming. Prefer imports through aliases such as `@shared/*`, `@features/*`, and `@widgets/*`. Respect FSD boundaries: lower layers must not import upper layers.

## Testing Guidelines

Unit tests use Jest with jsdom and usually live beside source files as `*.test.ts` or `*.test.tsx`. Playwright specs live under `tests/e2e/specs/`, grouped by domain such as `auth/`, `project/`, `silence/`, and `upload/`. Name mocked-flow specs `*.spec.ts` and real-backend flows `*.integration.spec.ts`. Keep reusable fixtures in `tests/e2e/fixtures/` and helper servers/config in `tests/e2e/support/`.

## Commit & Pull Request Guidelines

Recent history mostly uses short Conventional Commit-style messages, for example `feat: add ...`, `fix: include ...`, and `chore: ...`. Prefer that format, with an imperative, lower-case summary. Pull requests should describe the user-visible change, list test commands run, link related issues, and include screenshots or recordings for UI changes.

## Agent-Specific Instructions

When answering library, framework, SDK, API, CLI, or cloud-service questions, fetch current docs with Context7 before responding. Do not use Context7 for ordinary refactors, business-logic debugging, or code review.

Local project skills live in `.agents/skills/`. When a task matches one of these skills, open its `SKILL.md` and follow the workflow before changing code:

- `chrome-testing`: use for visual or browser testing, UI regression checks, screenshots, and local Chrome automation.
- `composition-patterns`: use when writing, reviewing, or refactoring React component APIs with boolean mode props, render slots, prop drilling, compound components, providers, or React 19 ref/context composition concerns.
- `feature-sliced-design`: use when deciding where code belongs in FSD layers, shaping slices and public APIs, placing assets, checking import boundaries, resolving cross-imports, or integrating framework patterns with FSD.
- `kimi`: use before making web design decisions or designs overall, including UI direction, redesigns, layout, typography, color, spacing, interaction states, responsive behavior, screenshots, mockups, landing pages, dashboards, and frontend visual critique. Kimi can use the `agent-browser` skill for browser inspection, screenshots, and visual QA when rendered UI matters.
- `react-best-practices`: use when working on React or Next.js components, App Router pages, Server Actions, data fetching, bundle size, render performance, hydration, or UI responsiveness.
- `typescript-best-practices`: use when touching TypeScript code that needs modern TS 5.x type safety, strictness, discriminated unions, `satisfies`, `unknown`, or safer type modeling.
