@omega.js/desktop 0.1.0

package/dist/defaults/AGENTS.md

@@ -0,0 +1,109 @@
+# ========== Default Values ==========
+# OMEGA Desktop (@omega.js/desktop) consumer project
+
+<!-- MAINTAINERS (framework repo): this consumer template is MIRRORED across all OMEGA framework consumer templates (src/defaults/AGENTS.md ×N; web's lives at scaffold/AGENTS.md).
+  Same sections in the same order: framework-specific extras may be inserted; canonical sections are never reordered/renamed. Edit every framework consumer template together.
+  The mirroring rule lives in each framework guide's Doc-update parity section (docs/<framework>/index.md) -->
+
+## Framework
+
+This project consumes **OMEGA Desktop** (@omega.js/desktop), a comprehensive framework for building modern Electron desktop apps. @omega.js/desktop provides one-line-import bootstrap per Electron process, a modular feature library with file-based extensibility, a multi-platform build/release pipeline (DMG / NSIS / deb / AppImage), and a built-in four-layer test framework.
+
+## 🚨 READ THE FRAMEWORK DOCS FIRST
+
+**Before doing ANY work on this codebase, the agent MUST read the framework documentation: that is where the architecture, conventions, APIs, and gotchas live. Skipping these will result in solutions that conflict with framework patterns.**
+
+**Required reading:**
+- **`node_modules/@omega.js/AGENTS.md`**: the OMEGA map, the one agent entry into the framework docs; follow it to `docs/desktop/index.md` (the @omega.js/desktop guide: identity, architecture, conventions)
+- **`node_modules/@omega.js/desktop/docs/`**: subsystem deep references (read the relevant ones for the task at hand)
+
+## 🚨 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.
+
+**Required reading:**
+- **`node_modules/@omega.js/AGENTS.md`** → `docs/client/index.md`, the @omega.js/client guide: identity, module list, conventions
+- **`node_modules/@omega.js/client/docs/`**: module deep references (Auth, Bindings, Firestore, Notifications, etc.)
+
+## Quick start
+
+```bash
+npm start           # dev with auto-reload (gulp → esbuild → electron .)
+npm run build       # local production build (compiles bundles only, no installer)
+npm run package     # full local production package (DMG/zip/universal-mac, NSIS-win, deb+AppImage-linux)
+npm run package:quick   # fast packaged build for the host platform/arch only (~20-30s)
+npm run release     # signed + published release (requires certs)
+npx omega test        # run YOUR project's test suites (bare runs never include the framework corpus)
+npx omega test build/config         # run project tests by path (relative to test/; full:<path> for both sources)
+npx omega test project:             # run ONLY your project tests (all of them)
+npx omega test project:custom-test  # run only consumer project tests matching a path
+npx omega test mgr:                 # run ONLY framework tests (universal alias; desktop:/framework: are equivalent)
+npx omega test desktop:build/config      # run only framework tests matching a path
+npx omega test --extended           # also run tests that hit REAL external services (off by default; TEST_EXTENDED_MODE=true is the env equivalent, a shared name across @omega.js/backend, @omega.js/extension, UJM, and @omega.js/desktop)
+# (output is teed to logs/: dev.log on `npm start`, build.log on `npm run build`, test.log on `npx omega test`; cat instead of scrolling scrollback)
+npx omega install dev  # use LOCAL @omega.js/desktop source (to test framework edits)
+npx omega install live # restore the published @omega.js/desktop from npm
+```
+
+> Editing the @omega.js/desktop framework source while working here? Run `npx omega install dev` so this project picks up your uncommitted framework changes (it otherwise uses its installed `node_modules/@omega.js/desktop`). Run `npx omega install live` to switch back.
+
+## Where things live
+
+- `config/omega.json5`: the single OMEGA config (JSON5), with shared sections (brand, analytics, payment, cloud, monitoring, theme) at the top level; desktop settings (app, platforms, autoUpdate, startup, releases, remoteConfig, restartManager) under `targets.desktop`.
+- Packaging config: fully generated. @omega.js/desktop produces `dist/electron-builder.yml` from `config/omega.json5` (brand/app/signing) + @omega.js/desktop's opinionated defaults. Consumers never ship an `electron-builder.yml`. Override defaults via the `electronBuilder:` block in `omega.json5` if you genuinely need to.
+- `hooks/notarize/post.js`: optional post-notarize extension hook (@omega.js/desktop owns the actual `afterSign` notarize step).
+- `src/main.js`: main-process entry. One-line bootstrap of `@omega.js/desktop/main`.
+- `src/preload.js`: preload entry. Exposes `window.desktop` via contextBridge.
+- `src/integrations/tray/index.js`: tray definition. Edit this; it's yours.
+- `src/integrations/menu/index.js`: application menu definition.
+- `src/integrations/context-menu/index.js`: right-click menu definition (called per-event with `params`).
+- `src/views/<window>/index.html`: per-window HTML.
+- `src/assets/js/components/<window>/index.js`: renderer entry per window.
+- `src/assets/scss/main.scss`: shared SCSS.
+- `config/icons/<platform>/<slot>.png`: optional icon overrides (`macos/icon.png`, `macos/tray.png`, `macos/dmg.png`, `windows/icon.png`, etc.).
+  - Ship ONE file per slot at the native (retina) size; @omega.js/desktop auto-downscales @1x variants.
+  - macOS tray must be 32×32 (@omega.js/desktop renames to `trayTemplate.png` in dist for the OS dark-mode magic).
+  - Missing slots fall back to @omega.js/desktop bundled defaults; Linux falls back to Windows resolution.
+- `test/**/*.js`: your project test suites (framework auto-runs them alongside its own).
+
+## Per-context imports
+
+```js
+// src/main.js
+new (require('@omega.js/desktop/main'))().initialize();   // auto-loads JSON5 config
+
+// src/preload.js
+new (require('@omega.js/desktop/preload'))().initialize();
+
+// src/assets/js/components/main/index.js
+new (require('@omega.js/desktop/renderer'))().initialize();
+```
+
+## Available APIs at runtime
+
+In main: `manager.storage`, `manager.ipc`, `manager.windows`, `manager.tray`, `manager.menu`, `manager.contextMenu`, `manager.startup`, `manager.appState`, `manager.deepLink`, `manager.autoUpdater`, `manager.sentry`, `manager.omega`, `manager.context`, `manager.usage`, `manager.remoteConfig`, `manager.analytics`, `manager.restartManager`.
+
+In renderer: `window.desktop.storage`, `window.desktop.ipc`, `window.desktop.logger`, `OMEGA_BUILD_JSON.config`.
+
+## Dependency resolution
+
+- **Do NOT install framework dependencies directly** (`firebase`, `fs-jetpack`, `@omega.js/client`, etc.). @omega.js/desktop's bundler resolves them through the framework's own `node_modules/`. If something doesn't resolve, the issue is in @omega.js/desktop's bundle task, not your `package.json`.
+- **@omega.js/client owns Firebase.** Never `require('firebase')` or `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).
+- **`Manager.require(name)`** resolves from @omega.js/desktop's module context at runtime for unbundled code (gulp tasks, test fixtures).
+
+## Testing
+
+Every feature ships with tests at every layer it has a surface in: **logic** (`test/build/`, `test/main/`), **UI** (`test/renderer/`: real events on the real DOM), and **end-to-end** (`test/boot/`).
+- Skip a layer only when the feature genuinely has no surface there; "the logic test covers it" does not excuse the UI test.
+- Test runs are invisible and never steal keyboard focus (@omega.js/desktop test stealth; set `OMEGA_TEST_SHOW=1` to watch a run live).
+- See `test/README.md` and `node_modules/@omega.js/desktop/docs/test-framework.md`.
+
+<!-- Everything above this marker is owned by the framework and rewritten by every omega verb. Add your project-specific notes below — they are preserved. -->
+
+# ========== Custom Values ==========
+
+## Project-specific notes
+
+Add anything specific to THIS project here. Edits below this line are preserved across framework re-syncs.

package/dist/defaults/CHANGELOG.md

@@ -0,0 +1,15 @@
+# CHANGELOG
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## Changelog Categories
+
+- `BREAKING` for breaking changes.
+- `Added` for new features.
+- `Changed` for changes in existing functionality.
+- `Deprecated` for soon-to-be removed features.
+- `Removed` for now removed features.
+- `Fixed` for any bug fixes.
+- `Security` in case of vulnerabilities.

package/dist/defaults/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/dist/defaults/_.gitignore

@@ -0,0 +1,24 @@
+# ========== Default Values ==========
+
+.DS_Store
+node_modules/
+/dist/
+/release/
+/.cache/
+/.omega/
+/.claude/
+.env
+*.log
+/logs/
+
+# Apple signing artifacts — never commit these
+config/certs/
+*.p12
+*.cer
+*.mobileprovision
+*.p8
+*.pem
+
+# ========== Custom Values ==========
+
+# Add your own ignores below. This section is preserved across framework re-syncs.

package/dist/defaults/_mas/README.md

@@ -0,0 +1,49 @@
+# MAS (Mac App Store) Reference Plists — ARCHIVED
+
+These entitlement plists are reference material for a future Mac App Store
+distribution implementation. They are **NOT** part of the active scaffold copied
+to consumers by `mgr setup` (the leading `_` keeps them out).
+
+## Source
+
+Copied from a working MAS-published Electron app (Slapform, last shipped to the
+App Store in March 2025). The configurations here are known-good for the use
+cases:
+
+| File | Purpose |
+|---|---|
+| `entitlements.mas.plist` | Main MAS app sandbox entitlements (network, file picker access, JIT, application-groups). |
+| `entitlements.mas.inherit.plist` | Inherited entitlements for child processes (`com.apple.security.inherit`). |
+| `entitlements.mas.loginhelper.plist` | Minimal entitlements for the optional MAS login-helper bundle. |
+
+Note that `entitlements.mas.plist` references `application-groups` with a
+team-ID-prefixed identifier (e.g. `9S9QEYN7C6.com.itwcreativeworks.slapform`).
+The actual implementation will need to derive this from the consumer's Apple
+Team ID + appId at build time.
+
+## Roadmap
+
+When MAS support is implemented (currently stubbed in
+`config.targets.mac.mas` — see `docs/installer-options.md`), this folder will be
+the starting point for the entitlements @omega.js/desktop auto-generates into `dist/config/`
+when `mac.mas.enabled === true`. The structure should be similar to the existing
+`writeMacEntitlements` flow but with separate output files for `mas`, `mas.inherit`,
+and `mas.loginhelper`.
+
+The other MAS-specific concerns:
+- Provisioning profile copy (`config/embedded.provisionprofile` → `dist/config/`)
+- Separate `mas` target in `mac.target` (alongside `dmg` + `zip`)
+- `mas:` config block with `hardenedRuntime: false`, `gatekeeperAssess: false`,
+  separate entitlement paths, and `publish: null` (App Store Connect submission
+  is manual, not GH Releases).
+
+## Why these are archived rather than implemented now
+
+MAS distribution adds significant non-trivial complexity (sandboxed app, App Store
+review cycle, separate provisioning profile per app, manual submission to App
+Store Connect via Transporter or Xcode). It's the right move only for apps that
+genuinely benefit from App Store distribution — most consumer apps ship via DMG
+download from a website, not the Mac App Store.
+
+If you need MAS now, the legacy @omega.js/desktop (pre-v1) had support that you
+can adapt; otherwise wait for the @omega.js/desktop v1.x implementation.

package/dist/defaults/_mas/entitlements.mas.inherit.plist

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>com.apple.security.app-sandbox</key>
+    <true/>
+    <key>com.apple.security.inherit</key>
+    <true/>
+    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+    <true/>
+  </dict>
+</plist>

package/dist/defaults/_mas/entitlements.mas.loginhelper.plist

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>com.apple.security.app-sandbox</key>
+    <true/>
+  </dict>
+</plist>

package/dist/defaults/_mas/entitlements.mas.plist

@@ -0,0 +1,33 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>com.apple.security.app-sandbox</key>
+    <true/>
+    <key>com.apple.security.files.user-selected.read-write</key>
+    <true/>
+    <key>com.apple.security.files.downloads.read-write</key>
+    <true/>
+    <key>com.apple.security.network.client</key>
+    <true/>
+    <key>com.apple.security.network.server</key>
+    <true/>
+    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+    <true/>
+    <key>com.apple.security.cs.allow-jit</key>
+    <true/>
+    <!-- https://github.com/electron-userland/electron-builder/issues/3940 -->
+    <!-- <key>com.apple.security.cs.disable-library-validation</key>
+    <true/> -->
+    <!-- <key>com.apple.security.automation.apple-events</key>
+    <true/> -->
+    <!-- <key>com.apple.security.files.bookmarks.app-scope</key>
+    <true/> -->
+    <!-- <key>com.apple.security.files.bookmarks.document-scope</key>
+    <true/> -->
+    <key>com.apple.security.application-groups</key>
+    <array>
+      <string>9S9QEYN7C6.com.itwcreativeworks.slapform</string>
+    </array>
+  </dict>
+</plist>

package/dist/defaults/config/certs/README.md

@@ -0,0 +1,60 @@
+# `config/certs/` — Code-signing certificates and provisioning profiles
+
+**Never commit anything in this directory.** The parent `.gitignore` excludes `*.p12`, `*.cer`, `*.mobileprovision`, `*.p8`, `*.pem` — and the entire `config/certs/` subdirectory is also ignored as a defense-in-depth measure.
+
+## File inventory
+
+### macOS (signing + notarization)
+
+| File | Source | Used by | Env var pointing at it |
+|---|---|---|---|
+| `developer-id-application.p12` | Apple Developer → Certificates → "Developer ID Application" | electron-builder for code signing | `CSC_LINK` |
+| `developer-id-installer.p12` | Apple Developer → Certificates → "Developer ID Installer" | electron-builder for `.pkg` signing (only if you ship a pkg installer) | `CSC_INSTALLER_LINK` |
+| `AuthKey_XXXXXXXXXX.p8` | App Store Connect → Users and Access → Keys | Notarization via notarytool API | `APPLE_API_KEY` (path), `APPLE_API_KEY_ID`, `APPLE_API_ISSUER` |
+| `<app-name>.provisionprofile` | Apple Developer → Profiles → Developer ID Provisioning Profile | Required if your app uses entitlements requiring Apple's review (push notifications, in-app purchase, network extensions, etc.) | electron-builder auto-discovers in `build/` |
+
+You also need (in `.env`, not in this directory):
+- `CSC_KEY_PASSWORD` — password for the `.p12` files
+- `APPLE_API_KEY_ID` — 10-char Key ID (matches the `XXXXXXXXXX` in the `.p8` filename)
+- `APPLE_API_ISSUER` — issuer UUID from App Store Connect
+- `APPLE_TEAM_ID` — 10-char team ID from developer.apple.com
+
+### Windows (signing)
+
+For self-hosted EV USB token:
+| File / value | Source | Env var |
+|---|---|---|
+| (USB token plugged into self-hosted runner) | Sectigo / DigiCert / etc. EV cert physical token | `WIN_EV_TOKEN_PATH`, `WIN_CSC_KEY_PASSWORD` |
+
+For cloud signing (future):
+- Azure Trusted Signing — service principal creds in `.env`
+- SSL.com eSigner — username + password + credential ID in `.env`
+- DigiCert KeyLocker — API token + endpoint in `.env`
+
+No file lives in `config/certs/` for Windows — credentials are env-vars-only.
+
+## Are these per-brand or universal?
+
+**Universal across brands you ship as the same Apple Developer team:**
+- `developer-id-application.p12` — one per team, valid for all your apps
+- `developer-id-installer.p12` — same
+- `AuthKey_*.p8` — one per team, used for notarization across all apps
+- Apple Team ID, Apple ID, app-specific password
+- Windows EV token (one per team)
+
+**Per-brand / per-app:**
+- Provisioning profile (`*.provisionprofile`) — only required if entitlements demand it; tied to a specific bundle ID (`com.itwcw.<app>`)
+- Icons (separate concern, live in `build/`, not `config/certs/`)
+
+## Setup walkthrough
+
+1. Drop the relevant cert files into this directory.
+2. Edit `.env` at the repo root and point env vars at them (typically just `CSC_LINK=config/certs/developer-id-application.p12`).
+3. Run `npx omega validate-certs` to check the OS sees them and notarization creds are wired.
+4. `npm run release` to do a signed + notarized build.
+
+For full details see [`docs/signing.md`](../../docs/signing.md) at the @omega.js/desktop repo root.
+
+## CI
+
+In CI (GitHub Actions), certs are passed via secrets, not files. The workflow base64-decodes secret values into temp files at runtime, points env vars at them, then nukes the files after the build. See `src/defaults/.github/workflows/build.yml` (when added in Pass 3).

package/dist/defaults/config/omega.json5

@@ -0,0 +1,279 @@
+// config/omega.json5 — the single OMEGA config file (JSON5: comments + trailing commas OK).
+//
+// Shape: SHARED sections at the top level (identical spelling in every OMEGA project
+// type — website, backend, extension, desktop), then a `targets` object whose KEY
+// PRESENCE says which targets this brand enables and whose values hold target-scoped
+// settings. Any shared key may also appear inside a target entry to override it for
+// that surface only (e.g. a desktop-specific monitoring.providers.sentry.dsn
+// under targets.desktop).
+//
+// Secrets NEVER live here — they live in .env. The validator hard-fails on
+// secret-shaped keys (…Secret, …privateKey).
+{
+  brand: {
+    id: 'myapp',
+    name: 'MyApp',
+    url: 'https://myapp.example',
+    contact: { email: 'support@myapp.example' },
+    images: {
+      brandmark: '',
+      wordmark:  '',
+      icon:      'src/assets/icons/icon.png',
+    },
+  },
+
+  monitoring: {
+    providers: {
+      sentry: {
+        dsn: '',
+      },
+    },
+  },
+
+  // GA4 analytics. Measurement ID lives in config (not secret); the API secret
+  // lives in `process.env.GOOGLE_ANALYTICS_SECRET` (matches @omega.js/backend convention) so
+  // it's not committed. The build's esbuild `define` bakes the secret into
+  // packaged builds at build time so production apps don't need .env at runtime.
+  // client_id / user_id are uuidv5(deviceId/firebaseUid, projectId-namespace)
+  // so the same human gets unified events across desktop + web + backend.
+  analytics: {
+    // Presence-driven: set `providers.google.id` to `G-XXXXXXXXXX` to enable analytics.
+    // Empty string = analytics disabled (matches @omega.js/backend convention — no redundant enabled flag).
+    providers: {
+      google: {
+        id: '',                               // 'G-XXXXXXXXXX' Measurement ID
+      },
+    },
+  },
+
+  // Payment — @omega.js/backend-shaped so the same product catalog can be referenced from backend
+  // + desktop. The schema enforces publishableKey shape when set; everything else is
+  // freeform so apps can extend per their needs without @omega.js/desktop caring. Leave empty until
+  // you're ready to wire payments.
+  payment: {
+    providers: {
+      stripe: { publishableKey: '' },
+      paypal: { clientId:       '' },
+    },
+    products: [],
+  },
+
+  // App/cloud platform role (provider-discriminated). `config` is the Firebase web
+  // SDK config — copy directly from Firebase Console → Project Settings → SDK setup
+  // (Config option). Same shape every OMEGA target reads.
+  // Empty config {} disables Firebase Auth in the renderer (client-bridge logs a warn).
+  cloud: {
+    provider: 'firebase',
+    config: {
+      apiKey:            '',
+      authDomain:        '',
+      databaseURL:       '',
+      projectId:         '',
+      storageBucket:     '',
+      messagingSenderId: '',
+      appId:             '',
+      measurementId:     '',
+    },
+  },
+
+  // Appearance — the app's DEFAULT theme. 'system' follows the OS preference live;
+  // 'light'/'dark' are explicit overrides. A user's runtime choice (manager.theme.set
+  // or the [data-omega-theme-set] controls) persists in storage and wins over this on
+  // every boot. See docs/themes.md.
+  theme: {
+    appearance: 'system',
+  },
+
+  // ── Target-scoped config. Key presence = "this brand enables this target". ──
+  // For a standalone desktop repo only the `desktop` entry exists; in a brand
+  // monorepo the brand-level omega.json5 lists every enabled target.
+  targets: {
+    desktop: {
+      // App-level metadata — universal cross-platform fields. @omega.js/desktop auto-derives sensible
+      // defaults from the BRAND: `appId` ← reverse-domain of `brand.url`
+      // (`https://foo.example.com` → `com.example.foo`; no url → `app.<brand.id>`),
+      // `productName` ← `brand.name`, `copyright` ← `© <year>, <brand.name>`.
+      // Override any of these explicitly only if you must.
+      //
+      // `category` is a generic high-level category — @omega.js/desktop maps it to per-platform values
+      // (mac uses Apple's UTI strings, linux uses freedesktop categories). Allowed values:
+      //   productivity (default) | developer-tools | utilities | media | social | network
+      // Override the per-platform mapping in `platforms.<plat>.category` if you need
+      // something specific. See docs/installer-options.md for the full table.
+      //
+      // `copyright` accepts a `{YEAR}` token expanded at build time to the current year.
+      // Default is `© {YEAR}, <brand.name>`. Set explicitly only to change the holder.
+      app: {
+        appId:           null,
+        productName:     null,
+        copyright:       null,                // null → `© {YEAR}, <brand.name>`
+        category:        'productivity',
+        languages:       ['en'],              // applied as mac.electronLanguages
+        darkModeSupport: true,                // mac honors via NSRequiresAquaSystemAppearance; win/linux ignore
+        // Icons are convention-only. Drop PNGs at:
+        //   config/icons/global/<slot>.png       — universal default for all platforms
+        //   config/icons/macos/<slot>.png        — macOS override (beats global)
+        //   config/icons/windows/<slot>.png      — Windows override
+        //   config/icons/linux/<slot>.png        — Linux override (otherwise falls back to global → windows)
+        // Slots: icon, tray (mac+win+linux); dmg (mac-only).
+        // Native size only — @omega.js/desktop downscales @1x variants from your @2x source automatically.
+        // macOS tray must be 32×32; @omega.js/desktop renames the dist output to trayTemplate.png for the
+        // OS dark-mode auto-inversion magic.
+      },
+      // Per-platform install/distribution config. The keys here map directly to the same
+      // electron-builder concepts (`mac.target`, `win.target`, `linux.target`) but @omega.js/desktop owns
+      // the actual target list (dmg+zip on mac, nsis on win, deb+AppImage on linux) so
+      // auto-update keeps working — see docs/installer-options.md for why. Each block
+      // exposes only the knobs that exist for that platform — no cross-platform analog
+      // for any of these.
+      platforms: {
+        mac: {
+          arch: ['universal'],   // universal binary (x64 + arm64 lipo'd) — one .dmg/.zip for both
+          // Entitlements override map. @omega.js/desktop ships sensible defaults (allow-jit,
+          // allow-unsigned-executable-memory, disable-library-validation, network.client/server,
+          // files.user-selected.read-write, allow-dyld-environment-variables). To override:
+          //   - Set a key to a value to add/replace it (boolean, string, or array per Apple's plist spec)
+          //   - Set a key to `null` to remove it from @omega.js/desktop's defaults
+          // Output: dist/config/entitlements.mac.plist (auto-wired into electron-builder.yml).
+          // Example: { 'com.apple.security.network.server': false, 'com.apple.security.device.audio-input': true }
+          entitlements: {},
+          // MAS (Mac App Store) — STUBBED. Config is parsed but not yet implemented;
+          // setting `enabled: true` triggers an audit warning. Real implementation lands
+          // in a future release. Reference plists from a working MAS-published Electron app
+          // are archived at <em>/src/defaults/_mas/ for the eventual implementation.
+          mas: {
+            enabled:             false,
+            provisioningProfile: null,
+            entitlements:        null,
+            entitlementsInherit: null,
+          },
+        },
+        win: {
+          arch: ['x64', 'ia32'],          // 64-bit + 32-bit (single multi-arch NSIS installer)
+          oneClick:           true,        // no installer wizard, just installs immediately
+          desktopShortcut:    true,
+          startMenuShortcut:  true,
+          runAfterFinish:     true,
+          perMachine:         false,       // per-user install (required for oneClick:true)
+          // Code-signing strategy. Picked at workflow time to drive runner selection +
+          // job gating. See docs/signing.md.
+          //   self-hosted (default) — sign with signtool against an EV USB token (typically
+          //                           on an framework-managed self-hosted GH Actions runner)
+          //   cloud                 — shell to a cloud signing provider's CLI (Azure /
+          //                           SSL.com / DigiCert) — provider configured in cloud.provider
+          //   local                 — skip CI signing; developer signs manually on their box
+          signing: {
+            strategy: 'self-hosted',
+            cloud:    { provider: null, options: {} },
+          },
+        },
+        linux: {
+          arch: ['x64'],                   // amd64; ia32 is essentially extinct on Linux
+          // Snap publishing — enabled by default. Adds a `snap` target to the linux build
+          // and auto-publishes to the Snap Store on release. Requires SNAPCRAFT_STORE_CREDENTIALS
+          // in your `.env` (run `snapcraft export-login -` locally to mint, then `mgr push-secrets`
+          // flows it to GH Actions). Set enabled:false here to skip the snap target entirely.
+          snap: {
+            enabled:     true,
+            confinement: 'strict',
+            grade:       'stable',
+            autoStart:   true,
+            channels:    ['stable'],
+          },
+        },
+      },
+      // Auto-updater (electron-updater wrapper). Feed URL is auto-derived from `releases` (below).
+      // Set `OMEGA_DEV_UPDATE=available|unavailable|error` to simulate updates in dev.
+      autoUpdate: {
+        enabled:        true,
+        channel:        'latest',
+        autoDownload:   true,
+        startupDelayMs:      10000,      // 10s after whenReady → first check
+        feedCheckIntervalMs: 3600000,    // 1h between feed polls (HTTP — keep slow)
+        idleEvalIntervalMs:  60000,      // 1m idle-install evaluator (cheap, in-process)
+        maxAgeMs:            2592000000, // 30d — once an update has been pending this long, force install
+      },
+      // Tray, menu, and context-menu are defined in JS files (full power, no DSL).
+      // @omega.js/desktop looks for them at the conventional paths:
+      //   src/integrations/tray/index.js
+      //   src/integrations/menu/index.js
+      //   src/integrations/context-menu/index.js
+      // To disable at runtime: call `manager.tray.disable()` / `manager.menu.disable()` /
+      // `manager.contextMenu.disable()` from your main entry. Idempotent.
+
+      // Startup behavior — two independent knobs.
+      //
+      // `mode` controls how the app launches when THE USER opens it directly:
+      //   normal — main window appears, dock icon visible (typical app).
+      //   hidden — packaged builds bake LSUIElement=true into Info.plist on macOS:
+      //            zero dock bounce, no dock icon, not in Cmd+Tab. Tray + notifications
+      //            + networking still work. Your main.js skips windows.create() at boot
+      //            and surfaces UI later (typically from a tray click). When you do call
+      //            windows.create('main'), @omega.js/desktop auto-runs app.dock.show() so the dock icon
+      //            appears alongside the window.
+      //
+      // `openAtLogin` controls auto-launch on OS login:
+      //   enabled — register the app with the OS to auto-launch (default true).
+      //   mode    — `hidden` (default) means at-login launches behave like `mode: 'hidden'`;
+      //             `normal` means the at-login launch shows UI like a normal launch.
+      //   The login-launch mode applies ONLY when the OS launches the app. User-direct
+      //   launches always use `startup.mode` above. So a "normal" app can still start
+      //   hidden at login and surface only when the user explicitly opens it.
+      startup: {
+        mode: 'normal',
+        openAtLogin: {
+          enabled: true,
+          mode:    'hidden',
+        },
+      },
+      // No `windows` block needed — @omega.js/desktop no longer auto-creates windows. Your main.js
+      // calls `manager.windows.create('main', { width: 1280, height: 800, ... })` when
+      // you want UI to surface. Defaults baked in:
+      //   main      → { width: 1024, height: 720, hideOnClose: true,  view: 'main' }
+      //   any other → { width: 800,  height: 600, hideOnClose: false, view: name   }
+      // Add a `windows: {}` block here only if you want to override defaults persistently.
+
+      // Releases: the ONE public repo where built artifacts (and the auto-update feed) live.
+      // The app repo can stay private; this one MUST be public for unauthenticated downloads + auto-updates.
+      // Both keys default: repo is `<brand.id>-releases` and owner is the brand repo's owner, so the whole
+      // block can stay empty (`releases: {}`) and still address a repo.
+      // `npx omega deploy`'s precheck auto-creates it if it doesn't exist (uses GH_TOKEN).
+      // Artifact names carry NO version (MyApp-mac-universal.dmg), so this repo also serves the marketing
+      // site: https://github.com/<owner>/<repo>/releases/latest/download/<asset> never changes across
+      // versions, and the website derives its download buttons from it. See docs/releasing.md.
+      releases: {
+        enabled: true,
+        // owner: null,             // null = the brand repo's owner
+        // repo:  'myapp-releases', // default: `<brand.id>-releases`
+      },
+      // Deep links: scheme is automatically `<brand.id>://...`. Built-in routes:
+      //   auth/token  → @omega.js/client auth token handoff
+      //   app/show    → manager.windows.show(query.window || 'main')
+      //   app/quit    → app.quit()
+      // Add custom routes at runtime: manager.deepLink.on('my-route', (ctx) => {...}) in main.
+
+      // "Hot config" — JSON document fetched from the brand site so app behavior
+      // can be flipped without shipping a new build (e.g. force-update gate, ads
+      // toggle, default user agent strings, etc.). Default URL is derived as
+      // `${brand.url}/data/resources/main.json` (legacy convention). Override the
+      // path with `remoteConfig.url`. Polled at the same cadence as auto-updater
+      // feed-check (default 1h). Disable via `enabled: false`.
+      remoteConfig: {
+        enabled: true,
+        // url: 'https://brand.example/data/resources/main.json',   // default uses brand.url
+      },
+      // Restart Manager — external guardian app that relaunches this app if it
+      // crashes. @omega.js/desktop talks to it over a localhost HTTP protocol (docs/restart-manager.md):
+      // auto-registers ~15s after launch, heartbeats every 60s, deregisters on clean
+      // quit, and silently installs RM when missing (mac zip / win silent NSIS /
+      // linux AppImage — no installer UI, no admin; RM then keeps itself updated via
+      // its own standard @omega.js/desktop auto-updater). Set false to disable entirely. In dev
+      // mode it's skipped unless OMEGA_RESTART_MANAGER_DEV=1.
+      restartManager: {
+        enabled: true,
+        // feed: { owner: 'restart-manager', repo: 'update-server' },  // override for forks/mirrors
+        // feed: { url: 'https://mirror.example.com/rm' },             // full base-URL override (air-gapped)
+      },
+    },
+  },
+}

package/dist/defaults/docs/README.md

@@ -0,0 +1,17 @@
+# Project docs
+
+Per-subsystem deep references live here. Keep `AGENTS.md` short — it should read as a **table of contents** that points at files in this directory.
+
+## Pattern
+
+When you find yourself adding more than a paragraph to `AGENTS.md`, create a new `docs/<topic>.md` instead and link to it from `AGENTS.md`. Goal: the project's `AGENTS.md` stays under ~250 lines (`CLAUDE.md` is only the one-line `@AGENTS.md` pointer).
+
+Examples of good `docs/*.md` topics:
+- Subsystem deep-dives (one per area of the codebase)
+- Architectural decisions / "why we built it this way"
+- Defaults tables, behavior matrices, edge cases
+- Setup walkthroughs that don't belong in `README.md`
+
+## See also
+
+The framework's own docs follow this same pattern — browse `node_modules/@omega.js/desktop/docs/` for the canonical examples.

package/dist/defaults/gulpfile.js

@@ -0,0 +1,6 @@
+// Consumer gulpfile — the framework's gulp pipeline, resolved through the
+// require climb so it works wherever npm hoists the framework (brand-root
+// node_modules in a monorepo, local node_modules standalone). The old
+// scripts hardcoded ./node_modules/@omega.js/desktop/... and broke under
+// workspace hoisting (dogfood friction #14).
+module.exports = require('@omega.js/desktop/gulp');