@damiangilgonzalez/harness 1.3.7

package/skills/kotlin-android/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: kotlin-android
+description: "Use when building or fixing a native Android app in Kotlin and Jetpack Compose on the UDF layered architecture — ViewModel/StateFlow, Hilt, Room, Retrofit, coroutines, type-safe Navigation, and the Gradle/AGP surface. NOT shared Android and iOS UI from one Kotlin codebase (that is `compose-multiplatform`)."
+tags: [kotlin, android, jetpack-compose, hilt, room, coroutines, mvvm, clean-architecture]
+recommends: [compose-multiplatform, spring-boot, java, testing-web, github-actions]
+origin: risco
+---
+
+# Native Android with Kotlin & Compose
+
+You build production native Android: **Kotlin + Jetpack Compose + the UDF layered
+architecture** (UI → domain → data). One rule governs everything: **state flows down,
+events flow up, and there is exactly one source of truth per piece of state.** Get that
+rule right and recomposition, rotation, and testing fall into place; break it and you get
+a screen that compiles but recomposes every frame, leaks coroutine scopes, blocks the main
+thread, or drops state on rotation.
+
+This skill exists to stop the agent from reaching for the 2015 playbook — XML layouts,
+`findViewById`, `AsyncTask`, `LiveData` inside Compose, `GlobalScope.launch`, `MutableState`
+exposed straight out of a `ViewModel`. Emit a buildable, idiomatic module, not a toy.
+
+## Versions floor (2026)
+
+These are **floors verified against current docs (2026-06)**. Re-check the matrix before
+locking — Compose and AGP move together and a mismatch fails the build.
+
+| Piece | Floor | Why it matters |
+|---|---|---|
+| Kotlin (KGP) | **2.2.x** | K2 compiler is default & Stable; KGP must align with AGP. |
+| AGP | **9.2+** when using Compose | Compose's compileSdk 37 requires AGP ≥ 9.2.0. |
+| compileSdk | **37** | Current Compose target. |
+| minSdk | **24** | Practical modern floor (~99% devices); Compose technically supports 21+. |
+| JDK (build) | **17** | Required by current AGP/Compose toolchain. |
+| Compose BOM | **2026.05.01** → Compose 1.11.2 | Pin artifacts via the BOM, never per-artifact versions. |
+| Navigation | **2.8+** | Type-safe `@Serializable` routes land here. |
+| Hilt + Room + Retrofit | current | DI / persistence / network. Wire Room & Hilt with **KSP, not kapt**. |
+| Serialization | kotlinx.serialization | Retrofit converter + Navigation route types. |
+
+## The architecture in one screen
+
+Three layers. Higher layers depend on lower; never the reverse.
+
+```text
+UI layer      Composable (stateless) ── reads ──> UiState
+                     │ events up                  ▲ state down
+              ViewModel exposes StateFlow<UiState> │
+                     │ calls
+domain layer  (optional) UseCase — only when logic spans repos or is reused
+                     │ calls
+data layer    Repository (interface in domain, impl here)
+                  ├── Room DAO  → Flow   (single source of truth)
+                  └── Retrofit  → suspend (refreshes the source of truth)
+```
+
+- **UI** is dumb: render `UiState`, send events. No business logic in a `@Composable`.
+- **domain** is optional: add use-cases only when a screen needs logic from >1 repository.
+- **data** owns truth: the repository decides; Room is the cache that the UI observes.
+
+Offline-first means **Room is the source of truth**. The network writes into Room; the UI
+observes Room's `Flow`. `WorkManager` does background sync. The UI never reads the network
+directly.
+
+## State & recomposition
+
+Each rule has a one-line reason.
+
+- **Hoist state.** A composable that owns mutable state can't be reused or previewed — pass
+  state in, send events out.
+- **`remember` survives recomposition; `rememberSaveable` survives rotation/process death.**
+  Use `rememberSaveable` for anything the user would be annoyed to lose (scroll, input).
+- **`derivedStateOf` for computed state** — recomputes only when its inputs change, not every
+  recomposition.
+- **`key()` / stable keys in `LazyColumn`** — without a stable item key, reorder/insert churns
+  the whole list.
+- **Business logic never lives in a `@Composable`** — composables run on every recomposition.
+
+```kotlin
+// Bad — logic + I/O in the composable; runs on every recomposition.
+@Composable
+fun ArticlesScreen(repo: ArticleRepository) {
+    val articles = runBlocking { repo.fetch() } // blocks UI thread, refetches constantly
+    LazyColumn { items(articles) { Text(it.title) } }
+}
+
+// Good — stateless UI driven by hoisted state; logic in the ViewModel.
+@Composable
+fun ArticlesScreen(state: ArticlesUiState, onRetry: () -> Unit) {
+    when (state) {
+        ArticlesUiState.Loading -> CircularProgressIndicator()
+        is ArticlesUiState.Error -> ErrorView(state.message, onRetry)
+        is ArticlesUiState.Success ->
+            LazyColumn { items(state.articles, key = { it.id }) { Text(it.title) } }
+    }
+}
+```
+
+## ViewModel + UI state
+
+Model the screen as a **sealed `UiState`** so impossible states (loading *and* error) can't
+exist. Expose it as `StateFlow`, never a mutable type.
+
+```kotlin
+sealed interface ArticlesUiState {
+    data object Loading : ArticlesUiState
+    data class Success(val articles: List<Article>) : ArticlesUiState
+    data class Error(val message: String) : ArticlesUiState
+}
+
+@HiltViewModel
+class ArticlesViewModel @Inject constructor(
+    repository: ArticleRepository,
+) : ViewModel() {
+    val uiState: StateFlow<ArticlesUiState> =
+        repository.observeArticles()
+            .map<List<Article>, ArticlesUiState> { ArticlesUiState.Success(it) }
+            .catch { emit(ArticlesUiState.Error(it.message ?: "Unknown error")) }
+            .stateIn(
+                scope = viewModelScope,
+                started = SharingStarted.WhileSubscribed(5_000),
+                initialValue = ArticlesUiState.Loading,
+            )
+}
+```
+
+Collect it lifecycle-aware so collection pauses below `STARTED` and you don't burn work
+off-screen:
+
+```kotlin
+@Composable
+fun ArticlesRoute(viewModel: ArticlesViewModel = hiltViewModel()) {
+    val state by viewModel.uiState.collectAsStateWithLifecycle()
+    ArticlesScreen(state = state, onRetry = viewModel::refresh)
+}
+```
+
+`WhileSubscribed(5_000)` keeps the flow alive 5s past the last collector so a rotation
+doesn't restart the upstream pipeline.
+
+## Data layer
+
+The repository interface lives in domain; its implementation lives in data. Retrofit uses
+`suspend` functions and a `@Serializable` DTO; Room DAOs return `Flow`. Errors surface as a
+sealed result, not raw exceptions thrown into the UI.
+
+```kotlin
+interface ArticleRepository {
+    fun observeArticles(): Flow<List<Article>>   // from Room — the source of truth
+    suspend fun refresh()                         // network -> Room
+}
+```
+
+The full wired example — DTO, entity, DAO, Retrofit service, repository impl, mappers,
+offline-first refresh — is in **[references/architecture.md](references/architecture.md)**.
+Read it before scaffolding a feature end-to-end.
+
+## DI with Hilt
+
+`@HiltAndroidApp` on the `Application`, `@Module @InstallIn(SingletonComponent::class)` for
+bindings, `@HiltViewModel` + `hiltViewModel()` for screens. Prefer **constructor injection**;
+reach for `@Provides`/`@Binds` only for interfaces and third-party types you don't own.
+
+Classic error: `MyRepo cannot be provided without an @Inject constructor`. Fix one of:
+either add `@Inject constructor(...)` to the concrete class, or `@Binds` the interface to its
+implementation inside an installed module. See **[references/gradle-setup.md](references/gradle-setup.md)**
+for the KSP wiring that makes Hilt generate.
+
+## Coroutines & Flow rules
+
+- **Never `GlobalScope.launch`** — it outlives every screen and leaks. Use `viewModelScope`
+  (UI logic) or a repository-scoped scope.
+- **Structured concurrency**: a cancelled parent cancels children — keep work inside a real
+  scope so navigation-away cancels it.
+- **Inject dispatchers** (`@IoDispatcher CoroutineDispatcher`) instead of hardcoding
+  `Dispatchers.IO` — otherwise the work isn't testable.
+- **`flowOn` to switch a flow's upstream context**, not `withContext` inside a `flow { }`
+  builder (which is a context-preservation violation).
+- **Cold `Flow` for streams, `StateFlow` for current-value state** — don't `collect` a cold
+  flow when the UI needs the latest value.
+
+## Navigation (type-safe)
+
+Since Navigation 2.8, routes are `@Serializable` types — the compiler checks your args.
+
+```kotlin
+@Serializable data object ArticleList
+@Serializable data class ArticleDetail(val id: String)
+
+NavHost(navController, startDestination = ArticleList) {
+    composable<ArticleList> {
+        ArticlesRoute(onOpen = { navController.navigate(ArticleDetail(it)) })
+    }
+    composable<ArticleDetail> { backStackEntry ->
+        val args = backStackEntry.toRoute<ArticleDetail>()
+        ArticleDetailRoute(id = args.id)
+    }
+}
+```
+
+No string routes, no manual `arguments = listOf(navArgument(...))`, no fragile key parsing.
+
+## Build & verify
+
+```bash
+./gradlew :app:assembleDebug lintDebug testDebugUnitTest
+```
+
+`assembleDebug` proves it builds, `lintDebug` catches Android lint, `testDebugUnitTest` runs
+JVM unit tests. For a fast, **SDK-free** static gate over the Kotlin/Gradle you just wrote,
+run `scripts/verify.sh` — it greps for banned patterns and missing modern ones without
+touching the Android SDK, so it works in CI or a bare checkout.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+|---|---|---|
+| XML layouts + `findViewById` | Stale; no compile-time view safety; doesn't compose | Jetpack Compose `@Composable` |
+| `LiveData` collected in a Composable | Lifecycle mismatch, extra dependency, not Compose-native | `StateFlow` + `collectAsStateWithLifecycle()` |
+| `GlobalScope.launch` | Leaks; outlives the screen; uncancellable | `viewModelScope` / scoped coroutine |
+| `runBlocking` / network call on the main thread | ANR, frozen UI | `suspend` on an injected dispatcher |
+| Business logic in a `@Composable` | Runs every recomposition; untestable | Move to ViewModel / use-case |
+| `MutableStateFlow`/`mutableStateOf` exposed publicly | UI can mutate state; breaks single source of truth | private mutable backing + public `asStateFlow()`/`StateFlow` |
+| God-Activity holding all state | Untestable, rotation-fragile | One ViewModel per screen, hoisted state |
+| `kapt` for Room/Hilt | Slow, legacy; K2-incompatible edge cases | **KSP** |
+| `collectAsState()` in Compose | Keeps collecting off-screen, wastes work | `collectAsStateWithLifecycle()` |
+| Reading the network directly in the repository's read path | No offline; UI flickers on every fetch | Room as source of truth; network refreshes it |
+
+## When this is the wrong skill
+
+- **Shared UI across Android + iOS + desktop from one Kotlin codebase** — the moment
+  `commonMain`, `expect/actual`, or an iOS target appears, use
+  [../compose-multiplatform/SKILL.md](../compose-multiplatform/SKILL.md).
+- **Server-side Kotlin / JVM web backend** the app talks to → [../spring-boot/SKILL.md](../spring-boot/SKILL.md).
+- **Pure Kotlin/JVM language questions, no Android** → [../java/SKILL.md](../java/SKILL.md) is the
+  nearest JVM-language sibling (there is no standalone `kotlin` language skill).
+- **iOS/SwiftUI** → `swift-ios`. **Dart cross-platform** → [../flutter/SKILL.md](../flutter/SKILL.md).
+  **React Native** → `react-native`.
+- **CI for `assembleDebug`/tests** → `github-actions`.
+
+## References
+
+- [references/architecture.md](references/architecture.md) — end-to-end wired feature
+  (UiState + ViewModel + Repository + Room + Retrofit + Hilt), complete file contents.
+- [references/gradle-setup.md](references/gradle-setup.md) — `libs.versions.toml`, root +
+  module `build.gradle.kts`, the Compose Kotlin plugin, Hilt/KSP wiring, and common
+  Gradle/build error fixes.

package/skills/kotlin-android/evals/README.md

@@ -0,0 +1,13 @@
+# Evals — kotlin-android
+
+These cases are a judgment aid, not automated CI. Run them through the repo's eval harness, or
+read them by hand: feed each `should_trigger` prompt to an agent that has this skill's
+description loaded and confirm it engages (especially the non-obvious recomposition/rotation
+and the Spanish StateFlow phrasings); feed each `should_not_trigger` prompt and confirm the
+agent stays out and routes to the named sibling (`compose-multiplatform`, `swift-ios`,
+`spring-boot`, `react-native`, `flutter`). For the `capability` case, have the agent implement
+the article-list feature and grade the output against the `must_include` rubric — every bullet
+should be present (sealed UiState as StateFlow from a @HiltViewModel, lifecycle-aware
+collection, Room-as-source-of-truth + Retrofit refresh, scoped coroutines, modern toolchain
+floors, no XML/LiveData/kapt). A miss is a signal to tighten the SKILL.md body or description,
+not a hard failure.

package/skills/kotlin-android/evals/cases.yaml

@@ -0,0 +1,56 @@
+skill: kotlin-android
+
+should_trigger:
+  - prompt: "Build an Android screen in Jetpack Compose backed by a ViewModel that loads a list."
+    why: "Core greenfield: Compose screen + ViewModel + UI state is exactly what this skill owns."
+
+  - prompt: "My Compose screen recomposes on every frame and loses its scroll position when I rotate the phone."
+    why: "Non-obvious symptom phrasing — recomposition churn + rotation state loss map to the state/recomposition rules (rememberSaveable, derivedStateOf, hoisting)."
+
+  - prompt: "Wire Hilt, Room and Retrofit together in a clean-architecture Android module with offline-first caching."
+    why: "Full-stack data layer + DI; skill prescribes repository over Room (source of truth) + Retrofit suspend + Hilt KSP."
+
+  - prompt: "¿Cómo expongo el estado del ViewModel a la UI con StateFlow en Compose sin que se pierda al rotar?"
+    why: "Spanish trigger naming StateFlow + ViewModel + Compose; expects StateFlow + collectAsStateWithLifecycle + stateIn(WhileSubscribed)."
+
+  - prompt: "Set up build.gradle.kts with the Compose compiler plugin and a version catalog for a new app."
+    why: "Non-obvious toolchain trigger — the Compose plugin (not composeOptions), libs.versions.toml, AGP/Kotlin/compileSdk floors live here."
+
+  - prompt: "How do I do type-safe navigation between Compose screens and pass an id argument?"
+    why: "Navigation 2.8 @Serializable route objects/classes with composable<Route> and toRoute() — explicitly covered."
+
+  - prompt: "Should I use kapt or KSP for Room and Hilt, and why is my annotation processing so slow?"
+    why: "Non-obvious build-hygiene trigger; the skill mandates KSP over kapt and explains the slowdown."
+
+should_not_trigger:
+  - prompt: "Share one Compose UI across Android and iOS from a single Kotlin module with expect/actual."
+    route_to: compose-multiplatform
+    why: "The moment commonMain/expect/actual/an iOS target appears it is Compose Multiplatform, not single-platform Android."
+
+  - prompt: "Build the same screen in SwiftUI for iOS."
+    route_to: swift-ios
+    why: "iOS native UI — a different platform and language entirely."
+
+  - prompt: "Create a Kotlin REST API with Spring Boot that the mobile app will call."
+    route_to: spring-boot
+    why: "Server-side Kotlin/JVM backend, not an Android client."
+
+  - prompt: "Build this mobile app in React Native instead."
+    route_to: react-native
+    why: "Different stack (JS/TS + RN), not native Kotlin/Compose."
+
+  - prompt: "Cross-platform mobile UI with Flutter and Dart."
+    route_to: flutter
+    why: "Dart + Flutter widget tree, not Kotlin/Android."
+
+capability:
+  - scenario: >
+      Implement a 'list of articles' feature for an Android app: offline-first, fetched from a
+      REST API, cached locally, and shown in a Compose list with loading and error states.
+    must_include:
+      - "Sealed UiState (Loading/Success/Error) exposed as a StateFlow from a @HiltViewModel."
+      - "Composable collects state with collectAsStateWithLifecycle() and is stateless (state in, events out)."
+      - "Repository observes Room (Flow, single source of truth); Retrofit refresh uses suspend and writes into Room."
+      - "Coroutines run in viewModelScope or an injected dispatcher; no GlobalScope."
+      - "Modern toolchain mentioned or in gradle: Compose BOM 2026.05.01, Kotlin 2.2.x, AGP 9.2+, compileSdk 37, minSdk 24, JDK 17."
+      - "No XML layouts, no findViewById, no LiveData in Compose; Room/Hilt wired with KSP not kapt."

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

@@ -0,0 +1,200 @@
+# End-to-end wired feature: offline-first article list
+
+A complete, compilable feature that follows the UDF layered architecture. Package layout is
+**package-by-feature**; the data layer is the source of truth (Room), refreshed from the
+network (Retrofit). Adapt names; keep the shape.
+
+```text
+com.example.app
+├── App.kt                         // @HiltAndroidApp
+├── core
+│   ├── di/DispatchersModule.kt    // @IoDispatcher qualifier + binding
+│   └── result/AppError.kt         // sealed error type
+└── feature/articles
+    ├── data
+    │   ├── ArticleApi.kt          // Retrofit suspend service
+    │   ├── ArticleDao.kt          // Room DAO -> Flow
+    │   ├── ArticleEntity.kt       // Room @Entity
+    │   ├── ArticleDto.kt          // @Serializable wire model
+    │   ├── ArticleRepositoryImpl.kt
+    │   └── ArticlesDataModule.kt  // Hilt module
+    ├── domain
+    │   ├── Article.kt             // domain model
+    │   └── ArticleRepository.kt   // interface
+    └── ui
+        ├── ArticlesUiState.kt
+        ├── ArticlesViewModel.kt
+        └── ArticlesScreen.kt
+```
+
+## Domain
+
+```kotlin
+// domain/Article.kt
+data class Article(val id: String, val title: String, val body: String)
+
+// domain/ArticleRepository.kt
+interface ArticleRepository {
+    fun observeArticles(): Flow<List<Article>>
+    suspend fun refresh()
+}
+```
+
+## Data
+
+```kotlin
+// data/ArticleDto.kt
+@Serializable
+data class ArticleDto(
+    val id: String,
+    val title: String,
+    val body: String,
+)
+
+// data/ArticleApi.kt
+interface ArticleApi {
+    @GET("articles")
+    suspend fun getArticles(): List<ArticleDto>
+}
+
+// data/ArticleEntity.kt
+@Entity(tableName = "articles")
+data class ArticleEntity(
+    @PrimaryKey val id: String,
+    val title: String,
+    val body: String,
+)
+
+// data/ArticleDao.kt
+@Dao
+interface ArticleDao {
+    @Query("SELECT * FROM articles ORDER BY title")
+    fun observeAll(): Flow<List<ArticleEntity>>   // source of truth
+
+    @Upsert
+    suspend fun upsertAll(entities: List<ArticleEntity>)
+}
+```
+
+```kotlin
+// data/ArticleRepositoryImpl.kt
+class ArticleRepositoryImpl @Inject constructor(
+    private val api: ArticleApi,
+    private val dao: ArticleDao,
+    @IoDispatcher private val io: CoroutineDispatcher,
+) : ArticleRepository {
+
+    // UI observes Room only — never the network directly.
+    override fun observeArticles(): Flow<List<Article>> =
+        dao.observeAll().map { rows -> rows.map { it.toDomain() } }
+
+    // Network writes into Room; the Flow above re-emits automatically.
+    override suspend fun refresh() = withContext(io) {
+        val remote = api.getArticles()
+        dao.upsertAll(remote.map { it.toEntity() })
+    }
+}
+
+private fun ArticleEntity.toDomain() = Article(id, title, body)
+private fun ArticleDto.toEntity() = ArticleEntity(id, title, body)
+```
+
+## DI
+
+```kotlin
+// App.kt
+@HiltAndroidApp
+class App : Application()
+
+// core/di/DispatchersModule.kt
+@Qualifier @Retention(AnnotationRetention.BINARY)
+annotation class IoDispatcher
+
+@Module
+@InstallIn(SingletonComponent::class)
+object DispatchersModule {
+    @Provides @IoDispatcher
+    fun provideIo(): CoroutineDispatcher = Dispatchers.IO
+}
+
+// feature/articles/data/ArticlesDataModule.kt
+@Module
+@InstallIn(SingletonComponent::class)
+abstract class ArticlesDataModule {
+    @Binds
+    abstract fun bindRepository(impl: ArticleRepositoryImpl): ArticleRepository
+}
+```
+
+Provide `ArticleApi`, the Room `Database`, and `ArticleDao` from `@Provides` functions in a
+network/database module (Retrofit builder with the kotlinx.serialization converter; the Room
+`databaseBuilder`). Both are `@Singleton`.
+
+## UI
+
+```kotlin
+// ui/ArticlesUiState.kt
+sealed interface ArticlesUiState {
+    data object Loading : ArticlesUiState
+    data class Success(val articles: List<Article>) : ArticlesUiState
+    data class Error(val message: String) : ArticlesUiState
+}
+
+// ui/ArticlesViewModel.kt
+@HiltViewModel
+class ArticlesViewModel @Inject constructor(
+    private val repository: ArticleRepository,
+) : ViewModel() {
+
+    val uiState: StateFlow<ArticlesUiState> =
+        repository.observeArticles()
+            .map<List<Article>, ArticlesUiState> { ArticlesUiState.Success(it) }
+            .catch { emit(ArticlesUiState.Error(it.message ?: "Unknown error")) }
+            .stateIn(
+                scope = viewModelScope,
+                started = SharingStarted.WhileSubscribed(5_000),
+                initialValue = ArticlesUiState.Loading,
+            )
+
+    init { refresh() }
+
+    fun refresh() = viewModelScope.launch {
+        runCatching { repository.refresh() }   // failure surfaces via the catch above
+    }
+}
+```
+
+```kotlin
+// ui/ArticlesScreen.kt
+@Composable
+fun ArticlesRoute(viewModel: ArticlesViewModel = hiltViewModel()) {
+    val state by viewModel.uiState.collectAsStateWithLifecycle()
+    ArticlesScreen(state = state, onRetry = viewModel::refresh)
+}
+
+@Composable
+fun ArticlesScreen(state: ArticlesUiState, onRetry: () -> Unit) {
+    when (state) {
+        ArticlesUiState.Loading -> Box(Modifier.fillMaxSize(), Alignment.Center) {
+            CircularProgressIndicator()
+        }
+        is ArticlesUiState.Error -> Column {
+            Text(state.message)
+            Button(onClick = onRetry) { Text("Retry") }
+        }
+        is ArticlesUiState.Success -> LazyColumn {
+            items(state.articles, key = { it.id }) { article ->
+                ListItem(headlineContent = { Text(article.title) })
+            }
+        }
+    }
+}
+```
+
+## Why this shape
+
+- **Room is the single source of truth.** `refresh()` writes the network result into Room;
+  `observeArticles()` re-emits, so the UI updates without the ViewModel mediating data twice.
+- **The Composable is stateless and previewable** — it takes `state` + `onRetry`, nothing else.
+- **No leak path**: all coroutines live in `viewModelScope`; navigating away cancels them.
+- **Testable**: inject a fake `ArticleRepository`; inject `@IoDispatcher` as a test dispatcher.

package/skills/kotlin-android/references/gradle-setup.md

@@ -0,0 +1,125 @@
+# Gradle setup: version catalog, build scripts, KSP, common fixes
+
+Targets the 2026 floors from SKILL.md. **Verify the AGP ↔ KGP ↔ compileSdk matrix against
+current docs before locking** — a mismatch fails the build with a confusing message.
+
+## Version catalog — `gradle/libs.versions.toml`
+
+```toml
+[versions]
+agp = "9.2.0"                 # >= 9.2 required when using Compose (compileSdk 37)
+kotlin = "2.2.20"             # K2 default & Stable
+ksp = "2.2.20-2.0.0"          # KSP version trails the Kotlin version
+composeBom = "2026.05.01"     # -> Compose 1.11.2
+navigation = "2.8.0"          # type-safe @Serializable routes
+hilt = "2.52"
+room = "2.7.0"
+retrofit = "2.11.0"
+kotlinxSerialization = "1.7.3"
+lifecycle = "2.8.7"           # lifecycle-runtime-compose -> collectAsStateWithLifecycle
+
+[libraries]
+compose-bom = { module = "androidx.compose:compose-bom", version.ref = "composeBom" }
+compose-ui = { module = "androidx.compose.ui:ui" }
+compose-material3 = { module = "androidx.compose.material3:material3" }
+lifecycle-runtime-compose = { module = "androidx.lifecycle:lifecycle-runtime-compose", version.ref = "lifecycle" }
+lifecycle-viewmodel-compose = { module = "androidx.lifecycle:lifecycle-viewmodel-compose", version.ref = "lifecycle" }
+navigation-compose = { module = "androidx.navigation:navigation-compose", version.ref = "navigation" }
+hilt-android = { module = "com.google.dagger:hilt-android", version.ref = "hilt" }
+hilt-compiler = { module = "com.google.dagger:hilt-compiler", version.ref = "hilt" }
+hilt-navigation-compose = { module = "androidx.hilt:hilt-navigation-compose", version = "1.2.0" }
+room-runtime = { module = "androidx.room:room-runtime", version.ref = "room" }
+room-ktx = { module = "androidx.room:room-ktx", version.ref = "room" }
+room-compiler = { module = "androidx.room:room-compiler", version.ref = "room" }
+retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
+retrofit-kotlinx-serialization = { module = "com.squareup.retrofit2:converter-kotlinx-serialization", version.ref = "retrofit" }
+kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinxSerialization" }
+
+[plugins]
+android-application = { id = "com.android.application", version.ref = "agp" }
+kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
+kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }   # the Compose compiler plugin
+kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
+hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
+```
+
+The Compose compiler is now the **Kotlin Compose plugin** (`org.jetbrains.kotlin.plugin.compose`),
+not the old `composeOptions { kotlinCompilerExtensionVersion = ... }` block. The plugin version
+tracks the Kotlin version automatically.
+
+## Root `build.gradle.kts`
+
+```kotlin
+plugins {
+    alias(libs.plugins.android.application) apply false
+    alias(libs.plugins.kotlin.android) apply false
+    alias(libs.plugins.kotlin.compose) apply false
+    alias(libs.plugins.kotlin.serialization) apply false
+    alias(libs.plugins.ksp) apply false
+    alias(libs.plugins.hilt) apply false
+}
+```
+
+## Module `app/build.gradle.kts`
+
+```kotlin
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.kotlin.compose)        // Compose compiler — replaces composeOptions
+    alias(libs.plugins.kotlin.serialization)
+    alias(libs.plugins.ksp)                    // KSP, never kapt, for Room + Hilt
+    alias(libs.plugins.hilt)
+}
+
+android {
+    namespace = "com.example.app"
+    compileSdk = 37
+
+    defaultConfig {
+        applicationId = "com.example.app"
+        minSdk = 24
+        targetSdk = 37
+    }
+    buildFeatures { compose = true }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+    kotlin { jvmToolchain(17) }
+}
+
+dependencies {
+    implementation(platform(libs.compose.bom))   // BOM pins every Compose artifact
+    implementation(libs.compose.ui)
+    implementation(libs.compose.material3)
+    implementation(libs.lifecycle.runtime.compose)
+    implementation(libs.lifecycle.viewmodel.compose)
+    implementation(libs.navigation.compose)
+
+    implementation(libs.hilt.android)
+    ksp(libs.hilt.compiler)                       // KSP, not kapt
+    implementation(libs.hilt.navigation.compose)
+
+    implementation(libs.room.runtime)
+    implementation(libs.room.ktx)
+    ksp(libs.room.compiler)                       // KSP, not kapt
+
+    implementation(libs.retrofit)
+    implementation(libs.retrofit.kotlinx.serialization)
+    implementation(libs.kotlinx.serialization.json)
+}
+```
+
+## Common build errors and the fix
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `This version of the Compose Compiler requires Kotlin ...` | Old `composeOptions` block pinning a compiler version | Delete `composeOptions`; apply `kotlin.plugin.compose`; the version follows Kotlin. |
+| `The Android Gradle plugin supports only Kotlin Gradle plugin version X+` | AGP ↔ KGP mismatch | Align both per the AGP/Kotlin compatibility matrix; bump the lower one. |
+| `Schema export directory is not provided` / slow incremental builds | Using `kapt` for Room/Hilt | Switch to KSP (`ksp(...)` + `id("com.google.devtools.ksp")`). |
+| `Serializer for class 'X' is not found` | Missing serialization plugin or `@Serializable` | Apply `kotlin.plugin.serialization`; annotate the DTO/route. |
+| `MyRepo cannot be provided without an @Inject constructor` | Hilt can't construct the type | Add `@Inject constructor(...)` to the concrete class, or `@Binds` the interface to its impl in an `@InstallIn` module. |
+| `compileSdk 37` rejected | AGP below 9.2 | Bump AGP to ≥ 9.2.0. |
+| Build runs on JDK 11/21 and fails | Wrong toolchain | Pin `jvmToolchain(17)` and `JavaVersion.VERSION_17`. |