NEXO 7.0.0 (BREAKING) — Physical layout split

Published 2026-04-19. Plan Consolidado fase F0.6.

What changes

v7.0.0 finishes the multi-release migration that began with F0.0 (schema marker) and walked through F0.5 (safe symlinks): the flat ~/.nexo/scripts/, brain/, data/, operations/, ... layout is replaced by an explicit three-zone tree:

~/.nexo/
├── core/                  ← shipped with the package, replaced on update
│   ├── scripts/           (38 packaged automations)
│   ├── plugins/
│   ├── hooks/
│   ├── rules/
│   └── contracts/
├── core-dev/              ← dev-only, off by default
│   └── scripts/
├── personal/              ← operator-owned, `nexo update` never touches
│   ├── scripts/
│   ├── skills/
│   ├── plugins/
│   ├── hooks/
│   ├── rules/
│   ├── brain/             (calibration.json, project-atlas.json, ...)
│   ├── config/
│   ├── lib/
│   └── overrides/
└── runtime/               ← dynamic state, never edited by hand
    ├── data/              (nexo.db)
    ├── logs/
    ├── operations/
    ├── backups/
    ├── memory/
    ├── cognitive/
    ├── coordination/
    ├── exports/
    ├── nexo-email/
    ├── doctor/
    ├── snapshots/
    └── crons/

Why the split

Three goals the flat layout could not satisfy:

• Update safety. nexo update needs to replace shipped code without ever touching operator-edited content. With everything mixed under ~/.nexo/scripts/, the update path could only act conservatively — a hash check before every overwrite. With core/ vs personal/ separated physically, update can swap core/ wholesale and never read personal/.
• State vs config vs code. Calibration, project-atlas, operator routing rules belong with the operator (they're hers, not ours). Logs, backups, the SQLite DB, the cron spool are dynamic state nobody edits by hand. Mixing the three under ~/.nexo/* made it hard to back up sensibly, hard to ship a fresh-install template, hard to write Doctor checks.
• Multi-machine sync. When a future feature wants to mirror operator state across machines (Mac + Linux + iPad companion), personal/ is the right unit to sync; core/ is package-managed; runtime/ stays local.

How it ships safely

The new src/paths.py module is the core of the migration. Every helper (core_scripts_dir, personal_scripts_dir, brain_dir, data_dir, db_path, logs_dir, operations_dir, ...) is transition-aware: it returns the new (post-F0.6) location if that location exists; otherwise it falls back to the legacy (pre-F0.6) location if the legacy one is present; otherwise it returns the new location (fresh install). This means:

• Pre-F0.6 runtimes that haven't migrated yet keep working.
• Mid-migration runtimes work on both halves of the tree.
• Post-F0.6 runtimes use the clean new tree.
• Fresh installs land directly in the new tree.

24 src files were refactored to use the helpers (auto_update.py, cli.py, evolution_cycle.py, runtime_power.py, cron_recovery.py, user_data_portability.py, system_catalog.py, public_contribution.py, tools_sessions.py, plugins/recover.py, plugins/personal_plugins.py, plugins/update.py, doctor/providers/runtime.py, doctor/providers/deep.py, doctor/providers/boot.py, db/_skills.py, ...). 7 shell scripts under src/scripts/ were updated to reference the new layout. The cron wrapper's DB="$NEXO_HOME/data/nexo.db" is now DB="$NEXO_HOME/runtime/data/nexo.db".

Migration mechanics

On first nexo update from v6.x to v7.0.0, the migrator:

1. Snapshots the runtime to ~/.nexo-pre-f06-snapshot/.
2. Unloads every com.nexo.*.plist via launchctl.
3. Moves 13 directories from ~/.nexo/<X>/ to ~/.nexo/{core,personal,runtime}/<X>/.
4. UPDATEs personal_scripts.path transactionally so the cron wrapper gate keeps finding scripts.
5. Rewrites every LaunchAgent plist (ProgramArguments + StandardOutPath + StandardErrorPath) to reference the new layout.
6. Writes ~/.nexo/.structure-version = F0.6 and reloads every plist.

Total downtime: ~30 sec. Rollback path: mv ~/.nexo-pre-f06-snapshot ~/.nexo if anything fails.

Tests & auditing

1551 pytest tests pass. Test fixtures were updated to either monkeypatch the env var alongside module constants OR use tmp_path / "runtime" / X for runtime state. The fixture for cron-wrapper, doctor, and watchdog were updated to point at the new layout.

Companion client

The NEXO Desktop client — a closed-source companion app distributed separately at systeam.es/nexo-desktop — ships v0.21.0 in coordination with this Brain release. Desktop's hardcoded path references (~/.nexo/data/nexo.db, ~/.nexo/brain/calibration.json, ~/.nexo/brain/profile.json) get the same transition-aware treatment so the auto-update flow keeps working without operator intervention.