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/.

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.

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.

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 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.