@omega.js/desktop 0.50.0 → 0.51.0

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

@@ -1,15 +1,22 @@
+# Deliberate deploys (D13): commits never auto-publish, save = commit and
+# publish = an explicit dispatch (`omega deploy`, or a plain HTTP
+# workflow_dispatch call).
+# Regenerated by every verb's ensureTarget: customize via config/omega.json5, not here.
 name: Build & Release
 
-# Manual-trigger only — releases are intentional, not a side effect of every commit.
 on:
   workflow_dispatch:
     inputs:
       platforms:
-        description: 'Platforms to build (comma-separated). Examples: all, windows, mac,linux'
+        description: "Platforms to build (comma-separated), in OMEGA's vocabulary. Examples: all, windows, mac,linux"
         required: false
         default: 'all'
         type: string
 
+concurrency:
+  group: ${{ github.ref }}
+  cancel-in-progress: true
+
 env:
   NODE_VERSION: '{{ versions.node }}'
   OMEGA_BUILD_MODE: 'true'
@@ -24,18 +31,15 @@ env:
   # restating one. Add a key to the schema, not to this file.
   {{ githubSecrets }}
 
-concurrency:
-  group: ${{ github.ref }}
-  cancel-in-progress: true
-
 jobs:
   # Resolve which platforms to build from the workflow_dispatch `platforms` input.
   # Outputs a JSON matrix (consumed by the build job) plus per-platform booleans
   # (consumed by windows-strategy / windows-sign gating). When `platforms` is
-  # omitted (older invocations) the input defaults to 'all'.
+  # omitted it defaults to 'all'.
   setup:
     name: Setup (resolve target platforms)
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     outputs:
       matrix:  ${{ steps.resolve.outputs.matrix }}
       mac:     ${{ steps.resolve.outputs.mac }}
@@ -47,28 +51,31 @@ jobs:
           input="${{ github.event.inputs.platforms || 'all' }}"
           input="$(echo "$input" | tr '[:upper:]' '[:lower:]')"
 
-          mac=false; win=false; linux=false
-          if [[ "$input" == *all* ]]; then mac=true; win=true; linux=true; fi
-          if [[ "$input" == *mac* ]] || [[ "$input" == *darwin* ]]; then mac=true; fi
-          if [[ "$input" == *win* ]]; then win=true; fi
-          if [[ "$input" == *linux* ]] || [[ "$input" == *ubuntu* ]]; then linux=true; fi
+          # The input speaks OMEGA's platform vocabulary and nothing else (#867):
+          # mac, windows, linux. The runner LABELS below are GitHub's names, the
+          # one foreign vocabulary this job translates.
+          mac=false; windows=false; linux=false
+          if [[ "$input" == *all* ]]; then mac=true; windows=true; linux=true; fi
+          if [[ "$input" == *mac* ]]; then mac=true; fi
+          if [[ "$input" == *windows* ]]; then windows=true; fi
+          if [[ "$input" == *linux* ]]; then linux=true; fi
 
           entries=()
-          $mac   && entries+=('"macos-latest"')
-          $win   && entries+=('"windows-latest"')
-          $linux && entries+=('"ubuntu-latest"')
+          $mac     && entries+=('"macos-latest"')
+          $windows && entries+=('"windows-latest"')
+          $linux   && entries+=('"ubuntu-latest"')
           if [ ${#entries[@]} -eq 0 ]; then
             echo "Error: '$input' did not match any platform. Use: all | mac | windows | linux | comma-separated combos." >&2
             exit 1
           fi
 
           matrix="[$(IFS=,; echo "${entries[*]}")]"
-          echo "Resolved input='$input' → mac=$mac, win=$win, linux=$linux, matrix=$matrix"
+          echo "Resolved input='$input' → mac=$mac, windows=$windows, linux=$linux, matrix=$matrix"
 
-          echo "matrix=$matrix"  >> "$GITHUB_OUTPUT"
-          echo "mac=$mac"        >> "$GITHUB_OUTPUT"
-          echo "windows=$win"    >> "$GITHUB_OUTPUT"
-          echo "linux=$linux"    >> "$GITHUB_OUTPUT"
+          echo "matrix=$matrix"      >> "$GITHUB_OUTPUT"
+          echo "mac=$mac"            >> "$GITHUB_OUTPUT"
+          echo "windows=$windows"    >> "$GITHUB_OUTPUT"
+          echo "linux=$linux"        >> "$GITHUB_OUTPUT"
 
   build:
     name: Build (${{ matrix.os }})
@@ -83,49 +90,91 @@ jobs:
       # The workflow's own token: a checkout never needs the release PAT, and a
       # bad PAT then fails at the release step with an API error, not here with
       # git asking for a username.
-      - uses: actions/checkout@v4
+      # Shallow on purpose: nothing in a desktop release reads git HISTORY, and
+      # electron-builder publishes over the API rather than over a git push.
+      - uses: actions/checkout@v7
         with:
-          fetch-depth: 0
+          fetch-depth: 1
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v7
         with:
           node-version: ${{ env.NODE_VERSION }}
           cache: npm
 
-      - name: Install Socket Firewall
-        run: npm install -g sfw
+      {{ installFirewall }}
 
       # 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
       # actions/runner shell-resolution: `cmd` is win-only and ignored elsewhere).
+      # `npm.cmd`, not `npm`, on the cmd leg (#872): the firewall spawns the command
+      # it is given LITERALLY, with no PATHEXT resolution, and the only `npm` on a
+      # Windows runner's PATH is `npm.cmd`. Bare `npm` there is
+      # `Command 'npm' not found in PATH`, from sfw rather than from cmd.
       - if: matrix.os == 'windows-latest'
         shell: cmd
-        run: sfw npm ci
+        run: sfw npm.cmd ci {{ installWorkspace }}
       - if: matrix.os != 'windows-latest'
-        run: sfw npm ci
+        run: sfw npm ci {{ installWorkspace }}
+
+      # No npx on a runner, in any spelling (#877): which package won npm's
+      # shared `omega` bin link is an install-order accident, and an `npx omega`
+      # that finds nothing linked fetches a stranger's package from the REGISTRY
+      # with every secret in the job env. This workflow belongs to exactly one
+      # framework, so it runs that framework's own bin FILE. The path is
+      # anchored at the workspace root: npm hoists a workspace's dependencies
+      # there, where a target-scoped `./node_modules` never sees them (#898).
+      # ONE step for all three legs, under an explicit `shell: bash`: bash exists
+      # on every hosted runner, and the cmd forcing above is for npm's
+      # long-running scripts, while this step only READS versions.
+      - name: Log versions
+        shell: bash
+        run: |
+          echo "Node: $(node -v)"
+          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.
-      # `npx omega push-secrets` uploads .p12 / .p8 files as base64-encoded secrets;
+      # `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
+      # empty secret writes an empty file, and `security import` of one dies with
+      # "parameters not valid".
+      # A missing secret EXITS 1 (#891): a mac build this framework ships is
+      # signed and notarized, so the leg stops here with the command that fixes
+      # it rather than publishing a release Gatekeeper refuses on every Mac.
       - if: matrix.os == 'macos-latest'
         run: |
           mkdir -p config/certs
-          echo "${{ secrets.CSC_LINK }}"      | base64 --decode > config/certs/dev-id.p12
-          echo "${{ secrets.APPLE_API_KEY }}" | base64 --decode > config/certs/AuthKey.p8
+          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."
+            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."
+            exit 1
+          fi
       # The two file-path OVERRIDES of the workflow env: electron-builder and
       # notarytool read these as paths, and the step above just decoded the
       # base64 secrets of the same name to disk. Every other credential comes
-      # from the generated env block.
+      # from the generated env block. Each override is set only when its file was
+      # written; empty reads as UNSET after the build's sanitize pass, and
+      # electron-builder then finds no identity, warns and skips signing (it only
+      # fails on a missing identity for MAS or `forceCodeSigning`, neither of
+      # which this framework sets).
       - if: matrix.os == 'macos-latest'
         env:
-          CSC_LINK:         config/certs/dev-id.p12
-          APPLE_API_KEY:    config/certs/AuthKey.p8
+          CSC_LINK:         ${{ secrets.CSC_LINK != '' && 'config/certs/dev-id.p12' || '' }}
+          APPLE_API_KEY:    ${{ secrets.APPLE_API_KEY != '' && 'config/certs/AuthKey.p8' || '' }}
         run: npm run release:local
 
-      # Linux — install snapcraft when (a) the consumer hasn't explicitly disabled snap
-      # in their config (`platforms.linux.snap.enabled !== false`; default is true) AND
+      # 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
       # the same condition, so the build still produces .deb + .AppImage cleanly with
@@ -133,29 +182,37 @@ jobs:
       - name: Install Snapcraft (Linux, when snap enabled + creds present)
         if: matrix.os == 'ubuntu-latest'
         run: |
-          # (a) Config check — explicit `enabled: false` opts out; missing/true opts in.
-          # `@omega.js/desktop/config` is the vendored @omega.js/config loader — resolves
+          # (a) The declaration (#867), read through @omega.js/config's own format
+          # table so this check can never drift from the build's.
+          # `@omega.js/desktop/config` is the vendored loader: it resolves
           # config/omega.json5 for the desktop target (brand-monorepo aware).
-          if node -e 'const c = require("@omega.js/desktop/config").loadConfig(process.cwd(), "desktop").config; process.exit(c.platforms?.linux?.snap?.enabled === false ? 1 : 0);'; then
+          if node -e 'const o = require("@omega.js/desktop/config"); const c = o.loadConfig(process.cwd(), "desktop").config; process.exit(o.enabledFormats(c, "desktop").some((e) => e.format === "snap") ? 0 : 1);'; then
             CONFIG_OK=1
           else
             CONFIG_OK=0
-            echo "platforms.linux.snap.enabled === false — skipping snapcraft install."
+            echo "platforms.linux.formats.snap is dropped, skipping snapcraft install."
           fi
           # (b) Credentials check — empty secret means no publish creds available.
           if [ -n "$SNAPCRAFT_STORE_CREDENTIALS" ]; then
             CREDS_OK=1
           else
             CREDS_OK=0
-            echo "SNAPCRAFT_STORE_CREDENTIALS not set — skipping snapcraft install. Run 'snapcraft export-login -' and add the blob to .env, then 'mgr push-secrets'."
+            echo "SNAPCRAFT_STORE_CREDENTIALS not set, skipping snapcraft install. Run 'snapcraft export-login -' and add the blob to .env, then 'omega deploy'."
           fi
           if [ "$CONFIG_OK" = 1 ] && [ "$CREDS_OK" = 1 ]; then
             sudo snap install snapcraft --classic
             echo "Snapcraft installed."
           fi
 
-      # Linux — no signing
+      # 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).
       - if: matrix.os == 'ubuntu-latest'
+        env:
+          CSC_LINK: ''
+          CSC_KEY_PASSWORD: ''
+          APPLE_API_KEY: ''
         run: npm run release:local
 
       # Windows — package (build + electron-builder package) unsigned. We do NOT publish
@@ -173,10 +230,13 @@ jobs:
           # it always did. windows-sign signs separately.
           CSC_LINK: ''
           CSC_KEY_PASSWORD: ''
+          # Same for the notarization key: base64 in this env, mac-only, and the
+          # precheck should never be handed a .p8 on a leg that cannot notarize.
+          APPLE_API_KEY: ''
         run: npm run package
 
       - if: matrix.os == 'windows-latest'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: windows-unsigned
           # Capture installer + auto-updater feed + blockmap so windows-sign can re-upload them all.
@@ -193,59 +253,78 @@ jobs:
     needs: [setup, build]
     if: needs.setup.outputs.windows == 'true'
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     outputs:
       strategy: ${{ steps.resolve.outputs.strategy }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
         with:
           node-version: ${{ env.NODE_VERSION }}
           cache: npm
-      - run: npm install -g sfw
-      - run: sfw npm ci
+      {{ installFirewall }}
+      - run: sfw npm ci {{ installWorkspace }}
       - id: resolve
         run: |
-          STRATEGY=$(node -e "const c=require('@omega.js/desktop/config').loadConfig(process.cwd(),'desktop').config;console.log(c.platforms?.win?.signing?.strategy || 'self-hosted');")
+          STRATEGY=$(node -e "const c=require('@omega.js/desktop/config').loadConfig(process.cwd(),'desktop').config;console.log(c.platforms?.windows?.signing?.strategy || 'self-hosted');")
           echo "strategy=$STRATEGY" >> "$GITHUB_OUTPUT"
           echo "Resolved Windows signing strategy: $STRATEGY"
 
   windows-sign:
     name: Sign Windows
     needs: [setup, build, windows-strategy]
-    # Strategy comes from config platforms.win.signing.strategy (read by windows-strategy job).
+    # 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`
-    if: needs.setup.outputs.windows == 'true' && needs.windows-strategy.outputs.strategy != 'local'
+    # 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,
+    # never a failure: `finalize` runs under `always()` and the unsigned Windows
+    # artifact the build job uploaded is still there. The box refuses such a job
+    # on its own too, through the runner's job-started hook.
+    if: needs.setup.outputs.windows == 'true' && needs.windows-strategy.outputs.strategy != 'local' && github.event_name == 'workflow_dispatch'
     runs-on: ${{ needs.windows-strategy.outputs.strategy == 'cloud' && fromJSON('["windows-latest"]') || fromJSON('["self-hosted","windows","ev-token"]') }}
+    # Signing is ~20s per installer. A job still running much later is waiting on
+    # something that never comes (a PIN at a locked console); end it instead of
+    # holding the self-hosted runner for GitHub's six-hour default.
+    timeout-minutes: 30
     # Use cmd.exe (not PowerShell) on Windows. Self-hosted runners often have PowerShell
     # ExecutionPolicy set to Restricted, which blocks the Actions-generated wrapper .ps1
     # scripts that GH spits out for every `run:` step. cmd.exe has no such restriction
-    # and runs the same `npm ci` / `npx ...` commands fine.
+    # and runs the same `npm ci` / `node ...` commands fine.
     defaults:
       run:
         shell: cmd
     # 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.win.signing.cloud.provider` names is consumed) — all arrive
+    # `platforms.windows.signing.cloud.provider` names is consumed), all arrive
     # through the workflow's generated env block. Set them in the brand .env and
-    # push with `npx omega push-secrets`.
+    # pushed by `npx omega deploy`'s precheck.
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
         with:
           node-version: ${{ env.NODE_VERSION }}
-      - run: npm install -g sfw
-      - run: sfw npm ci
-      - uses: actions/download-artifact@v4
+      # No firewall on the self-hosted signer, on purpose (#872): this box is the
+      # brand owner's own machine and its network does not reach Socket's API
+      # (the firewall fails closed on `fetch failed`). The lockfile it installs is
+      # the one the hosted build jobs installed through the firewall minutes
+      # earlier in this same run, so nothing arrives here unscreened. `npm.cmd`
+      # because this whole job runs under cmd (see `defaults` above).
+      - run: npm.cmd ci {{ installWorkspace }}
+      - uses: actions/download-artifact@v8
         with:
           name: windows-unsigned
           path: release
-      - run: npx omega sign-windows --in release --out release/signed
+      # The framework's own bin FILE (#877): nothing here resolves a bin NAME,
+      # so no missing link can make npx fetch a stranger's package with the
+      # signing token attached. cmd runs `node` like any other shell.
+      - run: node "${{ github.workspace }}/node_modules/@omega.js/desktop/bin/omega" sign-windows --in release --out release/signed
       # Upload the SIGNED Windows assets to the release the mac/linux electron-builder
       # publish step already created in the brand's public releases repo. The asset
       # names carry no version, so nothing is mirrored anywhere.
-      - run: npx omega finalize-release --signed-dir release/signed
+      - run: node "${{ github.workspace }}/node_modules/@omega.js/desktop/bin/omega" finalize-release --signed-dir release/signed
 
   finalize:
     name: Finalize release
@@ -257,20 +336,21 @@ jobs:
     needs: [setup, build, windows-sign]
     if: always() && needs.build.result == 'success'
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
         with:
           node-version: ${{ env.NODE_VERSION }}
           cache: npm
-      - run: npm install -g sfw
-      - run: sfw npm ci
+      {{ 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
       # 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: npx omega finalize-release --publish
+        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."

package/dist/defaults/AGENTS.md

@@ -52,6 +52,7 @@ npx omega install live # restore the published @omega.js/desktop from npm
 ## Where things live
 
 - `config/omega.json5`: the single OMEGA config (JSON5), with shared sections (brand, analytics, payment, cloud, monitoring, theme) at the top level; desktop settings (app, platforms, autoUpdate, startup, releases, remoteConfig, restartManager) under `targets.desktop`.
+  - What the app SHIPS is one declaration: `platforms.<mac|windows|linux>.formats.<dmg|nsis|deb|appimage|snap>`. Presence = enabled, every platform and format is on by default, and `false` drops one (`snap: false`). Per-format settings live inside the format.
 - Packaging config: fully generated. @omega.js/desktop produces `dist/electron-builder.yml` from `config/omega.json5` (brand/app/signing) + @omega.js/desktop's opinionated defaults. Consumers never ship an `electron-builder.yml`. Override defaults via the `electronBuilder:` block in `omega.json5` if you genuinely need to.
 - `hooks/notarize/post.js`: optional post-notarize extension hook (@omega.js/desktop owns the actual `afterSign` notarize step).
 - `src/main.js`: main-process entry. One-line bootstrap of `@omega.js/desktop/main`.
@@ -62,7 +63,7 @@ npx omega install live # restore the published @omega.js/desktop from npm
 - `src/views/<window>/index.html`: per-window HTML.
 - `src/assets/js/components/<window>/index.js`: renderer entry per window.
 - `src/assets/scss/main.scss`: shared SCSS.
-- `config/icons/<platform>/<slot>.png`: optional icon overrides (`macos/icon.png`, `macos/tray.png`, `macos/dmg.png`, `windows/icon.png`, etc.).
+- `config/icons/<platform>/<slot>.png`: optional icon overrides (`mac/icon.png`, `mac/tray.png`, `mac/dmg.png`, `windows/icon.png`, etc.; the platform words are `mac`, `windows`, `linux`).
   - Ship ONE file per slot at the native (retina) size; @omega.js/desktop auto-downscales @1x variants.
   - macOS tray must be 32×32 (@omega.js/desktop renames to `trayTemplate.png` in dist for the OS dark-mode magic).
   - Missing slots fall back to @omega.js/desktop bundled defaults; Linux falls back to Windows resolution.
@@ -85,7 +86,7 @@ new (require('@omega.js/desktop/renderer'))().initialize();
 
 In main: `manager.storage`, `manager.ipc`, `manager.windows`, `manager.tray`, `manager.menu`, `manager.contextMenu`, `manager.startup`, `manager.appState`, `manager.deepLink`, `manager.autoUpdater`, `manager.sentry`, `manager.omega`, `manager.context`, `manager.usage`, `manager.remoteConfig`, `manager.analytics`, `manager.restartManager`.
 
-In renderer: `window.desktop.storage`, `window.desktop.ipc`, `window.desktop.logger`, `OMEGA_BUILD_JSON.config`.
+In renderer: `window.desktop.storage`, `window.desktop.ipc`, `window.desktop.logger`, `window.OMEGA_BUILD_JSON.config` (the one `build.js` the view's shell loads).
 
 ## Dependency resolution
 

package/dist/defaults/_.gitignore

@@ -11,8 +11,10 @@ node_modules/
 *.log
 /logs/
 
-# Apple signing artifacts — never commit these
-config/certs/
+# Signing artifacts: never commit these. config/certs/ keeps its README, the one
+# tracked explanation of where the real material lives.
+config/certs/*
+!config/certs/README.md
 *.p12
 *.cer
 *.mobileprovision

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

@@ -1,60 +1,40 @@
-# `config/certs/` — Code-signing certificates and provisioning profiles
+# `config/certs/`: signing material on a RUNNER, and nothing else
 
-**Never commit anything in this directory.** The parent `.gitignore` excludes `*.p12`, `*.cer`, `*.mobileprovision`, `*.p8`, `*.pem` — and the entire `config/certs/` subdirectory is also ignored as a defense-in-depth measure.
+**Never commit anything in this directory.** The target's `.gitignore` ignores everything here except this file, which is tracked so the explanation travels with the repo.
 
-## File inventory
+## Locally: nothing lives here
 
-### macOS (signing + notarization)
+Signing material is READ IN PLACE from the signing tree ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)), never copied into a target:
 
-| File | Source | Used by | Env var pointing at it |
-|---|---|---|---|
-| `developer-id-application.p12` | Apple Developer → Certificates → "Developer ID Application" | electron-builder for code signing | `CSC_LINK` |
-| `developer-id-installer.p12` | Apple Developer → Certificates → "Developer ID Installer" | electron-builder for `.pkg` signing (only if you ship a pkg installer) | `CSC_INSTALLER_LINK` |
-| `AuthKey_XXXXXXXXXX.p8` | App Store Connect → Users and Access → Keys | Notarization via notarytool API | `APPLE_API_KEY` (path), `APPLE_API_KEY_ID`, `APPLE_API_ISSUER` |
-| `<app-name>.provisionprofile` | Apple Developer → Profiles → Developer ID Provisioning Profile | Required if your app uses entitlements requiring Apple's review (push notifications, in-app purchase, network extensions, etc.) | electron-builder auto-discovers in `build/` |
+```
+<company root>/company/.omega/certificates/apple/    # first, when the brand names a company
+<brand root>/.omega/certificates/apple/              # second
+```
 
-You also need (in `.env`, not in this directory):
-- `CSC_KEY_PASSWORD` — password for the `.p12` files
-- `APPLE_API_KEY_ID` — 10-char Key ID (matches the `XXXXXXXXXX` in the `.p8` filename)
-- `APPLE_API_ISSUER` — issuer UUID from App Store Connect
-- `APPLE_TEAM_ID` — 10-char team ID from developer.apple.com
+The `omega manage --service certificates` walk produces that tree, and every desktop boot (the CLI and gulp alike) derives the paths into it once, through `@omega.js/devkit/signing-env`:
 
-### Windows (signing)
+| Env var | Derived from |
+|---|---|
+| `CSC_LINK` | `certificates/DEVELOPER_ID_APPLICATION_G2.p12` in the tree, when `CSC_KEY_PASSWORD` opens it |
+| `APPLE_API_KEY` | `AuthKey_<APPLE_API_KEY_ID>.p8` in the tree |
 
-For self-hosted EV USB token:
-| File / value | Source | Env var |
-|---|---|---|
-| (USB token plugged into self-hosted runner) | Sectigo / DigiCert / etc. EV cert physical token | `WIN_EV_TOKEN_PATH`, `WIN_CSC_KEY_PASSWORD` |
+So the build, `omega validate-certs` and the deploy precheck's secret publish all read one answer. An EXPLICIT `CSC_LINK` or `APPLE_API_KEY` in the env always wins, and with neither set nor derivable, electron-builder falls back to macOS Keychain identity discovery.
 
-For cloud signing (future):
-- Azure Trusted Signing — service principal creds in `.env`
-- SSL.com eSigner — username + password + credential ID in `.env`
-- DigiCert KeyLocker — API token + endpoint in `.env`
+There is no provisioning profile: Developer ID is DIRECT distribution, signed and notarized, and needs none.
 
-No file lives in `config/certs/` for Windows — credentials are env-vars-only.
+## On the runner: this directory is the decode target
 
-## Are these per-brand or universal?
+The generated `.github/workflows/build.yml` decodes the pushed base64 secrets back to disk here (`config/certs/dev-id.p12`, `config/certs/AuthKey.p8`) and points `CSC_LINK` / `APPLE_API_KEY` at the decoded files. `omega deploy`'s precheck is what pushes those secrets; a mac leg with either secret missing exits 1 rather than shipping an unsigned app.
 
-**Universal across brands you ship as the same Apple Developer team:**
-- `developer-id-application.p12` — one per team, valid for all your apps
-- `developer-id-installer.p12` — same
-- `AuthKey_*.p8` — one per team, used for notarization across all apps
-- Apple Team ID, Apple ID, app-specific password
-- Windows EV token (one per team)
+## The rest of the signing set
 
-**Per-brand / per-app:**
-- Provisioning profile (`*.provisionprofile`) — only required if entitlements demand it; tied to a specific bundle ID (`com.itwcw.<app>`)
-- Icons (separate concern, live in `build/`, not `config/certs/`)
+These are values, not files, and live in the brand `.env` (never here):
 
-## Setup walkthrough
+- `CSC_KEY_PASSWORD`: the password for the `.p12`
+- `APPLE_API_KEY_ID`: 10-char Key ID (it also names the `.p8` file in the tree)
+- `APPLE_API_ISSUER`: issuer UUID from App Store Connect
+- `APPLE_TEAM_ID`: 10-char team ID from developer.apple.com
 
-1. Drop the relevant cert files into this directory.
-2. Edit `.env` at the repo root and point env vars at them (typically just `CSC_LINK=config/certs/developer-id-application.p12`).
-3. Run `npx omega validate-certs` to check the OS sees them and notarization creds are wired.
-4. `npm run release` to do a signed + notarized build.
+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 full details see [`docs/signing.md`](../../docs/signing.md) at the @omega.js/desktop repo root.
-
-## CI
-
-In CI (GitHub Actions), certs are passed via secrets, not files. The workflow base64-decodes secret values into temp files at runtime, points env vars at them, then nukes the files after the build. See `src/defaults/.github/workflows/build.yml` (when added in Pass 3).
+For the whole picture see [`docs/signing.md`](../../docs/signing.md).