docs: add Troubleshooting section to README

README.md

@@ -290,6 +290,59 @@ sudo systemctl daemon-reload
 
 ---
 
+## Troubleshooting
+
+### LCD shows garbled symbols or nothing at all
+
+The contrast is set by a trim potentiometer on the back of the I2C backpack. Turn it until text becomes visible. This is a hardware-only setting with no software equivalent.
+
+### LCD shows `Connecting... / Please wait` indefinitely
+
+The weather fetch is failing. Check:
+
+```sh
+journalctl -u weather-display -n 50
+```
+
+Common causes:
+- `WEATHER_API_KEY` is missing or invalid — verify it in `.env`
+- `WEATHER_LOCATION` is not set — the app has no city to look up
+- No network connectivity on the Pi
+
+### I2C devices not detected (`i2cdetect` shows nothing)
+
+```sh
+sudo i2cdetect -y 1
+```
+
+- Expected: `0x27` (LCD backpack) and `0x3C` (OLED) visible
+- If absent: check wiring and confirm I2C is enabled (`sudo raspi-config nonint do_i2c 0`, then reboot)
+- On Pi 5, the I2C bus may be `/dev/i2c-1` or `/dev/i2c-0` — try both
+
+### NeoPixel ring stays dark or flickers
+
+- The data wire must be on **GPIO 10 (SPI0 MOSI, header pin 19)** — any other pin will not work
+- Confirm SPI is enabled: `sudo raspi-config nonint do_spi 0`
+- Confirm the `spi` group membership: `id $USER` should include `spi`. If not, run `sudo usermod -aG spi $USER` and log out/in
+
+### Email alerts not arriving
+
+- Verify `GMAIL_USER`, `GMAIL_APP_PASSWORD`, and `ALERT_RECIPIENT` in `.env`
+- `GMAIL_APP_PASSWORD` must be a 16-character Google App Password, not your regular password — generate one at https://myaccount.google.com/apppasswords
+- Use `ENGINEERING_MODE=1` during development to suppress outbound email while you iterate
+
+### Service won't start
+
+```sh
+systemctl status weather-display
+journalctl -u weather-display -b
+```
+
+- Confirm the binary is at `/usr/local/bin/weather_display` (`sudo make install-service` installs it there)
+- Confirm `.env` is at the project root and readable by the service user
+
+---
+
 ## Dependencies
 
 - `wiringPi` (I2C access on the Pi)