publish README.md

README.md

@@ -1,2 +1,103 @@
-# eve-watcher
+# Eve Retriever ore-hold watcher (runs on Goliath)
 
+Pings me on my **phone (ntfy)** and with an **on-screen toast (Goliath)** when my
+Retriever's ore hold is full, so I stop AFK-mining and unload/compress.
+
+This runs entirely on **Goliath** (the Windows gaming PC) — Rocky isn't involved,
+it just reuses the same ntfy push app already on my phone.
+
+## Why not just read Eve's log files?
+Eve writes `(combat)` / `(notify)` lines to `Documents\EVE\logs\Gamelogs`, but
+there is **no reliable log line for "ore hold full"** — mining-laser auto-deactivation
+is a client-side event the established mining bots detect by reading the in-game UI,
+not the logs. So this watcher reads the **Ore Hold inventory window** (OCR mode), or
+runs a **yield-based countdown** (timer mode).
+
+## Pick a mode
+| | OCR mode | Timer mode |
+|---|---|---|
+| Accuracy | Reads real fill % | Estimate from yield |
+| Setup | Tesseract + one-time `--snip` | Just enter your m³/min |
+| Fragility | Breaks if you move/close the Ore Hold window or change UI scale | Immune to UI; misses early rock depletion |
+| In-game requirement | Keep the **Ore Hold** window open in a fixed spot | Press Enter when lasers go hot |
+
+Start with **timer mode** to prove delivery in 2 minutes, switch to **OCR** for hands-off.
+
+## Install on Goliath
+1. Install Python 3 (python.org installer — keep "Add to PATH" checked; it includes tkinter).
+2. In this folder:
+   ```
+   pip install -r requirements.txt
+   copy config.ini.example config.ini
+   ```
+3. Edit `config.ini`:
+   - `[ntfy] topic` → pick a private string (e.g. `eve-retriever-7h2k9`). On your
+     phone, open the **ntfy** app → *Add subscription* → enter that same topic.
+   - For **timer mode**: set `[watcher] mode = timer` and `[timer] yield_m3_per_min`
+     to your effective yield (Retriever ≈ 1,000–1,600 m³/min depending on fit/skills).
+   - For **OCR mode**: install Tesseract (`winget install --id UB-Mannheim.TesseractOCR`),
+     then run the region picker (below).
+
+## Test delivery
+```
+python eve_orehold_watcher.py --test
+```
+You should get a phone push **and** a Windows toast. If the toast fails, check
+`winotify` installed; if the push fails, check the topic matches your phone subscription.
+
+## OCR calibration (one time)
+In-game, open your **Ore Hold** so the `12,345 / 22,000 m³` text is visible and parked
+in a fixed spot. Then:
+```
+python eve_orehold_watcher.py --snip
+```
+Drag a tight box around just the `current / capacity m³` numbers; it saves the region
+to `config.ini`. (Esc cancels.)
+
+## Run it
+```
+python eve_orehold_watcher.py
+```
+- OCR mode: leave it running; it re-arms after you unload (hold drops below `reset_pct`).
+- Timer mode: press Enter each time you start a fresh hold.
+
+## Autostart (optional)
+Task Scheduler → Create Task → Trigger *At log on* → Action: `pythonw.exe` with argument
+`<full path>\eve_orehold_watcher.py` → Start in: this folder. `pythonw` runs it without a
+console window.
+
+## Tuning
+All in `[watcher]` of `config.ini`: `alert_pct` (default 95), `poll_secs` (10),
+`reset_pct` (50), `cooldown_secs` (120).
+
+## Notify a fleetmate (e.g. Adam) → Discord
+"Ping Adam to compress when his hold is nearly full" can't be done from ESI — **cargo/ore-hold
+fill is not exposed by any API.** The detection has to run on **Adam's own PC**. So:
+1. Adam installs this watcher on his machine (`setup.ps1` / `pip install -r requirements.txt`).
+2. In his `config.ini` set his ship's hold (**Venture ore/gas hold = 5,000 m³**), `alert_pct = 90`,
+   and a **`[discord] webhook`** (a webhook for your shared channel) with `mention = <@his-id>`.
+3. **OCR mode:** `--snip` his Venture's **Ore Hold** window. **Timer mode:** set his
+   `yield_m3_per_min`.
+4. When his hold passes 90%, the watcher posts **"compress now"** to your Discord channel
+   (and/or his phone if he also sets `[ntfy] topic`).
+- The watcher fans out to **ntfy (phone) + Windows toast + Discord** — set any/all.
+
+## Combat watcher — rats spawned / being tackled (eve_combat_watcher.py)
+EVE has no API for in-space NPCs or being tackled — but it **logs combat to disk**. This
+companion tails `Documents/EVE/logs/Gamelogs` and alerts (ntfy + toast + Discord) on:
+- **Incoming damage** ("rats?") — `(combat) … from …` lines.
+- ⚠ **Tackled / EWAR'd** — `(notify)` warp-scramble/disrupt/jam/web/neut — top priority,
+  no cooldown (if you can't warp, you need to know instantly).
+
+Run: `python eve_combat_watcher.py` (`--test` fires one alert). Reads the same `config.ini`
+(`[combat]` section). Reading the log is legit — it never touches the game. Pair with
+in-game **Drone Settings = Aggressive** so drones auto-engage rats.
+
+## Other holds (e.g. Pioneer gas hold)
+This watcher is hold-agnostic — it works for any "current / capacity m³" readout.
+- **Pioneer gas/specialized hold = 8,000 m³.** For **timer mode**, set
+  `[timer] ore_hold_m3 = 8000` and your gas yield (Gas Cloud Scoop I = 10 m³ / 30 s = 20
+  m³/min per scoop; ×2 with Gas Cloud Harvesting II → ~40 m³/min). For **OCR mode**, just
+  `--snip` the Pioneer's **Gas Hold** window instead of the ore hold.
+- Keep separate `config.ini` copies (one per ship) if you switch between the Retriever and
+  the Pioneer.