@code-migration/wow-migrator 0.2.1 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code-migration/wow-migrator",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "description": "Install KMP migration skills into Claude Code, Codex, Cursor, Gemini, OpenCode, OpenClaw, and JiuwenSwarm via npm install.",
   "keywords": [
     "android",

package/skills/android-to-kmp-migrator/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: android-to-kmp-migrator
 description: |
-  Module-first Swarm Skill that migrates Legacy Android into an existing KMP target using upstream analyst P6 artifacts, target-project-assistant alignment, planning/prep/implementation roles, global integrate+align phase, and mandatory kmp-test-validator handoff — without full-project build during migration.
-  Use only after android-project-analyst has finished and package P6 is ready, when the user wants module-first porting then whole-system assembly followed by validation.
-  Do NOT invoke before android-project-analyst completes P6. Do NOT treat migrator completion as final without invoking kmp-test-validator at V0. Do NOT use for Legacy Android analysis only, KMP-only feature work, or non-migration refactors.
-version: "0.8"
+  Module-first Swarm Skill that migrates Legacy Android into an existing KMP target by editing target KMP source after analyst P6 understanding — planning/prep/implementation roles create and update files under kmp_target_project_path, global integrate wires cross-module glue, then mandatory kmp-test-validator handoff — without full-project build during migration.
+  Use only after android-project-analyst has finished and package P6 is ready, when the user wants module-first porting with real target code changes then whole-system assembly followed by validation.
+  Do NOT invoke before android-project-analyst completes P6. Do NOT treat planning or analysis artifacts alone as migration success — target KMP files MUST be edited. Do NOT treat migrator completion as final without invoking kmp-test-validator at V0. Do NOT use for Legacy Android analysis only, KMP-only feature work, or non-migration refactors.
+version: "0.9"
 kind: swarm-skill
 disable-model-invocation: false
 roles:
@@ -57,13 +57,13 @@ roles:
 
 # Android To KMP Migrator Swarm Skill
 
-Module-first migrator for Legacy Android → KMP target assembly.
+Module-first migrator for Legacy Android → KMP target assembly. **Upstream analyst P6 is read-only input; this skill's job is to edit the target KMP project** under `kmp_target_project_path`.
 
 **Canonical contract**: [output-contract.md](output-contract.md)
 
 ## Protocol Summary
 
-0. Pre-flight — [dependencies.yaml](dependencies.yaml): `rg` / `git` / `curl`, optional `jetbrains` MCP (`optional_mcp`), upstream analyst **P6** (`upstream_inputs`); record `dependency_preflight` in `run_manifest.json`.
+0. Pre-flight — [dependencies.yaml](dependencies.yaml): `rg` / `git` / `curl`, optional `jetbrains` MCP (`optional_mcp`), upstream analyst **P6** (`upstream_inputs`); **identify `design_mode` from user input (default `mvi`)**; record `dependency_preflight` and `design_mode` in `run_manifest.json`.
 1. Verify analyst **P6**; `run_manifest.json`, `upstream_analyst_index.json`.
 2. Migration inventory + `modules_migration_index.json`.
 3. Workspace state init.
@@ -73,6 +73,23 @@ Module-first migrator for Legacy Android → KMP target assembly.
 7. Global representation + completion-report `report` mode.
 8. **kmp-test-validator** — **mandatory** when **V0** ready (MG17).
 
+## Design Mode (architecture pattern)
+
+The migrator targets one presentation architecture per run, selected at **pre-flight (Step 0)** by the Leader from the **user input**, then frozen for the whole run and recorded in `run_manifest.json` → `design_mode`.
+
+| `design_mode` | Architecture reference | When chosen |
+|---|---|---|
+| `mvi` **(default)** | [references/kmp-mvi-flowredux.md](references/kmp-mvi-flowredux.md) | Default when user input gives no clear signal; or user mentions MVI, FlowRedux, state machine, reducer, intent, unidirectional, sealed `State`/`Action`, `dispatch`, `inState`, `onEnter` |
+| `mvvm` | [references/kmp-mvvm.md](references/kmp-mvvm.md) | User mentions MVVM, shared `ViewModel`, `StateFlow`/`uiState`, `viewModelScope`, `collectAsStateWithLifecycle`, KMP-ObservableViewModel, SKIE |
+
+Both modes also follow [references/kmp-expert.md](references/kmp-expert.md) for base KMP/CMP conventions.
+
+**Rules**:
+- **Default is `mvi`** — when the user input contains no explicit or implied architecture signal, the Leader MUST select `mvi`.
+- Record the decision as `design_mode: { value, source: "user_input | default", signals: [] }` in `run_manifest.json` at **MG0**.
+- The Leader passes `design_mode` and the resolved `architecture_reference_path` to every architecture-producing role (planning-gate, prep, module-implementation, module-node-review-fix, global-migration-phase) and to TPA for target-pattern detection.
+- `design_mode` is **fixed for the run**; a mid-run change requires a fresh run, not in-place mutation.
+
 ## Skill Chain (mandatory)
 
 ```text
@@ -108,6 +125,7 @@ android-project-analyst (P6) → android-to-kmp-migrator (M0–V0) → kmp-test-
 | [bind.md](bind.md) | Limits, constraints, failures |
 | [dependencies.yaml](dependencies.yaml) | CLI + optional MCP per role |
 | [roles/](roles/) | Role specs |
+| [references/](references/) | Architecture references: `kmp-mvi-flowredux.md` (MVI, default), `kmp-mvvm.md` (MVVM), `kmp-expert.md` (base KMP/CMP) |
 
 ## Handoff Gates
 
@@ -123,6 +141,14 @@ android-project-analyst (P6) → android-to-kmp-migrator (M0–V0) → kmp-test-
 ## Shared Rules
 
 - **Skill chain**: `android-project-analyst` **P6** before migrator; `kmp-test-validator` **after** migrator **V0** — both mandatory.
+- **Design mode**: identified from user input at pre-flight, **default `mvi`**; frozen for the run; architecture-producing roles MUST follow the resolved `architecture_reference_path` (`kmp-mvi-flowredux.md` for `mvi`, `kmp-mvvm.md` for `mvvm`).
+- **Target KMP edit mandate**: after analyst P6 understanding, migrator roles MUST create or update production files under `kmp_target_project_path`. Planning-only or artifact-only completion is invalid.
+- **Roles that edit target** (record `changed_files[]` or `integration_changed_files[]`):
+  - `migration-prep` — optional scaffold edits (theme, resources, routes, models) when planning allows
+  - `module-implementation` `ui` / `logic` — required per-module UI and logic port
+  - `module-node-review-fix` `fix` — scoped remediation in `allowed_files`
+  - `global-migration-phase` `integrate` — cross-module glue and entry-point wiring
+- **Read-only on target**: `target-project-assistant`, `migration-planning-gate`, `migration-verification`, `global-migration-phase` `align`, `completion-report`.
 - Analyst **P6** required; TPA owns all target Q&A.
 - Mode boundaries non-negotiable: `ui`/`logic`, `integrate`/`align`, `review`/`fix`.
 - No full project build in migrator.

package/skills/android-to-kmp-migrator/bind.md

@@ -16,11 +16,20 @@
 - **Forbidden**: `incremental_build` in migrator.
 - **kmp-test-validator**: full compile/build/test at package **V0**.
 
+## Target KMP Edit Mandate
+
+- Analyst **P6** is read-only input. Migrator success requires **editing the target KMP project** at `kmp_target_project_path`.
+- **Edit-owning roles**: `migration-prep` (optional scaffold), `module-implementation` `ui`/`logic` (required), `module-node-review-fix` `fix`, `global-migration-phase` `integrate`.
+- **Read-only on target**: TPA, `migration-planning-gate`, `migration-verification`, `global-migration-phase` `align`, `completion-report`.
+- When planning tasks require file changes, `changed_files[]` MUST be non-empty and paths MUST resolve under `kmp_target_project_path`.
+- `migration_report.json` MUST aggregate `target_changed_files[]` before **V0**.
+
 ## Behavioral Constraints
 
 - **Skill chain (mandatory)**:
   - **Before migrator**: `android-project-analyst` MUST finish and produce package **P6** (`handoff_gates.P6.ready = true`). If P6 is missing or stale, return `blocked` and dispatch analyst — do not start migrator nodes.
   - **After migrator**: when package **V0** is ready, Leader MUST invoke `kmp-test-validator` (MG17). Migrator completion without validator dispatch is invalid.
+- **Design mode**: at pre-flight the Leader identifies `design_mode` from user input — **default `mvi`** when no architecture signal is present. It is recorded in `run_manifest.json`, **frozen for the run**, and every architecture-producing role MUST follow the resolved `architecture_reference_path` (`references/kmp-mvi-flowredux.md` for `mvi`, `references/kmp-mvvm.md` for `mvvm`). Both modes also follow `references/kmp-expert.md`.
 - **Role schedule**: dispatch only role IDs listed in [SKILL.md](SKILL.md).
 - **Mode discipline**:
   - `module-implementation`: `ui` then `logic` — separate invocations
@@ -36,6 +45,9 @@
 | Failure | Response |
 |---|---|
 | Unknown or invalid role ID | Reject; use role from `SKILL.md` registry |
+| `design_mode` not identified at pre-flight | Default to `mvi`; record `source: default` in `run_manifest.json` |
+| Architecture-producing dispatch missing `design_mode` | Reject; re-dispatch with `design_mode` + `architecture_reference_path` |
+| Code produced against wrong architecture vs `design_mode` | `needs_rerun` owning role with correct reference |
 | `ui` and `logic` combined | Reject invocation |
 | `integrate` and `align` combined | Reject invocation |
 | Verification restoration failed | Rerun `module-implementation` or `migration-prep`; no completion record |
@@ -44,6 +56,9 @@
 | Build requested in migrator | Block; route to kmp-test-validator |
 | Migrator invoked before analyst P6 | Block; dispatch `android-project-analyst` first |
 | V0 ready but validator not invoked | Block; dispatch `kmp-test-validator` at MG17 |
+| Analysis/planning only — no target edits when required | Block package M3; rerun `module-implementation` or `migration-prep` |
+| `changed_files` outside `kmp_target_project_path` | Block; rerun owning edit role |
+| Empty `target_changed_files` in `migration_report.json` when scope required edits | Block package V0 |
 
 ## Dependencies
 

package/skills/android-to-kmp-migrator/output-contract.md

@@ -128,13 +128,26 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 - **`incremental_build` is forbidden** in `migration-verification` during migrator runs.
 - **Full compile/build/preview/behavioral tests** are delegated to **`kmp-test-validator`** after `migration_report.*` handoff package **`V0`** is ready.
 
+### Target KMP Edit Mandate (mandatory)
+
+- **Purpose**: `android-project-analyst` **P6** supplies Legacy Android understanding only. The migrator MUST translate that understanding into **concrete edits** in the existing KMP target at `kmp_target_project_path`.
+- **Analysis alone is not migration**: planning gates, prep handoffs, TPA alignment, and representations do **not** satisfy migration without target file changes where tasks require implementation.
+- **Edit-owning roles** (each MUST record paths under `kmp_target_project_path`):
+  - `migration-prep` → `migration_prep.json` → `changed_files[]` (optional scaffold when planning allows)
+  - `module-implementation` `ui` / `logic` → `module_implementation_ui.json` / `module_implementation_logic.json` → `changed_files[]`, `target_edit_summary`
+  - `module-node-review-fix` `fix` → `module_node_fix.json` → `changed_files[]`
+  - `global-migration-phase` `integrate` → `global_system_integration.json` → `integration_changed_files[]`, `entry_point_wiring[]`
+- **Read-only on target**: `target-project-assistant`, `migration-planning-gate`, `migration-verification`, `global-migration-phase` `align`, `completion-report`.
+- **Fail closed**: when `migration_planning_gate.json` → `planning.tasks[]` includes file-changing work for a module, package **M3** is false if both `module_implementation_ui.json` and `module_implementation_logic.json` have empty `changed_files[]` or paths resolve outside `kmp_target_project_path`.
+- **Aggregation**: `migration_report.json` MUST include `target_changed_files[]` — deduplicated union of all module and global integrate target paths with `owning_role` and `migration_module_id` (or `global` for integrate).
+
 ---
 
 ## Write Order (Leader Schedule)
 
 | Step | Gate | Required artifacts before next step |
 |---|---|---|
-| `MG0` | Run lock | `run_manifest.json`, `upstream-index/upstream_analyst_index.json` |
+| `MG0` | Run lock | `run_manifest.json` (incl. `design_mode`), `upstream-index/upstream_analyst_index.json` |
 | `MG1` | Workspace init | global `migration_workspace_state.*` |
 | `MG2` | Migration index | `migration_module_inventory.*`, `modules_migration_index.json`, per-module `module_brief.json` |
 | `MG3` | Target baseline | global `target-project-assistant/*` (`mode: global_baseline`) + `target_alignment_revision.*` |
@@ -184,8 +197,9 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 | `migration-planning-gate/migration_planning_gate.json` |
 | `migration-prep/migration_prep.json` |
 | `module-implementation/ui/module_implementation_ui.json`, `module-implementation/logic/module_implementation_logic.json` + approved reviews |
-| `migration_verification.json` with all required `check_ids` passed |
-| `module_completion_record.json` with `ui_restoration` and `logic_restoration` passed |
+| **Target edits**: when planning tasks require file changes, both UI and logic implementation artifacts MUST have non-empty `changed_files[]` under `kmp_target_project_path` |
+| `migration_verification.json` with all required `check_ids` passed (including `target_files_exist` when `changed_files` non-empty) |
+| `module_completion_record.json` with `ui_restoration` and `logic_restoration` passed and `target_changed_files[]` listing module target paths |
 
 ### Package `M4` — All modules migrated
 
@@ -199,7 +213,7 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 | Required paths |
 |---|
 | Package `M4` |
-| `global/node-results/global-migration-phase/integrate/global_system_integration.json` |
+| `global/node-results/global-migration-phase/integrate/global_system_integration.json` with non-empty `integration_changed_files[]` when cross-module glue or entry-point wiring is required |
 | `global_migration_representation.json` |
 
 ### Package `M6` — Post-integration alignment passed
@@ -215,7 +229,7 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 | Required paths |
 |---|
 | Package `M6` |
-| `report/migration_report.json` |
+| `report/migration_report.json` with non-empty `target_changed_files[]` when any scheduled module required implementation |
 | `global_migration_representation.json` |
 | analyst `SPEC/*` paths recorded in `run_manifest.json` |
 
@@ -227,6 +241,30 @@ output_root = <output_dir or ~/.a2c_agents/migration>/android-to-kmp-migrator
 
 ## Key Artifact Content Requirements
 
+### `run_manifest.json` → `design_mode`
+
+Records the presentation architecture pattern, identified from **user input** at pre-flight (Step 0a) and **frozen for the run**. Default is `mvi` when user input gives no clear signal.
+
+```json
+{
+  "design_mode": {
+    "value": "mvi",
+    "source": "default",
+    "signals": [],
+    "architecture_reference_path": "references/kmp-mvi-flowredux.md"
+  }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `value` | `mvi` (default) \| `mvvm` |
+| `source` | `user_input` when a signal was matched; `default` when none |
+| `signals` | matched keywords/phrases from user input (empty when defaulted) |
+| `architecture_reference_path` | `references/kmp-mvi-flowredux.md` for `mvi`, `references/kmp-mvvm.md` for `mvvm` |
+
+The Leader MUST pass `design_mode.value` and `design_mode.architecture_reference_path` into every architecture-producing dispatch (`migration-planning-gate`, `migration-prep`, `module-implementation`, `module-node-review-fix`, `global-migration-phase`) and to `target-project-assistant` for target-pattern detection.
+
 ### `upstream_analyst_index.json`
 
 ```json
@@ -262,8 +300,10 @@ Machine lookup: `migration_module_id` → `legacy_module_id`, `module_output_roo
 {
   "migration_module_id": "",
   "legacy_module_id": "",
+  "kmp_target_project_path": "",
   "completion_status": "completed | needs_rerun | blocked",
   "verification_ref": "",
+  "target_changed_files": [{ "path": "", "owning_role": "migration-prep | module-implementation | module-node-review-fix", "mode": "ui | logic | fix | null" }],
   "ui_restoration": { "status": "passed | failed", "gaps": [] },
   "logic_restoration": { "status": "passed | failed", "gaps": [] },
   "upstream_match": { "module_representation_path": "", "matched_claims": [], "missing_claims": [] },
@@ -274,6 +314,7 @@ Machine lookup: `migration_module_id` → `legacy_module_id`, `module_output_roo
 
 ### `migration_verification.json` — required `check_ids` (migrator only)
 
+- `target_files_exist` — every path in aggregated module `changed_files[]` exists on disk under `kmp_target_project_path`
 - `source_set` — files in allowed source sets
 - `syntax_check` — Kotlin/syntax validity on changed files (static; no full project compile)
 - `api_contract` — API/model shape vs planning + analyst data contracts
@@ -311,14 +352,16 @@ Human/agent-readable synthesis of align mode; includes `entry_point_alignment_re
 
 ## Leader Obligations
 
-1. Verify analyst package `P6` before `MG0` completes.
+1. Verify analyst package `P6` before `MG0` completes; identify `design_mode` from user input (default `mvi`) and write it to `run_manifest.json` at `MG0`, then pass `design_mode` + `architecture_reference_path` into every architecture-producing dispatch.
 2. Dispatch `target-project-assistant` for all target-project questions; other roles MUST reference TPA artifacts instead of re-analyzing target ad hoc.
-3. Write `module_completion_record.json` after each module passes `migration-verification`.
-4. Run `global-migration-phase` `integrate` only after package `M4`.
-5. Run `global-migration-phase` `align` only after integrate; **no code changes** in align mode.
-6. Dispatch only role IDs listed in [SKILL.md](SKILL.md).
-7. Set `handoff_gates` (`M0`–`M6`, `V0`) in workspace ledger and `migration_report.json`.
-8. **MUST** invoke `kmp-test-validator` when `V0` is true (MG17). Do not end the migration workflow without validator dispatch or explicit validator blockers in `migration_report.json`.
+3. Ensure each module produces **target KMP edits** via `module-implementation` (and optional `migration-prep` / `module-node-review-fix` `fix`) before writing `module_completion_record.json`.
+4. Write `module_completion_record.json` after each module passes `migration-verification`; include aggregated `target_changed_files[]` for the module.
+5. Run `global-migration-phase` `integrate` only after package `M4`; integrate MUST edit target glue when assembly requires it.
+6. Run `global-migration-phase` `align` only after integrate; **no code changes** in align mode.
+7. Dispatch only role IDs listed in [SKILL.md](SKILL.md).
+8. Set `handoff_gates` (`M0`–`M6`, `V0`) in workspace ledger and `migration_report.json`.
+9. Aggregate all module and global integrate target paths into `migration_report.json` → `target_changed_files[]`.
+10. **MUST** invoke `kmp-test-validator` when `V0` is true (MG17). Do not end the migration workflow without validator dispatch or explicit validator blockers in `migration_report.json`.
 
 ## Invalid Artifact Handling
 
@@ -331,3 +374,9 @@ Human/agent-readable synthesis of align mode; includes `entry_point_alignment_re
 | `module_completion_record` failed | Re-enter module loop from routed node |
 | `post_integration_alignment` omissions | Rerun listed modules or `global-migration-phase integrate` |
 | Full build requested during migrator | Reject — route to `kmp-test-validator` |
+| Planning complete but `changed_files[]` empty when tasks require edits | `needs_rerun` → `module-implementation` or `migration-prep` |
+| `changed_files` paths outside `kmp_target_project_path` | `blocked` — reject artifact; rerun owning role |
+| `target_files_exist` failed | `needs_rerun` → owning edit role |
+| `design_mode` missing from `run_manifest.json` at MG0 | `blocked`, `reason: missing` — Leader must identify (default `mvi`) before module dispatch |
+| Architecture-producing dispatch missing `design_mode` / `architecture_reference_path` | Reject dispatch; re-dispatch with `design_mode` injected |
+| Implementation/review uses the wrong architecture vs `design_mode` | `needs_rerun` → owning role with correct `architecture_reference_path` |

package/skills/android-to-kmp-migrator/references/kmp-expert.md

@@ -0,0 +1,260 @@
+---
+name: kmp-expert
+description: >
+  Foundational Kotlin Multiplatform / Compose Multiplatform knowledge for KMP/CMP
+  development. Use when working on any KMP/CMP task: project setup, source set
+  hierarchy, expect/actual, Gradle/version-catalog config, choosing the library
+  stack (Ktor, SQLDelight, Room, Koin, serialization), iOS interop (SKIE,
+  KMP-NativeCoroutines), Wasm/web targets, or debugging build/source-set issues.
+  Triggers on Kotlin Multiplatform, KMP, CMP, Compose Multiplatform, commonMain,
+  expect/actual, shared module, iosMain, klib, Kotlin/Native.
+---
+
+# Kotlin Multiplatform / Compose Multiplatform — expert skill
+
+This is the foundational knowledge layer for KMP/CMP work. For presentation
+architecture, see the companion `kmp-mvvm` and `kmp-mvi-flowredux` skills — this
+skill covers everything beneath them: structure, source sets, interop, and the stack.
+
+References:
+- https://kotlinlang.org/docs/multiplatform/multiplatform-discover-project.html
+- https://kotlinlang.org/docs/multiplatform/multiplatform-hierarchy.html
+- https://blog.jetbrains.com/kotlin/2026/05/new-kmp-default-structure/
+
+## KMP vs CMP — know which one you mean
+
+- **KMP (Kotlin Multiplatform)** — shares non-UI logic (networking, persistence,
+  business rules). You build the UI natively per platform (Compose on Android,
+  SwiftUI on iOS). Officially supported by Google for Android/iOS logic sharing.
+- **CMP (Compose Multiplatform)** — a declarative UI framework layered on top of KMP
+  that lets you share the UI too. On iOS it renders via Skia (Skiko), not native widgets.
+
+Decision rule: push as much as possible into `commonMain`. Use KMP-only when you need
+the deepest native iOS fidelity; use CMP when one UI codebase outweighs that.
+
+---
+
+## Compilation targets
+
+| Target | Compiler | Output |
+|---|---|---|
+| Android / JVM backend | Kotlin/JVM | JVM bytecode |
+| iOS / macOS / watchOS / tvOS / Linux / Windows | Kotlin/Native (LLVM) | Native binary / `.framework` |
+| Web | Kotlin/Wasm (or legacy Kotlin/JS) | WebAssembly / JS |
+
+Kotlin/Native produces standalone binaries with no VM, which is how KMP gets native
+performance on iOS.
+
+---
+
+## Project structure (JetBrains 2026 default)
+
+The default structure changed in 2026 to give each module a single responsibility,
+aligning with Android Gradle Plugin 9.0.
+
+```
+project-root/
+├── shared/          ← KMP library: ALL shared code (the only multiplatform module)
+│   └── src/
+│       ├── commonMain/      ← 80–90% of code lives here
+│       ├── androidMain/     ← Android actuals + JVM-only deps
+│       ├── iosMain/         ← iOS actuals (intermediate; see hierarchy below)
+│       ├── desktopMain/     ← JVM desktop actuals
+│       ├── wasmJsMain/      ← web actuals
+│       └── commonTest/
+├── androidApp/      ← thin Android entry point, depends on :shared
+├── iosApp/          ← Xcode project consuming the shared framework
+├── desktopApp/      ← JVM desktop entry point
+└── webApp/          ← Wasm/JS entry point
+```
+
+The old single `composeApp` module that mixed library + app concerns is replaced by a
+clean `shared` library plus separate `*App` modules. Generate new projects at
+`kmp.jetbrains.com`. Reference samples: `KMP-App-Template`, `kotlinconf-app`, RSS Reader.
+
+For large apps, modularize further: feature modules (`:feature-x`) each split into
+`domain`/`data`/`presentation`, plus shared `:core-network`, `:core-db`, `:core-ui`.
+
+---
+
+## Source set hierarchy — the mental model
+
+Source sets form a tree. During compilation for a target, Kotlin combines **all** source
+sets on the path from `commonMain` down to the platform leaf.
+
+```
+                 commonMain
+                /          \
+          appleMain       jvmAndroidShared (you create if needed)
+          /      \         /        \
+     iosMain   macosMain  androidMain  desktopMain
+     /    \
+iosArm64  iosSimulatorArm64
+```
+
+Key facts:
+- `commonMain` compiles to every target; code here may use only multiplatform APIs.
+- **Intermediate source sets** (`iosMain`, `appleMain`, `nativeMain`) share code among a
+  subset of targets. Put `actual` declarations in the intermediate set (e.g. `iosMain`),
+  not in each leaf (`iosArm64Main`, `iosSimulatorArm64Main`).
+- The **default hierarchy template** (modern Kotlin) auto-wires `nativeMain`, `appleMain`,
+  `iosMain`, etc. You rarely need manual `dependsOn` anymore.
+- Kotlin does **not** auto-share a JVM+Android source set. If their deps overlap, create a
+  custom intermediate set and wire it with `dependsOn` (IDE intellisense may complain but
+  it compiles).
+
+---
+
+## expect / actual — the platform contract
+
+The cornerstone mechanism. Declare an `expect` in `commonMain`; provide an `actual` per
+target (or per intermediate source set).
+
+```kotlin
+// commonMain
+expect fun getPlatform(): Platform
+interface Platform { val name: String }
+
+// androidMain
+actual fun getPlatform(): Platform = object : Platform {
+    override val name = "Android ${Build.VERSION.SDK_INT}"
+}
+
+// iosMain
+actual fun getPlatform(): Platform = object : Platform {
+    override val name = UIDevice.currentDevice.systemName()
+}
+```
+
+Three forms:
+1. `expect fun` / `actual fun` — functions (most common)
+2. `expect class` / `actual class` — full classes
+3. **Interface + expect factory** (recommended) — declare an `interface` in common, an
+   `expect fun buildX(): Interface` factory, and platform `actual` factories returning
+   platform impls. This keeps common code free of platform types and is easier to test.
+
+Prefer the interface+factory form over `expect class`; it avoids the strictness of
+matching every member signature across platforms.
+
+When NOT to use expect/actual: if a library already provides a multiplatform API (Ktor,
+SQLDelight, kotlinx-datetime), use it directly in `commonMain` — no expect/actual needed.
+
+---
+
+## The standard 2026 library stack
+
+Verify multiplatform support at `klibs.io` before adding any dependency.
+
+| Concern | Library | Notes |
+|---|---|---|
+| Networking | **Ktor client** | `commonMain` core + per-platform engine (OkHttp/Android, Darwin/iOS, CIO/desktop) |
+| Serialization | **kotlinx.serialization** | apply the plugin to the module that defines `@Serializable` types |
+| Persistence | **SQLDelight** (typed SQL) or **Room KMP** (Google, DAO-style) | SQLDelight for control; Room for Android-team familiarity |
+| Key-value | **multiplatform-settings** or **DataStore** | small prefs |
+| DI | **Koin** | no codegen → fast multiplatform compile; `koin-compose-viewmodel` for CMP |
+| Dates/time | **kotlinx-datetime** | multiplatform `Instant`, `LocalDate`, time zones |
+| Coroutines | **kotlinx-coroutines-core** | the concurrency backbone |
+| Image loading | **Coil 3** | multiplatform |
+| Navigation | Navigation-Compose (KMP), **Voyager**, or **Decompose** | Decompose pairs well with KMP lifecycle |
+| Testing | **kotlinx-coroutines-test** + **Turbine** | flow testing |
+
+---
+
+## Gradle configuration (modern, terse)
+
+```kotlin
+// shared/build.gradle.kts
+plugins {
+    kotlin("multiplatform")
+    kotlin("plugin.serialization")
+    id("com.android.library")
+}
+
+kotlin {
+    androidTarget()
+    iosX64(); iosArm64(); iosSimulatorArm64()
+    jvm("desktop")
+    wasmJs { browser() }
+
+    // Default hierarchy template auto-creates iosMain/appleMain/nativeMain.
+    sourceSets {
+        commonMain.dependencies {
+            implementation(libs.ktor.client.core)
+            implementation(libs.kotlinx.serialization.json)
+            implementation(libs.koin.core)
+            implementation(libs.kotlinx.coroutines.core)
+        }
+        androidMain.dependencies { implementation(libs.ktor.client.okhttp) }
+        iosMain.dependencies     { implementation(libs.ktor.client.darwin) }
+        getByName("desktopMain").dependencies { implementation(libs.ktor.client.cio) }
+        commonTest.dependencies  {
+            implementation(libs.turbine)
+            implementation(libs.kotlinx.coroutines.test)
+        }
+    }
+}
+```
+
+Use a `gradle/libs.versions.toml` version catalog for all dependency coordinates —
+it is the standard for keeping versions consistent across modules.
+
+---
+
+## iOS interop — the hard part
+
+Kotlin/Native exports through an Objective-C bridge, which is lossy: sealed classes lose
+exhaustiveness, `Int?` becomes a boxed `KotlinInt`, and `suspend` functions become
+completion-handler callbacks. Mitigations:
+
+| Tool | What it fixes |
+|---|---|
+| **SKIE** | Maps Kotlin `Flow` → Swift `AsyncSequence`, sealed classes → Swift enums with associated values, default args. Easy setup, less verbose. |
+| **KMP-NativeCoroutines** | Maps `suspend`/`Flow` to Swift `async/await`, Combine, or RxSwift with proper cancellation. The more battle-tested option. |
+| **KMP-ObservableViewModel** | Lets SwiftUI observe Kotlin ViewModels and handles the iOS lifecycle/store-owner boilerplate. |
+| **Swift Export (emerging)** | Direct Kotlin→Swift modules (suspend→async/await, sealed→enums) without the ObjC layer. Still experimental — don't build production architecture on it yet. |
+
+Practical rules:
+- Reduce the exported surface: mark internal code `internal`/`private` and enable
+  `explicitApi()` so you don't export everything by default.
+- Annotate the flows/suspend functions you expose with the chosen tool's annotation
+  (`@NativeCoroutines`, `@NativeCoroutinesState`).
+- iOS engineers should never see `KotlinInt` or completion handlers — that's a sign your
+  interop layer is missing.
+
+---
+
+## Common gotchas
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `@Serializable` compiles but crashes at runtime | serialization plugin not on the module defining the type | Apply `kotlin("plugin.serialization")` to that module |
+| IDE shows red but it compiles | IntelliSense lagging on intermediate source sets | Sync Gradle; the build is the source of truth |
+| Can't share code across JVM + Android | Kotlin doesn't auto-create that intermediate set | Create a custom source set with `dependsOn` |
+| iOS sees opaque classes, no exhaustive switch | Raw ObjC bridge without SKIE | Add SKIE or KMP-NativeCoroutines |
+| Slow Kotlin/Native builds | Native compilation is inherently slower than JVM | Use `embedAndSign`/`SKIE` caching; iterate on Android/desktop, verify on iOS less often |
+| `expect class` won't compile — member mismatch | strict signature matching across platforms | Switch to interface + `expect` factory function |
+| Coroutine on iOS never cancels | exposed raw `suspend` without interop annotation | Annotate with `@NativeCoroutines` for proper cancellation |
+| Android-only API leaked into commonMain | wrote `android.*` import in common code | Move it behind expect/actual or an interface |
+
+---
+
+## Build/run quick reference
+
+```bash
+./gradlew :shared:build                 # compile the shared library, all targets
+./gradlew :androidApp:installDebug      # build + install Android app
+./gradlew :desktopApp:run               # run desktop (JVM) app
+./gradlew :shared:iosSimulatorArm64Test # run iOS tests on simulator
+# iOS app itself is built/run from Xcode (iosApp project) consuming the framework
+```
+
+---
+
+## When advising on KMP/CMP work
+
+1. Default to putting code in `commonMain`; only drop to platform source sets when an API
+   genuinely differs. Reach for expect/actual last, libraries first.
+2. Check `klibs.io` for multiplatform support before suggesting any dependency.
+3. For UI: ask whether they want shared UI (CMP) or native UI (KMP-only) before scaffolding.
+4. For presentation logic, defer to the `kmp-mvvm` or `kmp-mvi-flowredux` skill.
+5. Always consider the iOS interop cost of anything exposed across the Swift boundary.