# Repository Guidelines

## Project Structure & Module Organization
- `main/` holds Electron main-process entry (`main.ts`), IPC channels, and SQLite helpers.
- `renderer/` stores UI code: static HTML, TypeScript view logic, styles, and assets for the companion.
- `data/` retains seed content (compliments, badge tables) and migration scripts.
- `scripts/` aggregates automation such as packaging, schema generation, and smoke-test helpers.
- Keep feature experiments in `playgrounds/` so MVP code stays compact.

## Build, Test, and Development Commands
- `npm run dev` launches the Electron app with hot reload on main and renderer bundles.
- `npm run build` compiles TypeScript, packages assets, and emits a distributable bundle.
- `npm run lint` executes ESLint + Prettier for both processes; fix issues before committing.
- `npm run test` runs unit tests (Vitest) and lightweight IPC smoke checks.
- `npm run migrate` applies pending SQLite migrations to the local `buddy.db`.

## Coding Style & Naming Conventions
- TypeScript throughout; prefer explicit return types on exported functions.
- Use PascalCase for classes, camelCase for functions/variables, and kebab-case for filenames.
- Renderer templates live in `renderer/views/`; give DOM IDs descriptive prefixes (e.g., `timerStartButton`).
- Rely on ESLint (`@typescript-eslint`) and Prettier; do not disable rules without rationale inline.

## Testing Guidelines
- Place unit tests beside sources as `*.spec.ts`; mock Electron APIs with `@electron-mock/ipc`.
- Edge cases: empty achievement text, duplicate timers, and AI fallback messaging.
- Minimum expectation: each feature merges with passing unit tests plus a manual smoke run of the logging flow.

## Commit & Pull Request Guidelines
- Follow Conventional Commits (`feat:`, `fix:`, `chore:`) and keep messages under 72 characters.
- PR description should outline behavior changes, screenshots/gifs for UI tweaks, and list any new dependencies.
- Link related issues using `Closes #ID`; request review after lint/tests pass locally.

## Future Enhancements & Agents
- Treat voice capture, Live2D animation, and cloud sync as feature flags toggled in `main/config.ts`.
- Document new IPC channels in `docs/ipc.md`; provide mock responses for agent testing before hitting external APIs.