Update scripts to keep SOUL.md idempotent. Add release upgrade framework.

bin/mosaic

@@ -14,6 +14,9 @@ set -euo pipefail
 #   mosaic doctor [args...]       Health audit
 #   mosaic sync [args...]         Sync skills
 #   mosaic bootstrap <path>       Bootstrap a repo
+#   mosaic upgrade release         Upgrade installed Mosaic release
+#   mosaic upgrade check           Check release upgrade status (no changes)
+#   mosaic upgrade project [args]  Upgrade project-local stale files
 
 MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 VERSION="0.1.0"
@@ -34,7 +37,10 @@ Management:
   doctor [args...]       Audit runtime state and detect drift
   sync [args...]         Sync skills from canonical source
   bootstrap <path>       Bootstrap a repo with Mosaic standards
-  upgrade [path]         Clean up stale SOUL.md/CLAUDE.md in a project
+  upgrade [mode] [args]  Upgrade release (default) or project files
+  upgrade check          Check release upgrade status (no changes)
+  release-upgrade [...]  Upgrade installed Mosaic release
+  project-upgrade [...]  Clean up stale SOUL.md/CLAUDE.md in a project
 
 Options:
   -h, --help             Show this help
@@ -147,11 +153,54 @@ run_bootstrap() {
   exec "$MOSAIC_HOME/bin/mosaic-bootstrap-repo" "$@"
 }
 
-run_upgrade() {
+run_release_upgrade() {
+  check_mosaic_home
+  exec "$MOSAIC_HOME/bin/mosaic-release-upgrade" "$@"
+}
+
+run_project_upgrade() {
   check_mosaic_home
   exec "$MOSAIC_HOME/bin/mosaic-upgrade" "$@"
 }
 
+run_upgrade() {
+  check_mosaic_home
+
+  # Default: upgrade installed release
+  if [[ $# -eq 0 ]]; then
+    run_release_upgrade
+  fi
+
+  case "$1" in
+    release)
+      shift
+      run_release_upgrade "$@"
+      ;;
+    check)
+      shift
+      run_release_upgrade --dry-run "$@"
+      ;;
+    project)
+      shift
+      run_project_upgrade "$@"
+      ;;
+
+    # Backward compatibility for historical project-upgrade usage.
+    --all|--root)
+      run_project_upgrade "$@"
+      ;;
+    --dry-run|--ref|--keep|--overwrite|-y|--yes)
+      run_release_upgrade "$@"
+      ;;
+    -*)
+      run_release_upgrade "$@"
+      ;;
+    *)
+      run_project_upgrade "$@"
+      ;;
+  esac
+}
+
 # Main router
 if [[ $# -eq 0 ]]; then
   usage
@@ -170,6 +219,8 @@ case "$command" in
   sync)       run_sync "$@" ;;
   bootstrap)  run_bootstrap "$@" ;;
   upgrade)    run_upgrade "$@" ;;
+  release-upgrade) run_release_upgrade "$@" ;;
+  project-upgrade) run_project_upgrade "$@" ;;
   help|-h|--help)  usage ;;
   version|-v|--version) echo "mosaic $VERSION" ;;
   *)