docs(release-notes): v1.7.43-alpha bullet for AIUI preservation fix

chore(release): bump version to 1.7.43-alpha
fix(aiui): bundle demo/aiui in self-update and ISO builds so updates never wipe it
2026-04-23 13:22:28 -04:00 · 2026-04-23 13:21:58 -04:00 · 2026-04-23 13:21:49 -04:00 · 2026-04-23 13:03:49 -04:00 · 2026-04-23 13:02:45 -04:00 · 2026-04-23 13:02:28 -04:00
140 changed files with 9838 additions and 2308 deletions
@@ -73,3 +73,4 @@ loop/loop.log.bak
 # Separate repos nested in tree
 web/

+._*
@@ -1,6 +1,6 @@
 {
  "version": 2,
-  "updated": "2026-04-12T00:00:00Z",
+  "updated": "2026-04-22T00:00:00Z",
  "registry": "git.tx1138.com/lfg2025",
  "featured": {
    "id": "indeedhub",
@@ -18,6 +18,14 @@
      "dockerImage": "git.tx1138.com/lfg2025/bitcoin-knots:latest",
      "repoUrl": "https://github.com/bitcoinknots/bitcoin"
    },
+    {
+      "id": "bitcoin-core", "title": "Bitcoin Core", "version": "28.4",
+      "description": "Reference implementation of the Bitcoin protocol. Run a full node validating and relaying blocks.",
+      "icon": "/assets/img/app-icons/bitcoin-core.svg",
+      "author": "Bitcoin Core contributors", "category": "money", "tier": "optional",
+      "dockerImage": "docker.io/bitcoin/bitcoin:28.4",
+      "repoUrl": "https://github.com/bitcoin/bitcoin"
+    },
    {
      "id": "lnd", "title": "LND", "version": "0.18.4",
      "description": "Lightning Network Daemon. Fast Bitcoin payments through Lightning.",
@@ -102,14 +110,6 @@
      "dockerImage": "git.tx1138.com/lfg2025/searxng:latest",
      "repoUrl": "https://github.com/searxng/searxng"
    },
-    {
-      "id": "nostr-rs-relay", "title": "Nostr Relay", "version": "0.9.0",
-      "description": "Your own Nostr relay. Store events locally, relay for friends.",
-      "icon": "/assets/img/app-icons/nostr-rs-relay.svg",
-      "author": "scsiblade", "category": "nostr",
-      "dockerImage": "git.tx1138.com/lfg2025/nostr-rs-relay:0.9.0",
-      "repoUrl": "https://sr.ht/~gheartsfield/nostr-rs-relay/"
-    },
    {
      "id": "fedimint", "title": "Fedimint", "version": "0.10.0",
      "description": "Federated Bitcoin mint with privacy through federated guardians.",
@@ -182,30 +182,6 @@
      "dockerImage": "git.tx1138.com/lfg2025/uptime-kuma:1",
      "repoUrl": "https://github.com/louislam/uptime-kuma"
    },
-    {
-      "id": "nostr-vpn", "title": "Nostr VPN", "version": "0.3.7",
-      "description": "Tailscale-style mesh VPN with Nostr control plane.",
-      "icon": "/assets/img/app-icons/nostr-vpn.svg",
-      "author": "Martti Malmi", "category": "networking",
-      "dockerImage": "git.tx1138.com/lfg2025/nostr-vpn:v0.3.7",
-      "repoUrl": "https://github.com/mmalmi/nostr-vpn"
-    },
-    {
-      "id": "fips", "title": "FIPS", "version": "0.1.0",
-      "description": "Free Internetworking Peering System. Encrypted mesh network.",
-      "icon": "/assets/img/app-icons/fips.svg",
-      "author": "Jim Corgan", "category": "networking",
-      "dockerImage": "git.tx1138.com/lfg2025/fips:v0.1.0",
-      "repoUrl": "https://github.com/jmcorgan/fips"
-    },
-    {
-      "id": "routstr", "title": "Routstr", "version": "0.4.3",
-      "description": "Decentralized AI inference proxy with Cashu ecash.",
-      "icon": "/assets/img/app-icons/routstr.svg",
-      "author": "Routstr", "category": "community",
-      "dockerImage": "git.tx1138.com/lfg2025/routstr:v0.4.3",
-      "repoUrl": "https://github.com/routstr/routstr-core"
-    },
    {
      "id": "dwn", "title": "Decentralized Web Node", "version": "0.4.0",
      "description": "Own your data with DID-based access control.",
@@ -222,14 +198,6 @@
      "dockerImage": "git.tx1138.com/lfg2025/endurain:0.8.0",
      "repoUrl": "https://github.com/joaovitoriasilva/endurain"
    },
-    {
-      "id": "penpot", "title": "Penpot", "version": "2.4",
-      "description": "Open-source design platform. Self-hosted Figma alternative.",
-      "icon": "/assets/img/app-icons/penpot.webp",
-      "author": "Penpot", "category": "data",
-      "dockerImage": "git.tx1138.com/lfg2025/penpot-frontend:2.4",
-      "repoUrl": "https://github.com/penpot/penpot"
-    },
    {
      "id": "photoprism", "title": "PhotoPrism", "version": "240915",
      "description": "AI-powered photo management with facial recognition.",
@@ -1,11 +1,11 @@
 app:
  id: bitcoin-core
  name: Bitcoin Core
-  version: 24.0.0
+  version: 28.4.0
  description: Full Bitcoin node implementation. The reference implementation of the Bitcoin protocol.
-  
+
  container:
-    image: bitcoin/bitcoin:24.0
+    image: bitcoin/bitcoin:28.4
    image_signature: cosign://...
    pull_policy: verify-signature
    
@@ -13,8 +13,8 @@ app:
    - storage: 500Gi  # Minimum disk space for mainnet
    
  resources:
-    cpu_limit: 2
-    memory_limit: 2Gi
+    cpu_limit: 0      # 0 = unlimited; bitcoind uses -par=auto across all cores
+    memory_limit: 4Gi # matches container-specs.sh bitcoin-knots large-disk dbcache=4096
    disk_limit: 500Gi
    
  security:
@@ -0,0 +1,56 @@
+app:
+  id: bitcoin-ui
+  name: Bitcoin UI
+  version: 1.0.0
+  description: |
+    Archipelago-native HTTP proxy + static site for interacting with the
+    Bitcoin Core / Bitcoin Knots JSON-RPC. Runs nginx inside a container
+    and reverse-proxies /bitcoin-rpc/ to 127.0.0.1:8332 on the host. The
+    upstream Authorization header is substituted from
+    /var/lib/archipelago/secrets/bitcoin-rpc-password by the prod
+    orchestrator's pre-start hook, rendered into an nginx.conf that is
+    bind-mounted read-only at container start.
+
+  container:
+    build:
+      context: /opt/archipelago/docker/bitcoin-ui
+      dockerfile: Dockerfile
+      tag: localhost/bitcoin-ui:local
+
+  dependencies:
+    - app_id: bitcoin-core
+
+  resources:
+    memory_limit: 128Mi
+
+  security:
+    readonly_root: false
+    network_policy: host
+
+  # Host networking: nginx listens on 8334 directly on the host IP, and
+  # proxies to 127.0.0.1:8332 which is where the bitcoin backend binds
+  # its RPC. `ports:` is intentionally empty because host networking
+  # bypasses port mapping.
+  ports: []
+
+  volumes:
+    # Bind-mount the rendered nginx.conf read-only. The prod orchestrator
+    # renders /var/lib/archipelago/bitcoin-ui/nginx.conf on every install
+    # and every reconcile pass, substituting the base64 RPC auth from
+    # the plaintext password secret. If the rendered bytes change (the
+    # password rotated, or the template was updated by OTA), the
+    # reconciler restarts this container so nginx re-reads the config.
+    - type: bind
+      source: /var/lib/archipelago/bitcoin-ui/nginx.conf
+      target: /etc/nginx/conf.d/default.conf
+      options: [ro]
+
+  environment: []
+
+  health_check:
+    type: http
+    endpoint: http://127.0.0.1:8334
+    path: /
+    interval: 30s
+    timeout: 5s
+    retries: 3
@@ -0,0 +1,38 @@
+app:
+  id: electrs-ui
+  name: Electrs UI
+  version: 1.0.0
+  description: |
+    Archipelago-native HTTP frontend for electrs/electrumx status. Runs
+    nginx inside a container, serves static assets, and proxies
+    /electrs-status to the archipelago backend on 127.0.0.1:5678.
+
+  container:
+    build:
+      context: /opt/archipelago/docker/electrs-ui
+      dockerfile: Dockerfile
+      tag: localhost/electrs-ui:local
+
+  dependencies: []
+
+  resources:
+    memory_limit: 64Mi
+
+  security:
+    readonly_root: false
+    network_policy: host
+
+  # Host networking: nginx listens on 50002 directly on the host IP.
+  ports: []
+
+  volumes: []
+
+  environment: []
+
+  health_check:
+    type: http
+    endpoint: http://127.0.0.1:50002
+    path: /
+    interval: 30s
+    timeout: 5s
+    retries: 3
@@ -0,0 +1,40 @@
+app:
+  id: lnd-ui
+  name: LND UI
+  version: 1.0.0
+  description: |
+    Archipelago-native HTTP frontend for LND. Runs nginx inside a
+    container and serves static assets. LND connection info is fetched
+    via an absolute URL that the host nginx routes to the archipelago
+    backend on 127.0.0.1:5678, so no upstream auth is baked in.
+
+  container:
+    build:
+      context: /opt/archipelago/docker/lnd-ui
+      dockerfile: Dockerfile
+      tag: localhost/lnd-ui:local
+
+  dependencies:
+    - app_id: lnd
+
+  resources:
+    memory_limit: 64Mi
+
+  security:
+    readonly_root: false
+    network_policy: host
+
+  # Host networking: nginx listens on 8081 directly on the host IP.
+  ports: []
+
+  volumes: []
+
+  environment: []
+
+  health_check:
+    type: http
+    endpoint: http://127.0.0.1:8081
+    path: /
+    interval: 30s
+    timeout: 5s
+    retries: 3
@@ -1,5 +0,0 @@
-# Penpot - uses official image
-FROM penpot/penpot:latest
-
-# Default configuration is in the image
-# No additional setup needed
@@ -1,51 +0,0 @@
-app:
-  id: penpot
-  name: Penpot
-  version: 2.0.0
-  description: Open-source design and prototyping platform. Design tools for teams.
-  
-  container:
-    image: penpotapp/frontend:2.13.3
-    image_signature: cosign://...
-    pull_policy: if-not-present
-    
-  dependencies:
-    - storage: 10Gi
-    
-  resources:
-    cpu_limit: 4
-    memory_limit: 4Gi
-    disk_limit: 10Gi
-    
-  security:
-    capabilities: []
-    readonly_root: true
-    no_new_privileges: true
-    user: 1000
-    seccomp_profile: default
-    network_policy: isolated
-    apparmor_profile: penpot
-    
-  ports:
-    - host: 8089
-      container: 80
-      protocol: tcp  # Web UI
-    
-  volumes:
-    - type: bind
-      source: /var/lib/archipelago/penpot
-      target: /app/data
-      options: [rw]
-      
-  environment:
-    - PENPOT_PUBLIC_URI=http://localhost:8089
-    - PENPOT_DATABASE_URI=postgresql://penpot:penpot@penpot-db:5432/penpot
-    - PENPOT_REDIS_URI=redis://penpot-redis:6379
-    
-  health_check:
-    type: http
-    endpoint: http://localhost:8089
-    path: /api/health
-    interval: 30s
-    timeout: 5s
-    retries: 3
@@ -80,13 +80,14 @@ checksum = "a23eb6b1614318a8071c9b2521f36b424b2c83db5eb3a0fead4a6c0809af6e61"

 [[package]]
 name = "archipelago"
-version = "1.7.28-alpha"
+version = "1.7.43-alpha"
 dependencies = [
 "anyhow",
 "archipelago-container",
 "archipelago-performance",
 "archipelago-security",
 "argon2",
+ "async-trait",
 "base64 0.21.7",
 "bcrypt",
 "bip39",
@@ -1,6 +1,6 @@
 [package]
 name = "archipelago"
-version = "1.7.28-alpha"
+version = "1.7.43-alpha"
 edition = "2021"
 description = "Archipelago Bitcoin Node OS - Native backend"
 authors = ["Archipelago Team"]
@@ -103,6 +103,9 @@ mdns-sd = "0.18"
 # Systemd watchdog notification
 sd-notify = "0.4"

+# Trait objects for async methods (container orchestrator trait, Step 4)
+async-trait = "0.1"
+
 [dev-dependencies]
 tokio-test = "0.4"
 tempfile = "3.10"
@@ -10,6 +10,7 @@ mod websocket;
 use crate::api::rpc::RpcHandler;
 use crate::blobs::BlobStore;
 use crate::config::Config;
+use crate::container::{ContainerOrchestrator, DevContainerOrchestrator};
 use crate::monitoring::MetricsStore;
 use crate::session::{self, SessionStore};
 use crate::state::StateManager;
@@ -54,6 +55,8 @@ impl ApiHandler {
        config: Config,
        state_manager: Arc<StateManager>,
        metrics_store: Arc<MetricsStore>,
+        orchestrator: Option<Arc<dyn ContainerOrchestrator>>,
+        dev_orchestrator: Option<Arc<DevContainerOrchestrator>>,
    ) -> Result<Self> {
        let session_store = SessionStore::new().await;
        let rpc_handler = Arc::new(
@@ -62,6 +65,8 @@ impl ApiHandler {
                state_manager.clone(),
                metrics_store.clone(),
                session_store.clone(),
+                orchestrator,
+                dev_orchestrator,
            )
            .await?,
        );
@@ -115,14 +120,41 @@ 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
-    /// CSP (the fallback IP-port URL isn't in `connect-src`). Tries the
-    /// upstream URLs in the same order the frontend used, returns the
-    /// first 2xx response. 15s total timeout.
-    async fn handle_app_catalog_proxy() -> Result<Response<hyper::Body>> {
-        const UPSTREAMS: &[&str] = &[
-            "https://git.tx1138.com/lfg2025/app-catalog/raw/branch/main/catalog.json",
-            "http://23.182.128.160:3000/lfg2025/app-catalog/raw/branch/main/catalog.json",
-        ];
+    /// 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.
+    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
+        {
+            for reg in config.active_registries() {
+                let scheme = if reg.tls_verify { "https" } else { "http" };
+                // Gitea raw URL: <scheme>://<host>/<namespace>/app-catalog/raw/branch/main/catalog.json.
+                // reg.url already includes the namespace (e.g. "host/lfg2025"),
+                // so we just tack on the repo + raw path.
+                upstreams.push(format!(
+                    "{}://{}/app-catalog/raw/branch/main/catalog.json",
+                    scheme, reg.url
+                ));
+            }
+        }
+        if upstreams.is_empty() {
+            upstreams.push(
+                "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()
            .timeout(std::time::Duration::from_secs(15))
            .build()
@@ -136,8 +168,8 @@ impl ApiHandler {
                ));
            }
        };
-        for url in UPSTREAMS {
-            match client.get(*url).send().await {
+        for url in &upstreams {
+            match client.get(url).send().await {
                Ok(resp) if resp.status().is_success() => {
                    if let Ok(bytes) = resp.bytes().await {
                        return Ok(Response::builder()
@@ -289,7 +321,7 @@ impl ApiHandler {

        match (method, path.as_str()) {
            // RPC — auth is handled inside rpc handler per-method
-            (Method::POST, "/rpc/v1") => self.rpc_handler.handle(req_with_bytes).await,
+            (Method::POST, "/rpc/v1") => self.rpc_handler.clone().handle(req_with_bytes).await,

            // Health — unauthenticated, returns JSON with service status
            (Method::GET, "/health") => {
@@ -408,7 +440,7 @@ impl ApiHandler {
                if !self.is_authenticated(&headers).await {
                    return Ok(Self::unauthorized());
                }
-                Self::handle_app_catalog_proxy().await
+                self.handle_app_catalog_proxy().await
            }

            // LND connect info — nginx validates session cookie (presence check),
@@ -3,6 +3,55 @@ use anyhow::{Context, Result};
 use serde::{Deserialize, Serialize};
 use zeroize::Zeroize;

+/// Retry configuration for [`bitcoin_rpc_post_with_retry`].
+///
+/// Exposed as a struct (rather than hard-coded constants inside the function)
+/// so tests can dial down timeouts to keep the suite fast while still
+/// exercising real retry/backoff behavior.
+#[derive(Debug, Clone)]
+struct RetryConfig {
+    max_attempts: u32,
+    attempt_timeout: std::time::Duration,
+    /// Length must equal `max_attempts - 1` (one backoff between each
+    /// successive attempt). The last attempt is not followed by a backoff.
+    backoffs: Vec<std::time::Duration>,
+}
+
+impl RetryConfig {
+    /// Production retry policy: 3 attempts, 15s each, 500ms + 1500ms backoffs.
+    /// Total worst-case wall time: 3 * 15 + 0.5 + 1.5 = 47s.
+    fn production() -> Self {
+        Self {
+            max_attempts: BITCOIN_RPC_MAX_ATTEMPTS,
+            attempt_timeout: BITCOIN_RPC_ATTEMPT_TIMEOUT,
+            backoffs: BITCOIN_RPC_BACKOFFS.to_vec(),
+        }
+    }
+}
+
+/// Max retry attempts for a single bitcoin_rpc_call invocation.
+/// First attempt + 2 retries = 3 total.
+const BITCOIN_RPC_MAX_ATTEMPTS: u32 = 3;
+
+/// Per-attempt deadline. Must be >= the reqwest client's own timeout (we
+/// build it at 15s in handle_bitcoin_getinfo) — this is the outer safety net.
+const BITCOIN_RPC_ATTEMPT_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(15);
+
+/// Backoff between attempts. Index 0 = after first failure, 1 = after second, etc.
+/// Chosen to absorb bitcoind's typical block-validation stall (2-5s) without
+/// adding noticeable latency on the happy path (first attempt succeeds in ~30ms).
+const BITCOIN_RPC_BACKOFFS: [std::time::Duration; 2] = [
+    std::time::Duration::from_millis(500),
+    std::time::Duration::from_millis(1500),
+];
+
+/// Classify a reqwest error as transient (retryable) or fatal.
+/// Transient: timeout, connect refused, request/response body IO errors.
+/// Fatal: TLS errors, URL parse errors, redirect loops, builder errors.
+fn is_transient_transport_error(e: &reqwest::Error) -> bool {
+    e.is_timeout() || e.is_connect() || e.is_request() || e.is_body()
+}
+
 #[derive(Debug, Serialize)]
 struct BitcoinInfo {
    block_height: u64,
@@ -37,8 +86,15 @@ struct MempoolInfo {

 impl RpcHandler {
    pub(super) async fn handle_bitcoin_getinfo(&self) -> Result<serde_json::Value> {
+        // Per-attempt timeout (see bitcoin_rpc_call for retry semantics).
+        // 15s is enough room for bitcoind to answer getblockchaininfo even
+        // during block validation; bitcoin_rpc_call wraps each attempt in a
+        // separate tokio::time::timeout too, so this is belt-and-suspenders.
+        // connect_timeout is tighter so a dead bitcoind doesn't steal the
+        // whole attempt budget on TCP connect alone.
        let client = reqwest::Client::builder()
-            .timeout(std::time::Duration::from_secs(10))
+            .timeout(std::time::Duration::from_secs(15))
+            .connect_timeout(std::time::Duration::from_secs(3))
            .build()
            .context("Failed to create HTTP client")?;

@@ -68,6 +124,19 @@ impl RpcHandler {
        Ok(serde_json::to_value(info)?)
    }

+    /// Call a Bitcoin Core JSON-RPC method.
+    ///
+    /// Retries up to [`BITCOIN_RPC_MAX_ATTEMPTS`] times on transient
+    /// transport errors (timeout / connection refused / send/recv IO).
+    /// Does **not** retry when bitcoind responds with a well-formed
+    /// `{"error": ...}` body — those are real RPC errors and surfacing
+    /// them quickly is the right behavior.
+    ///
+    /// Motivation: on a syncing pruned node, bitcoind's RPC thread can block
+    /// for 5-10 seconds during block validation. A single 10s timeout means
+    /// ~30% of UI calls error out even though the node is perfectly healthy.
+    /// With retry + backoff, the UI sees a uniform slow-but-successful
+    /// response instead of intermittent failures.
    async fn bitcoin_rpc_call<T: serde::de::DeserializeOwned>(
        &self,
        client: &reqwest::Client,
@@ -75,33 +144,15 @@ impl RpcHandler {
        params: &[serde_json::Value],
    ) -> Result<T> {
        let (rpc_user, rpc_pass) = crate::bitcoin_rpc::bitcoin_rpc_credentials().await;
-        let body = serde_json::json!({
-            "jsonrpc": "1.0",
-            "id": "archy",
-            "method": method,
-            "params": params,
-        });
-
-        let resp = client
-            .post(crate::constants::BITCOIN_RPC_URL)
-            .basic_auth(&rpc_user, Some(&rpc_pass))
-            .json(&body)
-            .send()
-            .await
-            .context("Bitcoin RPC connection failed")?;
-
-        let rpc_resp: BitcoinRpcResponse<T> = resp
-            .json()
-            .await
-            .context("Failed to parse Bitcoin RPC response")?;
-
-        if let Some(err) = rpc_resp.error {
-            anyhow::bail!("Bitcoin RPC error: {}", err);
-        }
-
-        rpc_resp
-            .result
-            .ok_or_else(|| anyhow::anyhow!("Bitcoin RPC returned null result"))
+        bitcoin_rpc_post_with_retry(
+            client,
+            crate::constants::BITCOIN_RPC_URL,
+            &rpc_user,
+            &rpc_pass,
+            method,
+            params,
+        )
+        .await
    }

    /// Initialize a Bitcoin Core descriptor wallet with keys derived from the master seed.
@@ -243,3 +294,370 @@ impl RpcHandler {
        }))
    }
 }
+
+/// Free-function counterpart to `RpcHandler::bitcoin_rpc_call`.
+///
+/// Takes the URL + credentials as parameters so it can be exercised by unit
+/// tests against a mock HTTP server without constructing a full `RpcHandler`.
+///
+/// Production callers go through `RpcHandler::bitcoin_rpc_call`, which loads
+/// credentials from the secrets file and points at `BITCOIN_RPC_URL`.
+async fn bitcoin_rpc_post_with_retry<T: serde::de::DeserializeOwned>(
+    client: &reqwest::Client,
+    url: &str,
+    rpc_user: &str,
+    rpc_pass: &str,
+    method: &str,
+    params: &[serde_json::Value],
+) -> Result<T> {
+    bitcoin_rpc_post_with_retry_cfg(
+        client,
+        url,
+        rpc_user,
+        rpc_pass,
+        method,
+        params,
+        &RetryConfig::production(),
+    )
+    .await
+}
+
+/// Inner implementation with configurable retry policy (for tests).
+async fn bitcoin_rpc_post_with_retry_cfg<T: serde::de::DeserializeOwned>(
+    client: &reqwest::Client,
+    url: &str,
+    rpc_user: &str,
+    rpc_pass: &str,
+    method: &str,
+    params: &[serde_json::Value],
+    cfg: &RetryConfig,
+) -> Result<T> {
+    debug_assert_eq!(
+        cfg.backoffs.len(),
+        (cfg.max_attempts - 1) as usize,
+        "RetryConfig: backoffs.len() must equal max_attempts - 1"
+    );
+
+    let body = serde_json::json!({
+        "jsonrpc": "1.0",
+        "id": "archy",
+        "method": method,
+        "params": params,
+    });
+
+    let mut last_err: Option<anyhow::Error> = None;
+    for attempt in 0..cfg.max_attempts {
+        if attempt > 0 {
+            let backoff = cfg
+                .backoffs
+                .get(attempt as usize - 1)
+                .copied()
+                .unwrap_or_else(|| std::time::Duration::from_secs(2));
+            tracing::warn!(
+                "bitcoin_rpc({}): attempt {} failed, backing off {:?}",
+                method,
+                attempt,
+                backoff
+            );
+            tokio::time::sleep(backoff).await;
+        }
+
+        // Per-attempt hard deadline. Independent of reqwest's built-in timeout
+        // so we always cap total time even if reqwest blocks on something
+        // weird (e.g., DNS starvation).
+        let fut = client
+            .post(url)
+            .basic_auth(rpc_user, Some(rpc_pass))
+            .json(&body)
+            .send();
+
+        let send_result = match tokio::time::timeout(cfg.attempt_timeout, fut).await {
+            Err(_elapsed) => {
+                last_err = Some(anyhow::anyhow!(
+                    "Bitcoin RPC send timed out after {:?}",
+                    cfg.attempt_timeout
+                ));
+                continue; // transient: retry
+            }
+            Ok(r) => r,
+        };
+
+        let resp = match send_result {
+            Ok(r) => r,
+            Err(e) if is_transient_transport_error(&e) => {
+                last_err = Some(anyhow::Error::from(e).context("Bitcoin RPC connection failed"));
+                continue; // transient: retry
+            }
+            Err(e) => {
+                return Err(anyhow::Error::from(e).context("Bitcoin RPC connection failed"));
+            }
+        };
+
+        let rpc_resp: BitcoinRpcResponse<T> = resp
+            .json()
+            .await
+            .context("Failed to parse Bitcoin RPC response")?;
+
+        if let Some(err) = rpc_resp.error {
+            // RPC-level error: this is a real bitcoind response, not transient.
+            anyhow::bail!("Bitcoin RPC error: {}", err);
+        }
+
+        return rpc_resp
+            .result
+            .ok_or_else(|| anyhow::anyhow!("Bitcoin RPC returned null result"));
+    }
+
+    Err(last_err.unwrap_or_else(|| {
+        anyhow::anyhow!("Bitcoin RPC exhausted retries with no error captured")
+    }))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use hyper::service::{make_service_fn, service_fn};
+    use hyper::{Body, Request, Response, Server, StatusCode};
+    use std::convert::Infallible;
+    use std::net::SocketAddr;
+    use std::sync::atomic::{AtomicU32, Ordering};
+    use std::sync::Arc;
+
+    /// Spin up a mock bitcoind HTTP server that behaves according to `handler`.
+    /// Returns the bound URL and a JoinHandle (dropped = server shutdown via the
+    /// oneshot cancel channel).
+    async fn spawn_mock<F, Fut>(
+        handler: F,
+    ) -> (String, tokio::task::JoinHandle<()>, tokio::sync::oneshot::Sender<()>)
+    where
+        F: Fn(Request<Body>) -> Fut + Send + Sync + Clone + 'static,
+        Fut: std::future::Future<Output = Response<Body>> + Send + 'static,
+    {
+        let addr = SocketAddr::from(([127, 0, 0, 1], 0));
+        let make_svc = make_service_fn(move |_| {
+            let handler = handler.clone();
+            async move {
+                Ok::<_, Infallible>(service_fn(move |req| {
+                    let handler = handler.clone();
+                    async move { Ok::<_, Infallible>(handler(req).await) }
+                }))
+            }
+        });
+        let server = Server::bind(&addr).serve(make_svc);
+        let url = format!("http://{}", server.local_addr());
+        let (tx, rx) = tokio::sync::oneshot::channel::<()>();
+        let handle = tokio::spawn(async move {
+            let graceful = server.with_graceful_shutdown(async { let _ = rx.await; });
+            let _ = graceful.await;
+        });
+        (url, handle, tx)
+    }
+
+    /// Reply body bitcoind would send for a successful getblockcount.
+    fn ok_reply() -> Body {
+        Body::from(r#"{"result":42,"error":null,"id":"archy"}"#)
+    }
+
+    fn err_reply() -> Body {
+        Body::from(r#"{"result":null,"error":{"code":-8,"message":"nope"},"id":"archy"}"#)
+    }
+
+    /// Succeeds on first attempt — should not retry.
+    #[tokio::test]
+    async fn happy_path_first_attempt() {
+        let count = Arc::new(AtomicU32::new(0));
+        let c = count.clone();
+        let (url, _h, _tx) = spawn_mock(move |_req| {
+            let c = c.clone();
+            async move {
+                c.fetch_add(1, Ordering::SeqCst);
+                Response::new(ok_reply())
+            }
+        })
+        .await;
+
+        let client = reqwest::Client::builder().build().unwrap();
+        let v: u64 = bitcoin_rpc_post_with_retry(
+            &client,
+            &url,
+            "user",
+            "pass",
+            "getblockcount",
+            &[],
+        )
+        .await
+        .expect("should succeed");
+        assert_eq!(v, 42);
+        assert_eq!(count.load(Ordering::SeqCst), 1, "should not have retried");
+    }
+
+    /// HTTP 503 with non-JSON body: produces a JSON-parse error which is NOT
+    /// classified as transient. Must fail after first attempt.
+    /// This guards against the tempting mistake of blanket-retrying every
+    /// non-2xx response — which would mask real bitcoind misconfig.
+    #[tokio::test]
+    async fn does_not_retry_parse_errors() {
+        let count = Arc::new(AtomicU32::new(0));
+        let c = count.clone();
+        let (url, _h, _tx) = spawn_mock(move |_req| {
+            let c = c.clone();
+            async move {
+                c.fetch_add(1, Ordering::SeqCst);
+                Response::builder()
+                    .status(StatusCode::SERVICE_UNAVAILABLE)
+                    .body(Body::from("busy"))
+                    .unwrap()
+            }
+        })
+        .await;
+
+        let client = reqwest::Client::builder().build().unwrap();
+        let result: Result<u64> = bitcoin_rpc_post_with_retry(
+            &client,
+            &url,
+            "user",
+            "pass",
+            "getblockcount",
+            &[],
+        )
+        .await;
+        assert!(result.is_err(), "non-JSON response should error out");
+        assert_eq!(
+            count.load(Ordering::SeqCst),
+            1,
+            "parse errors are not retryable"
+        );
+    }
+
+    /// Connect-refused (port closed) is the canonical transient transport
+    /// error. Must exhaust BITCOIN_RPC_MAX_ATTEMPTS and the total elapsed
+    /// time must include at least the sum of the backoffs.
+    #[tokio::test]
+    async fn retries_exhausted_on_persistent_connect_refused() {
+        // Bind a port then immediately drop the listener so the port is closed.
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let closed_url = format!("http://{}", listener.local_addr().unwrap());
+        drop(listener);
+
+        let client = reqwest::Client::builder()
+            .connect_timeout(std::time::Duration::from_millis(500))
+            .build()
+            .unwrap();
+        let start = std::time::Instant::now();
+        let result: Result<u64> = bitcoin_rpc_post_with_retry(
+            &client,
+            &closed_url,
+            "user",
+            "pass",
+            "getblockcount",
+            &[],
+        )
+        .await;
+        let elapsed = start.elapsed();
+        assert!(result.is_err(), "connect-refused should exhaust retries");
+        let min_backoff: std::time::Duration = BITCOIN_RPC_BACKOFFS.iter().sum();
+        assert!(
+            elapsed >= min_backoff,
+            "should have backed off between retries (elapsed={:?}, expected at least {:?})",
+            elapsed,
+            min_backoff
+        );
+    }
+
+    /// The motivating scenario: first attempt times out (bitcoind busy),
+    /// subsequent attempt succeeds. Uses a short test-only RetryConfig so
+    /// the test runs in <1s instead of 15s.
+    #[tokio::test]
+    async fn retries_on_timeout_then_succeeds() {
+        let count = Arc::new(AtomicU32::new(0));
+        let c = count.clone();
+        // Mock server: first request hangs for 500ms, subsequent requests reply OK.
+        let (url, _h, _tx) = spawn_mock(move |_req| {
+            let c = c.clone();
+            async move {
+                let n = c.fetch_add(1, Ordering::SeqCst);
+                if n == 0 {
+                    tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+                }
+                Response::new(ok_reply())
+            }
+        })
+        .await;
+
+        let client = reqwest::Client::builder().build().unwrap();
+        // Attempt timeout 100ms < server's 500ms sleep => first attempt times out.
+        // Backoff 20ms between attempts.
+        let cfg = RetryConfig {
+            max_attempts: 3,
+            attempt_timeout: std::time::Duration::from_millis(100),
+            backoffs: vec![
+                std::time::Duration::from_millis(20),
+                std::time::Duration::from_millis(20),
+            ],
+        };
+        let v: u64 = bitcoin_rpc_post_with_retry_cfg(
+            &client,
+            &url,
+            "user",
+            "pass",
+            "getblockcount",
+            &[],
+            &cfg,
+        )
+        .await
+        .expect("second attempt should succeed");
+        assert_eq!(v, 42);
+        assert!(
+            count.load(Ordering::SeqCst) >= 2,
+            "expected at least 2 attempts (got {})",
+            count.load(Ordering::SeqCst)
+        );
+    }
+
+    /// bitcoind returned a well-formed `{"error": ...}` body. Must NOT retry.
+    #[tokio::test]
+    async fn does_not_retry_on_rpc_level_error() {
+        let count = Arc::new(AtomicU32::new(0));
+        let c = count.clone();
+        let (url, _h, _tx) = spawn_mock(move |_req| {
+            let c = c.clone();
+            async move {
+                c.fetch_add(1, Ordering::SeqCst);
+                Response::new(err_reply())
+            }
+        })
+        .await;
+
+        let client = reqwest::Client::builder().build().unwrap();
+        let result: Result<u64> = bitcoin_rpc_post_with_retry(
+            &client,
+            &url,
+            "user",
+            "pass",
+            "getblockcount",
+            &[],
+        )
+        .await;
+        assert!(result.is_err());
+        assert_eq!(
+            count.load(Ordering::SeqCst),
+            1,
+            "RPC-level errors are not transient"
+        );
+    }
+
+    /// Sanity: retry budget invariants. Chosen to catch regressions where
+    /// someone bumps these constants without realizing the total worst-case
+    /// wall time implications.
+    #[test]
+    fn retry_budget_invariants() {
+        assert_eq!(BITCOIN_RPC_MAX_ATTEMPTS, 3);
+        assert_eq!(BITCOIN_RPC_BACKOFFS.len(), (BITCOIN_RPC_MAX_ATTEMPTS - 1) as usize);
+        // Total wall-time ceiling:
+        //   3 attempts * 15s  +  (0.5s + 1.5s) backoff  =  47s
+        let total: std::time::Duration =
+            BITCOIN_RPC_ATTEMPT_TIMEOUT * BITCOIN_RPC_MAX_ATTEMPTS
+                + BITCOIN_RPC_BACKOFFS.iter().sum::<std::time::Duration>();
+        assert!(total < std::time::Duration::from_secs(60));
+    }
+}
@@ -1,4 +1,5 @@
 use super::package::validate_app_id;
+use super::transitional::Op;
 use super::RpcHandler;
 use anyhow::{Context, Result};

@@ -7,8 +8,13 @@ impl RpcHandler {
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
+        // The `container-install { manifest_path }` RPC is a dev-mode convenience
+        // that points at an arbitrary YAML on disk. Production install happens via
+        // the reconciler (BootReconciler, Step 5) and via the unified
+        // ContainerOrchestrator::install(app_id) trait call, which can be exposed
+        // through a separate `container-install-by-id` RPC when needed.
+        let dev = self.dev_orchestrator.as_ref().ok_or_else(|| {
+            anyhow::anyhow!("container-install with manifest_path is only available in dev mode")
        })?;

        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
@@ -45,7 +51,7 @@ impl RpcHandler {
        let manifest: archipelago_container::AppManifest =
            serde_yaml::from_str(&manifest_content).context("Failed to parse manifest")?;

-        let container_name = orchestrator
+        let container_name = dev
            .install_container(&manifest, manifest_path)
            .await
            .context("Failed to install container")?;
@@ -57,10 +63,6 @@ impl RpcHandler {
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
-
        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
        let app_id = params
            .get("app_id")
@@ -68,22 +70,23 @@ impl RpcHandler {
            .ok_or_else(|| anyhow::anyhow!("Missing app_id"))?;
        validate_app_id(app_id)?;

-        orchestrator
-            .start_container(app_id)
-            .await
-            .context("Failed to start container")?;
+        // User explicitly started the app — clear the user-stopped marker so
+        // crash recovery / health monitor won't second-guess it. Must happen
+        // BEFORE the spawn (see runtime.rs:145-148 for the symmetric stop
+        // side and the ordering contract crash recovery depends on).
+        crate::crash_recovery::clear_user_stopped(&self.config.data_dir, app_id).await;

-        Ok(serde_json::json!({ "status": "started" }))
+        // spawn_transitional returns as soon as the background task is
+        // launched (<1s). The UI sees Starting… immediately via WebSocket.
+        self.spawn_transitional(Op::Start, app_id.to_string()).await?;
+
+        Ok(serde_json::json!({ "status": "starting" }))
    }

    pub(super) async fn handle_container_stop(
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
-
        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
        let app_id = params
            .get("app_id")
@@ -91,21 +94,50 @@ impl RpcHandler {
            .ok_or_else(|| anyhow::anyhow!("Missing app_id"))?;
        validate_app_id(app_id)?;

-        orchestrator
-            .stop_container(app_id)
-            .await
-            .context("Failed to stop container")?;
+        // Mark as user-stopped BEFORE the spawn — ordering is load-bearing
+        // (crash recovery / health monitor inspect this flag concurrently
+        // with the in-flight stop; see runtime.rs:145-148 for the package
+        // path that also writes this in the same order).
+        crate::crash_recovery::mark_user_stopped(&self.config.data_dir, app_id).await;

-        Ok(serde_json::json!({ "status": "stopped" }))
+        // podman stop -t 600 (bitcoin-core) / -t 330 (lnd) runs in the
+        // background; the RPC returns now with "stopping".
+        self.spawn_transitional(Op::Stop, app_id.to_string()).await?;
+
+        Ok(serde_json::json!({ "status": "stopping" }))
+    }
+
+    pub(super) async fn handle_container_restart(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let app_id = params
+            .get("app_id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing app_id"))?;
+        validate_app_id(app_id)?;
+
+        // Restart does not mark user-stopped (the user wants the app to
+        // keep running). Clear the marker as a defensive measure in case a
+        // prior stop left it set and the restart is intended to revive the
+        // normal running state.
+        crate::crash_recovery::clear_user_stopped(&self.config.data_dir, app_id).await;
+
+        self.spawn_transitional(Op::Restart, app_id.to_string())
+            .await?;
+
+        Ok(serde_json::json!({ "status": "restarting" }))
    }

    pub(super) async fn handle_container_remove(
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
+        let orchestrator = self
+            .orchestrator
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Container orchestrator not available"))?;

        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
        let app_id = params
@@ -119,7 +151,7 @@ impl RpcHandler {
            .unwrap_or(false);

        orchestrator
-            .remove_container(app_id, preserve_data)
+            .remove(app_id, preserve_data)
            .await
            .context("Failed to remove container")?;

@@ -137,12 +169,25 @@ impl RpcHandler {
                .package_data
                .iter()
                .map(|(id, pkg)| {
+                    // Keep this mapping in sync with the UI's
+                    // ContainerStatus.state union in
+                    // neode-ui/src/api/container-client.ts. The UI maps
+                    // transitional variants to single-button labels
+                    // (Stopping… / Starting… / Restarting…).
                    let state = match &pkg.state {
                        crate::data_model::PackageState::Running => "running",
                        crate::data_model::PackageState::Stopped => "stopped",
                        crate::data_model::PackageState::Exited => "exited",
-                        crate::data_model::PackageState::Starting => "created",
-                        _ => "unknown",
+                        crate::data_model::PackageState::Starting => "starting",
+                        crate::data_model::PackageState::Stopping => "stopping",
+                        crate::data_model::PackageState::Restarting => "restarting",
+                        crate::data_model::PackageState::Installing => "installing",
+                        crate::data_model::PackageState::Installed => "installed",
+                        crate::data_model::PackageState::Updating => "updating",
+                        crate::data_model::PackageState::Removing => "removing",
+                        crate::data_model::PackageState::CreatingBackup => "creating-backup",
+                        crate::data_model::PackageState::RestoringBackup => "restoring-backup",
+                        crate::data_model::PackageState::BackingUp => "backing-up",
                    };
                    let lan = pkg
                        .installed
@@ -163,9 +208,9 @@ impl RpcHandler {
            return Ok(serde_json::json!(containers));
        }

-        // Fallback: scanner hasn't run yet, query podman directly
+        // Fallback: scanner hasn't run yet, query the orchestrator directly.
        if let Some(orchestrator) = &self.orchestrator {
-            if let Ok(containers) = orchestrator.list_containers().await {
+            if let Ok(containers) = orchestrator.list().await {
                if !containers.is_empty() {
                    return Ok(serde_json::to_value(containers)?);
                }
@@ -242,9 +287,10 @@ impl RpcHandler {
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
+        let orchestrator = self
+            .orchestrator
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Container orchestrator not available"))?;

        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
        let app_id = params
@@ -254,7 +300,7 @@ impl RpcHandler {
        validate_app_id(app_id)?;

        let status = orchestrator
-            .get_container_status(app_id)
+            .status(app_id)
            .await
            .context("Failed to get container status")?;

@@ -265,9 +311,10 @@ impl RpcHandler {
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
+        let orchestrator = self
+            .orchestrator
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Container orchestrator not available"))?;

        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
        let app_id = params
@@ -278,7 +325,7 @@ impl RpcHandler {
        let lines = params.get("lines").and_then(|v| v.as_u64()).unwrap_or(100) as u32;

        let logs = orchestrator
-            .get_container_logs(app_id, lines)
+            .logs(app_id, lines)
            .await
            .context("Failed to get container logs")?;

@@ -291,12 +338,13 @@ impl RpcHandler {
        app_id: &str,
        lines: u32,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
+        let orchestrator = self
+            .orchestrator
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Container orchestrator not available"))?;

        let logs = orchestrator
-            .get_container_logs(app_id, lines)
+            .logs(app_id, lines)
            .await
            .context("Failed to get container logs")?;

@@ -307,43 +355,52 @@ impl RpcHandler {
        &self,
        params: Option<serde_json::Value>,
    ) -> Result<serde_json::Value> {
-        let orchestrator = self.orchestrator.as_ref().ok_or_else(|| {
-            anyhow::anyhow!("Container orchestrator not available (dev mode required)")
-        })?;
+        let orchestrator = self
+            .orchestrator
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Container orchestrator not available"))?;

-        // If app_id is provided, get health for that app
+        // If app_id is provided, get health for that app.
        if let Some(params) = params {
            if let Some(app_id) = params.get("app_id").and_then(|v| v.as_str()) {
                let health = orchestrator
-                    .get_health_status(app_id)
+                    .health(app_id)
                    .await
                    .context("Failed to get container health")?;
                return Ok(serde_json::json!({ app_id: health }));
            }
        }

-        // Otherwise, get health for all containers
+        // Otherwise, get health for all containers.
        let containers = orchestrator
-            .list_containers()
+            .list()
            .await
            .context("Failed to list containers")?;

        let mut health_map = serde_json::Map::new();
        for container in containers {
-            if let Some(app_id) = container.name.strip_prefix("archipelago-") {
-                if let Some(app_id) = app_id.strip_suffix("-dev") {
-                    match orchestrator.get_health_status(app_id).await {
-                        Ok(health) => {
-                            health_map
-                                .insert(app_id.to_string(), serde_json::Value::String(health));
-                        }
-                        Err(_) => {
-                            health_map.insert(
-                                app_id.to_string(),
-                                serde_json::Value::String("unknown".to_string()),
-                            );
-                        }
-                    }
+            // Map the runtime container name back to the app_id the orchestrator
+            // knows about. Dev orchestrator uses `archipelago-<id>-dev`; Prod
+            // uses bare `<id>` (or `archy-<id>` for UIs — health() accepts the
+            // app_id either way since UI_APP_IDS is centralised).
+            let app_id_candidate = container
+                .name
+                .strip_prefix("archipelago-")
+                .and_then(|s| s.strip_suffix("-dev"))
+                .or_else(|| container.name.strip_prefix("archy-"))
+                .unwrap_or(container.name.as_str());
+            match orchestrator.health(app_id_candidate).await {
+                Ok(health) => {
+                    health_map.insert(
+                        app_id_candidate.to_string(),
+                        serde_json::Value::String(health),
+                    );
+                }
+                Err(_) => {
+                    health_map.insert(
+                        app_id_candidate.to_string(),
+                        serde_json::Value::String("unknown".to_string()),
+                    );
                }
            }
        }
@@ -1,10 +1,11 @@
 use super::RpcHandler;
 use anyhow::Result;
+use std::sync::Arc;

 impl RpcHandler {
    /// Route an RPC method name to its handler, returning the result value.
    pub(super) async fn dispatch(
-        &self,
+        self: &Arc<Self>,
        method: &str,
        params: Option<serde_json::Value>,
        session_token: &Option<String>,
@@ -36,19 +37,23 @@ impl RpcHandler {
            "container-install" => self.handle_container_install(params).await,
            "container-start" => self.handle_container_start(params).await,
            "container-stop" => self.handle_container_stop(params).await,
+            "container-restart" => self.handle_container_restart(params).await,
            "container-remove" => self.handle_container_remove(params).await,
            "container-list" => self.handle_container_list().await,
            "container-status" => self.handle_container_status(params).await,
            "container-logs" => self.handle_container_logs(params).await,
            "container-health" => self.handle_container_health(params).await,

-            // Package management (for docker-compose apps)
-            "package.install" => self.handle_package_install(params).await,
+            // Package management (for docker-compose apps).
+            // install/uninstall/update return immediately with a
+            // transitional status; the actual work runs in a background
+            // tokio::spawn so the HTTP request doesn't block for minutes.
+            "package.install" => self.clone().spawn_package_install(params).await,
            "package.start" => self.handle_package_start(params).await,
            "package.stop" => self.handle_package_stop(params).await,
            "package.restart" => self.handle_package_restart(params).await,
-            "package.uninstall" => self.handle_package_uninstall(params).await,
-            "package.update" => self.handle_package_update(params).await,
+            "package.uninstall" => self.clone().spawn_package_uninstall(params).await,
+            "package.update" => self.clone().spawn_package_update(params).await,
            "app.filebrowser-token" => self.handle_filebrowser_token().await,

            // Bundled app management (for pre-loaded container images)
@@ -220,6 +225,7 @@ impl RpcHandler {
            "registry.list" => self.handle_registry_list().await,
            "registry.add" => self.handle_registry_add(params).await,
            "registry.remove" => self.handle_registry_remove(params).await,
+            "registry.set-primary" => self.handle_registry_set_primary(params).await,
            "registry.test" => self.handle_registry_test(params).await,

            // Streaming ecash payments
@@ -3,7 +3,7 @@ use anyhow::{Context, Result};
 use base64::Engine;
 use serde::{Deserialize, Serialize};

-use super::{LndAmount, LndBalanceResponse};
+use super::{LndAmount, LndBalanceResponse, read_lnd_admin_macaroon};

 #[derive(Debug, Serialize)]
 struct LndInfo {
@@ -34,11 +34,7 @@ struct LndChannelBalanceResponse {

 impl RpcHandler {
    pub(in crate::api::rpc) async fn handle_lnd_getinfo(&self) -> Result<serde_json::Value> {
-        let macaroon_path = "/var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon";
-
-        let macaroon_bytes = tokio::fs::read(macaroon_path)
-            .await
-            .context("Failed to read LND admin macaroon — is LND installed?")?;
+        let macaroon_bytes = read_lnd_admin_macaroon().await?;
        let macaroon_hex = hex::encode(&macaroon_bytes);

        let client = reqwest::Client::builder()
@@ -114,7 +110,6 @@ impl RpcHandler {
    /// for building lndconnect:// URIs in the frontend.
    pub(crate) async fn handle_lnd_connect_info(&self) -> Result<serde_json::Value> {
        let cert_path = "/var/lib/archipelago/lnd/tls.cert";
-        let macaroon_path = "/var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon";

        // Read and encode TLS cert (PEM -> DER -> base64url)
        let cert_pem = tokio::fs::read_to_string(cert_path)
@@ -130,9 +125,7 @@ impl RpcHandler {
        let cert_b64url = base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(&cert_der);

        // Read and encode macaroon (binary -> base64url)
-        let macaroon_bytes = tokio::fs::read(macaroon_path)
-            .await
-            .context("Failed to read LND admin macaroon")?;
+        let macaroon_bytes = read_lnd_admin_macaroon().await?;
        let macaroon_b64url =
            base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(&macaroon_bytes);

@@ -183,10 +176,7 @@ impl RpcHandler {
    pub(in crate::api::rpc) async fn handle_lnd_export_channel_backup(
        &self,
    ) -> Result<serde_json::Value> {
-        let macaroon_path = "/var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon";
-        let macaroon_bytes = tokio::fs::read(macaroon_path)
-            .await
-            .context("Failed to read LND admin macaroon")?;
+        let macaroon_bytes = read_lnd_admin_macaroon().await?;
        let macaroon_hex = hex::encode(&macaroon_bytes);

        let client = reqwest::Client::builder()
@@ -4,7 +4,11 @@ mod payments;
 mod wallet;

 use crate::api::rpc::RpcHandler;
-use anyhow::{Context, Result};
+use anyhow::{Context, Result, anyhow};
+
+/// Canonical on-host path for LND's admin macaroon.
+pub(crate) const LND_ADMIN_MACAROON_PATH: &str =
+    "/var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon";

 // Shared LND response types used by multiple submodules
 #[derive(Debug, serde::Deserialize)]
@@ -17,15 +21,45 @@ pub(super) struct LndAmount {
    pub sat: Option<String>,
 }

+/// Read LND's admin macaroon from disk.
+///
+/// The macaroon lives inside LND's container data dir and is owned by a
+/// rootless-podman subordinate UID (typically 100000), mode 640. The
+/// archipelago server runs as UID 1000 and therefore cannot read it
+/// directly. We first try a plain read (works if an operator has relaxed
+/// permissions), then fall back to `sudo cat` — mirroring the pattern
+/// already used for Tor hidden-service hostnames.
+pub(crate) async fn read_lnd_admin_macaroon() -> Result<Vec<u8>> {
+    match tokio::fs::read(LND_ADMIN_MACAROON_PATH).await {
+        Ok(bytes) => Ok(bytes),
+        Err(direct_err) => {
+            let output = tokio::process::Command::new("sudo")
+                .args(["-n", "cat", LND_ADMIN_MACAROON_PATH])
+                .output()
+                .await
+                .with_context(|| {
+                    format!(
+                        "Failed to read LND admin macaroon (direct: {direct_err}); sudo fallback also failed"
+                    )
+                })?;
+            if !output.status.success() {
+                let stderr = String::from_utf8_lossy(&output.stderr);
+                return Err(anyhow!(
+                    "Failed to read LND admin macaroon — is LND installed? (direct: {direct_err}; sudo: {})",
+                    stderr.trim()
+                ));
+            }
+            Ok(output.stdout)
+        }
+    }
+}
+
 impl RpcHandler {
    /// Helper: create an authenticated LND REST client.
    /// Returns an HTTP client configured for LND's self-signed TLS and the
    /// hex-encoded admin macaroon for request headers.
    pub(crate) async fn lnd_client(&self) -> Result<(reqwest::Client, String)> {
-        let macaroon_path = "/var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon";
-        let macaroon_bytes = tokio::fs::read(macaroon_path)
-            .await
-            .context("Failed to read LND admin macaroon — is LND installed?")?;
+        let macaroon_bytes = read_lnd_admin_macaroon().await?;
        let macaroon_hex = hex::encode(&macaroon_bytes);
        let client = reqwest::Client::builder()
            .timeout(std::time::Duration::from_secs(15))
@@ -31,6 +31,7 @@ mod streaming;
 mod system;
 mod tor;
 mod totp;
+mod transitional;
 mod transport;
 mod update;
 mod vpn;
@@ -39,7 +40,7 @@ mod webhooks;

 use crate::auth::AuthManager;
 use crate::config::Config;
-use crate::container::DevContainerOrchestrator;
+use crate::container::{ContainerOrchestrator, DevContainerOrchestrator};
 use crate::monitoring::MetricsStore;
 use crate::port_allocator::PortAllocator;
 use crate::rate_limit::{EndpointRateLimiter, LoginRateLimiter};
@@ -62,7 +63,14 @@ pub(crate) const DEV_DEFAULT_PASSWORD: &str = "password123";
 pub struct RpcHandler {
    config: Config,
    auth_manager: AuthManager,
-    orchestrator: Option<Arc<DevContainerOrchestrator>>,
+    /// Shared lifecycle orchestrator (Dev or Prod). Always `Some` in a normal
+    /// build — the only reason it is `Option` is so tests that don't exercise
+    /// container RPCs can skip constructing one.
+    orchestrator: Option<Arc<dyn ContainerOrchestrator>>,
+    /// Concrete handle to the dev orchestrator, when we're in dev mode. Used by
+    /// `container-install { manifest_path }` which takes an ad-hoc manifest
+    /// path and is not part of the shared trait.
+    dev_orchestrator: Option<Arc<DevContainerOrchestrator>>,
    state_manager: Arc<StateManager>,
    pub(crate) metrics_store: Arc<MetricsStore>,
    port_allocator: Arc<tokio::sync::Mutex<PortAllocator>>,
@@ -79,6 +87,15 @@ pub struct RpcHandler {
    /// Our own Ed25519 pubkey hex — needed by ContentRef senders for cap scoping
    /// and by ContentRef receivers to request caps scoped to themselves.
    pub(crate) self_pubkey_hex: Arc<tokio::sync::RwLock<Option<String>>>,
+    /// Kick the package scanner to run immediately (bypassing the 60s interval).
+    /// Used by install/update success paths so the fresh manifest (with populated
+    /// `interfaces.main.ui`) lands before we flip state to Running — closes the
+    /// "Launch button is missing for up to 60s after install" UX gap.
+    pub(crate) scan_kick: Arc<tokio::sync::Notify>,
+    /// Monotonic counter incremented by the scan loop after each completed scan.
+    /// Install/update success paths subscribe to this to know when a kicked scan
+    /// has actually finished before flipping to the terminal state.
+    pub(crate) scan_tick: Arc<tokio::sync::watch::Sender<u64>>,
 }

 impl RpcHandler {
@@ -87,15 +104,10 @@ impl RpcHandler {
        state_manager: Arc<StateManager>,
        metrics_store: Arc<MetricsStore>,
        session_store: SessionStore,
+        orchestrator: Option<Arc<dyn ContainerOrchestrator>>,
+        dev_orchestrator: Option<Arc<DevContainerOrchestrator>>,
    ) -> Result<Self> {
        let auth_manager = AuthManager::new(config.data_dir.clone());
-        let orchestrator = if config.dev_mode {
-            Some(Arc::new(
-                DevContainerOrchestrator::new(config.clone()).await?,
-            ))
-        } else {
-            None
-        };
        let port_allocator = Arc::new(tokio::sync::Mutex::new(
            PortAllocator::new(&config.data_dir).await?,
        ));
@@ -129,6 +141,7 @@ impl RpcHandler {
            config,
            auth_manager,
            orchestrator,
+            dev_orchestrator,
            state_manager,
            metrics_store,
            port_allocator,
@@ -140,6 +153,8 @@ impl RpcHandler {
            transport_router: Arc::new(tokio::sync::RwLock::new(None)),
            blob_store: Arc::new(tokio::sync::RwLock::new(None)),
            self_pubkey_hex: Arc::new(tokio::sync::RwLock::new(None)),
+            scan_kick: Arc::new(tokio::sync::Notify::new()),
+            scan_tick: Arc::new(tokio::sync::watch::channel(0u64).0),
        })
    }

@@ -180,6 +195,21 @@ impl RpcHandler {
        Arc::clone(&self.mesh_service)
    }

+    /// Shared Notify handle the package-scanner loop waits on (in addition to
+    /// its periodic tick). Install/update success paths call `notify_one()` to
+    /// trigger an immediate scan so the fresh manifest lands before we flip to
+    /// the terminal Running state.
+    pub fn scan_kick(&self) -> Arc<tokio::sync::Notify> {
+        Arc::clone(&self.scan_kick)
+    }
+
+    /// Sender half of the scan-completion watch channel. The scanner bumps this
+    /// counter after every finished scan; install/update wait for an advance
+    /// after kicking so they know the fresh manifest has landed.
+    pub fn scan_tick(&self) -> Arc<tokio::sync::watch::Sender<u64>> {
+        Arc::clone(&self.scan_tick)
+    }
+
    fn cookie_suffix_for_request(&self, headers: &hyper::header::HeaderMap) -> &'static str {
        // Only set Secure flag when the original request was over HTTPS.
        // Nginx sends X-Forwarded-Proto: https for HTTPS connections.
@@ -197,7 +227,10 @@ impl RpcHandler {
        ""
    }

-    pub async fn handle(&self, req: Request<hyper::Body>) -> Result<Response<hyper::Body>> {
+    pub async fn handle(
+        self: Arc<Self>,
+        req: Request<hyper::Body>,
+    ) -> Result<Response<hyper::Body>> {
        // Extract session cookie before consuming the request
        let (parts, body) = req.into_parts();
        let session_token = session::extract_session_cookie(&parts.headers);
@@ -376,7 +409,7 @@ impl RpcHandler {

        // Route to handler (track latency for metrics)
        let rpc_start = std::time::Instant::now();
-        let result = self.dispatch(&rpc_req.method, params, &session_token).await;
+        let result = Self::dispatch(&self, &rpc_req.method, params, &session_token).await;

        // Record RPC latency for monitoring
        let elapsed_ms = rpc_start.elapsed().as_secs_f64() * 1000.0;
@@ -0,0 +1,450 @@
+//! Async wrappers for `package.install`, `package.uninstall`, `package.update`.
+//!
+//! The inner `handle_package_*` functions are large (install is 480 lines with
+//! the stack dispatchers, update is 300, uninstall is 200) and do their own
+//! fine-grained progress tracking via `install_progress` and `uninstall_stage`.
+//! We wrap them rather than refactor them.
+//!
+//! Each wrapper:
+//!   1. Parses + validates the RPC params (cheap, synchronous). Errors here
+//!      return immediately to the caller before any state change.
+//!   2. Flips the package state to the transitional variant
+//!      (`Installing` / `Removing` / `Updating`) so the UI sees it on the
+//!      next WebSocket push (before the RPC response even lands).
+//!   3. `tokio::spawn`s a background task that invokes the existing
+//!      `handle_package_*` method on the Arc-held self.
+//!   4. On task success: no state change needed — the inner handler has
+//!      already written the terminal state (Running for install/update, or
+//!      removed the entry for uninstall).
+//!   5. On task failure: revert state to the pre-transition value (or delete
+//!      the entry for install, since there was no pre-state), write a line
+//!      to the persistent install log, and clear any stale progress fields.
+//!   6. Returns `{ "status": "installing" }` etc. immediately.
+//!
+//! The server package-scan loop's `merge_preserving_transitional` helper
+//! already knows to preserve `Installing` / `Removing` / `Updating` between
+//! scans, so live progress updates broadcast from inside the spawned task
+//! reach the UI correctly.
+
+use super::install::install_log;
+use crate::api::rpc::RpcHandler;
+use crate::data_model::PackageState;
+use crate::state::StateManager;
+use anyhow::Result;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+impl RpcHandler {
+    /// Async wrapper for `package.install`. Returns `{ "status": "installing" }`
+    /// immediately after flipping state to `Installing` and spawning the
+    /// actual install pipeline. On failure, removes the package entry from
+    /// state so the UI reverts to "not installed".
+    pub(in crate::api::rpc) async fn spawn_package_install(
+        self: Arc<Self>,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        // Extract + validate package_id synchronously so bad params fail
+        // fast without touching state.
+        let params_val = params
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let package_id = params_val
+            .get("id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing package id"))?
+            .to_string();
+        super::validation::validate_app_id(&package_id)?;
+
+        // Reject if already in a transitional lifecycle (prevents double-click
+        // queuing two installs on the same package).
+        {
+            let (data, _) = self.state_manager.get_snapshot().await;
+            if let Some(entry) = data.package_data.get(&package_id) {
+                if matches!(
+                    entry.state,
+                    PackageState::Installing
+                        | PackageState::Removing
+                        | PackageState::Updating
+                ) {
+                    return Err(anyhow::anyhow!(
+                        "{} is already {:?}",
+                        package_id,
+                        entry.state
+                    ));
+                }
+            }
+        }
+
+        // Flip state to Installing BEFORE the spawn so the first WebSocket
+        // push carries the transitional state. Uses the same
+        // `create_installing_entry` path the inner handler would use once
+        // it starts pulling, so the UI sees a consistent shape.
+        flip_to_installing(&self.state_manager, &package_id).await;
+
+        install_log(&format!("INSTALL SPAWN: {}", package_id)).await;
+
+        let handler = Arc::clone(&self);
+        let package_id_spawn = package_id.clone();
+        tokio::spawn(async move {
+            match handler.handle_package_install(params).await {
+                Ok(_) => {
+                    info!("package.install {}: complete", package_id_spawn);
+                    // The install pipeline has verified the container is up
+                    // and healthy (see install.rs post-start exit check).
+                    // Kick the scanner first so the fresh manifest (with
+                    // `interfaces.main.ui` from the live port binding) lands
+                    // BEFORE we flip to Running — without this the Launch
+                    // button is missing for up to 60s after a successful
+                    // install, because the skeletal install-time manifest
+                    // has `interfaces: None`.
+                    kick_scanner_and_wait(&handler).await;
+                    // We MUST explicitly transition out of Installing here:
+                    // `merge_preserving_transitional` in the package-scan
+                    // loop treats Installing as RPC-owned and refuses to
+                    // let the scanner overwrite it with the observed
+                    // Running state. Without this write, the entry stays
+                    // stuck at Installing forever.
+                    set_package_state(
+                        &handler.state_manager,
+                        &package_id_spawn,
+                        PackageState::Running,
+                    )
+                    .await;
+                    handler.clear_install_progress(&package_id_spawn).await;
+                }
+                Err(e) => {
+                    error!("package.install {} failed: {:#}", package_id_spawn, e);
+                    install_log(&format!("INSTALL FAIL: {} — {:#}", package_id_spawn, e))
+                        .await;
+                    // No pre-state to revert to — remove the entry entirely so
+                    // the UI shows the app as not installed. The next package
+                    // scan will re-create it only if podman actually has a
+                    // container for it (partial install recovery).
+                    remove_package_entry(&handler.state_manager, &package_id_spawn).await;
+                }
+            }
+        });
+
+        Ok(serde_json::json!({
+            "status": "installing",
+            "package_id": package_id,
+        }))
+    }
+
+    /// Async wrapper for `package.uninstall`. Returns `{ "status": "removing" }`
+    /// immediately. State stays `Removing` until the inner handler finishes
+    /// (including the `sudo rm -rf` of app data, which can take minutes for
+    /// bitcoin-core's chainstate). On failure, reverts to the pre-transition
+    /// state (usually Running or Stopped) so the user can retry.
+    pub(in crate::api::rpc) async fn spawn_package_uninstall(
+        self: Arc<Self>,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params_val = params
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let package_id = params_val
+            .get("id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing package id"))?
+            .to_string();
+        super::validation::validate_app_id(&package_id)?;
+
+        // Reject if already in a transitional lifecycle.
+        {
+            let (data, _) = self.state_manager.get_snapshot().await;
+            if let Some(entry) = data.package_data.get(&package_id) {
+                if matches!(
+                    entry.state,
+                    PackageState::Installing
+                        | PackageState::Removing
+                        | PackageState::Updating
+                ) {
+                    return Err(anyhow::anyhow!(
+                        "{} is already {:?}",
+                        package_id,
+                        entry.state
+                    ));
+                }
+            }
+        }
+
+        let pre_state =
+            flip_package_state(&self.state_manager, &package_id, PackageState::Removing).await;
+
+        install_log(&format!("UNINSTALL SPAWN: {}", package_id)).await;
+
+        let handler = Arc::clone(&self);
+        let package_id_spawn = package_id.clone();
+        tokio::spawn(async move {
+            match handler.handle_package_uninstall(params).await {
+                Ok(_) => {
+                    info!("package.uninstall {}: complete", package_id_spawn);
+                    // Inner handler already removed the package entry on
+                    // success. Nothing more to do here.
+                }
+                Err(e) => {
+                    error!("package.uninstall {} failed: {:#}", package_id_spawn, e);
+                    install_log(&format!(
+                        "UNINSTALL FAIL: {} — {:#}",
+                        package_id_spawn, e
+                    ))
+                    .await;
+                    // Revert to pre-transition state so the user can retry.
+                    // Also clear any stale uninstall_stage label.
+                    if let Some(prev) = pre_state {
+                        set_package_state_and_clear_uninstall_stage(
+                            &handler.state_manager,
+                            &package_id_spawn,
+                            prev,
+                        )
+                        .await;
+                    }
+                }
+            }
+        });
+
+        Ok(serde_json::json!({
+            "status": "removing",
+            "package_id": package_id,
+        }))
+    }
+
+    /// Async wrapper for `package.update`. Returns `{ "status": "updating" }`
+    /// immediately. The inner handler already manages its own rollback on
+    /// failure (restarts old containers); this wrapper just flips state and
+    /// spawns.
+    pub(in crate::api::rpc) async fn spawn_package_update(
+        self: Arc<Self>,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params_val = params
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let package_id = params_val
+            .get("id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing package id"))?
+            .to_string();
+        super::validation::validate_app_id(&package_id)?;
+
+        // Reject if already in a transitional lifecycle.
+        {
+            let (data, _) = self.state_manager.get_snapshot().await;
+            if let Some(entry) = data.package_data.get(&package_id) {
+                if matches!(
+                    entry.state,
+                    PackageState::Installing
+                        | PackageState::Removing
+                        | PackageState::Updating
+                ) {
+                    return Err(anyhow::anyhow!(
+                        "{} is already {:?}",
+                        package_id,
+                        entry.state
+                    ));
+                }
+            }
+        }
+
+        // The inner handler flips state to Updating itself, but we do it
+        // here too so the transitional state lands before the spawn yields.
+        let pre_state =
+            flip_package_state(&self.state_manager, &package_id, PackageState::Updating).await;
+
+        install_log(&format!("UPDATE SPAWN: {}", package_id)).await;
+
+        let handler = Arc::clone(&self);
+        let package_id_spawn = package_id.clone();
+        tokio::spawn(async move {
+            match handler.handle_package_update(params).await {
+                Ok(_) => {
+                    info!("package.update {}: complete", package_id_spawn);
+                    // Same reasoning as install: the merge_preserving_transitional
+                    // helper treats Updating as RPC-owned, so we MUST write the
+                    // terminal Running state ourselves or the entry will stay
+                    // stuck at Updating forever. The update pipeline has
+                    // already verified the new container is running via its
+                    // post-recreate check.
+                    // Kick the scanner first so any manifest changes from the
+                    // new image version (interfaces, ports, etc.) land before
+                    // we flip to Running.
+                    kick_scanner_and_wait(&handler).await;
+                    set_package_state(
+                        &handler.state_manager,
+                        &package_id_spawn,
+                        PackageState::Running,
+                    )
+                    .await;
+                }
+                Err(e) => {
+                    error!("package.update {} failed: {:#}", package_id_spawn, e);
+                    install_log(&format!("UPDATE FAIL: {} — {:#}", package_id_spawn, e))
+                        .await;
+                    // Inner handler already ran rollback_update + cleared
+                    // update state, but be defensive: revert to pre-state
+                    // in case the inner flow died before its cleanup.
+                    if let Some(prev) = pre_state {
+                        set_package_state(&handler.state_manager, &package_id_spawn, prev)
+                            .await;
+                    }
+                }
+            }
+        });
+
+        Ok(serde_json::json!({
+            "status": "updating",
+            "package_id": package_id,
+        }))
+    }
+}
+
+// ---------------------------------------------------------------------------
+// State-manager helpers (free fns, usable from inside spawned tasks)
+// ---------------------------------------------------------------------------
+
+/// Create or update the entry for this package with `Installing` state.
+/// Matches what the inner handler's `set_install_progress` would do on first
+/// call, but fires before the spawn so the UI sees it immediately.
+async fn flip_to_installing(state_manager: &StateManager, package_id: &str) {
+    use crate::data_model::{Description, Manifest, PackageDataEntry, StaticFiles};
+    let (mut data, _) = state_manager.get_snapshot().await;
+    let entry = data
+        .package_data
+        .entry(package_id.to_string())
+        .or_insert_with(|| PackageDataEntry {
+            state: PackageState::Installing,
+            health: None,
+            exit_code: None,
+            static_files: StaticFiles {
+                license: String::new(),
+                instructions: String::new(),
+                // Leave icon empty during the transient Installing window:
+                // hardcoding `<id>.png` is wrong for ~half our apps (many use
+                // `.svg` / `.webp`), producing a broken-image flicker until
+                // the scanner refreshes the entry. The frontend's `icon`
+                // computed falls through to `curatedMap.get(id)?.icon` which
+                // has the correct extensions for known apps.
+                icon: String::new(),
+            },
+            manifest: Manifest {
+                id: package_id.to_string(),
+                title: package_id.to_string(),
+                version: String::new(),
+                description: Description {
+                    short: "Installing...".to_string(),
+                    long: String::new(),
+                },
+                release_notes: String::new(),
+                license: String::new(),
+                wrapper_repo: String::new(),
+                upstream_repo: String::new(),
+                support_site: String::new(),
+                marketing_site: String::new(),
+                donation_url: None,
+                author: None,
+                website: None,
+                interfaces: None,
+                tier: None,
+            },
+            installed: None,
+            install_progress: None,
+            uninstall_stage: None,
+            available_update: None,
+        });
+    entry.state = PackageState::Installing;
+    state_manager.update_data(data).await;
+}
+
+/// Flip an existing entry's state and return the pre-flip value (or None if
+/// no entry existed). Used for revert-on-failure.
+async fn flip_package_state(
+    state_manager: &StateManager,
+    package_id: &str,
+    new_state: PackageState,
+) -> Option<PackageState> {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    let prev = data.package_data.get(package_id).map(|e| e.state.clone());
+    if let Some(entry) = data.package_data.get_mut(package_id) {
+        entry.state = new_state;
+        state_manager.update_data(data).await;
+    } else {
+        warn!(
+            "flip_package_state: no entry for {} — cannot flip",
+            package_id
+        );
+    }
+    prev
+}
+
+/// Set state unconditionally (no-op if entry no longer exists).
+async fn set_package_state(
+    state_manager: &StateManager,
+    package_id: &str,
+    new_state: PackageState,
+) {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    if let Some(entry) = data.package_data.get_mut(package_id) {
+        if entry.state != new_state {
+            entry.state = new_state;
+            state_manager.update_data(data).await;
+        }
+    }
+}
+
+/// Set state and clear the uninstall_stage label. Used when an uninstall
+/// fails and we revert — the user doesn't want a stale "Removing app data"
+/// message sitting on a Running entry.
+async fn set_package_state_and_clear_uninstall_stage(
+    state_manager: &StateManager,
+    package_id: &str,
+    new_state: PackageState,
+) {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    if let Some(entry) = data.package_data.get_mut(package_id) {
+        entry.state = new_state;
+        entry.uninstall_stage = None;
+        state_manager.update_data(data).await;
+    }
+}
+
+/// Remove a package entry from state. Used for install-failure cleanup
+/// (since there's no pre-state to revert to — the entry was created
+/// speculatively when we flipped to Installing).
+async fn remove_package_entry(state_manager: &StateManager, package_id: &str) {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    if data.package_data.remove(package_id).is_some() {
+        state_manager.update_data(data).await;
+    }
+}
+
+/// Kick the container scanner to run immediately and wait for it to finish
+/// (with a 2s timeout). Used by install/update success paths so the fresh
+/// manifest — with `interfaces.main.ui` populated from the now-running
+/// container's port binding — lands BEFORE we flip state to Running.
+///
+/// Without this, the frontend sees `state = running` but the skeletal
+/// install-time manifest (interfaces = None), and hides the Launch button
+/// for up to the full 60s scan interval.
+///
+/// The scan merges via `merge_preserving_transitional`, which keeps
+/// state = Installing (we haven't flipped yet) while taking the fresh
+/// manifest. After this returns, the caller writes Running on top of the
+/// now-populated manifest.
+async fn kick_scanner_and_wait(handler: &RpcHandler) {
+    let mut rx = handler.scan_tick.subscribe();
+    let start = *rx.borrow_and_update();
+    handler.scan_kick.notify_one();
+    // 2s is well above a typical podman scan (~200ms on .228, ~500ms worst
+    // case). If it times out we proceed anyway — the next 60s scan will
+    // self-heal and the worst case is the pre-fix behavior (Launch button
+    // appears a bit late).
+    let _ = tokio::time::timeout(std::time::Duration::from_secs(2), async {
+        while *rx.borrow_and_update() == start {
+            if rx.changed().await.is_err() {
+                break;
+            }
+        }
+    })
+    .await;
+}
@@ -9,7 +9,7 @@ pub(super) const TRUSTED_REGISTRIES: &[&str] = &[
    "ghcr.io/",
    "localhost/",
    "git.tx1138.com/",
-    "23.182.128.160:3000/",
+    "146.59.87.168:3000/",
 ];

 /// Validate Docker image against trusted registry allowlist.
@@ -29,7 +29,7 @@ pub(super) fn is_valid_docker_image(image: &str) -> bool {
    };
    matches!(
        registry,
-        "docker.io" | "ghcr.io" | "localhost" | "git.tx1138.com" | "23.182.128.160:3000"
+        "docker.io" | "ghcr.io" | "localhost" | "git.tx1138.com" | "146.59.87.168:3000"
    )
 }

@@ -483,7 +483,30 @@ pub(super) async fn get_app_config(
            None,
            None,
        ),
-        "bitcoin" | "bitcoin-core" | "bitcoin-knots" => (
+        "bitcoin-core" => (
+            vec![
+                "8332:8332".to_string(),
+                "8333:8333".to_string(),
+                "28332:28332".to_string(),
+                "28333:28333".to_string(),
+            ],
+            vec!["/var/lib/archipelago/bitcoin:/home/bitcoin/.bitcoin".to_string()],
+            vec![],
+            None,
+            // Vanilla bitcoin/bitcoin image has no entrypoint wrapper and reads
+            // only what's in bitcoin.conf + argv. The shared bitcoin.conf
+            // carries rpcauth; we inject the networking flags as CLI args so
+            // RPC is reachable from the bitcoin-ui companion container.
+            Some(vec![
+                "-server=1".to_string(),
+                "-rpcbind=0.0.0.0".to_string(),
+                "-rpcallowip=0.0.0.0/0".to_string(),
+                "-rpcport=8332".to_string(),
+                "-printtoconsole=1".to_string(),
+                "-datadir=/home/bitcoin/.bitcoin".to_string(),
+            ]),
+        ),
+        "bitcoin" | "bitcoin-knots" => (
            vec![
                "8332:8332".to_string(),
                "8333:8333".to_string(),
@@ -9,14 +9,15 @@ use super::dependencies::{
 use super::progress::parse_pull_progress;
 use super::validation::validate_app_id;
 use crate::api::rpc::RpcHandler;
+use crate::data_model::InstallPhase;
 use anyhow::{Context, Result};
 use tokio::io::{AsyncBufReadExt, BufReader};
 use tracing::{debug, info, warn};

-const INSTALL_LOG: &str = "/var/log/archipelago-container-installs.log";
+const INSTALL_LOG: &str = "/var/log/archipelago/container-installs.log";

 /// Append a timestamped line to the persistent install log.
-pub(super) async fn install_log(msg: &str) {
+pub(in crate::api::rpc) async fn install_log(msg: &str) {
    use tokio::io::AsyncWriteExt;
    let ts = chrono::Utc::now().format("%Y-%m-%d %H:%M:%S UTC");
    let line = format!("[{}] {}\n", ts, msg);
@@ -86,9 +87,6 @@ impl RpcHandler {
        if package_id == "immich" {
            return self.install_immich_stack().await;
        }
-        if package_id == "penpot" || package_id == "penpot-frontend" {
-            return self.install_penpot_stack().await;
-        }
        if matches!(package_id, "btcpay-server" | "btcpayserver" | "btcpay") {
            return self.install_btcpay_stack().await;
        }
@@ -99,6 +97,9 @@ impl RpcHandler {
            return self.install_indeedhub_stack().await;
        }

+        // Phase: Preparing — validating deps and configs before any slow I/O.
+        self.set_install_phase(package_id, InstallPhase::Preparing).await;
+
        // Dependency checks
        let deps = detect_running_deps().await?;
        check_install_deps(package_id, &deps)?;
@@ -184,12 +185,21 @@ impl RpcHandler {
            package_id, docker_image
        ))
        .await;
+        // Phase: PullingImage — the longest phase. Podman doesn't emit
+        // parseable progress on a piped stderr, so the UI shows an
+        // indeterminate "Downloading image…" at this fixed percentage
+        // until pull completes.
+        self.set_install_phase(package_id, InstallPhase::PullingImage).await;
        let has_local_fallback = self.pull_or_verify_image(package_id, docker_image).await?;
        install_log(&format!(
            "INSTALL PULL OK: {} — image ready (local_fallback={})",
            package_id, has_local_fallback
        ))
        .await;
+        // Phase: CreatingContainer — image is local, now writing configs,
+        // data directories, chowning to container UID, building the run
+        // argv. Fast (sub-second to a few seconds).
+        self.set_install_phase(package_id, InstallPhase::CreatingContainer).await;

        // Normalize container name for legacy aliases
        let container_name = match package_id {
@@ -312,11 +322,6 @@ impl RpcHandler {
            }
        }

-        // TUN device for mesh networking apps
-        if matches!(package_id, "nostr-vpn" | "fips") {
-            run_args.push("--device=/dev/net/tun");
-        }
-
        // Create data directories (mkdir only — chown happens AFTER config files are written)
        for volume in &volumes {
            if let Some(host_path) = volume.split(':').next() {
@@ -358,36 +363,6 @@ impl RpcHandler {
            }
        }

-        // Pre-install: write Nostr identity key files for headless Nostr-aware apps
-        if matches!(package_id, "nostr-vpn" | "fips") {
-            let nostr_secret =
-                std::fs::read_to_string("/var/lib/archipelago/identity/nostr_secret")
-                    .map(|s| s.trim().to_string())
-                    .unwrap_or_default();
-            if !nostr_secret.is_empty() {
-                let key_dir = match package_id {
-                    "nostr-vpn" => "/var/lib/archipelago/nostr-vpn",
-                    "fips" => "/var/lib/archipelago/fips/config",
-                    _ => unreachable!(),
-                };
-                let key_path = match package_id {
-                    "nostr-vpn" => format!("{}/nostr_secret", key_dir),
-                    "fips" => format!("{}/fips.key", key_dir),
-                    _ => unreachable!(),
-                };
-                tokio::fs::create_dir_all(key_dir).await.ok();
-                tokio::fs::write(&key_path, &nostr_secret).await.ok();
-                // Restrict permissions on key file
-                #[cfg(unix)]
-                {
-                    use std::os::unix::fs::PermissionsExt;
-                    let perms = std::fs::Permissions::from_mode(0o600);
-                    std::fs::set_permissions(&key_path, perms).ok();
-                }
-                info!("Wrote Nostr identity key for {}", package_id);
-            }
-        }
-
        // NOW chown data directories to container UID (after all config files are written)
        self.create_data_dirs(package_id, &volumes).await;

@@ -474,9 +449,19 @@ impl RpcHandler {
        ))
        .await;

+        // Phase: StartingContainer — podman run accepted. Next we poll
+        // inspect until State.Status == running (up to 60s).
+        self.set_install_phase(package_id, InstallPhase::StartingContainer).await;
+
        // Post-start health verification: wait up to 60s for container to be running
        let mut container_running = false;
        for i in 0..12u32 {
+            // After the first poll, flip the UI to WaitingHealthy — the
+            // container hasn't come up yet, so the phase label changes
+            // from "Starting container" to "Waiting for healthy".
+            if i == 1 {
+                self.set_install_phase(package_id, InstallPhase::WaitingHealthy).await;
+            }
            tokio::time::sleep(std::time::Duration::from_secs(5)).await;
            let status = tokio::process::Command::new("podman")
                .args(["inspect", container_name, "--format", "{{.State.Status}}"])
@@ -536,6 +521,11 @@ impl RpcHandler {
            ));
        }

+        // Phase: PostInstall — container is up and running. Now any
+        // app-specific post-install (chain init, wallet setup, waiting
+        // for a first block). Varies by app; some are no-ops.
+        self.set_install_phase(package_id, InstallPhase::PostInstall).await;
+
        // Post-install hooks — await completion before returning success
        self.run_post_install_hooks(package_id).await;

@@ -635,31 +625,32 @@ impl RpcHandler {
        unreachable!()
    }

-    /// Single image pull attempt with progress streaming.
-    async fn do_pull_image(&self, package_id: &str, docker_image: &str) -> Result<()> {
-        debug!("Pulling image: {}", docker_image);
-        self.set_install_progress(package_id, 0, 0).await;
-
-        // Set TMPDIR to user-writable location — rootless podman's user namespace
-        // makes /var/tmp read-only, which causes `podman pull` to fail with
-        // "mkdir /var/tmp/container_images_storage...: read-only file system"
-        let user_tmp = format!(
-            "{}/.local/share/containers/tmp",
-            std::env::var("HOME").unwrap_or_else(|_| "/home/archipelago".to_string())
-        );
-        let _ = std::fs::create_dir_all(&user_tmp);
-
+    /// Pull one image URL with live progress streamed through
+    /// `update_install_progress`. Returns Ok(true) on a successful pull,
+    /// Ok(false) on transient failure (so the caller can try the next
+    /// mirror), Err only for unrecoverable setup errors.
+    async fn pull_one_url_with_progress(
+        &self,
+        url: &str,
+        tls_verify: bool,
+        package_id: &str,
+        user_tmp: &str,
+    ) -> Result<bool> {
+        let mut pull_args = vec!["pull".to_string(), url.to_string()];
+        if !tls_verify {
+            pull_args.push("--tls-verify=false".to_string());
+        }
        let mut child = tokio::process::Command::new("podman")
-            .args(["pull", docker_image])
-            .env("TMPDIR", &user_tmp)
+            .args(&pull_args)
+            .env("TMPDIR", user_tmp)
            .stdout(std::process::Stdio::piped())
            .stderr(std::process::Stdio::piped())
            .spawn()
            .context("Failed to start image pull")?;

-        // Wrap the entire pull (stderr progress + wait) in a 10-minute timeout.
-        // Large image layers (Minio, Postgres, ffmpeg) can take several minutes
-        // to pull. 60s was too short and caused premature retries on slow registries.
+        // 10-minute per-URL budget — large layers (Minio, Postgres,
+        // ffmpeg) regularly take several minutes and we'd rather wait
+        // than bounce to the next mirror mid-download.
        let pull_result = tokio::time::timeout(std::time::Duration::from_secs(600), async {
            if let Some(stderr) = child.stderr.take() {
                let reader = BufReader::new(stderr);
@@ -677,38 +668,118 @@ impl RpcHandler {
        })
        .await;

-        let primary_failed = match pull_result {
-            Ok(Ok(status)) => !status.success(),
+        match pull_result {
+            Ok(Ok(status)) => Ok(status.success()),
            Ok(Err(e)) => {
-                tracing::warn!("Image pull process error: {}", e);
-                true
+                tracing::warn!("Image pull process error on {}: {}", url, e);
+                Ok(false)
            }
            Err(_) => {
-                tracing::warn!("Image pull timed out after 60s: {}", docker_image);
+                tracing::warn!("Image pull timed out after 600s: {}", url);
                let _ = child.kill().await;
                let _ = child.wait().await; // reap zombie
-                true
+                Ok(false)
            }
-        };
-        if primary_failed {
-            // Try all configured fallback registries dynamically
-            match crate::container::registry::pull_from_registries(
-                &self.config.data_dir,
-                docker_image,
-                &user_tmp,
-            )
+        }
+    }
+
+    /// Pull a container image, trying each configured registry in
+    /// priority order and streaming progress during every attempt. The
+    /// primary is tried first; if it doesn't have the image (or 404's),
+    /// the next mirror is tried — with its own progress streaming, so
+    /// the UI doesn't freeze at 0% after a primary miss. On success the
+    /// image is tagged under `docker_image` so downstream commands
+    /// (images -q, run -d, etc.) can find it by its canonical name.
+    async fn do_pull_image(&self, package_id: &str, docker_image: &str) -> Result<()> {
+        debug!("Pulling image: {}", docker_image);
+        self.set_install_progress(package_id, 0, 0).await;
+
+        // Set TMPDIR to user-writable location — rootless podman's user namespace
+        // makes /var/tmp read-only, which causes `podman pull` to fail with
+        // "mkdir /var/tmp/container_images_storage...: read-only file system"
+        let user_tmp = format!(
+            "{}/.local/share/containers/tmp",
+            std::env::var("HOME").unwrap_or_else(|_| "/home/archipelago".to_string())
+        );
+        let _ = std::fs::create_dir_all(&user_tmp);
+
+        // Build the ordered candidate list: every enabled registry
+        // (highest priority first), each rewriting the image URL to its
+        // own origin. Deduplicate — two registries that happen to share
+        // a URL should only be tried once.
+        let config = crate::container::registry::load_registries(&self.config.data_dir)
            .await
+            .unwrap_or_default();
+        let mut tried: std::collections::HashSet<String> = std::collections::HashSet::new();
+        let mut candidates: Vec<(String, bool)> = Vec::new();
+        for reg in config.active_registries() {
+            let url = config.rewrite_image(docker_image, reg);
+            if tried.insert(url.clone()) {
+                candidates.push((url, reg.tls_verify));
+            }
+        }
+        // Always include the literal URL as a last-resort candidate —
+        // internal mirrors may not host every third-party upstream image
+        // (e.g. docker.io/bitcoin/bitcoin:28.4), and we don't want
+        // "app not mirrored" to masquerade as a generic pull failure.
+        if tried.insert(docker_image.to_string()) {
+            candidates.push((docker_image.to_string(), true));
+        }
+
+        // Walk candidates, streaming progress for each attempt.
+        let mut pulled_url: Option<String> = None;
+        let attempts = candidates.len();
+        for (i, (url, tls_verify)) in candidates.iter().enumerate() {
+            if url != docker_image {
+                debug!("Attempt {}/{}: {}", i + 1, attempts, url);
+            } else {
+                debug!("Attempt {}/{}: {} (literal)", i + 1, attempts, url);
+            }
+            // Reset progress at the top of each attempt so the UI reflects
+            // the fresh pull instead of showing stale bytes from a prior
+            // partial attempt.
+            self.set_install_progress(package_id, 0, 0).await;
+            match self
+                .pull_one_url_with_progress(url, *tls_verify, package_id, &user_tmp)
+                .await?
            {
-                Ok(_) => {
-                    tracing::info!("Pulled {} via dynamic registry fallback", docker_image);
+                true => {
+                    tracing::info!("Pulled {} from {}", docker_image, url);
+                    pulled_url = Some(url.clone());
+                    break;
                }
-                Err(e) => {
-                    return Err(anyhow::anyhow!("Image pull failed: {}", e));
+                false => {
+                    tracing::debug!(
+                        "Pull attempt {}/{} failed for {}, trying next mirror",
+                        i + 1,
+                        attempts,
+                        url
+                    );
+                    continue;
                }
            }
        }

-        // Verify image exists locally after pull
+        let Some(pulled_url) = pulled_url else {
+            return Err(anyhow::anyhow!(
+                "Image pull failed from all {} configured registries for {}",
+                attempts,
+                docker_image
+            ));
+        };
+
+        // Tag under the original docker_image reference if the successful
+        // pull came from a rewritten URL — downstream code (images -q,
+        // run -d docker_image, etc.) needs to find it by its canonical
+        // name regardless of which mirror actually served the bytes.
+        if pulled_url != docker_image {
+            let _ = tokio::process::Command::new("podman")
+                .args(["tag", &pulled_url, docker_image])
+                .output()
+                .await;
+        }
+
+        // Verify image exists locally after pull.
        let verify = tokio::process::Command::new("podman")
            .args(["images", "-q", docker_image])
            .output()
@@ -735,7 +806,7 @@ impl RpcHandler {
            "grafana" => 472,
            "lnd" => 1000,
            "mariadb" | "mysql" | "mysql-mempool" | "archy-mempool-db" => 999,
-            "postgres" | "btcpay-postgres" | "immich-postgres" | "penpot-postgres"
+            "postgres" | "btcpay-postgres" | "immich-postgres"
            | "archy-btcpay-db" | "nextcloud-db" => 70,
            "electrumx" | "electrs" => 1000,
            _ => 0, // Most containers run as root (UID 0)
@@ -795,6 +866,24 @@ impl RpcHandler {
        let bitcoin_dir = "/var/lib/archipelago/bitcoin";
        let conf_path = format!("{}/bitcoin.conf", bitcoin_dir);

+        // Idempotent: once bitcoin-knots (or a prior install) has started,
+        // the data dir is chowned into the container's user namespace
+        // (e.g. UID 100100 on the host) with 700 perms — the archipelago
+        // daemon can no longer stat or write there. Treat any non-NotFound
+        // error on the conf as "conf already provisioned by the container
+        // user" and skip. Matches the lnd.conf behavior below.
+        match tokio::fs::metadata(&conf_path).await {
+            Ok(_) => {
+                info!("bitcoin.conf already exists, skipping write");
+                return Ok(());
+            }
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
+            Err(_) => {
+                info!("bitcoin.conf path inaccessible (container-owned data dir), skipping write");
+                return Ok(());
+            }
+        }
+
        use hmac::{Hmac, Mac};
        use sha2::Sha256;
        let salt_bytes: [u8; 16] = rand::random();
@@ -805,12 +894,14 @@ impl RpcHandler {
        let hash_hex = hex::encode(mac.finalize().into_bytes());
        let rpcauth_line = format!("rpcauth={}:{}${}", rpc_user, salt_hex, hash_hex);

+        // Default to full archive — operators with 2TB+ drives shouldn't be
+        // silently pruned down to 550 MB. Users who want a pruned node can
+        // set `prune=N` in bitcoin.conf themselves after install.
        let bitcoin_conf = format!(
            "\
 # rpcauth: salted hash only — no plaintext password in config or CLI\n\
 {}\n\
 server=1\n\
-prune=550\n\
 rpcbind=0.0.0.0\n\
 rpcallowip=0.0.0.0/0\n\
 rpcport=8332\n\
@@ -1278,20 +1369,6 @@ server {
                    "electrs-ui",
                )]
            }
-            "nostr-vpn" => {
-                vec![(
-                    "archy-nostr-vpn-ui",
-                    "/opt/archipelago/docker/nostr-vpn-ui",
-                    "nostr-vpn-ui",
-                )]
-            }
-            "fips" => {
-                vec![(
-                    "archy-fips-ui",
-                    "/opt/archipelago/docker/fips-ui",
-                    "fips-ui",
-                )]
-            }
            _ => vec![],
        };

@@ -1467,6 +1544,36 @@ server {
        Ok(serde_json::json!({ "registries": config.registries, "removed": url }))
    }

+    /// Promote a registry to primary by resetting priorities — the named
+    /// URL becomes priority 0, every other enabled registry is bumped up
+    /// by 10. Order is stable (ties broken by original priority).
+    pub(in crate::api::rpc) async fn handle_registry_set_primary(
+        &self,
+        params: Option<serde_json::Value>,
+    ) -> Result<serde_json::Value> {
+        let params = params.ok_or_else(|| anyhow::anyhow!("Missing params"))?;
+        let url = params
+            .get("url")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| anyhow::anyhow!("Missing url"))?;
+
+        let mut config = crate::container::registry::load_registries(&self.config.data_dir).await?;
+        if !config.registries.iter().any(|r| r.url == url) {
+            return Err(anyhow::anyhow!("Registry '{}' not found", url));
+        }
+
+        // Reassign priorities: target = 0, everyone else = 10, 20, 30…
+        // in their existing priority order.
+        let target_url = url.to_string();
+        config.registries.sort_by_key(|r| (r.url != target_url, r.priority));
+        for (i, r) in config.registries.iter_mut().enumerate() {
+            r.priority = if r.url == target_url { 0 } else { (i as u32) * 10 };
+        }
+
+        crate::container::registry::save_registries(&self.config.data_dir, &config).await?;
+        Ok(serde_json::json!({ "registries": config.registries, "primary": url }))
+    }
+
    pub(in crate::api::rpc) async fn handle_registry_test(
        &self,
        params: Option<serde_json::Value>,
@@ -1481,10 +1588,16 @@ server {
            .and_then(|v| v.as_bool())
            .unwrap_or(true);

+        // Registries are configured as `host[:port]/namespace` (for
+        // example `146.59.87.168:3000/lfg2025`), but the Docker V2
+        // registry API lives at `/v2/` on the ROOT of the host — NOT
+        // under the namespace. Strip the namespace before appending
+        // `/v2/` so the reachability probe hits the correct URL.
+        let host = url.split('/').next().unwrap_or(url);
        let test_url = if tls_verify {
-            format!("https://{}/v2/", url)
+            format!("https://{}/v2/", host)
        } else {
-            format!("http://{}/v2/", url)
+            format!("http://{}/v2/", host)
        };

        let client = reqwest::Client::builder()
@@ -1496,8 +1609,11 @@ server {
        match client.get(&test_url).send().await {
            Ok(resp) => {
                let status = resp.status().as_u16();
-                // 200 = open registry, 401 = auth required (both mean it exists)
-                let reachable = status == 200 || status == 401;
+                // Accept any "the server responded to HTTP" code as
+                // reachable — 200 (open registry), 401 (auth required),
+                // or 405 (server rejects GET but the endpoint exists)
+                // all mean the registry daemon is alive on the host.
+                let reachable = status == 200 || status == 401 || status == 405;
                Ok(serde_json::json!({
                    "url": url,
                    "reachable": reachable,
@@ -1,3 +1,4 @@
+mod async_lifecycle;
 mod config;
 mod dependencies;
 mod install;
@@ -8,5 +9,6 @@ mod stacks;
 mod update;
 mod validation;

-// Re-export items needed by sibling modules (container.rs, security.rs)
+// Re-export items needed by sibling modules (container.rs, security.rs, transitional.rs)
 pub(super) use validation::validate_app_id;
+pub(in crate::api::rpc) use install::install_log;
@@ -2,12 +2,17 @@

 use crate::api::rpc::RpcHandler;
 use crate::data_model::{
-    Description, InstallProgress, Manifest, PackageDataEntry, PackageState, StaticFiles,
+    Description, InstallPhase, InstallProgress, Manifest, PackageDataEntry, PackageState,
+    StaticFiles,
 };

 impl RpcHandler {
    /// Set install progress for a package and broadcast the update.
    /// Creates a minimal package entry if one doesn't exist yet.
+    ///
+    /// Prefer `set_install_phase` — this byte-counter API is kept for
+    /// the rare case where the pull stream actually parses, but podman
+    /// almost never emits parseable progress on a piped stderr.
    pub(super) async fn set_install_progress(&self, package_id: &str, downloaded: u64, size: u64) {
        let (mut data, _rev) = self.state_manager.get_snapshot().await;
        let entry = data
@@ -15,7 +20,45 @@ impl RpcHandler {
            .entry(package_id.to_string())
            .or_insert_with(|| create_installing_entry(package_id));
        entry.state = PackageState::Installing;
-        entry.install_progress = Some(InstallProgress { size, downloaded });
+        let existing_phase = entry
+            .install_progress
+            .as_ref()
+            .and_then(|p| p.phase);
+        entry.install_progress = Some(InstallProgress {
+            size,
+            downloaded,
+            phase: existing_phase,
+        });
+        self.state_manager.update_data(data).await;
+    }
+
+    /// Set the install pipeline phase and broadcast. This is the
+    /// primary progress signal — the UI maps each phase to a
+    /// percentage and a user-facing label. Byte counters are retained
+    /// for the rare case podman emits parseable progress.
+    pub(super) async fn set_install_phase(&self, package_id: &str, phase: InstallPhase) {
+        let (mut data, _rev) = self.state_manager.get_snapshot().await;
+        let entry = data
+            .package_data
+            .entry(package_id.to_string())
+            .or_insert_with(|| create_installing_entry(package_id));
+        // Preparing / PullingImage / CreatingContainer / StartingContainer /
+        // WaitingHealthy / PostInstall all map to the Installing state.
+        // Updates use Updating state — the wrapper has already flipped
+        // state to Updating, so don't clobber it.
+        if entry.state != PackageState::Updating {
+            entry.state = PackageState::Installing;
+        }
+        let (size, downloaded) = entry
+            .install_progress
+            .as_ref()
+            .map(|p| (p.size, p.downloaded))
+            .unwrap_or((0, 0));
+        entry.install_progress = Some(InstallProgress {
+            size,
+            downloaded,
+            phase: Some(phase),
+        });
        self.state_manager.update_data(data).await;
    }

@@ -28,6 +71,18 @@ impl RpcHandler {
        self.state_manager.update_data(data).await;
    }

+    /// Set the uninstall stage label so the UI can show what's happening
+    /// instead of a generic spinner. Each call broadcasts a state change
+    /// — call sparingly (one per pipeline phase, not per container).
+    pub(super) async fn set_uninstall_stage(&self, package_id: &str, stage: &str) {
+        let (mut data, _rev) = self.state_manager.get_snapshot().await;
+        if let Some(entry) = data.package_data.get_mut(package_id) {
+            entry.uninstall_stage = Some(stage.to_string());
+            entry.state = crate::data_model::PackageState::Removing;
+        }
+        self.state_manager.update_data(data).await;
+    }
+
    /// Update install progress (static method for use in async closures).
    pub(super) async fn update_install_progress(
        state_manager: &crate::state::StateManager,
@@ -40,9 +95,14 @@ impl RpcHandler {
            .package_data
            .entry(package_id.to_string())
            .or_insert_with(|| create_installing_entry(package_id));
+        let existing_phase = entry
+            .install_progress
+            .as_ref()
+            .and_then(|p| p.phase);
        entry.install_progress = Some(InstallProgress {
            size: total,
            downloaded,
+            phase: existing_phase,
        });
        state_manager.update_data(data).await;
    }
@@ -57,7 +117,11 @@ fn create_installing_entry(package_id: &str) -> PackageDataEntry {
        static_files: StaticFiles {
            license: String::new(),
            instructions: String::new(),
-            icon: format!("/assets/img/app-icons/{}.png", package_id),
+            // Empty icon: hardcoding `<id>.png` is wrong for apps that use
+            // `.svg` or `.webp` assets and produces a broken-image flicker.
+            // The frontend's `icon` computed falls through to the curated
+            // map which has correct extensions for known apps.
+            icon: String::new(),
        },
        manifest: Manifest {
            id: package_id.to_string(),
@@ -81,6 +145,7 @@ fn create_installing_entry(package_id: &str) -> PackageDataEntry {
        },
        installed: None,
        install_progress: None,
+        uninstall_stage: None,
        available_update: None,
    }
 }
@@ -3,7 +3,10 @@ use super::dependencies::ordered_containers_for_start;
 use super::install::install_log;
 use super::validation::validate_app_id;
 use crate::api::rpc::RpcHandler;
+use crate::data_model::PackageState;
 use anyhow::{Context, Result};
+use std::sync::Arc;
+use tracing::warn;

 /// Per-container graceful shutdown timeout in seconds.
 /// Bitcoin Core needs 600s to flush UTXO set, LND 330s for channel state,
@@ -25,6 +28,12 @@ pub fn stop_timeout_secs(container_name: &str) -> &'static str {

 impl RpcHandler {
    /// Start a package: start all containers in dependency order.
+    ///
+    /// Returns immediately with `{ "status": "starting" }` after flipping
+    /// the package state to `Starting` in the StateManager. The actual
+    /// podman-start sequence + post-start exit verification runs in a
+    /// background task. On success the state becomes `Running`; on error
+    /// it reverts to the pre-transition state.
    pub(in crate::api::rpc) async fn handle_package_start(
        &self,
        params: Option<serde_json::Value>,
@@ -42,83 +51,52 @@ impl RpcHandler {
            return Err(anyhow::anyhow!("No containers found for {}", package_id));
        }

-        // Clear user-stopped flag — user explicitly started this app
+        // Clear user-stopped flag — user explicitly started this app.
+        // Must happen BEFORE the spawn (ordering contract with crash recovery).
        crate::crash_recovery::clear_user_stopped(&self.config.data_dir, package_id).await;
        for name in &to_start {
            crate::crash_recovery::clear_user_stopped(&self.config.data_dir, name).await;
        }

+        let package_id_owned = package_id.to_string();
+        let state_manager = Arc::clone(&self.state_manager);
+        let pre_state =
+            flip_package_state(&state_manager, &package_id_owned, PackageState::Starting).await;
+
        install_log(&format!(
            "START: {} (containers: {:?})",
-            package_id, to_start
+            package_id_owned, to_start
        ))
        .await;
-        let mut errors = Vec::new();
-        for (i, name) in to_start.iter().enumerate() {
-            // Brief delay between dependent containers to allow initialization
-            if i > 0 {
-                tokio::time::sleep(std::time::Duration::from_secs(2)).await;
-            }
-            tracing::info!("Starting container: {}", name);
-            let out = tokio::process::Command::new("podman")
-                .args(["start", name])
-                .output()
-                .await
-                .context(format!("Failed to exec podman start {}", name))?;
-            if !out.status.success() {
-                let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
-                tracing::error!("Failed to start {}: {}", name, stderr);
-                install_log(&format!("START FAIL: {} — {}", name, stderr)).await;
-                errors.push(format!("{}: {}", name, stderr));
-            }
-        }

-        if !errors.is_empty() {
-            return Err(anyhow::anyhow!("Start failed: {}", errors.join("; ")));
-        }
-
-        // Verify containers actually reached running state (podman start can
-        // succeed even if the container exits immediately after)
-        tokio::time::sleep(std::time::Duration::from_secs(3)).await;
-        for name in &to_start {
-            let status = tokio::process::Command::new("podman")
-                .args(["inspect", name, "--format", "{{.State.Status}}"])
-                .output()
-                .await;
-            if let Ok(o) = status {
-                let state = String::from_utf8_lossy(&o.stdout).trim().to_string();
-                if state == "exited" {
-                    let logs = tokio::process::Command::new("podman")
-                        .args(["logs", "--tail", "5", name])
-                        .output()
+        tokio::spawn(async move {
+            match do_package_start(&to_start).await {
+                Ok(()) => {
+                    set_package_state(&state_manager, &package_id_owned, PackageState::Running)
                        .await;
-                    let log_text = logs
-                        .map(|o| {
-                            let combined = format!(
-                                "{}{}",
-                                String::from_utf8_lossy(&o.stdout),
-                                String::from_utf8_lossy(&o.stderr)
-                            );
-                            combined.chars().take(200).collect::<String>()
-                        })
-                        .unwrap_or_default();
-                    tracing::error!("Container {} exited after start: {}", name, log_text);
-                    install_log(&format!("START EXITED: {} — {}", name, log_text)).await;
-                    errors.push(format!("{}: exited after start", name));
+                }
+                Err(e) => {
+                    tracing::error!("package.start {} failed: {:#}", package_id_owned, e);
+                    install_log(&format!("START FAIL: {} — {:#}", package_id_owned, e)).await;
+                    if let Some(prev) = pre_state {
+                        set_package_state(&state_manager, &package_id_owned, prev).await;
+                    } else {
+                        warn!(
+                            "package.start {}: no pre-state recorded; relying on next scan",
+                            package_id_owned
+                        );
+                    }
                }
            }
-        }
+        });

-        if !errors.is_empty() {
-            return Err(anyhow::anyhow!(
-                "Containers exited after start: {}",
-                errors.join("; ")
-            ));
-        }
-        Ok(serde_json::Value::Null)
+        Ok(serde_json::json!({ "status": "starting" }))
    }

    /// Stop a package: mark as user-stopped and stop all containers.
+    ///
+    /// Returns immediately with `{ "status": "stopping" }`. podman stop
+    /// (up to 600s for bitcoin-core) runs in the background.
    pub(in crate::api::rpc) async fn handle_package_stop(
        &self,
        params: Option<serde_json::Value>,
@@ -136,43 +114,48 @@ impl RpcHandler {
            return Err(anyhow::anyhow!("No containers found for {}", package_id));
        }

-        install_log(&format!(
-            "STOP: {} (containers: {:?})",
-            package_id, containers
-        ))
-        .await;
-        // Mark as user-stopped so health monitor and crash recovery don't auto-restart
+        // Mark as user-stopped BEFORE the spawn so health monitor and
+        // crash recovery don't auto-restart mid-flight. Ordering is
+        // load-bearing — see runtime.rs:145-148 original note.
        crate::crash_recovery::mark_user_stopped(&self.config.data_dir, package_id).await;
        for name in &containers {
            crate::crash_recovery::mark_user_stopped(&self.config.data_dir, name).await;
        }

-        let mut errors = Vec::new();
-        for name in &containers {
-            tracing::info!(
-                "Stopping container: {} (timeout: {}s)",
-                name,
-                stop_timeout_secs(name)
-            );
-            let out = tokio::process::Command::new("podman")
-                .args(["stop", "-t", stop_timeout_secs(name), name])
-                .output()
-                .await
-                .context(format!("Failed to exec podman stop {}", name))?;
-            if !out.status.success() {
-                let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
-                tracing::error!("Failed to stop {}: {}", name, stderr);
-                errors.push(format!("{}: {}", name, stderr));
-            }
-        }
+        let package_id_owned = package_id.to_string();
+        let state_manager = Arc::clone(&self.state_manager);
+        let pre_state =
+            flip_package_state(&state_manager, &package_id_owned, PackageState::Stopping).await;

-        if !errors.is_empty() {
-            return Err(anyhow::anyhow!("Stop failed: {}", errors.join("; ")));
-        }
-        Ok(serde_json::Value::Null)
+        install_log(&format!(
+            "STOP: {} (containers: {:?})",
+            package_id_owned, containers
+        ))
+        .await;
+
+        tokio::spawn(async move {
+            match do_package_stop(&containers).await {
+                Ok(()) => {
+                    set_package_state(&state_manager, &package_id_owned, PackageState::Stopped)
+                        .await;
+                }
+                Err(e) => {
+                    tracing::error!("package.stop {} failed: {:#}", package_id_owned, e);
+                    install_log(&format!("STOP FAIL: {} — {:#}", package_id_owned, e)).await;
+                    if let Some(prev) = pre_state {
+                        set_package_state(&state_manager, &package_id_owned, prev).await;
+                    }
+                }
+            }
+        });
+
+        Ok(serde_json::json!({ "status": "stopping" }))
    }

    /// Restart a package: restart all containers.
+    ///
+    /// Returns immediately with `{ "status": "restarting" }`. The restart
+    /// (up to 600s per container for bitcoin-core) runs in the background.
    pub(in crate::api::rpc) async fn handle_package_restart(
        &self,
        params: Option<serde_json::Value>,
@@ -190,55 +173,42 @@ impl RpcHandler {
            return Err(anyhow::anyhow!("No containers found for {}", package_id));
        }

+        // Restart does not mark user-stopped; user wants the app to keep
+        // running. Clear any lingering marker so downstream layers don't
+        // interpret the brief podman stop as user intent.
+        crate::crash_recovery::clear_user_stopped(&self.config.data_dir, package_id).await;
+        for name in &containers {
+            crate::crash_recovery::clear_user_stopped(&self.config.data_dir, name).await;
+        }
+
+        let package_id_owned = package_id.to_string();
+        let state_manager = Arc::clone(&self.state_manager);
+        let pre_state =
+            flip_package_state(&state_manager, &package_id_owned, PackageState::Restarting).await;
+
        install_log(&format!(
            "RESTART: {} (containers: {:?})",
-            package_id, containers
+            package_id_owned, containers
        ))
        .await;
-        let mut errors = Vec::new();
-        for name in &containers {
-            tracing::info!("Restarting container: {}", name);
-            let out = tokio::process::Command::new("podman")
-                .args(["restart", "-t", stop_timeout_secs(name), name])
-                .output()
-                .await
-                .context(format!("Failed to exec podman restart {}", name))?;

-            if !out.status.success() {
-                let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
-                tracing::warn!(
-                    "podman restart {} failed: {}, trying stop+start",
-                    name,
-                    stderr
-                );
-
-                // Fallback: stop then start (handles rootless podman loopback issues)
-                let _ = tokio::process::Command::new("podman")
-                    .args(["stop", "-t", stop_timeout_secs(name), name])
-                    .output()
-                    .await;
-                let start_out = tokio::process::Command::new("podman")
-                    .args(["start", name])
-                    .output()
-                    .await
-                    .context(format!("Failed to exec podman start {}", name))?;
-
-                if !start_out.status.success() {
-                    let start_err = String::from_utf8_lossy(&start_out.stderr)
-                        .trim()
-                        .to_string();
-                    tracing::error!("stop+start {} also failed: {}", name, start_err);
-                    errors.push(format!("{}: {}", name, start_err));
-                } else {
-                    tracing::info!("Restarted {} via stop+start fallback", name);
+        tokio::spawn(async move {
+            match do_package_restart(&containers).await {
+                Ok(()) => {
+                    set_package_state(&state_manager, &package_id_owned, PackageState::Running)
+                        .await;
+                }
+                Err(e) => {
+                    tracing::error!("package.restart {} failed: {:#}", package_id_owned, e);
+                    install_log(&format!("RESTART FAIL: {} — {:#}", package_id_owned, e)).await;
+                    if let Some(prev) = pre_state {
+                        set_package_state(&state_manager, &package_id_owned, prev).await;
+                    }
                }
            }
-        }
+        });

-        if !errors.is_empty() {
-            return Err(anyhow::anyhow!("Restart failed: {}", errors.join("; ")));
-        }
-        Ok(serde_json::Value::Null)
+        Ok(serde_json::json!({ "status": "restarting" }))
    }

    /// Uninstall a package: stop and remove all related containers, clean data.
@@ -261,12 +231,28 @@ impl RpcHandler {
        if containers_to_remove.is_empty() {
            tracing::warn!("Uninstall {}: no containers found", package_id);
        }
+        let total = containers_to_remove.len();

        let mut stopped = 0u32;
        let mut removed = 0u32;
        let mut errors = Vec::new();

-        for name in &containers_to_remove {
+        self.set_uninstall_stage(
+            package_id,
+            &if total > 0 {
+                format!("Stopping containers (0/{})", total)
+            } else {
+                "Cleaning up".to_string()
+            },
+        )
+        .await;
+
+        for (i, name) in containers_to_remove.iter().enumerate() {
+            self.set_uninstall_stage(
+                package_id,
+                &format!("Stopping containers ({}/{})", i + 1, total),
+            )
+            .await;
            tracing::info!("Uninstall {}: stopping container {}", package_id, name);
            let stop_out = tokio::process::Command::new("podman")
                .args(["stop", "-t", stop_timeout_secs(name), name])
@@ -326,6 +312,7 @@ impl RpcHandler {
            }
        }

+        self.set_uninstall_stage(package_id, "Cleaning up volumes").await;
        // Clean up dangling volumes associated with removed containers
        let _ = tokio::process::Command::new("podman")
            .args(["volume", "prune", "-f"])
@@ -354,6 +341,7 @@ impl RpcHandler {

        // Clean data directories unless preserve_data
        if !preserve_data {
+            self.set_uninstall_stage(package_id, "Removing app data").await;
            let data_dirs = get_data_dirs_for_app(package_id);
            for dir in &data_dirs {
                tracing::info!("Uninstall {}: removing data {}", package_id, dir);
@@ -561,3 +549,186 @@ impl RpcHandler {
        Ok(serde_json::json!({ "status": "stopped", "app_id": app_id }))
    }
 }
+
+// ---------------------------------------------------------------------------
+// Background workers for async package lifecycle RPCs.
+//
+// Extracted from the pre-async RPC handlers so the transitional state is
+// visible to the UI immediately. Each worker is pure IO over podman + the
+// crash_recovery helpers — no StateManager access here so we don't need
+// a handler reference. The caller does state flipping before/after.
+// ---------------------------------------------------------------------------
+
+/// Start containers in dependency order. Includes the post-start 3s wait +
+/// exit-check verification from the original synchronous handler (critical
+/// for catching "podman start succeeded but container immediately exited"
+/// failure modes).
+async fn do_package_start(to_start: &[String]) -> Result<()> {
+    let mut errors = Vec::new();
+    for (i, name) in to_start.iter().enumerate() {
+        if i > 0 {
+            tokio::time::sleep(std::time::Duration::from_secs(2)).await;
+        }
+        tracing::info!("Starting container: {}", name);
+        let out = tokio::process::Command::new("podman")
+            .args(["start", name])
+            .output()
+            .await
+            .context(format!("Failed to exec podman start {}", name))?;
+        if !out.status.success() {
+            let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
+            tracing::error!("Failed to start {}: {}", name, stderr);
+            install_log(&format!("START FAIL: {} — {}", name, stderr)).await;
+            errors.push(format!("{}: {}", name, stderr));
+        }
+    }
+    if !errors.is_empty() {
+        return Err(anyhow::anyhow!("Start failed: {}", errors.join("; ")));
+    }
+
+    // Post-start exit verification (podman start can succeed even if the
+    // container exits immediately after).
+    tokio::time::sleep(std::time::Duration::from_secs(3)).await;
+    for name in to_start {
+        let status = tokio::process::Command::new("podman")
+            .args(["inspect", name, "--format", "{{.State.Status}}"])
+            .output()
+            .await;
+        if let Ok(o) = status {
+            let state = String::from_utf8_lossy(&o.stdout).trim().to_string();
+            if state == "exited" {
+                let logs = tokio::process::Command::new("podman")
+                    .args(["logs", "--tail", "5", name])
+                    .output()
+                    .await;
+                let log_text = logs
+                    .map(|o| {
+                        let combined = format!(
+                            "{}{}",
+                            String::from_utf8_lossy(&o.stdout),
+                            String::from_utf8_lossy(&o.stderr)
+                        );
+                        combined.chars().take(200).collect::<String>()
+                    })
+                    .unwrap_or_default();
+                tracing::error!("Container {} exited after start: {}", name, log_text);
+                install_log(&format!("START EXITED: {} — {}", name, log_text)).await;
+                errors.push(format!("{}: exited after start", name));
+            }
+        }
+    }
+    if !errors.is_empty() {
+        return Err(anyhow::anyhow!(
+            "Containers exited after start: {}",
+            errors.join("; ")
+        ));
+    }
+    Ok(())
+}
+
+/// Stop all containers with their per-container graceful-shutdown timeout.
+async fn do_package_stop(containers: &[String]) -> Result<()> {
+    let mut errors = Vec::new();
+    for name in containers {
+        tracing::info!(
+            "Stopping container: {} (timeout: {}s)",
+            name,
+            stop_timeout_secs(name)
+        );
+        let out = tokio::process::Command::new("podman")
+            .args(["stop", "-t", stop_timeout_secs(name), name])
+            .output()
+            .await
+            .context(format!("Failed to exec podman stop {}", name))?;
+        if !out.status.success() {
+            let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
+            tracing::error!("Failed to stop {}: {}", name, stderr);
+            errors.push(format!("{}: {}", name, stderr));
+        }
+    }
+    if !errors.is_empty() {
+        return Err(anyhow::anyhow!("Stop failed: {}", errors.join("; ")));
+    }
+    Ok(())
+}
+
+/// Restart via `podman restart`, falling back to stop+start when restart
+/// fails (rootless podman loopback issues).
+async fn do_package_restart(containers: &[String]) -> Result<()> {
+    let mut errors = Vec::new();
+    for name in containers {
+        tracing::info!("Restarting container: {}", name);
+        let out = tokio::process::Command::new("podman")
+            .args(["restart", "-t", stop_timeout_secs(name), name])
+            .output()
+            .await
+            .context(format!("Failed to exec podman restart {}", name))?;
+
+        if !out.status.success() {
+            let stderr = String::from_utf8_lossy(&out.stderr).trim().to_string();
+            tracing::warn!(
+                "podman restart {} failed: {}, trying stop+start",
+                name,
+                stderr
+            );
+            // Fallback: stop then start
+            let _ = tokio::process::Command::new("podman")
+                .args(["stop", "-t", stop_timeout_secs(name), name])
+                .output()
+                .await;
+            let start_out = tokio::process::Command::new("podman")
+                .args(["start", name])
+                .output()
+                .await
+                .context(format!("Failed to exec podman start {}", name))?;
+            if !start_out.status.success() {
+                let start_err = String::from_utf8_lossy(&start_out.stderr)
+                    .trim()
+                    .to_string();
+                tracing::error!("stop+start {} also failed: {}", name, start_err);
+                errors.push(format!("{}: {}", name, start_err));
+            } else {
+                tracing::info!("Restarted {} via stop+start fallback", name);
+            }
+        }
+    }
+    if !errors.is_empty() {
+        return Err(anyhow::anyhow!("Restart failed: {}", errors.join("; ")));
+    }
+    Ok(())
+}
+
+/// Flip the primary package entry's state and return the pre-transition
+/// state for revert on error. Mirrors `transitional::flip_to_transitional`
+/// but lives here because the package path keys by `package_id` (which may
+/// differ from the container name used by orchestrator-level entries).
+async fn flip_package_state(
+    state_manager: &crate::state::StateManager,
+    package_id: &str,
+    transitional: PackageState,
+) -> Option<PackageState> {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    let prev = data.package_data.get(package_id).map(|e| e.state.clone());
+    if let Some(entry) = data.package_data.get_mut(package_id) {
+        entry.state = transitional;
+        state_manager.update_data(data).await;
+    }
+    prev
+}
+
+/// Write the package entry's final state. No-op if the entry has since
+/// been removed (uninstall race).
+async fn set_package_state(
+    state_manager: &crate::state::StateManager,
+    package_id: &str,
+    new_state: PackageState,
+) {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    if let Some(entry) = data.package_data.get_mut(package_id) {
+        if entry.state != new_state {
+            entry.state = new_state;
+            state_manager.update_data(data).await;
+        }
+    }
+}
+
@@ -273,234 +273,6 @@ impl RpcHandler {
        }))
    }

-    /// Install Penpot stack (postgres + valkey + backend + exporter + frontend).
-    pub(super) async fn install_penpot_stack(&self) -> Result<serde_json::Value> {
-        if let Some(adopted) = adopt_stack_if_exists(
-            "penpot-frontend",
-            "penpot",
-            &[
-                "penpot-postgres",
-                "penpot-valkey",
-                "penpot-backend",
-                "penpot-exporter",
-                "penpot-frontend",
-            ],
-        )
-        .await?
-        {
-            return Ok(adopted);
-        }
-
-        let images = [
-            "git.tx1138.com/lfg2025/postgres:15",
-            "git.tx1138.com/lfg2025/valkey:8.1",
-            "git.tx1138.com/lfg2025/penpot-backend:2.4",
-            "git.tx1138.com/lfg2025/penpot-exporter:2.4",
-            "git.tx1138.com/lfg2025/penpot-frontend:2.4",
-        ];
-        for img in &images {
-            pull_image_with_retry(img).await?;
-        }
-
-        let _ = tokio::process::Command::new("sudo")
-            .args(["mkdir", "-p", "/var/lib/archipelago/penpot-assets"])
-            .output()
-            .await;
-        let _ = tokio::process::Command::new("podman")
-            .args(["network", "create", "penpot-net"])
-            .output()
-            .await;
-
-        // Generate a stable secret key derived from the data directory
-        let secret = {
-            use sha2::{Digest, Sha256};
-            let mut hasher = Sha256::new();
-            hasher.update(b"penpot-secret-");
-            hasher.update(self.config.data_dir.to_string_lossy().as_bytes());
-            hex::encode(hasher.finalize())
-        };
-        let host_ip = &self.config.host_ip;
-
-        let _ = tokio::process::Command::new("podman")
-            .args([
-                "run",
-                "-d",
-                "--name",
-                "penpot-postgres",
-                "--restart",
-                "unless-stopped",
-                "--network",
-                "penpot-net",
-                "--network-alias",
-                "penpot-postgres",
-                "--cap-drop=ALL",
-                "--cap-add=CHOWN",
-                "--cap-add=DAC_OVERRIDE",
-                "--cap-add=FOWNER",
-                "--cap-add=SETGID",
-                "--cap-add=SETUID",
-                "--security-opt=no-new-privileges:true",
-                "--memory=512m",
-                "--pids-limit=4096",
-                "--health-cmd=pg_isready -U penpot || exit 1",
-                "--health-interval=30s",
-                "--health-retries=3",
-                "-v",
-                "/var/lib/archipelago/penpot-postgres:/var/lib/postgresql/data",
-                "-e",
-                "POSTGRES_DB=penpot",
-                "-e",
-                "POSTGRES_USER=penpot",
-                "-e",
-                "POSTGRES_PASSWORD=penpot",
-                "git.tx1138.com/lfg2025/postgres:15",
-            ])
-            .output()
-            .await;
-        tokio::time::sleep(std::time::Duration::from_secs(5)).await;
-
-        let _ = tokio::process::Command::new("podman")
-            .args([
-                "run",
-                "-d",
-                "--name",
-                "penpot-valkey",
-                "--restart",
-                "unless-stopped",
-                "--network",
-                "penpot-net",
-                "--network-alias",
-                "penpot-valkey",
-                "--cap-drop=ALL",
-                "--security-opt=no-new-privileges:true",
-                "--memory=192m",
-                "--pids-limit=2048",
-                "--health-cmd=valkey-cli ping || exit 1",
-                "--health-interval=30s",
-                "--health-retries=3",
-                "-e",
-                "VALKEY_EXTRA_FLAGS=--maxmemory 128mb --maxmemory-policy volatile-lfu",
-                "git.tx1138.com/lfg2025/valkey:8.1",
-            ])
-            .output()
-            .await;
-        tokio::time::sleep(std::time::Duration::from_secs(3)).await;
-
-        let _ = tokio::process::Command::new("podman")
-            .args([
-                "run",
-                "-d",
-                "--name",
-                "penpot-backend",
-                "--restart",
-                "unless-stopped",
-                "--network",
-                "penpot-net",
-                "--network-alias",
-                "penpot-backend",
-                "--cap-drop=ALL",
-                "--security-opt=no-new-privileges:true",
-                "--memory=1g",
-                "--pids-limit=4096",
-                "-v",
-                "/var/lib/archipelago/penpot-assets:/opt/data/assets",
-                "-e",
-                &format!("PENPOT_PUBLIC_URI=http://{}:9001", host_ip),
-                "-e",
-                &format!("PENPOT_SECRET_KEY={}", secret),
-                "-e",
-                "PENPOT_DATABASE_URI=postgresql://penpot-postgres/penpot",
-                "-e",
-                "PENPOT_DATABASE_USERNAME=penpot",
-                "-e",
-                "PENPOT_DATABASE_PASSWORD=penpot",
-                "-e",
-                "PENPOT_REDIS_URI=redis://penpot-valkey/0",
-                "-e",
-                "PENPOT_OBJECTS_STORAGE_BACKEND=fs",
-                "-e",
-                "PENPOT_OBJECTS_STORAGE_FS_DIRECTORY=/opt/data/assets",
-                "-e",
-                "PENPOT_FLAGS=disable-email-verification enable-smtp enable-prepl-server disable-secure-session-cookies",
-                "git.tx1138.com/lfg2025/penpot-backend:2.4",
-            ])
-            .output()
-            .await;
-        tokio::time::sleep(std::time::Duration::from_secs(5)).await;
-
-        let _ = tokio::process::Command::new("podman")
-            .args([
-                "run",
-                "-d",
-                "--name",
-                "penpot-exporter",
-                "--restart",
-                "unless-stopped",
-                "--network",
-                "penpot-net",
-                "--network-alias",
-                "penpot-exporter",
-                "--cap-drop=ALL",
-                "--security-opt=no-new-privileges:true",
-                "--memory=512m",
-                "--pids-limit=2048",
-                "-e",
-                &format!("PENPOT_SECRET_KEY={}", secret),
-                "-e",
-                "PENPOT_PUBLIC_URI=http://penpot-frontend:8080",
-                "-e",
-                "PENPOT_REDIS_URI=redis://penpot-valkey/0",
-                "git.tx1138.com/lfg2025/penpot-exporter:2.4",
-            ])
-            .output()
-            .await;
-        tokio::time::sleep(std::time::Duration::from_secs(2)).await;
-
-        let run = tokio::process::Command::new("podman")
-            .args([
-                "run",
-                "-d",
-                "--name",
-                "penpot-frontend",
-                "--restart",
-                "unless-stopped",
-                "--network",
-                "penpot-net",
-                "--network-alias",
-                "penpot-frontend",
-                "--cap-drop=ALL",
-                "--security-opt=no-new-privileges:true",
-                "--memory=512m",
-                "--pids-limit=2048",
-                "-p",
-                "9001:8080",
-                "-v",
-                "/var/lib/archipelago/penpot-assets:/opt/data/assets",
-                "-e",
-                &format!("PENPOT_PUBLIC_URI=http://{}:9001", host_ip),
-                "-e",
-                "PENPOT_FLAGS=disable-email-verification enable-smtp enable-prepl-server disable-secure-session-cookies",
-                "git.tx1138.com/lfg2025/penpot-frontend:2.4",
-            ])
-            .output()
-            .await
-            .context("Failed to start penpot-frontend")?;
-
-        if !run.status.success() {
-            let stderr = String::from_utf8_lossy(&run.stderr);
-            return Err(anyhow::anyhow!(
-                "Failed to start Penpot frontend: {}",
-                stderr
-            ));
-        }
-
-        info!("Penpot stack installed and started");
-        Ok(serde_json::json!({
-            "success": true,
-            "package_id": "penpot",
-            "message": "Penpot stack installed and started"
-        }))
-    }

    /// Install BTCPay stack (postgres + nbxplorer + btcpay-server).
    pub(super) async fn install_btcpay_stack(&self) -> Result<serde_json::Value> {
@@ -937,6 +709,31 @@ impl RpcHandler {
                .with_context(|| format!("Failed to pull IndeedHub image: {}", img))?;
        }

+        // Remove any leftover containers from a previous partial install (or
+        // from the first-boot frontend stub that used to race the installer).
+        // Without this, `podman run --name indeedhub` fails on name conflict
+        // and the whole stack install errors out — leaving a half-broken node.
+        for name in [
+            "indeedhub",
+            "indeedhub-postgres",
+            "indeedhub-redis",
+            "indeedhub-minio",
+            "indeedhub-relay",
+            "indeedhub-api",
+            "indeedhub-ffmpeg",
+            "indeedhub-build_api_1",
+            "indeedhub-build_ffmpeg-worker_1",
+        ] {
+            let _ = tokio::process::Command::new("podman")
+                .args(["rm", "-f", name])
+                .status()
+                .await;
+        }
+        let _ = tokio::process::Command::new("podman")
+            .args(["network", "rm", "-f", "indeedhub-net"])
+            .status()
+            .await;
+
        // Create indeedhub-net
        let _ = tokio::process::Command::new("podman")
            .args(["network", "create", "indeedhub-net"])
@@ -11,7 +11,7 @@ use super::runtime::stop_timeout_secs;
 use super::validation::validate_app_id;
 use crate::api::rpc::RpcHandler;
 use crate::container::image_versions;
-use crate::data_model::PackageState;
+use crate::data_model::{InstallPhase, PackageState};
 use anyhow::{Context, Result};
 use tokio::io::{AsyncBufReadExt, BufReader};
 use tracing::{error, info, warn};
@@ -34,15 +34,10 @@ impl RpcHandler {
        let pinned = image_versions::pinned_image_for_app(package_id)
            .ok_or_else(|| anyhow::anyhow!("No pinned image found for {}", package_id))?;

-        // Reject if already updating
-        {
-            let (data, _) = self.state_manager.get_snapshot().await;
-            if let Some(entry) = data.package_data.get(package_id) {
-                if entry.state == PackageState::Updating {
-                    return Err(anyhow::anyhow!("{} is already updating", package_id));
-                }
-            }
-        }
+        // Note: the `already updating` guard lives in `spawn_package_update`
+        // (the async wrapper that dispatch actually routes to). By the time
+        // this inner function runs, the wrapper has already flipped state to
+        // `Updating`, so duplicating the check here would be a false positive.

        install_log(&format!("UPDATE: {} → {}", package_id, pinned)).await;

@@ -101,6 +96,10 @@ impl RpcHandler {
        containers: &[String],
        images_to_pull: &[(String, String)],
    ) -> Result<()> {
+        // Phase: Preparing — about to stop the running container(s) so
+        // we can swap images. Fast.
+        self.set_install_phase(package_id, InstallPhase::Preparing).await;
+
        // 1. Graceful stop all containers (reverse order for dependencies)
        info!(
            "Update {}: stopping {} containers",
@@ -130,6 +129,9 @@ impl RpcHandler {
            }
        }

+        // Phase: PullingImage — about to fetch each pinned image in turn.
+        self.set_install_phase(package_id, InstallPhase::PullingImage).await;
+
        // 2. Pull new images with progress
        info!(
            "Update {}: pulling {} images",
@@ -173,6 +175,10 @@ impl RpcHandler {
            }
        }

+        // Phase: CreatingContainer — about to recreate each container
+        // via reconcile-containers.sh with the new image.
+        self.set_install_phase(package_id, InstallPhase::CreatingContainer).await;
+
        // 4. Recreate via reconcile script (single source of truth for container specs)
        info!("Update {}: recreating containers via reconcile", package_id);
        for name in containers {
@@ -205,6 +211,10 @@ impl RpcHandler {
            tokio::time::sleep(std::time::Duration::from_secs(2)).await;
        }

+        // Phase: WaitingHealthy — reconcile has started every container,
+        // now verifying each reached running state.
+        self.set_install_phase(package_id, InstallPhase::WaitingHealthy).await;
+
        // 5. Verify containers reached running state
        tokio::time::sleep(std::time::Duration::from_secs(5)).await;
        for name in containers {
@@ -296,11 +306,14 @@ impl RpcHandler {
                Ok(o) => {
                    let stderr = String::from_utf8_lossy(&o.stderr);
                    warn!("Rollback: could not restart {}: {}", name, stderr.trim());
-                    // Container was already removed — try reconcile to recreate with old image
+                    // Container was already removed (forward path ran `podman rm`).
+                    // Use --create-missing so reconcile rebuilds it from its
+                    // canonical spec instead of skipping it as optional.
                    let _ = tokio::process::Command::new("bash")
                        .args([
                            "/opt/archipelago/scripts/reconcile-containers.sh",
                            &format!("--container={}", name),
+                            "--create-missing",
                            "--force",
                        ])
                        .output()
@@ -0,0 +1,171 @@
+//! Async lifecycle helper for container Stop/Start/Restart RPCs.
+//!
+//! The `ContainerOrchestrator` trait is intentionally synchronous — blocking
+//! calls keep the reconciler, boot flow, chaos harness, and unit tests
+//! deterministic. But the RPC layer must return to the UI in <1s so the
+//! dashboard can render a transitional "Stopping…" / "Starting…" label while
+//! the underlying `podman stop` (up to 600s for bitcoin-core) runs in the
+//! background.
+//!
+//! `RpcHandler::spawn_transitional` bridges the two: it
+//!   1. flips the package state in `StateManager` to the appropriate
+//!      transitional variant (`Stopping` / `Starting` / `Restarting`),
+//!      which fans out to WebSocket clients immediately.
+//!   2. `tokio::spawn`s the actual orchestrator call.
+//!   3. on success, writes the final state (`Stopped` / `Running`).
+//!   4. on error, reverts to the pre-transition state and logs via
+//!      `install_log()` so the incident shows up in
+//!      `/var/log/archipelago/container-installs.log`.
+//!
+//! The server.rs package-scan loop must also be taught to preserve
+//! transitional states — see `server.rs:scan_and_update_packages`'s merge
+//! logic and the companion `merge_preserving_transitional` helper.
+
+use super::package::install_log;
+use super::RpcHandler;
+use crate::container::ContainerOrchestrator;
+use crate::data_model::PackageState;
+use crate::state::StateManager;
+use anyhow::Result;
+use std::sync::Arc;
+use tracing::{error, info, warn};
+
+/// The three transitional lifecycle operations that run asynchronously from
+/// the RPC handler. `Install` and `Remove` are intentionally NOT here — they
+/// already have their own progress-tracking paths (`install_progress`,
+/// `uninstall_stage`) with multi-step UI feedback.
+#[derive(Debug, Clone, Copy)]
+pub(super) enum Op {
+    Stop,
+    Start,
+    Restart,
+}
+
+impl Op {
+    /// The `PackageState` to set on the entry while the operation is in
+    /// flight. The package-scan merge loop must preserve this variant and
+    /// refuse to overwrite it with whatever podman reports (see
+    /// `merge_preserving_transitional` in server.rs).
+    fn transitional_state(self) -> PackageState {
+        match self {
+            Op::Stop => PackageState::Stopping,
+            Op::Start => PackageState::Starting,
+            Op::Restart => PackageState::Restarting,
+        }
+    }
+
+    /// The `PackageState` to set on success. On error the caller reverts to
+    /// the pre-transition state rather than using these.
+    fn final_state_on_success(self) -> PackageState {
+        match self {
+            Op::Stop => PackageState::Stopped,
+            Op::Start => PackageState::Running,
+            Op::Restart => PackageState::Running,
+        }
+    }
+
+    /// Prefix used in `install_log` entries so post-mortem readers can grep
+    /// the operation that failed.
+    fn log_prefix(self) -> &'static str {
+        match self {
+            Op::Stop => "STOP",
+            Op::Start => "START",
+            Op::Restart => "RESTART",
+        }
+    }
+
+    /// Call the orchestrator for this op. Kept in one place so the spawned
+    /// task doesn't repeat the match four times.
+    async fn dispatch(self, orch: &dyn ContainerOrchestrator, app_id: &str) -> Result<()> {
+        match self {
+            Op::Stop => orch.stop(app_id).await,
+            Op::Start => orch.start(app_id).await,
+            Op::Restart => orch.restart(app_id).await,
+        }
+    }
+}
+
+impl RpcHandler {
+    /// Flip the package state to `op.transitional_state()`, spawn a background
+    /// task that runs `op.dispatch()`, and return immediately. The spawned
+    /// task writes the final state on completion or reverts to the
+    /// pre-transition state on failure.
+    ///
+    /// If no package entry exists for `app_id` (e.g. Start on a container
+    /// that was never installed), no pre-state is recorded and the spawn
+    /// still runs — the post-success path will no-op the state write and
+    /// the next scan will pick up the newly-created entry with the correct
+    /// state. This keeps the helper usable for stacks that lazily create
+    /// their entries.
+    pub(super) async fn spawn_transitional(&self, op: Op, app_id: String) -> Result<()> {
+        let orchestrator = self
+            .orchestrator
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("Container orchestrator not available"))?
+            .clone();
+        let state_manager = Arc::clone(&self.state_manager);
+
+        // Snapshot pre-transition state (for revert on error) and flip to
+        // transitional variant. Done BEFORE the spawn so the WebSocket push
+        // beats the RPC response — the UI should see "Stopping…" the moment
+        // it gets the RPC ok, not on the next scan.
+        let pre_state = flip_to_transitional(&state_manager, &app_id, op.transitional_state()).await;
+
+        let log_prefix = op.log_prefix();
+        let app_id_log = app_id.clone();
+        install_log(&format!("{}: {}", log_prefix, app_id_log)).await;
+
+        tokio::spawn(async move {
+            match op.dispatch(orchestrator.as_ref(), &app_id).await {
+                Ok(()) => {
+                    info!("{} complete: {}", log_prefix, app_id);
+                    set_state(&state_manager, &app_id, op.final_state_on_success()).await;
+                }
+                Err(e) => {
+                    error!("{} failed for {}: {:#}", log_prefix, app_id, e);
+                    install_log(&format!("{} FAIL: {} — {:#}", log_prefix, app_id, e)).await;
+                    // Revert to pre-transition state if we had one; otherwise
+                    // leave the entry untouched so the next scan reconciles.
+                    if let Some(prev) = pre_state {
+                        set_state(&state_manager, &app_id, prev).await;
+                    } else {
+                        warn!(
+                            "{}: no pre-transition state recorded for {}; leaving entry to next scan",
+                            log_prefix, app_id
+                        );
+                    }
+                }
+            }
+        });
+
+        Ok(())
+    }
+}
+
+/// Flip the entry's state to `transitional` and return the previous state.
+/// Returns `None` if there is no entry for `app_id`.
+async fn flip_to_transitional(
+    state_manager: &StateManager,
+    app_id: &str,
+    transitional: PackageState,
+) -> Option<PackageState> {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    let prev = data.package_data.get(app_id).map(|e| e.state.clone());
+    if let Some(entry) = data.package_data.get_mut(app_id) {
+        entry.state = transitional;
+        state_manager.update_data(data).await;
+    }
+    prev
+}
+
+/// Set the entry's state to `new_state`. No-ops if the entry has since been
+/// removed (e.g. uninstall ran concurrently).
+async fn set_state(state_manager: &StateManager, app_id: &str, new_state: PackageState) {
+    let (mut data, _) = state_manager.get_snapshot().await;
+    if let Some(entry) = data.package_data.get_mut(app_id) {
+        if entry.state != new_state {
+            entry.state = new_state;
+            state_manager.update_data(data).await;
+        }
+    }
+}
@@ -185,12 +185,32 @@ impl AuthManager {
                }
            }
        }
-        // Fallback: user.json
-        Ok(self
-            .get_user()
-            .await?
-            .map(|u| u.onboarding_complete)
-            .unwrap_or(false))
+        // Fallback: user.json. A node that has a password set AND
+        // setup_complete=true has been through onboarding by
+        // definition — you can't reach the password-set step any
+        // other way. The separate `onboarding_complete` flag can drift
+        // out of sync (e.g. the completion RPC never reached disk, or
+        // the node was seeded from a backup pre-dating the flag), so
+        // auto-heal by inferring from setup_complete + password_hash.
+        // Without this, a fully-onboarded node whose `onboarding_complete`
+        // is stuck false will force its user back through the intro
+        // wizard on every cleared browser cache.
+        if let Some(u) = self.get_user().await? {
+            if u.onboarding_complete {
+                return Ok(true);
+            }
+            if u.setup_complete && !u.password_hash.is_empty() {
+                // Persist the healed state so subsequent calls skip this
+                // inference. Ignore write errors — returning true is
+                // still correct even if we can't persist.
+                let healed = OnboardingState { complete: true };
+                if let Ok(json) = serde_json::to_string_pretty(&healed) {
+                    let _ = fs::write(&onboarding_file, json).await;
+                }
+                return Ok(true);
+            }
+        }
+        Ok(false)
    }

    /// Check if 2FA is enabled for the user.
@@ -18,12 +18,12 @@ use base64::Engine;
 /// Convert a byte to an HSL triple biased toward readable foregrounds on
 /// dark backgrounds (saturation 60–85%, lightness 52–70%).
 fn hue_color(seed: u8) -> String {
-    let hue = (seed as u16) * 360 / 256;
+    let hue = (seed as u32) * 360 / 256;
    format!("hsl({}, 72%, 60%)", hue)
 }

 fn accent_color(seed: u8) -> String {
-    let hue = (seed as u16) * 360 / 256;
+    let hue = (seed as u32) * 360 / 256;
    format!("hsl({}, 80%, 68%)", hue)
 }

@@ -0,0 +1,264 @@
+//! Bootstrap host-side artifacts on every archipelago startup.
+//!
+//! The update pipeline swaps the archipelago binary but does not touch
+//! scripts, systemd units, or nginx configuration — those are installed
+//! once by the ISO builder. Without this module, changes to
+//! `container-doctor.sh`, the doctor service/timer, or the nginx config
+//! never reach boxes installed before the change.
+//!
+//! Two things are synced on startup:
+//!   1. Doctor artifacts (container-doctor.sh + service + timer).
+//!   2. An nginx `location /api/app-catalog` proxy block — required for
+//!      the App Store catalog proxy to actually reach the backend.
+//!
+//! Idempotent: no-ops on boxes that are already in sync. All work is
+//! best-effort — failures are logged but never abort the backend.
+
+use anyhow::{Context, Result};
+use std::path::Path;
+use tokio::fs;
+use tracing::{debug, info, warn};
+
+use crate::update::host_sudo;
+
+const DOCTOR_SH: &str = include_str!("../../../scripts/container-doctor.sh");
+const DOCTOR_SERVICE: &str =
+    include_str!("../../../image-recipe/configs/archipelago-doctor.service");
+const DOCTOR_TIMER: &str =
+    include_str!("../../../image-recipe/configs/archipelago-doctor.timer");
+
+const DOCTOR_SH_PATH: &str = "/home/archipelago/archy/scripts/container-doctor.sh";
+const DOCTOR_SERVICE_PATH: &str = "/etc/systemd/system/archipelago-doctor.service";
+const DOCTOR_TIMER_PATH: &str = "/etc/systemd/system/archipelago-doctor.timer";
+
+const NGINX_CONF_PATH: &str = "/etc/nginx/sites-available/archipelago";
+
+/// Inserted into every server block of the nginx config that lacks the
+/// `/api/app-catalog` proxy. Kept in sync with the canonical block in
+/// image-recipe/configs/nginx-archipelago.conf.
+const NGINX_APP_CATALOG_BLOCK: &str = "\n    # App Store catalog proxy — backend fetches from configured registries\n    # so the browser doesn't hit CORS/CSP. Without this block nginx falls\n    # through to the SPA index.html and the frontend gets HTML back instead\n    # of JSON.\n    location /api/app-catalog {\n        proxy_pass http://127.0.0.1:5678;\n        proxy_http_version 1.1;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header Cookie $http_cookie;\n        proxy_connect_timeout 15s;\n        proxy_read_timeout 30s;\n        proxy_send_timeout 15s;\n        error_page 502 503 = @backend_unavailable;\n        error_page 504 = @backend_timeout;\n    }\n\n";
+
+/// Entry point called from main startup. Never returns an error to the caller —
+/// failing to bootstrap host artifacts must not prevent the backend from serving.
+pub async fn ensure_doctor_installed() {
+    match run().await {
+        Ok(changed) if changed => info!("Doctor artifacts synchronized with binary"),
+        Ok(_) => debug!("Doctor artifacts already in sync"),
+        Err(e) => warn!("Doctor bootstrap failed (non-fatal): {:#}", e),
+    }
+    match run_nginx().await {
+        Ok(true) => info!("Patched nginx config to proxy /api/app-catalog"),
+        Ok(false) => debug!("Nginx already has /api/app-catalog block"),
+        Err(e) => warn!("Nginx bootstrap failed (non-fatal): {:#}", e),
+    }
+}
+
+async fn run() -> Result<bool> {
+    // Dev-box guard: on contributors' laptops `/home/archipelago/archy` is
+    // typically a symlink into the git checkout, and writing through it
+    // would clobber the working tree with whatever the binary happens to
+    // have been compiled from. Production ISO installs materialize a real
+    // directory.
+    let home_archy = Path::new("/home/archipelago/archy");
+    if fs::symlink_metadata(home_archy)
+        .await
+        .map(|m| m.file_type().is_symlink())
+        .unwrap_or(false)
+    {
+        debug!("/home/archipelago/archy is a symlink — skipping doctor bootstrap (dev box)");
+        return Ok(false);
+    }
+
+    // Skip entirely on machines without the canonical scripts directory —
+    // writing orphan files there just causes confusion.
+    let scripts_dir = Path::new(DOCTOR_SH_PATH)
+        .parent()
+        .context("doctor script path has no parent")?;
+    if !scripts_dir.exists() {
+        debug!(
+            "Scripts dir {} missing — skipping doctor bootstrap",
+            scripts_dir.display()
+        );
+        return Ok(false);
+    }
+
+    let mut changed = false;
+
+    // 1. Script — lives in archipelago's home dir, user-writable.
+    if needs_write(DOCTOR_SH_PATH, DOCTOR_SH).await {
+        fs::write(DOCTOR_SH_PATH, DOCTOR_SH)
+            .await
+            .with_context(|| format!("write {}", DOCTOR_SH_PATH))?;
+        let _ = tokio::process::Command::new("chmod")
+            .args(["+x", DOCTOR_SH_PATH])
+            .status()
+            .await;
+        info!("Updated {}", DOCTOR_SH_PATH);
+        changed = true;
+    }
+
+    // 2. Systemd unit files — /etc is restricted; route through host_sudo.
+    let service_changed = write_root_if_needed(DOCTOR_SERVICE_PATH, DOCTOR_SERVICE).await?;
+    let timer_changed = write_root_if_needed(DOCTOR_TIMER_PATH, DOCTOR_TIMER).await?;
+    changed = changed || service_changed || timer_changed;
+
+    // 3. Reload + enable. Only when we actually touched units, or when the
+    // timer isn't enabled yet (catches fresh upgrades of boxes that predate
+    // the doctor entirely).
+    let timer_enabled = is_timer_enabled().await;
+    if service_changed || timer_changed || !timer_enabled {
+        if let Err(e) = host_sudo(&["systemctl", "daemon-reload"]).await {
+            warn!("daemon-reload failed: {:#}", e);
+        }
+        if let Err(e) = host_sudo(&["systemctl", "enable", "--now", "archipelago-doctor.timer"])
+            .await
+        {
+            warn!("enable archipelago-doctor.timer failed: {:#}", e);
+        } else if !timer_enabled {
+            info!("Enabled archipelago-doctor.timer");
+        }
+    }
+
+    Ok(changed)
+}
+
+async fn needs_write(path: &str, expected: &str) -> bool {
+    match fs::read_to_string(path).await {
+        Ok(current) => current != expected,
+        Err(_) => true,
+    }
+}
+
+/// Write content to a root-owned path via `sudo mv` of a user-owned tmp file.
+/// Returns true if a write happened.
+async fn write_root_if_needed(path: &str, content: &str) -> Result<bool> {
+    if !needs_write(path, content).await {
+        return Ok(false);
+    }
+    let tmp = format!(
+        "/tmp/archipelago-bootstrap-{}-{}.tmp",
+        std::process::id(),
+        Path::new(path)
+            .file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("unit")
+    );
+    fs::write(&tmp, content)
+        .await
+        .with_context(|| format!("write tmp {}", tmp))?;
+    let status = host_sudo(&["mv", &tmp, path])
+        .await
+        .with_context(|| format!("sudo mv {} -> {}", tmp, path))?;
+    if !status.success() {
+        let _ = fs::remove_file(&tmp).await;
+        anyhow::bail!("sudo mv to {} exited with {}", path, status);
+    }
+    info!("Updated {}", path);
+    Ok(true)
+}
+
+async fn is_timer_enabled() -> bool {
+    tokio::process::Command::new("systemctl")
+        .args(["is-enabled", "--quiet", "archipelago-doctor.timer"])
+        .status()
+        .await
+        .map(|s| s.success())
+        .unwrap_or(false)
+}
+
+/// Patch the nginx site config to add a `/api/app-catalog` proxy block if
+/// it's missing. The original ISO shipped individual per-endpoint `location`
+/// blocks and no catch-all `/api/`, so `/api/app-catalog` silently fell
+/// through to the SPA `index.html` and the frontend got HTML instead of
+/// JSON. We anchor the insert to the DWN comment that already sits right
+/// after the `/api/blob` block, so the new block lands in both the HTTP
+/// and HTTPS server blocks.
+///
+/// Validates via `nginx -t` before reloading. On failure the patch is
+/// rolled back from a backup written just before the write.
+async fn run_nginx() -> Result<bool> {
+    // Skip on dev symlinks — we don't want to touch `/etc/nginx` on laptops.
+    let home_archy = Path::new("/home/archipelago/archy");
+    if fs::symlink_metadata(home_archy)
+        .await
+        .map(|m| m.file_type().is_symlink())
+        .unwrap_or(false)
+    {
+        return Ok(false);
+    }
+
+    if !Path::new(NGINX_CONF_PATH).exists() {
+        debug!(
+            "{} missing — skipping nginx bootstrap",
+            NGINX_CONF_PATH
+        );
+        return Ok(false);
+    }
+
+    let content = fs::read_to_string(NGINX_CONF_PATH)
+        .await
+        .with_context(|| format!("read {}", NGINX_CONF_PATH))?;
+    if content.contains("location /api/app-catalog") {
+        return Ok(false);
+    }
+
+    // The DWN comment sits at the same indent right after the `/api/blob`
+    // block in both server blocks — a stable anchor that existed on every
+    // ISO shipped to date. If it's absent (config got heavily customized),
+    // we bail rather than guess where to splice.
+    let anchor = "    # DWN endpoints — peer access over Tor (no auth)";
+    if !content.contains(anchor) {
+        warn!("nginx conf missing DWN anchor — skipping /api/app-catalog patch");
+        return Ok(false);
+    }
+
+    let replacement = format!("{}{}", NGINX_APP_CATALOG_BLOCK, anchor);
+    let patched = content.replace(anchor, &replacement);
+
+    // Write patched config via a user-owned tmp + sudo mv, after stashing
+    // a backup so we can revert if `nginx -t` hates what we produced.
+    let pid = std::process::id();
+    let tmp = format!("/tmp/archipelago-nginx-{}.conf", pid);
+    fs::write(&tmp, &patched)
+        .await
+        .with_context(|| format!("write {}", tmp))?;
+
+    let backup = format!("/tmp/archipelago-nginx-backup-{}.conf", pid);
+    if let Err(e) = host_sudo(&["cp", NGINX_CONF_PATH, &backup]).await {
+        let _ = fs::remove_file(&tmp).await;
+        return Err(e.context("backup nginx conf"));
+    }
+
+    let mv = host_sudo(&["mv", &tmp, NGINX_CONF_PATH]).await;
+    match mv {
+        Ok(s) if s.success() => {}
+        Ok(s) => {
+            let _ = fs::remove_file(&tmp).await;
+            anyhow::bail!("sudo mv nginx conf exited with {}", s);
+        }
+        Err(e) => {
+            let _ = fs::remove_file(&tmp).await;
+            return Err(e.context("mv tmp -> nginx conf"));
+        }
+    }
+
+    // Validate.
+    let test = host_sudo(&["nginx", "-t"]).await;
+    let valid = matches!(&test, Ok(s) if s.success());
+    if !valid {
+        warn!("nginx -t failed after patch — reverting");
+        let _ = host_sudo(&["mv", &backup, NGINX_CONF_PATH]).await;
+        if let Err(e) = test {
+            return Err(e.context("nginx -t"));
+        }
+        anyhow::bail!("nginx config invalid after patch — reverted");
+    }
+
+    // Reload nginx so the new block takes effect immediately. Reload (not
+    // restart) keeps in-flight connections alive.
+    if let Err(e) = host_sudo(&["systemctl", "reload", "nginx"]).await {
+        warn!("nginx reload failed (non-fatal): {:#}", e);
+    }
+    let _ = host_sudo(&["rm", "-f", &backup]).await;
+    Ok(true)
+}
@@ -0,0 +1,274 @@
+//! bitcoin-ui nginx.conf renderer.
+//!
+//! Step 7 of the rust-orchestrator migration. Replaces the old
+//! `sed -i __BITCOIN_RPC_AUTH__` approach from `first-boot-containers.sh`
+//! (which destructively overwrote its own template, broke on rotation,
+//! and had no story for dual Knots/Core UIs) with a binary-embedded
+//! template rendered at install/reconcile time and atomic-written to
+//! disk.
+//!
+//! The manifest bind-mounts the rendered file read-only into the
+//! container at `/etc/nginx/conf.d/default.conf`. On every reconcile
+//! pass we re-render and compare — if the rendered bytes would differ
+//! from what's on disk (password rotated, template changed via OTA),
+//! we rewrite atomically and the reconciler restarts the container.
+//!
+//! Source of truth:
+//!   * RPC user: hardcoded `archipelago` (matches the image's `bitcoin.conf`).
+//!   * RPC password: `/var/lib/archipelago/secrets/bitcoin-rpc-password`,
+//!     plaintext, written by the seed-derived credential setup.
+//!
+//! Both Knots and Core back-ends expose RPC on 127.0.0.1:8332 with the
+//! same auth shape, so one template serves both.
+
+use anyhow::{Context, Result};
+use base64::Engine;
+use sha2::{Digest, Sha256};
+use std::path::{Path, PathBuf};
+use tokio::fs;
+
+/// The nginx.conf template. Embedded at compile time so it can never
+/// drift from the code that renders it, and ships atomically with OTA.
+///
+/// `{{BITCOIN_RPC_AUTH}}` is the only placeholder — replaced with a
+/// `base64(user:password)` blob at render time.
+pub(crate) const TEMPLATE: &str = include_str!("bitcoin_ui_nginx.conf.template");
+
+/// The single placeholder in `TEMPLATE`.
+const PLACEHOLDER: &str = "{{BITCOIN_RPC_AUTH}}";
+
+/// Hardcoded RPC user. Matches the user written into `bitcoin.conf` by
+/// the bitcoin-core/bitcoin-knots bootstrap, and the legacy
+/// `BITCOIN_RPC_USER="archipelago"` from `first-boot-containers.sh`.
+const RPC_USER: &str = "archipelago";
+
+/// Default path to the plaintext RPC password secret.
+///
+/// Written by the seed-derived credential flow; same file the bash
+/// scripts read today at `first-boot-containers.sh:277` and `:1225`.
+pub const DEFAULT_SECRET_PATH: &str = "/var/lib/archipelago/secrets/bitcoin-rpc-password";
+
+/// Default output path for the rendered nginx.conf.
+///
+/// The manifest bind-mounts this file read-only into the bitcoin-ui
+/// container at `/etc/nginx/conf.d/default.conf`.
+pub const DEFAULT_RENDERED_PATH: &str = "/var/lib/archipelago/bitcoin-ui/nginx.conf";
+
+/// Parameters for rendering. Injectable so tests can hit a tmpdir
+/// instead of `/var/lib/archipelago`.
+#[derive(Debug, Clone)]
+pub struct RenderPaths {
+    /// Path to read the plaintext RPC password from.
+    pub secret_path: PathBuf,
+    /// Path to write the rendered nginx.conf to.
+    pub rendered_path: PathBuf,
+}
+
+impl Default for RenderPaths {
+    fn default() -> Self {
+        Self {
+            secret_path: PathBuf::from(DEFAULT_SECRET_PATH),
+            rendered_path: PathBuf::from(DEFAULT_RENDERED_PATH),
+        }
+    }
+}
+
+/// Outcome of a render pass. `Written` if the rendered bytes differed
+/// from the current on-disk contents and we rewrote; `Unchanged` if
+/// they matched and we left the file alone.
+///
+/// The caller (reconciler / install path) decides whether to restart
+/// the bitcoin-ui container based on this.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RenderOutcome {
+    Written,
+    Unchanged,
+}
+
+/// Render the bitcoin-ui nginx.conf and atomic-write it to disk if it
+/// differs from what's already there.
+///
+/// Idempotent: safe to call on every reconcile pass. Does a byte
+/// comparison before writing so an unchanged password + template is a
+/// no-op (no inode churn, no container restart cascade).
+///
+/// Errors if the secret file is missing or empty. Upstream callers
+/// treat that as "bitcoin-ui isn't installable yet" rather than fatal
+/// — the RPC password comes into being during bitcoin-core's own
+/// bootstrap, which may not have happened yet on a fresh node.
+pub async fn render(paths: &RenderPaths) -> Result<RenderOutcome> {
+    let password = read_password(&paths.secret_path).await?;
+    let auth_b64 = encode_basic_auth(RPC_USER, &password);
+    let rendered = TEMPLATE.replace(PLACEHOLDER, &auth_b64);
+
+    // Compare against existing. read-to-string fails on ENOENT (first
+    // install) — treat as "different".
+    let existing = fs::read_to_string(&paths.rendered_path).await.ok();
+    if existing.as_deref() == Some(rendered.as_str()) {
+        return Ok(RenderOutcome::Unchanged);
+    }
+
+    // Atomic write: write to sibling tmp + rename. Keeps the bind-
+    // mounted file pointing at a fully-formed config at all times.
+    let parent = paths
+        .rendered_path
+        .parent()
+        .ok_or_else(|| anyhow::anyhow!("rendered_path has no parent directory"))?;
+    fs::create_dir_all(parent)
+        .await
+        .with_context(|| format!("creating {}", parent.display()))?;
+
+    let tmp = paths.rendered_path.with_extension("tmp");
+    fs::write(&tmp, &rendered)
+        .await
+        .with_context(|| format!("writing tmp {}", tmp.display()))?;
+    fs::rename(&tmp, &paths.rendered_path)
+        .await
+        .with_context(|| format!("renaming {} -> {}", tmp.display(), paths.rendered_path.display()))?;
+
+    tracing::info!(
+        path = %paths.rendered_path.display(),
+        auth_hash = %short_hash(&auth_b64),
+        "bitcoin-ui nginx.conf rendered"
+    );
+
+    Ok(RenderOutcome::Written)
+}
+
+/// Read the plaintext RPC password from disk. Trims trailing newlines
+/// (common from `echo "$PASS" > file`) but rejects an empty result.
+async fn read_password(path: &Path) -> Result<String> {
+    let raw = fs::read_to_string(path)
+        .await
+        .with_context(|| format!("reading bitcoin RPC password from {}", path.display()))?;
+    let trimmed = raw.trim().to_string();
+    if trimmed.is_empty() {
+        anyhow::bail!(
+            "bitcoin RPC password file {} is empty — bitcoin-core bootstrap hasn't written it yet",
+            path.display()
+        );
+    }
+    Ok(trimmed)
+}
+
+/// `base64("user:password")` — the value nginx puts after `Basic ` in
+/// the upstream `Authorization` header.
+fn encode_basic_auth(user: &str, password: &str) -> String {
+    let raw = format!("{user}:{password}");
+    base64::engine::general_purpose::STANDARD.encode(raw.as_bytes())
+}
+
+/// Short hash of the auth value for logging — we never want the
+/// plaintext or full base64 in logs (it's a credential), but a stable
+/// fingerprint helps correlate rotations.
+fn short_hash(s: &str) -> String {
+    let mut hasher = Sha256::new();
+    hasher.update(s.as_bytes());
+    let digest = hasher.finalize();
+    hex::encode(&digest[..4])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    fn paths_in(dir: &Path, password: &str) -> RenderPaths {
+        let secret = dir.join("bitcoin-rpc-password");
+        std::fs::write(&secret, password).unwrap();
+        RenderPaths {
+            secret_path: secret,
+            rendered_path: dir.join("nginx.conf"),
+        }
+    }
+
+    #[tokio::test]
+    async fn render_writes_file_with_substitution() {
+        let tmp = TempDir::new().unwrap();
+        let paths = paths_in(tmp.path(), "hunter2");
+        let outcome = render(&paths).await.unwrap();
+        assert_eq!(outcome, RenderOutcome::Written);
+        let contents = std::fs::read_to_string(&paths.rendered_path).unwrap();
+        // archipelago:hunter2 -> "YXJjaGlwZWxhZ286aHVudGVyMg=="
+        assert!(
+            contents.contains("YXJjaGlwZWxhZ286aHVudGVyMg=="),
+            "base64 auth not found in rendered config:\n{contents}"
+        );
+        assert!(!contents.contains(PLACEHOLDER), "placeholder left in output");
+    }
+
+    #[tokio::test]
+    async fn render_is_idempotent_when_password_unchanged() {
+        let tmp = TempDir::new().unwrap();
+        let paths = paths_in(tmp.path(), "hunter2");
+        let first = render(&paths).await.unwrap();
+        assert_eq!(first, RenderOutcome::Written);
+        let second = render(&paths).await.unwrap();
+        assert_eq!(second, RenderOutcome::Unchanged);
+    }
+
+    #[tokio::test]
+    async fn render_rewrites_on_password_rotation() {
+        let tmp = TempDir::new().unwrap();
+        let paths = paths_in(tmp.path(), "old-pass");
+        render(&paths).await.unwrap();
+        // Rotate.
+        std::fs::write(&paths.secret_path, "new-pass").unwrap();
+        let outcome = render(&paths).await.unwrap();
+        assert_eq!(outcome, RenderOutcome::Written);
+        let contents = std::fs::read_to_string(&paths.rendered_path).unwrap();
+        // archipelago:new-pass -> "YXJjaGlwZWxhZ286bmV3LXBhc3M="
+        assert!(contents.contains("YXJjaGlwZWxhZ286bmV3LXBhc3M="));
+    }
+
+    #[tokio::test]
+    async fn render_trims_trailing_newline_from_secret() {
+        // Matches `echo "$PASS" > file` behaviour.
+        let tmp = TempDir::new().unwrap();
+        let paths = paths_in(tmp.path(), "hunter2\n");
+        render(&paths).await.unwrap();
+        let contents = std::fs::read_to_string(&paths.rendered_path).unwrap();
+        assert!(
+            contents.contains("YXJjaGlwZWxhZ286aHVudGVyMg=="),
+            "trailing newline should be stripped before encoding"
+        );
+    }
+
+    #[tokio::test]
+    async fn render_errors_on_empty_password() {
+        let tmp = TempDir::new().unwrap();
+        let paths = paths_in(tmp.path(), "");
+        let err = render(&paths).await.unwrap_err();
+        let msg = format!("{err}");
+        assert!(msg.contains("empty"), "unexpected error: {msg}");
+    }
+
+    #[tokio::test]
+    async fn render_errors_when_secret_missing() {
+        let tmp = TempDir::new().unwrap();
+        let paths = RenderPaths {
+            secret_path: tmp.path().join("does-not-exist"),
+            rendered_path: tmp.path().join("nginx.conf"),
+        };
+        let err = render(&paths).await.unwrap_err();
+        let msg = format!("{err}");
+        assert!(msg.contains("reading bitcoin RPC password"), "unexpected error: {msg}");
+    }
+
+    #[test]
+    fn template_contains_exactly_one_placeholder() {
+        // Safety net: if someone adds a second placeholder to the
+        // template without updating the renderer, we want a test to
+        // fail loudly rather than ship a half-substituted config.
+        let count = TEMPLATE.matches(PLACEHOLDER).count();
+        assert_eq!(count, 1, "template must contain exactly one {PLACEHOLDER}");
+    }
+
+    #[test]
+    fn template_proxies_bitcoin_rpc_on_8332() {
+        // Lock in the core shape so a bad template edit doesn't ship.
+        assert!(TEMPLATE.contains("proxy_pass http://127.0.0.1:8332/"));
+        assert!(TEMPLATE.contains("location /bitcoin-rpc/"));
+        assert!(TEMPLATE.contains("listen 8334"));
+    }
+}
@@ -9,7 +9,7 @@ server {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header Authorization "Basic __BITCOIN_RPC_AUTH__";
+        proxy_set_header Authorization "Basic {{BITCOIN_RPC_AUTH}}";
        add_header Access-Control-Allow-Origin *;
        add_header Access-Control-Allow-Methods "POST, GET, OPTIONS";
        add_header Access-Control-Allow-Headers "Content-Type, Authorization";
@@ -0,0 +1,351 @@
+//! BootReconciler — the long-running task that keeps the prod orchestrator's
+//! desired-state view in lockstep with what podman actually has.
+//!
+//! Step 5 of the rust-orchestrator migration. Spawned once from `main.rs`
+//! (Step 6) after the initial `adopt_existing()` pass. Every `interval` it
+//! calls `ProdContainerOrchestrator::reconcile_all()`, which ensures every
+//! loaded manifest has a running container, installing fresh ones as needed.
+//!
+//! Per answered design Q3, `interval` defaults to 30 seconds.
+//!
+//! Shutdown is signalled via `Arc<Notify>`. The reconciler finishes its
+//! current `reconcile_all` call before exiting — we don't interrupt an
+//! in-flight pull or build.
+//!
+//! See `docs/rust-orchestrator-migration.md` §269-352.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use tokio::sync::Notify;
+use tokio::time::{self, Instant};
+
+use crate::container::prod_orchestrator::{ProdContainerOrchestrator, ReconcileReport};
+
+/// Default reconciler cadence (answered design Q3).
+pub const DEFAULT_INTERVAL: Duration = Duration::from_secs(30);
+
+pub struct BootReconciler {
+    orchestrator: Arc<ProdContainerOrchestrator>,
+    interval: Duration,
+    shutdown: Arc<Notify>,
+}
+
+impl BootReconciler {
+    pub fn new(
+        orchestrator: Arc<ProdContainerOrchestrator>,
+        interval: Duration,
+        shutdown: Arc<Notify>,
+    ) -> Self {
+        Self {
+            orchestrator,
+            interval,
+            shutdown,
+        }
+    }
+
+    /// Run the reconcile loop until `shutdown` is notified.
+    ///
+    /// Does one reconcile immediately, then sleeps `interval` between
+    /// subsequent passes. A `shutdown.notify_one()` call unblocks the sleep
+    /// and the task returns after the *next* pass completes.
+    ///
+    /// Never panics: per-app failures are absorbed into `ReconcileReport` by
+    /// the orchestrator, and `reconcile_all` itself returns infallibly.
+    pub async fn run_forever(self) {
+        // Initial pass: no delay.
+        let report = self.orchestrator.reconcile_all().await;
+        Self::log_report(&report);
+
+        loop {
+            let deadline = Instant::now() + self.interval;
+            tokio::select! {
+                _ = time::sleep_until(deadline) => {
+                    let report = self.orchestrator.reconcile_all().await;
+                    Self::log_report(&report);
+                }
+                _ = self.shutdown.notified() => {
+                    tracing::info!("boot reconciler: shutdown requested, exiting loop");
+                    break;
+                }
+            }
+        }
+    }
+
+    fn log_report(report: &ReconcileReport) {
+        for (app_id, action) in &report.actions {
+            tracing::debug!(app_id = %app_id, action = ?action, "reconcile action");
+        }
+        for (app_id, err) in &report.failures {
+            tracing::warn!(app_id = %app_id, error = %err, "reconcile failure");
+        }
+        if report.failures.is_empty() {
+            tracing::debug!(
+                count = report.actions.len(),
+                "reconcile pass complete"
+            );
+        } else {
+            tracing::warn!(
+                ok = report.actions.len(),
+                failed = report.failures.len(),
+                "reconcile pass completed with failures"
+            );
+        }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::container::prod_orchestrator::ProdContainerOrchestrator;
+    use anyhow::Result;
+    use archipelago_container::{
+        AppManifest, BuildConfig, ContainerRuntime as ContainerRuntimeTrait, ContainerState,
+        ContainerStatus,
+    };
+    use async_trait::async_trait;
+    use std::collections::HashMap;
+    use std::path::PathBuf;
+    use std::sync::Mutex as StdMutex;
+
+    /// Instrumented runtime that counts reconcile-loop side effects so tests
+    /// can tell exactly how many passes have fired. All containers are
+    /// reported as already Running so `reconcile_all` will NoOp — we are only
+    /// measuring loop cadence, not install behavior.
+    #[derive(Default)]
+    struct CountingRuntime {
+        /// Number of times get_container_status has been called. Each
+        /// reconcile_all pass hits this once per manifest, so with one
+        /// manifest this equals the number of reconcile passes.
+        status_calls: StdMutex<u32>,
+        running: StdMutex<HashMap<String, ContainerState>>,
+    }
+
+    impl CountingRuntime {
+        fn new_with(names: &[&str]) -> Self {
+            let me = Self::default();
+            let mut m = me.running.lock().unwrap();
+            for n in names {
+                m.insert((*n).to_string(), ContainerState::Running);
+            }
+            drop(m);
+            me
+        }
+        fn status_call_count(&self) -> u32 {
+            *self.status_calls.lock().unwrap()
+        }
+    }
+
+    #[async_trait]
+    impl ContainerRuntimeTrait for CountingRuntime {
+        async fn pull_image(&self, _: &str, _: Option<&str>) -> Result<()> {
+            Ok(())
+        }
+        async fn create_container(
+            &self,
+            _: &AppManifest,
+            name: &str,
+            _: u16,
+        ) -> Result<String> {
+            Ok(name.to_string())
+        }
+        async fn start_container(&self, _: &str) -> Result<()> {
+            Ok(())
+        }
+        async fn stop_container(&self, _: &str) -> Result<()> {
+            Ok(())
+        }
+        async fn remove_container(&self, _: &str) -> Result<()> {
+            Ok(())
+        }
+        async fn get_container_status(&self, name: &str) -> Result<ContainerStatus> {
+            *self.status_calls.lock().unwrap() += 1;
+            let state = self
+                .running
+                .lock()
+                .unwrap()
+                .get(name)
+                .cloned()
+                .ok_or_else(|| anyhow::anyhow!("not found: {name}"))?;
+            Ok(ContainerStatus {
+                id: format!("id-{name}"),
+                name: name.to_string(),
+                state,
+                health: None,
+                exit_code: None,
+                started_at: None,
+                image: "test".into(),
+                created: "now".into(),
+                ports: vec![],
+                lan_address: None,
+            })
+        }
+        async fn get_container_logs(&self, _: &str, _: u32) -> Result<Vec<String>> {
+            Ok(vec![])
+        }
+        async fn list_containers(&self) -> Result<Vec<ContainerStatus>> {
+            Ok(vec![])
+        }
+        async fn image_exists(&self, _: &str) -> Result<bool> {
+            Ok(true)
+        }
+        async fn build_image(&self, _: &BuildConfig) -> Result<()> {
+            Ok(())
+        }
+    }
+
+    fn pull_manifest(id: &str, image: &str) -> AppManifest {
+        let yaml = format!(
+            "app:\n  id: {id}\n  name: {id}\n  version: 1.0.0\n  container:\n    image: {image}\n"
+        );
+        AppManifest::parse(&yaml).unwrap()
+    }
+
+    async fn orch_with_one_running_manifest(
+        rt: Arc<CountingRuntime>,
+    ) -> Arc<ProdContainerOrchestrator> {
+        let orch = Arc::new(ProdContainerOrchestrator::with_runtime(
+            rt,
+            PathBuf::from("/nonexistent-for-tests"),
+        ));
+        orch.insert_manifest_for_test(
+            pull_manifest("bitcoin-knots", "docker.io/bitcoin/knots:28"),
+            PathBuf::from("/tmp/bk"),
+        )
+        .await;
+        orch
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn initial_pass_fires_immediately() {
+        let rt = Arc::new(CountingRuntime::new_with(&["bitcoin-knots"]));
+        let orch = orch_with_one_running_manifest(rt.clone()).await;
+        let shutdown = Arc::new(Notify::new());
+        let reconciler = BootReconciler::new(
+            orch.clone(),
+            Duration::from_secs(30),
+            shutdown.clone(),
+        );
+        let handle = tokio::spawn(reconciler.run_forever());
+
+        // Yield so the spawned task gets CPU to run its initial reconcile.
+        tokio::task::yield_now().await;
+        tokio::task::yield_now().await;
+
+        // We expect exactly one reconcile pass to have run by now (the initial),
+        // NOT a second one (the 30s sleep hasn't elapsed in paused time).
+        assert_eq!(rt.status_call_count(), 1, "initial pass should fire once");
+
+        shutdown.notify_one();
+        // Under paused clock the select! is blocked on sleep_until; the notify
+        // will unblock it. Advance wall-clock a hair so the notify gets polled.
+        tokio::task::yield_now().await;
+        let _ = tokio::time::timeout(Duration::from_secs(1), handle).await;
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn second_pass_fires_after_interval() {
+        let rt = Arc::new(CountingRuntime::new_with(&["bitcoin-knots"]));
+        let orch = orch_with_one_running_manifest(rt.clone()).await;
+        let shutdown = Arc::new(Notify::new());
+        let reconciler = BootReconciler::new(
+            orch.clone(),
+            Duration::from_secs(30),
+            shutdown.clone(),
+        );
+        let handle = tokio::spawn(reconciler.run_forever());
+
+        tokio::task::yield_now().await;
+        tokio::task::yield_now().await;
+        assert_eq!(rt.status_call_count(), 1);
+
+        // Fast-forward past one interval; the sleep_until should fire.
+        tokio::time::advance(Duration::from_secs(31)).await;
+        tokio::task::yield_now().await;
+        tokio::task::yield_now().await;
+
+        assert_eq!(
+            rt.status_call_count(),
+            2,
+            "a second reconcile pass should fire after one interval"
+        );
+
+        shutdown.notify_one();
+        tokio::task::yield_now().await;
+        let _ = tokio::time::timeout(Duration::from_secs(1), handle).await;
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn shutdown_terminates_loop() {
+        let rt = Arc::new(CountingRuntime::new_with(&["bitcoin-knots"]));
+        let orch = orch_with_one_running_manifest(rt.clone()).await;
+        let shutdown = Arc::new(Notify::new());
+        let reconciler = BootReconciler::new(
+            orch.clone(),
+            Duration::from_secs(30),
+            shutdown.clone(),
+        );
+        let handle = tokio::spawn(reconciler.run_forever());
+        tokio::task::yield_now().await;
+        tokio::task::yield_now().await;
+
+        shutdown.notify_one();
+        // The select! should wake on Notified and return. Use a real timeout
+        // with advancing the paused clock to make sure the task exits.
+        tokio::time::advance(Duration::from_millis(10)).await;
+        let result = tokio::time::timeout(Duration::from_secs(5), handle).await;
+        assert!(result.is_ok(), "reconciler did not exit after shutdown");
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn failure_in_one_pass_does_not_stop_loop() {
+        // Manifest references a container the runtime does not have AND
+        // cannot create (no install path — install_fresh will also fail to
+        // pull, since CountingRuntime::pull_image returns Ok but the
+        // manifest's referenced container stays uncreated). In practice
+        // reconcile_all will observe the missing container, install_fresh
+        // will run, and the next pass will see a new state. We care about
+        // "loop keeps ticking even when the report has actions".
+        let rt = Arc::new(CountingRuntime::default());
+        let orch = Arc::new(ProdContainerOrchestrator::with_runtime(
+            rt.clone(),
+            PathBuf::from("/nonexistent-for-tests"),
+        ));
+        orch.insert_manifest_for_test(
+            pull_manifest("bitcoin-knots", "docker.io/bitcoin/knots:28"),
+            PathBuf::from("/tmp/bk"),
+        )
+        .await;
+        let shutdown = Arc::new(Notify::new());
+        let reconciler = BootReconciler::new(
+            orch.clone(),
+            Duration::from_secs(30),
+            shutdown.clone(),
+        );
+        let handle = tokio::spawn(reconciler.run_forever());
+
+        tokio::task::yield_now().await;
+        tokio::task::yield_now().await;
+        let first = rt.status_call_count();
+        assert!(first >= 1, "initial pass should have touched the runtime");
+
+        // Advance one interval — second pass should fire regardless of what
+        // the first pass did.
+        tokio::time::advance(Duration::from_secs(31)).await;
+        tokio::task::yield_now().await;
+        tokio::task::yield_now().await;
+        let second = rt.status_call_count();
+        assert!(
+            second > first,
+            "loop should have fired a second pass after the interval"
+        );
+
+        shutdown.notify_one();
+        tokio::time::advance(Duration::from_millis(10)).await;
+        let _ = tokio::time::timeout(Duration::from_secs(5), handle).await;
+    }
+}
@@ -1,12 +1,14 @@
 use anyhow::{Context, Result};
 use archipelago_container::{
    AppManifest, BitcoinSimulationMode, BitcoinSimulator,
-    ContainerRuntime as ContainerRuntimeTrait, ContainerStatus, PortManager,
+    ContainerRuntime as ContainerRuntimeTrait, ContainerStatus, PortManager, ResolvedSource,
 };
+use async_trait::async_trait;
 use std::sync::Arc;

 use crate::config::{BitcoinSimulation, Config, ContainerRuntime};
 use crate::container::data_manager::DevDataManager;
+use crate::container::traits::ContainerOrchestrator;

 pub struct DevContainerOrchestrator {
    runtime: Arc<dyn ContainerRuntimeTrait>,
@@ -103,14 +105,30 @@ impl DevContainerOrchestrator {
            volume.source = dev_path.to_string_lossy().to_string();
        }

-        // Pull image
-        self.runtime
-            .pull_image(
-                &manifest.app.container.image,
-                manifest.app.container.image_signature.as_deref(),
-            )
-            .await
-            .context("Failed to pull image")?;
+        // Resolve pull-or-build. Dev orchestrator currently only supports pull;
+        // Build support lands in Step 2 of the rust-orchestrator migration.
+        match manifest
+            .app
+            .container
+            .resolve()
+            .ok_or_else(|| anyhow::anyhow!("manifest container config invalid (neither image nor build)"))?
+        {
+            ResolvedSource::Pull {
+                image,
+                image_signature,
+                ..
+            } => {
+                self.runtime
+                    .pull_image(&image, image_signature.as_deref())
+                    .await
+                    .context("Failed to pull image")?;
+            }
+            ResolvedSource::Build(_) => {
+                anyhow::bail!(
+                    "dev orchestrator does not yet support local image builds (see rust-orchestrator-migration.md Step 2)"
+                );
+            }
+        }

        // Create container with port offset
        let port_offset = if self.config.dev_mode {
@@ -242,4 +260,82 @@ impl DevContainerOrchestrator {
            archipelago_container::ContainerState::Unknown(_) => Ok("unknown".to_string()),
        }
    }
+
+    /// Load a manifest for `app_id` from the dev-mode apps directory.
+    ///
+    /// Used by the trait-level `install(app_id)` entry point. Looks under
+    /// `<data_dir>/apps/<app_id>/manifest.yml`.
+    async fn load_manifest_for(&self, app_id: &str) -> Result<AppManifest> {
+        let path = self
+            .config
+            .data_dir
+            .join("apps")
+            .join(app_id)
+            .join("manifest.yml");
+        let content = tokio::fs::read_to_string(&path)
+            .await
+            .with_context(|| format!("reading manifest {}", path.display()))?;
+        let manifest: AppManifest = serde_yaml::from_str(&content)
+            .with_context(|| format!("parsing manifest {}", path.display()))?;
+        Ok(manifest)
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Trait impl (Step 4): expose the shared ContainerOrchestrator surface.
+// Forwards to the inherent methods, which internally apply the `-dev` suffix
+// and the port offset. The trait keeps the RPC layer mode-agnostic; Dev's
+// install_container (manifest_path-based) stays as an inherent method for the
+// ad-hoc dev-mode RPC and is not exposed on the trait.
+// ---------------------------------------------------------------------------
+
+#[async_trait]
+impl ContainerOrchestrator for DevContainerOrchestrator {
+    async fn install(&self, app_id: &str) -> Result<String> {
+        let manifest = self.load_manifest_for(app_id).await?;
+        let name = self.install_container(&manifest, "").await?;
+        Ok(name)
+    }
+
+    async fn start(&self, app_id: &str) -> Result<()> {
+        self.start_container(app_id).await
+    }
+
+    async fn stop(&self, app_id: &str) -> Result<()> {
+        self.stop_container(app_id).await
+    }
+
+    async fn restart(&self, app_id: &str) -> Result<()> {
+        let _ = self.stop_container(app_id).await;
+        self.start_container(app_id).await
+    }
+
+    async fn remove(&self, app_id: &str, preserve_data: bool) -> Result<()> {
+        self.remove_container(app_id, preserve_data).await
+    }
+
+    async fn upgrade(&self, app_id: &str) -> Result<()> {
+        // Dev upgrade: stop, remove (preserving data), re-install from the loaded manifest.
+        let _ = self.stop_container(app_id).await;
+        let _ = self.remove_container(app_id, true).await;
+        let manifest = self.load_manifest_for(app_id).await?;
+        self.install_container(&manifest, "").await?;
+        self.start_container(app_id).await
+    }
+
+    async fn status(&self, app_id: &str) -> Result<ContainerStatus> {
+        self.get_container_status(app_id).await
+    }
+
+    async fn list(&self) -> Result<Vec<ContainerStatus>> {
+        self.list_containers().await
+    }
+
+    async fn logs(&self, app_id: &str, lines: u32) -> Result<Vec<String>> {
+        self.get_container_logs(app_id, lines).await
+    }
+
+    async fn health(&self, app_id: &str) -> Result<String> {
+        self.get_health_status(app_id).await
+    }
 }
@@ -44,11 +44,6 @@ impl DockerPackageScanner {
            "nbxplorer",
            "mempool-db",
            "mempool-api",
-            "penpot-postgres",
-            "penpot-backend",
-            "penpot-exporter",
-            "penpot-valkey",
-            "penpot-mailcatch",
            "immich_postgres",
            "immich_redis",
            "endurain-db",
@@ -247,6 +242,7 @@ impl DockerPackageScanner {
                    status: service_status,
                }),
                install_progress: None,
+                uninstall_stage: None,
            };

            packages.insert(app_id.clone(), package);
@@ -296,9 +292,16 @@ fn get_app_tier(app_id: &str) -> &'static str {

 fn get_app_metadata(app_id: &str) -> AppMetadata {
    let mut meta = match app_id {
-        "bitcoin" | "bitcoin-core" | "bitcoin-knots" => AppMetadata {
+        "bitcoin-core" => AppMetadata {
+            title: "Bitcoin Core".to_string(),
+            description: "Reference Bitcoin node implementation".to_string(),
+            icon: "/assets/img/app-icons/bitcoin-core.svg".to_string(),
+            repo: "https://github.com/bitcoin/bitcoin".to_string(),
+            tier: "",
+        },
+        "bitcoin" | "bitcoin-knots" => AppMetadata {
            title: "Bitcoin Knots".to_string(),
-            description: "Full Bitcoin node implementation".to_string(),
+            description: "Enhanced Bitcoin node implementation".to_string(),
            icon: "/assets/img/app-icons/bitcoin-knots.webp".to_string(),
            repo: "https://github.com/bitcoinknots/bitcoin".to_string(),
            tier: "",
@@ -408,13 +411,6 @@ fn get_app_metadata(app_id: &str) -> AppMetadata {
            repo: "https://github.com/cryptpad/cryptpad".to_string(),
            tier: "",
        },
-        "penpot" | "penpot-frontend" => AppMetadata {
-            title: "Penpot".to_string(),
-            description: "Open-source design and prototyping".to_string(),
-            icon: "/assets/img/app-icons/penpot.webp".to_string(),
-            repo: "https://github.com/penpot/penpot".to_string(),
-            tier: "",
-        },
        "nextcloud" => AppMetadata {
            title: "Nextcloud".to_string(),
            description: "Self-hosted cloud storage and file management".to_string(),
@@ -492,13 +488,6 @@ fn get_app_metadata(app_id: &str) -> AppMetadata {
            repo: "https://github.com/indeedhub/indeedhub".to_string(),
            tier: "",
        },
-        "nostr-rs-relay" => AppMetadata {
-            title: "Nostr Relay".to_string(),
-            description: "Run your own Nostr relay for sovereign event storage".to_string(),
-            icon: "/assets/img/app-icons/nostr-rs-relay.svg".to_string(),
-            repo: "https://sr.ht/~gheartsfield/nostr-rs-relay/".to_string(),
-            tier: "",
-        },
        "dwn" => AppMetadata {
            title: "Decentralized Web Node".to_string(),
            description: "Store and sync personal data with DID-based access control".to_string(),
@@ -1,8 +1,8 @@
 //! Parser for image-versions.sh — single source of truth for pinned container images.
 //!
-//! Reads the deployed file at /opt/archipelago/image-versions.sh (or the repo-local
-//! scripts/image-versions.sh as fallback) and exposes lookup functions so the container
-//! scanner can compare running images against pinned targets.
+//! Reads the deployed file at /opt/archipelago/scripts/image-versions.sh (the canonical
+//! location installed by the image-recipe) with fallbacks for older layouts and the
+//! repo-local scripts/image-versions.sh for development runs from the repo root.

 use std::collections::HashMap;
 use std::path::Path;
@@ -18,8 +18,13 @@ struct CacheEntry {
    images: HashMap<String, String>,
 }

-/// File search order — production path first, then repo-local for dev.
+/// File search order — canonical production path first, older layout second,
+/// repo-local for dev last. The canonical deployed path is
+/// /opt/archipelago/scripts/image-versions.sh; earlier builds put it directly
+/// in /opt/archipelago/, so that path is kept as a fallback for not-yet-updated
+/// nodes. The repo-relative entry matches `cargo run` from the repo root.
 const PATHS: &[&str] = &[
+    "/opt/archipelago/scripts/image-versions.sh",
    "/opt/archipelago/image-versions.sh",
    "scripts/image-versions.sh",
 ];
@@ -102,8 +107,11 @@ fn parse_image_versions(content: &str) -> HashMap<String, String> {
        }
    }

-    // Keep only *_IMAGE entries
-    vars.retain(|k, _| k.ends_with("_IMAGE"));
+    // Keep only *_IMAGE entries whose value looks like a container image
+    // reference (contains a `:` tag separator and at least one `/` path
+    // component). Rejects placeholder values like "something" so a
+    // hand-edit typo in image-versions.sh never gets treated as an image.
+    vars.retain(|k, v| k.ends_with("_IMAGE") && v.contains(':') && v.contains('/'));
    vars
 }

@@ -1,8 +1,18 @@
+pub mod bitcoin_ui;
+pub mod boot_reconciler;
 pub mod data_manager;
 pub mod dev_orchestrator;
 pub mod docker_packages;
 pub mod image_versions;
+pub mod prod_orchestrator;
 pub mod registry;
+pub mod traits;

+pub use boot_reconciler::{BootReconciler, DEFAULT_INTERVAL as RECONCILER_DEFAULT_INTERVAL};
 pub use dev_orchestrator::DevContainerOrchestrator;
 pub use docker_packages::DockerPackageScanner;
+pub use prod_orchestrator::{
+    compute_container_name, AdoptionReport, ProdContainerOrchestrator, ReconcileAction,
+    ReconcileReport,
+};
+pub use traits::ContainerOrchestrator;
@@ -15,7 +15,7 @@ const REGISTRY_FILE: &str = "config/registries.json";
 /// A single container registry.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Registry {
-    /// Registry URL (e.g., "git.tx1138.com/lfg2025" or "23.182.128.160:3000/lfg2025").
+    /// Registry URL (e.g., "git.tx1138.com/lfg2025" or "146.59.87.168:3000/lfg2025").
    pub url: String,
    /// Human-readable name.
    pub name: String,
@@ -44,16 +44,16 @@ impl Default for RegistryConfig {
        Self {
            registries: vec![
                Registry {
-                    url: "git.tx1138.com/lfg2025".to_string(),
-                    name: "Archipelago Primary".to_string(),
-                    tls_verify: true,
+                    url: "146.59.87.168:3000/lfg2025".to_string(),
+                    name: "Server 1 (OVH)".to_string(),
+                    tls_verify: false,
                    enabled: true,
                    priority: 0,
                },
                Registry {
-                    url: "23.182.128.160:3000/lfg2025".to_string(),
-                    name: "Archipelago Fallback".to_string(),
-                    tls_verify: false,
+                    url: "git.tx1138.com/lfg2025".to_string(),
+                    name: "Server 2 (tx1138)".to_string(),
+                    tls_verify: true,
                    enabled: true,
                    priority: 10,
                },
@@ -71,8 +71,8 @@ impl RegistryConfig {
    }

    /// Rewrite an image reference to use a specific registry.
-    /// E.g., "git.tx1138.com/lfg2025/bitcoin-knots:latest" with registry "23.182.128.160:3000/lfg2025"
-    /// becomes "23.182.128.160:3000/lfg2025/bitcoin-knots:latest".
+    /// E.g., "git.tx1138.com/lfg2025/bitcoin-knots:latest" with registry "146.59.87.168:3000/lfg2025"
+    /// becomes "146.59.87.168:3000/lfg2025/bitcoin-knots:latest".
    pub fn rewrite_image(&self, image: &str, registry: &Registry) -> String {
        // Extract the image name (last component after the org/namespace)
        // Handles: "registry/org/image:tag" -> "image:tag"
@@ -80,20 +80,6 @@ impl RegistryConfig {
        format!("{}/{}", registry.url, image_name)
    }

-    /// Generate fallback image URLs to try (excludes the original since it already failed).
-    pub fn image_candidates(&self, image: &str) -> Vec<(String, bool)> {
-        let mut candidates = Vec::new();
-
-        // Rewrite for each active registry (skip if identical to original)
-        for reg in self.active_registries() {
-            let rewritten = self.rewrite_image(image, reg);
-            if rewritten != image {
-                candidates.push((rewritten, reg.tls_verify));
-            }
-        }
-
-        candidates
-    }
 }

 /// Extract the image name from a full image reference.
@@ -104,7 +90,12 @@ fn extract_image_name(image: &str) -> &str {
    image.rsplit('/').next().unwrap_or(image)
 }

-/// Load registry config from disk.
+/// Load registry config from disk, merging in any default registries
+/// that the operator hasn't explicitly removed. This lets us roll out
+/// new default mirrors (e.g. a new Server 3) to existing nodes without
+/// them having to edit their saved config. Explicit removals stick —
+/// if the URL is absent from disk AND absent from current defaults, it
+/// stays gone.
 pub async fn load_registries(data_dir: &Path) -> Result<RegistryConfig> {
    let path = data_dir.join(REGISTRY_FILE);
    if !path.exists() {
@@ -113,8 +104,44 @@ pub async fn load_registries(data_dir: &Path) -> Result<RegistryConfig> {
    let content = fs::read_to_string(&path)
        .await
        .context("Failed to read registry config")?;
-    let config: RegistryConfig =
+    let mut config: RegistryConfig =
        serde_json::from_str(&content).unwrap_or_else(|_| RegistryConfig::default());
+
+    // One-time migration: the Hetzner VPS at 23.182.128.160 was
+    // decommissioned 2026-04-23. Existing nodes have it baked into
+    // their saved registry list (was the original Server 1). Strip it
+    // on load so every container pull doesn't pay a connection-refused
+    // timeout against a dead host. Exception to the usual "explicit
+    // removals stick" rule: the user never chose to add this — it
+    // was a default.
+    let before = config.registries.len();
+    config.registries.retain(|r| !r.url.contains("23.182.128.160"));
+    let mut changed = config.registries.len() != before;
+
+    // Migrate: any default registry URL that isn't already in the
+    // saved list gets appended at the end (so existing priority order
+    // is preserved for anything the operator already configured).
+    let defaults = RegistryConfig::default();
+    let known: std::collections::HashSet<String> =
+        config.registries.iter().map(|r| r.url.clone()).collect();
+    let max_priority = config
+        .registries
+        .iter()
+        .map(|r| r.priority)
+        .max()
+        .unwrap_or(0);
+    for (i, def) in defaults.registries.iter().enumerate() {
+        if !known.contains(&def.url) {
+            let mut cloned = def.clone();
+            cloned.priority = max_priority.saturating_add(10 + i as u32);
+            config.registries.push(cloned);
+            changed = true;
+        }
+    }
+    if changed {
+        // Persist so the next load doesn't have to re-merge.
+        let _ = save_registries(data_dir, &config).await;
+    }
    Ok(config)
 }

@@ -133,69 +160,6 @@ pub async fn save_registries(data_dir: &Path, config: &RegistryConfig) -> Result
    Ok(())
 }

-/// Try pulling an image from configured registries in priority order.
-/// Returns the image reference that succeeded.
-pub async fn pull_from_registries(data_dir: &Path, image: &str, tmpdir: &str) -> Result<String> {
-    let config = load_registries(data_dir).await?;
-    let candidates = config.image_candidates(image);
-
-    for (candidate, tls_verify) in &candidates {
-        debug!("Trying registry: {}", candidate);
-
-        let mut args = vec!["pull".to_string(), candidate.clone()];
-        if !tls_verify {
-            args.push("--tls-verify=false".to_string());
-        }
-
-        let mut child = tokio::process::Command::new("podman")
-            .args(&args)
-            .env("TMPDIR", tmpdir)
-            .stdout(std::process::Stdio::null())
-            .stderr(std::process::Stdio::null())
-            .spawn()
-            .ok();
-
-        let status = if let Some(ref mut c) = child {
-            match tokio::time::timeout(std::time::Duration::from_secs(120), c.wait()).await {
-                Ok(Ok(s)) => Some(s.success()),
-                _ => {
-                    let _ = c.kill().await;
-                    let _ = c.wait().await;
-                    debug!("Fallback pull timed out: {}", candidate);
-                    None
-                }
-            }
-        } else {
-            None
-        };
-
-        if status == Some(true) {
-            // If we pulled from a non-original registry, tag it with the original name
-            if candidate != image {
-                let _ = tokio::process::Command::new("podman")
-                    .args(["tag", candidate, image])
-                    .status()
-                    .await;
-                info!(
-                    "Pulled {} from fallback registry, tagged as {}",
-                    candidate, image
-                );
-            } else {
-                info!("Pulled {} from primary registry", image);
-            }
-            return Ok(candidate.clone());
-        }
-
-        debug!("Failed to pull from {}", candidate);
-    }
-
-    Err(anyhow::anyhow!(
-        "Failed to pull {} from all {} configured registries",
-        image,
-        candidates.len()
-    ))
-}
-
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -217,21 +181,15 @@ mod tests {
    #[test]
    fn test_rewrite_image() {
        let config = RegistryConfig::default();
-        let fallback = &config.registries[1];
+        // Default primary is now the OVH VPS (index 0). A tx1138-hardcoded
+        // image rewrites to OVH when asked for the primary mirror.
+        let primary = &config.registries[0];
        assert_eq!(
-            config.rewrite_image("git.tx1138.com/lfg2025/bitcoin-knots:latest", fallback),
-            "23.182.128.160:3000/lfg2025/bitcoin-knots:latest"
+            config.rewrite_image("git.tx1138.com/lfg2025/bitcoin-knots:latest", primary),
+            "146.59.87.168:3000/lfg2025/bitcoin-knots:latest"
        );
    }

-    #[test]
-    fn test_image_candidates() {
-        let config = RegistryConfig::default();
-        let candidates = config.image_candidates("git.tx1138.com/lfg2025/lnd:v0.18.4-beta");
-        assert!(candidates.len() >= 2);
-        assert_eq!(candidates[0].0, "git.tx1138.com/lfg2025/lnd:v0.18.4-beta");
-    }
-
    #[test]
    fn test_active_registries_sorted() {
        let config = RegistryConfig::default();
@@ -0,0 +1,56 @@
+//! Orchestrator trait — the shared surface the RPC layer talks to.
+//!
+//! Step 4 of the rust-orchestrator migration. Unifies the container lifecycle
+//! surface of `DevContainerOrchestrator` and `ProdContainerOrchestrator` so
+//! `RpcHandler` can hold `Arc<dyn ContainerOrchestrator>` and stop caring
+//! which mode it is in.
+//!
+//! The trait takes `app_id: &str` everywhere (never a manifest path). Dev and
+//! Prod both resolve app_id → manifest internally. The legacy
+//! `container-install { manifest_path }` RPC shape is preserved as a concrete
+//! `install_container_from_path` method on `DevContainerOrchestrator` only,
+//! since that ad-hoc workflow is a dev convenience and has no prod meaning.
+//!
+//! See `docs/rust-orchestrator-migration.md`.
+
+use anyhow::Result;
+use archipelago_container::ContainerStatus;
+use async_trait::async_trait;
+
+/// Lifecycle + query operations every orchestrator exposes to the RPC layer.
+#[async_trait]
+pub trait ContainerOrchestrator: Send + Sync {
+    /// Build-or-pull the image, create the container, and start it. Returns the
+    /// podman container name that was created. Assumes the app_id corresponds
+    /// to a manifest the orchestrator already knows about.
+    async fn install(&self, app_id: &str) -> Result<String>;
+
+    /// Start an already-created container.
+    async fn start(&self, app_id: &str) -> Result<()>;
+
+    /// Stop a running container. No-op on Prod if already stopped.
+    async fn stop(&self, app_id: &str) -> Result<()>;
+
+    /// Stop-then-start. Best-effort: ignores stop failure.
+    async fn restart(&self, app_id: &str) -> Result<()>;
+
+    /// Remove the container. `preserve_data = true` keeps the volumes; `false`
+    /// is honored on a best-effort basis (Dev cleans, Prod leaves the volume
+    /// management to the data layer).
+    async fn remove(&self, app_id: &str, preserve_data: bool) -> Result<()>;
+
+    /// Pull/rebuild the image and recreate the container from scratch.
+    async fn upgrade(&self, app_id: &str) -> Result<()>;
+
+    /// Current state of a single container.
+    async fn status(&self, app_id: &str) -> Result<ContainerStatus>;
+
+    /// All containers this orchestrator knows about.
+    async fn list(&self) -> Result<Vec<ContainerStatus>>;
+
+    /// Tail the container's stdout+stderr.
+    async fn logs(&self, app_id: &str, lines: u32) -> Result<Vec<String>>;
+
+    /// Coarse health summary: "healthy", "unhealthy", "starting", "paused", "unknown".
+    async fn health(&self, app_id: &str) -> Result<String>;
+}
@@ -129,9 +129,21 @@ pub fn is_revoked(vc: &VerifiableCredential) -> bool {
 mod tests {
    use super::*;

+    /// Create a tempdir with a dummy `identity/node_key` so that the
+    /// credential store's encrypt/decrypt path can derive a key.
+    /// Returns the tempdir guard (drop it to clean up).
+    fn test_dir_with_node_key() -> tempfile::TempDir {
+        let dir = tempfile::tempdir().unwrap();
+        let identity_dir = dir.path().join("identity");
+        std::fs::create_dir_all(&identity_dir).unwrap();
+        // 32 bytes of deterministic test material; never a real key.
+        std::fs::write(identity_dir.join("node_key"), [0xAB; 32]).unwrap();
+        dir
+    }
+
    #[tokio::test]
    async fn test_issue_credential_w3c_format() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        let vc = issue_credential(
            dir.path(),
            "did:key:issuer",
@@ -163,7 +175,7 @@ mod tests {

    #[tokio::test]
    async fn test_issue_credential_serializes_as_jsonld() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        let vc = issue_credential(
            dir.path(),
            "did:key:issuer",
@@ -185,7 +197,7 @@ mod tests {

    #[tokio::test]
    async fn test_save_and_load_roundtrip() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        issue_credential(
            dir.path(),
            "did:key:a",
@@ -205,7 +217,7 @@ mod tests {

    #[tokio::test]
    async fn test_issue_credential_sign_fn_failure_propagates() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        let result = issue_credential(
            dir.path(),
            "did:key:issuer",
@@ -257,7 +269,7 @@ mod tests {

    #[tokio::test]
    async fn test_revoke_credential() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        let vc = issue_credential(
            dir.path(),
            "did:key:issuer",
@@ -288,7 +300,7 @@ mod tests {

    #[tokio::test]
    async fn test_revoke_nonexistent_credential_fails() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        let result = revoke_credential(dir.path(), "urn:uuid:does-not-exist").await;
        assert!(result.is_err());
        assert!(result
@@ -299,7 +311,7 @@ mod tests {

    #[tokio::test]
    async fn test_list_credentials_no_filter() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        issue_credential(
            dir.path(),
            "did:key:a",
@@ -329,7 +341,7 @@ mod tests {

    #[tokio::test]
    async fn test_list_credentials_filter_by_did() {
-        let dir = tempfile::tempdir().unwrap();
+        let dir = test_dir_with_node_key();
        issue_credential(
            dir.path(),
            "did:key:alice",
@@ -138,6 +138,13 @@ pub struct PackageDataEntry {
    pub installed: Option<InstalledPackageDataEntry>,
    #[serde(rename = "install-progress")]
    pub install_progress: Option<InstallProgress>,
+    /// Live label describing the current uninstall step ("Stopping
+    /// containers (2/5)", "Removing data", …). Set by the uninstall
+    /// pipeline so the UI can show real progress instead of a generic
+    /// "Uninstalling…" spinner. Cleared after the package entry is
+    /// removed.
+    #[serde(rename = "uninstall-stage", skip_serializing_if = "Option::is_none", default)]
+    pub uninstall_stage: Option<String>,
    /// Pinned image version from image-versions.sh when it differs from running version
    #[serde(rename = "available-update", skip_serializing_if = "Option::is_none")]
    pub available_update: Option<String>,
@@ -238,6 +245,38 @@ pub enum ServiceStatus {
 pub struct InstallProgress {
    pub size: u64,
    pub downloaded: u64,
+    /// High-level pipeline phase. Preferred by the UI over the byte
+    /// counters (podman pull doesn't emit parseable progress on a piped
+    /// stderr, so `size`/`downloaded` are often 0). Each phase maps to
+    /// a fixed UI percentage and a descriptive label.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub phase: Option<InstallPhase>,
+}
+
+/// Phases of the install / update pipeline, surfaced to the UI so users
+/// see where the pipeline is rather than a stuck 0% bar.
+///
+/// Ordered so each variant's index roughly corresponds to pipeline time.
+/// Serialized as kebab-case: "preparing", "pulling-image", …
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "kebab-case")]
+pub enum InstallPhase {
+    /// Validating params, checking deps, writing dynamic configs.
+    Preparing,
+    /// `podman pull` in progress (the longest phase — up to several
+    /// minutes for large images on slow networks).
+    PullingImage,
+    /// Creating data directories, writing app-specific configs
+    /// (bitcoin.conf, lnd.conf, searxng settings.yml, chown).
+    CreatingContainer,
+    /// `podman run` has returned; container is transitioning to running.
+    StartingContainer,
+    /// Post-start loop waiting up to 60s for `State.Status == running`.
+    WaitingHealthy,
+    /// Running post-install hooks (chain init, wallet setup, …).
+    PostInstall,
+    /// Pipeline finished successfully. Terminal phase, UI clears entry.
+    Done,
 }

 /// WebSocket message sent to clients
@@ -180,7 +180,10 @@ mod tests {
        // anchor is the only candidate.
        let status = FipsStatus::query(dir.path()).await;
        assert!(!status.key_present, "no key before onboarding");
-        assert!(status.npub.is_none());
+        // `npub` falls back to whatever an already-running local fips
+        // daemon advertises, so on a dev machine or node with fips
+        // installed this field can be Some(...) even when the test
+        // data_dir is empty. We only assert that key_present is false.
        // `installed`, `service_state`, `version` depend on the host and are
        // not asserted here — query() must return cleanly regardless.
    }
@@ -216,6 +216,80 @@ impl IdentityManager {
        Ok(record)
    }

+    /// Mirror an existing Ed25519 signing key as a manager-level identity.
+    ///
+    /// Used at boot to expose the node's own seed-derived key (the one that
+    /// backs `server_info.pubkey` and peer-to-peer connections) as an
+    /// entry in the Identities page, so all three surfaces — DID Status,
+    /// "Node" entry on Identities, and peer-connect DID — resolve to the
+    /// same DID. The id is deterministic (`node-<pubkey16>`), so repeated
+    /// calls on the same key are idempotent: if the file already exists
+    /// we return the existing record untouched.
+    pub async fn create_from_signing_key(
+        &self,
+        name: String,
+        purpose: IdentityPurpose,
+        signing_key: SigningKey,
+    ) -> Result<IdentityRecord> {
+        let pubkey_hex = hex::encode(signing_key.verifying_key().as_bytes());
+        let did = did_key_from_pubkey_hex(&pubkey_hex)?;
+        let id = format!("node-{}", &pubkey_hex[..16]);
+
+        // Idempotent: if we already mirrored this key, just return it.
+        let file_path = self.identities_dir.join(format!("{}.json", id));
+        if file_path.exists() {
+            return self.get(&id).await;
+        }
+
+        let created_at = chrono::Utc::now().to_rfc3339();
+        // Mark as the node (master) identity so it gets the hex SVG.
+        let default_profile = IdentityProfile {
+            picture: Some(crate::avatar::default_picture(&pubkey_hex, true)),
+            ..Default::default()
+        };
+
+        let identity_file = IdentityFile {
+            id: id.clone(),
+            name: name.clone(),
+            purpose: purpose.clone(),
+            secret_key: signing_key.to_bytes().to_vec(),
+            pubkey_hex: pubkey_hex.clone(),
+            did: did.clone(),
+            created_at,
+            nostr_secret_hex: None,
+            nostr_pubkey_hex: None,
+            profile: Some(default_profile),
+            derivation_index: Some(0),
+        };
+
+        let json = serde_json::to_string_pretty(&identity_file)
+            .context("Failed to serialize identity")?;
+        fs::write(&file_path, json.as_bytes())
+            .await
+            .context("Failed to write identity file")?;
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            fs::set_permissions(&file_path, std::fs::Permissions::from_mode(0o600))
+                .await
+                .context("Failed to set identity file permissions")?;
+        }
+
+        // First identity becomes the default.
+        let (existing, _) = self.list().await?;
+        if existing.len() <= 1 {
+            self.set_default(&id).await?;
+        }
+
+        tracing::info!(
+            "Mirrored node signing key as Node identity '{}' ({})",
+            name,
+            purpose
+        );
+
+        self.get(&id).await
+    }
+
    /// Create a new identity with keys derived from a BIP-39 master seed.
    /// The derivation index is auto-incremented and persisted.
    pub async fn create_from_seed(
@@ -811,11 +885,13 @@ mod tests {
    async fn test_create_nostr_key_npub_format() {
        let dir = tempdir().unwrap();
        let mgr = IdentityManager::new(dir.path()).await.unwrap();
+        // `create()` auto-provisions a Nostr key for every identity, so the
+        // returned record should already have a valid bech32 npub.
        let record = mgr
-            .create("Nostr".to_string(), IdentityPurpose::Personal)
+            .create("Personal".to_string(), IdentityPurpose::Personal)
            .await
            .unwrap();
-        let npub = mgr.create_nostr_key(&record.id).await.unwrap();
+        let npub = record.nostr_npub.expect("nostr npub should be populated");
        assert!(
            npub.starts_with("npub1"),
            "npub should start with npub1, got {}",
@@ -19,7 +19,9 @@

 use anyhow::{Context, Result};
 use std::net::SocketAddr;
+use std::sync::Arc;
 use tokio::signal;
+use tokio::sync::Notify;
 use tracing::info;

 mod api;
@@ -28,6 +30,7 @@ mod avatar;
 mod backup;
 mod bitcoin_rpc;
 mod blobs;
+mod bootstrap;
 mod config;
 mod constants;
 mod container;
@@ -68,6 +71,10 @@ mod wallet;
 mod webhooks;

 use config::Config;
+use container::{
+    BootReconciler, ContainerOrchestrator, DevContainerOrchestrator, ProdContainerOrchestrator,
+    RECONCILER_DEFAULT_INTERVAL,
+};
 use server::Server;

 #[tokio::main]
@@ -85,6 +92,36 @@ async fn main() -> Result<()> {

    info!("Starting Archipelago Bitcoin Node OS");

+    // Self-heal web-ui permissions. The OTA updater in <=v1.7.38 left
+    // /opt/archipelago/web-ui as drwx------ (700) after the atomic
+    // swap — nginx (www-data) then returned 500/403 on every request
+    // until someone shelled in and chmod'd it. Check on every boot
+    // and repair if needed so a node auto-recovers after the next
+    // service restart that follows a broken OTA.
+    tokio::spawn(async move {
+        use std::os::unix::fs::PermissionsExt;
+        let web_ui = std::path::Path::new("/opt/archipelago/web-ui");
+        if let Ok(meta) = tokio::fs::metadata(web_ui).await {
+            let mode = meta.permissions().mode() & 0o777;
+            if mode & 0o005 != 0o005 {
+                tracing::warn!(
+                    "web-ui perms {:o} not world-readable — self-healing",
+                    mode
+                );
+                let _ = tokio::process::Command::new("sudo")
+                    .args([
+                        "-n",
+                        "chmod",
+                        "-R",
+                        "u=rwX,go=rX",
+                        "/opt/archipelago/web-ui",
+                    ])
+                    .status()
+                    .await;
+            }
+        }
+    });
+
    // Load configuration
    let config = Config::load().await?;
    info!("📁 Data directory: {}", config.data_dir.display());
@@ -137,15 +174,65 @@ async fn main() -> Result<()> {

            // Signal to health monitor that boot recovery is done
            crash_recovery::mark_recovery_complete();
-
-            // Boot reconciliation disabled — the reconciler creates ALL containers
-            // from specs, which is wrong on unbundled installs where only user-chosen
-            // apps should exist. The health monitor handles restarting existing
-            // containers. Run reconcile-containers.sh manually when needed.
-            // crash_recovery::run_boot_reconciliation().await;
        });
    }

+    // Construct the container orchestrator once. In prod mode we load the
+    // on-disk app manifests, do an initial adoption pass, and spawn the
+    // BootReconciler loop (Step 5/6 of the rust-orchestrator migration).
+    // Dev mode uses the in-memory DevContainerOrchestrator and has no
+    // reconciler (manifests are pushed via RPC, not discovered from disk).
+    let shutdown_notify = Arc::new(Notify::new());
+    let (orchestrator, dev_orchestrator): (
+        Option<Arc<dyn ContainerOrchestrator>>,
+        Option<Arc<DevContainerOrchestrator>>,
+    ) = if config.dev_mode {
+        let dev = Arc::new(DevContainerOrchestrator::new(config.clone()).await?);
+        let trait_obj: Arc<dyn ContainerOrchestrator> = dev.clone();
+        (Some(trait_obj), Some(dev))
+    } else {
+        let prod = Arc::new(ProdContainerOrchestrator::new(config.clone()).await?);
+        // Best-effort manifest load; a missing /opt/archipelago/apps is
+        // logged inside load_manifests and not fatal.
+        match prod.load_manifests().await {
+            Ok(n) => info!("📦 Loaded {n} app manifest(s) from disk"),
+            Err(e) => {
+                tracing::error!(error = %e, "prod orchestrator: load_manifests failed at startup");
+            }
+        }
+        // Adoption pass: link existing podman containers back to their
+        // manifests so the reconciler doesn't recreate them.
+        match prod.adopt_existing().await {
+            Ok(report) => {
+                info!(
+                    "🔗 Adopted {} existing container(s): {:?}",
+                    report.adopted.len(),
+                    report.adopted
+                );
+            }
+            Err(e) => {
+                tracing::warn!(error = %e, "prod orchestrator: adopt_existing failed (non-fatal)");
+            }
+        }
+        // Spawn the boot reconciler loop. Runs an initial reconcile
+        // immediately, then re-checks every RECONCILER_DEFAULT_INTERVAL
+        // until shutdown_notify fires.
+        {
+            let reconciler = BootReconciler::new(
+                prod.clone(),
+                RECONCILER_DEFAULT_INTERVAL,
+                shutdown_notify.clone(),
+            );
+            tokio::spawn(reconciler.run_forever());
+            info!(
+                "🔄 Boot reconciler started (interval: {:?})",
+                RECONCILER_DEFAULT_INTERVAL
+            );
+        }
+        let trait_obj: Arc<dyn ContainerOrchestrator> = prod;
+        (Some(trait_obj), None)
+    };
+
    // Ensure a default user exists so login works after install/onboarding.
    // In production, the default password is "password123" (shown during install).
    // In dev mode, the dev default password is used.
@@ -154,7 +241,7 @@ async fn main() -> Result<()> {
    // "Create Password" form instead of login form.

    // Create server
-    let server = Server::new(config.clone()).await?;
+    let server = Server::new(config.clone(), orchestrator, dev_orchestrator).await?;

    // Start server
    let addr: SocketAddr = format!("{}:{}", config.bind_host, config.bind_port)
@@ -165,12 +252,30 @@ async fn main() -> Result<()> {
    // on a 30s poll of fips0 — so a post-onboarding fips.install brings it
    // online without needing an archipelago restart.

+    // Post-OTA verification: if apply_update() wrote a pending-verify
+    // marker right before the restart, probe the frontend now and auto-
+    // rollback if it's broken. This is the guardrail that stops fleet-
+    // wide breakage when an OTA lands a subtly-bad release (v1.7.38/39
+    // tarball-perms → nginx 500 was the trigger). Runs concurrently
+    // with normal startup — doesn't delay the server coming up.
+    {
+        let data_dir = config.data_dir.clone();
+        tokio::spawn(async move {
+            update::verify_pending_update(&data_dir).await;
+        });
+    }
+
    // Spawn background update scheduler
    let update_data_dir = config.data_dir.clone();
    tokio::spawn(async move {
        update::run_update_scheduler(update_data_dir).await;
    });

+    // Synchronize host-side doctor artifacts (script + systemd units) with
+    // what's embedded in this binary. Runs in the background so it never
+    // delays server readiness; best-effort, warnings only.
+    tokio::spawn(bootstrap::ensure_doctor_installed());
+
    // Spawn periodic container snapshot (for crash recovery)
    crash_recovery::spawn_snapshot_task(config.data_dir.clone());

@@ -212,6 +317,7 @@ async fn main() -> Result<()> {
    // Graceful shutdown: wait for SIGTERM or SIGINT
    let mut sigterm = signal::unix::signal(signal::unix::SignalKind::terminate())
        .context("Failed to register SIGTERM handler")?;
+    let shutdown_notify_for_signal = shutdown_notify.clone();
    let shutdown = async move {
        tokio::select! {
            _ = signal::ctrl_c() => {
@@ -221,6 +327,10 @@ async fn main() -> Result<()> {
                info!("Received SIGTERM, initiating graceful shutdown...");
            }
        }
+        // Signal the boot reconciler (and any other subscribers) to stop.
+        // `notify_one` stores a permit if no task is currently parked on
+        // `notified()`, so we don't race the reconciler's reconcile_all pass.
+        shutdown_notify_for_signal.notify_one();
    };

    server.serve_with_shutdown(addr, shutdown).await?;
@@ -229,5 +339,14 @@ async fn main() -> Result<()> {
    crash_recovery::remove_pid_marker(&config.data_dir).await;

    info!("Archipelago shut down cleanly");
-    Ok(())
+
+    // Hard-exit after logging. All business state is persisted by now
+    // (connections drained, PID marker removed, disk flushes done via
+    // tokio::fs awaits). Letting tokio try to drop the runtime instead
+    // can stall for 15s+ on non-daemon OS threads we don't directly
+    // own (mdns_sd daemon, reqwest resolver pool, etc.) — long enough
+    // for systemd's TimeoutStopSec to SIGKILL us and mark the service
+    // Failed, which makes an otherwise-successful update look like a
+    // crash in `systemctl status`.
+    std::process::exit(0);
 }
@@ -457,8 +457,9 @@ mod tests {
        let key = SigningKey::generate(&mut OsRng);
        let wire = build_block_header_announcement(
            890412,
-            "0000000000000000000abc",
-            "0000000000000000000aab",
+            // Block hashes must be 32 bytes (64 hex chars). Use realistic-shaped placeholders.
+            "0000000000000000000abc00000000000000000000000000000000000000abcd",
+            "0000000000000000000aab0000000000000000000000000000000000000aabcd",
            1710633600,
            "did:key:z6MkTest",
            &key,
@@ -469,7 +470,9 @@ mod tests {
        assert_eq!(wire[0], 0x02);
        let envelope = TypedEnvelope::from_wire(&wire).unwrap();
        assert_eq!(envelope.t, MeshMessageType::BlockHeader as u8);
-        assert!(envelope.sig.is_some());
+        // Block header announcements are intentionally unsigned to save 64 bytes
+        // on the 160-byte LoRa payload (see builder comment).
+        assert!(envelope.sig.is_none());
    }

    #[test]
@@ -52,7 +52,10 @@ impl PendingMessage {
            return true; // Can't parse = treat as expired
        };
        let age = chrono::Utc::now().signed_duration_since(created);
-        age.num_seconds() as u64 > self.ttl_secs
+        // Use `>=` so a ttl_secs=0 message is expired immediately (used by
+        // tests and by callers that want a fire-and-forget behavior when
+        // the relay can't deliver on first try).
+        age.num_seconds() as u64 >= self.ttl_secs
    }

    /// Check if this message can be relayed further.
@@ -701,9 +701,11 @@ mod tests {

    #[test]
    fn test_build_app_start() -> Result<()> {
+        // Frame layout: [0: '>'][1-2: len LE][3: CMD][4: VERSION][5..: padded name]
        let frame = build_app_start("Archipelago");
        assert_eq!(frame[3], CMD_APP_START);
-        let name = &frame[4..];
+        assert_eq!(frame[4], PROTOCOL_VERSION);
+        let name = &frame[5..];
        assert_eq!(
            std::str::from_utf8(name)
                .map_err(|e| anyhow::anyhow!("invalid UTF-8 in app name: {}", e))?,
@@ -753,15 +755,20 @@ mod tests {

    #[test]
    fn test_identity_broadcast_roundtrip() -> Result<()> {
-        let did = "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK";
+        // The v2 encoding drops the DID and the decoder reconstructs it
+        // deterministically from the ed25519 pubkey, so the roundtripped
+        // DID won't equal an arbitrary input DID. Derive what the decoder
+        // will produce and assert against that.
        let ed_pub = "a".repeat(64);
        let x25519_pub = "b".repeat(64);
+        let expected_did = crate::identity::did_key_from_pubkey_hex(&ed_pub)
+            .map_err(|e| anyhow::anyhow!("derive did: {}", e))?;

-        let encoded = encode_identity_broadcast(did, &ed_pub, &x25519_pub);
+        let encoded = encode_identity_broadcast(&expected_did, &ed_pub, &x25519_pub);

        let (parsed_did, parsed_ed, parsed_x) = parse_identity_broadcast(&encoded)
            .ok_or_else(|| anyhow::anyhow!("failed to parse identity broadcast"))?;
-        assert_eq!(parsed_did, did);
+        assert_eq!(parsed_did, expected_did);
        assert_eq!(parsed_ed, ed_pub);
        assert_eq!(parsed_x, x25519_pub);
        Ok(())
@@ -1,6 +1,8 @@
 use crate::api::ApiHandler;
 use crate::config::{Config, ContainerRuntime};
-use crate::container::{docker_packages, DockerPackageScanner};
+use crate::container::{
+    docker_packages, ContainerOrchestrator, DevContainerOrchestrator, DockerPackageScanner,
+};
 use crate::identity::{self, NodeIdentity};
 use crate::monitoring::MetricsStore;
 use crate::node_message;
@@ -14,7 +16,7 @@ use hyper::service::service_fn;
 use std::collections::HashMap;
 use std::net::SocketAddr;
 use std::sync::Arc;
-use std::time::Duration;
+use std::time::{Duration, Instant};
 use tokio::net::TcpListener;
 use tracing::{debug, error, info, warn};

@@ -26,7 +28,11 @@ pub struct Server {
 }

 impl Server {
-    pub async fn new(config: Config) -> Result<Self> {
+    pub async fn new(
+        config: Config,
+        orchestrator: Option<Arc<dyn ContainerOrchestrator>>,
+        dev_orchestrator: Option<Arc<DevContainerOrchestrator>>,
+    ) -> Result<Self> {
        let state_manager = Arc::new(StateManager::new());

        // Load node identity and set stable server_info.
@@ -89,22 +95,32 @@ impl Server {
        // Load persisted messages (Archipelago channel)
        node_message::init(&config.data_dir).await;

-        // Auto-create default identity if none exist (fresh boot or factory reset)
+        // Auto-create the Node identity on fresh boot, mirroring the node's
+        // own signing key (seed-derived when onboarded, random otherwise).
+        // This keeps the DID shown on the Identities page, the DID Status
+        // card, and the DID used for peer-to-peer connects all aligned on
+        // one value — the seed-derived node DID. Idempotent: if the entry
+        // already exists from a prior boot, create_from_signing_key returns
+        // the existing record unchanged.
        {
            let im = crate::identity_manager::IdentityManager::new(&config.data_dir).await;
            if let Ok(mgr) = im {
                if let Ok((list, _)) = mgr.list().await {
                    if list.is_empty() {
+                        let signing_key = ed25519_dalek::SigningKey::from_bytes(
+                            &identity.signing_key().to_bytes(),
+                        );
                        match mgr
-                            .create(
-                                "Default".to_string(),
+                            .create_from_signing_key(
+                                "Node".to_string(),
                                crate::identity_manager::IdentityPurpose::Personal,
+                                signing_key,
                            )
                            .await
                        {
                            Ok(record) => {
                                let _ = mgr.create_nostr_key(&record.id).await;
-                                tracing::info!(did = %record.did, "Auto-created default identity with Nostr key");
+                                tracing::info!(did = %record.did, "Auto-created Node identity mirroring node key");
                            }
                            Err(e) => tracing::debug!("Auto-identity creation (non-fatal): {}", e),
                        }
@@ -162,8 +178,16 @@ impl Server {
            Some(config.data_dir.clone()),
        );

-        let api_handler =
-            Arc::new(ApiHandler::new(config.clone(), state_manager.clone(), metrics_store).await?);
+        let api_handler = Arc::new(
+            ApiHandler::new(
+                config.clone(),
+                state_manager.clone(),
+                metrics_store,
+                orchestrator,
+                dev_orchestrator,
+            )
+            .await?,
+        );

        // Initialize mesh networking service (if config has enabled: true)
        {
@@ -289,6 +313,8 @@ impl Server {
            let scanner = create_docker_scanner(&config).await?;
            let state = state_manager.clone();
            let identity_clone = identity.clone();
+            let scan_kick = api_handler.rpc_handler().scan_kick();
+            let scan_tick = api_handler.rpc_handler().scan_tick();

            // Initial scan (delayed to let crash recovery finish first)
            tokio::spawn(async move {
@@ -298,18 +324,31 @@ impl Server {
                // Tracks how many consecutive scans each container has been absent from.
                // Prevents UI flapping when podman intermittently returns incomplete results.
                let mut absence_tracker: HashMap<String, u32> = HashMap::new();
+                // Tracks when each container first entered a transitional state
+                // (Stopping / Starting / Restarting / ...). Used by the merge
+                // loop below to ignore podman's live state during a pending
+                // lifecycle op, and to break out if the spawned task dies
+                // without ever writing a final state.
+                let mut transitional_since: HashMap<String, Instant> = HashMap::new();
                if let Err(e) = scan_and_update_packages(
                    &scanner,
                    &state,
                    identity_clone.as_ref(),
                    &mut absence_tracker,
+                    &mut transitional_since,
                )
                .await
                {
                    error!("Failed to scan containers: {}", e);
                }
+                // Bump the scan-completion counter so any caller waiting on a
+                // kicked scan (install/update success path) can proceed.
+                scan_tick.send_modify(|n| *n = n.wrapping_add(1));

-                // Periodic scan every 60 seconds (only broadcasts if state changed)
+                // Periodic scan every 60 seconds (only broadcasts if state changed).
+                // Also wakes immediately when `scan_kick` fires — install/update
+                // success paths poke it so the fresh manifest (with populated
+                // interfaces) lands before they flip state to Running.
                // Uses an in-flight guard to skip scans when a previous one is still running
                let mut interval = tokio::time::interval(Duration::from_secs(60));
                // Skip missed ticks instead of catching up — prevents burst of scans
@@ -317,7 +356,12 @@ impl Server {
                interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
                let scanning = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
                loop {
-                    interval.tick().await;
+                    tokio::select! {
+                        _ = interval.tick() => {}
+                        _ = scan_kick.notified() => {
+                            debug!("Scan kicked by install/update success — running immediately");
+                        }
+                    }
                    if scanning.load(std::sync::atomic::Ordering::Relaxed) {
                        debug!("Skipping container scan — previous scan still in progress");
                        continue;
@@ -328,11 +372,13 @@ impl Server {
                        &state,
                        identity_clone.as_ref(),
                        &mut absence_tracker,
+                        &mut transitional_since,
                    )
                    .await
                    {
                        error!("Failed to update containers: {}", e);
                    }
+                    scan_tick.send_modify(|n| *n = n.wrapping_add(1));
                    scanning.store(false, std::sync::atomic::Ordering::Relaxed);
                }
            });
@@ -785,11 +831,65 @@ async fn refresh_tor_address(state: &StateManager, identity: &NodeIdentity) -> R
 /// 3 scans × 30s = 90 seconds of absence before removal.
 const CONTAINER_ABSENCE_THRESHOLD: u32 = 3;

+/// Maximum time a package entry may remain stuck in a transitional state
+/// before the scan loop overrides it with podman's live state.
+///
+/// Rationale: the longest single-container stop timeout is bitcoin-core at
+/// 600s. 2× that gives the spawned task ample margin before we assume it
+/// died (panic, OOM, process restart mid-stop) and fall back to the
+/// scanner's authoritative view. Applies to all transitional variants.
+const TRANSITIONAL_STUCK_TIMEOUT: Duration = Duration::from_secs(1200);
+
+/// Returns true if `state` is one of the transitional variants that a
+/// `spawn_transitional`-style background task owns. While such a state is
+/// set, the package scanner must not overwrite it with whatever podman
+/// reports (see `merge_preserving_transitional`).
+fn is_transitional(state: &crate::data_model::PackageState) -> bool {
+    use crate::data_model::PackageState::*;
+    matches!(
+        state,
+        Installing
+            | Stopping
+            | Starting
+            | Restarting
+            | Updating
+            | Removing
+            | CreatingBackup
+            | RestoringBackup
+            | BackingUp
+    )
+}
+
+/// Merge a fresh scan entry `fresh` into `existing` while preserving
+/// `existing.state` (which is transitional — the RPC spawn task owns it).
+/// Non-state observability fields are taken from `fresh` so the UI still
+/// sees live health / exit_code / lan_address readings during a transition.
+fn merge_preserving_transitional(
+    existing: &crate::data_model::PackageDataEntry,
+    fresh: &crate::data_model::PackageDataEntry,
+) -> crate::data_model::PackageDataEntry {
+    crate::data_model::PackageDataEntry {
+        state: existing.state.clone(),
+        // install_progress and uninstall_stage are also owned by the
+        // initiating op (same reason as state) — keep them.
+        install_progress: existing.install_progress.clone(),
+        uninstall_stage: existing.uninstall_stage.clone(),
+        // Everything else comes from the fresh scan.
+        health: fresh.health.clone(),
+        exit_code: fresh.exit_code,
+        static_files: fresh.static_files.clone(),
+        manifest: fresh.manifest.clone(),
+        installed: fresh.installed.clone(),
+        available_update: fresh.available_update.clone(),
+    }
+}
+
 async fn scan_and_update_packages(
    scanner: &DockerPackageScanner,
    state: &StateManager,
    identity: &NodeIdentity,
    absence_tracker: &mut HashMap<String, u32>,
+    transitional_since: &mut HashMap<String, Instant>,
 ) -> Result<()> {
    let packages = scanner.scan_containers().await?;

@@ -823,10 +923,61 @@ async fn scan_and_update_packages(
    let mut merged = current_data.package_data.clone();
    let mut changed = false;

-    // Update/add containers found in this scan
+    // Update/add containers found in this scan.
+    //
+    // Transitional states (Stopping, Starting, Restarting, Installing,
+    // Updating, Removing, backup variants) are owned by the RPC spawn_task
+    // that initiated the operation — podman's live state during the op is
+    // meaningless ("running" during a graceful stop, "exited" during a
+    // restart, etc.) and must not be written back. See
+    // `merge_preserving_transitional` for the exact rule.
+    //
+    // Escape hatch: if a package has been in a transitional state for
+    // longer than TRANSITIONAL_STUCK_TIMEOUT we assume the spawned task
+    // died without cleanup and let the scan override it.
+    let now = Instant::now();
    for (id, pkg) in &packages {
        absence_tracker.remove(id);
-        if merged.get(id) != Some(pkg) {
+        let existing = merged.get(id);
+        let overwrite = match existing {
+            Some(existing_entry) if is_transitional(&existing_entry.state) => {
+                let entered = *transitional_since.entry(id.clone()).or_insert(now);
+                let stuck = now.duration_since(entered) > TRANSITIONAL_STUCK_TIMEOUT;
+                if stuck {
+                    warn!(
+                        "Container {} stuck in {:?} for >{}s; overriding with scan state {:?}",
+                        id,
+                        existing_entry.state,
+                        TRANSITIONAL_STUCK_TIMEOUT.as_secs(),
+                        pkg.state
+                    );
+                    transitional_since.remove(id);
+                    true
+                } else {
+                    // Keep existing transitional state, but merge non-state
+                    // observability fields (health, exit_code, lan_address
+                    // via installed) from the fresh scan so the UI still
+                    // sees live readings.
+                    let merged_entry = merge_preserving_transitional(existing_entry, pkg);
+                    if existing.cloned() != Some(merged_entry.clone()) {
+                        merged.insert(id.clone(), merged_entry);
+                        changed = true;
+                    }
+                    false
+                }
+            }
+            Some(_) => {
+                // Not transitional: the side-table may hold a stale entry
+                // from a previous transition on this id; drop it.
+                transitional_since.remove(id);
+                existing != Some(pkg)
+            }
+            None => {
+                transitional_since.remove(id);
+                true
+            }
+        };
+        if overwrite && merged.get(id) != Some(pkg) {
            merged.insert(id.clone(), pkg.clone());
            changed = true;
        }
@@ -846,6 +997,7 @@ async fn scan_and_update_packages(
                );
                merged.remove(&id);
                absence_tracker.remove(&id);
+                transitional_since.remove(&id);
                changed = true;
            }
        }
@@ -933,3 +1085,112 @@ async fn check_peer_health(state: &StateManager, data_dir: &std::path::Path) ->

    Ok(())
 }
+
+#[cfg(test)]
+mod merge_tests {
+    use super::*;
+    use crate::data_model::{
+        Description, Manifest, PackageDataEntry, PackageState, StaticFiles,
+    };
+
+    fn make_manifest() -> Manifest {
+        Manifest {
+            id: "lnd".to_string(),
+            title: "LND".to_string(),
+            version: "0.18.4".to_string(),
+            description: Description {
+                short: "".to_string(),
+                long: "".to_string(),
+            },
+            release_notes: "".to_string(),
+            license: "".to_string(),
+            wrapper_repo: "".to_string(),
+            upstream_repo: "".to_string(),
+            support_site: "".to_string(),
+            marketing_site: "".to_string(),
+            donation_url: None,
+            author: None,
+            website: None,
+            interfaces: None,
+            tier: None,
+        }
+    }
+
+    fn make_static() -> StaticFiles {
+        StaticFiles {
+            license: "".to_string(),
+            instructions: "".to_string(),
+            icon: "".to_string(),
+        }
+    }
+
+    fn make_entry(state: PackageState, health: Option<&str>) -> PackageDataEntry {
+        PackageDataEntry {
+            state,
+            health: health.map(|s| s.to_string()),
+            exit_code: None,
+            static_files: make_static(),
+            manifest: make_manifest(),
+            installed: None,
+            install_progress: None,
+            uninstall_stage: None,
+            available_update: None,
+        }
+    }
+
+    #[test]
+    fn preserves_transitional_state_on_merge() {
+        // existing: user initiated a stop, spawn_transitional set Stopping.
+        // fresh: podman hasn't finished the stop yet, still reports Running.
+        // Expected: merged state stays Stopping — podman's live view must
+        // not clobber the transitional state owned by the RPC spawn task.
+        let existing = make_entry(PackageState::Stopping, Some("healthy"));
+        let fresh = make_entry(PackageState::Running, Some("starting"));
+        let merged = merge_preserving_transitional(&existing, &fresh);
+        assert_eq!(merged.state, PackageState::Stopping);
+    }
+
+    #[test]
+    fn merges_fresh_observability_fields() {
+        // Non-state observability fields (health, exit_code, installed)
+        // MUST come from the fresh scan even while state is preserved —
+        // the UI still shows live health/health during a transition.
+        let mut existing = make_entry(PackageState::Stopping, Some("healthy"));
+        existing.exit_code = None;
+        let mut fresh = make_entry(PackageState::Running, Some("unhealthy"));
+        fresh.exit_code = Some(0);
+        let merged = merge_preserving_transitional(&existing, &fresh);
+        assert_eq!(merged.state, PackageState::Stopping);
+        assert_eq!(merged.health.as_deref(), Some("unhealthy"));
+        assert_eq!(merged.exit_code, Some(0));
+    }
+
+    #[test]
+    fn is_transitional_covers_all_variants() {
+        for s in [
+            PackageState::Installing,
+            PackageState::Stopping,
+            PackageState::Starting,
+            PackageState::Restarting,
+            PackageState::Updating,
+            PackageState::Removing,
+            PackageState::CreatingBackup,
+            PackageState::RestoringBackup,
+            PackageState::BackingUp,
+        ] {
+            assert!(is_transitional(&s), "{:?} should be transitional", s);
+        }
+        for s in [
+            PackageState::Installed,
+            PackageState::Stopped,
+            PackageState::Exited,
+            PackageState::Running,
+        ] {
+            assert!(
+                !is_transitional(&s),
+                "{:?} should NOT be transitional",
+                s
+            );
+        }
+    }
+}
@@ -70,6 +70,17 @@ impl SessionStore {
        }
    }

+    /// Construct an empty SessionStore that persists to a caller-supplied
+    /// path. Used by tests so they don't pick up sessions from the dev
+    /// machine's real /var/lib/archipelago/sessions.json.
+    #[cfg(test)]
+    pub fn new_for_tests(persist_path: PathBuf) -> Self {
+        Self {
+            sessions: Arc::new(RwLock::new(HashMap::new())),
+            persist_path,
+        }
+    }
+
    /// Load persisted sessions from disk (only Full sessions).
    async fn load_from_disk(path: &Path) -> HashMap<[u8; 32], Session> {
        let mut map = HashMap::new();
@@ -462,7 +473,7 @@ mod tests {

    #[tokio::test]
    async fn test_session_create_and_validate() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", rand::random::<u64>())));
        let token = store.create().await;

        assert!(store.validate(&token).await);
@@ -470,13 +481,13 @@ mod tests {

    #[tokio::test]
    async fn test_session_invalid_token() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", rand::random::<u64>())));
        assert!(!store.validate("nonexistent_token").await);
    }

    #[tokio::test]
    async fn test_session_remove() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", rand::random::<u64>())));
        let token = store.create().await;

        assert!(store.validate(&token).await);
@@ -486,7 +497,7 @@ mod tests {

    #[tokio::test]
    async fn test_pending_session_upgrade() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", rand::random::<u64>())));
        let secret = vec![1, 2, 3, 4];
        let token = store.create_pending(secret.clone()).await;

@@ -510,7 +521,7 @@ mod tests {

    #[tokio::test]
    async fn test_pending_session_max_attempts() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", rand::random::<u64>())));
        let secret = vec![1, 2, 3];
        let token = store.create_pending(secret).await;

@@ -538,7 +549,7 @@ mod tests {

    #[tokio::test]
    async fn test_session_activity_updates_on_validate() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", rand::random::<u64>())));
        let token = store.create().await;

        // First validation should succeed and touch last_activity
@@ -550,7 +561,7 @@ mod tests {

    #[tokio::test]
    async fn test_invalidate_all_except() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", rand::random::<u64>())));
        let token1 = store.create().await;
        let token2 = store.create().await;
        let token3 = store.create().await;
@@ -565,7 +576,7 @@ mod tests {

    #[tokio::test]
    async fn test_session_rotate() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", rand::random::<u64>())));
        let old_token = store.create().await;

        assert!(store.validate(&old_token).await);
@@ -580,7 +591,7 @@ mod tests {

    #[tokio::test]
    async fn test_max_concurrent_sessions() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", rand::random::<u64>())));
        let mut tokens = Vec::new();

        // Create MAX_CONCURRENT_SESSIONS sessions
@@ -608,7 +619,7 @@ mod tests {

    #[tokio::test]
    async fn test_active_session_count() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", rand::random::<u64>())));
        assert_eq!(store.active_session_count().await, 0);

        let token1 = store.create().await;
@@ -623,7 +634,7 @@ mod tests {

    #[tokio::test]
    async fn test_cleanup_expired_removes_stale() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", rand::random::<u64>())));
        let token = store.create().await;

        assert!(store.validate(&token).await);
@@ -636,7 +647,7 @@ mod tests {

    #[tokio::test]
    async fn test_rotate_preserves_session_count() {
-        let store = SessionStore::new().await;
+        let store = SessionStore::new_for_tests(std::env::temp_dir().join(format!("archipelago-sessions-test-{}.json", rand::random::<u64>())));
        let token = store.create().await;
        assert_eq!(store.active_session_count().await, 1);

@@ -98,7 +98,12 @@ pub fn encode_chunked(data: &[u8]) -> Result<Vec<Chunk>> {
    }

    let shard_size = MAX_CHUNK_PAYLOAD;
-    let data_shard_count = data.len().div_ceil(shard_size);
+    // Reserve the first 4 bytes of shard 0 for a length header so the
+    // receiver can trim padding after FEC reconstruction. Effective
+    // payload capacity is therefore (shards * shard_size) - 4.
+    const LEN_HEADER: usize = 4;
+    let total_payload = data.len() + LEN_HEADER;
+    let data_shard_count = total_payload.div_ceil(shard_size);

    if data_shard_count > MAX_PRACTICAL_CHUNKS {
        anyhow::bail!(
@@ -116,22 +121,25 @@ pub fn encode_chunked(data: &[u8]) -> Result<Vec<Chunk>> {
        anyhow::bail!("Too many shards: {}", total_shards);
    }

-    // Split data into equal-size shards
+    // Build a single contiguous buffer: [len_u32_le][data...][zero_padding]
+    // then split into equal-size shards.
+    let buffer_size = data_shard_count * shard_size;
+    let mut buffer = vec![0u8; buffer_size];
+    buffer[..LEN_HEADER].copy_from_slice(&(data.len() as u32).to_le_bytes());
+    buffer[LEN_HEADER..LEN_HEADER + data.len()].copy_from_slice(data);
+
    let mut shards: Vec<Vec<u8>> = Vec::with_capacity(total_shards);
    for i in 0..data_shard_count {
        let start = i * shard_size;
-        let end = (start + shard_size).min(data.len());
-        let mut shard = vec![0u8; shard_size];
-        shard[..end - start].copy_from_slice(&data[start..end]);
-        shards.push(shard);
+        shards.push(buffer[start..start + shard_size].to_vec());
    }
-
-    // Add empty parity shards
+    // Empty parity shards
    for _ in 0..parity_shard_count {
        shards.push(vec![0u8; shard_size]);
    }

-    // Generate parity
+    // Generate parity over the data shards (which now correctly include
+    // the length header in shard 0).
    let rs = ReedSolomon::new(data_shard_count, parity_shard_count)
        .context("Failed to create Reed-Solomon codec")?;
    rs.encode(&mut shards)
@@ -152,18 +160,6 @@ pub fn encode_chunked(data: &[u8]) -> Result<Vec<Chunk>> {
        });
    }

-    // Encode the original data length in the first chunk's first 4 bytes
-    // so the receiver can trim padding after reconstruction.
-    let data_len = data.len() as u32;
-    chunks[0].payload[..4].copy_from_slice(&data_len.to_le_bytes());
-    // Re-encode FEC to reflect the length header change
-    let mut shard_data: Vec<Vec<u8>> = chunks.iter().map(|c| c.payload.clone()).collect();
-    rs.encode(&mut shard_data)
-        .context("Reed-Solomon re-encoding failed")?;
-    for (i, shard) in shard_data.into_iter().enumerate() {
-        chunks[i].payload = shard;
-    }
-
    Ok(chunks)
 }

@@ -318,17 +314,13 @@ mod tests {

    #[test]
    fn test_chunk_roundtrip_medium() {
-        // ~500 bytes: 4 data chunks + 1 parity
+        // 500 bytes payload + 4-byte length header = 504 bytes.
+        // ceil(504 / 124) = 5 data shards, plus ceil(5/4) = 2 parity = 7 total.
        let data: Vec<u8> = (0..500).map(|i| (i % 256) as u8).collect();
        let chunks = encode_chunked(&data).unwrap();

        let data_chunks: Vec<_> = chunks.iter().filter(|c| !c.is_parity).collect();
-        let _parity_chunks: Vec<_> = chunks.iter().filter(|c| c.is_parity).collect();
-        assert_eq!(data_chunks.len(), 4); // ceil(500/124) = 5... wait
-                                          // Actually: ceil(500/124) = ceil(4.03) = 5 data shards
-                                          // But the first shard has 4 bytes of length header embedded, so
-                                          // the actual data capacity is 124 * N - 0 (length is IN the shard data).
-                                          // Let's just check it roundtrips.
+        assert_eq!(data_chunks.len(), 5);

        let mut reassembler = ChunkReassembler::new();
        let mut result = None;
@@ -160,6 +160,18 @@ impl LanTransport {
    }
 }

+impl Drop for LanTransport {
+    // The mdns_sd daemon runs on its own OS thread and the browse
+    // listener task blocks on a sync channel. Without this call both
+    // keep the process alive past SIGTERM, long enough for systemd to
+    // SIGKILL us — which makes a normal update look like a crash.
+    fn drop(&mut self) {
+        if let Some(daemon) = self.daemon.take() {
+            let _ = daemon.shutdown();
+        }
+    }
+}
+
 impl NodeTransport for LanTransport {
    fn kind(&self) -> TransportKind {
        TransportKind::Lan
@@ -63,13 +63,31 @@ fn is_newer(candidate: &str, current: &str) -> bool {

 const DEFAULT_UPDATE_MANIFEST_URL: &str =
    "https://git.tx1138.com/lfg2025/archy/raw/branch/main/releases/manifest.json";
-/// Secondary mirror: same manifest, served from the VPS. Added as a
-/// default mirror so nodes automatically fall through when the primary
-/// is slow or unreachable.
+/// Secondary mirror on an OVH VPS — independent network path so a
+/// single-provider outage doesn't knock out both mirrors. Promoted to
+/// primary default on 2026-04-23 after the Hetzner .160 VPS was
+/// decommissioned.
 const DEFAULT_SECONDARY_MIRROR_URL: &str =
-    "http://23.182.128.160:3000/lfg2025/archy/raw/branch/main/releases/manifest.json";
+    "http://146.59.87.168:3000/lfg2025/archy/raw/branch/main/releases/manifest.json";
 const UPDATE_STATE_FILE: &str = "update_state.json";
 const UPDATE_MIRRORS_FILE: &str = "update-mirrors.json";
+/// Marker written by apply_update() just before the service restart and
+/// consumed by verify_pending_update() in the NEW binary's startup path.
+/// If present, the new binary probes the frontend; if the probe fails,
+/// rollback_update() runs and the service restarts on the old binary.
+/// Closes the "OTA broke nginx fleet-wide with no auto-rollback" failure
+/// mode from 2026-04-22 (v1.7.38/39 tarball-perms bug).
+const PENDING_VERIFY_FILE: &str = "update-pending-verify.json";
+/// Probe timeout for the frontend health check (total time including
+/// retries). Generous: the new binary has to come fully up, health
+/// monitor settles, nginx has to re-read any snippet changes. 90s is
+/// comfortably longer than the slowest observed startup.
+const PENDING_VERIFY_WINDOW_SECS: u64 = 90;
+/// If the marker is older than this on read, treat it as stale and
+/// delete without probing. Guards against a node that somehow failed
+/// to run verification at all (e.g. crashed during startup) from
+/// spontaneously rolling back days later when the user reboots.
+const PENDING_VERIFY_MAX_AGE_SECS: i64 = 600;

 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 pub struct UpdateMirror {
@@ -91,7 +109,7 @@ fn default_mirrors() -> Vec<UpdateMirror> {
    vec![
        UpdateMirror {
            url: DEFAULT_SECONDARY_MIRROR_URL.to_string(),
-            label: "Server 1 (VPS)".to_string(),
+            label: "Server 1 (OVH)".to_string(),
        },
        UpdateMirror {
            url: DEFAULT_UPDATE_MANIFEST_URL.to_string(),
@@ -102,8 +120,15 @@ fn default_mirrors() -> Vec<UpdateMirror> {

 /// Load the operator-configured mirror list. Returns defaults if the
 /// file doesn't exist yet, so a node OTA'd from a pre-mirrors release
-/// starts with both Server 1 and Server 2 available without any manual
-/// config.
+/// starts with the current default mirrors available without any
+/// manual config.
+///
+/// Migration: any default mirror URL that isn't already in the saved
+/// list gets appended at the end. This lets us add new default mirrors
+/// (e.g. a new Server 3) and have them appear on existing nodes after
+/// an update, without requiring manual config edits. Explicit removals
+/// stick — once an operator removes a URL it stays gone unless it's
+/// later re-added to defaults.
 pub async fn load_mirrors(data_dir: &Path) -> Result<Vec<UpdateMirror>> {
    let path = mirrors_path(data_dir);
    if !path.exists() {
@@ -112,13 +137,36 @@ pub async fn load_mirrors(data_dir: &Path) -> Result<Vec<UpdateMirror>> {
    let bytes = fs::read(&path)
        .await
        .with_context(|| format!("read {}", path.display()))?;
-    let list: Vec<UpdateMirror> =
+    let mut list: Vec<UpdateMirror> =
        serde_json::from_slice(&bytes).with_context(|| format!("parse {}", path.display()))?;
    if list.is_empty() {
-        Ok(default_mirrors())
-    } else {
-        Ok(list)
+        return Ok(default_mirrors());
    }
+
+    // One-time migration: the Hetzner VPS at 23.182.128.160 was
+    // decommissioned 2026-04-23. Existing nodes have it baked into their
+    // saved mirror list (was the original Server 1). Strip it on load so
+    // we don't spend seconds per install timing out against a dead host.
+    // Exception to the usual "explicit removals stick" rule: the user
+    // never chose to add this — it was a default.
+    let before = list.len();
+    list.retain(|m| !m.url.contains("23.182.128.160"));
+    let mut changed = list.len() != before;
+
+    // Merge in any default URLs the saved config is missing.
+    let known: std::collections::HashSet<String> =
+        list.iter().map(|m| m.url.clone()).collect();
+    let defaults = default_mirrors();
+    for def in &defaults {
+        if !known.contains(&def.url) {
+            list.push(def.clone());
+            changed = true;
+        }
+    }
+    if changed {
+        let _ = save_mirrors(data_dir, &list).await;
+    }
+    Ok(list)
 }

 pub async fn save_mirrors(data_dir: &Path, mirrors: &[UpdateMirror]) -> Result<()> {
@@ -239,6 +287,189 @@ impl Default for UpdateState {
    }
 }

+/// Marker written by apply_update() just before the service restart and
+/// consumed by verify_pending_update() in the NEW binary's startup path.
+/// See PENDING_VERIFY_FILE for the full rationale — this is the hook
+/// that turns "nginx 500 on every page after OTA" from an unrecoverable
+/// field incident into an automatic rollback.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PendingVerification {
+    /// RFC3339 timestamp of the apply that wrote this marker.
+    pub applied_at: String,
+    /// Version we just applied (what the NEW binary should be running).
+    pub new_version: String,
+    /// Version the outgoing binary was running (what we roll back to).
+    pub previous_version: String,
+    /// Unix epoch seconds after which the probe should give up and
+    /// trigger rollback. Prevents a probe from retrying forever if e.g.
+    /// nginx is totally wedged.
+    pub deadline_ts: i64,
+}
+
+async fn write_pending_verification(
+    data_dir: &Path,
+    marker: &PendingVerification,
+) -> Result<()> {
+    let path = data_dir.join(PENDING_VERIFY_FILE);
+    let data = serde_json::to_string_pretty(marker)
+        .context("serialize pending-verify marker")?;
+    fs::write(&path, data)
+        .await
+        .with_context(|| format!("write pending-verify marker to {}", path.display()))?;
+    Ok(())
+}
+
+async fn read_pending_verification(data_dir: &Path) -> Option<PendingVerification> {
+    let path = data_dir.join(PENDING_VERIFY_FILE);
+    let data = fs::read_to_string(&path).await.ok()?;
+    serde_json::from_str(&data).ok()
+}
+
+async fn clear_pending_verification(data_dir: &Path) {
+    let path = data_dir.join(PENDING_VERIFY_FILE);
+    let _ = fs::remove_file(&path).await;
+}
+
+/// Probe the local frontend through nginx. Returns Ok(()) on the first
+/// response that's 2xx or 3xx; errors on timeout / connection refused /
+/// any 4xx/5xx. `accept_self_signed` because nodes use a self-signed
+/// cert the reqwest default root-set doesn't trust.
+async fn probe_frontend_once() -> Result<()> {
+    let client = reqwest::Client::builder()
+        .danger_accept_invalid_certs(true)
+        .timeout(std::time::Duration::from_secs(5))
+        .build()
+        .context("build probe client")?;
+    // Prefer HTTPS since that's the failure mode we're catching (nginx
+    // 500 on the PWA). HTTP usually redirects to HTTPS and would mask
+    // the bug.
+    let resp = client
+        .get("https://127.0.0.1/")
+        .send()
+        .await
+        .context("probe GET https://127.0.0.1/")?;
+    let status = resp.status();
+    if status.is_success() || status.is_redirection() {
+        return Ok(());
+    }
+    anyhow::bail!("frontend probe returned HTTP {}", status);
+}
+
+/// Called from main.rs startup. If a pending-verification marker is
+/// present, probe the frontend; on failure, trigger rollback and
+/// restart the service so the OLD binary boots.
+///
+/// This is the "post-OTA auto-rollback" guardrail. If ANY problem in
+/// the new version takes down the PWA (bad tarball perms as in v1.7.38,
+/// a broken service worker, a missing asset, a backend panic on first
+/// boot), the node self-heals back to the previous working state
+/// without SSH intervention.
+pub async fn verify_pending_update(data_dir: &Path) {
+    let marker = match read_pending_verification(data_dir).await {
+        Some(m) => m,
+        None => return, // No update pending; nothing to verify.
+    };
+
+    // Guard against a marker left behind by some earlier crash path —
+    // don't want a user who reboots days later to suddenly get
+    // rolled back because the marker was never cleared.
+    let applied_at = chrono::DateTime::parse_from_rfc3339(&marker.applied_at);
+    if let Ok(ts) = applied_at {
+        let age = chrono::Utc::now() - ts.with_timezone(&chrono::Utc);
+        if age.num_seconds() > PENDING_VERIFY_MAX_AGE_SECS {
+            tracing::warn!(
+                age_secs = age.num_seconds(),
+                "pending-verify marker is stale, clearing without probing"
+            );
+            clear_pending_verification(data_dir).await;
+            return;
+        }
+    }
+
+    info!(
+        new_version = %marker.new_version,
+        previous_version = %marker.previous_version,
+        "Post-OTA verification: probing frontend at https://127.0.0.1/"
+    );
+
+    // Give the new service time to bind its listeners + nginx to
+    // pick up any config changes. 15s matches what we observed on
+    // .116 during the v1.7.40 rollout recovery.
+    tokio::time::sleep(std::time::Duration::from_secs(15)).await;
+
+    let deadline =
+        std::time::Instant::now() + std::time::Duration::from_secs(PENDING_VERIFY_WINDOW_SECS);
+    let mut attempt = 0u32;
+    let mut last_err: Option<String> = None;
+
+    while std::time::Instant::now() < deadline {
+        attempt += 1;
+        match probe_frontend_once().await {
+            Ok(()) => {
+                info!(
+                    attempt,
+                    "Post-OTA verification succeeded — clearing marker"
+                );
+                clear_pending_verification(data_dir).await;
+                return;
+            }
+            Err(e) => {
+                let msg = e.to_string();
+                tracing::warn!(attempt, error = %msg, "Post-OTA probe failed, retrying");
+                last_err = Some(msg);
+            }
+        }
+        tokio::time::sleep(std::time::Duration::from_secs(5)).await;
+    }
+
+    tracing::error!(
+        attempts = attempt,
+        window_secs = PENDING_VERIFY_WINDOW_SECS,
+        last_error = last_err.as_deref().unwrap_or(""),
+        new_version = %marker.new_version,
+        previous_version = %marker.previous_version,
+        "Post-OTA verification FAILED — rolling back"
+    );
+
+    // Restore web-ui.bak on top of web-ui. update.rs keeps web-ui.bak
+    // from the previous apply; moving it back is the frontend half of
+    // the rollback. The binary half is handled by rollback_update().
+    let web_ui_bak = Path::new("/opt/archipelago/web-ui.bak");
+    let web_ui = "/opt/archipelago/web-ui";
+    if web_ui_bak.exists() {
+        let ts = chrono::Utc::now().timestamp_millis();
+        let quarantine = format!("/opt/archipelago/web-ui.failed.{}", ts);
+        let _ = host_sudo(&["mv", web_ui, &quarantine]).await;
+        let _ = host_sudo(&["mv", web_ui_bak.to_str().unwrap_or(""), web_ui]).await;
+        tracing::info!(quarantined = %quarantine, "Restored web-ui from web-ui.bak");
+    } else {
+        tracing::warn!(
+            "web-ui.bak not present — frontend cannot be rolled back, only binary"
+        );
+    }
+
+    if let Err(e) = rollback_update(data_dir).await {
+        tracing::error!(error = %e, "rollback_update() failed during post-OTA verification");
+        // Leave the marker in place so a future boot gets another shot.
+        return;
+    }
+
+    clear_pending_verification(data_dir).await;
+
+    // Record why we rolled back so the UI can show it on the next boot.
+    if let Ok(mut state) = load_state(data_dir).await {
+        state.current_version = marker.previous_version.clone();
+        if let Err(e) = save_state(data_dir, &state).await {
+            tracing::warn!(error = %e, "Failed to update state after rollback");
+        }
+    }
+
+    // Restart so the old binary takes over. --no-block because we're
+    // the service; systemd can't wait for us to exit before starting
+    // the old process.
+    let _ = host_sudo(&["systemctl", "--no-block", "restart", "archipelago"]).await;
+}
+
 pub async fn load_state(data_dir: &Path) -> Result<UpdateState> {
    let path = data_dir.join(UPDATE_STATE_FILE);
    if !path.exists() {
@@ -763,7 +994,7 @@ pub async fn cancel_download(data_dir: &Path) -> Result<()> {
 /// though sudo itself is root. `systemd-run --wait` spawns a transient
 /// service unit that inherits systemd's default protections (i.e. none
 /// of ours), escaping the namespace.
-async fn host_sudo(args: &[&str]) -> Result<std::process::ExitStatus> {
+pub(crate) async fn host_sudo(args: &[&str]) -> Result<std::process::ExitStatus> {
    let mut full: Vec<&str> = vec![
        "systemd-run",
        "--wait",
@@ -885,6 +1116,21 @@ pub async fn apply_update(data_dir: &Path) -> Result<()> {
                ])
                .await;

+                // Set world-readable perms so nginx (runs as www-data)
+                // can stat + serve the files. Without this, the tar
+                // extraction inherits the staging-dir's 700 mode and
+                // nginx returns 403/500 for every request after the
+                // swap — exactly what bit .116 on the v1.7.38 rollout.
+                let _ = host_sudo(&["chmod", "755", &staging_new]).await;
+                let _ = host_sudo(&[
+                    "find", &staging_new, "-type", "d", "-exec", "chmod", "755", "{}", "+",
+                ])
+                .await;
+                let _ = host_sudo(&[
+                    "find", &staging_new, "-type", "f", "-exec", "chmod", "644", "{}", "+",
+                ])
+                .await;
+
                // Preserve paths that are installed outside the Vue build
                // (baked in by the ISO or sibling installers) and so
                // aren't in the new tarball. Without this copy, every OTA
@@ -941,15 +1187,42 @@ pub async fn apply_update(data_dir: &Path) -> Result<()> {
    }

    // Update state
+    let previous_version = {
+        let state = load_state(data_dir).await?;
+        state.current_version.clone()
+    };
    let mut state = load_state(data_dir).await?;
-    if let Some(manifest) = &state.available_update {
+    let new_version = if let Some(manifest) = &state.available_update {
        state.current_version = manifest.version.clone();
-    }
+        manifest.version.clone()
+    } else {
+        state.current_version.clone()
+    };
    state.available_update = None;
    state.update_in_progress = false;
    state.rollback_available = true;
    save_state(data_dir, &state).await?;

+    // Write the post-OTA verification marker BEFORE we schedule the
+    // restart. The new binary will read it on startup, probe the
+    // frontend, and auto-rollback if nginx is serving 5xx. Covers the
+    // class of failure where "apply succeeds, restart succeeds, but
+    // the UI is dead" (v1.7.38/39 tarball-perms bug). Best-effort —
+    // a failed marker write shouldn't abort the apply.
+    let marker = PendingVerification {
+        applied_at: chrono::Utc::now().to_rfc3339(),
+        new_version,
+        previous_version,
+        deadline_ts: chrono::Utc::now().timestamp()
+            + PENDING_VERIFY_WINDOW_SECS as i64
+            + 60,
+    };
+    if let Err(e) = write_pending_verification(data_dir, &marker).await {
+        tracing::warn!(error = %e, "Failed to write post-OTA verify marker — rollback disabled for this OTA");
+    } else {
+        info!("Post-OTA verify marker written; new binary will probe on boot");
+    }
+
    // Clean staging
    let _ = fs::remove_dir_all(&staging_dir).await;

@@ -979,9 +1252,24 @@ pub async fn rollback_update(data_dir: &Path) -> Result<()> {

    let backup_binary = backup_dir.join("archipelago");
    if backup_binary.exists() {
-        fs::copy(&backup_binary, "/usr/local/bin/archipelago")
+        // Use host_sudo + mv so we escape the archipelago service's
+        // ProtectSystem=strict mount namespace. A plain fs::copy or
+        // `sudo cp` from inside the service hits EROFS on /usr/local/bin,
+        // which would silently orphan the rollback — exactly the
+        // opposite of what auto-rollback is for. Pattern matches
+        // apply_update()'s binary swap above.
+        let backup_str = backup_binary.to_string_lossy().to_string();
+        let _ = host_sudo(&["chmod", "0755", &backup_str]).await;
+        let _ = host_sudo(&["chown", "root:root", &backup_str]).await;
+        let status = host_sudo(&["cp", &backup_str, "/usr/local/bin/archipelago"])
            .await
-            .context("Failed to restore backup binary")?;
+            .context("Failed to restore backup binary via host_sudo")?;
+        if !status.success() {
+            anyhow::bail!(
+                "cp backup binary into /usr/local/bin failed (exit {:?})",
+                status.code()
+            );
+        }
        info!("Binary rolled back to previous version");
    }

@@ -1188,8 +1476,8 @@ mod tests {
        let dir = tempfile::tempdir().unwrap();
        let list = load_mirrors(dir.path()).await.unwrap();
        assert_eq!(list.len(), 2);
-        assert!(list[0].url.contains("git.tx1138.com"));
-        assert!(list[1].url.contains("23.182.128.160"));
+        assert!(list[0].url.contains("146.59.87.168"));
+        assert!(list[1].url.contains("git.tx1138.com"));
    }

    #[tokio::test]
@@ -1201,7 +1489,22 @@ mod tests {
        }];
        save_mirrors(dir.path(), &list).await.unwrap();
        let back = load_mirrors(dir.path()).await.unwrap();
-        assert_eq!(back, list);
+        // load_mirrors merges in any missing default mirrors so a node
+        // that explicitly added a single custom mirror still gets the
+        // built-in OVH + tx1138 fallbacks. The custom mirror is preserved.
+        assert!(
+            back.iter().any(|m| m.url == "https://example.com/m.json"),
+            "custom mirror should round-trip; got {:?}",
+            back
+        );
+        for def in default_mirrors() {
+            assert!(
+                back.iter().any(|m| m.url == def.url),
+                "default mirror {} should be present after load; got {:?}",
+                def.url,
+                back
+            );
+        }
    }

    #[test]
@@ -1404,4 +1707,45 @@ mod tests {
        assert_eq!(status.current_version, env!("CARGO_PKG_VERSION"));
        assert!(status.rollback_available);
    }
+
+    #[tokio::test]
+    async fn test_pending_verification_round_trip() {
+        let dir = tempfile::tempdir().unwrap();
+        let marker = PendingVerification {
+            applied_at: chrono::Utc::now().to_rfc3339(),
+            new_version: "1.7.41-alpha".into(),
+            previous_version: "1.7.40-alpha".into(),
+            deadline_ts: chrono::Utc::now().timestamp() + 150,
+        };
+        write_pending_verification(dir.path(), &marker).await.unwrap();
+        let read = read_pending_verification(dir.path()).await.unwrap();
+        assert_eq!(read.new_version, "1.7.41-alpha");
+        assert_eq!(read.previous_version, "1.7.40-alpha");
+        clear_pending_verification(dir.path()).await;
+        assert!(read_pending_verification(dir.path()).await.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_pending_verification_absent_is_none() {
+        let dir = tempfile::tempdir().unwrap();
+        assert!(read_pending_verification(dir.path()).await.is_none());
+    }
+
+    #[tokio::test]
+    async fn test_verify_pending_update_noop_without_marker() {
+        let dir = tempfile::tempdir().unwrap();
+        // No marker written -- must return quickly without doing anything
+        // risky (network probes, rollback calls). We're just asserting
+        // it doesn't panic or hang.
+        verify_pending_update(dir.path()).await;
+    }
+
+    #[test]
+    fn test_pending_verify_constants_are_sensible() {
+        // Window must be generous enough for nginx + backend startup,
+        // but less than the stale-marker threshold so a normal cycle
+        // can complete without the marker being considered stale.
+        assert!(PENDING_VERIFY_WINDOW_SECS < PENDING_VERIFY_MAX_AGE_SECS as u64);
+        assert!(PENDING_VERIFY_WINDOW_SECS >= 60);
+    }
 }
@@ -334,7 +334,9 @@ mod tests {
            amount: 1,
            id: "test".into(),
            secret: "s".into(),
-            c: "02a9acc1e48c25eeeb9289b5031cc57da9fe72f3fe2861d94ec4da0e7f6c2b4e24".to_string(),
+            // Generator point G of secp256k1, compressed form. Always a
+            // valid pubkey, so c_as_pubkey() must succeed.
+            c: "0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798".to_string(),
        };
        assert!(proof.c_as_pubkey().is_ok());
    }
@@ -213,9 +213,10 @@ mod tests {
                version: "1.0.0".to_string(),
                description: None,
                container: ContainerConfig {
-                    image: format!("test/{}:latest", id),
+                    image: Some(format!("test/{}:latest", id)),
                    image_signature: None,
                    pull_policy: "if-not-present".to_string(),
+                    build: None,
                },
                dependencies: deps,
                resources: Default::default(),
@@ -9,7 +9,10 @@ pub mod runtime;
 pub use bitcoin_simulator::{BitcoinSimulationMode, BitcoinSimulator};
 pub use dependency_resolver::DependencyResolver;
 pub use health_monitor::HealthMonitor;
-pub use manifest::{AppManifest, Dependency, HealthCheck, ResourceLimits, SecurityPolicy};
+pub use manifest::{
+    AppManifest, BuildConfig, Dependency, HealthCheck, ResolvedSource, ResourceLimits,
+    SecurityPolicy,
+};
 pub use podman_client::{ContainerState, ContainerStatus, PodmanClient};
 pub use port_manager::{PortError, PortManager};
 pub use runtime::{AutoRuntime, ContainerRuntime, DockerRuntime, PodmanRuntime};
@@ -57,17 +57,60 @@ pub struct AppDefinition {

 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
 pub struct ContainerConfig {
-    pub image: String,
+    /// Pull source. Mutually exclusive with `build`. Exactly one of the two must be present.
+    #[serde(default)]
+    pub image: Option<String>,
    #[serde(default)]
    pub image_signature: Option<String>,
    #[serde(default = "default_pull_policy")]
    pub pull_policy: String,
+    /// Local build source. Mutually exclusive with `image`.
+    #[serde(default)]
+    pub build: Option<BuildConfig>,
 }

 fn default_pull_policy() -> String {
    "if-not-present".to_string()
 }

+/// Build a container image locally from a Dockerfile rather than pulling from a registry.
+///
+/// When present on `ContainerConfig`, the orchestrator runs `podman build -t <tag> -f <dockerfile> <context>`
+/// before starting the container. The resulting local image is referenced by `tag`.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct BuildConfig {
+    /// Build context directory (absolute path or relative to the manifest location).
+    pub context: String,
+    /// Dockerfile path relative to `context`. Defaults to `Dockerfile`.
+    #[serde(default = "default_dockerfile")]
+    pub dockerfile: String,
+    /// Tag applied to the built image. Used as the container's image reference.
+    pub tag: String,
+    /// Optional `--build-arg KEY=VALUE` pairs passed to the build.
+    #[serde(default)]
+    pub build_args: HashMap<String, String>,
+}
+
+fn default_dockerfile() -> String {
+    "Dockerfile".to_string()
+}
+
+/// Resolved pull-or-build decision after manifest validation.
+///
+/// `ContainerConfig::resolve()` produces this. The orchestrator matches on it
+/// to decide whether to pull a registry image or invoke a local build.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ResolvedSource {
+    /// Pull `image` from a registry using `pull_policy` semantics.
+    Pull {
+        image: String,
+        pull_policy: String,
+        image_signature: Option<String>,
+    },
+    /// Build locally. The resulting tag is the image reference for `podman create`.
+    Build(BuildConfig),
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(untagged)]
 pub enum Dependency {
@@ -182,10 +225,33 @@ impl AppManifest {
            return Err(ManifestError::Invalid("app.id cannot be empty".to_string()));
        }

-        if self.app.container.image.is_empty() {
-            return Err(ManifestError::Invalid(
-                "container.image cannot be empty".to_string(),
-            ));
+        // Exactly one of container.image or container.build must be set. We can't
+        // default either side, because an empty-string image or an empty build block
+        // would be silently wrong downstream.
+        match (&self.app.container.image, &self.app.container.build) {
+            (Some(img), None) if !img.is_empty() => {}
+            (None, Some(b)) => {
+                if b.context.is_empty() {
+                    return Err(ManifestError::Invalid(
+                        "container.build.context cannot be empty".to_string(),
+                    ));
+                }
+                if b.tag.is_empty() {
+                    return Err(ManifestError::Invalid(
+                        "container.build.tag cannot be empty".to_string(),
+                    ));
+                }
+            }
+            (Some(_), Some(_)) => {
+                return Err(ManifestError::Invalid(
+                    "container.image and container.build are mutually exclusive".to_string(),
+                ));
+            }
+            _ => {
+                return Err(ManifestError::Invalid(
+                    "container must specify either image or build".to_string(),
+                ));
+            }
        }

        // Validate version format (semantic versioning)
@@ -199,6 +265,37 @@ impl AppManifest {
    }
 }

+impl ContainerConfig {
+    /// Collapse the (image, build) pair into a single resolved source.
+    ///
+    /// Returns `None` if the config is in an invalid state (e.g. neither field set
+    /// or both set). Callers should have already run `AppManifest::validate()` to
+    /// surface a user-facing error; this method is for internal orchestrator use
+    /// after validation has passed.
+    pub fn resolve(&self) -> Option<ResolvedSource> {
+        match (&self.image, &self.build) {
+            (Some(img), None) if !img.is_empty() => Some(ResolvedSource::Pull {
+                image: img.clone(),
+                pull_policy: self.pull_policy.clone(),
+                image_signature: self.image_signature.clone(),
+            }),
+            (None, Some(b)) => Some(ResolvedSource::Build(b.clone())),
+            _ => None,
+        }
+    }
+
+    /// The image reference used to create/inspect a container for this config.
+    ///
+    /// For Pull sources this is the registry image. For Build sources this is
+    /// the locally-built tag. Returns `None` only for an invalid config.
+    pub fn image_ref(&self) -> Option<String> {
+        self.resolve().map(|r| match r {
+            ResolvedSource::Pull { image, .. } => image,
+            ResolvedSource::Build(b) => b.tag,
+        })
+    }
+}
+
 #[cfg(test)]
 mod tests {
    use super::*;
@@ -234,4 +331,196 @@ app:
        let result = AppManifest::parse(yaml);
        assert!(result.is_err());
    }
+
+    #[test]
+    fn pull_source_resolves_to_pull() {
+        let yaml = r#"
+app:
+  id: test-app
+  name: Test
+  version: 1.0.0
+  container:
+    image: docker.io/library/nginx:1.27
+    pull_policy: always
+"#;
+        let m = AppManifest::parse(yaml).unwrap();
+        let src = m.app.container.resolve().unwrap();
+        match src {
+            ResolvedSource::Pull {
+                image, pull_policy, ..
+            } => {
+                assert_eq!(image, "docker.io/library/nginx:1.27");
+                assert_eq!(pull_policy, "always");
+            }
+            _ => panic!("expected Pull"),
+        }
+        assert_eq!(
+            m.app.container.image_ref().as_deref(),
+            Some("docker.io/library/nginx:1.27")
+        );
+    }
+
+    #[test]
+    fn build_source_resolves_to_build() {
+        let yaml = r#"
+app:
+  id: bitcoin-ui
+  name: Bitcoin UI
+  version: 1.0.0
+  container:
+    build:
+      context: /opt/archipelago/docker/bitcoin-ui
+      dockerfile: Dockerfile
+      tag: archy-bitcoin-ui:local
+      build_args:
+        NGINX_VERSION: "1.27"
+"#;
+        let m = AppManifest::parse(yaml).unwrap();
+        let src = m.app.container.resolve().unwrap();
+        match src {
+            ResolvedSource::Build(b) => {
+                assert_eq!(b.context, "/opt/archipelago/docker/bitcoin-ui");
+                assert_eq!(b.dockerfile, "Dockerfile");
+                assert_eq!(b.tag, "archy-bitcoin-ui:local");
+                assert_eq!(b.build_args.get("NGINX_VERSION").unwrap(), "1.27");
+            }
+            _ => panic!("expected Build"),
+        }
+        assert_eq!(
+            m.app.container.image_ref().as_deref(),
+            Some("archy-bitcoin-ui:local")
+        );
+    }
+
+    #[test]
+    fn dockerfile_defaults_to_dockerfile() {
+        let yaml = r#"
+app:
+  id: x
+  name: X
+  version: 1.0.0
+  container:
+    build:
+      context: /tmp
+      tag: x:local
+"#;
+        let m = AppManifest::parse(yaml).unwrap();
+        match m.app.container.resolve().unwrap() {
+            ResolvedSource::Build(b) => assert_eq!(b.dockerfile, "Dockerfile"),
+            _ => unreachable!(),
+        }
+    }
+
+    #[test]
+    fn image_and_build_both_set_is_rejected() {
+        let yaml = r#"
+app:
+  id: x
+  name: X
+  version: 1.0.0
+  container:
+    image: foo:latest
+    build:
+      context: /tmp
+      tag: x:local
+"#;
+        let err = AppManifest::parse(yaml).unwrap_err();
+        let msg = format!("{err}");
+        assert!(
+            msg.contains("mutually exclusive"),
+            "unexpected error: {msg}"
+        );
+    }
+
+    #[test]
+    fn neither_image_nor_build_is_rejected() {
+        let yaml = r#"
+app:
+  id: x
+  name: X
+  version: 1.0.0
+  container: {}
+"#;
+        let err = AppManifest::parse(yaml).unwrap_err();
+        let msg = format!("{err}");
+        assert!(
+            msg.contains("either image or build"),
+            "unexpected error: {msg}"
+        );
+    }
+
+    #[test]
+    fn empty_image_string_is_rejected() {
+        let yaml = r#"
+app:
+  id: x
+  name: X
+  version: 1.0.0
+  container:
+    image: ""
+"#;
+        let err = AppManifest::parse(yaml).unwrap_err();
+        let msg = format!("{err}");
+        assert!(
+            msg.contains("either image or build"),
+            "unexpected error: {msg}"
+        );
+    }
+
+    #[test]
+    fn empty_build_context_is_rejected() {
+        let yaml = r#"
+app:
+  id: x
+  name: X
+  version: 1.0.0
+  container:
+    build:
+      context: ""
+      tag: x:local
+"#;
+        let err = AppManifest::parse(yaml).unwrap_err();
+        let msg = format!("{err}");
+        assert!(msg.contains("context"), "unexpected error: {msg}");
+    }
+
+    #[test]
+    fn empty_build_tag_is_rejected() {
+        let yaml = r#"
+app:
+  id: x
+  name: X
+  version: 1.0.0
+  container:
+    build:
+      context: /tmp
+      tag: ""
+"#;
+        let err = AppManifest::parse(yaml).unwrap_err();
+        let msg = format!("{err}");
+        assert!(msg.contains("tag"), "unexpected error: {msg}");
+    }
+
+    #[test]
+    fn existing_pull_only_manifests_still_parse() {
+        // Backwards-compat smoke: the shape every file in apps/*/manifest.yml uses today.
+        let yaml = r#"
+app:
+  id: legacy
+  name: Legacy App
+  version: 0.1.0
+  description: existing shape
+  container:
+    image: registry.example.com/legacy:1.2.3
+    image_signature: sha256:abc
+  ports:
+    - { host: 8080, container: 80 }
+"#;
+        let m = AppManifest::parse(yaml).unwrap();
+        assert_eq!(m.app.container.pull_policy, "if-not-present");
+        matches!(
+            m.app.container.resolve().unwrap(),
+            ResolvedSource::Pull { .. }
+        );
+    }
 }
@@ -306,9 +306,43 @@ impl PodmanClient {
        let cap_add: Vec<String> = manifest.app.security.capabilities.clone();
        let cap_drop = vec!["ALL".to_string()];

+        let image_ref = manifest.app.container.image_ref().ok_or_else(|| {
+            anyhow::anyhow!(
+                "container config for {} has neither a valid image nor build source",
+                manifest.app.id
+            )
+        })?;
+
+        // Build resource_limits conditionally: if the manifest has no memory or
+        // cpu limit, OMIT the field entirely rather than sending 0. The podman
+        // libpod HTTP API treats `memory.limit: 0` as "set MemoryMax=0" which
+        // systemd then rejects at container-start time. Absent = unlimited.
+        let mut resource_limits = serde_json::Map::new();
+        if let Some(mem_bytes) = manifest
+            .app
+            .resources
+            .memory_limit
+            .as_ref()
+            .and_then(|m| parse_memory_limit(m))
+        {
+            resource_limits.insert(
+                "memory".to_string(),
+                serde_json::json!({ "limit": mem_bytes }),
+            );
+        }
+        if let Some(cpu) = manifest.app.resources.cpu_limit {
+            resource_limits.insert(
+                "cpu".to_string(),
+                serde_json::json!({
+                    "quota": (cpu as i64) * 100_000,
+                    "period": 100_000u64,
+                }),
+            );
+        }
+
        let body = serde_json::json!({
            "name": name,
-            "image": manifest.app.container.image,
+            "image": image_ref,
            "portmappings": port_mappings,
            "mounts": mounts,
            "env": env_map,
@@ -316,19 +350,7 @@ impl PodmanClient {
            "devices": manifest.app.devices.iter().map(|d| {
                serde_json::json!({"path": d})
            }).collect::<Vec<_>>(),
-            "resource_limits": {
-                "memory": {
-                    "limit": manifest.app.resources.memory_limit.as_ref()
-                        .and_then(|m| parse_memory_limit(m))
-                        .unwrap_or(0),
-                },
-                "cpu": {
-                    "quota": manifest.app.resources.cpu_limit
-                        .map(|c| (c as i64) * 100000)
-                        .unwrap_or(0),
-                    "period": 100000u64,
-                }
-            },
+            "resource_limits": resource_limits,
            "cap_add": cap_add,
            "cap_drop": cap_drop,
            "read_only_filesystem": manifest.app.security.readonly_root,
@@ -571,26 +593,106 @@ fn parse_port_bindings(bindings: &serde_json::Value) -> Vec<String> {
 }

 fn parse_memory_limit(limit: &str) -> Option<i64> {
-    let limit = limit.trim().to_lowercase();
-    if limit.ends_with('g') {
-        limit
-            .trim_end_matches('g')
-            .parse::<f64>()
-            .ok()
-            .map(|v| (v * 1_073_741_824.0) as i64)
-    } else if limit.ends_with('m') {
-        limit
-            .trim_end_matches('m')
-            .parse::<f64>()
-            .ok()
-            .map(|v| (v * 1_048_576.0) as i64)
-    } else if limit.ends_with('k') {
-        limit
-            .trim_end_matches('k')
-            .parse::<f64>()
-            .ok()
-            .map(|v| (v * 1024.0) as i64)
-    } else {
-        limit.parse::<i64>().ok()
+    // Supports the Kubernetes-style suffixes used throughout apps/*/manifest.yml
+    // (IEC binary: Ki/Mi/Gi/Ti) as well as the shorter docker-style k/m/g/t.
+    // Longest suffix matched first so "Mi" isn't mis-matched as "m".
+    //
+    // Historical bug: we used to lowercase+trim_end_matches('m'), which turned
+    // "128Mi" into "128i" → parse::<f64> failed → None → .unwrap_or(0) wrote
+    // memory.limit:0 into the OCI spec, which systemd then rejected at start
+    // time with "MemoryMax is out of range" on rootless podman. See
+    // docs/rust-orchestrator-migration.md Step 9 notes.
+    let trimmed = limit.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    const UNITS: &[(&str, i64)] = &[
+        ("Ki", 1024),
+        ("Mi", 1024 * 1024),
+        ("Gi", 1024 * 1024 * 1024),
+        ("Ti", 1024i64 * 1024 * 1024 * 1024),
+        ("kB", 1000),
+        ("MB", 1_000_000),
+        ("GB", 1_000_000_000),
+        ("TB", 1_000_000_000_000),
+        ("k", 1024),
+        ("K", 1024),
+        ("m", 1024 * 1024),
+        ("M", 1024 * 1024),
+        ("g", 1024 * 1024 * 1024),
+        ("G", 1024 * 1024 * 1024),
+        ("t", 1024i64 * 1024 * 1024 * 1024),
+        ("T", 1024i64 * 1024 * 1024 * 1024),
+        ("b", 1),
+        ("B", 1),
+    ];
+    for (suffix, multiplier) in UNITS {
+        if let Some(num) = trimmed.strip_suffix(suffix) {
+            let num = num.trim();
+            return num
+                .parse::<f64>()
+                .ok()
+                .map(|v| (v * (*multiplier as f64)) as i64)
+                .filter(|n| *n > 0);
+        }
+    }
+    // No recognised suffix — treat as raw bytes.
+    trimmed.parse::<i64>().ok().filter(|n| *n > 0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_memory_limit_iec_binary_suffixes() {
+        // Kubernetes-style — this is what apps/*/manifest.yml uses.
+        assert_eq!(parse_memory_limit("128Mi"), Some(128 * 1024 * 1024));
+        assert_eq!(parse_memory_limit("64Mi"), Some(64 * 1024 * 1024));
+        assert_eq!(parse_memory_limit("4Gi"), Some(4i64 * 1024 * 1024 * 1024));
+        assert_eq!(parse_memory_limit("512Ki"), Some(512 * 1024));
+    }
+
+    #[test]
+    fn parse_memory_limit_shorthand_suffixes() {
+        // Docker-style shorthand — treated as IEC binary for backwards compat.
+        assert_eq!(parse_memory_limit("128m"), Some(128 * 1024 * 1024));
+        assert_eq!(parse_memory_limit("128M"), Some(128 * 1024 * 1024));
+        assert_eq!(parse_memory_limit("2g"), Some(2i64 * 1024 * 1024 * 1024));
+        assert_eq!(parse_memory_limit("2G"), Some(2i64 * 1024 * 1024 * 1024));
+    }
+
+    #[test]
+    fn parse_memory_limit_si_decimal_suffixes() {
+        assert_eq!(parse_memory_limit("1MB"), Some(1_000_000));
+        assert_eq!(parse_memory_limit("1GB"), Some(1_000_000_000));
+    }
+
+    #[test]
+    fn parse_memory_limit_raw_bytes() {
+        assert_eq!(parse_memory_limit("134217728"), Some(134_217_728));
+        assert_eq!(parse_memory_limit("  134217728  "), Some(134_217_728));
+    }
+
+    #[test]
+    fn parse_memory_limit_invalid_returns_none() {
+        // Regression guard: the old implementation returned Some(0) for "128Mi"
+        // because lowercase+trim_end_matches('m') left "128i" which parse::<f64>
+        // rejected. The new implementation must never return Some(0) or Some of
+        // a negative number from any input.
+        assert_eq!(parse_memory_limit(""), None);
+        assert_eq!(parse_memory_limit("   "), None);
+        assert_eq!(parse_memory_limit("abc"), None);
+        assert_eq!(parse_memory_limit("0"), None);
+        assert_eq!(parse_memory_limit("0Mi"), None);
+        assert_eq!(parse_memory_limit("-1Mi"), None);
+    }
+
+    #[test]
+    fn parse_memory_limit_tolerates_whitespace_and_fractional() {
+        assert_eq!(
+            parse_memory_limit(" 1.5Gi "),
+            Some((1.5 * (1024.0 * 1024.0 * 1024.0)) as i64)
+        );
    }
 }
@@ -1,4 +1,4 @@
-use crate::manifest::AppManifest;
+use crate::manifest::{AppManifest, BuildConfig};
 use crate::podman_client::{ContainerState, ContainerStatus, PodmanClient};
 use anyhow::{Context, Result};
 use async_trait::async_trait;
@@ -20,6 +20,22 @@ pub trait ContainerRuntime: Send + Sync {
    async fn get_container_status(&self, name: &str) -> Result<ContainerStatus>;
    async fn get_container_logs(&self, name: &str, lines: u32) -> Result<Vec<String>>;
    async fn list_containers(&self) -> Result<Vec<ContainerStatus>>;
+
+    /// Check whether an image reference exists in local storage.
+    ///
+    /// The reconciler calls this before deciding to build. `true` means
+    /// `image inspect <image_ref>` succeeded (or equivalent); `false` means
+    /// the image is not present. Registry/network state is explicitly NOT
+    /// consulted — this is a local-storage check only.
+    async fn image_exists(&self, image_ref: &str) -> Result<bool>;
+
+    /// Build a local image from a `BuildConfig`.
+    ///
+    /// Equivalent to `podman build -t <tag> -f <dockerfile> [--build-arg K=V ...] <context>`.
+    /// The resulting image is referenceable by `config.tag` for subsequent
+    /// `create_container` / `image_exists` calls. Stdout/stderr are collected
+    /// and included in the error on failure; on success they are discarded.
+    async fn build_image(&self, config: &BuildConfig) -> Result<()>;
 }

 pub struct PodmanRuntime {
@@ -32,6 +48,17 @@ impl PodmanRuntime {
            client: PodmanClient::new(user),
        }
    }
+
+    /// Run `podman <args>`, returning an error with captured stderr on non-zero
+    /// exit. Used for operations (build, image inspect) that are awkward over the
+    /// HTTP API. The daemon runs as the target user already, so no sudo hop.
+    async fn podman_cli(&self, args: &[&str]) -> Result<std::process::Output> {
+        let mut cmd = TokioCommand::new("podman");
+        cmd.args(args);
+        cmd.output()
+            .await
+            .with_context(|| format!("failed to execute podman {}", args.join(" ")))
+    }
 }

 #[async_trait]
@@ -79,6 +106,64 @@ impl ContainerRuntime for PodmanRuntime {
    async fn list_containers(&self) -> Result<Vec<ContainerStatus>> {
        self.client.list_containers().await
    }
+
+    async fn image_exists(&self, image_ref: &str) -> Result<bool> {
+        // `podman image exists` returns 0 if present, 1 if absent. Any other
+        // exit code is an environment failure we should surface.
+        let output = self.podman_cli(&["image", "exists", image_ref]).await?;
+        match output.status.code() {
+            Some(0) => Ok(true),
+            Some(1) => Ok(false),
+            Some(code) => {
+                let stderr = String::from_utf8_lossy(&output.stderr);
+                Err(anyhow::anyhow!(
+                    "podman image exists {image_ref} exited with {code}: {stderr}"
+                ))
+            }
+            None => Err(anyhow::anyhow!(
+                "podman image exists {image_ref} terminated by signal"
+            )),
+        }
+    }
+
+    async fn build_image(&self, config: &BuildConfig) -> Result<()> {
+        let args = build_args_for_podman(config);
+        let borrowed: Vec<&str> = args.iter().map(|s| s.as_str()).collect();
+        let output = self.podman_cli(&borrowed).await?;
+        if !output.status.success() {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            let stdout = String::from_utf8_lossy(&output.stdout);
+            return Err(anyhow::anyhow!(
+                "podman build -t {} failed: {stderr}{}{stdout}",
+                config.tag,
+                if stderr.is_empty() || stdout.is_empty() { "" } else { "\n---stdout---\n" }
+            ));
+        }
+        Ok(())
+    }
+}
+
+/// Build the argv for `podman build` from a BuildConfig.
+///
+/// Extracted so it can be unit-tested without actually invoking podman.
+/// Order is fixed for deterministic tests: subcommand, -t, -f, build-args
+/// (sorted by key), context.
+fn build_args_for_podman(config: &BuildConfig) -> Vec<String> {
+    let mut args: Vec<String> = vec![
+        "build".to_string(),
+        "-t".to_string(),
+        config.tag.clone(),
+        "-f".to_string(),
+        config.dockerfile.clone(),
+    ];
+    let mut kv: Vec<(&String, &String)> = config.build_args.iter().collect();
+    kv.sort_by(|a, b| a.0.cmp(b.0));
+    for (k, v) in kv {
+        args.push("--build-arg".to_string());
+        args.push(format!("{k}={v}"));
+    }
+    args.push(config.context.clone());
+    args
 }

 pub struct DockerRuntime {
@@ -188,7 +273,13 @@ impl ContainerRuntime for DockerRuntime {
            cmd.arg("--cap-add").arg(cap);
        }

-        cmd.arg(&manifest.app.container.image);
+        let image_ref = manifest.app.container.image_ref().ok_or_else(|| {
+            anyhow::anyhow!(
+                "container config for {} has neither a valid image nor build source",
+                manifest.app.id
+            )
+        })?;
+        cmd.arg(&image_ref);

        let output = cmd.output().await.context("Failed to create container")?;

@@ -344,6 +435,42 @@ impl ContainerRuntime for DockerRuntime {

        Ok(result)
    }
+
+    async fn image_exists(&self, image_ref: &str) -> Result<bool> {
+        // `docker image inspect` exits 1 when the image is absent. Any message
+        // to stderr in that case is informational; we swallow it.
+        let mut cmd = self.docker_async();
+        cmd.arg("image").arg("inspect").arg(image_ref);
+        let output = cmd.output().await.context("failed to execute docker image inspect")?;
+        match output.status.code() {
+            Some(0) => Ok(true),
+            Some(1) => Ok(false),
+            Some(code) => {
+                let stderr = String::from_utf8_lossy(&output.stderr);
+                Err(anyhow::anyhow!(
+                    "docker image inspect {image_ref} exited with {code}: {stderr}"
+                ))
+            }
+            None => Err(anyhow::anyhow!(
+                "docker image inspect {image_ref} terminated by signal"
+            )),
+        }
+    }
+
+    async fn build_image(&self, config: &BuildConfig) -> Result<()> {
+        let mut cmd = self.docker_async();
+        cmd.arg("build").arg("-t").arg(&config.tag).arg("-f").arg(&config.dockerfile);
+        for (k, v) in &config.build_args {
+            cmd.arg("--build-arg").arg(format!("{k}={v}"));
+        }
+        cmd.arg(&config.context);
+        let output = cmd.output().await.context("failed to execute docker build")?;
+        if !output.status.success() {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            return Err(anyhow::anyhow!("docker build -t {} failed: {stderr}", config.tag));
+        }
+        Ok(())
+    }
 }

 pub struct AutoRuntime {
@@ -415,7 +542,91 @@ impl ContainerRuntime for AutoRuntime {
    async fn list_containers(&self) -> Result<Vec<ContainerStatus>> {
        self.runtime.list_containers().await
    }
+
+    async fn image_exists(&self, image_ref: &str) -> Result<bool> {
+        self.runtime.image_exists(image_ref).await
+    }
+
+    async fn build_image(&self, config: &BuildConfig) -> Result<()> {
+        self.runtime.build_image(config).await
+    }
 }

 // Runtime factory functions will be provided by the archipelago crate
 // that imports this library and has access to Config
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::collections::HashMap;
+
+    fn cfg(context: &str, tag: &str, dockerfile: &str, args: &[(&str, &str)]) -> BuildConfig {
+        BuildConfig {
+            context: context.to_string(),
+            dockerfile: dockerfile.to_string(),
+            tag: tag.to_string(),
+            build_args: args
+                .iter()
+                .map(|(k, v)| (k.to_string(), v.to_string()))
+                .collect::<HashMap<_, _>>(),
+        }
+    }
+
+    #[test]
+    fn build_args_minimal() {
+        let c = cfg("/tmp/ctx", "archy-bitcoin-ui:local", "Dockerfile", &[]);
+        assert_eq!(
+            build_args_for_podman(&c),
+            vec![
+                "build",
+                "-t",
+                "archy-bitcoin-ui:local",
+                "-f",
+                "Dockerfile",
+                "/tmp/ctx",
+            ]
+        );
+    }
+
+    #[test]
+    fn build_args_custom_dockerfile() {
+        let c = cfg("/opt/archy/bitcoin-ui", "x:local", "Dockerfile.prod", &[]);
+        let got = build_args_for_podman(&c);
+        assert_eq!(got[3], "-f");
+        assert_eq!(got[4], "Dockerfile.prod");
+        assert_eq!(got.last().unwrap(), "/opt/archy/bitcoin-ui");
+    }
+
+    #[test]
+    fn build_args_are_sorted_deterministically() {
+        // HashMap iteration order is nondeterministic; the runtime sorts so that
+        // equivalent BuildConfigs produce identical commands (easier to debug,
+        // cache-friendly if we ever layer build-cache keys on top).
+        let c = cfg(
+            "/c",
+            "t",
+            "Dockerfile",
+            &[("BAR", "2"), ("FOO", "1"), ("BAZ", "3")],
+        );
+        let args = build_args_for_podman(&c);
+        let flat: Vec<&str> = args.iter().map(|s| s.as_str()).collect();
+        // Build args appear as pairs of --build-arg K=V; locate them:
+        let mut pairs: Vec<&str> = Vec::new();
+        for w in flat.windows(2) {
+            if w[0] == "--build-arg" {
+                pairs.push(w[1]);
+            }
+        }
+        assert_eq!(pairs, vec!["BAR=2", "BAZ=3", "FOO=1"]);
+    }
+
+    #[test]
+    fn build_args_context_is_last() {
+        // Context MUST be the final positional argument — podman treats any
+        // stray trailing arg after build-args as the context, so placement
+        // matters. Regression guard.
+        let c = cfg("/final/context", "t", "Dockerfile", &[("K", "V")]);
+        let args = build_args_for_podman(&c);
+        assert_eq!(args.last().unwrap(), "/final/context");
+    }
+}
@@ -1,8 +1,22 @@
 FROM git.tx1138.com/lfg2025/nginx:1.27.4-alpine
+# Static site content.
 COPY index.html /usr/share/nginx/html/
 COPY 50x.html /usr/share/nginx/html/
-COPY nginx.conf /etc/nginx/conf.d/default.conf
-# Run nginx as root to avoid chown failures in rootless Podman user namespaces
+COPY assets/ /usr/share/nginx/html/assets/
+#
+# NOTE: /etc/nginx/conf.d/default.conf is intentionally NOT copied from
+# this build context. It is bind-mounted at container-create time from
+# /var/lib/archipelago/bitcoin-ui/nginx.conf on the host, which the
+# archipelago prod orchestrator renders with the current base64 RPC
+# auth substituted in (see core/archipelago/src/container/bitcoin_ui.rs).
+#
+# If the bind-mount fails nginx will start with no site configured and
+# return 404 on every request. That's the intended safe failure mode —
+# better than baking a placeholder into the image and potentially
+# serving the upstream RPC proxy with a stale/empty Authorization header.
+#
+# Run nginx as root to avoid chown failures in rootless Podman user
+# namespaces. The rest of the nginx image is unchanged.
 RUN sed -i 's/^user  nginx;/user  root;/' /etc/nginx/nginx.conf && \
    mkdir -p /var/cache/nginx/client_temp /var/cache/nginx/proxy_temp \
             /var/cache/nginx/fastcgi_temp /var/cache/nginx/uwsgi_temp \
@@ -6,7 +6,7 @@
    <meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
    <meta http-equiv="Pragma" content="no-cache">
    <meta http-equiv="Expires" content="0">
-    <title>Bitcoin Knots - Archipelago</title>
+    <title id="pageTitle">Bitcoin Node - Archipelago</title>
    <script src="https://cdn.tailwindcss.com"></script>
    <style>
        * {
@@ -336,9 +336,10 @@
                <!-- Logo - Top Left -->
                <div class="flex-shrink-0">
                    <div class="logo-gradient-border">
-                        <img 
+                        <img
+                            id="implLogo"
                            src="/assets/img/app-icons/bitcoin-knots.webp"
-                            alt="Bitcoin Knots" 
+                            alt="Bitcoin Node"
                            class="w-16 h-16"
                            style="object-fit: contain;"
                            onerror="this.style.display='none'"
@@ -348,8 +349,8 @@
                
                <!-- Title and Description -->
                <div class="flex-1 min-w-0">
-                    <h1 class="text-3xl font-bold text-white mb-2">Bitcoin Knots</h1>
-                    <p class="text-white/70">Enhanced Bitcoin node implementation</p>
+                    <h1 id="implName" class="text-3xl font-bold text-white mb-2">Bitcoin Node</h1>
+                    <p id="implTagline" class="text-white/70">Detecting implementation…</p>
                </div>

                <!-- Node Status Info - Compact on Desktop -->
@@ -385,8 +386,18 @@
                        </div>
                    </div>

-                    <button 
-                        onclick="openSettings()" 
+                    <div class="info-card flex items-center gap-3">
+                        <svg class="w-5 h-5 text-white/60" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 7v10c0 2 1.6 3 4 3h8c2.4 0 4-1 4-3V7M4 7c0-2 1.6-3 4-3h8c2.4 0 4 1 4 3M4 7h16M9 11h6M9 15h6" />
+                        </svg>
+                        <div>
+                            <p class="text-xs text-white/60">Storage</p>
+                            <p class="text-sm font-medium text-white" id="storageMode">Loading...</p>
+                        </div>
+                    </div>
+
+                    <button
+                        onclick="openSettings()"
                        class="px-4 py-3 glass-button rounded-lg text-sm font-medium"
                    >
                        Settings
@@ -556,19 +567,23 @@
            <div class="space-y-3">
                <div class="p-3 bg-white/5 rounded-lg">
                    <div class="font-semibold text-white mb-1">Network Mode</div>
-                    <div class="text-white/70 text-sm">Regtest (Development)</div>
+                    <div class="text-white/70 text-sm" id="settingsNetworkMode">Loading…</div>
+                </div>
+                <div class="p-3 bg-white/5 rounded-lg">
+                    <div class="font-semibold text-white mb-1">Storage Mode</div>
+                    <div class="text-white/70 text-sm" id="settingsStorageMode">Loading…</div>
                </div>
                <div class="p-3 bg-white/5 rounded-lg">
                    <div class="font-semibold text-white mb-1">Transaction Index</div>
-                    <div class="text-white/70 text-sm">Enabled (txindex=1)</div>
+                    <div class="text-white/70 text-sm" id="settingsTxIndex">Loading…</div>
                </div>
                <div class="p-3 bg-white/5 rounded-lg">
                    <div class="font-semibold text-white mb-1">ZMQ Publishing</div>
-                    <div class="text-white/70 text-sm">Block & TX notifications enabled</div>
+                    <div class="text-white/70 text-sm" id="settingsZmq">Loading…</div>
                </div>
                <div class="p-3 bg-white/5 rounded-lg">
                    <div class="font-semibold text-white mb-1">RPC Access</div>
-                    <div class="text-white/70 text-sm">Enabled on 0.0.0.0:18443</div>
+                    <div class="text-white/70 text-sm" id="settingsRpc">Loading…</div>
                </div>
            </div>
        </div>
@@ -630,6 +645,31 @@
            }
        }

+        // Implementation branding — detected from getnetworkinfo.subversion.
+        // Bitcoin Knots identifies as "/Satoshi:<ver>/Knots:<date>/", Bitcoin Core as "/Satoshi:<ver>/".
+        let brandingApplied = false;
+        function applyImplBranding(subversion) {
+            if (brandingApplied) return;
+            if (!subversion) return;
+            const isKnots = /Knots/i.test(subversion);
+            const name = isKnots ? 'Bitcoin Knots' : 'Bitcoin Core';
+            const tagline = isKnots
+                ? 'Enhanced Bitcoin node implementation'
+                : 'Reference Bitcoin node implementation';
+            const icon = isKnots
+                ? '/assets/img/app-icons/bitcoin-knots.webp'
+                : '/assets/img/app-icons/bitcoin-core.svg';
+            const pageTitle = document.getElementById('pageTitle');
+            const implName = document.getElementById('implName');
+            const implTagline = document.getElementById('implTagline');
+            const implLogo = document.getElementById('implLogo');
+            if (pageTitle) pageTitle.textContent = `${name} - Archipelago`;
+            if (implName) implName.textContent = name;
+            if (implTagline) implTagline.textContent = tagline;
+            if (implLogo) { implLogo.src = icon; implLogo.alt = name; }
+            brandingApplied = true;
+        }
+
        // Track last block count for animations
        let lastBlockCount = 0;

@@ -648,7 +688,9 @@
                }

                const networkInfo = await callRPC('getnetworkinfo');
-                
+
+                applyImplBranding(networkInfo && networkInfo.subversion);
+
                // Update network mode
                const chain = blockchainInfo.chain || 'unknown';
                const networkType = document.getElementById('networkType');
@@ -666,6 +708,70 @@
                
                if (networkType) networkType.textContent = networkShort;

+                // Mirror to Settings modal — Network Mode
+                const settingsNetworkMode = document.getElementById('settingsNetworkMode');
+                if (settingsNetworkMode) {
+                    const labels = { main: 'Mainnet', test: 'Testnet', signet: 'Signet', regtest: 'Regtest (Development)' };
+                    settingsNetworkMode.textContent = labels[chain] || networkShort;
+                }
+
+                // Update storage mode (pruned vs full archive)
+                const storageMode = document.getElementById('storageMode');
+                if (storageMode) {
+                    const sizeGb = blockchainInfo.size_on_disk
+                        ? (blockchainInfo.size_on_disk / 1e9).toFixed(1) + ' GB'
+                        : null;
+                    if (blockchainInfo.pruned) {
+                        storageMode.textContent = sizeGb ? `Pruned · ${sizeGb}` : 'Pruned';
+                        storageMode.className = 'text-sm font-medium text-amber-300';
+                    } else {
+                        storageMode.textContent = sizeGb ? `Full Archive · ${sizeGb}` : 'Full Archive';
+                        storageMode.className = 'text-sm font-medium text-emerald-300';
+                    }
+                }
+
+                // Mirror to Settings modal — Storage Mode
+                const settingsStorageMode = document.getElementById('settingsStorageMode');
+                if (settingsStorageMode) {
+                    if (blockchainInfo.pruned) {
+                        const heightNote = blockchainInfo.prune_height != null
+                            ? ` (keeping from block ${blockchainInfo.prune_height.toLocaleString()})` : '';
+                        settingsStorageMode.textContent = `Pruned${heightNote}`;
+                    } else {
+                        settingsStorageMode.textContent = 'Full archive (no pruning)';
+                    }
+                }
+
+                // Populate Settings — Transaction Index, ZMQ, RPC (fire-and-forget)
+                (async () => {
+                    const txIndexEl = document.getElementById('settingsTxIndex');
+                    if (txIndexEl) {
+                        const idx = await callRPC('getindexinfo');
+                        if (idx && typeof idx === 'object') {
+                            const names = Object.keys(idx);
+                            txIndexEl.textContent = names.length
+                                ? `Enabled: ${names.join(', ')}`
+                                : 'Disabled';
+                        } else {
+                            txIndexEl.textContent = 'Disabled';
+                        }
+                    }
+                    const zmqEl = document.getElementById('settingsZmq');
+                    if (zmqEl) {
+                        const zmq = await callRPC('getzmqnotifications');
+                        if (Array.isArray(zmq) && zmq.length) {
+                            zmqEl.textContent = zmq.map(z => `${z.type}@${z.address}`).join('; ');
+                        } else {
+                            zmqEl.textContent = 'Not enabled';
+                        }
+                    }
+                    const rpcEl = document.getElementById('settingsRpc');
+                    if (rpcEl && networkInfo) {
+                        const port = chain === 'main' ? 8332 : (chain === 'test' ? 18332 : (chain === 'signet' ? 38332 : 18443));
+                        rpcEl.textContent = `Reachable on port ${port}`;
+                    }
+                })();
+
                // Update sync status
                const blocks = blockchainInfo.blocks || 0;
                const headers = blockchainInfo.headers || 0;
@@ -779,7 +885,9 @@
                const peerInfo = await callRPC('getpeerinfo');
                
                if (networkInfo && blockchainInfo) {
-                    logsContent.textContent = `Bitcoin Knots version ${networkInfo.subversion || 'unknown'}
+                    applyImplBranding(networkInfo.subversion);
+                    const implLabel = /Knots/i.test(networkInfo.subversion || '') ? 'Bitcoin Knots' : 'Bitcoin Core';
+                    logsContent.textContent = `${implLabel} version ${networkInfo.subversion || 'unknown'}
 Network: ${blockchainInfo.chain}
 Blocks: ${blockchainInfo.blocks}
 Headers: ${blockchainInfo.headers}
@@ -1,10 +0,0 @@
-FROM git.tx1138.com/lfg2025/nginx:1.27.4-alpine
-COPY index.html /usr/share/nginx/html/
-COPY nginx.conf /etc/nginx/conf.d/default.conf
-RUN sed -i 's/^user  nginx;/user  root;/' /etc/nginx/nginx.conf && \
-    mkdir -p /var/cache/nginx/client_temp /var/cache/nginx/proxy_temp \
-             /var/cache/nginx/fastcgi_temp /var/cache/nginx/uwsgi_temp \
-             /var/cache/nginx/scgi_temp
-EXPOSE 8202
-ENTRYPOINT []
-CMD ["nginx", "-g", "daemon off;"]
@@ -1,236 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
-    <title>FIPS - Archipelago</title>
-    <style>
-        * { margin: 0; padding: 0; box-sizing: border-box; }
-        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; min-height: 100vh; color: white; overflow-x: hidden; }
-        .bg-layer { position: fixed; inset: 0; z-index: -10; background: linear-gradient(135deg, rgba(5,20,15,0.95) 0%, rgba(10,30,25,0.98) 50%, rgba(5,15,20,0.95) 100%); }
-        .overlay { position: fixed; inset: 0; background: rgba(0, 0, 0, 0.7); z-index: -5; }
-        .glass-card { background: rgba(0, 0, 0, 0.5); backdrop-filter: blur(24px); -webkit-backdrop-filter: blur(24px); border-radius: 1rem; border: 1px solid rgba(255, 255, 255, 0.12); transform: translateZ(0); isolation: isolate; }
-        .info-card { background: rgba(255, 255, 255, 0.05); border-radius: 12px; padding: 12px; border: 1px solid rgba(255, 255, 255, 0.08); }
-        .container { max-width: 56rem; margin: 0 auto; padding: 1.5rem; }
-        .flex { display: flex; } .flex-col { flex-direction: column; } .items-center { align-items: center; }
-        .gap-3 { gap: 0.75rem; } .gap-4 { gap: 1rem; } .flex-1 { flex: 1; } .flex-shrink-0 { flex-shrink: 0; }
-        .mb-2 { margin-bottom: 0.5rem; } .mb-4 { margin-bottom: 1rem; } .mb-6 { margin-bottom: 1.5rem; }
-        .p-5 { padding: 1.25rem; } .p-6 { padding: 1.5rem; }
-        .grid { display: grid; } .grid-cols-2 { grid-template-columns: repeat(2, 1fr); } .grid-cols-3 { grid-template-columns: repeat(3, 1fr); }
-        .text-xs { font-size: 0.75rem; } .text-sm { font-size: 0.875rem; } .text-lg { font-size: 1.125rem; }
-        .text-xl { font-size: 1.25rem; } .text-2xl { font-size: 1.5rem; }
-        .font-bold { font-weight: 700; } .font-semibold { font-weight: 600; } .font-medium { font-weight: 500; } .font-mono { font-family: monospace; }
-        .text-white-70 { color: rgba(255,255,255,0.7); } .text-white-60 { color: rgba(255,255,255,0.6); } .text-white-50 { color: rgba(255,255,255,0.5); }
-        .text-emerald { color: #34d399; } .text-green { color: #4ade80; } .text-yellow { color: #fbbf24; } .text-red { color: #f87171; }
-        .justify-between { justify-content: space-between; }
-        .status-dot { width: 0.75rem; height: 0.75rem; border-radius: 9999px; }
-        .bg-green { background: #4ade80; } .bg-yellow { background: #fbbf24; } .bg-red { background: #f87171; }
-        @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }
-        .animate-pulse { animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite; }
-        .icon-box { width: 3.5rem; height: 3.5rem; border-radius: 0.75rem; background: rgba(52, 211, 153, 0.15); display: flex; align-items: center; justify-content: center; }
-        .step { display: flex; gap: 1rem; align-items: flex-start; }
-        .step-num { width: 2rem; height: 2rem; border-radius: 50%; background: rgba(52, 211, 153, 0.2); border: 1px solid rgba(52, 211, 153, 0.4); display: flex; align-items: center; justify-content: center; font-size: 0.875rem; font-weight: 700; color: #34d399; flex-shrink: 0; }
-        .copy-btn { padding: 0.5rem 0.625rem; background: none; border: none; border-left: 1px solid rgba(255,255,255,0.1); cursor: pointer; color: rgba(255,255,255,0.4); transition: all 0.2s ease; display: flex; align-items: center; }
-        .copy-btn:hover { color: rgba(255,255,255,0.8); background: rgba(255,255,255,0.05); }
-        .copy-btn.copied { color: #4ade80; }
-        .field-row { display: flex; align-items: center; background: rgba(255,255,255,0.06); border: 1px solid rgba(255,255,255,0.1); border-radius: 0.5rem; overflow: hidden; }
-        .field-value { flex: 1; padding: 0.625rem 0.875rem; font-family: monospace; font-size: 0.8125rem; color: rgba(255,255,255,0.9); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-        .field-label { font-size: 0.6875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; color: rgba(255,255,255,0.4); margin-bottom: 0.375rem; }
-        .feature-icon { width: 2.5rem; height: 2.5rem; border-radius: 0.5rem; background: rgba(52, 211, 153, 0.1); display: flex; align-items: center; justify-content: center; flex-shrink: 0; }
-        @media (max-width: 640px) { .grid-cols-2 { grid-template-columns: 1fr; } .grid-cols-3 { grid-template-columns: 1fr; } }
-    </style>
-</head>
-<body>
-    <div class="bg-layer"></div>
-    <div class="overlay"></div>
-
-    <div class="container">
-        <!-- Header -->
-        <div class="glass-card p-6 mb-6">
-            <div class="flex items-center gap-4">
-                <div class="icon-box flex-shrink-0">
-                    <svg style="width:1.75rem;height:1.75rem;color:#34d399" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 12a9 9 0 01-9 9m9-9a9 9 0 00-9-9m9 9H3m9 9a9 9 0 01-9-9m9 9c1.657 0 3-4.03 3-9s-1.343-9-3-9m0 18c-1.657 0-3-4.03-3-9s1.343-9 3-9m-9 9a9 9 0 019-9" />
-                    </svg>
-                </div>
-                <div class="flex-1">
-                    <div class="flex items-center gap-3">
-                        <h1 class="text-2xl font-bold">FIPS</h1>
-                        <span class="text-xs text-white-50">v0.1.0</span>
-                    </div>
-                    <p class="text-white-60 text-sm">Free Internetworking Peering System</p>
-                </div>
-                <div class="info-card flex items-center gap-3">
-                    <div id="statusDot" class="status-dot bg-yellow animate-pulse"></div>
-                    <div>
-                        <p class="text-xs text-white-50">Status</p>
-                        <p class="text-sm font-medium" id="statusText">Checking...</p>
-                    </div>
-                </div>
-            </div>
-        </div>
-
-        <!-- What It Does -->
-        <div class="glass-card p-5 mb-6">
-            <h2 class="text-lg font-semibold mb-4" style="color:#34d399">What is FIPS?</h2>
-            <p class="text-white-70 text-sm mb-4" style="line-height:1.6">
-                FIPS is a <strong style="color:white">self-organizing encrypted mesh network</strong>. Each node gets a
-                <strong style="color:white">secp256k1 keypair</strong> (same as Nostr/Bitcoin) that serves as its identity.
-                Nodes discover each other, negotiate encryption using the <strong style="color:white">Noise protocol</strong>,
-                and route traffic without any central authority. A virtual network interface (<code style="background:rgba(255,255,255,0.1);padding:0.125rem 0.375rem;border-radius:0.25rem">fips0</code>)
-                lets unmodified applications — SSH, web browsers, anything — communicate transparently over the mesh.
-                Think of it as <strong style="color:white">a new internet layer, built on cryptographic identity</strong>.
-            </p>
-            <div class="grid grid-cols-3 gap-3">
-                <div class="info-card flex items-center gap-3">
-                    <div class="feature-icon">
-                        <svg style="width:1.25rem;height:1.25rem;color:#34d399" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 3v2m6-2v2M9 19v2m6-2v2M5 9H3m2 6H3m18-6h-2m2 6h-2M7 19h10a2 2 0 002-2V7a2 2 0 00-2-2H7a2 2 0 00-2 2v10a2 2 0 002 2zM9 9h6v6H9V9z"/></svg>
-                    </div>
-                    <div>
-                        <p class="text-sm font-medium">Zero Config</p>
-                        <p class="text-xs text-white-50">Self-organizing mesh</p>
-                    </div>
-                </div>
-                <div class="info-card flex items-center gap-3">
-                    <div class="feature-icon">
-                        <svg style="width:1.25rem;height:1.25rem;color:#34d399" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z"/></svg>
-                    </div>
-                    <div>
-                        <p class="text-sm font-medium">End-to-End Encrypted</p>
-                        <p class="text-xs text-white-50">Noise IK + XK protocols</p>
-                    </div>
-                </div>
-                <div class="info-card flex items-center gap-3">
-                    <div class="feature-icon">
-                        <svg style="width:1.25rem;height:1.25rem;color:#34d399" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3.055 11H5a2 2 0 012 2v1a2 2 0 002 2 2 2 0 012 2v2.945M8 3.935V5.5A2.5 2.5 0 0010.5 8h.5a2 2 0 012 2 2 2 0 104 0 2 2 0 012-2h1.064M15 20.488V18a2 2 0 012-2h3.064"/></svg>
-                    </div>
-                    <div>
-                        <p class="text-sm font-medium">Multi-Transport</p>
-                        <p class="text-xs text-white-50">UDP, TCP, Tor, BLE</p>
-                    </div>
-                </div>
-            </div>
-        </div>
-
-        <!-- Node Identity -->
-        <div class="glass-card p-5 mb-6">
-            <h2 class="text-lg font-semibold mb-4" style="color:#34d399">Node Identity</h2>
-            <p class="text-white-60 text-sm mb-4">Your node's Nostr public key doubles as its FIPS mesh address. Share with peers to connect.</p>
-            <div class="grid grid-cols-2 gap-3 mb-4">
-                <div>
-                    <div class="field-label">Nostr Public Key (npub)</div>
-                    <div class="field-row">
-                        <span class="field-value" id="npub">Loading...</span>
-                        <button class="copy-btn" onclick="copyField('npub', this)" title="Copy">
-                            <svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24"><rect x="9" y="9" width="13" height="13" rx="2" ry="2" stroke-width="2"/><path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" stroke-width="2"/></svg>
-                        </button>
-                    </div>
-                </div>
-                <div>
-                    <div class="field-label">Mesh Ports</div>
-                    <div class="field-row">
-                        <span class="field-value">UDP 2121 / TCP 8443</span>
-                        <button class="copy-btn" onclick="copyText('2121', this)" title="Copy">
-                            <svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24"><rect x="9" y="9" width="13" height="13" rx="2" ry="2" stroke-width="2"/><path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" stroke-width="2"/></svg>
-                        </button>
-                    </div>
-                </div>
-            </div>
-        </div>
-
-        <!-- How to Use -->
-        <div class="glass-card p-5 mb-6">
-            <h2 class="text-lg font-semibold mb-4" style="color:#34d399">How to Use</h2>
-            <div class="flex flex-col gap-4">
-                <div class="step">
-                    <div class="step-num">1</div>
-                    <div>
-                        <p class="text-sm font-semibold mb-2">Install FIPS on your other devices</p>
-                        <p class="text-xs text-white-60" style="line-height:1.5">Download <code style="background:rgba(255,255,255,0.1);padding:0.125rem 0.375rem;border-radius:0.25rem">fips</code> from <a href="https://github.com/jmcorgan/fips" style="color:#34d399;text-decoration:underline" target="_blank">GitHub</a>. Build with <code style="background:rgba(255,255,255,0.1);padding:0.125rem 0.375rem;border-radius:0.25rem">cargo build --release</code> (requires Rust 1.85+).</p>
-                    </div>
-                </div>
-                <div class="step">
-                    <div class="step-num">2</div>
-                    <div>
-                        <p class="text-sm font-semibold mb-2">Configure peers in fips.yaml</p>
-                        <p class="text-xs text-white-60" style="line-height:1.5">Edit <code style="background:rgba(255,255,255,0.1);padding:0.125rem 0.375rem;border-radius:0.25rem">/etc/fips/fips.yaml</code> on each device. Add your Archipelago node's IP and port as a peer. The node's npub above is its identity on the mesh.</p>
-                    </div>
-                </div>
-                <div class="step">
-                    <div class="step-num">3</div>
-                    <div>
-                        <p class="text-sm font-semibold mb-2">Start the daemon and connect</p>
-                        <p class="text-xs text-white-60" style="line-height:1.5">Run <code style="background:rgba(255,255,255,0.1);padding:0.125rem 0.375rem;border-radius:0.25rem">fips --config /etc/fips/fips.yaml</code>. A <code style="background:rgba(255,255,255,0.1);padding:0.125rem 0.375rem;border-radius:0.25rem">fips0</code> virtual interface appears. Use <code style="background:rgba(255,255,255,0.1);padding:0.125rem 0.375rem;border-radius:0.25rem">fipsctl show peers</code> to see connected nodes. You can now SSH, browse, or run any IP app over the encrypted mesh using <code style="background:rgba(255,255,255,0.1);padding:0.125rem 0.375rem;border-radius:0.25rem">.fips</code> DNS names.</p>
-                    </div>
-                </div>
-            </div>
-        </div>
-
-        <!-- Container Logs -->
-        <div class="glass-card p-5">
-            <h2 class="text-lg font-semibold mb-4" style="color:#34d399">Container Logs</h2>
-            <div id="logs" style="background:rgba(0,0,0,0.4);border-radius:0.5rem;padding:0.75rem;font-family:monospace;font-size:0.75rem;color:rgba(255,255,255,0.6);max-height:200px;overflow-y:auto;line-height:1.6">
-                Fetching logs...
-            </div>
-        </div>
-    </div>
-
-    <script>
-        var COPY_SVG = '<svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24"><rect x="9" y="9" width="13" height="13" rx="2" ry="2" stroke-width="2"/><path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" stroke-width="2"/></svg>';
-        var CHECK_SVG = '<svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7"/></svg>';
-
-        function flashCopied(btn) { btn.classList.add('copied'); var o = btn.innerHTML; btn.innerHTML = CHECK_SVG; setTimeout(function() { btn.classList.remove('copied'); btn.innerHTML = o; }, 1500); }
-        function copyField(id, btn) { var t = document.getElementById(id).textContent.trim(); if (!t || t === 'Loading...') return; navigator.clipboard.writeText(t).then(function() { flashCopied(btn); }); }
-        function copyText(text, btn) { navigator.clipboard.writeText(text).then(function() { flashCopied(btn); }); }
-
-        async function fetchNodeIdentity() {
-            try {
-                var resp = await fetch('/rpc/', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'node.nostr-pubkey', params: {} }) });
-                var data = await resp.json();
-                if (data.result && data.result.npub) {
-                    document.getElementById('npub').textContent = data.result.npub;
-                } else if (data.result && data.result.pubkey) {
-                    document.getElementById('npub').textContent = data.result.pubkey;
-                }
-            } catch(e) { document.getElementById('npub').textContent = 'Unavailable'; }
-        }
-
-        async function fetchStatus() {
-            try {
-                var resp = await fetch('/rpc/', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'package.info', params: { id: 'fips' } }) });
-                var data = await resp.json();
-                var dot = document.getElementById('statusDot');
-                var txt = document.getElementById('statusText');
-                if (data.result && data.result.state === 'running') {
-                    dot.className = 'status-dot bg-green'; txt.textContent = 'Running';
-                } else if (data.result && data.result.state === 'stopped') {
-                    dot.className = 'status-dot bg-red'; txt.textContent = 'Stopped';
-                } else {
-                    dot.className = 'status-dot bg-yellow animate-pulse'; txt.textContent = data.result ? data.result.state : 'Unknown';
-                }
-            } catch(e) { /* keep checking */ }
-        }
-
-        async function fetchLogs() {
-            try {
-                var resp = await fetch('/api/container/logs?app_id=fips&lines=30');
-                if (resp.ok) {
-                    var data = await resp.json();
-                    var logs = data.logs || data.stdout || '';
-                    if (typeof logs === 'object') logs = JSON.stringify(logs);
-                    document.getElementById('logs').textContent = logs || 'No logs available yet.';
-                    var el = document.getElementById('logs');
-                    el.scrollTop = el.scrollHeight;
-                }
-            } catch(e) { document.getElementById('logs').textContent = 'Waiting for container...'; }
-        }
-
-        fetchNodeIdentity();
-        fetchStatus();
-        fetchLogs();
-        setInterval(fetchStatus, 10000);
-        setInterval(fetchLogs, 15000);
-    </script>
-</body>
-</html>
@@ -1,11 +0,0 @@
-server {
-    listen 8202;
-    server_name _;
-
-    root /usr/share/nginx/html;
-    index index.html;
-
-    location / {
-        try_files $uri $uri/ /index.html;
-    }
-}
@@ -1,10 +0,0 @@
-FROM git.tx1138.com/lfg2025/nginx:1.27.4-alpine
-COPY index.html /usr/share/nginx/html/
-COPY nginx.conf /etc/nginx/conf.d/default.conf
-RUN sed -i 's/^user  nginx;/user  root;/' /etc/nginx/nginx.conf && \
-    mkdir -p /var/cache/nginx/client_temp /var/cache/nginx/proxy_temp \
-             /var/cache/nginx/fastcgi_temp /var/cache/nginx/uwsgi_temp \
-             /var/cache/nginx/scgi_temp
-EXPOSE 8201
-ENTRYPOINT []
-CMD ["nginx", "-g", "daemon off;"]
@@ -1,232 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
-    <title>Nostr VPN - Archipelago</title>
-    <style>
-        * { margin: 0; padding: 0; box-sizing: border-box; }
-        body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; min-height: 100vh; color: white; overflow-x: hidden; }
-        .bg-layer { position: fixed; inset: 0; z-index: -10; background: linear-gradient(135deg, rgba(10,5,30,0.95) 0%, rgba(20,10,50,0.98) 50%, rgba(5,15,35,0.95) 100%); }
-        .overlay { position: fixed; inset: 0; background: rgba(0, 0, 0, 0.7); z-index: -5; }
-        .glass-card { background: rgba(0, 0, 0, 0.5); backdrop-filter: blur(24px); -webkit-backdrop-filter: blur(24px); border-radius: 1rem; border: 1px solid rgba(255, 255, 255, 0.12); transform: translateZ(0); isolation: isolate; }
-        .info-card { background: rgba(255, 255, 255, 0.05); border-radius: 12px; padding: 12px; border: 1px solid rgba(255, 255, 255, 0.08); }
-        .container { max-width: 56rem; margin: 0 auto; padding: 1.5rem; }
-        .flex { display: flex; } .flex-col { flex-direction: column; } .items-center { align-items: center; }
-        .gap-3 { gap: 0.75rem; } .gap-4 { gap: 1rem; } .flex-1 { flex: 1; } .flex-shrink-0 { flex-shrink: 0; }
-        .mb-2 { margin-bottom: 0.5rem; } .mb-4 { margin-bottom: 1rem; } .mb-6 { margin-bottom: 1.5rem; }
-        .p-5 { padding: 1.25rem; } .p-6 { padding: 1.5rem; }
-        .grid { display: grid; } .grid-cols-2 { grid-template-columns: repeat(2, 1fr); } .grid-cols-3 { grid-template-columns: repeat(3, 1fr); }
-        .text-xs { font-size: 0.75rem; } .text-sm { font-size: 0.875rem; } .text-lg { font-size: 1.125rem; }
-        .text-xl { font-size: 1.25rem; } .text-2xl { font-size: 1.5rem; }
-        .font-bold { font-weight: 700; } .font-semibold { font-weight: 600; } .font-medium { font-weight: 500; } .font-mono { font-family: monospace; }
-        .text-white-70 { color: rgba(255,255,255,0.7); } .text-white-60 { color: rgba(255,255,255,0.6); } .text-white-50 { color: rgba(255,255,255,0.5); }
-        .text-purple { color: #a78bfa; } .text-green { color: #4ade80; } .text-yellow { color: #fbbf24; } .text-red { color: #f87171; }
-        .justify-between { justify-content: space-between; }
-        .status-dot { width: 0.75rem; height: 0.75rem; border-radius: 9999px; }
-        .bg-green { background: #4ade80; } .bg-yellow { background: #fbbf24; } .bg-red { background: #f87171; }
-        @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }
-        .animate-pulse { animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite; }
-        .icon-box { width: 3.5rem; height: 3.5rem; border-radius: 0.75rem; background: rgba(167, 139, 250, 0.15); display: flex; align-items: center; justify-content: center; }
-        .step { display: flex; gap: 1rem; align-items: flex-start; }
-        .step-num { width: 2rem; height: 2rem; border-radius: 50%; background: rgba(167, 139, 250, 0.2); border: 1px solid rgba(167, 139, 250, 0.4); display: flex; align-items: center; justify-content: center; font-size: 0.875rem; font-weight: 700; color: #a78bfa; flex-shrink: 0; }
-        .copy-btn { padding: 0.5rem 0.625rem; background: none; border: none; border-left: 1px solid rgba(255,255,255,0.1); cursor: pointer; color: rgba(255,255,255,0.4); transition: all 0.2s ease; display: flex; align-items: center; }
-        .copy-btn:hover { color: rgba(255,255,255,0.8); background: rgba(255,255,255,0.05); }
-        .copy-btn.copied { color: #4ade80; }
-        .field-row { display: flex; align-items: center; background: rgba(255,255,255,0.06); border: 1px solid rgba(255,255,255,0.1); border-radius: 0.5rem; overflow: hidden; }
-        .field-value { flex: 1; padding: 0.625rem 0.875rem; font-family: monospace; font-size: 0.8125rem; color: rgba(255,255,255,0.9); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-        .field-label { font-size: 0.6875rem; font-weight: 600; text-transform: uppercase; letter-spacing: 0.05em; color: rgba(255,255,255,0.4); margin-bottom: 0.375rem; }
-        .feature-icon { width: 2.5rem; height: 2.5rem; border-radius: 0.5rem; background: rgba(167, 139, 250, 0.1); display: flex; align-items: center; justify-content: center; flex-shrink: 0; }
-        @media (max-width: 640px) { .grid-cols-2 { grid-template-columns: 1fr; } .grid-cols-3 { grid-template-columns: 1fr; } }
-    </style>
-</head>
-<body>
-    <div class="bg-layer"></div>
-    <div class="overlay"></div>
-
-    <div class="container">
-        <!-- Header -->
-        <div class="glass-card p-6 mb-6">
-            <div class="flex items-center gap-4">
-                <div class="icon-box flex-shrink-0">
-                    <svg style="width:1.75rem;height:1.75rem;color:#a78bfa" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 15v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2zm10-10V7a4 4 0 00-8 0v4h8z" />
-                    </svg>
-                </div>
-                <div class="flex-1">
-                    <div class="flex items-center gap-3">
-                        <h1 class="text-2xl font-bold">Nostr VPN</h1>
-                        <span class="text-xs text-white-50">v0.3.4</span>
-                    </div>
-                    <p class="text-white-60 text-sm">Decentralized mesh VPN with Nostr signaling</p>
-                </div>
-                <div class="info-card flex items-center gap-3">
-                    <div id="statusDot" class="status-dot bg-yellow animate-pulse"></div>
-                    <div>
-                        <p class="text-xs text-white-50">Status</p>
-                        <p class="text-sm font-medium" id="statusText">Checking...</p>
-                    </div>
-                </div>
-            </div>
-        </div>
-
-        <!-- What It Does -->
-        <div class="glass-card p-5 mb-6">
-            <h2 class="text-lg font-semibold mb-4" style="color:#a78bfa">What is Nostr VPN?</h2>
-            <p class="text-white-70 text-sm mb-4" style="line-height:1.6">
-                Nostr VPN creates a <strong style="color:white">private mesh network</strong> between your devices using WireGuard tunnels.
-                Unlike traditional VPNs, there is no central server. Peers discover each other and exchange encryption keys over
-                <strong style="color:white">Nostr relays</strong>, making the network censorship-resistant and self-sovereign.
-                Think of it as <strong style="color:white">Tailscale, but decentralized</strong> — your node's Nostr identity is your network identity.
-            </p>
-            <div class="grid grid-cols-3 gap-3">
-                <div class="info-card flex items-center gap-3">
-                    <div class="feature-icon">
-                        <svg style="width:1.25rem;height:1.25rem;color:#a78bfa" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 11V7a4 4 0 118 0m-4 8v2m-6 4h12a2 2 0 002-2v-6a2 2 0 00-2-2H6a2 2 0 00-2 2v6a2 2 0 002 2z"/></svg>
-                    </div>
-                    <div>
-                        <p class="text-sm font-medium">No Central Server</p>
-                        <p class="text-xs text-white-50">Fully peer-to-peer mesh</p>
-                    </div>
-                </div>
-                <div class="info-card flex items-center gap-3">
-                    <div class="feature-icon">
-                        <svg style="width:1.25rem;height:1.25rem;color:#a78bfa" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 10V3L4 14h7v7l9-11h-7z"/></svg>
-                    </div>
-                    <div>
-                        <p class="text-sm font-medium">WireGuard Tunnels</p>
-                        <p class="text-xs text-white-50">Fast, modern encryption</p>
-                    </div>
-                </div>
-                <div class="info-card flex items-center gap-3">
-                    <div class="feature-icon">
-                        <svg style="width:1.25rem;height:1.25rem;color:#a78bfa" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3.055 11H5a2 2 0 012 2v1a2 2 0 002 2 2 2 0 012 2v2.945M8 3.935V5.5A2.5 2.5 0 0010.5 8h.5a2 2 0 012 2 2 2 0 104 0 2 2 0 012-2h1.064M15 20.488V18a2 2 0 012-2h3.064"/></svg>
-                    </div>
-                    <div>
-                        <p class="text-sm font-medium">NAT Traversal</p>
-                        <p class="text-xs text-white-50">Works behind firewalls</p>
-                    </div>
-                </div>
-            </div>
-        </div>
-
-        <!-- Node Identity -->
-        <div class="glass-card p-5 mb-6">
-            <h2 class="text-lg font-semibold mb-4" style="color:#a78bfa">Node Identity</h2>
-            <p class="text-white-60 text-sm mb-4">Your node's Nostr public key is used as its network identity. Share it with peers to connect.</p>
-            <div class="mb-4">
-                <div class="field-label">Nostr Public Key (npub)</div>
-                <div class="field-row">
-                    <span class="field-value" id="npub">Loading...</span>
-                    <button class="copy-btn" onclick="copyField('npub', this)" title="Copy">
-                        <svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24"><rect x="9" y="9" width="13" height="13" rx="2" ry="2" stroke-width="2"/><path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" stroke-width="2"/></svg>
-                    </button>
-                </div>
-            </div>
-            <div>
-                <div class="field-label">VPN Listen Port</div>
-                <div class="field-row">
-                    <span class="field-value">51820/udp</span>
-                    <button class="copy-btn" onclick="copyText('51820', this)" title="Copy">
-                        <svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24"><rect x="9" y="9" width="13" height="13" rx="2" ry="2" stroke-width="2"/><path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" stroke-width="2"/></svg>
-                    </button>
-                </div>
-            </div>
-        </div>
-
-        <!-- How to Use -->
-        <div class="glass-card p-5 mb-6">
-            <h2 class="text-lg font-semibold mb-4" style="color:#a78bfa">How to Use</h2>
-            <div class="flex flex-col gap-4">
-                <div class="step">
-                    <div class="step-num">1</div>
-                    <div>
-                        <p class="text-sm font-semibold mb-2">Install the Nostr VPN client on your device</p>
-                        <p class="text-xs text-white-60" style="line-height:1.5">Download <code style="background:rgba(255,255,255,0.1);padding:0.125rem 0.375rem;border-radius:0.25rem">nvpn</code> from <a href="https://github.com/mmalmi/nostr-vpn/releases" style="color:#a78bfa;text-decoration:underline" target="_blank">GitHub Releases</a> on your laptop, phone, or other devices you want to connect.</p>
-                    </div>
-                </div>
-                <div class="step">
-                    <div class="step-num">2</div>
-                    <div>
-                        <p class="text-sm font-semibold mb-2">Create or join a network</p>
-                        <p class="text-xs text-white-60" style="line-height:1.5">Run <code style="background:rgba(255,255,255,0.1);padding:0.125rem 0.375rem;border-radius:0.25rem">nvpn network create</code> on this node to create a new network, or join an existing one with an invite code. Each network gets a unique ID shared between members.</p>
-                    </div>
-                </div>
-                <div class="step">
-                    <div class="step-num">3</div>
-                    <div>
-                        <p class="text-sm font-semibold mb-2">Connect your devices</p>
-                        <p class="text-xs text-white-60" style="line-height:1.5">Run <code style="background:rgba(255,255,255,0.1);padding:0.125rem 0.375rem;border-radius:0.25rem">nvpn start --daemon --connect</code> on each device. Peers discover each other automatically over Nostr relays and establish direct WireGuard tunnels. Your devices are now privately connected.</p>
-                    </div>
-                </div>
-            </div>
-        </div>
-
-        <!-- Container Status -->
-        <div class="glass-card p-5">
-            <h2 class="text-lg font-semibold mb-4" style="color:#a78bfa">Container Logs</h2>
-            <div id="logs" style="background:rgba(0,0,0,0.4);border-radius:0.5rem;padding:0.75rem;font-family:monospace;font-size:0.75rem;color:rgba(255,255,255,0.6);max-height:200px;overflow-y:auto;line-height:1.6">
-                Fetching logs...
-            </div>
-        </div>
-    </div>
-
-    <script>
-        var COPY_SVG = '<svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24"><rect x="9" y="9" width="13" height="13" rx="2" ry="2" stroke-width="2"/><path d="M5 15H4a2 2 0 01-2-2V4a2 2 0 012-2h9a2 2 0 012 2v1" stroke-width="2"/></svg>';
-        var CHECK_SVG = '<svg width="16" height="16" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7"/></svg>';
-
-        function flashCopied(btn) { btn.classList.add('copied'); var o = btn.innerHTML; btn.innerHTML = CHECK_SVG; setTimeout(function() { btn.classList.remove('copied'); btn.innerHTML = o; }, 1500); }
-        function copyField(id, btn) { var t = document.getElementById(id).textContent.trim(); if (!t || t === 'Loading...') return; navigator.clipboard.writeText(t).then(function() { flashCopied(btn); }); }
-        function copyText(text, btn) { navigator.clipboard.writeText(text).then(function() { flashCopied(btn); }); }
-
-        async function fetchNodeIdentity() {
-            try {
-                var resp = await fetch('/rpc/', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'node.nostr-pubkey', params: {} }) });
-                var data = await resp.json();
-                if (data.result && data.result.npub) {
-                    document.getElementById('npub').textContent = data.result.npub;
-                } else if (data.result && data.result.pubkey) {
-                    document.getElementById('npub').textContent = data.result.pubkey;
-                }
-            } catch(e) { document.getElementById('npub').textContent = 'Unavailable'; }
-        }
-
-        async function fetchStatus() {
-            try {
-                var resp = await fetch('/rpc/', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'package.info', params: { id: 'nostr-vpn' } }) });
-                var data = await resp.json();
-                var dot = document.getElementById('statusDot');
-                var txt = document.getElementById('statusText');
-                if (data.result && data.result.state === 'running') {
-                    dot.className = 'status-dot bg-green'; txt.textContent = 'Running';
-                } else if (data.result && data.result.state === 'stopped') {
-                    dot.className = 'status-dot bg-red'; txt.textContent = 'Stopped';
-                } else {
-                    dot.className = 'status-dot bg-yellow animate-pulse'; txt.textContent = data.result ? data.result.state : 'Unknown';
-                }
-            } catch(e) { /* keep checking */ }
-        }
-
-        async function fetchLogs() {
-            try {
-                var resp = await fetch('/api/container/logs?app_id=nostr-vpn&lines=30');
-                if (resp.ok) {
-                    var data = await resp.json();
-                    var logs = data.logs || data.stdout || '';
-                    if (typeof logs === 'object') logs = JSON.stringify(logs);
-                    document.getElementById('logs').textContent = logs || 'No logs available yet.';
-                    var el = document.getElementById('logs');
-                    el.scrollTop = el.scrollHeight;
-                }
-            } catch(e) { document.getElementById('logs').textContent = 'Waiting for container...'; }
-        }
-
-        fetchNodeIdentity();
-        fetchStatus();
-        fetchLogs();
-        setInterval(fetchStatus, 10000);
-        setInterval(fetchLogs, 15000);
-    </script>
-</body>
-</html>
@@ -1,11 +0,0 @@
-server {
-    listen 8201;
-    server_name _;
-
-    root /usr/share/nginx/html;
-    index index.html;
-
-    location / {
-        try_files $uri $uri/ /index.html;
-    }
-}
@@ -0,0 +1,58 @@
+# Marketplace QA — app-by-app install walk
+
+Purpose: track install/launch/uninstall health for every app in the marketplace catalog on `.228`. User installs each app one by one; for each broken one we triage, fix at the right layer (app recipe / registry image / backend / frontend), commit, redeploy, and re-verify.
+
+Target build: `v1.7.43-alpha` + backend md5 `9b8ead06aaf210b85cd78fce270384e3` (image-versions path fix included).
+
+## Status key
+
+- ✅ install, launch, uninstall all clean
+- ⚠️  installs and runs but has cosmetic or partial issues (note in details)
+- ❌ broken — fix needed
+- ⏳ pending verification
+
+## Catalog
+
+Pull the authoritative list from Marketplace page on `.228` during the walk. Fill in as you go.
+
+| App | Status | Notes / fix applied |
+|---|---|---|
+| _(to be filled during walk)_ | ⏳ | |
+
+## Known issues going in
+
+- **Vaultwarden** — container exits immediately on start. Pre-existing. Backend async wrapper correctly detects + removes the install state entry. Needs container-config investigation (image pin / env vars / volume layout).
+
+## Fix layers cheat-sheet
+
+When an app breaks, identify which layer to fix at:
+
+1. **App recipe** — `apps/<app>/package.yaml` or wherever the Podman manifest lives. Ports, volumes, env vars, healthcheck, resource caps.
+2. **Registry image** — if image itself is missing/wrong-tag on `.168`:3000/lfg2025 or `git.tx1138.com`. Push corrected image, bump `scripts/image-versions.sh`.
+3. **Backend orchestrator** — `core/archipelago/src/container/` or `core/archipelago/src/api/rpc/package/` if the install flow mishandles this app's shape.
+4. **Frontend** — `neode-ui/src/views/marketplace/` or curated data in `neode-ui/src/views/marketplace/marketplaceData.ts` if catalog entry is wrong or UI can't render this app correctly.
+
+## Per-app fix workflow
+
+For each broken app:
+
+1. Capture failure mode:
+   ```
+   ssh archy228 'sudo journalctl -u archipelago --since "5 minutes ago" --no-pager | tail -80'
+   ssh archy228 'podman ps -a --format "{{.Names}}\t{{.Status}}\t{{.Image}}" | grep <app>'
+   ssh archy228 'podman logs <container-name> 2>&1 | tail -60'
+   ```
+2. Diagnose — which layer.
+3. Fix in repo (use SSHFS mount for edits).
+4. `cargo check` if backend changed; `npm run build` if frontend changed.
+5. Commit with `fix(app/<name>): ...` or `fix(registry/<image>): ...` etc.
+6. Redeploy as needed (binary via Mac ferry; frontend via rsync; registry via podman push).
+7. User re-verifies on `.228`. Mark ✅.
+
+## Release-notes policy
+
+For each app fix, append a bullet to the current in-flight release entry in `neode-ui/src/views/settings/AccountInfoSection.vue`. If the fix pile gets large enough to warrant its own release, bump to v1.7.44-alpha and start a new block at the top. Keep entries operator-focused ("Nostr Relay no longer crashes on first start"), not implementation-focused.
+
+## Running log
+
+_Add dated notes here as we progress through the catalog._
@@ -0,0 +1,190 @@
+# RESUME — Install UX polish round (v1.7.43-alpha)
+
+Last updated: 2026-04-23
+
+Read this first if you're a fresh OpenCode session resuming the install/uninstall/update UX work.
+
+---
+
+## Where we are right now
+
+**v1.7.43-alpha shipped and deployed to .228**. Latest addition: image-versions.sh path bug fixed (silent update-check failure on all production nodes). User is about to walk the marketplace app-by-app on `.228` to shake out any remaining broken apps. Tracker for that walk: `docs/MARKETPLACE-QA.md`.
+
+Commits on `.116:main` (newest first, unpushed per user mirror protocol):
+- `a9908597` fix(image-versions): locate image-versions.sh at its actual deployed path
+- `013e8df0` docs(resume): add RESUME.md for context-restart recovery
+- `f9fef8d2` docs(status): record rounds 3-5 + config migration + changelog as shipped
+- `008da477` docs(changelog): add v1.7.43-alpha entry covering async lifecycle + .23 retirement
+- `0ee16820` fix(config): auto-purge decommissioned .23 VPS from saved registry/mirror configs
+- `22052325` chore: retire .23 VPS mirror, promote .168 OVH to primary
+- `f86d86c3` fix(install): kick scanner post-install so Launch button appears immediately
+- `8cc84ebc` feat(install): phase-based progress bar replaces unparseable pull bytes
+- `2d5b859e` feat(rpc): async-spawn install/uninstall/update lifecycle (Round 2)
+- `0733ac40` fix(ui): shorten install/uninstall/update timeouts for async RPCs (Round 2)
+- `e471ef75` fix(rpc): empty icon in transient install entry (Round 2)
+
+**Deployed artifacts on .228**:
+- Backend: `/usr/local/bin/archipelago` md5 `9b8ead06aaf210b85cd78fce270384e3` (includes image-versions path fix)
+- Frontend: `/opt/archipelago/web-ui/` (v1.7.43-alpha changelog with 5 bullets, .168-only registry)
+- Rollback backups: `/usr/local/bin/archipelago.bak-pre-async-install` + `/opt/archipelago/web-ui.bak-pre-async-install/`
+
+**Rollback command** (if catastrophic):
+```
+ssh archy228 'sudo cp -a /usr/local/bin/archipelago.bak-pre-async-install /usr/local/bin/archipelago && sudo rsync -a --delete /opt/archipelago/web-ui.bak-pre-async-install/ /opt/archipelago/web-ui/ && sudo systemctl restart archipelago && sudo systemctl reload nginx'
+```
+
+---
+
+## Immediate next step
+
+**Phase 1 — browser verification of v1.7.43-alpha on https://192.168.1.228/**
+
+1. Settings → About: top changelog entry reads "v1.7.43-alpha · Apr 23, 2026" with **5** bullets. Last bullet mentions "Update-available badges and version comparisons work again across every app." Hard-refresh (Cmd+Shift+R) if stale.
+2. Settings → App Registries: only `146.59.87.168:3000/lfg2025` + `git.tx1138.com`. No .23.
+3. Settings → System Update → Update Mirrors: only `.168` (Server 1 primary) + `tx1138` (Server 2). No .23.
+4. Install SearXNG (small, fast image). Expect: instant button response, 7 phase labels in progress bar (Preparing → Pulling image → Creating container → Starting container → Waiting for healthy → Finalizing → Done), Launch button appears within ~3s of "Done".
+5. Uninstall: snappy, no freeze.
+
+**Phase 2 — marketplace walk (app-by-app on .228)**
+
+Once Phase 1 is clean, user will install every app in the marketplace catalog one by one. Tracker: `docs/MARKETPLACE-QA.md`. For each broken app:
+- Triage via `journalctl -u archipelago`, `podman ps -a`, `podman logs <name>`.
+- Identify layer: app recipe / registry image / backend / frontend.
+- Fix, commit `fix(app/<name>): ...` or similar.
+- Redeploy as needed.
+- Append release-note bullet for the fix (to current in-flight version, or bump to v1.7.44-alpha if the pile grows).
+- User re-verifies, mark ✅ in the tracker.
+
+Known pre-existing issue to expect: **Vaultwarden** container exits immediately on start. Backend correctly detects + removes state entry; needs container-config debug.
+
+---
+
+## Overall mission (unchanged)
+
+User mandate: _"best server containers in the world"_. Polish install/uninstall/update flows for all 6 bundled server containers + marketplace apps before release. Tackle UX issues one by one in order.
+
+---
+
+## Working layout — SSH + SSHFS
+
+- SSHFS mount: `/Users/dorian/mnt/archy-thinkpad/` → `archy:Projects/archy/`. Use for all file ops (read/edit/write/glob/grep).
+- Direct SSH: `ssh archy` (= `archipelago@192.168.1.116`, ThinkPad dev). Use for git/cargo/npm/systemctl.
+- Demo node: `ssh archy228` (= `archipelago@192.168.1.228`). NOPASSWD sudo. Dashboard login pw: `password123`.
+- Sudo pw on .116: `ThisIsWeb54321@`. Fallback sudo pw on .228: `archipelago`.
+- Cargo: `~/.cargo/bin/cargo` on .116. Long builds: `nohup ... & disown` to `/tmp/cargo-build-*.log`.
+- SSHFS flake: `write` sometimes returns `NotFound: FileSystem.readFile` on new files — retry once.
+
+## Deploy recipes
+
+**Backend binary** (can't cp while running — "Text file busy"; binary ferries via Mac because .116 can't resolve archy228):
+```
+# On .116:
+~/.cargo/bin/cargo build --release   # ~3.5 min
+# From Mac:
+scp archy:Projects/archy/core/target/release/archipelago /tmp/archipelago-new
+scp /tmp/archipelago-new archy228:/tmp/archipelago-new
+ssh archy228 'sudo systemctl stop archipelago && sudo cp /tmp/archipelago-new /usr/local/bin/archipelago && sudo systemctl start archipelago && sudo systemctl reload nginx'
+```
+
+**Frontend** (rsyncs via Mac):
+```
+ssh archy 'cd ~/Projects/archy/neode-ui && npm run build'   # outputs to ../web/dist/neode-ui/
+rsync -az --delete archy:Projects/archy/web/dist/neode-ui/ /tmp/archy-web/
+rsync -az /tmp/archy-web/ archy228:/tmp/archy-web/
+ssh archy228 'sudo rsync -a --delete /tmp/archy-web/ /opt/archipelago/web-ui/ && sudo systemctl reload nginx'
+```
+
+Note: frontend source is `neode-ui/` (has package.json). `web/` has no package.json; `web/dist/neode-ui/` is the build output.
+
+## Commit protocol
+
+- Never push. User mirrors to Gitea remotes manually.
+- Conventional Commits. No em-dashes or fancy punctuation.
+- Multi-line messages via `tmp-commit-msg.txt`: `git commit -F tmp-commit-msg.txt && rm tmp-commit-msg.txt`.
+- Git remotes on .116: `gitea-local`, `gitea-vps2` (.168 OVH), `tx1138` (canonical), `origin` (multi-push alias). `.23` URLs were removed from origin and `gitea-vps` remote was deleted — working-copy change, not in any commit.
+
+## Verification gates
+
+1. `cargo check`
+2. `cargo test -p archipelago --bin archipelago <filter>` (MUST use `--bin archipelago`; no lib target)
+3. `cargo build --release`
+
+Known issues:
+- `rust-lld: undefined hidden symbol` → cargo bug with test+release incremental collision. Fix: `rm -rf core/target/debug/incremental` and retry.
+- 22 pre-existing `cargo test` failures in unrelated modules (mesh/wallet/credentials/avatar/session/transport/update-mirrors/fips/identity_manager/image_versions). Not blocking. Tech debt.
+
+---
+
+## Architecture — locked-in patterns
+
+### Async-spawn lifecycle (install/update/uninstall/start/stop/restart)
+
+- RPC returns `{status, package_id}` immediately (15s client timeout).
+- Wrapper flips state to transitional variant (Installing/Updating/Removing/Stopping/Starting/Restarting) BEFORE spawn.
+- `tokio::spawn` runs existing monolithic inner handler with `self: Arc<Self>`.
+- Install/update success: MUST explicitly write terminal Running state. `merge_preserving_transitional` in `server.rs` refuses to let scanner overwrite transitional states.
+- Uninstall success: inner handler removes the entry itself.
+- On error: revert pre-transition state (or remove entry for install).
+
+Key files:
+- `core/archipelago/src/api/rpc/package/async_lifecycle.rs` — full install/update/uninstall wrappers
+- `core/archipelago/src/api/rpc/transitional.rs` — start/stop/restart wrappers
+- `core/archipelago/src/server.rs:832-871` — `merge_preserving_transitional`, `is_transitional`
+- `core/archipelago/src/server.rs:295-380` — scan loop with `tokio::select!` and tick bump
+
+### Install progress (phase-based, 7 levels)
+
+- `podman pull` emits zero parseable progress when stderr is piped (no TTY). Legacy byte regex never matched.
+- Phases + UI %: Preparing (5) → PullingImage (20) → CreatingContainer (70) → StartingContainer (80) → WaitingHealthy (88) → PostInstall (95) → Done (100).
+- UI bar only advances forward (`Math.max`).
+- Final phase label is "Finalizing…" (renamed from "Running post-install…" which confused users).
+
+Key files:
+- `neode-ui/src/stores/server.ts:25-33` — `PHASE_INFO` mapper
+
+### Scanner kick (instant Launch button)
+
+- Scan runs every 60s. Post-install state flipped to Running but skeletal manifest (`interfaces: None`) persisted until next scan → `canLaunch(pkg)` false for up to 60s.
+- `lan_address` derived from live container port bindings. `manifest.interfaces.main.ui` only populated when `lan_address.is_some() || tor_address.is_some()`.
+- Fix: `scan_kick: Arc<Notify>` + `scan_tick: Arc<watch::Sender<u64>>` on `RpcHandler`. Scan loop `tokio::select!` between 60s tick + notify. `kick_scanner_and_wait` helper (2s timeout) called in install/update success paths BEFORE writing Running. Merge during Installing keeps state + takes fresh manifest.
+
+Key files:
+- `core/archipelago/src/api/rpc/mod.rs:89-93` — fields on RpcHandler; accessors :186-199
+- `core/archipelago/src/api/rpc/package/async_lifecycle.rs:405-430` — `kick_scanner_and_wait`
+- `core/archipelago/src/container/docker_packages.rs:132-218` — where `lan_address` + manifest get populated
+- `neode-ui/src/views/apps/appsConfig.ts:106-111` — `canLaunch(pkg)`
+- `neode-ui/src/views/apps/AppCard.vue:141-149` — Launch button render
+
+### Config migration (.23 auto-purge)
+
+- `load_mirrors` + `load_registries` normally only ADD missing defaults ("explicit removals stick").
+- .23 was a default the user never chose, so we need the opposite: strip it.
+- `.retain(|m| !m.url.contains("23.182.128.160"))` before defaults-merge step. Narrow-scope exception, commented in-code.
+- Triggers lazily on next load (install RPC, update RPC, Settings UI open). Not tied to boot.
+
+Key files:
+- `core/archipelago/src/container/registry.rs` — `load_registries`
+- `core/archipelago/src/update.rs` — `load_mirrors`
+
+---
+
+## Backlog — after v1.7.43 verification
+
+1. User reports browser-verification results. Fix anything that fails.
+2. Continue user's "one by one" install/uninstall/update UX queue — ask for next issue.
+3. Tech debt (low priority, not blocking release):
+   - Vaultwarden container exits immediately on start (separate container-config issue).
+   - 22 pre-existing cargo test failures in unrelated modules.
+   - "Server 3 (OVH)" historical changelog entries in `AccountInfoSection.vue` left intact (user approved — they're release notes for what shipped at the time).
+
+---
+
+## User preferences (must follow)
+
+- Always state which option is "best long-term" first and explain why in plain terms. Trust my recommendation unless overridden.
+- "Tackle them one by one in order" — fix issues sequentially, not in a big bang.
+- Bitcoin-only. No altcoins, no proprietary deps without approval.
+- Prefer established OSS, crypto-first libs (rustls, argon2, ed25519), privacy-focused (no telemetry), minimal dep trees.
+- Atomic commits.
+- Never commit secrets. Pin dependency versions.
+- Never push — user mirrors to Gitea manually.
@@ -0,0 +1,667 @@
+# RESUME HERE — Rust orchestrator migration
+
+Updated: 2026-04-23 (Install UX polish: phase-based progress bar, post-install scanner kick for instant Launch button, .23 VPS retired with auto-purge migration, frontend/backend deployed to .228 as v1.7.43-alpha.)
+
+**To resume this work, SSH into the ThinkPad and run `opencode` from `~/Projects/archy/`. Or work from the laptop via the SSHFS mount at `~/mnt/archy-thinkpad/`.**
+
+---
+
+## ✅ INSTALL UX POLISH + .23 RETIREMENT — SHIPPED (v1.7.43-alpha)
+
+**Rounds 3–5 + config migration + changelog (2026-04-23)** — 5 commits on `main` (unpushed per user mirror protocol):
+
+- `8cc84ebc` `feat(install): phase-based progress bar replaces unparseable pull bytes` — `podman pull` emits zero parseable progress when stderr is piped (no TTY), so the legacy byte-counting regex never matched. Replaced with 7 phase-based levels: Preparing (5%) → PullingImage (20%) → CreatingContainer (70%) → StartingContainer (80%) → WaitingHealthy (88%) → PostInstall (95%) → Done (100%). UI maps phases to fixed % and only advances forward (`Math.max`). Final phase label renamed from "Running post-install…" to "Finalizing…" after user feedback that it read like a regression to the install step.
+- `f86d86c3` `fix(install): kick scanner post-install so Launch button appears immediately` — scan runs every 60s; post-install the state flipped to Running but the skeletal install-time manifest (`interfaces: None`) persisted until next scan, so `canLaunch(pkg)` returned false for up to a minute. Added `scan_kick: Arc<Notify>` + `scan_tick: Arc<watch::Sender<u64>>` on `RpcHandler`. Scan loop uses `tokio::select!` between the 60s interval and the notify. New `kick_scanner_and_wait` helper (2s timeout) called in install/update success paths BEFORE writing Running, so a fresh manifest lands first. Merge during Installing/Updating uses `merge_preserving_transitional` (keeps state, takes fresh manifest).
+- `22052325` `chore: retire .23 VPS mirror, promote .168 OVH to primary` — dropped `DEFAULT_TERTIARY_MIRROR_URL`, promoted `.168` to `DEFAULT_SECONDARY_MIRROR_URL` as "Server 1 (OVH)". 2-entry default registry (.168 priority 0, tx1138 priority 10). Trusted-registry allowlist, catalog fallback, installer ISO registries, `marketplaceData.ts` REGISTRY, `image-versions.sh` all updated. Tests updated for new default counts (registry 3→2, mirror 3→2). URL-parser fixture tests in `update.rs` retain `.23` strings intentionally — they exercise string-parsing logic, not policy.
+- `0ee16820` `fix(config): auto-purge decommissioned .23 VPS from saved registry/mirror configs` — `load_mirrors`/`load_registries` normally only ADD missing defaults (explicit removals stick, by design). Existing nodes have `.23` baked into their saved `update-mirrors.json` + `config/registries.json` and would pay timeouts forever against a dead host. Added targeted one-time migration in both loaders: `.retain(|m| !m.url.contains("23.182.128.160"))` before the defaults-merge step. Narrow-scope exception to the stickiness rule, documented in-code. Triggers lazily on next load (install RPC, update RPC, Settings UI open).
+- `008da477` `docs(changelog): add v1.7.43-alpha entry covering async lifecycle + .23 retirement` — 4 release-note bullets in `AccountInfoSection.vue` describing async-spawn, phase progress, scanner kick, and .23 retirement from the operator's perspective. Historical "Server 3 (OVH)" entries in older changelog blocks left intact — they describe what shipped at the time.
+
+**Deployed to .228**:
+- Backend binary md5 `d2b619949f19815faaeab10429e36ba0` at `/usr/local/bin/archipelago`.
+- Frontend at `/opt/archipelago/web-ui/` (includes marketplaceData.ts .168 update + v1.7.43-alpha changelog entry). Deployed bundle verified: `.168` present in `Settings-*.js` + `Marketplace-*.js`, `.23` absent from all assets.
+- `/var/lib/archipelago/update-mirrors.json` + `config/registries.json` were manually deleted + regenerated with new defaults during Round 5 verification; migration code will handle any other node on first load.
+- Rollback targets from Round 2 still valid: `/usr/local/bin/archipelago.bak-pre-async-install` + `/opt/archipelago/web-ui.bak-pre-async-install/`.
+
+**Git remotes cleaned on .116** (working-copy change only, not in any commit):
+- `git remote remove gitea-vps` (dropped the .23 Gitea remote).
+- `git remote set-url --delete --push origin http://.../23.182.128.160:3000/...` (dropped .23 from origin multi-push alias).
+- Remaining push targets: `tx1138` (canonical), `gitea-local` (localhost Gitea), `gitea-vps2` (.168 OVH).
+
+**Rollback Rounds 3–5** (same command as Round 2 — backups predate all of this):
+```
+ssh archy228 'sudo cp -a /usr/local/bin/archipelago.bak-pre-async-install /usr/local/bin/archipelago && sudo rsync -a --delete /opt/archipelago/web-ui.bak-pre-async-install/ /opt/archipelago/web-ui/ && sudo systemctl restart archipelago && sudo systemctl reload nginx'
+```
+
+---
+
+## ✅ ASYNC-SPAWN LIFECYCLE FIX — SHIPPED (Stop/Start/Restart + Install/Uninstall/Update)
+
+**Round 2 (2026-04-23, install/uninstall/update)** — 3 commits on `main`:
+
+- `2d5b859e` `feat(rpc): async-spawn install/uninstall/update lifecycle` — new `api/rpc/package/async_lifecycle.rs` with `spawn_package_install`, `spawn_package_uninstall`, `spawn_package_update`. Dispatcher + handler thread `self: Arc<Self>` so spawned tasks own their Arc. Install/update Ok arms explicitly set `Running` because `merge_preserving_transitional` refuses to let the scanner overwrite `Installing`/`Updating`. Removed redundant inner "already updating" guard in `update.rs`. Transient install entry uses empty icon (see commit 3 rationale).
+- `0733ac40` `fix(ui): shorten install/uninstall/update timeouts for async RPCs` — drop 11m/45m timeouts to 15s across `rpc-client.ts`, `stores/server.ts`, and the 5 direct call sites in `Marketplace.vue`, `Discover.vue`, `MarketplaceAppDetails.vue`. Return types updated to `{ status, package_id }`.
+- `e471ef75` `fix(rpc): empty icon in transient install entry to avoid broken-image flicker` — `progress.rs::create_installing_entry` no longer hardcodes `/assets/img/app-icons/<id>.png`. About half of bundled apps use `.svg`/`.webp` icons; the frontend's fallback chain (`backend_icon || curated.icon || placeholder`) now lands on the correct curated extension.
+
+**Deployed to .228** (binary md5 `f66857b3b8b3640c8cac8bd25fe508ec` at `/usr/local/bin/archipelago`, backup at `/usr/local/bin/archipelago.bak-pre-async-install`; frontend at `/opt/archipelago/web-ui/`, backup at `/opt/archipelago/web-ui.bak-pre-async-install/`). User confirmed: uninstall fast and responsive, install of LND + SearXNG clean, icon flicker fixed.
+
+**Known out-of-scope issue**: Vaultwarden container itself exits immediately on start with an internal error. The async wrapper correctly detects this via post-start exit verification and removes the state entry. Needs separate vaultwarden container-config investigation.
+
+**Rollback Round 2 (if ever needed)**:
+```
+ssh archy228 'sudo cp -a /usr/local/bin/archipelago.bak-pre-async-install /usr/local/bin/archipelago && sudo rsync -a --delete /opt/archipelago/web-ui.bak-pre-async-install/ /opt/archipelago/web-ui/ && sudo systemctl restart archipelago && sudo systemctl reload nginx'
+```
+
+---
+
+**Round 1 (Stop/Start/Restart)** — 4 commits on `main` (unpushed per user mirror protocol):
+
+- `44cd5eef` `feat(rpc): spawn_transitional helper for async lifecycle ops` — new `api/rpc/transitional.rs` with `Op::{Stop,Start,Restart}` and `RpcHandler::spawn_transitional` / `flip_to_transitional` / `set_state` helpers. `install_log` re-exported so sibling modules can use it.
+- `19a99ca9` `fix(rpc): async container stop/start/restart; widen state mapping` — `container.rs` start/stop rewritten + restart added; `container-list` now emits all transitional variants instead of falling back to `"unknown"`. `dispatcher.rs` registers `container-restart`. `package/runtime.rs` mirrored with `do_package_*` helpers inside `tokio::spawn` and revert-on-error.
+- `6712810b` `fix(state): preserve transitional state across container scans` — `server.rs` scan merge now keeps transitional states while taking fresh observability fields; 1200s stuck-timeout escape hatch via `transitional_since: HashMap<String, Instant>`. Three passing `server::merge_tests`.
+- `9ce28f08` `fix(ui): single-button lifecycle control with transitional labels` — `ContainerApps.vue` and `ContainerAppDetails.vue` use a single primary button driven by `getAppVisualState()`. **Dashboard now routes through `container-start`/`container-stop`** (the async RPCs) instead of the legacy synchronous `bundled-app-*` path. `ContainerStatus.vue` widened to render all new variants.
+
+**Deployed to .228** (ThinkPad demo device):
+- Binary at `/usr/local/bin/archipelago` (md5 `de86b63f74c7e6fe6e555ffe30b86b4f`), backup at `/usr/local/bin/archipelago.bak-pre-async-stop`.
+- Frontend at `/opt/archipelago/web-ui/`, backup at `/opt/archipelago/web-ui.bak-pre-async-stop/`.
+- Release build took 3m56s on .116. Deploy via scp + atomic `install -m 755` + `systemctl restart archipelago`. `nginx -t` + `systemctl reload nginx` for frontend.
+
+**Manual verification**: user clicked Stop on LND in the dashboard. Button flipped to `Stopping…` instantly, held for the full graceful-stop window, transitioned to `Start` when `podman stop` completed. No mid-flight revert to Running. User sign-off: _"absolutely beautiful"_.
+
+**Rollback (if ever needed)**:
+```
+ssh archy228 'sudo cp /usr/local/bin/archipelago.bak-pre-async-stop /usr/local/bin/archipelago && sudo rsync -a --delete /opt/archipelago/web-ui.bak-pre-async-stop/ /opt/archipelago/web-ui/ && sudo systemctl restart archipelago && sudo systemctl reload nginx'
+```
+
+### Follow-ups to consider
+
+1. **Chaos matrix / Step 11** — the original next-step gated behind this fix. Now unblocked.
+2. **bundled-app-start / bundled-app-stop** — still synchronous in the backend. Dashboard no longer calls them, but the RPC methods remain for any external caller. Decide: deprecate, or mirror the async-spawn treatment for parity.
+3. **`transitional_since` persistence** — currently in-memory only, so a backend restart mid-stop loses the timeout anchor. Acceptable for now (scan loop re-observes live podman state and reconciles), but worth revisiting if crash-recovery stories tighten.
+4. **Test regressions inventory** — the full `cargo test -p archipelago` run on .116 shows 22 pre-existing failures in unrelated modules (mesh/wallet/credentials/avatar/session/transport/update-mirrors/fips/identity_manager/image_versions). Unrelated to this work but tech debt. Log at `/tmp/cargo-test-all.log` on .116.
+5. **Amend STATUS.md's older "NEXT SESSION — START HERE" section** (below) — it is now stale. Left in place for historical reference of how the fix was designed; delete on the next pass if it gets confusing.
+
+---
+
+## ⚡ NEXT SESSION — START HERE (historical — fix above is now shipped)
+
+**Goal**: implement async-spawn lifecycle fix so the dashboard never shows a frozen spinner again. User mandate: _"best server containers in the world"_. Do not ship the chaos matrix (Step 11) until this lands and manual LND stop verifies instant RPC + live `Stopping…` label.
+
+### How to work on this repo (SSH + SSHFS setup)
+
+You are likely running on the **laptop** (macOS). The repo lives on the **ThinkPad** (.116). There are two access paths, use both in parallel:
+
+1. **SSHFS mount at `~/mnt/archy-thinkpad/`** — for all file ops (`read`/`edit`/`write`/`glob`/`grep`).
+2. **Direct SSH** — for everything that isn't file ops: `git`, `cargo`, `npm`, `systemctl`, running the server, tailing logs.
+
+See the "FUSE / SSHFS development loop" section below for the full mount lifecycle — that's _the_ thing that makes this dev setup work, and it will break periodically.
+
+### FUSE / SSHFS development loop
+
+**Why this exists**: editing the repo directly on the ThinkPad over raw SSH means no IDE, no tool-native file reads, no glob/grep speed. SSHFS mounts the remote filesystem as a local directory so OpenCode's file tools work transparently. But SSHFS is a leaky abstraction — know the gotchas or you'll waste hours.
+
+**Stack** (macOS laptop):
+- **macFUSE** — kernel extension providing FUSE on macOS. Install via `brew install --cask macfuse` (requires reboot + security approval in System Settings the first time).
+- **sshfs** — userspace mount tool. Install via `brew install gromgit/fuse/sshfs-mac` (the homebrew core `sshfs` was removed; use this tap).
+- Verify: `which sshfs` → `/opt/homebrew/bin/sshfs`, `sshfs --version` → `SSHFS version 2.10 / FUSE library version 2.9.9`.
+
+**Actual mount command currently running** (verified from `ps`):
+```
+sshfs archy:Projects/archy /Users/dorian/mnt/archy-thinkpad \
+  -o reconnect,ServerAliveInterval=15,ServerAliveCountMax=3,volname=archy-thinkpad
+```
+
+Breakdown:
+- `archy:Projects/archy` — remote path via the `archy` SSH alias (uses `~/.ssh/archy_opencode`, no password prompt).
+- `~/mnt/archy-thinkpad` — local mount point. Create once: `mkdir -p ~/mnt/archy-thinkpad`.
+- `reconnect` — sshfs auto-reconnects if the TCP session drops (WiFi flap, laptop sleep). Without this, the mount turns into a zombie immediately.
+- `ServerAliveInterval=15` — sends a keepalive every 15s.
+- `ServerAliveCountMax=3` — disconnect after 3 missed keepalives (45s). Tune up if your network is flaky.
+- `volname=archy-thinkpad` — Finder display name.
+
+**Check mount health**:
+```
+mount | grep archy-thinkpad
+# should print: archy:Projects/archy on /Users/dorian/mnt/archy-thinkpad (macfuse, nodev, nosuid, synchronous, mounted by dorian)
+
+ls ~/mnt/archy-thinkpad/ | head
+# should list repo contents fast (<1s). If it hangs, mount is stale.
+```
+
+**Recovery when the mount hangs / goes stale** (this WILL happen — laptop sleeps, WiFi drops, ThinkPad reboots):
+```
+# 1. Force-unmount (macOS — `umount` alone often fails on a hung FUSE mount)
+sudo diskutil unmount force ~/mnt/archy-thinkpad
+# fallback if diskutil can't see it:
+sudo umount -f ~/mnt/archy-thinkpad
+
+# 2. Kill any zombie sshfs process
+pkill -f "sshfs archy:Projects/archy"
+
+# 3. Remount
+sshfs archy:Projects/archy ~/mnt/archy-thinkpad \
+  -o reconnect,ServerAliveInterval=15,ServerAliveCountMax=3,volname=archy-thinkpad
+
+# 4. Verify
+ls ~/mnt/archy-thinkpad/ | head
+```
+
+If the mount point itself got wedged (`ls: /Users/dorian/mnt/archy-thinkpad: Device not configured`), the sequence above still works — macFUSE garbage-collects the inode after the force-unmount.
+
+**When to use which path** (rules, not suggestions):
+| Operation | Use | Why |
+|---|---|---|
+| `read` / `edit` / `write` | SSHFS mount | OpenCode tools want local paths |
+| `glob` / `grep` | SSHFS mount | Local FS traversal is fine; remote would need rg over SSH |
+| Reading many files | SSHFS mount | Each read is a round-trip but parallelizable |
+| `git status` / `git diff` / `git log` | SSH | Git over FUSE is painfully slow (lots of stat calls) |
+| `git add` / `git commit` | SSH | Same — commit times grow linearly with tree size on FUSE |
+| `cargo check` / `cargo test` / `cargo build` | SSH | Compiling over FUSE would take hours; cargo's incremental stat pattern destroys FUSE performance |
+| `npm install` / `npm run build` | SSH | Same reason — massive file churn |
+| Running the server / tailing journal | SSH | Service lives on .116 |
+| Deploying to .228 | SSH from .116 | SCP from ThinkPad; laptop isn't in the critical path |
+
+**Don't do this** (will bite you):
+- `cargo build` from the mount — will try to write target/ over FUSE, gets orders of magnitude slower, may hang.
+- `rsync` without `--exclude="._*"` — macOS writes AppleDouble metadata files, they leak to the remote as `._*` siblings of every real file. `.gitignore` already excludes them (commit `13858842`), but they clutter the tree.
+- Writing big binary files via the mount — use `scp` over SSH instead.
+- Relying on file-change-watcher tools (watchman, chokidar) — they get confused by FUSE event semantics.
+
+**Editing workflow in a typical session**:
+1. Laptop: OpenCode `read`s a file via `/Users/dorian/mnt/archy-thinkpad/...`. FUSE fetches it over SSH, caches briefly.
+2. Laptop: OpenCode `edit`s the file — FUSE writes the new bytes back to .116 immediately (synchronous mount).
+3. Laptop: `ssh archy "cd ~/Projects/archy && ~/.cargo/bin/cargo check -p archipelago"` — runs on the real filesystem on .116, sees the edit.
+4. Laptop: `ssh archy "cd ~/Projects/archy && git diff path/to/file"` — confirms the edit landed.
+5. Laptop: `ssh archy "cd ~/Projects/archy && git add path/to/file && git commit -m '...'"` — commit from .116.
+
+The SSHFS mount and the SSH shell are pointing at **the same inodes** — edits via the mount are instantly visible to `cargo`/`git` over SSH. There's no "sync" step.
+
+**Cache caveat**: macFUSE caches attributes briefly (default ~1s). If you write via SSH and read via the mount within that window, you may see stale metadata. The mount's `synchronous` flag (visible in `mount` output) minimizes but doesn't eliminate this. If you get a weird diff between what SSH and the mount report, re-read after a second, or `stat --file-system ~/mnt/archy-thinkpad/<file>` to force a refresh.
+
+**Direct SSH** access (use when FUSE isn't the right tool):
+   - `ssh archy` → `archipelago@192.168.1.116` using `~/.ssh/archy_opencode`
+   - `ssh archy228` → `archipelago@192.168.1.228` using `~/.ssh/archy_opencode`
+   - Full host form also works: `ssh archipelago@192.168.1.116` / `ssh archipelago@192.168.1.228` (same key resolves via IdentitiesOnly).
+
+### SSH keys — what's where
+
+**Laptop `~/.ssh/` (macOS, user `dorian`)**:
+| File | Purpose |
+|---|---|
+| `archy_opencode` / `.pub` | **Primary key for this project.** Unlocks both `archy` (.116) and `archy228` (.228). Created 2026-04-22 specifically for OpenCode work. |
+| `archipelago-deploy` / `.pub` | Older archipelago deploy key. Not needed for current work. |
+| `id_ed25519` / `.pub` | Personal default key. Not used by archy/archy228 configs (`IdentitiesOnly yes` forces `archy_opencode`). |
+| `id_ed25519_angor` / `.pub` | Angor project. Unrelated. |
+| `id_ed25519_start9` / `.pub` | Start9 project. Unrelated. |
+| `vps-ci-setup` / `.pub` | VPS CI. Unrelated. |
+| `config` | Host aliases (shown above) |
+
+**.116 `/home/archipelago/.ssh/`**:
+| File | Purpose |
+|---|---|
+| `authorized_keys` | Accepts: laptop's `archy_opencode.pub` + 3 other keys (4 lines total). |
+| `id_ed25519` / `.pub` | .116's OWN identity key. This is what lets `.116 → .228` work passwordless. |
+| `archipelago-deploy` | Symlink → `id_ed25519` (legacy alias). |
+| `id_ed25519_vps168` / `.pub` | For SSH to `146.59.87.168` (VPS). Unrelated to this work. |
+| `config` | Host entry for the VPS only. |
+
+**.228 `/home/archipelago/.ssh/`**:
+| File | Purpose |
+|---|---|
+| `authorized_keys` | Accepts: laptop's `archy_opencode.pub` + .116's `id_ed25519.pub` + 2 others (4 lines total). |
+| _(no `id_ed25519`)_ | .228 has no outbound key — it's a terminal node. Don't try to `ssh` _from_ .228 _to_ anywhere. |
+
+**Connectivity matrix (all verified 2026-04-23)**:
+| From → To | Works passwordless | Via |
+|---|---|---|
+| Laptop → .116 | ✅ | `archy_opencode` |
+| Laptop → .228 | ✅ | `archy_opencode` |
+| .116 → .228 | ✅ | .116's `id_ed25519` |
+| .228 → anywhere | ❌ | no outbound key (by design) |
+
+### Sudo — verified state
+
+**.116** (dev ThinkPad):
+- User `archipelago` is in `sudo` group.
+- Sudo password required: **`ThisIsWeb54321@`**
+- Sudoers drop-ins present: `/etc/sudoers.d/archipelago-ci`, `/etc/sudoers.d/archipelago-wg` (scope-limited NOPASSWD for specific CI/wg commands — not full NOPASSWD).
+- For most dev work you don't need sudo on .116.
+
+**.228** (prod kiosk):
+- User `archipelago` has **full passwordless sudo** via `/etc/sudoers.d/archipelago` containing `archipelago ALL=(ALL) NOPASSWD:ALL`.
+- User is also in `sudo` group.
+- Sudo password (if ever prompted, shouldn't be): **`archipelago`**
+- Dashboard password: **`password123`**
+
+### Cargo / npm / paths
+
+- **Cargo PATH gotcha**: non-interactive SSH login has no cargo in PATH. Always use `~/.cargo/bin/cargo` over SSH.
+  - Example: `ssh archy '~/.cargo/bin/cargo check -p archipelago' --workdir ~/Projects/archy/core`
+  - Or cd first: `ssh archy 'cd ~/Projects/archy && ~/.cargo/bin/cargo check -p archipelago'`
+- **Long cargo builds** (>2 min Bash tool timeout): launch detached and poll the log:
+  ```
+  ssh archy 'cd ~/Projects/archy && nohup ~/.cargo/bin/cargo build --release -p archipelago > /tmp/cargo-build.log 2>&1 < /dev/null & disown'
+  ssh archy 'tail -30 /tmp/cargo-build.log'
+  ssh archy 'pgrep -a cargo'   # to check if still running
+  ```
+- **npm / frontend** lives at `~/Projects/archy/neode-ui/` on .116 (also accessible via laptop mount at `~/mnt/archy-thinkpad/neode-ui/`). Node is on interactive PATH; for scripted SSH, `source ~/.nvm/nvm.sh && nvm use` or call the absolute path if nvm is used.
+- Repo on .116: `~/Projects/archy/` (Cargo workspace at `core/Cargo.toml`).
+- Web root on .228: check `/etc/nginx/sites-enabled/` for the live path; historically `/var/lib/archipelago/web-ui/` or `/opt/archipelago/web-ui/`.
+
+### Deploying new server binary to .228
+
+```
+# 1. Build on .116 (detached — takes ~3-5 min for release)
+ssh archy 'cd ~/Projects/archy && nohup ~/.cargo/bin/cargo build --release -p archipelago > /tmp/cargo-build.log 2>&1 < /dev/null & disown'
+# wait / tail log until "Finished `release` profile"
+
+# 2. SCP .116 → .228 (uses .116's id_ed25519 → .228's authorized_keys, passwordless)
+ssh archy 'scp ~/Projects/archy/core/target/release/archipelago archipelago@192.168.1.228:/tmp/archipelago.new'
+
+# 3. Atomic swap on .228 with backup
+ssh archy228 'sudo cp /usr/local/bin/archipelago /usr/local/bin/archipelago.bak-pre-async-stop && sudo mv /tmp/archipelago.new /usr/local/bin/archipelago && sudo chmod +x /usr/local/bin/archipelago && sudo systemctl restart archipelago'
+
+# 4. Verify
+ssh archy228 'systemctl status archipelago --no-pager | head -20 && sudo journalctl -u archipelago -n 50 --no-pager'
+```
+
+### Git workflow
+
+- Branch: `main` on .116, currently **22 commits ahead of `tx1138/main`**.
+- Remote `tx1138` exists but **do NOT push** — user mirrors to 4 Gitea remotes personally after reviewing.
+- Atomic commits, one logical change per commit. Conventional Commits format (`feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`, `perf:`).
+- Never `--amend` unless the commit you're amending was created in this session AND has not been pushed. Safer: new commit.
+- Never `--force` push. Never modify git config.
+- If pre-commit hooks fail, create a NEW commit with the fix — don't `--amend` after a failed commit.
+
+### Other
+
+- Full destructive latitude on both nodes. Announce multi-hour ops (OTA, full rebuild, apt upgrade). Don't ask for routine stop/start/rebuild permission.
+- No ship pressure. Do it properly.
+- Use `question` tool for ambiguous decisions (don't guess user intent on design choices).
+- Keep `docs/STATUS.md` fresh between sessions — it IS the session handoff.
+
+### Hosts reference (quick)
+
+| Host | IP | SSH alias | Role | Dashboard | Sudo |
+|---|---|---|---|---|---|
+| `archy` (ThinkPad X250) | 192.168.1.116 | `ssh archy` | dev host, Debian 13 | `archipelago` | `ThisIsWeb54321@` |
+| `archy228` (HP ProDesk) | 192.168.1.228 | `ssh archy228` | prod kiosk, Rust orchestrator | `password123` | NOPASSWD (fallback `archipelago`) |
+
+### Bug being fixed
+
+Dashboard sequence when user clicks **Stop LND**:
+1. UI collapses Start/Stop buttons to single spinner-button ("Stopping…") via `loadingApps.add('lnd')`.
+2. Frontend calls `container-stop` RPC. Server runs `podman stop -t 330 lnd` **synchronously inside the RPC handler** (via `orchestrator.stop()`). RPC blocks up to **5.5 min** for LND (330s timeout + overhead).
+3. Meanwhile the 30-second package-scan loop in `server.rs:scan_and_update_packages` keeps running. It rebuilds `PackageDataEntry` from podman inspect — podman still reports `running` (stop hasn't completed) — and **blindly overwrites** the store entry at `server.rs:854`.
+4. `container-list` RPC reads `state_manager` snapshot → returns `state = "running"`.
+5. Frontend polling sees `running` → `getAppState()` returns `'running'` → the two-button (Start | Stop) block re-renders → the transitional button disappears → **UI looks like the stop silently failed**.
+6. Eventually `podman stop` finishes → next scan → state flips to `Stopped` → buttons change _again_.
+
+Net visible bug: button spins briefly, reverts to Running, then several minutes later suddenly shows Stopped. User rightly calls this "out of sync and confusing".
+
+### Decisions already locked in (do not re-ask)
+
+- **Full scope fix** (not minimal hotfix). User chose "Go full scope, do it right".
+- **Async-spawn lives in the RPC layer**, not in the `ContainerOrchestrator` trait. Trait stays synchronous so the reconciler, boot flow, unit tests, and the chaos harness retain deterministic behaviour.
+- **`PackageState` already has `Stopping`/`Starting`/`Restarting`/`Installing`/`Updating`/`Removing`** variants — enum at `core/archipelago/src/data_model.rs:107-124`. No schema change needed.
+- **UI collapses to one full-width button** with spinner during every transitional state. Labels: Start / Stop / Starting… / Stopping… / Restarting… / Installing… / Updating… / Removing… / Install (when `not-installed`).
+- **Helper API shape**: `RpcHandler::spawn_transitional(op: Op, app_id: String)` where `Op` is an enum `{Stop, Start, Restart}`. Helper dispatches to `orchestrator.stop/start/restart` internally, knows each op's transitional+final states, handles error → revert + `install_log()`.
+- **`mark_user_stopped` must run BEFORE the spawn** (preserves ordering the crash recovery layer depends on — see `runtime.rs:145-148`).
+
+### Implementation order (4 commits, local only)
+
+**Commit 1 — `feat(rpc): spawn_transitional helper for async lifecycle ops`**
+- New file: `core/archipelago/src/api/rpc/transitional.rs` (or extend `container.rs`; prefer new file for cohesion with future stacks/package variants)
+- `enum Op { Stop, Start, Restart }` with `transitional_state()`, `final_state_on_success()`, `log_prefix()`, and async `dispatch(&orch, &app_id)` method
+- `impl RpcHandler { pub(super) async fn spawn_transitional(&self, op: Op, app_id: String) -> Result<()> }`
+  - Capture `Arc<dyn ContainerOrchestrator>` + `Arc<StateManager>` clones
+  - Set transitional state via `state_manager.update_data()` (if entry exists; skip if not — Start on never-installed shouldn't create an entry)
+  - `tokio::spawn(async move { ... })`
+  - Inside spawn: `install_log("{LOG_PREFIX}: {app_id}")`, `op.dispatch(&orch, &app_id).await`, on success set final state, on error log + `install_log("{LOG_PREFIX} FAIL: …")` + revert state to previous (cache pre-transition state in a local)
+  - Return `Ok(())` immediately after spawn
+
+**Commit 2 — `fix(rpc): async container stop/start/restart; widen state mapping`**
+- `api/rpc/container.rs:85-107` — rewrite `handle_container_stop` body: `validate_app_id`, `mark_user_stopped`, `spawn_transitional(Op::Stop, app_id.to_string()).await?`, return `Ok(json!({ "status": "stopping" }))`
+- `api/rpc/container.rs:61-83` — rewrite `handle_container_start`: `clear_user_stopped`, `spawn_transitional(Op::Start, …)`, return `{ "status": "starting" }`
+- **Add** `handle_container_restart` (currently missing in `container.rs` — only exists as `package.restart` at `runtime.rs:176-242`). Register RPC route name `container-restart`. Add matching frontend client method in `container-client.ts`.
+- `api/rpc/container.rs:148-154` — widen the `container-list` state mapping: add arms for `Stopping → "stopping"`, `Starting → "starting"`, `Restarting → "restarting"`, `Installing → "installing"`, `Updating → "updating"`, `Removing → "removing"`, `Installed → "installed"`, `CreatingBackup`/`RestoringBackup`/`BackingUp` → their kebab-case strings. No more `"unknown"` fallback unless the variant is genuinely unknown.
+- Mirror same spawn treatment in `api/rpc/package/runtime.rs`: `handle_package_start` (L28-119), `handle_package_stop` (L122-173), `handle_package_restart` (L176-242). Keep the existing verification loops (post-start exit-check at L82-117; restart stop+start fallback at L215-235) _inside_ the spawned future, not in the RPC body.
+
+**Commit 3 — `fix(state): preserve transitional state across container scans`**
+- `server.rs:847-857` — in the merge loop, before the `merged.insert(id.clone(), pkg.clone())` overwrite, check `merged.get(id).state` and skip overwrite if it's transitional: `matches!(existing.state, Installing | Stopping | Starting | Restarting | Updating | Removing | CreatingBackup | RestoringBackup | BackingUp)`
+- Still allow _non-state_ fields (lan_address, health, ports) to update. Simplest: when existing is transitional, keep `existing.state` but merge updated fields from `pkg`. Write a tiny helper `merge_preserving_transitional(existing, fresh) -> PackageDataEntry`.
+- Unit test: construct `existing.state = Stopping`, `fresh.state = Running`, assert merged.state stays `Stopping`.
+- **Also check**: Is there a timeout escape hatch? If `Stopping` is set and podman actually finishes but the spawn died before writing the final state (process crash, panic), the entry will be stuck `Stopping` forever. Mitigation: track a `transitional_since: Instant` in the entry (not persisted, just in-memory side table on StateManager), and if > 2× the stop timeout has elapsed, allow podman scan state to override. Scope for this commit or follow-up — lean toward: include it, because fleet reliability matters.
+
+**Commit 4 — `fix(ui): single-button lifecycle control with transitional labels`**
+- `neode-ui/src/api/container-client.ts` — extend `ContainerStatus.state` union to: `'created' | 'running' | 'stopped' | 'exited' | 'paused' | 'unknown' | 'stopping' | 'starting' | 'restarting' | 'installing' | 'updating' | 'removing' | 'installed'`. Add `restartContainer(appId)` method calling `container-restart`.
+- `neode-ui/src/stores/container.ts` — add computed `getAppVisualState(appId)` that returns one of: `'not-installed' | 'running' | 'stopped' | 'starting' | 'stopping' | 'restarting' | 'installing' | 'updating' | 'removing'`. Maps `exited`→`stopped`, `created`→`stopped`, `paused`→`stopped`, `installed`→`stopped`. Add `restartContainer(appId)` action (sets `loadingApps` for request dedup, calls client, does NOT `fetchContainers` immediately because server will broadcast state; a final `fetchContainers` after a short delay can backstop if WebSocket push is absent).
+- `neode-ui/src/views/ContainerApps.vue:85-136` — replace the two-button conditional with a single full-width button bound to `getAppVisualState(app.id)`. Table:
+  | visual state    | click action   | label          | spinner | disabled |
+  |-----------------|----------------|----------------|---------|----------|
+  | `not-installed` | installApp     | Install        | no      | no       |
+  | `running`       | stopContainer  | Stop           | no      | no       |
+  | `stopped`       | startContainer | Start          | no      | no       |
+  | `starting`      | —              | Starting…      | yes     | yes      |
+  | `stopping`      | —              | Stopping…      | yes     | yes      |
+  | `restarting`    | —              | Restarting…    | yes     | yes      |
+  | `installing`    | —              | Installing…    | yes     | yes      |
+  | `updating`      | —              | Updating…      | yes     | yes      |
+  | `removing`      | —              | Removing…      | yes     | yes      |
+  - Add a separate Restart button next to the primary one when state is `running`, calling new `restartContainer` action. Restart button hides while transitional.
+- `neode-ui/src/views/ContainerAppDetails.vue:83` (and full stop/start button blocks around L220, L232) — mirror the same single-button pattern.
+- Also audit line 239 of `ContainerApps.vue` (`some((app) => store.getAppState(app.id) === 'created')`) and the logic around lines 276, 295, 309, 312 — make sure they use `getAppVisualState` where appropriate.
+
+### Verification gates (do not skip)
+
+1. `~/.cargo/bin/cargo check -p archipelago` on .116 via SSH
+2. `~/.cargo/bin/cargo test -p archipelago` on .116 via SSH — at least the new merge helper test must pass
+3. Build release binary on .116: `nohup ~/.cargo/bin/cargo build --release -p archipelago > /tmp/cargo-build.log 2>&1 < /dev/null & disown`. Poll until done.
+4. SCP binary to .228 `/usr/local/bin/archipelago`, back up prior to `/usr/local/bin/archipelago.bak-pre-async-stop`. `sudo systemctl restart archipelago` on .228.
+5. **Manual LND stop test on .228**:
+   - Open dashboard, confirm LND is Running (first: `ssh archipelago@192.168.1.228 'podman start lnd'` — LND is currently Exited(0) from the demo)
+   - Click Stop
+   - Expected: button _immediately_ becomes "Stopping…" with spinner (RPC returns <1s)
+   - Dashboard should stay on "Stopping…" for ~5 min
+   - Then flip to "Start" button with label "Start"
+   - At no point should it revert to "Running" mid-stop
+6. Same test with Bitcoin Core stop (longest timeout, 600s)
+7. Frontend build: `cd ~/Projects/archy/neode-ui && npm run type-check && npm run build`. Rsync `dist/` to `archipelago@192.168.1.228:/var/lib/archipelago/web-ui/` (or wherever the active web root is — check `/etc/nginx` on .228 first).
+8. Then and only then: resume chaos matrix. First recover LND/ElectrumX via UI (great end-to-end test of the new async Start path), then run smoke → full 32-case matrix.
+
+### Key files (exact lines of interest)
+
+- `core/archipelago/src/api/rpc/container.rs:85-107` — `handle_container_stop` (blocking — target of fix)
+- `core/archipelago/src/api/rpc/container.rs:61-83` — `handle_container_start`
+- `core/archipelago/src/api/rpc/container.rs:148-154` — narrow state mapping (drops transitional → "unknown")
+- `core/archipelago/src/api/rpc/package/runtime.rs:11-24` — `stop_timeout_secs` table (reference, unchanged)
+- `core/archipelago/src/api/rpc/package/runtime.rs:122-173` — `handle_package_stop` (also blocking, mirror treatment)
+- `core/archipelago/src/api/rpc/package/runtime.rs:28-119` — `handle_package_start`
+- `core/archipelago/src/api/rpc/package/runtime.rs:176-242` — `handle_package_restart`
+- `core/archipelago/src/api/rpc/package/progress.rs` — existing broadcast pattern to mirror (`set_install_progress`, `set_uninstall_stage`)
+- `core/archipelago/src/api/rpc/mod.rs:62-100` — `RpcHandler` struct (already holds `Arc<dyn ContainerOrchestrator>` + state_manager)
+- `core/archipelago/src/server.rs:812-857` — `scan_and_update_packages` (merge loop at L850-857 is where transitional-state clobber happens)
+- `core/archipelago/src/container/docker_packages.rs:636-663` — `convert_state` + `package_state_str` (read-only reference, no change)
+- `core/archipelago/src/container/traits.rs` — `ContainerOrchestrator` trait (stays synchronous, do not change)
+- `core/archipelago/src/crash_recovery.rs` — `mark_user_stopped` / `clear_user_stopped` (call order preserved)
+- `core/archipelago/src/data_model.rs:107-124` — `PackageState` enum (no change — all variants exist)
+- `neode-ui/src/api/container-client.ts` — `ContainerStatus` type + RPC methods (extend)
+- `neode-ui/src/stores/container.ts:93-312` — Pinia store (add `getAppVisualState`, add `restartContainer` action)
+- `neode-ui/src/views/ContainerApps.vue:85-136, 239, 276, 295, 309-312, 383` — two-button block + state reads
+- `neode-ui/src/views/ContainerAppDetails.vue:83, 220, 232` — details page Stop/Start
+
+### Chaos harness (not in repo — lives on .116)
+
+- `archipelago@192.168.1.116:~/ui-chaos/` — deployed, playwright + deps installed, smoke test for bitcoin-core passes (2.1 min). LND/ElectrumX/bitcoin-ui smoke tests not yet run (blocked on the async-stop fix landing; LND currently Exited on .228 from the demo).
+- `/tmp/chaos/` on laptop — canonical source for rsync to .116.
+- Run: `cd ~/ui-chaos && npx playwright test tests/<spec>`
+- Target: 32 cases = 4 core containers × 8 scenarios (install-fresh, graceful-stop, sigkill, rm-container, oom-kill, rm-image, restart-service, network-partition).
+- Uses SSH+Playwright hybrid per design; includes the `bash -lc '<escaped>'` single-quote fix for ssh argv flattening and JSON-parsed `podman inspect` instead of Go templates.
+
+### Pre-existing bugs still deferred (do not fix until Stop UX lands)
+
+1. `archipelago --version` spawns server (should be a pure CLI query)
+2. RPC unknown-method returns generic error (should return method-not-found with the bad method name)
+3. `docker_packages.rs` filters out UI containers (`archy-lnd-ui`, `archy-electrs-ui`) — some views need them visible
+4. `lnd.lan_address` stale on .228
+5. first-boot silent failure on some hardware
+6. `web-ui.failed.*` scar on .228 (benign systemd unit state)
+7. `test_parse_image_versions` pre-existing broken assertion — fix or `#[ignore]` when touching that area
+
+---
+
+## Where we are
+
+Working through the 11-step plan in [`rust-orchestrator-migration.md`](./rust-orchestrator-migration.md).
+
+- [x] **Step 1** — `3767c267` ContainerConfig schema with `build:`, `ResolvedSource` enum, `resolve()`, 10 tests
+- [x] **Step 2** — `34af4d9d` ContainerRuntime trait gained `image_exists` + `build_image`, 4 argv tests, 25/25 pass
+- [x] **Step 3** — `b6a04d31` ProdContainerOrchestrator (999 LOC), 16 tests all pass, not yet wired to main.rs
+- [x] **Step 4** — `e8a59c93` ContainerOrchestrator trait, RpcHandler uses it in prod (+ `13858842` chore gitignore ._*)
+- [x] **Step 5** — `fc39b04b` BootReconciler with Arc<Notify> shutdown, 4 paused-time tests pass
+- [x] **Step 6** — `48f08aa3` main.rs wire-up (orchestrator construction + adopt_existing + BootReconciler spawn + shutdown Notify)
+- [x] **Step 7** — `069bc4a5` bitcoin-ui pre-start hook + embedded nginx.conf template (8 unit tests + 1 integration test), 39/39 container:: tests pass
+- [x] **Step 8a** — `a0707f4d` retire archipelago-reconcile.{service,timer} + ISO builder touchpoints, keep scripts for update.rs
+- [x] **Step 9** — **Hot-swap on .228 verified.** All three UIs (bitcoin-ui/lnd-ui/electrs-ui) installing + serving HTTP 200.
+- [x] **.228 dashboard bugs** — ExtraHost `192.168.1.254` bug (`3ee192ba`) + LND macaroon permission bug (`be960023`). See "Post-Step 9 bug hunt" below.
+- [ ] **Step 8b** — Port remaining ~25 container creations from `first-boot-containers.sh` into `apps/<id>/manifest.yml`, then port `update.rs` to orchestrator (deferred, multi-day work)
+- [ ] **Step 8c** — Rename `first-boot-containers.sh` → `first-boot-setup.sh`, strip container ops, keep setup. Delete `reconcile-containers.sh` + `container-specs.sh`. Add ISO lines to copy `apps/` (final one-way door, requires 8b complete)
+- [ ] **Step 10** — Hot-swap + verify on .116 (adoption-heavy test — .116 already has all containers running)
+- [ ] **Step 11** — Chaos matrix on both nodes (all 8 scenarios × all containers incl. bitcoin-core)
+
+## Post-Step 9 bug hunt (.228, 2026-04-23)
+
+User reported three visible dashboard bugs after Step 9 verification:
+1. LND — "no connect details or QR"
+2. ElectrumX — stuck at "Building index (2 KB / ~130 GB)" for days
+3. bitcoin-core — in scope for chaos testing
+
+**Root cause #1 (ExtraHost, commit `3ee192ba`)**: `scripts/first-boot-containers.sh` computed `HOST_GATEWAY` from `ip route show default`, which returns the **LAN router** (e.g. 192.168.1.254), not the gateway to the host. Every container configured with `--add-host=host.containers.internal:$HOST_GATEWAY` was dialing the WiFi router instead of the host. LND crash-looped with `dial tcp 192.168.1.254:8332: connection refused`; ElectrumX's DAEMON_URL hit the same dead end; any `archy-net` bridge consumer of bitcoin-core's RPC was broken. Fixed by replacing the computed value with podman's magic `host-gateway` literal (supported since 4.4; we ship 5.4.2). Live-recreated bitcoin-core/electrumx/lnd on .228 with the corrected `--add-host`; LND reached chain backend; ElectrumX resumed indexing (went from 2 KB → 164.9 MB in under an hour).
+
+**Root cause #2 (macaroon permissions, commit `be960023`)**: LND's `admin.macaroon` lives at `/var/lib/archipelago/lnd/data/chain/bitcoin/mainnet/admin.macaroon`, owned by rootless-podman subordinate UID 100000, mode 640. The archipelago server runs as host UID 1000 and literally cannot read the file. Every LND RPC (`getinfo`, `connect-info`, `export-channel-backup`) plus the shared `lnd_client()` helper failed with "Failed to read LND admin macaroon". **Confirmed pre-existing on .116 too** (long-standing bug unrelated to Step 9). Fix: centralised the path as `LND_ADMIN_MACAROON_PATH`, added a `read_lnd_admin_macaroon()` helper in `api/rpc/lnd/mod.rs` that tries direct read first then falls back to `sudo -n cat` (mirrors the pattern already used for Tor onion hostnames). Four call sites routed through the helper. Verified on .228 — `curl -k https://<host>/lnd-connect-info` now returns 200 with cert + macaroon + tor_onion; dashboard QR unblocked.
+
+## Step 9 evidence (.228, 2026-04-23)
+
+- Binary: Step 9 build with `732df1b8` + `ba83f9bc`, scp'd to .228 as `/usr/local/bin/archipelago`. Old binary backed up at `/usr/local/bin/archipelago.bak-pre-step9`. Later replaced with macaroon-fix build (`be960023`); previous backed up at `/usr/local/bin/archipelago.bak-pre-macaroon`.
+- DEV_MODE override disabled (`override.conf` → `override.conf.disabled-pre-step9`).
+- `/opt/archipelago/apps/{bitcoin-ui,electrs-ui,lnd-ui}/manifest.yml` populated.
+- `/opt/archipelago/docker/bitcoin-ui/Dockerfile` replaced with the Step 7 version (no `COPY nginx.conf`). Old dir backed up as `bitcoin-ui.bak-pre-step9`.
+- Post-start snapshot:
+  - `🔗 Adopted 1 existing container(s): ["electrs-ui"]` — adoption of 13h-running container worked without recreation
+  - `🔄 Boot reconciler started (interval: 30s)` — every 30s, all three app_ids reach `NoOp` after the initial install pass
+  - `bitcoin-ui nginx.conf rendered path=/var/lib/archipelago/bitcoin-ui/nginx.conf auth_hash=97af1c18` — pre-start hook fires in `install_fresh`
+  - `curl localhost:8334` → HTTP 200 (bitcoin-ui), `:8081` → 200 (lnd-ui), `:50002` → 200 (electrs-ui)
+  - OCI memory limits correctly applied: bitcoin-ui=128Mi, electrs-ui=128Mi, lnd-ui=64Mi (was emitted as 0 pre-fix)
+
+## Bugs fixed this session
+
+1. **`parse_memory_limit` truncation bug** (`732df1b8`): lowercased "128Mi" → "128mi" → `trim_end_matches('m')` → "128i" → f64 parse fails → `None.unwrap_or(0)` → OCI `memory.limit:0` → systemd rejects MemoryMax=0. 6 regression tests; `create_container` now omits instead of emitting 0.
+2. **`archipelago.service` cgroup delegation missing** (`ba83f9bc`): belt-and-braces `Delegate=memory pids cpu io`.
+3. **ExtraHost `192.168.1.254`** (`3ee192ba`): see Post-Step 9 bug hunt above.
+4. **LND admin.macaroon unreadable** (`be960023`): see Post-Step 9 bug hunt above.
+
+## Commits made this session
+
+```
+3ee192ba fix(first-boot): use podman host-gateway magic for host.containers.internal
+be960023 fix(lnd): read admin macaroon via sudo fallback
+4b8ef0a0 docs: STATUS.md through Step 9 (.228 hot-swap verified)
+ba83f9bc feat(systemd): delegate cgroup controllers to archipelago.service
+732df1b8 fix: parse_memory_limit accepts Ki/Mi/Gi IEC binary suffixes
+a0707f4d refactor: retire archipelago-reconcile.{service,timer}  (Step 8a)
+1c81a739 docs: split Step 8 into 8a/8b/8c
+6e46932f docs: STATUS.md through Step 7
+069bc4a5 feat: bitcoin-ui pre-start hook (Step 7)
+```
+
+Branch is **19 commits ahead of tx1138/main** (local only — user pushes to mirrors personally).
+
+## Uncommitted state
+
+Clean. Only untracked: `tests/` (bats harness from prior session, not in scope), `tmp-dump-spec.py` (scratch).
+
+## Answered design questions (no need to re-ask)
+
+1. UI container naming → `archy-<app_id>` for UIs only; existing bitcoin-knots/lnd/electrumx keep bare names
+2. BITCOIN_RPC_AUTH injection → runtime bind-mount of nginx.conf (no build-args, no envsubst)
+3. Reconciler interval → 30 seconds
+4. Concurrency → per-app `Mutex<()>` in a `DashMap`
+5. Bash scripts → split into 8a/8b/8c; 8a done, 8b/8c deferred
+6. Step 4 extension → `ContainerOrchestrator` trait includes `install(app_id)`; the `manifest_path`-based install RPC stays dev-only
+7. Step 7 bitcoin-ui template → embed via `include_str!`, render on install + every reconcile, atomic tmp+rename to `/var/lib/archipelago/bitcoin-ui/nginx.conf`, bind-mount into container. RPC user hardcoded `archipelago`, password from `/var/lib/archipelago/secrets/bitcoin-rpc-password`.
+
+## Context: which host is what
+
+| Host | IP | Role | Dashboard pw | Sudo pw |
+|---|---|---|---|---|
+| `archy` | 192.168.1.116 | **Dev ThinkPad** (Lenovo X250, Debian 13). Currently running v1.7.42-alpha (DEV_MODE). Step 10 target. | archipelago | ThisIsWeb54321@ |
+| `archy228` | 192.168.1.228 | Kiosk HP ProDesk. **Step 9 landing zone** — now running Rust-orchestrator binary in prod mode. | password123 | archipelago |
+
+Both are development alpha nodes — **full destructive latitude**, no need to ask before stop/start/rebuild.
+
+## Next action
+
+**Step 10 — Hot-swap on .116.**
+
+Unlike .228 (which tested the INSTALL path for net-new UI containers), .116 tests the ADOPTION path: it already has all three UIs and all backend containers running from prior v1.7.42-alpha runs. We want to verify the new prod orchestrator adopts every existing container without recreating or restarting them.
+
+Steps:
+1. Disable DEV_MODE on .116 (check if override.conf exists — `/etc/systemd/system/archipelago.service.d/`)
+2. Stage the already-built binary at `~/Projects/archy/core/target/release/archipelago` → `/usr/local/bin/archipelago.new`
+3. Ensure `/opt/archipelago/apps/{bitcoin-ui,electrs-ui,lnd-ui}/manifest.yml` present (copy from repo)
+4. Ensure `/opt/archipelago/docker/bitcoin-ui/` matches the Step-7 layout (no baked nginx.conf)
+5. Snapshot: `podman ps -a --format "{{.Names}}\t{{.Status}}\t{{.CreatedAt}}"` → save to `/tmp/pre-step10-containers.txt`
+6. `systemctl stop archipelago` → install binary → `systemctl start archipelago`
+7. Verify in journal: every running container appears in "Adopted N existing container(s)"; no container was recreated; all HTTP smokes still 200; BootReconciler reaches NoOp on every app_id after one pass.
+8. If broken → restore `.bak` binary, re-enable DEV_MODE override.
+9. Commit STATUS.md update.
+
+**Risk on .116:** If adoption fails mid-flight, we'd lose the running v1.7.42 backend that I'm currently typing at. Keep a second SSH session open to the ThinkPad for emergency revert. The backup plan is `install /usr/local/bin/archipelago.bak /usr/local/bin/archipelago && systemctl restart archipelago`.
+
+**After Step 10 we are blocked on Step 8b** (multi-day manifest ports) before Step 11 (chaos matrix).
+
+---
+
+### Why Step 8 got split (discovered 2026-04-23)
+
+Original plan was one commit "delete bash + edit ISO builder". But on investigation:
+- `first-boot-containers.sh` creates **30+ containers** with per-container logic (wallets, DB init, rpcauth derivations, post-create health waits). The repo only has manifests for 3 (bitcoin-ui, electrs-ui, lnd-ui from Step 7). Deleting bash now = brick first-boot on fresh installs.
+- Script also does non-container setup: secret generation (RPC pw, DB pw, FileBrowser admin pw), UID-mapping chowns for rootless podman subuid, Tor hostnames dir, WireGuard, firewall rules, nostr-relay dir. None of this lives in the Rust orchestrator.
+- `update.rs` (OTA update RPC) invokes `reconcile-containers.sh` at two sites. Deleting the script breaks package updates. Porting those call sites to the orchestrator needs all containers to have manifests.
+- Design doc §505 updated to split 8 → 8a/8b/8c. Only 8a (delete the reconcile systemd unit + timer, BootReconciler covers) is safe to execute before we port manifests.
+
+---
+
+# Archipelago — Current State, Plan, and Releases
+
+Updated: 2026-04-22
+
+This is the "pick this up tomorrow" page. One-stop summary of where we are, what the plan is, and what's shipped. Detailed plan lives in [`bulletproof-containers.md`](./bulletproof-containers.md).
+
+---
+
+## Current state
+
+### Fleet status
+
+All four Gitea mirrors are synced to v1.7.40-alpha:
+
+| Mirror | Host | Status |
+|---|---|---|
+| tx1138 | https://git.tx1138.com | ✅ v1.7.40-alpha live |
+| gitea-local | http://localhost:3000 | ✅ v1.7.40-alpha live |
+| .160 | http://23.182.128.160:3000 | ✅ v1.7.40-alpha live (Gitea recovered via `podman system renumber` — see below) |
+| .168 | http://146.59.87.168:3000 | ✅ v1.7.40-alpha live |
+
+Fleet test nodes:
+
+| Node | Version | State |
+|---|---|---|
+| .103 (dev) | 1.7.40 | running, being developed against |
+| .116 (this box) | 1.7.40 | healed manually via `systemd-run chmod 755 /opt/archipelago/web-ui` after v1.7.38/39 bug |
+| .198 | 1.7.39 → 1.7.40-alpha | healed manually |
+| .228 (primary test) | 1.7.40-alpha | healed manually; bitcoin-core + lnd + electrumx running; UI companions currently missing; bitcoin.conf rpcauth patched live |
+| .249 (ISO test) | unreachable today | |
+| .253 | 1.7.39 → 1.7.40-alpha | healed manually |
+
+### Known open issues (drives the plan below)
+
+1. **UI companion containers disappear** on .228 after daemon restarts — no auto-recreate (fixed by v1.7.45 Quadlet migration)
+2. **bitcoin.conf rpcauth drifts** from canonical secret → ElectrumX "Daemon connection problem" (fixed by v1.7.43 reconcile::derived)
+3. **`host.containers.internal`** resolves to LAN gateway inside containers on some versions (fixed by v1.7.42 containers.conf)
+4. **Podman state DB loss** requires manual recovery (fixed by v1.7.44 startup self-heal)
+5. **LND "Connect Wallet" info** vanishing after crashes — symptom of the same drift class as #2
+6. **ElectrumX not syncing** on .228 — downstream of #2; will resolve when bitcoin.conf is reconciled
+
+### Recent field incident (2026-04-22)
+
+- Shipped v1.7.38 + v1.7.39, both broke nginx fleet-wide because the frontend tarball's root dir was `drwx------` (700). Every node that OTA'd got 500 errors on every page.
+- Root-cause fix shipped in v1.7.40 (`create-release-manifest.sh` chmod + pre-ship assertion that `tar tvzf | head -1` shows `drwxr-xr-x`).
+- .160 Gitea was down all day (502) because its rootless podman's `libpod/bolt_state.db` had vanished. Recovered via clearing `/run/user/$UID/{containers,libpod,podman}` + `podman system renumber`.
+- Full failure-mode audit is in [`bulletproof-containers.md`](./bulletproof-containers.md).
+
+---
+
+## Plan
+
+We're shipping a level-triggered **reconciler + Quadlet** architecture over six incremental releases. Each release closes one failure mode. See [`bulletproof-containers.md`](./bulletproof-containers.md) for the full design, code layout, test harness, chaos matrix, sources.
+
+### Release roadmap
+
+| Release | Closes | What lands | Status |
+|---|---|---|---|
+| **v1.7.41** | FM5 (bad OTA nginx 500) | Post-OTA auto-rollback. New binary probes `https://127.0.0.1/` on boot; if non-200 within 90s, restores `web-ui.bak` + calls `rollback_update()` + restarts | **in flight — deploying to .228 for test** |
+| **v1.7.42** | FM4 (`host.containers.internal` wrong) | `/etc/containers/containers.conf` w/ `host_containers_internal_ip = 10.89.0.1`; every container gets `--add-host=host.archipelago:10.89.0.1` | pending |
+| **v1.7.43** | FM2 (config drift) | `reconcile::derived::render_bitcoin_conf` — pure fn over canonical secret, rewrites on drift. Same for `lnd.conf` | pending |
+| **v1.7.44** | FM6 (podman state loss) | Startup probe detects broken podman state, auto-recovers via `/run/user/$UID/*` clear + `system renumber` | pending |
+| **v1.7.45** | FM1 + FM3 (companion orphans) | `archy-bitcoin-ui` → Quadlet `.container` unit in `/etc/containers/systemd/`. systemd (not archipelago) owns it | pending |
+| **v1.7.46** | — | `archy-lnd-ui` → Quadlet | pending |
+| **v1.7.47** | — | `archy-electrs-ui` → Quadlet | pending |
+| **v1.7.48+** | all (full daemon refactor) | `core/archipelago/src/reconcile/` module replaces imperative `install.rs` container management. Main app containers become Quadlet too | pending |
+
+Test harness (bats + Goss + Chaos Toolkit + vmtest) lands scaffold in v1.7.41, first lifecycle tests blocking v1.7.45, full matrix blocking beta tag.
+
+---
+
+## Release history
+
+### [v1.7.41-alpha](/releases/v1.7.41-alpha/) — IN FLIGHT — 2026-04-22
+**Post-OTA auto-rollback.** After an update lands, the node probes its own web UI through nginx — if the frontend isn't answering cleanly within 90 seconds, the node automatically rolls back to the previous version and restarts. A bad release can no longer leave the fleet stranded on an unreachable node.
+
+Changes:
+- `core/archipelago/src/update.rs`: `PendingVerification` struct, write marker before service restart, `verify_pending_update()` on new binary boot — probes `https://127.0.0.1/`, on fail restores `web-ui.bak` + calls `rollback_update()` + `systemctl restart archipelago`
+- `core/archipelago/src/main.rs`: startup task invokes verifier concurrently with server
+
+### [v1.7.40-alpha](https://git.tx1138.com/lfg2025/archy/raw/branch/main/releases/v1.7.40-alpha/) — 2026-04-22
+**Proper fix for the 500 error.** Fixed the v1.7.38/39 tarball-perms bug at its source — staging dir is now explicitly `chmod 755` before tar; `--mode=u=rwX,go=rX` normalizes archive perms; pre-ship assertion aborts release if `tar tvzf | head -1` isn't `drwxr-xr-x`.
+
+Changes:
+- `scripts/create-release-manifest.sh`: pre-tar chmod + tar --mode flag + post-tar verify
+- Everything from .38 + .39 still in place (onboarding auto-heal, silent logins, app purge, AIUI in tarball)
+
+### [v1.7.39-alpha](https://git.tx1138.com/lfg2025/archy/raw/branch/main/releases/v1.7.39-alpha/) — 2026-04-22
+**Hotfix attempt** for v1.7.38's nginx 500 (didn't fully work — still shipped broken tarball perms). Added startup self-heal chmod in `main.rs` and post-extract chmod in `update.rs` OTA applier.
+
+### [v1.7.38-alpha](https://git.tx1138.com/lfg2025/archy/raw/branch/main/releases/v1.7.38-alpha/) — 2026-04-22
+**Onboarding auto-heal + silent logins + App Store trim.**
+
+Changes:
+- `auth.rs`: `is_onboarding_complete()` auto-heals from `setup_complete` + `password_hash` (prevents clear-cache → onboarding wizard bug)
+- `useOnboarding`: tri-state — backend-unreachable no longer defaults to `/onboarding/intro`
+- Login sounds gated by `isFirstInstallPhase()` — silent after onboarding, typing sounds unaffected
+- Removed FIPS app, Nostr Relay, Nostr VPN, Routstr, Penpot from catalog + Rust + docker + icons
+- Deleted 15 image versions from tx1138, .168, gitea-local registries
+- AIUI baked into release tarball via `demo/aiui/`
+- `prebuild` hook syncs `app-catalog/catalog.json` → `public/catalog.json`
+
+(Shipped with tarball-perms bug; fleet had to be healed before v1.7.40.)
+
+### [v1.7.37-alpha](https://git.tx1138.com/lfg2025/archy/raw/branch/main/releases/v1.7.37-alpha/) — 2026-04-22
+**Bitcoin Core install fixes + dynamic node UI + full-archive default.**
+
+- Bitcoin Core passes explicit `-rpcbind/-rpcallowip/etc.` CLI args so vanilla image exposes RPC
+- Split `bitcoin-core` from `bitcoin-knots` in backend `AppMetadata`
+- bitcoin-ui auto-detects Core vs. Knots from subversion, swaps branding at runtime
+- Storage (Full Archive · X GB / Pruned) indicator on dashboard
+- Node Settings modal shows real values (network, storage, txindex, ZMQ, RPC port)
+- Pull fallback to `docker.io` when no mirror carries the image
+- Removed `prune=550` hardcode — full archive default
+
+---
+
+## Key docs
+
+- [`bulletproof-containers.md`](./bulletproof-containers.md) — full reconcile architecture, code layout, test matrix, chaos scenarios, sources
+- [`BETA-RELEASE-CHECKLIST.md`](./BETA-RELEASE-CHECKLIST.md) — existing beta checklist
+- [`BETA-ISSUES-20260328.md`](./BETA-ISSUES-20260328.md) — prior beta-blocker tracking
+- [`hotfix-process.md`](./hotfix-process.md) — release workflow
+- [`architecture.md`](./architecture.md) — system architecture overview
+
+---
+
+## How to resume
+
+1. Check fleet mirrors are all live: `curl -sS https://git.tx1138.com/lfg2025/archy/raw/branch/main/releases/manifest.json | jq .version`
+2. Read [`bulletproof-containers.md`](./bulletproof-containers.md) for the current plan
+3. Check task list (`/list` or via Claude Code) for the in-flight release
+4. Latest in-flight work: v1.7.41 deploying to .228 for test; will ship to all 4 mirrors once verified
@@ -0,0 +1,314 @@
+# Bulletproof Containers for Beta
+
+**Status**: plan agreed 2026-04-22, implementation started.
+**Target**: zero-manual-intervention container lifecycle for the beta launch. A user installs, uninstalls, reboots, updates, or loses power — every combination must leave the node in a known-good state without SSH.
+**Project memory**: `~/.claude/projects/-home-archipelago-Projects-archy/memory/project_reconcile_architecture.md`
+**Failure log**: `~/.claude/projects/-home-archipelago-Projects-archy/memory/feedback_container_lifecycle_failure_modes.md`
+
+---
+
+## Why we're doing this
+
+The v1.7.38 and v1.7.39 rollouts on 2026-04-22 exposed a cluster of container-lifecycle failures that required manual SSH recovery on every affected node (.116, .198, .228, .253). If a user had been on those nodes, they'd have been stuck with "can't reach" or 500 errors and no path forward. We can't ship beta with this class of failure on the table.
+
+The pattern under every failure: **the canonical source of truth had the right answer, but derived state drifted away from it and nothing noticed or fixed it.**
+
+### The six failure modes
+
+| # | Symptom | Root cause |
+|---|---|---|
+| FM1 | `archy-bitcoin-ui` + `archy-lnd-ui` disappeared from `podman ps -a` after a daemon restart | Archipelago owns container creation imperatively; no owner recreates companions after a crash mid-transition |
+| FM2 | ElectrumX "Daemon connection problem" | `bitcoin.conf`'s `rpcauth` drifted from `/var/lib/archipelago/secrets/bitcoin-rpc-password` — config written once at install, never re-derived |
+| FM3 | archipelago.service `status=226/NAMESPACE` crash-loop SIGKILL'd every child container | Containers were children of archipelago's cgroup; systemd teardown killed them. `KillMode=control-group` default |
+| FM4 | `host.containers.internal` inside containers resolved to LAN gateway (192.168.1.254) | Known podman bug on bridge networks pre-5.3 ([#22644](https://github.com/containers/podman/issues/22644)) |
+| FM5 | Nginx 500 fleet-wide after OTA | Tarball root dir was `drwx------` (700), extracted identically on every node. Fixed in v1.7.40 at build time; still need post-OTA auto-rollback |
+| FM6 | Rootless podman's `libpod/bolt_state.db` vanished → whole registry node unreachable | No detection of corrupt state; required manual `rm -rf /run/user/$UID/libpod` + `podman system renumber` |
+
+---
+
+## Architecture decision
+
+**Adopt balena-style, level-triggered, desired-state reconciler built on Quadlet + sdnotify.**
+
+This is the one architecture that would have prevented all six failures, because each one is "reality drifted from the intended config and nothing noticed" — the exact problem reconcilers are designed for.
+
+### Why not the alternatives
+
+- **Keep imperative + patch per-failure** — we've been doing this. Five releases in a day. Doesn't scale.
+- **Migrate to LXC (StartOS's path)** — 6-month project. Our investment in podman (`install.rs`, `docker_packages.rs`, `image_versions.rs`) is substantial. Quadlet gives us StartOS's isolation property without the migration.
+- **Ship k3s / MicroShift** — 400-800 MB RAM baseline on top of bitcoind/electrs. Overkill for a home node OS.
+- **Edge-triggered like Umbrel** — their `app.ts` has an explicit TODO admitting they don't handle failure events. We'd inherit the same bug class.
+
+### The four patterns (from mature players)
+
+1. **Desired-state-first, level-triggered reconcile.** balena-supervisor, Kubernetes operators, NixOS. A supervisor owns a manifest of *what should run*; on every tick it diffs against *what is running* and issues steps.
+2. **Every container is its own systemd unit, not a child of the daemon.** Red Hat's Quadlet pattern: a `.container` file is parsed by a systemd *generator* into a normal `.service`. The daemon can crash without taking any containers with it.
+3. **sdnotify readiness + HealthCmd + rollback.** Podman v3.4+ has real rollback: bad image fails health check, systemd considers service failed, Podman re-tags the previous image digest.
+4. **Credentials and config derived from canonical secrets on every apply.** Not trusted across upgrades; re-rendered idempotently from single source of truth.
+
+### Fix-per-failure
+
+| Failure | Fix |
+|---|---|
+| FM1 | Move companions to Quadlet `.container` files in `/etc/containers/systemd/`. systemd (not archipelago) owns them |
+| FM2 | `reconcile::derived::render_bitcoin_conf(secrets)` — pure function, runs every tick, atomic rewrite + HUP on drift |
+| FM3 | `KillMode=mixed` in archipelago.service + containers in their own `archipelago-apps.slice`. Quadlet units already live outside archipelago's cgroup |
+| FM4 | Ship `/etc/containers/containers.conf` with `host_containers_internal_ip = "10.89.0.1"` + `default_rootless_network_cmd = "pasta"`; also `--add-host=host.archipelago:10.89.0.1` in every unit |
+| FM5 | Post-OTA `curl -k https://127.0.0.1/` health probe in new binary startup. If non-200 within 90s, rollback to `web-ui.bak` + binary-backup |
+| FM6 | Startup probe: `podman info` with timeout. On "invalid internal status", clear `/run/user/$UID/{containers,libpod,podman}` + `podman system renumber` + reconcile tick rebuilds from Quadlet units |
+
+---
+
+## New code layout (lands in v1.7.48)
+
+```
+core/archipelago/src/reconcile/
+  mod.rs           run_reconcile_loop, reconcile_once — called from main.rs
+  desired.rs       DesiredState built from packages.json + catalog + secrets
+  current.rs       snapshot via `systemctl list-units archy-*.service` + `podman ps -a --format json`
+  diff.rs          pure: reconcile(desired, current) -> Vec<Step>   (unit-testable without podman)
+  apply.rs         step executor with timeouts, structured logs, backoff
+  quadlet.rs       write `.container` / `.volume` / `.network` units atomically
+  derived.rs       render_bitcoin_conf, render_containers_conf, render_nginx_app_routes
+  backoff.rs       restart-history tracking (moved from health_monitor.rs)
+```
+
+### Step types (idempotent)
+
+```rust
+enum Step {
+    WriteQuadletUnit(path, content),
+    WriteDerivedFile(path, content),
+    WriteSecret(path, content),
+    DaemonReload,
+    EnsureStarted(unit),
+    StopUnit(unit),
+    RestartUnit(unit),
+    PullImage(ref),
+}
+```
+
+### Triggers
+
+- 30s interval tick
+- install/uninstall RPC
+- update-applied event
+- explicit `/rpc/v1/reconcile.tick`
+- podman event stream (if available)
+
+Level-triggered + idempotent — every call considers full desired vs current diff. Missed ticks/events are irrelevant.
+
+### Edits to existing code
+
+- **`src/main.rs`**: replace `tokio::spawn(crash_recovery::start_stopped_containers)` with `tokio::spawn(reconcile::run_reconcile_loop(state))`. Keep self-heal perms + PID-marker crash detection.
+- **`src/api/rpc/package/install.rs`**: stop calling `podman run` directly. Writes desired state + Quadlet unit + signals reconciler. Reconciler does pull + `systemctl start`.
+- **`src/api/rpc/package/runtime.rs`** + `lifecycle.rs` + `stacks.rs`: same pattern — mutate desired state, reconciler applies.
+- **`src/crash_recovery.rs`**: keep PID-marker + snapshot. Delete `start_stopped_containers` (reconciler handles cold boot). Keep `user-stopped.json` as `AppSpec.desired_state: Started | UserStopped | Uninstalled`.
+- **`src/health_monitor.rs`**: strip restart logic. Keep memory-leak detection; push unhealthy events as `Trigger::ContainerUnhealthy(name)`.
+- **`src/bitcoin_rpc.rs`**: add `pub fn derive_rpcauth_line(user, pass) -> String` (HMAC-SHA256 per Bitcoin Core's `rpcauth.py`).
+- **`src/update.rs`**: post-swap health probe + auto-rollback (v1.7.41).
+
+---
+
+## Shipping order
+
+Each release is independently deployable. Not a big-bang rewrite.
+
+### v1.7.41 — Post-OTA health probe + auto-rollback (closes FM5)
+- In `update.rs`: write `/var/lib/archipelago/update-pending-verify.json` just before service restart, with `applied_at`, `new_version`, `previous_version`, deadline.
+- In `main.rs` startup: read marker, spawn verification task. Wait 15s for full startup, then `curl -k https://127.0.0.1/` with retries up to 90s.
+- On 200: delete marker.
+- On non-200 after window: call `rollback_update(data_dir)` (already exists), restart service to boot the old binary.
+- Smallest diff, highest ROI.
+
+### v1.7.42 — containers.conf + host.archipelago alias (closes FM4)
+- Idempotent write of `/etc/containers/containers.conf` on startup (archipelago compares hash, rewrites only on drift).
+- Add `--add-host=host.archipelago:10.89.0.1` to every generated container in `install.rs` / `docker_packages.rs`.
+- ElectrumX `DAEMON_URL` migrates from `host.containers.internal` → `host.archipelago`.
+
+### v1.7.43 — `reconcile::derived` for bitcoin.conf / lnd.conf (closes FM2)
+- Pure function `render_bitcoin_conf(secrets) -> String`.
+- Tick every 30s: read secret, derive `rpcauth`, compare to on-disk, atomic rewrite (via `tempfile::NamedTempFile::persist`) + `podman exec ... kill -HUP 1` on drift.
+- Same pattern for `lnd.conf`.
+- First user of the eventual `reconcile::` module — ships the `derived.rs` piece early.
+
+### v1.7.44 — Podman state self-heal on startup (closes FM6)
+- Startup probe: `podman info --format '{{.Host.OS}}'` with 10s timeout.
+- On "invalid internal status" or similar:
+  - `systemctl --user stop podman.socket podman.service`
+  - `rm -rf /run/user/$UID/{containers,libpod,podman}`
+  - `podman system renumber`
+  - Trigger reconcile tick (will rebuild containers from their source of truth)
+- Surface clear error on `/health` if recovery fails — don't silently serve 502.
+
+### v1.7.45–47 — Quadlet migration per companion (closes FM1 + FM3)
+One companion per release so regressions have a narrow blame window:
+
+- **v1.7.45**: `archy-bitcoin-ui` → Quadlet `.container` unit
+- **v1.7.46**: `archy-lnd-ui` → Quadlet
+- **v1.7.47**: `archy-electrs-ui` → Quadlet
+
+Each:
+1. Write `.container` file to `/etc/containers/systemd/<name>.container`
+2. `systemctl daemon-reload`
+3. `systemctl enable --now <name>.service`
+4. Remove the `podman run` path from `install.rs` for that name
+5. Add Goss probe for the lifecycle test matrix
+
+### v1.7.48+ — Full reconcile module
+- `core/archipelago/src/reconcile/` replaces imperative `install.rs` container management.
+- Main app containers (bitcoin-knots, bitcoin-core, lnd, electrumx, btcpay-server, mempool, fedimint) become Quadlet units.
+- `install.rs` shrinks to ~300 lines of "write desired state, poke reconciler."
+- Biggest diff, lands last.
+
+---
+
+## Test harness (parallel track)
+
+### Stack
+
+- **Outer runner**: `bats-core` — TAP-style bash testing, readable by anyone
+- **Verifier**: `goss` — YAML assertions on ports, processes, HTTP endpoints, files. Reused by CI + live probe
+- **Chaos layer**: Chaos Toolkit JSON experiments (steady-state-hypothesis → method → rollback → verify)
+- **VM layer**: `vmtest` (Go) for reboot-survival + ISO-boot tests, or raw QEMU+SSH
+- **Tor probe**: curl through archipelago's own tor SOCKS5 (`--socks5-hostname 127.0.0.1:9050`), 60-180s retry window
+- **Live probe**: small Rust agent on every fleet node, ships same Goss YAMLs to Prometheus. Neither Umbrel nor StartOS has this — real differentiator.
+- **Reproducibility**: btrfs subvolume snapshots primary (fast), QEMU qcow2 for ISO/kernel-level repro
+
+### Directory layout
+
+```
+tests/lifecycle/
+  bats/
+    _helpers.bash              # install_app, wait_healthy, assert_no_orphans
+    00_bootstrap.bats
+    10_install.bats            # per-app install
+    20_ui_reachable.bats       # direct port + HTTPS proxy + iframe
+    30_tor_reachable.bats      # .onion probe
+    40_stop_start.bats
+    50_restart.bats
+    60_reboot.bats             # vmtest-driven
+    70_reinstall.bats          # idempotence + data preservation
+    80_uninstall.bats          # leak check
+    90_soak.bats               # 2-6h hold, periodic probe
+  goss/
+    bitcoin-knots.yaml
+    bitcoin-core.yaml
+    lnd.yaml
+    electrumx.yaml
+    btcpay-server.yaml
+    mempool.yaml
+    fedimint.yaml
+  chaos/
+    kill9_archipelago_mid_install.json
+    wipe_bolt_db.json
+    kill9_bitcoind.json
+    reboot_during_ota.json
+    corrupt_bitcoin_conf.json
+    systemctl_restart_mid_install.json
+    fill_disk_99_percent.json
+    kill_tor.json
+    delete_nginx_snippet.json
+    clock_jump_30min.json
+  vm/
+    iso_boot_smoke.go
+    reboot_survival.go
+  ci/
+    vm_runner.sh
+    collect_artifacts.sh
+probe/archy-probe/             # Rust bin, reuses goss YAMLs, ships to fleet
+Makefile                       # `make beta-matrix`, `make chaos`, `make soak`
+```
+
+### Minimum beta matrix
+
+7 apps × 9 lifecycle events × 10 chaos scenarios. Pass = every MUST-ship cell green on fresh rootless-podman single-node CI.
+
+| Case \ App | knots | core | lnd | electrumx | btcpay | mempool | fedimint |
+|---|---|---|---|---|---|---|---|
+| Fresh install | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| UI direct port | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| UI HTTPS proxy | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| UI iframe | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Tor .onion reachable | ✓ | ✓ | ✓ | — | ✓ | ✓ | ✓ |
+| Stop → ports released | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Restart → integrations | — | — | ✓↔btc | ✓↔btc | ✓↔btc,lnd | ✓↔electrs | — |
+| Reboot survival | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Reinstall idempotent | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Uninstall no orphans | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| 6h soak | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+**Harness scaffold lands in v1.7.41.** First lifecycle tests blocking v1.7.45. Full matrix + chaos suite blocking beta tag.
+
+### Chaos scenarios (10)
+
+Ordered by likelihood × severity:
+
+1. `kill -9 archipelagod` mid-install → systemd restart, in-flight install resumes or cleanly rolls back
+2. `rm bolt_state.db` while service stopped → restart regenerates, no data loss in named volumes
+3. `systemctl restart archipelago` mid-install → no orphans, no half-state
+4. Reboot mid-OTA → old version intact OR new version active, never half
+5. Corrupt `bitcoin.conf` → container restart-loops; UI surfaces banner; reconcile re-derives; other apps unaffected
+6. Fill `/var` to 99% → graceful degradation, disk-pressure report
+7. Revoke rootless-netns → self-heal within Tor descriptor window
+8. `pkill -9 tor` → supervisor restarts; onions reachable within 3–5 min
+9. Delete nginx conf snippet → reconciler rewrites or `archipelago doctor` flags drift
+10. Clock jump +30min → daemons survive; Tor recovers
+
+---
+
+## Decision log
+
+| Decision | Answer | Rationale |
+|---|---|---|
+| Scope | 6+ incremental releases, not big-bang rewrite | Each closes one failure class, narrow blame window |
+| Quadlet migration | Yes | Isolation from daemon crashes, systemd-native recovery, free from Red Hat's production patterns. Minimum podman version becomes 4.4+ (fine for modern Debian) |
+| Live probe to Prometheus | Yes, part of beta | Genuine differentiator — neither Umbrel nor StartOS has this. Adds Grafana dep |
+| Test gating | Scaffold in v1.7.41, first tests blocking v1.7.45, full matrix blocking beta tag | Gradual rather than all-or-nothing |
+
+---
+
+## Key sources
+
+### Architecture
+- Umbrel [app.ts](https://raw.githubusercontent.com/getumbrel/umbrel/master/packages/umbreld/source/modules/apps/app.ts) — edge-triggered, TODO on failure handling
+- StartOS [repo](https://github.com/Start9Labs/start-os), [v0.4 podman→LXC announce](https://community.start9.com/t/startos-v0-4-0-alpha-10-has-replaced-podman-new-commands-for-terminal/4062)
+- balena-supervisor [repo](https://github.com/balena-os/balena-supervisor), [Supervisor API](https://docs.balena.io/reference/supervisor/supervisor-api)
+- Quadlet: [Dan Walsh 2023 blog](https://www.redhat.com/en/blog/quadlet-podman), [podman-systemd.unit(5)](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html)
+- Podman rollback: [auto-update blog](https://www.redhat.com/en/blog/podman-auto-updates-rollbacks), [podman-auto-update(1)](https://docs.podman.io/en/latest/markdown/podman-auto-update.1.html)
+- Kubernetes operator pattern: [Kubebuilder reconcile](https://deepwiki.com/kubernetes-sigs/kubebuilder/5.2-reconciliation-loop), [good practices](https://book.kubebuilder.io/reference/good-practices)
+- NixOS containers: [wiki](https://wiki.nixos.org/wiki/NixOS_Containers)
+
+### Known bugs & references
+- `host.containers.internal` → LAN: [podman #22644](https://github.com/containers/podman/issues/22644), [#23782](https://github.com/containers/podman/issues/23782)
+- `bolt_state.db` recovery: [podman #17730](https://github.com/containers/podman/issues/17730), [staticdir mismatch #20872](https://github.com/containers/podman/issues/20872)
+- aardvark-dns flakiness: [#20396](https://github.com/containers/podman/issues/20396), [#22407](https://github.com/containers/podman/issues/22407)
+- systemd 226/NAMESPACE: [Arch forum](https://bbs.archlinux.org/viewtopic.php?id=156963), [systemd #29526](https://github.com/systemd/systemd/issues/29526)
+- [systemd CGROUP_DELEGATION](https://systemd.io/CGROUP_DELEGATION/), [systemd.kill(5)](https://www.freedesktop.org/software/systemd/man/latest/systemd.kill.html)
+
+### Test harness prior art
+- Umbrel [ci.yml](https://github.com/getumbrel/umbrel/blob/master/.github/workflows/ci.yml) — Vitest + qemu matrix fan-out
+- [YunoHost package_check](https://github.com/YunoHost/package_check) — closest analog, scored per-app lifecycle harness on LXC
+- [bats-core](https://github.com/bats-core/bats-core)
+- [Goss](https://github.com/goss-org/goss), [dgoss](https://github.com/aelsabbahy/goss-docker)
+- [Chaos Toolkit](https://chaostoolkit.org/)
+- [vmtest (Go)](https://github.com/anatol/vmtest)
+
+### Tor
+- [rend-spec-v3](https://github.com/torproject/torspec/blob/main/rend-spec-v3.txt) — descriptor lifetime + republish cadence
+- [stem](https://stem.torproject.org/) — Python Tor controller for `HS_DESC UPLOADED` waits
+
+---
+
+## To resume
+
+1. Read project memory: `~/.claude/projects/-home-archipelago-Projects-archy/memory/project_reconcile_architecture.md`
+2. Read failure-mode memory: `~/.claude/projects/-home-archipelago-Projects-archy/memory/feedback_container_lifecycle_failure_modes.md`
+3. Check task list for current release (should start with v1.7.41)
+4. Current state on fleet as of 2026-04-22:
+   - All 4 mirrors (tx1138, gitea-local, .160, .168) synced to v1.7.40-alpha
+   - .116, .198, .228, .253 healed manually via `systemd-run chmod 755 /opt/archipelago/web-ui`
+   - .228 still has stale `bitcoin.conf` rpcauth (regenerated during triage; will drift again until v1.7.43)
+   - .228 UI companions (archy-bitcoin-ui, archy-lnd-ui) keep vanishing (Quadlet migration in v1.7.45+ fixes)
+   - .160 Gitea required `podman system renumber` recovery (v1.7.44 automates this)
+5. Implementation is in progress on `main` branch — next edit is `core/archipelago/src/update.rs` for v1.7.41.
@@ -0,0 +1,525 @@
+# Rust Orchestrator Migration — Design Doc
+
+Status: **DRAFT — pending user approval**
+Author: OpenCode session, 2026-04-22
+Supersedes planning in `docs/bulletproof-containers.md` v1.7.43 slot
+
+## Problem statement
+
+Today, the archipelago backend has **no production container orchestrator**. Production containers (bitcoin-knots, lnd, electrumx, btcpay, filebrowser, and the three custom UIs archy-bitcoin-ui / archy-electrs-ui / archy-lnd-ui) are installed by **bash scripts** at first boot (`scripts/first-boot-containers.sh`) and optionally reconciled by another bash script (`scripts/reconcile-containers.sh`) that is **not enabled by default**. The existing `DevContainerOrchestrator` (`core/archipelago/src/container/dev_orchestrator.rs`) is hardcoded to append `-dev` suffixes and gated behind `config.dev_mode`, so it has never managed a production container.
+
+This design migrates production container management into Rust, under a single orchestrator that owns install, start, stop, restart, upgrade, uninstall, health, and self-healing for every container. The three custom UI containers are the first-class test fixture: they exercise the "build image from local Dockerfile" path (which today doesn't exist in the manifest schema) and their lifecycle was the original failure class the user asked to fix.
+
+## Non-goals
+
+- Backwards compatibility with `first-boot-containers.sh`: we **delete** it and its systemd unit after verifying Rust parity.
+- Backwards compatibility with the existing `package-install` RPC’s podman shell-outs: those get rewritten to call the orchestrator.
+- Registry signature verification: `image_signature` stays optional. Sigstore/cosign integration is out of scope.
+- Network isolation improvements: existing SecurityPolicy fields stay as-is.
+- Dev mode removal: `DevContainerOrchestrator` keeps existing behavior for local development; prod code path is separate.
+
+## Scope of this migration
+
+In scope:
+1. Extend `ContainerConfig` schema with a `source:` variant supporting `{type: build, context, dockerfile, tag}` alongside `{type: pull, image, pull_policy}`.
+2. Extend `ContainerRuntime` trait + `PodmanRuntime` impl with `build_image(...)` and `image_exists(...)`.
+3. Introduce `ProdContainerOrchestrator` (new type) with identical public surface to `DevContainerOrchestrator` but **no `-dev` suffix**, **no port offset**, **no data-path rewriting**, **no bitcoin_simulator gate**. It is wired into `RpcHandler::orchestrator` in prod (currently `None`).
+4. Add `AdoptionScan` at orchestrator startup: enumerate `podman ps -a`, match by container name against declared manifests, adopt into orchestrator state without recreating.
+5. Add `BootReconciler` task spawned from `main.rs` (replacing the commented-out `run_boot_reconciliation` hook). Walks the manifest set on startup and periodically, ensures each is present-and-running, builds/pulls/creates anything missing, logs failures non-silently.
+6. Ship three manifests in the repo: `apps/bitcoin-ui/manifest.yml`, `apps/electrs-ui/manifest.yml`, `apps/lnd-ui/manifest.yml`. They use the new `source: build` variant pointing at `/opt/archipelago/docker/<name>/`.
+7. Delete `scripts/first-boot-containers.sh`, `scripts/reconcile-containers.sh`, `scripts/container-specs.sh`, `image-recipe/configs/archipelago-first-boot-containers.service`, `image-recipe/configs/archipelago-reconcile.service`. Remove enablement from ISO builder.
+
+Out of scope this migration (tracked separately):
+- Migrating btcpay / mempool / fedimint multi-container stacks to manifests (they currently live in `core/archipelago/src/api/rpc/package/stacks.rs`). They keep working via `package-install` RPC. Phase 2.
+- Rewriting the 26 existing `apps/*/manifest.yml` files to use the new `source:` schema. They stay on `image:` for now; the schema is **additive and backwards-compatible**.
+- Re-enabling signature verification; stays todo.
+
+## Data model changes
+
+### 1. `ContainerConfig` gets a `source` enum
+
+File: `core/container/src/manifest.rs:58`
+
+**Before:**
+```rust
+pub struct ContainerConfig {
+    pub image: String,
+    pub image_signature: Option<String>,
+    pub pull_policy: String,
+}
+```
+
+**After:**
+```rust
+pub struct ContainerConfig {
+    // Legacy shorthand (backwards compatible with all 26 existing manifests):
+    // if `source` is absent, `image` + `pull_policy` are interpreted as
+    // `source: { type: pull, image, pull_policy }`.
+    #[serde(default)]
+    pub image: String,
+    #[serde(default)]
+    pub image_signature: Option<String>,
+    #[serde(default = "default_pull_policy")]
+    pub pull_policy: String,
+
+    // New: explicit source. If present, overrides the legacy shorthand.
+    #[serde(default)]
+    pub source: Option<ContainerSource>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(tag = "type", rename_all = "lowercase")]
+pub enum ContainerSource {
+    /// Pull an image from a registry.
+    Pull {
+        image: String,
+        #[serde(default)]
+        image_signature: Option<String>,
+        #[serde(default = "default_pull_policy")]
+        pull_policy: String,
+    },
+    /// Build an image from a local Dockerfile.
+    Build {
+        /// Filesystem path to build context, absolute or relative to manifest dir.
+        context: String,
+        /// Dockerfile path relative to context. Defaults to "Dockerfile".
+        #[serde(default = "default_dockerfile")]
+        dockerfile: String,
+        /// Tag to assign to the built image, e.g. "localhost/bitcoin-ui:local".
+        tag: String,
+        /// `--build-arg` key=value pairs.
+        #[serde(default)]
+        build_args: HashMap<String, String>,
+        /// If true, rebuild on every reconcile. If false, only build when tag is missing.
+        #[serde(default)]
+        always_rebuild: bool,
+    },
+}
+```
+
+Validation in `AppManifest::validate`:
+- If `source` is absent AND `image` is empty → error (unchanged rule just rephrased).
+- If `source` is present, legacy `image` field is ignored with a warning.
+- `Build::context` must resolve to an existing directory that contains `dockerfile`.
+
+Tests to add:
+- Parse a legacy manifest → works, produces `ContainerSource::Pull` at resolution time.
+- Parse a `source: { type: build, ... }` manifest → works.
+- Parse a manifest with both legacy `image:` and `source:` → warning logged, `source:` wins.
+- Parse a manifest with neither → rejected.
+
+### 2. `ContainerRuntime` trait gets `build_image` + `image_exists`
+
+File: `core/container/src/runtime.rs:10`
+
+```rust
+#[async_trait]
+pub trait ContainerRuntime: Send + Sync {
+    // existing methods unchanged...
+    async fn pull_image(&self, image: &str, signature: Option<&str>) -> Result<()>;
+    async fn create_container(...) -> Result<()>;
+    // ...
+
+    // NEW:
+    /// Build an image from a local Dockerfile. Returns Ok(()) if the image now
+    /// exists under the given tag (whether newly built or already present and
+    /// `force=false`). Returns Err if the build failed.
+    async fn build_image(
+        &self,
+        context: &Path,
+        dockerfile: &str,
+        tag: &str,
+        build_args: &HashMap<String, String>,
+        force: bool,
+    ) -> Result<()>;
+
+    /// Check if an image exists in the local image store.
+    async fn image_exists(&self, tag: &str) -> Result<bool>;
+}
+```
+
+`PodmanRuntime::build_image` shells out:
+```
+podman build --tag <tag> \
+    --file <context>/<dockerfile> \
+    --build-arg KEY=VALUE ... \
+    <context>
+```
+
+Force-rebuild semantics: if `force=false`, skip when `image_exists(tag) == true`. If `force=true`, always build (podman's own layer cache handles the fast path).
+
+Tests:
+- `build_image` happy path on a minimal Dockerfile (using a throwaway context in tmpdir).
+- `build_image` failure path (nonsense Dockerfile) → Err.
+- `image_exists` returns false for nonexistent tag.
+- `image_exists` returns true after `build_image`.
+
+### 3. Manifest resolution: `ContainerSource::resolve(manifest_dir) -> ResolvedSource`
+
+New method that turns the raw manifest into something the orchestrator can act on:
+
+```rust
+pub enum ResolvedSource {
+    Pull { image: String, signature: Option<String>, pull_policy: PullPolicy },
+    Build { context: PathBuf, dockerfile: String, tag: String, build_args: HashMap<String,String>, always_rebuild: bool },
+}
+
+impl ContainerConfig {
+    pub fn resolve(&self, manifest_dir: &Path) -> Result<ResolvedSource> {
+        match &self.source {
+            Some(ContainerSource::Pull { image, image_signature, pull_policy }) => Ok(ResolvedSource::Pull { ... }),
+            Some(ContainerSource::Build { context, dockerfile, tag, build_args, always_rebuild }) => {
+                let abs_context = if Path::new(context).is_absolute() {
+                    PathBuf::from(context)
+                } else {
+                    manifest_dir.join(context)
+                };
+                Ok(ResolvedSource::Build { context: abs_context, ... })
+            }
+            None => {
+                // Legacy shorthand
+                if self.image.is_empty() {
+                    return Err(...);
+                }
+                Ok(ResolvedSource::Pull { image: self.image.clone(), ... })
+            }
+        }
+    }
+}
+```
+
+## Runtime architecture
+
+### `ProdContainerOrchestrator`
+
+New file: `core/archipelago/src/container/prod_orchestrator.rs`
+
+```rust
+pub struct ProdContainerOrchestrator {
+    runtime: Arc<dyn ContainerRuntimeTrait>,
+    manifests_dir: PathBuf,   // e.g. /opt/archipelago/apps
+    data_dir: PathBuf,        // e.g. /var/lib/archipelago
+    state: Arc<RwLock<OrchestratorState>>,
+    config: Config,
+}
+
+struct OrchestratorState {
+    /// app_id → known manifest (loaded from disk at startup, refreshed on reconcile)
+    manifests: HashMap<String, AppManifest>,
+    /// app_id → current known state (from adoption scan or our own ops)
+    containers: HashMap<String, ContainerState>,
+    /// app_id → last install/health/build timestamp
+    last_reconciled: HashMap<String, Instant>,
+}
+```
+
+Public surface mirrors `DevContainerOrchestrator` but **container name = `archy-<app_id>` for UI apps, `<app_id>` for backends, matching existing .116 naming**:
+
+```rust
+impl ProdContainerOrchestrator {
+    pub async fn new(config: Config) -> Result<Self> { ... }
+    pub async fn load_manifests(&self) -> Result<()> { /* walks manifests_dir */ }
+    pub async fn adopt_existing(&self) -> Result<AdoptionReport> { /* scans podman ps -a */ }
+    pub async fn reconcile_all(&self) -> Result<ReconcileReport> { /* ensures every manifest has a running container */ }
+    pub async fn install(&self, app_id: &str) -> Result<()> { /* build-or-pull + create + start */ }
+    pub async fn start(&self, app_id: &str) -> Result<()> { ... }
+    pub async fn stop(&self, app_id: &str) -> Result<()> { ... }
+    pub async fn restart(&self, app_id: &str) -> Result<()> { ... }
+    pub async fn remove(&self, app_id: &str, preserve_data: bool) -> Result<()> { ... }
+    pub async fn upgrade(&self, app_id: &str) -> Result<()> { /* re-read manifest, rebuild/pull, recreate */ }
+    pub async fn status(&self, app_id: &str) -> Result<ContainerStatus> { ... }
+    pub async fn list(&self) -> Result<Vec<ContainerStatus>> { ... }
+    pub async fn logs(&self, app_id: &str, lines: u32) -> Result<Vec<String>> { ... }
+    pub async fn health(&self, app_id: &str) -> Result<String> { ... }
+}
+```
+
+**Container naming rule** (matches `.116` existing fixture so adoption works):
+- If the manifest has `extensions["container_name"]` → use that verbatim.
+- Else if the app_id starts with `bitcoin-ui` / `electrs-ui` / `lnd-ui` → `archy-<app_id>`.
+- Else → `<app_id>`.
+
+This is codified and tested; no ad-hoc naming in the codebase.
+
+### `AdoptionScan`
+
+On orchestrator startup, before any reconcile:
+
+```rust
+async fn adopt_existing(&self) -> Result<AdoptionReport> {
+    let all = self.runtime.list_containers().await?;  // podman ps -a
+    let mut report = AdoptionReport::default();
+    for c in all {
+        // For each manifest we have loaded, check if the expected container name matches
+        for (app_id, manifest) in self.state.read().await.manifests.iter() {
+            let expected_name = compute_container_name(manifest);
+            if c.name == expected_name {
+                // This container is ours. Record its state.
+                self.state.write().await.containers.insert(app_id.clone(), c.state.clone());
+                report.adopted.push(app_id.clone());
+            }
+        }
+    }
+    Ok(report)
+}
+```
+
+No recreate. No touching data volumes. Just "we now know this container belongs to app X and its current state is Y".
+
+### `BootReconciler`
+
+New file: `core/archipelago/src/container/boot_reconciler.rs`
+
+```rust
+pub struct BootReconciler {
+    orchestrator: Arc<ProdContainerOrchestrator>,
+    interval: Duration,  // e.g. 5 minutes
+    shutdown: CancellationToken,
+}
+
+impl BootReconciler {
+    pub async fn run_forever(self) {
+        // Initial reconcile immediately (after adoption).
+        let _ = self.orchestrator.reconcile_all().await;
+        loop {
+            tokio::select! {
+                _ = tokio::time::sleep(self.interval) => {
+                    let _ = self.orchestrator.reconcile_all().await;
+                }
+                _ = self.shutdown.cancelled() => break,
+            }
+        }
+    }
+}
+```
+
+`reconcile_all`:
+```rust
+async fn reconcile_all(&self) -> Result<ReconcileReport> {
+    let manifests: Vec<_> = self.state.read().await.manifests.values().cloned().collect();
+    let mut report = ReconcileReport::default();
+    for manifest in manifests {
+        let app_id = &manifest.app.id;
+        match self.ensure_running(&manifest).await {
+            Ok(action) => report.record(app_id, action),
+            Err(e) => {
+                tracing::error!(app_id, error = %e, "Reconcile failed for app");
+                report.failures.push((app_id.clone(), e.to_string()));
+            }
+        }
+    }
+    if !report.failures.is_empty() {
+        // Surface via WebSocket so the UI can show a banner.
+        self.notify_failures(&report).await;
+    }
+    Ok(report)
+}
+
+async fn ensure_running(&self, manifest: &AppManifest) -> Result<ReconcileAction> {
+    let name = compute_container_name(manifest);
+    match self.runtime.get_container_status(&name).await {
+        Ok(status) if matches!(status.state, ContainerState::Running) => Ok(ReconcileAction::NoOp),
+        Ok(status) if matches!(status.state, ContainerState::Exited | ContainerState::Stopped) => {
+            self.runtime.start_container(&name).await?;
+            Ok(ReconcileAction::Started)
+        }
+        Ok(_) => Ok(ReconcileAction::NoOp),  // Created / Paused — leave alone
+        Err(_) => {
+            // Container doesn't exist. Install it.
+            self.install_fresh(manifest).await?;
+            Ok(ReconcileAction::Installed)
+        }
+    }
+}
+
+async fn install_fresh(&self, manifest: &AppManifest) -> Result<()> {
+    let manifest_dir = ...;  // directory of manifest.yml
+    let resolved = manifest.app.container.resolve(manifest_dir)?;
+    match resolved {
+        ResolvedSource::Pull { image, signature, .. } => {
+            self.runtime.pull_image(&image, signature.as_deref()).await?;
+        }
+        ResolvedSource::Build { context, dockerfile, tag, build_args, always_rebuild } => {
+            if always_rebuild || !self.runtime.image_exists(&tag).await? {
+                self.runtime.build_image(&context, &dockerfile, &tag, &build_args, always_rebuild).await?;
+            }
+        }
+    }
+    self.runtime.create_container(manifest, &compute_container_name(manifest), 0).await?;
+    self.runtime.start_container(&compute_container_name(manifest)).await?;
+    Ok(())
+}
+```
+
+### Wire-up in `main.rs`
+
+File: `core/archipelago/src/main.rs`
+
+Replace the commented-out `run_boot_reconciliation` block (`main.rs:107-111`) with:
+
+```rust
+// Load manifests + adopt existing + start reconciler loop.
+let orchestrator = Arc::new(ProdContainerOrchestrator::new(config.clone()).await?);
+orchestrator.load_manifests().await?;
+let adoption = orchestrator.adopt_existing().await?;
+tracing::info!(adopted = adoption.adopted.len(), "Container adoption complete");
+let reconciler = BootReconciler::new(orchestrator.clone(), Duration::from_secs(300), shutdown_token.clone());
+tokio::spawn(reconciler.run_forever());
+```
+
+`RpcHandler` gets the orchestrator regardless of `dev_mode`:
+```rust
+// core/archipelago/src/api/rpc/mod.rs:83
+let orchestrator: Option<Arc<dyn ContainerOrchestrator>> = if config.dev_mode {
+    Some(Arc::new(DevContainerOrchestrator::new(config.clone()).await?))
+} else {
+    Some(Arc::new(prod_orch.clone()))
+};
+```
+
+Where `ContainerOrchestrator` becomes a trait implemented by both `DevContainerOrchestrator` and `ProdContainerOrchestrator`.
+
+### First-boot replacement
+
+There is no separate first-boot code. The reconciler handles it: when the archipelago service starts on a fresh node, `adopt_existing` finds nothing, `reconcile_all` sees no running container for any manifest, and installs each one in dependency order (bitcoin-core first, then everything else). On subsequent boots, adoption finds existing containers and reconcile mostly no-ops.
+
+**Removes completely**:
+- `/var/lib/archipelago/.first-boot-containers-done` marker (no longer needed)
+- `/var/lib/archipelago/.unbundled` handling in first-boot script (becomes a config flag in archipelago.conf if we still need it)
+- `scripts/first-boot-containers.sh` (1392 lines)
+- `scripts/reconcile-containers.sh`
+- `scripts/container-specs.sh`
+- `image-recipe/configs/archipelago-first-boot-containers.service`
+- `image-recipe/configs/archipelago-reconcile.service`
+- Related enable/disable in ISO builder
+
+## The three UI manifests
+
+Example: `apps/bitcoin-ui/manifest.yml`
+
+```yaml
+app:
+  id: bitcoin-ui
+  name: Bitcoin Knots UI
+  version: 1.0.0
+  description: Custom Archipelago UI for Bitcoin Knots
+  container:
+    source:
+      type: build
+      context: /opt/archipelago/docker/bitcoin-ui
+      dockerfile: Dockerfile
+      tag: localhost/bitcoin-ui:local
+      build_args:
+        BITCOIN_RPC_AUTH: ${BITCOIN_RPC_AUTH}  # injected from host-ip.env or secrets
+      always_rebuild: false
+  dependencies:
+    - app_id: bitcoin-core
+  resources:
+    memory_limit: 128Mi
+  security:
+    network_policy: host
+    readonly_root: false
+  ports: []  # host networking
+  volumes: []
+  environment: []
+  health_check:
+    type: http
+    endpoint: http://127.0.0.1:8334
+    path: /
+    interval: 30s
+  extensions:
+    container_name: archy-bitcoin-ui
+```
+
+The `extensions.container_name` is how we match the existing running container on .116 for adoption. Same pattern for `electrs-ui` (container_name: `archy-electrs-ui`, port probe 50002) and `lnd-ui` (container_name: `archy-lnd-ui`, port probe 8081).
+
+**BITCOIN_RPC_AUTH injection**: today `first-boot-containers.sh` `sed`s this value into `nginx.conf` (destructively). In the new world, it's a `--build-arg` — the Dockerfile gets `ARG BITCOIN_RPC_AUTH` and templates `nginx.conf` from a template file. Fixes the "sed destroys the source" bug from the mapping.
+
+## Migration path (.116 and .228 specifically)
+
+### .116 (all 3 UIs currently running, adopted from bash install)
+1. Ship the new archipelago binary with the prod orchestrator.
+2. On archipelago restart, `adopt_existing` scans `podman ps -a`, sees `archy-bitcoin-ui`, `archy-electrs-ui`, `archy-lnd-ui` already running.
+3. Matches them against the new manifests by `extensions.container_name`.
+4. Records state. Reconciler sees them Running → NoOp.
+5. Manual test: `podman stop archy-bitcoin-ui` → within 5 minutes, reconciler starts it again. `podman rm -f archy-bitcoin-ui` → reconciler rebuilds from `/opt/archipelago/docker/bitcoin-ui/Dockerfile` and re-creates.
+
+### .228 (no bitcoin-ui, no lnd-ui, has electrs-ui from bash first-boot)
+1. Ship same binary.
+2. Adoption finds only `archy-electrs-ui`.
+3. Reconciler sees `bitcoin-ui` and `lnd-ui` missing → triggers `install_fresh` for each.
+4. For `bitcoin-ui`: `image_exists("localhost/bitcoin-ui:local")` → false. `build_image(/opt/archipelago/docker/bitcoin-ui, Dockerfile, localhost/bitcoin-ui:local, {BITCOIN_RPC_AUTH: ...}, force=false)`. Then create + start.
+5. Same for `lnd-ui`.
+6. Manual test: HTTP probe ports 8334 and 8081 return 200 within ~5 minutes of service restart.
+
+## Test plan
+
+Unit tests (Rust, in-process):
+- `manifest::tests::legacy_image_parses_as_pull_source`
+- `manifest::tests::explicit_pull_source_parses`
+- `manifest::tests::explicit_build_source_parses`
+- `manifest::tests::source_build_requires_tag`
+- `runtime::tests::build_image_happy_path` (uses a minimal Dockerfile in `tempfile::TempDir`)
+- `runtime::tests::build_image_failure`
+- `runtime::tests::image_exists_roundtrip`
+- `prod_orchestrator::tests::install_fresh_pull`
+- `prod_orchestrator::tests::install_fresh_build`
+- `prod_orchestrator::tests::adopt_existing_matches_by_name`
+- `prod_orchestrator::tests::reconcile_starts_exited_container` (with a mock runtime)
+- `prod_orchestrator::tests::reconcile_installs_missing_container`
+- `prod_orchestrator::tests::compute_container_name_ui_apps_prefixed`
+- `prod_orchestrator::tests::compute_container_name_backend_apps_bare`
+
+Integration tests (require real podman, run on archy node):
+- Fresh-install path: wipe containers + images, start archipelago, verify all 3 UIs up within 60s.
+- Adoption path: containers pre-running, start archipelago, verify no recreate (compare container IDs before/after).
+- Reconcile-start path: `podman stop archy-bitcoin-ui`, wait, verify restart.
+- Reconcile-recreate path: `podman rm -f archy-bitcoin-ui`, wait, verify rebuild+recreate.
+- Rebuild-on-Dockerfile-change path: edit Dockerfile, call `upgrade` RPC, verify image rebuilt and container recreated.
+
+Chaos matrix (bash + Playwright, the original goal):
+- For each UI (bitcoin-ui, electrs-ui, lnd-ui) × each event (stop, start, restart, remove+reconcile, SIGKILL, archipelago-service-restart, host-reboot) × each node (.116, .228): assert HTTP 200 + page-title marker returns within 60s of event.
+
+## Risks + mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| Adoption mismatches and re-creates a container we already had, losing its data | Adoption matches by exact name; `install_fresh` only runs when `get_container_status` returns Err (container doesn't exist), not when it returns Stopped/Exited. Unit tested. |
+| Build loop: reconciler rebuilds on every tick | `always_rebuild: false` + `image_exists` check. Only rebuilds when image tag is missing OR `upgrade` RPC is called. |
+| Reconciler runs while user is mid-install via the UI | Orchestrator state has per-app mutex; reconcile waits. Install path takes the same mutex. |
+| Auto-rollback (v1.7.41) fires during testing | `reconcile_all` is spawned AFTER server is healthy and responding; if it fails, archipelago the service still passes verification. Individual container failures are logged, not fatal. |
+| Dependency ordering: bitcoin-ui needs BITCOIN_RPC_AUTH which is generated at first boot | Reconciler handles dependency order by reading `manifest.app.dependencies` and installing in topological order. If the dep doesn't exist yet, skip and retry next tick. |
+| Moving `/opt/archipelago/docker/<name>` content breaks the build context | That path is stable per the ISO builder at `image-recipe/build-auto-installer-iso.sh:1671-1685`. Manifests reference it absolutely. |
+| Dropping bash scripts breaks existing ISOs in the field | Target release cycle is disposable alpha nodes. For existing alpha nodes (.116, .228) we hot-swap the binary and let the reconciler take over, then the next reboot doesn't need the systemd units; we mask them manually. |
+| User wants to downgrade to v1.7.42 | Auto-rollback mechanism already handles that; binary swap is reversible. The removed bash scripts are still in git history. |
+
+## Implementation order
+
+1. **Schema first**: extend `ContainerConfig` + `ContainerSource` + `resolve()` + validation + unit tests. ~100 LOC Rust + ~80 LOC tests.
+2. **Runtime**: `build_image` + `image_exists` in trait, `PodmanRuntime`, `DockerRuntime` (can stub), `AutoRuntime`. ~150 LOC + tests with throwaway tempdir Dockerfile.
+3. **ProdContainerOrchestrator**: new type with `install/start/stop/restart/remove/status/list/logs/health/adopt_existing/reconcile_all/ensure_running/install_fresh`. ~400 LOC + unit tests with mocked runtime.
+4. **ContainerOrchestrator trait**: abstract over Dev and Prod so `RpcHandler` is polymorphic. ~50 LOC refactor.
+5. **BootReconciler**: task spawner with loop + cancellation. ~80 LOC + unit tests.
+6. **main.rs wire-up**: adopt + spawn reconciler. ~20 LOC.
+7. **3 UI manifests + Dockerfile BITCOIN_RPC_AUTH refactor** (use ARG + template file, not sed). ~60 lines of YAML + ~20 lines of Dockerfile.
+8. **Remove bash scripts + services**: split into sub-steps because `first-boot-containers.sh` creates 25+ containers (only 3 ported in Step 7) AND does non-container setup (secret gen, UID-mapping chowns, Tor hostnames, WireGuard, firewall, nostr-relay dir):
+   - **8a** (cheap, safe): delete `image-recipe/configs/archipelago-reconcile.{service,timer}` + their ISO-builder touchpoints (the systemd enablement + `cp` into `$WORK_DIR`). `BootReconciler` fully replaces the timer-driven path — no more periodic bash invocation. **Keep** `scripts/reconcile-containers.sh` + `scripts/container-specs.sh` because `core/archipelago/src/api/rpc/package/update.rs` still shells out to reconcile-containers.sh during OTA updates; porting that call site requires manifests for every container it touches (which is Step 8b's scope). Atomic commit, low risk.
+   - **8b** (large, deferred): port the remaining ~25 container creations from `first-boot-containers.sh` into `apps/<id>/manifest.yml` files. One manifest per commit, validated against current bash behavior (ports, volumes, env, deps, health checks, post-create wallet/db bootstrap). Probably 1-2 days of careful porting. Includes `apps/filebrowser/manifest.yml`. Then port `update.rs`'s two `reconcile-containers.sh` call sites to the `ContainerOrchestrator` trait (`upgrade(app_id)`).
+   - **8c** (final, one-way door): rename `first-boot-containers.sh` → `first-boot-setup.sh`, strip out all `$DOCKER run/pull/exec` calls, keep only secret generation + dir prep + Tor/WG/firewall/nostr setup. Rename `archipelago-first-boot-containers.service` → `archipelago-first-boot-setup.service`. Delete `scripts/reconcile-containers.sh` + `scripts/container-specs.sh` (update.rs no longer needs them). Add ISO builder lines to copy `apps/*/manifest.yml` → `/opt/archipelago/apps/`. Full ISO build test on .116 required before commit.
+9. **Live test on .228**: hot-swap binary, expect 3 UIs to come up within 60s of service restart.
+10. **Live test on .116**: hot-swap binary, expect zero container recreation + adoption-confirmed log lines.
+11. **Chaos matrix** on both nodes.
+
+Each step is a separate commit. Steps 1–6 are independent-enough that they can each have their own test gate.
+
+## Estimated total
+
+~1000 LOC Rust added, ~1500 lines bash deleted, ~50 LOC Rust deleted. 8–12 hours of focused work across multiple sessions. No release pressure per user decision.
+
+## Open questions for user
+
+1. **Container naming**: I propose `archy-<app_id>` for UIs, `<app_id>` for backends (matches current .116 fixture). Alternative: unify on `archy-<app_id>` for everything and migrate existing backends by renaming at adoption. Which?
+2. **BITCOIN_RPC_AUTH injection**: the build-arg approach rebuilds the UI image when the auth value changes. Fine during normal operation (rare). Alternative: mount the nginx.conf at runtime as a volume, never bake auth into the image. Which?
+3. **Reconciler interval**: 5 minutes. Too slow for a dropped container (user sees a broken UI for up to 5 min). Alternative: 30 seconds + more expensive `podman ps` calls. Which?
+4. **Concurrent reconcile + user install**: per-app mutex is the simple answer. Alternative: a single orchestrator-wide mutex (simpler, slower). Which?
+5. **Delete bash scripts in this migration, or keep them around as fallback?** I recommend delete (single source of truth), but deleting `first-boot-containers.sh` is a one-way door in terms of field recovery.
@@ -409,8 +409,6 @@ COPY archipelago-update.service /etc/systemd/system/archipelago-update.service
 COPY archipelago-update.timer /etc/systemd/system/archipelago-update.timer
 COPY archipelago-doctor.service /etc/systemd/system/archipelago-doctor.service
 COPY archipelago-doctor.timer /etc/systemd/system/archipelago-doctor.timer
-COPY archipelago-reconcile.service /etc/systemd/system/archipelago-reconcile.service
-COPY archipelago-reconcile.timer /etc/systemd/system/archipelago-reconcile.timer
 COPY archipelago-tor-helper.service /etc/systemd/system/archipelago-tor-helper.service
 COPY archipelago-tor-helper.path /etc/systemd/system/archipelago-tor-helper.path
 COPY nostr-vpn.service /etc/systemd/system/nostr-vpn.service
@@ -423,7 +421,10 @@ COPY nostr-relay-config.toml /etc/archipelago/nostr-relay-config.toml
 # WireGuard kernel module auto-load on boot
 RUN echo "wireguard" >> /etc/modules-load.d/wireguard.conf

-# Copy container doctor + reconcile scripts (referenced by the services above)
+# Copy container doctor + reconcile scripts (referenced by services and the
+# OTA update RPC; the reconcile systemd timer is gone as of Step 8a, but the
+# script stays until Step 8b/c ports all manifests — update.rs still shells
+# out to it during package updates).
 RUN mkdir -p /home/archipelago/archy/scripts/lib
 COPY container-doctor.sh /home/archipelago/archy/scripts/container-doctor.sh
 COPY reconcile-containers.sh /home/archipelago/archy/scripts/reconcile-containers.sh
@@ -450,7 +451,6 @@ RUN systemctl enable NetworkManager || true && \
    systemctl enable chrony || true && \
    systemctl enable archipelago-update.timer || true && \
    systemctl enable archipelago-doctor.timer || true && \
-    systemctl enable archipelago-reconcile.timer || true && \
    systemctl enable archipelago-tor-helper.path || true && \
    systemctl enable nostr-relay || true
 # archipelago-fips.service + archipelago-wg.service + archipelago-wg-address.service
@@ -540,13 +540,14 @@ NGINXCONF
        echo "   Using archipelago-update.service + timer from configs/"
    fi

-    # Copy container doctor and reconciliation timers + scripts
+    # Copy container doctor timer + reconcile script (the reconcile systemd
+    # timer is gone as of Step 8a — BootReconciler replaces it — but the
+    # reconcile-containers.sh script stays, invoked by the OTA update RPC
+    # until Step 8b/c ports all manifests to the Rust orchestrator).
    if [ -f "$SCRIPT_DIR/configs/archipelago-doctor.service" ]; then
        cp "$SCRIPT_DIR/configs/archipelago-doctor.service" "$WORK_DIR/archipelago-doctor.service"
        cp "$SCRIPT_DIR/configs/archipelago-doctor.timer" "$WORK_DIR/archipelago-doctor.timer"
-        cp "$SCRIPT_DIR/configs/archipelago-reconcile.service" "$WORK_DIR/archipelago-reconcile.service"
-        cp "$SCRIPT_DIR/configs/archipelago-reconcile.timer" "$WORK_DIR/archipelago-reconcile.timer"
-        # Copy the actual scripts the services reference
+        # Copy the actual scripts the services / update RPC reference
        for s in container-doctor.sh reconcile-containers.sh container-specs.sh tor-helper.sh; do
            if [ -f "$SCRIPT_DIR/../scripts/$s" ]; then
                cp "$SCRIPT_DIR/../scripts/$s" "$WORK_DIR/$s"
@@ -557,7 +558,7 @@ NGINXCONF
            mkdir -p "$WORK_DIR/lib"
            cp "$SCRIPT_DIR/../scripts/lib/"*.sh "$WORK_DIR/lib/" 2>/dev/null || true
        fi
-        echo "   Using container doctor + reconcile timers from configs/"
+        echo "   Using container doctor timer from configs/"
    fi

    # Copy Tor helper path-activated service (allows backend to manage Tor as non-root)
@@ -1221,8 +1222,12 @@ fi

 # Include AIUI web app (Claude chat interface)
 AIUI_INCLUDED=0
-# Search multiple locations for a pre-built AIUI app
+# Search multiple locations for a pre-built AIUI app.
+# demo/aiui is the canonical AIUI bundle checked into the repo and is
+# tried first so ISO builds on a fresh clone work without needing any
+# external AIUI checkout.
 for AIUI_DIR in \
+    "$SCRIPT_DIR/../demo/aiui" \
    "$SCRIPT_DIR/../../AIUI/packages/app/dist" \
    "$HOME/AIUI/packages/app/dist" \
    "/home/archipelago/AIUI/packages/app/dist" \
@@ -1245,7 +1250,7 @@ done
 if [ "$AIUI_INCLUDED" = "0" ]; then
    echo "   ⚠️  AIUI not found — build it first:"
    echo "      cd ~/AIUI/packages/app && VITE_BASE_PATH=/aiui/ npx vite build"
-    echo "   Searched: ~/AIUI, /home/archipelago/AIUI, /opt/archipelago/web-ui/aiui"
+    echo "   Searched: demo/aiui, ~/AIUI, /home/archipelago/AIUI, /opt/archipelago/web-ui/aiui"
 fi

 # Copy app manifests
@@ -2240,7 +2245,7 @@ location = "git.tx1138.com"
 insecure = true

 [[registry]]
-location = "23.182.128.160:3000"
+location = "146.59.87.168:3000"
 insecure = true
 REGCONF
 chown -R 1000:1000 /mnt/target/home/archipelago/.config
@@ -2251,7 +2256,7 @@ cat > /mnt/target/var/lib/archipelago/config/registries.json <<'DYNREG'
 {
  "registries": [
    {"url": "git.tx1138.com/lfg2025", "name": "Archipelago Primary", "tls_verify": true, "enabled": true, "priority": 0},
-    {"url": "23.182.128.160:3000/lfg2025", "name": "Archipelago Fallback", "tls_verify": false, "enabled": true, "priority": 10}
+    {"url": "146.59.87.168:3000/lfg2025", "name": "Archipelago Fallback", "tls_verify": false, "enabled": true, "priority": 10}
  ]
 }
 DYNREG
@@ -2992,6 +2997,14 @@ chown -R 1000:1000 /mnt/target/home/archipelago/.config 2>/dev/null || true
 mkdir -p /mnt/target/etc/tmpfiles.d
 echo 'd /run/user/1000 0700 archipelago archipelago -' > /mnt/target/etc/tmpfiles.d/archipelago-runtime.conf

+# Pre-create /var/log/archipelago/ and container-installs.log so the
+# backend (running as `archipelago`) can append to them without needing
+# root. Logrotate rotates files in this directory daily.
+cat > /mnt/target/etc/tmpfiles.d/archipelago-logs.conf <<'LOGSTMPFILES'
+d /var/log/archipelago 0755 archipelago archipelago - -
+f /var/log/archipelago/container-installs.log 0644 archipelago archipelago - -
+LOGSTMPFILES
+
 # Bootstrap switchover — checks when local Bitcoin finishes IBD and switches services
 cat > /mnt/target/etc/systemd/system/archipelago-bootstrap-switchover.service <<'BSSERVICE'
 [Unit]
@@ -1,14 +0,0 @@
-[Unit]
-Description=Archipelago Container Reconciliation
-After=archipelago.service
-
-[Service]
-Type=oneshot
-User=archipelago
-Environment="XDG_RUNTIME_DIR=/run/user/1000"
-Environment="HOME=/home/archipelago"
-Environment="PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
-ExecStart=/home/archipelago/archy/scripts/reconcile-containers.sh
-TimeoutStartSec=600
-StandardOutput=journal
-StandardError=journal
@@ -1,14 +0,0 @@
-[Unit]
-Description=Archipelago container reconciliation (periodic)
-
-[Timer]
-# First run 10 minutes after boot, then every 6 hours
-OnBootSec=10min
-OnUnitActiveSec=6h
-# Jitter to avoid load spikes
-RandomizedDelaySec=300
-# Run missed checks on boot
-Persistent=true
-
-[Install]
-WantedBy=timers.target
@@ -0,0 +1,10 @@
+# Archipelago persistent log directory and files
+# Runtime log destination. Backend runs as `archipelago`, but /var/log/
+# is root-owned, so we pre-create the directory and log files with the
+# right ownership at boot / install-time.
+#
+# Logrotate (image-recipe/configs/logrotate.conf) rotates files in this
+# directory daily, keeping 30 compressed copies.
+
+d /var/log/archipelago 0755 archipelago archipelago - -
+f /var/log/archipelago/container-installs.log 0644 archipelago archipelago - -
@@ -48,6 +48,14 @@ MemoryMax=4G
 LimitNOFILE=65535
 TasksMax=2048

+# Delegate cgroup controllers so rootless podman (run from this system service
+# as user=archipelago, not user@1000.service) can create transient libpod-*.scope
+# units with --memory / --cpus / --pids-limit. Without this, podman create fails
+# at start time with: "MemoryMax is out of range" because systemd rejects resource
+# limits on undelegated cgroup subtrees. Required for the ProdContainerOrchestrator
+# code path (see core/archipelago/src/container/prod_orchestrator.rs).
+Delegate=memory pids cpu io
+
 # Logging
 StandardOutput=journal
 StandardError=journal
@@ -241,6 +241,23 @@ server {
        error_page 504 = @backend_timeout;
    }

+    # App Store catalog proxy — backend fetches from configured registries
+    # so the browser doesn't hit CORS/CSP. Without this block nginx falls
+    # through to the SPA index.html and the frontend gets HTML back instead
+    # of JSON.
+    location /api/app-catalog {
+        proxy_pass http://127.0.0.1:5678;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header Cookie $http_cookie;
+        proxy_connect_timeout 15s;
+        proxy_read_timeout 30s;
+        proxy_send_timeout 15s;
+        error_page 502 503 = @backend_unavailable;
+        error_page 504 = @backend_timeout;
+    }
+
    # DWN endpoints — peer access over Tor (no auth)
    location /dwn {
        limit_req zone=peer burst=20 nodelay;
@@ -1029,6 +1046,23 @@ server {
        error_page 504 = @backend_timeout;
    }

+    # App Store catalog proxy — backend fetches from configured registries
+    # so the browser doesn't hit CORS/CSP. Without this block nginx falls
+    # through to the SPA index.html and the frontend gets HTML back instead
+    # of JSON.
+    location /api/app-catalog {
+        proxy_pass http://127.0.0.1:5678;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header Cookie $http_cookie;
+        proxy_connect_timeout 15s;
+        proxy_read_timeout 30s;
+        proxy_send_timeout 15s;
+        error_page 502 503 = @backend_unavailable;
+        error_page 504 = @backend_timeout;
+    }
+
    # DWN endpoints — peer access over Tor (no auth)
    location /dwn {
        limit_req zone=peer burst=20 nodelay;
@@ -1,12 +1,12 @@
 {
  "name": "neode-ui",
-  "version": "1.6.0-alpha",
+  "version": "1.7.38-alpha",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "neode-ui",
-      "version": "1.6.0-alpha",
+      "version": "1.7.38-alpha",
      "dependencies": {
        "@types/dompurify": "^3.0.5",
        "@vue-leaflet/vue-leaflet": "^0.10.1",
@@ -1,7 +1,7 @@
 {
  "name": "neode-ui",
  "private": true,
-  "version": "1.6.0-alpha",
+  "version": "1.7.43-alpha",
  "type": "module",
  "scripts": {
    "start": "./start-dev.sh",
@@ -14,6 +14,7 @@
    "dev:real": "echo 'Start backend: cd ../core && cargo run --release' && vite",
    "backend:mock": "node mock-backend.js",
    "backend:real": "cd ../core && cargo run --release",
+    "prebuild": "cp ../app-catalog/catalog.json public/catalog.json",
    "build": "vue-tsc -b && vite build",
    "build:docker": "vite build",
    "build:production": "NODE_ENV=production vue-tsc -b && vite build --mode production",
@@ -1,4 +0,0 @@
-<svg width="64" height="64" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg">
-  <rect width="64" height="64" rx="12" fill="#10b981"/>
-  <text x="32" y="38" text-anchor="middle" font-family="system-ui" font-size="16" font-weight="700" fill="white">FIPS</text>
-</svg>
@@ -1,11 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" fill="none">
-  <rect width="100" height="100" rx="20" fill="#7B2DBC"/>
-  <circle cx="50" cy="40" r="12" stroke="white" stroke-width="3" fill="none"/>
-  <circle cx="28" cy="68" r="8" stroke="white" stroke-width="2.5" fill="none"/>
-  <circle cx="72" cy="68" r="8" stroke="white" stroke-width="2.5" fill="none"/>
-  <line x1="42" y1="49" x2="33" y2="62" stroke="white" stroke-width="2.5" stroke-linecap="round"/>
-  <line x1="58" y1="49" x2="67" y2="62" stroke="white" stroke-width="2.5" stroke-linecap="round"/>
-  <circle cx="50" cy="40" r="4" fill="white"/>
-  <circle cx="28" cy="68" r="3" fill="white"/>
-  <circle cx="72" cy="68" r="3" fill="white"/>
-</svg>
@@ -1,4 +0,0 @@
-<svg width="64" height="64" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg">
-  <rect width="64" height="64" rx="12" fill="#6366f1"/>
-  <text x="32" y="38" text-anchor="middle" font-family="system-ui" font-size="18" font-weight="700" fill="white">NV</text>
-</svg>
@@ -1,4 +0,0 @@
-<svg width="64" height="64" viewBox="0 0 64 64" fill="none" xmlns="http://www.w3.org/2000/svg">
-  <rect width="64" height="64" rx="12" fill="#f59e0b"/>
-  <text x="32" y="38" text-anchor="middle" font-family="system-ui" font-size="18" font-weight="700" fill="white">R</text>
-</svg>
@@ -1,415 +1,210 @@
 {
-  "version": 1,
-  "updated": "2026-04-11T00:00:00Z",
-  "registry": "23.182.128.160:3000/lfg2025",
+  "version": 2,
+  "updated": "2026-04-22T00:00:00Z",
+  "registry": "git.tx1138.com/lfg2025",
  "featured": {
    "id": "indeedhub",
    "banner": "/assets/img/featured/indeedhub-banner.jpg",
    "headline": "Stream Sovereignty",
-    "description": "Bitcoin documentaries with Nostr identity. God Bless Bitcoin, The Bitcoin Psyop, and more \u2014 streaming from your own node.",
+    "description": "Bitcoin documentaries with Nostr identity.",
    "tag": "NOSTR IDENTITY // YOUR NODE"
  },
  "apps": [
    {
-      "id": "bitcoin-knots",
-      "title": "Bitcoin Knots",
-      "version": "28.1.0",
-      "description": "Run a full Bitcoin node. Validate and relay blocks and transactions on the Bitcoin network.",
+      "id": "bitcoin-knots", "title": "Bitcoin Knots", "version": "28.1.0",
+      "description": "Run a full Bitcoin node. Validate and relay blocks and transactions.",
      "icon": "/assets/img/app-icons/bitcoin-knots.webp",
-      "author": "Bitcoin Knots",
-      "dockerImage": "bitcoin-knots:latest",
-      "repoUrl": "https://github.com/bitcoinknots/bitcoin",
-      "category": "money",
-      "tier": "core"
+      "author": "Bitcoin Knots", "category": "money", "tier": "core",
+      "dockerImage": "git.tx1138.com/lfg2025/bitcoin-knots:latest",
+      "repoUrl": "https://github.com/bitcoinknots/bitcoin"
    },
    {
-      "id": "lnd",
-      "title": "LND",
-      "version": "0.18.4",
-      "description": "Lightning Network Daemon. Fast and cheap Bitcoin payments through the Lightning Network.",
+      "id": "bitcoin-core", "title": "Bitcoin Core", "version": "28.4",
+      "description": "Reference implementation of the Bitcoin protocol. Run a full node validating and relaying blocks.",
+      "icon": "/assets/img/app-icons/bitcoin-core.svg",
+      "author": "Bitcoin Core contributors", "category": "money", "tier": "optional",
+      "dockerImage": "docker.io/bitcoin/bitcoin:28.4",
+      "repoUrl": "https://github.com/bitcoin/bitcoin"
+    },
+    {
+      "id": "lnd", "title": "LND", "version": "0.18.4",
+      "description": "Lightning Network Daemon. Fast Bitcoin payments through Lightning.",
      "icon": "/assets/img/app-icons/lnd.svg",
-      "author": "Lightning Labs",
-      "dockerImage": "lnd:v0.18.4-beta",
+      "author": "Lightning Labs", "category": "money", "tier": "core",
+      "dockerImage": "git.tx1138.com/lfg2025/lnd:v0.18.4-beta",
      "repoUrl": "https://github.com/lightningnetwork/lnd",
-      "category": "money",
-      "tier": "core"
+      "requires": ["bitcoin-knots"]
    },
    {
-      "id": "btcpay-server",
-      "title": "BTCPay Server",
-      "version": "1.13.7",
-      "description": "Self-hosted Bitcoin payment processor. Accept Bitcoin payments without intermediaries or fees.",
+      "id": "btcpay-server", "title": "BTCPay Server", "version": "1.13.7",
+      "description": "Self-hosted Bitcoin payment processor.",
      "icon": "/assets/img/app-icons/btcpay-server.png",
-      "author": "BTCPay Server Foundation",
-      "dockerImage": "btcpayserver:1.13.7",
+      "author": "BTCPay Server Foundation", "category": "commerce", "tier": "core",
+      "dockerImage": "git.tx1138.com/lfg2025/btcpayserver:1.13.7",
      "repoUrl": "https://github.com/btcpayserver/btcpayserver",
-      "category": "commerce",
-      "tier": "core"
+      "requires": ["bitcoin-knots"]
    },
    {
-      "id": "mempool",
-      "title": "Mempool Explorer",
-      "version": "3.0.0",
-      "description": "Self-hosted Bitcoin blockchain and mempool visualizer. Monitor transactions without revealing your addresses.",
+      "id": "mempool", "title": "Mempool Explorer", "version": "3.0.0",
+      "description": "Self-hosted Bitcoin blockchain and mempool visualizer.",
      "icon": "/assets/img/app-icons/mempool.webp",
-      "author": "Mempool",
-      "dockerImage": "mempool-frontend:v3.0.0",
+      "author": "Mempool", "category": "money", "tier": "core",
+      "dockerImage": "git.tx1138.com/lfg2025/mempool-frontend:v3.0.0",
      "repoUrl": "https://github.com/mempool/mempool",
-      "category": "money",
-      "tier": "core"
+      "requires": ["bitcoin-knots", "electrumx"]
    },
    {
-      "id": "electrumx",
-      "title": "ElectrumX",
-      "version": "1.18.0",
-      "description": "Electrum protocol server. Index the blockchain for fast wallet lookups, privately.",
+      "id": "electrumx", "title": "ElectrumX", "version": "1.18.0",
+      "description": "Electrum protocol server. Index the blockchain for fast wallet lookups.",
      "icon": "/assets/img/app-icons/electrumx.webp",
-      "author": "Luke Childs",
-      "dockerImage": "electrumx:v1.18.0",
+      "author": "Luke Childs", "category": "money", "tier": "core",
+      "dockerImage": "git.tx1138.com/lfg2025/electrumx:v1.18.0",
      "repoUrl": "https://github.com/spesmilo/electrumx",
-      "category": "money",
-      "tier": "core"
+      "requires": ["bitcoin-knots"]
    },
    {
-      "id": "indeedhub",
-      "title": "IndeeHub",
-      "version": "1.0.0",
-      "description": "Bitcoin documentary streaming with Nostr identity. Stream sovereignty content from your node.",
+      "id": "indeedhub", "title": "IndeeHub", "version": "1.0.0",
+      "description": "Bitcoin documentary streaming with Nostr identity.",
      "icon": "/assets/img/app-icons/indeedhub.png",
-      "author": "IndeeHub Team",
-      "dockerImage": "indeedhub:1.0.0",
-      "repoUrl": "https://github.com/indeedhub/indeedhub",
-      "category": "community"
+      "author": "IndeeHub", "category": "community",
+      "dockerImage": "git.tx1138.com/lfg2025/indeedhub:1.0.0",
+      "repoUrl": "https://github.com/indeedhub/indeedhub"
    },
    {
-      "id": "botfights",
-      "title": "BotFights",
-      "version": "1.0.0",
-      "description": "Bot arena + 2-player arcade fighter with controller support.",
+      "id": "botfights", "title": "BotFights", "version": "1.1.0",
+      "description": "Bot arena + 2-player arcade fighter with controller support and Adventure Mode.",
      "icon": "/assets/img/app-icons/botfights.svg",
-      "author": "BotFights",
-      "dockerImage": "botfights:1.1.0",
-      "repoUrl": "https://botfights.net",
-      "category": "community"
+      "author": "BotFights", "category": "community",
+      "dockerImage": "git.tx1138.com/lfg2025/botfights:1.1.0",
+      "repoUrl": "https://botfights.net"
    },
    {
-      "id": "gitea",
-      "title": "Gitea",
-      "version": "1.23",
-      "description": "Self-hosted Git service with container registry, CI/CD, issue tracking, and package hosting.",
+      "id": "gitea", "title": "Gitea", "version": "1.23",
+      "description": "Self-hosted Git service with container registry, CI/CD, issue tracking.",
      "icon": "/assets/img/app-icons/gitea.svg",
-      "author": "Gitea",
+      "author": "Gitea", "category": "development",
      "dockerImage": "docker.io/gitea/gitea:1.23",
-      "repoUrl": "https://gitea.com",
-      "category": "development"
+      "repoUrl": "https://gitea.com"
    },
    {
-      "id": "filebrowser",
-      "title": "File Browser",
-      "version": "2.27.0",
-      "description": "Web-based file manager. Browse, upload, and manage files on your server.",
+      "id": "filebrowser", "title": "File Browser", "version": "2.27.0",
+      "description": "Web-based file manager.",
      "icon": "/assets/img/app-icons/file-browser.webp",
-      "author": "File Browser",
-      "dockerImage": "filebrowser:v2.27.0",
-      "repoUrl": "https://github.com/filebrowser/filebrowser",
-      "category": "data",
-      "tier": "core"
+      "author": "File Browser", "category": "data", "tier": "core",
+      "dockerImage": "git.tx1138.com/lfg2025/filebrowser:v2.27.0",
+      "repoUrl": "https://github.com/filebrowser/filebrowser"
    },
    {
-      "id": "vaultwarden",
-      "title": "Vaultwarden",
-      "version": "1.30.0",
-      "description": "Self-hosted password vault. Bitwarden-compatible with zero-knowledge encryption.",
+      "id": "vaultwarden", "title": "Vaultwarden", "version": "1.30.0",
+      "description": "Self-hosted password vault with zero-knowledge encryption.",
      "icon": "/assets/img/app-icons/vaultwarden.webp",
-      "author": "Vaultwarden",
-      "dockerImage": "vaultwarden:1.30.0-alpine",
-      "repoUrl": "https://github.com/dani-garcia/vaultwarden",
-      "category": "data",
-      "tier": "recommended"
+      "author": "Vaultwarden", "category": "data", "tier": "recommended",
+      "dockerImage": "git.tx1138.com/lfg2025/vaultwarden:1.30.0-alpine",
+      "repoUrl": "https://github.com/dani-garcia/vaultwarden"
    },
    {
-      "id": "searxng",
-      "title": "SearXNG",
-      "version": "2024.1.0",
-      "description": "Privacy-respecting metasearch engine. Search the internet without being tracked.",
+      "id": "searxng", "title": "SearXNG", "version": "2024.1.0",
+      "description": "Privacy-respecting metasearch engine.",
      "icon": "/assets/img/app-icons/searxng.png",
-      "author": "SearXNG",
-      "dockerImage": "searxng:latest",
-      "repoUrl": "https://github.com/searxng/searxng",
-      "category": "data",
-      "tier": "recommended"
+      "author": "SearXNG", "category": "data", "tier": "recommended",
+      "dockerImage": "git.tx1138.com/lfg2025/searxng:latest",
+      "repoUrl": "https://github.com/searxng/searxng"
    },
    {
-      "id": "nostr-rs-relay",
-      "title": "Nostr Relay",
-      "version": "0.9.0",
-      "description": "Your own Nostr relay. Store events locally, relay for friends, publish over Tor.",
-      "icon": "/assets/img/app-icons/nostr-rs-relay.svg",
-      "author": "scsiblade",
-      "dockerImage": "nostr-rs-relay:0.9.0",
-      "repoUrl": "https://sr.ht/~gheartsfield/nostr-rs-relay/",
-      "category": "nostr"
-    },
-    {
-      "id": "fedimint",
-      "title": "Fedimint",
-      "version": "0.10.0",
-      "description": "Federated Bitcoin mint. Private, scalable Bitcoin through federated guardians.",
+      "id": "fedimint", "title": "Fedimint", "version": "0.10.0",
+      "description": "Federated Bitcoin mint with privacy through federated guardians.",
      "icon": "/assets/img/app-icons/fedimint.png",
-      "author": "Fedimint",
-      "dockerImage": "fedimintd:v0.10.0",
-      "repoUrl": "https://github.com/fedimint/fedimint",
-      "category": "money"
+      "author": "Fedimint", "category": "money",
+      "dockerImage": "git.tx1138.com/lfg2025/fedimintd:v0.10.0",
+      "repoUrl": "https://github.com/fedimint/fedimint"
    },
    {
-      "id": "ollama",
-      "title": "Ollama",
-      "version": "0.5.4",
-      "description": "Run AI models locally. Llama, Mistral, and more \u2014 on your hardware, completely private.",
+      "id": "ollama", "title": "Ollama", "version": "0.5.4",
+      "description": "Run AI models locally. Private and on your hardware.",
      "icon": "/assets/img/app-icons/ollama.png",
-      "author": "Ollama",
-      "dockerImage": "ollama:latest",
-      "repoUrl": "https://github.com/ollama/ollama",
-      "category": "data"
+      "author": "Ollama", "category": "data",
+      "dockerImage": "git.tx1138.com/lfg2025/ollama:latest",
+      "repoUrl": "https://github.com/ollama/ollama"
    },
    {
-      "id": "nextcloud",
-      "title": "Nextcloud",
-      "version": "28",
-      "description": "Your own private cloud. File sync, calendars, contacts \u2014 all on your hardware.",
+      "id": "nextcloud", "title": "Nextcloud", "version": "28",
+      "description": "Your own private cloud. File sync, calendars, contacts.",
      "icon": "/assets/img/app-icons/nextcloud.webp",
-      "author": "Nextcloud",
-      "dockerImage": "nextcloud:28",
-      "repoUrl": "https://github.com/nextcloud/server",
-      "category": "data"
+      "author": "Nextcloud", "category": "data",
+      "dockerImage": "git.tx1138.com/lfg2025/nextcloud:28",
+      "repoUrl": "https://github.com/nextcloud/server"
    },
    {
-      "id": "jellyfin",
-      "title": "Jellyfin",
-      "version": "10.8.13",
-      "description": "Free media server. Stream your movies, music, and photos to any device.",
+      "id": "jellyfin", "title": "Jellyfin", "version": "10.8.13",
+      "description": "Free media server. Stream movies, music, and photos.",
      "icon": "/assets/img/app-icons/jellyfin.webp",
-      "author": "Jellyfin",
-      "dockerImage": "jellyfin:10.8.13",
-      "repoUrl": "https://github.com/jellyfin/jellyfin",
-      "category": "data"
+      "author": "Jellyfin", "category": "data",
+      "dockerImage": "git.tx1138.com/lfg2025/jellyfin:10.8.13",
+      "repoUrl": "https://github.com/jellyfin/jellyfin"
    },
    {
-      "id": "immich",
-      "title": "Immich",
-      "version": "1.90.0",
-      "description": "High-performance photo and video backup. Mobile-first with ML features.",
+      "id": "immich", "title": "Immich", "version": "1.90.0",
+      "description": "High-performance photo and video backup with ML.",
      "icon": "/assets/img/app-icons/immich.png",
-      "author": "Immich",
-      "dockerImage": "immich-server:release",
-      "repoUrl": "https://github.com/immich-app/immich",
-      "category": "data"
+      "author": "Immich", "category": "data",
+      "dockerImage": "git.tx1138.com/lfg2025/immich-server:release",
+      "repoUrl": "https://github.com/immich-app/immich"
    },
    {
-      "id": "homeassistant",
-      "title": "Home Assistant",
-      "version": "2024.1",
-      "description": "Open-source home automation. Control smart home devices privately.",
+      "id": "homeassistant", "title": "Home Assistant", "version": "2024.1",
+      "description": "Open-source home automation.",
      "icon": "/assets/img/app-icons/homeassistant.png",
-      "author": "Home Assistant",
-      "dockerImage": "home-assistant:2024.1",
-      "repoUrl": "https://github.com/home-assistant/core",
-      "category": "home"
+      "author": "Home Assistant", "category": "home",
+      "dockerImage": "git.tx1138.com/lfg2025/home-assistant:2024.1",
+      "repoUrl": "https://github.com/home-assistant/core"
    },
    {
-      "id": "grafana",
-      "title": "Grafana",
-      "version": "10.2.0",
-      "description": "Analytics and monitoring platform. Dashboards for your node metrics.",
+      "id": "grafana", "title": "Grafana", "version": "10.2.0",
+      "description": "Analytics and monitoring dashboards.",
      "icon": "/assets/img/app-icons/grafana.png",
-      "author": "Grafana Labs",
-      "dockerImage": "grafana:10.2.0",
-      "repoUrl": "https://github.com/grafana/grafana",
-      "category": "data",
-      "tier": "recommended"
+      "author": "Grafana Labs", "category": "data", "tier": "recommended",
+      "dockerImage": "git.tx1138.com/lfg2025/grafana:10.2.0",
+      "repoUrl": "https://github.com/grafana/grafana"
    },
    {
-      "id": "tailscale",
-      "title": "Tailscale",
-      "version": "1.78.0",
-      "description": "Zero-config VPN. Secure remote access with WireGuard mesh networking.",
+      "id": "tailscale", "title": "Tailscale", "version": "1.78.0",
+      "description": "Zero-config VPN with WireGuard mesh networking.",
      "icon": "/assets/img/app-icons/tailscale.webp",
-      "author": "Tailscale",
-      "dockerImage": "tailscale:stable",
-      "repoUrl": "https://github.com/tailscale/tailscale",
-      "category": "networking",
-      "tier": "recommended"
+      "author": "Tailscale", "category": "networking", "tier": "recommended",
+      "dockerImage": "git.tx1138.com/lfg2025/tailscale:stable",
+      "repoUrl": "https://github.com/tailscale/tailscale"
    },
    {
-      "id": "penpot",
-      "title": "Penpot",
-      "version": "2.4",
-      "description": "Open-source design platform. Self-hosted alternative to Figma.",
-      "icon": "/assets/img/app-icons/penpot.webp",
-      "author": "Penpot",
-      "dockerImage": "penpot-frontend:2.4",
-      "repoUrl": "https://github.com/penpot/penpot",
-      "category": "data"
-    },
-    {
-      "id": "photoprism",
-      "title": "PhotoPrism",
-      "version": "240915",
-      "description": "AI-powered photo management with facial recognition, privately.",
-      "icon": "/assets/img/app-icons/photoprism.svg",
-      "author": "PhotoPrism",
-      "dockerImage": "photoprism:240915",
-      "repoUrl": "https://github.com/photoprism/photoprism",
-      "category": "data"
-    },
-    {
-      "id": "uptime-kuma",
-      "title": "Uptime Kuma",
-      "version": "1.23.0",
-      "description": "Self-hosted uptime monitoring. Track HTTP, TCP, DNS, and more.",
+      "id": "uptime-kuma", "title": "Uptime Kuma", "version": "1.23.0",
+      "description": "Self-hosted uptime monitoring.",
      "icon": "/assets/img/app-icons/uptime-kuma.webp",
-      "author": "Uptime Kuma",
-      "dockerImage": "uptime-kuma:1",
-      "repoUrl": "https://github.com/louislam/uptime-kuma",
-      "category": "data",
-      "tier": "recommended"
+      "author": "Uptime Kuma", "category": "data", "tier": "recommended",
+      "dockerImage": "git.tx1138.com/lfg2025/uptime-kuma:1",
+      "repoUrl": "https://github.com/louislam/uptime-kuma"
    },
    {
-      "id": "nostr-vpn",
-      "title": "Nostr VPN",
-      "version": "0.3.7",
-      "description": "Tailscale-style mesh VPN with Nostr control plane.",
-      "icon": "/assets/img/app-icons/nostr-vpn.svg",
-      "author": "Martti Malmi",
-      "dockerImage": "nostr-vpn:v0.3.7",
-      "repoUrl": "https://github.com/mmalmi/nostr-vpn",
-      "category": "networking"
-    },
-    {
-      "id": "fips",
-      "title": "FIPS",
-      "version": "0.1.0",
-      "description": "Free Internetworking Peering System. Self-organizing encrypted mesh.",
-      "icon": "/assets/img/app-icons/fips.svg",
-      "author": "Jim Corgan",
-      "dockerImage": "fips:v0.1.0",
-      "repoUrl": "https://github.com/jmcorgan/fips",
-      "category": "networking"
-    },
-    {
-      "id": "routstr",
-      "title": "Routstr",
-      "version": "0.4.3",
-      "description": "Decentralized AI inference proxy. Pay-per-request with Cashu ecash.",
-      "icon": "/assets/img/app-icons/routstr.svg",
-      "author": "Routstr",
-      "dockerImage": "routstr:v0.4.3",
-      "repoUrl": "https://github.com/routstr/routstr-core",
-      "category": "community"
-    },
-    {
-      "id": "dwn",
-      "title": "Decentralized Web Node",
-      "version": "0.4.0",
-      "description": "Own your data with DID-based access control. Sync across devices.",
+      "id": "dwn", "title": "Decentralized Web Node", "version": "0.4.0",
+      "description": "Own your data with DID-based access control.",
      "icon": "/assets/img/app-icons/dwn.svg",
-      "author": "TBD",
-      "dockerImage": "dwn-server:main",
-      "repoUrl": "https://github.com/TBD54566975/dwn-server",
-      "category": "data"
+      "author": "TBD", "category": "data",
+      "dockerImage": "git.tx1138.com/lfg2025/dwn-server:main",
+      "repoUrl": "https://github.com/TBD54566975/dwn-server"
    },
    {
-      "id": "cryptpad",
-      "title": "CryptPad",
-      "version": "2024.12.0",
-      "description": "End-to-end encrypted documents and collaboration. Zero-knowledge.",
-      "icon": "/assets/img/app-icons/cryptpad.webp",
-      "author": "XWiki SAS",
-      "dockerImage": "cryptpad:2024.12.0",
-      "repoUrl": "https://github.com/cryptpad/cryptpad",
-      "category": "data"
+      "id": "endurain", "title": "Endurain", "version": "0.8.0",
+      "description": "Self-hosted fitness tracking. Strava alternative.",
+      "icon": "/assets/img/app-icons/endurain.png",
+      "author": "Endurain", "category": "data",
+      "dockerImage": "git.tx1138.com/lfg2025/endurain:0.8.0",
+      "repoUrl": "https://github.com/joaovitoriasilva/endurain"
    },
    {
-      "id": "nostrudel",
-      "title": "noStrudel",
-      "version": "0.40.0",
-      "description": "Feature-rich Nostr web client.",
-      "icon": "/assets/img/app-icons/nostrudel.svg",
-      "author": "hzrd149",
-      "dockerImage": "",
-      "repoUrl": "https://github.com/hzrd149/nostrudel",
-      "webUrl": "https://nostrudel.ninja",
-      "category": "nostr"
-    },
-    {
-      "id": "nwnn",
-      "title": "Next Web News Network",
-      "version": "1.0.0",
-      "description": "Decentralized news aggregator.",
-      "icon": "/assets/img/app-icons/nwnn.png",
-      "author": "L484",
-      "dockerImage": "",
-      "webUrl": "https://nwnn.l484.com",
-      "category": "l484"
-    },
-    {
-      "id": "484-kitchen",
-      "title": "484 Kitchen",
-      "version": "1.0.0",
-      "description": "K484 application platform.",
-      "icon": "/assets/img/app-icons/484-kitchen.png",
-      "author": "L484",
-      "dockerImage": "",
-      "webUrl": "https://484.kitchen",
-      "category": "l484"
-    },
-    {
-      "id": "call-the-operator",
-      "title": "Call the Operator",
-      "version": "1.0.0",
-      "description": "Escape the Matrix.",
-      "icon": "/assets/img/app-icons/call-the-operator.png",
-      "author": "TX1138",
-      "dockerImage": "",
-      "webUrl": "https://cta.tx1138.com",
-      "category": "l484"
-    },
-    {
-      "id": "arch-presentation",
-      "title": "Arch Presentation",
-      "version": "1.0.0",
-      "description": "The Future of Decentralized Infrastructure.",
-      "icon": "/assets/img/app-icons/arch-presentation.png",
-      "author": "L484",
-      "dockerImage": "",
-      "webUrl": "https://present.l484.com",
-      "category": "l484"
-    },
-    {
-      "id": "syntropy-institute",
-      "title": "Syntropy Institute",
-      "version": "1.0.0",
-      "description": "Medicine Reimagined.",
-      "icon": "/assets/img/app-icons/syntropy-institute.png",
-      "author": "Syntropy Institute",
-      "dockerImage": "",
-      "webUrl": "https://syntropy.institute",
-      "category": "l484"
-    },
-    {
-      "id": "t-zero",
-      "title": "T-0",
-      "version": "1.0.0",
-      "description": "Documentary series exploring decentralization.",
-      "icon": "/assets/img/app-icons/t-zero.png",
-      "author": "T-0",
-      "dockerImage": "",
-      "webUrl": "https://teeminuszero.net",
-      "category": "l484"
+      "id": "photoprism", "title": "PhotoPrism", "version": "240915",
+      "description": "AI-powered photo management with facial recognition.",
+      "icon": "/assets/img/app-icons/photoprism.svg",
+      "author": "PhotoPrism", "category": "data",
+      "dockerImage": "git.tx1138.com/lfg2025/photoprism:240915",
+      "repoUrl": "https://github.com/photoprism/photoprism"
    }
-  ],
-  "registries": [
-    "23.182.128.160:3000/lfg2025",
-    "git.tx1138.com/lfg2025"
  ]
-}
+}
@@ -284,12 +284,29 @@ async function handleSplashComplete() {
  }

  try {
-    const { isOnboardingComplete } = await import('@/composables/useOnboarding')
-    const seenOnboarding = await isOnboardingComplete()
-    const destination = seenOnboarding ? '/login' : '/onboarding/intro'
-    router.push(destination).catch(() => {})
+    const { checkOnboardingStatus } = await import('@/composables/useOnboarding')
+    const seenOnboarding = await checkOnboardingStatus()
+    if (seenOnboarding === true) {
+      router.push('/login').catch(() => {})
+      return
+    }
+    if (seenOnboarding === false) {
+      router.push('/onboarding/intro').catch(() => {})
+      return
+    }
+    // Backend unreachable after retries. Prefer the localStorage
+    // cache on THIS browser (if a prior successful check set it) —
+    // otherwise defer to RootRedirect which polls + retries rather
+    // than forcing an already-onboarded user through the wizard.
+    if (localStorage.getItem('neode_onboarding_complete') === '1') {
+      router.push('/login').catch(() => {})
+    } else {
+      router.push('/').catch(() => {})
+    }
  } catch {
-    router.push('/onboarding/intro').catch(() => {})
+    // Do NOT default to /onboarding/intro here. RootRedirect has retry
+    // + polling + boot-screen handling; let it decide.
+    router.push('/').catch(() => {})
  }
 }
 </script>
@@ -6,7 +6,20 @@ import { rpcClient } from './rpc-client'
 export interface ContainerStatus {
  id: string
  name: string
-  state: 'created' | 'running' | 'stopped' | 'exited' | 'paused' | 'unknown'
+  state:
+    | 'created'
+    | 'running'
+    | 'stopped'
+    | 'exited'
+    | 'paused'
+    | 'unknown'
+    | 'stopping'
+    | 'starting'
+    | 'restarting'
+    | 'installing'
+    | 'updating'
+    | 'removing'
+    | 'installed'
  image: string
  created: string
  ports: string[]
@@ -60,6 +73,16 @@ export const containerClient = {
    })
  },

+  /**
+   * Restart a container (async; returns immediately with restarting state)
+   */
+  async restartContainer(appId: string): Promise<void> {
+    return rpcClient.call<void>({
+      method: 'container-restart',
+      params: { app_id: appId },
+    })
+  },
+
  /**
   * Remove a container
   */
@@ -521,23 +521,30 @@ class RPCClient {
    })
  }

-  async installPackage(id: string, marketplaceUrl: string, version: string): Promise<string> {
+  async installPackage(
+    id: string,
+    marketplaceUrl: string,
+    version: string,
+  ): Promise<{ status: string; package_id: string }> {
+    // Backend is async — returns { status: 'installing' } in <1s after
+    // flipping state and spawning the pull/install pipeline. Progress is
+    // streamed via WebSocket (install_progress field on the package entry).
    return this.call({
      method: 'package.install',
      params: { id, 'marketplace-url': marketplaceUrl, version },
-      // 45 min — IndeedHub is 6 images and gitea raw-file throughput is
-      // ~70 KB/s per image; 15 min was short enough to kill the install
-      // mid-pull and land the user on a "didn't work" screen while the
-      // backend kept working in the background.
-      timeout: 2700000,
+      timeout: 15000,
    })
  }

-  async uninstallPackage(id: string): Promise<void> {
+  async uninstallPackage(id: string): Promise<{ status: string; package_id: string }> {
+    // Backend is async — returns { status: 'removing' } immediately after
+    // flipping state. Graceful stop (up to 600s for bitcoin) and data wipe
+    // (up to minutes for large chainstate) run in a background task.
+    // Progress shown via uninstall_stage field on the package entry.
    return this.call({
      method: 'package.uninstall',
      params: { id },
-      timeout: 660000, // Bitcoin Knots needs up to 600s for UTXO flush
+      timeout: 15000,
    })
  }

@@ -545,7 +552,7 @@ class RPCClient {
    return this.call({
      method: 'package.start',
      params: { id },
-      timeout: 60000,
+      timeout: 15000,
    })
  }

@@ -553,7 +560,7 @@ class RPCClient {
    return this.call({
      method: 'package.stop',
      params: { id },
-      timeout: 120000,
+      timeout: 15000,
    })
  }

@@ -561,15 +568,18 @@ class RPCClient {
    return this.call({
      method: 'package.restart',
      params: { id },
-      timeout: 120000,
+      timeout: 15000,
    })
  }

-  async updatePackage(id: string): Promise<{ status: string }> {
+  async updatePackage(id: string): Promise<{ status: string; package_id: string }> {
+    // Backend is async — returns { status: 'updating' } immediately after
+    // flipping state. Pull / stop / recreate / verify runs in background,
+    // with rollback-on-failure.
    return this.call({
      method: 'package.update',
      params: { id },
-      timeout: 660000, // Bitcoin Knots needs up to 600s for graceful shutdown
+      timeout: 15000,
    })
  }

@@ -33,7 +33,20 @@
 import { computed } from 'vue'

 interface Props {
-  state: 'created' | 'running' | 'stopped' | 'exited' | 'paused' | 'unknown'
+  state:
+    | 'created'
+    | 'running'
+    | 'stopped'
+    | 'exited'
+    | 'paused'
+    | 'unknown'
+    | 'stopping'
+    | 'starting'
+    | 'restarting'
+    | 'installing'
+    | 'updating'
+    | 'removing'
+    | 'installed'
  health?: 'healthy' | 'unhealthy' | 'unknown' | 'starting'
 }

@@ -49,8 +62,15 @@ const statusClass = computed(() => {
      return 'bg-green-400'
    case 'stopped':
    case 'exited':
+    case 'installed':
      return 'bg-gray-400'
    case 'paused':
+    case 'starting':
+    case 'stopping':
+    case 'restarting':
+    case 'installing':
+    case 'updating':
+    case 'removing':
      return 'bg-yellow-400'
    default:
      return 'bg-red-400'
@@ -63,8 +83,15 @@ const textClass = computed(() => {
      return 'text-green-400'
    case 'stopped':
    case 'exited':
+    case 'installed':
      return 'text-gray-400'
    case 'paused':
+    case 'starting':
+    case 'stopping':
+    case 'restarting':
+    case 'installing':
+    case 'updating':
+    case 'removing':
      return 'text-yellow-400'
    default:
      return 'text-red-400'
@@ -83,6 +110,20 @@ const statusText = computed(() => {
      return 'Paused'
    case 'created':
      return 'Created'
+    case 'installed':
+      return 'Installed'
+    case 'starting':
+      return 'Starting…'
+    case 'stopping':
+      return 'Stopping…'
+    case 'restarting':
+      return 'Restarting…'
+    case 'installing':
+      return 'Installing…'
+    case 'updating':
+      return 'Updating…'
+    case 'removing':
+      return 'Removing…'
    default:
      return 'Unknown'
  }
@@ -73,7 +73,6 @@ const APP_ICON_MAP: Record<string, string> = {
  fedimint: '/assets/img/app-icons/fedimint.png',
  mempool: '/assets/img/app-icons/mempool.webp',
  electrs: '/assets/img/app-icons/electrs.svg',
-  'nostr-rs-relay': '/assets/img/app-icons/nostr-rs-relay.svg',
 }

 function goalAppIcons(goal: GoalDefinition): { appId: string; url: string }[] {
@@ -1,7 +1,28 @@
 /**
 * Login screen audio: intro loop (MP3) + transition sounds.
+ *
+ * First-install vs returning-user gate: the synthwave loop, welcome
+ * voice, pop/whoosh/oomph transitions exist for the first-boot cinematic
+ * moment. After the user has completed onboarding we silence all of
+ * them — every subsequent login should be quiet. Typing sounds are
+ * exempt and continue to play regardless.
 */

+/** True when the node has not yet completed onboarding — i.e. we're
+ *  still in the first-install cinematic. Reads the localStorage cache
+ *  set by useOnboarding (which is re-seeded from the backend on each
+ *  successful check), so this stays correct after a browser clear
+ *  once the onboarding-complete probe runs. Sound calls that fire
+ *  before that probe completes will fall through silent on an already-
+ *  onboarded node — which is exactly what we want. */
+function isFirstInstallPhase(): boolean {
+  try {
+    return localStorage.getItem('neode_onboarding_complete') !== '1'
+  } catch {
+    return true
+  }
+}
+
 let audioContext: AudioContext | null = null
 let introAudio: HTMLAudioElement | null = null
 let introGain: GainNode | null = null
@@ -30,6 +51,7 @@ const LOOP_START_URL = '/assets/audio/loop-start.mp3'
 /** Play loop-start when transitioning from typing intro to Welcome Noderunner, as the intro music comes in.
 * Uses Web Audio API so it plays after context is resumed (user gesture). */
 export function playLoopStart() {
+  if (!isFirstInstallPhase()) return
  const ctx = getContext()
  if (!ctx) return
  try {
@@ -62,6 +84,7 @@ export function resumeAudioContext() {

 /** Start intro loop - Cosmic Updrift. Only works after resumeAudioContext() (user gesture). */
 export function startSynthwave() {
+  if (!isFirstInstallPhase()) return
  const ctxOrNull = getContext()
  if (!ctxOrNull) return

@@ -123,6 +146,7 @@ export function stopAllAudio() {

 /** Pop sound - plays when intro initiator (tap to start) is pressed */
 export function playPop() {
+  if (!isFirstInstallPhase()) return
  const audio = new Audio('/assets/audio/pop.mp3')
  audio.volume = 0.6
  audio.play().catch(() => {})
@@ -130,6 +154,7 @@ export function playPop() {

 /** Whoosh transition on successful login */
 export function playLoginSuccessWhoosh() {
+  if (!isFirstInstallPhase()) return
  const woosh = new Audio('/assets/audio/woosh.mp3')
  woosh.volume = 0.5
  woosh.play().catch(() => {})
@@ -169,6 +194,7 @@ const WELCOME_SPEECH_URL = '/assets/audio/welcome-noderunner.mp3'
 *   ELEVENLABS_API_KEY=your_key node neode-ui/scripts/generate-welcome-speech.js
 * Browse sci-fi voices at elevenlabs.io/voice-library and set ELEVENLABS_VOICE_ID for custom voice. */
 export function playWelcomeNoderunnerSpeech() {
+  if (!isFirstInstallPhase()) return
  const audio = new Audio(WELCOME_SPEECH_URL)
  audio.volume = 0.9
  audio.play().catch(() => {})
@@ -226,6 +252,7 @@ export function playKeyboardTypingSound() {

 /** Gaming-style boot thud - soft impact when dashboard loads */
 export function playDashboardLoadOomph() {
+  if (!isFirstInstallPhase()) return
  const ctx = getContext()
  if (!ctx) return

@@ -1,29 +1,64 @@
 /**
- * Onboarding state - prefers backend, falls back to localStorage for mock/offline.
- * Hardened: retries on 502/503, never blocks completion.
+ * Onboarding state - backend is authoritative.
+ * "Unknown" (backend unreachable) must NEVER default to false —
+ * that would falsely send an already-onboarded user back through
+ * the intro after a browser clear / update / reboot.
 */
 import { rpcClient } from '@/api/rpc-client'

-async function callWithRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T | null> {
+async function callWithRetry<T>(fn: () => Promise<T>, maxRetries = 5): Promise<T | null> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (e) {
      const msg = e instanceof Error ? e.message : ''
-      const isRetryable = /502|503|timeout|fetch|network/i.test(msg)
+      const isRetryable = /502|503|504|timeout|fetch|network|abort/i.test(msg)
      if (!isRetryable || i === maxRetries - 1) return null
-      await new Promise((r) => setTimeout(r, 800 * (i + 1)))
+      // Exponential-ish backoff: 500, 1000, 2000, 4000, 8000 (capped)
+      const delay = Math.min(500 * Math.pow(2, i), 8000)
+      await new Promise((r) => setTimeout(r, delay))
    }
  }
  return null
 }

+/**
+ * Returns true/false if the backend gave a definitive answer, null if
+ * the backend is unreachable. Callers MUST handle null explicitly —
+ * do not coerce to boolean without thinking about the consequences.
+ */
+export async function checkOnboardingStatus(): Promise<boolean | null> {
+  const result = await callWithRetry(() => rpcClient.isOnboardingComplete(), 5)
+  if (result !== null) {
+    if (result) {
+      try { localStorage.setItem('neode_onboarding_complete', '1') } catch {}
+    } else {
+      try { localStorage.removeItem('neode_onboarding_complete') } catch {}
+    }
+  }
+  return result
+}
+
+/**
+ * Boolean-only variant for places that genuinely cannot wait.
+ * Backend answer wins; on backend-unreachable, trusts a prior
+ * localStorage cache (set by a past successful check on THIS node).
+ * Returns false only when both the backend and the cache agree —
+ * or when the cache is empty on a genuinely fresh install.
+ *
+ * Prefer checkOnboardingStatus() where possible so the caller can
+ * distinguish "confirmed fresh install" from "can't reach backend".
+ */
 export async function isOnboardingComplete(): Promise<boolean> {
-  // localStorage is set on completion and survives backend restarts/resets
-  if (localStorage.getItem('neode_onboarding_complete') === '1') return true
-  const result = await callWithRetry(() => rpcClient.isOnboardingComplete(), 2)
+  const result = await checkOnboardingStatus()
  if (result !== null) return result
-  return false
+  // Backend unreachable — trust the local cache. If the cache says
+  // we're onboarded, we almost certainly are (this browser saw a
+  // prior backend 'true' and re-seeded the flag). If the cache is
+  // empty, we genuinely don't know; returning false here is the
+  // last-resort fallback, and the calling views should additionally
+  // keep polling the backend instead of treating this as gospel.
+  return localStorage.getItem('neode_onboarding_complete') === '1'
 }

 export async function completeOnboarding(): Promise<void> {
@@ -19,6 +19,8 @@
    "launch": "Launch",
    "starting": "Starting...",
    "stopping": "Stopping...",
+    "update": "Update",
+    "updating": "Updating...",
    "send": "Send",
    "sending": "Sending...",
    "back": "Back",
@@ -19,6 +19,8 @@
    "launch": "Abrir",
    "starting": "Iniciando...",
    "stopping": "Deteniendo...",
+    "update": "Actualizar",
+    "updating": "Actualizando...",
    "send": "Enviar",
    "sending": "Enviando...",
    "back": "Volver",
@@ -193,6 +193,11 @@ const router = createRouter({
          name: 'system-update',
          component: () => import('../views/SystemUpdate.vue'),
        },
+        {
+          path: 'settings/registries',
+          name: 'app-registries',
+          component: () => import('../views/AppRegistries.vue'),
+        },
        {
          path: 'goals/:goalId',
          name: 'goal-detail',
@@ -306,18 +311,35 @@ router.beforeEach(async (to, _from, next) => {
      next()
      return
    }
-    // Check if this is a fresh install that needs onboarding
+    // Check if this is a fresh install that needs onboarding.
+    // Prefer checkOnboardingStatus() (tri-state) so we can distinguish
+    // "confirmed fresh install" from "backend unreachable". On the
+    // latter, send the user to RootRedirect (/) rather than the intro
+    // wizard — RootRedirect polls the backend and will route to
+    // /login once it answers, instead of forcing a re-onboarding.
    try {
-      const { isOnboardingComplete, getSavedOnboardingStep } = await import('@/composables/useOnboarding')
-      const setupDone = await isOnboardingComplete()
-      if (!setupDone) {
+      const { checkOnboardingStatus, getSavedOnboardingStep } = await import('@/composables/useOnboarding')
+      const setupDone = await checkOnboardingStatus()
+      if (setupDone === false) {
        const step = getSavedOnboardingStep()
        next(`/onboarding/${step}`)
        return
      }
+      if (setupDone === null) {
+        // Backend unreachable after retries — bounce through RootRedirect
+        // so it can keep polling and land the user on /login once the
+        // backend answers, instead of flashing the onboarding wizard.
+        const cached = localStorage.getItem('neode_onboarding_complete') === '1'
+        if (!cached) {
+          next('/')
+          return
+        }
+        // Cached as onboarded — continue to the /login path below.
+      }
    } catch {
-      // If we can't check, assume fresh install and show onboarding
-      next('/onboarding/intro')
+      // Unexpected error — do NOT default to onboarding. Hand off to
+      // RootRedirect which has retry + polling + boot-screen handling.
+      next('/')
      return
    }
    next({ path: '/login', query: { redirect: to.fullPath } })
@@ -10,10 +10,19 @@ describe('useLoginTransitionStore', () => {
  it('starts with all flags false', () => {
    const store = useLoginTransitionStore()
    expect(store.justLoggedIn).toBe(false)
+    expect(store.justCompletedOnboarding).toBe(false)
    expect(store.pendingWelcomeTyping).toBe(false)
    expect(store.startWelcomeTyping).toBe(false)
  })

+  it('setJustCompletedOnboarding updates justCompletedOnboarding', () => {
+    const store = useLoginTransitionStore()
+    store.setJustCompletedOnboarding(true)
+    expect(store.justCompletedOnboarding).toBe(true)
+    store.setJustCompletedOnboarding(false)
+    expect(store.justCompletedOnboarding).toBe(false)
+  })
+
  it('setJustLoggedIn updates justLoggedIn', () => {
    const store = useLoginTransitionStore()
    store.setJustLoggedIn(true)
--- a/Show More
+++ b/Show More