triples-agentic 2.4.0

package/src/knowledge/mobile/android/android-platform.md

@@ -0,0 +1,60 @@
+---
+name: android-platform
+description: Android Material Design 3, local storage, background work, testing, and Play Store requirements
+---
+
+# Android — Platform & Distribution
+
+## Material Design 3
+
+- Use MD3 components (`Button`, `Card`, `TextField`, `TopAppBar`, `NavigationBar`)
+- Color roles: `primary`, `secondary`, `tertiary`, `error`, `surface`, `background`
+- Dynamic color (Material You): supported on Android 12+ with `dynamicColorScheme()`
+- Always support dark mode from day one: `isSystemInDarkTheme()`
+- Use `dp` for all dimensions, never hardcode pixel values
+
+## Local Storage
+
+| Use case | Solution |
+|---|---|
+| Structured relational data | Room |
+| Simple settings (non-sensitive) | DataStore (Preferences) |
+| Sensitive data (tokens) | EncryptedSharedPreferences |
+| Complex typed settings | DataStore (Proto) |
+| Binary files, documents | FileManager |
+
+Never use SharedPreferences for sensitive data.
+
+## Background Work
+
+- **WorkManager** — guaranteed background tasks (syncs, uploads, notifications scheduling)
+- **Coroutines + Dispatchers.IO** — async I/O on demand within the app lifecycle
+- Never do network/disk I/O on `Dispatchers.Main` (UI thread)
+
+```kotlin
+viewModelScope.launch(Dispatchers.IO) {
+    val result = repository.fetchData()
+    withContext(Dispatchers.Main) { _uiState.update { it.copy(data = result) } }
+}
+```
+
+## Testing
+
+- **Unit tests**: ViewModel + use cases — JUnit 5, Turbine (Flow testing), Mockk
+- **UI tests**: Composable testing with `ComposeTestRule`
+- **Integration tests**: Room in-memory database; Retrofit MockWebServer
+
+## Performance
+
+- Profile with Android Studio Profiler (CPU, Memory, Network tabs)
+- Use `LazyColumn` / `LazyRow` for large lists — never `Column` + scroll for dynamic data
+- Avoid object allocation in Composable functions (causes GC pressure)
+- Minimize recompositions: stable types, `remember`, `derivedStateOf`
+
+## Play Store Requirements
+
+- Target latest stable `targetSdkVersion` (within one year of release)
+- 64-bit support required
+- Privacy declarations for all permissions and data collected
+- App Bundle (`.aab`) format required for new apps
+- Content rating questionnaire must be completed

package/src/knowledge/mobile/android/kotlin-concurrency.md

@@ -0,0 +1,75 @@
+---
+name: kotlin-concurrency
+description: Kotlin coroutines, Flow, scope functions, and async/await patterns for Android development
+---
+
+# Kotlin — Coroutines & Concurrency
+
+## Coroutines Basics
+
+```kotlin
+// Launch fire-and-forget
+viewModelScope.launch {
+    val result = repository.fetchUser(id)  // suspend function
+    _uiState.update { it.copy(user = result) }
+}
+
+// Async/await for parallel execution
+val (user, orders) = awaitAll(
+    async { repository.fetchUser(id) },
+    async { repository.fetchOrders(id) }
+)
+```
+
+## Flow
+
+```kotlin
+// Cold stream — executes per collector
+val userFlow: Flow<User> = repository.observeUser(id)
+
+viewModelScope.launch {
+    userFlow
+        .map { user -> user.toUiModel() }
+        .catch { e -> handleError(e) }
+        .collect { uiModel -> _uiState.update { it.copy(user = uiModel) } }
+}
+
+// StateFlow — hot, always has a value
+private val _uiState = MutableStateFlow(LoginUiState())
+val uiState: StateFlow<LoginUiState> = _uiState.asStateFlow()
+```
+
+## Dispatchers
+
+| Dispatcher | Use for |
+|---|---|
+| `Dispatchers.Main` | UI updates, collect StateFlow |
+| `Dispatchers.IO` | Network, file, database operations |
+| `Dispatchers.Default` | CPU-intensive work (parsing, sorting large lists) |
+
+Never block the Main dispatcher.
+
+## Scope Functions
+
+| Function | Context | Returns | Use when |
+|---|---|---|---|
+| `let` | `it` | Lambda result | Null checks, transforming result |
+| `run` | `this` | Lambda result | Object configuration + compute |
+| `with` | `this` | Lambda result | Multiple calls on same object |
+| `apply` | `this` | Context object | Object initialization |
+| `also` | `it` | Context object | Side effects (logging) |
+
+## Error Handling in Coroutines
+
+```kotlin
+viewModelScope.launch {
+    try {
+        val result = repository.fetchData()
+        _uiState.update { it.copy(data = result, error = null) }
+    } catch (e: HttpException) {
+        _uiState.update { it.copy(error = "Network error: ${e.message}") }
+    } catch (e: CancellationException) {
+        throw e  // always rethrow CancellationException
+    }
+}
+```

package/src/knowledge/mobile/android/kotlin-core.md

@@ -0,0 +1,88 @@
+---
+name: kotlin-core
+description: Kotlin null safety, data classes, sealed classes, extension functions, and idiomatic collection operations
+---
+
+# Kotlin — Core Language
+
+## Null Safety
+
+```kotlin
+// Nullable type explicitly declared
+var name: String? = null
+
+// Safe call — returns null instead of NPE
+val length = name?.length
+
+// Elvis operator — provide fallback
+val displayName = name ?: "Anonymous"
+
+// Non-null assertion — only when truly certain
+val definiteLength = name!!.length  // avoid unless necessary
+
+// Let for null-checking scope
+name?.let { nonNullName ->
+    println("Name: $nonNullName")
+}
+```
+
+## Data Classes
+
+```kotlin
+data class User(
+    val id: String,
+    val email: String,
+    val name: String,
+)
+// Auto-generates: equals(), hashCode(), toString(), copy()
+val updated = user.copy(name = "New Name")
+```
+
+## Sealed Classes & When
+
+```kotlin
+sealed class Result<out T> {
+    data class Success<T>(val data: T) : Result<T>()
+    data class Error(val exception: Exception) : Result<Nothing>()
+    object Loading : Result<Nothing>()
+}
+
+// Exhaustive when — no else needed
+when (result) {
+    is Result.Success -> showData(result.data)
+    is Result.Error   -> showError(result.exception)
+    is Result.Loading -> showSpinner()
+}
+```
+
+## Extension Functions
+
+```kotlin
+fun String.toTitleCase(): String =
+    split(" ").joinToString(" ") { it.replaceFirstChar { c -> c.uppercase() } }
+
+// Usage: "hello world".toTitleCase() → "Hello World"
+```
+
+## Collections
+
+```kotlin
+val names: List<String> = listOf("Alice", "Bob")   // immutable
+val mutableNames = mutableListOf("Alice")           // mutable
+
+// Functional operations
+val activeAdultUsers = users
+    .filter { it.isActive && it.age >= 18 }
+    .map { UserSummary(it.id, it.name) }
+    .sortedBy { it.name }
+    .take(10)
+```
+
+## Idiomatic Kotlin Rules
+
+- Prefer `val` over `var` — immutability by default
+- Prefer `data class` over plain class for DTOs and models
+- Use `object` for singletons
+- Named arguments for functions with 3+ parameters
+- `when` over chained `if/else if`
+- String templates over concatenation: `"Hello, $name!"` not `"Hello, " + name + "!"`

package/src/knowledge/mobile/flutter/dart-async.md

@@ -0,0 +1,93 @@
+---
+name: dart-async
+description: Dart async/await, Future, Stream, error handling, mixins, and extension methods
+---
+
+# Dart — Async, Streams & Advanced Patterns
+
+## Future — One-time async value
+
+```dart
+Future<User> fetchUser(String id) async {
+  final response = await http.get(Uri.parse('/users/$id'));
+  return User.fromJson(jsonDecode(response.body) as Map<String, dynamic>);
+}
+
+// Error handling
+try {
+  final user = await fetchUser(id);
+  print(user.name);
+} on SocketException {
+  throw NetworkException('No internet connection');
+} catch (e) {
+  rethrow;  // preserve stack trace
+}
+```
+
+## Stream — Sequence of async values
+
+```dart
+Stream<List<Message>> watchMessages(String roomId) {
+  return firestore
+      .collection('messages')
+      .where('roomId', isEqualTo: roomId)
+      .snapshots()
+      .map((snap) => snap.docs.map(Message.fromDoc).toList());
+}
+
+// Consuming a stream
+await for (final messages in watchMessages(roomId)) {
+  updateUI(messages);
+}
+```
+
+## FutureBuilder & StreamBuilder (Flutter widgets)
+
+```dart
+FutureBuilder<User>(
+  future: fetchUser(userId),
+  builder: (context, snapshot) {
+    if (snapshot.connectionState == ConnectionState.waiting) {
+      return const CircularProgressIndicator();
+    }
+    if (snapshot.hasError) return Text('Error: ${snapshot.error}');
+    return Text(snapshot.data!.name);
+  },
+)
+```
+
+Prefer Riverpod's `AsyncNotifier` over `FutureBuilder` in new code — it handles caching and state more cleanly.
+
+## Mixins
+
+```dart
+mixin Serializable {
+  Map<String, dynamic> toJson();
+  String toJsonString() => jsonEncode(toJson());
+}
+
+class User with Serializable {
+  final String name;
+  User(this.name);
+  @override
+  Map<String, dynamic> toJson() => {'name': name};
+}
+```
+
+## Extension Methods
+
+```dart
+extension StringExtension on String {
+  String get titleCase =>
+      split(' ').map((w) => w[0].toUpperCase() + w.substring(1)).join(' ');
+}
+
+// Usage
+'hello world'.titleCase  // 'Hello World'
+
+extension ListExtension<T> on List<T> {
+  T? firstWhereOrNull(bool Function(T) test) {
+    try { return firstWhere(test); } catch (_) { return null; }
+  }
+}
+```

package/src/knowledge/mobile/flutter/dart-core.md

@@ -0,0 +1,97 @@
+---
+name: dart-core
+description: Dart null safety, core types, classes and constructors, enums, and idiomatic collection operations
+---
+
+# Dart — Core Language
+
+## Null Safety
+
+```dart
+String name = 'Alice';   // Non-nullable
+String? nickname;         // Nullable
+
+// Null-aware operators
+String display = nickname ?? 'No nickname';   // fallback
+int? length = nickname?.length;               // safe access
+nickname ??= 'Default';                       // assign if null
+String definite = nickname!;                  // assert non-null (throws if null)
+```
+
+## Core Types
+
+```dart
+int age = 25;
+double price = 9.99;
+bool isActive = true;
+String name = 'Alice';
+
+List<String> tags = ['flutter', 'dart'];   // immutable
+Set<int> ids = {1, 2, 3};
+Map<String, dynamic> data = {'name': 'Alice', 'age': 25};
+
+// Const — compile-time constants
+const pi = 3.14159;
+const colors = ['red', 'green', 'blue'];
+```
+
+## Classes & Constructors
+
+```dart
+class User {
+  final String id;
+  final String email;
+  String name;
+
+  // Named constructor with initializer list
+  User({required this.id, required this.email, required this.name});
+
+  // Named constructor
+  User.anonymous() : id = '', email = '', name = 'Guest';
+
+  // Factory constructor
+  factory User.fromJson(Map<String, dynamic> json) {
+    return User(id: json['id'], email: json['email'], name: json['name']);
+  }
+
+  // copyWith pattern
+  User copyWith({String? name}) =>
+      User(id: id, email: email, name: name ?? this.name);
+}
+```
+
+## Enhanced Enums (Dart 2.17+)
+
+```dart
+enum PaymentStatus {
+  pending('Pending', Colors.orange),
+  completed('Completed', Colors.green),
+  failed('Failed', Colors.red);
+
+  const PaymentStatus(this.label, this.color);
+  final String label;
+  final Color color;
+}
+
+// Usage
+PaymentStatus.completed.label  // 'Completed'
+PaymentStatus.completed.color  // Colors.green
+```
+
+## Functional Collections
+
+```dart
+final activeAdults = users
+    .where((u) => u.isActive && u.age >= 18)
+    .map((u) => UserSummary(u.id, u.name))
+    .toList();
+
+final total = orders.fold(0.0, (sum, order) => sum + order.total);
+```
+
+## Dart Style
+
+- `lowerCamelCase` for variables/functions, `UpperCamelCase` for classes
+- Prefer `final` over `var`; `const` over `final` where possible
+- Format with `dart format` (built-in, no Prettier needed)
+- Lint with `flutter_lints` or `very_good_analysis`

package/src/knowledge/mobile/flutter/flutter-architecture.md

@@ -0,0 +1,88 @@
+---
+name: flutter-architecture
+description: Flutter architecture with Riverpod, widget composition, GoRouter navigation, and state management patterns
+---
+
+# Flutter Architecture
+
+## Architecture: Riverpod + Clean Layers
+
+```
+UI Layer (Widgets)
+    ↕ ref.watch / Consumer
+Riverpod Provider (state + business logic)
+    ↕ Repository interface
+Data Layer (API, Local DB, Cache)
+```
+
+## Widget Philosophy
+
+Everything in Flutter is a widget. Widgets are immutable — they rebuild cheaply.
+
+```dart
+// Stateless: no mutable state
+class UserCard extends StatelessWidget {
+  const UserCard({super.key, required this.user});
+  final User user;
+
+  @override
+  Widget build(BuildContext context) => Card(child: Text(user.name));
+}
+```
+
+## Riverpod — State Management
+
+```dart
+// AsyncNotifier for complex state
+class OrdersNotifier extends AsyncNotifier<List<Order>> {
+  @override
+  Future<List<Order>> build() =>
+      ref.read(orderRepoProvider).fetchOrders();
+
+  Future<void> placeOrder(OrderRequest request) async {
+    state = const AsyncLoading();
+    state = await AsyncValue.guard(
+      () => ref.read(orderRepoProvider).place(request),
+    );
+  }
+}
+
+final ordersProvider =
+    AsyncNotifierProvider<OrdersNotifier, List<Order>>(OrdersNotifier.new);
+
+// Simple FutureProvider
+final userProvider = FutureProvider.family<User, String>(
+  (ref, userId) => ref.read(userRepoProvider).fetchUser(userId),
+);
+```
+
+## Navigation — GoRouter
+
+```dart
+final router = GoRouter(
+  routes: [
+    GoRoute(path: '/', builder: (_, __) => const HomeScreen()),
+    GoRoute(
+      path: '/user/:id',
+      builder: (ctx, state) =>
+          UserScreen(userId: state.pathParameters['id']!),
+    ),
+  ],
+);
+```
+
+## Networking — Dio
+
+```dart
+final dio = Dio(BaseOptions(
+  baseUrl: 'https://api.example.com',
+  headers: {'Content-Type': 'application/json'},
+));
+
+dio.interceptors.add(AuthInterceptor(tokenService));
+
+Future<User> fetchUser(String id) async {
+  final response = await dio.get('/users/$id');
+  return User.fromJson(response.data as Map<String, dynamic>);
+}
+```

package/src/knowledge/mobile/flutter/flutter-platform.md

@@ -0,0 +1,79 @@
+---
+name: flutter-platform
+description: Flutter Material 3, local storage, platform channels, performance, testing, and publishing for Android and iOS
+---
+
+# Flutter — Platform & Distribution
+
+## Material 3 Theming
+
+```dart
+MaterialApp(
+  theme: ThemeData(
+    useMaterial3: true,
+    colorScheme: ColorScheme.fromSeed(seedColor: Colors.indigo),
+  ),
+  darkTheme: ThemeData(
+    useMaterial3: true,
+    colorScheme: ColorScheme.fromSeed(
+      seedColor: Colors.indigo,
+      brightness: Brightness.dark,
+    ),
+  ),
+)
+```
+
+## Local Storage
+
+| Use case | Package |
+|---|---|
+| Structured data | Hive or Isar |
+| Relational data | drift (SQLite) |
+| Simple key-value | shared_preferences |
+| Sensitive data (tokens) | flutter_secure_storage |
+| Files | path_provider |
+
+Never store credentials in SharedPreferences.
+
+## Platform Channels (when Flutter doesn't cover a native feature)
+
+```dart
+const platform = MethodChannel('com.example.app/biometrics');
+final bool result = await platform.invokeMethod<bool>('authenticate') ?? false;
+```
+
+Prefer existing pub.dev packages before writing platform channels. Check:
+1. Pub points (quality score)
+2. Last published date
+3. Platform support (Android/iOS/Web checkboxes)
+
+## Performance
+
+- `const` constructor everywhere possible — prevents unnecessary rebuilds
+- `ListView.builder` / `GridView.builder` for long lists (lazy rendering)
+- Avoid `setState` high in the widget tree — keep state low
+- Profile with Flutter DevTools (Timeline, Widget Rebuilds inspector)
+- `RepaintBoundary` around complex widgets that change independently
+
+## Testing
+
+```dart
+// Widget test
+testWidgets('shows user name', (tester) async {
+  await tester.pumpWidget(const MaterialApp(home: UserCard(user: mockUser)));
+  expect(find.text(mockUser.name), findsOneWidget);
+});
+
+// Unit test
+test('formats currency correctly', () {
+  expect(formatCurrency(1234.56), '\$1,234.56');
+});
+```
+
+## Publishing
+
+- **Android**: `flutter build appbundle --release` → `.aab`
+- **iOS**: `flutter build ios --release` → archive via Xcode
+- Version: `version: 1.0.0+1` in `pubspec.yaml` (semantic version + build number)
+- Icons: `flutter_launcher_icons` package
+- Splash screen: `flutter_native_splash` package

package/src/knowledge/mobile/ios/ios-architecture.md

@@ -0,0 +1,88 @@
+---
+name: ios-architecture
+description: iOS MVVM architecture, SwiftUI view design, state management (@Observable, @ObservableObject), and networking
+---
+
+# iOS Architecture
+
+## Architecture Pattern: MVVM
+
+```
+View (SwiftUI) — observes ViewModel state
+    ↕ @Published / @Observable
+ViewModel — business logic, state management
+    ↕ async/await
+Repository / Service — data access, network calls
+```
+
+## SwiftUI View Design
+
+- Views are value types (structs) — cheap to recreate
+- Extract subviews into separate structs when body exceeds ~30 lines
+- `@State` for local ephemeral state only
+- `@StateObject` / `@ObservedObject` for ViewModels
+- `@EnvironmentObject` for app-wide state (theme, auth context)
+
+```swift
+// View observes ViewModel — correct pattern
+struct LoginView: View {
+    @StateObject private var viewModel = LoginViewModel()
+
+    var body: some View {
+        VStack {
+            TextField("Email", text: $viewModel.email)
+            Button("Log in") { viewModel.login() }
+        }
+    }
+}
+```
+
+## State Management
+
+```swift
+// @Observable macro (iOS 17+, Swift 5.9)
+@Observable
+class LoginViewModel {
+    var email = ""
+    var isLoading = false
+
+    func login() async {
+        isLoading = true
+        defer { isLoading = false }
+        // network call
+    }
+}
+
+// @ObservableObject (iOS 13+ compatibility)
+class LoginViewModel: ObservableObject {
+    @Published var email = ""
+    @Published var isLoading = false
+}
+```
+
+## Networking — async/await
+
+```swift
+func fetchUser(id: String) async throws -> User {
+    let url = URL(string: "https://api.example.com/users/\(id)")!
+    let (data, response) = try await URLSession.shared.data(from: url)
+    guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
+        throw APIError.invalidResponse
+    }
+    return try JSONDecoder().decode(User.self, from: data)
+}
+```
+
+## Navigation — NavigationStack (iOS 16+)
+
+```swift
+NavigationStack(path: $navigationPath) {
+    HomeView()
+        .navigationDestination(for: UserRoute.self) { route in
+            switch route {
+            case .profile(let id): UserProfileView(userId: id)
+            case .settings: SettingsView()
+            }
+        }
+}
+```