@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/e2e-testing/references/flakiness-playbook.md

@@ -0,0 +1,124 @@
+# flakiness-playbook — the 2026 patterns, reproduced and fixed
+
+A flaky test passes and fails on the same code. Industry flaky rates sit around 2–5%; a 3% rate on a
+40-minute pipeline costs roughly an engineer-day per week in reruns and erodes trust until people
+"just hit retry". Each pattern below has a named cause and a deterministic fix. **Open the trace
+first** — `npx playwright show-trace trace.zip` replays the failing run with DOM snapshots, network,
+and console, which turns a one-line CI log into an actual diagnosis.
+
+## 1. Auto-wait racing a re-render (read-once assertion)
+
+The element exists when you read it, but the async update lands a frame later.
+
+```ts
+// Repro — captures one frame; flakes when the fetch resolves after the read.
+const total = await page.locator('#total').textContent();
+expect(total).toBe('$42.00');
+
+// Fix — web-first assertion re-polls until the text matches or times out.
+await expect(page.getByTestId('total')).toHaveText('$42.00');
+```
+
+## 2. Route handler registered after `goto`
+
+The first request fires before the mock is in place, so it hits the network unmocked.
+
+```ts
+// Repro — initial /api/orders already went out by the time the route is set.
+await page.goto('/orders');
+await page.route('**/api/orders', r => r.fulfill({ json: orders }));
+
+// Fix — register before navigation; now the first request is intercepted.
+await page.route('**/api/orders', r => r.fulfill({ json: orders }));
+await page.goto('/orders');
+```
+
+## 3. `networkidle` never settling in an SPA
+
+SPAs with polling, websockets, or analytics beacons keep the network busy forever, so
+`waitUntil: 'networkidle'` hangs until timeout.
+
+```ts
+// Repro — hangs because a heartbeat poll keeps the connection alive.
+await page.goto('/dashboard', { waitUntil: 'networkidle' });
+
+// Fix — wait on a concrete UI signal instead of network silence.
+await page.goto('/dashboard');
+await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+```
+
+## 4. `waitForResponse` subscribed too late
+
+If you `await` the action and only then wait for the response, the event already fired.
+
+```ts
+// Repro — the click's response can resolve before the listener attaches.
+await page.getByRole('button', { name: 'Save' }).click();
+const res = await page.waitForResponse('**/api/save'); // may hang or catch the wrong call
+
+// Fix — start waiting first, then act, then await the promise.
+const resPromise = page.waitForResponse('**/api/save');
+await page.getByRole('button', { name: 'Save' }).click();
+const res = await resPromise;
+expect(res.ok()).toBeTruthy();
+```
+
+## 5. Strict-mode violation ("resolved to 2 elements")
+
+A locator matches more than one node. The throw is correct — your selector is ambiguous.
+
+```ts
+// Repro — two "Delete" buttons on the page.
+await page.getByRole('button', { name: 'Delete' }).click(); // throws in strict mode
+
+// Fix — scope to the row, do not paper over it with .first().
+await page
+  .getByRole('row', { name: 'Invoice 1024' })
+  .getByRole('button', { name: 'Delete' })
+  .click();
+```
+
+## 6. `storageState` leakage between tests/roles
+
+Sharing one mutated session file across roles, or letting one test's writes bleed into the next.
+
+- One state file per role: `admin.json`, `member.json`, `anon` (none).
+- Regenerate every CI run; gitignore `playwright/.auth/`.
+- Playwright already gives each test a fresh `BrowserContext` (cookies/storage reset). If state leaks
+  between tests, the cause is a shared fixture or committed state — not the framework.
+
+## 7. `test.use()` scope confusion
+
+`test.use({...})` applies to its whole file or `describe` block. Setting it at the top when only one
+test needs the override silently changes siblings.
+
+```ts
+test.describe('mobile checkout', () => {
+  test.use({ viewport: { width: 390, height: 844 } }); // scoped to this block only
+  test('completes on a phone viewport', async ({ page }) => { /* ... */ });
+});
+```
+
+## 8. Headed-vs-headless drift
+
+Green when watched, red in CI (or vice-versa). Usually viewport size, animation timing, or font
+rendering differences.
+
+- Pin `viewport` in the config so headed and headless agree.
+- Disable animations for determinism: `use: { ...devices['Desktop Chrome'] }` plus a global
+  `* { animation: none !important; transition: none !important; }` style, or
+  `await page.emulateMedia({ reducedMotion: 'reduce' })`.
+- Reproduce in the mode that fails: run CI's exact command headless locally, or
+  `npx playwright test --headed --project=chromium` to watch a headed-only failure.
+
+## Trace-viewer workflow
+
+1. CI uploads the trace (config has `trace: 'on-first-retry'`).
+2. Download the artifact, then `npx playwright show-trace path/to/trace.zip`.
+3. Step the timeline: inspect the DOM snapshot at the failing action, the network tab for the
+   missed/late request, and the console for errors.
+4. Reproduce locally with `--repeat-each=20` (or `--shard` parity) to measure the flake as a rate.
+5. Fix the cause from the table above; confirm the rate hits zero, not merely lower.
+
+When a flake survives this, hand the trace to `../debug/SKILL.md`: turn it into a measured k/N rate,
+isolate one variable at a time, fix the cause, and add the test that proves it gone.

package/skills/shared/e2e-testing/scripts/verify.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+#
+# verify.sh - read-only static lint for emitted Playwright test/config text.
+#
+# Usage:
+#   /path/to/verify.sh [TARGET_DIR]   # defaults to .
+#
+# Greps the produced .ts/.js/.mjs/.cts test+config text for this skill's banlist.
+# NO browser run, NO network, NO writes. Pure string checks.
+#
+# Banlist (each is a flake/anti-pattern this skill teaches against):
+#   1. waitForTimeout(            -> sleep-based wait
+#   2. xpath= or raw // locators  -> brittle XPath
+#   3. page.$(  / page.$$(        -> legacy element handles over locators
+#   4. expect(await              -> read-once assertion smell
+#   5. a playwright.config.* that lacks BOTH `trace` and `retries`
+#
+# Exit codes: 0 = clean OR nothing to check (empty/clean target);
+#             1 = a banned pattern was found.
+
+set -euo pipefail
+
+target="${1:-.}"
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+
+if [ ! -d "$target" ]; then
+  printf '%serror:%s target dir not found: %s\n' "$RED" "$RESET" "$target" >&2
+  exit 2
+fi
+
+# Count candidate source files up front so an empty/clean target exits cleanly.
+# Skip node_modules and Playwright's own output/report dirs - lint authored code only.
+find_sources() {
+  find "$target" \
+    \( -name node_modules -o -name '.git' -o -name 'playwright-report' \
+       -o -name 'blob-report' -o -name 'test-results' \) -prune -o \
+    -type f \( -name '*.ts' -o -name '*.js' -o -name '*.mjs' -o -name '*.cts' \) -print0 \
+    2>/dev/null
+}
+
+if [ "$(find_sources | tr -dc '\0' | wc -c)" -eq 0 ]; then
+  skip "no .ts/.js test or config files under $target - nothing to lint (clean pass)"
+  exit 0
+fi
+
+failed=0
+checked=0
+
+# grep -n on a single file; report each hit indented. Returns 0 if a hit found.
+flag() { # $1 = pattern (fixed string), $2 = file, $3 = message
+  local hits
+  hits=$(grep -nF -- "$1" "$2" 2>/dev/null || true)
+  if [ -n "$hits" ]; then
+    fail "$3 in $2"
+    printf '%s\n' "$hits" | sed 's/^/        /'
+    failed=1
+  fi
+}
+
+# Regex variant (for XPath // and page.$/$$ shapes).
+flag_re() { # $1 = ERE pattern, $2 = file, $3 = message
+  local hits
+  hits=$(grep -nE -- "$1" "$2" 2>/dev/null || true)
+  if [ -n "$hits" ]; then
+    fail "$3 in $2"
+    printf '%s\n' "$hits" | sed 's/^/        /'
+    failed=1
+  fi
+}
+
+while IFS= read -r -d '' file; do
+  checked=$((checked + 1))
+
+  # 1. sleep-based waits
+  flag 'waitForTimeout(' "$file" "waitForTimeout (sleep-based wait)"
+
+  # 2. XPath: explicit xpath= engine, or a locator string beginning with //
+  flag 'xpath=' "$file" "xpath= locator engine"
+  flag_re "(locator|getByTestId|click|fill)\([\"'\`]//" "$file" "raw // XPath locator"
+
+  # 3. legacy element handles
+  flag_re "page\.\\\$\\\$?\(" "$file" "page.\$ / page.\$\$ element handle (use locators)"
+
+  # 4. read-once assertion smell
+  flag 'expect(await ' "$file" "expect(await ...) read-once assertion"
+
+  # 5. config files must declare both trace and retries
+  case "$file" in
+    *playwright.config.*)
+      has_trace=$(grep -c 'trace' "$file" 2>/dev/null || true)
+      has_retries=$(grep -c 'retries' "$file" 2>/dev/null || true)
+      if [ "${has_trace:-0}" -eq 0 ] || [ "${has_retries:-0}" -eq 0 ]; then
+        fail "playwright config missing trace and/or retries: $file"
+        failed=1
+      else
+        ok "config declares trace + retries: $file"
+      fi
+      ;;
+  esac
+done < <(find_sources)
+
+if [ "$failed" -ne 0 ]; then
+  printf '%sverify failed:%s banned Playwright anti-patterns above.%s\n' "$RED" "$RESET" "$RESET" >&2
+  exit 1
+fi
+
+printf '%s[ ok ] %d file(s) lint clean - no banned e2e anti-patterns.%s\n' "$GREEN" "$checked" "$RESET"
+exit 0

package/skills/shared/electron/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: electron
+description: "Use when building, hardening, or shipping a cross-platform Electron desktop app — main/renderer/preload process model, typed contextBridge IPC, locking down nodeIntegration/contextIsolation/sandbox/CSP, or packaging with signing and auto-update. NOT a Rust-backed shell on the native webview (that is tauri), nor the web UI inside it (that is react)."
+tags: [electron, desktop, ipc, security, packaging, auto-update, code-signing]
+recommends: [tauri, react, nodejs, github-actions, secure-coding]
+origin: ai-hub
+---
+
+# Electron — desktop shell, typed IPC, hardening, signing
+
+This skill owns the **desktop shell**: process model, IPC, security, packaging, signing,
+auto-update. It does **not** own the web UI inside the window (`../react/SKILL.md`), the
+Node backend logic, or the CI runner matrix.
+
+## The mental model — three processes, one rule
+
+An Electron app is three kinds of process. Code lives in exactly one; putting it in the
+wrong one is the root cause of most security holes.
+
+| Process  | Runtime              | Trust         | One per | Does                                              |
+|----------|----------------------|---------------|---------|---------------------------------------------------|
+| main     | Node.js, full OS API | trusted       | app     | windows, menus, tray, dialogs, fs, child procs    |
+| renderer | Chromium, no Node    | **untrusted** | window  | your web UI; can run attacker JS if you load remote content |
+| preload  | isolated world, runs before page JS | semi-trusted | window | the **only** bridge: `contextBridge` exposes a tiny API |
+
+**The governing rule: the renderer is untrusted, the main process holds all privilege, and
+the preload is the only sanctioned bridge between them.** Renderer-to-OS escalation is the
+dominant failure mode in real Electron apps, so everything below is a corollary.
+
+## Start right
+
+Scaffold with **Electron Forge** (`@electron/forge`) — first-party, all-in-one
+(scaffold → package → make → publish), and it gets new Electron features first.
+
+```bash
+npm init electron-app@latest my-app -- --template=vite-typescript
+cd my-app && npm start
+```
+
+**Pin to a supported major.** Electron ships a new major every 8 weeks (tracking Chromium)
+and supports only the **latest 3 majors**. As of June 2026 the stable line is **Electron 42**
+(Chromium M148, Node 24); 43 lands 2026-06-30. Shipping on an EOL major means unpatched
+Chromium CVEs — check `package.json` and bump if behind.
+
+Project layout keeps the boundary visible:
+
+```text
+src/
+  main.ts       # main process — owns everything privileged
+  preload.ts    # the bridge — contextBridge only
+  renderer/     # your web UI (untrusted)
+  ipc/types.ts  # IPC contract shared by main + preload
+```
+
+## The security baseline
+
+Modern Electron defaults are already secure (`nodeIntegration:false`,
+`contextIsolation:true`, `sandbox:true` since Electron 20). **Assert them explicitly anyway**
+so a careless edit can't silently weaken the window:
+
+```ts
+const win = new BrowserWindow({
+  webPreferences: {
+    preload: path.join(__dirname, 'preload.js'),
+    nodeIntegration: false,        // renderer gets NO require/process — never flip true
+    contextIsolation: true,        // preload + page run in separate JS worlds
+    sandbox: true,                 // renderer in an OS sandbox; preload uses a limited API
+    webSecurity: true,             // keep same-origin policy; never disable to "fix CORS"
+    allowRunningInsecureContent: false, // no mixed http content on https pages
+  },
+});
+```
+
+One why per flag: each removes a documented way for renderer-side script to reach Node or
+the OS. Flipping any of them to the insecure value is what `verify.sh` fails on.
+
+**CSP via response headers, not a `<meta>` tag** — meta CSP can't restrict the initial
+document and is trivially bypassed for some directives. Set it in the main process:
+
+```ts
+session.defaultSession.webRequest.onHeadersReceived((details, cb) => {
+  cb({ responseHeaders: { ...details.responseHeaders,
+    'Content-Security-Policy': ["default-src 'self'; script-src 'self'"] } });
+});
+```
+
+**Lock navigation.** A renderer that can navigate to attacker content gets the renderer's
+privileges. Deny unexpected navigation and block new windows:
+
+```ts
+app.on('web-contents-created', (_e, contents) => {
+  contents.on('will-navigate', (e, url) => {
+    if (new URL(url).origin !== 'https://app.local') e.preventDefault();
+  });
+  contents.setWindowOpenHandler(() => ({ action: 'deny' })); // no tab-jacking
+});
+```
+
+Open real external links deliberately, after allow-listing the protocol:
+
+```ts
+function openExternal(url: string) {
+  const { protocol } = new URL(url);
+  if (protocol === 'https:' || protocol === 'mailto:') shell.openExternal(url);
+}
+```
+
+**Which branch are you on?**
+
+- **Local-only UI** (you bundle the HTML/JS): CSP + `sandbox:true` + nav lockdown is enough.
+- **Loads any remote/third-party content**: also add Electron Fuses (disable run-as-node,
+  encrypt cookies, ASAR integrity) and treat every embedded origin as hostile.
+
+Fuses and the full hardened example live in `references/security-and-ipc.md`.
+
+## Typed IPC the right way
+
+IPC is the seam between untrusted renderer and privileged main. Get it wrong and you've
+handed the OS to whatever script runs in the page.
+
+**Never expose `ipcRenderer` (or any of its methods) across the bridge.** Sending the whole
+module now yields an *empty object* on the other side — a deliberate footgun removal — and
+exposing its methods lets the page call any channel with any payload.
+
+```ts
+// Bad — preload.ts: hands the renderer a universal IPC weapon (also: empty object now)
+contextBridge.exposeInMainWorld('api', ipcRenderer);
+```
+
+```ts
+// Good — preload.ts: ONE function per channel, each wrapping a specific call
+import { contextBridge, ipcRenderer } from 'electron';
+contextBridge.exposeInMainWorld('api', {
+  readConfig: () => ipcRenderer.invoke('config:read'),
+  saveNote: (text: string) => ipcRenderer.invoke('note:save', text),
+  onSync: (cb: () => void) => ipcRenderer.on('sync:done', cb), // events: send/on
+});
+```
+
+**Prefer `ipcMain.handle` + `ipcRenderer.invoke`** (request/response, returns a Promise) for
+anything that returns data. Reserve `send`/`on` for fire-and-forget events (progress, push
+notifications). **Validate every argument in main** — a renderer message is an HTTP request
+from an untrusted client:
+
+```ts
+ipcMain.handle('note:save', (_e, text: unknown) => {
+  if (typeof text !== 'string' || text.length > 10_000) throw new Error('bad input');
+  return saveNote(text); // never path.join(userInput) or eval it
+});
+```
+
+Share the contract as TypeScript types across both sides (`ipc/types.ts`) so a channel
+rename breaks the build, not production. Full main + preload + `window.api` d.ts example:
+`references/security-and-ipc.md`.
+
+## Native capabilities — renderer asks, main acts
+
+The renderer can't (and must not) touch the OS directly. When the UI needs a native menu,
+tray icon, file dialog, system notification, custom `protocol://` handler, or a
+`child_process`, the renderer **invokes an IPC channel** and the **main process performs the
+action** and returns a result. Same one-function-per-channel discipline as above.
+
+For embedding web content in a region of a window, use **`WebContentsView`** —
+`BrowserView` is deprecated since Electron 30. They share shape (both take `webPreferences`;
+`setBounds`/`getBounds`/`webContents` carry over), so migration is mechanical.
+
+## Packaging, signing, auto-update
+
+Two real toolchains:
+
+| Need                                            | Use              |
+|-------------------------------------------------|------------------|
+| New app, first-party alignment, features first  | **Electron Forge** (ASAR integrity, universal macOS, scaffold→make→publish) |
+| Differential/staged updates, multi-provider (GitHub/S3), richer config | **electron-builder** + `electron-updater` |
+
+**Code signing is a prerequisite for auto-update, not optional polish.** macOS auto-update
+(Squirrel.Mac) **refuses** to update an app that isn't signed *and* notarized; Windows
+updates need an Authenticode-signed installer. So the order is always: sign → notarize →
+publish → auto-update. Full Forge and builder configs, notarytool steps, Windows
+Authenticode, and `electron-updater` + GitHub Releases wiring: `references/packaging-and-updates.md`.
+
+The CI matrix that *runs* these builds across three OSes is `github-actions`' job; this skill
+defines *what* to build and sign.
+
+## Anti-patterns and migration smells
+
+| Anti-pattern                                          | Why it's wrong                                              | Do instead                                            |
+|-------------------------------------------------------|------------------------------------------------------------|-------------------------------------------------------|
+| `nodeIntegration: true`                               | Page JS gets `require('fs')`; any XSS becomes OS-level RCE | `false`; move the capability behind IPC               |
+| `contextIsolation: false`                             | Page can rewrite the preload's globals                     | `true` (the default)                                  |
+| `sandbox: false` without a reason                     | Drops the OS sandbox around the renderer                   | `true`; only relax for a measured, isolated need      |
+| `exposeInMainWorld('api', ipcRenderer)` or its methods | Universal IPC weapon — any channel, any payload (and an empty object now) | One typed function per channel        |
+| No arg validation in `ipcMain.handle`                 | Renderer is an untrusted client; you trust its input       | Type-check + bound every arg before acting            |
+| `webSecurity: false` to "fix CORS"                    | Disables same-origin policy app-wide                       | Keep `true`; proxy/handle CORS in main                |
+| CSP only in a `<meta>` tag                            | Doesn't cover the initial document; bypassable             | Set CSP in `onHeadersReceived`                         |
+| Loading a remote URL into a Node-enabled window       | Remote site runs with your app's privilege                 | Bundle UI locally; sandbox + nav lockdown for remote  |
+| `@electron/remote` import                             | Sync main-object access = renderer→main RCE                | Replace with explicit `ipcMain.handle` channels       |
+| `new BrowserView(...)`                                | Deprecated since Electron 30, will be removed              | `new WebContentsView(...)`                            |
+| Auto-update with an unsigned/un-notarized build       | Squirrel.Mac silently refuses; no updates ship             | Sign + notarize (mac), Authenticode (win) first       |
+| Shipping on an EOL Electron major                     | Unpatched Chromium CVEs in your users' hands               | Stay within the latest 3 majors                       |
+| Heavy CPU work in the main process                    | Blocks the event loop → the whole UI freezes               | `utilityProcess`/worker, or do it in the renderer     |
+
+## Verify
+
+Run `scripts/verify.sh /path/to/your-electron-project` to grep a target for insecure
+patterns (`nodeIntegration: true`, `contextIsolation: false`, `sandbox: false`,
+`@electron/remote`, `new BrowserView`, `exposeInMainWorld(..., ipcRenderer)`). It's read-only
+and exits non-zero on any finding. With no argument it self-checks this skill's own example
+snippets for the secure baseline. See `references/security-and-ipc.md` for the full checklist.

package/skills/shared/electron/evals/README.md

@@ -0,0 +1,13 @@
+# electron evals
+
+`cases.yaml` is the source of truth. There is no fully automated runner: triggering and
+capability are graded **semantically** by an agent harness (an agent with the catalog's sibling
+names available for routing) plus a human or judge-agent spot-check, because "did it route to
+tauri" and "did it set the secure baseline" are intent judgments, not string matches. For
+triggering, feed each `should_trigger` / `should_not_trigger` prompt to a fresh session 3–5
+times and record whether the electron skill fires (and, for near-misses, whether it hands off to
+the named `route_to` sibling). For capability, answer each scenario once with the skill and once
+without, then score against its `must_include` rubric — the skill passes only if the with-skill
+answer covers the rubric and clearly beats the baseline. The one mechanical check is
+`scripts/verify.sh`: run it against any code the capability case produces to confirm the
+hardening is real (it exits non-zero on any insecure pattern).

package/skills/shared/electron/evals/cases.yaml

@@ -0,0 +1,38 @@
+skill: electron
+
+should_trigger:
+  - prompt: "Build a desktop app for Mac and Windows from this web UI with Electron."
+    why: "Cross-platform desktop shell from web UI is core Electron."
+  - prompt: "Let my Electron renderer read a file safely."
+    why: "Safe OS capability exposure through preload/IPC belongs here."
+  - prompt: "Audit my Electron security: nodeIntegration, sandbox, CSP and preload."
+    why: "Electron security baseline is a central responsibility."
+  - prompt: "Package my Electron app with code signing and auto-update."
+    why: "Packaging, signing and auto-update are Electron shipping concerns."
+  - prompt: "Mi preload expone ipcRenderer y el renderer puede require('fs')."
+    why: "Spanish Electron preload/renderer security hole triggers this skill."
+
+should_not_trigger:
+  - prompt: "Build a smaller Rust-backed desktop shell with native webview."
+    route_to: "tauri"
+    why: "Tauri is explicitly not Electron."
+  - prompt: "Fix this React component state bug in the renderer UI."
+    route_to: "react"
+    why: "Renderer UI framework bugs are not Electron shell concerns."
+  - prompt: "Write a Node CLI script."
+    route_to: "nodejs"
+    why: "Pure Node.js scripting has no Electron process model."
+  - prompt: "Set up GitHub Actions matrix for releases."
+    route_to: "github-actions"
+    why: "CI workflow mechanics are a separate skill, though Electron may inform requirements."
+
+capability:
+  - scenario: "A user has an Electron renderer with nodeIntegration true and wants file access plus auto-update."
+    must_include:
+      - "Explains main/renderer/preload process boundaries and treats renderer as untrusted."
+      - "Keeps nodeIntegration false, contextIsolation true and sandbox true."
+      - "Exposes a narrow typed API through contextBridge in preload."
+      - "Routes privileged file operations through validated IPC to the main process."
+      - "Avoids exposing raw ipcRenderer or fs to the renderer."
+      - "Mentions packaging/signing/auto-update requirements separately from app code."
+      - "Flags supported Electron major/security patch posture."

package/skills/shared/electron/references/packaging-and-updates.md

@@ -0,0 +1,122 @@
+# Packaging, signing & auto-update
+
+Two toolchains. **Electron Forge** is first-party and feature-first; **electron-builder** has
+the richer update/config surface via `electron-updater`. Pick one — don't mix.
+
+## Decision
+
+| You want…                                                       | Pick             |
+|-----------------------------------------------------------------|------------------|
+| New app, first-party alignment, newest Electron features first   | Electron Forge   |
+| ASAR integrity + universal macOS out of the box                  | Electron Forge   |
+| Differential downloads, staged rollouts, multi-provider feeds    | electron-builder |
+| The deepest config surface for exotic installer needs            | electron-builder |
+
+## Electron Forge config (`forge.config.ts`)
+
+```ts
+import type { ForgeConfig } from '@electron/forge-shared-types';
+import { MakerSquirrel } from '@electron-forge/maker-squirrel';   // Windows
+import { MakerDMG } from '@electron-forge/maker-dmg';             // macOS
+import { MakerDeb } from '@electron-forge/maker-deb';             // Linux
+import { PublisherGithub } from '@electron-forge/publisher-github';
+import { FusesPlugin } from '@electron-forge/plugin-fuses';
+import { FuseV1Options, FuseVersion } from '@electron/fuses';
+
+const config: ForgeConfig = {
+  packagerConfig: {
+    asar: true,
+    osxUniversal: { mergeASARs: true }, // single binary for Intel + Apple Silicon
+    osxSign: { identity: 'Developer ID Application: Your Co (TEAMID)' },
+    osxNotarize: {
+      appleId: process.env.APPLE_ID!,
+      appleIdPassword: process.env.APPLE_APP_PASSWORD!, // app-specific password
+      teamId: process.env.APPLE_TEAM_ID!,
+    },
+  },
+  makers: [new MakerSquirrel({}), new MakerDMG({}), new MakerDeb({})],
+  publishers: [
+    new PublisherGithub({ repository: { owner: 'you', name: 'my-app' } }),
+  ],
+  plugins: [
+    new FusesPlugin({
+      version: FuseVersion.V1,
+      [FuseV1Options.RunAsNode]: false,
+      [FuseV1Options.EnableCookieEncryption]: true,
+      [FuseV1Options.OnlyLoadAppFromAsar]: true,
+    }),
+  ],
+};
+export default config;
+```
+
+```bash
+npm run make      # build installers for the current OS
+npm run publish   # build + upload to the configured publisher
+```
+
+## electron-builder config (`electron-builder.yml`) + updater
+
+```yaml
+appId: com.yourco.myapp
+asar: true
+mac:
+  hardenedRuntime: true
+  gatekeeperAssess: false
+  notarize: true            # builder calls notarytool for you
+win:
+  target: nsis
+  signtoolOptions:
+    sign: ./scripts/sign.js # Authenticode signing hook
+publish:
+  provider: github
+  owner: you
+  repo: my-app
+  releaseType: release
+```
+
+```ts
+// main.ts — auto-update via electron-updater (pairs with electron-builder)
+import { autoUpdater } from 'electron-updater';
+
+app.whenReady().then(() => {
+  autoUpdater.checkForUpdatesAndNotify(); // checks the GitHub Releases feed
+});
+autoUpdater.on('update-downloaded', () => autoUpdater.quitAndInstall());
+```
+
+Staged rollout: publish `latest.yml` with a `stagingPercentage` so only a fraction of clients
+pick up the new version until you're confident, then raise it.
+
+## macOS signing + notarization
+
+1. **Sign** with a *Developer ID Application* certificate and the hardened runtime enabled.
+2. **Notarize** the signed app with `notarytool` (Apple scans it for malware):
+   ```bash
+   xcrun notarytool submit MyApp.dmg \
+     --apple-id "$APPLE_ID" --team-id "$APPLE_TEAM_ID" \
+     --password "$APPLE_APP_PASSWORD" --wait
+   ```
+3. **Staple** the ticket so the app validates offline: `xcrun stapler staple MyApp.dmg`.
+
+**Why it's mandatory for updates:** Squirrel.Mac refuses to apply an update whose new build
+isn't properly signed + notarized. Skip it and auto-update silently does nothing.
+
+## Windows Authenticode
+
+Sign the installer and the app `.exe` with an Authenticode certificate (an EV or OV cert from
+a CA; cloud HSM signing is increasingly required):
+
+```bash
+signtool sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 \
+  /a MyAppSetup.exe
+```
+
+Squirrel.Windows / NSIS auto-update relies on the signature matching across versions, so use
+the same publisher identity for every release.
+
+## Secrets
+
+Certificates, Apple app-specific passwords, and signing keys are CI secrets — never commit
+them. Storage/rotation policy belongs to `secure-coding`; this reference only covers where the
+Electron flow consumes them (`process.env`, CI secret store).