@omega.js/desktop 0.50.0 → 0.51.0

package/docs/index.md

@@ -30,7 +30,7 @@ OMEGA Desktop (@omega.js/desktop) is a comprehensive framework for building mode
 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.
+6. `npm run package`: full local production package, of whatever the `platforms` declaration says the brand ships (by default DMG/zip on mac, NSIS on windows, deb+AppImage+snap on 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/`)
@@ -108,37 +108,74 @@ All three ship sensible default templates and share a unified id-path API (`.fin
 
 ### 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).
+Convention-only. Drop PNGs at `config/icons/<platform>/<slot>.png` (`mac`, `windows`, `linux`: the one vocabulary, #867) 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).
+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]`. An ESM-only dependency bundles into main and preload like any other: both are CommonJS output, where the wrapper keeps `import.meta.url` answering ([#906](https://github.com/Omega-JS-Stack/omega/issues/906)), so a package that opens a require of its own with `createRequire(import.meta.url)` runs bundled instead of throwing at boot. `gulp/build-config` generates `dist/electron-builder.yml` + `dist/config/entitlements.mac.plist` from @omega.js/desktop defaults + consumer config. What the app SHIPS is one declaration, `platforms.<mac|windows|linux>.formats.<dmg|nsis|deb|appimage|snap>` ([#867](https://github.com/Omega-JS-Stack/omega/issues/867)): presence = enabled, every format defaults on, `false` drops one, and the electron-builder target lists derive from it. Artifact names carry NO version (`<Product>-mac-dmg.dmg`) and come from @omega.js/config's `platforms.js`: the ONE table the website's `/download/<platform>/<format>` 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. The `.deb` target's two required metadata facts come from the BRAND ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)): `linux.maintainer` from `brand.name` plus `brand.contact.email`, and the homepage from `brand.url` through `extraMetadata` (electron-builder reads it off the app manifest, never off its own config); a brand missing either fails at config generation, naming the key, instead of at package time after the AppImage has already uploaded. Strategy-pluggable Windows signing (`platforms.windows.signing.strategy`: `self-hosted` | `cloud` | `local`), whose value is also what the env schema gates each signing credential on, so the walk asks for one strategy's set and no other's. See [docs/releasing.md](../docs/releasing.md) for the whole release contract (one public repo, always `<brand.id>-releases`, 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 ACCENT comes from the config, not from a literal a consumer keeps in sync
+([#912](https://github.com/Omega-JS-Stack/omega/issues/912)): `gulp/sass` renders
+`dist/assets/scss/_brand.scss` from `brand.color` before every compile, carrying
+`$primary` (what Bootstrap's color ramp derives from) plus a `ramp` mixin of the
+runtime `--omega-accent` family, and the scaffold's `main.scss` reads both,
+`@use 'brand';` above the framework import and `@include brand.ramp;` below it
+(below, because a used module's css emits at its load position, ahead of the
+token sheet the ramp has to beat). A deliberate divergence puts a literal back in
+place of `brand.$primary`. Same renderer @omega.js/extension writes and the same
+ramp web inlines into its `<head>`: [shared/theming.md](shared/theming.md).
 
-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.
+### Signing material is READ IN PLACE, and the paths derive ONCE ([#891](https://github.com/Omega-JS-Stack/omega/issues/891))
 
-`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.
+Nothing copies signing material into a target. The signing tree is read where it lives, in TWO tiers ([#892](https://github.com/Omega-JS-Stack/omega/issues/892), `@omega.js/devkit/signing-tree`): the COMPANY's `<company tree>/.omega/certificates/apple/` first when the brand names one with `company: { id }` and that company is on this machine ([#677](https://github.com/Omega-JS-Stack/omega/issues/677)), the brand's own second, so a brand of a company signs with the company's material and falls back to its own only for a file the company tree does not hold. The manager's disperse `certs` operation, devkit's `deliverCerts()` and desktop's `deliver-certs.js` are all gone with the copy: one fact, one home, and no dispersed duplicate a build could silently sign with after the tree moved on.
+
+`CSC_LINK` and `APPLE_API_KEY` DERIVE from that tree, ONCE, at the desktop env load ([src/utils/load-env.js](../src/utils/load-env.js), over `@omega.js/devkit/signing-env`), which both boots call: the CLI (`src/cli.js`) and gulp (`src/gulp/main.js`, its own process under `npm start`). `CSC_LINK` takes the tree's `certificates/DEVELOPER_ID_APPLICATION_G2.p12` when `CSC_KEY_PASSWORD` OPENS it, `APPLE_API_KEY` takes its `AuthKey_<APPLE_API_KEY_ID>.p8`, and both are ABSOLUTE paths. An explicit env value always wins, a file that exists and cannot be used prints one line and leaves the key unset (electron-builder's Keychain discovery stays the default), and no provisioning profile derives at all: Developer ID is direct distribution and needs none. The build, `validate-certs` and the deploy precheck's secret publish then READ that one answer, which is what ended the split where the build signed fine and `validate-certs` stopped the deploy on `Found .p12 in config/certs/ but CSC_LINK env var is not set`.
+
+`CSC_LINK` and `APPLE_API_KEY` each take three shapes, a path, an https URL, or the file itself as inline base64, and the `validate-certs` precheck reports the non-file shapes instead of statting them ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)). ON THE RUNNER the target's `config/certs/` is still the decode target: the generated `build.yml` writes the pushed base64 secrets back to disk there and points both keys at the files. It decodes each mac secret only when that secret EXISTS, and a MISSING one exits 1 naming `omega deploy` (whose precheck pushes them): a mac build `omega deploy` ships is always signed and notarized, so the leg stops instead of publishing an unsigned app. The linux and windows legs blank both keys outright, and their `validate-certs` run skips the mac rungs entirely with one line ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)), because no leg but the mac one signs for mac: rungs about credentials that leg deliberately blanked are two warnings nobody can act on.
+
+**Signing, and then the PROOF** ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)). Every rung of the mac lane fails loudly, and the last two prove their work instead of assuming it:
+
+| Rung | What it refuses to pass |
+|---|---|
+| `validate-certs` (deploy precheck, and inside `publish`) | STRICT on macOS: an unset `CSC_LINK` or `APPLE_API_KEY` (which means the signing TREE holds no such file, and the line names both tier paths it looked in), a `CSC_LINK` pointing at a missing file, no `CSC_KEY_PASSWORD`, a `.p12` the password will not open, no Keychain `Developer ID Application` identity on a run whose `CSC_LINK` names no certificate (electron-builder imports a `CSC_LINK` `.p12` into its OWN temporary keychain, so the login keychain is only asked when discovery is what will sign), or an EXPIRED certificate. Under 30 days is a warning: it still signs. The unsigned findings are ERRORS only when the config declares `certificates.providers.apple`, the same gate the env schema's `requiredWhen` uses |
+| `push-secrets` (the precheck step, never a verb) | A signing key the schema marks required for this brand (the mac set once `certificates.providers.apple` is declared) that the `.env` cascade resolves EMPTY stops the deploy listing every one, and publishes NOTHING: the step is `fatal` on all four frameworks. `CSC_LINK` and `APPLE_API_KEY` are DERIVED from the signing tree first, so the refusal means the artifact is missing, and its line names both tier paths plus `omega manage --service certificates` rather than a path to paste |
+| `afterSign` hook ([src/hooks/notarize.js](../src/hooks/notarize.js)) | A non-darwin build is the ONE skip. Missing `APPLE_API_*` THROWS; an app whose `codesign -dv` report carries no `Developer ID Application` authority THROWS (notarytool rejects the ad-hoc signature an identity-less build leaves behind). After notarizing it runs `xcrun stapler staple`, then PROVES it with `xcrun stapler validate` and `spctl --assess --type execute -vv`, and throws unless both accept |
+| `artifactBuildCompleted` hook ([src/hooks/notarize-artifacts.js](../src/hooks/notarize-artifacts.js)) | Each `.dmg`, BEFORE electron-builder uploads it (this hook is awaited before the `artifactCreated` the publisher listens on; `afterAllArtifactBuild` fires after every upload is queued, and run 34738410986 published an unstapled image from there): `xcrun notarytool submit --wait` with the same API key triple, `stapler staple`, `stapler validate`, `spctl --assess --type open --context context:primary-signature -vv`. The ticket stapled to the app INSIDE an image is not stapled to the image, and a user's Mac assesses the image first, by the image's OWN signature: the generated config sets electron-builder's `dmg.sign`, so the image carries the Developer ID signature that assessment reads (an unsigned image is refused after a clean notarize and staple) |
+
+Both hooks run every command through one small runner (`src/hooks/lib/notarize-tools.js`) that a test replaces with a fake `xcrun`/`spctl`, and each one reads the tool's own report, stdout and stderr whatever the exit code: anything but the words that mean success throws with the tool's own verdict in the message, so the release step never runs on an artifact Gatekeeper would refuse.
 
 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.
+`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` ← `<certificates.providers.apple.bundleIdPrefix>.<brand.id>` with the brand id's dashes as dots, the very id the certificates service registers ([#909](https://github.com/Omega-JS-Stack/omega/issues/909); no prefix declared, and it falls back to the reverse-domain of `brand.url`, then `app.<brand.id>`), `app.productName` ← `brand.name`) → injected into the NODE bundles (main, preload) at build time as an esbuild `define` of `OMEGA_BUILD_JSON` plus a banner that assigns the same literal to `globalThis`, and written for the RENDERER as the ONE `dist/build.js` every view's shell loads with its first script tag ([#743](https://github.com/Omega-JS-Stack/omega/issues/743), the same file and the same load order web and the extension use). Runtime reads `OMEGA_BUILD_JSON.config` first (authoritative in packaged apps); dev falls back to resolving from disk.
+
+The wrapper is the ONE shape every OMEGA browser surface bakes ([#894](https://github.com/Omega-JS-Stack/omega/issues/894)): `{ config, package, mode, license, builtAt }`, with the build's own facts outside `config` and never part of the client contract. What goes INSIDE `config` differs by who reads the bundle:
+
+| Bundle | `config` |
+|---|---|
+| main, preload | the WHOLE resolved config, as a `define` + banner in their own bundles. The main process BOOTS from it (a packaged app's `config/omega.json5` is inside the asar), so `platforms`, `startup`, `autoUpdate`, `releases` and the rest have to be there. Both are Node, neither is a public surface |
+| renderer | the browser subset, `clientConfig(resolved)` from `@omega.js/config` (the config guide's "The browser subset"), written to `dist/build.js` and loaded by the page template as `../../build.js` ahead of the view's own bundle. A renderer is a public surface: its bundle is readable from DevTools, so the GCP account facts, the signing certificates and the account admins are not in it, and the bundle itself carries no copy of the snapshot at all |
+
+The build facts include `runtime: 'electron'` ([#896](https://github.com/Omega-JS-Stack/omega/issues/896)): a packaged renderer is a browser with no Electron globals of its own, so @omega.js/client's sniff would answer `'web'` without the baked fact. `mode` is the three keys every surface records, `{ environment, build, publish }`; desktop's own `server` verdict stays inside `Manager.getMode()`.
+
+Both halves carry the same name, so `renderer.js` hands `OMEGA_BUILD_JSON.config` to `@omega.js/client` exactly as an extension page and a web page do.
 
 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).
+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). The audit reports the validator's WARNINGS too ([#911](https://github.com/Omega-JS-Stack/omega/issues/911)): `omega build` prints each one and counts it (`audit ok (1 warning)`), so a key the schema does not declare, which is exactly what a typo looks like, is seen at build time instead of dropped. 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).
+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), and the three `is*()` checks DERIVE from it; gate side effects on the INTENTIONAL check (`isProduction()` for prod-only, `isDevelopment() || isTesting()` for local-or-test); never `!isDevelopment()`.
+
+**The environment four are `@omega.js/config`'s ONE module** ([#817](https://github.com/Omega-JS-Stack/omega/issues/817), the contract in full: [docs/shared/config.md](shared/config.md)): `src/utils/mode-helpers.js` re-exports them beside desktop's own `getVersion()`, so all four frameworks hang the identical functions. They read ONE input and never guess: `OMEGA_ENVIRONMENT` in Node, and the baked `OMEGA_BUILD_JSON.config.environment` in a renderer (which has none). Nothing sniffs `app.isPackaged` or `NODE_ENV` any more, and a context with neither input throws by name rather than defaulting; the old default here was `production`, so a plain `npm start` bundled itself as a production artifact while @omega.js/extension's copy of the same function answered `development`. `src/build.js` names the input at load, from the lane (`OMEGA_BUILD_MODE` is production and wins over an inherited value; the test runners name `testing`; a bare dev boot is `development`), and `main.js` names it from the baked config for a packaged app that has no parent lane: a FALLBACK for the context with no input, never an override of a lane that named one ([#925](https://github.com/Omega-JS-Stack/omega/issues/925)). A renderer has no `process` either, so the preload hands it the running word on `window.desktop.environment` and the renderer bootstrap applies it over the bake, which is how a test lane booting a production artifact answers `testing` in every context of that app. 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).
+`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/playground-omega/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)). A test run never touches the OS keychain (auth persistence is `none` on every layer, whatever the brand declares) and a boot that produces no harness output inside the budget fails with the last `runtime.log` line instead of hanging the runner ([#907](https://github.com/Omega-JS-Stack/omega/issues/907)). See [docs/test-framework.md](../docs/test-framework.md), [docs/test-boot-layer.md](../docs/test-boot-layer.md).
 
 ### Test coverage
 
@@ -146,7 +183,7 @@ Every feature ships with tests at EVERY layer it has a surface in — logic (`bu
 
 ### 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).
+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 `omega deploy` (with `npm run release`, the dispatch it delegates to) streams the GH Actions run to `logs/deploy.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)
 
@@ -163,14 +200,13 @@ Every gulp invocation tees stdout+stderr to `<projectRoot>/logs/dev.log` on `npm
 | `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 |
+| `deploy` | the deliberate-deploy verb (see docs/shared/deploys.md in the Omega repo): dispatch the composed `build.yml`, or with `--direct` run `omega publish --local` right here for the HOST platform, pinned by test to CI's own `release:local` step ([#865](https://github.com/Omega-JS-Stack/omega/issues/865)). A `--platforms` value the host cannot build refuses under `--direct`, because a cross-platform build is CI-only ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)). A DISPATCH runs the NETWORK prechecks first: framework freshness, `validate-certs`, repo provisioning, the secrets push, the two SIGNING ones fatal ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)); `--no-secrets` skips them all, and `--direct` never reaches them (a local deploy publishes no signing certs to the repo, #872). `--dry-run` RUNS the precheck too and sends nothing: the plan names the secret keys it would publish ([#895](https://github.com/Omega-JS-Stack/omega/issues/895)). |
 | `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 |
+| `build` | clean + `gulp build`, with `OMEGA_BUILD_MODE=true` set in-process |
+| `package` | clean + the electron-builder package (`--quick` for host platform/arch only) |
+| `publish` | ship-credential check + `validate-certs` (strict) + full sign + notarize + GH release upload (`OMEGA_IS_PUBLISH=true`); `--local` cleans first |
+| `validate-certs` | check the derived signing env, the cert file and its expiry, the notarization key, the Keychain identity. The mac rungs run on the mac leg only (#891). 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` |
@@ -179,7 +215,9 @@ Every gulp invocation tees stdout+stderr to `<projectRoot>/logs/dev.log` on `npm
 
 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.
+**A publish refuses a declared format it has no credential for, before it builds** ([#867](https://github.com/Omega-JS-Stack/omega/issues/867)). `omega publish` (which CI runs too, as `npm run release:local`) opens with a `ship-keys` step: the brand's declaration says what ships, @omega.js/config's format table says what each format needs, and anything empty stops the verb in a second instead of after a build. The wording is the extension publish's, to the letter (both read devkit's `ship-plan`): the key, the declaration that requires it (`platforms.linux.formats.snap`), and the ONE walk that collects it, `omega manage --service publishing`. What is OWED is gated by the brand's own config, so a brand that never mentions the snap is never refused for `SNAPCRAFT_STORE_CREDENTIALS`, and the Windows set narrows to the configured `platforms.windows.signing.strategy`. A BUILD keeps its clean skip (`build-config` drops the snap target when the login is absent): a build puts nothing in front of users. Every `asset` format rides the releases repo; the snap is the one desktop `store` format, and the Snap Store registers its name with the same credentials that publish, so desktop has no listing id to collect and no manual step to print.
+
+**The release verbs read the repo from CONFIG** ([#799](https://github.com/Omega-JS-Stack/omega/issues/799), [#883](https://github.com/Omega-JS-Stack/omega/issues/883)): `release` and `deploy` dispatch on the brand's SOURCE repo (`@omega.js/config`'s `sourceRepo`: `<brand.id>-omega` under `repo.org`), and `finalize-release`, the deploy precheck's provisioning and the electron-builder publish block all address the brand's ONE public releases repo (`releasesRepo`: always `<brand.id>-releases` under that same org, since `targets.desktop.releases.owner/repo` are retired and `releases: {}` is a presence switch alone). The precheck creates it public, with a first commit, through the ONE repo helper every OMEGA lane uses (`@omega.js/devkit/github-repo`'s `ensureRepo`). 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.
 
@@ -194,14 +232,14 @@ See [docs/releasing.md](../docs/releasing.md) for the end-to-end flow.
 
 ## 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 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` 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.
+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 get the firewall from Socket's own GitHub Action (`SocketDev/action`, firewall mode, pinned; it downloads the binary with the job's token and caches it, so a hosted runner's shared anonymous API quota never fails the step, [#871](https://github.com/Omega-JS-Stack/omega/issues/871)) and run `sfw npm ci`. The template carries only the `{{ installFirewall }}` token; the composer renders the step, once, from devkit's one pinned constant ([#872](https://github.com/Omega-JS-Stack/omega/issues/872)). It renders a Windows shim beside it, because the windows legs of the build force `shell: cmd` and cmd cannot execute the extension-less `sfw` the action caches ([docs/shared/deploys.md](shared/deploys.md)). 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
 
@@ -215,7 +253,7 @@ All `npm install` calls in CLI commands (`npx omega i`, `npx omega runner`, the
 - **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.
+- **`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). `src/cli-run.js` (the bin body every `bin/omega` invocation and every cross-framework dispatch runs) and `src/gulp/main.js` both `delete process.env.ELECTRON_RUN_AS_NODE` at the top.
 
 ## Doc-update parity
 
@@ -260,14 +298,14 @@ API references for each subsystem live in `docs/`. **Whenever you make a behavio
 - [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/hooks.md](../docs/hooks.md): lifecycle hooks (build/pre, build/post, release/pre, release/post, notarize/post, deploy/pre)
 - [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/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)). The same install writes the box's JOB GUARD ([#875](https://github.com/Omega-JS-Stack/omega/issues/875)): a job-started hook beside the runner, pointed at through each registration's `ACTIONS_RUNNER_HOOK_JOB_STARTED`, that fails any job whose event is not a dispatch or whose repository or actor is not on the box's own allow lists
 - [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

package/docs/installer-options.md

@@ -38,16 +38,16 @@ These apply identically on every OS — set them once.
 
 If you need a per-platform value not in the table, use the raw `electronBuilder.mac.category` / `electronBuilder.linux.category` override.
 
-## Windows (`platforms.win.*`)
+## Windows (`platforms.windows.*`)
 
 | Field | Default | What it does |
 |---|---|---|
-| `platforms.win.arch` | `['x64', 'ia32']` | Architectures. Single multi-arch NSIS installer ships both. |
-| `platforms.win.oneClick` | `true` | Slack-style: no installer wizard, just installs immediately to `%LocalAppData%\Programs\<App>`. Set to `false` for a standard "Next, Next, Finish" wizard. |
-| `platforms.win.desktopShortcut` | `true` | Create desktop shortcut. |
-| `platforms.win.startMenuShortcut` | `true` | Create Start menu entry. |
-| `platforms.win.runAfterFinish` | `true` | Auto-launch the app when the install completes. |
-| `platforms.win.perMachine` | `false` | Install for current user. Set `true` to install for all users (requires UAC elevation; **incompatible with `oneClick: true`**). |
+| `platforms.windows.arch` | `['x64', 'ia32']` | Architectures. Single multi-arch NSIS installer ships both. |
+| `platforms.windows.oneClick` | `true` | Slack-style: no installer wizard, just installs immediately to `%LocalAppData%\Programs\<App>`. Set to `false` for a standard "Next, Next, Finish" wizard. |
+| `platforms.windows.desktopShortcut` | `true` | Create desktop shortcut. |
+| `platforms.windows.startMenuShortcut` | `true` | Create Start menu entry. |
+| `platforms.windows.runAfterFinish` | `true` | Auto-launch the app when the install completes. |
+| `platforms.windows.perMachine` | `false` | Install for current user. Set `true` to install for all users (requires UAC elevation; **incompatible with `oneClick: true`**). |
 
 ### Why `oneClick: true` by default
 
@@ -61,7 +61,7 @@ If your app needs enterprise deployment, set `oneClick: false` to opt into the w
 
 ### `ia32` (32-bit Windows)
 
-@omega.js/desktop ships `ia32` alongside `x64` in a single multi-arch installer. Real-world 32-bit Windows usage is <3%, but the cost of including it is just ~2x installer size + ~2x signing time — no separate code path. Worth keeping for the long-tail user on an old Win 10 machine. To drop, set `platforms.win.arch: ['x64']`.
+@omega.js/desktop ships `ia32` alongside `x64` in a single multi-arch installer. Real-world 32-bit Windows usage is <3%, but the cost of including it is just ~2x installer size + ~2x signing time, no separate code path. Worth keeping for the long-tail user on an old Win 10 machine. To drop, set `platforms.windows.arch: ['x64']`.
 
 ## macOS (`platforms.mac.*`)
 
@@ -87,32 +87,35 @@ Reference plists from a working MAS-published Electron app (Slapform) are archiv
 | Field | Default | What it does |
 |---|---|---|
 | `platforms.linux.arch` | `['x64']` | Architectures. ia32 is essentially extinct on modern Linux. |
-| `platforms.linux.snap.enabled` | `true` (in scaffold) | Snap Store publishing. @omega.js/desktop scaffold ships this `true`; programmatic callers without the field default to OFF. Auto-skipped if `SNAPCRAFT_STORE_CREDENTIALS` env is unset. |
-| `platforms.linux.snap.confinement` | `'strict'` | `strict` (sandboxed) or `classic` (unrestricted, requires Snap Store approval). |
-| `platforms.linux.snap.grade` | `'stable'` | `stable` or `devel`. |
-| `platforms.linux.snap.autoStart` | `true` | Register the snap to auto-start on login. |
-| `platforms.linux.snap.channels` | `['stable']` | Snap Store channels to publish to. |
+| `platforms.linux.formats.deb` | on | The Debian package. `false` drops it. |
+| `platforms.linux.formats.appimage` | on | The AppImage. `false` drops it. |
+| `platforms.linux.formats.snap` | on | Snap Store publishing. Presence is the switch ([#867](https://github.com/Omega-JS-Stack/omega/issues/867)): `false` drops it, and a BUILD auto-skips it when `SNAPCRAFT_STORE_CREDENTIALS` is unset. A publish refuses instead when the brand WROTE the format down. |
+| `platforms.linux.formats.snap.confinement` | `'strict'` | `strict` (sandboxed) or `classic` (unrestricted, requires Snap Store approval). |
+| `platforms.linux.formats.snap.grade` | `'stable'` | `stable` or `devel`. |
+| `platforms.linux.formats.snap.autoStart` | `true` | Register the snap to auto-start on login. |
+| `platforms.linux.formats.snap.channels` | `['stable']` | Snap Store channels to publish to. |
 
 ### Snap Store publishing
 
-Tri-state behavior:
+Behavior, since the snap became a declared FORMAT (#867):
 
-- **Field missing entirely** → off. `build-config.js` checks `=== true` strictly, so older configs / programmatic callers without the field don't suddenly emit a snap target.
-- **`enabled: true` (scaffold default) + no `SNAPCRAFT_STORE_CREDENTIALS`** → off, with a build-time log line: `Snap target enabled in config but SNAPCRAFT_STORE_CREDENTIALS not set — skipping snap target.` This means a fresh `mgr setup` produces a working `.deb + .AppImage` build out of the box without failing on a missing snap publish credential.
-- **`enabled: true` + `SNAPCRAFT_STORE_CREDENTIALS` set** → snap target emits, snap publishes on release.
-- **`enabled: false`** → off, regardless of credentials. Explicit opt-out.
+- **Nothing declared** → the snap SHIPS, like every other format: presence is the switch and the default is on.
+- **Defaulted (nothing written) + no `SNAPCRAFT_STORE_CREDENTIALS`** → skipped, with a build-time log line naming the credential and how to get it. A fresh scaffold produces a working `.deb + .AppImage` build out of the box without failing on a missing publish credential.
+- **WRITTEN in config + no `SNAPCRAFT_STORE_CREDENTIALS`** → a BUILD still skips it as above, but `omega publish` REFUSES in its first step, naming the credential, `platforms.linux.formats.snap` and `omega manage --service publishing` ([#867](https://github.com/Omega-JS-Stack/omega/issues/867)). Writing the format down is saying this brand ships it, and a release that silently drops it is the failure this replaced.
+- **Declared + `SNAPCRAFT_STORE_CREDENTIALS` set** → the snap target emits and publishes on release.
+- **`platforms.linux.formats.snap: false`** → off, regardless of credentials. The explicit opt-out.
 
-To turn snap publishing on for a project that already has the field set to `true`:
+To turn snap publishing on for a project that ships the format:
 
 1. Mint store credentials locally:
    ```bash
    snapcraft export-login -    # writes a credentials blob to stdout
    ```
 2. Paste the entire blob (multi-line) into `.env` as `SNAPCRAFT_STORE_CREDENTIALS=...`.
-3. Run `npx omega push-secrets` to flow the secret to GitHub Actions.
+3. Run `npx omega deploy` (its precheck flows the secret to GitHub Actions).
 4. Next `npm run release` builds + uploads the snap automatically. No config flip needed.
 
-Reference: the workflow's Linux step conditionally installs `snapcraft` (`sudo snap install snapcraft --classic`) only when both (a) `platforms.linux.snap.enabled !== false` AND (b) `SNAPCRAFT_STORE_CREDENTIALS` secret is present. Mirrors the build-config-side gate.
+Reference: the workflow's Linux step conditionally installs `snapcraft` (`sudo snap install snapcraft --classic`) only when both (a) the brand still ships the snap format (read through `@omega.js/config`'s own `enabledFormats`, so the check cannot drift from the build's) AND (b) the `SNAPCRAFT_STORE_CREDENTIALS` secret is present.
 
 ## File associations + custom protocols (uncommon)
 

package/docs/logging.md

@@ -87,7 +87,7 @@ npx omega logs test --lines=100 # last 100 lines of the previous test run
 npx omega logs build --path     # just the path, for piping
 ```
 
-Anything else fails naming the four surfaces. (The four files themselves are described in the lifetime table below; `ci.log` and `signing.log` are not tail targets.)
+Anything else fails naming the four surfaces. (The four files themselves are described in the lifetime table below; `deploy.log` and `signing.log` are not tail targets.)
 
 `mgr logs` only resolves the dev path (`<cwd>/logs/<surface>.log`). To find the production runtime log on a user's machine, use the table above or call `getLogFilePath()` from app code.
 
@@ -173,7 +173,7 @@ window "main": closed (destroyed)
 activate (macOS) — surfacing main (visible=false, minimized=false)
 _ensureDockVisible — calling dock.show()
 _ensureDockVisible — dock already visible
-second-instance — argv=["..."] cwd=/...
+second-instance argv=["..."] eventArgv=["..."] cwd=/...
 second-instance — surfacing main (visible=false, minimized=false)
 ```
 
@@ -209,7 +209,7 @@ File path resolution in main:
 
 The transport is set up lazily on first `log()` call, so importing `LoggerLite` in build/CLI contexts that have no Electron is harmless.
 
-## Coexisting with `dev.log`, `build.log`, `test.log`, and `ci.log`
+## Coexisting with `dev.log`, `build.log`, `test.log`, and `deploy.log`
 
 Five separate logs in `<projectRoot>/logs/`:
 
@@ -219,11 +219,11 @@ Five separate logs in `<projectRoot>/logs/`:
 | `dev.log` | Gulp pipeline + spawned Electron child stdout (`npm start`) | Truncated each `npm start` |
 | `build.log` | Gulp pipeline output for production builds/packages (`npm run build` / `package` / `publish`, i.e. `OMEGA_BUILD_MODE=true`) | Truncated each build |
 | `test.log` | `npx omega test` runner output (suite names, pass/fail states, harness boot lines) | Truncated each test run |
-| `ci.log` | GH Actions release run output (streamed locally during `npm run release`) | Truncated each release run |
+| `deploy.log` | GH Actions run output, streamed locally by the follower every target's deploy uses (`omega deploy`, `npm run release`) ([#873](https://github.com/Omega-JS-Stack/omega/issues/873); this was `ci.log`) | Truncated each deploy |
 | `signing.log` | JSONL signing events from Windows code-signing (local dev fallback; on CI this writes to the runner home as `omega-signing.log` instead) | Appended (not truncated) |
 
 `dev.log` and `build.log` are the same gulp tee — which one it writes is chosen by `OMEGA_BUILD_MODE`, so they never both fill up in one run. (Disable the tee with `OMEGA_LOG_FILE=false`; override its path with `OMEGA_LOG_FILE=<path>`.)
 
-They serve different purposes and don't overlap — `dev.log`/`build.log` show you "is the build still running?", `test.log` shows you "which test failed on the last run?", `ci.log` shows you "did the release workflow pass?", `runtime.log` shows you "is my app's auto-updater finding the right release feed?". All useful.
+They serve different purposes and don't overlap: `dev.log`/`build.log` show you "is the build still running?", `test.log` shows you "which test failed on the last run?", `deploy.log` shows you "did the release workflow pass?", `runtime.log` shows you "is my app's auto-updater finding the right release feed?". All useful.
 
 In production: only `runtime.log` exists (no project, no gulp, no GH Actions stream).

package/docs/releasing.md

@@ -31,15 +31,16 @@ releases: {
 
 Every artifact name is **stable across releases** — no version in it:
 
-| Platform | Artifact | Asset name |
+| Platform | Format | Asset name |
 |---|---|---|
-| macOS | `universal` (dmg) | `<Product>-mac-universal.dmg` |
-| macOS | auto-update zip | `<Product>-mac-universal.zip` |
-| Windows | `universal` (NSIS) | `<Product>-windows-universal.exe` |
-| Linux | `debian` | `<Product>-linux-debian.deb` |
-| Linux | `appimage` | `<Product>-linux-appimage.AppImage` |
+| mac | `dmg` | `<Product>-mac-dmg.dmg` |
+| mac | auto-update zip (not a declared format) | `<Product>-mac.zip` |
+| windows | `nsis` | `<Product>-windows-nsis.exe` |
+| linux | `deb` | `<Product>-linux-deb.deb` |
+| linux | `appimage` | `<Product>-linux-appimage.AppImage` |
+| linux | `snap` | none: the Snap Store holds the file, so it is never a release asset |
 
-`<Product>` is `app.productName` (← `brand.name`) with non-filename characters hyphenated. The rule has ONE home — `@omega.js/config`'s `desktop-artifacts.js` — which `gulp/build-config` writes into `dist/electron-builder.yml`'s artifactName templates and the website reads to build its buttons. Never spell an asset name anywhere else.
+`<Product>` is `app.productName` (← `brand.name`) with non-filename characters hyphenated. The platform and format words are the ONE vocabulary ([#867](https://github.com/Omega-JS-Stack/omega/issues/867)) and the rule has ONE home, `@omega.js/config`'s `platforms.js`, which `gulp/build-config` writes into `dist/electron-builder.yml`'s artifactName templates and the website reads to build its buttons. Never spell an asset name anywhere else.
 
 Because the names never change, GitHub's latest-release redirect is a permanent direct-download URL:
 
@@ -47,7 +48,7 @@ Because the names never change, GitHub's latest-release redirect is a permanent
 https://github.com/<owner>/<brand.id>-releases/releases/latest/download/<asset>
 ```
 
-That is what `site.targets.desktop.downloads[platform][artifact]` derives (see [docs/shared/config.md](../../../docs/shared/config.md#the-site-global-the-curated-targets-view-85-610) in the Omega repo), what the `/download` page's buttons link, and what every `/download/<platform>[/<artifact>]` shortlink redirects to. **Releasing a desktop version never touches the website**, and the published URLs never change.
+That is what `site.targets.desktop.downloads[platform][format]` derives (see [docs/shared/config.md](../../../docs/shared/config.md#the-site-global-the-curated-targets-view-85-610) in the Omega repo), what the `/download` page's buttons link, and what every `/download/<platform>[/<format>]` shortlink redirects to. **Releasing a desktop version never touches the website**, and the published URLs never change.
 
 Auto-update is unaffected: `electron-updater` reads the feed files (`latest-mac.yml`, `latest.yml`, `latest-linux.yml`), which name whatever artifact the build produced.
 
@@ -59,7 +60,7 @@ If the releases repo has to move (rename or transfer), the rules are:
 
 - **The existing repo is the survivor** — transfer it, never build a fresh one. GitHub keeps redirects for the web pages, git remotes, the API and release-asset URLs, and `electron-updater` follows them, so every already-installed app (its feed URL is baked into `app-update.yml` at build time) keeps updating.
 - **Never reuse the old org/name.** A new repo created at the old path takes the redirect over and silently steals every installed app's update feed and every published download link.
-- Update `releases.repo` (and `releases.owner` if the owner changed) in `config/omega.json5`. The website's URLs re-derive from that on its next build; the asset names do not change.
+- The repo NAME is not configurable ([#883](https://github.com/Omega-JS-Stack/omega/issues/883)): it is always `<brand.id>-releases` under `repo.org`, so a move means renaming the repo to match (or, if the brand itself is renaming, changing `brand.id` / `repo.org` once). The website's URLs re-derive on its next build; the asset names do not change.
 - **Fallback only** — if the surviving repo were a *different* repo, installed apps would need a bridge release: build once with the new feed baked in and publish it to the OLD repo, so clients update themselves onto the new feed before it is retired.
 
 > The `downloads:` block (the `download-server` mirror at tag `installer`, `gulp/mirror-downloads`) predated this: it existed only to give marketing a fixed filename, which the versionless names made free. It is GONE ([#799](https://github.com/Omega-JS-Stack/omega/issues/799)): the task, the `publish` step, the finalize-release mirror and the second repo's provisioning are deleted, and `downloads.enabled|owner|repo|tag` are retired config keys a brand still carrying them fails validation on. One public repo, one set of assets.
@@ -104,7 +105,6 @@ Edit `.env`:
 
 ```bash
 GH_TOKEN="ghp_..."
-OMEGA_ADMIN_KEY="..."
 
 CSC_LINK="config/certs/developer-id-application.p12"
 CSC_KEY_PASSWORD="<password>"
@@ -147,12 +147,20 @@ A successful release on macOS prints something like:
 [notarize] Notarizing MyApp via App Store Connect API key (XXXXXXXXXX)...
 [notarize] Done in 84s.
 [release] Released 2 artifact(s):
-  • release/MyApp-mac-universal.dmg
-  • release/MyApp-mac-universal.zip
+  • release/MyApp-mac-dmg.dmg
+  • release/MyApp-mac.zip
 ```
 
 The release will appear on the GitHub repo's Releases page (as a draft if `releaseType: draft` is set in `electron-builder.yml`, or published if `release`).
 
+A release that uploaded NOTHING fails the task ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)). electron-builder resolves its build promise with the local artifact paths whether or not a byte was published, and it reports a skipped upload only as a warning on its own logger, so the task reads that logger for the length of the build. Any `skipped publishing` / `GitHub release not created` warning ends the run with electron-builder's own reason and tag instead of the `Released N artifact(s)` line:
+
+```
+[release] Nothing was uploaded: electron-builder skipped publishing 4 artifact(s) (...) to v0.0.1
+  (existing release published more than 2 hours ago). Bump the version in package.json: a release
+  that already exists is never re-uploaded.
+```
+
 ## Multi-platform release via CI
 
 CI handles the cross-platform matrix. The scaffolded workflow is `build.yml`, dispatched by `npx omega release` / `npx omega deploy`:
@@ -167,7 +175,7 @@ build             needs setup; matrix over the resolved OSes: npm ci, then
                   electron-builder publishes the DRAFT release in the brand's releases
                   repo), and `npm run package` on windows, whose unsigned output uploads
                   as the `windows-unsigned` artifact
-windows-strategy  needs [setup, build]; reads platforms.win.signing.strategy from config
+windows-strategy  needs [setup, build]; reads platforms.windows.signing.strategy from config
                   (only when windows is in the matrix)
 windows-sign      the self-hosted EV-token box, hosted windows-latest for the cloud
                   strategy, skipped for local: `omega sign-windows`, then
@@ -179,9 +187,9 @@ finalize          needs [setup, build, windows-sign] under always(), gated on th
                   draft standing for the next one to fill in)
 ```
 
-The macOS step decodes `secrets.CSC_LINK` and `secrets.APPLE_API_KEY` (uploaded by `npx omega push-secrets` as base64-encoded file contents) back to disk before running `npm run release:local`.
+The macOS step decodes `secrets.CSC_LINK` and `secrets.APPLE_API_KEY` (uploaded by `omega deploy`'s precheck as base64-encoded file contents) back to disk before running `npm run release:local`.
 
-**Dispatch only, never a push trigger** ([#802](https://github.com/Omega-JS-Stack/omega/issues/802)): the workflow declares `workflow_dispatch` alone, so no commit and no tag releases anything ([docs/shared/deploys.md](../../../docs/shared/deploys.md) in the Omega repo is the contract for all four frameworks). It runs no tests either: the suites run on the developer's machine and the commit gate runs the battery at ship.
+**Dispatch only, never a push trigger** ([#802](https://github.com/Omega-JS-Stack/omega/issues/802)): the workflow declares the one dispatch trigger (`workflow_dispatch`, [#880](https://github.com/Omega-JS-Stack/omega/issues/880), [#923](https://github.com/Omega-JS-Stack/omega/issues/923)) and nothing else, so no commit and no tag releases anything ([docs/shared/deploys.md](../../../docs/shared/deploys.md) in the Omega repo is the contract for all four frameworks). It runs no tests either: the suites run on the developer's machine and the commit gate runs the battery at ship.
 
 To release:
 1. Bump the version in `package.json`.
@@ -190,7 +198,7 @@ To release:
 
 ## Windows signing strategies
 
-Set `platforms.win.signing.strategy` in `config/omega.json5`:
+Set `platforms.windows.signing.strategy` in `config/omega.json5`:
 
 | Strategy | What runs | When to use |
 |---|---|---|
@@ -220,7 +228,7 @@ For details see [`docs/signing.md`](signing.md#windows-setup).
 
 ### CI: GitHub Releases upload fails
 - Verify `GH_TOKEN` secret is set. The auto-injected `GITHUB_TOKEN` won't work for cross-repo writes.
-- Confirm the config addresses the right repo: `repo.providers.github.org` (plus `repo.providers.github.repo` when the app repo is not `brand.id`) and, for the artifacts, `targets.desktop.releases`.
+- Confirm the config addresses the right repo: `repo.org` + `brand.id` derive both the source repo (`<brand.id>-omega`) and the artifacts' repo (`<brand.id>-releases`), and `targets.desktop.releases` is the presence switch alone.
 
 ## Related docs