wip(sync): merge main into next with combined resolutions

tools/install.sh

@@ -81,18 +81,40 @@ if [[ "${MOSAIC_NEXT:-0}" == "1" ]]; then
   fi
 fi
 
+installer_usage() {
+  printf 'Usage: install.sh [--check] [--framework] [--cli] [--ref <branch>] [--next] [--dev] [--yes|-y] [--no-auto-launch] [--uninstall]\n' >&2
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --check)          FLAG_CHECK=true; shift ;;
     --framework)      FLAG_CLI=false; shift ;;
     --cli)            FLAG_FRAMEWORK=false; shift ;;
-    --ref)            GIT_REF="${2:-main}"; GIT_REF_EXPLICIT=true; shift 2 ;;
+    --ref)
+      if [[ $# -lt 2 ]] || [[ -z "$2" ]]; then
+        printf 'Error: Missing value for --ref\n' >&2
+        installer_usage
+        exit 2
+      fi
+      if [[ "$2" == -* ]]; then
+        printf 'Error: Unknown argument: %s\n' "$2" >&2
+        installer_usage
+        exit 2
+      fi
+      GIT_REF="$2"
+      GIT_REF_EXPLICIT=true
+      shift 2
+      ;;
     --dev)            FLAG_DEV=true; shift ;;
     --next)           FLAG_NEXT=true; if [[ "$GIT_REF_EXPLICIT" == "false" ]]; then GIT_REF="next"; fi; shift ;;
     --yes|-y)         FLAG_YES=true; shift ;;
     --no-auto-launch) FLAG_NO_AUTO_LAUNCH=true; shift ;;
     --uninstall)      FLAG_UNINSTALL=true; shift ;;
-    *)                shift ;;
+    *)
+      printf 'Error: Unknown argument: %s\n' "$1" >&2
+      installer_usage
+      exit 2
+      ;;
   esac
 done
 
@@ -259,7 +281,7 @@ ok()    { echo "${G}✔${RESET}  $*"; }
 warn()  { echo "${Y}⚠${RESET}  $*"; }
 fail()  { echo "${R}✖${RESET}  $*" >&2; }
 dim()   { echo "${DIM}$*${RESET}"; }
-step()  { echo ""; echo "${BOLD}$*${RESET}"; }
+step()  { printf '\n%s%s%s\n' "$BOLD" "$*" "$RESET"; }
 
 is_next_registry_lane() {
   [[ "$FLAG_NEXT" == "true" && "$FLAG_DEV" == "false" && "$GIT_REF" == "next" && "$GIT_REF_EXPLICIT" == "false" ]]