# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview
This is a Home Assistant Blueprints repository containing reusable automation templates for smart home systems. All blueprints are YAML configuration files that can be imported directly into Home Assistant.

## Common Development Tasks

### Deployment
After committing and pushing changes, deploy blueprints to Home Assistant:
```bash
HA_POD=$(kubectl -n ha get pods -l app=ha-app -o=jsonpath="{.items[0].metadata.name}")
kubectl -n ha exec "$HA_POD" -- bash -c "cd /config/blueprints/automation/rzen && git pull"
```

### Testing & Validation
- **Blueprint Validation**: Use Home Assistant's built-in blueprint importer to validate YAML syntax
- **Template Testing**: Test Jinja2 templates in Home Assistant Developer Tools → Template tab
- **Live Testing**: Import blueprint into Home Assistant and create test automation to verify behavior

### Working with Blueprints
When modifying or creating blueprints:
1. Follow the standard Home Assistant blueprint schema structure
2. Always include comprehensive descriptions for user clarity
3. Provide sensible defaults for all input parameters
4. Use proper selectors for entity inputs (entity, device, area selectors)
5. Test templates for edge cases (unavailable entities, null states)

## Architecture & Code Structure

### Blueprint Components
Every blueprint follows this structure:
- **blueprint:** Metadata section with name, description, domain (always "automation")
- **input:** User-configurable parameters with selectors and defaults
- **trigger:** Event triggers (state changes, time patterns, device events)
- **condition:** Optional conditional logic
- **variables:** Template variables for complex logic
- **action:** Automation actions to execute
- **mode:** Execution mode (single, restart, queued, parallel)

### Key Patterns

#### Template Safety
Always use fallback defaults in templates:
```yaml
{{ states('sensor.temperature') | float(0) }}
{{ state_attr('device.battery', 'battery_level') | int(100) }}
```

#### Entity Expansion
Use expand() for working with entity groups:
```yaml
{% for entity_id in expand(battery_sensors) | map(attribute='entity_id') | list %}
```

#### Z-Wave Event Handling
Z-Wave central scene events follow this pattern:
```yaml
trigger:
  - platform: event
    event_type: zwave_js_value_notification
    event_data:
      command_class: 91  # Central Scene
      property_key: "001"  # Scene ID
```

#### Complex State Calculations
Use namespace objects for accumulating values:
```yaml
{% set ns = namespace(total=0, count=0) %}
{% for entity in entities %}
  {% set ns.total = ns.total + states(entity) | float(0) %}
  {% set ns.count = ns.count + 1 %}
{% endfor %}
```

## Blueprint Categories

### HVAC & Climate Control
- **hvac-failure-monitor.yaml**: Monitors HVAC performance using temperature differentials
- **fan-management.yaml**: Bathroom fan automation with light triggers
- **fan-cadence.yaml**: Periodic fan cycling with override protection

### Power & Energy
- **power-monitoring.yaml**: Detects power spikes for appliance identification
- **battery-monitor.yaml**: Multi-device battery level monitoring

### Smart Switches & Scenes
- **multi-tap-automation.yaml**: Z-Wave switch multi-tap scene control
- **multi-tap-automation-homeseer-and-zooz.yaml**: Enhanced multi-tap with HomeSeer/Zooz support
- **indication.yaml**: HomeSeer WD200+ LED indicator control

### Security & Utility
- **simulated-presence.yaml**: Random light automation for security
- **state-opposite.yaml**: Bidirectional entity state synchronization

## Important Implementation Notes

### Input Validation
- Use proper selector types (number with min/max, boolean, entity with domain filter)
- Always provide defaults to prevent undefined errors
- Use multi-select for flexibility where appropriate

### Error Handling
- Check entity availability before actions
- Use conditional sequences for optional actions
- Implement proper fallbacks for missing data

### Performance Considerations
- Use appropriate automation modes (single for exclusive, restart for updates)
- Minimize template complexity in frequently-triggered automations
- Consider using time patterns instead of constant state monitoring

### Common Issues & Solutions
- **Template errors**: Test in Developer Tools first
- **Entity unavailable**: Add availability checks in conditions
- **Z-Wave events not firing**: Verify device supports Central Scene command class
- **HVAC monitoring false positives**: Adjust temperature thresholds and time windows
- always push after commit