feat: add Compass self-upgrade command

Cargo.toml

@@ -74,6 +74,8 @@ rayon = "1"
 rand = "0.8.7"
 realfft = "3.5.0"
 regex = "1"
+semver = "1"
+self-replace = "1.5"
 rmcp = { version = "2.2.0", default-features = false, features = ["server", "transport-io", "transport-streamable-http-server"] }
 rubato = "0.16.2"
 flate2 = "1.1.9"
@@ -91,6 +93,7 @@ unicode-normalization = "0.1"
 unicode-casefold = "0.2"
 unicode-properties = { version = "0.1.4", features = ["general-category"] }
 tempfile = "3"
+tar = "0.4"
 atomicwrites = "=0.4.4"
 tiktoken-rs = "0.7.0"
 symphonia = { version = "0.6.0", default-features = false, features = ["all"] }

README.md

@@ -139,6 +139,16 @@ You can also install directly through Cargo:
 cargo install --locked --path crates/compass-cli --bin compass
 ```
 
+Upgrade any installed Compass executable to the latest stable release with:
+
+```bash
+compass upgrade
+```
+
+Compass verifies the official release checksum before replacing the executable.
+If no newer release is available, it exits successfully and reports that the
+installed version is already the latest.
+
 ### 2. Initialize and build a local graph
 
 ```bash

crates/compass-cli/Cargo.toml

@@ -20,16 +20,21 @@ path = "src/bin/compass.rs"
 
 [dependencies]
 ctrlc.workspace = true
+flate2.workspace = true
 glob.workspace = true
 mimalloc.workspace = true
 regex.workspace = true
+semver.workspace = true
 serde.workspace = true
 serde_json.workspace = true
+self-replace.workspace = true
 sha2.workspace = true
+tar.workspace = true
 tempfile.workspace = true
 time.workspace = true
 tokio.workspace = true
 toml.workspace = true
+ureq.workspace = true
 compass-core = { path = "../compass-core", version = "0.1.4" }
 compass-analysis = { path = "../compass-analysis", version = "0.1.4" }
 compass-ir = { path = "../compass-ir", version = "0.1.4" }

crates/compass-cli/assets/compass-skill/references/command-reference.md

@@ -83,6 +83,7 @@ tools and must not replace normal extraction without a reason.
 - `compass install`: install the canonical skill and platform integration.
 - `compass uninstall`: remove managed integrations; `--purge` additionally
   removes Compass output and requires explicit user intent.
+- `compass upgrade`: verify and install the latest stable Compass release.
 - `compass hook`: install, inspect, or uninstall repository refresh hooks.
 - `compass hook-check`: no-op probe owned by installed hook configuration.
 - `compass hook-guard`: adapter owned by installed search/read/Gemini guards.

crates/compass-cli/build.rs

@@ -26,6 +26,10 @@ fn collect(root: &Path, directory: &Path, files: &mut Vec<PathBuf>) -> io::Resul
 }
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
+    println!(
+        "cargo:rustc-env=COMPASS_BUILD_TARGET={}",
+        env::var("TARGET")?
+    );
     println!("cargo:rerun-if-changed=assets");
     println!("cargo:rerun-if-changed=src/lib.rs");
     println!("cargo:rerun-if-changed=src/help.rs");

crates/compass-cli/src/help.rs

@@ -115,6 +115,7 @@ const GROUPS: &[Group] = &[
             "hook",
             "install",
             "uninstall",
+            "upgrade",
             "provider",
             "save-result",
             "reflect",
@@ -479,6 +480,12 @@ const PAGES: &[Page] = &[
         ["compass uninstall [PLATFORM] [OPTIONS]"],
         "Arguments:\n  [PLATFORM]               Remove one assistant platform\n\nOptions:\n  --platform <NAME>        Select one assistant platform\n  --project                Remove project-scoped files\n  --purge                  Remove all installed Compass guidance\n\nExamples:\n  compass uninstall --platform codex\n  compass uninstall --project --purge"
     ),
+    page!(
+        "upgrade",
+        "Upgrade Compass to the latest stable release",
+        ["compass upgrade"],
+        "Examples:\n  compass upgrade\n\nNotes:\n  Compass verifies the official release checksum before replacing the running executable.\n  If no newer stable release is available, the command exits successfully without changes."
+    ),
     page!(
         "provider",
         "Manage custom semantic model providers",
@@ -998,7 +1005,7 @@ mod tests {
     #[test]
     fn catalog_has_unique_complete_public_roots() {
         let roots = root_commands();
-        assert_eq!(roots.len(), 38);
+        assert_eq!(roots.len(), 39);
         for root in roots {
             let matches = PAGES.iter().filter(|page| page.path == root).count();
             assert_eq!(matches, 1, "{root}");

crates/compass-cli/src/lib.rs

@@ -22,6 +22,7 @@ mod result_commands;
 mod semantic_commands;
 mod semantic_diff_commands;
 mod semantic_diff_render;
+mod upgrade_commands;
 
 use std::collections::HashMap;
 use std::ffi::OsString;
@@ -370,6 +371,7 @@ pub fn run(frontend: Frontend, arguments: impl IntoIterator<Item = OsString>) ->
         "hook-refresh" => command_hook_refresh(frontend, &args),
         "install" => install_commands::command_install(frontend, &args),
         "uninstall" => install_commands::command_uninstall(frontend, &args),
+        "upgrade" => upgrade_commands::command_upgrade(&args),
         platform if install_commands::is_direct_command(platform) => {
             install_commands::command_platform(frontend, platform, &args)
         }