@cubis/foundry 0.3.66 → 0.3.68

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-design-system/references/shared-widgets.md

@@ -0,0 +1,29 @@
+# Shared Widgets
+
+## Create a Shared Widget When
+
+- the widget appears in multiple features,
+- the behavior is generic,
+- the visual contract should stay consistent across the app.
+
+## Keep It Out of Shared
+
+- feature-specific business copy,
+- repository or notifier logic,
+- route-specific navigation decisions,
+- domain models that only one feature understands.
+
+## Expected Shared State Widgets
+
+- `LoadingView`: generic loading skeleton or progress state
+- `ErrorView`: user-facing error with retry affordance and visible request ID when available
+- `EmptyView`: empty-state illustration/message with optional CTA
+- `DeadLetterView`: permanent failure state for sync or outbox issues
+- `SyncStatusBadge`: normalized badge for `pendingSync`, `synced`, `failed`, `dead`, or `conflict`
+
+## Widget Contract
+
+- Accept data and callbacks through constructor parameters.
+- Use design-system tokens only.
+- Keep public APIs small and predictable.
+- Prefer composition over large configurable mega-widgets.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-design-system/references/tokens-and-theme.md

@@ -0,0 +1,34 @@
+# Tokens and Theme
+
+## Shared Theme Contract
+
+Keep app-wide visual tokens under `shared/theme/`:
+
+- `app_colors.dart`
+- `app_spacing.dart`
+- `app_radius.dart`
+- `app_typography.dart`
+- `app_theme.dart`
+
+## Token Rules
+
+- Add a token only when it represents a reusable design concept.
+- Do not add screen-specific names such as `salesCardBlue`.
+- Prefer semantic names (`success`, `warning`, `surfaceMuted`) over raw hue names when the token has product meaning.
+- Keep spacing on a small fixed scale unless the design system already supports a larger one.
+
+## ThemeData Checklist
+
+- `useMaterial3: true`
+- `colorScheme` derived from the shared token palette
+- text theme mapped from `AppTypography`
+- input, card, dialog, app bar, and button themes aligned to the same token set
+- dark theme derived intentionally instead of default inversion
+
+## Audit Checklist
+
+- No `Color(...)` literals in feature widgets unless bridging external APIs
+- No raw `EdgeInsets` numbers when a spacing token exists
+- No raw `BorderRadius.circular(...)` when a radius token exists
+- No raw `TextStyle(...)` when a typography token exists
+- Loading, error, empty, and sync-status visuals use shared widgets

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-drift/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: flutter-drift
+description: "Use when implementing or refactoring Flutter local persistence with Drift: tables, DAOs, typed queries, indexes, transactions, and migrations. Do not use for simple key-value storage or remote-only networking work."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Drift
+
+## Purpose
+
+Guide project-local SQLite persistence through Drift while keeping persistence
+details in the data layer and repositories above the DAO boundary.
+
+## When to Use
+
+- Adding a new table or DAO
+- Changing schema or indexes
+- Writing a migration
+- Adding typed multi-table queries
+- Wiring repositories to local persistence
+
+## Instructions
+
+1. Define or update the table schema first.
+2. Add indexes only for real filter, join, or sort paths.
+3. Keep DAOs typed and persistence-focused.
+4. Expose Drift through repositories instead of letting UI code call DAOs directly.
+5. Use transactions for multi-table consistency.
+6. Use explicit schema version bumps and migration steps for every persisted change.
+7. Never drop or rewrite user data silently.
+8. Test migration behavior from at least the previous production schema.
+
+## Output Format
+
+Produce Drift guidance or code that:
+
+- keeps one app database entrypoint,
+- uses typed DAOs and query helpers,
+- explains index or migration choices when they matter,
+- includes migration-test expectations for schema changes.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/migrations.md` | Changing schema version, adding columns or tables, or planning upgrade safety. |
+| `references/query-patterns.md` | Designing tables, indexes, DAOs, joins, transactions, or repository integration. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Add a Drift table and DAO for offline product notes."
+- "Plan a safe migration for a new required column in this Flutter database."

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-drift/references/migrations.md

@@ -0,0 +1,22 @@
+# Migrations
+
+## Migration Rules
+
+- Increment `schemaVersion` every time persisted structure changes.
+- Use `onCreate` for first-install setup only.
+- Use `onUpgrade` for stepwise migrations from older versions.
+- Backfill new required columns safely with defaults or staged rollout.
+- Enable pragmas such as foreign keys intentionally in `beforeOpen`.
+
+## Safe Upgrade Checklist
+
+- Existing rows stay readable after upgrade.
+- New nullable columns start nullable unless a safe default exists.
+- New indexes are created during migration or through `createAll` only when safe.
+- Data transforms are deterministic and reversible enough for debugging.
+
+## Tests
+
+- Test opening a fresh database.
+- Test upgrading from the last production schema.
+- Test representative old data through the upgrade path.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-drift/references/query-patterns.md

@@ -0,0 +1,26 @@
+# Query Patterns
+
+## Table Design
+
+- Use stable IDs with clear ownership rules.
+- Add indexes for foreign keys, frequent filters, and common sort columns.
+- Keep sync-related columns explicit when offline behavior exists.
+
+## DAO Design
+
+- Expose streams for UI-facing reactive reads.
+- Expose one-shot reads for detail fetches or background work.
+- Keep write methods small and composable.
+- Return typed data or typed companions, not maps.
+
+## Repository Integration
+
+- Read flow: local-first, then optional remote refresh.
+- Write flow: persist locally first, then reconcile sync policy.
+- Mapper code belongs in the data layer, not in widgets.
+
+## Use Raw SQL Only When
+
+- a partial index or special SQLite feature needs it,
+- a complex query is materially clearer in SQL,
+- Drift's typed API cannot express the operation cleanly.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-feature/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: flutter-feature
+description: "Use when scaffolding a full Flutter feature across data, domain, presentation, routing, offline sync, and tests. Do not use for isolated single-layer work when a narrower Flutter skill already fits."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "1.0"
+compatibility: Claude Code, Codex, GitHub Copilot
+---
+
+# Flutter Feature Scaffold
+
+## Purpose
+
+Generate a complete, architecture-compliant Flutter feature instead of shipping
+partial stubs across disconnected layers.
+
+## When to Use
+
+- Adding a new feature with UI, state, data, and tests
+- Scaffolding a feature that spans multiple layers
+- Defining a feature that needs routing or offline support
+- Generating a consistent feature folder structure
+
+## Instructions
+
+1. Clarify or infer the feature name, data fields, operations, cross-feature dependencies, business-logic needs, and offline conflict strategy.
+2. Stop and resolve missing requirements before generating files.
+3. Keep naming and folder structure consistent across data, domain, presentation, routing, and tests.
+4. Add a domain service only when business rules justify it.
+5. Add composite providers only when a screen composes multiple features.
+6. Keep repository, service, notifier, and widget responsibilities separate.
+7. Ship tests with the feature instead of leaving verification for later.
+
+## Output Format
+
+Produce feature scaffolding guidance or code that:
+
+- names the expected files and layer ownership,
+- calls out optional pieces such as domain services or composite providers,
+- keeps offline writes on the outbox path when needed,
+- includes the test surface that should ship with the feature.
+
+## References
+
+Load only what the current step needs.
+
+| File | Load when |
+| --- | --- |
+| `references/architecture-rules.md` | Checking layer boundaries, naming, app-state rules, and design-system constraints. |
+| `references/composite-provider.md` | A screen depends on multiple features and needs provider-layer composition. |
+| `references/testing-patterns.md` | Generating repository, service, notifier, or widget tests. |
+| `references/outbox-pattern.md` | The feature writes offline, syncs later, or needs conflict or dead-letter behavior. |
+
+## Scripts
+
+No helper scripts are required for this skill right now.
+
+## Examples
+
+- "Scaffold a Flutter inventory feature with offline edits and tests."
+- "Generate the full feature structure for a new sales module."

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-feature/references/architecture-rules.md

@@ -0,0 +1,85 @@
+# Architecture Rules Reference
+
+## Layer Boundaries (NEVER cross these)
+- Repository knows: Drift DAO + Retrofit API + OutboxService. Nothing else.
+- Service knows: repositories and other services. Zero Flutter, zero Riverpod.
+- Notifier knows: providers, services. Calls service/repo. Updates AppState.
+- Widget knows: notifier. Renders AppState. Calls notifier methods.
+- Cross-feature data: compose at the Riverpod provider layer ONLY (never repo→repo imports).
+
+## File Rules
+- One public class per file. Filename = class name in snake_case.
+- Private helpers used only by that class may colocate.
+- Extension methods on the class may colocate.
+- If a helper is used by 2+ classes → give it its own file.
+
+## Naming
+- Files: `<feature>_<suffix>.dart` (e.g. `product_repository.dart`)
+- Classes: `<Feature><Suffix>` (e.g. `ProductRepository`)
+- Provider variables: `<feature><Suffix>Provider` (e.g. `productRepositoryProvider`)
+- All codegen annotations: `@riverpod` (lowercase) on provider functions and Notifier classes
+
+## AppState<T> — All 5 cases must be handled
+```dart
+sealed class AppState<T> {
+  const factory AppState.loading()                                      = _Loading;
+  const factory AppState.data(T value)                                  = _Data;
+  const factory AppState.empty()                                        = _Empty;
+  const factory AppState.error(AppError error)                          = _Error;
+  const factory AppState.deadLetter({required AppError error, required String requestId}) = _DeadLetter;
+}
+```
+
+## AppError — Every error must carry a requestId
+```dart
+sealed class AppError {
+  const factory AppError.client({required String requestId, required int statusCode, required String userMessage, String? developerMessage}) = ClientError;
+  const factory AppError.server({required String requestId, required int statusCode, required String userMessage}) = ServerError;
+  const factory AppError.network({required String requestId, required String userMessage, int retryCount}) = NetworkError;
+  const factory AppError.database({required String requestId, required String userMessage, required Object cause}) = DatabaseError;
+  const factory AppError.syncDead({required String requestId, required String feature, required String operation, required String userMessage, required List<String> errorLog}) = SyncDeadError;
+  const factory AppError.conflict({required String requestId, required String userMessage, required Map<String, dynamic> localData, required Map<String, dynamic> serverData}) = ConflictError;
+}
+```
+
+## Repository Write Pattern (always)
+```dart
+Future<T> create(CreateInput input) async {
+  final operationId = const Uuid().v4();
+  final local = await dao.insert(input.toCompanion(operationId));
+  await outbox.enqueue(operationId: operationId, feature: '<n>', operation: 'create', payload: input.toJson());
+  if (await connectivity.isOnline) outbox.drainNow().ignore();
+  return local;
+}
+```
+
+## Notifier Pattern (always thin)
+```dart
+@riverpod
+class <N>Notifier extends _$<N>Notifier {
+  @override
+  AppState<List<T>> build() {
+    ref.listen(<n>StreamProvider, (_, next) {
+      next.when(
+        data: (items) => state = items.isEmpty ? const AppState.empty() : AppState.data(items),
+        loading: () => state = const AppState.loading(),
+        error: (e, _) => state = AppState.error(_mapError(e)),
+      );
+    });
+    return const AppState.loading();
+  }
+  AppError _mapError(Object e) => ref.read(errorHandlerProvider).map(e);
+}
+```
+
+## Design System — NEVER hardcode
+- Colors: `AppColors.<name>` only
+- Spacing: `AppSpacing.xs/sm/md/lg/xl/xxl` (4/8/16/24/32/48)
+- Radius: `AppRadius.sm/md/lg/full`
+- Text: `AppTypography.<style>` only
+- SyncStatusBadge: required on any widget displaying a record with syncStatus
+
+## Auth Storage Rules
+- Access token + refresh token → `FlutterSecureStorage` only
+- Non-sensitive (userId, locale, theme) → `SharedPreferences`
+- NEVER store tokens in SharedPreferences

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-feature/references/composite-provider.md

@@ -0,0 +1,58 @@
+# Composite Provider Pattern
+
+## The Rule
+When a screen needs data from multiple features (e.g. product + category +
+inventory), NEVER import one repository from another repository. Compose at
+the Riverpod provider layer only.
+
+## Pattern
+```dart
+// Result type — freezed sealed class
+@freezed
+class ProductDetailState with _$ProductDetailState {
+  const factory ProductDetailState({
+    required Product product,
+    required Category category,
+    required InventoryStock inventory,
+  }) = _ProductDetailState;
+}
+
+// Composite provider — each repo stays independent
+@riverpod
+Future<ProductDetailState> productDetail(Ref ref, String productId) async {
+  final product = await ref.watch(productRepositoryProvider).getById(productId);
+  if (product == null) throw AppError.client(
+    requestId: const Uuid().v4(),
+    statusCode: 404,
+    userMessage: 'Product not found',
+  );
+  final category  = await ref.watch(categoryRepositoryProvider).getById(product.categoryId);
+  final inventory = await ref.watch(inventoryRepositoryProvider).getByProduct(productId);
+
+  return ProductDetailState(
+    product:   product,
+    category:  category!,
+    inventory: inventory,
+  );
+}
+```
+
+## Test
+```dart
+test('composes all three repos', () async {
+  final container = ProviderContainer(overrides: [
+    productRepositoryProvider.overrideWith((_) => FakeProductRepository()),
+    categoryRepositoryProvider.overrideWith((_) => FakeCategoryRepository()),
+    inventoryRepositoryProvider.overrideWith((_) => FakeInventoryRepository()),
+  ]);
+  final state = await container.read(productDetailProvider('p1').future);
+  expect(state.category.name, isNotEmpty);
+  expect(state.inventory, isNotNull);
+});
+```
+
+## When to use
+- Screen needs data from 2+ features
+- Provider function (not a Notifier) — it's read-only composition
+- State type is a dedicated `<Feature>DetailState` freezed class
+- File goes in: `features/<main-feature>/presentation/providers/<n>_detail_provider.dart`

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-feature/references/outbox-pattern.md

@@ -0,0 +1,87 @@
+# Outbox Pattern Reference
+
+## The Rule
+Every write = local Drift first → outbox enqueue → return immediately.
+Never await the network before returning to UI.
+
+## Outbox Table (in AppDatabase)
+```dart
+class OutboxTable extends Table {
+  IntColumn  get id            => integer().autoIncrement()();
+  TextColumn get operationId   => text()();   // UUID v4 — dedup key for server
+  TextColumn get feature       => text()();   // e.g. 'product', 'sale'
+  TextColumn get operation     => text()();   // 'create' | 'update' | 'delete'
+  TextColumn get payload       => text()();   // jsonEncode(input.toJson())
+  IntColumn  get retryCount    => integer().withDefault(const Constant(0))();
+  IntColumn  get maxRetries    => integer().withDefault(const Constant(3))();
+  TextColumn get status        => text().withDefault(const Constant('pending'))();
+  // pending → processing → done | failed → dead
+  DateTimeColumn get createdAt     => dateTime()();
+  DateTimeColumn get lastAttemptAt => dateTime().nullable()();
+  TextColumn     get errorLog      => text().nullable()();
+}
+```
+
+## Repository Write Template
+```dart
+Future<T> create(Create<T>Input input) async {
+  final operationId = const Uuid().v4();
+
+  // 1. Write locally — always succeeds even offline
+  final local = await dao.insert(
+    input.toCompanion(operationId: operationId),
+  );
+
+  // 2. Queue for sync
+  await outbox.enqueue(
+    operationId: operationId,
+    feature:     '<feature>',
+    operation:   'create',
+    payload:     input.toJson(),
+  );
+
+  // 3. Try immediate sync if online (fire-and-forget)
+  if (await connectivity.isOnline) outbox.drainNow().ignore();
+
+  // 4. Return local result — UI never waits for server
+  return local;
+}
+```
+
+## Sync Status on Drift Table
+Every table that participates in offline sync adds:
+```dart
+TextColumn get syncStatus => text()
+  .withDefault(const Constant('pendingSync'))();
+// Values: pendingSync | synced | failed | dead | conflict
+```
+
+## Conflict Strategies
+Declare per-feature in the repository or service:
+```dart
+static const conflictStrategy = ConflictStrategy.clientWins;
+// clientWins     — offline action wins (sales, POS)
+// serverWins     — server is truth (pricing, master data)
+// lastWriteWins  — compare updatedAt timestamps
+// manualResolve  — surface ConflictError to user (safety-critical)
+```
+
+## OutboxService (auto-drain on reconnect)
+The outbox service watches connectivity and auto-drains:
+```dart
+@override
+AppState<OutboxState> build() {
+  ref.listen(connectivityProvider, (_, next) {
+    if (next == ConnectivityStatus.online) drainNow();
+  });
+  return const AppState.idle();
+}
+```
+
+## SyncStatusBadge Usage
+Show on any ListTile or Card that displays a record with syncStatus:
+```dart
+SyncStatusBadge(status: item.syncStatus)
+// Renders: 🕐 grey (pendingSync) | ✅ green (synced)
+//          ⚠️ amber (failed) | ❌ red (dead) | ⚡ orange (conflict)
+```

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/flutter-feature/references/testing-patterns.md

@@ -0,0 +1,218 @@
+# Testing Patterns Reference
+
+## Layer 1: Repository Test (in-memory Drift + mocktail)
+```dart
+void main() {
+  late AppDatabase db;
+  late Mock<N>Api mockApi;
+  late MockOutboxService mockOutbox;
+  late MockConnectivityService mockConnectivity;
+  late <N>Repository sut;
+
+  setUp(() {
+    db = AppDatabase(NativeDatabase.memory());
+    mockApi = Mock<N>Api();
+    mockOutbox = MockOutboxService();
+    mockConnectivity = MockConnectivityService();
+    when(() => mockConnectivity.isOnline).thenAnswer((_) async => false);
+    sut = <N>Repository(
+      dao: <N>Dao(db),
+      api: mockApi,
+      outbox: mockOutbox,
+      connectivity: mockConnectivity,
+    );
+  });
+
+  tearDown(() => db.close());
+
+  group('create', () {
+    test('writes to local DB immediately', () async {
+      await sut.create(fake<N>Input());
+      final items = await db.<n>Dao.getAll();
+      expect(items.length, 1);
+    });
+
+    test('enqueues in outbox with operationId', () async {
+      await sut.create(fake<N>Input());
+      verify(() => mockOutbox.enqueue(
+        operationId: any(named: 'operationId'),
+        feature: '<n>',
+        operation: 'create',
+        payload: any(named: 'payload'),
+      )).called(1);
+    });
+
+    test('does NOT call API directly', () async {
+      await sut.create(fake<N>Input());
+      verifyNever(() => mockApi.create(any()));
+    });
+  });
+
+  group('syncFromRemote', () {
+    test('upserts all remote records into local DB', () async {
+      when(() => mockApi.getAll()).thenAnswer((_) async => [fake<N>Dto()]);
+      await sut.syncFromRemote();
+      final items = await db.<n>Dao.getAll();
+      expect(items.length, 1);
+    });
+  });
+}
+```
+
+## Layer 2: Service Test (pure Dart — no Flutter, no Riverpod)
+```dart
+void main() {
+  late <N>Service sut;
+  late Mock<N>Repository mockRepo;
+
+  setUp(() {
+    mockRepo = Mock<N>Repository();
+    sut = <N>Service(repository: mockRepo, /* other deps */);
+  });
+
+  group('<operation>', () {
+    test('returns Left when <failure condition>', () async {
+      // Arrange: set up conditions that trigger failure
+      final result = await sut.<operation>(/* bad input */);
+      expect(result.isLeft(), true);
+      result.fold(
+        (err) => expect(err, isA<ClientError>()),
+        (_) => fail('should have been Left'),
+      );
+    });
+
+    test('returns Right on success', () async {
+      when(() => mockRepo.<action>(any())).thenAnswer((_) async => fake<N>());
+      final result = await sut.<operation>(/* valid input */);
+      expect(result.isRight(), true);
+    });
+  });
+}
+```
+
+## Layer 3: Notifier Test (ProviderContainer)
+```dart
+void main() {
+  late ProviderContainer container;
+
+  ProviderContainer makeContainer({List<Override> overrides = const []}) =>
+    ProviderContainer(overrides: [
+      <n>RepositoryProvider.overrideWith((_) => Fake<N>Repository()),
+      ...overrides,
+    ]);
+
+  tearDown(() => container.dispose());
+
+  test('initial state is AppState.loading()', () {
+    container = makeContainer();
+    expect(container.read(<n>NotifierProvider), const AppState.loading());
+  });
+
+  test('transitions to AppState.data when items exist', () async {
+    container = makeContainer();
+    await container.pump(); // allow stream to emit
+    expect(container.read(<n>NotifierProvider), isA<_Data>());
+  });
+
+  test('transitions to AppState.empty when no items', () async {
+    container = makeContainer(overrides: [
+      <n>RepositoryProvider.overrideWith((_) => Empty<N>Repository()),
+    ]);
+    await container.pump();
+    expect(container.read(<n>NotifierProvider), const AppState.empty());
+  });
+
+  test('error state contains non-empty requestId', () async {
+    container = makeContainer(overrides: [
+      <n>RepositoryProvider.overrideWith((_) => Failing<N>Repository()),
+    ]);
+    await container.pump();
+    final state = container.read(<n>NotifierProvider);
+    expect(state, isA<_Error>());
+    expect((state as _Error).error.requestId, isNotEmpty);
+  });
+}
+```
+
+## Layer 4: Widget Test (all 5 AppState variants)
+```dart
+void main() {
+  Widget buildSubject(AppState<List<<N>>> state) =>
+    ProviderScope(
+      overrides: [
+        <n>NotifierProvider.overrideWith((_) => FixedState<N>Notifier(state)),
+      ],
+      child: const MaterialApp(home: <N>ListPage()),
+    );
+
+  testWidgets('shows LoadingView in loading state', (tester) async {
+    await tester.pumpWidget(buildSubject(const AppState.loading()));
+    expect(find.byType(LoadingView), findsOneWidget);
+  });
+
+  testWidgets('shows EmptyView in empty state', (tester) async {
+    await tester.pumpWidget(buildSubject(const AppState.empty()));
+    expect(find.byType(EmptyView), findsOneWidget);
+  });
+
+  testWidgets('shows data in data state', (tester) async {
+    await tester.pumpWidget(buildSubject(AppState.data([fake<N>()])));
+    expect(find.byType(<N>Card), findsOneWidget);
+  });
+
+  testWidgets('shows ErrorView with selectable requestId', (tester) async {
+    final err = AppError.network(requestId: 'test-req-id', userMessage: 'Oops');
+    await tester.pumpWidget(buildSubject(AppState.error(err)));
+    expect(find.byType(ErrorView), findsOneWidget);
+    expect(find.textContaining('test-req-id'), findsOneWidget);
+  });
+
+  testWidgets('shows DeadLetterView with retry button', (tester) async {
+    final err = AppError.syncDead(requestId: 'dlq-id', feature: '<n>',
+      operation: 'create', userMessage: 'Failed', errorLog: []);
+    await tester.pumpWidget(buildSubject(
+      AppState.deadLetter(error: err, requestId: 'dlq-id'),
+    ));
+    expect(find.byType(DeadLetterView), findsOneWidget);
+    expect(find.text('Retry'), findsOneWidget);
+  });
+}
+```
+
+## Layer 5: Golden Test (shared widgets)
+```dart
+void main() {
+  testGoldens('ErrorView renders correctly', (tester) async {
+    await loadAppFonts();
+    await tester.pumpWidgetBuilder(
+      ErrorView(
+        error: AppError.network(requestId: 'abc-123', userMessage: 'No connection'),
+        onRetry: () {},
+      ),
+      surfaceSize: const Size(400, 300),
+    );
+    await screenMatchesGolden(tester, 'error_view');
+  });
+}
+```
+
+## Fake Repository Helpers
+```dart
+// Always create typed fakes — never use mocks for repositories in widget tests
+class Fake<N>Repository implements <N>Repository {
+  final List<<N>> items;
+  Fake<N>Repository({this.items = const []});
+
+  @override Stream<List<<N>>> watchAll() => Stream.value(items);
+  @override Future<bool> isEmpty() async => items.isEmpty;
+  @override Future<<N>> create(Create<N>Input input) async => fake<N>();
+  @override Future<void> syncFromRemote() async {}
+}
+
+class Failing<N>Repository implements <N>Repository {
+  @override Stream<List<<N>>> watchAll() => Stream.error(
+    Exception('DB error'), StackTrace.empty,
+  );
+  // ... other methods throw
+}
+```