chore(android): update companion apk download

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Android/app/build.gradle.kts

@@ -11,8 +11,8 @@ android {
         applicationId = "com.archipelago.app"
         minSdk = 26
         targetSdk = 35
-        versionCode = 16
-        versionName = "0.4.12"
+        versionCode = 17
+        versionName = "0.4.13"
 
         vectorDrawables {
             useSupportLibrary = true
@@ -111,6 +111,12 @@ dependencies {
     // OkHttp for WebSocket (remote input)
     implementation("com.squareup.okhttp3:okhttp:4.12.0")
 
+    // CameraX + ZXing (Apache-2.0, on-device, no telemetry) for pairing-QR scanning
+    implementation("androidx.camera:camera-camera2:1.3.4")
+    implementation("androidx.camera:camera-lifecycle:1.3.4")
+    implementation("androidx.camera:camera-view:1.3.4")
+    implementation("com.google.zxing:core:3.5.3")
+
     debugImplementation("androidx.compose.ui:ui-tooling")
     debugImplementation("androidx.compose.ui:ui-test-manifest")
 }

Android/app/src/main/AndroidManifest.xml

@@ -4,6 +4,9 @@
 
     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <!-- Pairing-QR scanner. Camera is optional: manual entry still works without one. -->
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-feature android:name="android.hardware.camera.any" android:required="false" />
 
     <application
         android:name=".ArchipelagoApp"
@@ -19,6 +22,7 @@
         <activity
             android:name=".MainActivity"
             android:exported="true"
+            android:launchMode="singleTask"
             android:theme="@style/Theme.Archipelago.Splash"
             android:windowSoftInputMode="adjustResize"
             android:configChanges="orientation|screenSize|screenLayout|keyboardHidden">
@@ -26,6 +30,14 @@
                 <action android:name="android.intent.action.MAIN" />
                 <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
+            <!-- Pairing deep link from the web UI's Companion popup:
+                 archipelago://pair?v=1&url=...[&pw=...] (docs/companion-pairing-qr.md) -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="archipelago" android:host="pair" />
+            </intent-filter>
         </activity>
     </application>
 

Android/app/src/main/java/com/archipelago/app/MainActivity.kt

@@ -1,22 +1,41 @@
 package com.archipelago.app
 
+import android.content.Intent
 import android.os.Bundle
 import androidx.activity.ComponentActivity
 import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
 import androidx.core.splashscreen.SplashScreen.Companion.installSplashScreen
 import com.archipelago.app.ui.navigation.AppNavHost
 import com.archipelago.app.ui.theme.ArchipelagoTheme
+import kotlinx.coroutines.flow.MutableStateFlow
 
 class MainActivity : ComponentActivity() {
+
+    // Pairing deep link (archipelago://pair?...) from the launch intent or a
+    // later one (launchMode=singleTask). Consumed by AppNavHost.
+    private val pendingPairUri = MutableStateFlow<String?>(null)
+
     override fun onCreate(savedInstanceState: Bundle?) {
         installSplashScreen()
         enableEdgeToEdge()
         super.onCreate(savedInstanceState)
+        pendingPairUri.value = intent?.dataString
         setContent {
             ArchipelagoTheme {
-                AppNavHost()
+                val pairUri by pendingPairUri.collectAsState()
+                AppNavHost(
+                    pairUri = pairUri,
+                    onPairUriConsumed = { pendingPairUri.value = null },
+                )
             }
         }
     }
+
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        pendingPairUri.value = intent.dataString
+    }
 }

Android/app/src/main/java/com/archipelago/app/data/ServerPreferences.kt

@@ -143,6 +143,39 @@ class ServerPreferences(private val context: Context) {
         }
     }
 
+    /**
+     * Add a server, or update the entry with the same connection identity
+     * (address/port/scheme) — used by QR pairing so re-scanning a node never
+     * duplicates it. A blank incoming password/name keeps the stored value
+     * (a real node's QR never carries the password). Returns the merged entry.
+     */
+    suspend fun upsertServer(server: ServerEntry): ServerEntry {
+        var merged = server
+        context.dataStore.edit { prefs ->
+            val current = prefs[savedServersKey] ?: emptySet()
+            val existing = current.mapNotNull { ServerEntry.deserialize(it) }.firstOrNull {
+                it.address == server.address &&
+                    it.port == server.port &&
+                    it.useHttps == server.useHttps
+            }
+            if (existing != null) {
+                merged = server.copy(
+                    password = server.password.ifBlank { existing.password },
+                    name = server.name.ifBlank { existing.name },
+                )
+            }
+            val filtered = current.filterNot { raw ->
+                val e = ServerEntry.deserialize(raw)
+                e != null &&
+                    e.address == server.address &&
+                    e.port == server.port &&
+                    e.useHttps == server.useHttps
+            }.toSet()
+            prefs[savedServersKey] = filtered + merged.serialize()
+        }
+        return merged
+    }
+
     suspend fun removeSavedServer(server: ServerEntry) {
         context.dataStore.edit { prefs ->
             val current = prefs[savedServersKey] ?: emptySet()

Android/app/src/main/java/com/archipelago/app/data/ServerQrParser.kt

@@ -0,0 +1,67 @@
+package com.archipelago.app.data
+
+import android.net.Uri
+
+/**
+ * Result of parsing a pairing QR / deep link.
+ *
+ * UnsupportedVersion means the payload is structurally a pairing URI but its
+ * major version is newer than this app understands — the UI should tell the
+ * user to update the app rather than call the code invalid.
+ */
+sealed class PairResult {
+    data class Success(val server: ServerEntry) : PairResult()
+    object UnsupportedVersion : PairResult()
+    object Invalid : PairResult()
+}
+
+/**
+ * Parser for the companion pairing QR / OS deep link. Contract:
+ * docs/companion-pairing-qr.md (repo root).
+ *
+ *   archipelago://pair?v=1&url=<percent-encoded origin>[&pw=<password>]
+ *
+ * - `url` is a full origin including scheme (http for LAN/mDNS nodes, https
+ *   for the public demo); trailing slashes are normalized away.
+ * - `pw` is only ever present for the public demo.
+ * - Unknown extra query params are tolerated (forward compat under v=1 —
+ *   `name` is already honored if present).
+ */
+object ServerQrParser {
+    private const val SUPPORTED_MAJOR = 1
+
+    fun parse(raw: String): PairResult {
+        val uri = try {
+            Uri.parse(raw.trim())
+        } catch (_: Exception) {
+            return PairResult.Invalid
+        }
+        if (!"archipelago".equals(uri.scheme, ignoreCase = true)) return PairResult.Invalid
+        if (uri.isOpaque || !"pair".equals(uri.host, ignoreCase = true)) return PairResult.Invalid
+
+        val major = uri.getQueryParameter("v")
+            ?.trim()
+            ?.takeWhile { it.isDigit() }
+            ?.toIntOrNull()
+            ?: return PairResult.Invalid
+        if (major != SUPPORTED_MAJOR) return PairResult.UnsupportedVersion
+
+        val serverUrl = uri.getQueryParameter("url")?.trim()?.trimEnd('/')
+        if (serverUrl.isNullOrBlank()) return PairResult.Invalid
+        val server = Uri.parse(serverUrl)
+        val scheme = server.scheme?.lowercase()
+        if (scheme != "http" && scheme != "https") return PairResult.Invalid
+        val host = server.host
+        if (host.isNullOrBlank()) return PairResult.Invalid
+
+        return PairResult.Success(
+            ServerEntry(
+                address = host,
+                useHttps = scheme == "https",
+                port = if (server.port != -1) server.port.toString() else "",
+                password = uri.getQueryParameter("pw") ?: "",
+                name = uri.getQueryParameter("name") ?: "",
+            )
+        )
+    }
+}

Android/app/src/main/java/com/archipelago/app/ui/components/NESMenu.kt

@@ -24,6 +24,9 @@ import androidx.compose.foundation.layout.widthIn
 import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.foundation.text.KeyboardActions
 import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.QrCodeScanner
+import androidx.compose.material3.Icon
 import androidx.compose.material3.OutlinedTextField
 import androidx.compose.material3.OutlinedTextFieldDefaults
 import androidx.compose.material3.Text
@@ -36,6 +39,7 @@ import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
 import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.res.stringResource
 import androidx.compose.ui.text.TextStyle
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.input.ImeAction
@@ -44,6 +48,7 @@ import androidx.compose.ui.text.input.PasswordVisualTransformation
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
+import com.archipelago.app.R
 import com.archipelago.app.data.ServerEntry
 import com.archipelago.app.ui.theme.BitcoinOrange
 import com.archipelago.app.ui.theme.ControllerStyle
@@ -75,6 +80,7 @@ fun NESMenu(
     onDismiss: () -> Unit,
     onSelectServer: (ServerEntry) -> Unit,
     onAddServer: (ServerEntry) -> Unit,
+    onScanQr: (() -> Unit)? = null,
     onEditServer: (ServerEntry, ServerEntry) -> Unit,
     onRemoveServer: (ServerEntry) -> Unit,
     onToggleMode: () -> Unit,
@@ -88,7 +94,7 @@ fun NESMenu(
             contentAlignment = Alignment.Center,
         ) {
             AnimatedVisibility(visible = visible, enter = fadeIn() + scaleIn(initialScale = 0.95f), exit = fadeOut() + scaleOut(targetScale = 0.95f)) {
-                MenuPanel(servers, activeServer, isGamepadMode, controllerStyle, onDismiss, onSelectServer, onAddServer, onEditServer, onRemoveServer, onToggleMode, onToggleStyle, onBackToWebView)
+                MenuPanel(servers, activeServer, isGamepadMode, controllerStyle, onDismiss, onSelectServer, onAddServer, onScanQr, onEditServer, onRemoveServer, onToggleMode, onToggleStyle, onBackToWebView)
             }
         }
     }
@@ -103,6 +109,7 @@ private fun MenuPanel(
     onDismiss: () -> Unit,
     onSelectServer: (ServerEntry) -> Unit,
     onAddServer: (ServerEntry) -> Unit,
+    onScanQr: (() -> Unit)?,
     onEditServer: (ServerEntry, ServerEntry) -> Unit,
     onRemoveServer: (ServerEntry) -> Unit,
     onToggleMode: () -> Unit,
@@ -235,7 +242,30 @@ private fun MenuPanel(
                 }
             }
         } else {
-            MenuItem(label = "Add Server", labelColor = BitcoinOrange, onClick = { showAdd = true })
+            Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.spacedBy(10.dp)) {
+                Box(Modifier.weight(1f)) {
+                    MenuItem(label = "Add Server", labelColor = BitcoinOrange, onClick = { showAdd = true })
+                }
+                if (onScanQr != null) {
+                    // Add server by scanning the node's pairing QR
+                    Box(
+                        Modifier
+                            .size(ROW_H)
+                            .clip(RoundedCornerShape(ROW_R))
+                            .background(RowBg)
+                            .border(1.dp, RowBorder, RoundedCornerShape(ROW_R))
+                            .clickable { onScanQr() },
+                        contentAlignment = Alignment.Center,
+                    ) {
+                        Icon(
+                            Icons.Default.QrCodeScanner,
+                            contentDescription = stringResource(R.string.add_server_qr),
+                            tint = BitcoinOrange,
+                            modifier = Modifier.size(24.dp),
+                        )
+                    }
+                }
+            }
         }
 
         Spacer(Modifier.height(2.dp))

Android/app/src/main/java/com/archipelago/app/ui/components/QrScannerOverlay.kt

@@ -0,0 +1,298 @@
+package com.archipelago.app.ui.components
+
+import android.Manifest
+import android.content.pm.PackageManager
+import androidx.activity.compose.BackHandler
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.camera.core.CameraSelector
+import androidx.camera.core.ImageAnalysis
+import androidx.camera.core.ImageProxy
+import androidx.camera.core.Preview
+import androidx.camera.lifecycle.ProcessCameraProvider
+import androidx.camera.view.PreviewView
+import androidx.compose.animation.AnimatedVisibility
+import androidx.compose.animation.fadeIn
+import androidx.compose.animation.fadeOut
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.WindowInsets
+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.layout.safeDrawing
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.windowInsetsPadding
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Close
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberUpdatedState
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.platform.LocalLifecycleOwner
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.viewinterop.AndroidView
+import androidx.core.content.ContextCompat
+import com.archipelago.app.R
+import com.archipelago.app.data.PairResult
+import com.archipelago.app.data.ServerEntry
+import com.archipelago.app.data.ServerQrParser
+import com.archipelago.app.ui.screens.GlassButton
+import com.archipelago.app.ui.theme.BitcoinOrange
+import com.archipelago.app.ui.theme.TextMuted
+import com.archipelago.app.ui.theme.TextPrimary
+import com.google.zxing.BarcodeFormat
+import com.google.zxing.BinaryBitmap
+import com.google.zxing.DecodeHintType
+import com.google.zxing.MultiFormatReader
+import com.google.zxing.NotFoundException
+import com.google.zxing.PlanarYUVLuminanceSource
+import com.google.zxing.common.HybridBinarizer
+import kotlinx.coroutines.delay
+import java.util.concurrent.Executors
+
+/**
+ * Full-screen camera overlay that scans the node pairing QR
+ * (docs/companion-pairing-qr.md) and reports the decoded server entry.
+ * Handles the camera permission itself; foreign/invalid codes show a hint
+ * and scanning continues.
+ */
+@Composable
+fun QrScannerOverlay(
+    visible: Boolean,
+    onDismiss: () -> Unit,
+    onServerScanned: (ServerEntry) -> Unit,
+) {
+    val context = LocalContext.current
+    var hasPermission by remember {
+        mutableStateOf(
+            ContextCompat.checkSelfPermission(context, Manifest.permission.CAMERA) ==
+                PackageManager.PERMISSION_GRANTED
+        )
+    }
+    var hintRes by remember { mutableStateOf<Int?>(null) }
+    var handled by remember { mutableStateOf(false) }
+
+    val permissionLauncher = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission()
+    ) { granted -> hasPermission = granted }
+
+    LaunchedEffect(visible) {
+        if (visible) {
+            handled = false
+            hintRes = null
+            val granted = ContextCompat.checkSelfPermission(context, Manifest.permission.CAMERA) ==
+                PackageManager.PERMISSION_GRANTED
+            hasPermission = granted
+            if (!granted) permissionLauncher.launch(Manifest.permission.CAMERA)
+        }
+    }
+
+    // Foreign-code hint fades after a moment so scanning feels live again.
+    LaunchedEffect(hintRes) {
+        if (hintRes != null) {
+            delay(2500)
+            hintRes = null
+        }
+    }
+
+    AnimatedVisibility(visible = visible, enter = fadeIn(), exit = fadeOut()) {
+        BackHandler { onDismiss() }
+        Box(
+            Modifier
+                .fillMaxSize()
+                .background(Color.Black),
+        ) {
+            if (hasPermission) {
+                CameraQrPreview(
+                    onDecoded = { text ->
+                        if (!handled) {
+                            when (val result = ServerQrParser.parse(text)) {
+                                is PairResult.Success -> {
+                                    handled = true
+                                    onServerScanned(result.server)
+                                }
+                                is PairResult.UnsupportedVersion -> hintRes = R.string.update_app_for_qr
+                                is PairResult.Invalid -> hintRes = R.string.invalid_pairing_qr
+                            }
+                        }
+                    },
+                )
+                // Aim frame
+                Box(
+                    Modifier
+                        .align(Alignment.Center)
+                        .size(260.dp)
+                        .border(2.dp, BitcoinOrange.copy(alpha = 0.85f), RoundedCornerShape(20.dp)),
+                )
+            } else {
+                Column(
+                    Modifier
+                        .align(Alignment.Center)
+                        .padding(horizontal = 32.dp),
+                    horizontalAlignment = Alignment.CenterHorizontally,
+                    verticalArrangement = Arrangement.spacedBy(16.dp),
+                ) {
+                    Text(
+                        text = stringResource(R.string.camera_permission_needed),
+                        color = TextPrimary,
+                        style = MaterialTheme.typography.bodyLarge,
+                        textAlign = TextAlign.Center,
+                    )
+                    GlassButton(
+                        text = stringResource(R.string.grant_camera_access),
+                        onClick = { permissionLauncher.launch(Manifest.permission.CAMERA) },
+                        modifier = Modifier.fillMaxWidth().height(56.dp),
+                    )
+                }
+            }
+
+            // Top bar: title + close
+            Row(
+                Modifier
+                    .fillMaxWidth()
+                    .windowInsetsPadding(WindowInsets.safeDrawing)
+                    .padding(horizontal = 8.dp, vertical = 4.dp),
+                verticalAlignment = Alignment.CenterVertically,
+                horizontalArrangement = Arrangement.SpaceBetween,
+            ) {
+                Text(
+                    text = stringResource(R.string.scan_node_qr),
+                    color = TextPrimary,
+                    style = MaterialTheme.typography.titleMedium,
+                    modifier = Modifier.padding(start = 12.dp),
+                )
+                IconButton(onClick = onDismiss) {
+                    Icon(Icons.Default.Close, stringResource(R.string.close), tint = TextPrimary)
+                }
+            }
+
+            // Bottom hints
+            Column(
+                Modifier
+                    .align(Alignment.BottomCenter)
+                    .windowInsetsPadding(WindowInsets.safeDrawing)
+                    .padding(horizontal = 32.dp, vertical = 24.dp),
+                horizontalAlignment = Alignment.CenterHorizontally,
+            ) {
+                hintRes?.let { res ->
+                    Text(
+                        text = stringResource(res),
+                        color = BitcoinOrange,
+                        style = MaterialTheme.typography.bodyMedium,
+                        textAlign = TextAlign.Center,
+                    )
+                    Spacer(Modifier.height(8.dp))
+                }
+                if (hasPermission) {
+                    Text(
+                        text = stringResource(R.string.scan_qr_hint),
+                        color = TextMuted,
+                        style = MaterialTheme.typography.bodyMedium,
+                        textAlign = TextAlign.Center,
+                    )
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun CameraQrPreview(onDecoded: (String) -> Unit) {
+    val context = LocalContext.current
+    val lifecycleOwner = LocalLifecycleOwner.current
+    val currentOnDecoded by rememberUpdatedState(onDecoded)
+    val previewView = remember {
+        PreviewView(context).apply { scaleType = PreviewView.ScaleType.FILL_CENTER }
+    }
+
+    DisposableEffect(Unit) {
+        val analysisExecutor = Executors.newSingleThreadExecutor()
+        val mainExecutor = ContextCompat.getMainExecutor(context)
+        val providerFuture = ProcessCameraProvider.getInstance(context)
+        var provider: ProcessCameraProvider? = null
+
+        providerFuture.addListener({
+            val p = providerFuture.get()
+            provider = p
+            val preview = Preview.Builder().build().also {
+                it.setSurfaceProvider(previewView.surfaceProvider)
+            }
+            val analysis = ImageAnalysis.Builder()
+                .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
+                .build()
+                .also {
+                    it.setAnalyzer(
+                        analysisExecutor,
+                        QrCodeAnalyzer { text -> mainExecutor.execute { currentOnDecoded(text) } },
+                    )
+                }
+            try {
+                p.unbindAll()
+                p.bindToLifecycle(lifecycleOwner, CameraSelector.DEFAULT_BACK_CAMERA, preview, analysis)
+            } catch (_: Exception) {
+                // Camera unavailable — the user can dismiss and enter details manually.
+            }
+        }, mainExecutor)
+
+        onDispose {
+            provider?.unbindAll()
+            analysisExecutor.shutdown()
+        }
+    }
+
+    AndroidView(factory = { previewView }, modifier = Modifier.fillMaxSize())
+}
+
+/** ZXing-based QR decoder over the camera's Y (luminance) plane. */
+private class QrCodeAnalyzer(private val onDecoded: (String) -> Unit) : ImageAnalysis.Analyzer {
+    private val reader = MultiFormatReader().apply {
+        setHints(mapOf(DecodeHintType.POSSIBLE_FORMATS to listOf(BarcodeFormat.QR_CODE)))
+    }
+
+    override fun analyze(image: ImageProxy) {
+        try {
+            val plane = image.planes[0]
+            val buffer = plane.buffer
+            // Copy into a rowStride-wide array; the last row of the plane buffer
+            // may be short of the full stride, so the tail stays zero-padded.
+            val data = ByteArray(plane.rowStride * image.height)
+            buffer.get(data, 0, minOf(buffer.remaining(), data.size))
+            val source = PlanarYUVLuminanceSource(
+                data, plane.rowStride, image.height,
+                0, 0, image.width, image.height,
+                false,
+            )
+            val result = reader.decodeWithState(BinaryBitmap(HybridBinarizer(source)))
+            onDecoded(result.text)
+        } catch (_: NotFoundException) {
+            // No QR in this frame — keep scanning.
+        } catch (_: Exception) {
+            // Malformed frame; skip it.
+        } finally {
+            reader.reset()
+            image.close()
+        }
+    }
+}

Android/app/src/main/java/com/archipelago/app/ui/navigation/NavGraph.kt

@@ -1,15 +1,21 @@
 package com.archipelago.app.ui.navigation
 
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.platform.LocalContext
 import androidx.navigation.compose.NavHost
 import androidx.navigation.compose.composable
 import androidx.navigation.compose.rememberNavController
+import com.archipelago.app.data.PairResult
+import com.archipelago.app.data.ServerEntry
 import com.archipelago.app.data.ServerPreferences
+import com.archipelago.app.data.ServerQrParser
 import com.archipelago.app.ui.screens.IntroScreen
 import com.archipelago.app.ui.screens.RemoteInputScreen
 import com.archipelago.app.ui.screens.ServerConnectScreen
@@ -24,7 +30,10 @@ object Routes {
 }
 
 @Composable
-fun AppNavHost() {
+fun AppNavHost(
+    pairUri: String? = null,
+    onPairUriConsumed: () -> Unit = {},
+) {
     val context = LocalContext.current
     val prefs = remember { ServerPreferences(context) }
     val navController = rememberNavController()
@@ -33,8 +42,41 @@ fun AppNavHost() {
     val introSeen by prefs.introSeen.collectAsState(initial = null)
     val activeServer by prefs.activeServer.collectAsState(initial = null)
 
+    // Pairing entry from a deep link that carried no password — prefills the
+    // connect form so the user lands on the password prompt for that server.
+    var pairPrefill by remember { mutableStateOf<ServerEntry?>(null) }
+
     if (introSeen == null) return
 
+    // Declared after the introSeen gate so it can't fire before the NavHost
+    // below has set the nav graph; pairUri stays pending until consumed here.
+    LaunchedEffect(pairUri) {
+        val raw = pairUri ?: return@LaunchedEffect
+        onPairUriConsumed()
+        when (val result = ServerQrParser.parse(raw)) {
+            is PairResult.Success -> {
+                // Pairing implies the app is installed and in use — skip the intro.
+                prefs.markIntroSeen()
+                val merged = prefs.upsertServer(result.server)
+                if (merged.password.isNotBlank()) {
+                    // Demo flow: password came with the link — connect in one step.
+                    prefs.setActiveServer(merged)
+                    navController.navigate(Routes.WEB_VIEW) {
+                        popUpTo(0) { inclusive = true }
+                    }
+                } else {
+                    pairPrefill = merged
+                    navController.navigate(Routes.SERVER_CONNECT) {
+                        popUpTo(0) { inclusive = true }
+                    }
+                }
+            }
+            else -> {
+                // Invalid or too-new pairing link — ignore; normal startup continues.
+            }
+        }
+    }
+
     val startDestination = when {
         introSeen == false -> Routes.INTRO
         activeServer != null -> Routes.WEB_VIEW
@@ -65,6 +107,7 @@ fun AppNavHost() {
                         popUpTo(Routes.SERVER_CONNECT) { inclusive = true }
                     }
                 },
+                initialServer = pairPrefill,
             )
         }
 
@@ -81,6 +124,7 @@ fun AppNavHost() {
             } else {
                 WebViewScreen(
                     serverUrl = server.toUrl(),
+                    serverPassword = server.password,
                     onDisconnect = {
                         scope.launch {
                             prefs.clearActiveServer()

Android/app/src/main/java/com/archipelago/app/ui/screens/RemoteInputScreen.kt

@@ -43,6 +43,7 @@ import com.archipelago.app.ui.components.NESController
 import com.archipelago.app.ui.components.NESKeyboard
 import com.archipelago.app.ui.components.NESMenu
 import com.archipelago.app.ui.components.NESPortraitController
+import com.archipelago.app.ui.components.QrScannerOverlay
 import com.archipelago.app.ui.components.Trackpad
 import com.archipelago.app.ui.theme.BitcoinOrange
 import com.archipelago.app.ui.theme.ControllerStyle
@@ -63,6 +64,7 @@ fun RemoteInputScreen(onBack: () -> Unit) {
 
     var isGamepadMode by remember { mutableStateOf(true) }
     var showModal by remember { mutableStateOf(false) }
+    var showQrScanner by remember { mutableStateOf(false) }
     var controllerStyle by remember { mutableStateOf(ControllerStyle.DARK) }
     var playerId by remember { mutableStateOf(0) }  // 0 = broadcast, 1 = P1, 2 = P2
 
@@ -216,6 +218,7 @@ fun RemoteInputScreen(onBack: () -> Unit) {
             onAddServer = { server ->
                 scope.launch { prefs.addSavedServer(server); if (activeServer == null) prefs.setActiveServer(server) }
             },
+            onScanQr = { showQrScanner = true },
             onEditServer = { original, updated ->
                 scope.launch {
                     prefs.updateSavedServer(original, updated)
@@ -247,5 +250,19 @@ fun RemoteInputScreen(onBack: () -> Unit) {
             },
             onBackToWebView = { showModal = false; onBack() },
         )
+
+        // Pairing-QR scan launched from the menu's Add Server row. The menu stays
+        // open behind the scanner so the new entry appears as soon as it closes.
+        QrScannerOverlay(
+            visible = showQrScanner,
+            onDismiss = { showQrScanner = false },
+            onServerScanned = { server ->
+                showQrScanner = false
+                scope.launch {
+                    val merged = prefs.upsertServer(server)
+                    if (activeServer == null) prefs.setActiveServer(merged)
+                }
+            },
+        )
     }
 }

Android/app/src/main/java/com/archipelago/app/ui/screens/ServerConnectScreen.kt

@@ -43,6 +43,7 @@ import androidx.compose.material3.Switch
 import androidx.compose.material3.SwitchDefaults
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
@@ -72,6 +73,7 @@ import androidx.compose.ui.unit.sp
 import com.archipelago.app.R
 import com.archipelago.app.data.ServerEntry
 import com.archipelago.app.data.ServerPreferences
+import com.archipelago.app.ui.components.QrScannerOverlay
 import com.archipelago.app.ui.theme.BitcoinOrange
 import com.archipelago.app.ui.theme.ErrorRed
 import com.archipelago.app.ui.theme.SurfaceBlack
@@ -93,6 +95,9 @@ import javax.net.ssl.X509TrustManager
 fun ServerConnectScreen(
     onConnected: (String) -> Unit,
     onRemoteInput: () -> Unit = {},
+    // Prefill from a pairing deep link (archipelago://pair) that carried no
+    // password — opens the manual form on the password prompt for that server.
+    initialServer: ServerEntry? = null,
 ) {
     val context = LocalContext.current
     val prefs = remember { ServerPreferences(context) }
@@ -109,6 +114,9 @@ fun ServerConnectScreen(
     var errorMessage by remember { mutableStateOf<String?>(null) }
     // The saved server currently being edited, or null when adding/connecting.
     var editingServer by remember { mutableStateOf<ServerEntry?>(null) }
+    // Landing shows Scan/Manual choice; the form appears in manual mode or while editing.
+    var manualMode by remember { mutableStateOf(false) }
+    var showScanner by remember { mutableStateOf(false) }
 
     val savedServers by prefs.savedServers.collectAsState(initial = emptyList())
 
@@ -173,6 +181,37 @@ fun ServerConnectScreen(
         }
     }
 
+    fun prefill(server: ServerEntry) {
+        name = server.name
+        address = server.address
+        port = server.port
+        password = server.password
+        useHttps = server.useHttps
+    }
+
+    // Pairing QR scanned: dedupe against saved servers, then either auto-connect
+    // (payload carried a password — the demo flow) or land on the password
+    // prompt with everything else filled in (real nodes never embed one).
+    fun onQrScanned(scanned: ServerEntry) {
+        showScanner = false
+        scope.launch {
+            val merged = prefs.upsertServer(scanned)
+            prefill(merged)
+            if (merged.password.isNotBlank()) {
+                connect(merged)
+            } else {
+                manualMode = true
+            }
+        }
+    }
+
+    LaunchedEffect(initialServer) {
+        if (initialServer != null) {
+            prefill(prefs.upsertServer(initialServer))
+            manualMode = true
+        }
+    }
+
     Box(
         modifier = Modifier
             .fillMaxSize()
@@ -208,7 +247,10 @@ fun ServerConnectScreen(
                 .padding(horizontal = 24.dp)
                 .padding(top = 48.dp, bottom = 32.dp),
             horizontalAlignment = Alignment.CenterHorizontally,
-            verticalArrangement = Arrangement.spacedBy(16.dp),
+            // Center the content vertically — the landing (logo + two buttons) is
+            // short and looks stranded at the top otherwise. Taller content (the
+            // manual form, saved servers) still scrolls from the top as normal.
+            verticalArrangement = Arrangement.spacedBy(16.dp, Alignment.CenterVertically),
         ) {
             // Circular badge logo
             Image(
@@ -226,8 +268,10 @@ fun ServerConnectScreen(
                 textAlign = TextAlign.Center,
             )
 
+            val showForm = manualMode || editingServer != null
+
             Text(
-                text = stringResource(R.string.server_address_hint),
+                text = if (showForm) stringResource(R.string.server_address_hint) else stringResource(R.string.connect_landing_hint),
                 style = MaterialTheme.typography.bodyMedium,
                 color = TextMuted,
                 textAlign = TextAlign.Center,
@@ -235,8 +279,25 @@ fun ServerConnectScreen(
 
             Spacer(modifier = Modifier.height(4.dp))
 
+            if (!showForm) {
+                // Landing: scan the pairing QR, or fall back to manual entry
+                GlassButton(
+                    text = stringResource(R.string.scan_node_qr),
+                    onClick = { showScanner = true },
+                    modifier = Modifier.fillMaxWidth().height(56.dp),
+                )
+                GlassButton(
+                    text = stringResource(R.string.enter_manually),
+                    onClick = {
+                        errorMessage = null
+                        manualMode = true
+                    },
+                    modifier = Modifier.fillMaxWidth().height(56.dp),
+                )
+            }
+
             // Glass card with form
-            Box(
+            if (showForm) Box(
                 modifier = Modifier
                     .fillMaxWidth()
                     .clip(RoundedCornerShape(16.dp))
@@ -458,16 +519,30 @@ fun ServerConnectScreen(
                         modifier = Modifier.weight(1f).height(56.dp),
                     )
                 }
-            } else {
-                // Connect button — glass style
-                GlassButton(
-                    text = if (isConnecting) stringResource(R.string.connecting) else stringResource(R.string.connect),
-                    onClick = {
-                        keyboard?.hide()
-                        connect(ServerEntry(address, useHttps, port, password, name))
-                    },
-                    modifier = Modifier.fillMaxWidth().height(56.dp),
-                )
+            } else if (manualMode) {
+                // Back to the Scan/Manual landing + Connect
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalArrangement = Arrangement.spacedBy(12.dp),
+                ) {
+                    GlassButton(
+                        text = stringResource(R.string.back),
+                        onClick = {
+                            keyboard?.hide()
+                            manualMode = false
+                            clearForm()
+                        },
+                        modifier = Modifier.weight(1f).height(56.dp),
+                    )
+                    GlassButton(
+                        text = if (isConnecting) stringResource(R.string.connecting) else stringResource(R.string.connect),
+                        onClick = {
+                            keyboard?.hide()
+                            connect(ServerEntry(address, useHttps, port, password, name))
+                        },
+                        modifier = Modifier.weight(2f).height(56.dp),
+                    )
+                }
             }
 
             if (isConnecting) {
@@ -499,6 +574,12 @@ fun ServerConnectScreen(
                 }
             }
         }
+
+        QrScannerOverlay(
+            visible = showScanner,
+            onDismiss = { showScanner = false },
+            onServerScanned = { onQrScanned(it) },
+        )
     }
 }
 

Android/app/src/main/java/com/archipelago/app/ui/screens/WebViewScreen.kt

@@ -136,6 +136,10 @@ fun WebViewScreen(
     serverUrl: String,
     onDisconnect: () -> Unit,
     onRemoteInput: () -> Unit = {},
+    // Stored password for this server (from QR pairing or manual entry). When
+    // non-blank, the login page is auto-filled and submitted — the one-step
+    // demo flow from docs/companion-pairing-qr.md.
+    serverPassword: String = "",
 ) {
     var isLoading by remember { mutableStateOf(true) }
     var loadProgress by remember { mutableIntStateOf(0) }
@@ -310,6 +314,12 @@ fun WebViewScreen(
                                     """.trimIndent(),
                                     null,
                                 )
+
+                                // Auto-login with the stored password (QR pairing /
+                                // saved server) — only on our own server's pages.
+                                if (serverPassword.isNotBlank() && url != null && url.startsWith(serverUrl)) {
+                                    view.evaluateJavascript(buildAutoLoginScript(serverPassword), null)
+                                }
                             }
 
                             override fun onReceivedError(
@@ -700,3 +710,39 @@ private fun InAppBrowser(
         }
     }
 }
+
+/**
+ * JS that fills the web UI login form (Login.vue's #login-password) with the
+ * stored password and submits it once the form is interactive — the one-step
+ * pairing flow. No-ops when the login step never appears (already
+ * authenticated, first-boot setup, TOTP). At most two attempts per page load,
+ * then it stops for good so a wrong stored password can't spam the node.
+ */
+private fun buildAutoLoginScript(password: String): String {
+    val quoted = org.json.JSONObject.quote(password)
+    return """
+    (function () {
+        if (window.__archyAutoLogin) return;
+        window.__archyAutoLogin = true;
+        var pw = $quoted;
+        var attempts = 0;
+        var started = Date.now();
+        var timer = setInterval(function () {
+            if (Date.now() - started > 45000) { clearInterval(timer); return; }
+            var el = document.getElementById('login-password');
+            if (!el) {
+                // Field gone after we submitted = success or step change - stop.
+                if (attempts > 0) clearInterval(timer);
+                return;
+            }
+            if (el.disabled) return; // form waits on serverReady
+            if (attempts >= 2) { clearInterval(timer); return; }
+            attempts++;
+            var setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set;
+            setter.call(el, pw);
+            el.dispatchEvent(new Event('input', { bubbles: true }));
+            el.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+        }, 1500);
+    })();
+    """.trimIndent()
+}

Android/app/src/main/res/values/strings.xml

@@ -29,6 +29,15 @@
     <string name="server_name_label">Server Name (optional)</string>
     <string name="server_name_placeholder">My Archipelago</string>
     <string name="edit_server">Edit</string>
+    <string name="scan_node_qr">Scan Node\'s QR</string>
+    <string name="enter_manually">Enter Manually</string>
+    <string name="connect_landing_hint">Scan the pairing QR from your node\'s Companion popup, or enter the address manually</string>
+    <string name="scan_qr_hint">Point the camera at the pairing QR shown in the Companion popup</string>
+    <string name="camera_permission_needed">Camera access is needed to scan the pairing QR. You can also enter the server details manually.</string>
+    <string name="grant_camera_access">Grant Camera Access</string>
+    <string name="invalid_pairing_qr">Not an Archipelago pairing code</string>
+    <string name="update_app_for_qr">This pairing code needs a newer app version — please update the companion app</string>
+    <string name="add_server_qr">Add server by QR</string>
     <string name="edit_server_title">Edit Server</string>
     <string name="save_changes">Save Changes</string>
     <string name="cancel">Cancel</string>

core/archipelago/src/api/handler/mod.rs

@@ -194,6 +194,39 @@ impl ApiHandler {
         ))
     }
 
+    /// Serve an encrypted backup archive (`<data_dir>/backups/<id>.bak`) as a
+    /// browser download. The archive is passphrase-encrypted at rest; the
+    /// session gate at the route controls who can fetch it.
+    async fn handle_backup_download(&self, path: &str) -> Result<Response<hyper::Body>> {
+        let id = path.strip_prefix("/api/blob/backup/").unwrap_or("");
+        // Backup ids are UUIDs — reject anything that could traverse paths.
+        if id.is_empty() || !id.chars().all(|c| c.is_ascii_hexdigit() || c == '-') {
+            return Ok(build_response(
+                StatusCode::BAD_REQUEST,
+                "application/json",
+                hyper::Body::from(r#"{"error":"invalid backup id"}"#),
+            ));
+        }
+        let file = self.config.data_dir.join("backups").join(format!("{id}.bak"));
+        match tokio::fs::read(&file).await {
+            Ok(bytes) => Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("Content-Type", "application/octet-stream")
+                .header(
+                    "Content-Disposition",
+                    format!("attachment; filename=\"archipelago-backup-{id}.bak\""),
+                )
+                .header("Content-Length", bytes.len())
+                .body(hyper::Body::from(bytes))
+                .unwrap_or_else(|_| Response::new(hyper::Body::from("Internal error")))),
+            Err(_) => Ok(build_response(
+                StatusCode::NOT_FOUND,
+                "application/json",
+                hyper::Body::from(r#"{"error":"backup not found"}"#),
+            )),
+        }
+    }
+
     /// Build a 401 Unauthorized JSON response.
     fn unauthorized() -> Response<hyper::Body> {
         let body = serde_json::json!({ "error": "Unauthorized" });
@@ -434,6 +467,16 @@ impl ApiHandler {
                 Self::handle_mesh_typed_relay(self.rpc_handler.clone(), body_bytes).await
             }
 
+            // Backup archive download — session-gated. Lives under /api/blob/
+            // so the existing nginx `location /api/blob` prefix proxies it on
+            // every fleet node without a config change.
+            (Method::GET, p) if p.starts_with("/api/blob/backup/") => {
+                if !self.is_authenticated(&headers).await {
+                    return Ok(Self::unauthorized());
+                }
+                self.handle_backup_download(p).await
+            }
+
             // Blob upload — local/session use only. Session-authenticated so
             // only the node owner can push attachments into the blob store.
             (Method::POST, "/api/blob") => {

core/archipelago/src/api/rpc/package/dependencies.rs

@@ -246,6 +246,11 @@ pub(super) fn check_install_deps(package_id: &str, deps: &RunningDeps) -> Result
 pub(super) const DEP_WAIT_INTERVAL: std::time::Duration = std::time::Duration::from_secs(5);
 /// 36 × 5s = 3 minutes of bounded waiting.
 pub(super) const DEP_WAIT_MAX_ATTEMPTS: u32 = 36;
+/// Separate, much larger budget while a dependency is still INSTALLING
+/// (image pulling, container not created yet): 360 × 5s = 30 minutes. A
+/// fresh-node Bitcoin pull routinely takes >3 minutes, and rejecting LND
+/// mid-pull was the confirmed "first install fails, second works" failure.
+pub(super) const DEP_INSTALLING_WAIT_MAX_ATTEMPTS: u32 = 360;
 
 /// Marker error: the install was rejected by the dependency gate BEFORE any
 /// resource (container, image, data dir) was created for the package. The
@@ -317,8 +322,12 @@ pub(super) struct DepProbe {
     /// Which dependency services are currently Running.
     pub running: RunningDeps,
     /// Container/package names that EXIST in any state — installed, but
-    /// possibly not running yet (`podman ps -a` ∪ package-state entries).
+    /// possibly not running yet (`podman ps -a`).
     pub existing: Vec<String>,
+    /// Package ids currently mid-install (state Installing/Updating) —
+    /// no container exists yet, but one is on the way, so the gate must
+    /// wait for the install to finish instead of failing fast.
+    pub installing: Vec<String>,
 }
 
 /// All container names known to podman in any state (`podman ps -a`).
@@ -366,8 +375,13 @@ where
     LF: std::future::Future<Output = ()>,
 {
     let mut waited_attempts = 0u32;
+    let mut installing_attempts = 0u32;
     loop {
-        let DepProbe { running, existing } = probe().await?;
+        let DepProbe {
+            running,
+            existing,
+            installing,
+        } = probe().await?;
         let missing = missing_install_deps(package_id, &running);
         if missing.is_empty() {
             // Keep behavior in lockstep with the canonical gate (covers any
@@ -377,11 +391,12 @@ where
         }
 
         // Fail fast if any missing dependency has no installed container
-        // under any name variant — waiting cannot satisfy it.
+        // under any name variant AND no install in flight — waiting cannot
+        // satisfy it.
         let some_dep_not_installed = missing.iter().any(|dep| {
-            !dep.containers
-                .iter()
-                .any(|c| existing.iter().any(|e| e == c))
+            !dep.containers.iter().any(|c| {
+                existing.iter().any(|e| e == c) || installing.iter().any(|i| i == c)
+            })
         });
         if some_dep_not_installed {
             let msg = match check_install_deps(package_id, &running) {
@@ -391,8 +406,38 @@ where
             return Err(anyhow::Error::new(DependencyGateError(msg)));
         }
 
+        // A dependency still mid-install (no container yet) gets its own,
+        // much larger budget: a fresh-node image pull can take far longer
+        // than the started-but-not-running window.
+        let some_dep_installing = missing.iter().any(|dep| {
+            dep.containers
+                .iter()
+                .any(|c| installing.iter().any(|i| i == c))
+        });
+
+        let labels = join_dep_labels(&missing);
+        if some_dep_installing {
+            if installing_attempts >= DEP_INSTALLING_WAIT_MAX_ATTEMPTS {
+                return Err(anyhow::Error::new(DependencyGateError(format!(
+                    "{labels} is still installing after {} seconds. Wait for it \
+                     to finish, then install {package_id} again.",
+                    u64::from(DEP_INSTALLING_WAIT_MAX_ATTEMPTS) * interval.as_secs()
+                ))));
+            }
+            installing_attempts += 1;
+            if installing_attempts == 1 {
+                info!(
+                    "Install {package_id}: dependency {labels} is still installing — \
+                     waiting up to {}s for it to finish",
+                    u64::from(DEP_INSTALLING_WAIT_MAX_ATTEMPTS) * interval.as_secs()
+                );
+            }
+            on_waiting(format!("Waiting for {labels} to finish installing…")).await;
+            tokio::time::sleep(interval).await;
+            continue;
+        }
+
         if waited_attempts >= max_attempts {
-            let labels = join_dep_labels(&missing);
             return Err(anyhow::Error::new(DependencyGateError(format!(
                 "{labels} is installed but did not reach the running state within \
                  {} seconds. Start {labels}, then install {package_id} again.",
@@ -401,7 +446,6 @@ where
         }
         waited_attempts += 1;
 
-        let labels = join_dep_labels(&missing);
         if waited_attempts == 1 {
             info!(
                 "Install {package_id}: dependency {labels} installed but not running yet — \
@@ -874,9 +918,19 @@ mod tests {
         }
 
         fn probe(has_bitcoin: bool, has_electrumx: bool, existing: &[&str]) -> DepProbe {
+            probe_with_installing(has_bitcoin, has_electrumx, existing, &[])
+        }
+
+        fn probe_with_installing(
+            has_bitcoin: bool,
+            has_electrumx: bool,
+            existing: &[&str],
+            installing: &[&str],
+        ) -> DepProbe {
             DepProbe {
                 running: deps(has_bitcoin, has_electrumx),
                 existing: existing.iter().map(|s| s.to_string()).collect(),
+                installing: installing.iter().map(|s| s.to_string()).collect(),
             }
         }
 
@@ -965,6 +1019,71 @@ mod tests {
             assert!(labels.iter().all(|l| l == "Waiting for Bitcoin to start…"));
         }
 
+        #[tokio::test]
+        async fn waits_while_dependency_is_still_installing_then_passes() {
+            // Bitcoin has NO container yet (image still pulling) but its
+            // package state is Installing. Old behavior failed fast here —
+            // the confirmed fresh-node LND "first install fails" bug. The
+            // gate must wait past the normal started-but-not-running budget
+            // (max_attempts=1 below) while the install is in flight.
+            let calls = Arc::new(AtomicU32::new(0));
+            let (labels, sink) = label_sink();
+            let probe_calls = Arc::clone(&calls);
+            let result = wait_for_install_deps(
+                "lnd",
+                move || {
+                    let n = probe_calls.fetch_add(1, Ordering::SeqCst);
+                    async move {
+                        Ok(match n {
+                            // pulling: no container, package Installing
+                            0 | 1 => probe_with_installing(false, false, &[], &["bitcoin-knots"]),
+                            // container created, starting
+                            2 => probe(false, false, &["bitcoin-knots"]),
+                            // running
+                            _ => probe(true, false, &["bitcoin-knots"]),
+                        })
+                    }
+                },
+                sink,
+                1,
+                Duration::ZERO,
+            )
+            .await;
+            assert!(result.is_ok(), "{result:?}");
+            assert_eq!(calls.load(Ordering::SeqCst), 4);
+            let labels = labels.lock().unwrap();
+            assert_eq!(
+                labels.as_slice(),
+                [
+                    "Waiting for Bitcoin to finish installing…",
+                    "Waiting for Bitcoin to finish installing…",
+                    "Waiting for Bitcoin to start…",
+                ]
+            );
+        }
+
+        #[tokio::test]
+        async fn fails_fast_when_dependency_neither_installed_nor_installing() {
+            // installing list has unrelated packages only — no reason to wait.
+            let calls = AtomicU32::new(0);
+            let (labels, sink) = label_sink();
+            let err = wait_for_install_deps(
+                "lnd",
+                || {
+                    calls.fetch_add(1, Ordering::SeqCst);
+                    async { Ok(probe_with_installing(false, false, &[], &["grafana"])) }
+                },
+                sink,
+                36,
+                Duration::ZERO,
+            )
+            .await
+            .unwrap_err();
+            assert_eq!(calls.load(Ordering::SeqCst), 1);
+            assert!(labels.lock().unwrap().is_empty());
+            assert!(err.downcast_ref::<DependencyGateError>().is_some());
+        }
+
         #[tokio::test]
         async fn times_out_when_installed_dependency_never_runs() {
             let (labels, sink) = label_sink();

core/archipelago/src/api/rpc/package/install.rs

@@ -984,6 +984,24 @@ impl RpcHandler {
         }))
     }
 
+    /// Package ids currently mid-install/update per the state manager — used
+    /// by the dependency gate so an app whose dependency is still pulling its
+    /// image (no container yet) waits instead of failing fast.
+    async fn packages_currently_installing(&self) -> Vec<String> {
+        let (data, _) = self.state_manager.get_snapshot().await;
+        data.package_data
+            .iter()
+            .filter(|(_, entry)| {
+                matches!(
+                    entry.state,
+                    crate::data_model::PackageState::Installing
+                        | crate::data_model::PackageState::Updating
+                )
+            })
+            .map(|(id, _)| id.clone())
+            .collect()
+    }
+
     async fn running_deps_for_install(&self, package_id: &str) -> Result<RunningDeps> {
         let (data, _) = self.state_manager.get_snapshot().await;
         let cached = detect_running_deps_from_package_data(&data.package_data);
@@ -1006,6 +1024,7 @@ impl RpcHandler {
                 Ok(DepProbe {
                     running: self.running_deps_for_install(package_id).await?,
                     existing: detect_existing_containers().await,
+                    installing: self.packages_currently_installing().await,
                 })
             },
             |msg| async move { self.set_install_message(package_id, &msg).await },
@@ -1089,46 +1108,97 @@ impl RpcHandler {
             .spawn()
             .context("Failed to start image pull")?;
 
-        // 5-minute per-URL budget. A full install tries each configured mirror
-        // once, so a two-registry setup fails visibly in roughly 10 minutes
-        // instead of staying in Installing for up to an hour.
-        const PULL_URL_TIMEOUT_SECS: u64 = 300;
-        let pull_result = tokio::time::timeout(
-            std::time::Duration::from_secs(PULL_URL_TIMEOUT_SECS),
-            async {
-                if let Some(stderr) = child.stderr.take() {
-                    let reader = BufReader::new(stderr);
-                    let mut lines = reader.lines();
-                    let pkg_id = package_id.to_string();
-                    let state_mgr = self.state_manager.clone();
+        // Stall-aware budget instead of a hard wall clock. The old fixed
+        // 300s cap killed slow-but-progressing pulls (LND on fresh-node
+        // WiFi routinely needs longer), which surfaced as "first install
+        // fails, second succeeds" once the layer cache was warm. A pull is
+        // only killed when NOTHING is observably happening — no stderr
+        // output and no byte growth in podman's staging dir — for
+        // PULL_STALL_TIMEOUT_SECS, or at a generous absolute ceiling.
+        // Dead registries still fail fast: no bytes ever land, so the
+        // stall window (3 min) is the effective bound.
+        const PULL_STALL_TIMEOUT_SECS: u64 = 180;
+        const PULL_URL_MAX_SECS: u64 = 1800;
+        const PULL_POLL_INTERVAL_SECS: u64 = 5;
 
-                    while let Ok(Some(line)) = lines.next_line().await {
-                        if let Some((downloaded, total)) = parse_pull_progress(&line) {
-                            Self::update_install_progress(&state_mgr, &pkg_id, downloaded, total)
-                                .await;
-                        }
+        let started = std::time::Instant::now();
+        // Seconds-since-start of the last stderr line, updated by the
+        // reader task. u64::MAX sentinel = no line seen yet (treated as
+        // activity at t=0 so the stall window starts at spawn).
+        let last_line_at = std::sync::Arc::new(std::sync::atomic::AtomicU64::new(0));
+        if let Some(stderr) = child.stderr.take() {
+            let reader = BufReader::new(stderr);
+            let mut lines = reader.lines();
+            let pkg_id = package_id.to_string();
+            let state_mgr = self.state_manager.clone();
+            let line_clock = std::sync::Arc::clone(&last_line_at);
+            let started_reader = started;
+            tokio::spawn(async move {
+                while let Ok(Some(line)) = lines.next_line().await {
+                    line_clock.store(
+                        started_reader.elapsed().as_secs(),
+                        std::sync::atomic::Ordering::Relaxed,
+                    );
+                    if let Some((downloaded, total)) = parse_pull_progress(&line) {
+                        Self::update_install_progress(&state_mgr, &pkg_id, downloaded, total)
+                            .await;
                     }
                 }
-                child.wait().await
-            },
-        )
-        .await;
+            });
+        }
 
-        match pull_result {
-            Ok(Ok(status)) => Ok(status.success()),
-            Ok(Err(e)) => {
-                tracing::warn!("Image pull process error on {}: {}", url, e);
-                Ok(false)
+        let mut last_staged_bytes = dir_size_bytes(user_tmp);
+        let mut last_staged_change = std::time::Instant::now();
+        loop {
+            match child.try_wait() {
+                Ok(Some(status)) => return Ok(status.success()),
+                Ok(None) => {}
+                Err(e) => {
+                    tracing::warn!("Image pull process error on {}: {}", url, e);
+                    let _ = child.kill().await;
+                    let _ = child.wait().await;
+                    return Ok(false);
+                }
             }
-            Err(_) => {
+
+            tokio::time::sleep(std::time::Duration::from_secs(PULL_POLL_INTERVAL_SECS)).await;
+
+            if started.elapsed() > std::time::Duration::from_secs(PULL_URL_MAX_SECS) {
                 tracing::warn!(
-                    "Image pull timed out after {}s: {}",
-                    PULL_URL_TIMEOUT_SECS,
+                    "Image pull exceeded absolute {}s ceiling: {}",
+                    PULL_URL_MAX_SECS,
                     url
                 );
                 let _ = child.kill().await;
                 let _ = child.wait().await; // reap zombie
-                Ok(false)
+                return Ok(false);
+            }
+
+            // Activity signal 1: stderr output from podman.
+            let line_age = started
+                .elapsed()
+                .as_secs()
+                .saturating_sub(last_line_at.load(std::sync::atomic::Ordering::Relaxed));
+            // Activity signal 2: podman stages layer downloads in TMPDIR
+            // (user_tmp) — any size change there means bytes are moving.
+            let staged = dir_size_bytes(user_tmp);
+            if staged != last_staged_bytes {
+                last_staged_bytes = staged;
+                last_staged_change = std::time::Instant::now();
+            }
+
+            let stalled = line_age > PULL_STALL_TIMEOUT_SECS
+                && last_staged_change.elapsed()
+                    > std::time::Duration::from_secs(PULL_STALL_TIMEOUT_SECS);
+            if stalled {
+                tracing::warn!(
+                    "Image pull stalled ({}s with no output and no staged bytes): {}",
+                    PULL_STALL_TIMEOUT_SECS,
+                    url
+                );
+                let _ = child.kill().await;
+                let _ = child.wait().await; // reap zombie
+                return Ok(false);
             }
         }
     }
@@ -2690,6 +2760,31 @@ async fn persist_install_version_selection(app_id: &str, version: &str) {
     }
 }
 
+/// Total bytes under `path` (bounded recursive walk). Used as a coarse
+/// "bytes are moving" signal for pull stall detection — exact size doesn't
+/// matter, only whether it CHANGES between polls. Errors count as 0.
+fn dir_size_bytes(path: &str) -> u64 {
+    fn walk(dir: &std::path::Path, depth: u32) -> u64 {
+        if depth > 8 {
+            return 0;
+        }
+        let Ok(entries) = std::fs::read_dir(dir) else {
+            return 0;
+        };
+        let mut total = 0u64;
+        for entry in entries.flatten() {
+            let Ok(meta) = entry.metadata() else { continue };
+            if meta.is_dir() {
+                total = total.saturating_add(walk(&entry.path(), depth + 1));
+            } else {
+                total = total.saturating_add(meta.len());
+            }
+        }
+        total
+    }
+    walk(std::path::Path::new(path), 0)
+}
+
 fn should_try_orchestrator_install(package_id: &str, orchestrator_available: bool) -> bool {
     orchestrator_available && uses_orchestrator_install_flow(package_id)
 }

core/archipelago/src/api/rpc/package/stacks.rs

@@ -621,8 +621,33 @@ async fn install_stack_via_orchestrator(
     ))
     .await;
 
+    // Phase: PullingImage — each member's orchestrator.install covers its
+    // whole pipeline (pull + create + start + health wait), and on a fresh
+    // node the pull dominates wall-clock. The X-of-N counter below is what
+    // the UI interpolates across the PullingImage band (20→70%); without
+    // these updates an orchestrator-installed stack sat at "Preparing… 5%"
+    // for the entire multi-gigabyte pull (indeedhub: 7 images).
+    let total = app_ids.len() as u64;
+    handler
+        .set_install_phase(stack_name, InstallPhase::PullingImage)
+        .await;
+
     let mut installed = 0usize;
-    for app_id in app_ids {
+    for (idx, app_id) in app_ids.iter().enumerate() {
+        handler
+            .set_install_progress(stack_name, idx as u64, total)
+            .await;
+        // Message after progress: set_install_progress resets the label,
+        // set_install_message preserves the phase + counters just written.
+        let component = app_id
+            .strip_prefix(&format!("{stack_name}-"))
+            .unwrap_or(app_id);
+        handler
+            .set_install_message(
+                stack_name,
+                &format!("Installing {} ({} of {})…", component, idx + 1, total),
+            )
+            .await;
         match orchestrator.install(app_id).await {
             Ok(container_name) => {
                 installed += 1;
@@ -672,6 +697,20 @@ async fn install_stack_via_orchestrator(
         }
     }
 
+    // Truthful end-of-install signal, mirroring the legacy stack installers:
+    // the real readiness gate is the scanner's next sweep, this just settles
+    // the bar at 95→100→done instead of leaving it mid-band.
+    handler
+        .set_install_progress(stack_name, total, total)
+        .await;
+    handler
+        .set_install_phase(stack_name, InstallPhase::PostInstall)
+        .await;
+    handler
+        .set_install_phase(stack_name, InstallPhase::Done)
+        .await;
+    handler.clear_install_progress(stack_name).await;
+
     install_log(&format!("INSTALL ORCH OK: {} stack", stack_name)).await;
     Ok(Some(serde_json::json!({
         "success": true,

core/archipelago/src/backup/full.rs

@@ -29,6 +29,11 @@ const BACKUP_DIRS: &[&str] = &[
     "credentials",
     "tor-config",
     "content",
+    // Per-node service secrets. Without these a restored node can't
+    // decrypt identity/lnd_aezeed.enc (the Lightning seed backup is
+    // encrypted with secrets/lnd-wallet-password) or reuse its service
+    // credentials. The archive itself is passphrase-encrypted.
+    "secrets",
 ];
 
 /// Files within data_dir to include in a full backup.
@@ -101,7 +106,9 @@ pub async fn create_full_backup(
     // Step 4: Write metadata
     let metadata = BackupMetadata {
         id: backup_id,
-        version: 2,
+        // v3: archive additionally carries the `secrets` dir (needed to
+        // decrypt identity/lnd_aezeed.enc on a restored node).
+        version: 3,
         created_at: timestamp,
         encrypted: true,
         size_bytes: encrypted.len() as u64,
@@ -193,6 +200,14 @@ pub async fn restore_full_backup(data_dir: &Path, backup_id: &str, passphrase: &
         .context("Failed to create rollback directory")?;
 
     for dir_name in BACKUP_DIRS {
+        // Only displace live data the backup will actually replace —
+        // older archives don't contain every current BACKUP_DIRS entry
+        // (e.g. `secrets` was added later), and moving a live dir to
+        // rollback with nothing staged to take its place would DELETE it
+        // at cleanup time.
+        if !staging_dir.join(dir_name).exists() {
+            continue;
+        }
         let src = data_dir.join(dir_name);
         if src.exists() {
             let dst = rollback_dir.join(dir_name);
@@ -207,6 +222,9 @@ pub async fn restore_full_backup(data_dir: &Path, backup_id: &str, passphrase: &
         }
     }
     for file_name in BACKUP_FILES {
+        if !staging_dir.join(file_name).exists() {
+            continue;
+        }
         let src = data_dir.join(file_name);
         if src.exists() {
             let dst = rollback_dir.join(file_name);
@@ -732,6 +750,46 @@ mod tests {
         assert!(!bad_result.valid);
     }
 
+    #[tokio::test]
+    async fn secrets_dir_rides_backup_and_restore() {
+        // The Lightning seed backup (identity/lnd_aezeed.enc) is encrypted
+        // with secrets/lnd-wallet-password — a backup that omits it can't
+        // recover the Lightning wallet on restore.
+        let dir = TempDir::new().unwrap();
+        setup_data_dir(dir.path());
+        std::fs::create_dir_all(dir.path().join("secrets")).unwrap();
+        std::fs::write(dir.path().join("secrets/lnd-wallet-password"), "s3cret").unwrap();
+
+        let meta = create_full_backup(dir.path(), "pass", None).await.unwrap();
+
+        std::fs::remove_dir_all(dir.path().join("secrets")).unwrap();
+        restore_full_backup(dir.path(), &meta.id, "pass").await.unwrap();
+
+        let pw = std::fs::read_to_string(dir.path().join("secrets/lnd-wallet-password")).unwrap();
+        assert_eq!(pw, "s3cret");
+    }
+
+    #[tokio::test]
+    async fn restoring_old_backup_without_secrets_keeps_live_secrets() {
+        // Archives created before `secrets` joined BACKUP_DIRS don't stage
+        // one — the restore must NOT displace (and then delete) the node's
+        // live secrets in that case.
+        let dir = TempDir::new().unwrap();
+        setup_data_dir(dir.path());
+
+        // Backup taken while no secrets dir existed (mimics an old archive).
+        let meta = create_full_backup(dir.path(), "pass", None).await.unwrap();
+
+        // Live secrets appear afterwards.
+        std::fs::create_dir_all(dir.path().join("secrets")).unwrap();
+        std::fs::write(dir.path().join("secrets/lnd-wallet-password"), "keep-me").unwrap();
+
+        restore_full_backup(dir.path(), &meta.id, "pass").await.unwrap();
+
+        let pw = std::fs::read_to_string(dir.path().join("secrets/lnd-wallet-password")).unwrap();
+        assert_eq!(pw, "keep-me");
+    }
+
     #[tokio::test]
     async fn backup_and_restore() {
         let dir = TempDir::new().unwrap();

core/archipelago/src/health_monitor.rs

@@ -475,7 +475,12 @@ async fn check_containers() -> Vec<ContainerHealth> {
 
         let podman_health = parse_podman_health(c, &state);
         let host_ports = host_tcp_ports_from_container(c);
-        let host_port_ready = if host_ports.is_empty() {
+        // Only raw-probe published ports for containers WITHOUT their own
+        // podman healthcheck. The healthcheck is the better signal, and the
+        // bare TCP connect+close is noisy against TLS listeners — LND logged
+        // "http: TLS handshake error … EOF" on every monitor cycle because
+        // this probe hit its REST/gRPC ports and hung up mid-handshake.
+        let host_port_ready = if host_ports.is_empty() || podman_health.is_some() {
             None
         } else {
             Some(host_ports_ready(&host_ports).await)

core/container/src/podman_client.rs

@@ -263,28 +263,38 @@ impl PodmanClient {
         )
         .await?;
 
-        // Image pull uses CLI — it's a streaming operation that the API handles differently
-        let mut cmd = tokio::process::Command::new("podman");
-        cmd.arg("pull");
-        if image_uses_insecure_registry(image) {
-            cmd.arg("--tls-verify=false");
+        // Stall-aware + retried, mirroring the legacy installer's
+        // pull_one_url_with_progress. The old single-attempt hard 600s wall
+        // clock killed slow-but-progressing pulls, which every orchestrator
+        // stack (btcpay, indeedhub, …) surfaced as "first install fails,
+        // second succeeds" once the layer cache was warm. Podman keeps
+        // completed layers between attempts, so retries resume cheaply.
+        const MAX_ATTEMPTS: u32 = 3;
+        const BACKOFF_SECS: [u64; 2] = [5, 15];
+
+        let mut last_err = anyhow::anyhow!("podman pull {image}: no attempt ran");
+        for attempt in 1..=MAX_ATTEMPTS {
+            match pull_image_stall_aware(image).await {
+                Ok(()) => return Ok(()),
+                Err(e) => {
+                    tracing::warn!(
+                        "Image pull failed for {} (attempt {}/{}): {:#}",
+                        image,
+                        attempt,
+                        MAX_ATTEMPTS,
+                        e
+                    );
+                    last_err = e;
+                    if attempt < MAX_ATTEMPTS {
+                        tokio::time::sleep(std::time::Duration::from_secs(
+                            BACKOFF_SECS[(attempt - 1) as usize],
+                        ))
+                        .await;
+                    }
+                }
+            }
         }
-        cmd.arg(image);
-
-        let output = tokio::time::timeout(
-            std::time::Duration::from_secs(600), // 10 min for large images
-            cmd.output(),
-        )
-        .await
-        .map_err(|_| anyhow::anyhow!("Image pull timed out after 10 minutes"))?
-        .context("Failed to execute podman pull")?;
-
-        if !output.status.success() {
-            let stderr = String::from_utf8_lossy(&output.stderr);
-            return Err(anyhow::anyhow!("Failed to pull image: {}", stderr));
-        }
-
-        Ok(())
+        Err(last_err)
     }
 
     pub async fn create_container(&self, manifest: &AppManifest, name: &str) -> Result<String> {
@@ -710,6 +720,155 @@ fn podman_network_settings(
 
 // ─── Helpers ─────────────────────────────────────────────────────
 
+/// One `podman pull` attempt with a stall-aware budget instead of a hard
+/// wall clock. A pull is only killed when NOTHING is observably happening —
+/// no stderr output AND no byte growth in podman's TMPDIR staging dir — for
+/// PULL_STALL_TIMEOUT_SECS, or at a generous absolute ceiling. Dead
+/// registries still fail fast (no bytes ever land, so the 3-minute stall
+/// window is the effective bound), while a slow-but-moving multi-GB pull is
+/// left alone. Same design as the legacy installer's
+/// pull_one_url_with_progress (LND "first install fails" fix).
+async fn pull_image_stall_aware(image: &str) -> Result<()> {
+    const PULL_STALL_TIMEOUT_SECS: u64 = 180;
+    const PULL_MAX_SECS: u64 = 1800;
+    const PULL_POLL_INTERVAL_SECS: u64 = 5;
+
+    // Rootless podman's user namespace makes /var/tmp read-only; stage into
+    // the user's containers tmp (same dir every other pull path uses) — it
+    // doubles as the "bytes are moving" signal for stall detection.
+    let user_tmp = format!(
+        "{}/.local/share/containers/tmp",
+        std::env::var("HOME").unwrap_or_else(|_| "/home/archipelago".to_string())
+    );
+    let _ = std::fs::create_dir_all(&user_tmp);
+
+    let mut cmd = tokio::process::Command::new("podman");
+    cmd.arg("pull");
+    if image_uses_insecure_registry(image) {
+        cmd.arg("--tls-verify=false");
+    }
+    cmd.arg(image);
+    cmd.env("TMPDIR", &user_tmp);
+    cmd.stdout(std::process::Stdio::piped());
+    cmd.stderr(std::process::Stdio::piped());
+    cmd.kill_on_drop(true);
+    let mut child = cmd.spawn().context("Failed to start podman pull")?;
+
+    let started = std::time::Instant::now();
+    // Seconds-since-start of the last stderr line, updated by the reader
+    // task. Starts at 0 so the stall window opens at spawn.
+    let last_line_at = std::sync::Arc::new(std::sync::atomic::AtomicU64::new(0));
+    // Ring of recent stderr lines so a failed pull reports podman's actual
+    // error, not just "exit status 125".
+    let recent_stderr = std::sync::Arc::new(std::sync::Mutex::new(std::collections::VecDeque::<
+        String,
+    >::with_capacity(8)));
+    if let Some(stderr) = child.stderr.take() {
+        use tokio::io::AsyncBufReadExt;
+        let mut lines = tokio::io::BufReader::new(stderr).lines();
+        let line_clock = std::sync::Arc::clone(&last_line_at);
+        let stderr_ring = std::sync::Arc::clone(&recent_stderr);
+        let started_reader = started;
+        tokio::spawn(async move {
+            while let Ok(Some(line)) = lines.next_line().await {
+                line_clock.store(
+                    started_reader.elapsed().as_secs(),
+                    std::sync::atomic::Ordering::Relaxed,
+                );
+                if let Ok(mut ring) = stderr_ring.lock() {
+                    if ring.len() >= 8 {
+                        ring.pop_front();
+                    }
+                    ring.push_back(line);
+                }
+            }
+        });
+    }
+
+    let stderr_tail = |ring: &std::sync::Mutex<std::collections::VecDeque<String>>| {
+        ring.lock()
+            .map(|r| r.iter().cloned().collect::<Vec<_>>().join(" | "))
+            .unwrap_or_default()
+    };
+
+    let mut last_staged_bytes = dir_size_bytes(&user_tmp);
+    let mut last_staged_change = std::time::Instant::now();
+    loop {
+        match child.try_wait() {
+            Ok(Some(status)) if status.success() => return Ok(()),
+            Ok(Some(status)) => {
+                anyhow::bail!(
+                    "podman pull {image} failed ({status}): {}",
+                    stderr_tail(&recent_stderr)
+                );
+            }
+            Ok(None) => {}
+            Err(e) => {
+                let _ = child.kill().await;
+                let _ = child.wait().await;
+                return Err(anyhow::anyhow!("podman pull {image} process error: {e}"));
+            }
+        }
+
+        tokio::time::sleep(std::time::Duration::from_secs(PULL_POLL_INTERVAL_SECS)).await;
+
+        if started.elapsed() > std::time::Duration::from_secs(PULL_MAX_SECS) {
+            let _ = child.kill().await;
+            let _ = child.wait().await; // reap zombie
+            anyhow::bail!("podman pull {image} exceeded absolute {PULL_MAX_SECS}s ceiling");
+        }
+
+        // Activity signal 1: stderr output from podman.
+        let line_age = started
+            .elapsed()
+            .as_secs()
+            .saturating_sub(last_line_at.load(std::sync::atomic::Ordering::Relaxed));
+        // Activity signal 2: staged layer bytes growing in TMPDIR.
+        let staged = dir_size_bytes(&user_tmp);
+        if staged != last_staged_bytes {
+            last_staged_bytes = staged;
+            last_staged_change = std::time::Instant::now();
+        }
+
+        if line_age > PULL_STALL_TIMEOUT_SECS
+            && last_staged_change.elapsed()
+                > std::time::Duration::from_secs(PULL_STALL_TIMEOUT_SECS)
+        {
+            let _ = child.kill().await;
+            let _ = child.wait().await; // reap zombie
+            anyhow::bail!(
+                "podman pull {image} stalled ({PULL_STALL_TIMEOUT_SECS}s with no output and no staged bytes): {}",
+                stderr_tail(&recent_stderr)
+            );
+        }
+    }
+}
+
+/// Total bytes under `path` (bounded recursive walk). Used as a coarse
+/// "bytes are moving" signal for pull stall detection — exact size doesn't
+/// matter, only whether it CHANGES between polls. Errors count as 0.
+fn dir_size_bytes(path: &str) -> u64 {
+    fn walk(dir: &std::path::Path, depth: u32) -> u64 {
+        if depth > 8 {
+            return 0;
+        }
+        let Ok(entries) = std::fs::read_dir(dir) else {
+            return 0;
+        };
+        let mut total = 0u64;
+        for entry in entries.flatten() {
+            let Ok(meta) = entry.metadata() else { continue };
+            if meta.is_dir() {
+                total = total.saturating_add(walk(&entry.path(), depth + 1));
+            } else {
+                total = total.saturating_add(meta.len());
+            }
+        }
+        total
+    }
+    walk(std::path::Path::new(path), 0)
+}
+
 fn parse_port_bindings(bindings: &serde_json::Value) -> Vec<String> {
     let mut ports = Vec::new();
     if let Some(obj) = bindings.as_object() {

docs/companion-pairing-qr.md

@@ -0,0 +1,81 @@
+# Companion app pairing QR — integration handoff
+
+**Status:** web-UI side SHIPPED (CompanionIntroOverlay.vue, 2026-07-16). This doc is
+the contract + requirements for the companion-app side (worked on separately, on
+the Mac).
+
+## What the web UI now does
+
+The "Remote Companion" intro modal (shown once after first dashboard login, and in
+the public demo) gained a second screen:
+
+1. **Screen 1 (existing):** APK download QR (desktop) / download button, plus a new
+   **"I've installed it"** button to the right of the download button.
+2. **Screen 2 (new, slide transition):** a **pairing QR** the companion app scans to
+   auto-fill the server entry, with a **Back** button returning to screen 1. On
+   small screens (where you can't scan your own display) an
+   **"Open in companion app"** deep-link button is shown above Back, using the same
+   URI as the QR.
+
+## The QR payload / deep link (the contract)
+
+A single URI, also usable as an OS deep link:
+
+```
+archipelago://pair?v=1&url=<percent-encoded server URL>[&pw=<percent-encoded password>]
+```
+
+Query parameters:
+
+| param | required | meaning |
+|-------|----------|---------|
+| `v`   | yes      | Payload version, currently `1`. Reject/ignore unknown majors gracefully — show "please update the app". |
+| `url` | yes      | Full origin the app should connect to, scheme included: `https://demo.archipelago-foundation.org`, `http://archipelago.local`, `http://192.168.1.228`, etc. No trailing slash guaranteed either way — normalize. |
+| `pw`  | no       | Login password. **Only present in the public demo** (shared demo password `entertoexit`). Real nodes never embed a password — the frontend doesn't have it. |
+
+Examples the web UI actually emits:
+
+- Demo: `archipelago://pair?v=1&url=https%3A%2F%2Fdemo.archipelago-foundation.org&pw=entertoexit`
+- Real node, browsed via LAN IP: `archipelago://pair?v=1&url=http%3A%2F%2F192.168.1.228`
+- Real node kiosk (UI runs on localhost, so it advertises the mDNS name from
+  `system.get-hostname`): `archipelago://pair?v=1&url=http%3A%2F%2Farchipelago.local`
+
+## Companion app requirements
+
+1. **Scan entry point:** the app's action is labeled **"Scan Node's QR"**
+   (implemented 2026-07-17; the modal copy in CompanionIntroOverlay.vue was
+   updated to match).
+2. **Parse the URI** (from camera scan AND from an OS deep-link intent —
+   register the `archipelago://` scheme so the "Open in companion app" button on
+   phones works).
+3. On success, **create/update a saved server entry**:
+   - Server address = `url` exactly as given (respect the scheme — the demo is
+     https, LAN nodes are typically http, `.local` mDNS names must work).
+   - If `pw` present, prefill the password and attempt auto-login; otherwise land
+     on the password prompt for that server.
+   - If an entry with the same origin already exists, update it rather than
+     duplicating.
+4. **Demo flow (the showcase):** scanning the demo QR should take a fresh install
+   to a logged-in demo session in one step — url `https://demo.archipelago-foundation.org`,
+   password `entertoexit`, no manual typing.
+5. **Robustness:**
+   - Tolerate unknown extra query params (forward compat — we may add `name`,
+     `cert` fingerprint, etc. under `v=1`).
+   - Self-signed HTTPS on `.local`/LAN addresses may appear later; don't hard-fail
+     the parse on scheme.
+   - Bad/foreign QR → clear error, stay on the scan screen.
+
+## Notes / future extensions (not in v1)
+
+- A real-node pairing **token** instead of a password (backend mints a one-time
+  token, QR carries it, app exchanges it for a session) — needs a backend RPC;
+  the `v` param exists so we can bump when this lands.
+- Optional `name` param (node display name) so the app labels the entry nicely.
+
+## Testing checklist (app side)
+
+- [ ] Scan demo QR from https://demo.archipelago-foundation.org → auto-connected demo session.
+- [ ] Scan a real node's QR (LAN IP origin) → entry created, password prompt shown.
+- [ ] Scan a kiosk node's QR (`http://<name>.local`) → mDNS resolution works on the phone.
+- [ ] Tap "Open in companion app" on a phone browser → deep link opens the app with the same behavior.
+- [ ] Re-scan same node → no duplicate entry.

image-recipe/_archived/build-auto-installer-iso.sh

@@ -1349,21 +1349,29 @@ if [ "$UNBUNDLED" = "1" ]; then
     # Clean stale images from previous builds (e.g. bundled build tars leaking into unbundled)
     rm -rf "$IMAGES_DIR"
     mkdir -p "$IMAGES_DIR"
-    # FileBrowser is a core dependency (powers the Cloud file manager) — always bundle it
-    CORE_IMAGE="${FILEBROWSER_IMAGE}"
-    CORE_FILE="filebrowser.tar"
-    if [ -f "$IMAGES_DIR/$CORE_FILE" ]; then
-        echo "   ✅ Using cached: $CORE_FILE"
-    else
-        echo "   Pulling $CORE_IMAGE ($CONTAINER_PLATFORM)..."
-        if container_pull "$CORE_IMAGE"; then
-            $CONTAINER_CMD save "$CORE_IMAGE" -o "$IMAGES_DIR/$CORE_FILE" 2>/dev/null && \
-                echo "   ✅ Saved core: $CORE_FILE ($(du -h "$IMAGES_DIR/$CORE_FILE" | cut -f1))" || \
-                echo "   ⚠️  Failed to save $CORE_IMAGE"
+    # Core baseline apps created by first-boot-containers.sh even in
+    # unbundled mode — their images must ride on the ISO so a fresh install
+    # works with no internet: FileBrowser (Cloud file manager) and fmcd
+    # (fedimint-clientd, ecash/sats out of the box).
+    CORE_BUNDLE="
+${FILEBROWSER_IMAGE} filebrowser.tar
+${FMCD_IMAGE} fmcd.tar
+"
+    echo "$CORE_BUNDLE" | while read -r CORE_IMAGE CORE_FILE; do
+        [ -n "$CORE_IMAGE" ] || continue
+        if [ -f "$IMAGES_DIR/$CORE_FILE" ]; then
+            echo "   ✅ Using cached: $CORE_FILE"
         else
-            echo "   ⚠️  Failed to pull $CORE_IMAGE — Cloud will not work until installed"
+            echo "   Pulling $CORE_IMAGE ($CONTAINER_PLATFORM)..."
+            if container_pull "$CORE_IMAGE"; then
+                $CONTAINER_CMD save "$CORE_IMAGE" -o "$IMAGES_DIR/$CORE_FILE" 2>/dev/null && \
+                    echo "   ✅ Saved core: $CORE_FILE ($(du -h "$IMAGES_DIR/$CORE_FILE" | cut -f1))" || \
+                    echo "   ⚠️  Failed to save $CORE_IMAGE"
+            else
+                echo "   ⚠️  Failed to pull $CORE_IMAGE — baseline app won't work offline"
+            fi
         fi
-    fi
+    done
 else
 echo "📦 Step 3b: Bundling container images for offline use..."
 
@@ -1472,6 +1480,13 @@ LOADSERVICE
 cat > "$WORK_DIR/load-container-images.sh" <<'LOADSCRIPT'
 #!/bin/bash
 # Load pre-bundled container images into Podman
+#
+# CRITICAL: all Archipelago containers run ROOTLESS as the archipelago user.
+# This script runs as root (systemd oneshot), so a plain `podman load` here
+# puts the images into root's storage where the rootless runtime can never
+# see them — containers then silently depend on registry pulls, and a fresh
+# install without internet gets no apps at all. Always load into the
+# archipelago user's storage.
 
 IMAGES_DIR="/opt/archipelago/container-images"
 LOG_FILE="/var/log/archipelago-images.log"
@@ -1483,21 +1498,32 @@ if [ ! -d "$IMAGES_DIR" ]; then
     exit 0
 fi
 
+ARCH_UID=$(id -u archipelago)
+# Linger gives the archipelago user a runtime dir (/run/user/UID) at boot,
+# before any login — required for rootless podman.
+loginctl enable-linger archipelago 2>/dev/null || true
+for _ in $(seq 1 30); do
+    [ -d "/run/user/$ARCH_UID" ] && break
+    sleep 1
+done
+PODMAN="runuser -u archipelago -- env XDG_RUNTIME_DIR=/run/user/$ARCH_UID podman"
+$PODMAN system migrate >> "$LOG_FILE" 2>&1 || true
+
 for tarfile in "$IMAGES_DIR"/*.tar; do
     if [ -f "$tarfile" ]; then
         echo "$(date): Loading $(basename "$tarfile")..." >> "$LOG_FILE"
-        podman load -i "$tarfile" >> "$LOG_FILE" 2>&1 && \
+        $PODMAN load -i "$tarfile" >> "$LOG_FILE" 2>&1 && \
             echo "$(date): Successfully loaded $(basename "$tarfile")" >> "$LOG_FILE" || \
             echo "$(date): Failed to load $(basename "$tarfile")" >> "$LOG_FILE"
     fi
 done
 
 # Ensure archy-net exists for mempool stack (db, api, frontend)
-podman network create archy-net 2>/dev/null || true
+$PODMAN network create archy-net 2>/dev/null || true
 
 echo "$(date): Container image load complete" >> "$LOG_FILE"
 echo "$(date): Available images:" >> "$LOG_FILE"
-podman images >> "$LOG_FILE" 2>&1
+$PODMAN images >> "$LOG_FILE" 2>&1
 LOADSCRIPT
 
 chmod +x "$WORK_DIR/load-container-images.sh"
@@ -3587,10 +3613,27 @@ echo "   Step 5 complete (GRUB + ISOLINUX configured)"
 echo ""
 echo "Step 6: Creating bootable ISO..."
 
-if [ "$UNBUNDLED" = "1" ]; then
-    OUTPUT_ISO="$OUTPUT_DIR/archipelago-installer-${BUILD_VERSION}-unbundled-${ARCH}.iso"
+# Release-candidate suffix: rebuilds of the SAME version used to overwrite
+# the previous ISO under an identical filename, so a flashed stick was
+# indistinguishable from a newer build. Auto-increment an RC counter per
+# version (persists next to the build counter); override with RC=n env.
+RC_COUNTER_FILE="/opt/archipelago/rc-counter-${BUILD_VERSION}"
+if [ -n "${RC:-}" ]; then
+    RC_NUM="$RC"
 else
-    OUTPUT_ISO="$OUTPUT_DIR/archipelago-installer-${BUILD_VERSION}-${ARCH}.iso"
+    if [ -f "$RC_COUNTER_FILE" ]; then
+        RC_NUM=$(( $(cat "$RC_COUNTER_FILE") + 1 ))
+    else
+        RC_NUM=1
+    fi
+fi
+echo "$RC_NUM" | sudo tee "$RC_COUNTER_FILE" > /dev/null 2>/dev/null || true
+echo "   Release candidate: RC${RC_NUM}"
+
+if [ "$UNBUNDLED" = "1" ]; then
+    OUTPUT_ISO="$OUTPUT_DIR/archipelago-installer-${BUILD_VERSION}-unbundled-${ARCH}_RC${RC_NUM}.iso"
+else
+    OUTPUT_ISO="$OUTPUT_DIR/archipelago-installer-${BUILD_VERSION}-${ARCH}_RC${RC_NUM}.iso"
 fi
 
 # Use the proven MBR code for hybrid USB boot

image-recipe/configs/archipelago-kiosk-launcher.sh

@@ -135,7 +135,7 @@ while true; do
       --disable-metrics \
       --disable-metrics-reporting \
       --disable-domain-reliability \
-      --js-flags="--max-old-space-size=128" \
+      --js-flags="--max-old-space-size=256" \
       --user-data-dir=/var/lib/archipelago/chromium-kiosk
     sleep 3
 done

neode-ui/src/App.vue

@@ -124,6 +124,13 @@ function syncKioskSafeArea() {
   if (typeof document === 'undefined') return
   const isKiosk = localStorage.getItem('kiosk') === 'true'
     || new URLSearchParams(window.location.search).has('kiosk')
+    // Very first kiosk boot: the launcher opens /kiosk before the route
+    // guard has had a chance to persist localStorage.kiosk.
+    || window.location.pathname === '/kiosk'
+  // Global styling hook: kiosk chromium runs software-composited
+  // (--in-process-gpu / --disable-gpu), where heavy compositing effects
+  // (3D bg layers, animated mix-blend overlays) fail and paint black.
+  document.documentElement.classList.toggle('kiosk-mode', isKiosk)
   const rawSafeArea = localStorage.getItem('archipelago_kiosk_safe_area_px') || '0'
   const safeArea = /^\d{1,3}$/.test(rawSafeArea) ? Number(rawSafeArea) : 0
   const rawSafeAreaX = localStorage.getItem('archipelago_kiosk_safe_area_x_px') || rawSafeArea
@@ -404,7 +411,13 @@ onMounted(async () => {
   // the initial navigation resolves asynchronously — so a deep-route load
   // (e.g. a direct /login visit) would masquerade as a root boot. The URL
   // bar is the only truthful source this early.
-  const bootPath = window.location.pathname
+  //
+  // The kiosk chromium opens /kiosk — a marker route whose beforeEnter
+  // stamps localStorage.kiosk and immediately redirects to '/'. That is a
+  // root boot, not a deep route: without normalizing it, the fresh-install
+  // kiosk never plays the typing intro (deep-route suppression regression).
+  const rawBootPath = window.location.pathname
+  const bootPath = rawBootPath === '/kiosk' ? '/' : rawBootPath
   // Public demo: every fresh boot at the root (first visit or a browser
   // refresh) starts with the typing splash for the full effect. In-session SPA
   // navigation never remounts App, and deep-route refreshes keep their place.
@@ -417,7 +430,17 @@ onMounted(async () => {
   if (splashCandidate && onboardingComplete !== true) {
     try {
       const { checkOnboardingStatus } = await import('@/composables/useOnboarding')
-      onboardingComplete = await checkOnboardingStatus()
+      // Bound the pre-splash status check: its retry ladder can spend ~30s
+      // against a still-booting backend, and this await holds the black
+      // "!isReady" screen the whole time — exactly where the typing intro
+      // should be playing on a fresh kiosk boot. Unknown within 2.5s → let
+      // the splash play (a fresh install IS the slow-backend case; onboarded
+      // nodes answer in milliseconds, so their suppression path is intact).
+      // handleSplashComplete re-checks with full retries after the intro.
+      onboardingComplete = await Promise.race([
+        checkOnboardingStatus(),
+        new Promise<null>((resolve) => setTimeout(() => resolve(null), 2500)),
+      ])
     } catch {
       onboardingComplete = localStorage.getItem('neode_onboarding_complete') === '1' ? true : null
     }
@@ -517,14 +540,24 @@ function onShareToMeshMessage(ev: MessageEvent) {
  * Routes user directly to appropriate screen based on onboarding status (from backend)
  */
 async function handleSplashComplete() {
-  showSplash.value = false
-  document.body.classList.add('splash-complete')
-  isReady.value = true
   sessionStorage.setItem('archipelago_from_splash', '1')
 
+  // Commit the destination route BEFORE revealing RouterView. Revealing
+  // first rendered whatever route was current — '/' → RootRedirect's
+  // spinner — for a beat between the intro's final frame and the
+  // onboarding/login screen actually mounting: a visible flash on every
+  // fresh install. Await the push so the first RouterView render is
+  // already the destination.
+  const reveal = () => {
+    showSplash.value = false
+    document.body.classList.add('splash-complete')
+    isReady.value = true
+  }
+
   const devMode = import.meta.env.VITE_DEV_MODE
   if (devMode === 'setup' || devMode === 'existing') {
-    router.push('/login').catch(() => {})
+    await router.push('/login').catch(() => {})
+    reveal()
     return
   }
 
@@ -534,7 +567,8 @@ async function handleSplashComplete() {
   {
     const { IS_DEMO } = await import('@/composables/useDemoIntro')
     if (IS_DEMO) {
-      router.push('/onboarding/intro').catch(() => {})
+      await router.push('/onboarding/intro').catch(() => {})
+      reveal()
       return
     }
   }
@@ -543,27 +577,24 @@ async function handleSplashComplete() {
     const { checkOnboardingStatus } = await import('@/composables/useOnboarding')
     const seenOnboarding = await checkOnboardingStatus()
     if (seenOnboarding === true) {
-      router.push('/login').catch(() => {})
-      return
-    }
-    if (seenOnboarding === false) {
-      router.push('/onboarding/intro').catch(() => {})
-      return
-    }
-    // Backend unreachable after retries. Prefer the localStorage
-    // cache on THIS browser (if a prior successful check set it) —
-    // otherwise defer to RootRedirect which polls + retries rather
-    // than forcing an already-onboarded user through the wizard.
-    if (localStorage.getItem('neode_onboarding_complete') === '1') {
-      router.push('/login').catch(() => {})
+      await router.push('/login').catch(() => {})
+    } else if (seenOnboarding === false) {
+      await router.push('/onboarding/intro').catch(() => {})
+    } else if (localStorage.getItem('neode_onboarding_complete') === '1') {
+      // Backend unreachable after retries. Prefer the localStorage
+      // cache on THIS browser (if a prior successful check set it) —
+      // otherwise defer to RootRedirect which polls + retries rather
+      // than forcing an already-onboarded user through the wizard.
+      await router.push('/login').catch(() => {})
     } else {
-      router.push('/').catch(() => {})
+      await router.push('/').catch(() => {})
     }
   } catch {
     // Do NOT default to /onboarding/intro here. RootRedirect has retry
     // + polling + boot-screen handling; let it decide.
-    router.push('/').catch(() => {})
+    await router.push('/').catch(() => {})
   }
+  reveal()
 }
 </script>
 

neode-ui/src/components/CompanionIntroOverlay.vue

@@ -8,66 +8,120 @@
       >
         <div class="absolute inset-0 bg-black/40 backdrop-blur-sm" />
         <div
-          class="glass-card p-5 w-full max-w-sm relative z-10 mb-20 sm:mb-0"
+          class="glass-card p-5 w-full max-w-sm relative z-10 mb-20 sm:mb-0 overflow-hidden"
           @click.stop
         >
           <button
             type="button"
-            class="absolute right-3 top-3 h-8 w-8 rounded-full bg-white/5 border border-white/10 text-white/60 hover:text-white hover:bg-white/10 transition-colors"
+            class="absolute right-3 top-3 h-8 w-8 rounded-full bg-white/5 border border-white/10 text-white/60 hover:text-white hover:bg-white/10 transition-colors z-10"
             aria-label="Close companion modal"
             @click="dismiss"
           >
             &times;
           </button>
 
-          <div class="flex items-start gap-4 mb-4">
-            <div class="w-12 h-12 rounded-xl bg-orange-500/15 border border-orange-500/30 flex items-center justify-center flex-shrink-0">
-              <svg class="w-7 h-7 text-orange-400" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
-                <rect x="3" y="7" width="18" height="11" rx="3" stroke-width="1.5" />
-                <rect x="7.5" y="10" width="2" height="5" rx="0.5" fill="currentColor" />
-                <rect x="6" y="11.5" width="5" height="2" rx="0.5" fill="currentColor" />
-                <circle cx="16" cy="11" r="1.2" fill="currentColor" />
-                <circle cx="14" cy="13.5" r="1.2" fill="currentColor" />
-              </svg>
-            </div>
-            <div class="min-w-0 flex-1">
-              <h3 class="text-lg font-semibold text-white mb-1">Remote Companion</h3>
-              <p class="text-sm text-white/60 leading-relaxed">
-                Install the Archipelago companion app on your phone, scan the code, and connect to the same node.
-              </p>
-            </div>
-          </div>
+          <Transition :name="slideName" mode="out-in">
+            <!-- Screen 1: get the app -->
+            <div v-if="step === 'download'" key="download">
+              <div class="flex items-start gap-4 mb-4">
+                <div class="w-12 h-12 rounded-xl bg-orange-500/15 border border-orange-500/30 flex items-center justify-center flex-shrink-0">
+                  <svg class="w-7 h-7 text-orange-400" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+                    <rect x="3" y="7" width="18" height="11" rx="3" stroke-width="1.5" />
+                    <rect x="7.5" y="10" width="2" height="5" rx="0.5" fill="currentColor" />
+                    <rect x="6" y="11.5" width="5" height="2" rx="0.5" fill="currentColor" />
+                    <circle cx="16" cy="11" r="1.2" fill="currentColor" />
+                    <circle cx="14" cy="13.5" r="1.2" fill="currentColor" />
+                  </svg>
+                </div>
+                <div class="min-w-0 flex-1">
+                  <h3 class="text-lg font-semibold text-white mb-1">Remote Companion</h3>
+                  <p class="text-sm text-white/60 leading-relaxed">
+                    Install the Archipelago companion app on your phone, scan the code, and connect to the same node.
+                  </p>
+                </div>
+              </div>
 
-          <div class="mb-4">
-            <a
-              :href="companionDownloadUrl"
-              class="md:hidden inline-flex w-full items-center justify-center rounded-lg bg-orange-500/20 border border-orange-500/30 px-4 py-2.5 text-sm font-medium text-orange-400 hover:bg-orange-500/30 transition-colors"
-              target="_blank"
-              rel="noopener noreferrer"
-            >
-              Download companion app
-            </a>
-            <div class="hidden md:flex justify-center">
-              <div class="w-[128px] rounded-2xl border border-white/10 bg-white/[0.03] p-1 overflow-hidden">
-                <img
-                  v-if="qrDataUrl"
-                  :src="qrDataUrl"
-                  alt="Companion app download QR code"
-                  class="block w-full max-w-full h-auto rounded-lg bg-white"
-                />
-                <div v-else class="w-full aspect-square rounded-lg bg-white/5"></div>
+              <div class="hidden md:flex justify-center mb-4">
+                <div class="w-[128px] rounded-2xl border border-white/10 bg-white/[0.03] p-1 overflow-hidden">
+                  <img
+                    v-if="qrDataUrl"
+                    :src="qrDataUrl"
+                    alt="Companion app download QR code"
+                    class="block w-full max-w-full h-auto rounded-lg bg-white"
+                  />
+                  <div v-else class="w-full aspect-square rounded-lg bg-white/5"></div>
+                </div>
+              </div>
+
+              <div class="flex gap-2">
+                <a
+                  :href="companionDownloadUrl"
+                  class="flex-1 inline-flex items-center justify-center rounded-lg bg-orange-500/20 border border-orange-500/30 px-3 py-2.5 text-sm font-medium text-orange-400 hover:bg-orange-500/30 transition-colors text-center"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                >
+                  Download app
+                </a>
+                <button
+                  type="button"
+                  class="flex-1 rounded-lg bg-white/5 border border-white/15 px-3 py-2.5 text-sm font-medium text-white/80 hover:bg-white/10 hover:text-white transition-colors"
+                  @click="showPairScreen"
+                >
+                  I've installed it
+                </button>
               </div>
             </div>
-          </div>
 
-          <a
-            :href="companionDownloadUrl"
-            class="hidden md:block w-full py-2.5 rounded-lg bg-orange-500/20 border border-orange-500/30 text-orange-400 text-sm font-medium hover:bg-orange-500/30 transition-colors text-center"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            Download companion app
-          </a>
+            <!-- Screen 2: pair the app with this node -->
+            <div v-else key="pair">
+              <div class="flex items-start gap-4 mb-4">
+                <div class="w-12 h-12 rounded-xl bg-orange-500/15 border border-orange-500/30 flex items-center justify-center flex-shrink-0">
+                  <svg class="w-7 h-7 text-orange-400" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+                    <rect x="4" y="4" width="7" height="7" rx="1.5" stroke-width="1.5" />
+                    <rect x="13" y="4" width="7" height="7" rx="1.5" stroke-width="1.5" />
+                    <rect x="4" y="13" width="7" height="7" rx="1.5" stroke-width="1.5" />
+                    <path d="M13 13h3v3h-3zM17 17h3v3h-3z" fill="currentColor" stroke="none" />
+                  </svg>
+                </div>
+                <div class="min-w-0 flex-1">
+                  <h3 class="text-lg font-semibold text-white mb-1">Connect your app</h3>
+                  <p class="text-sm text-white/60 leading-relaxed">
+                    In the companion app, choose “Scan Node's QR” and point your phone here — the server details fill in automatically.
+                  </p>
+                </div>
+              </div>
+
+              <div class="flex justify-center mb-4">
+                <div class="w-[128px] rounded-2xl border border-white/10 bg-white/[0.03] p-1 overflow-hidden">
+                  <img
+                    v-if="pairQrDataUrl"
+                    :src="pairQrDataUrl"
+                    alt="Companion app pairing QR code"
+                    class="block w-full max-w-full h-auto rounded-lg bg-white"
+                  />
+                  <div v-else class="w-full aspect-square rounded-lg bg-white/5"></div>
+                </div>
+              </div>
+
+              <!-- Same-device path: a QR on the phone's own screen can't be
+                   scanned, so offer the deep link directly on small screens. -->
+              <a
+                v-if="pairingUrl"
+                :href="pairingUrl"
+                class="md:hidden inline-flex w-full items-center justify-center rounded-lg bg-orange-500/20 border border-orange-500/30 px-4 py-2.5 text-sm font-medium text-orange-400 hover:bg-orange-500/30 transition-colors mb-2"
+              >
+                Open in companion app
+              </a>
+
+              <button
+                type="button"
+                class="w-full py-2.5 rounded-lg bg-white/5 border border-white/15 text-white/80 text-sm font-medium hover:bg-white/10 hover:text-white transition-colors"
+                @click="showDownloadScreen"
+              >
+                Back
+              </button>
+            </div>
+          </Transition>
         </div>
       </div>
     </Transition>
@@ -75,9 +129,11 @@
 </template>
 
 <script setup lang="ts">
-import { ref, onMounted, watch } from 'vue'
+import { ref, onMounted, onUnmounted, watch } from 'vue'
 import * as QRCode from 'qrcode'
-import { IS_DEMO } from '@/composables/useDemoIntro'
+import { IS_DEMO, DEMO_PASSWORD } from '@/composables/useDemoIntro'
+import { useLoginTransitionStore } from '@/stores/loginTransition'
+import { rpcClient } from '@/api/rpc-client'
 
 const STORAGE_KEY = 'neode_companion_intro_seen'
 // Absolute URL so the QR works when scanned by a phone (a relative path has no
@@ -89,21 +145,63 @@ const DEFAULT_DOWNLOAD_URL = IS_DEMO
   ? `${window.location.origin}/packages/archipelago-companion.apk`
   : 'http://146.59.87.168:3000/lfg2025/archy/raw/branch/main/neode-ui/public/packages/archipelago-companion.apk'
 
+// Deep-link scheme the companion app registers; carries the server entry the
+// app should create (see docs/companion-pairing-qr.md for the contract).
+const PAIR_SCHEME = 'archipelago://pair'
+const DEMO_SERVER_URL = 'https://demo.archipelago-foundation.org'
+
 const visible = ref(false)
+const step = ref<'download' | 'pair'>('download')
+const slideName = ref('slide-forward')
 const qrDataUrl = ref('')
+const pairQrDataUrl = ref('')
+const pairingUrl = ref('')
 const companionDownloadUrl = import.meta.env.VITE_COMPANION_APK_URL || DEFAULT_DOWNLOAD_URL
 
+const loginTransition = useLoginTransitionStore()
+
+// Base delay before the popup may appear, and extra breathing room after the
+// dashboard entrance cinematic ends so the popup never cuts into the reveal.
+const BASE_DELAY_MS = 5000
+const POST_INTRO_GRACE_MS = 2000
+
+let calmTicker: ReturnType<typeof setInterval> | null = null
+
 onMounted(() => {
   try {
     if (localStorage.getItem(STORAGE_KEY) !== '1') {
-      // Delay slightly so it doesn't compete with login animation
-      setTimeout(() => { visible.value = true }, 5000)
+      setTimeout(maybeShow, BASE_DELAY_MS)
     }
   } catch {
     // localStorage unavailable
   }
 })
 
+onUnmounted(() => {
+  if (calmTicker) clearInterval(calmTicker)
+})
+
+function maybeShow() {
+  // Show only after the scene has been CONTINUOUSLY calm (no reveal
+  // cinematic) for the full grace window. The previous point-in-time check
+  // raced a slow-starting reveal — on a cold cache the entrance video can
+  // begin buffering after the 5s base delay, so the flag was still false
+  // when sampled and the popup cut straight into the cinematic.
+  let calmSince = loginTransition.introCinematicPlaying ? null : Date.now()
+  calmTicker = setInterval(() => {
+    if (loginTransition.introCinematicPlaying) {
+      calmSince = null
+      return
+    }
+    if (calmSince === null) calmSince = Date.now()
+    if (Date.now() - calmSince >= POST_INTRO_GRACE_MS) {
+      if (calmTicker) clearInterval(calmTicker)
+      calmTicker = null
+      visible.value = true
+    }
+  }, 250)
+}
+
 watch(visible, async (isVisible) => {
   if (!isVisible) return
   qrDataUrl.value = await QRCode.toDataURL(companionDownloadUrl, {
@@ -117,8 +215,58 @@ watch(visible, async (isVisible) => {
   })
 }, { immediate: true, flush: 'post' })
 
+/**
+ * The server URL the companion app should connect to. The demo advertises its
+ * public https origin; a real node advertises whatever address the browser is
+ * already using — except on the kiosk, where that is localhost and useless to
+ * a phone, so fall back to the node's mDNS .local name.
+ */
+async function resolveServerUrl(): Promise<string> {
+  if (IS_DEMO) return DEMO_SERVER_URL
+  const { hostname, origin } = window.location
+  if (hostname !== 'localhost' && hostname !== '127.0.0.1') return origin
+  try {
+    const res = await rpcClient.call<{ mdns_hostname?: string }>({ method: 'system.get-hostname' })
+    if (res?.mdns_hostname) return `http://${res.mdns_hostname}`
+  } catch {
+    // RPC unavailable — fall through to the (localhost) origin
+  }
+  return origin
+}
+
+async function buildPairingUrl(): Promise<string> {
+  const params = new URLSearchParams({ v: '1', url: await resolveServerUrl() })
+  // Only the shared demo password ever rides in the QR; real node passwords
+  // are never available to the frontend and stay typed-by-hand in the app.
+  if (IS_DEMO) params.set('pw', DEMO_PASSWORD)
+  return `${PAIR_SCHEME}?${params.toString()}`
+}
+
+async function showPairScreen() {
+  slideName.value = 'slide-forward'
+  step.value = 'pair'
+  if (!pairQrDataUrl.value) {
+    pairingUrl.value = await buildPairingUrl()
+    pairQrDataUrl.value = await QRCode.toDataURL(pairingUrl.value, {
+      width: 112,
+      margin: 1,
+      errorCorrectionLevel: 'M',
+      color: {
+        dark: '#111111',
+        light: '#ffffff',
+      },
+    })
+  }
+}
+
+function showDownloadScreen() {
+  slideName.value = 'slide-back'
+  step.value = 'download'
+}
+
 function dismiss() {
   visible.value = false
+  step.value = 'download'
   try {
     localStorage.setItem(STORAGE_KEY, '1')
   } catch {
@@ -134,4 +282,14 @@ function dismiss() {
 .overlay-fade-leave-to { opacity: 0; }
 .overlay-fade-enter-active .glass-card { transition: transform 0.3s ease; }
 .overlay-fade-enter-from .glass-card { transform: translateY(20px); }
+
+/* Horizontal slide between the download and pairing screens */
+.slide-forward-enter-active,
+.slide-forward-leave-active,
+.slide-back-enter-active,
+.slide-back-leave-active { transition: transform 0.25s ease, opacity 0.25s ease; }
+.slide-forward-enter-from { transform: translateX(40px); opacity: 0; }
+.slide-forward-leave-to { transform: translateX(-40px); opacity: 0; }
+.slide-back-enter-from { transform: translateX(-40px); opacity: 0; }
+.slide-back-leave-to { transform: translateX(40px); opacity: 0; }
 </style>

neode-ui/src/components/LndSeedBackupPrompt.vue

@@ -101,7 +101,10 @@ const show = computed(() =>
 )
 
 function backUpNow() {
-  router.push(LND_DETAILS_PATH).catch(() => {})
+  // seed-backup=1 makes the LND page open the reveal flow immediately —
+  // landing on the app page with the card below the fold read as
+  // "clicking the notification did nothing".
+  router.push({ path: LND_DETAILS_PATH, query: { 'seed-backup': '1' } }).catch(() => {})
 }
 
 function snooze() {

neode-ui/src/components/PWAUpdatePrompt.vue

@@ -25,16 +25,49 @@
 <script setup lang="ts">
 import { ref, onMounted } from 'vue'
 import BaseModal from '@/components/BaseModal.vue'
+import { useLoginTransitionStore } from '@/stores/loginTransition'
 
 const showUpdatePrompt = ref(false)
 let updateCallback: (() => Promise<void>) | null = null
 
+// Reload for a genuine SW update — but never mid-cinematic. The splash
+// typing intro and the dashboard-reveal cinematic are the two moments a
+// surprise reload reads as "the app just reset itself" (kiosk and demo
+// replay the intro on every boot/visit, so an update landing during it
+// restarted the whole sequence). Wait until both are over, then reload.
+function reloadAfterCinematic() {
+  const loginTransition = useLoginTransitionStore()
+  const calm = () =>
+    document.body.classList.contains('splash-complete') &&
+    !loginTransition.introCinematicPlaying
+  if (calm()) {
+    window.location.reload()
+    return
+  }
+  const poll = setInterval(() => {
+    if (calm()) {
+      clearInterval(poll)
+      window.location.reload()
+    }
+  }, 1000)
+}
+
 onMounted(() => {
   // Listen for service worker updates
   if ('serviceWorker' in navigator) {
+    // On the very first visit the page loads with no controlling SW; the
+    // freshly-installed worker then activates and claims the page
+    // (autoUpdate → clientsClaim), firing controllerchange. Reloading on
+    // that first claim caused the fresh-install "loads, then reloads"
+    // jank (worst on kiosk). Only reload when an existing controller is
+    // REPLACED — i.e. a genuine update.
+    let hadController = !!navigator.serviceWorker.controller
     navigator.serviceWorker.addEventListener('controllerchange', () => {
-      // Service worker updated, reload the page
-      window.location.reload()
+      if (!hadController) {
+        hadController = true
+        return
+      }
+      reloadAfterCinematic()
     })
 
     // Check for updates periodically

neode-ui/src/composables/useControllerNav.ts

@@ -199,6 +199,22 @@ function focusEl(el: HTMLElement, sound: 'move' | 'action' | 'back' = 'move') {
   el.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
 }
 
+// ─── Nav-Ring Modality ──────────────────────────────────────────
+// The orange focus ring must only render while the user is actually
+// navigating directionally (arrows / gamepad). Ring visibility is gated in
+// CSS behind html.controller-nav; directional input turns it on, any
+// pointer input (tap, click) turns it off. Without this gate the ring
+// painted on plain :focus — every tap on a tabindex card, and every
+// programmatic route-change autofocus, lit it up with no controller in
+// sight (worst on mobile).
+function setNavRing(on: boolean) {
+  document.documentElement.classList.toggle('controller-nav', on)
+}
+
+function navRingActive(): boolean {
+  return document.documentElement.classList.contains('controller-nav')
+}
+
 // ─── Main Composable ────────────────────────────────────────────
 
 export function useControllerNav(containerRef?: { value: HTMLElement | null }) {
@@ -396,9 +412,18 @@ export function useControllerNav(containerRef?: { value: HTMLElement | null }) {
 
     // Mark controller as active
     isControllerActive.value = true
+    setNavRing(true)
     if (keyNavTimeout) clearTimeout(keyNavTimeout)
     keyNavTimeout = setTimeout(() => { isControllerActive.value = gamepadCount.value > 0 }, 3000)
 
+    // Nothing focused yet (fresh page, or focus was lost) — enter nav mode
+    // on the first arrow press by focusing the first container, instead of
+    // spatially navigating from <body>.
+    if (!activeEl || activeEl === document.body || activeEl === document.documentElement) {
+      autoFocusMain()
+      return
+    }
+
     const dir = e.key === 'ArrowLeft' ? 'left' as const
       : e.key === 'ArrowRight' ? 'right' as const
       : e.key === 'ArrowUp' ? 'up' as const
@@ -611,6 +636,7 @@ export function useControllerNav(containerRef?: { value: HTMLElement | null }) {
     const gamepads = navigator.getGamepads?.()
     gamepadCount.value = gamepads ? Array.from(gamepads).filter(g => g?.connected).length : 1
     isControllerActive.value = true
+    setNavRing(true)
   }
 
   function handleGamepadDisconnected() {
@@ -644,6 +670,10 @@ export function useControllerNav(containerRef?: { value: HTMLElement | null }) {
   // ─── Auto-Focus on Route Change ────────────────────────────
 
   function autoFocusMain() {
+    // Only when the user is actually in directional-nav mode. For pointer
+    // and touch users this programmatic focus painted the first card's
+    // focus ring on every route change with zero controller input.
+    if (!navRingActive()) return
     const active = document.activeElement as HTMLElement | null
     // Don't steal focus from inputs, modals, or sidebar
     if (active && (active.tagName === 'INPUT' || active.tagName === 'TEXTAREA')) return
@@ -668,9 +698,16 @@ export function useControllerNav(containerRef?: { value: HTMLElement | null }) {
 
   // ─── Lifecycle ─────────────────────────────────────────────
 
+  // Any pointer interaction ends directional-nav mode — the ring should
+  // never linger once the user reaches for mouse or touch.
+  function handlePointerDown() {
+    setNavRing(false)
+  }
+
   onMounted(() => {
     checkGamepads()
     window.addEventListener('keydown', handleKeyDown, true)
+    window.addEventListener('pointerdown', handlePointerDown, { capture: true, passive: true })
     window.addEventListener('wheel', handleWheel, { passive: false })
     window.addEventListener('gamepadconnected', handleGamepadConnected)
     window.addEventListener('gamepaddisconnected', handleGamepadDisconnected)
@@ -680,11 +717,13 @@ export function useControllerNav(containerRef?: { value: HTMLElement | null }) {
 
   onBeforeUnmount(() => {
     window.removeEventListener('keydown', handleKeyDown, true)
+    window.removeEventListener('pointerdown', handlePointerDown, { capture: true } as EventListenerOptions)
     window.removeEventListener('wheel', handleWheel)
     window.removeEventListener('gamepadconnected', handleGamepadConnected)
     window.removeEventListener('gamepaddisconnected', handleGamepadDisconnected)
     if (pollIntervalId) clearInterval(pollIntervalId)
     if (keyNavTimeout) clearTimeout(keyNavTimeout)
+    setNavRing(false)
   })
 
   return { isControllerActive, gamepadCount }

neode-ui/src/stores/loginTransition.ts

@@ -15,6 +15,12 @@ export const useLoginTransitionStore = defineStore('loginTransition', () => {
   const pendingWelcomeTyping = ref(false)
   /** Trigger welcome typing on Home - set true after dashboard animation finishes */
   const startWelcomeTyping = ref(false)
+  /**
+   * True while the dashboard entrance cinematic (zoom/glitch reveal) is
+   * playing. Overlays that would visually compete with it (e.g. the
+   * companion intro popup) hold off until this flips back to false.
+   */
+  const introCinematicPlaying = ref(false)
 
   function setJustLoggedIn(value: boolean) {
     justLoggedIn.value = value
@@ -32,6 +38,10 @@ export const useLoginTransitionStore = defineStore('loginTransition', () => {
     startWelcomeTyping.value = value
   }
 
+  function setIntroCinematicPlaying(value: boolean) {
+    introCinematicPlaying.value = value
+  }
+
   return {
     justLoggedIn,
     setJustLoggedIn,
@@ -41,5 +51,7 @@ export const useLoginTransitionStore = defineStore('loginTransition', () => {
     setPendingWelcomeTyping,
     startWelcomeTyping,
     setStartWelcomeTyping,
+    introCinematicPlaying,
+    setIntroCinematicPlaying,
   }
 })

neode-ui/src/style.css

@@ -270,9 +270,13 @@ input[type="radio"]:active + * {
 
 /* Containers: console-style focus — lift + ambient orange glow.
    Pure glow approach — no border-color or outline changes, avoids
-   Chromium compositor bugs with border-radius on translateZ(0) layers. */
-[data-controller-container]:focus-visible,
-[data-controller-container]:focus {
+   Chromium compositor bugs with border-radius on translateZ(0) layers.
+   Gated behind html.controller-nav (set by useControllerNav only while
+   the user navigates with arrows/gamepad; cleared on any pointer input).
+   Ungated, the plain :focus selector painted the ring on every tap of a
+   tabindex card — the "gamepad selection with no gamepad" bug on mobile. */
+html.controller-nav [data-controller-container]:focus-visible,
+html.controller-nav [data-controller-container]:focus {
   outline: none;
   transform: translateY(-4px) scale(1.01);
   box-shadow:
@@ -1615,6 +1619,18 @@ html.no-backdrop *::after {
   -webkit-backdrop-filter: none !important;
 }
 
+/* Kiosk: the infinite mix-blend-mode:multiply glitch overlays with
+   background-attachment:fixed are a known black-screen vector under the
+   kiosk's software compositor — a missed repaint leaves a dark multiply
+   layer stuck over the whole viewport. Their base opacity is 0, so
+   disabling the animations hides them entirely on kiosk. */
+html.kiosk-mode body::before,
+html.kiosk-mode body::after,
+html.kiosk-mode::before {
+  animation: none !important;
+  will-change: auto !important;
+}
+
 /* Dashboard: full viewport width, no letterboxing, no body scroll */
 body.dashboard-active {
   overflow: hidden;

neode-ui/src/views/Dashboard.vue

@@ -373,6 +373,7 @@ onMounted(() => {
     // un-forced call would gate itself silent.
     playDashboardLoadOomph(true)
     showZoomIn.value = true
+    loginTransition.setIntroCinematicPlaying(true)
     loginTransition.setPendingWelcomeTyping(true)
     loginTransition.setJustCompletedOnboarding(false)
     loginTransition.setJustLoggedIn(false)
@@ -383,7 +384,10 @@ onMounted(() => {
     scheduledTimeout(triggerRevealGlitch, 500)
     scheduledTimeout(triggerRevealGlitch, 1200)
     scheduledTimeout(triggerRevealGlitch, 2000)
-    scheduledTimeout(() => { showZoomIn.value = false }, 8000)
+    scheduledTimeout(() => {
+      showZoomIn.value = false
+      loginTransition.setIntroCinematicPlaying(false)
+    }, 8000)
     scheduledTimeout(() => {
       loginTransition.setStartWelcomeTyping(true)
       loginTransition.setPendingWelcomeTyping(false)
@@ -405,6 +409,9 @@ onMounted(() => {
 
 onBeforeUnmount(() => {
   document.body.classList.remove('dashboard-active')
+  // Timers are cleared below; make sure overlays waiting on the cinematic
+  // aren't left blocked forever if we unmount mid-reveal.
+  loginTransition.setIntroCinematicPlaying(false)
   window.removeEventListener('keydown', handleKioskShortcuts)
   for (const id of pendingTimers) clearTimeout(id)
   pendingTimers.length = 0

neode-ui/src/views/OnboardingWrapper.vue

@@ -682,5 +682,30 @@ video.bg-layer {
     transform: translateX(1px);
   }
 }
+
+/* Kiosk (software compositor): flatten THIS screen's background stack.
+   Same failure mode the dashboard kiosk fix addressed — perspective +
+   preserve-3d layers and mix-blend-mode overlays fail to repaint under
+   Chromium software compositing, so the black body fill shows through.
+   The dashboard-only overrides never reached this scoped stack, which is
+   why the kiosk login/onboarding background still went black. Keep 2D
+   opacity crossfades; drop 3D transforms, blur filters, and blend-mode
+   glitch overlays. */
+:global(html.kiosk-mode) .bg-perspective-container,
+:global(html.kiosk-mode) .perspective-container {
+  perspective: none !important;
+}
+:global(html.kiosk-mode) .bg-layer,
+:global(html.kiosk-mode) .view-wrapper {
+  transform: none !important;
+  transform-style: flat !important;
+  backface-visibility: visible !important;
+  will-change: auto !important;
+  filter: none !important;
+}
+:global(html.kiosk-mode) .login-glitch-layer,
+:global(html.kiosk-mode) .login-glitch-scan {
+  display: none !important;
+}
 </style>
 

neode-ui/src/views/RootRedirect.vue

@@ -40,10 +40,10 @@ function log(msg: string, data?: unknown) {
   sessionStorage.setItem('archipelago_boot_log', prev + entry + '\n')
 }
 
-async function quickHealthCheck(): Promise<boolean> {
+async function quickHealthCheck(timeoutMs = 2000): Promise<boolean> {
   try {
     const ac = new AbortController()
-    const t = setTimeout(() => ac.abort(), 2000)
+    const t = setTimeout(() => ac.abort(), timeoutMs)
     const res = await fetch('/rpc/v1', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
@@ -132,7 +132,16 @@ onMounted(async () => {
     return
   }
 
-  const isUp = await quickHealthCheck()
+  // First-boot backends can be up but slow (image loads, first-run podman
+  // work), so a single 2s echo timing out used to flash the BootScreen and
+  // then hard-reload seconds later ("loads, refreshes, loads again" on
+  // kiosk). Give it a second, more patient attempt before concluding the
+  // server is down.
+  let isUp = await quickHealthCheck()
+  if (!isUp) {
+    log('healthCheck retry with longer timeout')
+    isUp = await quickHealthCheck(6000)
+  }
   log('production flow', { isUp })
 
   if (isUp) {

neode-ui/src/views/appDetails/LndSeedBackup.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { ref, onMounted } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
 import { rpcClient } from '@/api/rpc-client'
 
 // Lightning seed (aezeed) backup card. Shown on the LND app detail page.
@@ -7,11 +8,14 @@ import { rpcClient } from '@/api/rpc-client'
 // confirms writing it down (`acknowledged`), the card renders as a
 // prominent first-launch prompt.
 
+const route = useRoute()
+const router = useRouter()
+
 const available = ref(false)
 const acknowledged = ref(true)
 const statusLoaded = ref(false)
 
-async function loadStatus() {
+async function loadStatus(): Promise<boolean> {
   try {
     const res = await rpcClient.call<{ available: boolean; acknowledged: boolean }>({
       method: 'lnd.seed-backup-status',
@@ -20,12 +24,28 @@ async function loadStatus() {
     available.value = !!res.available
     acknowledged.value = !!res.acknowledged
     statusLoaded.value = true
+    return true
   } catch {
-    statusLoaded.value = false
+    // Leave statusLoaded as-is; a one-off RPC blip must not permanently
+    // hide the card (the global banner may have just promised it's here).
+    return false
   }
 }
 
-onMounted(loadStatus)
+onMounted(async () => {
+  // Retry a few times — on fresh installs the backend can still be warming
+  // up when the user lands here straight from the backup banner.
+  for (let attempt = 0; attempt < 4; attempt++) {
+    if (await loadStatus()) break
+    await new Promise((r) => setTimeout(r, 1500 * (attempt + 1)))
+  }
+  // Deep link from the "Back up your Lightning seed" banner: open the
+  // reveal flow directly so the click visibly does something.
+  if (route.query['seed-backup'] === '1') {
+    router.replace({ query: { ...route.query, 'seed-backup': undefined } }).catch(() => {})
+    if (statusLoaded.value && available.value) openReveal()
+  }
+})
 
 // Reveal modal — re-auth gated (password + 2FA when enabled), same UX as
 // the recovery-phrase reveal in Settings → Backup.

neode-ui/src/views/dashboard/ConnectionBanner.vue

@@ -40,6 +40,7 @@
 <script setup lang="ts">
 import { computed, ref, watch, onUnmounted } from 'vue'
 import { useAppStore } from '@/stores/app'
+import { IS_DEMO } from '@/composables/useDemoIntro'
 
 const store = useAppStore()
 
@@ -62,8 +63,23 @@ const hasConnIssue = computed(
 )
 
 const SHOW_DELAY_MS = 2500
+// Right after the page loads or the tab returns to the foreground, a dead
+// WebSocket is the NORMAL state (browsers kill sockets in background tabs;
+// first paint races the initial connect). Reconnecting takes longer than
+// the steady-state grace on real links — radio wake-up, TLS, proxies — so
+// the 2.5s window made every tab-return flash "Connection lost" on a
+// perfectly healthy node. Give those moments a much longer runway; keep
+// the short window for genuine mid-session drops.
+const RESUME_GRACE_WINDOW_MS = 15000
+const RESUME_SHOW_DELAY_MS = 10000
 const showConnIssue = ref(false)
 let pendingTimer: ReturnType<typeof setTimeout> | null = null
+let lastResumeAt = Date.now() // mount counts as a resume (initial connect)
+
+function onVisibilityResume() {
+  if (!document.hidden) lastResumeAt = Date.now()
+}
+document.addEventListener('visibilitychange', onVisibilityResume)
 
 function clearTimer() {
   if (pendingTimer) {
@@ -76,11 +92,17 @@ watch(
   hasConnIssue,
   (issue) => {
     clearTimer()
+    // The demo runs against a local mock — a connection banner there is
+    // meaningless noise on what should be a flawless showcase.
+    if (IS_DEMO) return
     if (issue) {
+      const delay = Date.now() - lastResumeAt < RESUME_GRACE_WINDOW_MS
+        ? RESUME_SHOW_DELAY_MS
+        : SHOW_DELAY_MS
       pendingTimer = setTimeout(() => {
         showConnIssue.value = true
         pendingTimer = null
-      }, SHOW_DELAY_MS)
+      }, delay)
     } else {
       // Recovered before the grace window elapsed — hide at once.
       showConnIssue.value = false
@@ -89,7 +111,10 @@ watch(
   { immediate: true }
 )
 
-onUnmounted(clearTimer)
+onUnmounted(() => {
+  clearTimer()
+  document.removeEventListener('visibilitychange', onVisibilityResume)
+})
 
 // Debounced visual states the template renders.
 const showReconnecting = computed(

neode-ui/src/views/dashboard/dashboard-styles.css

@@ -741,6 +741,21 @@ aside:not(.sidebar-animate) .sidebar-logout-btn {
   transform: translateZ(0) scale(1.05) rotateY(0deg) !important;
 }
 
+/* Kiosk: chromium runs software-composited (--in-process-gpu or
+   --disable-gpu, single raster thread). 3D-transformed will-change layers
+   routinely fail to repaint there after the first background swap, leaving
+   the container's black fill on screen. Flatten the stack to plain 2D
+   opacity crossfades in kiosk mode. */
+html.kiosk-mode .dashboard-view .bg-perspective-container {
+  perspective: none;
+}
+html.kiosk-mode .dashboard-view .bg-layer {
+  transform: none !important;
+  transform-style: flat;
+  will-change: auto;
+  transition: opacity 0.45s ease;
+}
+
 /* Background glitch effect layers - World Fair style */
 .bg-glitch-layer-1,
 .bg-glitch-layer-2,

neode-ui/src/views/discover/curatedApps.ts

@@ -105,6 +105,7 @@ export function getCuratedAppList(): MarketplaceApp[] {
     { id: 'netbird', title: 'NetBird', version: '0.71.2', description: 'Self-hosted WireGuard mesh VPN control plane with dashboard, embedded identity provider, management API, signal, relay, and STUN.', icon: '/assets/img/app-icons/netbird.svg', author: 'NetBird', dockerImage: 'docker.io/netbirdio/dashboard:v2.38.0', repoUrl: 'https://github.com/netbirdio/netbird' },
     { id: 'electrumx', title: 'ElectrumX', version: '1.18.0', description: 'Electrum protocol server. Index the blockchain for fast wallet lookups, privately.', icon: '/assets/img/app-icons/electrumx.png', author: 'Luke Childs', dockerImage: `${R}/electrumx:v1.18.0`, repoUrl: 'https://github.com/spesmilo/electrumx' },
     { id: 'fedimint', title: 'Fedimint Guardian', version: '0.10.0', description: 'Federated Bitcoin mint. Private, scalable Bitcoin through federated guardians.', icon: '/assets/img/app-icons/fedimint.png', author: 'Fedimint', dockerImage: `${R}/fedimintd:v0.10.0`, repoUrl: 'https://github.com/fedimint/fedimint' },
+    { id: 'fedimint-clientd', title: 'Fedimint Client', version: '0.8.0', description: 'Fedimint ecash client daemon (fmcd). Lets the node hold Fedimint ecash and join federations; the wallet talks to it over a local REST API.', icon: '/assets/img/app-icons/fedimint.png', author: 'Fedimint', dockerImage: `${R}/fmcd:0.8.1`, repoUrl: 'https://github.com/minmoto/fmcd' },
     { id: 'indeedhub', title: 'Indeehub', version: '1.0.0', description: 'Bitcoin documentary streaming with Nostr identity. Stream sovereignty content.', icon: '/assets/img/app-icons/indeedhub.png', author: 'Indeehub Team', dockerImage: `${R}/indeedhub:1.0.0`, repoUrl: 'https://github.com/indeedhub/indeedhub' },
     { id: 'nostrudel', title: 'noStrudel', version: '0.40.0', category: 'nostr', description: 'Feature-rich Nostr web client. Browse feeds, post notes, manage relays with NIP-07.', icon: '/assets/img/app-icons/nostrudel.svg', author: 'hzrd149', dockerImage: '', repoUrl: 'https://github.com/hzrd149/nostrudel', webUrl: 'https://nostrudel.ninja' },
     { id: 'botfights', title: 'BotFights', version: '1.0.0', category: 'community', description: 'Bot arena + 2-player arcade fighter with controller support. AI bots battle in trivia, humans duke it out with controllers.', icon: '/assets/img/app-icons/botfights.svg', author: 'BotFights', dockerImage: `${R}/botfights:1.1.0`, repoUrl: 'https://botfights.net' },
@@ -122,6 +123,7 @@ export const INSTALLED_ALIASES: Record<string, string[]> = {
   immich: ['immich-server', 'immich-app', 'immich_server'],
   nextcloud: ['nextcloud-aio', 'nextcloud-server'],
   fedimint: ['fedimint-gateway'],
+  'fedimint-clientd': ['fedimint-clientd'],
   electrumx: ['electrumx'],
   grafana: ['grafana'],
   jellyfin: ['jellyfin'],

neode-ui/src/views/settings/BackupSection.vue

@@ -126,6 +126,31 @@ async function deleteBackup(id: string) {
   }
 }
 
+// Download the encrypted backup archive through the browser — the only
+// path off the node for remote/companion users with no USB access.
+const downloadingId = ref<string | null>(null)
+async function downloadBackup(id: string) {
+  downloadingId.value = id
+  try {
+    const res = await fetch(`/api/blob/backup/${encodeURIComponent(id)}`, { credentials: 'include' })
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const blob = await res.blob()
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = `archipelago-backup-${id}.bak`
+    document.body.appendChild(a)
+    a.click()
+    a.remove()
+    URL.revokeObjectURL(url)
+    showBackupStatus('Backup download started', 'success')
+  } catch {
+    showBackupStatus('Backup download failed', 'error')
+  } finally {
+    downloadingId.value = null
+  }
+}
+
 // Recovery phrase reveal — re-auth gated (password + 2FA when enabled).
 const showRevealModal = ref(false)
 const revealPassword = ref('')
@@ -364,6 +389,9 @@ defineExpose({ loadBackups })
           <button @click="backupToUsb(b.id)" :disabled="usbCopyingId === b.id" class="glass-button glass-button-sm px-3 py-1.5 rounded text-xs text-blue-400 disabled:opacity-50" :title="t('settings.copyToUsb')">
             {{ usbCopyingId === b.id ? '...' : 'USB' }}
           </button>
+          <button @click="downloadBackup(b.id)" :disabled="downloadingId === b.id" class="glass-button glass-button-sm px-3 py-1.5 rounded text-xs text-green-400 disabled:opacity-50" title="Download backup file">
+            {{ downloadingId === b.id ? '...' : 'Download' }}
+          </button>
           <button @click="confirmRestoreBackup(b.id)" class="glass-button glass-button-sm px-3 py-1.5 rounded text-xs text-orange-400" :title="t('common.restore')">
             {{ t('common.restore') }}
           </button>

scripts/first-boot-containers.sh

@@ -112,6 +112,13 @@ if [ -f "$UNBUNDLED_MARKER" ]; then
     # Helper: pull image with fallback registry
     pull_with_fallback() {
         local img="$1"
+        # Pre-bundled ISO images are already loaded into the rootless
+        # storage by archipelago-load-images.service — use them and skip
+        # the network entirely (fresh installs must work offline).
+        if $DOCKER image exists "$img" 2>/dev/null; then
+            log "  Image already present locally: $img"
+            return 0
+        fi
         log "  Pulling $img..."
         if $DOCKER pull "$img" 2>>"$LOG"; then
             return 0

scripts/image-versions.sh

@@ -59,9 +59,10 @@ ADGUARDHOME_IMAGE="$ARCHY_REGISTRY/adguardhome:v0.107.55"
 FEDIMINT_IMAGE="$ARCHY_REGISTRY/fedimintd:v0.10.0"
 FEDIMINT_GATEWAY_IMAGE="$ARCHY_REGISTRY/gatewayd:v0.10.0"
 # fmcd = Fedimint client daemon (iroh-capable, fedimint-client 0.8.2). Built
-# from minmoto/fmcd. NOT yet added to the bundled CONTAINER_IMAGES list / first-
-# boot auto-create: bundling fleet-wide needs a fleet-reachable default
-# federation first (the interim default is node-local). See docs/dual-ecash-design.md.
+# from minmoto/fmcd. Bundled on the ISO in BOTH modes (full CONTAINER_IMAGES
+# list and the unbundled core bundle) and auto-created by first-boot as a
+# baseline app so ecash works offline out of the box.
+# See docs/dual-ecash-design.md.
 FMCD_IMAGE="$ARCHY_REGISTRY/fmcd:0.8.1"
 
 # Ark (bark)