chore(android): update companion APK download [skip ci]

The 0.4.11 edit affordance only lived on ServerConnectScreen, which a
connected user never sees. Add edit to NESMenu — the settings modal
reached via two-finger hold while connected: a ✎ pencil on each saved
server opens the form pre-populated (Edit Server header + Cancel),
persists via ServerPreferences.updateSavedServer(), and reconnects when
the edited server is the live one.

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

.githooks/pre-push

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Keep the served companion APK in sync with main on every push.
+#
+# When a push to main includes Android changes, rebuild the APK, refresh
+# neode-ui/public/packages/archipelago-companion.apk, commit it, and ask
+# you to push again (so the refreshed APK rides along in the same push).
+#
+# Enable once per clone:  git config core.hooksPath .githooks
+set -euo pipefail
+
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+# ship-companion.sh already (re)published the APK for this push — don't redo it.
+[ -n "${SHIP_COMPANION:-}" ] && exit 0
+
+PUSH_MAIN=0; RANGE_OLD=""; RANGE_NEW=""
+while read -r _local_ref local_sha remote_ref remote_sha; do
+  if [ "${remote_ref##*/}" = "main" ]; then
+    PUSH_MAIN=1; RANGE_OLD="$remote_sha"; RANGE_NEW="$local_sha"
+  fi
+done
+[ "$PUSH_MAIN" = "1" ] || exit 0
+
+# Loop-break: if the tip is already the auto APK commit, let the push proceed.
+case "$(git log -1 --pretty=%s)" in
+  *"companion APK"*) exit 0 ;;
+esac
+
+# Only rebuild when this push actually touches the Android app.
+ZEROS="0000000000000000000000000000000000000000"
+if [ -z "$RANGE_OLD" ] || [ "$RANGE_OLD" = "$ZEROS" ]; then
+  ANDROID_CHANGED=1
+elif git diff --quiet "$RANGE_OLD" "$RANGE_NEW" -- Android/ 2>/dev/null; then
+  ANDROID_CHANGED=0
+else
+  ANDROID_CHANGED=1
+fi
+[ "$ANDROID_CHANGED" = "1" ] || exit 0
+
+bash scripts/publish-companion-apk.sh || exit 0
+
+DEST="neode-ui/public/packages/archipelago-companion.apk"
+if git diff --cached --quiet -- "$DEST"; then
+  exit 0   # APK unchanged — nothing to do
+fi
+
+git commit -q -m "chore(android): update companion APK download [skip ci]"
+echo "" >&2
+echo "▶ Companion APK rebuilt and committed. Run your push again to include it." >&2
+exit 1

Android/.gitignore

@@ -14,3 +14,8 @@ local.properties
 *.aab
 *.jks
 *.keystore
+# Exception: the repo-dedicated *debug* keystore is committed on purpose so every
+# machine (and the published companion download) signs debug builds identically —
+# updates then install over the top without an uninstall. Debug keys are not
+# secret (well-known password "android"); never commit a real release keystore.
+!/app/debug.keystore

Android/COMPANION_RELEASE.md

@@ -0,0 +1,94 @@
+# Companion App — Build, Ship & "App Not Installed" Runbook
+
+Canonical procedure for releasing the Archipelago Companion Android app and for
+debugging install failures. Read this before touching the companion release flow.
+Hard lessons from 2026-06-26 are baked in below — don't relearn them.
+
+## Ship the companion (the only sanctioned way)
+
+```bash
+./Android/ship-companion.sh
+```
+
+This calls `scripts/publish-companion-apk.sh` (the single source of truth, also
+used by the `.githooks/pre-push` hook), which:
+
+1. **Removes/rejects resource dirs whose names contain spaces.** Empty stray
+   `mipmap-* NNN` dirs (left by icon-export tools) break a *clean* build with
+   `Invalid resource directory name`. Incremental builds hide them — clean builds
+   don't.
+2. **Always does a CLEAN build** (`:app:clean :app:assembleDebug`).
+3. **Forces v1 + v2 + v3 signing** via `zipalign` + `apksigner`.
+4. **Verifies all three schemes** (`apksigner verify --min-sdk-version 21`) and
+   **aborts** if any is missing.
+5. Stages the signed APK at `neode-ui/public/packages/archipelago-companion.apk`,
+   commits, and pushes with `SHIP_COMPANION=1` (the sanctioned pre-push bypass).
+
+**Never** hand-roll `gradlew assembleDebug` + `cp` to the served path. That path
+skips the clean build and the signature enforcement and is exactly how a broken
+APK shipped.
+
+### Bump the version first
+Edit `Android/app/build.gradle.kts` — `versionCode` (must strictly increase) and
+`versionName`. The committed value can drift AHEAD of what's actually built into
+the served APK, so verify the served APK's real version after shipping:
+`aapt2 dump badging neode-ui/public/packages/archipelago-companion.apk | grep version`.
+
+## Signing facts (important)
+
+- Debug builds are signed with the **committed** `Android/app/debug.keystore`
+  (store/key pass `android`, alias `androiddebugkey`) so every machine and the
+  served download share ONE signing key. Cert SHA-256: `D6:22:E0:7E:…:66:4D`.
+- **AGP silently ignores `enableV1Signing = true` for `minSdk ≥ 24`**, so a plain
+  gradle build produces a **v2-only** APK. The `apksigner` step in the publish
+  script is what actually guarantees v1+v2+v3 — do not remove it.
+- **Changing the signing key forces every existing install to be uninstalled
+  once.** Android blocks in-place upgrades across different signatures. Treat the
+  keystore as permanent; never regenerate it casually.
+
+## Debugging "App Not Installed" — DIAGNOSE FIRST
+
+Do **not** theorize about signing schemes / OEM quirks. Get the real reason:
+
+```bash
+adb install ~/Desktop/archipelago-companion-<ver>.apk
+# -> Failure [INSTALL_FAILED_<REASON>: ...]
+```
+
+Map the reason:
+
+| `INSTALL_FAILED_*` | Cause | Fix |
+|---|---|---|
+| `UPDATE_INCOMPATIBLE … signatures do not match` | Old install signed with a **different key** (e.g. pre-shared-keystore per-machine key `58:31:12…`). | Uninstall the old package, then install. **One-time** per device after a key change. |
+| `INVALID_APK` / parse error | Corrupt/incomplete download or bad signing. | Re-download; re-run the publish script. |
+| `INSUFFICIENT_STORAGE` | Storage. | Free space. |
+| `OLDER_SDK` | Device below `minSdk` (26 = Android 8.0). | Unsupported device. |
+
+> A manual uninstall on the phone may NOT clear `UPDATE_INCOMPATIBLE` if the
+> package is registered under another user/profile — `pm path <pkg>` under user 0
+> can show nothing while the conflict persists. `adb uninstall <pkg>` clears it
+> across all users.
+
+## Phone / adb safety (non-negotiable)
+
+When acting on the user's physical phone, be surgical — the user once had all
+home-screen app layouts wiped by an over-broad action.
+
+- Default to **read-only** adb (`devices`, `getprop`, `pm path/list`, `dumpsys`).
+- Mutations (`adb install`, `adb uninstall com.archipelago.app.debug`) only with
+  explicit go-ahead and **scoped to our exact package** — echo it first.
+- **Never** run launcher/system resets: no `pm clear` on launchers, no
+  `reset-permissions`, no factory wipe, no uninstalling apps you didn't build.
+
+## Verify the published download after shipping
+
+The download served to nodes is Gitea raw-on-main. Confirm the live bytes match
+what you built and signed:
+
+```bash
+SERVED=neode-ui/public/packages/archipelago-companion.apk
+URL=http://146.59.87.168:3000/lfg2025/archy/raw/branch/main/$SERVED
+curl -sS -o /tmp/live.apk "$URL"
+shasum -a 256 "$SERVED" /tmp/live.apk          # must match
+apksigner verify -v --min-sdk-version 21 /tmp/live.apk | grep -i "scheme"  # v1/v2/v3 = true
+```

Android/app/build.gradle.kts

@@ -11,15 +11,41 @@ android {
         applicationId = "com.archipelago.app"
         minSdk = 26
         targetSdk = 35
-        versionCode = 6
-        versionName = "0.4.2"
+        versionCode = 16
+        versionName = "0.4.12"
 
         vectorDrawables {
             useSupportLibrary = true
         }
     }
 
+    signingConfigs {
+        // Repo-dedicated debug keystore (committed at app/debug.keystore) so every
+        // machine — and the published companion download — signs debug builds with
+        // the SAME key. Without this, Gradle falls back to each machine's
+        // ~/.android/debug.keystore, so a build from a different machine has a
+        // different signature and the phone rejects the update ("App not installed").
+        getByName("debug") {
+            storeFile = file("debug.keystore")
+            storePassword = "android"
+            keyAlias = "androiddebugkey"
+            keyPassword = "android"
+            // Force both legacy JAR (v1) and APK Signature Scheme v2. AGP drops v1
+            // for minSdk>=24, but some OEM package installers (e.g. Samsung) reject
+            // a v2-only sideload with "App not installed" — keep v1 for max compat.
+            enableV1Signing = true
+            enableV2Signing = true
+        }
+    }
+
     buildTypes {
+        debug {
+            // Separate app ID so a debug/test build installs alongside the
+            // release app instead of colliding on signature.
+            applicationIdSuffix = ".debug"
+            versionNameSuffix = "-debug"
+            signingConfig = signingConfigs.getByName("debug")
+        }
         release {
             isMinifyEnabled = true
             isShrinkResources = true

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

@@ -18,7 +18,11 @@ data class ServerEntry(
     val useHttps: Boolean,
     val port: String = "",
     val password: String = "",
+    val name: String = "",
 ) {
+    /** Label to show in lists — the user-given name, or the address if unnamed. */
+    fun displayName(): String = name.ifBlank { address }
+
     fun toUrl(): String {
         val scheme = if (useHttps) "https" else "http"
         val portSuffix = if (port.isNotBlank()) ":$port" else ""
@@ -31,7 +35,9 @@ data class ServerEntry(
         return "$scheme://$address$portSuffix"
     }
 
-    fun serialize(): String = "$address|$useHttps|$port|$password"
+    // name is the trailing field so entries saved before naming existed
+    // (4 fields) still deserialize, with name defaulting to "".
+    fun serialize(): String = "$address|$useHttps|$port|$password|$name"
 
     companion object {
         fun deserialize(raw: String): ServerEntry? {
@@ -42,6 +48,7 @@ data class ServerEntry(
                 useHttps = parts[1].toBooleanStrictOrNull() ?: false,
                 port = parts.getOrElse(2) { "" },
                 password = parts.getOrElse(3) { "" },
+                name = parts.getOrElse(4) { "" },
             )
         }
     }
@@ -53,6 +60,7 @@ class ServerPreferences(private val context: Context) {
     private val activeHttpsKey = booleanPreferencesKey("active_https")
     private val activePortKey = stringPreferencesKey("active_port")
     private val activePasswordKey = stringPreferencesKey("active_password")
+    private val activeNameKey = stringPreferencesKey("active_name")
     private val savedServersKey = stringSetPreferencesKey("saved_servers")
     private val introSeenKey = booleanPreferencesKey("intro_seen")
 
@@ -63,6 +71,7 @@ class ServerPreferences(private val context: Context) {
             useHttps = prefs[activeHttpsKey] ?: false,
             port = prefs[activePortKey] ?: "",
             password = prefs[activePasswordKey] ?: "",
+            name = prefs[activeNameKey] ?: "",
         )
     }
 
@@ -81,6 +90,7 @@ class ServerPreferences(private val context: Context) {
             prefs[activeHttpsKey] = server.useHttps
             prefs[activePortKey] = server.port
             prefs[activePasswordKey] = server.password
+            prefs[activeNameKey] = server.name
         }
         addSavedServer(server)
     }
@@ -91,6 +101,7 @@ class ServerPreferences(private val context: Context) {
             prefs.remove(activeHttpsKey)
             prefs.remove(activePortKey)
             prefs.remove(activePasswordKey)
+            prefs.remove(activeNameKey)
         }
     }
 
@@ -101,10 +112,50 @@ class ServerPreferences(private val context: Context) {
         }
     }
 
+    /**
+     * Replace a saved server in place. Matches the existing entry by connection
+     * identity (address/port/scheme) so edits that change the name or password —
+     * or that touch a legacy 4-field entry — still update the right record. If the
+     * edited server is also the active one, the active record is kept in sync.
+     */
+    suspend fun updateSavedServer(original: ServerEntry, updated: ServerEntry) {
+        context.dataStore.edit { prefs ->
+            val current = prefs[savedServersKey] ?: emptySet()
+            val filtered = current.filterNot { raw ->
+                val e = ServerEntry.deserialize(raw)
+                e != null &&
+                    e.address == original.address &&
+                    e.port == original.port &&
+                    e.useHttps == original.useHttps
+            }.toSet()
+            prefs[savedServersKey] = filtered + updated.serialize()
+
+            val isActive = prefs[activeAddressKey] == original.address &&
+                (prefs[activePortKey] ?: "") == original.port &&
+                (prefs[activeHttpsKey] ?: false) == original.useHttps
+            if (isActive) {
+                prefs[activeAddressKey] = updated.address
+                prefs[activeHttpsKey] = updated.useHttps
+                prefs[activePortKey] = updated.port
+                prefs[activePasswordKey] = updated.password
+                prefs[activeNameKey] = updated.name
+            }
+        }
+    }
+
     suspend fun removeSavedServer(server: ServerEntry) {
         context.dataStore.edit { prefs ->
             val current = prefs[savedServersKey] ?: emptySet()
-            prefs[savedServersKey] = current - server.serialize()
+            // Match by connection identity (address/port/scheme) rather than the
+            // exact serialized string, so a rename — or the legacy 4-field format
+            // saved before names existed — still removes the right entry.
+            prefs[savedServersKey] = current.filterNot { raw ->
+                val e = ServerEntry.deserialize(raw)
+                e != null &&
+                    e.address == server.address &&
+                    e.port == server.port &&
+                    e.useHttps == server.useHttps
+            }.toSet()
         }
     }
 

Android/app/src/main/java/com/archipelago/app/network/InputWebSocket.kt

@@ -35,6 +35,13 @@ class InputWebSocket(
     /** Player ID for arcade mode (0 = broadcast, 1 = P1, 2 = P2) */
     var playerId: Int = 0
 
+    /**
+     * Invoked when the kiosk asks us to open a URL in the phone's default
+     * browser ({"t":"o","url":"…"}). "Open in external browser" apps can't be
+     * usefully opened on the kiosk, so the kiosk forwards them here.
+     */
+    var onExternalOpen: ((String) -> Unit)? = null
+
     private val _state = MutableStateFlow(ConnectionState.DISCONNECTED)
     val state: StateFlow<ConnectionState> = _state
 
@@ -127,6 +134,20 @@ class InputWebSocket(
                 reconnectAttempt = 0
             }
 
+            override fun onMessage(webSocket: WebSocket, text: String) {
+                // The only inbound message we act on is an external-open request
+                // forwarded from the kiosk: {"t":"o","url":"https://…"}.
+                try {
+                    val obj = org.json.JSONObject(text)
+                    if (obj.optString("t") == "o") {
+                        val url = obj.optString("url")
+                        if (url.startsWith("http://") || url.startsWith("https://")) {
+                            onExternalOpen?.invoke(url)
+                        }
+                    }
+                } catch (_: Exception) {}
+            }
+
             override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) {
                 _state.value = ConnectionState.ERROR
                 scheduleReconnect()

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

@@ -108,7 +108,9 @@ private fun Btn(icon: ImageVector, key: String, onDir: (String) -> Unit) {
             .pointerInput(key) {
                 detectTapGestures(onPress = {
                     p = true; onDir(key)
-                    job = scope.launch { delay(350); while (true) { onDir(key); delay(100) } }
+                    // 500ms initial delay so a normal tap sends one key, not two
+                    // (a touch tap often exceeds 350ms → doubled nav sound).
+                    job = scope.launch { delay(500); while (true) { onDir(key); delay(100) } }
                     tryAwaitRelease(); p = false; job?.cancel()
                 })
             },

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

@@ -83,13 +83,16 @@ val ClassicPalette = NESPalette(
     inlayBg = Color(0xFF080808), inlayBorder = Color(0xFF999999),
 )
 
+// Glassmorphism-black (OS design): translucent dark surfaces so the backdrop
+// shows through the controller, subtle white-alpha borders, translucent-white
+// buttons. Accents come from each button's ring.
 val DarkPalette = NESPalette(
-    body = NES.DarkBody, face = NES.DarkFace, ridge = NES.DarkRidge,
-    label = NES.DarkLabel, labelMuted = NES.DarkLabelMuted,
-    dpad = Color(0xFF080808), dpadHi = Color(0xFF141418),
-    btn = NES.DarkButtonMain, btnPress = NES.DarkButtonMainPress,
-    capsule = Color(0xFF121216), capsulePress = Color(0xFF0A0A0C),
-    inlayBg = Color(0xFF060608), inlayBorder = Color(0xFF444448),
+    body = Color(0xA6121216), face = Color(0x8C0E0E12), ridge = Color(0x14FFFFFF),
+    label = Color(0xFF9A9A9A), labelMuted = Color(0xFF777777),
+    dpad = Color(0xFF202024), dpadHi = Color(0xFF33333A),
+    btn = Color(0x14FFFFFF), btnPress = Color(0x0AFFFFFF),
+    capsule = Color(0x12FFFFFF), capsulePress = Color(0x08FFFFFF),
+    inlayBg = Color(0x990A0A0A), inlayBorder = Color(0x1FFFFFFF),
 )
 
 fun paletteFor(style: ControllerStyle) = if (style == ControllerStyle.CLASSIC) ClassicPalette else DarkPalette
@@ -113,20 +116,10 @@ fun NESController(
     Box(
         modifier = modifier
             .fillMaxSize()
-            .background(Color(0xFF0C0C0C))  // Slightly lighter than black for shadow visibility
             .twoFingerHold(onMenu)
             .padding(horizontal = 40.dp, vertical = 24.dp),
         contentAlignment = Alignment.Center,
     ) {
-        // Shadow platform
-        Box(
-            modifier = Modifier
-                .fillMaxWidth(0.86f)
-                .aspectRatio(2.3f)
-                .padding(top = 6.dp)
-                .clip(RoundedCornerShape(18.dp))
-                .background(Color(0xFF000000)),
-        )
         // Controller body
         Box(
             Modifier
@@ -135,7 +128,7 @@ fun NESController(
                 .shadow(32.dp, RoundedCornerShape(16.dp), ambientColor = Color(0xFF000000), spotColor = Color(0xFF000000))
                 .clip(RoundedCornerShape(16.dp))
                 .background(
-                    Brush.verticalGradient(listOf(c.body, c.body.copy(alpha = 0.95f)))
+                    Brush.verticalGradient(listOf(c.body, c.body))
                 )
                 .border(1.dp, Color.White.copy(alpha = if (isClassic) 0.08f else 0.04f), RoundedCornerShape(16.dp)),
         ) {
@@ -193,13 +186,13 @@ fun NESController(
                         horizontalAlignment = Alignment.CenterHorizontally,
                         verticalArrangement = Arrangement.Center,
                     ) {
-                        // C on top (white)
-                        ColorBtn(Color(0xFF888888), Color(0xFFAAAAAA), 44.dp) { onKey("c") }
+                        // C on top
+                        GlassFaceBtn("C", Color(0xFFBBBBBB), 44.dp) { onKey("c") }
                         Spacer(Modifier.height(6.dp))
                         // B + A on bottom row
                         Row(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
-                            ColorBtn(Color(0xFF3B82F6), Color(0xFF60A5FA), 44.dp) { onKey("b") }
-                            ColorBtn(Color(0xFFEA580C), Color(0xFFFB923C), 44.dp) { onKey("a") }
+                            GlassFaceBtn("B", Color(0xFF60A5FA), 44.dp) { onKey("b") }
+                            GlassFaceBtn("A", Color(0xFFF7931A), 44.dp) { onKey("a") }
                         }
                     }
                 }
@@ -264,7 +257,9 @@ fun OnePointDPad(c: NESPalette, size: Dp, onDir: (String) -> Unit) {
                         }
                         activeDir = dir; onDir(dir)
                         job?.cancel()
-                        job = scope.launch { delay(300); while (true) { onDir(dir); delay(90) } }
+                        // 500ms initial delay so a normal tap sends one key, not
+                        // two (a touch tap often exceeds 300ms → doubled nav sound).
+                        job = scope.launch { delay(500); while (true) { onDir(dir); delay(90) } }
                         tryAwaitRelease()
                         job?.cancel(); activeDir = null
                     },
@@ -375,6 +370,28 @@ fun ColorBtn(color: Color, pressColor: Color, sz: Dp = 48.dp, onClick: () -> Uni
     }
 }
 
+/** Glass face button — dark translucent fill, colored ring + letter (OS style) */
+@Composable
+fun GlassFaceBtn(label: String, accent: Color, sz: Dp = 44.dp, onClick: () -> Unit) {
+    var p by remember { mutableStateOf(false) }
+    Box(
+        Modifier
+            .size(sz)
+            .clip(CircleShape)
+            .background(
+                Brush.verticalGradient(
+                    if (p) listOf(Color.White.copy(alpha = 0.05f), Color.White.copy(alpha = 0.02f))
+                    else listOf(Color.White.copy(alpha = 0.10f), Color.White.copy(alpha = 0.03f))
+                )
+            )
+            .border(1.5.dp, accent.copy(alpha = if (p) 0.95f else 0.55f), CircleShape)
+            .pointerInput(Unit) { detectTapGestures(onPress = { p = true; onClick(); tryAwaitRelease(); p = false }) },
+        contentAlignment = Alignment.Center,
+    ) {
+        Text(label, color = accent.copy(alpha = if (p) 1f else 0.85f), fontSize = 16.sp, fontWeight = FontWeight.Bold)
+    }
+}
+
 /** START/SELECT capsule */
 @Composable
 fun CapsuleBtn(label: String, c: NESPalette, w: Dp = 64.dp, h: Dp = 28.dp, onClick: () -> Unit) {

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

@@ -3,6 +3,8 @@ package com.archipelago.app.ui.components
 import androidx.compose.animation.AnimatedVisibility
 import androidx.compose.animation.fadeIn
 import androidx.compose.animation.fadeOut
+import androidx.compose.animation.scaleIn
+import androidx.compose.animation.scaleOut
 import androidx.compose.foundation.background
 import androidx.compose.foundation.border
 import androidx.compose.foundation.clickable
@@ -34,17 +36,35 @@ 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.text.TextStyle
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.input.ImeAction
 import androidx.compose.ui.text.input.KeyboardType
 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.data.ServerEntry
+import com.archipelago.app.ui.theme.BitcoinOrange
 import com.archipelago.app.ui.theme.ControllerStyle
-import com.archipelago.app.ui.theme.NES
+import com.archipelago.app.ui.theme.SurfaceDark
+import com.archipelago.app.ui.theme.TextMuted
+import com.archipelago.app.ui.theme.TextPrimary
 
-/** NES-styled modal menu — dark blue panel with white borders */
+// Glassmorphism palette (OS design): near-black surfaces, subtle white borders,
+// Bitcoin-orange accent.
+private val PanelBg = SurfaceDark                       // #0A0A0A
+private val PanelBorder = Color.White.copy(alpha = 0.12f)
+private val RowBg = Color.White.copy(alpha = 0.05f)
+private val RowBorder = Color.White.copy(alpha = 0.08f)
+private val FieldBg = Color.White.copy(alpha = 0.04f)
+
+private val PANEL_R = 20.dp
+private val ROW_R = 14.dp
+private val ROW_H = 54.dp
+private val FIELD_H = 58.dp
+
+/** Glassmorphism modal menu — #0A0A0A surface, subtle white borders. */
 @Composable
 fun NESMenu(
     visible: Boolean,
@@ -55,6 +75,7 @@ fun NESMenu(
     onDismiss: () -> Unit,
     onSelectServer: (ServerEntry) -> Unit,
     onAddServer: (ServerEntry) -> Unit,
+    onEditServer: (ServerEntry, ServerEntry) -> Unit,
     onRemoveServer: (ServerEntry) -> Unit,
     onToggleMode: () -> Unit,
     onToggleStyle: () -> Unit,
@@ -66,7 +87,9 @@ fun NESMenu(
                 .clickable(indication = null, interactionSource = remember { MutableInteractionSource() }) { onDismiss() },
             contentAlignment = Alignment.Center,
         ) {
-            MenuPanel(servers, activeServer, isGamepadMode, controllerStyle, onDismiss, onSelectServer, onAddServer, onRemoveServer, onToggleMode, onToggleStyle, onBackToWebView)
+            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)
+            }
         }
     }
 }
@@ -80,105 +103,160 @@ private fun MenuPanel(
     onDismiss: () -> Unit,
     onSelectServer: (ServerEntry) -> Unit,
     onAddServer: (ServerEntry) -> Unit,
+    onEditServer: (ServerEntry, ServerEntry) -> Unit,
     onRemoveServer: (ServerEntry) -> Unit,
     onToggleMode: () -> Unit,
     onToggleStyle: () -> Unit,
     onBackToWebView: (() -> Unit)?,
 ) {
     var showAdd by remember { mutableStateOf(false) }
+    // The saved server being edited, or null when adding a new one.
+    var editing by remember { mutableStateOf<ServerEntry?>(null) }
+    var nm by remember { mutableStateOf("") }
     var addr by remember { mutableStateOf("") }
     var pwd by remember { mutableStateOf("") }
 
+    fun resetForm() {
+        nm = ""; addr = ""; pwd = ""; showAdd = false; editing = null
+    }
+
+    fun startEdit(server: ServerEntry) {
+        editing = server
+        nm = server.name; addr = server.address; pwd = server.password
+        showAdd = false
+    }
+
+    fun submit() {
+        if (addr.isBlank()) return
+        val orig = editing
+        if (orig != null) {
+            // Preserve fields the compact form doesn't expose (scheme, port).
+            onEditServer(orig, orig.copy(address = addr, password = pwd, name = nm))
+        } else {
+            onAddServer(ServerEntry(addr, false, password = pwd, name = nm))
+        }
+        resetForm()
+    }
+
     Column(
         modifier = Modifier
-            .widthIn(max = 360.dp)
-            .clip(RoundedCornerShape(4.dp))
-            .background(NES.MenuPanel)
-            .border(3.dp, NES.MenuBorder, RoundedCornerShape(4.dp))
+            .widthIn(max = 420.dp)
+            .padding(horizontal = 20.dp)
+            .clip(RoundedCornerShape(PANEL_R))
+            .background(PanelBg)
+            .border(1.dp, PanelBorder, RoundedCornerShape(PANEL_R))
             .clickable(indication = null, interactionSource = remember { MutableInteractionSource() }) {}
-            .padding(16.dp),
-        verticalArrangement = Arrangement.spacedBy(6.dp),
+            .padding(22.dp),
+        verticalArrangement = Arrangement.spacedBy(10.dp),
     ) {
         // Title
-        Text("- MENU -", color = NES.MenuText, fontSize = 14.sp, fontWeight = FontWeight.Bold, letterSpacing = 4.sp,
-            modifier = Modifier.fillMaxWidth(), textAlign = androidx.compose.ui.text.style.TextAlign.Center)
-        Spacer(Modifier.height(4.dp))
+        Text(
+            "Menu",
+            color = TextPrimary,
+            fontSize = 18.sp,
+            fontWeight = FontWeight.SemiBold,
+            letterSpacing = 2.sp,
+            modifier = Modifier.fillMaxWidth(),
+            textAlign = TextAlign.Center,
+        )
+        Spacer(Modifier.height(2.dp))
 
         // Servers
         servers.forEach { server ->
             val active = server.serialize() == activeServer?.serialize()
             MenuItem(
-                label = (if (active) "\u25B6 " else "  ") + server.address,
+                label = server.displayName(),
                 selected = active,
                 onClick = { onSelectServer(server) },
+                onEdit = { startEdit(server) },
                 onRemove = { onRemoveServer(server) },
             )
         }
 
         if (servers.isEmpty()) {
-            Text("  NO SERVERS", color = NES.MenuMuted, fontSize = 11.sp, modifier = Modifier.padding(vertical = 4.dp))
+            Text("No servers", color = TextMuted, fontSize = 14.sp, modifier = Modifier.padding(vertical = 4.dp))
         }
 
-        // Add server
-        if (showAdd) {
+        // Add / edit server
+        if (showAdd || editing != null) {
             Column(
-                Modifier.fillMaxWidth().background(Color.Black.copy(alpha = 0.3f)).padding(8.dp),
-                verticalArrangement = Arrangement.spacedBy(6.dp),
+                Modifier
+                    .fillMaxWidth()
+                    .clip(RoundedCornerShape(ROW_R))
+                    .background(FieldBg)
+                    .border(1.dp, RowBorder, RoundedCornerShape(ROW_R))
+                    .padding(12.dp),
+                verticalArrangement = Arrangement.spacedBy(8.dp),
             ) {
-                OutlinedTextField(
-                    value = addr, onValueChange = { addr = it.trim() },
-                    placeholder = { Text("192.168.1.100", color = NES.MenuMuted, fontSize = 11.sp) },
-                    modifier = Modifier.fillMaxWidth().height(48.dp), singleLine = true,
-                    textStyle = androidx.compose.ui.text.TextStyle(color = NES.MenuText, fontSize = 12.sp),
-                    colors = nesFieldColors(),
-                    shape = RoundedCornerShape(2.dp),
+                Row(
+                    Modifier.fillMaxWidth(),
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.SpaceBetween,
+                ) {
+                    Text(
+                        if (editing != null) "Edit Server" else "Add Server",
+                        color = TextMuted,
+                        fontSize = 13.sp,
+                        letterSpacing = 1.sp,
+                        fontWeight = FontWeight.Medium,
+                    )
+                    Text(
+                        "Cancel",
+                        color = TextMuted,
+                        fontSize = 13.sp,
+                        modifier = Modifier.clickable { resetForm() }.padding(start = 8.dp),
+                    )
+                }
+                GlassField(
+                    value = nm, onValueChange = { nm = it },
+                    placeholder = "Name (optional)",
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Text, imeAction = ImeAction.Next),
                 )
-                Row(horizontalArrangement = Arrangement.spacedBy(6.dp), verticalAlignment = Alignment.CenterVertically) {
-                    OutlinedTextField(
+                GlassField(
+                    value = addr, onValueChange = { addr = it.trim() },
+                    placeholder = "192.168.1.100",
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Uri, imeAction = ImeAction.Next),
+                )
+                Row(horizontalArrangement = Arrangement.spacedBy(8.dp), verticalAlignment = Alignment.CenterVertically) {
+                    GlassField(
                         value = pwd, onValueChange = { pwd = it },
-                        placeholder = { Text("PASSWORD", color = NES.MenuMuted, fontSize = 11.sp) },
-                        modifier = Modifier.weight(1f).height(48.dp), singleLine = true,
+                        placeholder = "Password",
+                        modifier = Modifier.weight(1f),
                         visualTransformation = PasswordVisualTransformation(),
                         keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password, imeAction = ImeAction.Go),
-                        keyboardActions = KeyboardActions(onGo = {
-                            if (addr.isNotBlank()) { onAddServer(ServerEntry(addr, false, password = pwd)); addr = ""; pwd = ""; showAdd = false }
-                        }),
-                        textStyle = androidx.compose.ui.text.TextStyle(color = NES.MenuText, fontSize = 12.sp),
-                        colors = nesFieldColors(),
-                        shape = RoundedCornerShape(2.dp),
+                        keyboardActions = KeyboardActions(onGo = { submit() }),
                     )
                     Box(
-                        Modifier.size(48.dp).clip(RoundedCornerShape(2.dp)).background(NES.MenuSelected)
-                            .clickable {
-                                if (addr.isNotBlank()) { onAddServer(ServerEntry(addr, false, password = pwd)); addr = ""; pwd = ""; showAdd = false }
-                            },
+                        Modifier.size(FIELD_H).clip(RoundedCornerShape(12.dp)).background(BitcoinOrange.copy(alpha = 0.15f))
+                            .border(1.dp, BitcoinOrange.copy(alpha = 0.4f), RoundedCornerShape(12.dp))
+                            .clickable { submit() },
                         contentAlignment = Alignment.Center,
-                    ) { Text("OK", color = NES.MenuText, fontSize = 10.sp, fontWeight = FontWeight.Bold) }
+                    ) { Text("OK", color = BitcoinOrange, fontSize = 14.sp, fontWeight = FontWeight.Bold) }
                 }
             }
         } else {
-            MenuItem(label = "  ADD SERVER", onClick = { showAdd = true })
+            MenuItem(label = "Add Server", labelColor = BitcoinOrange, onClick = { showAdd = true })
         }
 
         Spacer(Modifier.height(2.dp))
-        Box(Modifier.fillMaxWidth().height(1.dp).background(NES.MenuBorder.copy(alpha = 0.3f)))
+        Box(Modifier.fillMaxWidth().height(1.dp).background(PanelBorder))
         Spacer(Modifier.height(2.dp))
 
         // Mode toggle
         MenuItem(
-            label = if (isGamepadMode) "  SWITCH TO KEYBOARD" else "  SWITCH TO GAMEPAD",
+            label = if (isGamepadMode) "Switch to Keyboard" else "Switch to Gamepad",
             onClick = onToggleMode,
         )
 
         // Style toggle
         MenuItem(
-            label = if (controllerStyle == ControllerStyle.CLASSIC) "  STYLE: CLASSIC" else "  STYLE: DARK",
+            label = if (controllerStyle == ControllerStyle.CLASSIC) "Style: Classic" else "Style: Dark",
             onClick = onToggleStyle,
         )
 
         // Back to dashboard
         if (onBackToWebView != null) {
-            MenuItem(label = "  BACK TO DASHBOARD", onClick = onBackToWebView)
+            MenuItem(label = "Back to Dashboard", onClick = onBackToWebView)
         }
     }
 }
@@ -187,32 +265,79 @@ private fun MenuPanel(
 private fun MenuItem(
     label: String,
     selected: Boolean = false,
+    labelColor: Color = TextPrimary,
     onClick: () -> Unit,
+    onEdit: (() -> Unit)? = null,
     onRemove: (() -> Unit)? = null,
 ) {
     Row(
         Modifier
             .fillMaxWidth()
-            .height(32.dp)
-            .background(if (selected) NES.MenuSelected.copy(alpha = 0.15f) else Color.Transparent)
+            .height(ROW_H)
+            .clip(RoundedCornerShape(ROW_R))
+            .background(if (selected) BitcoinOrange.copy(alpha = 0.12f) else RowBg)
+            .border(1.dp, if (selected) BitcoinOrange.copy(alpha = 0.4f) else RowBorder, RoundedCornerShape(ROW_R))
             .clickable { onClick() }
-            .padding(horizontal = 8.dp),
+            .padding(horizontal = 16.dp),
         verticalAlignment = Alignment.CenterVertically,
         horizontalArrangement = Arrangement.SpaceBetween,
     ) {
-        Text(label, color = if (selected) NES.MenuSelected else NES.MenuText, fontSize = 11.sp, fontWeight = FontWeight.Medium)
+        Text(
+            label,
+            color = if (selected) BitcoinOrange else labelColor,
+            fontSize = 16.sp,
+            fontWeight = FontWeight.Medium,
+            modifier = Modifier.weight(1f),
+        )
+        if (onEdit != null) {
+            Text(
+                "✎",
+                color = TextMuted,
+                fontSize = 16.sp,
+                modifier = Modifier.clickable { onEdit() }.padding(horizontal = 8.dp),
+            )
+        }
         if (onRemove != null) {
-            Text("\u2715", color = NES.MenuMuted, fontSize = 10.sp,
-                modifier = Modifier.clickable { onRemove() }.padding(horizontal = 8.dp))
+            Text(
+                "✕",
+                color = TextMuted,
+                fontSize = 16.sp,
+                modifier = Modifier.clickable { onRemove() }.padding(horizontal = 8.dp),
+            )
         }
     }
 }
 
+/** Glass text field with centered input text. */
 @Composable
-private fun nesFieldColors() = OutlinedTextFieldDefaults.colors(
-    focusedBorderColor = NES.MenuBorder,
-    unfocusedBorderColor = NES.MenuMuted,
-    cursorColor = NES.MenuText,
-    focusedTextColor = NES.MenuText,
-    unfocusedTextColor = NES.MenuText,
-)
+private fun GlassField(
+    value: String,
+    onValueChange: (String) -> Unit,
+    placeholder: String,
+    modifier: Modifier = Modifier,
+    visualTransformation: androidx.compose.ui.text.input.VisualTransformation = androidx.compose.ui.text.input.VisualTransformation.None,
+    keyboardOptions: KeyboardOptions = KeyboardOptions.Default,
+    keyboardActions: KeyboardActions = KeyboardActions.Default,
+) {
+    OutlinedTextField(
+        value = value,
+        onValueChange = onValueChange,
+        placeholder = {
+            Text(placeholder, color = TextMuted, fontSize = 15.sp, modifier = Modifier.fillMaxWidth(), textAlign = TextAlign.Center)
+        },
+        modifier = modifier.fillMaxWidth().height(FIELD_H),
+        singleLine = true,
+        visualTransformation = visualTransformation,
+        keyboardOptions = keyboardOptions,
+        keyboardActions = keyboardActions,
+        textStyle = TextStyle(color = TextPrimary, fontSize = 16.sp, textAlign = TextAlign.Center),
+        colors = OutlinedTextFieldDefaults.colors(
+            focusedBorderColor = Color.White.copy(alpha = 0.3f),
+            unfocusedBorderColor = Color.White.copy(alpha = 0.12f),
+            cursorColor = BitcoinOrange,
+            focusedTextColor = TextPrimary,
+            unfocusedTextColor = TextPrimary,
+        ),
+        shape = RoundedCornerShape(12.dp),
+    )
+}

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

@@ -50,7 +50,6 @@ fun NESPortraitController(
     Box(
         Modifier
             .fillMaxSize()
-            .background(Color(0xFF0C0C0C))
             .twoFingerHold(onMenu)
             .padding(horizontal = 40.dp, vertical = 24.dp),
         contentAlignment = Alignment.Center,
@@ -62,7 +61,7 @@ fun NESPortraitController(
                 .fillMaxSize()
                 .shadow(28.dp, RoundedCornerShape(20.dp), ambientColor = Color.Black, spotColor = Color.Black)
                 .clip(RoundedCornerShape(20.dp))
-                .background(Brush.verticalGradient(listOf(c.body, c.body.copy(alpha = 0.95f))))
+                .background(Brush.verticalGradient(listOf(c.body, c.body)))
                 .border(1.dp, Color.White.copy(alpha = if (isClassic) 0.08f else 0.04f), RoundedCornerShape(20.dp)),
         ) {
             // Top highlight
@@ -119,11 +118,11 @@ fun NESPortraitController(
                         Modifier.fillMaxWidth().padding(horizontal = 12.dp, vertical = 8.dp),
                         horizontalAlignment = Alignment.CenterHorizontally,
                     ) {
-                        ColorBtn(Color(0xFF888888), Color(0xFFAAAAAA), 46.dp) { onKey("c") }
+                        GlassFaceBtn("C", Color(0xFFBBBBBB), 46.dp) { onKey("c") }
                         Spacer(Modifier.height(6.dp))
                         Row(horizontalArrangement = Arrangement.spacedBy(14.dp)) {
-                            ColorBtn(Color(0xFF3B82F6), Color(0xFF60A5FA), 46.dp) { onKey("b") }
-                            ColorBtn(Color(0xFFEA580C), Color(0xFFFB923C), 46.dp) { onKey("a") }
+                            GlassFaceBtn("B", Color(0xFF60A5FA), 46.dp) { onKey("b") }
+                            GlassFaceBtn("A", Color(0xFFF7931A), 46.dp) { onKey("a") }
                         }
                     }
                 }

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

@@ -23,6 +23,7 @@ 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.material3.MaterialTheme
@@ -41,7 +42,7 @@ import androidx.compose.ui.geometry.Offset
 import androidx.compose.ui.geometry.Size
 import androidx.compose.ui.graphics.Brush
 import androidx.compose.ui.graphics.Color
-import androidx.compose.ui.graphics.ColorFilter
+import androidx.compose.ui.layout.ContentScale
 import androidx.compose.ui.res.painterResource
 import androidx.compose.ui.res.stringResource
 import androidx.compose.ui.text.style.TextAlign
@@ -67,26 +68,45 @@ fun IntroScreen(onContinue: () -> Unit) {
     Box(
         modifier = Modifier
             .fillMaxSize()
-            .background(SurfaceBlack)
-            .windowInsetsPadding(WindowInsets.safeDrawing),
-        contentAlignment = Alignment.Center,
+            .background(SurfaceBlack),
     ) {
+        // Reddish synthwave backdrop
+        Image(
+            painter = painterResource(id = R.drawable.bg_synthwave),
+            contentDescription = null,
+            modifier = Modifier.fillMaxSize(),
+            contentScale = ContentScale.Crop,
+        )
+        // Dark scrim so the title/buttons stay legible over the art
+        Box(
+            modifier = Modifier
+                .fillMaxSize()
+                .background(
+                    Brush.verticalGradient(
+                        colors = listOf(
+                            Color.Black.copy(alpha = 0.55f),
+                            Color.Black.copy(alpha = 0.35f),
+                            Color.Black.copy(alpha = 0.75f),
+                        ),
+                    )
+                ),
+        )
         Column(
             modifier = Modifier
+                .align(Alignment.Center)
                 .fillMaxWidth()
+                .windowInsetsPadding(WindowInsets.safeDrawing)
                 .padding(horizontal = 32.dp),
             horizontalAlignment = Alignment.CenterHorizontally,
             verticalArrangement = Arrangement.Center,
         ) {
-            // Wide pixel-art logo
+            // Circular badge logo
             Image(
-                painter = painterResource(id = R.drawable.ic_logo_wide),
+                painter = painterResource(id = R.drawable.ic_logo),
                 contentDescription = "Archipelago",
                 modifier = Modifier
-                    .fillMaxWidth()
-                    .padding(horizontal = 8.dp)
+                    .size(160.dp)
                     .alpha(logoAlpha.value),
-                colorFilter = ColorFilter.tint(Color.White),
             )
 
             Spacer(modifier = Modifier.height(48.dp))
@@ -102,7 +122,7 @@ fun IntroScreen(onContinue: () -> Unit) {
                     Text(
                         text = stringResource(R.string.welcome_title),
                         style = MaterialTheme.typography.headlineLarge,
-                        color = TextPrimary,
+                        color = Color(0xFFFAFAFA),
                         textAlign = TextAlign.Center,
                     )
 
@@ -111,7 +131,7 @@ fun IntroScreen(onContinue: () -> Unit) {
                     Text(
                         text = stringResource(R.string.welcome_subtitle),
                         style = MaterialTheme.typography.bodyLarge,
-                        color = TextMuted,
+                        color = Color(0xFFFAFAFA),
                         textAlign = TextAlign.Center,
                         lineHeight = 26.sp,
                     )

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

@@ -2,6 +2,7 @@ package com.archipelago.app.ui.screens
 
 import android.content.res.Configuration
 import androidx.activity.compose.BackHandler
+import androidx.compose.foundation.Image
 import androidx.compose.foundation.background
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
@@ -24,13 +25,17 @@ import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Brush
 import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.layout.ContentScale
 import androidx.compose.ui.platform.LocalConfiguration
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.platform.LocalLifecycleOwner
 import androidx.lifecycle.Lifecycle
 import androidx.lifecycle.LifecycleEventObserver
+import androidx.compose.ui.res.painterResource
 import androidx.compose.ui.unit.dp
+import com.archipelago.app.R
 import com.archipelago.app.data.ServerPreferences
 import com.archipelago.app.network.ConnectionState
 import com.archipelago.app.network.InputWebSocket
@@ -58,11 +63,26 @@ fun RemoteInputScreen(onBack: () -> Unit) {
 
     var isGamepadMode by remember { mutableStateOf(true) }
     var showModal by remember { mutableStateOf(false) }
-    var controllerStyle by remember { mutableStateOf(ControllerStyle.CLASSIC) }
+    var controllerStyle by remember { mutableStateOf(ControllerStyle.DARK) }
     var playerId by remember { mutableStateOf(0) }  // 0 = broadcast, 1 = P1, 2 = P2
 
     val ws = remember { InputWebSocket(scope) }
 
+    // When the kiosk forwards an "open in external browser" app, launch it in
+    // the phone's default browser.
+    DisposableEffect(ws) {
+        ws.onExternalOpen = { url ->
+            try {
+                val intent = android.content.Intent(
+                    android.content.Intent.ACTION_VIEW,
+                    android.net.Uri.parse(url),
+                ).apply { addFlags(android.content.Intent.FLAG_ACTIVITY_NEW_TASK) }
+                context.startActivity(intent)
+            } catch (_: Exception) {}
+        }
+        onDispose { ws.onExternalOpen = null }
+    }
+
     fun togglePlayer() {
         playerId = when (playerId) { 0 -> 1; 1 -> 2; else -> 0 }
         ws.playerId = playerId
@@ -98,9 +118,31 @@ fun RemoteInputScreen(onBack: () -> Unit) {
     Box(
         Modifier
             .fillMaxSize()
-            .background(Color(0xFF0C0C0C))
-            .windowInsetsPadding(WindowInsets.safeDrawing),
+            .background(Color(0xFF0C0C0C)),
     ) {
+        // Reddish synthwave backdrop behind the controller
+        Image(
+            painter = painterResource(id = R.drawable.bg_synthwave),
+            contentDescription = null,
+            modifier = Modifier.fillMaxSize(),
+            contentScale = ContentScale.Crop,
+        )
+        // Light scrim — the controller body provides its own contrast, so keep
+        // this subtle and let the backdrop show through around it.
+        Box(
+            modifier = Modifier
+                .fillMaxSize()
+                .background(
+                    Brush.verticalGradient(
+                        colors = listOf(
+                            Color.Black.copy(alpha = 0.4f),
+                            Color.Black.copy(alpha = 0.25f),
+                            Color.Black.copy(alpha = 0.45f),
+                        ),
+                    )
+                ),
+        )
+        Box(Modifier.fillMaxSize().windowInsetsPadding(WindowInsets.safeDrawing)) {
         when {
             isGamepadMode && isLandscape -> NESController(
                 style = controllerStyle,
@@ -159,6 +201,7 @@ fun RemoteInputScreen(onBack: () -> Unit) {
                     }
                 ),
         )
+        }
 
         NESMenu(
             visible = showModal,
@@ -173,7 +216,31 @@ fun RemoteInputScreen(onBack: () -> Unit) {
             onAddServer = { server ->
                 scope.launch { prefs.addSavedServer(server); if (activeServer == null) prefs.setActiveServer(server) }
             },
-            onRemoveServer = { server -> scope.launch { prefs.removeSavedServer(server) } },
+            onEditServer = { original, updated ->
+                scope.launch {
+                    prefs.updateSavedServer(original, updated)
+                    // If the edited server is the live one, reconnect with the new
+                    // address/credentials so the change takes effect immediately.
+                    if (original.serialize() == activeServer?.serialize()) {
+                        ws.disconnect()
+                        prefs.setActiveServer(updated)
+                    }
+                }
+            },
+            onRemoveServer = { server ->
+                scope.launch {
+                    prefs.removeSavedServer(server)
+                    // Deleting the last server leaves nothing to control — drop the
+                    // active server and return to the Connect screen.
+                    val remaining = savedServers.count { it.serialize() != server.serialize() }
+                    if (remaining == 0) {
+                        ws.disconnect()
+                        prefs.clearActiveServer()
+                        showModal = false
+                        onBack()
+                    }
+                }
+            },
             onToggleMode = { isGamepadMode = !isGamepadMode; showModal = false },
             onToggleStyle = {
                 controllerStyle = if (controllerStyle == ControllerStyle.CLASSIC) ControllerStyle.DARK else ControllerStyle.CLASSIC

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

@@ -30,6 +30,7 @@ import androidx.compose.material.icons.filled.VisibilityOff
 import androidx.compose.foundation.verticalScroll
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.filled.Close
+import androidx.compose.material.icons.filled.Edit
 import androidx.compose.material.icons.filled.Lock
 import androidx.compose.material.icons.filled.LockOpen
 import androidx.compose.material3.CircularProgressIndicator
@@ -55,6 +56,7 @@ import androidx.compose.ui.draw.drawWithContent
 import androidx.compose.ui.graphics.Brush
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.graphics.ColorFilter
+import androidx.compose.ui.layout.ContentScale
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.platform.LocalSoftwareKeyboardController
 import androidx.compose.ui.res.painterResource
@@ -97,6 +99,7 @@ fun ServerConnectScreen(
     val scope = rememberCoroutineScope()
     val keyboard = LocalSoftwareKeyboardController.current
 
+    var name by remember { mutableStateOf("") }
     var address by remember { mutableStateOf("") }
     var port by remember { mutableStateOf("") }
     var password by remember { mutableStateOf("") }
@@ -104,9 +107,50 @@ fun ServerConnectScreen(
     var useHttps by remember { mutableStateOf(false) }
     var isConnecting by remember { mutableStateOf(false) }
     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) }
 
     val savedServers by prefs.savedServers.collectAsState(initial = emptyList())
 
+    fun clearForm() {
+        name = ""
+        address = ""
+        port = ""
+        password = ""
+        useHttps = false
+        passwordVisible = false
+        errorMessage = null
+    }
+
+    fun startEdit(server: ServerEntry) {
+        editingServer = server
+        name = server.name
+        address = server.address
+        port = server.port
+        password = server.password
+        useHttps = server.useHttps
+        passwordVisible = false
+        errorMessage = null
+    }
+
+    fun cancelEdit() {
+        editingServer = null
+        clearForm()
+    }
+
+    fun saveEdit() {
+        val original = editingServer ?: return
+        if (address.isBlank()) {
+            errorMessage = "Enter a server address"
+            return
+        }
+        val updated = ServerEntry(address, useHttps, port, password, name)
+        scope.launch {
+            prefs.updateSavedServer(original, updated)
+            cancelEdit()
+        }
+    }
+
     fun connect(server: ServerEntry) {
         if (isConnecting) return
         if (server.address.isBlank()) {
@@ -132,12 +176,33 @@ fun ServerConnectScreen(
     Box(
         modifier = Modifier
             .fillMaxSize()
-            .background(SurfaceBlack)
-            .windowInsetsPadding(WindowInsets.safeDrawing),
+            .background(SurfaceBlack),
     ) {
+        // Reddish synthwave backdrop
+        Image(
+            painter = painterResource(id = R.drawable.bg_synthwave),
+            contentDescription = null,
+            modifier = Modifier.fillMaxSize(),
+            contentScale = ContentScale.Crop,
+        )
+        // Dark scrim so the form stays legible over the art
+        Box(
+            modifier = Modifier
+                .fillMaxSize()
+                .background(
+                    Brush.verticalGradient(
+                        colors = listOf(
+                            Color.Black.copy(alpha = 0.6f),
+                            Color.Black.copy(alpha = 0.45f),
+                            Color.Black.copy(alpha = 0.8f),
+                        ),
+                    )
+                ),
+        )
         Column(
             modifier = Modifier
                 .fillMaxSize()
+                .windowInsetsPadding(WindowInsets.safeDrawing)
                 .verticalScroll(state = rememberScrollState())
                 .drawWithContent { drawContent() }
                 .padding(horizontal = 24.dp)
@@ -145,20 +210,17 @@ fun ServerConnectScreen(
             horizontalAlignment = Alignment.CenterHorizontally,
             verticalArrangement = Arrangement.spacedBy(16.dp),
         ) {
-            // Wide logo
+            // Circular badge logo
             Image(
-                painter = painterResource(id = R.drawable.ic_logo_wide),
+                painter = painterResource(id = R.drawable.ic_logo),
                 contentDescription = "Archipelago",
-                modifier = Modifier
-                    .fillMaxWidth()
-                    .padding(horizontal = 16.dp),
-                colorFilter = ColorFilter.tint(Color.White),
+                modifier = Modifier.size(96.dp),
             )
 
             Spacer(modifier = Modifier.height(4.dp))
 
             Text(
-                text = "Connect to Server",
+                text = if (editingServer != null) stringResource(R.string.edit_server_title) else "Connect to Server",
                 style = MaterialTheme.typography.headlineMedium,
                 color = TextPrimary,
                 textAlign = TextAlign.Center,
@@ -178,6 +240,7 @@ fun ServerConnectScreen(
                 modifier = Modifier
                     .fillMaxWidth()
                     .clip(RoundedCornerShape(16.dp))
+                    .background(Color.Black.copy(alpha = 0.6f))
                     .background(
                         Brush.verticalGradient(
                             colors = listOf(
@@ -190,6 +253,34 @@ fun ServerConnectScreen(
                     .padding(20.dp),
             ) {
                 Column {
+                    OutlinedTextField(
+                        value = name,
+                        onValueChange = {
+                            name = it
+                            errorMessage = null
+                        },
+                        label = { Text(stringResource(R.string.server_name_label)) },
+                        placeholder = { Text(stringResource(R.string.server_name_placeholder)) },
+                        modifier = Modifier.fillMaxWidth(),
+                        singleLine = true,
+                        keyboardOptions = KeyboardOptions(
+                            keyboardType = KeyboardType.Text,
+                            imeAction = ImeAction.Next,
+                        ),
+                        colors = OutlinedTextFieldDefaults.colors(
+                            focusedBorderColor = Color.White.copy(alpha = 0.3f),
+                            unfocusedBorderColor = Color.White.copy(alpha = 0.12f),
+                            cursorColor = Color.White,
+                            focusedLabelColor = Color.White.copy(alpha = 0.7f),
+                            unfocusedLabelColor = TextMuted,
+                            focusedTextColor = TextPrimary,
+                            unfocusedTextColor = TextPrimary,
+                        ),
+                        shape = RoundedCornerShape(12.dp),
+                    )
+
+                    Spacer(modifier = Modifier.height(12.dp))
+
                     OutlinedTextField(
                         value = address,
                         onValueChange = {
@@ -275,7 +366,11 @@ fun ServerConnectScreen(
                             keyboardActions = KeyboardActions(
                                 onGo = {
                                     keyboard?.hide()
-                                    connect(ServerEntry(address, useHttps, port, password))
+                                    if (editingServer != null) {
+                                        saveEdit()
+                                    } else {
+                                        connect(ServerEntry(address, useHttps, port, password, name))
+                                    }
                                 },
                             ),
                             colors = OutlinedTextFieldDefaults.colors(
@@ -340,15 +435,40 @@ fun ServerConnectScreen(
                 }
             }
 
-            // 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))
-                },
-                modifier = Modifier.fillMaxWidth().height(56.dp),
-            )
+            if (editingServer != null) {
+                // Save / Cancel while editing an existing saved server
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalArrangement = Arrangement.spacedBy(12.dp),
+                ) {
+                    GlassButton(
+                        text = stringResource(R.string.cancel),
+                        onClick = {
+                            keyboard?.hide()
+                            cancelEdit()
+                        },
+                        modifier = Modifier.weight(1f).height(56.dp),
+                    )
+                    GlassButton(
+                        text = stringResource(R.string.save_changes),
+                        onClick = {
+                            keyboard?.hide()
+                            saveEdit()
+                        },
+                        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),
+                )
+            }
 
             if (isConnecting) {
                 CircularProgressIndicator(
@@ -358,8 +478,8 @@ fun ServerConnectScreen(
                 )
             }
 
-            // Saved servers
-            if (savedServers.isNotEmpty()) {
+            // Saved servers (hidden while editing one to keep focus on the form)
+            if (editingServer == null && savedServers.isNotEmpty()) {
                 Spacer(modifier = Modifier.height(8.dp))
                 Text(
                     text = stringResource(R.string.saved_servers),
@@ -373,6 +493,7 @@ fun ServerConnectScreen(
                     SavedServerItem(
                         server = server,
                         onConnect = { connect(it) },
+                        onEdit = { startEdit(it) },
                         onRemove = { scope.launch { prefs.removeSavedServer(it) } },
                     )
                 }
@@ -385,12 +506,14 @@ fun ServerConnectScreen(
 private fun SavedServerItem(
     server: ServerEntry,
     onConnect: (ServerEntry) -> Unit,
+    onEdit: (ServerEntry) -> Unit,
     onRemove: (ServerEntry) -> Unit,
 ) {
     Row(
         modifier = Modifier
             .fillMaxWidth()
             .clip(RoundedCornerShape(12.dp))
+            .background(Color.Black.copy(alpha = 0.6f))
             .background(
                 Brush.verticalGradient(
                     colors = listOf(
@@ -414,12 +537,21 @@ private fun SavedServerItem(
             )
             Spacer(modifier = Modifier.width(12.dp))
             Column {
-                Text(text = server.address, style = MaterialTheme.typography.bodyMedium, color = TextPrimary, maxLines = 1, overflow = TextOverflow.Ellipsis)
-                if (server.port.isNotBlank()) {
-                    Text(text = "Port ${server.port}", style = MaterialTheme.typography.labelMedium, color = TextMuted)
+                Text(text = server.displayName(), style = MaterialTheme.typography.bodyMedium, color = TextPrimary, maxLines = 1, overflow = TextOverflow.Ellipsis)
+                val secondary = buildString {
+                    if (server.name.isNotBlank()) append(server.address)
+                    if (server.port.isNotBlank()) {
+                        if (isNotEmpty()) append(":${server.port}") else append("Port ${server.port}")
+                    }
+                }
+                if (secondary.isNotBlank()) {
+                    Text(text = secondary, style = MaterialTheme.typography.labelMedium, color = TextMuted, maxLines = 1, overflow = TextOverflow.Ellipsis)
                 }
             }
         }
+        IconButton(onClick = { onEdit(server) }) {
+            Icon(imageVector = Icons.Default.Edit, contentDescription = stringResource(R.string.edit_server), modifier = Modifier.size(18.dp), tint = TextMuted)
+        }
         IconButton(onClick = { onRemove(server) }) {
             Icon(imageVector = Icons.Default.Close, contentDescription = stringResource(R.string.remove_server), modifier = Modifier.size(18.dp), tint = TextMuted)
         }

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

@@ -2,6 +2,7 @@ package com.archipelago.app.ui.screens
 
 import android.annotation.SuppressLint
 import android.graphics.Bitmap
+import android.graphics.BitmapFactory
 import android.view.ViewGroup
 import android.webkit.CookieManager
 import android.webkit.WebChromeClient
@@ -14,10 +15,12 @@ import androidx.activity.compose.BackHandler
 import androidx.compose.animation.AnimatedVisibility
 import androidx.compose.animation.fadeIn
 import androidx.compose.animation.fadeOut
+import androidx.compose.foundation.Image
 import androidx.compose.foundation.background
 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
@@ -26,14 +29,24 @@ 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.width
 import androidx.compose.foundation.layout.windowInsetsPadding
+import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ArrowBack
+import androidx.compose.material.icons.automirrored.filled.ArrowForward
+import androidx.compose.material.icons.filled.Close
 import androidx.compose.material.icons.filled.CloudOff
+import androidx.compose.material.icons.filled.OpenInBrowser
+import androidx.compose.material.icons.filled.Refresh
+import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
 import androidx.compose.material3.LinearProgressIndicator
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableIntStateOf
 import androidx.compose.runtime.mutableStateOf
@@ -41,8 +54,12 @@ import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.asImageBitmap
+import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.res.stringResource
 import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.viewinterop.AndroidView
 import com.archipelago.app.R
@@ -50,8 +67,70 @@ import com.archipelago.app.ui.theme.BitcoinOrange
 import com.archipelago.app.ui.theme.SurfaceBlack
 import com.archipelago.app.ui.theme.TextMuted
 import com.archipelago.app.ui.theme.TextPrimary
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
 
+/** Open a URL in the phone's default browser (genuinely external links). */
+private fun openExternalUrl(context: android.content.Context, url: String) {
+    try {
+        val intent = android.content.Intent(
+            android.content.Intent.ACTION_VIEW,
+            android.net.Uri.parse(url),
+        ).apply {
+            // Required when launching from a non-Activity/binder thread
+            // (the JS bridge below can run off the UI thread).
+            addFlags(android.content.Intent.FLAG_ACTIVITY_NEW_TASK)
+        }
+        context.startActivity(intent)
+    } catch (_: Exception) {}
+}
+
+/** True when [url] points at the same host as the connected Archipelago node
+ *  (ignoring port). Such URLs are node apps — e.g. one that can't be iframed —
+ *  and should stay inside the app rather than bouncing out to the browser. */
+private fun isSameHost(url: String, base: String): Boolean {
+    return try {
+        val a = android.net.Uri.parse(url).host ?: return false
+        val b = android.net.Uri.parse(base).host ?: return false
+        a.equals(b, ignoreCase = true)
+    } catch (_: Exception) {
+        false
+    }
+}
+
+/** Apply the WebView settings shared by the kiosk view and the in-app browser.
+ *  These are tuned for SPA performance and parity with the mobile browser;
+ *  none of them alter how a page renders visually. */
 @SuppressLint("SetJavaScriptEnabled")
+private fun WebView.applyArchipelagoSettings() {
+    // Pre-rasterize just outside the viewport so flinging the kiosk/app doesn't
+    // show blank checkerboarding — the single biggest scroll-smoothness win and
+    // a major part of the "feels slower than the browser" gap. (API 23+)
+    settings.setOffscreenPreRaster(true)
+
+    settings.apply {
+        javaScriptEnabled = true
+        domStorageEnabled = true
+        databaseEnabled = true
+        mediaPlaybackRequiresUserGesture = false
+        mixedContentMode = WebSettings.MIXED_CONTENT_COMPATIBILITY_MODE
+        useWideViewPort = true
+        loadWithOverviewMode = true
+        setSupportZoom(false)
+        builtInZoomControls = false
+        cacheMode = WebSettings.LOAD_DEFAULT
+        allowContentAccess = true
+        allowFileAccess = false
+    }
+
+    // chrome://inspect profiling on debuggable builds only — lets us measure the
+    // real in-page bottleneck rather than guess. No effect on release builds.
+    val debuggable = 0 != (context.applicationInfo.flags and
+        android.content.pm.ApplicationInfo.FLAG_DEBUGGABLE)
+    if (debuggable) WebView.setWebContentsDebuggingEnabled(true)
+}
+
+@SuppressLint("SetJavaScriptEnabled", "ClickableViewAccessibility")
 @Composable
 fun WebViewScreen(
     serverUrl: String,
@@ -63,7 +142,12 @@ fun WebViewScreen(
     var hasError by remember { mutableStateOf(false) }
     var webView by remember { mutableStateOf<WebView?>(null) }
 
-    BackHandler(enabled = webView?.canGoBack() == true) {
+    // A node app that refused iframing, opened in a local WebView overlay.
+    // null = no overlay. The kiosk WebView underneath stays alive (and warm)
+    // while this is shown, so closing it returns instantly with no reload.
+    var inAppUrl by remember { mutableStateOf<String?>(null) }
+
+    BackHandler(enabled = inAppUrl == null && webView?.canGoBack() == true) {
         webView?.goBack()
     }
 
@@ -132,16 +216,6 @@ fun WebViewScreen(
             AndroidView(
                 modifier = Modifier.fillMaxSize(),
                 factory = { context ->
-                    fun openExternalUrl(url: String) {
-                        try {
-                            val intent = android.content.Intent(
-                                android.content.Intent.ACTION_VIEW,
-                                android.net.Uri.parse(url),
-                            )
-                            context.startActivity(intent)
-                        } catch (_: Exception) {}
-                    }
-
                     WebView(context).apply {
                         layoutParams = ViewGroup.LayoutParams(
                             ViewGroup.LayoutParams.MATCH_PARENT,
@@ -155,22 +229,49 @@ fun WebViewScreen(
                         cookieManager.setAcceptCookie(true)
                         cookieManager.setAcceptThirdPartyCookies(this, true)
 
+                        applyArchipelagoSettings()
                         settings.apply {
-                            javaScriptEnabled = true
-                            domStorageEnabled = true
-                            databaseEnabled = true
-                            mediaPlaybackRequiresUserGesture = false
-                            mixedContentMode = WebSettings.MIXED_CONTENT_COMPATIBILITY_MODE
-                            useWideViewPort = true
-                            loadWithOverviewMode = true
-                            setSupportZoom(false)
-                            builtInZoomControls = false
-                            cacheMode = WebSettings.LOAD_DEFAULT
-                            allowContentAccess = true
-                            allowFileAccess = false
                             setSupportMultipleWindows(true)  // enables onCreateWindow for window.open
+                            // Let JS open windows without a synchronous user-gesture
+                            // chain; without this, window.open() from a Vue click
+                            // handler silently no-ops and "Open in new tab" dies.
+                            javaScriptCanOpenWindowsAutomatically = true
                         }
 
+                        val webViewRef = this
+
+                        // Decide where an outbound URL goes:
+                        //  - same host as the node  → in-app WebView overlay
+                        //    (this is the "open in browser" target for apps the
+                        //    kiosk couldn't iframe — keep the user inside the app)
+                        //  - different host         → the phone's real browser
+                        fun routeOutbound(url: String) {
+                            if (isSameHost(url, serverUrl)) {
+                                inAppUrl = url
+                            } else {
+                                openExternalUrl(context, url)
+                            }
+                        }
+
+                        // JS bridge. The web UI calls:
+                        //   window.ArchipelagoNative.openExternal(url) — host-routed
+                        //   window.ArchipelagoNative.openInApp(url)    — force in-app
+                        // Falls back to window.open in a plain mobile browser.
+                        addJavascriptInterface(
+                            object {
+                                @android.webkit.JavascriptInterface
+                                fun openExternal(url: String) {
+                                    webViewRef.post { routeOutbound(url) }
+                                }
+
+                                @android.webkit.JavascriptInterface
+                                fun openInApp(url: String) {
+                                    webViewRef.post { inAppUrl = url }
+                                }
+                            },
+                            "ArchipelagoNative",
+                        )
+
                         webViewClient = object : WebViewClient() {
                             override fun onPageStarted(view: WebView?, url: String?, favicon: Bitmap?) {
                                 isLoading = true
@@ -222,15 +323,35 @@ fun WebViewScreen(
                                 }
                             }
 
+                            // Node apps (e.g. NetBird) terminate TLS with a
+                            // self-signed cert — the dashboard needs a secure
+                            // context for OIDC/window.crypto.subtle (#15). The
+                            // WebView default is to CANCEL untrusted certs, so
+                            // those apps render blank. The user explicitly trusts
+                            // their own node, so proceed for same-host certs only;
+                            // reject anything else (don't blanket-trust the web).
+                            override fun onReceivedSslError(
+                                view: WebView?,
+                                handler: android.webkit.SslErrorHandler?,
+                                error: android.net.http.SslError?,
+                            ) {
+                                val u = error?.url
+                                if (u != null && isSameHost(u, serverUrl)) {
+                                    handler?.proceed()
+                                } else {
+                                    handler?.cancel()
+                                }
+                            }
+
                             override fun shouldOverrideUrlLoading(
                                 view: WebView?,
                                 request: WebResourceRequest?,
                             ): Boolean {
                                 val url = request?.url?.toString() ?: return false
-                                // Keep navigation within the Archipelago server
+                                // Keep kiosk navigation (same origin incl. port) in place
                                 if (url.startsWith(serverUrl)) return false
-                                // Open external URLs in the system browser
-                                openExternalUrl(url)
+                                // Same node (other port) → in-app; external → browser
+                                routeOutbound(url)
                                 return true
                             }
                         }
@@ -240,7 +361,9 @@ fun WebViewScreen(
                                 loadProgress = newProgress
                             }
 
-                            // Handle window.open() — open in system browser
+                            // window.open() — e.g. the kiosk's "Open in new tab"
+                            // for an app that can't be iframed. Capture the target
+                            // URL via a throwaway WebView and route it ourselves.
                             override fun onCreateWindow(
                                 view: WebView?,
                                 isDialog: Boolean,
@@ -258,12 +381,12 @@ fun WebViewScreen(
                                             request: WebResourceRequest?,
                                         ): Boolean {
                                             val url = request?.url?.toString() ?: return true
-                                            openExternalUrl(url)
+                                            routeOutbound(url)
                                             return true
                                         }
 
                                         override fun onPageStarted(view: WebView?, url: String?, favicon: Bitmap?) {
-                                            if (url != null) openExternalUrl(url)
+                                            if (url != null) routeOutbound(url)
                                             view?.stopLoading()
                                         }
                                     }
@@ -325,6 +448,255 @@ fun WebViewScreen(
                 )
             }
 
+            // In-app browser overlay for non-iframeable node apps. Rendered last
+            // so it sits above the kiosk WebView, which stays alive underneath.
+            inAppUrl?.let { target ->
+                InAppBrowser(
+                    url = target,
+                    serverUrl = serverUrl,
+                    onClose = { inAppUrl = null },
+                )
+            }
+        }
+    }
+}
+
+/** Best-effort fetch of the origin's /favicon.ico, so the launched app's icon
+ *  can be shown on the loading screen before the WebView reports onReceivedIcon
+ *  (which only fires once the page's <head> has parsed). Blocking — call on IO. */
+private fun fetchFavicon(pageUrl: String): Bitmap? {
+    return try {
+        val u = android.net.Uri.parse(pageUrl)
+        val scheme = u.scheme ?: return null
+        val host = u.host ?: return null
+        val portPart = if (u.port > 0) ":${u.port}" else ""
+        val conn = (java.net.URL("$scheme://$host$portPart/favicon.ico").openConnection()
+            as java.net.HttpURLConnection).apply {
+            connectTimeout = 4000
+            readTimeout = 4000
+            instanceFollowRedirects = true
+        }
+        conn.inputStream.use { BitmapFactory.decodeStream(it) }
+    } catch (_: Exception) {
+        null
+    }
+}
+
+/**
+ * Lightweight in-app browser used when the kiosk hands off an app that can't be
+ * shown in an iframe. Loads the app in a local WebView with a centered loading
+ * screen (app favicon + progress bar) and a BOTTOM control bar mirroring the
+ * web mobile-iframe footer (back / forward / reload / open-in-browser / close).
+ * Same-host navigation stays here; any genuinely external link escapes to the
+ * phone's browser.
+ */
+@SuppressLint("SetJavaScriptEnabled")
+@Composable
+private fun InAppBrowser(
+    url: String,
+    serverUrl: String,
+    onClose: () -> Unit,
+) {
+    val context = LocalContext.current
+    var browser by remember { mutableStateOf<WebView?>(null) }
+    var title by remember { mutableStateOf(android.net.Uri.parse(url).host ?: url) }
+    var favicon by remember { mutableStateOf<Bitmap?>(null) }
+    var progress by remember { mutableIntStateOf(0) }
+    var loading by remember { mutableStateOf(true) }
+    var canGoBack by remember { mutableStateOf(false) }
+    var canGoForward by remember { mutableStateOf(false) }
+
+    // Seed the loading-screen icon immediately from a best-effort favicon
+    // pre-fetch (main's app-icon work), then onReceivedIcon upgrades it — so the
+    // loader shows an icon right away instead of staying blank until the page
+    // parses its <head> (which is what made the loader look stuck).
+    LaunchedEffect(url) {
+        val fetched = withContext(Dispatchers.IO) { fetchFavicon(url) }
+        if (fetched != null && favicon == null) favicon = fetched
+    }
+
+    // Back: walk the in-app history first, then close the overlay.
+    BackHandler {
+        val b = browser
+        if (b != null && b.canGoBack()) b.goBack() else onClose()
+    }
+
+    Column(
+        modifier = Modifier
+            .fillMaxSize()
+            .background(SurfaceBlack)
+            .windowInsetsPadding(WindowInsets.safeDrawing),
+    ) {
+        // WebView + loading overlay fill the area above the bottom control bar.
+        Box(modifier = Modifier.weight(1f).fillMaxWidth()) {
+            AndroidView(
+                modifier = Modifier.fillMaxSize(),
+                factory = { ctx ->
+                    WebView(ctx).apply {
+                        layoutParams = ViewGroup.LayoutParams(
+                            ViewGroup.LayoutParams.MATCH_PARENT,
+                            ViewGroup.LayoutParams.MATCH_PARENT,
+                        )
+                        isVerticalScrollBarEnabled = false
+                        isHorizontalScrollBarEnabled = false
+
+                        CookieManager.getInstance().setAcceptThirdPartyCookies(this, true)
+                        applyArchipelagoSettings()
+
+                        webChromeClient = object : WebChromeClient() {
+                            override fun onProgressChanged(view: WebView?, newProgress: Int) {
+                                progress = newProgress
+                            }
+
+                            override fun onReceivedTitle(view: WebView?, t: String?) {
+                                if (!t.isNullOrBlank()) title = t
+                            }
+
+                            override fun onReceivedIcon(view: WebView?, icon: Bitmap?) {
+                                if (icon != null) favicon = icon
+                            }
+                        }
+
+                        webViewClient = object : WebViewClient() {
+                            override fun onPageStarted(view: WebView?, u: String?, favicon: Bitmap?) {
+                                loading = true
+                            }
+
+                            override fun onPageFinished(view: WebView?, u: String?) {
+                                loading = false
+                                canGoBack = view?.canGoBack() == true
+                                canGoForward = view?.canGoForward() == true
+                            }
+
+                            override fun doUpdateVisitedHistory(view: WebView?, u: String?, isReload: Boolean) {
+                                canGoBack = view?.canGoBack() == true
+                                canGoForward = view?.canGoForward() == true
+                            }
+
+                            // Self-signed TLS on the node's apps (e.g. NetBird on
+                            // :8087) would otherwise be cancelled by the WebView
+                            // and render blank. Proceed for the user's own node
+                            // (same host); reject any other untrusted cert.
+                            override fun onReceivedSslError(
+                                view: WebView?,
+                                handler: android.webkit.SslErrorHandler?,
+                                error: android.net.http.SslError?,
+                            ) {
+                                val u = error?.url
+                                if (u != null && isSameHost(u, serverUrl)) {
+                                    handler?.proceed()
+                                } else {
+                                    handler?.cancel()
+                                }
+                            }
+
+                            override fun shouldOverrideUrlLoading(
+                                view: WebView?,
+                                request: WebResourceRequest?,
+                            ): Boolean {
+                                val u = request?.url?.toString() ?: return false
+                                // Stay in the overlay for same-node navigation;
+                                // hand genuinely external links to the real browser.
+                                if (isSameHost(u, serverUrl)) return false
+                                openExternalUrl(ctx, u)
+                                return true
+                            }
+                        }
+
+                        browser = this
+                        loadUrl(url)
+                    }
+                },
+            )
+
+            // Centered loading screen — app favicon (or spinner) + title + bar.
+            if (loading) {
+                Column(
+                    modifier = Modifier
+                        .fillMaxSize()
+                        .background(SurfaceBlack),
+                    horizontalAlignment = Alignment.CenterHorizontally,
+                    verticalArrangement = Arrangement.Center,
+                ) {
+                    Box(
+                        modifier = Modifier.size(84.dp).clip(RoundedCornerShape(20.dp)),
+                        contentAlignment = Alignment.Center,
+                    ) {
+                        val fav = favicon
+                        if (fav != null) {
+                            Image(
+                                bitmap = fav.asImageBitmap(),
+                                contentDescription = title,
+                                modifier = Modifier.fillMaxSize(),
+                            )
+                        } else {
+                            CircularProgressIndicator(color = BitcoinOrange)
+                        }
+                    }
+                    Spacer(modifier = Modifier.height(18.dp))
+                    Text(
+                        text = title,
+                        style = MaterialTheme.typography.bodyLarge,
+                        color = TextPrimary,
+                        maxLines = 1,
+                        overflow = TextOverflow.Ellipsis,
+                    )
+                    Spacer(modifier = Modifier.height(16.dp))
+                    LinearProgressIndicator(
+                        progress = { progress / 100f },
+                        modifier = Modifier.width(220.dp),
+                        color = BitcoinOrange,
+                        trackColor = TextMuted.copy(alpha = 0.2f),
+                    )
+                }
+            }
+        }
+
+        // Bottom control bar — mirrors the web mobile-iframe footer.
+        Row(
+            modifier = Modifier
+                .fillMaxWidth()
+                .height(56.dp)
+                .background(SurfaceBlack)
+                .padding(horizontal = 8.dp),
+            horizontalArrangement = Arrangement.SpaceAround,
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            IconButton(onClick = { browser?.goBack() }, enabled = canGoBack) {
+                Icon(
+                    imageVector = Icons.AutoMirrored.Filled.ArrowBack,
+                    contentDescription = "Back",
+                    tint = if (canGoBack) TextPrimary else TextMuted.copy(alpha = 0.4f),
+                )
+            }
+            IconButton(onClick = { browser?.goForward() }, enabled = canGoForward) {
+                Icon(
+                    imageVector = Icons.AutoMirrored.Filled.ArrowForward,
+                    contentDescription = "Forward",
+                    tint = if (canGoForward) TextPrimary else TextMuted.copy(alpha = 0.4f),
+                )
+            }
+            IconButton(onClick = { browser?.reload() }) {
+                Icon(
+                    imageVector = Icons.Default.Refresh,
+                    contentDescription = "Reload",
+                    tint = TextPrimary,
+                )
+            }
+            IconButton(onClick = { openExternalUrl(context, browser?.url ?: url) }) {
+                Icon(
+                    imageVector = Icons.Default.OpenInBrowser,
+                    contentDescription = stringResource(R.string.open_in_browser),
+                    tint = TextPrimary,
+                )
+            }
+            IconButton(onClick = onClose) {
+                Icon(
+                    imageVector = Icons.Default.Close,
+                    contentDescription = stringResource(R.string.close),
+                    tint = TextPrimary,
+                )
+            }
         }
     }
 }

Android/app/src/main/res/drawable/ic_launcher_background.xml

@@ -1,10 +1,53 @@
 <?xml version="1.0" encoding="utf-8"?>
+<!-- Whole badge lives here (background renders to the mask edge with no
+     safe-zone cropping, unlike the foreground): dark fill + metallic ring pulled
+     inward to ~0.88 so the mask can't clip it + grid at ~0.58. Matches the
+     locally-rendered preview. Foreground is transparent. -->
 <vector xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:aapt="http://schemas.android.com/aapt"
     android:width="108dp"
     android:height="108dp"
-    android:viewportWidth="108"
-    android:viewportHeight="108">
+    android:viewportWidth="752"
+    android:viewportHeight="752">
+
     <path
-        android:fillColor="#030202"
-        android:pathData="M0,0h108v108H0z" />
+        android:fillColor="#0A0A0A"
+        android:pathData="M0,0h752v752H0z" />
+
+    <!-- Ring matching logo.svg's gradient (#000->#666). Scale 0.65 places it at
+         the home-screen's visible edge (calibrated from a device home screenshot;
+         launcher3 crops less than the Settings App-info view). -->
+    <group
+        android:pivotX="376"
+        android:pivotY="376"
+        android:scaleX="0.65"
+        android:scaleY="0.65">
+        <path
+            android:fillColor="#00000000"
+            android:strokeWidth="22.8834"
+            android:pathData="M11.441,375.669a364.227,364.227 0 1,0 728.454,0a364.227,364.227 0 1,0 -728.454,0z">
+            <aapt:attr name="android:strokeColor">
+                <gradient
+                    android:type="linear"
+                    android:startX="751.337"
+                    android:startY="751.338"
+                    android:endX="0"
+                    android:endY="0.000976562">
+                    <item android:offset="0" android:color="#FF000000" />
+                    <item android:offset="1" android:color="#FF666666" />
+                </gradient>
+            </aapt:attr>
+        </path>
+    </group>
+
+    <!-- White Archipelago grid -->
+    <group
+        android:pivotX="376"
+        android:pivotY="376"
+        android:scaleX="0.55"
+        android:scaleY="0.55">
+        <path
+            android:fillColor="#FFFFFF"
+            android:pathData="M253.805,278.37V222.28H309.853V278.37H253.805ZM315.797,278.37V222.28H372.694V278.37H315.797ZM378.639,278.37V222.28H435.536V278.37H378.639ZM441.481,278.37V222.28H497.529V278.37H441.481ZM441.481,341.259V284.319H497.529V341.259H441.481ZM503.473,341.259V284.319H560.37V341.259H503.473ZM190.963,404.148V347.208H247.86V404.148H190.963ZM253.805,404.148V347.208H309.853V404.148H253.805ZM315.797,404.148V347.208H372.694V404.148H315.797ZM378.639,404.148V347.208H435.536V404.148H378.639ZM441.481,404.148V347.208H497.529V404.148H441.481ZM503.473,404.148V347.208H560.37V404.148H503.473ZM190.963,466.187V410.097H247.86V466.187H190.963ZM253.805,466.187V410.097H309.853V466.187H253.805ZM441.481,466.187V410.097H497.529V466.187H441.481ZM503.473,466.187V410.097H560.37V466.187H503.473ZM253.805,529.076V472.136H309.853V529.076H253.805ZM315.797,529.076V472.136H372.694V529.076H315.797ZM378.639,529.076V472.136H435.536V529.076H378.639ZM441.481,529.076V472.136H497.529V529.076H441.481Z" />
+    </group>
 </vector>

Android/app/src/main/res/drawable/ic_launcher_foreground.xml

@@ -1,45 +1,12 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- Archipelago pixel-art "A" logo — scaled 90% and centered -->
+<!-- Transparent — the whole badge (ring + grid) is in the background layer so it
+     renders to the mask edge without safe-zone cropping. -->
 <vector xmlns:android="http://schemas.android.com/apk/res/android"
     android:width="108dp"
     android:height="108dp"
-    android:viewportWidth="1024"
-    android:viewportHeight="1024">
-
-    <group
-        android:pivotX="512"
-        android:pivotY="512"
-        android:scaleX="0.55"
-        android:scaleY="0.55">
-
-        <!-- Row 1: 4 blocks -->
-        <path android:fillColor="#FFFFFF" android:pathData="M357.614,318h71.007v70.936h-71.007z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M436.152,318h72.082v70.936h-72.082z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M515.766,318h72.082v70.936h-72.082z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M595.379,318h71.007v70.936h-71.007z" />
-
-        <!-- Row 2: 2 blocks (right side) -->
-        <path android:fillColor="#FFFFFF" android:pathData="M595.379,396.46h71.007v72.011h-71.007z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M673.917,396.46h72.083v72.011h-72.083z" />
-
-        <!-- Row 3: 6 blocks (full width) -->
-        <path android:fillColor="#FFFFFF" android:pathData="M278,475.994h72.083v72.012h-72.083z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M357.614,475.994h71.007v72.012h-71.007z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M436.152,475.994h72.082v72.012h-72.082z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M515.766,475.994h72.082v72.012h-72.082z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M595.379,475.994h71.007v72.012h-71.007z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M673.917,475.994h72.083v72.012h-72.083z" />
-
-        <!-- Row 4: 4 blocks (sides only — the "A" gap) -->
-        <path android:fillColor="#FFFFFF" android:pathData="M278,555.529h72.083v70.936h-72.083z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M357.614,555.529h71.007v70.936h-71.007z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M595.379,555.529h71.007v70.936h-71.007z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M673.917,555.529h72.083v70.936h-72.083z" />
-
-        <!-- Row 5: 4 blocks (bottom) -->
-        <path android:fillColor="#FFFFFF" android:pathData="M357.614,633.989h71.007v72.011h-71.007z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M436.152,633.989h72.082v72.011h-72.082z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M515.766,633.989h72.082v72.011h-72.082z" />
-        <path android:fillColor="#FFFFFF" android:pathData="M595.379,633.989h71.007v72.011h-71.007z" />
-    </group>
+    android:viewportWidth="108"
+    android:viewportHeight="108">
+    <path
+        android:fillColor="#00000000"
+        android:pathData="M0,0h108v108H0z" />
 </vector>

Android/app/src/main/res/drawable/ic_logo.xml

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Archipelago circular badge logo (from logo.svg):
+     dark circle with a black→grey gradient ring + white pixel-grid mark. -->
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:aapt="http://schemas.android.com/aapt"
+    android:width="120dp"
+    android:height="120dp"
+    android:viewportWidth="752"
+    android:viewportHeight="752">
+
+    <!-- Ringed circle (circle converted to a path; stroke carries the gradient) -->
+    <path
+        android:fillColor="#0A0A0A"
+        android:strokeWidth="22.8834"
+        android:pathData="M11.441,375.669a364.227,364.227 0 1,0 728.454,0a364.227,364.227 0 1,0 -728.454,0z">
+        <aapt:attr name="android:strokeColor">
+            <gradient
+                android:type="linear"
+                android:startX="751.337"
+                android:startY="751.338"
+                android:endX="0"
+                android:endY="0">
+                <item android:offset="0" android:color="#FF000000" />
+                <item android:offset="1" android:color="#FF666666" />
+            </gradient>
+        </aapt:attr>
+    </path>
+
+    <!-- White Archipelago pixel grid -->
+    <path
+        android:fillColor="#FFFFFF"
+        android:pathData="M253.805,278.37V222.28H309.853V278.37H253.805ZM315.797,278.37V222.28H372.694V278.37H315.797ZM378.639,278.37V222.28H435.536V278.37H378.639ZM441.481,278.37V222.28H497.529V278.37H441.481ZM441.481,341.259V284.319H497.529V341.259H441.481ZM503.473,341.259V284.319H560.37V341.259H503.473ZM190.963,404.148V347.208H247.86V404.148H190.963ZM253.805,404.148V347.208H309.853V404.148H253.805ZM315.797,404.148V347.208H372.694V404.148H315.797ZM378.639,404.148V347.208H435.536V404.148H378.639ZM441.481,404.148V347.208H497.529V404.148H441.481ZM503.473,404.148V347.208H560.37V404.148H503.473ZM190.963,466.187V410.097H247.86V466.187H190.963ZM253.805,466.187V410.097H309.853V466.187H253.805ZM441.481,466.187V410.097H497.529V466.187H441.481ZM503.473,466.187V410.097H560.37V466.187H503.473ZM253.805,529.076V472.136H309.853V529.076H253.805ZM315.797,529.076V472.136H372.694V529.076H315.797ZM378.639,529.076V472.136H435.536V529.076H378.639ZM441.481,529.076V472.136H497.529V529.076H441.481Z" />
+</vector>

Android/app/src/main/res/drawable/ic_nav_back.xml

@@ -0,0 +1,12 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24">
+    <path
+        android:pathData="M15,19l-7,-7 7,-7"
+        android:strokeColor="#FFFFFF"
+        android:strokeWidth="2"
+        android:strokeLineCap="round"
+        android:strokeLineJoin="round" />
+</vector>

Android/app/src/main/res/drawable/ic_nav_close.xml

@@ -0,0 +1,12 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24">
+    <path
+        android:pathData="M6,18L18,6M6,6l12,12"
+        android:strokeColor="#FFFFFF"
+        android:strokeWidth="2"
+        android:strokeLineCap="round"
+        android:strokeLineJoin="round" />
+</vector>

Android/app/src/main/res/drawable/ic_nav_forward.xml

@@ -0,0 +1,12 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24">
+    <path
+        android:pathData="M9,5l7,7 -7,7"
+        android:strokeColor="#FFFFFF"
+        android:strokeWidth="2"
+        android:strokeLineCap="round"
+        android:strokeLineJoin="round" />
+</vector>

Android/app/src/main/res/drawable/ic_nav_newtab.xml

@@ -0,0 +1,12 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24">
+    <path
+        android:pathData="M10,6H6a2,2 0,0 0,-2 2v10a2,2 0,0 0,2 2h10a2,2 0,0 0,2 -2v-4M14,4h6m0,0v6m0,-6L10,14"
+        android:strokeColor="#FFFFFF"
+        android:strokeWidth="2"
+        android:strokeLineCap="round"
+        android:strokeLineJoin="round" />
+</vector>

Android/app/src/main/res/drawable/ic_nav_refresh.xml

@@ -0,0 +1,12 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24">
+    <path
+        android:pathData="M4,4v6h6M20,20v-6h-6M5.64,15.36A8,8 0,0 0,18.36 18M18.36,8.64A8,8 0,0 0,5.64 6"
+        android:strokeColor="#FFFFFF"
+        android:strokeWidth="2"
+        android:strokeLineCap="round"
+        android:strokeLineJoin="round" />
+</vector>

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

@@ -21,4 +21,15 @@
     <string name="retry">Retry</string>
     <string name="remote_input">Remote Control</string>
     <string name="remote_input_hint">Use your phone as a keyboard and mouse for the kiosk</string>
+    <string name="close">Close</string>
+    <string name="open_in_browser">Open in browser</string>
+    <string name="back">Back</string>
+    <string name="forward">Forward</string>
+    <string name="refresh">Refresh</string>
+    <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="edit_server_title">Edit Server</string>
+    <string name="save_changes">Save Changes</string>
+    <string name="cancel">Cancel</string>
 </resources>

Android/logo.svg

@@ -0,0 +1,10 @@
+<svg width="752" height="752" viewBox="0 0 752 752" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="375.668" cy="375.669" r="364.227" fill="#0A0A0A" stroke="url(#paint0_linear_877_1990)" stroke-width="22.8834"/>
+<path d="M253.805 278.37V222.28H309.853V278.37H253.805ZM315.797 278.37V222.28H372.694V278.37H315.797ZM378.639 278.37V222.28H435.536V278.37H378.639ZM441.481 278.37V222.28H497.529V278.37H441.481ZM441.481 341.259V284.319H497.529V341.259H441.481ZM503.473 341.259V284.319H560.37V341.259H503.473ZM190.963 404.148V347.208H247.86V404.148H190.963ZM253.805 404.148V347.208H309.853V404.148H253.805ZM315.797 404.148V347.208H372.694V404.148H315.797ZM378.639 404.148V347.208H435.536V404.148H378.639ZM441.481 404.148V347.208H497.529V404.148H441.481ZM503.473 404.148V347.208H560.37V404.148H503.473ZM190.963 466.187V410.097H247.86V466.187H190.963ZM253.805 466.187V410.097H309.853V466.187H253.805ZM441.481 466.187V410.097H497.529V466.187H441.481ZM503.473 466.187V410.097H560.37V466.187H503.473ZM253.805 529.076V472.136H309.853V529.076H253.805ZM315.797 529.076V472.136H372.694V529.076H315.797ZM378.639 529.076V472.136H435.536V529.076H378.639ZM441.481 529.076V472.136H497.529V529.076H441.481Z" fill="white"/>
+<defs>
+<linearGradient id="paint0_linear_877_1990" x1="751.337" y1="751.338" x2="0" y2="0.000976562" gradientUnits="userSpaceOnUse">
+<stop/>
+<stop offset="1" stop-color="#666666"/>
+</linearGradient>
+</defs>
+</svg>

Android/ship-companion.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+#
+# Build the Android companion app and publish it as the served download
+# (neode-ui/public/packages/archipelago-companion.apk — a plain APK a phone can
+# install straight from the link), then commit + push.
+#
+# Use this INSTEAD of `git push` when shipping the companion app, so the
+# downloadable APK on the node always matches what's on main.
+#
+#   ./Android/ship-companion.sh
+#
+# The actual build/sign/verify/stage is done by scripts/publish-companion-apk.sh
+# (single source of truth, shared with the pre-push hook). It does a CLEAN build,
+# forces v1+v2+v3 signing, and ABORTS if any signature scheme is missing — so a
+# broken or v2-only APK can never be shipped.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+export JAVA_HOME="${JAVA_HOME:-/opt/homebrew/opt/openjdk@17}"
+export ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}"
+
+DEST="neode-ui/public/packages/archipelago-companion.apk"
+
+echo "==> Building + signing + verifying companion APK"
+bash scripts/publish-companion-apk.sh
+
+[ -f "$DEST" ] || { echo "ERROR: served APK not found at $DEST" >&2; exit 1; }
+
+if git diff --cached --quiet -- "$DEST"; then
+  echo "==> Nothing to commit (APK unchanged)"
+else
+  git commit -q -m "chore(android): update companion apk download"
+  echo "==> Committed"
+fi
+
+echo "==> Pushing $(git branch --show-current)"
+# SHIP_COMPANION lets the pre-push guard know the APK was just refreshed.
+SHIP_COMPANION=1 git push origin "$(git branch --show-current)"
+echo "==> Done — companion APK published and pushed."

CHANGELOG.md

@@ -1,5 +1,125 @@
 # Changelog
 
+## v1.8.00-alpha (2026-06-18)
+
+Polishes the mesh AI assistant and Fedimint, on top of all the v1.7.99 features (kept listed below so you can still see what's new).
+
+- The off-grid mesh radio no longer posts cryptic identity codes to the shared public channel. Your node was announcing a line starting with "ARCHY:" to the public channel about once a minute, which everyone else on that channel saw as spam; that broadcast has been removed.
+- You can now use your node's AI assistant straight from a normal chat. Send "!ai <your question>" in a direct message to an AI-enabled node and the answer comes right back in the same conversation — whether your message travelled over the internet or the LoRa radio. Before, the reply could be sent on the wrong path and never arrive.
+- The Mesh AI Assistant panel is easier to set up: pick the Claude model from a dropdown (Haiku, Sonnet, or Opus) instead of typing it, and add specific contacts to an "always allow" list so chosen people can use "!ai" even when the assistant is set to trusted-nodes-only.
+- Fedimint federations show up in Wallet Settings again. The Fedimint client app wasn't starting because of a configuration error, so the federation your node auto-joins never appeared; the client is fixed and runs again.
+- In Settings, "App Updates" and "App Registry" now sit directly under your Account section for quicker access.
+- In Mesh chat, scrolling the conversation no longer also scrolls the contact list behind it.
+- Mesh direct messages are now private and end-to-end encrypted to the recipient — they're sent as real radio DMs instead of being broadcast on the public channel, so other people on the mesh no longer see them, and the answer arrives intact (even on standard meshcore phone apps).
+- You can now message standard meshcore apps (like the phone companion) and they can message you — text shows up readable on both sides, and your node's AI answers come back as a private reply rather than on the public channel.
+- New contacts you hear on the radio are added automatically, so people show up in your Peers list without any extra steps.
+- "Clear All" now actually removes contacts (rather than hiding them forever); a contact comes back on its own the next time it's in range. Each contact also shows a reachability dot so you can see who's currently reachable.
+- The Peers list has a search box (with a clear button) to quickly filter your contacts by name, DID, npub, or key.
+
+All the v1.7.99-alpha features are included as well:
+
+- Your node can now hold Fedimint ecash as well as Cashu, with tabbed Wallet Settings for each and both balances shown side by side on the home wallet card.
+- You can buy files shared by another node right from their cloud, paying from this node's ecash, your Lightning wallet, on-chain, or by scanning a Lightning QR with any outside wallet.
+- Your node can act as an AI assistant on the off-grid mesh: peers ask by starting a message with "!ai" and get an answer back over the radio, with a panel to turn it on or off.
+- You can view your node's 24-word recovery phrase any time from Settings, behind a password (and 2FA) confirmation and a tap-to-show blur.
+- Setting up a brand-new node is smoother: it waits and retries quietly instead of flashing errors, and shows a gentle "securing your private connection…" status that turns to "ready" on its own.
+- The NetBird VPN app now logs in (it's served over HTTPS and opens in a browser tab).
+- Phone remote-control of a node's screen now supports two-finger scrolling inside apps, and external-browser apps open on your phone.
+- You can choose whether your node shares Bitcoin block headers over the mesh, and your choices are remembered.
+- Version numbers display cleanly everywhere (no more doubled "v"), and "Back" buttons look and behave consistently across desktop and mobile.
+- For advanced testing, Settings includes an optional update & app source choice between the usual trusted origin and an experimental peer-to-peer (DHT swarm) mode, with the trusted origin remaining the default.
+
+## v1.7.99-alpha (2026-06-17)
+
+- Your node can now hold Fedimint ecash as well as Cashu. Wallet Settings now has tabbed sections for each: keep your list of trusted Cashu mints, or paste a Fedimint invite code to join a federation, and the home wallet card shows both your Cashu and Fedimint balances side by side. A new "Fedimint Client" app in the catalog powers the federation side.
+- You can now buy files shared by another node, right from their cloud. When you open a peer's paid file you get a simple "Buy this file" picker with several ways to pay — instantly from this node's ecash balance, from your node's own Lightning wallet, on-chain from your node, or by scanning a Lightning QR code with any outside wallet. Once payment settles, the file downloads automatically.
+- Your node can now act as an AI assistant on the off-grid mesh radio network. If your node has a local AI model available (via Ollama), other people on the mesh can ask it a question by starting their message with "!ai" and get an answer back over the radio — handy where there's no internet. A new Mesh assistant panel lets you turn this on or off and shows whether a local AI model was detected.
+- You can now view your node's 24-word recovery phrase whenever you need it. Settings has a new "Recovery phrase" option that, after you confirm your password (and 2FA code if you use one), reveals the words behind a tap-to-show blur with a copy button — so you can write them down and store them safely offline.
+- Setting up a brand-new node is smoother and less alarming. If the node is still starting up while you generate or confirm your recovery phrase, it now quietly waits and retries instead of flashing a scary error, and offers a clear "Try again" button only when something genuinely goes wrong. The final setup screen also shows a gentle "securing your private connection…" status that turns to "ready" on its own, so you can tell the encrypted transport is coming up rather than stuck.
+- The NetBird VPN app now actually logs in. It was failing to reach its sign-in screen because the dashboard needs a secure (HTTPS) connection that wasn't being provided; the node now serves it over HTTPS and opens it in a browser tab, so the login flow completes.
+- When you use your phone to remote-control a node's attached screen, two-finger scrolling now works inside apps and panels, not just the main page. And tapping an app that's meant to open in an external browser now hands the link to your phone to open there, instead of trying to open it on the (often unattended) attached display.
+- You can now choose whether your node shares Bitcoin block headers over the mesh. The Mesh Bitcoin panel has new switches to announce headers to peers and to accept headers from them, and your choices are remembered.
+- Version numbers now display cleanly everywhere. In a few places the interface was showing a doubled "v" (like "vv1.7.98"); it now always shows a single, tidy version label.
+- The "Back" buttons throughout the cloud and other detail screens now look and behave consistently on both desktop and mobile, including when browsing another node's files.
+- For advanced testing, Settings now includes an optional "update & app source" choice between the usual trusted origin and an experimental peer-to-peer (DHT swarm) mode that pulls updates and app content from other nodes first, falling back to the origin automatically. The trusted origin remains the default.
+
+## v1.7.98-alpha (2026-06-16)
+
+- Apps that crash now recover on their own. Multi-part apps like Immich and IndeedHub could have one of their pieces stop and stay stopped until the whole node was rebooted; the node now checks every couple of minutes and restarts any crashed piece automatically (while still leaving apps you deliberately stopped alone).
+- The on-screen kiosk display can no longer slow the whole node down. On machines without a graphics chip the kiosk browser could spin a CPU core at full tilt, starving everything else (including the wallet, which then timed out); it's now capped and uses lighter rendering on those machines.
+- If an update download fails, you're taken back to the Download button to retry, instead of being stranded on an Install button for an update that didn't actually finish downloading.
+- Your node's identity is clearer and always visible: Settings now shows your Node DID on every node (it previously only appeared if your browser had cached it) plus your node's npub, both with copy buttons. There's also a terminal tool to cryptographically prove all your node's keys come from your one seed phrase.
+- The "all nodes over Tor" group chat sends quickly now — the "sending" spinner clears as soon as the reachable nodes have the message, instead of hanging on a slow or offline node.
+- Message notifications now have a close button and open the relevant chat when tapped.
+- The encrypted mesh transport (FIPS) turns itself on automatically after setup — no button to press — and connects to peers more reliably (it retries and keeps connections warm), so node-to-node features use the fast path more often instead of falling back to Tor.
+- Your chat history with other nodes is saved reliably and now encrypted on disk, so it survives restarts and updates and can't be read from a stolen drive (only clearing chat removes it).
+- Peer media shows a "connecting" loader before a video or audio file plays, and audio errors are accurate instead of blaming File Browser.
+- The Fedimint app now displays with its proper styling, and the Connected Nodes screen stays compact — it shows a few nodes and scrolls, you can tap a node to jump to it in Federation, or tap Message to open its chat.
+- App updates can now arrive on their own without waiting for a full system release, so individual apps can be improved and shipped faster.
+
+## v1.7.97-alpha (2026-06-16)
+
+- The Bitcoin sync status on the home screen no longer disappears for a moment when it refreshes. If the node was briefly busy, the panel used to vanish and pop back; it now stays put and simply shows "Updating…" until the next reading arrives, while a genuinely stopped node still correctly shows as not running.
+- Bitcoin sync progress on the home screen now updates more promptly, so the percentage and block height keep pace with the node instead of lagging behind.
+- The Lightning wallet "connect your wallet" screen loads its details and QR code again across all nodes, instead of failing to fetch them.
+- Your list of trusted nodes is now clean: the same node no longer appears several times under different names, and removed nodes stay removed. In chat, a node that previously showed up as two separate contacts now appears just once.
+- Browsing another node's cloud is smoother: music and video files from a peer now preview and play properly (including seeking partway through), and the connection now shows a small badge telling you whether it's using the fast encrypted mesh or the slower Tor network.
+- Opening "My Folders" in the cloud now shows a clear, friendly message when the file app isn't running, instead of a confusing error.
+- The Electrum server app opens on its own once it's ready, instead of sometimes leaving a loading spinner stuck on top of the screen.
+- The Fedimint app now displays with its proper styling and icons, instead of appearing unstyled with a missing image.
+- The Mempool app now connects to your Bitcoin node whether the node is Bitcoin Core or Bitcoin Knots, instead of only working with one of them.
+- Nodes start up cleanly after a reboot. On some boots the node's main service was trying to start before its data drive had finished mounting, so it failed and retried about twenty times over roughly five minutes — showing a wall of "Failed to start" messages — before finally coming up. It now waits for the data drive to be ready first, so it starts on the first try.
+- The background images throughout the interface now load faster — they've been made significantly smaller with no loss of quality.
+
+## v1.7.96-alpha (2026-06-15)
+
+- The screen attached to your node now shows the normal Archipelago interface and your dashboard after you sign in, instead of a separate, stripped-down grid of app icons that could appear in its place. That extra screen has been removed so the attached display matches what you see everywhere else.
+- On a brand-new node, the attached screen now walks through the same welcome and setup steps you'd see on a phone or laptop, and shows the normal sign-in screen once the node is set up — so the on-device display always matches the rest of the interface.
+- When adding a FIPS network anchor, you can now choose whether it connects over TCP (for a public anchor reached across the internet) or UDP (for one on your local network), instead of it always assuming the local-network option.
+- Behind the scenes, a new automated two-node test now exercises real node-to-node features — browsing another node's shared files and handling a removed node — against live nodes before each release, so node-to-node problems are caught earlier.
+
+## v1.7.95-alpha (2026-06-15)
+
+- Browsing another node's shared files now works over the fast encrypted mesh. Opening a peer's cloud could fail with a generic "Operation failed" message because the request for their file list wasn't permitted over the mesh and came back as "not found" — and it never retried over Tor. The mesh now serves the file list directly, and if a peer can't answer over the mesh the node automatically falls back to Tor instead of giving up.
+- Nodes you remove from your federation now stay removed. Previously a deleted node could quietly come back the next time you synced with another node that still listed it. Removed nodes are now remembered as removed and won't reappear on their own — only if you add them back yourself.
+- The app credentials pop-up now appears as a normal centred box with a dimmed background over the whole screen, instead of stretching to fill the entire screen.
+
+## v1.7.94-alpha (2026-06-15)
+
+- Your node now joins the private encrypted mesh network on its own. A wrong built-in setting meant nodes were quietly never reaching the shared mesh meeting point, so everything between nodes fell back to the slower Tor network. Every node now connects to the mesh automatically on startup, so node-to-node features like file sharing use the faster encrypted mesh first and only fall back to Tor when a peer is genuinely offline. (Confirmed live: a node with its mesh setting wiped re-connected to the mesh by itself within a second of starting.)
+- You can now bring the mesh networking software up to the latest stable version straight from the node, with one action — it fetches the new version, checks it's genuine before installing, and restarts the mesh on its own. (Confirmed live end to end: a node on an older build was upgraded to the current stable release and rejoined the mesh automatically.)
+- The Lightning wallet screen connects again on nodes where it was showing a "failed to fetch" error instead of your balance and channels. The wallet app and the node now talk to each other correctly, and the connection quietly repairs itself if its details drift after a restart.
+
+## v1.7.93-alpha (2026-06-14)
+
+- Receiving Bitcoin and Lightning works again on nodes where the Lightning wallet was stuck locked. After some updates the wallet could come back locked with a password the node no longer had, so "generate a receive address" kept failing with a "wallet is locked" message that nothing could clear. The node now detects this and repairs itself automatically.
+- Each node now secures its Lightning wallet with its own unique, randomly generated password instead of a shared built-in one, and remembers it safely so the wallet unlocks on its own after every restart or update — no more getting stuck locked.
+- If a wallet is found locked with an unrecoverable password, the node rebuilds it cleanly so Bitcoin and Lightning start working again. (On these early-access nodes the wallet holds no funds, so nothing is lost — a wallet locked with an unknown password was already inaccessible.)
+- The self-repair was validated end to end on live nodes: a stuck, locked wallet was detected, rebuilt, and came back unlocked on its own, and stayed unlocked across restarts.
+
+## v1.7.92-alpha (2026-06-14)
+
+- The Electrum server app no longer flashes a "can't connect, try again" error over its loading screen while it's still catching up. If ElectrumX is building its index or waiting on the Bitcoin node, you now just see the sync progress, and the app opens on its own once it's ready.
+- Behind the scenes, the reboot-survival test now confirms the whole system is genuinely healthy after a restart — every app reachable, updates not stuck, core services answering — instead of only checking that containers came back, so update-related problems are caught before shipping.
+- Settings → What's New now lists the notes for every recent release again. The screen had quietly fallen several versions behind, so the last eight releases of changes weren't showing up there — they're all back now, and a release check keeps it from drifting again.
+
+## v1.7.91-alpha (2026-06-14)
+
+- Apps you've installed now reliably show their "Open" button again. Some apps — including Jellyfin, BTCPay Server, Fedimint, Gitea and Portainer — were running fine but their launch link sometimes went missing, so there was no way to open them from the home screen. They now open correctly.
+- Receiving Bitcoin is more dependable: if the wallet's internal connection details drift after a restart, it now repairs them on its own, and any error it does hit is reported clearly instead of as a generic failure or a misleading "wallet locked" message.
+- Installing Bitcoin now sets itself up correctly without manual help — a security credential that could previously be missing and stop Bitcoin from starting is created automatically before it launches.
+- The Electrum server app is back on the home screen and can be launched again.
+- Behind the scenes, the release now runs an expanded automated test suite before shipping, so these kinds of issues are caught earlier.
+
+## v1.7.90-alpha (2026-06-13)
+
+- Generating a Bitcoin receive address works again — the wallet now requests the correct address type, fixing the "400 Bad Request" error when creating an address.
+- In the companion app, the on-screen pointer can now click into apps and type — including the app store search box — instead of clicks and keystrokes not reaching app content.
+- "Open in a new tab" from the companion app now opens the app in your phone's browser, instead of doing nothing. The normal mobile browser keeps working as before.
+- The login/credentials pop-up on phones is once again a centered, properly sized window rather than stretching the full height of the screen.
+- The Electrum server now recovers on its own if its index ever gets corrupted, and shows a clear progress screen (with percent complete and block height) while it builds its index, instead of a blank or broken page.
+- Software updates are more reliable on slow internet connections — downloads are given much more time to finish before giving up.
+
 ## v1.7.89-alpha (2026-06-12)
 
 - The AI assistant looks the way it always did again: no extra back button or close button on phones, and the desktop view fills the whole screen without a gap at the bottom.

CLAUDE.md

@@ -0,0 +1,57 @@
+# Archipelago — agent guide
+
+## ✅ Single-node production gate is GREEN (2026-06-23)
+
+`tests/lifecycle/run-gate.sh` is **5/5 on .228, 0 failures** — the single-node exit
+criterion is met and the priority banner is demoted. Next exit-criteria: the
+**multinode pass** (`docs/multinode-testing-plan.md`) and workstreams B/C/D.
+
+**Read `docs/PRODUCTION-MASTER-PLAN.md` first** — it is still the authoritative plan
+for the north star: a world-class, **developer-ready app platform** where every app
+is manifest-driven, manifests ship via the **signed registry** (not OTA disk files),
+and **third-party developers publish apps via an external/decentralized registry** —
+all rootless, secure, robust, and 100%-uptime-capable. It no longer overrides all
+ad-hoc direction now that the gate is green, but it remains the source of truth for
+sequencing the remaining workstreams.
+
+Detailed sub-plans (all linked from the master):
+- App platform / packaging phases + security model → `docs/APP-PACKAGING-MIGRATION-PLAN.md`
+- Registry-distributed manifests (in progress) → `docs/registry-manifest-design.md`
+- External/decentralized marketplace for devs → `docs/marketplace-protocol.md`
+- Current per-app state → `docs/app-registry-status-2026-06-21.md`
+- Production test gate (exit criterion) → `tests/lifecycle/TESTING.md`
+
+## Invariants (never violate)
+
+- **Rootless Podman only.** No rootful, no Docker-socket mounts, no privileged
+  containers unless explicitly approved.
+- **No per-app Rust installers / no OS-level reliance.** Apps are declarative;
+  the orchestrator owns the lifecycle. `install_immich_stack` (hardcoded
+  `podman run` + `sudo chown`) is the anti-pattern being deleted, not a template.
+- **Secrets are manifest-declared** (`generated_secrets`, materialised by
+  `container::secrets`, 0600/rootless) — never hardcoded, per-app, or logged.
+- **Migrations never destroy data** — preserve `/var/lib/archipelago/<app>`,
+  secrets, credentials, ports, and adoption container names; keep a rollback path.
+- **Verify on the real node .228 before any tag.** (Fleet-wide multinode
+  verification is a separate plan: `docs/multinode-testing-plan.md`.)
+
+## Build / verify
+
+- Rust workspace root is `core/` (no Cargo.toml at repo root). `cargo` from `core/`.
+- If a `cargo test`/build hits `rust-lld: undefined hidden symbol`, it's
+  incremental-cache corruption — rebuild with `CARGO_INCREMENTAL=0`.
+- Frontend: `neode-ui/` → `npm run build` outputs to `web/dist/neode-ui/`.
+  Grep the built bundle for new strings before shipping (build can silently no-op).
+- App manifests load from disk on nodes at `/opt/archipelago/apps/*/manifest.yml`
+  (today); the goal is to distribute them via the signed catalog instead.
+
+## Production test gate (definition of done)
+
+`tests/lifecycle/run-gate.sh` green across install / UI / stop / start / restart /
+reinstall / reboot-survive / archipelago-restart-survive / uninstall — **5× on
+.228** (`ARCHY_ITERATIONS=5`). **Run the gate ON the node** (it uses local podman/systemctl/bitcoin
+probes), not via RPC from another host. **✅ GREEN 2026-06-23 (5/5, 0 not-ok)** — keep it
+green (re-run after orchestrator/lifecycle changes); regressions are top priority again.
+**Multinode testing (.198 + the rest of the fleet) is a SEPARATE plan** —
+`docs/multinode-testing-plan.md` — not part of this single-node gate criterion, and is
+the next exit criterion now that single-node is green.

app-catalog/catalog.json

@@ -73,7 +73,7 @@
       "author": "Mempool",
       "category": "money",
       "tier": "core",
-      "dockerImage": "146.59.87.168:3000/lfg2025/mempool-frontend:v3.0.0",
+      "dockerImage": "146.59.87.168:3000/lfg2025/mempool-frontend:v3.0.1",
       "repoUrl": "https://github.com/mempool/mempool",
       "requires": [
         "bitcoin-knots",
@@ -281,7 +281,7 @@
     },
     {
       "id": "fedimint",
-      "title": "Fedimint",
+      "title": "Fedimint Guardian",
       "version": "0.10.0",
       "description": "Federated Bitcoin minting service with built-in Guardian UI. Privacy-preserving Bitcoin custody.",
       "icon": "/assets/img/app-icons/fedimint.png",
@@ -290,6 +290,18 @@
       "dockerImage": "146.59.87.168:3000/lfg2025/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 your 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",
+      "category": "money",
+      "tier": "core",
+      "dockerImage": "146.59.87.168:3000/lfg2025/fmcd:0.8.0",
+      "repoUrl": "https://github.com/minmoto/fmcd"
+    },
     {
       "id": "fedimint-gateway",
       "title": "Fedimint Gateway",

apps/archy-mempool-web/manifest.yml

@@ -1,12 +1,12 @@
 app:
   id: archy-mempool-web
   name: Mempool Web
-  version: 3.0.0
+  version: 3.0.1
   description: Frontend web UI for mempool explorer.
   container_name: mempool
 
   container:
-    image: git.tx1138.com/lfg2025/mempool-frontend:v3.0.0
+    image: 146.59.87.168:3000/lfg2025/mempool-frontend:v3.0.1
     pull_policy: if-not-present
     network: archy-net
 

apps/electrumx/manifest.yml

@@ -51,6 +51,20 @@ app:
     - CACHE_MB=1024
     - MAX_SEND=10000000
 
+  # The ElectrumX dashboard tile is served by the host-networked companion UI
+  # (archy-electrs-ui) on port 50002, NOT by this container. Declaring it here
+  # lets the catalog generator emit electrumx -> 50002 into GENERATED_APP_PORTS
+  # so the tile resolves a launch URL without relying on the hand-maintained
+  # override in appSessionConfig.ts (which the generator can clobber). The
+  # backend only validates this block — it does not proxy/health-check it.
+  interfaces:
+    main:
+      name: Web UI
+      description: ElectrumX server status and connection details
+      type: ui
+      port: 50002
+      protocol: http
+
   health_check:
     type: tcp
     endpoint: localhost:50001

apps/fedimint-clientd/manifest.yml

@@ -0,0 +1,95 @@
+app:
+  id: fedimint-clientd
+  name: 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.
+
+  container:
+    # fmcd built from source (github.com/minmoto/fmcd v0.8.0, fedimint-client
+    # 0.8.2 — iroh-capable). No usable upstream image exists, so we build + push
+    # this to the node registry. Pin the tag to match the REST shapes coded in
+    # core/archipelago/src/wallet/fedimint_client.rs (validated against 0.8.2).
+    image: 146.59.87.168:3000/lfg2025/fmcd:0.8.0
+    pull_policy: if-not-present
+    network: archy-net
+    # No entrypoint override: the image's resilient `fmcd-run` launcher loops
+    # fmcd and retries on join failure (fmcd needs >=1 federation to boot), so an
+    # unreachable default never crash-loops. All config comes from FMCD_* env
+    # below. Nodes can join more federations via wallet.fedimint-join.
+    # Auto-generated on first install (random hex, 0600, rootless-owned) so the
+    # app needs no host provisioning. The wallet bridge reads the same file.
+    generated_secrets:
+      - name: fmcd-password
+        kind: hex16
+    secret_env:
+      - key: FMCD_PASSWORD
+        secret_file: fmcd-password
+    data_uid: "1000:1000"
+
+  # NOTE: this is a CLIENT, not the guardian — it does not require the local
+  # `fedimint` app. It joins external federations (default below), so it can be
+  # bundled standalone on every node.
+  dependencies:
+    - storage: 2Gi
+
+  resources:
+    cpu_limit: 1
+    memory_limit: 1Gi
+    disk_limit: 2Gi
+
+  security:
+    # fmcd's `fmcd-run` launcher chowns its /data (existing federation DB) on
+    # every start. With the default `cap_drop: ALL` and no caps added back, that
+    # chown fails and fmcd dies "Operation not permitted (os error 1)" — but ONLY
+    # once /data holds a joined federation (a fresh/empty dir needs no chown, so
+    # it appeared to work). Restore the standard container capability set so the
+    # startup chown succeeds (#7). Verified by bisection on .116: these caps make
+    # fmcd boot + serve /v2/*; DAC_OVERRIDE or SETUID/SETGID alone do NOT.
+    capabilities: ["CHOWN", "DAC_OVERRIDE", "FOWNER", "SETUID", "SETGID"]
+    readonly_root: true
+    # NOT isolated: fmcd needs outbound UDP + Mainline DHT (port 6881) + iroh
+    # relays to reach iroh-transport federations. `bridge` gives NAT'd outbound
+    # (UDP/DHT/iroh hole-punch all work) plus the published 8178→8080 port the
+    # wallet bridge targets. ("open" is not a valid policy — it made the loader
+    # skip this whole manifest, so fmcd never ran and federations never joined.)
+    # Lock down once the default federation's reachability model is finalized.
+    network_policy: bridge
+
+  ports:
+    # fmcd REST bound to 8080 in-container; 8080 collides with LND REST on the
+    # host, so map to 8178. The Rust bridge targets http://127.0.0.1:8178.
+    - host: 8178
+      container: 8080
+      protocol: tcp
+
+  volumes:
+    # Same dir the first-boot bundled path uses + where the wallet bridge reads
+    # the password (/var/lib/archipelago/fmcd/password) — keep install paths aligned.
+    - type: bind
+      source: /var/lib/archipelago/fmcd
+      target: /data
+      options: [rw]
+
+  environment:
+    - FMCD_ADDR=0.0.0.0:8080
+    - FMCD_MODE=rest
+    - FMCD_DATA_DIR=/data
+    # Default federation joined out-of-the-box (guardian on .116, iroh
+    # transport; validated to join with fmcd 0.8.2). iroh does NAT traversal so
+    # it's reachable fleet-wide. Keep in sync with DEFAULT_FEDERATION_INVITE in
+    # core/.../wallet/fedimint_client.rs. CAVEAT: iroh is experimental — validate
+    # join reliability from a real second node before relying on auto-bundle.
+    - FMCD_INVITE_CODE=fed11qgqyj3mfwfhksw309uuxywtxxfjrjc35xuexverpxdsnxcnrxucxvenzveskgc3kvvun2c34xp3k2ep38yunzdpexcekxe3hvd3rvvmx8pnrvdenx5mnzvtzqqqjqt0t6pc3s5z0ynqjw9s4njf6svwgu59kweawc0vvrddcjeemw6yyn4pcdp
+
+  # fmcd serves only authenticated /v2/* routes — there is no unauthenticated
+  # /health endpoint, so an http probe to /health 404s forever and pins the
+  # container in "(starting)". fmcd's own image also ships neither curl nor wget.
+  # Use a TCP probe: the Quadlet renderer skips it (no HealthCmd emitted) and the
+  # host-side lifecycle layer verifies reachability, so the container reports
+  # "running" instead of a perpetual false-negative "(starting)".
+  health_check:
+    type: tcp
+    endpoint: localhost:8080
+    interval: 30s
+    timeout: 5s
+    retries: 3

apps/fedimint-gateway/manifest.yml

@@ -16,6 +16,14 @@ app:
         else
           exec gatewayd --data-dir /data --listen 0.0.0.0:8176 --bcrypt-password-hash "$FEDI_HASH" --network bitcoin --bitcoind-url http://host.archipelago:8332 --bitcoind-username "$FM_BITCOIND_USERNAME" --bitcoind-password "$FM_BITCOIND_PASSWORD" ldk --ldk-lightning-port 9737 --ldk-alias archipelago-gateway;
         fi
+    # The gateway's admin API is gated by a bcrypt password hash. Generate it on
+    # first install (random password + its bcrypt hash, both 0600 rootless-owned)
+    # so the app installs from its manifest alone — `fedimint-gateway-hash` holds
+    # the hash passed to gatewayd, `fedimint-gateway-hash.pw` the plaintext for
+    # any client that must authenticate. Self-heals a wrongly root-owned hash.
+    generated_secrets:
+      - name: fedimint-gateway-hash
+        kind: bcrypt
     secret_env:
       - key: FM_BITCOIND_PASSWORD
         secret_file: bitcoin-rpc-password

apps/fedimint/manifest.yml

@@ -1,6 +1,6 @@
 app:
   id: fedimint
-  name: Fedimint
+  name: Fedimint Guardian
   version: 0.10.0
   description: Federated Bitcoin minting service with built-in Guardian UI. Privacy-preserving Bitcoin custody.
 

apps/fips-ui/manifest.yml

@@ -0,0 +1,42 @@
+app:
+  id: fips-ui
+  name: FIPS Mesh
+  version: 1.0.0
+  description: |
+    Archipelago-native dashboard for the FIPS mesh transport. Runs nginx
+    inside a container with host networking, serves a static dashboard on
+    :8336, and reverse-proxies /rpc/v1 to the archipelago backend on
+    127.0.0.1:5678. All FIPS controls (status, seed anchors, reconnect,
+    restart, and stable-channel daemon updates) go through the existing
+    fips.* RPC methods, authenticated by the browser's own archipelago
+    session — there is no separate secret to manage.
+
+  container:
+    build:
+      context: /opt/archipelago/docker/fips-ui
+      dockerfile: Dockerfile
+      tag: localhost/fips-ui:local
+
+  resources:
+    memory_limit: 128Mi
+
+  security:
+    readonly_root: false
+    network_policy: host
+
+  # Host networking: nginx listens on 8336 directly on the host IP and
+  # proxies to 127.0.0.1:5678 (the archipelago RPC). `ports:` is
+  # intentionally empty because host networking bypasses port mapping.
+  ports: []
+
+  volumes: []
+
+  environment: []
+
+  health_check:
+    type: http
+    endpoint: http://127.0.0.1:8336
+    path: /
+    interval: 30s
+    timeout: 5s
+    retries: 3

apps/immich-postgres/manifest.yml

@@ -0,0 +1,58 @@
+app:
+  id: immich-postgres
+  name: Immich Postgres
+  version: "14-vectorchord0.4.3-pgvectors0.2.0"
+  description: Postgres (pgvecto.rs / vectorchord) backend for Immich.
+
+  # Container named immich_postgres (underscore) to match the runtime's existing
+  # per-app references (lifecycle/health/crash-recovery/config) and serve as the
+  # server's DB_HOSTNAME alias. Top-level key → serde(flatten) → extensions →
+  # compute_container_name.
+  container_name: immich_postgres
+
+  container:
+    image: 146.59.87.168:3000/lfg2025/immich-postgres:14-vectorchord0.4.3-pgvectors0.2.0
+    pull_policy: if-not-present
+    network: archy-net
+    # postgres drops to its own uid (container 999 → host 100998 under rootless),
+    # so the data dir must be owned by that mapped uid — mirrors archy-btcpay-db.
+    # Verified on .228: the live immich-db is owned 100998. Without this a FRESH
+    # install's dir would be service-user-owned and postgres would EACCES.
+    data_uid: "100998:100998"
+    generated_secrets:
+      - name: immich-db-password
+        kind: hex32
+    secret_env:
+      - key: POSTGRES_PASSWORD
+        secret_file: immich-db-password
+
+  dependencies:
+    - storage: 40Gi
+
+  resources:
+    memory_limit: 2Gi
+    disk_limit: 40Gi
+
+  security:
+    capabilities: [CHOWN, DAC_OVERRIDE, FOWNER, SETGID, SETUID]
+    readonly_root: false
+    network_policy: isolated
+
+  ports: []
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/immich-db
+      target: /var/lib/postgresql/data
+      options: [rw]
+
+  environment:
+    - POSTGRES_USER=postgres
+    - POSTGRES_DB=immich
+
+  health_check:
+    type: tcp
+    endpoint: localhost:5432
+    interval: 30s
+    timeout: 5s
+    retries: 3

apps/immich-redis/manifest.yml

@@ -0,0 +1,37 @@
+app:
+  id: immich-redis
+  name: Immich Redis
+  version: "7-alpine"
+  description: Valkey (Redis-compatible) cache for Immich.
+
+  # Container named immich_redis (underscore) to match runtime per-app references
+  # and serve as the server's REDIS_HOSTNAME alias on archy-net.
+  container_name: immich_redis
+
+  container:
+    image: 146.59.87.168:3000/lfg2025/valkey:7-alpine
+    pull_policy: if-not-present
+    network: archy-net
+
+  dependencies: []
+
+  resources:
+    memory_limit: 128Mi
+
+  security:
+    capabilities: [SETGID, SETUID]
+    readonly_root: false
+    network_policy: isolated
+
+  ports: []
+
+  volumes: []
+
+  environment: []
+
+  health_check:
+    type: tcp
+    endpoint: localhost:6379
+    interval: 30s
+    timeout: 5s
+    retries: 3

apps/immich/manifest.yml

@@ -0,0 +1,74 @@
+app:
+  id: immich
+  name: Immich
+  version: "2.7.4"
+  description: Self-hosted photo and video backup with mobile apps and search.
+
+  # app_id "immich" = the user-facing launcher (matches the catalog entry's title
+  # + icon). The container is named "immich_server" so it matches the runtime's
+  # existing per-app container references (lifecycle/health/crash-recovery/ports);
+  # `container_name` is a top-level app key (captured by serde(flatten) into
+  # extensions, read by compute_container_name). It reaches its backends by their
+  # underscore aliases on archy-net (DB_HOSTNAME / REDIS_HOSTNAME below).
+  container_name: immich_server
+
+  container:
+    image: 146.59.87.168:3000/lfg2025/immich-server:release
+    pull_policy: if-not-present
+    network: archy-net
+    secret_env:
+      - key: DB_PASSWORD
+        secret_file: immich-db-password
+
+  dependencies:
+    - app_id: immich-postgres
+    - app_id: immich-redis
+    - storage: 200Gi
+
+  resources:
+    memory_limit: 2Gi
+    disk_limit: 200Gi
+
+  security:
+    capabilities: []
+    readonly_root: false
+    network_policy: isolated
+
+  ports:
+    - host: 2283
+      container: 2283
+      protocol: tcp
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/immich
+      target: /usr/src/app/upload
+      options: [rw]
+
+  environment:
+    - DB_HOSTNAME=immich_postgres
+    - DB_USERNAME=postgres
+    - DB_DATABASE_NAME=immich
+    - REDIS_HOSTNAME=immich_redis
+    - UPLOAD_LOCATION=/usr/src/app/upload
+
+  health_check:
+    type: http
+    endpoint: http://localhost:2283
+    path: /api/server/ping
+    interval: 30s
+    timeout: 5s
+    retries: 20
+
+  interfaces:
+    main:
+      name: Web UI
+      description: Immich photo library
+      type: ui
+      port: 2283
+      protocol: http
+      path: /
+
+  metadata:
+    launch:
+      open_in_new_tab: true

apps/indeedhub-api/manifest.yml

@@ -0,0 +1,77 @@
+app:
+  id: indeedhub-api
+  name: IndeedHub API
+  version: "1.0.0"
+  description: IndeedHub backend API (Nostr auth, media, payments).
+  category: community
+
+  # Hyphen name matches runtime references + the live container (adoption);
+  # alias `api` is the short hostname the frontend nginx proxies to
+  # (http://api:4000). Reaches its backends by their short aliases
+  # (postgres/redis/minio) on indeedhub-net — unchanged from the legacy installer.
+  container_name: indeedhub-api
+
+  container:
+    image: 146.59.87.168:3000/lfg2025/indeedhub-api:1.0.0
+    pull_policy: if-not-present
+    network: indeedhub-net
+    network_aliases: [api]
+    # The JWT signing secret is owned here (no backend container owns it); the
+    # db + minio passwords are owned by indeedhub-postgres / indeedhub-minio and
+    # only consumed here. ensure_generated_secrets no-ops when a file already
+    # exists, so live values on .228 are preserved (postgres pw is fixed at
+    # PGDATA init — regenerating would lock the API out).
+    generated_secrets:
+      - name: indeedhub-jwt
+        kind: hex32
+    secret_env:
+      - key: DATABASE_PASSWORD
+        secret_file: indeedhub-db-password
+      - key: AWS_SECRET_KEY
+        secret_file: indeedhub-minio-password
+      - key: NOSTR_JWT_SECRET
+        secret_file: indeedhub-jwt
+
+  dependencies:
+    - app_id: indeedhub-postgres
+    - app_id: indeedhub-redis
+    - app_id: indeedhub-minio
+
+  resources:
+    memory_limit: 2Gi
+
+  security:
+    capabilities: []
+    readonly_root: false
+    network_policy: isolated
+
+  ports: []
+
+  volumes: []
+
+  environment:
+    - PORT=4000
+    - DATABASE_HOST=postgres
+    - DATABASE_PORT=5432
+    - DATABASE_USER=indeedhub
+    - DATABASE_NAME=indeedhub
+    - QUEUE_HOST=redis
+    - QUEUE_PORT=6379
+    - S3_ENDPOINT=http://minio:9000
+    - AWS_REGION=us-east-1
+    - AWS_ACCESS_KEY=indeeadmin
+    - S3_PUBLIC_BUCKET_NAME=indeedhub-public
+    - S3_PRIVATE_BUCKET_NAME=indeedhub-private
+    - S3_PUBLIC_BUCKET_URL=/storage
+    - NOSTR_JWT_EXPIRES_IN=7d
+    # Fixed across the fleet (envelope-encryption master key baked by the legacy
+    # installer); not node-specific, so a plain env literal, not a secret.
+    - AES_MASTER_SECRET=0123456789abcdef0123456789abcdef
+    - ENVIRONMENT=production
+
+  health_check:
+    type: tcp
+    endpoint: localhost:4000
+    interval: 30s
+    timeout: 5s
+    retries: 10

apps/indeedhub-ffmpeg/manifest.yml

@@ -0,0 +1,51 @@
+app:
+  id: indeedhub-ffmpeg
+  name: IndeedHub FFmpeg Worker
+  version: "1.0.0"
+  description: IndeedHub background media transcoding worker.
+  category: community
+
+  # Hyphen name matches runtime references + the live container (adoption). No
+  # network_alias: nothing connects TO the worker — it only dials out to
+  # postgres/redis/minio (resolved by their aliases on indeedhub-net).
+  container_name: indeedhub-ffmpeg
+
+  container:
+    image: 146.59.87.168:3000/lfg2025/indeedhub-ffmpeg:1.0.0
+    pull_policy: if-not-present
+    network: indeedhub-net
+    secret_env:
+      - key: DATABASE_PASSWORD
+        secret_file: indeedhub-db-password
+      - key: AWS_SECRET_KEY
+        secret_file: indeedhub-minio-password
+
+  dependencies:
+    - app_id: indeedhub-api
+
+  resources:
+    memory_limit: 4Gi
+
+  security:
+    capabilities: []
+    readonly_root: false
+    network_policy: isolated
+
+  ports: []
+
+  volumes: []
+
+  environment:
+    - DATABASE_HOST=postgres
+    - DATABASE_PORT=5432
+    - DATABASE_USER=indeedhub
+    - DATABASE_NAME=indeedhub
+    - QUEUE_HOST=redis
+    - QUEUE_PORT=6379
+    - S3_ENDPOINT=http://minio:9000
+    - AWS_REGION=us-east-1
+    - AWS_ACCESS_KEY=indeeadmin
+    - S3_PUBLIC_BUCKET_NAME=indeedhub-public
+    - S3_PRIVATE_BUCKET_NAME=indeedhub-private
+    - ENVIRONMENT=production
+    - AES_MASTER_SECRET=0123456789abcdef0123456789abcdef

apps/indeedhub-minio/manifest.yml

@@ -0,0 +1,60 @@
+app:
+  id: indeedhub-minio
+  name: IndeedHub MinIO
+  version: "RELEASE.2024-11-07T00-52-20Z"
+  description: MinIO S3-compatible object storage for IndeedHub media.
+  category: community
+
+  # Hyphen name matches runtime references + the live container (adoption);
+  # alias `minio` is the short hostname the api/ffmpeg use (S3_ENDPOINT=
+  # http://minio:9000) AND the frontend nginx proxies to (http://minio:9000).
+  container_name: indeedhub-minio
+
+  container:
+    image: 146.59.87.168:3000/lfg2025/minio:RELEASE.2024-11-07T00-52-20Z
+    pull_policy: if-not-present
+    network: indeedhub-net
+    network_aliases: [minio]
+    # `server /data` — the minio entrypoint args from the legacy installer.
+    custom_args: [server, /data]
+    generated_secrets:
+      - name: indeedhub-minio-password
+        kind: hex32
+    secret_env:
+      - key: MINIO_ROOT_PASSWORD
+        secret_file: indeedhub-minio-password
+
+  dependencies:
+    - storage: 50Gi
+
+  resources:
+    memory_limit: 1Gi
+    disk_limit: 50Gi
+
+  security:
+    capabilities: []
+    readonly_root: false
+    network_policy: isolated
+
+  ports: []
+
+  # Named volume matches the live indeedhub-minio-data volume on .228.
+  volumes:
+    - type: volume
+      source: indeedhub-minio-data
+      target: /data
+      options: [rw]
+
+  # MINIO_ROOT_USER "indeeadmin" is the fixed admin identity baked by the legacy
+  # installer (api/ffmpeg use it as AWS_ACCESS_KEY); the password is the
+  # generated secret above. Not secret, so it stays a plain env value.
+  environment:
+    - MINIO_ROOT_USER=indeeadmin
+
+  health_check:
+    type: http
+    endpoint: http://localhost:9000
+    path: /minio/health/live
+    interval: 30s
+    timeout: 5s
+    retries: 5

apps/indeedhub-postgres/manifest.yml

@@ -0,0 +1,59 @@
+app:
+  id: indeedhub-postgres
+  name: IndeedHub Postgres
+  version: "16.13-alpine"
+  description: Postgres database backend for IndeedHub.
+  category: community
+
+  # Container named indeedhub-postgres (hyphen) to match the runtime's existing
+  # per-app references (health_monitor tiers/deps, crash_recovery) and the live
+  # .228 install, so the orchestrator ADOPTS the running container instead of
+  # recreating it. `network_aliases: [postgres]` keeps the short hostname the
+  # api/ffmpeg/relay reach by (DATABASE_HOST=postgres) resolvable on
+  # indeedhub-net, reproducing the legacy `--network-alias postgres`.
+  container_name: indeedhub-postgres
+
+  container:
+    image: 146.59.87.168:3000/lfg2025/postgres:16.13-alpine
+    pull_policy: if-not-present
+    network: indeedhub-net
+    network_aliases: [postgres]
+    generated_secrets:
+      - name: indeedhub-db-password
+        kind: hex32
+    secret_env:
+      - key: POSTGRES_PASSWORD
+        secret_file: indeedhub-db-password
+
+  dependencies:
+    - storage: 10Gi
+
+  resources:
+    memory_limit: 1Gi
+    disk_limit: 10Gi
+
+  security:
+    capabilities: [CHOWN, DAC_OVERRIDE, FOWNER, SETGID, SETUID]
+    readonly_root: false
+    network_policy: isolated
+
+  ports: []
+
+  # Named podman volume (matches the live indeedhub-postgres-data volume on .228);
+  # preserves all existing database content across the migration.
+  volumes:
+    - type: volume
+      source: indeedhub-postgres-data
+      target: /var/lib/postgresql/data
+      options: [rw]
+
+  environment:
+    - POSTGRES_USER=indeedhub
+    - POSTGRES_DB=indeedhub
+
+  health_check:
+    type: tcp
+    endpoint: localhost:5432
+    interval: 30s
+    timeout: 5s
+    retries: 3

apps/indeedhub-redis/manifest.yml

@@ -0,0 +1,45 @@
+app:
+  id: indeedhub-redis
+  name: IndeedHub Redis
+  version: "7.4.8-alpine"
+  description: Redis queue/cache backend for IndeedHub.
+  category: community
+
+  # Hyphen name matches runtime references + the live container (adoption);
+  # alias `redis` is the short hostname the api/ffmpeg reach (QUEUE_HOST=redis).
+  container_name: indeedhub-redis
+
+  container:
+    image: 146.59.87.168:3000/lfg2025/redis:7.4.8-alpine
+    pull_policy: if-not-present
+    network: indeedhub-net
+    network_aliases: [redis]
+
+  dependencies:
+    - storage: 1Gi
+
+  resources:
+    memory_limit: 256Mi
+
+  security:
+    capabilities: [SETGID, SETUID]
+    readonly_root: false
+    network_policy: isolated
+
+  ports: []
+
+  # Named volume matches the live indeedhub-redis-data volume on .228.
+  volumes:
+    - type: volume
+      source: indeedhub-redis-data
+      target: /data
+      options: [rw]
+
+  environment: []
+
+  health_check:
+    type: tcp
+    endpoint: localhost:6379
+    interval: 30s
+    timeout: 5s
+    retries: 3

apps/indeedhub-relay/manifest.yml

@@ -0,0 +1,47 @@
+app:
+  id: indeedhub-relay
+  name: IndeedHub Nostr Relay
+  version: "0.9.0"
+  description: nostr-rs-relay backing IndeedHub's Nostr identity + comments.
+  category: community
+
+  # Hyphen name matches runtime references + the live container (adoption);
+  # alias `relay` is the short hostname the frontend nginx proxies to
+  # (http://relay:8080 for the /relay websocket).
+  container_name: indeedhub-relay
+
+  container:
+    image: 146.59.87.168:3000/lfg2025/nostr-rs-relay:0.9.0
+    pull_policy: if-not-present
+    network: indeedhub-net
+    network_aliases: [relay]
+
+  dependencies:
+    - storage: 2Gi
+
+  resources:
+    memory_limit: 256Mi
+    disk_limit: 2Gi
+
+  security:
+    capabilities: []
+    readonly_root: false
+    network_policy: isolated
+
+  ports: []
+
+  # Named volume matches the live indeedhub-relay-data volume on .228.
+  volumes:
+    - type: volume
+      source: indeedhub-relay-data
+      target: /usr/src/app/db
+      options: [rw]
+
+  environment: []
+
+  health_check:
+    type: tcp
+    endpoint: localhost:8080
+    interval: 30s
+    timeout: 5s
+    retries: 3

apps/indeedhub/manifest.yml

@@ -1,63 +1,84 @@
 app:
   id: indeedhub
   name: IndeeHub
-  version: 1.0.0
+  version: "1.0.0"
   description: Bitcoin documentary streaming platform featuring God Bless Bitcoin and other educational content about Bitcoin, sovereignty, and decentralized technology. Sign in with your Nostr identity.
   category: community
 
+  # The user-facing launcher (app_id "indeedhub"). Container is named "indeedhub"
+  # (matches the runtime's per-app references + the live container, so the
+  # orchestrator adopts it). Its nginx (listen 7777) proxies to the backends by
+  # their short aliases on indeedhub-net: api:4000, minio:9000, relay:8080.
+  container_name: indeedhub
+
   container:
     image: 146.59.87.168:3000/lfg2025/indeedhub:1.0.0
-    pull_policy: always  # Pull from registry; falls back to local build
+    pull_policy: if-not-present
     network: indeedhub-net
 
   dependencies:
+    - app_id: indeedhub-api
     - storage: 1Gi
 
   resources:
-    cpu_limit: 2
     memory_limit: 512Mi
     disk_limit: 1Gi
 
   security:
-    capabilities: []
-    readonly_root: true
-    no_new_privileges: true
-    user: 1001
-    seccomp_profile: default
-    network_policy: bridge
-    apparmor_profile: default
+    # nginx master runs as root and drops workers to the nginx user (uid/gid
+    # 101) — needs SET{UID,GID}; CHOWN + DAC_OVERRIDE let it own + write the
+    # proxy cache under the tmpfs /var/cache/nginx. The orchestrator does
+    # --cap-drop=ALL, so (unlike the legacy `podman run` default caps) these
+    # must be declared or nginx workers die with "setgid(101) failed".
+    capabilities: [CHOWN, DAC_OVERRIDE, SETGID, SETUID]
+    readonly_root: false
+    network_policy: isolated
 
   ports:
     - host: 7778
       container: 7777
-      protocol: tcp  # Web UI. Port 7777 on the host is reserved for Nostr relay.
+      protocol: tcp  # Web UI. Port 7777 on the host is reserved for the Nostr relay.
 
+  # Writable scratch the baked nginx needs; matches the legacy installer's
+  # --tmpfs /run + /var/cache/nginx.
   volumes:
-    - type: tmpfs
-      target: /tmp
-      options: [rw,noexec,nosuid,size=64m]
-    - type: tmpfs
-      target: /app/.next/cache
-      options: [rw,noexec,nosuid,size=128m]
     - type: tmpfs
       target: /run
-      options: [rw,nosuid,nodev,size=16m]
+      options: [rw, nosuid, nodev, size=16m]
     - type: tmpfs
       target: /var/cache/nginx
-      options: [rw,nosuid,nodev,size=32m]
+      options: [rw, nosuid, nodev, size=32m]
 
-  environment:
-    - NODE_ENV=production
-    - NEXT_TELEMETRY_DISABLED=1
+  environment: []
 
+  # Defensive + idempotent. The current indeedhub:1.0.0 image already bakes the
+  # iframe-friendly nginx (X-Frame-Options omitted, nostr-provider.js present +
+  # <script> injected), so these are mostly no-ops on that tag — but they keep
+  # the app iframe-loadable + the provider script fresh for any image build that
+  # predates the bake. copy_from_host pulls /opt/archipelago/web-ui/nostr-provider.js
+  # (kept current by frontend OTA releases). Replaces the legacy hardcoded
+  # patch_indeedhub_nostr_provider() Rust hook.
+  hooks:
+    post_install:
+      - exec: ["sed", "-i", "/X-Frame-Options/d", "/etc/nginx/conf.d/default.conf"]
+      - copy_from_host:
+          src: "web-ui/nostr-provider.js"
+          dest: "/usr/share/nginx/html/nostr-provider.js"
+      - exec: ["sh", "-c", "grep -q nostr-provider /etc/nginx/conf.d/default.conf || sed -i 's#</head>#<script src=\"/nostr-provider.js\"></script></head>#' /etc/nginx/conf.d/default.conf"]
+      - exec: ["nginx", "-s", "reload"]
+
+  # TCP liveness on the nginx port, NOT an http GET of /. nginx binds 7777 at
+  # startup (before workers), so this passes immediately and stays green under
+  # load. An http check of / runs the SPA + sub_filter and false-fails when the
+  # node is busy → the reconciler then treats the frontend as wedged and
+  # recreates it in a loop (observed churning the frontend on the loaded .198).
   health_check:
-    type: http
-    endpoint: http://localhost:3000
-    path: /
+    type: tcp
+    endpoint: localhost:7777
     interval: 30s
-    timeout: 10s
-    retries: 3
-    start_period: 40s
+    timeout: 5s
+    retries: 5
+    start_period: 30s
 
   interfaces:
     main:

apps/mempool-api/manifest.yml

@@ -8,6 +8,12 @@ app:
     image: git.tx1138.com/lfg2025/mempool-backend:v3.0.0
     pull_policy: if-not-present
     network: archy-net
+    # CORE_RPC_HOST must follow the node's actual Bitcoin container — Knots or
+    # Core — resolved at apply time from host facts (B12). Hardcoding either
+    # breaks mempool's RPC connection on the other.
+    derived_env:
+      - key: CORE_RPC_HOST
+        template: "{{BITCOIN_HOST}}"
     secret_env:
       - key: CORE_RPC_PASSWORD
         secret_file: bitcoin-rpc-password
@@ -47,7 +53,6 @@ app:
     - ELECTRUM_HOST=electrumx
     - ELECTRUM_PORT=50001
     - ELECTRUM_TLS_ENABLED=false
-    - CORE_RPC_HOST=bitcoin-knots
     - CORE_RPC_PORT=8332
     - CORE_RPC_USERNAME=archipelago
     - DATABASE_ENABLED=true

apps/mempool/manifest.yml

@@ -5,7 +5,7 @@ app:
   description: Bitcoin mempool and blockchain explorer. Real-time transaction and block visualization.
   
   container:
-    image: 146.59.87.168:3000/lfg2025/mempool-frontend:v3.0.0
+    image: 146.59.87.168:3000/lfg2025/mempool-frontend:v3.0.1
     image_signature: cosign://...
     pull_policy: if-not-present
     

apps/meshtastic/Dockerfile

@@ -1,5 +0,0 @@
-# Meshtastic - uses official image
-FROM meshtastic/meshtastic:latest
-
-# Default configuration is in the image
-# No additional setup needed

apps/meshtastic/manifest.yml

@@ -1,69 +0,0 @@
-app:
-  id: meshtastic
-  name: Meshtastic
-  version: 2-daily-alpine
-  description: Open-source mesh networking for LoRa radios. Create decentralized communication networks.
-  
-  container:
-    image: docker.io/meshtastic/meshtasticd:daily-alpine
-    pull_policy: if-not-present
-    
-  dependencies:
-    - storage: 1Gi
-    
-  resources:
-    cpu_limit: 1
-    memory_limit: 512Mi
-    disk_limit: 1Gi
-    
-  security:
-    capabilities: [NET_ADMIN, SYS_ADMIN]  # Required for LoRa radio access
-    readonly_root: false  # Needs write access for device management
-    no_new_privileges: true
-    user: 1000
-    seccomp_profile: default
-    network_policy: host  # Requires host network for radio access
-    apparmor_profile: meshtastic
-    
-  ports:
-    - host: 4403
-      container: 4403
-      protocol: tcp  # Meshtastic TCP API
-    
-  devices:
-    - /dev/ttyUSB0  # LoRa radio device (if connected)
-    
-  volumes:
-    - type: bind
-      source: /var/lib/archipelago/meshtastic
-      target: /var/lib/meshtasticd
-      options: [rw]
-
-  files:
-    - path: /var/lib/archipelago/meshtastic/config.yaml
-      content: |
-        General:
-          MACAddress: AA:BB:CC:DD:EE:01
-        Webserver:
-          Port: 4403
-      
-  environment:
-    - MESHTASTIC_PORT=/dev/ttyUSB0
-    - MESHTASTIC_SERIAL=true
-    
-  health_check:
-    type: cmd
-    endpoint: test -f /var/lib/meshtasticd/config.yaml
-    interval: 30s
-    timeout: 30s
-    retries: 5
-    
-  networking:
-    mesh_enabled: true
-    local_network_access: true
-
-  metadata:
-    icon: /assets/img/app-icons/meshcore.svg
-    category: networking
-    tier: recommended
-    repo: https://github.com/meshtastic/firmware

apps/netbird-dashboard/manifest.yml

@@ -0,0 +1,77 @@
+app:
+  id: netbird-dashboard
+  name: NetBird Dashboard
+  version: "2.38.0"
+  description: NetBird management dashboard (SPA). Internal stack member served through the netbird proxy.
+  category: networking
+
+  # Hyphen name matches runtime references + the live container (adoption).
+  # Alias `netbird-dashboard` is the short hostname the proxy's nginx proxies to.
+  container_name: netbird-dashboard
+
+  container:
+    image: docker.io/netbirdio/dashboard:v2.38.0
+    pull_policy: if-not-present
+    network: netbird-net
+    network_aliases: [netbird-dashboard]
+    # The dashboard SPA bakes its API/OIDC base URL from these at container
+    # start. They must point at the proxy's public HTTPS origin (8087) so the
+    # browser uses a secure context (window.crypto.subtle / OIDC PKCE, #15).
+    # {{HOST_IP}} is the node's primary host IP, resolved at apply time.
+    derived_env:
+      - key: NETBIRD_MGMT_API_ENDPOINT
+        template: "https://{{HOST_IP}}:8087"
+      - key: NETBIRD_MGMT_GRPC_API_ENDPOINT
+        template: "https://{{HOST_IP}}:8087"
+      - key: AUTH_AUTHORITY
+        template: "https://{{HOST_IP}}:8087/oauth2"
+
+  dependencies:
+    - app_id: netbird-server
+
+  resources:
+    memory_limit: 256Mi
+
+  security:
+    # cap-drop=ALL is applied by the orchestrator. The dashboard image runs
+    # nginx (master as root, drops workers) binding :80 — needs the worker-drop
+    # caps + NET_BIND_SERVICE for the privileged port.
+    capabilities: [CHOWN, DAC_OVERRIDE, SETGID, SETUID, NET_BIND_SERVICE]
+    readonly_root: false
+    network_policy: isolated
+
+  # Internal only — reached container-to-container by the proxy via netbird-net.
+  ports: []
+
+  volumes: []
+
+  environment:
+    - AUTH_AUDIENCE=netbird-dashboard
+    - AUTH_CLIENT_ID=netbird-dashboard
+    - AUTH_CLIENT_SECRET=
+    - USE_AUTH0=false
+    - AUTH_SUPPORTED_SCOPES=openid profile email groups
+    - AUTH_REDIRECT_URI=/nb-auth
+    - AUTH_SILENT_REDIRECT_URI=/nb-silent-auth
+    - NETBIRD_TOKEN_SOURCE=idToken
+    - NGINX_SSL_PORT=443
+    - LETSENCRYPT_DOMAIN=none
+
+  health_check:
+    type: tcp
+    endpoint: localhost:80
+    interval: 30s
+    timeout: 5s
+    retries: 5
+    start_period: 20s
+
+  metadata:
+    author: NetBird
+    icon: /assets/img/app-icons/netbird.svg
+    website: https://netbird.io
+    repo: https://github.com/netbirdio/dashboard
+    license: BSD-3-Clause
+    tags:
+      - networking
+      - vpn
+      - dashboard

apps/netbird-server/manifest.yml

@@ -0,0 +1,122 @@
+app:
+  id: netbird-server
+  name: NetBird Server
+  version: "0.71.2"
+  description: NetBird combined management / signal / relay server with an embedded identity provider and STUN. Backend for the self-hosted NetBird mesh VPN.
+  category: networking
+
+  # Hyphen name matches the runtime references (crash_recovery / dependencies /
+  # config startup order) + the live container, so on an existing node the
+  # orchestrator ADOPTS the running server rather than recreating it (data +
+  # the sqlite store under /var/lib/netbird preserved). Alias `netbird-server`
+  # is the short hostname the proxy's nginx proxies/grpc-passes to.
+  container_name: netbird-server
+
+  container:
+    image: docker.io/netbirdio/netbird-server:0.71.2
+    pull_policy: if-not-present
+    network: netbird-net
+    network_aliases: [netbird-server]
+    # The relay authSecret and the sqlite store encryptionKey are base64 keys
+    # (the server base64-decodes them to recover raw bytes — hex would decode to
+    # the wrong value). Generated once and reused: ensure_generated_secrets
+    # no-ops when the file already exists, so a re-render of config.yaml on an
+    # adopted node keeps the same keys (regenerating would orphan the store).
+    generated_secrets:
+      - name: netbird-relay-auth-secret
+        kind: base64
+      - name: netbird-store-encryption-key
+        kind: base64
+    # Pass the rendered config explicitly, mirroring the legacy `--config` arg.
+    custom_args: ["--config", "/etc/netbird/config.yaml"]
+
+  dependencies:
+    - storage: 1Gi
+
+  resources:
+    memory_limit: 1Gi
+
+  security:
+    # cap-drop=ALL is applied by the orchestrator. The server binds :80
+    # (management/signal/relay HTTP + gRPC) inside the container — a privileged
+    # port — so it needs NET_BIND_SERVICE. STUN is 3478/udp (unprivileged).
+    capabilities: [NET_BIND_SERVICE]
+    readonly_root: false
+    network_policy: isolated
+
+  ports:
+    - host: 8086
+      container: 80
+      protocol: tcp   # management API + embedded OIDC issuer (/oauth2)
+    - host: 3478
+      container: 3478
+      protocol: udp   # STUN — must be UDP; tcp here breaks relay discovery
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/netbird/data
+      target: /var/lib/netbird
+      options: [rw]
+    # The rendered config.yaml, read-only. Re-rendered on every reconcile from
+    # host facts + the base64 secrets; idempotent (stable bytes → no restart).
+    - type: bind
+      source: /var/lib/archipelago/netbird/config.yaml
+      target: /etc/netbird/config.yaml
+      options: [ro]
+
+  environment: []
+
+  # The server's config. {{HOST_IP}} is the node's primary host IP (the proxy's
+  # public origin is https on 8087 — the dashboard needs a secure context for
+  # OIDC PKCE, issue #15). {{secret:...}} are read 0600 from the secrets dir.
+  files:
+    - path: /var/lib/archipelago/netbird/config.yaml
+      overwrite: true
+      content: |
+        server:
+          listenAddress: ":80"
+          exposedAddress: "https://{{HOST_IP}}:8087"
+          stunPorts:
+            - 3478
+          metricsPort: 9090
+          healthcheckAddress: ":9000"
+          logLevel: "info"
+          logFile: "console"
+          authSecret: "{{secret:netbird-relay-auth-secret}}"
+          dataDir: "/var/lib/netbird"
+          auth:
+            issuer: "https://{{HOST_IP}}:8087/oauth2"
+            localAuthDisabled: false
+            signKeyRefreshEnabled: false
+            dashboardRedirectURIs:
+              - "https://{{HOST_IP}}:8087/nb-auth"
+              - "https://{{HOST_IP}}:8087/nb-silent-auth"
+            dashboardPostLogoutRedirectURIs:
+              - "https://{{HOST_IP}}:8087/"
+            cliRedirectURIs:
+              - "http://localhost:53000/"
+          store:
+            engine: "sqlite"
+            encryptionKey: "{{secret:netbird-store-encryption-key}}"
+
+  # TCP liveness on the management port. Binds at startup, stays green; an http
+  # check of /oauth2 would false-fail while the issuer warms up.
+  health_check:
+    type: tcp
+    endpoint: localhost:80
+    interval: 30s
+    timeout: 5s
+    retries: 10
+    start_period: 30s
+
+  metadata:
+    author: NetBird
+    icon: /assets/img/app-icons/netbird.svg
+    website: https://netbird.io
+    repo: https://github.com/netbirdio/netbird
+    license: BSD-3-Clause
+    tags:
+      - networking
+      - vpn
+      - wireguard
+      - mesh

apps/netbird/manifest.yml

@@ -0,0 +1,182 @@
+app:
+  id: netbird
+  name: NetBird
+  version: "2.38.0"
+  description: Self-hosted WireGuard mesh VPN control plane with dashboard, embedded identity provider, management API, signal, relay, and STUN. The user-facing entry point — a TLS proxy in front of the dashboard + server.
+  category: networking
+
+  # The user-facing launcher (app_id + container both "netbird", matching the
+  # runtime references + the live container so the orchestrator adopts it). This
+  # is the nginx that terminates TLS on 8087 and fans out to the dashboard +
+  # server by their short aliases on netbird-net.
+  container_name: netbird
+
+  container:
+    image: docker.io/library/nginx:1.27-alpine
+    pull_policy: if-not-present
+    network: netbird-net
+    # Self-signed TLS cert materialised before create — the dashboard needs a
+    # secure context (window.crypto.subtle / OIDC PKCE, issue #15), so the proxy
+    # serves HTTPS. Idempotent: kept as-is when crt+key already exist (a user
+    # accepts it once). SAN defaults to the host IP + 127.0.0.1 + localhost.
+    generated_certs:
+      - crt: /var/lib/archipelago/netbird/tls.crt
+        key: /var/lib/archipelago/netbird/tls.key
+
+  dependencies:
+    - app_id: netbird-server
+    - app_id: netbird-dashboard
+    - storage: 1Gi
+
+  resources:
+    memory_limit: 256Mi
+
+  security:
+    # cap-drop=ALL is applied by the orchestrator. nginx (master as root, drops
+    # workers) binds :443 — needs the worker-drop caps + NET_BIND_SERVICE.
+    capabilities: [CHOWN, DAC_OVERRIDE, SETGID, SETUID, NET_BIND_SERVICE]
+    readonly_root: false
+    network_policy: isolated
+
+  ports:
+    # 8087 publishes the TLS listener (container :443). HTTPS is required for the
+    # dashboard's secure context (issue #15).
+    - host: 8087
+      container: 443
+      protocol: tcp
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/netbird/nginx.conf
+      target: /etc/nginx/conf.d/default.conf
+      options: [ro]
+    - type: bind
+      source: /var/lib/archipelago/netbird/tls.crt
+      target: /etc/nginx/tls.crt
+      options: [ro]
+    - type: bind
+      source: /var/lib/archipelago/netbird/tls.key
+      target: /etc/nginx/tls.key
+      options: [ro]
+
+  environment: []
+
+  # The proxy config. {{NETWORK_GATEWAY}} is the netbird-net bridge gateway =
+  # Podman's aardvark DNS. nginx uses it as an explicit `resolver` with VARIABLE
+  # upstreams so it re-resolves container names per request — without it nginx
+  # pins a container IP at startup and 502s forever once that IP moves on a
+  # restart/reboot (issue #15, observed live on .198). Every #15 fix below
+  # (CORS $http_origin reflect, grpc pass, nb-auth/nb-silent-auth rewrite to
+  # index.html, /relay websocket) is preserved verbatim from the legacy config.
+  files:
+    - path: /var/lib/archipelago/netbird/nginx.conf
+      overwrite: true
+      content: |
+        server {
+            listen 443 ssl;
+            server_name _;
+
+            # netbird's dashboard needs a secure context (window.crypto.subtle for
+            # OIDC PKCE), so the proxy terminates TLS with a self-signed cert (#15).
+            ssl_certificate /etc/nginx/tls.crt;
+            ssl_certificate_key /etc/nginx/tls.key;
+
+            # Rootless Podman can hand a container a new IP across restarts/reboots.
+            # nginx resolves a literal upstream name ONCE at startup and caches it,
+            # so after the IP moves every request 502s with "host unreachable"
+            # (issue #15, observed live on .198: nginx pinned to a dead
+            # netbird-dashboard IP). Fix: point `resolver` at the netbird-net
+            # gateway (Podman's aardvark DNS) and use VARIABLE upstreams, which
+            # forces nginx to re-resolve the container names at request time.
+            resolver {{NETWORK_GATEWAY}} valid=10s ipv6=off;
+
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+            proxy_http_version 1.1;
+
+            location ~ ^/(relay|ws-proxy/) {
+                set $nb_server netbird-server;
+                proxy_pass http://$nb_server:80;
+                proxy_set_header Upgrade $http_upgrade;
+                proxy_set_header Connection "upgrade";
+                proxy_read_timeout 1d;
+            }
+
+            location ~ ^/(api|oauth2)(/|$) {
+                # The dashboard is a SPA whose API/OIDC base URL is baked at build
+                # time to one host:port. A single box is reached via several
+                # addresses, so those fetches are cross-origin and the browser
+                # blocks them with no Access-Control-Allow-Origin (#15, live on
+                # .198). Reflect the caller's Origin and answer the CORS preflight.
+                if ($request_method = OPTIONS) {
+                    add_header Access-Control-Allow-Origin $http_origin always;
+                    add_header Access-Control-Allow-Credentials true always;
+                    add_header Access-Control-Allow-Methods "GET, POST, PUT, PATCH, DELETE, OPTIONS" always;
+                    add_header Access-Control-Allow-Headers "Authorization, Content-Type, Accept" always;
+                    add_header Access-Control-Max-Age 86400 always;
+                    add_header Content-Length 0;
+                    return 204;
+                }
+                add_header Access-Control-Allow-Origin $http_origin always;
+                add_header Access-Control-Allow-Credentials true always;
+                add_header Access-Control-Allow-Methods "GET, POST, PUT, PATCH, DELETE, OPTIONS" always;
+                add_header Access-Control-Allow-Headers "Authorization, Content-Type, Accept" always;
+                set $nb_server netbird-server;
+                proxy_pass http://$nb_server:80;
+            }
+
+            location ~ ^/(signalexchange\.SignalExchange|management\.ManagementService|management\.ProxyService)/ {
+                set $nb_server netbird-server;
+                grpc_pass grpc://$nb_server:80;
+                grpc_read_timeout 1d;
+                grpc_send_timeout 1d;
+            }
+
+            # OIDC callback routes are client-side SPA routes with NO prebuilt page
+            # in the dashboard bundle, so proxying them straight through 404s —
+            # which crashes the dashboard's auth init and shows "Unauthenticated"
+            # with dead buttons (#15, live on .198: /nb-auth + /nb-silent-auth
+            # returned 404). Serve index.html at these paths (URL unchanged) so
+            # react-oidc boots and completes the login / silent-SSO.
+            location ~ ^/(nb-auth|nb-silent-auth) {
+                set $nb_dashboard netbird-dashboard;
+                rewrite ^.*$ /index.html break;
+                proxy_pass http://$nb_dashboard:80;
+            }
+
+            location / {
+                set $nb_dashboard netbird-dashboard;
+                proxy_pass http://$nb_dashboard:80;
+            }
+        }
+
+  health_check:
+    type: tcp
+    endpoint: localhost:443
+    interval: 30s
+    timeout: 5s
+    retries: 5
+    start_period: 20s
+
+  interfaces:
+    main:
+      name: Dashboard
+      description: Manage your self-hosted NetBird mesh VPN
+      type: ui
+      port: 8087
+      protocol: https
+      path: /
+
+  metadata:
+    author: NetBird
+    icon: /assets/img/app-icons/netbird.svg
+    website: https://netbird.io
+    repo: https://github.com/netbirdio/netbird
+    license: BSD-3-Clause
+    tags:
+      - networking
+      - vpn
+      - wireguard
+      - mesh

core/archipelago/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "archipelago"
-version = "1.7.89-alpha"
+version = "1.7.99-alpha"
 edition = "2021"
 description = "Archipelago Bitcoin Node OS - Native backend"
 authors = ["Archipelago Team"]
@@ -9,6 +9,16 @@ authors = ["Archipelago Team"]
 name = "archipelago"
 path = "src/main.rs"
 
+[features]
+default = []
+# DHT Phase 2: iroh-blobs peer swarm engine. OFF by default — it pulls a heavy
+# QUIC dependency tree, so it ships behind a flag for PoC/measurement on a
+# scratch node before any fleet rollout. With the flag off, swarm::providers()
+# is empty and every fetch goes straight to the origin HTTP path (today's
+# behaviour). Attach the optional iroh / iroh-blobs deps to this feature when
+# wiring the IrohProvider.
+iroh-swarm = ["dep:iroh", "dep:iroh-blobs"]
+
 [dependencies]
 # Core dependencies
 tokio = { version = "1", features = ["full"] }
@@ -42,6 +52,7 @@ archipelago-performance = { path = "../performance" }
 # Authentication
 bcrypt = "0.15"
 sha2 = "0.10.9"
+blake3 = "1"
 hmac = "0.12.1"
 uuid = { version = "1.0", features = ["v4"] }
 regex = "1.10"
@@ -64,7 +75,7 @@ serde_yaml = "0.9"
 
 # HTTP client (for LND REST proxy, Tor SOCKS for peer messaging)
 # Uses rustls-tls for cross-compilation (no OpenSSL dependency)
-reqwest = { version = "0.11", default-features = false, features = ["json", "socks", "rustls-tls"] }
+reqwest = { version = "0.11", default-features = false, features = ["json", "socks", "rustls-tls", "stream"] }
 
 # Nostr (node discovery + NIP-44 encrypted peer handshake)
 nostr-sdk = { version = "0.44", features = ["nip04", "nip44"] }
@@ -106,6 +117,12 @@ sd-notify = "0.4"
 # Trait objects for async methods (container orchestrator trait, Step 4)
 async-trait = "0.1"
 
+# DHT Phase 2: iroh-blobs peer swarm engine. OPTIONAL — only pulled in by the
+# `iroh-swarm` feature (off by default). Heavy QUIC dep tree; kept behind the
+# flag so the default fleet build is unaffected until the PoC is measured.
+iroh = { version = "1", optional = true }
+iroh-blobs = { version = "0.103", optional = true }
+
 [dev-dependencies]
 tokio-test = "0.4"
 tempfile = "3.10"

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

@@ -66,6 +66,21 @@ impl ApiHandler {
             .and_then(|v| v.to_str().ok())
             .map(|s| s.to_string());
 
+        // Extract a paid-entitlement gate token from X-Invoice-Hash (Lightning)
+        // or X-Onchain-Address (on-chain) — both authorize the download if this
+        // node issued+settled them, and both resolve against the same shared
+        // entitlement store keyed by the token string (#46).
+        let invoice_hash = headers
+            .get("x-invoice-hash")
+            .and_then(|v| v.to_str().ok())
+            .map(|s| s.to_string())
+            .or_else(|| {
+                headers
+                    .get("x-onchain-address")
+                    .and_then(|v| v.to_str().ok())
+                    .map(|s| s.to_string())
+            });
+
         // Extract federation peer DID from X-Federation-DID header
         let peer_did = headers
             .get("x-federation-did")
@@ -82,6 +97,7 @@ impl ApiHandler {
             &config.data_dir,
             content_id,
             payment_token.as_deref(),
+            invoice_hash.as_deref(),
             peer_did.as_deref(),
             range,
         )
@@ -130,7 +146,9 @@ impl ApiHandler {
             Ok(content_server::ServeResult::Forbidden) => Ok(build_response(
                 StatusCode::FORBIDDEN,
                 "application/json",
-                hyper::Body::from(r#"{"error":"Access denied — federation peer required"}"#),
+                hyper::Body::from(
+                    r#"{"error":"This file is shared with the host's federation peers only. Federate with that node (exchange invites) so it recognizes you, then try again."}"#,
+                ),
             )),
             Ok(content_server::ServeResult::NotFound) | Err(_) => Ok(build_response(
                 StatusCode::NOT_FOUND,
@@ -140,6 +158,259 @@ impl ApiHandler {
         }
     }
 
+    /// Seller side (#46): mint a Lightning invoice for a paid catalog item so a
+    /// buyer can pay from any external wallet. Path: GET /content/{id}/invoice.
+    /// Records a pending entitlement keyed by the invoice's payment hash.
+    pub(super) async fn handle_content_invoice(&self, path: &str) -> Result<Response<hyper::Body>> {
+        let content_id = path
+            .strip_prefix("/content/")
+            .and_then(|s| s.strip_suffix("/invoice"))
+            .unwrap_or("");
+        if content_id.is_empty() || !is_valid_app_id(content_id) {
+            return Ok(build_response(
+                StatusCode::BAD_REQUEST,
+                "text/plain",
+                hyper::Body::from("Invalid content ID"),
+            ));
+        }
+
+        let catalog = content_server::load_catalog(&self.config.data_dir)
+            .await
+            .unwrap_or_default();
+        let item = match catalog.items.iter().find(|i| i.id == content_id) {
+            Some(i) => i,
+            None => {
+                return Ok(build_response(
+                    StatusCode::NOT_FOUND,
+                    "text/plain",
+                    hyper::Body::from("Content not found"),
+                ))
+            }
+        };
+        let price_sats = match &item.access {
+            content_server::AccessControl::Paid { price_sats } => *price_sats,
+            _ => {
+                // Not a paid item — no invoice to issue.
+                return Ok(build_response(
+                    StatusCode::BAD_REQUEST,
+                    "application/json",
+                    hyper::Body::from(r#"{"error":"Item is not paid"}"#),
+                ));
+            }
+        };
+
+        let memo = format!("Archipelago peer file {content_id}");
+        match self
+            .rpc_handler
+            .create_invoice(price_sats as i64, &memo)
+            .await
+        {
+            Ok((bolt11, payment_hash)) if !payment_hash.is_empty() => {
+                crate::content_invoice::record_pending(&payment_hash, content_id, price_sats).await;
+                let body = serde_json::json!({
+                    "bolt11": bolt11,
+                    "payment_hash": payment_hash,
+                    "price_sats": price_sats,
+                });
+                Ok(build_response(
+                    StatusCode::OK,
+                    "application/json",
+                    hyper::Body::from(serde_json::to_vec(&body).unwrap_or_default()),
+                ))
+            }
+            Ok(_) => Ok(build_response(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "application/json",
+                hyper::Body::from(r#"{"error":"Invoice missing payment hash"}"#),
+            )),
+            Err(e) => {
+                // Surface the FULL error chain ({:#}) — the generic top-level
+                // message hid the real cause (e.g. the LND REST connection
+                // failing), which made this 503 undiagnosable.
+                tracing::warn!("content invoice creation failed: {e:#}");
+                let body = serde_json::json!({
+                    "error": format!("Could not create invoice: {e:#}")
+                });
+                Ok(build_response(
+                    StatusCode::SERVICE_UNAVAILABLE,
+                    "application/json",
+                    hyper::Body::from(serde_json::to_vec(&body).unwrap_or_default()),
+                ))
+            }
+        }
+    }
+
+    /// Seller side (#46): report whether a previously-issued invoice has settled.
+    /// Path: GET /content/{id}/invoice-status/{payment_hash}. On settlement the
+    /// entitlement is marked paid so the buyer can then download the file.
+    pub(super) async fn handle_content_invoice_status(
+        &self,
+        path: &str,
+    ) -> Result<Response<hyper::Body>> {
+        let rest = path.strip_prefix("/content/").unwrap_or("");
+        let (content_id, payment_hash) = match rest.split_once("/invoice-status/") {
+            Some((id, hash)) => (id, hash),
+            None => {
+                return Ok(build_response(
+                    StatusCode::BAD_REQUEST,
+                    "text/plain",
+                    hyper::Body::from("Invalid request"),
+                ))
+            }
+        };
+        if content_id.is_empty() || !is_valid_app_id(content_id) || payment_hash.is_empty() {
+            return Ok(build_response(
+                StatusCode::BAD_REQUEST,
+                "text/plain",
+                hyper::Body::from("Invalid request"),
+            ));
+        }
+
+        // The hash must be one we issued for exactly this content item.
+        match crate::content_invoice::lookup(payment_hash).await {
+            Some((cid, _)) if cid == content_id => {}
+            _ => {
+                return Ok(build_response(
+                    StatusCode::NOT_FOUND,
+                    "application/json",
+                    hyper::Body::from(r#"{"error":"Unknown invoice"}"#),
+                ))
+            }
+        }
+
+        // Already paid? Otherwise ask our LND and persist the result.
+        let mut paid = crate::content_invoice::is_paid_for(payment_hash, content_id).await;
+        if !paid {
+            if let Ok(true) = self.rpc_handler.invoice_is_settled(payment_hash).await {
+                crate::content_invoice::mark_paid(payment_hash).await;
+                paid = true;
+            }
+        }
+
+        let body = serde_json::json!({ "paid": paid });
+        Ok(build_response(
+            StatusCode::OK,
+            "application/json",
+            hyper::Body::from(serde_json::to_vec(&body).unwrap_or_default()),
+        ))
+    }
+
+    /// Seller side (#46): issue a fresh on-chain address for a paid catalog item
+    /// so a buyer can pay on-chain. Path: GET /content/{id}/onchain. Records a
+    /// pending entitlement keyed by the address; price doubles as expected amount.
+    pub(super) async fn handle_content_onchain(&self, path: &str) -> Result<Response<hyper::Body>> {
+        let content_id = path
+            .strip_prefix("/content/")
+            .and_then(|s| s.strip_suffix("/onchain"))
+            .unwrap_or("");
+        if content_id.is_empty() || !is_valid_app_id(content_id) {
+            return Ok(build_response(
+                StatusCode::BAD_REQUEST,
+                "text/plain",
+                hyper::Body::from("Invalid content ID"),
+            ));
+        }
+        let catalog = content_server::load_catalog(&self.config.data_dir)
+            .await
+            .unwrap_or_default();
+        let price_sats = match catalog.items.iter().find(|i| i.id == content_id) {
+            Some(i) => match &i.access {
+                content_server::AccessControl::Paid { price_sats } => *price_sats,
+                _ => {
+                    return Ok(build_response(
+                        StatusCode::BAD_REQUEST,
+                        "application/json",
+                        hyper::Body::from(r#"{"error":"Item is not paid"}"#),
+                    ))
+                }
+            },
+            None => {
+                return Ok(build_response(
+                    StatusCode::NOT_FOUND,
+                    "text/plain",
+                    hyper::Body::from("Content not found"),
+                ))
+            }
+        };
+
+        match self.rpc_handler.new_onchain_address().await {
+            Ok(address) if !address.is_empty() => {
+                crate::content_invoice::record_pending(&address, content_id, price_sats).await;
+                let body = serde_json::json!({
+                    "address": address,
+                    "amount_sats": price_sats,
+                });
+                Ok(build_response(
+                    StatusCode::OK,
+                    "application/json",
+                    hyper::Body::from(serde_json::to_vec(&body).unwrap_or_default()),
+                ))
+            }
+            _ => {
+                let body = serde_json::json!({
+                    "error": "Could not generate an on-chain address (is the wallet ready?)"
+                });
+                Ok(build_response(
+                    StatusCode::SERVICE_UNAVAILABLE,
+                    "application/json",
+                    hyper::Body::from(serde_json::to_vec(&body).unwrap_or_default()),
+                ))
+            }
+        }
+    }
+
+    /// Seller side (#46): report whether an on-chain payment to a previously-
+    /// issued address has arrived (>= price, >= 1 conf). Path:
+    /// GET /content/{id}/onchain-status/{address}. Marks the entitlement paid.
+    pub(super) async fn handle_content_onchain_status(
+        &self,
+        path: &str,
+    ) -> Result<Response<hyper::Body>> {
+        let rest = path.strip_prefix("/content/").unwrap_or("");
+        let (content_id, address) = match rest.split_once("/onchain-status/") {
+            Some((id, addr)) => (id, addr),
+            None => {
+                return Ok(build_response(
+                    StatusCode::BAD_REQUEST,
+                    "text/plain",
+                    hyper::Body::from("Invalid request"),
+                ))
+            }
+        };
+        if content_id.is_empty() || !is_valid_app_id(content_id) || address.is_empty() {
+            return Ok(build_response(
+                StatusCode::BAD_REQUEST,
+                "text/plain",
+                hyper::Body::from("Invalid request"),
+            ));
+        }
+        // The address must be one we issued for exactly this content item.
+        let price = match crate::content_invoice::lookup(address).await {
+            Some((cid, price)) if cid == content_id => price,
+            _ => {
+                return Ok(build_response(
+                    StatusCode::NOT_FOUND,
+                    "application/json",
+                    hyper::Body::from(r#"{"error":"Unknown address"}"#),
+                ))
+            }
+        };
+
+        let mut paid = crate::content_invoice::is_paid_for(address, content_id).await;
+        if !paid {
+            if let Ok(true) = self.rpc_handler.onchain_received(address, price).await {
+                crate::content_invoice::mark_paid(address).await;
+                paid = true;
+            }
+        }
+        let body = serde_json::json!({ "paid": paid });
+        Ok(build_response(
+            StatusCode::OK,
+            "application/json",
+            hyper::Body::from(serde_json::to_vec(&body).unwrap_or_default()),
+        ))
+    }
+
     /// Serve a degraded preview of paid content (blurred image or first 2% of video).
     pub(super) async fn handle_content_preview(
         path: &str,
@@ -190,6 +461,14 @@ impl ApiHandler {
                     .body(hyper::Body::from(bytes))
                     .unwrap())
             }
+            Ok(content_server::PreviewResult::PreviewUnavailable) => Ok(Response::builder()
+                .status(StatusCode::UNSUPPORTED_MEDIA_TYPE)
+                .header("Content-Type", "text/plain")
+                .header("X-Content-Preview", "unavailable")
+                .body(hyper::Body::from(
+                    "Preview unavailable for this media (needs re-encoding)",
+                ))
+                .unwrap()),
             Ok(content_server::PreviewResult::NotFound) | Err(_) => Ok(build_response(
                 StatusCode::NOT_FOUND,
                 "text/plain",

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

@@ -44,6 +44,11 @@ pub struct ApiHandler {
     session_store: SessionStore,
     /// Broadcast channel for relaying companion app input to remote browsers.
     input_relay_tx: broadcast::Sender<String>,
+    /// Reverse broadcast channel: the kiosk browser publishes "open this URL
+    /// externally" requests here, and the companion (phone) socket forwards them
+    /// to the phone's default browser. Lets "open in external browser" apps —
+    /// which the kiosk can't usefully open itself — launch on the controller.
+    external_open_tx: broadcast::Sender<String>,
     /// Content-addressed blob store for attachments shared over mesh/federation.
     blob_store: Arc<BlobStore>,
     /// Our own node pubkey (hex) — used to self-sign debug/test capabilities.
@@ -71,6 +76,7 @@ impl ApiHandler {
             .await?,
         );
         let (input_relay_tx, _) = broadcast::channel(64);
+        let (external_open_tx, _) = broadcast::channel(16);
 
         // Derive a blob-store capability key from the node's Ed25519 signing
         // key. SHA-256 domain-separated so rotating the identity rotates
@@ -100,6 +106,7 @@ impl ApiHandler {
             metrics_store,
             session_store,
             input_relay_tx,
+            external_open_tx,
             blob_store,
             self_pubkey_hex,
         })
@@ -202,6 +209,27 @@ impl ApiHandler {
             .unwrap()
     }
 
+    /// A 401 that still carries CORS headers, for endpoints fetched
+    /// cross-origin by same-node app UIs (e.g. the LND wallet UI on its own
+    /// port). Without the ACAO header the browser surfaces an opaque CORS
+    /// error instead of the 401, so the app can't tell it just needs auth.
+    /// `origin` is the already-validated reflect value from `app_cors_origin`
+    /// (empty string when the origin isn't allowed → no CORS header added).
+    fn unauthorized_cors(origin: &str) -> Response<hyper::Body> {
+        let body = serde_json::json!({ "error": "Unauthorized" });
+        let body_bytes = serde_json::to_vec(&body).unwrap_or_default();
+        let mut builder = Response::builder()
+            .status(StatusCode::UNAUTHORIZED)
+            .header("Content-Type", "application/json")
+            .header("Vary", "Origin");
+        if !origin.is_empty() {
+            builder = builder
+                .header("Access-Control-Allow-Origin", origin)
+                .header("Access-Control-Allow-Credentials", "true");
+        }
+        builder.body(hyper::Body::from(body_bytes)).unwrap()
+    }
+
     /// Allowed CORS origins derived from the config host IP.
     fn allowed_origins(&self) -> Vec<String> {
         let mut origins = vec![
@@ -256,6 +284,45 @@ impl ApiHandler {
         }
     }
 
+    /// CORS origin to echo for same-node app → backend calls (e.g. the LND
+    /// wallet UI, served on its own APP_PORTS port). Such apps share the node's
+    /// host but use a different port, so the strict allowlist (`host_ip`, no
+    /// port) rejects them and the browser gets no `Access-Control-Allow-Origin`
+    /// header ("blocked by CORS policy"). Reflect the Origin when its host
+    /// matches the request's own `Host` header — i.e. the app lives on the same
+    /// address the node is being reached by, which transparently covers the LAN
+    /// IP, the Tailscale IP, localhost, and the `.onion` address without needing
+    /// to enumerate them. Auth is still enforced by the session cookie; this
+    /// only authorizes the browser to *read* the reply. Returns "" (no echoed
+    /// origin) when there is no match.
+    fn app_cors_origin(&self, headers: &hyper::HeaderMap) -> String {
+        if let Some(origin) = self.validate_origin(headers) {
+            return origin;
+        }
+        let Some(origin) = headers.get("origin").and_then(|v| v.to_str().ok()) else {
+            return String::new();
+        };
+        // host portion (no scheme, no port) of an `scheme://host[:port]` value
+        let host_of = |s: &str| -> Option<String> {
+            let after_scheme = s.split_once("://").map(|(_, r)| r).unwrap_or(s);
+            let host_port = after_scheme.split('/').next().unwrap_or(after_scheme);
+            let host = host_port
+                .rsplit_once(':')
+                .map(|(h, _)| h)
+                .unwrap_or(host_port);
+            (!host.is_empty()).then(|| host.to_string())
+        };
+        let origin_host = host_of(origin);
+        let req_host = headers
+            .get(hyper::header::HOST)
+            .and_then(|v| v.to_str().ok())
+            .and_then(host_of);
+        match (origin_host, req_host) {
+            (Some(o), Some(r)) if o == r => origin.to_string(),
+            _ => String::new(),
+        }
+    }
+
     pub async fn handle_request(&self, req: Request<hyper::Body>) -> Result<Response<hyper::Body>> {
         let path = req.uri().path().to_string();
         let method = req.method().clone();
@@ -265,9 +332,10 @@ impl ApiHandler {
             let mut builder = Response::builder()
                 .status(StatusCode::NO_CONTENT)
                 .header("Vary", "Origin");
-            if let Some(origin) = self.validate_origin(req.headers()) {
+            let preflight_origin = self.app_cors_origin(req.headers());
+            if !preflight_origin.is_empty() {
                 builder = builder
-                    .header("Access-Control-Allow-Origin", &origin)
+                    .header("Access-Control-Allow-Origin", &preflight_origin)
                     .header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
                     .header("Access-Control-Allow-Headers", "Content-Type, X-CSRF-Token")
                     .header("Access-Control-Allow-Credentials", "true");
@@ -295,7 +363,12 @@ impl ApiHandler {
                 tracing::warn!("401 WebSocket /ws/remote-input — session invalid or missing");
                 return Ok(Self::unauthorized());
             }
-            return Self::handle_remote_input(req, self.input_relay_tx.clone()).await;
+            return Self::handle_remote_input(
+                req,
+                self.input_relay_tx.clone(),
+                self.external_open_tx.subscribe(),
+            )
+            .await;
         }
 
         // Remote relay WebSocket — browser receives companion input events
@@ -304,7 +377,12 @@ impl ApiHandler {
                 tracing::warn!("401 WebSocket /ws/remote-relay — session invalid or missing");
                 return Ok(Self::unauthorized());
             }
-            return Self::handle_remote_relay(req, self.input_relay_tx.subscribe()).await;
+            return Self::handle_remote_relay(
+                req,
+                self.input_relay_tx.subscribe(),
+                self.external_open_tx.clone(),
+            )
+            .await;
         }
 
         // Convert body to bytes for non-WS routes
@@ -419,6 +497,22 @@ impl ApiHandler {
                 Self::handle_content_preview(p, &self.config).await
             }
 
+            // Lightning-invoice peer-file sale (#46): mint invoice / poll settlement
+            (Method::GET, p) if p.starts_with("/content/") && p.ends_with("/invoice") => {
+                self.handle_content_invoice(p).await
+            }
+            (Method::GET, p) if p.starts_with("/content/") && p.contains("/invoice-status/") => {
+                self.handle_content_invoice_status(p).await
+            }
+
+            // On-chain peer-file sale (#46): issue address / poll for payment
+            (Method::GET, p) if p.starts_with("/content/") && p.contains("/onchain-status/") => {
+                self.handle_content_onchain_status(p).await
+            }
+            (Method::GET, p) if p.starts_with("/content/") && p.ends_with("/onchain") => {
+                self.handle_content_onchain(p).await
+            }
+
             // Content serving — peers access shared content over Tor (no session auth)
             (Method::GET, p) if p.starts_with("/content/") => {
                 Self::handle_content_request(p, &headers, &self.config).await
@@ -448,7 +542,8 @@ impl ApiHandler {
             // No backend auth check here because the LND UI iframe fetches this
             // endpoint and the session cookie flow is validated at the nginx layer.
             (Method::GET, "/lnd-connect-info") => {
-                Self::handle_lnd_connect_info(self.rpc_handler.clone()).await
+                let origin = self.app_cors_origin(&headers);
+                Self::handle_lnd_connect_info(self.rpc_handler.clone(), &origin).await
             }
 
             // Container logs — requires session
@@ -460,13 +555,26 @@ impl ApiHandler {
                 Self::handle_container_logs_http(self.rpc_handler.clone(), path, &origin).await
             }
 
-            // LND proxy — requires session
-            (Method::GET, path) if path.starts_with("/proxy/lnd/") => {
+            // Peer content streaming proxy — Range-streams a peer's media file
+            // so <video>/<audio> can seek/play (B3). Same-origin, session-gated.
+            (Method::GET, p) if p.starts_with("/api/peer-content/") => {
                 if !self.is_authenticated(&headers).await {
                     return Ok(Self::unauthorized());
                 }
-                let origin = self.validate_origin(&headers).unwrap_or_default();
-                Self::handle_lnd_proxy(path, &origin).await
+                self.handle_peer_content_stream(p, &headers).await
+            }
+
+            // LND proxy — requires session. The LND wallet UI calls this
+            // cross-origin from its own app port, so even the 401 must carry
+            // CORS headers; otherwise the browser reports a bare CORS failure
+            // ("No 'Access-Control-Allow-Origin' header") instead of a
+            // readable 401 the UI can act on.
+            (Method::GET, path) if path.starts_with("/proxy/lnd/") => {
+                let origin = self.app_cors_origin(&headers);
+                if !self.is_authenticated(&headers).await {
+                    return Ok(Self::unauthorized_cors(&origin));
+                }
+                Self::handle_lnd_proxy(self.rpc_handler.clone(), path, &origin).await
             }
 
             // DWN health — unauthenticated

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

@@ -19,6 +19,8 @@ impl ApiHandler {
             signature: Option<String>,
             #[serde(default)]
             encrypted: bool,
+            #[serde(default)]
+            msg_id: Option<String>,
         }
         let incoming: Incoming = serde_json::from_slice(&body).unwrap_or(Incoming {
             from_pubkey: None,
@@ -26,6 +28,7 @@ impl ApiHandler {
             message: None,
             signature: None,
             encrypted: false,
+            msg_id: None,
         });
         if let (Some(from), Some(msg)) = (incoming.from_pubkey.as_ref(), incoming.message.as_ref())
         {
@@ -152,7 +155,13 @@ impl ApiHandler {
             let clean_from = sanitize_html(from);
             let clean_msg = sanitize_html(&plaintext);
             let clean_name = incoming.from_name.as_deref().map(sanitize_html);
-            node_msg::store_received(&clean_from, &clean_msg, clean_name.as_deref()).await;
+            node_msg::store_received(
+                &clean_from,
+                &clean_msg,
+                clean_name.as_deref(),
+                incoming.msg_id.as_deref(),
+            )
+            .await;
         }
         Ok(build_response(
             StatusCode::OK,

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

@@ -99,33 +99,61 @@ impl ApiHandler {
 
     pub(super) async fn handle_lnd_connect_info(
         rpc: std::sync::Arc<super::super::rpc::RpcHandler>,
+        cors_origin: &str,
     ) -> Result<Response<hyper::Body>> {
+        // The LND wallet UI is served on its own APP_PORTS origin and fetches
+        // this cross-origin, so it needs the CORS headers echoed back.
+        let cors = |builder: hyper::http::response::Builder| {
+            builder
+                .header("Access-Control-Allow-Origin", cors_origin)
+                .header("Access-Control-Allow-Credentials", "true")
+                .header("Vary", "Origin")
+        };
         match rpc.handle_lnd_connect_info().await {
             Ok(val) => {
                 let body = serde_json::to_vec(&val).unwrap_or_default();
-                Ok(build_response(
-                    StatusCode::OK,
-                    "application/json",
-                    hyper::Body::from(body),
-                ))
+                Ok(cors(
+                    Response::builder()
+                        .status(StatusCode::OK)
+                        .header("Content-Type", "application/json"),
+                )
+                .body(hyper::Body::from(body))
+                .unwrap_or_else(|_| Response::new(hyper::Body::from("{}"))))
             }
-            Err(e) => Ok(Response::builder()
-                .status(StatusCode::INTERNAL_SERVER_ERROR)
-                .header("Content-Type", "application/json")
-                .body(hyper::Body::from(
-                    serde_json::json!({"error": e.to_string()}).to_string(),
-                ))
-                .unwrap()),
+            Err(e) => Ok(cors(
+                Response::builder()
+                    .status(StatusCode::INTERNAL_SERVER_ERROR)
+                    .header("Content-Type", "application/json"),
+            )
+            .body(hyper::Body::from(
+                serde_json::json!({"error": e.to_string()}).to_string(),
+            ))
+            .unwrap()),
         }
     }
 
     pub(super) async fn handle_lnd_proxy(
+        rpc: Arc<RpcHandler>,
         path: &str,
         cors_origin: &str,
     ) -> Result<Response<hyper::Body>> {
         let suffix = path.strip_prefix("/proxy/lnd").unwrap_or("/");
         let url = format!("{LND_REST_BASE_URL}{suffix}");
-        match reqwest::get(&url).await {
+        // LND REST serves a self-signed cert and requires the admin macaroon.
+        // A bare reqwest::get() uses the default client, which rejects the
+        // self-signed cert (TLS verify error -> 502 "failing to fetch") and
+        // sends no macaroon. Use the shared authenticated client instead — the
+        // same one lnd.getinfo and the wallet RPCs use.
+        let request = match rpc.lnd_client().await {
+            Ok((client, macaroon_hex)) => client
+                .get(&url)
+                .header("Grpc-Metadata-macaroon", &macaroon_hex)
+                .send()
+                .await
+                .map_err(anyhow::Error::from),
+            Err(e) => Err(e),
+        };
+        match request {
             Ok(resp) => {
                 let status = resp.status().as_u16();
                 let headers = resp.headers().clone();
@@ -157,4 +185,84 @@ impl ApiHandler {
             }
         }
     }
+
+    /// Range-streaming proxy for a peer's content file (B3). The browser's
+    /// `<video>`/`<audio>` element makes Range requests; we forward the Range
+    /// header to the peer's `/content/<id>` (which already returns 206 Partial
+    /// Content) and pass the bytes + Content-Range/Content-Type straight back.
+    /// This replaces the old path of downloading the whole file as base64 into
+    /// a non-seekable Blob URL, which broke playback/seeking for video and
+    /// large audio. Same-origin + session-authenticated (checked by caller).
+    /// Path: `/api/peer-content/<onion>/<content_id>`.
+    pub(super) async fn handle_peer_content_stream(
+        &self,
+        path: &str,
+        headers: &hyper::HeaderMap,
+    ) -> Result<Response<hyper::Body>> {
+        let bad = |msg: &str| {
+            Ok(build_response(
+                StatusCode::BAD_REQUEST,
+                "application/json",
+                hyper::Body::from(serde_json::json!({ "error": msg }).to_string()),
+            ))
+        };
+        let rest = path.strip_prefix("/api/peer-content/").unwrap_or("");
+        let (onion, content_id) = match rest.split_once('/') {
+            Some((o, c)) if !o.is_empty() && !c.is_empty() => (o, c),
+            _ => return bad("expected /api/peer-content/<onion>/<content_id>"),
+        };
+        // Validate to prevent SSRF / path traversal.
+        let onion_norm = onion.trim_end_matches(".onion");
+        let onion_ok = onion_norm.len() == 56
+            && onion_norm
+                .bytes()
+                .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit());
+        let id_ok = !content_id.contains("..")
+            && content_id
+                .bytes()
+                .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.'));
+        if !onion_ok || !id_ok {
+            return bad("invalid onion or content id");
+        }
+
+        let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
+        let peer_path = format!("/content/{}", content_id);
+        // Generous overall timeout: this endpoint serves both seek/Range
+        // playback (small, finishes fast) and full-file downloads of large
+        // media (#38). 60s was too tight for a multi-hundred-MB transfer over
+        // Tor and aborted the download mid-stream.
+        let mut req = crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, &peer_path)
+            .service(crate::settings::transport::PeerService::PeerFiles)
+            .timeout(std::time::Duration::from_secs(900));
+        if let Some(r) = headers.get("range").and_then(|v| v.to_str().ok()) {
+            req = req.header("Range", r.to_string());
+        }
+        match req.send_get().await {
+            Ok((resp, _transport)) => {
+                let status = resp.status().as_u16();
+                let rh = resp.headers().clone();
+                let mut builder = Response::builder()
+                    .status(status)
+                    .header("Accept-Ranges", "bytes");
+                for h in ["content-type", "content-range", "content-length"] {
+                    if let Some(v) = rh.get(h).and_then(|v| v.to_str().ok()) {
+                        builder = builder.header(h, v);
+                    }
+                }
+                // Stream the peer's body straight through instead of buffering
+                // the whole file into memory (#38). For a 178MB download the old
+                // `resp.bytes().await` allocated the entire file on the node
+                // before sending a byte; `wrap_stream` forwards chunks as they
+                // arrive, with constant memory.
+                Ok(builder
+                    .body(hyper::Body::wrap_stream(resp.bytes_stream()))
+                    .unwrap_or_else(|_| Response::new(hyper::Body::empty())))
+            }
+            Err(e) => Ok(build_response(
+                StatusCode::BAD_GATEWAY,
+                "application/json",
+                hyper::Body::from(serde_json::json!({ "error": e.to_string() }).to_string()),
+            )),
+        }
+    }
 }

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

@@ -211,6 +211,7 @@ impl ApiHandler {
     pub(super) async fn handle_remote_input(
         req: Request<hyper::Body>,
         relay_tx: broadcast::Sender<String>,
+        mut external_open_rx: broadcast::Receiver<String>,
     ) -> Result<Response<hyper::Body>> {
         // Extract optional player ID from query string: /ws/remote-input?p=1
         let player_id: Option<u8> = req
@@ -266,6 +267,19 @@ impl ApiHandler {
                                 break;
                             }
                         }
+                        // Forward kiosk "open this URL externally" requests down to
+                        // the companion so the link opens in the phone's browser.
+                        ext = external_open_rx.recv() => {
+                            match ext {
+                                Ok(text) => {
+                                    if tx.send(Message::Text(text)).await.is_err() {
+                                        break;
+                                    }
+                                }
+                                Err(broadcast::error::RecvError::Lagged(_)) => {}
+                                Err(broadcast::error::RecvError::Closed) => {}
+                            }
+                        }
                         msg = rx.next() => {
                             match msg {
                                 Some(Ok(Message::Text(text))) => {

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

@@ -11,9 +11,16 @@ use super::ApiHandler;
 impl ApiHandler {
     /// WebSocket endpoint for browser clients to receive relayed companion input.
     /// The browser's remote-relay.ts dispatches these as DOM keyboard/mouse events.
+    ///
+    /// The kiosk also uses this socket in the *reverse* direction: when an "open
+    /// in external browser" app is launched, the kiosk can't usefully open it
+    /// itself, so it sends `{"t":"o","url":"https://…"}` here. We validate the
+    /// URL and publish it on `external_open_tx`, which the companion (phone)
+    /// socket forwards so the link opens in the phone's default browser.
     pub(super) async fn handle_remote_relay(
         req: Request<hyper::Body>,
         mut relay_rx: broadcast::Receiver<String>,
+        external_open_tx: broadcast::Sender<String>,
     ) -> Result<Response<hyper::Body>> {
         let (response, ws_fut_opt) = hyper_ws_listener::create_ws(req)
             .map_err(|e| anyhow::anyhow!("WebSocket upgrade failed: {}", e))?;
@@ -63,10 +70,20 @@ impl ApiHandler {
                                 Err(broadcast::error::RecvError::Closed) => break,
                             }
                         }
-                        // Handle client-side messages (pong, close)
+                        // Handle client-side messages (pong, close, open-url requests)
                         client_msg = rx.next() => {
                             match client_msg {
                                 Some(Ok(Message::Pong(_))) | Some(Ok(Message::Ping(_))) => {}
+                                Some(Ok(Message::Text(text))) => {
+                                    // The only kiosk→server message we accept is an
+                                    // external-open request: {"t":"o","url":"https://…"}.
+                                    if let Some(url) = parse_open_url(&text) {
+                                        debug!("Relaying external-open to companion: {}", url);
+                                        let _ = external_open_tx.send(
+                                            format!(r#"{{"t":"o","url":{}}}"#, json_string(&url))
+                                        );
+                                    }
+                                }
                                 Some(Ok(Message::Close(_))) | None => break,
                                 _ => {}
                             }
@@ -81,3 +98,29 @@ impl ApiHandler {
         Ok(response)
     }
 }
+
+/// Parse a kiosk `{"t":"o","url":"…"}` external-open request, returning the URL
+/// only if it's a well-formed http(s) URL. Anything else (other message tags,
+/// non-http schemes like `javascript:`/`file:`, malformed JSON) is rejected so a
+/// compromised kiosk page can't push arbitrary URIs to the phone.
+fn parse_open_url(text: &str) -> Option<String> {
+    let v: serde_json::Value = serde_json::from_str(text).ok()?;
+    if v.get("t").and_then(|t| t.as_str()) != Some("o") {
+        return None;
+    }
+    let url = v.get("url").and_then(|u| u.as_str())?.trim();
+    if url.len() > 2048 {
+        return None;
+    }
+    let lower = url.to_ascii_lowercase();
+    if lower.starts_with("http://") || lower.starts_with("https://") {
+        Some(url.to_string())
+    } else {
+        None
+    }
+}
+
+/// Serialize a string as a JSON string literal (with surrounding quotes).
+fn json_string(s: &str) -> String {
+    serde_json::Value::String(s.to_string()).to_string()
+}

core/archipelago/src/api/mod.rs

@@ -1,4 +1,4 @@
 mod handler;
-mod rpc;
+pub(crate) mod rpc;
 
 pub use handler::ApiHandler;

core/archipelago/src/api/rpc/auth.rs

@@ -33,6 +33,19 @@ impl RpcHandler {
 
         tracing::info!("[onboarding] login successful");
 
+        // Best-effort: heal a LOCKED LND wallet created with an unknown/legacy
+        // password by rotating it onto the per-node secret, using the password
+        // the user just authenticated with as a candidate. Non-blocking so login
+        // is never slowed or broken when LND isn't installed / already unlocked.
+        let candidate = password.to_string();
+        tokio::spawn(async move {
+            match crate::container::lnd::migrate_locked_wallet(&[candidate]).await {
+                Ok(true) => tracing::info!("[login] LND wallet healed / auto-unlocked"),
+                Ok(false) => {} // not locked, or seed-recovery required
+                Err(e) => tracing::debug!("[login] LND wallet migration skipped: {e}"),
+            }
+        });
+
         // Ensure NostrVPN config exists — covers the case where onboardingComplete
         // was never called (e.g., user took the "already set up" shortcut).
         let data_dir = self.config.data_dir.clone();

core/archipelago/src/api/rpc/bitcoin_relay.rs

@@ -107,7 +107,7 @@ struct TrustedRelayPeer {
 }
 
 #[derive(Debug, Clone)]
-struct TxRelayCredentials {
+pub(crate) struct TxRelayCredentials {
     username: String,
     password: String,
 }
@@ -648,7 +648,13 @@ async fn txrelay_credentials_available(data_dir: &Path) -> bool {
         && fs::metadata(&client_env_path).await.is_ok()
 }
 
-async fn ensure_txrelay_credentials(data_dir: &Path) -> Result<TxRelayCredentials> {
+/// Idempotently ensure the tx-relay credential trio exists in the secrets dir:
+/// the random password, its derived `rpcauth` line, and the client env file.
+/// Bitcoin backend manifests reference `bitcoin-rpc-txrelay-rpcauth` as a
+/// required `secret_env`, so this must run before bitcoind starts — otherwise
+/// secret resolution hard-fails and the whole Bitcoin stack cascades (the .198
+/// failure). Safe to call repeatedly; it only writes what's missing or stale.
+pub(crate) async fn ensure_txrelay_credentials(data_dir: &Path) -> Result<TxRelayCredentials> {
     let (password_path, rpcauth_path, client_env_path) = txrelay_secret_paths(data_dir);
     let password = match read_trimmed(&password_path).await {
         Some(value) => value,

core/archipelago/src/api/rpc/container.rs

@@ -171,6 +171,13 @@ impl RpcHandler {
         // than the WebSocket-delivered package_data, which caused apps to flicker
         // between "installed" and "not-installed" in the UI.
         let (data, _) = self.state_manager.get_snapshot().await;
+        // Apps the user explicitly stopped must read as "stopped" even though a
+        // UI companion (electrs-ui, bitcoin-ui, …) keeps serving the launch port:
+        // launch_port_reachable() below would otherwise upgrade an exited backend
+        // back to "running". The reconcile guard keeps these backends down, so the
+        // marker is authoritative here.
+        let user_stopped =
+            crate::crash_recovery::load_user_stopped(&self.config.data_dir).await;
         if data.server_info.status_info.containers_scanned && !data.package_data.is_empty() {
             let mut containers = Vec::with_capacity(data.package_data.len());
             for (id, pkg) in &data.package_data {
@@ -202,7 +209,11 @@ impl RpcHandler {
                 // Scanner backoff preserves cached package_data. Refresh stable
                 // states so callers do not see stale `running`/`exited` after
                 // health-monitor recovery or Quadlet --rm container removal.
-                if state == "running" && requires_launch_port_for_health(id) {
+                if user_stopped.contains(id) {
+                    // User stopped it → authoritative "stopped". Do NOT let a
+                    // still-running UI companion's launch port mark it running.
+                    state = "stopped".to_string();
+                } else if state == "running" && requires_launch_port_for_health(id) {
                     if !self.cached_reachable_health(id).await?.is_some() {
                         state = live_state_for_app(id)
                             .await

core/archipelago/src/api/rpc/content.rs

@@ -19,6 +19,29 @@ fn is_valid_v3_onion(addr: &str) -> bool {
 
 const FILE_CATALOG_PROTOCOL: &str = "https://archipelago.dev/protocols/file-catalog/v1";
 
+/// Best-effort reclaim of an ecash payment token that was minted but the sale
+/// didn't complete (seller unreachable or couldn't redeem it), so the buyer
+/// doesn't lose the value. For Fedimint the spender can reissue its own
+/// un-redeemed notes; for Cashu the proofs are received back. Fails silently if
+/// the seller already claimed the token (then the value is genuinely gone).
+async fn reclaim_spent_ecash(data_dir: &std::path::Path, token: &str, backend: &str) {
+    let res = match backend {
+        "fedimint" => crate::wallet::fedimint_client::reissue_into_any(data_dir, token)
+            .await
+            .map(|(sats, _fed)| sats),
+        _ => ecash::receive_token(data_dir, token).await,
+    };
+    match res {
+        Ok(sats) => tracing::info!(
+            "paid download: reclaimed {sats} sats of unspent {backend} ecash after a failed sale"
+        ),
+        Err(e) => tracing::warn!(
+            "paid download: could not reclaim {backend} ecash (the peer may have already \
+             claimed it): {e:#}"
+        ),
+    }
+}
+
 impl RpcHandler {
     /// List content I'm sharing.
     pub(super) async fn handle_content_list_mine(&self) -> Result<serde_json::Value> {
@@ -234,7 +257,7 @@ impl RpcHandler {
         let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
 
         let path = format!("/content/{}", content_id);
-        let (response, _transport) =
+        let (response, transport) =
             crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, &path)
                 .service(crate::settings::transport::PeerService::PeerFiles)
                 .header("X-Federation-DID", local_did)
@@ -242,6 +265,15 @@ impl RpcHandler {
                 .send_get()
                 .await
                 .context("Failed to connect to peer")?;
+        // Record which transport actually reached the peer (B14) so the UI
+        // reflects FIPS vs Tor truthfully instead of always showing Tor/none.
+        let _ = crate::federation::record_peer_transport(
+            &self.config.data_dir,
+            None,
+            Some(onion),
+            &transport.to_string(),
+        )
+        .await;
 
         if response.status() == reqwest::StatusCode::PAYMENT_REQUIRED {
             let body: serde_json::Value = response.json().await.unwrap_or_default();
@@ -251,6 +283,20 @@ impl RpcHandler {
             }));
         }
 
+        // A 403 carries an actionable reason in its JSON body (e.g. "shared with
+        // the host's federation peers only — federate first"). Surface that to
+        // the user instead of a bare "Peer returned: 403 Forbidden".
+        if response.status() == reqwest::StatusCode::FORBIDDEN {
+            let status = response.status();
+            let body: serde_json::Value = response.json().await.unwrap_or_default();
+            let msg = body
+                .get("error")
+                .and_then(|v| v.as_str())
+                .map(|s| s.to_string())
+                .unwrap_or_else(|| format!("Peer returned: {status}"));
+            return Err(anyhow::anyhow!(msg));
+        }
+
         if !response.status().is_success() {
             return Err(anyhow::anyhow!("Peer returned: {}", response.status()));
         }
@@ -294,13 +340,21 @@ impl RpcHandler {
             fips_npub.is_some()
         );
 
-        let (response, _transport) =
+        let (response, transport) =
             crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, "/content")
                 .service(crate::settings::transport::PeerService::PeerFiles)
                 .timeout(std::time::Duration::from_secs(30))
                 .send_get()
                 .await
                 .context("Failed to connect to peer")?;
+        // Record which transport actually reached the peer (B14).
+        let _ = crate::federation::record_peer_transport(
+            &self.config.data_dir,
+            None,
+            Some(onion),
+            &transport.to_string(),
+        )
+        .await;
 
         if !response.status().is_success() {
             return Err(anyhow::anyhow!(
@@ -309,11 +363,20 @@ impl RpcHandler {
             ));
         }
 
-        let body: serde_json::Value = response
+        let mut body: serde_json::Value = response
             .json()
             .await
             .context("Failed to parse peer catalog")?;
 
+        // Surface the transport that actually reached the peer so the cloud
+        // browse UI can show a FIPS/Tor pill instead of always assuming Tor (B21).
+        if let Some(obj) = body.as_object_mut() {
+            obj.insert(
+                "transport".to_string(),
+                serde_json::Value::String(transport.to_string()),
+            );
+        }
+
         Ok(body)
     }
 
@@ -343,49 +406,573 @@ impl RpcHandler {
             return Err(anyhow::anyhow!("Invalid v3 onion address"));
         }
 
-        // Mint ecash payment token
-        let token_str = ecash::send_token(&self.config.data_dir, price_sats)
-            .await
-            .context("Failed to create ecash payment token — check wallet balance")?;
+        // `method` pins the backend the user confirmed in the UI ("cashu" |
+        // "fedimint"); absent = auto (Cashu first, then Fedimint). The seller's
+        // verify_payment_token accepts either, so a node whose balance lives in
+        // one system can still pay (#3).
+        let method = params.get("method").and_then(|v| v.as_str());
+
+        let mint_cashu = || ecash::send_token(&self.config.data_dir, price_sats);
+        let mint_fedimint =
+            || crate::wallet::fedimint_client::spend_from_any(&self.config.data_dir, price_sats);
+
+        let (token_str, used_backend) = match method {
+            Some("cashu") => match mint_cashu().await {
+                Ok(t) => (t, "cashu"),
+                Err(e) => {
+                    tracing::warn!("paid download: cashu mint failed for {price_sats} sats: {e:#}");
+                    return Ok(serde_json::json!({ "error": format!(
+                        "Couldn't pay {price_sats} sats from your Cashu wallet: {e}. \
+                         Fund it, or choose Fedimint."
+                    ) }));
+                }
+            },
+            Some("fedimint") => match mint_fedimint().await {
+                Ok((notes, fed)) => {
+                    tracing::info!("paid download: spending {price_sats} sats Fedimint notes from {fed}");
+                    (notes, "fedimint")
+                }
+                Err(e) => {
+                    tracing::warn!("paid download: fedimint spend failed for {price_sats} sats: {e:#}");
+                    return Ok(serde_json::json!({ "error": format!(
+                        "Couldn't pay {price_sats} sats from your Fedimint wallet: {e}. \
+                         Fund it, or choose Cashu."
+                    ) }));
+                }
+            },
+            _ => match mint_cashu().await {
+                Ok(t) => (t, "cashu"),
+                Err(cashu_err) => match mint_fedimint().await {
+                    Ok((notes, _fed)) => (notes, "fedimint"),
+                    Err(fedi_err) => {
+                        tracing::warn!(
+                            "paid download: no ecash backend could pay {price_sats} sats \
+                             (cashu: {cashu_err:#}; fedimint: {fedi_err:#})"
+                        );
+                        return Ok(serde_json::json!({ "error": format!(
+                            "Couldn't pay {price_sats} sats from your ecash wallet \
+                             (Cashu or Fedimint). Fund either wallet and try again."
+                        ) }));
+                    }
+                },
+            },
+        };
+        tracing::info!("paid download: paying {price_sats} sats to {onion} via {used_backend} ecash");
 
         let (data, _) = self.state_manager.get_snapshot().await;
         let local_did = crate::identity::did_key_from_pubkey_hex(&data.server_info.pubkey)?;
         let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
 
         let path = format!("/content/{}", content_id);
-        let (response, _transport) =
-            crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, &path)
-                .service(crate::settings::transport::PeerService::PeerFiles)
-                .header("X-Federation-DID", local_did)
-                .header("X-Payment-Token", token_str)
-                .timeout(std::time::Duration::from_secs(120))
-                .send_get()
-                .await
-                .context("Failed to connect to peer")?;
+        // Surface a real reason instead of the generic sanitized error (#30):
+        // the dial already tries FIPS/mesh then falls back to Tor, so a failure
+        // here means the peer is genuinely unreachable on both transports.
+        let (response, transport) = match crate::fips::dial::PeerRequest::new(
+            fips_npub.as_deref(),
+            onion,
+            &path,
+        )
+        .service(crate::settings::transport::PeerService::PeerFiles)
+        .header("X-Federation-DID", local_did)
+        .header("X-Payment-Token", token_str.clone())
+        .timeout(std::time::Duration::from_secs(900))
+        .send_get()
+        .await
+        {
+            Ok(v) => v,
+            Err(e) => {
+                tracing::warn!("paid peer download dial failed for {}: {:#}", onion, e);
+                // The token was already minted/spent — reclaim it so the buyer
+                // doesn't lose the value when the seller was simply unreachable.
+                reclaim_spent_ecash(&self.config.data_dir, &token_str, used_backend).await;
+                return Ok(serde_json::json!({
+                    "error": "Could not reach the peer over mesh or Tor — it may be offline. Your ecash was refunded to your wallet. Please try again."
+                }));
+            }
+        };
+        // Record which transport actually reached the peer (B14).
+        let _ = crate::federation::record_peer_transport(
+            &self.config.data_dir,
+            None,
+            Some(onion),
+            &transport.to_string(),
+        )
+        .await;
 
         if response.status() == reqwest::StatusCode::PAYMENT_REQUIRED {
-            // Payment was rejected — token is spent but content not received
-            return Err(anyhow::anyhow!(
-                "Payment rejected by peer — token may have been insufficient or invalid"
-            ));
+            // Payment was rejected by the seller. Surface the most likely cause
+            // per backend — for ecash both sides must share a redemption network
+            // (a Cashu mint, or a Fedimint federation).
+            let body = response.text().await.unwrap_or_default();
+            tracing::warn!(
+                "paid download: seller {onion} rejected {used_backend} payment of {price_sats} sats: {body}"
+            );
+            // Seller couldn't redeem the token — reclaim it so the buyer keeps
+            // their funds (the spent-but-unredeemed-notes case the user hit).
+            reclaim_spent_ecash(&self.config.data_dir, &token_str, used_backend).await;
+            let hint = match used_backend {
+                "fedimint" => "the seller isn't in the same Fedimint federation as you",
+                _ => "the seller doesn't accept your Cashu mint",
+            };
+            return Ok(serde_json::json!({
+                "error": format!(
+                    "Payment rejected by the seller — {hint}. Your ecash was refunded to \
+                     your wallet. Try the other ecash type, or use a shared mint/federation."
+                )
+            }));
         }
 
         if !response.status().is_success() {
-            return Err(anyhow::anyhow!("Peer returned: {}", response.status()));
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            tracing::warn!("paid download: seller {onion} returned {status}: {body}");
+            reclaim_spent_ecash(&self.config.data_dir, &token_str, used_backend).await;
+            return Ok(serde_json::json!({
+                "error": format!("Peer returned an error ({status}). Your ecash was refunded to your wallet.")
+            }));
         }
 
+        // Capture the content type BEFORE consuming the body so the local cache
+        // can render the right viewer (image vs video) later.
+        let mime_type = response
+            .headers()
+            .get(reqwest::header::CONTENT_TYPE)
+            .and_then(|v| v.to_str().ok())
+            .map(|s| s.split(';').next().unwrap_or(s).trim().to_string())
+            .filter(|s| !s.is_empty())
+            .unwrap_or_else(|| "application/octet-stream".to_string());
+
         let bytes = response
             .bytes()
             .await
             .context("Failed to read response body")?;
 
+        // Persist the purchase so it "stays unlocked" for this buyer: cache the
+        // bytes + metadata keyed by (onion, content_id). The gallery then renders
+        // it unblurred and views it in-app from this cache — no re-payment and no
+        // reliance on a browser download (which silently fails on the mobile
+        // companion, the original "paid but never unlocked" report). Best-effort:
+        // a cache-write failure must not fail an already-paid download.
+        let filename = params
+            .get("filename")
+            .and_then(|v| v.as_str())
+            .unwrap_or(content_id)
+            .to_string();
+        let purchased_at = chrono::Utc::now().to_rfc3339();
+        if let Err(e) = crate::content_owned::record_purchase(
+            &self.config.data_dir,
+            onion,
+            content_id,
+            &filename,
+            &mime_type,
+            &bytes,
+            price_sats,
+            used_backend,
+            &purchased_at,
+        )
+        .await
+        {
+            tracing::warn!("paid download: failed to cache purchased content (non-fatal): {e:#}");
+        }
+
         use base64::Engine;
         let encoded = base64::engine::general_purpose::STANDARD.encode(&bytes);
 
+        tracing::info!("paid download: received {} bytes from {onion} (paid {price_sats} sats via {used_backend})", bytes.len());
         Ok(serde_json::json!({
             "data": encoded,
             "size": bytes.len(),
             "paid_sats": price_sats,
+            "ecash_backend": used_backend,
+            "mime_type": mime_type,
+            "owned": true,
+        }))
+    }
+
+    /// Buyer side (#46): ask the selling node to mint a Lightning invoice for a
+    /// paid item so the buyer can pay from any external wallet. Returns the
+    /// bolt11 invoice + payment hash to render as a QR and poll for settlement.
+    pub(super) async fn handle_content_request_invoice(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let onion = params
+            .get("onion")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing onion address"))?;
+        let content_id = params
+            .get("content_id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing content_id"))?;
+        if !is_valid_v3_onion(onion) {
+            return Err(anyhow::anyhow!("Invalid v3 onion address"));
+        }
+
+        let (data, _) = self.state_manager.get_snapshot().await;
+        let local_did = crate::identity::did_key_from_pubkey_hex(&data.server_info.pubkey)?;
+        let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
+
+        // Minting a bolt11 is a tiny request/response — keep it snappy. Cap the
+        // FIPS attempt hard so a cold overlay can't burn the whole budget, and
+        // give Tor a short-but-real window (onion circuits need a few seconds).
+        let path = format!("/content/{}/invoice", content_id);
+        let (response, _transport) =
+            match crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, &path)
+                .service(crate::settings::transport::PeerService::PeerFiles)
+                .header("X-Federation-DID", local_did)
+                .timeout(std::time::Duration::from_secs(25))
+                .fips_timeout(std::time::Duration::from_secs(6))
+                .send_get()
+                .await
+            {
+                Ok(v) => v,
+                Err(e) => {
+                    tracing::warn!("request-invoice dial failed for {}: {:#}", onion, e);
+                    return Ok(serde_json::json!({
+                        "error": "Could not reach the peer over mesh or Tor — it may be offline."
+                    }));
+                }
+            };
+
+        if !response.status().is_success() {
+            return Ok(serde_json::json!({
+                "error": format!("Seller could not create an invoice ({}).", response.status())
+            }));
+        }
+        let body: serde_json::Value = response
+            .json()
+            .await
+            .context("Failed to parse invoice response")?;
+        Ok(body)
+    }
+
+    /// Buyer side (#46): poll the selling node for invoice settlement.
+    pub(super) async fn handle_content_invoice_status(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let onion = params
+            .get("onion")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing onion address"))?;
+        let content_id = params
+            .get("content_id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing content_id"))?;
+        let payment_hash = params
+            .get("payment_hash")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing payment_hash"))?;
+        if !is_valid_v3_onion(onion) {
+            return Err(anyhow::anyhow!("Invalid v3 onion address"));
+        }
+        // Payment hash is hex from the seller; keep it strictly hex so it's safe
+        // to interpolate into the request path.
+        if payment_hash.is_empty()
+            || payment_hash.len() > 128
+            || !payment_hash.chars().all(|c| c.is_ascii_hexdigit())
+        {
+            return Err(anyhow::anyhow!("Invalid payment_hash"));
+        }
+
+        let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
+        // Settlement poll — runs repeatedly, so each call must be quick. Fast-fail
+        // FIPS and keep a short Tor window; an unreachable peer just reads as
+        // "not yet paid" and the UI polls again.
+        let path = format!("/content/{}/invoice-status/{}", content_id, payment_hash);
+        let (response, _transport) =
+            match crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, &path)
+                .service(crate::settings::transport::PeerService::PeerFiles)
+                .timeout(std::time::Duration::from_secs(15))
+                .fips_timeout(std::time::Duration::from_secs(6))
+                .send_get()
+                .await
+            {
+                Ok(v) => v,
+                Err(_) => {
+                    // Treat an unreachable peer as "not yet paid" so the UI keeps polling.
+                    return Ok(serde_json::json!({ "paid": false, "unreachable": true }));
+                }
+            };
+        if !response.status().is_success() {
+            return Ok(serde_json::json!({ "paid": false }));
+        }
+        let body: serde_json::Value = response
+            .json()
+            .await
+            .context("Failed to parse invoice-status response")?;
+        Ok(body)
+    }
+
+    /// Buyer side (#46): download a paid item after the invoice settled, passing
+    /// the payment hash so the seller's content gate releases the file.
+    pub(super) async fn handle_content_download_peer_invoice(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let onion = params
+            .get("onion")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing onion address"))?;
+        let content_id = params
+            .get("content_id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing content_id"))?;
+        let payment_hash = params
+            .get("payment_hash")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing payment_hash"))?;
+        if !is_valid_v3_onion(onion) {
+            return Err(anyhow::anyhow!("Invalid v3 onion address"));
+        }
+        if payment_hash.is_empty() || !payment_hash.chars().all(|c| c.is_ascii_hexdigit()) {
+            return Err(anyhow::anyhow!("Invalid payment_hash"));
+        }
+
+        let (data, _) = self.state_manager.get_snapshot().await;
+        let local_did = crate::identity::did_key_from_pubkey_hex(&data.server_info.pubkey)?;
+        let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
+
+        let path = format!("/content/{}", content_id);
+        let (response, transport) = match crate::fips::dial::PeerRequest::new(
+            fips_npub.as_deref(),
+            onion,
+            &path,
+        )
+        .service(crate::settings::transport::PeerService::PeerFiles)
+        .header("X-Federation-DID", local_did)
+        .header("X-Invoice-Hash", payment_hash.to_string())
+        .timeout(std::time::Duration::from_secs(900))
+        .send_get()
+        .await
+        {
+            Ok(v) => v,
+            Err(e) => {
+                tracing::warn!("invoice download dial failed for {}: {:#}", onion, e);
+                return Ok(serde_json::json!({
+                    "error": "Could not reach the peer over mesh or Tor — it may be offline. Please try again."
+                }));
+            }
+        };
+        let _ = crate::federation::record_peer_transport(
+            &self.config.data_dir,
+            None,
+            Some(onion),
+            &transport.to_string(),
+        )
+        .await;
+
+        if response.status() == reqwest::StatusCode::PAYMENT_REQUIRED {
+            return Ok(serde_json::json!({
+                "error": "Seller has not registered this payment yet — wait for settlement and retry."
+            }));
+        }
+        if !response.status().is_success() {
+            return Ok(serde_json::json!({
+                "error": format!("Peer returned an error ({}).", response.status())
+            }));
+        }
+
+        let bytes = response
+            .bytes()
+            .await
+            .context("Failed to read response body")?;
+        use base64::Engine;
+        let encoded = base64::engine::general_purpose::STANDARD.encode(&bytes);
+        Ok(serde_json::json!({
+            "data": encoded,
+            "size": bytes.len(),
+        }))
+    }
+
+    /// Buyer side (#46): ask the seller for a fresh on-chain address to pay.
+    pub(super) async fn handle_content_request_onchain(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let onion = params
+            .get("onion")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing onion address"))?;
+        let content_id = params
+            .get("content_id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing content_id"))?;
+        if !is_valid_v3_onion(onion) {
+            return Err(anyhow::anyhow!("Invalid v3 onion address"));
+        }
+
+        let (data, _) = self.state_manager.get_snapshot().await;
+        let local_did = crate::identity::did_key_from_pubkey_hex(&data.server_info.pubkey)?;
+        let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
+
+        // Issuing an address is a tiny request/response — fast-fail FIPS, short
+        // Tor window (same budget shape as the invoice path, #6).
+        let path = format!("/content/{}/onchain", content_id);
+        let (response, _transport) =
+            match crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, &path)
+                .service(crate::settings::transport::PeerService::PeerFiles)
+                .header("X-Federation-DID", local_did)
+                .timeout(std::time::Duration::from_secs(25))
+                .fips_timeout(std::time::Duration::from_secs(6))
+                .send_get()
+                .await
+            {
+                Ok(v) => v,
+                Err(e) => {
+                    tracing::warn!("request-onchain dial failed for {}: {:#}", onion, e);
+                    return Ok(serde_json::json!({
+                        "error": "Could not reach the peer over mesh or Tor — it may be offline."
+                    }));
+                }
+            };
+        if !response.status().is_success() {
+            return Ok(serde_json::json!({
+                "error": format!("Seller could not provide an address ({}).", response.status())
+            }));
+        }
+        let body: serde_json::Value = response
+            .json()
+            .await
+            .context("Failed to parse onchain response")?;
+        Ok(body)
+    }
+
+    /// Buyer side (#46): poll the selling node for on-chain payment detection.
+    pub(super) async fn handle_content_onchain_status(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let onion = params
+            .get("onion")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing onion address"))?;
+        let content_id = params
+            .get("content_id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing content_id"))?;
+        let address = params
+            .get("address")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing address"))?;
+        if !is_valid_v3_onion(onion) {
+            return Err(anyhow::anyhow!("Invalid v3 onion address"));
+        }
+        // Bitcoin addresses are alphanumeric; keep strictly so for safe path use.
+        if address.is_empty()
+            || address.len() > 100
+            || !address.chars().all(|c| c.is_ascii_alphanumeric())
+        {
+            return Err(anyhow::anyhow!("Invalid address"));
+        }
+
+        let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
+        let path = format!("/content/{}/onchain-status/{}", content_id, address);
+        let (response, _transport) =
+            match crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, &path)
+                .service(crate::settings::transport::PeerService::PeerFiles)
+                .timeout(std::time::Duration::from_secs(15))
+                .fips_timeout(std::time::Duration::from_secs(6))
+                .send_get()
+                .await
+            {
+                Ok(v) => v,
+                Err(_) => return Ok(serde_json::json!({ "paid": false, "unreachable": true })),
+            };
+        if !response.status().is_success() {
+            return Ok(serde_json::json!({ "paid": false }));
+        }
+        let body: serde_json::Value = response
+            .json()
+            .await
+            .context("Failed to parse onchain-status response")?;
+        Ok(body)
+    }
+
+    /// Buyer side (#46): download a paid item after the on-chain payment was
+    /// detected, passing the address so the seller's content gate releases it.
+    pub(super) async fn handle_content_download_peer_onchain(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let onion = params
+            .get("onion")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing onion address"))?;
+        let content_id = params
+            .get("content_id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing content_id"))?;
+        let address = params
+            .get("address")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing address"))?;
+        if !is_valid_v3_onion(onion) {
+            return Err(anyhow::anyhow!("Invalid v3 onion address"));
+        }
+        if address.is_empty() || !address.chars().all(|c| c.is_ascii_alphanumeric()) {
+            return Err(anyhow::anyhow!("Invalid address"));
+        }
+
+        let (data, _) = self.state_manager.get_snapshot().await;
+        let local_did = crate::identity::did_key_from_pubkey_hex(&data.server_info.pubkey)?;
+        let fips_npub = crate::federation::fips_npub_for_onion(&self.config.data_dir, onion).await;
+
+        let path = format!("/content/{}", content_id);
+        let (response, transport) = match crate::fips::dial::PeerRequest::new(
+            fips_npub.as_deref(),
+            onion,
+            &path,
+        )
+        .service(crate::settings::transport::PeerService::PeerFiles)
+        .header("X-Federation-DID", local_did)
+        .header("X-Onchain-Address", address.to_string())
+        .timeout(std::time::Duration::from_secs(900))
+        .send_get()
+        .await
+        {
+            Ok(v) => v,
+            Err(e) => {
+                tracing::warn!("onchain download dial failed for {}: {:#}", onion, e);
+                return Ok(serde_json::json!({
+                    "error": "Could not reach the peer over mesh or Tor — it may be offline. Please try again."
+                }));
+            }
+        };
+        let _ = crate::federation::record_peer_transport(
+            &self.config.data_dir,
+            None,
+            Some(onion),
+            &transport.to_string(),
+        )
+        .await;
+
+        if response.status() == reqwest::StatusCode::PAYMENT_REQUIRED {
+            return Ok(serde_json::json!({
+                "error": "Seller has not registered this payment yet — wait for confirmation and retry."
+            }));
+        }
+        if !response.status().is_success() {
+            return Ok(serde_json::json!({
+                "error": format!("Peer returned an error ({}).", response.status())
+            }));
+        }
+
+        let bytes = response
+            .bytes()
+            .await
+            .context("Failed to read response body")?;
+        use base64::Engine;
+        let encoded = base64::engine::general_purpose::STANDARD.encode(&bytes);
+        Ok(serde_json::json!({
+            "data": encoded,
+            "size": bytes.len(),
         }))
     }
 
@@ -418,13 +1005,21 @@ impl RpcHandler {
             fips_npub.is_some()
         );
 
-        let (response, _transport) =
+        let (response, transport) =
             crate::fips::dial::PeerRequest::new(fips_npub.as_deref(), onion, &path)
                 .service(crate::settings::transport::PeerService::PeerFiles)
                 .timeout(std::time::Duration::from_secs(30))
                 .send_get()
                 .await
                 .context("Failed to connect to peer for preview")?;
+        // Record which transport actually reached the peer (B14).
+        let _ = crate::federation::record_peer_transport(
+            &self.config.data_dir,
+            None,
+            Some(onion),
+            &transport.to_string(),
+        )
+        .await;
 
         if !response.status().is_success() {
             return Err(anyhow::anyhow!(
@@ -462,4 +1057,43 @@ impl RpcHandler {
             "preview_mode": is_preview,
         }))
     }
+
+    /// `content.owned-list` — every paid item this node has purchased, so the
+    /// gallery can render owned items unblurred/viewable without re-payment.
+    pub(super) async fn handle_content_owned_list(&self) -> Result<serde_json::Value> {
+        let items = crate::content_owned::list_owned(&self.config.data_dir).await;
+        Ok(serde_json::json!({ "items": items }))
+    }
+
+    /// `content.owned-get` — return a purchased item's bytes (base64) from the
+    /// local cache for in-app viewing/saving. No network, no re-payment.
+    pub(super) async fn handle_content_owned_get(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let onion = params
+            .get("onion")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing onion address"))?;
+        let content_id = params
+            .get("content_id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing content_id"))?;
+
+        match crate::content_owned::read_owned(&self.config.data_dir, onion, content_id).await {
+            Some((mime_type, bytes)) => {
+                use base64::Engine;
+                let encoded = base64::engine::general_purpose::STANDARD.encode(&bytes);
+                Ok(serde_json::json!({
+                    "data": encoded,
+                    "size": bytes.len(),
+                    "mime_type": mime_type,
+                }))
+            }
+            None => Ok(serde_json::json!({
+                "error": "You don't own this item yet, or its cached copy is missing."
+            })),
+        }
+    }
 }

core/archipelago/src/api/rpc/dispatcher.rs

@@ -33,6 +33,7 @@ impl RpcHandler {
             "seed.restore" => self.handle_seed_restore(params).await,
             "seed.save-encrypted" => self.handle_seed_save_encrypted(params).await,
             "seed.status" => self.handle_seed_status().await,
+            "seed.reveal" => self.handle_seed_reveal(params).await,
 
             // Container orchestration (for Archipelago-managed containers)
             "container-install" => self.handle_container_install(params).await,
@@ -55,6 +56,7 @@ impl RpcHandler {
             "package.restart" => self.handle_package_restart(params).await,
             "package.uninstall" => self.clone().spawn_package_uninstall(params).await,
             "package.update" => self.clone().spawn_package_update(params).await,
+            "package.check-updates" => self.handle_package_check_updates(params).await,
             "package.credentials" => self.handle_package_credentials(params).await,
             "app.filebrowser-token" => self.handle_filebrowser_token().await,
 
@@ -236,6 +238,11 @@ impl RpcHandler {
             "wallet.ecash-receive" => self.handle_wallet_ecash_receive(params).await,
             "wallet.ecash-history" => self.handle_wallet_ecash_history().await,
             "wallet.networking-profits" => self.handle_wallet_networking_profits().await,
+            // Fedimint ecash (via fedimint-clientd sidecar)
+            "wallet.fedimint-list" => self.handle_wallet_fedimint_list().await,
+            "wallet.fedimint-join" => self.handle_wallet_fedimint_join(params).await,
+            "wallet.fedimint-leave" => self.handle_wallet_fedimint_leave(params).await,
+            "wallet.fedimint-balance" => self.handle_wallet_fedimint_balance().await,
 
             // Container registries
             "registry.list" => self.handle_registry_list().await,
@@ -249,6 +256,7 @@ impl RpcHandler {
             "streaming.configure-service" => self.handle_streaming_configure_service(params).await,
             "streaming.toggle-service" => self.handle_streaming_toggle_service(params).await,
             "streaming.pay" => self.handle_streaming_pay(params).await,
+            "streaming.prepare-payment" => self.handle_streaming_prepare_payment(params).await,
             "streaming.discover" => self.handle_streaming_discover().await,
             "streaming.usage" => self.handle_streaming_usage(params).await,
             "streaming.session" => self.handle_streaming_session(params).await,
@@ -268,6 +276,18 @@ impl RpcHandler {
             "content.browse-peer" => self.handle_content_browse_peer(params).await,
             "content.download-peer" => self.handle_content_download_peer(params).await,
             "content.download-peer-paid" => self.handle_content_download_peer_paid(params).await,
+            "content.owned-list" => self.handle_content_owned_list().await,
+            "content.owned-get" => self.handle_content_owned_get(params).await,
+            "content.request-invoice" => self.handle_content_request_invoice(params).await,
+            "content.invoice-status" => self.handle_content_invoice_status(params).await,
+            "content.download-peer-invoice" => {
+                self.handle_content_download_peer_invoice(params).await
+            }
+            "content.request-onchain" => self.handle_content_request_onchain(params).await,
+            "content.onchain-status" => self.handle_content_onchain_status(params).await,
+            "content.download-peer-onchain" => {
+                self.handle_content_download_peer_onchain(params).await
+            }
             "content.preview-peer" => self.handle_content_preview_peer(params).await,
 
             // DWN (Decentralized Web Node)
@@ -379,6 +399,11 @@ impl RpcHandler {
             "mesh.deadman-status" => self.handle_mesh_deadman_status().await,
             "mesh.deadman-configure" => self.handle_mesh_deadman_configure(params).await,
             "mesh.deadman-checkin" => self.handle_mesh_deadman_checkin().await,
+            "mesh.assistant-status" => self.handle_mesh_assistant_status().await,
+            "mesh.assistant-configure" => self.handle_mesh_assistant_configure(params).await,
+            "mesh.schedule-message" => self.handle_mesh_schedule_message(params).await,
+            "mesh.list-scheduled" => self.handle_mesh_list_scheduled().await,
+            "mesh.cancel-scheduled" => self.handle_mesh_cancel_scheduled(params).await,
             "mesh.test-send" => self.handle_mesh_test_send(params).await,
 
             // Transport layer (unified routing)
@@ -470,6 +495,11 @@ impl RpcHandler {
                 let p = params.unwrap_or(serde_json::json!({}));
                 self.handle_update_test_mirror(&p).await
             }
+            "update.get-source" => self.handle_update_get_source().await,
+            "update.set-source" => {
+                let p = params.unwrap_or(serde_json::json!({}));
+                self.handle_update_set_source(&p).await
+            }
             "update.apply" => self.handle_update_apply().await,
             "update.git-apply" => self.handle_update_git_apply().await,
             "update.rollback" => self.handle_update_rollback().await,

core/archipelago/src/api/rpc/federation/handlers.rs

@@ -30,6 +30,25 @@ impl RpcHandler {
             mesh::upsert_federation_peer(&svc.shared_state(), pubkey_hex, did, name).await;
         }
     }
+
+    /// Re-seed every federation node from disk into the mesh peer table so the
+    /// chat list reflects what the latest federation sync learned — display
+    /// names (landed in `nodes.json` by `update_node_state` when a peer
+    /// announces its name) and transitively-discovered peers (merged by
+    /// `merge_transitive_peers`) — WITHOUT waiting for a mesh restart.
+    ///
+    /// Without this, a peer accepted via invite (seeded with `name = None`)
+    /// stays "Archipelago <pubkey8>" in chat until the next restart even after
+    /// sync has learned its real name, and transitive peers never appear as
+    /// chat contacts at all. `seed_federation_peers_into_mesh` is idempotent
+    /// and dedups by onion, so calling it after each sync is safe.
+    /// Best-effort: silently no-ops when mesh is off.
+    pub(crate) async fn refresh_federation_mesh_peers(&self) {
+        let svc = self.mesh_service.read().await;
+        if let Some(svc) = svc.as_ref() {
+            mesh::seed_federation_peers_into_mesh(&svc.shared_state(), &self.config.data_dir).await;
+        }
+    }
 }
 
 impl RpcHandler {
@@ -243,9 +262,31 @@ impl RpcHandler {
             .ok_or_else(|| anyhow::anyhow!("Missing 'did' parameter"))?;
         validate_did(did)?;
 
+        // Capture the node's pubkey before removal so we can also purge its
+        // synthetic mesh contact/thread (#2) — remove_node only touches
+        // nodes.json, which would otherwise leave a stale chat contact behind.
+        let removed_pubkey = federation::load_nodes(&self.config.data_dir)
+            .await
+            .ok()
+            .and_then(|nodes| nodes.into_iter().find(|n| n.did == did).map(|n| n.pubkey));
+
         let nodes = federation::remove_node(&self.config.data_dir, did).await?;
         info!(did = %did, "Removed node from federation");
 
+        if let Some(pubkey) = removed_pubkey.filter(|p| !p.is_empty()) {
+            let svc = self.mesh_service.read().await;
+            if let Some(svc) = svc.as_ref() {
+                let contact_id = mesh::federation_peer_contact_id(&pubkey);
+                mesh::purge_federation_peer(
+                    &svc.shared_state(),
+                    contact_id,
+                    &pubkey,
+                    &self.config.data_dir,
+                )
+                .await;
+            }
+        }
+
         Ok(serde_json::json!({
             "removed": true,
             "nodes_remaining": nodes.len(),
@@ -341,6 +382,10 @@ impl RpcHandler {
             }
         }
 
+        // Push any names/roster the sync just learned into the live mesh peer
+        // table so the chat list updates without a restart (#42).
+        self.refresh_federation_mesh_peers().await;
+
         Ok(serde_json::json!({
             "synced": synced,
             "failed": failed,
@@ -533,6 +578,19 @@ impl RpcHandler {
             return Ok(serde_json::json!({ "accepted": true, "already_known": true }));
         }
 
+        // Respect operator removal: a peer the operator deleted must not
+        // silently re-join via a stale invite. The tombstone is only cleared
+        // by an explicit local action (manually adding the node or accepting
+        // an incoming invite) — not by a remote-triggered join.
+        if federation::load_removed_dids(&self.config.data_dir)
+            .await
+            .unwrap_or_default()
+            .contains(did)
+        {
+            info!(peer_did = %did, "Ignoring peer-joined for a removed (tombstoned) DID");
+            return Ok(serde_json::json!({ "accepted": false, "removed": true }));
+        }
+
         let node = FederatedNode {
             did: did.to_string(),
             pubkey: pubkey.to_string(),

core/archipelago/src/api/rpc/fedimint.rs

@@ -0,0 +1,131 @@
+//! Fedimint ecash RPCs — bridge to the `fedimint-clientd` sidecar.
+//!
+//! Companion to the Cashu wallet RPCs in [`super::wallet`]. Joining/holding
+//! Fedimint ecash is delegated to the clientd container via
+//! [`crate::wallet::fedimint_client::FedimintClient`]; here we expose the
+//! node's JSON-RPC surface and keep a local registry of joined federations so
+//! the list survives clientd being temporarily unreachable.
+//!
+//! See `docs/dual-ecash-design.md`.
+
+use super::RpcHandler;
+use crate::wallet::fedimint_client::{self, FedimintClient, JoinedFederation};
+use anyhow::Result;
+
+impl RpcHandler {
+    /// `wallet.fedimint-list` — joined federations with live balances.
+    pub(super) async fn handle_wallet_fedimint_list(&self) -> Result<serde_json::Value> {
+        // Best-effort: make sure the default federation is joined/tracked.
+        let _ = fedimint_client::ensure_default_federation(&self.config.data_dir).await;
+
+        let reg = fedimint_client::load_registry(&self.config.data_dir).await?;
+
+        // Live balances are best-effort: if clientd is down we still return the
+        // tracked federations (with 0 balance) rather than failing the call.
+        let info = match FedimintClient::from_node(&self.config.data_dir).await {
+            Ok(client) => client.info().await.ok(),
+            Err(_) => None,
+        };
+
+        let federations: Vec<serde_json::Value> = reg
+            .federations
+            .iter()
+            .map(|f| {
+                let balance_sats = info
+                    .as_ref()
+                    .and_then(|i| i.get(&f.federation_id))
+                    .and_then(|e| {
+                        e.get("totalAmountMsat")
+                            .or_else(|| e.get("totalMsat"))
+                            .and_then(|v| v.as_u64())
+                    })
+                    .map(|msat| msat / 1000)
+                    .unwrap_or(0);
+                serde_json::json!({
+                    "federation_id": f.federation_id,
+                    "name": f.name,
+                    "balance_sats": balance_sats,
+                })
+            })
+            .collect();
+
+        Ok(serde_json::json!({ "federations": federations }))
+    }
+
+    /// `wallet.fedimint-join` — join a federation by invite code.
+    pub(super) async fn handle_wallet_fedimint_join(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let invite_code = params
+            .get("invite_code")
+            .and_then(|v| v.as_str())
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .ok_or_else(|| anyhow::anyhow!("Missing invite_code"))?;
+
+        let client = FedimintClient::from_node(&self.config.data_dir).await?;
+        let federation_id = client.join(invite_code).await?;
+
+        // Try to label it from the federation meta (best-effort).
+        let name = client.info().await.ok().and_then(|i| {
+            i.get(&federation_id)
+                .and_then(|e| e.get("meta"))
+                .and_then(|m| {
+                    m.get("federation_name")
+                        .or_else(|| m.get("federation_expiry_timestamp"))
+                })
+                .and_then(|v| v.as_str())
+                .map(|s| s.to_string())
+        });
+
+        let mut reg = fedimint_client::load_registry(&self.config.data_dir).await?;
+        if !reg
+            .federations
+            .iter()
+            .any(|f| f.federation_id == federation_id)
+        {
+            reg.federations.push(JoinedFederation {
+                federation_id: federation_id.clone(),
+                name,
+            });
+            fedimint_client::save_registry(&self.config.data_dir, &reg).await?;
+        }
+
+        Ok(serde_json::json!({ "federation_id": federation_id }))
+    }
+
+    /// `wallet.fedimint-leave` — stop tracking a federation locally.
+    pub(super) async fn handle_wallet_fedimint_leave(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let federation_id = params
+            .get("federation_id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing federation_id"))?;
+
+        let mut reg = fedimint_client::load_registry(&self.config.data_dir).await?;
+        let before = reg.federations.len();
+        reg.federations.retain(|f| f.federation_id != federation_id);
+        let removed = reg.federations.len() != before;
+        if removed {
+            fedimint_client::save_registry(&self.config.data_dir, &reg).await?;
+        }
+
+        Ok(serde_json::json!({ "removed": removed }))
+    }
+
+    /// `wallet.fedimint-balance` — total sats across all joined federations.
+    pub(super) async fn handle_wallet_fedimint_balance(&self) -> Result<serde_json::Value> {
+        // Soft-fail to zero when clientd isn't installed/running, so the unified
+        // wallet balance still renders from the Cashu side.
+        let balance_sats = match FedimintClient::from_node(&self.config.data_dir).await {
+            Ok(client) => client.total_balance_sats().await.unwrap_or(0),
+            Err(_) => 0,
+        };
+        Ok(serde_json::json!({ "balance_sats": balance_sats }))
+    }
+}

core/archipelago/src/api/rpc/fips.rs

@@ -115,10 +115,12 @@ impl RpcHandler {
         } else if !after.key_present {
             "no_seed_key"
         } else if after.authenticated_peer_count == 0 {
-            // Daemon is up with a key but hasn't authenticated any
-            // peers — almost always outbound UDP/8668 dropped by the
-            // local firewall/router, or the anchor itself being down.
-            "no_outbound_udp_or_anchor_down"
+            // Daemon is up with a key but hasn't authenticated any peers —
+            // almost always the outbound connection to the anchor being
+            // dropped by the local firewall/router, or the anchor itself
+            // being down. The public anchor is reached over TCP/8443 (not
+            // UDP/8668 — that endpoint is dead).
+            "no_outbound_or_anchor_down"
         } else {
             "peers_but_no_anchor"
         };
@@ -126,8 +128,8 @@ impl RpcHandler {
             "connected" => "An anchor is reachable.",
             "daemon_down" => "The FIPS daemon didn't come back up — check the FIPS service on this host.",
             "no_seed_key" => "No seed-derived FIPS key on disk. Re-run the onboarding unlock step.",
-            "no_outbound_udp_or_anchor_down" =>
-                "Daemon is running but no peers handshook. Your router / ISP might be blocking outbound UDP 8668, or every configured anchor could be down. Add a reachable peer in Seed Anchors.",
+            "no_outbound_or_anchor_down" =>
+                "Daemon is running but no peers handshook. Your router or ISP may be blocking the outbound connection to the mesh anchor (TCP port 8443), or every configured anchor is down. The public anchor is added automatically — if it still won't connect, add another reachable peer in Seed Anchors.",
             "peers_but_no_anchor" =>
                 "Mesh has peers but none of them are anchors we recognise. Add your cluster's anchor in Seed Anchors.",
             _ => "",

core/archipelago/src/api/rpc/identity/handlers.rs

@@ -14,10 +14,39 @@ impl RpcHandler {
         let manager = IdentityManager::new(&self.config.data_dir).await?;
         let (identities, default_id) = manager.list().await?;
 
+        // #49: The canonical node Nostr key is the node-level HKDF key
+        // (`derive_node_nostr_key`) that Settings and Nostr discovery both use
+        // via `node.nostr-pubkey`. The mirrored "Node" identity stores
+        // nostr=None, and seed identities use a different BIP-32 NIP-06 key, so
+        // the "Node" entry in Web5 > Identities disagreed with Settings. Resolve
+        // the node-level key once and override it onto whichever identity record
+        // is the node's own (its ed25519 matches `server_info.pubkey`), so both
+        // surfaces always show the same npub. Display-only — no key is rewritten.
+        let identity_dir = self.config.data_dir.join("identity");
+        let node_nostr_hex = crate::nostr_discovery::get_nostr_pubkey(&identity_dir)
+            .await
+            .ok();
+        let node_nostr_npub = node_nostr_hex.as_ref().and_then(|h| {
+            nostr_sdk::PublicKey::from_hex(h)
+                .ok()
+                .and_then(|pk| pk.to_bech32().ok())
+        });
+        let (snapshot, _) = self.state_manager.get_snapshot().await;
+        let node_pubkey_hex = snapshot.server_info.pubkey.clone();
+
         let items: Vec<serde_json::Value> = identities
             .into_iter()
             .map(|id| {
                 let is_default = default_id.as_deref() == Some(&id.id);
+                let is_node = !node_pubkey_hex.is_empty() && id.pubkey_hex == node_pubkey_hex;
+                let (nostr_pubkey, nostr_npub) = if is_node {
+                    (
+                        node_nostr_hex.clone().or(id.nostr_pubkey),
+                        node_nostr_npub.clone().or(id.nostr_npub),
+                    )
+                } else {
+                    (id.nostr_pubkey, id.nostr_npub)
+                };
                 serde_json::json!({
                     "id": id.id,
                     "name": id.name,
@@ -26,8 +55,8 @@ impl RpcHandler {
                     "did": id.did,
                     "created_at": id.created_at,
                     "is_default": is_default,
-                    "nostr_pubkey": id.nostr_pubkey,
-                    "nostr_npub": id.nostr_npub,
+                    "nostr_pubkey": nostr_pubkey,
+                    "nostr_npub": nostr_npub,
                     "profile": id.profile,
                 })
             })

core/archipelago/src/api/rpc/lnd/wallet.rs

@@ -9,21 +9,44 @@ use super::LND_REST_BASE_URL;
 impl RpcHandler {
     /// Generate a new on-chain Bitcoin address.
     pub(in crate::api::rpc) async fn handle_lnd_newaddress(&self) -> Result<serde_json::Value> {
-        let (client, macaroon_hex) = self.lnd_client().await?;
+        let (client, macaroon_hex) = self.lnd_client().await.map_err(|e| {
+            tracing::warn!(error = %format!("{e:#}"), "LND newaddress: client/macaroon unavailable");
+            receive_error(
+                RECEIVE_WALLET_UNINITIALIZED,
+                "The Lightning wallet isn't set up on this node yet. Finish wallet setup, then try again.",
+            )
+        })?;
 
-        let resp = client
+        let resp = match client
             .get(format!("{LND_REST_BASE_URL}/v1/newaddress"))
-            .query(&[("type", "p2wkh")])
+            // LND's REST gateway parses `type` as the AddressType enum by its
+            // proto name (or integer), NOT the lncli aliases. "p2wkh" is not a
+            // valid enum value and returns 400 "parsing field type"; the native
+            // SegWit (bech32) variant is WITNESS_PUBKEY_HASH (= 0).
+            .query(&[("type", "WITNESS_PUBKEY_HASH")])
             .header("Grpc-Metadata-macaroon", &macaroon_hex)
             .send()
             .await
-            .context("LND REST connection failed")?;
+        {
+            Ok(resp) => resp,
+            Err(e) => {
+                // The .116 case: LND container is up but its REST endpoint isn't
+                // reachable on the expected port (e.g. published-port drift), so
+                // the connection is refused. This is NOT a locked wallet — emit a
+                // distinct code so the UI stops mislabelling it.
+                tracing::warn!(error = %format!("{e:#}"), "LND newaddress: REST connection failed");
+                return Err(receive_error(
+                    RECEIVE_REST_UNREACHABLE,
+                    "The Lightning wallet service isn't reachable yet. It may be starting up or recovering — please try again in a moment.",
+                ));
+            }
+        };
 
         let status = resp.status();
         let raw_body = resp
             .text()
             .await
-            .context("LND address response could not be read")?;
+            .context("Bitcoin address response could not be read")?;
         let body: serde_json::Value = serde_json::from_str(&raw_body).unwrap_or_else(|_| {
             serde_json::json!({
                 "raw": raw_body,
@@ -32,11 +55,9 @@ impl RpcHandler {
 
         if !status.is_success() {
             let message = lnd_error_message(&body);
-            anyhow::bail!(
-                "Bitcoin address generation failed ({}): {}",
-                status,
-                message
-            );
+            let code = classify_lnd_address_error(&message);
+            tracing::warn!(%status, lnd_message = %message, code, "LND newaddress returned an error");
+            return Err(receive_error(code, default_receive_detail(code)));
         }
 
         if let Some(error) = body
@@ -44,14 +65,21 @@ impl RpcHandler {
             .or_else(|| body.get("message"))
             .and_then(|v| v.as_str())
         {
-            anyhow::bail!("Bitcoin address generation failed: {}", error);
+            let code = classify_lnd_address_error(error);
+            tracing::warn!(lnd_message = %error, code, "LND newaddress returned an error body");
+            return Err(receive_error(code, default_receive_detail(code)));
         }
 
         let address = body
             .get("address")
             .and_then(|v| v.as_str())
             .filter(|addr| !addr.trim().is_empty())
-            .ok_or_else(|| anyhow::anyhow!("Bitcoin address generation failed: LND did not return a Bitcoin address. The wallet may still be locked, uninitialized, or waiting for Bitcoin to sync."))?
+            .ok_or_else(|| {
+                receive_error(
+                    RECEIVE_WALLET_UNINITIALIZED,
+                    "The wallet didn't return an address yet. It may still be unlocking or waiting for Bitcoin to sync — please try again shortly.",
+                )
+            })?
             .to_string();
 
         Ok(serde_json::json!({ "address": address }))
@@ -123,6 +151,250 @@ impl RpcHandler {
     }
 
     /// Create a Lightning invoice.
+    /// Create a Lightning invoice and return `(bolt11, payment_hash_hex)`.
+    ///
+    /// Shared helper used by both the `lnd.createinvoice` RPC and the seller-side
+    /// peer-file invoice flow (#46). LND returns `r_hash` as base64; we re-encode
+    /// it as hex so it can be used as a stable lookup key and passed in URLs.
+    /// Whether LND reports it's synced to its Bitcoin chain backend. Used to
+    /// fail invoice minting FAST with a clear reason while the node's Bitcoin
+    /// backend is still in initial block download — otherwise the `/v1/invoices`
+    /// POST hangs for the full client timeout (×3 retries ≈ 45s) and surfaces as
+    /// an opaque failure. `getinfo` answers in ~2s even mid-IBD. Returns
+    /// `Some(false)` only when LND is reachable AND explicitly not synced;
+    /// `None` when we couldn't tell (let the mint attempt proceed and report its
+    /// own error rather than guess "syncing").
+    pub(crate) async fn lnd_chain_synced(&self) -> Option<bool> {
+        let (client, macaroon_hex) = self.lnd_client().await.ok()?;
+        let resp = client
+            .get(format!("{LND_REST_BASE_URL}/v1/getinfo"))
+            .header("Grpc-Metadata-macaroon", &macaroon_hex)
+            .send()
+            .await
+            .ok()?;
+        let body: serde_json::Value = resp.json().await.ok()?;
+        body.get("synced_to_chain").and_then(|v| v.as_bool())
+    }
+
+    /// Error returned when the node can't mint a Lightning invoice because its
+    /// Bitcoin backend is still syncing. Kept as one string so every invoice
+    /// entry point surfaces the same clear, user-facing reason.
+    fn syncing_invoice_err() -> anyhow::Error {
+        anyhow::anyhow!(
+            "Your Bitcoin node is still syncing — Lightning invoices are unavailable until it finishes. Try again once the node is fully synced."
+        )
+    }
+
+    pub(crate) async fn create_invoice(
+        &self,
+        amount_sats: i64,
+        memo: &str,
+    ) -> Result<(String, String)> {
+        if amount_sats < 0 {
+            return Err(anyhow::anyhow!("Amount must be non-negative"));
+        }
+        if memo.len() > 639 {
+            return Err(anyhow::anyhow!("Memo too long (max 639 bytes)"));
+        }
+
+        let (client, macaroon_hex) = self.lnd_client().await?;
+        let invoice_body = serde_json::json!({
+            "value": amount_sats.to_string(),
+            "memo": memo,
+        });
+        // LND's REST endpoint can briefly drop/reset connections under load
+        // (swap pressure, just-restarted, TLS handshake races), which used to
+        // hard-fail the buy-file invoice with an opaque 503. Retry on a
+        // CONNECTION error with short backoff so a transient blip doesn't
+        // surface as a payment failure. A *timeout* is NOT retried: it means LND
+        // accepted the connection but isn't answering the mint (e.g. a degraded
+        // node), and retrying just multiplies the wait (3×15s ≈ 45s) — fail
+        // after the first hang and let the caller surface the real reason.
+        let mut last_err: Option<anyhow::Error> = None;
+        let mut resp = None;
+        for attempt in 0..3u32 {
+            match client
+                .post(format!("{LND_REST_BASE_URL}/v1/invoices"))
+                .header("Grpc-Metadata-macaroon", &macaroon_hex)
+                .json(&invoice_body)
+                .send()
+                .await
+            {
+                Ok(r) => {
+                    resp = Some(r);
+                    break;
+                }
+                Err(e) => {
+                    let timed_out = e.is_timeout();
+                    last_err = Some(anyhow::anyhow!(
+                        "LND REST send failed (attempt {}): {e}",
+                        attempt + 1
+                    ));
+                    if timed_out {
+                        break;
+                    }
+                    tokio::time::sleep(std::time::Duration::from_millis(400)).await;
+                }
+            }
+        }
+        let resp = match resp {
+            Some(r) => r,
+            None => {
+                // If LND is reachable but explicitly not synced to chain, say so —
+                // it's the most common reason a just-restored/syncing node can't
+                // mint. Otherwise surface the underlying transport error.
+                if self.lnd_chain_synced().await == Some(false) {
+                    return Err(Self::syncing_invoice_err());
+                }
+                return Err(last_err.unwrap_or_else(|| {
+                    anyhow::anyhow!("Failed to reach LND REST to create invoice")
+                }));
+            }
+        };
+
+        let status = resp.status();
+        let body: serde_json::Value = resp
+            .json()
+            .await
+            .context("Failed to parse invoice response")?;
+        if !status.is_success() {
+            let msg = body
+                .get("message")
+                .and_then(|v| v.as_str())
+                .unwrap_or("Unknown error");
+            return Err(anyhow::anyhow!("Failed to create invoice: {}", msg));
+        }
+
+        let payment_request = body
+            .get("payment_request")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string();
+
+        // r_hash is base64 in LND's REST response — convert to hex.
+        use base64::Engine;
+        let payment_hash_hex = body
+            .get("r_hash")
+            .and_then(|v| v.as_str())
+            .and_then(|b64| base64::engine::general_purpose::STANDARD.decode(b64).ok())
+            .map(hex::encode)
+            .unwrap_or_default();
+
+        Ok((payment_request, payment_hash_hex))
+    }
+
+    /// Look up an invoice by hex payment hash; true if it has settled.
+    pub(crate) async fn invoice_is_settled(&self, payment_hash_hex: &str) -> Result<bool> {
+        if payment_hash_hex.is_empty() || hex::decode(payment_hash_hex).is_err() {
+            return Err(anyhow::anyhow!("Invalid payment hash"));
+        }
+        let (client, macaroon_hex) = self.lnd_client().await?;
+        // LND REST: GET /v1/invoice/{r_hash_str} where r_hash_str is hex.
+        let resp = client
+            .get(format!("{LND_REST_BASE_URL}/v1/invoice/{payment_hash_hex}"))
+            .header("Grpc-Metadata-macaroon", &macaroon_hex)
+            .send()
+            .await
+            .context("Failed to look up invoice")?;
+        if !resp.status().is_success() {
+            return Ok(false);
+        }
+        let body: serde_json::Value = resp
+            .json()
+            .await
+            .context("Failed to parse invoice lookup response")?;
+        let settled = body
+            .get("settled")
+            .and_then(|v| v.as_bool())
+            .unwrap_or(false)
+            || body.get("state").and_then(|v| v.as_str()) == Some("SETTLED");
+        Ok(settled)
+    }
+
+    /// Generate a fresh on-chain receive address (seller side, #46).
+    pub(crate) async fn new_onchain_address(&self) -> Result<String> {
+        let (client, macaroon_hex) = self.lnd_client().await?;
+        let resp = client
+            .get(format!("{LND_REST_BASE_URL}/v1/newaddress"))
+            .header("Grpc-Metadata-macaroon", &macaroon_hex)
+            .send()
+            .await
+            .context("Failed to get new address")?;
+        if !resp.status().is_success() {
+            return Err(anyhow::anyhow!("LND newaddress failed: {}", resp.status()));
+        }
+        let body: serde_json::Value = resp
+            .json()
+            .await
+            .context("Failed to parse newaddress response")?;
+        body.get("address")
+            .and_then(|v| v.as_str())
+            .filter(|s| !s.is_empty())
+            .map(|s| s.to_string())
+            .ok_or_else(|| anyhow::anyhow!("LND newaddress returned no address"))
+    }
+
+    /// True if an on-chain payment of >= `min_sats` to `address` has been seen
+    /// with at least one confirmation (seller side, #46). Conservative on
+    /// purpose: requires a confirmation + exact-address + sufficient-amount so a
+    /// file sale is never released on an unconfirmed (reorg-able) tx.
+    pub(crate) async fn onchain_received(&self, address: &str, min_sats: u64) -> Result<bool> {
+        if address.is_empty() {
+            return Err(anyhow::anyhow!("Empty address"));
+        }
+        let (client, macaroon_hex) = self.lnd_client().await?;
+        let resp = client
+            .get(format!("{LND_REST_BASE_URL}/v1/transactions"))
+            .header("Grpc-Metadata-macaroon", &macaroon_hex)
+            .send()
+            .await
+            .context("Failed to list transactions")?;
+        if !resp.status().is_success() {
+            return Ok(false);
+        }
+        let body: serde_json::Value = resp
+            .json()
+            .await
+            .context("Failed to parse transactions response")?;
+        let i64_field = |tx: &serde_json::Value, k: &str| -> i64 {
+            tx.get(k)
+                .and_then(|v| v.as_str())
+                .and_then(|s| s.parse::<i64>().ok())
+                .or_else(|| tx.get(k).and_then(|v| v.as_i64()))
+                .unwrap_or(0)
+        };
+        let txs = body
+            .get("transactions")
+            .and_then(|v| v.as_array())
+            .cloned()
+            .unwrap_or_default();
+        for tx in &txs {
+            if i64_field(tx, "num_confirmations") < 1 {
+                continue;
+            }
+            if i64_field(tx, "amount") < min_sats as i64 {
+                continue;
+            }
+            let pays_addr = tx
+                .get("dest_addresses")
+                .and_then(|v| v.as_array())
+                .map(|arr| arr.iter().any(|a| a.as_str() == Some(address)))
+                .unwrap_or(false)
+                || tx
+                    .get("output_details")
+                    .and_then(|v| v.as_array())
+                    .map(|arr| {
+                        arr.iter()
+                            .any(|o| o.get("address").and_then(|a| a.as_str()) == Some(address))
+                    })
+                    .unwrap_or(false);
+            if pays_addr {
+                return Ok(true);
+            }
+        }
+        Ok(false)
+    }
+
     pub(in crate::api::rpc) async fn handle_lnd_createinvoice(
         &self,
         params: Option<serde_json::Value>,
@@ -155,13 +427,23 @@ impl RpcHandler {
             "memo": memo,
         });
 
-        let resp = client
+        let resp = match client
             .post(format!("{LND_REST_BASE_URL}/v1/invoices"))
             .header("Grpc-Metadata-macaroon", &macaroon_hex)
             .json(&invoice_body)
             .send()
             .await
-            .context("Failed to create invoice")?;
+        {
+            Ok(r) => r,
+            Err(e) => {
+                // A hung/failed mint while LND is explicitly not synced to chain
+                // gets a clear, user-facing reason instead of an opaque error.
+                if self.lnd_chain_synced().await == Some(false) {
+                    return Err(Self::syncing_invoice_err());
+                }
+                return Err(anyhow::anyhow!(e).context("Failed to create invoice"));
+            }
+        };
 
         let status = resp.status();
         let body: serde_json::Value = resp
@@ -524,8 +806,15 @@ impl RpcHandler {
         let entropy_b64 = base64::engine::general_purpose::STANDARD.encode(entropy);
         entropy.zeroize();
 
+        // Use the per-node secret as the LND wallet password (NOT the
+        // caller-supplied one) so the unattended boot path can auto-unlock this
+        // wallet. The wallet stays recoverable from the Archipelago seed via the
+        // derived entropy above. This unifies both init paths on one password
+        // source — the divergence here is what left wallets locked fleet-wide.
+        let _ = wallet_password; // accepted for API compat; superseded by the per-node secret
+        let node_wallet_pw = crate::container::lnd::ensure_wallet_password().await?;
         let wallet_password_b64 =
-            base64::engine::general_purpose::STANDARD.encode(wallet_password.as_bytes());
+            base64::engine::general_purpose::STANDARD.encode(node_wallet_pw.as_bytes());
 
         // Call LND REST API to initialize wallet with derived entropy.
         // LND must be running but NOT yet initialized (no existing wallet).
@@ -579,9 +868,75 @@ fn lnd_error_message(body: &serde_json::Value) -> String {
         .to_string()
 }
 
+// Stable, machine-readable reason codes for receive-address failures. They are
+// embedded in the error message as a `[CODE]` token so the frontend
+// (neode-ui/src/utils/bitcoinReceive.ts) can show an accurate explanation
+// instead of guessing wallet state by substring-matching — which is what made
+// .228 report "wallet is locked" when LND's REST was merely unreachable.
+//
+// Every receive error string starts with "Bitcoin address" so it survives the
+// RPC error sanitizer (api/rpc/middleware.rs) unchanged rather than being
+// flattened to the generic "Operation failed" message (the .116 symptom).
+pub(crate) const RECEIVE_REST_UNREACHABLE: &str = "LND_REST_UNREACHABLE";
+pub(crate) const RECEIVE_WALLET_LOCKED: &str = "LND_WALLET_LOCKED";
+pub(crate) const RECEIVE_WALLET_UNINITIALIZED: &str = "LND_WALLET_UNINITIALIZED";
+pub(crate) const RECEIVE_SYNCING: &str = "LND_SYNCING";
+pub(crate) const RECEIVE_LND_ERROR: &str = "LND_ERROR";
+
+/// Build a receive-address error carrying a reason code the UI can map.
+fn receive_error(code: &str, detail: &str) -> anyhow::Error {
+    anyhow::anyhow!("Bitcoin address unavailable [{code}]: {detail}")
+}
+
+/// A sensible default human message per code (used for non-UI callers and logs;
+/// the frontend renders its own copy from the code).
+fn default_receive_detail(code: &str) -> &'static str {
+    match code {
+        RECEIVE_REST_UNREACHABLE => {
+            "The Lightning wallet service isn't reachable yet. It may be starting up or recovering — please try again in a moment."
+        }
+        RECEIVE_WALLET_LOCKED => {
+            "The Lightning wallet is locked. Unlock it (or finish wallet setup), then try again."
+        }
+        RECEIVE_WALLET_UNINITIALIZED => {
+            "The Lightning wallet isn't set up yet. Finish wallet setup, then try again."
+        }
+        RECEIVE_SYNCING => {
+            "The wallet is still syncing with the Bitcoin network. Please try again once it has caught up."
+        }
+        _ => "Couldn't generate a Bitcoin address right now. Please try again shortly.",
+    }
+}
+
+/// Classify a non-2xx LND error body/message into a reason code. The wording of
+/// LND's REST errors is stable enough to bucket: a locked wallet, an
+/// uninitialized wallet, a syncing chain, or some other failure.
+fn classify_lnd_address_error(message: &str) -> &'static str {
+    let m = message.to_lowercase();
+    if m.contains("locked") || m.contains("unlock") {
+        RECEIVE_WALLET_LOCKED
+    } else if m.contains("synchroniz")
+        || m.contains("syncing")
+        || m.contains("not yet ready")
+        || m.contains("in the process of starting")
+    {
+        RECEIVE_SYNCING
+    } else if m.contains("wallet not found")
+        || m.contains("not exist")
+        || m.contains("uninitialized")
+        || m.contains("not initialized")
+        || m.contains("create a wallet")
+        || m.contains("no wallet")
+    {
+        RECEIVE_WALLET_UNINITIALIZED
+    } else {
+        RECEIVE_LND_ERROR
+    }
+}
+
 #[cfg(test)]
 mod tests {
-    use super::lnd_error_message;
+    use super::*;
 
     #[test]
     fn lnd_error_message_prefers_message_field() {
@@ -600,4 +955,46 @@ mod tests {
             "unknown LND error"
         );
     }
+
+    #[test]
+    fn classify_locked_wallet() {
+        assert_eq!(
+            classify_lnd_address_error("wallet locked, please unlock"),
+            RECEIVE_WALLET_LOCKED
+        );
+    }
+
+    #[test]
+    fn classify_uninitialized_wallet() {
+        assert_eq!(
+            classify_lnd_address_error("wallet not found, create a wallet first"),
+            RECEIVE_WALLET_UNINITIALIZED
+        );
+    }
+
+    #[test]
+    fn classify_syncing() {
+        assert_eq!(
+            classify_lnd_address_error("server is still in the process of starting"),
+            RECEIVE_SYNCING
+        );
+    }
+
+    #[test]
+    fn classify_unknown_is_generic_error() {
+        assert_eq!(
+            classify_lnd_address_error("some other failure"),
+            RECEIVE_LND_ERROR
+        );
+    }
+
+    #[test]
+    fn receive_error_starts_with_sanitizer_safe_prefix_and_embeds_code() {
+        // Must start with "Bitcoin address" (survives the RPC error sanitizer)
+        // and carry the [CODE] token the frontend parses.
+        let err = receive_error(RECEIVE_REST_UNREACHABLE, "unreachable");
+        let s = format!("{err}");
+        assert!(s.starts_with("Bitcoin address"), "got: {s}");
+        assert!(s.contains("[LND_REST_UNREACHABLE]"), "got: {s}");
+    }
 }

core/archipelago/src/api/rpc/mesh/assistant.rs

@@ -0,0 +1,189 @@
+//! Mesh-AI assistant RPCs (issue #50): read/update the local assistant config
+//! and report whether a local Ollama is available (for the install deep-link).
+
+use super::super::RpcHandler;
+use anyhow::Result;
+use std::time::Duration;
+
+/// Default model when the node hasn't picked one (kept in sync with the mesh
+/// assistant handler's `DEFAULT_MODEL`).
+const DEFAULT_MODEL: &str = "qwen2.5-coder";
+
+impl RpcHandler {
+    /// mesh.assistant-status — current settings + local Ollama availability.
+    pub(in crate::api::rpc) async fn handle_mesh_assistant_status(
+        &self,
+    ) -> Result<serde_json::Value> {
+        let (cfg, denied_askers) = {
+            let service = self.mesh_service.read().await;
+            let svc = service
+                .as_ref()
+                .ok_or_else(|| anyhow::anyhow!("Mesh service not running"))?;
+            (svc.assistant_config().await, svc.assistant_denied_askers().await)
+        };
+
+        let (ollama_detected, models) = detect_ollama().await;
+        let claude_available =
+            tokio::fs::metadata(self.config.data_dir.join("secrets/claude-api-key"))
+                .await
+                .is_ok();
+        Ok(serde_json::json!({
+            "enabled": cfg.enabled,
+            "model": cfg.model,
+            "trusted_only": cfg.trusted_only,
+            "backend": cfg.backend,
+            "allowed_contacts": cfg.allowed_contacts,
+            "default_model": DEFAULT_MODEL,
+            "ollama_detected": ollama_detected,
+            "claude_available": claude_available,
+            "models": models,
+            "denied_askers": denied_askers,
+        }))
+    }
+
+    /// mesh.assistant-configure — update assistant settings live.
+    /// Params: `enabled?: bool`, `trusted_only?: bool`,
+    /// `model?: string|null` (string sets, null clears to default, absent leaves).
+    pub(in crate::api::rpc) async fn handle_mesh_assistant_configure(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.unwrap_or_default();
+        let service = self.mesh_service.read().await;
+        let svc = service
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Mesh service not running"))?;
+
+        let enabled = params.get("enabled").and_then(|v| v.as_bool());
+        let trusted_only = params.get("trusted_only").and_then(|v| v.as_bool());
+        let backend = params
+            .get("backend")
+            .and_then(|v| v.as_str())
+            .map(|s| s.to_string());
+        // model: key present + string => set; present + null => clear; absent => leave
+        let model = if let Some(v) = params.get("model") {
+            Some(v.as_str().map(|s| s.to_string()))
+        } else {
+            None
+        };
+        // allowed_contacts: present + array => replace the allowlist (pubkey hex
+        // strings); absent => leave unchanged.
+        let allowed_contacts = params
+            .get("allowed_contacts")
+            .and_then(|v| v.as_array())
+            .map(|arr| {
+                arr.iter()
+                    .filter_map(|e| e.as_str().map(|s| s.to_string()))
+                    .collect::<Vec<String>>()
+            });
+
+        svc.configure_assistant(enabled, model, trusted_only, backend, allowed_contacts)
+            .await?;
+        let cfg = svc.assistant_config().await;
+        Ok(serde_json::json!({
+            "enabled": cfg.enabled,
+            "model": cfg.model,
+            "trusted_only": cfg.trusted_only,
+            "backend": cfg.backend,
+            "allowed_contacts": cfg.allowed_contacts,
+        }))
+    }
+
+    /// mesh.schedule-message — queue a message to send at a future time.
+    /// Params: `body: string`, `fire_at: i64` (unix secs), and one of
+    /// `contact_id: u32` (DM) or `channel: u8` (broadcast).
+    pub(in crate::api::rpc) async fn handle_mesh_schedule_message(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let p = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let body = p
+            .get("body")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("body is required"))?
+            .to_string();
+        let fire_at = p
+            .get("fire_at")
+            .and_then(|v| v.as_i64())
+            .ok_or_else(|| anyhow::anyhow!("fire_at (unix seconds) is required"))?;
+        let contact_id = p
+            .get("contact_id")
+            .and_then(|v| v.as_u64())
+            .map(|v| v as u32);
+        let channel = p.get("channel").and_then(|v| v.as_u64()).map(|v| v as u8);
+        if contact_id.is_none() && channel.is_none() {
+            anyhow::bail!("either contact_id or channel is required");
+        }
+
+        let service = self.mesh_service.read().await;
+        let svc = service
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Mesh service not running"))?;
+        let msg = svc
+            .scheduler
+            .add(contact_id, channel, body, fire_at)
+            .await?;
+        Ok(serde_json::to_value(msg)?)
+    }
+
+    /// mesh.list-scheduled — list queued messages (sorted by fire time).
+    pub(in crate::api::rpc) async fn handle_mesh_list_scheduled(
+        &self,
+    ) -> Result<serde_json::Value> {
+        let service = self.mesh_service.read().await;
+        let svc = service
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Mesh service not running"))?;
+        let messages = svc.scheduler.list().await;
+        Ok(serde_json::json!({ "messages": messages }))
+    }
+
+    /// mesh.cancel-scheduled — remove a queued message by id.
+    pub(in crate::api::rpc) async fn handle_mesh_cancel_scheduled(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let id = params
+            .as_ref()
+            .and_then(|p| p.get("id"))
+            .and_then(|v| v.as_u64())
+            .ok_or_else(|| anyhow::anyhow!("id is required"))?;
+        let service = self.mesh_service.read().await;
+        let svc = service
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Mesh service not running"))?;
+        let cancelled = svc.scheduler.cancel(id).await?;
+        Ok(serde_json::json!({ "cancelled": cancelled }))
+    }
+}
+
+/// Probe the local Ollama HTTP API; return (detected, model_names).
+async fn detect_ollama() -> (bool, Vec<String>) {
+    let client = match reqwest::Client::builder()
+        .timeout(Duration::from_secs(2))
+        .build()
+    {
+        Ok(c) => c,
+        Err(_) => return (false, Vec::new()),
+    };
+    match client.get("http://localhost:11434/api/tags").send().await {
+        Ok(resp) if resp.status().is_success() => {
+            let json: serde_json::Value = resp.json().await.unwrap_or_default();
+            let models = json
+                .get("models")
+                .and_then(|m| m.as_array())
+                .map(|arr| {
+                    arr.iter()
+                        .filter_map(|m| {
+                            m.get("name")
+                                .and_then(|n| n.as_str())
+                                .map(|s| s.to_string())
+                        })
+                        .collect()
+                })
+                .unwrap_or_default();
+            (true, models)
+        }
+        _ => (false, Vec::new()),
+    }
+}

core/archipelago/src/api/rpc/mesh/messaging.rs

@@ -110,6 +110,18 @@ impl RpcHandler {
         if let Some(name) = params.get("advert_name").and_then(|v| v.as_str()) {
             config.advert_name = Some(name.to_string());
         }
+        if let Some(announce) = params
+            .get("announce_block_headers")
+            .and_then(|v| v.as_bool())
+        {
+            config.announce_block_headers = announce;
+        }
+        if let Some(receive) = params
+            .get("receive_block_headers")
+            .and_then(|v| v.as_bool())
+        {
+            config.receive_block_headers = receive;
+        }
 
         mesh::save_config(&self.config.data_dir, &config).await?;
 
@@ -124,6 +136,8 @@ impl RpcHandler {
             "configured": true,
             "enabled": config.enabled,
             "device_path": config.device_path,
+            "announce_block_headers": config.announce_block_headers,
+            "receive_block_headers": config.receive_block_headers,
         }))
     }
 }

core/archipelago/src/api/rpc/mesh/mod.rs

@@ -1,3 +1,4 @@
+mod assistant;
 mod bitcoin_ops;
 mod messaging;
 mod safety;

core/archipelago/src/api/rpc/mesh/status.rs

@@ -5,26 +5,39 @@ use anyhow::Result;
 impl RpcHandler {
     /// mesh.status — Get mesh radio status, device info, and peer count.
     pub(in crate::api::rpc) async fn handle_mesh_status(&self) -> Result<serde_json::Value> {
+        // Block-header send/receive prefs live in MeshConfig; surface them in
+        // status so the UI toggles (issue #28) can show the persisted state.
+        let config = mesh::load_config(&self.config.data_dir).await?;
         let service = self.mesh_service.read().await;
-        if let Some(svc) = service.as_ref() {
+        let mut value = if let Some(svc) = service.as_ref() {
             let status = svc.status().await;
-            Ok(serde_json::to_value(status)?)
+            serde_json::to_value(status)?
         } else {
             // No service running — return basic config + device detection
-            let config = mesh::load_config(&self.config.data_dir).await?;
             let devices = mesh::detect_devices().await;
-            Ok(serde_json::json!({
+            serde_json::json!({
                 "enabled": config.enabled,
                 "device_connected": false,
                 "device_type": "unknown",
                 "device_path": config.device_path,
-                "channel_name": config.channel_name.unwrap_or_else(|| "archipelago".to_string()),
+                "channel_name": config.channel_name.clone().unwrap_or_else(|| "archipelago".to_string()),
                 "detected_devices": devices,
                 "peer_count": 0,
                 "messages_sent": 0,
                 "messages_received": 0,
-            }))
+            })
+        };
+        if let Some(obj) = value.as_object_mut() {
+            obj.insert(
+                "announce_block_headers".into(),
+                config.announce_block_headers.into(),
+            );
+            obj.insert(
+                "receive_block_headers".into(),
+                config.receive_block_headers.into(),
+            );
         }
+        Ok(value)
     }
 
     /// mesh.peers — List discovered mesh peers.
@@ -82,12 +95,17 @@ impl RpcHandler {
         if let Some(svc) = service.as_ref() {
             let peers = svc.peers().await;
             let messages = svc.messages(None).await;
-            // Per-peer last message.
-            for peer in &peers {
+            // Collapse radio/federation twins into one conversation per identity
+            // so a node reachable both ways shows once, with its messages unioned
+            // across both twin contact_ids (#12).
+            let groups = mesh::group_peer_twins(&peers);
+            for group in &groups {
+                let peer = &group.canonical;
+                // Newest message across ALL twin contact_ids in this group.
                 let last = messages
                     .iter()
                     .rev()
-                    .find(|m| m.peer_contact_id == peer.contact_id);
+                    .find(|m| group.contact_ids.contains(&m.peer_contact_id));
                 let is_federation = peer.contact_id & 0x8000_0000 != 0;
                 conversations.push(serde_json::json!({
                     "id": format!("{}:{}", if is_federation { "federation" } else { "mesh" }, peer.contact_id),
@@ -150,8 +168,16 @@ impl RpcHandler {
         let filtered: Vec<_> = match kind {
             "mesh" | "federation" => {
                 let contact_id: u32 = rest.parse().unwrap_or(0);
+                // Resolve this id's twin group and union messages across all of
+                // its contact_ids, so opening either twin shows the full thread
+                // (federation-injected + radio messages) (#12).
+                let ids: Vec<u32> = mesh::group_peer_twins(&svc.peers().await)
+                    .into_iter()
+                    .find(|g| g.contact_ids.contains(&contact_id))
+                    .map(|g| g.contact_ids)
+                    .unwrap_or_else(|| vec![contact_id]);
                 all.into_iter()
-                    .filter(|m| m.peer_contact_id == contact_id)
+                    .filter(|m| ids.contains(&m.peer_contact_id))
                     .collect()
             }
             "channel" => {
@@ -245,43 +271,45 @@ impl RpcHandler {
         if let Some(svc) = service.as_ref() {
             let state = svc.state();
 
-            // Snapshot the firmware pubkeys we currently know about, then
-            // add them to the radio-contact blocklist. MeshCore's on-device
-            // contact table is persistent and reads back stale rows on the
-            // next refresh_contacts, so without this step `clear-all` only
-            // wipes the app view for a few seconds before the old entries
-            // reappear. The blocklist is also saved to disk so the filter
-            // survives a restart.
-            let firmware_pubkeys: Vec<String> = state
+            // NOTE: `clear-all` intentionally does NOT build a radio-contact
+            // blocklist. Permanently ignoring firmware contacts meant a cleared
+            // peer could never return even when it re-advertised (it also broke
+            // re-pairing a phone after a clear). Real per-contact blocking will
+            // be a separate, explicit feature. Here we just wipe the app-side
+            // view and ALSO clear any blocklist left over from older builds, so
+            // previously-hidden contacts can re-appear when next heard. The
+            // firmware's own contact table is the source of truth on refresh.
+            {
+                let mut set = state.radio_contact_blocklist.write().await;
+                set.clear();
+            }
+            let _ = crate::mesh::save_ignored_radio_contacts(&data_dir, &[]).await;
+
+            // Actually DELETE each radio contact from the firmware table (via
+            // CMD_REMOVE_CONTACT) so wiped peers don't just reappear on the next
+            // refresh. They come back only when they re-advertise (reachable).
+            // Federation-synthetic peers (high contact_id bit) aren't firmware
+            // contacts, so skip those.
+            let firmware_pubkeys: Vec<[u8; 32]> = state
                 .peers
                 .read()
                 .await
                 .values()
-                .filter_map(|p| {
-                    // Federation-synthetic peers have their contact_id in the
-                    // high half of u32 and carry the archipelago key — those
-                    // aren't firmware contacts and must not go on the list.
-                    if p.contact_id & 0x8000_0000 != 0 {
-                        None
-                    } else {
-                        p.pubkey_hex.clone()
-                    }
+                .filter(|p| p.contact_id & 0x8000_0000 == 0)
+                .filter_map(|p| p.pubkey_hex.as_deref())
+                .filter_map(|h| hex::decode(h).ok())
+                .filter(|b| b.len() == 32)
+                .map(|b| {
+                    let mut k = [0u8; 32];
+                    k.copy_from_slice(&b);
+                    k
                 })
                 .collect();
-            {
-                let mut set = state.radio_contact_blocklist.write().await;
-                for pk in &firmware_pubkeys {
-                    set.insert(pk.clone());
-                }
+            for pk in firmware_pubkeys {
+                let _ = state
+                    .send_cmd(crate::mesh::listener::MeshCommand::RemoveContact { pubkey: pk })
+                    .await;
             }
-            let persisted: Vec<String> = state
-                .radio_contact_blocklist
-                .read()
-                .await
-                .iter()
-                .cloned()
-                .collect();
-            let _ = crate::mesh::save_ignored_radio_contacts(&data_dir, &persisted).await;
 
             state.peers.write().await.clear();
             state.messages.write().await.clear();

core/archipelago/src/api/rpc/mesh/typed_messages.rs

@@ -1133,9 +1133,13 @@ impl RpcHandler {
             .ok_or_else(|| anyhow::anyhow!("Mesh service not running"))?;
         let state = svc.shared_state();
         let contacts = state.contacts.read().await;
-        let peers = state.peers.read().await;
+        let peer_vec: Vec<_> = state.peers.read().await.values().cloned().collect();
+        // Collapse radio/federation twins so a node reachable both ways shows as
+        // one contact instead of two (#12).
+        let groups = crate::mesh::group_peer_twins(&peer_vec);
         let mut out: Vec<serde_json::Value> = Vec::new();
-        for peer in peers.values() {
+        for group in &groups {
+            let peer = &group.canonical;
             if let Some(pk) = peer.pubkey_hex.as_ref() {
                 let entry = contacts.get(pk).cloned().unwrap_or_default();
                 out.push(serde_json::json!({
@@ -1184,6 +1188,12 @@ impl RpcHandler {
             entry.pinned = p;
         }
         let saved = entry.clone();
+        let snapshot = contacts.clone();
+        drop(contacts);
+        // Persist (encrypted, atomic) so the customisation survives restarts.
+        if let Err(e) = crate::mesh::save_mesh_contacts(&self.config.data_dir, &snapshot).await {
+            tracing::warn!("failed to persist mesh contacts: {e}");
+        }
         Ok(serde_json::json!({
             "saved": true,
             "pubkey": pubkey,
@@ -1215,6 +1225,11 @@ impl RpcHandler {
         let mut contacts = state.contacts.write().await;
         let entry = contacts.entry(pubkey.clone()).or_default();
         entry.blocked = blocked;
+        let snapshot = contacts.clone();
+        drop(contacts);
+        if let Err(e) = crate::mesh::save_mesh_contacts(&self.config.data_dir, &snapshot).await {
+            tracing::warn!("failed to persist mesh contacts: {e}");
+        }
         Ok(serde_json::json!({ "pubkey": pubkey, "blocked": blocked }))
     }
 

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

@@ -9,6 +9,7 @@ mod credentials;
 mod dispatcher;
 mod dwn;
 mod federation;
+mod fedimint;
 mod fips;
 mod handshake;
 mod identity;

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

@@ -32,6 +32,8 @@ fn is_platform_managed_app(app_id: &str) -> bool {
             | "fedimint-gateway"
             | "indeedhub"
             | "immich"
+            | "fips"
+            | "fips-ui"
     )
 }
 
@@ -347,13 +349,37 @@ fn http_probe_cmd(url: &'static str) -> &'static str {
     }
 }
 
+/// Bitcoin UTXO cache (`-dbcache`) in MB, sized to host RAM.
+///
+/// A fixed large dbcache on a small box pushes bitcoind + the ~20 app
+/// containers past physical RAM and triggers system-wide swap thrash: the
+/// disk saturates, bitcoind can't answer its own RPC, and the dashboard
+/// backend's sqlite reads stall — surfacing as /rpc/v1 502s and a blank
+/// Bitcoin UI. Budget ~1/16 of RAM for the cache (floor 300 MB — bitcoind's
+/// own default is 450 — cap 4096 MB), mirroring scripts/container-specs.sh.
+pub(super) fn bitcoin_dbcache_mb() -> u64 {
+    let total_mb = std::fs::read_to_string("/proc/meminfo")
+        .ok()
+        .and_then(|c| {
+            c.lines()
+                .find_map(|l| l.strip_prefix("MemTotal:"))
+                .and_then(|v| v.split_whitespace().next())
+                .and_then(|kb| kb.parse::<u64>().ok())
+        })
+        .map(|kb| kb / 1024)
+        .unwrap_or(16000); // assume a comfortable host if /proc/meminfo is unreadable
+    (total_mb / 16).clamp(300, 4096)
+}
+
 /// Get per-app memory limit.
 pub(super) fn get_memory_limit(app_id: &str) -> &'static str {
     match app_id {
-        // Heavy apps. Bitcoin: dbcache uses ~4GB; the daemon also needs
-        // headroom for mempool + connection buffers + script-verifier
-        // memory + I/O. 4g caused OOM-cascades during IBD. 8g is the
-        // floor; ideally this would be host-RAM aware (next pass).
+        // Heavy apps. Bitcoin: dbcache is now host-RAM-aware (see
+        // bitcoin_dbcache_mb), so the daemon's footprint scales with the box.
+        // This cgroup cap is an upper bound for mempool + connection buffers +
+        // script-verifier memory + I/O; a tight cap (4g) previously caused
+        // OOM-cascades during IBD, so keep 8g as a generous ceiling rather
+        // than a tight limit — swap thrash is prevented at the dbcache layer.
         "bitcoin" | "bitcoin-core" | "bitcoin-knots" => "8g",
         // ElectrumX indexing spikes above its cache size due Python,
         // RocksDB, socket buffers, and reorg/history work. Keep cache
@@ -672,9 +698,10 @@ pub(super) async fn get_app_config(
             // RPC is reachable from the bitcoin-ui companion container.
             //
             // Sync-speed flags:
-            //   -dbcache=4096 — UTXO set cache; 4GB is the sweet spot before
-            //     diminishing returns. Container has --memory=8g now so
-            //     there's headroom for mempool + connections.
+            //   -dbcache     — UTXO set cache, sized to host RAM via
+            //     bitcoin_dbcache_mb() (see there). A fixed 4GB cache swap-
+            //     thrashed small nodes into fleet-wide 502s; ~1/16 of RAM
+            //     keeps headroom for mempool + connections + the app stack.
             //   -par=0       — use all available cores for script
             //     verification (defaults to NCPU-1 capped at 16). Was
             //     effectively pinned at 2 by --cpus=2 (now removed).
@@ -687,7 +714,7 @@ pub(super) async fn get_app_config(
                 "-rpcport=8332".to_string(),
                 "-printtoconsole=1".to_string(),
                 "-datadir=/home/bitcoin/.bitcoin".to_string(),
-                "-dbcache=4096".to_string(),
+                format!("-dbcache={}", bitcoin_dbcache_mb()),
                 "-par=0".to_string(),
                 "-maxconnections=125".to_string(),
             ]),
@@ -750,27 +777,33 @@ pub(super) async fn get_app_config(
             None,
             None,
         ),
-        "mempool-api" => (
-            vec!["8999:8999".to_string()],
-            vec!["/var/lib/archipelago/mempool:/data".to_string()],
-            vec![
-                "MEMPOOL_BACKEND=electrum".to_string(),
-                "ELECTRUM_HOST=electrumx".to_string(),
-                "ELECTRUM_PORT=50001".to_string(),
-                "ELECTRUM_TLS_ENABLED=false".to_string(),
-                "CORE_RPC_HOST=bitcoin-knots".to_string(),
-                "CORE_RPC_PORT=8332".to_string(),
-                "CORE_RPC_USERNAME=archipelago".to_string(),
-                format!("CORE_RPC_PASSWORD={}", rpc_pass),
-                "DATABASE_ENABLED=true".to_string(),
-                "DATABASE_HOST=archy-mempool-db".to_string(),
-                "DATABASE_DATABASE=mempool".to_string(),
-                "DATABASE_USERNAME=mempool".to_string(),
-                format!("DATABASE_PASSWORD={}", read_secret("mempool-db-password", "mempoolpass")),
-            ],
-            None,
-            None,
-        ),
+        "mempool-api" => {
+            // CORE_RPC_HOST must resolve to the actual Bitcoin node container —
+            // bitcoin-knots OR bitcoin-core — else mempool-api can't reach RPC
+            // on a Core node (B12). Falls back to bitcoin-knots if undetected.
+            let bitcoin_rpc_host = super::dependencies::detect_bitcoin_rpc_host().await;
+            (
+                vec!["8999:8999".to_string()],
+                vec!["/var/lib/archipelago/mempool:/data".to_string()],
+                vec![
+                    "MEMPOOL_BACKEND=electrum".to_string(),
+                    "ELECTRUM_HOST=electrumx".to_string(),
+                    "ELECTRUM_PORT=50001".to_string(),
+                    "ELECTRUM_TLS_ENABLED=false".to_string(),
+                    format!("CORE_RPC_HOST={}", bitcoin_rpc_host),
+                    "CORE_RPC_PORT=8332".to_string(),
+                    "CORE_RPC_USERNAME=archipelago".to_string(),
+                    format!("CORE_RPC_PASSWORD={}", rpc_pass),
+                    "DATABASE_ENABLED=true".to_string(),
+                    "DATABASE_HOST=archy-mempool-db".to_string(),
+                    "DATABASE_DATABASE=mempool".to_string(),
+                    "DATABASE_USERNAME=mempool".to_string(),
+                    format!("DATABASE_PASSWORD={}", read_secret("mempool-db-password", "mempoolpass")),
+                ],
+                None,
+                None,
+            )
+        }
         "electrumx" | "mempool-electrs" | "electrs" => {
             (
                 vec!["50001:50001".to_string()],

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

@@ -84,6 +84,78 @@ pub(super) async fn detect_running_deps() -> Result<RunningDeps> {
     })
 }
 
+/// Detect the container name of the running Bitcoin node so dependent stacks
+/// (mempool) can point CORE_RPC_HOST at the right host. Bitcoin Knots and Bitcoin
+/// Core are both reachable on archy-net by their container name — only the name
+/// differs (`bitcoin-knots` vs `bitcoin-core`), so hardcoding one breaks the
+/// other. Returns the first running BITCOIN_NAMES match; falls back to the
+/// default `bitcoin-knots` if none is detected (callers gate on has_bitcoin).
+pub(super) async fn detect_bitcoin_rpc_host() -> String {
+    let out = tokio::time::timeout(
+        std::time::Duration::from_secs(15),
+        tokio::process::Command::new("podman")
+            .args(["ps", "--format", "{{.Names}}"])
+            .output(),
+    )
+    .await;
+    if let Ok(Ok(o)) = out {
+        if o.status.success() {
+            let running = String::from_utf8_lossy(&o.stdout);
+            if let Some(name) = pick_bitcoin_host(&running) {
+                return name;
+            }
+        }
+    }
+    "bitcoin-knots".to_string()
+}
+
+/// Pure host-selection step of [`detect_bitcoin_rpc_host`], split out so it can
+/// be unit-tested without a podman runtime. Returns the first `podman ps` line
+/// whose trimmed name is one of [`BITCOIN_NAMES`]. (The Quadlet orchestrator
+/// mirrors this in `prod_orchestrator::bitcoin_host`.)
+fn pick_bitcoin_host(podman_names: &str) -> Option<String> {
+    podman_names
+        .lines()
+        .map(|l| l.trim())
+        .find(|name| BITCOIN_NAMES.contains(name))
+        .map(|name| name.to_string())
+}
+
+#[cfg(test)]
+mod bitcoin_host_tests {
+    use super::pick_bitcoin_host;
+
+    #[test]
+    fn picks_knots() {
+        let ps = "electrumx\nbitcoin-knots\narchy-mempool-db\n";
+        assert_eq!(pick_bitcoin_host(ps).as_deref(), Some("bitcoin-knots"));
+    }
+
+    #[test]
+    fn picks_core() {
+        let ps = "lnd\nbitcoin-core\nelectrumx\n";
+        assert_eq!(pick_bitcoin_host(ps).as_deref(), Some("bitcoin-core"));
+    }
+
+    #[test]
+    fn picks_plain_bitcoin() {
+        assert_eq!(pick_bitcoin_host("bitcoin\n").as_deref(), Some("bitcoin"));
+    }
+
+    #[test]
+    fn none_when_no_bitcoin_node() {
+        let ps = "electrumx\nlnd\narchy-mempool-db\n";
+        assert_eq!(pick_bitcoin_host(ps), None);
+    }
+
+    #[test]
+    fn ignores_substring_matches() {
+        // A companion UI container must NOT be mistaken for the node itself.
+        let ps = "archy-bitcoin-ui\nbitcoin-knots-foo\n";
+        assert_eq!(pick_bitcoin_host(ps), None);
+    }
+}
+
 /// Verify that required dependency services are running before installing an app.
 /// Returns an error with a user-friendly message if dependencies are missing.
 pub(super) fn check_install_deps(package_id: &str, deps: &RunningDeps) -> Result<()> {
@@ -304,16 +376,31 @@ pub(super) fn startup_order(package_id: &str) -> &'static [&'static str] {
 /// order for the given app. Unknown containers sort to the end.
 pub(super) async fn ordered_containers_for_start(package_id: &str) -> Result<Vec<String>> {
     let containers = get_containers_for_app(package_id).await?;
+    Ok(order_present_containers(package_id, containers))
+}
+
+/// Order the *actually-present* containers of an app by its dependency-aware
+/// startup order. Containers whose name is unknown to the order list sort to
+/// the end, preserving their relative input order.
+///
+/// This deliberately does NOT inject order entries that aren't live
+/// containers. `startup_order` is a union of container-name variants across
+/// install generations (e.g. `mysql-mempool` vs `archy-mempool-db`), so any
+/// single install only ever has a subset of those names. Injecting a phantom
+/// name makes the start path fail on a "no such object" inspect — and because
+/// `do_orchestrator_package_start` propagates the unknown-app-id fallback
+/// error via `?`, every later member (the api + frontend) is then skipped,
+/// leaving the stack down until the health monitor recovers it minutes later.
+/// That was the source of mempool gate flakes #73 (frontend) / #74 (api).
+fn order_present_containers(package_id: &str, containers: Vec<String>) -> Vec<String> {
+    if containers.is_empty() {
+        // Nothing is live under any known name. Fall back to the package id so
+        // a single-container app whose container matches its id still gets one
+        // start attempt; multi-container stacks with no live members are
+        // surfaced as "no containers" by the caller's emptiness check.
+        return vec![package_id.to_string()];
+    }
     let order = startup_order(package_id);
-    if order.is_empty() && containers.is_empty() {
-        return Ok(vec![package_id.to_string()]);
-    }
-    let mut sorted = containers;
-    for required in order {
-        if !sorted.iter().any(|name| name == required) {
-            sorted.push((*required).to_string());
-        }
-    }
     // If no special order is defined, fall back to mempool order for legacy
     // multi-container names that may still be returned by config lookups.
     let effective_order: &[&str] = if order.is_empty() {
@@ -321,8 +408,14 @@ pub(super) async fn ordered_containers_for_start(package_id: &str) -> Result<Vec
     } else {
         order
     };
-    sorted.sort_by_key(|c| effective_order.iter().position(|o| *o == c).unwrap_or(99));
-    Ok(sorted)
+    let mut sorted = containers;
+    sorted.sort_by_key(|c| {
+        effective_order
+            .iter()
+            .position(|o| *o == c)
+            .unwrap_or(usize::MAX)
+    });
+    sorted
 }
 
 /// Configure Fedimint Gateway to use LND instead of LDK.
@@ -380,7 +473,48 @@ pub(super) fn configure_fedimint_lnd(
 
 #[cfg(test)]
 mod tests {
-    use super::{requires_unpruned_bitcoin, startup_order};
+    use super::{order_present_containers, requires_unpruned_bitcoin, startup_order};
+
+    #[test]
+    fn order_present_containers_never_injects_phantom_stack_members() {
+        // The live mempool stack on a node: db + api + frontend. These are the
+        // only real container names; the startup_order list also contains
+        // variant/legacy names (mysql-mempool, archy-mempool-api, ...) that are
+        // NOT live here and must never appear in the result — a phantom name in
+        // the start list aborts the orchestrator start mid-sequence (gate
+        // #73/#74).
+        let present = vec![
+            "mempool".to_string(),
+            "mempool-api".to_string(),
+            "archy-mempool-db".to_string(),
+        ];
+        let ordered = order_present_containers("mempool", present);
+        // Dependency order: db -> api -> frontend.
+        assert_eq!(ordered, vec!["archy-mempool-db", "mempool-api", "mempool"]);
+        // No phantom variants leaked in.
+        for phantom in ["mysql-mempool", "archy-mempool-api", "archy-mempool-web"] {
+            assert!(
+                !ordered.iter().any(|c| c == phantom),
+                "phantom {phantom} must not be injected"
+            );
+        }
+    }
+
+    #[test]
+    fn order_present_containers_orders_known_before_unknown() {
+        let present = vec!["mempool".to_string(), "some-sidecar".to_string()];
+        let ordered = order_present_containers("mempool", present);
+        // The known frontend sorts ahead of an unknown sidecar.
+        assert_eq!(ordered, vec!["mempool", "some-sidecar"]);
+    }
+
+    #[test]
+    fn order_present_containers_empty_falls_back_to_package_id() {
+        assert_eq!(
+            order_present_containers("mempool", vec![]),
+            vec!["mempool".to_string()]
+        );
+    }
 
     #[test]
     fn btcpay_start_order_includes_required_stack_members() {

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

@@ -22,6 +22,11 @@ const PODMAN_LOG_TIMEOUT: Duration = Duration::from_secs(15);
 /// Per-container graceful shutdown timeout in seconds.
 /// Bitcoin Core needs 600s to flush UTXO set, LND 330s for channel state,
 /// indexers 300s for index flush, databases 120s for WAL/transaction commit.
+///
+/// MIRRORS `archipelago_container::runtime::stop_grace_secs_for` (which returns
+/// `u64` and is the canonical table used by the orchestrator stop path). This
+/// `&str` variant exists for the legacy `podman stop -t <s>` call sites here —
+/// keep the two tables in sync until those are migrated to the orchestrator.
 pub fn stop_timeout_secs(container_name: &str) -> &'static str {
     let id = container_name
         .strip_prefix("archy-")
@@ -307,7 +312,16 @@ impl RpcHandler {
 
         let mut stopped = 0u32;
         let mut removed = 0u32;
-        let mut errors = Vec::new();
+        // Two distinct failure classes, kept separate so they don't get
+        // conflated (the old single `errors` vec did, which caused the "ghost in
+        // My Apps" bug): `container_errors` means a container could NOT be
+        // removed (force-rm failed too) — the app is genuinely still present, so
+        // we keep its state entry and surface a hard error. `cleanup_errors`
+        // means volume/network/data-dir teardown left residue — the containers
+        // are already gone, so the app IS uninstalled and MUST disappear from My
+        // Apps; the residue is logged but never ghosts the app.
+        let mut container_errors: Vec<String> = Vec::new();
+        let mut cleanup_errors: Vec<String> = Vec::new();
 
         self.set_uninstall_stage(
             package_id,
@@ -365,7 +379,7 @@ impl RpcHandler {
                             let msg =
                                 format!("Failed to remove {}: {}; {}", name, stderr.trim(), e);
                             tracing::error!("Uninstall {}: {}", package_id, msg);
-                            errors.push(msg);
+                            container_errors.push(msg);
                         }
                     }
                 }
@@ -374,12 +388,35 @@ impl RpcHandler {
                     Err(force_err) => {
                         let msg = format!("Failed to remove {}: {}; {}", name, e, force_err);
                         tracing::error!("Uninstall {}: {}", package_id, msg);
-                        errors.push(msg);
+                        container_errors.push(msg);
                     }
                 },
             }
         }
 
+        // A container that survived even force-remove means the app is NOT
+        // actually uninstalled — keep its state entry and fail so the spawned
+        // task reverts it to its prior state (and the user can retry), rather
+        // than orphaning a live container that's missing from My Apps.
+        if !container_errors.is_empty() {
+            tracing::error!(
+                "Uninstall {}: containers could not be removed: {:?}",
+                package_id,
+                container_errors
+            );
+            return Err(anyhow::anyhow!(
+                "Uninstall {} failed: {}",
+                package_id,
+                container_errors.join("; ")
+            ));
+        }
+
+        // Containers are gone → the app is uninstalled. Remove its state entry
+        // NOW, before the (possibly slow, possibly fallible) volume/data
+        // teardown below, so My Apps updates immediately and a residue failure
+        // can never leave a ghost. Reinstall/scan no longer see a stale entry.
+        self.remove_package_state_entry(package_id).await;
+
         self.set_uninstall_stage(package_id, "Cleaning up volumes")
             .await;
         // Avoid global Podman volume prune on production nodes: store-wide
@@ -427,70 +464,73 @@ impl RpcHandler {
                         let stderr = String::from_utf8_lossy(&o.stderr);
                         let msg = format!("Failed to remove data {}: {}", dir, stderr.trim());
                         tracing::error!("Uninstall {}: {}", package_id, msg);
-                        errors.push(msg);
+                        cleanup_errors.push(msg);
                     }
                     Err(e) => {
                         let msg = format!("Failed to remove data {}: {}", dir, e);
                         tracing::error!("Uninstall {}: {}", package_id, msg);
-                        errors.push(msg);
+                        cleanup_errors.push(msg);
                     }
                     _ => {}
                 }
             }
         }
 
-        if !errors.is_empty() {
+        // The app is already gone from My Apps (entry removed above). Residual
+        // volume/data cleanup failures are logged but NEVER ghost the app — a
+        // reinstall and the next uninstall both tolerate leftover dirs.
+        if !cleanup_errors.is_empty() {
             tracing::error!(
-                "Uninstall {} completed with errors: {:?}",
+                "Uninstall {} removed but left cleanup residue: {:?}",
                 package_id,
-                errors
+                cleanup_errors
             );
-            return Err(anyhow::anyhow!(
-                "Uninstall {} partially failed: {}",
-                package_id,
-                errors.join("; ")
-            ));
         }
 
         tracing::info!(
-            "Uninstall {} complete: stopped={}, removed={}",
+            "Uninstall {} complete: stopped={}, removed={}, cleanup_errors={}",
             package_id,
             stopped,
-            removed
+            removed,
+            cleanup_errors.len()
         );
 
-        // Immediately remove from in-memory state so the UI updates without
-        // waiting for the scanner's absence threshold (3 scans × 60s each).
-        {
-            let (mut data, _rev) = self.state_manager.get_snapshot().await;
-            let before = data.package_data.len();
-            data.package_data.remove(package_id);
-            // Also remove any alias keys (e.g. "bitcoin-knots" vs "bitcoin")
-            let aliases: Vec<String> = data
-                .package_data
-                .keys()
-                .filter(|k| {
-                    super::config::all_container_names(package_id)
-                        .iter()
-                        .any(|c| c.strip_prefix("archy-").unwrap_or(c) == k.as_str())
-                })
-                .cloned()
-                .collect();
-            for alias in &aliases {
-                data.package_data.remove(alias);
-            }
-            if data.package_data.len() < before {
-                self.state_manager.update_data(data).await;
-            }
-        }
-
         Ok(serde_json::json!({
             "status": "uninstalled",
             "stopped": stopped,
             "removed": removed,
+            "cleanup_warnings": cleanup_errors,
         }))
     }
 
+    /// Remove a package's entry (and any alias keys) from persisted state so it
+    /// disappears from My Apps immediately, without waiting for the scanner's
+    /// absence threshold (3 scans × 60s). Called as soon as an uninstall has
+    /// removed the app's containers — before the slower volume/data teardown —
+    /// so a residue failure can never leave a ghost entry behind.
+    async fn remove_package_state_entry(&self, package_id: &str) {
+        let (mut data, _rev) = self.state_manager.get_snapshot().await;
+        let before = data.package_data.len();
+        data.package_data.remove(package_id);
+        // Also remove any alias keys (e.g. "bitcoin-knots" vs "bitcoin").
+        let aliases: Vec<String> = data
+            .package_data
+            .keys()
+            .filter(|k| {
+                super::config::all_container_names(package_id)
+                    .iter()
+                    .any(|c| c.strip_prefix("archy-").unwrap_or(c) == k.as_str())
+            })
+            .cloned()
+            .collect();
+        for alias in &aliases {
+            data.package_data.remove(alias);
+        }
+        if data.package_data.len() < before {
+            self.state_manager.update_data(data).await;
+        }
+    }
+
     /// Start a bundled app (create container from pre-loaded image if needed).
     pub(in crate::api::rpc) async fn handle_bundled_app_start(
         &self,

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

@@ -6,7 +6,6 @@
 use crate::api::rpc::RpcHandler;
 use crate::data_model::InstallPhase;
 use anyhow::{Context, Result};
-use base64::Engine;
 use std::process::Output;
 use std::time::Duration;
 use tracing::info;
@@ -434,6 +433,13 @@ async fn wait_for_stack_containers(
     containers: &[&str],
     timeout_secs: u64,
 ) -> Result<()> {
+    // A container can exit on its first start because a dependency (db, redis,
+    // the bitcoin node) was not quite ready — a transient crash, not a broken
+    // install. Restart each exited container a bounded number of times before
+    // declaring the install failed (#25). The runtime supervisor keeps it alive
+    // afterwards, but we want a healthy state by the time install returns.
+    const MAX_RESTARTS: u32 = 3;
+    let mut restarts: std::collections::HashMap<String, u32> = std::collections::HashMap::new();
     let deadline = std::time::Instant::now() + std::time::Duration::from_secs(timeout_secs);
     loop {
         let mut pending = Vec::new();
@@ -449,20 +455,41 @@ async fn wait_for_stack_containers(
                     match state.as_str() {
                         "running" => {}
                         "exited" | "dead" => {
-                            let logs = stack_container_logs(container, 40).await;
-                            install_log(&format!(
-                                "INSTALL CRASH: {} - container {} exited. Logs:\n{}",
-                                stack_name,
-                                container,
-                                logs.chars().take(1000).collect::<String>()
-                            ))
-                            .await;
-                            return Err(anyhow::anyhow!(
-                                "{} container {} exited after install. Logs: {}",
-                                stack_name,
-                                container,
-                                logs.chars().take(500).collect::<String>()
-                            ));
+                            let attempts = restarts.entry(container.to_string()).or_insert(0);
+                            if *attempts < MAX_RESTARTS {
+                                *attempts += 1;
+                                install_log(&format!(
+                                    "INSTALL RESTART: {} - container {} exited, restart attempt {}/{}",
+                                    stack_name, container, *attempts, MAX_RESTARTS
+                                ))
+                                .await;
+                                let _ = podman_stack_output(
+                                    &["start", container],
+                                    PODMAN_STACK_PROBE_TIMEOUT,
+                                )
+                                .await;
+                                pending.push(format!(
+                                    "{}=restarting({}/{})",
+                                    container, *attempts, MAX_RESTARTS
+                                ));
+                            } else {
+                                let logs = stack_container_logs(container, 40).await;
+                                install_log(&format!(
+                                    "INSTALL CRASH: {} - container {} exited after {} restarts. Logs:\n{}",
+                                    stack_name,
+                                    container,
+                                    MAX_RESTARTS,
+                                    logs.chars().take(1000).collect::<String>()
+                                ))
+                                .await;
+                                return Err(anyhow::anyhow!(
+                                    "{} container {} exited after install ({} restarts). Logs: {}",
+                                    stack_name,
+                                    container,
+                                    MAX_RESTARTS,
+                                    logs.chars().take(500).collect::<String>()
+                                ));
+                            }
                         }
                         other => pending.push(format!("{}={}", container, other)),
                     }
@@ -592,16 +619,25 @@ async fn install_stack_via_orchestrator(
     ))
     .await;
 
+    let mut installed = 0usize;
     for app_id in app_ids {
         match orchestrator.install(app_id).await {
             Ok(container_name) => {
+                installed += 1;
                 install_log(&format!(
                     "INSTALL ORCH: {} stack — app {} installed as {}",
                     stack_name, app_id, container_name
                 ))
                 .await;
             }
-            Err(e) if e.to_string().contains("unknown app_id") => {
+            Err(e) if e.to_string().contains("unknown app_id") && installed == 0 => {
+                // None of the stack's manifests are known — the orchestrator
+                // can't render this stack at all, so defer to the legacy
+                // installer. Only safe when NOTHING was installed yet: once an
+                // earlier member is up, falling back would let the legacy path
+                // double-create containers on the same data dir (observed
+                // corrupting an immich postgres cluster — two postmasters, one
+                // PGDATA). A partial set means a deploy bug, not a legacy node.
                 install_log(&format!(
                     "INSTALL ORCH SKIP: {} stack — app {} unknown, falling back to legacy stack installer",
                     stack_name, app_id
@@ -609,6 +645,17 @@ async fn install_stack_via_orchestrator(
                 .await;
                 return Ok(None);
             }
+            Err(e) if e.to_string().contains("unknown app_id") => {
+                install_log(&format!(
+                    "INSTALL ORCH FAIL: {} stack — app {} unknown AFTER {} installed; refusing legacy fallback (would double-create on shared data)",
+                    stack_name, app_id, installed
+                ))
+                .await;
+                return Err(e.context(format!(
+                    "orchestrator stack install {} aborted: app {} has no manifest but {} member(s) already installed — deploy all stack manifests",
+                    stack_name, app_id, installed
+                )));
+            }
             Err(e) => {
                 install_log(&format!(
                     "INSTALL ORCH FAIL: {} stack — app {} failed: {}",
@@ -640,11 +687,42 @@ fn mempool_stack_app_ids() -> &'static [&'static str] {
     &["archy-mempool-db", "mempool-api", "archy-mempool-web"]
 }
 
-const REGISTRY: &str = "146.59.87.168:3000/lfg2025";
+fn immich_stack_app_ids() -> &'static [&'static str] {
+    // Install order = dependency order: db + cache before the server. The server
+    // app_id is the user-facing "immich" (canonical name + icon); its install is
+    // handled here (not recursively) since orchestrator.install bypasses the
+    // package.install routing that maps "immich" → this stack installer.
+    &["immich-postgres", "immich-redis", "immich"]
+}
 
-const NETBIRD_DASHBOARD_IMAGE: &str = "docker.io/netbirdio/dashboard:v2.38.0";
-const NETBIRD_SERVER_IMAGE: &str = "docker.io/netbirdio/netbird-server:0.71.2";
-const NETBIRD_PROXY_IMAGE: &str = "docker.io/library/nginx:1.27-alpine";
+fn netbird_stack_app_ids() -> &'static [&'static str] {
+    // Dependency/startup order: the combined management/signal/relay server
+    // first (it owns the base64 relay/store secrets + the sqlite store, and is
+    // the OIDC issuer the others point at), then the dashboard SPA, then the
+    // user-facing TLS proxy ("netbird", which carries the self-signed cert +
+    // the templated nginx.conf and is the launcher). Mirrors the netbird
+    // startup_order in dependencies.rs.
+    &["netbird-server", "netbird-dashboard", "netbird"]
+}
+
+fn indeedhub_stack_app_ids() -> &'static [&'static str] {
+    // Dependency order: backends + their generated secrets first, then the api
+    // (owns indeedhub-jwt; reads the db/minio secrets the backends materialised),
+    // then the ffmpeg worker, then the user-facing frontend ("indeedhub", which
+    // carries the post_install nginx hook). The frontend's nginx reaches the
+    // backends by their short network_aliases (api/minio/relay) on indeedhub-net.
+    &[
+        "indeedhub-postgres",
+        "indeedhub-redis",
+        "indeedhub-minio",
+        "indeedhub-relay",
+        "indeedhub-api",
+        "indeedhub-ffmpeg",
+        "indeedhub",
+    ]
+}
+
+const REGISTRY: &str = "146.59.87.168:3000/lfg2025";
 
 /// Pull an image with retry and exponential backoff (3 attempts).
 async fn pull_image_with_retry(image: &str) -> Result<()> {
@@ -706,6 +784,17 @@ async fn pull_image_with_retry(image: &str) -> Result<()> {
 impl RpcHandler {
     /// Install Immich stack (postgres + redis + server).
     pub(super) async fn install_immich_stack(&self) -> Result<serde_json::Value> {
+        // Manifest-driven path (workstream B/C): render the stack from
+        // apps/immich-*/manifest.yml via the orchestrator (rootless Quadlet
+        // units, generated_secrets, reboot-survivable). Falls back to the legacy
+        // installer below only when the orchestrator doesn't know these app_ids
+        // (manifests not yet deployed). See docs/PRODUCTION-MASTER-PLAN.md.
+        if let Some(orchestrated) =
+            install_stack_via_orchestrator(self, "immich", immich_stack_app_ids()).await?
+        {
+            return Ok(orchestrated);
+        }
+
         if let Some(adopted) = adopt_stack_if_exists(
             "immich_server",
             "immich",
@@ -1152,6 +1241,9 @@ impl RpcHandler {
         let deps = super::dependencies::detect_running_deps().await?;
         super::dependencies::check_install_deps("mempool", &deps)?;
         let (_, rpc_pass) = crate::bitcoin_rpc::bitcoin_rpc_credentials().await;
+        // CORE_RPC_HOST must match the actual Bitcoin node container name —
+        // bitcoin-knots OR bitcoin-core — else mempool-api can't reach RPC (B12).
+        let bitcoin_rpc_host = super::dependencies::detect_bitcoin_rpc_host().await;
 
         install_log("INSTALL START: mempool (stack: mariadb + mempool-api + mempool-web)").await;
 
@@ -1275,7 +1367,7 @@ impl RpcHandler {
                 "-e",
                 "ELECTRUM_TLS_ENABLED=false",
                 "-e",
-                "CORE_RPC_HOST=bitcoin-knots",
+                &format!("CORE_RPC_HOST={}", bitcoin_rpc_host),
                 "-e",
                 "CORE_RPC_PORT=8332",
                 "-e",
@@ -1352,6 +1444,20 @@ impl RpcHandler {
 
     /// Install the IndeedHub multi-container stack.
     pub(super) async fn install_indeedhub_stack(&self) -> Result<serde_json::Value> {
+        // Manifest-driven path (#20 phase 3): render the 7-member stack from
+        // apps/indeedhub-*/manifest.yml via the orchestrator (dedicated
+        // indeedhub-net + network_aliases, generated_secrets, the frontend's
+        // post_install nginx hook, reboot-survivable). The manifests use the exact
+        // live container names / named volumes, so on an existing node this ADOPTS
+        // the running stack rather than recreating it (data preserved). Falls back
+        // to the legacy installer below only when the orchestrator doesn't know
+        // these app_ids (manifests not yet deployed). See PRODUCTION-MASTER-PLAN.md.
+        if let Some(orchestrated) =
+            install_stack_via_orchestrator(self, "indeedhub", indeedhub_stack_app_ids()).await?
+        {
+            return Ok(orchestrated);
+        }
+
         let registry = crate::container::registry::load_registries(&self.config.data_dir)
             .await
             .unwrap_or_default()
@@ -1727,6 +1833,27 @@ impl RpcHandler {
 
     /// Install self-hosted NetBird (dashboard + combined management/signal/relay server).
     pub(super) async fn install_netbird_stack(&self) -> Result<serde_json::Value> {
+        // Manifest-driven path (#20 phase 4): render the 3-member stack from
+        // apps/netbird-*/manifest.yml via the orchestrator — dedicated
+        // netbird-net + network_aliases, base64 generated_secrets, a self-signed
+        // TLS cert (generated_certs) so the dashboard gets a secure context for
+        // OIDC PKCE (#15), and templated config.yaml/nginx.conf rendered from
+        // host facts + the netbird-net gateway. The manifests use the exact live
+        // container names, so on an existing node this ADOPTS the running stack
+        // rather than recreating it (the sqlite store + base64 keys are
+        // preserved — ensure_generated_secrets no-ops on existing files).
+        //
+        // #20 ph4: the legacy hardcoded `podman run` installer was DELETED — the
+        // signed catalog always ships apps/netbird-*/manifest.yml, so there is no
+        // in-Rust fallback. If the orchestrator doesn't know these app_ids and no
+        // running stack exists to adopt, install errors rather than silently
+        // diverging from the manifest contract.
+        if let Some(orchestrated) =
+            install_stack_via_orchestrator(self, "netbird", netbird_stack_app_ids()).await?
+        {
+            return Ok(orchestrated);
+        }
+
         if let Some(adopted) = adopt_stack_if_exists(
             "netbird",
             "netbird",
@@ -1737,271 +1864,12 @@ impl RpcHandler {
             return Ok(adopted);
         }
 
-        install_log("INSTALL START: netbird stack (dashboard + server)").await;
-        info!("Installing self-hosted NetBird stack");
-
-        self.set_install_phase("netbird", InstallPhase::PullingImage)
-            .await;
-        for (i, image) in [
-            NETBIRD_DASHBOARD_IMAGE,
-            NETBIRD_SERVER_IMAGE,
-            NETBIRD_PROXY_IMAGE,
-        ]
-        .iter()
-        .enumerate()
-        {
-            self.set_install_progress("netbird", i as u64, 3).await;
-            pull_image_with_retry(image)
-                .await
-                .with_context(|| format!("Failed to pull NetBird image: {}", image))?;
-        }
-        self.set_install_progress("netbird", 3, 3).await;
-
-        for name in ["netbird", "netbird-dashboard", "netbird-server"] {
-            let _ = podman_stack_status(&["rm", "-f", name], PODMAN_STACK_PROBE_TIMEOUT).await;
-        }
-        let _ = podman_stack_status(
-            &["network", "rm", "-f", "netbird-net"],
-            PODMAN_STACK_PROBE_TIMEOUT,
+        anyhow::bail!(
+            "netbird manifests not available on this node — the signed catalog must provide apps/netbird-*/manifest.yml (legacy hardcoded installer removed in #20 ph4)"
         )
-        .await;
-
-        self.set_install_phase("netbird", InstallPhase::CreatingContainer)
-            .await;
-
-        tokio::fs::create_dir_all("/var/lib/archipelago/netbird/data")
-            .await
-            .context("Failed to create NetBird data directory")?;
-
-        let host_ip = detect_netbird_public_host_ip()
-            .await
-            .unwrap_or_else(|| self.config.host_ip.clone());
-        write_netbird_config_files(&host_ip).await?;
-
-        let _ = podman_stack_status(
-            &["network", "create", "netbird-net"],
-            PODMAN_STACK_PROBE_TIMEOUT,
-        )
-        .await;
-
-        let mut server_cmd = tokio::process::Command::new("podman");
-        server_cmd.args([
-            "run",
-            "-d",
-            "--name",
-            "netbird-server",
-            "--network",
-            "netbird-net",
-            "--network-alias",
-            "netbird-server",
-            "--restart=unless-stopped",
-            "-p",
-            "8086:80",
-            "-p",
-            "3478:3478/udp",
-            "-v",
-            "/var/lib/archipelago/netbird/data:/var/lib/netbird",
-            "-v",
-            "/var/lib/archipelago/netbird/config.yaml:/etc/netbird/config.yaml:ro",
-            NETBIRD_SERVER_IMAGE,
-            "--config",
-            "/etc/netbird/config.yaml",
-        ]);
-        run_required_stack_command("netbird", "create server", &mut server_cmd).await?;
-
-        self.set_install_phase("netbird", InstallPhase::StartingContainer)
-            .await;
-        tokio::time::sleep(std::time::Duration::from_secs(5)).await;
-
-        let mut dashboard_cmd = tokio::process::Command::new("podman");
-        dashboard_cmd.args([
-            "run",
-            "-d",
-            "--name",
-            "netbird-dashboard",
-            "--network",
-            "netbird-net",
-            "--restart=unless-stopped",
-            "--env-file",
-            "/var/lib/archipelago/netbird/dashboard.env",
-            NETBIRD_DASHBOARD_IMAGE,
-        ]);
-        run_required_stack_command("netbird", "create dashboard", &mut dashboard_cmd).await?;
-
-        let mut proxy_cmd = tokio::process::Command::new("podman");
-        proxy_cmd.args([
-            "run",
-            "-d",
-            "--name",
-            "netbird",
-            "--network",
-            "netbird-net",
-            "--restart=unless-stopped",
-            "-p",
-            "8087:80",
-            "-v",
-            "/var/lib/archipelago/netbird/nginx.conf:/etc/nginx/conf.d/default.conf:ro",
-            NETBIRD_PROXY_IMAGE,
-        ]);
-        run_required_stack_command("netbird", "create unified proxy", &mut proxy_cmd).await?;
-
-        wait_for_stack_containers(
-            "netbird",
-            &["netbird-server", "netbird-dashboard", "netbird"],
-            60,
-        )
-        .await?;
-
-        self.set_install_phase("netbird", InstallPhase::WaitingHealthy)
-            .await;
-        self.set_install_phase("netbird", InstallPhase::PostInstall)
-            .await;
-        self.set_install_phase("netbird", InstallPhase::Done).await;
-        self.clear_install_progress("netbird").await;
-
-        install_log("INSTALL OK: netbird stack").await;
-        info!("NetBird stack installed");
-        Ok(serde_json::json!({
-            "success": true,
-            "package_id": "netbird",
-            "message": "NetBird self-hosted stack installed",
-        }))
     }
 }
 
-async fn read_or_generate_b64_secret(name: &str) -> String {
-    let path = format!("/var/lib/archipelago/secrets/{}", name);
-    if let Ok(val) = tokio::fs::read_to_string(&path).await {
-        let trimmed = val.trim().to_string();
-        if !trimmed.is_empty() {
-            return trimmed;
-        }
-    }
-    let mut buf = [0u8; 32];
-    rand::RngCore::fill_bytes(&mut rand::rngs::OsRng, &mut buf);
-    let secret = base64::engine::general_purpose::STANDARD.encode(buf);
-    let _ = tokio::fs::create_dir_all("/var/lib/archipelago/secrets").await;
-    let _ = tokio::fs::write(&path, &secret).await;
-    secret
-}
-
-async fn write_netbird_config_files(host_ip: &str) -> Result<()> {
-    let public_origin = format!("http://{}:8087", host_ip);
-    let server_origin = format!("http://{}:8086", host_ip);
-    let relay_secret = read_or_generate_b64_secret("netbird-relay-auth-secret").await;
-    let encryption_key = read_or_generate_b64_secret("netbird-store-encryption-key").await;
-    let config = format!(
-        r#"server:
-  listenAddress: ":80"
-  exposedAddress: "{public_origin}"
-  stunPorts:
-    - 3478
-  metricsPort: 9090
-  healthcheckAddress: ":9000"
-  logLevel: "info"
-  logFile: "console"
-  authSecret: "{relay_secret}"
-  dataDir: "/var/lib/netbird"
-  auth:
-    issuer: "{public_origin}/oauth2"
-    localAuthDisabled: false
-    signKeyRefreshEnabled: false
-    dashboardRedirectURIs:
-      - "{public_origin}/nb-auth"
-      - "{public_origin}/nb-silent-auth"
-    dashboardPostLogoutRedirectURIs:
-      - "{public_origin}/"
-    cliRedirectURIs:
-      - "http://localhost:53000/"
-  store:
-    engine: "sqlite"
-    encryptionKey: "{encryption_key}"
-"#
-    );
-    tokio::fs::write("/var/lib/archipelago/netbird/config.yaml", config)
-        .await
-        .context("Failed to write NetBird config.yaml")?;
-
-    let dashboard_env = format!(
-        r#"NETBIRD_MGMT_API_ENDPOINT={public_origin}
-NETBIRD_MGMT_GRPC_API_ENDPOINT={public_origin}
-AUTH_AUDIENCE=netbird-dashboard
-AUTH_CLIENT_ID=netbird-dashboard
-AUTH_CLIENT_SECRET=
-AUTH_AUTHORITY={public_origin}/oauth2
-USE_AUTH0=false
-AUTH_SUPPORTED_SCOPES=openid profile email groups
-AUTH_REDIRECT_URI=/nb-auth
-AUTH_SILENT_REDIRECT_URI=/nb-silent-auth
-NETBIRD_TOKEN_SOURCE=idToken
-NGINX_SSL_PORT=443
-LETSENCRYPT_DOMAIN=none
-"#
-    );
-    tokio::fs::write("/var/lib/archipelago/netbird/dashboard.env", dashboard_env)
-        .await
-        .context("Failed to write NetBird dashboard.env")?;
-
-    let nginx_conf = format!(
-        r#"server {{
-    listen 80;
-    server_name _;
-
-    # Route browser API/auth through the host-published server port. Rootless
-    # Podman can give netbird-server a new container IP on restart while nginx
-    # keeps an old resolved address, which breaks login with 502s.
-
-    proxy_set_header Host $host;
-    proxy_set_header X-Real-IP $remote_addr;
-    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    proxy_set_header X-Forwarded-Proto $scheme;
-    proxy_http_version 1.1;
-
-    location ~ ^/(relay|ws-proxy/) {{
-        proxy_pass http://host.containers.internal:8086;
-        proxy_set_header Upgrade $http_upgrade;
-        proxy_set_header Connection "upgrade";
-        proxy_read_timeout 1d;
-    }}
-
-    location ~ ^/(api|oauth2)(/|$) {{
-        proxy_pass http://host.containers.internal:8086;
-    }}
-
-    location ~ ^/(signalexchange\.SignalExchange|management\.ManagementService|management\.ProxyService)/ {{
-        grpc_pass grpc://netbird-server:80;
-        grpc_read_timeout 1d;
-        grpc_send_timeout 1d;
-    }}
-
-    location / {{
-        proxy_pass http://netbird-dashboard:80;
-    }}
-}}
-
-# Direct server remains available for diagnostics at {server_origin}.
-"#
-    );
-    tokio::fs::write("/var/lib/archipelago/netbird/nginx.conf", nginx_conf)
-        .await
-        .context("Failed to write NetBird nginx.conf")?;
-
-    Ok(())
-}
-
-async fn detect_netbird_public_host_ip() -> Option<String> {
-    let output = tokio::process::Command::new("hostname")
-        .args(["-I"])
-        .output()
-        .await
-        .ok()?;
-    let stdout = String::from_utf8_lossy(&output.stdout);
-    stdout
-        .split_whitespace()
-        .find(|ip| ip.starts_with("100.") && ip.contains('.'))
-        .map(str::to_string)
-}
-
 #[cfg(test)]
 mod tests {
     use super::{btcpay_stack_app_ids, mempool_stack_app_ids};

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

@@ -32,8 +32,11 @@ impl RpcHandler {
             .ok_or_else(|| anyhow::anyhow!("Missing package id"))?;
         validate_app_id(package_id)?;
 
-        // Verify an update is actually available
-        let pinned = image_versions::pinned_image_for_app(package_id)
+        // Verify an update is actually available. Prefer the remote app catalog
+        // (decoupled from the binary OTA), falling back to the image-versions.sh
+        // pin when the catalog is absent or doesn't cover this app.
+        let pinned = crate::container::app_catalog::catalog_primary_image(package_id)
+            .or_else(|| image_versions::pinned_image_for_app(package_id))
             .ok_or_else(|| anyhow::anyhow!("No pinned image found for {}", package_id))?;
 
         // Note: the `already updating` guard lives in `spawn_package_update`
@@ -149,6 +152,28 @@ impl RpcHandler {
         }
     }
 
+    /// Manual "check for updates": refresh the remote app catalog now. The
+    /// package scanner recomputes each app's `available-update` from the fresh
+    /// catalog on its next cycle and pushes it to the UI. Best-effort — a fetch
+    /// failure leaves the cached catalog in place and reports `refreshed: false`.
+    pub(in crate::api::rpc) async fn handle_package_check_updates(
+        &self,
+        _params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        match crate::container::app_catalog::refresh_catalog(&self.config.data_dir).await {
+            Ok(count) => Ok(serde_json::json!({
+                "status": "ok",
+                "refreshed": true,
+                "catalog_apps": count,
+            })),
+            Err(e) => Ok(serde_json::json!({
+                "status": "ok",
+                "refreshed": false,
+                "error": e.to_string(),
+            })),
+        }
+    }
+
     /// Core update execution: stop → pull → remove → recreate → verify.
     async fn execute_update(
         &self,
@@ -385,13 +410,24 @@ impl RpcHandler {
         package_id: &str,
         pinned_primary: &str,
     ) -> Vec<(String, String)> {
-        let stack_images = image_versions::pinned_images_for_stack(package_id);
+        let mut stack_images = image_versions::pinned_images_for_stack(package_id);
         if stack_images.is_empty() {
-            // Single container app
-            vec![(package_id.to_string(), pinned_primary.to_string())]
-        } else {
-            stack_images
+            // Single container app — pinned_primary already prefers the catalog.
+            return vec![(package_id.to_string(), pinned_primary.to_string())];
         }
+        // Stack app: override per-container images with the catalog where it
+        // provides them; components the catalog omits keep the image-versions.sh
+        // pin. This lets a single component (e.g. the IndeeHub frontend) be
+        // bumped without touching the rest of the stack.
+        let catalog_images = crate::container::app_catalog::catalog_stack_images(package_id);
+        if !catalog_images.is_empty() {
+            for (name, image) in stack_images.iter_mut() {
+                if let Some(catalog_image) = catalog_images.get(name) {
+                    *image = catalog_image.clone();
+                }
+            }
+        }
+        stack_images
     }
 
     /// Rollback: restart old containers if they still exist.

core/archipelago/src/api/rpc/seed_rpc.rs

@@ -60,6 +60,30 @@ impl RpcHandler {
     /// Generate a new 24-word BIP-39 mnemonic, derive and persist node keys.
     /// Returns the words for the user to write down.
     pub(in crate::api::rpc) async fn handle_seed_generate(&self) -> Result<serde_json::Value> {
+        // Serialize concurrent / retried generate calls. The web client aborts
+        // at 15s and retries internally (up to 3x), and the onboarding view
+        // re-fires every 4s while the server is still booting on slow first-boot
+        // hardware. Without this guard each hit would mint a brand-new seed and
+        // overwrite the node keys mid-flight, leaving the words shown to the user
+        // out of sync with what `seed.verify` expects — the classic "error at the
+        // DID-creation screen". Holding the lock across the whole op fully
+        // serializes them.
+        let mut state = ONBOARDING_MNEMONIC.lock().await;
+
+        // Idempotent fast-path: a fresh pending mnemonic already exists, so the
+        // node keys are already on disk. Return the SAME words rather than
+        // regenerating, so every retry yields a consistent result.
+        if let Some(existing) = state.as_ref() {
+            if existing.created_at.elapsed() < MNEMONIC_TTL {
+                let words: Vec<String> = existing
+                    .words
+                    .split_whitespace()
+                    .map(str::to_string)
+                    .collect();
+                return Ok(serde_json::json!({ "words": words }));
+            }
+        }
+
         let (mnemonic, seed) = crate::seed::MasterSeed::generate()?;
 
         // Derive and write node Ed25519 key.
@@ -89,16 +113,14 @@ impl RpcHandler {
         // the onboarding RPC returns immediately.
         spawn_post_onboarding_fips_activate(self.config.data_dir.clone());
 
-        let words: Vec<&str> = mnemonic.words().collect();
+        let words: Vec<String> = mnemonic.words().map(str::to_string).collect();
 
-        // Hold mnemonic in memory for the verify step.
-        {
-            let mut state = ONBOARDING_MNEMONIC.lock().await;
-            *state = Some(OnboardingMnemonicState {
-                words: mnemonic.to_string(),
-                created_at: std::time::Instant::now(),
-            });
-        }
+        // Hold mnemonic in memory for the verify step. We already own the lock
+        // guard (`state`) from the top of the function, so just write through it.
+        *state = Some(OnboardingMnemonicState {
+            words: mnemonic.to_string(),
+            created_at: std::time::Instant::now(),
+        });
 
         Ok(serde_json::json!({
             "words": words,
@@ -149,11 +171,13 @@ impl RpcHandler {
         let nostr_keys = crate::seed::derive_node_nostr_key(&seed)?;
         let nostr_npub = nostr_keys.public_key().to_bech32().unwrap_or_default();
 
-        // Clear mnemonic from memory now that it's verified.
-        {
-            let mut state = ONBOARDING_MNEMONIC.lock().await;
-            *state = None;
-        }
+        // Intentionally DO NOT clear the mnemonic here. The web client aborts
+        // slow requests at 15s and retries internally; if we wiped it on the
+        // first (successful) verify, a retried request would fail with
+        // "No pending seed generation or session expired" even though the user
+        // did everything right. The mnemonic is bounded by MNEMONIC_TTL (10 min)
+        // and is overwritten on the next generate, so leaving it makes verify
+        // idempotent without meaningfully widening the in-memory window.
 
         // Save the encrypted seed for convenience backup.
         // Use empty passphrase placeholder — the real encrypted save happens via seed.save-encrypted.
@@ -290,4 +314,101 @@ impl RpcHandler {
             "next_index": next_index,
         }))
     }
+
+    /// Reveal the node's 24-word recovery phrase after onboarding. Heavily
+    /// gated, because this is the keys to the whole node:
+    ///   - requires a full authenticated session (enforced upstream: this
+    ///     method is NOT in the public auth whitelist),
+    ///   - re-verifies the login password,
+    ///   - requires a valid TOTP code when 2FA is enabled (replay-protected),
+    ///   - decrypts `identity/master_seed.enc` with the backup passphrase
+    ///     (defaults to the login password when the user used the same value).
+    /// The words are returned to the caller only and never logged.
+    pub(in crate::api::rpc) async fn handle_seed_reveal(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.unwrap_or_default();
+        let mut password = params
+            .get("password")
+            .and_then(|v| v.as_str())
+            .unwrap_or("")
+            .to_string();
+        if password.is_empty() {
+            anyhow::bail!("Password is required to reveal the recovery phrase");
+        }
+
+        // Nothing to reveal if this node never stored an encrypted seed.
+        if !crate::seed::seed_exists(&self.config.data_dir) {
+            anyhow::bail!(
+                "This node has no encrypted seed backup, so the recovery phrase \
+                 cannot be shown. It was only displayed once during setup."
+            );
+        }
+
+        // 1) Re-authenticate with the login password.
+        if !self.auth_manager.verify_password(&password).await? {
+            password.zeroize();
+            anyhow::bail!("Incorrect password");
+        }
+
+        // 2) Require a valid 2FA code when TOTP is enabled (replay-protected).
+        if self.auth_manager.is_totp_enabled().await.unwrap_or(false) {
+            let code = params
+                .get("code")
+                .and_then(|v| v.as_str())
+                .unwrap_or("")
+                .to_string();
+            if code.is_empty() {
+                password.zeroize();
+                anyhow::bail!("A 2FA code is required to reveal the recovery phrase");
+            }
+            let totp_data = self
+                .auth_manager
+                .get_totp_data()
+                .await?
+                .ok_or_else(|| anyhow::anyhow!("2FA is enabled but no TOTP data found"))?;
+            let secret = crate::totp::decrypt_secret(&totp_data, &password)
+                .context("Could not unlock 2FA with this password")?;
+            match crate::totp::verify_code(&secret, &code, &totp_data.used_steps)? {
+                Some(step) => {
+                    // Record the used step for replay protection, pruning old ones.
+                    let mut data = totp_data;
+                    data.used_steps.push(step);
+                    let now = std::time::SystemTime::now()
+                        .duration_since(std::time::UNIX_EPOCH)
+                        .unwrap_or_default()
+                        .as_secs() as i64;
+                    let cutoff = (now / 30) - 10; // ~5 minutes
+                    data.used_steps.retain(|s| *s > cutoff);
+                    let _ = self.auth_manager.update_totp(data).await;
+                }
+                None => {
+                    password.zeroize();
+                    anyhow::bail!("Invalid 2FA code");
+                }
+            }
+        }
+
+        // 3) Decrypt the stored seed. The backup passphrase may differ from the
+        //    login password, so accept an explicit one and fall back to the
+        //    password when the user used the same value for both.
+        let passphrase = params
+            .get("passphrase")
+            .and_then(|v| v.as_str())
+            .map(|s| s.to_string());
+        let secret_phrase = passphrase.unwrap_or_else(|| password.clone());
+        let reveal = crate::seed::load_seed_encrypted(&self.config.data_dir, &secret_phrase).await;
+        password.zeroize();
+        let mnemonic = reveal.map_err(|_| {
+            anyhow::anyhow!(
+                "Could not decrypt the saved seed. If you set a separate backup \
+                 passphrase during setup, enter that passphrase."
+            )
+        })?;
+
+        let words: Vec<String> = mnemonic.words().map(|w| w.to_string()).collect();
+        let word_count = words.len();
+        Ok(serde_json::json!({ "words": words, "word_count": word_count }))
+    }
 }

core/archipelago/src/api/rpc/streaming.rs

@@ -205,6 +205,64 @@ impl RpcHandler {
         }
     }
 
+    /// Build a payment token for a remote seeder (payer side, cross-mint aware).
+    ///
+    /// Given the seeder's advertised `accepted_mints` and `price_sats`, builds a
+    /// `cashuA` token denominated in one of those mints — paying directly if we
+    /// already hold the right mint, else auto-swapping into a trusted accepted
+    /// mint (within `max_fee_sats`). If the price is over `budget_sats`, the
+    /// wallet can't cover it, or the swap is too costly, returns `declined` so
+    /// the caller falls back to the free origin (origin always wins).
+    pub(super) async fn handle_streaming_prepare_payment(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let accepted_mints: Vec<String> = params
+            .get("accepted_mints")
+            .and_then(|v| v.as_array())
+            .map(|arr| {
+                arr.iter()
+                    .filter_map(|v| v.as_str().map(|s| s.to_string()))
+                    .collect()
+            })
+            .unwrap_or_default();
+        let price_sats = params
+            .get("price_sats")
+            .or_else(|| params.get("amount_sats"))
+            .and_then(|v| v.as_u64())
+            .ok_or_else(|| anyhow::anyhow!("Missing price_sats"))?;
+        // Default budget = the asked price (willing to pay exactly what's quoted).
+        let budget_sats = params
+            .get("budget_sats")
+            .and_then(|v| v.as_u64())
+            .unwrap_or(price_sats);
+        let max_fee_sats = params
+            .get("max_fee_sats")
+            .and_then(|v| v.as_u64())
+            .unwrap_or(0);
+
+        let policy = crate::swarm::payment::PaymentPolicy::with_budget(budget_sats, max_fee_sats);
+        match crate::swarm::payment::auto_pay_token(
+            &self.config.data_dir,
+            &policy,
+            &accepted_mints,
+            price_sats,
+        )
+        .await?
+        {
+            Some(token) => Ok(serde_json::json!({
+                "status": "ready",
+                "token": token,
+                "paid_sats": price_sats,
+            })),
+            None => Ok(serde_json::json!({
+                "status": "declined",
+                "message": "payment declined (over budget, unpayable, or swap too costly) — use free origin",
+            })),
+        }
+    }
+
     /// Discover available streaming services (pricing info).
     /// This is the unauthenticated discovery endpoint.
     pub(super) async fn handle_streaming_discover(&self) -> Result<serde_json::Value> {

core/archipelago/src/api/rpc/update.rs

@@ -253,6 +253,54 @@ impl RpcHandler {
         Ok(serde_json::json!({ "mirrors": list }))
     }
 
+    /// Report the node's swarm prefs (fetch source + whether it provides to the
+    /// swarm) plus swarm capability, so the UI can show whether DHT mode is
+    /// actually usable on this build.
+    pub(super) async fn handle_update_get_source(&self) -> Result<serde_json::Value> {
+        let source = update::load_update_source(&self.config.data_dir).await;
+        let provide_dht = update::load_provide_dht(&self.config.data_dir).await;
+        let source_str = match source {
+            update::UpdateSource::Origin => "origin",
+            update::UpdateSource::Swarm => "swarm",
+        };
+        Ok(serde_json::json!({
+            "source": source_str,
+            // Whether this node seeds/serves blobs to peers (default true).
+            "provide_dht": provide_dht,
+            // Compiled with the iroh swarm engine? If false, "swarm" mode has no
+            // peers and silently behaves like origin.
+            "swarm_available": cfg!(feature = "iroh-swarm"),
+            // Runtime swarm-assist gate from config (ARCHIPELAGO_SWARM_ENABLED).
+            "swarm_enabled": self.config.swarm_enabled,
+        }))
+    }
+
+    /// Update the node's swarm prefs. Params (both optional, at least one):
+    /// `{ source?: "origin" | "swarm", provide?: bool }`.
+    pub(super) async fn handle_update_set_source(
+        &self,
+        params: &serde_json::Value,
+    ) -> Result<serde_json::Value> {
+        let mut touched = false;
+        if let Some(s) = params.get("source").and_then(|v| v.as_str()) {
+            let source = match s {
+                "origin" => update::UpdateSource::Origin,
+                "swarm" => update::UpdateSource::Swarm,
+                _ => anyhow::bail!("source must be \"origin\" or \"swarm\""),
+            };
+            update::save_update_source(&self.config.data_dir, source).await?;
+            touched = true;
+        }
+        if let Some(provide) = params.get("provide").and_then(|v| v.as_bool()) {
+            update::save_provide_dht(&self.config.data_dir, provide).await?;
+            touched = true;
+        }
+        if !touched {
+            anyhow::bail!("expected \"source\" and/or \"provide\"");
+        }
+        self.handle_update_get_source().await
+    }
+
     /// Add a mirror to the end of the list. Params: `{ url, label? }`.
     /// Duplicates (same URL) are replaced rather than added twice.
     pub(super) async fn handle_update_add_mirror(

core/archipelago/src/api/rpc/wallet.rs

@@ -1,12 +1,34 @@
 use super::RpcHandler;
-use crate::wallet::{ecash, profits};
+use crate::wallet::{ecash, fedimint_client, profits};
 use anyhow::Result;
 
+/// A Cashu token (NUT-00 `cashuA`/`cashuB`, or our legacy `cashuSend_` form)
+/// always starts with `cashu`. Fedimint ecash notes never do, so a non-`cashu`
+/// string is routed to the Fedimint reissue path.
+fn is_cashu_token(token: &str) -> bool {
+    token.trim_start().starts_with("cashu")
+}
+
 impl RpcHandler {
     pub(super) async fn handle_wallet_ecash_balance(&self) -> Result<serde_json::Value> {
         let wallet = ecash::load_wallet(&self.config.data_dir).await?;
+        let cashu_sats = wallet.balance();
+        // Spendable Fedimint balance too, so callers (e.g. the pay-for-file
+        // pre-check) see funds available across BOTH backends (#3). Best-effort:
+        // if fmcd isn't installed/joined this is just 0, never an error.
+        let fedimint_sats = match fedimint_client::FedimintClient::from_node(&self.config.data_dir)
+            .await
+        {
+            Ok(client) => client.total_balance_sats().await.unwrap_or(0),
+            Err(_) => 0,
+        };
         Ok(serde_json::json!({
-            "balance_sats": wallet.balance(),
+            // `balance_sats` stays Cashu-only for back-compat; `total_sats` is the
+            // spendable amount across Cashu + Fedimint.
+            "balance_sats": cashu_sats,
+            "cashu_sats": cashu_sats,
+            "fedimint_sats": fedimint_sats,
+            "total_sats": cashu_sats + fedimint_sats,
             "proof_count": wallet.proofs.iter().filter(|p| !p.spent && !p.reserved).count(),
             "mint_url": wallet.mint_url,
         }))
@@ -129,18 +151,42 @@ impl RpcHandler {
         let token = params
             .get("token")
             .and_then(|v| v.as_str())
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
             .ok_or_else(|| anyhow::anyhow!("Missing token"))?;
 
-        let amount = ecash::receive_token(&self.config.data_dir, token).await?;
+        // Dual-ecash: one "Receive ecash" box accepts either a Cashu token
+        // (redeemed at the mint) or Fedimint notes (reissued via the fmcd
+        // sidecar). Detect by prefix and route accordingly.
+        if is_cashu_token(token) {
+            let amount = ecash::receive_token(&self.config.data_dir, token).await?;
+            return Ok(serde_json::json!({
+                "received_sats": amount,
+                "kind": "cashu",
+            }));
+        }
+
+        let (amount, federation_id) =
+            fedimint_client::reissue_into_any(&self.config.data_dir, token).await?;
         Ok(serde_json::json!({
             "received_sats": amount,
+            "kind": "fedimint",
+            "federation_id": federation_id,
         }))
     }
 
     pub(super) async fn handle_wallet_ecash_history(&self) -> Result<serde_json::Value> {
+        // Unified history: Cashu transactions (tagged kind="cashu") + the local
+        // Fedimint transaction log (kind="fedimint"), newest first. Previously
+        // only Cashu was returned, so a Fedimint receive showed up nowhere.
         let wallet = ecash::load_wallet(&self.config.data_dir).await?;
+        let mut transactions = wallet.transactions;
+        transactions.extend(fedimint_client::load_fedimint_txs(&self.config.data_dir).await);
+        // Sort by RFC-3339 timestamp descending (string compare is valid for
+        // same-offset RFC-3339), newest first.
+        transactions.sort_by(|a, b| b.timestamp.cmp(&a.timestamp));
         Ok(serde_json::json!({
-            "transactions": wallet.transactions,
+            "transactions": transactions,
         }))
     }
 

core/archipelago/src/bitcoin_status.rs

@@ -13,14 +13,32 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH};
 use tokio::sync::RwLock;
 use tracing::{debug, warn};
 
-const CACHE_REFRESH_SECS: u64 = 10;
-const CACHE_ERROR_BACKOFF_SECS: u64 = 15;
+// Poll frequently and recover fast so the cached snapshot tracks bitcoind's
+// responsive windows during IBD. During heavy block-connection, getblockchaininfo
+// can block briefly; a slow 10s/15s/20s cadence let one missed poll age the
+// snapshot past the UI's 30s "stale" threshold, so the UI dwelled on
+// "reconnecting…" long after bitcoind was answering again. Tight cadence + short
+// timeout keeps last-known state fresh and clears the stale banner promptly.
+const CACHE_REFRESH_SECS: u64 = 5;
+const CACHE_ERROR_BACKOFF_SECS: u64 = 5;
+
+// Grace window before a failing poll marks the snapshot "stale" for the UI.
+// On a busy / swap-thrashing node (e.g. .198) getblockchaininfo intermittently
+// exceeds the RPC timeout, so a single missed poll is normal and must NOT flip
+// the UI to "reconnecting…". Only after the cached snapshot is genuinely old —
+// several polls failed in a row — do we surface the banner.
+const STALE_GRACE_MS: u64 = 20_000;
 
 #[derive(Debug, Clone, Serialize)]
 pub struct BitcoinNodeStatus {
     pub ok: bool,
     pub stale: bool,
     pub updated_at_ms: u64,
+    // Server-computed age of the snapshot, filled in at serve time. The browser
+    // must not derive this itself (Date.now() - updated_at_ms) because that
+    // compares the browser clock against this node's clock — any skew made a
+    // fresh snapshot look stale and the "reconnecting…" banner never cleared.
+    pub age_ms: u64,
     pub error: Option<String>,
     pub blockchain_info: Option<serde_json::Value>,
     pub network_info: Option<serde_json::Value>,
@@ -34,6 +52,7 @@ impl Default for BitcoinNodeStatus {
             ok: false,
             stale: false,
             updated_at_ms: 0,
+            age_ms: 0,
             error: Some("Connecting to Bitcoin node...".to_string()),
             blockchain_info: None,
             network_info: None,
@@ -122,7 +141,11 @@ pub fn spawn_status_cache() {
 
                     if cached.blockchain_info.is_some() {
                         cached.ok = false;
-                        cached.stale = true;
+                        // Only flip to "stale" once the last good snapshot is older
+                        // than the grace window. A brief RPC gap on a busy node keeps
+                        // showing last-known state silently instead of a banner flicker.
+                        let snapshot_age_ms = now_ms().saturating_sub(cached.updated_at_ms);
+                        cached.stale = snapshot_age_ms > STALE_GRACE_MS;
                         cached.error = Some(friendly_transient_error(true, &err_msg));
                     } else {
                         *cached = BitcoinNodeStatus {
@@ -142,40 +165,46 @@ pub fn spawn_status_cache() {
 }
 
 pub async fn get_bitcoin_status() -> BitcoinNodeStatus {
-    cache().read().await.clone()
+    let mut status = cache().read().await.clone();
+    // Compute age here (server clock only) so the browser never has to subtract
+    // across clocks. A successful snapshot serves age_ms ≈ 0 → the UI clears the
+    // "reconnecting…" banner on its very next poll regardless of browser-clock skew.
+    if status.updated_at_ms > 0 {
+        status.age_ms = now_ms().saturating_sub(status.updated_at_ms);
+    }
+    status
 }
 
 async fn fetch_bitcoin_status() -> Result<BitcoinNodeStatus> {
+    // 12s (not 8s): on a swap-thrashing node getblockchaininfo can answer slowly
+    // but correctly; too tight a timeout turned working-but-slow polls into
+    // failures and tripped the "reconnecting…" banner. Stays under STALE_GRACE_MS.
     let client = reqwest::Client::builder()
-        .timeout(Duration::from_secs(20))
+        .timeout(Duration::from_secs(12))
         .build()
         .context("build Bitcoin status HTTP client")?;
 
-    let blockchain_info = bitcoin_rpc_call(&client, "getblockchaininfo", serde_json::json!([]))
-        .await
-        .context("getblockchaininfo")?;
-    let network_info = bitcoin_rpc_call(&client, "getnetworkinfo", serde_json::json!([]))
-        .await
-        .context("getnetworkinfo")
-        .ok();
-    let index_info = bitcoin_rpc_call(&client, "getindexinfo", serde_json::json!([]))
-        .await
-        .context("getindexinfo")
-        .ok();
-    let zmq_notifications = bitcoin_rpc_call(&client, "getzmqnotifications", serde_json::json!([]))
-        .await
-        .context("getzmqnotifications")
-        .ok();
+    // Fetch all four calls concurrently: getblockchaininfo gates freshness, so a
+    // slow auxiliary call (network/index/zmq) must not delay the snapshot or block
+    // the next refresh. Only getblockchaininfo failing marks the status stale.
+    let (blockchain_info, network_info, index_info, zmq_notifications) = tokio::join!(
+        bitcoin_rpc_call(&client, "getblockchaininfo", serde_json::json!([])),
+        bitcoin_rpc_call(&client, "getnetworkinfo", serde_json::json!([])),
+        bitcoin_rpc_call(&client, "getindexinfo", serde_json::json!([])),
+        bitcoin_rpc_call(&client, "getzmqnotifications", serde_json::json!([])),
+    );
+    let blockchain_info = blockchain_info.context("getblockchaininfo")?;
 
     Ok(BitcoinNodeStatus {
         ok: true,
         stale: false,
         updated_at_ms: now_ms(),
+        age_ms: 0,
         error: None,
         blockchain_info: Some(blockchain_info),
-        network_info,
-        index_info,
-        zmq_notifications,
+        network_info: network_info.ok(),
+        index_info: index_info.ok(),
+        zmq_notifications: zmq_notifications.ok(),
     })
 }
 

core/archipelago/src/blobs.rs

@@ -25,6 +25,12 @@ pub const MAX_BLOB_SIZE: u64 = 64 * 1024 * 1024;
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct BlobMeta {
     pub cid: String,
+    /// DHT Phase 1: BLAKE3 hash of the content (iroh-native swarm address).
+    /// The on-disk path stays SHA-256-keyed (`cid`) for back-compat; this
+    /// advertises the hash a peer swarm can fetch/range-verify by. Absent in
+    /// legacy metadata written before Phase 1.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub blake3: Option<String>,
     pub size: u64,
     pub mime: String,
     #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -88,6 +94,7 @@ impl BlobStore {
         let cid = hex::encode(hasher.finalize());
         let meta = BlobMeta {
             cid: cid.clone(),
+            blake3: Some(crate::content_hash::blake3_hex(bytes)),
             size: bytes.len() as u64,
             mime: mime.to_string(),
             filename,

core/archipelago/src/bootstrap.rs

@@ -30,8 +30,22 @@ const DOCTOR_SH_PATH: &str = "/home/archipelago/archy/scripts/container-doctor.s
 const DOCTOR_SERVICE_PATH: &str = "/etc/systemd/system/archipelago-doctor.service";
 const DOCTOR_TIMER_PATH: &str = "/etc/systemd/system/archipelago-doctor.timer";
 
+// Kiosk hardening (#36): keep the deployed unit + launcher in sync with the
+// repo so the CPU/memory cap and the GPU-vs-headless flag selection reach
+// already-installed nodes via OTA, not just fresh ISOs.
+const KIOSK_SERVICE: &str = include_str!("../../../image-recipe/configs/archipelago-kiosk.service");
+const KIOSK_LAUNCHER: &str =
+    include_str!("../../../image-recipe/configs/archipelago-kiosk-launcher.sh");
+const KIOSK_SERVICE_PATH: &str = "/etc/systemd/system/archipelago-kiosk.service";
+const KIOSK_LAUNCHER_PATH: &str = "/usr/local/bin/archipelago-kiosk-launcher";
+
 const NGINX_CONF_PATH: &str = "/etc/nginx/sites-available/archipelago";
 const NGINX_ENABLED_CONF_PATH: &str = "/etc/nginx/sites-enabled/archipelago";
+/// Per-app proxy snippet included by the HTTPS (:443) server block. Carries its
+/// own `/app/fedimint/` location, so it needs the same B13 asset-rewrite heal as
+/// the main conf — browsers reach fedimint over HTTPS via this snippet. Absent on
+/// HTTP-only nodes, in which case the bootstrap loop skips it.
+const NGINX_HTTPS_SNIPPET_PATH: &str = "/etc/nginx/snippets/archipelago-https-app-proxies.conf";
 const RUNTIME_ASSETS_DIR: &str = "/opt/archipelago/web-ui/archipelago-runtime";
 
 /// Inserted into every server block of the nginx config that lacks the
@@ -41,6 +55,41 @@ const NGINX_APP_CATALOG_BLOCK: &str = "\n    # App Store catalog proxy — backe
 
 const NGINX_BITCOIN_STATUS_BLOCK: &str = "\n    location /bitcoin-status {\n        proxy_pass http://127.0.0.1:5678/bitcoin-status;\n        proxy_http_version 1.1;\n        proxy_set_header Host $host;\n        proxy_connect_timeout 10s;\n        proxy_read_timeout 10s;\n        proxy_send_timeout 5s;\n        error_page 502 503 = @backend_unavailable;\n        error_page 504 = @backend_timeout;\n    }\n";
 
+/// Inserted into every server block that lacks the `/proxy/lnd/` proxy. Nodes
+/// flashed before 2026-04-10 shipped an nginx config without this block, so the
+/// browser's wallet fetches to `/proxy/lnd/*` fell through to the SPA
+/// index.html and got HTML back instead of JSON ("failing to fetch"). Kept in
+/// sync with the canonical block in image-recipe/configs/nginx-archipelago.conf.
+const NGINX_LND_PROXY_BLOCK: &str = "\n    # LND REST proxy — backend handles auth + CORS\n    location /proxy/lnd/ {\n        proxy_pass http://127.0.0.1:5678;\n        proxy_http_version 1.1;\n        proxy_set_header Host $host;\n        proxy_set_header Cookie $http_cookie;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_connect_timeout 10s;\n        proxy_read_timeout 10s;\n        proxy_send_timeout 5s;\n        error_page 502 503 = @backend_unavailable;\n        error_page 504 = @backend_timeout;\n    }\n";
+
+/// Inserted into every server block lacking the peer-content streaming proxy.
+/// Without it, the browser's `<video>`/`<audio>` Range requests to
+/// `/api/peer-content/*` fall through to the SPA index.html (HTML, no Range)
+/// and peer media won't play (B3). Forwards Cookie (session auth) + Range and
+/// disables buffering so streaming works. Kept in sync with the canonical
+/// block in image-recipe/configs/nginx-archipelago.conf.
+const NGINX_PEER_CONTENT_BLOCK: &str = "\n    # Peer content streaming proxy (B3) — Range-streams a peer's media file.\n    # Long read timeout: this path also serves full-file downloads of large\n    # media (#38), which can take minutes over Tor; 120s aborted them.\n    location /api/peer-content/ {\n        proxy_pass http://127.0.0.1:5678;\n        proxy_http_version 1.1;\n        proxy_set_header Host $host;\n        proxy_set_header Cookie $http_cookie;\n        proxy_set_header Range $http_range;\n        proxy_buffering off;\n        proxy_connect_timeout 10s;\n        proxy_read_timeout 900s;\n        error_page 502 503 = @backend_unavailable;\n        error_page 504 = @backend_timeout;\n    }\n";
+
+/// B13 — Fedimint UI asset rewrite. Pre-fix nodes proxy /app/fedimint/ with only
+/// the nostr-provider injection (`sub_filter_once on`), so the UI's root-rooted
+/// CSS/JS asset URLs (href="/…", url("/…")) miss the proxy and load the SPA shell
+/// → unstyled UI. We swap that single sub_filter for the full rewrite set that
+/// reroots every asset URL under /app/fedimint/. NEW matches the canonical block
+/// in image-recipe/configs/nginx-archipelago.conf byte-for-byte so self-healed
+/// nodes converge to the same config fresh ISOs ship with.
+const NGINX_FEDIMINT_OLD: &str = "        sub_filter_once on;\n        sub_filter '</head>' '<script src=\"/nostr-provider.js\"></script></head>';\n    }\n    location /app/fedimint-gateway/ {";
+const NGINX_FEDIMINT_NEW: &str = "        sub_filter_types text/css application/javascript application/json;\n        sub_filter_once off;\n        sub_filter 'href=\"/' 'href=\"/app/fedimint/';\n        sub_filter 'src=\"/' 'src=\"/app/fedimint/';\n        sub_filter \"href='/\" \"href='/app/fedimint/\";\n        sub_filter \"src='/\" \"src='/app/fedimint/\";\n        sub_filter 'url(\"/' 'url(\"/app/fedimint/';\n        sub_filter \"url('/\" \"url('/app/fedimint/\";\n        sub_filter '</head>' '<script src=\"/nostr-provider.js\"></script></head>';\n    }\n    location /app/fedimint-gateway/ {";
+
+/// B13 Style B — the HTTPS app-proxy snippet's fedimint block has NO sub_filter
+/// at all (older than the main conf's), and the directive that follows it varies
+/// per node (fedimint-gateway vs tailscale), so a full-block match is unreliable.
+/// Instead we anchor on the unique :8175 proxy_pass (fedimint is the only block
+/// proxying there) and insert the reroot set right after it — directive order
+/// inside a location block is irrelevant to nginx. Idempotent via the same
+/// `href="/app/fedimint/` marker the main-conf heal leaves behind.
+const NGINX_FEDIMINT_SNIPPET_ANCHOR: &str = "proxy_pass http://127.0.0.1:8175/;";
+const NGINX_FEDIMINT_SNIPPET_INSERT: &str = "proxy_pass http://127.0.0.1:8175/;\n    proxy_set_header Accept-Encoding \"\";\n    sub_filter_types text/css application/javascript application/json;\n    sub_filter_once off;\n    sub_filter 'href=\"/' 'href=\"/app/fedimint/';\n    sub_filter 'src=\"/' 'src=\"/app/fedimint/';\n    sub_filter \"href='/\" \"href='/app/fedimint/\";\n    sub_filter \"src='/\" \"src='/app/fedimint/\";\n    sub_filter 'url(\"/' 'url(\"/app/fedimint/';\n    sub_filter \"url('/\" \"url('/app/fedimint/\";\n    sub_filter '</head>' '<script src=\"/nostr-provider.js\"></script></head>';";
+
 /// Entry point called from main startup. Never returns an error to the caller —
 /// failing to bootstrap host artifacts must not prevent the backend from serving.
 pub async fn ensure_doctor_installed() {
@@ -476,6 +525,92 @@ async fn write_root_if_needed(path: &str, content: &str) -> Result<bool> {
     Ok(true)
 }
 
+const ARCHIPELAGO_SERVICE_PATH: &str = "/etc/systemd/system/archipelago.service";
+const MOUNT_REQUIRE_LINE: &str = "RequiresMountsFor=/var/lib/archipelago";
+
+/// B17 self-heal: ensure the installed archipelago.service waits for the data
+/// volume to mount before it starts. On production nodes `/var/lib/archipelago`
+/// (the app data dir AND podman's graphroot) is a separate device-mapper volume;
+/// without a mount dependency the service can start before `var-lib-archipelago.mount`,
+/// write to the bare mountpoint on rootfs, fail every podman call, exit, and be
+/// restarted every 5s until the volume mounts (~5 min of "[FAILED] Failed to start"
+/// on cold boots). Fresh ISOs already ship the directive; this heals already-deployed
+/// nodes. The change is boot-ordering only — it takes effect on the NEXT reboot, so we
+/// never restart the running service here. Idempotent; no-op if the unit is absent
+/// (dev runs) or already patched. Harmless when the data dir is on rootfs (systemd maps
+/// the requirement to the always-mounted root).
+pub async fn ensure_archipelago_mount_ordering() {
+    let current = match fs::read_to_string(ARCHIPELAGO_SERVICE_PATH).await {
+        Ok(c) => c,
+        Err(e) => {
+            tracing::debug!(
+                "mount-ordering self-heal: {} not readable ({}) — skipping",
+                ARCHIPELAGO_SERVICE_PATH,
+                e
+            );
+            return;
+        }
+    };
+    if current.contains(MOUNT_REQUIRE_LINE) {
+        return; // already healed
+    }
+    // Insert the directive into the [Unit] section, immediately before [Service].
+    let Some(idx) = current.find("\n[Service]") else {
+        tracing::warn!(
+            "mount-ordering self-heal: no [Service] section in {} — skipping",
+            ARCHIPELAGO_SERVICE_PATH
+        );
+        return;
+    };
+    let mut patched = String::with_capacity(current.len() + MOUNT_REQUIRE_LINE.len() + 96);
+    patched.push_str(&current[..idx]);
+    patched.push_str("\n# B17: start only after the data volume (+ podman graphroot) is mounted\n");
+    patched.push_str(MOUNT_REQUIRE_LINE);
+    patched.push_str(&current[idx..]);
+    match write_root_if_needed(ARCHIPELAGO_SERVICE_PATH, &patched).await {
+        Ok(true) => {
+            info!(
+                "B17: added '{}' to archipelago.service (effective next reboot)",
+                MOUNT_REQUIRE_LINE
+            );
+            if let Err(e) = host_sudo(&["systemctl", "daemon-reload"]).await {
+                tracing::warn!("B17 self-heal: daemon-reload failed: {:#}", e);
+            }
+        }
+        Ok(false) => {}
+        Err(e) => tracing::warn!("B17 mount-ordering self-heal failed: {:#}", e),
+    }
+}
+
+/// #36 self-heal: keep the kiosk unit + launcher current on already-deployed
+/// nodes so the CPU/memory cap (a runaway chromium was saturating the node and
+/// starving the backend) and the GPU-vs-headless flag selection arrive via OTA.
+/// No-op on nodes without the kiosk installed; only restarts the kiosk if it's
+/// actually running (so it never re-enables an operator-disabled kiosk).
+pub async fn ensure_kiosk_hardened() {
+    if fs::metadata(KIOSK_SERVICE_PATH).await.is_err() {
+        return; // kiosk not installed on this node
+    }
+    let svc_changed = write_root_if_needed(KIOSK_SERVICE_PATH, KIOSK_SERVICE)
+        .await
+        .unwrap_or(false);
+    let launcher_changed = write_root_if_needed(KIOSK_LAUNCHER_PATH, KIOSK_LAUNCHER)
+        .await
+        .unwrap_or(false);
+    if launcher_changed {
+        let _ = host_sudo(&["chmod", "+x", KIOSK_LAUNCHER_PATH]).await;
+    }
+    if svc_changed || launcher_changed {
+        if let Err(e) = host_sudo(&["systemctl", "daemon-reload"]).await {
+            warn!("kiosk hardening: daemon-reload failed: {:#}", e);
+        }
+        // try-restart only restarts a currently-active unit — leaves a stopped/
+        // disabled kiosk alone.
+        let _ = host_sudo(&["systemctl", "try-restart", "archipelago-kiosk.service"]).await;
+        info!("kiosk: applied resource cap + GPU-flag hardening (#36)");
+    }
+}
+
 /// Patch the nginx site config to add missing backend proxy blocks. Older ISO
 /// configs shipped individual per-endpoint `location` blocks, so missing
 /// endpoints silently fell through to the SPA `index.html` and the frontend
@@ -496,7 +631,11 @@ async fn run_nginx() -> Result<bool> {
 
     let mut changed = false;
     let mut patched_paths = Vec::<PathBuf>::new();
-    for path in [NGINX_CONF_PATH, NGINX_ENABLED_CONF_PATH] {
+    for path in [
+        NGINX_CONF_PATH,
+        NGINX_ENABLED_CONF_PATH,
+        NGINX_HTTPS_SNIPPET_PATH,
+    ] {
         let candidate = Path::new(path);
         if !candidate.exists() {
             debug!("{} missing — skipping nginx bootstrap", path);
@@ -514,18 +653,100 @@ async fn run_nginx() -> Result<bool> {
     Ok(changed)
 }
 
+/// Reflective CORS add_headers that older configs placed inside the
+/// `/lnd-connect-info` location. The backend now sets a validated
+/// `Access-Control-Allow-Origin` for that endpoint (api/handler/proxy.rs), so
+/// leaving these in nginx emits a DUPLICATE header ("contains multiple values
+/// … but only one is allowed") and the LND wallet UI's cross-origin fetch is
+/// rejected. Stripped during nginx bootstrap so the backend solely owns CORS.
+const NGINX_LND_DUP_CORS: &str = "        add_header Access-Control-Allow-Origin $http_origin always;\n        add_header Access-Control-Allow-Credentials \"true\" always;\n";
+
 async fn patch_nginx_conf(path: &str) -> Result<bool> {
     let content = fs::read_to_string(path)
         .await
         .with_context(|| format!("read {}", path))?;
-    let missing_app_catalog = !content.contains("location /api/app-catalog");
-    let missing_bitcoin_status = !content.contains("location /bitcoin-status");
-    if !missing_app_catalog && !missing_bitcoin_status {
+    // Each "missing" flag is gated on the splice anchor actually being present,
+    // so an included snippet that legitimately has none of these endpoints (the
+    // HTTPS app-proxy snippet) neither tries to patch them nor logs warn-skips on
+    // every boot — it falls through to the fedimint heal alone.
+    let has_lnd_anchor = content.contains("    location /lnd-connect-info {")
+        || content.contains("    location /electrs-status {");
+    let missing_app_catalog = content
+        .contains("    # DWN endpoints — peer access over Tor (no auth)")
+        && !content.contains("location /api/app-catalog");
+    let missing_bitcoin_status = content.contains("    location /electrs-status {")
+        && !content.contains("location /bitcoin-status");
+    let missing_lnd_proxy = has_lnd_anchor && !content.contains("location /proxy/lnd/");
+    let missing_peer_content = has_lnd_anchor && !content.contains("location /api/peer-content");
+    let has_lnd_dup_cors = content.contains(NGINX_LND_DUP_CORS);
+    // B13: fedimint block present but lacking the asset-rewrite sub_filters.
+    let needs_fedimint_css = content.contains("location /app/fedimint/")
+        && !content.contains("'href=\"/' 'href=\"/app/fedimint/'");
+    if !missing_app_catalog
+        && !missing_bitcoin_status
+        && !missing_lnd_proxy
+        && !missing_peer_content
+        && !has_lnd_dup_cors
+        && !needs_fedimint_css
+    {
         return Ok(false);
     }
 
     let mut patched = content.clone();
 
+    if has_lnd_dup_cors {
+        // Drop the redundant nginx-side CORS headers so the backend's single
+        // validated Access-Control-Allow-Origin is the only one returned.
+        patched = patched.replace(NGINX_LND_DUP_CORS, "");
+    }
+
+    if needs_fedimint_css {
+        // Style A (main conf): the block already injects nostr-provider, so swap
+        // its single-sub_filter tail for the full asset-rewrite set. No-op if the
+        // node's fedimint block doesn't match OLD.
+        patched = patched.replace(NGINX_FEDIMINT_OLD, NGINX_FEDIMINT_NEW);
+        // Style B (HTTPS app-proxy snippet): the block has no sub_filter to swap,
+        // so insert the reroot set after the unique :8175 proxy_pass. Guarded on
+        // the marker so it can never double-apply after Style A already healed.
+        if !patched.contains("'href=\"/' 'href=\"/app/fedimint/'") {
+            patched = patched.replace(NGINX_FEDIMINT_SNIPPET_ANCHOR, NGINX_FEDIMINT_SNIPPET_INSERT);
+        }
+    }
+
+    if missing_lnd_proxy {
+        // Prefer the `/lnd-connect-info` anchor (present since 2026-03-17); fall
+        // back to `/electrs-status` (since 2026-03-08) for even older configs.
+        // Both appear once per archipelago server block, so the block is added
+        // to every server block that proxies to the backend.
+        let anchor = if patched.contains("    location /lnd-connect-info {") {
+            "    location /lnd-connect-info {"
+        } else {
+            "    location /electrs-status {"
+        };
+        if !patched.contains(anchor) {
+            warn!("nginx conf missing lnd-connect-info/electrs-status anchor — skipping /proxy/lnd patch");
+        } else {
+            let replacement = format!("{}{}", NGINX_LND_PROXY_BLOCK, anchor);
+            patched = patched.replace(anchor, &replacement);
+        }
+    }
+
+    if missing_peer_content {
+        // Same anchoring as the LND proxy: prepend the block to every server
+        // block so /api/peer-content/* reaches the backend instead of the SPA.
+        let anchor = if patched.contains("    location /lnd-connect-info {") {
+            "    location /lnd-connect-info {"
+        } else {
+            "    location /electrs-status {"
+        };
+        if patched.contains(anchor) {
+            let replacement = format!("{}{}", NGINX_PEER_CONTENT_BLOCK, anchor);
+            patched = patched.replace(anchor, &replacement);
+        } else {
+            warn!("nginx conf missing anchor — skipping /api/peer-content patch");
+        }
+    }
+
     if missing_bitcoin_status {
         let anchor = "    location /electrs-status {";
         if !patched.contains(anchor) {

core/archipelago/src/ceremony.rs

@@ -0,0 +1,141 @@
+//! Release-root signing ceremony — the publisher-side counterpart to
+//! `trust::anchor`. Run as a subcommand of the same binary so it reuses the
+//! exact key derivation (`seed::derive_release_root_ed25519`) and canonical
+//! signing (`trust::signed_doc::sign_detached`) the fleet verifies against.
+//!
+//! Usage (the mnemonic is read from the `RELEASE_MASTER_MNEMONIC` env var or
+//! stdin — never an argv so it stays out of shell history / `ps`):
+//!
+//! ```text
+//!   archipelago ceremony gen
+//!       Generate a fresh 24-word release master mnemonic and print it plus the
+//!       derived release-root pubkey + did. Back the mnemonic up OFFLINE.
+//!
+//!   RELEASE_MASTER_MNEMONIC="word1 …" archipelago ceremony pubkey
+//!       Print the release-root pubkey hex (for ARCHY_RELEASE_ROOT_PUBKEY /
+//!       trust::anchor::RELEASE_ROOT_PUBKEY_HEX) and the signer did:key.
+//!
+//!   RELEASE_MASTER_MNEMONIC="word1 …" archipelago ceremony sign <file.json>
+//!       Sign a JSON document (e.g. releases/app-catalog.json) in place: insert
+//!       `signature` + `signed_by` over the canonical form, matching exactly
+//!       what `trust::verify_detached` recomputes on every node.
+//! ```
+
+use anyhow::{bail, Context, Result};
+use ed25519_dalek::SigningKey;
+
+use crate::seed::{self, MasterSeed};
+use crate::trust::{did, signed_doc};
+
+const ENV_MNEMONIC: &str = "RELEASE_MASTER_MNEMONIC";
+
+/// True if argv selects the ceremony subcommand. Checked before any server init.
+pub fn is_ceremony_invocation() -> bool {
+    std::env::args().nth(1).as_deref() == Some("ceremony")
+}
+
+/// Entry point for `archipelago ceremony …`. Returns Ok(()) on success; the
+/// caller (main) should exit without starting the server.
+pub fn run() -> Result<()> {
+    let sub = std::env::args().nth(2).unwrap_or_default();
+    match sub.as_str() {
+        "gen" => cmd_gen(),
+        "pubkey" => cmd_pubkey(),
+        "sign" => {
+            let file = std::env::args()
+                .nth(3)
+                .context("usage: archipelago ceremony sign <file.json>")?;
+            cmd_sign(&file)
+        }
+        other => {
+            bail!(
+                "unknown ceremony subcommand {:?}; expected gen | pubkey | sign <file>",
+                other
+            )
+        }
+    }
+}
+
+fn cmd_gen() -> Result<()> {
+    let (mnemonic, seed) = MasterSeed::generate().context("generate mnemonic")?;
+    let key = seed::derive_release_root_ed25519(&seed).context("derive release-root")?;
+    eprintln!("⚠  Back this mnemonic up OFFLINE. It is the ONLY way to re-derive");
+    eprintln!("   the release-root signing key. Anyone with it can sign for the fleet.\n");
+    println!("RELEASE_MASTER_MNEMONIC=\"{}\"", mnemonic);
+    print_key(&key);
+    Ok(())
+}
+
+fn cmd_pubkey() -> Result<()> {
+    let key = load_release_root_key()?;
+    print_key(&key);
+    Ok(())
+}
+
+fn cmd_sign(path: &str) -> Result<()> {
+    let key = load_release_root_key()?;
+
+    let body = std::fs::read_to_string(path).with_context(|| format!("read {path}"))?;
+    let mut value: serde_json::Value =
+        serde_json::from_str(&body).with_context(|| format!("parse {path} as JSON"))?;
+    {
+        let obj = value
+            .as_object_mut()
+            .context("document root must be a JSON object")?;
+        // Re-sign cleanly: drop any prior signature so the preimage matches.
+        obj.remove("signature");
+        obj.remove("signed_by");
+    }
+
+    let (signature, signed_by) =
+        signed_doc::sign_detached(&key, &value).context("sign document")?;
+
+    let obj = value.as_object_mut().expect("checked above");
+    obj.insert("signature".into(), serde_json::Value::String(signature));
+    obj.insert(
+        "signed_by".into(),
+        serde_json::Value::String(signed_by.clone()),
+    );
+
+    let pretty = serde_json::to_string_pretty(&value).context("serialize signed document")?;
+    let tmp = format!("{path}.tmp");
+    std::fs::write(&tmp, format!("{pretty}\n")).with_context(|| format!("write {tmp}"))?;
+    std::fs::rename(&tmp, path).with_context(|| format!("rename {tmp} -> {path}"))?;
+
+    eprintln!("✓ signed {path}");
+    eprintln!("  signed_by: {signed_by}");
+    Ok(())
+}
+
+/// Derive the release-root signing key from the mnemonic in env/stdin.
+fn load_release_root_key() -> Result<SigningKey> {
+    let phrase = read_mnemonic()?;
+    let (_mnemonic, seed) = MasterSeed::from_mnemonic_words(phrase.trim())
+        .context("invalid release master mnemonic")?;
+    seed::derive_release_root_ed25519(&seed).context("derive release-root")
+}
+
+/// Read the mnemonic from `RELEASE_MASTER_MNEMONIC` or, if unset, stdin.
+fn read_mnemonic() -> Result<String> {
+    if let Ok(v) = std::env::var(ENV_MNEMONIC) {
+        if !v.trim().is_empty() {
+            return Ok(v);
+        }
+    }
+    use std::io::Read;
+    eprintln!("Paste the release master mnemonic, then Ctrl-D:");
+    let mut buf = String::new();
+    std::io::stdin()
+        .read_to_string(&mut buf)
+        .context("read mnemonic from stdin")?;
+    if buf.trim().is_empty() {
+        bail!("no mnemonic provided (set {ENV_MNEMONIC} or pipe it on stdin)");
+    }
+    Ok(buf)
+}
+
+fn print_key(key: &SigningKey) {
+    let vk = key.verifying_key();
+    println!("RELEASE_ROOT_PUBKEY_HEX={}", hex::encode(vk.to_bytes()));
+    println!("signed_by_did={}", did::did_key_for_ed25519(&vk));
+}

core/archipelago/src/config.rs

@@ -66,10 +66,17 @@ pub struct Config {
     /// through Quadlet (`.container` units in ~/.config/containers/systemd
     /// + systemctl --user start) instead of `podman create + start`. Default
     /// off so the legacy path stays the production path until the harness
-    /// at tests/lifecycle/run-20x.sh has gone green against the new path
+    /// at tests/lifecycle/run-gate.sh has gone green against the new path
     /// on .228 + .198. See `project_v1_7_52_phase3_quadlet_design`.
     #[serde(default)]
     pub use_quadlet_backends: bool,
+    /// DHT swarm-assist (Phase 3): when true AND the binary was built with the
+    /// `iroh-swarm` feature, stand up an iroh-blobs provider that fetches release
+    /// blobs peer-to-peer (origin always wins) and seeds them via signed Nostr
+    /// adverts. Off by default; with the feature absent this is inert. Reuses
+    /// `nostr_relays` + `nostr_tor_proxy` for discovery transport.
+    #[serde(default)]
+    pub swarm_enabled: bool,
 }
 
 impl Config {
@@ -182,6 +189,12 @@ impl Config {
             config.nostr_tor_proxy = if s.is_empty() { None } else { Some(s) };
         }
 
+        // DHT swarm-assist (Phase 3). Opt-in: only takes effect when the binary
+        // was also built with the `iroh-swarm` feature; otherwise inert.
+        if let Ok(v) = std::env::var("ARCHIPELAGO_SWARM_ENABLED") {
+            config.swarm_enabled = parse_truthy_env(&v);
+        }
+
         // Phase 3.2 of v1.7.52. Truthy values (1, true, yes, on — case-insensitive)
         // route backend installs through the Quadlet path without requiring a
         // config.json edit + archipelago.service restart (which would trigger
@@ -241,6 +254,7 @@ impl Default for Config {
             ],
             nostr_tor_proxy: Some("127.0.0.1:9050".into()),
             use_quadlet_backends: false,
+            swarm_enabled: false,
         }
     }
 }
@@ -473,7 +487,7 @@ mod tests {
 
     #[test]
     fn test_config_use_quadlet_backends_defaults_off() {
-        // Phase 3.2 of v1.7.52 — the new path stays gated until the 20×
+        // Phase 3.2 of v1.7.52 — the new path stays gated until the 5×
         // harness goes green on .228 and .198. Flipping this default
         // ahead of that would route every backend install through code
         // we haven't fleet-validated yet.

core/archipelago/src/container/app_catalog.rs

@@ -0,0 +1,417 @@
+//! Remote app version catalog — DECOUPLES per-app updates from the binary OTA.
+//!
+//! Background: `image_versions.rs` reads the pinned image tags from
+//! `image-versions.sh`, which is deployed *with the archipelago binary*. That
+//! coupled every app update to a full node release. This module adds a remote
+//! catalog (`app-catalog.json`) fetched over HTTP from the same origin as the
+//! OTA manifest, refreshed periodically and on demand. Bumping an app's version
+//! is then a JSON edit + push — no binary release.
+//!
+//! Resolution order (origin-always-wins, matching the DHT design's posture):
+//!   1. Remote catalog (this module) — the live source of "available update".
+//!   2. `image-versions.sh` pin — offline/baseline fallback when the catalog is
+//!      missing or doesn't cover the app.
+//!
+//! ## Forward-compatibility with the DHT distribution plan
+//! (`docs/dht-distribution-design.md`)
+//! This catalog IS the "discovery / authenticity" layer of that plan. The schema
+//! is deliberately extensible so the later phases bolt on WITHOUT a breaking
+//! change:
+//!   - `signature` / `signed_by` (top level) — Phase 0 seed-derived release-root
+//!     signature over the canonical JSON. Absent today; verified when present.
+//!   - per-image `digest` / `size` — BLAKE3/SHA-256 content address + length, so
+//!     the iroh swarm can fetch images by hash with the registry as origin.
+//! Unknown fields are ignored (no `deny_unknown_fields`), so adding fields on the
+//! publisher side never breaks older nodes.
+
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::Mutex;
+use std::time::SystemTime;
+use tracing::{debug, info, warn};
+
+/// Filename for both the published catalog and the on-node cache.
+pub const APP_CATALOG_FILE: &str = "app-catalog.json";
+
+/// Cache of the parsed catalog, invalidated when the cache file mtime changes.
+static CACHE: Mutex<Option<CacheEntry>> = Mutex::new(None);
+
+struct CacheEntry {
+    mtime: SystemTime,
+    catalog: AppCatalog,
+}
+
+/// Top-level catalog document.
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct AppCatalog {
+    /// Schema version. 1 = current. Bump only on incompatible changes.
+    #[serde(default)]
+    pub schema: u32,
+    /// Publish date (RFC 3339 or YYYY-MM-DD). Informational.
+    #[serde(default)]
+    pub updated: String,
+    /// app_id -> entry.
+    #[serde(default)]
+    pub apps: HashMap<String, AppCatalogEntry>,
+    /// DHT-plan forward-compat: detached signature over the canonical JSON,
+    /// produced by the seed-derived release-root key. Absent today.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub signature: Option<String>,
+    /// DHT-plan forward-compat: publisher identity (did:key / npub).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub signed_by: Option<String>,
+}
+
+/// Per-app catalog entry.
+#[derive(Debug, Clone, Serialize, Deserialize, Default)]
+pub struct AppCatalogEntry {
+    /// User-facing version string (drives the "Update available" badge text).
+    pub version: String,
+    /// Primary single-container image reference (`registry/repo:tag`). For stack
+    /// apps this is the primary container's image (the one whose version the
+    /// badge tracks — e.g. the IndeeHub frontend).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub image: Option<String>,
+    /// Stack apps only: container_name -> image reference. Components omitted here
+    /// fall back to the `image-versions.sh` pin during an update.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub images: Option<HashMap<String, String>>,
+    /// DHT-plan forward-compat: content address of the primary image (unused now).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub digest: Option<String>,
+    /// DHT-plan forward-compat: size in bytes of the primary image (unused now).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub size: Option<u64>,
+    /// Optional human-readable changelog lines for this version.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub changelog: Vec<String>,
+    /// Full app manifest, embedded so the app installs from the registry alone —
+    /// no OTA-shipped `apps/<id>/manifest.yml`. Carried as the raw value the
+    /// publisher signed (so it stays part of the verified preimage) and
+    /// deserialized into an `AppManifest` by the orchestrator at load time, where
+    /// it overrides the disk manifest (origin-wins). Absent during the migration
+    /// window => the node falls back to the disk manifest. See
+    /// `docs/registry-manifest-design.md`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub manifest: Option<serde_json::Value>,
+}
+
+/// Read-side cache file search order. Mirrors `image_versions.rs`: the running
+/// daemon's data dir first (via env for dev), then the canonical runtime path.
+fn cache_paths() -> Vec<PathBuf> {
+    let mut paths = Vec::new();
+    if let Ok(dir) = std::env::var("ARCHIPELAGO_DATA_DIR") {
+        paths.push(Path::new(&dir).join(APP_CATALOG_FILE));
+    }
+    paths.push(Path::new("/var/lib/archipelago").join(APP_CATALOG_FILE));
+    paths
+}
+
+fn find_cache_file() -> Option<(PathBuf, SystemTime)> {
+    for p in cache_paths() {
+        if let Ok(meta) = p.metadata() {
+            if let Ok(mtime) = meta.modified() {
+                return Some((p, mtime));
+            }
+        }
+    }
+    None
+}
+
+/// Load and cache the on-node catalog. Returns an empty catalog when absent —
+/// callers then fall back to `image-versions.sh`.
+fn load_catalog() -> AppCatalog {
+    let (path, mtime) = match find_cache_file() {
+        Some(v) => v,
+        None => return AppCatalog::default(),
+    };
+
+    {
+        let cache = CACHE.lock().unwrap();
+        if let Some(ref entry) = *cache {
+            if entry.mtime == mtime {
+                return entry.catalog.clone();
+            }
+        }
+    }
+
+    let content = match std::fs::read_to_string(&path) {
+        Ok(c) => c,
+        Err(e) => {
+            debug!("app-catalog: failed to read {}: {}", path.display(), e);
+            return AppCatalog::default();
+        }
+    };
+    let catalog: AppCatalog = match serde_json::from_str(&content) {
+        Ok(c) => c,
+        Err(e) => {
+            warn!("app-catalog: invalid JSON at {}: {}", path.display(), e);
+            return AppCatalog::default();
+        }
+    };
+
+    {
+        let mut cache = CACHE.lock().unwrap();
+        *cache = Some(CacheEntry {
+            mtime,
+            catalog: catalog.clone(),
+        });
+    }
+    catalog
+}
+
+fn entry_for(app_id: &str) -> Option<AppCatalogEntry> {
+    load_catalog().apps.get(app_id).cloned()
+}
+
+/// Primary image for an app per the remote catalog, if covered.
+pub fn catalog_primary_image(app_id: &str) -> Option<String> {
+    entry_for(app_id).and_then(|e| e.image)
+}
+
+/// Per-container stack image overrides from the catalog (container_name -> image).
+pub fn catalog_stack_images(app_id: &str) -> HashMap<String, String> {
+    entry_for(app_id).and_then(|e| e.images).unwrap_or_default()
+}
+
+/// All `(app_id, manifest-value)` pairs the registry catalog carries. The
+/// orchestrator deserializes + validates each into an `AppManifest` and prefers
+/// it over the disk manifest (origin-wins); disk remains the migration fallback.
+/// Empty when the catalog is absent or no entry embeds a manifest.
+pub fn catalog_manifest_values() -> Vec<(String, serde_json::Value)> {
+    load_catalog()
+        .apps
+        .into_iter()
+        .filter_map(|(id, e)| e.manifest.map(|m| (id, m)))
+        .collect()
+}
+
+/// Image override for the orchestrator's install/upgrade path. Returns the
+/// catalog's primary image for `app_id` ONLY when it refers to the same
+/// repository as the manifest's current image — a guard so a catalog typo can
+/// never redirect an app to an unrelated image. `None` means "use the manifest
+/// image as-is" (catalog absent, app uncovered, or repo mismatch).
+pub fn catalog_image_override(app_id: &str, manifest_image: &str) -> Option<String> {
+    let candidate = catalog_primary_image(app_id)?;
+    let same_repo = crate::container::image_versions::image_without_registry_or_tag(&candidate)
+        == crate::container::image_versions::image_without_registry_or_tag(manifest_image);
+    if same_repo {
+        Some(candidate)
+    } else {
+        warn!(
+            "app-catalog: ignoring image for {} — repo mismatch (catalog={}, manifest={})",
+            app_id, candidate, manifest_image
+        );
+        None
+    }
+}
+
+/// Decoupled "available update" check for ALL apps.
+///
+/// Prefers the remote catalog; when the catalog covers the app, its verdict is
+/// authoritative (so we never advertise a stale `image-versions.sh` pin over a
+/// newer catalog, nor vice-versa). Falls back to the deployed pin only when the
+/// catalog is missing or doesn't cover the app.
+pub fn available_update_for_app(app_id: &str, running_image: &str) -> Option<String> {
+    if let Some(catalog_image) = catalog_primary_image(app_id) {
+        // Catalog covers this app with a concrete image -> authoritative.
+        return crate::container::image_versions::available_update_for_images(
+            &catalog_image,
+            running_image,
+        );
+    }
+    // Not covered by the catalog -> baseline pin from image-versions.sh.
+    crate::container::image_versions::available_update_for_app(app_id, running_image)
+}
+
+/// Derive candidate catalog URLs from the OTA mirror list by swapping the
+/// manifest filename for the catalog filename. Falls back to the default
+/// manifest origin when no mirrors are configured.
+fn catalog_urls_from_mirrors(mirrors: &[crate::update::UpdateMirror]) -> Vec<String> {
+    let mut urls: Vec<String> = mirrors
+        .iter()
+        .filter_map(|m| {
+            // mirror.url ends with ".../releases/manifest.json"
+            if m.url.ends_with("manifest.json") {
+                Some(m.url.replace("manifest.json", APP_CATALOG_FILE))
+            } else {
+                None
+            }
+        })
+        .collect();
+    urls.dedup();
+    urls
+}
+
+/// Fetch the catalog from the first reachable mirror and atomically write it to
+/// `<data_dir>/app-catalog.json`. Returns the number of apps in the catalog on
+/// success. Best-effort: a fetch failure leaves the existing cache untouched
+/// (origin-always-wins; updates simply aren't refreshed this cycle).
+pub async fn refresh_catalog(data_dir: &Path) -> anyhow::Result<usize> {
+    let mirrors = crate::update::load_mirrors(data_dir)
+        .await
+        .unwrap_or_default();
+    let urls = catalog_urls_from_mirrors(&mirrors);
+    if urls.is_empty() {
+        debug!("app-catalog: no mirror-derived URLs to fetch from");
+        return Ok(0);
+    }
+
+    let client = reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(20))
+        .build()?;
+
+    let mut last_err: Option<anyhow::Error> = None;
+    for url in &urls {
+        match fetch_one(&client, url).await {
+            Ok(catalog) => {
+                let count = catalog.apps.len();
+                write_cache(data_dir, &catalog)?;
+                // Invalidate the in-process cache so the next read re-parses.
+                *CACHE.lock().unwrap() = None;
+                info!("app-catalog: refreshed from {} ({} apps)", url, count);
+                return Ok(count);
+            }
+            Err(e) => {
+                debug!("app-catalog: fetch {} failed: {}", url, e);
+                last_err = Some(e);
+            }
+        }
+    }
+    Err(last_err.unwrap_or_else(|| anyhow::anyhow!("no catalog mirrors reachable")))
+}
+
+async fn fetch_one(client: &reqwest::Client, url: &str) -> anyhow::Result<AppCatalog> {
+    let resp = client.get(url).send().await?;
+    if !resp.status().is_success() {
+        anyhow::bail!("HTTP {}", resp.status());
+    }
+    let body = resp.text().await?;
+    let catalog: AppCatalog = serde_json::from_str(&body)?;
+
+    // DHT Phase 0 authenticity: verify the release-root signature when present.
+    // We verify against the raw JSON (the exact bytes the publisher signed),
+    // not a re-serialization of the typed struct, so unknown forward-compat
+    // fields stay part of the signed preimage. Unsigned catalogs are still
+    // accepted during the migration window — same trust level as today's
+    // manifest — but a *present* signature that fails is a hard reject so a
+    // tampering mirror cannot pass off altered bytes.
+    let raw: serde_json::Value = serde_json::from_str(&body)?;
+    match crate::trust::verify_detached(&raw)? {
+        crate::trust::SignatureStatus::Unsigned => {
+            debug!("app-catalog: unsigned (accepted during migration window)");
+        }
+        crate::trust::SignatureStatus::Verified {
+            signer_did,
+            anchored,
+        } => {
+            if anchored {
+                info!(
+                    "app-catalog: release-root signature verified ({})",
+                    signer_did
+                );
+            } else {
+                warn!(
+                    "app-catalog: signature self-consistent but release-root anchor \
+                     not pinned ({}); cannot confirm signer identity",
+                    signer_did
+                );
+            }
+        }
+    }
+
+    Ok(catalog)
+}
+
+fn write_cache(data_dir: &Path, catalog: &AppCatalog) -> anyhow::Result<()> {
+    let dest = data_dir.join(APP_CATALOG_FILE);
+    let tmp = data_dir.join(format!("{}.tmp", APP_CATALOG_FILE));
+    let json = serde_json::to_string_pretty(catalog)?;
+    std::fs::write(&tmp, json)?;
+    std::fs::rename(&tmp, &dest)?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_and_ignores_unknown_fields() {
+        let json = r#"{
+            "schema": 1,
+            "updated": "2026-06-16",
+            "future_field": "ignored",
+            "signature": "sig123",
+            "signed_by": "did:key:zABC",
+            "apps": {
+                "indeedhub": {
+                    "version": "1.0.1",
+                    "image": "146.59.87.168:3000/lfg2025/indeedhub:1.0.1",
+                    "digest": "blake3:deadbeef",
+                    "size": 12345,
+                    "another_future_field": true
+                }
+            }
+        }"#;
+        let cat: AppCatalog = serde_json::from_str(json).unwrap();
+        assert_eq!(cat.schema, 1);
+        assert_eq!(cat.signature.as_deref(), Some("sig123"));
+        let e = cat.apps.get("indeedhub").unwrap();
+        assert_eq!(e.version, "1.0.1");
+        assert_eq!(
+            e.image.as_deref(),
+            Some("146.59.87.168:3000/lfg2025/indeedhub:1.0.1")
+        );
+        assert_eq!(e.digest.as_deref(), Some("blake3:deadbeef"));
+    }
+
+    #[test]
+    fn entry_carries_embedded_manifest() {
+        let json = r#"{
+            "schema": 1,
+            "apps": {
+                "demo": {
+                    "version": "1.0.0",
+                    "manifest": {
+                        "app": {
+                            "id": "demo",
+                            "name": "Demo",
+                            "version": "1.0.0",
+                            "container": { "image": "registry/demo:1.0.0" }
+                        }
+                    }
+                }
+            }
+        }"#;
+        let cat: AppCatalog = serde_json::from_str(json).unwrap();
+        let e = cat.apps.get("demo").unwrap();
+        let m = e.manifest.as_ref().expect("manifest present");
+        assert_eq!(m["app"]["id"], "demo");
+    }
+
+    #[test]
+    fn empty_catalog_when_absent_is_default() {
+        let cat = AppCatalog::default();
+        assert!(cat.apps.is_empty());
+        assert!(cat.signature.is_none());
+    }
+
+    #[test]
+    fn catalog_url_derived_from_mirror() {
+        let mirrors = vec![crate::update::UpdateMirror {
+            url: "http://146.59.87.168:3000/lfg2025/archy/raw/branch/main/releases/manifest.json"
+                .to_string(),
+            label: "Server 1".to_string(),
+        }];
+        let urls = catalog_urls_from_mirrors(&mirrors);
+        assert_eq!(
+            urls,
+            vec![
+                "http://146.59.87.168:3000/lfg2025/archy/raw/branch/main/releases/app-catalog.json"
+                    .to_string()
+            ]
+        );
+    }
+}

core/archipelago/src/container/boot_reconciler.rs

@@ -96,6 +96,35 @@ impl BootReconciler {
             }
         }
 
+        // Companion self-heal runs on its OWN cadence, decoupled from the
+        // per-app reconcile pass. On a heavily loaded node `reconcile_existing`
+        // over dozens of apps can take well over a minute, which would delay a
+        // companion-unit repair (deleted/lost unit file) past any reasonable
+        // safety window. Detecting + rewriting a companion unit is cheap, so it
+        // gets a dedicated `interval` loop. The handle is aborted when the main
+        // loop exits (shutdown uses `notify_one`, so we must NOT add a second
+        // waiter on `self.shutdown` — it would steal the single wake permit).
+        let companion_handle = if self.companion_stage {
+            let orchestrator = self.orchestrator.clone();
+            let interval = self.interval;
+            Some(tokio::spawn(async move {
+                loop {
+                    let installed = orchestrator.manifest_ids().await;
+                    for (companion, err) in crate::container::companion::reconcile(&installed).await
+                    {
+                        tracing::warn!(
+                            companion = %companion,
+                            error = %err,
+                            "companion reconcile failed"
+                        );
+                    }
+                    time::sleep(interval).await;
+                }
+            }))
+        } else {
+            None
+        };
+
         // Initial pass: no delay.
         self.tick().await;
 
@@ -111,23 +140,15 @@ impl BootReconciler {
                 }
             }
         }
+
+        if let Some(handle) = companion_handle {
+            handle.abort();
+        }
     }
 
     async fn tick(&self) {
         let report = self.orchestrator.reconcile_existing().await;
         Self::log_report(&report);
-
-        if !self.companion_stage {
-            return;
-        }
-        let installed = self.orchestrator.manifest_ids().await;
-        for (companion, err) in crate::container::companion::reconcile(&installed).await {
-            tracing::warn!(
-                companion = %companion,
-                error = %err,
-                "companion reconcile failed"
-            );
-        }
     }
 
     fn log_report(report: &ReconcileReport) {

core/archipelago/src/container/companion.rs

@@ -102,8 +102,15 @@ const LND_UI: &[CompanionSpec] = &[CompanionSpec {
     ],
     pre_start: None,
     bind_mounts: &[],
-    ports: &[(18083, 80)],
-    host_network: false,
+    // Host networking so the app's own nginx can proxy the archipelago backend
+    // same-origin (127.0.0.1:5678), exactly like fips-ui / electrs-ui. The
+    // previous bridge + 18083→80 mapping forced the browser to fetch the
+    // backend cross-origin from the app's port, which depended on the host
+    // nginx route + a CORS Origin/Host match and broke on http-only nodes
+    // (e.g. .116: blank fields, QR "failed to fetch"). The app's nginx now
+    // listens on 18083 directly (NOT 80 — that would collide with host nginx).
+    ports: &[],
+    host_network: true,
 }];
 
 const ELECTRS_UI: &[CompanionSpec] = &[CompanionSpec {
@@ -214,13 +221,26 @@ async fn ensure_image_present(spec: &CompanionSpec) -> Result<String> {
     for dir in spec.build_dir_candidates {
         let dockerfile = PathBuf::from(dir).join("Dockerfile");
         if fs::try_exists(&dockerfile).await.unwrap_or(false) {
+            // `:local` is a deliberate manual override — never auto-rebuild it.
             if image_exists(&local_image_compat).await {
                 return Ok(local_image_compat);
             }
+            // Reuse the auto-built `:latest` only when the build context has NOT
+            // changed since it was built. Without this staleness check an
+            // already-present image is reused forever, so edits to the baked-in
+            // context (Dockerfile, nginx.conf, …) never reach the node — this is
+            // exactly why the guardian-CSS nginx fix never reached the fleet.
             if image_exists(&local_image).await {
-                return Ok(local_image);
+                if !context_is_newer_than_image(dir, &local_image).await {
+                    return Ok(local_image);
+                }
+                info!(
+                    companion = spec.name,
+                    "build context changed since image built; rebuilding {dir}"
+                );
+            } else {
+                info!(companion = spec.name, "building locally from {dir}");
             }
-            info!(companion = spec.name, "building locally from {dir}");
             let out = command_output_with_timeout(
                 Command::new("podman").args(["build", "-t", &local_image, dir]),
                 COMPANION_BUILD_TIMEOUT,
@@ -265,7 +285,15 @@ async fn ensure_image_present(spec: &CompanionSpec) -> Result<String> {
 
 async fn image_exists(image: &str) -> bool {
     let mut cmd = Command::new("podman");
-    cmd.args(["image", "inspect", image]);
+    // Only the exit status matters. WITHOUT a `--format`, `podman image inspect`
+    // prints the image's full multi-KB manifest JSON; `.status()` inherits the
+    // service's stdout, so on a hit that whole blob lands in the journal — once
+    // per companion image, every reconcile pass. That flood spikes journald +
+    // IO and starves the async runtime (UI websocket then drops → "connection
+    // lost"/reconnect). Discard the child's stdout/stderr; we read neither.
+    cmd.args(["image", "inspect", image])
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::null());
     match tokio::time::timeout(COMPANION_IMAGE_CHECK_TIMEOUT, cmd.status()).await {
         Ok(Ok(status)) => status.success(),
         Ok(Err(err)) => {
@@ -279,6 +307,73 @@ async fn image_exists(image: &str) -> bool {
     }
 }
 
+/// Returns true if any file in the build context `dir` is newer than the
+/// already-built `image`, signalling the cached image is stale and must be
+/// rebuilt. Conservative: if either timestamp can't be determined we return
+/// false (reuse the cache) to avoid rebuild storms on every reconcile pass.
+async fn context_is_newer_than_image(dir: &str, image: &str) -> bool {
+    let image_created = match image_created_unix(image).await {
+        Some(t) => t,
+        None => return false,
+    };
+    match newest_mtime_unix(PathBuf::from(dir)).await {
+        Some(ctx) => ctx > image_created,
+        None => false,
+    }
+}
+
+/// Build timestamp of `image` as Unix seconds, via `podman image inspect`.
+async fn image_created_unix(image: &str) -> Option<i64> {
+    let mut cmd = Command::new("podman");
+    cmd.args(["image", "inspect", "--format", "{{.Created.Unix}}", image]);
+    let out = command_output_with_timeout(
+        &mut cmd,
+        COMPANION_IMAGE_CHECK_TIMEOUT,
+        "podman image created time",
+    )
+    .await
+    .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    String::from_utf8_lossy(&out.stdout).trim().parse::<i64>().ok()
+}
+
+/// Newest modification time (Unix seconds) across all files under `dir`,
+/// walked recursively. Runs on a blocking thread since it touches the fs.
+async fn newest_mtime_unix(dir: PathBuf) -> Option<i64> {
+    tokio::task::spawn_blocking(move || newest_mtime_blocking(&dir))
+        .await
+        .ok()
+        .flatten()
+}
+
+fn newest_mtime_blocking(dir: &std::path::Path) -> Option<i64> {
+    let mut newest: Option<i64> = None;
+    let mut stack = vec![dir.to_path_buf()];
+    while let Some(p) = stack.pop() {
+        let entries = match std::fs::read_dir(&p) {
+            Ok(e) => e,
+            Err(_) => continue,
+        };
+        for entry in entries.flatten() {
+            let meta = match entry.metadata() {
+                Ok(m) => m,
+                Err(_) => continue,
+            };
+            if meta.is_dir() {
+                stack.push(entry.path());
+            } else if let Ok(modified) = meta.modified() {
+                if let Ok(dur) = modified.duration_since(std::time::UNIX_EPOCH) {
+                    let secs = dur.as_secs() as i64;
+                    newest = Some(newest.map_or(secs, |n| n.max(secs)));
+                }
+            }
+        }
+    }
+    newest
+}
+
 async fn command_output_with_timeout(
     cmd: &mut Command,
     timeout: Duration,
@@ -439,12 +534,15 @@ mod tests {
     }
 
     #[test]
-    fn lnd_ui_uses_port_mapping_not_host_port_80() {
+    fn lnd_ui_uses_host_network_for_same_origin_backend_proxy() {
+        // lnd-ui is host-networked (its nginx listens on 18083 directly) so the
+        // app can proxy the archipelago backend same-origin instead of fetching
+        // it cross-origin from its app port — see the spec comment for why.
         let spec = &LND_UI[0];
         let u = build_unit(spec, "localhost/lnd-ui:latest");
         assert_eq!(u.name, "archy-lnd-ui");
-        assert!(matches!(u.network, NetworkMode::Bridge(ref n) if n == "bridge"));
-        assert_eq!(u.ports, vec![(18083, 80, "tcp".into())]);
+        assert!(matches!(u.network, NetworkMode::Host));
+        assert!(u.ports.is_empty());
     }
 
     #[test]

core/archipelago/src/container/docker_packages.rs

@@ -172,8 +172,10 @@ impl DockerPackageScanner {
             // Extract actual version from container image tag
             let running_version = image_versions::extract_version_from_image(&container.image);
 
+            // Decoupled from the binary OTA: prefer the remote app catalog,
+            // falling back to the image-versions.sh pin when uncovered/offline.
             let available_update =
-                image_versions::available_update_for_app(&app_id, &container.image);
+                crate::container::app_catalog::available_update_for_app(&app_id, &container.image);
 
             let package = PackageDataEntry {
                 state: package_state.clone(),
@@ -363,6 +365,13 @@ fn get_app_metadata(app_id: &str) -> AppMetadata {
             repo: "https://github.com/fedimint/fedimint".to_string(),
             tier: "",
         },
+        "fedimint-clientd" | "fmcd" => AppMetadata {
+            title: "Fedimint Client".to_string(),
+            description: "Fedimint ecash client daemon (fmcd) — lets your node hold Fedimint ecash and join federations".to_string(),
+            icon: "/assets/img/app-icons/fedimint.png".to_string(),
+            repo: "https://github.com/minmoto/fmcd".to_string(),
+            tier: "",
+        },
         "morphos" | "morphos-server" => AppMetadata {
             title: "Morphos".to_string(),
             description: "Self-hosted file converter".to_string(),
@@ -682,16 +691,37 @@ fn extract_lan_address(ports: &[String]) -> Option<String> {
     None
 }
 
+/// netbird's dashboard launch URL: HTTPS on 8087 (the proxy terminates TLS —
+/// the dashboard needs a secure context for OIDC PKCE, issue #15) at the node's
+/// primary host IP so it's reachable from the LAN. Manifest-driven netbird no
+/// longer writes `dashboard.env`, so this is derived from host facts (the same
+/// `{{HOST_IP}}` the orchestrator bakes into the cert/config); it falls back to
+/// the static localhost mapping when the host IP can't be read. URL shape is
+/// identical to the legacy installer's, so the existing https reachability
+/// wrapper still applies.
 async fn netbird_configured_launch_url() -> Option<String> {
-    let env = tokio::fs::read_to_string("/var/lib/archipelago/netbird/dashboard.env")
+    if let Some(ip) = first_host_ip().await {
+        return Some(format!("https://{ip}:8087"));
+    }
+    PodmanClient::lan_address_for("netbird")
+}
+
+/// First address from `hostname -I` — the node's primary host IP. Mirrors the
+/// orchestrator's `detect_host_ip` so launch URLs match the cert/config the
+/// orchestrator renders for `{{HOST_IP}}`.
+async fn first_host_ip() -> Option<String> {
+    let out = tokio::process::Command::new("hostname")
+        .arg("-I")
+        .output()
         .await
         .ok()?;
-    env.lines()
-        .find_map(|line| line.strip_prefix("NETBIRD_MGMT_API_ENDPOINT="))
-        .map(str::trim)
-        .filter(|s| !s.is_empty())
+    if !out.status.success() {
+        return None;
+    }
+    String::from_utf8_lossy(&out.stdout)
+        .split_whitespace()
+        .next()
         .map(ToOwned::to_owned)
-        .or_else(|| PodmanClient::lan_address_for("netbird"))
 }
 
 async fn reachable_lan_address(app_id: &str, candidate: Option<String>) -> Option<String> {
@@ -699,7 +729,7 @@ async fn reachable_lan_address(app_id: &str, candidate: Option<String>) -> Optio
     if !requires_reachable_launch(app_id) {
         return Some(url);
     }
-    let Some(port) = url.rsplit(':').next().and_then(|p| p.parse::<u16>().ok()) else {
+    let Some(port) = launch_url_port(&url) else {
         return None;
     };
     if launch_port_reachable(port).await {
@@ -710,6 +740,23 @@ async fn reachable_lan_address(app_id: &str, candidate: Option<String>) -> Optio
     }
 }
 
+/// Extract the TCP port from a launch URL's authority.
+///
+/// The candidate URL can carry a path when it comes from a manifest
+/// `interfaces.main` declaration (e.g. `http://localhost:8096/`). A naive
+/// `rsplit(':')` then yields `"8096/"`, which fails to parse and silently
+/// drops a reachable launch URL. Reading digits after the final colon mirrors
+/// `port_from_url` in the RPC layer and tolerates a trailing path.
+fn launch_url_port(url: &str) -> Option<u16> {
+    let after_colon = url.rsplit_once(':')?.1;
+    after_colon
+        .chars()
+        .take_while(|c| c.is_ascii_digit())
+        .collect::<String>()
+        .parse::<u16>()
+        .ok()
+}
+
 async fn launch_port_reachable(port: u16) -> bool {
     matches!(
         tokio::time::timeout(
@@ -788,3 +835,26 @@ fn package_state_str(state: &PackageState) -> &str {
         PackageState::Updating => "updating",
     }
 }
+
+#[cfg(test)]
+mod launch_url_port_tests {
+    use super::launch_url_port;
+
+    #[test]
+    fn parses_port_with_trailing_path() {
+        // Regression: manifest interfaces.main yields a path-suffixed URL.
+        // The old rsplit(':') parse produced "8096/" and dropped the URL.
+        assert_eq!(launch_url_port("http://localhost:8096/"), Some(8096));
+        assert_eq!(launch_url_port("http://localhost:8175/admin"), Some(8175));
+    }
+
+    #[test]
+    fn parses_bare_authority_port() {
+        assert_eq!(launch_url_port("http://localhost:8083"), Some(8083));
+    }
+
+    #[test]
+    fn rejects_url_without_port() {
+        assert_eq!(launch_url_port("http://localhost/"), None);
+    }
+}

core/archipelago/src/container/hooks.rs

@@ -0,0 +1,203 @@
+//! Manifest-driven lifecycle hook executor (Task #20).
+//!
+//! Runs an app's declarative `post_install` hooks against its **own** running
+//! container. Hooks are an allowlisted, reviewed escape hatch — NOT arbitrary
+//! host scripts:
+//!
+//! - `exec` runs *inside the container* (`podman exec`), never on the host, and
+//!   inherits the container's (already dropped) capabilities.
+//! - `copy_from_host.src` is resolved against an allowlist root, canonicalised,
+//!   and rejected on any escape; only then is it `podman cp`'d into the container.
+//! - Execution is **best-effort + idempotent**: each step is logged, a failure is
+//!   warned and the remaining steps still run, so a transient hook error never
+//!   bricks an install. Authors must make steps safe to re-run (e.g. `grep -q … ||`).
+//!
+//! See `docs/manifest-hooks-design.md`.
+
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+use anyhow::{bail, Result};
+use archipelago_container::{AppManifest, HookStep};
+
+/// Upper bound on a single hook command. Generous — config rewrites + nginx
+/// reloads are fast, but an image with a hung entrypoint shouldn't wedge install.
+const HOOK_TIMEOUT: Duration = Duration::from_secs(60);
+
+/// Roots a `copy_from_host.src` may resolve within. A src is joined onto each
+/// root, canonicalised, and accepted only if it stays inside that root:
+/// - the app's own data dir (`<data_dir>/<app_id>`), and
+/// - `/opt/archipelago` (covers the orchestrator's bundled `web-ui/` assets,
+///   e.g. indeedhub's `web-ui/nostr-provider.js`).
+fn allowlist_roots(app_id: &str, data_dir: &Path) -> Vec<PathBuf> {
+    vec![data_dir.join(app_id), PathBuf::from("/opt/archipelago")]
+}
+
+/// Resolve a hook copy source against the allowlist. Returns the canonical
+/// absolute path iff it exists and lies within an allowlist root. Defence in
+/// depth: `AppManifest::validate` already rejects absolute / `..` srcs, but we
+/// re-check here and canonicalise so a symlink inside a root can't escape it.
+fn resolve_copy_src(src: &str, app_id: &str, data_dir: &Path) -> Result<PathBuf> {
+    if src.is_empty() || src.starts_with('/') || src.contains("..") {
+        bail!("hook copy src '{src}' is not an allowlisted relative path");
+    }
+    for root in allowlist_roots(app_id, data_dir) {
+        let Ok(root_canon) = root.canonicalize() else {
+            continue;
+        };
+        let Ok(canon) = root.join(src).canonicalize() else {
+            continue;
+        };
+        if canon.starts_with(&root_canon) {
+            return Ok(canon);
+        }
+    }
+    bail!("hook copy src '{src}' did not resolve inside an allowlist root")
+}
+
+/// Run an app's declarative `post_install` hooks against its running container.
+/// Best-effort: never returns an error — a failed step is warned and skipped.
+/// Called from the install path after the container is created + running, and
+/// only when a fresh container was created (see `install_fresh`).
+pub async fn run_post_install(manifest: &AppManifest, container_name: &str, data_dir: &Path) {
+    let steps = &manifest.app.hooks.post_install;
+    if steps.is_empty() {
+        return;
+    }
+    let app_id = &manifest.app.id;
+    tracing::info!(
+        app_id = %app_id,
+        container = %container_name,
+        steps = steps.len(),
+        "running manifest post_install hooks"
+    );
+    for (i, step) in steps.iter().enumerate() {
+        match run_step(step, container_name, app_id, data_dir).await {
+            Ok(()) => tracing::debug!(app_id = %app_id, step = i, "post_install hook step ok"),
+            Err(err) => tracing::warn!(
+                app_id = %app_id,
+                container = %container_name,
+                step = i,
+                error = %err,
+                "post_install hook step failed (continuing best-effort)"
+            ),
+        }
+    }
+}
+
+async fn run_step(
+    step: &HookStep,
+    container: &str,
+    app_id: &str,
+    data_dir: &Path,
+) -> Result<()> {
+    match step {
+        HookStep::Exec { exec } => {
+            let mut args: Vec<&str> = Vec::with_capacity(exec.len() + 2);
+            args.push("exec");
+            args.push(container);
+            args.extend(exec.iter().map(String::as_str));
+            // `exec` spawns a process INSIDE the container's cgroup. When the
+            // container was started by archipelago.service, that cgroup is under
+            // the service's slice and a bare `podman exec` from the service can't
+            // write its `cgroup.procs` ("crun: ... Permission denied / OCI
+            // permission denied"). Run it in a transient user scope (its own
+            // delegated cgroup) — mirrors `podman_user_scope` for pasta starts.
+            run_podman(&args, /* scoped */ true).await
+        }
+        HookStep::CopyFromHost { copy_from_host } => {
+            let abs = resolve_copy_src(&copy_from_host.src, app_id, data_dir)?;
+            let abs = abs.to_string_lossy().into_owned();
+            let dest = format!("{container}:{}", copy_from_host.dest);
+            // `cp` is a host-side copy (no in-container process), so no scope needed.
+            run_podman(&["cp", &abs, &dest], /* scoped */ false).await
+        }
+    }
+}
+
+/// Run a podman command, optionally inside a transient systemd user scope. The
+/// scope gives the invocation its own delegated cgroup so `podman exec` can
+/// place its child process — without it, an exec launched from the service's
+/// own cgroup is denied write to the container's `cgroup.procs`.
+async fn run_podman(args: &[&str], scoped: bool) -> Result<()> {
+    let rendered = args.join(" ");
+    let mut cmd = if scoped {
+        let mut c = tokio::process::Command::new("systemd-run");
+        c.args(["--user", "--scope", "--quiet", "--collect", "podman"]);
+        c.args(args);
+        c
+    } else {
+        let mut c = tokio::process::Command::new("podman");
+        c.args(args);
+        c
+    };
+    let out = tokio::time::timeout(HOOK_TIMEOUT, cmd.output())
+        .await
+        .map_err(|_| anyhow::anyhow!("podman {rendered} timed out after {:?}", HOOK_TIMEOUT))?
+        .map_err(|e| anyhow::anyhow!("podman {rendered}: {e}"))?;
+
+    if !out.status.success() {
+        bail!(
+            "podman {rendered} exited {}: {}",
+            out.status,
+            String::from_utf8_lossy(&out.stderr).trim()
+        );
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn resolve_copy_src_accepts_file_in_app_data_dir() {
+        let tmp = tempfile::tempdir().unwrap();
+        let data_dir = tmp.path();
+        let app_dir = data_dir.join("myapp/web-ui");
+        std::fs::create_dir_all(&app_dir).unwrap();
+        std::fs::write(app_dir.join("provider.js"), b"x").unwrap();
+
+        let got = resolve_copy_src("web-ui/provider.js", "myapp", data_dir).unwrap();
+        assert!(got.ends_with("myapp/web-ui/provider.js"));
+        assert!(got.is_absolute());
+    }
+
+    #[test]
+    fn resolve_copy_src_rejects_absolute() {
+        let tmp = tempfile::tempdir().unwrap();
+        assert!(resolve_copy_src("/etc/passwd", "myapp", tmp.path()).is_err());
+    }
+
+    #[test]
+    fn resolve_copy_src_rejects_traversal() {
+        let tmp = tempfile::tempdir().unwrap();
+        assert!(resolve_copy_src("web-ui/../../etc/shadow", "myapp", tmp.path()).is_err());
+    }
+
+    #[test]
+    fn resolve_copy_src_rejects_missing_file() {
+        // Inside the allowlist shape but the file doesn't exist → canonicalize fails.
+        let tmp = tempfile::tempdir().unwrap();
+        std::fs::create_dir_all(tmp.path().join("myapp")).unwrap();
+        assert!(resolve_copy_src("nope.js", "myapp", tmp.path()).is_err());
+    }
+
+    #[test]
+    fn resolve_copy_src_rejects_symlink_escape() {
+        // A symlink inside the app dir pointing outside it must be rejected by
+        // the post-canonicalisation prefix check.
+        let tmp = tempfile::tempdir().unwrap();
+        let app_dir = tmp.path().join("myapp");
+        std::fs::create_dir_all(&app_dir).unwrap();
+        let secret = tmp.path().join("secret.txt");
+        std::fs::write(&secret, b"s").unwrap();
+        let link = app_dir.join("link.js");
+        if std::os::unix::fs::symlink(&secret, &link).is_ok() {
+            // `secret.txt` lives in the tmp root, NOT under <data_dir>/myapp, so
+            // the canonical target escapes the app-data root. It also isn't under
+            // /opt/archipelago. Must be rejected.
+            assert!(resolve_copy_src("link.js", "myapp", tmp.path()).is_err());
+        }
+    }
+}

core/archipelago/src/container/image_versions.rs

@@ -213,7 +213,7 @@ pub fn available_update_for_app(app_id: &str, running_image: &str) -> Option<Str
     available_update_for_images(&pinned, running_image)
 }
 
-fn available_update_for_images(pinned: &str, running_image: &str) -> Option<String> {
+pub fn available_update_for_images(pinned: &str, running_image: &str) -> Option<String> {
     let pinned_version = extract_version_from_image(&pinned);
     if is_floating_tag(&pinned_version) {
         return None;
@@ -255,7 +255,7 @@ fn is_floating_tag(tag: &str) -> bool {
     matches!(tag, "latest" | "stable" | "release" | "main")
 }
 
-fn image_without_registry_or_tag(image: &str) -> &str {
+pub fn image_without_registry_or_tag(image: &str) -> &str {
     let without_tag = strip_tag(image);
     match without_tag.split_once('/') {
         Some((first, rest))

core/archipelago/src/container/lnd.rs

@@ -11,7 +11,16 @@ use crate::update::host_sudo;
 pub const DEFAULT_DATA_DIR: &str = "/var/lib/archipelago/lnd";
 pub const DEFAULT_CONF_PATH: &str = "/var/lib/archipelago/lnd/lnd.conf";
 const LND_REST_BASE_URL: &str = "https://127.0.0.1:18080";
-pub const WALLET_PASSWORD: &str = "hellohello";
+
+/// Per-node LND wallet password file (random, 0600). Replaces the old
+/// fleet-wide hardcoded constant: each node's wallet password is now unique,
+/// high-entropy, and recorded here so the unattended boot path can auto-unlock.
+const WALLET_PASSWORD_SECRET: &str = "/var/lib/archipelago/secrets/lnd-wallet-password";
+
+/// Legacy fleet-wide wallet password (builds that hardcoded it). Kept ONLY as an
+/// unlock fallback so wallets created by those builds still open; new wallets
+/// never use it, and the login-path migration rotates away from it.
+const LEGACY_WALLET_PASSWORD: &str = "hellohello";
 
 #[derive(Debug, Clone)]
 pub struct EnsurePaths {
@@ -79,15 +88,125 @@ pub async fn ensure_wallet_initialized() -> Result<()> {
         if file_exists_as_root(admin_macaroon).await && lnd_getinfo_ready(admin_macaroon).await {
             return Ok(());
         }
-        unlock_existing_wallet().await?;
-        wait_for_admin_macaroon(admin_macaroon).await?;
-        return Ok(());
+        match unlock_existing_wallet().await? {
+            true => {
+                wait_for_admin_macaroon(admin_macaroon).await?;
+                return Ok(());
+            }
+            false => {
+                // Every candidate password was actively rejected: this wallet was
+                // created with a password this node no longer has, so it can never
+                // auto-unlock unattended. Alpha nodes hold no real funds and a wallet
+                // locked with an unknown password is already inaccessible, so wipe +
+                // recreate it on the per-node secret to self-heal at boot.
+                recreate_wallet_destructively().await?;
+                wait_for_admin_macaroon(admin_macaroon).await?;
+                return Ok(());
+            }
+        }
     }
 
     init_wallet_via_rest().await?;
     wait_for_admin_macaroon(admin_macaroon).await
 }
 
+/// LND data subdirectories holding wallet + channel + graph state. Removing them
+/// returns LND to a NON_EXISTING wallet state. Funds-bearing data lives here too,
+/// so deletion is destructive — only done once the wallet is already unrecoverable.
+const LND_STATE_DIRS: &[&str] = &[
+    "/var/lib/archipelago/lnd/data/chain",
+    "/var/lib/archipelago/lnd/data/graph",
+];
+
+/// Podman container name for the core LND app (see `compute_container_name`:
+/// non-UI core apps keep their bare id). LND runs as a plain bridge-network
+/// container, not a Quadlet unit, so it is restarted via `podman`, not systemctl.
+const LND_CONTAINER: &str = "lnd";
+
+/// Archipelago data dir (default; not overridden in prod). Holds the
+/// `user-stopped.json` that gates health-monitor auto-restart.
+const ARCHY_DATA_DIR: &str = "/var/lib/archipelago";
+
+/// Destroy an unrecoverable LND wallet and recreate a fresh one keyed to the
+/// per-node secret. Suppresses health-monitor auto-restart for the wipe window,
+/// stops LND, deletes its wallet/chain/graph state as root, restarts it, waits
+/// for NON_EXISTING, then inits a fresh wallet. Destructive — only called when no
+/// candidate password can open the existing wallet.
+async fn recreate_wallet_destructively() -> Result<()> {
+    tracing::warn!(
+        "[lnd] wallet is locked with an unknown password and cannot auto-unlock; \
+         wiping and recreating it on the per-node secret (DESTRUCTIVE)"
+    );
+
+    // The health monitor restarts any container it sees stopped; mark LND
+    // user-stopped so it doesn't re-launch (and re-open the wallet) mid-wipe.
+    // Always cleared below so LND auto-recovers normally afterwards.
+    let data_dir = std::path::Path::new(ARCHY_DATA_DIR);
+    crate::crash_recovery::mark_user_stopped(data_dir, LND_CONTAINER).await;
+    let result = wipe_and_reinit_wallet().await;
+    crate::crash_recovery::clear_user_stopped(data_dir, LND_CONTAINER).await;
+    result
+}
+
+async fn wipe_and_reinit_wallet() -> Result<()> {
+    podman_user_scoped(&["stop", LND_CONTAINER])
+        .await
+        .context("stopping lnd before wallet wipe")?;
+
+    for dir in LND_STATE_DIRS {
+        let status = host_sudo(&["rm", "-rf", dir])
+            .await
+            .with_context(|| format!("removing {dir}"))?;
+        if !status.success() {
+            anyhow::bail!("removing {dir} exited with {status}");
+        }
+    }
+
+    podman_user_scoped(&["start", LND_CONTAINER])
+        .await
+        .context("restarting lnd after wallet wipe")?;
+
+    wait_for_wallet_state("NON_EXISTING").await?;
+    init_wallet_via_rest().await
+}
+
+/// Run `podman <args>` inside a transient `systemd-run --user --scope`, matching
+/// how the orchestrator/health-monitor manage rootless containers (keeps the
+/// container out of the archipelago service's cgroup).
+async fn podman_user_scoped(args: &[&str]) -> Result<()> {
+    let out = tokio::process::Command::new("systemd-run")
+        .args(["--user", "--scope", "--quiet", "--collect", "podman"])
+        .args(args)
+        .output()
+        .await
+        .with_context(|| format!("systemd-run --user --scope podman {}", args.join(" ")))?;
+    if !out.status.success() {
+        anyhow::bail!(
+            "podman {} failed: {}",
+            args.join(" "),
+            String::from_utf8_lossy(&out.stderr).trim()
+        );
+    }
+    Ok(())
+}
+
+/// Poll `/v1/state` until LND reports `target`, or time out after ~120s.
+async fn wait_for_wallet_state(target: &str) -> Result<()> {
+    let client = reqwest::Client::builder()
+        .no_proxy()
+        .timeout(std::time::Duration::from_secs(5))
+        .danger_accept_invalid_certs(true)
+        .build()
+        .context("building LND REST client")?;
+    for _ in 0..120 {
+        if wallet_state(&client).await.as_deref() == Some(target) {
+            return Ok(());
+        }
+        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+    }
+    anyhow::bail!("LND did not reach state {target} after wallet wipe")
+}
+
 async fn file_exists_as_root(path: &str) -> bool {
     if std::path::Path::new(path).exists() {
         return true;
@@ -121,11 +240,96 @@ async fn read_file_as_root(path: &str) -> Result<Vec<u8>> {
     }
 }
 
-async fn unlock_existing_wallet() -> Result<()> {
+/// Read the per-node wallet password from the secrets file, if present.
+/// Never generates one — absence means "fall back to legacy / not set yet".
+async fn read_wallet_password() -> Option<String> {
+    let bytes = fs::read(WALLET_PASSWORD_SECRET).await.ok()?;
+    let pw = String::from_utf8_lossy(&bytes).trim().to_string();
+    (!pw.is_empty()).then_some(pw)
+}
+
+/// Return the per-node wallet password, generating and persisting a fresh
+/// 256-bit one (base64, 0600) if none exists. Use ONLY when creating a NEW
+/// wallet — calling it merely to unlock an existing wallet would record a
+/// password that doesn't match it.
+pub(crate) async fn ensure_wallet_password() -> Result<String> {
+    if let Some(pw) = read_wallet_password().await {
+        return Ok(pw);
+    }
+    use rand::RngCore;
+    let mut raw = [0u8; 32];
+    rand::rngs::OsRng.fill_bytes(&mut raw);
+    let pw = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(raw);
+    let path = std::path::Path::new(WALLET_PASSWORD_SECRET);
+    if let Some(dir) = path.parent() {
+        fs::create_dir_all(dir)
+            .await
+            .with_context(|| format!("creating {}", dir.display()))?;
+    }
+    fs::write(path, &pw)
+        .await
+        .with_context(|| format!("writing {WALLET_PASSWORD_SECRET}"))?;
+    use std::os::unix::fs::PermissionsExt;
+    let _ = fs::set_permissions(path, std::fs::Permissions::from_mode(0o600)).await;
+    Ok(pw)
+}
+
+/// Candidate passwords to try when unlocking an EXISTING wallet, in order: the
+/// per-node secret (current scheme) first, then the legacy constant so wallets
+/// created by older builds still open.
+async fn unlock_password_candidates() -> Vec<String> {
+    let mut v = Vec::new();
+    if let Some(pw) = read_wallet_password().await {
+        v.push(pw);
+    }
+    v.push(LEGACY_WALLET_PASSWORD.to_string());
+    v
+}
+
+/// Outcome of a single unlock attempt — lets the caller fail fast on a wrong
+/// password (no point retrying) vs keep waiting for LND to come up.
+enum UnlockAttempt {
+    Unlocked,
+    WrongPassword,
+    NotReady,
+}
+
+/// One unlock POST, no internal retry. Distinguishes "invalid passphrase"
+/// (WrongPassword — try the next candidate, don't retry) from transient
+/// not-ready / connection errors (NotReady — worth retrying).
+async fn try_unlock_once(client: &reqwest::Client, password: &str) -> UnlockAttempt {
+    let body = serde_json::json!({
+        "wallet_password": base64::engine::general_purpose::STANDARD.encode(password)
+    });
+    match client
+        .post(format!("{LND_REST_BASE_URL}/v1/unlockwallet"))
+        .json(&body)
+        .send()
+        .await
+    {
+        Ok(resp) => {
+            let status = resp.status();
+            let text = resp.text().await.unwrap_or_default();
+            if status.is_success() || text.contains("already unlocked") {
+                UnlockAttempt::Unlocked
+            } else if text.contains("invalid passphrase") {
+                UnlockAttempt::WrongPassword
+            } else {
+                UnlockAttempt::NotReady
+            }
+        }
+        Err(_) => UnlockAttempt::NotReady,
+    }
+}
+
+/// Unlock an existing wallet. Ok(true) = unlocked; Ok(false) = every candidate
+/// password was actively rejected (unrecoverable — caller should recreate);
+/// Err = transient (LND not ready / timeout — caller should retry, NOT wipe).
+async fn unlock_existing_wallet() -> Result<bool> {
     unlock_existing_wallet_via_rest().await
 }
 
-async fn unlock_existing_wallet_via_rest() -> Result<()> {
+async fn unlock_existing_wallet_via_rest() -> Result<bool> {
     let client = reqwest::Client::builder()
         .no_proxy()
         .timeout(std::time::Duration::from_secs(20))
@@ -133,57 +337,130 @@ async fn unlock_existing_wallet_via_rest() -> Result<()> {
         .build()
         .context("building LND REST client")?;
 
-    let wallet_password = base64::engine::general_purpose::STANDARD.encode(WALLET_PASSWORD);
-    match post_lnd_unlocker_json::<serde_json::Value>(
-        &client,
-        "/v1/unlockwallet",
-        serde_json::json!({ "wallet_password": wallet_password }),
-    )
-    .await
-    .context("unlocking existing LND wallet")?
-    {
-        UnlockerResponse::Value(_) | UnlockerResponse::WalletAlreadyExists => Ok(()),
+    let candidates = unlock_password_candidates().await;
+    // Retry only while LND's unlocker isn't ready yet. If every candidate is
+    // *actively rejected* (invalid passphrase), retrying can't help — fail fast
+    // with a clear message instead of hanging the boot path for 60s+ (the wallet
+    // was created with a password this node doesn't have → migration/recovery).
+    for _ in 0..60 {
+        let mut all_rejected = true;
+        for pw in &candidates {
+            match try_unlock_once(&client, pw).await {
+                UnlockAttempt::Unlocked => return Ok(true),
+                UnlockAttempt::WrongPassword => {}
+                UnlockAttempt::NotReady => all_rejected = false,
+            }
+        }
+        if all_rejected {
+            tracing::warn!(
+                "[lnd] none of the {} candidate password(s) unlock the wallet — it was created \
+                 with a password this node does not have",
+                candidates.len()
+            );
+            return Ok(false);
+        }
+        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+    }
+    anyhow::bail!("LND wallet unlock timed out waiting for the unlocker to become ready")
+}
+
+/// Current LND wallet state via the unauthenticated `/v1/state` endpoint
+/// (NON_EXISTING / LOCKED / UNLOCKED / RPC_ACTIVE / …). None if unreachable.
+async fn wallet_state(client: &reqwest::Client) -> Option<String> {
+    let resp = client
+        .get(format!("{LND_REST_BASE_URL}/v1/state"))
+        .send()
+        .await
+        .ok()?;
+    let v: serde_json::Value = resp.json().await.ok()?;
+    v.get("state")
+        .and_then(|s| s.as_str())
+        .map(|s| s.to_string())
+}
+
+/// ChangePassword via WalletUnlocker (wallet must be LOCKED). Both passwords are
+/// base64-encoded. Ok(true) = current accepted and rotated; Ok(false) = current
+/// rejected (wrong password — try the next candidate); Err = transport/other.
+async fn change_wallet_password(
+    client: &reqwest::Client,
+    current: &str,
+    new: &str,
+) -> Result<bool> {
+    let body = serde_json::json!({
+        "current_password": base64::engine::general_purpose::STANDARD.encode(current),
+        "new_password": base64::engine::general_purpose::STANDARD.encode(new),
+    });
+    let resp = client
+        .post(format!("{LND_REST_BASE_URL}/v1/changepassword"))
+        .json(&body)
+        .send()
+        .await
+        .context("calling LND changepassword")?;
+    let status = resp.status();
+    let text = resp.text().await.unwrap_or_default();
+    if status.is_success() {
+        Ok(true)
+    } else if text.contains("invalid passphrase") {
+        Ok(false)
+    } else {
+        anyhow::bail!("LND changepassword returned {status}: {text}")
     }
 }
 
-#[allow(dead_code)]
-async fn unlock_existing_wallet_via_lncli() -> Result<()> {
-    let mut last_err = None;
-    for _ in 0..60 {
-        let mut cmd = tokio::process::Command::new("podman");
-        cmd.args(["exec", "-i", "lnd", "lncli", "unlock", "--stdin"]);
-        cmd.stdin(std::process::Stdio::piped());
-        cmd.stdout(std::process::Stdio::piped());
-        cmd.stderr(std::process::Stdio::piped());
+/// Best-effort migration of a LOCKED wallet onto the per-node secret. Called at
+/// login, when the onboarding password is available as a candidate. If the
+/// per-node secret already opens the wallet, just unlock. Otherwise try each
+/// candidate as the CURRENT password and ChangePassword it to a fresh per-node
+/// secret so all future boots auto-unlock. Ok(true) = healed/unlocked;
+/// Ok(false) = not locked, or no candidate worked (seed-recovery required).
+pub(crate) async fn migrate_locked_wallet(candidates: &[String]) -> Result<bool> {
+    let client = reqwest::Client::builder()
+        .no_proxy()
+        .timeout(std::time::Duration::from_secs(20))
+        .danger_accept_invalid_certs(true)
+        .build()
+        .context("building LND REST client")?;
 
-        let mut child = cmd.spawn().context("spawning lncli wallet unlock")?;
-        if let Some(mut stdin) = child.stdin.take() {
-            use tokio::io::AsyncWriteExt;
-            stdin
-                .write_all(format!("{}\n", WALLET_PASSWORD).as_bytes())
-                .await
-                .context("writing lncli password")?;
-        }
-        let out = child
-            .wait_with_output()
-            .await
-            .context("waiting for lncli")?;
-        if out.status.success() {
-            return Ok(());
-        }
-        let stderr = String::from_utf8_lossy(&out.stderr);
-        let stdout = String::from_utf8_lossy(&out.stdout);
-        let msg = format!("{stderr}{stdout}");
-        if msg.contains("wallet already unlocked") || msg.contains("already unlocked") {
-            return Ok(());
-        }
-        last_err = Some(msg);
-        tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+    // Only act on a wallet that is actually LOCKED.
+    if wallet_state(&client).await.as_deref() != Some("LOCKED") {
+        return Ok(false);
     }
-    anyhow::bail!(
-        "lncli wallet unlock failed: {}",
-        last_err.unwrap_or_else(|| "unknown error".to_string())
-    )
+
+    // If the per-node secret already opens it, nothing to rotate — just unlock.
+    if let Some(secret) = read_wallet_password().await {
+        if matches!(
+            try_unlock_once(&client, &secret).await,
+            UnlockAttempt::Unlocked
+        ) {
+            return Ok(true);
+        }
+    }
+
+    // The wallet's new password becomes the per-node secret (generate if absent).
+    let new_secret = ensure_wallet_password().await?;
+
+    // ChangePassword requires LOCKED; bail out if a prior step already unlocked.
+    if wallet_state(&client).await.as_deref() != Some("LOCKED") {
+        return Ok(true);
+    }
+
+    for cand in candidates {
+        if cand.is_empty() || *cand == new_secret {
+            continue;
+        }
+        match change_wallet_password(&client, cand, &new_secret).await {
+            Ok(true) => {
+                tracing::info!("[lnd-migrate] rotated locked wallet onto the per-node secret");
+                return Ok(true);
+            }
+            Ok(false) => continue, // wrong current password — try next candidate
+            Err(e) => tracing::debug!("[lnd-migrate] changepassword error: {e}"),
+        }
+    }
+    tracing::warn!(
+        "[lnd-migrate] no candidate password opened the wallet — seed-recovery required"
+    );
+    Ok(false)
 }
 
 #[derive(Debug, Deserialize)]
@@ -225,7 +502,8 @@ async fn init_wallet_via_rest() -> Result<()> {
         anyhow::bail!("LND genseed returned no seed words");
     }
 
-    let wallet_password = base64::engine::general_purpose::STANDARD.encode(WALLET_PASSWORD);
+    let wallet_password =
+        base64::engine::general_purpose::STANDARD.encode(ensure_wallet_password().await?);
     let req = InitWalletRequest {
         wallet_password,
         cipher_seed_mnemonic: seed.cipher_seed_mnemonic,
@@ -239,7 +517,9 @@ async fn init_wallet_via_rest() -> Result<()> {
     .context("initializing LND wallet")?
     {
         UnlockerResponse::Value(_) => {}
-        UnlockerResponse::WalletAlreadyExists => unlock_existing_wallet().await?,
+        UnlockerResponse::WalletAlreadyExists => {
+            unlock_existing_wallet().await?;
+        }
     }
 
     Ok(())
@@ -450,7 +730,16 @@ mod tests {
     }
 
     #[test]
-    fn wallet_password_is_valid_for_lncli() {
-        assert!(WALLET_PASSWORD.len() > 8);
+    fn legacy_wallet_password_is_valid_for_lncli() {
+        // Legacy fallback must still be a valid lncli passphrase (>8 chars).
+        assert!(LEGACY_WALLET_PASSWORD.len() > 8);
+    }
+
+    #[tokio::test]
+    async fn unlock_candidates_always_include_legacy_fallback() {
+        // With no per-node secret on disk in the test env, candidates fall back
+        // to the legacy constant so old wallets still open.
+        let cands = unlock_password_candidates().await;
+        assert!(cands.iter().any(|p| p == LEGACY_WALLET_PASSWORD));
     }
 }

core/archipelago/src/container/mod.rs

@@ -1,3 +1,4 @@
+pub mod app_catalog;
 pub mod bitcoin_ui;
 pub mod boot_reconciler;
 pub mod companion;
@@ -5,11 +6,13 @@ pub mod data_manager;
 pub mod dev_orchestrator;
 pub mod docker_packages;
 pub mod filebrowser;
+pub mod hooks;
 pub mod image_versions;
 pub mod lnd;
 pub mod prod_orchestrator;
 pub mod quadlet;
 pub mod registry;
+pub mod secrets;
 pub mod traits;
 
 pub use boot_reconciler::{BootReconciler, DEFAULT_INTERVAL as RECONCILER_DEFAULT_INTERVAL};