Make the setup wizard do the work, and correct the macOS launch advice

The wizard explained the workflow but performed none of it, which made it a
tour rather than setup. Each step now previews a real operation against the
real library and offers to run it: clean up tags, collapse duplicate copies,
file everything by genre and write the playlists, and gather tracks that need
Mixed In Key into 'To Be Processed'. Every step is skippable and shows counts
before it touches anything, and the run is wrapped in a testing session by
default so a first pass can be undone in one go.

Also corrects the macOS instructions, which were wrong. Approving the app in
System Settings is sufficient; clearing the quarantine flag is not needed. The
proof is that a still-fully-quarantined copy (453 flagged files) runs fine once
approved. The earlier diagnosis mistook the symptom: a blocked launch leaves a
process parked in dyld, and opening the app again just fronts that stuck copy
instead of starting a working one, so it looks like approval did nothing. The
fix is to quit the bouncing icon and open it again.

The first-run helper script is therefore removed - it addressed a problem that
was not the problem, and told people to run a command they do not need.

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

Author: sparkly-quasar

.github/workflows/release.yml

@@ -89,19 +89,17 @@ jobs:
             ## Installing
 
             **macOS** — the app is signed ad-hoc, not notarised (notarising needs a
-            paid Apple Developer account). macOS therefore quarantines every file
-            inside the bundle on download. Approving the app in System Settings only
-            clears the outer one, so it will **bounce in the Dock and never open a
-            window** until the flag is cleared from the whole bundle.
+            paid Apple Developer account), so macOS blocks the first launch.
 
-            Unzip, then either double-click `Sortero-first-run.command` (included), or
-            run once:
+            1. Drag `Sortero.app` where you want it; Applications is fine.
+            2. Open it once — macOS refuses, and it may bounce in the Dock with no
+               window.
+            3. **System Settings → Privacy & Security**, scroll to Security, click
+               **Open Anyway**.
+            4. **Quit the bouncing icon if it's still there**, then open it again.
 
-            ```
-            xattr -dr com.apple.quarantine /Applications/Sortero.app
-            ```
-
-            Then open it normally. Only needed once per download.
+            Step 4 matters: the blocked launch leaves a stuck process behind, and
+            opening the app again just brings that one to the front. Once per download.
 
             **Windows** — unzip and run `Sortero.exe`. SmartScreen may warn about an
             unknown publisher; choose More info → Run anyway.

README.md

@@ -122,24 +122,21 @@ from the [Releases page](../../releases):
 | Windows | `Sortero-windows-x86_64.zip` |
 | Linux | `Sortero-linux-x86_64.zip` |
 
-### macOS: clear the quarantine flag first
+### macOS: first launch
 
 Builds are signed ad-hoc, not notarised — notarising requires a paid Apple
-Developer account. macOS stamps a quarantine flag on the app **and on every one
-of the ~450 files inside it** when you download the zip. Approving the app in
-System Settings only clears the outer bundle, so the dynamic loader stalls on
-the nested libraries: **the app bounces in the Dock and no window ever appears.**
-Right-click → Open does not fix this.
-
-Unzip, then either double-click the included `Sortero-first-run.command`, or run:
-
-```bash
-xattr -dr com.apple.quarantine /Applications/Sortero.app
-```
-
-Then open Sortero normally. Only needed once per download. If Sortero is in
-`/Applications`, macOS may ask permission before another program can modify apps
-there — approve it, or run the app from `~/Downloads` instead.
+Developer account — so macOS blocks the first launch.
+
+1. Drag `Sortero.app` wherever you want it; Applications is fine.
+2. Open it once. macOS refuses, and the icon may bounce in the Dock without a
+   window appearing.
+3. **System Settings → Privacy & Security**, scroll to Security, click
+   **Open Anyway** next to Sortero.
+4. **Quit the bouncing icon if it's still there**, then open Sortero again.
+
+Step 4 matters: the blocked launch leaves a stuck process behind, and while it's
+running, opening the app again just brings that stuck copy to the front rather
+than starting a working one. Only needed once per download.
 
 **Windows** — SmartScreen may warn about an unknown publisher; More info → Run anyway.
 **Linux** — needs Tk (`apt install python3-tk`).

build/Sortero-first-run.command

@@ -96,11 +96,6 @@ def main():
             arch = "-".join(arches) or "unknown"
         zip_path = os.path.join(DIST, f"Sortero-macOS-{arch}.zip")
 
-        # Ship the first-run helper beside the app. Downloading the zip stamps
-        # com.apple.quarantine on every file inside the bundle, and approving
-        # the app in System Settings only clears the outer one - the loader
-        # then stalls on the nested libraries and no window appears.
-        helper_src = os.path.join(BUILD, "Sortero-first-run.command")
         payload = os.path.join(DIST, "Sortero")
         # --windowed also leaves a onedir build at dist/Sortero. The .app is
         # self-contained, so that folder is dead weight - drop it before reusing
@@ -109,26 +104,24 @@ def main():
             shutil.rmtree(payload)
         os.makedirs(payload)
         shutil.move(app, os.path.join(payload, "Sortero.app"))
-        if os.path.exists(helper_src):
-            helper_dst = os.path.join(payload, "Sortero-first-run.command")
-            shutil.copy2(helper_src, helper_dst)
-            os.chmod(helper_dst, 0o755)
         readme = os.path.join(payload, "READ ME FIRST.txt")
         with open(readme, "w") as fh:
             fh.write(
                 "Sortero for macOS\n"
                 "=================\n\n"
-                "Sortero is signed ad-hoc, not notarised, so macOS quarantines every\n"
-                "file inside the app when you download it. Approving the app in System\n"
-                "Settings only clears the outer bundle, and the app will bounce in the\n"
-                "Dock without ever opening a window.\n\n"
-                "To fix that, once:\n\n"
-                "  1. Drag Sortero.app wherever you want it (Applications is fine).\n"
-                "  2. Double-click 'Sortero-first-run.command'.\n\n"
-                "Or run this in Terminal:\n\n"
-                "  xattr -dr com.apple.quarantine /Applications/Sortero.app\n\n"
-                "After that, open Sortero normally. You only need to do this once per\n"
-                "download.\n")
+                "Sortero is signed ad-hoc rather than notarised (notarising needs a paid\n"
+                "Apple Developer account), so macOS blocks the first launch.\n\n"
+                "  1. Drag Sortero.app wherever you want it - Applications is fine.\n"
+                "  2. Open it once. macOS will refuse, and the icon may bounce in the\n"
+                "     Dock without a window appearing.\n"
+                "  3. Go to System Settings > Privacy & Security, scroll to Security,\n"
+                "     and click 'Open Anyway' next to Sortero.\n"
+                "  4. Quit the bouncing icon if it is still there, then open Sortero\n"
+                "     again. It will start normally.\n\n"
+                "Step 4 matters: the blocked launch leaves a stuck process behind, and\n"
+                "while it is running, opening the app again just brings it to the front\n"
+                "instead of starting a working copy.\n\n"
+                "You only need this once per download.\n")
 
         print("==> zipping (ditto preserves the bundle)")
         subprocess.run(["ditto", "-c", "-k", "--sequesterRsrc", "--keepParent",

build/build_app.py

@@ -1 +1 @@
-__version__ = "0.3.1"
+__version__ = "0.3.2"