Make build/release script menus self-documenting

README.md

@@ -70,7 +70,13 @@ The interactive build menu lets you:
 +---------------------------------------+
 ```
 
-Or use flags for CI/scripting: `--pull`, `--open`, `--build`, `--install`, `--clean`, `--reset-tcc`.
+Just run `./scripts/build.sh` with no arguments to get this menu -- the flags
+(`--pull`, `--open`, `--build`, `--install`, `--clean`, `--reset-tcc`) are
+optional shortcuts for CI/scripting and are never required.
+
+`build.sh` is for **local development** (build and run on your own Mac).
+Publishing a signed, notarised release for users is a separate, maintainer-only
+flow in `scripts/release.sh` -- see [RELEASING.md](RELEASING.md).
 
 ### Requirements
 

RELEASING.md

@@ -10,6 +10,40 @@ This repo is public, so **no identity values are committed**. The release
 script reads them from the environment; the placeholders below
 (`you@example.com`, `TEAMID`, `<profile>`, `<40-char-hash>`) are illustrative.
 
+## `build.sh` vs `release.sh`
+
+Two scripts, two jobs. You almost never need to remember a flag -- run either
+with **no arguments** for an interactive menu/prompt.
+
+| | `scripts/build.sh` | `scripts/release.sh` |
+|---|---|---|
+| Purpose | Local development | Publish a version to users |
+| Builds | Debug or Release, unsigned/local | Release, Developer ID-signed |
+| Output | `Untouchable.app` in `/Applications` | Signed, notarised `.dmg` + GitHub Release |
+| Touches the network | only `git pull` | uploads to Apple + GitHub |
+| Run it as | `./scripts/build.sh` (menu) | `./scripts/release.sh` (prompts for version) |
+
+Rule of thumb: **`build.sh` = "test my code on this Mac"**, **`release.sh` =
+"ship a new version to the world."**
+
+The flags (`--build`, `--full`, `--preflight`, ...) are **optional** shortcuts
+for CI/scripting. Running with no flags is fully supported and is the easy path.
+
+## Common tasks
+
+```sh
+# I changed some code and want to run it locally:
+./scripts/build.sh            # pick "Build + Install", then "Launch"
+
+# I want to cut a new public release:
+./scripts/release.sh          # it prompts: "What version are you releasing?"
+                              # enter e.g. v1.2.0 and follow the steps
+```
+
+The version you enter at the release prompt flows straight into the app: the
+About box shows exactly that version (see [Versioning](#versioning) below). You
+do not edit any version numbers by hand.
+
 ## What you need (maintainer, one-time)
 
 These are tied to your Apple **account** and **machine**, shared across all

scripts/build.sh

@@ -172,7 +172,17 @@ show_menu() {
     echo "+---------------------------------------+"
     echo "|         Untouchable Builder           |"
     echo "+---------------------------------------+"
-    echo "|                                       |"
+    echo ""
+    echo "  Local development: build, install, and"
+    echo "  run Untouchable on THIS Mac (unsigned)."
+    echo "  To publish a signed, notarised release"
+    echo "  for users, run scripts/release.sh."
+    echo ""
+    echo "  Flags (e.g. --build) are optional CI"
+    echo "  shortcuts -- with no flags you get this"
+    echo "  menu, which is all you need."
+    echo ""
+    echo "+---------------------------------------+"
     echo "|  1)  Pull latest from GitHub          |"
     echo "|  2)  Open in Xcode                    |"
     echo "|  3)  Build (Release)                  |"

scripts/release.sh

@@ -761,6 +761,13 @@ main() {
 
     # -- Interactive mode --------------------------------------------------
 
+    echo "  Publishes a new version to users: builds a signed Release,"
+    echo "  notarises it with Apple, packages a DMG, and creates a GitHub"
+    echo "  Release. For local dev builds on this Mac, use scripts/build.sh."
+    echo ""
+    echo "  The flags (--full, --build-only, --preflight) are optional"
+    echo "  shortcuts -- running with no flags walks you through every step."
+    echo ""
     echo "What version are you releasing?"
     read -rp "Tag (e.g. v1.0.0): " tag