reis-mobile 0.3.5

package/skills/flutter-managing-state/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: flutter-managing-state
+description: Manages application and ephemeral state in a Flutter app. Use when sharing data between widgets or handling complex UI state transitions.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Thu, 12 Mar 2026 22:18:06 GMT
+intents: [architecture]
+stacks: [flutter]
+source: https://github.com/flutter/skills
+license: BSD-3-Clause
+---
+# Managing State in Flutter
+
+## Contents
+- [Core Concepts](#core-concepts)
+- [Architecture and Data Flow](#architecture-and-data-flow)
+- [Workflow: Selecting a State Management Approach](#workflow-selecting-a-state-management-approach)
+- [Workflow: Implementing MVVM with Provider](#workflow-implementing-mvvm-with-provider)
+- [Examples](#examples)
+
+## Core Concepts
+
+Flutter's UI is declarative; it is built to reflect the current state of the app (`UI = f(state)`). When state changes, trigger a rebuild of the UI that depends on that state. 
+
+Distinguish between two primary types of state to determine your management strategy:
+*   **Ephemeral State (Local State):** State contained neatly within a single widget (e.g., current page in a `PageView`, current selected tab, animation progress). Manage this using a `StatefulWidget` and `setState()`.
+*   **App State (Shared State):** State shared across multiple parts of the app and maintained between user sessions (e.g., user preferences, login info, shopping cart contents). Manage this using advanced approaches like `InheritedWidget`, the `provider` package, and the MVVM architecture.
+
+## Architecture and Data Flow
+
+Implement the **Model-View-ViewModel (MVVM)** design pattern combined with **Unidirectional Data Flow (UDF)** for scalable app state management.
+
+*   **Unidirectional Data Flow (UDF):** Enforce a strict flow where state flows *down* from the data layer, through the logic layer, to the UI layer. Events from user interactions flow *up* from the UI layer, to the logic layer, to the data layer.
+*   **Single Source of Truth (SSOT):** Ensure data changes always happen in the data layer (Repositories). The SSOT class must be the only class capable of modifying its respective data.
+*   **Model (Data Layer):** Handle low-level tasks like HTTP requests, data caching, and system resources using Repository classes.
+*   **ViewModel (Logic Layer):** Manage the UI state. Convert app data from the Model into UI State. Extend `ChangeNotifier` and call `notifyListeners()` to trigger UI rebuilds when data changes.
+*   **View (UI Layer):** Display the state provided by the ViewModel. Keep views lean; they should contain minimal logic (only routing, animations, or simple UI conditionals).
+
+## Workflow: Selecting a State Management Approach
+
+Evaluate the scope of the state to determine the correct implementation strategy.
+
+*   **If managing Ephemeral State (single widget scope):**
+    1. Subclass `StatefulWidget` and `State`.
+    2. Store mutable state as private fields within the `State` class.
+    3. Mutate state exclusively inside a `setState()` callback to mark the widget as dirty and schedule a rebuild.
+*   **If managing App State (shared across widgets):**
+    1. Implement the MVVM pattern.
+    2. Use the `provider` package (a wrapper around `InheritedWidget`) to inject state into the widget tree.
+    3. Use `ChangeNotifier` to emit state updates.
+
+## Workflow: Implementing MVVM with Provider
+
+Follow this sequential workflow to implement app-level state management using MVVM and `provider`.
+
+**Task Progress:**
+- [ ] 1. Define the Model (Repository).
+- [ ] 2. Create the ViewModel (`ChangeNotifier`).
+- [ ] 3. Inject the ViewModel into the Widget Tree.
+- [ ] 4. Consume the State in the View.
+- [ ] 5. Validate the implementation.
+
+### 1. Define the Model (Repository)
+Create a repository class to act as the Single Source of Truth (SSOT) for the specific data domain. Handle all external API calls or database queries here.
+
+### 2. Create the ViewModel (`ChangeNotifier`)
+Create a ViewModel class that extends `ChangeNotifier`.
+*   Pass the Repository into the ViewModel via dependency injection.
+*   Define properties for the UI state (e.g., `isLoading`, `data`, `errorMessage`).
+*   Implement methods to handle UI events. Inside these methods, mutate the state and call `notifyListeners()` to trigger UI rebuilds.
+
+### 3. Inject the ViewModel into the Widget Tree
+Use `ChangeNotifierProvider` from the `provider` package to provide the ViewModel to the widget subtree that requires it. Place the provider as low in the widget tree as possible to avoid polluting the scope.
+
+### 4. Consume the State in the View
+Access the ViewModel in your `StatelessWidget` or `StatefulWidget`.
+*   Use `Consumer<MyViewModel>` to rebuild specific parts of the UI when `notifyListeners()` is called.
+*   Use `context.read<MyViewModel>()` (or `Provider.of<MyViewModel>(context, listen: false)`) inside event handlers (like `onPressed`) to call ViewModel methods without triggering a rebuild of the calling widget.
+
+### 5. Validate the implementation
+Run the following feedback loop to ensure data flows correctly:
+1. Trigger a user action in the View.
+2. Verify the ViewModel receives the event and calls the Repository.
+3. Verify the Repository updates the SSOT and returns data.
+4. Verify the ViewModel updates its state and calls `notifyListeners()`.
+5. Verify the View rebuilds with the new state.
+*Run validator -> review errors -> fix missing `notifyListeners()` calls or incorrect `Provider` scopes.*
+
+## Examples
+
+### Ephemeral State Implementation (`setState`)
+
+Use this pattern strictly for local, UI-only state.
+
+```dart
+class EphemeralCounter extends StatefulWidget {
+  const EphemeralCounter({super.key});
+
+  @override
+  State<EphemeralCounter> createState() => _EphemeralCounterState();
+}
+
+class _EphemeralCounterState extends State<EphemeralCounter> {
+  int _counter = 0; // Local state
+
+  void _increment() {
+    setState(() {
+      _counter++; // Mutate state and schedule rebuild
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return ElevatedButton(
+      onPressed: _increment,
+      child: Text('Count: $_counter'),
+    );
+  }
+}
+```
+
+### App State Implementation (MVVM + Provider)
+
+Use this pattern for shared data and complex business logic.
+
+```dart
+// 1. Model (Repository)
+class CartRepository {
+  Future<void> saveItemToCart(String item) async {
+    // Simulate network/database call
+    await Future.delayed(const Duration(milliseconds: 500));
+  }
+}
+
+// 2. ViewModel (ChangeNotifier)
+class CartViewModel extends ChangeNotifier {
+  final CartRepository repository;
+  
+  CartViewModel({required this.repository});
+
+  final List<String> _items = [];
+  bool isLoading = false;
+  String? errorMessage;
+
+  List<String> get items => List.unmodifiable(_items);
+
+  Future<void> addItem(String item) async {
+    isLoading = true;
+    errorMessage = null;
+    notifyListeners(); // Trigger loading UI
+
+    try {
+      await repository.saveItemToCart(item);
+      _items.add(item);
+    } catch (e) {
+      errorMessage = 'Failed to add item';
+    } finally {
+      isLoading = false;
+      notifyListeners(); // Trigger success/error UI
+    }
+  }
+}
+
+// 3. Injection & 4. View (UI)
+class CartApp extends StatelessWidget {
+  const CartApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    // Inject ViewModel
+    return ChangeNotifierProvider(
+      create: (_) => CartViewModel(repository: CartRepository()),
+      child: const CartScreen(),
+    );
+  }
+}
+
+class CartScreen extends StatelessWidget {
+  const CartScreen({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Consumer<CartViewModel>(
+        builder: (context, viewModel, child) {
+          if (viewModel.isLoading) {
+            return const CircularProgressIndicator();
+          }
+          if (viewModel.errorMessage != null) {
+            return Text(viewModel.errorMessage!);
+          }
+          return ListView.builder(
+            itemCount: viewModel.items.length,
+            itemBuilder: (_, index) => Text(viewModel.items[index]),
+          );
+        },
+      ),
+      floatingActionButton: FloatingActionButton(
+        // Use read() to access methods without listening for rebuilds
+        onPressed: () => context.read<CartViewModel>().addItem('New Item'),
+        child: const Icon(Icons.add),
+      ),
+    );
+  }
+}
+```

package/skills/flutter-project-audit/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: flutter-project-audit
+description: Audits the health of a Flutter project as a whole — pubspec constraints and lock file, analysis_options and lints, SDK and platform configuration (minSdk, iOS deployment target), flavors and environments, generated code, folder structure and test setup. Use when reviewing or auditing a Flutter app or plugin, before a release, or when the user asks whether a Flutter project is well configured.
+intents: [review, architecture, dependency]
+stacks: [flutter]
+---
+
+# Flutter Project Audit
+
+Project health checklist. Every item must be confirmed by reading the cited file; do not report what you could not verify.
+
+## 1. `pubspec.yaml` and dependencies
+
+- [ ] `environment.sdk` with a lower bound compatible with the features used (records, patterns and sealed classes require Dart 3).
+- [ ] Dependencies with caret constraints (`^x.y.z`). `any` or versions without an upper bound are a finding.
+- [ ] `dependency_overrides` present without a comment justifying it: finding (it masks conflicts and tends to be forgotten).
+- [ ] Dev packages (`build_runner`, `mocktail`, `flutter_lints`/`very_good_analysis`) in `dev_dependencies`, not in `dependencies`.
+- [ ] Dependencies via `git:` or `path:` in a published app: confirm it is intentional and that the `ref` is pinned.
+- [ ] `pubspec.lock` committed in **apps** (guarantees reproducible builds). In **packages/plugins**, committing it is optional.
+- [ ] Discontinued or replaced packages: only report with evidence (`pub` warning, package README). Do not claim it from memory.
+
+Useful command, if Flutter is available: `flutter pub outdated`.
+
+## 2. Static analysis
+
+- [ ] `analysis_options.yaml` exists and includes a lint set (`package:flutter_lints/flutter.yaml`, `package:lints/recommended.yaml` or `very_good_analysis`).
+- [ ] Rules disabled in bulk (`ignore:` at the top of files, `// ignore_for_file:`) without justification.
+- [ ] Generated files (`*.g.dart`, `*.freezed.dart`, `*.mocks.dart`) excluded from analysis and consistent with the annotations. Stale generated code is a build bug.
+
+Useful command: `flutter analyze`.
+
+## 3. Native configuration
+
+**Android** (`android/app/build.gradle` or `build.gradle.kts`):
+- [ ] `applicationId` is not the default `com.example.*` (the Play Store rejects it).
+- [ ] `minSdk`/`targetSdk`/`compileSdk`: explicit values or `flutter.*`. An outdated `targetSdk` blocks publishing; confirm the current Play Store requirement before citing a number.
+- [ ] The release `signingConfig` does not use the debug key; passwords come from `key.properties` outside version control.
+- [ ] `minifyEnabled`/`shrinkResources` and ProGuard/R8 rules consistent with plugins that use reflection.
+
+**iOS** (`ios/Runner.xcodeproj`, `ios/Podfile`, `ios/Runner/Info.plist`):
+- [ ] `PRODUCT_BUNDLE_IDENTIFIER` is not `com.example.*`.
+- [ ] The Podfile `platform :ios` aligned with the project's `IPHONEOS_DEPLOYMENT_TARGET`.
+- [ ] Every permission used has its `NS*UsageDescription` with real text (empty or generic text causes App Store rejection).
+
+## 4. Environments and flavors
+
+- [ ] Environment URLs and keys are not hardcoded in `lib/`. The standard is `--dart-define`/`--dart-define-from-file` or flavors.
+- [ ] Values passed via `--dart-define` **are not secret**: they end up in the binary. A private API key must never be in the app.
+- [ ] Production `.env`, `key.properties`, `*.jks`, `*.keystore`, `google-services.json` and `GoogleService-Info.plist` files: check `.gitignore` and `git ls-files`.
+
+## 5. Structure and architecture
+
+- [ ] Consistent organization (feature-first or by layers). Mixing both without criteria is a maintainability finding.
+- [ ] The UI does not call HTTP, the database or platform plugins directly; there is a data/repository layer.
+- [ ] A single predominant state management approach (BLoC, Riverpod, Provider...). Several without reason is a finding.
+- [ ] Centralized dependency injection (constructors, `get_it`, providers), without global singletons scattered around.
+
+## 6. Tests and CI
+
+- [ ] There is a `test/` folder with tests matching the business logic (not just the template's default `widget_test.dart`).
+- [ ] If there is an `integration_test/`, it runs in CI.
+- [ ] The pipeline (`.github/workflows`, `codemagic.yaml`, `bitrise.yml`...) runs at least `flutter analyze` and `flutter test`.
+
+## Output
+
+Report each finding in the matching section of the `mobile-code-reviewer` report (Architecture, Security, Maintainability...), with `file:line` and the proposed fix.

package/skills/flutter-reducing-app-size/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: flutter-reducing-app-size
+description: Measures and optimizes the size of Flutter application bundles for deployment. Use when minimizing download size or meeting app store package constraints.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Thu, 12 Mar 2026 22:22:44 GMT
+intents: [performance]
+stacks: [flutter]
+source: https://github.com/flutter/skills
+license: BSD-3-Clause
+---
+# Reducing Flutter App Size
+
+## Contents
+- [Core Concepts](#core-concepts)
+- [Workflow: Generating Size Analysis Files](#workflow-generating-size-analysis-files)
+- [Workflow: Analyzing Size Data in DevTools](#workflow-analyzing-size-data-in-devtools)
+- [Workflow: Estimating iOS Download Size](#workflow-estimating-ios-download-size)
+- [Workflow: Implementing Size Reduction Strategies](#workflow-implementing-size-reduction-strategies)
+- [Examples](#examples)
+
+## Core Concepts
+- **Debug vs. Release:** Never use debug builds to measure app size. Debug builds include VM overhead and lack Ahead-Of-Time (AOT) compilation and tree-shaking.
+- **Upload vs. Download Size:** The size of an upload package (APK, AAB, IPA) does not represent the end-user download size. App stores filter redundant native library architectures and asset densities based on the target device.
+- **AOT Tree-Shaking:** The Dart AOT compiler automatically removes unused or unreachable code in profile and release modes.
+- **Size Analysis JSON:** The `--analyze-size` flag generates a `*-code-size-analysis_*.json` file detailing the byte size of packages, libraries, classes, and functions.
+
+## Workflow: Generating Size Analysis Files
+
+Use this workflow to generate the raw data required for size analysis.
+
+**Task Progress:**
+- [ ] Determine the target platform (apk, appbundle, ios, linux, macos, windows).
+- [ ] Run the Flutter build command with the `--analyze-size` flag.
+- [ ] Locate the generated `*-code-size-analysis_*.json` file in the `build/` directory.
+
+**Conditional Logic:**
+- **If targeting Android:** Run `flutter build apk --analyze-size` or `flutter build appbundle --analyze-size`.
+- **If targeting iOS:** Run `flutter build ios --analyze-size`. *Note: This creates a `.app` file useful for relative content sizing, but not for estimating final App Store download size. Use the [Estimating iOS Download Size](#workflow-estimating-ios-download-size) workflow for accurate iOS metrics.*
+- **If targeting Desktop:** Run `flutter build [windows|macos|linux] --analyze-size`.
+
+## Workflow: Analyzing Size Data in DevTools
+
+Use this workflow to visualize and drill down into the Size Analysis JSON.
+
+**Task Progress:**
+- [ ] Launch DevTools by running `dart devtools` in the terminal.
+- [ ] Select "Open app size tool" from the DevTools landing page.
+- [ ] Upload the generated `*-code-size-analysis_*.json` file.
+- [ ] Inspect the treemap or tree view to identify large packages, libraries, or assets.
+- [ ] **Feedback Loop:** 
+  1. Identify the largest contributors to app size.
+  2. Determine if the dependency or asset is strictly necessary.
+  3. Remove, replace, or optimize the identified component.
+  4. Regenerate the Size Analysis JSON and compare the new build against the old build using the DevTools "Diff" tab.
+
+## Workflow: Estimating iOS Download Size
+
+Use this workflow to get an accurate projection of iOS download and installation sizes across different devices.
+
+**Task Progress:**
+- [ ] Configure the app version and build number in `pubspec.yaml`.
+- [ ] Generate an Xcode archive by running `flutter build ipa --export-method development`.
+- [ ] Open the generated archive (`build/ios/archive/*.xcarchive`) in Xcode.
+- [ ] Click **Distribute App** and select **Development**.
+- [ ] In the App Thinning configuration, select **All compatible device variants**.
+- [ ] Check the option to **Strip Swift symbols**.
+- [ ] Sign and export the IPA.
+- [ ] Open the exported directory and review the `App Thinning Size Report.txt` file to evaluate projected sizes per device.
+
+## Workflow: Implementing Size Reduction Strategies
+
+Apply these strategies to actively reduce the compiled footprint of the application.
+
+**Task Progress:**
+- [ ] **Split Debug Info:** Strip debug symbols from the compiled binary and store them in separate files.
+- [ ] **Remove Unused Resources:** Audit the `pubspec.yaml` and `assets/` directory. Delete any images, fonts, or files not actively referenced in the codebase.
+- [ ] **Minimize Library Resources:** Review third-party packages. If a package imports massive resource files (e.g., large icon sets or localization files) but only a fraction is used, consider alternative packages or custom implementations.
+- [ ] **Compress Media:** Compress all PNG and JPEG assets using tools like `pngquant`, `imageoptim`, or WebP conversion before bundling them into the app.
+
+## Examples
+
+### Generating Size Analysis (Android)
+```bash
+# Generate the size analysis JSON for an Android App Bundle
+flutter build appbundle --analyze-size --target-platform=android-arm64
+```
+
+### Splitting Debug Info (Release Build)
+```bash
+# Build an APK while stripping debug info to reduce binary size
+flutter build apk --obfuscate --split-debug-info=build/app/outputs/symbols
+```
+
+### Reading the iOS App Thinning Size Report
+When reviewing `App Thinning Size Report.txt`, look for the specific target device to understand the true impact on the user:
+```text
+Variant: Runner-7433FC8E-1DF4-4299-A7E8-E00768671BEB.ipa
+Supported variant descriptors: [device: iPhone12,1, os-version: 13.0]
+App + On Demand Resources size: 5.4 MB compressed, 13.7 MB uncompressed
+App size: 5.4 MB compressed, 13.7 MB uncompressed
+```
+*Interpretation: The end-user download size (compressed) is 5.4 MB, and the on-device footprint (uncompressed) is 13.7 MB.*

package/skills/flutter-secure-token-store/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: flutter-secure-token-store
+description: "Stores JWT access tokens on Flutter with platform secure storage (Keychain on iOS, Keystore-backed storage on Android) via flutter_secure_storage. Use when persisting, reading or clearing auth tokens, or when replacing shared_preferences token storage."
+intents: [security]
+stacks: [flutter]
+---
+
+# flutter-secure-token-store
+
+## Description
+Store JWT tokens securely on Flutter using platform secure storage.
+
+## Language
+Dart
+
+## Inputs
+- `token: String`
+
+## Returns
+- `Future<void>`
+- `Future<String?>`
+
+## Example
+```dart
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+
+class TokenStorage {
+  final FlutterSecureStorage _storage = const FlutterSecureStorage();
+  static const _key = 'access_token';
+
+  Future<void> save(String token) => _storage.write(key: _key, value: token);
+  Future<String?> read() => _storage.read(key: _key);
+  Future<void> clear() => _storage.delete(key: _key);
+}
+```

package/skills/flutter-setting-up-on-macos/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: flutter-setting-up-on-macos
+description: Sets up a macOS environment for Flutter development. Use when configuring a macOS machine to run, build, or deploy Flutter applications for iOS or macOS.
+metadata:
+  model: models/gemini-3.1-pro-preview
+  last_modified: Thu, 12 Mar 2026 22:12:50 GMT
+routing: manual
+stacks: [flutter]
+source: https://github.com/flutter/skills
+license: BSD-3-Clause
+---
+# Setting Up a macOS Environment for Flutter Development
+
+## Contents
+- [Prerequisites](#prerequisites)
+- [Tooling Configuration](#tooling-configuration)
+- [Workflow: Configuring macOS Tooling](#workflow-configuring-macos-tooling)
+- [Workflow: Validating the Environment](#workflow-validating-the-environment)
+- [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+Ensure the following baseline requirements are met before configuring the macOS-specific toolchain:
+- macOS operating system.
+- Flutter SDK installed and added to the system `PATH`.
+- Active internet connection for downloading toolchains and dependencies.
+
+## Tooling Configuration
+macOS desktop development requires specific Apple toolchains to compile and debug native Swift and Objective-C code. 
+- **Xcode**: Required for compiling macOS desktop applications.
+- **CocoaPods**: Required for managing native dependencies used by Flutter plugins.
+
+## Workflow: Configuring macOS Tooling
+
+Copy and follow this checklist to configure the macOS build environment.
+
+- [ ] **Install Xcode**: Install the latest version of Xcode from the Mac App Store or the Apple Developer portal.
+- [ ] **Configure Command-Line Tools**: Link the Xcode command-line tools to the installed Xcode version. Run the following command in the terminal:
+  ```bash
+  sudo sh -c 'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch'
+  ```
+  *Conditional*: If Xcode is installed in a custom directory, replace `/Applications/Xcode.app` with the correct absolute path.
+- [ ] **Accept Xcode Licenses**: Accept the required developer licenses by running:
+  ```bash
+  sudo xcodebuild -license
+  ```
+  Read and agree to the prompts.
+- [ ] **Install CocoaPods**: Install CocoaPods to handle native macOS plugin dependencies.
+  ```bash
+  sudo gem install cocoapods
+  ```
+  *Conditional*: If CocoaPods is already installed, ensure it is updated to the latest version (`sudo gem update cocoapods`).
+
+## Workflow: Validating the Environment
+
+Execute this feedback loop to ensure the environment is correctly configured for macOS desktop development.
+
+- [ ] **Run Validator**: Execute the Flutter diagnostic tool with verbose output:
+  ```bash
+  flutter doctor -v
+  ```
+- [ ] **Review Errors**: Check the `Xcode` section in the output. 
+- [ ] **Fix & Retry**: If errors or missing components are reported under the Xcode section, resolve them according to the output instructions, then re-run `flutter doctor -v` until the Xcode section passes.
+- [ ] **Verify Device Availability**: Confirm that Flutter recognizes the macOS desktop as a valid deployment target:
+  ```bash
+  flutter devices
+  ```
+  *Success Criteria*: The output must contain at least one entry with `macos` listed as the platform.
+
+## Troubleshooting
+
+If the validation workflow fails, apply the following resolutions:
+
+- **Missing Command-Line Tools**: If `flutter doctor` reports missing tools, ensure the `xcode-select` command was run with `sudo` and points to the correct `.app` directory.
+- **CocoaPods Not Found**: If CocoaPods is installed but not detected, verify that your Ruby `gem` binary path is included in your shell's `PATH` environment variable.
+- **Device Not Listed**: If `flutter devices` does not list `macos`, ensure desktop support is enabled in your Flutter configuration:
+  ```bash
+  flutter config --enable-macos-desktop
+  ```