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/alloy/deploy.yml

@@ -0,0 +1,116 @@
+---
+- name: Deploy Alloy to All Ubuntu Hosts
+  hosts: ubuntu
+  tasks:
+  - name: Check if host has alloy service
+    ansible.builtin.set_fact:
+      has_alloy_service: "{{'alloy' in services}}"
+
+  - name: Skip hosts without alloy service
+    ansible.builtin.meta: end_host
+    when: not has_alloy_service
+
+  - name: Add Grafana repository
+    become: true
+    ansible.builtin.deb822_repository:
+      name: grafana
+      types: [deb]
+      uris: https://apt.grafana.com
+      suites: [stable]
+      components: [main]
+      signed_by: https://apt.grafana.com/gpg.key
+      state: present
+
+  - name: Install Alloy
+    become: true
+    ansible.builtin.apt:
+      name: alloy
+      state: present
+      update_cache: true
+
+  - name: Check for host-specific Alloy config
+    ansible.builtin.stat:
+      path: "{{playbook_dir}}/{{inventory_hostname_short}}/config.alloy.j2"
+    register: host_specific_config
+    delegate_to: localhost
+    connection: local
+
+  - name: Create Alloy configuration (host-specific)
+    become: true
+    ansible.builtin.template:
+      src: "{{ inventory_hostname_short }}/config.alloy.j2"
+      dest: /etc/alloy/config.alloy
+      owner: alloy
+      group: alloy
+      mode: '644'
+    when: host_specific_config.stat.exists
+    notify: restart alloy
+
+  - name: Create Alloy configuration (default)
+    become: true
+    ansible.builtin.template:
+      src: config.alloy.j2
+      dest: /etc/alloy/config.alloy
+      owner: alloy
+      group: alloy
+      mode: '644'
+    when: not host_specific_config.stat.exists
+    notify: restart alloy
+
+  - name: Check if host has docker service
+    ansible.builtin.set_fact:
+      has_docker_service: "{{'docker' in services}}"
+
+  - name: Add alloy user to docker group for cAdvisor
+    become: true
+    ansible.builtin.user:
+      name: alloy
+      groups: docker
+      append: true
+    when: has_docker_service
+    notify: restart alloy
+
+  - name: Check if host has gitea service
+    ansible.builtin.set_fact:
+      has_gitea_service: "{{'gitea' in services}}"
+
+  - name: Add alloy user to gitea group for log collection
+    become: true
+    ansible.builtin.user:
+      name: alloy
+      groups: git
+      append: true
+    when: has_gitea_service
+    notify: restart alloy
+
+  - name: Enable and start Alloy service
+    become: true
+    ansible.builtin.systemd:
+      name: alloy
+      enabled: true
+      state: started
+      daemon_reload: true
+
+  - name: Flush handlers to ensure Alloy is restarted if needed
+    ansible.builtin.meta: flush_handlers
+
+  - name: Verify Alloy service is running
+    become: true
+    ansible.builtin.systemd:
+      name: alloy
+    register: alloy_service_status
+
+  - name: Confirm Alloy service is active
+    ansible.builtin.assert:
+      that:
+        - alloy_service_status.status.ActiveState == "active"
+      fail_msg: "Alloy service is not running (state: {{ alloy_service_status.status.ActiveState }})"
+      success_msg: "Alloy service is running"
+
+  handlers:
+  - name: restart alloy
+    become: true
+    ansible.builtin.systemd:
+      name: alloy
+      state: restarted
+