Add comprehensive Home Assistant integration documentation with correct YAML syntax

[Copilot]

This PR addresses the recurring YAML syntax errors reported in issue #29 by providing comprehensive, validated documentation for integrating the ESP32 Fencing Scoring Device with Home Assistant.

Problem

Users were experiencing frustration with AI-generated Home Assistant YAML code that contained syntax errors, specifically:

• Using unsupported Jinja block syntax ({% if ... %}) inside YAML mappings
• Mixing YAML and Jinja logic incompatibly with Home Assistant
• Not using Home Assistant's choose block for conditional logic
• Lack of proper validation for generated code snippets

Solution

This PR provides proper documentation and examples that users can reference instead of relying on potentially incorrect AI-generated code:

Documentation Added

• docs/home-assistant-integration.md (465 lines) - Comprehensive integration guide with:

  • Complete MQTT sensor configurations for the ESP32 device
  • Proper automation examples for match notifications and scoring
  • Correct script examples using Home Assistant patterns
  • Dashboard configuration examples
  • All examples use proper Home Assistant YAML syntax

• docs/yaml-troubleshooting.md (309 lines) - Detailed troubleshooting guide addressing:

  • Specific solutions for the exact syntax errors mentioned in issue #29
  • Correct vs incorrect YAML patterns with side-by-side comparisons
  • Proper use of choose instead of {% if %} blocks
  • Correct use of repeat instead of {% for %} loops
  • Template validation and debugging guidance

• docs/home-assistant-example-config.yaml (98 lines) - Copy-paste ready configuration examples

• docs/README.md - Documentation index for easy navigation

Key Technical Improvements

Before (Incorrect):

automation:
  action:
    {% if states('sensor.piste_status') == 'H' %}
    service: notify.mobile_app
    {% endif %}

After (Correct):

automation:
  action:
    choose:
      - conditions:
          - condition: state
            entity_id: sensor.piste_status
            state: "H"
        sequence:
          - service: notify.mobile_app

Validation

• All YAML examples have been syntax validated
• Examples follow Home Assistant's official documentation patterns
• Includes validation checklist and debugging tools
• Provides links to official Home Assistant resources

MQTT Integration

The ESP32 scoring device already has MQTT support via AtlasAsyncMqttClient, making Home Assistant integration a natural use case. The documentation provides specific examples for:

• Device connection monitoring (MQTT_Cyrano/Piste_XXX/Connection)
• Scoring data sensors (MQTT_Cyrano/Piste_XXX/FromDevice)
• Device control commands (MQTT_Cyrano/Piste_XXX/FromSoftware)

This documentation helps users avoid the syntax errors mentioned in the issue and provides a reliable reference for proper Home Assistant integration patterns.

Fixes #29.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

@pietwauters 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.