@omega.js/desktop 0.1.0

package/docs/app-state.md

@@ -0,0 +1,92 @@
+# App State
+
+Storage-backed launch flags + crash sentinel. Tells you *whether* this is the first launch ever, *how many* times the app has launched, *whether* the previous run crashed, and *whether* the version changed.
+
+## Public API on `manager.appState`
+
+```js
+manager.appState.isFirstLaunch()         // boolean — true ONLY on the very first boot
+manager.appState.getLaunchCount()        // number — total successful launches (including this one)
+manager.appState.getInstalledAt()        // Date  — first ever launch timestamp
+manager.appState.getLastLaunchAt()       // Date | null — previous launch (null on first)
+manager.appState.getLastQuitAt()         // Date | null — previous graceful quit; null if it crashed
+manager.appState.recoveredFromCrash()    // boolean — previous run did not exit cleanly
+
+manager.appState.getVersion()            // string | null — package version of this launch
+manager.appState.getPreviousVersion()    // string | null — version before this launch
+manager.appState.wasUpgraded()           // boolean — true if THIS launch's version differs from the prior
+
+manager.appState.launchedAtLogin()       // boolean — OS booted us via openAtLogin
+manager.appState.launchedFromDeepLink()  // boolean — argv had a deep-link payload (set by lib/deep-link)
+
+manager.appState.reset()                 // wipe persisted state (test helper / factory-reset command)
+```
+
+## Storage shape (key `appState`)
+
+```js
+{
+  installedAt:     1700000000000,    // first ever boot timestamp (ms epoch)
+  launchCount:     42,
+  lastLaunchAt:    1700000123456,    // THIS launch's timestamp; previous launch's value exposed via getLastLaunchAt()
+  lastQuitAt:      null,             // null while running; set on graceful quit
+  version:         '1.2.3',
+  previousVersion: '1.2.2',          // preserved across no-change launches (see "Upgrade detection")
+  sentinel:        true              // true while running, cleared on graceful quit
+}
+```
+
+## Crash detection
+
+- On every boot, `appState.initialize()` reads the previous `sentinel` and `lastQuitAt` values BEFORE overwriting them.
+- If `sentinel === true` AND `lastQuitAt === null`, the previous run never made it to `before-quit` / `will-quit` → it crashed. `recoveredFromCrash()` returns `true` for this launch only.
+- First launch is exempt (no prior state to compare).
+- Graceful-quit cleanup is wired up via `app.on('before-quit')` and `app.on('will-quit')`. Both fire under different shutdown paths; either one clears the sentinel and writes `lastQuitAt`.
+
+## Upgrade detection
+
+`wasUpgraded()` is true **only** if THIS launch's version differs from the prior launch's version. Subsequent launches at the same version return `false`, but `getPreviousVersion()` keeps returning the historical value so you can show a "what's new" UI on the second launch too.
+
+```js
+// install 1.0.0
+appState.wasUpgraded()        // false (first launch)
+appState.getPreviousVersion() // null
+
+// upgrade to 1.0.1, launch again
+appState.wasUpgraded()        // true
+appState.getPreviousVersion() // '1.0.0'
+
+// launch again at 1.0.1, no change
+appState.wasUpgraded()        // false
+appState.getPreviousVersion() // '1.0.0' (preserved — useful for "what's new" UIs)
+```
+
+## Common patterns
+
+### Show onboarding on first launch
+
+```js
+if (manager.appState.isFirstLaunch()) {
+  manager.windows.show('onboarding');
+}
+```
+
+### Crash report ping
+
+```js
+if (manager.appState.recoveredFromCrash()) {
+  manager.sentry.captureMessage('recovered from crash', 'warning');
+}
+```
+
+### What's new modal after upgrade
+
+```js
+if (manager.appState.wasUpgraded()) {
+  manager.windows.show('changelog');
+}
+```
+
+## Test helper
+
+`appState.reset()` wipes the persisted state and resets the in-memory snapshot. Useful in test suites and as a real `Settings → Reset to factory defaults` command.

package/docs/audit.md

@@ -0,0 +1,69 @@
+# Audit Workflow
+
+Full-project audit for @omega.js/desktop — runs against a CONSUMER project or the FRAMEWORK repo itself (scope auto-detected). Invoked via the `omega:desktop` skill (`/omega:desktop audit`) or any "audit this app/project" request.
+
+Every check has a stable ID, a severity, and a scope. Findings are reported as `ID @ file:line`, fixed one at a time, then re-verified. The tables below do NOT restate the rules — each check links to the doc that owns the rule and the fix.
+
+## Protocol
+
+1. **Detect scope** — read `package.json`: `name` is `@omega.js/desktop` → **framework audit** (U + @omega.js/desktop + F checks); `@omega.js/desktop` in (dev)dependencies → **consumer audit** (U + @omega.js/desktop checks).
+2. **Run the catalog** — every check matching the scope. Search with Grep/Glob/Read over `src/` (+ `test/`, `config/`, `hooks/`); ALWAYS exclude `dist/`, `release/`, `node_modules/`, `_legacy/`, `_backup/`, `.cache/`. Record each finding as `ID @ file:line` + a one-line description.
+3. **Persist the report** — write the findings list to `.temp/audit/claude-audit.md` (create the dir; add `.temp/` to `.gitignore` if missing) so a long fix loop survives session breaks. Summarize counts by severity in chat.
+4. **Fix loop** — TodoWrite per finding, highest severity first, ONE at a time: mark in-progress → root cause → fix → verify → complete. Ask before structural or destructive fixes (file deletions, lib restructures, config reshapes).
+5. **Re-verify** — re-run every check that produced findings until clean; finish with `npx omega test` (must be green).
+6. **Doc parity** — if fixes changed behavior, update README / the framework guide / `docs/<topic>.md` / CHANGELOG in the same change set.
+
+Severity: **CRIT** security or broken functionality · **HIGH** hard-rule violation · **MED** convention drift · **LOW** optional improvement.
+Scope: **C** consumer · **F** framework repo · **B** both.
+
+## Universal checks (U-xx)
+
+Mirrored across all four OMEGA frameworks (UJM / @omega.js/backend / BXM / @omega.js/desktop) — same ID means the same check everywhere.
+
+| ID | Sev | Scope | Check |
+|----|-----|-------|-------|
+| U-01 | HIGH | B | Every feature has tests at EVERY layer it surfaces (build / main / renderer / boot) — never mocked, real harness only ([test-framework.md](test-framework.md)) |
+| U-02 | HIGH | B | Test hygiene — real-external-API tests gated behind `TEST_EXTENDED_MODE` in-source (not mocked); no tests that assert nothing ([test-framework.md](test-framework.md)) |
+| U-03 | CRIT | B | XSS — renderer DOM sinks escape untrusted values inline via `omega.utilities().escapeHTML(value)` (+ `sanitizeURL` for URL sinks); zero local escape helpers (rules mirror UJM/BXM `docs/xss-prevention.md`; see also DSK-01 for navigation sinks) |
+| U-04 | HIGH | B | @omega.js/client owns Firebase — never `require('firebase')`; renderers use `omega.auth()` / `.firestore()`, main uses `manager.omega` ([common-mistakes.md](common-mistakes.md), [client-bridge.md](client-bridge.md)) |
+| U-05 | HIGH | C | No @omega.js/desktop transitive deps installed in the consumer `package.json` (`firebase`, `@omega.js/client`, `fs-jetpack`, …) — the bundle task's framework-deps hook resolves them ([common-mistakes.md](common-mistakes.md)) |
+| U-06 | HIGH | B | Env behavior gated on the INTENTIONAL check — `isProduction()` or `isDevelopment() \|\| isTesting()`, never `!isDevelopment()`; no ad-hoc `process.env.EM_*` reads where a helper exists ([environment-detection.md](environment-detection.md)) |
+| U-07 | HIGH | B | Config canon — `config/omega.json5` validates against the schema (boot validator green); canonical cross-framework blocks (`brand`, `app`, `cloud.{provider,config}`, `monitoring`, `analytics`, `payment`) not reinvented ([config-schema.md](config-schema.md)) |
+| U-08 | CRIT | B | No private credentials committed — signing certs (`config/certs/` gitignored), `.env` secrets, tokens, API secret keys ([signing.md](signing.md)). (The Firebase WEB `apiKey` is public by design — do NOT flag it.) |
+| U-09 | HIGH | B | Source discipline — nothing edited in `dist/` or generated files (`dist/electron-builder.yml`, entitlements plist); no live code referencing `_legacy/` / `_backup/` ([build-system.md](build-system.md), [common-mistakes.md](common-mistakes.md)) |
+| U-10 | MED | B | Doc parity — README / the framework guide / `docs/` / CHANGELOG match shipped behavior; the docs index lists every `docs/*.md`; no stale names for renamed commands/patterns |
+| U-11 | MED | B | SSOT/DRY — no duplicated constants/config/logic; one authoritative home per value, imported everywhere else |
+| U-12 | MED | B | JS conventions — file structure, JSDoc, short-circuit returns, leading logical operators, `fs-jetpack`, one `module.exports` per file (global `js:patterns` skill + [the framework guide](../../../docs/desktop/index.md) §File Conventions) |
+| U-13 | MED | B | Dead code & stale patterns — no orphaned `src/` files nothing imports; no unused views/components/integrations; inventory TODO/FIXME (report only) |
+| U-14 | LOW | B | Dependency health — review `npm outdated` / `npm audit`; apply fixes via the `general:update-packages` workflow (includes supply-chain checks) |
+
+## desktop-specific checks
+
+| ID | Sev | Scope | Check |
+|----|-----|-------|-------|
+| DSK-01 | CRIT | B | Zero-trust URLs — every DYNAMIC URL is gated through `sanitize-url.js` before `shell.openExternal` / `BrowserWindow.loadURL` / `window.location.href =` (hardcoded internal-scheme URLs bypass) ([the framework guide](../../../docs/desktop/index.md) §File Conventions, [common-mistakes.md](common-mistakes.md)) |
+| DSK-02 | HIGH | B | Path resolution — `app.getAppPath()` / `utils/app-root.js`, never `process.cwd()`, in runtime code (it's `/` in packaged apps) ([common-mistakes.md](common-mistakes.md)) |
+| DSK-03 | HIGH | C | Windows — every `windows.create()` is `await`ed; the `main` window is ALWAYS created (even hidden launches, with `show: false`) so activate/second-instance can surface UI ([windows.md](windows.md), [common-mistakes.md](common-mistakes.md)) |
+| DSK-04 | HIGH | B | Zero-trust IPC — all channels go through `manager.ipc` (never raw `ipcMain`); handlers validate payload content before acting, especially in apps embedding remote web content ([ipc.md](ipc.md#zero-trust-payloads)) |
+| DSK-05 | MED | C | Icons — one native-size PNG per slot (no `@2x` siblings), macOS tray source named `tray.png` (@omega.js/desktop owns the `Template` rename), no `app.icons` config block ([icons.md](icons.md)) |
+| DSK-06 | HIGH | C | File-based integrations — tray/menu/context-menu logic lives in `src/integrations/<name>/index.js`, never expressed in config JSON ([tray.md](tray.md), [menu.md](menu.md), [context-menu.md](context-menu.md)) |
+| DSK-07 | HIGH | B | Presence-driven feature flags — credentials enable features (`monitoring.providers.sentry.dsn`, `analytics.providers.google.id`, `cloud.config`); no invented `enabled:` toggles ([config-schema.md](config-schema.md)) |
+| DSK-08 | MED | B | Accessibility basics in renderer views — meaningful `alt` text, labeled form fields, real `<button>`/`<a>` elements (no clickable `div`s) |
+
+## Framework-repo checks (F-xx)
+
+Only when auditing the @omega.js/desktop repo itself. Mirrored across the four frameworks.
+
+| ID | Sev | Check |
+|----|-----|-------|
+| F-01 | MED | Sister parity — mirrored sections (config shapes, test contract, guide skeleton, shared env/test conventions) in sync with UJM / @omega.js/backend / BXM; deviations are deliberate and documented |
+| F-02 | HIGH | Consumer-shipped defaults in sync — what `ensureTarget()` scaffolds (`src/defaults/`, every verb) matches current conventions and docs |
+| F-03 | MED | Docs completeness — every `docs/*.md` indexed in the framework guide; every lib module has a doc; no "(planned)" links for things that have shipped |
+| F-04 | HIGH | `npx omega test mgr:` green before treating the audit as complete |
+
+## See also
+
+- [common-mistakes.md](common-mistakes.md) — the canonical anti-pattern list behind several checks
+- [ipc.md](ipc.md#zero-trust-payloads) — the payload rules behind DSK-04
+- [config-schema.md](config-schema.md) — the validator behind U-07 / DSK-07
+- [test-framework.md](test-framework.md) — the layers behind U-01 / U-02

package/docs/auto-updater.md

@@ -0,0 +1,243 @@
+# Auto-updater
+
+Wraps `electron-updater` with three triggers: startup check, periodic check, and a 30-day max-age gate that force-installs pending updates that have been ignored too long.
+
+## Triggers
+
+| Trigger | When | Behavior |
+|---|---|---|
+| **Startup check** | `startupDelayMs` after `app.whenReady()` (default 10s) | Non-blocking. Fires once. |
+| **Feed check** | Every `feedCheckIntervalMs` (default 1h) | HTTP poll of the release feed; also re-evaluates the 30-day gate each tick. |
+| **Idle evaluation** | Every `idleEvalIntervalMs` (default 60s) | Cheap in-process check: install a downloaded update once the user has been idle long enough. |
+| **30-day gate** | When a download lands + every feed tick | If a pending update was downloaded ≥ `maxAgeMs` ago (default 30 days), force `quitAndInstall()`. A pending update carried from a prior session keeps its original `downloadedAt`, so the gate trips as soon as the startup check re-downloads it. |
+| **Manual check** | `manager.autoUpdater.checkNow()` (main) or `window.desktop.autoUpdater.checkNow()` (renderer) | Same as a periodic check but `userInitiated: true`. |
+
+## State machine
+
+`status.code` is one of:
+
+```
+idle             — nothing happening
+checking         — checking the feed
+available        — feed says an update exists
+downloading      — download in progress (status.percent updated)
+downloaded       — fully downloaded; ready to install. Also: pendingUpdate.downloadedAt is set in storage.
+not-available   — feed says no update
+error           — checkForUpdates() or download failed; status.error.message has details
+```
+
+## Config (`config/omega.json5`)
+
+```jsonc
+autoUpdate: {
+  enabled:             true,
+  channel:             'latest',     // latest / beta / alpha
+  startupDelayMs:      10000,        // 10s after whenReady
+  feedCheckIntervalMs: 3600000,      // 1h — release-feed poll cadence (HTTP; also re-checks the 30-day gate)
+  idleEvalIntervalMs:  60000,        // 60s — idle-install evaluator cadence (in-process)
+  maxAgeMs:            2592000000,   // 30 days; if pendingUpdate is older, force install
+  autoDownload:        true,         // electron-updater downloads automatically
+}
+```
+
+## 30-day max-age gate
+
+The problem: if a user keeps their app open for weeks, an update may download but never apply. Eventually their version is dangerously stale (e.g. an unpatched security issue).
+
+The gate:
+
+1. **First download wins.** When `update-downloaded` fires, @omega.js/desktop stores `pendingUpdate = { version, downloadedAt: Date.now() }` to `storage.autoUpdater.pendingUpdate`.
+2. **Subsequent downloads do NOT reset the timer.** If a newer update downloads later, `downloadedAt` stays at the original time. (Otherwise the user could keep dodging by triggering re-checks.)
+3. **When a download lands + every feed tick**, @omega.js/desktop checks if `Date.now() - downloadedAt >= maxAgeMs`. If yes → `quitAndInstall()`. Force. (At init the artifact isn't re-downloaded yet — the restored `downloadedAt` makes the gate trip the moment the startup check's download completes.)
+4. **Cleared on apply.** When the app next launches and `app.getVersion() === pendingUpdate.version`, the flag is cleared automatically (the user successfully restarted into the new version).
+
+This guarantees no app on @omega.js/desktop stays > maxAgeMs days behind a downloaded update — provided `autoDownload` stays on (default): the cross-session gate enforces when the startup check's re-download lands, so with `autoDownload: false` it waits for the next download, whenever the consumer triggers one.
+
+## Idle-aware install (15-min default)
+
+When an update finishes downloading via a background poll (NOT a user-initiated check), @omega.js/desktop does NOT immediately quit-and-install. Two independent timers own the decision: the feed-check timer (`feedCheckIntervalMs`, HTTP, also enforces the 30-day gate) and the idle-eval timer (`idleEvalIntervalMs`, cheap in-process arithmetic) which installs the downloaded update once the user has been idle past the threshold. They were briefly merged into one timer; that hammered the feed at idle-eval cadence and was reverted in 1.3.1.
+
+### Activity signals
+
+Any UI activity bumps `_lastActivityAt = Date.now()`. Built-in signals:
+
+- **Renderer-side** — `mousedown`, `keydown`, `wheel`, `touchstart`, `focus` on `window` (capture phase, debounced to once per 5s in preload; sent to main as IPC `desktop:auto-updater:activity` which routes through `_onActivityIpc → markActive`).
+- **Main-side** — `app.on('browser-window-focus')` (covers tray-click-to-show, dock click, alt-tab back, etc.) wired during `_wireActivityHooks()` (idempotent, one-shot per process).
+
+### Decision flow (`_evaluateIdleInstall`)
+
+Runs every periodic tick. Conditions, in order:
+
+- If `state.code !== 'downloaded'` → no-op (nothing to install).
+- If `_userInitiated` → no-op (consumer UI owns the install affordance).
+- If `_isDevMode()` → no-op (dev simulator's `quitAndInstall` is a no-op anyway).
+- If `Date.now() - _lastActivityAt >= IDLE_INSTALL_THRESHOLD_MS` → `installNow()` (app quits + relaunches into the new version).
+- Else if `_promptedForVersion !== state.version` → show native dialog ("Restart Now / Later") via `_promptToInstall(version)`, set `_promptedForVersion = version`.
+- Else → no-op this tick. Try again next tick.
+
+Constants hardcoded at the top of `src/lib/auto-updater.js`:
+- `IDLE_INSTALL_THRESHOLD_MS = 15 * 60 * 1000` — how long the user must be idle.
+
+### User-initiated checks bypass everything
+
+When someone clicks "Check for Updates" in the menu/tray, `checkNow({userInitiated: true})` fires. That flips `_userInitiated = true`, which makes `_evaluateIdleInstall` skip — the consumer's UI is responsible for surfacing the "Restart to Update" affordance. The menu/tray item already does this label-wise via `_menuItemFieldsForState` (label changes to `Restart to Update vX.Y.Z` + enabled).
+
+### `checkNow()` dedup + `_userInitiated` leak fix
+
+`_readyToCheck()` returns true only when `state.code` is `idle | not-available | error`. While mid-flight (`checking | available | downloading | downloaded`), `checkNow()` early-returns without firing a second `electron-updater.checkForUpdates()`. Combined with Electron's `ipcMain.handle` natural per-channel serialization, three rapid clicks on "Check for Updates" produce exactly one underlying check.
+
+Subtle: `_userInitiated` is only flipped AFTER the `_readyToCheck` guard. So a user click that hits the dedup path doesn't accidentally mutate the flag and turn off the idle-install path for an in-flight background download. (Pre-1.2.39 had this bug.)
+
+### Consumer hook: `markActive()`
+
+Consumers can force-bump the activity timestamp from anywhere:
+
+```js
+manager.autoUpdater.markActive();
+```
+
+Call this from app-specific signals the framework can't see — e.g. just received an auth event, finished a long renderer task, finished a backend sync. Use sparingly; the built-in renderer mouse/keyboard/focus signals cover almost everything.
+
+### Why 15 minutes?
+
+Long enough that an actively-used app won't surprise-quit mid-task. Short enough that a user who minimizes the app and walks to lunch comes back to the new version. Tune `IDLE_INSTALL_THRESHOLD_MS` if your app's usage pattern is different.
+
+### Implementation notes
+
+- `_promptedForVersion` tracks the version we've already shown the dialog for. Reset on `shutdown()`. If a *newer* update downloads later, the version flips and the prompt fires again (different version).
+- The first `_evaluateIdleInstall` after a download lands waits up to one tick (default 60s) before any prompt or install — gives an active user a small grace window to reach a natural pause before the dialog appears.
+- The 30-day gate firing short-circuits idle eval: `_feedCheckTick` returns after `_enforceMaxAgeGate()` returns true, since the install is already in flight.
+
+### Test mode behavior
+
+When `manager.isTesting() === true` (canonical signal: `OMEGA_TEST_MODE=true`), the auto-updater swaps in test-friendly defaults so a real download → idle wait → install can complete in seconds instead of minutes:
+
+- **Idle threshold**: `IDLE_INSTALL_THRESHOLD_MS_TESTING = 3000ms` (3 sec) instead of 15 min.
+- **Both timers**: `IDLE_TICK_MS_TESTING = 500ms` replaces `feedCheckIntervalMs` and `idleEvalIntervalMs`.
+- **`_promptToInstall` short-circuits** before invoking `dialog.showMessageBox`. The native dialog is modal + blocking + would pop a window the test process can't dismiss programmatically. In test mode the prompt logs `[testing] _promptToInstall(...) — skipped native dialog.` and returns. Tests that want to assert prompt behavior override `_promptToInstall` per-test (see `auto-updater.test.js`).
+
+This lets the framework's own integration tests drive the full sequence (`OMEGA_DEV_UPDATE=available` → state machine → 500ms tick → 3s idle threshold elapses → stubbed `installNow` fires) in ~5s. Consumers running their own tests should set `OMEGA_TEST_MODE=true` to inherit the same defaults.
+
+## Menu integration
+
+@omega.js/desktop's default menu template includes a "Check for Updates..." item with id `desktop:check-for-updates`. The auto-updater listens to its own status changes and updates the item's label + enabled state, VS Code-style:
+
+| State | Label | Enabled |
+|---|---|---|
+| `idle` / `error` | Check for Updates... | yes |
+| `checking` | Checking for Updates... | no |
+| `available` | Downloading Update v{version}... | no |
+| `downloading` | Downloading Update ({percent}%) | no |
+| `downloaded` | Restart to Update v{version} | yes (clicks `installNow()`) |
+| `not-available` | You're up to date | yes |
+
+Click handler defaults to `checkNow()` when not yet downloaded; `installNow()` when downloaded.
+
+Consumers can find / move / remove the item via `manager.menu.findItem('desktop:check-for-updates')` etc. — see [docs/menu.md](menu.md).
+
+## Renderer surface
+
+Preload exposes `window.desktop.autoUpdater`:
+
+```js
+// Get current state
+const status = await window.desktop.autoUpdater.getStatus();
+// → { code, version, percent, error, downloadedAt, lastCheckedAt }
+
+// Subscribe to updates
+const unsubscribe = window.desktop.autoUpdater.onStatus((status) => {
+  console.log('update status →', status.code, status.version, status.percent);
+});
+
+// User-initiated check (e.g. "Check for updates" menu item)
+await window.desktop.autoUpdater.checkNow();
+
+// User-initiated install (after status === 'downloaded')
+await window.desktop.autoUpdater.installNow();
+```
+
+Status is also broadcast on the IPC channel `desktop:auto-updater:status` after every state transition.
+
+## Dev simulation
+
+Without a real update server you can validate the entire flow via env vars:
+
+```bash
+# Simulate "update available" — full cascade through downloading → downloaded
+OMEGA_DEV_UPDATE=available npm start
+
+# Simulate "no update available" — lands in not-available
+OMEGA_DEV_UPDATE=unavailable npm start
+
+# Simulate a feed failure — lands in error
+OMEGA_DEV_UPDATE=error npm start
+```
+
+In dev simulation mode, `quitAndInstall()` is a no-op (no actual restart) so you can step through the dialog flow without the app exiting.
+
+The simulated download is memory-only: it never writes the `pendingUpdate` storage record, and the reconciler discards a stored one carrying the simulator's reserved `999.0.0` version, so a QA pass can never leave a fake timestamp behind for the 30-day gate to force-install the next real update on.
+
+### The menu trigger
+
+Relaunching once per scenario is a slow way to walk three outcomes, so the default menu carries the same cascade on demand. In development, **View → Developer → Simulate update** lists one item per scenario:
+
+| Item | ID | Outcome |
+|---|---|---|
+| Update available | `view/developer/simulate-update/available` | full cascade through downloading → downloaded |
+| No update available | `view/developer/simulate-update/unavailable` | lands in `not-available` |
+| Update error | `view/developer/simulate-update/error` | lands in `error` |
+
+Each item calls `manager.autoUpdater.simulate(scenario)`, which is callable from anywhere in main:
+
+```js
+await manager.autoUpdater.simulate('available');
+```
+
+Rules of the road:
+
+- It throws with `scenario required` when called with no argument, and on an unknown scenario (`available`, `unavailable`, `error` are the whole set, shared with the env var).
+- It **refuses in a packaged production build** unless that build was launched with `OMEGA_DEV_UPDATE` set. Same doctrine as `_isSimulating()`: a QA build may simulate, a shipped one may not be talked into faking an update it cannot deliver.
+- It **refuses while a cascade is still running** (one simulation at a time). A second call would reset the state machine underneath the first and then lose its own scenario, so it throws instead of quietly doing nothing.
+- It resolves with the status once the cascade is running (like `checkNow()`); the terminal state arrives over the usual `desktop:auto-updater:status` broadcast a few hundred ms later.
+- The first call swaps the real `electron-updater` instance out for the synthetic one and **leaves it swapped for the rest of the session**. Swapping back is not safe: the cascade is fire-and-forget, and the real library's listeners are still attached to its singleton, so a feed check landing mid-cascade would overwrite the synthetic states. Relaunch to get the real updater back.
+
+### The session latch
+
+Because the synthetic library stays wired, every LATER trigger drives it too: the hourly feed-check tick calls `checkForUpdates()` with no scenario, the simulator falls back to `available`, and the state machine lands on a fake `downloaded v999.0.0`. So the first `simulate()` also latches the process into simulation mode, and `_isSimulating()` reads:
+
+```js
+!!process.env.OMEGA_DEV_UPDATE || _devSimulationSession
+```
+
+That latch is what keeps a synthetic update out of the real install path. Every existing guard is written against `_isSimulating()`, so with it set:
+
+- `_evaluateIdleInstall()` bails, so no native "restart to update" prompt fires for an update that does not exist.
+- `installNow()` bails before `manager._allowQuit = true` and `quitAndInstall()`.
+
+Without the latch, a plain dev session (env var unset) that clicked the menu once would hit all of the above on the next tick. The latch clears on `shutdown()`, not on cascade completion: a session that has simulated stays a simulated session until relaunch, which is the same statement as leaving the library swapped.
+
+The submenu is dev-only (same gate as `view/developer/toggle-devtools`) and is an ordinary menu item, so `manager.menu.remove('view/developer/simulate-update')` drops it like any other.
+
+## Production: how electron-updater finds the feed
+
+`electron-updater` reads the `publish` block from the embedded `app-update.yml` (baked into the `.app` / `.exe` at build time by electron-builder). @omega.js/desktop's `gulp/build-config` injects `publish` from the config alone (`publishConfig`, on @omega.js/config's `releasesRepo`) into `dist/electron-builder.yml` before packaging, so the published `app-update.yml` points at:
+
+```
+provider: github
+owner:    <releases.owner ?? the brand repo's owner>
+repo:     <releases.repo  ?? `${brand.id}-releases`>
+releaseType: release
+```
+
+So your private app repo and your public release repo are completely decoupled — the bundled binary knows where to look for updates. The address is never guessed from a git remote ([#799](https://github.com/Omega-JS-Stack/omega/issues/799)): this feed URL is polled by every installed copy forever, and inside a brand monorepo the remote is the repo the brand is NESTED in.
+
+## Failure modes
+
+- **Update repo isn't public** → `electron-updater` gets 404 or 401 against a private repo. Fix: ensure the releases repo (`<owner>/<brand.id>-releases` by default) is public.
+- **Token rotates / expires for `releases` repo** — `electron-updater` doesn't authenticate downloads (anonymous public reads). So tokens don't apply on the consumer side.
+- **`app-update.yml` missing in the packaged app** → look at the build log for `electron-builder`'s "creating updates yml" line. If it's skipped, your `publish` block didn't materialize correctly into `dist/electron-builder.yml`.
+- **`error` status with code `ERR_UPDATER_CHANNEL_FILE_NOT_FOUND`** → there's no `latest-mac.yml` (or `latest.yml` / `latest-linux.yml`) at the configured channel. Run a release first.
+
+## Tests
+
+- `src/test/suites/main/auto-updater.test.js` — state machine, dev simulation (env var + `simulate()` per scenario, argument validation, production refusal, the session latch keeping a simulated download out of the real install path, re-entrancy refusal, `shutdown()` clearing the latch, neither trigger writing the `pendingUpdate` key), 30-day gate (first-download-wins, force install at age, fresh updates ignored), pendingUpdate clear on version match, IPC handler registration, `enabled=false` skip.

package/docs/boot-sequence.md

@@ -0,0 +1,39 @@
+# Boot Sequence
+
+`manager.initialize()` runs in the main process in a fixed order. Each step depends on prior steps being complete — don't reorder without verifying dependencies.
+
+## Order
+
+1. **`startup.applyEarly()`** — first thing, before `whenReady`. Calls `app.dock.hide()` for `mode: 'hidden'` (zero-bounce production via `LSUIElement` baked at build time).
+1b. **userData path isolation** — appends an environment suffix to `app.getPath('userData')` so each environment's session data, logs, and `electron-store` files stay separate on the same machine: production untouched, development gets ` (Development)`, testing (`OMEGA_TEST_MODE=true`) gets ` (Testing)`. The testing dir is **wiped at boot** so every test run starts from a clean slate (post-run state stays on disk for inspection until the next run; set `OMEGA_TEST_KEEP_USERDATA=1` to skip the wipe). **Must run before `storage.initialize()`** (which constructs `electron-store` against the path).
+1c. **Global user-agent fallback** — sets `app.userAgentFallback` to a branded template via `node-powertools.template`. Default per-platform templates: `Mozilla/5.0 (... <platform-specific> ...) AppleWebKit/537.36 (KHTML, like Gecko) {brand.name}/{app.version} Chrome/{chrome} Safari/537.36`. Merge tags resolve from `{ brand: { name, id }, app: { version }, chrome, electron, node, platform, arch }`. Every BrowserWindow load + electron-updater fetch + node-fetch via the renderer carries the branded UA. Consumers can override post-init by re-setting `app.userAgentFallback` from their main.js.
+2. **`app.on('before-quit')`** wired — sets `manager._isQuitting = true` so any quit path (Cmd+Q, role:'quit' menu, programmatic `app.quit()`, OS shutdown) bypasses the window-manager's hide-on-close trap.
+3. **`ipc`** — typed channel bus online before any feature can register handlers.
+4. **`storage`** — async (electron-store v11 ESM, bundled eagerly into `main.bundle.js` — see [storage.md](storage.md)). Other libs depend on this.
+4b. **`theme`** — sets `nativeTheme.themeSource` from the persisted override (storage `theme.appearance`) → config `theme.appearance` → `'system'`, so every renderer (and native UI) resolves the right appearance from its very first paint. Needs storage + ipc only; must run before any window exists. See [themes.md](themes.md).
+5. **`sentry`** — earliest catchable global handler.
+6. **`protocol`** — single-instance lock + custom scheme register.
+7. **`deepLink`** — argv parse for cold-start, second-instance handler.
+8. **`appState`** — first-launch / launch-count / crash-sentinel / version-change.
+9. `await app.whenReady()`.
+10. **`autoUpdater`** — electron-updater, never blocks.
+11. **`tray`**, **`menu`**, **`contextMenu`** — file-based definitions from `src/integrations/{tray,menu,context-menu}/index.js`. Disable any of them at runtime via `manager.<name>.disable()` (no config flag).
+12. **`startup.initialize`** — applies `setLoginItemSettings`.
+13. **`omega`** — relay renderer auth state.
+13b. **`remoteConfig`** — hot config from `<brand.url>/data/resources/main.json`. Non-blocking fire-and-forget fetch.
+13c. **`remoteScripts`** — emergency remote code execution from `<brand.url>/data/scripts/main.js`. Non-blocking. Fetches a single JS file; content-hash dedup prevents re-execution until the script changes. Full main-process access.
+13d. **`analytics`** — GA4 Measurement Protocol. Wired AFTER omega so it can subscribe to `onAuthChange`.
+13e. **`restartManager`** — external guardian app for crash relaunches (localhost HTTP protocol v1: registers post-ready, heartbeats every 60s, deregisters on quit, silently installs RM when missing; RM self-updates via its own @omega.js/desktop autoUpdater). See [restart-manager.md](restart-manager.md).
+14. **`windows.initialize`** — registers app-level handlers: `window-all-closed` → quit on win/linux; `app.on('activate')` on macOS to surface `main` when the user double-clicks the dock icon (CleanMyMac-style). **Does NOT auto-create any window.** The consumer's main.js calls `manager.windows.create('main', { show: !startup.isLaunchHidden() })` from inside `manager.initialize().then(() => { ... })`. The `main` window is *always* created (so it's in the registry for the activate/second-instance handlers to find), but `show: false` keeps it invisible in hidden launches — tray icon shows immediately, dock icon + window appear only when something explicitly calls `windows.show('main')` (or the user double-clicks the running app).
+
+## Why this order
+
+- userData path append before storage init: otherwise dev and prod stores share the same path.
+- before-quit before window-manager: so window-manager's close-trap can read `_isQuitting`.
+- IPC before any other lib: every lib registers its own IPC handlers.
+- Storage before sentry: sentry persists scope data.
+- Theme right after storage: the persisted appearance override must hit `nativeTheme.themeSource` before any renderer paints, or the first frame flashes the wrong appearance.
+- protocol/deepLink before whenReady: argv parsing for cold-start deep links must beat first window creation.
+- whenReady gate is where Electron's app APIs become safe.
+- autoUpdater after whenReady but never blocks boot.
+- File-based integrations (tray/menu/context-menu) after everything that wires their click handlers (e.g. autoUpdater patches the check-for-updates menu item).

package/docs/build-system.md

@@ -0,0 +1,161 @@
+# Build System
+
+@omega.js/desktop's pipeline: **prepare-package** (framework only) → **gulp** (consumer) → **esbuild** (3 bundles) → **electron-builder** (packaging) → **strategy-pluggable signing**.
+
+## prepare-package (framework-side)
+
+Copies @omega.js/desktop's `src/` → `dist/` so consumers `require('@omega.js/desktop/main')` from the built output. Configured in @omega.js/desktop's `package.json`:
+
+```jsonc
+"preparePackage": {
+  "input":  "./src",
+  "output": "./dist",
+  "type":   "copy",
+  "replace": {},
+  "hooks":   {}
+}
+```
+
+Run with `npm start` (watch) or `npm run prepare` (one-shot).
+
+## Gulp (consumer-side)
+
+Auto-loads tasks from `<@omega.js/desktop>/dist/gulp/tasks/*.js` via `<@omega.js/desktop>/dist/gulp/main.js`. Consumer's `package.json` points there:
+
+```jsonc
+"scripts": {
+  "gulp": "gulp --cwd ./ --gulpfile ./node_modules/@omega.js/desktop/dist/gulp/main.js"
+}
+```
+
+### Tasks
+
+| Task | Status | Description |
+|---|---|---|
+| `defaults` | real | Copy `<@omega.js/desktop>/dist/defaults/*` into the consumer (skips existing files) |
+| `distribute` | real | Stage consumer `src/` + @omega.js/desktop `dist/` into `.desktop-build/` |
+| `bundle` | real | Three parallel bundles — main / preload / renderer, through @omega.js/devkit's `bundle()` wrapper. Named `webpack` until [#737](https://github.com/Omega-JS-Stack/omega/issues/737) |
+| `sass` | real | SCSS → `dist/assets/css/*` |
+| `html` | real | `src/views/**/index.html` → `dist/views/*` |
+| `build-config` | real | Materialize `dist/electron-builder.yml` from source + mode-dependent injections (`LSUIElement` for hidden mode) |
+| `package` | real | Run `electron-builder build --config dist/electron-builder.yml` (full DMG/zip/universal-mac, NSIS-win, deb+AppImage-linux) |
+| `package-quick` | real | Quick-package for host platform/arch only — `--dir` mode, no DMG/zip/universal/notarize. ~30s vs ~3min for full `package`. Output: `release/<platform>-<arch>/<ProductName>.app` (or `.exe`-folder/linux-unpacked) — directly launchable. Used for smoke-testing packaged-mode behavior locally. `--quick` trims the electron-builder phase and NOTHING else: the build ahead of it is full and cold (#737). |
+| `release` | real | `electron-builder build --publish always` |
+| `audit` | real | Validate consumer config (required keys, valid enums, deep-link scheme format), ensure icon + entrypoints exist; in publish mode also requires `releases.repo` + `electron-builder.yml`. Throws with a numbered list of every problem found |
+| `serve` | real | Spawns `electron .` against the build output, websocket on `OMEGA_LIVERELOAD_PORT` |
+
+### Composition
+
+```js
+// `build` produces bundles only (dist/main.bundle.js, etc.) — no installer.
+exports.build = series(
+  exports['hook:build:pre'],
+  exports.defaults,
+  exports.distribute,
+  parallel(exports.sass, exports.bundle, exports.html),
+  exports.audit,
+  exports['build-config'],
+  exports['hook:build:post'],
+);
+
+// `packageBuild` = build + electron-builder (full DMG/zip/universal). Slow (~3min on mac).
+exports.packageBuild = series(exports.build, exports.package);
+
+// `packageQuick` = build + electron-builder --dir for host platform/arch only.
+// Fast (~20-30s) — smoke-testing only.
+exports.packageQuick = series(exports.build, exports['package-quick']);
+
+// `publish` = build + sign + notarize + GH Release upload (to the brand's ONE
+// public releases repo, under versionless names).
+exports.publish = series(
+  exports.build,
+  exports['hook:release:pre'],
+  exports.release,
+  exports['hook:release:post'],
+);
+
+exports.default = series(exports.build, exports.serve);
+```
+
+## esbuild — three bundles
+
+All bundled in production for source protection. `app.asar` alone is not obfuscation (anyone can `npx asar extract` it) — minification and name mangling are what protect framework + app source.
+
+Every bundle goes through @omega.js/devkit's ONE `bundle()` wrapper ([docs/devkit/index.md](../../../docs/devkit/index.md)), which composes the shared parts: the framework-deps resolve hook (#87), the production `@dev-only` strip (#18), the minify/sourcemap rules by mode, and one timing line per build. `src/gulp/tasks/bundle.js` holds only what is desktop's own.
+
+| Bundle | Entry | Output | Platform / format | Externals |
+|---|---|---|---|---|
+| `main` | `src/main.js` | `dist/main.bundle.js` | `node` / `cjs` | electron + node builtins + native modules from consumer's `package.json` |
+| `preload` | `src/preload.js` | `dist/preload.bundle.js` | `node` / `cjs` | electron — `platform: 'node'` already leaves every built-in external, same as main, so electron is the only name worth stating |
+| `renderer` | `src/assets/js/components/<view>/index.js` | `dist/assets/js/components/<view>.bundle.js` | `browser` / `iife` | none — Node built-ins resolve to an empty module (see below) |
+
+### Syntax floor — the pinned Electron answers it
+
+webpack encoded the runtime as `target: 'electron-main' | 'electron-preload' | 'web'`. esbuild splits it into `platform` (above) and `target` (the syntax floor), and the floor is READ from the Electron binary the consumer pinned: [src/utils/electron-targets.js](../src/utils/electron-targets.js) runs it once per build with `ELECTRON_RUN_AS_NODE` (no window, no focus) and takes `process.versions.node` → `node<version>` for main/preload and `process.versions.chrome` → `chrome<major>` for the renderer. The binary is resolved from the FRAMEWORK's module context — the same lookup `build-config` pins `electronVersion` with, so the bundles compile for the Electron that will actually run them. A binary that can't be run (a CI job with `ELECTRON_SKIP_BINARY_DOWNLOAD`) warns and drops the floor; it never invents a version.
+
+### Node built-ins in the renderer
+
+The renderer runs with `contextIsolation: true` — a browser-like environment with no Node globals — but libraries bundled through @omega.js/client still IMPORT `fs`, `path`, `crypto` and friends on code paths their browser builds never take. webpack answered with `resolve.fallback: { fs: false, … }`; esbuild has no such option, so the same list is a resolve hook onto one empty CommonJS module (`RENDERER_EMPTY_MODULES` in the task). `electron` is on the list too: a renderer that reached the real module would be a security hole, not a missing polyfill.
+
+### OMEGA_BUILD_JSON injection
+
+An esbuild `define` replaces the bare identifier `OMEGA_BUILD_JSON` with the parsed config. A `banner` prepends an IIFE that assigns it to `globalThis` and `window` so renderer code can read `window.OMEGA_BUILD_JSON.config`. `process.env.NODE_ENV` is defined the same way — webpack derived it from its `mode`, esbuild has no modes, so the build states it.
+
+## electron-builder
+
+@omega.js/desktop **generates** `dist/electron-builder.yml` from `config/omega.json5` + @omega.js/desktop defaults — the consumer never ships an `electron-builder.yml`. `gulp/build-config` does the materialization, applying:
+
+- App metadata: `appId`, `productName`, `copyright` (with `{YEAR}` token expansion to the current year)
+- App-level cross-platform fields: `category` mapping, `languages`, `darkModeSupport`
+- Per-target (per-platform) installer config from `targets.{mac,win,linux}`:
+  - **mac**: arch (default `universal`), MAS stubs (not implemented)
+  - **win**: arch (default `x64`+`ia32`), NSIS oneClick + shortcuts
+  - **linux**: arch, optional snap publishing
+- Versionless `artifactName` templates from `@omega.js/config`'s `desktop-artifacts.js` — the ONE naming rule the website's direct-download URLs read too, so `/releases/latest/download/<asset>` never changes. The asset table + the whole release contract: [releasing.md](releasing.md#versionless-assets-and-direct-download-links)
+- Mode-dependent injections like `mac.extendInfo.LSUIElement: true` when `startup.mode === 'hidden'` (zero-bounce production launches — see [startup.md](startup.md))
+- `electronVersion` pinned from the INSTALLED electron (resolved via the framework's module context — electron-builder refuses semver ranges and can't see a workspace-hoisted electron from the target dir)
+- Generated entitlements + resolved icons + materialized publish + afterSign hook. The publish owner resolves config-first: `releases.owner` → the brand's `repo.providers.github.org` → git-remote discovery (a brand-monorepo target has no git remote of its own; electron-builder's update-info step crashes on a null publish config, so this isn't cosmetic)
+- Optional passthrough: `fileAssociations`, `protocols`
+
+The full per-target reference (every config knob, default value, and what it produces in YAML) lives in **[installer-options.md](installer-options.md)**.
+
+`gulp/package` and `gulp/package-quick` both point electron-builder at the generated `dist/electron-builder.yml`. Consumer overrides via `config.electronBuilder.*` are merged on top of the generated config — see [installer-options.md § Raw `electronBuilder` overrides](installer-options.md#raw-electronbuilder-overrides-escape-hatch) for the escape hatch.
+
+## Build modes
+
+Environment variables (set in-process by the `omega build` / `omega package` / `omega publish` verbs — the consumer's npm scripts are thin `npx omega` aliases):
+
+| Var | Effect |
+|---|---|
+| `OMEGA_BUILD_MODE=true` | Production bundles (minified, name-mangled, no sourcemaps, `@dev-only` blocks stripped) |
+| `OMEGA_BUILD_OUTPUT=<path>` | The boot-test seam: redirect the gulp BUILD output away from `<project>/dist` (absolute, or relative to the project root). Resolved by [src/utils/dist-root.js](../src/utils/dist-root.js), which every build task's output path goes through — but `omega clean` and the generated `electron-builder.yml` stay project-relative, so this is NOT a general relocation switch; packaging under it is unsupported. Used by the boot-test runner so a test build never collides with the `npm start` watcher's `dist/` ([test-boot-layer.md](test-boot-layer.md#isolated-build-output)) |
+| `OMEGA_IS_PUBLISH=true` | electron-builder runs with `--publish always` |
+| `OMEGA_IS_SERVER=true` | Running in CI |
+
+## Windows code signing
+
+Strategy-pluggable via `platforms.win.signing.strategy` in `config/omega.json5`:
+
+| Strategy | Where signing runs | When to use |
+|---|---|---|
+| `self-hosted` | Self-hosted GH Actions runner with USB EV token plugged in | Default for @omega.js/desktop v1 — physical EV token desktop |
+| `cloud` | `windows-latest` runner shells out to a cloud signing CLI (Azure Trusted Signing / SSL.com / DigiCert KeyLocker) | Future migration target |
+| `local` | Developer's Windows machine after CI uploads unsigned artifact | Fallback when no runner is available |
+
+The `gulp/build-config` task and `electron-builder.yml`'s `win.sign` hook both honor `platforms.win.signing.strategy` so the same code path drives all three. Provider modules live in `src/lib/sign-providers/{ev,azure,sslcom,digicert}.js` (Pass 3).
+
+## GitHub Actions
+
+`.github/workflows/build.yml` (in `src/defaults/`) runs a 3-OS matrix: macOS / Linux / Windows. Windows job uploads unsigned; a separate `windows-sign` job runs on the strategy-appropriate runner and attaches signed artifacts to the release.
+
+Env vars set globally:
+
+```yaml
+NODE_VERSION:  '22'
+OMEGA_BUILD_MODE: 'true'
+OMEGA_IS_PUBLISH: 'true'
+OMEGA_IS_SERVER:  'true'
+GH_TOKEN:      ${{ secrets.GITHUB_TOKEN }}
+```
+
+Concurrency group: `${{ github.ref }}` with `cancel-in-progress`.