# Home Assistant Automation Blueprints

This repository contains automation blueprints for Home Assistant OS.

## Git Workflow

**Do not commit or push automatically.** Always ask before committing or pushing changes.

## Code Review Guidelines

When reviewing or refactoring blueprint files:

1. **Code Quality** - Improve overall structure and readability
2. **Bug Fixes** - Identify and fix obvious or critical bugs and mistakes
3. **Spelling & Grammar** - Correct any spelling or grammatical errors
4. **Documentation** - Add comments to make the code easier to read and understand
5. **User-Friendly Messages** - Use entity friendly names instead of entity IDs in notification messages

## Versioning

After any change to repository content (blueprints, documentation, or other files), update the `version` field in `manifest.json` using semantic versioning:

- **Major** (X.0.0) - Breaking changes or major new features
- **Minor** (0.X.0) - New features, enhancements, or significant improvements
- **Patch** (0.0.X) - Bug fixes, typos, small tweaks, or documentation updates

## Repository Structure

Each blueprint is organized in its own folder:

```text
Common/
  Blueprint Name/
    blueprint.yaml    # The automation blueprint
    README.md         # Detailed documentation
Zigbee/
  Blueprint Name/
    blueprint.yaml
    README.md
```

### Working with Blueprints

**When modifying a blueprint:**

1. Edit `blueprint.yaml` for code changes
2. Update `README.md` if the change affects features, configuration, or behavior
3. Keep the blueprint header short (4-5 lines) - detailed docs go in README.md

**When creating a new blueprint:**

1. Create a new folder named after the blueprint (e.g., `Common/My New Blueprint/`)
2. Add `blueprint.yaml` with a short header referencing README.md
3. Add `README.md` with full documentation (features, how it works, configuration)

**Blueprint header format:**

```yaml
# Blueprint Name
# One-line description of what it does.
# See README.md for detailed documentation.
#
# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
```

When any blueprint file is moved ask if I need to update the link somewhere else.

## Jinja2 Whitespace Issue

Home Assistant evaluates all blueprint variables before conditions are checked. When a variable's Jinja2 template contains whitespace (newlines, indentation), that whitespace gets included in the output even if the template logic produces an empty string.

**Problem:** Using a variable like `{{ my_variable }}` in string replacements will include unwanted whitespace.

**Solution:** Compute complex values inline where they're used, with `{%- -%}` whitespace control:

```yaml
# BAD - whitespace from my_list variable will be included
my_list: >
  {% for item in items %}
    {{ item }}
  {% endfor %}

result: "{{ template | replace('{items}', my_list) }}"

# GOOD - inline computation with whitespace control
result: >
  {%- set ns = namespace(items = '') -%}
  {%- for item in items -%}
    {%- set ns.items = ns.items ~ item -%}
  {%- endfor -%}
  {{ template | replace('{items}', ns.items) }}
```

This pattern is used throughout the Immich Album Watcher blueprint for `common_date`, `common_location`, `video_warning`, and `periodic_albums_list`.