diff --git a/assets/AppIcon.icns b/assets/AppIcon.icns
deleted file mode 100644
index aa6206cf..00000000
Binary files a/assets/AppIcon.icns and /dev/null differ
diff --git a/assets/README.md b/assets/README.md
new file mode 100644
index 00000000..098ee7d4
--- /dev/null
+++ b/assets/README.md
@@ -0,0 +1,34 @@
+# Assets Directory
+
+## File Structure
+
+```text
+assets/
+├── AppIcon.png              # Mac master source (1024x1024) - for icns generation & SetApp
+├── prep-icons.sh            # Generate icon.icns from AppIcon.png
+├── README.md                # This file
+│
+├── icon.icns                # Mac app icon (generated by prep-icons.sh)
+├── icon.ico                 # Windows app icon
+├── icon.png                 # Linux/Windows BrowserWindow icon (256x256)
+├── iconTemplate.png         # macOS tray icon
+├── iconTemplate@2x.png      # macOS tray icon (Retina)
+├── iconTemplate@2x.ico      # Windows tray icon (high DPI)
+│
+├── icons/                   # Linux icons ONLY (electron-builder auto-uses)
+│   ├── 16x16.png
+│   ├── 32x32.png
+│   ├── 64x64.png
+│   ├── 128x128.png
+│   ├── 256x256.png
+│   ├── 512x512.png
+│   └── 1024x1024.png
+│
+├── entitlements.mac.plist   # macOS entitlements for code signing
+├── requirement.rqset        # macOS code signing requirements
+└── assets.d.ts              # TypeScript declarations for asset imports
+```
+
+## Regenerating macOS Icons
+
+After updating `AppIcon.png`, run `prep-icons.sh`.
diff --git a/assets/icon.icns b/assets/icon.icns
index 2fda15af..91728f4c 100644
Binary files a/assets/icon.icns and b/assets/icon.icns differ
diff --git a/assets/icon.svg b/assets/icon.svg
deleted file mode 100644
index 2df6fa76..00000000
--- a/assets/icon.svg
+++ /dev/null
@@ -1,29 +0,0 @@
-<svg width="251" height="251" viewBox="0 0 251 251" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M124.754 246.086V188.404C104.851 188.696 83.1008 187.109 60.5075 182.5L60.4009 182.397V216.767C60.4009 223.635 61.1406 229.181 62.62 233.408C64.0994 237.634 66.1952 240.935 68.9074 243.312C71.8662 245.69 75.4413 247.274 79.6329 248.067C84.0711 249.123 89.1256 249.652 94.7966 249.652C100.468 249.652 106.138 249.255 111.809 248.463C117.727 247.671 122.042 246.878 124.754 246.086Z" fill="url(#paint0_linear_4_4180)"/>
-<path d="M124.754 170.016H127.495C152.798 169.506 180.396 165.746 203.918 154.985L203.901 154.961C214.75 148.622 224.119 139.641 232.009 128.019C239.899 116.398 243.844 102.399 243.844 86.0225C243.844 59.8735 235.214 39.1392 217.955 23.8196C200.696 8.50001 175.053 0.84021 141.027 0.84021C128.452 0.84021 116.617 1.63261 105.522 3.21739C94.4267 4.53804 84.6875 6.78317 76.3043 9.95275C71.373 11.8017 67.428 14.3109 64.4692 17.4805C61.757 20.3859 60.4009 24.612 60.4009 30.1588V96.5946C71.7283 98.3286 114.728 102.044 124.384 101.633V57.8925C127.096 57.3642 129.562 56.9681 131.781 56.7039C134 56.4398 136.959 56.3077 140.657 56.3077C153.725 56.3077 163.218 58.949 169.135 64.2317C175.3 69.2502 178.382 76.7779 178.382 86.8148C178.382 96.8518 175.669 104.512 170.245 109.794C164.821 114.813 157.424 117.322 148.054 117.322H124.384V117.111C124.32 117.212 124.261 117.314 124.207 117.417C88.3261 115.69 66.5386 114.167 60.3868 113.304L60.3863 113.294L43.3402 111.6C41.784 111.446 40.6464 110.059 40.7993 108.502L41.7222 99.1087C41.9889 96.3938 38.6401 94.905 36.8074 96.9237L1.23285 136.109C0.259475 137.181 0.253063 138.816 1.21799 139.898L29.7951 171.938C31.4378 173.779 34.4836 172.788 34.7247 170.334L35.3876 163.587C35.5482 161.951 37.063 160.797 38.6828 161.076L60.4009 164.816V164.948L60.5075 164.841C73.7953 167.081 97.8246 170.358 124.754 170.059V170.016Z" fill="url(#paint1_linear_4_4180)"/>
-<path d="M175.423 223.503L153.991 186.604C181.833 183.575 203.841 177.365 216.13 172.399C220.842 178.965 225.519 185.303 230.16 191.411C238.79 202.768 245.57 213.069 250.501 222.314C248.036 231.559 243.474 238.69 236.817 243.709C230.406 248.463 223.133 250.84 214.996 250.84C209.572 250.84 204.887 250.18 200.942 248.859C196.997 247.539 193.545 245.69 190.586 243.312C187.628 240.935 184.916 238.03 182.45 234.596C179.984 231.162 177.642 227.465 175.423 223.503Z" fill="url(#paint2_linear_4_4180)"/>
-<path d="M0.499023 138.067C0.512121 138.723 0.751586 139.375 1.21791 139.897L29.795 171.938C31.4377 173.779 34.4835 172.788 34.7247 170.334L35.3875 163.587C35.5482 161.951 37.0629 160.797 38.6827 161.076L60.4009 164.816V164.948L60.5074 164.841C73.7953 167.08 97.8245 170.358 124.754 170.059V170.016H125.296V145.058L0.499023 138.067Z" fill="url(#paint3_linear_4_4180)"/>
-<path d="M125.296 145.058L0.499104 138.067C0.485099 137.367 0.729882 136.663 1.23285 136.109L36.8074 96.9237C38.6401 94.905 41.9889 96.3939 41.7222 99.1087L40.7993 108.502C40.6464 110.059 41.784 111.446 43.3402 111.6L60.3863 113.294L60.3868 113.304C66.5386 114.167 88.3261 115.69 124.207 117.417C124.261 117.314 124.32 117.212 124.384 117.111V117.322H125.296V145.058Z" fill="url(#paint4_linear_4_4180)"/>
-<defs>
-<linearGradient id="paint0_linear_4_4180" x1="58.6395" y1="-23.1891" x2="206.763" y2="302.735" gradientUnits="userSpaceOnUse">
-<stop stop-color="#1EA0FF"/>
-<stop offset="1" stop-color="#004EEB"/>
-</linearGradient>
-<linearGradient id="paint1_linear_4_4180" x1="58.6395" y1="-23.1891" x2="206.763" y2="302.735" gradientUnits="userSpaceOnUse">
-<stop stop-color="#1EA0FF"/>
-<stop offset="1" stop-color="#004EEB"/>
-</linearGradient>
-<linearGradient id="paint2_linear_4_4180" x1="58.6395" y1="-23.1891" x2="206.763" y2="302.735" gradientUnits="userSpaceOnUse">
-<stop stop-color="#1EA0FF"/>
-<stop offset="1" stop-color="#004EEB"/>
-</linearGradient>
-<linearGradient id="paint3_linear_4_4180" x1="186.137" y1="154.698" x2="82.1848" y2="127.558" gradientUnits="userSpaceOnUse">
-<stop stop-color="#1EA0FF"/>
-<stop offset="1" stop-color="#004EEB"/>
-</linearGradient>
-<linearGradient id="paint4_linear_4_4180" x1="40.8111" y1="78.6602" x2="230.354" y2="102.909" gradientUnits="userSpaceOnUse">
-<stop stop-color="#1EA0FF"/>
-<stop offset="1" stop-color="#004EEB"/>
-</linearGradient>
-</defs>
-</svg>
diff --git a/assets/prep-icons.sh b/assets/prep-icons.sh
new file mode 100755
index 00000000..afbd745d
--- /dev/null
+++ b/assets/prep-icons.sh
@@ -0,0 +1,46 @@
+#!/usr/bin/env sh
+
+# Generate icon.icns from AppIcon.png for macOS
+# This script creates a temporary iconset folder, generates all required sizes,
+# converts to icns, then cleans up.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SOURCE="$SCRIPT_DIR/AppIcon.png"
+OUTPUT="$SCRIPT_DIR/icon.icns"
+ICONSET="$SCRIPT_DIR/icon.iconset"
+
+if [ ! -f "$SOURCE" ]; then
+  echo "Error: Source file not found: $SOURCE"
+  exit 1
+fi
+
+echo "Generating icon.icns from AppIcon.png..."
+
+# Remove existing iconset if present
+rm -rf "$ICONSET"
+mkdir "$ICONSET"
+
+# Generate all required icon sizes for macOS
+# Format: filename - size
+# @2x variants are double the base size
+
+sips -z 16 16     "$SOURCE" --out "$ICONSET/icon_16x16.png"
+sips -z 32 32     "$SOURCE" --out "$ICONSET/icon_16x16@2x.png"
+sips -z 32 32     "$SOURCE" --out "$ICONSET/icon_32x32.png"
+sips -z 64 64     "$SOURCE" --out "$ICONSET/icon_32x32@2x.png"
+sips -z 128 128   "$SOURCE" --out "$ICONSET/icon_128x128.png"
+sips -z 256 256   "$SOURCE" --out "$ICONSET/icon_128x128@2x.png"
+sips -z 256 256   "$SOURCE" --out "$ICONSET/icon_256x256.png"
+sips -z 512 512   "$SOURCE" --out "$ICONSET/icon_256x256@2x.png"
+sips -z 512 512   "$SOURCE" --out "$ICONSET/icon_512x512.png"
+sips -z 1024 1024 "$SOURCE" --out "$ICONSET/icon_512x512@2x.png"
+
+# Convert to icns (macOS only)
+iconutil -c icns "$ICONSET" -o "$OUTPUT"
+
+# Clean up
+rm -rf "$ICONSET"
+
+echo "Successfully generated: $OUTPUT"