diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..aa9112d
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+# airodump-ng capture artifacts, if ever run from here
+*.csv
+*.cap
+*.netxml
+*.kismet.*
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a56cce4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,107 @@
+# wifi-deauth-test
+
+A small Tkinter GUI that walks you through deauthenticating **one** client from a
+Wi-Fi network **you own or are explicitly authorized to test**. It is a guided
+front-end for the `aircrack-ng` suite (`airmon-ng`, `airodump-ng`, `aireplay-ng`).
+
+If you just want the result and not the click-flow, `wifite2` and `airgeddon`
+already do all of this.
+
+---
+
+## ⚠️ Responsible use
+
+Sending 802.11 deauthentication frames to a network or client you do not own, or
+do not have **written** permission to test, is illegal in most jurisdictions
+(e.g. the US Computer Fraud and Abuse Act, the UK Computer Misuse Act).
+
+This tool exists to test the resilience of **your own** network, for lab
+exercises, and for learning how the attack works. It targets a single client at a
+time. You are responsible for how you use it.
+
+---
+
+## What it does
+
+A step-by-step wizard:
+
+| Step | Screen | Under the hood |
+|------|--------|----------------|
+| 1 | **Select Wi-Fi card** — lists wireless interfaces, flags which support monitor mode | `iw dev`, `iw <phy> info` |
+| 2 | **Monitor mode** (on confirm) — saves current card state first | `airmon-ng check kill`, then `airmon-ng start <iface>` |
+| 3 | **Scan networks** — 10 s scan, then a table of ESSID / BSSID / channel / signal / encryption | `airodump-ng` → CSV |
+| 4 | **Scan clients** — 15 s scan locked to the chosen BSSID + channel, lists associated client MACs | `airodump-ng --bssid <b> -c <ch>` → CSV |
+| 5 | **Deauth** — **30 s with a live countdown** (auto-stops) or **infinite** (until you click *Stop deauth*) | `aireplay-ng --deauth 0 -a <bssid> -c <client> <mon>` |
+| 6 | **Stop & Reset card** — always visible, any screen | see below |
+
+### Reset behaviour
+
+Before it touches the card, the tool records:
+
+- the interface name and MAC address
+- whether `NetworkManager` was running
+
+**Stop & Reset card** (and closing the window) then:
+
+1. kills any running `airodump-ng` / `aireplay-ng`
+2. `airmon-ng stop <mon>`
+3. renames / sets the interface back to `managed` if needed
+4. restores the original MAC if it changed
+5. `systemctl start NetworkManager`
+
+The card ends up exactly as it was before step 2.
+
+---
+
+## Requirements
+
+- Linux
+- root (`sudo`)
+- `aircrack-ng`, `iw`, `iproute2`, `python3-tk`
+
+```bash
+sudo apt install aircrack-ng iw iproute2 python3-tk
+```
+
+- A Wi-Fi adapter whose driver supports **monitor mode + packet injection**.
+  Many built-in Intel cards inject poorly; `ath9k_htc` (Atheros) and RTL8812AU
+  adapters are the common choices.
+
+---
+
+## Usage
+
+```bash
+sudo python3 wifi_deauth.py
+```
+
+Then follow the wizard. The card is only modified after you confirm the prompt on
+step 1 → 2, and is fully restored by **Stop & Reset card**.
+
+---
+
+## Selftest
+
+The `airodump-ng` CSV parser has a self-check that needs no hardware and no root:
+
+```bash
+python3 wifi_deauth.py --selftest
+```
+
+---
+
+## Limitations
+
+- Scan durations are fixed (10 s / 15 s). Bump `SCAN_NET_SECS` / `SCAN_CLIENT_SECS`
+  at the top of `wifi_deauth.py` if devices are slow to appear.
+- The CSV is parsed by naive comma-splitting; an ESSID that contains a comma can
+  shift columns.
+- WPA3 / 802.11w (protected management frames) makes deauth ineffective — that is
+  expected, not a bug.
+- One client at a time, by design.
+
+---
+
+## Files
+
+- `wifi_deauth.py` — the whole thing: GUI, logic, and selftest.