@rubytech/create-realagent 1.0.775 → 1.0.789

package/dist/index.js

@@ -430,6 +430,18 @@ function installSystemDeps() {
                 console.log(`  Avahi host-name: ${HOSTNAME_FLAG} (updated avahi-daemon.conf)`);
             }
             catch { /* avahi-daemon.conf may not exist — non-critical */ }
+            // Restart avahi-daemon so the new hostname takes effect immediately
+            // and any stale "maxytest-2" auto-renamed records from a previous
+            // boot's hostname-conflict cycle are withdrawn. Without this,
+            // avahi-resolve -n <hostname>.local times out from the device itself
+            // because the daemon is still advertising the previous identity.
+            try {
+                console.log("  [privileged] systemctl restart avahi-daemon");
+                shell("systemctl", ["restart", "avahi-daemon"], { sudo: true });
+            }
+            catch (err) {
+                console.error(`  WARNING: avahi-daemon restart failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
         }
         catch (err) {
             console.error(`  WARNING: Failed to set hostname to '${HOSTNAME_FLAG}': ${err instanceof Error ? err.message : String(err)}`);
@@ -1346,6 +1358,19 @@ function buildPlatform() {
     // server/package.json but NOT shipped as pre-built node_modules — npm pack silently
     // strips files from nested node_modules (e.g. rxjs/package.json), breaking require().
     // Install fresh on device to guarantee a complete dependency tree.
+    //
+    // On upgrade, wipe `node_modules` first so npm extracts a clean tree. Without
+    // this, an interrupted previous install (network blip, operator cancellation,
+    // power loss) can leave nested package.json files half-truncated — the most
+    // common manifestation is `Error: Invalid package config .../rxjs/package.json`
+    // at server startup, which loops the brand service indefinitely. The wipe
+    // adds ~30 s to upgrades but eliminates a class of unrecoverable customer
+    // states; reliability wins over speed for a one-shot install path.
+    const serverNodeModules = join(INSTALL_DIR, "server", "node_modules");
+    if (existsSync(serverNodeModules)) {
+        console.log("  Wiping previous server/node_modules for a clean reinstall...");
+        rmSync(serverNodeModules, { recursive: true, force: true });
+    }
     console.log(`  Installing server dependencies (${join(INSTALL_DIR, "server")})...`);
     shellRetry("npm", ["install", "--omit=dev", ...NPM_NET_FLAGS], { cwd: join(INSTALL_DIR, "server") }, 3, 15);
 }
@@ -1541,11 +1566,11 @@ function setupVncViewer() {
 }
 function setupAccount() {
     log("10", TOTAL, "Setting up...");
-    // Tasks 787 + 788 — both seed-neo4j.sh and embed-backfill.sh hard-exit
-    // without NEO4J_URI. The installer owns the brand-correct URI and password,
-    // so we derive them once and pass to both call sites. Missing password file
-    // is a hard error: ensureNeo4jPassword() ran upstream and would have thrown
-    // already if it couldn't reach the brand's Neo4j.
+    // Task 787 — seed-neo4j.sh hard-exits without NEO4J_URI. The installer
+    // owns the brand-correct URI and password, so we derive them once.
+    // Missing password file is a hard error: ensureNeo4jPassword() ran
+    // upstream and would have thrown already if it couldn't reach the
+    // brand's Neo4j.
     const passwordFile = join(INSTALL_DIR, "platform/config/.neo4j-password");
     if (!existsSync(passwordFile)) {
         throw new Error(`Neo4j password file missing at ${passwordFile} — required by setup step.`);
@@ -1559,40 +1584,6 @@ function setupAccount() {
         logFile(`  [neo4j] passing NEO4J_URI=${neo4jUri} to seed`);
         shell("bash", [seedScript], { cwd: INSTALL_DIR, env: neo4jEnv });
     }
-    // Task 748 — universal embedding coverage backfill. Run after seed so the
-    // entity_search index is in place and any pre-Task-748 nodes (e.g. the
-    // 5096 LinkedIn-imported Persons on existing Pis that bulk-import skipped
-    // embedding for) get a vector populated. Idempotent — instant no-op when
-    // nothing is pending, so re-running on every install is harmless.
-    //
-    // Failure-mode policy: WARN, do not abort. The fulltext index is already
-    // applied above, so BM25 search works end-to-end without embeddings; the
-    // only gap is vector ranking quality on legacy nodes. Aborting the
-    // installer on an Ollama hiccup would block every install for a
-    // strictly-degradable feature. The script's own loud-failure output
-    // tells the operator how to re-run.
-    const backfillScript = join(INSTALL_DIR, "platform/scripts/embed-backfill.sh");
-    if (existsSync(backfillScript)) {
-        const start = Date.now();
-        logFile(`> bash ${backfillScript} (warn-not-abort)`);
-        const result = spawnSync("bash", [backfillScript], {
-            stdio: "inherit",
-            timeout: 30 * 60_000,
-            cwd: INSTALL_DIR,
-            env: neo4jEnv,
-        });
-        const dur = ((Date.now() - start) / 1000).toFixed(1);
-        if (result.status !== 0 || result.signal) {
-            const reason = result.signal ? `signal=${result.signal}` : `exit=${result.status}`;
-            logFile(`  WARN: embed-backfill non-zero (${reason}) after ${dur}s`);
-            console.warn(`\n  WARNING: embed-backfill did not complete (${reason}) — BM25 search works,\n` +
-                `  but vector ranking on legacy nodes will be sparse until you re-run:\n` +
-                `    bash ${backfillScript}\n`);
-        }
-        else {
-            logFile(`  OK embed-backfill in ${dur}s`);
-        }
-    }
 }
 // ---------------------------------------------------------------------------
 // Tunnel script shortcuts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent",
-  "version": "1.0.775",
+  "version": "1.0.789",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent": "./dist/index.js"

package/payload/platform/plugins/docs/references/troubleshooting.md

@@ -125,7 +125,7 @@ If the initial Cloudflare login fails during setup, {{productName}} will fall ba
 
 Task 795 — `maxy-edge.service` (always-on front door) classifies upstream errors and serves a brand-aware response. There are two distinct user-visible shapes; the right one depends on what failed.
 
-**Branded holding page ("{{productName}} is starting") for ~10 s during an upgrade — this is expected and self-healing.** The edge process binds the public port immediately, but `maxy.service` (the upstream UI) takes ~10 s after restart to apply the neo4j schema and mount its 11 routes. Any browser navigation that lands during that window gets a self-contained HTML holding page that polls `/api/health` and reloads automatically once the upstream binds. No operator action required. The diagnostic line in `~/.maxy/logs/edge.log` is `[edge] upstream http error path=… err=connect ECONNREFUSED 127.0.0.1:<UPSTREAM_PORT> err-class=econnrefused-coldstart upstream=…` and disappears as soon as upstream binds.
+**Branded holding page (brand logo + "Starting") for ~10 s during an upgrade — this is expected and self-healing.** The edge process binds the public port immediately, but `maxy.service` (the upstream UI) takes ~10 s after restart to apply the neo4j schema and mount its 11 routes. Any browser navigation that lands during that window gets a self-contained HTML holding page that polls `/api/health` and reloads automatically once the upstream binds. The page renders the brand logo (inlined as a base64 data URI at edge boot from `<install>/server/public/brand/<assets.logo>`) and the brand display/body fonts (loaded from fonts.googleapis.com) — both paths bypass the unavailable upstream so the page never makes a same-origin asset fetch. When `brand.logoContainsName` is true the logo replaces the productName text; otherwise the page falls back to "{{productName}} is starting". No operator action required. The diagnostic line in `~/.maxy/logs/edge.log` is `[edge] upstream http error path=… err=connect ECONNREFUSED 127.0.0.1:<UPSTREAM_PORT> err-class=econnrefused-coldstart upstream=…` and disappears as soon as upstream binds. Boot-time confirmation that the logo resolved: `[edge] brand=<name> holding-logo=inlined assets-dir=<path>` — `holding-logo=missing` means the logo file wasn't found at `assets-dir`, the page degrades to text-only.
 
 **Branded plain-text 502 ("Bad Gateway ({{productName}} unavailable)") — real upstream failure, not cold-start.** Any error class other than `ECONNREFUSED` (timeouts, resets, host-unreachable) returns the existing 502 path. The diagnostic line carries `err-class=other`. Read the log with `tail -200 ~/.maxy/logs/edge.log | rg 'err-class=other'` and check `~/.maxy/logs/server.log` for upstream stack traces — the upstream itself is the source.
 

package/payload/platform/scripts/wifi-provision-server/server.js

@@ -38,11 +38,34 @@ const CONNECT_FIFO = args["connect-fifo"] || "/tmp/wifi-provision-connect";
 const RESULT_FILE = args["result-file"] || "/tmp/wifi-provision-result";
 const BRAND_JSON = args["brand-json"] || "";
 const HOSTNAME = args.hostname || "maxy";
-
-// ── Load brand config ────────────────────────────────────────────���──
+const PORTAL_HOST = args["portal-host"] || "";
+// Brand service port (e.g. 19200). Distinct from PORT, which is the
+// captive portal's own listen port (always 80). Used only to render the
+// post-connect URL.
+const DEVICE_PORT = parseInt(args["device-port"] || "19200", 10);
+
+// ── Load brand config ─────────────────────────────────────────────────
+// All visual surfaces (colour, font, logo) come from brand.json so the
+// captive portal matches the rest of the product. Earlier this file
+// hard-coded a generic dark navy + system font fallback that bore no
+// relation to the brand's actual look — the operator-side complaint
+// that surfaced this. Now: read the brand's `defaultColors`,
+// `defaultFonts`, and `assets.logo`, fall through to neutral defaults
+// only if a field is missing from brand.json.
 let brandName = "Maxy";
-let brandColor = "#1a1a2e";
-let brandAccent = "#4a90d9";
+const colors = {
+  primary: "#1a1a2e",
+  primaryHover: "#0f0f1f",
+  background: "#FAFAF8",
+  text: "#1a1a2e",
+  card: "rgba(0,0,0,0.04)",
+  cardBorder: "rgba(0,0,0,0.08)",
+  muted: "#6b6b6b",
+};
+const fonts = {
+  display: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+  body: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
+};
 let logoBase64 = "";
 
 try {
@@ -50,15 +73,29 @@ try {
     const brand = JSON.parse(fs.readFileSync(BRAND_JSON, "utf-8"));
     if (brand.productName) brandName = brand.productName;
 
-    // Load logo if available (brand assets are alongside brand.json)
+    if (brand.defaultColors) {
+      const c = brand.defaultColors;
+      if (c.primary) colors.primary = c.primary;
+      if (c.primaryHover) colors.primaryHover = c.primaryHover;
+      if (c.background) colors.background = c.background;
+      if (c.agentBubble) colors.card = c.agentBubble;
+    }
+    if (brand.defaultFonts) {
+      if (brand.defaultFonts.display) fonts.display = brand.defaultFonts.display;
+      if (brand.defaultFonts.body) fonts.body = brand.defaultFonts.body;
+    }
+
+    // Load logo. Prefer assets.logo (the larger brand mark) and fall
+    // back to assets.icon.
     const brandDir = path.dirname(BRAND_JSON);
-    if (brand.assets && brand.assets.icon) {
-      const iconPath = path.join(brandDir, "assets", brand.assets.icon);
-      if (fs.existsSync(iconPath)) {
-        const iconData = fs.readFileSync(iconPath);
-        const ext = path.extname(iconPath).slice(1);
+    const logoFile = (brand.assets && (brand.assets.logo || brand.assets.icon)) || "";
+    if (logoFile) {
+      const logoPath = path.join(brandDir, "assets", logoFile);
+      if (fs.existsSync(logoPath)) {
+        const logoData = fs.readFileSync(logoPath);
+        const ext = path.extname(logoPath).slice(1);
         const mime = ext === "png" ? "image/png" : ext === "ico" ? "image/x-icon" : "image/" + ext;
-        logoBase64 = `data:${mime};base64,${iconData.toString("base64")}`;
+        logoBase64 = `data:${mime};base64,${logoData.toString("base64")}`;
       }
     }
   }
@@ -95,25 +132,29 @@ function portalHTML() {
 <style>
   * { margin: 0; padding: 0; box-sizing: border-box; }
   body {
-    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-    background: ${brandColor};
-    color: #e8e8e8;
+    font-family: ${fonts.body};
+    background: ${colors.background};
+    color: ${colors.text};
     min-height: 100vh;
     display: flex;
     flex-direction: column;
     align-items: center;
     padding: 24px 16px;
   }
-  .logo { width: 48px; height: 48px; margin-bottom: 8px; border-radius: 12px; }
+  .logo { width: 56px; height: 56px; margin-bottom: 12px; border-radius: 12px; }
   .logo-text {
-    font-size: 24px; font-weight: 700; margin-bottom: 8px;
-    color: ${brandAccent};
+    font-family: ${fonts.display};
+    font-size: 28px; font-weight: 600; margin-bottom: 8px;
+    color: ${colors.primary};
+  }
+  h1 {
+    font-family: ${fonts.display};
+    font-size: 22px; font-weight: 500; margin-bottom: 4px;
   }
-  h1 { font-size: 20px; font-weight: 600; margin-bottom: 4px; }
-  .subtitle { font-size: 14px; color: #999; margin-bottom: 24px; }
+  .subtitle { font-size: 14px; color: ${colors.muted}; margin-bottom: 24px; }
   .card {
-    background: rgba(255,255,255,0.06);
-    border: 1px solid rgba(255,255,255,0.1);
+    background: ${colors.card};
+    border: 1px solid ${colors.cardBorder};
     border-radius: 12px;
     width: 100%; max-width: 360px;
     padding: 16px;
@@ -128,17 +169,17 @@ function portalHTML() {
     transition: background 0.15s;
   }
   .network-item:hover, .network-item.selected {
-    background: rgba(255,255,255,0.1);
+    background: ${colors.cardBorder};
   }
-  .network-item.selected { border: 1px solid ${brandAccent}; }
+  .network-item.selected { border: 1px solid ${colors.primary}; }
   .network-name { font-size: 15px; font-weight: 500; }
-  .network-meta { font-size: 12px; color: #888; }
+  .network-meta { font-size: 12px; color: ${colors.muted}; }
   .signal-bars { display: flex; gap: 2px; align-items: flex-end; height: 16px; }
   .signal-bar {
     width: 4px; border-radius: 1px;
-    background: rgba(255,255,255,0.2);
+    background: ${colors.cardBorder};
   }
-  .signal-bar.active { background: ${brandAccent}; }
+  .signal-bar.active { background: ${colors.primary}; }
   .password-group {
     position: relative;
     margin-top: 16px;
@@ -146,34 +187,35 @@ function portalHTML() {
   .password-group input {
     width: 100%;
     padding: 12px 44px 12px 12px;
-    background: rgba(255,255,255,0.08);
-    border: 1px solid rgba(255,255,255,0.15);
+    background: ${colors.background};
+    border: 1px solid ${colors.cardBorder};
     border-radius: 8px;
-    color: #e8e8e8;
+    color: ${colors.text};
     font-size: 15px;
     outline: none;
   }
-  .password-group input:focus { border-color: ${brandAccent}; }
+  .password-group input:focus { border-color: ${colors.primary}; }
   .toggle-pw {
     position: absolute; right: 8px; top: 50%; transform: translateY(-50%);
-    background: none; border: none; color: #888; cursor: pointer;
+    background: none; border: none; color: ${colors.muted}; cursor: pointer;
     font-size: 13px; padding: 4px 8px;
   }
   .btn {
     width: 100%; padding: 14px;
-    background: ${brandAccent};
+    background: ${colors.primary};
     color: #fff; font-size: 16px; font-weight: 600;
     border: none; border-radius: 8px;
     cursor: pointer; margin-top: 16px;
-    transition: opacity 0.15s;
+    transition: background 0.15s;
     min-height: 48px;
   }
-  .btn:disabled { opacity: 0.5; cursor: not-allowed; }
+  .btn:hover:not(:disabled) { background: ${colors.primaryHover}; }
+  .btn:disabled { opacity: 0.4; cursor: not-allowed; }
   .error {
-    color: #ff6b6b; font-size: 13px;
+    color: #c0392b; font-size: 13px;
     margin-top: 8px; display: none;
   }
-  .empty { text-align: center; padding: 24px; color: #888; font-size: 14px; }
+  .empty { text-align: center; padding: 24px; color: ${colors.muted}; font-size: 14px; }
 
   /* Progress / success screens */
   .screen { display: none; width: 100%; max-width: 360px; text-align: center; }
@@ -181,31 +223,35 @@ function portalHTML() {
   @keyframes spin { to { transform: rotate(360deg); } }
   .spinner {
     width: 40px; height: 40px;
-    border: 3px solid rgba(255,255,255,0.15);
-    border-top-color: ${brandAccent};
+    border: 3px solid ${colors.cardBorder};
+    border-top-color: ${colors.primary};
     border-radius: 50%;
     animation: spin 0.8s linear infinite;
     margin: 24px auto;
   }
   .success-icon {
     width: 48px; height: 48px; margin: 24px auto;
-    border-radius: 50%; background: #2ecc71;
+    border-radius: 50%; background: ${colors.primary};
     display: flex; align-items: center; justify-content: center;
     font-size: 24px; color: #fff;
   }
   .address-box {
-    background: rgba(255,255,255,0.08);
-    border: 1px solid rgba(255,255,255,0.15);
+    background: ${colors.card};
+    border: 1px solid ${colors.cardBorder};
     border-radius: 8px;
     padding: 12px 16px;
     margin: 16px auto;
     display: inline-block;
+    max-width: 100%;
+    word-break: break-all;
   }
   .address-box a {
-    color: ${brandAccent};
-    text-decoration: none;
+    color: ${colors.primary};
+    text-decoration: underline;
     font-size: 16px;
     font-weight: 600;
+    display: block;
+    -webkit-tap-highlight-color: ${colors.primary};
   }
   .hint { color: #888; font-size: 13px; margin-top: 12px; line-height: 1.5; }
 </style>
@@ -245,9 +291,11 @@ function portalHTML() {
     <div class="card" style="padding:32px 16px">
       <div class="success-icon">&#10003;</div>
       <h1>Connected!</h1>
-      <p class="hint">${escapedBrandName} is now online. Open your browser and visit:</p>
-      <div class="address-box">
-        <a id="device-link" href="#" target="_blank"></a>
+      <p class="hint">${escapedBrandName} is now online. Redirecting in <span id="redirect-countdown">15</span>s…</p>
+      <a id="open-btn" href="#" class="btn" style="text-decoration:none;display:flex;align-items:center;justify-content:center">Open ${escapedBrandName} →</a>
+      <p class="hint" style="margin-top:16px">Or copy this URL into your browser:</p>
+      <div class="address-box" style="user-select:all" id="manual-box">
+        <span id="device-link-text"></span>
       </div>
       <p class="hint">This access point will close shortly.<br>Your phone will reconnect to your WiFi automatically.</p>
     </div>
@@ -257,7 +305,10 @@ function portalHTML() {
 (function() {
   "use strict";
   var selectedSSID = "";
-  var devicePort = ${PORT === 80 ? '""' : JSON.stringify(":" + PORT)};
+  // The brand service port (19200, configurable via --port), NOT the
+  // captive portal port (always 80). devicePort is appended to the
+  // post-connect URL so the link points at the admin server.
+  var devicePort = ${DEVICE_PORT === 80 ? '""' : JSON.stringify(":" + DEVICE_PORT)};
   var deviceHostname = ${JSON.stringify(HOSTNAME)};
 
   // Safe text insertion — no innerHTML for user-controlled content
@@ -362,13 +413,40 @@ function portalHTML() {
   }
 
   function showSuccess(data) {
-    var addr = data.hostname
+    var hostnameAddr = data.hostname
       ? "http://" + data.hostname + ".local" + devicePort
-      : "http://" + data.ip + devicePort;
-    var link = document.getElementById("device-link");
-    link.href = addr;
-    link.textContent = addr;
+      : null;
+    var ipAddr = data.ip ? "http://" + data.ip + devicePort : null;
+    // Auto-navigate target: prefer the IP because mDNS .local resolution
+    // is flaky on Android (notably Brave) and the redirect dead-ends.
+    var redirectAddr = ipAddr || hostnameAddr;
+    var openBtn = document.getElementById("open-btn");
+    if (openBtn) openBtn.href = redirectAddr;
+    var manualText = document.getElementById("device-link-text");
+    if (manualText) manualText.textContent = redirectAddr;
     showScreen("success-screen");
+    // 15s countdown: the Pi keeps the AP up for ~10s after writing the
+    // success result so this poll can land, then tears it down; the
+    // phone then needs ~5s to drop the AP SSID and rejoin home WiFi.
+    var remaining = 15;
+    var countdownEl = document.getElementById("redirect-countdown");
+    var ticker = setInterval(function() {
+      remaining -= 1;
+      if (countdownEl) countdownEl.textContent = String(remaining);
+      if (remaining <= 0) {
+        clearInterval(ticker);
+        // Try multiple navigation primitives — captive webviews on some
+        // platforms ignore one but accept another.
+        try { window.location.replace(redirectAddr); } catch(e) {}
+        try { window.location.href = redirectAddr; } catch(e) {}
+        // Last-resort: synthesise a click on a freshly-built anchor.
+        try {
+          var a = document.createElement("a");
+          a.href = redirectAddr; a.rel = "noopener";
+          document.body.appendChild(a); a.click();
+        } catch(e) {}
+      }
+    }, 1000);
   }
 
   function pollResult() {
@@ -475,7 +553,7 @@ function handleRequest(req, res) {
 
   // Captive portal detection — iOS
   if (pathname === "/hotspot-detect.html" || pathname === "/library/test/success.html") {
-    res.writeHead(302, { Location: `http://${AP_IP}/` });
+    res.writeHead(302, { Location: `http://${PORTAL_HOST || AP_IP}/` });
     res.end();
     return;
   }
@@ -483,14 +561,14 @@ function handleRequest(req, res) {
   // Captive portal detection — Android
   if (pathname === "/generate_204" || pathname === "/gen_204" ||
       pathname === "/connecttest.txt" || pathname === "/ncsi.txt") {
-    res.writeHead(302, { Location: `http://${AP_IP}/` });
+    res.writeHead(302, { Location: `http://${PORTAL_HOST || AP_IP}/` });
     res.end();
     return;
   }
 
   // Captive portal detection — Windows
   if (pathname === "/redirect" || pathname === "/fwlink/") {
-    res.writeHead(302, { Location: `http://${AP_IP}/` });
+    res.writeHead(302, { Location: `http://${PORTAL_HOST || AP_IP}/` });
     res.end();
     return;
   }
@@ -525,6 +603,7 @@ function handleRequest(req, res) {
 
   // API: POST /connect — submit WiFi credentials
   if (pathname === "/connect" && req.method === "POST") {
+    console.error(`[wifi-provision-server] /connect POST received connecting-flag=${connecting}`);
     if (connecting) {
       res.writeHead(409, { "Content-Type": "application/json" });
       res.end('{"error":"Connection already in progress"}');
@@ -577,8 +656,12 @@ function handleRequest(req, res) {
         // Use async open+write to avoid blocking the event loop (a FIFO
         // write blocks until a reader opens the other end).
         connecting = true;
-        res.writeHead(202, { "Content-Type": "application/json" });
-        res.end('{"status":"connecting"}');
+        console.error(`[wifi-provision-server] /connect ssid=${JSON.stringify(ssid)} → 200 sync-success hostname=${HOSTNAME}`);
+        res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+        res.end(JSON.stringify({
+          success: true,
+          hostname: HOSTNAME,
+        }));
 
         const fifoData = `${ssid}\n${password}`;
         fs.open(CONNECT_FIFO, "w", (err, fd) => {
@@ -620,8 +703,23 @@ function handleRequest(req, res) {
     return;
   }
 
-  // Default: serve portal page
-  res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+  // Default: serve portal page. If the client hit the raw AP IP (e.g.
+  // 192.168.4.1) and we have a friendly portal host configured, redirect
+  // so the URL bar shows the brand-aware name (e.g. http://maxy.setup/).
+  // dnsmasq's wildcard DNS resolves PORTAL_HOST → AP_IP transparently
+  // while the AP is up.
+  const incomingHost = (req.headers.host || "").split(":")[0];
+  if (PORTAL_HOST && incomingHost === AP_IP) {
+    res.writeHead(302, { Location: `http://${PORTAL_HOST}/` });
+    res.end();
+    return;
+  }
+  res.writeHead(200, {
+    "Content-Type": "text/html; charset=utf-8",
+    "Cache-Control": "no-store, no-cache, must-revalidate",
+    "Pragma": "no-cache",
+    "Expires": "0",
+  });
   res.end(portalHTML());
 }
 

package/payload/platform/scripts/wifi-provision.sh

@@ -40,15 +40,21 @@ PLATFORM_ROOT="${MAXY_PLATFORM_ROOT:-$(dirname "$SCRIPT_DIR")}"
 BRAND_JSON="${PLATFORM_ROOT}/config/brand.json"
 CONFIG_DIR=".maxy"
 PRODUCT_NAME="Maxy"
-HOSTNAME_NAME="maxy"
 if [ -f "$BRAND_JSON" ] && command -v jq >/dev/null 2>&1; then
   _dir=$(jq -r '.configDir // empty' "$BRAND_JSON" 2>/dev/null) || true
   [ -n "$_dir" ] && CONFIG_DIR="$_dir"
   _name=$(jq -r '.productName // empty' "$BRAND_JSON" 2>/dev/null) || true
   [ -n "$_name" ] && PRODUCT_NAME="$_name"
-  _host=$(jq -r '.hostname // empty' "$BRAND_JSON" 2>/dev/null) || true
-  [ -n "$_host" ] && HOSTNAME_NAME="$_host"
 fi
+# HOSTNAME_NAME must be the **actual system hostname** (the name Avahi
+# advertises and the post-connect URL must use), not the brand default
+# from brand.json. The operator's --hostname flag rewrites the system
+# hostname but never touches brand.json's hostname field, so reading
+# from the brand mis-routed the captive portal's success URL to a name
+# that doesn't resolve. `hostname -s` is the canonical answer Avahi
+# itself follows when avahi-daemon.conf has `host-name` left empty,
+# so this is the same source of truth.
+HOSTNAME_NAME="$(hostname -s 2>/dev/null || hostname 2>/dev/null || echo maxy)"
 
 # Determine the home directory of the installing user. The service runs as
 # root, but logs and config belong to the user who installed the platform.
@@ -60,9 +66,33 @@ LOG_FILE="${LOG_DIR}/wifi-provision.log"
 
 mkdir -p "$LOG_DIR"
 
+# Resolve the brand service's public port so the captive portal can render
+# the post-connect URL with the correct port (the captive portal itself
+# runs on :80, but the device's admin URL is on the brand port). Mirrors
+# the same precedence as the installer: ~/{configDir}/.env override, then
+# the systemd unit's Environment=PORT, then the documented default.
+BRAND_PORT="19200"
+if [ -f "${MAXY_DIR}/.env" ]; then
+  _p=$(grep -E '^PORT=' "${MAXY_DIR}/.env" 2>/dev/null | tail -1 | cut -d= -f2 | tr -d '"' | tr -d "'")
+  [ -n "$_p" ] && BRAND_PORT="$_p"
+fi
+if [ "$BRAND_PORT" = "19200" ]; then
+  _svc="${INSTALL_HOME}/.config/systemd/user/${HOSTNAME_NAME}.service"
+  if [ -f "$_svc" ]; then
+    _p=$(grep -E '^Environment=PORT=' "$_svc" 2>/dev/null | tail -1 | cut -d= -f3)
+    [ -n "$_p" ] && BRAND_PORT="$_p"
+  fi
+fi
+
 # ── Derived constants ────────────────────────────────────────────────
-# SSID: remove spaces from product name, append -Setup
-SSID="${PRODUCT_NAME// /}-Setup"
+# SSID: lowercase the product name and replace spaces with hyphens — gives
+# `maxy`, `real-agent`, etc. (kebab-case, no "-Setup" suffix). The user's
+# phone-side WiFi list is the brand surface; an extra "-Setup" suffix is
+# operator jargon, not customer language.
+SSID="$(echo "$PRODUCT_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')"
+# Captive-portal hostname served by dnsmasq's wildcard — gives the phone
+# a friendly URL bar (`http://maxy.setup/`) instead of `http://192.168.4.1/`.
+PORTAL_HOST="${SSID}.setup"
 AP_IP="192.168.4.1"
 AP_SUBNET="192.168.4.0/24"
 DHCP_RANGE_START="192.168.4.2"
@@ -157,8 +187,31 @@ get_wifi_ip() {
 
 scan_networks() {
   log "scanning WiFi networks"
-  local raw
-  raw=$(nmcli -t -f SSID,SIGNAL,SECURITY device wifi list --rescan yes 2>/dev/null) || true
+
+  # `nmcli device wifi list --rescan yes` triggers a rescan but returns the
+  # currently cached list immediately — on cold boot the cache is empty
+  # because the radio hasn't completed its first scan yet. Trigger an
+  # explicit rescan, then poll the cached list until it has at least one
+  # visible (non-hidden) SSID, up to a hard timeout.
+  nmcli device wifi rescan 2>/dev/null || true
+  local raw=""
+  local elapsed=0
+  local max_wait=15
+  while [ "$elapsed" -lt "$max_wait" ]; do
+    raw=$(nmcli -t -f SSID,SIGNAL,SECURITY device wifi list 2>/dev/null) || true
+    # Lines have form SSID:SIGNAL:SECURITY; a leading ':' means hidden SSID.
+    # Break as soon as at least one line starts with a non-':' character.
+    if [ -n "$raw" ] && echo "$raw" | grep -qE '^[^:]'; then
+      break
+    fi
+    sleep 1
+    elapsed=$((elapsed + 1))
+  done
+  if [ "$elapsed" -ge "$max_wait" ]; then
+    log "scan timeout: no visible networks after ${max_wait}s — proceeding with empty list"
+  else
+    log "scan settled in ${elapsed}s"
+  fi
 
   # Parse nmcli terse output into JSON using jq for safe escaping.
   # Terse mode uses colon separators and escapes literal colons as \:
@@ -260,6 +313,8 @@ DNSMASQ_EOF
     --result-file "$RESULT_FILE" \
     --brand-json "$BRAND_JSON" \
     --hostname "$HOSTNAME_NAME" \
+    --portal-host "$PORTAL_HOST" \
+    --device-port "$BRAND_PORT" \
     >> "$LOG_FILE" 2>&1 &
   HTTP_SERVER_PID=$!
   sleep 1
@@ -309,10 +364,28 @@ handle_connect_requests() {
     nmcli device set wlan0 managed yes 2>/dev/null
     sleep 2
 
+    # NM's wifi-list cache is empty immediately after wlan0 is handed back
+    # from hostapd, so `nmcli device wifi connect` reports "No network with
+    # SSID 'X' found" even when hostapd's pre-AP scan saw it. Trigger a
+    # rescan and poll until the target SSID appears in the cache (or 15s
+    # timeout) before attempting the connect.
+    nmcli device wifi rescan 2>/dev/null || true
+    local rescan_elapsed=0
+    while [ "$rescan_elapsed" -lt 15 ]; do
+      if nmcli -t -f SSID device wifi list 2>/dev/null | grep -Fxq "$target_ssid"; then
+        break
+      fi
+      sleep 1
+      rescan_elapsed=$((rescan_elapsed + 1))
+    done
+    log "rescan-before-connect: target=\"${target_ssid}\" elapsed=${rescan_elapsed}s"
+
     # Attempt WiFi connection. Capture exit code before || true so we
     # get nmcli's actual exit status, not the unconditional 0 from || true.
     local connect_output connect_exit
-    connect_output=$(nmcli device wifi connect "$target_ssid" password "$target_password" --wait 30 2>&1)
+    # `--wait` / `-w` is a top-level nmcli option (must precede the
+    # subcommand), not an argument to `device wifi connect`.
+    connect_output=$(nmcli --wait 30 device wifi connect "$target_ssid" password "$target_password" 2>&1)
     connect_exit=$?
 
     if [ $connect_exit -eq 0 ] && wifi_is_connected; then
@@ -320,6 +393,13 @@ handle_connect_requests() {
       assigned_ip=$(get_wifi_ip)
       log_state "connected" "ssid=\"${target_ssid}\" ip=\"${assigned_ip}\""
 
+      # Restart avahi-daemon so it withdraws any stale "<host>-2.local"
+      # auto-renamed records from a previous boot (where hostapd's wlan0
+      # transition triggered a self-conflict during withdraw/announce) and
+      # re-claims the canonical hostname on the freshly-connected network.
+      systemctl restart avahi-daemon 2>/dev/null || true
+      log "avahi-daemon restarted to refresh ${HOSTNAME_NAME}.local advertisement"
+
       # Write success result for the HTTP server
       echo "{\"success\":true,\"ip\":\"${assigned_ip}\",\"hostname\":\"${HOSTNAME_NAME}\"}" > "$RESULT_FILE"