iiEsaywebUIapp/AGENTS.md

AGENTS GUIDE FOR THIS REPO

Build, lint, test

• Install: flutter pub get
• Generate code (required for freezed/json): flutter pub run build_runner build --delete-conflicting-outputs
• Analyze (lints): flutter analyze
• Format: dart format . --fix
• Run app: flutter run -d ios | -d android
• Build release: flutter build apk --release; flutter build appbundle --release; flutter build ios --release
• Run all tests: flutter test
• Run single test file: flutter test path/to/test.dart
• Run single test by name: flutter test path/to/test.dart --name "test name substring"

Code style

• Use Flutter lints (analysis_options.yaml includes package:flutter_lints/flutter.yaml); avoid print, prefer logging/services. Fix analyzer warnings before merging.
• Imports: prefer relative imports within lib/, package:conduit for cross-feature access. Group as: dart:, package:, third-party, project; alphabetize within groups; no unused imports.
• Formatting: run dart format .; keep lines readable (< 100–120 cols). No trailing whitespace. Use const where possible.
• Types and null safety: use sound null-safety; avoid dynamic; prefer explicit types for public APIs; use final for immutables.
• Naming: lowerCamelCase for variables/functions, UpperCamelCase for classes/types; file names snake_case.dart; private members with leading _.
• State management: use Riverpod providers in features/* and core/providers; avoid global singletons except services injected via providers.
• Data models: use freezed/json_serializable where applicable; regenerate with build_runner after model changes.
• Error handling: never swallow errors; convert Dio/network/storage errors into domain errors via core/error/* (api_error_handler.dart, user_friendly_error_handler.dart). Surface user-safe messages; log details via services.
• Async/streams: cancel subscriptions; handle connectivity changes via core/services; prefer Future return for async methods.
• UI: keep widgets small and pure; move side effects to controllers/providers; respect theme in shared/theme/*; follow design tokens in shared/theme/app_theme.dart and shared/theme/theme_extensions.dart (Spacing, AppBorderRadius, Elevation, ConduitShadows, AppTypography).

Repo conventions

• Follow CI versions from .github/workflows/release.yml (Flutter stable 3.32.5, Java 21). Keep pubspec constraints aligned.
• No Cursor/Copilot rule files present. If added later (.cursor/rules or .github/copilot-instructions.md), mirror their guidance here.