Fix onboarding quickstart bugs and guard destructive cactus clean

README.md

@@ -42,7 +42,7 @@ A low-latency AI engine for mobile devices & wearables.
 ## Quick Demo (Mac)
 
 - Step 1: `brew install cactus-compute/cactus/cactus`
-- Step 2: `cactus transcribe` or `cactus run` 
+- Step 2: `cactus run`
 
 ## Cactus Engine
 
@@ -230,7 +230,7 @@ cactus build               # default static lib
 ┌────────────────────────────────────────────────────────────────────────────────┐
 │                                                                                │
 │ Step 0: if on Linux (Ubuntu/Debian)                                            │
-│ sudo apt-get install python3 python3-venv python3-pip cmake                    │
+│ sudo apt-get install python3.12 python3.12-venv python3-pip cmake              │
 │   build-essential libcurl4-openssl-dev                                         │
 │                                                                                │
 │ Step 1: clone and setup                                                        │

docs/quickstart.md

@@ -62,7 +62,7 @@ Install Cactus and run your first on-device AI completion.
     **From Source (Linux):**
 
     ```bash
-    sudo apt-get install python3 python3-venv python3-pip cmake build-essential libcurl4-openssl-dev
+    sudo apt-get install python3.12 python3.12-venv python3-pip cmake build-essential libcurl4-openssl-dev
     git clone https://github.com/cactus-compute/cactus && cd cactus && source ./setup && cactus build --python
     ```
 

python/cactus/cli/__init__.py

@@ -174,7 +174,7 @@ def create_parser():
     --android                          run on connected Android
     --enable-telemetry                 send cloud telemetry (off by default)
 
-  cactus clean                         delete build artifacts
+  cactus clean                         delete build artifacts, weights, venv
   cactus --help                        show this help
 
   -----------------------------------------------------------------
@@ -297,7 +297,8 @@ def create_parser():
     auth_parser.add_argument("--status", action="store_true",
                              help="Show current key status")
 
-    subparsers.add_parser("clean", help="Delete build artifacts")
+    clean_parser = subparsers.add_parser("clean", help="Delete build artifacts, downloaded weights, and venv")
+    clean_parser.add_argument("--yes", "-y", action="store_true", help="Skip confirmation prompt")
 
     subparsers.add_parser("list", help="List local converted weights and bundles")
 

python/cactus/cli/clean.py

@@ -1,11 +1,12 @@
 import shutil
 import subprocess
+import sys
 from pathlib import Path
 
 from .common import (
     PROJECT_ROOT,
     print_color,
-    GREEN, YELLOW, BLUE,
+    RED, GREEN, YELLOW, BLUE,
 )
 
 
@@ -15,6 +16,24 @@ def cmd_clean(args):
     print(f"Project root: {PROJECT_ROOT}")
     print()
 
+    destructive_targets = [
+        PROJECT_ROOT / "weights",
+        PROJECT_ROOT / "transpiled",
+        PROJECT_ROOT / "venv",
+    ]
+    present = [t for t in destructive_targets if t.exists()]
+    if present and not args.yes:
+        print_color(YELLOW, "This also deletes the following (not just build artifacts):")
+        for t in present:
+            print(f"  - {t}")
+        print_color(YELLOW, "Downloaded weights are NOT re-fetched by setup and will be lost.")
+        if not sys.stdin.isatty():
+            print_color(RED, "Refusing to proceed without confirmation. Re-run with --yes to skip this prompt.")
+            return 0
+        if input("Continue? [y/N]: ").strip().lower() not in ("y", "yes"):
+            print_color(YELLOW, "Aborted.")
+            return 0
+
     def remove_if_exists(path):
         if path.is_dir():
             print(f"Removing: {path}")
@@ -110,7 +129,7 @@ def should_preserve_artifact(path):
 
     print()
     print_color(GREEN, "Clean complete!")
-    print("All build artifacts have been removed.")
+    print("All build artifacts, weights, and venv have been removed.")
     print()
 
     print_color(BLUE, "Re-running setup...")