diff --git a/README.md b/README.md
index 5d4332e..d104842 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,53 @@
-# wagenet-ip-ban-list
+# WageNet IP Ban List
 
-The IP ban list generated from threat detection on the WageNet.
\ No newline at end of file
+A small repository that publishes the current WageNet IP blocklist. The list is generated from WageNet threat detection and exported as a flat text file for easy consumption by firewalls, web servers, and other tooling.
+
+## What’s in this repo
+- `banned.txt`: newline‑separated IPv4 addresses to block. Comment lines start with `#` and may include a timestamp and count.
+- `update.sh`: helper script that copies a source list into the repo, commits, and pushes updates.
+- `LICENSE`: license for this repository (GPL‑3.0).
+
+## File format
+- Plain text, UTF‑8.
+- Lines beginning with `#` are comments/metadata.
+- Each non‑comment line contains a single IPv4 address.
+
+Example:
+```
+# WageNet IP Blocklist - Last Updated 2025-08-17 00:00:01
+# 130 IPs.
+203.0.113.7
+198.51.100.24
+...
+```
+
+## How updates happen
+The blocklist is periodically generated by WageNet and published by committing a fresh `banned.txt`. The included `update.sh` script can be used to automate this from the system that produces the list.
+
+Script defaults (override with flags):
+- `-s`: source file path (default: `/var/www/html/banned.txt`)
+- `-d`: git repository directory (default: `/git/repository`)
+- `-f`: destination filename inside the repo (default: `banned.txt`)
+
+Example usage:
+```
+./update.sh -s /var/www/html/banned.txt -d /git/repository -f banned.txt
+```
+
+To automate, add a cron entry on the generating host (example runs hourly):
+```
+0 * * * * /path/to/update.sh -s /var/www/html/banned.txt -d /git/repository -f banned.txt >/tmp/wagenet-update.log 2>&1
+```
+
+## Using the blocklist
+- Ingest the file directly in your tooling (e.g., fail2ban, WAF, or custom scripts).
+- Convert to firewall rules (iptables/nftables) with a simple wrapper that reads each line and applies a drop rule.
+- For web servers (nginx/apache), generate `deny` directives from the list.
+
+Note: Always validate the list for your environment and merge with any allowlists you maintain.
+
+## Contributing
+`banned.txt` is generated content. Please open issues or PRs for improvements to `update.sh`, documentation, or format clarifications rather than manual edits to the list.
+
+## License
+Distributed under the GPL‑3.0 license. See `LICENSE` for details.