fix(macos-pkg): product ID, Verae branding, license Agree in installer

The product .pkg was a bare component wrapper with no Installer.app UI. - Distribution.xml.in: title Verae Print Stamp, org ai.verae, product id - resources: welcome/license/readme/conclusion HTML + plum brand backgrounds - license.html requires Agree/Disagree before install continues - readme.html product identification table (bundle/pkg IDs, version, publisher) - App bundle: AppIcon.icns, VeraeProductID/VeraeBrand keys, PRODUCT.txt sidecar - build-pkg.sh uses productbuild --distribution --resources - SKIP_SIGN=1 for local UI smoke; smoke-installer-ui.sh (15 checks) Verify: SKIP_SIGN=1 ./platform/macos/pkg/build-pkg.sh ./platform/macos/pkg/smoke-installer-ui.sh
2026-10-14 05:25:28 -04:00 · 2026-10-14 05:25:28 -04:00 · 78cc3a40ec
commit 78cc3a40ec
parent 41e079a0ad
14 changed files with 660 additions and 40 deletions
--- a/.gitignore
+++ b/.gitignore
@ -11,3 +11,5 @@ Verae-Secret-Credentials.MD
 # Compiled PT-06 menu bar (built by run-menubar.sh / swiftc)
 platform/macos/menubar/verae-menubar
 verae-print
+platform/macos/pkg/resources/AppIcon.iconset/
+build/macos-pkg/
--- a/docs/COMMERCIAL-INSTALLER-BACKLOG.md
+++ b/docs/COMMERCIAL-INSTALLER-BACKLOG.md
@ -130,6 +130,7 @@ NSIS product already covers much of the *install experience* (files under Progra
 | Item | Location / notes | Status |
 |------|------------------|--------|
 | **Signed + notarized `.pkg` builder** | [`platform/macos/pkg/build-pkg.sh`](../platform/macos/pkg/build-pkg.sh) | **Full commercial path for installer package**: universal `verae-print`, codesign hardened runtime, stages `Verae Print Stamp.app`, `pkgbuild` + `productbuild` (Developer ID Installer), `notarytool submit --wait`, `stapler staple`, SHA256SUMS |
+| **Installer GUI: product ID + Verae brand + license Agree** | [`pkg/Distribution.xml.in`](../platform/macos/pkg/Distribution.xml.in) + [`pkg/resources/`](../platform/macos/pkg/resources/) + [`smoke-installer-ui.sh`](../platform/macos/pkg/smoke-installer-ui.sh) | **Done** — productbuild Distribution with welcome, **license Agree/Disagree**, readme product ID table, conclusion, plum brand backgrounds; app Info.plist `VeraeProductID` + AppIcon; smoke 15/14 |
 | Entitlements | [`platform/macos/pkg/entitlements.plist`](../platform/macos/pkg/entitlements.plist) | network client, user-selected files, allow-jit |
 | Postinstall (printer, LaunchAgent, key setup) | [`platform/macos/pkg/scripts/postinstall`](../platform/macos/pkg/scripts/postinstall) | Console-user IPP queue + `mac-key-setup` |
 | App bundle **inside** pkg stage | Built by `build-pkg.sh` → `/Applications/Verae Print Stamp.app` | Thin wrapper: runs `verae-print mac-key-setup` or `stamp -open` on dropped PDFs; codesigned in pkg flow |
--- a/docs/PACKAGING.md
+++ b/docs/PACKAGING.md
@ -325,3 +325,34 @@ Operator enable package (secrets/VM only left):
 | `platform/macos/pkg/build-pkg.sh` | optional signed `.pkg` (certs required) |
 | `platform/smoke-packaging-metadata.sh` | A4 packaging smoke |
 | `site/printit.verae.ai/certificate.html` | CERT-01 web cert viewer (brand kit) |
+
+
+## macOS product .pkg installer GUI
+
+`platform/macos/pkg/build-pkg.sh` builds a **product** package (not a bare
+component) with Installer.app pages:
+
+| Page | Resource | Purpose |
+|------|----------|---------|
+| Welcome | `resources/welcome.html` | Verae branding + product ID `ai.verae.print-stamp` |
+| License | `resources/license.html` | **Agree / Disagree** EULA acceptance |
+| Read Me | `resources/readme.html` | Product identification table (name, IDs, version, publisher) |
+| Conclusion | `resources/conclusion.html` | Next steps after install |
+| Background | `resources/background.png` (+ dark) | Verae plum brand panel |
+
+Distribution template: `Distribution.xml.in` → stamped `Distribution.xml`.
+App bundle also carries `CFBundleIconFile` (AppIcon.icns), `VeraeProductID`,
+and `/Library/Application Support/Verae/PrintStamp/PRODUCT.txt`.
+
+```sh
+# Full signed + notarized (needs signing.env)
+./platform/macos/pkg/build-pkg.sh
+
+# Local unsigned product for Installer UI review
+SKIP_SIGN=1 ./platform/macos/pkg/build-pkg.sh
+open build/macos-pkg/dist/VeraePrintStamp-macos.pkg
+
+# Smoke: product ID + brand + license resources embedded
+./platform/macos/pkg/smoke-installer-ui.sh
+```
+
--- a/platform/macos/pkg/Distribution.xml.in
+++ b/platform/macos/pkg/Distribution.xml.in
@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="utf-8"?>
+<installer-gui-script minSpecVersion="2">
+    <title>Verae Print Stamp</title>
+    <organization>ai.verae</organization>
+
+    <!-- Product identification shown in Installer.app -->
+    <options
+        customize="never"
+        require-scripts="false"
+        hostArchitectures="x86_64,arm64"
+        rootVolumeOnly="true"/>
+
+    <domains enable_anywhere="false"
+             enable_currentUserHome="false"
+             enable_localSystem="true"/>
+
+    <!-- Verae branding backgrounds -->
+    <background file="background.png"
+                mime-type="image/png"
+                alignment="bottomleft"
+                scaling="proportional"/>
+    <background-darkAqua file="background-dark.png"
+                         mime-type="image/png"
+                         alignment="bottomleft"
+                         scaling="proportional"/>
+
+    <!-- Welcome with product ID and brand -->
+    <welcome file="welcome.html" mime-type="text/html" />
+
+    <!-- Required license acceptance (Installer shows Agree / Disagree) -->
+    <license file="license.html" mime-type="text/html" />
+
+    <!-- Explicit product identification sheet -->
+    <readme file="readme.html" mime-type="text/html" />
+
+    <conclusion file="conclusion.html" mime-type="text/html" />
+
+    <installation-check script="pm_install_check()"/>
+    <script>
+    <![CDATA[
+    function pm_install_check() {
+        if (!(system.compareVersions(system.version.ProductVersion, '14.0') >= 0)) {
+            my.result.type = 'Fatal';
+            my.result.message = 'Verae Print Stamp requires macOS 14 or later.';
+            return false;
+        }
+        return true;
+    }
+    ]]>
+    </script>
+
+    <choices-outline>
+        <line choice="verae-print-stamp"/>
+    </choices-outline>
+
+    <choice id="verae-print-stamp"
+            visible="false"
+            title="Verae Print Stamp"
+            description="Verae Print Stamp (PrintIt). Product ID ai.verae.print-stamp. Installs the branded app, helper, and print integration.">
+        <pkg-ref id="@PKG_ID@"/>
+    </choice>
+
+    <pkg-ref id="@PKG_ID@"
+             version="@VERSION@"
+             auth="Root"
+             onConclusion="none">@COMPONENT_NAME@</pkg-ref>
+</installer-gui-script>
--- a/platform/macos/pkg/LICENSE.txt
+++ b/platform/macos/pkg/LICENSE.txt
@ -0,0 +1,39 @@
+Verae Print Stamp (PrintIt)
+Product ID: ai.verae.print-stamp
+Copyright (c) Verae / FlightLookup Inc. / George Lambert
+
+END USER LICENSE AGREEMENT
+
+You must accept this agreement to install Verae Print Stamp.
+
+1. License
+UNLICENSED — all rights reserved unless otherwise agreed in writing.
+Subject to this agreement, Verae grants a limited, non-exclusive,
+non-transferable license to install and use Verae Print Stamp on macOS
+computers you own or control for Verae-backed document timestamping.
+
+2. What is sent to Verae
+This software sends only a SHA-256 digest of your document (and related
+registration metadata) to Verae. Document bytes remain on your computer.
+
+3. Accounts and keys
+Signing keys and customer tokens are tied to your Verae account. Keep
+keys secret. Portal: https://customer.verae.ai/portal/
+
+4. Restrictions
+Do not reverse engineer except where mandatory law allows.
+Do not remove Verae branding, copyright, or product identification.
+Do not misrepresent timestamp receipts or certificate contents.
+
+5. Disclaimer
+THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
+
+6. Limitation of liability
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, VERAE AND ITS SUPPLIERS ARE NOT
+LIABLE FOR INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE
+DAMAGES ARISING FROM USE OF THE SOFTWARE.
+
+7. Contact
+Downloads: https://printit.verae.ai/
+Support:   https://verae.com
+Bundle:    Verae Print Stamp.app (ai.verae.print-stamp)
--- a/platform/macos/pkg/build-pkg.sh
+++ b/platform/macos/pkg/build-pkg.sh
@ -1,13 +1,31 @@
 #!/usr/bin/env bash
 # Build a Developer ID–signed, notarized macOS .pkg for Verae Print Stamp.
-# Uses the same signing.env as Verae Timestamping.app (FlightLookup Inc.).
+# Installer GUI includes: product identification, Verae branding, license Agree.
+#
+# Env:
+#   VERSION          override HelperVersion
+#   SIGNING_ENV      path to Apple signing.env (default ~/fie/installers/macos/signing.env)
+#   SKIP_SIGN=1      unsigned component + product (local UI smoke; no notary)
+#   SKIP_NOTARY=1    sign product but skip notarytool/staple
+#   UNSIGNED_ONLY=1  alias for SKIP_SIGN=1
 set -euo pipefail

 ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
 PKG_DIR="$(cd "$(dirname "$0")" && pwd)"
+RES_SRC="$PKG_DIR/resources"
 SIGNING_ENV="${SIGNING_ENV:-$HOME/fie/installers/macos/signing.env}"
-# shellcheck source=/dev/null
-source "$SIGNING_ENV"
+SKIP_SIGN="${SKIP_SIGN:-${UNSIGNED_ONLY:-0}}"
+SKIP_NOTARY="${SKIP_NOTARY:-0}"
+
+if [[ "$SKIP_SIGN" != "1" ]]; then
+  if [[ ! -f "$SIGNING_ENV" ]]; then
+    echo "error: signing env not found: $SIGNING_ENV" >&2
+    echo "hint: SKIP_SIGN=1 ./build-pkg.sh   # unsigned product for installer UI smoke" >&2
+    exit 1
+  fi
+  # shellcheck source=/dev/null
+  source "$SIGNING_ENV"
+fi

 # Package version = internal/job.HelperVersion (single source of truth).
 if [[ -z "${VERSION:-}" ]]; then
@ -18,15 +36,18 @@ BUILD_ROOT="$ROOT/build/macos-pkg"
 STAGE="$BUILD_ROOT/stage"
 SCRIPTS="$BUILD_ROOT/scripts"
 DIST="$BUILD_ROOT/dist"
+RES_STAGE="$BUILD_ROOT/resources"
 ID_APP="${APPLE_APP_SIGN_ID:-Developer ID Application: FlightLookup Inc. (G8CKY7VMZC)}"
 ID_PKG="${APPLE_INSTALLER_SIGN_ID:-Developer ID Installer: FlightLookup Inc. (G8CKY7VMZC)}"
 ENTITLEMENTS="$PKG_DIR/entitlements.plist"
 BUNDLE_ID="ai.verae.print-stamp"
 PKG_ID="ai.verae.print-stamp.pkg"
+PRODUCT_NAME="Verae Print Stamp"
+COMPONENT_NAME="VeraePrintStamp-component.pkg"

 echo "→ Cleaning $BUILD_ROOT"
 rm -rf "$BUILD_ROOT"
-mkdir -p "$STAGE" "$SCRIPTS" "$DIST" \
+mkdir -p "$STAGE" "$SCRIPTS" "$DIST" "$RES_STAGE" \
  "$STAGE/Library/Application Support/Verae/PrintStamp/bin" \
  "$STAGE/Library/Application Support/Verae/PrintStamp/ipp" \
  "$STAGE/Library/Application Support/Verae/PrintStamp/registration-pdf" \
@ -37,16 +58,30 @@ cd "$ROOT"
 mkdir -p "$BUILD_ROOT/bin"
 GOOS=darwin GOARCH=arm64 go build -o "$BUILD_ROOT/bin/verae-print-arm64" ./cmd/verae-print
 GOOS=darwin GOARCH=amd64 go build -o "$BUILD_ROOT/bin/verae-print-amd64" ./cmd/verae-print
-# Embed version string into HelperVersion via env for postinstall display
 echo "$VERSION" > "$STAGE/Library/Application Support/Verae/PrintStamp/VERSION"
+# Product identification sidecar for support/audit
+cat > "$STAGE/Library/Application Support/Verae/PrintStamp/PRODUCT.txt" <<PROD
+product_name=$PRODUCT_NAME
+product_id=$BUNDLE_ID
+package_id=$PKG_ID
+version=$VERSION
+publisher=Verae / FlightLookup Inc.
+brand=Verae
+downloads=https://printit.verae.ai/
+support=https://verae.com
+PROD
 lipo -create -output "$STAGE/Library/Application Support/Verae/PrintStamp/bin/verae-print" \
  "$BUILD_ROOT/bin/verae-print-arm64" "$BUILD_ROOT/bin/verae-print-amd64"
 chmod 755 "$STAGE/Library/Application Support/Verae/PrintStamp/bin/verae-print"

-echo "→ Signing verae-print"
-codesign --force --sign "$ID_APP" --options runtime --timestamp \
+if [[ "$SKIP_SIGN" != "1" ]]; then
+  echo "→ Signing verae-print"
+  codesign --force --sign "$ID_APP" --options runtime --timestamp \
    --entitlements "$ENTITLEMENTS" \
    "$STAGE/Library/Application Support/Verae/PrintStamp/bin/verae-print"
+else
+  echo "→ SKIP_SIGN=1 — leaving verae-print unsigned"
+fi

 echo "→ Bundling registration-pdf (jsPDF) + assets"
 cp -R "$ROOT/platform/registration-pdf/." "$STAGE/Library/Application Support/Verae/PrintStamp/registration-pdf/"
@ -58,30 +93,37 @@ rm -rf "$STAGE/Library/Application Support/Verae/PrintStamp/registration-pdf/nod
 mkdir -p "$STAGE/Library/Application Support/Verae/PrintStamp/assets"
 cp -f "$ROOT/assets/VeraeFullLogo.png" "$STAGE/Library/Application Support/Verae/PrintStamp/assets/" 2>/dev/null || true
 cp -f "$ROOT/internal/pdfcert/logo.png" "$STAGE/Library/Application Support/Verae/PrintStamp/registration-pdf/VeraeFullLogo.png" 2>/dev/null || true
+cp -f "$PKG_DIR/LICENSE.txt" "$STAGE/Library/Application Support/Verae/PrintStamp/LICENSE.txt"

 echo "→ IPP helper files"
 cp -f "$ROOT/platform/macos/ipp/verae-print-command.sh" "$STAGE/Library/Application Support/Verae/PrintStamp/ipp/"
 cp -f "$ROOT/platform/macos/ipp/com.verae.timestamping.ipp.plist" "$STAGE/Library/Application Support/Verae/PrintStamp/ipp/"
 chmod 755 "$STAGE/Library/Application Support/Verae/PrintStamp/ipp/verae-print-command.sh"
-# Point LaunchAgent template -c path will be rewritten in postinstall to user support;
-# also bake library binary path into a system copy of the command for reference.
 sed -i '' "s|VERAE_PRINT_BIN:-\$HOME/bin/verae-print|VERAE_PRINT_BIN:-/Library/Application Support/Verae/PrintStamp/bin/verae-print|" \
  "$STAGE/Library/Application Support/Verae/PrintStamp/ipp/verae-print-command.sh" 2>/dev/null || true

-echo "→ Building Verae Print Stamp.app"
-APP="$STAGE/Applications/Verae Print Stamp.app"
+echo "→ Building $PRODUCT_NAME.app (branded + product ID)"
+APP="$STAGE/Applications/${PRODUCT_NAME}.app"
 mkdir -p "$APP/Contents/MacOS" "$APP/Contents/Resources"
+if [[ -f "$RES_SRC/AppIcon.icns" ]]; then
+  cp -f "$RES_SRC/AppIcon.icns" "$APP/Contents/Resources/AppIcon.icns"
+fi
+cp -f "$ROOT/assets/VeraeFullLogo.png" "$APP/Contents/Resources/VeraeFullLogo.png" 2>/dev/null || true
+
 cat > "$APP/Contents/Info.plist" <<PLIST
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0"><dict>
  <key>CFBundleExecutable</key><string>Verae Print Stamp</string>
  <key>CFBundleIdentifier</key><string>$BUNDLE_ID</string>
-  <key>CFBundleName</key><string>Verae Print Stamp</string>
-  <key>CFBundleDisplayName</key><string>Verae Print Stamp</string>
+  <key>CFBundleName</key><string>$PRODUCT_NAME</string>
+  <key>CFBundleDisplayName</key><string>$PRODUCT_NAME</string>
  <key>CFBundlePackageType</key><string>APPL</string>
  <key>CFBundleShortVersionString</key><string>$VERSION</string>
  <key>CFBundleVersion</key><string>$VERSION</string>
+  <key>CFBundleGetInfoString</key>
+  <string>$PRODUCT_NAME $VERSION — Verae / FlightLookup Inc. (ai.verae.print-stamp)</string>
+  <key>CFBundleIconFile</key><string>AppIcon</string>
  <key>LSMinimumSystemVersion</key><string>14.0</string>
  <key>NSHighResolutionCapable</key><true/>
  <key>CFBundleDocumentTypes</key>
@ -95,7 +137,11 @@ cat > "$APP/Contents/Info.plist" <<PLIST
    </dict>
  </array>
  <key>NSHumanReadableCopyright</key>
-  <string>Copyright © FlightLookup Inc. / Verae</string>
+  <string>Copyright © Verae / FlightLookup Inc. All rights reserved.</string>
+  <key>VeraeProductID</key><string>$BUNDLE_ID</string>
+  <key>VeraePackageID</key><string>$PKG_ID</string>
+  <key>VeraeBrand</key><string>Verae</string>
+  <key>VeraeProductURL</key><string>https://printit.verae.ai/</string>
 </dict></plist>
 PLIST

@ -120,20 +166,41 @@ for f in "$@"; do
 done
 RUN
 chmod 755 "$APP/Contents/MacOS/Verae Print Stamp"
+echo "APPL????" > "$APP/Contents/PkgInfo" 2>/dev/null || printf 'APPL????' > "$APP/Contents/PkgInfo"

-echo "→ Signing app bundle"
-codesign --force --deep --sign "$ID_APP" --options runtime --timestamp \
+if [[ "$SKIP_SIGN" != "1" ]]; then
+  echo "→ Signing app bundle"
+  codesign --force --deep --sign "$ID_APP" --options runtime --timestamp \
    --entitlements "$ENTITLEMENTS" \
    "$APP"
+else
+  echo "→ SKIP_SIGN=1 — leaving app unsigned"
+fi
+
+echo "→ Preparing installer GUI resources (welcome / license / readme / branding)"
+cp -f "$RES_SRC/welcome.html" "$RES_STAGE/"
+cp -f "$RES_SRC/license.html" "$RES_STAGE/"
+cp -f "$RES_SRC/conclusion.html" "$RES_STAGE/"
+cp -f "$RES_SRC/background.png" "$RES_STAGE/"
+cp -f "$RES_SRC/background-dark.png" "$RES_STAGE/"
+# readme: inject version
+sed "s/{{VERSION}}/$VERSION/g" "$RES_SRC/readme.html" > "$RES_STAGE/readme.html"
+# Distribution from template
+sed \
+  -e "s/@VERSION@/$VERSION/g" \
+  -e "s/@PKG_ID@/$PKG_ID/g" \
+  -e "s/@BUNDLE_ID@/$BUNDLE_ID/g" \
+  -e "s/@COMPONENT_NAME@/$COMPONENT_NAME/g" \
+  "$PKG_DIR/Distribution.xml.in" > "$BUILD_ROOT/Distribution.xml"

 echo "→ Preparing pkg scripts"
 cp -f "$PKG_DIR/scripts/postinstall" "$SCRIPTS/postinstall"
 chmod 755 "$SCRIPTS/postinstall"

-COMPONENT_PKG="$DIST/VeraePrintStamp-component.pkg"
+COMPONENT_PKG="$DIST/$COMPONENT_NAME"
 PRODUCT_PKG="$DIST/VeraePrintStamp-${VERSION}.pkg"

-echo "→ pkgbuild component"
+echo "→ pkgbuild component ($PKG_ID $VERSION)"
 pkgbuild \
  --root "$STAGE" \
  --scripts "$SCRIPTS" \
@ -142,25 +209,34 @@ pkgbuild \
  --install-location "/" \
  "$COMPONENT_PKG"

-echo "→ productbuild + Developer ID Installer sign"
-productbuild \
-  --package "$COMPONENT_PKG" \
-  --sign "$ID_PKG" \
-  --timestamp \
-  "$PRODUCT_PKG"
+echo "→ productbuild Distribution (branded + license accept + product ID)"
+PB_ARGS=(
+  --distribution "$BUILD_ROOT/Distribution.xml"
+  --resources "$RES_STAGE"
+  --package-path "$DIST"
+)
+if [[ "$SKIP_SIGN" != "1" ]]; then
+  PB_ARGS+=(--sign "$ID_PKG" --timestamp)
+fi
+productbuild "${PB_ARGS[@]}" "$PRODUCT_PKG"

-echo "→ Notarizing $PRODUCT_PKG"
-xcrun notarytool submit "$PRODUCT_PKG" --wait \
+if [[ "$SKIP_SIGN" != "1" && "$SKIP_NOTARY" != "1" ]]; then
+  echo "→ Notarizing $PRODUCT_PKG"
+  xcrun notarytool submit "$PRODUCT_PKG" --wait \
    --key "$APPLE_API_KEY_PATH" \
    --key-id "$APPLE_API_KEY_ID" \
    --issuer "$APPLE_API_ISSUER_ID"
-
-echo "→ Stapling"
-xcrun stapler staple "$PRODUCT_PKG"
-
-echo "→ Verifying"
-spctl -a -vv -t install "$PRODUCT_PKG" || true
-pkgutil --check-signature "$PRODUCT_PKG" || true
+  echo "→ Stapling"
+  xcrun stapler staple "$PRODUCT_PKG"
+  echo "→ Verifying"
+  spctl -a -vv -t install "$PRODUCT_PKG" || true
+  pkgutil --check-signature "$PRODUCT_PKG" || true
+elif [[ "$SKIP_SIGN" == "1" ]]; then
+  echo "→ SKIP_SIGN=1 — skipping notary/staple (open $PRODUCT_PKG to review Installer UI)"
+elif [[ "$SKIP_NOTARY" == "1" ]]; then
+  echo "→ SKIP_NOTARY=1 — signed product, not notarized"
+  pkgutil --check-signature "$PRODUCT_PKG" || true
+fi

 # Stable latest name + checksums
 cp -f "$PRODUCT_PKG" "$DIST/VeraePrintStamp-macos.pkg"
@ -169,10 +245,45 @@ cp -f "$PRODUCT_PKG" "$DIST/VeraePrintStamp-macos.pkg"
  shasum -a 256 "VeraePrintStamp-${VERSION}.pkg" VeraePrintStamp-macos.pkg > SHA256SUMS
 )

+# Expand smoke: ensure Distribution + license resources embedded
+EXPAND="$BUILD_ROOT/expand-check"
+rm -rf "$EXPAND"
+pkgutil --expand "$PRODUCT_PKG" "$EXPAND"
+fail=0
+has_expand_file() {
+  local f
+  f="$(find "$EXPAND" -name "$1" -print -quit 2>/dev/null || true)"
+  [[ -n "$f" && -s "$f" ]]
+}
+for need in Distribution welcome.html license.html readme.html conclusion.html background.png; do
+  if ! has_expand_file "$need"; then
+    echo "error: product pkg missing installer resource: $need" >&2
+    fail=1
+  fi
+done
+DIST_FILE=""
+[[ -f "$EXPAND/Distribution" ]] && DIST_FILE="$EXPAND/Distribution"
+[[ -z "$DIST_FILE" && -f "$EXPAND/Distribution.xml" ]] && DIST_FILE="$EXPAND/Distribution.xml"
+if [[ -z "$DIST_FILE" ]] || ! grep -q 'Verae Print Stamp' "$DIST_FILE"; then
+  echo "error: Distribution missing product title Verae Print Stamp" >&2
+  fail=1
+fi
+if [[ -n "$DIST_FILE" ]] && ! grep -q 'ai.verae.print-stamp' "$DIST_FILE"; then
+  echo "error: Distribution missing product id ai.verae.print-stamp" >&2
+  fail=1
+fi
+if [[ "$fail" -ne 0 ]]; then
+  echo "Installer resource check failed. Tree:" >&2
+  find "$EXPAND" -maxdepth 3 -type f >&2 || true
+  exit 1
+fi
+echo "→ Installer GUI resources verified inside product pkg"
+
 echo
 echo "Signed installable ready:"
 echo "  $PRODUCT_PKG"
 echo "  $DIST/VeraePrintStamp-macos.pkg"
 echo
+echo "Installer pages: Welcome (branded) → License (Agree) → Read Me (product ID) → Install → Conclusion"
 echo "Install: double-click the .pkg  (or: sudo installer -pkg … -target /)"
 echo "Then: Print → Destination → Verae Timestamping"
--- a/platform/macos/pkg/resources/AppIcon.icns
+++ b/platform/macos/pkg/resources/AppIcon.icns
--- a/platform/macos/pkg/resources/background-dark.png
+++ b/platform/macos/pkg/resources/background-dark.png
--- a/platform/macos/pkg/resources/background.png
+++ b/platform/macos/pkg/resources/background.png
--- a/platform/macos/pkg/resources/conclusion.html
+++ b/platform/macos/pkg/resources/conclusion.html
@ -0,0 +1,43 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<title>Install complete — Verae Print Stamp</title>
+<style>
+  html, body {
+    margin: 0; padding: 0;
+    font-family: -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, Arial, sans-serif;
+    color: #1D1534; background: #fff;
+  }
+  .wrap { padding: 18px 22px; }
+  h1 { margin: 0; font-size: 20px; color: #531B59; }
+  .sub { margin: 4px 0 12px 0; font-size: 12px; color: #6C5B81; }
+  p, li { font-size: 13px; line-height: 1.45; }
+  ul { margin: 8px 0 0 18px; padding: 0; color: #5A4E6E; }
+  .next {
+    margin-top: 14px; padding: 12px 14px; border-radius: 10px;
+    background: #F7EFF8; border: 1px solid #D9CCE3;
+  }
+  .next strong { color: #3E1343; }
+  a { color: #531B59; }
+</style>
+</head>
+<body>
+  <div class="wrap">
+    <h1>Verae Print Stamp is installed</h1>
+    <div class="sub">Product ID ai.verae.print-stamp · branded Verae installer</div>
+    <div class="next">
+      <strong>Next steps</strong>
+      <ul>
+        <li>Open <strong>Verae Print Stamp</strong> from Applications to finish key setup</li>
+        <li>Or Print → Destination → <strong>Verae Timestamping</strong> when the printer is registered</li>
+        <li>Sign in at <a href="https://customer.verae.ai/portal/">customer.verae.ai/portal</a> if you need an account or key</li>
+        <li>Docs &amp; downloads: <a href="https://printit.verae.ai/">printit.verae.ai</a></li>
+      </ul>
+    </div>
+    <p style="margin-top:14px;font-size:12px;color:#6C5B81;">
+      Thank you for choosing Verae.
+    </p>
+  </div>
+</body>
+</html>
--- a/platform/macos/pkg/resources/license.html
+++ b/platform/macos/pkg/resources/license.html
@ -0,0 +1,109 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<title>License Agreement — Verae Print Stamp</title>
+<style>
+  html, body {
+    margin: 0; padding: 0;
+    font-family: -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, Arial, sans-serif;
+    color: #1D1534; background: #fff;
+  }
+  .wrap { padding: 14px 18px; }
+  h1 { font-size: 16px; color: #531B59; margin: 0 0 8px 0; }
+  h2 { font-size: 13px; color: #3E1343; margin: 14px 0 6px 0; }
+  p, li { font-size: 12px; line-height: 1.45; margin: 0 0 8px 0; }
+  ul { margin: 0 0 8px 18px; padding: 0; }
+  .meta { font-size: 11px; color: #6C5B81; margin-bottom: 12px; }
+  .box {
+    border: 1px solid #D9CCE3; border-radius: 8px;
+    background: #F7EFF8; padding: 10px 12px; margin: 10px 0;
+    font-size: 12px;
+  }
+</style>
+</head>
+<body>
+  <div class="wrap">
+    <h1>Verae Print Stamp — End User License Agreement</h1>
+    <div class="meta">
+      Product: Verae Print Stamp (PrintIt) · ID: ai.verae.print-stamp<br/>
+      Copyright © Verae / FlightLookup Inc. / George Lambert<br/>
+      You must accept this agreement to continue installation.
+    </div>
+
+    <div class="box">
+      <strong>Accept to install.</strong> By clicking Agree / Continue in the macOS
+      Installer, you accept these terms. If you do not agree, click Agree is not
+      available until you review, or cancel the installer.
+    </div>
+
+    <h2>1. License</h2>
+    <p>
+      UNLICENSED — all rights reserved unless otherwise agreed in writing with Verae.
+      Subject to this agreement, Verae grants you a limited, non-exclusive,
+      non-transferable license to install and use Verae Print Stamp on Apple
+      macOS computers you own or control, for timestamping documents with Verae.
+    </p>
+
+    <h2>2. What is sent to Verae</h2>
+    <p>
+      This software sends only a <strong>SHA-256 digest</strong> of your document
+      (and related registration metadata) to Verae for timestamp registration.
+      Document bytes remain on your computer. You are responsible for network
+      access, account credentials (including xVerae- keys), and lawful use.
+    </p>
+
+    <h2>3. Accounts and keys</h2>
+    <p>
+      Signing keys and customer tokens are tied to your Verae account. Keep keys
+      secret. Lost keys may prevent proving prior stamps. Portal:
+      https://customer.verae.ai/portal/
+    </p>
+
+    <h2>4. Restrictions</h2>
+    <ul>
+      <li>Do not reverse engineer except where mandatory law allows.</li>
+      <li>Do not remove Verae branding, copyright, or product identification.</li>
+      <li>Do not use the software to infringe others’ rights or violate law.</li>
+      <li>Do not misrepresent timestamp receipts or certificate contents.</li>
+    </ul>
+
+    <h2>5. Ownership</h2>
+    <p>
+      The software, Verae marks, and documentation remain property of Verae and
+      its licensors. No trademark license is granted beyond normal use of the
+      installed product UI.
+    </p>
+
+    <h2>6. Disclaimer</h2>
+    <p>
+      THE SOFTWARE IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+      IMPLIED, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND
+      NON-INFRINGEMENT. TIMESTAMPING DEPENDS ON NETWORK, ACCOUNT, AND UPSTREAM
+      SERVICES.
+    </p>
+
+    <h2>7. Limitation of liability</h2>
+    <p>
+      TO THE MAXIMUM EXTENT PERMITTED BY LAW, VERAE AND ITS SUPPLIERS ARE NOT
+      LIABLE FOR INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE
+      DAMAGES, OR LOSS OF DATA, PROFITS, OR BUSINESS, ARISING FROM USE OF THE
+      SOFTWARE.
+    </p>
+
+    <h2>8. Termination</h2>
+    <p>
+      This license ends if you breach it. On termination, stop using and uninstall
+      the software. Provisions that by nature should survive (ownership,
+      disclaimer, liability) survive termination.
+    </p>
+
+    <h2>9. Contact</h2>
+    <p>
+      Downloads: https://printit.verae.ai/<br/>
+      Support: https://verae.com<br/>
+      Product ID: ai.verae.print-stamp · Bundle: Verae Print Stamp.app
+    </p>
+  </div>
+</body>
+</html>
--- a/platform/macos/pkg/resources/readme.html
+++ b/platform/macos/pkg/resources/readme.html
@ -0,0 +1,49 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<title>Product identification — Verae Print Stamp</title>
+<style>
+  html, body {
+    margin: 0; padding: 0;
+    font-family: -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, Arial, sans-serif;
+    color: #1D1534; background: #fff;
+  }
+  .wrap { padding: 14px 18px; }
+  h1 { font-size: 16px; color: #531B59; margin: 0 0 10px 0; }
+  table { border-collapse: collapse; width: 100%; font-size: 12px; }
+  th, td {
+    text-align: left; vertical-align: top;
+    padding: 6px 8px; border-bottom: 1px solid #EBD9EE;
+  }
+  th { width: 38%; color: #3E1343; font-weight: 600; background: #F7EFF8; }
+  td { color: #1D1534; }
+  .note { margin-top: 12px; font-size: 11px; color: #6C5B81; }
+</style>
+</head>
+<body>
+  <div class="wrap">
+    <h1>Product identification</h1>
+    <table>
+      <tr><th>Product name</th><td>Verae Print Stamp (PrintIt)</td></tr>
+      <tr><th>Display name</th><td>Verae Print Stamp</td></tr>
+      <tr><th>Publisher</th><td>Verae / FlightLookup Inc.</td></tr>
+      <tr><th>Bundle identifier</th><td>ai.verae.print-stamp</td></tr>
+      <tr><th>Installer package ID</th><td>ai.verae.print-stamp.pkg</td></tr>
+      <tr><th>Version</th><td><!--VERSION-->{{VERSION}}<!--/VERSION--></td></tr>
+      <tr><th>Platform</th><td>macOS 14+ (Apple silicon &amp; Intel)</td></tr>
+      <tr><th>Install locations</th><td>
+        /Applications/Verae Print Stamp.app<br/>
+        /Library/Application Support/Verae/PrintStamp/
+      </td></tr>
+      <tr><th>Brand</th><td>Verae plum #531B59 · printit.verae.ai</td></tr>
+      <tr><th>Support</th><td>https://verae.com · https://printit.verae.ai/</td></tr>
+      <tr><th>License</th><td>Must accept EULA in this installer before files are installed</td></tr>
+    </table>
+    <p class="note">
+      This Read Me identifies the product for audit and support. It is not a
+      substitute for the License Agreement screen.
+    </p>
+  </div>
+</body>
+</html>
--- a/platform/macos/pkg/resources/welcome.html
+++ b/platform/macos/pkg/resources/welcome.html
@ -0,0 +1,83 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<title>Welcome — Verae Print Stamp</title>
+<style>
+  :root {
+    --plum: #531B59;
+    --plum-d: #3E1343;
+    --plum-mid: #6C5B81;
+    --ink: #1D1534;
+    --muted: #5A4E6E;
+    --bg: #F7EFF8;
+  }
+  html, body {
+    margin: 0; padding: 0;
+    font-family: -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, Arial, sans-serif;
+    color: var(--ink);
+    background: #fff;
+  }
+  .wrap { padding: 18px 22px 12px 22px; }
+  .brand {
+    display: flex; align-items: center; gap: 12px;
+    margin-bottom: 14px;
+  }
+  .mark {
+    width: 36px; height: 36px; border-radius: 8px;
+    background: var(--plum);
+    color: #fff; font-weight: 700; font-size: 14px;
+    display: flex; align-items: center; justify-content: center;
+  }
+  h1 {
+    margin: 0; font-size: 22px; font-weight: 700; color: var(--plum);
+    letter-spacing: -0.02em;
+  }
+  .product-id {
+    margin: 2px 0 0 0; font-size: 12px; color: var(--plum-mid);
+  }
+  .tag {
+    display: inline-block; margin-top: 10px;
+    padding: 3px 10px; border-radius: 999px;
+    background: var(--bg); color: var(--plum-d);
+    font-size: 11px; font-weight: 600; letter-spacing: 0.04em;
+    text-transform: uppercase;
+  }
+  p { font-size: 13px; line-height: 1.45; color: var(--ink); margin: 12px 0 0 0; }
+  ul { margin: 10px 0 0 18px; padding: 0; font-size: 13px; line-height: 1.5; color: var(--muted); }
+  li { margin: 4px 0; }
+  .foot {
+    margin-top: 16px; padding-top: 10px;
+    border-top: 1px solid #EBD9EE;
+    font-size: 11px; color: var(--plum-mid);
+  }
+</style>
+</head>
+<body>
+  <div class="wrap">
+    <div class="brand">
+      <div class="mark">V</div>
+      <div>
+        <h1>Verae Print Stamp</h1>
+        <div class="product-id">Product ID: ai.verae.print-stamp · PrintIt for macOS</div>
+      </div>
+    </div>
+    <span class="tag">Verae branded installer</span>
+    <p>
+      This installer sets up <strong>Verae Print Stamp</strong> (PrintIt) so you can
+      timestamp PDFs and print jobs with a Verae-backed cryptographic receipt.
+      Only a SHA-256 digest leaves your Mac — document bytes stay local.
+    </p>
+    <ul>
+      <li><strong>Verae Print Stamp.app</strong> in Applications</li>
+      <li>Helper binary under Application Support</li>
+      <li>Optional “Verae Timestamping” print destination</li>
+      <li>Menu bar / LaunchAgent hooks when enabled</li>
+    </ul>
+    <p>Click Continue to review the license agreement, then install.</p>
+    <div class="foot">
+      Publisher: Verae / FlightLookup Inc. · https://printit.verae.ai/ · https://verae.com
+    </div>
+  </div>
+</body>
+</html>
--- a/platform/macos/pkg/smoke-installer-ui.sh
+++ b/platform/macos/pkg/smoke-installer-ui.sh
@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Smoke: assert macOS product pkg carries product ID, Verae branding, license UI.
+# Prefer an existing dist pkg; else build unsigned with SKIP_SIGN=1.
+set -euo pipefail
+PKG_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$PKG_DIR/../../.." && pwd)"
+DIST="$ROOT/build/macos-pkg/dist"
+VERSION="${VERSION:-}"
+if [[ -z "$VERSION" && -f "$ROOT/internal/job/job.go" ]]; then
+  VERSION="$(grep -E 'HelperVersion[[:space:]]*=' "$ROOT/internal/job/job.go" | head -1 | sed -E 's/.*"([^"]+)".*/\1/')"
+fi
+VERSION="${VERSION:-0.3.6}"
+
+PRODUCT="${1:-}"
+if [[ -z "$PRODUCT" ]]; then
+  if [[ -f "$DIST/VeraePrintStamp-${VERSION}.pkg" ]]; then
+    PRODUCT="$DIST/VeraePrintStamp-${VERSION}.pkg"
+  elif [[ -f "$DIST/VeraePrintStamp-macos.pkg" ]]; then
+    PRODUCT="$DIST/VeraePrintStamp-macos.pkg"
+  else
+    echo "→ no existing pkg; building unsigned product (SKIP_SIGN=1)"
+    SKIP_SIGN=1 "$PKG_DIR/build-pkg.sh"
+    PRODUCT="$DIST/VeraePrintStamp-${VERSION}.pkg"
+  fi
+fi
+
+echo "→ smoke installer UI: $PRODUCT"
+TMP="$(mktemp -d /tmp/verae-pkg-smoke.XXXXXX)"
+trap 'rm -rf "$TMP"' EXIT
+pkgutil --expand "$PRODUCT" "$TMP/exp"
+
+pass=0
+fail=0
+check() {
+  local id="$1"; shift
+  if "$@" >/dev/null 2>&1; then
+    echo "  PASS $id"
+    pass=$((pass+1))
+  else
+    echo "  FAIL $id"
+    fail=$((fail+1))
+  fi
+}
+
+has_file() {
+  local name="$1"
+  local f
+  f="$(find "$TMP/exp" -name "$name" -print -quit 2>/dev/null || true)"
+  [[ -n "$f" && -s "$f" ]]
+}
+
+find_one() {
+  find "$TMP/exp" -name "$1" -print -quit 2>/dev/null || true
+}
+
+DIST_FILE=""
+if [[ -f "$TMP/exp/Distribution" ]]; then
+  DIST_FILE="$TMP/exp/Distribution"
+elif [[ -f "$TMP/exp/Distribution.xml" ]]; then
+  DIST_FILE="$TMP/exp/Distribution.xml"
+fi
+check has-distribution test -n "$DIST_FILE" -a -s "${DIST_FILE:-/dev/null}"
+check title-verae grep -q 'Verae Print Stamp' "$DIST_FILE"
+check product-id grep -q 'ai.verae.print-stamp' "$DIST_FILE"
+check license-ref grep -qi 'license' "$DIST_FILE"
+check welcome-ref grep -qi 'welcome' "$DIST_FILE"
+check readme-ref grep -qi 'readme' "$DIST_FILE"
+check background-ref grep -qi 'background' "$DIST_FILE"
+
+check welcome-html has_file welcome.html
+check license-html has_file license.html
+check readme-html has_file readme.html
+check conclusion-html has_file conclusion.html
+check background-png has_file background.png
+
+WELCOME="$(find_one welcome.html)"
+LICENSE="$(find_one license.html)"
+README="$(find_one readme.html)"
+check welcome-branding grep -Eq '531B59|Verae branded|Product ID' "$WELCOME"
+check license-accept grep -Eiq 'accept|Agree|License Agreement' "$LICENSE"
+check readme-product-id grep -q 'ai.verae.print-stamp' "$README"
+
+echo "════════════════════════════════"
+echo " installer-ui PASS=$pass FAIL=$fail"
+[[ "$fail" -eq 0 ]]