From adc8a5dec94874bf05b6d1e802ce148ff596b09f Mon Sep 17 00:00:00 2001
From: dev <dev@local>
Date: Mon, 1 Jun 2026 17:40:18 -0500
Subject: [PATCH] docs: README with install, usage, and self-test instructions

---
 README.md | 45 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 43 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 715dfa1..b455273 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,46 @@
 # Torn Attribute Training Tracker
 
-A userscript for [torn.com](https://www.torn.com) that shows a floating dialog on the gym page with your attribute, target, and ETA.
+A userscript for [torn.com](https://www.torn.com) that shows a floating dialog on the gym page with your current attribute, target, rate of gain, and an ETA to the target.
 
-_(installation and usage coming once tasks complete)_
+## Install
+
+1. Install [Tampermonkey](https://www.tampermonkey.net/) (or Violentmonkey / Greasemonkey).
+2. Open `torn-attribute-tracker.user.js` in your editor, copy its contents.
+3. In Tampermonkey, click the dashboard → **+** (Create new script) → paste → save.
+4. Visit `https://www.torn.com/gym.php`. The dialog appears in the bottom-right.
+
+## Use
+
+- Type a target value in the **Target** field, or pick a milestone from the dropdown.
+- The dialog updates live as you train.
+- Drag the header to reposition. Click **Above training UI** to anchor above the gym form. Click **Float free** to drag again.
+- The **✕** closes the dialog for the current page session; it returns on next visit.
+
+Targets, dialog position, and the 30-day train history are stored in `localStorage`.
+
+## Self-test
+
+Load the script with `#tat-test` in the URL:
+
+```
+https://www.torn.com/gym.php#tat-test
+```
+
+Open the browser console; you'll see `[tat] self-test results:` followed by `OK …` / `FAIL …` lines.
+
+## Tests
+
+```
+npm install   # no deps; node:test ships with Node 18+
+npm test
+```
+
+## Files
+
+- `torn-attribute-tracker.user.js` — the script you install in Tampermonkey.
+- `src/pure.js`, `src/store.js`, `src/dom.js`, `src/interceptor.js`, `src/ui.js`, `src/main.js` — source split for testability; the user-facing file is the bundle in step 11.
+- `tests/` — Node test runner (`node --test`).
+
+## Notes
+
+The DOM scraper and request interceptor are best-effort matches for the current Torn gym page. If Torn updates the markup, you may need to adjust the selectors in `src/dom.js` and re-bundle by copying the new source into the embedded section in `torn-attribute-tracker.user.js`.