# Repository Guidelines

## Project Structure & Module Organization
- `src/app` hosts the App Router; use `(auth)` and `(main)` route groups and keep route-only components inside their segment folders.
- `src/components` holds shared UI; keep primitives in `components/ui` and group feature widgets under clear folder names.
- `src/lib`, `src/services`, and `src/utils` house shared logic, API clients, and helpers; extend an existing module before adding a new directory.
- Mock handlers live in `src/mocks`, MSW’s worker sits in `public/mockServiceWorker.js`, localization bundles under `public/locales`, and generated docs go to `docs/`.

## Build, Test, and Development Commands
- `npm run dev` starts the Turbopack dev server with MSW auto-registration when `NEXT_PUBLIC_ENABLE_MOCK=true`.
- `npm run build` compiles the production bundle; run after routing or configuration changes.
- `npm run start` serves the built app and mirrors production runtime.
- `npm run lint` applies the Next.js ESLint preset; resolve warnings before review.
- `npm run i18n:scan`, `npm run i18n:scan-custom`, and `npm run i18n:convert` refresh translation keys and write `docs/copy-audit.xlsx`.

## Coding Style & Naming Conventions
- TypeScript is required; keep strict types at module boundaries and define payload interfaces explicitly.
- Follow the house formatting: two-space indentation, double quotes, no semicolons, and Tailwind classes composed with `cn`.
- Use PascalCase for React components, camelCase for utilities, `use` prefix for hooks, and kebab-case file names in routes.
- Reuse theme tokens and shared icons through design-system helpers; avoid ad-hoc color values or inline SVG copies.

## Testing Guidelines
- There is no global Jest/Vitest runner; smoke tests such as `src/utils/textParser.test.ts` execute with `npx tsx <path>`—mirror that pattern for quick unit checks.
- Keep exploratory scripts or `.test.ts` files beside the code they exercise and strip console noise before shipping.
- Prioritize integration checks through the dev server plus MSW, and document manual test steps in the PR when automation is absent.

## Commit & Pull Request Guidelines
- Commit subjects are present-tense, sentence-style summaries (see `git log`); add rationale in the body when touching multiple areas.
- Scope each branch to a vertical slice (`feature/`, `fix/`, or `chore/`) and rebase on `main` before review.
- PRs need a concise summary, screenshots for UI updates, environment-variable callouts, and links to related issues or docs.
- Flag data, security, or localization assumptions so reviewers can validate configuration changes quickly.