reis-mobile 0.7.0 → 0.7.2

package/core/update/check.mjs

@@ -0,0 +1,119 @@
+import { readFile, mkdir, rm, rmdir, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+import { PLUGIN_ROOT } from '../paths.mjs';
+
+const REGISTRY_URL = 'https://registry.npmjs.org/reis-mobile/latest';
+const SUCCESS_TTL_MS = 24 * 60 * 60 * 1000;
+const FAILURE_TTL_MS = 60 * 60 * 1000;
+
+export function updateCachePath(env = process.env) {
+  const base = process.platform === 'win32'
+    ? env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local')
+    : env.XDG_CACHE_HOME || join(homedir(), '.cache');
+  return join(base, 'reis-mobile', 'update-check.json');
+}
+
+export async function clearUpdateCache(path = updateCachePath()) {
+  try {
+    await rm(path, { force: true });
+    await rmdir(dirname(path));
+  } catch {
+    // Cache cleanup must not prevent uninstalling the plugin.
+  }
+}
+
+export async function installedVersion(root = PLUGIN_ROOT) {
+  return JSON.parse(await readFile(join(root, 'package.json'), 'utf8')).version;
+}
+
+export function compareVersions(left, right) {
+  const parse = (value) => {
+    if (typeof value !== 'string') return null;
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+    if (!match) return null;
+    const numbers = match.slice(1, 4).map(Number);
+    return numbers.every(Number.isSafeInteger) ? { numbers, prerelease: match[4] } : null;
+  };
+  const a = parse(left);
+  const b = parse(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < 3; index++) {
+    if (a.numbers[index] !== b.numbers[index]) return Math.sign(a.numbers[index] - b.numbers[index]);
+  }
+  if (a.prerelease === b.prerelease) return 0;
+  if (!a.prerelease) return 1;
+  if (!b.prerelease) return -1;
+  // The package is published under the stable npm dist-tag. An unknown prerelease
+  // ordering should never generate an update warning for the same base version.
+  return null;
+}
+
+export async function fetchLatestVersion(fetcher = fetch) {
+  const response = await fetcher(REGISTRY_URL, {
+    headers: { accept: 'application/json' },
+    signal: AbortSignal.timeout(1500),
+  });
+  if (!response.ok) throw new Error(`Registry returned ${response.status}`);
+  const { version } = await response.json();
+  if (typeof version !== 'string' || compareVersions(version, version) === null) {
+    throw new Error('Registry returned an invalid version');
+  }
+  return version;
+}
+
+export async function checkForUpdate({
+  current,
+  cachePath = updateCachePath(),
+  now = Date.now(),
+  force = false,
+  fetchVersion = fetchLatestVersion,
+} = {}) {
+  const version = current ?? await installedVersion();
+  let cached;
+  try {
+    cached = JSON.parse(await readFile(cachePath, 'utf8'));
+  } catch {
+    cached = null;
+  }
+  const cachedLatest = compareVersions(cached?.latest, cached?.latest) === 0 ? cached.latest : null;
+  const age = now - cached?.checkedAt;
+  const ttl = cachedLatest ? SUCCESS_TTL_MS : FAILURE_TTL_MS;
+  let latest = cachedLatest;
+  if (force || !Number.isFinite(age) || age < 0 || age >= ttl) {
+    try {
+      latest = await fetchVersion();
+      if (compareVersions(latest, latest) === null) throw new Error('Invalid version');
+    } catch {
+      latest = cachedLatest;
+      if (!latest) {
+        await saveCache(cachePath, { checkedAt: now, latest: null });
+        return { status: 'unavailable', current: version };
+      }
+    }
+    await saveCache(cachePath, { checkedAt: now, latest });
+  }
+  if (!latest || compareVersions(version, latest) === null) return { status: 'unavailable', current: version };
+  return {
+    status: compareVersions(version, latest) < 0 ? 'outdated' : 'current',
+    current: version,
+    latest,
+  };
+}
+
+async function saveCache(path, value) {
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(value), { mode: 0o600 });
+  } catch {
+    // A read-only home must not interrupt a session.
+  }
+}
+
+export function updateMessage({ current, latest }, tool = 'claude') {
+  const update = tool === 'codex'
+    ? 'codex plugin marketplace upgrade reis-mobile && codex plugin add reis-mobile@reis-mobile'
+    : 'claude plugin marketplace update reis-mobile && claude plugin update reis-mobile@reis-mobile';
+  return `reis-mobile ${current} is outdated; ${latest} is available. Update the plugin: ${update}. If you installed the CLI with npm, also run npm update -g reis-mobile.`;
+}

package/docs/agent-context.md

@@ -6,7 +6,7 @@ Read this contract once per task. If the caller supplied a brief, reuse it and v
 
 Use the CLI's resolved `Project` directory and stack/platform focus. Read repository instructions that apply to the files in scope, then relevant architecture docs, build manifests, lock files, nearby implementation and tests. In a monorepo, keep repository-wide constraints and app-specific conventions distinct. Skip generated files and unrelated features.
 
-If the repository contains `.reis-mobile/project.md`, read it for team knowledge that code cannot explain: product vocabulary, critical journeys, intentional boundaries and supported environments. This is optional Markdown read by the model, not a new CLI configuration key. Verify its file paths, symbols and commands against the current checkout; mark stale statements. Do not require a setup interview or create the file unless requested.
+If the repository contains `.reis-mobile/project.md`, read it for team knowledge that code cannot explain: product vocabulary, critical journeys, intentional boundaries and supported environments. In a monorepo with `.reis-mobile/config.yaml`, look beside that config; otherwise look under the resolved app root. This is optional Markdown read by the model, not a new CLI configuration key. Verify its file paths, symbols and commands against the current checkout; mark stale statements and distinguish team-authored business rules from facts inferred from code. Do not require a setup interview or create the file unless requested.
 
 ## Build a compact brief
 
@@ -33,7 +33,7 @@ Trace at least one concrete path through the relevant objects: an action to a st
 
 ## Optional team context
 
-A team can commit `.reis-mobile/project.md` alongside the existing `.reis-mobile/config.yaml` (which continues to support only `app`). Useful content is short and specific:
+A team can run `/reis-mobile:project [feature]` to create or refresh a verified object map in `.reis-mobile/project.md`, then add product knowledge that cannot be inferred from code. The command preserves team-authored text on refresh. The optional profile can live beside the existing `.reis-mobile/config.yaml` (which continues to support only `app`). Useful content is short and specific:
 
 ```markdown
 # Mobile project context

package/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "description": "Warn when a newer reis-mobile release is available.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/update-check.mjs\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "reis-mobile",
-  "version": "0.7.0",
-  "description": "AI agents and skills for mobile development — Flutter, Android, iOS and React Native — as a plugin for Claude Code and Codex: code review, debugging, tests, architecture, security and Firebase.",
+  "version": "0.7.2",
+  "description": "AI agents and skills for Flutter, Android, iOS, React Native and Kotlin Multiplatform — a Claude Code and Codex plugin for reviews, debugging, tests, architecture, security and Firebase.",
   "type": "module",
   "license": "MIT",
   "author": "Warleson Reis",
@@ -19,6 +19,7 @@
     "commands",
     "core",
     "docs/agent-context.md",
+    "hooks",
     "skills",
     "stacks",
     "THIRD_PARTY_NOTICES.md",
@@ -30,7 +31,8 @@
   "scripts": {
     "test": "node --test",
     "validate": "node bin/reis-mobile.mjs validate",
-    "check": "npm run validate && npm test"
+    "check": "npm run validate && npm test",
+    "version:sync": "node scripts/versions.mjs --sync"
   },
   "keywords": [
     "flutter",
@@ -41,6 +43,7 @@
     "swift",
     "swiftui",
     "kotlin",
+    "kotlin-multiplatform",
     "jetpack-compose",
     "dart",
     "firebase",

package/skills/mobile-accessibility/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mobile-accessibility
-description: Audits and fixes accessibility in mobile apps on every stack — screen reader labels, roles, states and reading order for TalkBack and VoiceOver, decorative elements, grouping, touch target size, text scaling and Dynamic Type, color contrast, focus in dialogs and announcements for dynamic content — with the exact APIs for Flutter (Semantics), native Android (Jetpack Compose semantics and Views), native iOS (SwiftUI and UIKit) and React Native, plus automated checks in tests. Use when building or reviewing UI for accessibility, preparing an accessibility audit, fixing TalkBack or VoiceOver issues, or when the user mentions a11y, WCAG, screen readers, font scaling or contrast, even if they only point at one screen.
+description: Audits and fixes mobile accessibility across Flutter, native Android, native iOS, React Native and Kotlin Multiplatform, including shared Compose UI and native hosts. Covers TalkBack/VoiceOver labels, roles, state, reading order, touch targets, text scaling, contrast and focus. Use for a11y audits, screen-reader bugs or accessible UI implementation.
 intents: [accessibility]
 stacks: ["*"]
 ---
@@ -17,6 +17,7 @@ One accessibility process for every mobile stack. This file holds what is true e
 | Native Android: Jetpack Compose or Views | [references/android.md](references/android.md) |
 | Native iOS: SwiftUI or UIKit | [references/ios.md](references/ios.md) |
 | React Native or Expo | [references/react-native.md](references/react-native.md) |
+| Kotlin Multiplatform with shared Compose UI or native host UI | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
 
 In Flutter and React Native apps, the native reference applies only to screens or components written natively (platform views, native modules with UI).
 

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

@@ -27,7 +27,7 @@ Pitfalls:
 ## Announcements and focus
 
 - Mark text that changes on its own (a counter, a status) with `Semantics(liveRegion: true, ...)`.
-- For one-off messages, `SemanticsService.announce(message, textDirection)` exists in `package:flutter/semantics.dart`; check its status in the Flutter version in `pubspec.lock`'s SDK constraint before recommending it, since the announcement APIs have been evolving for multi-view support.
+- For one-off messages, inspect the installed Flutter SDK's `SemanticsService` API and the project's SDK pin before recommending an announcement call; `pubspec.lock` does not identify the exact Flutter SDK version.
 - `SnackBar`s shown through `ScaffoldMessenger` are announced by the framework.
 - Dialogs opened with `showDialog` and routes block the semantics of what is behind them; custom overlays built with `Stack` and `Positioned` do not — use `BlockSemantics` or a route.
 - Control reading order with `Semantics(sortKey: OrdinalSortKey(n))` only when the visual order and the widget order genuinely differ.

package/skills/mobile-accessibility/references/kotlin-multiplatform.md

@@ -0,0 +1,9 @@
+# Kotlin Multiplatform accessibility
+
+Determine whether the changed screen is shared Compose Multiplatform UI, native Android UI, native SwiftUI/UIKit, or a mix. KMP shared domain code has no accessibility tree by itself.
+
+- For shared Compose UI, inspect semantics and state on the actual component, then verify the Android and iOS host experience with TalkBack and VoiceOver. Check the installed Compose version's iOS accessibility behavior against [JetBrains' iOS accessibility guide](https://kotlinlang.org/docs/multiplatform/compose-ios-accessibility.html).
+- For native host UI, use the [Android](android.md) or [iOS](ios.md) reference and inspect the adapter that turns a shared state/error into labels, announcements and focus transitions.
+- Test the same critical journey on both targets at large text sizes. A shared composable test does not prove native screen-reader behavior on either device.
+
+Give **screen path:symbol → rendered target UI → missing name/role/state/order or focus behavior → target-specific fix → verification**. If a target UI is absent, report that fact instead of claiming parity.

package/skills/mobile-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Designs and reviews mobile architecture across Flutter, native Android, native iOS, React Native and Kotlin Multiplatform. Covers state ownership, data flow, modules, dependency boundaries, navigation, offline data and KMP shared source sets versus host apps. Use when structuring a feature, choosing state management, refactoring layers or deciding where a real class or screen belongs.
 intents: [architecture]
 stacks: ["*"]
 ---
@@ -17,6 +17,7 @@ What makes a mobile codebase keep up with its team, and how each stack expresses
 | 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) |
+| Kotlin Multiplatform shared code and target boundaries | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
 
 ## 2. Map before judging
 

package/skills/mobile-architecture/references/kotlin-multiplatform.md

@@ -0,0 +1,11 @@
+# Kotlin Multiplatform architecture
+
+Read the [KMP source-set guide](../../mobile-kmp/references/source-sets.md) before assigning a responsibility to shared or target code.
+
+1. Draw the actual module and source-set graph from Gradle configuration. Mark `commonMain`, intermediate sets, target sets and the Android/iOS host entry points that consume the module. Do not infer a shared UI from the KMP plugin.
+2. Trace one user action through each host into the same shared domain object. Record the state owner, repository or use-case interface, platform adapter, persistence model and error conversion. Include the Swift-facing API if iOS calls shared Kotlin.
+3. Put platform-neutral rules and data contracts in shared code only when both callers need the same behavior. Keep lifecycle, permissions, UI navigation and platform SDK setup with their actual owners. For small platform operations, compare an `expect`/`actual` seam with an injected interface; follow the project's existing pattern.
+4. Specify object mappings at API and persistence boundaries, especially nullability and error types exported to Swift. Name who writes each object and which cache is authoritative.
+5. Return a table of **object/symbol → source set → owner → Android caller → iOS caller → test seam**, plus a minimal migration sequence. Mark proposed paths as proposed.
+
+Check [Kotlin's source-set hierarchy](https://kotlinlang.org/docs/multiplatform/multiplatform-dsl-reference.html) and [platform API connection guidance](https://kotlinlang.org/docs/multiplatform/multiplatform-connect-to-apis.html) against the installed Kotlin version.

package/skills/mobile-code-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mobile-code-review
-description: Reviews mobile code for the bugs that reach production on every stack — Flutter and Dart (pull request checklist, widget lifecycle and rebuilds, project health, static analysis), native Android (Kotlin, coroutines, Jetpack Compose, lifecycle), native iOS (Swift concurrency, SwiftUI, retain cycles) and React Native (hooks, re-renders, platform code, Expo) — with file:line evidence and a structured report. Use whenever the user asks for a code review, PR or merge request review, project audit or quality check of a mobile app, or runs /reis-mobile:review, even if they only point at a diff or a folder.
+description: Reviews mobile code for production bugs across Flutter, native Android, native iOS, React Native and Kotlin Multiplatform, including KMP source-set and host API contracts. Covers lifecycle, concurrency, UI state and native boundaries with file:line evidence. Use for a code review, PR, project audit, quality check or /reis-mobile:review.
 intents: [review, performance]
 stacks: ["*"]
 ---
@@ -19,6 +19,7 @@ Detect the stack first, then apply the platform checklist to the files in scope:
 | Native Android (Kotlin/Java), or the Android side of Kotlin Multiplatform | [references/android.md](references/android.md) |
 | Native iOS (Swift/Objective-C) | [references/ios.md](references/ios.md) |
 | React Native or Expo | [references/react-native.md](references/react-native.md) |
+| Kotlin Multiplatform shared and target changes | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
 
 In a cross-platform app, native code in `android/`, `ios/` or native modules gets the native checklist too. Security findings follow `mobile-security` when it is loaded.
 

package/skills/mobile-code-review/references/flutter/widget-review.md

@@ -23,7 +23,7 @@ Apply to Dart files with widgets (`StatelessWidget`, `StatefulWidget`, `Consumer
 - [ ] Long lists with `ListView(children: [...])` / `Column` inside `SingleChildScrollView`: use `ListView.builder` or `SliverList`.
 - [ ] `shrinkWrap: true` on a large list inside another scroll view: forces layout of every item.
 - [ ] Rebuild scope too large: `setState`, `BlocBuilder` or `Consumer` at the top of the screen when only one part changes. Use `buildWhen`, `select` or extract the widget.
-- [ ] `MediaQuery.of(context)` used only for the size: `MediaQuery.sizeOf(context)` rebuilds less. Confirm the Flutter version in `pubspec.lock` before suggesting it.
+- [ ] `MediaQuery.of(context)` used only for the size: `MediaQuery.sizeOf(context)` rebuilds less. Confirm the project's Flutter SDK pin or installed toolchain before suggesting it.
 - [ ] Network images without `cacheWidth`/`cacheHeight` or without caching, decoded at full resolution to display thumbnails.
 - [ ] Animated `Opacity` or `ClipRRect`/`BackdropFilter` in list items: prefer `FadeTransition`/`AnimatedOpacity` and avoid unnecessary clipping.
 - [ ] Heavy work (parsing large JSON, cryptography, image processing) on the UI thread: use `compute`/`Isolate.run`.

package/skills/mobile-code-review/references/flutter.md

@@ -13,6 +13,6 @@ Apply the checklists in this order; stop early for a small diff that only touche
 
 - Dart style and idioms: the Effective Dart and Dart 3 guides in the `mobile-flutter` skill (`references/dart.md`).
 - Follow the project's state management (BLoC/Cubit, Riverpod, Provider) instead of suggesting another one.
-- Check the Flutter and Dart versions in `pubspec.lock` before recommending newer APIs (`MediaQuery.sizeOf`, Dart 3 patterns).
+- Check the Flutter SDK pin or installed toolchain before recommending newer APIs (`MediaQuery.sizeOf`, Dart 3 patterns); `pubspec.lock` records dependency resolution, not the exact Flutter SDK version.
 - Generated files (`*.g.dart`, `*.freezed.dart`, `*.mocks.dart`) are reviewed through their source annotations, not line by line.
 - Native code under `android/` and `ios/` follows [android.md](android.md) and [ios.md](ios.md).

package/skills/mobile-code-review/references/kotlin-multiplatform.md

@@ -0,0 +1,11 @@
+# Kotlin Multiplatform review
+
+Read the changed module's source-set graph and all configured target implementations. Review the public contract as it is consumed by Android and the Swift/iOS host.
+
+- **Shared logic:** check that DTO/domain conversions, error mapping, coroutine ownership and repository state remain target-neutral. Cite the exact shared symbol and affected caller.
+- **Target completeness:** compare every changed `expect` declaration and actual implementation or injected adapter across configured targets. Check target-only dependencies are declared in the correct source set.
+- **iOS boundary:** inspect framework export, Swift nullability/error handling and callback or coroutine lifetime when a shared API changes. A shared Kotlin compile alone does not validate the Swift caller.
+- **UI boundary:** first determine whether the project shares Compose UI. Review the Android/iOS host lifecycle and accessibility in the correct native or Compose reference.
+- **Tests:** look for common tests for the rule and target/host tests where behavior depends on platform services. Verify that CI actually runs the relevant target tasks.
+
+Return only reproducible findings at `path:line`, with the affected target and smallest fix. Use the [source-set guide](../../mobile-kmp/references/source-sets.md) for the dependency graph.

package/skills/mobile-debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mobile-debug
-description: Finds the cause of failing builds and runtime errors in mobile apps on every stack — Flutter (pub version solving, Dart compilation, generated code, layout overflows, runtime exceptions), native Android (Gradle, AGP, JDK and Kotlin mismatches, dependency conflicts, manifest merger, R8, logcat crashes, ANRs and memory leaks), native iOS (Xcode signing and provisioning, deployment targets, CocoaPods, Swift Package Manager, crash logs) and React Native (Metro, native modules not found, Hermes, the Android and iOS builds underneath), plus deep links, App Links and Universal Links that do not open the app. Use whenever a build, `flutter run`, `pod install`, Gradle task, Xcode archive or app launch fails, when the user pastes a stack trace, "BUILD FAILED" or a red screen, or runs /reis-mobile:debug, even if they only paste the error.
+description: Diagnoses build and runtime failures across Flutter, native Android, native iOS, React Native and Kotlin Multiplatform. Covers pub/Dart, Gradle/AGP, Xcode/CocoaPods, Metro, KMP source sets and iOS frameworks, crashes and deep links. Use for failing builds, app launches, stack traces or /reis-mobile:debug.
 intents: [debug, build, dependency, migration]
 stacks: ["*"]
 ---
@@ -19,6 +19,7 @@ Choose by the stack **and** by the layer the error comes from — a Flutter or R
 | Gradle, the Android build, logcat crashes or ANRs (native Android, or the `android/` folder of any app) | [references/android.md](references/android.md) |
 | Xcode, signing, CocoaPods, Swift packages or iOS crash logs (native iOS, or the `ios/` folder of any app) | [references/ios.md](references/ios.md) |
 | A React Native or Expo app: Metro, native modules, JavaScript errors | [references/react-native.md](references/react-native.md) |
+| Kotlin Multiplatform compilation, source-set or framework integration | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
 | A deep link, App Link or Universal Link that opens the browser, the wrong screen or crashes (any stack) | [references/deep-links.md](references/deep-links.md) |
 
 When `reis-mobile debug` (or `/reis-mobile:debug`) ran, its `area` line points at the layer: `gradle`, `manifest`, `proguard` → Android; `xcode`, `signing`, `cocoapods`, `spm` → iOS; `pub` → Flutter; `metro` → React Native.

package/skills/mobile-debug/references/kotlin-multiplatform.md

@@ -0,0 +1,10 @@
+# Kotlin Multiplatform debugging
+
+Find the first failing module, Gradle task, compilation and target in the log. Read `settings.gradle.kts`, the affected `build.gradle.kts`, version catalog and source-set directories before suggesting a fix.
+
+1. For an unresolved symbol, check whether its dependency and declaration belong to `commonMain`, an intermediate source set or a target source set. Confirm that the failing target actually depends on that set.
+2. For `expect`/`actual` errors, compare declarations and implementations for every configured target; follow the installed Kotlin compiler's message rather than assuming a missing iOS file.
+3. For an iOS framework or Xcode failure, separate Kotlin framework compilation/linking from the Swift host build, then inspect the project's integration method and selected architecture. Use the [Apple integration guide](../../mobile-kmp/references/apple-interop.md).
+4. For an Android failure, apply the [Android debugging reference](android.md) to the host/module. For a native iOS failure, apply the [iOS reference](ios.md) to the host. A shared-source error remains a KMP issue.
+
+Report the first error line, affected source set/target, configuration evidence and the exact project task that reproduces it. Discover task names from the wrapper instead of guessing them. Kotlin's [source-set reference](https://kotlinlang.org/docs/multiplatform/multiplatform-dsl-reference.html) defines the hierarchy.

package/skills/mobile-firebase/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mobile-firebase
-description: Integrates Firebase into mobile apps on every stack — Flutter (FlutterFire), native Android (Kotlin), native iOS (Swift) and React Native (React Native Firebase) — covering project setup, Authentication, Cloud Firestore, Realtime Database, Cloud Storage, callable Cloud Functions, Cloud Messaging push notifications, Analytics, Crashlytics, Remote Config, App Check, In-App Messaging, AI Logic and SQL Connect (formerly Data Connect). Use whenever the user adds, configures, debugs or reviews any Firebase product in a mobile app, including google-services.json, GoogleService-Info.plist, FCM tokens, security rules and the Firebase Local Emulator Suite, even if they only name the product.
+description: Integrates and reviews Firebase across Flutter, native Android, native iOS, React Native and Kotlin Multiplatform. Covers Auth, databases, Storage, Functions, FCM, Analytics, Crashlytics, Remote Config, App Check and KMP shared-to-platform SDK boundaries. Use for any Firebase setup, bug, security rule, emulator, configuration file or product integration.
 routing: manual
 stacks: ["*"]
 ---
@@ -19,6 +19,7 @@ Detect the stack first, then read the platform guide (shared setup and the produ
 | 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) |
+| Kotlin Multiplatform shared API and Android/iOS Firebase boundaries | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
 
 In a Flutter or React Native app, native code in `android/` and `ios/` (a notification service, an app extension) follows the native guides.
 

package/skills/mobile-firebase/references/kotlin-multiplatform.md

@@ -0,0 +1,10 @@
+# Firebase in Kotlin Multiplatform
+
+Start with the installed Gradle dependencies and source sets. Do not assume a Firebase SDK is available to `commonMain`, or that Android and iOS use the same API surface. Identify the actual Firebase wrapper and platform initialization in this repository.
+
+1. Map each requested product operation to a shared interface or target implementation, the Android Firebase setup and the iOS Firebase setup. Record who owns listeners, token refresh and error conversion.
+2. Verify target dependency availability against the installed library and version. If a third-party KMP wrapper is used, inspect its target support and native integration before moving a call into shared code.
+3. Keep each host's configuration, push notification entitlement/permission and lifecycle handling in that host. Read the [Android](android.md) or [iOS](ios.md) product reference only for the affected target.
+4. Test shared mapping against fakes, then test each real target's configuration or emulator setup separately. Do not treat a `commonTest` pass as proof of FCM delivery or native SDK setup.
+
+Report **product → shared symbol → Android implementation/config → iOS implementation/config → verification**, marking unsupported or unverified targets explicitly. Check [Kotlin's platform API guidance](https://kotlinlang.org/docs/multiplatform/multiplatform-connect-to-apis.html) for the boundary options.

package/skills/mobile-flutter/SKILL.md

@@ -26,5 +26,5 @@ Each topic file lists its guides; open only the ones the task needs.
 ## Before writing code
 
 - Follow the project: its state management, folder structure, lints and packages already in `pubspec.yaml`.
-- Check the Flutter and Dart versions in `pubspec.lock` before using newer APIs; guides may describe features that a pinned SDK does not have.
+- Check the Flutter SDK pin (`.fvmrc`, toolchain config or CI) and the installed `flutter --version` before using newer APIs; `pubspec.lock` records resolved packages, not the exact Flutter SDK version.
 - Prefer packages the project already depends on over adding new ones; when adding one, check that it supports every platform the app targets.

package/skills/mobile-kmp/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: mobile-kmp
+description: Works on Kotlin Multiplatform mobile projects with shared Kotlin source sets and Android/iOS targets. Use for architecture, tests, debugging, reviews, performance, security, accessibility, dependencies and releases when `org.jetbrains.kotlin.multiplatform` is applied; inspect actual targets, `commonMain`/`commonTest`, target source sets, Compose Multiplatform and the iOS framework/host app before giving platform advice.
+intents: [architecture, test, performance, review, debug, security, release, accessibility, migration, dependency, build, deployment]
+stacks: [kotlin-multiplatform]
+---
+
+# Kotlin Multiplatform
+
+KMP is a sharing mechanism, not a promise that both apps use the same UI or SDK. Resolve the module and target graph before choosing Android, iOS or shared-code guidance.
+
+| Question | Read |
+|---|---|
+| Which code and dependencies can be shared? | [references/source-sets.md](references/source-sets.md) |
+| How does shared Kotlin reach the iOS app? | [references/apple-interop.md](references/apple-interop.md) |
+| Is UI shared with Compose Multiplatform or native on each target? | [references/compose-ui.md](references/compose-ui.md) |
+| Which build, measurement or release task applies? | [references/build-performance.md](references/build-performance.md) |
+
+## Ground the answer
+
+1. Read `settings.gradle.kts`, the affected module's `build.gradle.kts`, version catalog and source-set directories. Record the configured targets; `androidMain` and `iosMain` are not proof that a target is built in CI.
+2. Trace a real symbol from `commonMain` through an interface or `expect` declaration to each configured implementation and its Android/iOS caller. Name the module, source set and owner at every boundary. For shared Compose UI, trace its host entry too.
+3. Match validation to the changed boundary: shared Kotlin tests on configured targets, target tests for `actual` implementations, and host UI/device tests for behavior that crosses into Android or iOS. A JVM test is not iOS coverage.
+4. Use the topic skill for the requested work. Use `mobile-android` or `mobile-ios` only for an affected host or target-specific implementation; do not apply native-app instructions blindly to `commonMain`.
+
+The [Kotlin Multiplatform source-set reference](https://kotlinlang.org/docs/multiplatform/multiplatform-dsl-reference.html) defines `commonMain`, `commonTest` and target compilations. Confirm DSL and task names in the project's installed Kotlin and Gradle versions.

package/skills/mobile-kmp/references/apple-interop.md

@@ -0,0 +1,9 @@
+# iOS host and framework integration
+
+Locate the iOS app target, scheme and the shared framework declaration in the KMP build. Determine whether the app integrates it through an Xcode build phase, a local/remote Swift package, CocoaPods or another checked-in path. Trace the same Kotlin API to its Swift call and back through errors, callbacks or state observation.
+
+For an iOS build failure, separate Kotlin/Native compilation, framework export/linking, Xcode signing and Swift source errors. Inspect the actual build phase and artifact path before changing Gradle or Pods. Match architecture, configuration and framework version to the failing simulator or device. For a release, verify the framework embedded in the signed app matches the shared module revision and preserve the app's existing symbol upload path.
+
+An iOS simulator test of shared Kotlin does not exercise the Swift app's navigation, permissions or VoiceOver. Use the iOS topic reference when the changed behavior lives in the host.
+
+Reference: [official iOS integration methods](https://kotlinlang.org/docs/multiplatform-ios-integration-overview.html).

package/skills/mobile-kmp/references/build-performance.md

@@ -0,0 +1,9 @@
+# Build, profiling and delivery
+
+List Gradle tasks for the affected module and configured target before naming a command. Use the wrapper, version catalog and CI matrix as the source of the Kotlin, Gradle, Compose and Android plugin versions. A compilation failure in `commonMain` affects all targets; an `ios*` link failure or Android variant failure has a narrower owner.
+
+For performance, identify whether the cost is shared algorithm work, Android UI, iOS host/Compose UI or framework crossing. Measure the same journey and input on each affected target with that target's profiler and release-like configuration; do not infer iOS frame time from JVM or Android traces. Attribute retained state to the shared object, native host or bridge that owns it.
+
+For delivery, trace Android artifact and iOS archive separately to their app IDs, signing, symbols and store workflow. The shared library is an input to both; publishing one platform does not publish the other. Preserve the host app's rollout and rollback process.
+
+References: [KMP test tasks and reports](https://kotlinlang.org/docs/multiplatform-run-tests.html), [iOS framework integration](https://kotlinlang.org/docs/multiplatform-ios-integration-overview.html).

package/skills/mobile-kmp/references/compose-ui.md

@@ -0,0 +1,9 @@
+# Shared UI versus native UI
+
+First find where the screen is implemented. A KMP app may share only logic and render with Jetpack Compose on Android and SwiftUI/UIKit on iOS, or share UI with Compose Multiplatform. Do not apply Compose tests or semantics to a native Swift screen.
+
+For shared Compose UI, trace the screen's state owner, Composable entry, navigation owner and the Android/iOS host that installs it. Keep platform services behind the project's existing boundary. Inspect resource generation and the source set holding each resource; Android `R` resources and Compose Multiplatform `Res` accessors are different APIs.
+
+For accessibility, inspect Compose semantics and verify them on both targets with TalkBack/VoiceOver. For target-specific dialogs, text input, insets or navigation, inspect the native host as well. Verify API availability against the installed Compose Multiplatform version.
+
+References: [Compose resources](https://kotlinlang.org/docs/multiplatform/compose-multiplatform-resources.html), [iOS accessibility](https://kotlinlang.org/docs/multiplatform/compose-ios-accessibility.html).

package/skills/mobile-kmp/references/source-sets.md

@@ -0,0 +1,9 @@
+# Shared-code boundaries
+
+Read the actual `kotlin {}` targets and `sourceSets {}` dependency graph. Identify `commonMain`, intermediate source sets (such as `iosMain`) and target sources. A file's folder does not establish that every configured binary includes it; check `dependsOn` and the target hierarchy.
+
+For a requested feature, record the shared public type, its caller on each target, input/output values and error/cancellation contract. Keep pure business rules and serialization in common code when all targets use the same contract. Put platform SDK calls behind a small common interface or `expect`/`actual` declaration; confirm every configured target has the implementation. Prefer the project's existing injection pattern rather than adding a second one.
+
+When a shared type is exported to Swift, check the actual framework API and conversion at the call site. Kotlin nullability, exceptions, collections and asynchronous work can have a different Swift-facing shape from the Kotlin call. Do not infer that a Kotlin unit test covers the Swift consumer.
+
+References: [source-set DSL](https://kotlinlang.org/docs/multiplatform/multiplatform-dsl-reference.html), [platform APIs and interfaces](https://kotlinlang.org/docs/multiplatform/multiplatform-connect-to-apis.html).

package/skills/mobile-release/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mobile-release
-description: Prepares and checks mobile app releases on every stack — release readiness (go/no-go) checklist, version name and build number, signing, crash symbols (R8 mappings, dSYMs, Dart split debug info, JavaScript source maps), store requirements, staged rollout and rollback, release notes and store listing copy with the Google Play and App Store character limits, and CI/CD pipelines with GitHub Actions, fastlane and EAS — for Flutter, native Android, native iOS and React Native. Use when preparing a version for Google Play or the App Store, auditing whether a build is ready to ship, writing release notes or store descriptions from the git history, setting up or reviewing a build and deploy pipeline, or planning a rollout, even if the user only says "we ship on Friday".
+description: Prepares mobile releases across Flutter, native Android, native iOS, React Native and Kotlin Multiplatform, including separate Android/iOS artifacts from a shared KMP revision. Covers versions, signing, symbols, store readiness, rollout, release notes and CI/CD. Use for release audits, store submission, build pipelines or rollout planning.
 intents: [release, deployment]
 stacks: ["*"]
 ---
@@ -17,6 +17,7 @@ One release process for every mobile stack. This file holds the process and what
 | Native Android, or the Android build of any app | [references/android.md](references/android.md) |
 | Native iOS, or the iOS build of any app | [references/ios.md](references/ios.md) |
 | React Native or Expo app | [references/react-native.md](references/react-native.md) |
+| Kotlin Multiplatform shared module and both host apps | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
 | Release notes and store listing text | [references/store-copy.md](references/store-copy.md) |
 | A CI/CD pipeline that builds, signs and uploads | [references/ci-cd.md](references/ci-cd.md) |
 

package/skills/mobile-release/references/kotlin-multiplatform.md

@@ -0,0 +1,12 @@
+# Kotlin Multiplatform release
+
+A shared module revision can affect two separate app artifacts. Inventory the Android application, iOS host project and framework integration that this repository actually ships.
+
+| Boundary | Verify |
+|---|---|
+| Shared module | Exact commit/version consumed by both hosts, configured target builds and common/target tests. |
+| Android app | Version/build number, signing, release variant, R8 mapping and Play rollout using the [Android guide](android.md). |
+| iOS app | Host version/build number, framework architecture, archive/signing, dSYM and App Store rollout using the [iOS guide](ios.md). |
+| CI | Both artifacts built from the intended shared revision; host tests and upload jobs are distinguished from framework compilation. |
+
+Record **artifact → shared revision → build/test evidence → signing/symbol evidence → rollout owner**. One target passing does not make the other ready. Use the [Apple integration guide](../../mobile-kmp/references/apple-interop.md) to identify the framework path, and confirm current store requirements in each store's official portal.

package/skills/mobile-security/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mobile-security
-description: Security review and hardening for mobile apps on every stack, organized by the OWASP MASVS categories — insecure token and credential storage, hardcoded secrets, cleartext traffic and TLS validation bypass, certificate pinning, exported components and intent handling, deep links, WebView bridges, biometrics, sensitive logging, backups, screenshots and release hardening — with concrete checks for Flutter, native Android, native iOS and React Native. Use when reviewing mobile code for security, auditing an app before release, storing tokens or credentials, handling authentication, deep links or WebViews, or when the user mentions OWASP, MASVS, pentest findings or store security requirements.
+description: Reviews mobile security across Flutter, native Android, native iOS, React Native and Kotlin Multiplatform using OWASP MASVS. Covers credential storage, secrets, transport, deep links, WebViews, logging and platform implementations of shared KMP contracts. Use for security audits, auth/token handling, pentest findings or release hardening.
 intents: [review, security, release]
 stacks: ["*"]
 ---
@@ -17,6 +17,7 @@ Organized by the OWASP MASVS categories. Apply the general checks below, then th
 | Native Android (Kotlin/Java), or `android/` in any app | [references/android.md](references/android.md) |
 | Native iOS (Swift/Objective-C), or `ios/` in any app | [references/ios.md](references/ios.md) |
 | React Native or Expo | [references/react-native.md](references/react-native.md) |
+| Kotlin Multiplatform shared code and platform implementations | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
 
 Firebase-specific protection (security rules, App Check) is covered by `mobile-firebase`.
 

package/skills/mobile-security/references/kotlin-multiplatform.md

@@ -0,0 +1,10 @@
+# Kotlin Multiplatform security
+
+Trace a credential or sensitive value through shared code and both host apps. Mark the concrete storage and network implementations used by each target.
+
+- A `commonMain` interface called `SecureStorage` is not proof of protection: inspect Android's Keystore-backed implementation and iOS Keychain implementation, their failure behavior and how logout clears each store. Do not claim an API exists until the dependency and target code confirm it.
+- Check that shared serializers, caches and logs do not persist or emit tokens or personal data in plain text. Identify the exact object, path and caller.
+- Check platform transport configuration in Android and iOS hosts: cleartext allowances, TLS overrides, deep-link handlers and WebView bridges are target-specific.
+- Check that secrets are not embedded in shared resources or framework exports; anything bundled into either app is extractable.
+
+For each finding, give **source path:line → target(s) → exposed object → consequence → fix**. Apply the [Android](android.md) and [iOS](ios.md) references to affected host files, and follow the project's actual storage/network dependencies. The shared source-set boundary is explained in [mobile-kmp](../../mobile-kmp/references/source-sets.md).

package/skills/mobile-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mobile-test
-description: Writes, runs and reviews automated tests for mobile apps on every stack — Flutter and Dart (unit, widget and integration tests, Patrol, mocktail, mockito, coverage, package:checks), native Android (JUnit, coroutines and Flow tests, Robolectric, Compose UI tests, Espresso, Hilt, screenshot tests), native iOS (Swift Testing, XCTest, XCUITest) and React Native (Jest, React Native Testing Library, Detox, Maestro). Use whenever the user wants to add, fix or audit tests, set up a test stack, mock dependencies, measure coverage or deal with flaky tests in a mobile project, even if they only name a class to test.
+description: Writes, runs and reviews mobile tests across Flutter, native Android, native iOS, React Native and Kotlin Multiplatform. Covers Dart widget/integration tests, JUnit/Compose/Espresso, XCTest/XCUITest, Jest/Detox, and KMP common/target tests. Use to add, fix, run or audit tests, test setup, mocks, coverage and flaky tests for a real app behavior.
 intents: [test]
 stacks: ["*"]
 ---
@@ -19,6 +19,7 @@ Detect the stack first (the router result, or `pubspec.yaml`, Gradle files, the
 | Native Android (Kotlin), or the Android side of Kotlin Multiplatform | [references/android.md](references/android.md); for setting up a test stack from scratch, [references/android/setup/GUIDE.md](references/android/setup/GUIDE.md) |
 | Native iOS (Swift) | [references/ios.md](references/ios.md) |
 | React Native or Expo | [references/react-native.md](references/react-native.md) |
+| Kotlin Multiplatform shared and target tests | [references/kotlin-multiplatform.md](references/kotlin-multiplatform.md) |
 
 A cross-platform app with native code (`android/`, `ios/`, native modules) uses the native reference for that code.
 

package/skills/mobile-test/references/kotlin-multiplatform.md

@@ -0,0 +1,12 @@
+# Kotlin Multiplatform tests
+
+Resolve the configured targets and actual Gradle test tasks before running a command. Use the [KMP testing guide](https://kotlinlang.org/docs/multiplatform-run-tests.html) and the project's Kotlin plugin version to interpret the task graph.
+
+| Behavior under test | Location and runner |
+|---|---|
+| Shared domain rule or mapper | `commonTest`; run the configured target test tasks that compile and execute it. |
+| Android or iOS `actual` implementation | The matching target test source set and runner; a JVM-only pass does not cover Kotlin/Native. |
+| Swift adapter or native host flow | The host app's XCTest/XCUITest or Android local/instrumented suite, depending on the boundary. |
+| Shared Compose screen | Compose Multiplatform UI test where supported by the installed version; also verify the target accessibility and host flow. |
+
+For each requested test, record **source path:symbol → input → result → dependency seam → test source set → real task**. Use existing fixtures and test libraries. Discover task names with the project's Gradle wrapper; avoid assuming all iOS targets run on the current machine. Inspect test counts and target results, not only a successful compilation. [Compose Multiplatform UI testing](https://kotlinlang.org/docs/multiplatform/compose-test.html) has separate host constraints.