@cubis/foundry 0.3.10

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/riverpod-3/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: "riverpod-3"
+displayName: "Riverpod 3 Expert"
+description: "Riverpod 3 best practices for codegen, UI interaction boundaries, caching, paging, lifecycle, and testing"
+keywords:
+  [
+    "riverpod",
+    "riverpod 3",
+    "flutter",
+    "state management",
+    "asyncnotifier",
+    "codegen",
+    "keepalive",
+    "testing",
+  ]
+---
+
+# Riverpod 3 Expert
+
+## Overview
+
+Use this skill for production-grade Riverpod 3 usage in Flutter apps.
+Focus: correct provider lifecycles, predictable UI interaction, rebuild control, side effects, and testability.
+
+## When to Use
+
+- Creating or refactoring providers/notifiers
+- Solving rebuild storms or dependency loops
+- Designing refresh/paging/cache behavior
+- Defining provider lifecycles (`autoDispose` vs `keepAlive`)
+- Writing Riverpod unit/widget tests
+
+## Quick Reference
+
+### AsyncNotifier Pattern
+
+```dart
+@riverpod
+class OrdersController extends _$OrdersController {
+  @override
+  FutureOr<OrdersState> build() async {
+    final repo = ref.watch(ordersRepositoryProvider);
+    final items = await repo.fetchOrders();
+    return OrdersState(items: items);
+  }
+
+  Future<void> refresh() async {
+    ref.invalidateSelf();
+    await future;
+  }
+
+  Future<void> createOrder(CreateOrderInput input) async {
+    final repo = ref.read(ordersRepositoryProvider);
+    state = const AsyncLoading();
+    state = await AsyncValue.guard(() async {
+      await repo.createOrder(input);
+      if (!ref.mounted) return const OrdersState(items: []);
+      final items = await repo.fetchOrders();
+      return OrdersState(items: items);
+    });
+  }
+}
+```
+
+### watch/read/listen/listenManual
+
+```dart
+// Build/render: watch
+final state = ref.watch(ordersControllerProvider);
+
+// User callbacks: read
+onPressed: () => ref.read(ordersControllerProvider.notifier).refresh();
+
+// UI side effects in build-capable context
+ref.listen(ordersControllerProvider, (prev, next) {
+  next.whenOrNull(error: (e, st) => showErrorSnackBar(context, e));
+});
+
+// Lifecycle side effects (initState/dispose flows)
+late final remove = ref.listenManual(authStateProvider, (prev, next) {
+  if (next.isLoggedOut) context.go('/login');
+});
+```
+
+### keepAlive Rule
+
+```dart
+// Use only for app-wide long-lived state
+@Riverpod(keepAlive: true)
+SessionState sessionState(Ref ref) => const SessionState.unknown();
+```
+
+Default to auto-dispose for route/screen-scoped and family providers.
+
+## Core Rules (Do/Don't)
+
+1. Do use `ref.watch` only in widget/provider build paths.
+2. Do use `ref.read` for callbacks and imperative actions.
+3. Do use `ref.listen`/`ref.listenManual` for side effects (navigation/snackbar/dialog).
+4. Don't trigger side effects from render branches (`watch + if + navigate`).
+5. Don't call notifier mutation methods from widget `build`.
+6. Don't mutate collections in-place; always emit new immutable values.
+7. Do keep provider parameters stable and immutable (correct `==/hashCode`).
+8. Do keep business state in providers and ephemeral UI state in widgets.
+
+## KeepAlive Decision Matrix
+
+Use `keepAlive: true` only when all are true:
+- state should survive route changes,
+- recomputation is expensive,
+- cardinality is low (not unbounded families).
+
+Avoid keepAlive for:
+- search/filter family providers,
+- row/detail item families,
+- short-lived forms.
+
+## Loop Avoidance Checklist
+
+- No notifier writes inside provider `build()` unless conditional and bounded.
+- No unconditional `invalidateSelf()` in `build()`.
+- No provider cycles (A watches B and B watches A).
+- No `ref.watch` in callbacks.
+- Audit repeated rebuilds with narrowed `select` usage.
+
+## Steering Files
+
+- `loop-avoidance.md` - Loop diagnostics and safe patterns
+- `minimal-rebuild.md` - `select`, widget splitting, item-level providers
+- `provider-layout.md` - Generic provider organization and boundaries
+- `refresh-cache-paging.md` - Refresh/paging/cache recipes
+- `testing.md` - ProviderContainer and widget test patterns
+
+## Examples
+
+- `attendance_paging.md` - Complete paging example
+- `profile_edit.md` - Form workflow example
+
+## Templates
+
+- `cache_policy.dart` - TTL helper for repository cache policy
+- `paged_controller.dart` - Cursor/page-based infinite list controller
+- `riverpod_controller_test` - Provider/controller test template

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/riverpod-3/examples/attendance_paging.md

@@ -0,0 +1,29 @@
+# Example: Attendance list with paging + refresh (realistic)
+
+This example shows how to implement:
+- initial load (today’s attendance)
+- pull-to-refresh
+- infinite scroll “load more” (older records)
+- cached-first UX
+
+## Files
+- `features/attendance/attendance_controller.dart`
+- `features/attendance/attendance_state.dart`
+- `features/attendance/views/attendance_view.dart`
+
+## State (simplified)
+Use `PagedState<AttendanceRecord>` from the template.
+
+## Controller
+Use `PagedItemsController` template but rename:
+- `PagedAttendanceController`
+- `AttendanceRepository.fetchAttendancePage(...)`
+
+## UI
+- The screen watches the controller provider.
+- A `ScrollController` triggers `loadNextPage` when close to bottom.
+- `RefreshIndicator` calls `refresh()`.
+
+Important minimal-rebuild tip:
+- The list widget should be a separate widget that receives `items` as plain values.
+- Only one place watches the provider.

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/riverpod-3/examples/profile_edit.md

@@ -0,0 +1,15 @@
+# Example: Profile edit flow (load + edit + save, loop-free)
+
+Goal:
+- Load profile (AsyncNotifier build)
+- Edit in UI without triggering network calls per keystroke
+- Save -> invalidateSelf -> refresh
+
+Pattern:
+- Controller exposes AsyncValue<ProfileState>.
+- Text fields use local `TextEditingController` for draft edits.
+- On Save: call controller.save(draft) (ref.read(notifier))
+- After save success: controller invalidates itself so build reloads canonical data.
+
+This avoids the common anti-pattern:
+- writing draft state directly into provider on each keystroke (causes rebuild storms).

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/riverpod-3/references/loop-avoidance.md

@@ -0,0 +1,68 @@
+# Infinite loop & rebuild-storm avoidance (Riverpod 3)
+
+## Common loop sources
+
+### 1) Mutation calls in widget build
+Bad:
+```dart
+if (needsLoad) ref.read(itemsControllerProvider.notifier).load();
+```
+Every rebuild can re-trigger the write path.
+
+Fix:
+- Trigger in explicit user callbacks.
+- Trigger initial load in provider `build()`.
+- Use `ref.listenManual` in widget lifecycle when you need one-time imperative hooks.
+
+### 2) Self-invalidating provider build
+Bad:
+- `build()` unconditionally calls `ref.invalidateSelf()`.
+- `build()` performs persistent writes each run.
+
+Fix:
+- Keep `build()` declarative.
+- Mutations belong in methods.
+- Use dependency `watch` so recompute happens naturally when inputs change.
+
+### 3) Wrong watch/read boundaries
+Bad:
+```dart
+onPressed: () async {
+  final v = ref.watch(filtersProvider); // WRONG
+}
+```
+Fix:
+```dart
+onPressed: () async {
+  final v = ref.read(filtersProvider);
+}
+```
+
+### 4) In-place state mutation
+Bad:
+```dart
+state.value!.items.add(item);
+state = state;
+```
+Fix:
+```dart
+final current = state.valueOrNull ?? const ItemsState(items: []);
+state = AsyncData(current.copyWith(items: [...current.items, item]));
+```
+
+### 5) Circular provider graph
+Bad:
+- `aProvider` watches `bProvider`
+- `bProvider` watches `aProvider`
+
+Fix:
+- Extract shared dependency into `baseProvider`.
+- Keep read model and write model separated.
+
+## Quick debug flow
+
+1. Identify the smallest widget rebuilding repeatedly.
+2. Search for `invalidateSelf`, `state =`, and notifier calls in build paths.
+3. Confirm no `watch` usage in callbacks.
+4. Confirm immutable updates and stable family params.
+5. Add temporary logs to provider build/mutation methods to locate loop edge.

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/riverpod-3/references/minimal-rebuild.md

@@ -0,0 +1,64 @@
+# Minimal rebuild patterns (Riverpod 3)
+
+## The goal
+Only the widgets that *use* a value should rebuild when that value changes.
+
+## Patterns
+
+### 1) `select` in widgets
+Use select to watch one field:
+
+```dart
+final title = ref.watch(profileControllerProvider.select((s) => s.title));
+```
+
+Do this especially for:
+- App bars
+- Buttons enabled/disabled flags
+- Small pieces of derived UI state
+
+### 2) Split widgets by responsibility
+- Parent screen: watches overall async state and routes to child widgets.
+- Child widgets: pure renderers that take plain Dart values.
+
+### 3) `listen` for side effects
+Snackbars, dialogs, navigation:
+- use `ref.listen` in build (safe)
+- do not “watch + if” side effects
+
+```dart
+ref.listen(authStateProvider, (prev, next) {
+  if (next is LoggedOut) context.go('/login');
+});
+```
+
+### 4) Avoid rebuilding big lists
+If list items update individually:
+- expose an item-level family provider:
+
+```dart
+@riverpod
+Leave? leaveById(Ref ref, {required String id, required String orgId}) {
+  final leaves = ref.watch(leaveListControllerProvider(orgId: orgId)).valueOrNull?.items ?? const [];
+  return leaves.firstWhereOrNull((e) => e.id == id);
+}
+```
+
+Then each tile watches only its item:
+
+```dart
+final leave = ref.watch(leaveByIdProvider(id: leaveId, orgId: orgId));
+```
+
+### 5) Keep state immutable
+If you mutate a List in-place, Riverpod can't detect changes reliably and `select` optimizations break.
+Always replace collections:
+- `state = state.copyWith(items: [...state.items, ...newItems]);`
+- `List.unmodifiable(...)`
+
+## Under-the-hood mental model (why this works)
+
+- Providers form a dependency graph.
+- `ref.watch` registers a dependency edge.
+- When a provider emits a new value, dependents are invalidated and rebuilt.
+- `select` narrows the dependency to a projected value, reducing rebuild triggers.

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/riverpod-3/references/provider-layout.md

@@ -0,0 +1,77 @@
+# Provider layout (Riverpod 3 codegen, general)
+
+## Naming conventions
+
+- Repository DI provider: `{feature}RepositoryProvider`
+- Controller provider (AsyncNotifier): `{feature}ControllerProvider`
+- Query/filter families: `{feature}QueryProvider`
+- App-wide state providers: `{name}Provider` with `@Riverpod(keepAlive: true)` only when justified
+
+## Suggested structure
+
+```
+features/{feature}/
+├── data/
+│   ├── datasources/
+│   ├── repositories/
+│   └── models/
+├── domain/
+│   ├── entities/
+│   ├── repositories/
+│   └── usecases/
+└── presentation/
+    ├── providers/
+    ├── views/
+    └── widgets/
+```
+
+## Dependency boundaries
+
+- UI widgets watch presentation providers only.
+- Presentation providers call domain use cases (preferred in clean architecture).
+- Data layer implementations are injected behind domain interfaces.
+- Do not import concrete database/network clients into UI providers.
+
+## Provider roles
+
+- Read providers: load and expose queryable state.
+- Mutation providers/notifiers: execute commands (create/update/delete).
+- Session/auth/router providers: global lifecycle, typically keepAlive.
+
+## Parameter rules for families
+
+Use parameters with stable equality:
+- primitives/enums,
+- immutable value objects (Freezed/equatable).
+
+Avoid:
+- mutable `List/Map` params,
+- anonymous objects without stable `==/hashCode`.
+
+## Minimal skeleton
+
+```dart
+part 'orders_controller.g.dart';
+
+@riverpod
+class OrdersController extends _$OrdersController {
+  @override
+  FutureOr<OrdersState> build({required OrdersQuery query}) async {
+    final useCase = ref.watch(getOrdersUseCaseProvider);
+    final items = await useCase(query);
+    return OrdersState(items: items);
+  }
+
+  Future<void> refresh() async {
+    ref.invalidateSelf();
+    await future;
+  }
+}
+```
+
+## When to split providers further
+
+Split when:
+- one provider manages unrelated concerns,
+- write paths exceed simple command handlers,
+- separate lifecycles are needed (long-lived global + short-lived page state).

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/riverpod-3/references/refresh-cache-paging.md

@@ -0,0 +1,106 @@
+# Refresh + paging + caching patterns (Riverpod 3)
+
+## 1) Refresh
+
+Controller pattern:
+
+```dart
+Future<void> refresh() async {
+  ref.invalidateSelf();
+  await future;
+}
+```
+
+UI pattern:
+
+```dart
+RefreshIndicator(
+  onRefresh: () => ref.read(itemsControllerProvider(query: query).notifier).refresh(),
+  child: ItemsList(items: items),
+)
+```
+
+Notes:
+- `invalidateSelf` marks provider stale and recomputes on next read.
+- Use `ref.refresh(provider)` when you need an immediate fresh value in imperative code.
+
+## 2) Paging
+
+Represent load-more state separately from initial AsyncValue:
+
+```dart
+@freezed
+class PagedState<T> with _$PagedState<T> {
+  const factory PagedState({
+    @Default(<T>[]) List<T> items,
+    String? nextCursor,
+    @Default(true) bool hasMore,
+    @Default(false) bool isLoadingMore,
+    String? loadMoreError,
+  }) = _PagedState<T>;
+}
+```
+
+Rules:
+- guard parallel `loadMore` calls,
+- append immutably,
+- reset cursor/items on refresh.
+
+## 3) Caching strategy
+
+### In-memory (provider cache)
+- Provider values are cached while alive.
+- Families cache by parameter instance.
+- Default auto-dispose is safer for high-cardinality families.
+
+### Persistent (storage-agnostic)
+Cache belongs in repository/data layer, not widget layer.
+Storage can be Drift/SQLite/Isar/Hive/etc.
+
+Recommended read flow:
+1. return fresh local cache if available,
+2. fetch remote when needed,
+3. persist new data,
+4. emit updated state.
+
+## 4) KeepAlive guidance
+
+### Static keepAlive
+Use annotation-level keepAlive for truly app-wide state:
+
+```dart
+@Riverpod(keepAlive: true)
+SessionState sessionState(Ref ref) => const SessionState.unknown();
+```
+
+### Fine-grained keepAlive on auto-disposed providers
+Use `ref.keepAlive()` when you only want to keep successful/fresh results:
+
+```dart
+@riverpod
+Future<List<Item>> cachedItems(Ref ref) async {
+  final link = ref.keepAlive();
+
+  // Example TTL: re-enable auto-dispose after 5 minutes
+  final timer = Timer(const Duration(minutes: 5), link.close);
+  ref.onDispose(timer.cancel);
+
+  return ref.read(itemsRepositoryProvider).fetch();
+}
+```
+
+Use keepAlive for:
+- low-cardinality app-level state,
+- expensive state reused across routes.
+
+Avoid keepAlive for:
+- parameterized search/list/detail families,
+- route-scoped temporary state.
+
+## 5) Stale-while-revalidate UX
+
+Pattern:
+- show cached data immediately,
+- show subtle loading indicator during background refresh,
+- update list when fresh data arrives,
+- keep explicit retry path on error.

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/riverpod-3/references/testing.md

@@ -0,0 +1,159 @@
+# Riverpod 3 testing
+
+This guide focuses on provider/controller tests and widget tests for Riverpod 3 + codegen.
+
+## Core idea
+
+- In tests, control dependencies via `ProviderContainer(overrides: ...)` or `ProviderScope(overrides: ...)`.
+- Never hit real network/db in unit tests.
+- Prefer fakes over heavy mocks when practical.
+
+## 1) Unit test a simple provider
+
+```dart
+test('counter defaults to 0', () {
+  final container = ProviderContainer();
+  addTearDown(container.dispose);
+
+  expect(container.read(counterProvider), 0);
+});
+```
+
+## 2) Unit test an AsyncNotifier (happy path)
+
+```dart
+class FakeOrdersRepository implements OrdersRepository {
+  @override
+  Future<List<Order>> getOrders() async => [Order(id: '1')];
+}
+
+test('OrdersController loads data', () async {
+  final container = ProviderContainer(
+    overrides: [
+      ordersRepositoryProvider.overrideWithValue(FakeOrdersRepository()),
+    ],
+  );
+  addTearDown(container.dispose);
+
+  final state = await container.read(ordersControllerProvider.future);
+  expect(state.items, isNotEmpty);
+});
+```
+
+## 3) Unit test error path
+
+```dart
+class FakeFailOrdersRepository implements OrdersRepository {
+  @override
+  Future<List<Order>> getOrders() async => throw Exception('network');
+}
+
+test('OrdersController exposes error on failure', () async {
+  final container = ProviderContainer(
+    overrides: [
+      ordersRepositoryProvider.overrideWithValue(FakeFailOrdersRepository()),
+    ],
+  );
+  addTearDown(container.dispose);
+
+  expect(
+    () => container.read(ordersControllerProvider.future),
+    throwsException,
+  );
+});
+```
+
+## 4) Unit test `refresh()`
+
+```dart
+class CountingOrdersRepository implements OrdersRepository {
+  int calls = 0;
+
+  @override
+  Future<List<Order>> getOrders() async {
+    calls++;
+    return [Order(id: '$calls')];
+  }
+}
+
+test('refresh re-runs build()', () async {
+  final repo = CountingOrdersRepository();
+  final container = ProviderContainer(
+    overrides: [ordersRepositoryProvider.overrideWithValue(repo)],
+  );
+  addTearDown(container.dispose);
+
+  final first = await container.read(ordersControllerProvider.future);
+  expect(first.items.single.id, '1');
+  expect(repo.calls, 1);
+
+  await container.read(ordersControllerProvider.notifier).refresh();
+
+  final second = await container.read(ordersControllerProvider.future);
+  expect(second.items.single.id, '2');
+  expect(repo.calls, 2);
+});
+```
+
+## 5) Family parameter stability test
+
+```dart
+test('family parameter equality reuses provider instance', () {
+  final container = ProviderContainer();
+  addTearDown(container.dispose);
+
+  final q1 = OrdersQuery(status: 'open', page: 1);
+  final q2 = OrdersQuery(status: 'open', page: 1);
+
+  final a = container.read(ordersListProvider(q1));
+  final b = container.read(ordersListProvider(q2));
+
+  expect(identical(a, b), isTrue);
+});
+```
+
+## 6) Paging controller test
+
+```dart
+class FakePagedRepo implements OrdersRepository {
+  int page = 0;
+
+  @override
+  Future<OrderPage> fetchPage({String? cursor}) async {
+    page++;
+    if (page == 1) return OrderPage(items: [Order(id: 'a')], nextCursor: 'c2');
+    if (page == 2) return OrderPage(items: [Order(id: 'b')], nextCursor: null);
+    return OrderPage(items: const [], nextCursor: null);
+  }
+}
+```
+
+Validate:
+- first page loads,
+- `loadMore` appends immutably,
+- `hasMore` flips to false when no cursor.
+
+## 7) Widget test (loading -> data)
+
+```dart
+testWidgets('shows list when data loaded', (tester) async {
+  await tester.pumpWidget(
+    ProviderScope(
+      overrides: [
+        ordersRepositoryProvider.overrideWithValue(FakeOrdersRepository()),
+      ],
+      child: const MaterialApp(home: OrdersView()),
+    ),
+  );
+
+  await tester.pump();
+  expect(find.text('1'), findsOneWidget);
+});
+```
+
+## 8) Loop regression test
+
+If a screen previously had rebuild loops:
+- pump widget,
+- call `pumpAndSettle` with timeout,
+- assert it settles.