From 14fadbe44e3062cc51660e30e4c7baa6b6f76c77 Mon Sep 17 00:00:00 2001
From: John Ogle <john@ogle.fyi>
Date: Sun, 21 Dec 2025 17:44:47 -0800
Subject: [PATCH] Add custom mode tutorial and update docs for pure blueprint
 architecture

Add ADDING_MODES.md tutorial covering:
- UI-created modes (recommended) and package-defined modes
- Complete schema reference with nested al_config
- Behavior types (adaptive_lighting, scene, script)
- Manual control support and advanced examples

Update all documentation to reflect:
- Zero YAML editing for room setup (UI-driven workflow)
- Convention-based mode lookup pattern
- Pure blueprint architecture (3 core + 3 optional blueprints)
- Extensibility via helpers instead of template copying
---
 ADDING_MODES.md             | 453 +++++++++++++++++++++++++++
 CLAUDE.md                   | 451 ++++++++++++++++++++++++---
 PACKAGE_SETUP_GUIDE.md      | 253 +++++++++------
 README.md                   | 130 +++++---
 ROOM_CONFIGURATION_GUIDE.md | 605 ++++++++++++++++++++++++++----------
 5 files changed, 1553 insertions(+), 339 deletions(-)
 create mode 100644 ADDING_MODES.md

diff --git a/ADDING_MODES.md b/ADDING_MODES.md
new file mode 100644
index 0000000..28bb451
--- /dev/null
+++ b/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
diff --git a/CLAUDE.md b/CLAUDE.md
index e1bb23f..a51762d 100644
--- a/CLAUDE.md
+++ b/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
\ No newline at end of file
+- `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/)
diff --git a/PACKAGE_SETUP_GUIDE.md b/PACKAGE_SETUP_GUIDE.md
index 822e291..3858e9d 100644
--- a/PACKAGE_SETUP_GUIDE.md
+++ b/PACKAGE_SETUP_GUIDE.md
@@ -2,41 +2,84 @@
 
 ## Overview
 
-This guide explains how to set up Home Assistant packages for the Adaptive
-Lighting Mode System and configure version control.
+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
-or room.
+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 room or feature
+- Organize configuration by feature
 - Version control specific areas independently
-- Easier to share and reuse configurations
+- Share and reuse configurations
 - Keep `configuration.yaml` clean and minimal
 
 ## Prerequisites
 
 - Home Assistant installed and running
 - SSH or file editor access to your HA configuration directory
-- Git installed (optional, for version control)
 - Adaptive Lighting integration installed via HACS
+- Git installed (optional, for version control)
 
-## Step 1: Enable Packages in Home Assistant
+## Installation Steps
 
-**1.1 Edit your `configuration.yaml`**
+### Step 1: Import Blueprints
 
-Add this line to the top of your `configuration.yaml`:
+**1.1 Navigate to blueprints**
+
+Settings → Automations & Scenes → Blueprints → Import Blueprint
+
+**1.2 Import the three mode system blueprints**
+
+Import these URLs one at a time:
+
+```
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/apply_lighting_mode.yaml
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/weekend_mode_schedule.yaml
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/weekend_mode_apply_settings.yaml
+```
+
+**Optional blueprints** (for Inovelli switches and presence-based automation):
+
+```
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/inovelli_mode_cycling.yaml
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/inovelli_button_actions.yaml
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/presence_mode_reset.yaml
+```
+
+**1.3 Verify blueprints imported**
+
+Settings → Automations & Scenes → Blueprints
+
+You should see:
+- Apply Lighting Mode Settings
+- Weekend Mode Schedule
+- Weekend Mode Apply Settings
+- (Optional) Inovelli Mode Cycling, Inovelli Button Actions, Presence Mode Reset
+
+### Step 2: Enable Packages in Home Assistant
+
+**2.1 Edit your `configuration.yaml`**
+
+Add this line to enable packages:
 
 ```yaml
 homeassistant:
   packages: !include_dir_named packages/
 ```
 
-**1.2 Create the packages directory**
+**2.2 Create the packages directory**
 
 SSH into your Home Assistant instance or use File Editor add-on:
 
@@ -45,97 +88,115 @@ cd /config
 mkdir packages
 ```
 
-**1.3 Restart Home Assistant**
+**2.3 Restart Home Assistant**
 
 Settings → System → Restart Home Assistant
 
-## Step 2: Install Global Definitions
+### Step 3: Install Global Package
 
-**2.1 Copy the global package**
+**3.1 Copy the global package**
 
-Download or copy `packages/adaptive_lighting_global.yaml` from this repository
-to your `/config/packages/` directory.
+Download or copy `packages/adaptive_lighting_global.yaml` from this repository to your `/config/packages/` directory.
 
-**2.2 Reload YAML configuration**
+**3.2 Reload YAML configuration**
 
 Developer Tools → YAML → Reload all YAML configuration
 
-**2.3 Verify helpers exist**
+**3.3 Verify mode entities exist**
 
-Settings → Devices & Services → Helpers
+Developer Tools → States
 
-You should see:
-- `input_text.adaptive_lighting_mode_colors`
+Search for `adaptive_lighting_settings` - you should see 8 entities:
 - `input_text.adaptive_lighting_settings_adaptive`
-- `input_text.adaptive_lighting_settings_reading`
 - `input_text.adaptive_lighting_settings_relaxing`
 - `input_text.adaptive_lighting_settings_sleep`
-- And several more mode settings helpers
+- `input_text.adaptive_lighting_settings_theater`
+- `input_text.adaptive_lighting_settings_party`
+- `input_text.adaptive_lighting_settings_cooking`
+- `input_text.adaptive_lighting_settings_dining`
+- `input_text.adaptive_lighting_settings_cleanup`
 
-## Step 3: Import Blueprints
+### Step 4: Configure Your First Room
 
-**3.1 Import via UI**
+**This is done entirely via the UI** - no YAML editing required!
 
-Settings → Automations & Scenes → Blueprints → Import Blueprint
+See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for complete UI-driven room setup instructions.
 
-Import these URLs:
-```
-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
+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
+  }
+}
 ```
 
-**3.2 Verify blueprints imported**
+**Top-level fields**:
+- `behavior`: "adaptive_lighting", "scene", or "script" - determines how the mode behaves
+- `manual_control`: `true` or `false` - if `true`, pauses Adaptive Lighting for this mode
+- `led_color`: 0-255 hue value for LED feedback on Inovelli switches
+- `al_config`: Nested object with Adaptive Lighting settings
 
-Settings → Automations & Scenes → Blueprints
+**AL config fields** (only used for "adaptive_lighting" behavior):
+- `use_defaults`: "configuration" or "current"
+- `min_brightness`, `max_brightness`: 1-100
+- `min_color_temp`, `max_color_temp`: Kelvin values (2000-6500)
+- `sleep_rgb_color`: RGB array like `[255, 50, 0]`
+- `transition`: Seconds
 
-You should see all three blueprints listed.
+### Editing Mode Settings
 
-## Step 4: Configure Your First Room
+To customize a mode, edit `packages/adaptive_lighting_global.yaml` and modify the `initial` value:
 
-**4.1 Choose a template**
+**Example: Make "Relaxing" mode dimmer**
 
-Select the appropriate template for your room type:
-- Bedroom: `packages/adaptive_lighting_bedroom_template.yaml`
-- Living room: `packages/adaptive_lighting_living_room_template.yaml`
-- Simple (bathroom, closet): `packages/adaptive_lighting_simple_template.yaml`
-
-**4.2 Copy and customize**
-
-```bash
-cd /config/packages
-cp adaptive_lighting_bedroom_template.yaml adaptive_lighting_master_bedroom.yaml
+```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}}'
 ```
 
-Edit the file and update:
-- Replace "bedroom" with "master_bedroom" throughout
-- Update entity IDs (search for # UPDATE THIS comments)
-- Adjust available modes if desired
-- Customize mode settings
+After editing, reload YAML configuration (Developer Tools → YAML → Reload all YAML configuration).
 
-**4.3 Reload configuration**
+### Adding Custom Modes
 
-Developer Tools → YAML → Reload all YAML configuration
+See [ADDING_MODES.md](ADDING_MODES.md) for complete tutorial on adding custom modes.
 
-**4.4 Create blueprint automations**
+**Two methods**:
+1. **UI-created modes** (recommended): Create input_text helper via Settings → Helpers - no restart required
+2. **Package-defined modes**: Add to `adaptive_lighting_global.yaml` - version controlled
 
-Settings → Automations & Scenes → Create Automation → Use Blueprint
+Both methods work identically with the convention-based blueprint system.
 
-Create automations for:
-1. Inovelli Mode Cycling (config button)
-2. Inovelli Button Actions (multi-tap)
-3. Presence Mode Reset (if you have occupancy sensors)
+## Version Control Setup (Optional)
 
-## Step 5: Version Control Setup (Optional)
-
-**5.1 Initialize git repository**
+### Initialize git repository
 
 ```bash
 cd /config
 git init
 ```
 
-**5.2 Create .gitignore**
+### Create .gitignore
 
 ```bash
 cat > .gitignore << 'EOF'
@@ -159,20 +220,19 @@ __pycache__/
 
 # Keep these version controlled:
 # - packages/
-# - automations.yaml
+# - automations.yaml (optional - UI automations are in .storage)
 # - configuration.yaml
-# - blueprints/
 EOF
 ```
 
-**5.3 Commit initial setup**
+### Commit initial setup
 
 ```bash
-git add packages/ automations.yaml configuration.yaml
+git add packages/ configuration.yaml
 git commit -m "Initial adaptive lighting mode system setup"
 ```
 
-**5.4 Add remote (optional)**
+### Add remote (optional)
 
 ```bash
 git remote add origin your-git-repo-url
@@ -183,38 +243,51 @@ git push -u origin main
 
 ### Packages not loading
 
-**Symptom**: Helpers don't appear after reloading
+**Symptom**: Mode entities don't appear after reloading
 
 **Solutions**:
-- Check `configuration.yaml` has packages line
+- Check `configuration.yaml` has packages line: `packages: !include_dir_named packages/`
 - Verify packages directory exists at `/config/packages/`
-- Check YAML syntax: `yamllint /config/packages/*.yaml`
+- Check YAML syntax with a validator
 - Look for errors in Settings → System → Logs
+- Try restarting Home Assistant instead of just reloading YAML
 
-### Entity IDs don't match
+### Invalid JSON in mode settings
 
-**Symptom**: Automations fail because entities not found
+**Symptom**: Mode doesn't work or causes errors
 
 **Solutions**:
-- Go to Settings → Devices & Services → MQTT
-- Find your Inovelli switch device
-- Note the exact entity IDs (event.xxx_action,
-  number.xxx_led_color_when_on)
-- Update package file with correct entity IDs
-- Reload YAML
+- 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 working
+### Blueprints not appearing
 
-**Symptom**: Automation from blueprint doesn't trigger
+**Symptom**: Blueprints don't show up after import
 
 **Solutions**:
-- Check automation trace: Settings → Automations → [your automation] →
-  Traces
-- Verify trigger entity is correct
-- Ensure Inovelli buttonDelay is set to >= 500ms
-- Test button press in Developer Tools → States (watch event.xxx_action)
+- 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
 
-See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for detailed
-room setup examples.
+**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
diff --git a/README.md b/README.md
index 3f0cb56..946f8d3 100644
--- a/README.md
+++ b/README.md
@@ -2,70 +2,110 @@
 
 ## Adaptive Lighting Mode System
 
-A comprehensive mode-based lighting control system for Inovelli Blue Dimmer
-Switches with Adaptive Lighting integration.
+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
 
-- **Room-specific modes**: Define custom lighting modes per room (Reading,
-  Theater, Sleep, etc.)
-- **Visual LED feedback**: LED bar color indicates current mode
-- **Config button control**: Press config button to cycle through modes
-- **Multi-tap actions**: Double-tap boost, triple-tap max/night light
-- **Adaptive Lighting integration**: Dynamic brightness and color following sun
-  position
-- **Version controlled**: All configuration in git-trackable package files
+- **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
 
-### System Components
+### Architecture
 
-**Blueprints** (Reusable):
-- `inovelli_mode_cycling.yaml` - Config button cycles modes with LED feedback
-- `inovelli_button_actions.yaml` - Multi-tap brightness controls
-- `presence_mode_reset.yaml` - Auto-reset on room exit
+**Pure blueprint architecture** with global mode definitions:
 
-**Packages** (Templates):
-- `adaptive_lighting_global.yaml` - Shared mode definitions and colors
-- `adaptive_lighting_bedroom_template.yaml` - Complete bedroom example
-- `adaptive_lighting_living_room_template.yaml` - Living room example
-- `adaptive_lighting_simple_template.yaml` - Minimal single-mode room
+- **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
 
-### Setup Guide
+**Key principle**: **Convention over configuration** - modes are discovered by naming convention, not hardcoded logic.
 
-**Quick Start**:
-1. Install Adaptive Lighting integration via HACS
-2. Follow [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) to enable packages
-3. Copy templates from `packages/` directory
-4. Import blueprints via UI
-5. See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for examples
+### Quick Start
 
-**Documentation**:
-- [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) - Initial setup and version
-  control
-- [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) - Room-by-room
-  examples
-- [ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md](ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md) -
-  Complete system design
+**Step 1: Install Adaptive Lighting integration via HACS**
 
-**Files**:
-- `packages/adaptive_lighting_global.yaml` - Required for all rooms
-- `packages/adaptive_lighting_bedroom_template.yaml` - Template for bedrooms
-- `packages/adaptive_lighting_living_room_template.yaml` - Template for common
-  areas
-- `packages/adaptive_lighting_simple_template.yaml` - Template for simple rooms
-- `blueprints/automation/inovelli_mode_cycling.yaml` - Config button mode
-  cycling
-- `blueprints/automation/inovelli_button_actions.yaml` - Multi-tap actions
-- `blueprints/automation/presence_mode_reset.yaml` - Auto-reset on room exit
+**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
 
-**Blueprints**:
+**Core mode system blueprints**:
+```
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/apply_lighting_mode.yaml
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/weekend_mode_schedule.yaml
+https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/weekend_mode_apply_settings.yaml
+```
+
+**Optional Inovelli and presence blueprints**:
 ```
 https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/inovelli_mode_cycling.yaml
 https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/inovelli_button_actions.yaml
 https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/presence_mode_reset.yaml
 ```
 
+### Extensibility Example
+
+**Traditional approach** (hardcoded): Adding "Bowling" mode requires editing blueprint code, modifying choose blocks, updating all rooms.
+
+**Convention-based approach** (this system): Create ONE helper via UI:
+1. Settings → Helpers → Create Text input
+2. Name: `input_text.adaptive_lighting_settings_bowling`
+3. Value: `{"behavior":"adaptive_lighting","manual_control":false,"led_color":148,"al_config":{...}}`
+4. Add "Bowling" to your room's mode dropdown
+5. Done! No blueprint changes, works immediately in all rooms.
+
 ---
 
 ## Occupancy Controlled Lights Blueprint
diff --git a/ROOM_CONFIGURATION_GUIDE.md b/ROOM_CONFIGURATION_GUIDE.md
index 2a13dc3..ed617aa 100644
--- a/ROOM_CONFIGURATION_GUIDE.md
+++ b/ROOM_CONFIGURATION_GUIDE.md
@@ -1,200 +1,485 @@
 # Room Configuration Guide
 
-Complete examples of configuring different room types with the Adaptive
-Lighting Mode System.
+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 control with optional AL, reading/sleep modes, weekend mode
+**Goal**: Full mode control with weekend mode, optional Inovelli integration
 
-**Hardware**:
-- Inovelli Blue Dimmer: `bedroom_switch` (Zigbee2MQTT name)
-- Lights: `light.bedroom_ceiling`, `light.bedroom_lamp_1`,
-  `light.bedroom_lamp_2`
-- No presence sensor (privacy)
+**Room Type**: Private bedroom with comprehensive lighting control
+
+### Adaptive Lighting Configuration
+
+In `configuration.yaml` (if not already done):
 
-**Adaptive Lighting Configuration** (in `configuration.yaml`):
 ```yaml
 adaptive_lighting:
-  - name: bedroom
+  - name: master_bedroom
     lights:
-      - light.bedroom_ceiling
-      - light.bedroom_lamp_1
-      - light.bedroom_lamp_2
+      - 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
 ```
 
-**Package File** (`packages/adaptive_lighting_master_bedroom.yaml`):
+Restart Home Assistant after editing configuration.yaml.
 
-Copy from `adaptive_lighting_bedroom_template.yaml`, customize:
-- Modes: Adaptive, Reading, Relaxing, Sleep, Manual Override
-- Weekend mode enabled
-- Default mode: Adaptive
+### UI Configuration Steps
 
-**Blueprint Automations** (create via UI):
+**Step 1: Create Mode Selector**
+- Name: "Master Bedroom Lighting Mode"
+- Entity ID: `input_select.master_bedroom_lighting_mode`
+- Options: Adaptive, Relaxing, Sleep, Theater (for movies in bed), Party (rare, but available)
+- Initial: Adaptive
 
-1. **Config Button Mode Cycling**:
-   - Blueprint: Inovelli Mode Cycling
-   - Switch Action Event: `event.bedroom_switch_action`
-   - Mode Input Select: `input_select.bedroom_lighting_mode`
-   - LED Color Entity: `number.bedroom_switch_led_color_when_on`
-   - Zigbee2MQTT Device Name: `bedroom_switch`
+**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"
 
-2. **Button Actions**:
-   - Blueprint: Inovelli Button Actions
-   - Switch Action Event: `event.bedroom_switch_action`
-   - AL Switch: `switch.adaptive_lighting_bedroom`
-   - Target Lights: `light.bedroom_ceiling`, `light.bedroom_lamp_1`,
-     `light.bedroom_lamp_2`
-   - Auto-Reset: 30 minutes
+**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**:
-- [ ] Press config button → mode cycles through all 5 modes
-- [ ] LED changes color for each mode
-- [ ] Double-tap up → brightness boosts
-- [ ] Weekend mode enables Friday 10pm
-- [ ] Sunrise shifts to 10am on weekend
+### Testing
 
-## Example 2: Living Room (Common Area)
+- [ ] Mode selector cycles through all modes via UI
+- [ ] Lights change appropriately for each mode
+- [ ] LED changes color for each mode (if Inovelli)
+- [ ] Weekend mode enables Friday evening
+- [ ] Sunrise shifts to 10am when weekend mode active
+- [ ] Weekend mode disables Sunday evening
 
-**Goal**: Entertainment modes (Theater, Party), presence control
+## Example 2: Living Room
 
-**Hardware**:
-- Inovelli Blue Dimmer: `living_room_switch`
-- Lights: `light.living_room_ceiling`, `light.living_room_lamp_1`
-- Presence: `binary_sensor.living_room_occupancy`
+**Goal**: Entertainment modes (Theater, Party), standard adaptive lighting
 
-**Package File** (`packages/adaptive_lighting_living_room.yaml`):
+**Room Type**: Common area with social and entertainment use
 
-Copy from `adaptive_lighting_living_room_template.yaml`
-- Modes: Adaptive, Theater, Party, Reading
-- Auto-reset mode to Adaptive when lights turn off
+### Adaptive Lighting Configuration
 
-**Blueprint Automations**:
-
-1. **Config Button Mode Cycling** (same as bedroom)
-2. **Button Actions** (same as bedroom, adjust auto-reset to 15 min)
-3. **Presence Mode Reset**:
-   - Occupancy Sensors: `binary_sensor.living_room_occupancy`
-   - Empty Delay: 5 minutes
-   - AL Switch: `switch.adaptive_lighting_living_room`
-   - Mode Input Select: `input_select.living_room_lighting_mode`
-   - Default Mode: `Adaptive`
-
-**Testing**:
-- [ ] Enter room → lights turn on (via separate occupancy automation)
-- [ ] Press config button → cycles through 4 modes
-- [ ] Set to Theater mode, leave room → after 5 min, resets to Adaptive
-- [ ] Manual boost → leave room → manual control clears
-
-## Example 3: Bathroom (Simple)
-
-**Goal**: Always Adaptive, brightness boost only
-
-**Hardware**:
-- Inovelli Blue Dimmer: `bathroom_switch`
-- Lights: `light.bathroom_ceiling`, `light.bathroom_vanity`
-- Presence: `binary_sensor.bathroom_occupancy`
-
-**Package File** (`packages/adaptive_lighting_bathroom.yaml`):
-
-Copy from `adaptive_lighting_simple_template.yaml`
-- No modes (Adaptive only)
-- No weekend mode
-- Simple reset on presence end
-
-**Blueprint Automations**:
-
-1. **Button Actions ONLY**:
-   - Double-tap up: Boost brightness
-   - Triple-tap down: Night light
-   - Auto-reset: 10 minutes
-
-2. **Presence Mode Reset**:
-   - Reset manual control when empty 5 minutes
-   - No mode reset (no input_select)
-
-**Testing**:
-- [ ] Double-tap up → brightness boosts
-- [ ] Leave bathroom 5 min → manual control clears
-- [ ] Triple-tap down → night light mode
-- [ ] No config button action (not configured)
-
-## Entity ID Quick Reference
-
-### Finding Your Entities
-
-**Inovelli Switch Entities** (via Zigbee2MQTT):
-```
-event.{device_name}_action           # Button presses (event entity)
-number.{device_name}_led_color_when_on
-number.{device_name}_led_color_when_off
-number.{device_name}_led_intensity_when_on
-select.{device_name}_smart_bulb_mode
-select.{device_name}_button_delay
-```
-
-**Adaptive Lighting Entities**:
-```
-switch.adaptive_lighting_{name}
-switch.adaptive_lighting_sleep_mode_{name}
-switch.adaptive_lighting_adapt_brightness_{name}
-switch.adaptive_lighting_adapt_color_{name}
-```
-
-**Your Input Helpers**:
-```
-input_select.{room}_lighting_mode
-input_boolean.{room}_weekend_mode
-```
-
-## Common Customizations
-
-### Add a New Mode
-
-1. Edit package file, add mode to `input_select`:
 ```yaml
-input_select:
-  bedroom_lighting_mode:
-    options:
-      - "Adaptive"
-      - "Reading"
-      - "NEW MODE HERE"  # Add this
+adaptive_lighting:
+  - name: living_room
+    lights:
+      - light.living_room_ceiling
+      - light.living_room_lamp_1
+      - light.living_room_lamp_2
+    interval: 90
+    transition: 30
 ```
 
-2. Add color mapping to global package (or use existing color)
+### UI Configuration Steps
+
+**Step 1: Create Mode Selector**
+- Name: "Living Room Lighting Mode"
+- Entity ID: `input_select.living_room_lighting_mode`
+- Options: Adaptive, Theater, Party, Relaxing
+- Initial: Adaptive
+
+**Step 2: Create Mode Application Automation**
+- Blueprint: Apply Lighting Mode Settings
+- Mode Input Select: `input_select.living_room_lighting_mode`
+- AL Switch: `switch.adaptive_lighting_living_room`
+- LED Entity: `number.living_room_switch_led_color_when_on` (if Inovelli)
+- Name: "Living Room: Apply Lighting Mode"
+
+**Weekend Mode**: Optional for living room - use if you want different behavior on weekends
+
+### Testing
+
+- [ ] Switch to Theater mode → lights dim for movie watching
+- [ ] Switch to Party mode → lights bright and dynamic
+- [ ] Switch to Adaptive → normal adaptive behavior
+- [ ] LED colors match modes (if Inovelli)
+
+## Example 3: Simple Bathroom
+
+**Goal**: Always adaptive, no mode switching needed
+
+**Room Type**: Utility space with simple lighting needs
+
+### Adaptive Lighting Configuration
 
-3. Add mode application to automation:
 ```yaml
-- conditions: "{{ mode == 'NEW MODE HERE' }}"
-  sequence:
-    - service: adaptive_lighting.change_switch_settings
-      data:
-        min_brightness: 50
-        max_brightness: 80
-        # ... settings
+adaptive_lighting:
+  - name: bathroom
+    lights:
+      - light.bathroom_ceiling
+      - light.bathroom_vanity
+    interval: 60
+    transition: 20
 ```
 
-4. Reload YAML configuration
+### UI Configuration Steps
 
-### Change Auto-Reset Timeout
+**Step 1: Create Mode Selector (Minimal)**
+- Name: "Bathroom Lighting Mode"
+- Entity ID: `input_select.bathroom_lighting_mode`
+- Options: Adaptive, Sleep (for night use)
+- Initial: Adaptive
 
-Edit blueprint automation via UI:
-- Settings → Automations → [Your button action automation]
-- Click Edit
-- Adjust "Auto-Reset Timeout" slider
+**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
 
-### Disable Weekend Mode
+**Step 3**: Test
+- Switch to Reading mode via UI
+- Verify it works without any blueprint changes!
 
-Comment out weekend mode automations in package file:
-```yaml
-#  - id: bedroom_weekend_mode_auto_enable
-#    alias: "Bedroom: Enable Weekend Mode Friday/Saturday"
-#    # ... entire automation
-```
+### Change Weekend Mode Times
 
-Reload YAML configuration.
+**Edit the automation**:
+- Settings → Automations & Scenes
+- Find "{Room}: Weekend Mode Apply Settings"
+- Click **Edit**
+- Adjust sunrise time, sunset time, or max brightness
+- Save
+
+Changes apply immediately (no restart needed).
+
+### Remove Weekend Mode
+
+If you no longer want weekend mode:
+
+**Step 1**: Disable automations
+- Settings → Automations & Scenes
+- Find weekend mode automations
+- Toggle them OFF (or delete them)
+
+**Step 2**: Delete helpers (optional)
+- Settings → Devices & Services → Helpers
+- Find weekend mode boolean
+- Delete
+
+### Use Scene-Based Modes
+
+Want a mode that activates a complex scene?
+
+See [ADDING_MODES.md - Advanced Examples](ADDING_MODES.md#advanced-examples) for scene and script-based mode creation.
+
+## Troubleshooting
+
+### Mode Doesn't Change Lights
+
+**Symptom**: Selected mode but lights stayed the same
+
+**Solutions**:
+1. Check automation is enabled: Settings → Automations → "{Room}: Apply Lighting Mode"
+2. View automation trace: Click automation → Traces tab
+3. Verify AL switch entity ID is correct in automation config
+4. Verify mode selector entity ID matches automation config
+5. Check mode settings entity exists: Developer Tools → States → `input_text.adaptive_lighting_settings_{mode}`
+
+### LED Doesn't Change Color
+
+**Symptom**: Mode changes work but LED stays same color
+
+**Solutions**:
+1. Verify LED entity configured in automation (not left empty)
+2. Check LED entity ID is correct (should be `number.{device}_led_color_when_on`)
+3. Test LED manually: Developer Tools → Services → `number.set_value`
+4. Verify Inovelli switch firmware is up to date
+
+### Weekend Mode Doesn't Apply
+
+**Symptom**: Boolean toggles but AL settings don't change
+
+**Solutions**:
+1. Check "Weekend Mode Apply Settings" automation is enabled
+2. View automation trace to see what happened
+3. Verify AL switch entity ID is correct
+4. Manually trigger automation: Developer Tools → Services → `automation.trigger`
+5. Check for errors in logs
+
+### Modes Work But Automation Triggers Too Often
+
+**Symptom**: Automation runs many times for single mode change
+
+**Solutions**:
+- This is expected behavior - automation uses `mode: restart`
+- Check automation traces - should see restart behavior
+- If causing issues, automation is working as designed (debounces rapid changes)
+- No action needed unless you see actual problems
+
+### Can't Find Mode Selector in UI
+
+**Symptom**: Created helper but can't find it on dashboard
+
+**Solutions**:
+1. Check entity was created: Settings → Devices & Services → Helpers
+2. Add to dashboard manually: Edit Dashboard → Add Card → Entities → Select your input_select
+3. Or use in automations/scripts without dashboard visibility
+4. Verify entity ID in Developer Tools → States
+
+## Next Steps
+
+After configuring your first room:
+
+1. **Add more rooms**: Repeat the basic workflow for each room
+2. **Customize modes**: See [ADDING_MODES.md](ADDING_MODES.md) to create custom modes
+3. **Add Inovelli integration**: Use optional blueprints for button control
+4. **Add presence control**: Use presence_mode_reset blueprint for occupancy-based automation
+
+For more information:
+- [ADDING_MODES.md](ADDING_MODES.md) - Custom mode creation tutorial
+- [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) - Global package installation
+- [README.md](README.md) - Main documentation
+- [Adaptive Lighting Docs](https://github.com/basnijholt/adaptive-lighting) - AL integration reference