# Repository Guidelines

## Project Structure & Module Organization
- `lib/main.dart` is the single entry point; group new features in subfolders under `lib/` (e.g., `timer/`, `settings/`) with `widgets/`, `services/`, and `models/` as needed.
- Tests live in `test/` (default `widget_test.dart`); mirror `lib/` paths (`lib/timer/controller.dart` → `test/timer/controller_test.dart`).
- Assets such as backgrounds reside in `assets/` and are declared in `pubspec.yaml`; keep new images in the same folder and register them there.
- Platform folders (`android/`, `ios/`, `macos/`, `windows/`, `linux/`, `web/`) hold generated build config—modify only when working on platform-specific code or permissions.

## Build, Test, and Development Commands
- `flutter pub get` – install/update dependencies.
- `flutter analyze` – static analysis using `flutter_lints`; run before commits.
- `dart format .` – format codebase (uses 2-space indent).
- `flutter test` – run all unit/widget tests; add `--coverage` to check coverage.
- `flutter run -d <device>` – launch locally on a simulator/emulator or browser.
- `flutter build apk --release` or `flutter build web --release` – produce release artifacts for mobile or web.

## Coding Style & Naming Conventions
- Follow `analysis_options.yaml` (`flutter_lints`); prefer clean imports and avoid unused code.
- Use snake_case for files, PascalCase for types, camelCase for variables/methods, and ALL_CAPS for consts.
- Keep widgets small and composable; separate stateful logic from rendering.
- Document non-obvious logic with comments; avoid print debugging in committed code.

## Testing Guidelines
- Use `flutter_test` for units and widgets; name files `*_test.dart` and describe behavior in test names (`'starts countdown on tap'`).
- Cover new logic paths and UI states (loading/error/success); add visuals only when needed.
- Run `flutter test` locally before opening a PR; ensure assets or permissions used in tests are mocked (e.g., geolocator calls).

## Commit & Pull Request Guidelines
- If using Git, follow Conventional Commits (`feat: add timer presets`, `fix: handle geolocator errors`).
- Scope commits narrowly; keep diffs focused on one concern.
- PRs should include: summary of changes, linked issues/tasks, screenshots or screen recordings for UI updates, and a checklist of commands run (`flutter analyze`, `flutter test`).
- Flag platform-specific changes (Android/iOS/Web) and note any permission/config edits in `pubspec.yaml` or platform manifests.

## Security & Configuration Tips
- Do not commit API keys or secrets; prefer runtime configuration or platform-specific secure stores.
- Keep asset paths synced with `pubspec.yaml` to avoid runtime load failures.
- When adding location-dependent features (geolocator), document permission prompts and testing steps per platform.