feat: self-heal Electron installs before dev and postinstall

Adds an Electron install check that repairs incomplete or wrong-architecture binaries
Runs the check during root postinstall and before electron dev startup
Adds tests and docs for the new ensure:electron workflow

packages/electron/scripts/electron-dev.mjs

@@ -45,6 +45,25 @@ function spawnProcess(command, args, options = {}) {
   });
 }
 
+function ensureElectronInstalled() {
+  // Electron's postinstall can silently fail to extract the binary under
+  // Node 24 (see ensure-electron.mjs). Fail fast with a repair attempt
+  // before wiring up the dev servers so the error is actionable.
+  const result = spawnSync('node', [path.join(__dirname, 'ensure-electron.mjs')], {
+    cwd: repoRoot,
+    stdio: 'inherit',
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(
+      '[electron:dev] electron binary is missing or incomplete and could not be repaired. ' +
+        'Run `bun run --cwd packages/electron ensure:electron` (or `bun install`) with a network connection.',
+    );
+  }
+}
+
 function runProcess(command, args, options = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, {
@@ -183,6 +202,8 @@ async function main() {
   let hmrApiPort = '';
   let hmrUiPort = '';
 
+  ensureElectronInstalled();
+
   if (useBundledUi) {
     await runProcess('bun', ['run', '--cwd', 'packages/electron', 'build:web-assets']);
   } else {