@@ -35,6 +35,11 @@ All notable changes to CallShield will be documented in this file.
   before it would have failed on October 12. None of the 93 reports reached the
   publishing threshold, so the database (version 52) gained no new numbers and
   366 numbers wait for more reporters.
+- Home shows a card when a newer CallShield release is out, with a link to its
+  release page. The notice is a signed file that syncs with the spam database
+  every six hours, so it needs no extra server and nothing unsigned can fake
+  it. Hide it and it stays hidden until the next release. The optional weekly
+  update check in Settings works as before.
 
 ## v1.10.0 (2026-09-28)
 
 
@@ -12,7 +12,7 @@
 <p align="center">
   <a href="https://github.com/SysAdminDoc/CallShield/releases/latest"><img src="https://img.shields.io/github/v/release/SysAdminDoc/CallShield?style=flat-square&color=a6e3a1" alt="Release"></a>
   <img src="https://img.shields.io/badge/Spam%20Numbers-51%2C363-f38ba8?style=flat-square" alt="51,363 Numbers">
-  <img src="https://img.shields.io/badge/JVM%20unit%20tests-1654-94e2d5?style=flat-square" alt="1654 JVM unit tests">
+  <img src="https://img.shields.io/badge/JVM%20unit%20tests-1661-94e2d5?style=flat-square" alt="1661 JVM unit tests">
   <img src="https://img.shields.io/badge/Android-10%2B-89b4fa?style=flat-square" alt="Android 10+">
   <img src="https://img.shields.io/badge/License-MIT-cba6f7?style=flat-square" alt="MIT License">
   <img src="https://img.shields.io/badge/API%20Keys-None-fab387?style=flat-square" alt="No required API keys">
@@ -283,7 +283,7 @@ by locale and message type without shipping personal data:
 - Protection test validates all layers and permissions, including checker errors and deadline cutoffs
 - Rules surface priority conflicts after sync and edits, with the winning rule and a review path
 - Home leads with localized blocked-call/text outcomes and collapses completed setup into a review row
-- Optional weekly GitHub Releases update checks are off by default and only offer release/SHA256 links
+- Home shows a card when a newer release is out, read from a signed file that syncs with the spam database, so no extra host is contacted. Optional weekly GitHub Releases update checks are off by default and only offer release/SHA256 links
 - Maintainer data regeneration uses the gated `scripts/import_all_sources.py` pipeline. Legacy direct writers aren't supported
 - Onboarding wizard with permission requests
 
@@ -380,7 +380,7 @@ scrape Nomorobo's restricted carrier feed.
 ## Privacy
 
 Call and message decisions run on the phone. No personal data is collected. CallShield makes these network requests:
-- The spam database and trending feeds, from this public repository on GitHub, or from the feed mirror if you set one
+- The spam database, trending feeds and the new-release notice, from this public repository on GitHub, or from the feed mirror if you set one
 - Live caller enrichment, which is off by default and runs only for locally suspicious calls. The setting names every destination host before a number is shared
 - Community reports to the Cloudflare Worker. Each report is committed as a public JSON file to this repository's `data/reports` folder, and the next merge folds it into the database. It holds the reported number, the report type and time, the report's random id, and two reporter IDs that change every day (keyed HMACs of your network's /48 and /64, so the same network can't be linked across days or turned back into an address). An SMS report adds the linked domains and link labels, never message text. The report never holds your IP address. To stop floods and repeat reports, the Worker's short-lived store keys a duplicate check on your IPv4 address or IPv6 /64 for five minutes, and when Cloudflare's rate limiter is unavailable its fallback counter does the same for one minute. Both expire on their own
 - Local spam-domain checks don't disclose SMS or RCS links. Optional PhishTank lookups send only the site's base domain, and the OpenPhish feed is downloaded for local matching. Neither receives message text
@@ -509,12 +509,12 @@ RELEASE_KEY_PASSWORD=...
 ## Testing
 
 ```bash
-./gradlew testDebugUnitTest   # 1654 tests
+./gradlew testDebugUnitTest   # 1661 tests
 ./gradlew connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=com.sysadmindoc.callshield.platform.TargetSdkBehaviorSmokeTest
 ./gradlew verifyPipelineTests # Cloudflare Worker (node) + data-pipeline and translation checks (python)
 ```
 
-The suite is **1654 total JVM unit tests**, run with Robolectric wherever a screen, a service or the database is involved.
+The suite is **1661 total JVM unit tests**, run with Robolectric wherever a screen, a service or the database is involved.
 
 Two GitHub workflows run without building the app. **Validation** runs the Worker and
 pipeline suites on every push except report-only ones (`run-pipeline-tests.ps1 -CorrectnessOnly`),
@@ -551,7 +551,7 @@ language in [issue #7](https://github.com/SysAdminDoc/CallShield/issues/7).
 | Community API | Cloudflare Workers |
 | URL Safety | Local spam-domain data, with optional PhishTank and OpenPhish |
 | Verification | Local Gradle, lint, and release-artifact checks |
-| Tests | 1654 JVM unit tests (JUnit) |
+| Tests | 1661 JVM unit tests (JUnit) |
 | Strings | 1708 string resources and 38 plural groups (translation-ready) |
 | Accessibility | 100+ content descriptions, 48dp touch targets |
 | Min SDK | 29 (Android 10) |
 
@@ -296,6 +296,13 @@ class SpamRepository(
         /** Set once stored rows carry the latest-evidence expiry; see SyncRepository.applyLatestEvidenceExpiryRule. */
         internal val KEY_EVIDENCE_EXPIRY_RULE_APPLIED = booleanPreferencesKey("evidence_expiry_rule_applied")
         val KEY_APP_UPDATE_CHECKS = booleanPreferencesKey("app_update_checks_enabled")
+
+        /** The newest release the signed feed announced, and the one Home's card was last dismissed for. */
+        internal val KEY_RELEASE_NOTICE_CODE = intPreferencesKey("release_notice_version_code")
+        internal val KEY_RELEASE_NOTICE_NAME = stringPreferencesKey("release_notice_version_name")
+        internal val KEY_RELEASE_NOTICE_URL = stringPreferencesKey("release_notice_url")
+        internal val KEY_RELEASE_NOTICE_SHA256 = stringPreferencesKey("release_notice_apk_sha256")
+        internal val KEY_RELEASE_NOTICE_DISMISSED = intPreferencesKey("release_notice_dismissed_code")
         internal val KEY_APP_UPDATE_STATUS = stringPreferencesKey("app_update_status")
         internal val KEY_APP_UPDATE_TAG = stringPreferencesKey("app_update_latest_tag")
         internal val KEY_APP_UPDATE_RELEASE_URL = stringPreferencesKey("app_update_release_url")
@@ -552,6 +559,13 @@ class SpamRepository(
 
     suspend fun clearEndedExpectingCall(now: Long) = settingsRepository.clearEndedExpectingCall(now)
 
+    /** The release Home offers, or null when this build is current or the user dismissed it. */
+    val appReleaseNotice: Flow<AppReleaseNotice?> = settingsRepository.appReleaseNotice()
+
+    suspend fun refreshAppReleaseNotice(): Boolean = syncRepository.refreshAppReleaseNotice()
+
+    suspend fun dismissAppReleaseNotice(versionCode: Int) = settingsRepository.dismissAppReleaseNotice(versionCode)
+
     suspend fun togglePushAlertPackage(
         pkg: String,
         allowed: Boolean,
 
@@ -0,0 +1,20 @@
+package com.sysadmindoc.callshield.data.model
+
+/**
+ * The newest release, from the signed `data/app_release.json` that the
+ * six-hour sync downloads with the other feeds. `scripts/write_app_release.py`
+ * writes it at release time. Home offers it while it's newer than the
+ * installed build and not dismissed.
+ */
+data class AppReleaseNotice(
+    val versionCode: Int,
+    val versionName: String,
+    val releaseUrl: String,
+    val apkSha256: String,
+) {
+    /** Whether Home offers this release to a build of [installedCode] that last dismissed [dismissedCode]. */
+    fun shouldShow(
+        installedCode: Int,
+        dismissedCode: Int,
+    ): Boolean = versionCode > installedCode && versionCode != dismissedCode
+}
@@ -2,10 +2,12 @@ package com.sysadmindoc.callshield.data.remote
 
 import android.content.Context
 import com.squareup.moshi.Json
+import com.squareup.moshi.JsonDataException
 import com.squareup.moshi.Moshi
 import com.squareup.moshi.Types
 import com.squareup.moshi.kotlin.reflect.KotlinJsonAdapterFactory
 import com.sysadmindoc.callshield.data.AppUpdateRelease
+import com.sysadmindoc.callshield.data.model.AppReleaseNotice
 import com.sysadmindoc.callshield.data.model.HotNumber
 import com.sysadmindoc.callshield.data.model.SpamDatabase
 import com.sysadmindoc.callshield.data.model.SpamDatabaseShard
@@ -35,6 +37,14 @@ internal enum class GitHubFeedFailureReason {
     SIGNATURE,
 }
 
+/** `data/app_release.json` as published; every field is checked before use. */
+internal data class AppReleaseJson(
+    @param:Json(name = "version_code") val versionCode: Int? = null,
+    @param:Json(name = "version_name") val versionName: String? = null,
+    @param:Json(name = "release_url") val releaseUrl: String? = null,
+    @param:Json(name = "apk_sha256") val apkSha256: String? = null,
+)
+
 internal class GitHubFeedValidationException(
     val reason: GitHubFeedFailureReason,
     message: String,
@@ -177,6 +187,7 @@ class GitHubDataSource internal constructor(
         const val HOT_RANGES_PATH = "data/hot_ranges.json"
         const val SPAM_DOMAINS_PATH = "data/spam_domains.json"
         const val MODEL_WEIGHTS_PATH = "data/spam_model_weights.json"
+        const val APP_RELEASE_PATH = "data/app_release.json"
 
         const val BUNDLED_DATABASE_ASSET = "spam_numbers.json"
         const val BUNDLED_SHARD_MANIFEST_ASSET = "spam_numbers.manifest.json"
@@ -191,6 +202,7 @@ class GitHubDataSource internal constructor(
         internal const val MAX_HOT_LIST_BYTES = 1L * 1024L * 1024L
         internal const val MAX_HOT_RANGES_BYTES = 512L * 1024L
         internal const val MAX_SPAM_DOMAINS_BYTES = 2L * 1024L * 1024L
+        internal const val MAX_APP_RELEASE_BYTES = 4L * 1024L
         internal const val MAX_MODEL_WEIGHTS_BYTES = 1L * 1024L * 1024L
 
         internal const val MAX_SPAM_DATABASE_NUMBERS = 250_000
@@ -226,6 +238,7 @@ class GitHubDataSource internal constructor(
                 HOT_RANGES_PATH to RawFeedSpec("hot ranges", MAX_HOT_RANGES_BYTES),
                 SPAM_DOMAINS_PATH to RawFeedSpec("spam domains", MAX_SPAM_DOMAINS_BYTES),
                 MODEL_WEIGHTS_PATH to RawFeedSpec("model weights", MAX_MODEL_WEIGHTS_BYTES),
+                APP_RELEASE_PATH to RawFeedSpec("release notice", MAX_APP_RELEASE_BYTES),
             )
 
         /**
@@ -234,7 +247,49 @@ class GitHubDataSource internal constructor(
          * scripts/feed_signing.py signs the same files; its test checks the lists agree.
          */
         internal val SIGNED_FEED_PATHS =
-            setOf(DATA_PATH, SHARD_MANIFEST_PATH, HOT_LIST_PATH, HOT_RANGES_PATH, SPAM_DOMAINS_PATH, MODEL_WEIGHTS_PATH)
+            setOf(
+                DATA_PATH,
+                SHARD_MANIFEST_PATH,
+                HOT_LIST_PATH,
+                HOT_RANGES_PATH,
+                SPAM_DOMAINS_PATH,
+                MODEL_WEIGHTS_PATH,
+                APP_RELEASE_PATH,
+            )
+
+        private val VERSION_NAME_REGEX = Regex("\\d{1,4}\\.\\d{1,4}\\.\\d{1,4}")
+        private val SHA256_REGEX = Regex("[0-9a-f]{64}")
+        private val releaseNoticeAdapter =
+            Moshi
+                .Builder()
+                .addLast(KotlinJsonAdapterFactory())
+                .build()
+                .adapter(AppReleaseJson::class.java)
+
+        /**
+         * The release notice in [body], refused unless every field is usable and
+         * the link is this repo's tag page for that version. The file is signed,
+         * but a notice can only ever point at CallShield's own release page.
+         */
+        internal fun parseAppReleaseNotice(body: String): AppReleaseNotice {
+            val json =
+                try {
+                    releaseNoticeAdapter.fromJson(body)
+                } catch (e: IOException) {
+                    failFeedValidation(GitHubFeedFailureReason.INVALID_SCHEMA, "release notice isn't JSON: ${e.message}")
+                } catch (e: JsonDataException) {
+                    failFeedValidation(GitHubFeedFailureReason.INVALID_SCHEMA, "release notice has the wrong shape: ${e.message}")
+                }
+            val versionCode = json?.versionCode ?: 0
+            val versionName = json?.versionName.orEmpty()
+            val apkSha256 = json?.apkSha256.orEmpty()
+            requireFeed(versionCode > 0, GitHubFeedFailureReason.MISSING_SCHEMA_FIELD) { "release notice has no version_code" }
+            requireFeed(VERSION_NAME_REGEX.matches(versionName), GitHubFeedFailureReason.INVALID_SCHEMA) { "release notice version_name is unusable" }
+            requireFeed(SHA256_REGEX.matches(apkSha256), GitHubFeedFailureReason.INVALID_SCHEMA) { "release notice apk_sha256 is unusable" }
+            val releaseUrl = "https://github.com/$DEFAULT_REPO_OWNER/$DEFAULT_REPO_NAME/releases/tag/v$versionName"
+            requireFeed(json?.releaseUrl == releaseUrl, GitHubFeedFailureReason.INVALID_SCHEMA) { "release notice links somewhere other than its tag page" }
+            return AppReleaseNotice(versionCode, versionName, releaseUrl, apkSha256)
+        }
 
         /** Throws unless a signed feed arrived with a signature the app accepts. */
         internal fun requireFeedSignature(
@@ -417,6 +472,22 @@ class GitHubDataSource internal constructor(
             }
         }
 
+    override suspend fun fetchAppReleaseNotice(
+        owner: String,
+        repo: String,
+    ): Result<AppReleaseNotice> =
+        withContext(Dispatchers.IO) {
+            val result = fetchRawText(APP_RELEASE_PATH, owner, repo)
+            if (result.isFailure) {
+                return@withContext Result.failure(result.exceptionOrNull()!!)
+            }
+            try {
+                Result.success(parseAppReleaseNotice(result.getOrThrow()))
+            } catch (refused: GitHubFeedValidationException) {
+                Result.failure(refused)
+            }
+        }
+
     suspend fun fetchModelWeightsJson(
         owner: String = DEFAULT_REPO_OWNER,
         repo: String = DEFAULT_REPO_NAME,
 
@@ -1,5 +1,6 @@
 package com.sysadmindoc.callshield.data.remote
 
+import com.sysadmindoc.callshield.data.model.AppReleaseNotice
 import com.sysadmindoc.callshield.data.model.SpamDatabase
 import com.sysadmindoc.callshield.data.model.SpamDatabaseShard
 import com.sysadmindoc.callshield.data.model.SpamShardManifest
@@ -33,6 +34,12 @@ interface SpamDataSource {
 
     fun parseSpamShardJson(body: String): Result<SpamDatabaseShard> = Result.failure(UnsupportedOperationException("Content-addressed spam shards are unavailable"))
 
+    /** The signed release notice (`data/app_release.json`), fetched like the other feeds. */
+    suspend fun fetchAppReleaseNotice(
+        owner: String = GitHubDataSource.DEFAULT_REPO_OWNER,
+        repo: String = GitHubDataSource.DEFAULT_REPO_NAME,
+    ): Result<AppReleaseNotice> = Result.failure(UnsupportedOperationException("Release notices are unavailable"))
+
     /** True while GitHub itself fails certificate verification, even when a mirror is serving the feeds. */
     val gitHubTrustFailing: Boolean get() = false
 
 
@@ -27,6 +27,7 @@ import com.sysadmindoc.callshield.data.NotificationScreeningSources
 import com.sysadmindoc.callshield.data.RegionRules
 import com.sysadmindoc.callshield.data.RegulatoryPrefix
 import com.sysadmindoc.callshield.data.SpamRepository
+import com.sysadmindoc.callshield.data.model.AppReleaseNotice
 import com.sysadmindoc.callshield.data.model.ExternalBlocklistSubscription
 import com.sysadmindoc.callshield.data.model.HotDataHealth
 import com.sysadmindoc.callshield.data.model.HotDataHealthUpdate
@@ -259,6 +260,34 @@ class SettingsRepository(
     val activeProfileName: Flow<String?> = dataStore.data.map { it[SpamRepository.KEY_ACTIVE_PROFILE] }
     val appTheme: Flow<String> = dataStore.data.map { sanitizeAppTheme(it[SpamRepository.KEY_APP_THEME]) }
     val appUpdateChecksEnabled: Flow<Boolean> = dataStore.data.map { it[SpamRepository.KEY_APP_UPDATE_CHECKS] ?: false }
+
+    /** The stored release notice while [installedCode] is older and the user hasn't dismissed that release. */
+    fun appReleaseNotice(installedCode: Int = BuildConfig.VERSION_CODE): Flow<AppReleaseNotice?> =
+        dataStore.data
+            .map { prefs ->
+                val notice =
+                    AppReleaseNotice(
+                        versionCode = prefs[SpamRepository.KEY_RELEASE_NOTICE_CODE] ?: return@map null,
+                        versionName = prefs[SpamRepository.KEY_RELEASE_NOTICE_NAME] ?: return@map null,
+                        releaseUrl = prefs[SpamRepository.KEY_RELEASE_NOTICE_URL] ?: return@map null,
+                        apkSha256 = prefs[SpamRepository.KEY_RELEASE_NOTICE_SHA256].orEmpty(),
+                    )
+                notice.takeIf { it.shouldShow(installedCode, prefs[SpamRepository.KEY_RELEASE_NOTICE_DISMISSED] ?: 0) }
+            }.distinctUntilChanged()
+
+    suspend fun saveAppReleaseNotice(notice: AppReleaseNotice) {
+        dataStore.edit {
+            it[SpamRepository.KEY_RELEASE_NOTICE_CODE] = notice.versionCode
+            it[SpamRepository.KEY_RELEASE_NOTICE_NAME] = notice.versionName
+            it[SpamRepository.KEY_RELEASE_NOTICE_URL] = notice.releaseUrl
+            it[SpamRepository.KEY_RELEASE_NOTICE_SHA256] = notice.apkSha256
+        }
+    }
+
+    suspend fun dismissAppReleaseNotice(versionCode: Int) {
+        dataStore.edit { it[SpamRepository.KEY_RELEASE_NOTICE_DISMISSED] = versionCode }
+    }
+
     val appUpdateState: Flow<AppUpdateState> =
         dataStore.data.map { prefs ->
             AppUpdateState(
 
@@ -260,6 +260,17 @@ class SyncRepository(
             }
         }
 
+    /**
+     * Fetches the signed release notice and keeps it for Home. A missing,
+     * unsigned or refused file changes nothing, so the last good notice stays.
+     */
+    suspend fun refreshAppReleaseNotice(): Boolean =
+        withContext(Dispatchers.IO) {
+            val notice = remote.fetchAppReleaseNotice().getOrNull() ?: return@withContext false
+            settingsRepository.saveAppReleaseNotice(notice)
+            true
+        }
+
     /** Saves [url] as the feed mirror once it serves this project's signed manifest. */
     suspend fun saveFeedMirrorUrl(url: String): FeedMirrorSave {
         val normalized = FeedMirror.normalize(url) ?: return FeedMirrorSave.INVALID
 
@@ -36,6 +36,13 @@ class SyncWorker
             // Also sync the ML model weights file — lightweight, same GitHub repo
             spamMLScorer.syncWeights(applicationContext)
 
+            // And the signed release notice Home offers to older builds.
+            try {
+                repo.refreshAppReleaseNotice()
+            } catch (e: Exception) {
+                android.util.Log.w("SyncWorker", "Release notice refresh failed", e)
+            }
+
             // A pin failure still reports success when older data is on the
             // device, so it is surfaced here rather than through the result.
             FeedTrustNotice.maybeNotify(applicationContext, repo)