diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 02849c5..57b2e81 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,8 +1,9 @@
 name: CI
 
-# Host-side tests for the three components. None of these need real hardware or
-# a mixer — they exercise the pure logic that is deliberately split out from the
-# platform/IO code (cli/*_logic.c, esp32 X32Link logic, ToastSaverCore).
+# Host-side tests for the three components (no hardware/mixer needed — pure logic
+# split out from the platform/IO code), plus an arduino-cli compile of the X32Link
+# firmware so a change that passes host tests but breaks the real Arduino build
+# (missing include, Arduino-only API, flash overflow) is caught before merge.
 on:
   push:
     branches: [master]
@@ -35,3 +36,45 @@ jobs:
       - uses: actions/checkout@v4
       - name: swift test
         run: swift test --package-path ios/ToastSaverCore
+
+  firmware-compile:
+    name: Firmware compile (X32Link)
+    runs-on: ubuntu-latest
+    env:
+      FQBN: esp32:esp32:esp32s3:USBMode=hwcdc,CDCOnBoot=cdc,FlashSize=16M,PSRAM=opi
+    steps:
+      - uses: actions/checkout@v4
+
+      # The ESP32 core + toolchain is a large download; cache it so only the
+      # first run (or a core bump) pays the ~2-3 min install cost.
+      - name: Cache arduino-cli data
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.arduino15
+            ~/Arduino
+          key: arduino-esp32-${{ runner.os }}-v1
+
+      - name: Install arduino-cli
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh -s
+          echo "$GITHUB_WORKSPACE/bin" >> "$GITHUB_PATH"
+
+      - name: Install ESP32 core + LovyanGFX
+        run: |
+          arduino-cli config init --additional-urls https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
+          arduino-cli core update-index
+          arduino-cli core install esp32:esp32
+          arduino-cli lib install LovyanGFX
+
+      # Headless / non-display build (build_opt.h is empty at HEAD).
+      - name: Compile X32Link (headless)
+        run: arduino-cli compile --fqbn "$FQBN" esp32/X32Link
+
+      # Waveshare touch board — the real deployment. build_opt.h carries the
+      # board flag as Arduino build options; write it just for this compile.
+      - name: Compile X32Link (Waveshare touch board)
+        run: |
+          echo '-DBOARD_WAVESHARE_S3_TOUCH_LCD_147' > esp32/X32Link/build_opt.h
+          arduino-cli compile --fqbn "$FQBN" esp32/X32Link
+          git checkout -- esp32/X32Link/build_opt.h