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

@@ -0,0 +1,56 @@
+---
+- name: Deploy Gitea MCP Server with Docker Compose
+  hosts: ubuntu
+  become: true
+  vars:
+    required_service: gitea_mcp
+  tasks:
+  - name: Check if host has gitea_mcp service
+    ansible.builtin.set_fact:
+      has_gitea_mcp_service: "{{ required_service in services | default([]) }}"
+
+  - name: Skip hosts without gitea_mcp service
+    ansible.builtin.meta: end_host
+    when: not has_gitea_mcp_service
+
+  - name: Create gitea_mcp group
+    ansible.builtin.group:
+      name: "{{gitea_mcp_group}}"
+
+  - name: Create gitea_mcp user
+    ansible.builtin.user:
+      name: "{{gitea_mcp_user}}"
+      comment: "{{gitea_mcp_user}}"
+      group: "{{gitea_mcp_group}}"
+      system: true
+
+  - name: Add group gitea_mcp to Ansible remote_user
+    ansible.builtin.user:
+      name: "{{remote_user}}"
+      groups: "{{gitea_mcp_group}}"
+      append: true
+
+  - name: Create gitea_mcp directory
+    ansible.builtin.file:
+      path: "{{gitea_mcp_directory}}"
+      owner: "{{gitea_mcp_user}}"
+      group: "{{gitea_mcp_group}}"
+      state: directory
+      mode: '750'
+
+  - name: Template docker-compose file
+    ansible.builtin.template:
+      src: docker-compose.yml.j2
+      dest: "{{gitea_mcp_directory}}/docker-compose.yml"
+      owner: "{{gitea_mcp_user}}"
+      group: "{{gitea_mcp_group}}"
+      mode: '550'
+
+  - name: Reset SSH connection to apply group changes
+    meta: reset_connection
+
+  - name: Start Gitea MCP service
+    community.docker.docker_compose_v2:
+      project_src: "{{gitea_mcp_directory}}"
+      state: present
+      pull: always

ansible/gitea_mcp/docker-compose.yml.j2

@@ -0,0 +1,18 @@
+services:
+  gitea-mcp:
+    image: docker.gitea.com/gitea-mcp-server:latest
+    pull_policy: always
+    container_name: gitea-mcp
+    restart: unless-stopped
+    ports:
+      - "{{gitea_mcp_port}}:8000"
+    environment:
+      - GITEA_HOST={{gitea_mcp_host}}
+      - GITEA_ACCESS_TOKEN={{gitea_mcp_access_token}}
+    command: ["/app/gitea-mcp", "-t", "http", "--port", "8000"]
+    logging:
+      driver: syslog
+      options:
+        syslog-address: "tcp://127.0.0.1:{{gitea_mcp_syslog_port}}"
+        syslog-format: "{{syslog_format}}"
+        tag: "gitea-mcp"

ansible/gitea_mcp/remove.yml

@@ -0,0 +1,36 @@
+---
+- name: Remove Gitea MCP Server
+  hosts: ubuntu
+  become: true
+  tasks:
+    - name: Check if host has gitea_mcp service
+      ansible.builtin.set_fact:
+        has_gitea_mcp_service: "{{ 'gitea_mcp' in services | default([]) }}"
+
+    - name: Skip hosts without gitea_mcp service
+      ansible.builtin.meta: end_host
+      when: not has_gitea_mcp_service
+
+    - name: Check if docker-compose.yml exists
+      ansible.builtin.stat:
+        path: "{{gitea_mcp_directory}}/docker-compose.yml"
+      register: compose_file
+
+    - name: Stop and remove Docker containers, volumes, and images
+      community.docker.docker_compose_v2:
+        project_src: "{{gitea_mcp_directory}}"
+        state: absent
+        remove_images: all
+        remove_volumes: true
+      when: compose_file.stat.exists
+
+    - name: Prune Docker images
+      community.docker.docker_prune:
+        images: true
+        images_filters:
+          dangling: false
+
+    - name: Remove Gitea MCP directory
+      ansible.builtin.file:
+        path: "{{gitea_mcp_directory}}"
+        state: absent