@omega.js/desktop 0.53.0 → 0.54.1

package/docs/signing.md

@@ -1,293 +0,0 @@
-# Code Signing
-
-Cross-platform code signing reference. Covers macOS (sign + notarize), Windows (EV token + cloud), and Linux (no signing required for AppImage/deb but Snap/Flatpak have their own conventions).
-
-## tl;dr
-
-- **macOS production**: Developer ID Application cert + notarization API key. Files in `config/certs/`. Env vars point at them.
-- **Windows production**: EV USB token (self-hosted runner now) or cloud signing (future, pluggable via `platforms.windows.signing.strategy`).
-- **Linux**: No signing for AppImage/deb. Snap/Flatpak have their own pipelines.
-
-## Where files live
-
-Signing material lives in the SIGNING TREE and is read there, never copied into a target
-([#891](https://github.com/Omega-JS-Stack/omega/issues/891)):
-
-```
-<company brand>/company/.omega/certificates/apple/   # read FIRST when the brand names a company
-<your brand>/.omega/certificates/apple/              # read second
-  certificates/DEVELOPER_ID_APPLICATION_G2.p12       # what CSC_LINK resolves to
-  certificates/DEVELOPER_ID_INSTALLER_G2.p12         # only for .pkg builds (rare)
-  AuthKey_XXXXXXXXXX.p8                              # what APPLE_API_KEY resolves to
-
-<your-app>/
-  build/
-    entitlements.mac.plist             # universal, already in @omega.js/desktop defaults
-    icon.icns / icon.ico / icon.png    # per-brand
-  config/certs/                        # gitignored, and EMPTY on a developer machine:
-                                       # only a RUNNER writes here, decoding the pushed secrets
-    README.md                          # the ONE tracked file here (#913): it says the above
-  .env                                 # gitignored, and it carries no signing PATH: only
-                                       # CSC_KEY_PASSWORD and the APPLE_* three
-```
-
-There is no provisioning profile: Developer ID is direct distribution, signed and notarized,
-and needs none.
-
-## Where the macOS certificate comes from (the lookup order)
-
-Every desktop boot (the CLI and gulp alike) derives the signing paths ONCE, at the env load
-([src/utils/load-env.js](../src/utils/load-env.js), over `@omega.js/devkit/signing-env`), so
-the build, `omega validate-certs` and the deploy precheck's secret publish all read the same
-answer. `CSC_LINK` resolves in ONE order:
-
-1. **`CSC_LINK`** in the environment — an explicit answer always wins.
-2. **The COMPANY's tree**, when the brand names a company and that company is on this
-   machine: a brand with a company reuses the company tree first, always
-   ([#677](https://github.com/Omega-JS-Stack/omega/issues/677)). A brand is NEVER physically
-   inside its company folder: membership is its `company: { id }` key, resolved through
-   `@omega.js/config`'s `resolveCompany` (the ecosystem's one company rule), and the
-   certificate is one more relative path through that resolver's `file()`:
-   `<company>/company/.omega/certificates/apple/certificates/DEVELOPER_ID_APPLICATION_G2.p12`.
-3. **The brand's own signing tree**:
-   `<brandRoot>/.omega/certificates/apple/certificates/DEVELOPER_ID_APPLICATION_G2.p12`.
-   `@omega.js/manager`'s certificates service produces the tree
-   ([the manager guide](../../../docs/manager/index.md)).
-4. **The macOS Keychain** — electron-builder's own identity auto-discovery.
-
-`APPLE_API_KEY` follows the same order for `AuthKey_<APPLE_API_KEY_ID>.p8` (an unset id means
-there is no filename to look for). Both derived values are ABSOLUTE paths into the tree.
-
-**Keychain stays the default.** A project with no signing tree resolves to it exactly as
-before. Two further conditions keep a build on the Keychain rather than handing
-electron-builder a file it cannot use: no `CSC_KEY_PASSWORD` in the `.env` cascade, or a
-password that does not OPEN the `.p12` (verified with `openssl pkcs12 -legacy`, retried
-without the flag for LibreSSL — stock macOS openssl — which reads legacy containers but
-rejects the flag; a missing openssl is named as the reason rather than blamed on the
-password). Either case prints one line naming the file and the reason, and leaves the key
-unset rather than failing the build silently.
-
-The password itself never lives in config: `CSC_KEY_PASSWORD` comes from the `.env`
-cascade (the manager's certificates service writes it to the signing root's `.env`),
-and the config validator hard-fails secret-shaped config keys.
-
-## What's universal vs per-brand
-
-**Universal (one set per Apple Developer team / Windows signing identity):**
-- Developer ID Application cert (`.p12`)
-- Developer ID Installer cert (`.p12`) — only if you ship `.pkg`
-- App Store Connect API key (`.p8`)
-- Apple Team ID, Apple ID, app-specific password
-- Windows EV USB token
-
-**Per-brand (per app):**
-- Provisioning profile (`.provisionprofile`) — only required if your app uses entitlements that Apple gates (push notifications, in-app purchase, network extensions, app groups, etc.)
-- Icons (`icon.icns`, `icon.ico`, `icon.png`)
-
-So for ITW Creative Works' multiple Electron apps signed by the same team, you generally drop the **same** `developer-id-application.p12` and `AuthKey_*.p8` into each app's `config/certs/`. The `.env` paths are identical across apps. Provisioning profiles, if needed, are unique per app.
-
-## macOS setup
-
-### 1. Apple Developer prerequisites
-
-You need an Apple Developer Program membership ($99/year). Inside it:
-
-1. **Developer ID Application certificate** — generate at Apple Developer → Certificates → `+` → "Developer ID Application." Download the `.cer`, install in Keychain Access, then export from Keychain as `.p12` with a password.
-2. **App Store Connect API key** (preferred over Apple ID + app-specific password) — generate at App Store Connect → Users and Access → Keys → `+`. Download the `.p8` once (Apple won't show it again). Note the Key ID and Issuer ID shown on the page.
-3. **Team ID** — visible in your Apple Developer membership page.
-
-### 2. Drop files into your project
-
-```bash
-cp ~/Downloads/developer-id-application.p12 config/certs/
-cp ~/Downloads/AuthKey_XXXXXXXXXX.p8        config/certs/
-```
-
-### 3. Wire `.env`
-
-```bash
-CSC_LINK=config/certs/developer-id-application.p12
-CSC_KEY_PASSWORD=<password you set on export>
-
-APPLE_API_KEY=config/certs/AuthKey_XXXXXXXXXX.p8
-APPLE_API_KEY_ID=XXXXXXXXXX             # 10 chars from key filename
-APPLE_API_ISSUER=00000000-0000-...      # UUID from App Store Connect
-
-APPLE_TEAM_ID=XXXXXXXXXX
-```
-
-> **Empty values are safe.** The `.env` template ships these as `CSC_LINK=""` placeholders; @omega.js/desktop deletes empty/whitespace signing vars after loading `.env` (`src/utils/sanitize-signing-env.js`) so they read as *unset*. Without the guard, app-builder-lib only null-checks — `importCertificate('')` resolves `''` to the project root and the build dies with `"<projectRoot> not a file"`. With no `CSC_LINK` at all, electron-builder falls back to Keychain identity auto-discovery (so local `package:quick` builds still sign when an identity is installed).
-
-### 4. Verify
-
-```bash
-npx omega validate-certs
-```
-
-This checks:
-- `CSC_LINK` exists and is readable
-- macOS Keychain has a Developer ID Application identity, and ONLY when `CSC_LINK` names no certificate: electron-builder imports a `CSC_LINK` `.p12` into its own temporary keychain, so the login keychain says nothing about that build
-- API key file exists and `APPLE_API_KEY_ID` + `APPLE_API_ISSUER` are set
-- Team ID matches the cert
-
-The electron-builder floor is 26.16.1 (the package's peer range, installed by ensure-target for any consumer below it): every earlier build hands the `.p12` password to `security set-key-partition-list`, which wants the temporary keychain's own password, and the macos-26 runner image rejects the mismatch (electron-userland/electron-builder#10066, [#891](https://github.com/Omega-JS-Stack/omega/issues/891)).
-
-### 5. Build + notarize
-
-```bash
-npm run release   # signs + notarizes + publishes
-```
-
-@omega.js/desktop's built-in notarize is wired as electron-builder's `afterSign` hook (via `gulp/build-config`) and calls `@electron/notarize` with the API key creds. Consumers can extend it with an optional `hooks/notarize/post.js` for post-notarization work.
-
-## Windows setup
-
-### Self-hosted EV USB token (recommended for v1)
-
-Buy an EV code-signing cert from Sectigo, DigiCert, SSL.com, etc. Get a physical USB token (you can't transfer EV certs).
-
-1. Plug the token into a Windows machine that's registered as a self-hosted GitHub Actions runner labeled `windows`, `self-hosted`, `ev-token`.
-2. Install the token's middleware (SafeNet, etc.) on that machine.
-3. Set `.env` (on the runner):
-   ```
-   # config: { signing: { windows: { strategy: 'self-hosted' } } }
-   WIN_EV_TOKEN_PATH=<cert SHA1 thumbprint, or a path to a .pfx>
-   WIN_CSC_KEY_PASSWORD=<token PIN>
-   ```
-4. The `windows-sign` job in `.github/workflows/build.yml` will route signing to that runner.
-
-Setting the box up is [`docs/runner.md`](runner.md) — the runner home, the Startup-folder auto-start, the commands, and the Session 0 / Session 1 rule that makes the whole thing work.
-
-**A workflow that targets this runner fires only on dispatch**, and the box enforces it ([#875](https://github.com/Omega-JS-Stack/omega/issues/875)). Whoever can start a job on the signing box can sign binaries with your token, so two guards stand between a stray trigger and `signtool`:
-
-- The generated `windows-sign` job runs only on `workflow_dispatch`, the one trigger the file carries (#923). A `push` or `pull_request` trigger added to `build.yml` later SKIPS the sign job instead of signing what it built.
-- The runner itself refuses the job before its first step. `npx omega runner install` writes `job-started.js` beside the runner and points every registration's `ACTIONS_RUNNER_HOOK_JOB_STARTED` at it; the hook exits nonzero, failing the job with one line, unless the event is a dispatch, `GITHUB_REPOSITORY` is on `allowed-repos.txt` and `GITHUB_ACTOR` is on `allowed-actors.txt`. Both lists live on the box and are yours to edit ([`docs/runner.md`](runner.md) § One-time setup).
-
-`npx omega sign-windows` is the strategy-aware command that drives `signtool` (or the cloud provider CLI).
-
-Every signed artifact is verified before the job moves on, and the log says so in the mac lane's shape: `Signed and verified: signtool verify /pa accepts <file>.` mirrors macOS's `Stapled and verified: ...`, so a deploy log proves the Windows signature was checked rather than only claimed ([#918](https://github.com/Omega-JS-Stack/omega/issues/918)). A failing verify aborts the job.
-
-### Cloud signing (future migration)
-
-Once the framework's cloud strategy is finalized, set the provider in `config/omega.json5`:
-```
-# config: { targets: { win: { signing: { strategy: 'cloud', cloud: { provider: 'azure' } } } } }
-# provider: 'azure' | 'sslcom' | 'digicert'
-# Provider-specific creds (secrets) live in .env Custom Values section.
-```
-
-Provider modules will live in `src/lib/sign-providers/{azure,sslcom,digicert}.js` (Pass 3 work).
-
-### Local (developer-machine) fallback
-
-If no signing runner is available, CI uploads the unsigned `.exe` and a developer manually signs locally:
-```
-# config: { signing: { windows: { strategy: 'local' } } }
-```
-
-## Pushing secrets to GitHub Actions
-
-`omega deploy`'s precheck pushes the target's **composed env** to the repo's GitHub Actions secrets over the same shared `gh` transport the other three frameworks use (`gh secret set`, which seals each value with the repo's public key locally): values travel on **stdin**, never in argv, and are never logged. For env vars whose value is a path to a local file (`.p12`, `.p8`, etc.), the secret value pushed is the **base64-encoded file contents**: the workflow decodes back to a temp file at job start.
-
-There is no standalone `omega push-secrets` verb ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)): the push happens where it matters, and the manage walk's `repo` service runs the same function when you want a brand brought current without deploying.
-
-```bash
-# Make sure the brand root's .env holds CSC_KEY_PASSWORD + the APPLE_* three, and `gh auth login` has run
-npx omega deploy
-
-# See exactly what it would publish, and publish nothing
-npx omega deploy --dry-run
-```
-
-Behavior:
-- The source is `composeTargetEnv({ targetDir, target: 'desktop' })`: company `.env` ← brand `.env` ← target `.env`, the brand-side layers filtered by the env schema to the keys the desktop target reads. The brand root's `.env` is the one file you keep; a target `.env` is an optional per-key override.
-- Files only — the shell is never a source — and an empty value never claims a key, so unset keys simply don't publish.
-- Auto-detects "is this a path?" — relative or absolute paths ending in `.p12`/`.pem`/`.cer`/`.p8`/`.provisionprofile`/`.crt`/`.key`/`.json` that exist on disk (target root first, brand root second) get base64-encoded.
-- Publishes to the brand's SOURCE repo (`repo.org` + `brand.id` → `<brand.id>-omega`), and REFUSES unless the checkout's own remote IS that repo: a fork, a template clone or a vendored target never arms a stranger's Actions with your certificates.
-- No PAT: the credential is `gh`'s auth session. A missing or signed-out `gh` fails loudly with install/auth instructions; a CI run, an empty cascade or a remote-less checkout skips loudly, and a checkout whose `origin` is not the derived source repo refuses on the one drift line (`origin is <slug> but config derives <derived>: ...`, [#934](https://github.com/Omega-JS-Stack/omega/issues/934)).
-- `CSC_LINK` and `APPLE_API_KEY` are DERIVED, never typed ([#891](https://github.com/Omega-JS-Stack/omega/issues/891)): the env load resolved them from the signing tree, so the publish sends those files' bytes. A typed value still wins, and a key the config REQUIRES that neither the tree nor the `.env` answers STOPS the deploy (the step is `fatal`), naming both tier paths it looked in and `omega manage --service certificates`, publishing nothing.
-- Logs key NAMES only; never a value.
-
-The corresponding decode step in CI looks like:
-
-```yaml
-- name: Decode signing assets
-  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
-  env:
-    CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
-    APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
-    APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
-    APPLE_TEAM_ID:    ${{ secrets.APPLE_TEAM_ID }}
-- name: Build and release
-  run: npm run release
-  env:
-    CSC_LINK:         config/certs/dev-id.p12
-    APPLE_API_KEY:    config/certs/AuthKey.p8
-    GH_TOKEN:         ${{ secrets.GH_TOKEN }}
-```
-
-This is wired up automatically in the `.github/workflows/build.yml` template (lands in Pass 3).
-
-## CI integration
-
-GitHub Actions secrets you'll need (per repo):
-
-| Secret | Purpose |
-|---|---|
-| `GH_TOKEN` | Cross-repo publish, secret rotation |
-| `CSC_LINK` | base64-encoded `.p12` (workflow decodes to file) |
-| `CSC_KEY_PASSWORD` | `.p12` password |
-| `APPLE_API_KEY` | base64-encoded `.p8` |
-| `APPLE_API_KEY_ID` | Plain string |
-| `APPLE_API_ISSUER` | UUID |
-| `APPLE_TEAM_ID` | 10-char team ID |
-| `WIN_EV_TOKEN_PATH` | Windows EV cert reference — SHA1 thumbprint or `.pfx` path (the ONE name; the `WIN_CSC_LINK` alias is gone) |
-| `WIN_CSC_KEY_PASSWORD` | EV token PIN / `.pfx` password |
-| `SIGNTOOL_PATH` | Full path to `signtool.exe` on the signing runner |
-
-The workflow base64-decodes secrets into temp files inside `config/certs/` at job start, runs the build, and the runner's ephemeral filesystem cleans up afterward. Local `.env` files are never committed and never shipped.
-
-## Troubleshooting
-
-### "Could not find a certificate" on macOS
-- Run `security find-identity -v -p codesigning` — you should see "Developer ID Application: <your name> (TEAMID)".
-- If absent: re-import your `.p12` to Keychain Access and make sure the private key is included.
-
-### Notarization timeout
-- Confirm `APPLE_API_KEY` is the absolute path (or relative to repo root) and the file is readable.
-- Confirm `APPLE_API_KEY_ID` matches the `XXXXXXXXXX` portion of the `AuthKey_XXXXXXXXXX.p8` filename.
-- Confirm `APPLE_API_ISSUER` is the issuer UUID from App Store Connect → Users and Access → Keys.
-
-### "Hardened runtime requires entitlements"
-- @omega.js/desktop generates `dist/config/entitlements.mac.plist` from defaults + your overrides at build time.
-- Defaults cover Electron's needs (allow-jit, network client/server, library validation off, etc.).
-- To override or add: set the `entitlements.mac` block in `config/omega.json5`. Setting a key to `null` removes a default.
-  ```json5
-  entitlements: {
-    mac: {
-      'com.apple.security.cs.allow-jit': false,           // override default
-      'com.apple.security.device.camera': true,           // add a key
-      'com.apple.security.network.server': null,          // remove a default
-    },
-  }
-  ```
-
-### Windows: "SignTool Error: No certificates were found"
-- Token unplugged or middleware not running.
-- For cloud: verify `platforms.windows.signing.cloud.provider` in `config/omega.json5` matches the provider whose creds are in `.env`.
-
-## What lives in `build/`
-
-`build/` in a consumer project holds **only** code-signing certificate files. Everything else (entitlements, icons, electron-builder config) is generated by @omega.js/desktop into `dist/config/` at build time.
-
-- **`config/certs/`** — `.p12`, `.p8`, `.cer`, `.mobileprovision` files. Per-developer / per-CI-runner. **Never commit** — `.gitignore` blocks them.
-- **Nothing else.** `entitlements.mac.plist` is generated. App icons + DMG background + tray icons resolve from `config/icons/` (consumer override) → @omega.js/desktop's bundled defaults. `electron-builder.yml` is generated.
-
-The only file you usually create yourself in `build/` is the cert files in `config/certs/`. See [`config/certs/README.md`](../src/defaults/config/certs/README.md) for the full inventory.
-
-## Related docs
-
-- [`config/certs/README.md`](../src/defaults/config/certs/README.md) — cert file inventory

package/docs/startup.md

@@ -1,142 +0,0 @@
-# Startup
-
-Controls how the app launches: full normal launch vs completely hidden background app. Also handles open-at-login.
-
-## Config
-
-```jsonc
-"startup": {
-  "mode": "normal",                // user-launch behavior: 'normal' | 'hidden'
-  "openAtLogin": {
-    "enabled": true,               // OS auto-launches the app at login
-    "mode":    "hidden"            // login-launch behavior (defaults to 'hidden')
-  }
-}
-```
-
-`mode` is what happens when **the user launches the app directly** (clicks the dock icon / Start menu / etc.).
-
-`openAtLogin.mode` is what happens when **the OS auto-launches the app at login**. It applies *only* when the launch is detected as a login-launch (macOS: `wasOpenedAtLogin` flag; Windows/Linux: presence of the `--omega-launched-at-login` arg @omega.js/desktop passes when registering the login item).
-
-The default behavior — `mode: 'normal'` + `openAtLogin: { enabled: true, mode: 'hidden' }` — means: the app auto-starts at login but stays out of the way until the user opens it themselves. User-direct launches show the main window like any normal app.
-
-## Modes
-
-### `normal` (default)
-
-Standard app behavior. Your `main.js` calls `windows.create('main', { show: !startup.isLaunchHidden() })` from inside `omega.initialize().then(...)`. In `normal` mode, `show` is `true` so the window appears immediately. Dock visible (macOS), taskbar entry (win/linux).
-
-### `hidden`
-
-App launches **completely invisible**: no dock icon, no Cmd+Tab presence, no taskbar entry. Tray + notifications + networking + IPC + auto-update all still work — only the visible UI is suppressed. Production builds inject `LSUIElement: true` into `Info.plist` (via `gulp/build-config`) so macOS treats the process as a background agent from launch — **zero dock bounce**.
-
-The `main` window is still created (just with `show: false`) so it sits in @omega.js/desktop's window registry. When the user double-clicks the running app's icon, @omega.js/desktop's `app.on('activate')` (macOS) / `app.on('second-instance')` (win/linux) handler finds `main` in the registry and calls `windows.show('main')` — which auto-runs `app.dock.show()` so the dock icon appears alongside the window. Same thing happens when the consumer manually surfaces UI from a tray click / deep-link / IPC event via `windows.show('main')`. The reverse is automatic too: hiding the last visible window (including the hide-on-close X) re-runs `app.dock.hide()`, so a hidden-mode app never strands a dock icon after its UI is dismissed.
-
-Use this for: menubar apps, agent apps (clipboard managers, time trackers, system monitors), apps that should be invisible at boot but available on demand.
-
-**Dev caveat**: in dev (`npm start` / `electron .`), the packaged `Info.plist` isn't in effect, so macOS will still briefly bounce. Production builds (`npm run build` / `npm run release`) get the real zero-bounce behavior.
-
-> **Note:** the deprecated `'tray-only'` mode is no longer valid — its behavior was always identical to `'hidden'`, so they've been folded into one. Old `tray-only` configs fall back to `'normal'` per `getMode()` validation.
-
-## Public API on `omega.startup`
-
-```js
-omega.startup.getMode()                  // user-launch mode: 'normal' | 'hidden'
-omega.startup.isLaunchHidden()           // true if THIS launch is hidden: combines
-                                           //   user-launch mode + login-launch detection.
-                                           //   Use this in main.js to gate windows.create().
-omega.startup.wasLaunchedAtLogin()       // true if the OS auto-launched us at login
-omega.startup.applyEarly()               // calls app.dock.hide() if needed (called by main.js boot)
-
-omega.startup.setOpenAtLogin(true)                            // back-compat boolean form
-omega.startup.setOpenAtLogin({ enabled: true, mode: 'hidden' }) // object form
-omega.startup.isOpenAtLogin()            // read live OS state
-```
-
-## Typical main.js pattern
-
-```js
-omega.initialize().then(() => {
-  // Always create the main window. In hidden launches, `show: false` keeps it
-  // invisible until something explicitly calls windows.show('main') — but it's
-  // in the registry, so @omega.js/desktop's activate/second-instance handlers can find and
-  // surface it when the user double-clicks the running app.
-  omega.windows.create('main', {
-    show: !omega.startup.isLaunchHidden(),
-  });
-});
-```
-
-Don't conditionally skip `create()` for hidden launches — without `main` in the registry, the dock-click / re-launch handlers have nothing to surface, and the user double-clicking the running app appears to do nothing.
-
-## Boot order
-
-`startup.applyEarly()` is the **first** call in `omega.initialize()`: before `whenReady`, before any other lib. The goal: spend as little time as possible in the dock-bounce window.
-
-Sequence: applyEarly → before-quit hook → ipc → storage → theme → fontawesome → sentry → protocol → deep-link → auth-flow → app-state → context → usage → whenReady → updater → tray/menu/contextMenu → startup.initialize → auth → remote-config → remote-scripts → analytics → restart-manager → windows.initialize (full list: [boot-sequence.md](boot-sequence.md)). **@omega.js/desktop does not auto-create the main window**: your `main.js` does that inside the `.then()` callback after `initialize()` resolves.
-
-## How zero-bounce works on macOS
-
-`LSUIElement` is an `Info.plist` key that tells macOS *before launch* "this app is a background agent — don't put it in the dock or app switcher." Setting it at runtime (`app.dock.hide()`) is too late — by the time JS runs, the dock-bounce animation has already started.
-
-@omega.js/desktop handles this at build time:
-1. `gulp/build-config` reads `config/omega.json5`.
-2. If `startup.mode === 'hidden'` **or** `startup.openAtLogin.mode === 'hidden'`, it injects `mac.extendInfo.LSUIElement: true` into the materialized `dist/electron-builder.yml`. (The openAtLogin case matters for `mode: 'normal'` apps that launch hidden at login — without the plist key, the login launch flashes the dock before `applyEarly()`'s `dock.hide()` can run.)
-3. `electron-builder` packages the app with that key in the final `Info.plist`.
-
-With the key baked, a MANUAL launch also starts dockless — the dock icon appears the moment the main window surfaces (every surface path runs `_ensureDockVisible()` → `app.dock.show()`), so the visible difference is only that the bounce animation is replaced by the icon appearing when the window is ready.
-
-At runtime, when the consumer first calls `omega.windows.show()` (or the `windows.create()` call resolves with `show: true`), @omega.js/desktop calls `app.dock.show()` so the dock icon appears alongside the window. Reverses cleanly via `app.dock.hide()` if you want to go back to invisible.
-
-The injection is YAML-text-level (preserves comments, idempotent, merges with existing `extendInfo`). See `src/gulp/tasks/build-config.js`.
-
-## Re-surfacing on user re-launch
-
-When the user double-clicks a running hidden-mode app (or clicks its dock icon on macOS), @omega.js/desktop transparently surfaces the main window — no consumer wiring needed. Mechanisms:
-
-- **macOS**: `window-manager.initialize()` registers `app.on('activate')` which calls `windows.show('main')` if `main` is in the registry.
-- **Windows / Linux**: `deep-link.initialize()` registers `app.on('second-instance')` which does the same. (The OS spawns a duplicate process, the single-instance lock kills it, and forwards its argv to the original instance.)
-
-Both handlers are no-ops if `main` isn't in the registry, so consumers who genuinely never want a window can omit `windows.create('main', ...)` entirely. Otherwise, with the canonical pattern (`windows.create('main', { show: !isLaunchHidden() })`), hidden-mode apps come back to life on a second click — like CleanMyMac, Rectangle, etc.
-
-## Testing the login-launch path locally
-
-Pass `--omega-launched-at-login` as a command-line arg when launching the .app; @omega.js/desktop treats it identically to a real OS-driven login launch (`startup.wasLaunchedAtLogin()` returns `true`, with `via:argv-flag` in the boot summary log). Useful for testing hidden-mode behavior without configuring login items + rebooting.
-
-The easiest way is `mgr launch`, which auto-strips `ELECTRON_RUN_AS_NODE` and uses `open -n` under the hood:
-
-```bash
-# Auto-discover the most recent `mgr package:quick` build:
-npx omega launch --args="--omega-launched-at-login"
-
-# Or pass an explicit path:
-npx omega launch /Applications/MyApp.app --args="--omega-launched-at-login"
-```
-
-If you'd rather call `open` directly, remember to strip `ELECTRON_RUN_AS_NODE` first (the variable leaks into shells from common host processes like VS Code's Claude Code extension and silently breaks Electron):
-
-```bash
-unset ELECTRON_RUN_AS_NODE
-open -n /path/to/MyApp.app --args --omega-launched-at-login
-
-# Windows / Linux — direct binary launch
-"/path/to/MyApp.exe" --omega-launched-at-login
-```
-
-The boot summary log written by the `startup` lib distinguishes a real login launch (`via:macos-wasOpenedAtLogin`) from a flag-based simulation (`via:argv-flag`).
-
-## Pairing with tray/window patterns
-
-Hidden / agent apps usually want:
-
-```jsonc
-"startup": { "mode": "hidden" }
-```
-
-And in `src/integrations/tray/index.js`:
-
-```js
-tray.update('open', { click: () => omega.windows.show('main') });
-```
-
-The window is created at boot but invisible. When the user clicks the tray's "Open" item (or double-clicks the app icon), `windows.show('main')` runs, @omega.js/desktop calls `app.dock.show()`, and the user sees both the dock icon and the window appear together.

package/docs/storage.md

@@ -1,59 +0,0 @@
-# Storage
-
-Persistent KV store accessible from both main and renderer. Backed by [`electron-store`](https://github.com/sindresorhus/electron-store) under the hood.
-
-## File location
-
-```
-macOS:   ~/Library/Application Support/<productName>/omega-storage.json
-Windows: %APPDATA%/<productName>/omega-storage.json
-Linux:   ~/.config/<productName>/omega-storage.json
-```
-
-## Main-process API (sync, direct disk-backed)
-
-```js
-omega.storage.get(key, defaultValue)   // any
-omega.storage.set(key, value)
-omega.storage.delete(key)
-omega.storage.has(key)                 // boolean
-omega.storage.clear()
-omega.storage.onChange(key, fn)        // returns unsubscribe fn
-omega.storage.getPath()                // absolute path to omega-storage.json
-```
-
-## Renderer-process API (async, proxied through preload + IPC)
-
-```js
-await window.desktop.storage.get(key, defaultValue)
-await window.desktop.storage.set(key, value)
-await window.desktop.storage.delete(key)
-await window.desktop.storage.has(key)
-await window.desktop.storage.clear()
-
-const off = window.desktop.storage.onChange(key, ({ value, previous }) => { ... });
-// pass '*' as key to receive all changes
-off();
-```
-
-## Dot-notation paths
-
-Keys support dot-notation for nested objects natively:
-
-```js
-omega.storage.set('window.main.bounds', { x: 10, y: 20, w: 800, h: 600 });
-omega.storage.get('window.main.bounds.w');   // → 800
-```
-
-## Change broadcasts
-
-Every `set` / `delete` / `clear` in main broadcasts an `desktop:storage:change` IPC event to all renderer windows. The renderer's `window.desktop.storage.onChange` filters by key locally.
-
-In main, `omega.storage.onChange(key, fn)` registers a callback fired with `(value, previous)`.
-
-## Implementation notes
-
-- Storage initialization is async: `omega.initialize()` `await`s it before any other lib boots, since features like `app-state` and `windows` rely on it.
-- IPC handlers (`desktop:storage:get` etc.) are registered on the @omega.js/desktop `ipc` bus, not directly on `ipcMain`. See [ipc.md](ipc.md).
-- The store uses `name: 'omega-storage'` (filename `omega-storage.json`). Don't reuse this name in a separate `electron-store` instance.
-- `electron-store@11` is ESM-only. The bundler inlines it INTO `main.bundle.js` (the static-specifier `import()` in `lib/storage.js`) — consumers install NOTHING; packaged apps carry it inside the bundle with no runtime resolution. (It used to be a runtime import the bundler was told to ignore, which silently no-op'd storage in packaged consumers — @omega.js/desktop is a devDependency and never ships in the asar.)

package/docs/templating.md

@@ -1,101 +0,0 @@
-# Templating
-
-Light token-replacement engine for HTML pages. Uses `{{ var }}` syntax, dot-notation paths, brand/app values from config.
-
-## How it works
-
-1. Consumer authors `src/views/<name>/index.html` as the **body** of the page (no `<html>`, `<head>`, `<body>` tags).
-2. @omega.js/desktop ships a default page template at `<em>/dist/config/page-template.html`. Consumers can override with their own at `<consumer>/config/page-template.html` if they want to.
-3. At build time, `gulp/html`:
-   - Reads each `src/views/<name>/index.html`
-   - Templates its body with the page vars (so the body can use `{{ brand.name }}` etc.)
-   - Injects the rendered body into the page template's `{{ content }}` slot
-   - Writes the final HTML to `dist/views/<name>/index.html`
-4. The page template auto-includes:
-   - `assets/css/main.bundle.css` (compiled from `src/assets/scss/main.scss` by gulp/sass) — present on every page
-   - `assets/js/components/<page.name>.bundle.js` (per-view renderer bundle) — only the JS for this page
-
-## Page name
-
-`page.name` is derived from the view's path under `src/views/`:
-- `src/views/main/index.html`        → `page.name = 'main'`
-- `src/views/settings/index.html`    → `page.name = 'settings'`
-- `src/views/blog/post.html`         → `page.name = 'blog/post'`
-
-This naming lines up with the renderer bundle's entry naming so the JS bundle path resolves correctly.
-
-## Page template variables
-
-| Var | Source | Example |
-|---|---|---|
-| `{{ brand.id }}`, `{{ brand.name }}`, `{{ brand.url }}` | `config.brand.*` | `myapp` / `MyApp` |
-| `{{ app.productName }}`, `{{ app.appId }}`, `{{ app.copyright }}` | `config.app.*` | `MyApp` / `com.itwcw.myapp` |
-| `{{ page.name }}` | derived from view path | `main` / `settings` |
-| `{{ page.title }}` | `extras.title` (in gulp/html) or `app.productName` | `MyApp` |
-| `{{ theme.appearance }}` | `config.theme.appearance` (default `'system'`) | `light` / `dark` / `system` — runtime applier replaces with the resolved value ([themes.md](themes.md)) |
-| `{{ cacheBust }}` | build timestamp | `1777515223640` |
-| `{{ content }}` | rendered body (set by gulp/html) | `<main>...</main>` |
-
-## Default page template
-
-```html
-<!doctype html>
-<html data-bs-theme="{{ theme.appearance }}">
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width,initial-scale=1">
-    <title>{{ page.title }}</title>
-    <link href="../../assets/css/main.bundle.css?cb={{ cacheBust }}" rel="stylesheet">
-  </head>
-  <body>
-    {{ content }}
-    <script src="../../assets/js/components/{{ page.name }}.bundle.js?cb={{ cacheBust }}"></script>
-  </body>
-</html>
-```
-
-## Overriding the page template
-
-Drop your own `config/page-template.html` in your project root. @omega.js/desktop picks it up before falling back to its own default.
-
-```html
-<!-- consumer/config/page-template.html -->
-<!doctype html>
-<html data-bs-theme="{{ theme.appearance }}" lang="en">
-  <head>
-    <meta charset="utf-8">
-    <title>{{ page.title }} | {{ brand.name }}</title>
-    <link href="../../assets/css/main.bundle.css?cb={{ cacheBust }}" rel="stylesheet">
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700" rel="stylesheet">
-  </head>
-  <body class="custom-shell">
-    {{ content }}
-    <script src="../../assets/js/components/{{ page.name }}.bundle.js?cb={{ cacheBust }}"></script>
-  </body>
-</html>
-```
-
-## Runtime API
-
-`omega.templating` is also available at runtime if you need to template a string yourself (e.g. dynamic deep-link routes):
-
-```js
-omega.templating.render('Hello {{ user.name }}', { user: { name: 'Ian' } });
-// → 'Hello Ian'
-
-omega.templating.render('Custom [name]', { name: 'X' }, { brackets: ['[', ']'] });
-// → 'Custom X'
-```
-
-## Future
-
-The current page template hardcodes the asset paths. A future pass adds:
-- Per-page CSS bundles (currently only one shared `main.bundle.css`)
-- Source map references in dev mode
-- Inline critical CSS for fast first paint
-
-For theme-related styling (Bootstrap, classy theme), see [docs/themes.md](themes.md) when that pass lands.
-
-## Tests
-
-`src/test/suites/build/templating.test.js` — render, dot-notation, custom brackets, buildPageVars, renderPage end-to-end. 8 tests.