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

CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to the Adaptive Lighting Mode System will be documented in
+this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [1.0.0] - 2025-12-20
+
+### Added
+
+**Blueprints**:
+- `inovelli_mode_cycling.yaml` - Config button cycles through lighting modes
+  with LED feedback
+- `inovelli_button_actions.yaml` - Multi-tap brightness controls with
+  auto-reset
+- `presence_mode_reset.yaml` - Auto-reset modes and manual control when room
+  empty
+
+**Package Templates**:
+- `adaptive_lighting_global.yaml` - Shared mode definitions and color mappings
+- `adaptive_lighting_bedroom_template.yaml` - Complete bedroom example with 5
+  modes
+- `adaptive_lighting_living_room_template.yaml` - Living room example with
+  entertainment modes
+- `adaptive_lighting_simple_template.yaml` - Minimal template for simple rooms
+
+**Documentation**:
+- `PACKAGE_SETUP_GUIDE.md` - Setup instructions and version control guide
+- `ROOM_CONFIGURATION_GUIDE.md` - Room-by-room configuration examples
+- `HARDWARE_TESTING_CHECKLIST.md` - Comprehensive testing checklist
+- Updated `README.md` with system overview and quick start
+
+**Features**:
+- Room-specific mode definitions (Adaptive, Reading, Theater, Sleep, etc.)
+- Visual LED feedback using ROYGBIV color scheme
+- Weekend mode with automatic sunrise/sunset adjustments
+- Multi-tap button actions (boost, max, night light)
+- Presence-based auto-reset
+- Version-controlled package-based configuration
+
+### Technical Details
+
+- Zigbee2MQTT integration for Inovelli Blue VZM31-SN switches
+- Home Assistant Adaptive Lighting integration required
+- Package-based architecture for easy version control
+- Template-driven room setup for scalability
+
+### Known Limitations
+
+- Zigbee2MQTT only (Z-Wave JS requires different MQTT topics)
+- Settings from `adaptive_lighting.change_switch_settings` reset on HA restart
+- Requires manual Inovelli switch configuration (Smart Bulb Mode, buttonDelay)

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
-- **Documentation**: README.md provides detailed usage examples and configuration guidance
-- Each blueprint is self-contained with embedded metadata (name, description, domain, inputs)
+- **3 core blueprints** for Adaptive Lighting mode system (mode application + 2 weekend mode blueprints)
+- **3 optional blueprints** for Inovelli switch integration and presence-based automation
+- **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`)
-- **Purpose**: Trigger different actions based on rapid entity state changes (single, double, triple, quad press)
-- **Key features**: 
-  - Configurable time window for press detection
-  - Immediate vs delayed single-press modes
-  - Support for complex action sequences with conditions
-- **Architecture patterns**:
-  - Uses Home Assistant blueprint format with input selectors
-  - Implements state machine logic with press counting
-  - Uses `mode: restart` to handle overlapping triggers
-  - Template-based conditional logic for press count evaluation
+### User Workflow
+- **Zero YAML editing** for room setup
+- Create helpers via Settings → Helpers (dropdowns, toggles, text inputs)
+- Import blueprints via Settings → Blueprints
+- Create automations from blueprints via UI
+- Add custom modes by creating helpers following naming convention
+
+## Core Blueprints
+
+### Apply Lighting Mode Blueprint (`apply_lighting_mode.yaml`)
+**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
-1. Create new `.yaml` file in repository root
-2. Follow Home Assistant blueprint format:
-   - `blueprint:` section with metadata
-   - `input:` section with user-configurable parameters
-   - `trigger:` and `action:` sections for automation logic
-3. Update README.md with new blueprint documentation
-4. Test blueprint by importing into Home Assistant development environment
+### Adding New Modes
+
+**Two methods**:
+
+1. **UI-created modes** (recommended):
+   - Create input_text helper via Settings → Helpers
+   - Follow naming convention: `input_text.adaptive_lighting_settings_{{mode}}`
+   - 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
-- Use `mode: restart` or `mode: single` appropriately based on use case
-- Implement proper variable scoping within actions
-- Include detailed documentation with usage examples
+- Include comprehensive documentation in blueprint metadata
 
-### Testing
-- 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
+### Home Assistant Blueprint Format
 
-### Import URLs
-- Repository uses custom Git hosting at `git.johnogle.info`
-- Import URL pattern: `https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/{blueprint_name}.yaml`
+Blueprints follow this structure:
+```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
-├── multi_press_action.yaml     # Multi-press detection blueprint
-└── CLAUDE.md                   # This file
+├── blueprints/
+│   └── automation/
+│       ├── 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/)

HARDWARE_TESTING_CHECKLIST.md

@@ -0,0 +1,110 @@
+# Hardware Testing Checklist
+
+## Prerequisites
+
+- [ ] Inovelli Blue Dimmer VZM31-SN paired with Zigbee2MQTT
+- [ ] Switch in Smart Bulb Mode (select.xxx_smart_bulb_mode = "Smart Bulb
+  Mode")
+- [ ] buttonDelay set to 500ms or 700ms (select.xxx_button_delay)
+- [ ] Smart bulbs powered and responsive
+- [ ] Adaptive Lighting integration installed and configured
+- [ ] All packages and blueprints loaded
+
+## Switch Configuration Tests
+
+- [ ] Smart Bulb Mode enabled: Load always powered
+- [ ] LED bar displays color correctly
+- [ ] LED intensity acceptable (adjust if too bright/dim)
+- [ ] Button presses detected: event.xxx_action updates
+- [ ] Single tap: Shows "up_single" or "down_single"
+- [ ] Double tap: Shows "up_double" or "down_double" reliably
+- [ ] Triple tap: Shows "up_triple" or "down_triple" reliably
+- [ ] Config button: Shows "config_single"
+
+## Mode Cycling Tests
+
+- [ ] Config button press triggers automation
+- [ ] Mode cycles through all available modes
+- [ ] Mode cycles back to first after last mode
+- [ ] input_select updates in UI
+- [ ] LED color changes to match mode
+- [ ] LED flash pulse visible (3 seconds)
+- [ ] Colors distinguishable for each mode
+- [ ] Cycle works from any starting mode
+
+## Mode Application Tests
+
+For each mode:
+- [ ] Adaptive: AL settings reset to configuration defaults
+- [ ] Reading: Brightness increases, color cools
+- [ ] Theater: Brightness decreases, color warms
+- [ ] Sleep: Very dim, red/amber color
+- [ ] Manual Override: AL paused, manual control enabled
+
+## Button Action Tests
+
+- [ ] Double tap up: Brightness boosts +50%
+- [ ] Double tap up: Color temperature increases +1000K
+- [ ] Double tap down: Returns to AL control immediately
+- [ ] Triple tap up: Sets 100% brightness, 4000K (neutral)
+- [ ] Triple tap down: Sets 5% brightness, warm red
+- [ ] Auto-reset: Returns to AL after configured timeout
+- [ ] Auto-reset: Works after boost action
+- [ ] Auto-reset: Works after max brightness
+- [ ] Auto-reset: Works after night light
+
+## Weekend Mode Tests (if configured)
+
+- [ ] Enables automatically Friday 10pm
+- [ ] Disables automatically Sunday 10pm
+- [ ] Sunrise time shifts when enabled
+- [ ] Max brightness reduces when enabled
+- [ ] Settings restore when disabled
+- [ ] Triple-tap toggle works (if configured)
+- [ ] LED flash confirms toggle
+
+## Presence Integration Tests (if configured)
+
+- [ ] Presence sensor triggers correctly
+- [ ] Lights turn on when occupied
+- [ ] Lights stay on while occupied
+- [ ] Manual control resets after room empty
+- [ ] Mode resets after room empty (if configured)
+- [ ] Delay timing is appropriate
+- [ ] Works with multiple sensors (OR logic)
+
+## Edge Cases and Failure Modes
+
+- [ ] Rapid button presses don't cause errors
+- [ ] Mode change while lights off doesn't error
+- [ ] Switching modes rapidly doesn't break AL
+- [ ] Zigbee network congestion doesn't cause issues
+- [ ] Home Assistant restart preserves mode
+- [ ] AL switch off doesn't break mode system
+- [ ] Invalid mode name doesn't crash automation
+- [ ] Missing entity gracefully fails
+
+## Performance Tests
+
+- [ ] Mode change response < 1 second
+- [ ] LED update response < 1 second
+- [ ] Button action response < 1 second
+- [ ] AL adaptation smooth (no flicker)
+- [ ] No automation trace errors
+- [ ] No excessive log warnings
+
+## Multi-Room Tests
+
+- [ ] Multiple rooms work independently
+- [ ] Mode cycling doesn't affect other rooms
+- [ ] LED colors consistent across rooms
+- [ ] Performance acceptable with many rooms
+- [ ] Global package shared correctly
+
+## Documentation Accuracy
+
+- [ ] All entity IDs in examples are correct format
+- [ ] Zigbee2MQTT topics match actual topics
+- [ ] Service calls work as documented
+- [ ] Examples produce expected behavior
+- [ ] Troubleshooting guide solves real issues

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

@@ -0,0 +1,293 @@
+# Package Setup Guide
+
+## Overview
+
+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.
+
+## 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 files instead of one giant `configuration.yaml`. Each package file can contain automations, helpers, scripts, and other entities related to a specific feature.
+
+**Benefits**:
+- Organize configuration by feature
+- Version control specific areas independently
+- 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
+- Adaptive Lighting integration installed via HACS
+- Git installed (optional, for version control)
+
+## Installation Steps
+
+### Step 1: Import Blueprints
+
+**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/
+```
+
+**2.2 Create the packages directory**
+
+SSH into your Home Assistant instance or use File Editor add-on:
+
+```bash
+cd /config
+mkdir packages
+```
+
+**2.3 Restart Home Assistant**
+
+Settings → System → Restart Home Assistant
+
+### Step 3: Install Global Package
+
+**3.1 Copy the global package**
+
+Download or copy `packages/adaptive_lighting_global.yaml` from this repository to your `/config/packages/` directory.
+
+**3.2 Reload YAML configuration**
+
+Developer Tools → YAML → Reload all YAML configuration
+
+**3.3 Verify mode entities exist**
+
+Developer Tools → States
+
+Search for `adaptive_lighting_settings` - you should see 8 entities:
+- `input_text.adaptive_lighting_settings_adaptive`
+- `input_text.adaptive_lighting_settings_relaxing`
+- `input_text.adaptive_lighting_settings_sleep`
+- `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 4: Configure Your First Room
+
+**This is done entirely via the UI** - no YAML editing required!
+
+See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for complete UI-driven room setup instructions.
+
+Quick summary:
+1. Create mode selector dropdown via Settings → Helpers
+2. Create automation from "Apply Lighting Mode Settings" blueprint
+3. Test mode switching via UI
+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
+  }
+}
+```
+
+**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
+
+**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
+
+### Editing Mode Settings
+
+To customize a mode, edit `packages/adaptive_lighting_global.yaml` and modify the `initial` value:
+
+**Example: Make "Relaxing" mode dimmer**
+
+```yaml
+adaptive_lighting_settings_relaxing:
+  name: "AL Settings: Relaxing"
+  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}}'
+```
+
+After editing, reload YAML configuration (Developer Tools → YAML → Reload all YAML configuration).
+
+### Adding Custom Modes
+
+See [ADDING_MODES.md](ADDING_MODES.md) for complete tutorial on adding custom modes.
+
+**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
+
+Both methods work identically with the convention-based blueprint system.
+
+## Version Control Setup (Optional)
+
+### Initialize git repository
+
+```bash
+cd /config
+git init
+```
+
+### Create .gitignore
+
+```bash
+cat > .gitignore << 'EOF'
+# Secrets and sensitive data
+secrets.yaml
+*.db
+*.db-shm
+*.db-wal
+*.log
+
+# Generated files
+*.pyc
+__pycache__/
+.storage/
+.cloud/
+.google.token
+
+# Add-on data
+.ssh/
+.vscode/
+
+# Keep these version controlled:
+# - packages/
+# - automations.yaml (optional - UI automations are in .storage)
+# - configuration.yaml
+EOF
+```
+
+### Commit initial setup
+
+```bash
+git add packages/ configuration.yaml
+git commit -m "Initial adaptive lighting mode system setup"
+```
+
+### Add remote (optional)
+
+```bash
+git remote add origin your-git-repo-url
+git push -u origin main
+```
+
+## Troubleshooting
+
+### Packages not loading
+
+**Symptom**: Mode entities don't appear after reloading
+
+**Solutions**:
+- Check `configuration.yaml` has packages line: `packages: !include_dir_named packages/`
+- Verify packages directory exists at `/config/packages/`
+- Check YAML syntax with a validator
+- Look for errors in Settings → System → Logs
+- Try restarting Home Assistant instead of just reloading YAML
+
+### Invalid JSON in mode settings
+
+**Symptom**: Mode doesn't work or causes errors
+
+**Solutions**:
+- Verify JSON is valid using jsonlint.com
+- Check for trailing commas (not allowed in JSON)
+- Ensure all strings use double quotes, not single quotes
+- Verify `al_config` is a nested object, not at top level
+
+### Blueprints not appearing
+
+**Symptom**: Blueprints don't show up after import
+
+**Solutions**:
+- Check for import errors in Settings → System → Logs
+- Verify blueprint URLs are correct
+- Try importing again
+- Check YAML syntax of blueprint files if self-hosting
+
+### 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
+
+**This package only provides mode definitions.** To configure a room, see [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for the UI-driven workflow.
+
+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

@@ -1,5 +1,113 @@
 # Home Assistant Blueprints
 
+## Adaptive Lighting Mode System
+
+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.
+
+### Features
+
+- **Convention-based mode lookup**: Add "Bowling" mode by creating one helper - no code changes needed
+- **UI-driven room configuration**: Setup entire rooms via Home Assistant UI - zero YAML editing required
+- **Weekend mode blueprints**: Automatic schedule adjustments for weekends (delayed sunrise, extended sunset)
+- **Extensible behavior system**: Supports Adaptive Lighting, scene-based, and script-based modes
+- **Manual control support**: Any mode can pause AL with `manual_control` attribute
+- **Visual LED feedback**: LED bar color indicates current mode (optional Inovelli integration)
+- **8 essential modes**: Adaptive, Relaxing, Sleep, Theater, Party, Cooking, Dining, Cleanup
+
+### Architecture
+
+**Pure blueprint architecture** with global mode definitions:
+
+- **3 core blueprints**: Mode application + 2 weekend mode blueprints
+- **1 global package**: 8 shipped modes with nested JSON schema
+- **UI-created helpers**: Room-specific dropdowns and toggles created via Settings → Helpers
+- **UI-created automations**: No package copying or YAML editing required
+
+**Key principle**: **Convention over configuration** - modes are discovered by naming convention, not hardcoded logic.
+
+### Quick Start
+
+**Step 1: Install Adaptive Lighting integration via HACS**
+
+**Step 2: Import blueprints**
+
+Settings → Automations & Scenes → Blueprints → Import Blueprint
+
+Import URLs (see below for full list)
+
+**Step 3: Install global package**
+
+Follow [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) to install `adaptive_lighting_global.yaml`
+
+**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
+
+**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
 
 Automatically control lights based on occupancy sensors with adaptive lighting support. Perfect for any room where you want lights to turn on when someone enters and turn off when they leave.

ROOM_CONFIGURATION_GUIDE.md

@@ -0,0 +1,485 @@
+# Room Configuration Guide
+
+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**.
+
+## 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 mode control with weekend mode, optional Inovelli integration
+
+**Room Type**: Private bedroom with comprehensive lighting control
+
+### Adaptive Lighting Configuration
+
+In `configuration.yaml` (if not already done):
+
+```yaml
+adaptive_lighting:
+  - name: master_bedroom
+    lights:
+      - light.master_bedroom_ceiling
+      - light.master_bedroom_lamp_1
+      - light.master_bedroom_lamp_2
+    interval: 90
+    transition: 45
+    take_over_control: true
+    autoreset_control_seconds: 3600  # 1 hour gentle reset
+```
+
+Restart Home Assistant after editing configuration.yaml.
+
+### UI Configuration Steps
+
+**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
+
+**Step 2: Create Mode Application Automation**
+- Blueprint: Apply Lighting Mode Settings
+- Mode Input Select: `input_select.master_bedroom_lighting_mode`
+- AL Switch: `switch.adaptive_lighting_master_bedroom`
+- LED Entity: `number.master_bedroom_switch_led_color_when_on` (if Inovelli)
+- Name: "Master Bedroom: Apply Lighting Mode"
+
+**Step 3: Create Weekend Mode Helpers and Automations**
+- Toggle: `input_boolean.master_bedroom_weekend_mode`
+- Schedule automation: Toggle at 22:00
+- Apply settings automation:
+  - Sunrise: 10:00 (sleep in on weekends)
+  - Sunset: 01:00 (stay up later)
+  - Max brightness: 60%
+
+### Testing
+
+- [ ] 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
+
+## Example 2: Living Room
+
+**Goal**: Entertainment modes (Theater, Party), standard adaptive lighting
+
+**Room Type**: Common area with social and entertainment use
+
+### Adaptive Lighting Configuration
+
+```yaml
+adaptive_lighting:
+  - name: living_room
+    lights:
+      - light.living_room_ceiling
+      - light.living_room_lamp_1
+      - light.living_room_lamp_2
+    interval: 90
+    transition: 30
+```
+
+### 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
+
+```yaml
+adaptive_lighting:
+  - name: bathroom
+    lights:
+      - light.bathroom_ceiling
+      - light.bathroom_vanity
+    interval: 60
+    transition: 20
+```
+
+### UI Configuration Steps
+
+**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
+
+**Step 2: Create Mode Application Automation**
+- Blueprint: Apply Lighting Mode Settings
+- Mode Input Select: `input_select.bathroom_lighting_mode`
+- 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
+
+**Step 3**: Test
+- Switch to Reading mode via UI
+- Verify it works without any blueprint changes!
+
+### Change Weekend Mode Times
+
+**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_button_actions.yaml

@@ -0,0 +1,163 @@
+---
+# blueprints/automation/inovelli_button_actions.yaml
+#
+# Inovelli Button Actions for Adaptive Lighting
+#
+# Implements multi-tap actions:
+# - Double tap up: Brightness boost (+50% from current AL setting)
+# - Double tap down: Return to Adaptive Lighting control
+# - Triple tap up: Maximum brightness (100%, neutral white)
+# - Triple tap down: Night light mode (5%, warm red)
+#
+# Features:
+# - Auto-reset after configurable timeout
+# - Reads current AL settings for relative boost
+# - Works with any Inovelli Blue Dimmer via Zigbee2MQTT
+#
+# Requirements:
+# - Inovelli Blue Dimmer (VZM31-SN) with buttonDelay >= 500ms
+# - Adaptive Lighting switch for the room
+# - Light entities to control
+#
+# Reference: ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md lines 308-421
+
+blueprint:
+  name: Inovelli Button Actions for Adaptive Lighting
+  description: Multi-tap brightness controls with adaptive lighting integration
+  domain: automation
+  input:
+    switch_action_event:
+      name: Switch Action Event
+      description: Event entity that reports button presses (event.xxx_action)
+      selector:
+        entity:
+          domain: event
+
+    adaptive_lighting_switch:
+      name: Adaptive Lighting Switch
+      description: The AL switch entity for this room
+      selector:
+        entity:
+          domain: switch
+          integration: adaptive_lighting
+
+    target_lights:
+      name: Target Lights
+      description: Light entities to control
+      selector:
+        target:
+          entity:
+            domain: light
+
+    auto_reset_minutes:
+      name: Auto-Reset Timeout (minutes)
+      description: Minutes before returning to AL after manual boost
+      default: 10
+      selector:
+        number:
+          min: 0
+          max: 120
+          step: 5
+          unit_of_measurement: minutes
+
+mode: restart
+max_exceeded: silent
+
+trigger:
+  - platform: state
+    entity_id: !input switch_action_event
+
+condition:
+  - condition: template
+    value_template: >-
+      {{
+        state_attr(trigger.entity_id, 'event_type') in
+        ['up_double', 'down_double', 'up_triple', 'down_triple']
+      }}
+
+action:
+  - variables:
+      action: "{{ state_attr(trigger.entity_id, 'event_type') }}"
+      al_switch: !input adaptive_lighting_switch
+      lights: !input target_lights
+      reset_minutes: !input auto_reset_minutes
+
+  - choose:
+      # ========================================================================
+      # DOUBLE TAP UP - Brightness Boost
+      # ========================================================================
+      - conditions: "{{ action == 'up_double' }}"
+        sequence:
+          - variables:
+              current_brightness: >-
+                {{ state_attr(al_switch, 'brightness_pct') | float(50) }}
+              boosted_brightness: "{{ [current_brightness + 50, 100] | min }}"
+              current_color_temp: >-
+                {{ state_attr(al_switch, 'color_temp_kelvin') | int(4000) }}
+              boosted_color_temp: >-
+                {{ [current_color_temp + 1000, 5500] | min }}
+
+          - service: light.turn_on
+            target: "{{ lights }}"
+            data:
+              brightness_pct: "{{ boosted_brightness }}"
+              color_temp_kelvin: "{{ boosted_color_temp }}"
+              transition: 1
+
+          # Auto-reset after timeout
+          - delay:
+              minutes: "{{ reset_minutes }}"
+          - service: adaptive_lighting.set_manual_control
+            data:
+              entity_id: "{{ al_switch }}"
+              manual_control: false
+
+      # ========================================================================
+      # DOUBLE TAP DOWN - Return to AL
+      # ========================================================================
+      - conditions: "{{ action == 'down_double' }}"
+        sequence:
+          - service: adaptive_lighting.set_manual_control
+            data:
+              entity_id: "{{ al_switch }}"
+              manual_control: false
+
+      # ========================================================================
+      # TRIPLE TAP UP - Max Brightness (Neutral White)
+      # ========================================================================
+      - conditions: "{{ action == 'up_triple' }}"
+        sequence:
+          - service: light.turn_on
+            target: "{{ lights }}"
+            data:
+              brightness_pct: 100
+              color_temp_kelvin: 4000
+              transition: 0.5
+
+          # Auto-reset after timeout
+          - delay:
+              minutes: "{{ reset_minutes }}"
+          - service: adaptive_lighting.set_manual_control
+            data:
+              entity_id: "{{ al_switch }}"
+              manual_control: false
+
+      # ========================================================================
+      # TRIPLE TAP DOWN - Night Light
+      # ========================================================================
+      - conditions: "{{ action == 'down_triple' }}"
+        sequence:
+          - service: light.turn_on
+            target: "{{ lights }}"
+            data:
+              brightness_pct: 5
+              rgb_color: [255, 50, 0]
+              transition: 1
+
+          # Auto-reset after timeout
+          - delay:
+              minutes: "{{ reset_minutes }}"
+          - service: adaptive_lighting.set_manual_control
+            data:
+              entity_id: "{{ al_switch }}"
+              manual_control: false

blueprints/automation/inovelli_mode_cycling.yaml

@@ -0,0 +1,98 @@
+# blueprints/automation/inovelli_mode_cycling.yaml
+#
+# Inovelli Config Button Mode Cycling
+#
+# Cycles through lighting modes when the config button is pressed on an
+# Inovelli Blue Dimmer Switch (VZM31-SN) via Zigbee2MQTT.
+#
+# Features:
+# - Cycles through available modes in input_select
+# - Updates LED color to match new mode (ROYGBIV scheme)
+# - Flashes LED to confirm mode change (0.5-second pulse)
+#
+# Requirements:
+# - Inovelli Blue Dimmer (VZM31-SN) paired with Zigbee2MQTT
+# - input_select helper with available modes
+# - 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
+
+blueprint:
+  name: Inovelli Config Button Mode Cycling
+  description: Press config button to cycle through lighting modes with LED feedback
+  domain: automation
+  input:
+    switch_action_event:
+      name: Switch Action Event
+      description: The event entity that reports button presses (event.xxx_action)
+      selector:
+        entity:
+          domain: event
+
+    mode_input_select:
+      name: Mode Input Select
+      description: The input_select helper that tracks current lighting mode
+      selector:
+        entity:
+          domain: input_select
+
+    led_color_entity:
+      name: LED Color Entity
+      description: The number entity for LED color when on (number.xxx_led_color_when_on)
+      selector:
+        entity:
+          domain: number
+
+    zigbee2mqtt_device_name:
+      name: Zigbee2MQTT Device Name
+      description: The device name in Zigbee2MQTT (for LED flash effect via MQTT). Example "bedroom_switch"
+      selector:
+        text:
+
+mode: single
+max_exceeded: silent
+
+trigger:
+  - platform: state
+    entity_id: !input switch_action_event
+
+condition:
+  - condition: state
+    entity_id: !input switch_action_event
+    attribute: event_type
+    state: "config_single"
+
+action:
+  - variables:
+      mode_select: !input mode_input_select
+      zigbee2mqtt_device_name: !input zigbee2mqtt_device_name
+      current_mode: "{{ states(mode_select) }}"
+      available_modes: "{{ state_attr(mode_select, 'options') }}"
+      current_index: "{{ available_modes.index(current_mode) }}"
+      next_index: "{{ (current_index + 1) % (available_modes | length) }}"
+      next_mode: "{{ available_modes[next_index] }}"
+      next_mode_settings_entity: "input_text.adaptive_lighting_settings_{{ next_mode | lower | replace(' ', '_') }}"
+      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
+    target:
+      entity_id: !input mode_input_select
+    data:
+      option: "{{ next_mode }}"
+
+  # Update LED color
+  - service: number.set_value
+    target:
+      entity_id: !input led_color_entity
+    data:
+      value: "{{ next_color }}"
+
+  # Flash LED to confirm mode change (0.5-second pulse)
+  - service: mqtt.publish
+    data:
+      topic: "zigbee2mqtt/{{ zigbee2mqtt_device_name }}/set"
+      payload: >-
+        {"led_effect": {"effect": "pulse", "color": {{ next_color }}, "level": 100, "duration": 0.5}}

blueprints/automation/presence_mode_reset.yaml

@@ -0,0 +1,116 @@
+---
+# blueprints/automation/presence_mode_reset.yaml
+#
+# Presence-Based Mode and Manual Control Reset
+#
+# Automatically resets lighting mode and clears manual control when room
+# becomes unoccupied for a configurable duration.
+#
+# Use Cases:
+# - Reset Theater mode to Adaptive when leaving living room
+# - Clear manual brightness boosts when bedroom becomes empty
+# - Return bathroom to normal AL after presence ends
+#
+# Requirements:
+# - Binary sensor(s) for occupancy/presence detection
+# - Adaptive Lighting switch (optional - for manual control reset)
+# - Mode input_select (optional - for mode reset)
+#
+# Reference: ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md lines 437-451,
+#            709-719
+
+blueprint:
+  name: Presence-Based Mode and Manual Control Reset
+  description: >-
+    Reset lighting modes and AL manual control when room becomes empty
+  domain: automation
+  input:
+    occupancy_sensors:
+      name: Occupancy Sensors
+      description: Binary sensor(s) that detect room occupancy
+      selector:
+        entity:
+          domain: binary_sensor
+          device_class: occupancy
+          multiple: true
+
+    empty_delay:
+      name: Empty Delay
+      description: How long room must be empty before reset
+      default: 5
+      selector:
+        number:
+          min: 0
+          max: 60
+          step: 1
+          unit_of_measurement: minutes
+
+    adaptive_lighting_switch:
+      name: Adaptive Lighting Switch (Optional)
+      description: AL switch to reset manual control. Leave empty to skip.
+      default: {}
+      selector:
+        entity:
+          domain: switch
+          integration: adaptive_lighting
+
+    mode_input_select:
+      name: Mode Input Select (Optional)
+      description: Mode selector to reset to Adaptive. Leave empty to skip.
+      default: {}
+      selector:
+        entity:
+          domain: input_select
+
+    default_mode:
+      name: Default Mode
+      description: Mode to reset to when room becomes empty
+      default: "Adaptive"
+      selector:
+        text:
+
+mode: restart
+
+trigger:
+  - platform: state
+    entity_id: !input occupancy_sensors
+    to: 'off'
+    for:
+      minutes: !input empty_delay
+
+action:
+  - variables:
+      occupancy_sensors: !input occupancy_sensors
+      al_switch: !input adaptive_lighting_switch
+      mode_select: !input mode_input_select
+      default_mode: !input default_mode
+
+  # Ensure ALL sensors are off (room is truly empty)
+  - condition: template
+    value_template: >-
+      {{
+        expand(occupancy_sensors) |
+        selectattr('state', 'eq', 'on') |
+        list | count == 0
+      }}
+
+  # Reset manual control if AL switch provided
+  - if:
+      - condition: template
+        value_template: "{{ al_switch not in [none, {}, ''] }}"
+    then:
+      - service: adaptive_lighting.set_manual_control
+        data:
+          entity_id: "{{ al_switch }}"
+          manual_control: false
+
+  # Reset mode if input_select provided
+  - if:
+      - condition: template
+        value_template: "{{ mode_select not in [none, {}, ''] }}"
+    then:
+      - service: input_select.select_option
+        target:
+          entity_id: "{{ mode_select }}"
+        data:
+          option: "{{ default_mode }}"

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

examples/test_room_config.yaml

@@ -0,0 +1,66 @@
+---
+# examples/test_room_config.yaml
+#
+# Test configuration for validating the Adaptive Lighting Mode System
+# without real Inovelli hardware or Adaptive Lighting integration.
+#
+# This uses template sensors and manual input helpers to simulate the system.
+
+input_select:
+  test_room_lighting_mode:
+    name: "Test Room Lighting Mode"
+    options:
+      - "Adaptive"
+      - "Reading"
+      - "Sleep"
+    initial: "Adaptive"
+
+sensor:
+  - platform: template
+    sensors:
+      test_switch_action:
+        friendly_name: "Test Switch Action"
+        value_template: "{{ states('input_text.test_switch_action_sim') }}"
+
+input_text:
+  test_switch_action_sim:
+    name: "Simulate Switch Action"
+    initial: "none"
+
+input_number:
+  test_led_color:
+    name: "Test LED Color"
+    min: 0
+    max: 255
+    step: 1
+    initial: 170
+
+# Automation to test mode cycling logic
+automation:
+  - id: test_mode_cycling
+    alias: "Test: Mode Cycling"
+    trigger:
+      - platform: state
+        entity_id: input_text.test_switch_action_sim
+        to: "config_single"
+    variables:
+      mode_select: input_select.test_room_lighting_mode
+      current_mode: "{{ states(mode_select) }}"
+      available_modes: "{{ state_attr(mode_select, 'options') }}"
+      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_color: "{{ mode_colors.get(next_mode, 170) }}"
+    action:
+      - service: input_select.select_option
+        target:
+          entity_id: input_select.test_room_lighting_mode
+        data:
+          option: "{{ next_mode }}"
+      - service: input_number.set_value
+        target:
+          entity_id: input_number.test_led_color
+        data:
+          value: "{{ next_color }}"

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_global.yaml

@@ -0,0 +1,84 @@
+# packages/adaptive_lighting_global.yaml
+#
+# Global constants for Adaptive Lighting Mode System
+# This file is shared across all rooms and should be version controlled.
+#
+# To use: Place in config/packages/ directory
+# Enable packages in configuration.yaml:
+#   homeassistant:
+#     packages: !include_dir_named packages/
+
+# =============================================================================
+# MODE SETTINGS DEFINITIONS
+# =============================================================================
+# Each mode has its own input_text helper with nested JSON schema
+# Schema: {"behavior": "adaptive_lighting"|"scene"|"script",
+#          "manual_control": true|false,
+#          "led_color": 0-255,
+#          "al_config": {AL settings dict}}
+# Room automations use convention-based lookup to apply settings
+# =============================================================================
+
+input_text:
+  # Adaptive mode - uses default AL configuration
+  adaptive_lighting_settings_adaptive:
+    name: "AL Settings: Adaptive"
+    max: 255
+    initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":170,"al_config":{"use_defaults":"configuration"}}'
+
+  # Relaxing mode - dim, warm white
+  adaptive_lighting_settings_relaxing:
+    name: "AL Settings: Relaxing"
+    max: 255
+    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: '{"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: '{"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: '{"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}}'
+
+  # Cooking mode - bright, cool task lighting
+  adaptive_lighting_settings_cooking:
+    name: "AL Settings: Cooking"
+    max: 255
+    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: '{"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: '{"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}}'
+
+# =============================================================================
+# USAGE NOTES
+# =============================================================================
+# To access mode settings in blueprints/automations:
+#   {% set mode = states('input_select.room_lighting_mode') %}
+#   {% 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 add custom modes:
+#   See ADDING_MODES.md for complete tutorial