nexo-brain 2.4.0 → 2.5.0

package/README.md

@@ -341,7 +341,7 @@ Deep Sleep generates a `session-tone.json` that tells NEXO how to behave next mo
 
 This is read by `nexo_smart_startup` and injected into every session's context. NEXO adapts its personality based on real behavioral data, not just configuration.
 
-## Cron Manifest (v2.1.0)
+## Cron Manifest & Scheduler (v2.4.0)
 
 All core crons are defined in `src/crons/manifest.json`. When you run `nexo_update`, the sync script:
 - **Installs** new crons from the manifest
@@ -349,7 +349,23 @@ All core crons are defined in `src/crons/manifest.json`. When you run `nexo_upda
 - **Removes** crons no longer in the manifest (only core ones)
 - **Never touches** personal crons you created yourself
 
-Run `python3 src/crons/sync.py --dry-run` to preview changes without applying.
+Every cron execution is tracked in the `cron_runs` table via a universal wrapper. Use `nexo_schedule_status` to see what ran overnight:
+
+```
+✅ deep-sleep: 1/1 OK, 4523s avg — 37 sessions, 259 findings
+✅ immune: 48/48 OK, 2s avg
+❌ evolution: 0/1 OK — CLI timeout
+```
+
+Add personal crons from conversation with `nexo_schedule_add` — generates LaunchAgent (macOS) or systemd timer (Linux) automatically.
+
+## Skill Auto-Creation (v2.4.0)
+
+Deep Sleep automatically extracts reusable procedures from successful multi-step tasks and stores them as skills with full procedural content (steps, gotchas, markdown).
+
+Pipeline: `trace → draft → published → archived`. Trust rises with successful use, decays without it. No human approval gates.
+
+7 MCP tools: `nexo_skill_create`, `nexo_skill_match`, `nexo_skill_get`, `nexo_skill_result`, `nexo_skill_list`, `nexo_skill_merge`, `nexo_skill_stats`.
 
 ## Dashboard (v1.6.0)
 
@@ -528,6 +544,38 @@ That's it. No need to run `claude` manually. Your operator will greet you immedi
 | Auto-diary | 3-layer system: PostToolUse every 10 calls, PreCompact emergency, heartbeat DIARY_OVERDUE | Built into hooks |
 | Claude Code config | MCP server + 7 hooks + 15 processes registered | ~/.claude/settings.json |
 
+### Runtime CLI
+
+After installation or auto-update, NEXO adds `NEXO_HOME/bin` to your shell `PATH`. Open a new terminal and the `nexo` command provides operational tools:
+
+```bash
+# Personal Scripts
+nexo scripts list              # List your personal scripts
+nexo scripts run my-script     # Run a script with injected NEXO env
+nexo scripts doctor            # Validate all personal scripts
+nexo scripts call nexo_learning_search --input '{"query":"cron"}' # Call any MCP tool
+
+# Skills v2
+nexo skills sync               # Sync filesystem skill definitions into SQLite
+nexo skills list               # List published/stable skills
+nexo skills get SK-...         # Inspect a skill definition
+nexo skills apply SK-... --dry-run --json  # Resolve guide/execute/hybrid without running it
+nexo skills approve SK-... --execution-level local --approved-by Francisco  # Optional metadata override
+nexo skills evolution          # Show text→script and improvement candidates
+
+# Unified Doctor
+nexo doctor                    # Quick boot diagnostics
+nexo doctor --tier all         # Full system check (boot + runtime + deep)
+nexo doctor --tier runtime --json  # Machine-readable health report
+nexo doctor --fix              # Apply deterministic repairs
+```
+
+Personal scripts live in `NEXO_HOME/scripts/` with inline metadata. See `docs/writing-scripts.md` for details.
+
+Skills v2 combine procedural guides with optional executable scripts. Personal skills live in `NEXO_HOME/skills/`, packaged core skills live in `NEXO_CODE/skills/` during development and `NEXO_HOME/skills-core/` in installed environments, and staged runtime copies live in `NEXO_HOME/skills-runtime/`. Execution is fully autonomous: Deep Sleep can evolve mature guide skills into executable drafts automatically, and runtime execution no longer waits for manual approval. See `docs/skills-v2.md` for the full model.
+
+The Doctor system reads existing health artifacts (immune, watchdog, self-audit) without triggering repairs in default mode.
+
 ### Requirements
 
 - **macOS or Linux** (Windows via [WSL](https://learn.microsoft.com/en-us/windows/wsl/install))
@@ -741,6 +789,21 @@ If NEXO Brain is useful to you, consider:
 
 ## Changelog
 
+### v2.4.0 — Skills, Cron Scheduler, Security, Full Audit (2026-04-03)
+- **Skill Auto-Creation**: Deep Sleep extracts reusable procedures from sessions. Content stored as markdown with steps and gotchas. Trust pipeline with autonomous quality control.
+- **Cron Scheduler**: execution tracking (`cron_runs` table), `nexo_schedule_status` and `nexo_schedule_add` MCP tools, universal cron wrapper for all processes.
+- **Deep Sleep v2.4**: watermark-based collection (late-night sessions included), per-session checkpointing (crash-safe), retry x3, JSON parsing fix, auto-calibration of personality settings.
+- **Security**: credential redaction in tool logs, transcript sanitization, command injection fix in dashboard, path traversal protection in plugin loader.
+- **Diary filter**: startup only shows human sessions, auto-closed cron sessions filtered out. Email sessions preserved as real interactions.
+- **Preflight CI**: 66 automated checks (py_compile, bash -n, manifest consistency, npm artifact, forbidden markers).
+- **Python 3.9 compat**: `from __future__ import annotations` across 18 files.
+- **Linux**: full systemd timer support, .bashrc alias for interactive shells.
+- Passed 5-phase automated audit: Product, Failure, Security, Packaging, UX.
+
+### v2.2.0 — Trust Score v2 (2026-04-01)
+- **Trust Score**: fair daily calibration from Deep Sleep analysis. Score 0-100 based on corrections, autonomy, proactivity.
+- **Cognitive Quarantine**: new memories go through quarantine before promotion to LTM.
+
 ### v2.0.0 — Unified Architecture (2026-03-31)
 - **Code/data separation**: Code in repo (`src/`), personal data in `NEXO_HOME` (default `~/.nexo/`). `NEXO_HOME` env var required.
 - **Plugin loader dual-directory**: Scans `src/plugins/` (base) then `NEXO_HOME/plugins/` (personal override by filename).

package/bin/nexo-brain.js

@@ -31,6 +31,13 @@ const LAUNCH_AGENTS = path.join(
   "LaunchAgents"
 );
 
+function isEphemeralInstall(nexoHome) {
+  const homeDir = require("os").homedir();
+  const allowEphemeral = process.env.NEXO_ALLOW_EPHEMERAL_INSTALL === "1";
+  if (allowEphemeral) return false;
+  return nexoHome.startsWith("/tmp/") || homeDir.startsWith("/tmp/");
+}
+
 const rl = readline.createInterface({
   input: process.stdin,
   output: process.stdout,
@@ -66,9 +73,9 @@ const ALL_PROCESSES = [
   // --- Every 5 minutes ---
   { name: "auto-close-sessions", script: "auto_close_sessions.py", interpreter: "python", scriptDir: "root",
     type: "interval", intervalMinutes: 5, purpose: "Clean stale sessions" },
-  { name: "watchdog", script: "nexo-watchdog.sh", interpreter: "bash", scriptDir: "scripts",
-    type: "interval", intervalMinutes: 5, purpose: "Health monitoring" },
   // --- Every 30 minutes ---
+  { name: "watchdog", script: "nexo-watchdog.sh", interpreter: "bash", scriptDir: "scripts",
+    type: "interval", intervalMinutes: 30, purpose: "Health monitoring" },
   { name: "immune", script: "nexo-immune.py", interpreter: "python", scriptDir: "scripts",
     type: "interval", intervalMinutes: 30, purpose: "System immunity checks" },
   // --- Every 2 hours ---
@@ -86,6 +93,10 @@ const ALL_PROCESSES = [
   // --- KeepAlive (persistent daemon) ---
   { name: "prevent-sleep", script: "nexo-prevent-sleep.sh", interpreter: "bash", scriptDir: "scripts",
     type: "keepAlive", purpose: "Keep machine awake for nocturnal processes" },
+  { name: "dashboard", script: "nexo-dashboard.sh", interpreter: "bash", scriptDir: "scripts",
+    type: "keepAlive", optional: "dashboard", purpose: "Web dashboard at localhost:6174" },
+  { name: "day-orchestrator", script: "nexo-day-orchestrator.sh", interpreter: "bash", scriptDir: "scripts",
+    type: "keepAlive", optional: "orchestrator", purpose: "Autonomous NEXO cycles every 15 min (8:00-23:00)" },
   // --- Daily (times from schedule.json) ---
   { name: "cognitive-decay", script: "nexo-cognitive-decay.py", interpreter: "python", scriptDir: "scripts",
     type: "daily", defaultHour: 3, defaultMinute: 0, purpose: "Memory decay" },
@@ -262,7 +273,7 @@ const DAY_MAP = {
  * Linux+systemd: .service + .timer files
  * Linux fallback: crontab entries
  */
-function installAllProcesses(platform, pythonPath, nexoHome, schedule, launchAgentsDir) {
+function installAllProcesses(platform, pythonPath, nexoHome, schedule, launchAgentsDir, enabledOptionals = {}) {
   const home = require("os").homedir();
   const nexoCode = nexoHome;
   const logsDir = path.join(nexoHome, "logs");
@@ -298,6 +309,8 @@ function installAllProcesses(platform, pythonPath, nexoHome, schedule, launchAge
     for (const proc of ALL_PROCESSES) {
       // Skip macOnly processes on Linux
       if (proc.macOnly && platform !== "darwin") continue;
+      // Skip optional processes that weren't enabled
+      if (proc.optional && !enabledOptionals[proc.optional]) continue;
 
       const plistName = `com.nexo.${proc.name}.plist`;
       const plistPath = path.join(launchAgentsDir, plistName);
@@ -404,6 +417,7 @@ function installAllProcesses(platform, pythonPath, nexoHome, schedule, launchAge
 
       for (const proc of ALL_PROCESSES) {
         if (proc.macOnly) continue; // tcc-approve is macOS only
+        if (proc.optional && !enabledOptionals[proc.optional]) continue;
         const serviceName = `nexo-${proc.name}`;
         const serviceFile = path.join(systemdDir, `${serviceName}.service`);
         const timerFile = path.join(systemdDir, `${serviceName}.timer`);
@@ -481,6 +495,7 @@ WantedBy=timers.target
       const envLine2 = `NEXO_CODE=${nexoCode}`;
 
       for (const proc of ALL_PROCESSES) {
+        if (proc.optional && !enabledOptionals[proc.optional]) continue;
         const sPath = scriptPath(proc);
         const interp = interpreterPath(proc);
         const s = getSchedule(proc);
@@ -729,8 +744,13 @@ async function main() {
         // Regenerate ALL 13 LaunchAgents / systemd timers
         const migSchedule = loadOrCreateSchedule(NEXO_HOME);
         const migPython = findVenvPython(NEXO_HOME) || "python3";
-        installAllProcesses(platform, migPython, NEXO_HOME, migSchedule, LAUNCH_AGENTS);
-        log("  All 13 automated processes updated.");
+        let migOptionals = {};
+        try {
+          const optFile = path.join(NEXO_HOME, "config", "optionals.json");
+          if (fs.existsSync(optFile)) migOptionals = JSON.parse(fs.readFileSync(optFile, "utf8"));
+        } catch {}
+        installAllProcesses(platform, migPython, NEXO_HOME, migSchedule, LAUNCH_AGENTS, migOptionals);
+        log("  All automated processes updated.");
 
         // Update version file
         fs.writeFileSync(versionFile, JSON.stringify({
@@ -776,7 +796,7 @@ async function main() {
       // Same version — backfill crons/ if missing (for installs before crons was shipped)
       const cronsDest = path.join(NEXO_HOME, "crons");
       const cronsSrc = path.join(__dirname, "..", "src", "crons");
-      if (!fs.existsSync(path.join(cronsDest, "manifest.json")) && fs.existsSync(cronsSrc)) {
+      if (fs.existsSync(cronsSrc)) {
         const copyDirRec2 = (src, dest) => {
           fs.mkdirSync(dest, { recursive: true });
           fs.readdirSync(src).forEach(item => {
@@ -788,7 +808,61 @@ async function main() {
           });
         };
         copyDirRec2(cronsSrc, cronsDest);
-        log("Backfilled crons/ directory (catchup & watchdog need it).");
+        log("Refreshed crons/ directory.");
+
+        const cronSyncPath = path.join(cronsSrc, "sync.py");
+        const syncPython = findVenvPython(NEXO_HOME) || run("which python3") || "python3";
+        if (fs.existsSync(cronSyncPath)) {
+          const syncResult = spawnSync(syncPython, [cronSyncPath], {
+            env: { ...process.env, NEXO_HOME, NEXO_CODE: path.join(__dirname, "..", "src") },
+            stdio: "pipe",
+            encoding: "utf8",
+          });
+          if (syncResult.status === 0) {
+            log("Core crons reconciled with manifest.");
+          } else {
+            const syncErr = (syncResult.stderr || syncResult.stdout || "").trim();
+            log(`Cron sync warning: ${syncErr || `exit ${syncResult.status}`}`);
+          }
+        }
+      }
+
+      // Same version — refresh packaged core skills/templates/runtime helpers too.
+      const skillsCoreDest = path.join(NEXO_HOME, "skills-core");
+      const skillsCoreSrc = path.join(__dirname, "..", "src", "skills");
+      if (fs.existsSync(skillsCoreSrc)) {
+        const copyDirRec3 = (src, dest) => {
+          fs.mkdirSync(dest, { recursive: true });
+          fs.readdirSync(src).forEach(item => {
+            if (item === "__pycache__" || item.endsWith(".pyc")) return;
+            const srcP = path.join(src, item);
+            const destP = path.join(dest, item);
+            if (fs.statSync(srcP).isDirectory()) copyDirRec3(srcP, destP);
+            else fs.copyFileSync(srcP, destP);
+          });
+        };
+        copyDirRec3(skillsCoreSrc, skillsCoreDest);
+        log("Refreshed skills-core/ directory.");
+      }
+
+      ["skills_runtime.py"].forEach((fname) => {
+        const srcFile = path.join(__dirname, "..", "src", fname);
+        const destFile = path.join(NEXO_HOME, fname);
+        if (fs.existsSync(srcFile)) {
+          fs.copyFileSync(srcFile, destFile);
+        }
+      });
+
+      const templatesSrc = path.join(__dirname, "..", "templates");
+      const templatesDest = path.join(NEXO_HOME, "templates");
+      if (fs.existsSync(templatesSrc)) {
+        fs.mkdirSync(templatesDest, { recursive: true });
+        ["script-template.py", "nexo_helper.py", "skill-template.md", "skill-script-template.py"].forEach((f) => {
+          const src = path.join(templatesSrc, f);
+          if (fs.existsSync(src)) {
+            fs.copyFileSync(src, path.join(templatesDest, f));
+          }
+        });
       }
 
       log(`Already at v${currentVersion}. No migration needed.`);
@@ -895,6 +969,12 @@ async function main() {
       caffeinateQ: "  Keep Mac awake for my cognitive processes at night?\n  (I consolidate memory, clean duplicates, and discover connections while you sleep)\n    1. Yes\n    2. No\n  > ",
       caffYes: "Nocturnal processes scheduled.",
       caffNo: "Ok, I'll run them when I can.",
+      dashboardQ: "  Enable web dashboard at localhost:6174?\n  (Always-on UI to explore memory, sessions, learnings, and system health)\n    1. Yes\n    2. No\n  > ",
+      dashYes: "Dashboard enabled.",
+      dashNo: "Dashboard disabled. You can start it manually: nexo dashboard",
+      orchestratorQ: "  Enable autonomous mode? (I'll work on my own every 15 min: check followups, emails, infra, and report by email)\n    1. Yes\n    2. No\n  > ",
+      orchYes: "Autonomous mode enabled. I'll be working for you 8:00-23:00.",
+      orchNo: "Autonomous mode disabled. I'll only work when you open a session.",
       autoInstallQ: "  Can I install tools automatically if I need them? (brew, pip, npm)\n    1. Yes, install whatever you need\n    2. Ask me before installing anything\n  > ",
       autoInstallYes: "Auto-install enabled.",
       autoInstallNo: "I'll ask before installing.",
@@ -924,6 +1004,12 @@ async function main() {
       caffeinateQ: "  ¿Mantengo el Mac despierto para mis procesos cognitivos nocturnos?\n  (Consolido memoria, limpio duplicados y descubro conexiones mientras duermes)\n    1. Sí\n    2. No\n  > ",
       caffYes: "Procesos nocturnos programados.",
       caffNo: "Ok, los ejecutaré cuando pueda.",
+      dashboardQ: "  ¿Activar el dashboard web en localhost:6174?\n  (UI siempre activa para explorar memoria, sesiones, learnings y salud del sistema)\n    1. Sí\n    2. No\n  > ",
+      dashYes: "Dashboard activado.",
+      dashNo: "Dashboard desactivado. Puedes iniciarlo manualmente: nexo dashboard",
+      orchestratorQ: "  ¿Activar modo autónomo? (Trabajo solo cada 15 min: reviso followups, emails, infra, y te informo por email)\n    1. Sí\n    2. No\n  > ",
+      orchYes: "Modo autónomo activado. Estaré trabajando para ti de 8:00 a 23:00.",
+      orchNo: "Modo autónomo desactivado. Solo trabajo cuando abras sesión.",
       autoInstallQ: "  ¿Puedo instalar herramientas automáticamente si las necesito? (brew, pip, npm)\n    1. Sí, instala lo que necesites\n    2. Pregúntame antes de instalar algo\n  > ",
       autoInstallYes: "Auto-instalación activada.",
       autoInstallNo: "Te preguntaré antes.",
@@ -953,6 +1039,12 @@ async function main() {
       caffeinateQ: "  Garder le Mac éveillé pour mes processus nocturnes ?\n    1. Oui\n    2. Non\n  > ",
       caffYes: "Processus nocturnes programmés.",
       caffNo: "Ok, je les exécuterai quand possible.",
+      dashboardQ: "  Activer le dashboard web sur localhost:6174 ?\n  (UI toujours active pour explorer mémoire, sessions et santé du système)\n    1. Oui\n    2. Non\n  > ",
+      dashYes: "Dashboard activé.",
+      dashNo: "Dashboard désactivé. Démarrage manuel : nexo dashboard",
+      orchestratorQ: "  Activer le mode autonome ? (Je travaille seul toutes les 15 min : followups, emails, infra, rapport par email)\n    1. Oui\n    2. Non\n  > ",
+      orchYes: "Mode autonome activé. Je travaille pour vous de 8h à 23h.",
+      orchNo: "Mode autonome désactivé. Je travaille uniquement en session.",
       autoInstallQ: "  Puis-je installer des outils automatiquement ? (brew, pip, npm)\n    1. Oui\n    2. Demande-moi avant\n  > ",
       autoInstallYes: "Auto-installation activée.",
       autoInstallNo: "Je demanderai avant.",
@@ -982,6 +1074,12 @@ async function main() {
       caffeinateQ: "  Mac wach halten für nächtliche Prozesse?\n    1. Ja\n    2. Nein\n  > ",
       caffYes: "Nachtprozesse geplant.",
       caffNo: "Ok, führe sie aus wenn möglich.",
+      dashboardQ: "  Web-Dashboard auf localhost:6174 aktivieren?\n  (Immer aktive UI für Speicher, Sitzungen und Systemgesundheit)\n    1. Ja\n    2. Nein\n  > ",
+      dashYes: "Dashboard aktiviert.",
+      dashNo: "Dashboard deaktiviert. Manuell starten: nexo dashboard",
+      orchestratorQ: "  Autonomen Modus aktivieren? (Ich arbeite alle 15 Min selbstständig: Followups, E-Mails, Infra, Bericht per E-Mail)\n    1. Ja\n    2. Nein\n  > ",
+      orchYes: "Autonomer Modus aktiviert. Ich arbeite für dich von 8:00 bis 23:00.",
+      orchNo: "Autonomer Modus deaktiviert. Ich arbeite nur in Sitzungen.",
       autoInstallQ: "  Darf ich Tools automatisch installieren? (brew, pip, npm)\n    1. Ja\n    2. Frag mich vorher\n  > ",
       autoInstallYes: "Auto-Installation aktiviert.",
       autoInstallNo: "Frage vorher.",
@@ -1011,6 +1109,12 @@ async function main() {
       caffeinateQ: "  Tenere il Mac sveglio per i processi notturni?\n    1. Sì\n    2. No\n  > ",
       caffYes: "Processi notturni programmati.",
       caffNo: "Ok, li eseguirò quando possibile.",
+      dashboardQ: "  Attivare la dashboard web su localhost:6174?\n  (UI sempre attiva per esplorare memoria, sessioni e salute del sistema)\n    1. Sì\n    2. No\n  > ",
+      dashYes: "Dashboard attivata.",
+      dashNo: "Dashboard disattivata. Avvio manuale: nexo dashboard",
+      orchestratorQ: "  Attivare la modalità autonoma? (Lavoro da solo ogni 15 min: followup, email, infra, report via email)\n    1. Sì\n    2. No\n  > ",
+      orchYes: "Modalità autonoma attivata. Lavoro per te dalle 8:00 alle 23:00.",
+      orchNo: "Modalità autonoma disattivata. Lavoro solo nelle sessioni.",
       autoInstallQ: "  Posso installare strumenti automaticamente? (brew, pip, npm)\n    1. Sì\n    2. Chiedimi prima\n  > ",
       autoInstallYes: "Auto-installazione attivata.",
       autoInstallNo: "Chiederò prima.",
@@ -1040,6 +1144,12 @@ async function main() {
       caffeinateQ: "  Manter o Mac acordado para processos noturnos?\n    1. Sim\n    2. Não\n  > ",
       caffYes: "Processos noturnos agendados.",
       caffNo: "Ok, executo quando possível.",
+      dashboardQ: "  Ativar dashboard web em localhost:6174?\n  (UI sempre ativa para explorar memória, sessões e saúde do sistema)\n    1. Sim\n    2. Não\n  > ",
+      dashYes: "Dashboard ativado.",
+      dashNo: "Dashboard desativado. Iniciar manualmente: nexo dashboard",
+      orchestratorQ: "  Ativar modo autônomo? (Trabalho sozinho a cada 15 min: followups, emails, infra, relatório por email)\n    1. Sim\n    2. Não\n  > ",
+      orchYes: "Modo autônomo ativado. Trabalho para você das 8:00 às 23:00.",
+      orchNo: "Modo autônomo desativado. Trabalho apenas nas sessões.",
       autoInstallQ: "  Posso instalar ferramentas automaticamente? (brew, pip, npm)\n    1. Sim\n    2. Pergunta antes\n  > ",
       autoInstallYes: "Auto-instalação ativada.",
       autoInstallNo: "Perguntarei antes.",
@@ -1158,6 +1268,8 @@ async function main() {
   // Step 5: Deep scan (P9)
   let doScan = false;
   let doCaffeinate = false;
+  let doDashboard = false;
+  let doOrchestrator = false;
   let autoInstall = "ask";
   if (!useDefaults) {
     const scanAnswer = await ask(t.scanQ);
@@ -1172,6 +1284,18 @@ async function main() {
       console.log("");
     }
 
+    // Step 6b: Dashboard — always-on web UI
+    const dashAnswer = await ask(t.dashboardQ);
+    doDashboard = dashAnswer.trim() === "1" || dashAnswer.trim().toLowerCase().startsWith("y") || dashAnswer.trim().toLowerCase().startsWith("s");
+    log(doDashboard ? `✓ ${t.dashYes}` : t.dashNo);
+    console.log("");
+
+    // Step 6c: Day Orchestrator — autonomous NEXO cycles
+    const orchAnswer = await ask(t.orchestratorQ);
+    doOrchestrator = orchAnswer.trim() === "1" || orchAnswer.trim().toLowerCase().startsWith("y") || orchAnswer.trim().toLowerCase().startsWith("s");
+    log(doOrchestrator ? `✓ ${t.orchYes}` : t.orchNo);
+    console.log("");
+
     // Step 7: Auto-install permission (P11)
     const autoInstallAnswer = await ask(t.autoInstallQ);
     autoInstall = (autoInstallAnswer.trim() === "1" || autoInstallAnswer.trim().toLowerCase().startsWith("y") || autoInstallAnswer.trim().toLowerCase().startsWith("s")) ? "auto" : "ask";
@@ -1224,8 +1348,12 @@ async function main() {
   log("Setting up NEXO home...");
   const dirs = [
     NEXO_HOME,
+    path.join(NEXO_HOME, "bin"),
     path.join(NEXO_HOME, "plugins"),
     path.join(NEXO_HOME, "scripts"),
+    path.join(NEXO_HOME, "skills"),
+    path.join(NEXO_HOME, "skills-core"),
+    path.join(NEXO_HOME, "skills-runtime"),
     path.join(NEXO_HOME, "logs"),
     path.join(NEXO_HOME, "backups"),
     path.join(NEXO_HOME, "coordination"),
@@ -1275,6 +1403,7 @@ async function main() {
   const srcDir = path.join(__dirname, "..", "src");
   const pluginsSrcDir = path.join(srcDir, "plugins");
   const scriptsSrcDir = path.join(srcDir, "scripts");
+  const skillsSrcDir = path.join(srcDir, "skills");
   const templateDir = path.join(__dirname, "..", "templates");
 
   // Recursive copy helper (skips __pycache__, .pyc, .db files)
@@ -1315,6 +1444,9 @@ async function main() {
     "tools_task_history.py",
     "tools_menu.py",
     "requirements.txt",
+    "cli.py",
+    "script_registry.py",
+    "skills_runtime.py",
   ];
   coreFiles.forEach((f) => {
     const src = path.join(srcDir, f);
@@ -1323,8 +1455,31 @@ async function main() {
     }
   });
 
+  // Runtime CLI wrapper lives in NEXO_HOME/bin so it survives npx installs.
+  const runtimeCli = [
+    "#!/usr/bin/env bash",
+    "set -euo pipefail",
+    "",
+    `NEXO_HOME="${NEXO_HOME}"`,
+    'PYTHON="$NEXO_HOME/.venv/bin/python3"',
+    'if [ ! -x "$PYTHON" ]; then',
+    '  if command -v python3 >/dev/null 2>&1; then',
+    '    PYTHON="python3"',
+    "  else",
+    '    PYTHON="python"',
+    "  fi",
+    "fi",
+    'export NEXO_HOME',
+    'export NEXO_CODE="$NEXO_HOME"',
+    'exec "$PYTHON" "$NEXO_HOME/cli.py" "$@"',
+    "",
+  ].join("\n");
+  const runtimeCliPath = path.join(NEXO_HOME, "bin", "nexo");
+  fs.writeFileSync(runtimeCliPath, runtimeCli);
+  fs.chmodSync(runtimeCliPath, 0o755);
+
   // Core packages (directories with __init__.py)
-  ["db", "cognitive"].forEach(pkg => {
+  ["db", "cognitive", "doctor"].forEach(pkg => {
     const pkgSrc = path.join(srcDir, pkg);
     if (fs.existsSync(pkgSrc)) {
       copyDirRecursive(pkgSrc, path.join(NEXO_HOME, pkg));
@@ -1349,6 +1504,12 @@ async function main() {
     });
   }
 
+  // Core skills are shipped separately from personal skills.
+  if (fs.existsSync(skillsSrcDir)) {
+    copyDirRecursive(skillsSrcDir, path.join(NEXO_HOME, "skills-core"));
+    log("  Core skills installed.");
+  }
+
   // Dashboard (recursive — includes static/, templates/)
   const dashSrcDir = path.join(srcDir, "dashboard");
   if (fs.existsSync(dashSrcDir)) {
@@ -1370,6 +1531,19 @@ async function main() {
     log("  Crons installed.");
   }
 
+  // Templates directory (scripts + skills scaffolds)
+  const templatesDest = path.join(NEXO_HOME, "templates");
+  fs.mkdirSync(templatesDest, { recursive: true });
+  if (fs.existsSync(templateDir)) {
+    ["script-template.py", "nexo_helper.py", "skill-template.md", "skill-script-template.py"].forEach(f => {
+      const src = path.join(templateDir, f);
+      if (fs.existsSync(src)) {
+        fs.copyFileSync(src, path.join(templatesDest, f));
+      }
+    });
+    log("  Script and skill templates installed.");
+  }
+
   // Hooks directory
   const hooksSrcDir = path.join(srcDir, "hooks");
   if (fs.existsSync(hooksSrcDir)) {
@@ -1862,12 +2036,25 @@ ${doScan ? `- Stack: ${Object.keys(profileData.code.languages || {}).slice(0, 5)
   // Step 7: Create schedule.json (only on fresh install) and install ALL 13 processes
   log("Setting up automated processes...");
   const schedule = loadOrCreateSchedule(NEXO_HOME);
-  installAllProcesses(platform, python, NEXO_HOME, schedule, LAUNCH_AGENTS);
+  const enabledOptionals = { dashboard: doDashboard, orchestrator: doOrchestrator };
+  if (isEphemeralInstall(NEXO_HOME)) {
+    log("Ephemeral HOME/NEXO_HOME detected — skipping LaunchAgents installation.");
+  } else {
+    installAllProcesses(platform, python, NEXO_HOME, schedule, LAUNCH_AGENTS, enabledOptionals);
+  }
+
+  // Persist optional process preferences for auto-update
+  try {
+    const configDir = path.join(NEXO_HOME, "config");
+    fs.mkdirSync(configDir, { recursive: true });
+    const optFile = path.join(configDir, "optionals.json");
+    fs.writeFileSync(optFile, JSON.stringify(enabledOptionals, null, 2));
+  } catch {}
 
   // Note: prevent-sleep and tcc-approve are now part of ALL_PROCESSES
   // and installed by installAllProcesses() above. No separate caffeinate block needed.
 
-  // Step 8: Create shell alias so user can just type the operator's name
+  // Step 8: Create shell alias and add runtime CLI to PATH
   log("Creating shell alias...");
   const aliasName = operatorName.toLowerCase();
   const savedCliPath = (() => {
@@ -1877,6 +2064,8 @@ ${doScan ? `- Stack: ${Object.keys(profileData.code.languages || {}).slice(0, 5)
   const claudeBin = savedCliPath || run("which claude") || "claude";
   const aliasLine = `alias ${aliasName}='${claudeBin} --dangerously-skip-permissions "."'`;
   const aliasComment = `# ${operatorName} — start Claude Code with ${operatorName} speaking first`;
+  const nexoPathLine = `export PATH="${path.join(NEXO_HOME, "bin")}:$PATH"`;
+  const nexoPathComment = "# NEXO runtime CLI";
 
   // Detect shell and add alias
   const userShell = process.env.SHELL || "/bin/bash";
@@ -1899,6 +2088,14 @@ ${doScan ? `- Stack: ${Object.keys(profileData.code.languages || {}).slice(0, 5)
       rcContent = fs.readFileSync(rcFile, "utf8");
     }
 
+    if (!rcContent.includes(nexoPathLine)) {
+      fs.appendFileSync(rcFile, `\n${nexoPathComment}\n${nexoPathLine}\n`);
+      log(`Added NEXO runtime CLI to ${path.basename(rcFile)}`);
+      rcContent += `\n${nexoPathComment}\n${nexoPathLine}\n`;
+    } else {
+      log(`Runtime CLI already present in ${path.basename(rcFile)}`);
+    }
+
     if (!rcContent.includes(`alias ${aliasName}=`)) {
       fs.appendFileSync(rcFile, `\n${aliasComment}\n${aliasLine}\n`);
       log(`Added '${aliasName}' alias to ${path.basename(rcFile)}`);
@@ -1906,7 +2103,7 @@ ${doScan ? `- Stack: ${Object.keys(profileData.code.languages || {}).slice(0, 5)
       log(`Alias '${aliasName}' already exists in ${path.basename(rcFile)}`);
     }
   }
-  log(`After setup, open a new terminal and type: ${aliasName}`);
+  log(`After setup, open a new terminal and type: ${aliasName} or nexo`);
   console.log("");
 
   // Step 9: Generate CLAUDE.md template

package/bin/nexo.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * nexo — Runtime operational CLI for NEXO.
+ *
+ * Thin Node launcher that resolves NEXO_HOME, finds Python,
+ * and delegates to src/cli.py (repo mode) or NEXO_HOME/cli.py (installed mode).
+ *
+ * Business logic lives in Python, not here.
+ */
+const { spawnSync } = require("child_process");
+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 findPython() {
+  const candidates = [
+    path.join(NEXO_HOME, ".venv", "bin", "python3"),
+    path.join(NEXO_HOME, ".venv", "bin", "python"),
+    "python3",
+    "python",
+  ];
+  for (const c of candidates) {
+    if (c.includes("/") ? fs.existsSync(c) : true) return c;
+  }
+  return "python3";
+}
+
+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;
+}
+
+const python = findPython();
+const cliPy = findCliPy();
+
+if (!fs.existsSync(cliPy)) {
+  console.error(`NEXO CLI not found at ${cliPy}`);
+  console.error("Run 'nexo-brain' first to complete installation.");
+  process.exit(1);
+}
+
+const result = spawnSync(python, [cliPy, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: {
+    ...process.env,
+    NEXO_HOME,
+    NEXO_CODE: path.join(__dirname, "..", "src"),
+  },
+});
+
+process.exit(result.status ?? 1);

package/community/skills/.gitkeep

@@ -0,0 +1 @@
+

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "nexo-brain",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO — Cognitive co-operator for Claude Code. Memory, emotional intelligence, overnight learning (Deep Sleep), cron management, trust scoring, and adaptive calibration.",
   "bin": {
-    "nexo-brain": "./bin/nexo-brain.js"
+    "nexo-brain": "./bin/nexo-brain.js",
+    "nexo": "./bin/nexo.js"
   },
   "keywords": [
     "claude-code",
@@ -54,8 +55,10 @@
   },
   "files": [
     "bin/nexo-brain.js",
+    "bin/nexo.js",
     "bin/postinstall.js",
     "src/",
+    "community/",
     "!src/**/__pycache__",
     "!src/**/*.pyc",
     "!src/**/*.pyo",