## Architecture Rules

- Feature-first folder structure. Each feature in `lib/features/` with `data/`, `domain/`, `presentation/` layers.
- Clean Architecture layers: Presentation (widgets, controllers) → Domain (entities, repository interfaces) → Data (API, database, repository implementations).
- Riverpod for all state management. No `setState` except for local ephemeral widget state (text field focus, animation controllers).
- `@riverpod` annotation on controller classes. Code-generated providers via `riverpod_generator`. Never manually create `StateNotifierProvider` or `ChangeNotifierProvider`.
- Providers are the dependency injection mechanism. No service locator (get_it). No manual dependency passing through constructors across the widget tree.
- `go_router` for navigation. Declarative route configuration. `context.go()` for navigation, `context.push()` for stack navigation. No `Navigator.push`.
- `freezed` for all data models. Immutable, with `copyWith`, `toJson`/`fromJson`, union types for sealed classes.
- `build_runner` for code generation. Run after model or provider changes. Generated files: `*.g.dart`, `*.freezed.dart`.
- Feature modules must not import from other features directly. Shared code in `lib/core/`.
- Domain layer has no Flutter dependencies. Pure Dart classes and abstract interfaces.

## Coding Conventions

- Dart 3.6: records, patterns, sealed classes, class modifiers (`final class`, `interface class`).
- Very Good Analysis lint rules. Zero lint warnings. Fix all analyzer issues before commit.
- Naming: `UpperCamelCase` for types and extensions, `lowerCamelCase` for variables/functions/parameters, `SCREAMING_CAPS` for constants.
- File naming: `snake_case.dart`. One primary class per file. Widget files match widget name.
- Widget types: `StatelessWidget` for pure UI. `HookWidget` (flutter_hooks) for lifecycle management. `ConsumerWidget` for Riverpod-connected widgets.
- Private members: prefix with `_`. Private classes, methods, variables all use underscore prefix.
- Immutable by default: use `final` on all variable declarations unless mutation is required. Use `const` constructors where possible.
- `const` widgets: mark widget constructors as `const` when all fields are `final` and the widget takes no mutable state. Flutter optimizes const widget rebuilds.
- Trailing commas on all function calls and widget constructors with multiple arguments. Enables better dart format output.
- Widget tree: max 5 levels of nesting in a single `build()` method. Extract sub-widgets at 5+ levels.
- Extension methods for reusable utility on built-in types. Place in `lib/core/extensions/`.
- Prefer named parameters for functions with 2+ parameters. Use `required` for non-optional named params.
- Null safety: fully sound. No `!` operator in production code. Use `?.`, `??`, `if-case let`, or pattern matching.
- Imports: `dart:` first, `package:` second, relative imports third. Prefer `package:` imports over relative.
- No print statements. Use `debugPrint()` for development, or logging package for structured logs.
- Comments: `///` doc comments on public APIs. `//` for implementation notes. `// TODO(name):` for todos.

## Error Handling

- `AsyncValue<T>` from Riverpod for async state. Three states: `.data(value)`, `.loading()`, `.error(error, stack)`.
- UI: `ref.watch(provider).when(data: ..., loading: ..., error: ...)` pattern for rendering async states.
- Network errors: Dio interceptor catches `DioException`. Maps to `AppException` sealed class: `.network()`, `.server(statusCode, message)`, `.unauthorized()`, `.timeout()`.
- Repository layer: catches data-layer exceptions, maps to domain-specific errors.
- Controller layer: errors propagated through `AsyncValue.error`. UI displays error widget with retry callback.
- Form validation: `TextFormField` with `validator` callback. Return null for valid, error string for invalid.
- Snackbar for transient errors: `ScaffoldMessenger.of(context).showSnackBar(...)`. Controller exposes one-shot error events.
- Never catch generic `Exception`. Catch specific types: `DioException`, `DatabaseException`, `FormatException`.
- Crash reporting: Firebase Crashlytics in `FlutterError.onError` and `PlatformDispatcher.instance.onError`.
- Stack traces: always capture with `StackTrace.current` or from catch block. Pass to error reporting.

## Testing Conventions

- Widget tests: `testWidgets("description", (tester) async { ... })`. Pump widget with `pumpApp()` helper that wraps in `ProviderScope`.
- Controller/provider tests: use `ProviderContainer()` with overrides. Test state transitions.
- Repository tests: mock API with Mocktail. Assert repository transforms API responses to domain models.
- Mock pattern: `class MockUserRepository extends Mock implements UserRepository {}`. Configure with `when(() => mock.method()).thenReturn(value)`.
- Golden tests: `matchesGoldenFile('goldens/login_screen.png')` for visual regression. Update with `--update-goldens`.
- Integration tests: `flutter test integration_test/app_test.dart`. Test critical user flows end-to-end.
- Test naming: `test("should return user when login succeeds", () { ... })`.
- Provider testing: `container.read(authControllerProvider.notifier).login(email, password)`. Assert state changes.
- No `setUp` with side effects. Each test creates its own container and mocks.
- Coverage: 90% for controllers, 85% for repositories, 70% for widgets. Exclude generated files from coverage.

## Database & API Patterns

- Drift for SQLite: type-safe queries generated from Dart table definitions. Run `build_runner` after schema changes.
- Drift tables: Dart classes extending `Table`. Columns defined as getters: `TextColumn get name => text()()`.
- Drift queries: generated methods on database class. Custom queries with `@DriftAccessor`.
- API client: Dio with `BaseOptions(baseUrl, connectTimeout, receiveTimeout)`. Interceptors for auth token and error handling.
- API response: `ApiResponse<T>` wrapper with `data`, `message`, `meta` fields. JSON deserialized with `json_serializable`.
- Offline-first: Drift as source of truth. API syncs update local database. UI reads from Drift streams.
- Pagination: `FutureProvider.family((ref, page) => ...)` for paginated API calls. Infinite scroll with `ScrollController.addListener`.
- Image caching: `cached_network_image` for network images. Placeholder and error widgets.

## What Claude Should Never Do

- Never use `setState` for state that outlives a single widget or is shared between widgets. Use Riverpod providers.
- Never manually write `StateNotifierProvider` or `ChangeNotifierProvider`. Use `@riverpod` annotation with code generation.
- Never use `Navigator.push()` or `MaterialPageRoute`. Use `go_router` with `context.go()` or `context.push()`.
- Never use `get_it` or any service locator. Riverpod is the dependency injection mechanism.
- Never use `!` (null assertion) in production code. Handle nullability with `?.`, `??`, pattern matching, or `if-case`.
- Never create mutable data models. Use `@freezed` for immutable models with `copyWith`.
- Never edit generated files (`*.g.dart`, `*.freezed.dart`). Modify the source and re-run `build_runner`.
- Never use `BuildContext` after async gaps without checking `mounted`. Context may be invalid after await.
- Never import from one feature into another feature. Shared code belongs in `lib/core/`.
- Never use `print()`. Use `debugPrint()` for development output.
- Never skip trailing commas on multi-argument constructors and function calls.
- Never use `dynamic` type. Use `Object?` or define proper types.

## Project-Specific Context

- [YOUR APP NAME] — update with your project details
- Target platforms: iOS, Android, [Web / macOS / Windows / Linux]
- Backend: [REST API / Firebase / Supabase / Appwrite]
- Analytics: [Firebase Analytics / Amplitude / Mixpanel]
- Crash reporting: Firebase Crashlytics
- Push notifications: Firebase Cloud Messaging
- Distribution: [Google Play / App Store / TestFlight / Firebase App Distribution]
- CI/CD: [GitHub Actions / Codemagic / Bitrise] → Store upload