@renbostudios/edge-ota 0.4.0 → 0.4.2

package/dist/index.js

@@ -1,17 +1,6 @@
 #!/usr/bin/env node
-/**
- * edge-ota CLI  — Zero-SDK, self-hostable OTA updates for Expo
- * by Renbo Studios  —  Mobile App Development Studio
- * https://renbostudios.com
- *
- * Commands:
- *   edge-ota login    — Authenticate and save credentials globally
- *   edge-ota logout   — Remove stored credentials
- *   edge-ota init     — Register project, generate signing keys, configure app.json
- *   edge-ota push     — Export bundle and publish an OTA update
- *   edge-ota status   — List recent deployments for this project
- *   edge-ota keygen   — Generate a new ECDSA key pair (prints to stdout)
- */
+
+// src/index.ts
 import { Command } from "commander";
 import { execSync, spawn } from "child_process";
 import fs from "fs";
@@ -19,963 +8,1230 @@ import os from "os";
 import path from "path";
 import readline from "readline";
 import { fileURLToPath } from "url";
-import { generateECDSAKeyPair, signPayload, sha256Hex } from "./core/index.js";
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-// ─── Global Config Paths ─────────────────────────────────────────────────────
-const GLOBAL_CONFIG_DIR = path.join(os.homedir(), ".config", "edge-ota");
-const GLOBAL_CONFIG_FILE = path.join(GLOBAL_CONFIG_DIR, "config.json");
-const GLOBAL_KEYS_DIR = path.join(GLOBAL_CONFIG_DIR, "keys");
+
+// ../../packages/core/dist/crypto.js
+async function generateECDSAKeyPair() {
+  const keyPair = await globalThis.crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
+  const privateKeyDer = await globalThis.crypto.subtle.exportKey("pkcs8", keyPair.privateKey);
+  const publicKeyDer = await globalThis.crypto.subtle.exportKey("spki", keyPair.publicKey);
+  return {
+    privateKey: derToPem(privateKeyDer, "PRIVATE KEY"),
+    publicKey: derToPem(publicKeyDer, "PUBLIC KEY")
+  };
+}
+async function signPayload(payload, privateKeyPem) {
+  const privateKeyDer = pemToDer(privateKeyPem, "PRIVATE KEY");
+  const privateKey = await globalThis.crypto.subtle.importKey("pkcs8", privateKeyDer, { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);
+  const data = new TextEncoder().encode(payload);
+  const sigBuffer = await globalThis.crypto.subtle.sign({ name: "ECDSA", hash: { name: "SHA-256" } }, privateKey, data);
+  return arrayBufferToBase64(sigBuffer);
+}
+async function sha256Hex(buffer) {
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", buffer);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function derToPem(der, label) {
+  const base64 = arrayBufferToBase64(der);
+  const lines = base64.match(/.{1,64}/g) || [];
+  return `-----BEGIN ${label}-----
+${lines.join("\n")}
+-----END ${label}-----`;
+}
+function pemToDer(pem, label) {
+  const cleanPem = pem.replace(`-----BEGIN ${label}-----`, "").replace(`-----END ${label}-----`, "").replace(/\s+/g, "");
+  return base64ToArrayBuffer(cleanPem);
+}
+function arrayBufferToBase64(buffer) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(buffer).toString("base64");
+  }
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  const chunkSize = 32768;
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    binary += String.fromCharCode.apply(null, bytes.subarray(i, i + chunkSize));
+  }
+  return globalThis.btoa(binary);
+}
+function base64ToArrayBuffer(base64) {
+  if (typeof Buffer !== "undefined") {
+    const buf = Buffer.from(base64, "base64");
+    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  }
+  const binary = globalThis.atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+
+// src/index.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+var GLOBAL_CONFIG_DIR = path.join(os.homedir(), ".config", "edge-ota");
+var GLOBAL_CONFIG_FILE = path.join(GLOBAL_CONFIG_DIR, "config.json");
+var GLOBAL_KEYS_DIR = path.join(GLOBAL_CONFIG_DIR, "keys");
 function loadGlobalConfig() {
-    try {
-        if (fs.existsSync(GLOBAL_CONFIG_FILE)) {
-            return JSON.parse(fs.readFileSync(GLOBAL_CONFIG_FILE, "utf-8"));
-        }
+  try {
+    if (fs.existsSync(GLOBAL_CONFIG_FILE)) {
+      return JSON.parse(fs.readFileSync(GLOBAL_CONFIG_FILE, "utf-8"));
     }
-    catch { /* ignore */ }
-    return null;
+  } catch {
+  }
+  return null;
 }
 function saveGlobalConfig(config) {
-    fs.mkdirSync(GLOBAL_CONFIG_DIR, { recursive: true });
-    fs.writeFileSync(GLOBAL_CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+  fs.mkdirSync(GLOBAL_CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(GLOBAL_CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 384 });
 }
 function clearGlobalConfig() {
-    try {
-        fs.rmSync(GLOBAL_CONFIG_FILE);
-    }
-    catch { /* ignore */ }
+  try {
+    fs.rmSync(GLOBAL_CONFIG_FILE);
+  } catch {
+  }
 }
 function loadPrivateKey(projectId) {
-    // 1. Global key store (new location)
-    const globalKeyPath = path.join(GLOBAL_KEYS_DIR, `${projectId}.key`);
-    if (fs.existsSync(globalKeyPath)) {
-        return fs.readFileSync(globalKeyPath, "utf-8").trim();
-    }
-    // 2. Legacy local file (backward compat with deprecation notice)
-    const localKeyPath = path.resolve(process.cwd(), ".edge-ota.private.key");
-    if (fs.existsSync(localKeyPath)) {
-        spin.stop();
-        console.log(`  ${c.yellow}⚠${c.reset}  Using legacy ${c.dim}.edge-ota.private.key${c.reset} in project directory.`);
-        console.log(`     Move it to ${c.dim}${globalKeyPath}${c.reset} and delete the local copy.`);
-        return fs.readFileSync(localKeyPath, "utf-8").trim();
-    }
-    return null;
+  const globalKeyPath = path.join(GLOBAL_KEYS_DIR, `${projectId}.key`);
+  if (fs.existsSync(globalKeyPath)) {
+    return fs.readFileSync(globalKeyPath, "utf-8").trim();
+  }
+  const localKeyPath = path.resolve(process.cwd(), ".edge-ota.private.key");
+  if (fs.existsSync(localKeyPath)) {
+    spin.stop();
+    console.log(`  ${c.yellow}\u26A0${c.reset}  Using legacy ${c.dim}.edge-ota.private.key${c.reset} in project directory.`);
+    console.log(`     Move it to ${c.dim}${globalKeyPath}${c.reset} and delete the local copy.`);
+    return fs.readFileSync(localKeyPath, "utf-8").trim();
+  }
+  return null;
 }
 function savePrivateKey(projectId, key) {
-    fs.mkdirSync(GLOBAL_KEYS_DIR, { recursive: true });
-    const keyPath = path.join(GLOBAL_KEYS_DIR, `${projectId}.key`);
-    fs.writeFileSync(keyPath, key, { mode: 0o600 });
+  fs.mkdirSync(GLOBAL_KEYS_DIR, { recursive: true });
+  const keyPath = path.join(GLOBAL_KEYS_DIR, `${projectId}.key`);
+  fs.writeFileSync(keyPath, key, { mode: 384 });
 }
-// ─── Auto-load .env ───────────────────────────────────────────────────────────
 try {
-    const envPath = path.resolve(process.cwd(), ".env");
-    if (fs.existsSync(envPath)) {
-        for (const line of fs.readFileSync(envPath, "utf8").split("\n")) {
-            const t = line.trim();
-            if (!t || t.startsWith("#"))
-                continue;
-            const eq = t.indexOf("=");
-            if (eq === -1)
-                continue;
-            const k = t.slice(0, eq).trim();
-            const v = t.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
-            if (!(k in process.env))
-                process.env[k] = v;
-        }
+  const envPath = path.resolve(process.cwd(), ".env");
+  if (fs.existsSync(envPath)) {
+    for (const line of fs.readFileSync(envPath, "utf8").split("\n")) {
+      const t = line.trim();
+      if (!t || t.startsWith("#")) continue;
+      const eq = t.indexOf("=");
+      if (eq === -1) continue;
+      const k = t.slice(0, eq).trim();
+      const v = t.slice(eq + 1).trim().replace(/^["']|["']$/g, "");
+      if (!(k in process.env)) process.env[k] = v;
     }
+  }
+} catch {
 }
-catch { /* silently skip */ }
-// ─── ANSI Colors ─────────────────────────────────────────────────────────────
-const c = {
-    reset: "\x1b[0m",
-    bold: "\x1b[1m",
-    dim: "\x1b[2m",
-    underline: "\x1b[4m",
-    red: "\x1b[31m",
-    green: "\x1b[32m",
-    yellow: "\x1b[33m",
-    blue: "\x1b[34m",
-    cyan: "\x1b[36m",
-    white: "\x1b[37m",
-    gray: "\x1b[90m",
+var c = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  underline: "\x1B[4m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  magenta: "\x1B[35m",
+  cyan: "\x1B[36m",
+  white: "\x1B[37m",
+  gray: "\x1B[90m"
 };
-// ─── Spinner ─────────────────────────────────────────────────────────────────
-const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-const spin = (() => {
-    let timer = null;
-    let frame = 0;
-    let label = "";
+function printErrorBox(title, reason, solution) {
+  const sep = `${c.red}${"\u2500".repeat(56)}${c.reset}`;
+  console.error(`
+${sep}`);
+  console.error(`  ${c.red}${c.bold}\u2716  ${title}${c.reset}`);
+  console.error(`  ${c.dim}${reason}${c.reset}`);
+  if (solution) {
+    console.error();
+    console.error(`  ${c.cyan}${c.bold}\u{1F4A1} How to fix:${c.reset}`);
+    const sols = Array.isArray(solution) ? solution : [solution];
+    for (const s of sols) {
+      console.error(`     ${s}`);
+    }
+  }
+  console.error(`${sep}
+`);
+}
+function printWarningBox(title, reason, tip) {
+  const sep = `${c.yellow}${"\u2500".repeat(56)}${c.reset}`;
+  console.warn(`
+${sep}`);
+  console.warn(`  ${c.yellow}${c.bold}\u26A0  ${title}${c.reset}`);
+  console.warn(`  ${c.dim}${reason}${c.reset}`);
+  if (tip) {
+    console.warn(`  ${c.cyan}${tip}${c.reset}`);
+  }
+  console.warn(`${sep}
+`);
+}
+function diagnoseNetworkError(err, serverUrl) {
+  const msg = err?.message || String(err);
+  if (msg.includes("ECONNREFUSED")) {
     return {
-        start(text) {
-            label = text;
-            frame = 0;
-            if (!process.stdout.isTTY) {
-                process.stdout.write(`  ${text}...\n`);
-                return;
-            }
-            timer = setInterval(() => {
-                const f = `${c.cyan}${FRAMES[frame % FRAMES.length]}${c.reset}`;
-                process.stdout.write(`\r  ${f}  ${c.dim}${label}${c.reset}   `);
-                frame++;
-            }, 80);
-        },
-        update(text) {
-            label = text;
-        },
-        stop(successMsg) {
-            if (timer) {
-                clearInterval(timer);
-                timer = null;
-            }
-            if (process.stdout.isTTY) {
-                process.stdout.write("\r\x1b[K"); // clear line
-            }
-            if (successMsg) {
-                console.log(`  ${c.green}✓${c.reset}  ${successMsg}`);
-            }
-        },
-        fail(errMsg) {
-            if (timer) {
-                clearInterval(timer);
-                timer = null;
-            }
-            if (process.stdout.isTTY)
-                process.stdout.write("\r\x1b[K");
-            console.error(`  ${c.red}✗${c.reset}  ${errMsg}`);
-        }
+      title: "Cannot connect to EdgeOTA server",
+      reason: `Server at ${c.bold}${serverUrl}${c.reset}${c.dim} refused the connection (ECONNREFUSED).`,
+      solution: [
+        `Ensure your EdgeOTA server is running: ${c.bold}lsof -i :3020${c.reset} or check your server process.`,
+        `Verify the server URL in ${c.bold}app.json${c.reset} or specify ${c.cyan}-s <url>${c.reset}`,
+        `If using USB physical device debugging, run ${c.cyan}adb reverse tcp:3020 tcp:3020${c.reset}`
+      ]
+    };
+  }
+  if (msg.includes("ETIMEDOUT") || msg.includes("timeout") || msg.includes("aborted")) {
+    return {
+      title: "Server request timed out",
+      reason: `Connection to ${c.bold}${serverUrl}${c.reset}${c.dim} exceeded timeout threshold.`,
+      solution: [
+        "Check your internet connection or local network routing.",
+        "Ensure your firewall or VPS security group permits traffic on this port."
+      ]
     };
+  }
+  return {
+    title: "Network request failed",
+    reason: msg,
+    solution: [
+      `Check your server URL: ${c.bold}${serverUrl}${c.reset}`,
+      `Verify internet connectivity and try again.`
+    ]
+  };
+}
+var FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var spin = /* @__PURE__ */ (() => {
+  let timer = null;
+  let frame = 0;
+  let label = "";
+  return {
+    start(text) {
+      label = text;
+      frame = 0;
+      if (!process.stdout.isTTY) {
+        process.stdout.write(`  ${text}...
+`);
+        return;
+      }
+      timer = setInterval(() => {
+        const f = `${c.cyan}${FRAMES[frame % FRAMES.length]}${c.reset}`;
+        process.stdout.write(`\r  ${f}  ${c.dim}${label}${c.reset}   `);
+        frame++;
+      }, 80);
+    },
+    update(text) {
+      label = text;
+    },
+    stop(successMsg) {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      if (process.stdout.isTTY) {
+        process.stdout.write("\r\x1B[K");
+      }
+      if (successMsg) {
+        console.log(`  ${c.green}\u2713${c.reset}  ${successMsg}`);
+      }
+    },
+    fail(errMsg) {
+      if (timer) {
+        clearInterval(timer);
+        timer = null;
+      }
+      if (process.stdout.isTTY) process.stdout.write("\r\x1B[K");
+      console.error(`  ${c.red}\u2717${c.reset}  ${errMsg}`);
+    }
+  };
 })();
-// ─── Package version ─────────────────────────────────────────────────────────
-let packageVersion = "0.3.0";
+var packageVersion = "0.4.0";
 try {
-    const pkgPath = path.join(__dirname, "..", "package.json");
-    if (fs.existsSync(pkgPath)) {
-        packageVersion = JSON.parse(fs.readFileSync(pkgPath, "utf8")).version;
-    }
+  const pkgPath = path.join(__dirname, "..", "package.json");
+  if (fs.existsSync(pkgPath)) {
+    packageVersion = JSON.parse(fs.readFileSync(pkgPath, "utf8")).version;
+  }
+} catch {
 }
-catch { /* fallback */ }
-// ─── Auto Update Check ────────────────────────────────────────────────────────
-const UPDATE_CHECK_FILE = path.join(GLOBAL_CONFIG_DIR, "update-check.json");
+var UPDATE_CHECK_FILE = path.join(GLOBAL_CONFIG_DIR, "update-check.json");
 function isNewerVersion(current, latest) {
-    const cParts = current.split(".").map(Number);
-    const lParts = latest.split(".").map(Number);
-    for (let i = 0; i < 3; i++) {
-        const cNum = cParts[i] || 0;
-        const lNum = lParts[i] || 0;
-        if (lNum > cNum)
-            return true;
-        if (lNum < cNum)
-            return false;
-    }
-    return false;
+  const cParts = current.split(".").map(Number);
+  const lParts = latest.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const cNum = cParts[i] || 0;
+    const lNum = lParts[i] || 0;
+    if (lNum > cNum) return true;
+    if (lNum < cNum) return false;
+  }
+  return false;
 }
 async function checkAndAutoUpdate() {
-    if (process.env.EDGE_OTA_UPDATING === "true")
-        return;
-    try {
-        const now = Date.now();
-        if (fs.existsSync(UPDATE_CHECK_FILE)) {
-            try {
-                const cache = JSON.parse(fs.readFileSync(UPDATE_CHECK_FILE, "utf-8"));
-                // Only check npm once every 15 minutes to keep CLI commands extremely fast
-                if (now - (cache.lastChecked || 0) < 15 * 60 * 1000) {
-                    return;
-                }
-            }
-            catch { /* ignore */ }
-        }
-        // Save timestamp immediately to prevent concurrent requests
-        fs.mkdirSync(GLOBAL_CONFIG_DIR, { recursive: true });
-        fs.writeFileSync(UPDATE_CHECK_FILE, JSON.stringify({ lastChecked: now }));
-        // Fetch latest version from registry with a short 1s timeout
-        const controller = new AbortController();
-        const timerId = setTimeout(() => controller.abort(), 1000);
-        const res = await fetch("https://registry.npmjs.org/@renbostudios/edge-ota/latest", {
-            signal: controller.signal
-        });
-        clearTimeout(timerId);
-        if (!res.ok)
-            return;
-        const data = (await res.json());
-        const latestVersion = data.version;
-        if (latestVersion && isNewerVersion(packageVersion, latestVersion)) {
-            console.log(`\n  ${c.yellow}${c.reset}  New version of ${c.bold}edge-ota${c.reset} available: ${c.green}${latestVersion}${c.reset} (current: ${c.dim}${packageVersion}${c.reset})`);
-            console.log(`  ${c.blue}➜${c.reset}  Auto-updating globally...`);
-            try {
-                execSync("npm install -g @renbostudios/edge-ota", {
-                    stdio: "inherit",
-                    env: { ...process.env, EDGE_OTA_UPDATING: "true" }
-                });
-                console.log(`  ${c.green}✓${c.reset}  Successfully auto-updated to ${c.bold}${latestVersion}${c.reset}!\n`);
-            }
-            catch (err) {
-                console.error(`  ${c.red}✗${c.reset}  Auto-update failed: ${err.message}`);
-                console.error(`     Please update manually: ${c.cyan}npm install -g @renbostudios/edge-ota${c.reset}\n`);
-            }
+  if (process.env.EDGE_OTA_UPDATING === "true") return;
+  try {
+    const now = Date.now();
+    if (fs.existsSync(UPDATE_CHECK_FILE)) {
+      try {
+        const cache = JSON.parse(fs.readFileSync(UPDATE_CHECK_FILE, "utf-8"));
+        if (now - (cache.lastChecked || 0) < 15 * 60 * 1e3) {
+          return;
         }
+      } catch {
+      }
     }
-    catch {
-        // Fail silently so CLI works offline
+    fs.mkdirSync(GLOBAL_CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(UPDATE_CHECK_FILE, JSON.stringify({ lastChecked: now }));
+    const controller = new AbortController();
+    const timerId = setTimeout(() => controller.abort(), 1e3);
+    const res = await fetch("https://registry.npmjs.org/@renbostudios/edge-ota/latest", {
+      signal: controller.signal
+    });
+    clearTimeout(timerId);
+    if (!res.ok) return;
+    const data = await res.json();
+    const latestVersion = data.version;
+    if (latestVersion && isNewerVersion(packageVersion, latestVersion)) {
+      console.log(`
+  ${c.yellow}\uF069${c.reset}  New version of ${c.bold}edge-ota${c.reset} available: ${c.green}${latestVersion}${c.reset} (current: ${c.dim}${packageVersion}${c.reset})`);
+      console.log(`  ${c.blue}\u279C${c.reset}  Auto-updating globally...`);
+      try {
+        execSync("npm install -g @renbostudios/edge-ota", {
+          stdio: "inherit",
+          env: { ...process.env, EDGE_OTA_UPDATING: "true" }
+        });
+        console.log(`  ${c.green}\u2713${c.reset}  Successfully auto-updated to ${c.bold}${latestVersion}${c.reset}!
+`);
+      } catch (err) {
+        console.error(`  ${c.red}\u2717${c.reset}  Auto-update failed: ${err.message}`);
+        console.error(`     Please update manually: ${c.cyan}npm install -g @renbostudios/edge-ota${c.reset}
+`);
+      }
     }
+  } catch {
+  }
 }
-// ─── Banner ───────────────────────────────────────────────────────────────────
 function printBanner() {
-    const sep = `${c.dim}${"─".repeat(52)}${c.reset}`;
-    console.log(`\n${sep}`);
-    console.log(`  ${c.bold}${c.white}edge-ota${c.reset}  ${c.dim}v${packageVersion} · Zero-SDK OTA for Expo${c.reset}`);
-    console.log(`  ${c.dim}by ${c.reset}${c.bold}Renbo Studios${c.reset}${c.dim} — Mobile App Development Studio${c.reset}`);
-    console.log(`  ${c.dim}renbostudios.com${c.reset}`);
-    console.log(`${sep}\n`);
+  const sep = `${c.dim}${"\u2500".repeat(56)}${c.reset}`;
+  console.log(`
+${sep}`);
+  console.log(`  ${c.bold}${c.white}edge-ota${c.reset}  ${c.dim}v${packageVersion} \xB7 Zero-SDK OTA for Expo${c.reset}`);
+  console.log(`  ${c.dim}by ${c.reset}${c.bold}Renbo Studios${c.reset}${c.dim} \u2014 Mobile App Development Studio${c.reset}`);
+  console.log(`  ${c.dim}renbostudios.com${c.reset}`);
+  console.log(`${sep}
+`);
 }
-// ─── app.json helpers ────────────────────────────────────────────────────────
-const DEFAULT_SERVER = "https://api.ota.renbo.site";
+var DEFAULT_SERVER = "https://api.ota.renbo.site";
 function readAppJson(cwd) {
-    const appJsonPath = path.resolve(cwd, "app.json");
-    if (!fs.existsSync(appJsonPath)) {
-        console.error(`\n  ${c.red}✗${c.reset}  ${c.bold}app.json not found${c.reset} in ${cwd}`);
-        console.error(`     Run this command from your Expo project root.\n`);
-        process.exit(1);
-    }
-    let data;
-    try {
-        data = JSON.parse(fs.readFileSync(appJsonPath, "utf-8"));
-    }
-    catch {
-        console.error(`  ${c.red}✗${c.reset}  Failed to parse app.json`);
-        process.exit(1);
-    }
-    const expo = data?.expo ?? {};
-    // ── Runtime version ──
-    let runtimeVersion = expo.runtimeVersion;
-    if (!runtimeVersion) {
-        console.error(`  ${c.red}✗${c.reset}  ${c.bold}expo.runtimeVersion${c.reset} is not set in app.json`);
-        console.error(`     Add: ${c.dim}"runtimeVersion": "1.0.0"${c.reset} under the expo key.\n`);
-        process.exit(1);
-    }
-    // Resolve runtimeVersion object (e.g. policy helper) to string
-    if (typeof runtimeVersion === "object" && runtimeVersion !== null) {
-        const policy = runtimeVersion.policy;
-        if (policy === "appVersion") {
-            runtimeVersion = expo.version;
-        }
-        else if (policy === "sdkVersion") {
-            runtimeVersion = expo.sdkVersion;
-        }
-        else {
-            runtimeVersion = expo.version || expo.sdkVersion;
-        }
-    }
-    if (!runtimeVersion || typeof runtimeVersion !== "string") {
-        console.error(`  ${c.red}✗${c.reset}  Could not resolve ${c.bold}expo.runtimeVersion${c.reset} to a valid string in app.json`);
-        if (typeof expo.runtimeVersion === "object") {
-            console.error(`     Since you are using a policy, please ensure either ${c.bold}expo.version${c.reset} or ${c.bold}expo.sdkVersion${c.reset} is defined.\n`);
-        }
-        process.exit(1);
-    }
-    // ── Updates URL ──
-    const updatesUrl = expo?.updates?.url ?? "";
-    if (!updatesUrl) {
-        console.error(`  ${c.red}✗${c.reset}  ${c.bold}expo.updates.url${c.reset} is not configured in app.json`);
-        console.error(`     Run ${c.cyan}edge-ota init${c.reset} to set this up.\n`);
-        process.exit(1);
-    }
-    // Parse serverUrl and projectId from the updates URL.
-    // Expected format: https://<host>/api/projects/<uuid>/updates
-    //              or: https://<host>/api/updates
-    let serverUrl;
-    let projectId = null;
-    try {
-        const u = new URL(updatesUrl);
-        const projectMatch = u.pathname.match(/\/api\/projects\/([^/]+)\/updates/);
-        if (projectMatch) {
-            projectId = projectMatch[1];
-            serverUrl = `${u.protocol}//${u.host}`;
-        }
-        else {
-            serverUrl = `${u.protocol}//${u.host}`;
-        }
-    }
-    catch {
-        console.error(`  ${c.red}✗${c.reset}  Could not parse ${c.dim}expo.updates.url${c.reset} in app.json`);
-        process.exit(1);
+  const appJsonPath = path.resolve(cwd, "app.json");
+  if (!fs.existsSync(appJsonPath)) {
+    printErrorBox(
+      "app.json not found",
+      `No app.json file located in directory: ${cwd}`,
+      [
+        `Ensure you are running edge-ota commands from the ${c.bold}root directory${c.reset} of your Expo project.`,
+        `If you use dynamic config (${c.dim}app.config.js / app.config.ts${c.reset}), create a base ${c.bold}app.json${c.reset} file with your Expo configuration.`
+      ]
+    );
+    process.exit(1);
+  }
+  let data;
+  try {
+    data = JSON.parse(fs.readFileSync(appJsonPath, "utf-8"));
+  } catch (parseErr) {
+    printErrorBox(
+      "Invalid app.json syntax",
+      `Failed to parse JSON in ${appJsonPath}: ${parseErr.message}`,
+      `Verify that app.json contains valid JSON syntax (no trailing commas, unclosed brackets, or unescaped quotes).`
+    );
+    process.exit(1);
+  }
+  const expo = data?.expo ?? {};
+  let runtimeVersion = expo.runtimeVersion;
+  if (!runtimeVersion) {
+    printErrorBox(
+      "Missing expo.runtimeVersion in app.json",
+      "Expo Updates requires a runtimeVersion to ensure native compatibility between the app binary and JS bundle.",
+      [
+        `Add a fixed version string in ${c.bold}app.json${c.reset} under ${c.dim}"expo"${c.reset}: ${c.cyan}"runtimeVersion": "1.0.0"${c.reset}`,
+        `Or use an Expo policy helper: ${c.cyan}"runtimeVersion": { "policy": "appVersion" }${c.reset}`
+      ]
+    );
+    process.exit(1);
+  }
+  if (typeof runtimeVersion === "object" && runtimeVersion !== null) {
+    const policy = runtimeVersion.policy;
+    if (policy === "appVersion") {
+      runtimeVersion = expo.version;
+    } else if (policy === "sdkVersion") {
+      runtimeVersion = expo.sdkVersion;
+    } else {
+      runtimeVersion = expo.version || expo.sdkVersion;
     }
-    // ── Project-level server override ──
-    // expo.extra.edgeOtaServer lets users point a specific project at a
-    // different (self-hosted) EdgeOTA instance without re-logging in.
-    const projectServer = expo?.extra?.edgeOtaServer;
-    if (projectServer) {
-        serverUrl = projectServer.replace(/\/$/, "");
+  }
+  if (!runtimeVersion || typeof runtimeVersion !== "string") {
+    printErrorBox(
+      "Could not resolve runtimeVersion",
+      `expo.runtimeVersion in app.json resolved to: ${JSON.stringify(runtimeVersion)}`,
+      [
+        `If using ${c.dim}"policy": "appVersion"${c.reset}, make sure ${c.bold}"expo.version"${c.reset} (e.g. "1.0.0") is defined in app.json.`,
+        `If using ${c.dim}"policy": "sdkVersion"${c.reset}, make sure ${c.bold}"expo.sdkVersion"${c.reset} (e.g. "52.0.0") is defined.`,
+        `Or simply specify a static string: ${c.cyan}"runtimeVersion": "1.0.0"${c.reset}`
+      ]
+    );
+    process.exit(1);
+  }
+  const updatesUrl = expo?.updates?.url ?? "";
+  if (!updatesUrl) {
+    printErrorBox(
+      "Missing expo.updates.url in app.json",
+      "Your app is not configured to receive updates from an EdgeOTA server.",
+      [
+        `Run ${c.cyan}edge-ota init${c.reset} in this directory to automatically configure your project.`,
+        `Or manually add under ${c.dim}"expo.updates"${c.reset}: ${c.cyan}"url": "https://api.ota.renbo.site/api/projects/<project-id>/updates"${c.reset}`
+      ]
+    );
+    process.exit(1);
+  }
+  let serverUrl;
+  let projectId = null;
+  try {
+    const u = new URL(updatesUrl);
+    const projectMatch = u.pathname.match(/\/api\/projects\/([^/]+)\/updates/);
+    if (projectMatch) {
+      projectId = projectMatch[1];
+      serverUrl = `${u.protocol}//${u.host}`;
+    } else {
+      serverUrl = `${u.protocol}//${u.host}`;
     }
-    return { serverUrl, projectId, runtimeVersion, publicKey: expo?.extra?.edgeOtaPublicKey };
+  } catch {
+    printErrorBox(
+      "Malformed expo.updates.url",
+      `The URL "${updatesUrl}" in app.json is not a valid HTTP/HTTPS URL.`,
+      `Run ${c.cyan}edge-ota init${c.reset} to generate a valid updates URL.`
+    );
+    process.exit(1);
+  }
+  const projectServer = expo?.extra?.edgeOtaServer;
+  if (projectServer) {
+    serverUrl = projectServer.replace(/\/$/, "");
+  }
+  return { serverUrl, projectId, runtimeVersion, publicKey: expo?.extra?.edgeOtaPublicKey };
 }
 function updateAppJson(cwd, serverUrl, projectId, publicKey) {
-    const appJsonPath = path.resolve(cwd, "app.json");
-    if (!fs.existsSync(appJsonPath))
-        return;
-    try {
-        const data = JSON.parse(fs.readFileSync(appJsonPath, "utf-8"));
-        if (!data.expo)
-            data.expo = {};
-        if (!data.expo.updates)
-            data.expo.updates = {};
-        if (!data.expo.extra)
-            data.expo.extra = {};
-        const cleanUrl = serverUrl.replace(/\/$/, "");
-        data.expo.updates.url = projectId
-            ? `${cleanUrl}/api/projects/${projectId}/updates`
-            : `${cleanUrl}/api/updates`;
-        data.expo.updates.checkAutomatically = data.expo.updates.checkAutomatically ?? "ON_LOAD";
-        data.expo.updates.fallbackToCacheTimeout = data.expo.updates.fallbackToCacheTimeout ?? 30000;
-        data.expo.updates.requestHeaders = data.expo.updates.requestHeaders ?? { "expo-channel-name": "production" };
-        // Store the server URL in expo.extra.edgeOtaServer so users can easily
-        // override which EdgeOTA instance this project points to without re-running
-        // `edge-ota login`. They can edit this value directly in app.json.
-        data.expo.extra.edgeOtaServer = cleanUrl;
-        if (publicKey) {
-            data.expo.extra.edgeOtaPublicKey = publicKey;
-        }
-        fs.writeFileSync(appJsonPath, JSON.stringify(data, null, 2) + "\n", "utf-8");
-        console.log(`  ${c.dim}app.json${c.reset}    updated ${c.dim}expo.updates.url${c.reset} + ${c.dim}expo.extra.edgeOtaServer${c.reset}`);
-    }
-    catch (e) {
-        console.error(`  ${c.yellow}⚠${c.reset}   Could not update app.json: ${e.message}`);
+  const appJsonPath = path.resolve(cwd, "app.json");
+  if (!fs.existsSync(appJsonPath)) return;
+  try {
+    const data = JSON.parse(fs.readFileSync(appJsonPath, "utf-8"));
+    if (!data.expo) data.expo = {};
+    if (!data.expo.updates) data.expo.updates = {};
+    if (!data.expo.extra) data.expo.extra = {};
+    const cleanUrl = serverUrl.replace(/\/$/, "");
+    data.expo.updates.url = projectId ? `${cleanUrl}/api/projects/${projectId}/updates` : `${cleanUrl}/api/updates`;
+    data.expo.updates.checkAutomatically = data.expo.updates.checkAutomatically ?? "ON_LOAD";
+    data.expo.updates.fallbackToCacheTimeout = data.expo.updates.fallbackToCacheTimeout ?? 3e4;
+    data.expo.updates.requestHeaders = data.expo.updates.requestHeaders ?? { "expo-channel-name": "production" };
+    data.expo.extra.edgeOtaServer = cleanUrl;
+    if (publicKey) {
+      data.expo.extra.edgeOtaPublicKey = publicKey;
     }
+    fs.writeFileSync(appJsonPath, JSON.stringify(data, null, 2) + "\n", "utf-8");
+    console.log(`  ${c.dim}app.json${c.reset}    updated ${c.dim}expo.updates.url${c.reset} + ${c.dim}expo.extra.edgeOtaServer${c.reset}`);
+  } catch (e) {
+    printWarningBox("Could not write to app.json", e.message, "Ensure app.json is writable.");
+  }
 }
-// ─── Readline helper ─────────────────────────────────────────────────────────
 function ask(query) {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise(resolve => rl.question(query, a => { rl.close(); resolve(a.trim()); }));
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(query, (a) => {
+    rl.close();
+    resolve(a.trim());
+  }));
 }
 function askSecret(query) {
-    return new Promise(resolve => {
-        if (process.stdin.isTTY) {
-            process.stdout.write(query);
-            let input = "";
-            process.stdin.setRawMode(true);
-            process.stdin.resume();
-            process.stdin.setEncoding("utf8");
-            process.stdin.on("data", function onData(ch) {
-                if (ch === "\r" || ch === "\n") {
-                    process.stdin.setRawMode(false);
-                    process.stdin.removeListener("data", onData);
-                    process.stdout.write("\n");
-                    resolve(input);
-                }
-                else if (ch === "\u0003") {
-                    process.exit(0);
-                }
-                else if (ch === "\u007f") {
-                    if (input.length > 0) {
-                        input = input.slice(0, -1);
-                        process.stdout.write("\b \b");
-                    }
-                }
-                else {
-                    input += ch;
-                    process.stdout.write("•");
-                }
-            });
-        }
-        else {
-            ask(query).then(resolve);
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) {
+      process.stdout.write(query);
+      let input = "";
+      process.stdin.setRawMode(true);
+      process.stdin.resume();
+      process.stdin.setEncoding("utf8");
+      process.stdin.on("data", function onData(ch) {
+        if (ch === "\r" || ch === "\n") {
+          process.stdin.setRawMode(false);
+          process.stdin.removeListener("data", onData);
+          process.stdout.write("\n");
+          resolve(input);
+        } else if (ch === "") {
+          process.exit(0);
+        } else if (ch === "\x7F") {
+          if (input.length > 0) {
+            input = input.slice(0, -1);
+            process.stdout.write("\b \b");
+          }
+        } else {
+          input += ch;
+          process.stdout.write("\u2022");
         }
-    });
+      });
+    } else {
+      ask(query).then(resolve);
+    }
+  });
 }
 function selectOption(question, options) {
-    return new Promise((resolve) => {
-        if (!process.stdin.isTTY) {
-            console.log(`  ${c.bold}${question}${c.reset}`);
-            options.forEach((opt, idx) => {
-                console.log(`  [${idx + 1}] ${opt.label}`);
-            });
-            ask(`  selection (1-${options.length}): `).then((choice) => {
-                const idx = parseInt(choice) - 1;
-                if (!isNaN(idx) && idx >= 0 && idx < options.length) {
-                    resolve(options[idx].value);
-                }
-                else {
-                    resolve(options[0].value);
-                }
-            });
-            return;
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) {
+      console.log(`  ${c.bold}${question}${c.reset}`);
+      options.forEach((opt, idx) => {
+        console.log(`  [${idx + 1}] ${opt.label}`);
+      });
+      ask(`  selection (1-${options.length}): `).then((choice) => {
+        const idx = parseInt(choice) - 1;
+        if (!isNaN(idx) && idx >= 0 && idx < options.length) {
+          resolve(options[idx].value);
+        } else {
+          resolve(options[0].value);
         }
-        let cursor = 0;
-        const hideCursor = "\u001b[?25l";
-        const showCursor = "\u001b[?25h";
-        let hasRendered = false;
-        console.log(`  ${c.bold}${question}${c.reset}`);
-        function render() {
-            if (hasRendered) {
-                for (let i = 0; i < options.length; i++) {
-                    process.stdout.write("\r\u001b[K\u001b[A");
-                }
-                process.stdout.write("\r\u001b[K");
-            }
-            hasRendered = true;
-            options.forEach((opt, idx) => {
-                const isSelected = idx === cursor;
-                const marker = isSelected ? `${c.cyan}❯${c.reset}` : " ";
-                const text = isSelected ? `${c.bold}${c.cyan}${opt.label}${c.reset}` : `${c.dim}${opt.label}${c.reset}`;
-                process.stdout.write(`  ${marker} ${text}\n`);
-            });
+      });
+      return;
+    }
+    let cursor = 0;
+    const hideCursor = "\x1B[?25l";
+    const showCursor = "\x1B[?25h";
+    let hasRendered = false;
+    console.log(`  ${c.bold}${question}${c.reset}`);
+    function render() {
+      if (hasRendered) {
+        for (let i = 0; i < options.length; i++) {
+          process.stdout.write("\r\x1B[K\x1B[A");
         }
-        readline.emitKeypressEvents(process.stdin);
-        process.stdin.setRawMode(true);
-        process.stdin.resume();
-        process.stdout.write(hideCursor);
+        process.stdout.write("\r\x1B[K");
+      }
+      hasRendered = true;
+      options.forEach((opt, idx) => {
+        const isSelected = idx === cursor;
+        const marker = isSelected ? `${c.cyan}\u276F${c.reset}` : " ";
+        const text = isSelected ? `${c.bold}${c.cyan}${opt.label}${c.reset}` : `${c.dim}${opt.label}${c.reset}`;
+        process.stdout.write(`  ${marker} ${text}
+`);
+      });
+    }
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdout.write(hideCursor);
+    render();
+    function onKeypress(str, key) {
+      if (key.ctrl && key.name === "c") {
+        process.stdout.write(showCursor);
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        process.exit(0);
+      }
+      if (key.name === "up" || key.name === "k") {
+        cursor = (cursor - 1 + options.length) % options.length;
         render();
-        function onKeypress(str, key) {
-            if (key.ctrl && key.name === "c") {
-                process.stdout.write(showCursor);
-                process.stdin.setRawMode(false);
-                process.stdin.pause();
-                process.exit(0);
-            }
-            if (key.name === "up" || key.name === "k") {
-                cursor = (cursor - 1 + options.length) % options.length;
-                render();
-            }
-            else if (key.name === "down" || key.name === "j") {
-                cursor = (cursor + 1) % options.length;
-                render();
-            }
-            else if (key.name === "return" || key.name === "enter") {
-                process.stdout.write(showCursor);
-                process.stdin.setRawMode(false);
-                process.stdin.removeListener("keypress", onKeypress);
-                process.stdin.pause();
-                resolve(options[cursor].value);
-            }
-        }
-        process.stdin.on("keypress", onKeypress);
-    });
+      } else if (key.name === "down" || key.name === "j") {
+        cursor = (cursor + 1) % options.length;
+        render();
+      } else if (key.name === "return" || key.name === "enter") {
+        process.stdout.write(showCursor);
+        process.stdin.setRawMode(false);
+        process.stdin.removeListener("keypress", onKeypress);
+        process.stdin.pause();
+        resolve(options[cursor].value);
+      }
+    }
+    process.stdin.on("keypress", onKeypress);
+  });
 }
-const CONTENT_TYPES = {
-    ".js": "application/javascript",
-    ".hbc": "application/javascript",
-    ".json": "application/json",
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".gif": "image/gif",
-    ".svg": "image/svg+xml",
-    ".ttf": "font/ttf",
-    ".otf": "font/otf",
-    ".woff": "font/woff",
-    ".woff2": "font/woff2",
-    ".mp4": "video/mp4",
-    ".webm": "video/webm",
+var CONTENT_TYPES = {
+  ".js": "application/javascript",
+  ".hbc": "application/javascript",
+  ".json": "application/json",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm"
 };
 async function hashFile(filePath) {
-    const buffer = fs.readFileSync(filePath);
-    return sha256Hex(buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength));
+  const buffer = fs.readFileSync(filePath);
+  return sha256Hex(buffer.buffer.slice(
+    buffer.byteOffset,
+    buffer.byteOffset + buffer.byteLength
+  ));
 }
 async function collectAssets(distDir) {
-    const entries = [];
-    function walk(dir) {
-        for (const name of fs.readdirSync(dir)) {
-            const full = path.join(dir, name);
-            if (fs.statSync(full).isDirectory()) {
-                walk(full);
-            }
-            else {
-                const ext = path.extname(name).toLowerCase();
-                entries.push({
-                    localPath: full,
-                    key: path.relative(distDir, full).replace(/\\/g, "/"),
-                    contentType: CONTENT_TYPES[ext] || "application/octet-stream",
-                    hash: ""
-                });
-            }
-        }
+  const entries = [];
+  function walk(dir) {
+    for (const name of fs.readdirSync(dir)) {
+      const full = path.join(dir, name);
+      if (fs.statSync(full).isDirectory()) {
+        walk(full);
+      } else {
+        const ext = path.extname(name).toLowerCase();
+        entries.push({
+          localPath: full,
+          key: path.relative(distDir, full).replace(/\\/g, "/"),
+          contentType: CONTENT_TYPES[ext] || "application/octet-stream",
+          hash: ""
+        });
+      }
     }
-    walk(distDir);
-    await Promise.all(entries.map(async (e) => { e.hash = await hashFile(e.localPath); }));
-    return entries;
+  }
+  walk(distDir);
+  await Promise.all(entries.map(async (e) => {
+    e.hash = await hashFile(e.localPath);
+  }));
+  return entries;
 }
 function findBundle(distDir, platform) {
-    const expoStaticJs = path.join(distDir, "_expo", "static", "js", platform);
-    if (fs.existsSync(expoStaticJs)) {
-        const files = fs.readdirSync(expoStaticJs).filter(f => f.endsWith(".js") || f.endsWith(".hbc"));
-        if (files.length)
-            return path.join(expoStaticJs, files[0]);
-    }
-    const flatJs = path.join(distDir, `index.${platform}.js`);
-    if (fs.existsSync(flatJs))
-        return flatJs;
-    const flatHbc = path.join(distDir, `index.${platform}.hbc`);
-    if (fs.existsSync(flatHbc))
-        return flatHbc;
-    const rootJs = fs.readdirSync(distDir).find(f => f.endsWith(".js") || f.endsWith(".hbc"));
-    if (rootJs)
-        return path.join(distDir, rootJs);
-    return null;
+  const expoStaticJs = path.join(distDir, "_expo", "static", "js", platform);
+  if (fs.existsSync(expoStaticJs)) {
+    const files = fs.readdirSync(expoStaticJs).filter((f) => f.endsWith(".js") || f.endsWith(".hbc"));
+    if (files.length) return path.join(expoStaticJs, files[0]);
+  }
+  const flatJs = path.join(distDir, `index.${platform}.js`);
+  if (fs.existsSync(flatJs)) return flatJs;
+  const flatHbc = path.join(distDir, `index.${platform}.hbc`);
+  if (fs.existsSync(flatHbc)) return flatHbc;
+  const rootJs = fs.readdirSync(distDir).find((f) => f.endsWith(".js") || f.endsWith(".hbc"));
+  if (rootJs) return path.join(distDir, rootJs);
+  return null;
 }
-// ─── Auth token resolution ────────────────────────────────────────────────────
 function resolveToken() {
-    // 1. Global config
-    const cfg = loadGlobalConfig();
-    if (cfg?.token)
-        return cfg.token;
-    // 2. Env var fallback
-    return process.env.EDGE_OTA_TOKEN || null;
+  const cfg = loadGlobalConfig();
+  if (cfg?.token) return cfg.token;
+  return process.env.EDGE_OTA_TOKEN || null;
 }
-// ─── Program ─────────────────────────────────────────────────────────────────
-const program = new Command();
-program
-    .name("edge-ota")
-    .description("Zero-SDK OTA update platform for Expo — by Renbo Studios")
-    .version(packageVersion);
-// Show help + auth status when called with no arguments
+var program = new Command();
+program.name("edge-ota").description("Zero-SDK, self-hostable OTA update platform for Expo \u2014 by Renbo Studios").version(packageVersion);
+program.addHelpText("after", `
+${c.bold}Quick Start:${c.reset}
+  1. ${c.cyan}edge-ota login${c.reset}                       Authenticate with EdgeOTA
+  2. ${c.cyan}edge-ota init${c.reset}                        Configure your Expo app and generate signing keys
+  3. ${c.cyan}npx expo prebuild --clean${c.reset}            Bake the server URL into native files (Required!)
+  4. ${c.cyan}edge-ota push${c.reset}                        Export and publish your first OTA update
+
+${c.bold}Documentation & Support:${c.reset}
+  Website:       https://ota.renbo.site
+  Studio:        https://renbostudios.com
+  GitHub:        https://github.com/renbostudios/edge-ota-cli
+`);
 program.action(() => {
-    printBanner();
-    const cfg = loadGlobalConfig();
-    if (cfg?.email) {
-        console.log(`  ${c.green}●${c.reset}  Logged in as ${c.bold}${cfg.email}${c.reset}  ${c.dim}(${cfg.serverUrl})${c.reset}`);
-    }
-    else {
-        console.log(`  ${c.dim}○  Not logged in — run ${c.reset}${c.cyan}edge-ota login${c.reset}`);
-    }
-    console.log();
-    console.log(`  ${c.bold}Commands${c.reset}`);
-    const cmds = [
-        ["login", "Authenticate and save credentials globally"],
-        ["logout", "Remove stored credentials"],
-        ["init", "Register project, generate signing keys, configure app.json"],
-        ["push", "Export bundle and publish an OTA update"],
-        ["status", "List recent deployments for this project"],
-        ["keygen", "Generate a new ECDSA key pair (prints to stdout)"],
-    ];
-    for (const [cmd, desc] of cmds) {
-        console.log(`  ${c.cyan}${cmd.padEnd(10)}${c.reset}  ${c.dim}${desc}${c.reset}`);
-    }
-    console.log();
-    console.log(`  Run ${c.cyan}edge-ota <command> --help${c.reset} for command-specific options.`);
-    console.log();
+  printBanner();
+  const cfg = loadGlobalConfig();
+  if (cfg?.email) {
+    console.log(`  ${c.green}\u25CF${c.reset}  Logged in as ${c.bold}${cfg.email}${c.reset}  ${c.dim}(${cfg.serverUrl})${c.reset}`);
+  } else {
+    console.log(`  ${c.dim}\u25CB  Not logged in \u2014 run ${c.reset}${c.cyan}edge-ota login${c.reset}`);
+  }
+  console.log();
+  console.log(`  ${c.bold}Commands${c.reset}`);
+  const cmds = [
+    ["login", "Authenticate and save credentials globally"],
+    ["logout", "Remove stored credentials"],
+    ["init", "Register project, generate signing keys, configure app.json"],
+    ["push", "Export bundle and publish an OTA update"],
+    ["status", "List recent deployments for this project"],
+    ["keygen", "Generate a new ECDSA key pair (prints to stdout)"]
+  ];
+  for (const [cmd, desc] of cmds) {
+    console.log(`  ${c.cyan}${cmd.padEnd(10)}${c.reset}  ${c.dim}${desc}${c.reset}`);
+  }
+  console.log();
+  console.log(`  Run ${c.cyan}edge-ota <command> --help${c.reset} for detailed command options and examples.`);
+  console.log();
 });
-// ──────────────────────────────────────────────────────────────────────────────
-// edge-ota login
-// ──────────────────────────────────────────────────────────────────────────────
-program
-    .command("login")
-    .description("Authenticate with your EdgeOTA account")
-    .option("-s, --server <url>", `EdgeOTA server URL (default: ${DEFAULT_SERVER})`)
-    .action(async (options) => {
-    printBanner();
-    const usingCustomServer = options.server && options.server !== DEFAULT_SERVER;
-    console.log(`  ${c.bold}Sign in to EdgeOTA${c.reset}`);
-    if (usingCustomServer) {
-        console.log(`  ${c.dim}server: ${options.server}${c.reset}`);
-    }
-    console.log();
-    const serverUrl = (options.server || DEFAULT_SERVER).replace(/\/$/, "");
-    const email = await ask(`  ${c.dim}email:${c.reset}    `);
-    const password = await askSecret(`  ${c.dim}password:${c.reset} `);
-    spin.start("authenticating");
-    try {
-        const res = await fetch(`${serverUrl}/api/auth/login`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ email, password }),
-        });
-        if (!res.ok) {
-            const text = await res.text();
-            spin.fail(`Login failed: ${text || res.statusText}`);
-            process.exit(1);
-        }
-        const data = await res.json();
-        saveGlobalConfig({ token: data.token, email: data.email, serverUrl });
-        spin.stop();
-        const sep = `${c.dim}${"─".repeat(52)}${c.reset}`;
-        console.log(sep);
-        console.log(`  ${c.green}✓${c.reset}  Logged in as ${c.bold}${data.email}${c.reset}`);
-        console.log(`  ${c.dim}credentials saved to ${GLOBAL_CONFIG_FILE}${c.reset}`);
-        console.log(sep + "\n");
-        process.exit(0);
-    }
-    catch (e) {
-        spin.fail(`Connection failed: ${e.message}`);
-        process.exit(1);
+program.command("login").description("Authenticate with your EdgeOTA account and save credentials globally").option("-s, --server <url>", "EdgeOTA server URL", DEFAULT_SERVER).addHelpText("after", `
+${c.bold}Examples:${c.reset}
+  $ ${c.cyan}edge-ota login${c.reset}                          Sign in to standard cloud service (${DEFAULT_SERVER})
+  $ ${c.cyan}edge-ota login -s http://localhost:3020${c.reset} Sign in to a self-hosted local server
+  $ ${c.cyan}edge-ota login -s https://ota.mycompany.com${c.reset} Sign in to a self-hosted custom domain
+
+${c.bold}CI/CD Environments:${c.reset}
+  Instead of interactive login, set the ${c.bold}EDGE_OTA_TOKEN${c.reset} environment variable:
+  $ ${c.cyan}export EDGE_OTA_TOKEN="eota_prod_..."${c.reset}
+`).action(async (options) => {
+  printBanner();
+  const usingCustomServer = options.server && options.server !== DEFAULT_SERVER;
+  console.log(`  ${c.bold}Sign in to EdgeOTA${c.reset}`);
+  if (usingCustomServer) {
+    console.log(`  ${c.dim}server: ${options.server}${c.reset}`);
+  }
+  console.log();
+  const serverUrl = (options.server || DEFAULT_SERVER).replace(/\/$/, "");
+  const email = await ask(`  ${c.dim}email:${c.reset}    `);
+  const password = await askSecret(`  ${c.dim}password:${c.reset} `);
+  spin.start("authenticating");
+  try {
+    const res = await fetch(`${serverUrl}/api/auth/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email, password })
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      spin.fail("Authentication failed");
+      if (res.status === 401) {
+        printErrorBox(
+          "Invalid email or password",
+          text || "The credentials provided were rejected by the server.",
+          [
+            `Check your email and password for typos.`,
+            `If you don't have an account yet, register at ${c.bold}https://ota.renbo.site${c.reset}`,
+            `If using self-hosted server, verify ${c.bold}${serverUrl}${c.reset} is correct.`
+          ]
+        );
+      } else if (res.status === 403) {
+        printErrorBox(
+          "Account email not verified",
+          text || "Your account email has not been verified.",
+          `Check your inbox for the verification OTP or log in to the dashboard to verify your email.`
+        );
+      } else {
+        printErrorBox(
+          `Server returned HTTP ${res.status}`,
+          text || res.statusText,
+          `Check server logs or try again shortly.`
+        );
+      }
+      process.exit(1);
     }
+    const data = await res.json();
+    saveGlobalConfig({ token: data.token, email: data.email, serverUrl });
+    spin.stop();
+    const sep = `${c.dim}${"\u2500".repeat(56)}${c.reset}`;
+    console.log(sep);
+    console.log(`  ${c.green}\u2713${c.reset}  Logged in as ${c.bold}${data.email}${c.reset}`);
+    console.log(`  ${c.dim}credentials saved to ${GLOBAL_CONFIG_FILE}${c.reset}`);
+    console.log(sep + "\n");
+    process.exit(0);
+  } catch (e) {
+    spin.fail("Connection failed");
+    const diag = diagnoseNetworkError(e, serverUrl);
+    printErrorBox(diag.title, diag.reason, diag.solution);
+    process.exit(1);
+  }
+});
+program.command("logout").description("Remove stored credentials and log out").addHelpText("after", `
+${c.bold}Details:${c.reset}
+  Deletes the global configuration file at ${c.dim}${GLOBAL_CONFIG_FILE}${c.reset}.
+  Project private signing keys in ${c.dim}${GLOBAL_KEYS_DIR}${c.reset} are preserved.
+`).action(() => {
+  printBanner();
+  const cfg = loadGlobalConfig();
+  clearGlobalConfig();
+  if (cfg?.email) {
+    console.log(`  ${c.green}\u2713${c.reset}  Logged out from ${c.bold}${cfg.email}${c.reset}
+`);
+  } else {
+    console.log(`  ${c.dim}Already logged out.${c.reset}
+`);
+  }
+  process.exit(0);
 });
-// ──────────────────────────────────────────────────────────────────────────────
-// edge-ota logout
-// ──────────────────────────────────────────────────────────────────────────────
-program
-    .command("logout")
-    .description("Remove stored credentials")
-    .action(() => {
-    printBanner();
-    const cfg = loadGlobalConfig();
-    clearGlobalConfig();
-    if (cfg?.email) {
-        console.log(`  ${c.green}✓${c.reset}  Logged out from ${c.bold}${cfg.email}${c.reset}\n`);
+program.command("init").description("Register project on EdgeOTA, generate signing keys, and configure app.json").option("-s, --server <url>", "EdgeOTA server URL (overrides logged-in server)").addHelpText("after", `
+${c.bold}What this command does:${c.reset}
+  1. Authenticates with your EdgeOTA server
+  2. Creates or links a project ID
+  3. Generates a cryptographic ECDSA P-256 code-signing keypair
+  4. Stores private key securely in ${c.dim}~/.config/edge-ota/keys/<projectId>.key${c.reset}
+  5. Updates ${c.bold}app.json${c.reset} with ${c.dim}expo.updates.url${c.reset} and public key
+
+${c.bold}Critical Next Step:${c.reset}
+  After running ${c.cyan}edge-ota init${c.reset}, you ${c.bold}MUST rebuild your native app${c.reset}:
+    $ ${c.cyan}npx expo prebuild --clean${c.reset}
+    $ ${c.cyan}npx expo run:android${c.reset}   (or ${c.cyan}npx expo run:ios${c.reset} / ${c.cyan}eas build${c.reset})
+`).action(async (options) => {
+  printBanner();
+  const token = resolveToken();
+  if (!token) {
+    printErrorBox(
+      "Not logged in",
+      "You must be authenticated to initialize a project.",
+      [
+        `Run ${c.cyan}edge-ota login${c.reset} to authenticate interactively.`,
+        `Or set ${c.cyan}export EDGE_OTA_TOKEN="eota_prod_..."${c.reset} in your environment.`
+      ]
+    );
+    process.exit(1);
+  }
+  const globalCfg = loadGlobalConfig();
+  const serverUrl = (options.server || globalCfg?.serverUrl || DEFAULT_SERVER).replace(/\/$/, "");
+  const cwd = process.cwd();
+  spin.start("fetching existing projects from server");
+  let projects = [];
+  try {
+    const res = await fetch(`${serverUrl}/api/projects`, {
+      headers: { Authorization: `Bearer ${token}` }
+    });
+    if (res.ok) {
+      projects = await res.json();
     }
-    else {
-        console.log(`  ${c.dim}Already logged out.${c.reset}\n`);
+    spin.stop();
+  } catch (e) {
+    spin.fail("Failed to fetch projects list");
+    const diag = diagnoseNetworkError(e, serverUrl);
+    printWarningBox(diag.title, diag.reason, "Proceeding with new project registration...");
+  }
+  let projectId = null;
+  let projectName = "";
+  if (projects.length > 0) {
+    const selectOptions = projects.map((p) => ({
+      label: `${p.name} ${c.dim}(id: ${p.id.slice(0, 8)}...)${c.reset}`,
+      value: p
+    }));
+    selectOptions.push({
+      label: `${c.green}+ Create a new project...${c.reset}`,
+      value: null
+    });
+    const selected = await selectOption(
+      "Select a project to associate with this app:",
+      selectOptions
+    );
+    if (selected) {
+      projectId = selected.id;
+      projectName = selected.name;
     }
-    process.exit(0);
-});
-// ──────────────────────────────────────────────────────────────────────────────
-// edge-ota init
-// ──────────────────────────────────────────────────────────────────────────────
-program
-    .command("init")
-    .description("Register project on EdgeOTA, generate signing keys, configure app.json")
-    .option("-s, --server <url>", "EdgeOTA server URL (overrides logged-in server)")
-    .action(async (options) => {
-    printBanner();
-    const token = resolveToken();
-    if (!token) {
-        console.error(`  ${c.red}✗${c.reset}  Not logged in. Run ${c.cyan}edge-ota login${c.reset} first.\n`);
+  }
+  const keys = await generateECDSAKeyPair();
+  if (projectId) {
+    spin.start(`associating project "${projectName}"`);
+    try {
+      const res = await fetch(`${serverUrl}/api/projects/${projectId}`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ name: projectName, publicKey: keys.publicKey })
+      });
+      if (!res.ok) {
+        const text = await res.text();
+        spin.fail("Failed to update project public key");
+        printErrorBox(
+          `Server returned HTTP ${res.status}`,
+          text,
+          `Ensure your user account has administrator or member permissions for project "${projectName}".`
+        );
         process.exit(1);
+      }
+      spin.stop(`associated project "${projectName}"`);
+    } catch (e) {
+      spin.fail("Connection error during project update");
+      const diag = diagnoseNetworkError(e, serverUrl);
+      printErrorBox(diag.title, diag.reason, diag.solution);
+      process.exit(1);
     }
-    const globalCfg = loadGlobalConfig();
-    const serverUrl = (options.server || globalCfg?.serverUrl || DEFAULT_SERVER).replace(/\/$/, "");
-    const cwd = process.cwd();
-    // Fetch existing projects
-    spin.start("fetching existing projects from server");
-    let projects = [];
+  } else {
+    let suggestedName = path.basename(cwd);
     try {
-        const res = await fetch(`${serverUrl}/api/projects`, {
-            headers: { Authorization: `Bearer ${token}` }
-        });
-        if (res.ok) {
-            projects = await res.json();
-        }
-        spin.stop();
-    }
-    catch (e) {
-        spin.fail(`Failed to fetch projects: ${e.message}`);
-        // Continue with creation if list fails
+      const data = JSON.parse(fs.readFileSync(path.resolve(cwd, "app.json"), "utf-8"));
+      suggestedName = data?.expo?.name || suggestedName;
+    } catch {
     }
-    let projectId = null;
-    let projectName = "";
-    if (projects.length > 0) {
-        const options = projects.map(p => ({
-            label: `${p.name} ${c.dim}(id: ${p.id.slice(0, 8)}...)${c.reset}`,
-            value: p
-        }));
-        options.push({
-            label: `${c.green}Create a new project...${c.reset}`,
-            value: null
-        });
-        const selected = await selectOption("Select a project to associate with this app:", options);
-        if (selected) {
-            projectId = selected.id;
-            projectName = selected.name;
-        }
-    }
-    const keys = await generateECDSAKeyPair();
-    if (projectId) {
-        // Re-initialize existing project: update public key on the server
-        spin.start(`associating project "${projectName}"`);
-        try {
-            const res = await fetch(`${serverUrl}/api/projects/${projectId}`, {
-                method: "PUT",
-                headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
-                body: JSON.stringify({ name: projectName, publicKey: keys.publicKey }),
-            });
-            if (!res.ok) {
-                const text = await res.text();
-                spin.fail(`Failed to update project public key on server: ${text}`);
-                process.exit(1);
-            }
-            spin.stop(`associated project "${projectName}"`);
-        }
-        catch (e) {
-            spin.fail(`Connection error: ${e.message}`);
-            process.exit(1);
-        }
+    projectName = await ask(`  ${c.dim}project name [${suggestedName}]:${c.reset} `) || suggestedName;
+    spin.start("registering project on server");
+    try {
+      const res = await fetch(`${serverUrl}/api/projects`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ name: projectName, publicKey: keys.publicKey })
+      });
+      if (!res.ok) {
+        const text = await res.text();
+        spin.fail("Failed to register project");
+        printErrorBox(
+          `Server returned HTTP ${res.status}`,
+          text,
+          `Check that your session token is valid and project name is acceptable.`
+        );
+        process.exit(1);
+      }
+      const data = await res.json();
+      projectId = data.id;
+      spin.stop("project registered");
+    } catch (e) {
+      spin.fail("Connection error during registration");
+      const diag = diagnoseNetworkError(e, serverUrl);
+      printErrorBox(diag.title, diag.reason, diag.solution);
+      process.exit(1);
     }
-    else {
-        // Create new project
-        let suggestedName = path.basename(cwd);
-        try {
-            const data = JSON.parse(fs.readFileSync(path.resolve(cwd, "app.json"), "utf-8"));
-            suggestedName = data?.expo?.name || suggestedName;
-        }
-        catch { /* ignore */ }
-        projectName = (await ask(`  ${c.dim}project name [${suggestedName}]:${c.reset} `)) || suggestedName;
-        spin.start("registering project on server");
-        try {
-            const res = await fetch(`${serverUrl}/api/projects`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
-                body: JSON.stringify({ name: projectName, publicKey: keys.publicKey }),
-            });
-            if (!res.ok) {
-                const text = await res.text();
-                spin.fail(`Failed to register project: ${text}`);
-                process.exit(1);
-            }
-            const data = await res.json();
-            projectId = data.id;
-            spin.stop("project registered");
+  }
+  if (projectId) {
+    savePrivateKey(projectId, keys.privateKey);
+    updateAppJson(cwd, serverUrl, projectId, keys.publicKey);
+    const sep = `${c.dim}${"\u2500".repeat(56)}${c.reset}`;
+    console.log(`
+${sep}`);
+    console.log(`  ${c.green}\u2713${c.reset}  ${c.bold}Initialised Successfully${c.reset}`);
+    console.log(sep);
+    console.log(`  project    ${c.dim}${projectId}${c.reset}`);
+    console.log(`  server     ${c.dim}${serverUrl}${c.reset}`);
+    console.log(`  key file   ${c.dim}${path.join(GLOBAL_KEYS_DIR, `${projectId}.key`)}${c.reset}`);
+    console.log(sep);
+    console.log(`
+${c.bold}${c.yellow}  \u26A0  REBUILD REQUIRED${c.reset}`);
+    console.log(sep);
+    console.log(`  ${c.bold}Your native app MUST be rebuilt for OTA updates${c.reset}`);
+    console.log(`  ${c.bold}to work.${c.reset} The server URL is baked into native`);
+    console.log(`  binary configurations at build time \u2014 not read dynamically from app.json.`);
+    console.log();
+    console.log(`  Run these commands in order:`);
+    console.log();
+    console.log(`    ${c.cyan}npx expo prebuild --clean${c.reset}`);
+    console.log(`    ${c.cyan}npx expo run:android${c.reset}  (or ${c.cyan}npx expo run:ios${c.reset})`);
+    console.log();
+    console.log(`  Or via EAS Build:`);
+    console.log(`    ${c.cyan}eas build --profile production${c.reset}`);
+    console.log();
+    console.log(`  ${c.red}Skipping this WILL cause "Failed to check for${c.reset}`);
+    console.log(`  ${c.red}update" errors on app launch.${c.reset}`);
+    console.log(sep + "\n");
+    console.log(`  Then run ${c.cyan}edge-ota push${c.reset} to publish your first update.
+`);
+    process.exit(0);
+  }
+});
+program.command("push").description("Export bundle, sign with ECDSA P-256, and publish an OTA update").option("-c, --channel <channel>", "Deployment channel", "production").option("-p, --platform <platform>", "Target platform: ios | android | all", "all").option("-r, --runtime <runtime>", "Override target runtime version (comma-separated for multi-runtime matrix, e.g. 1.0.0,1.0.1)").option("--skip-export", "Skip expo export (use existing ./dist directory)").option("--dry-run", "Build and sign payload locally without uploading").addHelpText("after", `
+${c.bold}Examples:${c.reset}
+  $ ${c.cyan}edge-ota push${c.reset}                               Publish update to 'production' channel
+  $ ${c.cyan}edge-ota push -c staging${c.reset}                    Publish update to 'staging' channel
+  $ ${c.cyan}edge-ota push -p android${c.reset}                    Publish to Android only
+  $ ${c.cyan}edge-ota push -r 1.0.5${c.reset}                      Override runtime version to 1.0.5
+  $ ${c.cyan}edge-ota push -r 1.0.0,1.0.1,2.0.0${c.reset}          Hotfix multiple native runtime versions simultaneously
+  $ ${c.cyan}edge-ota push --skip-export${c.reset}                 Deploy existing ./dist without re-running expo export
+  $ ${c.cyan}edge-ota push --dry-run${c.reset}                     Verify build, asset collection, and signature locally
+
+${c.bold}How It Works:${c.reset}
+  1. Runs ${c.dim}npx expo export${c.reset} to produce Hermes bytecode bundles (.hbc)
+  2. Discovers and uploads static media assets (.png, .jpg, .svg, .ttf, etc.)
+  3. Signs bundle hash with private key in ${c.dim}~/.config/edge-ota/keys/<projectId>.key${c.reset}
+  4. Publishes update to EdgeOTA server for instant client OTA sync
+`).action(async (options) => {
+  const cwd = process.cwd();
+  const token = resolveToken();
+  printBanner();
+  if (!token) {
+    printErrorBox(
+      "Not logged in",
+      "You must be authenticated to publish an OTA update.",
+      [
+        `Run ${c.cyan}edge-ota login${c.reset} to sign in to your EdgeOTA account.`,
+        `Or set ${c.cyan}export EDGE_OTA_TOKEN="eota_prod_..."${c.reset} in your environment (recommended for CI/CD).`
+      ]
+    );
+    process.exit(1);
+  }
+  const appCfg = readAppJson(cwd);
+  const { serverUrl, projectId } = appCfg;
+  const runtimeVersion = options.runtime || appCfg.runtimeVersion;
+  const privateKey = projectId ? loadPrivateKey(projectId) : null;
+  if (!privateKey) {
+    const keyPath = projectId ? path.join(GLOBAL_KEYS_DIR, `${projectId}.key`) : "unknown";
+    printErrorBox(
+      "No signing key found for this project",
+      `Expected private key file at: ${keyPath}`,
+      [
+        `Run ${c.cyan}edge-ota init${c.reset} to re-associate this project and generate a new keypair.`,
+        `If collaborating with a team, copy the project's private key into ${c.bold}${keyPath}${c.reset}`,
+        `Or generate keys manually using ${c.cyan}edge-ota keygen${c.reset}`
+      ]
+    );
+    process.exit(1);
+  }
+  const uploadUrl = projectId ? `${serverUrl}/api/projects/${projectId}/updates` : `${serverUrl}/api/updates`;
+  const distDir = path.resolve(cwd, "dist");
+  if (!options.skipExport) {
+    spin.start("running expo export");
+    await new Promise((resolve, reject) => {
+      const proc = spawn("npx", ["expo", "export"], {
+        cwd,
+        stdio: ["inherit", "pipe", "pipe"],
+        shell: process.platform === "win32"
+      });
+      proc.stdout?.on("data", (chunk) => {
+        const text = chunk.toString();
+        for (const line of text.split("\n")) {
+          const t = line.trim();
+          if (t.startsWith("_expo/static/js/") || t.match(/\.(hbc|js)\s+\(\d/)) {
+            spin.stop();
+            console.log(`  ${c.dim}${t}${c.reset}`);
+            spin.start("running expo export");
+          }
+          if (t.match(/Bundled \d+ms/)) {
+            spin.update("expo export \u2014 " + t.replace("Bundled", "").trim());
+          }
         }
-        catch (e) {
-            spin.fail(`Connection error: ${e.message}`);
-            process.exit(1);
+      });
+      let stderrBuf = "";
+      proc.stderr?.on("data", (chunk) => {
+        stderrBuf += chunk.toString();
+      });
+      proc.on("close", (code) => {
+        if (code === 0) {
+          spin.stop("expo export complete");
+          resolve();
+        } else {
+          spin.fail("expo export failed");
+          printErrorBox(
+            "Expo export failed",
+            `npx expo export exited with code ${code}`,
+            [
+              `Run ${c.bold}npx expo export${c.reset} directly in your terminal to see full Metro compiler logs.`,
+              `Check for TypeScript compiler errors, missing dependencies, or invalid asset imports.`,
+              `Recent stderr output:
+${c.dim}${stderrBuf.slice(-400).trim()}${c.reset}`
+            ]
+          );
+          reject(new Error(`expo export exited with code ${code}`));
         }
+      });
+    }).catch(() => process.exit(1));
+  } else {
+    console.log(`  ${c.dim}skip-export \u2014 using existing ./dist${c.reset}`);
+  }
+  if (!fs.existsSync(distDir)) {
+    printErrorBox(
+      "dist directory not found",
+      `Expected export output at ${distDir}`,
+      [
+        `Run ${c.cyan}edge-ota push${c.reset} without ${c.dim}--skip-export${c.reset} to automatically generate bundles.`,
+        `Or manually build using ${c.cyan}npx expo export${c.reset}`
+      ]
+    );
+    process.exit(1);
+  }
+  spin.start("collecting assets");
+  const assets = await collectAssets(distDir);
+  const mediaAssets = assets.filter((a) => !a.key.endsWith(".js") && !a.key.endsWith(".hbc"));
+  spin.stop(`found ${assets.length} total asset(s) (${mediaAssets.length} static assets)`);
+  if (mediaAssets.length > 0 && !options.dryRun) {
+    spin.start(`uploading ${mediaAssets.length} static asset(s)`);
+    try {
+      const assetForm = new FormData();
+      for (const ma of mediaAssets) {
+        const fileBuf = fs.readFileSync(ma.localPath);
+        assetForm.append("assets", new Blob([fileBuf], { type: ma.contentType }), path.basename(ma.localPath));
+      }
+      const assetUploadUrl = `${serverUrl}/api/assets/upload`;
+      const assetRes = await fetch(assetUploadUrl, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          ...projectId ? { "X-Project-Id": projectId } : {}
+        },
+        body: assetForm
+      });
+      if (assetRes.ok) {
+        spin.stop(`synced ${mediaAssets.length} static asset(s)`);
+      } else {
+        spin.stop(`asset sync notice: server returned HTTP ${assetRes.status}`);
+      }
+    } catch (assetErr) {
+      spin.stop(`asset sync: ${c.dim}${assetErr.message}${c.reset}`);
     }
-    // Save private key globally
-    if (projectId) {
-        savePrivateKey(projectId, keys.privateKey);
-        // Update app.json
-        updateAppJson(cwd, serverUrl, projectId, keys.publicKey);
-        const sep = `${c.dim}${"─".repeat(52)}${c.reset}`;
-        console.log(`\n${sep}`);
-        console.log(`  ${c.green}✓${c.reset}  ${c.bold}Initialised${c.reset}`);
-        console.log(sep);
-        console.log(`  project    ${c.dim}${projectId}${c.reset}`);
-        console.log(`  server     ${c.dim}${serverUrl}${c.reset}`);
-        console.log(`  key file   ${c.dim}${path.join(GLOBAL_KEYS_DIR, `${projectId}.key`)}${c.reset}`);
-        console.log(sep);
-        console.log(`\n${c.bold}${c.yellow}  ⚠  REBUILD REQUIRED${c.reset}`);
-        console.log(sep);
-        console.log(`  ${c.bold}Your native app MUST be rebuilt for OTA updates${c.reset}`);
-        console.log(`  ${c.bold}to work.${c.reset} The server URL is baked into the native`);
-        console.log(`  binary at build time — not read from app.json.`);
-        console.log();
-        console.log(`  Run these commands in order:`);
-        console.log();
-        console.log(`    ${c.cyan}npx expo prebuild --clean${c.reset}`);
-        console.log(`    ${c.cyan}npx expo run:ios${c.reset}`);
-        console.log(`    ${c.cyan}npx expo run:android${c.reset}`);
-        console.log();
-        console.log(`  Or via EAS:`);
-        console.log(`    ${c.cyan}eas build --profile production${c.reset}`);
-        console.log();
-        console.log(`  ${c.red}Skipping this WILL cause "Failed to check for${c.reset}`);
-        console.log(`  ${c.red}update" errors on app launch.${c.reset}`);
-        console.log(sep + "\n");
-        console.log(`  Then run ${c.cyan}edge-ota push${c.reset} to publish your first update.\n`);
-        process.exit(0);
-    }
-});
-// ──────────────────────────────────────────────────────────────────────────────
-// edge-ota push
-// ──────────────────────────────────────────────────────────────────────────────
-program
-    .command("push")
-    .description("Export your Expo bundle and publish an OTA update")
-    .option("-c, --channel <channel>", "Deployment channel", "production")
-    .option("-p, --platform <platform>", "Target platform: ios | android | all", "all")
-    .option("--skip-export", "Skip expo export (use existing ./dist directory)")
-    .option("--dry-run", "Build and sign the payload but do NOT upload")
-    .action(async (options) => {
-    const cwd = process.cwd();
-    const token = resolveToken();
-    printBanner();
-    if (!token) {
-        console.error(`  ${c.red}✗${c.reset}  Not logged in. Run ${c.cyan}edge-ota login${c.reset} first.`);
-        console.error(`     Or set ${c.dim}EDGE_OTA_TOKEN${c.reset} environment variable.\n`);
-        process.exit(1);
+  }
+  const platforms = options.platform === "all" ? ["ios", "android"] : [options.platform];
+  const sep = `${c.dim}${"\u2500".repeat(56)}${c.reset}`;
+  for (const platform of platforms) {
+    console.log(`
+${sep}`);
+    console.log(`  ${c.bold}${platform}${c.reset}`);
+    console.log(sep);
+    const bundlePath = findBundle(distDir, platform);
+    if (!bundlePath) {
+      printWarningBox(
+        `No bundle found for ${platform}`,
+        `Expected bundle at ./dist/_expo/static/js/${platform}/ or ./dist/index.${platform}.hbc`,
+        `If this platform is not supported in your app, ignore this or pass -p <platform>.`
+      );
+      continue;
     }
-    // Auto-detect from app.json
-    const appCfg = readAppJson(cwd);
-    const { serverUrl, projectId, runtimeVersion } = appCfg;
-    // Load private signing key
-    const privateKey = projectId ? loadPrivateKey(projectId) : null;
-    if (!privateKey) {
-        console.error(`  ${c.red}✗${c.reset}  No signing key found for this project.`);
-        if (projectId) {
-            console.error(`     Expected at: ${c.dim}${path.join(GLOBAL_KEYS_DIR, `${projectId}.key`)}${c.reset}`);
-        }
-        console.error(`     Run ${c.cyan}edge-ota init${c.reset} to set up code signing.\n`);
-        process.exit(1);
+    const bundleHash = await hashFile(bundlePath);
+    const bundleSize = (fs.statSync(bundlePath).size / 1024 / 1024).toFixed(2);
+    console.log(`  bundle     ${c.dim}${bundleHash.slice(0, 16)}\u2026  ${bundleSize} MB${c.reset}`);
+    const payloadObj = {
+      channel: options.channel,
+      runtimeVersion,
+      platform,
+      bundleHash,
+      timestamp: Date.now(),
+      assets: mediaAssets.map((a) => ({
+        hash: a.hash,
+        key: a.key,
+        fileExtension: path.extname(a.localPath),
+        contentType: a.contentType
+      })),
+      assetCount: mediaAssets.length,
+      publicKey: appCfg.publicKey
+    };
+    const payloadStr = JSON.stringify(payloadObj);
+    spin.start("signing bundle hash");
+    const signature = await signPayload(payloadStr, privateKey);
+    spin.stop(`signed  ${c.dim}${signature.slice(0, 20)}\u2026${c.reset}`);
+    if (options.dryRun) {
+      console.log(`  ${c.yellow}dry-run${c.reset}   upload skipped`);
+      continue;
     }
-    const uploadUrl = projectId
-        ? `${serverUrl}/api/projects/${projectId}/updates`
-        : `${serverUrl}/api/updates`;
-    const distDir = path.resolve(cwd, "dist");
-    // ── Step 1: Expo export ──────────────────────────────────────────────────
-    if (!options.skipExport) {
-        spin.start("running expo export");
-        await new Promise((resolve, reject) => {
-            const proc = spawn("npx", ["expo", "export"], {
-                cwd,
-                stdio: ["inherit", "pipe", "pipe"],
-                shell: process.platform === "win32",
-            });
-            // Filter stdout: only show platform bundle lines
-            proc.stdout?.on("data", (chunk) => {
-                const text = chunk.toString();
-                for (const line of text.split("\n")) {
-                    const t = line.trim();
-                    // Show platform bundle summary lines only
-                    if (t.startsWith("_expo/static/js/") || t.match(/\.(hbc|js)\s+\(\d/)) {
-                        spin.stop();
-                        console.log(`  ${c.dim}${t}${c.reset}`);
-                        spin.start("running expo export");
-                    }
-                    // Update spinner with bundling progress
-                    if (t.match(/Bundled \d+ms/)) {
-                        spin.update("expo export — " + t.replace("Bundled", "").trim());
-                    }
-                }
-            });
-            // Suppress stderr noise but capture real errors
-            let stderrBuf = "";
-            proc.stderr?.on("data", (chunk) => { stderrBuf += chunk.toString(); });
-            proc.on("close", code => {
-                if (code === 0) {
-                    spin.stop("expo export complete");
-                    resolve();
-                }
-                else {
-                    spin.fail("expo export failed");
-                    // Print last few lines of stderr for context
-                    const lines = stderrBuf.split("\n").filter(Boolean);
-                    for (const l of lines.slice(-10))
-                        console.error(`  ${c.dim}${l}${c.reset}`);
-                    reject(new Error(`expo export exited with code ${code}`));
-                }
-            });
-        }).catch(() => process.exit(1));
+    spin.start("uploading release to server");
+    const bundleBuffer = fs.readFileSync(bundlePath);
+    const form = new FormData();
+    form.append("bundle", new Blob([bundleBuffer], { type: "application/javascript" }), `bundle-${platform}.hbc`);
+    form.append("payload", payloadStr);
+    form.append("signature", signature);
+    form.append("platform", platform);
+    let response;
+    try {
+      response = await fetch(uploadUrl, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          ...projectId ? { "X-Project-Id": projectId } : {}
+        },
+        body: form
+      });
+    } catch (uploadNetErr) {
+      spin.fail("Upload connection failed");
+      const diag = diagnoseNetworkError(uploadNetErr, serverUrl);
+      printErrorBox(diag.title, diag.reason, diag.solution);
+      process.exit(1);
     }
-    else {
-        console.log(`  ${c.dim}skip-export — using existing ./dist${c.reset}`);
+    if (!response.ok) {
+      const text = await response.text();
+      spin.fail(`Upload failed (HTTP ${response.status})`);
+      if (response.status === 401) {
+        printErrorBox(
+          "Authentication expired",
+          "Your session token is no longer valid.",
+          `Run ${c.cyan}edge-ota login${c.reset} to refresh your credentials.`
+        );
+      } else if (response.status === 403) {
+        printErrorBox(
+          "Permission denied",
+          text || `You do not have permission to publish updates to project ${projectId}.`,
+          `Check your team role on ${c.bold}https://ota.renbo.site${c.reset} or verify API key permissions.`
+        );
+      } else if (response.status === 404) {
+        printErrorBox(
+          "Project not found on server",
+          `Project ID "${projectId}" was not found at ${serverUrl}.`,
+          `Run ${c.cyan}edge-ota init${c.reset} to re-associate with an existing project or create a new one.`
+        );
+      } else if (response.status === 413) {
+        printErrorBox(
+          "Payload too large",
+          "The bundle file exceeds server upload size limits.",
+          "Consider optimizing your bundle, removing large embedded media, or adjusting server body limit."
+        );
+      } else {
+        printErrorBox(`Server returned HTTP ${response.status}`, text, "Check server logs or try again shortly.");
+      }
+      process.exit(1);
     }
-    if (!fs.existsSync(distDir)) {
-        console.error(`  ${c.red}✗${c.reset}  ./dist not found after export\n`);
-        process.exit(1);
+    const body = await response.json().catch(() => ({}));
+    spin.stop("uploaded");
+    const runtimesDisplay = body.runtimeVersions ? body.runtimeVersions.join(", ") : runtimeVersion;
+    console.log(`  ${c.green}\u2713${c.reset}  deployed`);
+    console.log(`  id         ${c.dim}${body.updateId || "\u2014"}${c.reset}`);
+    console.log(`  channel    ${options.channel}`);
+    console.log(`  runtime(s) ${runtimesDisplay}`);
+    if (mediaAssets.length > 0) {
+      console.log(`  assets     ${mediaAssets.length} static asset(s) linked`);
     }
-    // ── Step 2: Collect assets ───────────────────────────────────────────────
-    spin.start("collecting assets");
-    const assets = await collectAssets(distDir);
-    spin.stop(`found ${assets.length} asset(s)`);
-    const platforms = options.platform === "all" ? ["ios", "android"] : [options.platform];
-    const sep = `${c.dim}${"─".repeat(52)}${c.reset}`;
-    // ── Step 3: Per-platform upload ──────────────────────────────────────────
-    for (const platform of platforms) {
-        console.log(`\n${sep}`);
-        console.log(`  ${c.bold}${platform}${c.reset}`);
-        console.log(sep);
-        const bundlePath = findBundle(distDir, platform);
-        if (!bundlePath) {
-            console.warn(`  ${c.yellow}⚠${c.reset}   no bundle found for ${platform}, skipping`);
-            continue;
-        }
-        const bundleHash = await hashFile(bundlePath);
-        const bundleSize = (fs.statSync(bundlePath).size / 1024 / 1024).toFixed(2);
-        console.log(`  bundle     ${c.dim}${bundleHash.slice(0, 16)}…  ${bundleSize} MB${c.reset}`);
-        const payloadObj = {
-            channel: options.channel,
-            runtimeVersion,
-            platform,
-            bundleHash,
-            timestamp: Date.now(),
-            assetCount: assets.length,
-            publicKey: appCfg.publicKey,
-        };
-        const payloadStr = JSON.stringify(payloadObj);
-        spin.start("signing");
-        const signature = await signPayload(payloadStr, privateKey);
-        spin.stop(`signed  ${c.dim}${signature.slice(0, 20)}…${c.reset}`);
-        if (options.dryRun) {
-            console.log(`  ${c.yellow}dry-run${c.reset}   upload skipped`);
-            continue;
-        }
-        spin.start("uploading");
-        const bundleBuffer = fs.readFileSync(bundlePath);
-        const form = new FormData();
-        form.append("bundle", new Blob([bundleBuffer], { type: "application/javascript" }), `bundle-${platform}.hbc`);
-        form.append("payload", payloadStr);
-        form.append("signature", signature);
-        form.append("platform", platform);
-        const response = await fetch(uploadUrl, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${token}`,
-                ...(projectId ? { "X-Project-Id": projectId } : {})
-            },
-            body: form,
-        }).catch(e => {
-            spin.fail(`Upload failed: ${e.message}`);
-            process.exit(1);
-        });
-        if (!response.ok) {
-            const text = await response.text();
-            spin.fail(`Upload failed (HTTP ${response.status}): ${text}`);
-            process.exit(1);
-        }
-        const body = await response.json().catch(() => ({}));
-        spin.stop("uploaded");
-        console.log(`  ${c.green}✓${c.reset}  deployed`);
-        console.log(`  id         ${c.dim}${body.updateId || "—"}${c.reset}`);
-        console.log(`  channel    ${options.channel}`);
-        console.log(`  runtime    ${runtimeVersion}`);
-    }
-    console.log(`\n${sep}`);
-    console.log(`  ${c.green}✓${c.reset}  ${c.bold}done${c.reset}  ${c.dim}update will be applied on next OTA sync${c.reset}`);
-    console.log(`${sep}\n`);
-    process.exit(0);
+  }
+  console.log(`
+${sep}`);
+  console.log(`  ${c.green}\u2713${c.reset}  ${c.bold}done${c.reset}  ${c.dim}update will be applied on next OTA sync${c.reset}`);
+  console.log(`${sep}
+`);
+  process.exit(0);
 });
-// ──────────────────────────────────────────────────────────────────────────────
-// edge-ota status
-// ──────────────────────────────────────────────────────────────────────────────
-program
-    .command("status")
-    .description("List recent deployments for this project")
-    .option("-n, --limit <n>", "Number of releases to show", "10")
-    .action(async (options) => {
-    printBanner();
-    const token = resolveToken();
-    if (!token) {
-        console.error(`  ${c.red}✗${c.reset}  Not logged in. Run ${c.cyan}edge-ota login${c.reset} first.\n`);
-        process.exit(1);
-    }
-    const cwd = process.cwd();
-    const appCfg = readAppJson(cwd);
-    const { serverUrl, projectId } = appCfg;
-    const headers = { Authorization: `Bearer ${token}` };
-    if (projectId)
-        headers["x-project-id"] = projectId;
-    spin.start("fetching releases");
-    const res = await fetch(`${serverUrl}/api/releases`, { headers }).catch(e => {
-        spin.fail(`Connection failed: ${e.message}`);
-        process.exit(1);
-    });
-    if (!res.ok) {
-        spin.fail(`Failed to fetch releases (HTTP ${res.status})`);
-        process.exit(1);
-    }
-    const releases = await res.json();
-    spin.stop();
-    if (!releases.length) {
-        console.log(`  ${c.dim}No releases found.${c.reset}\n`);
-        process.exit(0);
-    }
-    const limit = parseInt(options.limit);
-    const rows = releases.slice(0, limit).map((r) => ({
-        ID: r.id?.slice(0, 8) ?? "—",
-        Channel: r.channel ?? "—",
-        Runtime: r.runtime ?? "—",
-        Platform: r.platform ?? "all",
-        Created: r.created_at ? new Date(r.created_at).toLocaleString() : "—",
-    }));
-    console.table(rows);
+program.command("status").description("List recent deployments and active release status for this project").option("-n, --limit <n>", "Number of releases to show", "10").addHelpText("after", `
+${c.bold}Examples:${c.reset}
+  $ ${c.cyan}edge-ota status${c.reset}                         Show the last 10 releases
+  $ ${c.cyan}edge-ota status -n 25${c.reset}                   Show the last 25 releases
+`).action(async (options) => {
+  printBanner();
+  const token = resolveToken();
+  if (!token) {
+    printErrorBox(
+      "Not logged in",
+      "Authentication is required to query release status.",
+      `Run ${c.cyan}edge-ota login${c.reset} first.`
+    );
+    process.exit(1);
+  }
+  const cwd = process.cwd();
+  const appCfg = readAppJson(cwd);
+  const { serverUrl, projectId } = appCfg;
+  const headers = { Authorization: `Bearer ${token}` };
+  if (projectId) headers["x-project-id"] = projectId;
+  spin.start("fetching releases from server");
+  let res;
+  try {
+    res = await fetch(`${serverUrl}/api/releases`, { headers });
+  } catch (e) {
+    spin.fail("Connection failed");
+    const diag = diagnoseNetworkError(e, serverUrl);
+    printErrorBox(diag.title, diag.reason, diag.solution);
+    process.exit(1);
+  }
+  if (!res.ok) {
+    spin.fail(`Failed to fetch releases (HTTP ${res.status})`);
+    printErrorBox(
+      `Server returned HTTP ${res.status}`,
+      res.statusText,
+      `Verify that project "${projectId}" exists and your token has view permissions.`
+    );
+    process.exit(1);
+  }
+  const releases = await res.json();
+  spin.stop();
+  if (!releases.length) {
+    console.log(`  ${c.dim}No releases found for project "${projectId}".${c.reset}`);
+    console.log(`  Run ${c.cyan}edge-ota push${c.reset} to publish your first OTA release!
+`);
     process.exit(0);
+  }
+  const limit = parseInt(options.limit);
+  const rows = releases.slice(0, limit).map((r) => ({
+    ID: r.id?.slice(0, 8) ?? "\u2014",
+    Channel: r.channel ?? "\u2014",
+    Runtime: r.runtime ?? "\u2014",
+    Platform: r.platform ?? "all",
+    Created: r.created_at ? new Date(r.created_at).toLocaleString() : "\u2014"
+  }));
+  console.table(rows);
+  console.log();
+  process.exit(0);
 });
-// ──────────────────────────────────────────────────────────────────────────────
-// edge-ota keygen
-// ──────────────────────────────────────────────────────────────────────────────
-program
-    .command("keygen")
-    .description("Generate a fresh ECDSA P-256 key pair (prints to stdout, does not write files)")
-    .action(async () => {
-    const keys = await generateECDSAKeyPair();
-    const sep = `${c.dim}${"─".repeat(52)}${c.reset}`;
-    console.log(`\n${sep}`);
-    console.log(`  ${c.bold}private key${c.reset}  ${c.dim}keep secret — never commit${c.reset}`);
-    console.log(sep);
-    console.log(keys.privateKey);
-    console.log(`\n${sep}`);
-    console.log(`  ${c.bold}public key${c.reset}   ${c.dim}paste into dashboard → Settings → General${c.reset}`);
-    console.log(sep);
-    console.log(keys.publicKey);
-    process.exit(0);
+program.command("keygen").description("Generate a fresh ECDSA P-256 key pair for code signing").addHelpText("after", `
+${c.bold}What to do with these keys:${c.reset}
+  1. ${c.bold}Private Key:${c.reset} Store securely in ${c.dim}~/.config/edge-ota/keys/<projectId>.key${c.reset}
+     or set in your CI/CD secrets for automated pushes.
+  2. ${c.bold}Public Key:${c.reset}  Save in your project settings on the dashboard (${DEFAULT_SERVER})
+     or paste into ${c.dim}app.json${c.reset} under ${c.dim}expo.extra.edgeOtaPublicKey${c.reset}.
+`).action(async () => {
+  const keys = await generateECDSAKeyPair();
+  const sep = `${c.dim}${"\u2500".repeat(56)}${c.reset}`;
+  console.log(`
+${sep}`);
+  console.log(`  ${c.bold}PRIVATE KEY${c.reset}  ${c.red}(Keep Secret \u2014 Never Commit to Git)${c.reset}`);
+  console.log(sep);
+  console.log(keys.privateKey);
+  console.log(`
+${sep}`);
+  console.log(`  ${c.bold}PUBLIC KEY${c.reset}   ${c.green}(Paste into Dashboard \u2192 Settings \u2192 Code Signing)${c.reset}`);
+  console.log(sep);
+  console.log(keys.publicKey);
+  console.log(`${sep}
+`);
+  process.exit(0);
 });
 await checkAndAutoUpdate();
 program.parse(process.argv);