# Package Setup Guide

## Overview

This guide explains how to set up Home Assistant packages for the Adaptive
Lighting Mode System and configure version control.

## 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.

**Benefits**:
- Organize configuration by room or feature
- Version control specific areas independently
- Easier to 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

## Step 1: Enable Packages in Home Assistant

**1.1 Edit your `configuration.yaml`**

Add this line to the top of your `configuration.yaml`:

```yaml
homeassistant:
  packages: !include_dir_named packages/
```

**1.2 Create the packages directory**

SSH into your Home Assistant instance or use File Editor add-on:

```bash
cd /config
mkdir packages
```

**1.3 Restart Home Assistant**

Settings → System → Restart Home Assistant

## Step 2: Install Global Definitions

**2.1 Copy the global package**

Download or copy `packages/adaptive_lighting_global.yaml` from this repository
to your `/config/packages/` directory.

**2.2 Reload YAML configuration**

Developer Tools → YAML → Reload all YAML configuration

**2.3 Verify helpers exist**

Settings → Devices & Services → Helpers

You should see:
- `input_text.adaptive_lighting_mode_colors`
- `input_text.adaptive_lighting_settings_adaptive`
- `input_text.adaptive_lighting_settings_reading`
- `input_text.adaptive_lighting_settings_relaxing`
- `input_text.adaptive_lighting_settings_sleep`
- And several more mode settings helpers

## Step 3: Import Blueprints

**3.1 Import via UI**

Settings → Automations & Scenes → Blueprints → Import Blueprint

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
```

**3.2 Verify blueprints imported**

Settings → Automations & Scenes → Blueprints

You should see all three blueprints listed.

## Step 4: Configure Your First Room

**4.1 Choose a template**

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
```

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

**4.3 Reload configuration**

Developer Tools → YAML → Reload all YAML configuration

**4.4 Create blueprint automations**

Settings → Automations & Scenes → Create Automation → Use Blueprint

Create automations for:
1. Inovelli Mode Cycling (config button)
2. Inovelli Button Actions (multi-tap)
3. Presence Mode Reset (if you have occupancy sensors)

## Step 5: Version Control Setup (Optional)

**5.1 Initialize git repository**

```bash
cd /config
git init
```

**5.2 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
# - configuration.yaml
# - blueprints/
EOF
```

**5.3 Commit initial setup**

```bash
git add packages/ automations.yaml configuration.yaml
git commit -m "Initial adaptive lighting mode system setup"
```

**5.4 Add remote (optional)**

```bash
git remote add origin your-git-repo-url
git push -u origin main
```

## Troubleshooting

### Packages not loading

**Symptom**: Helpers don't appear after reloading

**Solutions**:
- Check `configuration.yaml` has packages line
- Verify packages directory exists at `/config/packages/`
- Check YAML syntax: `yamllint /config/packages/*.yaml`
- Look for errors in Settings → System → Logs

### Entity IDs don't match

**Symptom**: Automations fail because entities not found

**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

### Blueprints not working

**Symptom**: Automation from blueprint doesn't trigger

**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)

## Next Steps

See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for detailed
room setup examples.