@@ -39,10 +39,23 @@ Follow conventional commits: `<type>: <subject>`
 - [ ] I've tested my changes locally
 - [ ] I've followed the code principles (SOLID, DRY, KISS)
 - [ ] My PR is small and focused (< 400 lines ideally)
+- [ ] **(Python only)** All file operations specify `encoding="utf-8"` for text files
+
+## Platform Testing Checklist
+
+**CRITICAL:** This project supports Windows, macOS, and Linux. Platform-specific bugs are a common source of breakage.
+
+- [ ] **Windows tested** (either on Windows or via CI)
+- [ ] **macOS tested** (either on macOS or via CI)
+- [ ] **Linux tested** (CI covers this)
+- [ ] Used centralized `platform/` module instead of direct `process.platform` checks
+- [ ] No hardcoded paths (used `findExecutable()` or platform abstractions)
+
+**If you only have access to one OS:** CI now tests on all platforms. Ensure all checks pass before submitting.
 
 ## CI/Testing Requirements
 
-- [ ] All CI checks pass
+- [ ] All CI checks pass on **all platforms** (Windows, macOS, Linux)
 - [ ] All existing tests pass
 - [ ] New features include test coverage
 - [ ] Bug fixes include regression tests
 
@@ -0,0 +1,160 @@
+name: 'Finalize macOS Notarization'
+description: 'Wait for Apple notarization to complete and staple tickets to DMG files'
+
+inputs:
+  apple-id:
+    description: 'Apple ID for notarization'
+    required: true
+  apple-app-specific-password:
+    description: 'Apple app-specific password'
+    required: true
+  apple-team-id:
+    description: 'Apple Team ID'
+    required: true
+  intel-notarization-id:
+    description: 'Notarization request ID for Intel build'
+    required: false
+    default: ''
+  arm64-notarization-id:
+    description: 'Notarization request ID for ARM64 build'
+    required: false
+    default: ''
+  intel-dmg-file:
+    description: 'Filename of the Intel DMG'
+    required: false
+    default: ''
+  arm64-dmg-file:
+    description: 'Filename of the ARM64 DMG'
+    required: false
+    default: ''
+  intel-artifact-path:
+    description: 'Path to Intel build artifacts'
+    required: false
+    default: 'intel'
+  arm64-artifact-path:
+    description: 'Path to ARM64 build artifacts'
+    required: false
+    default: 'arm64'
+  timeout:
+    description: 'Timeout in seconds for notarization wait'
+    required: false
+    default: '3600'
+
+outputs:
+  intel-stapled:
+    description: 'Whether Intel DMG was successfully stapled'
+    value: ${{ steps.staple.outputs.intel_stapled }}
+  arm64-stapled:
+    description: 'Whether ARM64 DMG was successfully stapled'
+    value: ${{ steps.staple.outputs.arm64_stapled }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Wait for notarization and staple
+      id: staple
+      shell: bash
+      env:
+        APPLE_ID: ${{ inputs.apple-id }}
+        APPLE_APP_SPECIFIC_PASSWORD: ${{ inputs.apple-app-specific-password }}
+        APPLE_TEAM_ID: ${{ inputs.apple-team-id }}
+        INTEL_NOTARIZATION_ID: ${{ inputs.intel-notarization-id }}
+        ARM64_NOTARIZATION_ID: ${{ inputs.arm64-notarization-id }}
+        INTEL_DMG: ${{ inputs.intel-dmg-file }}
+        ARM64_DMG: ${{ inputs.arm64-dmg-file }}
+        INTEL_PATH: ${{ inputs.intel-artifact-path }}
+        ARM64_PATH: ${{ inputs.arm64-artifact-path }}
+        TIMEOUT: ${{ inputs.timeout }}
+      run: |
+        intel_stapled=false
+        arm64_stapled=false
+
+        if [ -z "$APPLE_ID" ]; then
+          echo "Skipping notarization wait: APPLE_ID not configured"
+          echo "intel_stapled=false" >> "$GITHUB_OUTPUT"
+          echo "arm64_stapled=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        # Warn if no notarization IDs provided (could indicate submission failure)
+        if [ -z "$INTEL_NOTARIZATION_ID" ] && [ -z "$ARM64_NOTARIZATION_ID" ]; then
+          echo "::warning::No notarization IDs provided - nothing to finalize. Check if notarization submission succeeded."
+          echo "intel_stapled=false" >> "$GITHUB_OUTPUT"
+          echo "arm64_stapled=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        # Wait for Intel notarization
+        if [ -n "$INTEL_NOTARIZATION_ID" ]; then
+          echo "Waiting for Intel notarization: $INTEL_NOTARIZATION_ID"
+          if ! xcrun notarytool wait "$INTEL_NOTARIZATION_ID" \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_APP_SPECIFIC_PASSWORD" \
+            --team-id "$APPLE_TEAM_ID" \
+            --timeout "$TIMEOUT"; then
+            echo "::error::Intel notarization failed or timed out"
+            exit 1
+          fi
+          # Verify notarization was accepted (not just processed)
+          INTEL_STATUS=$(xcrun notarytool info "$INTEL_NOTARIZATION_ID" \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_APP_SPECIFIC_PASSWORD" \
+            --team-id "$APPLE_TEAM_ID" \
+            --output-format json | jq -r '.status // "Unknown"')
+          if [ "$INTEL_STATUS" != "Accepted" ]; then
+            echo "::error::Intel notarization status is '$INTEL_STATUS', expected 'Accepted'"
+            exit 1
+          fi
+          echo "Intel notarization status: $INTEL_STATUS"
+          # Verify DMG file exists before stapling
+          if [ ! -f "$INTEL_PATH/$INTEL_DMG" ]; then
+            echo "::error::Intel DMG not found at $INTEL_PATH/$INTEL_DMG"
+            exit 1
+          fi
+          echo "Stapling Intel DMG: $INTEL_PATH/$INTEL_DMG"
+          if ! xcrun stapler staple "$INTEL_PATH/$INTEL_DMG"; then
+            echo "::error::Failed to staple Intel DMG"
+            exit 1
+          fi
+          echo "Successfully stapled Intel DMG"
+          intel_stapled=true
+        fi
+
+        # Wait for ARM64 notarization
+        if [ -n "$ARM64_NOTARIZATION_ID" ]; then
+          echo "Waiting for ARM64 notarization: $ARM64_NOTARIZATION_ID"
+          if ! xcrun notarytool wait "$ARM64_NOTARIZATION_ID" \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_APP_SPECIFIC_PASSWORD" \
+            --team-id "$APPLE_TEAM_ID" \
+            --timeout "$TIMEOUT"; then
+            echo "::error::ARM64 notarization failed or timed out"
+            exit 1
+          fi
+          # Verify notarization was accepted (not just processed)
+          ARM64_STATUS=$(xcrun notarytool info "$ARM64_NOTARIZATION_ID" \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_APP_SPECIFIC_PASSWORD" \
+            --team-id "$APPLE_TEAM_ID" \
+            --output-format json | jq -r '.status // "Unknown"')
+          if [ "$ARM64_STATUS" != "Accepted" ]; then
+            echo "::error::ARM64 notarization status is '$ARM64_STATUS', expected 'Accepted'"
+            exit 1
+          fi
+          echo "ARM64 notarization status: $ARM64_STATUS"
+          # Verify DMG file exists before stapling
+          if [ ! -f "$ARM64_PATH/$ARM64_DMG" ]; then
+            echo "::error::ARM64 DMG not found at $ARM64_PATH/$ARM64_DMG"
+            exit 1
+          fi
+          echo "Stapling ARM64 DMG: $ARM64_PATH/$ARM64_DMG"
+          if ! xcrun stapler staple "$ARM64_PATH/$ARM64_DMG"; then
+            echo "::error::Failed to staple ARM64 DMG"
+            exit 1
+          fi
+          echo "Successfully stapled ARM64 DMG"
+          arm64_stapled=true
+        fi
+
+        echo "intel_stapled=$intel_stapled" >> "$GITHUB_OUTPUT"
+        echo "arm64_stapled=$arm64_stapled" >> "$GITHUB_OUTPUT"
@@ -0,0 +1,193 @@
+name: 'Merge macOS Manifests'
+description: 'Merge Intel and ARM64 macOS manifests for electron-updater'
+
+inputs:
+  dist-path:
+    description: 'Path to the dist directory containing build artifacts'
+    required: false
+    default: 'dist'
+  output-path:
+    description: 'Path to output the merged manifest'
+    required: false
+    default: 'release-assets'
+  copy-other-manifests:
+    description: 'Whether to copy Windows/Linux manifests as well'
+    required: false
+    default: 'true'
+  yq-version:
+    description: 'Version of yq to use for YAML merging'
+    required: false
+    default: 'v4.44.3'
+
+outputs:
+  merged:
+    description: 'Whether manifests were merged (true) or single architecture used (false)'
+    value: ${{ steps.merge.outputs.merged }}
+  file-count:
+    description: 'Number of files in the merged manifest'
+    value: ${{ steps.validate.outputs.file_count }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Merge macOS manifests
+      id: merge
+      shell: bash
+      env:
+        # yq SHA256 checksum for v4.44.3 linux_amd64
+        # When updating yq-version, update this checksum and the one in validate step
+        YQ_SHA256: "a2c097180dd884a8d50c956ee16a9cec070f30a7947cf4ebf87d5f36213e9ed7"
+      run: |
+        echo "=== Merging macOS update manifests ==="
+
+        # Find all latest-mac.yml files from different build artifacts
+        intel_manifest=$(find "${{ inputs.dist-path }}" -path "*/macos-intel-builds/latest-mac.yml" -type f 2>/dev/null | head -1)
+        arm64_manifest=$(find "${{ inputs.dist-path }}" -path "*/macos-arm64-builds/latest-mac.yml" -type f 2>/dev/null | head -1)
+
+        echo "Intel manifest: ${intel_manifest:-not found}"
+        echo "ARM64 manifest: ${arm64_manifest:-not found}"
+
+        mkdir -p "${{ inputs.output-path }}"
+
+        if [ -n "$intel_manifest" ] && [ -n "$arm64_manifest" ]; then
+          echo "Both architectures found - merging manifests..."
+          echo "merged=true" >> "$GITHUB_OUTPUT"
+
+          # Install yq for YAML merging (pinned version with checksum verification)
+          YQ_VERSION="${{ inputs.yq-version }}"
+          YQ_URL="https://github.com/mikefarah/yq/releases/download/${YQ_VERSION}/yq_linux_amd64"
+
+          echo "Downloading yq ${YQ_VERSION}..."
+          if ! wget -qO /tmp/yq "$YQ_URL"; then
+            echo "::error::Failed to download yq ${YQ_VERSION}"
+            exit 1
+          fi
+
+          # Verify checksum
+          echo "Verifying yq checksum..."
+          ACTUAL_SHA256=$(sha256sum /tmp/yq | cut -d' ' -f1)
+          if [ "$ACTUAL_SHA256" != "$YQ_SHA256" ]; then
+            echo "::error::yq checksum verification failed!"
+            echo "Expected: $YQ_SHA256"
+            echo "Actual:   $ACTUAL_SHA256"
+            rm -f /tmp/yq
+            exit 1
+          fi
+          echo "Checksum verified successfully"
+
+          sudo mv /tmp/yq /usr/local/bin/yq
+          sudo chmod +x /usr/local/bin/yq
+          echo "Installed yq version:"
+          yq --version
+
+          # Merge the files arrays from both manifests using eval-all
+          # This avoids shell expansion issues with multiline YAML
+          yq eval-all '
+            select(fileIndex == 0) * {"files": ([.[].files] | add)}
+          ' "$intel_manifest" "$arm64_manifest" > "${{ inputs.output-path }}/latest-mac.yml"
+
+          echo "Merged manifest contents:"
+          cat "${{ inputs.output-path }}/latest-mac.yml"
+
+        elif [ -n "$intel_manifest" ]; then
+          echo "Only Intel manifest found - using as-is"
+          echo "merged=false" >> "$GITHUB_OUTPUT"
+          cp "$intel_manifest" "${{ inputs.output-path }}/latest-mac.yml"
+        elif [ -n "$arm64_manifest" ]; then
+          echo "Only ARM64 manifest found - using as-is"
+          echo "merged=false" >> "$GITHUB_OUTPUT"
+          cp "$arm64_manifest" "${{ inputs.output-path }}/latest-mac.yml"
+        else
+          echo "::error::No macOS manifests found - this will cause auto-update to fail"
+          exit 1
+        fi
+
+    - name: Validate merged manifest
+      id: validate
+      shell: bash
+      env:
+        # Single source of truth for yq checksum - must match merge step
+        YQ_SHA256: "a2c097180dd884a8d50c956ee16a9cec070f30a7947cf4ebf87d5f36213e9ed7"
+      run: |
+        manifest_file="${{ inputs.output-path }}/latest-mac.yml"
+
+        echo "=== Validating merged manifest ==="
+
+        # Check file exists
+        if [ ! -f "$manifest_file" ]; then
+          echo "::error::Merged manifest file not found at $manifest_file"
+          exit 1
+        fi
+
+        # Install yq if not already installed (for single-arch case)
+        if ! command -v yq &> /dev/null; then
+          YQ_VERSION="${{ inputs.yq-version }}"
+          YQ_URL="https://github.com/mikefarah/yq/releases/download/${YQ_VERSION}/yq_linux_amd64"
+
+          echo "Downloading yq ${YQ_VERSION}..."
+          wget -qO /tmp/yq "$YQ_URL"
+
+          # Verify checksum (YQ_SHA256 from env)
+          ACTUAL_SHA256=$(sha256sum /tmp/yq | cut -d' ' -f1)
+          if [ "$ACTUAL_SHA256" != "$YQ_SHA256" ]; then
+            echo "::error::yq checksum verification failed!"
+            echo "Expected: $YQ_SHA256"
+            echo "Actual:   $ACTUAL_SHA256"
+            exit 1
+          fi
+
+          sudo mv /tmp/yq /usr/local/bin/yq
+          sudo chmod +x /usr/local/bin/yq
+        fi
+
+        # Validate YAML is parseable
+        if ! yq eval '.' "$manifest_file" > /dev/null 2>&1; then
+          echo "::error::Merged manifest is not valid YAML"
+          cat "$manifest_file"
+          exit 1
+        fi
+        echo "YAML syntax is valid"
+
+        # Count files in manifest
+        file_count=$(yq eval '.files | length' "$manifest_file")
+        echo "file_count=$file_count" >> "$GITHUB_OUTPUT"
+        echo "Manifest contains $file_count file entries"
+
+        # Validate file count
+        if [ "$file_count" -eq 0 ]; then
+          echo "::error::Merged manifest contains no files"
+          exit 1
+        fi
+
+        # If we merged both architectures, expect at least 2 files (one per arch)
+        if [ "${{ steps.merge.outputs.merged }}" = "true" ] && [ "$file_count" -lt 2 ]; then
+          echo "::warning::Merged manifest has fewer than 2 files - merge may have failed"
+        fi
+
+        # Validate required fields exist
+        if ! yq eval '.version' "$manifest_file" | grep -q .; then
+          echo "::error::Manifest missing 'version' field"
+          exit 1
+        fi
+        echo "Version field present: $(yq eval '.version' "$manifest_file")"
+
+        echo "Manifest validation passed"
+
+    - name: Copy other manifests
+      if: inputs.copy-other-manifests == 'true'
+      shell: bash
+      run: |
+        echo "=== Copying other update manifests ==="
+
+        # Copy other manifests (Windows, Linux) - these don't have the duplicate issue
+        for manifest in latest.yml latest-linux.yml latest-linux-arm64.yml; do
+          found=$(find "${{ inputs.dist-path }}" -name "$manifest" -type f 2>/dev/null | head -1)
+          if [ -n "$found" ]; then
+            echo "Copying $manifest"
+            cp "$found" "${{ inputs.output-path }}/"
+          fi
+        done
+
+        echo ""
+        echo "=== Manifest files in ${{ inputs.output-path }} ==="
+        ls -la "${{ inputs.output-path }}"/*.yml 2>/dev/null || echo "No manifest files found"