flutter-agentic GEMINI.md

FlutterAgentic — Gemini Rules

Full reference → docs/ folder

Monorepo layout

Dart pub-workspace monorepo: one shared core package consumed by multiple Flutter apps.

packages/core/   shared toolbelt → import 'package:core/core/…'   (no app-specific code)
apps/jokes/      demo app          apps/doc_scanner/  request/response app
apps/ai_chat/    streaming app

One flutter pub get at the repo root resolves all packages. Run make targets from the root; run an app from its folder (apps/<app>). Each app owns its main.dart, di/injection_container.dart, and constants/ (ValueConst/ApiConstants); core holds only CoreConst. The primary feature is always feature/home/.

@docs/ai-rules/conventions.md @docs/reference/architecture.md @docs/explanation/end-goal.md

Read docs/how-to/contributing.md for contributor workflow and git hooks. Read docs/how-to/add-feature-template.md when scaffolding a new feature — it has the full folder tree, empty class skeletons, DI registration order, and a forbidden-pattern checklist. Read docs/how-to/add-usecase.md when adding a use case — create the class and register it in injection_container.dart. Read docs/how-to/design-screen-state.md when designing BLoC events and states — covers business-logic naming, state design, retry context, and screen rendering rules with examples from the jokes feature. Read docs/how-to/review-code.md when the user asks to review, audit, or check generated code — run through the full checklist and report ✅/❌ per section. Read docs/how-to/change-app-id.md when the user asks to change the application ID or bundle identifier — covers Android (build.gradle.kts + MainActivity.kt package path) and iOS (project.pbxproj), with Xcode manual steps and provisioning notes. Read docs/how-to/rename-app.md when the user asks to rename the app — covers display name, package name, and all files that reference the old name. Read docs/how-to/connect-firebase.md when connecting an app to Firebase — covers checking/installing the Firebase + FlutterFire CLIs, running flutterfire configure, per-app firebase_core, main.dart init, Android Gradle plugin, iOS deployment target (15.0+), and the Xcode GoogleService-Info.plist registration check; it asks which app under apps/ to connect. Read docs/how-to/add-app-logo.md when setting or changing an app's launcher icon — one brand image (ask the user for it) → every Android/iOS/web size via flutter_launcher_icons, with adaptive-icon safe-zone rules and a per-platform verification checklist. Read docs/how-to/add-splash-screen.md when adding a native boot splash to an app — flutter_native_splash with theme-derived light/dark colours and a centered logo (4x-density and Android-12 asset rules), plus a verification checklist; pairs with an optional Flutter splash route. Read docs/how-to/add-notification-feature.md when adding Firebase Cloud Messaging push notifications to an app — covers per-app firebase_messaging + flutter_local_notifications, foreground/background/terminated handling, tap-to-open-a-page routing, and image (rich) notifications, split into shared Flutter code + separate iOS / Android tracks; builds on connect-firebase. Recommend testing FCM on a real Android device (emulator Play services is flaky). Read docs/explanation/ai-agents.md for per-agent install and usage. Read docs/tutorials/solid-principles.md to understand how SOLID principles are applied across all layers — useful context when designing new classes or reviewing layer boundaries. Read docs/tutorials/design-patterns-and-concepts.md for design patterns used in this codebase (Singleton, Repository, DTO, Either, Sealed Classes, Strategy, and more) — explains the why behind structural decisions. When the user asks to do a release, follow the steps below interactively — ask for confirmation at each step before proceeding.