@cubis/foundry 0.3.10

package/Ai Agent Workflow/workflows/agent-environment-setup/platforms/cursor/skills/riverpod-3/steering/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/steering/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/steering/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/steering/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/steering/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.

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

@@ -0,0 +1,17 @@
+```dart
+// templates/cache_policy.dart.tmpl
+//
+// Minimal TTL helper you can use in repositories.
+
+class CachePolicy {
+  const CachePolicy({
+    required this.ttl,
+    this.allowStaleWhileRevalidate = true,
+  });
+
+  final Duration ttl;
+  final bool allowStaleWhileRevalidate;
+
+  bool isFresh(DateTime cachedAt, DateTime now) => now.difference(cachedAt) <= ttl;
+}
+```

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

@@ -0,0 +1,54 @@
+# Paged Controller Template
+
+Infinite scroll controller with clean initial/refresh/load-more separation.
+
+## Usage
+
+1. Copy `paged_controller.dart.tmpl` to your feature root (e.g., `features/<feature>/`)
+2. Rename file and update part directives
+3. Replace `Item` with your entity type
+4. Replace `itemRepositoryProvider` with your repository provider
+5. Run `flutter pub run build_runner build`
+
+## Key Features
+
+- **Initial load**: `build()` fetches first page
+- **Refresh**: `refresh()` invalidates and re-fetches from scratch
+- **Load more**: `loadNextPage()` appends without losing current items
+- **Error handling**: `loadMoreError` captures pagination errors separately
+
+## State Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `items` | `List<Item>` | All loaded items (immutable) |
+| `nextCursor` | `String?` | Cursor for next page |
+| `hasMore` | `bool` | Whether more pages exist |
+| `isLoadingMore` | `bool` | Loading indicator for pagination |
+| `loadMoreError` | `String?` | Error from load more (not initial) |
+
+## View Integration
+
+```dart
+NotificationListener<ScrollNotification>(
+  onNotification: (notification) {
+    if (notification is ScrollEndNotification &&
+        notification.metrics.extentAfter < 200 &&
+        state.hasMore && !state.isLoadingMore) {
+      ref.read(provider.notifier).loadNextPage();
+    }
+    return false;
+  },
+  child: RefreshIndicator(
+    onRefresh: () => ref.read(provider.notifier).refresh(),
+    child: ListView.builder(...),
+  ),
+)
+```
+
+## Notes
+
+- Uses `ref.watch` in `build()` for repository (establishes dependency)
+- Uses `ref.read` in `loadNextPage()` (no rebuild needed)
+- Build params accessible via `this.orgId` in methods
+- State is always immutable (`List.unmodifiable`)

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

@@ -0,0 +1,30 @@
+```dart
+// templates/riverpod_controller_test.tmpl
+//
+// Copy into: test/unit/<feature>/<feature>_controller_test.dart
+// Adjust providers + fakes.
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+void main() {
+  test('controller loads data', () async {
+    final container = ProviderContainer(
+      overrides: [
+        // repositoryProvider.overrideWithValue(FakeRepo()),
+      ],
+    );
+    addTearDown(container.dispose);
+
+    // final state = await container.read(controllerProvider(args...).future);
+    // expect(state, ...);
+  });
+
+  test('refresh re-runs build', () async {
+    final container = ProviderContainer();
+    addTearDown(container.dispose);
+
+    // await container.read(controllerProvider(args...).notifier).refresh();
+  });
+}
+```