ADR 0296: Signed macOS DMG is a two-icon install

• Status: Accepted
• Date: 2026-09-19
• Deciders: PI-Desktop release maintainers
• Amends: ADR 0232, ADR 0204
• Related: D457, D450 / ADR 0289, E2E-196b, E2E-196c

Context

Official GitHub Release DMGs are Developer ID-signed and notarized (ADR 0289). The DMG still showed If app won't open, read this.txt from ADR 0232, which was the unsigned first-launch fallback. That note is no longer the install path for tagged builds and made the installer look like an error dialog.

Decision

1. The macOS DMG contains only PI-Desktop.app and the Applications link, on a branded 720×440 dark plate with 128px icons. It does not include the opening-help note or PI-Desktop-macOS-open.command.
2. The macOS ZIP package still ships both PI-Desktop-macOS-opening-help.txt and the executable helper at its root, for trusted unsigned local or debug artifacts. Helper bounds from ADR 0204 are unchanged.
3. The DMG artwork is generated by scripts/make-dmg-background.py from the canonical app icon. Do not hand-edit the PNG pair.

Consequences

• A tagged DMG is a single drag-to-Applications gesture.
• Unsigned local DMGs no longer carry the in-volume note; use the ZIP helper or the documented xattr command.
• Finder still localizes the Applications alias; the plate caption is English plus a quiet Chinese line.

Verification

apps/desktop/test/packaging-footprint.test.mjs asserts the two-icon DMG contents, 720×440 / 1440×880 backgrounds, and retained ZIP helper assets. E2E-196b covers native archive inspection on macOS.