docs(openwrt): document the confirmed working end-to-end install flow

Adds a verification checklist (service running, nodogsplash bound to
br-tollgate not br-lan via the rendered config not just UCI, LAN/SSH
untouched, mint probes succeeding) plus notes on the dev-build test-mint
injection and the default-route race between a router's LAN interface
and the node's other uplinks before the router's own WAN/WISP is live.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0176RpCxFNS9ZaSJjL72W9Z5

core/openwrt/src/tollgate/install.rs

@@ -6,18 +6,53 @@ use crate::Router;
 /// The OpenWrt package name for the TollGate reference implementation.
 const TOLLGATE_PACKAGE: &str = "tollgate-module-basic-go";
 
-/// Direct-download fallback URLs by opkg architecture string.
+/// Pinned upstream release. Was stuck on v0.2.0 (Oct 2025) until 2026-09-05 —
+/// nine releases behind. v0.5.0's changelog covers exactly the failure modes
+/// hit live against archy-x250-pa3: a mint with an empty/broken keyset used
+/// to crash-loop the daemon forever ("graceful degradation when Cashu mints
+/// fail" in v0.5.0), and the bundled captive-portal build had no CBOR support
+/// at all, so it could only decode legacy `cashuA` tokens — rejecting the
+/// `cashuB` (NUT-00 V4) tokens modern wallets like Minibits generate by
+/// default ("portal improvements" in v0.5.0 include a JS bundle update that
+/// should carry a current cashu-ts with V4 support). Bump this string to move
+/// both this crate's URLs and the version baked into the source comments.
+const TOLLGATE_VERSION: &str = "v0.5.0";
+
+/// Direct-download fallback URLs by opkg architecture string, for the
+/// `.ipk` (ar-archive) package format.
 /// Used when the package is not in any configured feed.
-/// Source: https://github.com/OpenTollGate/tollgate-module-basic-go/releases/tag/v0.2.0
-fn ipk_url(arch: &str) -> Option<&'static str> {
-    match arch {
-        "mips_24kc"          => Some("https://github.com/OpenTollGate/tollgate-module-basic-go/releases/download/v0.2.0/mips_24kc.ipk"),
-        "mipsel_24kc"        => Some("https://github.com/OpenTollGate/tollgate-module-basic-go/releases/download/v0.2.0/mipsel_24kc.ipk"),
-        "aarch64_cortex-a53" => Some("https://github.com/OpenTollGate/tollgate-module-basic-go/releases/download/v0.2.0/aarch64_cortex-a53.ipk"),
-        "aarch64_cortex-a72" => Some("https://github.com/OpenTollGate/tollgate-module-basic-go/releases/download/v0.2.0/aarch64_cortex-a72.ipk"),
-        "arm_cortex-a7"      => Some("https://github.com/OpenTollGate/tollgate-module-basic-go/releases/download/v0.2.0/arm_cortex-a7.ipk"),
-        _ => None,
-    }
+/// Source: https://github.com/OpenTollGate/tollgate-module-basic-go/releases/tag/v0.5.0
+fn ipk_url(arch: &str) -> Option<String> {
+    let name = match arch {
+        "mips_24kc"          => "mips_24kc",
+        "mipsel_24kc"        => "mipsel_24kc",
+        "aarch64_cortex-a53" => "aarch64_cortex-a53",
+        "aarch64_cortex-a72" => "aarch64_cortex-a72",
+        "arm_cortex-a7"      => "arm_cortex-a7",
+        "x86_64"             => "x86_64",
+        _ => return None,
+    };
+    Some(format!(
+        "https://github.com/OpenTollGate/tollgate-module-basic-go/releases/download/{TOLLGATE_VERSION}/tollgate-wrt_{TOLLGATE_VERSION}_{name}.ipk"
+    ))
+}
+
+/// Direct-download URLs for the native Alpine-style `.apk` package format —
+/// only published for a subset of architectures as of v0.5.0. Where
+/// available this is strictly better than [`ipk_url`] on an apk-native
+/// (OpenWrt 25.x+) router: `apk add` installs it directly (dependency
+/// resolution, postinst, uci-defaults all handled by apk itself), instead of
+/// the manual `ar`/`tar` extraction dance `install_ipk` has to do to unpack
+/// an `.ipk` on a router with no `opkg`.
+fn apk_url(arch: &str) -> Option<String> {
+    let name = match arch {
+        "aarch64_cortex-a53" => "aarch64_cortex-a53",
+        "x86_64" => "x86_64",
+        _ => return None,
+    };
+    Some(format!(
+        "https://github.com/OpenTollGate/tollgate-module-basic-go/releases/download/{TOLLGATE_VERSION}/tollgate-wrt_{TOLLGATE_VERSION}_{name}.apk"
+    ))
 }
 
 /// Install tollgate-module-basic-go via opkg (OpenWrt ≤24.x).
@@ -103,6 +138,39 @@ pub fn install_tollgate_apk_native(router: &Router) -> Result<()> {
         anyhow::bail!("Could not determine router architecture");
     }
 
+    // Prefer a native .apk when the release publishes one for this arch —
+    // `apk add` handles the install itself (deps, postinst, uci-defaults),
+    // skipping the manual ar/tar extraction the .ipk fallback below needs.
+    if let Some(url) = apk_url(arch) {
+        info!(
+            "[{}] Downloading native TollGate .apk for {} from GitHub releases",
+            router.host, arch
+        );
+        let (dl_out, dl_code) = router.run(&format!(
+            "wget --no-check-certificate -O /tmp/tollgate.apk '{}' 2>&1",
+            url
+        ))?;
+        if dl_code != 0 {
+            anyhow::bail!("TollGate .apk download failed: {}", dl_out.trim());
+        }
+        let (size_out, _) = router.run("wc -c < /tmp/tollgate.apk 2>/dev/null")?;
+        let size: u64 = size_out.trim().parse().unwrap_or(0);
+        if size < 50_000 {
+            anyhow::bail!(
+                "Downloaded TollGate .apk is only {}B — wget likely captured an error page. \
+                 Check router internet access and that the release URL is reachable.",
+                size
+            );
+        }
+        let (add_out, add_code) =
+            router.run("apk add --allow-untrusted /tmp/tollgate.apk 2>&1")?;
+        router.run_ok("rm -f /tmp/tollgate.apk")?;
+        if add_code != 0 {
+            anyhow::bail!("TollGate .apk install failed: {}", add_out.trim());
+        }
+        return Ok(());
+    }
+
     let url = ipk_url(arch).ok_or_else(|| {
         anyhow::anyhow!(
             "No pre-built TollGate package for architecture '{}'. \

docs/openwrt-gateway-setup.md

@@ -69,6 +69,15 @@ matches the prebuilt TollGate `.ipk` architectures exactly
    From here, continue with the Prerequisites/Step 2 flow above to connect
    it to the Archipelago node.
 
+   > The Archipelago UI's Connect form (Step 2) authenticates *with* a
+   > password — it has no flow for setting the initial one on a fresh,
+   > passwordless router. You have to set it out-of-band first. If you're
+   > working from the node's own local kiosk display rather than a normal
+   > desktop browser, there's no visible tab bar/address bar to open a new
+   > tab from — press **Ctrl+T** to open one anyway, navigate to
+   > `192.168.1.1`, and use LuCI's first-boot prompt to set the root
+   > password. Then switch back to the Archipelago tab and Connect with it.
+
 **If the flash fails / the router doesn't come back**: filogic devices
 don't use a reset-button recovery. Instead, connect to the router's LAN
 port and, during boot, press a key within the first ~2 seconds to enter
@@ -169,6 +178,52 @@ installed:
 Anyone who joins the `archipelago` SSID sees TollGate's captive portal and
 pays sats (via the configured Cashu mint) for timed access.
 
+## Verifying a successful install
+
+A clean install (flash → Connect → WAN/WISP → Install TollGate, all through
+the UI as above) ends in this state — worth checking if you want to confirm
+everything actually landed correctly rather than trusting the UI's success
+toast alone:
+
+- `tollgate-wrt` is running (`/etc/init.d/tollgate-wrt status` → `running`).
+- nodogsplash's **rendered** config — not just the UCI source — has
+  `GatewayInterface br-tollgate`. Check the actual file the daemon was
+  started with (typically `/tmp/etc/nodogsplash_main.conf`), since that's
+  what's actually enforced, not `uci show nodogsplash`. This matters because
+  provisioning must stop nodogsplash and reconfigure it to gate the
+  `br-tollgate` bridge *before* starting it — installing the package by hand
+  (bypassing the UI/RPC flow) leaves nodogsplash on its default
+  `br-lan`-gating behavior instead, which locks out the router's own
+  admin/SSH access. If you ever see a router become unreachable right after
+  a TollGate install, this is the first thing to check.
+- The router's own LAN (the interface you manage it over — SSH, ping) is
+  still reachable and untouched by the portal.
+- TollGate's own log (`logread | grep tollgate-wrt`) shows successful mint
+  probes for each configured mint.
+
+A `dev build detected (branch=unknown), injecting test mint:
+https://nofee.testnut.cashu.space` line in that log means the installed
+build considers itself a dev build and silently adds a test mint alongside
+your configured one(s) — check the Edit panel's Mint URL afterward if you
+don't want that test mint accepted.
+
+### A note on network topology during setup
+
+If the Archipelago node reaches the router over the same wired interface the
+router uses as its LAN, expect the router to become the node's default
+route on that interface once it has its own working WAN/WISP uplink — this
+is normal and, once WAN is actually configured with internet access, works
+fine end-to-end (the node's traffic routes out through the router's
+uplink). It's only a problem *before* WAN is configured: a freshly flashed
+or freshly factory-reset router has no upstream internet yet, so if it wins
+the node's default-route race (lowest metric on its own interface) while
+still offline, it creates a dead-end route and the node loses its own
+connectivity (including anything tunneled, e.g. a VPN/mesh network the node
+relies on) until that route is removed or the router gets its uplink
+working. If you hit this, either wait until WAN/WISP is actually up before
+letting the router's interface win the route race, or temporarily lower the
+priority of that route until it is.
+
 ## Reconfiguring or moving to a different router
 
 Use **Disconnect** on the status dashboard to return to the connect form —
@@ -198,6 +253,18 @@ new host/credentials; the newly connected router becomes the persisted one.
   fails**: the node sanity-checks the downloaded `.ipk` is at least 50 KB —
   a smaller file usually means `wget` captured an HTML error page instead
   (no internet access from the router, or a bad release URL).
+- **Install fails right after a reboot or a fresh WAN setup** with `apk
+  update failed ... router may have no internet access` even though WAN
+  looks configured: this is usually just timing, not a real problem — the
+  router's WiFi-uplink association (`wwan`/`hakodosh`-style STA interface)
+  can take a few seconds longer to reconnect than the dashboard takes to
+  let you click Install. Wait ~10–15 seconds after WAN shows `sta_state:
+  up` and retry; it should succeed on the next attempt.
+- **Install fails with `opkg not found at /usr/bin/opkg` (or similar) even
+  though the router clearly has `opkg`/`apk` installed**: fixed as of
+  2026-09-05 — the backend used to hardcode `/usr/bin/opkg`/`/usr/bin/apk`,
+  which some official OpenWrt builds don't symlink into `/bin`. If you're
+  running an Archipelago build from before that fix, update first.
 
 ---