scripts: require --tag for debug reload

CLAUDE.md

@@ -10,13 +10,7 @@ Run the setup script to initialize submodules and build GhosttyKit:
 
 ## Local dev
 
-After making code changes, always run the reload script to launch the Debug app:
+After making code changes, always run the reload script with a tag to launch the Debug app:
-
-```bash
-./scripts/reload.sh
-```
-
-After you're done with a fix, also reload with a tag so you can verify it in an isolated side-by-side app:
 
 ```bash
 ./scripts/reload.sh --tag fix-zsh-autosuggestions
@@ -40,10 +34,10 @@ When rebuilding cmuxd for release/bundling, always use ReleaseFast:
 cd cmuxd && zig build -Doptimize=ReleaseFast
 ```
 
-`reload` = kill and launch the Debug app only:
+`reload` = kill and launch the Debug app only (tag required):
 
 ```bash
-./scripts/reload.sh
+./scripts/reload.sh --tag <tag>
 ```
 
 `reloadp` = kill and launch the Release app:
@@ -58,10 +52,10 @@ cd cmuxd && zig build -Doptimize=ReleaseFast
 ./scripts/reloads.sh
 ```
 
-`reload2` = reload both Debug and Release:
+`reload2` = reload both Debug and Release (tag required for Debug reload):
 
 ```bash
-./scripts/reload2.sh
+./scripts/reload2.sh --tag <tag>
 ```
 
 For parallel/isolated builds (e.g., testing a feature alongside the main app), use `--tag` with a short descriptive name:
@@ -72,6 +66,8 @@ For parallel/isolated builds (e.g., testing a feature alongside the main app), u
 
 This creates an isolated app with its own name, bundle ID, socket, and derived data path so it runs side-by-side with the main app. Important: use a non-`/tmp` derived data path if you need xcframework resolution (the script handles this automatically).
 
+Before launching a new tagged run, clean up any older tags you started in this session (quit old tagged app + remove its `/tmp` socket/derived data).
+
 ## Pitfalls
 
 - Do not add an app-level display link or manual `ghostty_surface_draw` loop; rely on Ghostty wakeups/renderer to avoid typing lag.

scripts/reload.sh

@@ -12,10 +12,10 @@ TAG=""
 
 usage() {
   cat <<'EOF'
-Usage: ./scripts/reload.sh [options]
+Usage: ./scripts/reload.sh --tag <name> [options]
 
 Options:
-  --tag <name>           Short tag for parallel builds (e.g., feature-xyz-lol).
+  --tag <name>           Required. Short tag for parallel builds (e.g., feature-xyz-lol).
                          Sets app name, bundle id, and derived data path unless overridden.
   --name <app name>      Override app display/bundle name.
   --bundle-id <id>       Override bundle identifier.
@@ -93,6 +93,12 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+if [[ -z "$TAG" ]]; then
+  echo "error: --tag is required (example: ./scripts/reload.sh --tag fix-sidebar-theme)" >&2
+  usage
+  exit 1
+fi
+
 if [[ -n "$TAG" ]]; then
   TAG_ID="$(sanitize_bundle "$TAG")"
   TAG_SLUG="$(sanitize_path "$TAG")"

scripts/reload2.sh

@@ -1,5 +1,10 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-./scripts/reload.sh
+if [[ $# -eq 0 ]]; then
+  echo "error: reload2 requires a tag (example: ./scripts/reload2.sh --tag smoke)" >&2
+  exit 1
+fi
+
+./scripts/reload.sh "$@"
 ./scripts/reloadp.sh

scripts/setup.sh

@@ -27,4 +27,4 @@ ln -sf ghostty/macos/GhosttyKit.xcframework GhosttyKit.xcframework
 echo "==> Setup complete!"
 echo ""
 echo "You can now build and run the app:"
-echo "  ./scripts/reload.sh"
+echo "  ./scripts/reload.sh --tag first-run"