Release version management: single VERSION file as source of truth

- VERSION at repo root (0.1.2); bump it to cut a release
- App: generated AppVersion.kt (config-cache-safe Gradle task with
  VERSION as declared input) shown in Settings; sent to the gateway
  via X-Iris-App-Version header on the SSE open
- Gateway: reports its own version in hello.ack server_caps.app_version
  (read from the repo-root VERSION via the plugin symlink); stores the
  app's version in the device registry caps (merge, not overwrite, so
  an old app reconnecting without the header doesn't wipe it)
- Settings: app + gateway version rows, mismatch hint, and a best-effort
  Gitea latest-release check (ReleaseCheck) with an 'update available' hint
- Release workflow: reads VERSION from the repo (no manual input), with
  a guard against an empty file
- Docs: frames.schema.json + 04-wire-protocol.md updated for app_version

app/shared/build.gradle.kts

@@ -33,6 +33,48 @@ val sqldelightVersion = "2.3.2"
 val cameraxVersion = "1.5.1"
 val mlKitVersion = "16.1.1"
 
+// ── App version (generated) ─────────────────────────────────────────────
+// The repo-root VERSION file is the single source of truth (bump it to cut
+// a release; CI can still override with -PappVersion). Generate AppVersion.kt
+// into commonMain so both targets can display it in Settings and send it to
+// the gateway (X-Iris-App-Version header).
+//
+// A real task with the VERSION file as a DECLARED input: on a
+// configuration-cache hit the script body does not re-run, so only the task
+// (keyed on the file's content) can regenerate AppVersion.kt after a bump.
+// The doLast reads everything from the task's own inputs/outputs (which are
+// configuration-cache serializable) — it must not reference script-scope
+// vals, because a .kts script lambda captures the script object and the
+// configuration cache rejects that.
+val generatedVersionDir = layout.buildDirectory.dir("generated/app-version")
+val generateAppVersion by tasks.registering {
+    inputs.file(project.file("../../VERSION"))
+    inputs.property("appVersionOverride", (project.findProperty("appVersion") as? String).orEmpty())
+    val outFile = generatedVersionDir.map { it.file("AppVersion.kt") }
+    outputs.file(outFile)
+    doLast {
+        val override = inputs.properties["appVersionOverride"] as? String ?: ""
+        val versionFile = inputs.files.singleFile
+        val version =
+            override.ifBlank {
+                versionFile.takeIf { it.exists() }?.readText()?.trim() ?: "0.1.0"
+            }
+        val f = outFile.get().asFile
+        f.parentFile?.mkdirs()
+        f.writeText(
+            """
+            |package iris
+            |
+            |/** Generated from the repo-root VERSION file - do not edit. */
+            |object AppVersion {
+            |    const val VERSION = "$version"
+            |}
+            |
+            """.trimMargin(),
+        )
+    }
+}
+
 kotlin {
     android {
         namespace = "iris.shared"
@@ -53,6 +95,11 @@ kotlin {
     }
 
     sourceSets {
+        // AppVersion.kt is generated from the repo-root VERSION file (see
+        // generateAppVersion above) into commonMain so both targets can read it.
+        commonMain {
+            kotlin.srcDir(generatedVersionDir)
+        }
         // Both targets are JVM-based (androidTarget + jvm("desktop")), so
         // shared JVM code (File I/O, SHA-256, media cache) lives in jvmMain.
         val jvmMain by creating { dependsOn(commonMain.get()) }
@@ -138,3 +185,8 @@ sqldelight {
         }
     }
 }
+
+// Every Kotlin compile depends on the generated AppVersion.kt being current.
+tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
+    dependsOn(generateAppVersion)
+}

app/shared/src/commonMain/kotlin/iris/net/HttpGateway.kt

@@ -1,5 +1,6 @@
 package iris.net
 
+import iris.AppVersion
 import iris.media.Sha256
 import iris.media.isValidMediaId
 import iris.protocol.ErrorPayload
@@ -135,6 +136,9 @@ class HttpGateway(
         deviceName?.takeIf { it.isNotBlank() }?.let { b.add("X-Iris-Device-Name", it) }
         fcmToken()?.takeIf { !it.isNullOrBlank() }?.let { b.add("X-Iris-Fcm-Token", it) }
         ntfyTopic()?.takeIf { it.isNotBlank() }?.let { b.add("X-Iris-Ntfy-Topic", it) }
+        // Release version (repo-root VERSION baked in at build time); the
+        // gateway stores it in the device registry (docs/04 hello.ack note).
+        b.add("X-Iris-App-Version", AppVersion.VERSION)
         return b.build()
     }
 

app/shared/src/commonMain/kotlin/iris/net/ReleaseCheck.kt

@@ -0,0 +1,96 @@
+package iris.net
+
+import iris.protocol.IrisJson
+import iris.util.IrisLog
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.json.jsonPrimitive
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+
+/**
+ * Latest-release check (docs/04 hello.ack note): the repo is public on Gitea,
+ * so the app can ask for the newest release tag without any token. Settings
+ * shows "vX.Y.Z available" when the running build is older.
+ *
+ * Best-effort by design: any failure (offline, DNS, rate limit) just yields
+ * `null` — the check must never surface an error in the UI.
+ */
+object ReleaseCheck {
+    const val LATEST_RELEASE_URL =
+        "https://gitea.zephyre.one/api/v1/repos/ARIA/iris_x_hermes/releases/latest"
+
+    /**
+     * One shared client for the process lifetime: an OkHttpClient owns a
+     * thread pool and connection pool, so it must not be rebuilt per screen
+     * open (and never needs explicit shutdown — the pools idle out). Short
+     * timeouts so a black-holed network can't linger the LaunchedEffect.
+     */
+    private val client: OkHttpClient =
+        OkHttpClient
+            .Builder()
+            .connectTimeout(5, java.util.concurrent.TimeUnit.SECONDS)
+            .readTimeout(10, java.util.concurrent.TimeUnit.SECONDS)
+            .build()
+
+    /**
+     * The latest release version (tag without the leading "v"), or `null`
+     * when the check could not be performed.
+     */
+    suspend fun latestVersion(): String? =
+        withContext(Dispatchers.IO) {
+            val request =
+                Request
+                    .Builder()
+                    .url(LATEST_RELEASE_URL)
+                    .get()
+                    .build()
+            try {
+                client.newCall(request).execute().use { response: Response ->
+                    if (!response.isSuccessful) {
+                        IrisLog.d("ReleaseCheck: HTTP ${response.code}")
+                        return@withContext null
+                    }
+                    val body = response.body?.string() ?: return@withContext null
+                    val tag =
+                        IrisJson
+                            .instance
+                            .parseToJsonElement(body)
+                            .jsonObject
+                            .get("tag_name")
+                            ?.jsonPrimitive
+                            ?.content
+                            .orEmpty()
+                    tag.removePrefix("v").ifBlank { null }
+                }
+            } catch (e: Exception) {
+                IrisLog.d("ReleaseCheck: ${e.message}")
+                null
+            }
+        }
+
+    /**
+     * True when [latest] is a newer release than [running]. Numeric
+     * component-wise comparison (so "0.1.10" > "0.1.9"); anything that does
+     * not parse as dotted numbers is treated as "not newer" — the hint is
+     * best-effort and must never fire for dev builds ahead of the latest
+     * release.
+     */
+    fun isNewer(
+        latest: String,
+        running: String,
+    ): Boolean {
+        val a = latest.split('.').mapNotNull { it.takeWhile(Char::isDigit).toIntOrNull() }
+        val b = running.split('.').mapNotNull { it.takeWhile(Char::isDigit).toIntOrNull() }
+        if (a.isEmpty() || b.isEmpty()) return false
+        val n = maxOf(a.size, b.size)
+        for (i in 0 until n) {
+            val x = a.getOrElse(i) { 0 }
+            val y = b.getOrElse(i) { 0 }
+            if (x != y) return x > y
+        }
+        return false
+    }
+}

app/shared/src/commonMain/kotlin/iris/protocol/Protocol.kt

@@ -140,6 +140,8 @@ data class ServerCaps(
     val push: String = "fcm",
     @SerialName("push_ntfy_server") val pushNtfyServer: String = "",
     val pickers: Boolean = false,
+    /** Release version of the gateway plugin (repo-root VERSION file). */
+    @SerialName("app_version") val appVersion: String = "",
 )
 
 @Serializable

app/shared/src/commonMain/kotlin/iris/state/IrisController.kt

@@ -158,6 +158,15 @@ class IrisController(
     private val _gatewayStatus = MutableStateFlow<String?>(null)
     val gatewayStatus: StateFlow<String?> = _gatewayStatus.asStateFlow()
 
+    /**
+     * Release version of the connected gateway (hello.ack `server_caps.app_version`,
+     * the repo-root VERSION file). Empty when not connected or the gateway is
+     * old enough not to report it. Settings shows it next to the app version
+     * and hints when the two differ.
+     */
+    private val _gatewayVersion = MutableStateFlow("")
+    val gatewayVersion: StateFlow<String> = _gatewayVersion.asStateFlow()
+
     // ── M8: unread indicator ──────────────────────────────────────────────
 
     /** True while the current lane's newest content sits at the bottom of the
@@ -889,6 +898,11 @@ class IrisController(
                     // just close the in-flight turn's dangling tool cards /
                     // streaming bubble (nothing spins forever).
                     chat.finalizeInterrupted()
+                    // The gateway is gone — clear the advertised version so
+                    // Settings doesn't keep showing it (and the mismatch
+                    // hint) while disconnected (matches the KDoc: empty when
+                    // not connected).
+                    _gatewayVersion.value = ""
                 }
             }
         }
@@ -927,6 +941,7 @@ class IrisController(
      * refreshes (skipped on a plain reconnect via historyLoaded).
      */
     private fun onConnectedLane(connected: GatewayClient.State.Connected) {
+        _gatewayVersion.value = connected.caps.appVersion
         // Never wipe the directory with an empty list: the long-poll restore
         // path carries no channels when there was no prior SSE hello (lastAck
         // null), and the cached directory is still valid then.

app/shared/src/commonMain/kotlin/iris/ui/screens/SettingsScreen.kt

@@ -44,6 +44,8 @@ import androidx.compose.ui.layout.ContentScale
 import androidx.compose.ui.unit.Dp
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
+import iris.AppVersion
+import iris.net.ReleaseCheck
 import iris.platform.ImageFilePicker
 import iris.platform.decodeImageBytes
 import iris.platform.loadScaledImage
@@ -79,10 +81,18 @@ fun SettingsScreen(
     val runtimeFooterFields by controller.runtimeFooterFields.collectAsState()
     val toolDetail by controller.toolDetail.collectAsState()
     val fontSizeScale by controller.fontSizeScale.collectAsState()
+    val gatewayVersion by controller.gatewayVersion.collectAsState()
     val theme = LocalUserTheme.current
     var pickerTarget by remember { mutableStateOf<PickerTarget?>(null) }
     var showForgetConfirm by remember { mutableStateOf(false) }
 
+    // Best-effort latest-release check (docs/04): one query per screen open,
+    // failures stay silent (ReleaseCheck returns null).
+    var latestVersion by remember { mutableStateOf<String?>(null) }
+    LaunchedEffect(Unit) {
+        latestVersion = ReleaseCheck.latestVersion()
+    }
+
     Box(modifier = Modifier.fillMaxSize().background(theme.background)) {
         Column(
             modifier =
@@ -434,6 +444,19 @@ fun SettingsScreen(
                     Text("Forget pairing", fontSize = 12.sp)
                 }
             }
+
+            Text(
+                "About",
+                style = MaterialTheme.typography.titleSmall,
+                modifier = Modifier.padding(top = 12.dp, bottom = 4.dp),
+            )
+            SettingsCard {
+                VersionCard(
+                    appVersion = AppVersion.VERSION,
+                    gatewayVersion = gatewayVersion,
+                    latestVersion = latestVersion,
+                )
+            }
         }
 
         when (pickerTarget) {
@@ -534,6 +557,47 @@ private fun BackArrow(
     }
 }
 
+/**
+ * About card (docs/04 hello.ack note): app version (repo-root VERSION baked in
+ * at build time), the connected gateway's version (hello.ack
+ * `server_caps.app_version`), a mismatch hint, and the latest Gitea release
+ * when the running build is older.
+ */
+@Composable
+private fun VersionCard(
+    appVersion: String,
+    gatewayVersion: String,
+    latestVersion: String?,
+) {
+    Text("📦 Version", fontSize = 14.sp)
+    Text(
+        "Iris app v$appVersion",
+        fontSize = 12.sp,
+        color = IrisColors.textSecondary,
+    )
+    if (gatewayVersion.isNotBlank()) {
+        Text(
+            "Gateway v$gatewayVersion",
+            fontSize = 12.sp,
+            color = IrisColors.textSecondary,
+        )
+        if (gatewayVersion != appVersion) {
+            Text(
+                "App and gateway versions differ — update the other side to match.",
+                fontSize = 12.sp,
+                color = IrisColors.statusAmber,
+            )
+        }
+    }
+    latestVersion?.takeIf { ReleaseCheck.isNewer(it, appVersion) }?.let { latest ->
+        Text(
+            "New version v$latest available — see the Gitea releases page.",
+            fontSize = 12.sp,
+            color = IrisColors.statusAmber,
+        )
+    }
+}
+
 /** Settings row container (panel card). */
 @Composable
 private fun SettingsCard(content: @Composable () -> Unit) {