Merge pull request 'fix(wallet+companion): pre-demo blockers — Send modal TDZ crash, cold-start inset collapse, loader branding — 0.5.10' (#118) from fix/safe-area-insets into main

- SendBitcoinModal crashed AT MOUNT on device ('Cannot access R before
  initialization'): the invoice-first block's watch() evaluates its
  computed source at setup, which read effectiveMethod while still in
  its temporal dead zone (declared 20 lines later). Send button did
  nothing and the failure poisoned sibling modal data. Block moved below
  effectiveMethod, with a comment so it can't drift back.
- Cold start injected 0px safe-area vars (onPageFinished can beat window
  attachment; rootWindowInsets null) — UI lost top/bottom margins and
  the tab bar sat in the gesture zone eating taps. Injection extracted
  to injectSafeAreaVars(), re-fired from an OnApplyWindowInsetsListener
  when real insets arrive, on page finish, and on reattach.
- MeshLoadingScreen wears the proper brand: pixel 'a' in the black
  circle-container + F*CK IPS MESH wordmark.

Served APK: 0.5.10 (vc30). Reproduced+diagnosed live on-device.

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

.dockerignore

@@ -7,6 +7,14 @@
 # Allow demo assets (AIUI pre-built dist)
 !demo/
 
+# Allow the Bitcoin UI + ElectrumX UI mock shells (served from /docker/*)
+!docker/
+docker/*
+!docker/bitcoin-ui/
+!docker/electrs-ui/
+!docker/lnd-ui/
+!docker/fedimint-ui/
+
 # Allow backend source for ISO source builds
 !core/
 !scripts/

.gitea/workflows/demo-images.yml

@@ -0,0 +1,74 @@
+name: Demo images
+
+# Builds and pushes the public-demo images on every change to the UI / mock
+# backend, so the separated `archy-demo` Portainer stack auto-tracks the real
+# code (see demo-deploy/ and docs/demo-deployment-design.md).
+#
+# Required repo configuration:
+#   vars.DEMO_REGISTRY        e.g. 146.59.87.168:3000/lfg2025
+#   vars.DEMO_REGISTRY_HOST   registry host for docker login (no org suffix)
+#   secrets.DEMO_REGISTRY_USER
+#   secrets.DEMO_REGISTRY_TOKEN
+# Optional:
+#   secrets.PORTAINER_WEBHOOK  redeploy hook called after a successful push
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'neode-ui/**'
+      - 'docker-compose.demo.yml'
+      - '.gitea/workflows/demo-images.yml'
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build & push demo images
+    runs-on: ubuntu-latest
+    # Skip cleanly on forks / before registry config is set.
+    if: ${{ vars.DEMO_REGISTRY != '' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          # The demo registry is plain HTTP — teach buildkit to push without TLS
+          # (the host docker daemon needs it in insecure-registries for login too).
+          buildkitd-config-inline: |
+            [registry."${{ vars.DEMO_REGISTRY_HOST || vars.DEMO_REGISTRY }}"]
+              http = true
+
+      - name: Log in to registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ vars.DEMO_REGISTRY_HOST || vars.DEMO_REGISTRY }}
+          username: ${{ secrets.DEMO_REGISTRY_USER }}
+          password: ${{ secrets.DEMO_REGISTRY_TOKEN }}
+
+      - name: Build & push backend
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: neode-ui/Dockerfile.backend
+          push: true
+          tags: |
+            ${{ vars.DEMO_REGISTRY }}/archy-demo-backend:demo
+            ${{ vars.DEMO_REGISTRY }}/archy-demo-backend:${{ github.sha }}
+
+      - name: Build & push web
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: neode-ui/Dockerfile.web
+          push: true
+          build-args: |
+            VITE_DEMO=1
+          tags: |
+            ${{ vars.DEMO_REGISTRY }}/archy-demo-web:demo
+            ${{ vars.DEMO_REGISTRY }}/archy-demo-web:${{ github.sha }}
+
+      - name: Trigger Portainer redeploy
+        if: ${{ success() && secrets.PORTAINER_WEBHOOK != '' }}
+        run: curl -fsS -X POST "${{ secrets.PORTAINER_WEBHOOK }}"

.github/workflows/demo-images.yml

@@ -0,0 +1,74 @@
+name: Demo images
+
+# Builds and pushes the public-demo images on every change to the UI / mock
+# backend, so the separated `archy-demo` Portainer stack auto-tracks the real
+# code (see demo-deploy/ and docs/demo-deployment-design.md).
+#
+# Required repo configuration:
+#   vars.DEMO_REGISTRY        e.g. 146.59.87.168:3000/lfg2025
+#   vars.DEMO_REGISTRY_HOST   registry host for docker login (no org suffix)
+#   secrets.DEMO_REGISTRY_USER
+#   secrets.DEMO_REGISTRY_TOKEN
+# Optional:
+#   secrets.PORTAINER_WEBHOOK  redeploy hook called after a successful push
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'neode-ui/**'
+      - 'docker-compose.demo.yml'
+      - '.github/workflows/demo-images.yml'
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build & push demo images
+    runs-on: ubuntu-latest
+    # Skip cleanly on forks / before registry config is set.
+    if: ${{ vars.DEMO_REGISTRY != '' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          # The demo registry is plain HTTP — teach buildkit to push without TLS
+          # (the host docker daemon needs it in insecure-registries for login too).
+          buildkitd-config-inline: |
+            [registry."${{ vars.DEMO_REGISTRY_HOST || vars.DEMO_REGISTRY }}"]
+              http = true
+
+      - name: Log in to registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ vars.DEMO_REGISTRY_HOST || vars.DEMO_REGISTRY }}
+          username: ${{ secrets.DEMO_REGISTRY_USER }}
+          password: ${{ secrets.DEMO_REGISTRY_TOKEN }}
+
+      - name: Build & push backend
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: neode-ui/Dockerfile.backend
+          push: true
+          tags: |
+            ${{ vars.DEMO_REGISTRY }}/archy-demo-backend:demo
+            ${{ vars.DEMO_REGISTRY }}/archy-demo-backend:${{ github.sha }}
+
+      - name: Build & push web
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: neode-ui/Dockerfile.web
+          push: true
+          build-args: |
+            VITE_DEMO=1
+          tags: |
+            ${{ vars.DEMO_REGISTRY }}/archy-demo-web:demo
+            ${{ vars.DEMO_REGISTRY }}/archy-demo-web:${{ github.sha }}
+
+      - name: Trigger Portainer redeploy
+        if: ${{ success() && secrets.PORTAINER_WEBHOOK != '' }}
+        run: curl -fsS -X POST "${{ secrets.PORTAINER_WEBHOOK }}"

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "indeedhub"]
 	path = indeedhub
-	url = https://git.tx1138.com/lfg2025/indeehub.git
+	url = http://146.59.87.168:3000/lfg2025/indeehub.git

Android/.gitignore

@@ -19,3 +19,7 @@ local.properties
 # 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
+
+# Rust build outputs (archy-fips-core → jniLibs via buildRustArm64)
+/rust/archy-fips-core/target
+/app/src/main/jniLibs

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,12 +11,17 @@ android {
         applicationId = "com.archipelago.app"
         minSdk = 26
         targetSdk = 35
-        versionCode = 13
-        versionName = "0.4.9"
+        versionCode = 30
+        versionName = "0.5.10"
 
         vectorDrawables {
             useSupportLibrary = true
         }
+
+        // The embedded FIPS mesh (libarchy_fips_core.so) is built arm64-only,
+        // matching real handsets. FipsNative.available gates every call, so
+        // the app still runs as a plain companion elsewhere (e.g. x86 emu).
+        ndk { abiFilters += "arm64-v8a" }
     }
 
     signingConfigs {
@@ -80,6 +85,44 @@ android {
     }
 }
 
+// ---------------------------------------------------------------------------
+// Embedded FIPS mesh: cross-compile Android/rust/archy-fips-core via cargo-ndk
+// into jniLibs before the native-libs merge, so a plain `gradlew assembleDebug`
+// builds the Rust too. Requires rustup target aarch64-linux-android, cargo-ndk,
+// and an NDK (ANDROID_NDK_HOME or the SDK's ndk/ dir).
+// ---------------------------------------------------------------------------
+val rustCrateDir = layout.projectDirectory.dir("../rust/archy-fips-core")
+val jniLibsDir = layout.projectDirectory.dir("src/main/jniLibs")
+
+tasks.register<Exec>("buildRustArm64") {
+    workingDir = rustCrateDir.asFile
+    inputs.dir(rustCrateDir.dir("src"))
+    inputs.file(rustCrateDir.file("Cargo.toml"))
+    outputs.dir(jniLibsDir)
+    // cargo/cargo-ndk live in ~/.cargo/bin, which Gradle's env may not have.
+    val home = System.getProperty("user.home")
+    environment("PATH", "$home/.cargo/bin:${System.getenv("PATH")}")
+    if (System.getenv("ANDROID_NDK_HOME") == null) {
+        val sdkNdk = file("$home/Library/Android/sdk/ndk")
+            .listFiles()?.maxByOrNull { it.name }
+        if (sdkNdk != null) environment("ANDROID_NDK_HOME", sdkNdk.absolutePath)
+    }
+    commandLine(
+        "cargo", "ndk",
+        "-t", "arm64-v8a",
+        "--platform", "26",
+        "-o", jniLibsDir.asFile.absolutePath,
+        "build", "--release",
+    )
+}
+
+tasks.matching {
+    it.name in listOf(
+        "mergeDebugNativeLibs", "mergeReleaseNativeLibs",
+        "mergeDebugJniLibFolders", "mergeReleaseJniLibFolders",
+    )
+}.configureEach { dependsOn("buildRustArm64") }
+
 dependencies {
     val composeBom = platform("androidx.compose:compose-bom:2024.05.00")
     implementation(composeBom)
@@ -111,6 +154,12 @@ dependencies {
     // OkHttp for WebSocket (remote input)
     implementation("com.squareup.okhttp3:okhttp:4.12.0")
 
+    // CameraX + ZXing (Apache-2.0, on-device, no telemetry) for pairing-QR scanning
+    implementation("androidx.camera:camera-camera2:1.3.4")
+    implementation("androidx.camera:camera-lifecycle:1.3.4")
+    implementation("androidx.camera:camera-view:1.3.4")
+    implementation("com.google.zxing:core:3.5.3")
+
     debugImplementation("androidx.compose.ui:ui-tooling")
     debugImplementation("androidx.compose.ui:ui-test-manifest")
 }

Android/app/src/main/AndroidManifest.xml

@@ -4,6 +4,13 @@
 
     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <!-- Pairing-QR scanner. Camera is optional: manual entry still works without one. -->
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-feature android:name="android.hardware.camera.any" android:required="false" />
+    <!-- Embedded FIPS mesh tunnel (ArchyVpnService) runs as a foreground service. -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
 
     <application
         android:name=".ArchipelagoApp"
@@ -16,9 +23,22 @@
         android:usesCleartextTraffic="true"
         tools:targetApi="35">
 
+        <!-- Party-screen "Share this app": exposes the copied APK from
+             cache/share/ to the system share sheet, nothing else. -->
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.fileprovider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/file_paths" />
+        </provider>
+
         <activity
             android:name=".MainActivity"
             android:exported="true"
+            android:launchMode="singleTask"
             android:theme="@style/Theme.Archipelago.Splash"
             android:windowSoftInputMode="adjustResize"
             android:configChanges="orientation|screenSize|screenLayout|keyboardHidden">
@@ -26,7 +46,30 @@
                 <action android:name="android.intent.action.MAIN" />
                 <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
+            <!-- Pairing deep link from the web UI's Companion popup:
+                 archipelago://pair?v=1&url=...[&pw=...] (docs/companion-pairing-qr.md) -->
+            <intent-filter>
+                <action android:name="android.intent.action.VIEW" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <category android:name="android.intent.category.BROWSABLE" />
+                <data android:scheme="archipelago" android:host="pair" />
+            </intent-filter>
         </activity>
+
+        <!-- Embedded FIPS mesh node: split-tunnel VpnService (fd00::/8 only),
+             configured entirely by scanning the node's pairing QR. -->
+        <service
+            android:name=".fips.ArchyVpnService"
+            android:exported="false"
+            android:foregroundServiceType="specialUse"
+            android:permission="android.permission.BIND_VPN_SERVICE">
+            <property
+                android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
+                android:value="mesh-vpn-tunnel" />
+            <intent-filter>
+                <action android:name="android.net.VpnService" />
+            </intent-filter>
+        </service>
     </application>
 
 </manifest>

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

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

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

@@ -19,25 +19,45 @@ data class ServerEntry(
     val port: String = "",
     val password: String = "",
     val name: String = "",
+    /** Node's FIPS mesh ULA (IPv6) — reachable from anywhere once meshed. */
+    val meshIp: String = "",
+    /** Node's FIPS npub — the durable identity. When present it, not the
+     *  address, is what identifies the entry: FIPS peers on npubs, IPs are
+     *  only dial hints (docs/companion-pairing-qr.md, npub-first contract). */
+    val npub: String = "",
 ) {
     /** Label to show in lists — the user-given name, or the address if unnamed. */
     fun displayName(): String = name.ifBlank { address }
 
+    /** Bracket bare IPv6 literals (the mesh ULA) so they form valid URLs. */
+    private fun urlHost(host: String): String =
+        if (host.contains(":") && !host.startsWith("[")) "[$host]" else host
+
     fun toUrl(): String {
         val scheme = if (useHttps) "https" else "http"
         val portSuffix = if (port.isNotBlank()) ":$port" else ""
-        return "$scheme://$address$portSuffix"
+        return "$scheme://${urlHost(address)}$portSuffix"
     }
 
     fun toWsUrl(): String {
         val scheme = if (useHttps) "wss" else "ws"
         val portSuffix = if (port.isNotBlank()) ":$port" else ""
-        return "$scheme://$address$portSuffix"
+        return "$scheme://${urlHost(address)}$portSuffix"
     }
 
-    // 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"
+    /** Mesh-address UI URL, or null when the node never advertised one. */
+    fun toMeshUrl(): String? =
+        meshIp.takeIf { it.isNotBlank() }?.let { "http://${urlHost(it)}" }
+
+    // name/meshIp/npub are trailing fields so entries saved before they
+    // existed (4/5/6 fields) still deserialize, defaulting to "".
+    fun serialize(): String = "$address|$useHttps|$port|$password|$name|$meshIp|$npub"
+
+    /** Same node as [other]? npub identity wins; address/port/scheme is the
+     *  fallback for LAN-only entries that never advertised FIPS. */
+    fun sameNode(other: ServerEntry): Boolean =
+        (npub.isNotBlank() && npub == other.npub) ||
+            (address == other.address && port == other.port && useHttps == other.useHttps)
 
     companion object {
         fun deserialize(raw: String): ServerEntry? {
@@ -49,6 +69,8 @@ data class ServerEntry(
                 port = parts.getOrElse(2) { "" },
                 password = parts.getOrElse(3) { "" },
                 name = parts.getOrElse(4) { "" },
+                meshIp = parts.getOrElse(5) { "" },
+                npub = parts.getOrElse(6) { "" },
             )
         }
     }
@@ -61,8 +83,11 @@ class ServerPreferences(private val context: Context) {
     private val activePortKey = stringPreferencesKey("active_port")
     private val activePasswordKey = stringPreferencesKey("active_password")
     private val activeNameKey = stringPreferencesKey("active_name")
+    private val activeMeshIpKey = stringPreferencesKey("active_mesh_ip")
+    private val activeNpubKey = stringPreferencesKey("active_npub")
     private val savedServersKey = stringSetPreferencesKey("saved_servers")
     private val introSeenKey = booleanPreferencesKey("intro_seen")
+    private val gestureHintSeenKey = booleanPreferencesKey("gesture_hint_seen")
 
     val activeServer: Flow<ServerEntry?> = context.dataStore.data.map { prefs ->
         val address = prefs[activeAddressKey] ?: return@map null
@@ -72,6 +97,8 @@ class ServerPreferences(private val context: Context) {
             port = prefs[activePortKey] ?: "",
             password = prefs[activePasswordKey] ?: "",
             name = prefs[activeNameKey] ?: "",
+            meshIp = prefs[activeMeshIpKey] ?: "",
+            npub = prefs[activeNpubKey] ?: "",
         )
     }
 
@@ -84,6 +111,11 @@ class ServerPreferences(private val context: Context) {
         prefs[introSeenKey] ?: false
     }
 
+    /** One-shot flag for the three-finger-hold teaching overlay. */
+    val gestureHintSeen: Flow<Boolean> = context.dataStore.data.map { prefs ->
+        prefs[gestureHintSeenKey] ?: false
+    }
+
     suspend fun setActiveServer(server: ServerEntry) {
         context.dataStore.edit { prefs ->
             prefs[activeAddressKey] = server.address
@@ -91,6 +123,8 @@ class ServerPreferences(private val context: Context) {
             prefs[activePortKey] = server.port
             prefs[activePasswordKey] = server.password
             prefs[activeNameKey] = server.name
+            prefs[activeMeshIpKey] = server.meshIp
+            prefs[activeNpubKey] = server.npub
         }
         addSavedServer(server)
     }
@@ -102,6 +136,8 @@ class ServerPreferences(private val context: Context) {
             prefs.remove(activePortKey)
             prefs.remove(activePasswordKey)
             prefs.remove(activeNameKey)
+            prefs.remove(activeMeshIpKey)
+            prefs.remove(activeNpubKey)
         }
     }
 
@@ -112,18 +148,81 @@ class ServerPreferences(private val context: Context) {
         }
     }
 
+    /**
+     * Replace a saved server in place. Matches the existing entry by node
+     * identity — npub first, address/port/scheme as the LAN-only fallback
+     * (ServerEntry.sameNode) — so edits that change the name, password or even
+     * every address still update the right record. An edit form that doesn't
+     * carry the npub keeps the stored one. If the edited server is also the
+     * active one, the active record is kept in sync.
+     */
+    suspend fun updateSavedServer(original: ServerEntry, updated: ServerEntry) {
+        val toStore = updated.copy(npub = updated.npub.ifBlank { original.npub })
+        context.dataStore.edit { prefs ->
+            val current = prefs[savedServersKey] ?: emptySet()
+            val filtered = current.filterNot { raw ->
+                ServerEntry.deserialize(raw)?.sameNode(original) == true
+            }.toSet()
+            prefs[savedServersKey] = filtered + toStore.serialize()
+
+            val activeNpub = prefs[activeNpubKey] ?: ""
+            val isActive = (activeNpub.isNotBlank() && activeNpub == original.npub) ||
+                (
+                    prefs[activeAddressKey] == original.address &&
+                        (prefs[activePortKey] ?: "") == original.port &&
+                        (prefs[activeHttpsKey] ?: false) == original.useHttps
+                    )
+            if (isActive) {
+                prefs[activeAddressKey] = toStore.address
+                prefs[activeHttpsKey] = toStore.useHttps
+                prefs[activePortKey] = toStore.port
+                prefs[activePasswordKey] = toStore.password
+                prefs[activeNameKey] = toStore.name
+                prefs[activeMeshIpKey] = toStore.meshIp
+                prefs[activeNpubKey] = toStore.npub
+            }
+        }
+    }
+
+    /**
+     * Add a server, or update the entry for the same node — npub first,
+     * address/port/scheme as the LAN-only fallback (ServerEntry.sameNode) —
+     * used by QR pairing so re-scanning a node never duplicates it, even after
+     * the LAN renumbered and every address changed (npub-first contract in
+     * docs/companion-pairing-qr.md). A blank incoming password/name keeps the
+     * stored value (a real node's QR never carries the password). Returns the
+     * merged entry.
+     */
+    suspend fun upsertServer(server: ServerEntry): ServerEntry {
+        var merged = server
+        context.dataStore.edit { prefs ->
+            val current = prefs[savedServersKey] ?: emptySet()
+            val existing = current.mapNotNull { ServerEntry.deserialize(it) }
+                .firstOrNull { it.sameNode(server) }
+            if (existing != null) {
+                merged = server.copy(
+                    password = server.password.ifBlank { existing.password },
+                    name = server.name.ifBlank { existing.name },
+                    meshIp = server.meshIp.ifBlank { existing.meshIp },
+                    npub = server.npub.ifBlank { existing.npub },
+                )
+            }
+            val filtered = current.filterNot { raw ->
+                ServerEntry.deserialize(raw)?.sameNode(merged) == true
+            }.toSet()
+            prefs[savedServersKey] = filtered + merged.serialize()
+        }
+        return merged
+    }
+
     suspend fun removeSavedServer(server: ServerEntry) {
         context.dataStore.edit { prefs ->
             val current = prefs[savedServersKey] ?: emptySet()
-            // 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.
+            // Match by node identity (npub, else address/port/scheme) rather
+            // than the exact serialized string, so a rename — or a legacy
+            // short-format entry — still removes the right record.
             prefs[savedServersKey] = current.filterNot { raw ->
-                val e = ServerEntry.deserialize(raw)
-                e != null &&
-                    e.address == server.address &&
-                    e.port == server.port &&
-                    e.useHttps == server.useHttps
+                ServerEntry.deserialize(raw)?.sameNode(server) == true
             }.toSet()
         }
     }
@@ -133,4 +232,10 @@ class ServerPreferences(private val context: Context) {
             prefs[introSeenKey] = true
         }
     }
+
+    suspend fun markGestureHintSeen() {
+        context.dataStore.edit { prefs ->
+            prefs[gestureHintSeenKey] = true
+        }
+    }
 }

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

@@ -0,0 +1,118 @@
+package com.archipelago.app.data
+
+import android.net.Uri
+import com.archipelago.app.fips.AnchorPeer
+import com.archipelago.app.fips.FipsPairInfo
+
+/**
+ * Result of parsing a pairing QR / deep link.
+ *
+ * UnsupportedVersion means the payload is structurally a pairing URI but its
+ * major version is newer than this app understands — the UI should tell the
+ * user to update the app rather than call the code invalid.
+ */
+sealed class PairResult {
+    data class Success(
+        val server: ServerEntry,
+        /** Mesh info when the node advertises FIPS (fnpub present). */
+        val fips: FipsPairInfo? = null,
+    ) : PairResult()
+    object UnsupportedVersion : PairResult()
+    object Invalid : PairResult()
+}
+
+/**
+ * Parser for the companion pairing QR / OS deep link. Contract:
+ * docs/companion-pairing-qr.md (repo root).
+ *
+ *   archipelago://pair?v=1&url=<origin>&name=…[&tok=…][&pw=…][&fnpub=…&fip=…&fhost=…&fudp=…&ftcp=…]
+ *
+ * - `url` is a full origin including scheme (http for LAN/mDNS nodes, https
+ *   for the public demo); trailing slashes are normalized away.
+ * - `tok` is a device token minted by the node; it goes through the password
+ *   field on purpose — the whole password auto-login path (WebSocket auth +
+ *   WebView form injection) then works unchanged, and the backend accepts
+ *   device tokens wherever it accepts the password. `pw` (demo only) wins if
+ *   both are ever present.
+ * - `fnpub`/`fip`/`fhost`/`fudp`/`ftcp` describe the node's FIPS mesh; their
+ *   absence just means LAN-only pairing (older node, or FIPS not provisioned).
+ * - Unknown extra query params are tolerated (forward compat under v=1).
+ */
+object ServerQrParser {
+    private const val SUPPORTED_MAJOR = 1
+
+    fun parse(raw: String): PairResult {
+        val uri = try {
+            Uri.parse(raw.trim())
+        } catch (_: Exception) {
+            return PairResult.Invalid
+        }
+        if (!"archipelago".equals(uri.scheme, ignoreCase = true)) return PairResult.Invalid
+        if (uri.isOpaque || !"pair".equals(uri.host, ignoreCase = true)) return PairResult.Invalid
+
+        val major = uri.getQueryParameter("v")
+            ?.trim()
+            ?.takeWhile { it.isDigit() }
+            ?.toIntOrNull()
+            ?: return PairResult.Invalid
+        if (major != SUPPORTED_MAJOR) return PairResult.UnsupportedVersion
+
+        val serverUrl = uri.getQueryParameter("url")?.trim()?.trimEnd('/')
+        if (serverUrl.isNullOrBlank()) return PairResult.Invalid
+        val server = Uri.parse(serverUrl)
+        val scheme = server.scheme?.lowercase()
+        if (scheme != "http" && scheme != "https") return PairResult.Invalid
+        val host = server.host
+        if (host.isNullOrBlank()) return PairResult.Invalid
+
+        val fips = parseFips(uri)
+        val credential = uri.getQueryParameter("pw")?.takeIf { it.isNotBlank() }
+            ?: uri.getQueryParameter("tok")
+            ?: ""
+
+        return PairResult.Success(
+            server = ServerEntry(
+                address = host,
+                useHttps = scheme == "https",
+                port = if (server.port != -1) server.port.toString() else "",
+                password = credential,
+                name = uri.getQueryParameter("name") ?: "",
+                meshIp = fips?.ula ?: "",
+                // npub is the durable identity — saved-server upserts match on
+                // it, so re-scanning after a LAN renumber updates in place.
+                npub = fips?.npub ?: "",
+            ),
+            fips = fips,
+        )
+    }
+
+    private fun parseFips(uri: Uri): FipsPairInfo? {
+        val npub = uri.getQueryParameter("fnpub")?.trim()
+        val host = uri.getQueryParameter("fhost")?.trim()
+        if (npub.isNullOrBlank() || host.isNullOrBlank()) return null
+        return FipsPairInfo(
+            npub = npub,
+            ula = uri.getQueryParameter("fip")?.trim().orEmpty(),
+            host = host,
+            udpPort = uri.getQueryParameter("fudp")?.toIntOrNull() ?: 2121,
+            tcpPort = uri.getQueryParameter("ftcp")?.toIntOrNull() ?: 8443,
+            anchors = parseAnchors(uri.getQueryParameter("fanchors")),
+        )
+    }
+
+    /** `fanchors` = comma-joined `npub@host:port/transport`; bad items skipped. */
+    private fun parseAnchors(raw: String?): List<AnchorPeer> {
+        if (raw.isNullOrBlank()) return emptyList()
+        return raw.split(",").mapNotNull { item ->
+            val at = item.indexOf('@')
+            val slash = item.lastIndexOf('/')
+            if (at <= 0 || slash <= at) return@mapNotNull null
+            val npub = item.substring(0, at).trim()
+            val addr = item.substring(at + 1, slash).trim()
+            val transport = item.substring(slash + 1).trim().lowercase()
+            if (npub.isBlank() || !addr.contains(":")) return@mapNotNull null
+            if (transport != "udp" && transport != "tcp") return@mapNotNull null
+            AnchorPeer(npub = npub, addr = addr, transport = transport)
+        }
+    }
+}

Android/app/src/main/java/com/archipelago/app/fips/ArchyVpnService.kt

@@ -0,0 +1,228 @@
+package com.archipelago.app.fips
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.Intent
+import android.net.VpnService
+import android.os.Build
+import android.util.Log
+import com.archipelago.app.MainActivity
+import com.archipelago.app.R
+import com.archipelago.app.data.ServerPreferences
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+
+/**
+ * VpnService hosting the embedded FIPS mesh node.
+ *
+ * Split tunnel: only fd00::/8 (the FIPS ULA space) routes into the TUN, so
+ * normal phone traffic is untouched — this is mesh reachability, not a
+ * default-route VPN. The established fd is detached and handed to the Rust
+ * node (Node::start_with_tun_fd); the node owns it until stop.
+ */
+class ArchyVpnService : VpnService() {
+
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+    private var warmerJob: Job? = null
+
+    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+        if (intent?.action == ACTION_STOP) {
+            shutdown()
+            return START_NOT_STICKY
+        }
+        startForeground(NOTIFICATION_ID, buildNotification())
+        scope.launch { startMesh() }
+        return START_STICKY
+    }
+
+    private suspend fun startMesh() {
+        if (!FipsNative.available) {
+            shutdown()
+            return
+        }
+        val prefs = FipsPreferences(this)
+        val identity = FipsManager.ensureIdentity(prefs)
+        val peersJson = prefs.combinedPeersJson()
+        if (identity == null || peersJson == "[]") {
+            Log.w(TAG, "mesh not configured — stopping")
+            shutdown()
+            return
+        }
+        // Party mode: fixed inbound UDP bind so a nearby phone can dial us
+        // directly over a shared LAN/hotspot (no internet required).
+        val listenPort = if (prefs.partyListen()) PartyQr.PARTY_UDP_PORT else 0
+
+        // A fresh app open re-triggers the service. Tearing a HEALTHY mesh
+        // down to rebuild it costs ~8s of anchor+session bring-up on every
+        // launch (observed live: stop 00:34:38 → session back 00:34:49) and
+        // is what made "freshly loading the app" slow. Keep a running node;
+        // restart only when it's dead or a pairing changed the peer set.
+        if (FipsNative.isRunning() && !FipsManager.peersDirty) {
+            Log.i(TAG, "mesh already running — keeping warm sessions")
+            startSessionWarmer()
+            return
+        }
+        FipsManager.peersDirty = false
+        // Re-establishing while running would strand the old fd; restart clean.
+        if (FipsNative.isRunning()) FipsNative.stop()
+
+        val pfd = try {
+            Builder()
+                .setSession("Archipelago Mesh")
+                .setMtu(1280)
+                .addAddress(identity.address, 128)
+                .addRoute("fd00::", 8)
+                // The TUN is IPv6-only. Android blocks every address family
+                // the VPN has no address for — without this, bringing the
+                // mesh up cut ALL of the phone's IPv4 internet.
+                .allowFamily(android.system.OsConstants.AF_INET)
+                // And let apps that bind their own network skip the TUN
+                // entirely — this is mesh reachability, not a privacy VPN.
+                .allowBypass()
+                .apply {
+                    // Android 10+ treats VPN networks as METERED by default,
+                    // which flips the whole phone into data-saver behaviour
+                    // (background sync off, "metered" warnings) while the
+                    // mesh is up. It inherits the underlying network's real
+                    // metered state instead.
+                    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) setMetered(false)
+                }
+                .establish()
+        } catch (e: Exception) {
+            Log.e(TAG, "VPN establish failed", e)
+            null
+        }
+        if (pfd == null) {
+            shutdown()
+            return
+        }
+
+        val fd = pfd.detachFd()
+        val result = FipsNative.start(identity.secret, peersJson, fd, listenPort)
+        Log.i(TAG, "mesh start: $result (listen=$listenPort)")
+        if (result.contains("\"error\"")) {
+            shutdown()
+        } else {
+            startSessionWarmer()
+            // Phone-to-phone chat/beam + the phone's own mesh-served page.
+            FlareServer.start(this, identity.address, identity.npub, prefs.partyName())
+            // Mutual pairing: when a phone that scanned OUR QR announces
+            // itself, store it as a party peer and re-run the mesh config so
+            // this side gets the peer + chat entry without scanning back.
+            FlareServer.onHello = { peer ->
+                scope.launch {
+                    prefs.upsertPartyPeer(peer)
+                    FipsManager.requestMeshRestart(this@ArchyVpnService)
+                }
+            }
+        }
+    }
+
+    /**
+     * Pre-warm + keep-warm mesh sessions to every known node ULA.
+     *
+     * Discovery + first session through the public tree can take 15s+
+     * (HANDOFF-2026-07-23 node diagnosis) — paying that cost here, the
+     * moment the tunnel is up, means the connect probe and WebView hit an
+     * established session instead of timing out on a cold one. The periodic
+     * touch afterwards keeps the session from idling out. Failed connects
+     * are expected and cheap; the attempt itself is what drives discovery.
+     */
+    private fun startSessionWarmer() {
+        warmerJob?.cancel()
+        warmerJob = scope.launch {
+            val prefs = ServerPreferences(this@ArchyVpnService)
+            val fipsPrefs = FipsPreferences(this@ArchyVpnService)
+            var round = 0
+            while (isActive && FipsNative.isRunning()) {
+                val targets = try {
+                    prefs.savedServers.first()
+                        .mapNotNull { it.meshIp.ifBlank { null } }
+                        .map { it to 80 } +
+                        // Party phones answer on the flare port, not :80.
+                        fipsPrefs.partyPeers().map { it.ula to PartyQr.FLARE_PORT }
+                } catch (_: Exception) {
+                    emptyList()
+                }.distinct()
+                for ((ula, port) in targets) {
+                    try {
+                        java.net.Socket().use { s ->
+                            s.connect(
+                                java.net.InetSocketAddress(java.net.InetAddress.getByName(ula), port),
+                                20_000,
+                            )
+                        }
+                    } catch (_: Exception) {
+                        // Cold path / node away — the connect attempt still
+                        // drove session establishment; try again next round.
+                    }
+                }
+                round++
+                // Aggressive for the first ~minute (session bring-up), then a
+                // slow keep-warm tick that costs nearly nothing.
+                delay(if (round < 12) 5_000 else 60_000)
+            }
+        }
+    }
+
+    private fun shutdown() {
+        warmerJob?.cancel()
+        FlareServer.stop()
+        FipsNative.stop()
+        stopForeground(STOP_FOREGROUND_REMOVE)
+        stopSelf()
+    }
+
+    override fun onDestroy() {
+        FipsNative.stop()
+        scope.cancel()
+        super.onDestroy()
+    }
+
+    override fun onRevoke() {
+        // User pulled VPN permission from system settings.
+        shutdown()
+    }
+
+    private fun buildNotification(): Notification {
+        val manager = getSystemService(NotificationManager::class.java)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            manager.createNotificationChannel(
+                NotificationChannel(
+                    CHANNEL_ID,
+                    "Mesh connection",
+                    NotificationManager.IMPORTANCE_MIN,
+                ).apply { description = "Keeps the node reachable from anywhere" }
+            )
+        }
+        val tapIntent = PendingIntent.getActivity(
+            this,
+            0,
+            Intent(this, MainActivity::class.java),
+            PendingIntent.FLAG_IMMUTABLE,
+        )
+        return Notification.Builder(this, CHANNEL_ID)
+            .setContentTitle("Connected to your Archipelago")
+            .setContentText("Secure mesh link active")
+            .setSmallIcon(R.mipmap.ic_launcher)
+            .setContentIntent(tapIntent)
+            .setOngoing(true)
+            .build()
+    }
+
+    companion object {
+        const val ACTION_STOP = "com.archipelago.app.fips.STOP"
+        private const val CHANNEL_ID = "archy_mesh"
+        private const val NOTIFICATION_ID = 4841
+        private const val TAG = "ArchyVpnService"
+    }
+}

Android/app/src/main/java/com/archipelago/app/fips/FipsManager.kt

@@ -0,0 +1,95 @@
+package com.archipelago.app.fips
+
+import android.content.Context
+import android.content.Intent
+import android.net.VpnService
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+
+/**
+ * Glue between pairing and the mesh: persists the node peer from a scanned
+ * QR and asks the UI to bring the tunnel up. There is deliberately no
+ * settings surface — scanning a node's QR is the entire configuration.
+ *
+ * The one unavoidable interaction is Android's VPN consent dialog
+ * (VpnService.prepare), which only an Activity can launch; [consentNeeded]
+ * signals AppNavHost to run it, once, on first pairing.
+ */
+object FipsManager {
+
+    /** Set when a pairing registered mesh info and the VPN needs starting. */
+    private val _consentNeeded = MutableStateFlow(false)
+    val consentNeeded: StateFlow<Boolean> = _consentNeeded
+
+    /** True after a pairing changed the peer set while the node was running —
+     *  tells the service a restart is genuinely needed (the ONLY case; a
+     *  routine app open must keep the warm mesh, not rebuild it). */
+    @Volatile
+    var peersDirty: Boolean = false
+
+    fun consentHandled() {
+        _consentNeeded.value = false
+    }
+
+    /**
+     * Persist mesh info from a pairing scan and request tunnel start.
+     * No-op on devices without the native lib (non-arm64).
+     */
+    suspend fun registerNode(context: Context, info: FipsPairInfo?, alias: String) {
+        if (info == null || !FipsNative.available) return
+        val prefs = FipsPreferences(context)
+        ensureIdentity(prefs)
+        prefs.upsertNodePeer(info, alias)
+        peersDirty = true
+        _consentNeeded.value = true
+    }
+
+    /** Generate-once mesh identity. Returns null only if the RNG/native fails. */
+    suspend fun ensureIdentity(prefs: FipsPreferences): FipsNative.Identity? {
+        prefs.identity()?.let { return it }
+        val generated = FipsNative.parseIdentity(FipsNative.generateIdentity()) ?: return null
+        prefs.saveIdentity(generated)
+        return generated
+    }
+
+    /**
+     * Start the mesh service if this device is paired and the user has already
+     * consented to the VPN (prepare() == null). Called on app start so the
+     * tunnel comes back without any interaction; first-time consent goes
+     * through AppNavHost instead.
+     */
+    suspend fun autoStartIfReady(context: Context) {
+        if (!FipsNative.available) return
+        val prefs = FipsPreferences(context)
+        if (prefs.identity() == null || !prefs.hasPeers()) return
+        if (VpnService.prepare(context) != null) return // consent missing — don't prompt here
+        startService(context)
+    }
+
+    fun startService(context: Context) {
+        val intent = Intent(context, ArchyVpnService::class.java)
+        context.startForegroundService(intent)
+    }
+
+    /**
+     * Re-run the mesh with current prefs (party listen toggled, peer added).
+     * Marks the peer set dirty so startMesh genuinely restarts the node —
+     * otherwise the keep-warm fast path would skip the new config.
+     * First-timers go through the consent flow.
+     */
+    fun requestMeshRestart(context: Context) {
+        if (!FipsNative.available) return
+        peersDirty = true
+        if (VpnService.prepare(context) == null) {
+            startService(context)
+        } else {
+            _consentNeeded.value = true
+        }
+    }
+
+    fun stopService(context: Context) {
+        val intent = Intent(context, ArchyVpnService::class.java)
+            .setAction(ArchyVpnService.ACTION_STOP)
+        context.startService(intent)
+    }
+}

Android/app/src/main/java/com/archipelago/app/fips/FipsNative.kt

@@ -0,0 +1,49 @@
+package com.archipelago.app.fips
+
+import org.json.JSONObject
+
+/**
+ * JNI binding to the embedded FIPS mesh node (Android/rust/archy-fips-core,
+ * built into libarchy_fips_core.so by the buildRustArm64 gradle task).
+ *
+ * All calls return JSON strings; failures come back as {"error": "…"} rather
+ * than exceptions. [available] is false on ABIs the .so isn't built for
+ * (anything but arm64) — every caller must gate on it so the app still runs
+ * as a plain companion there.
+ */
+object FipsNative {
+    val available: Boolean = try {
+        System.loadLibrary("archy_fips_core")
+        true
+    } catch (_: Throwable) {
+        false
+    }
+
+    external fun generateIdentity(): String
+    external fun deriveIdentity(secret: String): String
+
+    /**
+     * [listenPort] 0 = outbound-only (default posture). Non-zero binds UDP on
+     * that port so a nearby phone can dial us directly (party mode); the node
+     * stays leaf-only either way.
+     */
+    external fun start(secret: String, peersJson: String, tunFd: Int, listenPort: Int): String
+    external fun stop()
+    external fun isRunning(): Boolean
+    external fun statusJson(): String
+
+    data class Identity(val secret: String, val npub: String, val address: String)
+
+    /** Parse an identity JSON reply; null on {"error": …} or malformed. */
+    fun parseIdentity(json: String): Identity? = try {
+        val obj = JSONObject(json)
+        if (obj.has("error")) null
+        else Identity(
+            secret = obj.getString("secret"),
+            npub = obj.getString("npub"),
+            address = obj.getString("address"),
+        )
+    } catch (_: Exception) {
+        null
+    }
+}

Android/app/src/main/java/com/archipelago/app/fips/FipsPairInfo.kt

@@ -0,0 +1,29 @@
+package com.archipelago.app.fips
+
+/**
+ * Node mesh parameters carried by the pairing QR (fnpub/fip/fhost/fudp/ftcp —
+ * docs/companion-pairing-qr.md). The phone's embedded FIPS node dials
+ * host:udpPort / host:tcpPort claiming nothing; the mesh accepts inbound peers
+ * without registration, so possession of these params is all pairing takes.
+ */
+data class FipsPairInfo(
+    val npub: String,
+    /** Node's fips0 ULA — where its UI stays reachable once meshed. May be empty. */
+    val ula: String,
+    val host: String,
+    val udpPort: Int,
+    val tcpPort: Int,
+    /**
+     * Public rendezvous anchors (the node's seed-anchor list). The phone
+     * peers with these too, so it can route to the node via the mesh when
+     * the node's LAN endpoint isn't directly dialable.
+     */
+    val anchors: List<AnchorPeer> = emptyList(),
+)
+
+/** One rendezvous anchor from the QR's `fanchors` param (npub@addr/transport). */
+data class AnchorPeer(
+    val npub: String,
+    val addr: String,
+    val transport: String,
+)

Android/app/src/main/java/com/archipelago/app/fips/FipsPreferences.kt

@@ -0,0 +1,260 @@
+package com.archipelago.app.fips
+
+import android.content.Context
+import androidx.datastore.core.DataStore
+import androidx.datastore.preferences.core.Preferences
+import androidx.datastore.preferences.core.booleanPreferencesKey
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.stringPreferencesKey
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.flow.map
+import org.json.JSONArray
+import org.json.JSONObject
+import androidx.datastore.preferences.preferencesDataStore
+
+private val Context.fipsDataStore: DataStore<Preferences> by preferencesDataStore(name = "fips_prefs")
+
+// Archipelago-operated public anchor (vps2). Baked in so EVERY pairing yields
+// both paths — direct LAN p2p to the node AND a public rendezvous for
+// away-from-home — even when the scanned node is old enough that its QR
+// carries no fanchors. Keep in lockstep with
+// core/archipelago/src/fips/anchors.rs (ARCHY_ANCHOR_*).
+internal const val ARCHY_ANCHOR_NPUB =
+    "npub1dptaktwxv0mm245g2lqjykwm5ll0jpc6m3r4242ydfa9z7qe6urs3jvrak"
+internal const val ARCHY_ANCHOR_ADDR = "146.59.87.168:8444"
+internal const val ARCHY_ANCHOR_TRANSPORT = "tcp"
+
+/**
+ * Mesh identity + known node peers. Follows the same plaintext-DataStore
+ * storage model as ServerPreferences (the server password lives there the
+ * same way); the mesh secret only grants mesh membership, not node login.
+ */
+class FipsPreferences(private val context: Context) {
+
+    private val secretKey = stringPreferencesKey("fips_secret")
+    private val npubKey = stringPreferencesKey("fips_npub")
+    private val addressKey = stringPreferencesKey("fips_address")
+    /** JSON array of node peers in fips PeerConfig shape (see NodePeer). */
+    private val peersKey = stringPreferencesKey("fips_node_peers")
+    /** JSON array of phone party peers (PartyPeer shape, NOT PeerConfig). */
+    private val partyPeersKey = stringPreferencesKey("fips_party_peers")
+    /** Party mode: accept a direct inbound mesh link (UDP 2121). */
+    private val partyListenKey = booleanPreferencesKey("fips_party_listen")
+    /** Name shown in this phone's party QR and outgoing flares. */
+    private val partyNameKey = stringPreferencesKey("fips_party_name")
+
+    suspend fun identity(): FipsNative.Identity? {
+        val prefs = context.fipsDataStore.data.first()
+        val secret = prefs[secretKey] ?: return null
+        return FipsNative.Identity(
+            secret = secret,
+            npub = prefs[npubKey] ?: "",
+            address = prefs[addressKey] ?: "",
+        )
+    }
+
+    suspend fun saveIdentity(identity: FipsNative.Identity) {
+        context.fipsDataStore.edit { prefs ->
+            prefs[secretKey] = identity.secret
+            prefs[npubKey] = identity.npub
+            prefs[addressKey] = identity.address
+        }
+    }
+
+    suspend fun peersJson(): String {
+        val prefs = context.fipsDataStore.data.first()
+        return prefs[peersKey] ?: "[]"
+    }
+
+    suspend fun hasPeers(): Boolean = JSONArray(peersJson()).length() > 0
+
+    // ── Mesh Party (phone↔phone) ────────────────────────────────────────────
+
+    suspend fun partyListen(): Boolean =
+        context.fipsDataStore.data.first()[partyListenKey] ?: false
+
+    val partyListenFlow: Flow<Boolean>
+        get() = context.fipsDataStore.data.map { it[partyListenKey] ?: false }
+
+    suspend fun setPartyListen(enabled: Boolean) {
+        context.fipsDataStore.edit { it[partyListenKey] = enabled }
+    }
+
+    suspend fun partyName(): String =
+        context.fipsDataStore.data.first()[partyNameKey]
+            ?: android.os.Build.MODEL.orEmpty().ifBlank { "Phone" }
+
+    suspend fun setPartyName(name: String) {
+        context.fipsDataStore.edit { it[partyNameKey] = name.trim() }
+    }
+
+    val partyPeersFlow: Flow<List<PartyPeer>>
+        get() = context.fipsDataStore.data.map { parsePartyPeers(it[partyPeersKey] ?: "[]") }
+
+    suspend fun partyPeers(): List<PartyPeer> =
+        parsePartyPeers(context.fipsDataStore.data.first()[partyPeersKey] ?: "[]")
+
+    /** Matched by npub, so re-scanning updates the direct-dial address in place. */
+    suspend fun upsertPartyPeer(peer: PartyPeer) {
+        context.fipsDataStore.edit { prefs ->
+            val kept = parsePartyPeers(prefs[partyPeersKey] ?: "[]").filter { it.npub != peer.npub }
+            prefs[partyPeersKey] = toJson(kept + peer)
+        }
+    }
+
+    suspend fun removePartyPeer(npub: String) {
+        context.fipsDataStore.edit { prefs ->
+            val kept = parsePartyPeers(prefs[partyPeersKey] ?: "[]").filter { it.npub != npub }
+            prefs[partyPeersKey] = toJson(kept)
+        }
+    }
+
+    /**
+     * Node peers + direct-dial party peers, in the fips PeerConfig JSON the
+     * Rust node deserializes. Party peers get the best priority: on a shared
+     * LAN/hotspot the direct link beats every anchor path, and while off-LAN
+     * the failed dial is cheap (auto-reconnect keeps retrying, which is
+     * exactly what makes the link snap up the moment both phones share WiFi).
+     * Party peers without an underlay address are mesh-routed and need no
+     * entry here at all.
+     */
+    suspend fun combinedPeersJson(): String {
+        val merged = JSONArray(peersJson())
+        val party = partyPeers()
+        for (peer in party) {
+            if (peer.ip.isBlank() || peer.port <= 0) continue
+            merged.put(JSONObject().apply {
+                put("npub", peer.npub)
+                put("alias", peer.name.ifBlank { "Party phone" })
+                put("addresses", JSONArray().put(JSONObject().apply {
+                    put("transport", "udp")
+                    put("addr", "${peer.ip}:${peer.port}")
+                    put("priority", 5)
+                }))
+            })
+        }
+        // A party-only phone (never paired with a node) still needs a public
+        // rendezvous to reach its peers ACROSS the internet — without it, two
+        // bare phones would be hotspot/LAN-only. Node pairing normally bakes
+        // this anchor in; do the same when there are party peers.
+        if (party.isNotEmpty() &&
+            (0 until merged.length()).none {
+                merged.optJSONObject(it)?.optString("npub") == ARCHY_ANCHOR_NPUB
+            }
+        ) {
+            merged.put(JSONObject().apply {
+                put("npub", ARCHY_ANCHOR_NPUB)
+                put("alias", "Archipelago anchor")
+                put("addresses", JSONArray().put(JSONObject().apply {
+                    put("transport", ARCHY_ANCHOR_TRANSPORT)
+                    put("addr", ARCHY_ANCHOR_ADDR)
+                    put("priority", 40)
+                }))
+            })
+        }
+        return merged.toString()
+    }
+
+    private fun parsePartyPeers(json: String): List<PartyPeer> = try {
+        val arr = JSONArray(json)
+        (0 until arr.length()).mapNotNull { i ->
+            val o = arr.optJSONObject(i) ?: return@mapNotNull null
+            val npub = o.optString("npub")
+            val ula = o.optString("ula")
+            if (npub.isBlank() || ula.isBlank()) return@mapNotNull null
+            PartyPeer(
+                npub = npub,
+                ula = ula,
+                name = o.optString("name").ifBlank { "Phone" },
+                ip = o.optString("ip"),
+                port = o.optInt("port"),
+            )
+        }
+    } catch (_: Exception) {
+        emptyList()
+    }
+
+    private fun toJson(peers: List<PartyPeer>): String {
+        val arr = JSONArray()
+        for (p in peers) {
+            arr.put(JSONObject().apply {
+                put("npub", p.npub)
+                put("ula", p.ula)
+                put("name", p.name)
+                put("ip", p.ip)
+                put("port", p.port)
+            })
+        }
+        return arr.toString()
+    }
+
+    /**
+     * Add or update the node peer plus its rendezvous anchors (each matched
+     * by npub, so re-pairing updates addresses instead of duplicating).
+     * Stored directly in the fips PeerConfig JSON shape the Rust side
+     * deserializes. The node's direct addresses get the best priorities;
+     * anchors trail so the mesh prefers the direct path when it works.
+     */
+    suspend fun upsertNodePeer(info: FipsPairInfo, alias: String) {
+        val incoming = mutableListOf<JSONObject>()
+        incoming += JSONObject().apply {
+            put("npub", info.npub)
+            put("alias", alias.ifBlank { "Archipelago" })
+            val addresses = JSONArray()
+            if (info.udpPort > 0) {
+                addresses.put(JSONObject().apply {
+                    put("transport", "udp")
+                    put("addr", "${info.host}:${info.udpPort}")
+                    put("priority", 10)
+                })
+            }
+            if (info.tcpPort > 0) {
+                addresses.put(JSONObject().apply {
+                    put("transport", "tcp")
+                    put("addr", "${info.host}:${info.tcpPort}")
+                    put("priority", 20)
+                })
+            }
+            put("addresses", addresses)
+        }
+        for (anchor in info.anchors) {
+            if (anchor.npub == info.npub) continue
+            incoming += JSONObject().apply {
+                put("npub", anchor.npub)
+                put("alias", "Mesh anchor")
+                put("addresses", JSONArray().put(JSONObject().apply {
+                    put("transport", anchor.transport)
+                    put("addr", anchor.addr)
+                    put("priority", 30)
+                }))
+            }
+        }
+        // Guarantee the public anchor: without it, a QR from an older node
+        // leaves the phone LAN-only and pairing/connecting dies off-LAN.
+        if (info.npub != ARCHY_ANCHOR_NPUB &&
+            incoming.none { it.optString("npub") == ARCHY_ANCHOR_NPUB }
+        ) {
+            incoming += JSONObject().apply {
+                put("npub", ARCHY_ANCHOR_NPUB)
+                put("alias", "Archipelago anchor")
+                put("addresses", JSONArray().put(JSONObject().apply {
+                    put("transport", ARCHY_ANCHOR_TRANSPORT)
+                    put("addr", ARCHY_ANCHOR_ADDR)
+                    put("priority", 40)
+                }))
+            }
+        }
+        val incomingNpubs = incoming.map { it.optString("npub") }.toSet()
+        context.fipsDataStore.edit { prefs ->
+            val current = JSONArray(prefs[peersKey] ?: "[]")
+            val merged = JSONArray()
+            for (i in 0 until current.length()) {
+                val existing = current.optJSONObject(i) ?: continue
+                if (existing.optString("npub") !in incomingNpubs) merged.put(existing)
+            }
+            incoming.forEach { merged.put(it) }
+            prefs[peersKey] = merged.toString()
+        }
+    }
+}

Android/app/src/main/java/com/archipelago/app/fips/FlareServer.kt

@@ -0,0 +1,398 @@
+package com.archipelago.app.fips
+
+import android.content.Context
+import android.util.Log
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import okhttp3.MediaType.Companion.toMediaType
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.RequestBody.Companion.toRequestBody
+import org.json.JSONObject
+import java.io.BufferedInputStream
+import java.io.File
+import java.io.InputStream
+import java.net.InetAddress
+import java.net.InetSocketAddress
+import java.net.ServerSocket
+import java.net.Socket
+import java.util.UUID
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+
+/** One chat/photo message in a party conversation, keyed by the peer's npub. */
+data class FlareMessage(
+    val id: String,
+    val peerNpub: String,
+    val fromMe: Boolean,
+    val name: String,
+    val text: String = "",
+    val photoPath: String = "",
+    val ts: Long,
+    val status: Status = Status.RECEIVED,
+) {
+    enum class Status { SENDING, SENT, FAILED, RECEIVED }
+}
+
+/** In-memory conversation store (demo scope — nothing persists across restarts). */
+object FlareStore {
+    private val _messages = MutableStateFlow<List<FlareMessage>>(emptyList())
+    val messages: StateFlow<List<FlareMessage>> = _messages
+
+    fun add(message: FlareMessage) {
+        _messages.value = _messages.value + message
+    }
+
+    fun setStatus(id: String, status: FlareMessage.Status) {
+        _messages.value = _messages.value.map { if (it.id == id) it.copy(status = status) else it }
+    }
+}
+
+/**
+ * Minimal HTTP listener bound ONLY on this phone's mesh ULA — plain HTTP is
+ * fine there because FIPS is the encryption + peer-identity layer (same
+ * stance as the node's ULA-only peer listener). This is what makes the phone
+ * a *server* on the mesh: another phone (or `curl -6` from any mesh node)
+ * reaches it by npub-derived address with no port forwarding, DNS, or CA.
+ *
+ * FIPS authenticates the node, not the request (project doctrine), so inputs
+ * are still validated at this boundary: size caps, JSON shape, no
+ * client-controlled paths.
+ */
+object FlareServer {
+    private const val TAG = "FlareServer"
+    private const val MAX_PHOTO_BYTES = 8 * 1024 * 1024
+    private const val MAX_TEXT_CHARS = 4_000
+    private const val MAX_HEADER_BYTES = 16 * 1024
+
+    private var socket: ServerSocket? = null
+    private var pool: ExecutorService? = null
+    @Volatile private var identityName = "Phone"
+    @Volatile private var identityNpub = ""
+    @Volatile private var photoDir: File? = null
+
+    /** Invoked when a peer announces itself (POST /hello) — pairing used to
+     *  be one-way: only the SCANNING phone learned the other side, so the
+     *  scanned phone had no peer, no chat entry, no way in. The VPN service
+     *  wires this to upsert the peer + restart the mesh config. */
+    @Volatile var onHello: ((PartyPeer) -> Unit)? = null
+
+    @Synchronized
+    fun start(context: Context, ula: String, myNpub: String, myName: String) {
+        stop()
+        identityNpub = myNpub
+        identityName = myName
+        photoDir = File(context.cacheDir, "flare").apply { mkdirs() }
+        val pool = Executors.newCachedThreadPool().also { this.pool = it }
+        pool.execute {
+            try {
+                val server = ServerSocket().apply {
+                    reuseAddress = true
+                    bind(InetSocketAddress(InetAddress.getByName(ula), PartyQr.FLARE_PORT))
+                }
+                socket = server
+                Log.i(TAG, "flare listening on [$ula]:${PartyQr.FLARE_PORT}")
+                while (!server.isClosed) {
+                    val client = try {
+                        server.accept()
+                    } catch (_: Exception) {
+                        break
+                    }
+                    pool.execute { handle(client) }
+                }
+            } catch (e: Exception) {
+                Log.e(TAG, "flare server died: $e")
+            }
+        }
+    }
+
+    @Synchronized
+    fun stop() {
+        try {
+            socket?.close()
+        } catch (_: Exception) {
+        }
+        socket = null
+        pool?.shutdownNow()
+        pool = null
+    }
+
+    private fun handle(client: Socket) {
+        client.use { sock ->
+            sock.soTimeout = 30_000
+            try {
+                val input = BufferedInputStream(sock.getInputStream())
+                val requestLine = readLine(input) ?: return
+                val parts = requestLine.trim().split(" ")
+                if (parts.size < 2) return respond(sock, 400, json("bad_request"))
+                val (method, path) = parts[0] to parts[1]
+
+                var contentLength = 0
+                var from = ""
+                var fromName = ""
+                var headerBytes = requestLine.length
+                while (true) {
+                    val line = readLine(input) ?: return
+                    if (line.isEmpty()) break
+                    headerBytes += line.length
+                    if (headerBytes > MAX_HEADER_BYTES) return respond(sock, 431, json("headers_too_large"))
+                    val idx = line.indexOf(':')
+                    if (idx <= 0) continue
+                    val key = line.substring(0, idx).trim().lowercase()
+                    val value = line.substring(idx + 1).trim()
+                    when (key) {
+                        "content-length" -> contentLength = value.toIntOrNull() ?: 0
+                        "x-from" -> from = value.take(80)
+                        "x-name" -> fromName = value.take(80)
+                    }
+                }
+
+                when {
+                    method == "GET" && (path == "/" || path.startsWith("/?")) ->
+                        respondHtml(sock, profilePage())
+                    method == "POST" && path == "/hello" -> {
+                        if (contentLength !in 1..MAX_HEADER_BYTES) return respond(sock, 413, json("too_large"))
+                        val body = readExactly(input, contentLength) ?: return
+                        receiveHello(String(body, Charsets.UTF_8))
+                        respond(sock, 200, """{"ok":true}""")
+                    }
+                    method == "POST" && path == "/flare" -> {
+                        if (contentLength !in 1..MAX_HEADER_BYTES) return respond(sock, 413, json("too_large"))
+                        val body = readExactly(input, contentLength) ?: return
+                        receiveFlare(String(body, Charsets.UTF_8))
+                        respond(sock, 200, """{"ok":true}""")
+                    }
+                    method == "POST" && path == "/photo" -> {
+                        if (contentLength !in 1..MAX_PHOTO_BYTES) return respond(sock, 413, json("too_large"))
+                        if (!from.startsWith("npub1")) return respond(sock, 400, json("bad_request"))
+                        val body = readExactly(input, contentLength) ?: return
+                        receivePhoto(from, fromName, body)
+                        respond(sock, 200, """{"ok":true}""")
+                    }
+                    else -> respond(sock, 404, json("not_found"))
+                }
+            } catch (e: Exception) {
+                Log.w(TAG, "request failed: $e")
+            }
+        }
+    }
+
+    /** A peer that scanned OUR QR announces itself — mutual pairing. */
+    private fun receiveHello(body: String) {
+        val o = try {
+            JSONObject(body)
+        } catch (_: Exception) {
+            return
+        }
+        val from = o.optString("from")
+        val ula = o.optString("ula")
+        if (!from.startsWith("npub1") || !ula.startsWith("fd")) return
+        if (from == identityNpub) return
+        val peer = PartyPeer(
+            npub = from.take(80),
+            ula = ula.take(64),
+            name = o.optString("name").take(24).ifBlank { "Phone" },
+            ip = o.optString("ip").take(40),
+            port = o.optInt("port", 0),
+        )
+        onHello?.invoke(peer)
+        // Seed the conversation so the chat has a visible entry on this side.
+        FlareStore.add(
+            FlareMessage(
+                id = UUID.randomUUID().toString(),
+                peerNpub = peer.npub,
+                fromMe = false,
+                name = peer.name,
+                text = "👋 ${peer.name} joined the party",
+                ts = System.currentTimeMillis(),
+            )
+        )
+    }
+
+    private fun receiveFlare(body: String) {
+        val o = try {
+            JSONObject(body)
+        } catch (_: Exception) {
+            return
+        }
+        val from = o.optString("from")
+        if (!from.startsWith("npub1")) return
+        val text = o.optString("text").take(MAX_TEXT_CHARS)
+        if (text.isBlank()) return
+        FlareStore.add(
+            FlareMessage(
+                id = UUID.randomUUID().toString(),
+                peerNpub = from,
+                fromMe = false,
+                name = o.optString("name").take(80).ifBlank { "Phone" },
+                text = text,
+                ts = System.currentTimeMillis(),
+            )
+        )
+    }
+
+    private fun receivePhoto(from: String, fromName: String, bytes: ByteArray) {
+        // Server-generated filename — the sender never controls the path.
+        val dir = photoDir ?: return
+        val file = File(dir, "${UUID.randomUUID()}.jpg")
+        file.writeBytes(bytes)
+        FlareStore.add(
+            FlareMessage(
+                id = UUID.randomUUID().toString(),
+                peerNpub = from,
+                fromMe = false,
+                name = fromName.ifBlank { "Phone" },
+                photoPath = file.absolutePath,
+                ts = System.currentTimeMillis(),
+            )
+        )
+    }
+
+    private fun profilePage(): String {
+        val npub = identityNpub
+        val name = identityName
+        return """
+            <!doctype html><html><head><meta charset="utf-8">
+            <meta name="viewport" content="width=device-width,initial-scale=1">
+            <title>$name — on the mesh</title>
+            <style>
+              body{background:#0a0a0a;color:#eee;font-family:monospace;
+                   display:flex;min-height:100vh;align-items:center;justify-content:center;margin:0}
+              .card{border:1px solid rgba(255,255,255,.12);border-radius:20px;padding:32px;
+                    max-width:560px;background:rgba(255,255,255,.04)}
+              h1{color:#f7931a;margin:0 0 8px;font-size:22px}
+              .npub{word-break:break-all;color:#888;font-size:12px;margin:12px 0}
+              p{line-height:1.5}
+            </style></head><body><div class="card">
+            <h1>⚡ $name</h1>
+            <div class="npub">$npub</div>
+            <p>This page is being served <b>by a phone</b>, addressed by its
+            cryptographic identity over the FIPS mesh.</p>
+            <p>No port forwarding. No DNS. No certificate authority. No cloud.
+            The key <i>is</i> the address — and the transport underneath can be
+            5G, WiFi, or a hotspot with no internet at all.</p>
+            </div></body></html>
+        """.trimIndent()
+    }
+
+    // ── tiny HTTP plumbing ──────────────────────────────────────────────────
+
+    /** Read one CRLF-terminated header line as ISO-8859-1; null on EOF. */
+    private fun readLine(input: InputStream): String? {
+        val sb = StringBuilder()
+        while (true) {
+            val b = input.read()
+            if (b == -1) return if (sb.isEmpty()) null else sb.toString()
+            if (b == '\n'.code) return sb.toString().trimEnd('\r')
+            sb.append(b.toChar())
+            if (sb.length > MAX_HEADER_BYTES) return null
+        }
+    }
+
+    private fun readExactly(input: InputStream, length: Int): ByteArray? {
+        val buf = ByteArray(length)
+        var off = 0
+        while (off < length) {
+            val n = input.read(buf, off, length - off)
+            if (n == -1) return null
+            off += n
+        }
+        return buf
+    }
+
+    private fun json(code: String) = """{"error":{"code":"$code","message":"request rejected"}}"""
+
+    private fun respond(sock: Socket, status: Int, body: String) =
+        writeResponse(sock, status, "application/json", body.toByteArray(Charsets.UTF_8))
+
+    private fun respondHtml(sock: Socket, body: String) =
+        writeResponse(sock, 200, "text/html; charset=utf-8", body.toByteArray(Charsets.UTF_8))
+
+    private fun writeResponse(sock: Socket, status: Int, contentType: String, body: ByteArray) {
+        val reason = when (status) {
+            200 -> "OK"; 400 -> "Bad Request"; 404 -> "Not Found"
+            413 -> "Payload Too Large"; 431 -> "Headers Too Large"
+            else -> "Error"
+        }
+        val head = "HTTP/1.1 $status $reason\r\n" +
+            "Content-Type: $contentType\r\n" +
+            "Content-Length: ${body.size}\r\n" +
+            "Connection: close\r\n\r\n"
+        sock.getOutputStream().apply {
+            write(head.toByteArray(Charsets.ISO_8859_1))
+            write(body)
+            flush()
+        }
+    }
+}
+
+/** Outbound flares: plain HTTP to the peer's ULA — FIPS encrypts underneath. */
+object FlareClient {
+    // Connect timeout must outlive cold mesh-session establishment (~15s via
+    // the public tree per HANDOFF-2026-07-23); the attempt itself drives
+    // session setup, same trick as the VPN service's session warmer.
+    private val http = OkHttpClient.Builder()
+        .connectTimeout(25, TimeUnit.SECONDS)
+        .readTimeout(15, TimeUnit.SECONDS)
+        .writeTimeout(60, TimeUnit.SECONDS)
+        .build()
+
+    private fun base(peer: PartyPeer) = "http://[${peer.ula}]:${PartyQr.FLARE_PORT}"
+
+    /** Announce myself to a freshly scanned peer so pairing becomes MUTUAL —
+     *  their phone gets me as a peer + a chat entry without scanning back.
+     *  Blocking — call from Dispatchers.IO. */
+    fun sendHello(
+        peer: PartyPeer,
+        myNpub: String,
+        myName: String,
+        myUla: String,
+        myIp: String?,
+        myPort: Int,
+    ): Boolean = try {
+        val body = JSONObject()
+            .put("from", myNpub)
+            .put("name", myName)
+            .put("ula", myUla)
+            .put("ip", myIp ?: "")
+            .put("port", if (myIp != null) myPort else 0)
+            .toString()
+            .toRequestBody("application/json".toMediaType())
+        http.newCall(
+            Request.Builder().url("${base(peer)}/hello").post(body).build()
+        ).execute().use { it.isSuccessful }
+    } catch (_: Exception) {
+        false
+    }
+
+    /** Blocking — call from Dispatchers.IO. */
+    fun sendText(peer: PartyPeer, myNpub: String, myName: String, text: String): Boolean = try {
+        val body = JSONObject()
+            .put("from", myNpub)
+            .put("name", myName)
+            .put("text", text)
+            .put("ts", System.currentTimeMillis())
+            .toString()
+            .toRequestBody("application/json".toMediaType())
+        http.newCall(
+            Request.Builder().url("${base(peer)}/flare").post(body).build()
+        ).execute().use { it.isSuccessful }
+    } catch (_: Exception) {
+        false
+    }
+
+    /** Blocking — call from Dispatchers.IO. */
+    fun sendPhoto(peer: PartyPeer, myNpub: String, myName: String, jpeg: ByteArray): Boolean = try {
+        http.newCall(
+            Request.Builder()
+                .url("${base(peer)}/photo")
+                .header("X-From", myNpub)
+                .header("X-Name", myName)
+                .post(jpeg.toRequestBody("image/jpeg".toMediaType()))
+                .build()
+        ).execute().use { it.isSuccessful }
+    } catch (_: Exception) {
+        false
+    }
+}

Android/app/src/main/java/com/archipelago/app/fips/PartyQr.kt

@@ -0,0 +1,102 @@
+package com.archipelago.app.fips
+
+import android.net.Uri
+import java.net.Inet4Address
+import java.net.NetworkInterface
+
+/**
+ * Phone↔phone mesh pairing ("Mesh Party") QR contract:
+ *
+ *   archipelago://party?v=1&npub=<npub>&ula=<fd..>&name=<name>[&ip=<v4>&port=<udp>]
+ *
+ * npub + ula alone are enough to chat *through* the mesh (anchors route by
+ * node address, no underlay info needed). ip/port are present only while the
+ * showing phone has its inbound UDP listener up (party mode) — the scanner
+ * then also gets a direct-dial link that works on a shared LAN/hotspot with
+ * no internet at all. Same versioning stance as the node pairing QR
+ * (docs/companion-pairing-qr.md): unknown params tolerated under v=1.
+ */
+data class PartyPeer(
+    val npub: String,
+    val ula: String,
+    val name: String,
+    /** Direct-dial underlay endpoint; empty when the peer wasn't listening. */
+    val ip: String = "",
+    val port: Int = 0,
+)
+
+object PartyQr {
+    const val SCHEME_HOST = "party"
+    private const val SUPPORTED_MAJOR = 1
+
+    /** UDP port a party-mode phone listens on (matches the node's mesh port). */
+    const val PARTY_UDP_PORT = 2121
+
+    /** Application-layer chat/beam port, bound only on the mesh ULA. */
+    const val FLARE_PORT = 5680
+
+    fun build(npub: String, ula: String, name: String, ip: String?, port: Int): String {
+        val b = Uri.Builder()
+            .scheme("archipelago")
+            .authority(SCHEME_HOST)
+            .appendQueryParameter("v", "1")
+            .appendQueryParameter("npub", npub)
+            .appendQueryParameter("ula", ula)
+            .appendQueryParameter("name", name)
+        if (!ip.isNullOrBlank() && port > 0) {
+            b.appendQueryParameter("ip", ip)
+            b.appendQueryParameter("port", port.toString())
+        }
+        return b.build().toString()
+    }
+
+    /** Null when [raw] is not a valid party QR (foreign codes just keep scanning). */
+    fun parse(raw: String): PartyPeer? {
+        val uri = try {
+            Uri.parse(raw.trim())
+        } catch (_: Exception) {
+            return null
+        }
+        if (!"archipelago".equals(uri.scheme, ignoreCase = true)) return null
+        if (uri.isOpaque || !SCHEME_HOST.equals(uri.host, ignoreCase = true)) return null
+        val major = uri.getQueryParameter("v")?.takeWhile { it.isDigit() }?.toIntOrNull() ?: return null
+        if (major != SUPPORTED_MAJOR) return null
+
+        val npub = uri.getQueryParameter("npub")?.trim().orEmpty()
+        val ula = uri.getQueryParameter("ula")?.trim().orEmpty()
+        if (!npub.startsWith("npub1") || !ula.startsWith("fd")) return null
+        return PartyPeer(
+            npub = npub,
+            ula = ula,
+            name = uri.getQueryParameter("name")?.trim().orEmpty().ifBlank { "Phone" },
+            ip = uri.getQueryParameter("ip")?.trim().orEmpty(),
+            port = uri.getQueryParameter("port")?.toIntOrNull() ?: 0,
+        )
+    }
+
+    /**
+     * This phone's private IPv4 on WiFi or its own hotspot, for the QR's
+     * direct-dial hint. Hotspot interfaces (ap/swlan/softap) win over wlan so
+     * the hotspot-host phone advertises the address its guests can reach.
+     */
+    fun localWifiIpv4(): String? {
+        val candidates = mutableListOf<Pair<String, String>>() // ifname → addr
+        try {
+            for (nif in NetworkInterface.getNetworkInterfaces()) {
+                if (!nif.isUp || nif.isLoopback) continue
+                for (addr in nif.inetAddresses) {
+                    if (addr is Inet4Address && addr.isSiteLocalAddress) {
+                        candidates += nif.name to addr.hostAddress.orEmpty()
+                    }
+                }
+            }
+        } catch (_: Exception) {
+            return null
+        }
+        val hotspot = candidates.firstOrNull {
+            it.first.startsWith("ap") || it.first.startsWith("swlan") || it.first.startsWith("softap")
+        }
+        return (hotspot ?: candidates.firstOrNull { it.first.startsWith("wlan") } ?: candidates.firstOrNull())
+            ?.second
+    }
+}

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

@@ -38,7 +38,7 @@ import com.archipelago.app.ui.theme.neoRaised
 @Composable
 fun GamepadLayout(
     onKey: (String) -> Unit,
-    onTwoFingerHold: () -> Unit,
+    onThreeFingerHold: () -> Unit,
     modifier: Modifier = Modifier,
 ) {
     val surface = Neo.surface()
@@ -54,9 +54,9 @@ fun GamepadLayout(
                     do {
                         val ev = awaitPointerEvent()
                         val a = ev.changes.filter { !it.changedToUp() }
-                        if (a.size >= 2 && t == 0L) t = System.currentTimeMillis()
-                        if (a.size >= 2 && !fired && t > 0 && System.currentTimeMillis() - t > 500) { fired = true; onTwoFingerHold() }
-                        if (a.size < 2) t = 0L
+                        if (a.size >= 3 && t == 0L) t = System.currentTimeMillis()
+                        if (a.size >= 3 && !fired && t > 0 && System.currentTimeMillis() - t > 500) { fired = true; onThreeFingerHold() }
+                        if (a.size < 3) t = 0L
                     } while (ev.changes.any { it.pressed })
                 }
             }

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

@@ -0,0 +1,147 @@
+package com.archipelago.app.ui.components
+
+import androidx.compose.animation.core.LinearEasing
+import androidx.compose.animation.core.RepeatMode
+import androidx.compose.animation.core.animateFloat
+import androidx.compose.animation.core.infiniteRepeatable
+import androidx.compose.animation.core.rememberInfiniteTransition
+import androidx.compose.animation.core.tween
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.offset
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+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.remember
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.draw.scale
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import com.archipelago.app.R
+import com.archipelago.app.ui.theme.BitcoinOrange
+import kotlinx.coroutines.delay
+
+/**
+ * First-launch teaching overlay for the three-finger hold gesture. Three
+ * fingertip dots pulse in a "press" rhythm with an expanding ring while a
+ * short caption explains what the gesture opens. Dismissed by tapping
+ * anywhere (or automatically after a few seconds) — shown once, ever.
+ */
+@Composable
+fun GestureHintOverlay(onDismiss: () -> Unit) {
+    // Auto-dismiss so a user who taps nothing is never stuck behind the scrim.
+    LaunchedEffect(Unit) {
+        delay(6500)
+        onDismiss()
+    }
+
+    val transition = rememberInfiniteTransition(label = "gesture-hint")
+    // Fingertips press down together…
+    val press by transition.animateFloat(
+        initialValue = 1f,
+        targetValue = 0.86f,
+        animationSpec = infiniteRepeatable(tween(650), RepeatMode.Reverse),
+        label = "press",
+    )
+    // …while a ring ripples outward on each press cycle.
+    val ripple by transition.animateFloat(
+        initialValue = 0f,
+        targetValue = 1f,
+        animationSpec = infiniteRepeatable(tween(1300, easing = LinearEasing)),
+        label = "ripple",
+    )
+
+    Box(
+        modifier = Modifier
+            .fillMaxSize()
+            .background(Color.Black.copy(alpha = 0.72f))
+            .clickable(
+                interactionSource = remember { MutableInteractionSource() },
+                indication = null,
+                onClick = onDismiss,
+            ),
+        contentAlignment = Alignment.Center,
+    ) {
+        Column(horizontalAlignment = Alignment.CenterHorizontally) {
+            // Hand: three fingertip dots in a natural arc + ripple ring.
+            Box(Modifier.size(160.dp), contentAlignment = Alignment.Center) {
+                Box(
+                    Modifier
+                        .size(150.dp)
+                        .scale(0.4f + ripple * 0.6f)
+                        .border(
+                            2.dp,
+                            BitcoinOrange.copy(alpha = (1f - ripple) * 0.8f),
+                            CircleShape,
+                        ),
+                )
+                FingerDot(x = (-44).dp, y = 14.dp, scale = press)
+                FingerDot(x = 0.dp, y = (-12).dp, scale = press)
+                FingerDot(x = 44.dp, y = 8.dp, scale = press)
+            }
+
+            Spacer(Modifier.height(28.dp))
+
+            Text(
+                text = stringResource(R.string.gesture_hint_title),
+                style = MaterialTheme.typography.headlineSmall,
+                fontWeight = FontWeight.Bold,
+                color = Color.White,
+                textAlign = TextAlign.Center,
+            )
+            Spacer(Modifier.height(10.dp))
+            Text(
+                text = stringResource(R.string.gesture_hint_body),
+                style = MaterialTheme.typography.bodyMedium,
+                color = Color.White.copy(alpha = 0.7f),
+                textAlign = TextAlign.Center,
+                modifier = Modifier.padding(horizontal = 48.dp),
+            )
+
+            Spacer(Modifier.height(32.dp))
+
+            Box(
+                modifier = Modifier
+                    .clip(RoundedCornerShape(12.dp))
+                    .background(Color.White.copy(alpha = 0.12f))
+                    .clickable(onClick = onDismiss)
+                    .padding(horizontal = 28.dp, vertical = 12.dp),
+            ) {
+                Text(
+                    text = stringResource(R.string.gesture_hint_got_it),
+                    style = MaterialTheme.typography.labelLarge,
+                    color = Color.White,
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun FingerDot(x: androidx.compose.ui.unit.Dp, y: androidx.compose.ui.unit.Dp, scale: Float) {
+    Box(
+        Modifier
+            .offset(x = x, y = y)
+            .size(26.dp)
+            .scale(scale)
+            .background(Color.White.copy(alpha = 0.92f), CircleShape),
+    )
+}

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

@@ -0,0 +1,77 @@
+package com.archipelago.app.ui.components
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.size
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+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.font.FontWeight
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import com.archipelago.app.ui.screens.PixelArtLogo
+import com.archipelago.app.ui.theme.BitcoinOrange
+import com.archipelago.app.ui.theme.SurfaceBlack
+import com.archipelago.app.ui.theme.TextMuted
+
+/**
+ * The branded "F*CK IPs" full-screen loader — shown whenever the app is
+ * dialing the node over the mesh (relaunch race, post-scan first connect),
+ * instead of an anonymous spinner. The point of the brand: what's loading
+ * is a connection to a cryptographic identity, not an IP.
+ */
+@Composable
+fun MeshLoadingScreen(message: String = "Dialing your node by its key — no IPs harmed") {
+    Box(
+        Modifier
+            .fillMaxSize()
+            .background(SurfaceBlack),
+        contentAlignment = Alignment.Center,
+    ) {
+        Column(horizontalAlignment = Alignment.CenterHorizontally) {
+            // The brand's circle-container logo (as on the connect screen /
+            // web login): pixel-art "a" centered in a black disc.
+            Box(
+                Modifier
+                    .size(120.dp)
+                    .clip(androidx.compose.foundation.shape.CircleShape)
+                    .background(Color.Black)
+                    .border(
+                        1.dp,
+                        Color.White.copy(alpha = 0.14f),
+                        androidx.compose.foundation.shape.CircleShape,
+                    ),
+                contentAlignment = Alignment.Center,
+            ) {
+                PixelArtLogo(Modifier.size(64.dp))
+            }
+            Spacer(Modifier.height(20.dp))
+            Text(
+                text = "F*CK IPs MESH",
+                color = BitcoinOrange,
+                fontSize = 18.sp,
+                fontWeight = FontWeight.Bold,
+                letterSpacing = 4.sp,
+            )
+            Spacer(Modifier.height(8.dp))
+            Text(
+                text = message,
+                color = TextMuted,
+                fontSize = 13.sp,
+                textAlign = TextAlign.Center,
+            )
+            Spacer(Modifier.height(24.dp))
+            CircularProgressIndicator(color = BitcoinOrange)
+        }
+    }
+}

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

@@ -116,7 +116,7 @@ fun NESController(
     Box(
         modifier = modifier
             .fillMaxSize()
-            .twoFingerHold(onMenu)
+            .threeFingerHold(onMenu)
             .padding(horizontal = 40.dp, vertical = 24.dp),
         contentAlignment = Alignment.Center,
     ) {
@@ -451,17 +451,17 @@ fun PlayerPill(c: NESPalette, playerId: Int, onToggle: () -> Unit) {
     }
 }
 
-/** Two-finger hold gesture modifier */
-fun Modifier.twoFingerHold(onHold: () -> Unit) = this.pointerInput(Unit) {
+/** Three-finger hold gesture modifier (two fingers stay free for scrolling) */
+fun Modifier.threeFingerHold(onHold: () -> Unit) = this.pointerInput(Unit) {
     awaitEachGesture {
         awaitFirstDown(requireUnconsumed = false)
         var t = 0L; var fired = false
         do {
             val ev = awaitPointerEvent()
             val a = ev.changes.filter { !it.changedToUp() }
-            if (a.size >= 2 && t == 0L) t = System.currentTimeMillis()
-            if (a.size >= 2 && !fired && t > 0 && System.currentTimeMillis() - t > 500) { fired = true; onHold() }
-            if (a.size < 2) t = 0L
+            if (a.size >= 3 && t == 0L) t = System.currentTimeMillis()
+            if (a.size >= 3 && !fired && t > 0 && System.currentTimeMillis() - t > 500) { fired = true; onHold() }
+            if (a.size < 3) t = 0L
         } while (ev.changes.any { it.pressed })
     }
 }

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

@@ -24,6 +24,9 @@ import androidx.compose.foundation.layout.widthIn
 import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.foundation.text.KeyboardActions
 import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.QrCodeScanner
+import androidx.compose.material3.Icon
 import androidx.compose.material3.OutlinedTextField
 import androidx.compose.material3.OutlinedTextFieldDefaults
 import androidx.compose.material3.Text
@@ -36,6 +39,7 @@ import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
 import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.res.stringResource
 import androidx.compose.ui.text.TextStyle
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.input.ImeAction
@@ -44,6 +48,7 @@ import androidx.compose.ui.text.input.PasswordVisualTransformation
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
+import com.archipelago.app.R
 import com.archipelago.app.data.ServerEntry
 import com.archipelago.app.ui.theme.BitcoinOrange
 import com.archipelago.app.ui.theme.ControllerStyle
@@ -75,10 +80,13 @@ fun NESMenu(
     onDismiss: () -> Unit,
     onSelectServer: (ServerEntry) -> Unit,
     onAddServer: (ServerEntry) -> Unit,
+    onScanQr: (() -> Unit)? = null,
+    onEditServer: (ServerEntry, ServerEntry) -> Unit,
     onRemoveServer: (ServerEntry) -> Unit,
     onToggleMode: () -> Unit,
     onToggleStyle: () -> Unit,
     onBackToWebView: (() -> Unit)? = null,
+    onMeshParty: (() -> Unit)? = null,
 ) {
     AnimatedVisibility(visible = visible, enter = fadeIn(), exit = fadeOut()) {
         Box(
@@ -87,7 +95,7 @@ fun NESMenu(
             contentAlignment = Alignment.Center,
         ) {
             AnimatedVisibility(visible = visible, enter = fadeIn() + scaleIn(initialScale = 0.95f), exit = fadeOut() + scaleOut(targetScale = 0.95f)) {
-                MenuPanel(servers, activeServer, isGamepadMode, controllerStyle, onDismiss, onSelectServer, onAddServer, onRemoveServer, onToggleMode, onToggleStyle, onBackToWebView)
+                MenuPanel(servers, activeServer, isGamepadMode, controllerStyle, onDismiss, onSelectServer, onAddServer, onScanQr, onEditServer, onRemoveServer, onToggleMode, onToggleStyle, onBackToWebView, onMeshParty)
             }
         }
     }
@@ -102,21 +110,41 @@ private fun MenuPanel(
     onDismiss: () -> Unit,
     onSelectServer: (ServerEntry) -> Unit,
     onAddServer: (ServerEntry) -> Unit,
+    onScanQr: (() -> Unit)?,
+    onEditServer: (ServerEntry, ServerEntry) -> Unit,
     onRemoveServer: (ServerEntry) -> Unit,
     onToggleMode: () -> Unit,
     onToggleStyle: () -> Unit,
     onBackToWebView: (() -> Unit)?,
+    onMeshParty: (() -> 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.isNotBlank()) {
+        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))
-            nm = ""; addr = ""; pwd = ""; showAdd = false
         }
+        resetForm()
     }
 
     Column(
@@ -149,6 +177,7 @@ private fun MenuPanel(
                 label = server.displayName(),
                 selected = active,
                 onClick = { onSelectServer(server) },
+                onEdit = { startEdit(server) },
                 onRemove = { onRemoveServer(server) },
             )
         }
@@ -157,8 +186,8 @@ private fun MenuPanel(
             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()
@@ -168,6 +197,25 @@ private fun MenuPanel(
                     .padding(12.dp),
                 verticalArrangement = Arrangement.spacedBy(8.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)",
@@ -196,7 +244,30 @@ private fun MenuPanel(
                 }
             }
         } else {
-            MenuItem(label = "Add Server", labelColor = BitcoinOrange, onClick = { showAdd = true })
+            Row(Modifier.fillMaxWidth(), horizontalArrangement = Arrangement.spacedBy(10.dp)) {
+                Box(Modifier.weight(1f)) {
+                    MenuItem(label = "Add Server", labelColor = BitcoinOrange, onClick = { showAdd = true })
+                }
+                if (onScanQr != null) {
+                    // Add server by scanning the node's pairing QR
+                    Box(
+                        Modifier
+                            .size(ROW_H)
+                            .clip(RoundedCornerShape(ROW_R))
+                            .background(RowBg)
+                            .border(1.dp, RowBorder, RoundedCornerShape(ROW_R))
+                            .clickable { onScanQr() },
+                        contentAlignment = Alignment.Center,
+                    ) {
+                        Icon(
+                            Icons.Default.QrCodeScanner,
+                            contentDescription = stringResource(R.string.add_server_qr),
+                            tint = BitcoinOrange,
+                            modifier = Modifier.size(24.dp),
+                        )
+                    }
+                }
+            }
         }
 
         Spacer(Modifier.height(2.dp))
@@ -215,6 +286,11 @@ private fun MenuPanel(
             onClick = onToggleStyle,
         )
 
+        // Phone↔phone mesh pairing + chat
+        if (onMeshParty != null) {
+            MenuItem(label = "Mesh Party", labelColor = BitcoinOrange, onClick = onMeshParty)
+        }
+
         // Back to dashboard
         if (onBackToWebView != null) {
             MenuItem(label = "Back to Dashboard", onClick = onBackToWebView)
@@ -228,6 +304,7 @@ private fun MenuItem(
     selected: Boolean = false,
     labelColor: Color = TextPrimary,
     onClick: () -> Unit,
+    onEdit: (() -> Unit)? = null,
     onRemove: (() -> Unit)? = null,
 ) {
     Row(
@@ -247,7 +324,16 @@ private fun MenuItem(
             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(
                 "✕",

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

@@ -50,7 +50,7 @@ fun NESPortraitController(
     Box(
         Modifier
             .fillMaxSize()
-            .twoFingerHold(onMenu)
+            .threeFingerHold(onMenu)
             .padding(horizontal = 40.dp, vertical = 24.dp),
         contentAlignment = Alignment.Center,
     ) {
@@ -87,7 +87,7 @@ fun NESPortraitController(
                     onMove = { dx, dy -> onMouseMove(dx, dy) },
                     onClick = { onMouseClick(it) },
                     onScroll = { dy -> onMouseScroll(dy) },
-                    onTwoFingerHold = onMenu,
+                    onThreeFingerHold = onMenu,
                     modifier = Modifier
                         .fillMaxWidth()
                         .weight(1f),

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

@@ -0,0 +1,334 @@
+package com.archipelago.app.ui.components
+
+import android.Manifest
+import android.content.pm.PackageManager
+import androidx.activity.compose.BackHandler
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.camera.core.CameraSelector
+import androidx.camera.core.ImageAnalysis
+import androidx.camera.core.ImageProxy
+import androidx.camera.core.Preview
+import androidx.camera.lifecycle.ProcessCameraProvider
+import androidx.camera.view.PreviewView
+import androidx.compose.animation.AnimatedVisibility
+import androidx.compose.animation.fadeIn
+import androidx.compose.animation.fadeOut
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.WindowInsets
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.safeDrawing
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.windowInsetsPadding
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Close
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberUpdatedState
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.platform.LocalLifecycleOwner
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.viewinterop.AndroidView
+import androidx.core.content.ContextCompat
+import com.archipelago.app.R
+import com.archipelago.app.data.PairResult
+import com.archipelago.app.data.ServerQrParser
+import com.archipelago.app.ui.screens.GlassButton
+import com.archipelago.app.ui.theme.BitcoinOrange
+import com.archipelago.app.ui.theme.TextMuted
+import com.archipelago.app.ui.theme.TextPrimary
+import com.google.zxing.BarcodeFormat
+import com.google.zxing.BinaryBitmap
+import com.google.zxing.DecodeHintType
+import com.google.zxing.MultiFormatReader
+import com.google.zxing.NotFoundException
+import com.google.zxing.PlanarYUVLuminanceSource
+import com.google.zxing.common.HybridBinarizer
+import kotlinx.coroutines.delay
+import java.util.concurrent.Executors
+
+/**
+ * Full-screen camera overlay that scans the node pairing QR
+ * (docs/companion-pairing-qr.md) and reports the decoded server entry.
+ * Handles the camera permission itself; foreign/invalid codes show a hint
+ * and scanning continues.
+ */
+@Composable
+fun QrScannerOverlay(
+    visible: Boolean,
+    onDismiss: () -> Unit,
+    onServerScanned: (PairResult.Success) -> Unit,
+) {
+    val context = LocalContext.current
+    var hasPermission by remember {
+        mutableStateOf(
+            ContextCompat.checkSelfPermission(context, Manifest.permission.CAMERA) ==
+                PackageManager.PERMISSION_GRANTED
+        )
+    }
+    var hintRes by remember { mutableStateOf<Int?>(null) }
+    var handled by remember { mutableStateOf(false) }
+
+    val permissionLauncher = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission()
+    ) { granted -> hasPermission = granted }
+
+    LaunchedEffect(visible) {
+        if (visible) {
+            handled = false
+            hintRes = null
+            val granted = ContextCompat.checkSelfPermission(context, Manifest.permission.CAMERA) ==
+                PackageManager.PERMISSION_GRANTED
+            hasPermission = granted
+            if (!granted) permissionLauncher.launch(Manifest.permission.CAMERA)
+        }
+    }
+
+    // Foreign-code hint fades after a moment so scanning feels live again.
+    LaunchedEffect(hintRes) {
+        if (hintRes != null) {
+            delay(2500)
+            hintRes = null
+        }
+    }
+
+    AnimatedVisibility(visible = visible, enter = fadeIn(), exit = fadeOut()) {
+        BackHandler { onDismiss() }
+        Box(
+            Modifier
+                .fillMaxSize()
+                .background(Color.Black),
+        ) {
+            if (hasPermission) {
+                CameraQrPreview(
+                    onDecoded = { text ->
+                        if (!handled) {
+                            when (val result = ServerQrParser.parse(text)) {
+                                is PairResult.Success -> {
+                                    handled = true
+                                    onServerScanned(result)
+                                }
+                                is PairResult.UnsupportedVersion -> hintRes = R.string.update_app_for_qr
+                                is PairResult.Invalid -> hintRes = R.string.invalid_pairing_qr
+                            }
+                        }
+                    },
+                )
+                // Aim frame
+                Box(
+                    Modifier
+                        .align(Alignment.Center)
+                        .size(260.dp)
+                        .border(2.dp, BitcoinOrange.copy(alpha = 0.85f), RoundedCornerShape(20.dp)),
+                )
+            } else {
+                Column(
+                    Modifier
+                        .align(Alignment.Center)
+                        .padding(horizontal = 32.dp),
+                    horizontalAlignment = Alignment.CenterHorizontally,
+                    verticalArrangement = Arrangement.spacedBy(16.dp),
+                ) {
+                    Text(
+                        text = stringResource(R.string.camera_permission_needed),
+                        color = TextPrimary,
+                        style = MaterialTheme.typography.bodyLarge,
+                        textAlign = TextAlign.Center,
+                    )
+                    GlassButton(
+                        text = stringResource(R.string.grant_camera_access),
+                        onClick = { permissionLauncher.launch(Manifest.permission.CAMERA) },
+                        modifier = Modifier.fillMaxWidth().height(56.dp),
+                    )
+                }
+            }
+
+            // Top bar: title + close
+            Row(
+                Modifier
+                    .fillMaxWidth()
+                    .windowInsetsPadding(WindowInsets.safeDrawing)
+                    .padding(horizontal = 8.dp, vertical = 4.dp),
+                verticalAlignment = Alignment.CenterVertically,
+                horizontalArrangement = Arrangement.SpaceBetween,
+            ) {
+                Text(
+                    text = stringResource(R.string.scan_node_qr),
+                    color = TextPrimary,
+                    style = MaterialTheme.typography.titleMedium,
+                    modifier = Modifier.padding(start = 12.dp),
+                )
+                IconButton(onClick = onDismiss) {
+                    Icon(Icons.Default.Close, stringResource(R.string.close), tint = TextPrimary)
+                }
+            }
+
+            // Bottom hints
+            Column(
+                Modifier
+                    .align(Alignment.BottomCenter)
+                    .windowInsetsPadding(WindowInsets.safeDrawing)
+                    .padding(horizontal = 32.dp, vertical = 24.dp),
+                horizontalAlignment = Alignment.CenterHorizontally,
+            ) {
+                hintRes?.let { res ->
+                    Text(
+                        text = stringResource(res),
+                        color = BitcoinOrange,
+                        style = MaterialTheme.typography.bodyMedium,
+                        textAlign = TextAlign.Center,
+                    )
+                    Spacer(Modifier.height(8.dp))
+                }
+                if (hasPermission) {
+                    Text(
+                        text = stringResource(R.string.scan_qr_hint),
+                        color = TextMuted,
+                        style = MaterialTheme.typography.bodyMedium,
+                        textAlign = TextAlign.Center,
+                    )
+                }
+            }
+        }
+    }
+}
+
+/** Shared by the pairing scanner and the wallet scan modal. */
+@Composable
+internal fun CameraQrPreview(onDecoded: (String) -> Unit) {
+    val context = LocalContext.current
+    val lifecycleOwner = LocalLifecycleOwner.current
+    val currentOnDecoded by rememberUpdatedState(onDecoded)
+    val previewView = remember {
+        PreviewView(context).apply {
+            scaleType = PreviewView.ScaleType.FILL_CENTER
+            // TextureView, not the SurfaceView default: SurfaceView punches a
+            // hole in the window, which black-flashes inside Compose fades and
+            // ignores rounded-corner clipping (wallet modal).
+            implementationMode = PreviewView.ImplementationMode.COMPATIBLE
+        }
+    }
+
+    DisposableEffect(Unit) {
+        val analysisExecutor = Executors.newSingleThreadExecutor()
+        val mainExecutor = ContextCompat.getMainExecutor(context)
+        val providerFuture = ProcessCameraProvider.getInstance(context)
+        var provider: ProcessCameraProvider? = null
+
+        providerFuture.addListener({
+            val p = providerFuture.get()
+            provider = p
+            val preview = Preview.Builder().build().also {
+                it.setSurfaceProvider(previewView.surfaceProvider)
+            }
+            // CameraX's analysis default is 640x480 — too few pixels per module
+            // to decode a modal-sized QR at arm's length. 1280x720 more than
+            // doubles the pixel density at negligible analysis cost.
+            @Suppress("DEPRECATION")
+            val analysis = ImageAnalysis.Builder()
+                .setTargetResolution(android.util.Size(1280, 720))
+                .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
+                .build()
+                .also {
+                    it.setAnalyzer(
+                        analysisExecutor,
+                        QrCodeAnalyzer { text -> mainExecutor.execute { currentOnDecoded(text) } },
+                    )
+                }
+            try {
+                p.unbindAll()
+                p.bindToLifecycle(lifecycleOwner, CameraSelector.DEFAULT_BACK_CAMERA, preview, analysis)
+            } catch (_: Exception) {
+                // Camera unavailable — the user can dismiss and enter details manually.
+            }
+        }, mainExecutor)
+
+        onDispose {
+            provider?.unbindAll()
+            analysisExecutor.shutdown()
+        }
+    }
+
+    AndroidView(factory = { previewView }, modifier = Modifier.fillMaxSize())
+}
+
+/** ZXing-based QR decoder over the camera's Y (luminance) plane. */
+private class QrCodeAnalyzer(private val onDecoded: (String) -> Unit) : ImageAnalysis.Analyzer {
+    private val reader = MultiFormatReader().apply {
+        setHints(
+            mapOf(
+                DecodeHintType.POSSIBLE_FORMATS to listOf(BarcodeFormat.QR_CODE),
+                // Screen-displayed QRs come with moiré, glare, and soft focus at
+                // close range — the exhaustive search is worth the milliseconds.
+                DecodeHintType.TRY_HARDER to true,
+            )
+        )
+    }
+
+    private var lastAttempt = 0L
+
+    override fun analyze(image: ImageProxy) {
+        // Decode ~7x/s, not on every frame: TRY_HARDER (plus the inverted
+        // retry) pegs a core when run at camera rate, and that CPU contention
+        // is what made the preview itself stutter. KEEP_ONLY_LATEST means the
+        // frames skipped here are simply dropped, so decodes stay current.
+        val now = System.currentTimeMillis()
+        if (now - lastAttempt < 140) {
+            image.close()
+            return
+        }
+        lastAttempt = now
+        try {
+            val plane = image.planes[0]
+            val buffer = plane.buffer
+            // Copy into a rowStride-wide array; the last row of the plane buffer
+            // may be short of the full stride, so the tail stays zero-padded.
+            val data = ByteArray(plane.rowStride * image.height)
+            buffer.get(data, 0, minOf(buffer.remaining(), data.size))
+            val source = PlanarYUVLuminanceSource(
+                data, plane.rowStride, image.height,
+                0, 0, image.width, image.height,
+                false,
+            )
+            val result = try {
+                reader.decodeWithState(BinaryBitmap(HybridBinarizer(source)))
+            } catch (_: NotFoundException) {
+                // Dark-themed pages can render light-on-dark QRs — retry inverted.
+                reader.reset()
+                reader.decodeWithState(BinaryBitmap(HybridBinarizer(source.invert())))
+            }
+            onDecoded(result.text)
+        } catch (_: NotFoundException) {
+            // No QR in this frame — keep scanning.
+        } catch (_: Exception) {
+            // Malformed frame; skip it.
+        } finally {
+            reader.reset()
+            image.close()
+        }
+    }
+}

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

@@ -32,7 +32,7 @@ fun Trackpad(
     onMove: (dx: Int, dy: Int) -> Unit,
     onClick: (button: Int) -> Unit,
     onScroll: (dy: Int) -> Unit,
-    onTwoFingerHold: () -> Unit,
+    onThreeFingerHold: () -> Unit,
     modifier: Modifier = Modifier,
 ) {
     var fingers by remember { mutableIntStateOf(0) }
@@ -53,7 +53,7 @@ fun Trackpad(
                     val t0 = System.currentTimeMillis()
                     var maxPtrs = 1
                     var holdFired = false
-                    var twoStart = 0L
+                    var threeStart = 0L
                     var scrollAcc = 0f
                     fingers = 1
 
@@ -64,19 +64,24 @@ fun Trackpad(
                         fingers = active.size
 
                         when {
-                            active.size >= 2 -> {
-                                if (twoStart == 0L) twoStart = System.currentTimeMillis()
-                                if (!holdFired && System.currentTimeMillis() - twoStart > 500) {
+                            // Three fingers = hold for menu; two = scroll. Kept
+                            // on separate counts so a long two-finger scroll can
+                            // never fire the menu mid-gesture.
+                            active.size >= 3 -> {
+                                if (threeStart == 0L) threeStart = System.currentTimeMillis()
+                                if (!holdFired && System.currentTimeMillis() - threeStart > 500) {
                                     holdFired = true
-                                    onTwoFingerHold()
+                                    onThreeFingerHold()
                                 }
-                                if (!holdFired) {
-                                    val dy = active.map { it.positionChange().y }.average().toFloat()
-                                    scrollAcc += dy
-                                    if (kotlin.math.abs(scrollAcc) > 12f) {
-                                        onScroll(if (scrollAcc > 0) 1 else -1)
-                                        scrollAcc = 0f
-                                    }
+                                ev.changes.forEach { it.consume() }
+                            }
+                            active.size == 2 -> {
+                                threeStart = 0L
+                                val dy = active.map { it.positionChange().y }.average().toFloat()
+                                scrollAcc += dy
+                                if (kotlin.math.abs(scrollAcc) > 12f) {
+                                    onScroll(if (scrollAcc > 0) 1 else -1)
+                                    scrollAcc = 0f
                                 }
                                 ev.changes.forEach { it.consume() }
                             }
@@ -99,7 +104,11 @@ fun Trackpad(
         contentAlignment = Alignment.Center,
     ) {
         Text(
-            text = if (fingers >= 2) "hold for menu" else "",
+            text = when {
+                fingers >= 3 -> "hold for menu"
+                fingers == 2 -> "scroll"
+                else -> ""
+            },
             style = MaterialTheme.typography.labelSmall,
             color = muted.copy(alpha = 0.4f),
         )

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

@@ -0,0 +1,294 @@
+package com.archipelago.app.ui.components
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.graphics.BitmapFactory
+import android.net.Uri
+import androidx.activity.compose.BackHandler
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.compose.animation.AnimatedVisibility
+import androidx.compose.animation.fadeIn
+import androidx.compose.animation.fadeOut
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+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.aspectRatio
+import androidx.compose.foundation.layout.defaultMinSize
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Close
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.res.stringResource
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.core.content.ContextCompat
+import com.archipelago.app.R
+import com.archipelago.app.ui.screens.GlassButton
+import com.archipelago.app.ui.theme.BitcoinOrange
+import com.google.zxing.BarcodeFormat
+import com.google.zxing.BinaryBitmap
+import com.google.zxing.DecodeHintType
+import com.google.zxing.MultiFormatReader
+import com.google.zxing.NotFoundException
+import com.google.zxing.RGBLuminanceSource
+import com.google.zxing.common.HybridBinarizer
+
+/**
+ * Native replacement for the web wallet's scan pane — same visual design as
+ * neode-ui's WalletScanModal (dark glass card, square preview, orange
+ * viewfinder, status strip) but the camera and decoding run natively, so the
+ * preview doesn't lag the way getUserMedia does inside a WebView.
+ *
+ * Decoded text is handed back to the page ([onDecoded]) which does all the
+ * detection/spend logic; the page in turn streams status lines (animated-QR
+ * progress, "not recognised" errors) back in via [status] and closes the
+ * modal through the JS bridge once it accepts a code.
+ */
+@Composable
+fun WalletQrScannerModal(
+    visible: Boolean,
+    status: Pair<String, Boolean>?, // message from the web page + isError
+    onDecoded: (String) -> Unit,
+    onDismiss: () -> Unit,
+) {
+    val context = LocalContext.current
+    var hasPermission by remember {
+        mutableStateOf(
+            ContextCompat.checkSelfPermission(context, Manifest.permission.CAMERA) ==
+                PackageManager.PERMISSION_GRANTED
+        )
+    }
+    val permissionLauncher = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission()
+    ) { granted -> hasPermission = granted }
+
+    // Local error from a failed image upload; a fresh web status replaces it.
+    var uploadError by remember { mutableStateOf<String?>(null) }
+    val noQrMessage = stringResource(R.string.no_qr_in_image)
+    val imagePicker = rememberLauncherForActivityResult(
+        ActivityResultContracts.GetContent()
+    ) { uri ->
+        if (uri != null) {
+            val decoded = decodeQrFromUri(context, uri)
+            if (decoded != null) {
+                uploadError = null
+                onDecoded(decoded)
+            } else {
+                uploadError = noQrMessage
+            }
+        }
+    }
+
+    LaunchedEffect(visible) {
+        if (visible) {
+            uploadError = null
+            val granted = ContextCompat.checkSelfPermission(context, Manifest.permission.CAMERA) ==
+                PackageManager.PERMISSION_GRANTED
+            hasPermission = granted
+            if (!granted) permissionLauncher.launch(Manifest.permission.CAMERA)
+        }
+    }
+    LaunchedEffect(status) { if (status != null) uploadError = null }
+
+    AnimatedVisibility(visible = visible, enter = fadeIn(), exit = fadeOut()) {
+        BackHandler { onDismiss() }
+        Box(
+            Modifier
+                .fillMaxSize()
+                .background(Color.Black.copy(alpha = 0.6f))
+                .clickable(
+                    interactionSource = remember { MutableInteractionSource() },
+                    indication = null,
+                    onClick = onDismiss,
+                ),
+            contentAlignment = Alignment.Center,
+        ) {
+            Column(
+                Modifier
+                    .padding(16.dp)
+                    .widthIn(max = 420.dp)
+                    .fillMaxWidth()
+                    .clip(RoundedCornerShape(24.dp))
+                    .background(Color(0xF212151C))
+                    .border(1.dp, Color.White.copy(alpha = 0.10f), RoundedCornerShape(24.dp))
+                    .clickable(
+                        interactionSource = remember { MutableInteractionSource() },
+                        indication = null,
+                        onClick = {}, // swallow — only the scrim dismisses
+                    )
+                    .padding(24.dp),
+            ) {
+                // Header — mirrors the web modal's title row
+                Row(
+                    Modifier.fillMaxWidth(),
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.SpaceBetween,
+                ) {
+                    Text(
+                        text = stringResource(R.string.scan_to_send),
+                        style = MaterialTheme.typography.titleLarge,
+                        fontWeight = FontWeight.SemiBold,
+                        color = Color.White,
+                    )
+                    IconButton(onClick = onDismiss) {
+                        Icon(
+                            Icons.Default.Close,
+                            stringResource(R.string.close),
+                            tint = Color.White.copy(alpha = 0.7f),
+                        )
+                    }
+                }
+
+                Spacer(Modifier.height(8.dp))
+
+                // Square camera preview with the orange viewfinder
+                Box(
+                    Modifier
+                        .fillMaxWidth()
+                        .aspectRatio(1f)
+                        .clip(RoundedCornerShape(12.dp))
+                        .background(Color.Black.copy(alpha = 0.4f))
+                        .border(1.dp, Color.White.copy(alpha = 0.10f), RoundedCornerShape(12.dp)),
+                    contentAlignment = Alignment.Center,
+                ) {
+                    if (hasPermission) {
+                        // Throttle repeat frames: a static QR decodes ~20x/s but
+                        // the page only needs one; animated QRs still stream
+                        // because each frame's text differs.
+                        var lastText by remember { mutableStateOf("") }
+                        var lastSentAt by remember { mutableStateOf(0L) }
+                        CameraQrPreview(onDecoded = { text ->
+                            val now = System.currentTimeMillis()
+                            if (text != lastText || now - lastSentAt > 250) {
+                                lastText = text
+                                lastSentAt = now
+                                onDecoded(text)
+                            }
+                        })
+                        Box(
+                            Modifier
+                                .fillMaxSize(0.62f)
+                                .border(
+                                    2.dp,
+                                    BitcoinOrange.copy(alpha = 0.85f),
+                                    RoundedCornerShape(16.dp),
+                                ),
+                        )
+                    } else {
+                        Column(
+                            Modifier.padding(horizontal = 24.dp),
+                            horizontalAlignment = Alignment.CenterHorizontally,
+                            verticalArrangement = Arrangement.spacedBy(12.dp),
+                        ) {
+                            Text(
+                                text = stringResource(R.string.camera_permission_needed),
+                                color = Color.White.copy(alpha = 0.7f),
+                                style = MaterialTheme.typography.bodyMedium,
+                                textAlign = TextAlign.Center,
+                            )
+                            GlassButton(
+                                text = stringResource(R.string.grant_camera_access),
+                                onClick = { permissionLauncher.launch(Manifest.permission.CAMERA) },
+                                modifier = Modifier.fillMaxWidth().height(48.dp),
+                            )
+                        }
+                    }
+                }
+
+                Spacer(Modifier.height(16.dp))
+
+                // Status strip — same slot the web modal uses for hints/errors
+                val message = uploadError ?: status?.first
+                val isError = uploadError != null || status?.second == true
+                Box(
+                    Modifier
+                        .fillMaxWidth()
+                        .clip(RoundedCornerShape(8.dp))
+                        .background(Color.White.copy(alpha = 0.05f))
+                        .padding(12.dp)
+                        .defaultMinSize(minHeight = 24.dp),
+                    contentAlignment = Alignment.Center,
+                ) {
+                    Text(
+                        text = message?.takeIf { it.isNotBlank() }
+                            ?: stringResource(R.string.scan_wallet_hint),
+                        style = MaterialTheme.typography.bodySmall,
+                        color = if (isError) Color(0xFFF87171) else Color.White.copy(alpha = 0.6f),
+                        textAlign = TextAlign.Center,
+                    )
+                }
+
+                Spacer(Modifier.height(16.dp))
+
+                GlassButton(
+                    text = stringResource(R.string.upload_qr_image),
+                    onClick = { imagePicker.launch("image/*") },
+                    modifier = Modifier.fillMaxWidth().height(48.dp),
+                )
+            }
+        }
+    }
+}
+
+/** Decode a QR from a picked image, downsampled so huge photos stay cheap. */
+private fun decodeQrFromUri(context: Context, uri: Uri): String? {
+    return try {
+        val resolver = context.contentResolver
+        val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+        resolver.openInputStream(uri)?.use { BitmapFactory.decodeStream(it, null, bounds) }
+        var sample = 1
+        val maxDim = maxOf(bounds.outWidth, bounds.outHeight)
+        while (maxDim / (sample * 2) >= 1600) sample *= 2
+        val opts = BitmapFactory.Options().apply { inSampleSize = sample }
+        val bmp = resolver.openInputStream(uri)?.use { BitmapFactory.decodeStream(it, null, opts) }
+            ?: return null
+        val pixels = IntArray(bmp.width * bmp.height)
+        bmp.getPixels(pixels, 0, bmp.width, 0, 0, bmp.width, bmp.height)
+        val source = RGBLuminanceSource(bmp.width, bmp.height, pixels)
+        val reader = MultiFormatReader().apply {
+            setHints(
+                mapOf(
+                    DecodeHintType.POSSIBLE_FORMATS to listOf(BarcodeFormat.QR_CODE),
+                    DecodeHintType.TRY_HARDER to true,
+                )
+            )
+        }
+        try {
+            reader.decodeWithState(BinaryBitmap(HybridBinarizer(source))).text
+        } catch (_: NotFoundException) {
+            // Light-on-dark QRs (dark-themed wallets) decode inverted.
+            reader.reset()
+            reader.decodeWithState(BinaryBitmap(HybridBinarizer(source.invert()))).text
+        }
+    } catch (_: Exception) {
+        null
+    }
+}

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

@@ -1,16 +1,28 @@
 package com.archipelago.app.ui.navigation
 
+import android.net.VpnService
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.platform.LocalContext
 import androidx.navigation.compose.NavHost
 import androidx.navigation.compose.composable
 import androidx.navigation.compose.rememberNavController
+import com.archipelago.app.data.PairResult
+import com.archipelago.app.data.ServerEntry
 import com.archipelago.app.data.ServerPreferences
+import com.archipelago.app.data.ServerQrParser
+import com.archipelago.app.fips.FipsManager
+import com.archipelago.app.ui.screens.FlareScreen
 import com.archipelago.app.ui.screens.IntroScreen
+import com.archipelago.app.ui.screens.PartyScreen
 import com.archipelago.app.ui.screens.RemoteInputScreen
 import com.archipelago.app.ui.screens.ServerConnectScreen
 import com.archipelago.app.ui.screens.WebViewScreen
@@ -21,10 +33,15 @@ object Routes {
     const val SERVER_CONNECT = "server_connect"
     const val WEB_VIEW = "web_view"
     const val REMOTE_INPUT = "remote_input"
+    const val MESH_PARTY = "mesh_party"
+    const val FLARE = "flare"
 }
 
 @Composable
-fun AppNavHost() {
+fun AppNavHost(
+    pairUri: String? = null,
+    onPairUriConsumed: () -> Unit = {},
+) {
     val context = LocalContext.current
     val prefs = remember { ServerPreferences(context) }
     val navController = rememberNavController()
@@ -33,8 +50,70 @@ fun AppNavHost() {
     val introSeen by prefs.introSeen.collectAsState(initial = null)
     val activeServer by prefs.activeServer.collectAsState(initial = null)
 
+    // Pairing entry from a deep link that carried no password — prefills the
+    // connect form so the user lands on the password prompt for that server.
+    var pairPrefill by remember { mutableStateOf<ServerEntry?>(null) }
+
+    // Mesh tunnel: Android's VPN consent dialog is the single unavoidable
+    // interaction — it can only be launched from an Activity, so pairing
+    // paths raise FipsManager.consentNeeded and it is handled here, once.
+    val consentNeeded by FipsManager.consentNeeded.collectAsState()
+    val vpnConsentLauncher = rememberLauncherForActivityResult(
+        ActivityResultContracts.StartActivityForResult()
+    ) { result ->
+        FipsManager.consentHandled()
+        if (result.resultCode == android.app.Activity.RESULT_OK) {
+            FipsManager.startService(context)
+        }
+    }
+    LaunchedEffect(consentNeeded) {
+        if (!consentNeeded) return@LaunchedEffect
+        val consentIntent = VpnService.prepare(context)
+        if (consentIntent == null) {
+            FipsManager.consentHandled()
+            FipsManager.startService(context)
+        } else {
+            vpnConsentLauncher.launch(consentIntent)
+        }
+    }
+
+    // Paired + previously consented → the mesh comes back silently on launch.
+    LaunchedEffect(Unit) {
+        FipsManager.autoStartIfReady(context)
+    }
+
     if (introSeen == null) return
 
+    // Declared after the introSeen gate so it can't fire before the NavHost
+    // below has set the nav graph; pairUri stays pending until consumed here.
+    LaunchedEffect(pairUri) {
+        val raw = pairUri ?: return@LaunchedEffect
+        onPairUriConsumed()
+        when (val result = ServerQrParser.parse(raw)) {
+            is PairResult.Success -> {
+                // Pairing implies the app is installed and in use — skip the intro.
+                prefs.markIntroSeen()
+                val merged = prefs.upsertServer(result.server)
+                FipsManager.registerNode(context, result.fips, merged.displayName())
+                if (merged.password.isNotBlank()) {
+                    // Demo flow: password came with the link — connect in one step.
+                    prefs.setActiveServer(merged)
+                    navController.navigate(Routes.WEB_VIEW) {
+                        popUpTo(0) { inclusive = true }
+                    }
+                } else {
+                    pairPrefill = merged
+                    navController.navigate(Routes.SERVER_CONNECT) {
+                        popUpTo(0) { inclusive = true }
+                    }
+                }
+            }
+            else -> {
+                // Invalid or too-new pairing link — ignore; normal startup continues.
+            }
+        }
+    }
+
     val startDestination = when {
         introSeen == false -> Routes.INTRO
         activeServer != null -> Routes.WEB_VIEW
@@ -47,6 +126,9 @@ fun AppNavHost() {
     ) {
         composable(Routes.INTRO) {
             IntroScreen(
+                onMeshParty = {
+                    navController.navigate(Routes.MESH_PARTY)
+                },
                 onContinue = {
                     scope.launch {
                         prefs.markIntroSeen()
@@ -65,6 +147,7 @@ fun AppNavHost() {
                         popUpTo(Routes.SERVER_CONNECT) { inclusive = true }
                     }
                 },
+                initialServer = pairPrefill,
             )
         }
 
@@ -81,6 +164,8 @@ fun AppNavHost() {
             } else {
                 WebViewScreen(
                     serverUrl = server.toUrl(),
+                    serverPassword = server.password,
+                    meshFallbackUrl = server.toMeshUrl(),
                     onDisconnect = {
                         scope.launch {
                             prefs.clearActiveServer()
@@ -101,6 +186,22 @@ fun AppNavHost() {
                 onBack = {
                     navController.popBackStack()
                 },
+                onMeshParty = {
+                    navController.navigate(Routes.MESH_PARTY)
+                },
+            )
+        }
+
+        composable(Routes.MESH_PARTY) {
+            PartyScreen(
+                onBack = { navController.popBackStack() },
+                onOpenChat = { navController.navigate(Routes.FLARE) },
+            )
+        }
+
+        composable(Routes.FLARE) {
+            FlareScreen(
+                onBack = { navController.popBackStack() },
             )
         }
     }

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

@@ -0,0 +1,359 @@
+package com.archipelago.app.ui.screens
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.net.Uri
+import androidx.activity.compose.BackHandler
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.compose.foundation.Image
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.imePadding
+import androidx.compose.foundation.layout.navigationBarsPadding
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.statusBarsPadding
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.lazy.rememberLazyListState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.foundation.text.KeyboardActions
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Image
+import androidx.compose.material3.Icon
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.OutlinedTextFieldDefaults
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+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.Color
+import androidx.compose.ui.graphics.asImageBitmap
+import androidx.compose.ui.layout.ContentScale
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.text.TextStyle
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.input.ImeAction
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import com.archipelago.app.fips.FipsManager
+import com.archipelago.app.fips.FipsNative
+import com.archipelago.app.fips.FipsPreferences
+import com.archipelago.app.fips.FlareClient
+import com.archipelago.app.fips.FlareMessage
+import com.archipelago.app.fips.FlareStore
+import com.archipelago.app.fips.PartyPeer
+import com.archipelago.app.ui.theme.BitcoinOrange
+import com.archipelago.app.ui.theme.SurfaceDark
+import com.archipelago.app.ui.theme.TextMuted
+import com.archipelago.app.ui.theme.TextPrimary
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+import java.io.ByteArrayOutputStream
+import java.io.File
+import java.util.UUID
+
+private val BubbleTheirs = Color.White.copy(alpha = 0.07f)
+private val BubbleBorder = Color.White.copy(alpha = 0.08f)
+
+/**
+ * Flare — phone↔phone chat and photo beam over the FIPS mesh. Every byte is
+ * E2E encrypted by the mesh layer and addressed by npub; whether it travels
+ * via a public anchor (5G) or a direct hotspot link is invisible up here —
+ * which is the entire point.
+ */
+@Composable
+fun FlareScreen(onBack: () -> Unit) {
+    val context = LocalContext.current
+    val prefs = remember { FipsPreferences(context) }
+    val scope = rememberCoroutineScope()
+
+    var identity by remember { mutableStateOf<FipsNative.Identity?>(null) }
+    var myName by remember { mutableStateOf("Phone") }
+    val peers by prefs.partyPeersFlow.collectAsState(initial = emptyList())
+    var selectedNpub by remember { mutableStateOf<String?>(null) }
+    val allMessages by FlareStore.messages.collectAsState()
+    var draft by remember { mutableStateOf("") }
+
+    LaunchedEffect(Unit) {
+        identity = FipsManager.ensureIdentity(prefs)
+        myName = prefs.partyName()
+    }
+    LaunchedEffect(peers) {
+        if (selectedNpub == null || peers.none { it.npub == selectedNpub }) {
+            selectedNpub = peers.firstOrNull()?.npub
+        }
+    }
+
+    val peer = peers.firstOrNull { it.npub == selectedNpub }
+    val messages = allMessages.filter { it.peerNpub == selectedNpub }
+    val listState = rememberLazyListState()
+    LaunchedEffect(messages.size) {
+        if (messages.isNotEmpty()) listState.animateScrollToItem(messages.size - 1)
+    }
+
+    fun sendText() {
+        val target = peer ?: return
+        val me = identity ?: return
+        val text = draft.trim()
+        if (text.isEmpty()) return
+        draft = ""
+        val msg = FlareMessage(
+            id = UUID.randomUUID().toString(),
+            peerNpub = target.npub,
+            fromMe = true,
+            name = myName,
+            text = text,
+            ts = System.currentTimeMillis(),
+            status = FlareMessage.Status.SENDING,
+        )
+        FlareStore.add(msg)
+        scope.launch(Dispatchers.IO) {
+            val ok = FlareClient.sendText(target, me.npub, myName, text)
+            FlareStore.setStatus(msg.id, if (ok) FlareMessage.Status.SENT else FlareMessage.Status.FAILED)
+        }
+    }
+
+    fun sendPhoto(uri: Uri) {
+        val target = peer ?: return
+        val me = identity ?: return
+        scope.launch(Dispatchers.IO) {
+            val jpeg = compressPhoto(context, uri) ?: return@launch
+            // Local copy so our own bubble renders the sent photo.
+            val dir = File(context.cacheDir, "flare").apply { mkdirs() }
+            val local = File(dir, "${UUID.randomUUID()}.jpg").apply { writeBytes(jpeg) }
+            val msg = FlareMessage(
+                id = UUID.randomUUID().toString(),
+                peerNpub = target.npub,
+                fromMe = true,
+                name = myName,
+                photoPath = local.absolutePath,
+                ts = System.currentTimeMillis(),
+                status = FlareMessage.Status.SENDING,
+            )
+            FlareStore.add(msg)
+            val ok = FlareClient.sendPhoto(target, me.npub, myName, jpeg)
+            FlareStore.setStatus(msg.id, if (ok) FlareMessage.Status.SENT else FlareMessage.Status.FAILED)
+        }
+    }
+
+    val photoPicker = rememberLauncherForActivityResult(
+        ActivityResultContracts.GetContent()
+    ) { uri -> uri?.let { sendPhoto(it) } }
+
+    BackHandler { onBack() }
+
+    Column(
+        Modifier
+            .fillMaxSize()
+            .background(SurfaceDark)
+            .statusBarsPadding()
+            .navigationBarsPadding()
+            .imePadding(),
+    ) {
+        // Header
+        Row(
+            Modifier.fillMaxWidth().padding(horizontal = 16.dp, vertical = 10.dp),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.SpaceBetween,
+        ) {
+            Text("‹ Back", color = TextMuted, fontSize = 15.sp, modifier = Modifier.clickable { onBack() }.padding(6.dp))
+            Column(horizontalAlignment = Alignment.CenterHorizontally) {
+                Text("FLARE", color = TextPrimary, fontSize = 16.sp, fontWeight = FontWeight.SemiBold, letterSpacing = 3.sp)
+                peer?.let {
+                    Text(
+                        it.name + if (it.ip.isNotBlank()) "  ·  direct+mesh" else "  ·  mesh",
+                        color = BitcoinOrange,
+                        fontSize = 11.sp,
+                    )
+                }
+            }
+            Spacer(Modifier.size(48.dp))
+        }
+
+        // Peer tabs when chatting with more than one phone
+        if (peers.size > 1) {
+            Row(
+                Modifier.fillMaxWidth().padding(horizontal = 16.dp),
+                horizontalArrangement = Arrangement.spacedBy(8.dp),
+            ) {
+                peers.forEach { p ->
+                    val active = p.npub == selectedNpub
+                    Text(
+                        p.name,
+                        color = if (active) BitcoinOrange else TextMuted,
+                        fontSize = 13.sp,
+                        modifier = Modifier
+                            .clip(RoundedCornerShape(10.dp))
+                            .background(if (active) BitcoinOrange.copy(alpha = 0.12f) else Color.Transparent)
+                            .border(
+                                1.dp,
+                                if (active) BitcoinOrange.copy(alpha = 0.4f) else BubbleBorder,
+                                RoundedCornerShape(10.dp),
+                            )
+                            .clickable { selectedNpub = p.npub }
+                            .padding(horizontal = 12.dp, vertical = 6.dp),
+                    )
+                }
+            }
+        }
+
+        if (peer == null) {
+            Box(Modifier.weight(1f).fillMaxWidth(), contentAlignment = Alignment.Center) {
+                Text("No party peers yet — scan a phone first", color = TextMuted, fontSize = 14.sp)
+            }
+        } else {
+            LazyColumn(
+                state = listState,
+                modifier = Modifier.weight(1f).fillMaxWidth(),
+                contentPadding = androidx.compose.foundation.layout.PaddingValues(16.dp),
+                verticalArrangement = Arrangement.spacedBy(8.dp),
+            ) {
+                items(messages, key = { it.id }) { msg ->
+                    MessageBubble(msg)
+                }
+            }
+
+            // Composer
+            Row(
+                Modifier.fillMaxWidth().padding(horizontal = 12.dp, vertical = 8.dp),
+                verticalAlignment = Alignment.CenterVertically,
+                horizontalArrangement = Arrangement.spacedBy(8.dp),
+            ) {
+                Box(
+                    Modifier
+                        .size(48.dp)
+                        .clip(RoundedCornerShape(12.dp))
+                        .background(BubbleTheirs)
+                        .border(1.dp, BubbleBorder, RoundedCornerShape(12.dp))
+                        .clickable { photoPicker.launch("image/*") },
+                    contentAlignment = Alignment.Center,
+                ) {
+                    Icon(Icons.Default.Image, "Beam a photo", tint = BitcoinOrange, modifier = Modifier.size(22.dp))
+                }
+                OutlinedTextField(
+                    value = draft,
+                    onValueChange = { draft = it },
+                    placeholder = { Text("Send a flare…", color = TextMuted, fontSize = 14.sp) },
+                    modifier = Modifier.weight(1f),
+                    singleLine = true,
+                    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Send),
+                    keyboardActions = KeyboardActions(onSend = { sendText() }),
+                    textStyle = TextStyle(color = TextPrimary, fontSize = 15.sp),
+                    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),
+                )
+                Box(
+                    Modifier
+                        .size(48.dp)
+                        .clip(RoundedCornerShape(12.dp))
+                        .background(BitcoinOrange.copy(alpha = 0.15f))
+                        .border(1.dp, BitcoinOrange.copy(alpha = 0.4f), RoundedCornerShape(12.dp))
+                        .clickable { sendText() },
+                    contentAlignment = Alignment.Center,
+                ) {
+                    Text("➤", color = BitcoinOrange, fontSize = 18.sp)
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun MessageBubble(msg: FlareMessage) {
+    Row(
+        Modifier.fillMaxWidth(),
+        horizontalArrangement = if (msg.fromMe) Arrangement.End else Arrangement.Start,
+    ) {
+        Column(
+            Modifier
+                .widthIn(max = 300.dp)
+                .clip(RoundedCornerShape(16.dp))
+                .background(if (msg.fromMe) BitcoinOrange.copy(alpha = 0.14f) else BubbleTheirs)
+                .border(
+                    1.dp,
+                    if (msg.fromMe) BitcoinOrange.copy(alpha = 0.35f) else BubbleBorder,
+                    RoundedCornerShape(16.dp),
+                )
+                .padding(horizontal = 12.dp, vertical = 8.dp),
+        ) {
+            if (msg.photoPath.isNotBlank()) {
+                val bmp = remember(msg.photoPath) { BitmapFactory.decodeFile(msg.photoPath) }
+                bmp?.let {
+                    Image(
+                        bitmap = it.asImageBitmap(),
+                        contentDescription = "Beamed photo",
+                        modifier = Modifier
+                            .fillMaxWidth()
+                            .clip(RoundedCornerShape(10.dp)),
+                        contentScale = ContentScale.FillWidth,
+                    )
+                }
+            }
+            if (msg.text.isNotBlank()) {
+                Text(msg.text, color = TextPrimary, fontSize = 15.sp)
+            }
+            Text(
+                when (msg.status) {
+                    FlareMessage.Status.SENDING -> "sending…"
+                    FlareMessage.Status.SENT -> "sent · E2E via mesh"
+                    FlareMessage.Status.FAILED -> "failed — tap to retry later"
+                    FlareMessage.Status.RECEIVED -> msg.name
+                },
+                color = if (msg.status == FlareMessage.Status.FAILED) BitcoinOrange else TextMuted,
+                fontSize = 10.sp,
+                modifier = Modifier.padding(top = 2.dp),
+            )
+        }
+    }
+}
+
+/** Decode, downscale (≤1600px) and JPEG-compress a picked photo off-main. */
+private suspend fun compressPhoto(context: android.content.Context, uri: Uri): ByteArray? =
+    withContext(Dispatchers.IO) {
+        try {
+            val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+            context.contentResolver.openInputStream(uri)?.use {
+                BitmapFactory.decodeStream(it, null, bounds)
+            }
+            var sample = 1
+            while (maxOf(bounds.outWidth, bounds.outHeight) / sample > 1600) sample *= 2
+            val opts = BitmapFactory.Options().apply { inSampleSize = sample }
+            val bitmap = context.contentResolver.openInputStream(uri)?.use {
+                BitmapFactory.decodeStream(it, null, opts)
+            } ?: return@withContext null
+            val out = ByteArrayOutputStream()
+            bitmap.compress(Bitmap.CompressFormat.JPEG, 80, out)
+            bitmap.recycle()
+            out.toByteArray()
+        } catch (_: Exception) {
+            null
+        }
+    }

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

@@ -55,7 +55,12 @@ import com.archipelago.app.ui.theme.TextPrimary
 import kotlinx.coroutines.delay
 
 @Composable
-fun IntroScreen(onContinue: () -> Unit) {
+fun IntroScreen(
+    onContinue: () -> Unit,
+    // Mesh Party works with no node at all (phone↔phone) — offered right on
+    // the first screen so a friend who just got the app can join a party.
+    onMeshParty: () -> Unit = {},
+) {
     val logoAlpha = remember { Animatable(0f) }
     var showContent by remember { mutableStateOf(false) }
 
@@ -143,6 +148,14 @@ fun IntroScreen(onContinue: () -> Unit) {
                         onClick = onContinue,
                         modifier = Modifier.fillMaxWidth().height(56.dp),
                     )
+
+                    Spacer(modifier = Modifier.height(12.dp))
+
+                    GlassButton(
+                        text = stringResource(R.string.mesh_party),
+                        onClick = onMeshParty,
+                        modifier = Modifier.fillMaxWidth().height(48.dp),
+                    )
                 }
             }
         }

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

@@ -0,0 +1,519 @@
+package com.archipelago.app.ui.screens
+
+import android.graphics.Bitmap
+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.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.statusBarsPadding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.OutlinedTextFieldDefaults
+import androidx.compose.material3.Switch
+import androidx.compose.material3.SwitchDefaults
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+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.Color
+import androidx.compose.ui.graphics.asImageBitmap
+import androidx.compose.ui.platform.LocalContext
+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.style.TextAlign
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import com.archipelago.app.fips.FipsManager
+import com.archipelago.app.fips.FipsNative
+import com.archipelago.app.fips.FipsPreferences
+import com.archipelago.app.fips.FlareClient
+import com.archipelago.app.fips.PartyPeer
+import com.archipelago.app.fips.PartyQr
+import com.archipelago.app.ui.components.CameraQrPreview
+import com.archipelago.app.ui.theme.BitcoinOrange
+import com.archipelago.app.ui.theme.SurfaceDark
+import com.archipelago.app.ui.theme.TextMuted
+import com.archipelago.app.ui.theme.TextPrimary
+import com.google.zxing.BarcodeFormat
+import com.google.zxing.EncodeHintType
+import com.google.zxing.qrcode.QRCodeWriter
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+
+private val CardBg = Color.White.copy(alpha = 0.05f)
+private val CardBorder = Color.White.copy(alpha = 0.08f)
+
+/** Public companion download (vps2 demo host — serves the same APK as the
+ *  nodes' QR link). Rendered as the "Share this app" QR. */
+private const val APP_DOWNLOAD_URL =
+    "http://146.59.87.168:2100/packages/archipelago-companion.apk"
+
+/**
+ * Mesh Party — phone↔phone FIPS pairing. Show your QR, scan theirs, and the
+ * two embedded mesh nodes link up: through anchors when there's internet,
+ * directly over any shared WiFi/hotspot when there isn't.
+ */
+@Composable
+fun PartyScreen(
+    onBack: () -> Unit,
+    onOpenChat: () -> Unit,
+) {
+    val context = LocalContext.current
+    val prefs = remember { FipsPreferences(context) }
+    val scope = rememberCoroutineScope()
+
+    var identity by remember { mutableStateOf<FipsNative.Identity?>(null) }
+    var name by remember { mutableStateOf("") }
+    var localIp by remember { mutableStateOf<String?>(null) }
+    var showScanner by remember { mutableStateOf(false) }
+    var showShareQr by remember { mutableStateOf(false) }
+    var scanHint by remember { mutableStateOf<String?>(null) }
+
+    // Camera permission — fresh installs (and reinstalls: uninstall wipes
+    // grants) land here with no CAMERA grant, and the raw preview just showed
+    // black. Ask the moment the scanner opens.
+    var hasCamera by remember {
+        mutableStateOf(
+            androidx.core.content.ContextCompat.checkSelfPermission(
+                context, android.Manifest.permission.CAMERA,
+            ) == android.content.pm.PackageManager.PERMISSION_GRANTED
+        )
+    }
+    val cameraPermLauncher = androidx.activity.compose.rememberLauncherForActivityResult(
+        androidx.activity.result.contract.ActivityResultContracts.RequestPermission()
+    ) { hasCamera = it }
+    LaunchedEffect(showScanner) {
+        if (showScanner && !hasCamera) {
+            cameraPermLauncher.launch(android.Manifest.permission.CAMERA)
+        }
+    }
+    val listenOn by prefs.partyListenFlow.collectAsState(initial = false)
+    val peers by prefs.partyPeersFlow.collectAsState(initial = emptyList())
+
+    LaunchedEffect(Unit) {
+        identity = FipsManager.ensureIdentity(prefs)
+        name = prefs.partyName()
+        // The hotspot/WiFi address can change while this screen is open
+        // (e.g. the user flips the hotspot on mid-demo) — keep it fresh.
+        while (true) {
+            localIp = withContext(Dispatchers.IO) { PartyQr.localWifiIpv4() }
+            delay(3_000)
+        }
+    }
+
+    val qrPayload = identity?.let { id ->
+        PartyQr.build(
+            npub = id.npub,
+            ula = id.address,
+            name = name.ifBlank { "Phone" },
+            ip = if (listenOn) localIp else null,
+            port = PartyQr.PARTY_UDP_PORT,
+        )
+    }
+    val qrBitmap = remember(qrPayload) { qrPayload?.let { renderQr(it) } }
+
+    BackHandler {
+        when {
+            showScanner -> showScanner = false
+            showShareQr -> showShareQr = false
+            else -> onBack()
+        }
+    }
+
+    Box(Modifier.fillMaxSize().background(SurfaceDark)) {
+        Column(
+            Modifier
+                .fillMaxSize()
+                .statusBarsPadding()
+                .verticalScroll(rememberScrollState())
+                .padding(horizontal = 24.dp, vertical = 16.dp),
+            verticalArrangement = Arrangement.spacedBy(14.dp),
+        ) {
+            Row(
+                Modifier.fillMaxWidth(),
+                verticalAlignment = Alignment.CenterVertically,
+                horizontalArrangement = Arrangement.SpaceBetween,
+            ) {
+                Text("‹ Back", color = TextMuted, fontSize = 15.sp, modifier = Modifier.clickable { onBack() }.padding(8.dp))
+                Text("MESH PARTY", color = TextPrimary, fontSize = 17.sp, fontWeight = FontWeight.SemiBold, letterSpacing = 3.sp)
+                Spacer(Modifier.size(56.dp))
+            }
+
+            // My QR card
+            Column(
+                Modifier
+                    .fillMaxWidth()
+                    .clip(RoundedCornerShape(20.dp))
+                    .background(CardBg)
+                    .border(1.dp, CardBorder, RoundedCornerShape(20.dp))
+                    .padding(18.dp),
+                horizontalAlignment = Alignment.CenterHorizontally,
+                verticalArrangement = Arrangement.spacedBy(12.dp),
+            ) {
+                qrBitmap?.let { bmp ->
+                    Box(
+                        Modifier
+                            .clip(RoundedCornerShape(16.dp))
+                            .background(Color.White)
+                            .padding(12.dp),
+                    ) {
+                        Image(
+                            bitmap = bmp.asImageBitmap(),
+                            contentDescription = "My mesh party QR",
+                            modifier = Modifier.size(220.dp),
+                        )
+                    }
+                } ?: Text("Mesh identity unavailable on this device", color = TextMuted, fontSize = 14.sp)
+
+                identity?.let {
+                    Text(
+                        it.npub.take(16) + "…" + it.npub.takeLast(6),
+                        color = TextMuted,
+                        fontSize = 12.sp,
+                        textAlign = TextAlign.Center,
+                    )
+                }
+
+                OutlinedTextField(
+                    value = name,
+                    onValueChange = {
+                        name = it.take(24)
+                        scope.launch { prefs.setPartyName(name) }
+                    },
+                    placeholder = { Text("Your name", color = TextMuted, textAlign = TextAlign.Center, modifier = Modifier.fillMaxWidth()) },
+                    modifier = Modifier.fillMaxWidth().height(56.dp),
+                    singleLine = true,
+                    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Done),
+                    textStyle = TextStyle(color = TextPrimary, fontSize = 15.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),
+                )
+
+                // Direct-link toggle (hotspot mode)
+                Row(
+                    Modifier.fillMaxWidth(),
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.SpaceBetween,
+                ) {
+                    Column(Modifier.padding(end = 12.dp)) {
+                        Text("Accept direct links", color = TextPrimary, fontSize = 15.sp, fontWeight = FontWeight.Medium)
+                        Text(
+                            when {
+                                listenOn && localIp != null -> "Dialable at $localIp:${PartyQr.PARTY_UDP_PORT} — no internet needed"
+                                listenOn -> "Waiting for a WiFi/hotspot address…"
+                                else -> "Off — mesh routes via anchors only"
+                            },
+                            color = if (listenOn) BitcoinOrange else TextMuted,
+                            fontSize = 12.sp,
+                        )
+                    }
+                    Switch(
+                        checked = listenOn,
+                        onCheckedChange = { on ->
+                            scope.launch {
+                                prefs.setPartyListen(on)
+                                FipsManager.requestMeshRestart(context)
+                            }
+                        },
+                        colors = SwitchDefaults.colors(
+                            checkedTrackColor = BitcoinOrange,
+                            checkedThumbColor = Color.White,
+                        ),
+                    )
+                }
+            }
+
+            GlassButton(
+                text = "Scan a Phone",
+                onClick = { showScanner = true },
+                modifier = Modifier.fillMaxWidth().height(56.dp),
+            )
+
+            if (peers.isNotEmpty()) {
+                Text("PARTY PEERS", color = TextMuted, fontSize = 12.sp, letterSpacing = 2.sp)
+                peers.forEach { peer ->
+                    Row(
+                        Modifier
+                            .fillMaxWidth()
+                            .clip(RoundedCornerShape(14.dp))
+                            .background(CardBg)
+                            .border(1.dp, CardBorder, RoundedCornerShape(14.dp))
+                            .clickable { onOpenChat() }
+                            .padding(horizontal = 16.dp, vertical = 12.dp),
+                        verticalAlignment = Alignment.CenterVertically,
+                        horizontalArrangement = Arrangement.SpaceBetween,
+                    ) {
+                        Column(Modifier.padding(end = 8.dp)) {
+                            Text(peer.name, color = TextPrimary, fontSize = 15.sp, fontWeight = FontWeight.Medium)
+                            Text(
+                                peer.npub.take(14) + "…" + if (peer.ip.isNotBlank()) "  ·  direct ${peer.ip}" else "  ·  via mesh",
+                                color = TextMuted,
+                                fontSize = 11.sp,
+                            )
+                        }
+                        Text(
+                            "✕",
+                            color = TextMuted,
+                            fontSize = 16.sp,
+                            modifier = Modifier.clickable {
+                                scope.launch {
+                                    prefs.removePartyPeer(peer.npub)
+                                    FipsManager.requestMeshRestart(context)
+                                }
+                            }.padding(8.dp),
+                        )
+                    }
+                }
+                GlassButton(
+                    text = "Open Flare Chat",
+                    onClick = onOpenChat,
+                    modifier = Modifier.fillMaxWidth().height(56.dp),
+                )
+            } else {
+                Text(
+                    "Scan another phone's party QR (or let them scan yours) to link your mesh nodes — works over 5G via anchors, or over any shared WiFi/hotspot with zero internet.",
+                    color = TextMuted,
+                    fontSize = 13.sp,
+                    textAlign = TextAlign.Center,
+                    modifier = Modifier.fillMaxWidth().padding(horizontal = 8.dp),
+                )
+            }
+            Spacer(Modifier.height(12.dp))
+            // Hand the app itself to a friend: shares this install's own APK
+            // through the system sheet (Quick Share/Bluetooth), so a nearby
+            // phone gets the companion with zero internet — the whole party
+            // premise.
+            GlassButton(
+                text = "Share this app",
+                onClick = { showShareQr = true },
+                modifier = Modifier.fillMaxWidth().height(48.dp),
+            )
+            Spacer(Modifier.height(12.dp))
+        }
+
+        // "Share this app" — a QR of the public download link, so the other
+        // phone scans it with its normal camera and installs over any
+        // internet. (The vps2 demo host serves the same APK the nodes do.)
+        AnimatedVisibility(visible = showShareQr, enter = fadeIn(), exit = fadeOut()) {
+            Box(
+                Modifier
+                    .fillMaxSize()
+                    .background(Color.Black.copy(alpha = 0.94f))
+                    .clickable { showShareQr = false },
+                contentAlignment = Alignment.Center,
+            ) {
+                Column(horizontalAlignment = Alignment.CenterHorizontally) {
+                    val dlQr = remember { renderQr(APP_DOWNLOAD_URL) }
+                    dlQr?.let { bmp ->
+                        Box(
+                            Modifier
+                                .clip(RoundedCornerShape(16.dp))
+                                .background(Color.White)
+                                .padding(14.dp),
+                        ) {
+                            Image(
+                                bitmap = bmp.asImageBitmap(),
+                                contentDescription = "Companion download QR",
+                                modifier = Modifier.size(240.dp),
+                            )
+                        }
+                    }
+                    Spacer(Modifier.height(18.dp))
+                    Text(
+                        "Scan with any camera to download\nthe Archipelago Companion",
+                        color = TextPrimary,
+                        fontSize = 15.sp,
+                        textAlign = TextAlign.Center,
+                    )
+                    Spacer(Modifier.height(10.dp))
+                    Text(
+                        "…or send the APK file directly",
+                        color = BitcoinOrange,
+                        fontSize = 13.sp,
+                        modifier = Modifier.clickable { shareCompanionApk(context) }.padding(8.dp),
+                    )
+                    Spacer(Modifier.height(6.dp))
+                    Text("Close", color = TextMuted, fontSize = 14.sp, modifier = Modifier.clickable { showShareQr = false }.padding(8.dp))
+                }
+            }
+        }
+
+        // Party QR scanner overlay
+        AnimatedVisibility(visible = showScanner, enter = fadeIn(), exit = fadeOut()) {
+            Box(Modifier.fillMaxSize().background(Color.Black)) {
+                if (!hasCamera) {
+                    Column(
+                        Modifier.align(Alignment.Center).padding(horizontal = 32.dp),
+                        horizontalAlignment = Alignment.CenterHorizontally,
+                        verticalArrangement = Arrangement.spacedBy(14.dp),
+                    ) {
+                        Text(
+                            "Camera access is needed to scan a party QR.",
+                            color = TextPrimary,
+                            fontSize = 15.sp,
+                            textAlign = TextAlign.Center,
+                        )
+                        GlassButton(
+                            text = "Grant camera access",
+                            onClick = { cameraPermLauncher.launch(android.Manifest.permission.CAMERA) },
+                            modifier = Modifier.fillMaxWidth().height(48.dp),
+                        )
+                    }
+                } else CameraQrPreview(onDecoded = { text ->
+                    val peer = PartyQr.parse(text)
+                    when {
+                        peer == null -> scanHint = "Not a mesh party QR"
+                        peer.npub == identity?.npub -> scanHint = "That's your own QR"
+                        else -> {
+                            showScanner = false
+                            scanHint = null
+                            scope.launch {
+                                prefs.upsertPartyPeer(peer)
+                                // Pick up the direct-dial PeerConfig (and the
+                                // listener, if ours is on) immediately.
+                                FipsManager.requestMeshRestart(context)
+                                // Pairing must be MUTUAL: announce ourselves so
+                                // the scanned phone gets us as a peer + a chat
+                                // entry without scanning back. Retried while
+                                // the fresh link/session comes up.
+                                val me = identity
+                                if (me != null) {
+                                    launch(Dispatchers.IO) {
+                                        for (attempt in 0 until 6) {
+                                            val ok = FlareClient.sendHello(
+                                                peer = peer,
+                                                myNpub = me.npub,
+                                                myName = name.ifBlank { "Phone" },
+                                                myUla = me.address,
+                                                myIp = if (listenOn) localIp else null,
+                                                myPort = PartyQr.PARTY_UDP_PORT,
+                                            )
+                                            if (ok) break
+                                            delay(3_000)
+                                        }
+                                    }
+                                }
+                                onOpenChat()
+                            }
+                        }
+                    }
+                })
+                Box(
+                    Modifier
+                        .align(Alignment.Center)
+                        .size(260.dp)
+                        .border(2.dp, BitcoinOrange.copy(alpha = 0.85f), RoundedCornerShape(20.dp)),
+                )
+                Text(
+                    "Close",
+                    color = TextPrimary,
+                    fontSize = 16.sp,
+                    modifier = Modifier
+                        .align(Alignment.TopEnd)
+                        .statusBarsPadding()
+                        .clickable { showScanner = false }
+                        .padding(20.dp),
+                )
+                scanHint?.let {
+                    Text(
+                        it,
+                        color = BitcoinOrange,
+                        fontSize = 14.sp,
+                        textAlign = TextAlign.Center,
+                        modifier = Modifier
+                            .align(Alignment.BottomCenter)
+                            .padding(bottom = 48.dp)
+                            .fillMaxWidth(),
+                    )
+                }
+            }
+        }
+    }
+
+    // Scan hints fade so the camera feels live again.
+    LaunchedEffect(scanHint) {
+        if (scanHint != null) {
+            delay(2500)
+            scanHint = null
+        }
+    }
+}
+
+/** Render a QR payload as a bitmap (dark modules on white). */
+private fun renderQr(payload: String, size: Int = 640): Bitmap? = try {
+    val matrix = QRCodeWriter().encode(
+        payload,
+        BarcodeFormat.QR_CODE,
+        size,
+        size,
+        mapOf(EncodeHintType.MARGIN to 1),
+    )
+    val pixels = IntArray(size * size)
+    for (y in 0 until size) {
+        for (x in 0 until size) {
+            pixels[y * size + x] = if (matrix[x, y]) 0xFF0A0A0A.toInt() else 0xFFFFFFFF.toInt()
+        }
+    }
+    Bitmap.createBitmap(pixels, size, size, Bitmap.Config.ARGB_8888)
+} catch (_: Exception) {
+    null
+}
+
+/** Share this install's own APK via the system share sheet — a nearby friend
+ *  gets the companion with no internet at all (Quick Share / Bluetooth). */
+private fun shareCompanionApk(context: android.content.Context) {
+    try {
+        val src = java.io.File(context.applicationInfo.sourceDir)
+        val dir = java.io.File(context.cacheDir, "share").apply { mkdirs() }
+        val out = java.io.File(dir, "archipelago-companion.apk")
+        src.copyTo(out, overwrite = true)
+        val uri = androidx.core.content.FileProvider.getUriForFile(
+            context, "${context.packageName}.fileprovider", out,
+        )
+        val send = android.content.Intent(android.content.Intent.ACTION_SEND).apply {
+            type = "application/vnd.android.package-archive"
+            putExtra(android.content.Intent.EXTRA_STREAM, uri)
+            addFlags(android.content.Intent.FLAG_GRANT_READ_URI_PERMISSION)
+        }
+        context.startActivity(
+            android.content.Intent.createChooser(send, "Share Archipelago Companion")
+                .addFlags(android.content.Intent.FLAG_ACTIVITY_NEW_TASK),
+        )
+    } catch (_: Exception) {
+        // No share targets / copy failed — nothing sensible to do here.
+    }
+}

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

@@ -37,12 +37,14 @@ 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.fips.FipsManager
 import com.archipelago.app.network.ConnectionState
 import com.archipelago.app.network.InputWebSocket
 import com.archipelago.app.ui.components.NESController
 import com.archipelago.app.ui.components.NESKeyboard
 import com.archipelago.app.ui.components.NESMenu
 import com.archipelago.app.ui.components.NESPortraitController
+import com.archipelago.app.ui.components.QrScannerOverlay
 import com.archipelago.app.ui.components.Trackpad
 import com.archipelago.app.ui.theme.BitcoinOrange
 import com.archipelago.app.ui.theme.ControllerStyle
@@ -52,7 +54,7 @@ import com.archipelago.app.ui.theme.TextMuted
 import kotlinx.coroutines.launch
 
 @Composable
-fun RemoteInputScreen(onBack: () -> Unit) {
+fun RemoteInputScreen(onBack: () -> Unit, onMeshParty: (() -> Unit)? = null) {
     val context = LocalContext.current
     val prefs = remember { ServerPreferences(context) }
     val scope = rememberCoroutineScope()
@@ -63,6 +65,7 @@ fun RemoteInputScreen(onBack: () -> Unit) {
 
     var isGamepadMode by remember { mutableStateOf(true) }
     var showModal by remember { mutableStateOf(false) }
+    var showQrScanner by remember { mutableStateOf(false) }
     var controllerStyle by remember { mutableStateOf(ControllerStyle.DARK) }
     var playerId by remember { mutableStateOf(0) }  // 0 = broadcast, 1 = P1, 2 = P2
 
@@ -169,7 +172,7 @@ fun RemoteInputScreen(onBack: () -> Unit) {
                             onMove = { dx, dy -> ws.sendMouseMove(dx, dy) },
                             onClick = { ws.sendClick(it) },
                             onScroll = { ws.sendScroll(it) },
-                            onTwoFingerHold = { showModal = true },
+                            onThreeFingerHold = { showModal = true },
                             modifier = Modifier.fillMaxWidth().weight(1f)
                                 .padding(horizontal = 16.dp, vertical = 8.dp),
                         )
@@ -216,6 +219,18 @@ fun RemoteInputScreen(onBack: () -> Unit) {
             onAddServer = { server ->
                 scope.launch { prefs.addSavedServer(server); if (activeServer == null) prefs.setActiveServer(server) }
             },
+            onScanQr = { showQrScanner = true },
+            onEditServer = { original, updated ->
+                scope.launch {
+                    prefs.updateSavedServer(original, updated)
+                    // 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)
@@ -235,6 +250,22 @@ fun RemoteInputScreen(onBack: () -> Unit) {
                 controllerStyle = if (controllerStyle == ControllerStyle.CLASSIC) ControllerStyle.DARK else ControllerStyle.CLASSIC
             },
             onBackToWebView = { showModal = false; onBack() },
+            onMeshParty = onMeshParty?.let { open -> { showModal = false; open() } },
+        )
+
+        // Pairing-QR scan launched from the menu's Add Server row. The menu stays
+        // open behind the scanner so the new entry appears as soon as it closes.
+        QrScannerOverlay(
+            visible = showQrScanner,
+            onDismiss = { showQrScanner = false },
+            onServerScanned = { scan ->
+                showQrScanner = false
+                scope.launch {
+                    val merged = prefs.upsertServer(scan.server)
+                    FipsManager.registerNode(context, scan.fips, merged.displayName())
+                    if (activeServer == null) prefs.setActiveServer(merged)
+                }
+            },
         )
     }
 }

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
@@ -42,6 +43,7 @@ import androidx.compose.material3.Switch
 import androidx.compose.material3.SwitchDefaults
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
@@ -69,8 +71,12 @@ import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
 import androidx.compose.ui.unit.sp
 import com.archipelago.app.R
+import com.archipelago.app.data.PairResult
 import com.archipelago.app.data.ServerEntry
 import com.archipelago.app.data.ServerPreferences
+import com.archipelago.app.fips.FipsManager
+import com.archipelago.app.ui.components.MeshLoadingScreen
+import com.archipelago.app.ui.components.QrScannerOverlay
 import com.archipelago.app.ui.theme.BitcoinOrange
 import com.archipelago.app.ui.theme.ErrorRed
 import com.archipelago.app.ui.theme.SurfaceBlack
@@ -80,6 +86,7 @@ import com.archipelago.app.ui.theme.TextMuted
 import com.archipelago.app.ui.theme.TextPrimary
 import com.archipelago.app.ui.theme.TextSecondary
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 import java.net.HttpURLConnection
@@ -92,6 +99,9 @@ import javax.net.ssl.X509TrustManager
 fun ServerConnectScreen(
     onConnected: (String) -> Unit,
     onRemoteInput: () -> Unit = {},
+    // Prefill from a pairing deep link (archipelago://pair) that carried no
+    // password — opens the manual form on the password prompt for that server.
+    initialServer: ServerEntry? = null,
 ) {
     val context = LocalContext.current
     val prefs = remember { ServerPreferences(context) }
@@ -106,9 +116,53 @@ 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) }
+    // Landing shows Scan/Manual choice; the form appears in manual mode or while editing.
+    var manualMode by remember { mutableStateOf(false) }
+    var showScanner by remember { mutableStateOf(false) }
 
     val savedServers by prefs.savedServers.collectAsState(initial = emptyList())
 
+    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()) {
@@ -119,10 +173,35 @@ fun ServerConnectScreen(
         errorMessage = null
 
         scope.launch {
-            val result = testConnection(server)
+            var reachable = testConnection(server)
+
+            // LAN address didn't answer — phone off-LAN (5G) or DHCP moved the
+            // node. The scanned IP was only ever a dial hint; the node's real
+            // identity is its npub and its ULA is reachable from anywhere over
+            // the mesh. Bring the tunnel up and probe the ULA before failing.
+            if (!reachable && server.meshIp.isNotBlank()) {
+                FipsManager.autoStartIfReady(context)
+                val meshServer = server.copy(
+                    address = server.meshIp,
+                    useHttps = false,
+                    port = "",
+                )
+                // Mesh discovery + first session can take 15s+ through the
+                // public tree (HANDOFF-2026-07-23 node diagnosis), and on a
+                // first-ever pairing the VPN consent dialog is on screen at
+                // the same time — so probe patiently inside a 60s budget with
+                // per-attempt timeouts wide enough to ride out TCP
+                // retransmit backoff. The VPN service pre-warms the session
+                // in parallel (ArchyVpnService.startSessionWarmer).
+                val deadline = System.currentTimeMillis() + 60_000
+                while (!reachable && System.currentTimeMillis() < deadline) {
+                    reachable = testConnection(meshServer, timeoutMs = 15_000)
+                    if (!reachable) delay(3000)
+                }
+            }
             isConnecting = false
 
-            if (result) {
+            if (reachable) {
                 prefs.setActiveServer(server)
                 onConnected(server.toUrl())
             } else {
@@ -131,6 +210,39 @@ fun ServerConnectScreen(
         }
     }
 
+    fun prefill(server: ServerEntry) {
+        name = server.name
+        address = server.address
+        port = server.port
+        password = server.password
+        useHttps = server.useHttps
+    }
+
+    // Pairing QR scanned: dedupe against saved servers, then either auto-connect
+    // (payload carried a credential — demo password or a real node's device
+    // token) or land on the password prompt with everything else filled in.
+    // Mesh info (when present) is registered so the FIPS tunnel comes up too.
+    fun onQrScanned(scan: PairResult.Success) {
+        showScanner = false
+        scope.launch {
+            val merged = prefs.upsertServer(scan.server)
+            FipsManager.registerNode(context, scan.fips, merged.displayName())
+            prefill(merged)
+            if (merged.password.isNotBlank()) {
+                connect(merged)
+            } else {
+                manualMode = true
+            }
+        }
+    }
+
+    LaunchedEffect(initialServer) {
+        if (initialServer != null) {
+            prefill(prefs.upsertServer(initialServer))
+            manualMode = true
+        }
+    }
+
     Box(
         modifier = Modifier
             .fillMaxSize()
@@ -166,7 +278,10 @@ fun ServerConnectScreen(
                 .padding(horizontal = 24.dp)
                 .padding(top = 48.dp, bottom = 32.dp),
             horizontalAlignment = Alignment.CenterHorizontally,
-            verticalArrangement = Arrangement.spacedBy(16.dp),
+            // Center the content vertically — the landing (logo + two buttons) is
+            // short and looks stranded at the top otherwise. Taller content (the
+            // manual form, saved servers) still scrolls from the top as normal.
+            verticalArrangement = Arrangement.spacedBy(16.dp, Alignment.CenterVertically),
         ) {
             // Circular badge logo
             Image(
@@ -178,14 +293,16 @@ fun ServerConnectScreen(
             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,
             )
 
+            val showForm = manualMode || editingServer != null
+
             Text(
-                text = stringResource(R.string.server_address_hint),
+                text = if (showForm) stringResource(R.string.server_address_hint) else stringResource(R.string.connect_landing_hint),
                 style = MaterialTheme.typography.bodyMedium,
                 color = TextMuted,
                 textAlign = TextAlign.Center,
@@ -193,8 +310,25 @@ fun ServerConnectScreen(
 
             Spacer(modifier = Modifier.height(4.dp))
 
+            if (!showForm) {
+                // Landing: scan the pairing QR, or fall back to manual entry
+                GlassButton(
+                    text = stringResource(R.string.scan_node_qr),
+                    onClick = { showScanner = true },
+                    modifier = Modifier.fillMaxWidth().height(56.dp),
+                )
+                GlassButton(
+                    text = stringResource(R.string.enter_manually),
+                    onClick = {
+                        errorMessage = null
+                        manualMode = true
+                    },
+                    modifier = Modifier.fillMaxWidth().height(56.dp),
+                )
+            }
+
             // Glass card with form
-            Box(
+            if (showForm) Box(
                 modifier = Modifier
                     .fillMaxWidth()
                     .clip(RoundedCornerShape(16.dp))
@@ -324,7 +458,11 @@ fun ServerConnectScreen(
                             keyboardActions = KeyboardActions(
                                 onGo = {
                                     keyboard?.hide()
-                                    connect(ServerEntry(address, useHttps, port, password, name))
+                                    if (editingServer != null) {
+                                        saveEdit()
+                                    } else {
+                                        connect(ServerEntry(address, useHttps, port, password, name))
+                                    }
                                 },
                             ),
                             colors = OutlinedTextFieldDefaults.colors(
@@ -389,15 +527,54 @@ 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, name))
-                },
-                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 if (manualMode) {
+                // Back to the Scan/Manual landing + Connect
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalArrangement = Arrangement.spacedBy(12.dp),
+                ) {
+                    GlassButton(
+                        text = stringResource(R.string.back),
+                        onClick = {
+                            keyboard?.hide()
+                            manualMode = false
+                            clearForm()
+                        },
+                        modifier = Modifier.weight(1f).height(56.dp),
+                    )
+                    GlassButton(
+                        text = if (isConnecting) stringResource(R.string.connecting) else stringResource(R.string.connect),
+                        onClick = {
+                            keyboard?.hide()
+                            connect(ServerEntry(address, useHttps, port, password, name))
+                        },
+                        modifier = Modifier.weight(2f).height(56.dp),
+                    )
+                }
+            }
 
             if (isConnecting) {
                 CircularProgressIndicator(
@@ -407,8 +584,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),
@@ -422,11 +599,26 @@ fun ServerConnectScreen(
                     SavedServerItem(
                         server = server,
                         onConnect = { connect(it) },
+                        onEdit = { startEdit(it) },
                         onRemove = { scope.launch { prefs.removeSavedServer(it) } },
                     )
                 }
             }
         }
+
+        QrScannerOverlay(
+            visible = showScanner,
+            onDismiss = { showScanner = false },
+            onServerScanned = { onQrScanned(it) },
+        )
+
+        // Full-screen branded loader while the first connect runs — most
+        // visibly right after a pairing-QR scan, when the mesh may still be
+        // establishing (LAN probe → tunnel up → ULA probe can take a while).
+        // The small inline spinner stays for context; this owns the screen.
+        if (isConnecting) {
+            MeshLoadingScreen()
+        }
     }
 }
 
@@ -434,6 +626,7 @@ fun ServerConnectScreen(
 private fun SavedServerItem(
     server: ServerEntry,
     onConnect: (ServerEntry) -> Unit,
+    onEdit: (ServerEntry) -> Unit,
     onRemove: (ServerEntry) -> Unit,
 ) {
     Row(
@@ -476,6 +669,9 @@ private fun SavedServerItem(
                 }
             }
         }
+        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)
         }
@@ -490,8 +686,10 @@ private fun sanitizeAddress(input: String): String {
         .trimEnd('/')
 }
 
-/** Test RPC connectivity. Accepts self-signed certs for local LAN servers. */
-private suspend fun testConnection(server: ServerEntry): Boolean {
+/** Test RPC connectivity. Accepts self-signed certs for local LAN servers.
+ *  [timeoutMs] is per-phase (connect / read) — mesh probes need far more
+ *  patience than LAN ones (first session through the tree can take 15s+). */
+private suspend fun testConnection(server: ServerEntry, timeoutMs: Int = 5000): Boolean {
     return withContext(Dispatchers.IO) {
         try {
             val url = URL("${server.toUrl()}/rpc/v1")
@@ -511,8 +709,8 @@ private suspend fun testConnection(server: ServerEntry): Boolean {
             }
 
             connection.requestMethod = "POST"
-            connection.connectTimeout = 5000
-            connection.readTimeout = 5000
+            connection.connectTimeout = timeoutMs
+            connection.readTimeout = timeoutMs
             connection.setRequestProperty("Content-Type", "application/json")
             connection.doOutput = true
             val body = """{"method":"server.echo","params":{"message":"ping"}}"""

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

@@ -1,10 +1,13 @@
 package com.archipelago.app.ui.screens
 
+import android.Manifest
 import android.annotation.SuppressLint
+import android.content.pm.PackageManager
 import android.graphics.Bitmap
 import android.graphics.BitmapFactory
 import android.view.ViewGroup
 import android.webkit.CookieManager
+import android.webkit.PermissionRequest
 import android.webkit.WebChromeClient
 import android.webkit.WebResourceError
 import android.webkit.WebResourceRequest
@@ -12,6 +15,9 @@ import android.webkit.WebSettings
 import android.webkit.WebView
 import android.webkit.WebViewClient
 import androidx.activity.compose.BackHandler
+import androidx.activity.compose.rememberLauncherForActivityResult
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.core.content.ContextCompat
 import androidx.compose.animation.AnimatedVisibility
 import androidx.compose.animation.fadeIn
 import androidx.compose.animation.fadeOut
@@ -29,8 +35,10 @@ 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.statusBars
 import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.layout.windowInsetsPadding
+import androidx.compose.foundation.layout.windowInsetsTopHeight
 import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.automirrored.filled.ArrowBack
@@ -47,28 +55,46 @@ import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableIntStateOf
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
 import androidx.compose.runtime.setValue
+import androidx.compose.runtime.snapshotFlow
 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.SpanStyle
+import androidx.compose.ui.text.buildAnnotatedString
+import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.style.TextAlign
 import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.text.withStyle
 import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
 import androidx.compose.ui.viewinterop.AndroidView
+import android.webkit.ValueCallback
 import com.archipelago.app.R
+import com.archipelago.app.data.ServerPreferences
+import com.archipelago.app.ui.components.GestureHintOverlay
+import com.archipelago.app.ui.components.MeshLoadingScreen
+import com.archipelago.app.ui.components.WalletQrScannerModal
 import com.archipelago.app.ui.theme.BitcoinOrange
+import com.archipelago.app.ui.theme.ErrorRed
 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.delay
+import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
+import org.json.JSONObject
 
 /** Open a URL in the phone's default browser (genuinely external links). */
 private fun openExternalUrl(context: android.content.Context, url: String) {
@@ -98,6 +124,82 @@ private fun isSameHost(url: String, base: String): Boolean {
     }
 }
 
+/** Kiosk WebView retained across navigation (remote ⇄ dashboard) so leaving
+ *  the kiosk and coming back reattaches the LIVE page — no reload, no
+ *  re-login, no reconnect. Dropped on retry/disconnect/server change. */
+private object KioskWebView {
+    var instance: WebView? = null
+    var url: String? = null
+
+    // Live-composition delegates for the JS bridges (see the factory) — the
+    // registered interface objects call through these, so reattaching the
+    // retained view re-points them instead of leaving stale closures.
+    var onRouteOutbound: (String) -> Unit = {}
+    var onOpenInApp: (String) -> Unit = {}
+    var onQrOpen: () -> Unit = {}
+    var onQrStatus: (String, Boolean) -> Unit = { _, _ -> }
+    var onQrClose: () -> Unit = {}
+
+    fun drop() {
+        instance?.let {
+            (it.parent as? ViewGroup)?.removeView(it)
+            it.destroy()
+        }
+        instance = null
+        url = null
+    }
+}
+
+/** Inject the safe-area CSS vars from the CURRENT window insets. Android
+ *  WebView doesn't populate env(safe-area-inset-*); worse, on a cold start
+ *  onPageFinished can run before the view is attached — rootWindowInsets is
+ *  null then, and injecting 0px collapsed the UI's top/bottom margins (and
+ *  put the tab bar inside the gesture zone, killing its taps). Called from
+ *  onPageFinished, from the window-insets listener (fires when real insets
+ *  arrive), and on reattach. */
+private fun injectSafeAreaVars(view: WebView) {
+    val insets = view.rootWindowInsets ?: return // listener re-fires when real
+    val density = view.resources.displayMetrics.density
+    val sat = (insets.getInsets(android.view.WindowInsets.Type.statusBars()).top / density).toInt()
+    val sab = (insets.getInsets(android.view.WindowInsets.Type.navigationBars()).bottom / density).toInt()
+    view.evaluateJavascript(
+        """
+        (function() {
+            var style = document.getElementById('archipelago-android-insets');
+            if (!style) {
+                style = document.createElement('style');
+                style.id = 'archipelago-android-insets';
+                document.head.appendChild(style);
+            }
+            style.textContent = ':root { --safe-area-top: ${sat}px; --safe-area-bottom: ${sab}px; }';
+        })();
+        """.trimIndent(),
+        null,
+    )
+}
+
+/** True when a TCP listener answers at [base]'s host:port within [timeoutMs]. */
+private fun tcpAnswers(base: String, timeoutMs: Int): Boolean = try {
+    val u = android.net.Uri.parse(base)
+    val port = if (u.port != -1) u.port else if (u.scheme == "https") 443 else 80
+    java.net.Socket().use {
+        it.connect(java.net.InetSocketAddress(u.host, port), timeoutMs)
+        true
+    }
+} catch (_: Exception) {
+    false
+}
+
+/** Fastest answering origin: LAN inside a short window, else the mesh ULA
+ *  (patient — a cold session may still be establishing), else LAN anyway so
+ *  the existing error/fallback path handles it. */
+private suspend fun pickStartUrl(lanUrl: String, meshUrl: String?): String =
+    withContext(Dispatchers.IO) {
+        if (tcpAnswers(lanUrl, 2500)) return@withContext lanUrl
+        if (meshUrl != null && tcpAnswers(meshUrl, 12_000)) return@withContext meshUrl
+        lanUrl
+    }
+
 /** 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. */
@@ -136,17 +238,109 @@ fun WebViewScreen(
     serverUrl: String,
     onDisconnect: () -> Unit,
     onRemoteInput: () -> Unit = {},
+    // Stored password for this server (from QR pairing or manual entry). When
+    // non-blank, the login page is auto-filled and submitted — the one-step
+    // demo flow from docs/companion-pairing-qr.md.
+    serverPassword: String = "",
+    // Node's FIPS mesh URL (http://[fd…]). When the primary address fails on
+    // a main-frame load — typically the phone left the LAN — retry there
+    // before surfacing the error page: the mesh tunnel works from anywhere.
+    meshFallbackUrl: String? = null,
 ) {
     var isLoading by remember { mutableStateOf(true) }
+    // First kiosk load (often over the FIPS mesh) gets the full branded
+    // loader; later navigations keep just the slim top progress bar.
+    var firstLoadDone by remember { mutableStateOf(false) }
+    LaunchedEffect(Unit) {
+        snapshotFlow { isLoading }.first { !it }
+        firstLoadDone = true
+    }
     var loadProgress by remember { mutableIntStateOf(0) }
+    var triedMeshFallback by remember { mutableStateOf(false) }
     var hasError by remember { mutableStateOf(false) }
     var webView by remember { mutableStateOf<WebView?>(null) }
 
+    // Race LAN vs mesh BEFORE the WebView exists: Chromium pointed at an
+    // unreachable LAN IP burns a minute+ in connect retries before
+    // onReceivedError fires the mesh fallback — the "stuck connecting"
+    // stall. A raw TCP probe answers in milliseconds at home and fails in
+    // ~2.5s off-LAN, so startup lands on the right origin in seconds.
+    var startUrl by remember(serverUrl) { mutableStateOf<String?>(null) }
+    var raceNonce by remember { mutableIntStateOf(0) }
+    LaunchedEffect(serverUrl, meshFallbackUrl, raceNonce) {
+        // A retained live session exists — reattach instantly: no race, no
+        // reload, no re-login (remote ⇄ dashboard round trip).
+        if (KioskWebView.instance != null && KioskWebView.url == serverUrl) {
+            isLoading = false
+            startUrl = serverUrl
+            return@LaunchedEffect
+        }
+        val picked = pickStartUrl(serverUrl, meshFallbackUrl)
+        // Starting on the mesh: don't bounce back to it on error (it IS it).
+        if (picked != serverUrl) triedMeshFallback = true
+        startUrl = picked
+    }
+
+    // Web-page camera access (wallet QR scanner). The WebView's default
+    // WebChromeClient silently denies getUserMedia, so grant video capture —
+    // asking for the app-level CAMERA permission first when needed.
+    val webViewContext = LocalContext.current
+    var pendingWebPermission by remember { mutableStateOf<PermissionRequest?>(null) }
+    val webCameraPermissionLauncher = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission(),
+    ) { granted ->
+        pendingWebPermission?.let { req ->
+            if (granted) req.grant(arrayOf(PermissionRequest.RESOURCE_VIDEO_CAPTURE)) else req.deny()
+        }
+        pendingWebPermission = null
+    }
+
     // 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) }
 
+    // Same node = EITHER of its addresses. Over the mesh the kiosk's host is
+    // the ULA while app links may carry the LAN IP (and vice versa) —
+    // comparing against one host bounced same-node apps (Pine, Home
+    // Assistant, BTCPay) out to the phone's external browser.
+    fun isSameNode(url: String): Boolean =
+        isSameHost(url, serverUrl) ||
+            (meshFallbackUrl != null && isSameHost(url, meshFallbackUrl))
+
+    // Native wallet QR scanner, opened by the web UI via the ArchipelagoQr
+    // bridge; status lines stream back from the page while it's up.
+    var walletScannerVisible by remember { mutableStateOf(false) }
+    var walletScannerStatus by remember { mutableStateOf<Pair<String, Boolean>?>(null) }
+
+    // One-time three-finger-hold teaching overlay (initial=true: never flash
+    // it while DataStore is still loading).
+    val prefs = remember { ServerPreferences(webViewContext) }
+    val gestureHintSeen by prefs.gestureHintSeen.collectAsState(initial = true)
+    var gestureHintDismissed by remember { mutableStateOf(false) }
+    // Don't teach the gesture on top of the login/splash — arm the overlay
+    // ~2 minutes after the kiosk first finishes loading, once the user has
+    // settled in.
+    var gestureHintReady by remember { mutableStateOf(false) }
+    LaunchedEffect(Unit) {
+        snapshotFlow { isLoading }.first { !it }
+        delay(120_000)
+        gestureHintReady = true
+    }
+    val scope = rememberCoroutineScope()
+
+    // <input type="file"> support — without a chooser implementation the
+    // WebView silently ignores file inputs (broke the wallet's upload path).
+    var pendingFileChooser by remember { mutableStateOf<ValueCallback<Array<android.net.Uri>>?>(null) }
+    val fileChooserLauncher = rememberLauncherForActivityResult(
+        ActivityResultContracts.StartActivityForResult(),
+    ) { result ->
+        pendingFileChooser?.onReceiveValue(
+            WebChromeClient.FileChooserParams.parseResult(result.resultCode, result.data),
+        )
+        pendingFileChooser = null
+    }
+
     BackHandler(enabled = inAppUrl == null && webView?.canGoBack() == true) {
         webView?.goBack()
     }
@@ -195,9 +389,16 @@ fun WebViewScreen(
                 GlassButton(
                     text = stringResource(R.string.retry),
                     onClick = {
+                        // Re-race LAN vs mesh — the network we're on may have
+                        // changed since the last pick. Drop the retained view:
+                        // an errored session must genuinely reload.
+                        KioskWebView.drop()
+                        webView = null
                         hasError = false
                         isLoading = true
-                        webView?.loadUrl(serverUrl)
+                        triedMeshFallback = false
+                        startUrl = null
+                        raceNonce++
                     },
                     modifier = Modifier.fillMaxWidth().height(56.dp),
                 )
@@ -206,17 +407,33 @@ fun WebViewScreen(
 
                 GlassButton(
                     text = stringResource(R.string.disconnect),
-                    onClick = onDisconnect,
+                    onClick = {
+                        KioskWebView.drop()
+                        onDisconnect()
+                    },
                     modifier = Modifier.fillMaxWidth().height(48.dp),
                 )
             }
+        } else if (startUrl == null) {
+            // Racing LAN vs mesh (≤2.5s at home, a few seconds off-LAN) —
+            // far cheaper than letting Chromium retry a dead LAN IP.
+            MeshLoadingScreen()
         } else {
             // Edge-to-edge WebView — background bleeds behind status bar.
             // Safe area values injected as CSS env() polyfill on each page load.
+            val initialUrl = startUrl ?: serverUrl
             AndroidView(
                 modifier = Modifier.fillMaxSize(),
                 factory = { context ->
-                    WebView(context).apply {
+                    // Reattach the retained kiosk WebView (remote ⇄ dashboard
+                    // must not reload the node UI). Everything configured
+                    // below is idempotent, and re-running it rebinds clients,
+                    // bridges and listeners to THIS composition's state —
+                    // stale closures from the previous visit are replaced.
+                    if (KioskWebView.url != serverUrl) KioskWebView.drop()
+                    val reused = KioskWebView.instance
+                    (reused ?: WebView(context)).apply {
+                        (parent as? ViewGroup)?.removeView(this)
                         layoutParams = ViewGroup.LayoutParams(
                             ViewGroup.LayoutParams.MATCH_PARENT,
                             ViewGroup.LayoutParams.MATCH_PARENT,
@@ -240,38 +457,90 @@ fun WebViewScreen(
 
                         val webViewRef = this
 
+                        // Re-inject the safe-area vars whenever REAL insets
+                        // arrive — on cold start onPageFinished often beats
+                        // window attachment and would otherwise bake in 0px.
+                        setOnApplyWindowInsetsListener { v, insets ->
+                            (v as? WebView)?.let { injectSafeAreaVars(it) }
+                            v.onApplyWindowInsets(insets)
+                        }
+
                         // 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)) {
+                            if (isSameNode(url)) {
                                 inAppUrl = url
                             } else {
                                 openExternalUrl(context, url)
                             }
                         }
 
+                        // Bridge callbacks are DELEGATED through the holder:
+                        // the interface objects registered on a retained
+                        // WebView survive recomposition, and re-registering
+                        // them doesn't reliably swap the JS-visible object
+                        // without a reload — with direct closures, a
+                        // remote ⇄ dashboard round trip left the bridges
+                        // writing to a dead composition's state ("apps don't
+                        // launch"). These assignments re-point the live
+                        // interface objects at THIS composition every attach.
+                        KioskWebView.onRouteOutbound = { url -> routeOutbound(url) }
+                        KioskWebView.onOpenInApp = { url -> inAppUrl = url }
+                        KioskWebView.onQrOpen = {
+                            walletScannerStatus = null
+                            walletScannerVisible = true
+                        }
+                        KioskWebView.onQrStatus = { msg, err -> walletScannerStatus = msg to err }
+                        KioskWebView.onQrClose = { walletScannerVisible = false }
+
                         // 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(
+                        if (reused == null) addJavascriptInterface(
                             object {
                                 @android.webkit.JavascriptInterface
                                 fun openExternal(url: String) {
-                                    webViewRef.post { routeOutbound(url) }
+                                    webViewRef.post { KioskWebView.onRouteOutbound(url) }
                                 }
 
                                 @android.webkit.JavascriptInterface
                                 fun openInApp(url: String) {
-                                    webViewRef.post { inAppUrl = url }
+                                    webViewRef.post { KioskWebView.onOpenInApp(url) }
                                 }
                             },
                             "ArchipelagoNative",
                         )
 
+                        // Wallet QR bridge. The web scan modal calls:
+                        //   window.ArchipelagoQr.open()             — show the native scanner
+                        //   window.ArchipelagoQr.setStatus(msg, e)  — mirror status/progress lines
+                        //   window.ArchipelagoQr.close()            — code accepted, tear down
+                        // Decodes flow back through window.__archyQrResult(text);
+                        // a user cancel calls window.__archyQrCancelled().
+                        if (reused == null) addJavascriptInterface(
+                            object {
+                                @android.webkit.JavascriptInterface
+                                fun open() {
+                                    webViewRef.post { KioskWebView.onQrOpen() }
+                                }
+
+                                @android.webkit.JavascriptInterface
+                                fun setStatus(message: String, isError: Boolean) {
+                                    webViewRef.post { KioskWebView.onQrStatus(message, isError) }
+                                }
+
+                                @android.webkit.JavascriptInterface
+                                fun close() {
+                                    webViewRef.post { KioskWebView.onQrClose() }
+                                }
+                            },
+                            "ArchipelagoQr",
+                        )
+
                         webViewClient = object : WebViewClient() {
                             override fun onPageStarted(view: WebView?, url: String?, favicon: Bitmap?) {
                                 isLoading = true
@@ -282,34 +551,18 @@ fun WebViewScreen(
                                 isLoading = false
                                 if (view == null) return
 
-                                // Convert physical pixels → CSS pixels
-                                val density = view.resources.displayMetrics.density
-                                val satPx = view.rootWindowInsets
-                                    ?.getInsets(android.view.WindowInsets.Type.statusBars())
-                                    ?.top ?: 0
-                                val sabPx = view.rootWindowInsets
-                                    ?.getInsets(android.view.WindowInsets.Type.navigationBars())
-                                    ?.bottom ?: 0
-                                val sat = (satPx / density).toInt()
-                                val sab = (sabPx / density).toInt()
+                                injectSafeAreaVars(view)
 
-                                // Android WebView doesn't populate env(safe-area-inset-*).
-                                // Set CSS custom properties the web UI can use as fallback:
-                                //   var(--safe-area-top, env(safe-area-inset-top, 0px))
-                                view.evaluateJavascript(
-                                    """
-                                    (function() {
-                                        var style = document.getElementById('archipelago-android-insets');
-                                        if (!style) {
-                                            style = document.createElement('style');
-                                            style.id = 'archipelago-android-insets';
-                                            document.head.appendChild(style);
-                                        }
-                                        style.textContent = ':root { --safe-area-top: ${sat}px; --safe-area-bottom: ${sab}px; }';
-                                    })();
-                                    """.trimIndent(),
-                                    null,
-                                )
+                                // Auto-login with the stored password (QR pairing /
+                                // saved server) — only on our own server's pages
+                                // (LAN origin or the mesh address).
+                                val onOwnServer = url != null && (
+                                    url.startsWith(serverUrl) ||
+                                        (meshFallbackUrl != null && url.startsWith(meshFallbackUrl))
+                                    )
+                                if (serverPassword.isNotBlank() && onOwnServer) {
+                                    view.evaluateJavascript(buildAutoLoginScript(serverPassword), null)
+                                }
                             }
 
                             override fun onReceivedError(
@@ -318,11 +571,40 @@ fun WebViewScreen(
                                 error: WebResourceError?,
                             ) {
                                 if (request?.isForMainFrame == true) {
+                                    val mesh = meshFallbackUrl
+                                    if (mesh != null && !triedMeshFallback &&
+                                        request.url?.toString()?.startsWith(mesh) != true
+                                    ) {
+                                        triedMeshFallback = true
+                                        isLoading = true
+                                        view?.loadUrl(mesh)
+                                        return
+                                    }
                                     hasError = true
                                     isLoading = false
                                 }
                             }
 
+                            // 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 && isSameNode(u)) {
+                                    handler?.proceed()
+                                } else {
+                                    handler?.cancel()
+                                }
+                            }
+
                             override fun shouldOverrideUrlLoading(
                                 view: WebView?,
                                 request: WebResourceRequest?,
@@ -330,6 +612,8 @@ fun WebViewScreen(
                                 val url = request?.url?.toString() ?: return false
                                 // Keep kiosk navigation (same origin incl. port) in place
                                 if (url.startsWith(serverUrl)) return false
+                                // Mesh address is the same server too
+                                if (meshFallbackUrl != null && url.startsWith(meshFallbackUrl)) return false
                                 // Same node (other port) → in-app; external → browser
                                 routeOutbound(url)
                                 return true
@@ -341,6 +625,46 @@ fun WebViewScreen(
                                 loadProgress = newProgress
                             }
 
+                            override fun onShowFileChooser(
+                                view: WebView?,
+                                filePathCallback: ValueCallback<Array<android.net.Uri>>?,
+                                fileChooserParams: FileChooserParams?,
+                            ): Boolean {
+                                pendingFileChooser?.onReceiveValue(null)
+                                pendingFileChooser = filePathCallback
+                                val intent = fileChooserParams?.createIntent()
+                                if (intent == null) {
+                                    pendingFileChooser = null
+                                    return false
+                                }
+                                return try {
+                                    fileChooserLauncher.launch(intent)
+                                    true
+                                } catch (_: Exception) {
+                                    pendingFileChooser = null
+                                    false
+                                }
+                            }
+
+                            // Wallet QR scanner: grant the page camera access.
+                            // Only video capture is granted — anything else the
+                            // page asks for is denied as before.
+                            override fun onPermissionRequest(request: PermissionRequest) {
+                                if (PermissionRequest.RESOURCE_VIDEO_CAPTURE !in request.resources) {
+                                    request.deny()
+                                    return
+                                }
+                                val hasCamera = ContextCompat.checkSelfPermission(
+                                    webViewContext, Manifest.permission.CAMERA,
+                                ) == PackageManager.PERMISSION_GRANTED
+                                if (hasCamera) {
+                                    request.grant(arrayOf(PermissionRequest.RESOURCE_VIDEO_CAPTURE))
+                                } else {
+                                    pendingWebPermission = request
+                                    webCameraPermissionLauncher.launch(Manifest.permission.CAMERA)
+                                }
+                            }
+
                             // 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.
@@ -377,22 +701,24 @@ fun WebViewScreen(
                             }
                         }
 
-                        // Two-finger hold (500ms) → navigate to remote input
-                        var twoFingerStart = 0L
-                        var twoFingerFired = false
+                        // Three-finger hold (500ms) → navigate to remote input.
+                        // Three fingers, not two: two-finger scroll/pinch on the
+                        // page collided with the old two-finger hold.
+                        var threeFingerStart = 0L
+                        var threeFingerFired = false
                         setOnTouchListener { _, event ->
                             val pointerCount = event.pointerCount
                             when (event.actionMasked) {
                                 android.view.MotionEvent.ACTION_POINTER_DOWN -> {
-                                    if (pointerCount >= 2) {
-                                        twoFingerStart = System.currentTimeMillis()
-                                        twoFingerFired = false
+                                    if (pointerCount >= 3) {
+                                        threeFingerStart = System.currentTimeMillis()
+                                        threeFingerFired = false
                                     }
                                 }
                                 android.view.MotionEvent.ACTION_MOVE -> {
-                                    if (pointerCount >= 2 && !twoFingerFired && twoFingerStart > 0) {
-                                        if (System.currentTimeMillis() - twoFingerStart > 500) {
-                                            twoFingerFired = true
+                                    if (pointerCount >= 3 && !threeFingerFired && threeFingerStart > 0) {
+                                        if (System.currentTimeMillis() - threeFingerStart > 500) {
+                                            threeFingerFired = true
                                             onRemoteInput()
                                         }
                                     }
@@ -400,8 +726,8 @@ fun WebViewScreen(
                                 android.view.MotionEvent.ACTION_UP,
                                 android.view.MotionEvent.ACTION_POINTER_UP,
                                 android.view.MotionEvent.ACTION_CANCEL -> {
-                                    if (event.pointerCount <= 2) {
-                                        twoFingerStart = 0L
+                                    if (event.pointerCount <= 3) {
+                                        threeFingerStart = 0L
                                     }
                                 }
                             }
@@ -409,7 +735,21 @@ fun WebViewScreen(
                         }
 
                         webView = this
-                        loadUrl(serverUrl)
+                        if (reused == null) {
+                            KioskWebView.instance = this
+                            KioskWebView.url = serverUrl
+                            loadUrl(initialUrl)
+                        } else {
+                            // Reattached views keep stale measurements until an
+                            // input event — that was the top/bottom UI being
+                            // wrong until a tap. Force a fresh pass, and re-sync
+                            // the page's safe-area vars while we're at it.
+                            post {
+                                requestLayout()
+                                invalidate()
+                                injectSafeAreaVars(this)
+                            }
+                        }
                     }
                 },
             )
@@ -428,15 +768,81 @@ fun WebViewScreen(
                 )
             }
 
+            // Branded first-load screen while the mesh session comes up.
+            AnimatedVisibility(
+                visible = isLoading && !firstLoadDone,
+                enter = fadeIn(),
+                exit = fadeOut(),
+            ) {
+                Column(
+                    Modifier.fillMaxSize().background(SurfaceBlack),
+                    horizontalAlignment = Alignment.CenterHorizontally,
+                    verticalArrangement = Arrangement.Center,
+                ) {
+                    Text(
+                        buildAnnotatedString {
+                            withStyle(SpanStyle(color = ErrorRed)) { append("F*CK") }
+                            withStyle(SpanStyle(color = TextPrimary)) { append(" IPS") }
+                        },
+                        fontSize = 40.sp,
+                        fontWeight = FontWeight.Black,
+                        letterSpacing = 4.sp,
+                        textAlign = TextAlign.Center,
+                    )
+                    Spacer(Modifier.height(10.dp))
+                    Text(
+                        "connecting to your archipelago",
+                        color = TextMuted,
+                        fontSize = 13.sp,
+                        letterSpacing = 1.sp,
+                    )
+                    Spacer(Modifier.height(28.dp))
+                    CircularProgressIndicator(color = BitcoinOrange)
+                }
+            }
+
             // 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,
+                    meshUrl = meshFallbackUrl,
                     onClose = { inAppUrl = null },
                 )
             }
+
+            // Native wallet QR scanner, opened by the page via ArchipelagoQr.
+            WalletQrScannerModal(
+                visible = walletScannerVisible,
+                status = walletScannerStatus,
+                onDecoded = { text ->
+                    webView?.evaluateJavascript(
+                        "window.__archyQrResult && window.__archyQrResult(${JSONObject.quote(text)})",
+                        null,
+                    )
+                },
+                onDismiss = {
+                    walletScannerVisible = false
+                    webView?.evaluateJavascript(
+                        "window.__archyQrCancelled && window.__archyQrCancelled()",
+                        null,
+                    )
+                },
+            )
+
+            // First-launch teaching overlay for the three-finger hold — armed
+            // ~2 minutes after login so it never fights the splash/first look.
+            if (gestureHintReady && !gestureHintSeen && !gestureHintDismissed &&
+                !isLoading && inAppUrl == null
+            ) {
+                GestureHintOverlay(
+                    onDismiss = {
+                        gestureHintDismissed = true
+                        scope.launch { prefs.markGestureHintSeen() }
+                    },
+                )
+            }
         }
     }
 }
@@ -475,9 +881,14 @@ private fun fetchFavicon(pageUrl: String): Bitmap? {
 private fun InAppBrowser(
     url: String,
     serverUrl: String,
+    meshUrl: String? = null,
     onClose: () -> Unit,
 ) {
     val context = LocalContext.current
+    // Same-node check across BOTH node addresses (LAN + mesh ULA) — see the
+    // kiosk's isSameNode; a mismatch here bounced app links to the browser.
+    fun isSameNode(u: String): Boolean =
+        isSameHost(u, serverUrl) || (meshUrl != null && isSameHost(u, meshUrl))
     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) }
@@ -486,6 +897,18 @@ private fun InAppBrowser(
     var canGoBack by remember { mutableStateOf(false) }
     var canGoForward by remember { mutableStateOf(false) }
 
+    // Same camera bridge as the main WebView — node apps opened in the overlay
+    // (e.g. anything with a QR scanner) get getUserMedia too.
+    var pendingWebPermission by remember { mutableStateOf<PermissionRequest?>(null) }
+    val webCameraPermissionLauncher = rememberLauncherForActivityResult(
+        ActivityResultContracts.RequestPermission(),
+    ) { granted ->
+        pendingWebPermission?.let { req ->
+            if (granted) req.grant(arrayOf(PermissionRequest.RESOURCE_VIDEO_CAPTURE)) else req.deny()
+        }
+        pendingWebPermission = null
+    }
+
     // 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
@@ -535,6 +958,22 @@ private fun InAppBrowser(
                             override fun onReceivedIcon(view: WebView?, icon: Bitmap?) {
                                 if (icon != null) favicon = icon
                             }
+
+                            override fun onPermissionRequest(request: PermissionRequest) {
+                                if (PermissionRequest.RESOURCE_VIDEO_CAPTURE !in request.resources) {
+                                    request.deny()
+                                    return
+                                }
+                                val hasCamera = ContextCompat.checkSelfPermission(
+                                    context, Manifest.permission.CAMERA,
+                                ) == PackageManager.PERMISSION_GRANTED
+                                if (hasCamera) {
+                                    request.grant(arrayOf(PermissionRequest.RESOURCE_VIDEO_CAPTURE))
+                                } else {
+                                    pendingWebPermission = request
+                                    webCameraPermissionLauncher.launch(Manifest.permission.CAMERA)
+                                }
+                            }
                         }
 
                         webViewClient = object : WebViewClient() {
@@ -553,6 +992,23 @@ private fun InAppBrowser(
                                 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 && isSameNode(u)) {
+                                    handler?.proceed()
+                                } else {
+                                    handler?.cancel()
+                                }
+                            }
+
                             override fun shouldOverrideUrlLoading(
                                 view: WebView?,
                                 request: WebResourceRequest?,
@@ -560,7 +1016,7 @@ private fun InAppBrowser(
                                 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
+                                if (isSameNode(u)) return false
                                 openExternalUrl(ctx, u)
                                 return true
                             }
@@ -663,3 +1119,48 @@ private fun InAppBrowser(
         }
     }
 }
+
+/**
+ * JS that fills the web UI login form (Login.vue's #login-password) with the
+ * stored password and submits it once the form is interactive — the one-step
+ * pairing flow. No-ops when the login step never appears (already
+ * authenticated, first-boot setup, TOTP). At most two attempts per page load,
+ * then it stops for good so a wrong stored password can't spam the node.
+ */
+private fun buildAutoLoginScript(password: String): String {
+    val quoted = org.json.JSONObject.quote(password)
+    return """
+    (function () {
+        if (window.__archyAutoLogin) return;
+        window.__archyAutoLogin = true;
+        var pw = $quoted;
+        var attempts = 0;
+        var started = Date.now();
+        var timer = setInterval(function () {
+            if (Date.now() - started > 45000) { clearInterval(timer); return; }
+            var el = document.getElementById('login-password');
+            if (!el) {
+                // Field gone after we submitted = success or step change - stop.
+                if (attempts > 0) clearInterval(timer);
+                return;
+            }
+            if (el.disabled) return; // form waits on serverReady
+            if (attempts >= 2) { clearInterval(timer); return; }
+            attempts++;
+            var setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set;
+            setter.call(el, pw);
+            el.dispatchEvent(new Event('input', { bubbles: true }));
+            // Let Vue re-render before submitting: a synchronous Enter arrives
+            // while the login button is still disabled, and the web UI's
+            // controller-nav "Enter in input clicks the next enabled button"
+            // pattern then hits Replay Intro instead — restarting the intro
+            // cinematic on every connect (two frames = value flush + render).
+            requestAnimationFrame(function () {
+                requestAnimationFrame(function () {
+                    el.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+                });
+            });
+        }, 1500);
+    })();
+    """.trimIndent()
+}

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

@@ -11,6 +11,7 @@
     <string name="welcome_title">Your Sovereign\nPersonal Server</string>
     <string name="welcome_subtitle">Bitcoin node, app platform, and private cloud — all in one box you control.</string>
     <string name="get_started">Get Started</string>
+    <string name="mesh_party">Mesh Party</string>
     <string name="use_https">Use HTTPS</string>
     <string name="port_label">Port (optional)</string>
     <string name="saved_servers">Saved Servers</string>
@@ -28,4 +29,24 @@
     <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="scan_node_qr">Scan Node\'s QR</string>
+    <string name="enter_manually">Enter Manually</string>
+    <string name="connect_landing_hint">Scan the pairing QR from your node\'s Companion popup, or enter the address manually</string>
+    <string name="scan_qr_hint">Point the camera at the pairing QR shown in the Companion popup</string>
+    <string name="camera_permission_needed">Camera access is needed to scan the pairing QR. You can also enter the server details manually.</string>
+    <string name="grant_camera_access">Grant Camera Access</string>
+    <string name="invalid_pairing_qr">Not an Archipelago pairing code</string>
+    <string name="update_app_for_qr">This pairing code needs a newer app version — please update the companion app</string>
+    <string name="add_server_qr">Add server by QR</string>
+    <string name="edit_server_title">Edit Server</string>
+    <string name="save_changes">Save Changes</string>
+    <string name="cancel">Cancel</string>
+    <string name="gesture_hint_title">Hold with three fingers</string>
+    <string name="gesture_hint_body">Anywhere in the app — opens the remote control and menu</string>
+    <string name="gesture_hint_got_it">Got it</string>
+    <string name="scan_to_send">Scan to send</string>
+    <string name="scan_wallet_hint">Point the camera at a Lightning invoice, Bitcoin address, Cashu or Fedimint code</string>
+    <string name="upload_qr_image">Upload image</string>
+    <string name="no_qr_in_image">No QR code found in that image — try another, closer and well-lit</string>
 </resources>

Android/app/src/main/res/xml/file_paths.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- FileProvider scope for the party-screen "Share this app" APK handoff. -->
+<paths>
+    <cache-path name="share" path="share/" />
+</paths>

Android/rust/archy-fips-core/Cargo.toml

@@ -0,0 +1,45 @@
+# Embedded FIPS mesh node for the Archipelago companion app.
+#
+# Built for Android via cargo-ndk (see Android/app/build.gradle.kts, task
+# buildRustArm64) into app/src/main/jniLibs/arm64-v8a/libarchy_fips_core.so.
+# Also builds on the host so `cargo test` covers the non-JNI logic.
+#
+# `fips` is pinned to the fips-native fork rev that this integration was
+# developed against — the fork carries Android support upstream lacks
+# (Tun::from_fd for a VpnService-owned fd, cfg(target_os = "android") paths).
+# Override with a local checkout when hacking on fips itself:
+#   CARGO_NET_OFFLINE=false cargo ndk ... --config 'patch."https://github.com/9qeklajc/fips-native".fips.path="/path/to/fips-native/fips"'
+[package]
+name = "archy-fips-core"
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+publish = false
+
+[lib]
+name = "archy_fips_core"
+# rlib for host tests; cdylib for the Android shared library.
+crate-type = ["lib", "cdylib"]
+
+[dependencies]
+# default-features drops the ratatui TUI; tun-support enables Node::start_with_tun_fd.
+fips = { git = "https://github.com/9qeklajc/fips-native", rev = "46494a74fc85b878305d275d42ab719082b06ba6", default-features = false, features = ["tun-support"] }
+anyhow = "1.0"
+serde_json = "1.0"
+hex = "0.4"
+# OS CSPRNG for identity generation (crypto rule: no thread-local RNG for keys).
+getrandom = "0.2"
+tokio = { version = "1", features = ["rt-multi-thread", "sync", "time", "macros"] }
+tracing = "0.1"
+# fcntl: force the VpnService TUN fd into blocking mode (see mesh::start).
+libc = "0.2"
+
+# The JNI surface only exists on Android; host builds skip it and drive the
+# mesh module directly (tests).
+[target.'cfg(target_os = "android")'.dependencies]
+jni = "0.21"
+# Bridge `tracing` (ours + fips) to logcat: `adb logcat -s archy-fips`.
+tracing-subscriber = { version = "0.3", features = ["env-filter"] }
+paranoid-android = "0.2"
+
+[workspace]

Android/rust/archy-fips-core/src/jni_glue.rs

@@ -0,0 +1,129 @@
+//! JNI surface for `com.archipelago.app.fips.FipsNative` — JSON over strings,
+//! no codegen (the myco / nostr-vpn embedding pattern). Errors come back as
+//! `{"error": "…"}` so Kotlin never sees a raw exception from native code.
+
+use std::sync::Once;
+
+use jni::objects::{JClass, JString};
+use jni::sys::{jboolean, jint, jstring};
+use jni::JNIEnv;
+
+use crate::mesh;
+
+static LOG_INIT: Once = Once::new();
+
+fn init_logging() {
+    LOG_INIT.call_once(|| {
+        use tracing_subscriber::layer::SubscriberExt;
+        use tracing_subscriber::util::SubscriberInitExt;
+        let _ = tracing_subscriber::registry()
+            .with(tracing_subscriber::EnvFilter::new("info"))
+            .with(paranoid_android::layer("archy-fips"))
+            .try_init();
+    });
+}
+
+fn jstr(env: &mut JNIEnv, s: &JString) -> String {
+    env.get_string(s).map(|s| s.into()).unwrap_or_default()
+}
+
+fn out(env: &JNIEnv, s: String) -> jstring {
+    env.new_string(s)
+        .map(|s| s.into_raw())
+        .unwrap_or(std::ptr::null_mut())
+}
+
+fn err_json(e: impl std::fmt::Display) -> String {
+    serde_json::json!({ "error": e.to_string() }).to_string()
+}
+
+fn identity_json(info: &mesh::IdentityInfo) -> String {
+    serde_json::json!({
+        "secret": info.secret_hex,
+        "npub": info.npub,
+        "address": info.address,
+    })
+    .to_string()
+}
+
+/// Kotlin: `external fun generateIdentity(): String`
+#[no_mangle]
+pub extern "system" fn Java_com_archipelago_app_fips_FipsNative_generateIdentity(
+    env: JNIEnv,
+    _class: JClass,
+) -> jstring {
+    init_logging();
+    let json = match mesh::generate_identity() {
+        Ok(info) => identity_json(&info),
+        Err(e) => err_json(e),
+    };
+    out(&env, json)
+}
+
+/// Kotlin: `external fun deriveIdentity(secret: String): String`
+#[no_mangle]
+pub extern "system" fn Java_com_archipelago_app_fips_FipsNative_deriveIdentity(
+    mut env: JNIEnv,
+    _class: JClass,
+    secret: JString,
+) -> jstring {
+    init_logging();
+    let secret = jstr(&mut env, &secret);
+    let json = match mesh::derive_identity(&secret) {
+        Ok(info) => identity_json(&info),
+        Err(e) => err_json(e),
+    };
+    out(&env, json)
+}
+
+/// Kotlin: `external fun start(secret: String, peersJson: String, tunFd: Int, listenPort: Int): String`
+/// Returns `{"npub": "...", "address": "..."}` or `{"error": "..."}`.
+/// `listenPort` 0 = outbound-only; non-zero = fixed UDP bind (party mode).
+#[no_mangle]
+pub extern "system" fn Java_com_archipelago_app_fips_FipsNative_start(
+    mut env: JNIEnv,
+    _class: JClass,
+    secret: JString,
+    peers_json: JString,
+    tun_fd: jint,
+    listen_port: jint,
+) -> jstring {
+    init_logging();
+    let secret = jstr(&mut env, &secret);
+    let peers = jstr(&mut env, &peers_json);
+    let listen_port = u16::try_from(listen_port).unwrap_or(0);
+    let json = match mesh::start(&secret, &peers, tun_fd, listen_port) {
+        Ok((npub, address)) => {
+            serde_json::json!({ "npub": npub, "address": address }).to_string()
+        }
+        Err(e) => err_json(e),
+    };
+    out(&env, json)
+}
+
+/// Kotlin: `external fun stop()`
+#[no_mangle]
+pub extern "system" fn Java_com_archipelago_app_fips_FipsNative_stop(
+    _env: JNIEnv,
+    _class: JClass,
+) {
+    mesh::stop();
+}
+
+/// Kotlin: `external fun isRunning(): Boolean`
+#[no_mangle]
+pub extern "system" fn Java_com_archipelago_app_fips_FipsNative_isRunning(
+    _env: JNIEnv,
+    _class: JClass,
+) -> jboolean {
+    mesh::is_running() as jboolean
+}
+
+/// Kotlin: `external fun statusJson(): String`
+#[no_mangle]
+pub extern "system" fn Java_com_archipelago_app_fips_FipsNative_statusJson(
+    env: JNIEnv,
+    _class: JClass,
+) -> jstring {
+    out(&env, mesh::status_json())
+}

Android/rust/archy-fips-core/src/lib.rs

@@ -0,0 +1,17 @@
+//! Embedded FIPS mesh node for the Archipelago companion app.
+//!
+//! The phone runs a real, leaf-only FIPS node in-process: Android's
+//! `VpnService` owns the TUN fd (routing only `fd00::/8`, so normal traffic
+//! never touches the tunnel) and hands it to [`fips::Node::start_with_tun_fd`].
+//! Peering is outbound-only — the pairing QR carries the node's npub and
+//! transport endpoints, and FIPS nodes accept inbound peers without prior
+//! registration, so no server-side enrollment step exists.
+//!
+//! The JNI surface (`jni_glue`, Android-only) is deliberately tiny and
+//! JSON-over-strings, mirroring the myco / nostr-vpn embedding pattern:
+//! `generateIdentity`, `deriveIdentity`, `start`, `stop`, `isRunning`.
+
+pub mod mesh;
+
+#[cfg(target_os = "android")]
+mod jni_glue;

Android/rust/archy-fips-core/src/mesh.rs

@@ -0,0 +1,274 @@
+//! Mesh lifecycle: identity, config assembly, and the node task.
+//!
+//! Host-buildable (no JNI) so the config/identity logic is unit-testable;
+//! only [`start`] needs a real TUN fd and therefore only runs on-device.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use anyhow::{anyhow, Context, Result};
+use fips::config::{PeerConfig, TransportInstances, UdpConfig};
+use fips::{Config, Identity, Node};
+use tokio::sync::Notify;
+
+/// How long `start` waits for the node to come up (TUN attach + transports).
+const START_TIMEOUT: Duration = Duration::from_secs(15);
+
+/// How long `stop` waits for the node task to drain.
+const STOP_TIMEOUT: Duration = Duration::from_secs(5);
+
+struct MeshHandle {
+    runtime: tokio::runtime::Runtime,
+    task: Option<tokio::task::JoinHandle<()>>,
+    shutdown: Arc<Notify>,
+    running: Arc<AtomicBool>,
+    npub: String,
+    address: String,
+}
+
+static MESH: Mutex<Option<MeshHandle>> = Mutex::new(None);
+
+#[derive(Debug, Clone)]
+pub struct IdentityInfo {
+    pub secret_hex: String,
+    pub npub: String,
+    /// The phone's own ULA on the mesh (fd::/8), for VpnService.addAddress.
+    pub address: String,
+}
+
+/// Generate a fresh mesh identity from the OS CSPRNG.
+pub fn generate_identity() -> Result<IdentityInfo> {
+    // ~1 in 2^128 chance a candidate is off the curve; loop regardless.
+    loop {
+        let mut bytes = [0u8; 32];
+        getrandom::getrandom(&mut bytes).context("OS RNG")?;
+        if let Ok(id) = Identity::from_secret_bytes(&bytes) {
+            return Ok(IdentityInfo {
+                secret_hex: hex::encode(bytes),
+                npub: id.npub(),
+                address: id.address().to_ipv6().to_string(),
+            });
+        }
+    }
+}
+
+/// Re-derive npub + ULA from a stored secret.
+pub fn derive_identity(secret: &str) -> Result<IdentityInfo> {
+    let id = Identity::from_secret_str(secret).map_err(|e| anyhow!("bad secret: {e}"))?;
+    Ok(IdentityInfo {
+        secret_hex: secret.to_string(),
+        npub: id.npub(),
+        address: id.address().to_ipv6().to_string(),
+    })
+}
+
+/// Build the phone-side node config: leaf-only (never routes third-party
+/// traffic — battery), no DNS responder, TUN enabled but attached to the
+/// VpnService fd rather than created.
+///
+/// `listen_port` 0 = ephemeral UDP (outbound-only, the default posture).
+/// Non-zero = fixed UDP bind so a nearby phone can dial us directly over a
+/// local link (party mode); leaf_only still guarantees we never carry
+/// third-party transit even while accepting an inbound link.
+pub fn build_config(secret: &str, peers: Vec<PeerConfig>, listen_port: u16) -> Config {
+    let mut cfg = Config::default();
+    cfg.node.identity.nsec = Some(secret.to_string());
+    cfg.node.identity.persistent = false;
+    cfg.node.leaf_only = true;
+    cfg.tun.enabled = true;
+    cfg.tun.mtu = Some(1280);
+    cfg.dns.enabled = false;
+    cfg.transports.udp = TransportInstances::Single(UdpConfig {
+        bind_addr: Some(format!("0.0.0.0:{listen_port}")),
+        ..Default::default()
+    });
+    // TCP with no bind_addr = outbound-only (fallback when UDP is blocked).
+    cfg.transports.tcp = TransportInstances::Single(Default::default());
+    cfg.peers = peers;
+    cfg
+}
+
+/// Parse the peers JSON handed over from Kotlin. Shape = fips `PeerConfig`:
+/// `[{"npub":"…","alias":"…","addresses":[{"transport":"udp","addr":"host:2121","priority":10},…]}]`
+pub fn parse_peers(peers_json: &str) -> Result<Vec<PeerConfig>> {
+    serde_json::from_str(peers_json).context("peers JSON")
+}
+
+/// Start the mesh node on the given TUN fd (from `VpnService.establish()`,
+/// detached — the node owns it from here). Returns (npub, ula) on success.
+/// Any previously running node is stopped first.
+pub fn start(secret: &str, peers_json: &str, tun_fd: i32, listen_port: u16) -> Result<(String, String)> {
+    stop();
+
+    // Android hands the VpnService TUN fd over in non-blocking mode on some
+    // OS builds. The fips TUN reader is a dedicated blocking-read thread that
+    // treats EAGAIN as fatal — the loop died at startup ("TUN read error …
+    // Try again (os error 11)" on-device), so sessions came up but no packet
+    // ever entered the mesh. Force the fd into the blocking mode the reader
+    // is designed for.
+    unsafe {
+        let flags = libc::fcntl(tun_fd, libc::F_GETFL);
+        if flags >= 0 && (flags & libc::O_NONBLOCK) != 0 {
+            libc::fcntl(tun_fd, libc::F_SETFL, flags & !libc::O_NONBLOCK);
+        }
+    }
+
+    let peers = parse_peers(peers_json)?;
+    let config = build_config(secret, peers, listen_port);
+    let mut node = Node::new(config).map_err(|e| anyhow!("node init: {e}"))?;
+    let npub = node.npub();
+    let address = node.identity().address().to_ipv6().to_string();
+
+    let runtime = tokio::runtime::Builder::new_multi_thread()
+        .worker_threads(2)
+        .enable_all()
+        .thread_name("archy-fips")
+        .build()
+        .context("tokio runtime")?;
+
+    let shutdown = Arc::new(Notify::new());
+    let running = Arc::new(AtomicBool::new(false));
+    let (started_tx, started_rx) = tokio::sync::oneshot::channel::<Result<()>>();
+
+    let task = {
+        let shutdown = shutdown.clone();
+        let running = running.clone();
+        runtime.spawn(async move {
+            match node.start_with_tun_fd(tun_fd).await {
+                Ok(()) => {
+                    running.store(true, Ordering::SeqCst);
+                    let _ = started_tx.send(Ok(()));
+                }
+                Err(e) => {
+                    let _ = started_tx.send(Err(anyhow!("node start: {e}")));
+                    return;
+                }
+            }
+            tokio::select! {
+                result = node.run_rx_loop() => {
+                    if let Err(e) = result {
+                        tracing::error!("mesh rx loop error: {e}");
+                    }
+                }
+                _ = shutdown.notified() => {}
+            }
+            if let Err(e) = node.stop().await {
+                tracing::warn!("mesh stop: {e}");
+            }
+            running.store(false, Ordering::SeqCst);
+        })
+    };
+
+    let started = runtime
+        .block_on(async { tokio::time::timeout(START_TIMEOUT, started_rx).await })
+        .map_err(|_| anyhow!("node start timed out"))?
+        .map_err(|_| anyhow!("node task died during start"))?;
+    if let Err(e) = started {
+        runtime.shutdown_background();
+        return Err(e);
+    }
+
+    *MESH.lock().unwrap() = Some(MeshHandle {
+        runtime,
+        task: Some(task),
+        shutdown,
+        running,
+        npub: npub.clone(),
+        address: address.clone(),
+    });
+    Ok((npub, address))
+}
+
+/// Stop the mesh node if running. Idempotent.
+pub fn stop() {
+    let Some(mut handle) = MESH.lock().unwrap().take() else {
+        return;
+    };
+    handle.shutdown.notify_waiters();
+    if let Some(task) = handle.task.take() {
+        let _ = handle
+            .runtime
+            .block_on(async { tokio::time::timeout(STOP_TIMEOUT, task).await });
+    }
+    handle.runtime.shutdown_background();
+}
+
+pub fn is_running() -> bool {
+    MESH.lock()
+        .unwrap()
+        .as_ref()
+        .map(|h| h.running.load(Ordering::SeqCst))
+        .unwrap_or(false)
+}
+
+/// `{running, npub, address}` for the Kotlin status surface.
+pub fn status_json() -> String {
+    let guard = MESH.lock().unwrap();
+    match guard.as_ref() {
+        Some(h) => serde_json::json!({
+            "running": h.running.load(Ordering::SeqCst),
+            "npub": h.npub,
+            "address": h.address,
+        })
+        .to_string(),
+        None => serde_json::json!({ "running": false }).to_string(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn identity_roundtrip() {
+        let a = generate_identity().unwrap();
+        let b = derive_identity(&a.secret_hex).unwrap();
+        assert_eq!(a.npub, b.npub);
+        assert_eq!(a.address, b.address);
+        // ULA in fd::/8
+        assert!(a.address.starts_with("fd"));
+    }
+
+    #[test]
+    fn peers_json_parses_into_peer_config() {
+        let peers = parse_peers(
+            r#"[{
+                "npub": "npub1abc",
+                "alias": "My Archipelago",
+                "addresses": [
+                    {"transport": "udp", "addr": "192.168.1.228:2121", "priority": 10},
+                    {"transport": "tcp", "addr": "192.168.1.228:8443", "priority": 20}
+                ]
+            }]"#,
+        )
+        .unwrap();
+        assert_eq!(peers.len(), 1);
+        assert_eq!(peers[0].addresses.len(), 2);
+        assert!(peers[0].is_auto_connect());
+    }
+
+    #[test]
+    fn config_is_leaf_only_with_tun() {
+        let id = generate_identity().unwrap();
+        let cfg = build_config(&id.secret_hex, vec![], 0);
+        assert!(cfg.node.leaf_only);
+        assert!(cfg.tun.enabled);
+        assert_eq!(cfg.tun.mtu(), 1280);
+        assert!(!cfg.dns.enabled);
+        assert!(!cfg.transports.udp.is_empty());
+        assert!(!cfg.transports.tcp.is_empty());
+    }
+
+    #[test]
+    fn listen_port_sets_fixed_udp_bind() {
+        let id = generate_identity().unwrap();
+        let cfg = build_config(&id.secret_hex, vec![], 2121);
+        // Party mode keeps leaf_only — accepting a link is not routing transit.
+        assert!(cfg.node.leaf_only);
+        let TransportInstances::Single(udp) = &cfg.transports.udp else {
+            panic!("expected single UDP transport");
+        };
+        assert_eq!(udp.bind_addr.as_deref(), Some("0.0.0.0:2121"));
+    }
+}

Android/ship-companion.sh

@@ -9,6 +9,10 @@
 #
 #   ./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)"
@@ -17,25 +21,15 @@ cd "$ROOT"
 export JAVA_HOME="${JAVA_HOME:-/opt/homebrew/opt/openjdk@17}"
 export ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}"
 
-APK="Android/app/build/outputs/apk/debug/app-debug.apk"
 DEST="neode-ui/public/packages/archipelago-companion.apk"
-OLD_ZIP="neode-ui/public/packages/archipelago-companion.apk.zip"
 
-echo "==> Building debug APK"
-( cd Android && ./gradlew :app:assembleDebug --console=plain -q )
-[ -f "$APK" ] || { echo "ERROR: APK not found at $APK" >&2; exit 1; }
+echo "==> Building + signing + verifying companion APK"
+bash scripts/publish-companion-apk.sh
 
-echo "==> Publishing -> $DEST"
-mkdir -p "$(dirname "$DEST")"
-cp "$APK" "$DEST"
-# Drop the legacy zipped artifact so the served download is the raw APK only.
-if [ -f "$OLD_ZIP" ]; then
-  git rm -q --ignore-unmatch "$OLD_ZIP" 2>/dev/null || rm -f "$OLD_ZIP"
-fi
+[ -f "$DEST" ] || { echo "ERROR: served APK not found at $DEST" >&2; exit 1; }
 
-git add "$DEST"
-if git diff --cached --quiet; then
-  echo "==> Nothing to commit (working tree + APK unchanged)"
+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"

CHANGELOG.md

@@ -1,33 +1,166 @@
 # Changelog
 
-## v1.8.00-alpha (2026-06-18)
+## v1.7.112-alpha (2026-07-23)
 
-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).
+- Sound works on TVs out of the box. Fresh installs were missing the audio system entirely, and even when present a boot-time race left HDMI silent until the cable was unplugged and replugged. Both are fixed: installer images now ship the full audio stack, and a small background helper detects the silent-HDMI state and heals it automatically.
+- Plug in a game controller and drive the whole TV interface with it — navigation, menus, and media playback all respond to the gamepad, and dialogs that pop up are controller-navigable too.
+- The companion phone app took a huge leap (0.5.9). Your node and its apps now work from anywhere — on 5G or any internet connection, the phone reaches the node over the encrypted mesh with zero port forwarding or VPN setup. Startup away from home is instant, apps on your node open inside the app, the phone's native camera handles QR scanning, and a branded full-screen loader shows while the mesh connects.
+- Mesh Party: two phones scan each other's QR and instantly get a direct encrypted chat and app sharing between them — plus a "Share this app" QR that anyone can scan with a normal camera to install the companion app.
+- Pairing a second phone no longer silently logs out the first. Every device now keeps its own named access credential, ending the mystery reconnects when a household paired more than one phone.
+- The companion pairing QR is scannable again (it had grown too dense for phone cameras) and now identifies your node by its identity key, so the app recognizes your node even after it moves or gets a new address.
+- Every app your node serves on your home network is now also reachable over the mesh — remote access covers the apps themselves, not just the dashboard.
+- Selling files: you now choose which payment methods you accept (Lightning, ecash, …) and buyers are only offered those — enforced by the node itself, not just the buttons. Paying twice for the same file is impossible now, purchases file themselves into a new Paid Files tab, purchased music always plays in the bottom-bar player, and videos get picture-in-picture.
+- Sending Lightning is invoice-first: paste or scan an invoice and the amount fills in and locks by itself. An expired invoice now tells you plainly to ask for a fresh one instead of failing cryptically, and payment errors always reach your screen.
+- Sending to a pasted address gets a confirmation step showing exactly what will happen before any money moves, and buying ecash is an explicit two-step — no more accidental purchases.
+- Apps keep running when you change how they're displayed. Switching an app between windowed and fullscreen used to reload it from scratch (stopping any playing media); the app now stays live through the switch, and each app remembers its own preferred display mode.
+- A watchdog notices when the Lightning (LND) node wedges and revives it before you do; Fedi ecash gets its own send option with scannable token QR codes.
+- Fedimint's Lightning gateway and guardian now follow whichever bitcoin version is actually running instead of pointing at a stale address — switching bitcoin versions no longer strands them.
+- If your router starts handing out different addresses, the Pine voice speaker re-links itself automatically instead of staying silent until someone re-configures it.
+- Polish: mesh radios never show garbled device names anymore, the TV kiosk uses slim overlay scrollbars instead of fat grey bars, and the AI chat's background artwork shows through again.
+- Your mesh messages now survive restarts. Chat history — channels and DMs alike — used to live only in memory, so a reboot or update wiped every conversation; worse, other nodes silently discarded the first messages you sent after a reboot. Everything is now saved on the node and restored on startup, and post-reboot messages deliver reliably.
+- Plug in any LoRa radio and the node walks you through it. A setup window appears every time a radio is connected, shows what firmware is already on it (MeshCore, Meshtastic, or Reticulum RNode — with its current name, region, and channels where available), and offers two honest choices: "Set Up with Archipelago Settings" (a preview screen shows exactly what will be written before anything touches the radio) or "Keep As Is" (the radio is used untouched, and you can hot-swap radios freely). Swapping sticks mid-session now just works — including Reticulum RNodes, which fresh installer images now support out of the box.
+- Incoming bitcoin appears in your wallet within seconds of being sent — balance and the yellow "unconfirmed" entry update live, no refresh, no waiting for the next poll.
+- The speaker now announces the very first mesh message a node ever receives, and DMs announce just like channel messages (a safety guard against announcement storms was quietly swallowing them). Announcements also react about twice as fast.
+- Opening a Lightning channel right after the node starts no longer fails with a scary red error. The node quietly retries while Lightning finishes waking up, and if it's still not ready you get a calm "still finishing its startup — try again shortly" notice instead.
+- Viewing a transaction works on every node now, including small ones. Nodes with pruned bitcoin storage can't run the Mempool explorer app; transaction links now open your choice of external explorer instead (tx1138.com by default) — after a clear one-time warning that a third-party server will see which transaction you looked up. Set your preferred explorer in Wallet Settings → the new On-chain tab.
+- Voice commands respond noticeably faster: speech recognition now transcribes in roughly half the time, with identical accuracy on short commands.
+- Scanning a Lightning invoice with your phone's camera is far more reliable — dense invoice QR codes that the photo scanner missed are now read by the phone's native barcode engine.
+- The companion app's pairing QR always contains an address your phone can actually reach. If you manage your node over a VPN (Tailscale), the QR used to embed the VPN address, and pairing silently failed; it now advertises the node's home-network address.
+- Peer requests sent from Nostr discovery now actually arrive: your node checks for incoming requests every five minutes by itself (previously they sat unseen until someone manually pressed "Poll"), requests publish to all your configured relays instead of two hardcoded ones, and a failed send tells you instead of pretending it worked.
+- The Connected Nodes list refreshes instantly. It previously froze for up to 30 seconds per offline peer while checking who's reachable, one peer at a time; the checks now run all at once in the background while the list shows immediately.
+- Apps opened from inside a window (like a transaction from the wallet) now animate smoothly on top instead of loading invisibly underneath.
+- Settings-style windows keep their tabs pinned at the top and their buttons pinned at the bottom; only the middle scrolls. The wallet's tabs are now Channels / Cashu / Fedi / Ark / On-chain so all five fit.
+- On the TV screen, menus no longer flash open and instantly close. And the interface never follows your computer's light/dark preference anymore — dropdowns and other native controls stay dark on every device.
+- Error messages tell you what's actually wrong: "Insufficient balance: need 80 sats, have 0 sats" now reaches your screen instead of "Operation failed. Check server logs."
+- Installing Mempool no longer refuses to start while ElectrumX is mid-resync (it connects by itself once ElectrumX is ready), and installs no longer fail just because the system was momentarily busy.
+- Much quieter logs: the node no longer tries to start containers that are already running (hundreds of harmless-but-alarming errors per day), and a node that's offline stops hammering unreachable servers every 30 seconds with rebuild attempts.
+- Phones pairing with the companion app connect over the node's embedded mesh for remote access, with instant QR pairing and per-device access tokens (contributed alongside this release).
 
-- 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.
+## v1.7.111-alpha (2026-07-22)
 
-All the v1.7.99-alpha features are included as well:
+- Ask your node anything, out loud. Install Pine (the voice assistant app) alongside Home Assistant and everything wires itself automatically: speech recognition, the speaking voice, and a Claude-powered brain. Questions about your node — "what's the block height?", "how many peers am I connected to?", "is bitcoin synced?", "what's my Lightning balance?" — are answered instantly from the node itself without costing anything; anything else goes to Claude for a real conversation. New mesh radio messages are read out on your speaker as they arrive.
+- Pine now ships a wake-word listener, so a paired speaker can sit on standby and activate when it hears its wake word instead of needing a button press. (A custom "Yo Archy" wake word is in the works.)
+- Pine's launcher page shows your node's live status at a glance: software version, uptime, bitcoin sync progress, and mesh peers.
+- Fixed: installing Pine could send Home Assistant into a crash loop on startup (a record the installer wrote was missing a timestamp field Home Assistant requires). Two noisy warnings that repeated in Home Assistant's log every half minute are silenced too.
+- The companion phone app opens every app in its fast built-in browser view again, with native back/forward/reload controls, instead of embedding some apps inside the page where they scroll and render worse. This had quietly regressed.
+- Turning on federation discovery now shows you exactly what you're about to sign: a panel explains the announcement before your key signs it, you can review the signing details any time from the discoverability strip, and the panel fits and scrolls properly on small phones.
+- Fixed a bug on nodes using the newer app-management engine where Bitcoin's access credentials were written out incorrectly (a placeholder leaked through as the literal text "/bin/bash"), which broke the node's Bitcoin status display, Lightning's connection to the chain, and any app that reads Bitcoin data.
+- Bitcoin's access credentials also moved out of the process command line into a protected file, so they're no longer visible to other software on the node.
+- Desktop app windows have one-click buttons to switch between side panel, overlay, and fullscreen viewing.
+- On the phone home screen, the wallet card moved up to sit right under My Apps.
+- Home Assistant updated to 2026.7.3, which keeps voice satellites (like Pine's speaker) connected reliably.
 
-- 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.110-alpha (2026-07-21)
+
+- Pay by pointing your camera: the wallet has a new Scan button (on the wallet card and inside both the Send and Receive windows) that reads any payment QR code — Lightning invoices, Bitcoin addresses, Cashu tokens, and Fedimint invites — and takes you straight to the right send or redeem screen with everything filled in. It also understands the animated, multi-part QR codes some wallets show for long payloads. If your browser can't open a live camera preview (common when reaching the node over plain http), a "Take photo of QR" button snaps a picture with your phone's camera and reads the code from the photo instead.
+- The TV screen got a complete overhaul. A deep bug made the display freeze on the intro artwork on 4K TVs — that's fixed, and along the way: the interface now picks a comfortable, sharp size for big screens (a 4K TV gets a full desktop layout at double sharpness), the artwork behind every page shows again instead of a black void, switching between tabs animates smoothly, the built-in AI assistant stays in its dark theme, and the Cashu and Ark wallet icons no longer render as empty squares.
+- You can now choose how big the interface renders on your node's attached screen: Settings → Display offers Auto (recommended), Large UI, Balanced, and Native — changing it applies immediately.
+- The companion phone app can steer the TV again. Remote input from the phone was being silently ignored on kiosk displays; the remote-control relay now runs there like everywhere else.
+- The companion app is also ready to grant its built-in browser camera access, so the wallet scanner can work inside the app (ships with the next companion app build).
+- Zero-amount Lightning invoices can now be paid: the wallet asks you for the amount and sends it along, instead of failing on invoices that leave the amount up to the payer.
+- The Lightning setup guidance now reads the same everywhere: "Open a channel with Zeus Olympus node and start sending and receiving Lightning payments. Minimum 150,000 · maximum 1,500,000 on-chain sats required."
+- Installer images now bundle a color-emoji font, so emoji anywhere in the interface render properly on the TV screen.
+
+## v1.7.109-alpha (2026-07-21)
+
+- Meet Pine, your node's voice assistant: a new app in the App Store that gives your node ears and a voice — speech-to-text and text-to-speech engines that run entirely on your own hardware, ready to wire into Home Assistant for private, offline voice control. Install it like any other app; nothing you say leaves your node.
+- Your node can now program its MeshCore radio's RF settings — frequency, bandwidth, spreading factor, and coding rate — from Mesh → Device settings. Radios that were flashed with mismatched settings could hear that other radios exist but never decode their messages, and until now the only fix was a separate phone app. Set the values once and the node programs the radio automatically (it restarts once to apply); every radio on your mesh must use the same values to talk to each other.
+- The Device settings panel is tidier: values you can edit (name, region, channel) are no longer also shown as separate read-only rows.
+
+## v1.7.108-alpha (2026-07-20)
+
+- Your node connects to the private mesh far more reliably. Nodes rely on a public rendezvous point to find each other, and the only one available was unreachable from many home and office networks — leaving some nodes unable to join the mesh at all. There is now a second, always-reachable rendezvous point, and your node tries every one it knows, so it joins the mesh in seconds instead of being stranded.
+- Wi-Fi setup now heals itself on older nodes. Some nodes set up before a mid-year fix couldn't connect to a Wi-Fi network from the screen — it failed with a permissions error — because the piece that lets the node manage networking on your behalf was missing. Nodes now put that piece in place automatically on startup, so "scan, pick a network, type the password, connect" works without reinstalling.
+- Your node rejoins the mesh within seconds after an update. Applying an update briefly restarts the mesh service, and previously a node could sit disconnected from other nodes for up to five minutes before it retried.
+- The TV screen now fits your television. On a large or 4K TV the interface rendered tiny with no way to zoom on a keyboard-less screen; it now sizes itself to a comfortable, readable scale automatically (and small laptop panels are left unchanged).
+- More TV-screen polish: the built-in assistant shows its dark theme instead of bright white panels, the on-screen hint for switching between the kiosk and a terminal now points at the right keys, the welcome logo no longer occasionally renders as garbled characters, and an accidental tap of the power button no longer shuts the node down — hold it to power off on purpose.
+- Behind the scenes: fixed the installer image build so it no longer stops on a component that was removed from the product, and so it correctly includes the private relay it was meant to bundle.
+
+## v1.7.106-alpha (2026-07-20)
+
+- Nodes on the same network now find each other directly. Your node announces itself on your local network and connects straight to other Archipelago nodes nearby, instead of every connection having to be introduced by a public rendezvous server out on the internet. Peers in the same home or office stay connected to each other even when that server is unreachable, and they reach each other faster.
+- On a phone, the peer files screen tells you how you're connected again. The badge showing whether a peer's files are arriving over the fast mesh or over Tor was only visible on desktop — on narrow screens it disappeared entirely. It now appears next to the peer name on mobile too.
+- Your node's mesh settings can no longer be written in a way that breaks the mesh. The configuration file used to be assembled as free-form text, where one wrong setting would stop the mesh service from starting and quietly drop your node off the network. It's now generated from a checked description of the file, with tests that verify the exact output.
+- When your node has trouble reaching another node, the logs now record the real reason instead of a generic summary. A failure to open a peer's files previously logged only "Failed to connect to peer" and threw away the actual cause, which made these problems very hard to diagnose. Nothing changes on screen, and no internal detail is exposed.
+- Behind the scenes: the installer image now builds its mesh component at a fixed, known version instead of whatever upstream had published that day, so two images built from the same source are identical.
+
+## v1.7.105-alpha (2026-07-20)
+
+- Fixed a failure loop where a node that lost power or was moved could get stuck on a blank "can't reach your node" screen forever: startup recovery no longer spends minutes retrying containers that no longer exist, and a genuinely large recovery is no longer cut off half-way and forced to start over. The node now reaches its login screen even after the messiest shutdown.
+- Phone tunnel setup (WireGuard) is now dependable: the QR screen automatically retries while a fresh install is still settling instead of dead-ending at "failed to fetch", and if your node has moved to a different network the QR and downloadable config now carry the node's current address instead of the old one.
+- Fixed the white screen some laptop displays showed right after the intro on v1.7.104.
+- The companion phone app no longer suggests installing the companion app from inside itself.
+- The Tor page now lists onion addresses only for apps you actually have installed — fresh installs no longer come with six pre-made addresses for apps that were never set up.
+- Running `archipelago --version` or `--help` on the command line now prints and exits instead of silently starting a second copy of the node, which could briefly disrupt running apps.
+- Behind the scenes: installer image builds now stop loudly if VPN components are missing instead of producing a broken image, and a background file-permission sweep runs far less often, reducing disk churn on busy nodes.
+
+## v1.7.104-alpha (2026-07-19)
+
+- Software updates are now much safer to receive: the node will never install an update that isn't completely downloaded and verified byte-for-byte, closing a rare bug where an interrupted or cancelled download could leave a node unable to start.
+- If a freshly installed update does fail to start, the node now notices and automatically restores the previous working version by itself — no manual rescue needed.
+- The Electrum server now works with whichever Bitcoin you run: it finds Bitcoin Knots or Bitcoin Core automatically instead of assuming Knots.
+- While the Electrum server is first building its index, its waiting screen now shows the ElectrumX app icon and live progress.
+
+## v1.7.103-alpha (2026-07-18)
+
+- Connecting from the phone app no longer replays the intro cinematic on a loop: signing in after scanning the pairing QR could accidentally trigger "Replay Intro" instead of logging you in. The companion app now lands you straight on your dashboard, and the Android app waits for the login screen to be ready before it types your password.
+- Pressing Enter in any password box now does what you expect — it signs you in or moves to the next field, and can no longer "click" a nearby button by mistake when using a controller or the companion app.
+- The public demo no longer interrupts you with an "Update Available" popup that reset the site back to the intro — demo visitors simply get the newest version on their next visit.
+
+## v1.7.102-alpha (2026-07-17)
+
+- The password you choose during setup is now truly your node's password: it also becomes the system login for console and SSH access, instead of leaving the factory default in place. If you ever renamed your node and the TV screen went black on the next boot, that's fixed too — renaming no longer breaks the kiosk display.
+- Setting up Lightning is now a guided journey: a fund-your-wallet step that shows a live countdown while Bitcoin syncs, suggested channels you can open straight into the Zeus mobile wallet with one tap, and a "finish setup" prompt that walks you to the end — goals now complete when you've actually done the steps, not just when apps happen to be running.
+- Pair your phone by pointing it at the screen: the companion app now connects by scanning a QR code — scan, and it fills in your node's address and logs you in. The App Store has a banner to grab the Android app, and the pairing flow can now also set up secure remote access so your phone reaches home from anywhere.
+- First installs are far more dependable: app downloads that stall now retry instead of hanging forever (the old "first install fails, the second works" pattern), big multi-part apps show their real download progress instead of sitting at "Preparing", Lightning no longer fails its first install over temporary hiccups, and a brand-new node now comes up with its core apps — file cloud and ecash wallet — even with no internet connection.
+- The installer image is about 160MB smaller and gets to a working screen faster, because the apps bundled for offline setup are now compressed.
+- The first-run experience keeps its magic: the typing intro is back on fresh installs and can no longer be cut short by a mid-play refresh — updates now politely wait for the cinematic to finish — and dark backgrounds stay dark instead of flashing black or white.
+- Your backups now include your secrets — including the key that protects your Lightning wallet's recovery seed — and there's a Download button to take a copy off the node; the seed-backup reminder now actually opens the backup flow when you tap it.
+- Networking Profits grew into a full dashboard, network cards keep their action buttons in reach on every screen size, "Connect to Mesh" goes to the right page instead of a dead end, and the identity pages got a round of mobile polish.
+- Behind the scenes: apps that report their own health are no longer second-guessed by a port probe (fewer false "restarting" states), and pressing arrow keys or a gamepad is once again the only thing that shows the controller focus ring.
+
+## v1.7.101-alpha (2026-07-15)
+
+- The wallet speaks Ark: a new Ark tab shows your Ark balance and history, you can send and receive over the Ark protocol, pay Lightning invoices from your Ark balance, and Ark payments appear in the transactions view with their own filter chip.
+- Every app you install now automatically gets its own private .onion address — your apps are reachable over Tor a few seconds after install, with no manual "Add Service" step.
+- "Add Service" in the Tor panel now works for every app, not just a fixed list — the node reads the app's actual web port, so apps like Gitea, Jellyfin, Nextcloud, and Uptime Kuma no longer fail with "see server logs".
+- Renaming your node now genuinely renames it everywhere: the machine's hostname, its .local network name (re-announced immediately), the local hosts file, and the HTTPS certificate all follow — so http and https links using your node's name keep working right after a rename.
+- The node no longer mistakes a VPN tunnel for its own address. On fresh installs with NetBird, apps could launch on an internal 10.x address instead of your LAN IP; the node now reads its address from the actual network route, fixing app launch links, generated app configs, and VPN setup.
+- Your cloud got a real layout: Apps-style tabs with categories for Folders, My Files, and Peer Files, readable file rows, a search that also finds files shared by your federated peer nodes — and music now opens in the bottom-bar player instead of a broken preview window.
+- The first-login experience flows again: the dashboard entrance animation is back — and you can actually hear it now (its sound was silently swallowed before, including on replays) — "Replay Intro" in Settings actually replays it, opening a direct link to an inner page no longer detours through the splash screen, the login screen keeps the intro video until your first login (switching to rotating backgrounds after), and the intro video streams three times lighter so it starts instantly.
+- Changing DNS settings no longer blanks the page, and the DNS and WiFi dialogs now cover the whole app instead of only the right panel.
+- The public demo is richer and truer: the intro plays on every fresh visit, Ark wallet flows, working DNS and Tor service management, and a library of peer content with previews that never break.
+- Assorted fixes: failed installs clean up after themselves properly, and the transactions view fits mobile screens (capped at 60% of the visible viewport).
+
+## v1.7.100-alpha (2026-07-14)
+
+- Bitcoin now supports multiple versions of both Bitcoin Core and Bitcoin Knots: install the version you want, switch between them, pin a version, or let it auto-update — and switching is designed to be safe, with no surprise resyncs.
+- Lightning grew up: your LND wallet's recovery seed is captured at setup and kept as an encrypted backup you can reveal from Settings, there's a new Channels tab with a fee control when opening channels, and on-chain and Lightning balances now show side by side.
+- Installing Lightning (and other Bitcoin-dependent apps) on a fresh node no longer fails repeatedly — the node now waits until Bitcoin is genuinely ready to answer before starting them, and Bitcoin sizes its storage to your actual disk and its memory cache to your RAM, so small machines stop swapping and stalling.
+- The wallet understands more money: Cashu v4 tokens are supported, you can pay for a peer's files from either your Cashu or Fedimint ecash, and the Transactions view now shows your Lightning, Cashu, and Fedimint activity together — with a payment confirmation screen and an automatic refund if a purchase fails.
+- Mesh radios got a major upgrade: Meshtastic direct messages are now true end-to-end-encrypted radio messages that interoperate with off-the-shelf Meshtastic phone apps, your radio's region and a shared channel are provisioned automatically, and a new setup window appears when a radio is plugged in — with board pictures, full radio settings, and signal-strength indicators.
+- Reticulum joins as a third mesh radio protocol with RNode LoRa hardware support, including sending images and voice messages over the radio — and every chat message now carries a small pill showing how it travelled (Mesh, FIPS, or Tor).
+- Your node can manage an OpenWrt router: set up its internet uplink from the UI with a Wi-Fi network scan, turn it into a TollGate pay-for-Wi-Fi hotspot with a real captive portal, and sweep the router's earnings into your node's wallet. The gateway's status appears on the Home screen's Network tile.
+- Peering is now trust-aware: "Invite a Peer" grants view-only Observer access while "Link Your Nodes" grants Trusted access, incoming requests ask for your confirmation with an optional message, Node Visibility is a single clear switch plus a list of discoverable nodes you can peer with, and the Fleet view shows your trusted nodes' health.
+- Updates and apps are verified end-to-end: release updates are cryptographically signed and checked against a key baked into your node, app definitions arrive via the signed catalog, and container images are checked against trusted sources before anything installs or runs.
+- Dozens of reliability fixes: failed installs no longer leave phantom app cards, uninstalling can't hang forever, apps you stopped stay stopped, crashed apps heal themselves (even "running" containers whose process actually died), the login page no longer refresh-loops, and the mobile layout fits real phone screens instead of hiding the last row behind the browser bar.
+
+### Also in this release
+
+- Ask your node things over the radio: send "!archy" for node status with no AI involved, or "!ai <your question>" in a direct message for an AI answer that comes back on the same path it arrived — with a model dropdown (Haiku, Sonnet, or Opus) and an "always allow" list in the Mesh AI Assistant panel.
+- The off-grid mesh radio no longer posts cryptic identity codes ("ARCHY:") to the shared public channel every minute.
+- Mesh contacts take care of themselves: new radios you hear are added automatically, "Clear All" really removes contacts (they return when in range), each contact shows a reachability dot, and the Peers list has a search box.
+- You can message standard meshcore phone apps and they can message you — readable text both ways, private replies instead of public-channel broadcasts.
+- Federated Archipelago nodes now appear on the Mesh Map.
+- Apps open as an overlay on top of whatever page you're on, in every display mode, instead of yanking you to a different screen; the Services tab groups apps by category with proper icons.
+- BTCPay Server keeps its plugins across restarts, connects to your node's own LND out of the box, and its invoices stay payable over private Lightning channels.
+- Fedimint federations show up in Wallet Settings again (the client app's configuration error is fixed), and Wallet Settings has tabbed sections for Cashu and Fedimint.
+- The phone companion app can upload and download files, edit saved server entries, opens non-embeddable apps in an in-app browser, and got a proper round launcher icon.
+- Six placeholder "apps" that were just web bookmarks (484.kitchen, arch-presentation, call-the-operator, nwnn, syntropy-institute, t-zero) are gone from the store.
+- The Bitcoin dashboard works fully offline (no more loading its styling from the internet), Gitea opens on the right port, and mempool, strfry, and Electrum stopped their restart/health-check loops.
+- Kiosk displays: HDMI audio no longer stutters, and a bad display-clone state no longer sticks after reboot.
+- Consistent dropdowns, toggles, tabs, and modal styling across Settings, Federation, and the rest of the UI; in Mesh chat, scrolling the conversation no longer also scrolls the contact list; "App Updates" and "App Registry" sit directly under Account in Settings.
+- A fresh node no longer reinstalls apps just because their definition file exists on disk — only apps you actually installed come back.
 
 ## v1.7.99-alpha (2026-06-17)
 

CLAUDE.md

@@ -6,6 +6,11 @@
 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.
 
+**For day-to-day work, use `docs/UNIFIED-TASK-TRACKER.md`** — the consolidated,
+priority-ordered "what's left" list across the 1.8.0 OTA and master-plan docs
+(fastest/simplest tasks first). It supersedes hunting through the two source docs
+below for open items; those remain the narrative/history.
+
 **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),
@@ -18,9 +23,31 @@ 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`
+- Current per-app state → `docs/archive/app-registry-status-2026-06-21.md`
 - Production test gate (exit criterion) → `tests/lifecycle/TESTING.md`
 
+## Commit & push every unit of work (never violate)
+
+**The #1 process rule: work is not "done" until it is committed AND pushed.** This
+exists because finished work has been lost/clobbered by sitting uncommitted in the
+shared tree across agents and sessions. To prevent that:
+
+- **Commit each feature/fix the moment it works** — one focused, self-contained
+  commit per logical change (it compiles and its targeted tests pass). Do not let
+  unrelated changes accumulate uncommitted.
+- **Push immediately after committing** so nothing lives only on one machine. `main`
+  is protected → push via `git push gitea-ai main` (account `ai`, see the memory
+  note); feature branches push to their own remote.
+- **Never leave a stack of finished work uncommitted** overnight or when handing off
+  between agents — if you must pause mid-change, commit a clearly-labelled WIP
+  checkpoint rather than leaving it dirty.
+- **Stage explicitly by path** (`git add <paths>`) when another agent's uncommitted
+  work shares the tree — never `git add -A` / `git commit -a`, which clobbers or
+  entangles their changes.
+- **Never commit or push secrets** (mnemonics, private keys, API tokens). Signing is
+  done offline; artifacts (catalog/manifest) are signed, not the keys.
+- Commit messages end with the `Co-Authored-By: Claude …` trailer.
+
 ## Invariants (never violate)
 
 - **Rootless Podman only.** No rootful, no Docker-socket mounts, no privileged

CONTRIBUTING.md

@@ -8,9 +8,9 @@ Be respectful. We follow the [Contributor Covenant](https://www.contributor-cove
 
 ## Getting Started
 
-1. Fork the repository
-2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/archy.git`
-3. Set up the dev environment (see `docs/development-setup.md`)
+1. Fork the repository on the project's Gitea instance
+2. Clone your fork: `git clone <your-fork-url>/archy.git`
+3. Set up the dev environment (see `docs/developer-guide.md`)
 4. Create a feature branch: `git checkout -b feature/your-feature`
 
 ## Development Setup

INSTALL.sh

@@ -122,7 +122,7 @@ echo ""
 # Install custom app dependencies
 echo "Installing custom app dependencies..."
 
-for app in did-wallet endurain morphos-server router; do
+for app in did-wallet morphos-server router; do
     if [ -d "apps/$app" ]; then
         echo "  - Installing $app dependencies..."
         cd "apps/$app"
@@ -161,6 +161,6 @@ echo "   http://localhost:8100"
 echo ""
 echo "For more information, see:"
 echo "  - README.md"
-echo "  - docs/development-setup.md"
+echo "  - docs/developer-guide.md"
 echo "  - apps/QUICKSTART.md"
 echo ""

README.md

@@ -2,71 +2,99 @@
 
 > Self-Sovereign Bitcoin Node OS
 
-**Archipelago** is a bootable personal server OS. Flash it to a USB drive, install on any x86_64 or ARM64 machine, and manage Bitcoin infrastructure, self-hosted apps, and decentralized identity through a glassmorphism web UI.
+**Archipelago** is a bootable personal server OS. Flash it to a USB drive, install on any x86_64 or ARM64 machine, and manage Bitcoin infrastructure, self-hosted apps, mesh communication, and decentralized identity through a glassmorphism web UI.
 
 [![Debian 13](https://img.shields.io/badge/Debian-13%20Trixie-a80030)](https://www.debian.org/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Rust](https://img.shields.io/badge/rust-stable-orange)](https://www.rust-lang.org/)
 [![Vue.js](https://img.shields.io/badge/vue.js-3.5-brightgreen)](https://vuejs.org/)
-[![Version](https://img.shields.io/badge/version-1.3.1--beta-blue)]()
+[![Version](https://img.shields.io/badge/version-1.8.0--alpha-blue)]()
+
+## Philosophy
+
+Archipelago is being built as a **developer-ready app platform**, not a fixed appliance:
+
+- **Manifest-driven apps.** Every app is declared in a single `manifest.yml` — image, ports, volumes, secrets, health checks, security policy. The orchestrator owns the entire lifecycle; there is no per-app installer code and no host-level provisioning.
+- **Signed distribution.** App manifests ship inside an Ed25519-signed catalog verified against a pinned release-root key, not as loose files on disk. OTA release manifests are signed the same way.
+- **Decentralized marketplace.** Third-party developers publish apps via Nostr-based discovery (NIP-78) with DID-signed manifests and federation-weighted trust scoring — no gatekept central store.
+- **Rootless and secure by default.** Rootless Podman only. Read-only root, no-new-privileges, capability allow-list, secrets materialised 0600 and never logged. Never rootful, never a Docker socket mount.
+- **100%-uptime-capable.** Every container is a systemd Quadlet unit under `user.slice` that survives backend restarts; a level-triggered reconciler self-heals drift every 30 seconds; migrations never destroy data.
 
 ## Features
 
 ### Bitcoin Infrastructure
-- **Bitcoin Knots** full node with pruning support
-- **LND** Lightning Network daemon with channel management
+- **Bitcoin Core and Bitcoin Knots** full nodes with per-app version pinning and bulletproof version switching, automatic prune/full mode based on disk size
+- **LND** and **Core Lightning** with channel management
 - **ElectrumX** Electrum server for wallet connectivity
 - **BTCPay Server** for accepting Bitcoin payments
 - **Mempool** block explorer and fee estimator
-- **Fedimint** federation guardian and gateway
+- **Fedimint** federation guardian, gateway, and client — plus Cashu ecash wallet support
 
-### Self-Hosted Apps (29)
-Bitcoin, Storage (FileBrowser, Immich, Nextcloud), Productivity (Penpot, Vaultwarden), Media (Jellyfin, PhotoPrism), Search (SearXNG), AI (Ollama), Network (Tailscale, Nginx Proxy Manager), Home (Home Assistant), Nostr (nostr-rs-relay, Nostrudel), Dev (Grafana, Portainer), and more.
+### Self-Hosted Apps (50+)
+Storage (FileBrowser, Immich, Nextcloud), Productivity (Vaultwarden), Media (Jellyfin, PhotoPrism, IndeeHub), Search (SearXNG), Network (NetBird, Tailscale), Home (Home Assistant), Nostr (nostr-rs-relay, strfry), Dev/Ops (Gitea, Grafana, Portainer, Uptime Kuma), and more — 27 curated in the store UI, 50+ packaged as manifests.
+
+### Mesh Networking (tri-protocol)
+- **Meshtastic**, **MeshCore**, and **Reticulum (RNS/LXMF)** LoRa transports behind one mesh chat UI
+- End-to-end encryption with X3DH key agreement + double-ratchet
+- RNode radio support with an OS-level `archy-rnodeconf` tool; interop verified against Sideband
+- Image/voice attachments, mesh AI assistant (`!ai`), Bitcoin balance relay over mesh
 
 ### Decentralized Identity
 - Ed25519 node identity with DID Documents (did:key)
 - Multi-identity management (Personal/Business/Anonymous)
 - W3C Verifiable Credentials issuance and verification
-- Decentralized Web Node (DWN) with bidirectional sync over Tor
-- Nostr relay integration and NIP-07 signing for iframe apps
+- Nostr integration: NIP-33 node discovery, NIP-44/NIP-04 encryption, NIP-07 signer bridge for iframe apps, relay hosting
+- Decentralized Web Node (DWN) record sync between federated nodes over Tor
 
 ### Multi-Node Federation
 - Invite-based node joining over Tor hidden services
 - Trust levels (Trusted/Verified/Untrusted) with DID-based auth
-- Bidirectional DWN state sync between federated nodes
-- File sharing with access controls (free/peers-only/paid)
-
-### Mesh Networking
-- LoRa radio communication via Meshcore protocol
-- Device discovery and mesh routing
-- Off-grid Bitcoin balance checks (planned)
+- State sync and app deployment across federated nodes
+- File sharing with access controls (free/peers-only/paid via Lightning, on-chain, or ecash)
 
 ### System Updates
-- OTA updates from self-hosted Gitea (git.tx1138.com) with SHA256 verification
-- Three update modes: Manual, Daily Check, Auto Apply (3 AM window)
-- Rollback support with automatic backup before applying
-- Full UI for update management in Settings
+- OTA updates from a self-hosted Gitea release server, Ed25519-signature-verified against a pinned release-root key
+- Resumable downloads, automatic pre-update backup, rollback with a post-update self-verify window
+- Manual, scheduled-check, and auto-apply modes (auto-apply refuses unsigned manifests)
 
 ### Security
-- ChaCha20-Poly1305 encrypted secrets at rest, Argon2id password hashing
-- Rootless Podman: read-only root, cap-drop ALL, non-root user, no-new-privileges
-- TOTP two-factor authentication
-- Per-endpoint rate limiting, CSRF protection, input validation
-- AppArmor profiles for container confinement
-- Tor hidden services for all inter-node communication
-- All crypto and container dependencies pinned to exact versions
-- Full penetration test completed (33 findings, all remediated)
+- Argon2id password hashing (transparent upgrade from legacy hashes), ChaCha20-Poly1305 encrypted secrets at rest
+- Rootless Podman: read-only root, cap-drop ALL with a reviewed allow-list, no-new-privileges
+- Signed release manifests and signed app catalog (Ed25519, pinned trust anchor)
+- TOTP two-factor authentication, per-endpoint rate limiting, CSRF protection
+- AppArmor profiles for container confinement; Tor hidden services for inter-node traffic
+- Independent security audit of an early version archived in [`docs/archive/`](docs/archive/security-code-audit-2026-03.md); top findings since remediated
+
+## Roadmap
+
+**Done**
+- Single-node production gate **green** — install / stop / start / restart / reinstall / reboot-survive / uninstall, 5 consecutive full runs with zero failures on real hardware
+- Quadlet migration validated (all backends as `user.slice` services on the canary node)
+- Release signing ceremony completed — release-root key pinned, catalog and OTA manifests signed
+- Reticulum third mesh transport (real-RF LoRa gates passed), Bitcoin Core/Knots multi-version switching, decentralized marketplace backend, public demo
+
+**In progress**
+- Multinode pass: the same production gate across the whole test fleet ([`docs/multinode-testing-plan.md`](docs/multinode-testing-plan.md))
+- Quadlet default flip fleet-wide + container-flapping elimination
+- 1.8.0 release hardening tail ([`docs/1.8.0-RELEASE-HARDENING-PLAN.md`](docs/1.8.0-RELEASE-HARDENING-PLAN.md)): OTA upgrade soak on real hardware, ISO/image hardening (per-device keys, no default creds, signed ISO)
+
+**Planned**
+- Developer CLI (`archy app validate/render/install/test`) to open third-party app publishing
+- External marketplace trust UX + publishing tooling ([`docs/marketplace-protocol.md`](docs/marketplace-protocol.md))
+- DHT/P2P distribution of releases and app images ([`docs/dht-distribution-design.md`](docs/dht-distribution-design.md))
+- P2P encrypted voice/video over Tor, dual-ecash (Fedimint + Cashu) phases, paid streaming, hardware signer support
+
+The live, priority-ordered task list is [`docs/UNIFIED-TASK-TRACKER.md`](docs/UNIFIED-TASK-TRACKER.md); the full narrative plan is [`docs/PRODUCTION-MASTER-PLAN.md`](docs/PRODUCTION-MASTER-PLAN.md).
 
 ## Quick Start
 
 ### Install from ISO
 
-1. Download the ISO for your architecture (x86_64 or ARM64)
+1. Build or download the ISO for your architecture (x86_64 or ARM64) — see [`image-recipe/`](image-recipe/)
 2. Flash to USB drive with Balena Etcher or `dd`
-3. Boot from USB on target hardware
-4. Follow the automated installer
-5. Access the web UI at `http://<device-ip>`
-6. Set your password and start the onboarding wizard
+3. Boot from USB on target hardware and follow the automated installer
+4. Access the web UI at `http://<device-ip>`
+5. Set your password and complete the onboarding wizard (seed backup, DID identity)
 
 ### Supported Hardware
 
@@ -75,7 +103,7 @@ Bitcoin, Storage (FileBrowser, Immich, Nextcloud), Productivity (Penpot, Vaultwa
 | **x86_64** | Intel NUC, mini PCs, any 64-bit PC | 4GB RAM, 32GB storage |
 | **ARM64** | Raspberry Pi 5, ARM64 SBCs | 4GB RAM, 32GB storage |
 
-**Recommended**: 8GB+ RAM, 1TB+ NVMe SSD (for full Bitcoin node)
+**Recommended**: 8GB+ RAM, 1TB+ NVMe SSD (for a full Bitcoin node). Optional: an RNode-compatible LoRa radio for mesh networking.
 
 ## Development
 
@@ -94,7 +122,15 @@ npm run type-check # TypeScript validation
 npm run build      # Production build → web/dist/neode-ui/
 ```
 
-### Deploy to Server
+### Backend Development
+
+```bash
+cd core            # Rust workspace root (no Cargo.toml at repo root)
+cargo build
+cargo test
+```
+
+### Deploy to a Test Node
 
 ```bash
 ./scripts/deploy-to-target.sh --live   # Deploy to primary dev server
@@ -104,54 +140,57 @@ npm run build      # Production build → web/dist/neode-ui/
 ### Release (tarball-only)
 
 Releases ship as a backend binary and a frontend tarball referenced by
-`releases/manifest.json`. Nodes OTA-update via `scripts/self-update.sh`.
+`releases/manifest.json`, published to the self-hosted Gitea release server.
 
 ```bash
 ./scripts/create-release.sh 1.2.3
-git push gitea-local main --tags
-git push gitea-vps2 main --tags
+git push origin main --tags
 ```
 
-ISO builds are archived under `image-recipe/_archived/` and not part of the
-release deliverable.
-
 ## Architecture
 
 ```
 Debian 13 (Trixie)
-  ├── Rootless Podman (30 containers, archy-net DNS)
+  ├── Rootless Podman — every app a systemd Quadlet unit under user.slice
   ├── Nginx (reverse proxy, security headers, rate limiting)
-  ├── Rust Backend (JSON-RPC API on 127.0.0.1:5678)
-  │     ├── core/archipelago/  — RPC endpoints, auth, identity, federation, mesh
-  │     ├── core/container/    — PodmanClient (REST API socket), manifests, health
-  │     ├── core/security/     — AppArmor, secrets, Cosign image verification
-  │     └── 6 more crates      — models, helpers, js-engine, performance, etc.
-  ├── Vue 3 Frontend (Composition API + TypeScript strict + Pinia + Tailwind)
+  ├── Rust Backend (JSON-RPC API on 127.0.0.1:5678, ~380 RPC methods)
+  │     ├── core/archipelago/  — API, orchestrator + reconciler, mesh, identity,
+  │     │                        federation, wallet, updates, marketplace
+  │     ├── core/container/    — Podman client, manifest schema, Quadlet compiler,
+  │     │                        health monitor, signed app catalog
+  │     ├── core/security/     — AppArmor/seccomp policy, secrets manager
+  │     ├── core/openwrt/      — TollGate gateway provisioning (SSH/UCI)
+  │     └── core/performance/  — resource limits
+  ├── Vue 3 Frontend (Composition API + TypeScript strict + Pinia + Tailwind, PWA)
+  │     └── Three UI modes (Pro/Easy/Chat) + gamepad navigation + i18n
+  ├── Reticulum daemon (supervised Python/PyInstaller, one per LoRa radio)
   └── System Tor (hidden services, SOCKS5 proxy)
 ```
 
-~49,000 lines of Rust | ~47,000 lines of TypeScript/Vue | 78 shell scripts | 30 container apps
+~117,000 lines of Rust | ~69,000 lines of TypeScript/Vue | 51 packaged apps | Android companion app
 
 ## Documentation
 
 | Doc | Purpose |
 |-----|---------|
-| [Architecture](docs/architecture.md) | System design, codebase stats, data paths |
-| [Architecture Review (HTML)](docs/architecture-review.html) | Interactive guide with diagrams and learning path |
+| [Architecture](docs/architecture.md) | System design, crate map, data paths |
 | [Developer Guide](docs/developer-guide.md) | Dev setup, workflow, code conventions |
-| [API Reference](docs/api-reference.md) | Complete RPC endpoint reference |
+| [API Reference](docs/api-reference.md) | RPC endpoint reference |
 | [App Developer Guide](docs/app-developer-guide.md) | Building and publishing apps |
+| [App Manifest Spec](docs/app-manifest-spec.md) | The `manifest.yml` schema |
 | [User Walkthrough](docs/user-walkthrough.md) | End-user installation and usage guide |
 | [Troubleshooting](docs/troubleshooting.md) | Diagnostic scenarios and solutions |
 | [Operations Runbook](docs/operations-runbook.md) | Ops commands and emergency recovery |
-| [Security Audit](docs/security-code-audit-2026-03.md) | Penetration test findings |
-| [Master Plan](docs/MASTER_PLAN.md) | Phased roadmap and task tracking |
+| [Production Master Plan](docs/PRODUCTION-MASTER-PLAN.md) | North star and workstream narrative |
+| [Unified Task Tracker](docs/UNIFIED-TASK-TRACKER.md) | Live, priority-ordered open items |
+| [Test Gate](tests/lifecycle/TESTING.md) | Production lifecycle test gate (definition of done) |
+| [Archive](docs/archive/) | Historical audits, session logs, shipped designs |
 
 ## Contributing
 
 1. Fork the repository
 2. Create a feature branch (`feature/description`)
-3. Follow the coding standards in [CLAUDE.md](CLAUDE.md)
+3. Follow the coding standards in [CONTRIBUTING.md](CONTRIBUTING.md) and [CLAUDE.md](CLAUDE.md)
 4. Submit a pull request
 
 ## License
@@ -160,4 +199,4 @@ Debian 13 (Trixie)
 
 ## Acknowledgments
 
-Built with: [Rust](https://www.rust-lang.org/), [Vue.js](https://vuejs.org/), [Podman](https://podman.io/), [Bitcoin Core](https://bitcoin.org/), [LND](https://lightning.engineering/), [Debian](https://www.debian.org/)
+Built with: [Rust](https://www.rust-lang.org/), [Vue.js](https://vuejs.org/), [Podman](https://podman.io/), [Bitcoin Core](https://bitcoin.org/), [LND](https://lightning.engineering/), [Reticulum](https://reticulum.network/), [Debian](https://www.debian.org/)

app-catalog/README.md

@@ -21,7 +21,7 @@ Add an entry to `catalog.json`:
   "icon": "/assets/img/app-icons/my-app.svg",
   "author": "Author",
   "category": "data",
-  "dockerImage": "git.tx1138.com/lfg2025/my-app:1.0.0",
+  "dockerImage": "146.59.87.168:3000/lfg2025/my-app:1.0.0",
   "repoUrl": "https://github.com/...",
   "containerConfig": {
     "ports": ["8080:8080"],

app-catalog/catalog.json

@@ -39,7 +39,7 @@
       "title": "LND",
       "version": "0.18.4",
       "description": "Lightning Network implementation by Lightning Labs. Enables instant, low-cost Bitcoin payments.",
-      "icon": "/assets/img/app-icons/lnd.svg",
+      "icon": "/assets/img/app-icons/lnd.png",
       "author": "Lightning Labs",
       "category": "money",
       "tier": "core",
@@ -172,7 +172,7 @@
       "author": "File Browser",
       "category": "data",
       "tier": "core",
-      "dockerImage": "git.tx1138.com/lfg2025/filebrowser:v2.27.0",
+      "dockerImage": "146.59.87.168:3000/lfg2025/filebrowser:v2.27.0",
       "repoUrl": "https://github.com/filebrowser/filebrowser",
       "containerConfig": {
         "ports": [
@@ -195,7 +195,7 @@
       "title": "Nostr Relay (Rust)",
       "version": "0.8.0",
       "description": "High-performance Nostr relay written in Rust. Host your own decentralized social media relay and earn networking profits.",
-      "icon": "/assets/img/app-icons/nostr.svg",
+      "icon": "/assets/img/app-icons/nostrudel.svg",
       "author": "Nostr RS Relay",
       "category": "community",
       "tier": "recommended",
@@ -214,31 +214,6 @@
         ]
       }
     },
-    {
-      "id": "meshtastic",
-      "title": "Meshtastic",
-      "version": "2-daily-alpine",
-      "description": "Open-source mesh networking for LoRa radios. Create decentralized communication networks.",
-      "icon": "/assets/img/app-icons/meshcore.svg",
-      "author": "Meshtastic",
-      "category": "networking",
-      "tier": "recommended",
-      "dockerImage": "docker.io/meshtastic/meshtasticd:daily-alpine",
-      "repoUrl": "https://github.com/meshtastic/firmware",
-      "containerConfig": {
-        "ports": [
-          "4403:4403"
-        ],
-        "volumes": [
-          "/var/lib/archipelago/meshtastic:/var/lib/meshtasticd"
-        ],
-        "env": [
-          "MESHTASTIC_PORT=/dev/ttyUSB0",
-          "MESHTASTIC_SERIAL=true"
-        ],
-        "notes": "Requires a LoRa radio device at /dev/ttyUSB0. The config file is rendered from the app manifest before container start."
-      }
-    },
     {
       "id": "vaultwarden",
       "title": "Vaultwarden",
@@ -294,12 +269,12 @@
       "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.",
+      "description": "Fedimint ecash client daemon (fmcd). Lets the node hold Fedimint ecash and join federations; the wallet talks to it over a local REST API.",
       "icon": "/assets/img/app-icons/fedimint.png",
       "author": "Fedimint",
       "category": "money",
       "tier": "core",
-      "dockerImage": "146.59.87.168:3000/lfg2025/fmcd:0.8.0",
+      "dockerImage": "146.59.87.168:3000/lfg2025/fmcd:0.8.1",
       "repoUrl": "https://github.com/minmoto/fmcd"
     },
     {
@@ -310,7 +285,7 @@
       "icon": "/assets/img/app-icons/fedimint.png",
       "author": "Fedimint",
       "category": "money",
-      "dockerImage": "git.tx1138.com/lfg2025/gatewayd:v0.10.0",
+      "dockerImage": "146.59.87.168:3000/lfg2025/gatewayd:v0.10.0",
       "repoUrl": "https://github.com/fedimint/fedimint",
       "containerConfig": {
         "ports": [
@@ -323,6 +298,25 @@
         ]
       }
     },
+    {
+      "id": "barkd",
+      "title": "Ark Wallet",
+      "version": "0.3.0",
+      "description": "Ark protocol wallet daemon (barkd). Lets the node hold self-custodial off-chain bitcoin via an Ark server; the wallet talks to it over a local REST API. Signet by default while Ark matures.",
+      "icon": "/assets/img/app-icons/bark.png",
+      "author": "Second",
+      "category": "money",
+      "dockerImage": "146.59.87.168:3000/lfg2025/barkd:0.3.0",
+      "repoUrl": "https://gitlab.com/ark-bitcoin/bark",
+      "containerConfig": {
+        "ports": [
+          "3535:3535"
+        ],
+        "volumes": [
+          "/var/lib/archipelago/barkd:/data"
+        ]
+      }
+    },
     {
       "id": "jellyfin",
       "title": "Jellyfin",
@@ -346,8 +340,8 @@
     {
       "id": "immich",
       "title": "Immich",
-      "version": "1.90.0",
-      "description": "High-performance photo and video backup with ML.",
+      "version": "2.7.4",
+      "description": "Self-hosted photo and video backup with mobile apps and search.",
       "icon": "/assets/img/app-icons/immich.png",
       "author": "Immich",
       "category": "data",
@@ -357,12 +351,12 @@
     {
       "id": "homeassistant",
       "title": "Home Assistant",
-      "version": "2024.1.0",
+      "version": "2026.7.3",
       "description": "Open source home automation platform. Control and monitor your smart home devices.",
       "icon": "/assets/img/app-icons/homeassistant.png",
       "author": "Home Assistant",
       "category": "home",
-      "dockerImage": "146.59.87.168:3000/lfg2025/home-assistant:2024.1",
+      "dockerImage": "146.59.87.168:3000/lfg2025/home-assistant:2026.7.3",
       "repoUrl": "https://github.com/home-assistant/core",
       "containerConfig": {
         "ports": [
@@ -376,6 +370,17 @@
         ]
       }
     },
+    {
+      "id": "pine",
+      "title": "Pine",
+      "version": "1.3.0",
+      "description": "A private voice assistant for your home. Pine runs speech-to-text (Whisper), text-to-speech (Piper) and wake-word detection (openWakeWord) on your own node and pairs with a PineVoice satellite speaker, so Home Assistant Assist works locally with nothing sent to the cloud. Ask it about your node — block height, sync, peers, Lightning balance — and, when a Claude API key is set, anything else.",
+      "icon": "/assets/img/app-icons/pine.svg",
+      "author": "Archipelago",
+      "category": "home",
+      "dockerImage": "docker.io/library/nginx:1.27-alpine",
+      "repoUrl": "https://github.com/rhasspy/wyoming"
+    },
     {
       "id": "grafana",
       "title": "Grafana",
@@ -453,13 +458,13 @@
     {
       "id": "netbird",
       "title": "NetBird",
-      "version": "0.71.2",
-      "description": "Self-hosted WireGuard mesh VPN control plane with dashboard, embedded identity provider, management API, signal, relay, and STUN service.",
+      "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.",
       "icon": "/assets/img/app-icons/netbird.svg",
       "author": "NetBird",
       "category": "networking",
       "tier": "recommended",
-      "dockerImage": "docker.io/netbirdio/dashboard:v2.38.0",
+      "dockerImage": "docker.io/library/nginx:1.27-alpine",
       "repoUrl": "https://github.com/netbirdio/netbird",
       "containerConfig": {
         "ports": [

apps/README.md

@@ -31,7 +31,7 @@ Containerized applications for the Archipelago Bitcoin Node OS. All apps run in
 ### Custom & External
 - **indeedhub** — Bitcoin documentary streaming (custom build)
 - **router** — Mesh routing and network management
-- **botfights**, **nwnn**, **484-kitchen**, **call-the-operator**, **arch-presentation**, **syntropy-institute**, **t-zero** — External web apps
+- **botfights** — External web app
 
 ## Manifest Format
 

apps/archy-btcpay-db/manifest.yml

@@ -1,11 +1,11 @@
 app:
   id: archy-btcpay-db
   name: BTCPay Postgres
-  version: 15.17
+  version: "15.17"
   description: Postgres backend for BTCPay and NBXplorer.
 
   container:
-    image: git.tx1138.com/lfg2025/postgres:15.17
+    image: 146.59.87.168:3000/lfg2025/postgres:15.17
     pull_policy: if-not-present
     network: archy-net
     data_uid: "100998:100998"

apps/archy-mempool-db/manifest.yml

@@ -5,7 +5,7 @@ app:
   description: MariaDB backend for the mempool explorer stack.
 
   container:
-    image: git.tx1138.com/lfg2025/mariadb:11.4.10
+    image: 146.59.87.168:3000/lfg2025/mariadb:11.4.10
     pull_policy: if-not-present
     network: archy-net
     data_uid: "100998:100998"

apps/archy-mempool-web/manifest.yml

@@ -33,7 +33,10 @@ app:
 
   health_check:
     type: http
-    endpoint: http://localhost:8080
+    # 127.0.0.1 not localhost: the image's wget resolves localhost to ::1 (IPv6)
+    # first, but nginx binds 0.0.0.0:8080 (IPv4) only -> localhost probe gets
+    # "connection refused" -> perpetual unhealthy -> health_monitor restart loop.
+    endpoint: http://127.0.0.1:8080
     path: /
     interval: 30s
     timeout: 5s

apps/archy-nbxplorer/manifest.yml

@@ -5,7 +5,7 @@ app:
   description: BTCPay blockchain indexer service.
 
   container:
-    image: git.tx1138.com/lfg2025/nbxplorer:2.6.0
+    image: 146.59.87.168:3000/lfg2025/nbxplorer:2.6.0
     pull_policy: if-not-present
     network: archy-net
     secret_env:

apps/barkd/Dockerfile

@@ -0,0 +1,32 @@
+# barkd — Ark protocol wallet daemon (https://gitlab.com/ark-bitcoin/bark).
+# No official upstream image exists (their GitLab registry is empty), so we
+# package the pinned, checksum-verified release binary ourselves and push to
+# the node registry — same approach as fmcd. Keep the version in lockstep with
+# the REST shapes coded in core/archipelago/src/wallet/ark_client.rs (0.3.0).
+FROM debian:bookworm-slim
+
+ARG BARKD_VERSION=0.3.0
+ARG BARKD_SHA256=8562fa27386bae666ed62fa95c92d40f7bdb20d22525f75799adfc16adaaedb3
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends ca-certificates curl && \
+    curl -fsSL "https://gitlab.com/api/v4/projects/ark-bitcoin%2Fbark/packages/generic/release-assets/bark-${BARKD_VERSION}/barkd-${BARKD_VERSION}-linux-x86_64" \
+        -o /usr/local/bin/barkd && \
+    echo "${BARKD_SHA256}  /usr/local/bin/barkd" | sha256sum -c - && \
+    chmod a+x /usr/local/bin/barkd && \
+    apt-get purge -y curl && apt-get autoremove -y && \
+    apt-get clean && rm -rf /var/lib/apt/lists/*
+
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod a+x /entrypoint.sh
+
+# The wallet itself is created over REST by the node's Ark bridge
+# (wallet.ark-* RPCs) — the container just runs the daemon.
+ENV BARKD_DATADIR=/data \
+    BARKD_BIND_HOST=0.0.0.0 \
+    BARKD_BIND_PORT=3535
+
+EXPOSE 3535
+VOLUME /data
+
+ENTRYPOINT ["/entrypoint.sh"]

apps/barkd/entrypoint.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Install the node-provided auth secret (64-char hex from the manifest's
+# generated barkd-secret) so the wallet bridge can derive the matching Bearer
+# token, then start the daemon. Without BARKD_SECRET, barkd generates its own
+# random token in the datadir and the bridge won't authenticate — so treat a
+# failed refresh as fatal rather than starting an unreachable daemon.
+set -eu
+
+if [ -n "${BARKD_SECRET:-}" ]; then
+    # `secret refresh` prints the Bearer token on stdout — never log it.
+    barkd secret refresh --secret "$BARKD_SECRET" >/dev/null
+    unset BARKD_SECRET
+fi
+
+exec barkd

apps/barkd/manifest.yml

@@ -0,0 +1,76 @@
+app:
+  id: barkd
+  name: Ark Wallet
+  version: 0.3.0
+  description: Ark protocol wallet daemon (barkd). Lets the node hold self-custodial off-chain bitcoin via an Ark server; the wallet talks to it over a local REST API. Signet by default while Ark matures.
+
+  container:
+    # barkd packaged from the pinned upstream release binary (no usable
+    # upstream image exists — their registry is empty). Built from
+    # apps/barkd/Dockerfile and pushed to the node registry. Pin the tag to
+    # match the REST shapes coded in core/archipelago/src/wallet/ark_client.rs
+    # (validated against barkd 0.3.0 on signet, 2026-07-14).
+    image: 146.59.87.168:3000/lfg2025/barkd:0.3.0
+    pull_policy: if-not-present
+    network: archy-net
+    # The entrypoint installs the shared secret below via `barkd secret
+    # refresh` (so the wallet bridge can derive the matching Bearer token) and
+    # execs the daemon. The Ark wallet itself is created over REST by the
+    # bridge on first use (wallet.ark-* RPCs) with the node's ark_config
+    # (default: Second's public signet server) — no host provisioning needed.
+    generated_secrets:
+      - name: barkd-secret
+        kind: hex32
+    secret_env:
+      - key: BARKD_SECRET
+        secret_file: barkd-secret
+    data_uid: "1000:1000"
+
+  dependencies:
+    - storage: 1Gi
+
+  resources:
+    # barkd is a single wallet daemon (SQLite + a gRPC conn to the Ark server
+    # + esplora polling); steady state is tiny. Cap it so a stuck sync can't
+    # starve the node.
+    cpu_limit: 1
+    memory_limit: 512Mi
+    disk_limit: 1Gi
+
+  security:
+    readonly_root: true
+    # Needs outbound HTTPS to the Ark server (ark.signet.2nd.dev) and the
+    # esplora chain source, plus the published REST port for the wallet
+    # bridge. No inbound requirements beyond that.
+    network_policy: bridge
+
+  ports:
+    # barkd REST bound to 3535 in-container (BARKD_BIND_PORT); 3535 is free on
+    # the host (see port_allocator.rs). The Rust bridge targets
+    # http://127.0.0.1:3535.
+    - host: 3535
+      container: 3535
+      protocol: tcp
+
+  volumes:
+    # Holds the wallet DB, mnemonic and auth token. ARK funds are recoverable
+    # on-chain from this datadir (unilateral exit) — include it in backups.
+    - type: bind
+      source: /var/lib/archipelago/barkd
+      target: /data
+      options: [rw]
+
+  environment:
+    - BARKD_DATADIR=/data
+    - BARKD_BIND_HOST=0.0.0.0
+    - BARKD_BIND_PORT=3535
+
+  # All /api/v1/* routes require the Bearer token, so an HTTP probe would 401
+  # forever — use a TCP probe like fmcd (the host-side lifecycle layer
+  # verifies reachability).
+  health_check:
+    type: tcp
+    endpoint: localhost:3535
+    interval: 30s
+    timeout: 5s
+    retries: 3

apps/bitcoin-core/Dockerfile

@@ -1,5 +1,34 @@
-# Bitcoin Core - uses official image
-FROM bitcoin/bitcoin:24.0
-
-# Default user is already 'bitcoin'
-# No additional setup needed
+# Bitcoin Core — minimal rootless image built from the OFFICIAL upstream release.
+#
+# The CANONICAL, verified build path is scripts/build-bitcoin-image.sh, which
+# downloads the upstream tarball, verifies SHA-256 + the OpenPGP signature
+# (fail-closed), and tags/pushes <registry>/bitcoin:<version>. This Dockerfile
+# mirrors that image for a manual/local build and replaces the old stale
+# community base (`FROM bitcoin/bitcoin:24.0`).
+#
+# Build (binaries must be pre-fetched + verified into ./bin — see the script):
+#   scripts/build-bitcoin-image.sh core 31.0
+FROM debian:bookworm-slim
+ARG BITCOIN_VERSION=31.0
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends ca-certificates; \
+    rm -rf /var/lib/apt/lists/*; \
+    useradd -m -u 1000 -s /bin/bash bitcoin; \
+    mkdir -p /home/bitcoin/.bitcoin; \
+    chown -R bitcoin:bitcoin /home/bitcoin
+# bin/ holds the SHA-256 + GPG-verified bitcoind / bitcoin-cli (Guix-built,
+# x86_64-linux-gnu) extracted from the official release tarball.
+COPY bin/bitcoind /usr/local/bin/bitcoind
+COPY bin/bitcoin-cli /usr/local/bin/bitcoin-cli
+RUN chmod 0755 /usr/local/bin/bitcoind /usr/local/bin/bitcoin-cli
+# Run as (container) root, like the legacy hand-built :latest image. Rootless
+# Podman maps container-root to the unprivileged host service user; the manifest
+# grants CAP_DAC_OVERRIDE so bitcoind can read its data dir, which the
+# orchestrator chowns to the data_uid (host 100101 / container uid 102), not to
+# this image's `bitcoin` user. A non-root USER can't read existing chain data and
+# bitcoind crash-loops with "Error initializing block database".
+WORKDIR /home/bitcoin
+VOLUME ["/home/bitcoin/.bitcoin"]
+EXPOSE 8332 8333
+ENTRYPOINT ["bitcoind"]

apps/bitcoin-core/manifest.yml

@@ -17,6 +17,13 @@ app:
       # the IBD sweet spot - 4GB on full nodes, 1GB on pruned. Container
       # --memory=8g (config.rs::get_memory_limit) leaves headroom for
       # mempool + connections.
+      #
+      # -printtoconsole=0: foreground bitcoind defaults console logging ON,
+      # which pushed every IBD "UpdateTip" line through conmon into journald
+      # (>1 GB/day on a fresh node). bitcoind still writes debug.log in the
+      # datadir (/var/lib/archipelago/bitcoin/debug.log, self-shrunk on
+      # restart) — use that for deep debugging; podman logs only carries
+      # entrypoint/startup errors.
       - >-
         BITCOIND="$(command -v bitcoind || true)";
         if [ -z "$BITCOIND" ]; then
@@ -28,6 +35,9 @@ app:
         fi;
         RPC_USER="$(printenv BITCOIN_RPC_USER)";
         RPC_PASS="$(printenv BITCOIN_RPC_PASS)";
+        RPC_CONF="/tmp/rpc.conf";
+        umask 077;
+        { echo "rpcuser=$RPC_USER"; echo "rpcpassword=$RPC_PASS"; } > "$RPC_CONF";
         RPC_TXRELAY_AUTH="$(printenv BITCOIN_RPC_TXRELAY_RPCAUTH || true)";
         DISK_GB_VALUE="$(printenv DISK_GB || true)";
         RPC_HEADROOM="-rpcthreads=16 -rpcworkqueue=256";
@@ -36,9 +46,9 @@ app:
           RPC_TXRELAY_FLAGS="$RPC_TXRELAY_FLAGS -rpcauth=$RPC_TXRELAY_AUTH -rpcwhitelist=txrelay:sendrawtransaction,submitpackage,testmempoolaccept,getmempoolinfo,getrawmempool,getmempoolentry,getnetworkinfo,getblockchaininfo,getblockcount,getblockhash,getblock,getblockheader,getrawtransaction,gettxout,gettxspendingprevout,decoderawtransaction,decodescript,estimatesmartfee,uptime,ping,getconnectioncount,getpeerinfo,getindexinfo,getdeploymentinfo,getchaintips";
         fi;
         if [ "${DISK_GB_VALUE:-0}" -lt 1000 ]; then
-          exec "$BITCOIND" -datadir=/home/bitcoin/.bitcoin -noconf -server=1 -prune=550 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=1024 -par=0 -maxconnections=125 $RPC_HEADROOM $RPC_TXRELAY_FLAGS -rpcuser="$RPC_USER" -rpcpassword="$RPC_PASS";
+          exec "$BITCOIND" -datadir=/home/bitcoin/.bitcoin -conf="$RPC_CONF" -printtoconsole=0 -server=1 -prune=550 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=1024 -par=0 -maxconnections=125 $RPC_HEADROOM $RPC_TXRELAY_FLAGS;
         else
-          exec "$BITCOIND" -datadir=/home/bitcoin/.bitcoin -noconf -server=1 -txindex=1 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=4096 -par=0 -maxconnections=125 $RPC_HEADROOM $RPC_TXRELAY_FLAGS -rpcuser="$RPC_USER" -rpcpassword="$RPC_PASS";
+          exec "$BITCOIND" -datadir=/home/bitcoin/.bitcoin -conf="$RPC_CONF" -printtoconsole=0 -server=1 -txindex=1 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=4096 -par=0 -maxconnections=125 $RPC_HEADROOM $RPC_TXRELAY_FLAGS;
         fi
     derived_env:
       - key: DISK_GB
@@ -64,9 +74,17 @@ app:
     network_policy: isolated
 
   ports:
+    # RPC is auth-only: publish host-local ONLY - the LAN cannot reach
+    # nodeIP:8332. In-node consumers (lnd, fedimint, btcpay, mempool-api)
+    # dial the container's archy-net alias directly (bitcoin-core:8332),
+    # which needs no publish at all. Do NOT bind the archy-net gateway
+    # (10.89.0.1): rootlessport binds in the HOST netns where that address
+    # does not exist, and the whole unit crash-loops (2026-07-09, .228).
+    # P2P 8333 stays public.
     - host: 8332
       container: 8332
       protocol: tcp
+      bind: 127.0.0.1
     - host: 8333
       container: 8333
       protocol: tcp

apps/bitcoin-knots/Dockerfile

@@ -0,0 +1,35 @@
+# Bitcoin Knots — minimal rootless image built from the OFFICIAL upstream release.
+#
+# Knots previously had NO Dockerfile (the :latest tag was built/pushed by hand).
+# The CANONICAL, verified build path is scripts/build-bitcoin-image.sh, which
+# downloads the upstream tarball, verifies SHA-256 + the OpenPGP signature
+# (fail-closed, Luke-Jr release key), and tags/pushes
+# <registry>/bitcoin-knots:<version>. Knots version strings embed a build date,
+# e.g. 29.3.knots20260508 — the full string is the tag.
+#
+# Build (binaries must be pre-fetched + verified into ./bin — see the script):
+#   scripts/build-bitcoin-image.sh knots 29.3.knots20260508
+FROM debian:bookworm-slim
+ARG KNOTS_VERSION=29.3.knots20260508
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends ca-certificates; \
+    rm -rf /var/lib/apt/lists/*; \
+    useradd -m -u 1000 -s /bin/bash bitcoin; \
+    mkdir -p /home/bitcoin/.bitcoin; \
+    chown -R bitcoin:bitcoin /home/bitcoin
+# bin/ holds the SHA-256 + GPG-verified bitcoind / bitcoin-cli (Knots, Guix-built,
+# x86_64-linux-gnu) extracted from the official release tarball.
+COPY bin/bitcoind /usr/local/bin/bitcoind
+COPY bin/bitcoin-cli /usr/local/bin/bitcoin-cli
+RUN chmod 0755 /usr/local/bin/bitcoind /usr/local/bin/bitcoin-cli
+# Run as (container) root, like the legacy hand-built :latest image. Rootless
+# Podman maps container-root to the unprivileged host service user; the manifest
+# grants CAP_DAC_OVERRIDE so bitcoind can read its data dir, which the
+# orchestrator chowns to the data_uid (host 100101 / container uid 102), not to
+# this image's `bitcoin` user. A non-root USER can't read existing chain data and
+# bitcoind crash-loops with "Error initializing block database".
+WORKDIR /home/bitcoin
+VOLUME ["/home/bitcoin/.bitcoin"]
+EXPOSE 8332 8333
+ENTRYPOINT ["bitcoind"]

apps/bitcoin-knots/manifest.yml

@@ -17,6 +17,13 @@ app:
       # the IBD sweet spot - 4GB on full nodes, 1GB on pruned. Container
       # --memory=8g (config.rs::get_memory_limit) leaves headroom for
       # mempool + connections.
+      #
+      # -printtoconsole=0: foreground bitcoind defaults console logging ON,
+      # which pushed every IBD "UpdateTip" line through conmon into journald
+      # (>1 GB/day on a fresh node). bitcoind still writes debug.log in the
+      # datadir (/var/lib/archipelago/bitcoin/debug.log, self-shrunk on
+      # restart) — use that for deep debugging; podman logs only carries
+      # entrypoint/startup errors.
       - >-
         BITCOIND="$(command -v bitcoind || true)";
         if [ -z "$BITCOIND" ]; then
@@ -28,6 +35,9 @@ app:
         fi;
         RPC_USER="$(printenv BITCOIN_RPC_USER)";
         RPC_PASS="$(printenv BITCOIN_RPC_PASS)";
+        RPC_CONF="/tmp/rpc.conf";
+        umask 077;
+        { echo "rpcuser=$RPC_USER"; echo "rpcpassword=$RPC_PASS"; } > "$RPC_CONF";
         RPC_TXRELAY_AUTH="$(printenv BITCOIN_RPC_TXRELAY_RPCAUTH || true)";
         DISK_GB_VALUE="$(printenv DISK_GB || true)";
         RPC_HEADROOM="-rpcthreads=16 -rpcworkqueue=256";
@@ -36,9 +46,9 @@ app:
           RPC_TXRELAY_FLAGS="$RPC_TXRELAY_FLAGS -rpcauth=$RPC_TXRELAY_AUTH -rpcwhitelist=txrelay:sendrawtransaction,submitpackage,testmempoolaccept,getmempoolinfo,getrawmempool,getmempoolentry,getnetworkinfo,getblockchaininfo,getblockcount,getblockhash,getblock,getblockheader,getrawtransaction,gettxout,gettxspendingprevout,decoderawtransaction,decodescript,estimatesmartfee,uptime,ping,getconnectioncount,getpeerinfo,getindexinfo,getdeploymentinfo,getchaintips";
         fi;
         if [ "${DISK_GB_VALUE:-0}" -lt 1000 ]; then
-          exec "$BITCOIND" -datadir=/home/bitcoin/.bitcoin -noconf -server=1 -prune=550 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=2048 -par=0 -maxconnections=125 $RPC_HEADROOM $RPC_TXRELAY_FLAGS -rpcuser="$RPC_USER" -rpcpassword="$RPC_PASS";
+          exec "$BITCOIND" -datadir=/home/bitcoin/.bitcoin -conf="$RPC_CONF" -printtoconsole=0 -server=1 -prune=550 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=2048 -par=0 -maxconnections=125 $RPC_HEADROOM $RPC_TXRELAY_FLAGS;
         else
-          exec "$BITCOIND" -datadir=/home/bitcoin/.bitcoin -noconf -server=1 -txindex=1 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=4096 -par=0 -maxconnections=125 $RPC_HEADROOM $RPC_TXRELAY_FLAGS -rpcuser="$RPC_USER" -rpcpassword="$RPC_PASS";
+          exec "$BITCOIND" -datadir=/home/bitcoin/.bitcoin -conf="$RPC_CONF" -printtoconsole=0 -server=1 -txindex=1 -rpcallowip=0.0.0.0/0 -rpcbind=0.0.0.0:8332 -listen=1 -bind=0.0.0.0:8333 -dbcache=4096 -par=0 -maxconnections=125 $RPC_HEADROOM $RPC_TXRELAY_FLAGS;
         fi
     derived_env:
       - key: DISK_GB
@@ -64,9 +74,17 @@ app:
     network_policy: isolated
 
   ports:
+    # RPC is auth-only: publish host-local ONLY - the LAN cannot reach
+    # nodeIP:8332. In-node consumers (lnd, fedimint, btcpay, mempool-api)
+    # dial the container's archy-net alias directly (bitcoin-knots:8332),
+    # which needs no publish at all. Do NOT bind the archy-net gateway
+    # (10.89.0.1): rootlessport binds in the HOST netns where that address
+    # does not exist, and the whole unit crash-loops (2026-07-09, .228).
+    # P2P 8333 stays public.
     - host: 8332
       container: 8332
       protocol: tcp
+      bind: 127.0.0.1
     - host: 8333
       container: 8333
       protocol: tcp

apps/btcpay-server/manifest.yml

@@ -13,6 +13,12 @@ app:
         secret_file: bitcoin-rpc-password
       - key: BTCPAY_DB_PASS
         secret_file: btcpay-db-password
+      # Internal LND node. Generated by the daemon (lnd macaroon as hex +
+      # tls.cert thumbprint) — see container::lnd::ensure_btcpay_lnd_connection_secret.
+      # Optional: nodes without LND run btcpay without an internal node.
+      - key: BTCPAY_BTCLIGHTNING
+        secret_file: btcpay-lnd-connection
+        optional: true
     derived_env:
       - key: BTCPAY_HOST
         template: "{{HOST_IP}}:23000"
@@ -50,6 +56,10 @@ app:
     - ASPNETCORE_URLS=http://0.0.0.0:49392
     - BTCPAY_PROTOCOL=http
     - BTCPAY_CHAINS=btc
+    # Plugins must live on the persistent volume: the image default
+    # (/root/.btcpayserver/Plugins) is container-local, so every recreate
+    # silently wiped installed plugins.
+    - BTCPAY_PLUGINDIR=/datadir/Plugins
     - BTCPAY_BTCEXPLORERURL=http://archy-nbxplorer:32838
     - BTCPAY_BTCRPCURL=http://bitcoin-knots:8332
     - BTCPAY_BTCRPCUSER=archipelago

apps/did-wallet/manifest.yml

@@ -27,7 +27,7 @@ app:
     apparmor_profile: did-wallet
     
   ports:
-    - host: 8083
+    - host: 8088
       container: 8080
       protocol: tcp  # Web UI
     
@@ -42,7 +42,7 @@ app:
     
   health_check:
     type: http
-    endpoint: http://localhost:8083
+    endpoint: http://127.0.0.1:8080
     path: /health
     interval: 30s
     timeout: 5s

apps/electrumx/manifest.yml

@@ -10,9 +10,16 @@ app:
     network: archy-net
     data_uid: "1000:1000"
     entrypoint: ["sh", "-lc"]
+    # The bitcoin backend container is bitcoin-knots OR bitcoin-core depending
+    # on which version the node runs (multi-version switch) — probe which name
+    # resolves on archy-net instead of hardcoding knots, which left electrumx
+    # permanently disconnected (block index 0) on core nodes.
     custom_args:
       - >-
-        export DAEMON_URL="http://archipelago:$(printenv BITCOIN_RPC_PASS)@bitcoin-knots:8332/";
+        for h in bitcoin-knots bitcoin-core; do
+        if getent hosts "$h" >/dev/null 2>&1; then BTC_HOST="$h"; break; fi;
+        done;
+        export DAEMON_URL="http://archipelago:$(printenv BITCOIN_RPC_PASS)@${BTC_HOST:-bitcoin-knots}:8332/";
         exec electrumx_server
     secret_env:
       - key: BITCOIN_RPC_PASS
@@ -22,6 +29,7 @@ app:
     - app_id: bitcoin-knots
       version: ">=26.0"
     - storage: 50Gi
+    - bitcoin:archival
 
   resources:
     cpu_limit: 0

apps/fedimint-clientd/manifest.yml

@@ -9,7 +9,7 @@ app:
     # 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
+    image: 146.59.87.168:3000/lfg2025/fmcd:0.8.1
     pull_policy: if-not-present
     network: archy-net
     # No entrypoint override: the image's resilient `fmcd-run` launcher loops
@@ -33,6 +33,11 @@ app:
     - storage: 2Gi
 
   resources:
+    # fmcd's embedded iroh networking can hot-loop on relay/hole-punch retries
+    # on NAT'd nodes that reach the federation neither directly nor via iroh's
+    # public relays, pegging its whole allotment. Cap it low so a stuck instance
+    # can't starve the node (steady-state is <3% of a core; joins are brief);
+    # the fmcd-run watchdog additionally restarts a sustained-hot process.
     cpu_limit: 1
     memory_limit: 1Gi
     disk_limit: 2Gi

apps/fedimint-gateway/manifest.yml

@@ -5,17 +5,26 @@ app:
   description: Fedimint gateway service with automatic LND-or-LDK backend selection.
 
   container:
-    image: git.tx1138.com/lfg2025/gatewayd:v0.10.0
+    image: 146.59.87.168:3000/lfg2025/gatewayd:v0.10.0
     pull_policy: if-not-present
     network: archy-net
     entrypoint: ["sh", "-lc"]
+    # The bitcoind host comes from $FM_BITCOIND_URL, filled by the
+    # {{BITCOIN_HOST}} derived-env below — it resolves to whichever bitcoin
+    # container is actually running (Knots, Core, or any future distro archy
+    # ships), so the gateway is never pinned to one node's container name.
+    # (Was hardcoded http://host.archipelago:8332 — the host gateway IP where
+    # bitcoind does not listen — which crash-looped the gateway, 2026-07-22.)
     custom_args:
       - >-
         if [ -f /lnd/tls.cert ] && [ -f /lnd/data/chain/bitcoin/mainnet/admin.macaroon ]; then
-          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" lnd --lnd-rpc-host lnd:10009 --lnd-tls-cert /lnd/tls.cert --lnd-macaroon /lnd/data/chain/bitcoin/mainnet/admin.macaroon;
+          exec gatewayd --data-dir /data --listen 0.0.0.0:8176 --bcrypt-password-hash "$FEDI_HASH" --network bitcoin --bitcoind-url "$FM_BITCOIND_URL" --bitcoind-username "$FM_BITCOIND_USERNAME" --bitcoind-password "$FM_BITCOIND_PASSWORD" lnd --lnd-rpc-host lnd:10009 --lnd-tls-cert /lnd/tls.cert --lnd-macaroon /lnd/data/chain/bitcoin/mainnet/admin.macaroon;
         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;
+          exec gatewayd --data-dir /data --listen 0.0.0.0:8176 --bcrypt-password-hash "$FEDI_HASH" --network bitcoin --bitcoind-url "$FM_BITCOIND_URL" --bitcoind-username "$FM_BITCOIND_USERNAME" --bitcoind-password "$FM_BITCOIND_PASSWORD" ldk --ldk-lightning-port 9737 --ldk-alias archipelago-gateway;
         fi
+    derived_env:
+      - key: FM_BITCOIND_URL
+        template: "http://{{BITCOIN_HOST}}:8332"
     # 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

apps/fedimint/manifest.yml

@@ -21,6 +21,11 @@ app:
         template: fedimint://{{HOST_MDNS}}:8173
       - key: FM_API_URL
         template: ws://{{HOST_MDNS}}:8174
+      # Resolves to whichever bitcoin container is running (Knots/Core/future
+      # distro) instead of a hardcoded name — the guardian works on any node
+      # regardless of which Bitcoin software it runs.
+      - key: FM_BITCOIND_URL
+        template: "http://{{BITCOIN_HOST}}:8332"
     secret_env:
       - key: FM_BITCOIND_PASSWORD
         secret_file: bitcoin-rpc-password
@@ -62,7 +67,8 @@ app:
 
   environment:
     - FM_DATA_DIR=/data
-    - FM_BITCOIND_URL=http://bitcoin-knots:8332
+    # FM_BITCOIND_URL comes from derived_env ({{BITCOIN_HOST}}) above, not a
+    # hardcoded name — do not re-add it here.
     - FM_BITCOIND_USERNAME=archipelago
     - FM_BITCOIN_NETWORK=bitcoin
     - FM_BIND_P2P=0.0.0.0:8173

apps/filebrowser/manifest.yml

@@ -5,7 +5,7 @@ app:
   description: Baseline Archipelago file manager service.
 
   container:
-    image: git.tx1138.com/lfg2025/filebrowser:v2.27.0
+    image: 146.59.87.168:3000/lfg2025/filebrowser:v2.27.0
     pull_policy: if-not-present
     network: archy-net
     custom_args: ["--config", "/data/.filebrowser.json"]

apps/home-assistant/Dockerfile

@@ -1,5 +1,5 @@
 # Home Assistant - uses official image
-FROM homeassistant/home-assistant:2024.1
+FROM homeassistant/home-assistant:2026.7.3
 
 # Default configuration is in the image
 # No additional setup needed

apps/home-assistant/manifest.yml

@@ -1,11 +1,11 @@
 app:
   id: homeassistant
   name: Home Assistant
-  version: 2024.1.0
+  version: 2026.7.3
   description: Open source home automation platform. Control and monitor your smart home devices.
   
   container:
-    image: 146.59.87.168:3000/lfg2025/home-assistant:2024.1
+    image: 146.59.87.168:3000/lfg2025/home-assistant:2026.7.3
     pull_policy: if-not-present
     network: pasta
     

apps/immich/manifest.yml

@@ -30,7 +30,13 @@ app:
     disk_limit: 200Gi
 
   security:
-    capabilities: []
+    # Runs as container root over a data tree the legacy installer chowned
+    # to the subuid range (host 100000 = container uid 1). Without
+    # DAC_OVERRIDE the server EACCESes writing upload/encoded-video the
+    # moment the container is recreated against this manifest (latent until
+    # the 2026-07-05 secret-env migration recreated it). Same cap set as
+    # immich-postgres minus the setuid pair it doesn't use.
+    capabilities: [CHOWN, DAC_OVERRIDE, FOWNER]
     readonly_root: false
     network_policy: isolated
 

apps/indeedhub/push-to-registry.sh

@@ -12,7 +12,7 @@ set -e
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 FRONTEND_DIR="${INDEEHUB_FRONTEND:-$HOME/Projects/indeehub-frontend}"
 VERSION="${1:-latest}"
-REGISTRY="${REGISTRY:-git.tx1138.com}"
+REGISTRY="${REGISTRY:-146.59.87.168:3000}"
 NAMESPACE="${NAMESPACE:-lfg2025}"
 IMAGE_NAME="indeedhub"
 RUNTIME="${RUNTIME:-podman}"

apps/lightning-stack/manifest.yml

@@ -29,13 +29,13 @@ app:
     apparmor_profile: lightning-stack
     
   ports:
-    - host: 9737
+    - host: 9738
       container: 9735
       protocol: tcp  # P2P
     - host: 10010
       container: 10009
       protocol: tcp  # gRPC
-    - host: 8087
+    - host: 8091
       container: 8080
       protocol: tcp  # REST/Web UI
     
@@ -53,7 +53,7 @@ app:
     
   health_check:
     type: http
-    endpoint: http://localhost:8087
+    endpoint: http://127.0.0.1:8080
     path: /v1/getinfo
     interval: 30s
     timeout: 5s

apps/lnd/manifest.yml

@@ -8,6 +8,13 @@ app:
     image: 146.59.87.168:3000/lfg2025/lnd:v0.18.4-beta
     pull_policy: if-not-present
     network: archy-net
+    # BITCOIND_HOST must follow the node's actual Bitcoin container — Knots or
+    # Core — resolved at apply time from host facts. Hardcoding either breaks
+    # LND's chain backend connection on the other (lnd.conf is likewise
+    # resolved in lnd::ensure_config).
+    derived_env:
+      - key: BITCOIND_HOST
+        template: "{{BITCOIN_HOST}}"
     secret_env:
       - key: BITCOIND_RPCPASS
         secret_file: bitcoin-rpc-password
@@ -45,7 +52,6 @@ app:
       options: [rw]
 
   environment:
-    - BITCOIND_HOST=bitcoin-knots
     - BITCOIND_RPCUSER=archipelago
     - NETWORK=mainnet
 

apps/mempool-api/manifest.yml

@@ -5,7 +5,7 @@ app:
   description: Backend API for mempool explorer.
 
   container:
-    image: git.tx1138.com/lfg2025/mempool-backend:v3.0.0
+    image: 146.59.87.168:3000/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
@@ -27,6 +27,7 @@ app:
       version: ">=1.18.0"
     - app_id: archy-mempool-db
       version: ">=11.4.10"
+    - bitcoin:archival
 
   resources:
     memory_limit: 2Gi

apps/mempool/manifest.yml

@@ -13,6 +13,7 @@ app:
     - app_id: bitcoin-core
       version: ">=24.0"
     - storage: 20Gi
+    - bitcoin:archival
     
   resources:
     cpu_limit: 2
@@ -30,7 +31,7 @@ app:
     
   ports:
     - host: 4080
-      container: 4080
+      container: 8080  # mempool-frontend nginx listens on 8080 (FRONTEND_HTTP_PORT=8080)
       protocol: tcp  # Web UI
     
   volumes:

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/morphos-server/manifest.yml

@@ -27,7 +27,7 @@ app:
     apparmor_profile: morphos-server
     
   ports:
-    - host: 8086
+    - host: 8089
       container: 8080
       protocol: tcp  # Web UI
     
@@ -43,7 +43,7 @@ app:
     
   health_check:
     type: http
-    endpoint: http://localhost:8086
+    endpoint: http://127.0.0.1:8080
     path: /health
     interval: 30s
     timeout: 5s

apps/pine-openwakeword/manifest.yml

@@ -0,0 +1,70 @@
+app:
+  id: pine-openwakeword
+  name: Pine Wake Word (openWakeWord)
+  version: "2.1.0"
+  description: Wyoming-protocol openWakeWord wake-word engine. Internal Pine voice-assistant stack member — lets Assist pipelines run wake-word detection on the node (groundwork for the custom "Yo Archy" wake word; stock models like "ok nabu" ship with the image).
+  category: home
+
+  # Hyphen name matches the runtime references (stack member table / startup
+  # order) so the orchestrator adopts a matching running container instead of
+  # recreating it.
+  container_name: pine-openwakeword
+
+  container:
+    image: docker.io/rhasspy/wyoming-openwakeword:2.1.0
+    pull_policy: if-not-present
+    network: archy-net
+    network_aliases: [pine-openwakeword]
+    # The image entrypoint binds tcp://0.0.0.0:10400. Preload the stock
+    # "ok nabu" model; /custom is where a trained custom model (yo_archy)
+    # drops in later — the engine picks up new .tflite files on restart.
+    custom_args: ["--preload-model", "ok_nabu", "--custom-model-dir", "/custom"]
+
+  dependencies:
+    - storage: 512Mi
+
+  resources:
+    memory_limit: 512Mi
+
+  security:
+    # cap-drop=ALL is applied by the orchestrator. A plain Python Wyoming server
+    # on an unprivileged port needs no added capabilities.
+    capabilities: []
+    readonly_root: false
+    no_new_privileges: true
+    network_policy: isolated
+
+  ports:
+    # Published so Home Assistant (on the pasta net) can reach the engine via
+    # host.containers.internal:10400 (the Wyoming integration endpoint).
+    - host: 10400
+      container: 10400
+      protocol: tcp
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/pine-openwakeword
+      target: /custom
+      options: [rw]
+
+  environment: []
+
+  health_check:
+    type: tcp
+    endpoint: localhost:10400
+    interval: 30s
+    timeout: 5s
+    retries: 5
+    start_period: 30s
+
+  metadata:
+    author: Rhasspy / Home Assistant
+    icon: /assets/img/app-icons/pine.svg
+    website: https://github.com/rhasspy/wyoming-openwakeword
+    repo: https://github.com/rhasspy/wyoming-openwakeword
+    license: MIT
+    tags:
+      - home
+      - voice
+      - wake-word
+      - wyoming

apps/pine-piper/manifest.yml

@@ -0,0 +1,70 @@
+app:
+  id: pine-piper
+  name: Pine Piper (TTS)
+  version: "2.2.2"
+  description: Wyoming-protocol Piper text-to-speech engine. Internal Pine voice-assistant stack member — gives Home Assistant Assist a natural voice for spoken responses on the PineVoice satellite.
+  category: home
+
+  # Hyphen name matches the runtime references (stack member table / startup
+  # order) + the live container, so on an existing node the orchestrator ADOPTS
+  # the running engine rather than recreating it (downloaded voices under /data
+  # preserved).
+  container_name: pine-piper
+
+  container:
+    image: docker.io/rhasspy/wyoming-piper:2.2.2
+    pull_policy: if-not-present
+    network: archy-net
+    network_aliases: [pine-piper]
+    # The image entrypoint already binds tcp://0.0.0.0:10200; this arg only
+    # picks the voice (mirrors the pine ha-stack.yml compose command).
+    custom_args: ["--voice", "en_GB-alba-medium"]
+
+  dependencies:
+    - storage: 1Gi
+
+  resources:
+    memory_limit: 512Mi
+
+  security:
+    # cap-drop=ALL is applied by the orchestrator. A plain Python Wyoming server
+    # on an unprivileged port needs no added capabilities.
+    capabilities: []
+    readonly_root: false   # downloads the voice into /data on first run
+    no_new_privileges: true
+    network_policy: isolated
+
+  ports:
+    # Published so Home Assistant (on the pasta net) can reach the engine via
+    # host.containers.internal:10200 (the Wyoming integration endpoint).
+    - host: 10200
+      container: 10200
+      protocol: tcp
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/pine-piper
+      target: /data
+      options: [rw]
+
+  environment: []
+
+  health_check:
+    type: tcp
+    endpoint: localhost:10200
+    interval: 30s
+    timeout: 5s
+    retries: 5
+    start_period: 60s   # first start downloads the voice
+
+  metadata:
+    author: Rhasspy / Home Assistant
+    icon: /assets/img/app-icons/pine.svg
+    website: https://github.com/rhasspy/wyoming-piper
+    repo: https://github.com/rhasspy/wyoming-piper
+    license: MIT
+    tags:
+      - home
+      - voice
+      - text-to-speech
+      - wyoming

apps/pine-whisper/manifest.yml

@@ -0,0 +1,78 @@
+app:
+  id: pine-whisper
+  name: Pine Whisper (STT)
+  # App revision 3.4.2 = upstream wyoming-whisper 3.4.1 image + tuned args
+  # (--beam-size 1). Bumped past the image version so catalog-driven nodes
+  # pick up the args change; the pre-release form "3.4.1-1" would compare
+  # LOWER than 3.4.1 under semver and never roll out.
+  version: "3.4.2"
+  description: Wyoming-protocol faster-whisper speech-to-text engine. Internal Pine voice-assistant stack member — turns speech captured by a PineVoice satellite into text for Home Assistant Assist.
+  category: home
+
+  # Hyphen name matches the runtime references (stack member table / startup
+  # order) + the live container, so on an existing node the orchestrator ADOPTS
+  # the running engine rather than recreating it (downloaded models under /data
+  # preserved).
+  container_name: pine-whisper
+
+  container:
+    image: docker.io/rhasspy/wyoming-whisper:3.4.1
+    pull_policy: if-not-present
+    network: archy-net
+    network_aliases: [pine-whisper]
+    # The image entrypoint already binds tcp://0.0.0.0:10300; these args only
+    # pick the model + language (mirrors the pine ha-stack.yml compose command).
+    # --beam-size 1: the image default is 5 on x86 (1 on ARM). Benchmarked on
+    # framework-pt (i5-1135G7, base-int8): beam 1 transcribes the same text
+    # ~45% faster — the standard low-latency setting for short voice commands
+    # (HA's own whisper add-on defaults to 1).
+    custom_args: ["--model", "base-int8", "--language", "en", "--beam-size", "1"]
+
+  dependencies:
+    - storage: 2Gi
+
+  resources:
+    memory_limit: 2Gi
+
+  security:
+    # cap-drop=ALL is applied by the orchestrator. A plain Python Wyoming server
+    # on an unprivileged port needs no added capabilities.
+    capabilities: []
+    readonly_root: false   # downloads the whisper model into /data on first run
+    no_new_privileges: true
+    network_policy: isolated
+
+  ports:
+    # Published so Home Assistant (on the pasta net) can reach the engine via
+    # host.containers.internal:10300 (the Wyoming integration endpoint).
+    - host: 10300
+      container: 10300
+      protocol: tcp
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/pine-whisper
+      target: /data
+      options: [rw]
+
+  environment: []
+
+  health_check:
+    type: tcp
+    endpoint: localhost:10300
+    interval: 30s
+    timeout: 5s
+    retries: 5
+    start_period: 60s   # first start downloads the model
+
+  metadata:
+    author: Rhasspy / Home Assistant
+    icon: /assets/img/app-icons/pine.svg
+    website: https://github.com/rhasspy/wyoming-faster-whisper
+    repo: https://github.com/rhasspy/wyoming-faster-whisper
+    license: MIT
+    tags:
+      - home
+      - voice
+      - speech-to-text
+      - wyoming

apps/pine/manifest.yml

@@ -0,0 +1,395 @@
+app:
+  id: pine
+  name: Pine
+  version: "1.3.0"
+  description: A private voice assistant for your home. Pine runs speech-to-text (Whisper), text-to-speech (Piper) and wake-word detection (openWakeWord) on your own node and pairs with a PineVoice satellite speaker, so Home Assistant Assist works locally with nothing sent to the cloud. Ask it about your node — block height, sync, peers, Lightning balance — and, when a Claude API key is set, anything else.
+  category: home
+
+  # The user-facing launcher (app_id + container both "pine", matching the
+  # runtime references + the live container so the orchestrator adopts it). A
+  # tiny nginx that serves the "Connect Pine to WiFi" provisioner page for the
+  # voice stack. The two Wyoming engines (pine-whisper, pine-piper) are internal
+  # stack members.
+  container_name: pine
+
+  container:
+    image: docker.io/library/nginx:1.27-alpine
+    pull_policy: if-not-present
+    network: archy-net
+    network_aliases: [pine]
+    # The provisioner uses Web Bluetooth (Improv-over-BLE) to push WiFi creds to
+    # the PineVoice speaker. navigator.bluetooth only exists in a SECURE CONTEXT
+    # (https or localhost), so the launcher terminates TLS with a self-signed
+    # cert — otherwise the "Connect Pine to WiFi" button is inert on the LAN.
+    # Idempotent: kept as-is when crt+key already exist. Mirrors the netbird
+    # secure-context fix (#15).
+    generated_certs:
+      - crt: /var/lib/archipelago/pine/tls.crt
+        key: /var/lib/archipelago/pine/tls.key
+
+  dependencies:
+    - app_id: pine-whisper
+    - app_id: pine-piper
+    - app_id: pine-openwakeword
+    - storage: 128Mi
+
+  resources:
+    memory_limit: 64Mi
+
+  security:
+    # cap-drop=ALL is applied by the orchestrator. nginx (master as root, drops
+    # workers) binds :443 inside the container — needs the worker-drop caps +
+    # NET_BIND_SERVICE for the privileged port.
+    capabilities: [CHOWN, DAC_OVERRIDE, SETGID, SETUID, NET_BIND_SERVICE]
+    readonly_root: false
+    no_new_privileges: true
+    network_policy: isolated
+
+  ports:
+    # 10380 (http) is the Open target — the UI launches apps as
+    # http://host:10380 (resolveAppUrl). nginx there 301-redirects to the https
+    # listener on 10381, so the new tab lands on a secure context where
+    # navigator.bluetooth (the "Connect Pine to WiFi" provisioner) works.
+    - host: 10380
+      container: 80
+      protocol: tcp
+    - host: 10381
+      container: 443
+      protocol: tcp
+
+  volumes:
+    - type: bind
+      source: /var/lib/archipelago/pine/nginx.conf
+      target: /etc/nginx/conf.d/default.conf
+      options: [ro]
+    - type: bind
+      source: /var/lib/archipelago/pine/tls.crt
+      target: /etc/nginx/tls.crt
+      options: [ro]
+    - type: bind
+      source: /var/lib/archipelago/pine/tls.key
+      target: /etc/nginx/tls.key
+      options: [ro]
+    - type: bind
+      source: /var/lib/archipelago/pine/index.html
+      target: /usr/share/nginx/html/index.html
+      options: [ro]
+
+  environment: []
+
+  files:
+    - path: /var/lib/archipelago/pine/nginx.conf
+      overwrite: true
+      content: |
+        server {
+            listen 80;
+            server_name _;
+            return 301 https://$host:10381$request_uri;
+        }
+        server {
+            listen 443 ssl;
+            server_name _;
+            ssl_certificate /etc/nginx/tls.crt;
+            ssl_certificate_key /etc/nginx/tls.key;
+            root /usr/share/nginx/html;
+            index index.html;
+            # Live node facts for the status card — proxied to the node's
+            # public status tier so the (https) page can fetch same-origin.
+            location = /node-status {
+                proxy_pass http://host.containers.internal:80/api/pine/status;
+                proxy_http_version 1.1;
+                proxy_set_header Host $host;
+                proxy_connect_timeout 5s;
+                proxy_read_timeout 10s;
+            }
+            location / { try_files $uri $uri/ /index.html; }
+        }
+    - path: /var/lib/archipelago/pine/index.html
+      overwrite: true
+      content: |
+        <!doctype html>
+        <html lang="en">
+        <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>Pine — connect your speaker</title>
+          <style>
+            :root { color-scheme: dark; }
+            * { box-sizing: border-box; }
+            body { margin: 0; font: 16px/1.6 system-ui, -apple-system, sans-serif;
+                   background: #0f1512; color: #e7efe9; }
+            .wrap { max-width: 520px; margin: 0 auto; padding: 40px 22px 64px; }
+            header { display: flex; align-items: center; gap: 14px; margin-bottom: 6px; }
+            header svg { width: 52px; height: 52px; flex: 0 0 auto; }
+            h1 { font-size: 26px; margin: 0; }
+            .tag { color: #8fbfa5; font-size: 14px; margin: 2px 0 0; }
+            .card { background: #16201b; border: 1px solid #24332b;
+                    border-radius: 14px; padding: 20px; margin: 20px 0; }
+            .status .row { display: flex; gap: 10px; align-items: baseline; font-size: 14px; }
+            .status .row b { min-width: 84px; color: #9fd3b6; }
+            .status code { background: #0f1512; padding: 1px 6px; border-radius: 5px;
+                           font-size: 13px; color: #cfe9d9; }
+            label { display: block; font-size: 13px; color: #9fbfad; margin: 14px 0 5px; }
+            input { width: 100%; padding: 11px 12px; font-size: 15px; color: #e7efe9;
+                    background: #0f1512; border: 1px solid #2b3d33; border-radius: 9px;
+                    outline: none; }
+            input:focus { border-color: #4fae82; }
+            button { width: 100%; margin-top: 18px; padding: 13px; font-size: 15px;
+                     font-weight: 600; color: #06110b; background: #7fd6a6; border: 0;
+                     border-radius: 10px; cursor: pointer; transition: filter .15s; }
+            button:hover:not(:disabled) { filter: brightness(1.08); }
+            button:disabled { opacity: .45; cursor: default; }
+            #log { margin-top: 16px; padding: 12px; min-height: 68px; font-size: 13px;
+                   font-family: ui-monospace, monospace; white-space: pre-wrap;
+                   background: #0b100d; border: 1px solid #1e2a23; border-radius: 9px;
+                   color: #a9c6b6; max-height: 220px; overflow-y: auto; }
+            .ok { color: #7fd6a6; } .err { color: #ee8f8f; } .warn { color: #e8c878; }
+            .ha { color: #6d8578; font-size: 13px; margin-top: 22px; }
+            .ha b { color: #9fbfad; }
+            .insecure { display: none; background: #2a1f12; border-color: #4a3418;
+                        color: #e8c878; font-size: 13px; }
+          </style>
+        </head>
+        <body>
+          <div class="wrap">
+            <header>
+              <svg viewBox="0 0 512 512" aria-hidden="true"><g fill="#7fd6a6">
+                <rect x="236" y="396" width="40" height="72" rx="6"/>
+                <path d="M256 44 L336 168 L296 168 L256 108 L216 168 L176 168 Z"/>
+                <path d="M256 150 L360 300 L300 300 L256 236 L212 300 L152 300 Z"/>
+                <path d="M256 262 L392 430 L120 430 L256 262 Z"/>
+              </g></svg>
+              <div><h1>Pine</h1>
+                <p class="tag">Connect your speaker — everything stays on your node.</p></div>
+            </header>
+
+            <div class="card status">
+              <div class="row"><b>Whisper</b><span>speech-to-text ready on <code>:10300</code></span></div>
+              <div class="row"><b>Piper</b><span>text-to-speech ready on <code>:10200</code></span></div>
+              <div class="row"><b>Wake word</b><span>“Hey Jarvis” on the speaker (openWakeWord on <code>:10400</code>)</span></div>
+              <div class="row"><b>Speaker</b><span>put it in pairing mode — ring LED blinking yellow</span></div>
+            </div>
+
+            <div class="card status">
+              <div class="row"><b>Node</b><span id="ns-node">checking…</span></div>
+              <div class="row"><b>Bitcoin</b><span id="ns-btc">—</span></div>
+              <div class="row"><b>Peers</b><span id="ns-peers">—</span></div>
+            </div>
+
+            <div class="card insecure" id="insecure">
+              This page isn’t running over HTTPS, so the browser blocks Bluetooth.
+              Open it via its <b>https://…:10380</b> address (accept the self-signed
+              certificate) and the button below will work.
+            </div>
+
+            <div class="card">
+              <label for="ssid">WiFi network (SSID)</label>
+              <input id="ssid" autocomplete="off" spellcheck="false" placeholder="Your 2.4 GHz network">
+              <label for="pass">WiFi password — typed here, sent only over Bluetooth to the speaker</label>
+              <input id="pass" type="password" autocomplete="off">
+              <button id="go">Connect Pine to WiFi</button>
+              <div id="log">Ready. Click the button, then pick “PineVoice” in the Bluetooth popup.</div>
+            </div>
+
+            <p class="ha">After WiFi joins, one manual step remains — pair the
+              speaker in Home Assistant: <b>Settings → Devices &amp; services →
+              Add Wyoming Protocol</b>, host = the speaker’s IP, port
+              <b>10700</b>. Whisper, Piper, openWakeWord and the Assist pipeline
+              are wired up automatically when Pine installs. Wake word:
+              <b>“Hey Jarvis.”</b> Ask node things like <i>“what’s the block
+              height?”</i>, <i>“how many peers?”</i>, <i>“is the node
+              synced?”</i> or <i>“what’s my lightning balance?”</i> — and when a
+              Claude API key is set on the node, anything else gets answered by
+              Claude. New mesh messages are announced on the speaker too.</p>
+            <p class="ha">Troubleshooting: if it hears you (LED reacts) but answers
+              are silent, unplug and replug the speaker — an interrupted answer can
+              wedge its audio output until it reboots.</p>
+          </div>
+
+          <script>
+          "use strict";
+          // Improv-over-BLE (improv-wifi spec, verified vs improv-wifi-sdk 1.4.0).
+          const SVC   = "00467768-6228-2272-4663-277478268000";
+          const CHAR_STATE  = "00467768-6228-2272-4663-277478268001";
+          const CHAR_ERROR  = "00467768-6228-2272-4663-277478268002";
+          const CHAR_RPC    = "00467768-6228-2272-4663-277478268003";
+          const CHAR_RESULT = "00467768-6228-2272-4663-277478268004";
+          const STATES = {1:"authorization required",2:"authorized",3:"provisioning…",4:"PROVISIONED"};
+          const ERRORS = {1:"invalid RPC packet",2:"unknown RPC command",
+            3:"unable to connect — wrong password, or the SSID isn't reachable on 2.4 GHz",
+            4:"not authorized — press the button on the device",5:"bad hostname",
+            255:"unknown device error"};
+
+          const logEl = document.getElementById("log");
+          const log = (msg, cls) => { const l = document.createElement("div");
+            if (cls) l.className = cls; l.textContent = msg; logEl.appendChild(l);
+            logEl.scrollTop = logEl.scrollHeight; };
+          const hex = dv => [...new Uint8Array(dv.buffer, dv.byteOffset, dv.byteLength)]
+            .map(b => b.toString(16).padStart(2, "0")).join(" ");
+
+          const btn = document.getElementById("go");
+          if (!navigator.bluetooth) {
+            document.getElementById("insecure").style.display = "block";
+            logEl.textContent = "Web Bluetooth unavailable — open this page over https (see note above).";
+          }
+
+          btn.addEventListener("click", async () => {
+            const ssid = document.getElementById("ssid").value.trim();
+            const pass = document.getElementById("pass").value;
+            if (!ssid) { log("Enter your WiFi network name first.", "err"); return; }
+            if (!navigator.bluetooth) { log("No Web Bluetooth — open this page over https.", "err"); return; }
+            btn.disabled = true; logEl.textContent = "";
+            let device;
+            try {
+              log("Opening Bluetooth device chooser…");
+              device = await navigator.bluetooth.requestDevice({
+                filters: [{ services: [SVC] }, { namePrefix: "PineVoice" }],
+                optionalServices: [SVC],
+              });
+              log(`Selected: ${device.name || "(unnamed)"}`);
+              device.addEventListener("gattserverdisconnected", () => log("BLE disconnected."));
+              log("Connecting…");
+              const gatt = await device.gatt.connect();
+              const svc = await gatt.getPrimaryService(SVC);
+              const stateChar  = await svc.getCharacteristic(CHAR_STATE);
+              const errorChar  = await svc.getCharacteristic(CHAR_ERROR);
+              const rpcChar    = await svc.getCharacteristic(CHAR_RPC);
+              const resultChar = await svc.getCharacteristic(CHAR_RESULT);
+
+              let done, fail;
+              const outcome = new Promise((res, rej) => { done = res; fail = rej; });
+              let authorize; const authorized = new Promise(res => { authorize = res; });
+              let state = -1;
+              const onState = (s, via = "") => {
+                if (s === state) return; state = s;
+                log(`Device state${via}: ${STATES[s] || s}`, s === 4 ? "ok" : undefined);
+                if (s >= 2) authorize();
+                if (s === 4) done(null);
+              };
+              stateChar.addEventListener("characteristicvaluechanged",
+                e => onState(e.target.value.getUint8(0)));
+              errorChar.addEventListener("characteristicvaluechanged", e => {
+                const c = e.target.value.getUint8(0);
+                if (c !== 0) fail(new Error(ERRORS[c] || `error ${c}`)); });
+              resultChar.addEventListener("characteristicvaluechanged", e => {
+                const v = e.target.value; log(`RPC result: ${hex(v)}`);
+                if (v.byteLength > 2 && v.getUint8(1) > 0) {
+                  const n = v.getUint8(2); const b = new Uint8Array(n);
+                  for (let i = 0; i < n; i++) b[i] = v.getUint8(3 + i);
+                  done(new TextDecoder().decode(b)); } });
+              await stateChar.startNotifications();
+              await errorChar.startNotifications();
+              await resultChar.startNotifications();
+              onState((await stateChar.readValue()).getUint8(0));
+
+              const poller = setInterval(async () => {
+                try { onState((await stateChar.readValue()).getUint8(0), " (polled)");
+                  const ec = (await errorChar.readValue()).getUint8(0);
+                  if (ec !== 0) fail(new Error(ERRORS[ec] || `error ${ec}`)); } catch {} }, 2000);
+
+              let nextUrl;
+              try {
+                if (state === 1) {
+                  log("Authorization required — press the centre button on the speaker now.", "warn");
+                  await Promise.race([authorized, outcome,
+                    new Promise((_, rej) => setTimeout(
+                      () => rej(new Error("timed out waiting for the button press")), 60000))]);
+                  log("Authorized.", "ok");
+                }
+                const enc = new TextEncoder();
+                const sb = enc.encode(ssid), pb = enc.encode(pass);
+                const data = new Uint8Array([sb.length, ...sb, pb.length, ...pb]);
+                const pkt = new Uint8Array([1, data.length, ...data, 0]);
+                pkt[pkt.length - 1] = pkt.reduce((s, b) => s + b, 0);
+                log(`Sending WiFi credentials for “${ssid}”…`);
+                if (rpcChar.writeValueWithResponse) await rpcChar.writeValueWithResponse(pkt);
+                else await rpcChar.writeValue(pkt);
+                log("Credentials delivered — speaker acknowledged.", "ok");
+                log("Joining WiFi… (the speaker plays a sound within ~20s either way)");
+                const timeout = new Promise((_, rej) => setTimeout(
+                  () => rej(new Error("timed out after 60s waiting for the device")), 60000));
+                nextUrl = await Promise.race([outcome, timeout]);
+              } finally { clearInterval(poller); }
+
+              log("✓ PROVISIONED — the ring LED should breathe dim magenta.", "ok");
+              if (nextUrl) log(`Device reports next step: ${nextUrl}`, "ok");
+              try { gatt.disconnect(); } catch {}
+            } catch (err) {
+              log(`✗ ${err.name || "Error"}: ${err.message}`, "err");
+              if (err.name === "NotFoundError")
+                log("No speaker matched, or you closed the chooser. LED blinking yellow? "
+                  + "Hold the dot button 15s to reset.", "warn");
+              if (err.name === "NetworkError")
+                log("BLE link dropped — move closer, and make sure the Mac isn't already "
+                  + "paired to the speaker (it can hold the link exclusively).", "warn");
+              try { device?.gatt?.disconnect(); } catch {}
+            } finally { btn.disabled = false; }
+          });
+
+          // Live node status card — public tier of /api/pine/status via the
+          // same-origin /node-status proxy. Best-effort: failures just show
+          // "unavailable" and retry on the next tick.
+          const nsNode = document.getElementById("ns-node");
+          const nsBtc = document.getElementById("ns-btc");
+          const nsPeers = document.getElementById("ns-peers");
+          async function refreshNodeStatus() {
+            try {
+              const r = await fetch("/node-status", { cache: "no-store" });
+              if (!r.ok) throw new Error(String(r.status));
+              const s = await r.json();
+              const up = Math.floor((s.uptime_seconds || 0) / 3600);
+              nsNode.textContent = `Archipelago ${s.version || "?"} — up ${up}h`;
+              if (s.bitcoin && s.bitcoin.height != null) {
+                const pct = s.bitcoin.sync_percent;
+                nsBtc.textContent = `block ${s.bitcoin.height}` +
+                  (pct != null ? (pct >= 99.99 ? " — synced" : ` — ${pct}% synced`) : "");
+              } else {
+                nsBtc.textContent = "not running";
+              }
+              const btcPeers = s.bitcoin && s.bitcoin.peers != null ? s.bitcoin.peers : "?";
+              const meshPeers = s.mesh ? s.mesh.peers : 0;
+              nsPeers.textContent = `${btcPeers} bitcoin` +
+                (s.mesh && s.mesh.enabled ? `, ${meshPeers} mesh` : "");
+            } catch {
+              nsNode.textContent = "node status unavailable";
+              nsBtc.textContent = "—";
+              nsPeers.textContent = "—";
+            }
+          }
+          refreshNodeStatus();
+          setInterval(refreshNodeStatus, 30000);
+          </script>
+        </body>
+        </html>
+
+  health_check:
+    type: tcp
+    endpoint: localhost:443
+    interval: 30s
+    timeout: 5s
+    retries: 5
+    start_period: 10s
+
+  interfaces:
+    main:
+      name: Pine
+      description: Connect your speaker to WiFi and check the voice assistant
+      type: ui
+      port: 10380
+      protocol: http
+      path: /
+
+  metadata:
+    author: Archipelago
+    icon: /assets/img/app-icons/pine.svg
+    website: https://github.com/rhasspy/wyoming
+    repo: https://github.com/rhasspy/wyoming
+    license: MIT
+    category: home
+    launch:
+      open_in_new_tab: true
+    tags:
+      - home
+      - voice
+      - assistant
+      - privacy

apps/strfry/manifest.yml

@@ -3,51 +3,211 @@ app:
   name: Strfry Nostr Relay
   version: 0.9.0
   description: Lightweight Nostr relay written in C++. Alternative to nostr-rs-relay with lower resource usage.
-  
+
   container:
     image: dockurr/strfry:1.0.4
     image_signature: cosign://...
     pull_policy: verify-signature
-    
+
   dependencies:
     - storage: 5Gi
-    
+
   resources:
     cpu_limit: 1
     memory_limit: 512Mi
     disk_limit: 5Gi
-    
+
   security:
     capabilities: []
     readonly_root: true
     no_new_privileges: true
-    user: 1000
     seccomp_profile: default
     network_policy: isolated
     apparmor_profile: nostr-relay
-    
+
   ports:
-    - host: 8082
-      container: 8080
-      protocol: tcp  # HTTP/WebSocket
-    
+    - host: 8090
+      container: 7777
+      protocol: tcp  # HTTP/WebSocket (strfry listens on 7777)
+
   volumes:
     - type: bind
       source: /var/lib/archipelago/strfry
-      target: /strfry
+      target: /app/strfry-db
       options: [rw]
-      
-  environment:
-    - RELAY_NAME=Archipelago Strfry Relay
-    
+    # Image default config demands a 1M NOFILES rlimit, above the rootless
+    # user-manager hard cap (524288) — ship the config with nofiles = 0.
+    # Mounting it also skips the entrypoint's copy into /etc, which a
+    # readonly_root container cannot do.
+    - type: bind
+      source: /var/lib/archipelago/strfry-config/strfry.conf
+      target: /etc/strfry.conf
+      options: [ro]
+
+  files:
+    - path: /var/lib/archipelago/strfry-config/strfry.conf
+      overwrite: true
+      content: |
+        ##
+        ## Default strfry config
+        ##
+
+        # Directory that contains the strfry LMDB database (restart required)
+        db = "./strfry-db/"
+
+        dbParams {
+            # Maximum number of threads/processes that can simultaneously have LMDB transactions open (restart required)
+            maxreaders = 256
+
+            # Size of mmap() to use when loading LMDB (default is 10TB, does *not* correspond to disk-space used) (restart required)
+            mapsize = 10995116277760
+
+            # Disables read-ahead when accessing the LMDB mapping. Reduces IO activity when DB size is larger than RAM. (restart required)
+            noReadAhead = false
+        }
+
+        events {
+            # Maximum size of normalised JSON, in bytes
+            maxEventSize = 65536
+
+            # Events newer than this will be rejected
+            rejectEventsNewerThanSeconds = 900
+
+            # Events older than this will be rejected
+            rejectEventsOlderThanSeconds = 94608000
+
+            # Ephemeral events older than this will be rejected
+            rejectEphemeralEventsOlderThanSeconds = 60
+
+            # Ephemeral events will be deleted from the DB when older than this
+            ephemeralEventsLifetimeSeconds = 300
+
+            # Maximum number of tags allowed
+            maxNumTags = 2000
+
+            # Maximum size for tag values, in bytes
+            maxTagValSize = 1024
+        }
+
+        relay {
+            # Interface to listen on. Use 0.0.0.0 to listen on all interfaces (restart required)
+            bind = "0.0.0.0"
+
+            # Port to open for the nostr websocket protocol (restart required)
+            port = 7777
+
+            # Set OS-limit on maximum number of open files/sockets (if 0, don't attempt to set) (restart required)
+            nofiles = 0
+
+            # HTTP header that contains the client's real IP, before reverse proxying (ie x-real-ip) (MUST be all lower-case)
+            realIpHeader = ""
+
+            info {
+                # NIP-11: Name of this server. Short/descriptive (< 30 characters)
+                name = "Archipelago Strfry Relay"
+
+                # NIP-11: Detailed information about relay, free-form
+                description = "Self-hosted strfry Nostr relay on Archipelago."
+
+                # NIP-11: Administrative nostr pubkey, for contact purposes
+                pubkey = ""
+
+                # NIP-11: Alternative administrative contact (email, website, etc)
+                contact = ""
+
+                # NIP-11: URL pointing to an image to be used as an icon for the relay
+                icon = ""
+
+                # List of supported lists as JSON array, or empty string to use default. Example: "[1,2]"
+                nips = ""
+            }
+
+            # Maximum accepted incoming websocket frame size (should be larger than max event) (restart required)
+            maxWebsocketPayloadSize = 131072
+
+            # Maximum number of filters allowed in a REQ
+            maxReqFilterSize = 200
+
+            # Websocket-level PING message frequency (should be less than any reverse proxy idle timeouts) (restart required)
+            autoPingSeconds = 55
+
+            # If TCP keep-alive should be enabled (detect dropped connections to upstream reverse proxy)
+            enableTcpKeepalive = false
+
+            # How much uninterrupted CPU time a REQ query should get during its DB scan
+            queryTimesliceBudgetMicroseconds = 10000
+
+            # Maximum records that can be returned per filter
+            maxFilterLimit = 500
+
+            # Maximum number of subscriptions (concurrent REQs) a connection can have open at any time
+            maxSubsPerConnection = 20
+
+            writePolicy {
+                # If non-empty, path to an executable script that implements the writePolicy plugin logic
+                plugin = "/app/write-policy.py"
+            }
+
+            compression {
+                # Use permessage-deflate compression if supported by client. Reduces bandwidth, but slight increase in CPU (restart required)
+                enabled = true
+
+                # Maintain a sliding window buffer for each connection. Improves compression, but uses more memory (restart required)
+                slidingWindow = true
+            }
+
+            logging {
+                # Dump all incoming messages
+                dumpInAll = false
+
+                # Dump all incoming EVENT messages
+                dumpInEvents = false
+
+                # Dump all incoming REQ/CLOSE messages
+                dumpInReqs = false
+
+                # Log performance metrics for initial REQ database scans
+                dbScanPerf = false
+
+                # Log reason for invalid event rejection? Can be disabled to silence excessive logging
+                invalidEvents = true
+            }
+
+            numThreads {
+                # Ingester threads: route incoming requests, validate events/sigs (restart required)
+                ingester = 3
+
+                # reqWorker threads: Handle initial DB scan for events (restart required)
+                reqWorker = 3
+
+                # reqMonitor threads: Handle filtering of new events (restart required)
+                reqMonitor = 3
+
+                # negentropy threads: Handle negentropy protocol messages (restart required)
+                negentropy = 2
+            }
+
+            negentropy {
+                # Support negentropy protocol messages
+                enabled = true
+
+                # Maximum records that sync will process before returning an error
+                maxSyncEvents = 1000000
+            }
+        }
+
   health_check:
     type: http
-    endpoint: http://localhost:8082
+    # In-container probe: must target the CONTAINER port (7777), not the host
+    # mapping (8090), and 127.0.0.1 explicitly — `localhost` resolves to ::1
+    # inside the image while strfry binds IPv4 0.0.0.0 only (verified on .228:
+    # localhost:7777 refused, 127.0.0.1:7777/health = 200).
+    endpoint: http://127.0.0.1:7777
     path: /health
     interval: 30s
     timeout: 5s
     retries: 3
-    
+
   nostr_integration:
     relay_type: public
     monetization_enabled: true

core/Cargo.lock

@@ -95,10 +95,11 @@ dependencies = [
 
 [[package]]
 name = "archipelago"
-version = "1.7.99-alpha"
+version = "1.7.111-alpha"
 dependencies = [
  "anyhow",
  "archipelago-container",
+ "archipelago-openwrt",
  "archipelago-performance",
  "archipelago-security",
  "argon2",
@@ -128,6 +129,7 @@ dependencies = [
  "hyper-ws-listener",
  "iroh",
  "iroh-blobs",
+ "libc",
  "mainline",
  "mdns-sd",
  "nostr-sdk",
@@ -138,10 +140,12 @@ dependencies = [
  "reqwest 0.11.27",
  "sd-notify",
  "serde",
+ "serde_bytes",
  "serde_json",
  "serde_yaml",
  "serial2-tokio",
  "sha2 0.10.9",
+ "socket2 0.5.10",
  "tar",
  "tempfile",
  "thiserror 1.0.69",
@@ -167,6 +171,7 @@ dependencies = [
  "async-trait",
  "chrono",
  "futures",
+ "hex",
  "hyper 0.14.32",
  "indexmap",
  "log",
@@ -174,12 +179,29 @@ dependencies = [
  "serde",
  "serde_json",
  "serde_yaml",
+ "sha2 0.10.9",
  "thiserror 1.0.69",
  "tokio",
  "tracing",
  "uuid",
 ]
 
+[[package]]
+name = "archipelago-openwrt"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "async-trait",
+ "reqwest 0.11.27",
+ "serde",
+ "serde_json",
+ "ssh2",
+ "thiserror 1.0.69",
+ "tokio",
+ "tokio-test",
+ "tracing",
+]
+
 [[package]]
 name = "archipelago-performance"
 version = "0.1.0"
@@ -2839,6 +2861,32 @@ dependencies = [
  "redox_syscall 0.7.3",
 ]
 
+[[package]]
+name = "libssh2-sys"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "220e4f05ad4a218192533b300327f5150e809b54c4ec83b5a1d91833601811b9"
+dependencies = [
+ "cc",
+ "libc",
+ "libz-sys",
+ "openssl-sys",
+ "pkg-config",
+ "vcpkg",
+]
+
+[[package]]
+name = "libz-sys"
+version = "1.1.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85bc9657773828b90eeb625adff10eeac83cc21bbfd8e23a03eaa8a33c9e28d9"
+dependencies = [
+ "cc",
+ "libc",
+ "pkg-config",
+ "vcpkg",
+]
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.11.0"
@@ -3580,6 +3628,18 @@ version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"
 
+[[package]]
+name = "openssl-sys"
+version = "0.9.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b47e7e6bb2c38cd930d25a23b40fa52e068c10e85f3e03a7f5ba5aaca5713695"
+dependencies = [
+ "cc",
+ "libc",
+ "pkg-config",
+ "vcpkg",
+]
+
 [[package]]
 name = "papaya"
 version = "0.2.4"
@@ -3758,6 +3818,12 @@ dependencies = [
  "spki 0.8.0",
 ]
 
+[[package]]
+name = "pkg-config"
+version = "0.3.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
+
 [[package]]
 name = "plain"
 version = "0.2.3"
@@ -4988,6 +5054,18 @@ dependencies = [
  "der 0.8.0",
 ]
 
+[[package]]
+name = "ssh2"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f84d13b3b8a0d4e91a2629911e951db1bb8671512f5c09d7d4ba34500ba68c8"
+dependencies = [
+ "bitflags 2.13.0",
+ "libc",
+ "libssh2-sys",
+ "parking_lot 0.12.5",
+]
+
 [[package]]
 name = "stable_deref_trait"
 version = "1.2.1"
@@ -5775,6 +5853,12 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65"
 
+[[package]]
+name = "vcpkg"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
+
 [[package]]
 name = "vergen"
 version = "9.1.0"

core/Cargo.toml

@@ -4,6 +4,7 @@ resolver = "2"
 members = [
     "archipelago",
     "container",
+    "openwrt",
     "performance",
     "security",
 ]

core/archipelago/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "archipelago"
-version = "1.7.99-alpha"
+version = "1.7.111-alpha"
 edition = "2021"
 description = "Archipelago Bitcoin Node OS - Native backend"
 authors = ["Archipelago Team"]
@@ -22,6 +22,10 @@ iroh-swarm = ["dep:iroh", "dep:iroh-blobs"]
 [dependencies]
 # Core dependencies
 tokio = { version = "1", features = ["full"] }
+# Mesh port mirror: needs IPV6_V6ONLY on [::] listeners so they coexist with
+# the containers' own 0.0.0.0 binds (std/tokio don't expose the sockopt).
+socket2 = "0.5"
+libc = "0.2"   # process-group signalling for the supervised reticulum daemon
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 anyhow = "1.0"
@@ -42,6 +46,7 @@ futures-util = "0.3"
 
 # Our modules
 archipelago-container = { path = "../container" }
+archipelago-openwrt = { path = "../openwrt" }
 archipelago-security = { path = "../security" }
 archipelago-performance = { path = "../performance" }
 
@@ -108,6 +113,7 @@ hkdf = "0.12.4"
 
 # Transport abstraction (Phase 2: mesh as federation transport)
 ciborium = "0.2.2"
+serde_bytes = "0.11"
 reed-solomon-erasure = "6.0"
 mdns-sd = "0.18"
 

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

@@ -48,6 +48,17 @@ impl ApiHandler {
             .get("x-blob-filename")
             .and_then(|v| v.to_str().ok())
             .map(|s| s.to_string());
+        // Optional caller-supplied thumbnail (small, base64) — e.g. the mesh
+        // chat's image-quality picker generates a tiny client-side preview so
+        // a ContentRef receiver can render something before fetching the full
+        // blob. Best-effort: a malformed header is just ignored, not fatal.
+        let thumb_bytes = headers
+            .get("x-blob-thumb")
+            .and_then(|v| v.to_str().ok())
+            .and_then(|b64| {
+                use base64::{engine::general_purpose::STANDARD, Engine as _};
+                STANDARD.decode(b64).ok()
+            });
 
         let bytes = body.to_vec();
         // Uploads through /api/blob come from the node owner's session and
@@ -55,7 +66,7 @@ impl ApiHandler {
         // pictures, banners). Store them public so `/blob/<cid>` serves
         // without a capability check — external Nostr clients fetching a
         // kind-0 `picture` URL have no cap and can't get one.
-        match store.put(&bytes, &mime, filename, None, true).await {
+        match store.put(&bytes, &mime, filename, thumb_bytes, true).await {
             Ok(meta) => {
                 let exp =
                     (chrono::Utc::now().timestamp() as u64) + crate::blobs::DEFAULT_CAP_TTL_SECS;

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

@@ -188,7 +188,7 @@ impl ApiHandler {
             }
         };
         let price_sats = match &item.access {
-            content_server::AccessControl::Paid { price_sats } => *price_sats,
+            content_server::AccessControl::Paid { price_sats, .. } => *price_sats,
             _ => {
                 // Not a paid item — no invoice to issue.
                 return Ok(build_response(
@@ -198,6 +198,13 @@ impl ApiHandler {
                 ));
             }
         };
+        if !content_server::method_accepted(&item.access, "lightning") {
+            return Ok(build_response(
+                StatusCode::BAD_REQUEST,
+                "application/json",
+                hyper::Body::from(r#"{"error":"The seller does not accept Lightning for this item"}"#),
+            ));
+        }
 
         let memo = format!("Archipelago peer file {content_id}");
         match self
@@ -315,7 +322,18 @@ impl ApiHandler {
             .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,
+                content_server::AccessControl::Paid { price_sats, .. } => {
+                    if !content_server::method_accepted(&i.access, "onchain") {
+                        return Ok(build_response(
+                            StatusCode::BAD_REQUEST,
+                            "application/json",
+                            hyper::Body::from(
+                                r#"{"error":"The seller does not accept on-chain payment for this item"}"#,
+                            ),
+                        ));
+                    }
+                    *price_sats
+                }
                 _ => {
                     return Ok(build_response(
                         StatusCode::BAD_REQUEST,

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

@@ -126,15 +126,15 @@ impl ApiHandler {
     }
 
     /// Server-side fetch of the upstream app catalog so the browser can
-    /// load it without fighting CORS (git.tx1138.com emits no ACAO) or
+    /// load it without fighting CORS (upstream Gitea emits no ACAO) or
     /// CSP (the fallback IP-port URL isn't in `connect-src`). The upstream
     /// list is derived from the operator's configured container registries
     /// so switching mirrors in Settings changes the App Store source too —
     /// each active registry contributes one Gitea `raw/branch/main/catalog.json`
     /// URL (http or https per `tls_verify`), tried in priority order.
-    /// If registry config can't be loaded, falls back to the legacy
-    /// hardcoded pair so the App Store still renders on nodes that haven't
-    /// persisted a registry config yet. 15s total timeout.
+    /// If registry config can't be loaded, falls back to the hardcoded OVH
+    /// URL so the App Store still renders on nodes that haven't persisted
+    /// a registry config yet. 15s total timeout.
     async fn handle_app_catalog_proxy(&self) -> Result<Response<hyper::Body>> {
         let mut upstreams: Vec<String> = Vec::new();
         if let Ok(config) = crate::container::registry::load_registries(&self.config.data_dir).await
@@ -155,10 +155,6 @@ impl ApiHandler {
                 "http://146.59.87.168:3000/lfg2025/app-catalog/raw/branch/main/catalog.json"
                     .to_string(),
             );
-            upstreams.push(
-                "https://git.tx1138.com/lfg2025/app-catalog/raw/branch/main/catalog.json"
-                    .to_string(),
-            );
         }
 
         let client = match reqwest::Client::builder()
@@ -198,6 +194,43 @@ impl ApiHandler {
         ))
     }
 
+    /// Serve an encrypted backup archive (`<data_dir>/backups/<id>.bak`) as a
+    /// browser download. The archive is passphrase-encrypted at rest; the
+    /// session gate at the route controls who can fetch it.
+    async fn handle_backup_download(&self, path: &str) -> Result<Response<hyper::Body>> {
+        let id = path.strip_prefix("/api/blob/backup/").unwrap_or("");
+        // Backup ids are UUIDs — reject anything that could traverse paths.
+        if id.is_empty() || !id.chars().all(|c| c.is_ascii_hexdigit() || c == '-') {
+            return Ok(build_response(
+                StatusCode::BAD_REQUEST,
+                "application/json",
+                hyper::Body::from(r#"{"error":"invalid backup id"}"#),
+            ));
+        }
+        let file = self
+            .config
+            .data_dir
+            .join("backups")
+            .join(format!("{id}.bak"));
+        match tokio::fs::read(&file).await {
+            Ok(bytes) => Ok(Response::builder()
+                .status(StatusCode::OK)
+                .header("Content-Type", "application/octet-stream")
+                .header(
+                    "Content-Disposition",
+                    format!("attachment; filename=\"archipelago-backup-{id}.bak\""),
+                )
+                .header("Content-Length", bytes.len())
+                .body(hyper::Body::from(bytes))
+                .unwrap_or_else(|_| Response::new(hyper::Body::from("Internal error")))),
+            Err(_) => Ok(build_response(
+                StatusCode::NOT_FOUND,
+                "application/json",
+                hyper::Body::from(r#"{"error":"backup not found"}"#),
+            )),
+        }
+    }
+
     /// Build a 401 Unauthorized JSON response.
     fn unauthorized() -> Response<hyper::Body> {
         let body = serde_json::json!({ "error": "Unauthorized" });
@@ -438,6 +471,16 @@ impl ApiHandler {
                 Self::handle_mesh_typed_relay(self.rpc_handler.clone(), body_bytes).await
             }
 
+            // Backup archive download — session-gated. Lives under /api/blob/
+            // so the existing nginx `location /api/blob` prefix proxies it on
+            // every fleet node without a config change.
+            (Method::GET, p) if p.starts_with("/api/blob/backup/") => {
+                if !self.is_authenticated(&headers).await {
+                    return Ok(Self::unauthorized());
+                }
+                self.handle_backup_download(p).await
+            }
+
             // Blob upload — local/session use only. Session-authenticated so
             // only the node owner can push attachments into the blob store.
             (Method::POST, "/api/blob") => {
@@ -527,7 +570,7 @@ impl ApiHandler {
 
             // App-catalog proxy — fetches catalog.json from the configured
             // upstream URLs server-side so the browser doesn't hit CORS
-            // (git.tx1138.com has no ACAO header) or CSP (IP-port upstream
+            // (upstream Gitea has no ACAO header) or CSP (IP-port upstream
             // falls outside `connect-src`). Session-authenticated so only
             // the logged-in node owner can spin up fetches.
             (Method::GET, "/api/app-catalog") => {
@@ -537,6 +580,26 @@ impl ApiHandler {
                 self.handle_app_catalog_proxy().await
             }
 
+            // Pine node status — public tier (version/uptime/height/sync/peer
+            // counts) is unauthenticated like /bitcoin-status; Lightning
+            // balances + latest mesh message additionally require the bearer
+            // token the pine/HA seeder minted (or a valid session).
+            (Method::GET, "/api/pine/status") => {
+                let bearer = headers
+                    .get(hyper::header::AUTHORIZATION)
+                    .and_then(|v| v.to_str().ok())
+                    .and_then(|v| v.strip_prefix("Bearer "))
+                    .unwrap_or("");
+                let authorized = self.rpc_handler.pine_status_token_ok(bearer).await
+                    || self.is_authenticated(&headers).await;
+                let body = self.rpc_handler.pine_status_json(authorized).await;
+                Ok(build_response(
+                    StatusCode::OK,
+                    "application/json",
+                    hyper::Body::from(serde_json::to_vec(&body).unwrap_or_default()),
+                ))
+            }
+
             // LND connect info — nginx validates session cookie (presence check),
             // backend is bound to 127.0.0.1 so only nginx can reach it.
             // No backend auth check here because the LND UI iframe fetches this

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

@@ -39,6 +39,17 @@ impl ApiHandler {
 
                 let (mut tx, mut rx) = ws_stream.split();
 
+                // Subscribe BEFORE taking the initial snapshot. Messages are full
+                // data dumps keyed by a monotonic revision, so a broadcast that
+                // races the snapshot is at worst a harmless duplicate/newer dump
+                // delivered right after — but subscribing after the snapshot send
+                // (the old order) let any update in that window vanish forever,
+                // since a tokio broadcast channel never delivers sends that
+                // predate subscribe(). That silently stuck clients (e.g. a fresh
+                // install's post-boot container scan) on a stale initial snapshot
+                // until a full page reload opened a new connection past the race.
+                let mut state_rx = state_manager.subscribe();
+
                 let initial_msg = state_manager.get_initial_message().await;
                 if let Ok(json_msg) = serde_json::to_string(&initial_msg) {
                     if let Err(e) = tx.send(Message::Text(json_msg)).await {
@@ -47,8 +58,6 @@ impl ApiHandler {
                     }
                     debug!("Sent initial data dump at revision {}", initial_msg.rev);
                 }
-
-                let mut state_rx = state_manager.subscribe();
                 let ping_interval = tokio::time::interval(tokio::time::Duration::from_secs(30));
                 tokio::pin!(ping_interval);
                 let mut last_client_activity = Instant::now();

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

@@ -326,75 +326,93 @@ impl RpcHandler {
     }
 
     /// Get all fleet nodes' latest reports.
-    /// Reads all {node_id}.json files from telemetry-fleet/ (excluding *-history.json).
+    ///
+    /// Primary source: TRUSTED federated nodes from nodes.json — their
+    /// `last_state` snapshot (kept fresh by federation state-sync) already
+    /// carries everything the Fleet UI renders. Observer ("peer") and
+    /// Untrusted nodes are deliberately excluded from Fleet.
+    ///
+    /// Secondary source: telemetry-fleet/*.json collector reports (opt-in
+    /// anonymous telemetry, includes this node's own report) — merged in for
+    /// back-compat with nodes that push telemetry but aren't federated.
     pub(super) async fn handle_telemetry_fleet_status(&self) -> Result<serde_json::Value> {
-        let fleet_dir = self.config.data_dir.join("telemetry-fleet");
-        if !fleet_dir.exists() {
-            return Ok(serde_json::json!({ "nodes": [] }));
+        let mut nodes: Vec<serde_json::Value> = Vec::new();
+
+        // ── Trusted federation nodes ─────────────────────────────────────
+        let fed_nodes = crate::federation::load_nodes(&self.config.data_dir)
+            .await
+            .unwrap_or_default();
+        for n in fed_nodes
+            .iter()
+            .filter(|n| n.trust_level == crate::federation::TrustLevel::Trusted)
+        {
+            let state = n.last_state.as_ref();
+            let pct = |used: Option<u64>, total: Option<u64>| -> serde_json::Value {
+                match (used, total) {
+                    (Some(u), Some(t)) if t > 0 => {
+                        serde_json::json!((u as f64 / t as f64 * 100.0).round())
+                    }
+                    _ => serde_json::json!(0),
+                }
+            };
+            let apps = state.map(|s| s.apps.as_slice()).unwrap_or(&[]);
+            let reported_at = state
+                .map(|s| s.timestamp.clone())
+                .or_else(|| n.last_seen.clone())
+                .unwrap_or_else(|| n.added_at.clone());
+
+            let mut report = serde_json::json!({
+                "node_id": n.did,
+                "node_name": state.and_then(|s| s.node_name.clone()).or_else(|| n.name.clone()),
+                "uptime_secs": state.and_then(|s| s.uptime_secs).unwrap_or(0),
+                "cpu_pct": state.and_then(|s| s.cpu_usage_percent).map(|v| v.round()).unwrap_or(0.0),
+                "mem_pct": pct(state.and_then(|s| s.mem_used_bytes), state.and_then(|s| s.mem_total_bytes)),
+                "disk_pct": pct(state.and_then(|s| s.disk_used_bytes), state.and_then(|s| s.disk_total_bytes)),
+                "container_count": apps.len(),
+                "running_count": apps.iter().filter(|a| a.status == "running").count(),
+                "federation_peers": state.map(|s| s.federated_peers.len()).unwrap_or(0),
+                "containers": apps.iter().map(|a| serde_json::json!({
+                    "id": a.id,
+                    "state": a.status,
+                    "version": a.version.clone().unwrap_or_default(),
+                })).collect::<Vec<_>>(),
+                "reported_at": reported_at,
+                "trust_level": n.trust_level.to_string(),
+                "source": "federation",
+            });
+            annotate_fleet_report(&mut report);
+            nodes.push(report);
         }
 
-        let mut nodes: Vec<serde_json::Value> = Vec::new();
-        let mut entries = tokio::fs::read_dir(&fleet_dir)
-            .await
-            .context("Failed to read telemetry-fleet directory")?;
+        // ── Opt-in telemetry collector reports ───────────────────────────
+        let fleet_dir = self.config.data_dir.join("telemetry-fleet");
+        if fleet_dir.exists() {
+            let mut entries = tokio::fs::read_dir(&fleet_dir)
+                .await
+                .context("Failed to read telemetry-fleet directory")?;
 
-        while let Some(entry) = entries.next_entry().await? {
-            let file_name = entry.file_name();
-            let name = file_name.to_string_lossy();
-            // Skip history files and non-JSON files
-            if name.ends_with("-history.json") || !name.ends_with(".json") {
-                continue;
-            }
+            while let Some(entry) = entries.next_entry().await? {
+                let file_name = entry.file_name();
+                let name = file_name.to_string_lossy();
+                // Skip history files and non-JSON files
+                if name.ends_with("-history.json") || !name.ends_with(".json") {
+                    continue;
+                }
 
-            match tokio::fs::read_to_string(entry.path()).await {
-                Ok(data) => {
-                    match serde_json::from_str::<serde_json::Value>(&data) {
+                match tokio::fs::read_to_string(entry.path()).await {
+                    Ok(data) => match serde_json::from_str::<serde_json::Value>(&data) {
                         Ok(mut report) => {
-                            // Compute online/offline status from reported_at
-                            let is_online = report
-                                .get("reported_at")
-                                .and_then(|v| v.as_str())
-                                .and_then(|s| chrono::DateTime::parse_from_rfc3339(s).ok())
-                                .map(|dt| {
-                                    let age = chrono::Utc::now().signed_duration_since(dt);
-                                    age.num_minutes() < 30
-                                })
-                                .unwrap_or(false);
-
-                            // Compute human-readable last_seen
-                            let last_seen = report
-                                .get("reported_at")
-                                .and_then(|v| v.as_str())
-                                .and_then(|s| chrono::DateTime::parse_from_rfc3339(s).ok())
-                                .map(|dt| {
-                                    let age = chrono::Utc::now().signed_duration_since(dt);
-                                    let mins = age.num_minutes();
-                                    if mins < 1 {
-                                        "just now".to_string()
-                                    } else if mins < 60 {
-                                        format!("{}m ago", mins)
-                                    } else if mins < 1440 {
-                                        format!("{}h ago", mins / 60)
-                                    } else {
-                                        format!("{}d ago", mins / 1440)
-                                    }
-                                })
-                                .unwrap_or_else(|| "unknown".to_string());
-
-                            if let Some(obj) = report.as_object_mut() {
-                                obj.insert("online".to_string(), serde_json::json!(is_online));
-                                obj.insert("last_seen".to_string(), serde_json::json!(last_seen));
-                            }
+                            annotate_fleet_report(&mut report);
                             nodes.push(report);
                         }
                         Err(e) => {
                             warn!(file = %name, error = %e, "Skipping corrupt fleet report");
                         }
+                    },
+                    Err(e) => {
+                        warn!(file = %name, error = %e, "Failed to read fleet report");
                     }
                 }
-                Err(e) => {
-                    warn!(file = %name, error = %e, "Failed to read fleet report");
-                }
             }
         }
 
@@ -531,3 +549,40 @@ fn local_server_url(host_ip: &str) -> Option<String> {
         Some(format!("https://{host_ip}"))
     }
 }
+
+/// Stamp a fleet report with computed `online` and human-readable `last_seen`
+/// derived from its `reported_at` timestamp (online = reported <30min ago).
+fn annotate_fleet_report(report: &mut serde_json::Value) {
+    let reported = report
+        .get("reported_at")
+        .and_then(|v| v.as_str())
+        .and_then(|s| chrono::DateTime::parse_from_rfc3339(s).ok());
+
+    let is_online = reported
+        .map(|dt| {
+            let age = chrono::Utc::now().signed_duration_since(dt);
+            age.num_minutes() < 30
+        })
+        .unwrap_or(false);
+
+    let last_seen = reported
+        .map(|dt| {
+            let age = chrono::Utc::now().signed_duration_since(dt);
+            let mins = age.num_minutes();
+            if mins < 1 {
+                "just now".to_string()
+            } else if mins < 60 {
+                format!("{}m ago", mins)
+            } else if mins < 1440 {
+                format!("{}h ago", mins / 60)
+            } else {
+                format!("{}d ago", mins / 1440)
+            }
+        })
+        .unwrap_or_else(|| "unknown".to_string());
+
+    if let Some(obj) = report.as_object_mut() {
+        obj.insert("online".to_string(), serde_json::json!(is_online));
+        obj.insert("last_seen".to_string(), serde_json::json!(last_seen));
+    }
+}

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

@@ -0,0 +1,229 @@
+//! Ark protocol RPCs — bridge to the `barkd` sidecar.
+//!
+//! Companion to the Cashu RPCs in [`super::wallet`] and the Fedimint RPCs in
+//! [`super::fedimint`]. Holding VTXOs, joining rounds and unilateral exits are
+//! delegated to the barkd container via [`crate::wallet::ark_client::ArkClient`];
+//! here we expose the node's JSON-RPC surface. barkd keeps its own movement
+//! history, so unlike Fedimint there is no local transaction log.
+
+use super::RpcHandler;
+use crate::wallet::ark_client::{self, ArkClient};
+use anyhow::Result;
+
+impl RpcHandler {
+    /// `wallet.ark-status` — sidecar reachability, wallet fingerprint, network
+    /// and Ark server parameters. Soft-fails into `available: false` so the
+    /// settings UI can render an install/enable hint instead of an error.
+    pub(super) async fn handle_wallet_ark_status(&self) -> Result<serde_json::Value> {
+        let config = ark_client::load_config(&self.config.data_dir).await;
+        let client = match ArkClient::from_node(&self.config.data_dir).await {
+            Ok(c) => c,
+            Err(_) => {
+                return Ok(serde_json::json!({
+                    "available": false,
+                    "wallet_ready": false,
+                    "config": config,
+                }))
+            }
+        };
+        // Make sure the wallet exists before reporting (idempotent, cheap once
+        // created).
+        let _ = ark_client::ensure_wallet(&self.config.data_dir).await;
+
+        let wallet = client.wallet_info().await.ok();
+        let info = client.ark_info().await.ok();
+        Ok(serde_json::json!({
+            "available": true,
+            "wallet_ready": wallet.is_some(),
+            "wallet": wallet,
+            "ark_info": info,
+            "config": config,
+        }))
+    }
+
+    /// `wallet.ark-balance` — off-chain (spendable + pending) and on-chain
+    /// sats. Soft-fails to zeros so unified balances still render.
+    pub(super) async fn handle_wallet_ark_balance(&self) -> Result<serde_json::Value> {
+        let client = match ArkClient::from_node(&self.config.data_dir).await {
+            Ok(c) => c,
+            Err(_) => {
+                return Ok(serde_json::json!({
+                    "balance_sats": 0,
+                    "spendable_sats": 0,
+                    "pending_sats": 0,
+                    "onchain_sats": 0,
+                }))
+            }
+        };
+        let bal = client
+            .balance()
+            .await
+            .unwrap_or_else(|_| serde_json::json!({}));
+        let sat = |key: &str| bal.get(key).and_then(|v| v.as_u64()).unwrap_or(0);
+        let spendable = sat("spendable_sat");
+        let pending = sat("pending_in_round_sat")
+            + sat("pending_board_sat")
+            + sat("pending_lightning_send_sat")
+            + sat("claimable_lightning_receive_sat")
+            + bal
+                .get("pending_exit_sat")
+                .and_then(|v| v.as_u64())
+                .unwrap_or(0);
+        let onchain = client
+            .onchain_balance()
+            .await
+            .ok()
+            .and_then(|b| {
+                b.get("total_sat")
+                    .or_else(|| b.get("confirmed_sat"))
+                    .and_then(|v| v.as_u64())
+            })
+            .unwrap_or(0);
+        Ok(serde_json::json!({
+            "balance_sats": spendable,
+            "spendable_sats": spendable,
+            "pending_sats": pending,
+            "onchain_sats": onchain,
+        }))
+    }
+
+    /// `wallet.ark-address` — fresh Ark (`tark1…`) receive address; pass
+    /// `{"onchain": true}` for an on-chain boarding address instead.
+    pub(super) async fn handle_wallet_ark_address(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let _ = ark_client::ensure_wallet(&self.config.data_dir).await;
+        let client = ArkClient::from_node(&self.config.data_dir).await?;
+        let onchain = params
+            .as_ref()
+            .and_then(|p| p.get("onchain"))
+            .and_then(|v| v.as_bool())
+            .unwrap_or(false);
+        let address = if onchain {
+            client.onchain_address().await?
+        } else {
+            client.ark_address().await?
+        };
+        Ok(serde_json::json!({ "address": address, "onchain": onchain }))
+    }
+
+    /// `wallet.ark-send` — pay an Ark address, BOLT11 invoice, LNURL or
+    /// lightning address from Ark funds.
+    pub(super) async fn handle_wallet_ark_send(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let destination = params
+            .get("destination")
+            .and_then(|v| v.as_str())
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .ok_or_else(|| anyhow::anyhow!("Missing destination"))?;
+        // Optional for BOLT11 invoices that carry their own amount.
+        let amount_sats = params.get("amount_sats").and_then(|v| v.as_u64());
+        if amount_sats == Some(0) {
+            return Err(anyhow::anyhow!("Amount must be greater than zero"));
+        }
+        let comment = params.get("comment").and_then(|v| v.as_str());
+
+        let client = ArkClient::from_node(&self.config.data_dir).await?;
+        let movement = client.send(destination, amount_sats, comment).await?;
+        Ok(serde_json::json!({
+            "sent": true,
+            "movement": movement,
+        }))
+    }
+
+    /// `wallet.ark-invoice` — BOLT11 invoice that lands as Ark funds when paid.
+    pub(super) async fn handle_wallet_ark_invoice(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let amount_sats = params
+            .get("amount_sats")
+            .and_then(|v| v.as_u64())
+            .filter(|&v| v > 0)
+            .ok_or_else(|| anyhow::anyhow!("Missing amount_sats"))?;
+
+        let _ = ark_client::ensure_wallet(&self.config.data_dir).await;
+        let client = ArkClient::from_node(&self.config.data_dir).await?;
+        let res = client.lightning_invoice(amount_sats).await?;
+        Ok(res)
+    }
+
+    /// `wallet.ark-board` — lift on-chain funds into Ark VTXOs. Omitting
+    /// `amount_sats` boards everything.
+    pub(super) async fn handle_wallet_ark_board(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let amount_sats = params
+            .as_ref()
+            .and_then(|p| p.get("amount_sats"))
+            .and_then(|v| v.as_u64());
+        if amount_sats == Some(0) {
+            return Err(anyhow::anyhow!("Amount must be greater than zero"));
+        }
+        let client = ArkClient::from_node(&self.config.data_dir).await?;
+        let res = client.board(amount_sats).await?;
+        Ok(res)
+    }
+
+    /// `wallet.ark-offboard` — collaboratively move all VTXOs back on-chain,
+    /// optionally to a provided address (defaults to the wallet's own).
+    pub(super) async fn handle_wallet_ark_offboard(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let address = params
+            .as_ref()
+            .and_then(|p| p.get("address"))
+            .and_then(|v| v.as_str())
+            .map(str::trim)
+            .filter(|s| !s.is_empty());
+        let client = ArkClient::from_node(&self.config.data_dir).await?;
+        let res = client.offboard_all(address).await?;
+        Ok(res)
+    }
+
+    /// `wallet.ark-history` — barkd movements mapped to the unified
+    /// transaction shape (kind = "ark"), newest first.
+    pub(super) async fn handle_wallet_ark_history(&self) -> Result<serde_json::Value> {
+        let mut transactions = ark_client::load_ark_txs(&self.config.data_dir).await;
+        transactions.sort_by(|a, b| b.timestamp.cmp(&a.timestamp));
+        Ok(serde_json::json!({ "transactions": transactions }))
+    }
+
+    /// `wallet.ark-configure` — set the Ark server / esplora / network used
+    /// when the barkd wallet is (re)created. Does NOT migrate an existing
+    /// wallet: barkd binds a wallet to its Ark server at creation.
+    pub(super) async fn handle_wallet_ark_configure(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let mut config = ark_client::load_config(&self.config.data_dir).await;
+        for (key, field) in [
+            ("network", &mut config.network as &mut String),
+            ("ark_server", &mut config.ark_server),
+            ("esplora", &mut config.esplora),
+        ] {
+            if let Some(v) = params.get(key).and_then(|v| v.as_str()) {
+                let v = v.trim();
+                if !v.is_empty() {
+                    *field = v.to_string();
+                }
+            }
+        }
+        if !matches!(config.network.as_str(), "signet" | "mainnet" | "regtest") {
+            return Err(anyhow::anyhow!(
+                "network must be one of: signet, mainnet, regtest"
+            ));
+        }
+        ark_client::save_config(&self.config.data_dir, &config).await?;
+        Ok(serde_json::json!({ "config": config }))
+    }
+}

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

@@ -1,4 +1,6 @@
-use super::{RpcHandler, DEV_DEFAULT_PASSWORD};
+use super::RpcHandler;
+#[cfg(debug_assertions)]
+use super::DEV_DEFAULT_PASSWORD;
 use anyhow::Result;
 
 impl RpcHandler {
@@ -7,6 +9,23 @@ impl RpcHandler {
         params: Option<serde_json::Value>,
     ) -> Result<serde_json::Value> {
         let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+
+        // Companion device-token login: minted via auth.createDeviceToken and
+        // carried by the pairing QR. Verified here so it shares the login rate
+        // limiter with password attempts.
+        if let Some(token) = params.get("token").and_then(|v| v.as_str()) {
+            return match crate::device_tokens::verify(&self.config.data_dir, token).await {
+                Some(device) => {
+                    tracing::info!("[onboarding] device-token login ({device})");
+                    Ok(serde_json::Value::Null)
+                }
+                None => {
+                    tracing::warn!("[onboarding] device-token login failed");
+                    Err(anyhow::anyhow!("Invalid device token"))
+                }
+            };
+        }
+
         let password = params
             .get("password")
             .and_then(|v| v.as_str())
@@ -14,7 +33,10 @@ impl RpcHandler {
 
         let is_setup = self.auth_manager.is_setup().await?;
         if !is_setup {
-            // Dev mode: allow default password so UI can log in without running setup
+            // Dev BUILDS only: allow the default password so the UI can log
+            // in without running setup. cfg-gated so no release binary can
+            // carry the bypass, whatever its runtime config says.
+            #[cfg(debug_assertions)]
             if self.config.dev_mode && password == DEV_DEFAULT_PASSWORD {
                 tracing::info!("[onboarding] login via dev default password");
                 return Ok(serde_json::Value::Null);
@@ -27,6 +49,15 @@ impl RpcHandler {
 
         let valid = self.auth_manager.verify_password(password).await?;
         if !valid {
+            // The companion app sends its device token through the password
+            // field (it reuses the whole password auto-login path, including
+            // the WebView form). Accept a valid token here so that path works.
+            if let Some(device) =
+                crate::device_tokens::verify(&self.config.data_dir, password).await
+            {
+                tracing::info!("[onboarding] device-token login via password field ({device})");
+                return Ok(serde_json::Value::Null);
+            }
             tracing::warn!("[onboarding] login failed — wrong password");
             return Err(anyhow::anyhow!("Password Incorrect"));
         }
@@ -68,6 +99,56 @@ impl RpcHandler {
         Ok(serde_json::Value::Null)
     }
 
+    /// Mint a device token for the companion pairing QR. Session-gated by the
+    /// dispatcher (not in UNAUTHENTICATED_METHODS), so only a logged-in web UI
+    /// can mint one. The plaintext token is returned exactly once.
+    pub(super) async fn handle_auth_create_device_token(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let mut name = params
+            .as_ref()
+            .and_then(|p| p.get("name"))
+            .and_then(|v| v.as_str())
+            .unwrap_or("companion")
+            .trim()
+            .to_string();
+        if name.is_empty() || name.len() > 64 {
+            return Err(anyhow::anyhow!("Device name must be 1-64 characters"));
+        }
+        // The default name was a single shared slot: every pairing popup
+        // replaced the previous phone's token, silently logging out the
+        // first phone the moment a second one paired. Default-named mints
+        // get a unique suffix so each device keeps its own credential;
+        // explicitly named devices keep replace-in-place semantics.
+        if name == "companion" {
+            name = format!("companion-{}", hex::encode(rand::random::<[u8; 2]>()));
+        }
+        let token = crate::device_tokens::create(&self.config.data_dir, &name).await?;
+        Ok(serde_json::json!({ "name": name, "token": token }))
+    }
+
+    pub(super) async fn handle_auth_list_device_tokens(&self) -> Result<serde_json::Value> {
+        let tokens = crate::device_tokens::list(&self.config.data_dir).await;
+        Ok(serde_json::json!(tokens
+            .iter()
+            .map(|t| serde_json::json!({ "name": t.name, "created": t.created }))
+            .collect::<Vec<_>>()))
+    }
+
+    pub(super) async fn handle_auth_revoke_device_token(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let name = params
+            .as_ref()
+            .and_then(|p| p.get("name"))
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing name"))?;
+        let removed = crate::device_tokens::remove(&self.config.data_dir, name).await?;
+        Ok(serde_json::json!({ "removed": removed }))
+    }
+
     pub(super) async fn handle_auth_logout(&self) -> Result<serde_json::Value> {
         tracing::info!("[onboarding] logout");
         Ok(serde_json::Value::Null)
@@ -141,6 +222,28 @@ impl RpcHandler {
 
         self.auth_manager.setup_user(password).await?;
         tracing::info!("[onboarding] user setup complete");
+
+        // The install-time password must also become the OS login for the
+        // archipelago user — otherwise the console/SSH keeps the image default
+        // ("archipelago") after the user has picked a real password (#97).
+        // Best-effort: a failure here must not break onboarding.
+        match crate::auth::change_ssh_password(password).await {
+            Ok(()) => tracing::info!("[onboarding] system login password synced"),
+            Err(e) => tracing::warn!("[onboarding] system login password sync failed: {e}"),
+        }
+
+        // Persist the pending onboarding seed as the encrypted backup now that
+        // a passphrase (the login password) finally exists — otherwise "Reveal
+        // recovery phrase" has nothing to decrypt on this node, ever.
+        // Best-effort: a failure here must not break password setup.
+        match super::seed_rpc::save_pending_seed_encrypted(&self.config.data_dir, password).await {
+            Ok(true) => tracing::info!("[onboarding] encrypted seed backup saved"),
+            Ok(false) => tracing::info!(
+                "[onboarding] no pending mnemonic to back up (restored earlier or legacy node)"
+            ),
+            Err(e) => tracing::warn!("[onboarding] encrypted seed backup failed: {e:#}"),
+        }
+
         Ok(serde_json::json!(true))
     }
 

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

@@ -862,7 +862,9 @@ async fn hydrate_tor_endpoint(data_dir: &Path, state: &mut BitcoinRelayState) {
         let onion = onion.trim().trim_end_matches('/').to_string();
         if !onion.is_empty() {
             state.settings.tor_endpoint = Some(format!("http://{onion}/"));
-            let _ = save_relay_state(data_dir, state).await;
+            if let Err(e) = save_relay_state(data_dir, state).await {
+                tracing::warn!("Failed to persist relay tor endpoint: {e:#}");
+            }
         }
     }
 }

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

@@ -176,8 +176,7 @@ impl RpcHandler {
         // 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;
+        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 {
@@ -805,7 +804,7 @@ async fn http_launch_url_reachable(url: &str) -> bool {
     }
 }
 
-fn port_from_url(url: &str) -> Option<u16> {
+pub(in crate::api::rpc) fn port_from_url(url: &str) -> Option<u16> {
     let after_colon = url.rsplit_once(':')?.1;
     let port = after_colon
         .chars()

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

@@ -179,7 +179,24 @@ impl RpcHandler {
                 if price == 0 {
                     return Err(anyhow::anyhow!("Paid content requires price_sats > 0"));
                 }
-                AccessControl::Paid { price_sats: price }
+                // Optional list of payment methods the sharer accepts.
+                // Absent/empty = all methods (backward compatible).
+                const KNOWN_METHODS: [&str; 4] = ["lightning", "onchain", "ecash", "fedimint"];
+                let accepted: Vec<String> = params
+                    .get("accepted_methods")
+                    .and_then(|v| v.as_array())
+                    .map(|arr| {
+                        arr.iter()
+                            .filter_map(|m| m.as_str())
+                            .filter(|m| KNOWN_METHODS.contains(m))
+                            .map(str::to_string)
+                            .collect()
+                    })
+                    .unwrap_or_default();
+                AccessControl::Paid {
+                    price_sats: price,
+                    accepted,
+                }
             }
             _ => return Err(anyhow::anyhow!("Invalid access type: {}", access_type)),
         };
@@ -267,13 +284,16 @@ impl RpcHandler {
                 .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(
+        if let Err(e) = crate::federation::record_peer_transport(
             &self.config.data_dir,
             None,
             Some(onion),
             &transport.to_string(),
         )
-        .await;
+        .await
+        {
+            tracing::warn!("Failed to persist peer transport badge: {e:#}");
+        }
 
         if response.status() == reqwest::StatusCode::PAYMENT_REQUIRED {
             let body: serde_json::Value = response.json().await.unwrap_or_default();
@@ -348,13 +368,16 @@ impl RpcHandler {
                 .await
                 .context("Failed to connect to peer")?;
         // Record which transport actually reached the peer (B14).
-        let _ = crate::federation::record_peer_transport(
+        if let Err(e) = crate::federation::record_peer_transport(
             &self.config.data_dir,
             None,
             Some(onion),
             &transport.to_string(),
         )
-        .await;
+        .await
+        {
+            tracing::warn!("Failed to persist peer transport badge: {e:#}");
+        }
 
         if !response.status().is_success() {
             return Err(anyhow::anyhow!(
@@ -406,6 +429,55 @@ impl RpcHandler {
             return Err(anyhow::anyhow!("Invalid v3 onion address"));
         }
 
+        // NEVER pay twice for content we already own (2026-07-22: a file
+        // shared twice produced two catalog ids for the same bytes and the
+        // buyer paid both). Guard BEFORE any ecash is minted, matching both
+        // by exact (onion, content_id) and by (onion, filename) — the latter
+        // catches duplicate ids pointing at the same file on the same
+        // seller. The owned copy is served from the local cache instead.
+        {
+            let filename = params.get("filename").and_then(|v| v.as_str());
+            let owned = crate::content_owned::list_owned(&self.config.data_dir).await;
+            let already = owned.iter().find(|o| {
+                o.onion == onion
+                    && (o.content_id == content_id
+                        || filename.is_some_and(|f| {
+                            !f.is_empty()
+                                && o.filename.trim_start_matches('/')
+                                    == f.trim_start_matches('/')
+                        }))
+            });
+            if let Some(o) = already {
+                tracing::info!(
+                    onion,
+                    content_id,
+                    owned_as = %o.content_id,
+                    "paid download: already owned — serving cached copy, NOT paying again"
+                );
+                if let Some((mime, bytes)) = crate::content_owned::read_owned(
+                    &self.config.data_dir,
+                    &o.onion,
+                    &o.content_id,
+                )
+                .await
+                {
+                    use base64::Engine;
+                    return Ok(serde_json::json!({
+                        "owned": true,
+                        "already_owned": true,
+                        "filename": o.filename,
+                        "mime_type": mime,
+                        "size_bytes": bytes.len(),
+                        "paid_sats": 0,
+                        "data_base64":
+                            base64::engine::general_purpose::STANDARD.encode(&bytes),
+                    }));
+                }
+                // Cache record exists but bytes are gone — fall through and
+                // repurchase rather than stranding the user.
+            }
+        }
+
         // `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
@@ -429,11 +501,15 @@ impl RpcHandler {
             },
             Some("fedimint") => match mint_fedimint().await {
                 Ok((notes, fed)) => {
-                    tracing::info!("paid download: spending {price_sats} sats Fedimint notes from {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:#}");
+                    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."
@@ -457,7 +533,9 @@ impl RpcHandler {
                 },
             },
         };
-        tracing::info!("paid download: paying {price_sats} sats to {onion} via {used_backend} ecash");
+        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)?;
@@ -491,13 +569,16 @@ impl RpcHandler {
             }
         };
         // Record which transport actually reached the peer (B14).
-        let _ = crate::federation::record_peer_transport(
+        if let Err(e) = crate::federation::record_peer_transport(
             &self.config.data_dir,
             None,
             Some(onion),
             &transport.to_string(),
         )
-        .await;
+        .await
+        {
+            tracing::warn!("Failed to persist peer transport badge: {e:#}");
+        }
 
         if response.status() == reqwest::StatusCode::PAYMENT_REQUIRED {
             // Payment was rejected by the seller. Surface the most likely cause
@@ -575,6 +656,54 @@ impl RpcHandler {
             tracing::warn!("paid download: failed to cache purchased content (non-fatal): {e:#}");
         }
 
+        // Auto-file the purchase into the user's Files area (2026-07-22):
+        // Photos for images/video, Music for audio, Documents otherwise —
+        // same buckets the Cloud view uses. The in-app viewer still plays
+        // from the purchase cache; this makes the file ALSO show up where
+        // files live, on every device, without relying on a browser
+        // download. Best-effort: never fail a paid download over it.
+        {
+            let folder = if mime_type.starts_with("image/") || mime_type.starts_with("video/") {
+                "Photos"
+            } else if mime_type.starts_with("audio/") {
+                "Music"
+            } else {
+                "Documents"
+            };
+            let base = std::path::Path::new(&filename)
+                .file_name()
+                .and_then(|n| n.to_str())
+                .unwrap_or("download")
+                .to_string();
+            let dir = self.config.data_dir.join("filebrowser").join(folder);
+            if let Err(e) = tokio::fs::create_dir_all(&dir).await {
+                tracing::warn!("paid download: cannot create {}: {e}", dir.display());
+            } else {
+                // Don't clobber an existing file of the same name: "x.jpg"
+                // → "x (2).jpg" etc.
+                let mut target = dir.join(&base);
+                let (stem, ext) = match base.rsplit_once('.') {
+                    Some((s, e)) if !s.is_empty() => (s.to_string(), format!(".{e}")),
+                    _ => (base.clone(), String::new()),
+                };
+                let mut n = 2;
+                while target.exists() {
+                    target = dir.join(format!("{stem} ({n}){ext}"));
+                    n += 1;
+                }
+                match tokio::fs::write(&target, &bytes).await {
+                    Ok(()) => tracing::info!(
+                        "paid download: filed into {}",
+                        target.display()
+                    ),
+                    Err(e) => tracing::warn!(
+                        "paid download: filing into {} failed (non-fatal): {e}",
+                        target.display()
+                    ),
+                }
+            }
+        }
+
         use base64::Engine;
         let encoded = base64::engine::general_purpose::STANDARD.encode(&bytes);
 
@@ -757,13 +886,16 @@ impl RpcHandler {
                 }));
             }
         };
-        let _ = crate::federation::record_peer_transport(
+        if let Err(e) = crate::federation::record_peer_transport(
             &self.config.data_dir,
             None,
             Some(onion),
             &transport.to_string(),
         )
-        .await;
+        .await
+        {
+            tracing::warn!("Failed to persist peer transport badge: {e:#}");
+        }
 
         if response.status() == reqwest::StatusCode::PAYMENT_REQUIRED {
             return Ok(serde_json::json!({
@@ -945,13 +1077,16 @@ impl RpcHandler {
                 }));
             }
         };
-        let _ = crate::federation::record_peer_transport(
+        if let Err(e) = crate::federation::record_peer_transport(
             &self.config.data_dir,
             None,
             Some(onion),
             &transport.to_string(),
         )
-        .await;
+        .await
+        {
+            tracing::warn!("Failed to persist peer transport badge: {e:#}");
+        }
 
         if response.status() == reqwest::StatusCode::PAYMENT_REQUIRED {
             return Ok(serde_json::json!({
@@ -1013,13 +1148,16 @@ impl RpcHandler {
                 .await
                 .context("Failed to connect to peer for preview")?;
         // Record which transport actually reached the peer (B14).
-        let _ = crate::federation::record_peer_transport(
+        if let Err(e) = crate::federation::record_peer_transport(
             &self.config.data_dir,
             None,
             Some(onion),
             &transport.to_string(),
         )
-        .await;
+        .await
+        {
+            tracing::warn!("Failed to persist peer transport badge: {e:#}");
+        }
 
         if !response.status().is_success() {
             return Err(anyhow::anyhow!(

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

@@ -26,6 +26,9 @@ impl RpcHandler {
             "auth.onboardingComplete" => self.handle_auth_onboarding_complete().await,
             "auth.isOnboardingComplete" => self.handle_auth_is_onboarding_complete().await,
             "auth.resetOnboarding" => self.handle_auth_reset_onboarding(params).await,
+            "auth.createDeviceToken" => self.handle_auth_create_device_token(params).await,
+            "auth.listDeviceTokens" => self.handle_auth_list_device_tokens().await,
+            "auth.revokeDeviceToken" => self.handle_auth_revoke_device_token(params).await,
 
             // Seed management (BIP-39 mnemonic)
             "seed.generate" => self.handle_seed_generate().await,
@@ -57,6 +60,8 @@ impl RpcHandler {
             "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.versions" => self.handle_package_versions(params).await,
+            "package.set-config" => self.clone().handle_package_set_config(params).await,
             "package.credentials" => self.handle_package_credentials(params).await,
             "app.filebrowser-token" => self.handle_filebrowser_token().await,
 
@@ -129,9 +134,13 @@ impl RpcHandler {
             "lnd.finalize-psbt" => self.handle_lnd_finalize_psbt(params).await,
             "lnd.create-raw-tx" => self.handle_lnd_create_raw_tx(params).await,
             "lnd.gettransactions" => self.handle_lnd_gettransactions().await,
+            "lnd.lightning-history" => self.handle_lnd_lightning_history().await,
             "lnd.connect-info" => self.handle_lnd_connect_info().await,
             "lnd.export-channel-backup" => self.handle_lnd_export_channel_backup().await,
             "lnd.init-wallet-from-seed" => self.handle_lnd_init_wallet_from_seed(params).await,
+            "lnd.seed-backup-status" => self.handle_lnd_seed_backup_status().await,
+            "lnd.seed-reveal" => self.handle_lnd_seed_reveal(params).await,
+            "lnd.seed-backup-ack" => self.handle_lnd_seed_backup_ack().await,
 
             // Multi-identity management
             "identity.list" => self.handle_identity_list(params).await,
@@ -221,6 +230,7 @@ impl RpcHandler {
             "network.list-interfaces" => self.handle_network_list_interfaces().await,
             "network.scan-wifi" => self.handle_network_scan_wifi().await,
             "network.configure-wifi" => self.handle_network_configure_wifi(params).await,
+            "network.set-wifi-radio" => self.handle_network_set_wifi_radio(params).await,
             "network.configure-ethernet" => self.handle_network_configure_ethernet(params).await,
             "network.dns-status" => self.handle_network_dns_status().await,
             "network.configure-dns" => self.handle_network_configure_dns(params).await,
@@ -228,6 +238,13 @@ impl RpcHandler {
             "router.info" => self.handle_router_info().await,
             "router.configure" => self.handle_router_configure(params).await,
 
+            // OpenWrt / TollGate
+            "openwrt.scan" => self.handle_openwrt_scan(params).await,
+            "openwrt.get-status" => self.handle_openwrt_get_status(params).await,
+            "openwrt.provision-tollgate" => self.handle_openwrt_provision_tollgate(params).await,
+            "openwrt.scan-wifi" => self.handle_openwrt_scan_wifi(params).await,
+            "openwrt.configure-wan" => self.handle_openwrt_configure_wan(params).await,
+
             // Ecash wallet
             "wallet.ecash-balance" => self.handle_wallet_ecash_balance().await,
             "wallet.ecash-mint" => self.handle_wallet_ecash_mint(params).await,
@@ -243,6 +260,18 @@ impl RpcHandler {
             "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,
+            "wallet.fedimint-send" => self.handle_wallet_fedimint_send(params).await,
+
+            // Ark protocol (via barkd sidecar)
+            "wallet.ark-status" => self.handle_wallet_ark_status().await,
+            "wallet.ark-balance" => self.handle_wallet_ark_balance().await,
+            "wallet.ark-address" => self.handle_wallet_ark_address(params).await,
+            "wallet.ark-send" => self.handle_wallet_ark_send(params).await,
+            "wallet.ark-invoice" => self.handle_wallet_ark_invoice(params).await,
+            "wallet.ark-board" => self.handle_wallet_ark_board(params).await,
+            "wallet.ark-offboard" => self.handle_wallet_ark_offboard(params).await,
+            "wallet.ark-history" => self.handle_wallet_ark_history().await,
+            "wallet.ark-configure" => self.handle_wallet_ark_configure(params).await,
 
             // Container registries
             "registry.list" => self.handle_registry_list().await,
@@ -312,7 +341,7 @@ impl RpcHandler {
             }
 
             // Federation
-            "federation.invite" => self.handle_federation_invite().await,
+            "federation.invite" => self.handle_federation_invite(params).await,
             "federation.join" => self.handle_federation_join(params).await,
             "federation.list-nodes" => self.handle_federation_list_nodes().await,
             "federation.remove-node" => self.handle_federation_remove_node(params).await,
@@ -358,12 +387,14 @@ impl RpcHandler {
 
             // Mesh networking (Meshcore LoRa)
             "mesh.status" => self.handle_mesh_status().await,
+            "mesh.probe-device" => self.handle_mesh_probe_device(params).await,
             "mesh.peers" => self.handle_mesh_peers().await,
             "mesh.messages" => self.handle_mesh_messages(params).await,
             "mesh.debug-dump" => self.handle_mesh_debug_dump().await,
             "mesh.send" => self.handle_mesh_send(params).await,
             "mesh.send-channel" => self.handle_mesh_send_channel(params).await,
             "mesh.broadcast" => self.handle_mesh_broadcast().await,
+            "mesh.reboot-radio" => self.handle_mesh_reboot_radio(params).await,
             "mesh.configure" => self.handle_mesh_configure(params).await,
             "mesh.send-invoice" => self.handle_mesh_send_invoice(params).await,
             "mesh.send-coordinate" => self.handle_mesh_send_coordinate(params).await,
@@ -416,8 +447,10 @@ impl RpcHandler {
 
             // Server settings
             "server.set-name" => self.handle_server_set_name(params).await,
+            "server.set-location" => self.handle_server_set_location(params).await,
 
             // System monitoring
+            "system.get-hostname" => self.handle_system_get_hostname().await,
             "system.stats" => self.handle_system_stats().await,
             "system.processes" => self.handle_system_processes().await,
             "system.temperature" => self.handle_system_temperature().await,
@@ -428,6 +461,8 @@ impl RpcHandler {
             "system.factory-reset" => self.handle_system_factory_reset(params).await,
             "system.settings.get" => self.handle_system_settings_get(params).await,
             "system.settings.set" => self.handle_system_settings_set(params).await,
+            "system.kiosk-display.get" => self.handle_system_kiosk_display_get().await,
+            "system.kiosk-display.set" => self.handle_system_kiosk_display_set(params).await,
 
             // Opt-in anonymous analytics
             "analytics.get-status" => self.handle_analytics_get_status().await,
@@ -456,6 +491,7 @@ impl RpcHandler {
 
             // FIPS mesh transport
             "fips.status" => self.handle_fips_status().await,
+            "fips.pair-info" => self.handle_fips_pair_info().await,
             "fips.check-update" => self.handle_fips_check_update().await,
             "fips.apply-update" => self.handle_fips_apply_update().await,
             "fips.install" => self.handle_fips_install().await,

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

@@ -53,7 +53,24 @@ impl RpcHandler {
 
 impl RpcHandler {
     /// federation.invite — Generate an invite code containing our DID + onion for a peer.
-    pub(in crate::api::rpc) async fn handle_federation_invite(&self) -> Result<serde_json::Value> {
+    /// Optional param `trust_level`: "trusted" (default, "Link Your Nodes") or
+    /// "observer" ("Invite a Peer") — the level BOTH sides assign for this invite.
+    pub(in crate::api::rpc) async fn handle_federation_invite(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let trust_level = params
+            .as_ref()
+            .and_then(|p| p.get("trust_level"))
+            .and_then(|v| v.as_str())
+            .map(|s| {
+                TrustLevel::parse(s).ok_or_else(|| {
+                    anyhow::anyhow!("Invalid trust_level: {s} (expected trusted|observer)")
+                })
+            })
+            .transpose()?
+            .unwrap_or(TrustLevel::Trusted);
+
         let (data, _) = self.state_manager.get_snapshot().await;
         let did = identity::did_key_from_pubkey_hex(&data.server_info.pubkey)?;
         let onion = data.server_info.tor_address.clone().unwrap_or_default();
@@ -72,14 +89,16 @@ impl RpcHandler {
             &onion,
             &pubkey,
             fips_npub.as_deref(),
+            trust_level,
         )
         .await?;
 
-        info!(did = %did, fips_advertised = fips_npub.is_some(), "Generated federation invite");
+        info!(did = %did, trust = %trust_level, fips_advertised = fips_npub.is_some(), "Generated federation invite");
         Ok(serde_json::json!({
             "code": code,
             "did": did,
             "onion": onion,
+            "trust_level": trust_level.to_string(),
         }))
     }
 
@@ -454,6 +473,12 @@ impl RpcHandler {
                 .flatten(),
         };
 
+        let shared_location = if data.server_info.share_location {
+            data.server_info.lat.zip(data.server_info.lon)
+        } else {
+            None
+        };
+
         let state = federation::build_local_state(
             apps,
             0.0,
@@ -467,6 +492,7 @@ impl RpcHandler {
             nostr_npub,
             own_fips_npub,
             &federated_peers,
+            shared_location,
         );
 
         Ok(serde_json::to_value(&state)?)
@@ -504,6 +530,36 @@ impl RpcHandler {
             .and_then(|v| v.as_str())
             .map(|s| s.to_string());
 
+        // Resolve the trust level granted by this join. Authoritative source:
+        // the acceptor echoes the invite's random token, which we match against
+        // OUR stored outgoing invites — the level we minted the code with wins.
+        // Fallback: the peer's (unsigned) "trust" claim, honored only as a
+        // DOWNGRADE from Trusted so it can never escalate. Legacy peers send
+        // neither → Trusted, matching pre-threading behavior.
+        let claimed_trust = params
+            .get("trust")
+            .and_then(|v| v.as_str())
+            .and_then(TrustLevel::parse)
+            .unwrap_or(TrustLevel::Trusted);
+        let invite_trust = match params.get("invite_token").and_then(|v| v.as_str()) {
+            Some(token) => federation::load_invites(&self.config.data_dir)
+                .await
+                .ok()
+                .and_then(|invites| {
+                    invites.outgoing.iter().find_map(|inv| {
+                        federation::parse_invite(&inv.code)
+                            .ok()
+                            .filter(|p| p.token == token)
+                            .map(|_| inv.trust_level)
+                    })
+                }),
+            None => None,
+        };
+        let granted_trust = match invite_trust {
+            Some(level) => level,
+            None => TrustLevel::Trusted.min(claimed_trust),
+        };
+
         // Reject self-peering. If somehow our own did / onion / pubkey
         // comes back at us (misconfigured invite, gossip loop), adding
         // the entry causes sync loops where the node syncs with itself
@@ -596,7 +652,7 @@ impl RpcHandler {
             pubkey: pubkey.to_string(),
             onion: onion.to_string(),
             name: incoming_name.clone(),
-            trust_level: TrustLevel::Trusted,
+            trust_level: granted_trust,
             added_at: chrono::Utc::now().to_rfc3339(),
             last_seen: None,
             last_state: None,
@@ -606,7 +662,7 @@ impl RpcHandler {
         };
 
         federation::add_node(&self.config.data_dir, node).await?;
-        info!(peer_did = %did, "Peer joined our federation");
+        info!(peer_did = %did, trust = %granted_trust, "Peer joined our federation");
 
         // Mirror into mesh state so the inbound peer is addressable from
         // the chat UI without waiting for the next mesh restart.
@@ -1039,12 +1095,16 @@ impl RpcHandler {
         // ciphertext below.
         let identity_dir = self.config.data_dir.join("identity");
         let local_fips_npub = identity::fips_npub(&identity_dir).await.unwrap_or(None);
+        // Discovery/connection-request approvals admit the requester as
+        // Observer — the invite itself now carries that level, so both
+        // sides converge on Observer without post-hoc demotion.
         let invite_code = federation::create_invite(
             &self.config.data_dir,
             &local_did,
             &local_onion,
             &local_pubkey,
             local_fips_npub.as_deref(),
+            TrustLevel::Observer,
         )
         .await?;
 

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

@@ -118,6 +118,31 @@ impl RpcHandler {
         Ok(serde_json::json!({ "removed": removed }))
     }
 
+    /// `wallet.fedimint-send` — spend ecash notes from any joined federation
+    /// with sufficient balance. Returns the notes token for the recipient
+    /// (rendered as text + QR by the send modal — the wallet's Fedi rail,
+    /// split from Cashu 2026-07-22). The heavy lifting already existed in
+    /// `fedimint_client::spend_from_any`; it was simply never exposed.
+    pub(super) async fn handle_wallet_fedimint_send(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let amount_sats = params
+            .as_ref()
+            .and_then(|p| p.get("amount_sats"))
+            .and_then(|v| v.as_u64())
+            .ok_or_else(|| anyhow::anyhow!("Missing amount_sats"))?;
+        anyhow::ensure!(amount_sats > 0, "must be at least 1 sat");
+        let (token, federation_id) =
+            crate::wallet::fedimint_client::spend_from_any(&self.config.data_dir, amount_sats)
+                .await?;
+        Ok(serde_json::json!({
+            "token": token,
+            "federation_id": federation_id,
+            "amount_sats": amount_sats,
+        }))
+    }
+
     /// `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