feat(docs): update LSP setup instructions for compile_commands.json

.clangd

@@ -1,36 +0,0 @@
-CompileFlags:
-  Add:
-    - "-I/home/david/.arduino15/packages/esp32/hardware/esp32/3.3.7/cores/esp32"
-    - "-I/home/david/.arduino15/packages/esp32/tools/esp32-libs/3.3.7/include"
-    - "-I/home/david/.arduino15/packages/esp32/hardware/esp32/3.3.7/libraries/WiFi/src"
-    - "-I/home/david/.arduino15/packages/esp32/hardware/esp32/3.3.7/libraries/EEPROM/src"
-    - "-I/home/david/.arduino15/packages/esp32/hardware/esp32/3.3.7/libraries/HTTPClient/src"
-    - "-I/home/david/.arduino15/packages/esp32/hardware/esp32/3.3.7/libraries/Network/src"
-    - "-I/home/david/.arduino15/packages/esp32/hardware/esp32/3.3.7/libraries/NetworkClientSecure/src"
-    - "-I/home/david/.arduino15/packages/esp32/hardware/esp32/3.3.7/libraries/NTPClient/src"
-    - "-I/home/david/Arduino/libraries/ArduinoJson/src"
-    - "-I/home/david/Arduino/libraries/TFT_eSPI"
-    - "-I/home/david/Arduino/sketches/doorbell-touch/vendor/esp32-s3-lcd-43/LovyanGFX/src"
-    - "-I/home/david/Arduino/sketches/doorbell-touch/libraries/KlubhausCore/src"
-    - "-I/home/david/Arduino/sketches/doorbell-touch/boards/esp32-32e-4"
-    - "-DARDUINO=200"
-    - "-DESC32"
-    - "-DESP_PLATFORM"
-    - "-Dcore_debug=0"
-    - "-DARDUINO_ESP32_DEV"
-  Remove:
-    - "-fno-tree-switch-conversion"
-    - "-fstrict-volatile-bitfields"
-    - "-mdisable-hardware-atomics"
-    - "-mlongcalls"
-
-Diagnostics:
-  ClangTidy:
-    Add:
-      - modernize-*
-      - performance-*
-      - readability-*
-      - bugprone-*
-    Remove:
-      - modernize-use-trailing-return-type
-      - readability-magic-numbers

.gitignore

@@ -15,3 +15,4 @@ vendor/esp32-s3-lcd-43/GFX_Library_for_Arduino/
 *.swo
 *~
 .DS_Store
+compile_commands.json

AGENTS.md

@@ -254,7 +254,7 @@ The monitor daemon automatically starts after upload and is killed before upload
 
 3. **No unit tests**: This is an embedded Arduino sketch — no test suite exists. Verify changes by building and deploying to hardware.
 
-4. **LSP errors are expected**: The LSP cannot find `Arduino.h` because it requires arduino-cli to resolve. Ignore clangd/IntelliSense errors about missing Arduino types; builds work correctly via arduino-cli.
+4. **LSP errors are expected**: The LSP may show errors about missing Arduino types until `compile_commands.json` is generated. Run `mise run gen-compile-commands` first, then restart the LSP. The build works correctly via arduino-cli.
 
 5. **Build artifacts in board dirs**: Build output goes to `boards/[board]/build/` — cleaned by `mise run clean`.
 
@@ -328,7 +328,7 @@ Track changes that were reverted to avoid flapping:
 | "Another instance is running" error | Run `mise run kill BOARD=<board>` or `FORCE=1 mise run <task> BOARD=<board>` |
 | Upload fails - port in use | Run `mise run kill` to stop monitor daemon and release port |
 | Build fails - missing libraries | Run `mise run install-libs-shared` then `BOARD=<board> mise run install` |
-| LSP shows errors but build works | LSP cannot resolve Arduino types without arduino-cli; ignore clangd errors |
+| LSP shows errors but build works | Run `mise run gen-compile-commands` to generate compile_commands.json for your BOARD |
 | No serial output | Check baud rate is set to 115200 in serial monitor |
 | State file not updating | Ensure serial output contains `[STATE]` or `[ADMIN]` tags |
 
@@ -347,21 +347,10 @@ When uncertain about CLI tool flags or argument syntax:
 
 ## LSP / IDE Configuration
 
-The project uses clangd for C++ and arduino-language-server for Arduino. The `.crush.json` contains dynamic FQBN resolution:
+The project uses **clangd** for C++ via the `compile_commands.json` generated by arduino-cli:
 
-```json
+- `mise run gen-compile-commands` regenerates the compile database (automatically run as part of `compile`)
-{
+- The generated `compile_commands.json` includes all necessary includes, defines, and library paths for your BOARD
-  "lsp": {
-    "arduino": {
-      "command": "arduino-language-server",
-      "args": ["-fqbn", "$(cat boards/${BOARD:-esp32-32e-4}/board-config.sh | grep '^FQBN=' | cut -d'\"' -f2)"]
-    },
-    "cpp": {
-      "command": "clangd"
-    }
-  }
-}
-```
 
 **Generate compile_commands.json** for accurate IDE diagnostics:
 

mise.toml

@@ -20,6 +20,7 @@ pkl = "latest"
 
 [tasks.compile]
 description = "Compile (uses BOARD env var)"
+depends = ["gen-compile-commands"]
 run = """
 source ./boards/$BOARD/board-config.sh
 arduino-cli compile --fqbn "$FQBN" --libraries ./libraries $LIBS --build-property "compiler.cpp.extra_flags=$OPTS" --warnings default ./boards/$BOARD
@@ -185,9 +186,9 @@ description = "Generate compile_commands.json for LSP (uses BOARD env var)"
 run = """
 rm -rf /tmp/arduino-build
 source ./boards/$BOARD/board-config.sh
-arduino-cli compile --only-compilation-database --fqbn "$FQBN" --build-path /tmp/arduino-build ./boards/$BOARD
+arduino-cli compile --only-compilation-database --fqbn "$FQBN" --libraries ./libraries $LIBS --build-property "compiler.cpp.extra_flags=$OPTS" --build-path /tmp/arduino-build ./boards/$BOARD
 cp /tmp/arduino-build/compile_commands.json .
-echo "[OK] compile_commands.json generated"
+echo "[OK] Generated compile_commands.json for $BOARD"
 """
 
 [tasks.gen-crush-config]