nexo-brain 2.6.13 → 2.6.15

package/src/evolution_cycle.py

@@ -275,19 +275,19 @@ def build_evolution_prompt(week_data: dict, objective: dict) -> str:
     if mode == "review":
         mode_desc = "review-only, nothing executes automatically"
         safe_zones = "~/.nexo/scripts/, ~/.nexo/plugins/, ~/.nexo/brain/"
-        immutable_files = "db.py, server.py, plugin_loader.py, storage_router.py, cognitive.py, knowledge_graph.py, tools_*.py, nexo-watchdog.sh, evolution_cycle.py, CLAUDE.md"
+        immutable_files = "db.py, server.py, plugin_loader.py, storage_router.py, cognitive.py, knowledge_graph.py, tools_*.py, nexo-watchdog.sh, evolution_cycle.py, CLAUDE.md, AGENTS.md"
     elif mode == "managed":
         mode_desc = f"owner-managed, max {max_auto} auto-applied changes with rollback and followups"
         safe_zones = "~/.nexo/scripts/, ~/.nexo/plugins/, ~/.nexo/brain/, NEXO_CODE/src, repo bin/docs/templates/tests"
-        immutable_files = "db.py, server.py, plugin_loader.py, storage_router.py, nexo-watchdog.sh, evolution_cycle.py, CLAUDE.md, personality.md, user-profile.md"
+        immutable_files = "db.py, server.py, plugin_loader.py, storage_router.py, nexo-watchdog.sh, evolution_cycle.py, CLAUDE.md, AGENTS.md, personality.md, user-profile.md"
     elif mode == "public_core":
         mode_desc = "public core contribution via isolated checkout and Draft PR"
         safe_zones = "isolated public repo checkout only"
-        immutable_files = "personal runtime, ~/.nexo/**, local DBs/logs, CLAUDE.md, user-profile.md"
+        immutable_files = "personal runtime, ~/.nexo/**, local DBs/logs, CLAUDE.md, AGENTS.md, user-profile.md"
     else:
         mode_desc = f"public auto, max {max_auto} auto-applied changes in personal safe zones"
         safe_zones = "~/.nexo/scripts/, ~/.nexo/plugins/"
-        immutable_files = "db.py, server.py, plugin_loader.py, storage_router.py, cognitive.py, knowledge_graph.py, tools_*.py, nexo-watchdog.sh, evolution_cycle.py, CLAUDE.md"
+        immutable_files = "db.py, server.py, plugin_loader.py, storage_router.py, cognitive.py, knowledge_graph.py, tools_*.py, nexo-watchdog.sh, evolution_cycle.py, CLAUDE.md, AGENTS.md"
 
     prompt = f"""You are NEXO Evolution — the weekly self-improvement cycle.
 

package/src/hooks/session-start.sh

@@ -173,6 +173,22 @@ if os.path.exists(audit_file):
     except Exception:
         pass
 
+# Evolution status
+evolution_file = os.path.join(nexo_home, 'brain', 'evolution-objective.json')
+if os.path.exists(evolution_file):
+    try:
+        evo = json.load(open(evolution_file))
+        lines.append('## Evolution')
+        lines.append(f\"Enabled: {bool(evo.get('evolution_enabled', True))}\")
+        lines.append(f\"Mode: {evo.get('evolution_mode', 'auto')}\")
+        lines.append(f\"Last evolution: {evo.get('last_evolution', 'never')}\")
+        lines.append(f\"Total evolutions: {evo.get('total_evolutions', 0)}\")
+        if evo.get('disabled_reason'):
+            lines.append(f\"Disabled reason: {evo.get('disabled_reason')}\")
+        lines.append('')
+    except Exception:
+        pass
+
 print('\n'.join(lines))
 " > "$BRIEFING_FILE" 2>/dev/null
 

package/src/scripts/deep-sleep/collect.py

@@ -4,7 +4,8 @@ from __future__ import annotations
 Deep Sleep v2 -- Phase 1: Collect all context for overnight analysis.
 
 Gathers transcripts, DB data, logs, and discovered files into a single
-plain-text context file that subsequent phases read via Claude's Read tool.
+plain-text context file that subsequent phases read via the configured
+automation backend.
 
 Environment variables:
   NEXO_HOME  -- root of the NEXO installation (default: ~/.nexo)
@@ -52,22 +53,43 @@ def _redact_sensitive(text: str) -> str:
     return _SENSITIVE_PATTERNS.sub('[REDACTED]', text)
 
 
-# ── Transcript collection (kept from collect_transcripts.py) ──────────────
+# ── Transcript collection (Claude Code + Codex) ────────────────────────────
 
 
-def find_session_dirs() -> list[Path]:
-    """Find all Claude Code project directories that contain .jsonl files."""
+def _session_identifier(client: str, session_file: str) -> str:
+    return f"{client}:{session_file}"
+
+
+def find_claude_session_files() -> list[Path]:
+    """Find Claude Code session JSONL files under ~/.claude/projects."""
     claude_dir = Path.home() / ".claude" / "projects"
     if not claude_dir.exists():
         return []
-    dirs = set()
-    for jsonl in claude_dir.rglob("*.jsonl"):
-        dirs.add(jsonl.parent)
-    return list(dirs)
+    return sorted(claude_dir.rglob("*.jsonl"))
+
+
+def find_codex_session_files() -> list[Path]:
+    """Find Codex session JSONL files under ~/.codex/sessions and archived_sessions."""
+    roots = [
+        Path.home() / ".codex" / "sessions",
+        Path.home() / ".codex" / "archived_sessions",
+    ]
+    files: list[Path] = []
+    seen: set[str] = set()
+    for root in roots:
+        if not root.exists():
+            continue
+        for jsonl in sorted(root.rglob("*.jsonl")):
+            key = jsonl.name
+            if key in seen:
+                continue
+            seen.add(key)
+            files.append(jsonl)
+    return files
 
 
-def extract_session(jsonl_path: Path) -> dict | None:
-    """Extract clean transcript from a session JSONL file."""
+def extract_claude_session(jsonl_path: Path) -> dict | None:
+    """Extract clean transcript from a Claude Code JSONL session."""
     messages = []
     tool_uses = []
     user_msg_count = 0
@@ -136,13 +158,99 @@ def extract_session(jsonl_path: Path) -> dict | None:
         return None
 
     return {
-        "session_file": jsonl_path.name,
+        "client": "claude_code",
+        "session_file": _session_identifier("claude_code", jsonl_path.name),
+        "display_name": jsonl_path.name,
+        "session_path": str(jsonl_path),
+        "message_count": len(messages),
+        "user_message_count": user_msg_count,
+        "tool_use_count": len(tool_uses),
+        "messages": messages,
+        "tool_uses": tool_uses,
+        "source": "claude_projects",
+    }
+
+
+def extract_codex_session(jsonl_path: Path) -> dict | None:
+    """Extract clean transcript from a Codex JSONL session."""
+    messages = []
+    tool_uses = []
+    user_msg_count = 0
+    session_meta: dict = {}
+
+    try:
+        with open(jsonl_path, "r") as f:
+            for line_no, line in enumerate(f, 1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    d = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                item_type = d.get("type")
+                payload = d.get("payload", {})
+
+                if item_type == "session_meta" and isinstance(payload, dict):
+                    session_meta = payload
+                    continue
+
+                if item_type == "event_msg" and isinstance(payload, dict) and payload.get("type") == "user_message":
+                    content = str(payload.get("message", "") or "").strip()
+                    if not content or content.startswith("<environment_context>"):
+                        continue
+                    messages.append({
+                        "role": "user",
+                        "index": line_no,
+                        "text": _redact_sensitive(content[:5000]),
+                    })
+                    user_msg_count += 1
+                    continue
+
+                if item_type == "response_item" and isinstance(payload, dict):
+                    response_type = payload.get("type")
+                    role = payload.get("role")
+                    if response_type == "message" and role == "assistant":
+                        text_parts = []
+                        for block in payload.get("content", []) or []:
+                            if isinstance(block, dict) and block.get("type") == "output_text":
+                                text_parts.append(str(block.get("text", "")))
+                        combined = "\n".join(part for part in text_parts if part).strip()
+                        if combined:
+                            messages.append({
+                                "role": "assistant",
+                                "index": line_no,
+                                "text": _redact_sensitive(combined[:5000]),
+                            })
+                    elif response_type == "function_call":
+                        tool_uses.append({
+                            "tool": payload.get("name", ""),
+                            "input_keys": [],
+                            "file": _redact_sensitive(str(payload.get("arguments", ""))[:100]),
+                        })
+
+    except Exception as e:
+        print(f"  [collect] Error reading {jsonl_path}: {e}", file=sys.stderr)
+        return None
+
+    if user_msg_count < MIN_USER_MESSAGES:
+        return None
+
+    return {
+        "client": "codex",
+        "session_file": _session_identifier("codex", jsonl_path.name),
+        "display_name": jsonl_path.name,
         "session_path": str(jsonl_path),
         "message_count": len(messages),
         "user_message_count": user_msg_count,
         "tool_use_count": len(tool_uses),
         "messages": messages,
-        "tool_uses": tool_uses
+        "tool_uses": tool_uses,
+        "source": session_meta.get("source", "codex"),
+        "cwd": session_meta.get("cwd", ""),
+        "originator": session_meta.get("originator", ""),
+        "session_uid": session_meta.get("id", ""),
     }
 
 
@@ -156,17 +264,22 @@ def collect_transcripts_since(since_iso: str, until_iso: str = "") -> list[dict]
     until_dt = datetime.fromisoformat(until_iso) if until_iso else datetime.now()
 
     sessions = []
-    for sdir in find_session_dirs():
-        for f in sdir.glob("*.jsonl"):
-            try:
-                mtime = datetime.fromtimestamp(f.stat().st_mtime)
-            except OSError:
-                continue
-            if since_dt < mtime <= until_dt:
-                session = extract_session(f)
-                if session:
-                    session["modified"] = mtime.isoformat()
-                    sessions.append(session)
+    transcript_files: list[tuple[str, Path]] = [
+        ("claude_code", path) for path in find_claude_session_files()
+    ] + [
+        ("codex", path) for path in find_codex_session_files()
+    ]
+    for client, session_file in transcript_files:
+        try:
+            mtime = datetime.fromtimestamp(session_file.stat().st_mtime)
+        except OSError:
+            continue
+        if not (since_dt < mtime <= until_dt):
+            continue
+        session = extract_codex_session(session_file) if client == "codex" else extract_claude_session(session_file)
+        if session:
+            session["modified"] = mtime.isoformat()
+            sessions.append(session)
     sessions.sort(key=lambda s: s["modified"])
     return sessions
 
@@ -353,6 +466,9 @@ def format_transcripts(sessions: list[dict]) -> str:
     for i, session in enumerate(sessions):
         lines.append(f"\n{'─' * 60}")
         lines.append(f"SESSION {i + 1}: {session['session_file']}")
+        lines.append(f"Client: {session.get('client', 'unknown')}")
+        if session.get("source"):
+            lines.append(f"Source: {session['source']}")
         lines.append(f"Modified: {session['modified']}")
         lines.append(f"Messages: {session['message_count']}, Tool uses: {session['tool_use_count']}")
         lines.append(f"{'─' * 60}")
@@ -460,18 +576,27 @@ def main():
 
     # Individual session files
     session_files_written = []
+    session_txt_map = {}
     total_size = len(shared_text.encode("utf-8"))
     for i, session in enumerate(sessions):
-        sid_short = session["session_file"].replace(".jsonl", "")[:20]
+        raw_id = session["session_file"].replace(".jsonl", "").replace(":", "-")
+        sid_short = raw_id[:30]
         filename = f"session-{i+1:02d}-{sid_short}.txt"
         session_path = date_dir / filename
 
         lines = [
             f"Session: {session['session_file']}",
+            f"Display name: {session.get('display_name', session['session_file'])}",
+            f"Client: {session.get('client', 'unknown')}",
+            f"Source: {session.get('source', 'unknown')}",
             f"Modified: {session['modified']}",
             f"Messages: {session['message_count']}, Tool uses: {session['tool_use_count']}",
             f"{'─' * 60}",
         ]
+        if session.get("cwd"):
+            lines.insert(4, f"CWD: {session['cwd']}")
+        if session.get("originator"):
+            lines.insert(4, f"Originator: {session['originator']}")
         for msg in session["messages"]:
             role = "USER" if msg["role"] == "user" else "AGENT"
             idx = msg.get("index", "?")
@@ -487,6 +612,7 @@ def main():
         session_text = "\n".join(lines)
         session_path.write_text(session_text, encoding="utf-8")
         session_files_written.append(filename)
+        session_txt_map[session["session_file"]] = filename
         total_size += len(session_text.encode("utf-8"))
         print(f"  {filename}: {len(session_text) / 1024:.0f} KB")
 
@@ -508,6 +634,18 @@ def main():
         "sessions_found": len(sessions),
         "session_files": [s["session_file"] for s in sessions],
         "session_txt_files": session_files_written,
+        "session_txt_map": session_txt_map,
+        "session_manifest": [
+            {
+                "session_id": s["session_file"],
+                "display_name": s.get("display_name", s["session_file"]),
+                "client": s.get("client", "unknown"),
+                "source": s.get("source", ""),
+                "session_path": s.get("session_path", ""),
+                "session_txt_file": session_txt_map.get(s["session_file"], ""),
+            }
+            for s in sessions
+        ],
         "total_messages": sum(s["message_count"] for s in sessions),
         "total_tool_uses": sum(s["tool_use_count"] for s in sessions),
         "followups_active": len(followups),

package/src/scripts/deep-sleep/extract.py

@@ -66,23 +66,43 @@ def extract_json_from_response(text: str) -> dict | None:
     return None
 
 
-def find_session_file(session_id: str, date_dir: Path) -> Path | None:
+def _safe_session_slug(session_id: str) -> str:
+    return (
+        session_id
+        .replace(".jsonl", "")
+        .replace(":", "-")
+        .replace("/", "-")
+    )
+
+
+def find_session_file(session_id: str, date_dir: Path, session_txt_map: dict[str, str] | None = None) -> Path | None:
     """Find the individual .txt file for a session."""
+    if session_txt_map:
+        mapped = session_txt_map.get(session_id)
+        if mapped:
+            candidate = date_dir / mapped
+            if candidate.exists():
+                return candidate
     if date_dir and date_dir.exists():
-        sid_short = session_id.replace(".jsonl", "")[:20]
+        sid_short = _safe_session_slug(session_id)[:20]
         for f in sorted(date_dir.glob("session-*.txt")):
             if sid_short in f.name:
                 return f
     return None
 
 
-def analyze_session(session_id: str, date_dir: Path, shared_context_file: Path | None) -> dict | None:
+def analyze_session(
+    session_id: str,
+    date_dir: Path,
+    shared_context_file: Path | None,
+    session_txt_map: dict[str, str] | None = None,
+) -> dict | None:
     """Send a session to the automation backend for extraction analysis.
 
     The backend reads the small per-session file + shared context file.
     Prompt is short — the heavy lifting is in the Read tool calls.
     """
-    session_file = find_session_file(session_id, date_dir)
+    session_file = find_session_file(session_id, date_dir, session_txt_map=session_txt_map)
     if not session_file:
         print(f"    No session file found for {session_id}", file=sys.stderr)
         return None
@@ -181,10 +201,12 @@ def main():
         with open(meta_file) as f:
             meta = json.load(f)
         session_files = meta.get("session_files", [])
+        session_txt_map = meta.get("session_txt_map", {})
     else:
         # Fallback: parse context file for session IDs
         print("[extract] No meta file found, scanning context for sessions...")
         session_files = []
+        session_txt_map = {}
         if context_file.exists():
             for line in context_file.read_text().splitlines():
                 if line.startswith("SESSION ") and ":" in line:
@@ -224,7 +246,7 @@ def main():
     MAX_RETRIES = 3
 
     for i, session_id in enumerate(session_files):
-        sid_safe = session_id.replace(".jsonl", "")[:30]
+        sid_safe = _safe_session_slug(session_id)[:40]
         checkpoint_file = checkpoint_dir / f"{sid_safe}.json"
 
         # Resume: skip already-processed sessions
@@ -246,7 +268,12 @@ def main():
         # Retry loop
         result = None
         for attempt in range(1, MAX_RETRIES + 1):
-            result = analyze_session(session_id, date_dir, shared_context_file)
+            result = analyze_session(
+                session_id,
+                date_dir,
+                shared_context_file,
+                session_txt_map=session_txt_map,
+            )
             if result:
                 break
             if attempt < MAX_RETRIES:

package/src/scripts/nexo-daily-self-audit.py

@@ -261,7 +261,7 @@ def check_watchdog_registry():
     if not HASH_REGISTRY.exists():
         return
     text = HASH_REGISTRY.read_text(errors="ignore")
-    forbidden = ["CLAUDE.md", "server.py", "plugin_loader.py"]
+    forbidden = ["CLAUDE.md", "AGENTS.md", "server.py", "plugin_loader.py"]
     bad = [name for name in forbidden if name in text]
     if bad:
         finding("ERROR", "watchdog", f"mutable files still protected: {', '.join(bad)}")

package/src/scripts/nexo-deep-sleep.sh

@@ -58,7 +58,7 @@ if [ "$SESSIONS" -eq 0 ]; then
     exit 0
 fi
 
-# Phase 2: Extract findings per session (Claude Opus)
+# Phase 2: Extract findings per session (configured automation backend)
 log "Phase 2: Extracting findings from $SESSIONS sessions..."
 python3 "$SCRIPT_DIR/deep-sleep/extract.py" "$RUN_ID" >> "$LOG_DIR/deep-sleep.log" 2>&1
 
@@ -67,7 +67,7 @@ if [ ! -f "$DEEP_SLEEP_DIR/$RUN_ID-extractions.json" ]; then
     exit 1
 fi
 
-# Phase 3: Cross-session synthesis (Claude Opus, one call)
+# Phase 3: Cross-session synthesis (configured automation backend, one call)
 log "Phase 3: Synthesizing cross-session findings..."
 python3 "$SCRIPT_DIR/deep-sleep/synthesize.py" "$RUN_ID" >> "$LOG_DIR/deep-sleep.log" 2>&1
 

package/src/scripts/nexo-evolution-run.py

@@ -3,8 +3,8 @@
 NEXO Evolution — Standalone weekly runner with real execution.
 Cron: 0 3 * * 0  (Sundays 3:00 AM)
 
-Runs independently of Cortex. Calls Opus API directly to analyze
-the past week and generate improvement proposals.
+Runs independently of Cortex. Calls the configured NEXO automation backend
+to analyze the past week and generate improvement proposals.
 
 AUTO proposals are executed: snapshot → apply → validate → commit/rollback.
 PROPOSE proposals are logged for the user's review.
@@ -45,6 +45,7 @@ GLOBAL_IMMUTABLE_FILES = {
     "nexo-watchdog.sh",
     "cortex-wrapper.py",
     "CLAUDE.md",
+    "AGENTS.md",
     "personality.md",
     "user-profile.md",
     "evolution_cycle.py",
@@ -364,7 +365,9 @@ def _sanitize_public_diff(worktree_dir: Path, changed_files: list[str]) -> tuple
         "/Users/",
         "/home/",
         "CLAUDE.md",
+        "AGENTS.md",
         ".nexo/",
+        ".codex/",
     ]
     for marker in private_markers:
         if marker and marker in diff_text:

package/src/scripts/nexo-watchdog.sh

@@ -1134,7 +1134,7 @@ STEPS:
 ${PROPAGATE_BLOCK}
 
 CONSTRAINTS:
-- Do NOT modify CLAUDE.md or any protected file
+- Do NOT modify CLAUDE.md, AGENTS.md, or any protected file
 - Do NOT start interactive conversations
 - Keep it under 5 minutes
 - Log what you did to $NEXO_HOME/logs/watchdog-repair-result.log

package/src/server.py

@@ -140,6 +140,9 @@ def _server_init():
                     print(f"[NEXO] {result['npm_notice']}", file=sys.stderr)
                 if result.get("claude_md_update"):
                     print(f"[NEXO] {result['claude_md_update']}", file=sys.stderr)
+                for message in result.get("client_bootstrap_updates", []):
+                    if message != result.get("claude_md_update"):
+                        print(f"[NEXO] {message}", file=sys.stderr)
                 for m in result.get("migrations", []):
                     if m["status"] == "failed":
                         print(f"[NEXO] Migration {m['file']} FAILED: {m['message']}", file=sys.stderr)
@@ -184,6 +187,9 @@ mcp = FastMCP(
         "- **Diary:** When user signals end of session (any language, any style — 'bye', 'done', 'cierro', etc.), "
         "write `nexo_session_diary_write(...)` with self_critique BEFORE responding. "
         "Detect intent, not keywords. If session closes without diary, auto_close handles it.\n"
+        "- **Evolution:** NEXO has a weekly self-improvement cycle. If the user asks how NEXO evolves, inspect "
+        "`nexo_evolution_status` / `nexo_evolution_history` instead of assuming this subsystem does not exist. "
+        "Use propose/approve/reject only when the user explicitly wants to work on NEXO evolution.\n"
         "- **Cortex:** `nexo_cortex_check` before budget/campaign/architecture changes\n"
         "- **Dissonance:** user contradicts memory→`nexo_cognitive_dissonance`. Frustrated→force=True\n"
         "- **Trust:** <40=paranoid verify twice, >80=fluid. Check: `nexo_cognitive_trust`"
@@ -202,8 +208,9 @@ def nexo_startup(task: str = "Startup", claude_session_id: str = "") -> str:
 
     Args:
         task: Initial task description.
-        claude_session_id: The Claude Code session UUID (from session-briefing or hook).
-                          Pass this to enable automatic inter-terminal inbox detection.
+        claude_session_id: External client session token. Claude Code passes its UUID via hooks;
+                          other clients may pass a synthetic durable token when useful.
+                          Pass this to enable automatic inter-terminal inbox detection when available.
     """
     return handle_startup(task, claude_session_id=claude_session_id)
 

package/src/tools_sessions.py

@@ -69,8 +69,9 @@ def handle_startup(task: str = "Startup", claude_session_id: str = "") -> str:
 
     Args:
         task: Initial task description
-        claude_session_id: UUID from Claude Code (passed via SessionStart hook file).
-                          Enables automatic inbox detection via PostToolUse hook.
+        claude_session_id: External client session token. Claude Code passes its UUID via hooks;
+                          other clients may pass a synthetic durable ID when useful.
+                          Enables automatic inbox detection when hook-backed clients provide one.
     """
     sid = _generate_sid()
     cleaned = clean_stale_sessions()

package/templates/CLAUDE.md.template

@@ -1,15 +1,21 @@
-<!-- nexo-claude-md-version: 1.0.0 -->
+<!-- nexo-claude-md-version: 2.0.0 -->
+******CORE******
+<!-- nexo:core:start -->
 # {{NAME}} — Cognitive Co-Operator
 
 I am {{NAME}}, a cognitive co-operator powered by NEXO Brain. Not an assistant — an operational partner.
-Tool-coupled behavioral rules (heartbeat, guard, trust, memory, diary) live in the MCP server instructions field and are injected automatically. This file is the bootstrap: identity, profile, format, and autonomy.
+Tool-coupled behavioral rules (heartbeat, guard, trust, memory, diary) live in the MCP server instructions field and are injected automatically. This file is the stable bootstrap for Claude Code.
+
+Keep durable NEXO product rules in `CORE`. Put operator-specific instructions only in `USER`.
+NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
 
 <!-- nexo:start:startup -->
-## Startup (4 steps)
-1. `nexo_startup` → SID
+## Startup (5 steps)
+1. `nexo_startup` -> SID
 2. In parallel: `nexo_session_diary_read(last_day=true)` + `nexo_reminders(filter="due")` + `nexo_reminders(filter="followups")` + read `{{NEXO_HOME}}/brain/calibration.json`
-3. Execute overdue followups in background. Adopt `mental_state` from last diary (don't start cold).
+3. Execute overdue followups in background. Adopt `mental_state` from last diary (do not start cold).
 4. Read user's name and language from `{{NEXO_HOME}}/brain/calibration.json` — ALWAYS communicate in that language.
+5. Be explicitly aware of NEXO core systems: shared brain, Deep Sleep, weekly Evolution, Skills, Watchdog, and followup machinery.
 
 **Presentation:** {{NAME}} speaks first. Conversational greeting adapted to time of day. Tell what you HAVE DONE, not list pending items. Menu only if the user asks.
 <!-- nexo:end:startup -->
@@ -20,7 +26,7 @@ Tool-coupled behavioral rules (heartbeat, guard, trust, memory, diary) live in t
 - **Profile:** `{{NEXO_HOME}}/brain/profile.json` (deep scan results from onboarding)
 
 ### First Session Onboarding (only if profile.json lacks `role` or `technical_level`)
-Ask TWO questions: (1) "What do you do?" → save to profile.json + `nexo_preference_set("role", answer)`. (2) "Technical level? Beginner / Intermediate / Advanced" → save + `nexo_preference_set("technical_level", answer)`. Then: "Got it. From now on I learn by observing." Never ask onboarding questions again.
+Ask TWO questions: (1) "What do you do?" -> save to profile.json + `nexo_preference_set("role", answer)`. (2) "Technical level? Beginner / Intermediate / Advanced" -> save + `nexo_preference_set("technical_level", answer)`. Then: "Got it. From now on I learn by observing." Never ask onboarding questions again.
 
 ### Personality Calibration (from calibration.json)
 - **autonomy:** conservative (ask first) | balanced (default) | full (act first)
@@ -30,6 +36,15 @@ Ask TWO questions: (1) "What do you do?" → save to profile.json + `nexo_prefer
 - **error_handling:** brief-fix (default) | explain-and-learn
 <!-- nexo:end:profile -->
 
+<!-- nexo:start:systems -->
+## Core Systems
+- **Shared Brain:** one memory/runtime for Claude Code, Codex, and Claude Desktop.
+- **Deep Sleep:** overnight multi-phase analysis that extracts findings from recent sessions and memory state.
+- **Evolution:** NEXO has a weekly self-improvement cycle. If the user asks how NEXO improves itself, inspect `nexo_evolution_status`, `nexo_evolution_history`, and `nexo_evolution_propose` instead of assuming this system does not exist.
+- **Skills:** reusable procedures plus `nexo_skill_evolution_candidates` for text->script and iterative skill improvement.
+- **Watchdog / Immune / Followups:** reliability, quarantine, reminders, and self-healing are native parts of NEXO, not add-ons.
+<!-- nexo:end:systems -->
+
 <!-- nexo:start:autonomy -->
 ## Autonomy
 Install tools, create scripts, run commands — whatever it takes. NEVER push manual steps to the user. NEVER say "I can't".
@@ -51,13 +66,22 @@ Credentials: (1) `nexo_credential_get`, (2) `{{NEXO_HOME}}/*.txt/*.json`.
 
 <!-- nexo:start:hooks -->
 ## Hooks
-- **SessionStart** → generates briefing at `{{NEXO_HOME}}/coordination/session-briefing.txt`. Read during startup.
-- **Stop** → injects post-mortem instructions. Write diary, buffer entry, followups, proactive seeds.
-- **PostToolUse** → logs mutations to `session_buffer.jsonl` silently.
-- **PreCompact** → saves checkpoint. Write diary IMMEDIATELY when you see this, then read checkpoint after compaction.
+- **SessionStart** -> generates briefing at `{{NEXO_HOME}}/coordination/session-briefing.txt`. Read during startup.
+- **Stop** -> injects post-mortem instructions. Write diary, buffer entry, followups, proactive seeds.
+- **PostToolUse** -> logs mutations to `session_buffer.jsonl` silently.
+- **PreCompact** -> saves checkpoint. Write diary IMMEDIATELY when you see this, then read checkpoint after compaction.
 <!-- nexo:end:hooks -->
 
 <!-- nexo:start:menu -->
 ## Menu
 **On demand only.** `nexo_menu` when user asks. NEVER show at startup.
 <!-- nexo:end:menu -->
+<!-- nexo:core:end -->
+
+******USER******
+<!-- nexo:user:start -->
+# Personal Instructions
+Add operator-specific instructions below this line.
+NEXO updates preserve this USER block exactly as written.
+
+<!-- nexo:user:end -->

package/templates/CODEX.AGENTS.md.template

@@ -0,0 +1,45 @@
+<!-- nexo-codex-agents-version: 1.0.0 -->
+******CORE******
+<!-- nexo:core:start -->
+# {{NAME}} — NEXO Shared Brain for Codex
+
+You are {{NAME}}, a cognitive co-operator powered by NEXO Brain, running inside Codex.
+You are not plain Codex with an MCP attached. NEXO is the active shared memory/runtime layer for this session.
+Tool-coupled behavioral rules (heartbeat, guard, trust, memory, diary) live in the MCP server instructions field. This file is the persistent Codex bootstrap.
+
+Keep stable NEXO product rules in `CORE`. Put operator-specific instructions only in `USER`.
+NEXO updates may rewrite `CORE`, but they must preserve `USER` verbatim.
+
+## Startup (5 steps)
+1. Call `nexo_startup` once at the beginning of the session.
+2. In parallel: `nexo_session_diary_read(last_day=true)` + `nexo_reminders(filter="due")` + `nexo_reminders(filter="followups")` + read `{{NEXO_HOME}}/brain/calibration.json`.
+3. Adopt the user's language from calibration.json and ALWAYS reply in that language.
+4. Execute overdue followups silently when appropriate.
+5. Maintain explicit awareness of NEXO core systems: shared brain, Deep Sleep, weekly Evolution, Skills, Watchdog, and followup machinery.
+
+## Codex Runtime Notes
+- Codex does not provide Claude Code hooks. Compensate explicitly: startup, heartbeat on every user message, diary on clear end-of-session intent, and memory capture on every correction or durable decision.
+- If a stable session token is useful, you may pass a synthetic `claude_session_id` like `codex-<task>-<date>` to `nexo_startup`; otherwise leave it blank.
+- `nexo chat` must inject this bootstrap explicitly when it launches Codex so the session starts as NEXO even if plain global Codex startup ignores global instructions.
+- `nexo chat` should open the configured client and keep runtime/model alignment with NEXO preferences.
+
+## Core Systems
+- **Shared Brain:** one NEXO runtime shared across Claude Code, Codex, and Claude Desktop.
+- **Deep Sleep:** overnight session + memory analysis. Transcript-aware parity matters even when the user works only in Codex.
+- **Evolution:** NEXO has a weekly self-improvement cycle. If asked how NEXO improves itself, inspect `nexo_evolution_status`, `nexo_evolution_history`, and `nexo_evolution_propose`.
+- **Skills:** reusable procedures plus `nexo_skill_evolution_candidates` for text->script and skill refinement.
+- **Watchdog / Immune / Followups:** reliability, quarantine, reminders, and self-healing are native parts of NEXO.
+
+## Project Atlas
+Search `{{NEXO_HOME}}/brain/project-atlas.json` BEFORE touching any project. Never assume server, port, or code location.
+
+Credentials: (1) `nexo_credential_get`, (2) `{{NEXO_HOME}}/*.txt/*.json`.
+<!-- nexo:core:end -->
+
+******USER******
+<!-- nexo:user:start -->
+# Personal Instructions
+Add operator-specific Codex instructions below this line.
+NEXO updates preserve this USER block exactly as written.
+
+<!-- nexo:user:end -->