From 6376c5148d88381227019bf61b2009ae088d1f4d Mon Sep 17 00:00:00 2001
From: thekiwismarthome <134335563+thekiwismarthome@users.noreply.github.com>
Date: Fri, 6 Feb 2026 09:48:41 +1300
Subject: [PATCH] Update README.md

---
 README.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 117 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 7ebdf4e..e174edb 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,135 @@
-## Installation
+# Shopping List Manager
 
-### 1. Install via HACS
+A custom Home Assistant integration that provides an enhanced shopping list experience, including a companion Lovelace card for managing items directly from your dashboard.
 
-[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=thekiwismarthome&repository=shopping-list-manager&category=integration)
+---
 
-Click the button above or manually add the custom repository in HACS.
-Restart HA
+## Features
 
-### 2. Add the Card Resource
+- 📋 Manage shopping list items from Home Assistant
+- 🔌 WebSocket-based backend (no polling entities)
+- 🖥️ Custom Lovelace card
+- ⚙️ UI-based configuration (Config Flow)
+- 🚀 Compatible with Home Assistant **2024.8+**
 
-After installing via HACS, add the frontend resource:
+---
 
-1. Go to Settings → Dashboards
-2. Click ⋮ (three dots, top right) → Resources
-3. Click "+ Add Resource"
-4. URL: `/local/community/shopping-list-manager/shopping_list_card.js`
-5. Resource type: JavaScript Module
-6. Click "Create"
+## 1. Installation (HACS)
 
-### 3. Add the Integration
+[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](
+https://my.home-assistant.io/redirect/hacs_repository/?owner=thekiwismarthome&repository=shopping-list-manager&category=integration
+)
 
-[![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=shopping_list_manager)
+Click the button above **or** follow the manual steps below.
 
-Click the button above or manually add via Settings → Devices & Services.
+1. Open **HACS**
+2. Go to **Integrations**
+3. Click **⋮ → Custom repositories**
+4. Add this repository:
+   - **Repository:** `https://github.com/thekiwismarthome/shopping-list-manager`
+   - **Category:** Integration
+5. Install **Shopping List Manager**
+6. **Restart Home Assistant**
+
+---
+
+## 2. Install the Lovelace Card Resource (Required)
+
+The Lovelace card JavaScript file is included with the integration, but **must be copied manually** to the `www` directory so Home Assistant can load it.
+
+### Step 1: Copy the card file
+
+Run the following command (via SSH, Terminal add-on, or container shell):
+
+```bash
+mkdir -p /config/www/community/shopping_list_card && \
+cp /config/custom_components/shopping_list_manager/frontend/shopping_list_card.js \
+   /config/www/community/shopping_list_card/shopping_list_card.js
+```
+
+---
+
+### Step 2: Add the resource to Home Assistant
+
+1. Go to **Settings → Dashboards**
+2. Click **⋮ (top right) → Resources**
+3. Click **Add Resource**
+4. Enter:
+
+```text
+URL: /local/community/shopping_list_card/shopping_list_card.js
+Type: JavaScript Module
+```
+
+5. Click **Create**
+6. Refresh your browser (**Ctrl + F5**)
+
+---
+
+## 3. Add the Integration
+
+[![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](
+https://my.home-assistant.io/redirect/config_flow_start/?domain=shopping_list_manager
+)
+
+Click the button above **or** add it manually:
+
+1. Go to **Settings → Devices & Services**
+2. Click **Add Integration**
+3. Search for **Shopping List Manager**
+4. Follow the setup steps
+
+No YAML configuration is required.
+
+---
+
+## 4. Add the Card to a Dashboard
+
+Add a **Manual** card to your dashboard and use the following YAML:
 
-### 4. Add Card to Dashboard
 ```yaml
 type: custom:shopping-list-card
 title: Shopping List
 list_id: groceries
 ```
 
+Use the **⚙️ cog button** in the card to configure additional settings.
 
-Use the ⚙️ cog button in the card to configure settings.
+---
 
+## Updating
+
+- HACS updates will update the **integration**
+- If the Lovelace card JavaScript changes in a future release, you must **repeat the copy command** above
+
+This is expected behavior for single-repository integrations.
+
+---
+
+## Compatibility Notes
+
+- Designed for **Home Assistant 2024.8+**
+- Uses WebSocket APIs
+- Fully compatible with the **Services → Actions** change introduced in Home Assistant 2024.8
+
+---
+
+## Troubleshooting
+
+If the card does not load:
+
+1. Ensure Home Assistant was restarted after installation
+2. Verify the file exists at:
+
+```
+/config/www/community/shopping_list_card/shopping_list_card.js
+```
+
+3. Confirm the resource URL is correct
+4. Perform a hard browser refresh (**Ctrl + F5**)
+
+---
+
+## License
+
+MIT License