# CLAUDE.md

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

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

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

### Current Blueprints

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

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

### Blueprint Best Practices
- 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

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

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

## File Organization

```
/
├── README.md                    # Comprehensive documentation
├── multi_press_action.yaml     # Multi-press detection blueprint
└── 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  
- `number`: Numeric input with min/max/step validation
- `boolean`: True/false toggle
- `text`: String input fields

### Template Usage
- Use `!input` to reference blueprint inputs
- Template conditions with `{{ }}` syntax for dynamic logic
- Variable assignment and reference within action sequences

### Automation Modes
- `restart`: Stops current execution and restarts on new trigger
- `single`: Ignores new triggers while running
- `parallel`: Allows multiple simultaneous executions