nexo-brain 5.3.0 → 5.3.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.0",
+  "version": "5.3.2",
   "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

@@ -87,9 +87,18 @@ Versions `3.1.7` through `3.2.0` close the recent-memory gap:
 - when even that misses, NEXO now exposes raw transcript fallback tools for Claude Code and Codex session stores
 - NEXO can now inspect itself through a live system catalog derived from canonical sources instead of relying only on stale docs or operator memory
 
+Version `5.3.2` hardens the packaged runtime boundary: NEXO now persists which runtime scripts/hooks are core product artifacts, `nexo scripts` no longer mixes those into the personal bucket, and `nexo update` migrates the legacy Claude Code heartbeat wrappers into managed core hooks.
+
+Version `5.3.1` normalizes packaged npm installs so they behave like packaged npm installs: `nexo update` now keeps the runtime anchored to `~/.nexo`, refreshes packaged bootstrap/client artifacts after upgrade, avoids repo-only release-artifact drift in installed runtimes, and keeps personal scripts on the canonical packaged path.
+
 Version `5.3.0` adds `nexo uninstall` — a CLI command that cleanly separates runtime from user data. It stops all crons, removes the MCP server config, and preserves databases, learnings, and personal scripts for safe reinstall.
 
-Version `5.2.1` closes two focused gaps in the Cortex layer that were left open by the v5.1 audit — the high-stakes response-contract detector was English-only, and the `nexo-cortex-cycle` cron was writing a quality snapshot that no reader ever consumed:
+Version `5.2.1` fixes the Deep Sleep datetime regression and closes the decision-to-outcome feedback gap:
+
+- `_parse_any_datetime` in `apply_findings.py` now strips timezone info before comparison, fixing the offset-aware/offset-naive crash that was breaking Deep Sleep verification work.
+- `cortex_decide()` now auto-creates a `decision_outcome` when none is linked yet, so the outcome-checker cron can verify real decisions instead of leaving the loop open.
+
+Version `5.2.0` closes two focused gaps in the Cortex layer that were left open by the v5.1 audit — the high-stakes response-contract detector was English-only, and the `nexo-cortex-cycle` cron was writing a quality snapshot that no reader ever consumed:
 
 - `HIGH_STAKES_KEYWORDS_ES` adds ~45 Spanish keywords to the high-stakes detector with accented and unaccented variants, so a goal written in Spanish (`migrar la base de datos de producción`) trips the same gate as its English twin.
 - `NEGATION_PATTERNS` suppresses false positives when the user explicitly disclaims touching the sensitive area (`sin afectar producción`, `no tocar prod`, `without touching production`, `don't modify`). The raw keyword being present is no longer enough to flag the task.

package/bin/nexo-brain.js

@@ -93,6 +93,33 @@ function syncWatchdogHashRegistry(nexoHome) {
   }
 }
 
+function writeRuntimeCoreArtifactsManifest(nexoHome, srcDir) {
+  try {
+    const listTopLevelFiles = (dirPath) => {
+      if (!fs.existsSync(dirPath)) return [];
+      return fs.readdirSync(dirPath)
+        .filter((name) => {
+          const full = path.join(dirPath, name);
+          return fs.existsSync(full) && fs.statSync(full).isFile();
+        })
+        .sort();
+    };
+    const configDir = path.join(nexoHome, "config");
+    fs.mkdirSync(configDir, { recursive: true });
+    const payload = {
+      generated_at: new Date().toISOString(),
+      script_names: listTopLevelFiles(path.join(srcDir, "scripts")),
+      hook_names: listTopLevelFiles(path.join(srcDir, "hooks")),
+    };
+    fs.writeFileSync(
+      path.join(configDir, "runtime-core-artifacts.json"),
+      `${JSON.stringify(payload, null, 2)}\n`
+    );
+  } catch (err) {
+    log(`WARN: could not write runtime core-artifacts manifest: ${err.message}`);
+  }
+}
+
 function getCoreRuntimeFlatFiles() {
   return [
     "server.py",
@@ -1538,6 +1565,7 @@ async function main() {
             fs.chmodSync(path.join(scriptsDest, f), "755");
           });
         }
+        writeRuntimeCoreArtifactsManifest(NEXO_HOME, srcDir);
         log("  Scripts updated.");
 
         // Register ALL 8 core hooks in settings.json (additive — don't remove user's custom hooks)
@@ -2210,15 +2238,31 @@ async function main() {
     "#!/usr/bin/env bash",
     "set -euo pipefail",
     "",
-    `NEXO_HOME="${NEXO_HOME}"`,
+    `RUNTIME_HOME="${NEXO_HOME}"`,
+    'NEXO_HOME="$RUNTIME_HOME"',
     'export NEXO_HOME',
-    'export NEXO_CODE="${NEXO_CODE:-$NEXO_HOME}"',
+    'resolve_code_dir() {',
+    '  if [ -n "${NEXO_CODE:-}" ] && [ -f "${NEXO_CODE%/}/cli.py" ]; then',
+    '    printf \'%s\\n\' "${NEXO_CODE%/}"',
+    '    return 0',
+    '  fi',
+    '  if [ -f "$NEXO_HOME/cli.py" ]; then',
+    '    printf \'%s\\n\' "$NEXO_HOME"',
+    '    return 0',
+    '  fi',
+    '  printf \'%s\\n\' "$NEXO_HOME"',
+    '}',
+    'NEXO_CODE="$(resolve_code_dir)"',
+    'export NEXO_CODE',
     'resolve_python() {',
     '  local candidates=()',
     '  local candidate=""',
     '  if [ -n "${NEXO_RUNTIME_PYTHON:-}" ]; then candidates+=("$NEXO_RUNTIME_PYTHON"); fi',
     '  if [ -n "${NEXO_PYTHON:-}" ]; then candidates+=("$NEXO_PYTHON"); fi',
-    '  candidates+=("$NEXO_HOME/.venv/bin/python3" "$NEXO_HOME/.venv/bin/python")',
+    '  candidates+=("$NEXO_CODE/.venv/bin/python3" "$NEXO_CODE/.venv/bin/python")',
+    '  if [ "$NEXO_CODE" != "$NEXO_HOME" ]; then',
+    '    candidates+=("$NEXO_HOME/.venv/bin/python3" "$NEXO_HOME/.venv/bin/python")',
+    '  fi',
     '  case "$(uname -s)" in',
     '    Darwin) candidates+=("/opt/homebrew/bin/python3" "/usr/local/bin/python3") ;;',
     '    *) candidates+=("/usr/local/bin/python3" "/usr/bin/python3") ;;',
@@ -2246,7 +2290,17 @@ async function main() {
     '  echo "NEXO runtime Python not found. Run nexo-brain or nexo update to repair the installation." >&2',
     '  exit 1',
     'fi',
-    'exec "$PYTHON" "$NEXO_HOME/cli.py" "$@"',
+    'CLI_PY="$NEXO_CODE/cli.py"',
+    'if [ ! -f "$CLI_PY" ] && [ -f "$NEXO_HOME/cli.py" ]; then',
+    '  NEXO_CODE="$NEXO_HOME"',
+    '  export NEXO_CODE',
+    '  CLI_PY="$NEXO_HOME/cli.py"',
+    'fi',
+    'if [ ! -f "$CLI_PY" ]; then',
+    '  echo "NEXO CLI not found under $NEXO_HOME. Run nexo-brain or nexo update to repair the installation." >&2',
+    '  exit 1',
+    'fi',
+    'exec "$PYTHON" "$CLI_PY" "$@"',
     "",
   ].join("\n");
   const runtimeCliPath = path.join(NEXO_HOME, "bin", "nexo");
@@ -2333,6 +2387,7 @@ async function main() {
     });
     log("  Hooks installed.");
   }
+  writeRuntimeCoreArtifactsManifest(NEXO_HOME, srcDir);
 
   // Generate personality
   const personality = `# ${operatorName} — Personality

package/bin/nexo.js

@@ -12,7 +12,44 @@ const fs = require("fs");
 const os = require("os");
 const path = require("path");
 
-const NEXO_HOME = process.env.NEXO_HOME || path.join(os.homedir(), ".nexo");
+function resolveNexoHome(rawValue) {
+  const homeDir = os.homedir();
+  const managedHome = path.join(homeDir, ".nexo");
+  const legacyHome = path.join(homeDir, "claude");
+  const candidate = rawValue || managedHome;
+
+  if (candidate === managedHome) return managedHome;
+  if (candidate === legacyHome) return fs.existsSync(managedHome) ? managedHome : candidate;
+
+  try {
+    if (fs.existsSync(managedHome) && fs.realpathSync.native(candidate) === fs.realpathSync.native(managedHome)) {
+      return managedHome;
+    }
+  } catch {}
+
+  return candidate;
+}
+
+const NEXO_HOME = resolveNexoHome(process.env.NEXO_HOME);
+const NEXO_CODE = resolveCodeDir();
+
+function resolveCodeDir() {
+  const envCode = process.env.NEXO_CODE;
+  if (envCode && fs.existsSync(path.join(envCode, "cli.py"))) {
+    return envCode;
+  }
+  const repoCandidate = path.join(__dirname, "..", "src", "cli.py");
+  if (fs.existsSync(repoCandidate)) {
+    return path.join(__dirname, "..", "src");
+  }
+  if (fs.existsSync(path.join(NEXO_HOME, "cli.py"))) {
+    return NEXO_HOME;
+  }
+  if (fs.existsSync(path.join(NEXO_HOME, "claude", "cli.py"))) {
+    return path.join(NEXO_HOME, "claude");
+  }
+  return NEXO_HOME;
+}
 
 function pythonSupportsModule(candidate, moduleName) {
   if (!candidate) return false;
@@ -23,7 +60,7 @@ function pythonSupportsModule(candidate, moduleName) {
       env: {
         ...process.env,
         NEXO_HOME,
-        NEXO_CODE: path.join(__dirname, "..", "src"),
+        NEXO_CODE,
       },
     });
     return result.status === 0;
@@ -36,6 +73,8 @@ function findPython() {
   const candidates = [
     process.env.NEXO_RUNTIME_PYTHON,
     process.env.NEXO_PYTHON,
+    path.join(NEXO_CODE, ".venv", "bin", "python3"),
+    path.join(NEXO_CODE, ".venv", "bin", "python"),
     path.join(NEXO_HOME, ".venv", "bin", "python3"),
     path.join(NEXO_HOME, ".venv", "bin", "python"),
     process.platform === "darwin" ? "/opt/homebrew/bin/python3" : "",
@@ -55,10 +94,7 @@ function findPython() {
 }
 
 function findCliPy() {
-  const repoCandidate = path.join(__dirname, "..", "src", "cli.py");
-  const installedCandidate = path.join(NEXO_HOME, "cli.py");
-  if (fs.existsSync(repoCandidate)) return repoCandidate;
-  return installedCandidate;
+  return path.join(NEXO_CODE, "cli.py");
 }
 
 const python = findPython();
@@ -75,7 +111,7 @@ const result = spawnSync(python, [cliPy, ...process.argv.slice(2)], {
   env: {
     ...process.env,
     NEXO_HOME,
-    NEXO_CODE: path.join(__dirname, "..", "src"),
+    NEXO_CODE,
   },
 });
 

package/hooks/hooks.json

@@ -50,6 +50,18 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/heartbeat-user-msg.sh\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
     "PostToolUse": [
       {
         "matcher": "*",
@@ -73,6 +85,11 @@
             "type": "command",
             "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/protocol-guardrail.sh\"",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "NEXO_HOME=\"${CLAUDE_PLUGIN_DATA}\" NEXO_CODE=\"${CLAUDE_PLUGIN_ROOT}/src\" bash \"${CLAUDE_PLUGIN_ROOT}/src/hooks/heartbeat-posttool.sh\"",
+            "timeout": 3
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.0",
+  "version": "5.3.2",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO Brain — 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",
@@ -67,6 +67,7 @@
     "bin/nexo-brain.js",
     "bin/nexo.js",
     "bin/postinstall.js",
+    "scripts/sync_release_artifacts.py",
     "src/",
     "community/",
     "!src/**/__pycache__",

package/scripts/sync_release_artifacts.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+ROOT_PACKAGE_JSON = ROOT / "package.json"
+CLAUDE_PLUGIN_JSON = ROOT / ".claude-plugin" / "plugin.json"
+CLAWHUB_SKILL_MD = ROOT / "clawhub-skill" / "SKILL.md"
+OPENCLAW_PACKAGE_JSON = ROOT / "openclaw-plugin" / "package.json"
+OPENCLAW_MCP_BRIDGE = ROOT / "openclaw-plugin" / "src" / "mcp-bridge.ts"
+
+
+def fail(message: str) -> None:
+    raise SystemExit(f"[sync-release-artifacts] {message}")
+
+
+def load_json(path: Path) -> dict:
+    return json.loads(path.read_text())
+
+
+def dump_json(path: Path, payload: dict) -> None:
+    path.write_text(json.dumps(payload, indent=2) + "\n")
+
+
+def sync_json_version(path: Path, expected_version: str, label: str) -> bool:
+    payload = load_json(path)
+    if payload.get("version") == expected_version:
+        return False
+    payload["version"] = expected_version
+    dump_json(path, payload)
+    print(f"[sync-release-artifacts] synced {label} version -> {expected_version}")
+    return True
+
+
+def sync_clawhub_skill(skill_path: Path, expected_version: str) -> bool:
+    text = skill_path.read_text()
+    updated = text
+
+    updated = re.sub(
+        r"(?m)^version:\s*[^\n]+$",
+        f"version: {expected_version}",
+        updated,
+        count=1,
+    )
+    updated = updated.replace("~/.nexo/src/server.py", "~/.nexo/server.py")
+
+    if updated == text:
+        return False
+
+    skill_path.write_text(updated)
+    print(f"[sync-release-artifacts] synced ClawHub skill -> {expected_version}")
+    return True
+
+
+def sync_openclaw_bridge(bridge_path: Path, expected_version: str) -> bool:
+    text = bridge_path.read_text()
+    updated = text
+
+    updated = updated.replace(
+        'resolve(this.config.nexoHome, "src", "server.py")',
+        'resolve(this.config.nexoHome, "server.py")',
+    )
+    updated = re.sub(
+        r'clientInfo:\s*\{\s*name:\s*"openclaw-memory-nexo-brain",\s*version:\s*"[^"]+"\s*\}',
+        f'clientInfo: {{ name: "openclaw-memory-nexo-brain", version: "{expected_version}" }}',
+        updated,
+    )
+
+    if updated == text:
+        return False
+
+    bridge_path.write_text(updated)
+    print(f"[sync-release-artifacts] synced OpenClaw bridge -> {expected_version}")
+    return True
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Keep release-facing integration artifacts in sync.")
+    parser.add_argument("--release-version", help="Expected release version (must match root package.json).")
+    parser.add_argument("--check", action="store_true", help="Fail if any artifact would change.")
+    args = parser.parse_args()
+
+    root_package = load_json(ROOT_PACKAGE_JSON)
+    root_version = root_package.get("version")
+    if not root_version:
+        fail("root package.json is missing version")
+
+    if args.release_version and args.release_version != root_version:
+        fail(
+            f"release version {args.release_version} does not match root package.json version {root_version}"
+        )
+
+    original_payloads = {
+        CLAUDE_PLUGIN_JSON: CLAUDE_PLUGIN_JSON.read_text(),
+        CLAWHUB_SKILL_MD: CLAWHUB_SKILL_MD.read_text(),
+        OPENCLAW_PACKAGE_JSON: OPENCLAW_PACKAGE_JSON.read_text(),
+        OPENCLAW_MCP_BRIDGE: OPENCLAW_MCP_BRIDGE.read_text(),
+    }
+
+    changed = []
+    if sync_json_version(CLAUDE_PLUGIN_JSON, root_version, "Claude plugin"):
+        changed.append(".claude-plugin/plugin.json")
+    if sync_clawhub_skill(CLAWHUB_SKILL_MD, root_version):
+        changed.append("clawhub-skill/SKILL.md")
+    if sync_json_version(OPENCLAW_PACKAGE_JSON, root_version, "OpenClaw package"):
+        changed.append("openclaw-plugin/package.json")
+    if sync_openclaw_bridge(OPENCLAW_MCP_BRIDGE, root_version):
+        changed.append("openclaw-plugin/src/mcp-bridge.ts")
+
+    if args.check:
+        for path, text in original_payloads.items():
+            path.write_text(text)
+        if changed:
+            fail("artifacts out of sync: " + ", ".join(changed))
+        print("[sync-release-artifacts] OK")
+        return
+
+    if not changed:
+        print("[sync-release-artifacts] already in sync")
+
+
+if __name__ == "__main__":
+    main()

package/src/auto_update.py

@@ -17,7 +17,9 @@ import sys
 import time
 from pathlib import Path
 
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+from runtime_home import export_resolved_nexo_home, managed_nexo_home
+
+NEXO_HOME = export_resolved_nexo_home()
 DATA_DIR = NEXO_HOME / "data"
 DATA_DIR.mkdir(parents=True, exist_ok=True)
 
@@ -148,15 +150,42 @@ def _runtime_cli_wrapper_text() -> str:
     return (
         "#!/usr/bin/env bash\n"
         "set -euo pipefail\n\n"
-        f'NEXO_HOME="{NEXO_HOME}"\n'
+        f'DEFAULT_NEXO_HOME="{managed_nexo_home()}"\n'
+        'RUNTIME_HOME="${NEXO_HOME:-$DEFAULT_NEXO_HOME}"\n'
+        'if [ "$RUNTIME_HOME" = "${HOME}/claude" ] && [ -e "$DEFAULT_NEXO_HOME" ]; then\n'
+        '  RUNTIME_HOME="$DEFAULT_NEXO_HOME"\n'
+        'fi\n'
+        'if [ -e "$RUNTIME_HOME" ] && [ -e "$DEFAULT_NEXO_HOME" ]; then\n'
+        '  RESOLVED_RUNTIME="$(cd "$RUNTIME_HOME" 2>/dev/null && pwd -P || true)"\n'
+        '  RESOLVED_DEFAULT="$(cd "$DEFAULT_NEXO_HOME" 2>/dev/null && pwd -P || true)"\n'
+        '  if [ -n "$RESOLVED_RUNTIME" ] && [ "$RESOLVED_RUNTIME" = "$RESOLVED_DEFAULT" ]; then\n'
+        '    RUNTIME_HOME="$DEFAULT_NEXO_HOME"\n'
+        '  fi\n'
+        'fi\n'
+        'NEXO_HOME="$RUNTIME_HOME"\n'
         'export NEXO_HOME\n'
-        'export NEXO_CODE="${NEXO_CODE:-$NEXO_HOME}"\n'
+        'resolve_code_dir() {\n'
+        '  if [ -n "${NEXO_CODE:-}" ] && [ -f "${NEXO_CODE%/}/cli.py" ]; then\n'
+        '    printf \'%s\\n\' "${NEXO_CODE%/}"\n'
+        '    return 0\n'
+        '  fi\n'
+        '  if [ -f "$NEXO_HOME/cli.py" ]; then\n'
+        '    printf \'%s\\n\' "$NEXO_HOME"\n'
+        '    return 0\n'
+        '  fi\n'
+        '  printf \'%s\\n\' "$NEXO_HOME"\n'
+        '}\n'
+        'NEXO_CODE="$(resolve_code_dir)"\n'
+        'export NEXO_CODE\n'
         'resolve_python() {\n'
         '  local candidates=()\n'
         '  local candidate=""\n'
         '  if [ -n "${NEXO_RUNTIME_PYTHON:-}" ]; then candidates+=("$NEXO_RUNTIME_PYTHON"); fi\n'
         '  if [ -n "${NEXO_PYTHON:-}" ]; then candidates+=("$NEXO_PYTHON"); fi\n'
-        '  candidates+=("$NEXO_HOME/.venv/bin/python3" "$NEXO_HOME/.venv/bin/python")\n'
+        '  candidates+=("$NEXO_CODE/.venv/bin/python3" "$NEXO_CODE/.venv/bin/python")\n'
+        '  if [ "$NEXO_CODE" != "$NEXO_HOME" ]; then\n'
+        '    candidates+=("$NEXO_HOME/.venv/bin/python3" "$NEXO_HOME/.venv/bin/python")\n'
+        '  fi\n'
         '  case "$(uname -s)" in\n'
         '    Darwin) candidates+=("/opt/homebrew/bin/python3" "/usr/local/bin/python3") ;;\n'
         '    *) candidates+=("/usr/local/bin/python3" "/usr/bin/python3") ;;\n'
@@ -184,7 +213,17 @@ def _runtime_cli_wrapper_text() -> str:
         '  echo "NEXO runtime Python not found. Run nexo-brain or nexo update to repair the installation." >&2\n'
         '  exit 1\n'
         'fi\n'
-        'exec "$PYTHON" "$NEXO_HOME/cli.py" "$@"\n'
+        'CLI_PY="$NEXO_CODE/cli.py"\n'
+        'if [ ! -f "$CLI_PY" ] && [ -f "$NEXO_HOME/cli.py" ]; then\n'
+        '  NEXO_CODE="$NEXO_HOME"\n'
+        '  export NEXO_CODE\n'
+        '  CLI_PY="$NEXO_HOME/cli.py"\n'
+        'fi\n'
+        'if [ ! -f "$CLI_PY" ]; then\n'
+        '  echo "NEXO CLI not found under $NEXO_HOME. Run nexo-brain or nexo update to repair the installation." >&2\n'
+        '  exit 1\n'
+        'fi\n'
+        'exec "$PYTHON" "$CLI_PY" "$@"\n'
     )
 
 
@@ -320,6 +359,10 @@ 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",
     ]
     for target in retired:
         try:
@@ -1451,9 +1494,11 @@ def _resolve_sync_source() -> tuple[Path | None, Path | None]:
     if (
         not same_as_runtime
         and (NEXO_CODE / "db").is_dir()
-        and (NEXO_CODE.parent / "package.json").is_file()
     ):
-        return NEXO_CODE, NEXO_CODE.parent
+        if (NEXO_CODE.parent / "package.json").is_file():
+            return NEXO_CODE, NEXO_CODE.parent
+        if (NEXO_CODE / "package.json").is_file():
+            return NEXO_CODE, NEXO_CODE
 
     version_source = _runtime_version_source()
     if version_source:
@@ -1583,7 +1628,21 @@ def _backup_runtime_tree(dest: Path = NEXO_HOME) -> str:
     backup_dir = NEXO_HOME / "backups" / f"runtime-tree-{timestamp}"
     backup_dir.mkdir(parents=True, exist_ok=True)
 
-    code_dirs = ["hooks", "plugins", "db", "cognitive", "dashboard", "rules", "crons", "scripts", "doctor", "skills-core"]
+    code_dirs = [
+        "hooks",
+        "plugins",
+        "db",
+        "cognitive",
+        "dashboard",
+        "rules",
+        "crons",
+        "scripts",
+        "doctor",
+        "skills",
+        "skills-core",
+        "skills-runtime",
+        "templates",
+    ]
     flat_files = _runtime_flat_files(dest)
     for name in code_dirs:
         src = dest / name
@@ -1636,6 +1695,9 @@ def _copy_runtime_from_source(src_dir: Path, repo_dir: Path, dest: Path = NEXO_H
     script_conflicts: list[dict[str, str]] = []
     installed_script_classes = _installed_scripts_classification(dest)
 
+    for dirname in ("bin", "skills", "skills-core", "skills-runtime", "templates"):
+        (dest / dirname).mkdir(parents=True, exist_ok=True)
+
     _emit_progress(progress_fn, "Copying core packages...")
     for pkg in packages:
         pkg_src = src_dir / pkg

package/src/bootstrap_docs.py

@@ -16,6 +16,7 @@ from client_preferences import (
     normalize_client_key,
     normalize_client_preferences,
 )
+from runtime_home import resolve_nexo_home
 
 def _resolve_templates_dir(module_file: str | os.PathLike[str]) -> Path:
     module_dir = Path(module_file).resolve().parent
@@ -60,7 +61,7 @@ def _user_home() -> Path:
 
 
 def _default_nexo_home() -> Path:
-    return Path(os.environ.get("NEXO_HOME", str(_user_home() / ".nexo"))).expanduser()
+    return resolve_nexo_home(os.environ.get("NEXO_HOME", str(_user_home() / ".nexo")))
 
 
 def _resolve_operator_name(nexo_home: Path, explicit: str = "") -> str:
@@ -115,6 +116,18 @@ def _build_user_block(user_payload: str, template_text: str) -> str:
     return f"{USER_START}\n{user_payload.rstrip()}\n{USER_END}"
 
 
+def _extract_user_payload(text: str) -> str:
+    block = _extract_block(text, USER_START, USER_END)
+    if not block:
+        return ""
+    payload = block
+    if payload.startswith(USER_START):
+        payload = payload[len(USER_START):]
+    if payload.endswith(USER_END):
+        payload = payload[: -len(USER_END)]
+    return payload.strip("\n")
+
+
 def _legacy_user_payload(existing_text: str) -> str:
     cleaned = re.sub(r"<!--\s*nexo-[^-]+-[^-]+-version:\s*[\d.]+\s*-->\s*", "", existing_text)
     if "<!-- nexo:start:" in cleaned:
@@ -146,6 +159,33 @@ def _legacy_user_payload(existing_text: str) -> str:
     return cleaned.strip()
 
 
+def _home_alias(path: Path, user_home: Path) -> str:
+    try:
+        relative = path.expanduser().relative_to(user_home.expanduser())
+    except Exception:
+        return str(path.expanduser())
+    return "~/" + relative.as_posix()
+
+
+def _migrate_legacy_nexo_home_references(user_payload: str, *, nexo_home: Path, user_home: Path) -> str:
+    if not user_payload.strip():
+        return user_payload
+    legacy_home = user_home.expanduser() / "claude"
+    target_home = nexo_home.expanduser()
+    if legacy_home == target_home:
+        return user_payload
+
+    replacements = [
+        (str(legacy_home), str(target_home)),
+        (_home_alias(legacy_home, user_home), _home_alias(target_home, user_home)),
+    ]
+    updated = user_payload
+    for old, new in replacements:
+        if old and new and old != new:
+            updated = updated.replace(old, new)
+    return updated
+
+
 def _target_path(client: str, *, user_home: Path | None = None) -> Path:
     spec = BOOTSTRAP_SPECS[client]
     home = user_home or _user_home()
@@ -243,12 +283,23 @@ def sync_client_bootstrap(
 
     existing = target_path.read_text()
     if CORE_START in existing and CORE_END in existing and USER_START in existing and USER_END in existing:
-        user_block = _extract_block(existing, USER_START, USER_END) or _extract_block(rendered, USER_START, USER_END)
+        user_payload = _extract_user_payload(existing) or _extract_user_payload(rendered)
+        user_payload = _migrate_legacy_nexo_home_references(
+            user_payload,
+            nexo_home=nexo_home_path,
+            user_home=home_path,
+        )
+        user_block = _build_user_block(user_payload, rendered)
         updated = _replace_block(existing, CORE_START, CORE_END, rendered_core)
         updated = _replace_block(updated, USER_START, USER_END, user_block)
         action = "updated" if updated != existing else "unchanged"
     else:
         legacy_user = _legacy_user_payload(existing)
+        legacy_user = _migrate_legacy_nexo_home_references(
+            legacy_user,
+            nexo_home=nexo_home_path,
+            user_home=home_path,
+        )
         updated = _replace_block(rendered, USER_START, USER_END, _build_user_block(legacy_user, rendered))
         action = "migrated"
 

package/src/cli.py

@@ -40,7 +40,9 @@ import subprocess
 import sys
 from pathlib import Path
 
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+from runtime_home import export_resolved_nexo_home
+
+NEXO_HOME = export_resolved_nexo_home()
 NEXO_CODE = Path(os.environ.get("NEXO_CODE", str(Path(__file__).resolve().parent)))
 TERMINAL_CLIENT_LABELS = {
     "claude_code": "Claude Code",