feat(docs): add comprehensive README for GitHub Actions runner

- Introduces a detailed README file that outlines the purpose and features of the GitHub Actions runner images.
- Highlights key functionalities including multi-architecture support and a suite of pre-installed tools.
- Provides quick start instructions and explanations for included software and customization options.
- Replaces the original, minimal README to improve documentation clarity.

chore: remove outdated README file and redundant scripts.

Author: winromulus

README.md

@@ -1 +1,228 @@
-# github-actions-runner-images
+# GitHub Actions Runner Images
+
+[![Docker Hub](https://img.shields.io/docker/pulls/emberstack/github-actions-runner.svg)](https://hub.docker.com/r/emberstack/github-actions-runner)
+[![GitHub Container Registry](https://img.shields.io/badge/ghcr.io-emberstack%2Fgithub-actions-runner-blue)](https://github.com/emberstack/github-actions-runner/pkgs/container/github-actions-runner)
+[![License](https://img.shields.io/github/license/emberstack/github-actions-runner)](LICENSE)
+
+## Overview
+
+This repository provides enhanced Docker images for GitHub Actions self-hosted runners with a comprehensive suite of pre-installed development and operations tools. Built on top of the official GitHub Actions runner base image, it includes essential tools for CI/CD workflows, making it ideal for enterprise and development environments.
+
+### Key Features
+- 🚀 Based on official GitHub Actions runner image (`ghcr.io/actions/actions-runner:2.327.1`)
+- 🏗️ Multi-architecture support (AMD64 and ARM64)
+- 📦 Comprehensive tool suite pre-installed
+- 🔧 YAML-driven installation system for easy customization
+- 🎯 Automated CI/CD pipeline with semantic versioning
+- 🐳 Published to both Docker Hub and GitHub Container Registry
+
+## Quick Start
+
+### Pull from Docker Hub
+```bash
+docker pull emberstack/github-actions-runner:latest
+```
+
+### Pull from GitHub Container Registry
+```bash
+docker pull ghcr.io/emberstack/github-actions-runner:latest
+```
+
+### Run as GitHub Actions Runner
+```bash
+docker run -d \
+  --name github-runner \
+  -e RUNNER_NAME="my-runner" \
+  -e GITHUB_TOKEN="your-github-token" \
+  -e RUNNER_REPOSITORY_URL="https://github.com/your-org/your-repo" \
+  emberstack/github-actions-runner:latest
+```
+
+## Included Software
+
+### Core Utilities
+- **GNU Coreutils** - Essential Unix utilities (ls, cp, mv, cat, etc.)
+- **File Utilities**
+  - `file` - File type identification
+  - `findutils` - Find files and directories
+  - `tree` - Directory tree visualization
+  - `time` - Time command execution
+
+### Programming Languages & Runtimes
+- **Python 3** with pip - Python interpreter and package manager
+- **PowerShell Core** - Cross-platform PowerShell
+- **Node.js** (LTS 20.x) with npm - JavaScript runtime and package manager
+- **.NET SDK**
+  - LTS version - Long Term Support release
+  - STS version - Standard Term Support (latest) release
+
+### Cloud & Infrastructure Tools
+- **Azure CLI** - Azure cloud management
+- **AzCopy** - Azure Storage data transfer (latest release)
+- **Ansible** - Infrastructure automation (latest from pip)
+
+### Container Tools
+- **Docker Compose Plugin** - Multi-container orchestration (latest)
+- **Docker Buildx Plugin** - Advanced Docker builds (latest)
+
+### Kubernetes Tools
+- **kubectl** - Kubernetes CLI (latest stable)
+- **Helm** - Kubernetes package manager (latest)
+- **Kustomize** - Kubernetes configuration management (latest)
+
+### Development Tools
+- **Git** - Version control (latest from official PPA)
+- **GitHub CLI** (`gh`) - GitHub operations (latest)
+- **jq** - JSON processor
+- **yq** - YAML processor (latest)
+- **yamllint** - YAML linter (latest from pip)
+
+### Archive & Compression Tools
+- **tar** - Tape archive utility
+- **zip/unzip** - ZIP archive utilities
+- **p7zip-full** (7z) - 7-Zip archiver
+
+### Network Tools
+- **DNS Utilities**
+  - `dig` - DNS lookup
+  - `nslookup` - Query DNS servers
+  - `nsupdate` - Dynamic DNS updates
+- **IP Utilities**
+  - `ping` - Network connectivity test
+  - `tracepath` - Network path discovery
+  - `arping` - ARP level ping
+  - `ip` - Show/manipulate routing, network devices
+  - `ss` - Socket statistics
+- **Legacy Network Tools**
+  - `ifconfig` - Network interface configuration
+  - `netstat` - Network statistics
+  - `route` - Routing table manipulation
+- **Connection Tools**
+  - `ssh` - Secure Shell client
+  - `scp` - Secure copy
+  - `ftp` - File Transfer Protocol client
+  - `telnet` - Telnet client
+  - `netcat` (`nc`) - Network debugging
+  - `sshpass` - Non-interactive SSH authentication
+
+## Architecture
+
+### Build System
+The image uses a YAML-driven installation system:
+- `src/setup.yaml` - Defines installation steps
+- `src/setup.sh` - Orchestrates the installation process
+- `src/scripts/` - Individual installation scripts for each tool group
+
+### Multi-Architecture Support
+- Automatic architecture detection during build
+- Platform-specific binaries for AMD64 and ARM64
+- Unified multi-arch manifests in registries
+
+## Building Locally
+
+### Prerequisites
+- Docker or Docker Desktop
+- Docker Buildx (for multi-platform builds)
+
+### Build for Current Platform
+```bash
+docker build -t github-actions-runner -f src/Dockerfile src/
+```
+
+### Build for Specific Platform
+```bash
+docker buildx build --platform linux/amd64 -t github-actions-runner -f src/Dockerfile src/
+```
+
+### Build Multi-Platform
+```bash
+docker buildx build --platform linux/amd64,linux/arm64 -t github-actions-runner -f src/Dockerfile src/
+```
+
+## Customization
+
+### Adding New Tools
+
+1. Create an installation script in `src/scripts/`:
+```bash
+#!/bin/bash
+# src/scripts/install-newtool.sh
+apt-get update
+apt-get install -y newtool
+# Add verification
+if ! command -v newtool &> /dev/null; then
+    echo "ERROR: newtool installation failed"
+    exit 1
+fi
+```
+
+2. Add to `src/setup.yaml`:
+```yaml
+- name: "Install New Tool"
+  script: "scripts/install-newtool.sh"
+  description: "Description of the tool"
+```
+
+3. Make the script executable:
+```bash
+chmod +x src/scripts/install-newtool.sh
+```
+
+## CI/CD Pipeline
+
+The repository uses GitHub Actions for automated building and releasing:
+
+- **Automatic Builds**: Triggered on push to any branch
+- **Multi-Architecture Builds**: Parallel builds for AMD64 and ARM64
+- **Semantic Versioning**: Using GitVersion
+- **Container Registries**: Publishes to Docker Hub and GitHub Container Registry
+- **Release Management**: Automatic GitHub releases on main branch
+
+### Version Control
+- Commit messages control version bumps:
+  - `feat:` - Minor version bump
+  - `fix:` - Patch version bump
+  - `feat!:` or `+semver:major` - Major version bump
+
+## Repository Structure
+```
+├── .github/
+│   └── workflows/
+│       └── pipeline.yaml      # CI/CD pipeline
+├── src/
+│   ├── Dockerfile            # Main Docker image definition
+│   ├── setup.yaml           # Tool installation configuration
+│   ├── setup.sh            # Installation orchestrator
+│   └── scripts/            # Individual tool installation scripts
+├── GitVersion.yaml         # Semantic versioning configuration
+├── LICENSE                # Repository license
+├── README.md             # This file
+└── CLAUDE.md            # AI assistant guidance
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+### Development Guidelines
+1. Follow the existing script patterns
+2. Ensure tools work on both AMD64 and ARM64
+3. Add verification steps in installation scripts
+4. Update documentation for new tools
+5. Test builds locally before submitting PR
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- 🐛 [Report Issues](https://github.com/emberstack/github-actions-runner/issues)
+- 💬 [Discussions](https://github.com/emberstack/github-actions-runner/discussions)
+- 📚 [Documentation](https://github.com/emberstack/github-actions-runner/wiki)
+
+## Acknowledgments
+
+- Built on top of [actions/runner](https://github.com/actions/runner) official images
+- Inspired by the need for comprehensive CI/CD environments
+- Thanks to all contributors and the open-source community

src/scripts/install-archive-tools.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+
+# Install archive and compression tools
+
+echo "Installing archive tools..."
+
+# Install archive-related packages
+apt-get update
+apt-get install -y --no-install-recommends \
+    p7zip-full \
+    zip
+
+# Note: p7zip-rar is not available in standard Ubuntu repositories
+# and requires multiverse repository which may not be available on all architectures
+# tar and unzip are already installed in base image
+
+# Verify installations
+echo ""
+echo "Verifying archive tools installation..."
+
+# Check tar (should already exist)
+if ! command -v tar &> /dev/null; then
+    echo "ERROR: tar command not found"
+    exit 1
+fi
+echo "tar available:"
+tar --version | head -1
+
+# Check zip
+if ! command -v zip &> /dev/null; then
+    echo "ERROR: zip command not found after installation"
+    exit 1
+fi
+echo "zip available:"
+zip -v | head -2 | tail -1
+
+# Check unzip (should already exist)
+if ! command -v unzip &> /dev/null; then
+    echo "ERROR: unzip command not found"
+    exit 1
+fi
+echo "unzip available:"
+unzip -v | head -1
+
+# Check 7z
+if ! command -v 7z &> /dev/null; then
+    echo "ERROR: 7z command not found after installation"
+    exit 1
+fi
+echo "7z available:"
+7z | head -2 | tail -1
+
+# Check if p7zip is available
+if command -v p7zip &> /dev/null; then
+    echo "p7zip available"
+else
+    echo "Note: p7zip command not available (7z command is the main interface)"
+fi
+
+echo ""
+echo "Archive tools installation completed successfully!"

src/scripts/install-coreutils.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+# Install/ensure coreutils (GNU Core Utilities)
+
+echo "Installing/verifying GNU coreutils..."
+
+# Install coreutils package (likely already installed, but ensure it's there)
+apt-get update
+apt-get install -y --no-install-recommends coreutils
+
+# Verify some key coreutils commands
+echo "Verifying coreutils installation..."
+
+# Check for some essential coreutils commands
+CORE_COMMANDS=(
+    "ls"
+    "cp"
+    "mv"
+    "rm"
+    "cat"
+    "echo"
+    "head"
+    "tail"
+    "sort"
+    "uniq"
+    "wc"
+    "date"
+    "whoami"
+    "sha256sum"
+    "base64"
+    "realpath"
+    "timeout"
+    "stat"
+    "dd"
+    "tr"
+)
+
+echo "Checking essential coreutils commands..."
+for cmd in "${CORE_COMMANDS[@]}"; do
+    if ! command -v "$cmd" &> /dev/null; then
+        echo "ERROR: $cmd command not found after installation"
+        exit 1
+    fi
+done
+
+# Display coreutils version
+echo ""
+echo "Coreutils version:"
+ls --version | head -1
+
+# Show package info
+echo ""
+echo "Coreutils package info:"
+dpkg -l | grep coreutils || echo "Package info not available"
+
+echo ""
+echo "GNU coreutils installation completed successfully!"
+echo "Total commands checked: ${#CORE_COMMANDS[@]}"