@omega.js/desktop 0.1.0

package/docs/cdp-debugging.md

@@ -0,0 +1,169 @@
+# CDP Debugging (Claude ↔ Electron)
+
+@omega.js/desktop's `serve` task forwards all `--` CLI flags to the Electron child process. This enables Chrome DevTools Protocol (CDP) debugging, which lets Claude (or any CDP client) interact with the running Electron app — take screenshots, click elements, type text, evaluate JS, read console logs, inspect network requests, etc.
+
+Two ways to use it: **the built-in `npx omega cdp` toolkit** (below — zero setup, multi-target, knows @omega.js/desktop's conventions) and the `chrome-devtools-electron` MCP (further down — richer single-page interaction: click/fill/network/traces).
+
+## Launching with CDP
+
+Two equivalent ways:
+
+```bash
+# Env var (recommended)
+OMEGA_CDP_PORT=9222 npm start
+
+# CLI flag
+npm start -- --remote-debugging-port=9222
+```
+
+Both add `--remote-debugging-port=9222` to the Electron spawn args. The env var takes precedence if both are set; a CLI flag already present won't be duplicated.
+
+Verify CDP is live:
+
+```bash
+curl -s http://localhost:9222/json
+# Returns JSON array of page targets (one per BrowserWindow)
+```
+
+## The `mgr cdp` toolkit
+
+Zero-dependency subcommands for driving the running dev app — see, act, and run the no-watch iterate loop. All read `OMEGA_CDP_PORT` (default 9222), or take `--port <n>` (which wins).
+
+**Pinning a port in an npm script? Use `--port`, never `cross-env`.** `npx cross-env OMEGA_CDP_PORT=… npx omega cdp eval … "window.desktop.ipc.invoke('my:channel')"` STRIPS the inner quotes from the expression before it reaches V8 (`invoke(my:channel)` → `SyntaxError: missing ) after argument list`). `npx omega cdp eval … "…" --port <n>` keeps the expression intact.
+
+```bash
+npx omega cdp status                          # running? targets, window rect, theme
+npx omega cdp eval <match> '<expr>'           # evaluate JS in any webContents
+npx omega cdp shot <match> <out.png>          # ONE renderer's own pixels
+npx omega cdp capture <out.png>               # the COMPOSITED window (macOS)
+npx omega cdp theme <dark|light|system>       # flip the live theme (manager.theme)
+npx omega cdp relaunch                        # quit → npm start → wait for boot
+npx omega cdp quit                            # quit + wait for the process tree to drain
+```
+
+### The multi-target model
+
+An @omega.js/desktop app is one window but potentially MANY webContents (every BrowserWindow + every `WebContentsView` is its own CDP page target). Every subcommand takes a **URL-substring matcher** instead of a "current page": the main window's document is always `/views/main/` (@omega.js/desktop's templating convention); other views match by their own URLs. `status` lists what's live.
+
+```bash
+npx omega cdp eval "/views/main/" 'document.title'
+npx omega cdp eval "example.com" 'getComputedStyle(document.body).backgroundColor'
+npx omega cdp eval "/views/main/" "window.desktop.ipc.invoke('my-app:some-channel')"   # the real IPC surface
+```
+
+Promises are awaited, results print as JSON, and expressions run with a user gesture (focus()/clipboard-ish APIs behave like real input).
+
+### shot vs capture — the compositing discriminator
+
+`shot` asks ONE renderer for its own surface; `capture` photographs the window the OS composited (the BrowserWindow document + every WebContentsView stacked). They answer different questions:
+
+- Styling wrong in one view? → `shot` that target.
+- Layering/transparency/z-order wrong? → `capture`; if `shot` looks right but `capture` doesn't, the bug is in compositing, not your CSS.
+
+Caveats:
+- `shot` needs a VISIBLE surface — a hidden view (`setVisible(false)`, a background view) produces no compositor frames and the capture times out. Show/select it first.
+- `capture` raises the app and region-captures its rect — anything overlaying that region still wins. For an occlusion-proof image: `--find-window-id` (slow Swift path; JXA's CoreGraphics bridge segfaults) → `capture <out.png> --window-id <id>` (the ID is stable per window lifetime — cache it).
+- **Color profiles:** macOS embeds the MONITOR's ICC profile in screenshot PNGs; many viewers (including image previews in tooling) misrender it dramatically — an opaque dark panel can read near-white. `capture` converts every file to sRGB via `sips`, so it's portable. Hand-rolled screencaptures should do the same: `sips -m "/System/Library/ColorSync/Profiles/sRGB Profile.icc" shot.png --out shot.png`.
+- `capture`, `relaunch`, and `quit` are macOS-only (screencapture / sips / osascript). `status`/`eval`/`shot`/`theme` are cross-platform.
+
+### relaunch / quit — the iterate loop
+
+@omega.js/desktop dev has **no watch** (`npm start` builds once, then runs) — every `src/` edit needs quit → rebuild → boot. `relaunch` is that loop in one command: it quits the app (real quit — `before-quit` handlers run), waits for the **full process tree to drain** (port-down alone is NOT that signal — the npm-start chain takes a few more seconds, and a test run started inside that window gets contaminated with flaky boot suites), spawns a detached `npm start` with `OMEGA_CDP_PORT`, and waits for the boot signal. `quit` is the first half alone — safe to run `npx omega test` the moment it returns. **Never run tests while the app is going down** (a test run started before the process tree drains gets contaminated) — boot tests build into their own `.omega/test-app/` output since #110, so `dist/` itself no longer collides.
+
+The boot signal defaults to the main window's document target. Apps whose boot completes later than first paint override it in `config/omega.json5`:
+
+```json5
+cdp: {
+  readySignal: 'my-app://overlay',   // URL substring of the target that appears LAST in boot
+}
+```
+
+The packaged-app process name (for quit/raise/window-id matching) comes from config too: `app.productName` (derived from `brand.name`); dev builds run under "Electron".
+
+## Driving a regular Chrome (not the app)
+
+Sometimes the thing to drive is a regular **Chrome** — the marketing site, a web flow, an OAuth page — not the Electron app.
+
+> Mirrored across the five sister frameworks (UJM / @omega.js/backend / BXM / @omega.js/desktop / @omega.js/client) — same core section, framework-flavored. Edit all five together.
+
+Browser work runs through the **`chrome-devtools` MCP** (via mcp-router). There is NO launch procedure anymore — no ports, no profile dirs, no curl checks:
+
+- **Just call the tools** — `new_page`, `navigate_page`, `take_screenshot`, `click`, `fill`, `evaluate_script`, `list_console_messages`, `list_network_requests`. The browser auto-launches on the first call.
+- **Each Claude session gets its OWN private Chrome** (`--isolated`): temp profile, CDP over an internal pipe. Parallel sessions cannot see or touch each other's pages — open and close pages freely, the whole browser is yours.
+- **It dies with the session.** No orphans, no cleanup, nothing to kill.
+- **Ephemeral profile** — cookies/logins do NOT persist between sessions. If a flow needs auth, log in during the task.
+- **Self-signed HTTPS is pre-accepted** (`--acceptInsecureCerts` in the upstream) — dev servers load without certificate interstitials.
+- **NEVER quit/kill Chrome by app name** (`killall "Google Chrome"`, osascript) — that's the user's personal browser, not yours.
+
+Humans: the agent's Chrome window is visible — you can watch it drive. Full reference: `~/.claude/mcp-server/servers/chrome-devtools/CLAUDE.md`.
+
+@omega.js/desktop specifics:
+
+- **The Electron app stays attach-by-port** — that's the whole rest of this doc (`mgr cdp` per invocation, or the `chrome-devtools-electron` MCP below). Port convention: **9222** = the Electron app. The isolated `chrome-devtools` browser has nothing to do with the app.
+- **Navigating to a brand's UJM dev site (the local marketing site)?** **`https://localhost:4000` — NEVER the LAN IP** (`https://192.168.x.x:...`). Port 4000 by default, increments to 4001+ when multiple sites run; exact port in `.temp/_config_browsersync.yml` at the root of the WEBSITE project (the UJM consumer — e.g. `<brand>-website/.temp/_config_browsersync.yml`, NOT this app repo).
+
+## What CDP exposes
+
+- **Renderer processes only** — one "page" target per BrowserWindow. Main process is NOT exposed (use `--inspect=9229` for that, which is a separate V8 inspector protocol).
+- Each BrowserWindow appears as a separate page target. MCP tools with `list_pages`/`select_page` can switch between them.
+- Chromium silently ignores flags it doesn't recognize, so gulp's own flags (`--cwd`, `--gulpfile`) pass through harmlessly.
+
+## MCP setup (Claude ↔ Electron)
+
+A `chrome-devtools-electron` MCP upstream is configured at `~/.claude/mcp-server/servers/chrome-devtools-electron/config.json`. It reads `OMEGA_CDP_PORT` from the environment at spawn time (defaults to 9222), so the same upstream works for any Electron app — just set the env var **BEFORE launching `claude`** (it's expanded once, when the session's router spawns the upstream; mid-session changes do nothing).
+
+```json
+{
+  "enabled": true,
+  "command": "sh",
+  "args": ["-c", "exec /Users/ian/.nvm/default-bin/npx -y chrome-devtools-mcp@latest --browserUrl=http://127.0.0.1:${OMEGA_CDP_PORT:-9222} --usage-statistics=false"]
+}
+```
+
+This runs alongside the regular `chrome-devtools` upstream (which launches its own per-session isolated browser — no env vars, no ports). Tools are namespaced:
+- `chrome-devtools__take_screenshot` → the session's own Chrome browser
+- `chrome-devtools-electron__take_screenshot` → the running Electron app
+
+Multiple Claude sessions can debug different apps simultaneously — each terminal sets its own `OMEGA_CDP_PORT`. See `~/.claude/mcp-server/README.md`.
+
+### Available MCP tools (29)
+
+Screenshots, click, fill, type, hover, drag, evaluate JS, list/read console messages, list/inspect network requests, navigate, resize, keyboard input, accessibility snapshots, Lighthouse audits, performance traces, heap snapshots, dialog handling.
+
+### Session setup
+
+If the upstream was added/enabled after a Claude session started, its tools won't appear until next session. To enable mid-session:
+
+```
+# From shell
+mcp enable chrome-devtools-electron
+
+# From inside Claude (if upstream is enabled on disk but not in session)
+router__enable_upstream { name: "chrome-devtools-electron" }
+```
+
+## Port conventions
+
+| Port | Protocol | Usage |
+|------|----------|-------|
+| 9222 | CDP (HTTP + WebSocket) | Electron renderer debugging (standard CDP port) |
+| 9229 | V8 Inspector | Node.js / Electron main process debugging (`--inspect`) |
+
+Use 9222 for `--remote-debugging-port` (industry standard). Avoid 9229 — that's the Node.js inspector port and a different protocol.
+
+## Security
+
+CDP gives full control of the renderer — any local process can connect and read/modify anything. **Never ship with `--remote-debugging-port` baked in.** It's dev-only, gated behind `OMEGA_CDP_PORT` which is never set in production.
+
+## How it works
+
+`src/gulp/tasks/serve.js` collects extra args in two ways:
+
+1. **CLI flags**: `process.argv.slice(2).filter(arg => arg.startsWith('--'))` — forwards all `--` flags from the gulp process to Electron
+2. **`OMEGA_CDP_PORT` env var**: if set and no `--remote-debugging-port` is already in the args, appends `--remote-debugging-port=${OMEGA_CDP_PORT}`
+
+The args are passed to `spawn(electronBin, ['.', ...extraArgs])`. The main process boot log shows the received argv:
+
+```
+[info] (main) Initializing @omega.js/desktop (main)... argv=[".","--remote-debugging-port=9222"]
+```

package/docs/client-bridge.md

@@ -0,0 +1,267 @@
+# Client Bridge — Auth State Sync
+
+@omega.js/desktop keeps Firebase auth state in sync across all processes (main + every renderer window). The pattern mirrors BXM's background/foreground architecture: **main is the source of truth**, renderers reflect.
+
+## Why this exists
+
+In Electron, you can't just initialize Firebase in the renderer and forget about it:
+
+- Multiple renderer windows would each have their own Firebase instance with no coordination.
+- Main-process code (tray, menu, deep-link routes) needs to know who's signed in.
+- A deep-link auth-token (`myapp://auth/token?token=...`) arrives in main, but the user's UI lives in the renderer — somebody has to bridge them.
+
+The bridge handles all three.
+
+## How it works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  MAIN (client-bridge.js)                               │
+│  - Owns Firebase Auth instance ("omega-auth" app)              │
+│  - Source of truth for auth state                           │
+│  - Listens for desktop:auth:* IPC from renderers                 │
+│  - Broadcasts desktop:auth:* IPC to all renderers on changes     │
+└─────────────────────────────────────────────────────────────┘
+              ▲                     │ broadcasts
+              │ sync-request        ▼
+┌──────────────────────────┐  ┌──────────────────────────┐
+│  RENDERER (window 1)     │  │  RENDERER (window 2)     │
+│  @omega.js/client + Firebase  │  │  @omega.js/client + Firebase  │
+└──────────────────────────┘  └──────────────────────────┘
+```
+
+### Auth flow: deep-link → all processes signed in
+
+**Consumers never collect credentials.** There is no login form to build — call `manager.openAuthFlow()` (documented in `lib/auth-flow.js`), which opens the brand website's sign-in page in the user's browser and receives the result through the deep link below.
+
+1. User signs in on the website. Web-manager generates a custom token. Website opens `myapp://auth/token?token=XYZ` (deep link).
+2. @omega.js/desktop's deep-link `auth/token` built-in fires `manager.omega.handleAuthToken(token)`.
+3. Main calls `signInWithCustomToken(auth, token)` against its own Firebase Auth → main is now signed in.
+4. Main broadcasts `desktop:auth:sign-in-with-token` IPC with the same token to all renderer windows.
+5. Each renderer receives the broadcast, calls `omega.auth().signInWithCustomToken(token)` against its own (@omega.js/client-managed) Firebase Auth → all renderers signed in with the same user.
+6. Tokens are NOT stored — they expire in 1 hour. Auth state persists via Firebase's built-in IndexedDB persistence.
+
+### Auth flow: renderer load → sync with main
+
+When a renderer window opens (cold or warm), it asks main for the current state:
+
+1. Renderer sends `desktop:auth:sync-request` IPC with its current UID (or null).
+2. Main compares with its own UID:
+   - **Same UID** → no sync needed, returns `{ needsSync: false }`.
+   - **Main signed out, renderer signed in** → returns `{ needsSync: true, signOut: true }`. Renderer signs out.
+   - **Main signed in, renderer not (or different user)** → main fetches a fresh custom token from `POST ${apiUrl}/omega/user/token` (responds `{ token }`) and returns `{ needsSync: true, customToken, user }`. Renderer signs in with that token.
+
+### Sign-out flow
+
+Any renderer (or main code) calls `manager.omega.signOut()`:
+
+1. Main signs out its own Firebase.
+2. Main broadcasts `desktop:auth:sign-out` IPC to all renderers.
+3. Each renderer signs out its own Firebase.
+
+## Public API
+
+### Main process (`manager.omega`)
+
+```js
+// Sign in via a custom token (called automatically by the auth/token deep-link route).
+await manager.omega.handleAuthToken(token);
+
+// Read the currently signed-in user (snapshot, no sensitive fields).
+manager.omega.getCurrentUser();
+//   → { uid, email, displayName, photoURL, emailVerified } | null
+
+// Fresh Firebase ID token for calling authenticated backend routes from main
+// (send as `Authorization: Bearer <token>`). null when signed out.
+await manager.omega.getIdToken();
+
+// Subscribe to auth state changes (e.g. to refresh tray/menu items).
+const off = manager.omega.onAuthChange((user) => {
+  manager.tray.refresh();
+  manager.menu.refresh();
+});
+off();   // unsubscribe
+
+// Sign out from any process.
+await manager.omega.signOut();
+
+// The renderer-resolved subscription — THE main-side plan source. Renderers run
+// @omega.js/client's full auth cycle (Firestore account fetch → resolveSubscription)
+// and push the result to main (desktop:auth:account-resolved, uid-guarded); main can't
+// run Firestore itself. null until a renderer has resolved.
+manager.omega.getResolvedPlan();
+//   → { plan, active, trialing, cancelling } | null
+manager.omega.getResolvedRoles();
+//   → { admin, betaTester, ... } | null
+```
+
+### Renderer process (the @omega.js/desktop Manager you `initialize()`)
+
+```js
+// Read the user from main (always returns main's authoritative state).
+const user = await renderer.getMainUser();
+
+// Sign out (goes through main; broadcasts to all other renderers).
+await renderer.signOut();
+```
+
+The renderer's `Manager.initialize()` automatically:
+- Boots @omega.js/client (so renderer-side Firebase is available).
+- Wires the auth bridge (`desktop:auth:sync-request` on load + listens for broadcasts).
+- Runs @omega.js/client's **full auth cycle** (`auth().listen()`): waits for auth to settle,
+  fetches the Firestore account, resolves the subscription, and auto-populates the
+  **`data-omega-bind` bindings** — so @omega.js/desktop app views can use UJM/BXM-style reactive HTML
+  (`@show auth.user`, `@text auth.account.plan.id`, `@show auth.account.plan.id === 'premium'`,
+  see @omega.js/client's docs/bindings.md). Each settle pushes `{ resolved, roles }` to main
+  (`desktop:auth:account-resolved`) and re-offers it whenever main announces a state change,
+  so a renderer that resolved before main signed in still delivers.
+
+You don't write any of this — it just works.
+
+## Session persistence (main)
+
+Renderers persist their Firebase sessions in IndexedDB for free (browser contexts).
+Main is Node — Firebase defaults to in-memory there — so @omega.js/desktop plugs in its own vault:
+**`lib/auth-persistence.js`**, a PLUGGABLE strategy behind a custom Firebase
+`Persistence` (the `getReactNativePersistence()` shape).
+
+- **`safeStorage`** (default) — values encrypted via Electron `safeStorage` (macOS
+  Keychain / Windows DPAPI / kwallet-gnome) before touching disk
+  (`{userData}/omega-auth-session.json` holds base64 ciphertext only). This is the same
+  os_crypt machinery Chromium uses for its cookie jar — stronger than browser
+  IndexedDB/localStorage, which are plaintext LevelDB on disk.
+- **`none`** — explicit opt-out (in-memory, pre-1.12 behavior).
+- **Custom** — `require('@omega.js/desktop/lib/auth-persistence').register(name, { available, getItem, setItem, removeItem })` before `initialize()`, then select it via config.
+
+```jsonc
+{
+  "omega": {
+    "authPersistence": "safeStorage"   // 'safeStorage' (default) | 'none' | custom name
+  }
+}
+```
+
+Storage only — distribution across processes stays the IPC sync protocol above.
+The session restores at boot (offline included: no network round trip), so a restart
+keeps the user signed in; renderers then re-resolve the account and re-push the plan.
+
+## Config
+
+```jsonc
+{
+  "cloud": {
+    "provider": "firebase",
+    "config": {
+      "apiKey":            "...",
+      "authDomain":        "myapp.com",
+      "projectId":         "myapp",
+      // ... etc.
+    }
+  }
+}
+```
+
+If `cloud.config` is empty/missing, the bridge logs a warning and runs in no-op mode (everything returns harmless defaults).
+
+## Firebase (bundled)
+
+Firebase is **bundled from @omega.js/desktop's module context** (@omega.js/client owns it in @omega.js/desktop's dependency tree) — the same treatment `json5` gets in main. It was previously runtime-resolved, which silently failed in every symlinked dev app (see CHANGELOG 1.11.1).
+
+If you're building a no-auth Electron app, just leave `cloud.config` empty — the bridge is a clean no-op.
+
+In a TESTING run (`OMEGA_TEST_MODE=true`) the bridge connects its auth instance to the local auth emulator, on the port it reads in three steps: `OMEGA_AUTH_PORT` when the CLI that booted the stack published one, then the `dev.ports.auth` value the bundle baked into `OMEGA_BUILD_JSON` (a packaged main process has no parent env, [#745](https://github.com/Omega-JS-Stack/omega/issues/745)), then the classic `9099`. Same chain `getApiUrl()` walks ([environment-detection.md](environment-detection.md)) and the same move it makes when it maps testing to localhost, and the same one @omega.js/extension's background worker makes for its emulator runs; development and production are untouched.
+
+## Common patterns
+
+### Refresh tray when auth state changes
+
+```js
+// In src/tray/index.js or wherever you have access to manager:
+manager.omega.onAuthChange((user) => {
+  manager.tray.refresh();   // re-evaluates dynamic labels
+});
+```
+
+```js
+// In src/tray/index.js:
+tray.item({
+  label: () => {
+    const user = manager.omega.getCurrentUser();
+    return user ? `Signed in as ${user.email}` : 'Sign in';
+  },
+  click: () => {
+    if (manager.omega.getCurrentUser()) {
+      manager.omega.signOut();
+    } else {
+      require('electron').shell.openExternal(`${manager.config.brand.url}/sign-in?desktop=true`);
+    }
+  },
+});
+```
+
+### Gate a deep-link route on auth
+
+```js
+manager.deepLink.on('user/profile/:id', (ctx) => {
+  if (!manager.omega.getCurrentUser()) {
+    require('electron').shell.openExternal(`${manager.config.brand.url}/sign-in?return=profile/${ctx.params.id}`);
+    ctx.handled = true;
+    return;
+  }
+  manager.windows.show('main');
+  manager.windows.get('main').webContents.send('navigate', { to: `/profile/${ctx.params.id}` });
+});
+```
+
+### Sign-out button in a renderer
+
+```html
+<button id="signout">Sign out</button>
+<script>
+  document.getElementById('signout').addEventListener('click', async () => {
+    await renderer.signOut();   // goes through main, propagates everywhere
+  });
+</script>
+```
+
+## IPC channels
+
+| Channel | Direction | Payload | Description |
+|---|---|---|---|
+| `desktop:auth:sync-request` | renderer → main | `{ contextUid }` | "I'm at this UID, are we in sync?" |
+| `desktop:auth:sign-out` | renderer → main | (none) | "Sign me (and everyone) out." |
+| `desktop:auth:get-user` | renderer → main | (none) | Read main's current user. |
+| `desktop:auth:sign-in-with-token` | main → all renderers | `{ token }` | "Sign in with this custom token now." |
+| `desktop:auth:sign-out` | main → all renderers | `{}` | "Sign out now." |
+| `desktop:auth:state-changed` | main → all renderers | `{ uid, email, ... } \| null` | Auth state changed (informational). |
+
+## Testing
+
+### Unit tests (always run)
+
+`client-bridge.test.js` covers the dispatch logic, IPC handler shape, sync-request comparison, and the `auth/token` deep-link integration — all without hitting Firebase.
+
+### The real-surface e2e lane (monorepo root)
+
+`npm run test:e2e-desktop` ([scripts/e2e-desktop-auth.js](../../../scripts/e2e-desktop-auth.js)) boots a real Electron app against the backend emulator and delivers `<brand.id>://auth/token` from a SECOND instance — the OS-forwarded argv path — then asserts main AND the renderer both land on the emulator user. Offline; it is the lane that proves this whole chain end to end.
+
+### Extended tests (skip without opt-in + creds)
+
+`client-bridge.integration.test.js` actually mints custom tokens via `firebase-admin` and signs in — it hits REAL Firebase, so it's gated behind extended mode (the cross-framework `TEST_EXTENDED_MODE` opt-in; see [test-framework.md](test-framework.md#extended-vs-normal-mode)). To run:
+
+```bash
+npm i -D firebase-admin                                   # already in @omega.js/desktop's devDeps
+export OMEGA_TEST_FIREBASE_ADMIN_KEY=/path/to/service-account.json
+export OMEGA_TEST_USER_UID=desktop-test-user                      # optional, defaults to desktop-test-user
+npx omega test --extended                                   # or: TEST_EXTENDED_MODE=true npx omega test
+```
+
+Without the extended-mode opt-in the suite skips cleanly with a clear reason; same when `OMEGA_TEST_FIREBASE_ADMIN_KEY` (or `GOOGLE_APPLICATION_CREDENTIALS`) isn't set. CI without creds → tests stay green.
+
+## Implementation notes
+
+- Firebase app name in main is `omega-auth` (avoids clashes if a consumer's main code also wants its own Firebase instance).
+- The bridge does NOT persist user info to @omega.js/desktop storage — Firebase's IndexedDB persistence handles session restoration. Matches BXM.
+- Custom tokens are NEVER stored. Renderers receive them once via broadcast, sign in, discard. Fresh tokens are minted on demand from `POST /omega/user/token` via @omega.js/client's shared request layer (`createRequest` from `@omega.js/client/modules/request.js`) — same code path as the extension background's token sync.
+- `manager.getApiUrl()` returns the dev or prod URL, so the bridge automatically hits the right backend. Available across all four Manager contexts (main / renderer / preload / build) via the shared `src/utils/url-helpers.js` module — same code path everywhere. See the Cross-context helpers section of the framework guide ([docs/desktop/index.md](../../../docs/desktop/index.md)).
+- All sensitive Firebase user fields (`stsTokenManager`, `providerData`, etc.) are stripped before sending over IPC. Only `{uid, email, displayName, photoURL, emailVerified}` cross the bridge.

package/docs/common-mistakes.md

@@ -0,0 +1,21 @@
+# Common Mistakes to Avoid
+
+1. **Auto-creating windows in main.js** — @omega.js/desktop does NOT auto-create windows. The consumer's main.js must call `manager.windows.create('main', { show: !startup.isLaunchHidden() })` inside `manager.initialize().then()`. Always create `main` — even in hidden launches, with `show: false` — so the activate/second-instance handlers can surface UI on user re-launch.
+2. **Putting JS logic in config** — Trays / menus / context-menus are file-based (`src/integrations/<name>/index.js`). Click handlers, dynamic labels, conditional visibility — all live in the JS file. Don't try to express them in `omega.json5`.
+3. **Shipping `<slot>@2x.png` files** — Ship ONE file at the native (@2x) size; @omega.js/desktop downscales the @1x sibling. Bundled defaults work the same way. See [icons.md](icons.md).
+4. **Naming the macOS tray icon source `trayTemplate.png`** — The input filename is `tray.png` (matches Windows/Linux). @omega.js/desktop owns the `Template` magic when writing to dist.
+5. **Reading `process.cwd()` from packaged-app runtime code** — It's `/` in packaged apps. Use `require('./utils/app-root.js')()` (tries `app.getAppPath()` first, falls back for tests/non-Electron contexts).
+6. **Setting `enabled: true` to turn on sentry/analytics** — Wrong convention. Set the credentials (`monitoring.providers.sentry.dsn = '...'`, `analytics.providers.google.id = '...'`); presence enables. Same for `cloud.config`.
+7. **Defining cross-context helpers on individual Manager prototypes** — Use `attachTo(Manager)` in `src/utils/<topic>-helpers.js` so main/renderer/preload/build all share the same code path.
+8. **Trying to share a Manager instance across processes** — Each process has its own. They communicate via IPC (`manager.ipc.invoke/handle`).
+9. **Calling `shell.openExternal(url)` directly with a dynamic URL** — Gate through `require('./utils/sanitize-url.js')` first (returns `''` for non-http(s) protocols). Any dynamic URL must have its protocol filtered before navigation.
+10. **Hand-editing `dist/electron-builder.yml` or `dist/config/entitlements.mac.plist`** — Both are generated by `gulp/build-config` from `config/omega.json5` + @omega.js/desktop defaults. Edit the source config; the YAML/plist regenerate every build.
+11. **Forgetting that "build" failed but the .app launched anyway** — `ELECTRON_RUN_AS_NODE=1` makes Electron silently run as Node: `app` is undefined, no BrowserWindow, no window appears. The CLI boundary strips this var; if you see weird "nothing happens" launches in dev, check whether your shell has it set.
+12. **Hard-coding `EM_*` env vars in source** — Use `manager.isDevelopment()`, `manager.isProduction()`, `manager.isTesting()`, `manager.getEnvironment()` instead. See [environment-detection.md](environment-detection.md).
+13. **Installing @omega.js/desktop's dependencies as direct consumer deps** — Consumer projects must NOT `npm install firebase`, `fs-jetpack`, `@omega.js/client`, or any other @omega.js/desktop/@omega.js/client transitive dep. The bundler re-resolves every name @omega.js/desktop DECLARES from the framework's own installation (`@omega.js/devkit/bundle`'s framework-deps hook). If a dependency isn't resolving, the fix is in @omega.js/desktop's `package.json` or its bundle task — not the consumer's `package.json`. Mirrors BXM and UJM.
+14. **Touching Firebase directly in consumer code** — Firebase is owned by @omega.js/client. Consumer code NEVER does `require('firebase')` or `import('firebase/app')`. In renderers use `require('@omega.js/client')` → `omega.auth()`, `omega.firestore()`. In main process, use `manager.omega` (the @omega.js/desktop bridge). Same rule in BXM and UJM.
+15. **Forgetting `await` on `windows.create()`** — It's async and returns a Promise, not a BrowserWindow. Passing the Promise to code that calls `win.on(...)` silently fails with "is not a function".
+16. **Using raw `import()` for ESM-only deps** — Use `importESM(specifier)` from `utils/import-esm.js`. It tries the consumer's `node_modules/` first, then falls back to @omega.js/desktop's own copy. This means consumers don't need to install @omega.js/desktop's transitive ESM deps (they're resolved from @omega.js/desktop's `node_modules/` automatically). A dep import the bundler cannot inline (a variable specifier) only resolves from the consumer — if the dep isn't installed there, it fails silently.
+17. **Touching `process` in code shared with renderers** — With `contextIsolation: true` and `nodeIntegration: false` (the defaults), `process` does not exist in renderers — `process.platform` in a shared util throws a `ReferenceError`, it does not return `undefined`. Branch platform/env logic in main (or the preload) and hand the RESULT to the renderer (IPC, preload-exposed value, or a data attribute) — never share a util that dereferences `process` across contexts.
+18. **Expecting `target="_blank"` to work in a `file://` renderer** — Anchors with `target="_blank"` silently do nothing; there is no browser to open. External links go through `shell.openExternal` (gated per mistake 9) — wire a click handler or use the framework's external-link binding rather than a bare anchor.
+19. **Registering the brand-scheme handler on the default session only** — `protocol.handle('<brand.id>', handler)` covers ONLY the default session. Sessions from `session.fromPartition(...)` do NOT inherit it, and Electron auto-opens external protocols: a `brand://` load in a partitioned webContents is classified by Chromium as an EXTERNAL protocol and handed to the OS — macOS Launch Services then launches whatever installed app owns the scheme (an old production copy of YOUR app, mid-run). Silent in dev until it isn't. If your app uses partitions, register the same handler on every partition you vend, idempotently — e.g. a session-manager whose `getElectronSession()` does `ses.protocol.handle(scheme, handler)` guarded by a `WeakSet`. There is no Electron API to read a registered handler back, so this cannot be automated after the fact; register through one owned code path. (Candidate future @omega.js/desktop API: opt-in `manager.protocol.handle(handler)` that applies the handler to the default session + every `session-created` — see TODO.md.) The TEST harness already contains this class of escape during `mgr test` (stub brand handler + `openExternal` denied — see [test-framework.md](test-framework.md)), but that protects tests only, not your packaged app.

package/docs/config-schema.md

@@ -0,0 +1,120 @@
+# Config schema
+
+@omega.js/desktop validates `config/omega.json5` against the canonical OMEGA schema in **`@omega.js/config`** (vendored into `dist/vendor/config/` at prepare time; also exposed to consumers as `require('@omega.js/desktop/config')`). The shared schema covers the cross-framework sections (brand, cloud, analytics, payment, monitoring, connections, theme, targets); the desktop-specific refinements (app.category, platforms.win.signing.strategy, startup.mode, restartManager.*, …) live in the same package's `TARGET_SCHEMAS.desktop` and apply when validating with `{ target: 'desktop' }`. Validation always runs against the RESOLVED config — `targets.desktop` contents land at the top level (see the monorepo's `docs/shared/config.md` for the format).
+
+Validation runs in two places:
+
+1. **`Manager.initialize()` (boot)** — hard-fails the app at boot if any required field is missing or any present field is invalid. So a misconfigured app never reaches the "white window of confusion" phase — it tells you exactly which field is broken.
+2. **`gulp audit` (build)** — same schema, plus build-pipeline-specific extras (file-existence for icons, `releases.repo` in publish mode, etc.).
+
+## Schema entry shape
+
+```js
+{
+  path:        'brand.id',                     // dot-path into the config
+  type:        'string' | 'boolean' | 'number' | 'array' | 'object',
+  required:    true | false | (config) => bool,
+  match:       /^[a-z][a-z0-9+\-.]*$/,         // string-value regex
+  enum:        ['normal', 'hidden'],           // value-must-be-in-this-list
+  description: 'Used for the deep-link scheme + default appId.',
+}
+```
+
+## The `required` flag
+
+@omega.js/desktop keeps validation simple: **`required` is either `true`, `false`, or a function**.
+
+```js
+required: true                    // hard-fail if missing
+required: false                   // OK to omit (but if present, match/enum/type still run)
+required: (cfg) => bool           // conditional — predicate gets the full config
+```
+
+The function form is for "this field is mandatory only when another part of config is set." Illustrative shape (no current entry uses it — every present-day field is `true` or `false`):
+
+```js
+{
+  path:     'analytics.providers.google.id',
+  required: (cfg) => Boolean(cfg?.analytics?.providers?.google?.secret),  // id mandatory only when a secret is configured
+  match:    /^G-[A-Z0-9]+$/,
+}
+```
+
+This is identical strictness in dev and production. There's no separate `'publish-only'` tier — if a field truly matters only for builds, validate it inside `gulp/audit.js` (next to `fileMustExist` calls for icons, etc.) rather than the schema.
+
+## How `match` / `enum` / `type` interact with absence
+
+They **only run when the value is present**. A missing field with `required: false` is silent. A missing field with `required: true` fires the "missing" error and nothing else — so consumers don't see a confusing flood of "missing AND wrong type AND doesn't match" for the same field.
+
+## Presence-driven feature flags (@omega.js/backend convention)
+
+A non-empty credential value enables a feature — there is no separate `enabled: true/false` flag for credential-gated features:
+
+| Feature | Enable signal | Disable signal |
+|---|---|---|
+| Sentry | `monitoring.providers.sentry.dsn = 'https://...'` | `monitoring.providers.sentry.dsn = ''` |
+| GA4 analytics | `analytics.providers.google.id = 'G-XXXXX'` | `analytics.providers.google.id = ''` |
+| Firebase Auth (renderer) | `cloud.config.projectId = '...'` (etc.) | empty `cloud.config` |
+
+**Exceptions where an explicit `enabled` flag exists:** `remoteConfig.enabled`, `autoUpdate.enabled`, `releases.enabled`, `restartManager.enabled`, `startup.openAtLogin.enabled`, `platforms.linux.snap.enabled`. These toggle BEHAVIOR, not credentials — you can have `releases.repo` set but still want releases off in a fork, for example.
+
+## Adding a new field
+
+When you add a new config knob anywhere in @omega.js/desktop:
+
+1. Add an entry to `TARGET_SCHEMAS.desktop` in `@omega.js/config` (`packages/config/src/schema.js` in the Omega monorepo) — or to `SHARED_SCHEMA` if the field is genuinely cross-framework.
+2. If it has a default, set it in [`src/defaults/config/omega.json5`](../src/defaults/config/omega.json5) (under `targets.desktop` for desktop-scoped fields).
+3. That's it. No separate validation logic to add elsewhere — the schema entry is the validation.
+
+## What's NOT in the schema
+
+These checks live in [`gulp/tasks/audit.js`](../src/gulp/tasks/audit.js) instead, because they depend on build-pipeline state rather than the config shape:
+
+- **`src/main.js` / `src/preload.js` existence** — the bundle task skips them with a warning but the schema doesn't know about consumer entry points.
+- **`brand.images.icon` file existence** — only enforced when packaging (`isBuildMode()` / `isPublishMode()`); dev runs with the default Electron icon.
+- **`releases.repo` presence** — only enforced in publish mode.
+
+These are kept in `audit.js` so the schema stays a pure description of the config shape, callable from any context without dragging in build state.
+
+## Examples
+
+Required field missing:
+
+```
+@omega.js/desktop: config validation failed — fix the following in config/omega.json5:
+  1. config.brand.id is required — URL-scheme-safe slug. Used as deep-link scheme + default appId. Must be lowercase, start with a letter, alnum/+/-/.
+```
+
+Field present but invalid:
+
+```
+  1. config.startup.mode "tray-only" is not allowed — must be one of [normal, hidden]
+  2. config.brand.id "My App!" does not match expected pattern /^[a-z][a-z0-9+\-.]*$/ — URL-scheme-safe slug. Used as deep-link scheme + default appId. Must be lowercase, start with a letter, alnum/+/-/.
+```
+
+Errors are numbered so you can fix everything in one pass instead of fix-rebuild-fix-rebuild.
+
+## Adding payment fields (@omega.js/backend-shaped)
+
+@omega.js/desktop's schema mirrors [@omega.js/backend's `manager-config.example.json`](https://github.com/itw-creative-works/backend-manager) shape for payment so the same product catalog reads identically on backend, web, and desktop:
+
+```js
+{
+  payment: {
+    providers: {
+      stripe: { publishableKey: 'pk_live_...' },     // schema: match /^pk_(test|live)_/
+      paypal: { clientId: '...' },
+    },
+    products: [
+      { id: 'basic', name: 'Basic', type: 'subscription', limits: { credits: 100 } },
+    ],
+  },
+}
+```
+
+The schema only enforces shape for the few well-defined publishable keys — the product catalog itself is freeform so @omega.js/backend can extend it without @omega.js/desktop caring.
+
+## Source
+
+- Schema definitions + validator engine: `@omega.js/config` (`packages/config/src/{schema,validate}.js` in the Omega monorepo; vendored copy at `dist/vendor/config/`)
+- @omega.js/desktop integration tests: [`src/test/suites/build/validate-config.test.js`](../src/test/suites/build/validate-config.test.js)