Fix Adaptive mode not restoring lighting conditions

The blueprint was unconditionally overriding use_defaults to 'current',
preventing modes from specifying their own use_defaults value. This caused
Adaptive mode (which uses use_defaults: 'configuration') to keep the current
settings instead of resetting to configuration defaults.

Modified the data template to conditionally add use_defaults: 'current' only
when not already present in al_config, allowing modes like Adaptive to use
their specified value while maintaining backward compatibility.

.gitignore

@@ -0,0 +1,6 @@
+.DS_Store
+.idea
+*.log
+tmp/
+
+thoughts

ADDING_MODES.md

@@ -0,0 +1,453 @@
+# Adding Custom Lighting Modes
+
+This guide teaches you how to add custom lighting modes to your Adaptive Lighting setup. The mode system is **convention-based** - you can add new modes by creating helpers via the UI or editing the global package, with no blueprint code changes required.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start: Adding "Reading" Mode](#quick-start-adding-reading-mode)
+- [Method 1: UI-Created Modes (Recommended)](#method-1-ui-created-modes-recommended)
+- [Method 2: Package-Defined Modes](#method-2-package-defined-modes)
+- [Schema Reference](#schema-reference)
+- [Behavior Types](#behavior-types)
+- [Manual Control](#manual-control)
+- [Advanced Examples](#advanced-examples)
+- [Troubleshooting](#troubleshooting)
+- [Extensibility](#extensibility)
+
+## Overview
+
+The Adaptive Lighting Mode System uses **convention-based entity lookup** to find mode settings. When you switch to a mode (e.g., "Reading"), the blueprint automatically looks for an entity named:
+
+```
+input_text.adaptive_lighting_settings_reading
+```
+
+This means adding a new mode requires:
+1. Creating a helper with the correct naming convention
+2. Adding the mode name to your room's mode selector dropdown
+3. That's it! No blueprint code changes needed.
+
+### Why "Reading" Mode Was Excluded
+
+The default installation includes 8 essential modes: Adaptive, Relaxing, Sleep, Theater, Party, Cooking, Dining, and Cleanup. "Reading" mode was intentionally excluded as a pedagogical example - this tutorial uses it to teach you how to create custom modes yourself.
+
+## Quick Start: Adding "Reading" Mode
+
+Let's add a "Reading" mode with bright, cool white light ideal for reading.
+
+### Step 1: Create the Settings Entity
+
+1. Go to **Settings → Devices & Services → Helpers**
+2. Click **+ Create Helper → Text**
+3. Configure the helper:
+   - **Name**: `Mode: Reading`
+   - **Entity ID**: `input_text.adaptive_lighting_settings_reading`
+   - **Max length**: `255`
+   - **Initial value**:
+   ```json
+   {"behavior":"adaptive_lighting","manual_control":false,"led_color":42,"al_config":{"min_brightness":80,"max_brightness":100,"min_color_temp":4500,"max_color_temp":5500,"transition":2}}
+   ```
+4. Click **Create**
+
+### Step 2: Add to Mode Selector
+
+1. Go to **Settings → Devices & Services → Helpers**
+2. Find your room's lighting mode dropdown (e.g., `input_select.bedroom_lighting_mode`)
+3. Click **Edit**
+4. Add option: `Reading`
+5. Click **Update**
+
+### Step 3: Test
+
+1. Go to your room's mode selector in the UI
+2. Select **Reading**
+3. Verify:
+   - Lights change to bright, cool white (80-100% brightness, 4500-5500K color temp)
+   - LED on Inovelli switch turns yellow (hue 42)
+   - No blueprint modifications were needed!
+
+## Method 1: UI-Created Modes (Recommended)
+
+Creating modes via the UI is recommended because:
+- No restart required (immediate availability)
+- Easy to test and iterate
+- No risk of YAML syntax errors
+- Perfect for experimenting with custom modes
+
+### Naming Convention
+
+The entity ID must follow this pattern:
+```
+input_text.adaptive_lighting_settings_<mode_name_lowercase_underscores>
+```
+
+Examples:
+- Mode name: "Reading" → Entity ID: `input_text.adaptive_lighting_settings_reading`
+- Mode name: "Movie Night" → Entity ID: `input_text.adaptive_lighting_settings_movie_night`
+- Mode name: "Bowling" → Entity ID: `input_text.adaptive_lighting_settings_bowling`
+
+### UI Creation Steps
+
+1. **Settings → Devices & Services → Helpers**
+2. **+ Create Helper → Text**
+3. Configure:
+   - **Name**: `Mode: <Your Mode Name>` (e.g., "Mode: Reading")
+   - **Entity ID**: Follow naming convention above
+   - **Max length**: `255`
+   - **Initial value**: JSON with your mode settings (see Schema Reference below)
+
+### Example: "Focus" Mode
+
+Create a mode for focused work with bright, neutral light:
+
+```json
+{"behavior":"adaptive_lighting","manual_control":false,"led_color":85,"al_config":{"min_brightness":90,"max_brightness":100,"min_color_temp":4000,"max_color_temp":5000,"transition":1}}
+```
+
+## Method 2: Package-Defined Modes
+
+For version-controlled, permanent modes, add them to the global package.
+
+### Editing the Global Package
+
+1. Open `packages/adaptive_lighting_global.yaml`
+2. Add a new `input_text` entity under the existing modes:
+
+```yaml
+input_text:
+  # ... existing modes ...
+
+  # Your custom mode
+  adaptive_lighting_settings_reading:
+    name: "AL Settings: Reading"
+    max: 255
+    initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":42,"al_config":{"min_brightness":80,"max_brightness":100,"min_color_temp":4500,"max_color_temp":5500,"transition":2}}'
+```
+
+3. Save the file
+4. **Developer Tools → YAML → Reload all YAML configuration**
+5. Verify the entity appears in **Developer Tools → States**
+
+### When to Use Package-Defined Modes
+
+Use this method when:
+- You want modes version-controlled with Git
+- The mode is permanent (not experimental)
+- You're deploying to multiple Home Assistant instances
+- You want modes available immediately after fresh install
+
+## Schema Reference
+
+Every mode must have a JSON value with this nested structure:
+
+```json
+{
+  "behavior": "adaptive_lighting",
+  "manual_control": false,
+  "led_color": 170,
+  "al_config": {
+    "min_brightness": 20,
+    "max_brightness": 80,
+    "min_color_temp": 2000,
+    "max_color_temp": 4000,
+    "transition": 5
+  }
+}
+```
+
+### Top-Level Fields
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `behavior` | string | Yes | N/A | Mode behavior type: "adaptive_lighting", "scene", or "script" |
+| `manual_control` | boolean | No | `false` | If `true`, pauses Adaptive Lighting manual control for this mode |
+| `led_color` | number | No | `170` | LED hue value (0-255) for Inovelli switches |
+| `al_config` | object | Yes* | `{}` | Adaptive Lighting settings (*required for "adaptive_lighting" behavior) |
+
+### AL Config Fields (adaptive_lighting behavior)
+
+These settings are passed directly to `adaptive_lighting.change_switch_settings`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `use_defaults` | string | "configuration" or "current" - whether to use AL defaults |
+| `min_brightness` | number | Minimum brightness percentage (1-100) |
+| `max_brightness` | number | Maximum brightness percentage (1-100) |
+| `min_color_temp` | number | Minimum color temperature in Kelvin (2000-6500) |
+| `max_color_temp` | number | Maximum color temperature in Kelvin (2000-6500) |
+| `sleep_rgb_color` | array | RGB array for sleep mode, e.g., `[255, 50, 0]` |
+| `transition` | number | Transition time in seconds |
+
+See [Adaptive Lighting documentation](https://github.com/basnijholt/adaptive-lighting) for all available AL settings.
+
+### LED Color Values (ROYGBIV Scheme)
+
+LED colors use hue values (0-255) for Zigbee2MQTT `ledColorWhenOn` parameter:
+
+| Color | Hue | Used By Default Modes |
+|-------|-----|----------------------|
+| Red | 0 | Sleep |
+| Orange | 21 | Relaxing, Dining |
+| Yellow | 42 | Cooking |
+| Green | 85 | (none - good for Focus mode) |
+| Cyan | 170 | Adaptive, Cleanup |
+| Purple | 127 | Theater |
+| Magenta | 234 | Party |
+| Pink | 212 | (none - good for Manual Override) |
+
+## Behavior Types
+
+The mode system supports three behavior types:
+
+### 1. Adaptive Lighting (Standard)
+
+Applies Adaptive Lighting settings to lights:
+
+```json
+{
+  "behavior": "adaptive_lighting",
+  "manual_control": false,
+  "led_color": 42,
+  "al_config": {
+    "min_brightness": 80,
+    "max_brightness": 100,
+    "min_color_temp": 4500,
+    "max_color_temp": 5500,
+    "transition": 2
+  }
+}
+```
+
+Use for: Most lighting modes where you want automated color temperature and brightness.
+
+### 2. Scene-Based Mode
+
+Activates a Home Assistant scene:
+
+```json
+{
+  "behavior": "scene",
+  "manual_control": false,
+  "scene_entity": "scene.movie_night",
+  "led_color": 127,
+  "al_config": {}
+}
+```
+
+Use for: Complex lighting setups with multiple lights, specific colors, or other device states.
+
+### 3. Script-Based Mode
+
+Runs a Home Assistant script:
+
+```json
+{
+  "behavior": "script",
+  "manual_control": false,
+  "script_entity": "script.party_lights",
+  "led_color": 234,
+  "al_config": {}
+}
+```
+
+Use for: Dynamic lighting effects, light shows, or complex automation sequences.
+
+## Manual Control
+
+The `manual_control` field controls whether Adaptive Lighting is paused for the mode.
+
+### Pausing Adaptive Lighting
+
+Set `manual_control: true` to pause AL and prevent automatic adjustments:
+
+```json
+{
+  "behavior": "adaptive_lighting",
+  "manual_control": true,
+  "led_color": 212,
+  "al_config": {}
+}
+```
+
+This is useful for:
+- **Manual Override mode**: Let users manually control lights without AL interference
+- **Scene-based modes**: Prevent AL from overriding scene settings
+- **Script-based modes**: Prevent AL from interfering with light effects
+
+### How Manual Control Works
+
+The blueprint **always** calls `adaptive_lighting.set_manual_control` with the mode's `manual_control` value:
+- `manual_control: false` (default): AL remains active and adjusts lights automatically
+- `manual_control: true`: AL is paused and won't adjust lights until mode changes
+
+## Advanced Examples
+
+### Example 1: "Movie Night" Scene Mode
+
+Combines multiple devices (lights, media player, etc.) via a scene:
+
+**Step 1**: Create the scene in Home Assistant (Settings → Scenes)
+**Step 2**: Create mode helper with scene behavior:
+
+```json
+{"behavior":"scene","manual_control":false,"scene_entity":"scene.movie_night","led_color":127,"al_config":{}}
+```
+
+### Example 2: "Disco" Script Mode
+
+Runs a script that cycles through colors:
+
+```json
+{"behavior":"script","manual_control":false,"script_entity":"script.disco_lights","led_color":234,"al_config":{}}
+```
+
+### Example 3: "Manual Override" Mode
+
+Pauses AL completely for manual light control:
+
+```json
+{"behavior":"adaptive_lighting","manual_control":true,"led_color":212,"al_config":{}}
+```
+
+### Example 4: "Sunrise Alarm" Mode
+
+Gradual brightness increase with warm colors:
+
+```json
+{"behavior":"adaptive_lighting","manual_control":false,"led_color":21,"al_config":{"min_brightness":1,"max_brightness":100,"min_color_temp":2000,"max_color_temp":2500,"transition":600}}
+```
+
+Note: 600-second transition = 10-minute gradual wake-up.
+
+### Example 5: "Bowling" Mode (From Documentation)
+
+Bright, energizing light for recreational activities:
+
+```json
+{"behavior":"adaptive_lighting","manual_control":false,"led_color":148,"al_config":{"min_brightness":70,"max_brightness":100,"min_color_temp":4000,"max_color_temp":5500,"transition":1}}
+```
+
+## Troubleshooting
+
+### Mode Not Working
+
+**Problem**: Selected mode but lights didn't change.
+
+**Solutions**:
+1. Check entity ID matches naming convention: `input_text.adaptive_lighting_settings_<mode_lowercase>`
+2. Verify JSON is valid (use a JSON validator)
+3. Check Home Assistant logs for errors: **Settings → System → Logs**
+4. Verify mode name in dropdown exactly matches entity ID (case-sensitive)
+
+### JSON Syntax Errors
+
+**Problem**: Mode causes errors in logs.
+
+**Common mistakes**:
+```json
+// BAD - trailing comma
+{"behavior":"adaptive_lighting","manual_control":false,}
+
+// BAD - missing quotes
+{behavior:"adaptive_lighting"}
+
+// BAD - single quotes
+{'behavior':'adaptive_lighting'}
+
+// GOOD
+{"behavior":"adaptive_lighting","manual_control":false}
+```
+
+**Solution**: Use a JSON validator (e.g., jsonlint.com) before saving.
+
+### Entity ID Naming Mistakes
+
+**Problem**: Mode selector has "Movie Night" but blueprint can't find settings.
+
+**Issue**: Spaces in mode name must become underscores in entity ID.
+
+**Correct mapping**:
+- "Movie Night" → `input_text.adaptive_lighting_settings_movie_night`
+- "Reading" → `input_text.adaptive_lighting_settings_reading`
+- "Focus Mode" → `input_text.adaptive_lighting_settings_focus_mode`
+
+### Schema Validation Errors
+
+**Problem**: Error like "extra keys not allowed" in logs.
+
+**Cause**: Putting AL settings at top level instead of in `al_config`.
+
+**Wrong**:
+```json
+{"behavior":"adaptive_lighting","min_brightness":20,"max_brightness":40}
+```
+
+**Correct**:
+```json
+{"behavior":"adaptive_lighting","manual_control":false,"led_color":170,"al_config":{"min_brightness":20,"max_brightness":40}}
+```
+
+### Mode Works But LED Doesn't Change
+
+**Problem**: AL settings apply but LED stays same color.
+
+**Solutions**:
+1. Verify LED entity configured in "Apply Lighting Mode Settings" blueprint automation
+2. Check LED entity supports `number.set_value` service
+3. Verify `led_color` value is 0-255
+4. Test LED manually: **Developer Tools → Services → number.set_value**
+
+## Extensibility
+
+### Adding New Behavior Types (Future)
+
+The blueprint can be extended to support new behaviors beyond AL, scene, and script.
+
+**Example**: Add "webhook" behavior to trigger external services:
+
+1. Edit `blueprints/automation/apply_lighting_mode.yaml`
+2. Add new condition to `choose` block:
+
+```yaml
+- conditions: "{{ behavior == 'webhook' }}"
+  sequence:
+    - service: rest_command.trigger_webhook
+      data:
+        url: "{{ settings.webhook_url }}"
+```
+
+3. Create mode with webhook behavior:
+
+```json
+{"behavior":"webhook","manual_control":false,"webhook_url":"https://example.com/hook","led_color":85,"al_config":{}}
+```
+
+**Note**: This is a **one-time blueprint change** that enables infinite webhook modes via helpers.
+
+### Convention Over Configuration
+
+The key principle: **Extend the blueprint once to add a capability, then use that capability unlimited times via helpers.**
+
+- Want 100 adaptive_lighting modes? Create 100 helpers (no blueprint changes)
+- Want scene-based modes? Blueprint already supports it (no changes needed)
+- Want webhook behavior? Add once to blueprint, then create unlimited webhook modes via helpers
+
+This is the power of convention-based design.
+
+---
+
+## Next Steps
+
+Now that you understand custom modes:
+
+1. **Experiment**: Create a "Reading" mode following the Quick Start
+2. **Iterate**: Try different brightness/color temp combinations
+3. **Share**: Document your favorite modes for others
+4. **Extend**: Consider new behavior types for your use case
+
+For more information:
+- [Room Configuration Guide](ROOM_CONFIGURATION_GUIDE.md) - Setting up rooms
+- [Package Setup Guide](PACKAGE_SETUP_GUIDE.md) - Installing global package
+- [README](README.md) - Main documentation
+- [Adaptive Lighting Docs](https://github.com/basnijholt/adaptive-lighting) - AL integration reference

CLAUDE.md

@@ -4,84 +4,447 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Repository Overview
 
-This is a Home Assistant blueprints repository containing automation blueprints for Home Assistant. The repository follows a simple structure with individual YAML blueprint files in the root directory alongside comprehensive documentation.
+This is a Home Assistant blueprints repository containing automation blueprints and a global package for Adaptive Lighting mode management. The repository uses a **pure blueprint architecture** with **convention-based entity lookup** for extensibility.
 
 ## Architecture
 
 ### Blueprint Structure
-- **Blueprint files**: YAML files defining Home Assistant automation blueprints
+- **3 core blueprints** for Adaptive Lighting mode system (mode application + 2 weekend mode blueprints)
-- **Documentation**: README.md provides detailed usage examples and configuration guidance
+- **3 optional blueprints** for Inovelli switch integration and presence-based automation
-- Each blueprint is self-contained with embedded metadata (name, description, domain, inputs)
+- **Convention-based entity lookup**: Blueprints dynamically discover mode settings using naming convention (`adaptive_lighting_settings_{{mode}}`)
+- **Optional input handling**: Blueprints use `default: {}` pattern for optional inputs
 
-### Current Blueprints
+### Package Structure
+- **1 global package** with 8 mode definitions (`adaptive_lighting_global.yaml`)
+- **Nested JSON schema**: Each mode contains `behavior`, `manual_control`, `led_color`, and `al_config` fields
+- **No room templates**: Room configuration done entirely via Home Assistant UI
 
-#### Multi-Press Action Blueprint (`multi_press_action.yaml`)
+### User Workflow
-- **Purpose**: Trigger different actions based on rapid entity state changes (single, double, triple, quad press)
+- **Zero YAML editing** for room setup
-- **Key features**: 
+- Create helpers via Settings → Helpers (dropdowns, toggles, text inputs)
-  - Configurable time window for press detection
+- Import blueprints via Settings → Blueprints
-  - Immediate vs delayed single-press modes
+- Create automations from blueprints via UI
-  - Support for complex action sequences with conditions
+- Add custom modes by creating helpers following naming convention
-- **Architecture patterns**:
+
-  - Uses Home Assistant blueprint format with input selectors
+## Core Blueprints
-  - Implements state machine logic with press counting
+
-  - Uses `mode: restart` to handle overlapping triggers
+### Apply Lighting Mode Blueprint (`apply_lighting_mode.yaml`)
-  - Template-based conditional logic for press count evaluation
+**Purpose**: Data-driven mode application using convention-based entity lookup
+
+**Key features**:
+- Convention-based entity lookup: `adaptive_lighting_settings_{{mode | lower | replace(' ', '_')}}`
+- Behavior polymorphism: Supports "adaptive_lighting", "scene", and "script" behaviors
+- Manual control support: Top-level `manual_control` attribute controls AL manual control state
+- Optional LED color integration for Inovelli switches
+- Mode: restart for debouncing rapid state changes
+
+**Architecture patterns**:
+- Dynamic entity ID construction from mode name
+- Nested al_config extraction to avoid service validation errors
+- Conditional execution based on behavior type
+- Optional input handling with `default: {}`
+
+### Weekend Mode Schedule Blueprint (`weekend_mode_schedule.yaml`)
+**Purpose**: Auto-enable/disable weekend mode based on day of week
+
+**Key features**:
+- Single automation combines enable + disable logic using choose action
+- Time trigger checks day of week
+- Toggles input_boolean based on weekday condition
+- Mode: single to prevent overlapping executions
+
+### Weekend Mode Apply Settings Blueprint (`weekend_mode_apply_settings.yaml`)
+**Purpose**: Apply AL adjustments when weekend mode toggles
+
+**Key features**:
+- Delayed sunrise time for sleeping in on weekends
+- Extended sunset time for staying up later
+- Reduced max brightness
+- Reset to defaults when weekend mode turns off
+- Triggers on boolean state change + HA restart
+- Mode: restart for debouncing
 
 ## Development Workflow
 
-### Adding New Blueprints
+### Adding New Modes
-1. Create new `.yaml` file in repository root
+
-2. Follow Home Assistant blueprint format:
+**Two methods**:
-   - `blueprint:` section with metadata
+
-   - `input:` section with user-configurable parameters
+1. **UI-created modes** (recommended):
-   - `trigger:` and `action:` sections for automation logic
+   - Create input_text helper via Settings → Helpers
-3. Update README.md with new blueprint documentation
+   - Follow naming convention: `input_text.adaptive_lighting_settings_{{mode}}`
-4. Test blueprint by importing into Home Assistant development environment
+   - Use nested schema: `{"behavior":"adaptive_lighting","manual_control":false,"led_color":170,"al_config":{...}}`
+   - No restart required
+   - Reference: ADDING_MODES.md tutorial
+
+2. **Package-defined modes** (version controlled):
+   - Edit `adaptive_lighting_global.yaml`
+   - Add new input_text entity following existing patterns
+   - Use nested schema with behavior, manual_control, led_color, al_config
+   - Reload YAML configuration
+
+**Key principle**: Modes are discovered by convention, not hardcoded. Adding a mode doesn't require blueprint changes.
+
+### Blueprint Testing
+
+Manual testing workflow (no automated testing framework for HA blueprints):
+1. Import blueprint to Home Assistant
+2. Create test helpers via UI
+3. Create automation from blueprint
+4. Test all input combinations
+5. Verify automation traces for debugging
+6. Check Home Assistant logs for errors
 
 ### Blueprint Best Practices
+- **Convention-based entity naming** for extensibility (modes, devices)
+- **Optional input handling** with `default: {}` for flexible configuration
+- **Mode: restart** for debouncing state changes
+- **Mode: single** for preventing overlapping executions
+- **Nested JSON schema** to satisfy service validation constraints
+- **Integration filters** (`domain: switch, integration: adaptive_lighting`) for user-friendly entity selection
 - Use descriptive names and clear descriptions for inputs
 - Provide sensible defaults for optional parameters
-- Include comprehensive selector types for user inputs
+- Include comprehensive documentation in blueprint metadata
-- Use `mode: restart` or `mode: single` appropriately based on use case
-- Implement proper variable scoping within actions
-- Include detailed documentation with usage examples
 
-### Testing
+### Home Assistant Blueprint Format
-- No automated testing framework (blueprints are tested in Home Assistant directly)
-- Manual testing involves:
-  1. Importing blueprint into Home Assistant
-  2. Creating automation from blueprint
-  3. Testing various input combinations and edge cases
-  4. Verifying automation traces for debugging
 
-### Import URLs
+Blueprints follow this structure:
-- Repository uses custom Git hosting at `git.johnogle.info`
+```yaml
-- Import URL pattern: `https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/{blueprint_name}.yaml`
+blueprint:
+  name: Blueprint Name
+  description: Clear description of what this blueprint does
+  domain: automation
+
+input:
+  input_name:
+    name: User-Facing Name
+    description: Clear description of this input
+    default: {}  # For optional inputs
+    selector:
+      entity:
+        domain: switch
+        integration: adaptive_lighting  # Optional filter
+
+mode: restart  # or single, queued, parallel
+max_exceeded: silent
+
+trigger:
+  - platform: state
+    entity_id: !input input_name
+
+variables:
+  var_name: !input input_name
+  derived_var: "{{ template_expression }}"
+
+action:
+  - service: some.service
+    target:
+      entity_id: "{{ var_name }}"
+    data:
+      setting: "{{ derived_var }}"
+```
+
+### Input Selectors
+
+Common selector types used in this repository:
+
+**Entity selectors**:
+```yaml
+selector:
+  entity:
+    domain: input_select  # Dropdown helpers
+    # or
+    domain: input_boolean  # Toggle helpers
+    # or
+    domain: switch
+    integration: adaptive_lighting  # Filter by integration
+    # or
+    domain: number  # Number entities (LED color)
+```
+
+**Time selector**:
+```yaml
+selector:
+  time:  # HH:MM:SS time picker
+```
+
+**Number selector**:
+```yaml
+selector:
+  number:
+    min: 1
+    max: 100
+    step: 1
+    unit_of_measurement: "%"
+```
+
+**Action selector**:
+```yaml
+selector:
+  action:  # Full action sequence builder
+```
+
+### Mode Settings Schema
+
+Each mode uses this nested JSON structure:
+
+```json
+{
+  "behavior": "adaptive_lighting",  // or "scene", "script"
+  "manual_control": false,  // Controls AL manual control state
+  "led_color": 170,  // 0-255 hue value for Inovelli LED
+  "al_config": {  // Nested object for AL settings
+    "min_brightness": 20,
+    "max_brightness": 80,
+    "min_color_temp": 2000,
+    "max_color_temp": 4000,
+    "transition": 5
+  }
+}
+```
+
+**Why nested?**: The `adaptive_lighting.change_switch_settings` service performs strict key validation, rejecting unknown keys. The nested structure isolates AL-specific settings in `al_config`, while metadata like `behavior` and `led_color` remain at the top level.
+
+**Manual control**: The `manual_control` attribute (defaults to `false`) controls whether AL manual control is enabled for the mode. When `true`, AL is paused and won't adjust lights. The blueprint always calls `adaptive_lighting.set_manual_control` with this value.
 
 ## File Organization
 
 ```
 /
-├── README.md                    # Comprehensive documentation
+├── blueprints/
-├── multi_press_action.yaml     # Multi-press detection blueprint
+│   └── automation/
-└── CLAUDE.md                   # This file
+│       ├── apply_lighting_mode.yaml               # Core: Data-driven mode application
+│       ├── weekend_mode_schedule.yaml             # Core: Auto-enable/disable weekend mode
+│       ├── weekend_mode_apply_settings.yaml       # Core: Apply weekend AL adjustments
+│       ├── inovelli_mode_cycling.yaml             # Optional: Config button mode cycling
+│       ├── inovelli_button_actions.yaml           # Optional: Multi-tap button actions
+│       ├── presence_mode_reset.yaml               # Optional: Auto-reset on room exit
+│       └── occupancy_controlled_lights.yaml       # Standalone: Occupancy-based lighting
+├── packages/
+│   └── adaptive_lighting_global.yaml              # Global mode definitions (8 modes)
+├── hardware/
+│   └── inovelli/
+│       └── blue-dimmer-2-in-1-vzt31.md           # Inovelli Blue Dimmer documentation
+├── README.md                                      # Main documentation
+├── PACKAGE_SETUP_GUIDE.md                        # Global package installation
+├── ROOM_CONFIGURATION_GUIDE.md                   # UI-driven room setup
+├── ADDING_MODES.md                               # Custom mode creation tutorial
+└── CLAUDE.md                                     # This file
 ```
 
 ## Home Assistant Blueprint Conventions
 
 ### Input Types
 - `entity`: Entity selector for picking Home Assistant entities
-- `action`: Action sequence selector for automation actions  
+- `action`: Action sequence selector for automation actions
 - `number`: Numeric input with min/max/step validation
 - `boolean`: True/false toggle
 - `text`: String input fields
+- `time`: Time picker (HH:MM:SS format)
 
 ### Template Usage
 - Use `!input` to reference blueprint inputs
 - Template conditions with `{{ }}` syntax for dynamic logic
 - Variable assignment and reference within action sequences
+- Jinja2 filters for string manipulation (`lower`, `replace`, `from_json`)
 
 ### Automation Modes
-- `restart`: Stops current execution and restarts on new trigger
+- `restart`: Stops current execution and restarts on new trigger (used for debouncing)
 - `single`: Ignores new triggers while running
-- `parallel`: Allows multiple simultaneous executions
+- `parallel`: Allows multiple simultaneous executions
+- `queued`: Queues triggers and executes sequentially
+
+### Pattern References
+
+**Optional input handling** (`presence_mode_reset.yaml:98-116`):
+```yaml
+input:
+  optional_entity:
+    default: {}
+    selector:
+      entity:
+        domain: input_select
+
+# Later in action:
+- if:
+    - condition: template
+      value_template: "{{ optional_entity not in [none, {}, ''] }}"
+  then:
+    - service: some.service
+      target:
+        entity_id: "{{ optional_entity }}"
+```
+
+**Integration filter** (`inovelli_button_actions.yaml:36-42`):
+```yaml
+selector:
+  entity:
+    domain: switch
+    integration: adaptive_lighting
+```
+
+**Choose action pattern** (for behavior polymorphism):
+```yaml
+- choose:
+    - conditions: "{{ behavior == 'adaptive_lighting' }}"
+      sequence:
+        - service: adaptive_lighting.change_switch_settings
+          data: "{{ al_config }}"
+
+    - conditions: "{{ behavior == 'scene' }}"
+      sequence:
+        - service: scene.turn_on
+          target:
+            entity_id: "{{ settings.scene_entity }}"
+
+    - conditions: "{{ behavior == 'script' }}"
+      sequence:
+        - service: script.turn_on
+          target:
+            entity_id: "{{ settings.script_entity }}"
+```
+
+## Import URLs
+
+Blueprints are hosted at:
+- Base URL: `https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/`
+- Pattern: `{base_url}/blueprints/automation/{blueprint_name}.yaml`
+
+Example: `https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/apply_lighting_mode.yaml`
+
+## Design Principles
+
+### Convention Over Configuration
+
+**Key insight**: Extend the blueprint once to add a capability, then use that capability unlimited times via helpers.
+
+Examples:
+- Want 100 adaptive_lighting modes? Create 100 helpers following naming convention (no blueprint changes)
+- Want scene-based modes? Blueprint already supports it (no changes needed)
+- Want custom "Bowling" mode? Create one helper with correct entity ID (no changes needed)
+
+**This is the power of convention-based design.**
+
+### Zero YAML Editing for Users
+
+Room configuration workflow:
+1. Create helpers via UI (dropdowns, toggles)
+2. Create automations from blueprints via UI
+3. Test by switching modes via UI
+4. Add custom modes by creating text helpers via UI
+
+No template copying, no YAML editing, no search/replace, no package files per room.
+
+### Nested Schema for Service Validation
+
+Why nested `al_config`?
+- Home Assistant services perform strict validation
+- Unknown keys cause errors
+- Nested structure separates metadata from service parameters
+- Only `al_config` is passed to `adaptive_lighting.change_switch_settings`
+- Top-level fields (`behavior`, `manual_control`, `led_color`) used by blueprint logic
+
+### Behavior Polymorphism
+
+Modes can have different behaviors:
+- **adaptive_lighting**: Apply AL settings (default)
+- **scene**: Activate Home Assistant scene
+- **script**: Run Home Assistant script
+
+This enables complex use cases (movie scenes, light shows) without modifying blueprint core logic.
+
+## Migration Notes
+
+**No migration needed** - repository contains only blueprints and one global package, no deployed room configurations.
+
+**For future users**: If this becomes public, users would migrate from template packages to blueprint + UI workflow by:
+1. Creating helpers via UI matching their room names
+2. Importing blueprints
+3. Creating automations from blueprints
+4. Deleting old package files
+5. Reloading YAML configuration
+
+## Performance Considerations
+
+No performance concerns:
+- Automations trigger only on mode changes (user-initiated, infrequent)
+- JSON parsing is fast and cached by Home Assistant
+- Convention-based lookup is simple string templating
+- No polling, no external services, no heavy computation
+- Mode: restart prevents rapid-fire executions
+
+## Common Issues and Solutions
+
+### Service Validation Errors
+
+**Symptom**: "extra keys not allowed" in logs
+
+**Cause**: Passing top-level fields to `adaptive_lighting.change_switch_settings`
+
+**Solution**: Only pass `al_config` nested object to service
+
+### Missing Mode Entities
+
+**Symptom**: Blueprint fails to find mode settings
+
+**Cause**: Entity ID doesn't match naming convention
+
+**Solution**: Verify entity ID follows pattern `input_text.adaptive_lighting_settings_{{mode | lower | replace(' ', '_')}}`
+
+### LED Color Not Updating
+
+**Symptom**: Mode changes but LED stays same color
+
+**Causes**:
+1. LED entity not configured (left empty)
+2. Incorrect entity ID
+3. Inovelli switch firmware issue
+
+**Solution**: Check automation configuration, verify entity ID, test LED manually
+
+## Testing Guidelines
+
+Since Home Assistant blueprints have no automated testing framework, all testing is manual:
+
+1. **Blueprint Import**: Verify imports without errors in HA
+2. **Helper Creation**: Create test helpers via UI
+3. **Automation Creation**: Create test automations from blueprints
+4. **Mode Switching**: Test all mode combinations
+5. **Custom Modes**: Create custom mode and verify convention-based lookup
+6. **LED Integration**: Verify LED colors update (if configured)
+7. **Weekend Mode**: Test schedule and AL adjustments
+8. **HA Restart**: Verify persistence across restarts
+9. **Error Handling**: Test missing entities, invalid JSON, etc.
+10. **Logs**: Check for errors in Settings → System → Logs
+
+Always check automation traces (Settings → Automations → [automation] → Traces) for debugging.
+
+## Key Differences from Traditional Approach
+
+**Old approach** (template packages):
+- Copy package file per room
+- Search/replace entity IDs
+- Edit YAML to add modes
+- Hardcoded choose blocks for each mode
+- Adding mode requires editing every room
+
+**New approach** (pure blueprints):
+- Create helpers via UI
+- Create automations via UI
+- Zero YAML editing for rooms
+- Convention-based mode lookup
+- Adding mode = create ONE helper
+
+**Benefits**:
+- Lower friction for users
+- No YAML syntax errors from manual editing
+- Extensible without code changes
+- Easier to maintain
+- Better user experience
+
+## Resources
+
+- [Home Assistant Blueprint Documentation](https://www.home-assistant.io/docs/blueprint/)
+- [Adaptive Lighting Integration](https://github.com/basnijholt/adaptive-lighting)
+- [Jinja2 Template Reference](https://jinja.palletsprojects.com/)
+- [YAML Specification](https://yaml.org/)

INOVELLI_BLUE_DIMMER_SWITCHES.md

@@ -0,0 +1,121 @@
+# Inovelli Blue Series Dimmer Switch - Zigbee2MQTT Reference
+
+This directory contains technical specifications for Inovelli Blue Series Dimmer Switch (VZM31-SN) when used with Zigbee2MQTT, organized by theme for selective context loading.
+
+## Parameter Categories
+
+### [Dimming & Ramp Control](inovelli/dimming-and-ramp.md)
+Properties controlling dimming speeds and ramp rates for both local (physical paddle) and remote (hub/automation) control.
+- **Properties**: dimmingSpeed*, rampRate*
+- **Use cases**: Fine-tuning dimming behavior, creating smooth lighting transitions
+
+### [Brightness Levels](inovelli/brightness-levels.md)
+Properties defining brightness limits, default levels, and multi-tap brightness targets.
+- **Properties**: minimumLevel, maximumLevel, defaultLevel*, invertSwitch, brightnessLevelForDoubleTap*
+- **Use cases**: Setting brightness constraints, configuring default on levels, switch inversion
+
+### [Power & Energy Monitoring](inovelli/power-monitoring.md)
+Properties for power measurement, reporting thresholds, and energy monitoring.
+- **Properties**: power, energy, activePowerReports, activeEnergyReports, periodicPowerAndEnergyReports
+- **Use cases**: Power consumption tracking, energy usage analytics, reporting intervals
+
+### [LED Configuration](inovelli/led-configuration.md)
+Properties controlling LED strip colors and intensity for individual LEDs and global defaults, plus LED effects.
+- **Properties**: led_effect, individual_led_effect, ledColorWhen*, ledIntensityWhen*, defaultLed*
+- **Use cases**: LED notifications, status indicators, custom color schemes, animated effects
+
+### [Switch Configuration](inovelli/switch-config.md)
+Properties defining switch type, operational modes, and hardware configuration.
+- **Properties**: switchType, buttonDelay, smartBulbMode, outputMode, powerType, ledBarScaling
+- **Use cases**: 3-way setup, smart bulb mode, non-neutral wiring, on/off mode
+
+### [Protection & Safety](inovelli/protection-safety.md)
+Properties for device protection, temperature monitoring, and access control.
+- **Properties**: internalTemperature, overheat, localProtection, remoteProtection
+- **Use cases**: Child locks, overheat protection, disabling physical/remote control
+
+### [Timers & Automation](inovelli/timers-automation.md)
+Properties for time-based automation features.
+- **Properties**: autoTimerOff, loadLevelIndicatorTimeout, doubleTapUpToParam55, doubleTapDownToParam56
+- **Use cases**: Auto-off timers, LED timeout, double-tap shortcuts
+
+### [Advanced Features](inovelli/advanced-features.md)
+Properties for advanced configuration, bindings, and special modes.
+- **Properties**: fanControlMode, singleTapBehavior, auxSwitchUniqueScenes, bindingOffToOnSyncLevel
+- **Use cases**: Fan control, scene control, firmware updates, custom behaviors
+
+## Quick Property Lookup
+
+| Property | Category |
+|----------|----------|
+| dimmingSpeedUpRemote, dimmingSpeedUpLocal | Dimming & Ramp |
+| dimmingSpeedDownRemote, dimmingSpeedDownLocal | Dimming & Ramp |
+| rampRateOffToOnRemote, rampRateOffToOnLocal | Dimming & Ramp |
+| rampRateOnToOffRemote, rampRateOnToOffLocal | Dimming & Ramp |
+| minimumLevel, maximumLevel | Brightness Levels |
+| defaultLevelLocal, defaultLevelRemote | Brightness Levels |
+| invertSwitch, stateAfterPowerRestored | Brightness Levels |
+| brightnessLevelForDoubleTapUp, brightnessLevelForDoubleTapDown | Brightness Levels |
+| autoTimerOff | Timers & Automation |
+| loadLevelIndicatorTimeout | Timers & Automation |
+| doubleTapUpToParam55, doubleTapDownToParam56 | Timers & Automation |
+| power, energy | Power Monitoring |
+| activePowerReports, activeEnergyReports | Power Monitoring |
+| periodicPowerAndEnergyReports | Power Monitoring |
+| quickStartTime, quickStartLevel | Power Monitoring |
+| led_effect, individual_led_effect | LED Configuration |
+| ledColorWhenOn, ledColorWhenOff | LED Configuration |
+| ledIntensityWhenOn, ledIntensityWhenOff | LED Configuration |
+| defaultLed1-7ColorWhenOn/Off | LED Configuration |
+| defaultLed1-7IntensityWhenOn/Off | LED Configuration |
+| ledBarScaling, onOffLedMode | LED Configuration |
+| switchType, buttonDelay | Switch Configuration |
+| smartBulbMode, outputMode | Switch Configuration |
+| powerType, dimmingMode, relayClick | Switch Configuration |
+| higherOutputInNonNeutral | Switch Configuration |
+| internalTemperature, overheat | Protection & Safety |
+| localProtection, remoteProtection | Protection & Safety |
+| fanControlMode, singleTapBehavior | Advanced Features |
+| auxSwitchUniqueScenes, bindingOffToOnSyncLevel | Advanced Features |
+| deviceBindNumber, firmwareUpdateInProgressIndicator | Advanced Features |
+| doubleTapClearNotifications, fanLedLevelType | Advanced Features |
+
+## Zigbee2MQTT Integration
+
+These properties are exposed by Zigbee2MQTT and can be accessed in Home Assistant as:
+- **Entities**: `light.switch_name` (state, brightness)
+- **Sensors**: `sensor.switch_name_power`, `sensor.switch_name_energy`
+- **Numbers**: `number.switch_name_dimming_speed_up_remote`, etc.
+- **Selects**: `select.switch_name_switch_type`, etc.
+- **Actions**: `mqtt.publish` to set LED effects via `led_effect` and `individual_led_effect`
+
+## Setting Properties
+
+Properties can be set via:
+1. **Home Assistant UI**: Using the exposed number/select entities
+2. **Services**: Using `number.set_value` or `select.select_option`
+3. **MQTT**: Publishing directly to `zigbee2mqtt/[device_name]/set`
+
+Example MQTT publish for LED effect:
+```yaml
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"led_effect": {"effect": "pulse", "color": 170, "level": 100, "duration": 255}}'
+```
+
+## Source
+
+- Official Inovelli documentation: https://help.inovelli.com/en/articles/8189241-blue-series-dimmer-switch-parameters
+- Zigbee2MQTT device definition: Model VZM31-SN
+
+## Usage for LLM Agents
+
+Each category file contains detailed property specifications including:
+- Property name as exposed by Zigbee2MQTT
+- Value range and units
+- Default value
+- Detailed description
+- Usage notes and Home Assistant examples
+
+Load only the category files relevant to your current task to minimize context usage.

PACKAGE_SETUP_GUIDE.md

@@ -2,41 +2,84 @@
 
 ## Overview
 
-This guide explains how to set up Home Assistant packages for the Adaptive
+This guide covers installing the **global mode definitions package only**. Room configuration is done entirely via Home Assistant UI - see [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for the UI-driven room setup workflow.
-Lighting Mode System and configure version control.
+
+## Architecture
+
+The Adaptive Lighting Mode System uses a **pure blueprint architecture**:
+
+- **Global package**: Provides shared mode definitions (8 essential modes) as input_text helpers
+- **Blueprints**: Provide automation logic for mode application and weekend mode schedules
+- **UI-created helpers**: Users create room-specific helpers (dropdowns, toggles) via Settings → Helpers
+- **UI-created automations**: Users create automations from blueprints via Settings → Automations
+
+**Key principle**: Zero YAML editing required for room setup. The global package is the only YAML file you need to install.
 
 ## What Are Packages?
 
-Packages allow you to organize Home Assistant configuration into multiple YAML
+Packages allow you to organize Home Assistant configuration into multiple YAML files instead of one giant `configuration.yaml`. Each package file can contain automations, helpers, scripts, and other entities related to a specific feature.
-files instead of one giant `configuration.yaml`. Each package file can contain
-automations, helpers, scripts, and other entities related to a specific feature
-or room.
 
 **Benefits**:
-- Organize configuration by room or feature
+- Organize configuration by feature
 - Version control specific areas independently
-- Easier to share and reuse configurations
+- Share and reuse configurations
 - Keep `configuration.yaml` clean and minimal
 
 ## Prerequisites
 
 - Home Assistant installed and running
 - SSH or file editor access to your HA configuration directory
-- Git installed (optional, for version control)
 - Adaptive Lighting integration installed via HACS
+- Git installed (optional, for version control)
 
-## Step 1: Enable Packages in Home Assistant
+## Installation Steps
 
-**1.1 Edit your `configuration.yaml`**
+### Step 1: Import Blueprints
 
-Add this line to the top of your `configuration.yaml`:
+**1.1 Navigate to blueprints**
+
+Settings → Automations & Scenes → Blueprints → Import Blueprint
+
+**1.2 Import the three mode system blueprints**
+
+Import these URLs one at a time:
+
+```
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/apply_lighting_mode.yaml
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/weekend_mode_schedule.yaml
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/weekend_mode_apply_settings.yaml
+```
+
+**Optional blueprints** (for Inovelli switches and presence-based automation):
+
+```
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/inovelli_mode_cycling.yaml
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/inovelli_button_actions.yaml
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/presence_mode_reset.yaml
+```
+
+**1.3 Verify blueprints imported**
+
+Settings → Automations & Scenes → Blueprints
+
+You should see:
+- Apply Lighting Mode Settings
+- Weekend Mode Schedule
+- Weekend Mode Apply Settings
+- (Optional) Inovelli Mode Cycling, Inovelli Button Actions, Presence Mode Reset
+
+### Step 2: Enable Packages in Home Assistant
+
+**2.1 Edit your `configuration.yaml`**
+
+Add this line to enable packages:
 
 ```yaml
 homeassistant:
   packages: !include_dir_named packages/
 ```
 
-**1.2 Create the packages directory**
+**2.2 Create the packages directory**
 
 SSH into your Home Assistant instance or use File Editor add-on:
 
@@ -45,97 +88,115 @@ cd /config
 mkdir packages
 ```
 
-**1.3 Restart Home Assistant**
+**2.3 Restart Home Assistant**
 
 Settings → System → Restart Home Assistant
 
-## Step 2: Install Global Definitions
+### Step 3: Install Global Package
 
-**2.1 Copy the global package**
+**3.1 Copy the global package**
 
-Download or copy `packages/adaptive_lighting_global.yaml` from this repository
+Download or copy `packages/adaptive_lighting_global.yaml` from this repository to your `/config/packages/` directory.
-to your `/config/packages/` directory.
 
-**2.2 Reload YAML configuration**
+**3.2 Reload YAML configuration**
 
 Developer Tools → YAML → Reload all YAML configuration
 
-**2.3 Verify helpers exist**
+**3.3 Verify mode entities exist**
 
-Settings → Devices & Services → Helpers
+Developer Tools → States
 
-You should see:
+Search for `adaptive_lighting_settings` - you should see 8 entities:
-- `input_text.adaptive_lighting_mode_colors`
 - `input_text.adaptive_lighting_settings_adaptive`
-- `input_text.adaptive_lighting_settings_reading`
 - `input_text.adaptive_lighting_settings_relaxing`
 - `input_text.adaptive_lighting_settings_sleep`
-- And several more mode settings helpers
+- `input_text.adaptive_lighting_settings_theater`
+- `input_text.adaptive_lighting_settings_party`
+- `input_text.adaptive_lighting_settings_cooking`
+- `input_text.adaptive_lighting_settings_dining`
+- `input_text.adaptive_lighting_settings_cleanup`
 
-## Step 3: Import Blueprints
+### Step 4: Configure Your First Room
 
-**3.1 Import via UI**
+**This is done entirely via the UI** - no YAML editing required!
 
-Settings → Automations & Scenes → Blueprints → Import Blueprint
+See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for complete UI-driven room setup instructions.
 
-Import these URLs:
+Quick summary:
-```
+1. Create mode selector dropdown via Settings → Helpers
-https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/inovelli_mode_cycling.yaml
+2. Create automation from "Apply Lighting Mode Settings" blueprint
-https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/inovelli_button_actions.yaml
+3. Test mode switching via UI
-https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/presence_mode_reset.yaml
+4. Optionally add weekend mode automations
+
+## Mode Customization
+
+### Understanding the Mode Schema
+
+Each mode in the global package uses a **nested JSON schema**:
+
+```json
+{
+  "behavior": "adaptive_lighting",
+  "manual_control": false,
+  "led_color": 170,
+  "al_config": {
+    "min_brightness": 20,
+    "max_brightness": 80,
+    "min_color_temp": 2000,
+    "max_color_temp": 4000,
+    "transition": 5
+  }
+}
 ```
 
-**3.2 Verify blueprints imported**
+**Top-level fields**:
+- `behavior`: "adaptive_lighting", "scene", or "script" - determines how the mode behaves
+- `manual_control`: `true` or `false` - if `true`, pauses Adaptive Lighting for this mode
+- `led_color`: 0-255 hue value for LED feedback on Inovelli switches
+- `al_config`: Nested object with Adaptive Lighting settings
 
-Settings → Automations & Scenes → Blueprints
+**AL config fields** (only used for "adaptive_lighting" behavior):
+- `use_defaults`: "configuration" or "current"
+- `min_brightness`, `max_brightness`: 1-100
+- `min_color_temp`, `max_color_temp`: Kelvin values (2000-6500)
+- `sleep_rgb_color`: RGB array like `[255, 50, 0]`
+- `transition`: Seconds
 
-You should see all three blueprints listed.
+### Editing Mode Settings
 
-## Step 4: Configure Your First Room
+To customize a mode, edit `packages/adaptive_lighting_global.yaml` and modify the `initial` value:
 
-**4.1 Choose a template**
+**Example: Make "Relaxing" mode dimmer**
 
-Select the appropriate template for your room type:
+```yaml
-- Bedroom: `packages/adaptive_lighting_bedroom_template.yaml`
+adaptive_lighting_settings_relaxing:
-- Living room: `packages/adaptive_lighting_living_room_template.yaml`
+  name: "AL Settings: Relaxing"
-- Simple (bathroom, closet): `packages/adaptive_lighting_simple_template.yaml`
+  max: 255
-
+  initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":21,"al_config":{"min_brightness":10,"max_brightness":30,"min_color_temp":2000,"max_color_temp":2200,"transition":5}}'
-**4.2 Copy and customize**
-
-```bash
-cd /config/packages
-cp adaptive_lighting_bedroom_template.yaml adaptive_lighting_master_bedroom.yaml
 ```
 
-Edit the file and update:
+After editing, reload YAML configuration (Developer Tools → YAML → Reload all YAML configuration).
-- Replace "bedroom" with "master_bedroom" throughout
-- Update entity IDs (search for # UPDATE THIS comments)
-- Adjust available modes if desired
-- Customize mode settings
 
-**4.3 Reload configuration**
+### Adding Custom Modes
 
-Developer Tools → YAML → Reload all YAML configuration
+See [ADDING_MODES.md](ADDING_MODES.md) for complete tutorial on adding custom modes.
 
-**4.4 Create blueprint automations**
+**Two methods**:
+1. **UI-created modes** (recommended): Create input_text helper via Settings → Helpers - no restart required
+2. **Package-defined modes**: Add to `adaptive_lighting_global.yaml` - version controlled
 
-Settings → Automations & Scenes → Create Automation → Use Blueprint
+Both methods work identically with the convention-based blueprint system.
 
-Create automations for:
+## Version Control Setup (Optional)
-1. Inovelli Mode Cycling (config button)
-2. Inovelli Button Actions (multi-tap)
-3. Presence Mode Reset (if you have occupancy sensors)
 
-## Step 5: Version Control Setup (Optional)
+### Initialize git repository
-
-**5.1 Initialize git repository**
 
 ```bash
 cd /config
 git init
 ```
 
-**5.2 Create .gitignore**
+### Create .gitignore
 
 ```bash
 cat > .gitignore << 'EOF'
@@ -159,20 +220,19 @@ __pycache__/
 
 # Keep these version controlled:
 # - packages/
-# - automations.yaml
+# - automations.yaml (optional - UI automations are in .storage)
 # - configuration.yaml
-# - blueprints/
 EOF
 ```
 
-**5.3 Commit initial setup**
+### Commit initial setup
 
 ```bash
-git add packages/ automations.yaml configuration.yaml
+git add packages/ configuration.yaml
 git commit -m "Initial adaptive lighting mode system setup"
 ```
 
-**5.4 Add remote (optional)**
+### Add remote (optional)
 
 ```bash
 git remote add origin your-git-repo-url
@@ -183,38 +243,51 @@ git push -u origin main
 
 ### Packages not loading
 
-**Symptom**: Helpers don't appear after reloading
+**Symptom**: Mode entities don't appear after reloading
 
 **Solutions**:
-- Check `configuration.yaml` has packages line
+- Check `configuration.yaml` has packages line: `packages: !include_dir_named packages/`
 - Verify packages directory exists at `/config/packages/`
-- Check YAML syntax: `yamllint /config/packages/*.yaml`
+- Check YAML syntax with a validator
 - Look for errors in Settings → System → Logs
+- Try restarting Home Assistant instead of just reloading YAML
 
-### Entity IDs don't match
+### Invalid JSON in mode settings
 
-**Symptom**: Automations fail because entities not found
+**Symptom**: Mode doesn't work or causes errors
 
 **Solutions**:
-- Go to Settings → Devices & Services → MQTT
+- Verify JSON is valid using jsonlint.com
-- Find your Inovelli switch device
+- Check for trailing commas (not allowed in JSON)
-- Note the exact entity IDs (event.xxx_action,
+- Ensure all strings use double quotes, not single quotes
-  number.xxx_led_color_when_on)
+- Verify `al_config` is a nested object, not at top level
-- Update package file with correct entity IDs
-- Reload YAML
 
-### Blueprints not working
+### Blueprints not appearing
 
-**Symptom**: Automation from blueprint doesn't trigger
+**Symptom**: Blueprints don't show up after import
 
 **Solutions**:
-- Check automation trace: Settings → Automations → [your automation] →
+- Check for import errors in Settings → System → Logs
-  Traces
+- Verify blueprint URLs are correct
-- Verify trigger entity is correct
+- Try importing again
-- Ensure Inovelli buttonDelay is set to >= 500ms
+- Check YAML syntax of blueprint files if self-hosting
-- Test button press in Developer Tools → States (watch event.xxx_action)
+
+### Mode entities exist but automations don't work
+
+**Symptom**: Can see entities in States but mode switching does nothing
+
+**Solutions**:
+- Verify you created automation from "Apply Lighting Mode Settings" blueprint
+- Check automation is enabled
+- View automation traces: Settings → Automations → [your automation] → Traces
+- Verify AL switch entity ID is correct in automation configuration
+- Check mode selector entity ID matches in automation configuration
 
 ## Next Steps
 
-See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for detailed
+**This package only provides mode definitions.** To configure a room, see [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for the UI-driven workflow.
-room setup examples.
+
+Additional resources:
+- [ADDING_MODES.md](ADDING_MODES.md) - Tutorial for creating custom modes
+- [README.md](README.md) - Main documentation and architecture overview
+- [Adaptive Lighting Integration Docs](https://github.com/basnijholt/adaptive-lighting) - Reference for AL settings

README.md

@@ -2,70 +2,110 @@
 
 ## Adaptive Lighting Mode System
 
-A comprehensive mode-based lighting control system for Inovelli Blue Dimmer
+A comprehensive mode-based lighting control system with **pure blueprint architecture** and **zero YAML editing** for room setup. Features convention-based mode lookup allowing unlimited custom modes with no code changes.
-Switches with Adaptive Lighting integration.
 
 ### Features
 
-- **Room-specific modes**: Define custom lighting modes per room (Reading,
+- **Convention-based mode lookup**: Add "Bowling" mode by creating one helper - no code changes needed
-  Theater, Sleep, etc.)
+- **UI-driven room configuration**: Setup entire rooms via Home Assistant UI - zero YAML editing required
-- **Visual LED feedback**: LED bar color indicates current mode
+- **Weekend mode blueprints**: Automatic schedule adjustments for weekends (delayed sunrise, extended sunset)
-- **Config button control**: Press config button to cycle through modes
+- **Extensible behavior system**: Supports Adaptive Lighting, scene-based, and script-based modes
-- **Multi-tap actions**: Double-tap boost, triple-tap max/night light
+- **Manual control support**: Any mode can pause AL with `manual_control` attribute
-- **Adaptive Lighting integration**: Dynamic brightness and color following sun
+- **Visual LED feedback**: LED bar color indicates current mode (optional Inovelli integration)
-  position
+- **8 essential modes**: Adaptive, Relaxing, Sleep, Theater, Party, Cooking, Dining, Cleanup
-- **Version controlled**: All configuration in git-trackable package files
 
-### System Components
+### Architecture
 
-**Blueprints** (Reusable):
+**Pure blueprint architecture** with global mode definitions:
-- `inovelli_mode_cycling.yaml` - Config button cycles modes with LED feedback
-- `inovelli_button_actions.yaml` - Multi-tap brightness controls
-- `presence_mode_reset.yaml` - Auto-reset on room exit
 
-**Packages** (Templates):
+- **3 core blueprints**: Mode application + 2 weekend mode blueprints
-- `adaptive_lighting_global.yaml` - Shared mode definitions and colors
+- **1 global package**: 8 shipped modes with nested JSON schema
-- `adaptive_lighting_bedroom_template.yaml` - Complete bedroom example
+- **UI-created helpers**: Room-specific dropdowns and toggles created via Settings → Helpers
-- `adaptive_lighting_living_room_template.yaml` - Living room example
+- **UI-created automations**: No package copying or YAML editing required
-- `adaptive_lighting_simple_template.yaml` - Minimal single-mode room
 
-### Setup Guide
+**Key principle**: **Convention over configuration** - modes are discovered by naming convention, not hardcoded logic.
 
-**Quick Start**:
+### Quick Start
-1. Install Adaptive Lighting integration via HACS
-2. Follow [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) to enable packages
-3. Copy templates from `packages/` directory
-4. Import blueprints via UI
-5. See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for examples
 
-**Documentation**:
+**Step 1: Install Adaptive Lighting integration via HACS**
-- [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) - Initial setup and version
-  control
-- [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) - Room-by-room
-  examples
-- [ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md](ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md) -
-  Complete system design
 
-**Files**:
+**Step 2: Import blueprints**
-- `packages/adaptive_lighting_global.yaml` - Required for all rooms
+
-- `packages/adaptive_lighting_bedroom_template.yaml` - Template for bedrooms
+Settings → Automations & Scenes → Blueprints → Import Blueprint
-- `packages/adaptive_lighting_living_room_template.yaml` - Template for common
+
-  areas
+Import URLs (see below for full list)
-- `packages/adaptive_lighting_simple_template.yaml` - Template for simple rooms
+
-- `blueprints/automation/inovelli_mode_cycling.yaml` - Config button mode
+**Step 3: Install global package**
-  cycling
+
-- `blueprints/automation/inovelli_button_actions.yaml` - Multi-tap actions
+Follow [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) to install `adaptive_lighting_global.yaml`
-- `blueprints/automation/presence_mode_reset.yaml` - Auto-reset on room exit
+
+**Step 4: Create helpers and automations via UI**
+
+Follow [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for complete UI workflow
+
+**Step 5: (Optional) Add custom modes**
+
+Follow [ADDING_MODES.md](ADDING_MODES.md) to create "Reading" mode or any custom mode
+
+### Documentation
+
+- [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) - Installing global package and blueprints
+- [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) - UI-driven room setup (no YAML editing)
+- [ADDING_MODES.md](ADDING_MODES.md) - Tutorial for creating custom modes
+- [ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md](ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md) - System architecture design
+
+### File Inventory
+
+**Blueprints** (3 core + 3 optional):
+
+**Core blueprints** (required for mode system):
+- `blueprints/automation/apply_lighting_mode.yaml` - Data-driven mode application with convention-based entity lookup
+- `blueprints/automation/weekend_mode_schedule.yaml` - Auto-enable/disable weekend mode based on day of week
+- `blueprints/automation/weekend_mode_apply_settings.yaml` - Apply AL adjustments when weekend mode toggles
+
+**Optional blueprints** (for Inovelli switches and presence-based automation):
+- `blueprints/automation/inovelli_mode_cycling.yaml` - Config button cycles modes with LED feedback
+- `blueprints/automation/inovelli_button_actions.yaml` - Multi-tap brightness controls
+- `blueprints/automation/presence_mode_reset.yaml` - Auto-reset mode on room exit
+
+**Packages** (1 file):
+- `packages/adaptive_lighting_global.yaml` - Global mode definitions (8 modes with nested schema)
+
+**Documentation** (6 files):
+- `README.md` - Main documentation (this file)
+- `PACKAGE_SETUP_GUIDE.md` - Global package installation
+- `ROOM_CONFIGURATION_GUIDE.md` - UI-driven room setup
+- `ADDING_MODES.md` - Custom mode creation tutorial
+- `CLAUDE.md` - Claude Code instructions
+- `ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md` - Architecture design doc
 
 ### Import URLs
 
-**Blueprints**:
+**Core mode system blueprints**:
+```
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/apply_lighting_mode.yaml
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/weekend_mode_schedule.yaml
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/weekend_mode_apply_settings.yaml
+```
+
+**Optional Inovelli and presence blueprints**:
 ```
 https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/inovelli_mode_cycling.yaml
 https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/inovelli_button_actions.yaml
 https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/presence_mode_reset.yaml
 ```
 
+### Extensibility Example
+
+**Traditional approach** (hardcoded): Adding "Bowling" mode requires editing blueprint code, modifying choose blocks, updating all rooms.
+
+**Convention-based approach** (this system): Create ONE helper via UI:
+1. Settings → Helpers → Create Text input
+2. Name: `input_text.adaptive_lighting_settings_bowling`
+3. Value: `{"behavior":"adaptive_lighting","manual_control":false,"led_color":148,"al_config":{...}}`
+4. Add "Bowling" to your room's mode dropdown
+5. Done! No blueprint changes, works immediately in all rooms.
+
 ---
 
 ## Occupancy Controlled Lights Blueprint

ROOM_CONFIGURATION_GUIDE.md

@@ -1,200 +1,485 @@
 # Room Configuration Guide
 
-Complete examples of configuring different room types with the Adaptive
+This guide walks you through configuring rooms using the **pure blueprint architecture**. All configuration is done via the Home Assistant UI - **no YAML editing required**.
-Lighting Mode System.
+
+## Table of Contents
+
+- [Prerequisites](#prerequisites)
+- [Basic Room Setup (UI Workflow)](#basic-room-setup-ui-workflow)
+- [Advanced: Weekend Mode](#advanced-weekend-mode-optional)
+- [Example 1: Master Bedroom](#example-1-master-bedroom)
+- [Example 2: Living Room](#example-2-living-room)
+- [Example 3: Simple Bathroom](#example-3-simple-bathroom)
+- [Testing Checklist](#testing-checklist)
+- [Customization](#customization)
+- [Troubleshooting](#troubleshooting)
+
+## Prerequisites
+
+Before configuring a room:
+
+- ✅ Global package loaded (`adaptive_lighting_global.yaml`)
+- ✅ 3 blueprints imported (apply_lighting_mode, weekend_mode_schedule, weekend_mode_apply_settings)
+- ✅ Adaptive Lighting integration configured
+- ✅ Adaptive Lighting switch created for your room
+
+If you haven't done these steps, see [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) first.
+
+## Basic Room Setup (UI Workflow)
+
+This is the core workflow for every room. All steps are done in the Home Assistant UI.
+
+### Step 1: Create Mode Selector Helper
+
+**1.1 Navigate to Helpers**
+
+Settings → Devices & Services → Helpers
+
+**1.2 Create Dropdown Helper**
+
+- Click **+ Create Helper → Dropdown**
+- Configure:
+  - **Name**: `{Room} Lighting Mode` (e.g., "Master Bedroom Lighting Mode")
+  - **Icon**: `mdi:lightbulb-multiple` (optional)
+  - **Options**: Add the modes you want (from the 8 shipped modes)
+    - Adaptive
+    - Relaxing
+    - Sleep
+    - Theater
+    - Party
+    - Cooking
+    - Dining
+    - Cleanup
+  - **Initial option**: `Adaptive`
+
+**1.3 Note the Entity ID**
+
+After creation, click the helper to see its entity ID (e.g., `input_select.master_bedroom_lighting_mode`). You'll need this for the next step.
+
+### Step 2: Create Mode Application Automation
+
+**2.1 Navigate to Blueprints**
+
+Settings → Automations & Scenes → Blueprints
+
+**2.2 Create Automation from Blueprint**
+
+- Find "Apply Lighting Mode Settings" blueprint
+- Click **Create Automation**
+
+**2.3 Configure Inputs**
+
+- **Mode Input Select**: Select your dropdown helper (e.g., `input_select.master_bedroom_lighting_mode`)
+- **Adaptive Lighting Switch**: Select your room's AL switch (e.g., `switch.adaptive_lighting_master_bedroom`)
+- **LED Color Entity (Optional)**:
+  - Leave empty if you don't have Inovelli switches
+  - Select `number.{device_name}_led_color_when_on` if you have an Inovelli switch
+
+**2.4 Name the Automation**
+
+- Suggested name: `{Room}: Apply Lighting Mode` (e.g., "Master Bedroom: Apply Lighting Mode")
+- Click **Save**
+
+### Step 3: Test Mode Switching
+
+**3.1 Find Your Mode Selector**
+
+- Go to Overview dashboard
+- Or Settings → Devices & Services → Helpers → Find your dropdown
+
+**3.2 Switch Between Modes**
+
+- Select different modes from the dropdown
+- Verify lights change appropriately:
+  - **Adaptive**: Follows AL defaults
+  - **Relaxing**: Dim, warm (20-40% brightness, 2000-2500K)
+  - **Sleep**: Very dim red/amber (1-5% brightness)
+  - **Theater**: Dim, cool (5-20% brightness)
+  - **Party**: Bright, dynamic (60-90% brightness)
+  - **Cooking**: Bright, cool task lighting (90-100% brightness)
+  - **Dining**: Medium, warm (40-70% brightness)
+  - **Cleanup**: Bright, standard (80-100% brightness)
+
+**3.3 Verify LED Updates (If Configured)**
+
+- If you configured an LED entity, verify the Inovelli switch LED changes color with each mode
+
+**Congratulations!** You've configured basic mode switching for your room with zero YAML editing.
+
+## Advanced: Weekend Mode (Optional)
+
+Weekend mode automatically adjusts Adaptive Lighting settings on weekends (delayed sunrise, extended sunset, reduced brightness).
+
+### Step 1: Create Weekend Mode Toggle
+
+**1.1 Navigate to Helpers**
+
+Settings → Devices & Services → Helpers
+
+**1.2 Create Toggle Helper**
+
+- Click **+ Create Helper → Toggle**
+- Configure:
+  - **Name**: `{Room} Weekend Mode` (e.g., "Master Bedroom Weekend Mode")
+  - **Icon**: `mdi:calendar-weekend` (optional)
+  - **Initial state**: Off
+
+**1.3 Note the Entity ID**
+
+Example: `input_boolean.master_bedroom_weekend_mode`
+
+### Step 2: Create Schedule Automation
+
+**2.1 Create from Blueprint**
+
+Settings → Automations & Scenes → Blueprints → "Weekend Mode Schedule"
+
+**2.2 Configure Inputs**
+
+- **Weekend Mode Boolean**: Select your toggle helper
+- **Toggle Time**: When to check and toggle weekend mode (default: 22:00:00)
+  - Recommended: Late evening (e.g., 22:00 / 10:00 PM)
+
+**2.3 Save**
+
+Name: `{Room}: Weekend Mode Schedule`
+
+**How it works**:
+- Friday/Saturday at toggle time → Turns ON weekend mode
+- Sunday-Thursday at toggle time → Turns OFF weekend mode
+
+### Step 3: Create Apply Settings Automation
+
+**3.1 Create from Blueprint**
+
+Settings → Automations & Scenes → Blueprints → "Weekend Mode Apply Settings"
+
+**3.2 Configure Inputs**
+
+- **Weekend Mode Boolean**: Select your toggle helper (same as Step 2)
+- **Adaptive Lighting Switch**: Select your room's AL switch
+- **Weekend Sunrise Time**: When sunrise should be on weekends (default: 10:00:00)
+- **Weekend Sunset Time**: When sunset should be on weekends (default: 01:00:00)
+- **Weekend Max Brightness**: Maximum brightness on weekends (default: 60%)
+
+**3.3 Save**
+
+Name: `{Room}: Weekend Mode Apply Settings`
+
+**How it works**:
+- When weekend mode turns ON → Applies delayed sunrise, extended sunset, reduced brightness
+- When weekend mode turns OFF → Resets to AL default settings
+
+### Step 4: Test Weekend Mode
+
+**4.1 Manual Toggle Test**
+
+- Toggle your weekend mode boolean ON manually
+- Verify AL settings change (check Developer Tools → States → your AL switch attributes)
+- Toggle OFF
+- Verify AL settings reset
+
+**4.2 Schedule Test (Optional)**
+
+- Temporarily change toggle time to 1 minute in future
+- Wait for trigger
+- Verify boolean toggles based on current day of week
 
 ## Example 1: Master Bedroom
 
-**Goal**: Full control with optional AL, reading/sleep modes, weekend mode
+**Goal**: Full mode control with weekend mode, optional Inovelli integration
 
-**Hardware**:
+**Room Type**: Private bedroom with comprehensive lighting control
-- Inovelli Blue Dimmer: `bedroom_switch` (Zigbee2MQTT name)
+
-- Lights: `light.bedroom_ceiling`, `light.bedroom_lamp_1`,
+### Adaptive Lighting Configuration
-  `light.bedroom_lamp_2`
+
-- No presence sensor (privacy)
+In `configuration.yaml` (if not already done):
 
-**Adaptive Lighting Configuration** (in `configuration.yaml`):
 ```yaml
 adaptive_lighting:
-  - name: bedroom
+  - name: master_bedroom
     lights:
-      - light.bedroom_ceiling
+      - light.master_bedroom_ceiling
-      - light.bedroom_lamp_1
+      - light.master_bedroom_lamp_1
-      - light.bedroom_lamp_2
+      - light.master_bedroom_lamp_2
     interval: 90
     transition: 45
     take_over_control: true
     autoreset_control_seconds: 3600  # 1 hour gentle reset
 ```
 
-**Package File** (`packages/adaptive_lighting_master_bedroom.yaml`):
+Restart Home Assistant after editing configuration.yaml.
 
-Copy from `adaptive_lighting_bedroom_template.yaml`, customize:
+### UI Configuration Steps
-- Modes: Adaptive, Reading, Relaxing, Sleep, Manual Override
-- Weekend mode enabled
-- Default mode: Adaptive
 
-**Blueprint Automations** (create via UI):
+**Step 1: Create Mode Selector**
+- Name: "Master Bedroom Lighting Mode"
+- Entity ID: `input_select.master_bedroom_lighting_mode`
+- Options: Adaptive, Relaxing, Sleep, Theater (for movies in bed), Party (rare, but available)
+- Initial: Adaptive
 
-1. **Config Button Mode Cycling**:
+**Step 2: Create Mode Application Automation**
-   - Blueprint: Inovelli Mode Cycling
+- Blueprint: Apply Lighting Mode Settings
-   - Switch Action Event: `event.bedroom_switch_action`
+- Mode Input Select: `input_select.master_bedroom_lighting_mode`
-   - Mode Input Select: `input_select.bedroom_lighting_mode`
+- AL Switch: `switch.adaptive_lighting_master_bedroom`
-   - LED Color Entity: `number.bedroom_switch_led_color_when_on`
+- LED Entity: `number.master_bedroom_switch_led_color_when_on` (if Inovelli)
-   - Zigbee2MQTT Device Name: `bedroom_switch`
+- Name: "Master Bedroom: Apply Lighting Mode"
 
-2. **Button Actions**:
+**Step 3: Create Weekend Mode Helpers and Automations**
-   - Blueprint: Inovelli Button Actions
+- Toggle: `input_boolean.master_bedroom_weekend_mode`
-   - Switch Action Event: `event.bedroom_switch_action`
+- Schedule automation: Toggle at 22:00
-   - AL Switch: `switch.adaptive_lighting_bedroom`
+- Apply settings automation:
-   - Target Lights: `light.bedroom_ceiling`, `light.bedroom_lamp_1`,
+  - Sunrise: 10:00 (sleep in on weekends)
-     `light.bedroom_lamp_2`
+  - Sunset: 01:00 (stay up later)
-   - Auto-Reset: 30 minutes
+  - Max brightness: 60%
 
-**Testing**:
+### Testing
-- [ ] Press config button → mode cycles through all 5 modes
-- [ ] LED changes color for each mode
-- [ ] Double-tap up → brightness boosts
-- [ ] Weekend mode enables Friday 10pm
-- [ ] Sunrise shifts to 10am on weekend
 
-## Example 2: Living Room (Common Area)
+- [ ] Mode selector cycles through all modes via UI
+- [ ] Lights change appropriately for each mode
+- [ ] LED changes color for each mode (if Inovelli)
+- [ ] Weekend mode enables Friday evening
+- [ ] Sunrise shifts to 10am when weekend mode active
+- [ ] Weekend mode disables Sunday evening
 
-**Goal**: Entertainment modes (Theater, Party), presence control
+## Example 2: Living Room
 
-**Hardware**:
+**Goal**: Entertainment modes (Theater, Party), standard adaptive lighting
-- Inovelli Blue Dimmer: `living_room_switch`
-- Lights: `light.living_room_ceiling`, `light.living_room_lamp_1`
-- Presence: `binary_sensor.living_room_occupancy`
 
-**Package File** (`packages/adaptive_lighting_living_room.yaml`):
+**Room Type**: Common area with social and entertainment use
 
-Copy from `adaptive_lighting_living_room_template.yaml`
+### Adaptive Lighting Configuration
-- Modes: Adaptive, Theater, Party, Reading
-- Auto-reset mode to Adaptive when lights turn off
 
-**Blueprint Automations**:
-
-1. **Config Button Mode Cycling** (same as bedroom)
-2. **Button Actions** (same as bedroom, adjust auto-reset to 15 min)
-3. **Presence Mode Reset**:
-   - Occupancy Sensors: `binary_sensor.living_room_occupancy`
-   - Empty Delay: 5 minutes
-   - AL Switch: `switch.adaptive_lighting_living_room`
-   - Mode Input Select: `input_select.living_room_lighting_mode`
-   - Default Mode: `Adaptive`
-
-**Testing**:
-- [ ] Enter room → lights turn on (via separate occupancy automation)
-- [ ] Press config button → cycles through 4 modes
-- [ ] Set to Theater mode, leave room → after 5 min, resets to Adaptive
-- [ ] Manual boost → leave room → manual control clears
-
-## Example 3: Bathroom (Simple)
-
-**Goal**: Always Adaptive, brightness boost only
-
-**Hardware**:
-- Inovelli Blue Dimmer: `bathroom_switch`
-- Lights: `light.bathroom_ceiling`, `light.bathroom_vanity`
-- Presence: `binary_sensor.bathroom_occupancy`
-
-**Package File** (`packages/adaptive_lighting_bathroom.yaml`):
-
-Copy from `adaptive_lighting_simple_template.yaml`
-- No modes (Adaptive only)
-- No weekend mode
-- Simple reset on presence end
-
-**Blueprint Automations**:
-
-1. **Button Actions ONLY**:
-   - Double-tap up: Boost brightness
-   - Triple-tap down: Night light
-   - Auto-reset: 10 minutes
-
-2. **Presence Mode Reset**:
-   - Reset manual control when empty 5 minutes
-   - No mode reset (no input_select)
-
-**Testing**:
-- [ ] Double-tap up → brightness boosts
-- [ ] Leave bathroom 5 min → manual control clears
-- [ ] Triple-tap down → night light mode
-- [ ] No config button action (not configured)
-
-## Entity ID Quick Reference
-
-### Finding Your Entities
-
-**Inovelli Switch Entities** (via Zigbee2MQTT):
-```
-event.{device_name}_action           # Button presses (event entity)
-number.{device_name}_led_color_when_on
-number.{device_name}_led_color_when_off
-number.{device_name}_led_intensity_when_on
-select.{device_name}_smart_bulb_mode
-select.{device_name}_button_delay
-```
-
-**Adaptive Lighting Entities**:
-```
-switch.adaptive_lighting_{name}
-switch.adaptive_lighting_sleep_mode_{name}
-switch.adaptive_lighting_adapt_brightness_{name}
-switch.adaptive_lighting_adapt_color_{name}
-```
-
-**Your Input Helpers**:
-```
-input_select.{room}_lighting_mode
-input_boolean.{room}_weekend_mode
-```
-
-## Common Customizations
-
-### Add a New Mode
-
-1. Edit package file, add mode to `input_select`:
 ```yaml
-input_select:
+adaptive_lighting:
-  bedroom_lighting_mode:
+  - name: living_room
-    options:
+    lights:
-      - "Adaptive"
+      - light.living_room_ceiling
-      - "Reading"
+      - light.living_room_lamp_1
-      - "NEW MODE HERE"  # Add this
+      - light.living_room_lamp_2
+    interval: 90
+    transition: 30
 ```
 
-2. Add color mapping to global package (or use existing color)
+### UI Configuration Steps
+
+**Step 1: Create Mode Selector**
+- Name: "Living Room Lighting Mode"
+- Entity ID: `input_select.living_room_lighting_mode`
+- Options: Adaptive, Theater, Party, Relaxing
+- Initial: Adaptive
+
+**Step 2: Create Mode Application Automation**
+- Blueprint: Apply Lighting Mode Settings
+- Mode Input Select: `input_select.living_room_lighting_mode`
+- AL Switch: `switch.adaptive_lighting_living_room`
+- LED Entity: `number.living_room_switch_led_color_when_on` (if Inovelli)
+- Name: "Living Room: Apply Lighting Mode"
+
+**Weekend Mode**: Optional for living room - use if you want different behavior on weekends
+
+### Testing
+
+- [ ] Switch to Theater mode → lights dim for movie watching
+- [ ] Switch to Party mode → lights bright and dynamic
+- [ ] Switch to Adaptive → normal adaptive behavior
+- [ ] LED colors match modes (if Inovelli)
+
+## Example 3: Simple Bathroom
+
+**Goal**: Always adaptive, no mode switching needed
+
+**Room Type**: Utility space with simple lighting needs
+
+### Adaptive Lighting Configuration
 
-3. Add mode application to automation:
 ```yaml
-- conditions: "{{ mode == 'NEW MODE HERE' }}"
+adaptive_lighting:
-  sequence:
+  - name: bathroom
-    - service: adaptive_lighting.change_switch_settings
+    lights:
-      data:
+      - light.bathroom_ceiling
-        min_brightness: 50
+      - light.bathroom_vanity
-        max_brightness: 80
+    interval: 60
-        # ... settings
+    transition: 20
 ```
 
-4. Reload YAML configuration
+### UI Configuration Steps
 
-### Change Auto-Reset Timeout
+**Step 1: Create Mode Selector (Minimal)**
+- Name: "Bathroom Lighting Mode"
+- Entity ID: `input_select.bathroom_lighting_mode`
+- Options: Adaptive, Sleep (for night use)
+- Initial: Adaptive
 
-Edit blueprint automation via UI:
+**Step 2: Create Mode Application Automation**
-- Settings → Automations → [Your button action automation]
+- Blueprint: Apply Lighting Mode Settings
-- Click Edit
+- Mode Input Select: `input_select.bathroom_lighting_mode`
-- Adjust "Auto-Reset Timeout" slider
+- AL Switch: `switch.adaptive_lighting_bathroom`
+- LED Entity: Leave empty (likely no Inovelli in bathroom)
+- Name: "Bathroom: Apply Lighting Mode"
+
+**Weekend Mode**: Not needed for bathroom
+
+### Alternative: No Mode Selector At All
+
+If you want **only** adaptive lighting with no manual modes:
+- Skip creating mode selector
+- Skip creating mode application automation
+- Just use Adaptive Lighting integration directly
+- This is the simplest possible setup
+
+### Testing
+
+- [ ] Lights follow adaptive lighting automatically
+- [ ] Optional: Switch to Sleep mode for night bathroom trips
+- [ ] Adaptive mode uses AL defaults
+
+## Testing Checklist
+
+After configuring any room, verify:
+
+### Basic Functionality
+- [ ] All modes switch correctly via UI dropdown
+- [ ] AL settings apply as expected for each mode
+- [ ] Lights change brightness and color temperature appropriately
+- [ ] Mode changes are smooth (transitions work)
+
+### LED Integration (If Inovelli Configured)
+- [ ] LED color updates match mode
+- [ ] LED colors are visible and distinct
+- [ ] LED updates happen immediately after mode change
+
+### Weekend Mode (If Configured)
+- [ ] Weekend mode toggle works manually
+- [ ] Weekend mode enables automatically on Friday/Saturday
+- [ ] Weekend mode disables automatically on Sunday-Thursday
+- [ ] AL adjustments apply when weekend mode turns on
+- [ ] AL settings reset when weekend mode turns off
+
+### Home Assistant Restart
+- [ ] Restart Home Assistant
+- [ ] Verify mode settings persist and apply on startup
+- [ ] Verify weekend mode settings persist and apply on startup
+
+### Error Checking
+- [ ] No errors in Home Assistant logs (Settings → System → Logs)
+- [ ] Automation traces show successful execution (Settings → Automations → [automation] → Traces)
+
+## Customization
+
+### Add Custom Modes to a Room
+
+Want to add "Reading" mode to your bedroom?
+
+**Step 1**: Create the mode settings (see [ADDING_MODES.md](ADDING_MODES.md))
+
+**Step 2**: Edit your room's mode selector helper
+- Settings → Devices & Services → Helpers
+- Find your room's dropdown (e.g., `input_select.master_bedroom_lighting_mode`)
+- Click **Edit**
+- Add "Reading" to options list
 - Save
 
-### Disable Weekend Mode
+**Step 3**: Test
+- Switch to Reading mode via UI
+- Verify it works without any blueprint changes!
 
-Comment out weekend mode automations in package file:
+### Change Weekend Mode Times
-```yaml
-#  - id: bedroom_weekend_mode_auto_enable
-#    alias: "Bedroom: Enable Weekend Mode Friday/Saturday"
-#    # ... entire automation
-```
 
-Reload YAML configuration.
+**Edit the automation**:
+- Settings → Automations & Scenes
+- Find "{Room}: Weekend Mode Apply Settings"
+- Click **Edit**
+- Adjust sunrise time, sunset time, or max brightness
+- Save
+
+Changes apply immediately (no restart needed).
+
+### Remove Weekend Mode
+
+If you no longer want weekend mode:
+
+**Step 1**: Disable automations
+- Settings → Automations & Scenes
+- Find weekend mode automations
+- Toggle them OFF (or delete them)
+
+**Step 2**: Delete helpers (optional)
+- Settings → Devices & Services → Helpers
+- Find weekend mode boolean
+- Delete
+
+### Use Scene-Based Modes
+
+Want a mode that activates a complex scene?
+
+See [ADDING_MODES.md - Advanced Examples](ADDING_MODES.md#advanced-examples) for scene and script-based mode creation.
+
+## Troubleshooting
+
+### Mode Doesn't Change Lights
+
+**Symptom**: Selected mode but lights stayed the same
+
+**Solutions**:
+1. Check automation is enabled: Settings → Automations → "{Room}: Apply Lighting Mode"
+2. View automation trace: Click automation → Traces tab
+3. Verify AL switch entity ID is correct in automation config
+4. Verify mode selector entity ID matches automation config
+5. Check mode settings entity exists: Developer Tools → States → `input_text.adaptive_lighting_settings_{mode}`
+
+### LED Doesn't Change Color
+
+**Symptom**: Mode changes work but LED stays same color
+
+**Solutions**:
+1. Verify LED entity configured in automation (not left empty)
+2. Check LED entity ID is correct (should be `number.{device}_led_color_when_on`)
+3. Test LED manually: Developer Tools → Services → `number.set_value`
+4. Verify Inovelli switch firmware is up to date
+
+### Weekend Mode Doesn't Apply
+
+**Symptom**: Boolean toggles but AL settings don't change
+
+**Solutions**:
+1. Check "Weekend Mode Apply Settings" automation is enabled
+2. View automation trace to see what happened
+3. Verify AL switch entity ID is correct
+4. Manually trigger automation: Developer Tools → Services → `automation.trigger`
+5. Check for errors in logs
+
+### Modes Work But Automation Triggers Too Often
+
+**Symptom**: Automation runs many times for single mode change
+
+**Solutions**:
+- This is expected behavior - automation uses `mode: restart`
+- Check automation traces - should see restart behavior
+- If causing issues, automation is working as designed (debounces rapid changes)
+- No action needed unless you see actual problems
+
+### Can't Find Mode Selector in UI
+
+**Symptom**: Created helper but can't find it on dashboard
+
+**Solutions**:
+1. Check entity was created: Settings → Devices & Services → Helpers
+2. Add to dashboard manually: Edit Dashboard → Add Card → Entities → Select your input_select
+3. Or use in automations/scripts without dashboard visibility
+4. Verify entity ID in Developer Tools → States
+
+## Next Steps
+
+After configuring your first room:
+
+1. **Add more rooms**: Repeat the basic workflow for each room
+2. **Customize modes**: See [ADDING_MODES.md](ADDING_MODES.md) to create custom modes
+3. **Add Inovelli integration**: Use optional blueprints for button control
+4. **Add presence control**: Use presence_mode_reset blueprint for occupancy-based automation
+
+For more information:
+- [ADDING_MODES.md](ADDING_MODES.md) - Custom mode creation tutorial
+- [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) - Global package installation
+- [README.md](README.md) - Main documentation
+- [Adaptive Lighting Docs](https://github.com/basnijholt/adaptive-lighting) - AL integration reference

blueprints/automation/apply_lighting_mode.yaml

@@ -0,0 +1,95 @@
+blueprint:
+  name: Apply Lighting Mode Settings
+  description: Data-driven mode application using convention-based entity lookup
+  domain: automation
+  input:
+    mode_input_select:
+      name: Mode Input Select
+      description: Dropdown helper tracking current lighting mode
+      selector:
+        entity:
+          domain: input_select
+
+    adaptive_lighting_switch:
+      name: Adaptive Lighting Switch
+      description: AL switch for this room
+      selector:
+        entity:
+          domain: switch
+          integration: adaptive_lighting
+
+    led_color_entity:
+      name: LED Color Entity (Optional)
+      description: Number entity for LED color (e.g., Inovelli switch)
+      default: {}
+      selector:
+        entity:
+          domain: number
+
+mode: restart
+max_exceeded: silent
+
+trigger:
+  - platform: state
+    entity_id: !input mode_input_select
+  - platform: homeassistant
+    event: start
+
+variables:
+  mode_select: !input mode_input_select
+  al_switch: !input adaptive_lighting_switch
+  led_entity: !input led_color_entity
+  mode: "{{ states(mode_select) }}"
+  settings_entity: "input_text.adaptive_lighting_settings_{{ mode | lower | replace(' ', '_') }}"
+  settings: "{{ states(settings_entity) | from_json }}"
+  behavior: "{{ settings.behavior | default('adaptive_lighting') }}"
+  manual_control: "{{ settings.manual_control | default(false) }}"
+  al_config: "{{ settings.al_config | default({}) }}"
+  led_color: "{{ settings.led_color | default(170) }}"
+
+action:
+  # Always set manual_control state based on mode settings
+  - service: adaptive_lighting.set_manual_control
+    data:
+      entity_id: "{{ al_switch }}"
+      manual_control: "{{ manual_control }}"
+
+  # Execute behavior-specific actions
+  - choose:
+      # Behavior: adaptive_lighting
+      - conditions: "{{ behavior == 'adaptive_lighting' }}"
+        sequence:
+          - service: adaptive_lighting.change_switch_settings
+            target:
+              entity_id: "{{ al_switch }}"
+            data: >
+              {% if 'use_defaults' not in al_config %}
+                {{ al_config | combine({'use_defaults': 'current'}) }}
+              {% else %}
+                {{ al_config }}
+              {% endif %}
+
+      # Behavior: scene
+      - conditions: "{{ behavior == 'scene' }}"
+        sequence:
+          - service: scene.turn_on
+            target:
+              entity_id: "{{ settings.scene_entity }}"
+
+      # Behavior: script
+      - conditions: "{{ behavior == 'script' }}"
+        sequence:
+          - service: script.turn_on
+            target:
+              entity_id: "{{ settings.script_entity }}"
+
+  # Update LED color if entity provided
+  - if:
+      - condition: template
+        value_template: "{{ led_entity not in [none, {}, ''] }}"
+    then:
+      - service: number.set_value
+        target:
+          entity_id: "{{ led_entity }}"
+        data:
+          value: "{{ led_color }}"

blueprints/automation/inovelli_mode_cycling.yaml

@@ -13,7 +13,8 @@
 # Requirements:
 # - Inovelli Blue Dimmer (VZM31-SN) paired with Zigbee2MQTT
 # - input_select helper with available modes
-# - packages/adaptive_lighting_global.yaml for mode colors
+# - Mode settings entities following convention: input_text.adaptive_lighting_settings_{{mode}}
+# - Each mode must have led_color field in nested JSON schema
 #
 # Reference: ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md lines 144-182
 
@@ -71,8 +72,9 @@ action:
       current_index: "{{ available_modes.index(current_mode) }}"
       next_index: "{{ (current_index + 1) % (available_modes | length) }}"
       next_mode: "{{ available_modes[next_index] }}"
-      mode_colors: "{{ states('input_text.adaptive_lighting_mode_colors') | from_json }}"
+      next_mode_settings_entity: "input_text.adaptive_lighting_settings_{{ next_mode | lower | replace(' ', '_') }}"
-      next_color: "{{ mode_colors.get(next_mode, 170) }}"
+      next_mode_settings: "{{ states(next_mode_settings_entity) | from_json }}"
+      next_color: "{{ next_mode_settings.led_color | default(170) }}"
 
   # Change to next mode
   - service: input_select.select_option

blueprints/automation/weekend_mode_apply_settings.yaml

@@ -0,0 +1,84 @@
+blueprint:
+  name: Weekend Mode Apply Settings
+  description: Adjust AL settings when weekend mode toggles
+  domain: automation
+  input:
+    weekend_mode_boolean:
+      name: Weekend Mode Boolean
+      description: Toggle helper for weekend mode
+      selector:
+        entity:
+          domain: input_boolean
+
+    adaptive_lighting_switch:
+      name: Adaptive Lighting Switch
+      description: AL switch to adjust
+      selector:
+        entity:
+          domain: switch
+          integration: adaptive_lighting
+
+    sunrise_time:
+      name: Weekend Sunrise Time
+      description: Delayed sunrise time for weekends
+      default: "10:00:00"
+      selector:
+        time:
+
+    sunset_time:
+      name: Weekend Sunset Time
+      description: Extended sunset time for weekends
+      default: "01:00:00"
+      selector:
+        time:
+
+    max_brightness:
+      name: Weekend Max Brightness
+      description: Reduced max brightness for weekends
+      default: 60
+      selector:
+        number:
+          min: 1
+          max: 100
+          step: 1
+          unit_of_measurement: "%"
+
+mode: restart
+max_exceeded: silent
+
+trigger:
+  - platform: state
+    entity_id: !input weekend_mode_boolean
+  - platform: homeassistant
+    event: start
+
+variables:
+  weekend_boolean: !input weekend_mode_boolean
+  al_switch: !input adaptive_lighting_switch
+  sunrise_time: !input sunrise_time
+  sunset_time: !input sunset_time
+  max_brightness: !input max_brightness
+  weekend_active: "{{ is_state(weekend_boolean, 'on') }}"
+
+action:
+  - choose:
+      # Weekend mode ON - Apply adjustments
+      - conditions: "{{ weekend_active }}"
+        sequence:
+          - service: adaptive_lighting.change_switch_settings
+            target:
+              entity_id: "{{ al_switch }}"
+            data:
+              sunrise_time: "{{ sunrise_time }}"
+              sunset_time: "{{ sunset_time }}"
+              max_brightness: "{{ max_brightness }}"
+              use_defaults: current
+
+      # Weekend mode OFF - Reset to defaults
+      - conditions: "{{ not weekend_active }}"
+        sequence:
+          - service: adaptive_lighting.change_switch_settings
+            target:
+              entity_id: "{{ al_switch }}"
+            data:
+              use_defaults: configuration

blueprints/automation/weekend_mode_schedule.yaml

@@ -0,0 +1,45 @@
+blueprint:
+  name: Weekend Mode Schedule
+  description: Auto-enable/disable weekend mode based on day of week
+  domain: automation
+  input:
+    weekend_mode_boolean:
+      name: Weekend Mode Boolean
+      description: Toggle helper for weekend mode
+      selector:
+        entity:
+          domain: input_boolean
+
+    toggle_time:
+      name: Toggle Time
+      description: Time to check and toggle weekend mode
+      default: "22:00:00"
+      selector:
+        time:
+
+mode: single
+max_exceeded: silent
+
+trigger:
+  - platform: time
+    at: !input toggle_time
+
+action:
+  - choose:
+      # Friday/Saturday - Enable weekend mode
+      - conditions:
+          - condition: time
+            weekday: [fri, sat]
+        sequence:
+          - service: input_boolean.turn_on
+            target:
+              entity_id: !input weekend_mode_boolean
+
+      # Sunday-Thursday - Disable weekend mode
+      - conditions:
+          - condition: time
+            weekday: [sun, mon, tue, wed, thu]
+        sequence:
+          - service: input_boolean.turn_off
+            target:
+              entity_id: !input weekend_mode_boolean

inovelli/advanced-features.md

@@ -0,0 +1,322 @@
+# Advanced Features Properties
+
+Properties for fan control modes, special operational modes, firmware updates, and advanced configuration via Zigbee2MQTT.
+
+## Fan Control Mode
+
+The switch can be configured to control ceiling fans with multi-tap or cycle modes.
+
+### fanControlMode
+
+- **Type**: Select
+- **Values**: "Disabled", "Multi Tap", "Cycle"
+- **Default**: "Disabled"
+- **Description**: Which mode to use when binding EP3 (config button) to another device (like a fan module). Controls how the switch sends fan speed commands.
+- **Home Assistant Entity**: `select.[device_name]_fan_control_mode`
+- **Use cases**:
+  - Control ceiling fan from dimmer switch
+  - Multi-speed fan control
+  - Coordinate light + fan control
+- **Modes**:
+  - "Disabled": No fan control
+  - "Multi Tap": Different tap counts = different speeds
+  - "Cycle": Each tap cycles through speeds
+
+### lowLevelForFanControlMode
+
+- **Type**: Number
+- **Range**: 2-254
+- **Default**: 33
+- **Description**: Level to send to device bound to EP3 when set to low.
+- **Home Assistant Entity**: `number.[device_name]_low_level_for_fan_control_mode`
+- **Requires**: fanControlMode != "Disabled"
+
+### mediumLevelForFanControlMode
+
+- **Type**: Number
+- **Range**: 2-254
+- **Default**: 66
+- **Description**: Level to send to device bound to EP3 when set to medium.
+- **Home Assistant Entity**: `number.[device_name]_medium_level_for_fan_control_mode`
+- **Requires**: fanControlMode != "Disabled"
+
+### highLevelForFanControlMode
+
+- **Type**: Number
+- **Range**: 2-254
+- **Default**: 100
+- **Description**: Level to send to device bound to EP3 when set to high.
+- **Home Assistant Entity**: `number.[device_name]_high_level_for_fan_control_mode`
+- **Requires**: fanControlMode != "Disabled"
+
+### ledColorForFanControlMode
+
+- **Type**: Number
+- **Range**: 0-255
+- **Default**: 170 (Blue)
+- **Description**: LED color used to display fan control mode.
+- **Home Assistant Entity**: `number.[device_name]_led_color_for_fan_control_mode`
+- **Preset colors**:
+  - `0` = Red
+  - `21` = Orange
+  - `42` = Yellow
+  - `85` = Green
+  - `127` = Cyan
+  - `170` = Blue
+  - `212` = Violet
+  - `234` = Pink
+  - `255` = White
+
+### fanLedLevelType
+
+- **Type**: Number
+- **Range**: 0-10
+- **Default**: 0
+- **Description**: Level display of the LED Strip for fan control.
+- **Home Assistant Entity**: `number.[device_name]_fan_led_level_type`
+- **Presets**:
+  - `0` = Limitless (like VZM31)
+  - `10` = Adaptive LED
+
+## Single Tap Behavior
+
+### singleTapBehavior
+
+- **Type**: Select
+- **Values**: "Old Behavior", "New Behavior", "Down Always Off"
+- **Default**: "Old Behavior"
+- **Description**: Behavior of single tapping the on or off button.
+- **Home Assistant Entity**: `select.[device_name]_single_tap_behavior`
+- **Modes**:
+  - "Old Behavior": Traditional on/off operation
+  - "New Behavior": Cycles through brightness levels
+  - "Down Always Off": Up cycles levels, down always turns off
+- **Use cases**:
+  - Customize paddle tap behavior
+  - Multi-level control without holding
+  - Quick access to preset levels
+
+## Advanced Configuration
+
+### auxSwitchUniqueScenes
+
+- **Type**: Select
+- **Values**: "Disabled", "Enabled"
+- **Default**: "Disabled"
+- **Description**: Have unique scene numbers for scenes activated with the aux switch.
+- **Home Assistant Entity**: `select.[device_name]_aux_switch_unique_scenes`
+- **Use cases**:
+  - Different automations per switch location in 3-way setup
+  - Location-aware scene triggers
+  - Advanced multi-point control systems
+- **Requires**: switchType = "3-Way Aux Switch"
+
+### bindingOffToOnSyncLevel
+
+- **Type**: Select
+- **Values**: "Disabled", "Enabled"
+- **Default**: "Disabled"
+- **Description**: Send Move_To_Level using Default Level with Off/On to bound devices.
+- **Home Assistant Entity**: `select.[device_name]_binding_off_to_on_sync_level`
+- **Use cases**:
+  - Synchronized dimming across Zigbee-bound devices
+  - Match brightness on associated lights
+  - Group control coordination
+- **Note**: Applies when switch binds to other Zigbee devices
+
+### deviceBindNumber
+
+- **Type**: Sensor (read-only)
+- **Description**: The number of devices currently bound (excluding gateways) and counts one group as two devices.
+- **Home Assistant Entity**: `sensor.[device_name]_device_bind_number`
+- **Read-only**: Cannot be changed, reflects current binding status
+- **Use cases**:
+  - Diagnostic information
+  - Verify Zigbee binding configuration
+  - Troubleshoot multi-device coordination
+
+### firmwareUpdateInProgressIndicator
+
+- **Type**: Select
+- **Values**: "Disabled", "Enabled"
+- **Default**: "Enabled"
+- **Description**: Display progress on LED bar during firmware update.
+- **Home Assistant Entity**: `select.[device_name]_firmware_update_in_progress_indicator`
+- **Use cases**:
+  - Visual feedback during OTA firmware update
+  - Indicate update in progress
+  - Disable for discrete updates
+- **Behavior when "Enabled"**:
+  - LED bar shows update progress
+  - Progress indication during OTA update
+  - Provides visual confirmation
+
+### doubleTapClearNotifications
+
+- **Type**: Select
+- **Values**: "Enabled (Default)", "Disabled"
+- **Default**: "Enabled (Default)"
+- **Description**: Double-Tap the Config button to clear notifications.
+- **Home Assistant Entity**: `select.[device_name]_double_tap_clear_notifications`
+- **Use cases**:
+  - Quick notification dismissal
+  - Manual control over persistent LED effects
+  - User convenience for notification management
+
+## Configuration Patterns
+
+### Fan Control Setup (Multi Tap)
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_fan_control_mode
+data:
+  option: "Multi Tap"
+
+# Set fan speed levels
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_low_level_for_fan_control_mode
+data:
+  value: 33  # Low speed
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_medium_level_for_fan_control_mode
+data:
+  value: 66  # Medium speed
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_high_level_for_fan_control_mode
+data:
+  value: 100  # High speed
+
+# Set LED color for fan mode
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_color_for_fan_control_mode
+data:
+  value: 85  # Green
+```
+
+### Cycling Single Tap Behavior
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_single_tap_behavior
+data:
+  option: "New Behavior"  # Cycles through levels
+```
+
+### Location-Aware 3-Way Scenes
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_aux_switch_unique_scenes
+data:
+  option: "Enabled"
+
+# Now bedroom and hallway switches send different scene IDs
+# Create separate automations for each location
+```
+
+### Synchronized Binding
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_binding_off_to_on_sync_level
+data:
+  option: "Enabled"  # Bound devices match this switch's level
+```
+
+### Visual Firmware Updates
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_firmware_update_in_progress_indicator
+data:
+  option: "Enabled"  # Show progress on LED bar
+```
+
+### Config Button Notification Clear
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_double_tap_clear_notifications
+data:
+  option: "Enabled (Default)"  # Double-tap config to clear
+```
+
+## Fan Control Workflow
+
+### Multi-Tap Mode
+With fanControlMode = "Multi Tap":
+- Single tap config: Off
+- Double tap config: Low speed
+- Triple tap config: Medium speed
+- Quadruple tap config: High speed
+
+### Cycle Mode
+With fanControlMode = "Cycle":
+- Each config button tap cycles: Off → Low → Medium → High → Off
+
+### Automation Integration
+
+```yaml
+automation:
+  - alias: "Fan Control via Config Button"
+    trigger:
+      - platform: state
+        entity_id: sensor.bedroom_switch_action
+    action:
+      - choose:
+          - conditions:
+              - condition: state
+                entity_id: sensor.bedroom_switch_action
+                state: "config_double"
+            sequence:
+              - service: fan.set_percentage
+                target:
+                  entity_id: fan.bedroom_fan
+                data:
+                  percentage: 33  # Low
+          - conditions:
+              - condition: state
+                entity_id: sensor.bedroom_switch_action
+                state: "config_triple"
+            sequence:
+              - service: fan.set_percentage
+                target:
+                  entity_id: fan.bedroom_fan
+                data:
+                  percentage: 66  # Medium
+          - conditions:
+              - condition: state
+                entity_id: sensor.bedroom_switch_action
+                state: "config_quadruple"
+            sequence:
+              - service: fan.set_percentage
+                target:
+                  entity_id: fan.bedroom_fan
+                data:
+                  percentage: 100  # High
+```
+
+## Important Notes
+
+- Fan control modes are designed for Zigbee binding to fan controllers
+- Single tap behavior affects all paddle taps (up and down)
+- auxSwitchUniqueScenes requires 3-way aux switch configuration
+- deviceBindNumber is informational only (read-only)
+- firmwareUpdateInProgressIndicator only affects visual feedback, not update function
+- LED effects set via led_effect/individual_led_effect can be cleared with config button double-tap
+- Fan control LED color helps distinguish between light and fan control modes
+- Bindings are managed at the Zigbee level, not via these properties
+- Properties exposed via Zigbee2MQTT; Z-Wave-specific features are not applicable

inovelli/brightness-levels.md

@@ -0,0 +1,236 @@
+# Brightness Levels Properties
+
+Properties controlling brightness limits, default levels when turning on, power restore behavior, and multi-tap brightness shortcuts.
+
+## minimumLevel
+
+- **Type**: Number
+- **Range**: 1-254
+- **Default**: 1 (lowest possible)
+- **Description**: The minimum brightness level the switch can dim to. Prevents dimming below a threshold where lights flicker or turn off.
+- **Home Assistant Entity**: `number.[device_name]_minimum_level`
+- **Use cases**:
+  - Prevent LED bulb flickering at low levels
+  - Set nightlight minimum brightness
+  - Ensure lights never go completely dark when dimming
+- **Common values**:
+  - LED bulbs: 10-20 (prevents flickering)
+  - Incandescent: 1-5 (can dim lower)
+  - Smart bulbs: 1 (handle dimming internally)
+
+## maximumLevel
+
+- **Type**: Number
+- **Range**: 2-255
+- **Default**: 255 (full brightness)
+- **Description**: The maximum brightness level the switch can reach. Limits top-end brightness.
+- **Home Assistant Entity**: `number.[device_name]_maximum_level`
+- **Use cases**:
+  - Limit max brightness to extend bulb life
+  - Reduce energy consumption
+  - Create softer ambient lighting maximum
+  - Protect sensitive loads
+- **Common values**:
+  - Full brightness: 255
+  - Energy saving: 200-230
+  - Ambient lighting: 150-180
+
+## invertSwitch
+
+- **Type**: Select
+- **Values**: "Yes", "No"
+- **Default**: "No" (normal orientation)
+- **Description**: Inverts paddle operation (up becomes down, down becomes up).
+- **Home Assistant Entity**: `select.[device_name]_invert_switch`
+- **Use cases**:
+  - Match 3-way switch orientation
+  - Accommodate non-standard wiring
+  - User preference for reversed operation
+
+## defaultLevelLocal
+
+- **Type**: Number
+- **Range**: 0-255
+- **Default**: 255 (last level or max)
+- **Description**: Brightness level when turned on via physical paddle.
+- **Home Assistant Entity**: `number.[device_name]_default_level_local`
+- **Special values**:
+  - `0-254` = Specific brightness level
+  - `255` = Return to the level that it was on before it was turned off (smart resume)
+- **Use cases**:
+  - Always turn on to comfortable level (e.g., 128 for 50%)
+  - Predictable brightness for specific room uses
+  - Override smart resume for consistent behavior
+
+## defaultLevelRemote
+
+- **Type**: Number
+- **Range**: 0-255
+- **Default**: 255 (last level or max)
+- **Description**: Brightness level when turned on via hub commands (automations/app).
+- **Home Assistant Entity**: `number.[device_name]_default_level_remote`
+- **Special values**:
+  - `0-254` = Specific brightness level
+  - `255` = Return to the level that it was on before it was turned off (smart resume)
+- **Use cases**:
+  - Automations that need predictable brightness
+  - Different default for voice/app control vs physical
+  - Scene activation with specific levels
+
+## stateAfterPowerRestored
+
+- **Type**: Number
+- **Range**: 0-255
+- **Default**: 255 (previous state)
+- **Description**: The state the switch should return to when power is restored after power failure.
+- **Home Assistant Entity**: `number.[device_name]_state_after_power_restored`
+- **Special values**:
+  - `0` = off
+  - `1-254` = Specific brightness level (and turn on)
+  - `255` = Return to previous state before power loss
+- **Use cases**:
+  - Always off after power restore (set to 0)
+  - Emergency lighting (set to specific brightness)
+  - Smart restore to previous state (set to 255)
+
+## brightnessLevelForDoubleTapUp
+
+- **Type**: Number
+- **Range**: 2-255
+- **Default**: 254 (near maximum)
+- **Description**: Set this level on double-tap UP (if enabled by doubleTapUpToParam55).
+- **Home Assistant Entity**: `number.[device_name]_brightness_level_for_double_tap_up`
+- **Special values**:
+  - `2-254` = Specific brightness level
+  - `255` = Send ON command
+- **Use cases**:
+  - Quick full-bright shortcut
+  - Task lighting preset
+  - Scene activation brightness
+- **Prerequisites**: Requires doubleTapUpToParam55 = "Enabled"
+
+## brightnessLevelForDoubleTapDown
+
+- **Type**: Number
+- **Range**: 0-255
+- **Default**: 0
+- **Description**: Set this level on double-tap DOWN (if enabled by doubleTapDownToParam56).
+- **Home Assistant Entity**: `number.[device_name]_brightness_level_for_double_tap_down`
+- **Special values**:
+  - `0` = Send OFF command
+  - `1-254` = Specific brightness level
+  - `255` = Send OFF command
+- **Use cases**:
+  - Quick nightlight mode
+  - Turn off shortcut
+  - Low-light scene activation
+- **Prerequisites**: Requires doubleTapDownToParam56 = "Enabled"
+
+## Configuration Patterns
+
+### Smart Resume (Memory)
+All settings return to previous state/level:
+
+```yaml
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_default_level_local
+    - number.bedroom_switch_default_level_remote
+    - number.bedroom_switch_state_after_power_restored
+data:
+  value: 255  # Remember previous level
+```
+
+### Predictable Lighting
+Always turn on to 50% brightness:
+
+```yaml
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_default_level_local
+    - number.bedroom_switch_default_level_remote
+    - number.bedroom_switch_state_after_power_restored
+data:
+  value: 128  # 50% brightness
+```
+
+### LED Bulb Optimization
+Prevent low-level flicker with memory:
+
+```yaml
+# Prevent flicker
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_minimum_level
+data:
+  value: 15
+
+# Full range at top
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_maximum_level
+data:
+  value: 255
+
+# Smart resume
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_default_level_local
+    - number.bedroom_switch_default_level_remote
+data:
+  value: 255
+```
+
+### Task + Ambient Presets
+Three brightness presets via paddle control:
+
+```yaml
+# Comfortable ambient for single press
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_level_local
+data:
+  value: 180
+
+# Full bright for tasks (double-tap up)
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_brightness_level_for_double_tap_up
+data:
+  value: 254
+
+# Enable double-tap up
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_double_tap_up_to_param55
+data:
+  option: "Enabled"
+
+# Nightlight mode (double-tap down)
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_brightness_level_for_double_tap_down
+data:
+  value: 30
+
+# Enable double-tap down
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_double_tap_down_to_param56
+data:
+  option: "Enabled"
+```
+
+### Inverted Switch
+For upside-down installation:
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_invert_switch
+data:
+  option: "Yes"
+```

inovelli/dimming-and-ramp.md

@@ -0,0 +1,219 @@
+# Dimming & Ramp Control Properties
+
+Properties controlling how the switch dims lights and transitions between brightness levels. Each property has separate settings for "Remote" (commands from Home Assistant hub/automations) and "Local" (physical paddle presses).
+
+## dimmingSpeedUpRemote
+
+- **Type**: Number
+- **Range**: 0-127
+- **Default**: 25
+- **Unit**: 100ms increments (e.g., 25 = 2.5 seconds)
+- **Description**: Changes the speed that the light dims up when controlled from the hub. A setting of 0 turns the light immediately to the target level. Increasing the value slows down the transition speed.
+- **Home Assistant Entity**: `number.[device_name]_dimming_speed_up_remote`
+- **Special values**:
+  - `0` = Instant dimming (no transition)
+  - `1-127` = Duration in 100ms increments
+- **Use cases**: Smooth transitions for automations, gradual wake-up lighting
+
+## dimmingSpeedUpLocal
+
+- **Type**: Number
+- **Range**: 0-127
+- **Default**: 127 (sync with dimmingSpeedUpRemote)
+- **Unit**: 100ms increments
+- **Description**: Changes the speed that the light dims up when controlled at the switch. A setting of 0 turns the light immediately to the target level. Setting to 127 keeps it in sync with dimmingSpeedUpRemote.
+- **Home Assistant Entity**: `number.[device_name]_dimming_speed_up_local`
+- **Special values**:
+  - `0` = Instant dimming
+  - `1-126` = Duration in 100ms increments
+  - `127` = Sync with dimmingSpeedUpRemote
+- **Use cases**: Customize local dimming to be faster or slower than remote control
+
+## rampRateOffToOnRemote
+
+- **Type**: Number
+- **Range**: 0-127
+- **Default**: 127 (sync with dimmingSpeedUpRemote)
+- **Unit**: 100ms increments
+- **Description**: Changes the speed that the light turns on when controlled from the hub. A setting of 0 turns the light immediately on.
+- **Home Assistant Entity**: `number.[device_name]_ramp_rate_off_to_on_remote`
+- **Special values**:
+  - `0` = Instant on
+  - `1-126` = Duration in 100ms increments
+  - `127` = Sync with dimmingSpeedUpRemote
+- **Use cases**: Gentle wake-up lighting, dramatic scene transitions
+
+## rampRateOffToOnLocal
+
+- **Type**: Number
+- **Range**: 0-127
+- **Default**: 127 (sync with dimmingSpeedUpRemote)
+- **Unit**: 100ms increments
+- **Description**: Changes the speed that the light turns on when controlled at the switch. A setting of 0 turns the light immediately on.
+- **Home Assistant Entity**: `number.[device_name]_ramp_rate_off_to_on_local`
+- **Special values**:
+  - `0` = Instant on
+  - `1-126` = Duration in 100ms increments
+  - `127` = Sync with dimmingSpeedUpRemote
+- **Use cases**: Different on-ramp behavior for manual vs automated control
+
+## dimmingSpeedDownRemote
+
+- **Type**: Number
+- **Range**: 0-127
+- **Default**: 127 (sync with dimmingSpeedUpRemote)
+- **Unit**: 100ms increments
+- **Description**: Changes the speed that the light dims down when controlled from the hub. A setting of 0 turns the light immediately to the target level.
+- **Home Assistant Entity**: `number.[device_name]_dimming_speed_down_remote`
+- **Special values**:
+  - `0` = Instant dimming
+  - `1-126` = Duration in 100ms increments
+  - `127` = Sync with dimmingSpeedUpRemote
+- **Use cases**: Asymmetric dimming (e.g., fast up, slow down for sunset effect)
+
+## dimmingSpeedDownLocal
+
+- **Type**: Number
+- **Range**: 0-127
+- **Default**: 127 (sync with dimmingSpeedUpLocal)
+- **Unit**: 100ms increments
+- **Description**: Changes the speed that the light dims down when controlled at the switch. A setting of 0 turns the light immediately to the target level.
+- **Home Assistant Entity**: `number.[device_name]_dimming_speed_down_local`
+- **Special values**:
+  - `0` = Instant dimming
+  - `1-126` = Duration in 100ms increments
+  - `127` = Sync with dimmingSpeedUpLocal
+- **Use cases**: Match or differentiate from remote down-dimming behavior
+
+## rampRateOnToOffRemote
+
+- **Type**: Number
+- **Range**: 0-127
+- **Default**: 127 (sync with rampRateOffToOnRemote)
+- **Unit**: 100ms increments
+- **Description**: Changes the speed that the light turns off when controlled from the hub. A setting of 0 (instant) turns the light immediately off.
+- **Home Assistant Entity**: `number.[device_name]_ramp_rate_on_to_off_remote`
+- **Special values**:
+  - `0` = Instant off
+  - `1-126` = Duration in 100ms increments
+  - `127` = Sync with rampRateOffToOnRemote
+- **Use cases**: Gradual fade to black, bedtime dimming routines
+
+## rampRateOnToOffLocal
+
+- **Type**: Number
+- **Range**: 0-127
+- **Default**: 127 (sync with rampRateOffToOnLocal)
+- **Unit**: 100ms increments
+- **Description**: Changes the speed that the light turns off when controlled at the switch. A setting of 0 (instant) turns the light immediately off.
+- **Home Assistant Entity**: `number.[device_name]_ramp_rate_on_to_off_local`
+- **Special values**:
+  - `0` = Instant off
+  - `1-126` = Duration in 100ms increments
+  - `127` = Sync with rampRateOffToOnLocal
+- **Use cases**: Theater-style fade out, energy-saving gradual shutoff
+
+## Configuration Patterns
+
+### Synchronized Dimming
+Set all local parameters to `127` to use the remote parameters as the master speed control for all dimming operations.
+
+```yaml
+# All in sync with dimmingSpeedUpRemote
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_dimming_speed_up_remote
+data:
+  value: 25  # 2.5 seconds
+
+# Set all local to sync
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_dimming_speed_up_local
+    - number.bedroom_switch_ramp_rate_off_to_on_local
+    - number.bedroom_switch_dimming_speed_down_local
+    - number.bedroom_switch_ramp_rate_on_to_off_local
+data:
+  value: 127  # Sync with remote
+```
+
+### Instant Local, Smooth Remote
+- Local: `0` (instant control)
+- Remote: `50` (5-second smooth transitions)
+
+```yaml
+# Set remote for smooth transitions
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_dimming_speed_up_remote
+    - number.bedroom_switch_ramp_rate_off_to_on_remote
+    - number.bedroom_switch_dimming_speed_down_remote
+    - number.bedroom_switch_ramp_rate_on_to_off_remote
+data:
+  value: 50
+
+# Set local for instant response
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_dimming_speed_up_local
+    - number.bedroom_switch_ramp_rate_off_to_on_local
+    - number.bedroom_switch_dimming_speed_down_local
+    - number.bedroom_switch_ramp_rate_on_to_off_local
+data:
+  value: 0
+```
+
+### Asymmetric Dimming
+- Dim up quickly: `10` (1 second)
+- Dim down slowly: `100` (10 seconds)
+- Creates dynamic lighting feel
+
+```yaml
+# Quick dim up
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_dimming_speed_up_remote
+    - number.bedroom_switch_dimming_speed_up_local
+data:
+  value: 10
+
+# Slow dim down
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_dimming_speed_down_remote
+    - number.bedroom_switch_dimming_speed_down_local
+data:
+  value: 100
+```
+
+### Scene-Based Transitions
+- Off→On ramp: `30` (3 seconds - gentle fade in)
+- On→Off ramp: `100` (10 seconds - slow fade out)
+- Dimming speed: `20` (2 seconds - responsive)
+
+```yaml
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_ramp_rate_off_to_on_remote
+data:
+  value: 30
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_ramp_rate_on_to_off_remote
+data:
+  value: 100
+
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_dimming_speed_up_remote
+    - number.bedroom_switch_dimming_speed_down_remote
+data:
+  value: 20
+```

inovelli/led-configuration.md

@@ -0,0 +1,428 @@
+# LED Configuration Properties
+
+Properties controlling the LED strip on the switch, including colors, intensity levels, animated effects, and display modes. The switch has 7 individual LEDs plus global defaults.
+
+## LED Effects
+
+### led_effect
+
+Composite property to control LED effects for the entire LED bar.
+
+- **Type**: Composite (requires MQTT publish)
+- **Description**: Controls animation effects for all LEDs on the bar
+- **Access**: Set via MQTT publish to `zigbee2mqtt/[device_name]/set`
+- **Properties**:
+  - `effect`: Animation effect type
+  - `color`: Color value (0-255, hue-based)
+  - `level`: Brightness (0-100%)
+  - `duration`: How long the effect lasts
+- **Effect values**:
+  - `off` - Turn off LED effect
+  - `solid` - Solid color
+  - `fast_blink` - Fast blinking
+  - `slow_blink` - Slow blinking
+  - `pulse` - Pulsing effect
+  - `chase` - Chase/running pattern
+  - `open_close` - Open/close animation
+  - `small_to_big` - Small to big animation
+  - `aurora` - Aurora effect
+  - `slow_falling` - Slow falling effect
+  - `medium_falling` - Medium falling effect
+  - `fast_falling` - Fast falling effect
+  - `slow_rising` - Slow rising effect
+  - `medium_rising` - Medium rising effect
+  - `fast_rising` - Fast rising effect
+  - `medium_blink` - Medium blink
+  - `slow_chase` - Slow chase
+  - `fast_chase` - Fast chase
+  - `fast_siren` - Fast siren
+  - `slow_siren` - Slow siren
+  - `clear_effect` - Clear/stop current effect
+- **Duration encoding**:
+  - `1-60` = Seconds
+  - `61-120` = Minutes (value - 60)
+  - `121-254` = Hours (value - 120)
+  - `255` = Indefinitely
+
+**Example usage:**
+```yaml
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"led_effect": {"effect": "pulse", "color": 170, "level": 100, "duration": 255}}'
+```
+
+### individual_led_effect
+
+Composite property to control effects for a single LED.
+
+- **Type**: Composite (requires MQTT publish)
+- **Description**: Controls animation effects for one specific LED
+- **Access**: Set via MQTT publish to `zigbee2mqtt/[device_name]/set`
+- **Properties**:
+  - `led`: LED number (1-7, 1=bottom, 7=top)
+  - `effect`: Animation effect type
+  - `color`: Color value (0-255)
+  - `level`: Brightness (0-100%)
+  - `duration`: How long the effect lasts
+- **LED numbering**: 1 (bottom) through 7 (top)
+- **Effect values**:
+  - `off` - Turn off LED effect
+  - `solid` - Solid color
+  - `fast_blink` - Fast blinking
+  - `slow_blink` - Slow blinking
+  - `pulse` - Pulsing effect
+  - `chase` - Chase pattern
+  - `falling` - Falling effect
+  - `rising` - Rising effect
+  - `aurora` - Aurora effect
+  - `clear_effect` - Clear/stop effect
+- **Duration encoding**: Same as led_effect
+
+**Example usage:**
+```yaml
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"individual_led_effect": {"led": "4", "effect": "fast_blink", "color": 0, "level": 100, "duration": 30}}'
+```
+
+## Global LED Properties
+
+### ledColorWhenOn
+
+- **Type**: Number
+- **Range**: 0-255
+- **Default**: 170 (Blue)
+- **Description**: Default LED strip color when switch is on. Applies to all LEDs unless individually configured.
+- **Home Assistant Entity**: `number.[device_name]_led_color_when_on`
+- **Color wheel mapping**: 0-255 representing hue (0-360° mapped to 0-255)
+- **Preset colors**:
+  - `0` = Red
+  - `21` = Orange
+  - `42` = Yellow
+  - `85` = Green
+  - `127` = Cyan
+  - `170` = Blue
+  - `212` = Violet
+  - `234` = Pink
+  - `255` = White
+
+### ledColorWhenOff
+
+- **Type**: Number
+- **Range**: 0-255
+- **Default**: 170 (Blue)
+- **Description**: Default LED strip color when switch is off.
+- **Home Assistant Entity**: `number.[device_name]_led_color_when_off`
+- **Preset colors**: Same as ledColorWhenOn
+
+### ledIntensityWhenOn
+
+- **Type**: Number
+- **Range**: 0-100
+- **Default**: 33 (33%)
+- **Description**: Default LED strip brightness when switch is on.
+- **Home Assistant Entity**: `number.[device_name]_led_intensity_when_on`
+- **Special values**:
+  - `0` = LEDs off (no indicator when on)
+  - `1-100` = Brightness percentage
+- **Common values**:
+  - Night mode: `5-10`
+  - Default: `33`
+  - Maximum visibility: `100`
+
+### ledIntensityWhenOff
+
+- **Type**: Number
+- **Range**: 0-100
+- **Default**: 1 (1%)
+- **Description**: Default LED strip brightness when switch is off.
+- **Home Assistant Entity**: `number.[device_name]_led_intensity_when_off`
+- **Common values**:
+  - Nightlight: `1-5`
+  - Locator: `10-20`
+  - Off (stealth): `0`
+
+## Individual LED Properties
+
+Each of the 7 LEDs can be individually configured with color and intensity for both on and off states. LED #1 is the bottom, LED #7 is the top.
+
+### LED #1 (Bottom)
+
+- **Color When On**: `number.[device_name]_default_led1_color_when_on` (0-255, 255=sync with global)
+- **Color When Off**: `number.[device_name]_default_led1_color_when_off` (0-255, 255=sync with global)
+- **Intensity When On**: `number.[device_name]_default_led1_intensity_when_on` (0-101, 101=sync)
+- **Intensity When Off**: `number.[device_name]_default_led1_intensity_when_off` (0-101, 101=sync)
+
+### LED #2
+
+- **Color When On**: `number.[device_name]_default_led2_color_when_on`
+- **Color When Off**: `number.[device_name]_default_led2_color_when_off`
+- **Intensity When On**: `number.[device_name]_default_led2_intensity_when_on`
+- **Intensity When Off**: `number.[device_name]_default_led2_intensity_when_off`
+
+### LED #3
+
+- **Color When On**: `number.[device_name]_default_led3_color_when_on`
+- **Color When Off**: `number.[device_name]_default_led3_color_when_off`
+- **Intensity When On**: `number.[device_name]_default_led3_intensity_when_on`
+- **Intensity When Off**: `number.[device_name]_default_led3_intensity_when_off`
+
+### LED #4 (Middle)
+
+- **Color When On**: `number.[device_name]_default_led4_color_when_on`
+- **Color When Off**: `number.[device_name]_default_led4_color_when_off`
+- **Intensity When On**: `number.[device_name]_default_led4_intensity_when_on`
+- **Intensity When Off**: `number.[device_name]_default_led4_intensity_when_off`
+
+### LED #5
+
+- **Color When On**: `number.[device_name]_default_led5_color_when_on`
+- **Color When Off**: `number.[device_name]_default_led5_color_when_off`
+- **Intensity When On**: `number.[device_name]_default_led5_intensity_when_on`
+- **Intensity When Off**: `number.[device_name]_default_led5_intensity_when_off`
+
+### LED #6
+
+- **Color When On**: `number.[device_name]_default_led6_color_when_on`
+- **Color When Off**: `number.[device_name]_default_led6_color_when_off`
+- **Intensity When On**: `number.[device_name]_default_led6_intensity_when_on`
+- **Intensity When Off**: `number.[device_name]_default_led6_intensity_when_off`
+
+### LED #7 (Top)
+
+- **Color When On**: `number.[device_name]_default_led7_color_when_on`
+- **Color When Off**: `number.[device_name]_default_led7_color_when_off`
+- **Intensity When On**: `number.[device_name]_default_led7_intensity_when_on`
+- **Intensity When Off**: `number.[device_name]_default_led7_intensity_when_off`
+
+**Note**: Individual LED color set to `255` or intensity set to `101` means "follow global default"
+
+## LED Display Modes
+
+### ledBarScaling
+
+- **Type**: Select
+- **Values**: "Gen3 method (VZM-style)", "Gen2 method (LZW-style)"
+- **Default**: "Gen3 method (VZM-style)"
+- **Description**: Controls how LED bar represents dimmer level.
+- **Home Assistant Entity**: `select.[device_name]_led_bar_scaling`
+- **Use cases**: Match behavior of older Inovelli switches for consistency
+
+### onOffLedMode
+
+- **Type**: Select
+- **Values**: "All", "One"
+- **Default**: "All"
+- **Description**: When in On/Off mode, use full LED bar or just one LED.
+- **Home Assistant Entity**: `select.[device_name]_on_off_led_mode`
+- **Use cases**:
+  - Match Gen 2 Red/Black series appearance
+  - Preference for single LED indicator
+  - Reduce LED brightness/distraction
+
+## Configuration Patterns
+
+### Standard Blue Indicator
+
+```yaml
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_color_when_on
+data:
+  value: 170  # Blue
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_color_when_off
+data:
+  value: 170  # Blue
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_intensity_when_on
+data:
+  value: 33
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_intensity_when_off
+data:
+  value: 1
+```
+
+### Green On / Red Off
+
+```yaml
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_color_when_on
+data:
+  value: 85  # Green
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_color_when_off
+data:
+  value: 0  # Red
+
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_led_intensity_when_on
+    - number.bedroom_switch_led_intensity_when_off
+data:
+  value: 40
+```
+
+### Stealth Mode
+
+```yaml
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_led_intensity_when_on
+    - number.bedroom_switch_led_intensity_when_off
+data:
+  value: 0
+```
+
+### Nightlight Mode
+
+```yaml
+# Soft pink when off, dark when on
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_color_when_off
+data:
+  value: 234  # Pink
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_intensity_when_off
+data:
+  value: 5
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_led_intensity_when_on
+data:
+  value: 0
+```
+
+### Rainbow Bar (Individual LEDs)
+
+```yaml
+# Set each LED to a different color
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_default_led1_color_when_on
+data:
+  value: 0  # Red
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_led2_color_when_on
+data:
+  value: 42  # Yellow
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_led3_color_when_on
+data:
+  value: 85  # Green
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_led4_color_when_on
+data:
+  value: 127  # Cyan
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_led5_color_when_on
+data:
+  value: 170  # Blue
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_led6_color_when_on
+data:
+  value: 212  # Violet
+
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_default_led7_color_when_on
+data:
+  value: 234  # Pink
+```
+
+### Notification Alert (Pulse Red)
+
+```yaml
+# 30 second red pulse on all LEDs
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"led_effect": {"effect": "pulse", "color": 0, "level": 100, "duration": 30}}'
+```
+
+### Status Indicator (Middle LED Blink)
+
+```yaml
+# Blink middle LED (LED 4) blue for 1 minute
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"individual_led_effect": {"led": "4", "effect": "fast_blink", "color": 170, "level": 100, "duration": 60}}'
+```
+
+### Doorbell Notification (Fast Chase)
+
+```yaml
+# Fast chase effect in cyan for 10 seconds
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"led_effect": {"effect": "fast_chase", "color": 127, "level": 100, "duration": 10}}'
+```
+
+### Clear All Effects
+
+```yaml
+service: mqtt.publish
+data:
+  topic: zigbee2mqtt/bedroom_switch/set
+  payload: '{"led_effect": {"effect": "clear_effect"}}'
+```
+
+## LED Color Palette
+
+Quick reference for common colors (hue-based, 0-255):
+- `0` - Red
+- `21` - Orange
+- `42` - Yellow
+- `64` - Yellow-Green
+- `85` - Green
+- `106` - Cyan-Green
+- `127` - Cyan
+- `148` - Blue-Cyan
+- `170` - Blue (default)
+- `191` - Blue-Violet
+- `212` - Violet
+- `223` - Magenta
+- `234` - Pink
+- `244` - Pink-Red
+- `255` - White
+
+## Notes
+
+- Individual LED properties override global defaults
+- Setting individual LED color to `255` makes it follow global color
+- Setting individual LED intensity to `101` makes it follow global intensity
+- LED effects from `led_effect` and `individual_led_effect` are temporary
+- Effects automatically clear after duration expires or when `clear_effect` is sent
+- Property changes take effect immediately without requiring switch reboot
+- Use MQTT publish for LED effects; they cannot be set via Home Assistant number/select entities

inovelli/power-monitoring.md

@@ -0,0 +1,364 @@
+# Power & Energy Monitoring Properties
+
+Properties for power consumption measurement, energy usage tracking, and reporting thresholds via Zigbee2MQTT.
+
+## Sensor Properties (Read-Only)
+
+### power
+
+- **Type**: Sensor (read-only)
+- **Unit**: Watts (W)
+- **Description**: Instantaneous measured power consumption of the connected load.
+- **Home Assistant Entity**: `sensor.[device_name]_power`
+- **Updates**: Based on activePowerReports threshold or periodicPowerAndEnergyReports interval
+- **Use cases**:
+  - Real-time power monitoring
+  - Detect when lights turn on/off
+  - Track power consumption changes
+  - Trigger automations based on power usage
+
+### energy
+
+- **Type**: Sensor (read-only)
+- **Unit**: Kilowatt-hours (kWh)
+- **Description**: Cumulative energy consumption over time.
+- **Home Assistant Entity**: `sensor.[device_name]_energy`
+- **Updates**: Based on activeEnergyReports threshold or periodicPowerAndEnergyReports interval
+- **Use cases**:
+  - Long-term energy tracking
+  - Billing/cost calculations
+  - Energy usage analytics
+  - Historical consumption trends
+
+## Reporting Configuration
+
+### activePowerReports
+
+- **Type**: Number
+- **Range**: 0-100
+- **Default**: 10 (10% change)
+- **Description**: Percent power level change that will result in a new power report being sent. 0 = Disabled.
+- **Home Assistant Entity**: `number.[device_name]_active_power_reports`
+- **Special values**:
+  - `0` = Disabled (no automatic power reports based on change)
+  - `1-100` = Percentage change threshold
+- **Use cases**:
+  - Real-time power monitoring
+  - Detect significant power changes
+  - Trigger automations based on power delta
+- **Common values**:
+  - Sensitive monitoring: `5` (5% change)
+  - Default: `10` (10% change)
+  - Reduce network traffic: `20` (20% change)
+- **Network impact**: Lower values generate more Zigbee traffic
+
+### periodicPowerAndEnergyReports
+
+- **Type**: Number
+- **Range**: 0-32767
+- **Default**: 3600 seconds (1 hour)
+- **Description**: Time period between consecutive power & energy reports being sent (in seconds). The timer is reset after each report is sent.
+- **Home Assistant Entity**: `number.[device_name]_periodic_power_and_energy_reports`
+- **Units**: Seconds
+- **Special values**:
+  - `0` = Disabled (no periodic reports)
+  - `1-32767` = Report interval in seconds
+- **Use cases**:
+  - Regular energy usage logging
+  - Dashboard updates
+  - Long-term consumption tracking
+  - Backup reporting if active reports miss changes
+- **Common values**:
+  - Frequent updates: `300` (5 minutes)
+  - Default: `3600` (1 hour)
+  - Reduce traffic: `7200` (2 hours)
+  - Daily: `86400` (24 hours)
+- **Note**: Works alongside activePowerReports and activeEnergyReports (not instead of)
+
+### activeEnergyReports
+
+- **Type**: Number
+- **Range**: 0-32767
+- **Default**: 10 (0.10 kWh)
+- **Description**: Energy level change which will result in sending a new energy report. 0 = disabled, 1-32767 = 0.01kWh-327.67kWh.
+- **Home Assistant Entity**: `number.[device_name]_active_energy_reports`
+- **Units**: 0.01 kWh (value of 10 = 0.10 kWh = 100 Wh)
+- **Special values**:
+  - `0` = Disabled (no automatic energy reports based on accumulation)
+  - `1-32767` = Threshold in 0.01 kWh increments
+- **Use cases**:
+  - Track cumulative energy consumption
+  - Billing/cost calculations
+  - Energy usage analytics
+  - Trigger automations at energy milestones
+- **Common values**:
+  - Sensitive: `1` (0.01 kWh = 10 Wh)
+  - Default: `10` (0.10 kWh = 100 Wh)
+  - Reduce traffic: `100` (1.0 kWh)
+- **Example**: Default of 10 means report every 100 Wh (0.1 kWh) consumed
+
+## Performance Tuning
+
+### quickStartTime
+
+- **Type**: Number
+- **Range**: 0-60
+- **Default**: 0 (disabled)
+- **Description**: Duration of full power output while lamp transitions from Off to On. In 60th of second. 0 = disable, 1 = 1/60s, 60 = 1s.
+- **Home Assistant Entity**: `number.[device_name]_quick_start_time`
+- **Units**: 1/60th of a second
+- **Use cases**:
+  - Help LED bulbs start reliably
+  - Overcome LED driver inrush requirements
+  - Prevent flickering on startup
+- **Common values**:
+  - Disabled: `0`
+  - Short boost: `10` (0.17 seconds)
+  - Default boost: `20` (0.33 seconds)
+  - Long boost: `60` (1 second)
+
+### quickStartLevel
+
+- **Type**: Number
+- **Range**: 1-254
+- **Default**: 254 (near full power)
+- **Description**: Level of power output during Quick Start Light time (quickStartTime).
+- **Home Assistant Entity**: `number.[device_name]_quick_start_level`
+- **Use cases**:
+  - Ensure LED bulbs receive enough initial power to start
+  - Match bulb requirements for startup
+- **Requires**: quickStartTime > 0
+
+### higherOutputInNonNeutral
+
+- **Type**: Select
+- **Values**: "Disabled (default)", "Enabled"
+- **Default**: "Disabled (default)"
+- **Description**: Increase output level in non-neutral mode to help bulbs start and operate properly.
+- **Home Assistant Entity**: `select.[device_name]_higher_output_in_non_neutral`
+- **Use cases**:
+  - Non-neutral installations with LED bulbs
+  - Improve dimming range in non-neutral mode
+  - Help bulbs work better without neutral wire
+- **Note**: Only applies to non-neutral wiring configurations
+
+## Power Type Detection
+
+### powerType
+
+- **Type**: Sensor (read-only)
+- **Values**: "Non Neutral", "Neutral"
+- **Description**: Detected power wiring type.
+- **Home Assistant Entity**: `sensor.[device_name]_power_type`
+- **Read-only**: Cannot be changed by user, automatically detected
+- **Use cases**:
+  - Diagnostic information
+  - Verify wiring configuration
+  - Troubleshooting installation issues
+- **Note**: Automatically detected by switch hardware
+
+## Configuration Patterns
+
+### Real-Time Power Monitoring
+
+```yaml
+# Sensitive power change detection
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_active_power_reports
+data:
+  value: 5  # Report on 5% power change
+
+# Frequent periodic backup
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_periodic_power_and_energy_reports
+data:
+  value: 300  # Every 5 minutes
+
+# Disable energy threshold reports (focus on power)
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_active_energy_reports
+data:
+  value: 0  # Disabled
+```
+
+### Energy Usage Tracking
+
+```yaml
+# Less sensitive power reports
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_active_power_reports
+data:
+  value: 20  # Report on 20% change
+
+# Hourly periodic reports
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_periodic_power_and_energy_reports
+data:
+  value: 3600  # Every hour
+
+# Energy threshold reporting
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_active_energy_reports
+data:
+  value: 10  # Report every 0.1 kWh
+```
+
+### Low Network Traffic
+
+```yaml
+# High power change threshold
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_active_power_reports
+data:
+  value: 25  # 25% change
+
+# 2-hour periodic reports
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_periodic_power_and_energy_reports
+data:
+  value: 7200
+
+# High energy threshold
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_active_energy_reports
+data:
+  value: 100  # Every 1 kWh
+```
+
+### LED Bulb Quick Start
+
+```yaml
+# Enable quick start with 1/3 second boost
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_quick_start_time
+data:
+  value: 20  # 20/60 = 0.33 seconds
+
+# Full power during quick start
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_quick_start_level
+data:
+  value: 254  # Near maximum
+```
+
+### Non-Neutral Optimization
+
+```yaml
+# Enable higher output for non-neutral
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_higher_output_in_non_neutral
+data:
+  option: "Enabled"
+
+# May also need quick start
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_quick_start_time
+data:
+  value: 30  # 0.5 seconds
+```
+
+### Disable All Monitoring
+
+```yaml
+# Turn off all automatic reporting
+service: number.set_value
+target:
+  entity_id:
+    - number.bedroom_switch_active_power_reports
+    - number.bedroom_switch_periodic_power_and_energy_reports
+    - number.bedroom_switch_active_energy_reports
+data:
+  value: 0
+```
+
+## Reporting Behavior
+
+The switch can send reports via three independent mechanisms:
+1. **Active Power Reports**: Sent when power changes by threshold percentage
+2. **Active Energy Reports**: Sent when accumulated energy reaches threshold
+3. **Periodic Reports**: Sent at regular time intervals
+
+All three work independently and can be used together for comprehensive monitoring.
+
+## Home Assistant Integration Example
+
+### Power-Based Automation
+
+```yaml
+automation:
+  - alias: "Detect Light On"
+    trigger:
+      - platform: numeric_state
+        entity_id: sensor.bedroom_switch_power
+        above: 5  # 5W threshold
+    action:
+      - service: notify.mobile_app
+        data:
+          message: "Bedroom light turned on ({{ states('sensor.bedroom_switch_power') }}W)"
+
+  - alias: "Detect Light Off"
+    trigger:
+      - platform: numeric_state
+        entity_id: sensor.bedroom_switch_power
+        below: 1  # Less than 1W
+        for:
+          seconds: 5
+    action:
+      - service: notify.mobile_app
+        data:
+          message: "Bedroom light turned off"
+```
+
+### Energy Cost Tracking
+
+```yaml
+automation:
+  - alias: "Daily Energy Report"
+    trigger:
+      - platform: time
+        at: "23:59:00"
+    action:
+      - service: notify.mobile_app
+        data:
+          message: >
+            Bedroom light energy today: {{ states('sensor.bedroom_switch_energy') }} kWh
+            Estimated cost: ${{ (states('sensor.bedroom_switch_energy') | float * 0.12) | round(2) }}
+```
+
+## Example Calculations
+
+### Power Threshold
+activePowerReports = `20` → Report when power changes by 20%
+- Load at 40W, dims to 35W: Change is 12.5%, no report
+- Load at 40W, dims to 30W: Change is 25%, report sent
+
+### Energy Threshold
+activeEnergyReports = `50` → Report every 0.5 kWh (500 Wh)
+- 100W bulb for 5 hours: 500 Wh consumed → Report sent
+
+### Periodic Reporting
+periodicPowerAndEnergyReports = `1800` → Report every 30 minutes
+- Regardless of power/energy changes, status sent every 30min
+
+## Important Notes
+
+- All reporting properties work independently
+- Power and energy sensors update based on configured thresholds
+- quickStartTime/Level only applies to the transition from off to on
+- higherOutputInNonNeutral only helps in non-neutral wiring setups
+- Sensors are read-only; only configuration properties can be set
+- Lower reporting thresholds increase Zigbee network traffic
+- Power readings may have ~1W accuracy tolerance

inovelli/protection-safety.md

@@ -0,0 +1,213 @@
+# Protection & Safety Properties
+
+Properties for device protection, temperature monitoring, access control, and overheat safety features via Zigbee2MQTT.
+
+## Temperature Monitoring (Read-Only)
+
+### internalTemperature
+
+- **Type**: Sensor (read-only)
+- **Range**: 0-127°C
+- **Unit**: Degrees Celsius (°C)
+- **Description**: The temperature measured by the temperature sensor inside the chip, in degrees Celsius.
+- **Home Assistant Entity**: `sensor.[device_name]_internal_temperature`
+- **Read-only**: Cannot be changed by user, reports actual temperature
+- **Use cases**:
+  - Monitor switch health
+  - Detect overheating conditions
+  - Trigger cooling automations
+  - Diagnostic information
+- **Normal range**: Typically 30-50°C during operation
+- **Warning signs**:
+  - Above 60°C: High temperature, check ventilation
+  - Above 70°C: Overheat protection may activate
+
+### overheat
+
+- **Type**: Sensor (read-only)
+- **Values**: "No Alert", "Overheated"
+- **Description**: Indicates if the internal chipset is currently in an overheated state.
+- **Home Assistant Entity**: `sensor.[device_name]_overheat`
+- **Read-only**: Cannot be changed by user, reports protection status
+- **Use cases**:
+  - Safety monitoring
+  - Alert when switch is overheating
+  - Diagnostic for load issues
+  - Automation triggers for problems
+- **Behavior when "Overheated"**:
+  - Switch may reduce output or shut off load
+  - LED may indicate error state
+  - Switch protects itself from damage
+- **Recovery**: Automatically resets when temperature drops to safe level
+- **Causes**:
+  - Excessive load (too many bulbs/watts)
+  - Poor ventilation (box too small, insulation)
+  - High ambient temperature
+  - Short circuit or wiring issues
+
+## Access Control
+
+### localProtection
+
+- **Type**: Select
+- **Values**: "Disabled", "Enabled"
+- **Default**: "Disabled"
+- **Description**: Ability to control switch from the wall. When enabled, disables physical paddle control.
+- **Home Assistant Entity**: `select.[device_name]_local_protection`
+- **Use cases**:
+  - Child safety locks
+  - Prevent accidental changes
+  - Commercial applications
+  - Force automation-only control
+- **Behavior when "Enabled"**:
+  - Paddle presses do nothing
+  - Zigbee commands still work
+  - Switch can only be controlled via hub/automations
+  - LED effects still respond to paddle (visual feedback)
+- **Override**: Can be disabled via Zigbee command from hub
+- **Note**: Does not affect config button or air-gap switch
+
+### remoteProtection
+
+- **Type**: Sensor (read-only via Zigbee2MQTT)
+- **Values**: "Disabled", "Enabled"
+- **Default**: "Disabled"
+- **Description**: Ability to control switch from the hub.
+- **Home Assistant Entity**: `sensor.[device_name]_remote_protection`
+- **Read-only via Zigbee2MQTT**: Status can be read but not changed remotely
+- **Use cases**:
+  - Prevent automation interference
+  - Local control only mode
+  - Troubleshooting automation issues
+- **Behavior when "Enabled"**:
+  - Paddle works normally
+  - Zigbee on/off/dim commands ignored
+  - Configuration commands may still be accepted
+  - Switch operates as manual-only dimmer
+
+## Configuration Patterns
+
+### Standard Operation (No Protection)
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_local_protection
+data:
+  option: "Disabled"
+```
+
+### Child Lock (Paddle Disabled)
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_local_protection
+data:
+  option: "Enabled"
+```
+
+### Temperature Monitoring Automation
+
+```yaml
+automation:
+  - alias: "Inovelli Overheat Alert"
+    trigger:
+      - platform: numeric_state
+        entity_id: sensor.bedroom_switch_internal_temperature
+        above: 60
+    action:
+      - service: notify.mobile_app
+        data:
+          message: "Bedroom switch overheating: {{ states('sensor.bedroom_switch_internal_temperature') }}°C"
+
+  - alias: "Inovelli Overheat Protection Triggered"
+    trigger:
+      - platform: state
+        entity_id: sensor.bedroom_switch_overheat
+        to: "Overheated"
+    action:
+      - service: notify.mobile_app
+        data:
+          message: "ALERT: Bedroom switch overheat protection activated!"
+          title: "Switch Overheat"
+      - service: light.turn_off
+        entity_id: light.bedroom_switch
+```
+
+## Safety Considerations
+
+### Overheat Protection
+The switch has built-in thermal protection that cannot be disabled:
+- Monitors internal temperature continuously
+- Automatically reduces output if too hot
+- Protects switch from permanent damage
+- Resets automatically when cooled
+
+### Common Causes of Overheating
+1. **Overloaded circuit**: Too many bulbs/high wattage
+2. **Poor ventilation**: Tight gang box, spray foam insulation
+3. **Non-neutral wiring**: Generates more heat
+4. **Ambient temperature**: Hot attic/outdoor locations
+5. **Electrical issues**: Poor connections, high resistance
+
+### Prevention
+- Don't exceed rated wattage (typically 150W LED, 300W incandescent)
+- Ensure adequate box size and ventilation
+- Use fan/cooling for hot environments
+- Regular temperature monitoring via automations
+- Quality bulbs that don't overdraw current
+
+### Emergency Procedures
+If overheat protection triggers:
+1. Check overheat sensor status
+2. Read internalTemperature value
+3. Turn off load via Zigbee if possible
+4. Allow switch to cool (15-30 minutes)
+5. Investigate cause before restoring power
+6. Reduce load or improve ventilation
+
+## Protection Use Cases
+
+### Vacation Mode Child Lock
+```yaml
+# Before leaving, disable paddle
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_local_protection
+data:
+  option: "Enabled"
+
+# Configure automations for lighting schedule
+```
+
+### Critical Lighting Protection
+```yaml
+# For always-on circuits (security, safety)
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_local_protection
+data:
+  option: "Enabled"
+```
+
+### Commercial Installation
+```yaml
+# Public spaces - prevent tampering
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_local_protection
+data:
+  option: "Enabled"
+```
+
+## Important Notes
+
+- localProtection can be changed remotely via Zigbee2MQTT
+- remoteProtection is read-only via Zigbee2MQTT
+- Physical config button can reset protections if needed
+- Air-gap switch always works regardless of protection settings
+- Overheat protection is hardware-based and cannot be disabled
+- Temperature monitoring via internalTemperature sensor
+- Local + Remote protection together creates fully locked state (not recommended)
+- Temperature readings update based on reporting configuration

inovelli/switch-config.md

@@ -0,0 +1,296 @@
+# Switch Configuration Properties
+
+Properties defining switch type, operational modes, hardware configuration, and timing behavior for Zigbee2MQTT integration.
+
+## Switch Type & Wiring
+
+### switchType
+
+- **Type**: Select
+- **Values**: "Single Pole", "3-Way Dumb Switch", "3-Way Aux Switch", "Single-Pole Full Sine Wave"
+- **Default**: "Single Pole"
+- **Description**: Configures the physical switch wiring type and companion switch behavior.
+- **Home Assistant Entity**: `select.[device_name]_switch_type`
+- **Use cases**:
+  - Single location: "Single Pole"
+  - Multi-location with dumb 3-way: "3-Way Dumb Switch"
+  - Multi-location with Aux switch: "3-Way Aux Switch"
+  - Ceiling fan control: "Single-Pole Full Sine Wave"
+- **Important**: Must match actual wiring configuration
+
+### powerType
+
+- **Type**: Sensor (read-only)
+- **Values**: "Non Neutral", "Neutral"
+- **Description**: Detected power wiring type.
+- **Home Assistant Entity**: `sensor.[device_name]_power_type`
+- **Read-only**: Automatically detected by switch hardware
+- **Use cases**:
+  - Diagnostic information
+  - Verify wiring configuration
+  - Troubleshooting installation issues
+
+### dimmingMode
+
+- **Type**: Sensor (read-only)
+- **Values**: "Leading edge", "Trailing edge"
+- **Default**: "Trailing edge"
+- **Description**: Dimming method used for load control. Can only be changed at the switch.
+- **Home Assistant Entity**: `sensor.[device_name]_dimming_mode`
+- **Read-only via Zigbee2MQTT**: Must be configured at the physical switch
+- **Use cases**:
+  - LED bulbs: "Trailing edge"
+  - Incandescent: "Leading edge"
+  - Troubleshooting flicker/buzz issues
+- **Note**: Trailing edge only available on neutral single-pole and neutral multi-way with aux switch
+
+## Operational Modes
+
+### outputMode
+
+- **Type**: Select
+- **Values**: "Dimmer", "On/Off"
+- **Default**: "Dimmer"
+- **Description**: Switches between dimmer and on/off only operation.
+- **Home Assistant Entity**: `select.[device_name]_output_mode`
+- **Use cases**:
+  - Dimming incompatible loads: "On/Off"
+  - Standard operation: "Dimmer"
+  - User preference for simple on/off: "On/Off"
+- **Behavior in On/Off mode**:
+  - Paddle only turns on/off (no dimming)
+  - Commands still accept brightness levels
+  - No ramp rates (instant on/off)
+  - Simpler operation for non-dimmable loads
+
+### smartBulbMode
+
+- **Type**: Select
+- **Values**: "Disabled", "Smart Bulb Mode"
+- **Default**: "Disabled"
+- **Description**: Keeps power always on to load, disables dimming. For smart bulbs that need constant power.
+- **Home Assistant Entity**: `select.[device_name]_smart_bulb_mode`
+- **Use cases**:
+  - Regular dumb bulbs: "Disabled"
+  - Philips Hue, LIFX, other smart bulbs: "Smart Bulb Mode"
+  - Smart switches in parallel with dimmer: "Smart Bulb Mode"
+- **Behavior when enabled**:
+  - Load receives constant full power
+  - Switch still sends Zigbee commands
+  - Paddle controls scenes/automations, not load directly
+  - LED bar still shows "virtual" dimming level
+- **Important**: Required for smart bulbs to maintain Wi-Fi/Zigbee/Z-Wave control
+
+### relayClick
+
+- **Type**: Select
+- **Values**: "Disabled (Click Sound On)", "Enabled (Click Sound Off)"
+- **Default**: "Disabled (Click Sound On)"
+- **Description**: Controls audible relay click sound. In neutral on/off setups, you may disable the click sound by creating a "simulated" on/off where the switch only turns on to 100 or off to 0.
+- **Home Assistant Entity**: `select.[device_name]_relay_click`
+- **Use cases**:
+  - Silent operation (bedrooms): "Enabled" (removes click)
+  - Normal operation: "Disabled" (click present)
+- **Note**: Only applies to neutral on/off mode configurations
+
+## Timing & Button Behavior
+
+### buttonDelay
+
+- **Type**: Select
+- **Values**: "0ms", "100ms", "200ms", "300ms", "400ms", "500ms", "600ms", "700ms", "800ms", "900ms"
+- **Default**: "500ms"
+- **Description**: Delay before switch responds to paddle press. Allows multi-tap detection.
+- **Home Assistant Entity**: `select.[device_name]_button_delay`
+- **Special values**:
+  - "0ms" = Instant response (disables multi-tap features and button press events)
+  - "500ms" = Default, balanced
+  - "700ms"-"900ms" = More forgiving multi-tap timing
+- **Use cases**:
+  - Instant control: "0ms" (no multi-tap)
+  - Default multi-tap: "500ms" (good balance)
+  - Reliable multi-tap: "700ms" or higher
+- **Trade-off**: Higher values enable easier multi-tap but slower single-press response
+
+## LED Display Modes
+
+### ledBarScaling
+
+- **Type**: Select
+- **Values**: "Gen3 method (VZM-style)", "Gen2 method (LZW-style)"
+- **Default**: "Gen3 method (VZM-style)"
+- **Description**: Controls how LED bar represents dimmer level.
+- **Home Assistant Entity**: `select.[device_name]_led_bar_scaling`
+- **Use cases**: Match behavior of older Inovelli switches for consistency
+
+### onOffLedMode
+
+- **Type**: Select
+- **Values**: "All", "One"
+- **Default**: "All"
+- **Description**: When in On/Off mode, use full LED bar or just one LED.
+- **Home Assistant Entity**: `select.[device_name]_on_off_led_mode`
+- **Use cases**:
+  - Match Gen 2 Red/Black series appearance: "One"
+  - Standard bar graph: "All"
+  - Reduce LED brightness/distraction: "One"
+
+## Configuration Patterns
+
+### Standard Single-Pole Installation
+
+```yaml
+service: select.select_option
+target:
+  entity_id:
+    - select.bedroom_switch_switch_type
+    - select.bedroom_switch_output_mode
+    - select.bedroom_switch_smart_bulb_mode
+data:
+  option: "Single Pole"
+
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_output_mode
+data:
+  option: "Dimmer"
+
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_smart_bulb_mode
+data:
+  option: "Disabled"
+```
+
+### 3-Way with Aux Switch
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_switch_type
+data:
+  option: "3-Way Aux Switch"
+
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_button_delay
+data:
+  option: "500ms"  # Allow multi-tap
+```
+
+### Smart Bulb Control
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_switch_type
+data:
+  option: "Single Pole"
+
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_smart_bulb_mode
+data:
+  option: "Smart Bulb Mode"
+
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_output_mode
+data:
+  option: "Dimmer"  # Virtual dimming for scenes
+```
+
+### Non-Dimmable Load
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_output_mode
+data:
+  option: "On/Off"
+```
+
+### Silent Operation (No Relay Click)
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_relay_click
+data:
+  option: "Enabled"  # Removes click sound
+```
+
+### Multi-Tap Optimization
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_button_delay
+data:
+  option: "700ms"  # Reliable double-tap detection
+
+# Also enable double-tap shortcuts
+service: select.select_option
+target:
+  entity_id:
+    - select.bedroom_switch_double_tap_up_to_param55
+    - select.bedroom_switch_double_tap_down_to_param56
+data:
+  option: "Enabled"
+```
+
+### Instant Response (No Scenes)
+
+```yaml
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_button_delay
+data:
+  option: "0ms"  # Instant, but disables button events
+
+# Note: 0ms disables multi-tap and button press events entirely
+```
+
+## Troubleshooting Guide
+
+### Bulb Flickers
+- Check dimmingMode (can only be changed at switch, not via Zigbee2MQTT)
+- Increase minimumLevel property
+- Verify bulb is dimmable
+- Try smartBulbMode if using smart bulbs
+
+### Buzzing/Humming
+- Try changing dimmingMode at the physical switch
+- Reduce load (fewer bulbs)
+- Verify bulb compatibility with dimmer
+
+### Aux Switch Not Working
+- Verify switchType = "3-Way Aux Switch"
+- Check wiring: Line, Load, Traveler
+- Ensure Aux switch is compatible (GE/Inovelli)
+
+### Smart Bulbs Lose Connection
+- Enable smartBulbMode = "Smart Bulb Mode"
+- This keeps power constant to bulbs
+
+### Switch Too Slow/Too Fast
+- Adjust buttonDelay
+- Lower = faster response, harder multi-tap
+- Higher = slower response, easier multi-tap
+- "0ms" disables button events entirely
+
+### Non-Neutral Installation Issues
+- Check powerType sensor to verify detection
+- Ensure minimum load requirements met
+- May need bypass capacitor for LED loads
+- Consider higherOutputInNonNeutral option
+
+## Important Notes
+
+- dimmingMode can only be changed at the physical switch, not via Zigbee2MQTT
+- powerType is automatically detected and read-only
+- smartBulbMode is essential for any smart bulb integration
+- buttonDelay of "0ms" completely disables button press events and multi-tap
+- relayClick only applies to specific neutral on/off configurations
+- switchType must match your actual wiring for proper operation
+- LED scaling and mode options provide compatibility with older Inovelli switches

inovelli/timers-automation.md

@@ -0,0 +1,341 @@
+# Timers & Automation Properties
+
+Properties for time-based features including auto-off timers, LED timeouts, multi-tap shortcuts, and button press events via Zigbee2MQTT.
+
+## Auto-Off Timer
+
+### autoTimerOff
+
+- **Type**: Number
+- **Range**: 0-32767
+- **Default**: 0 (disabled)
+- **Unit**: Seconds
+- **Description**: Automatically turns the switch off after this many seconds. When the switch is turned on a timer is started. When the timer expires, the switch is turned off. 0 = Auto off is disabled.
+- **Home Assistant Entity**: `number.[device_name]_auto_timer_off`
+- **Special values**:
+  - `0` = Disabled (no auto-off)
+  - `1-32767` = Time in seconds before auto-off
+- **Use cases**:
+  - Bathroom fan auto-off
+  - Closet lights safety shutoff
+  - Energy saving for forgotten lights
+  - Timed task lighting
+- **Common values**:
+  - 3 minutes: `180`
+  - 5 minutes: `300`
+  - 15 minutes: `900`
+  - 30 minutes: `1800`
+  - 1 hour: `3600`
+  - 2 hours: `7200`
+- **Behavior**:
+  - Timer starts when load is turned on
+  - Resets if manually turned off then on again
+  - Works for both local (paddle) and remote (hub) activation
+  - Switch turns off automatically when timer expires
+- **Maximum**: ~9 hours (32767 seconds)
+
+## LED Indicator Timeout
+
+### loadLevelIndicatorTimeout
+
+- **Type**: Select
+- **Values**: "Stay Off", "1 Second", "2 Seconds", "3 Seconds", "4 Seconds", "5 Seconds", "6 Seconds", "7 Seconds", "8 Seconds", "9 Seconds", "10 Seconds", "Stay On"
+- **Default**: "3 Seconds"
+- **Description**: Shows the level that the load is at for x number of seconds after the load is adjusted and then returns to the Default LED state. 0 = Stay Off, 1-10 = seconds, 11 = Stay On.
+- **Home Assistant Entity**: `select.[device_name]_load_level_indicator_timeout`
+- **Use cases**:
+  - Show brightness level briefly after adjustment
+  - Return to default LED color/intensity after timeout
+  - Visual feedback for dimming changes
+- **Behavior**:
+  - When brightness is adjusted
+  - LED bar shows actual load level
+  - After timeout, returns to configured LED state (ledColorWhen*, ledIntensityWhen*)
+
+## Multi-Tap Shortcuts
+
+### doubleTapUpToParam55
+
+- **Type**: Select
+- **Values**: "Disabled", "Enabled"
+- **Default**: "Disabled"
+- **Description**: Enable or Disable setting level to brightnessLevelForDoubleTapUp on double-tap UP.
+- **Home Assistant Entity**: `select.[device_name]_double_tap_up_to_param55`
+- **Use cases**:
+  - Quick full-bright shortcut
+  - Task lighting activation
+  - Scene trigger for bright preset
+- **Prerequisites**:
+  - Requires buttonDelay > "0ms" for multi-tap detection
+  - Target level set in brightnessLevelForDoubleTapUp
+- **Behavior**:
+  - Works from any current brightness or off state
+  - Jumps directly to brightnessLevelForDoubleTapUp level
+  - Can be used to trigger automations via action events
+
+### doubleTapDownToParam56
+
+- **Type**: Select
+- **Values**: "Disabled", "Enabled"
+- **Default**: "Disabled"
+- **Description**: Enable or Disable setting level to brightnessLevelForDoubleTapDown on double-tap DOWN.
+- **Home Assistant Entity**: `select.[device_name]_double_tap_down_to_param56`
+- **Use cases**:
+  - Quick dim/nightlight mode
+  - Quick off shortcut
+  - Scene trigger for dim preset
+- **Prerequisites**:
+  - Requires buttonDelay > "0ms" for multi-tap detection
+  - Target level set in brightnessLevelForDoubleTapDown
+- **Behavior**:
+  - Works from any current brightness
+  - Jumps directly to brightnessLevelForDoubleTapDown level
+  - If brightnessLevelForDoubleTapDown = 0, turns off
+  - Can be used to trigger automations via action events
+
+## Button Press Events
+
+### action
+
+- **Type**: Sensor (read-only, event-based)
+- **Description**: Triggered action (e.g. a button click). Events are published to this entity when paddle/config button is pressed.
+- **Home Assistant Entity**: `event.[device_name]_action`
+- **Event values**:
+  - `down_single`, `up_single`, `config_single` - Single tap
+  - `down_release`, `up_release`, `config_release` - Button released
+  - `down_held`, `up_held`, `config_held` - Button held
+  - `down_double`, `up_double`, `config_double` - Double tap
+  - `down_triple`, `up_triple`, `config_triple` - Triple tap
+  - `down_quadruple`, `up_quadruple`, `config_quadruple` - Quadruple tap
+  - `down_quintuple`, `up_quintuple`, `config_quintuple` - Quintuple tap
+- **Use cases**:
+  - Trigger Home Assistant automations based on button presses
+  - Multi-tap scene control
+  - Advanced automation logic
+- **Prerequisites**: buttonDelay > "0ms" (setting to "0ms" disables button events)
+
+## Configuration Patterns
+
+### Bathroom Fan Auto-Off (15 minutes)
+
+```yaml
+service: number.set_value
+target:
+  entity_id: number.bathroom_fan_auto_timer_off
+data:
+  value: 900  # 15 minutes
+```
+
+### Closet Light Safety (5 minutes)
+
+```yaml
+service: number.set_value
+target:
+  entity_id: number.closet_light_auto_timer_off
+data:
+  value: 300  # 5 minutes
+```
+
+### Quick Brightness Shortcuts
+
+```yaml
+# Enable button delay for multi-tap detection
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_button_delay
+data:
+  option: "500ms"
+
+# Enable double-tap up
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_double_tap_up_to_param55
+data:
+  option: "Enabled"
+
+# Set bright level for double-tap up
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_brightness_level_for_double_tap_up
+data:
+  value: 254  # Nearly full brightness
+
+# Enable double-tap down
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_double_tap_down_to_param56
+data:
+  option: "Enabled"
+
+# Set nightlight level for double-tap down
+service: number.set_value
+target:
+  entity_id: number.bedroom_switch_brightness_level_for_double_tap_down
+data:
+  value: 20  # Dim nightlight
+```
+
+### LED Level Indicator Timing
+
+```yaml
+# Show level for 5 seconds after adjustment
+service: select.select_option
+target:
+  entity_id: select.bedroom_switch_load_level_indicator_timeout
+data:
+  option: "5 Seconds"
+```
+
+## Button Press Automation Examples
+
+### Double-Tap Scene Trigger
+
+```yaml
+automation:
+  - alias: "Bedroom Double-Tap Up - Movie Mode"
+    trigger:
+      - platform: state
+        entity_id: sensor.bedroom_switch_action
+        to: "up_double"
+    action:
+      - service: scene.turn_on
+        target:
+          entity_id: scene.movie_mode
+
+  - alias: "Bedroom Double-Tap Down - Nighttime"
+    trigger:
+      - platform: state
+        entity_id: sensor.bedroom_switch_action
+        to: "down_double"
+    action:
+      - service: scene.turn_on
+        target:
+          entity_id: scene.nighttime
+```
+
+### Triple-Tap for All Lights
+
+```yaml
+automation:
+  - alias: "Kitchen Triple-Tap Up - All Lights On"
+    trigger:
+      - platform: state
+        entity_id: sensor.kitchen_switch_action
+        to: "up_triple"
+    action:
+      - service: light.turn_on
+        target:
+          entity_id: all
+
+  - alias: "Kitchen Triple-Tap Down - All Lights Off"
+    trigger:
+      - platform: state
+        entity_id: sensor.kitchen_switch_action
+        to: "down_triple"
+    action:
+      - service: light.turn_off
+        target:
+          entity_id: all
+```
+
+### Config Button Custom Action
+
+```yaml
+automation:
+  - alias: "Config Button - Toggle Guest Mode"
+    trigger:
+      - platform: state
+        entity_id: sensor.bedroom_switch_action
+        to: "config_double"
+    action:
+      - service: input_boolean.toggle
+        target:
+          entity_id: input_boolean.guest_mode
+```
+
+### Held Button for Scenes
+
+```yaml
+automation:
+  - alias: "Up Held - Gradually Brighten"
+    trigger:
+      - platform: state
+        entity_id: sensor.bedroom_switch_action
+        to: "up_held"
+    action:
+      - service: light.turn_on
+        target:
+          entity_id: light.bedroom_switch
+        data:
+          brightness_pct: 100
+          transition: 10
+
+  - alias: "Down Held - Gradually Dim"
+    trigger:
+      - platform: state
+        entity_id: sensor.bedroom_switch_action
+        to: "down_held"
+    action:
+      - service: light.turn_on
+        target:
+          entity_id: light.bedroom_switch
+        data:
+          brightness_pct: 1
+          transition: 10
+```
+
+## Auto-Off Timer Examples
+
+### Common Applications
+
+**Bathroom Exhaust Fan**
+```yaml
+# 15 minutes
+service: number.set_value
+target:
+  entity_id: number.bathroom_fan_auto_timer_off
+data:
+  value: 900
+```
+
+**Laundry Room**
+```yaml
+# 1 hour
+service: number.set_value
+target:
+  entity_id: number.laundry_room_auto_timer_off
+data:
+  value: 3600
+```
+
+**Garage Workshop**
+```yaml
+# 2 hours
+service: number.set_value
+target:
+  entity_id: number.garage_auto_timer_off
+data:
+  value: 7200
+```
+
+**Pantry/Closet**
+```yaml
+# 3 minutes
+service: number.set_value
+target:
+  entity_id: number.pantry_auto_timer_off
+data:
+  value: 180
+```
+
+## Important Notes
+
+- autoTimerOff works independently of other features
+- loadLevelIndicatorTimeout only affects load level display, not LED effects
+- Multi-tap features require buttonDelay > "0ms" for detection
+- Setting buttonDelay to "0ms" disables ALL button events (action sensor)
+- Double-tap can both change brightness AND trigger automations via action events
+- action sensor events can trigger automations for any tap pattern
+- Auto-off timer resets on each manual on/off cycle
+- Button events are published to the action sensor for Home Assistant automations
+- Use action events for complex scene control and multi-location logic

multi_press_action.yaml

@@ -1,127 +0,0 @@
-blueprint:
-  name: Multi-Press Action
-  description: Trigger different actions based on how many times an entity changes state rapidly
-  domain: automation
-  input:
-    trigger_entity:
-      name: Trigger Entity
-      description: The entity to monitor for state changes
-      selector:
-        entity: {}
-
-    press_counter:
-      name: Multi-Press Counter
-      description: House-wide counter helper for tracking presses (create counter.multi_press_counter)
-      default: counter.multi_press_counter
-      selector:
-        entity:
-          domain: counter
-
-    time_window:
-      name: Time Window
-      description: Maximum time between presses (in seconds)
-      default: 1.5
-      selector:
-        number:
-          min: 0.5
-          max: 5
-          step: 0.1
-          unit_of_measurement: seconds
-
-    immediate_single_press:
-      name: Execute Single Press Immediately
-      description: If enabled, single press action runs immediately without waiting. If disabled, waits to see if it's a multi-press before acting.
-      default: true
-      selector:
-        boolean: {}
-
-    single_press_action:
-      name: Single Press Action
-      description: Action to run on single press
-      default: []
-      selector:
-        action: {}
-
-    double_press_action:
-      name: Double Press Action
-      description: Action to run on double press
-      default: []
-      selector:
-        action: {}
-
-    triple_press_action:
-      name: Triple Press Action
-      description: Action to run on triple press
-      default: []
-      selector:
-        action: {}
-
-    quad_press_action:
-      name: Quad Press Action
-      description: Action to run on quad press (4 times)
-      default: []
-      selector:
-        action: {}
-
-mode: restart
-max_exceeded: silent
-
-trigger:
-  - platform: state
-    entity_id: !input trigger_entity
-
-action:
-  - variables:
-      time_window: !input time_window
-      immediate: !input immediate_single_press
-      counter_entity: !input press_counter
-
-  # Increment the counter (each restart = new press)
-  - action: counter.increment
-    target:
-      entity_id: !input press_counter
-
-  # Execute single press immediately if enabled
-  - if:
-      - condition: template
-        value_template: "{{ immediate and states(counter_entity) | int == 1 }}"
-    then:
-      - choose:
-          - conditions: []
-            sequence: !input single_press_action
-
-  # Wait for the time window to see if more presses come
-  - delay:
-      seconds: "{{ time_window }}"
-
-  # Get final press count and execute appropriate action
-  - variables:
-      final_count: "{{ states(counter_entity) | int }}"
-
-  # Reset counter before executing actions
-  - action: counter.reset
-    target:
-      entity_id: !input press_counter
-
-  # Execute action based on final press count
-  - choose:
-      # Only run single press if NOT immediate (delayed mode)
-      - conditions:
-          - condition: template
-            value_template: "{{ final_count == 1 and not immediate }}"
-        sequence: !input single_press_action
-
-      - conditions:
-          - condition: template
-            value_template: "{{ final_count == 2 }}"
-        sequence: !input double_press_action
-
-      - conditions:
-          - condition: template
-            value_template: "{{ final_count == 3 }}"
-        sequence: !input triple_press_action
-
-      - conditions:
-          - condition: template
-            value_template: "{{ final_count >= 4 }}"
-        sequence: !input quad_press_action

packages/adaptive_lighting_bedroom_template.yaml

@@ -1,235 +0,0 @@
-# packages/adaptive_lighting_bedroom_template.yaml
-#
-# Adaptive Lighting Mode System - Bedroom Template
-#
-# CUSTOMIZATION INSTRUCTIONS:
-# 1. Copy this file to a new file named after your room (e.g., adaptive_lighting_master_bedroom.yaml)
-# 2. Search and replace "bedroom" with your room name throughout
-# 3. Update entity IDs to match your actual devices
-# 4. Adjust available modes in input_select as desired
-# 5. Customize mode settings in the automation
-# 6. Place in config/packages/ directory
-#
-# Prerequisites:
-# - packages/adaptive_lighting_global.yaml loaded
-# - Adaptive Lighting integration installed
-# - Adaptive Lighting switch created for this room
-# - Inovelli Blue Dimmer paired with Zigbee2MQTT in Smart Bulb Mode
-#
-# Reference: ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md lines 1589-1672
-
-# =============================================================================
-# INPUT HELPERS
-# =============================================================================
-
-input_select:
-  bedroom_lighting_mode:
-    name: "Bedroom Lighting Mode"
-    options:
-      - "Adaptive"       # Standard AL following sun
-      - "Reading"        # Bright, cool white
-      - "Relaxing"       # Dim, warm white
-      - "Sleep"          # Very dim, red/amber
-      - "Manual Override" # Full user control, AL paused
-    initial: "Adaptive"
-    icon: mdi:lightbulb-multiple
-
-input_boolean:
-  bedroom_weekend_mode:
-    name: "Bedroom Weekend Mode"
-    icon: mdi:sleep
-    initial: off
-
-# =============================================================================
-# AUTOMATIONS
-# =============================================================================
-
-automation:
-  # ---------------------------------------------------------------------------
-  # Mode Application
-  # ---------------------------------------------------------------------------
-  # When mode changes, apply appropriate Adaptive Lighting settings
-  # Reference: ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md lines 192-306
-  # ---------------------------------------------------------------------------
-  - id: bedroom_apply_lighting_mode
-    alias: "Bedroom: Apply Lighting Mode Settings"
-    description: "Apply AL settings based on selected lighting mode"
-    mode: restart
-    trigger:
-      - platform: state
-        entity_id: input_select.bedroom_lighting_mode
-      - platform: homeassistant
-        event: start
-    variables:
-      mode: "{{ states('input_select.bedroom_lighting_mode') }}"
-      switch_entity: "switch.adaptive_lighting_bedroom"  # UPDATE THIS
-      mode_colors: "{{ states('input_text.adaptive_lighting_mode_colors') | from_json }}"
-    action:
-      - choose:
-          # Adaptive Mode - Standard AL following sun
-          - conditions:
-              - condition: template
-                value_template: "{{ mode == 'Adaptive' }}"
-            sequence:
-              - service: adaptive_lighting.set_manual_control
-                data:
-                  entity_id: "{{ switch_entity }}"
-                  manual_control: false
-              - service: adaptive_lighting.change_switch_settings
-                target:
-                  entity_id: "{{ switch_entity }}"
-                data:
-                  use_defaults: configuration
-
-          # Reading Mode - Bright cool white
-          # Option 1: Read from centralized settings (recommended for maintainability)
-          - conditions:
-              - condition: template
-                value_template: "{{ mode == 'Reading' }}"
-            sequence:
-              - variables:
-                  settings: "{{ states('input_text.adaptive_lighting_settings_reading') | from_json }}"
-              - service: adaptive_lighting.set_manual_control
-                data:
-                  entity_id: "{{ switch_entity }}"
-                  manual_control: false
-              - service: adaptive_lighting.change_switch_settings
-                target:
-                  entity_id: "{{ switch_entity }}"
-                data: "{{ settings | combine({'use_defaults': 'current'}) }}"
-
-          # Alternative: Hardcode values directly (simpler but less maintainable)
-          # - conditions:
-          #     - condition: template
-          #       value_template: "{{ mode == 'Reading' }}"
-          #   sequence:
-          #     - service: adaptive_lighting.change_switch_settings
-          #       data:
-          #         min_brightness: 80
-          #         max_brightness: 100
-          #         min_color_temp: 4500
-          #         max_color_temp: 5500
-          #         transition: 2
-          #         use_defaults: current
-
-          # Relaxing Mode - Dim warm white
-          - conditions:
-              - condition: template
-                value_template: "{{ mode == 'Relaxing' }}"
-            sequence:
-              - variables:
-                  settings: "{{ states('input_text.adaptive_lighting_settings_relaxing') | from_json }}"
-              - service: adaptive_lighting.set_manual_control
-                data:
-                  entity_id: "{{ switch_entity }}"
-                  manual_control: false
-              - service: adaptive_lighting.change_switch_settings
-                target:
-                  entity_id: "{{ switch_entity }}"
-                data: "{{ settings | combine({'use_defaults': 'current'}) }}"
-
-          # Sleep Mode - Very dim red/amber
-          - conditions:
-              - condition: template
-                value_template: "{{ mode == 'Sleep' }}"
-            sequence:
-              - variables:
-                  settings: "{{ states('input_text.adaptive_lighting_settings_sleep') | from_json }}"
-              - service: adaptive_lighting.set_manual_control
-                data:
-                  entity_id: "{{ switch_entity }}"
-                  manual_control: false
-              - service: adaptive_lighting.change_switch_settings
-                target:
-                  entity_id: "{{ switch_entity }}"
-                data: "{{ settings | combine({'use_defaults': 'current'}) }}"
-
-          # Manual Override - Pause AL completely
-          - conditions:
-              - condition: template
-                value_template: "{{ mode == 'Manual Override' }}"
-            sequence:
-              - service: adaptive_lighting.set_manual_control
-                data:
-                  entity_id: "{{ switch_entity }}"
-                  manual_control: true
-
-      # Update LED color on Inovelli switch to match mode
-      # NOTE: Update entity_id to match your switch
-      - service: number.set_value
-        target:
-          entity_id: number.bedroom_switch_led_color_when_on  # UPDATE THIS
-        data:
-          value: "{{ mode_colors.get(mode, 170) }}"
-
-  # ---------------------------------------------------------------------------
-  # Weekend Mode - Auto Enable/Disable
-  # ---------------------------------------------------------------------------
-  # Reference: ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md lines 894-926
-  # ---------------------------------------------------------------------------
-  - id: bedroom_weekend_mode_auto_enable
-    alias: "Bedroom: Enable Weekend Mode Friday/Saturday"
-    trigger:
-      - platform: time
-        at: "22:00:00"
-    condition:
-      - condition: time
-        weekday: ["fri", "sat"]
-    action:
-      - service: input_boolean.turn_on
-        target:
-          entity_id: input_boolean.bedroom_weekend_mode
-
-  - id: bedroom_weekend_mode_auto_disable
-    alias: "Bedroom: Disable Weekend Mode Sunday-Thursday"
-    trigger:
-      - platform: time
-        at: "22:00:00"
-    condition:
-      - condition: time
-        weekday: ["sun", "mon", "tue", "wed", "thu"]
-    action:
-      - service: input_boolean.turn_off
-        target:
-          entity_id: input_boolean.bedroom_weekend_mode
-
-  # ---------------------------------------------------------------------------
-  # Weekend Mode - Apply AL Adjustments
-  # ---------------------------------------------------------------------------
-  # Reference: ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md lines 928-961
-  # ---------------------------------------------------------------------------
-  - id: bedroom_weekend_mode_apply
-    alias: "Bedroom: Apply Weekend Mode AL Adjustments"
-    trigger:
-      - platform: state
-        entity_id: input_boolean.bedroom_weekend_mode
-      - platform: homeassistant
-        event: start
-    variables:
-      weekend_mode: "{{ is_state('input_boolean.bedroom_weekend_mode', 'on') }}"
-      switch_entity: "switch.adaptive_lighting_bedroom"  # UPDATE THIS
-    action:
-      - choose:
-          - conditions:
-              - condition: template
-                value_template: "{{ weekend_mode }}"
-            sequence:
-              # Weekend settings: Later sunrise, lower max brightness
-              - service: adaptive_lighting.change_switch_settings
-                target:
-                  entity_id: "{{ switch_entity }}"
-                data:
-                  sunrise_time: "10:00:00"
-                  sunset_time: "01:00:00"
-                  max_brightness: 60
-                  use_defaults: current
-          - conditions:
-              - condition: template
-                value_template: "{{ not weekend_mode }}"
-            sequence:
-              # Weekday settings: Reset to defaults
-              - service: adaptive_lighting.change_switch_settings
-                target:
-                  entity_id: "{{ switch_entity }}"
-                data:
-                  use_defaults: configuration

packages/adaptive_lighting_global.yaml

@@ -9,106 +9,76 @@
 #     packages: !include_dir_named packages/
 
 # =============================================================================
-# MODE COLOR MAPPINGS (ROYGBIV Scheme)
+# MODE SETTINGS DEFINITIONS
 # =============================================================================
-# These colors are used for LED feedback on Inovelli switches
+# Each mode has its own input_text helper with nested JSON schema
-# Values are hue (0-255) for Zigbee2MQTT ledColorWhenOn/Off parameter
+# Schema: {"behavior": "adaptive_lighting"|"scene"|"script",
-#
+#          "manual_control": true|false,
-# Reference ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md lines 112-131
+#          "led_color": 0-255,
+#          "al_config": {AL settings dict}}
+# Room automations use convention-based lookup to apply settings
 # =============================================================================
 
 input_text:
-  adaptive_lighting_mode_colors:
-    name: "AL Mode Color Mappings (JSON)"
-    max: 255
-    # JSON minified to fit in 255 char limit
-    initial: >-
-      {"Adaptive":170,"Reading":42,"Relaxing":21,"Sleep":0,
-      "Manual Override":212,"Theater":127,"Party":234,"Homework":85,
-      "Play":148,"Cooking":42,"Dining":21,"Cleanup":170}
-
-# =============================================================================
-# MODE SETTINGS DEFINITIONS
-# =============================================================================
-# Each mode has its own input_text helper to stay within 255 char limit
-# Room automations read these to apply appropriate AL settings
-# =============================================================================
-
   # Adaptive mode - uses default AL configuration
   adaptive_lighting_settings_adaptive:
     name: "AL Settings: Adaptive"
     max: 255
-    initial: '{"use_defaults":"configuration"}'
+    initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":170,"al_config":{"use_defaults":"configuration"}}'
-
-  # Reading mode - bright, cool white
-  adaptive_lighting_settings_reading:
-    name: "AL Settings: Reading"
-    max: 255
-    initial: '{"min_brightness":80,"max_brightness":100,"min_color_temp":4500,"max_color_temp":5500,"transition":2}'
 
   # Relaxing mode - dim, warm white
   adaptive_lighting_settings_relaxing:
     name: "AL Settings: Relaxing"
     max: 255
-    initial: '{"min_brightness":20,"max_brightness":40,"min_color_temp":2000,"max_color_temp":2500,"transition":5}'
+    initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":21,"al_config":{"min_brightness":20,"max_brightness":40,"min_color_temp":2000,"max_color_temp":2500,"transition":5}}'
 
   # Sleep mode - very dim red/amber
   adaptive_lighting_settings_sleep:
     name: "AL Settings: Sleep"
     max: 255
-    initial: '{"min_brightness":1,"max_brightness":5,"min_color_temp":2000,"sleep_rgb_color":[255,50,0],"transition":2}'
+    initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":0,"al_config":{"min_brightness":1,"max_brightness":5,"min_color_temp":2000,"sleep_rgb_color":[255,50,0],"transition":2}}'
 
   # Theater mode - dim, cool for movies
   adaptive_lighting_settings_theater:
     name: "AL Settings: Theater"
     max: 255
-    initial: '{"min_brightness":5,"max_brightness":20,"min_color_temp":3000,"max_color_temp":4000,"transition":3}'
+    initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":127,"al_config":{"min_brightness":5,"max_brightness":20,"min_color_temp":3000,"max_color_temp":4000,"transition":3}}'
 
   # Party mode - bright, dynamic for socializing
   adaptive_lighting_settings_party:
     name: "AL Settings: Party"
     max: 255
-    initial: '{"min_brightness":60,"max_brightness":90,"min_color_temp":3500,"max_color_temp":4500,"transition":1}'
+    initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":234,"al_config":{"min_brightness":60,"max_brightness":90,"min_color_temp":3500,"max_color_temp":4500,"transition":1}}'
-
-  # Homework mode - bright, neutral for focus
-  adaptive_lighting_settings_homework:
-    name: "AL Settings: Homework"
-    max: 255
-    initial: '{"min_brightness":85,"max_brightness":100,"min_color_temp":4000,"max_color_temp":5000,"transition":2}'
-
-  # Play mode - medium bright, energizing
-  adaptive_lighting_settings_play:
-    name: "AL Settings: Play"
-    max: 255
-    initial: '{"min_brightness":60,"max_brightness":85,"min_color_temp":4000,"max_color_temp":5000,"transition":2}'
 
   # Cooking mode - bright, cool task lighting
   adaptive_lighting_settings_cooking:
     name: "AL Settings: Cooking"
     max: 255
-    initial: '{"min_brightness":90,"max_brightness":100,"min_color_temp":4500,"max_color_temp":5500,"transition":1}'
+    initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":42,"al_config":{"min_brightness":90,"max_brightness":100,"min_color_temp":4500,"max_color_temp":5500,"transition":1}}'
 
   # Dining mode - medium, warm for meals
   adaptive_lighting_settings_dining:
     name: "AL Settings: Dining"
     max: 255
-    initial: '{"min_brightness":40,"max_brightness":70,"min_color_temp":2500,"max_color_temp":3500,"transition":3}'
+    initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":21,"al_config":{"min_brightness":40,"max_brightness":70,"min_color_temp":2500,"max_color_temp":3500,"transition":3}}'
 
   # Cleanup mode - bright, standard for cleaning
   adaptive_lighting_settings_cleanup:
     name: "AL Settings: Cleanup"
     max: 255
-    initial: '{"min_brightness":80,"max_brightness":100,"min_color_temp":4000,"max_color_temp":5000,"transition":1}'
+    initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":170,"al_config":{"min_brightness":80,"max_brightness":100,"min_color_temp":4000,"max_color_temp":5000,"transition":1}}'
-
-# Manual Override mode - pauses AL completely (no settings needed)
 
 # =============================================================================
 # USAGE NOTES
 # =============================================================================
-# To access mode colors in templates:
+# To access mode settings in blueprints/automations:
-#   {% set colors = states('input_text.adaptive_lighting_mode_colors') | from_json %}
+#   {% set mode = states('input_select.room_lighting_mode') %}
-#   {{ colors.get('Reading', 170) }}
+#   {% set settings_entity = 'input_text.adaptive_lighting_settings_' ~ (mode | lower | replace(' ', '_')) %}
+#   {% set settings = states(settings_entity) | from_json %}
+#   {{ settings.behavior }}         # "adaptive_lighting", "scene", "script"
+#   {{ settings.manual_control }}   # true/false - controls AL manual control state
+#   {{ settings.led_color }}        # 0-255 hue value for LED feedback
+#   {{ settings.al_config }}        # Dict to pass to adaptive_lighting.change_switch_settings
 #
-# To access mode settings in templates:
+# To add custom modes:
-#   {% set settings = states('input_text.adaptive_lighting_settings_reading') | from_json %}
+#   See ADDING_MODES.md for complete tutorial
-#   {{ settings.min_brightness }}

packages/adaptive_lighting_living_room_template.yaml

@@ -1,122 +0,0 @@
-# packages/adaptive_lighting_living_room_template.yaml
-#
-# Adaptive Lighting Mode System - Living Room Template
-#
-# CUSTOMIZATION INSTRUCTIONS:
-# 1. Copy this file and rename for your room
-# 2. Search and replace "living_room" with your room name
-# 3. Update entity IDs to match your devices
-# 4. Adjust modes as desired
-# 5. Place in config/packages/ directory
-#
-# Reference: ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md lines 1512-1587
-
-# =============================================================================
-# INPUT HELPERS
-# =============================================================================
-
-input_select:
-  living_room_lighting_mode:
-    name: "Living Room Lighting Mode"
-    options:
-      - "Adaptive"
-      - "Theater"
-      - "Party"
-      - "Reading"
-    initial: "Adaptive"
-    icon: mdi:lightbulb-multiple
-
-# =============================================================================
-# AUTOMATIONS
-# =============================================================================
-
-automation:
-  # ---------------------------------------------------------------------------
-  # Mode Application
-  # ---------------------------------------------------------------------------
-  - id: living_room_apply_lighting_mode
-    alias: "Living Room: Apply Lighting Mode Settings"
-    mode: restart
-    trigger:
-      - platform: state
-        entity_id: input_select.living_room_lighting_mode
-      - platform: homeassistant
-        event: start
-    variables:
-      mode: "{{ states('input_select.living_room_lighting_mode') }}"
-      switch_entity: "switch.adaptive_lighting_living_room"  # UPDATE THIS
-      mode_colors: "{{ states('input_text.adaptive_lighting_mode_colors') | from_json }}"
-    action:
-      - choose:
-          - conditions: "{{ mode == 'Adaptive' }}"
-            sequence:
-              - service: adaptive_lighting.set_manual_control
-                data:
-                  entity_id: "{{ switch_entity }}"
-                  manual_control: false
-              - service: adaptive_lighting.change_switch_settings
-                target:
-                  entity_id: "{{ switch_entity }}"
-                data:
-                  use_defaults: configuration
-
-          - conditions: "{{ mode == 'Theater' }}"
-            sequence:
-              - variables:
-                  settings: "{{ states('input_text.adaptive_lighting_settings_theater') | from_json }}"
-              - service: adaptive_lighting.set_manual_control
-                data:
-                  entity_id: "{{ switch_entity }}"
-                  manual_control: false
-              - service: adaptive_lighting.change_switch_settings
-                target:
-                  entity_id: "{{ switch_entity }}"
-                data: "{{ settings | combine({'use_defaults': 'current'}) }}"
-
-          - conditions: "{{ mode == 'Party' }}"
-            sequence:
-              - variables:
-                  settings: "{{ states('input_text.adaptive_lighting_settings_party') | from_json }}"
-              - service: adaptive_lighting.set_manual_control
-                data:
-                  entity_id: "{{ switch_entity }}"
-                  manual_control: false
-              - service: adaptive_lighting.change_switch_settings
-                target:
-                  entity_id: "{{ switch_entity }}"
-                data: "{{ settings | combine({'use_defaults': 'current'}) }}"
-
-          - conditions: "{{ mode == 'Reading' }}"
-            sequence:
-              - variables:
-                  settings: "{{ states('input_text.adaptive_lighting_settings_reading') | from_json }}"
-              - service: adaptive_lighting.set_manual_control
-                data:
-                  entity_id: "{{ switch_entity }}"
-                  manual_control: false
-              - service: adaptive_lighting.change_switch_settings
-                target:
-                  entity_id: "{{ switch_entity }}"
-                data: "{{ settings | combine({'use_defaults': 'current'}) }}"
-
-      - service: number.set_value
-        target:
-          entity_id: number.living_room_switch_led_color_when_on  # UPDATE THIS
-        data:
-          value: "{{ mode_colors.get(mode, 170) }}"
-
-  # ---------------------------------------------------------------------------
-  # Auto-Reset Mode to Adaptive When Lights Turn Off
-  # ---------------------------------------------------------------------------
-  - id: living_room_reset_mode_on_off
-    alias: "Living Room: Reset Mode to Adaptive When Off"
-    trigger:
-      - platform: state
-        entity_id: light.living_room_lights  # UPDATE THIS
-        to: 'off'
-    action:
-      - service: input_select.select_option
-        target:
-          entity_id: input_select.living_room_lighting_mode
-        data:
-          option: "Adaptive"

packages/adaptive_lighting_simple_template.yaml

@@ -1,38 +0,0 @@
-# packages/adaptive_lighting_simple_template.yaml
-#
-# Adaptive Lighting Mode System - Simple Template
-#
-# For rooms that only need basic Adaptive Lighting without mode switching.
-# Example: Bathrooms, closets, hallways
-#
-# CUSTOMIZATION INSTRUCTIONS:
-# 1. Copy and rename for your room
-# 2. Replace "simple_room" with your room name
-# 3. Update entity IDs
-# 4. This template has NO mode cycling (Adaptive only)
-#
-# For button actions like brightness boost, use the inovelli_button_actions blueprint
-
-# =============================================================================
-# CONFIGURATION
-# =============================================================================
-# No input_select needed - always in Adaptive mode
-
-# =============================================================================
-# AUTOMATIONS
-# =============================================================================
-
-automation:
-  # ---------------------------------------------------------------------------
-  # Ensure AL is Always Active
-  # ---------------------------------------------------------------------------
-  - id: simple_room_ensure_adaptive_lighting
-    alias: "Simple Room: Ensure Adaptive Lighting Active"
-    trigger:
-      - platform: homeassistant
-        event: start
-    action:
-      - service: adaptive_lighting.set_manual_control
-        data:
-          entity_id: switch.adaptive_lighting_simple_room  # UPDATE THIS
-          manual_control: false

scripts/validate_yaml.sh

@@ -1,36 +0,0 @@
-#!/bin/bash
-# scripts/validate_yaml.sh
-#
-# Validates YAML syntax for all Adaptive Lighting system files
-
-set -e
-
-echo "Validating Adaptive Lighting Mode System YAML files..."
-echo "========================================================"
-
-# Check if yamllint is installed
-if ! command -v yamllint &> /dev/null; then
-    echo "ERROR: yamllint not found."
-    echo "Install with: pip install yamllint"
-    echo "Or run with: nix run nixpkgs#yamllint -- <files>"
-    exit 1
-fi
-
-# Validate packages
-echo ""
-echo "Validating packages..."
-for file in packages/*.yaml; do
-    echo "  - $file"
-    yamllint -d '{extends: default, rules: {line-length: {max: 120}}}' "$file"
-done
-
-# Validate blueprints
-echo ""
-echo "Validating blueprints..."
-for file in blueprints/automation/*.yaml; do
-    echo "  - $file"
-    yamllint -d '{extends: default, rules: {line-length: {max: 120}}}' "$file"
-done
-
-echo ""
-echo "✓ All YAML files are valid!"