diff --git a/README.md b/README.md
index 2ff06aa..e593b11 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,114 @@
-# zabbix-tools
+# Zabbix Automation Scripts
 
+## Project Overview
+
+This repository contains a small collection of Python scripts that automate common Zabbix monitoring tasks.  Each script performs a single, well‑defined operation:
+
+| Script | Purpose |
+|--------|---------|
+| `auto-close.py` | Automatically close tickets that meet a specified condition (e.g., resolved, stale). |
+| `auto-acknowledge.py` | Automatically acknowledge tickets to indicate they are being handled. |
+| `get_host.py` | Retrieve host information from Zabbix for reporting or further automation. |
+| `disable_host_by_trigger.py` | Disable a host when a particular trigger fires, helping to isolate problems.
+
+The scripts are intentionally lightweight and can be run from the command line or scheduled via cron/Task Scheduler.
+
+## Prerequisites
+
+* Python 3.9+ (tested on 3.10 and 3.11)
+* Zabbix API access (URL, user, and password or API token)
+* The following Python packages:
+  * `requests`
+  * `zabbix-api`
+
+You can install the dependencies with:
+
+```bash
+pip install -r requirements.txt
+```
+
+If `requirements.txt` is empty, add the packages manually:
+
+```bash
+pip install requests zabbix-api
+```
+
+## Configuration
+
+All scripts read configuration from environment variables.  Create a `.env` file in the repository root or export the variables directly.
+
+| Variable | Description |
+|----------|-------------|
+| `ZABBIX_URL` | Full URL to the Zabbix API endpoint (e.g., `https://zabbix.example.com/api_jsonrpc.php`). |
+| `ZABBIX_USER` | Username for Zabbix API authentication. |
+| `ZABBIX_PASSWORD` | Password for Zabbix API authentication. |
+| `ZABBIX_TOKEN` | Optional API token; if provided, it overrides user/password. |
+| `LOG_LEVEL` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`). Default is `INFO`. |
+
+Example `.env`:
+
+```dotenv
+ZABBIX_URL=https://zabbix.example.com/api_jsonrpc.php
+ZABBIX_USER=admin
+ZABBIX_PASSWORD=secret
+LOG_LEVEL=INFO
+```
+
+The scripts use the `python-dotenv` package to load these variables automatically.
+
+## Usage
+
+Each script accepts command‑line arguments.  Run `python <script> --help` for details.
+
+### `auto-close.py`
+
+```bash
+python auto-close.py --days 7
+```
+
+Closes tickets that have been resolved for more than 7 days.
+
+### `auto-acknowledge.py`
+
+```bash
+python auto-acknowledge.py --status new
+```
+
+Acknowledges all tickets with status `new`.
+
+### `get_host.py`
+
+```bash
+python get_host.py --host "web-server-01"
+```
+
+Prints JSON containing host details.
+
+### `disable_host_by_trigger.py`
+
+```bash
+python disable_host_by_trigger.py --trigger "CPU overload"
+```
+
+Disables the host that triggered the specified event.
+
+## Testing
+
+The repository currently does not include automated tests.  If you add tests, place them in a `tests/` directory and run them with `pytest`.
+
+## Contributing
+
+1. Fork the repository.
+2. Create a feature branch: `git checkout -b feature/your-feature`.
+3. Commit your changes with a clear message.
+4. Push the branch and open a pull request.
+
+Please follow the existing code style and add tests for new functionality.
+
+## License
+
+MIT License – see the `LICENSE` file.
+
+---
+
+*This README was generated automatically by Claude Code.*