Update Nexus
Purpose: Sync system files from the upstream Nexus repository while protecting user data
Trigger: "update nexus", "sync nexus", "get updates", "check for updates"
Duration: 1-2 minutes
What This Does
Updates these system files from upstream:
-
00-system/
-
Core framework, skills, documentation
-
CLAUDE.md
-
Entry point
-
README.md
-
Project readme
Protects these user folders (NEVER touched):
-
01-memory/
-
Your goals, learnings, config
-
02-projects/
-
Your projects
-
03-skills/
-
Your custom skills
-
04-workspace/
-
Your files
-
.env , .claude/
-
Your secrets and settings
Workflow
Step 1: Check for Updates
Run the update check:
python 00-system/core/nexus-loader.py --check-update
Parse the JSON response:
-
If checked: false with error → Display error, exit gracefully
-
If update_available: false → Display "Already up-to-date!", exit
-
If update_available: true → Continue to Step 2
Step 2: Show What Will Change
Display to user:
UPDATE AVAILABLE
Current version: {local_version} New version: {upstream_version}
Files to update ({changes_count}): {list changed_files, max 20}
PROTECTED (will NOT be touched):
- 01-memory/ (your goals & config)
- 02-projects/ (your projects)
- 03-skills/ (your custom skills)
- 04-workspace/ (your files)
Step 3: Confirm with User
Ask: "Proceed with update? (yes/no)"
-
If no → Exit with "Update cancelled"
-
If yes → Continue to Step 4
Step 4: Perform Sync
Run the sync command:
python 00-system/core/nexus-loader.py --sync --force
Parse the JSON response:
-
If success: false → Display error message, suggest fixes
-
If success: true → Continue to Step 5
Step 5: Display Results
On success, display:
UPDATE COMPLETE!
{local_version} → {upstream_version}
Updated paths: {list files_updated}
Backup saved to: {backup_path}
To commit this update: git add . && git commit -m "Update Nexus to v{upstream_version}"
Error Handling
Error User Message
"Not a git repository" "This folder isn't a git repo. Initialize with: git init"
"Could not reach upstream" "Can't connect to GitHub. Check your internet connection."
"Uncommitted changes detected" "You have uncommitted changes. Commit them first:\n git add . && git commit -m 'Save changes'"
"Could not read upstream version" "The upstream repo might not be set up correctly. Check the URL in user-config.yaml"
Advanced: Dry Run
To preview changes without applying:
python 00-system/core/nexus-loader.py --sync --dry-run
This shows what WOULD change, but doesn't change anything.
Notes
-
Backup: Before any sync, your current system files are backed up to .sync-backup/{timestamp}/
-
Safe: User data folders are NEVER in the sync paths - they cannot be touched
-
Upstream Remote: Automatically added on first use (named "upstream")
-
Default URL: https://github.com/beamanalytica/Nexus-v4.git (can override in user-config.yaml)