@omega.js/desktop 0.53.0 → 0.54.1

package/dist/vendor/devkit/update.js

@@ -4,10 +4,10 @@
  * tool): per dependency report installed vs wanted vs latest, classify the
  * jump (patch/minor/major), and QUARANTINE releases younger than --min-age
  * days (default 7 — a brand-new publish may be a compromised one; hold it
- * back unless explicitly forced). Report-only by default; --apply installs
- * the non-quarantined, non-breaking set (majors need the explicit --major
- * opt-in) through `npu install` when npu is on the machine, else plain
- * `npm install` with a loud note.
+ * back unless explicitly forced). A bare run installs the non-quarantined,
+ * non-breaking set (majors need the explicit --major opt-in) through
+ * `npu install` when npu is on the machine, else plain `npm install` with a
+ * loud note; --dry-run reports and installs nothing.
  *
  * `file:`/`link:`/git specs have no registry story (the local era's linked
  * @omega.js packages) — they're skipped with a dim note, never updated.
@@ -332,7 +332,7 @@ async function buildUpdateReport(options) {
 }
 
 /**
- * Pick the updates an --apply run installs. Default tier is MINOR (highest
+ * Pick the updates a run installs. Default tier is MINOR (highest
  * same-major — npu's non-breaking lane); --major unlocks latest. A target
  * published < minAge days ago is HELD (quarantine) unless already installed.
  * @param {object[]} rows - buildUpdateReport rows
@@ -469,7 +469,7 @@ function formatReport(report, options = {}) {
     for (const cells of body) lines.push(render(cells));
 
     if (report.rows.some((row) => row.quarantined)) {
-      lines.push(`QUARANTINED = latest published < ${minAge} days ago (held from --apply; --min-age 0 or --force-fresh overrides)`);
+      lines.push(`QUARANTINED = latest published < ${minAge} days ago (held from the install; --min-age 0 or --force-fresh overrides)`);
     }
     if (report.rows.some((row) => row.bump === 'major')) {
       lines.push('major = breaking — never auto-applied (explicit --major opt-in)');
@@ -484,14 +484,14 @@ function formatReport(report, options = {}) {
 }
 
 /**
- * The one verb body every wrapper calls: report (default), then apply when
- * asked. Flags mirror npu: --apply, --major, --min-age N (default 7, 0
- * disables), --force-fresh (alias for --min-age 0).
+ * The one verb body every wrapper calls: report, then install (default) or
+ * stop at the report (--dry-run). Flags mirror npu: --major, --min-age N
+ * (default 7, 0 disables), --force-fresh (alias for --min-age 0).
  * @param {object} [options]
  * @param {string} [options.dir] - target directory (default cwd)
  * @param {string[]} [options.only] - check just these package names (#794)
- * @param {boolean} [options.apply] - install the selected set
- * @param {boolean} [options.major] - allow breaking jumps (with --apply)
+ * @param {boolean} [options.dryRun] - report only, install nothing
+ * @param {boolean} [options.major] - allow breaking jumps
  * @param {number} [options.minAge] - quarantine threshold in days
  * @param {boolean} [options.forceFresh] - disable the age quarantine
  * @param {object} [options.logger] - logger with log/warn (default console)
@@ -512,9 +512,9 @@ async function runUpdate(options = {}) {
   logger.log(`Dependency report for ${report.project}:`);
   for (const line of formatReport(report, { minAge })) logger.log(line);
 
-  if (!options.apply) {
+  if (options.dryRun) {
     if (report.rows.length > 0) {
-      logger.log('Report only — `omega update --apply` installs the non-quarantined, non-breaking set (--major for breaking).');
+      logger.log('Dry run (--dry-run): nothing installed; a bare `omega update` installs the non-quarantined, non-breaking set (--major for breaking).');
     }
     return { report, selection: null, commands: [] };
   }
@@ -529,7 +529,7 @@ async function runUpdate(options = {}) {
   }
 
   if (selection.updates.length === 0) {
-    logger.log('Nothing to apply.');
+    logger.log('Nothing to install.');
     return { report, selection, commands: [] };
   }
 
@@ -545,7 +545,7 @@ async function runUpdate(options = {}) {
     execFn(entry.command, { cwd: dir, stdio: 'inherit' });
   }
 
-  logger.log(`Applied ${selection.updates.length} update(s).`);
+  logger.log(`Installed ${selection.updates.length} update(s).`);
   return { report, selection, commands };
 }
 

package/dist/vendor/devkit/verb-scripts.js

@@ -0,0 +1,40 @@
+/**
+ * verb-scripts: the package.json scripts a framework scaffolds into its targets,
+ * derived from the one verb table (verbs.js). Every fan-out verb a framework owns
+ * (fanout `each`) is `"<verb>": "omega <verb>"`, so the brand-root fan-out's
+ * `npm run <verb>` reaches the framework in every target, and `dev` is
+ * `"start": "omega dev"`. A single-target command (fanout `none`) is no script:
+ * the brand root passes it to the framework's CLI. Vendored with the table into
+ * every framework dist.
+ */
+
+const { VERBS } = require('./verbs.js');
+
+// npm names the dev script `start` (`npm start`), and the brand-root `omega dev`
+// runs each target's `npm run start`.
+const SCRIPT_KEYS = { dev: 'start' };
+
+/**
+ * The verb scripts a framework owns.
+ *
+ * @param {string} framework - The framework package name ('@omega.js/web', ...).
+ * @returns {Object<string, string>} Script name to `omega <verb>`, in table order.
+ */
+function verbScripts(framework) {
+  return Object.fromEntries(VERBS
+    .filter((row) => row.owners.includes(framework) && (row.fanout === 'each' || row.name in SCRIPT_KEYS))
+    .map((row) => [SCRIPT_KEYS[row.name] || row.name, `omega ${row.name}`]));
+}
+
+/**
+ * Every script a framework writes into a target: its verb scripts, with the
+ * scripts its manifest still declares (`projectScripts`) merged over them.
+ *
+ * @param {object} manifest - The framework's own package.json.
+ * @returns {Object<string, string>} Script name to command.
+ */
+function projectScripts(manifest) {
+  return { ...verbScripts(manifest.name), ...(manifest.projectScripts || {}) };
+}
+
+module.exports = { verbScripts, projectScripts };

package/dist/vendor/devkit/verbs.js

@@ -0,0 +1,170 @@
+/**
+ * verbs: the ONE verb table. Every verb any OMEGA CLI answers to, declared once
+ * with where it runs (`scope`), who answers it (`owners`) and how a root runs it
+ * (`fanout`, `order`, `dryRun`). The dispatcher, the brand-root fan-outs and the
+ * target-script scaffolds (verb-scripts.js) read it; the field contract lives in
+ * docs/devkit/index.md. Pure data: the dispatcher that requires it is vendored
+ * into every framework dist.
+ */
+
+const MANAGER = '@omega.js/manager';
+const WEB = '@omega.js/web';
+const BACKEND = '@omega.js/backend';
+const DESKTOP = '@omega.js/desktop';
+const EXTENSION = '@omega.js/extension';
+const ALL = [MANAGER, WEB, BACKEND, DESKTOP, EXTENSION];
+
+// The order every 'each' verb walks: backend's API goes live before the
+// surfaces that call it. A target type with no rank runs after every ranked one.
+const TARGET_ORDER = Object.freeze(['backend', 'web', 'extension', 'desktop', 'mobile']);
+
+const SCOPES = Object.freeze(['root', 'contextless', 'box']);
+const FANOUTS = Object.freeze(['each', 'root', 'none']);
+
+const VERBS = Object.freeze([
+  // ─── contextless: run with no target at all ───────────────────────────────
+  { name: 'onboard', aliases: ['-o', '--onboard', 'create', 'new'], scope: 'contextless', owners: [MANAGER],
+    fanout: 'root', order: null, dryRun: false },
+  { name: 'help', aliases: ['h', '-h', '--help'], scope: 'contextless', owners: ALL,
+    fanout: 'root', order: null, dryRun: false },
+  { name: 'version', aliases: ['v', '-v', '--version'], scope: 'contextless', owners: ALL,
+    fanout: 'root', order: null, dryRun: false },
+  // none: prints ONE target's resolved root
+  { name: 'cwd', aliases: [], scope: 'contextless', owners: [BACKEND],
+    fanout: 'none', order: null, dryRun: false },
+  // none: reads one target's logs; interleaved streams would be unreadable
+  { name: 'logs', aliases: ['log', '--logs', 'logs:read', 'logs:tail', 'logs:stream'], scope: 'contextless', owners: [DESKTOP, BACKEND],
+    fanout: 'none', order: null, dryRun: false },
+
+  // ─── box: the signing box is a machine, not a project ─────────────────────
+  // none: the runner is the box's own service, configured from the runner home
+  { name: 'runner', aliases: ['--runner'], scope: 'box', owners: [DESKTOP],
+    fanout: 'none', order: null, dryRun: false },
+  // none: signs one artifact on the box, from any directory
+  { name: 'sign-windows', aliases: ['--sign-windows'], scope: 'box', owners: [DESKTOP],
+    fanout: 'none', order: null, dryRun: false },
+
+  // ─── brand-root fan-outs ──────────────────────────────────────────────────
+  { name: 'deploy', aliases: ['-d', '--deploy'], scope: 'root', owners: ALL,
+    fanout: 'each', order: TARGET_ORDER, dryRun: false },
+  { name: 'build', aliases: ['-b', '--build'], scope: 'root', owners: ALL,
+    fanout: 'each', order: TARGET_ORDER, dryRun: true },
+  { name: 'clean', aliases: ['-c', '--clean', 'clean:npm'], scope: 'root', owners: ALL,
+    fanout: 'each', order: TARGET_ORDER, dryRun: true },
+  { name: 'update', aliases: ['-u', '--update'], scope: 'root', owners: ALL,
+    fanout: 'each', order: TARGET_ORDER, dryRun: false },
+  { name: 'test', aliases: ['-t', '--test'], scope: 'root', owners: ALL,
+    fanout: 'each', order: TARGET_ORDER, dryRun: false },
+
+  // ─── the manager's own, run once at the brand root ────────────────────────
+  // root: the link flip walks every target from the brand root, so it runs once, never per target
+  { name: 'install', aliases: ['-i', 'i', '--install'], scope: 'root', owners: [MANAGER],
+    fanout: 'root', order: null, dryRun: false },
+  // root: the brand root boots every target's dev at once; a target runs its own framework's in place
+  { name: 'dev', aliases: ['--dev', 'serve', 'start'], scope: 'root', owners: ALL,
+    fanout: 'root', order: null, dryRun: false },
+  { name: 'manage', aliases: [], scope: 'root', owners: [MANAGER],
+    fanout: 'root', order: null, dryRun: false },
+  { name: 'bump', aliases: ['--bump'], scope: 'root', owners: [MANAGER],
+    fanout: 'root', order: null, dryRun: false },
+  { name: 'company', aliases: [], scope: 'root', owners: [MANAGER],
+    fanout: 'root', order: null, dryRun: false },
+  { name: 'devlog', aliases: [], scope: 'root', owners: [MANAGER],
+    fanout: 'root', order: null, dryRun: false },
+  { name: 'pipeline', aliases: [], scope: 'root', owners: [MANAGER],
+    fanout: 'root', order: null, dryRun: false },
+  // root: converts the brand config, then walks every target's migrate entry in-process
+  { name: 'migrate', aliases: ['-m', '--migrate', 'migration'], scope: 'root', owners: [MANAGER],
+    fanout: 'root', order: null, dryRun: false },
+
+  // ─── @omega.js/web ────────────────────────────────────────────────────────
+  // none: materializes ONE named page or file into one web target
+  { name: 'customize', aliases: ['-cz', '--customize'], scope: 'root', owners: [WEB],
+    fanout: 'none', order: null, dryRun: false },
+  { name: 'translate', aliases: ['--translate', 'translation'], scope: 'root', owners: [WEB],
+    fanout: 'each', order: TARGET_ORDER, dryRun: false },
+  { name: 'audit', aliases: ['-a', '--audit'], scope: 'root', owners: [WEB],
+    fanout: 'each', order: TARGET_ORDER, dryRun: false },
+  { name: 'purge', aliases: ['-cf', '--purge', 'cloudflare-purge'], scope: 'root', owners: [WEB],
+    fanout: 'each', order: TARGET_ORDER, dryRun: false },
+
+  // ─── @omega.js/desktop ────────────────────────────────────────────────────
+  { name: 'package', aliases: [], scope: 'root', owners: [DESKTOP],
+    fanout: 'each', order: TARGET_ORDER, dryRun: false },
+  { name: 'validate-certs', aliases: ['certs', '--validate-certs'], scope: 'root', owners: [DESKTOP],
+    fanout: 'each', order: TARGET_ORDER, dryRun: false },
+  // none: a CI leg's step on the tree that leg just built, one runner at a time
+  { name: 'publish', aliases: ['-p', '--publish'], scope: 'root', owners: [DESKTOP],
+    fanout: 'none', order: null, dryRun: false },
+  // none: cuts one signed release of one app
+  { name: 'release', aliases: ['-r', '--release'], scope: 'root', owners: [DESKTOP],
+    fanout: 'none', order: null, dryRun: false },
+  // none: closes the one release the CI run just built
+  { name: 'finalize-release', aliases: ['finalize', '--finalize-release'], scope: 'root', owners: [DESKTOP],
+    fanout: 'none', order: null, dryRun: false },
+  // none: opens one built app on this machine
+  { name: 'launch', aliases: ['open', '--launch'], scope: 'root', owners: [DESKTOP],
+    fanout: 'none', order: null, dryRun: false },
+  // none: drives one running app over its debugging port
+  { name: 'cdp', aliases: [], scope: 'root', owners: [DESKTOP],
+    fanout: 'none', order: null, dryRun: false },
+
+  // ─── @omega.js/backend ────────────────────────────────────────────────────
+  // none: clears the terminal; there is nothing per target to repeat
+  { name: 'clear', aliases: [], scope: 'root', owners: [BACKEND],
+    fanout: 'none', order: null, dryRun: false },
+  // none: a long-running emulator suite for one backend; the multi-target boot is `dev`
+  { name: 'serve', aliases: [], scope: 'root', owners: [BACKEND],
+    fanout: 'none', order: null, dryRun: false },
+  { name: 'indexes', aliases: ['indexes:get', 'firestore:indexes', 'firestore:indexes:get'], scope: 'root', owners: [BACKEND],
+    fanout: 'each', order: TARGET_ORDER, dryRun: false },
+  // none: a long-running emulator keep-alive for one backend
+  { name: 'emulator', aliases: ['emulators'], scope: 'root', owners: [BACKEND],
+    fanout: 'none', order: null, dryRun: false },
+  // none: a long-running source watcher for one backend
+  { name: 'watch', aliases: [], scope: 'root', owners: [BACKEND],
+    fanout: 'none', order: null, dryRun: false },
+  // none: a long-running webhook forwarder into one local backend
+  { name: 'stripe', aliases: ['stripe:listen'], scope: 'root', owners: [BACKEND],
+    fanout: 'none', order: null, dryRun: false },
+  // none: reads or writes named documents in one project
+  { name: 'firestore:get', aliases: ['firestore:set', 'firestore:query', 'firestore:delete'], scope: 'root', owners: [BACKEND],
+    fanout: 'none', order: null, dryRun: false },
+  // none: reads or writes named users in one project
+  { name: 'auth:get', aliases: ['auth:list', 'auth:delete', 'auth:set-claims', 'auth:token'], scope: 'root', owners: [BACKEND],
+    fanout: 'none', order: null, dryRun: false },
+  // none: one stdio MCP server for one backend
+  { name: 'mcp', aliases: [], scope: 'root', owners: [BACKEND],
+    fanout: 'none', order: null, dryRun: false },
+  // none: a one-time conversion that changes what the live project enforces, run alone
+  { name: 'migrate:rules', aliases: ['migrate:firestore-rules'], scope: 'root', owners: [BACKEND],
+    fanout: 'none', order: null, dryRun: false },
+  // none: a one-time conversion of one older tree, run alone
+  { name: 'migrate:markers', aliases: [], scope: 'root', owners: [BACKEND],
+    fanout: 'none', order: null, dryRun: false },
+]);
+
+/**
+ * Every token that selects a verb: its name, then its aliases.
+ *
+ * @param {object} entry - A VERBS entry.
+ * @returns {string[]}
+ */
+function tokensOf(entry) {
+  return [entry.name, ...entry.aliases];
+}
+
+/**
+ * The verb a token selects, or null. A name wins over an alias: `serve` is a
+ * `dev` alias AND the backend's own verb, and the row that NAMES it answers.
+ *
+ * @param {string} token - The token as typed.
+ * @returns {object|null} The VERBS entry.
+ */
+function findVerb(token) {
+  return VERBS.find((entry) => entry.name === token)
+    || VERBS.find((entry) => entry.aliases.includes(token))
+    || null;
+}
+
+module.exports = { VERBS, TARGET_ORDER, SCOPES, FANOUTS, tokensOf, findVerb };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omega.js/desktop",
-  "version": "0.53.0",
+  "version": "0.54.1",
   "description": "OMEGA desktop framework — build, test, and package Electron apps for macOS, Windows, and Linux",
   "private": false,
   "publishConfig": {
@@ -36,17 +36,17 @@
     "./lib/window-manager": "./dist/lib/window-manager.js",
     "./cli": "./dist/cli-run.js",
     "./ensure-target": "./dist/commands/lib/ensure-target.js",
+    "./migrate": "./dist/commands/lib/migrate.js",
     "./scripts/sync-nvmrc": "./scripts/sync-nvmrc.js"
   },
   "bin": {
-    "omega": "./bin/omega",
-    "omg": "./bin/omg",
-    "mgr": "./bin/omega"
+    "omega": "bin/omega",
+    "omg": "bin/omg",
+    "mgr": "bin/omega"
   },
   "files": [
     "bin/",
     "dist/",
-    "docs/",
     "scripts/"
   ],
   "preparePackage": {
@@ -101,19 +101,13 @@
     "start": "npm run prepare:watch",
     "prepare": "node -e \"require('../devkit/tools/prepare-guard').run()\"",
     "prepare:watch": "node -e \"require('prepare-package/watch')()\"",
-    "test": "node ./bin/omega test"
+    "test": "node dist/cli-run.js test"
   },
   "projectScripts": {
-    "start": "omega clean && npm run gulp --",
     "gulp": "gulp",
-    "build": "omega build",
-    "package": "omega package",
     "package:quick": "omega package --quick",
-    "publish": "omega publish",
-    "release": "omega release",
     "release:local": "omega publish --local",
     "postinstall": "node -e \"try { require('@omega.js/desktop/scripts/sync-nvmrc') } catch (e) {}\"",
-    "test": "omega test",
     "electron": "electron ."
   },
   "engines": {
@@ -147,39 +141,39 @@
     "@omega.js/web": "*",
     "electron": "^42.0.1",
     "electron-builder": "^26.16.1",
-    "firebase-admin": "^13.9.0",
-    "prepare-package": "^2.2.0"
+    "firebase-admin": "^13.10.0",
+    "prepare-package": "^2.2.1"
   },
   "dependencies": {
-    "@fortawesome/fontawesome-free": "^7.3.0",
-    "@inquirer/prompts": "^8.5.2",
+    "@fortawesome/fontawesome-free": "^7.3.1",
+    "@inquirer/prompts": "^8.7.2",
     "@octokit/rest": "^22.0.1",
-    "@omega.js/client": "0.53.0",
+    "@omega.js/client": "0.54.1",
     "@popperjs/core": "^2.11.8",
     "@sentry/electron": "^7.13.0",
     "chalk": "^5.6.2",
     "dotenv": "^17.4.2",
-    "electron-log": "^5.4.3",
+    "electron-log": "^5.4.4",
     "electron-store": "^11.0.2",
     "electron-updater": "^6.8.3",
-    "esbuild": "^0.28.1",
+    "esbuild": "^0.28.2",
     "extract-zip": "^2.0.1",
     "fs-jetpack": "^5.1.0",
     "glob": "^13.0.6",
     "gulp-clean-css": "^4.3.0",
     "gulp-rename": "^2.1.0",
-    "gulp-responsive-modern": "^1.0.0",
+    "gulp-responsive-modern": "^1.0.4",
     "gulp-sass": "^6.0.1",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.3.2",
     "json5": "^2.2.3",
     "lodash": "^4.18.1",
-    "minimatch": "^10.2.5",
+    "minimatch": "^10.2.6",
     "node-powertools": "^3.0.0",
     "plist": "^4.0.0",
     "sass": "^1.99.0",
     "sharp": "^0.35.3",
-    "uuid": "^14.0.0",
-    "wonderful-fetch": "^2.0.5",
+    "uuid": "^14.0.2",
+    "wonderful-fetch": "^2.0.6",
     "wonderful-version": "^1.3.2",
     "ws": "^8.20.0"
   },

package/dist/commands/install.js

@@ -1,37 +0,0 @@
-// Libraries
-const build = require('../build.js');
-const logger = build.logger('install');
-const local = require('../vendor/devkit/local.js');
-
-const package = build.getPackage('main');
-
-module.exports = async function (options) {
-  logger.log(`Installing ${package.name}...`);
-
-  const type = options._[1] || 'prod';
-
-  try {
-    if (['live', 'prod', 'p', 'production'].includes(type)) {
-      // The publish-day inverse of `i local`: flip every file: spec in the
-      // brand tree to the exact <linked version>, then one registry install
-      logger.log('Installing production (restoring registry specs tree-wide)...');
-      const actions = await local.restoreRegistrySpecs({ dir: process.cwd(), logger });
-      const flipped = actions.filter((action) => action.action === 'flip').length;
-      return logger.log(flipped > 0
-        ? `Production installation complete (${flipped} spec(s) restored to registry ranges).`
-        : 'Already on registry specs — nothing to flip.');
-    }
-
-    if (['dev', 'd', 'development', 'local', 'l'].includes(type)) {
-      logger.log('Installing development (local Omega monorepo)...');
-      await local.linkLocalPackages({
-        dir: process.cwd(),
-        monorepoRoot: local.resolveMonorepoRoot(),
-        logger,
-      });
-      return logger.log('Development installation complete.');
-    }
-  } catch (e) {
-    logger.error('Error during install:', e);
-  }
-};

package/dist/defaults/AGENTS.md

@@ -1,119 +0,0 @@
-# ========== 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's renderer instance extends `@omega.js/client`'s base class.**
-- It powers auth, Firebase, reactive `data-omega-bind` directives, analytics, error tracking, and utilities (`escapeHTML`, etc.).
-- `omega.auth.user` is always a `User`: `authenticated`, `plan`, `active`, `profile.displayName`; `omega.auth.listen()` delivers `{ user, denied }`.
-- 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`.
-  - What the app SHIPS is one declaration: `platforms.<mac|windows|linux>.formats.<dmg|nsis|deb|appimage|snap>`. Presence = enabled, every platform and format is on by default, and `false` drops one (`snap: false`). Per-format settings live inside the format.
-- 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 (`mac/icon.png`, `mac/tray.png`, `mac/dmg.png`, `windows/icon.png`, etc.; the platform words are `mac`, `windows`, `linux`).
-  - 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
-
-Each entry exports ONE ready-made instance, `omega`; a consumer never writes `new`.
-
-```js
-// src/main.js
-const omega = require('@omega.js/desktop/main');
-omega.initialize().then(() => { const { logger, windows } = omega; });   // auto-loads JSON5 config
-
-// src/preload.js
-const omega = require('@omega.js/desktop/preload');
-omega.initialize();
-
-// src/assets/js/components/main/index.js
-import omega from '@omega.js/desktop/renderer';
-omega.initialize().then(() => { const { logger, desktop } = omega; });
-```
-
-## Available APIs at runtime
-
-In main, each a property of `omega`: `windows`, `tray`, `menu`, `contextMenu`, `ipc`, `storage`, `deepLink`, `autoUpdater`, `appState`, `startup`, `protocol`, `authFlow`, `theme`, `fontawesome`, `context`, `usage`, `remoteConfig`, `remoteScripts`, `restartManager`, `analytics`, `sentry`, `logger`.
-- `omega.auth` is the signed-in account in main: `.user` (a `User`), `.listen()`, `.signOut()`, `.getIdToken()`, `.handleToken()`.
-
-In renderer: the @omega.js/client base (`omega.auth`, `omega.firestore`, `omega.bindings`, and `omega.storage`, the page store) plus `omega.desktop`, the preload's bridge to main.
-- `omega.desktop.{ipc,storage,theme,fontawesome,autoUpdater,analytics,context,usage,remoteConfig}`; `omega.desktop.storage` is the app store, async over IPC.
-- Config: `window.OMEGA_BUILD_JSON.config` (the one `build.js` the view's shell loads).
-
-## 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')`. In renderers use `omega.auth` and `omega.firestore` on the renderer instance. In the main process, use `omega.auth` (the @omega.js/desktop bridge).
-- **`omega.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/CLAUDE.md

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