fix(launcher): survive the GitHub-ZIP download (kills the "(null)" error)

A GitHub ZIP + macOS unzip strips the executable flag and adds a quarantine
flag, so double-clicking the freshly-downloaded VolScope.app failed with
'…does not have permission to open "(null)"'. This is a hard limitation of
shipping a committed .app via ZIP — not fixable by the bundle alone.

Fix the real flow instead:
- Start VolScope.command now runs the bootstrap via `bash` (bash reads a
  script regardless of its executable flag), so the FIRST launch works from a
  stripped ZIP.
- The bootstrap self-heals on that first run: chmod +x on its own launchers +
  xattr -dr com.apple.quarantine on the bundle, so EVERY launch after the
  first is a normal double-click on the icon.
- The bootstrap also drops a sitecustomize shim into the new venv before pip
  runs, so the install can't die on Anaconda Pythons (their sys.version string
  breaks platform.python_implementation() mid-install).

README rewritten into a dead-simple, explained two-step pipeline: a one-time
"type `bash ` + drag Start VolScope.command into Terminal" setup (with the WHY
— macOS strips the run-flag from ZIPs), then double-click the icon forever
after. Honest: this is not zero-install, but it is one-time and bulletproof.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: 2 people

README.md

@@ -21,7 +21,7 @@ a vol desk reads: IV rank, a volatility cone, a time-travelling term structure,
 **own** Black-Scholes solver, **never** Yahoo's IV. The volatility screen you'd
 otherwise rent from Bloomberg, running in a browser tab on your own machine.
 
-> **▶ Get started in one click:** download the ZIP, double-click **`VolScope.app`** — no terminal, no commands. [Full steps ↓](#run-volscope--just-double-click)
+> **▶ Get started:** download the ZIP → one quick one-time setup → then it's just a double-click on the **VolScope** icon. [How ↓](#-run-volscope)
 
 ## Why VolScope
 
@@ -50,25 +50,32 @@ machine. What makes it strong:
   estimator is property-tested, and analytics never crash the UI — bad
   input returns nothing, not an exception.
 
-## Run VolScope — just double-click
+## ▶ Run VolScope
 
-**No terminal. No commands.** Download, unzip, double-click **`VolScope.app`**.
+Download the ZIP from GitHub and unzip it — you'll get a `volscope-…` folder
+with a **VolScope** app icon inside. It runs in two small steps: a one-time
+setup, then a double-click forever after.
 
-1. On the [repo page](https://github.com/SchoenTom/volscope): **Code ▸ Download ZIP**, then unzip.
-2. Double-click **`VolScope.app`**. The first launch quietly builds a private
-   environment and fetches a starter universe (~2 min, one time only); every
-   launch after that opens in a couple of seconds.
-3. VolScope opens in its own clean window. Quit it like any app (Dock → Quit)
-   to stop the local server.
+> **Why a one-time step?** macOS strips the "this file may run" flag from
+> anything downloaded as a ZIP (a built-in security default — nothing to do with
+> VolScope). So the **first** launch goes through Terminal once to install
+> VolScope's private environment. That same step re-enables the flag, so from
+> then on the **`VolScope.app`** icon opens with a normal double-click.
 
-> **First time only — macOS Gatekeeper.** Because the app isn't code-signed,
-> macOS asks once: **right-click `VolScope.app` → Open → Open**. A normal
-> double-click works ever after. *(If Finder still refuses, the included
-> `Start VolScope.command` does the exact same thing.)*
+### ① First launch — once (~2 min)
 
-Needs **Python 3.11+** installed on your Mac — the app builds its own isolated
-environment and never touches your system Python. Everything runs locally; no
-account, no subscription, no data leaves your machine.
+1. **Download & unzip.** On the [repo page](https://github.com/SchoenTom/volscope): **Code ▸ Download ZIP**, then double-click the downloaded ZIP to unzip it.
+2. **Open Terminal.** Press **⌘ + Space**, type `Terminal`, press **Enter**.
+3. In the Terminal window type **`bash `** (the word *bash* followed by one space) — then **drag the `Start VolScope.command` file** from the unzipped folder onto the Terminal window. Its full location fills in for you.
+4. Press **Enter**. VolScope installs its environment, fetches a starter
+   universe, and opens. ☕ (~2 minutes — only this first time.)
+
+### ② Every time after that
+
+Just **double-click `VolScope.app`** 🟢 — it opens in its own clean window in a
+couple of seconds. Quit it like any app (**Dock → Quit**) to stop the local server.
+
+> *Requires **Python 3.11+** on your Mac (free from [python.org](https://www.python.org/downloads/)). VolScope builds its own isolated environment and never touches your system Python. Everything runs locally — no account, no subscription, no data ever leaves your machine.*
 
 <details>
 <summary><b>Developer / command-line setup</b></summary>

Start VolScope.command

@@ -1,5 +1,11 @@
 #!/bin/bash
-# Fallback launcher — only needed if double-clicking VolScope.app is blocked.
-# Runs the exact same thing VolScope.app does.
+# First-run launcher for VolScope.
+#
+# A GitHub ZIP download strips the "executable" flag from files, so the very
+# first launch can't be a double-click — it goes through this script once
+# (run it with: bash "Start VolScope.command"). It runs the app's bootstrap
+# via `bash`, which doesn't need the executable flag, and the bootstrap then
+# re-sets that flag so every launch AFTER this one is a normal double-click on
+# VolScope.app.
 DIR="$(cd "$(dirname "$0")" && pwd)"
-exec "$DIR/VolScope.app/Contents/MacOS/VolScope"
+exec bash "$DIR/VolScope.app/Contents/MacOS/VolScope"

VolScope.app/Contents/MacOS/VolScope

@@ -20,6 +20,16 @@ APP_DIR="$(cd "$MACOS_DIR/../.." && pwd)"          # …/VolScope.app
 REPO="$(cd "$APP_DIR/.." && pwd)"                  # repo root
 RES_DIR="$APP_DIR/Contents/Resources"
 
+# ── Self-heal the download (so the icon is double-clickable afterwards) ──
+# A GitHub ZIP + macOS unzip strips the "executable" flag and adds a
+# quarantine flag, which makes a fresh double-click fail with
+# '…does not have permission to open "(null)"'. Re-set both here, so AFTER
+# this first (Terminal-launched) run, double-clicking VolScope.app just works.
+chmod +x "$MACOS_DIR/VolScope" 2>/dev/null || true
+[ -f "$REPO/Start VolScope.command" ] && chmod +x "$REPO/Start VolScope.command" 2>/dev/null || true
+xattr -dr com.apple.quarantine "$APP_DIR" 2>/dev/null || true
+xattr -dr com.apple.quarantine "$REPO/Start VolScope.command" 2>/dev/null || true
+
 LOG_DIR="$HOME/Library/Logs/VolScope"
 mkdir -p "$LOG_DIR"
 SETUP_LOG="$LOG_DIR/setup.log"
@@ -75,6 +85,21 @@ if [ ! -x "$STREAMLIT" ]; then
   {
     echo "== $(date) VolScope setup =="
     "$PY" -m venv "$VENV"
+    # Bulletproof pip on Anaconda Pythons: their sys.version carries an extra
+    # "| packaged by Anaconda |" segment that breaks
+    # platform.python_implementation() mid-install. A tiny sitecustomize shim
+    # normalises it for every interpreter start (pip's process included).
+    VSITE="$("$VENV/bin/python" -c 'import site; print(site.getsitepackages()[0])' 2>/dev/null)"
+    if [ -n "$VSITE" ]; then
+      printf '%s\n' \
+        'import sys as _s' \
+        'if "Anaconda" in _s.version and _s.version.count("|") >= 2:' \
+        '    _p = _s.version.split("|")' \
+        '    if len(_p) >= 3:' \
+        '        try: _s.version = _p[0].strip() + " " + " ".join(x.strip() for x in _p[2:])' \
+        '        except Exception: pass' \
+        > "$VSITE/sitecustomize.py"
+    fi
     "$VENV/bin/python" -m pip install --upgrade pip
     "$VENV/bin/python" -m pip install -r "$REPO/requirements.txt"
   } >>"$SETUP_LOG" 2>&1