nexo-brain 5.3.0 → 5.3.1

package/.claude-plugin/plugin.json

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

@@ -2210,15 +2210,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 +2262,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");

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "5.3.0",
+  "version": "5.3.1",
   "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'
     )
 
 
@@ -1451,9 +1490,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 +1624,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 +1691,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",

package/src/client_sync.py

@@ -18,6 +18,7 @@ except ModuleNotFoundError:  # Python < 3.11
     import tomli as tomllib
 
 from bootstrap_docs import sync_client_bootstrap
+from runtime_home import resolve_nexo_home
 
 try:
     from client_preferences import (
@@ -73,7 +74,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:

package/src/db/_personal_scripts.py

@@ -12,15 +12,30 @@ import os
 from pathlib import Path
 
 from db._core import get_db
+from runtime_home import resolve_nexo_home
 
 
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+NEXO_HOME = resolve_nexo_home()
 
 
 def _now_text() -> str:
     return datetime.datetime.now().isoformat(timespec="seconds")
 
 
+def _canonical_scripts_dir() -> Path:
+    home = resolve_nexo_home(os.environ.get("NEXO_HOME", str(NEXO_HOME)))
+    return home / "scripts"
+
+
+def _normalize_script_path(path: str | Path) -> str:
+    candidate = Path(path).expanduser()
+    try:
+        relative = candidate.resolve(strict=False).relative_to(_canonical_scripts_dir().resolve(strict=False))
+    except Exception:
+        return str(candidate)
+    return str(_canonical_scripts_dir() / relative)
+
+
 def _row_to_dict(row) -> dict:
     return dict(row) if row is not None else {}
 
@@ -61,6 +76,7 @@ def _safe_slug(value: str) -> str:
 
 
 def _ensure_script_id(conn, name: str, path: str) -> str:
+    path = _normalize_script_path(path)
     existing = conn.execute(
         "SELECT id FROM personal_scripts WHERE path = ? LIMIT 1",
         (path,),
@@ -90,6 +106,7 @@ def upsert_personal_script(
     has_inline_metadata: bool = False,
 ) -> dict:
     conn = get_db()
+    path = _normalize_script_path(path)
     script_id = _ensure_script_id(conn, name, path)
     now = _now_text()
     conn.execute(
@@ -132,11 +149,12 @@ def upsert_personal_script(
 
 def delete_missing_personal_scripts(active_paths: list[str]) -> int:
     conn = get_db()
-    if active_paths:
-        placeholders = ",".join("?" for _ in active_paths)
+    normalized_paths = [_normalize_script_path(path) for path in active_paths]
+    if normalized_paths:
+        placeholders = ",".join("?" for _ in normalized_paths)
         rows = conn.execute(
             f"SELECT id FROM personal_scripts WHERE path NOT IN ({placeholders})",
-            tuple(active_paths),
+            tuple(normalized_paths),
         ).fetchall()
     else:
         rows = conn.execute("SELECT id FROM personal_scripts").fetchall()
@@ -160,6 +178,7 @@ def register_personal_script_schedule(
     enabled: bool = True,
 ) -> dict | None:
     conn = get_db()
+    script_path = _normalize_script_path(script_path)
     script = conn.execute(
         "SELECT id FROM personal_scripts WHERE path = ?",
         (script_path,),
@@ -342,6 +361,7 @@ def list_personal_scripts(include_disabled: bool = True) -> list[dict]:
 
 def get_personal_script(name_or_path: str) -> dict | None:
     conn = get_db()
+    normalized_path = _normalize_script_path(name_or_path)
     row = conn.execute(
         """
         SELECT * FROM personal_scripts
@@ -349,7 +369,7 @@ def get_personal_script(name_or_path: str) -> dict | None:
         ORDER BY path = ? DESC
         LIMIT 1
         """,
-        (name_or_path, name_or_path, name_or_path),
+        (normalized_path, name_or_path, normalized_path),
     ).fetchone()
     if not row:
         return None
@@ -361,9 +381,10 @@ def get_personal_script(name_or_path: str) -> dict | None:
 
 def delete_personal_script(name_or_path: str) -> int:
     conn = get_db()
+    normalized_path = _normalize_script_path(name_or_path)
     result = conn.execute(
         "DELETE FROM personal_scripts WHERE path = ? OR name = ? OR id = ?",
-        (name_or_path, name_or_path, name_or_path),
+        (normalized_path, name_or_path, name_or_path),
     )
     return int(result.rowcount or 0)
 
@@ -371,13 +392,14 @@ def delete_personal_script(name_or_path: str) -> int:
 def record_personal_script_run(name_or_path: str, exit_code: int, run_at: str | None = None) -> None:
     conn = get_db()
     run_at = run_at or _now_text()
+    normalized_path = _normalize_script_path(name_or_path)
     conn.execute(
         """
         UPDATE personal_scripts
         SET last_run_at = ?, last_exit_code = ?, updated_at = ?
         WHERE path = ? OR name = ?
         """,
-        (run_at, exit_code, _now_text(), name_or_path, name_or_path),
+        (run_at, exit_code, _now_text(), normalized_path, name_or_path),
     )
 
 
@@ -393,7 +415,7 @@ def sync_personal_scripts_registry(
     scheduled = 0
 
     for record in script_records:
-        path = str(record["path"])
+        path = _normalize_script_path(record["path"])
         active_paths.append(path)
         upsert_personal_script(
             name=record.get("name") or Path(path).stem,

package/src/doctor/providers/runtime.py

@@ -84,6 +84,28 @@ def _release_root() -> Path:
     return Path(NEXO_CODE)
 
 
+def _has_release_publish_context(release_root: Path) -> bool:
+    git_dir = release_root / ".git"
+    if git_dir.exists() or git_dir.is_file():
+        return True
+    if _recorded_source_root() is not None:
+        return True
+    try:
+        release_root_resolved = release_root.resolve()
+        nexo_home_resolved = NEXO_HOME.resolve()
+    except Exception:
+        release_root_resolved = release_root
+        nexo_home_resolved = NEXO_HOME
+    if release_root_resolved == nexo_home_resolved:
+        return False
+    has_release_files = (
+        (release_root / "package.json").is_file()
+        and (release_root / "CHANGELOG.md").is_file()
+        and (release_root / "scripts" / "sync_release_artifacts.py").is_file()
+    )
+    return has_release_files
+
+
 def _package_json_path() -> Path:
     if PACKAGE_JSON.is_file():
         return PACKAGE_JSON
@@ -2660,13 +2682,27 @@ def check_release_artifact_sync() -> DoctorCheck:
     if changelog_version:
         evidence.append(f"top changelog version: {changelog_version}")
 
+    release_root = _release_root()
+    if not _has_release_publish_context(release_root):
+        if version:
+            evidence.append(f"package version: {version}")
+        evidence.append(f"release root: {release_root}")
+        evidence.append("packaged runtime without source repo; release artifact audit skipped")
+        return DoctorCheck(
+            id="runtime.release_artifacts",
+            tier="runtime",
+            status="healthy",
+            severity="info",
+            summary="Release artifact audit skipped for packaged runtime",
+            evidence=evidence,
+        )
+
     if version and changelog_version and version != changelog_version:
         status = "critical"
         severity = "error"
         evidence.append("package/changelog release version mismatch")
         repair_plan.append("Bump or align CHANGELOG.md before publishing")
 
-    release_root = _release_root()
     sync_script = release_root / "scripts" / "sync_release_artifacts.py"
     if not sync_script.is_file():
         status = "critical"

package/src/hooks/session-start.sh

@@ -4,6 +4,8 @@
 # Caches output for 1 hour to avoid regenerating on rapid successive sessions.
 set -uo pipefail
 
+NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
+
 # Fase 3 item 7: hook lifecycle observability — record duration + exit code
 # in hook_runs on EXIT. Best-effort: a failure here must not break the hook.
 NEXO_HOOK_START_MS=$(python3 -c "import time; print(int(time.time()*1000))" 2>/dev/null || echo 0)
@@ -18,8 +20,12 @@ _nexo_record_hook_run() {
             duration_ms=$((now_ms - NEXO_HOOK_START_MS))
         fi
     fi
-    local recorder
-    recorder="${NEXO_CODE:-/Users/franciscoc/Documents/_PhpstormProjects/nexo/src}/scripts/nexo-hook-record.py"
+    local recorder=""
+    if [ -n "${NEXO_CODE:-}" ] && [ -f "${NEXO_CODE%/}/scripts/nexo-hook-record.py" ]; then
+        recorder="${NEXO_CODE%/}/scripts/nexo-hook-record.py"
+    elif [ -f "$NEXO_HOME/scripts/nexo-hook-record.py" ]; then
+        recorder="$NEXO_HOME/scripts/nexo-hook-record.py"
+    fi
     if [ -f "$recorder" ]; then
         python3 "$recorder" record \
             --hook "$NEXO_HOOK_NAME" \
@@ -30,8 +36,6 @@ _nexo_record_hook_run() {
     fi
 }
 trap _nexo_record_hook_run EXIT
-
-NEXO_HOME="${NEXO_HOME:-$HOME/.nexo}"
 BRIEFING_FILE="$NEXO_HOME/coordination/session-briefing.txt"
 MAX_AGE_SECONDS=3600  # 1 hour cache
 

package/src/plugins/update.py

@@ -9,6 +9,8 @@ import sys
 import time
 from pathlib import Path
 
+from runtime_home import export_resolved_nexo_home
+
 # Code root is the parent of plugins/:
 # - source checkout: <repo>/src
 # - packaged runtime: <NEXO_HOME>
@@ -16,7 +18,7 @@ _THIS_DIR = Path(__file__).resolve().parent
 CODE_ROOT = _THIS_DIR.parent
 _REPO_CANDIDATE = CODE_ROOT.parent
 
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo")))
+NEXO_HOME = export_resolved_nexo_home()
 DATA_DIR = NEXO_HOME / "data"
 BACKUP_BASE = NEXO_HOME / "backups"
 
@@ -330,8 +332,23 @@ def _backup_code_tree() -> tuple[str | None, str | None]:
     timestamp = time.strftime("%Y-%m-%d-%H%M%S")
     backup_dir = BACKUP_BASE / f"code-tree-{timestamp}"
     # Directories and flat files that postinstall copies into NEXO_HOME
-    code_dirs = ["hooks", "plugins", "db", "cognitive", "dashboard", "rules", "crons", "scripts"]
-    code_files_glob = ["*.py", "requirements.txt"]
+    code_dirs = [
+        "bin",
+        "hooks",
+        "plugins",
+        "db",
+        "cognitive",
+        "dashboard",
+        "rules",
+        "crons",
+        "scripts",
+        "doctor",
+        "skills",
+        "skills-core",
+        "skills-runtime",
+        "templates",
+    ]
+    code_files_glob = ["*.py", "requirements.txt", "package.json"]
     try:
         backup_dir.mkdir(parents=True, exist_ok=True)
         # Backup directories
@@ -372,6 +389,54 @@ def _restore_code_tree(backup_dir: str) -> str | None:
     return None
 
 
+def _normalize_preferences_for_client_sync() -> dict:
+    from client_preferences import normalize_client_preferences
+
+    schedule_path = NEXO_HOME / "config" / "schedule.json"
+    schedule_payload = json.loads(schedule_path.read_text()) if schedule_path.exists() else {}
+    normalized_preferences = normalize_client_preferences(schedule_payload)
+    if normalized_preferences != {
+        key: schedule_payload.get(key)
+        for key in normalized_preferences
+    }:
+        merged_schedule = dict(schedule_payload)
+        merged_schedule.update(normalized_preferences)
+        schedule_path.parent.mkdir(parents=True, exist_ok=True)
+        schedule_path.write_text(json.dumps(merged_schedule, indent=2, ensure_ascii=False) + "\n")
+    return normalized_preferences
+
+
+def _sync_packaged_clients() -> tuple[bool, str | None]:
+    try:
+        from client_sync import sync_all_clients
+    except Exception as e:
+        return False, f"client sync import failed: {e}"
+
+    try:
+        preferences = _normalize_preferences_for_client_sync()
+        result = sync_all_clients(
+            nexo_home=NEXO_HOME,
+            runtime_root=NEXO_HOME,
+            operator_name=os.environ.get("NEXO_NAME", ""),
+            preferences=preferences,
+        )
+    except Exception as e:
+        return False, f"client sync failed: {e}"
+
+    if result.get("ok"):
+        return True, None
+
+    clients = result.get("clients", {})
+    failures = []
+    for key, payload in clients.items():
+        if payload.get("ok") or payload.get("skipped"):
+            continue
+        failures.append(f"{key}: {payload.get('error', 'unknown error')}")
+    if not failures:
+        failures.append("unknown client sync failure")
+    return False, "; ".join(failures)
+
+
 def _rollback_npm_package(target_version: str) -> str | None:
     """Rollback nexo-brain npm package to a specific version.
 
@@ -480,6 +545,20 @@ def _handle_packaged_update(progress_fn=None) -> str:
     if verify_err:
         errors.append(f"verification: {verify_err}")
 
+    hook_sync_warning = None
+    try:
+        _emit_progress(progress_fn, "Refreshing installed hooks and manifests...")
+        _refresh_installed_manifest()
+        _sync_hooks_to_home()
+    except Exception as e:
+        hook_sync_warning = f"{e}"
+
+    client_sync_warning = None
+    _emit_progress(progress_fn, "Refreshing shared client configs...")
+    clients_ok, client_sync_error = _sync_packaged_clients()
+    if not clients_ok:
+        client_sync_warning = client_sync_error or "unknown client sync error"
+
     if errors:
         # 5. Full rollback: restore code tree + DBs + pip deps + rollback npm package
         if code_backup_dir:
@@ -516,6 +595,14 @@ def _handle_packaged_update(progress_fn=None) -> str:
     lines = ["UPDATE SUCCESSFUL (packaged install)"]
     lines.append(f"  Version: {old_version} -> {new_version}")
     lines.append(f"  Backup: {backup_dir}")
+    if not hook_sync_warning:
+        lines.append("  Hooks: synced to NEXO_HOME")
+    else:
+        lines.append(f"  WARNING: hook sync: {hook_sync_warning}")
+    if not client_sync_warning:
+        lines.append("  Clients: configured client targets synced")
+    else:
+        lines.append(f"  WARNING: client sync: {client_sync_warning}")
     lines.append("")
     lines.append("MCP server restart needed to load new code.")
     return "\n".join(lines)

package/src/runtime_home.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+"""Shared helpers to resolve the managed NEXO home path."""
+
+import os
+from pathlib import Path
+
+
+def user_home() -> Path:
+    return Path(os.environ.get("HOME", str(Path.home()))).expanduser()
+
+
+def managed_nexo_home(*, home: Path | None = None) -> Path:
+    return (home or user_home()) / ".nexo"
+
+
+def legacy_nexo_home(*, home: Path | None = None) -> Path:
+    return (home or user_home()) / "claude"
+
+
+def resolve_nexo_home(value: str | os.PathLike[str] | None = None) -> Path:
+    home = user_home()
+    managed = managed_nexo_home(home=home)
+    candidate = Path(value).expanduser() if value else Path(
+        os.environ.get("NEXO_HOME", str(managed))
+    ).expanduser()
+    legacy = legacy_nexo_home(home=home)
+
+    if candidate == managed:
+        return managed
+    if candidate == legacy:
+        return managed if managed.exists() or legacy.is_symlink() else candidate
+
+    try:
+        if managed.exists() and candidate.resolve(strict=False) == managed.resolve(strict=False):
+            return managed
+    except Exception:
+        pass
+
+    return candidate
+
+
+def export_resolved_nexo_home(value: str | os.PathLike[str] | None = None) -> Path:
+    resolved = resolve_nexo_home(value)
+    os.environ["NEXO_HOME"] = str(resolved)
+    return resolved

package/src/script_registry.py

@@ -16,7 +16,9 @@ import stat
 import subprocess
 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)))
 
 # Internal artifacts to always ignore
@@ -73,6 +75,7 @@ METADATA_KEYS = {
     "run_on_wake",
     "idempotent",
     "max_catchup_age",
+    "doctor_allow_db",
 }
 SUPPORTED_RUNTIMES = {"python", "shell", "node", "php", "unknown"}
 PERSONAL_SCHEDULE_MANAGED_ENV = "NEXO_MANAGED_PERSONAL_CRON"
@@ -213,7 +216,11 @@ def _is_ignored(path: Path) -> bool:
         return True
     if path.name.startswith("."):
         return True
-    for parent in path.relative_to(get_scripts_dir()).parents:
+    try:
+        relative_path = path.resolve().relative_to(get_scripts_dir().resolve())
+    except Exception:
+        return False
+    for parent in relative_path.parents:
         if parent.name in _IGNORED_DIRS:
             return True
     return False
@@ -1425,14 +1432,19 @@ def doctor_script(path_or_name: str) -> dict:
             elif cmd:
                 items.append({"level": "pass", "msg": f"Required command found: {cmd}"})
 
+    allow_db_access = str(meta.get("doctor_allow_db", "")).strip().lower() in {"1", "true", "yes", "on"}
+    if allow_db_access:
+        items.append({"level": "pass", "msg": "Doctor DB access explicitly allowed"})
+
     # Forbidden patterns (only for personal scripts)
     if not is_core:
         try:
             content = p.read_text(errors="ignore")
-            for pat in _FORBIDDEN_PATTERNS:
-                match = pat.search(content)
-                if match:
-                    items.append({"level": "fail", "msg": f"Forbidden DB pattern found: {match.group()}"})
+            if not allow_db_access:
+                for pat in _FORBIDDEN_PATTERNS:
+                    match = pat.search(content)
+                    if match:
+                        items.append({"level": "fail", "msg": f"Forbidden DB pattern found: {match.group()}"})
         except Exception:
             pass
 

package/src/scripts/nexo-cognitive-decay.py

@@ -63,7 +63,7 @@ def _open_correction_fatigue_followup(fatigued: list) -> str:
         lines.append(f"... and {len(fatigued) - 10} more")
     description = "\n".join(lines)
     verification = (
-        "sqlite3 ~/claude/data/cognitive.db \"SELECT id, content, strength, tags "
+        "sqlite3 ~/.nexo/data/cognitive.db \"SELECT id, content, strength, tags "
         "FROM ltm_memories WHERE tags LIKE '%under_review%' ORDER BY strength ASC LIMIT 50\""
     )
     now_epoch = datetime.now().timestamp()

package/src/scripts/nexo-cortex-cycle.py

@@ -12,7 +12,7 @@ recommendation pattern could persist indefinitely between user reports.
 What this script does (idempotent and best-effort):
 
 1. Loads cortex_evaluation_summary for the last 7 days and last 1 day.
-2. Persists the snapshot to ~/claude/operations/cortex-quality-latest.json
+2. Persists the snapshot to ~/.nexo/operations/cortex-quality-latest.json
    so dashboards / morning briefings can read fresh metrics without
    re-running the SQL.
 3. Detects degradation signals on the 7-day window. The criteria are
@@ -25,7 +25,7 @@ What this script does (idempotent and best-effort):
    metrics when degradation is detected. Idempotent: if a non-PENDING /
    resolved followup of the same id already exists, it is updated in
    place rather than duplicated.
-5. Logs every run to ~/claude/logs/cortex-cycle.log.
+5. Logs every run to ~/.nexo/logs/cortex-cycle.log.
 
 Catchup-friendly: a stale plist firing twice in quick succession is fine.
 The quality file is rewritten in place, the followup is upserted, no

package/src/scripts/nexo-hook-record.py

@@ -3,7 +3,7 @@
 
 Closes Fase 3 item 7 of NEXO-AUDIT-2026-04-11. Bash hooks can call:
 
-    python3 ~/Documents/_PhpstormProjects/nexo/src/scripts/nexo-hook-record.py \
+    NEXO_HOME=~/.nexo python3 ~/.nexo/scripts/nexo-hook-record.py \
         --hook session-start --duration-ms 142 --exit $? --session $SID
 
 This script is intentionally minimal so it adds <50ms of latency to the

package/src/scripts/nexo-migrate.py

@@ -7,7 +7,7 @@ Usage:
     python3 nexo-migrate.py --from 1.6.0 # override detected current version
 
 Reads current version from $NEXO_HOME/version.json.
-Reads target version from the repo's package.json.
+Reads target version from the installed runtime package.json.
 Backs up NEXO_HOME/db/ before any migration.
 Runs DB schema migrations via the existing _schema.py system.
 """
@@ -16,13 +16,43 @@ import argparse
 import json
 import os
 import shutil
-import sqlite3
 import sys
 from datetime import datetime
 from pathlib import Path
 
-NEXO_HOME = Path(os.environ.get("NEXO_HOME", Path.home() / ".nexo"))
-REPO_ROOT = Path(__file__).resolve().parent.parent.parent  # nexo/src/scripts -> nexo/
+NEXO_HOME = Path(os.environ.get("NEXO_HOME", str(Path.home() / ".nexo"))).expanduser()
+SCRIPT_ROOT = Path(__file__).resolve().parent.parent
+
+
+def _resolve_runtime_root() -> Path:
+    candidates: list[Path] = []
+
+    raw_code = os.environ.get("NEXO_CODE", "").strip()
+    if raw_code:
+        env_code = Path(raw_code).expanduser()
+        candidates.append(env_code)
+        if env_code.name == "src":
+            candidates.append(env_code.parent)
+
+    candidates.extend([SCRIPT_ROOT, NEXO_HOME])
+
+    seen: set[str] = set()
+    for candidate in candidates:
+        candidate = candidate if candidate.is_dir() else candidate.parent
+        key = str(candidate)
+        if key in seen:
+            continue
+        seen.add(key)
+        if (candidate / "package.json").is_file():
+            return candidate
+        if (candidate / "src" / "server.py").is_file() and (candidate / "package.json").is_file():
+            return candidate
+
+    return SCRIPT_ROOT
+
+
+RUNTIME_ROOT = _resolve_runtime_root()
+SOURCE_ROOT = RUNTIME_ROOT / "src" if (RUNTIME_ROOT / "src" / "db").is_dir() else RUNTIME_ROOT
 
 
 # ── Version helpers ──────────────────────────────────────────────
@@ -56,8 +86,8 @@ def get_current_version() -> str:
 
 
 def get_target_version() -> str:
-    """Read target version from repo package.json."""
-    pkg = REPO_ROOT / "package.json"
+    """Read target version from installed runtime package.json."""
+    pkg = RUNTIME_ROOT / "package.json"
     if not pkg.exists():
         print(f"ERROR: package.json not found at {pkg}", file=sys.stderr)
         sys.exit(1)
@@ -107,10 +137,8 @@ def ensure_nexo_home_dirs():
 
 def run_db_schema_migrations():
     """Run the formal DB schema migration system from _schema.py."""
-    # Add src/ to path so we can import the db module
-    src_dir = REPO_ROOT / "src"
-    if str(src_dir) not in sys.path:
-        sys.path.insert(0, str(src_dir))
+    if str(SOURCE_ROOT) not in sys.path:
+        sys.path.insert(0, str(SOURCE_ROOT))
 
     # Set NEXO_HOME env for the db module
     os.environ["NEXO_HOME"] = str(NEXO_HOME)

package/src/state_watchers_runtime.py

@@ -374,7 +374,7 @@ def _open_watcher_followup(result: dict) -> dict:
     )
     description = "\n".join(description_lines)
     verification = (
-        f"sqlite3 ~/claude/data/nexo.db \"SELECT last_health, last_result "
+        f"sqlite3 ~/.nexo/data/nexo.db \"SELECT last_health, last_result "
         f"FROM state_watchers WHERE watcher_id = '{watcher_id}'\""
     )
 

package/templates/CLAUDE.md.template

@@ -1,4 +1,4 @@
-<!-- nexo-claude-md-version: 2.1.3 -->
+<!-- nexo-claude-md-version: 2.1.4 -->
 ******CORE******
 <!-- nexo:core:start -->
 # {{NAME}} — Cognitive Co-Operator
@@ -35,6 +35,12 @@ NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
 - For single-artifact asks, the default cap before the first visible answer is one lookup plus one detail read. Do not keep chaining tools before answering unless the user explicitly asked for more depth.
 - After `nexo_email_read`, `nexo_session_diary_read`, `nexo_reminders`, `nexo_followups`, or equivalent single-artifact retrieval, answer immediately. Do not launch another search, another read, or background analysis before the first user-visible answer unless the user explicitly asked for it.
 
+## Communication Guardrail
+- In the first answer to Francisco on any thread, lead with the direct recommendation, decision, or status.
+- Keep each decision point to 2-3 short sentences maximum. Hold extra detail unless he explicitly asks for it.
+- Do not use internal NEXO jargon in the first answer (`protocol debt`, `cortex evaluation`, `runtime check`, `guard_check`, `heartbeat`, etc.). Translate it into plain operational language.
+- Prefer conclusion plus next action over option dumps, raw diagnostics, or internal process narration. Apply this equally to chat replies, emails, briefings, and headless reports intended for Francisco.
+
 <!-- nexo:start:profile -->
 ## User Profile
 - **Calibration:** `{{NEXO_HOME}}/brain/calibration.json` (personality settings + language + user name)

package/templates/CODEX.AGENTS.md.template

@@ -1,4 +1,4 @@
-<!-- nexo-codex-agents-version: 1.2.3 -->
+<!-- nexo-codex-agents-version: 1.2.4 -->
 ******CORE******
 <!-- nexo:core:start -->
 # {{NAME}} — NEXO Shared Brain for Codex
@@ -32,6 +32,12 @@ NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
 - For single-artifact asks, the default cap before the first visible answer is one lookup plus one detail read. Do not keep chaining tools before answering unless the user explicitly asked for more depth.
 - After `nexo_email_read`, `nexo_session_diary_read`, `nexo_reminders`, `nexo_followups`, or equivalent single-artifact retrieval, answer immediately. Do not launch another search, another read, or background analysis before the first visible answer unless the user explicitly asked for it.
 
+## Communication Guardrail
+- In the first answer to Francisco on any thread, lead with the direct recommendation, decision, or status.
+- Keep each decision point to 2-3 short sentences maximum. Hold extra detail unless he explicitly asks for it.
+- Do not use internal NEXO jargon in the first answer (`protocol debt`, `cortex evaluation`, `runtime check`, `guard_check`, `heartbeat`, etc.). Translate it into plain operational language.
+- Prefer conclusion plus next action over option dumps, raw diagnostics, or internal process narration. Apply this equally to chat replies, emails, briefings, and headless reports intended for Francisco.
+
 ## Codex Runtime Notes
 - Codex does not provide Claude Code hooks, so protocol discipline must be explicit.
 - If a stable session token is useful, pass `session_token='codex-<task>-<date>'` and `session_client='codex'` to `nexo_startup`; otherwise leave them blank.

package/templates/nexo_helper.py

@@ -30,11 +30,15 @@ def _detect_nexo_home() -> Path:
     ):
         return inferred_home
 
+    default_home = Path.home() / ".nexo"
+    if default_home.is_dir():
+        return default_home
+
     claude_home = Path.home() / "claude"
     if claude_home.is_dir():
         return claude_home
 
-    return Path.home() / ".nexo"
+    return default_home
 
 
 NEXO_HOME = _detect_nexo_home()