# Repository Guidelines

## Project Structure & Module Organization
- `app/` hosts Next.js routes, layouts, and server actions for the web UI.
- `components/`, `hooks/`, `store/`, and `utils/` group reusable UI pieces, custom hooks, Zustand stores, and shared helpers.
- `services/`, `api-client/`, and `server/` encapsulate API integrations, background jobs, and Hono handlers; keep external calls here.
- `public/` stores static assets, while `docs/` and `schema/` capture product and API documentation.
- Tests and fixtures live under `test/`; mirror the runtime folder structure when adding coverage.

## Build, Test, and Development Commands
- `npm run dev` boots the local Next.js app on port 3200; use `npm run dev:restart` when you need a clean background process.
- `npm run build` compiles the production bundle, and `npm start` serves the build output.
- `npm run lint` runs ESLint with the Next.js config; `npm run lintfix` chains Prettier and ESLint for autofixes.
- `npm test`, `npm run test:watch`, and `npm run test:ui` execute Vitest in batch, watch, or UI mode.
- Use `npm run generate:dummy-screenshots` or `npm run prepare:dummy-images` to refresh design placeholders referenced in demos.

## Coding Style & Naming Conventions
- TypeScript and modern React patterns are expected; default to server components unless client interactivity is required.
- Formatting is enforced by Prettier (2-space indentation, single quotes, trailing commas) and ESLint; run lint before committing.
- Name React components and Zustand stores in PascalCase, hooks with the `use` prefix, and internal helpers in camelCase.
- Keep import paths absolute via the `@` alias rather than deep relative chains, and group CSS or Tailwind utilities near their components.

## Testing Guidelines
- Write unit and integration specs with Vitest; locate files beside the code (`*.test.ts[x]`) or under `test/` mirroring the module path.
- Mock external services through helpers in `services/` to avoid real network calls, and assert both success and error flows.
- Run `npm test` plus `npm run lint` before pushing; add snapshots only when the UI surface is stable.

## Commit & Pull Request Guidelines
- Follow Conventional Commits (`feat:`, `fix:`, `chore:`) as in the git log; include localization context when touching Japanese copy.
- Each pull request should link the relevant issue, describe behavior changes, note required environment updates, and attach UI screenshots or recordings.
- Confirm CI passes locally (`npm run lint`, `npm test`, `npm run build`) and mention any skipped checks or follow-up tasks in the description.

## Configuration Tips
- Secrets live in `.env.local`; never commit credentials or API tokens—consult `api-config.json` for expected keys.
- Update documentation in `docs/` when endpoints or flows change, and surface breaking environment changes in the pull request summary.