# Doorbell Touch - Build Harness

## Session Handoff Note
⚠️ ALWAYS check `mise.toml` for available build tasks before compiling/uploading. Run `mise tasks` to list.

## Quick Commands
```bash
BOARD=esp32-32e-4 mise run compile   # Compile
BOARD=esp32-32e-4 mise run upload    # Upload (auto-kills monitor)
BOARD=esp32-32e-4 mise run monitor   # Start JSON monitor daemon
BOARD=esp32-32e-4 mise run log-tail  # Watch colored logs
BOARD=esp32-32e-4 mise run cmd COMMAND=dashboard  # Send command
BOARD=esp32-32e-4 mise run state     # Show device state
BOARD=esp32-32e-4 mise run install   # Install libs (shared + board)
```

## Files
- `mise.toml` - Tasks (compile, upload, monitor, log-tail, cmd, state, install, clean)
- `scripts/lockfile.sh` - Lockfile functions (acquire_lock, kill_locked)
- `scripts/monitor-agent.py` - Serial monitor with JSON log + command FIFO
- `scripts/install-shared.sh` - Shared Arduino libs (ArduinoJson, NTPClient)
- `boards/{BOARD}/install.sh` - Board-specific vendor libs

## Monitor Daemon
- JSON log: `/tmp/doorbell-$BOARD.jsonl` - `{"ts":123.456,"line":"..."}`
- State: `/tmp/doorbell-$BOARD-state.json` - `{"screen":"DASHBOARD",...}`
- Cmd: `echo 'dashboard' > /tmp/doorbell-$BOARD-cmd.fifo`

## Boards
- esp32-32e (original 2.8" ILI9341)
- esp32-32e-4 (4" ST7796)
- esp32-s3-lcd-43 (4.3" S3 display)

## Known Fixes
- dashboard/off admin commands now reset inactivity timer (DoorbellLogic.cpp:234,240)

## 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

## Documentation Lookup Rule
When uncertain about CLI tool flags or argument syntax:
1. Run the tool with `-h` or `--help` first
2. If unclear, search for official documentation matching the tool version
3. Prefer checking the tool's own help/docs over guessing
4. For Arduino CLI, check `arduino-cli <command> --help` or official Arduino CLI docs

## Neovim LSP Configuration
For Neovim projects:
- Use Mason + mason-lspconfig to manage LSP installations
- Add LSP configs to `~/.config/nvim/lua/plugins/` as separate plugin files
- Use `on_new_config` for dynamic settings (e.g., BOARD env var → FQBN mapping)
- Example: `~/.config/nvim/lua/plugins/arduino.lua` (arduino-language-server)

## Crush LSP Configuration
- Configure via `.crush.json` in project root (or `$HOME/.config/crush/crush.json` globally)
- Supports env var interpolation: `$BOARD` or `${BOARD}`
- Supports command substitution: `$(cat boards/$BOARD/board-config.sh | grep '^FQBN=' | cut -d'"' -f2)`
- Example for Arduino (auto-detects FQBN from BOARD):
```json
{
  "lsp": {
    "arduino": {
      "command": "arduino-language-server",
      "args": ["-fqbn", "$(cat boards/${BOARD:-esp32-32e-4}/board-config.sh | grep '^FQBN=' | cut -d'\"' -f2)"]
    }
  }
}
```
- Run `mise run gen-crush-config` to regenerate static config