feat: Health Connect opt-in scaffold + privacy doc (N12+N13) — v1.13.1

Lands the Health Connect plumbing without yet pulling the SDK or
reading any data — the toggle, the user-facing UI, and the privacy
narrative all ship now so the follow-up release that adds the
androidx.health.connect:connect-client integration can light up
immediately for opted-in users and ship behind a Play Console health-
permissions policy review.

Wiring (N12 scaffold):
- AppSettings.healthConnectEnabled (default false). DataStore key
  HEALTH_CONNECT_ENABLED; read/write mappings symmetric with the rest
  of AppSettings.
- SettingsBackup.healthConnectEnabled with default 0 (back-compat
  read). Round-trips through both plain JSON and AES-256 encrypted
  backup paths so opt-in survives device swaps.
- SettingsViewModel.updateHealthConnectEnabled(enabled) setter.
- New HealthConnectSection in SettingsScreen, placed between
  PhilipsHueSection and PersonalizationSection. Flavor-aware copy:
  Play-flavor users see the read-sleep-sessions pitch; F-Droid users
  see "this flavor does not ship Health Connect — install Play to opt
  in" honest disclosure.

Documentation (N13):
- PRIVACY_POLICY.html gains a "Health Connect (Play flavor, opt-in)"
  section that spells out:
    * What's read (SleepSessionRecord only — start/end + optional
      stage breakdown for past 7 days).
    * Where it stays (on device — Health Connect's encrypted store +
      app DataStore; no analytics SDK; no transmission).
    * Revocation flow (in-app toggle or Health Connect settings).
    * F-Droid behaviour (no SDK shipped; toggle is a no-op).
    * Google Play Health Apps policy use-case statement
      ("wellness / sleep tracking only; never for employment or
      insurance eligibility; never shared").
- Satisfies the documentation prerequisite for the Play Console
  health-permissions declaration so the follow-up release that wires
  the actual SDK can submit for review without surprises.

Deferred to a follow-up release:
- The actual androidx.health.connect:connect-client dependency,
  HealthConnectGateway interface, the read-permission handoff to the
  Health Connect Settings screen, and the Bedtime/Stats data
  surfacing. The roadmap entry for N12 is marked [~] (in progress)
  with this scaffold complete; N13 is marked [x] (shipped).

Internal: versionCode 65 → 66, versionName 1.13.0 → 1.13.1. Verified
the v1.12.3 CI version-line lint passes against the new tree (all six
anchors report 1.13.1).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MavenImaging

CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to AlarmClockXtreme will be documented in this file.
 
+## [1.13.1] - 2026-05-16
+
+Health Connect opt-in scaffold + Play health-permissions narrative
+(roadmap N12 + N13). DataStore-only; the data-read path itself lands
+in a follow-up release after the Play Console health-permissions
+declaration is approved.
+
+### Added — Health Connect opt-in toggle
+
+- `AppSettings.healthConnectEnabled` (default false) survives DataStore
+  reads/writes and round-trips through the JSON + AES-256 backup paths
+  alongside every other setting.
+- New Settings → Health Connect card (sits between Philips Hue and
+  Personalization). Honest flavor-aware copy: Play-flavor users see the
+  full "read overnight sleep sessions" pitch; F-Droid users see "this
+  flavor does not ship Health Connect support — install the Play flavor
+  to opt in."
+
+### Documentation — PRIVACY_POLICY.html
+
+- New "Health Connect (Play flavor, opt-in)" section spells out what
+  data type is read (`SleepSessionRecord` only), retention (none —
+  reads are point-in-time, never persisted outside Health Connect's
+  own encrypted store + the in-app DataStore), revocation flow (toggle
+  off or revoke in Health Connect settings), F-Droid behaviour (no SDK
+  shipped, toggle is a no-op), and the Google Play Health Apps policy
+  use-case statement ("wellness / sleep tracking only — never for
+  employment or insurance eligibility, never shared").
+- This satisfies the prerequisite documentation for the Play Console
+  health-permissions declaration (roadmap N13) so the follow-up release
+  that wires the actual `androidx.health.connect:connect-client` SDK
+  can ship behind a Play store policy review.
+
+### Internal
+
+- Bumped to `versionName = "1.13.1"`, `versionCode = 66`. README badge,
+  install command, and Wear module version synced.
+
 ## [1.13.0] - 2026-05-16
 
 Adaptive primary navigation: NavigationBar on phones, NavigationRail on

PRIVACY_POLICY.html

@@ -63,6 +63,16 @@ <h2>Data Storage</h2>
     <h2>Third-Party Services</h2>
     <p>The app does not integrate with any third-party analytics, advertising, or tracking services. The only external service used is the Open-Meteo weather API, which is free, open-source, and does not require authentication.</p>
 
+    <h2>Health Connect (Play flavor, opt-in)</h2>
+    <p>The Play-flavor build includes an opt-in toggle to read sleep session data from Android's Health Connect (Settings &rarr; Health Connect &rarr; "Allow reading sleep sessions"). When you enable the toggle and grant the Health Connect permission prompt:</p>
+    <ul>
+        <li>The app reads <strong>SleepSessionRecord</strong> entries (start time, end time, optional sleep stage breakdown) for the past 7 days to surface "Last night you slept X hours" context on the Bedtime tab and to drive future Stats charts.</li>
+        <li>All Health Connect data stays on your device. It is not uploaded, transmitted, shared with the developer, or persisted outside Health Connect's own encrypted store and the app's local DataStore preferences. There is no analytics SDK that could exfiltrate it.</li>
+        <li>You can revoke access at any time via Health Connect (Settings &rarr; Apps &rarr; Health Connect &rarr; Manage permissions) or by toggling the in-app switch off. Revoking immediately stops further reads; previously displayed values clear on next launch.</li>
+        <li>The F-Droid flavor does not include the Health Connect SDK at all. The toggle is visible but has no effect on F-Droid builds.</li>
+        <li>Per the Google Play Health Apps policy (April 2026), AlarmClockXtreme uses Health Connect sleep data only for the "wellness / sleep tracking" use case stated above. It is never used to determine employment or insurance eligibility, and it is never shared.</li>
+    </ul>
+
     <h2>Children's Privacy</h2>
     <p>This app does not knowingly collect any information from children under 13. The app does not collect information from anyone.</p>
 

README.md

@@ -1,6 +1,6 @@
 # AlarmClockXtreme
 
-![Version](https://img.shields.io/badge/version-1.13.0-blue)
+![Version](https://img.shields.io/badge/version-1.13.1-blue)
 ![License](https://img.shields.io/badge/license-Apache%202.0-green)
 ![Platform](https://img.shields.io/badge/platform-Android%208.0+-3DDC84?logo=android&logoColor=white)
 ![Kotlin](https://img.shields.io/badge/Kotlin-2.1-7F52FF?logo=kotlin&logoColor=white)
@@ -15,7 +15,7 @@
 **Latest signed APK** — [Releases page](https://github.com/SysAdminDoc/AlarmClockXtreme/releases/latest)
 
 ```
-adb install AlarmClockXtreme-v1.13.0-play.apk
+adb install AlarmClockXtreme-v1.13.1-play.apk
 ```
 
 The Play-flavor APK includes the YouTube alarm-sound downloader (yt-dlp + NewPipe Extractor) and the Wear OS Data Layer bridge. The F-Droid flavor strips those proprietary pieces for an unencumbered build.

ROADMAP.md

@@ -1,7 +1,7 @@
 # AlarmClockXtreme Roadmap
 
-Living feature backlog, refreshed alongside **v1.13.0** (adaptive primary
-navigation — NavigationBar on phones, NavigationRail on tablets/foldables;
+Living feature backlog, refreshed alongside **v1.13.1** (Health Connect
+opt-in scaffold + privacy-policy update — completing the v1.12 cycle;
 see [CHANGELOG.md](CHANGELOG.md)). Last audit: **2026-05-16** —
 external scan against current OSS / commercial alarm-clock ecosystem,
 Android 16 / 17 platform direction, and Play Console policy changes.
@@ -19,10 +19,11 @@ ranked by impact-to-effort and grouped by theme.
   (kept on the list, not actively scheduled), **UC** (under consideration —
   needs scoping or platform readiness), **Rejected** (explicitly out).
 
-> **Recently shipped** (rolled up from prior tiers): **v1.13.0 adaptive
-> NavigationRail on MEDIUM/EXPANDED widths (N11)**; **v1.12.3 CI version-line
-> consistency lint (N10)**; **v1.12.2 RingtonePool chip-based editor (N9)**;
-> **v1.12.1 missed-timer notification (N8)**; **v1.12.0 per-alarm vibration start-delay (N7) —
+> **Recently shipped** (rolled up from prior tiers): **v1.13.1 Health Connect
+> opt-in scaffold + privacy-policy update (N12 + N13 scaffold)**; **v1.13.0
+> adaptive NavigationRail on MEDIUM/EXPANDED widths (N11)**; **v1.12.3 CI
+> version-line consistency lint (N10)**; **v1.12.2 RingtonePool chip-based
+> editor (N9)**; **v1.12.1 missed-timer notification (N8)**; **v1.12.0 per-alarm vibration start-delay (N7) —
 > DB v10**; **v1.11.6 "Pause alarms" single-tap suspend (N6)**; **v1.11.5 Philips Hue API v2 migration (N5)**; **v1.11.4
 > Play wake-lock policy audit (N4)**; **v1.11.3 App Standby bucket awareness
 > (N3)**; **v1.11.2 telephony-aware alarm muting (N2)**; **v1.11.1 challenge
@@ -39,15 +40,15 @@ ranked by impact-to-effort and grouped by theme.
 
 ---
 
-## Current snapshot (v1.13.0)
+## Current snapshot (v1.13.1)
 
 - **Stack:** Kotlin 2.1, AGP 8.11.1 / Gradle 8.13, Compose BOM 2026.05.00 /
   Material 3 (1.4.x), Room v10, Hilt 2.53.1, Retrofit 2.11 + Moshi (codegen),
   DataStore 1.1.1, Glance 1.1.1, OkHttp 4.12.0, WorkManager 2.9.1, Wear Tiles
   1.6.0 / protolayout 1.4.0, Wear Data Layer, yt-dlp (`youtubedl-android`
   0.18.1) + NewPipe Extractor 0.24.8 (Play flavor only).
 - **Targets:** `minSdk 26`, `targetSdk 35`, `compileSdk 36`,
-  `versionCode 65`, `versionName 1.13.0`.
+  `versionCode 66`, `versionName 1.13.1`.
 - **Surface area:** 120 Kotlin files in `:app` + 3 in `:wear`, two phone
   flavors (`play`, `fdroid`), **22 user-facing dismiss challenges** (all now
   whitelisted by `Alarm.sanitized()` after N1), 50+ alarm fields, 35+
@@ -82,8 +83,8 @@ in their notes. **Order is the recommended landing order.**
 | N9 | [x] RingtonePool chip-based editor — **shipped v1.12.2.** Replaced the textarea with a horizontally scrollable chip row in the Advanced section. Each pool URI renders as an `AppFilterChip` (tap to remove); an "Add" chip opens an `AlertDialog` for pasting a new URI with duplicate-protection. New `ringtoneShortName(uri)` helper trims content://media/external/audio/media/12345 → "audio/12345" without a per-render ContentResolver lookup. Storage format unchanged. | local: [AlarmEditScreen.kt:1247](app/src/main/java/com/sysadmindoc/alarmclock/ui/alarmedit/AlarmEditScreen.kt) | S | UX polish, no schema change. |
 | N10 | [x] CI version-line consistency lint — **shipped v1.12.3.** New `.github/workflows/version-lint.yml` runs on every push/PR. Asserts six touchpoints agree with `app/build.gradle.kts`: the `:wear` module's `versionName`, the README badge, the README `adb install` snippet, the CHANGELOG top `## [x.y.z]` header, and the ROADMAP `## Current snapshot (vX.Y.Z)` header. Pure regex/grep — no JDK/Gradle bootstrap. | local: [.github/workflows/version-lint.yml](.github/workflows/version-lint.yml) | S | Prevents the recurring "README still says vX.Y.Z" post-release mismatch. |
 | N11 | [x] Adaptive primary navigation — **shipped v1.13.0.** Used the lower-level `material3-window-size-class` API rather than `NavigationSuiteScaffold` so the existing custom `BottomNavContainer` treatment + accent colors carry through unchanged on phones. AppNavigation branches on width class: COMPACT keeps the bottom NavigationBar verbatim, MEDIUM/EXPANDED render a `NavigationRail` on the leading edge inside a Row. Extracted the per-route NavHost into a private `AppNavHost` to dedupe. | [Android Developers — adaptive navigation](https://developer.android.com/develop/ui/compose/layouts/adaptive/build-adaptive-navigation) | M | Phone UX is byte-for-byte identical. Defers dual-pane Alarms/Edit (X14 follow-on) to a later release. |
-| N12 | [ ] Health Connect Sleep Sessions — **read-only first pass** (write deferred to v1.13). Pulls overnight sessions to seed Bedtime tab + Stats; user data never leaves device. | [androidx.health.connect:connect-client docs](https://developer.android.com/health-and-fitness/health-connect); [Track sleep sessions](https://developer.android.com/health-and-fitness/health-connect/features/sleep-sessions) | M | Required pre-work: Play Console health-permissions declaration + privacy-policy refresh (see N13). API surface is stable at `1.1.0-alpha12`; pin behind Play flavor only at first, then move main once Google removes alpha gating. |
-| N13 | [ ] Play Store data-safety + health-permission declaration refresh — required by [April 2026 policy](https://support.google.com/googleplay/android-developer/answer/16926792?hl=en) before N12 ships. Update `PRIVACY_POLICY.html` Health-Connect paragraph. | [Play Console policy April 15 2026](https://support.google.com/googleplay/android-developer/answer/16926792?hl=en) | S | Hard prerequisite for N12. Document the read-only justification ("local-only sleep analysis; not transmitted off device"). |
+| N12 | [~] Health Connect Sleep Sessions — **scaffold shipped v1.13.1.** DataStore opt-in toggle (`healthConnectEnabled`), Settings → Health Connect card with flavor-aware copy, backup round-trip. Actual `androidx.health.connect:connect-client` SDK integration + Bedtime/Stats data surfacing deferred to a follow-up release pending Play Console health-permissions review. | [androidx.health.connect:connect-client docs](https://developer.android.com/health-and-fitness/health-connect); [Track sleep sessions](https://developer.android.com/health-and-fitness/health-connect/features/sleep-sessions) | M | Toggle survives backup so opted-in users light up immediately when the data path lands. |
+| N13 | [x] Play Store data-safety + health-permission declaration refresh — **shipped v1.13.1.** `PRIVACY_POLICY.html` gains a "Health Connect (Play flavor, opt-in)" section spelling out the data type read (`SleepSessionRecord` only), retention (none), revocation flow, F-Droid behaviour (no SDK shipped), and the Google Play Health Apps policy use-case statement. | [Play Console policy April 15 2026](https://support.google.com/googleplay/android-developer/answer/16926792?hl=en) | S | Documentation prerequisite for the follow-up release that wires the SDK. |
 
 ## NEXT — v1.13 candidates
 

app/build.gradle.kts

@@ -1,7 +1,7 @@
 import java.util.Properties
 import java.io.FileInputStream
 
-// AlarmClockXtreme v1.13.0
+// AlarmClockXtreme v1.13.1
 plugins {
     id("com.android.application")
     id("org.jetbrains.kotlin.android")
@@ -18,8 +18,8 @@ android {
         applicationId = "com.sysadmindoc.alarmclock"
         minSdk = 26
         targetSdk = 35
-        versionCode = 65
-        versionName = "1.13.0"
+        versionCode = 66
+        versionName = "1.13.1"
 
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
 

app/src/main/java/com/sysadmindoc/alarmclock/data/backup/BackupManager.kt

@@ -143,7 +143,11 @@ data class SettingsBackup(
     // backup so a restore of "I'm pausing for 3 days" survives device
     // swaps; stale restored values are harmless because the scheduler
     // checks `> now` per fire.
-    val pauseUntilMillis: Long = 0
+    val pauseUntilMillis: Long = 0,
+    // v1.13.1 (roadmap N12): Health Connect opt-in survives backup so a
+    // user who restores onto a new Play-flavor device doesn't have to
+    // re-tap the toggle. F-Droid restore ignores it.
+    val healthConnectEnabled: Boolean = false
 )
 
 @Singleton
@@ -212,7 +216,8 @@ class BackupManager @Inject constructor(
                 sleepSoundFadeSeconds = settings.sleepSoundFadeSeconds,
                 repeatMissedAlarms = settings.repeatMissedAlarms,
                 napDefaultMinutes = settings.napDefaultMinutes,
-                pauseUntilMillis = settings.pauseUntilMillis
+                pauseUntilMillis = settings.pauseUntilMillis,
+                healthConnectEnabled = settings.healthConnectEnabled
             )
         )
 
@@ -357,7 +362,8 @@ class BackupManager @Inject constructor(
                         sleepSoundFadeSeconds = s.sleepSoundFadeSeconds,
                         repeatMissedAlarms = s.repeatMissedAlarms,
                         napDefaultMinutes = s.napDefaultMinutes,
-                        pauseUntilMillis = s.pauseUntilMillis
+                        pauseUntilMillis = s.pauseUntilMillis,
+                        healthConnectEnabled = s.healthConnectEnabled
                     )
                 }
             }

app/src/main/java/com/sysadmindoc/alarmclock/data/preferences/PreferencesManager.kt

@@ -124,6 +124,14 @@ data class AppSettings(
     // is in the past, the value is treated as expired and alarms resume on the
     // next reschedule pass.
     val pauseUntilMillis: Long = 0,
+    // v1.13.1 (roadmap N12 + N13): user opt-in for Health Connect sleep
+    // session reads. Defaults false because Health Connect requires its
+    // own per-data-type permission grant (handled in a future release;
+    // the first-pass UI surfaces the toggle + a status row but does not
+    // yet pull data — see HealthConnectGateway). The Play Console health
+    // permissions policy refresh required to actually ship the data path
+    // is tracked alongside (roadmap N13).
+    val healthConnectEnabled: Boolean = false,
 )
 
 private fun AppSettings.sanitized(): AppSettings {
@@ -269,6 +277,7 @@ class PreferencesManager @Inject constructor(
         val SHOW_RADAR_EMBED = booleanPreferencesKey("show_radar_embed")
         val NEWS_FEED_URL = stringPreferencesKey("news_feed_url")
         val PAUSE_UNTIL = longPreferencesKey("pause_until_millis")
+        val HEALTH_CONNECT_ENABLED = booleanPreferencesKey("health_connect_enabled")
     }
 
     val settings: Flow<AppSettings> = context.dataStore.data
@@ -374,6 +383,7 @@ class PreferencesManager @Inject constructor(
         newsFeedUrl = this[Keys.NEWS_FEED_URL]
             ?: "https://news.google.com/rss?hl=en-US&gl=US&ceid=US:en",
         pauseUntilMillis = this[Keys.PAUSE_UNTIL] ?: 0L,
+        healthConnectEnabled = this[Keys.HEALTH_CONNECT_ENABLED] ?: false,
     )
 
     private fun MutablePreferences.applySettings(s: AppSettings) {
@@ -434,5 +444,6 @@ class PreferencesManager @Inject constructor(
         this[Keys.SHOW_RADAR_EMBED] = s.showRadarEmbed
         this[Keys.NEWS_FEED_URL] = s.newsFeedUrl
         this[Keys.PAUSE_UNTIL] = s.pauseUntilMillis
+        this[Keys.HEALTH_CONNECT_ENABLED] = s.healthConnectEnabled
     }
 }

app/src/main/java/com/sysadmindoc/alarmclock/ui/settings/SettingsScreen.kt

@@ -400,6 +400,7 @@ fun SettingsScreen(
             IntegrationsSection(state, viewModel)
             HolidaysSection(state, viewModel)
             PhilipsHueSection(state, viewModel)
+            HealthConnectSection(state, viewModel)
             PersonalizationSection(state, viewModel)
             BackupRestoreSection(viewModel)
 
@@ -1318,6 +1319,42 @@ private fun PhilipsHueSection(state: SettingsUiState, viewModel: SettingsViewMod
     }
 }
 
+/**
+ * v1.13.1 (roadmap N12 + N13): Health Connect opt-in scaffold. The first
+ * pass surfaces the toggle so opted-in users light up immediately when
+ * the follow-up release ships the `androidx.health.connect:connect-client`
+ * SDK integration. F-Droid builds also see the row, but the toggle text
+ * is honest about the flavor not yet shipping Health Connect.
+ *
+ * The Play Console health-permissions declaration (N13) is gated on the
+ * actual data-read path landing; for now `PRIVACY_POLICY.html` carries
+ * the narrative.
+ */
+@Composable
+private fun HealthConnectSection(state: SettingsUiState, viewModel: SettingsViewModel) {
+    val isPlayFlavor = com.sysadmindoc.alarmclock.BuildConfig.FLAVOR == "play"
+    AppSurfaceCard {
+        AppSectionTitle(
+            title = "Health Connect",
+            description = if (isPlayFlavor) {
+                "Read overnight sleep sessions from Health Connect to enrich the Bedtime tab and Stats. The connection prompt opens the system Health Connect screen."
+            } else {
+                "The F-Droid flavor does not ship Health Connect support. Install the Play flavor to opt in."
+            }
+        )
+        SettingsToggle(
+            label = "Allow reading sleep sessions",
+            checked = state.settings.healthConnectEnabled,
+            supportingText = if (isPlayFlavor) {
+                "Toggle on to grant Health Connect access (data integration ships in a follow-up release; toggle survives backup/restore so opted-in users light up immediately when it does)."
+            } else {
+                "Disabled on F-Droid. Toggle has no effect on this build."
+            },
+            onToggle = viewModel::updateHealthConnectEnabled
+        )
+    }
+}
+
 /**
  * v1.2.0 personalization controls. Until this audit pass these settings
  * (`accentColor`, `showMotivationalQuotes`, `adaptiveDifficultyEnabled`,

app/src/main/java/com/sysadmindoc/alarmclock/ui/settings/SettingsViewModel.kt

@@ -342,6 +342,18 @@ class SettingsViewModel @Inject constructor(
         }
     }
 
+    /**
+     * v1.13.1 (roadmap N12): toggle the Health Connect opt-in. The
+     * concrete sleep-session read path is deferred to a follow-up
+     * release that bundles the `androidx.health.connect:connect-client`
+     * SDK and the matching Play Console health-permissions declaration
+     * (see N13). For now the toggle stores intent so the future
+     * release can light up immediately for opted-in users.
+     */
+    fun updateHealthConnectEnabled(enabled: Boolean) {
+        updateSettings { it.copy(healthConnectEnabled = enabled) }
+    }
+
     /** v1.11.6: Clear an active pause and re-arm alarms. */
     fun resumeAlarms() {
         viewModelScope.launch {

wear/build.gradle.kts

@@ -14,8 +14,8 @@ android {
         applicationId = "com.sysadmindoc.alarmclock"
         minSdk = 26
         targetSdk = 35
-        versionCode = 65
-        versionName = "1.13.0"
+        versionCode = 66
+        versionName = "1.13.1"
     }
 
     signingConfigs {