@omega.js/desktop 0.53.0 → 0.54.1

package/README.md

@@ -21,11 +21,11 @@
 - **Lazy windows + Discord-style hide-on-close.** @omega.js/desktop doesn't auto-create any windows — your `main.js` calls `windows.create('main', { show: !startup.isLaunchHidden() })`. The `main` window's X button hides instead of quitting on every platform; real quit only via Cmd+Q / menu Quit / tray Quit / auto-update install. Inset titlebar by default (mac `hiddenInset` traffic lights / win native overlay buttons / linux native frame) with a draggable topbar in the page template.
 - **Zero-bounce hidden-launch on macOS.** `startup.mode = 'hidden'` bakes `LSUIElement: true` into Info.plist at build time → app launches completely invisible (no dock icon, no Cmd+Tab, no taskbar). Tray + notifications + networking still work. When the user double-clicks the running app's icon, @omega.js/desktop's `app.on('activate')` (macOS) / `app.on('second-instance')` (win/linux) handler surfaces the `main` window and the dock icon appears alongside it. CleanMyMac-style "tray-only at login, full window when manually opened" is the default.
 - **Auto-update background install.** When a download finishes from a background poll (not user-initiated), @omega.js/desktop auto-relaunches into the new version after 5s — apps update overnight without bothering the user. User-initiated checks skip this so your UI can prompt instead.
-- **Vert (ad) units with zero JS.** Drop `<div data-omega-vert></div>` into any view — the renderer auto-binds it (live, MutationObserver) to the shared OMEGA verts module: house/company inventory only (no AdSense in desktop surfaces), lazy near-viewport loading, sandboxed iframe, no-fill collapse. See [verts](docs/verts.md).
+- **Vert (ad) units with zero JS.** Drop `<div data-omega-vert></div>` into any view — the renderer auto-binds it (live, MutationObserver) to the shared OMEGA verts module: house/company inventory only (no AdSense in desktop surfaces), lazy near-viewport loading, sandboxed iframe, no-fill collapse. See [verts](../../docs/desktop/verts.md).
 - **esbuild-bundled** main / preload / renderer for source protection.
 - **Built-in test framework**: Jest-like syntax, four layers: `build` (plain Node), `main` (spawned Electron), `renderer` (hidden BrowserWindow), and `boot` (spawns the consumer's actual built `dist/main.bundle.js` for end-to-end smoke tests against the live `omega`, no `npm start && sleep && kill` shell hacks). Boot layer always rebuilds the bundle first so tests never see stale code.
-- **Schema-validated config.** One `config/omega.json5` (the OMEGA-wide format: shared brand/analytics/payment/firebase sections + desktop settings under `targets.desktop`), validated against the canonical schema in the bundled `@omega.js/config`. Validation runs at app boot AND during `gulp audit` — a misconfigured app never reaches the "white window of confusion" stage; it tells you exactly which field is broken with a numbered list. Simple flag model — `required: true | false | (config) => bool` — and `match` / `enum` / `type` only fire on field presence so consumers never see a flood of redundant errors for the same field. Pure-JS validator, no Ajv/Joi/Zod dep. See [config-schema](docs/config-schema.md).
-- **Multi-platform build/release** via GitHub Actions — macOS sign + notarize, Linux (deb + AppImage + optional Snap), Windows EV-token signing (self-hosted runner now, cloud-signing pluggable). Sensible installer defaults out of the box: NSIS one-click install on Windows (desktop + start menu shortcut, launch on finish), universal mac binary (one .dmg for Intel + Apple Silicon), `app.category` automatically mapped to per-platform values, copyright `{YEAR}` token always current. Snap Store publishing is on by default in the scaffold and auto-skipped at build time when `SNAPCRAFT_STORE_CREDENTIALS` isn't set — drop the credential blob into `.env`, run `mgr push-secrets`, and the next release ships to the Snap Store. See [installer-options](docs/installer-options.md).
+- **Schema-validated config.** One `config/omega.json5` (the OMEGA-wide format: shared brand/analytics/payment/firebase sections + desktop settings under `targets.desktop`), validated against the canonical schema in the bundled `@omega.js/config`. Validation runs at app boot AND during `gulp audit` — a misconfigured app never reaches the "white window of confusion" stage; it tells you exactly which field is broken with a numbered list. Simple flag model — `required: true | false | (config) => bool` — and `match` / `enum` / `type` only fire on field presence so consumers never see a flood of redundant errors for the same field. Pure-JS validator, no Ajv/Joi/Zod dep. See [config-schema](../../docs/desktop/config-schema.md).
+- **Multi-platform build/release** via GitHub Actions — macOS sign + notarize, Linux (deb + AppImage + optional Snap), Windows EV-token signing (self-hosted runner now, cloud-signing pluggable). Sensible installer defaults out of the box: NSIS one-click install on Windows (desktop + start menu shortcut, launch on finish), universal mac binary (one .dmg for Intel + Apple Silicon), `app.category` automatically mapped to per-platform values, copyright `{YEAR}` token always current. Snap Store publishing is on by default in the scaffold and auto-skipped at build time when `SNAPCRAFT_STORE_CREDENTIALS` isn't set — drop the credential blob into `.env`, run `mgr push-secrets`, and the next release ships to the Snap Store. See [installer-options](../../docs/desktop/installer-options.md).
 
 ## Quick start (consumer)
 
@@ -36,11 +36,11 @@ npm install @omega.js/desktop --save-dev
 nvm use                  # switch to the Node version Electron uses (one-time per shell)
 npm start                # dev: gulp → esbuild → electron .
 OMEGA_CDP_PORT=9222 npm start  # dev + expose Chrome DevTools Protocol for Claude/MCP debugging
-npx omega cdp status       # drive the running dev app over CDP: status|eval|shot|capture|theme|relaunch|quit (docs/cdp-debugging.md)
+npx omega cdp status       # drive the running dev app over CDP: status|eval|shot|capture|theme|relaunch|quit (docs/desktop/cdp-debugging.md)
 npm run build            # local production build (bundles only, no installer)
 npm run package:quick    # fast packaged build for host platform/arch (.app/.exe-folder/linux-unpacked, ~20-30s) — for smoke-testing packaged behavior
 npm run package          # full local production package (DMG/zip/universal-mac, NSIS-win, deb+AppImage-linux)
-npm run release          # signed + published release via GitHub Actions
+npx omega release        # signed + published release via GitHub Actions
 npx omega test             # YOUR project tests only (C5 scoping — docs/shared/testing.md)
 npx omega test framework:  # the framework's own suite (aliases: omega:, mgr:, desktop:, em:; add a path to narrow)
 npx omega test full:       # both sources
@@ -82,7 +82,7 @@ Five logs in `<projectRoot>/logs/`, each with its own purpose:
 | `dev.log` | Gulp pipeline output — sass, bundle, html, electron child stdout from `npm start` | Truncated each `npm start` |
 | `build.log` | Gulp pipeline output for production builds/packages (`npm run build` / `package` / `publish`, i.e. `OMEGA_BUILD_MODE=true`) | Truncated each build |
 | `test.log` | `npx omega test` runner output (suite names, pass/fail, harness boot lines) | Truncated each test run |
-| `deploy.log` | `omega deploy` and `npm run release`, the whole deploy: the scaffold, the precheck, the dispatch, then the streamed GH Actions run | Truncated each deploy |
+| `deploy.log` | `omega deploy` and `omega release`, the whole deploy: the scaffold, the precheck, the dispatch, then the streamed GH Actions run | Truncated each deploy |
 
 ```bash
 npx omega logs                  # tail last 50 of runtime.log
@@ -96,7 +96,7 @@ In production, `runtime.log` lives at `app.getPath('logs')`:
 - Windows: `%APPDATA%\<AppName>\logs\runtime.log`
 - Linux: `~/.config/<AppName>/logs/runtime.log`
 
-See [docs/logging.md](docs/logging.md) for the full picture (renderer forwarding, log levels, programmatic path access).
+See [docs/desktop/logging.md](../../docs/desktop/logging.md) for the full picture (renderer forwarding, log levels, programmatic path access).
 
 Override gulp's `dev.log` path via `OMEGA_LOG_FILE=<path>`; disable entirely via `OMEGA_LOG_FILE=false`. The default `.gitignore` includes `logs/`.
 
@@ -131,40 +131,40 @@ omega.initialize().then(() => { const { logger, desktop } = omega; });
 
 ## Documentation
 
-Each subsystem has its own API reference under [`docs/`](docs/):
-
-- [storage](docs/storage.md) — KV store, sync in main, async (via IPC) in renderer, dot-notation paths, change broadcasts
-- [ipc](docs/ipc.md) — typed channel bus, `handle` / `invoke` / `broadcast`
-- [windows](docs/windows.md) — lazy named-window registry (no auto-create), bounds persistence, inset titlebar, hide-on-close
-- [tray](docs/tray.md) — file-based tray definition, dynamic items, runtime mutators
-- [menu](docs/menu.md) — file-based application menu, platform-aware default template
-- [context-menu](docs/context-menu.md) — file-based right-click menus, called per-event with `params`
-- [startup](docs/startup.md) — launch modes (`normal` / `hidden`), LSUIElement on macOS, login-item handling
-- [app-state](docs/app-state.md) — first-launch / launch-count / crash-sentinel flags
-- [deep-link](docs/deep-link.md) — cross-platform deep links, single-instance, pattern routing, built-in routes
-- [auth](docs/auth.md): `omega.auth`, Firebase auth state synchronized across main + every renderer
-- [auto-updater](docs/auto-updater.md) — startup + periodic checks, 30-day max-age gate, dev simulation
-- [analytics](docs/analytics.md) — GA4 Measurement Protocol with cross-platform `uuidv5` identity (same human → same `user_id` across desktop/web/backend)
-- [context](docs/context.md) — runtime info block (geolocation, client, session, app) — @omega.js/backend-shaped
-- [usage](docs/usage.md) — opens / hoursTotal / hoursThisSession; clean-exit accumulation
-- [remote-config](docs/remote-config.md) — "hot config" fetched from brand site for runtime flag flips without re-releases
-- [restart-manager](docs/restart-manager.md) — auxiliary helper app for relaunches; auto-installs via signed mac.zip / NSIS exe / browser-opened .deb
-- [config-schema](docs/config-schema.md) — canonical schema + validator for `config/omega.json5`. Hard-fails boot AND `gulp audit` on missing required fields, regex mismatches, enum violations, type mismatches. Single source of truth in the bundled `@omega.js/config`
-- [templating](docs/templating.md) — `{{ var }}` token replacement, page template, body-only views
-- [themes](docs/themes.md): classy + bootstrap themes, `@use 'omega-desktop' as * with (...)` overrides, per-page CSS bundles, system-aware appearance (`omega.theme`)
-- [sentry](docs/sentry.md) — error/crash reporting, dev-mode gating, auto auth attribution, release tagging
-- [hooks](docs/hooks.md) — lifecycle hooks (build/pre, build/post, release/pre, release/post, notarize)
-- [installer-options](docs/installer-options.md) — installer/distribution config: NSIS one-click defaults, ia32 inclusion, app.category mapping, `{YEAR}` copyright token, snap publishing (default-on with cred-gated auto-skip), MAS roadmap
-- [signing](docs/signing.md) — macOS + Windows code signing reference, cert files, env vars
-- [releasing](docs/releasing.md) — end-to-end release walkthrough (`.env` → GitHub Release)
-- [runner](docs/runner.md) — Windows EV-token signing runner — `npx omega runner start`, which onboards new GH orgs, `npx omega runner monitor` for a live signing event tail
-- [test-framework](docs/test-framework.md) — writing tests, running them, layers
-- [test-boot-layer](docs/test-boot-layer.md) — boot test layer (spawns the consumer's actual built bundle for end-to-end smoke tests)
-- [build-system](docs/build-system.md) — gulp, esbuild, electron-builder pipeline
+Each subsystem has its own API reference under [`docs/desktop/`](../../docs/desktop):
+
+- [storage](../../docs/desktop/storage.md) — KV store, sync in main, async (via IPC) in renderer, dot-notation paths, change broadcasts
+- [ipc](../../docs/desktop/ipc.md) — typed channel bus, `handle` / `invoke` / `broadcast`
+- [windows](../../docs/desktop/windows.md) — lazy named-window registry (no auto-create), bounds persistence, inset titlebar, hide-on-close
+- [tray](../../docs/desktop/tray.md) — file-based tray definition, dynamic items, runtime mutators
+- [menu](../../docs/desktop/menu.md) — file-based application menu, platform-aware default template
+- [context-menu](../../docs/desktop/context-menu.md) — file-based right-click menus, called per-event with `params`
+- [startup](../../docs/desktop/startup.md) — launch modes (`normal` / `hidden`), LSUIElement on macOS, login-item handling
+- [app-state](../../docs/desktop/app-state.md) — first-launch / launch-count / crash-sentinel flags
+- [deep-link](../../docs/desktop/deep-link.md) — cross-platform deep links, single-instance, pattern routing, built-in routes
+- [auth](../../docs/desktop/auth.md): `omega.auth`, Firebase auth state synchronized across main + every renderer
+- [auto-updater](../../docs/desktop/auto-updater.md) — startup + periodic checks, 30-day max-age gate, dev simulation
+- [analytics](../../docs/desktop/analytics.md) — GA4 Measurement Protocol with cross-platform `uuidv5` identity (same human → same `user_id` across desktop/web/backend)
+- [context](../../docs/desktop/context.md) — runtime info block (geolocation, client, session, app) — @omega.js/backend-shaped
+- [usage](../../docs/desktop/usage.md) — opens / hoursTotal / hoursThisSession; clean-exit accumulation
+- [remote-config](../../docs/desktop/remote-config.md) — "hot config" fetched from brand site for runtime flag flips without re-releases
+- [restart-manager](../../docs/desktop/restart-manager.md) — auxiliary helper app for relaunches; auto-installs via signed mac.zip / NSIS exe / browser-opened .deb
+- [config-schema](../../docs/desktop/config-schema.md) — canonical schema + validator for `config/omega.json5`. Hard-fails boot AND `gulp audit` on missing required fields, regex mismatches, enum violations, type mismatches. Single source of truth in the bundled `@omega.js/config`
+- [templating](../../docs/desktop/templating.md) — `{{ var }}` token replacement, page template, body-only views
+- [themes](../../docs/desktop/themes.md): classy + bootstrap themes, `@use 'omega-desktop' as * with (...)` overrides, per-page CSS bundles, system-aware appearance (`omega.theme`)
+- [sentry](../../docs/desktop/sentry.md) — error/crash reporting, dev-mode gating, auto auth attribution, release tagging
+- [hooks](../../docs/desktop/hooks.md) — lifecycle hooks (build/pre, build/post, release/pre, release/post, notarize)
+- [installer-options](../../docs/desktop/installer-options.md) — installer/distribution config: NSIS one-click defaults, ia32 inclusion, app.category mapping, `{YEAR}` copyright token, snap publishing (default-on with cred-gated auto-skip), MAS roadmap
+- [signing](../../docs/desktop/signing.md) — macOS + Windows code signing reference, cert files, env vars
+- [releasing](../../docs/desktop/releasing.md) — end-to-end release walkthrough (`.env` → GitHub Release)
+- [runner](../../docs/desktop/runner.md) — Windows EV-token signing runner — `npx omega runner start`, which onboards new GH orgs, `npx omega runner monitor` for a live signing event tail
+- [test-framework](../../docs/desktop/test-framework.md) — writing tests, running them, layers
+- [test-boot-layer](../../docs/desktop/test-boot-layer.md) — boot test layer (spawns the consumer's actual built bundle for end-to-end smoke tests)
+- [build-system](../../docs/desktop/build-system.md) — gulp, esbuild, electron-builder pipeline
 
 ## Status
 
-Active development on `v1`. See [`PROGRESS.md`](PROGRESS.md) for pass-by-pass progress.
+Active development on `v1`.
 
 ## License
 

package/dist/cli-run.js

@@ -9,7 +9,7 @@
 const BOOLEAN_FLAGS = [
   'extended', 'local', 'quick', 'q', 'direct', 'dry-run', 'secrets',
   'smoke', 'verify-only', 'find-window-id', 'publish', 'open', 'tail', 'f', 'strict',
-  'apply', 'major', 'force-fresh',
+  'major', 'force-fresh',
 ];
 
 async function run() {
@@ -39,3 +39,6 @@ async function run() {
 }
 
 module.exports = { run, BOOLEAN_FLAGS };
+
+// Runnable as a file: the package's own `npm test` calls it directly, never through the dispatcher
+if (require.main === module) run();

package/dist/cli.js

@@ -36,14 +36,14 @@ module.exports = createCliRouter({
   defaultCommand: 'help',
   aliases: {
     clean:            ['-c', '--clean'],
-    install:          ['-i', 'i', '--install'],
+    dev:              ['serve', 'start', '--dev'],
     version:          ['-v', '--version'],
     build:            ['-b', '--build'],
     deploy:           ['-d', '--deploy'],
     publish:          ['-p', '--publish'],
     release:          ['-r', '--release'],
     test:             ['-t', '--test'],
-    update:           ['-u', '--update', 'outdated', 'out'],
+    update:           ['-u', '--update'],
     logs:             ['--logs', 'log'],
     'validate-certs': ['certs', '--validate-certs'],
     'sign-windows':   ['--sign-windows'],

package/dist/commands/cdp/client.js

@@ -7,7 +7,7 @@
 // matcher instead of a "selected page"; the main window's document is always
 // at `dist/views/main/` (the MAIN_VIEW default matcher).
 //
-// See docs/cdp-debugging.md for the full toolkit reference.
+// See docs/desktop/cdp-debugging.md for the full toolkit reference.
 
 // The main window's view path — @omega.js/desktop's templating convention, so it holds for
 // every consumer. Subcommands that need "the app's main renderer" (status,

package/dist/commands/cdp.js

@@ -16,7 +16,7 @@
 // MANGLES quoted eval expressions (cross-env strips inner quotes), so a
 // pinned-port script must pass the port as a flag instead. Targets are
 // matched by URL substring (the main window is always `/views/main/`).
-// Full reference: docs/cdp-debugging.md.
+// Full reference: docs/desktop/cdp-debugging.md.
 
 const path = require('path');
 

package/dist/commands/clean.js

@@ -13,9 +13,8 @@ const dirs = [
 ];
 
 module.exports = async function (options) {
-  // The local scaffold (#675): the consumer `start` script is
-  // `omega clean && npm run gulp --`, and gulp itself is one of the peer
-  // deps the ensure installs — clean is the only verb that runs before it.
+  // The local scaffold: dev, build and package clean before gulp runs,
+  // and gulp itself is one of the peer deps the ensure installs.
   await ensureTarget({ log: (line) => logger.log(line), warn: (line) => logger.warn(line) });
 
   // Quick mode used to keep `dist/` so "the next gulp run is incremental" —

package/dist/commands/dev.js

@@ -0,0 +1,25 @@
+// Libraries
+const build = require('../build.js');
+const logger = build.logger('dev');
+const { runPipeline } = require('../utils/build-pipeline.js');
+
+// The local dev loop the target's `start` script runs: clean (which runs the
+// local scaffold), then the gulp default task, build then launch electron. The
+// `--` flags it was given ride to the gulp lane (`--debug`, `--remote-debugging-port=<n>`).
+function plan(options, argv = process.argv.slice(2)) {
+  return {
+    env: {},
+    steps: [
+      { type: 'clean' },
+      { type: 'gulp', task: 'default', args: argv.filter((arg) => arg.startsWith('--')) },
+    ],
+  };
+}
+
+module.exports = async function (options) {
+  logger.log('Starting the dev loop...');
+
+  await runPipeline(plan(options), options);
+};
+
+module.exports.plan = plan;

package/dist/commands/lib/ensure-target.js

@@ -20,7 +20,8 @@
  *   peer dependencies installed when missing or behind (a satisfied target
  *                     installs nothing)
  *   defaults tree     src/defaults/** — copy-if-missing, marker merges for
- *                     .env/.gitignore/AGENTS.md, workflows re-rendered
+ *                     .env/.gitignore, workflows re-rendered
+ *   AGENTS.md         standalone only, through devkit's one builder
  *   locality          a WARNING when the framework is a `file:` link
  *
  * Everything here is copy-if-missing, marker-merge or write-if-changed. What
@@ -36,6 +37,8 @@ const { ensurePeerDependencies, readProject } = require('./dependencies.js');
 const { renderSecretsBlock } = require('../../vendor/config/env-delivery.js');
 const { composeTargetWorkflows, renderInstallFirewall, renderInstallWorkspace } = require('../../vendor/devkit/ci-workflows.js');
 const { assertScaffoldable } = require('../../vendor/devkit/scaffold-guard.js');
+const { scaffoldAgentsMd } = require('../../vendor/devkit/agents-md.js');
+const { projectScripts } = require('../../vendor/devkit/verb-scripts.js');
 
 const logger = build.logger('ensure-target');
 const package = build.getPackage('main');
@@ -52,11 +55,8 @@ function setupScripts(projectDir, result) {
 
   const project = readProject(projectDir);
 
-  project.scripts = project.scripts || {};
-
-  Object.keys(package.projectScripts || {}).forEach((key) => {
-    project.scripts[key] = package.projectScripts[key];
-  });
+  // The verb table's scripts for this framework, the manifest's declarations over them
+  project.scripts = { ...project.scripts, ...projectScripts(package) };
 
   // Electron consumer projects should not be published to npm
   project.private = true;
@@ -195,18 +195,10 @@ async function copyDefaults(projectDir, engineLogger) {
       // material really lives, so a target keeps the explanation that matches
       // the ignore rules the scaffold just wrote, never an older one.
       'config/certs/README.md': { overwrite: true },
-      // The agent-docs chain (#63): AGENTS.md carries the content (marker-merged
-      // like .gitignore), CLAUDE.md is the one-line `@AGENTS.md` pointer — copied
-      // when missing by the `**/*` rule above, never clobbered.
-      'AGENTS.md': { mergeLines: true, template: templateContext },
-      // Brand doc unification (Ian 2026-07-20): inside a brand monorepo the
-      // BRAND ROOT is the one doc home — per-target AGENTS.md/CLAUDE.md/CHANGELOG.md/docs/
-      // never scaffold, and existing framework-owned-only copies are swept
-      // (retire rules; consumer content is never destroyed). Standalone projects
-      // keep them. Last-match-wins: these override the rules above.
+      // In a brand the BRAND ROOT is the one doc home: per-target CHANGELOG.md
+      // and docs/ never scaffold, and framework-owned copies are swept (consumer
+      // content is kept). Last-match-wins over the rules above.
       ...(isBrandTarget ? {
-        'AGENTS.md': { retire: true, template: templateContext },
-        'CLAUDE.md': { retire: true, template: templateContext },
         'CHANGELOG.md': { retire: true },
         'docs/**/*': { retire: true },
       } : {}),
@@ -235,6 +227,9 @@ async function copyDefaults(projectDir, engineLogger) {
     logger: engineLogger,
   });
 
+  // The project-root AGENTS.md, through devkit's one builder.
+  scaffoldAgentsMd({ outputDir: projectDir, standalone: seed.standalone, result: applied, logger: engineLogger });
+
   if (isBrandTarget) {
     // The same templateContext the yml rule uses, so the composed copy carries
     // the generated `githubSecrets` block — a composed workflow with the raw

package/dist/commands/lib/migrate.js

@@ -0,0 +1,17 @@
+/**
+ * migrateTarget: the desktop leg of the brand root's `omega migrate`. No
+ * legacy electron-manager shape converts mechanically yet (the register's
+ * by-hand steps cover them), so it answers the shared shape with nothing due.
+ * Every framework exposes this entry, so the manager's walk never special-cases
+ * a framework name.
+ *
+ * @param {string} targetDir - the desktop target's root
+ * @param {object} [options]
+ * @param {boolean} [options.execute] - convert (default: report only)
+ * @returns {{ due: string[], changed: string[], errors: string[] }}
+ */
+function migrateTarget(targetDir, options = {}) {
+  return { due: [], changed: [], errors: [] };
+}
+
+module.exports = { migrateTarget };

package/dist/commands/logs.js

@@ -3,7 +3,7 @@
 //
 // The optional positional names the surface (default `runtime`) and resolves to
 // <projectRoot>/logs/<surface>.log — the same four files documented in
-// docs/logging.md. Every flag below works on whichever surface was named.
+// docs/desktop/logging.md. Every flag below works on whichever surface was named.
 //
 // `runtime` resolves to the file the runtime logger writes to:
 //   - Dev (running from a project directory): <projectRoot>/logs/runtime.log

package/dist/commands/release.js

@@ -2,7 +2,7 @@
 // run it started.
 //
 // Replaces the old "do it from my laptop" release flow with "let CI do it, but make it
-// feel local." User runs `npm run release` (or `npx omega release`) and gets:
+// feel local." User runs `npx omega release` and gets:
 //   1. The ONE deploy lane every target takes (`@omega.js/devkit/deploy`'s
 //      deployViaDispatch, #872, #915): the composed workflow files reach the
 //      default branch when they differ there (GitHub registers a workflow from

package/dist/commands/test.js

@@ -21,7 +21,7 @@ module.exports = async function (options) {
 
   // Tee all test output to <projectRoot>/logs/test.log (ANSI-stripped) — mirrors
   // @omega.js/backend's test.log and @omega.js/desktop's own dev.log pattern.
-  attachLogFile(path.join(process.cwd(), 'logs', 'test.log'));
+  const detachLog = attachLogFile(path.join(process.cwd(), 'logs', 'test.log'));
 
   // The local half of the retired `omega setup` (#675) — idempotent, offline,
   // and quiet on a converged target. The gulp verbs get it from the `defaults`
@@ -104,19 +104,19 @@ module.exports = async function (options) {
     // ONE target to every target, so a distinct code lets it count this as a
     // miss rather than a failure (#814).
     process.exitCode = noMatchExitCode();
-    await attachLogFile.detach();
+    detachLog();
     return;
   }
 
   if (result.failed > 0) {
     process.exitCode = 1;
-    await attachLogFile.detach();
+    detachLog();
     throw new Error(`${result.failed} test(s) failed`);
   }
 
   // Close test.log before exiting. Nothing to flush: every write already went
   // to the fd synchronously (#197), so the Results block survives the exit
   // below whatever happens — detach() just closes the handle.
-  await attachLogFile.detach();
+  detachLog();
   process.exit(0);
 };

package/dist/commands/update.js

@@ -1,9 +1,10 @@
 /**
- * `omega update` — dependency freshness report (npu-outdated semantics):
+ * `omega update` — dependency freshness (npu-outdated semantics):
  * installed/wanted/latest + patch/minor/major per dep, releases younger than
- * --min-age days (default 7) QUARANTINED. `--apply` installs the
+ * --min-age days (default 7) QUARANTINED. A bare run installs the
  * non-quarantined, non-breaking set (`--major` opts into breaking) through
- * npu when present. The whole verb is the shared devkit implementation.
+ * npu when present; `--dry-run` reports and installs nothing. The whole verb
+ * is the shared devkit implementation.
  */
 const build = require('../build.js');
 const logger = build.logger('update');
@@ -12,7 +13,7 @@ const { runUpdate } = require('../vendor/devkit/update.js');
 module.exports = async function (options) {
   await runUpdate({
     dir: process.cwd(),
-    apply: options.apply,
+    dryRun: options.dryRun || options['dry-run'],
     major: options.major,
     minAge: options.minAge ?? options['min-age'],
     forceFresh: options.forceFresh || options['force-fresh'],

package/dist/defaults/.github/workflows/build.yml

@@ -27,7 +27,7 @@ env:
   # `KEY: ${{ secrets.KEY }}` line per `delivery: { desktop: 'ci' | 'bake' }`
   # entry (@omega.js/config's env-delivery.js), re-rendered by every verb's
   # ensureTarget. Signing, notarization, store and analytics credentials all
-  # arrive here, workflow-wide — the jobs and steps below consume them without
+  # arrive here, workflow-wide: the jobs and steps below consume them without
   # restating one. Add a key to the schema, not to this file.
   {{ githubSecrets }}
 
@@ -103,7 +103,7 @@ jobs:
 
       {{ installFirewall }}
 
-      # On Windows, force cmd for every shell step in this job — the runner's default
+      # On Windows, force cmd for every shell step in this job: the runner's default
       # is PowerShell 7 which has its own ExecutionPolicy/wrapping quirks that cause
       # `npm ci` and similar to exit silently with no captured output. cmd has none
       # of that. mac/linux use their default bash regardless of this flag (per
@@ -135,7 +135,7 @@ jobs:
           echo "NPM: $(npm -v)"
           echo "Omega: $(node "${{ github.workspace }}/node_modules/@omega.js/desktop/bin/omega" version)"
 
-      # macOS — decode signing assets from secrets, then sign + notarize + publish.
+      # macOS: decode signing assets from secrets, then sign + notarize + publish.
       # `npx omega deploy`'s precheck uploads .p12 / .p8 files as base64-encoded secrets;
       # the workflow decodes them back to disk for electron-builder + notarytool to read.
       # Each decode is gated on its secret EXISTING (#872): `base64 --decode` of an
@@ -150,13 +150,13 @@ jobs:
           if [ -n "${{ secrets.CSC_LINK }}" ]; then
             echo "${{ secrets.CSC_LINK }}" | base64 --decode > config/certs/dev-id.p12
           else
-            echo "No CSC_LINK secret: run omega deploy from targets/desktop (its precheck pushes them). A mac build must be signed."
+            echo "No CSC_LINK secret: run omega deploy at the brand root (its precheck pushes them). A mac build must be signed."
             exit 1
           fi
           if [ -n "${{ secrets.APPLE_API_KEY }}" ]; then
             echo "${{ secrets.APPLE_API_KEY }}" | base64 --decode > config/certs/AuthKey.p8
           else
-            echo "No APPLE_API_KEY secret: run omega deploy from targets/desktop (its precheck pushes them). A mac build must be notarized."
+            echo "No APPLE_API_KEY secret: run omega deploy at the brand root (its precheck pushes them). A mac build must be notarized."
             exit 1
           fi
       # The two file-path OVERRIDES of the workflow env: electron-builder and
@@ -176,7 +176,7 @@ jobs:
       # Linux: install snapcraft when (a) the brand still SHIPS the snap format
       # (`platforms.linux.formats.snap`, on unless dropped with `false`) AND
       # (b) SNAPCRAFT_STORE_CREDENTIALS is set as a repo secret. Without the secret we
-      # skip snapcraft install entirely — build-config.js auto-skips the snap target on
+      # skip snapcraft install entirely: build-config.js auto-skips the snap target on
       # the same condition, so the build still produces .deb + .AppImage cleanly with
       # no snap publish attempt and no failure.
       - name: Install Snapcraft (Linux, when snap enabled + creds present)
@@ -192,7 +192,7 @@ jobs:
             CONFIG_OK=0
             echo "platforms.linux.formats.snap is dropped, skipping snapcraft install."
           fi
-          # (b) Credentials check — empty secret means no publish creds available.
+          # (b) Credentials check: empty secret means no publish creds available.
           if [ -n "$SNAPCRAFT_STORE_CREDENTIALS" ]; then
             CREDS_OK=1
           else
@@ -204,7 +204,7 @@ jobs:
             echo "Snapcraft installed."
           fi
 
-      # Linux — no signing. The workflow env carries the mac credentials as the
+      # Linux: no signing. The workflow env carries the mac credentials as the
       # base64 secrets themselves (only the mac job decodes them to disk), and a
       # leg that never signs for mac has no business holding them: empty reads as
       # UNSET after the build's sanitize pass (#872).
@@ -215,18 +215,18 @@ jobs:
           APPLE_API_KEY: ''
         run: npm run release:local
 
-      # Windows — package (build + electron-builder package) unsigned. We do NOT publish
+      # Windows: package (build + electron-builder package) unsigned. We do NOT publish
       # here. Mac/linux's `npm run release:local` step already created the GH Release via
       # electron-builder publish; windows-sign uploads signed .exe to that same release.
-      # shell: cmd as above — PowerShell 7's wrapping breaks long-running npm scripts.
+      # shell: cmd as above. PowerShell 7's wrapping breaks long-running npm scripts.
       - if: matrix.os == 'windows-latest'
         shell: cmd
         env:
           OMEGA_SKIP_WIN_SIGN: 'true'
           # The workflow env carries the mac signing cert (CSC_LINK is the
           # base64 .p12 the mac job decodes); electron-builder would otherwise
-          # try to sign the Windows build with it. Empty reads as UNSET — the
-          # build's sanitize pass drops it — so this step packages unsigned, as
+          # try to sign the Windows build with it. Empty reads as UNSET (the
+          # build's sanitize pass drops it), so this step packages unsigned, as
           # it always did. windows-sign signs separately.
           CSC_LINK: ''
           CSC_KEY_PASSWORD: ''
@@ -276,9 +276,9 @@ jobs:
     name: Sign Windows
     needs: [setup, build, windows-strategy]
     # Strategy comes from config platforms.windows.signing.strategy (read by windows-strategy job).
-    #   self-hosted (default) — runs on a self-hosted runner with EV USB token attached
-    #   cloud                 — runs on hosted windows-latest, calls cloud signing provider
-    #   local                 — skip this job; sign locally via `npx omega sign-windows`
+    #   self-hosted (default):  runs on a self-hosted runner with EV USB token attached
+    #   cloud:                  runs on hosted windows-latest, calls cloud signing provider
+    #   local:                  skip this job; sign locally via `npx omega sign-windows`
     # The trigger half of the signer guard (#875): only a DISPATCH may reach the
     # box that holds the EV token, so a `pull_request` or `push` trigger added to
     # this file later skips the sign job instead of signing a stray build. A skip,
@@ -298,7 +298,7 @@ jobs:
     defaults:
       run:
         shell: cmd
-    # Signing credentials — self-hosted EV USB token (WIN_EV_TOKEN_PATH,
+    # Signing credentials: self-hosted EV USB token (WIN_EV_TOKEN_PATH,
     # WIN_CSC_KEY_PASSWORD, SIGNTOOL_PATH) and the cloud providers (only the set
     # `platforms.windows.signing.cloud.provider` names is consumed), all arrive
     # through the workflow's generated env block. Set them in the brand .env and
@@ -348,11 +348,11 @@ jobs:
       {{ installFirewall }}
       - run: sfw npm ci {{ installWorkspace }}
       # Flip the releases-repo release from Draft to Published so electron-updater
-      # can read it. Idempotent — safe to run even if already published. ONLY runs
+      # can read it. Idempotent: safe to run even if already published. ONLY runs
       # on all-platforms builds: a partial run (e.g. `--platforms windows`) leaves
       # the release as a draft, so subsequent runs can fill in the missing platform
       # assets before electron-updater starts seeing the version.
       - if: needs.setup.outputs.mac == 'true' && needs.setup.outputs.linux == 'true' && needs.setup.outputs.windows == 'true'
         run: node "${{ github.workspace }}/node_modules/@omega.js/desktop/bin/omega" finalize-release --publish
       - if: needs.setup.outputs.mac != 'true' || needs.setup.outputs.linux != 'true' || needs.setup.outputs.windows != 'true'
-        run: echo "Partial-platform run (mac=${{ needs.setup.outputs.mac }} linux=${{ needs.setup.outputs.linux }} windows=${{ needs.setup.outputs.windows }}) — leaving release as draft. Run with --platforms all to publish."
+        run: echo "Partial-platform run (mac=${{ needs.setup.outputs.mac }} linux=${{ needs.setup.outputs.linux }} windows=${{ needs.setup.outputs.windows }}), leaving release as draft. Run with --platforms all to publish."

package/dist/defaults/_.gitignore

@@ -22,5 +22,3 @@ config/certs/*
 *.pem
 
 # ========== Custom Values ==========
-
-# Add your own ignores below. This section is preserved across framework re-syncs.

package/dist/defaults/_mas/README.md

@@ -1,4 +1,4 @@
-# MAS (Mac App Store) Reference Plists — ARCHIVED
+# 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
@@ -24,7 +24,7 @@ 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
+`config.targets.mac.mas`, see `node_modules/@omega.js/manager/docs/desktop/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`,
@@ -42,7 +42,7 @@ The other MAS-specific concerns:
 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
+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

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

@@ -37,4 +37,4 @@ These are values, not files, and live in the brand `.env` (never here):
 
 Windows keeps no file here at all: the self-hosted EV USB token is addressed by `WIN_EV_TOKEN_PATH` / `WIN_CSC_KEY_PASSWORD`, and each cloud provider by its own env set.
 
-For the whole picture see [`docs/signing.md`](../../docs/signing.md).
+For the whole picture see `node_modules/@omega.js/manager/docs/desktop/signing.md`.