docs(REV-007): unsigned per-arch distribution + install guide; defer universal

Signing is not required to ship a testable build. Documents the v0 plan:
unsigned, per-arch macOS builds (arm64 + x64) plus Windows/Linux, with clear
end-user "open it anyway" instructions per OS.

- New dev-docs/guidelines/INSTALLING-UNSIGNED-BUILDS.md: Gatekeeper (xattr /
  right-click), Windows SmartScreen (More info → Run anyway), Linux AppImage
  (chmod +x, FUSE / --appimage-extract-and-run). Written for end users; copy
  into the GitHub Release notes.
- A single-file macOS `--universal` build was evaluated and DEFERRED: proven
  locally that @electron/universal refuses to ship the single-arch native
  binaries (desktop-trampoline, dugite's git) our one-npm-install-per-arch
  pipeline produces. Per-arch is correct and ready; universal needs per-arch
  native merging, a later CI change. build.ts documents this; the universal
  wiring was reverted rather than left half-built.
- RELEASE-PROCESS.md: unsigned distribution is fully supported (§ top);
  reframed the latest-mac.yml limitation as moot-until-signed (macOS
  auto-update requires a signed app).

Verified: typecheck:editor clean; the arm64 per-arch packaging path is the same
one already proven green (NodeGX-0.1.0-mac-arm64.{dmg,zip}); x64 builds natively
on the macos-13 release runner.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: richardosborne14

dev-docs/guidelines/INSTALLING-UNSIGNED-BUILDS.md

@@ -0,0 +1,100 @@
+# Installing NodeGX (unsigned builds)
+
+NodeGX v0 is **not code-signed** — there is no paid Apple/Windows signing
+certificate yet. The app is safe, but because it is unsigned each operating
+system will warn you and make you take one deliberate step to open it the first
+time. After that first launch it opens normally.
+
+> This page is written for end users. Copy it into the GitHub Release
+> description so anyone downloading a build knows how to open it. Maintainers:
+> the signing story is in [RELEASE-PROCESS.md](./RELEASE-PROCESS.md).
+
+---
+
+## macOS
+
+**Download:** `NodeGX-<version>-mac-universal.dmg` — one file, runs on both Apple
+Silicon (M1/M2/M3/M4) and Intel Macs.
+
+1. Open the `.dmg` and drag **NodeGX** into **Applications**.
+2. The first time you open it, macOS will say NodeGX *"cannot be opened because
+   Apple cannot check it for malicious software"* (or *"is damaged"* on the
+   newest macOS). This is the unsigned warning, not a real problem.
+
+**Easiest fix — Terminal (works on every macOS version):**
+
+```bash
+xattr -dr com.apple.quarantine /Applications/NodeGX.app
+```
+
+Then open NodeGX normally from Applications.
+
+**Alternative — no Terminal (macOS 14 and earlier):**
+
+- Right-click (or Control-click) **NodeGX** in Applications → **Open** →
+  **Open** again in the dialog. macOS remembers the choice.
+- Or: try to open it once, then go to **System Settings → Privacy & Security**,
+  scroll down, and click **Open Anyway**.
+
+> On macOS 15 (Sequoia) Apple removed the right-click bypass for unsigned apps,
+> so the `xattr` command above is the reliable route there.
+
+---
+
+## Windows
+
+**Download:** `NodeGX-<version>-win-x64.exe`.
+
+1. Run the installer. Windows **SmartScreen** shows *"Windows protected your
+   PC"*.
+2. Click **More info**, then **Run anyway**.
+
+That's it — the app installs and opens normally afterwards.
+
+> This warning appears because the installer is unsigned (and, once signed, will
+> still appear for a while until the certificate builds "reputation" through
+> downloads). It is expected for a new app, not a sign of a problem.
+
+---
+
+## Linux
+
+**Download:** `NodeGX-<version>-linux-x86_64.AppImage` (portable, no install) or
+the `.deb` (Debian/Ubuntu).
+
+### AppImage
+
+```bash
+chmod +x NodeGX-*-linux-x86_64.AppImage
+./NodeGX-*-linux-x86_64.AppImage
+```
+
+If it complains about **FUSE**, either install it once:
+
+```bash
+sudo apt install libfuse2      # Debian/Ubuntu
+```
+
+…or run without FUSE:
+
+```bash
+./NodeGX-*-linux-x86_64.AppImage --appimage-extract-and-run
+```
+
+### .deb (Debian / Ubuntu)
+
+```bash
+sudo apt install ./NodeGX-*-linux-amd64.deb
+```
+
+Then launch **NodeGX** from your applications menu.
+
+---
+
+## Is this safe?
+
+Yes. "Unsigned" only means the project has not (yet) paid for the certificates
+that let Apple and Microsoft pre-verify the publisher. The warnings are the OS
+being cautious about *any* unsigned app. If you would rather verify the download
+yourself, each release lists SHA-512 checksums (in `latest*.yml`) you can check
+against your downloaded file.

dev-docs/guidelines/RELEASE-PROCESS.md

@@ -9,8 +9,13 @@ How to cut, verify, publish, and roll back a signed NodeGX release.
 > code-signing certificate, and the CI secrets built from them. Until a human
 > completes [§1](#1-one-time-credential-setup-human-required), releases produced
 > by CI are **unsigned** (they still build and publish as drafts, but macOS
-> Gatekeeper will warn and Windows SmartScreen will block). Nothing ships to
-> users until someone provisions credentials and publishes a draft.
+> Gatekeeper will warn and Windows SmartScreen will block).
+>
+> **Distributing unsigned test builds is fully supported** in the meantime —
+> that is the current v0 plan. Point testers at
+> [INSTALLING-UNSIGNED-BUILDS.md](./INSTALLING-UNSIGNED-BUILDS.md) (copy it into
+> the GitHub Release notes) for the one-step "open it anyway" instructions per
+> OS. Signing just removes that friction; it is not required to ship.
 
 ---
 
@@ -193,14 +198,21 @@ If a bad release has been published:
 
 These are documented deliberately rather than silently shipped:
 
-- **macOS multi-arch auto-update feed.** The matrix builds `darwin-arm64` and
-  `darwin-x64` as separate jobs, and each writes `latest-mac.yml`. The second to
-  finish overwrites the first, so the published `latest-mac.yml` points at only
-  one arch's `.zip`. This is **harmless for the very first release** (no client
-  is auto-updating yet) but **must be fixed before the second release**, or half
-  of macOS users will be offered the wrong-arch update. The fix is a single
-  **universal** macOS build (`--universal`) or arch-scoped update channels.
-  Tracked as a follow-up; do not publish a v0.1.1 to mac users until it is done.
+- **macOS ships as per-arch builds** (`darwin-arm64` for Apple Silicon,
+  `darwin-x64` for Intel), each fully functional — the standard "which Mac do
+  you have?" download split. A single-file **universal** build was evaluated and
+  **deferred**: `@electron/universal` correctly refuses to ship the bundled
+  single-arch native binaries (`desktop-trampoline`, `dugite`'s `git`) in a
+  universal app, so a real universal build needs each arch's natives built
+  separately and lipo-merged — a CI change worth doing later, not required for
+  distribution now.
+- **macOS multi-arch auto-update feed (future, signed phase only).** Once
+  signing + auto-update are live, the two mac jobs each write `latest-mac.yml`
+  and the later one wins, so the feed would point at one arch. This is **moot
+  today** — macOS auto-update (Squirrel.Mac) requires a *signed* app, so
+  auto-update does not run at all in the current unsigned phase. It becomes a
+  must-fix the moment an Apple Developer ID is added: resolve it then with a
+  universal build or arch-scoped update channels.
 - **Signing is credential-gated, not verified end-to-end.** No Apple/Windows
   certificates exist yet, so the signed/notarised path has never actually run.
   The hooks are wired and will engage the moment the secrets in §1 are present,

dev-docs/tasks/phase-12-reanimation/REV-007-SHIP-V0.md

@@ -36,7 +36,9 @@
 - ⬜ Auto-update end-to-end across two *published* releases.
 - ⬜ Cut & publish v0.1.0 publicly (draft workflow is ready; a human confirms the draft).
 
-**Known limitation flagged, not silently shipped:** the mac matrix builds arm64 and x64 as separate jobs that each overwrite `latest-mac.yml`, so the published feed points at one arch. Harmless for the *first* release (nobody is auto-updating yet) but **must be fixed before v0.1.1** (universal build). See `RELEASE-PROCESS.md` §6.
+**Unsigned distribution (current v0 plan).** Signing is *not* required to ship a testable build — it only removes the OS warning. macOS ships as **per-arch** builds (arm64 + x64), each fully functional; a single-file universal build was evaluated and deferred (`@electron/universal` refuses to ship the single-arch native binaries `desktop-trampoline`/`dugite` produced by the one-`npm install`-per-arch pipeline — proven by a local build attempt). End-user "open it anyway" instructions for all three OSes are in [`INSTALLING-UNSIGNED-BUILDS.md`](../../guidelines/INSTALLING-UNSIGNED-BUILDS.md), meant to be copied into the GitHub Release notes.
+
+**Known limitation flagged, not silently shipped:** the mac arm64/x64 jobs each overwrite `latest-mac.yml`. This is **moot while unsigned** — macOS auto-update (Squirrel.Mac) requires a signed app, so it does not run at all yet — but becomes a must-fix the moment an Apple Developer ID is added. See `RELEASE-PROCESS.md` §6.
 
 ---
 

packages/noodl-editor/scripts/build.ts

@@ -48,6 +48,12 @@ import { BuildTarget, getDistPlatform } from './platform/build-platforms';
   const PUBLISH_RELEASE = valueToBoolean(process.env.PUBLISH_RELEASE);
   const publishArg = PUBLISH_RELEASE ? '--publish onTagOrDraft' : '--publish never';
 
+  // Per-arch macOS builds (arm64 / x64), each fully functional. A single-file
+  // `--universal` build was evaluated and deferred: it needs the bundled native
+  // binaries (desktop-trampoline, dugite's git) built for both arches and
+  // lipo-merged, which this one-`npm install`-per-arch pipeline does not
+  // produce — @electron/universal correctly refuses to ship single-arch natives
+  // in a universal app. See dev-docs/guidelines/RELEASE-PROCESS.md §6.
   const args = [`--${platformName}`, `--${target.arch}`, publishArg].join(' ');
 
   // Signing: