reis-mobile 0.4.0 → 0.5.0

package/skills/{android-adaptive/SKILL.md → mobile-android/references/ui/adaptive/GUIDE.md}

@@ -1,28 +1,4 @@
----
-name: android-adaptive
-description: Instructions to make or update an app's UI so that it adapts to different
-  Android devices including phones, tablets, foldables, laptops, desktop, TV, Auto
-  and XR. It includes how to handle different window sizes, pointing devices (such
-  as mouse) and text entry devices (such as keyboard) using the Compose MediaQuery
-  API. It also covers multi-pane layouts using Navigation3 Scenes, adaptive UI components
-  (such as buttons) with varying target sizes, and adaptive layouts (including navigation
-  areas - nav rails and nav bars) using the Compose Grid and FlexBox APIs.
-license: Apache-2.0
-source: https://github.com/android/skills
-routing: manual
-stacks: [android]
-metadata:
-  author: Google LLC
-  last-updated: '2026-08-27'
-  keywords:
-  - android
-  - ui
-  - adaptive
-  - Grid
-  - FlexBox
-  - MediaQuery
-  - navigation
----
+> Adapted from the `adaptive` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
 
 ## Prerequisites
 

package/skills/{android-edge-to-edge/SKILL.md → mobile-android/references/ui/edge-to-edge/GUIDE.md}

@@ -1,24 +1,4 @@
----
-name: android-edge-to-edge
-description: Use this skill to migrate your Jetpack Compose app to add adaptive edge-to-edge
-  support and troubleshoot common issues. Use this skill to fix UI components (like
-  buttons or lists) that are obscured by or overlapping with the navigation bar or
-  status bar, fix IME insets, and fix system bar legibility.
-license: Apache-2.0
-source: https://github.com/android/skills
-routing: manual
-stacks: [android]
-metadata:
-  author: Google LLC
-  last-updated: '2026-08-24'
-  keywords:
-  - android
-  - compose
-  - system bars
-  - edge-to-edge
-  - status bar
-  - navigation bar
----
+> Adapted from the `edge-to-edge` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
 
 ## Prerequisites
 

package/skills/{android-migrate-xml-views-to-jetpack-compose/SKILL.md → mobile-android/references/ui/migrate-xml-views-to-jetpack-compose/GUIDE.md}

@@ -1,27 +1,4 @@
----
-name: android-migrate-xml-views-to-jetpack-compose
-description: Provides a structured workflow for migrating an Android XML View to Jetpack
-  Compose. This skill details the step-by-step process, from planning and dependency
-  setup, to theming and layout migration, validation and XML cleanup. Use this skill
-  when you need to migrate an XML View to Jetpack Compose in an Android project. It
-  solves the problem of converting the UI of a legacy XML View into modern, declarative
-  Compose components while maintaining interoperability.
-license: Apache-2.0
-source: https://github.com/android/skills
-routing: manual
-stacks: [android]
-metadata:
-  author: Google LLC
-  last-updated: '2026-08-14'
-  keywords:
-  - Jetpack Compose
-  - migration
-  - XML
-  - Views
-  - interoperability
-  - incremental adoption
-  - UI development
----
+> Adapted from the `migrate-xml-views-to-jetpack-compose` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
 
 This skill guides through the process of migrating an existing Android XML View
 to Jetpack Compose. It performs a stable, safe and visually consistent

package/skills/{android-navigation-3/SKILL.md → mobile-android/references/ui/navigation-3/GUIDE.md}

@@ -1,40 +1,4 @@
----
-name: android-navigation-3
-description: Learn how to install and migrate to Jetpack Navigation 3, and how to
-  implement features and patterns such as deep links, multiple backstacks, scenes
-  (dialogs, bottom sheets, list-detail, two-pane, supporting pane), conditional navigation
-  (such as logged-in navigation versus anonymous), returning results from flows, integration
-  with Hilt, ViewModel, Kotlin, and view interoperability.
-license: Apache-2.0
-source: https://github.com/android/skills
-routing: manual
-stacks: [android]
-metadata:
-  author: Google LLC
-  last-updated: '2026-09-10'
-  keywords:
-  - recipe
-  - Android
-  - Navigation 2
-  - Navigation 3
-  - migration
-  - Compose
-  - guide
-  - dependencies
-  - NavKey
-  - NavHost
-  - NavDisplay
-  - BottomSheet
-  - list-detail
-  - scenes
-  - two-pane
-  - supporting pane
-  - multiple backstacks
-  - dialog
-  - Hilt
-  - ViewModel
-  - View interop.
----
+> Adapted from the `navigation-3` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
 
 *** ** * ** ***
 

package/skills/{android-navigation-event/SKILL.md → mobile-android/references/ui/navigation-event/GUIDE.md}

@@ -1,28 +1,4 @@
----
-name: android-navigation-event
-description: Intercept back gestures and run Predictive Back animations using the
-  NavigationEvent (androidx.navigationevent) library in Compose Android. Handles Activity
-  setup, parent-child dispatcher scoping in `ViewPagers` or tabs, Compose `NavigationBackHandler`,
-  and migration from legacy `BackHandler` on SDK 36+.
-license: Apache-2.0
-source: https://github.com/android/skills
-routing: manual
-stacks: [android]
-metadata:
-  author: Google LLC
-  last-updated: '2026-09-01'
-  keywords:
-  - Android
-  - Navigation Event
-  - Jetpack Compose
-  - Back Navigation
-  - Dispatcher
-  - Guidelines
-  - Troubleshooting
-  - ComponentActivity
-  - Dialog
-  - ViewPager
----
+> Adapted from the `navigation-event` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
 
 ## Common guidelines
 

package/skills/{android-styles/SKILL.md → mobile-android/references/ui/styles/GUIDE.md}

@@ -1,24 +1,4 @@
----
-name: android-styles
-description: Use this skill to integrate the Jetpack Compose Styles API into an Android
-  project. This skill guides you through upgrading dependencies, setting up component
-  themes, making custom components styleable, and migrating existing layout properties
-  to use unified styles. Migrate custom design system components, replace hard coded
-  parameters with Style attributes, and use Modifier.styleable for interaction states.
-license: Apache-2.0
-source: https://github.com/android/skills
-routing: manual
-stacks: [android]
-metadata:
-  author: Google LLC
-  last-updated: '2026-09-08'
-  keywords:
-  - Jetpack Compose
-  - Styles
-  - Theming with Styles
-  - Migrate to Styles
-  - Modifier.styleable
----
+> Adapted from the `styles` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
 
 ## Limitations
 

package/skills/mobile-android/references/ui.md

@@ -0,0 +1,14 @@
+# Android: UI and navigation
+
+Jetpack Compose, adaptive layouts, edge-to-edge, styles, XML-to-Compose migration and Navigation 3.
+
+| Guide | What it covers |
+|---|---|
+| [adaptive](ui/adaptive/GUIDE.md) | Instructions to make or update an app's UI so that it adapts to different Android devices including phones, tablets, foldables, laptops, desktop, TV, Auto and XR. |
+| [edge-to-edge](ui/edge-to-edge/GUIDE.md) | Use this skill to migrate your Jetpack Compose app to add adaptive edge-to-edge support and troubleshoot common issues. |
+| [styles](ui/styles/GUIDE.md) | Use this skill to integrate the Jetpack Compose Styles API into an Android project. |
+| [migrate-xml-views-to-jetpack-compose](ui/migrate-xml-views-to-jetpack-compose/GUIDE.md) | Provides a structured workflow for migrating an Android XML View to Jetpack Compose. |
+| [navigation-3](ui/navigation-3/GUIDE.md) | Learn how to install and migrate to Jetpack Navigation 3, and how to implement features and patterns such as deep links, multiple backstacks, scenes (dialogs, bottom sheets, list-detail, two-pane, supporting pane), conditional navigation (such as logged-in navigation versus anonymous), returning results from flows, integration with Hilt, ViewModel, Kotlin, and view interoperability. |
+| [navigation-event](ui/navigation-event/GUIDE.md) | Intercept back gestures and run Predictive Back animations using the NavigationEvent (androidx.navigationevent) library in Compose Android. |
+
+Each guide lives in its own folder with its references and scripts. Relative paths in a guide — and `<repo_root>` where a guide uses it — refer to that guide's folder.

package/skills/mobile-architecture/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: mobile-architecture
+description: Designs and reviews the architecture of mobile apps on every stack — layers (UI, domain, data), unidirectional data flow, state ownership and state management, feature-first modularization, dependency injection, navigation, offline data and use cases — for Flutter (BLoC, Riverpod, Provider, ChangeNotifier), native Android (ViewModel, Hilt, Gradle modules), native iOS (SwiftUI and UIKit, Observation, Swift packages, actors) and React Native (server vs client state, React Navigation, Expo Router, native modules). Use when structuring a new app or feature, choosing or implementing state management, refactoring to layers or modules, or when the user asks where code should live, even if they only mention one class or screen.
+intents: [architecture]
+stacks: ["*"]
+---
+
+# Mobile Architecture
+
+What makes a mobile codebase keep up with its team, and how each stack expresses it. This file holds the principles; each platform's patterns, libraries and structure live in its reference.
+
+## 1. Pick the reference
+
+| Project | Read |
+|---|---|
+| Flutter | [references/flutter.md](references/flutter.md) — structure guides and one guide per state management library |
+| Native Android (Kotlin), or the Android side of Kotlin Multiplatform | [references/android.md](references/android.md) |
+| Native iOS (Swift) | [references/ios.md](references/ios.md) |
+| React Native or Expo | [references/react-native.md](references/react-native.md) |
+
+## 2. Map before judging
+
+Read the entry point, navigation setup, dependency wiring, module or package graph and two or three representative features before proposing changes. A coherent structure that differs from the references is not a finding; inconsistency and coupling are.
+
+## 3. Principles on every stack
+
+- **Layers with one direction of dependency.** UI renders state and sends events; logic (view models, blocs, stores, use cases) decides; data (repositories and data sources) fetches and stores. UI never calls HTTP clients, databases or platform SDKs directly.
+- **Unidirectional data flow.** State flows down to the UI; events flow up. The UI does not mutate shared state in place.
+- **Single source of truth.** Each piece of data has one owner — usually a repository — that the rest of the app observes. Duplicated copies drift.
+- **State ownership.** Screen state lives with the screen's logic and survives configuration changes where the platform requires it; app-wide state (session, settings) has one explicit owner; server data lives in a cache or repository, not copied into global stores.
+- **Impossible states unrepresentable.** Model loading, content and error as one sealed or discriminated state instead of independent flags.
+- **Feature boundaries.** Organize by feature once there are several; features depend on shared core code, not on each other's internals.
+- **Dependencies injected.** Construct dependencies at a composition root (DI container or initializers) and pass them in; no service locators reached from deep inside features.
+- **Offline and errors by design.** Decide what works offline, how writes sync and how failures reach the user before building screens.
+- **Testability as a check.** If business logic cannot be tested without a device, it is in the wrong layer.
+
+## 4. Proportion
+
+Match the structure to the app and team. A domain layer, a DI framework or a multi-module build pays off with size and team count; adding them to a small app is also a finding. Propose incremental steps with the files involved, highest impact and lowest risk first.
+
+## Output
+
+```markdown
+## Architecture Overview
+## Architecture Issues
+## Coupling Problems
+## Refactoring Suggestions
+## Recommended Architecture
+## Action Plan
+```
+
+Cite `path:line` for every finding.

package/skills/mobile-architecture/references/android.md

@@ -0,0 +1,54 @@
+# Android architecture
+
+Follows Google's guide to app architecture. Adapt to the project instead of forcing a rewrite.
+
+## Layers
+
+- **UI layer:** Composables (or Views) render a `UiState` exposed by a `ViewModel` as `StateFlow`; user events call `ViewModel` functions. Composables stay stateless where possible and receive state and callbacks as parameters (state hoisting).
+- **Domain layer (optional):** use cases for business logic that is reused by several `ViewModel`s or complex enough to test alone. Name them by action (`GetUserOrdersUseCase`) with one public `operator fun invoke`.
+- **Data layer:** repositories are the single source of truth, expose `Flow` or suspend functions, and hide data sources (Retrofit/Ktor services, Room DAOs, DataStore). Offline-first apps read from the database and sync from the network into it.
+
+```kotlin
+@HiltViewModel
+class OrdersViewModel @Inject constructor(repository: OrdersRepository) : ViewModel() {
+    val uiState: StateFlow<OrdersUiState> = repository.observeOrders()
+        .map<List<Order>, OrdersUiState> { OrdersUiState.Content(it) }
+        .catch { emit(OrdersUiState.Error) }
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), OrdersUiState.Loading)
+}
+```
+
+The names are illustrative; use the project's conventions.
+
+## State
+
+- `ViewModel` survives configuration changes; `SavedStateHandle` keeps what must survive process death (ids, form input).
+- Collect state in the UI with lifecycle awareness (`collectAsStateWithLifecycle` in Compose, `repeatOnLifecycle` in Views).
+- One-off events (navigation, messages) are modeled as state the UI consumes, or handled by the UI directly, not replayed on rotation.
+
+## Modularization
+
+```text
+:app                         application, navigation graph, DI wiring
+:feature:<name>              screens and ViewModels of one feature
+:core:data, :core:domain     repositories, use cases
+:core:ui, :core:designsystem shared UI and theme
+:core:testing                fakes and test utilities
+```
+
+- Feature modules do not depend on each other; they communicate through navigation and `:core` contracts.
+- Prefer `implementation` over `api` dependencies to keep modules decoupled and builds incremental.
+- Share build logic with convention plugins and versions with the version catalog.
+- Split into modules when build time, ownership or boundaries need it, not by default in a small app.
+
+## Dependency injection and navigation
+
+- Hilt (or Koin) at the composition root; constructor injection everywhere else. Dispatchers are injected so tests can control them.
+- Navigation: Navigation Compose, or Navigation 3 for new Compose apps (see `mobile-android` → UI). Pass ids between destinations, not objects.
+
+## Problems to look for
+
+- Activities, Fragments or Composables calling DAOs, Retrofit services or `SharedPreferences`.
+- `ViewModel`s holding `Context`, Views or Activity references.
+- Several classes owning the same data, or UI state split into contradictory fields.
+- A single `:app` module in a large codebase, or circular and `api`-leaking module dependencies.

package/skills/{flutter-app-architecture/SKILL.md → mobile-architecture/references/flutter/app-architecture.md}

@@ -1,11 +1,4 @@
----
-name: flutter-app-architecture
-description: Provides best practices for Flutter app architecture, including layered architecture, data flow, state management patterns, and extensibility guidelines.
-intents: [architecture]
-stacks: [flutter]
-source: https://github.com/evanca/flutter-ai-rules
-license: MIT
----
+> Adapted from the `flutter-app-architecture` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Flutter App Architecture Skill
 

package/skills/{flutter-bloc/SKILL.md → mobile-architecture/references/flutter/bloc.md}

@@ -1,11 +1,4 @@
----
-name: flutter-bloc
-description: Implements Flutter state management using the bloc library (Bloc and Cubit). Use when creating new features, screens, or state management logic with bloc/cubit, modeling state, wiring Flutter widgets to blocs, or writing bloc/cubit unit tests.
-routing: manual
-stacks: [flutter]
-source: https://github.com/evanca/flutter-ai-rules
-license: MIT
----
+> Adapted from the `bloc` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Bloc Skill
 

package/skills/{flutter-change-notifier/SKILL.md → mobile-architecture/references/flutter/change-notifier.md}

@@ -1,11 +1,4 @@
----
-name: flutter-change-notifier
-description: Implements state management with ChangeNotifier and Provider in Flutter. Use when setting up ChangeNotifier models, providing them to the widget tree, consuming state with Consumer or Provider.of, or optimizing rebuilds.
-routing: manual
-stacks: [flutter]
-source: https://github.com/evanca/flutter-ai-rules
-license: MIT
----
+> Adapted from the `flutter-change-notifier` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Flutter ChangeNotifier Skill
 

package/skills/{flutter-architecture-feature-first/SKILL.md → mobile-architecture/references/flutter/feature-first.md}

@@ -1,11 +1,4 @@
----
-name: flutter-architecture-feature-first
-description: Structures Flutter apps using layered architecture (UI / Logic / Data) with feature-first file organization. Use when creating new features, designing the project structure, adding repositories/services/view models (or cubits/providers/notifiers), or wiring dependency injection. State management agnostic.
-intents: [architecture]
-stacks: [flutter]
-source: https://github.com/evanca/flutter-ai-rules
-license: MIT
----
+> Adapted from the `architecture-feature-first` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Flutter Architecture — Feature-First Skill
 

package/skills/{flutter-login-usecase/SKILL.md → mobile-architecture/references/flutter/login-use-case.md}

@@ -1,10 +1,3 @@
----
-name: flutter-login-usecase
-description: "Implements a Flutter login use case that authenticates through an injected repository and persists the access token through an injected storage abstraction. Use when building or reviewing the login flow of a Flutter app with layered architecture."
-routing: manual
-stacks: [flutter]
----
-
 # flutter-login-usecase
 
 ## Description

package/skills/{flutter-managing-state/SKILL.md → mobile-architecture/references/flutter/managing-state.md}

@@ -1,14 +1,5 @@
----
-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
----
+> Adapted from the `flutter-managing-state` skill in [flutter/skills](https://github.com/flutter/skills) (BSD-3-Clause). See `THIRD_PARTY_NOTICES.md`.
+
 # Managing State in Flutter
 
 ## Contents

package/skills/{flutter-provider/SKILL.md → mobile-architecture/references/flutter/provider.md}

@@ -1,11 +1,4 @@
----
-name: flutter-provider
-description: Uses the Provider package for dependency injection and state management in Flutter. Use when setting up providers, consuming state, optimizing rebuilds, using ProxyProvider, or migrating from deprecated providers.
-routing: manual
-stacks: [flutter]
-source: https://github.com/evanca/flutter-ai-rules
-license: MIT
----
+> Adapted from the `provider` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Provider Skill
 

package/skills/{flutter-apply-architecture-best-practices/SKILL.md → mobile-architecture/references/flutter/recommended-architecture.md}

@@ -1,14 +1,5 @@
----
-name: flutter-apply-architecture-best-practices
-description: Architects a Flutter application using the recommended layered approach (UI, Logic, Data). Use when structuring a new project or refactoring for scalability.
-metadata:
-  model: models/gemini-3.1-pro-preview
-  last_modified: Tue, 21 Apr 2026 20:11:20 GMT
-intents: [architecture]
-stacks: [flutter]
-source: https://github.com/flutter/skills
-license: BSD-3-Clause
----
+> Adapted from the `flutter-apply-architecture-best-practices` skill in [flutter/skills](https://github.com/flutter/skills) (BSD-3-Clause). See `THIRD_PARTY_NOTICES.md`.
+
 # Architecting Flutter Applications
 
 ## Contents

package/skills/{flutter-riverpod/SKILL.md → mobile-architecture/references/flutter/riverpod.md}

@@ -1,11 +1,4 @@
----
-name: flutter-riverpod
-description: Uses Riverpod for state management in Flutter/Dart. Use when setting up providers, combining requests, managing state disposal, passing arguments, performing side effects, testing providers, or applying Riverpod best practices.
-routing: manual
-stacks: [flutter]
-source: https://github.com/evanca/flutter-ai-rules
-license: MIT
----
+> Adapted from the `riverpod` skill in [evanca/flutter-ai-rules](https://github.com/evanca/flutter-ai-rules) (MIT). See `THIRD_PARTY_NOTICES.md`.
 
 # Riverpod Skill
 

package/skills/mobile-architecture/references/flutter.md

@@ -0,0 +1,21 @@
+# Flutter architecture
+
+Start with the structure guides, then the guide for the state management the project uses. Do not introduce a second state management approach without a reason the user agrees with.
+
+| Guide | What it covers |
+|---|---|
+| [app-architecture](flutter/app-architecture.md) | Provides best practices for Flutter app architecture, including layered architecture, data flow, state management patterns, and extensibility guidelines. |
+| [feature-first](flutter/feature-first.md) | Structures Flutter apps using layered architecture (UI / Logic / Data) with feature-first file organization. |
+| [recommended-architecture](flutter/recommended-architecture.md) | Architects a Flutter application using the recommended layered approach (UI, Logic, Data). |
+| [managing-state](flutter/managing-state.md) | Manages application and ephemeral state in a Flutter app. |
+| [bloc](flutter/bloc.md) | Implements Flutter state management using the bloc library (Bloc and Cubit). |
+| [riverpod](flutter/riverpod.md) | Uses Riverpod for state management in Flutter/Dart. |
+| [provider](flutter/provider.md) | Uses the Provider package for dependency injection and state management in Flutter. |
+| [change-notifier](flutter/change-notifier.md) | Implements state management with ChangeNotifier and Provider in Flutter. |
+| [login-use-case](flutter/login-use-case.md) | Implements a Flutter login use case that authenticates through an injected repository and persists the access token through an injected storage abstraction. |
+
+## Deciding
+
+- Detect the state management in `pubspec.yaml` (`flutter_bloc`, `flutter_riverpod`/`riverpod`, `provider`) and in `lib/` before recommending one.
+- Layers: UI (widgets) → logic (blocs, notifiers, view models) → data (repositories, data sources). Widgets do not call HTTP clients, databases or plugins directly.
+- Feature-first folders scale better than folders by technical type once the app has several features.

package/skills/mobile-architecture/references/ios.md

@@ -0,0 +1,58 @@
+# iOS architecture
+
+Adapt to what the project uses — SwiftUI or UIKit, MVVM or another pattern — instead of forcing a rewrite. Check the deployment target before recommending APIs such as `@Observable` (iOS 17) or SwiftData (iOS 17).
+
+## Layers
+
+- **Presentation:** SwiftUI views stay declarative and render state from an observable model; UIKit view controllers stay thin and delegate to a view model or presenter.
+- **Domain / services:** business rules in plain Swift types behind protocols, testable without UI.
+- **Data:** API clients, persistence (SwiftData, Core Data, files, Keychain) and caching behind repository-like types. Views never call `URLSession` or `UserDefaults` directly.
+
+```swift
+@MainActor
+@Observable
+final class OrdersModel {
+    private(set) var state: LoadState<[Order]> = .loading
+    private let repository: OrdersRepository
+
+    init(repository: OrdersRepository) { self.repository = repository }
+
+    func load() async {
+        do { state = .loaded(try await repository.orders()) }
+        catch { state = .failed(error) }
+    }
+}
+```
+
+The names are illustrative. Before iOS 17, the same model is an `ObservableObject` with `@Published` properties.
+
+## State ownership
+
+- The view that creates a model owns it: `@State` with `@Observable`, or `@StateObject` with `ObservableObject`. Views that receive it do not recreate it (`@ObservedObject`, `@Bindable` or a plain property).
+- App-wide dependencies are injected at the root (initializers or the SwiftUI environment), not reached through singletons.
+- Navigation state lives in one place per flow: a `NavigationStack` path in a model, or a coordinator in UIKit.
+
+## Concurrency boundaries
+
+- UI-facing types are `@MainActor`.
+- Shared mutable state lives in an `actor` or is confined to one isolation domain.
+- Types crossing isolation boundaries are `Sendable`; compiler warnings about isolation are architecture findings, not noise.
+
+## Modularization
+
+```text
+App/                         app target: composition root, navigation, app lifecycle
+Packages/
+  Core/                      networking, persistence, design system, shared models
+  Features/<Name>/           views and models of one feature
+```
+
+- Local Swift packages make boundaries explicit and build incrementally; features depend on `Core`, not on each other.
+- Split when build time, ownership or boundaries need it; a small app does not need a package per screen.
+
+## Problems to look for
+
+- Massive view controllers or views mixing networking, persistence and layout.
+- Singletons used as shared mutable state across features.
+- Models recreated by views that do not own them; navigation state scattered across views.
+- `DispatchQueue.main.async` sprinkled to silence threading warnings instead of actor isolation.

package/skills/mobile-architecture/references/react-native.md

@@ -0,0 +1,61 @@
+# React Native architecture
+
+Adapt to what the project uses — Expo or bare React Native, React Navigation or Expo Router, its state libraries — instead of forcing a rewrite. Check the versions in `package.json` before recommending APIs.
+
+## Structure
+
+```text
+src/
+  app/ or navigation/        routes (Expo Router) or navigators, providers
+  features/<name>/
+    screens/                 screen components
+    components/              feature components
+    hooks/                   feature logic exposed as hooks
+    api/                     requests and response mapping
+  shared/                    design system, API client, utilities, types
+```
+
+Features depend on `shared`; they do not import each other's internals.
+
+## State: decide by kind
+
+| Kind | Where it lives |
+|---|---|
+| Server state (data from APIs) | A server-state cache: TanStack Query or RTK Query — caching, refetching, retries and invalidation included |
+| Screen state (inputs, toggles) | `useState`/`useReducer` in the screen or a feature hook |
+| App-wide client state (session, preferences) | A small store (Zustand, Redux Toolkit) or context with a narrow value |
+| Navigation state | The router; pass ids in params, not objects |
+| Persisted state | MMKV or AsyncStorage for preferences, SQLite for relational data, the Keychain/Keystore for secrets |
+
+Copying server data into a global store and synchronizing it by hand is the most common source of stale data.
+
+## Logic in hooks, UI in components
+
+```tsx
+export function useOrders() {
+  return useQuery({ queryKey: ['orders'], queryFn: api.orders.list });
+}
+
+export function OrdersScreen() {
+  const { data, isPending, isError, refetch } = useOrders();
+  if (isPending) return <Loading />;
+  if (isError) return <ErrorState onRetry={refetch} />;
+  return <OrderList orders={data} />;
+}
+```
+
+The names are illustrative. Components render and delegate; data access and rules live in hooks and plain TypeScript modules that can be tested without rendering.
+
+## Boundaries
+
+- **API layer:** one typed client; responses validated or mapped at the boundary (for example with zod) instead of `as` casts in screens.
+- **Platform differences:** `.ios.tsx`/`.android.tsx` files or a small platform module, not `Platform.OS` checks spread across screens.
+- **Native code:** behind a typed module interface (Turbo Modules or Expo Modules), wrapped once. Check whether the app runs on the New Architecture before choosing a native module approach.
+- **Configuration:** environment values through the build (app config, EAS environment variables); secrets stay on the backend.
+
+## Problems to look for
+
+- `fetch`/`axios` calls and business rules inside components and effects.
+- One large context re-rendering the whole app on any change, or deep prop drilling.
+- Large objects or callbacks passed through navigation params.
+- `strict` TypeScript disabled in a codebase that relies on types.