rsc-universal 0.1.1

package/skills/compliance/references/operating-rhythm.md

@@ -0,0 +1,79 @@
+# Operating rhythm — schema, calendar, evidence, audit prep
+
+The register is the source of truth. The cadence calendar, evidence catalog, and
+audit-prep runbook are all generated from it.
+
+## Control-register schema
+
+A control register is a flat table, one row per control. Markdown or CSV — both
+lint cleanly with `scripts/verify.sh`.
+
+| Column | Required | Notes |
+| --- | --- | --- |
+| `control-id` | yes | Stable internal id, e.g. `AC-02`, `IR-01` |
+| `framework` | yes | Every framework this control satisfies, multi-tagged |
+| `owner` | yes | A named person/role — never "the team" |
+| `evidence` | yes | The exact proving artifact and where it lives |
+| `cadence` | yes | Review frequency, sized by risk |
+| `last-verified` | recommended | Timestamp of the last attestation |
+| `status` | recommended | `met` / `gap` / `in-progress` |
+
+Optional leading `scope:` line names the frameworks in play, so `verify.sh` can
+warn if a scoped framework has zero mapped controls:
+
+```text
+scope: SOC2, ISO27001, GDPR
+| control-id | framework | owner | evidence | cadence | last-verified | status |
+| --- | --- | --- | --- | --- | --- | --- |
+| AC-02 | ISO27001 A.5.18, SOC2 CC6.2 | Head of IT | quarterly IdP access export, signed | quarterly | 2026-05-30 | met |
+| IR-01 | ISO27001 A.5.24, SOC2 CC7.3 | Security Lead | incident runbook + last tabletop log | annual | 2026-04-12 | met |
+```
+
+## Cadence calendar
+
+| Cadence | Work | Typical owner |
+| --- | --- | --- |
+| Daily | Automated control monitoring, drift/alert review | Security/Ops |
+| Weekly | **Control-health review** — open gaps, stale evidence, overdue owners | Compliance lead |
+| Monthly | Evidence refresh (high-risk controls); vuln-scan review | Control owners |
+| Quarterly | Access recertification; vendor/third-party risk reassessment | IT / Vendor mgmt |
+| Annual | Full risk assessment; policy review; pen test; audit prep | Compliance lead |
+
+The **weekly control-health review** is the heartbeat. Without it, gaps surface
+as audit findings instead of five-minute fixes.
+
+## Evidence-source catalog
+
+For each control, name where its evidence actually comes from. Common sources:
+
+- **IdP / SSO** — access exports, MFA-enforcement config, deprovisioning logs.
+- **Ticketing** — change-management approvals, incident records.
+- **CI/CD** — build provenance, dependency-scan results, deploy approvals.
+- **Cloud config** — encryption-at-rest settings, network rules, logging config.
+- **HR system** — onboarding/offboarding timestamps, training completion.
+- **Vendor portal / DPAs** — third-party security attestations, signed DPAs
+  (drafted by `../contracts/SKILL.md`).
+- **Policy repo** — versioned policy docs (text owned by `../data-policy/SKILL.md`,
+  `../gdpr-privacy/SKILL.md`, `../terms-conditions/SKILL.md`).
+
+Each evidence item must be **timestamped, mapped to the framework clause, and
+owner-attested**.
+
+## Audit-prep runbook
+
+When an audit is announced (or T-90 days):
+
+1. **Confirm scope** — frameworks, criteria/Annex selections, the audit window
+   (for SOC 2 Type II, the 3–12 month period under test).
+2. **Run a gap pass** — filter the register to `status != met`; assign each gap
+   an owner and a close-by date.
+3. **Refresh evidence** — for every in-scope control, confirm evidence exists,
+   is timestamped within the window, and is owner-attested.
+4. **Dry-run the interview** — for each control, can the owner produce the
+   evidence and explain the control in one sentence? If not, that's a finding
+   waiting to happen.
+5. **Stand the rhythm back up** — the audit is a checkpoint, not the goal; the
+   weekly review continues so the next audit is a non-event.
+
+A program running the weekly review all year treats the audit as confirmation,
+not as a crisis.

package/skills/compliance/scripts/verify.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ============================================================================
+# NAME
+#   verify.sh — lint a compliance control register
+#
+# USAGE
+#   ./verify.sh <register.md|register.csv>
+#   ./verify.sh                       # no arg / empty target -> exits 0
+#
+# WHAT IT DOES
+#   1. Detects the register format (Markdown table or CSV).
+#   2. Asserts the required columns exist:
+#        control-id, framework, owner, evidence, cadence, status
+#      (last-verified is recommended, not required).
+#   3. FAILS if any data row is missing owner / evidence / cadence — the
+#      cardinal sin of "checklist theater": a control nobody owns and nothing
+#      proves.
+#   4. WARNS (does not fail) if a framework named in a leading `scope:` line
+#      has zero mapped controls in the register.
+#
+# GUARANTEES
+#   - Read-only: never writes to or modifies the target.
+#   - No dependencies beyond bash + awk + grep (stock macOS bash 3.2 OK).
+#   - Exits 0 on a missing arg, an empty file, or a clean register — never a
+#     false failure on nothing.
+#
+# EXIT CODES
+#   0  Clean / empty / nothing to check.
+#   1  At least one row missing owner, evidence, or cadence; or a required
+#      column is absent.
+# ============================================================================
+
+RED=$'\033[31m'; YEL=$'\033[33m'; GRN=$'\033[32m'; RST=$'\033[0m'
+if [ -n "${NO_COLOR:-}" ]; then RED=""; YEL=""; GRN=""; RST=""; fi
+
+ok()   { printf '%s[ok]%s %s\n'   "$GRN" "$RST" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YEL" "$RST" "$*" >&2; }
+bad()  { printf '%s[FAIL]%s %s\n' "$RED" "$RST" "$*" >&2; }
+
+TARGET="${1:-}"
+
+# No target, or it is not a regular file, or it is empty -> nothing to verify.
+if [ -z "$TARGET" ]; then
+  ok "no register given — nothing to verify"
+  exit 0
+fi
+if [ ! -f "$TARGET" ]; then
+  warn "register not found: $TARGET — nothing to verify"
+  exit 0
+fi
+if [ ! -s "$TARGET" ]; then
+  ok "register is empty — nothing to verify"
+  exit 0
+fi
+
+REQUIRED="control-id framework owner evidence cadence status"
+
+# awk does the parsing for both Markdown-pipe and CSV registers.
+# It prints lint lines on stderr (FAIL:/WARN:) and the final verdict marker.
+RESULT="$(awk -v required="$REQUIRED" '
+  function trim(s) { gsub(/^[ \t]+|[ \t]+$/, "", s); return s }
+  function norm(s) { s=trim(s); gsub(/[ \t]+/, " ", s); return tolower(s) }
+
+  BEGIN {
+    nreq = split(required, req, " ")
+    delim = "|"            # assume markdown until a CSV header proves otherwise
+    have_header = 0
+    fails = 0
+    rows = 0
+  }
+
+  # Capture a scope: line (markdown or plain) before the header.
+  !have_header && tolower($0) ~ /^[ \t]*scope[ \t]*:/ {
+    line = $0
+    sub(/^[ \t]*[Ss][Cc][Oo][Pp][Ee][ \t]*:[ \t]*/, "", line)
+    n = split(line, parts, /[,;]/)
+    for (i = 1; i <= n; i++) {
+      f = norm(parts[i])
+      if (f != "") scope[f] = 1
+    }
+    next
+  }
+
+  # Skip markdown separator rows like | --- | --- |
+  /^[ \t]*\|?[ \t:-]*\|[ \t:|-]*$/ && have_header { next }
+
+  {
+    raw = $0
+    # Choose delimiter from the header line.
+    if (!have_header) {
+      if (raw ~ /\|/) delim = "|"; else if (raw ~ /,/) delim = ","; else next
+    }
+
+    # Split the row on the chosen delimiter.
+    if (delim == "|") {
+      sub(/^[ \t]*\|/, "", raw); sub(/\|[ \t]*$/, "", raw)
+      ncol = split(raw, cells, /\|/)
+    } else {
+      ncol = split(raw, cells, /,/)
+    }
+
+    if (!have_header) {
+      for (c = 1; c <= ncol; c++) {
+        h = norm(cells[c])
+        colidx[h] = c
+      }
+      # Verify required columns are present.
+      missing = ""
+      for (k = 1; k <= nreq; k++) {
+        if (!(req[k] in colidx)) missing = missing " " req[k]
+      }
+      if (missing != "") {
+        print "FAIL: missing required column(s):" missing > "/dev/stderr"
+        fails++
+      }
+      have_header = 1
+      next
+    }
+
+    rows++
+    rownum = rows
+
+    for (k = 1; k <= nreq; k++) {
+      name = req[k]
+      if (name != "owner" && name != "evidence" && name != "cadence") continue
+      ci = colidx[name]
+      val = (ci <= ncol) ? trim(cells[ci]) : ""
+      if (val == "" || val == "-" || tolower(val) == "tbd" || tolower(val) == "n/a") {
+        idc = colidx["control-id"]
+        cid = (idc <= ncol) ? trim(cells[idc]) : ("row " rownum)
+        print "FAIL: control [" cid "] has empty " name > "/dev/stderr"
+        fails++
+      }
+    }
+
+    # Record which scoped frameworks are referenced by some control.
+    fc = colidx["framework"]
+    fval = (fc <= ncol) ? norm(cells[fc]) : ""
+    for (s in scope) { if (index(fval, s) > 0) seen[s] = 1 }
+  }
+
+  END {
+    for (s in scope) {
+      if (!(s in seen))
+        print "WARN: scoped framework \"" s "\" has zero mapped controls" > "/dev/stderr"
+    }
+    print "ROWS=" rows " FAILS=" fails
+  }
+' "$TARGET")"
+
+ROWS="$(printf '%s\n' "$RESULT" | sed -n 's/.*ROWS=\([0-9]*\).*/\1/p')"
+FAILS="$(printf '%s\n' "$RESULT" | sed -n 's/.*FAILS=\([0-9]*\).*/\1/p')"
+ROWS="${ROWS:-0}"; FAILS="${FAILS:-0}"
+
+if [ "$ROWS" -eq 0 ] && [ "$FAILS" -eq 0 ]; then
+  ok "no data rows found — nothing to verify"
+  exit 0
+fi
+
+if [ "$FAILS" -gt 0 ]; then
+  bad "$FAILS issue(s) in register — fix owner/evidence/cadence gaps before audit"
+  exit 1
+fi
+
+ok "register clean: $ROWS control(s), required columns present, no owner/evidence/cadence gaps"
+exit 0

package/skills/compose-multiplatform/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: compose-multiplatform
+description: "Use when building shared UI across Android, iOS, and desktop from one Kotlin codebase with Compose Multiplatform — shared commonMain @Composables, expect/actual for platform divergence, native interop, multiplatform ViewModel/navigation/Koin. Triggers: 'share one Compose UI across Android and iOS', 'my expect has no actual and the build fails', 'where does this code go — commonMain or iosMain', 'embed a SwiftUI/UIKit view inside shared Compose with UIKitView', 'host shared Compose in a SwiftUI app', 'add a desktop target and package it', 'compartir la UI entre Android i iOS amb Kotlin', 'una sola UI para Android, iOS y escritorio'. NOT a single-platform native build (that is kotlin-android / swift-ios), and NOT Dart/Flutter cross-platform UI (that is flutter)."
+tags: [kotlin, kmp, compose-multiplatform, cross-platform, shared-ui, expect-actual, ios, android]
+recommends: [kotlin-android, swift-ios, flutter, tauri]
+origin: risco
+---
+
+# Compose Multiplatform
+
+You write **one** Compose UI tree in `commonMain` and let each platform be a thin host. The whole discipline is one sentence: **common by default, platform by exception.** Every line you put in `commonMain` ships to Android, iOS, and desktop unchanged; every line you put in a platform source set is a deliberate exception you should be able to justify.
+
+## Versions floor (2026)
+
+Pin these or the K2 compiler bites you. Verify against current docs before locking a project — these are the floors, not opinions.
+
+- **Compose Multiplatform 1.11.0**, bundling Jetpack Compose 1.11.1.
+- **Kotlin 2.1.0+** required (2.2.20 recommended for evolving iOS/Web targets). Since CMP 1.8.0 the **K2 compiler is mandatory**, so *every* dependency must compile against Kotlin 2.1.0+.
+- **iOS is Stable** (production-ready since CMP 1.8.0, May 2025): feature parity for popular cases, type-safe navigation with deep linking, accessibility (VoiceOver, Full Keyboard Access).
+- **Web is Beta** (CMP 1.9.0, Sept 2025), runs on WasmGC browsers. Do **not** promise Web parity — ship Android/iOS/desktop, pilot Web.
+- Platform minimums: Android API 21, iOS 14+, macOS 13 arm64, Windows 10+, Ubuntu 20.04+, desktop JDK 11+ (17+ for `jpackage` packaging).
+
+## Where does this code go?
+
+This is the question you answer dozens of times a day. Default to the leftmost column that compiles.
+
+| Source set | Put here | Concrete example | Never here |
+|---|---|---|---|
+| `commonMain` | Shared `@Composable`s, `ViewModel`s, business logic, common `interface`s, `expect` declarations | `@Composable fun GreetingScreen()`, `expect fun platformName(): String` | `android.*`, `platform.UIKit`, `java.awt`, `androidx.activity` |
+| `androidMain` | `Activity`, `actual` using Android `Context`/`Build` | `class MainActivity : ComponentActivity` | iOS/desktop-only APIs |
+| `iosMain` | `ComposeUIViewController` factory, `actual` via cinterop/`platform.*` | `fun MainViewController() = ComposeUIViewController { App() }` | `android.*` |
+| `desktopMain` | `application {}` window, Swing interop | `application { Window(::exitApplication) { App() } }` | mobile-only APIs |
+| `wasmJsMain` (Beta) | Web entry point | `ComposeViewport(document.body!!) { App() }` | anything you can't ship as Beta |
+
+Why this matters: a platform import in `commonMain` breaks the build for *every other* target, and the error surfaces in the iOS link step, far from the offending line. Keep `commonMain` import-clean.
+
+## Project structure (the 2026 default)
+
+The current default KMP layout (announced May 2026, aligned with AGP 9.0) is **a dedicated `shared` KMP library module + per-platform app modules**, not the old single `composeApp`:
+
+```text
+my-app/
+  shared/            # KMP library: commonMain holds the Compose UI tree
+    src/
+      commonMain/    # @Composables, ViewModels, expect declarations, DI
+      androidMain/   # actual impls using android.*
+      iosMain/       # actual impls + ComposeUIViewController
+      desktopMain/   # actual impls + application {} window
+      wasmJsMain/    # web entry (Beta)
+  androidApp/        # thin Android host -> setContent { App() }
+  iosApp/            # Xcode project -> embeds the shared framework
+  desktopApp/        # ./gradlew :desktopApp:run
+  webApp/            # WasmGC entry (Beta)
+```
+
+Split rule: if some screens are native and only *some* are shared Compose, split into **`sharedLogic`** (all platforms) + **`sharedUI`** (CMP platforms only). A server-inclusive project adds a root **`core`** module. Don't pre-split — start with one `shared` module and split when a platform genuinely needs native UI.
+
+Source-set hierarchy — `commonMain` fans out, with intermediate sets where targets share code:
+
+```text
+commonMain
+├── androidMain
+├── desktopMain (jvm)
+├── wasmJsMain (Beta)
+└── iosMain (intermediate)
+    ├── iosArm64
+    └── iosSimulatorArm64
+```
+
+Scaffold a new project with **kmp.new** or the Kotlin Multiplatform wizard (IntelliJ IDEA 2025.2.2+ / Android Studio Otter 2025.2.1+ with the KMP plugin). Add a shared module to an *existing* Android app via Android Studio's **Shared Module Template**.
+
+Minimal version-catalog plugin wiring (full Gradle in `references/project-setup.md`):
+
+```kotlin
+// gradle/libs.versions.toml
+[versions]
+kotlin = "2.2.20"
+compose = "1.11.0"
+agp = "9.0.0"
+
+[plugins]
+kotlinMultiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
+composeMultiplatform = { id = "org.jetbrains.compose", version.ref = "compose" }
+```
+
+## expect / actual — the core mechanism
+
+`expect`/`actual` is how you reach a platform API while keeping the call site common. Declare `expect` in `commonMain`; provide an `actual` in **every** target you compile.
+
+```kotlin
+// commonMain
+expect fun platformName(): String
+```
+
+```kotlin
+// androidMain
+import android.os.Build
+actual fun platformName(): String = "Android ${Build.VERSION.SDK_INT}"
+```
+
+```kotlin
+// iosMain
+import platform.UIKit.UIDevice
+actual fun platformName(): String =
+    UIDevice.currentDevice.systemName + " " + UIDevice.currentDevice.systemVersion
+```
+
+Rules, each with the reason it exists:
+
+- **Every `expect` needs an `actual` in every compiled target.** An orphan `expect` is not a warning — it is a hard build failure (often only surfacing on the iOS target), so add the `actual` per target or remove the target.
+- **Keep the common surface tiny.** Each `expect` symbol multiplies into N `actual`s you maintain; expose the smallest function, not a fat class.
+- **Prefer a common `interface` + DI over deep `expect` trees** for anything you want to test or fake. `expect class` can't be mocked in common tests.
+
+```kotlin
+// Bad: deep expect class — N actuals, untestable in commonTest
+expect class Database {
+    fun query(sql: String): List<Row>
+    fun close()
+}
+```
+
+```kotlin
+// Good: common interface, platform impls injected via Koin (fakeable in tests)
+interface Database {
+    fun query(sql: String): List<Row>
+    fun close()
+}
+// androidMain/iosMain provide SqliteDatabase implementing Database, bound in a Koin module.
+```
+
+## Native interop
+
+You bridge in both directions. Shared Compose embeds native views; native hosts embed shared Compose.
+
+- **iOS — native view inside shared Compose:** `UIKitView` / `UIKitViewController` with a factory lambda.
+- **iOS — shared Compose inside SwiftUI:** wrap `ComposeUIViewController` in a `UIViewControllerRepresentable`.
+- **Android:** `AndroidView` for native views; host the tree via `setContent { App() }` in an `Activity`.
+- **Desktop:** `application { Window { App() } }`; Swing interop via `SwingPanel`.
+
+Embed a native view through an *injected interface*, not a raw `expect` — so the common screen stays platform-agnostic and testable:
+
+```kotlin
+// commonMain
+interface MapFactory { /* returns a platform map handle */ }
+
+@Composable
+fun MapScreen(mapFactory: MapFactory = koinInject()) {
+    // iosMain provides the actual UIKitView wiring around mapFactory; see references/ios-interop.md
+}
+```
+
+Full bridge patterns (`ComposeUIViewController` SwiftUI wrapper, native-view-factory-via-Koin, MapKit/camera, ViewModel lifecycle) live in `references/ios-interop.md` — read it before writing iOS interop.
+
+## State, ViewModel, navigation, DI
+
+- **`androidx.lifecycle.ViewModel` works in `commonMain`.** Obtain instances with `koin-compose-viewmodel`'s `koinViewModel { }` so they survive recomposition. iOS has **no built-in `ViewModelStoreOwner`** — tie the VM lifecycle to SwiftUI manually (KMP-ObservableViewModel lets SwiftUI observe Kotlin VMs).
+- **Koin is the common DI runtime.** Define a shared `initKoin()` and call it from the Android `Application` and from iOS app init:
+
+```kotlin
+// commonMain
+fun initKoin(config: KoinAppDeclaration? = null) = startKoin {
+    config?.invoke(this)
+    modules(appModule, platformModule)
+}
+```
+
+- **Navigation:** `androidx.navigation` provides type-safe nav + deep links in `commonMain`.
+- **Resources:** `compose.components.resources` generates `Res` accessors — `Res.string.app_name`, `Res.drawable.logo`, fonts — shared across all platforms.
+
+## Running & packaging
+
+- **Android:** run the `androidApp` run config (hosts via `setContent`).
+- **iOS:** open `iosApp` in Xcode, or use the KMP iOS run config in the IDE.
+- **Desktop:** `./gradlew :desktopApp:run`; package with `./gradlew :desktopApp:packageDistributionForCurrentOS` (needs **JDK 17+** for `jpackage`).
+- **Web (Beta):** `./gradlew :webApp:wasmJsBrowserDevelopmentRun`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| `android.*` / `platform.UIKit` / `java.awt` import in `commonMain` | Breaks the build for every other target, error surfaces far away | `expect`/`actual` or inject via a common interface |
+| `expect` with no `actual` for a target | Hard build failure on that target | Add an `actual` per compiled target or drop the target |
+| Recreating a `ViewModel` each recomposition (`remember { VM() }` wrong) | State loss on every recompose | `koinViewModel { }` / hoist state |
+| Treating Compose Web as production | Web is Beta (1.9), not Stable | Ship Android/iOS/desktop; pilot Web only |
+| Kotlin < 2.1.0 with CMP 1.8+ | K2 incompatibility — deps fail to link | Bump to Kotlin 2.2.x |
+| Deep `expect class` for testable logic | Can't fake in `commonTest` | Common `interface` + Koin-injected platform impl |
+| Pre-splitting into `sharedLogic`/`sharedUI` on day one | Premature complexity, extra Gradle wiring | Start with one `shared` module; split when a platform needs native UI |
+
+## Verify
+
+After scaffolding or editing, run `scripts/verify.sh <project-dir>` (read-only, no Gradle/Xcode needed). It statically checks the structural invariants:
+
+- a `commonMain` source set exists;
+- every `expect` in `commonMain` has a matching `actual` in some platform source set (catches orphans);
+- the Compose Multiplatform plugin (`org.jetbrains.compose`) and a Kotlin version are present, and Kotlin is >= 2.1.0 (K2 floor);
+- no forbidden platform imports leak into `commonMain`.
+
+It exits 0 on a clean or empty target and non-zero only on hard failures.

package/skills/compose-multiplatform/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — compose-multiplatform
+
+`cases.yaml` is a trigger/routing harness, not an executable test suite. Run it through the repo's eval runner (or read it by hand) to confirm three things: the `should_trigger` prompts — including the non-obvious orphaned-`expect` case and the Catalan phrasing — actually fire this skill on its description; each `should_not_trigger` prompt routes to the named sibling (`kotlin-android`, `swift-ios`, `flutter`, `tauri`) instead of here; and a real skill response to the `capability` scenario satisfies every item in its `must_include` rubric. There is nothing to compile or execute — judgment is against the description and the SKILL.md body.

package/skills/compose-multiplatform/evals/cases.yaml

@@ -0,0 +1,40 @@
+skill: compose-multiplatform
+
+should_trigger:
+  - prompt: "Set up a Kotlin Multiplatform project that shares one Compose UI across Android and iOS."
+    why: Core use — shared commonMain @Composables across platforms, the center of the skill.
+  - prompt: "My `expect fun` compiles fine but the iOS build complains there's no `actual` — how do I fix it?"
+    why: Non-obvious — orphaned expect/actual is a CMP build trap surfacing only on the iOS target.
+  - prompt: "How do I embed a native MapKit/SwiftUI view inside my shared Compose screen using UIKitView?"
+    why: Non-obvious native interop — the iOS UIKitView factory / injected-interface pattern.
+  - prompt: "Compartir la UI entre Android i iOS amb Kotlin, una sola base de codi."
+    why: Catalan phrasing for sharing UI across Android/iOS with Kotlin — the core CMP use.
+  - prompt: "Where should the platform-specific date formatter live — commonMain or androidMain/iosMain?"
+    why: Source-set placement decision — the 'where does this code go' table is the skill's daily question.
+  - prompt: "Add a desktop target to my Compose Multiplatform app and package it with jpackage."
+    why: Desktop breadth — application {} window + packageDistributionForCurrentOS, JDK 17+ floor.
+
+should_not_trigger:
+  - prompt: "Build a native Android-only app with Jetpack Compose and publish it to the Play Store."
+    route_to: kotlin-android
+    why: Single-platform native Android — no shared multiplatform module, Play Store specifics.
+  - prompt: "I'm writing a SwiftUI app in Xcode and need help with App Store code signing."
+    route_to: swift-ios
+    why: Single-platform native iOS — SwiftUI/Xcode/signing, not shared Kotlin Compose.
+  - prompt: "Build a cross-platform mobile UI with Flutter widgets and the flutter CLI."
+    route_to: flutter
+    why: Dart/Flutter cross-platform, not Kotlin/Compose Multiplatform.
+  - prompt: "Create a cross-platform desktop app with a Rust core and a web-tech UI."
+    route_to: tauri
+    why: Rust desktop shell with web UI, not a Kotlin/CMP shared tree.
+
+capability:
+  - scenario: "Scaffold a shared-UI KMP project (a `shared` module plus Android and iOS app hosts), add an `expect`/`actual` `platformName()`, share one @Composable greeting screen across platforms, and embed a native map via `UIKitView` injected through a common interface."
+    must_include:
+      - "shared module whose commonMain holds the shared @Composable greeting screen"
+      - "Compose Multiplatform plugin (org.jetbrains.compose) and Kotlin 2.1.0+ in the build (2.2.x recommended; K2 floor)"
+      - "expect fun platformName() in commonMain with an actual in BOTH androidMain and iosMain"
+      - "no platform import (android.*, platform.UIKit) leaking into commonMain"
+      - "native view embedded via UIKitView fed by an injected common interface, not a raw expect @Composable"
+      - "host wiring named: ComposeUIViewController for iOS and setContent for Android"
+      - "notes iOS is Stable since CMP 1.8.0 and Web is only Beta (1.9), not production"

package/skills/compose-multiplatform/references/ios-interop.md

@@ -0,0 +1,91 @@
+# iOS interop — bridge patterns
+
+Read this before writing any iOS-specific Compose interop. iOS is **Stable** in Compose Multiplatform since 1.8.0 (May 2025). Two directions: native views inside shared Compose, and shared Compose inside SwiftUI.
+
+## 1. Native UIKit view inside shared Compose — `UIKitView`
+
+`UIKitView` (and `UIKitViewController` for a whole controller) takes a `factory` lambda that builds the native object. Run on the main thread; size it with the Compose `modifier`.
+
+```kotlin
+// iosMain
+import androidx.compose.ui.viewinterop.UIKitView
+import platform.MapKit.MKMapView
+
+@Composable
+fun NativeMap(modifier: Modifier = Modifier) {
+    UIKitView(
+        factory = { MKMapView() },
+        modifier = modifier.fillMaxSize(),
+        update = { mapView -> /* mutate mapView on state change */ },
+    )
+}
+```
+
+## 2. Native view factory via a common interface + Koin (preferred)
+
+Keep the shared screen platform-agnostic. Define the contract in `commonMain`, implement it in `iosMain`, inject with Koin. The common `@Composable` never imports `platform.*`.
+
+```kotlin
+// commonMain
+interface NativeViewFactory {
+    @Composable
+    fun MapView(modifier: Modifier)
+}
+
+@Composable
+fun MapScreen(factory: NativeViewFactory = koinInject()) {
+    factory.MapView(Modifier.fillMaxSize())
+}
+```
+
+```kotlin
+// iosMain
+class IosNativeViewFactory : NativeViewFactory {
+    @Composable
+    override fun MapView(modifier: Modifier) {
+        UIKitView(factory = { MKMapView() }, modifier = modifier)
+    }
+}
+// bind in a platformModule: single<NativeViewFactory> { IosNativeViewFactory() }
+```
+
+Why an interface over a raw `expect @Composable`: the Android/desktop targets get their own implementation (or a no-op), and you can fake it in `commonTest`.
+
+## 3. Shared Compose inside a SwiftUI app — `ComposeUIViewController`
+
+Expose a factory from `iosMain`, then wrap it in a SwiftUI `UIViewControllerRepresentable`.
+
+```kotlin
+// iosMain
+import androidx.compose.ui.window.ComposeUIViewController
+
+fun MainViewController() = ComposeUIViewController { App() }
+```
+
+```swift
+// iosApp (SwiftUI)
+import SwiftUI
+import shared
+
+struct ComposeView: UIViewControllerRepresentable {
+    func makeUIViewController(context: Context) -> UIViewController {
+        MainViewControllerKt.MainViewController()
+    }
+    func updateUIViewController(_ vc: UIViewController, context: Context) {}
+}
+
+struct ContentView: View {
+    var body: some View { ComposeView().ignoresSafeArea(.all) }
+}
+```
+
+## 4. ViewModel lifecycle on iOS
+
+`androidx.lifecycle.ViewModel` runs in `commonMain`, but iOS has **no built-in `ViewModelStoreOwner`**, so nothing clears the VM for you.
+
+- Inside a Compose-hosted screen, obtain VMs with `koinViewModel { }` (from `koin-compose-viewmodel`) — they are scoped to the Compose nav entry and cleared correctly.
+- When a Kotlin VM must be observed from *SwiftUI* (not a Compose host), use **KMP-ObservableViewModel** so SwiftUI sees `@Published`-style updates, and clear it from the SwiftUI view's lifecycle.
+
+## 5. Camera / system APIs
+
+Same pattern: a common `interface` (`CameraController`, `SecureStorage`) with an `iosMain` impl using `platform.AVFoundation` / Keychain, injected via Koin. Reserve raw `expect`/`actual` for tiny, untestable leaves (device name, locale).