@omega.js/desktop 0.51.0 → 0.53.0

package/docs/index.md

@@ -2,11 +2,11 @@
 
 > **Note for contributors and Claude:** This file is the guide for `@omega.js/desktop` — identity, top-level conventions, and a map to the deep references. It lives in the monorepo's `docs/` tree and is loaded on demand (the omega Claude plugin's hooks inject it by context; the repo-root AGENTS.md map is the one agent entry — packages carry no agent docs). The **meat** (per-subsystem APIs, edge cases, behavior tables, defaults lists) lives in the package's own [`docs/<topic>.md`](../docs) files. When extending or adding content, write it in the matching `docs/*.md` file and cross-link from here — do NOT inline it. If a topic doesn't have a doc yet, create one.
 
-> **Mirrored structure:** the four framework guides — `docs/web/index.md`, `docs/backend/index.md`, `docs/extension/index.md`, and `docs/desktop/index.md` — mirror each other (the legacy UJM/BEM/BXM/EM lineage): shared sections (Supply-Chain Security, Development Workflow, File Conventions, Doc-update parity, etc.) appear in the **same order at the same position** across all four. When adding a section that applies to multiple frameworks, insert it in the same spot in all of them.
+> **Mirrored structure:** the four framework guides (`docs/web/index.md`, `docs/backend/index.md`, `docs/extension/index.md`, and `docs/desktop/index.md`) mirror each other: shared sections (Supply-Chain Security, Development Workflow, File Conventions, Doc-update parity, etc.) appear in the **same order at the same position** across all four. When adding a section that applies to multiple frameworks, insert it in the same spot in all of them. Each consumer template (`src/defaults/AGENTS.md`; web's lives at `scaffold/AGENTS.md`, beside its one-line `@AGENTS.md` `CLAUDE.md` pointer) mirrors its guide the same way.
 
 ## Identity
 
-OMEGA Desktop (@omega.js/desktop) is a comprehensive framework for building modern Electron desktop apps. Sister project to @omega.js/extension and Ultimate Jekyll Manager (UJM). Provides one-line-import bootstrap per Electron process, modular feature library with file-based extensibility, a multi-platform build/release pipeline, and a built-in test framework.
+OMEGA Desktop (@omega.js/desktop) is a comprehensive framework for building modern Electron desktop apps, the desktop of the OMEGA family beside @omega.js/web, @omega.js/extension and @omega.js/backend. Each process module's default export is ONE ready-made instance, `omega`. It provides a one-line-import bootstrap per Electron process, a modular feature library with file-based extensibility, a multi-platform build/release pipeline, and a built-in test framework.
 
 ## Recommended skills
 
@@ -15,7 +15,7 @@ OMEGA Desktop (@omega.js/desktop) is a comprehensive framework for building mode
 
 ## 🚨 READ @omega.js/client TOO
 
-**@omega.js/desktop ships `@omega.js/client` as a runtime singleton inside the renderer process** — it powers auth, Firebase, reactive `data-omega-bind` directives, analytics, error tracking, and utilities (`escapeHTML`, etc.). Any task that touches auth flows, Firestore reads/writes, subscription resolution, push notifications, or DOM bindings means you are working with @omega.js/client as much as with @omega.js/desktop.
+**@omega.js/desktop's renderer instance extends `@omega.js/client`'s base class**: `omega.auth`, `omega.storage`, `omega.bindings`, `omega.firestore` and the rest of the client are properties of the renderer's `omega`, beside `omega.desktop`, the preload's bridge to main. The client powers auth, Firebase, reactive `data-omega-bind` directives, analytics, error tracking, and utilities (`escapeHTML`, etc.). Any task that touches auth flows, Firestore reads/writes, subscription resolution, push notifications, or DOM bindings means you are working with @omega.js/client as much as with @omega.js/desktop.
 
 **Required reading:**
 - **`docs/client/index.md`** (in the framework monorepo) — the client guide: identity, module list, conventions
@@ -52,59 +52,70 @@ OMEGA Desktop (@omega.js/desktop) is a comprehensive framework for building mode
 
 ## Architecture
 
-### Per-process Manager singletons
+### The consumer entry
 
-Each Electron process has its own one-line bootstrap:
+Each Electron process's module exports ONE ready-made instance, `omega`; the class is exported by name (`Omega`) for tests only, and a consumer never writes `new`:
 
 ```js
 // src/main.js
-new (require('@omega.js/desktop/main'))().initialize();      // auto-loads JSON5 config
+const omega = require('@omega.js/desktop/main');        // auto-loads JSON5 config
+omega.initialize().then(() => { const { logger, windows } = omega; });
 
 // src/preload.js
-new (require('@omega.js/desktop/preload'))().initialize();   // exposes window.desktop
+const omega = require('@omega.js/desktop/preload');     // exposes window.desktop
+omega.initialize();
 
 // src/assets/js/components/<view>/index.js
-new (require('@omega.js/desktop/renderer'))().initialize();
+import omega from '@omega.js/desktop/renderer';
+omega.initialize().then(() => { const { logger, desktop } = omega; });
 ```
 
-`manager.initialize()` runs a fixed boot order (startup → ipc → storage → theme → sentry → protocol → deepLink → appState → whenReady → autoUpdater → tray/menu/contextMenu → startup → omega → remoteConfig → remoteScripts → windows). See [docs/boot-sequence.md](../docs/boot-sequence.md) for the full ordered list + rationale.
+`initialize()` returns the instance, and `omega.ready` is the same promise, so a module that did not call it can still await it. In main, `omega.initialize()` runs a fixed boot order (startup → ipc → storage → theme → fontawesome → sentry → protocol → deepLink → authFlow → appState → context → usage → whenReady → autoUpdater → tray/menu/contextMenu → startup → auth → remoteConfig → remoteScripts → analytics → restartManager → windows). See [docs/boot-sequence.md](../docs/boot-sequence.md) for the full ordered list + rationale.
+
+### The instance (`omega`)
+
+- **main**: every lib is a plain property: `omega.windows`, `tray`, `menu`, `contextMenu`, `ipc`, `storage`, `deepLink`, `autoUpdater`, `appState`, `startup`, `protocol`, `authFlow`, `theme`, `fontawesome`, `context`, `usage`, `remoteConfig`, `remoteScripts`, `restartManager`, `analytics`, `sentry`, `logger`, plus `config`, the environment helpers, the URL helpers (`getApiUrl()`, `getWebsiteUrl()`, `getFunctionsUrl()`, `getAuthUrl()`), `quit()`, `relaunch()`, `openAuthFlow()`, `request(url, options)` (the client base's harmonized API fetch, carrying a fresh Bearer token from main's session when signed in) and `require(name)`. `omega.auth` is the signed-in account: `.user` (always a `User`), `.listen()`, `.signOut()`, `.getIdToken()`, `.handleToken()` ([docs/auth.md](../docs/auth.md)).
+- **preload**: exposes `window.desktop` through `contextBridge`; `omega.logger` and the environment helpers.
+- **renderer**: `@omega.js/client`'s base class (`omega.auth`, `omega.storage` the page store, `omega.bindings`, `omega.firestore`, ...) plus `omega.desktop`, the preload's bridge under main's names: `omega.desktop.{ipc,storage,theme,fontawesome,autoUpdater,analytics,context,usage,remoteConfig}`. `omega.desktop.storage` is the app store, async over IPC. The renderer carries the same auth click triggers as the extension's pages: `.omega-signin` runs main's `openAuthFlow()`, `.omega-account` opens the website's `/account` page in the user's browser, and `.omega-signout` (the client's trigger) signs the whole app out through main, whose broadcast then signs every window out ([docs/auth.md](../docs/auth.md)).
 
 ### Lib modules
 
-`src/lib/*.js` — every Electron concern its own module. Each exports a singleton with `initialize(manager)`. Deep dive per module: see `docs/<lib-name>.md`. Authoring guide (initialization contract, adding a new lib, flat-vs-split): [docs/lib-modules.md](../docs/lib-modules.md).
+`src/lib/*.js`: every Electron concern its own module. Each exports one object with `initialize(omega)`, and main hangs it on the instance by name. Deep dive per module: see `docs/<lib-name>.md`. Authoring guide (initialization contract, adding a new lib, flat-vs-split): [docs/lib-modules.md](../docs/lib-modules.md).
 
 | Module | Description |
 |---|---|
 | `ipc` | typed channel bus, single registration point |
 | `storage` | electron-store wrapper, sync main / async renderer via IPC |
-| `theme` | system-aware appearance — `nativeTheme.themeSource` ('system'/'light'/'dark'), persisted override, live `<html data-bs-theme>` in every renderer via matchMedia |
+| `theme` | system-aware appearance: `nativeTheme.themeSource` ('system'/'light'/'dark'), persisted override, live `<html data-bs-theme>` in every renderer via matchMedia |
 | `window-manager` | lazy-creation registry, bounds persistence, Discord-style hide-on-close, inset titlebar, dock-show on first window, re-surface on user re-launch |
 | `tray` / `menu` / `context-menu` | file-based definitions; unified id-path API; default templates with id-tagged items |
 | `startup` | `mode: 'normal' \| 'hidden'`; `'hidden'` bakes `LSUIElement: true` for zero dock bounce |
 | `app-state` | storage-backed launch flags + crash sentinel |
 | `protocol` | single-instance lock + scheme registration |
+| `fontawesome` | serves the bundled icon SVGs to renderers over IPC (`desktop:fontawesome:get`); the renderer auto-renders `fa-*` markup ([docs/fontawesome.md](../docs/fontawesome.md)) |
 | `deep-link` | unified deep-link dispatch (cold + warm start, mac + win + linux), built-in routes, pattern matching |
-| `client-bridge` | main = source-of-truth Firebase Auth, renderers reflect via IPC; session persists via `auth-persistence`; renderers push the @omega.js/client-resolved plan → `getResolvedPlan()` |
+| `auth` | `omega.auth`: main = source-of-truth Firebase Auth, renderers reflect via IPC; session persists via `auth-persistence`; renderers push the account document their client resolved, so main's `omega.auth.user` is the same `User` |
+| `auth-flow` | `omega.authFlow` / `omega.openAuthFlow()`: the sign-in round trip in the user's default browser, returning over the deep link (production) or a one-shot loopback listener (dev/test) |
 | `auth-persistence` | pluggable main-session vault (default: safeStorage OS-keychain encryption; `omega.authPersistence` config) |
 | `auto-updater` | electron-updater wrapper, idle-aware install, 30-day pending gate, dev simulation |
 | `sentry` | `@omega.js/monitoring` — the shared error-reporting contract, auto auth attribution, dev-mode gating |
-| `templating` | `{{ }}` token replacement (BXM/UJM convention), used at build time by `gulp/html` |
-| `context` | runtime info — `manager.context.{geolocation,client,session,app}` |
+| `templating` | `{{ }}` token replacement, used at build time by `gulp/html` |
+| `context` | runtime info: `omega.context.{geolocation,client,session,app}` |
 | `usage` | `opens` / `hoursTotal` / `hoursThisSession`; crash-safe |
 | `remote-config` | "Hot config" fetched from `${brand.url}/data/resources/main.json`, polled hourly |
-| `remote-scripts` | Emergency remote code execution — OPT-IN (`remoteScripts.enabled: true`) + https-only; fetches `${brand.url}/data/scripts/main.js`, content-hash dedup, async `manager` + `require` in scope |
+| `remote-scripts` | Emergency remote code execution: OPT-IN (`remoteScripts.enabled: true`) + https-only; fetches `${brand.url}/data/scripts/main.js`, content-hash dedup, async `omega` + `require` in scope |
 | `analytics` | GA4 Measurement Protocol; cross-platform `uuidv5` identity; the app's ONE sender — renderer events forward here over IPC ([docs/analytics.md](../docs/analytics.md)) |
 | `restart-manager` | external guardian app for crash relaunches — localhost HTTP protocol v1 (register/heartbeat/deregister), silent install when missing (mac zip / win NSIS `/S` / linux AppImage; RM self-updates via its own @omega.js/desktop autoUpdater); split dir ships the protocol SSOT the RM app imports |
 
 ### File-based feature definitions
 
-Trays, menus, and context-menus are NOT defined in config — they're defined in JS files the consumer authors at fixed conventional paths (`src/integrations/{tray,menu,context-menu}/index.js`). To opt out, call `manager.{tray,menu,contextMenu}.disable()` at runtime.
+Trays, menus, and context-menus are NOT defined in config: they're defined in JS files the consumer authors at fixed conventional paths (`src/integrations/{tray,menu,context-menu}/index.js`). To opt out, call `omega.{tray,menu,contextMenu}.disable()` at runtime. Each file exports one function of an object: `({ omega, tray })`, `({ omega, menu, defaults })`, and `({ omega, menu, params, webContents })` for the context menu, called per right-click.
 
 All three ship sensible default templates and share a unified id-path API (`.find/.has/.update/.remove/.enable/.show/.hide/.insertBefore/.insertAfter/.appendTo`), implemented once in `src/lib/_menu-mixin.js`. See [docs/tray.md](../docs/tray.md), [docs/menu.md](../docs/menu.md), [docs/context-menu.md](../docs/context-menu.md).
 
 ### Windows
 
-@omega.js/desktop does NOT auto-create any windows. Consumers call `manager.windows.create('main', { show: !startup.isLaunchHidden() })` from inside `manager.initialize().then(...)`. Inset titlebar by default; Discord-style hide-on-close on `main`; auto re-surface on user re-launch. See [docs/windows.md](../docs/windows.md).
+@omega.js/desktop does NOT auto-create any windows. Consumers call `omega.windows.create('main', { show: !startup.isLaunchHidden() })` from inside `omega.initialize().then(...)`. Inset titlebar by default; Discord-style hide-on-close on `main`; auto re-surface on user re-launch. See [docs/windows.md](../docs/windows.md).
 
 ### Icons
 
@@ -148,7 +159,7 @@ All three bundles strip `@dev-only` blocks in production builds — code between
 
 ### Config flow
 
-`config/omega.json5` (JSON5, in consumer; shared sections top-level + desktop settings under `targets.desktop`) → `Manager.getConfig()` (resolves via `@omega.js/config`: `targets.desktop` overlays the top level, brand-monorepo walk-up included), then applies derived defaults: `app.appId` ← `<certificates.providers.apple.bundleIdPrefix>.<brand.id>` with the brand id's dashes as dots, the very id the certificates service registers ([#909](https://github.com/Omega-JS-Stack/omega/issues/909); no prefix declared, and it falls back to the reverse-domain of `brand.url`, then `app.<brand.id>`), `app.productName` ← `brand.name`) → injected into the NODE bundles (main, preload) at build time as an esbuild `define` of `OMEGA_BUILD_JSON` plus a banner that assigns the same literal to `globalThis`, and written for the RENDERER as the ONE `dist/build.js` every view's shell loads with its first script tag ([#743](https://github.com/Omega-JS-Stack/omega/issues/743), the same file and the same load order web and the extension use). Runtime reads `OMEGA_BUILD_JSON.config` first (authoritative in packaged apps); dev falls back to resolving from disk.
+`config/omega.json5` (JSON5, in consumer; shared sections top-level + desktop settings under `targets.desktop`) → `build.getConfig()` (resolves via `@omega.js/config`: `targets.desktop` overlays the top level, brand-monorepo walk-up included), then applies derived defaults: `app.appId` ← `<certificates.providers.apple.bundleIdPrefix>.<brand.id>` with the brand id's dashes as dots, the very id the certificates service registers ([#909](https://github.com/Omega-JS-Stack/omega/issues/909); no prefix declared, and it falls back to the reverse-domain of `brand.url`, then `app.<brand.id>`), `app.productName` ← `brand.name`) → injected into the NODE bundles (main, preload) at build time as an esbuild `define` of `OMEGA_BUILD_JSON` plus a banner that assigns the same literal to `globalThis`, and written for the RENDERER as the ONE `dist/build.js` every view's shell loads with its first script tag ([#743](https://github.com/Omega-JS-Stack/omega/issues/743), the same file and the same load order web and the extension use). Runtime reads `OMEGA_BUILD_JSON.config` first (authoritative in packaged apps); dev falls back to resolving from disk.
 
 The wrapper is the ONE shape every OMEGA browser surface bakes ([#894](https://github.com/Omega-JS-Stack/omega/issues/894)): `{ config, package, mode, license, builtAt }`, with the build's own facts outside `config` and never part of the client contract. What goes INSIDE `config` differs by who reads the bundle:
 
@@ -157,7 +168,7 @@ The wrapper is the ONE shape every OMEGA browser surface bakes ([#894](https://g
 | main, preload | the WHOLE resolved config, as a `define` + banner in their own bundles. The main process BOOTS from it (a packaged app's `config/omega.json5` is inside the asar), so `platforms`, `startup`, `autoUpdate`, `releases` and the rest have to be there. Both are Node, neither is a public surface |
 | renderer | the browser subset, `clientConfig(resolved)` from `@omega.js/config` (the config guide's "The browser subset"), written to `dist/build.js` and loaded by the page template as `../../build.js` ahead of the view's own bundle. A renderer is a public surface: its bundle is readable from DevTools, so the GCP account facts, the signing certificates and the account admins are not in it, and the bundle itself carries no copy of the snapshot at all |
 
-The build facts include `runtime: 'electron'` ([#896](https://github.com/Omega-JS-Stack/omega/issues/896)): a packaged renderer is a browser with no Electron globals of its own, so @omega.js/client's sniff would answer `'web'` without the baked fact. `mode` is the three keys every surface records, `{ environment, build, publish }`; desktop's own `server` verdict stays inside `Manager.getMode()`.
+The build facts include `runtime: 'electron'` ([#896](https://github.com/Omega-JS-Stack/omega/issues/896)): a packaged renderer is a browser with no Electron globals of its own, so @omega.js/client's sniff would answer `'web'` without the baked fact. `mode` is the three keys every surface records, `{ environment, build, publish }`; desktop's own `server` verdict stays inside `build.getMode()`.
 
 Both halves carry the same name, so `renderer.js` hands `OMEGA_BUILD_JSON.config` to `@omega.js/client` exactly as an extension page and a web page do.
 
@@ -165,11 +176,11 @@ Required fields: `brand.id` + `brand.name`. Everything else has defaults. See [d
 
 ### Schema validation
 
-Every field in `config/omega.json5` is declared in `@omega.js/config`: the shared OMEGA schema plus the desktop refinements (`TARGET_SCHEMAS.desktop`), vendored into `dist/vendor/config/` and exposed to consumers as `require('@omega.js/desktop/config')`. Runs at boot (hard-fails `manager.initialize()` if invalid) AND in `gulp/audit` (plus build-pipeline extras). The audit reports the validator's WARNINGS too ([#911](https://github.com/Omega-JS-Stack/omega/issues/911)): `omega build` prints each one and counts it (`audit ok (1 warning)`), so a key the schema does not declare, which is exactly what a typo looks like, is seen at build time instead of dropped. See [docs/config-schema.md](../docs/config-schema.md).
+Every field in `config/omega.json5` is declared in `@omega.js/config`: the shared OMEGA schema plus the desktop refinements (`TARGET_SCHEMAS.desktop`), vendored into `dist/vendor/config/` and exposed to consumers as `require('@omega.js/desktop/config')`. Runs at boot (hard-fails `omega.initialize()` if invalid) AND in `gulp/audit` (plus build-pipeline extras). The audit reports the validator's WARNINGS too ([#911](https://github.com/Omega-JS-Stack/omega/issues/911)): `omega build` prints each one and counts it (`audit ok (1 warning)`), so a key the schema does not declare, which is exactly what a typo looks like, is seen at build time instead of dropped. See [docs/config-schema.md](../docs/config-schema.md).
 
 ### Cross-context helpers
 
-Four Managers (main / renderer / preload / build-time) all mix in shared helpers via `attachTo(Manager)`: `isDevelopment()`, `isProduction()`, `isTesting()`, `getWebsiteUrl()`, `getEnvironment()`, `getFunctionsUrl()`, `getApiUrl()`, `getAuthUrl()` (the sign-in URL that round-trips an auth token back into the app via the `auth/token` deep link; never link the bare `/signin` page; apps launch it via **`manager.openAuthFlow()`** (main), which opens the user's REAL default browser and, in dev/test where the custom scheme isn't OS-registered, swaps the final hop for a one-shot nonce-checked loopback listener (RFC 8252) feeding the same deep-link pipeline, `lib/auth-flow.js`). Use these instead of grepping `process.env` ad-hoc. `getEnvironment()` returns `'development' | 'testing' | 'production'` (mutually exclusive), and the three `is*()` checks DERIVE from it; gate side effects on the INTENTIONAL check (`isProduction()` for prod-only, `isDevelopment() || isTesting()` for local-or-test); never `!isDevelopment()`.
+The three process instances (main / preload / renderer) carry the shared helpers as methods, and the build module (`require('@omega.js/desktop/build')`) exports the environment four and `getVersion()` as plain functions: `isDevelopment()`, `isProduction()`, `isTesting()`, `getWebsiteUrl()`, `getEnvironment()`, `getFunctionsUrl()`, `getApiUrl()`, `getAuthUrl()` (the sign-in URL that round-trips an auth token back into the app via the `auth/token` deep link; never link the bare `/signin` page; apps launch it via **`omega.openAuthFlow()`** (main), which opens the user's REAL default browser and, in dev/test where the custom scheme isn't OS-registered, swaps the final hop for a one-shot nonce-checked loopback listener (RFC 8252) feeding the same deep-link pipeline, `lib/auth-flow.js`). Use these instead of grepping `process.env` ad-hoc. `getEnvironment()` returns `'development' | 'testing' | 'production'` (mutually exclusive), and the three `is*()` checks DERIVE from it; gate side effects on the INTENTIONAL check (`isProduction()` for prod-only, `isDevelopment() || isTesting()` for local-or-test); never `!isDevelopment()`.
 
 **The environment four are `@omega.js/config`'s ONE module** ([#817](https://github.com/Omega-JS-Stack/omega/issues/817), the contract in full: [docs/shared/config.md](shared/config.md)): `src/utils/mode-helpers.js` re-exports them beside desktop's own `getVersion()`, so all four frameworks hang the identical functions. They read ONE input and never guess: `OMEGA_ENVIRONMENT` in Node, and the baked `OMEGA_BUILD_JSON.config.environment` in a renderer (which has none). Nothing sniffs `app.isPackaged` or `NODE_ENV` any more, and a context with neither input throws by name rather than defaulting; the old default here was `production`, so a plain `npm start` bundled itself as a production artifact while @omega.js/extension's copy of the same function answered `development`. `src/build.js` names the input at load, from the lane (`OMEGA_BUILD_MODE` is production and wins over an inherited value; the test runners name `testing`; a bare dev boot is `development`), and `main.js` names it from the baked config for a packaged app that has no parent lane: a FALLBACK for the context with no input, never an override of a lane that named one ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)). A renderer has no `process` either, so the preload hands it the running word on `window.desktop.environment` and the renderer bootstrap applies it over the bake, which is how a test lane booting a production artifact answers `testing` in every context of that app. See [docs/environment-detection.md](../docs/environment-detection.md).
 
@@ -227,8 +238,8 @@ See [docs/releasing.md](../docs/releasing.md) for the end-to-end flow.
 
 - **Consumer code can `require()` any @omega.js/desktop dependency** — the bundler re-resolves every name @omega.js/desktop DECLARES from the framework's own installation (`@omega.js/devkit/bundle`'s framework-deps hook). Consumer projects do NOT need to `npm install firebase`, `fs-jetpack`, `@omega.js/client`, or any other @omega.js/desktop dep. If a dep doesn't resolve, the fix is in @omega.js/desktop's `package.json` or its bundle task — not the consumer's `package.json`.
 - **The framework's copy wins ([#87](https://github.com/Omega-JS-Stack/omega/issues/87)).** Every name @omega.js/desktop DECLARES is re-resolved from the framework root by `@omega.js/devkit/bundle`'s resolve hook, so a consumer that declares its own version of a framework dependency still bundles ONE copy — the framework's — the identical hook and guarantee @omega.js/web gives web consumers. npm nests a framework-private copy only when the consumer's declaration conflicts, so this picks the nested copy on a conflict and the shared hoisted copy otherwise. There is no per-dependency override today, so a consumer that genuinely needs its OWN copy of a framework-carried package should raise it upstream ([#87](https://github.com/Omega-JS-Stack/omega/issues/87)) rather than pin and silently lose. Narrower than the webpack `resolve.modules` ordering it replaced ([#737](https://github.com/Omega-JS-Stack/omega/issues/737)): a package the framework only carries TRANSITIVELY is no longer forced to the framework's copy, because the hook reads the declared set. @omega.js/extension is on the same hook since [#738](https://github.com/Omega-JS-Stack/omega/issues/738); pinned by `src/test/suites/build/framework-deps.test.js` in each.
-- **@omega.js/client owns Firebase.** Consumer code NEVER imports Firebase directly (`require('firebase')` / `import('firebase/app')`). Use `require('@omega.js/client')` → `omega.auth()`, `omega.firestore()` in renderers. In main process, use `manager.omega` (the @omega.js/desktop bridge). Same rule in BXM and UJM.
-- **`Manager.require(name)`** resolves from @omega.js/desktop's module context at runtime (static + prototype). Use in gulp tasks or unbundled code (e.g. test fixtures). The bundle task's framework-deps hook handles the bundled case.
+- **@omega.js/client owns Firebase.** Consumer code NEVER imports Firebase directly (`require('firebase')` / `import('firebase/app')`). In renderers use `omega.auth` and `omega.firestore` on the renderer instance. In the main process, use `omega.auth` (the @omega.js/desktop bridge). Same rule on every OMEGA browser surface.
+- **`omega.require(name)`** (main) resolves from @omega.js/desktop's module context at runtime. Use in gulp tasks or unbundled code (e.g. test fixtures). The bundle task's framework-deps hook handles the bundled case.
 
 ## Development Workflow
 
@@ -272,7 +283,7 @@ Don't ship behavioral changes with stale docs. Validate first, then document —
 
 API references for each subsystem live in `docs/`. **Whenever you make a behavioral change, update both this overview AND the relevant `docs/*.md` deep reference.** Treat docs as a first-class deliverable, not an afterthought.
 
-- [docs/boot-sequence.md](../docs/boot-sequence.md) — full `manager.initialize()` ordered list + rationale
+- [docs/boot-sequence.md](../docs/boot-sequence.md): full `omega.initialize()` ordered list + rationale
 - [docs/lib-modules.md](../docs/lib-modules.md) — lib initialization contract, adding a new lib, flat-vs-split convention
 - [docs/storage.md](../docs/storage.md) — main + renderer storage, dot-notation, change broadcasts
 - [docs/ipc.md](../docs/ipc.md) — typed channel bus
@@ -283,7 +294,7 @@ API references for each subsystem live in `docs/`. **Whenever you make a behavio
 - [docs/startup.md](../docs/startup.md) — launch modes, zero-bounce production
 - [docs/app-state.md](../docs/app-state.md) — launch flags, crash sentinel
 - [docs/deep-link.md](../docs/deep-link.md) — cross-platform deep links, single-instance, built-in routes
-- [docs/client-bridge.md](../docs/client-bridge.md) — Firebase auth state sync across main + renderers, session persistence (safeStorage vault), the renderer @omega.js/client auth cycle (`data-omega-bind` bindings live in every renderer) + the resolved-plan push (`getResolvedPlan()`)
+- [docs/auth.md](../docs/auth.md): `omega.auth`, Firebase auth state sync across main + renderers, session persistence (safeStorage vault), the renderer @omega.js/client auth cycle (`data-omega-bind` bindings live in every renderer) + the account push that builds main's `omega.auth.user`
 - [docs/auto-updater.md](../docs/auto-updater.md) — startup + periodic checks, 30-day pending-update gate, idle-aware install
 - [docs/analytics.md](../docs/analytics.md) — GA4 Measurement Protocol, cross-platform `uuidv5` identity
 - [docs/context.md](../docs/context.md) — runtime context block (geolocation, client, session, app)
@@ -295,17 +306,17 @@ API references for each subsystem live in `docs/`. **Whenever you make a behavio
 - [docs/sentry.md](../docs/sentry.md) — the desktop half of `@omega.js/monitoring`, auto auth attribution
 - [docs/templating.md](../docs/templating.md) — `{{ }}` token replacement, page vars, HTML pipeline
 - [docs/logging.md](../docs/logging.md) — runtime logger (main + preload + renderer → one `runtime.log`)
-- [docs/themes.md](../docs/themes.md) — vendored classy + bootstrap themes, per-page CSS bundles, system-aware appearance (`manager.theme`)
+- [docs/themes.md](../docs/themes.md): vendored classy + bootstrap themes, per-page CSS bundles, system-aware appearance (`omega.theme`)
 - [docs/tooltips.md](../docs/tooltips.md) — Bootstrap JS ships in @omega.js/desktop (prebuilt bundle, Popper inlined): zero-setup auto-initialized tooltips, `window.bootstrap` namespace
 - [docs/css.md](../docs/css.md) — SCSS architecture: main entry, theme `@use` config, per-window bundles, Bootstrap-first
 - [docs/hooks.md](../docs/hooks.md): lifecycle hooks (build/pre, build/post, release/pre, release/post, notarize/post, deploy/pre)
 - [docs/shared/icons.md](../docs/icons.md) — convention-only icon resolution (`global/` + per-platform), retina derivation, macOS Template magic
-- [docs/fontawesome.md](../docs/fontawesome.md) — Font Awesome Free served from the npm dep (icon semantics shared with web via @omega.js/client's icon-core): `<i class="fa-solid fa-*">` auto-render, `manager.fontawesome.get`
+- [docs/fontawesome.md](../docs/fontawesome.md): Font Awesome Free served from the npm dep (icon semantics shared with web via @omega.js/client's icon-core): `<i class="fa-solid fa-*">` auto-render, `omega.desktop.fontawesome.get`
 - [docs/verts.md](../docs/verts.md) — `[data-omega-vert]` auto-bind to @omega.js/client's verts module (live via MutationObserver): house/company lane ONLY (type pinned 'house' — no AdSense in desktop surfaces)
 - [docs/installer-options.md](../docs/installer-options.md) — per-target installer config, defaults table
 - [docs/signing.md](../docs/signing.md) — code signing for macOS + Windows
 - [docs/releasing.md](../docs/releasing.md) — end-to-end release walkthrough
-- [docs/runner.md](../docs/runner.md): Windows EV-token signing runner. The listener runs with a private HOME (`%LOCALAPPDATA%\omega-runner\home`, holding a real `.gitconfig`), written at install and healed by `start`/`restart`, so a job's `actions/checkout` never copies the box's symlinked `~/.gitconfig` into a junction it cannot read ([#807](https://github.com/Omega-JS-Stack/omega/issues/807)). The same install writes the box's JOB GUARD ([#875](https://github.com/Omega-JS-Stack/omega/issues/875)): a job-started hook beside the runner, pointed at through each registration's `ACTIONS_RUNNER_HOOK_JOB_STARTED`, that fails any job whose event is not a dispatch or whose repository or actor is not on the box's own allow lists
+- [docs/runner.md](../docs/runner.md): Windows EV-token signing runner. The listener runs with a private HOME (`%LOCALAPPDATA%\omega-runner\home`, holding a real `.gitconfig`), written at install and healed by `start`/`restart`, so a job's `actions/checkout` never copies the box's symlinked `~/.gitconfig` into a junction it cannot read ([#807](https://github.com/Omega-JS-Stack/omega/issues/807)). The same install writes the box's JOB GUARD ([#875](https://github.com/Omega-JS-Stack/omega/issues/875)): a job-started hook beside the runner, pointed at through each registration's `ACTIONS_RUNNER_HOOK_JOB_STARTED`, that fails any job whose event is not a dispatch or whose repository or actor is not on the box's own allow lists. `start` is the one command a box operator runs ([#937](https://github.com/Omega-JS-Stack/omega/issues/937)): it installs a bare box, refreshes a stale actions/runner download in place, and registers any admin org the box does not serve yet before bringing every org online
 - [docs/test-framework.md](../docs/test-framework.md) — writing tests, running them, layers
 - [docs/test-boot-layer.md](../docs/test-boot-layer.md) — the `boot` test layer: consumer end-to-end smoke + @omega.js/desktop's framework self-test from the repo via the bundled fixture (`src/test/fixtures/consumer-app/`) + `OMEGA_TEST_BOOT_PROJECT` (@omega.js/desktop's analog of @omega.js/backend/BXM/UJM `*_TEST_BOOT_PROJECT`)
 - [docs/build-system.md](../docs/build-system.md) — gulp, esbuild, electron-builder pipeline

package/docs/ipc.md

@@ -5,15 +5,15 @@ Typed channel bus for main ↔ renderer communication. All @omega.js/desktop fea
 ## Main-process API
 
 ```js
-manager.ipc.handle(channel, async (payload, evt) => result)   // request/response
-manager.ipc.unhandle(channel)
-manager.ipc.invoke(channel, payload)                          // call locally (also what renderer triggers)
-manager.ipc.on(channel, (payload, evt) => void)               // one-way subscribe (renderer → main)
-manager.ipc.off(channel, fn)
-manager.ipc.broadcast(channel, payload)                       // → all BrowserWindows
-manager.ipc.send(webContents, channel, payload)               // → one renderer
-manager.ipc.hasHandler(channel)
-manager.ipc.listenerCount(channel)
+omega.ipc.handle(channel, async (payload, evt) => result)   // request/response
+omega.ipc.unhandle(channel)
+omega.ipc.invoke(channel, payload)                          // call locally (also what renderer triggers)
+omega.ipc.on(channel, (payload, evt) => void)               // one-way subscribe (renderer → main)
+omega.ipc.off(channel, fn)
+omega.ipc.broadcast(channel, payload)                       // → all BrowserWindows
+omega.ipc.send(webContents, channel, payload)               // → one renderer
+omega.ipc.hasHandler(channel)
+omega.ipc.listenerCount(channel)
 ```
 
 ## Renderer-process API (via preload contextBridge)
@@ -51,7 +51,7 @@ Registration is validated for you (above) — payload CONTENT is not. Treat ever
 
 ```js
 // main
-manager.ipc.handle('user:get-token', async (payload) => {
+omega.ipc.handle('user:get-token', async (payload) => {
   const token = await fetchToken(payload.userId);
   return { token };
 });

package/docs/lib-modules.md

@@ -1,6 +1,6 @@
 # Lib Modules
 
-`src/lib/*.js` — every Electron concern is its own module. Each exports a singleton with `initialize(manager)`; the main-process Manager wires them in a fixed order at boot (see [boot-sequence.md](boot-sequence.md)). Each module's deep reference lives at `docs/<lib-name>.md`; the module list is in the framework guide's Architecture section ([docs/desktop/index.md](../../../docs/desktop/index.md)).
+`src/lib/*.js`: every Electron concern is its own module. Each exports one object with `initialize(omega)`; the main-process instance hangs each on itself by name and initializes them in a fixed order at boot (see [boot-sequence.md](boot-sequence.md)). Each module's deep reference lives at `docs/<lib-name>.md`; the module list is in the framework guide's Architecture section ([docs/desktop/index.md](../../../docs/desktop/index.md)).
 
 ## Lib initialization contract
 
@@ -9,10 +9,10 @@ Each lib exposes the same skeleton:
 ```js
 const myLib = {
   _initialized: false,
-  _manager: null,
+  _omega: null,
 
-  initialize(manager) {
-    myLib._manager = manager;
+  initialize(omega) {
+    myLib._omega = omega;
     // wire IPC handlers, app event listeners, etc.
     myLib._initialized = true;
   },
@@ -33,9 +33,9 @@ Don't use `EventEmitter` unless the lib genuinely emits multiple event types. Fo
 
 ## Adding a new lib
 
-1. Create `src/lib/<name>.js` exporting a singleton object with `initialize(manager)`.
-2. Wire it into the boot order in `src/main.js` (or the renderer/preload Manager if it's a per-context lib) — check [boot-sequence.md](boot-sequence.md) for where it belongs and what it may depend on.
-3. Attach it to `Manager.prototype` as `manager.<camelCaseName>` so consumers can access it at runtime.
+1. Create `src/lib/<name>.js` exporting one object with `initialize(omega)`.
+2. Wire it into the boot order in `src/main.js` (or the renderer/preload class if it's a per-context lib): check [boot-sequence.md](boot-sequence.md) for where it belongs and what it may depend on.
+3. Set it on the instance in the `Omega` constructor as `this.<camelCaseName>`, so consumers reach it at runtime as `omega.<camelCaseName>`.
 4. Write tests at every layer the lib has a surface in (see [test-framework.md](test-framework.md)) — at minimum `src/test/suites/main/<name>.test.js`.
 5. Add a `docs/<name>.md` deep reference, add the module's row to the Lib modules table in the framework guide (`docs/desktop/index.md`), and link it from the Documentation index.
 
@@ -48,6 +48,6 @@ Don't use `EventEmitter` unless the lib genuinely emits multiple event types. Fo
 
 ## See also
 
-- [boot-sequence.md](boot-sequence.md) — the fixed `manager.initialize()` order + rationale
-- [environment-detection.md](environment-detection.md) — cross-context helpers shared by all four Managers via `attachTo(Manager)`
+- [boot-sequence.md](boot-sequence.md): the fixed `omega.initialize()` order + rationale
+- [environment-detection.md](environment-detection.md): cross-context helpers shared by the three processes and the build module
 - [test-framework.md](test-framework.md) — the four-layer harness new libs must ship tests in

package/docs/logging.md

@@ -20,25 +20,23 @@
 
 ## How to write logs
 
-In **main process** (uses the same `manager.logger` you've always had):
+In **main process**:
 
 ```js
-const Manager = require('@omega.js/desktop/main');
-const manager = new Manager();
-await manager.initialize();
+const omega = require('@omega.js/desktop/main');
+await omega.initialize();
 
-manager.logger.log('booted');
-manager.logger.warn('connection slow');
-manager.logger.error(new Error('boom'));
+omega.logger.log('booted');
+omega.logger.warn('connection slow');
+omega.logger.error(new Error('boom'));
 ```
 
 In **preload**:
 
 ```js
-const Manager = require('@omega.js/desktop/preload');
-const manager = new Manager();
-await manager.initialize();
-manager.logger.log('preload ready');
+const omega = require('@omega.js/desktop/preload');
+await omega.initialize();
+omega.logger.log('preload ready');
 ```
 
 In **renderer** (use the contextBridge surface, which forwards to main → file):
@@ -52,7 +50,7 @@ window.desktop.logger.error(new Error('ui blew up'));
 All three end up in the same `runtime.log`, prefixed with their scope (`main`, `preload`, `renderer`):
 
 ```
-[2026-05-05 14:32:11.045] [info] main manager.initialize
+[2026-05-05 14:32:11.045] [info] main omega.initialize
 [2026-05-05 14:32:11.122] [info] main ipc ready
 [2026-05-05 14:32:11.187] [info] preload contextBridge exposed
 [2026-05-05 14:32:11.401] [info] renderer auth.listen attached
@@ -108,7 +106,7 @@ Useful for:
 
 Beyond what you write yourself, @omega.js/desktop emits a fixed set of high-signal lifecycle lines so post-mortem debugging works without redeploying:
 
-**At boot (`manager.initialize()`):**
+**At boot (`omega.initialize()`):**
 
 ```
 (main)     Initializing @omega.js/desktop (main)... pid=12345 platform=darwin arch=arm64 packaged=true argv=["--omega-launched-at-login"]
@@ -118,7 +116,7 @@ Beyond what you write yourself, @omega.js/desktop emits a fixed set of high-sign
 (startup)    process.arch:            arm64
 (startup)    app.isPackaged:          true
 (startup)    app.getLoginItemSettings(): {"status":"enabled","openAtLogin":true,"openAsHidden":false,"restoreState":false,"wasOpenedAtLogin":false,"wasOpenedAsHidden":false}
-(startup)    EM_/electron/node env:   {}
+(startup)    boot env:                {}
 (startup)  startup boot summary — RESOLVED values:
 (startup)    config.startup.mode:     normal
 (startup)    config.startup.openAtLogin: {enabled:true, mode:hidden}

package/docs/menu.md

@@ -4,13 +4,13 @@ File-based application menu (the macOS menu bar / Windows + Linux menu). Same bu
 
 ## Config
 
-No config block. Path is conventional: `src/integrations/menu/index.js`. To opt out, call `manager.menu.disable()` from your main entry.
+No config block. Path is conventional: `src/integrations/menu/index.js`. To opt out, call `omega.menu.disable()` from your main entry.
 
 ## Definition file
 
 ```js
 // src/integrations/menu/index.js
-module.exports = ({ manager, menu, defaults }) => {
+module.exports = ({ omega, menu, defaults }) => {
   // Easiest: start from the platform-aware default template.
   menu.useDefaults();
 
@@ -18,7 +18,7 @@ module.exports = ({ manager, menu, defaults }) => {
   menu.show('main/preferences');                // @omega.js/desktop ships this hidden by default
   menu.update('main/check-for-updates', { label: 'Get Latest Version' });
   menu.insertAfter('main/check-for-updates', {
-    id: 'main/account', label: 'Account...', click: () => manager.windows.show('account'),
+    id: 'main/account', label: 'Account...', click: () => omega.windows.show('account'),
   });
   menu.remove('view/reload');
   menu.hide('main/services');
@@ -39,7 +39,7 @@ menu.clear()                   // start over
 
 ## Id-path API
 
-Same shape across menu / tray / context-menu. Available **during definition** (on the `menu` builder arg) AND **at runtime** on `manager.menu`:
+Same shape across menu / tray / context-menu. Available **during definition** (on the `menu` builder arg) AND **at runtime** on `omega.menu`:
 
 ```js
 .find(idPath)                  // live descriptor or null
@@ -108,7 +108,7 @@ Every item in @omega.js/desktop's default template carries a stable id you can t
 
 ### Development menu (dev mode only)
 
-Top-level, only visible when `manager.isDevelopment()`. Mirrors legacy @omega.js/desktop's developer utilities.
+Top-level, only visible when `omega.isDevelopment()`. Mirrors legacy @omega.js/desktop's developer utilities.
 
 | ID | Item | Action |
 |---|---|---|
@@ -120,7 +120,7 @@ Top-level, only visible when `manager.isDevelopment()`. Mirrors legacy @omega.js
 
 ## Built-in framework items
 
-`main/check-for-updates` (mac) and `help/check-for-updates` (win/linux) are **wired to `manager.autoUpdater`**:
+`main/check-for-updates` (mac) and `help/check-for-updates` (win/linux) are **wired to `omega.autoUpdater`**:
 - Label updates dynamically: *Checking…*, *Downloading 42%*, *Restart to Update v1.2.3*, *You're up to date*.
 - Click triggers `autoUpdater.checkNow()` or `autoUpdater.installNow()` depending on state.
 
@@ -135,24 +135,24 @@ Same dynamic conveniences as tray:
 - `click` wrapped to catch errors
 - `submenu` recursively resolved
 
-## Runtime API on `manager.menu`
+## Runtime API on `omega.menu`
 
 ```js
-manager.menu.refresh()                         // re-evaluate dynamic state
-manager.menu.define(fn)                        // replace the whole definition at runtime
-manager.menu.destroy()                         // tear down (mostly for tests)
-manager.menu.disable()                         // turn the menu off entirely (idempotent)
+omega.menu.refresh()                         // re-evaluate dynamic state
+omega.menu.define(fn)                        // replace the whole definition at runtime
+omega.menu.destroy()                         // tear down (mostly for tests)
+omega.menu.disable()                         // turn the menu off entirely (idempotent)
 
 // Id-path API — same as listed above.
-manager.menu.find('main/check-for-updates')
-manager.menu.update('main/check-for-updates', { label: 'Updates...' })
-manager.menu.remove('view/reload')
-manager.menu.insertAfter('main/check-for-updates', { id: 'main/account', label: 'Account...' })
+omega.menu.find('main/check-for-updates')
+omega.menu.update('main/check-for-updates', { label: 'Updates...' })
+omega.menu.remove('view/reload')
+omega.menu.insertAfter('main/check-for-updates', { id: 'main/account', label: 'Account...' })
 
 // Inspection
-manager.menu.getItems()                        // top-level descriptors (shallow copy)
-manager.menu.isRendered()                      // bool
-manager.menu.getMenu()                         // the underlying Electron Menu instance
+omega.menu.getItems()                        // top-level descriptors (shallow copy)
+omega.menu.isRendered()                      // bool
+omega.menu.getMenu()                         // the underlying Electron Menu instance
 ```
 
 ## Default scaffold

package/docs/releasing.md

@@ -92,7 +92,7 @@ Every verb runs `ensureTarget()` first ([#675](https://github.com/Omega-JS-Stack
 `npx omega deploy` adds the network half as a precheck (`--no-secrets` opts out):
 
 - Validates signing prereqs (warns if missing — non-fatal).
-- Pushes the composed `.env` → GitHub Actions secrets over the `gh` CLI (`gh auth login`; a CI run, an empty cascade, no remote, or a checkout that is not the brand's declared repo skips loudly).
+- Pushes the composed `.env` → GitHub Actions secrets over the `gh` CLI (`gh auth login`; a CI run, an empty cascade, or no GitHub remote skips loudly, and a checkout whose `origin` is not the derived source repo refuses on the one drift line, `origin is <slug> but config derives <derived>: fix repo.org in config/omega.json5 or move the repo`, [#934](https://github.com/Omega-JS-Stack/omega/issues/934)).
 
 Now drop your cert files:
 
@@ -174,7 +174,9 @@ build             needs setup; matrix over the resolved OSes: npm ci, then
                   `npm run release:local` on mac and linux (sign, notarize, and
                   electron-builder publishes the DRAFT release in the brand's releases
                   repo), and `npm run package` on windows, whose unsigned output uploads
-                  as the `windows-unsigned` artifact
+                  as the `windows-unsigned` artifact, a one-day intermediate that
+                  windows-sign consumes in the same run (the releases repo is the
+                  durable home)
 windows-strategy  needs [setup, build]; reads platforms.windows.signing.strategy from config
                   (only when windows is in the matrix)
 windows-sign      the self-hosted EV-token box, hosted windows-latest for the cloud

package/docs/remote-config.md

@@ -17,7 +17,7 @@ remoteConfig: {
 
 ## Cadence
 
-Polled at the same interval as the auto-updater feed-check (`autoUpdater.feedCheckIntervalMs`, default 1h). Same job category (HTTP, low-frequency, network-dependent), so re-using the cadence keeps both poll-rates aligned. Fetch timeout is 60s; in tests both collapse to 500ms via `manager.isTesting()`.
+Polled at the same interval as the auto-updater feed-check (`autoUpdater.feedCheckIntervalMs`, default 1h). Same job category (HTTP, low-frequency, network-dependent), so re-using the cadence keeps both poll-rates aligned. Fetch timeout is 60s; in tests both collapse to 500ms via `omega.isTesting()`.
 
 ## Defaults — `get()` always returns SOMETHING usable
 
@@ -28,7 +28,7 @@ A key design point: **app boot never blocks on the fetch**. `initialize()` retur
 3. **Async, on the first successful background fetch:** server values overlay the defaults.
 4. **Async, on every subsequent successful fetch:** repeats step 3, fires `'update'` event so consumers can re-run gates.
 
-Defaults (exported as `manager.remoteConfig.DEFAULTS`):
+Defaults (exported as `omega.remoteConfig.DEFAULTS`):
 
 ```js
 {
@@ -59,10 +59,10 @@ function checkForceUpdate(cfg) {
 }
 
 // Run at boot — works against defaults / cached value / first fetch result, whatever's there.
-checkForceUpdate(manager.remoteConfig.get());
+checkForceUpdate(omega.remoteConfig.get());
 
 // Re-run on every fresh fetch so a server-side bump kicks in within an hour.
-manager.remoteConfig.on('update', checkForceUpdate);
+omega.remoteConfig.on('update', checkForceUpdate);
 ```
 
 ## Failure mode
@@ -74,11 +74,11 @@ Failure warnings are formatted through `src/utils/format-fetch-error.js` — one
 ## API
 
 ```js
-manager.remoteConfig.get();                     // → entire current config (cache-first, never blocks)
-manager.remoteConfig.get('versionRequired');    // → dot-path lookup
-manager.remoteConfig.get('settings.deep.path'); // → nested
-manager.remoteConfig.refreshNow();              // → force a fetch right now (returns Promise<data | null>)
-const off = manager.remoteConfig.on('update', (data) => { ... });
+omega.remoteConfig.get();                     // → entire current config (cache-first, never blocks)
+omega.remoteConfig.get('versionRequired');    // → dot-path lookup
+omega.remoteConfig.get('settings.deep.path'); // → nested
+omega.remoteConfig.refreshNow();              // → force a fetch right now (returns Promise<data | null>)
+const off = omega.remoteConfig.on('update', (data) => { ... });
 off();                                          // unsubscribe
 ```
 

package/docs/remote-scripts.md

@@ -31,14 +31,14 @@ Host a plain `.js` file at the source URL. The content is fetched as text and ex
 ### Example: force all users to update
 
 ```js
-await manager.autoUpdater.checkNow();
+await omega.autoUpdater.checkNow();
 ```
 
 ### Example: clear corrupted storage
 
 ```js
-manager.storage.delete('auth.staleToken');
-manager.storage.set('app.patched', true);
+omega.storage.delete('auth.staleToken');
+omega.storage.set('app.patched', true);
 ```
 
 ### Example: emergency restart with cache wipe
@@ -52,18 +52,18 @@ if (fs.existsSync(cacheDir)) {
   fs.rmSync(cacheDir, { recursive: true });
 }
 
-manager.relaunch({ force: true });
+omega.relaunch({ force: true });
 ```
 
 ### Example: redirect updater to a hotfix feed
 
 ```js
-manager.autoUpdater._autoUpdater.setFeedURL({
+omega.autoUpdater._autoUpdater.setFeedURL({
   provider: 'github',
   owner: 'myorg',
   repo: 'myapp-hotfix',
 });
-await manager.autoUpdater.checkNow();
+await omega.autoUpdater.checkNow();
 ```
 
 ### Example: version-gated fix (script handles its own gating)
@@ -73,7 +73,7 @@ const wv = require('wonderful-version');
 const appVersion = require('electron').app.getVersion();
 
 if (wv.greaterThanOrEqual(appVersion, '1.4.0') && wv.lessThan(appVersion, '1.6.0')) {
-  manager.storage.delete('corrupted.key');
+  omega.storage.delete('corrupted.key');
 }
 ```
 
@@ -89,9 +89,9 @@ Or return a 404 — fetch failures are caught and logged, never crash. Failure l
 
 ## Execution context
 
-The script runs via `new AsyncFunction('manager', 'require', code)`:
+The script runs via `new AsyncFunction('omega', 'require', code)`:
 
-- **`manager`** — the live main-process Manager singleton. Full access to all libs: `manager.storage`, `manager.autoUpdater`, `manager.windows`, `manager.ipc`, etc.
+- **`omega`**: the live main-process instance. Full access to all libs: `omega.storage`, `omega.autoUpdater`, `omega.windows`, `omega.ipc`, etc.
 - **`require`** — the real Node.js `require`. Can load `fs`, `path`, `child_process`, `electron`, or any installed package.
 - **`await`** — supported natively.
 
@@ -107,13 +107,13 @@ If the script throws, the error is logged but the hash is still stored (prevents
 
 ```js
 // Force-fetch and execute if the script changed
-await manager.remoteScripts.refreshNow();
+await omega.remoteScripts.refreshNow();
 
 // See the last execution ({ hash, timestamp } or null)
-manager.remoteScripts.getLastRun();
+omega.remoteScripts.getLastRun();
 
 // Wipe stored hash — next poll will re-run the current script
-manager.remoteScripts.clearExecuted();
+omega.remoteScripts.clearExecuted();
 ```
 
 ## Config