nexo-brain 6.5.0 → 7.0.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "6.5.0",
+  "version": "7.0.0",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -18,7 +18,9 @@
 
 [Watch the overview video](https://nexo-brain.com/watch/) · [Watch on YouTube](https://www.youtube.com/watch?v=i2lkGhKyVqI) · [Open the infographic](https://nexo-brain.com/assets/nexo-brain-infographic-v5.png)
 
-Version `6.5.0` is the current packaged-runtime line — Plan Consolidado fase F0.2: operators can now `nexo scripts enable|disable|status <name>` any personal automation. The cron wrapper honours the flag at every tick (`exit 0` with `summary='[disabled]'` while the LaunchAgent stays loaded). The companion NEXO Desktop client (a closed-source product, distributed separately) wires the same toggle into its Automatizaciones panel. See [CHANGELOG](CHANGELOG.md) for the full diff.
+Version `7.0.0` is the current packaged-runtime line — **BREAKING — Plan Consolidado fase F0.6**: physical separation of the runtime tree into `~/.nexo/{core,personal,runtime}/`. The flat layout (`~/.nexo/scripts/`, `brain/`, `data/`, `operations/`, ...) is gone. Operators on v6.x are auto-migrated on first `nexo update`; fresh installs land directly in the new tree. New `paths.py` helpers are transition-aware. The companion NEXO Desktop client (v0.21.0, closed-source distributed separately) updates its hardcoded paths so auto-update keeps working.
+
+Previously in `6.5.0`: Plan Consolidado fase F0.2: operators can now `nexo scripts enable|disable|status <name>` any personal automation. The cron wrapper honours the flag at every tick (`exit 0` with `summary='[disabled]'` while the LaunchAgent stays loaded). The companion NEXO Desktop client (a closed-source product, distributed separately) wires the same toggle into its Automatizaciones panel. See [CHANGELOG](CHANGELOG.md) for the full diff.
 
 > **About NEXO Desktop.** NEXO Desktop is a separate closed-source companion app distributed at [systeam.es/nexo-desktop](https://systeam.es/nexo-desktop) — its source does not live in this repo. When release notes mention Desktop they describe a coordinated client release that consumes the Brain's CLI / MCP contract; the Brain itself is fully usable on its own (terminal, Codex, Claude Code, or any MCP client).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "6.5.0",
+  "version": "7.0.0",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain \u2014 Shared brain for AI agents. Persistent memory, semantic RAG, natural forgetting, metacognitive guard, trust scoring, 150+ MCP tools. Works with Claude Code, Codex, Claude Desktop & any MCP client. 100% local, free.",
   "homepage": "https://nexo-brain.com",
@@ -92,4 +92,4 @@
     "README.md",
     "LICENSE"
   ]
-}
+}

package/src/auto_update.py

@@ -10,6 +10,7 @@ This is separate from plugins/update.py which handles MANUAL updates with rollba
 import json
 import hashlib
 import os
+import paths
 import re
 import shutil
 import subprocess
@@ -32,7 +33,7 @@ except ModuleNotFoundError as exc:
         return False
 
 NEXO_HOME = export_resolved_nexo_home()
-DATA_DIR = NEXO_HOME / "data"
+DATA_DIR = paths.data_dir()
 DATA_DIR.mkdir(parents=True, exist_ok=True)
 
 # Repo root: go up from src/
@@ -212,10 +213,10 @@ def _write_last_check(data: dict):
 def _sync_watchdog_hash_registry():
     """Keep the immutable-hash registry aligned with the installed watchdog script."""
     try:
-        watchdog_file = NEXO_HOME / "scripts" / "nexo-watchdog.sh"
+        watchdog_file = paths.core_scripts_dir() / "nexo-watchdog.sh"
         if not watchdog_file.exists():
             return
-        registry_file = NEXO_HOME / "scripts" / ".watchdog-hashes"
+        registry_file = paths.core_scripts_dir() / ".watchdog-hashes"
         entries: dict[str, str] = {}
         if registry_file.exists():
             for line in registry_file.read_text().splitlines():
@@ -523,7 +524,7 @@ def _refresh_installed_manifest():
     try:
         import shutil
         src_crons = SRC_DIR / "crons"
-        dst_crons = NEXO_HOME / "crons"
+        dst_crons = paths.crons_dir()
         if src_crons.exists():
             dst_crons.mkdir(parents=True, exist_ok=True)
             for f in src_crons.iterdir():
@@ -537,17 +538,17 @@ def _refresh_installed_manifest():
 def _cleanup_retired_runtime_files():
     """Remove retired core files that should not survive updates."""
     retired = [
-        NEXO_HOME / "scripts" / "nexo-day-orchestrator.sh",
-        NEXO_HOME / "scripts" / "heartbeat-enforcement.py",
-        NEXO_HOME / "scripts" / "heartbeat-posttool.sh",
-        NEXO_HOME / "scripts" / "heartbeat-user-msg.sh",
-        NEXO_HOME / "hooks" / "heartbeat-guard.sh",
+        paths.core_scripts_dir() / "nexo-day-orchestrator.sh",
+        paths.core_scripts_dir() / "heartbeat-enforcement.py",
+        paths.core_scripts_dir() / "heartbeat-posttool.sh",
+        paths.core_scripts_dir() / "heartbeat-user-msg.sh",
+        paths.core_hooks_dir() / "heartbeat-guard.sh",
     ]
     conditional_retired = [
-        (NEXO_HOME / "scripts" / "nexo-postcompact.sh", NEXO_HOME / "hooks" / "post-compact.sh"),
-        (NEXO_HOME / "scripts" / "nexo-memory-precompact.sh", NEXO_HOME / "hooks" / "pre-compact.sh"),
-        (NEXO_HOME / "scripts" / "nexo-memory-stop.sh", NEXO_HOME / "hooks" / "session-stop.sh"),
-        (NEXO_HOME / "scripts" / "nexo-session-briefing.sh", NEXO_HOME / "hooks" / "session-start.sh"),
+        (paths.core_scripts_dir() / "nexo-postcompact.sh", paths.core_hooks_dir() / "post-compact.sh"),
+        (paths.core_scripts_dir() / "nexo-memory-precompact.sh", paths.core_hooks_dir() / "pre-compact.sh"),
+        (paths.core_scripts_dir() / "nexo-memory-stop.sh", paths.core_hooks_dir() / "session-stop.sh"),
+        (paths.core_scripts_dir() / "nexo-session-briefing.sh", paths.core_hooks_dir() / "session-start.sh"),
     ]
     for target in retired:
         try:
@@ -692,7 +693,7 @@ def _rotate_auto_update_backups(prefix: str, keep: int = AUTO_UPDATE_BACKUP_KEEP
     """
     if keep <= 0:
         return 0
-    base = NEXO_HOME / "backups"
+    base = paths.backups_dir()
     if not base.is_dir():
         return 0
     try:
@@ -721,7 +722,7 @@ def _rotate_auto_update_backups(prefix: str, keep: int = AUTO_UPDATE_BACKUP_KEEP
     return removed
 
 
-SELF_HEAL_STATE_FILE = NEXO_HOME / "operations" / ".self-heal-state.json"
+SELF_HEAL_STATE_FILE = paths.operations_dir() / ".self-heal-state.json"
 SELF_HEAL_COOLDOWN_SECONDS = 6 * 3600  # Never auto-heal twice within 6 h.
 
 
@@ -765,7 +766,7 @@ def _self_heal_if_wiped() -> dict | None:
     if not db_looks_wiped(primary, CRITICAL_TABLES):
         return None
     reference = find_latest_hourly_backup(
-        NEXO_HOME / "backups",
+        paths.backups_dir(),
         max_age_seconds=HOURLY_BACKUP_MAX_AGE,
     )
     if reference is None:
@@ -813,7 +814,7 @@ def _self_heal_if_wiped() -> dict | None:
         time.sleep(0.5)
 
     # Snapshot the current (wiped) state so the heal is reversible.
-    pre_heal_dir = NEXO_HOME / "backups" / f"pre-heal-{time.strftime('%Y-%m-%d-%H%M%S')}"
+    pre_heal_dir = paths.backups_dir() / f"pre-heal-{time.strftime('%Y-%m-%d-%H%M%S')}"
     try:
         import shutil as _shutil
         pre_heal_dir.mkdir(parents=True, exist_ok=True)
@@ -1282,7 +1283,7 @@ def _backup_dbs() -> str | None:
     # validation and rollback paths. Safe no-op when there are none.
     _purge_zero_byte_db_files()
     timestamp = _time.strftime("%Y-%m-%d-%H%M%S")
-    backup_dir = NEXO_HOME / "backups" / f"pre-autoupdate-{timestamp}"
+    backup_dir = paths.backups_dir() / f"pre-autoupdate-{timestamp}"
 
     db_files = list(DATA_DIR.glob("*.db")) if DATA_DIR.is_dir() else []
     db_files += [f for f in NEXO_HOME.glob("*.db") if f.is_file()]
@@ -1353,7 +1354,7 @@ def _sync_hooks():
     """Copy hook scripts from src/hooks/ to NEXO_HOME/hooks/ after a git pull."""
     import shutil
     hooks_src = SRC_DIR / "hooks"
-    hooks_dest = NEXO_HOME / "hooks"
+    hooks_dest = paths.core_hooks_dir()
     if not hooks_src.is_dir():
         return
     hooks_dest.mkdir(parents=True, exist_ok=True)
@@ -1526,6 +1527,12 @@ def _run_db_migrations() -> bool:
         # over automatically so scripts pick up the new source on the
         # next cron without the operator running anything manually.
         _maybe_migrate_legacy_email_config()
+        # Plan Consolidado F0.6 — one-shot physical layout migration.
+        # If ~/.nexo/.structure-version is absent or pre-F0.6, move the
+        # flat layout into ~/.nexo/{core,personal,runtime}/<X>/, rewrite
+        # personal_scripts.path + LaunchAgent plists, then write the
+        # F0.6 marker. Idempotent: returns immediately when already F0.6.
+        _maybe_migrate_to_f06_layout()
         return True
     except Exception as e:
         _log(f"DB migration error: {e}")
@@ -1540,7 +1547,7 @@ def _maybe_migrate_legacy_email_config() -> None:
     except Exception:
         return  # m46 not applied yet (older runtime), nothing to do
     try:
-        legacy = NEXO_HOME / "nexo-email" / "config.json"
+        legacy = paths.nexo_email_dir() / "config.json"
         if not legacy.exists():
             return
         if get_email_account("primary"):
@@ -1571,6 +1578,240 @@ def _maybe_migrate_legacy_email_config() -> None:
 
 # ── npm version check (notify only) ─────────────────────────────────
 
+
+def _maybe_migrate_to_f06_layout() -> None:
+    """Plan F0.6 — one-shot physical layout migration. Idempotent.
+
+    Pre-condition: ``~/.nexo/.structure-version`` is absent or its content
+    is not ``F0.6``. After running, every dir from the flat layout
+    (``~/.nexo/scripts/``, ``brain/``, ``data/``, ``operations/``, ...)
+    has been moved to its post-F0.6 home (``~/.nexo/{core,personal,runtime}/<X>/``),
+    ``personal_scripts.path`` rows point at the new locations, every
+    ``com.nexo.*.plist`` LaunchAgent has been rewritten to use the new
+    paths, and ``~/.nexo/.structure-version`` is set to ``F0.6``.
+
+    A snapshot is taken before the move at ``~/.nexo-pre-f06-snapshot/``
+    so a complete rollback is ``mv ~/.nexo-pre-f06-snapshot ~/.nexo``.
+
+    Failures are non-fatal — the helper logs and returns; the operator
+    can re-run ``nexo update`` later.
+    """
+    try:
+        marker = NEXO_HOME / ".structure-version"
+        try:
+            current = marker.read_text(encoding="utf-8").strip()
+        except Exception:
+            current = ""
+        if current == "F0.6":
+            return  # already migrated
+        # Refuse to migrate from a non-NEXO_HOME or a fresh install
+        # without legacy dirs to move.
+        legacy_anchors = [NEXO_HOME / sub for sub in
+                          ("scripts", "brain", "data", "operations", "logs", "backups",
+                           "memory", "cognitive", "coordination", "exports",
+                           "nexo-email", "doctor", "snapshots", "crons",
+                           "skills", "plugins", "hooks", "rules")]
+        present = [p for p in legacy_anchors if p.exists() and not p.is_symlink()]
+        if not present:
+            # Fresh install — write marker and return.
+            try:
+                marker.write_text("F0.6\n", encoding="utf-8")
+            except Exception:
+                pass
+            return
+
+        _log("[F0.6] starting layout migration...")
+        import shutil
+        import sqlite3
+        import re as _re
+        # 1. Snapshot
+        snapshot = Path(str(NEXO_HOME) + "-pre-f06-snapshot")
+        if not snapshot.exists():
+            try:
+                shutil.copytree(NEXO_HOME, snapshot, symlinks=True, ignore_dangling_symlinks=True)
+                _log(f"[F0.6] snapshot at {snapshot}")
+            except Exception as e:
+                _log(f"[F0.6] snapshot failed (non-fatal): {e}")
+
+        # 2. Ensure target dirs
+        for sub in ("core/scripts", "core-dev/scripts", "personal/scripts",
+                    "personal/brain", "personal/skills",
+                    "core/plugins", "core/hooks", "core/rules",
+                    "runtime/data", "runtime/logs", "runtime/operations",
+                    "runtime/backups", "runtime/memory", "runtime/cognitive",
+                    "runtime/coordination", "runtime/exports",
+                    "runtime/nexo-email", "runtime/doctor",
+                    "runtime/snapshots", "runtime/crons"):
+            (NEXO_HOME / sub).mkdir(parents=True, exist_ok=True)
+
+        # 3. Classify scripts: load core names from packaged manifest
+        core_names: set[str] = set()
+        artifacts = NEXO_HOME / "config" / "runtime-core-artifacts.json"
+        try:
+            data = json.loads(artifacts.read_text(encoding="utf-8"))
+            for name in data.get("script_names", []):
+                core_names.add(name)
+        except Exception:
+            pass
+        for f in (NEXO_HOME / "core" / "scripts").iterdir() if (NEXO_HOME / "core" / "scripts").is_dir() else []:
+            core_names.add(f.name)
+        dev_names: set[str] = set()
+        if (NEXO_HOME / "core-dev" / "scripts").is_dir():
+            for f in (NEXO_HOME / "core-dev" / "scripts").iterdir():
+                dev_names.add(f.name)
+
+        def _classify(name: str) -> str:
+            if name in dev_names:
+                return "core-dev"
+            if name in core_names:
+                return "core"
+            return "personal"
+
+        # 4. Move script files (handle existing F0.3/0.4 symlinks)
+        legacy_scripts = NEXO_HOME / "scripts"
+        if legacy_scripts.is_dir() and not legacy_scripts.is_symlink():
+            for f in sorted(legacy_scripts.iterdir()):
+                if not f.is_file():
+                    continue
+                cls = _classify(f.name)
+                root = {
+                    "core": NEXO_HOME / "core" / "scripts",
+                    "personal": NEXO_HOME / "personal" / "scripts",
+                    "core-dev": NEXO_HOME / "core-dev" / "scripts",
+                }[cls]
+                dst = root / f.name
+                if dst.is_symlink():
+                    target = dst.resolve()
+                    if target == f.resolve():
+                        dst.unlink()
+                if dst.exists():
+                    if dst.is_file() and f.is_file() and dst.read_bytes() == f.read_bytes():
+                        f.unlink()
+                        continue
+                    dst.rename(dst.with_suffix(dst.suffix + ".f06bak"))
+                shutil.move(str(f), str(dst))
+
+        # 5. Move tree dirs (brain, data, logs, ...)
+        TREE_MAP = [
+            ("brain", NEXO_HOME / "personal" / "brain"),
+            ("data", NEXO_HOME / "runtime" / "data"),
+            ("logs", NEXO_HOME / "runtime" / "logs"),
+            ("operations", NEXO_HOME / "runtime" / "operations"),
+            ("backups", NEXO_HOME / "runtime" / "backups"),
+            ("memory", NEXO_HOME / "runtime" / "memory"),
+            ("cognitive", NEXO_HOME / "runtime" / "cognitive"),
+            ("coordination", NEXO_HOME / "runtime" / "coordination"),
+            ("exports", NEXO_HOME / "runtime" / "exports"),
+            ("nexo-email", NEXO_HOME / "runtime" / "nexo-email"),
+            ("doctor", NEXO_HOME / "runtime" / "doctor"),
+            ("snapshots", NEXO_HOME / "runtime" / "snapshots"),
+            ("crons", NEXO_HOME / "runtime" / "crons"),
+            ("skills", NEXO_HOME / "personal" / "skills"),
+            ("plugins", NEXO_HOME / "core" / "plugins"),
+            ("hooks", NEXO_HOME / "core" / "hooks"),
+            ("rules", NEXO_HOME / "core" / "rules"),
+        ]
+        for legacy_name, new_dir in TREE_MAP:
+            legacy = NEXO_HOME / legacy_name
+            if not legacy.is_dir() or legacy.is_symlink():
+                continue
+            new_dir.parent.mkdir(parents=True, exist_ok=True)
+            # Per-item move so we don't kill files via symlink-loop.
+            for item in list(legacy.iterdir()):
+                target = new_dir / item.name
+                if target.is_symlink() and target.resolve() == item.resolve():
+                    target.unlink()
+                if target.exists():
+                    if item.is_file() and target.is_file() and item.stat().st_size == target.stat().st_size:
+                        try:
+                            item.unlink()
+                            continue
+                        except Exception:
+                            pass
+                    # Backup conflict and proceed
+                    try:
+                        target.rename(target.with_suffix(target.suffix + ".f06bak"))
+                    except Exception:
+                        continue
+                try:
+                    shutil.move(str(item), str(target))
+                except Exception as e:
+                    _log(f"[F0.6] move {item} -> {target} failed: {e}")
+            try:
+                legacy.rmdir()
+            except OSError:
+                pass
+
+        # 6. UPDATE personal_scripts.path
+        try:
+            db = NEXO_HOME / "runtime" / "data" / "nexo.db"
+            if not db.is_file():
+                db = NEXO_HOME / "data" / "nexo.db"
+            if db.is_file():
+                conn = sqlite3.connect(str(db))
+                rows = conn.execute("SELECT id, path FROM personal_scripts").fetchall()
+                updates = []
+                legacy_root = str(NEXO_HOME / "scripts") + "/"
+                for row_id, old_path in rows:
+                    if not old_path or not old_path.startswith(legacy_root):
+                        continue
+                    name = Path(old_path).name
+                    cls = _classify(name)
+                    new_root = {
+                        "core": NEXO_HOME / "core" / "scripts",
+                        "personal": NEXO_HOME / "personal" / "scripts",
+                        "core-dev": NEXO_HOME / "core-dev" / "scripts",
+                    }[cls]
+                    updates.append((str(new_root / name), row_id))
+                if updates:
+                    conn.executemany("UPDATE personal_scripts SET path = ? WHERE id = ?", updates)
+                    conn.commit()
+                    _log(f"[F0.6] UPDATEd {len(updates)} personal_scripts.path rows")
+                conn.close()
+        except Exception as e:
+            _log(f"[F0.6] DB UPDATE failed (non-fatal): {e}")
+
+        # 7. Rewrite LaunchAgent plists
+        try:
+            la_dir = Path.home() / "Library" / "LaunchAgents"
+            count = 0
+            if la_dir.is_dir():
+                for plist in sorted(la_dir.glob("com.nexo.*.plist")):
+                    try:
+                        text = plist.read_text(encoding="utf-8")
+                    except Exception:
+                        continue
+                    original = text
+                    def _repl_script(m):
+                        full = m.group(0)
+                        name = Path(full).name
+                        cls = _classify(name)
+                        new_root = {
+                            "core": NEXO_HOME / "core" / "scripts",
+                            "personal": NEXO_HOME / "personal" / "scripts",
+                            "core-dev": NEXO_HOME / "core-dev" / "scripts",
+                        }[cls]
+                        return str(new_root / name)
+                    text = _re.sub(rf"{_re.escape(str(NEXO_HOME))}/scripts/[\w\-\.]+\.(py|sh|js)", _repl_script, text)
+                    text = text.replace(f"{NEXO_HOME}/logs/", f"{NEXO_HOME}/runtime/logs/")
+                    if text != original:
+                        plist.write_text(text, encoding="utf-8")
+                        count += 1
+                _log(f"[F0.6] rewrote {count} LaunchAgent plists")
+        except Exception as e:
+            _log(f"[F0.6] plist rewrite failed (non-fatal): {e}")
+
+        # 8. Write marker
+        try:
+            marker.write_text("F0.6\n", encoding="utf-8")
+            _log("[F0.6] marker written: ~/.nexo/.structure-version = F0.6")
+        except Exception as e:
+            _log(f"[F0.6] marker write failed: {e}")
+        _log("[F0.6] migration done")
+    except Exception as e:
+        _log(f"[F0.6] unexpected error (non-fatal, runtime keeps working): {e}")
+
+
 def _check_npm_version() -> str | None:
     """For non-git installs: check npm registry for a newer version. Returns notification or None."""
     current = _read_package_version()
@@ -2067,7 +2308,7 @@ def _sync_client_bootstraps(preferences: dict | None = None) -> list[str]:
 
 # ── Main entry point ─────────────────────────────────────────────────
 
-_AUTO_UPDATE_LOCK_FILE = NEXO_HOME / "operations" / ".auto_update.lock"
+_AUTO_UPDATE_LOCK_FILE = paths.operations_dir() / ".auto_update.lock"
 _AUTO_UPDATE_LOCK_STALE_SECONDS = 600  # 10 minutes
 
 
@@ -2265,10 +2506,10 @@ def _auto_update_check_locked() -> dict:
 
     # Backfill evolution-objective.json for existing installs
     try:
-        evo_obj_path = NEXO_HOME / "brain" / "evolution-objective.json"
+        evo_obj_path = paths.brain_dir() / "evolution-objective.json"
         from evolution_cycle import normalize_objective
         if not evo_obj_path.exists():
-            (NEXO_HOME / "brain").mkdir(parents=True, exist_ok=True)
+            (paths.brain_dir()).mkdir(parents=True, exist_ok=True)
             default_objective = {
                 "objective": "Improve operational excellence and reduce repeated errors",
                 "focus_areas": ["error_prevention", "proactivity", "memory_quality"],
@@ -2298,7 +2539,7 @@ def _auto_update_check_locked() -> dict:
 
     # Backfill NEXO_HOME/scripts/ for existing installs
     try:
-        scripts_dest = NEXO_HOME / "scripts"
+        scripts_dest = paths.core_scripts_dir()
         # Deduce NEXO_CODE: env var first, then from __file__ (auto_update.py is in src/)
         nexo_code = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent)))
         scripts_src = nexo_code / "scripts" if (nexo_code / "scripts").is_dir() else None
@@ -2336,7 +2577,7 @@ def _auto_update_check_locked() -> dict:
     # Backfill doctor package for existing installs
     try:
         doctor_src = SRC_DIR / "doctor"
-        doctor_dest = NEXO_HOME / "doctor"
+        doctor_dest = paths.doctor_dir()
         if doctor_src.is_dir():
             import shutil
             if not doctor_dest.is_dir():
@@ -2391,7 +2632,7 @@ def _auto_update_check_locked() -> dict:
     # Backfill MCP doctor plugin so existing installs expose nexo_doctor.
     try:
         plugin_src = SRC_DIR / "plugins" / "doctor.py"
-        plugin_dest = NEXO_HOME / "plugins" / "doctor.py"
+        plugin_dest = paths.core_plugins_dir() / "doctor.py"
         plugin_dest.parent.mkdir(parents=True, exist_ok=True)
         if plugin_src.is_file() and (not plugin_dest.exists() or plugin_src.stat().st_mtime > plugin_dest.stat().st_mtime):
             import shutil
@@ -2478,8 +2719,8 @@ def _auto_update_check_locked() -> dict:
     return result
 
 
-UPDATE_SUMMARY_FILE = NEXO_HOME / "logs" / "update-last-summary.json"
-UPDATE_HISTORY_FILE = NEXO_HOME / "logs" / "update-history.jsonl"
+UPDATE_SUMMARY_FILE = paths.logs_dir() / "update-last-summary.json"
+UPDATE_HISTORY_FILE = paths.logs_dir() / "update-history.jsonl"
 
 
 def _resolve_sync_source() -> tuple[Path | None, Path | None]:
@@ -2645,7 +2886,7 @@ def _installed_scripts_classification(dest: Path) -> dict[str, str]:
 
 def _backup_runtime_tree(dest: Path = NEXO_HOME) -> str:
     timestamp = time.strftime("%Y-%m-%d-%H%M%S")
-    backup_dir = NEXO_HOME / "backups" / f"runtime-tree-{timestamp}"
+    backup_dir = paths.backups_dir() / f"runtime-tree-{timestamp}"
     backup_dir.mkdir(parents=True, exist_ok=True)
 
     code_dirs = [
@@ -3090,7 +3331,7 @@ def _runtime_busy_reason() -> str | None:
 
 def _write_update_summary(summary: dict):
     try:
-        logs_dir = NEXO_HOME / "logs"
+        logs_dir = paths.logs_dir()
         logs_dir.mkdir(parents=True, exist_ok=True)
         payload = dict(summary)
         payload.setdefault("timestamp", time.strftime("%Y-%m-%dT%H:%M:%S"))

package/src/bootstrap_docs.py

@@ -193,7 +193,8 @@ def _target_path(client: str, *, user_home: Path | None = None) -> Path:
 
 
 def _version_tracker_path(nexo_home: Path, client: str) -> Path:
-    return nexo_home / "data" / BOOTSTRAP_SPECS[client]["version_file"]
+    import paths
+    return paths.data_dir() / BOOTSTRAP_SPECS[client]["version_file"]
 
 
 def render_bootstrap_template(

package/src/calibration_migration.py

@@ -54,7 +54,8 @@ TOP_LEVEL_KEYS = {"version", "created", "mood_history", "operator_name"}
 
 def _calibration_path(nexo_home: Path | None = None) -> Path:
     home = nexo_home or Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
-    return home / "brain" / "calibration.json"
+    import paths
+    return paths.brain_dir() / "calibration.json"
 
 
 def _is_nested(cal: dict) -> bool:
@@ -342,7 +343,9 @@ def apply_v6_purge(
         "seeded_default_resonance": False,
     }
 
-    cal_path = home / "brain" / "calibration.json"
+    _brain_new = home / "personal" / "brain"
+    _brain_legacy = home / "brain"
+    cal_path = (_brain_new if _brain_new.is_dir() else _brain_legacy) / "calibration.json"
     sched_path = home / "config" / "schedule.json"
 
     # --- calibration.json ---

package/src/cli.py

@@ -37,6 +37,7 @@ import contextlib
 import io
 import json
 import os
+import paths
 import shutil
 import subprocess
 import sys
@@ -303,7 +304,7 @@ def _scripts_list(args):
         print(json.dumps(scripts, indent=2))
     else:
         if not scripts:
-            print("No personal scripts found in", NEXO_HOME / "scripts")
+            print("No personal scripts found in", paths.core_scripts_dir())
             return 0
         # Table output
         name_w = max(len(s["name"]) for s in scripts)
@@ -347,7 +348,7 @@ def _scripts_classify(args):
 
     entries = report.get("entries", [])
     if not entries:
-        print("No scripts directory found:", report.get("scripts_dir", NEXO_HOME / "scripts"))
+        print("No scripts directory found:", report.get("scripts_dir", paths.core_scripts_dir()))
         return 0
 
     path_w = max(len(Path(entry["path"]).name) for entry in entries)
@@ -538,8 +539,8 @@ def _scripts_run(args):
 
     # Only inject DB paths for core scripts
     if is_core:
-        env["NEXO_DB"] = str(NEXO_HOME / "data" / "nexo.db")
-        env["NEXO_COGNITIVE_DB"] = str(NEXO_HOME / "data" / "cognitive.db")
+        env["NEXO_DB"] = str(paths.db_path())
+        env["NEXO_COGNITIVE_DB"] = str(paths.data_dir() / "cognitive.db")
 
     # Timeout
     timeout = None
@@ -1031,7 +1032,7 @@ def _update(args):
     # the sensory-register buffer. Keeps a .pre-v5.4.1.bak backup the first
     # time it runs on a given host.
     try:
-        buf = NEXO_HOME / "brain" / "session_buffer.jsonl"
+        buf = paths.brain_dir() / "session_buffer.jsonl"
         marker = buf.with_suffix(".jsonl.pre-v5.4.1.bak")
         if buf.is_file() and not marker.is_file():
             raw = buf.read_text(errors="ignore").splitlines()
@@ -1163,7 +1164,7 @@ def _write_calibration_default_resonance(tier: str) -> None:
     …). This helper keeps the CLI path writing to both calibration.json
     AND schedule.json so the two surfaces never disagree.
     """
-    cal_path = NEXO_HOME / "brain" / "calibration.json"
+    cal_path = paths.brain_dir() / "calibration.json"
     try:
         cal_path.parent.mkdir(parents=True, exist_ok=True)
         if cal_path.exists():

package/src/cron_recovery.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import json
 import os
+import paths
 import plistlib
 import sqlite3
 import contextlib
@@ -16,8 +17,8 @@ NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent
 LAUNCH_AGENTS_DIR = Path.home() / "Library" / "LaunchAgents"
 OPTIONALS_FILE = NEXO_HOME / "config" / "optionals.json"
 SCHEDULE_FILE = NEXO_HOME / "config" / "schedule.json"
-DB_PATH = NEXO_HOME / "data" / "nexo.db"
-STATE_FILE = NEXO_HOME / "operations" / ".catchup-state.json"
+DB_PATH = paths.db_path()
+STATE_FILE = paths.operations_dir() / ".catchup-state.json"
 
 
 def _local_timezone():
@@ -84,7 +85,7 @@ def resolve_declared_schedule(cron: dict) -> dict:
 
 def load_enabled_crons() -> list[dict]:
     manifest_candidates = [
-        NEXO_HOME / "crons" / "manifest.json",
+        paths.crons_dir() / "manifest.json",
         NEXO_CODE / "crons" / "manifest.json",
     ]
     optionals = _load_json(OPTIONALS_FILE, {})

package/src/db/_skills.py

@@ -11,6 +11,7 @@ Executable skills are indexed in SQLite but sourced from filesystem definitions.
 import datetime
 import json
 import os
+import paths
 import re
 import shutil
 from pathlib import Path
@@ -25,7 +26,7 @@ NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
 NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parents[1])))
 
 NEXO_ROOT = NEXO_CODE.parent
-PERSONAL_SKILLS_DIR = NEXO_HOME / "skills"
+PERSONAL_SKILLS_DIR = paths.personal_skills_dir()
 
 
 def _resolve_core_skills_dir() -> Path:

package/src/desktop_bridge.py

@@ -27,11 +27,13 @@ def _nexo_home() -> Path:
 
 
 def _calibration_path() -> Path:
-    return _nexo_home() / "brain" / "calibration.json"
+    import paths
+    return paths.brain_dir() / "calibration.json"
 
 
 def _profile_path() -> Path:
-    return _nexo_home() / "brain" / "profile.json"
+    import paths
+    return paths.brain_dir() / "profile.json"
 
 
 def _read_json(path: Path) -> dict: