@omega.js/desktop 0.1.0

package/docs/installer-options.md

@@ -0,0 +1,162 @@
+# Installer & Distribution Options
+
+Single source of truth for everything that controls how your app is packaged + delivered to end users. @omega.js/desktop owns the *target type* choices (NSIS on Windows, DMG+zip on Mac, deb+AppImage on Linux) and lets you configure the per-target UX through a small set of config knobs.
+
+## Why @omega.js/desktop owns the target list
+
+@omega.js/desktop picks specific installer types because they're the only ones that play well with the auto-update mechanism + cross-platform release pipeline:
+
+| Platform | Target | Why |
+|---|---|---|
+| **macOS** | `dmg` + `zip` | DMG is the user-facing installer, zip is what `electron-updater` consumes for the auto-update feed. Universal binary (one .dmg works on Intel + Apple Silicon). |
+| **Windows** | `nsis` | The only target that integrates with `electron-updater` for delta updates. Squirrel.Windows works too but installs to a weird per-user location with no Add/Remove Programs entry. MSI uses Windows Installer's own update mechanism (no electron-updater). |
+| **Linux** | `deb` + `AppImage` (+ optional `snap`) | `deb` for Ubuntu/Debian/Mint users, `AppImage` for distro-agnostic distribution. `snap` opt-in for Snap Store distribution. |
+
+If you genuinely need a different target (Squirrel for "no installer UI" UX, MSI for enterprise, MAS for App Store), use the raw `electronBuilder` override block in `omega.json5` — that's an escape hatch into electron-builder's full config surface. We just don't expose those choices in the consumer-facing API to keep the default path safe.
+
+## Cross-platform fields (`app.*`)
+
+These apply identically on every OS — set them once.
+
+| Field | Default | What it does |
+|---|---|---|
+| `app.category` | `'productivity'` | Generic app category. @omega.js/desktop maps to `mac.category` (Apple UTI) and `linux.category` (freedesktop). Allowed: `productivity`, `developer-tools`, `utilities`, `media`, `social`, `network`. |
+| `app.copyright` | `'© {YEAR}, ITW Creative Works'` | Copyright string. `{YEAR}` token is expanded to the current year at build time, so the string stays current without consumers ever editing it. |
+| `app.languages` | `['en']` | Locale list. Applied as `mac.electronLanguages` (which strips other locales' `.lproj` dirs from the .app bundle). win/linux currently ignore this. |
+| `app.darkModeSupport` | `true` | macOS honors via `NSRequiresAquaSystemAppearance: false` in Info.plist. Win/linux ignore. |
+
+### Category mapping table
+
+| `app.category` | mac (`mac.category`) | linux (`linux.category`) |
+|---|---|---|
+| `productivity` (default) | `public.app-category.productivity` | `Utility` |
+| `developer-tools` | `public.app-category.developer-tools` | `Development` |
+| `utilities` | `public.app-category.utilities` | `Utility` |
+| `media` | `public.app-category.entertainment` | `AudioVideo` |
+| `social` | `public.app-category.social-networking` | `Network` |
+| `network` | `public.app-category.business` | `Network` |
+
+If you need a per-platform value not in the table, use the raw `electronBuilder.mac.category` / `electronBuilder.linux.category` override.
+
+## Windows (`platforms.win.*`)
+
+| Field | Default | What it does |
+|---|---|---|
+| `platforms.win.arch` | `['x64', 'ia32']` | Architectures. Single multi-arch NSIS installer ships both. |
+| `platforms.win.oneClick` | `true` | Slack-style: no installer wizard, just installs immediately to `%LocalAppData%\Programs\<App>`. Set to `false` for a standard "Next, Next, Finish" wizard. |
+| `platforms.win.desktopShortcut` | `true` | Create desktop shortcut. |
+| `platforms.win.startMenuShortcut` | `true` | Create Start menu entry. |
+| `platforms.win.runAfterFinish` | `true` | Auto-launch the app when the install completes. |
+| `platforms.win.perMachine` | `false` | Install for current user. Set `true` to install for all users (requires UAC elevation; **incompatible with `oneClick: true`**). |
+
+### Why `oneClick: true` by default
+
+Most Electron consumer apps default to `oneClick: true` (Slack, Discord) — it's a "nothing to think about" flow that gets users to your app fast. Trade-offs:
+- ✅ No installer wizard, no choices for the user, fastest install
+- ✅ Combined with `runAfterFinish: true`, the app just opens after install finishes
+- ❌ Cannot install per-machine (incompatible with multi-user environments / enterprise)
+- ❌ User can't pick install location (always per-user `%LocalAppData%`)
+
+If your app needs enterprise deployment, set `oneClick: false` to opt into the wizard installer with `perMachine: true`.
+
+### `ia32` (32-bit Windows)
+
+@omega.js/desktop ships `ia32` alongside `x64` in a single multi-arch installer. Real-world 32-bit Windows usage is <3%, but the cost of including it is just ~2x installer size + ~2x signing time — no separate code path. Worth keeping for the long-tail user on an old Win 10 machine. To drop, set `platforms.win.arch: ['x64']`.
+
+## macOS (`platforms.mac.*`)
+
+| Field | Default | What it does |
+|---|---|---|
+| `platforms.mac.arch` | `['universal']` | Architectures. `universal` produces one .dmg/.zip that runs on both Intel and Apple Silicon (electron-builder lipo's the two arch binaries together). Override to `['arm64']` or `['x64']` for single-arch builds. |
+| `platforms.mac.mas.*` | (stubbed) | Mac App Store distribution config. **Not yet implemented** — see "MAS distribution" below. |
+
+### Universal binary trade-off
+
+`universal` produces ~2x file size (~225MB vs ~117MB) and ~2x build time on the Mac CI runner (builds both archs sequentially then stitches with `lipo`). Win: one .dmg link to give users — no "which one do I download?" flow.
+
+### MAS distribution (stubbed)
+
+Mac App Store config keys exist in @omega.js/desktop (`platforms.mac.mas.{enabled, provisioningProfile, entitlements, entitlementsInherit}`) but **are not yet wired up** — setting `enabled: true` triggers an audit warning and is otherwise ignored. The standard DMG+zip targets still build normally.
+
+When MAS support lands, the work covered will be: separate `mas` target alongside DMG/zip, separate sandbox entitlements (4 plist files instead of 1), provisioning profile copy from `config/embedded.provisionprofile`, application-groups derivation, App Store Connect submission flow (manual via Transporter, not GH Releases).
+
+Reference plists from a working MAS-published Electron app (Slapform) are archived at `<em>/src/defaults/_mas/` for the eventual implementation.
+
+## Linux (`platforms.linux.*`)
+
+| Field | Default | What it does |
+|---|---|---|
+| `platforms.linux.arch` | `['x64']` | Architectures. ia32 is essentially extinct on modern Linux. |
+| `platforms.linux.snap.enabled` | `true` (in scaffold) | Snap Store publishing. @omega.js/desktop scaffold ships this `true`; programmatic callers without the field default to OFF. Auto-skipped if `SNAPCRAFT_STORE_CREDENTIALS` env is unset. |
+| `platforms.linux.snap.confinement` | `'strict'` | `strict` (sandboxed) or `classic` (unrestricted, requires Snap Store approval). |
+| `platforms.linux.snap.grade` | `'stable'` | `stable` or `devel`. |
+| `platforms.linux.snap.autoStart` | `true` | Register the snap to auto-start on login. |
+| `platforms.linux.snap.channels` | `['stable']` | Snap Store channels to publish to. |
+
+### Snap Store publishing
+
+Tri-state behavior:
+
+- **Field missing entirely** → off. `build-config.js` checks `=== true` strictly, so older configs / programmatic callers without the field don't suddenly emit a snap target.
+- **`enabled: true` (scaffold default) + no `SNAPCRAFT_STORE_CREDENTIALS`** → off, with a build-time log line: `Snap target enabled in config but SNAPCRAFT_STORE_CREDENTIALS not set — skipping snap target.` This means a fresh `mgr setup` produces a working `.deb + .AppImage` build out of the box without failing on a missing snap publish credential.
+- **`enabled: true` + `SNAPCRAFT_STORE_CREDENTIALS` set** → snap target emits, snap publishes on release.
+- **`enabled: false`** → off, regardless of credentials. Explicit opt-out.
+
+To turn snap publishing on for a project that already has the field set to `true`:
+
+1. Mint store credentials locally:
+   ```bash
+   snapcraft export-login -    # writes a credentials blob to stdout
+   ```
+2. Paste the entire blob (multi-line) into `.env` as `SNAPCRAFT_STORE_CREDENTIALS=...`.
+3. Run `npx omega push-secrets` to flow the secret to GitHub Actions.
+4. Next `npm run release` builds + uploads the snap automatically. No config flip needed.
+
+Reference: the workflow's Linux step conditionally installs `snapcraft` (`sudo snap install snapcraft --classic`) only when both (a) `platforms.linux.snap.enabled !== false` AND (b) `SNAPCRAFT_STORE_CREDENTIALS` secret is present. Mirrors the build-config-side gate.
+
+## File associations + custom protocols (uncommon)
+
+Available for the rare app that needs them — both pass through to electron-builder verbatim.
+
+```jsonc
+{
+  fileAssociations: [
+    { name: 'My Document', description: 'My App document', ext: 'mydoc', role: 'Editor' },
+  ],
+  protocols: [
+    { name: 'CustomScheme', schemes: ['mycustom'] },
+  ],
+}
+```
+
+`protocols` is **additive** — @omega.js/desktop auto-registers `<brand.id>://` for every app (handled by `lib/protocol.js` at runtime). Use this to add EXTRA schemes (e.g., to handle `mailto:` if you're a custom email client).
+
+99% of apps don't need either of these — leave both unset.
+
+## Raw `electronBuilder` overrides (escape hatch)
+
+For anything @omega.js/desktop doesn't expose, set the value directly on `config.electronBuilder.*` in `omega.json5`. @omega.js/desktop merges your overrides on top of its generated config:
+
+**Gotcha: the merge REPLACES arrays wholesale** (objects deep-merge, arrays don't). A `target:` override must restate the FULL target list — `target: [{ target: 'mas' }]` alone would silently DROP dmg+zip and break auto-update.
+
+```jsonc
+{
+  electronBuilder: {
+    mac: {
+      target: [
+        { target: 'dmg', arch: ['universal'] },            // restate @omega.js/desktop's defaults…
+        { target: 'zip', arch: ['universal'] },            // …(zip is the auto-update artifact)
+        { target: 'mas', arch: ['universal'] },            // …then add MAS
+      ],
+    },
+    win: {
+      target: [
+        { target: 'nsis', arch: ['x64', 'ia32'] },
+        { target: 'msi',  arch: ['x64'] },                 // add MSI alongside NSIS
+      ],
+    },
+  },
+}
+```
+
+Use this for: legacy apps migrating from a custom builder config, enterprise deployments needing MSI, MAS apps until first-class support lands. Generally try the framework-native config first.

package/docs/ipc.md

@@ -0,0 +1,61 @@
+# IPC
+
+Typed channel bus for main ↔ renderer communication. All @omega.js/desktop features register their channels through this single layer rather than calling `ipcMain.handle` directly, so you have one place to look and one place to instrument.
+
+## 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)
+```
+
+## Renderer-process API (via preload contextBridge)
+
+```js
+await window.desktop.ipc.invoke(channel, payload)   // → Promise<result>
+const off = window.desktop.ipc.on(channel, (payload) => { ... });
+window.desktop.ipc.send(channel, payload);          // fire-and-forget
+```
+
+## Channel naming
+
+framework-internal channels are prefixed `desktop:` (e.g. `desktop:storage:get`, `desktop:storage:change`). Consumers are free to use any namespace.
+
+## Validation
+
+- `handle()` throws if `channel` is empty/non-string or `handler` is non-function.
+- `handle()` throws on duplicate registration. Call `unhandle()` first if you need to swap.
+- `invoke()` rejects with a clear message if no handler is registered for the channel.
+- Handler errors propagate through `invoke()` (both main-local and renderer-side) — your renderer's `await window.desktop.ipc.invoke(...)` will reject with the original error message.
+
+## Zero-trust payloads
+
+Registration is validated for you (above) — payload CONTENT is not. Treat every payload reaching a `handle()` / `on()` callback as untrusted input: renderers can be compromised, and apps that embed remote web content (e.g. external pages in `WebContentsView`s) expose the IPC surface to code you don't control.
+
+- **Validate shape and values before acting** — types match, IDs are well-formed, enums are from the expected set, paths resolve inside the expected roots.
+- **Gate any URL arriving via IPC** through `sanitize-url.js` before `shell.openExternal` / `loadURL` (the zero-trust URL rule — see [common-mistakes.md](common-mistakes.md)).
+- **Never feed raw payload values** into filesystem paths, shell commands, or `webContents.executeJavaScript`.
+
+## Boot order
+
+`ipc` initializes **before** `storage` so that storage (and every other feature) can register handlers via `ipc.handle`. This is the canonical pattern: don't touch `ipcMain` directly.
+
+## Example
+
+```js
+// main
+manager.ipc.handle('user:get-token', async (payload) => {
+  const token = await fetchToken(payload.userId);
+  return { token };
+});
+
+// renderer
+const { token } = await window.desktop.ipc.invoke('user:get-token', { userId: 'abc' });
+```

package/docs/lib-modules.md

@@ -0,0 +1,53 @@
+# 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)).
+
+## Lib initialization contract
+
+Each lib exposes the same skeleton:
+
+```js
+const myLib = {
+  _initialized: false,
+  _manager: null,
+
+  initialize(manager) {
+    myLib._manager = manager;
+    // wire IPC handlers, app event listeners, etc.
+    myLib._initialized = true;
+  },
+
+  // Public API
+  doThing() { ... },
+
+  // Disable at runtime (idempotent)
+  disable() {
+    // tear down listeners; safe to call multiple times
+  },
+};
+
+module.exports = myLib;
+```
+
+Don't use `EventEmitter` unless the lib genuinely emits multiple event types. For "fires once when ready" use a promise; for "broadcasts changes" use IPC with renderer subscriptions.
+
+## 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.
+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.
+
+## Flat file vs directory split
+
+- **Default to flat `src/lib/<name>.js`.**
+- **Split into a directory** (`src/lib/<name>/{index,core,main,renderer,preload}.js`) ONLY when each Electron context has materially different logic that would force ugly runtime branching inside one file. `index.js` becomes a thin context detector that delegates.
+- `lib/sentry/` was that split (the SDK has separate main/renderer/preload entry points) until it moved WHOLE into `@omega.js/monitoring` (#380) — the backend and the client needed the same policy, so the shape it proved now lives in the shared package. `lib/restart-manager/` is split for a different, also-valid reason — a **shared-SSOT split**: its `protocol.js` (the wire contract) must be importable by the Restart Manager app via the `exports` map with zero Electron/@omega.js/desktop baggage, so the contract lives in its own pure-Node file next to the main-only `index.js` + `install.js`. `sign-helpers/` is a helpers directory, not a lib.
+- Don't split prophylactically; convert when the branching gets ugly.
+
+## 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)`
+- [test-framework.md](test-framework.md) — the four-layer harness new libs must ship tests in

package/docs/logging.md

@@ -0,0 +1,229 @@
+# Logging
+
+@omega.js/desktop ships a runtime logger that writes to **both the console and a file on disk**, so production issues are inspectable without remoting into the user's machine.
+
+## What you get
+
+- **One log file**, `runtime.log`, populated by all three Electron processes (main / preload / renderer)
+- **Live console output** during development (DevTools console for renderer, terminal stdout for main)
+- **Kept across boots** — never truncated; it rotates by size instead (see the lifetime table below), unlike `dev.log`/`build.log`/`test.log`
+- **Cross-process timestamps** so log lines from main + preload + renderer interleave in arrival order
+
+## Where the file lives
+
+| Mode | Location |
+|---|---|
+| Dev (`npm start`, `app.isPackaged === false`) | `<projectRoot>/logs/runtime.log` |
+| Prod (installed `.dmg` / `.exe` / `.deb`, `app.isPackaged === true`) | OS log dir: `~/Library/Logs/<ProductName>/runtime.log` (macOS), `%APPDATA%\<ProductName>\logs\runtime.log` (Windows), `~/.config/<ProductName>/logs/runtime.log` (Linux) |
+
+`<ProductName>` = `config.app.productName` (falls back to `config.brand.name`). @omega.js/desktop calls `app.setName(productName)` at boot so `app.getPath('logs')` uses the human-readable brand name, not `package.json#name`.
+
+## How to write logs
+
+In **main process** (uses the same `manager.logger` you've always had):
+
+```js
+const Manager = require('@omega.js/desktop/main');
+const manager = new Manager();
+await manager.initialize();
+
+manager.logger.log('booted');
+manager.logger.warn('connection slow');
+manager.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');
+```
+
+In **renderer** (use the contextBridge surface, which forwards to main → file):
+
+```js
+window.desktop.logger.log('user clicked Save');
+window.desktop.logger.warn('IPC slow');
+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.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
+[2026-05-05 14:32:12.998] [warn] main auto-updater check failed: network
+```
+
+Grep one context with:
+
+```bash
+grep ' main ' logs/runtime.log
+```
+
+## CLI: `npx omega logs`
+
+For dev-loop convenience. From the consumer project root:
+
+| Command | Effect |
+|---|---|
+| `npx omega logs` | Print path, then `tail -50` of the file |
+| `npx omega logs --tail` (or `-f`) | Follow mode (like `tail -f`). Ctrl+C to stop. Cross-platform. |
+| `npx omega logs --path` (or `-p`) | Print the resolved path only (pipe-friendly) |
+| `npx omega logs --open` | Open the log file in OS default editor |
+| `npx omega logs --lines=100` | Default mode with custom tail length |
+
+### The surface argument
+
+An optional positional names which of the project's logs to read — `npx omega logs [runtime|dev|build|test]`, resolving `<cwd>/logs/<surface>.log`. It defaults to `runtime`, and every flag above works the same on whichever surface was named:
+
+```bash
+npx omega logs dev --tail       # follow the gulp pipeline live
+npx omega logs test --lines=100 # last 100 lines of the previous test run
+npx omega logs build --path     # just the path, for piping
+```
+
+Anything else fails naming the four surfaces. (The four files themselves are described in the lifetime table below; `ci.log` and `signing.log` are not tail targets.)
+
+`mgr logs` only resolves the dev path (`<cwd>/logs/<surface>.log`). To find the production runtime log on a user's machine, use the table above or call `getLogFilePath()` from app code.
+
+## How to find the file path from app code
+
+```js
+const LoggerLite = require('@omega.js/desktop/lib/logger-lite');
+const filePath = LoggerLite.getLogFilePath();
+// → '/Users/<user>/Library/Logs/MyApp/runtime.log' in production
+```
+
+Useful for:
+- "Send us your log" buttons in your settings UI
+- Programmatic log shipping (e.g. POSTing the file to your support backend)
+- Crash reporters that want to attach the runtime log
+
+## What @omega.js/desktop logs automatically
+
+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()`):**
+
+```
+(main)     Initializing @omega.js/desktop (main)... pid=12345 platform=darwin arch=arm64 packaged=true argv=["--omega-launched-at-login"]
+(startup)  startup boot summary — RAW inputs:
+(startup)    process.argv:            ["--omega-launched-at-login"]
+(startup)    process.platform:        darwin
+(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)  startup boot summary — RESOLVED values:
+(startup)    config.startup.mode:     normal
+(startup)    config.startup.openAtLogin: {enabled:true, mode:hidden}
+(startup)    isDev:                   false
+(startup)    hasLoginArg:             true
+(startup)    wasLaunchedAtLogin():    true (via argv-flag)
+(startup)    isLaunchHidden():        true
+```
+
+The boot summary has two parallel blocks: **RAW inputs** (what the OS / shell gave us) and **RESOLVED values** (what @omega.js/desktop decided to act on). Use it to debug both directions:
+- "Why is @omega.js/desktop behaving like X?" → check resolved values
+- "Why did @omega.js/desktop decide X?" → check raw inputs
+
+The `via:` annotation on `wasLaunchedAtLogin()` distinguishes a real login launch (`via:macos-wasOpenedAtLogin`) from a flag-based simulation (`via:argv-flag` — i.e. the user passed `--omega-launched-at-login`).
+
+**App lifecycle events** (logged from `main.js`):
+
+```
+app event: before-quit (entering quit sequence — close events bypass hide-on-close)
+app event: will-quit
+app event: quit code=0
+app event: window-all-closed
+app event: activate (macOS — dock click or app re-launch)
+app event: open-url url=myapp://auth/token?...
+app event: render-process-gone reason=crashed exitCode=139
+app event: child-process-gone type=GPU reason=killed exitCode=9
+process exit code=0
+uncaughtException: <stack>
+unhandledRejection: <stack>
+```
+
+**Window lifecycle events** (per named window, logged from `window-manager`):
+
+```
+createNamed: building "main" (show=false, hideOnClose=true)
+createNamed: loaded /path/to/app.asar/dist/views/main/index.html for "main"
+window "main": ready-to-show — staying invisible (show:false at create)
+window "main": ready-to-show — surfacing
+window "main": show event
+window "main": hide event
+window "main": focus event
+window "main": minimize event
+window "main": restore event
+window "main": close intercepted (hide-on-close) — hiding instead
+window "main": close allowed (hideOnClose=true, allowQuit=false, isQuitting=true, force=false)
+window "main": closed (destroyed)
+```
+
+**Re-surface handlers**:
+
+```
+activate (macOS) — surfacing main (visible=false, minimized=false)
+_ensureDockVisible — calling dock.show()
+_ensureDockVisible — dock already visible
+second-instance — argv=["..."] cwd=/...
+second-instance — surfacing main (visible=false, minimized=false)
+```
+
+These cover everything you'd want when debugging "why did the app go invisible / crash / fail to surface" without needing to attach a debugger.
+
+## Log levels
+
+Standard: `log`, `info`, `warn`, `error`, `debug`. All levels are written to both transports by default.
+
+To dial down via env vars (useful in CI to silence verbose framework noise):
+
+| Var | Effect |
+|---|---|
+| `OMEGA_LOG_LEVEL_FILE=warn` | Only `warn` + `error` reach the file |
+| `OMEGA_LOG_LEVEL_CONSOLE=error` | Only `error` reaches stdout/stderr |
+
+Default is `silly` (everything) on both.
+
+## How it works under the hood
+
+@omega.js/desktop's runtime logger (`lib/logger-lite.js`) detects which process it's in:
+
+- **Main**: writes to `runtime.log` directly via [electron-log](https://github.com/megahertz/electron-log)'s file transport. Sets up an IPC listener on channel `desktop:log:forward` to receive forwarded calls from preload + renderer.
+- **Preload**: writes to console (DevTools) AND forwards each call via `ipcRenderer.send('desktop:log:forward', ...)` to main.
+- **Renderer**: same as preload via `window.desktop.logger` (contextBridge surface).
+- **Outside Electron** (build/CLI tools that happen to require this module): falls back to console-only.
+
+File path resolution in main:
+1. Read `app.isPackaged`.
+2. If packaged → `app.getPath('logs')`.
+3. If dev → `<cwd>/logs/`.
+4. `mkdirSync` the dir, point electron-log at `<dir>/runtime.log`.
+
+The transport is set up lazily on first `log()` call, so importing `LoggerLite` in build/CLI contexts that have no Electron is harmless.
+
+## Coexisting with `dev.log`, `build.log`, `test.log`, and `ci.log`
+
+Five separate logs in `<projectRoot>/logs/`:
+
+| File | Source | Lifetime |
+|---|---|---|
+| `runtime.log` | Packaged-app runtime in dev mode | Persistent, rotates at 10 MB to `runtime.old.log` (one archive generation) |
+| `dev.log` | Gulp pipeline + spawned Electron child stdout (`npm start`) | Truncated each `npm start` |
+| `build.log` | Gulp pipeline output for production builds/packages (`npm run build` / `package` / `publish`, i.e. `OMEGA_BUILD_MODE=true`) | Truncated each build |
+| `test.log` | `npx omega test` runner output (suite names, pass/fail states, harness boot lines) | Truncated each test run |
+| `ci.log` | GH Actions release run output (streamed locally during `npm run release`) | Truncated each release run |
+| `signing.log` | JSONL signing events from Windows code-signing (local dev fallback; on CI this writes to the runner home as `omega-signing.log` instead) | Appended (not truncated) |
+
+`dev.log` and `build.log` are the same gulp tee — which one it writes is chosen by `OMEGA_BUILD_MODE`, so they never both fill up in one run. (Disable the tee with `OMEGA_LOG_FILE=false`; override its path with `OMEGA_LOG_FILE=<path>`.)
+
+They serve different purposes and don't overlap — `dev.log`/`build.log` show you "is the build still running?", `test.log` shows you "which test failed on the last run?", `ci.log` shows you "did the release workflow pass?", `runtime.log` shows you "is my app's auto-updater finding the right release feed?". All useful.
+
+In production: only `runtime.log` exists (no project, no gulp, no GH Actions stream).

package/docs/menu.md

@@ -0,0 +1,160 @@
+# Application Menu
+
+File-based application menu (the macOS menu bar / Windows + Linux menu). Same builder + id-path API as [tray](tray.md) and [context-menu](context-menu.md).
+
+## Config
+
+No config block. Path is conventional: `src/integrations/menu/index.js`. To opt out, call `manager.menu.disable()` from your main entry.
+
+## Definition file
+
+```js
+// src/integrations/menu/index.js
+module.exports = ({ manager, menu, defaults }) => {
+  // Easiest: start from the platform-aware default template.
+  menu.useDefaults();
+
+  // Mutate by id-path:
+  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'),
+  });
+  menu.remove('view/reload');
+  menu.hide('main/services');
+
+  // Or add a whole new top-level menu:
+  menu.menu('Tools', [{ id: 'tools/sync', label: 'Sync Now', click: () => {} }]);
+};
+```
+
+## Builder API (during definition)
+
+```js
+menu.menu(label, items)        // add a top-level menu bar entry
+menu.useDefaults()             // populate with the platform-appropriate default template
+menu.append(item)              // append a top-level descriptor (rare; prefer menu())
+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`:
+
+```js
+.find(idPath)                  // live descriptor or null
+.has(idPath)                   // bool
+.update(idPath, patch)         // Object.assign + re-render. returns true if found.
+.remove(idPath)                // splice + re-render. returns true if removed.
+.enable(idPath, bool = true)   // sugar over update({enabled})
+.show(idPath, bool = true)     // sugar over update({visible})
+.hide(idPath)                  // visible:false
+.insertBefore(idPath, item)    // splice in a sibling
+.insertAfter(idPath, item)     // splice in a sibling
+.appendTo(idPath, item)        // push into a submenu (creates submenu if absent)
+```
+
+Menu ids are **paths** because menus actually nest (`main/check-for-updates`, `view/developer/toggle-devtools`). @omega.js/desktop matches by full id field first; if that misses it walks the path treating each segment as the last component of an id.
+
+## Default template ids
+
+Every item in @omega.js/desktop's default template carries a stable id you can target.
+
+### macOS App menu (the one labeled with your app name)
+
+| ID | Item | Notes |
+|---|---|---|
+| `main/about` | About | |
+| `main/check-for-updates` | Check for Updates… | Auto-updater wired |
+| `main/preferences` | Preferences… | `visible:false` by default — use `menu.show('main/preferences')` |
+| `main/services` | Services submenu | |
+| `main/hide` | Hide | |
+| `main/hide-others` | Hide Others | |
+| `main/show-all` | Show All | |
+| `main/relaunch` | Relaunch | Restarts the app |
+| `main/quit` | Quit | |
+
+### File menu (win/linux equivalents of the App menu)
+
+| ID | Item | Notes |
+|---|---|---|
+| `file/close` | Close (mac only) | |
+| `file/preferences` | Preferences… (win/linux) | `visible:false` by default |
+| `file/relaunch` | Relaunch (win/linux) | |
+| `file/quit` | Exit | |
+
+### Cross-platform
+
+| ID | Item |
+|---|---|
+| `edit/undo`, `edit/redo`, `edit/cut`, `edit/copy`, `edit/paste`, `edit/select-all`, `edit/delete` | Edit submenu |
+| `edit/paste-and-match-style` | mac only |
+| `view/reload`, `view/reset-zoom`, `view/zoom-in`, `view/zoom-out`, `view/toggle-fullscreen` | View submenu |
+| `view/developer` | Submenu (dev mode only) |
+| `view/developer/toggle-devtools` | Toggle Developer Tools |
+| `view/developer/inspect-elements` | Inspect Element |
+| `view/developer/force-reload` | Force Reload |
+| `view/developer/simulate-update` | Simulate update submenu (see [docs/auto-updater.md](auto-updater.md)) |
+| `view/developer/simulate-update/available`, `.../unavailable`, `.../error` | Run the update simulator for one scenario |
+| `window/minimize`, `window/zoom`, `window/front` | Window submenu (mac) |
+| `window/minimize`, `window/close` | Window submenu (win/linux) |
+
+### Help menu
+
+| ID | Item | Notes |
+|---|---|---|
+| `help/check-for-updates` | Check for Updates… (win/linux only) | Auto-updater wired |
+| `help/website` | "`<brandName>` Home" | Only when `brand.url` configured |
+
+### Development menu (dev mode only)
+
+Top-level, only visible when `manager.isDevelopment()`. Mirrors legacy @omega.js/desktop's developer utilities.
+
+| ID | Item | Action |
+|---|---|---|
+| `development/open-exe-folder` | Open exe folder | Reveals `app.getPath('exe')` |
+| `development/open-user-data` | Open user data folder | Reveals `app.getPath('userData')` |
+| `development/open-logs` | Open logs folder | Reveals `app.getPath('logs')` |
+| `development/open-app-config` | Open app config folder | Reveals `app.getPath('appData')` |
+| `development/test-error` | Throw test error | Throws an uncaught error (verifies sentry / error handling) |
+
+## Built-in framework items
+
+`main/check-for-updates` (mac) and `help/check-for-updates` (win/linux) are **wired to `manager.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.
+
+The same hook also patches the tray's `check-for-updates` item if present, so both UIs stay in lockstep.
+
+Patch or remove either as needed — the auto-updater hook is a no-op when the item is missing.
+
+## Item descriptors
+
+Same dynamic conveniences as tray:
+- `label` / `enabled` / `visible` / `checked` may be functions, evaluated on every `refresh()`
+- `click` wrapped to catch errors
+- `submenu` recursively resolved
+
+## Runtime API on `manager.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)
+
+// 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...' })
+
+// Inspection
+manager.menu.getItems()                        // top-level descriptors (shallow copy)
+manager.menu.isRendered()                      // bool
+manager.menu.getMenu()                         // the underlying Electron Menu instance
+```
+
+## Default scaffold
+
+The scaffold every verb runs ships `src/integrations/menu/index.js` calling `menu.useDefaults()` plus commented-out examples (show preferences, insertAfter, update, remove, hide, add a Tools menu, appendTo).