tests: add populated-state screenshot UITest

Companion to EmptyStateScreenshotUITests: seeds a fresh verified account with
realistic data (residences, tasks across kanban columns, contractors, documents
+ warranties) and screenshots each populated tab. Exploratory visual harness.

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

.claude/settings.local.json

@@ -18,7 +18,8 @@
       "Bash(ps:*)",
       "Bash(stdbuf:*)",
       "Bash(sysctl:*)",
-      "Bash(tee:*)"
+      "Bash(tee:*)",
+      "Bash(codesign -d --entitlements :- /Users/treyt/Library/Developer/Xcode/DerivedData/honeyDue-buvczbpttcfkxxcmxbnqkqrmujyh/Build/Products/Debug-iphonesimulator/honeyDue.app)"
     ]
   }
 }

composeApp/src/androidMain/AndroidManifest.xml

@@ -121,6 +121,19 @@
             </intent-filter>
         </receiver>
 
+        <!-- Per-widget residence picker (gitea#6). Each widget provider
+             XML declares `android:configure` pointing at this activity,
+             so the system launches it whenever the user pins a new
+             tile or hits "Edit Widget" on an existing one. -->
+        <activity
+            android:name=".widget.WidgetConfigActivity"
+            android:exported="true"
+            android:theme="@android:style/Theme.Material.Light.NoActionBar">
+            <intent-filter>
+                <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE" />
+            </intent-filter>
+        </activity>
+
         <!-- Small Widget Receiver (2x1) -->
         <receiver
             android:name=".widget.HoneyDueSmallWidgetReceiver"

composeApp/src/androidMain/kotlin/com/tt/honeyDue/MainActivity.kt

@@ -314,9 +314,10 @@ class MainActivity : FragmentActivity(), SingletonImageLoader.Factory {
         return ImageLoader.Builder(context)
             .components {
                 // Auth interceptor runs before the network fetcher so every
-                // image request carries the current Authorization header, with
-                // 401 -> refresh-token -> retry handled transparently. Mirrors
-                // iOS AuthenticatedImage.swift (Stream U).
+                // image request carries the current X-Session-Token header
+                // (Kratos session token), with 401 -> session re-check ->
+                // retry handled transparently. Mirrors iOS
+                // AuthenticatedImage.swift.
                 add(
                     CoilAuthInterceptor(
                         tokenProvider = { TokenStorage.getToken() },
@@ -324,7 +325,6 @@ class MainActivity : FragmentActivity(), SingletonImageLoader.Factory {
                             val r = APILayer.refreshToken()
                             if (r is ApiResult.Success) r.data else null
                         },
-                        authScheme = "Token",
                     )
                 )
                 add(KtorNetworkFetcherFactory())

composeApp/src/androidMain/kotlin/com/tt/honeyDue/NotificationActionReceiver.kt

@@ -91,7 +91,6 @@ class NotificationActionReceiver : BroadcastReceiver() {
                 notes = null,
                 actualCost = null,
                 rating = null,
-                imageUrls = null
             )
 
             when (val result = APILayer.createTaskCompletion(request)) {

composeApp/src/androidMain/kotlin/com/tt/honeyDue/media/ImageDownsampler.kt

@@ -0,0 +1,101 @@
+package com.tt.honeyDue.media
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import java.io.ByteArrayOutputStream
+import java.io.InputStream
+
+/**
+ * Memory-efficient image resizer for upload preprocessing on Android.
+ *
+ * Why not just decode + Bitmap.createScaledBitmap? createScaledBitmap
+ * decodes the full source bitmap first — a 12 MP photo materializes ~50 MB
+ * in RAM regardless of how big the JPEG is. That OOMs older devices.
+ *
+ * BitmapFactory.Options.inSampleSize, paired with inJustDecodeBounds=true
+ * for a metadata-only first pass, lets us decode at a power-of-two
+ * subsample. Combined with a final scaled-down draw, peak memory is
+ * roughly proportional to the *output* bitmap's pixel count — not the
+ * source's.
+ *
+ * Quality tuning matches WhatsApp-class apps: 2048 px max edge, JPEG 85.
+ */
+object ImageDownsampler {
+
+    data class Profile(
+        val maxPixelEdge: Int,
+        /** JPEG quality 0-100. */
+        val jpegQuality: Int,
+    ) {
+        companion object {
+            val Completion = Profile(maxPixelEdge = 2048, jpegQuality = 85)
+            val DocumentImage = Profile(maxPixelEdge = 2560, jpegQuality = 90)
+        }
+    }
+
+    /** Downsample raw image bytes into JPEG bytes ready for upload. */
+    fun downsample(bytes: ByteArray, profile: Profile): ByteArray? {
+        val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+        BitmapFactory.decodeByteArray(bytes, 0, bytes.size, bounds)
+        if (bounds.outWidth <= 0 || bounds.outHeight <= 0) return null
+
+        val sampleSize = computeSampleSize(bounds.outWidth, bounds.outHeight, profile.maxPixelEdge)
+        val decodeOpts = BitmapFactory.Options().apply {
+            inSampleSize = sampleSize
+            // ARGB_8888 keeps quality; on memory-constrained devices we
+            // could drop to RGB_565 here, but for upload prep the extra
+            // ~2x peak memory isn't worth the visible quality loss.
+            inPreferredConfig = Bitmap.Config.ARGB_8888
+        }
+        val decoded = BitmapFactory.decodeByteArray(bytes, 0, bytes.size, decodeOpts)
+            ?: return null
+
+        // Subsample is power-of-two only; the result may still be larger
+        // than maxPixelEdge by up to 2x. One more proportional scale gets
+        // us to the exact target.
+        val scaled = scaleProportional(decoded, profile.maxPixelEdge)
+
+        val out = ByteArrayOutputStream(64 * 1024)
+        val ok = scaled.compress(Bitmap.CompressFormat.JPEG, profile.jpegQuality, out)
+        // Only recycle if scaled is a different bitmap; createScaledBitmap
+        // sometimes returns the input unchanged, and recycling that would
+        // double-recycle below.
+        if (scaled !== decoded) decoded.recycle()
+        scaled.recycle()
+        return if (ok) out.toByteArray() else null
+    }
+
+    /** Same, from a stream (for content:// URIs etc.). */
+    fun downsample(input: InputStream, profile: Profile): ByteArray? {
+        val bytes = input.use { it.readBytes() }
+        return downsample(bytes, profile)
+    }
+
+    /**
+     * Pick the largest power-of-two sub-sample factor that still yields
+     * an image at least as large as maxPixelEdge on both axes. Mirrors
+     * the canonical Android docs example.
+     */
+    private fun computeSampleSize(srcW: Int, srcH: Int, maxEdge: Int): Int {
+        var sample = 1
+        var halfW = srcW / 2
+        var halfH = srcH / 2
+        while (halfW >= maxEdge && halfH >= maxEdge) {
+            sample *= 2
+            halfW /= 2
+            halfH /= 2
+        }
+        return sample
+    }
+
+    private fun scaleProportional(src: Bitmap, maxEdge: Int): Bitmap {
+        val w = src.width
+        val h = src.height
+        val longest = maxOf(w, h)
+        if (longest <= maxEdge) return src
+        val ratio = maxEdge.toFloat() / longest.toFloat()
+        val newW = (w * ratio).toInt().coerceAtLeast(1)
+        val newH = (h * ratio).toInt().coerceAtLeast(1)
+        return Bitmap.createScaledBitmap(src, newW, newH, true)
+    }
+}

composeApp/src/androidMain/kotlin/com/tt/honeyDue/notifications/NotificationActionReceiver.kt

@@ -105,7 +105,6 @@ class NotificationActionReceiver : BroadcastReceiver() {
             notes = "Completed from notification",
             actualCost = null,
             rating = null,
-            imageUrls = null
         )
         when (val result = APILayer.createTaskCompletion(request)) {
             is ApiResult.Success -> {

composeApp/src/androidMain/kotlin/com/tt/honeyDue/platform/ImagePicker.android.kt

@@ -8,6 +8,7 @@ import androidx.activity.result.contract.ActivityResultContracts
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.remember
 import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.platform.LocalInspectionMode
 import androidx.core.content.FileProvider
 import java.io.File
 
@@ -58,6 +59,15 @@ actual fun rememberImagePicker(
 actual fun rememberCameraPicker(
     onImageCaptured: (ImageData) -> Unit
 ): () -> Unit {
+    // Compose previews and Roborazzi snapshot tests run without a
+    // `FileProvider` resolvable cache path — `getUriForFile` throws
+    // `Failed to find configured root...` because the test cache dir
+    // isn't registered in the manifest's `file_paths.xml`. The launch
+    // callback is never invoked in a preview/snapshot anyway, so
+    // returning a no-op keeps the composition clean.
+    if (LocalInspectionMode.current) {
+        return {}
+    }
     val context = LocalContext.current
 
     // Create a temp file URI for the camera to save to

composeApp/src/androidMain/kotlin/com/tt/honeyDue/widget/HoneyDueLargeWidget.kt

@@ -45,8 +45,14 @@ class HoneyDueLargeWidget : GlanceAppWidget() {
 
     override suspend fun provideGlance(context: Context, id: GlanceId) {
         val repo = WidgetDataRepository.get(context)
-        val tasks = repo.loadTasks()
-        val stats = repo.computeStats()
+        // Per-instance residence scoping (gitea#6). Stats are computed
+        // off the same filtered list so the bottom-tile counters
+        // ("Overdue / 7 days / 30 days") match the visible tasks
+        // instead of aggregating across every residence.
+        val appWidgetId =
+            androidx.glance.appwidget.GlanceAppWidgetManager(context).getAppWidgetId(id)
+        val tasks = repo.loadTasksForWidget(appWidgetId)
+        val stats = repo.computeStatsFromTasks(tasks)
         val tier = repo.loadTierState()
         val isPremium = tier.equals("premium", ignoreCase = true)
 
@@ -135,4 +141,9 @@ class HoneyDueLargeWidget : GlanceAppWidget() {
 /** AppWidget receiver for the large widget. */
 class HoneyDueLargeWidgetReceiver : GlanceAppWidgetReceiver() {
     override val glanceAppWidget: GlanceAppWidget = HoneyDueLargeWidget()
+
+    override fun onDeleted(context: Context, appWidgetIds: IntArray) {
+        super.onDeleted(context, appWidgetIds)
+        WidgetReceiverHelpers.purgeResidenceScopes(context, appWidgetIds)
+    }
 }

composeApp/src/androidMain/kotlin/com/tt/honeyDue/widget/HoneyDueMediumWidget.kt

@@ -36,7 +36,10 @@ class HoneyDueMediumWidget : GlanceAppWidget() {
 
     override suspend fun provideGlance(context: Context, id: GlanceId) {
         val repo = WidgetDataRepository.get(context)
-        val tasks = repo.loadTasks()
+        // Per-instance residence scoping (gitea#6). See small widget for rationale.
+        val appWidgetId =
+            androidx.glance.appwidget.GlanceAppWidgetManager(context).getAppWidgetId(id)
+        val tasks = repo.loadTasksForWidget(appWidgetId)
         val tier = repo.loadTierState()
         val isPremium = tier.equals("premium", ignoreCase = true)
 
@@ -122,4 +125,9 @@ class HoneyDueMediumWidget : GlanceAppWidget() {
 /** AppWidget receiver for the medium widget. */
 class HoneyDueMediumWidgetReceiver : GlanceAppWidgetReceiver() {
     override val glanceAppWidget: GlanceAppWidget = HoneyDueMediumWidget()
+
+    override fun onDeleted(context: Context, appWidgetIds: IntArray) {
+        super.onDeleted(context, appWidgetIds)
+        WidgetReceiverHelpers.purgeResidenceScopes(context, appWidgetIds)
+    }
 }

composeApp/src/androidMain/kotlin/com/tt/honeyDue/widget/HoneyDueSmallWidget.kt

@@ -2,6 +2,7 @@ package com.tt.honeyDue.widget
 
 import android.content.Context
 import android.content.Intent
+import kotlinx.coroutines.launch
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.unit.dp
 import androidx.glance.GlanceId
@@ -43,7 +44,13 @@ class HoneyDueSmallWidget : GlanceAppWidget() {
 
     override suspend fun provideGlance(context: Context, id: GlanceId) {
         val repo = WidgetDataRepository.get(context)
-        val tasks = repo.loadTasks()
+        // Resolve which residence this widget instance is scoped to
+        // (gitea#6). `loadTasksForWidget` falls back to "All residences"
+        // when no scope is saved, matching pre-#6 behaviour for tiles
+        // that haven't been configured yet.
+        val appWidgetId =
+            androidx.glance.appwidget.GlanceAppWidgetManager(context).getAppWidgetId(id)
+        val tasks = repo.loadTasksForWidget(appWidgetId)
         val tier = repo.loadTierState()
         val isPremium = tier.equals("premium", ignoreCase = true)
 
@@ -125,4 +132,35 @@ class OpenAppAction : ActionCallback {
 /** AppWidget receiver for the small widget. */
 class HoneyDueSmallWidgetReceiver : GlanceAppWidgetReceiver() {
     override val glanceAppWidget: GlanceAppWidget = HoneyDueSmallWidget()
+
+    override fun onDeleted(context: Context, appWidgetIds: IntArray) {
+        super.onDeleted(context, appWidgetIds)
+        // Clean per-instance residence scope when the user removes a tile
+        // so dangling `widget_residence_id_<n>` keys don't accumulate in
+        // the DataStore (gitea#6).
+        WidgetReceiverHelpers.purgeResidenceScopes(context, appWidgetIds)
+    }
+}
+
+/**
+ * Shared helpers for honeyDue Glance widget receivers. Kept in a
+ * top-level utility so every receiver size (Small / Medium / Large)
+ * uses identical cleanup logic.
+ */
+internal object WidgetReceiverHelpers {
+    @OptIn(kotlinx.coroutines.DelicateCoroutinesApi::class)
+    fun purgeResidenceScopes(context: Context, appWidgetIds: IntArray) {
+        if (appWidgetIds.isEmpty()) return
+        val repo = WidgetDataRepository.get(context)
+        // Fire-and-forget on a background dispatcher — `onDeleted` runs
+        // on the broadcast thread which doesn't permit suspend calls.
+        // GlobalScope is correct here: the IO is short-lived (one
+        // DataStore edit per removed appWidgetId) and there's no
+        // coroutine-scope tied to a long-lived receiver to attach to.
+        kotlinx.coroutines.GlobalScope.launch(kotlinx.coroutines.Dispatchers.IO) {
+            for (id in appWidgetIds) {
+                repo.clearResidenceIdFor(id)
+            }
+        }
+    }
 }

composeApp/src/androidMain/kotlin/com/tt/honeyDue/widget/WidgetConfigActivity.kt

@@ -0,0 +1,270 @@
+package com.tt.honeyDue.widget
+
+import android.app.Activity
+import android.appwidget.AppWidgetManager
+import android.content.Intent
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Check
+import androidx.compose.material.icons.filled.Home
+import androidx.compose.material3.Button
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import androidx.glance.appwidget.GlanceAppWidgetManager
+import androidx.glance.appwidget.updateAll
+import com.tt.honeyDue.ui.theme.AppSpacing
+import com.tt.honeyDue.ui.theme.HoneyDueTheme
+import com.tt.honeyDue.ui.theme.ThemeManager
+import kotlinx.coroutines.launch
+import androidx.lifecycle.lifecycleScope
+
+/**
+ * Per-widget residence selector. Launched by the system when the user
+ * pins a new honeyDue widget (because each widget provider XML now
+ * declares `android:configure`) and again when they hit "Edit Widget".
+ *
+ * Saves the chosen residence id under
+ * `widget_residence_id_<appWidgetId>` in [WidgetDataStore] so each
+ * widget instance can independently scope its task list (gitea#6).
+ * Selecting "All residences" clears the key and the widget reverts to
+ * the legacy unscoped behaviour.
+ */
+class WidgetConfigActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        // The system passes the just-created widget id in the extras.
+        // Without it we don't know which widget to configure — bail
+        // with CANCELED so the system removes the placeholder tile.
+        val appWidgetId = intent?.extras?.getInt(
+            AppWidgetManager.EXTRA_APPWIDGET_ID,
+            AppWidgetManager.INVALID_APPWIDGET_ID
+        ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
+
+        if (appWidgetId == AppWidgetManager.INVALID_APPWIDGET_ID) {
+            setResult(Activity.RESULT_CANCELED)
+            finish()
+            return
+        }
+
+        // Default a CANCEL result so the widget is removed if the user
+        // dismisses without saving (matches the Android convention).
+        setResult(
+            Activity.RESULT_CANCELED,
+            Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
+        )
+
+        setContent {
+            val theme = ThemeManager.currentTheme
+            HoneyDueTheme(themeColors = theme) {
+                WidgetConfigScreen(
+                    appWidgetId = appWidgetId,
+                    onCommit = { residenceId ->
+                        lifecycleScope.launch {
+                            val repo = WidgetDataRepository.get(this@WidgetConfigActivity)
+                            repo.saveResidenceIdFor(appWidgetId, residenceId)
+                            // Repaint every widget tile so this one
+                            // picks up the new scope on the next frame
+                            // (Glance handles which `appWidgetId` we
+                            // belong to via the per-instance state).
+                            HoneyDueSmallWidget().updateAll(this@WidgetConfigActivity)
+                            HoneyDueMediumWidget().updateAll(this@WidgetConfigActivity)
+                            HoneyDueLargeWidget().updateAll(this@WidgetConfigActivity)
+
+                            setResult(
+                                Activity.RESULT_OK,
+                                Intent().putExtra(
+                                    AppWidgetManager.EXTRA_APPWIDGET_ID,
+                                    appWidgetId
+                                )
+                            )
+                            finish()
+                        }
+                    }
+                )
+            }
+        }
+    }
+}
+
+/**
+ * The actual picker UI. Loads residences from [WidgetDataRepository]
+ * and offers an "All residences" option above them. Empty state shows
+ * a helper message instead of an empty list (user hasn't created any
+ * residences yet, or the main app hasn't synced).
+ */
+@Composable
+private fun WidgetConfigScreen(
+    appWidgetId: Int,
+    onCommit: (Long?) -> Unit
+) {
+    var residences by remember { mutableStateOf<List<WidgetResidenceDto>?>(null) }
+    var selectedId by remember { mutableStateOf<Long?>(null) }
+
+    val context = androidx.compose.ui.platform.LocalContext.current
+    LaunchedEffect(appWidgetId) {
+        val repo = WidgetDataRepository.get(context)
+        // Pre-select whatever the user picked last time they configured
+        // this same widget; falls back to "All residences" on first run.
+        selectedId = repo.loadResidenceIdFor(appWidgetId)
+        residences = repo.loadResidences()
+    }
+
+    Column(
+        modifier = Modifier
+            .fillMaxSize()
+            .background(MaterialTheme.colorScheme.background)
+            .padding(AppSpacing.lg)
+    ) {
+        Text(
+            text = "Choose a residence",
+            style = MaterialTheme.typography.headlineSmall,
+            fontWeight = FontWeight.SemiBold,
+            color = MaterialTheme.colorScheme.onBackground
+        )
+        Spacer(Modifier.height(AppSpacing.sm))
+        Text(
+            text = "This widget will only show tasks for the residence you pick. " +
+                "Choose \"All residences\" to keep showing every home.",
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant
+        )
+        Spacer(Modifier.height(AppSpacing.lg))
+
+        val items = residences
+        if (items == null) {
+            // Loading state — DataStore reads off the IO dispatcher.
+            Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+                CircularProgressIndicator()
+            }
+            return@Column
+        }
+
+        LazyColumn(
+            modifier = Modifier.weight(1f, fill = true),
+            verticalArrangement = Arrangement.spacedBy(AppSpacing.sm)
+        ) {
+            // "All residences" — selecting clears the per-widget key.
+            item {
+                ResidenceRow(
+                    title = "All residences",
+                    isSelected = selectedId == null,
+                    onClick = { selectedId = null }
+                )
+            }
+            if (items.isEmpty()) {
+                item {
+                    EmptyResidencesNote()
+                }
+            } else {
+                items(items, key = { it.id }) { residence ->
+                    ResidenceRow(
+                        title = residence.name,
+                        isSelected = selectedId == residence.id,
+                        onClick = { selectedId = residence.id }
+                    )
+                }
+            }
+        }
+
+        Spacer(Modifier.height(AppSpacing.lg))
+        Button(
+            onClick = { onCommit(selectedId) },
+            modifier = Modifier.fillMaxWidth()
+        ) {
+            Text("Save")
+        }
+    }
+}
+
+@Composable
+private fun ResidenceRow(
+    title: String,
+    isSelected: Boolean,
+    onClick: () -> Unit
+) {
+    Box(
+        modifier = Modifier
+            .fillMaxWidth()
+            .clip(RoundedCornerShape(AppSpacing.md))
+            .background(
+                if (isSelected) MaterialTheme.colorScheme.primaryContainer
+                else MaterialTheme.colorScheme.surfaceVariant
+            )
+            .clickable(onClick = onClick)
+            .padding(AppSpacing.lg)
+    ) {
+        androidx.compose.foundation.layout.Row(
+            verticalAlignment = Alignment.CenterVertically,
+            modifier = Modifier.fillMaxWidth()
+        ) {
+            Icon(
+                imageVector = Icons.Default.Home,
+                contentDescription = null,
+                tint = if (isSelected) MaterialTheme.colorScheme.primary
+                else MaterialTheme.colorScheme.onSurfaceVariant
+            )
+            Spacer(Modifier.fillMaxWidth(0.04f))
+            Text(
+                text = title,
+                style = MaterialTheme.typography.bodyLarge,
+                color = MaterialTheme.colorScheme.onBackground,
+                modifier = Modifier.weight(1f)
+            )
+            if (isSelected) {
+                Icon(
+                    imageVector = Icons.Default.Check,
+                    contentDescription = "Selected",
+                    tint = MaterialTheme.colorScheme.primary
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun EmptyResidencesNote() {
+    Box(
+        modifier = Modifier
+            .fillMaxWidth()
+            .clip(RoundedCornerShape(AppSpacing.md))
+            .background(MaterialTheme.colorScheme.surfaceVariant)
+            .padding(AppSpacing.lg)
+    ) {
+        Text(
+            text = "No residences yet — open honeyDue and add a property first, " +
+                "then come back to configure this widget.",
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurfaceVariant
+        )
+    }
+}

composeApp/src/androidMain/kotlin/com/tt/honeyDue/widget/WidgetDataRepository.kt

@@ -115,6 +115,66 @@ class WidgetDataRepository internal constructor(private val context: Context) {
         return all.filterNot { it.id in pending }
     }
 
+    /**
+     * Load the cached task list filtered by [residenceId]. Pass `null` to
+     * return every residence's tasks (the "All residences" widget option,
+     * matching pre-gitea#6 behaviour).
+     *
+     * Pending completions are excluded — same contract as [loadTasks].
+     */
+    suspend fun loadTasksForResidence(residenceId: Long?): List<WidgetTaskDto> {
+        val all = loadTasks()
+        return filterTasksForResidence(all, residenceId)
+    }
+
+    /**
+     * Resolve the residence scope for [appWidgetId] and return only its
+     * tasks. The widget [GlanceAppWidget.provideGlance] looks up its
+     * `appWidgetId` and calls this; configuration changes take effect on
+     * the next `updateAll` invocation.
+     */
+    suspend fun loadTasksForWidget(appWidgetId: Int): List<WidgetTaskDto> {
+        val residenceId = store.readResidenceIdFor(appWidgetId)
+        return loadTasksForResidence(residenceId)
+    }
+
+    // =========================================================================
+    // Residence sidecar (gitea#6)
+    // =========================================================================
+
+    /**
+     * Persist the user's residences so [WidgetConfigActivity] can offer
+     * them in its picker. Called from the main app whenever
+     * `DataManager.myResidences` updates.
+     */
+    suspend fun saveResidences(residences: List<WidgetResidenceDto>) {
+        store.writeResidencesJson(json.encodeToString(residences))
+    }
+
+    /** Read the persisted residence list (empty when never written or after logout). */
+    suspend fun loadResidences(): List<WidgetResidenceDto> {
+        val raw = store.readResidencesJson()
+        return try {
+            json.decodeFromString<List<WidgetResidenceDto>>(raw)
+        } catch (e: Exception) {
+            emptyList()
+        }
+    }
+
+    /** Read which residence this widget instance is currently scoped to (null = All). */
+    suspend fun loadResidenceIdFor(appWidgetId: Int): Long? =
+        store.readResidenceIdFor(appWidgetId)
+
+    /** Persist the chosen residence for this widget instance. */
+    suspend fun saveResidenceIdFor(appWidgetId: Int, residenceId: Long?) {
+        store.writeResidenceIdFor(appWidgetId, residenceId)
+    }
+
+    /** Drop the per-widget residence selection when the widget is removed. */
+    suspend fun clearResidenceIdFor(appWidgetId: Int) {
+        store.clearResidenceIdFor(appWidgetId)
+    }
+
     /** Queue a task id for optimistic completion. See [loadTasks]. */
     suspend fun markPendingCompletion(taskId: Long) {
         val current = store.readPendingCompletionIds().toMutableSet()
@@ -141,8 +201,15 @@ class WidgetDataRepository internal constructor(private val context: Context) {
      *
      * Pending-completion tasks are excluded (via [loadTasks]).
      */
-    suspend fun computeStats(): WidgetStats {
-        val tasks = loadTasks()
+    suspend fun computeStats(): WidgetStats = computeStatsFromTasks(loadTasks())
+
+    /**
+     * Compute the same stats off a pre-filtered task list. Used by
+     * [HoneyDueLargeWidget] after applying the per-widget residence
+     * scope (gitea#6) so the stat tiles reflect only the residence the
+     * user picked.
+     */
+    fun computeStatsFromTasks(tasks: List<WidgetTaskDto>): WidgetStats {
         var overdue = 0
         var within7 = 0
         var within8To30 = 0
@@ -257,5 +324,18 @@ class WidgetDataRepository internal constructor(private val context: Context) {
 
         /** Legacy accessor — delegates to [get]. */
         fun getInstance(context: Context): WidgetDataRepository = get(context)
+
+        /**
+         * Pure filter — exposed for unit-test coverage. Mirrors iOS'
+         * `WidgetDataManager.filterTasks(_:forResidenceId:)` semantics
+         * (gitea#6).
+         */
+        fun filterTasksForResidence(
+            tasks: List<WidgetTaskDto>,
+            residenceId: Long?
+        ): List<WidgetTaskDto> {
+            if (residenceId == null) return tasks
+            return tasks.filter { it.residenceId == residenceId }
+        }
     }
 }

composeApp/src/androidMain/kotlin/com/tt/honeyDue/widget/WidgetDataStore.kt

@@ -32,6 +32,15 @@ internal object WidgetDataStoreKeys {
     val PENDING_COMPLETION_IDS = stringPreferencesKey("pending_completion_ids")
     val LAST_REFRESH_TIME = longPreferencesKey("last_refresh_time")
     val USER_TIER = stringPreferencesKey("user_tier")
+    /** JSON-serialized List<WidgetResidenceDto> for the configuration picker (gitea#6). */
+    val WIDGET_RESIDENCES_JSON = stringPreferencesKey("widget_residences_json")
+
+    /**
+     * Returns a key for the `Long` residence id this `appWidgetId` is
+     * scoped to. Missing key = "All residences" (legacy behaviour).
+     */
+    fun residenceIdKeyFor(appWidgetId: Int) =
+        longPreferencesKey("widget_residence_id_$appWidgetId")
 }
 
 /**
@@ -90,6 +99,56 @@ class WidgetDataStore(private val context: Context) {
             prefs.remove(WidgetDataStoreKeys.PENDING_COMPLETION_IDS)
             prefs.remove(WidgetDataStoreKeys.LAST_REFRESH_TIME)
             prefs.remove(WidgetDataStoreKeys.USER_TIER)
+            prefs.remove(WidgetDataStoreKeys.WIDGET_RESIDENCES_JSON)
+            // Per-widget residence ids are added dynamically as
+            // `widget_residence_id_<appWidgetId>` keys; sweep them by
+            // prefix so logout doesn't leave dangling per-instance
+            // scoping behind.
+            prefs.asMap().keys
+                .filter { it.name.startsWith("widget_residence_id_") }
+                .forEach { prefs.remove(it) }
+        }
+    }
+
+    // =========================================================================
+    // Per-residence widget configuration (gitea#6)
+    // =========================================================================
+
+    /**
+     * Read the user's residences (id + name) as persisted by the main
+     * app. Used by [WidgetConfigActivity] to populate its picker.
+     */
+    suspend fun readResidencesJson(): String =
+        store.data.first()[WidgetDataStoreKeys.WIDGET_RESIDENCES_JSON] ?: "[]"
+
+    suspend fun writeResidencesJson(json: String) {
+        store.edit { prefs ->
+            prefs[WidgetDataStoreKeys.WIDGET_RESIDENCES_JSON] = json
+        }
+    }
+
+    /**
+     * Read the residence id this widget instance is scoped to, or `null`
+     * for "All residences" (no scoping — the legacy default).
+     */
+    suspend fun readResidenceIdFor(appWidgetId: Int): Long? =
+        store.data.first()[WidgetDataStoreKeys.residenceIdKeyFor(appWidgetId)]
+
+    suspend fun writeResidenceIdFor(appWidgetId: Int, residenceId: Long?) {
+        store.edit { prefs ->
+            val key = WidgetDataStoreKeys.residenceIdKeyFor(appWidgetId)
+            if (residenceId == null) {
+                prefs.remove(key)
+            } else {
+                prefs[key] = residenceId
+            }
+        }
+    }
+
+    /** Clear scoping for a removed widget instance (called from `onDeleted`). */
+    suspend fun clearResidenceIdFor(appWidgetId: Int) {
+        store.edit { prefs ->
+            prefs.remove(WidgetDataStoreKeys.residenceIdKeyFor(appWidgetId))
         }
     }
 }

composeApp/src/androidMain/kotlin/com/tt/honeyDue/widget/WidgetRefreshWorker.kt

@@ -18,6 +18,13 @@ interface WidgetRefreshDataSource {
     suspend fun fetchTasks(): ApiResult<List<WidgetTaskDto>>
     /** Fetch the current user's subscription tier ("free" | "premium"). */
     suspend fun fetchTier(): String
+    /**
+     * Fetch the user's residences for the widget configuration picker
+     * (gitea#6). Returning an empty list is non-fatal — the worker will
+     * just skip the residence sidecar update and pre-existing scopes
+     * keep working until next refresh.
+     */
+    suspend fun fetchResidences(): List<WidgetResidenceDto> = emptyList()
 }
 
 /**
@@ -48,6 +55,16 @@ internal object DefaultWidgetRefreshDataSource : WidgetRefreshDataSource {
         }
     }
 
+    override suspend fun fetchResidences(): List<WidgetResidenceDto> {
+        val result = APILayer.getMyResidences(forceRefresh = false)
+        return when (result) {
+            is ApiResult.Success -> result.data.residences.map { r ->
+                WidgetResidenceDto(id = r.id.toLong(), name = r.name)
+            }
+            else -> emptyList()
+        }
+    }
+
     private fun mapToWidgetTasks(response: TaskColumnsResponse): List<WidgetTaskDto> {
         val out = mutableListOf<WidgetTaskDto>()
         for (column in response.columns) {
@@ -112,6 +129,16 @@ class WidgetRefreshWorker(
                 val repo = WidgetDataRepository.get(ctx)
                 repo.saveTasks(tasksResult.data)
                 repo.saveTierState(tier)
+                // Best-effort residence sidecar update — failure is
+                // non-fatal because pre-existing scopes (and the
+                // "All residences" fallback) keep working with stale
+                // data until the next refresh succeeds (gitea#6).
+                runCatching {
+                    val residences = dataSource.fetchResidences()
+                    if (residences.isNotEmpty()) {
+                        repo.saveResidences(residences)
+                    }
+                }
                 refreshGlanceWidgets(ctx)
                 // Chain the next scheduled refresh so cadence keeps ticking
                 // even if the OS evicts our periodic request. Wrapped in

composeApp/src/androidMain/kotlin/com/tt/honeyDue/widget/WidgetTaskDto.kt

@@ -34,6 +34,20 @@ data class WidgetTaskDto(
     val completed: Boolean
 )
 
+/**
+ * Lightweight residence identifier persisted to the widget DataStore.
+ *
+ * Written by the main app whenever [com.tt.honeyDue.data.DataManager.myResidences]
+ * updates so the widget configuration activity can offer the current
+ * residence list (gitea#6 — per-residence widget selection). Mirrors
+ * iOS' `WidgetDataManager.WidgetResidence` shape.
+ */
+@Serializable
+data class WidgetResidenceDto(
+    val id: Long,
+    val name: String
+)
+
 /**
  * Summary metrics computed from the cached task list.
  *

composeApp/src/androidMain/res/xml/honeydue_large_widget_info.xml

@@ -14,4 +14,5 @@
     android:previewLayout="@layout/widget_large_preview"
     android:description="@string/widget_large_description"
     android:updatePeriodMillis="1800000"
+    android:configure="com.tt.honeyDue.widget.WidgetConfigActivity"
     android:widgetFeatures="reconfigurable" />

composeApp/src/androidMain/res/xml/honeydue_medium_widget_info.xml

@@ -14,4 +14,5 @@
     android:previewLayout="@layout/widget_medium_preview"
     android:description="@string/widget_medium_description"
     android:updatePeriodMillis="1800000"
+    android:configure="com.tt.honeyDue.widget.WidgetConfigActivity"
     android:widgetFeatures="reconfigurable" />

composeApp/src/androidMain/res/xml/honeydue_small_widget_info.xml

@@ -14,4 +14,5 @@
     android:previewLayout="@layout/widget_small_preview"
     android:description="@string/widget_small_description"
     android:updatePeriodMillis="1800000"
+    android:configure="com.tt.honeyDue.widget.WidgetConfigActivity"
     android:widgetFeatures="reconfigurable" />

composeApp/src/androidUnitTest/kotlin/com/tt/honeyDue/architecture/NoIndependentViewModelStateFileScanTest.kt

@@ -0,0 +1,130 @@
+package com.tt.honeyDue.architecture
+
+import java.io.File
+import kotlin.test.Test
+import kotlin.test.fail
+
+/**
+ * Architecture regression gate.
+ *
+ * Scans `composeApp/src/commonMain/kotlin/com/tt/honeyDue/viewmodel/` and
+ * asserts every ViewModel either:
+ *   a) accepts `dataManager: IDataManager` as a constructor parameter, or
+ *   b) is explicitly allowlisted in [WORKFLOW_ONLY_VMS] as a
+ *      workflow/mutation-only VM.
+ *
+ * Prevents the Dec 3 2025 regression (4 VMs holding independent
+ * `MutableStateFlow` read-state instead of deriving from DataManager).
+ * See `docs/parity-gallery.md` "Known limitations" for the history.
+ *
+ * Workflow / write-only (no read-state to mirror):
+ *   * `TaskCompletionViewModel`  — single-shot create mutation
+ *   * `OnboardingViewModel`       — wizard form + per-step ApiResult
+ *   * `PasswordResetViewModel`    — wizard form + per-step ApiResult
+ *
+ * Everyone else must accept the `dataManager` ctor param.
+ */
+class NoIndependentViewModelStateFileScanTest {
+
+    @Test
+    fun every_read_state_vm_accepts_iDataManager_ctor_param() {
+        val vmSources = findViewModelSources()
+        val violations = mutableListOf<String>()
+
+        vmSources.forEach { file ->
+            val name = file.name
+            if (name in WORKFLOW_ONLY_VMS) return@forEach
+
+            val body = file.readText()
+            val hasCtorParam = body.contains(Regex("""dataManager:\s*IDataManager"""))
+            if (!hasCtorParam) {
+                violations.add(
+                    "$name — expected `dataManager: IDataManager = DataManager` " +
+                        "constructor parameter. Without this, read-state can't derive " +
+                        "from the DataManager single source of truth and snapshot " +
+                        "tests can't substitute a fixture. " +
+                        "If this VM genuinely has no read-state (workflow / mutation only), " +
+                        "add its filename to WORKFLOW_ONLY_VMS with justification.",
+                )
+            }
+        }
+
+        if (violations.isNotEmpty()) {
+            fail(
+                "ViewModel architecture regression (see docs/parity-gallery.md):\n" +
+                    violations.joinToString(separator = "\n") { "  - $it" },
+            )
+        }
+    }
+
+    @Test
+    fun read_state_flows_should_be_derived_not_independent() {
+        val vmSources = findViewModelSources()
+        val violations = mutableListOf<String>()
+
+        // Names of fields that track one-shot mutation/workflow feedback —
+        // exempt from the "must be derived" rule.
+        val mutationFieldPrefixes = listOf(
+            "create", "update", "delete", "toggle", "download",
+            "upload", "archive", "unarchive", "cancel", "uncancel",
+            "mark", "generate", "request", "submit", "login", "register",
+            "reset", "forgot", "verify", "apple", "google",
+            "join", "addNew", "addTask", "taskAddNew",
+            "action", "currentStep", "resetToken", "email", "selected",
+            // Local-only state not cached by DataManager:
+            "category", // NotificationPreferencesViewModel per-channel local toggles
+        )
+
+        vmSources.forEach { file ->
+            val name = file.name
+            if (name in WORKFLOW_ONLY_VMS) return@forEach
+            if (name == "AuthViewModel.kt") return@forEach  // 11 one-shot states, all mutation-feedback; allowlisted as a file
+
+            val body = file.readText()
+            val mutableReads = Regex("""private val (_[a-zA-Z]+State)\s*=\s*MutableStateFlow""")
+                .findAll(body).map { it.groupValues[1] }.toList()
+
+            mutableReads.forEach { fieldName ->
+                val root = fieldName.removePrefix("_").removeSuffix("State")
+                val isMutationFeedback = mutationFieldPrefixes.any {
+                    root.lowercase().startsWith(it.lowercase())
+                }
+                if (!isMutationFeedback) {
+                    violations.add(
+                        "$name — field `$fieldName` looks like cached read-state " +
+                            "(not matching any mutation-feedback prefix). Derive it from " +
+                            "DataManager via `dataManager.xxx.map { ... }.stateIn(...)` " +
+                            "instead of owning a MutableStateFlow. If this field really " +
+                            "is mutation feedback, add its name prefix to " +
+                            "mutationFieldPrefixes in this test.",
+                    )
+                }
+            }
+        }
+
+        if (violations.isNotEmpty()) {
+            fail(
+                "ViewModel state-ownership regression (see docs/parity-gallery.md):\n" +
+                    violations.joinToString(separator = "\n") { "  - $it" },
+            )
+        }
+    }
+
+    private fun findViewModelSources(): List<File> {
+        // Test cwd is `composeApp/` — resolve from the project dir.
+        val vmDir = File("src/commonMain/kotlin/com/tt/honeyDue/viewmodel")
+        check(vmDir.exists()) {
+            "expected VM source directory not found: ${vmDir.absolutePath} (cwd=${File(".").absolutePath})"
+        }
+        return vmDir.listFiles { f -> f.extension == "kt" }?.toList().orEmpty()
+    }
+
+    companion object {
+        /** VMs that legitimately don't need DataManager injection. */
+        val WORKFLOW_ONLY_VMS: Set<String> = setOf(
+            "TaskCompletionViewModel.kt",
+            "OnboardingViewModel.kt",
+            "PasswordResetViewModel.kt",
+        )
+    }
+}

composeApp/src/androidUnitTest/kotlin/com/tt/honeyDue/network/CoilAuthInterceptorTest.kt

@@ -25,10 +25,14 @@ import kotlin.test.assertTrue
 /**
  * Unit tests for [CoilAuthInterceptor].
  *
+ * Identity is owned by Ory Kratos. Authenticated honeyDue media is gated on
+ * the Kratos session token, carried on the `X-Session-Token` header (the old
+ * `Authorization: Token …` scheme is gone).
+ *
  * The interceptor is responsible for:
- *  1. Attaching `Authorization: <scheme> <token>` to image requests.
- *  2. On HTTP 401, calling the refresh callback once and retrying the
- *     request with the new token.
+ *  1. Attaching `X-Session-Token: <token>` to image requests.
+ *  2. On HTTP 401, calling the re-validation callback once and retrying the
+ *     request with the returned token.
  *  3. Not looping: if the retry also returns 401, the error is returned.
  *  4. When no token is available, the request proceeds unauthenticated.
  *
@@ -96,7 +100,7 @@ class CoilAuthInterceptorTest {
     }
 
     @Test
-    fun interceptor_attaches_authorization_header_when_token_present() = runTest {
+    fun interceptor_attaches_session_token_header_when_token_present() = runTest {
         val request = makeRequest()
         val chain = FakeChain(
             initialRequest = request,
@@ -105,7 +109,6 @@ class CoilAuthInterceptorTest {
         val interceptor = CoilAuthInterceptor(
             tokenProvider = { "abc123" },
             refreshToken = { null },
-            authScheme = "Token",
         )
 
         val result = interceptor.intercept(chain)
@@ -113,7 +116,9 @@ class CoilAuthInterceptorTest {
         assertTrue(result is SuccessResult, "Expected success result")
         assertEquals(1, chain.capturedRequests.size)
         val sent = chain.capturedRequests.first()
-        assertEquals("Token abc123", sent.httpHeaders["Authorization"])
+        // Token is sent bare (no scheme prefix) on the X-Session-Token header.
+        assertEquals("abc123", sent.httpHeaders["X-Session-Token"])
+        assertNull(sent.httpHeaders["Authorization"], "Legacy Authorization header must not be set")
     }
 
     @Test
@@ -126,7 +131,6 @@ class CoilAuthInterceptorTest {
         val interceptor = CoilAuthInterceptor(
             tokenProvider = { null },
             refreshToken = { null },
-            authScheme = "Token",
         )
 
         val result = interceptor.intercept(chain)
@@ -134,12 +138,12 @@ class CoilAuthInterceptorTest {
         assertTrue(result is SuccessResult)
         assertEquals(1, chain.capturedRequests.size)
         val sent = chain.capturedRequests.first()
-        // No Authorization header should have been added
-        assertNull(sent.httpHeaders["Authorization"])
+        // No session-token header should have been added.
+        assertNull(sent.httpHeaders["X-Session-Token"])
     }
 
     @Test
-    fun interceptor_refreshes_and_retries_on_401() = runTest {
+    fun interceptor_revalidates_and_retries_on_401() = runTest {
         val request = makeRequest()
         var refreshCallCount = 0
         val chain = FakeChain(
@@ -150,25 +154,25 @@ class CoilAuthInterceptorTest {
             )
         )
         val interceptor = CoilAuthInterceptor(
-            tokenProvider = { "old-token" },
+            tokenProvider = { "session-tok" },
             refreshToken = {
                 refreshCallCount++
-                "new-token"
+                // Kratos session tokens are not rotated — same token echoed back.
+                "session-tok"
             },
-            authScheme = "Token",
         )
 
         val result = interceptor.intercept(chain)
 
         assertTrue(result is SuccessResult, "Expected retry to succeed")
-        assertEquals(1, refreshCallCount, "refreshToken should be invoked exactly once")
+        assertEquals(1, refreshCallCount, "session re-check should be invoked exactly once")
         assertEquals(2, chain.capturedRequests.size, "Expected original + 1 retry")
-        assertEquals("Token old-token", chain.capturedRequests[0].httpHeaders["Authorization"])
-        assertEquals("Token new-token", chain.capturedRequests[1].httpHeaders["Authorization"])
+        assertEquals("session-tok", chain.capturedRequests[0].httpHeaders["X-Session-Token"])
+        assertEquals("session-tok", chain.capturedRequests[1].httpHeaders["X-Session-Token"])
     }
 
     @Test
-    fun interceptor_returns_error_when_refresh_returns_null() = runTest {
+    fun interceptor_returns_error_when_revalidation_returns_null() = runTest {
         val request = makeRequest()
         var refreshCallCount = 0
         val chain = FakeChain(
@@ -176,19 +180,18 @@ class CoilAuthInterceptorTest {
             responses = mutableListOf({ req -> make401Error(req) })
         )
         val interceptor = CoilAuthInterceptor(
-            tokenProvider = { "old-token" },
+            tokenProvider = { "session-tok" },
             refreshToken = {
                 refreshCallCount++
                 null
             },
-            authScheme = "Token",
         )
 
         val result = interceptor.intercept(chain)
 
-        assertTrue(result is ErrorResult, "Expected error result when refresh fails")
-        assertEquals(1, refreshCallCount, "refreshToken should be attempted once")
-        // Only the first attempt should have gone through
+        assertTrue(result is ErrorResult, "Expected error result when session is gone")
+        assertEquals(1, refreshCallCount, "session re-check should be attempted once")
+        // Only the first attempt should have gone through.
         assertEquals(1, chain.capturedRequests.size)
     }
 
@@ -204,23 +207,22 @@ class CoilAuthInterceptorTest {
             )
         )
         val interceptor = CoilAuthInterceptor(
-            tokenProvider = { "old-token" },
+            tokenProvider = { "session-tok" },
             refreshToken = {
                 refreshCallCount++
-                "new-token"
+                "session-tok"
             },
-            authScheme = "Token",
         )
 
         val result = interceptor.intercept(chain)
 
         assertTrue(result is ErrorResult, "Second 401 should surface as ErrorResult")
-        assertEquals(1, refreshCallCount, "refreshToken should be called exactly once — no infinite loop")
+        assertEquals(1, refreshCallCount, "session re-check should be called exactly once — no infinite loop")
         assertEquals(2, chain.capturedRequests.size, "Expected original + exactly one retry")
     }
 
     @Test
-    fun interceptor_passes_through_non_401_errors_without_refresh() = runTest {
+    fun interceptor_passes_through_non_401_errors_without_revalidation() = runTest {
         val request = makeRequest()
         var refreshCallCount = 0
         val chain = FakeChain(
@@ -241,33 +243,32 @@ class CoilAuthInterceptorTest {
                 refreshCallCount++
                 "should-not-be-called"
             },
-            authScheme = "Token",
         )
 
         val result = interceptor.intercept(chain)
 
         assertTrue(result is ErrorResult)
-        assertEquals(0, refreshCallCount, "refreshToken should not be invoked on non-401 errors")
+        assertEquals(0, refreshCallCount, "session re-check should not be invoked on non-401 errors")
         assertEquals(1, chain.capturedRequests.size)
     }
 
     @Test
-    fun interceptor_supports_bearer_scheme() = runTest {
+    fun interceptor_supports_custom_header_name() = runTest {
         val request = makeRequest()
         val chain = FakeChain(
             initialRequest = request,
             responses = mutableListOf({ req -> makeSuccess(req) })
         )
         val interceptor = CoilAuthInterceptor(
-            tokenProvider = { "jwt.payload.sig" },
+            tokenProvider = { "tok-value" },
             refreshToken = { null },
-            authScheme = "Bearer",
+            headerName = "X-Custom-Auth",
         )
 
         val result = interceptor.intercept(chain)
 
         assertTrue(result is SuccessResult)
         val sent = chain.capturedRequests.first()
-        assertEquals("Bearer jwt.payload.sig", sent.httpHeaders["Authorization"])
+        assertEquals("tok-value", sent.httpHeaders["X-Custom-Auth"])
     }
 }

composeApp/src/androidUnitTest/kotlin/com/tt/honeyDue/network/LiveAuthIntegrationTest.kt

@@ -0,0 +1,68 @@
+package com.tt.honeyDue.network
+
+import com.tt.honeyDue.data.DataManager
+import com.tt.honeyDue.models.RegisterRequest
+import com.tt.honeyDue.models.VerifyEmailRequest
+import kotlinx.coroutines.runBlocking
+import org.junit.Assume.assumeTrue
+import org.junit.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertNotNull
+import kotlin.test.assertTrue
+
+/**
+ * LIVE end-to-end integration test: drives the REAL [AuthApi] (the exact client
+ * code the app runs, OkHttp engine, production URLs from ApiConfig) against the
+ * live honeyDue API + Ory Kratos. No fixtures, no hand-written JSON — every
+ * response is decoded by the real models over the wire, so a contract mismatch
+ * between the API and the KMP client fails here.
+ *
+ * Skipped unless RUN_LIVE_IT=1 (it creates a real throwaway account and needs
+ * network), so it never runs on a normal build/CI. Run explicitly:
+ *   RUN_LIVE_IT=1 ./gradlew :composeApp:testDebugUnitTest \
+ *     --tests "com.tt.honeyDue.network.LiveAuthIntegrationTest"
+ */
+class LiveAuthIntegrationTest {
+
+    private fun liveEnabled() = System.getenv("RUN_LIVE_IT") == "1"
+
+    @Test
+    fun passwordSignupFlowAgainstProd() = runBlocking {
+        assumeTrue("set RUN_LIVE_IT=1 to run the live integration test", liveEnabled())
+
+        val api = AuthApi() // ApiClient.httpClient (OkHttp) + PROD URLs
+        val email = "kmpqa-" + System.currentTimeMillis() + "@example.com"
+        val password = "KmpQa1!Test99"
+
+        // 1. Register: admin-create via /api/auth/register/ then immediate login.
+        //    Exercises the createAccount HTTP call AND the login decode that
+        //    crashed on "continue_with": null.
+        val reg = api.register(
+            RegisterRequest(username = "kmpqa", email = email, password = password, firstName = "Kmp", lastName = "Qa"),
+        )
+        assertTrue(reg is ApiResult.Success, "register should succeed, got: $reg")
+        val auth = (reg as ApiResult.Success).data
+        assertTrue(auth.token.isNotBlank(), "session token must be present")
+        assertEquals(email, auth.user.email)
+        assertFalse(auth.user.verified, "a fresh password account must start unverified")
+
+        // 2. /auth/me decodes through the ApiClient json config (User model).
+        val me = api.getCurrentUser(auth.token)
+        assertTrue(me is ApiResult.Success, "auth/me should succeed, got: $me")
+        assertEquals(email, (me as ApiResult.Success).data.email)
+
+        // 3. Start the client-owned verification flow — decodes the flow body and
+        //    stores the flow id; sends the single code.
+        val started = api.startEmailVerification(email)
+        assertTrue(started is ApiResult.Success, "startEmailVerification should succeed, got: $started")
+        assertNotNull(DataManager.pendingVerificationFlowId.value, "a verification flow id must be stored")
+
+        // 4. Submit a deliberately wrong code: must decode the re-rendered flow
+        //    and return a clean Error (not a parse crash).
+        val wrong = api.verifyEmail(auth.token, VerifyEmailRequest(code = "000000"))
+        assertTrue(wrong is ApiResult.Error, "wrong code must return Error, got: $wrong")
+
+        DataManager.setPendingVerificationFlowId(null)
+    }
+}

composeApp/src/androidUnitTest/kotlin/com/tt/honeyDue/screenshot/GalleryManifestParityTest.kt

@@ -0,0 +1,68 @@
+package com.tt.honeyDue.screenshot
+
+import com.tt.honeyDue.testing.GalleryScreens
+import com.tt.honeyDue.testing.Platform
+import org.junit.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+/**
+ * Parity gate — asserts [gallerySurfaces] is exactly the set of screens
+ * declared in [GalleryScreens] with [Platform.ANDROID] in their platforms.
+ *
+ * If this fails, either:
+ *   - A new screen was added to [gallerySurfaces] but missing from the
+ *     canonical manifest — update [GalleryScreens.all].
+ *   - A new screen was added to the manifest but not wired into
+ *     [gallerySurfaces] — add the corresponding `GallerySurface(...)`
+ *     entry.
+ *   - A rename landed on only one side — reconcile.
+ *
+ * This keeps Android and iOS from silently drifting apart in coverage.
+ * The iOS equivalent (`GalleryManifestParityTest.swift`) enforces the
+ * same invariant on the Swift test file.
+ */
+class GalleryManifestParityTest {
+
+    @Test
+    fun android_surfaces_match_manifest_exactly() {
+        val actual = gallerySurfaces.map { it.name }.toSet()
+        val expected = GalleryScreens.forAndroid.keys
+
+        val missing = expected - actual
+        val extra = actual - expected
+
+        if (missing.isNotEmpty() || extra.isNotEmpty()) {
+            val message = buildString {
+                appendLine("Android GallerySurfaces drifted from canonical manifest.")
+                if (missing.isNotEmpty()) {
+                    appendLine()
+                    appendLine("Screens in manifest but missing from GallerySurfaces.kt:")
+                    missing.sorted().forEach { appendLine("  - $it") }
+                }
+                if (extra.isNotEmpty()) {
+                    appendLine()
+                    appendLine("Screens in GallerySurfaces.kt but missing from manifest:")
+                    extra.sorted().forEach { appendLine("  - $it") }
+                }
+                appendLine()
+                appendLine("Reconcile by editing com.tt.honeyDue.testing.GalleryScreens and/or")
+                appendLine("com.tt.honeyDue.screenshot.GallerySurfaces so both agree.")
+            }
+            kotlin.test.fail(message)
+        }
+        assertEquals(expected, actual)
+    }
+
+    @Test
+    fun no_duplicate_surface_names() {
+        val duplicates = gallerySurfaces.map { it.name }
+            .groupingBy { it }
+            .eachCount()
+            .filterValues { it > 1 }
+        assertTrue(
+            duplicates.isEmpty(),
+            "Duplicate surface names in GallerySurfaces.kt: $duplicates",
+        )
+    }
+}

composeApp/src/androidUnitTest/kotlin/com/tt/honeyDue/screenshot/GallerySurfaces.kt

@@ -2,6 +2,7 @@
 package com.tt.honeyDue.screenshot
 
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
 import com.tt.honeyDue.testing.Fixtures
 import com.tt.honeyDue.ui.screens.AddDocumentScreen
 import com.tt.honeyDue.ui.screens.AddResidenceScreen
@@ -25,11 +26,10 @@ import com.tt.honeyDue.ui.screens.RegisterScreen
 import com.tt.honeyDue.ui.screens.ResetPasswordScreen
 import com.tt.honeyDue.ui.screens.ResidenceDetailScreen
 import com.tt.honeyDue.ui.screens.ResidencesScreen
-import com.tt.honeyDue.ui.screens.TasksScreen
 import com.tt.honeyDue.ui.screens.VerifyEmailScreen
 import com.tt.honeyDue.ui.screens.VerifyResetCodeScreen
-import com.tt.honeyDue.ui.screens.dev.AnimationTestingScreen
 import com.tt.honeyDue.ui.screens.onboarding.OnboardingCreateAccountContent
+import com.tt.honeyDue.ui.screens.onboarding.OnboardingFirstTaskContent
 import com.tt.honeyDue.ui.screens.onboarding.OnboardingHomeProfileContent
 import com.tt.honeyDue.ui.screens.onboarding.OnboardingJoinResidenceContent
 import com.tt.honeyDue.ui.screens.onboarding.OnboardingLocationContent
@@ -40,34 +40,44 @@ import com.tt.honeyDue.ui.screens.onboarding.OnboardingVerifyEmailContent
 import com.tt.honeyDue.ui.screens.onboarding.OnboardingWelcomeContent
 import com.tt.honeyDue.ui.screens.residence.JoinResidenceScreen
 import com.tt.honeyDue.ui.screens.subscription.FeatureComparisonScreen
+import com.tt.honeyDue.ui.screens.task.AddTaskWithResidenceScreen
 import com.tt.honeyDue.ui.screens.task.TaskSuggestionsScreen
 import com.tt.honeyDue.ui.screens.task.TaskTemplatesBrowserScreen
 import com.tt.honeyDue.ui.screens.theme.ThemeSelectionScreen
+import com.tt.honeyDue.viewmodel.ContractorViewModel
+import com.tt.honeyDue.viewmodel.DocumentViewModel
 import com.tt.honeyDue.viewmodel.OnboardingViewModel
 import com.tt.honeyDue.viewmodel.PasswordResetViewModel
 
 /**
- * Declarative manifest of every primary screen in the app that the parity
- * gallery captures. Each entry renders the production composable directly —
- * the screen reads its data from [com.tt.honeyDue.data.LocalDataManager],
- * which the capture driver overrides with a [com.tt.honeyDue.testing.FixtureDataManager]
- * (empty or populated) per variant.
+ * Declarative manifest of every Android gallery surface. Must stay in sync
+ * with the canonical [com.tt.honeyDue.testing.GalleryScreens] manifest —
+ * [GalleryManifestParityTest] fails CI if the two drift.
  *
  * Scope: the screens users land on. We deliberately skip:
  *   - dialogs that live inside a host screen (already captured on the host),
  *   - animation sub-views / decorative components in AnimationTesting/,
  *   - widget views (Android Glance / iOS WidgetKit — separate surface),
- *   - shared helper composables listed under `category: shared` in
- *     docs/ios-parity/screens.json (loaders, error rows, thumbnails — they
+ *   - shared helper composables (loaders, error rows, thumbnails — they
  *     only appear as part of a parent screen).
  *
- * Screens that require a construction-time ViewModel (`OnboardingViewModel`,
- * `PasswordResetViewModel`) instantiate it inline here. The production code
- * paths start the viewmodel's own `launch { APILayer.xxx() }` on first
- * composition — those calls fail fast in the hermetic Robolectric
- * environment, but the composition itself renders the surface from the
- * injected [com.tt.honeyDue.data.LocalDataManager] before any network
- * result arrives, which is exactly what we want to compare against iOS.
+ * Detail-VM pattern (contractor_detail, document_detail, edit_document):
+ * the VM is created with the fixture id already pre-selected, so
+ * `stateIn(SharingStarted.Eagerly, initialValue = dataManager.x[id])`
+ * emits `Success(entity)` on first composition. Without this pre-select,
+ * the screens' own `LaunchedEffect(id) { vm.loadX(id) }` dispatches the id
+ * assignment to a coroutine that runs *after* Roborazzi captures the
+ * frame — so both empty and populated captures would render the `Idle`
+ * state and be byte-identical.
+ *
+ * Screens that require a construction-time ViewModel
+ * ([OnboardingViewModel], [PasswordResetViewModel]) instantiate it inline
+ * here. The production code paths start the viewmodel's own
+ * `launch { APILayer.xxx() }` on first composition — those calls fail fast
+ * in the hermetic Robolectric environment, but the composition itself
+ * renders the surface from the injected
+ * [com.tt.honeyDue.data.LocalDataManager] before any network result
+ * arrives, which is exactly what we want to compare against iOS.
  */
 data class GallerySurface(
     /** Snake-case identifier; used as the golden file-name prefix. */
@@ -177,6 +187,12 @@ val gallerySurfaces: List<GallerySurface> = listOf(
             onJoined = {},
         )
     },
+    GallerySurface("onboarding_first_task") {
+        OnboardingFirstTaskContent(
+            viewModel = OnboardingViewModel(),
+            onTasksAdded = {},
+        )
+    },
     GallerySurface("onboarding_subscription") {
         OnboardingSubscriptionContent(
             onSubscribe = {},
@@ -184,7 +200,7 @@ val gallerySurfaces: List<GallerySurface> = listOf(
         )
     },
 
-    // ---------- Home / main navigation ----------
+    // ---------- Home (Android-only dashboard) ----------
     GallerySurface("home") {
         HomeScreen(
             onNavigateToResidences = {},
@@ -240,12 +256,16 @@ val gallerySurfaces: List<GallerySurface> = listOf(
     },
 
     // ---------- Tasks ----------
-    GallerySurface("tasks") {
-        TasksScreen(onNavigateBack = {})
-    },
     GallerySurface("all_tasks") {
         AllTasksScreen(onNavigateToEditTask = {})
     },
+    GallerySurface("add_task_with_residence") {
+        AddTaskWithResidenceScreen(
+            residenceId = Fixtures.primaryHome.id,
+            onNavigateBack = {},
+            onCreated = {},
+        )
+    },
     GallerySurface("edit_task") {
         EditTaskScreen(
             task = Fixtures.tasks.first(),
@@ -285,9 +305,20 @@ val gallerySurfaces: List<GallerySurface> = listOf(
         )
     },
     GallerySurface("contractor_detail") {
+        val id = Fixtures.contractors.first().id
+        // Pass `initialSelectedContractorId` at VM construction so the
+        // synchronous `stateIn` initial-value closure observes both the
+        // id AND the fixture-seeded `dataManager.contractorDetail[id]`,
+        // emitting `Success(contractor)` on first composition. Without
+        // this the screen's own `LaunchedEffect(id) { vm.loadContractorDetail(id) }`
+        // dispatches the id assignment to a coroutine that runs after
+        // the frame is captured, leaving both empty and populated
+        // captures byte-identical on the `Idle` branch.
+        val vm = remember { ContractorViewModel(initialSelectedContractorId = id) }
         ContractorDetailScreen(
-            contractorId = Fixtures.contractors.first().id,
+            contractorId = id,
             onNavigateBack = {},
+            viewModel = vm,
         )
     },
 
@@ -299,10 +330,13 @@ val gallerySurfaces: List<GallerySurface> = listOf(
         )
     },
     GallerySurface("document_detail") {
+        val id = Fixtures.documents.first().id ?: 0
+        val vm = remember { DocumentViewModel(initialSelectedDocumentId = id) }
         DocumentDetailScreen(
-            documentId = Fixtures.documents.first().id ?: 0,
+            documentId = id,
             onNavigateBack = {},
-            onNavigateToEdit = {},
+            onNavigateToEdit = { _ -> },
+            documentViewModel = vm,
         )
     },
     GallerySurface("add_document") {
@@ -313,9 +347,12 @@ val gallerySurfaces: List<GallerySurface> = listOf(
         )
     },
     GallerySurface("edit_document") {
+        val id = Fixtures.documents.first().id ?: 0
+        val vm = remember { DocumentViewModel(initialSelectedDocumentId = id) }
         EditDocumentScreen(
-            documentId = Fixtures.documents.first().id ?: 0,
+            documentId = id,
             onNavigateBack = {},
+            documentViewModel = vm,
         )
     },
 
@@ -326,14 +363,11 @@ val gallerySurfaces: List<GallerySurface> = listOf(
             onLogout = {},
         )
     },
-    GallerySurface("theme_selection") {
-        ThemeSelectionScreen(onNavigateBack = {})
-    },
     GallerySurface("notification_preferences") {
         NotificationPreferencesScreen(onNavigateBack = {})
     },
-    GallerySurface("animation_testing") {
-        AnimationTestingScreen(onNavigateBack = {})
+    GallerySurface("theme_selection") {
+        ThemeSelectionScreen(onNavigateBack = {})
     },
     GallerySurface("biometric_lock") {
         BiometricLockScreen(onUnlocked = {})

composeApp/src/androidUnitTest/kotlin/com/tt/honeyDue/screenshot/ScreenshotTests.kt

@@ -6,54 +6,60 @@ import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.CompositionLocalProvider
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalInspectionMode
 import androidx.test.core.app.ApplicationProvider
 import com.github.takahirom.roborazzi.captureRoboImage
 import com.tt.honeyDue.data.IDataManager
 import com.tt.honeyDue.data.LocalDataManager
 import com.tt.honeyDue.testing.FixtureDataManager
+import com.tt.honeyDue.testing.GalleryCategory
+import com.tt.honeyDue.testing.GalleryScreens
 import com.tt.honeyDue.ui.theme.AppThemes
 import com.tt.honeyDue.ui.theme.HoneyDueTheme
 import org.junit.Before
 import org.junit.Test
 import org.junit.runner.RunWith
 import org.robolectric.ParameterizedRobolectricTestRunner
+import org.robolectric.Shadows.shadowOf
 import org.robolectric.annotation.Config
 import org.robolectric.annotation.GraphicsMode
 
 /**
- * Parity-gallery Roborazzi snapshot tests (P2).
+ * Parity-gallery Roborazzi snapshot tests.
  *
- * For every entry in [gallerySurfaces] we capture four variants:
- *   empty × light,  empty × dark,  populated × light,  populated × dark
+ * Variant matrix (driven by [GalleryCategory] in the canonical
+ * [GalleryScreens] manifest):
  *
- * Per surface that's 4 PNGs × ~40 surfaces ≈ 160 goldens. Paired with the
- * iOS swift-snapshot-testing gallery (P3) that captures the same set of
- * (screen, data, theme) tuples, any visual divergence between the two
- * platforms surfaces here as a golden diff rather than silently shipping.
+ *   DataCarrying surfaces — capture 4 variants:
+ *     surface_empty_light.png      (empty fixture, no lookups,  light)
+ *     surface_empty_dark.png       (empty fixture, no lookups,  dark)
+ *     surface_populated_light.png  (populated fixture,          light)
+ *     surface_populated_dark.png   (populated fixture,          dark)
  *
- * How this differs from the showcase tests that lived here before:
- *   - Showcases rendered hand-crafted theme-agnostic surfaces; now we
- *     render the actual production composables (`LoginScreen(…)`, etc.)
- *     through the fixture-backed [LocalDataManager].
- *   - Surfaces are declared in [GallerySurfaces.kt] instead of being
- *     inlined, so adding a new screen is a one-line change.
- *   - Previously 6 surfaces × 3 themes × 2 modes; now the matrix is
- *     N surfaces × {empty, populated} × {light, dark} — themes beyond
- *     the default are intentionally out of scope (theme variation is
- *     covered by the dedicated theme_selection surface).
+ *   DataFree surfaces — capture 2 variants:
+ *     surface_light.png            (empty fixture, lookups seeded, light)
+ *     surface_dark.png             (empty fixture, lookups seeded, dark)
  *
- * One parameterized test per surface gives granular CI failures — the
+ *   The `empty` fixture for DataCarrying variants passes
+ *   `seedLookups = false` so form dropdowns render their empty state
+ *   (yielding a visible populated-vs-empty diff for forms that read
+ *   lookups from `DataManager`). The `empty` fixture for DataFree
+ *   variants passes `seedLookups = true` because those screens expect
+ *   realistic production lookups even when the user has no entities yet.
+ *
+ *   DataFree surfaces omit the populated variant entirely — the screens
+ *   render no entity data, so `populated` would be byte-identical to
+ *   `empty` and add zero signal.
+ *
+ * Granular CI failures: one parameterized test per surface means the
  * report shows `ScreenshotTests[login]`, `ScreenshotTests[tasks]`, etc.
  * rather than one monolithic failure when any surface drifts.
  *
  * Why the goldens land directly under `src/androidUnitTest/roborazzi/`:
  * Roborazzi resolves `captureRoboImage(filePath = …)` relative to the
  * Gradle test task's working directory (the module root). Writing to
- * the same directory where goldens are committed means record and verify
- * round-trip through one canonical location; we never have to copy
- * between a transient `build/outputs/roborazzi/` and the committed
- * fixture directory (which was the source of the pre-existing
- * "original file was not found" failure).
+ * the same directory where goldens are committed means record and
+ * verify round-trip through one canonical location.
  */
 @RunWith(ParameterizedRobolectricTestRunner::class)
 @GraphicsMode(GraphicsMode.Mode.NATIVE)
@@ -64,24 +70,15 @@ class ScreenshotTests(
 
     /**
      * Compose Multiplatform's `stringResource()` loads text via a
-     * JVM-static context held by `AndroidContextProvider`. In a real APK
-     * that ContentProvider is registered in the manifest and populated at
-     * app start; under Robolectric unit tests it never runs, so every
-     * `stringResource(...)` call throws "Android context is not
-     * initialized."
-     *
-     * `PreviewContextConfigurationEffect()` is the documented fix — but
-     * it only fires inside `LocalInspectionMode = true`, and even then
-     * the first composition frame renders before the effect lands, so
-     * `stringResource()` calls race the context set.
+     * JVM-static context held by `AndroidContextProvider`. Under
+     * Robolectric unit tests the `ContentProvider` that normally
+     * populates it never runs, so every `stringResource(...)` call throws
+     * "Android context is not initialized."
      *
      * Install the context eagerly via reflection before each test.
-     * `AndroidContextProvider` is `internal` in Kotlin, so we can't
-     * touch its class directly — but its static slot is writable
-     * through the generated `Companion.setANDROID_CONTEXT` accessor.
-     * `@Before` runs inside the Robolectric sandbox (where
-     * `ApplicationProvider` is valid); `@BeforeClass` would run outside
-     * it and fail with "No instrumentation registered!".
+     * `AndroidContextProvider` is `internal`, but its static slot is
+     * writable through the generated `Companion.setANDROID_CONTEXT`
+     * accessor.
      */
     @Before
     fun bootstrapComposeResources() {
@@ -95,17 +92,67 @@ class ScreenshotTests(
 
     @Test
     fun captureAllVariants() {
-        Variant.all().forEach { variant ->
-            val fileName = "${surface.name}_${variant.state}_${variant.mode}.png"
+        val screen = GalleryScreens.forAndroid[surface.name]
+            ?: error(
+                "Surface '${surface.name}' is in GallerySurfaces.kt but not in " +
+                    "GalleryScreens.all (canonical manifest). " +
+                    "GalleryManifestParityTest should have caught this.",
+            )
+
+        val variants = when (screen.category) {
+            GalleryCategory.DataCarrying -> Variant.dataCarrying
+            GalleryCategory.DataFree -> Variant.dataFree
+        }
+
+        variants.forEach { variant ->
+            val fileName = "${surface.name}${variant.fileSuffix}.png"
             val fixture = variant.dataManager()
-            // Seed the global DataManager singleton from the fixture. Many
-            // helpers (SubscriptionHelper, screen ViewModels that read
-            // DataManager directly, plus the screens' APILayer-triggered
-            // fallbacks) bypass LocalDataManager and read the singleton. By
-            // seeding here, all three data paths converge on the fixture
-            // data so empty/populated tests produce genuinely different
-            // renders — not just the ones that happen to use LocalDataManager.
+            seedSingleton(fixture)
+            // Flush the main-thread Looper so any `stateIn(... Eagerly)`
+            // collectors on VMs reused across captures have processed the
+            // DataManager update before we snapshot. Without this, VMs
+            // might see the previous variant's data because coroutine
+            // emissions race the capture call.
+            shadowOf(android.os.Looper.getMainLooper()).idle()
+            captureRoboImage(filePath = "src/androidUnitTest/roborazzi/$fileName") {
+                HoneyDueTheme(
+                    themeColors = AppThemes.Default,
+                    darkTheme = variant.darkTheme,
+                ) {
+                    // `LocalInspectionMode = true` signals to production
+                    // composables that they're rendering in a hermetic
+                    // preview/test environment. Camera pickers, gated push
+                    // registrations, and animation callbacks use this flag
+                    // to short-circuit calls that require real Android
+                    // subsystems (e.g. `FileProvider` paths that aren't
+                    // resolvable under Robolectric's test data dir).
+                    CompositionLocalProvider(
+                        LocalDataManager provides fixture,
+                        LocalInspectionMode provides true,
+                    ) {
+                        Box(Modifier.fillMaxSize()) {
+                            surface.content()
+                        }
+                    }
+                }
+            }
+        }
+        // Reset after suite so other tests don't inherit state.
+        com.tt.honeyDue.data.DataManager.setSubscription(null)
+    }
+
+    /**
+     * Mirror every StateFlow on `fixture` onto the `DataManager` singleton
+     * so code paths that bypass `LocalDataManager` (screens that call
+     * `DataManager.x` directly, VMs whose default-arg resolves to the
+     * singleton, `SubscriptionHelper` free-tier gate) see the same data.
+     *
+     * Critical: clear the singleton first so the previous variant's
+     * writes don't leak into this variant's `empty` render.
+     */
+    private fun seedSingleton(fixture: IDataManager) {
         val dm = com.tt.honeyDue.data.DataManager
+        dm.clear()
         dm.setSubscription(fixture.subscription.value)
         dm.setCurrentUser(fixture.currentUser.value)
         fixture.myResidences.value?.let { dm.setMyResidences(it) }
@@ -119,21 +166,18 @@ class ScreenshotTests(
         dm.setTaskCategories(fixture.taskCategories.value)
         dm.setTaskPriorities(fixture.taskPriorities.value)
         dm.setTaskFrequencies(fixture.taskFrequencies.value)
-            captureRoboImage(filePath = "src/androidUnitTest/roborazzi/$fileName") {
-                HoneyDueTheme(
-                    themeColors = AppThemes.Default,
-                    darkTheme = variant.darkTheme,
-                ) {
-                    CompositionLocalProvider(LocalDataManager provides fixture) {
-                        Box(Modifier.fillMaxSize()) {
-                            surface.content()
+        fixture.contractorsByResidence.value.forEach { (rid, list) ->
+            dm.setContractorsForResidence(rid, list)
         }
+        fixture.contractorDetail.value.values.forEach { dm.setContractorDetail(it) }
+        fixture.documentDetail.value.values.forEach { dm.setDocumentDetail(it) }
+        fixture.taskCompletions.value.forEach { (taskId, completions) ->
+            dm.setTaskCompletions(taskId, completions)
         }
+        fixture.tasksByResidence.value.forEach { (rid, cols) ->
+            dm.setTasksForResidence(rid, cols)
         }
-            }
-        }
-        // Reset after suite so other tests don't inherit state.
-        com.tt.honeyDue.data.DataManager.setSubscription(null)
+        fixture.notificationPreferences.value?.let { dm.setNotificationPreferences(it) }
     }
 
     companion object {
@@ -145,23 +189,48 @@ class ScreenshotTests(
 }
 
 /**
- * One of the four render-variants captured per surface. The
- * `dataManager` factory is invoked lazily so each capture gets its own
- * pristine fixture (avoiding cross-test StateFlow mutation).
+ * One render-variant captured per surface. The `dataManager` factory is
+ * invoked lazily so each capture gets a pristine fixture (avoiding
+ * cross-test StateFlow mutation).
+ *
+ * @property fileSuffix Appended to the surface name to form the PNG
+ *   filename. Includes a leading `_`. Examples: `_empty_light`,
+ *   `_populated_dark`, `_light`, `_dark`.
  */
 private data class Variant(
-    val state: String,
-    val mode: String,
+    val fileSuffix: String,
     val darkTheme: Boolean,
     val dataManager: () -> IDataManager,
 ) {
     companion object {
-        fun all(): List<Variant> = listOf(
-            Variant("empty", "light", darkTheme = false) { FixtureDataManager.empty() },
-            Variant("empty", "dark",  darkTheme = true)  { FixtureDataManager.empty() },
-            Variant("populated", "light", darkTheme = false) { FixtureDataManager.populated() },
-            Variant("populated", "dark",  darkTheme = true)  { FixtureDataManager.populated() },
+        /**
+         * DataCarrying surfaces: 4 variants. `empty` captures pass
+         * `seedLookups = false` so form dropdowns render empty in the
+         * empty-variant PNGs — letting screens that read lookups produce
+         * a visible diff against the populated variant.
+         */
+        val dataCarrying: List<Variant> = listOf(
+            Variant("_empty_light", darkTheme = false) {
+                FixtureDataManager.empty(seedLookups = false)
+            },
+            Variant("_empty_dark", darkTheme = true) {
+                FixtureDataManager.empty(seedLookups = false)
+            },
+            Variant("_populated_light", darkTheme = false) { FixtureDataManager.populated() },
+            Variant("_populated_dark", darkTheme = true) { FixtureDataManager.populated() },
+        )
+
+        /**
+         * DataFree surfaces: 2 variants (light/dark only). Lookups are
+         * seeded because forms expect them to be present in production
+         * (a user with zero entities still sees the priority picker).
+         * The populated variant is deliberately omitted — DataFree
+         * surfaces render no entity data, so `populated` would be
+         * byte-identical to `empty`.
+         */
+        val dataFree: List<Variant> = listOf(
+            Variant("_light", darkTheme = false) { FixtureDataManager.empty(seedLookups = true) },
+            Variant("_dark", darkTheme = true) { FixtureDataManager.empty(seedLookups = true) },
         )
     }
 }
-

composeApp/src/androidUnitTest/kotlin/com/tt/honeyDue/widget/WidgetResidenceFilterTest.kt

@@ -0,0 +1,140 @@
+package com.tt.honeyDue.widget
+
+import android.content.Context
+import androidx.test.core.app.ApplicationProvider
+import kotlinx.coroutines.test.runTest
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+/**
+ * Coverage for the per-residence widget filter added in gitea#6.
+ *
+ * Two surfaces under test:
+ *
+ *  1. `WidgetDataRepository.filterTasksForResidence` — the pure filter
+ *     used by `loadTasksForResidence` and (transitively) by the
+ *     timeline provider. Mirrors iOS' `WidgetDataManager.filterTasks`.
+ *  2. The per-`appWidgetId` DataStore key — verifies round-tripping
+ *     a saved residence id and clearing it for a removed widget.
+ */
+@RunWith(RobolectricTestRunner::class)
+class WidgetResidenceFilterTest {
+
+    private lateinit var context: Context
+    private lateinit var repo: WidgetDataRepository
+
+    @Before
+    fun setUp() = runTest {
+        context = ApplicationProvider.getApplicationContext()
+        repo = WidgetDataRepository.get(context)
+        repo.clearAll()
+    }
+
+    @After
+    fun tearDown() = runTest {
+        repo.clearAll()
+    }
+
+    private fun task(id: Long, residenceId: Long): WidgetTaskDto =
+        WidgetTaskDto(
+            id = id,
+            title = "Task $id",
+            priority = 0,
+            dueDate = null,
+            isOverdue = false,
+            daysUntilDue = 0,
+            residenceId = residenceId,
+            residenceName = "",
+            categoryIcon = "",
+            completed = false
+        )
+
+    // --- pure filter -------------------------------------------------------
+
+    @Test
+    fun filter_nullResidenceReturnsAllTasks() {
+        val tasks = listOf(task(1, 10), task(2, 20), task(3, 30))
+        val result = WidgetDataRepository.filterTasksForResidence(tasks, residenceId = null)
+        assertEquals(listOf(1L, 2L, 3L), result.map { it.id })
+    }
+
+    @Test
+    fun filter_matchingResidenceKeepsOnlyMatchingTasks() {
+        val tasks = listOf(task(1, 10), task(2, 20), task(3, 10), task(4, 30))
+        val result = WidgetDataRepository.filterTasksForResidence(tasks, residenceId = 10)
+        assertEquals(listOf(1L, 3L), result.map { it.id })
+    }
+
+    @Test
+    fun filter_unknownResidenceReturnsEmpty() {
+        val tasks = listOf(task(1, 10), task(2, 20))
+        val result = WidgetDataRepository.filterTasksForResidence(tasks, residenceId = 999)
+        assertTrue(result.isEmpty())
+    }
+
+    @Test
+    fun filter_preservesInputOrder() {
+        // Subset only — the timeline provider relies on this so its
+        // own sort step ("overdue first, then by due date") operates
+        // on already-filtered tasks.
+        val tasks = listOf(task(5, 1), task(3, 1), task(7, 1), task(1, 2))
+        val result = WidgetDataRepository.filterTasksForResidence(tasks, residenceId = 1)
+        assertEquals(listOf(5L, 3L, 7L), result.map { it.id })
+    }
+
+    // --- DataStore round-trip ---------------------------------------------
+
+    @Test
+    fun perWidgetResidenceId_roundTripsThroughDataStore() = runTest {
+        // Initial state: no scope persisted → returns null ("All residences").
+        assertNull(repo.loadResidenceIdFor(appWidgetId = 42))
+
+        repo.saveResidenceIdFor(appWidgetId = 42, residenceId = 7L)
+        assertEquals(7L, repo.loadResidenceIdFor(appWidgetId = 42))
+
+        // Different widget id stays unscoped — keys are per-instance.
+        assertNull(repo.loadResidenceIdFor(appWidgetId = 99))
+
+        // Save null clears the scope ("All residences" selected after a
+        // previously residence-scoped tile).
+        repo.saveResidenceIdFor(appWidgetId = 42, residenceId = null)
+        assertNull(repo.loadResidenceIdFor(appWidgetId = 42))
+    }
+
+    @Test
+    fun loadTasksForWidget_appliesPerInstanceScope() = runTest {
+        repo.saveTasks(listOf(task(1, 10), task(2, 20), task(3, 10)))
+        repo.saveResidenceIdFor(appWidgetId = 1, residenceId = 10L)
+        repo.saveResidenceIdFor(appWidgetId = 2, residenceId = 20L)
+
+        assertEquals(listOf(1L, 3L), repo.loadTasksForWidget(1).map { it.id })
+        assertEquals(listOf(2L), repo.loadTasksForWidget(2).map { it.id })
+        // Unconfigured tile defaults to "All residences" — every task.
+        assertEquals(listOf(1L, 2L, 3L), repo.loadTasksForWidget(3).map { it.id })
+    }
+
+    @Test
+    fun clearResidenceIdFor_dropsScope() = runTest {
+        repo.saveResidenceIdFor(appWidgetId = 5, residenceId = 11L)
+        assertEquals(11L, repo.loadResidenceIdFor(5))
+
+        repo.clearResidenceIdFor(5)
+        assertNull(repo.loadResidenceIdFor(5))
+    }
+
+    @Test
+    fun saveResidences_roundTripsResidenceList() = runTest {
+        val payload = listOf(
+            WidgetResidenceDto(id = 1, name = "Home"),
+            WidgetResidenceDto(id = 2, name = "Cabin")
+        )
+        repo.saveResidences(payload)
+        assertEquals(payload, repo.loadResidences())
+    }
+}