# AGENTS.md: Guide for AI coding agents (Claude Code, Codex, Cursor and others) working in this repo. ## Project map | Path | What lives there | |---|---| | `lib/main.dart` | | | `lib//` | | | `lib//` | | | `lib//` | | | `lib/` | | | `test/` | | **Not in this repo:** ## Architecture rules **State: .** Don't add a second state library. - - **Navigation: .** - **Data.** - - - **UI.** - Colors come from `Theme.of(context).colorScheme` and text styles from `Theme.of(context).textTheme`. Don't hard-code colors. - - ## Commands Run from the repo root. Tested with Flutter (Dart ). ```bash flutter pub get dart run build_runner build --delete-conflicting-outputs # flutter analyze # compare issue counts before and after dart format lib test flutter test flutter run -d ``` ## Generated and machine-owned files: don't hand-edit - <`lib/firebase_options.dart` (FlutterFire CLI)> - <`*.g.dart`, `*.freezed.dart`, `*.gr.dart`, `*.mocks.dart` (build_runner: json_serializable, freezed, auto_route, mockito)> - <`app_localizations*.dart` (gen-l10n, from the ARB files)> - <`GeneratedPluginRegistrant.*` under android/, ios/ and macos/, `ios/Flutter/Generated.xcconfig`, `.flutter-plugins-dependencies`, and `linux/flutter/generated_*`, `windows/flutter/generated_*` (rewritten by `flutter pub get` and builds)> ## Never do - Never commit secrets: `.env`, service-account JSON, keystores (`*.jks`, `key.properties`), App Store Connect keys (`*.p8`), API secret keys. - Never put a server-side secret in the Flutter app. Everything in `lib/` and in bundled assets ships to users. - Never deploy, publish or change remote state without explicit approval: <`firebase deploy`, store uploads, `git push`, …>. Prepare the change and tell the human what to run. - Never hand-edit the generated files listed above. - Don't bump major dependency versions or restructure folders unless the task asks for it. - ## Definition of done 1. Every touched `.dart` file passes `dart format --output=none --set-exit-if-changed`. 2. `flutter analyze` reports no new issues compared with before the change. Say both counts. 3. `flutter test` passes. New logic that doesn't need a device or backend has a unit test. 4. New UI works at phone and desktop widths, in light and dark mode. 5. The summary lists the files changed and every manual step left for the human (consoles, deploys, store settings). ## Known issues (as of ; update this list when fixed) - issues on Flutter .> -