| 1 | # Repository Guidelines |
| 2 | |
| 3 | ## Project Structure & Module Organization |
| 4 | |
| 5 | App setup lives in `lib/main.dart`, `lib/app.dart`, and `lib/bootstrap/`. Shared code belongs in `lib/core/`. Organize product code as vertical slices under `lib/features/<feature>/`, using `data/`, `providers/`, `views/`, and `utils/` as needed. |
| 6 | |
| 7 | Localization sources are `lib/l10n/app_*.arb`; resources live in `assets/`. Tests mirror production areas under `test/core/` and `test/features/`. Native projects are in `android/` and `ios/`; store media belongs in `docs/`. |
| 8 | |
| 9 | ## Build, Test, and Development Commands |
| 10 | |
| 11 | Use FVM so development matches `.fvmrc` (Flutter 3.44.2): |
| 12 | |
| 13 | - `fvm flutter pub get` installs dependencies. |
| 14 | - `fvm flutter run` launches the selected device. |
| 15 | - `fvm flutter analyze` runs lints and analyzer checks. |
| 16 | - `fvm dart format .` formats Dart sources. |
| 17 | - `fvm flutter test [path]` runs all tests or a focused file. |
| 18 | - `fvm flutter gen-l10n` regenerates localization output. |
| 19 | - `fvm dart run build_runner build --delete-conflicting-outputs` refreshes ObjectBox output after entity changes. |
| 20 | |
| 21 | ## Architecture, Style & UI Libraries |
| 22 | |
| 23 | Follow `.agents/skills/flutter-feature-based-architecture/SKILL.md` for every feature or refactor. A feature may import itself and `core/`, never a sibling feature. Keep views thin; place business rules, async work, persistence, and mutations in Riverpod notifiers or repositories. Extract UI sections into named `StatelessWidget` classes under `views/components/`, not private `_build...` helpers. Keep models and providers handwritten; ObjectBox is the existing generation exception. |
| 24 | |
| 25 | Use two-space indentation and `dart format`. Name files `snake_case.dart`, types `UpperCamelCase`, and members and providers `lowerCamelCase`. Render every icon with `HugeIcon` and a `HugeIcons.*` constant; do not use Flutter `Icon` or `Icons.*`. For animation, prefer Cue, provide an explicit motion, and use one `Cue` per coordinated scene with `Actor` delays for stagger. Follow `.agents/skills/hugeicons-usage/SKILL.md` and `.agents/skills/cue-animations/SKILL.md`. Do not hand-edit generated files. |
| 26 | |
| 27 | ## Testing Guidelines |
| 28 | |
| 29 | Tests use `flutter_test` and end in `_test.dart`. Add regression tests beside the feature; use widget tests for navigation and provider-driven UI. Run tests and analysis before a PR. The MinIO test requires `LOCALMIND_MINIO_*` variables. No numeric coverage threshold is enforced, but changed behavior should be covered. |
| 30 | |
| 31 | ## Commit & Pull Request Guidelines |
| 32 | |
| 33 | Use Conventional Commit-style prefixes: `feat:`, `fix:`, `refactor:`, and `chore:`, with optional scopes such as `fix(providers):`. Keep subjects imperative and reference issues when relevant. PRs should explain impact and verification, link issues, include before/after UI screenshots, and call out localization, permissions, schema, or generated-file updates. |
| 34 | |
| 35 | ## Security & Configuration |
| 36 | |
| 37 | Never commit API keys, signing material, model data, or user conversations. `private/` and `playstore_keys/` are intentionally ignored. Treat server URLs and cloud-sync credentials as sensitive test data. |