diff --git a/README.md b/README.md
index a258b0e..2b73821 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # LinTunes
 
-[screenshot]
+![LinTunes](screenshot.png)
 
 an mp3 library manager and player for linux. Absolutely no guarantees, if it wrecks your itunes library or wipes your
 harddrive that's on you (maybe just have your LLM of choice review the
@@ -39,37 +39,59 @@ even some tracks I got from napster all the way back in 2000 (I have since
 paid for!!)
 
 
-## Quickstart
+## Installing
+
+LinTunes needs four Python packages — **PyQt6** (with its QtMultimedia module),
+**mutagen**, **numpy**, **requests** — plus the **FFmpeg codecs** for Qt
+Multimedia so audio actually plays. Nothing compiles; get the deps whichever way
+fits your distro:
+
+- **pip** — simplest where your distro allows it; also puts a `lintunes` command
+  in `~/.local/bin`:
+  ```sh
+  pip install -e .
+  ```
+- **Debian/Ubuntu** — system pip is locked down (the `externally-managed-environment`
+  / PEP 668 error), so install the deps from apt and skip pip entirely:
+  ```sh
+  sudo apt install python3-pyqt6 python3-pyqt6.qtmultimedia \
+                   python3-mutagen python3-numpy python3-requests
+  ```
+  (If `python3-pyqt6.qtmultimedia` isn't found, `apt search python3-pyqt6` and
+  grab the multimedia one.) There's no `lintunes` command this way — run it with
+  `python3 -m lintunes.main`.
+- **venv** — isolated:
+  ```sh
+  python3 -m venv .venv && .venv/bin/pip install -e .
+  ```
+  Run with `.venv/bin/lintunes`. One caveat: the dock launcher (see *App icon*)
+  uses the *system* python, which can't see a venv's packages — so for the icon
+  to work, edit the installed `lintunes.desktop`'s `Exec=` line to the absolute
+  venv path (`…/lintunes/.venv/bin/lintunes %F`).
+
+**You never strictly need pip or the `lintunes` command.** As long as those four
+deps import, `python3 -m lintunes.main` from the checkout runs the app — which is
+exactly what the desktop launcher does. The FFmpeg codecs come from
+`qt6-qtmultimedia` built with ffmpeg (Fedora: RPM Fusion; Debian/Ubuntu: pulled in
+by `python3-pyqt6.qtmultimedia`). Without them the UI runs but tracks won't play.
+
+## Running it
 
 ```sh
-pip install -e .          # PyQt6, mutagen, numpy, requests
-# one-time import from iTunes (XML from iTunes 12.x: File > Library > Export Library)
-lintunes --import-xml "iTunes Library.xml" \
-         --music-root "/path/to/iTunes Media" \
-         --data-dir /path/to/library-data --save-config
-lintunes                  # run the app
+# one-time import from iTunes (XML: File ▸ Library ▸ Export Library in iTunes 12.x)
+python3 -m lintunes.main --import-xml "iTunes Library.xml" \
+    --music-root "/path/to/iTunes Media" \
+    --data-dir /path/to/library-data --save-config
+python3 -m lintunes.main            # run the app (uses the saved config)
 ```
 
-
-### Running it
-
-The `lintunes` command only exists after `pip install -e .`, and it lives in
-`~/.local/bin`, so that has to be on your `PATH` (it is by default on most
-distros). If `lintunes` isn't found, you can always run it straight from this
-checkout without installing — from the project directory:
-
-```sh
-python3 -m lintunes.main   # same thing the desktop launcher runs
-```
-
-Fedora/Debian note: you need the FFmpeg codecs for Qt Multimedia
-(`qt6-qtmultimedia` with ffmpeg, usually via RPM Fusion / regular apt).
+(Installed with pip? Type `lintunes` instead of `python3 -m lintunes.main`.)
 
 LinTunes looks best with **Century Gothic** installed (`~/.local/share/fonts/`);
 if it's missing, you'll be asked to pick a font on first run.
 
-The desktop launcher runs `lintunes` with no `--data-dir`, so it always uses
-whatever is saved in `~/.config/lintunes/config.json`. Point that config wherever
+The desktop launcher runs LinTunes with no `--data-dir`, so it always uses
+whatever is saved in `~/.config/lintunes/config.json` — point that config wherever
 you want and the dock icon follows.
 
 ## Running on a second machine (Syncthing)
@@ -84,15 +106,15 @@ shared folder — you never edit anything inside the library to move it.
 new machine you just tell LinTunes where the synced folder landed:
 
 ```sh
-# 1. get the code
+# 1. get the code, then install the deps (see "Installing" above: pip / apt / venv)
 git clone ssh://git@git.autonomic.zone:2222/trav/lintunes.git
-cd lintunes && pip install -e .
+cd lintunes
 
 # 2. let Syncthing finish replicating the music folder, then point the config at
 #    THIS machine's paths and launch — no re-import, the data is already synced:
-lintunes --data-dir  "/path/to/synced/music/lintunes" \
-         --music-root "/path/to/synced/music/iTunes Media" \
-         --save-config
+python3 -m lintunes.main --data-dir  "/path/to/synced/music/lintunes" \
+                         --music-root "/path/to/synced/music/iTunes Media" \
+                         --save-config
 
 # 3. install the launcher + icon, then pin it (see "App icon" below)
 bash packaging/install-desktop.sh
diff --git a/screenshot.png b/screenshot.png
new file mode 100644
index 0000000..22e491b
Binary files /dev/null and b/screenshot.png differ