From 04a951114278a5e4df94c395ee5fdada5a0ce0f6 Mon Sep 17 00:00:00 2001
From: John Ogle <john@ogle.fyi>
Date: Sat, 25 Oct 2025 21:51:01 -0700
Subject: [PATCH] Add CLAUDE.md

---
 CLAUDE.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..e1bb23f
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,87 @@
+# 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
\ No newline at end of file