diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5b044b8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,56 @@
+# AMD TUF Power Monitor
+
+Two small utilities live here:
+
+- `amd-monitor.sh` – a one‑second loop that reads AMD APU/dGPU telemetry from `/sys/class/hwmon`, prints a live dashboard, and appends the readings to `power_log.csv`.
+- `plot_power.py` – turns the CSV log into a bar + line chart so you can visualize power draw and temperatures after a capture session.
+
+The scripts were built for an ASUS TUF laptop running Debian 13, but they should work on any recent AMD system that exposes the same hwmon files.
+
+## Requirements
+
+- Bash (already on most Linux installs).
+- Read access to the hwmon entries for your APU and GPU. On some systems you need to run the script with `sudo` or add yourself to the `video` group.
+- Python 3.9+ with `pandas` and `matplotlib` (`pip install pandas matplotlib`) for plotting.
+
+## Usage Flow
+
+1. **Collect live telemetry**
+   ```bash
+   chmod +x amd-monitor.sh
+   ./amd-monitor.sh
+   ```
+   - The script clears the terminal and prints APU/GPU wattage, temperatures, and total power every second.
+   - Each sample is appended to `power_log.csv` as `timestamp,apu_w,gpu_w,total_w,apu_temp,gpu_temp`.
+   - The file is capped at the most recent 500 lines; tweak `MAX_LINES` if you want longer captures.
+
+2. **Adjust sensor paths if needed**
+   - Edit the `APU_HWMON` and `GPU_HWMON` variables near the top of `amd-monitor.sh` so they point to the correct `/sys/class/hwmon/...` folders on your machine.
+   - You can also change `INTERVAL` for faster/slower sampling and `LOGFILE` if you want a different CSV name.
+
+3. **Plot the results**
+   ```bash
+   python3 plot_power.py
+   ```
+   - The script reads `power_log.csv` (assumed to be headerless), down-samples if there are more than ~200 records, and saves `power_graph.png`.
+   - Power traces are displayed as grouped bars (APU, GPU, total) while temperatures are overlaid as dashed lines on a secondary axis.
+
+## Tips
+
+- Keep `amd-monitor.sh` running while you stress the system (games, benchmarks, etc.), then stop it with `Ctrl+C` before plotting.
+- If you need to log multiple sessions, rename or move `power_log.csv` between runs so plots only cover the period you care about.
+- Want live graphing or more metrics? Extend the CSV schema and the plotting script—the code is intentionally short and hackable.
+
+## Forgejo workflow
+
+A Forgejo workflow (`.forgejo/workflows/power-graph.yml`) automates the chart generation whenever `power_log.csv` changes on the `master` branch.
+
+What it does:
+
+1. Runs on a self-hosted runner because it needs local hwmon logs and Python packages.
+2. Manually clones the repo with a read token stored in `secrets.PAT_READ_REPO`.
+3. Installs Python (via `apt`), prepares a virtualenv, and pulls `pandas` + `matplotlib`.
+4. Executes `python plot_power.py`, producing `power_graph.png`.
+5. Uploads the PNG as a Forgejo artifact (`power-graph`), so you can download the rendered plot from the workflow page.
+
+To use it, push an updated `power_log.csv` to `master`, wait for the workflow to finish, then grab the artifact from the run summary. Update the workflow if your runner already has Python or if you want different triggers/retention.