commit 9e789f5173f41d05e40b405ec02d108ae85a9604
Author: jessikitty <jess.rogerson.29@outlook.com>
Date:   Mon Jan 5 17:36:46 2026 +1100

    Initial commit - Home Assistant Device Assignment System

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dc7722f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+# Home Assistant Device Assignment System
+
+Integrates network device discovery with Home Assistant's person-based control system for dynamic device assignment and OPNsense firewall synchronization.
+
+## 📋 Overview
+
+This system extends your existing Home Assistant person-based device blocking with automatic configuration generation for all discovered network devices. Simply assign devices to family members via dropdown menus, and the firewall rules update automatically.
+
+## 🎯 Features
+
+- **21 Discovered Devices** automatically configured
+- **Dynamic Dashboard** - devices appear/disappear based on assignment
+- **Person-Level Blocking** - block all devices for a person at once
+- **Device-Level Blocking** - block individual devices
+- **Real-Time Sync** - OPNsense firewall updates automatically
+- **MAC Address Management** - stores both wired and wireless MACs
+
+## 📊 Current Device Inventory
+
+### Assigned Devices:
+- **Jess:** 3 devices (LIL-JESS, Jesss-iPad, Jess-Bedroom)
+- **Bella:** 1 device (BLUKITTENS)
+- **Xander:** 1 device (XANDERGAMER)
+- **William:** 0 devices
+- **Parents:** 3 devices (SHIELD, Pioneer AV Receiver, etc.)
+
+### Unassigned Devices:
+- **11 devices** need assignment (5 Apple devices, Nintendo Switch, computers, etc.)
+
+## 🚀 Quick Start
+
+1. Copy files to `/config` directory
+2. Add includes to `configuration.yaml`
+3. Import dashboard YAML
+4. Restart Home Assistant
+5. Open Device Assignment dashboard
+6. Assign devices to family members!
+
+## 📁 Files
+
+- `discovered_devices.yaml` - Device entities (21 devices)
+- `discovered_devices_sensors.yaml` - Device count sensors
+- `discovered_devices_automation.yaml` - OPNsense sync
+- `device_assignment_dashboard.yaml` - Assignment interface
+- `generate_discovered_devices_config.py` - Generator script
+
+## 📖 Full Documentation
+
+See the complete documentation in this repository for:
+- Installation instructions
+- Usage examples
+- Troubleshooting
+- Adding new devices
+
+---
+
+**Repository:** https://gitea.hideawaygaming.com.au/jessikitty/ha-device-assignment