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

README.md

@@ -30,6 +30,7 @@ The installer will:
 - Add `~/.config/mosaic/bin` to your PATH
 - Sync runtime adapters and skills
 - Run a health audit
+- Detect existing installs and prompt to keep or overwrite local files
 - Prompt you to run `mosaic init` to set up your agent identity
 
 ## First Run
@@ -96,24 +97,58 @@ mosaic init                # Generate SOUL.md (agent identity)
 mosaic doctor              # Health audit — detect drift and missing files
 mosaic sync                # Sync skills from canonical source
 mosaic bootstrap <path>    # Bootstrap a repo with Mosaic standards
-mosaic upgrade [path]      # Clean up stale per-project files (see below)
-mosaic upgrade --all       # Upgrade all projects in ~/src
-mosaic upgrade --dry-run   # Preview without changes
+mosaic upgrade check       # Check release upgrade status (no changes)
+mosaic upgrade             # Upgrade installed Mosaic release (keeps SOUL.md by default)
+mosaic upgrade --dry-run   # Preview release upgrade without changes
+mosaic upgrade --ref main  # Upgrade from a specific branch/tag/commit ref
+mosaic upgrade --overwrite # Upgrade release and overwrite local files
+mosaic upgrade project ... # Project file cleanup mode (see below)
 ```
 
+## Upgrading Mosaic Release
+
+Upgrade the installed framework in place:
+
+```bash
+# Default (safe): keep local SOUL.md + memory
+mosaic upgrade
+
+# Check current/target release info without changing files
+mosaic upgrade check
+
+# Non-interactive
+mosaic upgrade --yes
+
+# Pull a specific ref
+mosaic upgrade --ref main
+
+# Force full overwrite (fresh install semantics)
+mosaic upgrade --overwrite --yes
+```
+
+`mosaic upgrade` re-runs the remote installer and passes install mode controls (`keep`/`overwrite`).
+This is the manual upgrade path today and is suitable for future app-driven update checks.
+
 ## Upgrading Projects
 
 After centralizing AGENTS.md and SOUL.md, existing projects may have stale files:
 
 ```bash
 # Preview what would change across all projects
-mosaic upgrade --all --dry-run
+mosaic upgrade project --all --dry-run
 
 # Apply to all projects
-mosaic upgrade --all
+mosaic upgrade project --all
 
 # Apply to a specific project
-mosaic upgrade ~/src/my-project
+mosaic upgrade project ~/src/my-project
+```
+
+Backward compatibility is preserved for historical usage:
+
+```bash
+mosaic upgrade --all          # still routes to project-upgrade
+mosaic upgrade ~/src/my-repo  # still routes to project-upgrade
 ```
 
 What it does per project:
@@ -186,6 +221,10 @@ Pull the latest and re-run the installer:
 cd ~/src/mosaic-bootstrap && git pull && bash install.sh
 ```
 
+If an existing install is detected, the installer prompts for:
+- `keep` (recommended): preserve local `SOUL.md` and `memory/`
+- `overwrite`: replace everything in `~/.config/mosaic`
+
 Or use the one-liner again — it always pulls the latest:
 
 ```bash