# Repository Guidelines

## Project Structure & Module Organization
`lib/` follows Clean Architecture: `core/` for shared constants, errors, network utilities, and base widgets; `data/` for API clients, datasources, and repository implementations; `domain/` for entities and use cases; `presentation/` for Riverpod providers, pages, and widgets. Tests mirror features in `test/`, Hive migration specs live in `test_hive/`. Platform scaffolding sits under `android/`, `ios/`, `macos/`, `linux/`, `windows/`, `web/`, and docs under `doc/`.

## Build, Test, and Development Commands
- `flutter pub get` – run after cloning or switching branches.
- `flutter pub run build_runner build --delete-conflicting-outputs` – regenerates adapters, JSON code, and merges `doc/restaurant_data/store.db` changes into `assets/data/store_seed.json` and `store_seed.meta.json`.
- `flutter pub run build_runner watch --delete-conflicting-outputs` – keep this on during development to auto-regenerate seeds when `store.db` changes.
- `flutter run -d ios|android|chrome` – launch on the target device/simulator (prefer simulators with location APIs).
- `flutter build apk|appbundle|ios --release` – production bundles after QA is green.

## Coding Style & Naming Conventions
See `doc/03_architecture/code_convention.md`: two-space indent, 80-char soft wrap (120 hard), imports grouped Dart → packages → project, one public class per file. Use PascalCase for classes/providers, camelCase for methods/variables, UPPER_SNAKE_CASE for constants, snake_case for files/folders. Business logic identifiers and UI strings stay in English; comments/docs may be in Korean with the first English term in parentheses. Keep widgets small and compose within the relevant `presentation/*` module to preserve MVVM boundaries.

## Testing Guidelines
Use the Flutter test runner: `flutter test` for all, `flutter test test/..._test.dart` for targeted runs, `flutter test --coverage && genhtml coverage/lcov.info -o coverage/html` for coverage. Name tests with `_test.dart` alongside sources. Prefer `group`/`testWidgets` to describe behaviors (e.g., “should recommend restaurants under rainy limits”). Run `flutter test test_hive` when Hive persistence changes.

## Commit & Pull Request Guidelines
Commit format `type(scope): summary` (e.g., `feat(recommendation): enforce rainy radius`), optional body and `Resolves: #123`. Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`. Create feature branches from `develop`, include API/UI screenshots when visuals change, describe validation steps, and link issues before review. Keep PRs focused on a single feature/bugfix.

## Security & Configuration Tips
Never commit API secrets. Create `lib/core/constants/api_keys.dart` locally with placeholders and use secure storage/CI wiring. Verify location permissions and weather API keys before captures or uploads.

## Scope, Goals, and Guardrails
- Applies repo-wide unless more specific instructions exist; system/developer directives still win.
- Keep changes minimal and localized; avoid destructive rewrites, config changes, or dependency bumps unless requested.
- For multi-step tasks, maintain an `update_plan` with exactly one step `in_progress`.
- Responses stay concise and list code/logs before rationale. If uncertain, prefix with “Uncertain:” and surface at most the top two options.
- Work is workspace-scoped; ask before adding dependencies or new network calls. Avoid unrequested deletes/rewrites/config changes.

## Collaboration & Language
- Default responses must be in Korean; keep code/logs/commands in their original form.
- Business logic, identifiers, and UI strings remain in English; comments/docs in Korean with the first English term in parentheses.
- Git push reports and work completion reports are in Korean.
- Write code comments and commit/PR/work summary comments in Korean; include English terms in parentheses when helpful.
- All git comments (commit messages, PR descriptions, push notes) must be written in Korean.

## Validation & Quality Checks
- Run `dart format --set-exit-if-changed .` before finishing.
- Always run `flutter analyze` and relevant `flutter test` suites (including `flutter test test_hive` when Hive code changes) before hand-off. Add/update tests when behavior changes or bugs are fixed.
- Document executed commands in your PR or hand-off notes.

## Sensitive Areas & Approvals
- Editing Android/iOS/macOS build settings, signing artifacts, Gradle/Xcode configs needs explicit approval.
- Do not touch `pubspec.yaml` dependency graphs, secrets, or add network activity/tools without requester confirmation.

## Branch & Reporting Conventions
- Branch naming: `codex/<type>-<slug>` (e.g., `codex/fix-search-null`).
- Commit messages use `type(scope): summary`; keep explanations short and focused on observable behavior.
- When offering alternatives, show only the top two concise options.
- When closing a work report, propose concrete next tasks; if none, state that work is complete.

## Notification & Wrap-up
- Before final report or end of conversation, run `/Users/maximilian.j.sul/.codex/notify.py`.
- Update any needed working docs before reporting results.

## SRP & Layering Checklist
- Each file/class should have a single reason to change; split widgets ~400 lines and methods ~60 lines into helpers.
- Preserve presentation → domain → data dependency flow. Domain stays framework-agnostic; data must not reference presentation.
- Extract validation/transform/sort/filter logic into services/utilities instead of burying it inside widgets.