refactor(sketch): update build configuration and remove obsolete files

sketches/doorbell-touch/.clangd

@@ -18,6 +18,11 @@ CompileFlags:
     - "-DESP_PLATFORM"
     - "-Dcore_debug=0"
     - "-DARDUINO_ESP32_DEV"
+  Remove:
+    - "-fno-tree-switch-conversion"
+    - "-fstrict-volatile-bitfields"
+    - "-mdisable-hardware-atomics"
+    - "-mlongcalls"
 
 Diagnostics:
   ClangTidy:

sketches/doorbell-touch/.crush.json

@@ -1,11 +0,0 @@
-{
-  "lsp": {
-    "arduino": {
-      "command": "arduino-language-server",
-      "args": [
-        "-fqbn",
-        "$(cat boards/${BOARD:-esp32-32e-4}/board-config.sh | grep '^FQBN=' | cut -d'\"' -f2)"
-      ]
-    }
-  }
-}

sketches/doorbell-touch/AGENTS.md

@@ -72,7 +72,26 @@ mise run monitor-raw           # raw serial monitor (arduino-cli)
 mise run monitor-tio           # show tio command for terminal UI
 ```
 
-**Upload port override**: `PORT=/dev/ttyXXX BOARD=esp32-32e mise run upload`
+# Board Configuration Files
+
+Each board directory contains `board-config.sh` which defines:
+
+| Variable | Description |
+|----------|-------------|
+| `FQBN` | Fully Qualified Board Name for arduino-cli |
+| `PORT` | Serial port for upload/monitoring (default: `/dev/ttyUSB0`) |
+| `LIBS` | Vendor library path for `--libraries` flag |
+| `OPTS` | Additional compiler flags (e.g., `-DDEBUG_MODE`) |
+
+**Example** (`boards/esp32-32e-4/board-config.sh`):
+```bash
+FQBN="esp32:esp32:esp32:FlashSize=4M,PartitionScheme=default"
+PORT="/dev/ttyUSB0"
+LIBS="--libraries ./vendor/esp32-32e-4/TFT_eSPI"
+OPTS="-DDEBUG_MODE -DBOARD_HAS_PSRAM"
+```
+
+**Port override**: `PORT=/dev/ttyXXX BOARD=esp32-32e mise run upload`
 
 **Prerequisites**: arduino-cli with `esp32:esp32` platform installed, mise.
 
@@ -191,6 +210,66 @@ The monitor daemon automatically starts after upload and is killed before upload
 
 8. **Lockfile system**: The build system uses lockfiles (`/tmp/doorbell-$BOARD.lock`) to prevent concurrent upload/monitor operations. Use `mise run kill` to clean up stuck processes.
 
+9. **Monitor state parsing**: The monitor-agent parses serial output for state updates:
+   - `[STATE] → DASHBOARD` → updates state file to `"screen":"DASHBOARD"`
+   - `[STATE] → ALERT` → updates state file to `"screen":"ALERT"`
+   - `[STATE] → OFF` → updates state file to `"screen":"OFF"`
+   - `[STATE] → BOOT` → updates state file to `"screen":"BOOT"`
+   - `[ADMIN]` commands also update state accordingly
+
+10. **Serial baud rate**: All serial communication uses 115200 baud.
+
+11. **Lockfile mechanism**: The build system uses `/tmp/doorbell-$BOARD.lock` to prevent concurrent operations. The lockfile script (`scripts/lockfile.sh`) provides `acquire_lock()` and `release_lock()` functions. Use `FORCE=1` to override locks.
+
+## Config Constants
+
+Key timing and configuration values in `Config.h`:
+
+| Constant | Default | Description |
+|----------|---------|-------------|
+| `FW_VERSION` | "5.1" | Firmware version string |
+| `POLL_INTERVAL_MS` | 15000 | How often to poll ntfy.sh for new messages |
+| `HEARTBEAT_INTERVAL_MS` | 300000 | NTP sync interval (5 min) |
+| `ALERT_TIMEOUT_MS` | 120000 | Auto-clear alert after 2 min |
+| `INACTIVITY_TIMEOUT_MS` | 30000 | Turn off display after 30s of inactivity |
+| `HOLD_TO_SILENCE_MS` | 3000 | Hold duration to silence alert |
+| `LOOP_YIELD_MS` | 10 | Yield to prevent Task Watchdog (configurable) |
+
+## Screen States
+
+The device operates in these states (defined in `ScreenState.h`):
+
+- **BOOT** — Initializing
+- **DASHBOARD** — Normal operation, showing status
+- **ALERT** — Doorbell ring detected, display on
+- **OFF** — Display backlight off (but polling continues)
+
+## Serial Output Tags
+
+The firmware outputs structured tags for the monitor agent:
+
+- `[STATE] → DASHBOARD/ALERT/OFF/BOOT` — State transitions
+- `[ADMIN]` — Admin commands received (dashboard, off, alert, silence, status, reboot)
+- `[TOUCH]` — Touch events (x, y, pressed/released)
+- `[ALERT]` — Alert triggered
+
+## Reverted Changes Log
+
+Track changes that were reverted to avoid flapping:
+
+- 2025-02-18: Initially configured LSP via neovim/mason (`.config/nvim/lua/plugins/arduino.lua`) — user clarified they wanted Crush-native LSP config instead
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "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 |
+| 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 |
+
 ## Known Fixes
 
 - **dashboard/off admin commands reset inactivity timer** (DoorbellLogic.cpp:234,240) — Admin commands like `dashboard` and `off` now reset the inactivity timer so the display doesn't turn off immediately after switching screens.