docs: rewrite README with structured overview and quick start guide

Replaces the minimal project description with a comprehensive README
including a component overview table, quick start instructions, common
Ansible operations, and links to detailed documentation. Aligns with
Red Panda Approval™ standards.

ansible/hass/configuration.yaml

@@ -0,0 +1,17 @@
+# Loads default set of integrations. Do not remove.
+default_config:
+
+# ISAL accelerates aiohttp
+isal:
+
+# Load frontend themes from the themes folder
+frontend:
+  themes: !include_dir_merge_named themes
+
+automation: !include automations.yaml
+script: !include scripts.yaml
+scene: !include scenes.yaml
+
+homeassistant:
+  media_dirs:
+    media: /mnt/media

ansible/hass/configuration.yaml.j2

@@ -0,0 +1,33 @@
+# Loads default set of integrations. Do not remove.
+default_config:
+
+# ISAL accelerates aiohttp
+isal:
+
+# Load frontend themes from the themes folder
+frontend:
+  themes: !include_dir_merge_named themes
+
+automation: !include automations.yaml
+script: !include scripts.yaml
+scene: !include scenes.yaml
+
+homeassistant:
+  media_dirs:
+    media: {{hass_media_directory}}
+
+# HTTP configuration for reverse proxy (HAProxy on Titania)
+http:
+  server_port: {{hass_port}}
+  use_x_forwarded_for: true
+  trusted_proxies:
+    - 10.0.0.0/8
+
+# PostgreSQL recorder (Portia)
+recorder:
+  db_url: "postgresql://{{hass_db_user}}:{{hass_db_password}}@{{hass_db_host}}:{{hass_db_port}}/{{hass_db_name}}"
+  purge_keep_days: 30
+  commit_interval: 1
+
+# Prometheus metrics endpoint
+prometheus:

ansible/hass/deploy.yml

@@ -0,0 +1,139 @@
+---
+- name: Deploy Home Assistant to Dev Environment
+  hosts: ubuntu
+  vars:
+    ansible_common_remote_group: "{{hass_group}}"
+    allow_world_readable_tmpfiles: true
+  tasks:
+  - name: Check if host has hass service
+    ansible.builtin.set_fact:
+      has_hass_service: "{{ 'hass' in services | default([]) }}"
+
+  - name: Skip hosts without hass service
+    ansible.builtin.meta: end_host
+    when: not has_hass_service
+
+  - name: Create hass user
+    become: true
+    ansible.builtin.user:
+      name: "{{hass_user}}"
+      comment: "{{hass_user}}"
+      system: true
+      create_home: false
+
+  - name: Add group hass to user {{remote_user}}
+    become: true
+    ansible.builtin.user:
+      name: "{{remote_user}}"
+      groups: "{{hass_group}}"
+      append: true
+
+  - name: Create required directories
+    become: true
+    ansible.builtin.file:
+      path: "{{item.path}}"
+      owner: "{{hass_user}}"
+      group: "{{hass_group}}"
+      state: directory
+      mode: '750'
+    loop:
+      - path: "{{hass_directory}}"
+      - path: "{{hass_media_directory}}"
+
+  - name: Add Deadsnakes APT repository
+    become: true
+    ansible.builtin.apt_repository:
+      repo: ppa:deadsnakes/ppa
+
+  - name: Install Python 3.13 and build dependencies
+    become: true
+    ansible.builtin.apt:
+      name:
+        - python3.13-dev
+        - python3.13-venv
+        - build-essential
+        - libffi-dev
+        - libssl-dev
+      state: present
+      update_cache: true
+
+  - name: Create virtual environment
+    become: true
+    become_user: "{{hass_user}}"
+    ansible.builtin.command:
+      cmd: python3.13 -m venv {{hass_directory}}/env
+    args:
+      creates: "{{hass_directory}}/env/bin/activate"
+
+  - name: Template configuration files
+    become: true
+    ansible.builtin.template:
+      src: "{{item.src}}"
+      dest: "{{hass_directory}}/{{item.dest}}"
+      owner: "{{hass_user}}"
+      group: "{{hass_group}}"
+      mode: '550'
+    loop:
+      - src: "configuration.yaml.j2"
+        dest: "configuration.yaml"
+      - src: "requirements.txt.j2"
+        dest: "requirements.txt"
+    notify: restart hass
+
+  - name: Create systemd service file
+    become: true
+    ansible.builtin.template:
+      src: hass.service.j2
+      dest: /etc/systemd/system/hass.service
+      mode: '644'
+    notify: restart hass
+
+  - name: Install Python packages from requirements
+    become: true
+    become_user: "{{hass_user}}"
+    ansible.builtin.pip:
+      requirements: "{{hass_directory}}/requirements.txt"
+      virtualenv: "{{hass_directory}}/env"
+      virtualenv_python: python3.13
+    vars:
+      ansible_common_remote_group: "{{hass_group}}"
+      allow_world_readable_tmpfiles: true
+    notify: restart hass
+
+  - name: Reset SSH connection to apply group changes
+    meta: reset_connection
+
+  - name: Enable and start Home Assistant service
+    become: true
+    ansible.builtin.systemd:
+      name: hass
+      enabled: true
+      state: started
+      daemon_reload: true
+
+  post_tasks:
+  - name: Wait for Home Assistant to initialize
+    ansible.builtin.pause:
+      seconds: 30
+      prompt: "Waiting for Home Assistant to initialize..."
+
+  - name: Check if Home Assistant is running
+    ansible.builtin.uri:
+      url: http://localhost:{{hass_port}}/
+      method: GET
+      status_code: 200
+      timeout: 10
+    register: hass_status
+    ignore_errors: true
+
+  - name: Show Home Assistant status
+    ansible.builtin.debug:
+      msg: "Home Assistant is {{ 'running' if hass_status.status == 200 else 'not running properly' }}"
+
+  handlers:
+  - name: restart hass
+    become: true
+    ansible.builtin.systemd:
+      name: hass
+      state: restarted
+      daemon_reload: true

ansible/hass/hass.service.j2

@@ -0,0 +1,18 @@
+[Unit]
+Description=Home Assistant
+After=network.target
+
+[Service]
+Type=simple
+User={{hass_user}}
+Group={{hass_group}}
+WorkingDirectory={{hass_directory}}
+ExecStart=/bin/bash -c 'source {{hass_directory}}/env/bin/activate && hass --config {{hass_directory}}'
+Restart=always
+RestartSec=3
+SyslogIdentifier=hass
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target

ansible/hass/requirements.txt.j2

@@ -0,0 +1,2 @@
+wheel
+homeassistant=={{hass_version}}