groundwork-method 0.0.1 → 0.10.0

package/src/engineer-skills/groundwork-flutter-engineer/references/data-and-contracts.md

@@ -0,0 +1,136 @@
+# Data and Contracts
+
+## Table of Contents
+- [The Seam](#the-seam)
+- [The Thin Client (Current Stance)](#the-thin-client-current-stance)
+- [When to Switch to Generated Clients](#when-to-switch-to-generated-clients)
+- [Repositories: Translation and Truth](#repositories-translation-and-truth)
+- [Error Mapping](#error-mapping)
+- [Configuration](#configuration)
+- [dio Conventions](#dio-conventions)
+- [Anti-patterns](#anti-patterns)
+
+---
+
+## The Seam
+
+The app reaches the capability core through exactly one seam:
+
+```
+ViewModel → Repository (abstract) → ApiClient (data/services/) → gateway
+```
+
+Nothing above the data layer knows the transport. A view model cannot tell whether the core is hosted or embedded, REST or gRPC. If transport details (URLs, status codes, `DioException`) appear above `data/`, the seam has leaked — fix the leak before the feature.
+
+## The Thin Client (Current Stance)
+
+The recorded contract-tooling stance (O8, settled 2026-06-12): while the promoted contract surface is small, the client is **hand-rolled and thin** — one method per contract operation, typed models in `domain/models/`, no codegen dependency:
+
+```dart
+class ApiClient {
+  ApiClient(this._dio);
+  final Dio _dio;
+
+  Future<Order> order(String id) async {
+    final res = await _dio.get<Map<String, dynamic>>('/api/v1/orders/$id');
+    return Order.fromJson(res.data ?? const {});
+  }
+
+  Future<Order> placeOrder(PlaceOrderRequest req) async {
+    final res = await _dio.post<Map<String, dynamic>>(
+      '/api/v1/orders',
+      data: req.toJson(),
+    );
+    return Order.fromJson(res.data ?? const {});
+  }
+}
+```
+
+Discipline that keeps "thin" honest:
+
+- Every method maps 1:1 to a promoted-contract operation — the method set is the contract's operation list, nothing speculative.
+- Request/response models live in `domain/models/` with explicit `fromJson`/`toJson` that match the contract schema field-for-field.
+- When the contract changes, the client changes in the same slice — the promoted `openapi.yaml` is the source of truth, and drift between it and this client is a defect.
+
+## When to Switch to Generated Clients
+
+The thin client is the lightest path **while the surface is small**. Once the promoted `openapi.yaml` grows past a handful of operations (or starts carrying complex schemas you are hand-mapping), switch to generation: `openapi_generator`'s **dart-dio** output via build_runner, consuming the promoted spec directly.
+
+The migration is contained by construction: repositories keep consuming a client; only the client's implementation becomes generated. Nothing above the data layer changes. Hand-mapping a large promoted contract is the defect the principles warn about — the contract is promoted precisely so clients can be generated from it.
+
+## Repositories: Translation and Truth
+
+Repositories own the boundary between contract types and domain models:
+
+```dart
+class RemoteOrderRepository implements OrderRepository {
+  RemoteOrderRepository(this._client);
+  final ApiClient _client;
+
+  List<Order>? _cache;
+
+  @override
+  Future<List<Order>> recent({bool refresh = false}) async {
+    if (!refresh && _cache != null) return _cache!;
+    _cache = await _client.recentOrders();
+    return _cache!;
+  }
+}
+```
+
+- Caching, retry policy, polling, and merge logic live here — not in view models, not in the client.
+- Contract DTO → domain model translation happens here and nowhere else.
+- Repositories are many-to-many with view models and never aware of each other.
+
+## Error Mapping
+
+The data layer converts transport failures into domain-meaningful states; `DioException` never crosses upward:
+
+```dart
+@override
+Future<HealthStatus> status() async {
+  try {
+    return await _client.health();
+  } on DioException catch (e) {
+    if (e.type == DioExceptionType.connectionTimeout ||
+        e.type == DioExceptionType.connectionError) {
+      return const HealthStatus.unreachable();
+    }
+    rethrow; // programming errors still surface loudly
+  }
+}
+```
+
+Rules of thumb:
+
+- **Expected failures** (offline, gateway down, 404 on an optional resource) become domain states the UI renders.
+- **Contract violations** (schema mismatch, unexpected 500s) surface as errors — they indicate a defect, and the view renders the error state.
+- Business rules about failures (retry budgets, "is this recoverable") still do not belong in views.
+
+## Configuration
+
+The gateway URL arrives at build time via `--dart-define`:
+
+```dart
+static const String apiBaseUrl = String.fromEnvironment(
+  'API_BASE_URL',
+  defaultValue: 'http://localhost:4000',
+);
+```
+
+- Android emulator → host: `http://10.0.2.2:4000`. iOS simulator → `http://localhost:4000`.
+- No `.env` files baked into the binary; no secrets in `--dart-define` either — a mobile binary is fully inspectable, so anything secret stays server-side.
+
+## dio Conventions
+
+- One `Dio` instance, configured in the client provider: `baseUrl`, timeouts, `Accept: application/json`.
+- Cross-cutting concerns (auth header injection, logging, retry) are **interceptors** on that instance — not per-call options scattered through methods.
+- dio throws on non-2xx by default; keep that behaviour and map in repositories rather than checking status codes inline.
+
+## Anti-patterns
+
+- **Transport above the data layer** — a view model importing `dio` or parsing status codes.
+- **Hand-mapping a grown contract** — switch to dart-dio generation; the seam is built for it.
+- **Speculative client methods** — operations the promoted contract does not define.
+- **Business rules in the surface** — validation semantics, pricing, permissions re-implemented in Dart. The core proves them; the surface renders results.
+- **Repositories calling repositories** — orchestration belongs in a view model or an earned use-case.

package/src/engineer-skills/groundwork-flutter-engineer/references/navigation.md

@@ -0,0 +1,122 @@
+# Navigation
+
+## Table of Contents
+- [The Router Is go_router](#the-router-is-go_router)
+- [The Route Table](#the-route-table)
+- [Typed Routes](#typed-routes)
+- [Tab Scaffolds: StatefulShellRoute](#tab-scaffolds-statefulshellroute)
+- [Auth Guards: Centralized redirect](#auth-guards-centralized-redirect)
+- [The Route as State](#the-route-as-state)
+- [Deep Links](#deep-links)
+- [What Remains for Navigator 1.0](#what-remains-for-navigator-10)
+
+---
+
+## The Router Is go_router
+
+go_router (flutter.dev verified publisher, declared feature-complete — a stable platform piece) owns app-level navigation. The router lives in one module as a provider:
+
+```dart
+final routerProvider = Provider<GoRouter>((ref) {
+  return GoRouter(
+    routes: [/* the route table */],
+    redirect: (context, state) => _guard(ref, state),
+  );
+});
+```
+
+`MaterialApp.router(routerConfig: ref.watch(routerProvider))` is the only place the router meets the widget tree. Hand-rolled `RouterDelegate`/Navigator 2.0 code is legacy — it is the API go_router exists to hide. Do not write it, and refactor it away on contact.
+
+## The Route Table
+
+One table, hierarchical, every destination declared:
+
+```dart
+GoRoute(
+  path: '/orders',
+  name: 'orders',
+  builder: (context, state) => const OrdersView(),
+  routes: [
+    GoRoute(
+      path: ':orderId',
+      name: 'order-detail',
+      builder: (context, state) =>
+          OrderDetailView(orderId: state.pathParameters['orderId']!),
+    ),
+  ],
+)
+```
+
+Conventions:
+
+- Paths are URL-shaped and lowercase-kebab; names exist for every route.
+- The view receives parsed parameters via its constructor — it does not read `GoRouterState` internally.
+- New screens are added to the table, never pushed ad hoc from a feature file.
+
+## Typed Routes
+
+As the table grows past a few routes, adopt `go_router_builder` typed routes — route paths and parameters as generated, compile-checked classes:
+
+```dart
+@TypedGoRoute<OrderDetailRoute>(path: '/orders/:orderId')
+class OrderDetailRoute extends GoRouteData {
+  const OrderDetailRoute({required this.orderId});
+  final String orderId;
+
+  @override
+  Widget build(BuildContext context, GoRouterState state) =>
+      OrderDetailView(orderId: orderId);
+}
+
+// Navigation becomes compile-checked:
+const OrderDetailRoute(orderId: '42').go(context);
+```
+
+Stringly-typed `context.go('/orders/$id')` calls scattered through features are the navigation equivalent of hand-rolled JSON — acceptable only while the table is a handful of routes, refactored to typed routes as it grows.
+
+## Tab Scaffolds: StatefulShellRoute
+
+Bottom-bar/tab UIs use `StatefulShellRoute.indexedStack` — per-tab navigation stacks whose state survives tab switches:
+
+```dart
+StatefulShellRoute.indexedStack(
+  builder: (context, state, shell) => AppScaffold(shell: shell),
+  branches: [
+    StatefulShellBranch(routes: [GoRoute(path: '/home', ...)]),
+    StatefulShellBranch(routes: [GoRoute(path: '/settings', ...)]),
+  ],
+)
+```
+
+Do not hand-roll tab stacks with nested Navigators.
+
+## Auth Guards: Centralized redirect
+
+Auth is one `redirect` function on the router — never per-screen checks:
+
+```dart
+String? _guard(Ref ref, GoRouterState state) {
+  final signedIn = ref.read(sessionProvider).isSignedIn;
+  final signingIn = state.matchedLocation == '/sign-in';
+  if (!signedIn && !signingIn) return '/sign-in?from=${state.matchedLocation}';
+  if (signedIn && signingIn) return '/';
+  return null;
+}
+```
+
+Wire the session provider to the router with `refreshListenable` (or rebuild the router provider on session change) so guard decisions re-evaluate when auth state changes.
+
+## The Route as State
+
+The URL is a first-class state container. Selected entity id, active tab, current screen — if the route encodes it, **no provider duplicates it**; a provider mirroring the route will drift. This also makes navigation state survive process death for free, which matters because mobile processes die constantly.
+
+## Deep Links
+
+Anything declared as a `GoRoute` is deep-linkable across Android/iOS — that falls out of the declarative table. Practical consequences:
+
+- Every route must render sensibly when entered **directly** (cold start onto `/orders/42`): the view model fetches what it needs from its id parameters; no route depends on in-memory state a previous screen happened to leave behind.
+- Guard-sensitive routes are protected by the central `redirect`, so deep links cannot skip auth.
+
+## What Remains for Navigator 1.0
+
+Imperative `showDialog`, `showModalBottomSheet`, and one-off local flows are fine — they are transient UI, not app navigation. The boundary: if a destination should be linkable, restorable, or guarded, it is a `GoRoute`; if it is a momentary overlay, Navigator 1.0 primitives are correct.

package/src/engineer-skills/groundwork-flutter-engineer/references/platform-channels.md

@@ -0,0 +1,93 @@
+# Platform Channels
+
+## Table of Contents
+- [The Decision Ladder](#the-decision-ladder)
+- [Check the Plugin Shelf First](#check-the-plugin-shelf-first)
+- [Pigeon: the Default for Structured APIs](#pigeon-the-default-for-structured-apis)
+- [Wrapping the Native Module](#wrapping-the-native-module)
+- [ffigen/jnigen: the Tracked Destination](#ffigenjnigen-the-tracked-destination)
+- [Raw MethodChannel](#raw-methodchannel)
+- [iOS Build Wiring](#ios-build-wiring)
+- [Testing the Boundary](#testing-the-boundary)
+
+---
+
+## The Decision Ladder
+
+When a capability is not reachable from Dart:
+
+1. **pub.dev** — a maintained, verified-publisher plugin is a dependency decision, not an interop project.
+2. **Pigeon module** — write Swift/Kotlin behind a generated, typed boundary.
+3. **Raw MethodChannel** — a single fire-and-forget call with no evolving surface, nothing more.
+
+Dropping to native is a **capability decision, never a performance reflex**. Profile in Dart first — rendering and isolates cover almost every performance complaint, and a native detour taken for imagined speed buys two codebases for one feature. Legitimate native triggers: a platform API with no maintained plugin (HealthKit details, background modes, vendor SDKs), OS-integrated UI Flutter cannot render (widgets/complications, App Intents), hardware access below the plugin ecosystem.
+
+## Check the Plugin Shelf First
+
+Before writing native code: search pub.dev, check publisher verification, maintenance cadence, and issue tracker health. Rewriting a maintained verified-publisher plugin is negative work. Write native code when the shelf is empty or unmaintained.
+
+## Pigeon: the Default for Structured APIs
+
+Define the API once in Dart; Pigeon generates type-safe stubs on both sides — misspelled methods and mistyped arguments become compile errors instead of runtime channel exceptions:
+
+```dart
+// pigeons/battery_api.dart
+import 'package:pigeon/pigeon.dart';
+
+@ConfigurePigeon(PigeonOptions(
+  dartOut: 'lib/data/services/gen/battery_api.g.dart',
+  kotlinOut: 'android/app/src/main/kotlin/.../BatteryApi.kt',
+  swiftOut: 'ios/Runner/BatteryApi.swift',
+))
+@HostApi()
+abstract class BatteryApi {
+  int batteryLevel();
+  bool isCharging();
+}
+```
+
+Run `dart run pigeon --input pigeons/battery_api.dart` and implement the generated interface in Kotlin/Swift. **Every structured Flutter↔native API goes through Pigeon** — keep the native side a small module the agent can regenerate.
+
+## Wrapping the Native Module
+
+The Dart side of a Pigeon API is a **service in the data layer**, like any other platform API:
+
+```dart
+class BatteryService {
+  BatteryService(this._api);
+  final BatteryApi _api;
+
+  Future<BatteryReading> read() async => BatteryReading(
+        level: await _api.batteryLevel(),
+        charging: await _api.isCharging(),
+      );
+}
+
+final batteryServiceProvider = Provider<BatteryService>(
+  (ref) => BatteryService(BatteryApi()),
+);
+```
+
+Repositories/view models consume the service; nothing above the data layer knows a channel exists. **Native code never grows business rules** — it is transport to an OS capability; rules live in the core or the view model where they are proven.
+
+## ffigen/jnigen: the Tracked Destination
+
+The ecosystem is mid-migration to channel-free codegen interop: `ffigen` (C/Obj-C/Swift; stable) and `jnigen` (Java/Kotlin via JNI; pre-1.0), on build hooks / native assets (default-enabled since Flutter 3.38). The stance:
+
+- **Adopt where a dependency already ships it** — that is the dependency's choice.
+- **Pigeon remains the app-code default** until the jnigen path reaches 1.0.
+- Aim refactors at the destination; re-evaluate at the next ecosystem survey.
+
+## Raw MethodChannel
+
+Acceptable for exactly one shape: a single trivial call with no evolving surface (toggle a platform flag, read one value). The moment a channel grows a second method or a structured payload, it becomes a Pigeon definition. Hand-written channels for any real API surface are legacy — stringly-typed, runtime-failing, agent-hostile.
+
+## iOS Build Wiring
+
+**Swift Package Manager is the iOS/macOS default as of Flutter 3.44.** New native modules and plugin dependencies use SwiftPM; CocoaPods is the legacy path kept only where a required dependency has not migrated. Do not add new Podfile-based wiring.
+
+## Testing the Boundary
+
+- **Unit/widget tiers:** fake the Pigeon-fronted **service** in Dart like any other service — the native side does not run.
+- **Emulator tier:** the native implementation is exercised by `integration_test` (or Patrol, when the flow crosses into OS UI) only where the capability is observable.
+- Pure pass-through wrappers over OS APIs get a thin smoke test, not a re-proof of the OS.

package/src/engineer-skills/groundwork-flutter-engineer/references/releases-and-distribution.md

@@ -0,0 +1,84 @@
+# Releases and Distribution
+
+## Table of Contents
+- [Why This Is Architecture](#why-this-is-architecture)
+- [Signing](#signing)
+- [CI/CD Pipeline](#cicd-pipeline)
+- [Versioning](#versioning)
+- [Forced Upgrade: the Compatibility Floor](#forced-upgrade-the-compatibility-floor)
+- [Shorebird Code Push](#shorebird-code-push)
+- [Release Checklist](#release-checklist)
+
+---
+
+## Why This Is Architecture
+
+A mobile surface cannot be rolled back and cannot be force-refreshed: every version ever shipped is potentially still running, store review adds days of latency, and a signing mistake can permanently lock the listing. Treat release engineering as the half of the contract-compatibility story that lives outside the repo — and keep it CI-driven, because a human clicking through Xcode is a step the delivery loop stalls on.
+
+## Signing
+
+**Android**
+
+- One upload keystore per app, generated once, stored in a secret manager **with an independent secure copy** — the official docs warn it is unrecoverable.
+- `key.properties` and the keystore are never in git; CI injects them from encrypted secrets (or Codemagic code-signing identities).
+- **Play App Signing** holds the actual app signing key, so a compromised upload key is rotatable.
+
+**iOS**
+
+- **App Store Connect API keys** authenticate CI — no human Apple ID sessions in automation.
+- Certificates/provisioning profiles are fastlane-match-style: encrypted, centrally stored, CI-fetched. Codemagic's managed signing is the equivalent.
+
+A keystore or service-account JSON committed to a repo is an **incident**, not a finding: rotate it, scrub history, then fix the pipeline. The generated `.gitignore` already excludes signing material — keep it that way.
+
+## CI/CD Pipeline
+
+Default stack: **GitHub Actions + fastlane** (`supply` → Play, `deliver`/`pilot` → App Store Connect/TestFlight). **Codemagic** is the recorded Flutter-native alternative; fastlane is preinstalled there, so the stacks compose. Pick one per product and record it.
+
+The standard flow:
+
+```
+PR        → analyze + widget tests + emulator integration lane (the test gate)
+main      → build signed release artifacts (CI-owned build number)
+artifact  → internal track / TestFlight first
+promote   → staged rollout to production
+```
+
+No artifact reaches a store that CI did not build, sign, and test. Manual store uploads are unrepeatable releases — refuse them.
+
+## Versioning
+
+pubspec carries `version: x.y.z+buildNumber`:
+
+- **Humans own `x.y.z`** — the user-visible, compatibility-relevant part.
+- **CI owns the build number**, auto-incrementing per release build via `--build-number` (and `--build-name` when overriding the version). Hand-bumped build numbers collide, and collided build numbers are store-upload rejections.
+
+## Forced Upgrade: the Compatibility Floor
+
+The core's stance is that a published contract field is never broken — because the fleet lags releases by months and cannot be recalled. Forced upgrade is the other half of that bargain:
+
+- The core (or a config endpoint / Firebase Remote Config) publishes a **minimum supported version**; the app compares at startup.
+- The **`upgrader`** package implements the prompt: `minAppVersion` below the floor auto-hides "Later"/"Ignore".
+- Two tiers, used deliberately:
+  - **Soft prompt** (dismissible) — new features, gentle migration pressure.
+  - **Hard force** (blocking) — security issues, or a contract the core can no longer serve.
+
+Operational rules: the floor advances slowly and each advance is a recorded product decision; between "never break a field" and the floor, every fleet version is served correctly. **Shipping a contract-breaking core change without first raising the floor and waiting out adoption is a sequencing defect** — flag it whenever a slice proposes it.
+
+## Shorebird Code Push
+
+Shorebird (stable on Android and iOS, store-policy compliant) is the OTA lane for **Dart-only hotfixes** — it skips store latency for Dart-level defects, with `shorebird_code_push` for in-app patch checks. Boundaries:
+
+- Native-code changes (plugins, Pigeon modules, SDK bumps) still require a store release.
+- A patched 1.4.2 is still 1.4.2 to the contract — OTA never substitutes for the version floor.
+- It is a hotfix channel, not the release process; features and floors move through the stores.
+
+## Release Checklist
+
+Before a release slice closes:
+
+- [ ] CI builds, signs, and tests the artifact; no manual store steps.
+- [ ] Build number CI-assigned; `x.y.z` deliberately chosen.
+- [ ] No signing material, `key.properties`, ASC keys, or service-account JSON in the diff.
+- [ ] Contract changes verified against the version floor (raise the floor first, then ship the change after adoption).
+- [ ] Internal track / TestFlight before production; staged rollout configured.
+- [ ] If Shorebird patched anything since the last release, the patch content is folded into this store release.

package/src/engineer-skills/groundwork-flutter-engineer/references/state-management.md

@@ -0,0 +1,166 @@
+# State Management
+
+## Table of Contents
+- [The Rules](#the-rules)
+- [Providers Are the Graph](#providers-are-the-graph)
+- [Notifier and AsyncNotifier](#notifier-and-asyncnotifier)
+- [Mutations for Action Lifecycle](#mutations-for-action-lifecycle)
+- [App State vs Ephemeral State](#app-state-vs-ephemeral-state)
+- [ref.watch vs ref.read](#refwatch-vs-refread)
+- [Testing Providers](#testing-providers)
+- [Refused Packages and Patterns](#refused-packages-and-patterns)
+
+---
+
+## The Rules
+
+1. **Riverpod 3.x** is the state-management and DI mechanism. One tool for both; no second container.
+2. Everything shared is a provider; everything provider-shaped is testable through overrides.
+3. Pin 3.x conservatively — the experimental offline-persistence API never enters load-bearing paths.
+4. `setState` survives only for ephemeral widget-local state.
+
+---
+
+## Providers Are the Graph
+
+Repositories, services, the contract client, view models, and derived state are all providers. The provider graph **is** the dependency-injection graph:
+
+```dart
+final apiClientProvider = Provider<ApiClient>((ref) => ApiClient(/* ... */));
+
+final userRepositoryProvider = Provider<UserRepository>(
+  (ref) => RemoteUserRepository(ref.watch(apiClientProvider)),
+);
+
+// Derived read-only state: a plain provider, not a class.
+final unreadCountProvider = Provider<int>(
+  (ref) => ref.watch(inboxViewModelProvider).valueOrNull?.unread.length ?? 0,
+);
+```
+
+Construction order, disposal, and test substitution fall out of the graph. Do not write a `Notifier` class where a derived provider (a function) suffices.
+
+`ProviderScope` at the root of `main.dart` is the only composition root. There is no `get_it`, no manually threaded constructors across features, no `InheritedWidget` plumbing for app state.
+
+---
+
+## Notifier and AsyncNotifier
+
+A view model is a `Notifier` (synchronous initial state) or `AsyncNotifier` (asynchronous initial state). `build` declares dependencies with `ref.watch` — when a dependency changes, state recomputes:
+
+```dart
+class InboxViewModel extends AsyncNotifier<InboxState> {
+  @override
+  Future<InboxState> build() async {
+    final messages = await ref.watch(messageRepositoryProvider).inbox();
+    return InboxState(messages: messages);
+  }
+
+  // Commands: the only way the view mutates anything.
+  Future<void> archive(String id) async {
+    await ref.read(messageRepositoryProvider).archive(id);
+    ref.invalidateSelf(); // re-derive from the source of truth
+  }
+}
+
+final inboxViewModelProvider =
+    AsyncNotifierProvider<InboxViewModel, InboxState>(InboxViewModel.new);
+```
+
+Prefer `ref.invalidateSelf()` (re-derive from the repository) over hand-patching state when the repository is cheap to re-read — hand-patched state drifts from the source of truth.
+
+In views, render `AsyncValue` exhaustively:
+
+```dart
+final state = ref.watch(inboxViewModelProvider);
+return state.when(
+  loading: () => const InboxSkeleton(),
+  error: (e, _) => ErrorPanel(error: e, onRetry: ...),
+  data: (inbox) => InboxList(inbox: inbox),
+);
+```
+
+Never `.valueOrNull!` your way past the loading and error cases in a view.
+
+---
+
+## Mutations for Action Lifecycle
+
+User actions that need pending/success/error surfacing — submit, delete, retry — use Riverpod 3 **Mutations** instead of hand-rolled `isLoading` booleans:
+
+```dart
+final archiveMessage = Mutation<void>();
+
+// In the view model / command site:
+archiveMessage.run(ref, (tsx) async {
+  await tsx.get(messageRepositoryProvider).archive(id);
+});
+
+// In the view:
+final archiveState = ref.watch(archiveMessage);
+// idle / pending / success / error — render the spinner or the failure from this.
+```
+
+One mutation per user action. If you are writing `bool _submitting` into a state class, reach for a Mutation instead.
+
+---
+
+## App State vs Ephemeral State
+
+The boundary question: **does anything outside this widget care?**
+
+| State | Mechanism |
+|---|---|
+| Session, fetched data, feature view state | provider / Notifier |
+| Selected tab, selected entity id, current screen | the **route** (go_router) — never duplicated in a provider |
+| Text-field focus, animation progress, tile expanded | `setState` in a `StatefulWidget` |
+
+Two corollaries:
+
+- **Route-mirroring providers drift.** If go_router already encodes it, read it from the route.
+- **State must be recoverable.** Mobile processes die constantly; anything not rebuildable from the core or the route is state the app silently loses. Design state so `build()` can reconstruct it.
+
+---
+
+## ref.watch vs ref.read
+
+- `ref.watch` — in `build` methods (Notifier and widget alike). Declares a reactive dependency.
+- `ref.read` — inside callbacks and commands only. A `ref.read` in `build` silently opts out of reactivity and is a bug even when it appears to work.
+- `ref.listen` — for side-effects on state change (showing a snackbar on error) — never for deriving state.
+
+---
+
+## Testing Providers
+
+Providers test without widgets. `ProviderContainer` plus overrides substitutes fakes at any node:
+
+```dart
+test('archiving removes the message from inbox state', () async {
+  final fakeRepo = FakeMessageRepository(seed: [message1, message2]);
+  final container = ProviderContainer(
+    overrides: [messageRepositoryProvider.overrideWithValue(fakeRepo)],
+  );
+  addTearDown(container.dispose);
+
+  await container.read(inboxViewModelProvider.future);
+  await container.read(inboxViewModelProvider.notifier).archive(message1.id);
+
+  final state = await container.read(inboxViewModelProvider.future);
+  expect(state.messages, [message2]);
+});
+```
+
+Widget tests use the same seam through `ProviderScope(overrides: [...])`. Test the **real Notifier with fake repositories** — mocking the Notifier itself proves nothing. Fakes over mocks throughout (see `references/testing.md`).
+
+---
+
+## Refused Packages and Patterns
+
+These are named so they are recognised and refused in review:
+
+- **GetX** — global mutable service locators, context-free magic. Never, in any role.
+- **provider as state management** — the 2019–2022 pattern; Riverpod is its successor by the same author. With Riverpod, even provider's DI role is subsumed — do not run both.
+- **setState as architecture** — app state in `StatefulWidget`s threaded through constructors.
+- **Riverpod experimental persistence** — explicitly experimental; not in load-bearing paths.
+- **Bloc** — not wrong, but a deliberate alternative for regulated/large-team contexts. Adopting it is a recorded decision, not a drift; never mix it with Riverpod in one app.
+- **One god-provider per screen** — split by concern; the graph recomputes at the right granularity only if you let it.