diff --git a/apt/README.md b/apt/README.md
index 247490d..2e588bb 100644
--- a/apt/README.md
+++ b/apt/README.md
@@ -1,3 +1,73 @@
+# System Update Automation
+
+This project uses **Ansible** to automate system updates across multiple servers and infrastructure components.
+
+## Overview
+
+This playbook updates, upgrades, and cleans up packages on all managed hosts. It's designed to work with a mixed infrastructure environment including:
+
+- **Hetzner** cloud servers
+- **Proxmox** virtualization infrastructure (PVE, PBS, PDM nodes)
+- **LXC** containers (instances across the 10.0.0.100–10.0.0.199 range)
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `inventory.ini` | Defines all hosts organized by group (hetz, prox, lxc) |
+| `playbook.yml` | Contains the update tasks to run on all hosts |
+| `run-playbook.sh` | Bash script to execute the playbook safely |
+
+## Prerequisites
+
+- **Ansible** installed on your control machine
+- **SSH access** configured to all hosts listed in `inventory.ini`
+- SSH keys or password authentication set up for the `root` user on each host
+
+## Usage
+
+### 1. Make the Script Executable
+
+Before running the playbook, you must make the script executable:
+
 ```bash
-ansible-playbook -i ../inventory.ini playbook.yml
-```
\ No newline at end of file
+chmod +x run-playbook.sh
+```
+
+### 2. Run the Playbook
+
+Execute the script:
+
+```bash
+./run-playbook.sh
+```
+
+The script will:
+- Verify that both `inventory.ini` and `playbook.yml` exist
+- Run the Ansible playbook to update all hosts
+- Exit with an error if any required file is missing
+
+## What the Playbook Does
+
+The playbook runs on **all hosts** and performs:
+
+1. **Update cache** — Refreshes the package list
+2. **Full upgrade** — Upgrades all installed packages to their latest versions
+3. **Autoremove** — Removes unused dependencies
+
+This ensures all systems stay current with the latest security patches and updates.
+
+## Inventory Structure
+
+```
+[hetz]              # Hetzner cloud server
+[prox]              # Proxmox nodes (PVE, PBS, PDM)
+[lxc]               # LXC container hosts
+```
+
+## Notes
+
+- The script uses `set -e` to exit immediately if any command fails
+- SSH must be configured to allow root login on all target hosts
+- Consider running this during a maintenance window to minimize service disruption
+- Review the playbook before first use to ensure it meets your security and operational requirements