Add install.sh, run.sh uses the venv when present

install.sh creates a --system-site-packages venv (so it can still see
the system-installed PyGObject bindings, which pip can't build
reliably) and pip-installs the rest of requirements.txt into it.
Checks for PyGObject (GTK4 + libadwaita) and tesseract up front and
prints per-distro package hints if either is missing, rather than
failing deep into pip install. run.sh now prefers .venv/bin/python3
when it exists, falling back to system python3 otherwise. README gets
an Install section describing this.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -18,13 +18,21 @@ A companion app that mostly automates **IRON NEST: Heavy Turret Simulator** for
 - **Tracks the battle.** A second screenshot of the field log marks units destroyed and folds in newly-spotted contacts, merging with what's already known instead of duplicating it.
 - **Plans strikes.** Drop a strike anywhere on the map and pick a shell to preview its blast radius before committing.
 
+## Install
+
+```bash
+./install.sh
+```
+
+Sets up a venv for the Python deps (Pillow, numpy, pytesseract) and checks for the system packages that pip can't install: GTK4/libadwaita bindings and tesseract. If either is missing it prints the package names for your distro and stops, install those and re-run.
+
 ## Run
 
 ```bash
 ./run.sh
 ```
 
-GTK apps with this app ID are single-instance, if a run gets killed uncleanly it can leave a zombie registered on D-Bus and silently no-op the next launch. If `./run.sh` seems to do nothing, `pgrep -af ironnest_assist` and kill any stragglers first.
+Uses the venv from `install.sh` if one exists, otherwise falls back to system `python3`. GTK apps with this app ID are single-instance, if a run gets killed uncleanly it can leave a zombie registered on D-Bus and silently no-op the next launch. If `./run.sh` seems to do nothing, `pgrep -af ironnest_assist` and kill any stragglers first.
 
 ## Stack
 

install.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Set up FeNigma: a venv for the pip deps, plus checks for the system
+# packages that can't come from pip (GTK4/libadwaita bindings, tesseract).
+set -euo pipefail
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
+missing=()
+
+python3 -c "import gi; gi.require_version('Gtk', '4.0'); gi.require_version('Adw', '1')" 2>/dev/null \
+    || missing+=("PyGObject (GTK4 + libadwaita bindings)")
+
+command -v tesseract >/dev/null 2>&1 || missing+=("tesseract")
+
+if [ "${#missing[@]}" -gt 0 ]; then
+    echo "Missing system packages:"
+    for m in "${missing[@]}"; do echo "  - $m"; done
+    echo
+    echo "These come from your distro's package manager, not pip. For example:"
+    echo "  Fedora:         sudo dnf install python3-gobject gtk4 libadwaita tesseract"
+    echo "  Debian/Ubuntu:  sudo apt install python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 tesseract-ocr"
+    echo "  Arch:           sudo pacman -S python-gobject gtk4 libadwaita tesseract"
+    echo
+    echo "Install those, then re-run this script."
+    exit 1
+fi
+
+# --system-site-packages so the venv can still see the system-installed
+# PyGObject above (pip can't build it reliably) while everything else in
+# requirements.txt installs normally into the venv.
+python3 -m venv --system-site-packages .venv
+.venv/bin/pip install --upgrade pip
+.venv/bin/pip install -r requirements.txt
+
+echo
+echo "Done. Run the app with ./run.sh"

run.sh

@@ -1,5 +1,9 @@
 #!/usr/bin/env bash
-# Launch IronNest Assist.
+# Launch FeNigma.
 set -euo pipefail
 cd "$(dirname "${BASH_SOURCE[0]}")"
-exec env PYTHONPATH=src python3 -m ironnest_assist.app
+
+PYTHON=python3
+[ -x .venv/bin/python3 ] && PYTHON=.venv/bin/python3
+
+exec env PYTHONPATH=src "$PYTHON" -m ironnest_assist.app