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

@@ -0,0 +1,157 @@
+---
+- name: Deploy Gitea Runner
+  hosts: ubuntu
+  become: true
+  tasks:
+
+    - name: Check if host has gitea_runner service
+      ansible.builtin.set_fact:
+        has_gitea_runner_service: "{{ 'gitea_runner' in services }}"
+
+    - name: Skip hosts without gitea_runner service
+      ansible.builtin.meta: end_host
+      when: not has_gitea_runner_service
+
+    # =========================================================================
+    # Service Account
+    # =========================================================================
+
+    - name: Create gitea-runner system group
+      ansible.builtin.group:
+        name: gitea-runner
+        system: true
+        state: present
+
+    - name: Create gitea-runner system user
+      ansible.builtin.user:
+        name: gitea-runner
+        group: gitea-runner
+        groups: docker
+        append: true
+        system: true
+        shell: /bin/bash
+        home: /srv/gitea-runner
+        create_home: true
+        comment: "Gitea Act Runner"
+
+    # =========================================================================
+    # Binary Installation
+    # =========================================================================
+
+    - name: Ensure /usr/local/bin directory exists
+      ansible.builtin.file:
+        path: /usr/local/bin
+        state: directory
+        mode: '0755'
+        owner: root
+        group: root
+
+    - name: Check current act_runner version
+      ansible.builtin.command: /usr/local/bin/act_runner --version
+      register: act_runner_current_version
+      changed_when: false
+      failed_when: false
+
+    - name: Download act_runner binary
+      ansible.builtin.get_url:
+        url: "https://gitea.com/gitea/act_runner/releases/download/v{{ act_runner_version }}/act_runner-{{ act_runner_version }}-linux-amd64"
+        dest: /usr/local/bin/act_runner
+        mode: '0755'
+        owner: root
+        group: root
+        force: true
+      when: act_runner_current_version.rc != 0 or act_runner_version not in (act_runner_current_version.stdout | default(''))
+      notify: restart gitea-runner
+
+    # =========================================================================
+    # Configuration
+    # =========================================================================
+
+    - name: Copy runner config
+      ansible.builtin.copy:
+        src: config.yaml
+        dest: /srv/gitea-runner/config.yaml
+        owner: gitea-runner
+        group: gitea-runner
+        mode: '0644'
+      notify: restart gitea-runner
+
+    # =========================================================================
+    # Systemd Service
+    # =========================================================================
+
+    - name: Template gitea-runner systemd service
+      ansible.builtin.template:
+        src: gitea-runner.service.j2
+        dest: /etc/systemd/system/gitea-runner.service
+        owner: root
+        group: root
+        mode: '0644'
+      notify: restart gitea-runner
+
+    - name: Check if runner is registered
+      ansible.builtin.stat:
+        path: /srv/gitea-runner/.runner
+      register: runner_registration
+
+    # =========================================================================
+    # Registration
+    # =========================================================================
+
+    - name: Prompt for registration token
+      ansible.builtin.pause:
+        prompt: |
+          
+          Gitea runner registration required.
+          Get token from: {{ gitea_runner_instance_url }}/-/admin/runners
+          
+          Enter registration token
+      register: runner_token
+      when: 
+        - not runner_registration.stat.exists
+        - registration_token is not defined
+
+    - name: Set registration token from prompt or variable
+      ansible.builtin.set_fact:
+        runner_registration_token: "{{ registration_token | default(runner_token.user_input) }}"
+      when: not runner_registration.stat.exists
+
+    - name: Register runner with Gitea instance
+      ansible.builtin.shell:
+        cmd: >
+          sudo -u gitea-runner
+          /usr/local/bin/act_runner register
+          --instance {{ gitea_runner_instance_url }}
+          --token {{ runner_registration_token }}
+          --name {{ gitea_runner_name }}
+          --no-interactive
+      args:
+        creates: /srv/gitea-runner/.runner
+        chdir: /srv/gitea-runner
+      when: not runner_registration.stat.exists
+
+    # =========================================================================
+    # Service Management
+    # =========================================================================
+
+    - name: Enable gitea-runner service
+      ansible.builtin.systemd:
+        name: gitea-runner
+        enabled: true
+        daemon_reload: true
+
+    - name: Start gitea-runner service
+      ansible.builtin.systemd:
+        name: gitea-runner
+        state: started
+
+  # ===========================================================================
+  # Handlers
+  # ===========================================================================
+
+  handlers:
+    - name: restart gitea-runner
+      ansible.builtin.systemd:
+        name: gitea-runner
+        state: restarted
+        daemon_reload: true