diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..1762ccc
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+## Project Overview
+
+This repository contains ESPHome configuration files for various ESP32-based home automation devices integrated with Home Assistant.
+
+## Repository Structure
+
+- `*.yaml` - ESPHome device configuration files
+- Each YAML file represents a single ESP32 device with its specific configuration
+- Configurations use secrets for sensitive data (WiFi credentials, OTA passwords)
+
+## Device Inventory
+
+1. **ades-office-control-panel.yaml** - Office control panel with LVGL display interface
+2. **ades-office-resistive-control-panel.yaml** - Alternative office panel with resistive touchscreen
+3. **ns-panel-ground-floor.yaml** - Sonoff NS Panel for ground floor controls
+4. **oekoboiler-interface.yaml** - Interface for Oekoboiler (eco-boiler) monitoring/control
+5. **old-phone-doorbell.yaml** - Repurposed old phone as doorbell system
+6. **powermeter.yaml** - Power meter monitoring device
+
+## Technology Stack
+
+- **ESPHome** - ESP32/ESP8266 firmware framework
+- **ESP32** - Microcontroller platform (esp32dev board)
+- **Home Assistant** - Primary home automation platform for integration
+- **LVGL** - Light and Versatile Graphics Library (used in control panels)
+- **OTA Updates** - Over-the-air firmware updates enabled
+
+## Common Patterns
+
+### Device Structure
+Each device configuration typically includes:
+- `substitutions:` - Device-specific variables (name, friendly_name)
+- `esphome:` - Core ESPHome configuration
+- `esp32:` - Hardware platform settings
+- `wifi:` - Network connectivity (uses secrets)
+- `ota:` - Over-the-air update configuration (password-protected)
+- `logger:` - Logging configuration
+- `api:` - Home Assistant API integration (likely present)
+- Component-specific configs (sensors, displays, switches, etc.)
+
+### Secrets Management
+Sensitive data is stored in a secrets file (not in repository):
+- `!secret wifi_ssid`
+- `!secret wifi_password`
+- `!secret ota_password`
+- Additional device-specific secrets
+
+### Communication Protocols
+- **SPI** - Display communication (TFT screens)
+- **I2C** - Sensor communication
+- **WiFi** - Network connectivity and Home Assistant integration
+
+## Development Workflow
+
+Currently, configurations are transmitted "manually" (as noted in README), suggesting:
+- Manual upload to devices via ESPHome dashboard or CLI
+- No automated CI/CD pipeline yet
+- Direct device flashing workflow
+
+## When Working on This Project
+
+1. **Never commit secrets** - Always use `!secret` references
+2. **Test locally first** - ESPHome configurations should be validated before deployment
+3. **Backup configurations** - These files represent physical device configurations
+4. **Check git history** - Recent commits show auto-sync functionality was being developed
+5. **Device-specific testing** - Changes to one YAML only affect that device
+6. **Home Assistant integration** - Changes may require Home Assistant entity updates
+
+## Recent Activity
+
+Git history shows auto-sync functionality in development:
+- `test.yaml` was being used for sync testing (now archived/deleted)
+- Multiple sync test devices were created and removed
+- Suggests move toward automated synchronization workflow
+
+## Useful Commands
+
+```bash
+# Validate a configuration
+esphome config device-name.yaml
+
+# Compile firmware
+esphome compile device-name.yaml
+
+# Upload to device
+esphome upload device-name.yaml
+
+# View logs
+esphome logs device-name.yaml
+```
+
+## Notes for AI Assistance
+
+- Focus on ESPHome best practices and YAML syntax
+- Consider Home Assistant integration implications
+- Respect existing device pin configurations (hardware-specific)
+- Maintain consistent naming conventions across devices
+- Be cautious with GPIO pin assignments (hardware limitations)
+- LVGL configurations are complex - reference ESPHome documentation
diff --git a/README.md b/README.md
index f134f76..f4118f5 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,53 @@
 # ESP-Home-Scripts
 
-Device description files for my ESPHome-devices - currently still transmitted "manually"...
+ESPHome configuration files for ESP32-based home automation devices integrated with Home Assistant.
+
+## Overview
+
+This repository contains device configuration files for various ESPHome devices around my home. Each YAML file represents a complete device configuration that can be compiled and uploaded to the corresponding ESP32 hardware.
+
+## Devices
+
+- **ades-office-control-panel.yaml** - Office control panel with LVGL touchscreen display
+- **ades-office-resistive-control-panel.yaml** - Alternative office control panel with resistive touch
+- **ns-panel-ground-floor.yaml** - Sonoff NS Panel for ground floor home controls
+- **oekoboiler-interface.yaml** - Monitoring and control interface for eco-boiler system
+- **old-phone-doorbell.yaml** - Repurposed vintage phone as smart doorbell
+- **powermeter.yaml** - Real-time power consumption monitoring device
+
+## Setup
+
+1. Install [ESPHome](https://esphome.io/guides/getting_started_command_line.html)
+2. Create a `secrets.yaml` file with your credentials:
+   ```yaml
+   wifi_ssid: "your-wifi-ssid"
+   wifi_password: "your-wifi-password"
+   ota_password: "your-ota-password"
+   # Add other device-specific secrets as needed
+   ```
+3. Validate a configuration:
+   ```bash
+   esphome config device-name.yaml
+   ```
+4. Compile and upload:
+   ```bash
+   esphome run device-name.yaml
+   ```
+
+## Requirements
+
+- ESPHome (latest version recommended)
+- Home Assistant instance for device integration
+- ESP32 development boards (esp32dev)
+- Device-specific hardware (displays, sensors, etc.)
+
+## Notes
+
+- Configurations are currently transmitted manually to devices
+- All sensitive credentials are stored in `secrets.yaml` (not tracked in git)
+- Devices use OTA (Over-The-Air) updates for firmware upgrades
+- Each device integrates with Home Assistant via the native API
+
+## License
+
+See [LICENSE](LICENSE) file for details.