@omega.js/desktop 0.1.0

package/docs/fontawesome.md

@@ -0,0 +1,107 @@
+# FontAwesome
+
+@omega.js/desktop serves the **brand's best available Font Awesome set** —
+Pro when the brand supplies one (see below), otherwise the **Free set**
+(solid + regular + brands, SVG) straight from its
+`@fortawesome/fontawesome-free` npm dependency — every consumer gets 2,600+
+icons with **zero setup**, fully offline, no icon font, no CDN, and nothing
+vendored inside the framework package.
+
+```html
+<button class="btn btn-primary">
+  <i class="fa-solid fa-rocket me-2"></i>Launch
+</button>
+```
+
+That's it. Any `<i>` element carrying `fa-*` classes — in static HTML or
+inserted dynamically at any time — gets the real SVG injected inline by the
+renderer bootstrap. No `initialize()` options, no imports.
+
+## One icon mechanism, every surface (C4 cp108)
+
+Icon SEMANTICS — valid names/styles, candidate lookup order (requested style,
+then the brands fallback), the injected root attributes, and alias mapping —
+live in **`@omega.js/client/modules/icon-core.js`**, the SAME module
+@omega.js/web's build-time inlining pass uses. Desktop and web can never
+drift on how an icon name resolves or what the served SVG looks like.
+
+## How it works
+
+- **Assets** — resolved through the root chain (cp111), best-first:
+  `OMEGA_FONTAWESOME_ROOT` download dir → `@fortawesome/fontawesome-pro`
+  when the brand installed it → `@fortawesome/fontawesome-free` (a declared
+  runtime dependency, always last so a partial brand set never loses icons
+  the free set has). Each root holds `svgs/<style>/*.svg` plus
+  `metadata/icon-families.json` for aliases (`search` → `magnifying-glass`).
+  Declared dependencies ride into packaged apps automatically (fs reads
+  through the asar transparently).
+- **Main lib** (`lib/fontawesome.js`) — `manager.fontawesome.get(name, style)`
+  resolves an icon to its SVG string (`null` for unknown names — never
+  throws). Lookups are slug-sanitized via icon-core (the IPC channel can
+  never read outside the icon directories) and cached per app run. Serves
+  renderers over `desktop:fontawesome:get`.
+- **Preload bridge** — `window.desktop.fontawesome.get(name, style)` →
+  `Promise<svg | null>`.
+- **Renderer auto-render** (`renderer.js _wireFontAwesome`) — a thin
+  wrapper over **@omega.js/client's shared `icon-renderer`** (C4 cp112, the
+  same module web pages run): scan + MutationObserver for insertions AND
+  class changes (`el.className = 'fa-solid fa-stop'` re-renders in place;
+  dropping the classes clears the SVG), FA's family × weight class parsing
+  (`fa-sharp fa-light` → `sharp-light`; Pro markup without a Pro set stays
+  empty — never a wrong-style fallback), caching, and the
+  `data-omega-fa="<style>/<name>"` marker. Desktop supplies only the
+  transport: IPC to main's icon server.
+  The SVG is injected as a child of the `<i>`, sized `1em`/`currentColor` — it
+  inherits text color and scales with font-size (bump it via `font-size` or a
+  `fs-*` utility). Served SVGs also carry `overflow="visible"` (FA-kit parity:
+  `.svg-inline--fa { overflow: visible }`) — FA 7 glyphs may draw OUTSIDE
+  their viewBox (fa-lock's shackle peaks at y=-32 in a `0 0 384 512` box) and
+  the SVG-root default of `overflow: hidden` clips them flat.
+
+## Minimal surfaces
+
+The auto-render is wired by `initialize()`. A renderer that deliberately skips
+the full init (no @omega.js/client / auth — e.g. a lightweight popover overlay) can
+enable JUST the icon pipeline:
+
+```js
+new (require('@omega.js/desktop/renderer'))().enableFontAwesome();
+```
+
+## Supplying Font Awesome Pro (C4 cp111)
+
+Pro is brand-supplied, never redistributed by the framework. The two
+routes (FA npm token, or an `OMEGA_FONTAWESOME_ROOT` download dir), the
+chain semantics, and the style/family model are documented once at the
+repo hub: **[docs/shared/icons.md](../../../docs/shared/icons.md)**. Desktop-specific
+note: a packaged brand target declares `@fortawesome/fontawesome-pro` as its
+own **prod dependency** so the set ships inside the asar.
+
+## Notes
+
+- **The icon CSS is not desktop's.** The box, the size scale and the
+  `fa-spin`/`fa-bounce`/`fa-beat` utilities ride ONE sheet vendored from
+  @omega.js/web at prepare (see [css.md](css.md#icon-presentation)). Fix icon
+  presentation there, never here.
+- **Unknown names render nothing** — the `<i>` stays empty (marked
+  `data-omega-fa`). If you need a fallback, resolve through
+  `window.desktop.fontawesome.get()` and swap yourself.
+- **Free set = solid + regular + brands.** Pro styles (light/duotone/sharp)
+  need a supplied Pro set (above); otherwise
+  `manager.fontawesome.get(name, 'duotone')` returns `null`.
+- **Updating the set** — bump the `@fortawesome/fontawesome-free` dependency
+  (or reinstall/refresh the brand's Pro supply).
+
+## Testing
+
+- `src/test/suites/main/fontawesome.test.js` — resolution, aliases (via the
+  metadata map), sanitization (traversal attempts), caching, IPC round-trip,
+  the `overflow="visible"` serve attribute, and the cp111 root chain
+  (`OMEGA_FONTAWESOME_ROOT` wins, free set falls through for icons and
+  metadata the brand set lacks).
+- `src/test/suites/renderer/fontawesome.test.js` — the real-DOM proof of
+  the SHARED icon-renderer: inserted `<i>` elements get SVGs on the live
+  DOM, class changes re-render in place and class removal clears (cp112),
+  modifier classes are never mistaken for names, Pro family/weight classes
+  compose (Pro-adaptive assertions), unknown names stay empty, injected
+  SVGs compute `overflow: visible` (out-of-viewBox glyphs must not clip).

package/docs/hooks.md

@@ -0,0 +1,87 @@
+# Lifecycle Hooks
+
+Consumers can inject custom logic at well-defined points without forking @omega.js/desktop's gulp tasks. All hooks are **purely additive extension points** — @omega.js/desktop's core logic always runs first, the hook is called after (or before, depending on the lifecycle point), and a hook throwing only logs a warning, never breaks the build.
+
+## How hooks work
+
+1. @omega.js/desktop scaffolds empty hook files into `<consumer>/hooks/**/*.js` on every verb (`ensureTarget()`).
+2. At each lifecycle point, @omega.js/desktop checks for the file. If it exists, @omega.js/desktop loads + invokes it. If not, no-op.
+3. The hook signature is `async (ctx) => { ... }`. Whatever it returns is awaited but ignored.
+4. **Failure semantics:**
+   - File missing entirely → logged informationally (`hook "<name>" not present at ... — skipping.`), build continues.
+   - File exists but fails to load (syntax error, etc.) → **throws**, build fails.
+   - File exists but doesn't export a function → **throws**, build fails.
+   - File loads + invokes the function and the function throws → **throws**, build fails.
+
+   In other words: a hook that doesn't exist is fine (you'll see one log line), but a hook that's broken in any way fails loudly. You should never silently ship a malformed hook to production.
+
+## Hooks reference
+
+| Hook file | When it runs | `ctx` shape |
+|---|---|---|
+| `hooks/build/pre.js`     | Before the build pipeline runs (`defaults` → `distribute` → `bundle` ...) | `{ manager, projectRoot, mode }` |
+| `hooks/build/post.js`    | After the build pipeline finishes, before `electron-builder` packages anything | `{ manager, projectRoot, mode }` |
+| `hooks/release/pre.js`   | Before `electron-builder build --publish always` | `{ manager, projectRoot, mode }` |
+| `hooks/release/post.js`  | After the release publishes | `{ manager, projectRoot, mode }` |
+| `hooks/notarize/post.js` | After @omega.js/desktop's built-in macOS notarization completes (extension only — @omega.js/desktop's notarize is the real entrypoint) | electron-builder afterSign context |
+
+`mode` is `'production'` when `OMEGA_BUILD_MODE=true`, else `'development'`.
+
+## Why this design
+
+- **Notarize specifically:** the consumer's `hooks/notarize/post.js` is **never** the electron-builder afterSign entrypoint. @omega.js/desktop's `gulp/build-config` injects `afterSign:` pointing at @omega.js/desktop's real notarize implementation (resolved via `require.resolve('@omega.js/desktop/hooks/notarize')`). @omega.js/desktop's real notarize calls into the consumer's `hooks/notarize/post.js` as a final post-step. So the consumer can never accidentally break notarization by editing the file — the file can be empty, malformed, or missing entirely and the app still notarizes correctly.
+- **Why no `hooks/notarize/pre.js`?** electron-builder's `afterSign` hook is the only signing-related extension point we control. Anything that would belong in a "pre-notarize" step belongs either in `hooks/release/pre.js` (whole-release-level prep, runs before the gulp release task), or in electron-builder's own `afterPack` / `afterAllArtifactBuild` configuration (per-artifact mutation). If you have a real use case that doesn't fit either, file an issue.
+- **Build/release hooks:** standard before/after lifecycle pattern. Same shape as Ultimate Jekyll Manager's hook system.
+
+## Examples
+
+### Slack notification on release
+
+```js
+// hooks/release/post.js
+module.exports = async ({ manager, projectRoot }) => {
+  const pkg = require(`${projectRoot}/package.json`);
+  const url = process.env.SLACK_WEBHOOK_URL;
+  if (!url) return;
+  await fetch(url, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ text: `🚀 ${pkg.name} v${pkg.version} released` }),
+  });
+};
+```
+
+### Generate changelog before build
+
+```js
+// hooks/build/pre.js
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+module.exports = async ({ projectRoot }) => {
+  const log = execSync('git log --oneline -n 20', { cwd: projectRoot });
+  fs.writeFileSync(path.join(projectRoot, 'CHANGELOG_LATEST.txt'), log);
+};
+```
+
+### Custom post-notarize archive
+
+```js
+// hooks/notarize/post.js
+const fs = require('fs');
+const path = require('path');
+
+module.exports = async (context) => {
+  const { appOutDir, packager } = context;
+  const appName = packager.appInfo.productFilename;
+  const appPath = path.join(appOutDir, `${appName}.app`);
+  // e.g. archive a copy somewhere off the build path
+  fs.cpSync(appPath, `/tmp/omega-archive/${appName}-${Date.now()}.app`, { recursive: true });
+};
+```
+
+## Tests
+
+- `src/test/suites/build/run-consumer-hook.test.js` — silent skip, invocation with args, error swallowing.
+- `src/test/suites/build/build-config.test.js` — `injectAfterSign` always points at @omega.js/desktop's notarize.

package/docs/icons.md

@@ -0,0 +1,79 @@
+# Icons
+
+Convention-only. No config block — drop PNGs at known paths and @omega.js/desktop finds them.
+
+## Layout
+
+```
+config/icons/
+  global/             ← used by any platform with no platform-specific override
+    icon.png
+    tray.png
+  macos/              ← macOS overrides (beats global)
+    icon.png
+    tray.png          ← 32×32 native; @omega.js/desktop renames to trayTemplate.png in dist
+    dmg.png           ← 1080×760 DMG installer background
+  windows/            ← Windows overrides
+    icon.png
+    tray.png          ← optional; falls back to icon.png
+  linux/              ← Linux overrides
+    icon.png
+    tray.png
+```
+
+## Resolution chain (per slot, per platform)
+
+Most specific wins:
+
+1. `<projectRoot>/config/icons/<platform>/<file>` — platform-specific override
+2. `<projectRoot>/config/icons/global/<file>` — universal fallback shared by all platforms
+3. `<projectRoot>/config/icons/windows/<file>` — Linux-only extra step (legacy compat — Linux apps historically reuse Windows assets)
+4. `<@omega.js/desktop>/dist/config/icons/<platform>/<file>` — @omega.js/desktop bundled default
+5. `<@omega.js/desktop>/dist/config/icons/windows/<file>` — Linux-only extra step at the bundled level
+
+Inside the runtime tray lookup (`lib/tray.js`), tray-slot misses fall back to the app icon (`icon.png`) instead of returning null.
+
+## Sizes — ship @2x native only
+
+Retina slots (macOS tray, macOS dmg) take ONE source file at the native (@2x) size. @omega.js/desktop downscales the @1x sibling at build time via `sharp` and writes both into `dist/`. Consumers never ship `<name>@2x.png` files.
+
+| Slot | Native size | @omega.js/desktop emits |
+|---|---|---|
+| `macos/tray.png` | 32×32 | `trayTemplate.png` (16×16) + `trayTemplate@2x.png` (32×32) |
+| `macos/dmg.png` | 1080×760 | `dmg.png` (540×380) + `dmg@2x.png` (1080×760) |
+| `macos/icon.png` | 1024×1024 | `icon.png` (unchanged; electron-builder converts to `.icns`) |
+| `windows/icon.png` | 1024×1024 | `icon.png` (unchanged; electron-builder converts to `.ico`) |
+| `linux/icon.png` | 1024×1024 | `icon.png` (unchanged) |
+
+## Why `trayTemplate.png` on disk
+
+macOS reads the literal filename of the tray icon and treats any `*Template.png` as a "template image" — pure-black with alpha, automatically inverted in dark mode. Consumers ship `tray.png` (clearer naming, matches Windows/Linux); @omega.js/desktop owns the `Template` suffix when writing to `dist/`.
+
+If you set a custom path via `tray.icon(path)` in your `src/integrations/tray/index.js`, YOU are responsible for the runtime filename containing `Template` — @omega.js/desktop only owns the convention path.
+
+## Two common scenarios
+
+**One icon for everything:**
+
+```
+config/icons/global/icon.png    # mac + win + linux
+config/icons/global/tray.png    # mac + win + linux
+```
+
+**Mac-specific + shared Win/Linux:**
+
+```
+config/icons/global/icon.png    # win + linux use this
+config/icons/macos/icon.png     # mac override
+config/icons/macos/tray.png     # mac-specific tray (will become trayTemplate.png in dist)
+config/icons/macos/dmg.png      # mac-only by definition
+```
+
+## Source files
+
+- `src/lib/sign-helpers/resolve-icons.js` — the resolver itself; called from `gulp/build-config.js`.
+- `src/lib/tray.js#_defaultIconPath` — runtime tray lookup (same convention waterfall, but checks `dist/` first since the build already resolved).
+
+## Bundled defaults
+
+@omega.js/desktop ships its own `icon.png`, `tray.png`, `dmg.png` for each platform in `<@omega.js/desktop>/src/defaults/config/icons/<platform>/`. These are the final fallback when neither the consumer nor a global file provides anything — so a freshly scaffolded project produces a buildable app with the generic @omega.js/desktop icon out of the box.

package/docs/index.md

@@ -0,0 +1,279 @@
+# OMEGA Desktop (@omega.js/desktop)
+
+> **Note for contributors and Claude:** This file is the guide for `@omega.js/desktop` — identity, top-level conventions, and a map to the deep references. It lives in the monorepo's `docs/` tree and is loaded on demand (the omega Claude plugin's hooks inject it by context; the repo-root AGENTS.md map is the one agent entry — packages carry no agent docs). The **meat** (per-subsystem APIs, edge cases, behavior tables, defaults lists) lives in the package's own [`docs/<topic>.md`](../docs) files. When extending or adding content, write it in the matching `docs/*.md` file and cross-link from here — do NOT inline it. If a topic doesn't have a doc yet, create one.
+
+> **Mirrored structure:** the four framework guides — `docs/web/index.md`, `docs/backend/index.md`, `docs/extension/index.md`, and `docs/desktop/index.md` — mirror each other (the legacy UJM/BEM/BXM/EM lineage): shared sections (Supply-Chain Security, Development Workflow, File Conventions, Doc-update parity, etc.) appear in the **same order at the same position** across all four. When adding a section that applies to multiple frameworks, insert it in the same spot in all of them.
+
+## Identity
+
+OMEGA Desktop (@omega.js/desktop) is a comprehensive framework for building modern Electron desktop apps. Sister project to @omega.js/extension and Ultimate Jekyll Manager (UJM). Provides one-line-import bootstrap per Electron process, modular feature library with file-based extensibility, a multi-platform build/release pipeline, and a built-in test framework.
+
+## Recommended skills
+
+- **`omega:desktop`** — the router skill from the omega Claude plugin. The inject hook loads it automatically in any project with `@omega.js/desktop` (and inside `packages/desktop` here); it points back to this guide + `docs/` (the SSOT).
+- **`js:patterns`** — JavaScript/Node.js conventions: file structure, JSDoc, defensive coding (`?.` usage), template literals, `package.json` conventions. Auto-loads when creating new `.js` files or touching JS module structure.
+
+## 🚨 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:**
+- **`docs/client/index.md`** (in the framework monorepo) — the client guide: identity, module list, conventions
+- **`node_modules/@omega.js/client/docs/`** — module deep references (Auth, Bindings, Firestore, Notifications, etc.)
+
+## Quick Start
+
+### For Consuming Projects
+
+1. `npm install @omega.js/desktop --save-dev`
+2. There is no setup step ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)). The project scaffolds itself on the first verb below — `ensureTarget()` writes `config/omega.json5`, `src/main.js`, `src/preload.js`, per-window renderer entries, and integrations skeletons in `src/integrations/{tray,menu,context-menu}/index.js`, idempotently and silently once the target is converged.
+3. `npm start` — dev (gulp → esbuild → electron .)
+4. `npm run build` — local production build (compiles bundles only, no installer)
+5. `npm run package:quick` — fast packaged build for the host platform/arch only (~30s, skips DMG/zip/universal/notarize). Smoke-test packaged-mode behavior locally. Quick mode runs end-to-end (#117) and means exactly ONE thing since [#737](https://github.com/Omega-JS-Stack/omega/issues/737): the trimmed electron-builder phase. `clean` no longer keeps `dist/` and `release/` for it — the "next run is incremental" that justified keeping them was never true (every bundle was rebuilt anyway), and a cold esbuild bundle of all three targets is ~1s.
+6. `npm run package` — full local production package (DMG/zip/universal-mac, NSIS-win, deb+AppImage-linux). ~3min on mac.
+7. `npm run release` — signed + published release (requires certs)
+8. `npx omega test` — runs the project's test suites (bare consumer runs never include the framework corpus)
+   - `npx omega test build/config` — run project tests by path (relative to `test/`)
+   - `npx omega test framework:` / `npx omega test full:` — reach the framework suite (alone, or both sources)
+   - `npx omega test project:custom-test` — run only that project test file
+   - `npx omega test mgr:` — run ONLY framework tests (universal cross-framework alias for "the manager's own tests")
+   - `npx omega test desktop:build/config` — run only framework tests matching a path (`desktop:` is equivalent to `mgr:`)
+   - `--filter=<substring>` matches test NAMES (orthogonal to the path target)
+   - `npx omega test --extended` (or `TEST_EXTENDED_MODE=true`) opts into tests that hit real external services (Firebase, analytics, update feeds) — off by default. `TEST_EXTENDED_MODE` is the shared, unprefixed env var across @omega.js/backend, @omega.js/extension, UJM, and @omega.js/desktop; it propagates to every spawned test environment and prints a warning when on. See [docs/test-framework.md](../docs/test-framework.md#extended-vs-normal-mode).
+
+### For Framework Development (This Repository)
+
+> **🚫 NEVER use `npx omega ...` from the framework repo.** `npx omega` is for CONSUMER projects only (where the bin is linked in `node_modules/.bin/`). From the framework repo, use `npm test`, `npm start`, etc. — the `scripts` in `package.json` call the local `bin/` directly. This applies to ALL four OMEGA frameworks (@omega.js/backend, UJM, @omega.js/extension, @omega.js/desktop).
+
+1. `npm install`
+2. `npm start` — watch + compile `src/` → `dist/` via prepare-package
+3. Test in the **designated test consumer** — `../../Deployment-Playground/deployment-playground-desktop` is @omega.js/desktop's consumer for validating framework changes end-to-end (exercise any consumer-level flow there freely: builds, tests, packaging, runtime). From inside it, run `npx omega install dev` to swap @omega.js/desktop to this local repo — required whenever you edit the framework source and want the consumer to pick up the changes (the consumer otherwise keeps its installed `node_modules/@omega.js/desktop`). Reverse with `npx omega install live`.
+4. `npm test` — runs the framework's own suites
+
+## Architecture
+
+### Per-process Manager singletons
+
+Each Electron process has its own one-line bootstrap:
+
+```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();   // exposes window.desktop
+
+// src/assets/js/components/<view>/index.js
+new (require('@omega.js/desktop/renderer'))().initialize();
+```
+
+`manager.initialize()` runs a fixed boot order (startup → ipc → storage → theme → sentry → protocol → deepLink → appState → whenReady → autoUpdater → tray/menu/contextMenu → startup → omega → remoteConfig → remoteScripts → windows). See [docs/boot-sequence.md](../docs/boot-sequence.md) for the full ordered list + rationale.
+
+### Lib modules
+
+`src/lib/*.js` — every Electron concern its own module. Each exports a singleton with `initialize(manager)`. Deep dive per module: see `docs/<lib-name>.md`. Authoring guide (initialization contract, adding a new lib, flat-vs-split): [docs/lib-modules.md](../docs/lib-modules.md).
+
+| Module | Description |
+|---|---|
+| `ipc` | typed channel bus, single registration point |
+| `storage` | electron-store wrapper, sync main / async renderer via IPC |
+| `theme` | system-aware appearance — `nativeTheme.themeSource` ('system'/'light'/'dark'), persisted override, live `<html data-bs-theme>` in every renderer via matchMedia |
+| `window-manager` | lazy-creation registry, bounds persistence, Discord-style hide-on-close, inset titlebar, dock-show on first window, re-surface on user re-launch |
+| `tray` / `menu` / `context-menu` | file-based definitions; unified id-path API; default templates with id-tagged items |
+| `startup` | `mode: 'normal' \| 'hidden'`; `'hidden'` bakes `LSUIElement: true` for zero dock bounce |
+| `app-state` | storage-backed launch flags + crash sentinel |
+| `protocol` | single-instance lock + scheme registration |
+| `deep-link` | unified deep-link dispatch (cold + warm start, mac + win + linux), built-in routes, pattern matching |
+| `client-bridge` | main = source-of-truth Firebase Auth, renderers reflect via IPC; session persists via `auth-persistence`; renderers push the @omega.js/client-resolved plan → `getResolvedPlan()` |
+| `auth-persistence` | pluggable main-session vault (default: safeStorage OS-keychain encryption; `omega.authPersistence` config) |
+| `auto-updater` | electron-updater wrapper, idle-aware install, 30-day pending gate, dev simulation |
+| `sentry` | `@omega.js/monitoring` — the shared error-reporting contract, auto auth attribution, dev-mode gating |
+| `templating` | `{{ }}` token replacement (BXM/UJM convention), used at build time by `gulp/html` |
+| `context` | runtime info — `manager.context.{geolocation,client,session,app}` |
+| `usage` | `opens` / `hoursTotal` / `hoursThisSession`; crash-safe |
+| `remote-config` | "Hot config" fetched from `${brand.url}/data/resources/main.json`, polled hourly |
+| `remote-scripts` | Emergency remote code execution — OPT-IN (`remoteScripts.enabled: true`) + https-only; fetches `${brand.url}/data/scripts/main.js`, content-hash dedup, async `manager` + `require` in scope |
+| `analytics` | GA4 Measurement Protocol; cross-platform `uuidv5` identity; the app's ONE sender — renderer events forward here over IPC ([docs/analytics.md](../docs/analytics.md)) |
+| `restart-manager` | external guardian app for crash relaunches — localhost HTTP protocol v1 (register/heartbeat/deregister), silent install when missing (mac zip / win NSIS `/S` / linux AppImage; RM self-updates via its own @omega.js/desktop autoUpdater); split dir ships the protocol SSOT the RM app imports |
+
+### File-based feature definitions
+
+Trays, menus, and context-menus are NOT defined in config — they're defined in JS files the consumer authors at fixed conventional paths (`src/integrations/{tray,menu,context-menu}/index.js`). To opt out, call `manager.{tray,menu,contextMenu}.disable()` at runtime.
+
+All three ship sensible default templates and share a unified id-path API (`.find/.has/.update/.remove/.enable/.show/.hide/.insertBefore/.insertAfter/.appendTo`), implemented once in `src/lib/_menu-mixin.js`. See [docs/tray.md](../docs/tray.md), [docs/menu.md](../docs/menu.md), [docs/context-menu.md](../docs/context-menu.md).
+
+### Windows
+
+@omega.js/desktop does NOT auto-create any windows. Consumers call `manager.windows.create('main', { show: !startup.isLaunchHidden() })` from inside `manager.initialize().then(...)`. Inset titlebar by default; Discord-style hide-on-close on `main`; auto re-surface on user re-launch. See [docs/windows.md](../docs/windows.md).
+
+### Icons
+
+Convention-only. Drop PNGs at `config/icons/<platform>/<slot>.png` (platform-specific) or `config/icons/global/<slot>.png` (universal fallback). Resolution per slot: platform → global → (Linux only) windows → bundled default. Ship @2x native size only — @omega.js/desktop downscales the @1x sibling via sharp. macOS tray input is `tray.png` (consumer-friendly); @omega.js/desktop renames the dist output to `trayTemplate.png` for OS dark-mode auto-inversion. No `app.icons` config block. See [docs/shared/icons.md](../docs/icons.md).
+
+### Build system
+
+prepare-package copies `src/` → `dist/`; gulp orchestrates esbuild (3 bundles, all bundled) + electron-builder. The bundler is @omega.js/devkit's ONE `bundle()` wrapper since [#737](https://github.com/Omega-JS-Stack/omega/issues/737) — webpack and its loaders are gone from desktop, and the task went with the name: `src/gulp/tasks/bundle.js`, gulp task `bundle`, log tag `[@omega.js/desktop:bundle]`. `gulp/build-config` generates `dist/electron-builder.yml` + `dist/config/entitlements.mac.plist` from @omega.js/desktop defaults + consumer config. Artifact names carry NO version (`<Product>-mac-universal.dmg`) and come from @omega.js/config's `desktop-artifacts.js` — the ONE rule the website's direct-download URLs read too ([#620](https://github.com/Omega-JS-Stack/omega/issues/620)), so `/releases/latest/download/<asset>` is permanent and a desktop release never touches the site. Strategy-pluggable Windows signing (`platforms.win.signing.strategy`: `self-hosted` | `cloud` | `local`). See [docs/releasing.md](../docs/releasing.md) for the whole release contract (one public repo, `<brand.id>-releases` by default, the survivor + never-reuse rules, the asset table), [docs/build-system.md](../docs/build-system.md), [docs/installer-options.md](../docs/installer-options.md), [docs/signing.md](../docs/signing.md).
+
+### Signing artifacts — delivered on every verb ([#678](https://github.com/Omega-JS-Stack/omega/issues/678))
+
+The Apple artifacts land in the target's `config/certs/` from the signing tree (`<companyRoot||brandRoot>/.omega/certificates/apple/`, the company workspace's when the brand carries the `.omega/company.json` stamp) at the start of `build`, `package`, `publish` and `deploy` — not only on a manager `manage` run. The copy rules and the byte-compare are `@omega.js/devkit/certs`'s `deliverCerts()`, the same ONE delivery the manager's disperse writer rides; desktop's framing is [src/utils/deliver-certs.js](../src/utils/deliver-certs.js). A target outside a brand, or a brand whose tree was never produced, is a silent no-op.
+
+`CSC_LINK` and `APPLE_API_KEY` used to be stamped into the target's `.env` by disperse. No machine writes a target `.env` any more, so the gulp entry DERIVES them ([src/utils/derive-signing-env.js](../src/utils/derive-signing-env.js)): an unset key whose delivered file exists gets the target-relative path (`config/certs/developer-id-application.p12`, `config/certs/AuthKey_<APPLE_API_KEY_ID>.p8`). An already-set value always wins, and an absent file sets nothing — electron-builder's own skip/auto-discovery logic then applies, exactly as when [sanitize-signing-env.js](../src/utils/sanitize-signing-env.js) deletes an empty placeholder.
+
+All three bundles strip `@dev-only` blocks in production builds — code between `/* @dev-only:start */` and `/* @dev-only:end */` is cut from the bundle, so dev warnings and simulation hooks (@omega.js/client's and the vendored themes' included) never ship. Dev builds keep them. The markers and the cut are one home, `@omega.js/devkit/strip-dev-blocks`; desktop, web and @omega.js/extension all reach it through the same `bundle()` composition (production builds only).
+
+### Config flow
+
+`config/omega.json5` (JSON5, in consumer; shared sections top-level + desktop settings under `targets.desktop`) → `Manager.getConfig()` (resolves via `@omega.js/config` — `targets.desktop` overlays the top level, brand-monorepo walk-up included — then applies derived defaults: `app.appId` ← `com.itwcreativeworks.<brand.id>`, `app.productName` ← `brand.name`) → injected into ALL THREE bundles at build time as an esbuild `define` of `OMEGA_BUILD_JSON` (plus a banner that assigns the same literal to `globalThis`/`window`). Runtime reads `OMEGA_BUILD_JSON.config` first (authoritative in packaged apps); dev falls back to resolving from disk.
+
+Required fields: `brand.id` + `brand.name`. Everything else has defaults. See [docs/installer-options.md](../docs/installer-options.md) for the full defaults table.
+
+### Schema validation
+
+Every field in `config/omega.json5` is declared in `@omega.js/config` — the shared OMEGA schema plus the desktop refinements (`TARGET_SCHEMAS.desktop`), vendored into `dist/vendor/config/` and exposed to consumers as `require('@omega.js/desktop/config')`. Runs at boot (hard-fails `manager.initialize()` if invalid) AND in `gulp/audit` (plus build-pipeline extras). See [docs/config-schema.md](../docs/config-schema.md).
+
+### Cross-context helpers
+
+Four Managers (main / renderer / preload / build-time) all mix in shared helpers via `attachTo(Manager)`: `isDevelopment()`, `isProduction()`, `isTesting()`, `getWebsiteUrl()`, `getEnvironment()`, `getFunctionsUrl()`, `getApiUrl()`, `getAuthUrl()` (the sign-in URL that round-trips an auth token back into the app via the `auth/token` deep link — never link the bare `/signin` page; apps launch it via **`manager.openAuthFlow()`** (main), which opens the user's REAL default browser and, in dev/test where the custom scheme isn't OS-registered, swaps the final hop for a one-shot nonce-checked loopback listener (RFC 8252) feeding the same deep-link pipeline — `lib/auth-flow.js`). Use these instead of grepping `process.env` ad-hoc. `getEnvironment()` returns `'development' | 'testing' | 'production'` (mutually exclusive — testing wins over dev); gate side effects on the INTENTIONAL check (`isProduction()` for prod-only, `isDevelopment() || isTesting()` for local-or-test) — never `!isDevelopment()`. See [docs/environment-detection.md](../docs/environment-detection.md).
+
+### Test framework
+
+`npx omega test` discovers + runs framework suites (`<@omega.js/desktop>/dist/test/suites/**`) plus consumer suites (`<cwd>/test/**`). Four layers: **build** (plain Node), **main** (spawned Electron), **renderer** (hidden BrowserWindow), **boot** (consumer's actual built bundle for end-to-end smoke tests). The worked CONSUMER example is the playground desktop target's [`test/`](../../brands/omega-playground/targets/desktop/test) ([#811](https://github.com/Omega-JS-Stack/omega/issues/811)): a build suite over its resolved config and a boot suite over its real bundle, each asserting only what that project declares or wires. A renderer suite reaches the project's OWN views by declaring `view: '<name>'`, which runs it on the boot lane's built app so the page carries the project's real preload, IPC handlers and config ([#813](https://github.com/Omega-JS-Stack/omega/issues/813)). See [docs/test-framework.md](../docs/test-framework.md), [docs/test-boot-layer.md](../docs/test-boot-layer.md).
+
+### Test coverage
+
+Every feature ships with tests at EVERY layer it has a surface in — logic (`build`/`main`), UI (`renderer` — real events on the real DOM), and end-to-end (`boot`). Skip a layer ONLY when the feature genuinely has no surface there (a pure build utility has no UI; a CSS-only tweak has no logic). "The logic test already covers it" is NOT a reason to skip the UI test — logic tests prove the logic, UI tests prove the wiring, boot tests prove the built artifact. See [docs/test-framework.md](../docs/test-framework.md).
+
+### Dev logs
+
+Every gulp invocation tees stdout+stderr to `<projectRoot>/logs/dev.log` on `npm start` or `logs/build.log` on a production build/package (`OMEGA_BUILD_MODE=true`) — chosen by build mode, path via `OMEGA_LOG_FILE`; disable with `OMEGA_LOG_FILE=false`. `npx omega test` likewise tees its output to `<projectRoot>/logs/test.log`, and `npm run release` streams the GH Actions run to `logs/ci.log`. The packaged app's own `logs/runtime.log` (main + preload + renderer) sits beside them, and Windows signing appends `logs/signing.log`. When debugging via Claude, prefer `cat logs/dev.log` / `cat logs/test.log` over copy-pasting terminal scrollback — never restart the app to see output it already wrote. The runtime logger: [docs/logging.md](../docs/logging.md); the cross-framework tee contract and the full path table: [docs/shared/logging.md](shared/logging.md).
+
+### CDP debugging (Claude ↔ Electron)
+
+`serve` forwards all `--` CLI flags to the Electron child process. Set `OMEGA_CDP_PORT=9222` (or pass `--remote-debugging-port=9222` via `--`) to expose Chrome DevTools Protocol on that port. Drive the running app with the built-in toolkit — `npx omega cdp status|eval|shot|capture|theme|relaunch|quit` (multi-target by URL substring; `relaunch` IS the dev iterate loop since serve has no watch) — or via the `chrome-devtools-electron` MCP upstream for richer single-page interaction (click, fill, network, traces). See [docs/cdp-debugging.md](../docs/cdp-debugging.md).
+
+## CLI
+
+`npx omega <command>` (bare `omega` prints the listing). Every verb runs `ensureTarget()` first — the local scaffold the retired `omega setup` used to own ([#675](https://github.com/Omega-JS-Stack/omega/issues/675)): scripts, `.nvmrc` seed, Node check, peer deps, the defaults tree, the locality warning. It writes no `.env` ([#678](https://github.com/Omega-JS-Stack/omega/issues/678)): the brand root's `.env` is the one file humans and the manager edit, and a target `.env` is an optional per-key override you author yourself. The scripts it syncs spell the verb BARE (`omega build`, never `npx omega`) — npm already puts `node_modules/.bin` on the path inside a script; the `npx` form stays canonical for docs and the terminal ([#748](https://github.com/Omega-JS-Stack/omega/issues/748)). The gulp verbs get it from the `defaults` task; `test` and `deploy` call it themselves:
+
+| Command | Description |
+|---|---|
+| `clean` | remove `dist/`, `release/`, `.cache/` |
+| `install` | install peer deps |
+| `version` | print versions |
+| `test` | run the project's test suites (`framework:` / `full:` reach the framework suite) |
+| `update` | dependency freshness report (installed/wanted/latest + patch/minor/major, < 7-day releases QUARANTINED); `--apply` installs the safe set via npu, `--major` explicit. Aliases: `outdated`, `out`. See docs/shared/updates.md in the Omega repo |
+| `deploy` | delegate to the release flow (the deliberate-deploy verb; see docs/shared/deploys.md in the Omega repo). Runs the NETWORK prechecks first — framework freshness, `validate-certs`, repo provisioning, `push-secrets` — each soft; `--no-secrets` skips them all |
+| `logs [runtime|dev|build|test]` | read one of the project's log files, `runtime` by default (alias `log`) |
+| `help` | command listing (router built-in; also `-h`/`--help`) |
+| `build` | clean + certs delivery + `gulp build`, with `OMEGA_BUILD_MODE=true` set in-process |
+| `package` | clean + certs delivery + the electron-builder package (`--quick` for host platform/arch only) |
+| `publish` | certs delivery + full sign + notarize + GH release upload (`OMEGA_IS_PUBLISH=true`); `--local` cleans first |
+| `validate-certs` | check cert files, env vars, profile expiration, Keychain identity. Auto-runs as an `omega deploy` precheck |
+| `push-secrets` | publish the schema's delivered set for desktop (values from the composed env, file-path secrets base64'd from disk) as GH Actions secrets, through the shared `gh` boundary web and the extension use — values on stdin, never logged, `gh auth login` the only credential. A CI run, an empty cascade, no remote, or a checkout that is not the brand's declared repo skips loudly. `--only=KEY,KEY` narrows; auto-runs as an `omega deploy` precheck |
+| `sign-windows` | strategy-aware EV/cloud/local signer; emits JSONL events for `runner monitor` |
+| `runner monitor` | tails `omega-signing.log` and pretty-prints signing events |
+| `launch` | launch a packaged app with clean env (strips `ELECTRON_RUN_AS_NODE`); auto-discovers `release/<platform>-<arch>/<App>.app`. Aliases: `mgr open` |
+| `finalize-release` | `--signed-dir` uploads signed installers; `--publish` flips release Draft→Published |
+| `release` | trigger consumer's GH Actions Build & Release workflow, poll-stream logs |
+
+See [docs/releasing.md](../docs/releasing.md) for the end-to-end flow.
+
+**The release verbs read the repo from CONFIG** ([#799](https://github.com/Omega-JS-Stack/omega/issues/799)): `release` and `deploy` dispatch on the brand's app repo (`@omega.js/config`'s `brandRepo`), and `finalize-release`, the deploy precheck's provisioning and the electron-builder publish block all address the brand's ONE public releases repo (`releasesRepo`: `<brand.id>-releases` under the brand repo's owner unless `targets.desktop.releases` names another). No git remote is read anywhere, so a target inside a brand monorepo stops targeting the repo it is nested in. The dispatched workflow is the one the scaffold wrote: `desktop-build.yml` at the brand root, `build.yml` standalone, named by the same `@omega.js/devkit/ci-workflows` helper web and the extension use. The `downloads:` mirror lane retired with it.
+
+**`finalize-release` finds the release by LISTING, drafts included** ([#810](https://github.com/Omega-JS-Stack/omega/issues/810)): a draft carries no tag ref, so `repos.getReleaseByTag` answers with PUBLISHED releases only and 404'd on the very draft electron-builder had just created. Every run then made another draft for the same version (two v0.0.1 drafts on the playground's releases repo), and a full run would have split its assets across two of them while the `--publish` flip found neither. Both call sites (the signed-Windows upload and the flip) now read through one `findRelease` helper that paginates `repos.listReleases` and matches `tag_name`: the newest draft wins, since that is the one this run's publish step created; a published release answers when no draft carries the tag; and only a tag with neither leaves the upload step creating the draft a partial-platform run needs. Uploading an asset whose name is already on the release deletes the old one first, with one line naming the replacement, so re-running a version never collides.
+
+**The release workflow runs no tests** ([#802](https://github.com/Omega-JS-Stack/omega/issues/802)): it is dispatch-only and builds, like web's and the extension's. The suites run on the developer's machine and the commit gate runs the battery at ship ([docs/shared/testing.md](shared/testing.md)), so the Test job the workflow used to carry is gone: `build` needs `setup`, and `finalize`, the job that flips the draft release to published, needs `[setup, build, windows-sign]` and gates on `needs.build.result == 'success'` inside its `always()`.
+
+## Dependency Resolution
+
+- **Consumer code can `require()` any @omega.js/desktop dependency** — the bundler re-resolves every name @omega.js/desktop DECLARES from the framework's own installation (`@omega.js/devkit/bundle`'s framework-deps hook). Consumer projects do NOT need to `npm install firebase`, `fs-jetpack`, `@omega.js/client`, or any other @omega.js/desktop dep. If a dep doesn't resolve, the fix is in @omega.js/desktop's `package.json` or its bundle task — not the consumer's `package.json`.
+- **The framework's copy wins ([#87](https://github.com/Omega-JS-Stack/omega/issues/87)).** Every name @omega.js/desktop DECLARES is re-resolved from the framework root by `@omega.js/devkit/bundle`'s resolve hook, so a consumer that declares its own version of a framework dependency still bundles ONE copy — the framework's — the identical hook and guarantee @omega.js/web gives web consumers. npm nests a framework-private copy only when the consumer's declaration conflicts, so this picks the nested copy on a conflict and the shared hoisted copy otherwise. There is no per-dependency override today, so a consumer that genuinely needs its OWN copy of a framework-carried package should raise it upstream ([#87](https://github.com/Omega-JS-Stack/omega/issues/87)) rather than pin and silently lose. Narrower than the webpack `resolve.modules` ordering it replaced ([#737](https://github.com/Omega-JS-Stack/omega/issues/737)): a package the framework only carries TRANSITIVELY is no longer forced to the framework's copy, because the hook reads the declared set. @omega.js/extension is on the same hook since [#738](https://github.com/Omega-JS-Stack/omega/issues/738); pinned by `src/test/suites/build/framework-deps.test.js` in each.
+- **@omega.js/client owns Firebase.** Consumer code NEVER imports Firebase directly (`require('firebase')` / `import('firebase/app')`). Use `require('@omega.js/client')` → `omega.auth()`, `omega.firestore()` in renderers. In main process, use `manager.omega` (the @omega.js/desktop bridge). Same rule in BXM and UJM.
+- **`Manager.require(name)`** resolves from @omega.js/desktop's module context at runtime (static + prototype). Use in gulp tasks or unbundled code (e.g. test fixtures). The bundle task's framework-deps hook handles the bundled case.
+
+## Development Workflow
+
+- **🚫 NEVER use `npx omega ...` from the framework repo** — `npx omega` is for CONSUMER projects only (where the bin lives in `node_modules/.bin/`). From the framework repo, use `npm test`, `npm start`, etc. — the `scripts` in `package.json` call `node bin/omega-desktop` directly. This applies to ALL four OMEGA frameworks (@omega.js/backend, UJM, @omega.js/extension, @omega.js/desktop).
+- **🚫 NEVER run `npm start`** (consumer projects) — it's the user's long-running dev process. Assume it's already running; if it isn't, **instruct the user to run it** rather than running it yourself (running it again kills theirs). To see output, **read the `logs/*.log` files** (`dev.log`, `runtime.log`, `test.log`) — never tail/attach to the process. Running `npx omega test` is fine.
+- **After editing files**, verify the gulp watcher recompiled successfully. Check for esbuild/sass errors in the console output. A change that breaks the build is not a completed change.
+- **Live-test UI changes via CDP.** After code changes compile, use the `chrome-devtools-electron` MCP tools (screenshots, click, evaluate JS, console logs) to verify the change works in the running app. This is the primary way to confirm UI/renderer changes — type-checking and test suites verify code correctness, not feature correctness. See [docs/cdp-debugging.md](../docs/cdp-debugging.md) and `~/.claude/mcp-server/servers/chrome-devtools-electron/CLAUDE.md`.
+
+## Supply-Chain Security
+
+All `npm install` calls in CLI commands (`npx omega i`, `npx omega runner`, the peer-dependency step of every verb's `ensureTarget()`) route through the `safeInstall()` helper (`src/utils/safe-install.js`). It prefixes `sfw` (Socket Firewall) when installed — blocking confirmed malware at the network level before packages reach disk. Falls back to plain npm if sfw isn't available. CI workflows install sfw globally and run `sfw npm ci`. Installs will **fail if sfw detects confirmed malware** in any package in the dependency tree; non-critical CVEs and quality warnings pass through.
+
+## File Conventions
+
+- **CommonJS** (`require()`) throughout. Node 24 runs ESM deps natively via `require()` — no need for dynamic `import()` unless a package is genuinely ESM-only. For ESM-only deps in bundled code, use a STATIC-specifier `await import('pkg')` — esbuild inlines the module into the consumer's bundle so packaged apps need nothing installed (e.g. `electron-store@11` in `lib/storage.js`). NEVER make a dep import unbundlable (a variable specifier, or an ignore comment): it leaves a runtime resolution that fails in packaged consumers (@omega.js/desktop is a devDependency — it never ships in the asar).
+- **Node version auto-synced from Electron.** The consumer's `postinstall` (`scripts/sync-nvmrc.js`) queries `releases.electronjs.org` and writes `.nvmrc` to match — the ONE reader of that feed. `ensureTarget()` only SEEDS `.nvmrc` from the framework's pinned `omega.nodeRuntime` when the file is missing, so the two never fight, and warns when the running Node major is not the pin.
+- One `module.exports = ...` per file.
+- Logical operators at the **start** of continuation lines.
+- Short-circuit early returns rather than nested ifs.
+- Prefer **`fs-jetpack`** over `fs-extra`.
+- **No backwards compatibility** unless explicitly requested — this is unreleased v1.
+- **Lib structure — 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. No lib is split today — `lib/sentry/` was the one, and it moved WHOLE into `@omega.js/monitoring` (#380) once the backend and the client needed the same policy. Don't split prophylactically.
+- **Use `app.getAppPath()`, not `process.cwd()`, for runtime path resolution.** In a packaged app, `process.cwd()` is `/`. Use `require('./utils/app-root.js')()` — tries `app.getAppPath()` first, falls back to `process.cwd()` for tests/non-Electron contexts.
+- **Zero-trust URL handling — `sanitizeURL` for `shell.openExternal` and friends.** Any dynamic URL passed to `shell.openExternal`, `BrowserWindow.loadURL`, `window.location.href =`, etc. MUST be gated through `require('./utils/sanitize-url.js')` first. Returns the URL unchanged when its protocol is `http:`/`https:`, and `''` for anything else (`javascript:`, `data:`, `file:`, `vbscript:`, `chrome:`, custom schemes). Canonical pattern: `const safe = sanitizeURL(url); if (safe) shell.openExternal(safe);`. Hardcoded URLs constructed entirely from internal constants (e.g. the restart-manager feed URLs built from schema-validated config in `lib/restart-manager/install.js`) bypass — not attacker-controllable. See `src/utils/sanitize-url.js` and the `js:patterns/xss-escaping` skill.
+- **`ELECTRON_RUN_AS_NODE` is stripped at the CLI boundary.** When set, Electron silently runs as plain Node — `app` is undefined, no BrowserWindow. The variable leaks from common parent processes (VS Code's Claude Code extension runs as a `node.mojom.NodeService` utility process with the var set). `bin/omega-desktop` and `src/gulp/main.js` both `delete process.env.ELECTRON_RUN_AS_NODE` at the top.
+
+## Doc-update parity
+
+Whenever you make a behavioral change (new command, new flag, new pattern, removed feature), update:
+
+1. **`README.md`** — user-facing summary
+2. **`docs/desktop/index.md`** (this file) — architecture overview, one paragraph or cross-link
+3. **`docs/<topic>.md`** — the meat. If a topic doesn't have a doc yet, create one.
+4. **`CHANGELOG.md`** — if the project keeps one
+
+Don't ship behavioral changes with stale docs. Validate first, then document — write docs that describe shipped reality, not intentions.
+
+**The four framework guides are structurally MIRRORED.** [docs/web/index.md](../web/index.md), [docs/backend/index.md](../backend/index.md), [docs/desktop/index.md](../desktop/index.md), and [docs/extension/index.md](../extension/index.md) keep the same section skeleton in the same order, and each consumer template (`src/defaults/AGENTS.md`; web's lives at `scaffold/AGENTS.md`) mirrors its guide. Never add, rename, or reorder a section in one without making the SAME change in the others in the same pass.
+
+## Documentation
+
+API references for each subsystem live in `docs/`. **Whenever you make a behavioral change, update both this overview AND the relevant `docs/*.md` deep reference.** Treat docs as a first-class deliverable, not an afterthought.
+
+- [docs/boot-sequence.md](../docs/boot-sequence.md) — full `manager.initialize()` ordered list + rationale
+- [docs/lib-modules.md](../docs/lib-modules.md) — lib initialization contract, adding a new lib, flat-vs-split convention
+- [docs/storage.md](../docs/storage.md) — main + renderer storage, dot-notation, change broadcasts
+- [docs/ipc.md](../docs/ipc.md) — typed channel bus
+- [docs/windows.md](../docs/windows.md) — named windows, bounds persistence, hide-on-close, inset titlebar
+- [docs/tray.md](../docs/tray.md) — file-based tray
+- [docs/menu.md](../docs/menu.md) — file-based application menu
+- [docs/context-menu.md](../docs/context-menu.md) — file-based right-click menus
+- [docs/startup.md](../docs/startup.md) — launch modes, zero-bounce production
+- [docs/app-state.md](../docs/app-state.md) — launch flags, crash sentinel
+- [docs/deep-link.md](../docs/deep-link.md) — cross-platform deep links, single-instance, built-in routes
+- [docs/client-bridge.md](../docs/client-bridge.md) — Firebase auth state sync across main + renderers, session persistence (safeStorage vault), the renderer @omega.js/client auth cycle (`data-omega-bind` bindings live in every renderer) + the resolved-plan push (`getResolvedPlan()`)
+- [docs/auto-updater.md](../docs/auto-updater.md) — startup + periodic checks, 30-day pending-update gate, idle-aware install
+- [docs/analytics.md](../docs/analytics.md) — GA4 Measurement Protocol, cross-platform `uuidv5` identity
+- [docs/context.md](../docs/context.md) — runtime context block (geolocation, client, session, app)
+- [docs/usage.md](../docs/usage.md) — opens / hoursTotal / hoursThisSession; clean-exit accumulation
+- [docs/remote-config.md](../docs/remote-config.md) — "hot config" fetched from brand site
+- [docs/remote-scripts.md](../docs/remote-scripts.md) — emergency remote code execution (opt-in, https-only), content-hash dedup
+- [docs/restart-manager.md](../docs/restart-manager.md) — the external guardian app: HTTP protocol v1 (SSOT), silent install, self-updates via its own @omega.js/desktop autoUpdater, threat model
+- [docs/config-schema.md](../docs/config-schema.md) — canonical schema + validator
+- [docs/sentry.md](../docs/sentry.md) — the desktop half of `@omega.js/monitoring`, auto auth attribution
+- [docs/templating.md](../docs/templating.md) — `{{ }}` token replacement, page vars, HTML pipeline
+- [docs/logging.md](../docs/logging.md) — runtime logger (main + preload + renderer → one `runtime.log`)
+- [docs/themes.md](../docs/themes.md) — vendored classy + bootstrap themes, per-page CSS bundles, system-aware appearance (`manager.theme`)
+- [docs/tooltips.md](../docs/tooltips.md) — Bootstrap JS ships in @omega.js/desktop (prebuilt bundle, Popper inlined): zero-setup auto-initialized tooltips, `window.bootstrap` namespace
+- [docs/css.md](../docs/css.md) — SCSS architecture: main entry, theme `@use` config, per-window bundles, Bootstrap-first
+- [docs/hooks.md](../docs/hooks.md) — lifecycle hooks (build/pre, build/post, release/pre, release/post, notarize/post)
+- [docs/shared/icons.md](../docs/icons.md) — convention-only icon resolution (`global/` + per-platform), retina derivation, macOS Template magic
+- [docs/fontawesome.md](../docs/fontawesome.md) — Font Awesome Free served from the npm dep (icon semantics shared with web via @omega.js/client's icon-core): `<i class="fa-solid fa-*">` auto-render, `manager.fontawesome.get`
+- [docs/verts.md](../docs/verts.md) — `[data-omega-vert]` auto-bind to @omega.js/client's verts module (live via MutationObserver): house/company lane ONLY (type pinned 'house' — no AdSense in desktop surfaces)
+- [docs/installer-options.md](../docs/installer-options.md) — per-target installer config, defaults table
+- [docs/signing.md](../docs/signing.md) — code signing for macOS + Windows
+- [docs/releasing.md](../docs/releasing.md) — end-to-end release walkthrough
+- [docs/runner.md](../docs/runner.md): Windows EV-token signing runner. The listener runs with a private HOME (`%LOCALAPPDATA%\omega-runner\home`, holding a real `.gitconfig`), written at install and healed by `start`/`restart`, so a job's `actions/checkout` never copies the box's symlinked `~/.gitconfig` into a junction it cannot read ([#807](https://github.com/Omega-JS-Stack/omega/issues/807))
+- [docs/test-framework.md](../docs/test-framework.md) — writing tests, running them, layers
+- [docs/test-boot-layer.md](../docs/test-boot-layer.md) — the `boot` test layer: consumer end-to-end smoke + @omega.js/desktop's framework self-test from the repo via the bundled fixture (`src/test/fixtures/consumer-app/`) + `OMEGA_TEST_BOOT_PROJECT` (@omega.js/desktop's analog of @omega.js/backend/BXM/UJM `*_TEST_BOOT_PROJECT`)
+- [docs/build-system.md](../docs/build-system.md) — gulp, esbuild, electron-builder pipeline
+- [docs/environment-detection.md](../docs/environment-detection.md) — `isDevelopment`/`isTesting`/`getApiUrl` etc., adding new helpers
+- [docs/common-mistakes.md](../docs/common-mistakes.md) — the canonical "don't do this" list
+- [docs/audit.md](../docs/audit.md) — full-audit check catalog (U-xx universal / DSK-xx / F-xx IDs with severity + scope), protocol + fix loop
+- [docs/cdp-debugging.md](../docs/cdp-debugging.md) — Claude ↔ Electron via CDP: the `mgr cdp` toolkit (status/eval/shot/capture/theme/relaunch/quit), `OMEGA_CDP_PORT`, MCP setup
+
+`PROGRESS.md` tracks pass-by-pass progress and decisions.